第一个 Agent 从 Pi 开始

📌 一句话摘要

本文以 Pi 项目为切入点，深入剖析了构建 AI Agent 所需的底层工程能力，强调 Agent 的核心在于一套可投影、可授权、可恢复、可观测的运行时秩序，而非依赖模型智能本身。

📝 详细摘要

本文以开源项目 Pi 为样本，系统性地阐述了构建一个最小化 coding agent 所需的工程实践。文章指出，Agent 的核心并非模型智能，而是一套名为 Harness 的工程系统，它负责让模型能观察环境、采取动作、被限制、被记录、失败后能继续，并最终用证据判断任务完成。作者详细拆解了 Pi 的分层架构（模型适配、agent loop、工具、session、上下文），并深入讨论了工具合约、上下文装配、Session 作为行动账本、Compaction 的连续性机制、权限设计、完成判断等关键环节。文章进一步以 OpenClaw 项目为例，展示了从内核到产品控制面的扩展，并总结了五种可复用的工程模式。最终，作者给出了从零搭建 Agent 的渐进式路线图，并指出 Harness 作为运行时秩序，会随着模型能力增强而变得更加重要。

💡 主要观点

1. Agent 的核心是 Harness 工程，而非模型智能。 Harness 是让 Agent 趋近目标的一切工程化手段，包括让模型观察环境、采取动作、被限制、被记录、失败后修复，并用证据判断完成。模型越强，这套外部秩序越不能省。
2. 工具是合约，不是函数。 工具设计需守住输入有 schema、输出适合模型消费、大输出要截断、截断后能续读、有副作用的工具返回 diff、失败也回到 loop 等原则，避免 Agent 变成不可控的 API 调用器。
3. Context 要按轮装配，区分发生过和模型该看到。 Agent 中的发生过和模型该看到不是同一个集合。需要将状态拆分为给模型看的投影、给用户界面看的、只给审计和恢复看的，并通过 transformContext 和 convertToLlm 进行治理。
4. Session 是行动账本，Compaction 是连续性机制。 Session 需记录完整的行动轨迹（事件日志），而 Compaction 则通过摘要压缩旧上下文，保留完整历史的同时，让模型聚焦当前任务。两者结合，实现可恢复、可审计的 Agent 系统。
5. 权限要进入运行时管线，而非仅依赖 Prompt。 通过 beforeToolCall/afterToolCall 等钩子，在运行时根据环境、用户、通道等元数据动态计算有效工具策略，比在 prompt 中提醒模型不要做危险操作更可靠。

💬 文章金句

• 凡是让 Agent 趋近于目标的一切工程化手段，都是 harness（意图 → harness 工程 → 趋近目标）。
• Agent 里的发生过和模型该看到不是同一个集合。
• 把 compaction 当省钱技巧，会低估它对任务连续性的作用。
• Agent 工程不急着把模型包装得更像人。关键在于，把模型的判断放进一套可投影、可授权、可恢复、可观测的系统里。
• 弱模型需要 harness 帮它做事，强模型更需要 harness 确保它做事不越界、可复盘、能交付。

📊 文章信息

阅读完整文章