为什么你的 Agent 总翻车？Harness Engineering 全拆解

Table of contents

1. 背景与问题

这段视频试图回答的，不是“怎样把 Prompt 写得更漂亮”，而是一个更工程化的问题：

为什么很多 Agent Demo 看起来很聪明，但一到真实任务、长任务、多工具任务、跨 Session 任务，就开始翻车？

更准确地说，问题通常不在模型“不会回答”，而在于：

• 任务没有被正确拆解
• 上下文没有被稳定管理
• 工具太多、太乱，或权限边界不清
• 执行过程缺乏状态保存与恢复机制
• 结果没有经过独立验证
• 失败后没有重试、回滚、人类接管等治理机制

所以，视频想强调的是：

Prompt Engineering 解决“怎么说”，而 Harness Engineering 解决“怎么让模型在一个可控的运行系统里把事情做成”。

flowchart TD
    A([问题起点<br>Agent Demo 很强]) --> B[进入真实任务]
    B --> C[长任务 / 多步任务 / 多工具调用]
    C --> D[裸模型暴露系统性缺陷]
    D --> E[上下文漂移]
    E --> F[状态丢失]
    F --> G[验证缺失]
    G --> H[提前宣布完成]
    H --> I([需要 Runtime / Harness 设计])

    style A fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style D fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    style I fill:#e8f5e9,stroke:#43a047,stroke-width:2px

📡 扩展
Anthropic 在 2025-11 的官方工程文章中直接指出：长时间运行的 Agent 面临的核心问题，是任务必须跨多个 context windows 离散执行，而每个新 session 都从“失忆”开始；仅靠 compaction 不够，还需要额外的 harness 结构来让 Agent 在多轮会话中持续推进。[Anthropic, Effective harnesses for long-running agents, 2025-11-26]

2. 核心概念

2.1 Harness Engineering 是什么

视频中最核心的一句定义可以整理为：

Harness Engineering 不是在教模型怎么回答，而是在设计模型怎么工作。

这里的 harness，可以理解为一整套把模型“约束、引导、连接、验证、治理”起来的运行时系统。
它不是单个 prompt，也不是单个工具，而是围绕 Agent 执行闭环的一层工程化外壳。

2.2 它和 Prompt / Context 的关系

flowchart TD
    A([Agent 工程演化]) --> B[Prompt Engineering<br>优化问法]
    B --> C[Context Engineering<br>优化可见上下文]
    C --> D[Harness Engineering<br>优化运行机制]

    B ~~~ C
    C ~~~ D

    D ==> E([生产级 Agent Runtime])

    style A fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style B fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style C fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    style D fill:#e8f5e9,stroke:#43a047,stroke-width:2px
    style E fill:#e0f7fa,stroke:#00838f,stroke-width:2px

📡 扩展
Google 官方文档对 Agent 的定义也很接近这一思路：Agent 不只是一次模型调用，而是结合模型、工具、推理能力去完成复杂多步任务；官方文档还明确写到，实际构建时通常仍需要额外的 orchestration framework 来管理 memory、plan loops 和复杂 tool chaining。也就是说，“模型 + 工具”还不够，运行机制本身就是独立层。[Google AI for Developers, Agents Overview, 2026-03-19]

3. 主体内容

3.1 为什么是 2025 年底到 2026 年初开始爆发

视频里给出了四个原因，整理后更清楚：

原因一：模型变强后，差异化开始从“模型本体”转向“系统设计”

当基础模型的能力不断抬高，很多任务的瓶颈就不再是“模型是否足够聪明”，而是：

• 有没有给它合适的工作环境
• 有没有把知识、规则、约束放到它能读、能执行的位置
• 有没有把失败变成可观测、可修复的问题

原因二：长任务、多步任务暴露了裸模型的系统性缺陷

典型失败模式包括：

