全书阅读地图：从会用到会研究

你不需要先读完全部 Spec，也不需要先背 Agent 术语。本书始终使用同一项任务：

阅读 workspace 中的项目资料，把一份总结写进 outputs/summary.md。

我们先让它运行，再一层层解释是谁调用模型、谁执行 Tool、谁保存 Event、谁阻止越界。读到开发者第五步时，你会沿同一条链进入源码和测试。

六步分别解决什么问题

步骤	读者问题	读完能做到
第一步：先亲手跑一次	“这个项目到底怎么用？”	配置模型，启动 Run，查看 Artifact、状态和 Event
第二步：看懂 Agent 运行	“Model、Tool、Runtime 各干什么？”	画出一次 Run 的循环，解释状态和预算来源
第三步：理解安全边界	“模型为什么不能直接读写文件？”	解释 adapter、Policy、路径边界和原子提交
第四步：拼出系统架构	“这些模块为什么这样分？”	看懂 interface、application、runtime、port 和 adapter
第五步：沿代码继续学习	“从哪个文件开始读，怎么验证？”	顺着调用链找到实现、契约和失败测试
第六步：走向研究与扩展	“今天还有哪些问题没有解决？”	把恢复、隔离、评测和长任务变成研究问题

flowchart LR
    A["运行一个 Run"] --> B["观察 Event 与 Artifact"]
    B --> C["解释 Agent Loop"]
    C --> D["拆开安全边界"]
    D --> E["进入源码与测试"]
    E --> F["提出研究问题"]

第一步：先亲手跑一次

这条学习路线对应 2026-09-08 已收口的 P1：你可以初始化配置、完成有限文件任务，并核对 Event 与 Artifact。中断后自动继续仍属于 P2，当前边界与验收记录见现在实现到了哪里。

从第一次运行：读一份文档开始，先看到输入、输出文件与执行记录。需要查参数、退出码和路径时，再打开完整命令行手册，不用先通读全部参考内容。

随后读配置一次模型服务和运行、检查与读取 Event。此时先把 Run ID、Artifact 和有序 Event 看成“程序给你的收据”，还不用理解全部字段。

第二步：看懂 Agent 运行

依次阅读：

一项 Agent 任务怎样运转：分清 Model、Context、Tool 与 Runtime；
一次文件任务的完整链路：跟完模型—Tool—模型循环；
状态和预算怎样计算：理解 Event 与 Reducer；
逐条读懂一次 Run：把抽象规则落到事件序列；
Event 为什么是事实来源：分清“能够重开查询”和“能够恢复执行”。

第三步：理解安全边界

这部分从四个常见误解出发：

“SDK 对象直接传进 Runtime 更省事” → 模型为什么需要 adapter；
“模型都选择 Tool 了，直接调用就行” → Tool 请求为什么过四道检查；
“拒绝 .. 就不会越界” → 路径怎样留在 workspace；
“写文件只要 write_text” → 为什么不能直接覆盖文件。

最后用失败后先问哪三个问题把 P1 的记录、P2 的恢复和 P3 的授权/ 隔离分开。

第四、五步：从架构进入源码

先读架构总览和一次请求怎样穿过 Runtime，再进入源码阅读路线。源码页不会只列目录：每篇都会给出读代码的顺序、要守住的不变量、最小实验和对应测试。

第六步：把困惑变成研究问题

先读从一次失败，到一个可以检验的研究问题。它沿同一个文件任务区分结果核对、原因验证与执行授权，并说明怎样比较不同恢复策略。这些扩展属于 P2/P3 规划。

Agent 今天能做什么帮助你判断适合 Agent 的任务形状；Agent 仍然难在哪里把长任务、Context、评测、安全、恢复和多 Agent 协作拆成可研究的问题。参考项目只用来解释通用概念，不能证明 BearAgent 已经具备同样能力。

只有半小时，走这条捷径

每章怎样读最有效

先回答开头的具体问题；再自己画一遍流程；然后打开“代码位置”中的第一个文件；最后只运行该章列出的最小测试。能够用自己的话解释“失败时会看到什么”，比记住类名更重要。