第 35 章 · Building on the Harness — pi

从“学模式”到“造东西”

恭喜你走到这里。全书从那个查竞品价格的卖家开始，一路陪着他：给 Agent 装工具查销量、接 MCP 复用现成能力、用技能封装竞品分析流程、拿扩展加合规门、让多个研究员并行调研再综合成报告、把成本压下来、把它挪到后台自己跑……三十一章，模式一个个铺开。

现在是把它们合起来的时候。这一章不引入任何新概念，只回答一个问题：

当你要真正做一个属于自己的、生产可用的 Agent 时，该怎么把这些模式组装起来？

答案就藏在本书的标题里：Building on the Harness（在宿主之上构建）。

回到书名——《AI Agent：如何构建企业级 Harness 智能体》。走到这里你应该能体会到：所谓“企业级 Harness 智能体”，从来不是某一个模式、某一段代码，而是把前面三十一章的模式，全部落到同一个 Harness 之上、拼成一个达到企业标准的整体。这一章，就是那次拼装。

核心心法：不要造 harness，要在 harness 上构建

这是全书最重要的一条经验，值得单独拎出来：

你几乎永远不该从零造一个 agent harness。那些 ReAct 循环、工具调用、上下文管理、会话持久化、多 provider 适配、compaction……都是又难又琐碎、又不产生业务差异的工程。一个成熟的 harness（如 pi）已经把它们做好了。你的价值，在于在它之上构建你独有的东西。

那“你独有的东西”是什么？回顾全书，pi 给了你四个清晰的扩展面（extension surfaces）——这四个面，就是本章要贯穿到底的主线：

  1. 工具（Tools，第 4 章）：接入你的业务系统——内部 API、数据库、专有服务。
  2. 技能（Skills，第 7 章）：封装你的领域工作流——“我们公司怎么做竞品分析”“怎么写合规报告”。
  3. 扩展 / Hooks（Extensions，第 8 章）：注入你的规则与控制——权限门、审计、检查点、自定义压缩。
  4. 编排（Orchestration，Part 5）：组合你的多 Agent 协作——研究、辩论、流水线。

你独有的业务价值，通过这四个面注入 harness；通用的苦活，harness 替你扛。 这就是心法。剩下的，是看它怎么落地。

四个扩展面，各注入什么

把四个面拆开看，每个面回答一个不同的问题：

  • 工具回答“Agent 能碰到你的哪些系统”。查自家销售库、抓竞品页、下单改价——都是工具。通用能力（网页搜索、文件系统）接 MCP（第 5 章）就行，别自己造。
  • 技能回答“Agent 按你的方法论怎么干活”。同样是“做竞品分析”，你公司有自己的口径：看哪些维度、按什么顺序、报告长什么样。把它写进 SKILL.md，Agent 就按你的流程走，而不是每次即兴发挥。
  • 扩展 / Hooks 回答“Agent 被你的规则约束到什么程度”。在生命周期点（beforeToolCall、afterModelCall、beforeCompact……）挂上你的逻辑：敏感数据不许外传、每步记账、危险操作要确认、上下文按你的方式压缩。
  • 编排回答“多个 Agent 怎么分工协作”。一个研究员扛不动全网竞品，就让多个并行调研（发散）、再由综合 Agent 收敛成一份报告（第 22 章）。

四个面从“能碰什么”到“怎么干”“受什么约束”“怎么协作”，正好覆盖了一个 Agent 的全部业务个性。而这一切之下的通用运行时，一行都不用你写。

用 pi 实现：一次完整的组装

把贯穿全书的跨境电商 Research Agent，落成一个真正构建在 pi 之上的产品。注意这段代码只写“你独有的部分”，四个扩展面一一对应：

// 在 pi 之上构建一个跨境电商竞品研究 Agent —— 只写你独有的部分
export default function competitorResearchAgent(pi) {
  // 面 1 · 工具（第 4 章）：接入你的业务数据
  pi.registerTool({ name: "query_our_sales",       /* 查自家销售库（只读） */ });
  pi.registerTool({ name: "fetch_competitor_page", /* 抓竞品页面 */ });
  // 通用检索接 MCP（第 5 章），不自己造轮子

  // 面 2 · 技能（第 7 章）：封装你的领域方法论
  //   .pi/skills/competitor-analysis/SKILL.md
  //   —— 写清"我们公司做竞品分析的标准流程：看哪些维度、报告什么格式"

  // 面 3 · 扩展/Hooks（第 8 章）：注入规则与控制
  pi.on("beforeToolCall", guardSensitiveData);  // 数据合规门（第 27 章）
  pi.on("afterModelCall", trackBudget);         // 预算控制（第 26 章）

  // 面 4 · 编排（Part 5）：多 Agent 分工
  //   研究员并行调研各竞品（第 22 章）→ 综合 Agent 汇成报告
}