• 一口气试图做完全部事情，导致上下文耗尽
• 下一轮 session 读到部分产物，就误判“已经完成”
• 修改了代码但没有测试
• 看见结果“差不多能跑”就停止

原因三：多步系统会发生成功率连乘坍塌

如果每一步成功率是 95%，看起来很高；
但串联 20 步之后，端到端成功率是：

0.95 ^ 20 ≈ 35.8%

也就是说，局部看起来很稳，整体仍然可能很不稳。

原因四：模型在商品化，Harness 变成新的护城河

当 GPT / Claude / Gemini 之间的核心差距缩小时，真正拉开差距的会越来越像：

• 知识组织是否对 Agent 友好
• 工具是否被合理裁剪
• 验证机制是否足够硬
• 状态是否可恢复
• 反馈闭环是否能持续改进系统

📡 扩展
OpenAI 在官方文章中强调，工程师的工作正在转向设计环境、明确意图、构建反馈循环，而不是亲手写每一行代码。[OpenAI, Harness engineering: leveraging Codex in an agent-first world, 2026-02-11]
Anthropic 在 2026-03 的官方文章也明确表示：在 agentic coding 的前沿，性能关键越来越落在 harness design 上，而不仅是 prompt。[Anthropic, Harness design for long-running application development, 2026-03-24]

3.2 头部公司到底在怎么做 Harness

3.2.1 Anthropic：从“双 Agent 跨窗口续跑”到“生成-评估分离”

Anthropic 早期的官方方案，核心是为跨多个上下文窗口的长任务设计一个最小可持续执行结构。

早期两段式结构

官方文章里的关键点包括：

• 第一次 session 用特殊 prompt 初始化环境
• 生成 claude-progress.txt 记录已做工作
• 生成 feature list，把高层需求展开成可测试清单
• 后续 coding agent 每次只做增量推进
• session 结束时写 commit、写进度，保证下个 session 可恢复

flowchart TD
    A([用户高层需求]) --> B[Initializer Agent]
    B --> C[初始化脚本 init.sh]
    C --> D[Feature List / JSON]
    D --> E[claude-progress.txt]
    E --> F[Git 基线]
    F ==> G[Coding Agent 多轮续跑]
    G --> H[读取进度与 Git 历史]
    H --> I[只推进一个功能]
    I --> J[测试 / 提交 / 写进度]
    J -.-> H
    J --> K([跨 Session 持续推进])

    style A fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style B fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    style G fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style K fill:#e8f5e9,stroke:#43a047,stroke-width:2px

📡 扩展
这部分与视频基本一致。Anthropic 官方写得非常明确：initializer agent 会建立 init.sh、claude-progress.txt 和初始 git commit；feature list 会把用户高层需求展开成大量可测试功能点，后续 coding agent 启动时先读这些外部制品，再增量推进。[Anthropic, Effective harnesses for long-running agents, 2025-11-26]

后续演进：Planner / Generator / Evaluator

Anthropic 后续进一步强调：

• Planner：先把工作规格化、拆解清楚
• Generator：负责实现
• Evaluator：负责独立检查结果，尤其通过 Playwright 等工具做真实交互验证

这里最关键的工程洞察是：

让生成者自己给自己打分，往往不可靠；把“生成”和“评估”拆开，通常更有效。

这和传统软件工程里“开发”和“QA / Review”分层很像，但在 Agent 系统里更关键，因为模型天然倾向于对自己的产出过度乐观。

sequenceDiagram
    participant U as 用户
    participant P as Planner
    participant G as Generator
    participant E as Evaluator
    participant H as Human

    U->>P: 给出目标 / 需求
    P->>G: 规格、计划、验收标准
    G->>E: 提交实现结果
    E->>E: 运行测试 / Playwright 检查
    E-->>G: 缺陷反馈 / 打分
    G->>E: 修复后再次提交
    E-->>H: 关键风险 / 需要人工确认
    H->>G: 继续 / 驳回 / 改需求

