四大 Agent Harness 对比：技术选型、设计思想与构建最佳实践

四大 Agent Harness 对比：技术选型、设计思想与构建最佳实践

阅读指南 本文不是四款工具的功能测评，而是基于我们已经完成的四套源码级教程，回答三个更底层的问题：

1. Pi、DeepSeek Harness、Codex、Claude Code 分别在优化什么？
2. 面对不同用户、风险、规模与成本约束，应该采用哪条架构路线？
3. 如果今天从零构建一个 Agent，哪些关键节点必须优先设计？

全文先做技术选型与设计哲学对比，再沉淀一套「Agent Harness 十二节点法」，作为后续构建内部 Agent、产品型 Agent 和 Agent 平台的设计检查清单。

先说结论 四者不是简单的优劣关系，而是四组约束条件下的最优解：

• Pi 优化「最小、可读、可改」；
• DeepSeek Harness 优化「可替换、可组合、可长期演化」；
• Codex 优化「可验证、可交付、可在不可信环境运行」；
• Claude Code 优化「长上下文、缓存命中率和机队级 token 成本」。

真正成熟的 Agent 架构通常不是四选一，而是分阶段组合：

用 Pi 的最小内核起步，用 dsh 的 seam 与生命周期支撑演化，用 Codex 的协议、安全和测试走向生产，再用 Claude Code 的上下文经济学解决规模成本。

一、为什么比较 Harness，而不只是比较模型

模型决定 Agent 的能力上限，但 Harness 决定这份能力能不能在真实环境里稳定工作。

一个只会调用模型的程序很简单：输入消息，获得回答。但真实 Agent 还要处理：

• 模型什么时候继续、什么时候停止；
• 工具如何注册、校验、审批、执行与回传；
• 项目规则、用户偏好、环境状态如何进入上下文；
• 对话过长以后如何压缩，又如何避免丢失关键事实；
• 会话如何恢复、回退、分叉和审计；
• 子 Agent 如何委派，权限如何继承，结果如何验证；
• 插件如何扩展能力，又如何避免污染内核；
• 失败、重试、成本、缓存和安全事件如何被观测。

因此，Agent Harness 更接近一个面向智能体的「操作系统」：

graph TB
    U[用户与外部系统] --> P[交互协议与任务入口]
    P --> L[Agent Loop]
    L --> M[模型调用]
    L --> T[工具执行]
    L --> C[上下文管理]
    L --> S[会话与状态]
    T --> G[权限与安全治理]
    C --> O[预算与压缩]
    S --> E[恢复与审计]
    X[扩展与多 Agent] -.-> L
    V[可观测性与评估] -.-> M
    V -.-> T
    V -.-> C

    classDef input fill:#a5d8ff,stroke:#1971c2
    classDef core fill:#d0bfff,stroke:#7048e8
    classDef govern fill:#ffc9c9,stroke:#c92a2a
    classDef data fill:#c3fae8,stroke:#0ca678
    classDef support fill:#fff3bf,stroke:#e67700

    class U,P input
    class L,M,T,C,S core
    class G,O govern
    class E data
    class X,V support

四套 Harness 的差异，主要不是 Agent Loop 写法不同，而是它们如何处理 Loop 周围这些昂贵、复杂且充满边界条件的工程问题。

二、研究基线与证据边界

不要机械比较代码量 四组数字的统计口径并不完全一致。Codex 的 147 万行包含大量测试、TUI 和跨平台沙箱；Claude Code 的 51 万行来自外部构建 sourcemap；dsh 的「185 个包」体现拆分粒度，不代表核心循环很大；Pi 则主动把许多能力留给扩展。

因此本文比较的是架构选择与工程重点，不是用包数或代码行数给项目排名。

四套教程入口：Pi-Agent 深度教程、DeepSeek Harness 深度教程、Codex Harness 深度教程、Claude Code Harness 深度教程。

三、四条架构路线：它们分别在解决什么问题

3.1 Pi：最少需要什么

Pi 的问题是：一个可用、可理解、可改造的 Agent，最少需要保留什么？

它的答案是一个依赖漏斗：

• pi-ai 负责多模型统一调用；
• pi-agent-core 负责 Agent Loop、工具和状态；
• pi-coding-agent 负责编码场景产品能力；
• pi-tui 作为正交 UI 库独立存在。