看这段代码有多“薄”——它只写了业务独有的部分，却免费继承了 pi 的一切：ReAct 循环、上下文压缩、会话持久化、多 provider 与分层、RPC 远程驱动、可观测性……它白天能在终端交互调试，晚上挂上 cron 就成了后台 Agent（第 33 章）。这就是“在 harness 上构建”的杠杆——薄薄一层业务代码，撬动一整套成熟运行时。

示例仓库应该长什么样

如果把这章落成一个可跟做的 examples/harness-research-agent/，最小结构可以这样设计：

examples/harness-research-agent/
  README.md                    # 跑起来的最短路径
  .pi/
    skills/competitor-analysis/SKILL.md
    extensions/guard-and-budget.ts
  src/
    tools/query-our-sales.ts
    tools/search-knowledge.ts
    tools/fetch-competitor-page.ts
    workflows/research-synthesis.ts
  evals/
    cases/rag-compliance.json
    cases/competitor-summary.json
    replay.ts
  ops/
    launch-checklist.md
    env.example

每个目录对应全书一条主线：

  • .pi/skills/ 对应第 7 章，把领域方法论写成可加载技能。
  • .pi/extensions/ 对应第 7、25、26 章，放危险操作确认、预算追踪和策略门。
  • src/tools/ 对应第 3、4、10 章，接业务系统、MCP 和 RAG。
  • src/workflows/ 对应 Part 5、6，组织 Research-Synthesis。
  • evals/ 对应附录 D，把真实会话固化成回归集。
  • ops/ 对应附录 E，记录上线参数、密钥、回滚和运维清单。

这样读者不是“读完一章感觉懂了”，而是能沿着同一个 Research Agent，把工具、RAG、技能、Hooks、编排、评测和上线串起来。

动手看看

打开你自己关心的一个业务场景，别急着写代码，先在纸上按四个扩展面填空：工具要接哪几个系统？技能要沉淀哪几条你独有的方法论？扩展要挂哪几道规则门？编排要不要多 Agent，怎么分工？填完你会发现——绝大部分格子都是你的业务知识，几乎没有一格是“造 harness”。

再翻一遍 pi 的扩展与技能目录（.pi/extensions/、.pi/skills/），对照上面的组装代码，看真实的注册点长什么样。你会更笃定一件事：你要写的，从来不是循环和上下文管理，而是只有你懂的那部分。

从原型到生产的检查清单

把这个 Agent 从“能跑”推到“能上生产”，用全书后半部分逐项过一遍：

  • [ ] 上下文：长任务会压缩吗？关键信息保得住吗？（第 9 章）
  • [ ] 记忆：需要记住用户/项目的偏好吗？（第 10 章）
  • [ ] 知识库/RAG：检索结果带来源、分数和版本吗？回答会引用依据吗？（第 11 章）
  • [ ] 状态：会话、任务进度和后台 run 可寻址、可恢复吗？（第 11、23、32 章）
  • [ ] 成本：设了预算上限吗？简单步骤用便宜模型了吗？（第 25、33 章）
  • [ ] 可观测：会话都持久化了吗？成本能归因吗？（第 25 章）
  • [ ] 评测：核心任务集、高风险样本、RAG 命中回归跑过吗？（附录 D）
  • [ ] 安全/HITL：不可信操作隔离了吗？危险操作有确认门或人工审批吗？（第 7、26、27 章）
  • [ ] 治理：敏感数据访问有策略和审计吗？（第 27 章）
  • [ ] 部署/运维：要 Web/后台驱动吗？多租户吗？有回滚和降级开关吗？（第 23、28、32 章，附录 E）

走完这张清单，你手上的竞品研究 Agent 就从一段“能跑的原型”变成了一个真正的生产级产品。

实战中的几个坑

坑一：忍不住从零造 harness。

  • 现象：嫌现成 harness“不够贴合”，自己动手写循环、写上下文管理、写会话持久化。
  • 原因：低估了这些通用工程的复杂度，也误以为它们是你的业务差异所在。
  • 对策：把力气全押在四个扩展面上，通用运行时交给成熟 harness——它们不产生业务价值，只消耗你的时间。

