从 Pi 开始理解 Agent Harness 工程

凡是让 Agent 趋近于目标的一切工程化手段，都是 harness。

概述#

本文是对《第一个 Agent 从 Pi 开始》一文的精炼总结。文章从 Pi（一个 minimal terminal coding harness）出发，系统阐述了 Agent Harness 的概念、分层架构、工程模式，以及如何从零搭建一个 coding agent。核心观点是：Agent 工程的关键不在于堆砌概念，而在于构建一套可投影、可授权、可恢复、可观测的运行时秩序。

核心见解#

Harness 的定义#

Harness 不是新名词。它是模型进入真实任务后绕不开的那套工程外壳，负责补齐模型自身不具备的能力：

• 观察环境（读文件、检索代码）
• 采取动作（修改文件、执行命令）
• 动作前被限制（权限、路径检查）
• 动作后被记录（session、event log）
• 失败后能继续修（loop、重试）
• 最后拿证据判断任务完成（completion check）

最小 Agent 分层（以 Pi 为例）#

Provider API
  → agent loop (<a href="/concepts/agent-loop" class="wikilink" data-preview-title="Agent Loop" data-preview-excerpt="定义 Agent Loop 是 Agent Runtime 的心跳：系统把用户目标、上下文和工具结果送入模型，模型产生文本或工具调用，运行时执行工具并把结果继续送回模型，直到有证据可以收尾。 " data-preview-backlinks="1">concepts/agent-loop</a>)
  → coding tools (read/write/edit/bash)
  → session / context / compaction
  → terminal UI / RPC / SDK

关键原则：模型适配是一层，agent loop 是一层，coding tools 是一层，session/context 是一层，UI 只是外围投影。

Agent Loop 的心跳#

最小循环：

1. user goal → build context → call model → stream output
2. detect tool calls → validate args → execute tools → append results
3. call model again → stop with evidence

Agent 工程的第一项基本功，是把 loop 当 runtime 写，不要写成一段模型调用脚本。

工具即合约#

默认四工具：read、write、edit、bash。工具设计至少守住：

• 输入有 schema
• 输出适合模型消费
• 大输出要截断，截断后能续读
• 有副作用的工具返回 diff 或 details
• 工具失败也回到 loop

Context 工程#

Agent 里的"发生过"和"模型该看到"不是同一个集合。需要区分：

• Durable history：完整行动轨迹
• Working context：当前模型可见材料
• Summary：二者之间的压缩视图

Session 是行动账本#

不止是 chat log。每轮的用户输入、模型输出、工具调用、参数、结果、文件修改、命令执行都应该可回放。支持树形分支和恢复。

Compaction 是连续性机制#

把 compaction 当省钱技巧，会低估它对任务连续性的作用。历史保留在 JSONL 中，模型当前看到的是压缩视图，两层都要保留。

工程模式（可复用）#

1. Context 像投影：状态分三类——给模型看的、给 UI 看的、只给审计和恢复看的。
2. Transcript 是账本，working context 是视图：transcript 记录发生过什么，session store 记录现在该往哪里走。
3. 权限进入运行时管线：beforeToolCall / afterToolCall 钩子 + 动态 effective tool policy，比 prompt 提示可靠。
4. Runtime 内核小，产品控制面厚：Pi 负责内核语义，OpenClaw 负责产品控制面。
5. 失败路径和证据链一起设计：工具不假设一切顺利，留有截断、超时、重试和完整轨迹。

实践路线#

1. 先做只读 Agent（read/grep/find/ls）
2. 加精确修改（edit + diff）
3. 加命令执行（bash + timeout）
4. 尽早做 event log
5. 做 context builder 和 compaction
6. 最后再上 skills、extensions、MCP、memory

相关页面#

• Agent Harness 概念
• Pi (pi-mono)
• OpenClaw
• RAG

开放问题#

• Harness 中哪些部分会随着模型能力增强而被"内化"？当前判断是：认知策略层可以被模型吸收，但外部世界边界（文件系统、权限、审计）不会。
• prompt scaffolding 变薄后，runtime harness 是否会变得更硬？文章认为会。