Pi 明确不内置 MCP、子 Agent、权限弹窗、Plan Mode、Todo 和后台 Bash。它不是否认这些能力有价值，而是认为：

1. 有些能力应该交给成熟外部工具，例如 tmux、容器和文件；
2. 有些能力应该由用户按工作流自行扩展；
3. 内核一旦内置某种工作流，就会替用户做决定。

Pi 的核心竞争力不是功能少，而是「少而不封闭」：核心保持可读，扩展系统负责长出个性化能力。

3.2 DeepSeek Harness：最多能拆成什么

DeepSeek Harness 的问题是：Agent 运行时的每个能力，能不能都拆成可替换接缝？

它以 cordis IoC 容器为底座，把文件、Shell、进程、模型、沙箱、审批、会话、压缩、委派等能力拆成 seam：

• Service Definition 只定义能力；
• Provider 提供具体实现；
• 插件通过 inject 声明依赖；
• fiber 管理生命周期与自动清理；
• Profile 与 Patch 分层组装每次会话；
• host 平面和 agent 平面分别管理进程级与会话级能力。

这条路线的价值是：换后端、换部署方式、换安全策略，尽量只改配置或 Provider，不改调用方。

代价也很明确：理解 cordis、配置分层和插件图之后，才能真正理解系统行为。它用较高的认知门槛换取长期演化能力。

3.3 Codex：一个生产级 Agent 产品要补齐多少工程账

Codex 的问题是：如果 Agent 要跑在大量用户的电脑上、面对不可信代码库，并同时服务 TUI、IDE、桌面端、MCP 和云任务，需要补齐哪些工程能力？

它选择了 Rust、单二进制、多入口和协议先行：

• UI 到内核走提交队列；
• 内核到 UI 走事件队列；
• 所有交互先变成协议消息；
• 多种前端只是同一协议的消费者；
• 沙箱针对不同操作系统分别实现；
• 审批从静态规则一路升级到 LLM Guardian；
• 复杂度由 14000+ 测试兜底。

Codex 展示的不是最优雅的最小架构，而是一份产品级 Agent 的完整工程账单：协议兼容、跨平台、安全隔离、恢复、诊断、测试、分发，一个都不能少。

3.4 Claude Code：上下文与缓存能不能成为第一性架构约束

Claude Code 的问题是：当会话规模巨大、上下文直接影响效果与成本、prompt cache 命中率关系到机队级费用时，整个系统该如何围绕上下文经济学重构？

它把这条约束贯彻到了多个子系统：

• 系统提示词划分静态与动态边界；
• 动态状态通过附件和 system-reminder 注入消息尾部；
• 工具 schema 与技能清单有独立预算和延迟加载；
• 上下文压缩分成多层，优先可逆、低损方案；
• fork 子 Agent 复用父会话缓存前缀；
• 提示词、缓存断裂和工具执行都有机队级遥测；
• 提示词补丁带模型版本、实验与失败率依据。

Claude Code 的核心亮点不是「做了五层压缩」，而是把 token、缓存和上下文从实现细节提升成架构预算，并建立了约定、类型和观测三层治理。

四、技术选型对比

4.1 核心架构与交付形态

选型判断：

• 你要的是可读懂、可快速定制的骨架，优先参考 Pi；
• 你要的是多后端、多部署方式的 Agent 平台，优先参考 dsh；
• 你要的是面向大量用户的完整产品，优先参考 Codex；
• 你的主要矛盾已经变成长会话成本与上下文稳定性，优先参考 Claude Code。

4.2 Agent Loop 与生命周期

四者共同证明：Agent Loop 本身并不复杂，复杂的是围绕每一轮发生的状态冻结、工具治理、用户插话、压缩、恢复和观测。

如果一个团队一开始就把大量业务逻辑塞进 while true，后面几乎一定会遇到无法测试、无法插拔、无法恢复的问题。

4.3 模型接入与提示词管理

这里有两种不同路线：

1. Provider 广度优先：Pi 和 dsh 接受「能力取交集」与翻译成本，换取模型可替换性；
2. 单家能力深度优先：Codex 和 Claude Code 更充分利用自家协议、推理链、缓存或远端压缩能力。

因此，多模型不是无条件正确。要先决定：你的产品更需要供应商可替换性，还是更需要吃满某一家模型的专有能力。

4.4 上下文工程

四者共同给出三个结论：