📡 扩展
Anthropic 2026-03 的官方文章显示，他们给 evaluator 接入了 Playwright MCP，让它直接操作页面、截图、评分、写详细 critique；并且作者明确提到：对于更强的新模型，某些 evaluator 环节会从“必要”变成“额外开销”，说明 harness 必须随模型能力动态裁剪，而不是越复杂越好。[Anthropic, Harness design for long-running application development, 2026-03-24]

3.2.2 OpenAI：把仓库本身做成 Agent 可读、可执行的系统

视频里提到的 OpenAI 案例，重点不是“Agent 会写代码”本身，而是他们如何把仓库、文档、约束、反馈循环工程化。

视频里的关键抽象

1. 把仓库知识变成系统记录（system of record）
2. 不靠 Agent “自觉守规矩”，而是加确定性规则和测试
3. 让 Agent 的失败反过来推动 Harness 自我改进

这件事真正重要的地方

• AGENTS.md 不是百科全书，而是目录
• 真正的知识应放在结构化的 docs/ 体系里
• 规则、测试、lint、review 这些确定性机制，要直接纳入运行时闭环
• 当 Agent 卡住时，不是继续硬试，而是追问：缺了什么能力、文档或护栏？

📡 扩展
OpenAI 官方写得很直白：当 agent struggle 时，他们把它视作信号，去补工具、补 guardrails、补 documentation，并让 Codex 自己写出这些修复。[OpenAI, Harness engineering: leveraging Codex in an agent-first world, 2026-02-11]
同一篇文章还写到：5 个月内，这个仓库增长到约 100 万行代码，由最初 3 人驱动 Codex，累计约 1,500 个 PR，平均约 3.5 PR / 人 / 天；随着团队增长到 7 人，吞吐反而继续上升。[OpenAI, 2026-02-11]

结构示意

flowchart TD
    A([用户需求]) --> B[AGENTS.md<br>目录型入口]
    B --> C[docs/ 结构化知识库]
    C --> D[Codex / Agent]
    D --> E[实现代码]
    E --> F[Lint / Test / Review]
    F -- "❌ 未通过" --> G[反馈写回仓库]
    G --> C
    F -- "✅ 通过" --> H([合并 / 发布])

    style B fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    style C fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style F fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style H fill:#e8f5e9,stroke:#43a047,stroke-width:2px

3.2.3 Google DeepMind：把“生成 / 验证 / 修正”做成闭环

视频中提到的 Aletheia，可以视作一个非常典型的“生成—验证—修正”式 Harness。

它的结构不是让一个模型“一把梭”，而是拆成：

• Generator：生成候选解
• Verifier：检查逻辑问题 / 缺陷
• Reviser：根据验证结果修正

flowchart TD
    A([问题]) --> B[Generator 生成候选解]
    B --> C[Verifier 检查逻辑与缺陷]
    C -- "✅ 正确" --> F([Final Output])
    C -- "🟡 小问题" --> D[Reviser 局部修正]
    D --> C
    C -- "🔴 根本性错误" --> B

    style A fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style B fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    style C fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style D fill:#ede7f6,stroke:#5e35b1,stroke-width:2px
    style F fill:#e8f5e9,stroke:#43a047,stroke-width:2px

📡 扩展
Google DeepMind 官方在 2026-02 的文章中明确写到：Aletheia 是一个数学研究 Agent，带有 natural language verifier，并通过 generate → verify → revise 的迭代流程来处理研究级数学问题。[Google DeepMind, Accelerating Mathematical and Scientific Discovery with Gemini Deep Think, 2026-02-11]
需要注意一个与字幕存在出入的点：字幕说它在 IMO-ProofBench Advanced 达到 95.1%；但我查到的官方博文表述是 “scoring up to 90%”，并没有看到 95.1% 这一数字。这里应以官方表述为准。

额外值得注意：Thought Signatures

字幕里提到的 “salt signatures” 更可能是 thought signatures。

它的官方定义是：