坑二：把业务逻辑焊死在 harness 内部。

  • 现象：改了 pi 的核心代码来塞业务逻辑，harness 一升级就冲突、难以维护。
  • 原因：没走扩展面，而是侵入式改动运行时。
  • 对策：业务只从工具/技能/扩展/编排四个面注入，和 harness 内核解耦，升级无痛。

坑三：原型直接上生产，跳过检查清单。

  • 现象：demo 跑得漂亮就上线，结果长任务爆上下文、成本失控、敏感数据外泄。
  • 原因：把“能跑”当成“能上生产”，漏了成本、安全、可观测、治理。
  • 对策：上线前逐项走完上面的检查清单，一项都别跳。

坑四：把 pi 的 API 当成要学的重点。

  • 现象：死记某个函数签名，pi 一更新就慌，觉得白学了。
  • 原因：学的是具体 API 而非背后的模式。
  • 对策：记模式、忘 API——registerTool 明天可能改名，但“工具是描述+请求+执行”永远不变。

对比：四家框架 vs pi 的定位差异

全书每章都拿这四家框架和 pi 对照。收尾时把它们放在一起看，差别不在“谁更强”，而在定位与心智模型——你在哪一层思考、被框住多少、能扩展多少。

框架定位与心智模型你在它之上做什么
LangGraph把 Agent 建模成状态图，控制流最显式、最精细，也最啰嗦画一张流程图，让 Agent 沿图跑——适合精确控制复杂流程
CrewAI核心是团队 + 角色 + 任务，抽象层次高，多 Agent 上手直观组建一个有角色分工的团队
PydanticAI主打类型安全与结构化输出，像写普通 Python 一样写 Agent用类型系统约束 Agent 的输入输出
Agno电池全含的应用层框架，Agent/Team/Workflow/Memory 一应俱全开箱即用地拼装一个 Agent 应用
piharness / 运行时视角——你在它之上构建，而非被它框住从四个扩展面注入业务，继承整套运行时

它们底层跑的都是同一套模式（ReAct、工具与技能、上下文工程、多 Agent 发散收敛、成本分层），差别只在抽象层次和心智模型。理解了模式，你在哪家框架里都能很快上手——这正是本书的用意。

最后：模式会留下，框架会变

本书从头到尾用 pi 做参考，但请记住前言里的话——我们学的是模式，不是 pi 的 API。

pi 会更新，它的 orchestrator 还是实验性的，某些接口明天可能就变了。但你在本书学到的东西——ReAct 循环、工具与技能的分工、上下文工程、多 Agent 的发散与收敛、成本分层、安全隔离——这些不会过时。

哪天你换用 Claude Agent SDK、LangGraph、或某个还没诞生的 harness，你会发现：你早就懂它了。因为你理解的是 Agent 系统背后那套不变的设计模式，而任何 harness，都只是这些模式的一种具体实现。这，就是“Building on the Harness”最深的一层含义——先懂模式，再用任何工具。

小结

  1. 核心心法：不造 harness，在其之上构建——通用的循环、上下文、持久化交给成熟 harness，你的价值在业务独有的那部分。
  2. pi 给你四个扩展面注入价值：工具（业务系统）、技能（领域工作流）、扩展/Hooks（规则控制）、编排（多 Agent）——它们覆盖一个 Agent 的全部业务个性。
  3. 一个垂直 Agent 的代码可以很薄——只写独有部分，免费继承 harness 的 ReAct 循环、压缩、持久化、多 provider、RPC、可观测性。
  4. 推荐用一个示例仓库把全书串起来：工具、RAG、技能、Hooks、编排、评测和运维各有目录，而不是散落在章节里。
  5. 用“原型到生产检查清单”把 Agent 推上生产：上下文、记忆、RAG、状态、成本、可观测、评测、安全、治理、部署，一项都别跳。
  6. 最重要的：模式会留下，框架会变——你学的是不变的设计模式，能迁移到任何 harness，包括还没诞生的那个。

到这里，正文结束了。感谢你读完这趟从单体到生产级的旅程——从那个想查竞品价格的卖家，到一个构建在成熟 harness 之上、能上生产的跨境电商 Research Agent。接下来的附录，是你日后随手查阅的工具箱。