• 上下文不是一段字符串，而是一条装配流水线；
• 静态规则、动态状态、工具清单和历史消息必须分开管理；
• 上下文越复杂，越需要预算、降级顺序和可观测性。

4.5 工具系统与安全治理

这里不存在统一答案，关键在威胁模型：

• 如果用户就是机器主人，且运行在可丢弃容器里，Pi 的坦诚边界是合理的；
• 如果平台需要替不同部署接不同隔离后端，dsh 的 sandbox seam 更合适；
• 如果 Agent 面对不可信仓库、普通用户和跨平台桌面环境，Codex 的隔离优先路线更稳妥；
• 如果已有成熟规则、钩子和审批体系，Claude Code 的治理组合更容易覆盖复杂企业工作流。

4.6 会话、扩展与多 Agent

会话设计上，Pi 和 dsh 给出了两个非常值得保留的原则：

• 历史不删除，只移动当前视角；
• 消息不是唯一真相，日志或树才是真源。

这使恢复、审计、分叉、压缩和调试能够建立在同一份数据之上。

五、设计思想对比：四种哲学背后的约束

5.1 Pi 的哲学：克制是一种产品能力

Pi 最值得学习的不是「少」，而是每一个「不做」都能回答：

• 谁来补？
• 用什么补？
• 为什么外部实现更合适？

例如后台 Bash 交给 tmux，安全边界交给容器，计划交给文件，个性化工作流交给扩展。它用文件、协议和外部工具替代内建功能，避免把单一工作方式固化进核心。

**适用前提：**用户有一定技术能力，团队愿意管理扩展，且风险可以通过环境隔离承担。

5.2 dsh 的哲学：所有长期变化都应该有接缝

dsh 把变化当作默认：模型会换、存储会换、沙箱会换、部署会换、UI 会换。因此它提前把这些位置都做成 seam，并通过依赖声明、fiber 和 dispose 管理插件生命周期。

它最重要的判断是：插件系统的核心不是「能注册功能」，而是「依赖、所有权、卸载和冲突都可管理」。

**适用前提：**系统确实存在多实现或长期平台化需求。只有单一后端的小项目，提前复制 185 包的粒度只会制造抽象债务。

5.3 Codex 的哲学：复杂度必须由协议、隔离和测试偿付

Codex 不回避复杂度，因为它面对的是产品级责任：任何前端都要能接入，任何平台都要能运行，任何危险命令都不能只靠模型自觉。

它的工程纪律可以概括为：

• 交互先协议化；
• 每次请求冻结世界视图；
• 权限由多层策略收敛；
• 自由策略外面必须有硬上限；
• 复杂度必须有测试和诊断能力兜底。

**适用前提：**产品面向广泛用户、操作真实资源、需要跨平台交付，并且团队有能力承担长期测试与兼容成本。

5.4 Claude Code 的哲学：看不见的 token 也必须进入工程预算

Claude Code 把上下文和 prompt cache 当成类似 CPU、内存、延迟的基础资源：

• 有预算；
• 有缓存边界；
• 有逐层降级；
• 有断裂检测；
• 有机队级数据；
• 有针对模型版本的提示词补丁和回滚计划。

它反复使用「预算 + 降级 + 打点」模式：先规定资源上限，超限时按明确顺序牺牲内容，并记录每次降级发生了什么。

**适用前提：**会话足够多、上下文足够长、成本足够大，而且团队能真正测量优化前后的变化。没有数据时照抄复杂缓存技巧，只会得到不可解释的系统。

六、四者的工程重点与核心亮点

6.1 Pi：最值得带走的五点

1. 内核 + 叠加：先保留十几行能跑的 Loop，再把 steering、follow-up、hooks 等产品能力叠在外层。
2. 协议优先于继承：多 Provider 通过统一事件协议和翻译函数接入，不强求共享基类实现。
3. 错误即消息：工具失败不让异常穿透 Agent 边界，而是变成模型能理解、能自愈的结果。
4. 会话树：append-only + leafId 实现不丢历史的回退和分叉。
5. 渐进式披露：Skills 只让名称与描述常驻，完整内容按需加载。

Pi 最适合作为「第一版 Harness 的代码教科书」：它让团队先看清什么是不可缺少的，再决定往外增加什么。

6.2 DeepSeek Harness：最值得带走的五点

