项目导览：从使用价值讲到关键设计

这条路线适合第一次系统了解 Iris，也可以帮助准备项目介绍。重点是让每个设计回答一个实际问题；不需要在一次讲解中列完全部包名和可选功能。

1. 先说明为什么需要它

Iris 面向希望在自己的 Python 项目中使用 Agent 的开发者。模型 API 已经能生成文字，但一个可持续使用的助手还需要工具、上下文、人工交互、状态保存和宿主接线。Iris 把这些能力组织成一个本地优先、配置驱动的 Agent Kit。

可以用这句话开始：

用 YAML 声明 Agent，用 Python 控制完整任务，让工作文件和运行状态围绕本地项目组织，并按需求增加工具、记忆和持续任务能力。

随后用快速开始里的文件问答说明实际用法。它先回答“能帮使用者做什么”，再引出实现，而不把介绍停留在框架名词。

本地优先的具体含义是本地配置、workspace、SQLite 和文件材料；模型调用仍可能依赖远端服务。易于集成的依据是 CLI 与 Python 宿主复用同一配置和运行入口，而不是没有依赖或没有集成工作。

2. 用一次请求建立整体关系

沿“读取配置文件并解释启动方式”这个任务讲：

1. YAML 声明能力，Runner 装配组件并接收输入。
2. Runtime 组织上下文，provider 调用模型。
3. 模型选择工具，工具系统执行并返回结果。
4. 运行事实提交到 store，下一步继续，最终返回 RunResult。

对应架构总览。需要讲清的设计选择是完整运行与一次激活分开：宿主不必自己重建取消、等待和恢复流程，runtime 也不需要知道具体数据库。

3. 选择能支撑讨论的设计专题

上下文为什么不能只是不断追加消息

从长文件、多次工具读取与窗口容量开始，解释“持久原文”和“模型本步视图”的区别。再说明工具结果外置、旧观察裁剪、动态快照、工具按需披露与摘要怎样分工。

值得展开的取舍是保留回读能力与控制每次输入量。框架没有把全部材料送给模型，也没有在压力下直接删掉权威历史。上下文工程提供完整流程。

为什么人工等待与故障恢复属于运行系统

用“工具等待确认后继续”解释 Session、Run、activation 和 checkpoint。人工回答不是重新执行整个任务；恢复也不能把结果未知的写操作直接重跑。

重点在职责与状态事实：harness 编排、runtime 推进、store 保持权威，HITL 提供 typed 交互。详见生命周期和人工交互。

为什么工具扩展不只是一张函数表

工具定义需要转成模型可理解的 schema，输入要在边界解析，执行有权限和资源语义，结果还要保存或投影。目录增大后，工具发现负责决定本步提供哪些说明。

这里可以连接 Python/MCP、自定义工具、Hook/Middleware 和子 Agent 的不同职责。详见工具执行、委派与扩展点。

长期工作怎样积累材料

先区分三个目标：Goal 管理跨 Run 推进，Todo 表示当前清单，Memory 保存可跨任务检索的知识。再解释真实经历如何经后台维护形成记忆或项目经验 Skill。

这是机制层面的设计，不等同于“Agent 已被证明持续变强”。若要介绍效果，需要另有任务、评价和对照证据。记忆、Goal、经验修订分别说明边界。

宿主为什么需要实时输出与持久状态两条路径

让界面尽早看到文字，与可靠知道任务已完成，是不同需求。流式增量可以被合并，最终状态必须从已提交事实读取；OTel 则用来解释耗时和失败，不接管恢复。

这能说明 Iris 为不同宿主保留了哪些稳定接口，以及为什么没有将 UI、网络协议和执行状态混在一起。详见流式与观测。

4. 让设计与证据相连

介绍每个专题时，选择一项可查阅依据即可：一段可运行配方、一组针对性测试、一条清楚的调用链或一次真实记录。不要把所有源码路径搬进讲述。

想证明的事情	合适的材料
开发者能怎样使用	入门与对应 Cookbook 的完整示例
某项状态规则确实被实现	公开契约和相应状态转换测试
实际服务集成可运行	说明模型、配置、时间与输出的真实执行记录
某种方案带来效果提升	明确数据集、指标、预算与对照的评测

参考测试指南区分这些证据。当前文档提供机制与使用说明，不替代未开展的性能、稳定性或学习效果评测。

5. 最后说明取舍与可贡献的位置

Iris 选择本地配置和可选服务，降低基本使用的外部设施需求；同时把界面、网络宿主、模型部署和音频设备留给应用。typed 边界使内部职责清楚，也要求扩展实现满足当前协议。保存运行事实便于恢复，但仍需承认外部副作用结果未知的情况。

想参与修改的人可以从源码地图找到具体 owner，再查扩展方式。介绍个人贡献时，应另行说明自己实际负责的内容；项目已有能力本身不能代替个人贡献的证明。