模型内部思考过程的加密表示，用于在多步交互里保留推理上下文。

这意味着 Google 在部分链路上，尝试把“跨步骤保持推理连续性”的问题，部分下沉到模型/API 层来处理。

📡 扩展
Google 官方文档明确说明，thought signatures 是模型内部思考过程的加密表示；在 Gemini 3 系列的函数调用里，如果上一步响应里带了 thought signature，下一步要原样带回，否则可能会报 4xx 校验错误。[Google AI for Developers, Thought Signatures, 2026]

3.2.4 Vercel：不是工具越多越强，而是常常越少越强

视频里非常值得记的一条经验来自 Vercel：

他们删掉了 80% 的工具，Agent 反而更好用了。

这条经验的工程含义很强：

• 太多工具会增加选择空间
• 选择空间越大，越容易出现冗余调用、路径漂移、无意义试探
• 对 Agent 来说，“少而清晰”的工具集，往往比“全而杂”的工具集更有效

📡 扩展
Vercel 官方博客明确写到：他们把 agent 简化到一个“文件系统 + bash 命令”的结构后，成功率从 80% 提升到 100%，同时步骤更少、token 更少、响应更快。[Vercel, We removed 80% of our agent’s tools, 2025-12-22]

3.2.5 Stripe：生产环境不是“补工具”，而是“给 Agent 一个像工程师一样的工作环境”

视频提到 Stripe 的启发点，可以抽象成一句话：

Agent 不是只需要“一个模型 + 一堆 API”，而是需要一个接近真实工程师工作台的环境。

包括但不限于：

• 隔离运行环境
• 预热好的 dev box / sandbox
• 真实内部工具入口
• 明确的权限边界
• 与生产隔离
• 可追踪、可回滚、可审计

这说明 Harness 的本质之一，不只是工具接入，而是工作环境设计。

3.3 一个成熟 Harness 应该包含哪些模块

结合视频内容，可以把一个成熟的 Harness 归纳为六大模块：

flowchart TD
    A([成熟 Harness]) --> B[① 上下文工程与知识管理]
    A --> C[② 工具编排与权限设计]
    A --> D[③ 验证机制与硬约束]
    A --> E[④ 状态管理与记忆持续性]
    A --> F[⑤ 可观测性与反馈闭环]
    A --> G[⑥ 人类接管与生命周期管理]

    B ~~~ C
    C ~~~ D
    D ~~~ E
    E ~~~ F
    F ~~~ G

    style A fill:#e8f5e9,stroke:#43a047,stroke-width:2px
    style B fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style C fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    style D fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px
    style E fill:#ede7f6,stroke:#5e35b1,stroke-width:2px
    style F fill:#fff8e1,stroke:#f9a825,stroke-width:2px
    style G fill:#ffebee,stroke:#e53935,stroke-width:2px

📡 扩展
Google ADK 官方文档把 ADK 定义为一个 build / manage / evaluate / deploy agent 的工具包，并在核心概念中提供了 workflow agents、parallel agents、loop agents 等原语；Google 官方 Agents 文档也明确写到，需要 orchestration framework 来处理 memory、planning loop 和复杂 tool chaining。[ADK 官方文档, 2026；Google AI for Developers, Agents Overview, 2026-03-19]

4. 实践案例

4.1 典型的生产级 Agent 执行闭环

sequenceDiagram
    participant User as 用户
    participant Planner as 规划层
    participant Runner as Runtime / Harness
    participant Tools as 工具集
    participant Eval as 验证层
    participant Human as 人类审批

    User->>Planner: 提交目标
    Planner->>Runner: 输出子任务 / 验收标准
    Runner->>Tools: 调工具、查文档、执行动作
    Tools-->>Runner: 返回结果
    Runner->>Eval: 提交结果做验证
    Eval-->>Runner: 通过 / 缺陷 / 风险
    Runner-->>Human: 关键节点请求确认
    Human->>Runner: 批准 / 驳回 / 修改
    Runner->>User: 返回最终结果 / 中间状态