1. Service Definition 与 Provider 分离：接口不依赖具体后端。
2. 依赖用声明，不用配置顺序：插件通过 inject 声明前置能力。
3. 生命周期硬约束：owner 卸载时，监听器、服务和资源必须自动释放。
4. 事件是真源，消息是投影：对人和对模型可以生成不同 surface。
5. 压缩是遮蔽，不是删除：用追加事件替代破坏性裁剪，保留恢复和审计能力。

dsh 最适合作为「Agent 平台接缝清单」：即使不采用 cordis，也可以用它检查自己的系统里哪些能力仍被写死。

6.3 Codex：最值得带走的六点

1. SQ/EQ 协议先行：内核与前端只交换提交和事件，不直接调用。
2. 不可变世界视图：一次模型请求看到的工具、权限、环境和实际执行时保持一致。
3. World State 增量更新：环境状态结构化，每轮只注入变化。
4. 工具可见性三维化：区分初始直出、可检索、可在 Code Mode 调用。
5. Guardian 策略文档化：LLM 判官的风险标准可读、可评审、可版本控制。
6. 自由策略 + 硬性上限：重试、压缩、多 Agent、判官判断都允许灵活，但代码保留不可突破的天花板。

Codex 最适合作为「生产级 Agent 工程总账」：当产品要从内部试用走向广泛交付时，它会提醒团队还有哪些债没有还。

6.4 Claude Code：最值得带走的六点

1. 静态与动态上下文分离：稳定前缀进入缓存，动态信息移到后部通道。
2. 每类上下文都有预算：技能、工具 schema、记忆、工具结果分别治理。
3. 压缩先可逆后有损：先落盘和清理可重跑工具结果，最后才做整段摘要。
4. fork 复用缓存前缀：多 Agent 的成本优化进入调度设计。
5. 提示词工程化运营：模型补丁有版本、实验、失败率和回滚语义。
6. 验证 Agent 的问责结构：命名失败模式、反驳托词、规定证据格式、限制逃生口，并让被验证者知道结果会被抽查。

Claude Code 最适合作为「规模化上下文工程手册」：它告诉我们，效果、成本和可靠性可以被放进同一套工程治理体系。

七、技术选型：什么场景该参考哪一条路线

graph TB
    A[先定义用户与风险承担者] --> B{是否面向不可信环境或广泛用户}
    B -->|是| C[优先采用 Codex 路线<br/>协议 隔离 审批 测试]
    B -->|否| D{是否需要多后端多部署长期演化}
    D -->|是| E[优先采用 dsh 路线<br/>seam 插件 生命周期 配置]
    D -->|否| F[优先采用 Pi 路线<br/>最小内核 文件 扩展]
    C --> G{上下文与 token 是否已成主要成本}
    E --> G
    F --> G
    G -->|是| H[叠加 Claude Code 路线<br/>缓存边界 预算 降级 打点]
    G -->|否| I[保持当前复杂度<br/>先补观测再扩展]

    classDef input fill:#a5d8ff,stroke:#1971c2
    classDef decision fill:#fff3bf,stroke:#e67700
    classDef route fill:#d0bfff,stroke:#7048e8
    classDef scale fill:#c3fae8,stroke:#0ca678

    class A input
    class B,D,G decision
    class C,E,F route
    class H,I scale

7.1 场景选型矩阵

7.2 推荐的组合方式

最现实的方案不是复制任何一个项目，而是按层组合：

graph TB
    subgraph product["产品与入口层"]
        A[Codex 式协议与多前端]
    end
    subgraph govern["治理与交付层"]
        B[Codex 式沙箱 审批 测试]
        C[dsh 式 fail-closed 与 Provider 替换]
    end
    subgraph runtime["运行时内核层"]
        D[Pi 式最小 Agent Loop]
        E[dsh 式 seam 生命周期 事件]
    end
    subgraph context["上下文与成本层"]
        F[Claude Code 式缓存边界 预算 降级 打点]
        G[Codex 式 World State 增量]
    end
    subgraph data["会话与审计层"]
        H[Pi 式会话树]
        I[dsh 式事件真源与投影]
    end

    A --> B
    A --> C
    B --> D
    C --> E
    D --> F
    E --> G
    F --> H
    G --> I

    classDef productClass fill:#a5d8ff,stroke:#1971c2
    classDef governClass fill:#ffc9c9,stroke:#c92a2a
    classDef runtimeClass fill:#d0bfff,stroke:#7048e8
    classDef contextClass fill:#fff3bf,stroke:#e67700
    classDef dataClass fill:#c3fae8,stroke:#0ca678

    class A productClass
    class B,C governClass
    class D,E runtimeClass
    class F,G contextClass
    class H,I dataClass

