A1 · Pi Harness 源码精读与最小 Coding Agent

本模块产出：pi-adapter、最小 Coding Agent Demo、不少于 2 页的对照报告 · 对应总课表：第 5 周

学前自测

1. 你在程序员基础版第 4 周手写过 Agent Loop。现在读别人的实现，你打算先看哪三个东西？

入口（一次 Run 从哪个函数开始）、状态（循环之间靠什么数据结构传递）、失败路径（错误在哪里被捕获、怎么向上传播）。绝大多数人读源码从头往下顺着读，效率极低。带着这三个问题读，一个下午能读透一个 Harness。

2. 什么叫最小核心？一个 Harness 应该把哪些职责交给宿主？

最小核心通常只保留循环、消息状态和事件发射。交给宿主的一般是：模型调用的具体实现、工具的具体实现、权限判定、持久化、UI。判断一个 Harness 好不好，就看它这条线划得清不清楚。划不清的表现是你想换个模型 Provider 却发现要改循环代码。

3. headless 模式和 JSON Event Stream 解决什么问题？

让 Harness 可以被任意宿主程序嵌入，而不绑定某个 UI 或某种语言。事件以结构化 JSON 输出，宿主自己决定怎么渲染、怎么持久化。这是把一个 Agent 从产品变成基础设施的关键一步，A5 的平台化直接依赖这个能力。

4. 为什么源码精读要产出对照报告，而不只是读懂就行？

因为读懂了但说不出差异，在面试里换不来任何东西。对照报告强迫你把 Pi 的设计和自己 Native 版的设计逐项对齐，那些对不上的地方就是你原来没想到的设计维度。这份报告本身就是作品集材料。

学习目标

精读一个最小 Agent Harness 参考实现的包边界与源码，并构建可控的 Coding Agent。

这个模块的价值不在于学会用 Pi，而在于建立读 Agent 框架源码的方法论。学完之后，任何一个新框架你都能在半天内判断它的核心边界在哪、值不值得引入。

课程内容

1. pi-ai Provider 与统一消息边界
2. pi-agent-core 状态、循环和事件流
3. Agent Core 与 Coding Agent 的包边界
4. Tool 注册、调用与结果回注
5. Context Transform 与消息转换
6. streaming、abort 与错误传播
7. read / search / edit / bash 工具
8. Workspace Root、Protected Path 与 Permission Gate
9. headless embedding 与 JSON Event Stream
10. 最小核心和可扩展性的架构取舍
11. 源码阅读方法：入口、状态、不变量、失败路径
12. Native Harness 与 Pi 事件映射

包边界与职责划分

实施任务

• 阅读 Pi packages/ai、packages/agent 与 packages/coding-agent 的关键入口
• 用 Pi Agent Core 接入程序员基础版第 2 到 3 周的 Model Gateway 与 Tool Runtime
• 实现一个只允许在测试 Workspace 内 read / search / edit / bash 的最小 Coding Agent
• 编写 pi-adapter，把 Pi 事件转换为统一 AgentEvent
• 注入模型失败、工具失败、取消和越权写入，验证失败路径

对照报告

必须回答四个问题：

• Pi 的最小核心保留了哪些职责，又把哪些能力交给宿主？
• Pi Event 与课程统一 Event Contract 有哪些一对一或一对多映射？
• Coding Agent 的工具边界在哪，哪些权限必须由平台而非 Prompt 控制？
• Native Harness 与 Pi 在复杂度、事件完整性、取消和扩展性上的差异是什么？

动手挑战

用四十行代码复刻 Pi 的核心循环，然后对比你砍掉了什么。

具体做法：读完源码后，不看代码，凭理解在一个空文件里重写它的主循环，限制在四十行以内。写完再打开原实现逐行对照，列出你漏掉的每一处，并给每一处标注：

1. 这是必要复杂度（比如取消传播、错误分类）还是可选复杂度（比如某个扩展点）？
2. 如果漏掉它，什么场景会出错？

这个练习比通读三遍源码有效得多，因为它逼你区分本质和装饰。列出的必要复杂度清单，就是你评估任何 Harness 的检查表。

Agent OS 里程碑

完成 pi-adapter 和最小 Coding Agent Demo。

验收标准

• 同一 Agent Definition 可通过 Native Harness 与 Pi Adapter 运行
• 两种实现通过同一 Tool Contract、Dataset 和事件快照
• 文件系统越权、危险命令和 Secret 泄漏测试全部通过
• 提交 Pi 源码架构图与不少于 2 页的对照报告

学后自测

1. Pi Event 到统一 AgentEvent 的映射里，哪些是一对多？为什么会出现一对多？

一对多通常出现在语义粒度不同的地方，比如 Pi 的一个消息事件在统一契约里要拆成 turn 开始加 text delta 加 turn 结束。出现一对多说明两套协议的抽象层级不一致，这是 Adapter 复杂度的主要来源，也是评估框架接入成本的关键指标。

2. 你的 Coding Agent 能被诱导写到 Workspace 之外吗？你试了几种方式？

至少要试相对路径穿越、软链接、绝对路径、以及通过 bash 工具间接写入四种。前三种在程序员基础版第 3 周已经防过，第四种是 Coding Agent 特有的：edit 工具防住了，但 bash 里一句重定向就绕过去了。这就是为什么权限必须在 Executor 层统一拦，不能按工具各自实现。

3. 如果让你给团队推荐 Native 自研还是接入 Pi，你的判断依据是什么？

依据应该是具体的：需要多少扩展点、团队有没有人能维护、事件契约的缺口有多大、退出成本多高。给不出依据只凭喜好的推荐，在架构评审上会被打回。这题的答案质量直接反映你是不是真读懂了源码。

本模块作业

1. packages/harness-pi/ 扩展：完整的 pi-adapter 与事件映射
2. 最小 Coding Agent，含四类故障注入测试
3. docs/pi-architecture.md：Pi 源码架构图与包边界分析
4. docs/native-vs-pi.md：不少于 2 页的对照报告，回答上面四个问题
5. 动手挑战的必要复杂度清单

面试考点

这个模块对应面试里的源码理解深度，是区分 Senior 和中级的典型考点。

• 「你读过哪些 Agent 框架的源码？」：这题看似闲聊，实际是深水区入口。答之前先想清楚你要引导到哪个模块。讲 Pi 的包边界划分，然后自然过渡到你的对照报告。
• 「一个 Agent Harness 的最小职责集是什么？」：拿你的必要复杂度清单答。能区分必要复杂度和可选复杂度，是架构判断力的直接证据。
• 「你怎么快速评估一个新框架？」：答入口、状态、失败路径三步法，再加事件契约缺口和退出成本两个量化维度。这个回答能让面试官相信你换个技术栈也能快速上手。
• 「Coding Agent 的安全边界怎么设计？」：注意 bash 工具会绕过 edit 的路径限制这个坑。主动讲这个细节，说明你真动手做过。
• 反问加分：可以反问面试官团队现在用的是自研还是框架，以及退出成本评估过没有。这个反问显得你在平台层思考问题。

复习与延伸

官方文档

• Pi 文档
• Pi RPC 与 JSON Event Mode
• Pi Agent Core 源码
• Pi Coding Agent 源码

备选 Harness 参考（Pi 不可用时替换教材，学习目标不变）

• Claude Agent SDK
• OpenAI Agents SDK
• OpenCode

本仓库对应源码

• packages/harness-pi/src/harness.ts 与 event-adapter.ts：Pi 事件适配参考实现
• packages/harness-native/src/agent-loop.ts：拿来做对照基线

下一步：A2 · Session / Compaction 深度实现