本阶段的核心命题 从"会用 Agent"上升到"能定义和比较 Agent Harness"。判别标准：拿到一个陌生 Harness，能在半小时内说清它做了哪九件事、每件做到什么程度、为什么这么取舍。
本阶段是全路线唯一"有现成教材"的阶段 本仓已有四份完整拆解——Pi、DeepSeek Harness、Codex、Claude Code。阶段 6 的任务不是顺读 50 余章，而是把四份拆解压成一张对照表，并回答"我们的主要约束是什么、哪些设计值得迁移"。
任何生产级 Agent 系统都要有人承担这九项责任，但承担者未必都在 Harness 内核：也可能是宿主应用、OS、扩展或独立服务。缺少明确责任方，就会把风险悄悄转嫁给用户或研发。
| # | 部件 | 解决什么 | 做不好的症状 |
|---|---|---|---|
| ① | 指令装配 | 系统提示词从哪来、按什么顺序拼、能不能分层覆盖 | 行为不可预期，改一处影响全局 |
| ② | 模型适配 | 多 Provider、协议差异、降级路由 | 绑死一家；换模型要重写 |
| ③ | 工具管线 | 注册 → 校验 → 权限 → 执行 → 呈现 | 工具随便加，没人知道谁能做什么 |
| ④ | 上下文与压缩 | 装配、筛选、超限处理 | 长会话必崩，或悄悄丢掉关键约束 |
| ⑤ | 会话与状态 | 存储、恢复、分叉、重放 | 关掉就没了；出问题无法复现 |
| ⑥ | 执行环境 | 文件系统、Shell、进程、网络、浏览器 | 能力有了但没有边界 |
| ⑦ | 权限与审批 | 什么能自动做、什么要确认、什么禁止 | 要么处处弹窗，要么什么都敢做 |
| ⑧ | 扩展点 | 别人怎么加能力而不改内核 | 每个需求都要改主干 |
| ⑨ | 可观测性 | 事件流、轨迹、用量、成本归因 | 线上问题只能靠研发捞日志 |
这九项就是阶段 0 那张分层图里"③ Harness"的展开 也是阶段 0 实践 2的自评表。此刻回去看一眼当初填的"只记得结论"有几格——这一阶段的任务就是把它们清掉。
阶段 0 讲过边界，这里补一条实践中最有用的判别方法：看这九个部件分别由谁实现。
| 方案形态 | ①②③ | ④⑤ | ⑥⑦ | ⑧⑨ |
|---|---|---|---|---|
| 自己拿 SDK 从零搭 | 自己 | 自己 | 自己 | 自己 |
| 用 Agent 框架 | 框架 | 部分框架 | 自己 | 部分框架 |
| 用现成 Harness（Claude Code / Codex） | 大部分内置 | 会话能力较完整，持久任务另论 | 有产品边界，但企业策略仍需定义 | 有扩展与事件，完整观测平台另建 |
| 基于开源 Harness 做产品 | 继承 | 继承 | 你要重新定义 | 你要补 |
第四行是本学习路线最相关的形态（Pi 桌面端就是它）。它的特点是：内核能力是继承来的，但边界、权限、打包、更新、可观测性必须自己重做——因为这几项和"面向什么用户"强绑定。
本仓四份拆解分别优化了不同的一等约束：
| Pi | DeepSeek Harness | Codex | Claude Code | |
|---|---|---|---|---|
| 它在问什么 | 最少需要什么？ | 最多能拆成什么？ | 全都做完要付多少？ | 如何把有限上下文用到最值钱的地方？ |
| 组织原则 | 减法 | 全插件化 | 工程完备 | 上下文经济学 |
| 优化目标 | 可读、可改 | 可替换 | 可验证、可交付 | 稳定缓存前缀、控制 Token 与动态注入 |
| 典型取舍 | 不兜住全部能力 | 内核也可替换 | 自研协议、安全与跨平台能力 | 系统提示词分区、附件增量、工具延迟加载、Fork 复用缓存 |
| 适合学习什么 | 最小 Loop 与扩展边界 | Seam、Patch 与插件契约 | 协议、沙箱和产品完备性 | Prompt 装配、工具治理、Subagent 与缓存成本 |
Claude Code 的证据边界 Claude Code Harness 深度教程基于 2026-03-31 的外部版 Sourcemap 快照，并用本机 2.1.241 Transcript 交叉验证。基础教程只迁移通用设计原则；精确数量、内部实验名和被 DCE 删除模块的推断，不能当成永久公开契约。
| 能力 | Pi | dsh | Codex | Claude Code |
|---|---|---|---|---|
| 子 Agent | 不做（用外部进程协作） | 多种委派机制 | 子进程与协作图 | Fresh / Fork 两条上下文合同，Fork 兼顾缓存复用 |
| 权限 | 不做弹窗 | 留 approval seam | 规则 + 模型判官 + OS 隔离 | 多模式规则、Hooks 与外部 Sandbox 叠加 |
| 上下文 | 单层摘要，保持简单 | 配置化装配与摘要 | 本地/远端压缩 | 稳定前缀 + 动态附件 + 分层压缩 |
| 扩展 | TS 扩展 | 一切皆插件 | MCP / Skills / Hooks / Plugins | Skills / Plugins / MCP / Commands / Hooks 多通道 |
这是本阶段最重要的一条可迁移判断 "要不要做这个能力"取决于目标用户、主要威胁、谁为出错买单，以及系统最稀缺的资源是什么。 不存在脱离约束的最佳架构。
Codex 用一份提交/事件双队列协议把 core 与前端彻底解耦，因此同一个内核能同时喂饱终端、IDE 插件、桌面 App、MCP 客户端和云端任务。
代价是真实的：所有人机交互都要变成往返消息、协议版本要冻结、一个 Session 同时只能跑一个 Task。
产品含义：如果产品未来要有多个前端形态，协议先行必须在第一天做；如果只有一个前端，它是过度设计。
Codex 把提示词随模型元数据下发并按客户端版本管理；Claude Code 则把稳定段、动态段和运行时附件分开，避免动态信息反复破坏缓存前缀。
产品含义：提示词工程正在变成提示词运维——有 Section、有版本、有灰度、有缓存语义、与模型能力绑定。任何"提示词写死在代码里"的方案，都要问：改一次要不要发版？动态内容为什么要进入稳定前缀？
Codex 的跨平台沙箱代码量比例约为 Windows 19852 : Linux 9694 : macOS 1036。
产品含义：给一个桌面工具加沙箱，Windows 那一份大约是 macOS 的 20 倍工作量。这个数字可以直接用于排期估算和"先支持哪个平台"的决策。
Codex 的 Guardian 用一个模型给另一个模型的动作做风险判定，其策略文件（8KB 级）是可评审、可版本控制、可针对性测试的。两个设计点值得记：二维判定（风险等级 × 用户授权），以及一半篇幅在防误报。
产品含义：安全组件的失败模式有两个方向——漏拦（危险）和误拦（不可用）。只优化前者的安全设计，最终会被用户关掉。
四者的扩展面差异很大：Pi 靠扩展补能力、dsh 一切皆插件、Codex 与 Claude Code 都提供多条扩展通道。Claude Code 进一步说明：扩展存在还不够，模型必须通过渐进披露和动态列表及时知道当前有什么能力。
产品含义：扩展点越深，第三方能做的事越多，兼容、发现、权限和供应链治理成本也越大。
Claude Code 的 Hook 案例说明，生命周期扩展可以改写输入输出、参与权限判断、阻止执行或停止、注入上下文并落审计轨迹。它把提示词中的"建议"升级成了确定性系统策略。
产品含义：Hook 需要单独设计工作区信任、密钥白名单、超时、失败语义与上下文预算。非阻塞失败也不是零成本：错误可能持续进入日志和上下文。详见 Claude Code：Hooks 治理层。
| 形态 | 例子 | 强项 | 难点 |
|---|---|---|---|
| 本地 Harness | Claude Code、Codex CLI、Pi 桌面端 | 直接访问用户文件与工具链；数据不出域 | 分发、更新、跨平台、支持成本 |
| 云端 Managed Agent | 各家托管 Agent 服务 | 免安装、可扩容、可集中治理 | 访问用户本地环境难；数据合规 |
| 嵌入式 Agent | 集成在 IDE / SaaS 内 | 贴近工作流、上下文天然 | 受宿主约束；能力面窄 |
混合形态是常态 现实产品往往是"本地壳 + 云端能力"或"云端主体 + 本地执行器"。判断一个产品属于哪一类，看执行发生在哪里、状态存在哪里这两件事，而不是看它长什么样。
| 误区 | 纠正 |
|---|---|
| "包越少越优雅" / "包越多越灵活" | 两者都是对特定用户群的合理选择，脱离用户群比较没有意义 |
| "先做通用架构，以后好扩展" | 协议先行/全插件化都有实打实的代价；没有多前端需求就是过度设计 |
| "权限弹窗是安全措施" | 弹窗是 UI；安全是能力边界。Pi 直接称其为"安全表演"有其道理 |
| "扩展点越多越好" | 每个扩展点都是一份长期兼容承诺 |
| "沙箱是研发的事" | 平台成本差 20 倍，直接影响支持哪些平台——这是产品决策 |
| "提示词是内容不是工程" | 版本、灰度、与模型绑定，全是工程问题 |
| "选一个开源 Harness 就省事了" | 内核能省，⑥⑦⑧⑨ 四项通常都要重新定义 |
| "有 Hook 就有治理" | Hook 本身也是代码执行与上下文注入面，需要信任、权限、超时和审计 |
| 资料 | 出处 | 读它拿什么 |
|---|---|---|
| Effective harnesses for long-running agents | Anthropic，2025-11-26 | Harness 这一层在长任务上要解决什么 |
| Building agents with the Claude Agent SDK | Anthropic，2025-09-29 | 一个成熟 SDK 把哪些部件打包了 |
| Agent SDK overview | Claude Code 文档 | "什么时候用 SDK、什么时候自己写 loop"的官方判别 |
| Agents SDK 指南 | OpenAI | 另一家对同样九个部件的切分方式 |
本仓已有资料（本阶段的主教材）：
阅读顺序建议 先读 Claude Code 第 15 章拿到四方框架，再按九个部件去四份教程里找对应章节。不要顺读全部章节；带着九格表精读关键部分，才能把产品细节还原为可迁移判断。