一句话表达这套组合：

内核保持 Pi 式克制，变化位置采用 dsh 式接缝，生产边界按 Codex 式加固，规模成本用 Claude Code 式治理。

八、构建 Agent 的最佳实践：十二关键节点

下面这套「十二节点法」不是要求第一天全部实现，而是要求在设计时逐项回答。没有答案的节点，就是未来最可能爆发的工程债。

节点 1：先定义用户、风险与约束

在写 Loop 之前，先明确：

• 用户是开发者、内部员工，还是普通消费者？
• Agent 操作的是个人沙盒、共享代码库，还是订单与资金？
• 风险由用户承担，还是平台必须兜底？
• 主要成本是研发速度、跨平台、安全，还是 token？
• 系统是否真的需要多模型、多后端、多前端？

**最佳实践：**形成一页「约束与威胁模型」，所有架构复杂度必须能映射回其中一条约束。无法映射的复杂度暂缓引入。

来源启示：四者的全部差异，本质上都是用户和约束不同。

节点 2：先写最小 Agent Loop，再做叠加

最小 Loop 只需要：

1. 获取用户输入；
2. 组装当前上下文；
3. 调用模型并流式接收结果；
4. 如果有工具调用，执行并回填结果；
5. 根据明确终止原因决定继续或结束。

Plan Mode、Todo、压缩、子 Agent、权限弹窗都不应成为第一版 Loop 的内生分支。

**最佳实践：**让主循环只负责状态推进；压缩、复核、委派等能力建成平级任务、事件监听器或外层叠加。

来源启示：Pi 的「内核 + 叠加」、Codex 的任务类型、dsh 唯一含循环逻辑的包。

节点 3：把生命周期和交互协议化

至少定义清楚：

• Session、Task、Turn、Step 分别是什么；
• 长任务是否有 Begin / Delta / End 事件；
• 用户插话是立即 steering，还是排队 follow-up；
• 前端和内核通过函数调用还是消息协议通信；
• 哪些事件允许通知、否决、修改或接管。

**最佳实践：**先写事件清单、状态机和错误语义，再写具体 UI。多前端需求一旦存在，协议必须先于界面。

来源启示：Codex SQ/EQ、Pi steering/follow-up、dsh 可否决事件。

节点 4：冻结一次请求的世界视图

模型请求发出时，应该冻结一份不可变快照，至少包含：

• 当前模型与能力；
• 当前工具 schema；
• 当前权限模式与审批策略；
• 当前工作目录、环境和项目规则；
• 当前上下文预算与压缩状态。

不能出现「模型看到工具可用，但执行时工具已经被卸载」或「模型按旧权限规划，执行时权限突然变化」的漂移。

**最佳实践：**广告给模型的世界和实际执行的世界必须来自同一份快照；动态变化进入下一轮。

来源启示：Codex 不可变世界视图、dsh agent 平面会话级插件图。

节点 5：模型接入采用 seam，模型差异进入元数据

模型调用层至少要分开：

• 通用消息与 Provider 请求格式；
• 通用流事件与 Provider 返回事件；
• 模型能力、窗口、思考等级和工具支持；
• 模型专属提示词与行为补丁。

**最佳实践：**不要在业务代码里散落 if model == ...。把模型能力和提示方式放进同一份元数据，通过翻译器或 Provider seam 处理差异。

来源启示：Pi 翻译器函数、dsh LLM seam、Codex 模型目录、Claude Code 模型版本补丁。

节点 6：上下文必须分区、预算化和可降级

建议至少分成五区：

1. 稳定系统指令；
2. 项目与用户规则；
3. 当前世界状态；
4. 工具和技能能力清单；
5. 对话历史与工具结果。

每一区都要回答：

• 是否稳定，能否缓存？
• 最大预算是多少？
• 超限先牺牲什么？
• 降级是否可观测？
• 内容是否能够按需加载？

**最佳实践：**采用「预算 + 明确降级顺序 + 打点」三段式；动态状态优先发 diff，工具与技能优先渐进披露。

来源启示：Claude Code 缓存边界与预算、Codex World State、Pi Skills、dsh 模型体验说明。