这个闭环和“单轮问答”的本质区别

4.2 一个最小可落地的 Harness 升级路径

如果你现在的 Agent 还停留在“Prompt + 几个工具”的层面，比较务实的升级方式是：

阶段 1：先把可重复错误固化成规则

• 在仓库根目录维护一个简短的 AGENTS.md
• 每次 Agent 犯重复错，就补一条规则
• 不求完美，只求减少同类翻车

阶段 2：补确定性约束

• 加 lint
• 加结构测试
• 加 pre-commit
• 加最基础的可观测性（日志 / trace）

阶段 3：补运行时治理

• 增加 progress file
• 增加 feature list / task contracts
• 引入 evaluator 或独立 review agent
• 在关键动作前要求 human approval

flowchart TD
    A([当前状态<br>Prompt + Tools]) --> B[阶段 1<br>规则文件化]
    B --> C[阶段 2<br>确定性约束]
    C --> D[阶段 3<br>运行时治理]
    D ==> E([更接近生产级 Agent])

    style A fill:#ffebee,stroke:#e53935,stroke-width:2px
    style B fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
    style C fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px
    style D fill:#ede7f6,stroke:#5e35b1,stroke-width:2px
    style E fill:#e8f5e9,stroke:#43a047,stroke-width:2px

5. 核心结论

5.1 一句话总结

Prompt 决定模型怎么说，Context 决定模型看到什么，Harness 决定模型在什么机制里干活，以及是否真的能把活干成。

5.2 这期视频最值得带走的 8 个点

1. Harness Engineering 的关注点是 Runtime，而不是单条 Prompt。
2. 长任务的本质难点是跨 session 失忆与状态漂移。
3. 生成与评估分离，是当前最值得重视的结构模式之一。
4. 工具不是越多越好，很多时候越少越稳。
5. 知识必须放在 Agent 可读、可执行、可版本化的位置。
6. 验证层必须尽量确定化，不能只靠模型“自觉”。
7. Harness 必须和模型能力边界匹配，模型变强后要敢于删护栏。
8. Harness 既是性能放大器，也可能是风险放大器。

5.3 我的整理结论

从工程实践角度看，Harness Engineering 不是一个完全全新的学科，它更像是：

• 软件工程里的 test harness
• DevOps 的 CI/CD 与可观测性
• 安全工程里的权限与沙箱
• 分布式系统里的状态恢复与幂等设计

这些成熟方法，在 LLM / Agent 这个“概率性系统” 上被重新组合、重新权重、重新命名。
所以它真正的新意，不在于组件“从未存在”，而在于：

它把“如何让不确定模型在确定业务里可靠干活”这件事，抬升成了一门独立的系统设计问题。

附：本次字幕中的关键术语校正

参考资料（按本文实际采用）

1. OpenAI — Harness engineering: leveraging Codex in an agent-first world（2026-02-11）
2. Anthropic — Effective harnesses for long-running agents（2025-11-26）
3. Anthropic — Harness design for long-running application development（2026-03-24）
4. Anthropic — Eval awareness in Claude Opus 4.6’s BrowseComp performance（2026-03-06）
5. Google DeepMind — Accelerating Mathematical and Scientific Discovery with Gemini Deep Think（2026-02-11）
6. Google AI for Developers — Agents Overview（2026-03-19）
7. Google AI for Developers — Thought Signatures（2026）
8. Google ADK 官方文档（2026）
9. Vercel — We removed 80% of our agent’s tools（2025-12-22）

适合继续长大的 Obsidian 双链建议

• Prompt Engineering
• Context Engineering
• Harness Engineering
• Agent Runtime
• Agent Observability
• Tool Orchestration
• State Persistence
• Human-in-the-loop
• Claude Agent SDK
• Codex
• Google ADK
• Thought Signatures
• Playwright MCP