节点 7：工具调用必须经过统一执行管道

一条成熟的工具链至少包含：

发现工具
→ 参数规范化
→ Schema 校验
→ 业务前置校验
→ 权限与策略判定
→ 必要时人工审批
→ 沙箱或受控环境执行
→ 结果规范化
→ 后置钩子
→ 审计与指标
→ 回填模型

最佳实践：

• 工具错误转成结构化消息，告诉模型下一步该怎么办；
• 观察用数据和执行用数据分开，执行数据才是权威；
• 并发工具的副作用在批次结束后按确定顺序统一应用；
• 安全扩展可以无条件收紧权限，但放宽必须经过中央策略。

来源启示：Pi 五步管道、dsh 事件流水线、Codex execpolicy、Claude Code 多道工具关卡。

节点 8：软引导与硬安全必须分层

提示词只能负责「建议」，不能承担「强制」。真正的安全边界应该由：

• 操作系统沙箱或容器；
• 最小权限凭据；
• 路径与网络策略；
• 审批与一次性授权；
• 幂等、限额与熔断器；
• 不可被子 Agent 扩大的权限继承规则。

**最佳实践：**安全相关故障默认 fail-closed；所有模型或用户可配置的自由度，都要有一层它们无法突破的硬上限。

来源启示：Pi 对安全边界的诚实声明、dsh fail-closed、Codex Guardian 与沙箱、Claude Code 权限模式。

节点 9：会话以 append-only 日志或树为真源

不要只保存最终 messages 数组。更稳妥的真源应该能记录：

• 用户与助手消息；
• 工具调用与结果；
• 权限申请与审批；
• 模型和配置变化；
• 压缩、替换和遮蔽事件；
• 分支、回退和恢复位置。

**最佳实践：**历史不原地删除；回退移动指针，分叉追加新节点；面向人和面向模型的消息从真源投影生成。

来源启示：Pi 会话树、dsh 事件溯源、Codex rollout、Claude Code transcript。

节点 10：压缩遵循「可逆优先、有损兜底」

推荐顺序：

1. 单条超大工具结果落盘，只保留预览与路径；
2. 清理可重跑、低价值的旧工具结果；
3. 对局部历史做结构化遮蔽或替换；
4. 最后才对整段历史生成交接摘要；
5. 撞上服务端上限时再走 reactive recovery。

**最佳实践：**摘要不是文学总结，而是「给下一个模型的结构化交接」；固定必填字段，保留目标、事实、决策、未完成项、关键路径和验证状态。

来源启示：Pi 结构化摘要、dsh 遮蔽压缩、Codex 本地与远端路径、Claude Code 多层防线。

节点 11：扩展与多 Agent 都必须有治理合同

扩展系统至少需要：

• 清晰的注册协议；
• 显式依赖声明；
• owner 生命周期与 disposer；
• 「发现」与「启用」权限分离；
• 对权限影响的不对称规则；
• 版本、冲突和诊断机制。

多 Agent 至少需要：

• 子任务范围和交付物；
• 子权限必须是父权限的子集；
• 主 Agent 派活后该做什么；
• 禁止重复劳动和预测异步结果；
• 结果证据格式与抽查机制；
• 递归深度、数量和 token 硬上限。

**最佳实践：**不要把「能启动子 Agent」误认为「已经有多 Agent 架构」。没有委派合同、权限继承和结果验证，多 Agent 只是在并行制造不确定性。

来源启示：dsh 插件生命周期与多种委派、Codex 协作图与权限收缩、Claude Code fork 协议与验证 Agent、Pi 对内置子 Agent 的克制。

节点 12：先有可观测性，再允许复杂度增长

至少记录：

• 每轮 token、延迟、重试和终止原因；
• 工具执行链每一道关的耗时与决策来源；
• 上下文各区大小、截断与降级次数；
• 缓存命中与前缀断裂；
• 压缩触发、摘要长度和恢复成功率；
• 权限拒绝、用户推翻与重复尝试；
• 子 Agent 数量、成本、成功率和复核结果。

测试应覆盖：

• Provider 替身与流事件；
• 工具成功、失败、中断与并发；
• 会话恢复、分叉和压缩；
• 权限规则的正反例断言；
• 提示词与策略的回归评估；
• 跨平台安全边界。

**最佳实践：**提示词也按代码管理：有版本、有基线、有评估、有 A/B、有回滚。任何依赖「感觉更好」的提示词改动，都不应直接进入生产。

来源启示：Pi 事件断言面、dsh 事件日志、Codex 大规模测试、Claude Code 机队遥测与提示词实验。

九、推荐的建设路线：从能跑到能规模化

阶段一：最小可用

目标是证明 Agent 闭环，而不是证明架构能力。

必须有：

• 最小 Loop；
• 统一模型流事件；
• 3–5 个核心工具；
• 参数校验和结构化错误；
• append-only 会话记录；
• 基础 token、延迟、工具成功率指标。

主要参考：Pi。

阶段二：可演化

当第二个 Provider、第二种存储或第二个产品入口出现时，再补：

• Provider seam；
• 事件总线；
• 生命周期与 disposer；
• 配置分层；
• Skills 与工具渐进披露；
• 结构化压缩。

主要参考：DeepSeek Harness + Pi。

阶段三：可交付

当 Agent 开始操作真实资源、面向更多用户时，补齐：

• 前端与内核协议；
• 不可变世界视图；
• 沙箱、网络与凭据隔离；
• 审批与权限规则；
• fail-closed；
• 恢复、诊断和完整测试矩阵；
• 多 Agent 权限与数量上限。

主要参考：Codex。

阶段四：可规模化

当上下文与成本成为主要矛盾时，再引入：

• 静态/动态缓存边界；
• World State diff；
• 工具与技能检索；
• 分区预算与降级打点；
• 多层压缩；
• fork 缓存复用；
• 提示词 A/B 与行为指标。

主要参考：Claude Code + Codex。

复杂度的准入原则 每增加一层复杂度，至少要同时增加一种验证手段：测试、指标、日志、断言或回放。

没有可观测性的复杂度，不是能力，而是黑箱。

十、最常见的十个反模式

1. 先建插件平台，后找第二个实现：没有变化需求时，seam 只是抽象债务。
2. 把所有逻辑塞进主循环：最终无法测试、无法插拔、无法恢复。
3. 把提示词当安全边界：模型建议不能替代沙箱、权限、限额和审批。
4. 项目文件被发现就自动启用：仓库内容可以声明扩展，但启用应由用户信任层决定。
5. 所有工具和技能永久塞进上下文：能力越多，模型越难选，token 成本也越高。
6. 压缩直接删除历史：短期省 token，长期失去审计、恢复和纠错能力。
7. 给用户和模型自由配置，却没有硬上限：重试、递归、多 Agent 和预算最终都会失控。
8. 主 Agent 派活后继续做同一件事：多 Agent 退化成重复劳动和互相覆盖。
9. 提示词修改不做回归评估：局部行为改善可能引发另一类失败率上升。
10. 没有数据却复制超大规模优化：缓存技巧、五层压缩和模型判官都需要真实收益证明。

十一、最终判断：该抄的不是架构外形，而是决策方法

四套 Harness 最终留下的不是四份标准答案，而是一套判断顺序：

1. 先问约束，不先问流行架构；
2. 先做最小闭环，不先做平台；
3. 变化真实出现后，再建立 seam；
4. 风险真实扩大后，再增加隔离和治理；
5. 成本真实可测后，再进行上下文经济学优化；
6. 每引入一层复杂度，都用测试或观测偿付。

可以把四者的精华压缩成一条构建公式：

Pi 的克制 × dsh 的可替换 × Codex 的可验证 × Claude Code 的可度量。

• 没有 Pi 的克制，系统会过早膨胀；
• 没有 dsh 的可替换，系统会被第一版实现锁死；
• 没有 Codex 的可验证，系统无法安全交付；
• 没有 Claude Code 的可度量，系统无法在规模下持续优化。

因此，构建 Agent 最重要的能力，不是写出一个会调用工具的 Loop，而是持续回答：

这一层复杂度，是由什么真实约束换来的？它的边界在哪里？我们用什么证据证明它有效？

能长期回答这三个问题，才是真正的 Harness Engineering。

Related Documents

• Pi 研究摘要
• DeepSeek Harness 研究摘要
• Codex Harness 研究摘要
• Claude Code Harness 研究摘要
• Pi：设计精华总结
• DeepSeek Harness：全插件化的收益与代价
• Codex：设计精华与哲学对照
• Claude Code：四种 Harness 哲学对照