实现篇第1章 白纸与边界——Scope ​

小A与老Z用橙色细绳围出有限的工作区,将文件夹、终端和模型球留在线内,网络球与额外机器人则置于线外。

本章导读: 这一步不写一行逻辑代码,只做一件事:把“做”和“不做”同时写进清单。你会建立 examples/mini-agent 的骨架、FakeClient 测试替身,以及一份明确的非目标列表(MCP、Skill、多 Agent、retry 都不做)。

实现篇开工那天,小A抱着一个空目录来找老Z,里面只躺着 package.json 和一张白纸。他把 pi-mono 的源码目录截图摆在旁边,一脸豪迈:“我打算照着它写一个自己的 Agent。”

老Z看了一眼,没有接话,先问了个问题:“你打算写多大?”

“多大?”小A愣了,“就……把 pi 的功能都实现一遍?”

“那你这半年都搭不完。”老Z敲了敲桌子,“换个方式:先决定不做什么。实现篇从一个具体场景开始:在受限工作区内,让编码助手读取、写入或执行命令,并把每一步留为可检查消息。咱们结对的第一件事,是把范围写进代码库,而不是先堆功能。”

小A:“那范围到底怎么定?我怕写小了,被人说‘这不算 Agent’。”

“定范围不看‘像不像 Agent’,看每一行承诺能不能验证。”老Z把一张表推到小A面前:

验收项 当前证据 非目标
模型事件与工具回路 test/agent.test.ts 多 Provider、自动重试
工作区工具 src/tools.ts OS 沙箱、跨文件事务
JSONL 与字符预算 src/session.ts、src/context.ts 摘要压缩、长期记忆
一次命令行入口 src/main.ts、src/cli.ts 完整 REPL、TUI、RPC

“你看,每个功能旁边都写着它不做什么。”老Z说,“范围交付的是两样东西:可验证的承诺,和明确的非目标。”

“可验证承诺”这四个字让小A停住了:“‘能验证’怎么算?谁来验证?”

“两条路。”老Z说,“一条是测试文件能证明的:agent.test.ts 覆盖模型事件与工具回路,tools.ts 的行为由工具测试钉住;另一条是命令能复现的:npm test、npm run typecheck、npm start -- "任务",每一个都有确定输出。所谓‘可验证’,是一个刚接手的人照着文档跑一遍,能亲眼看到承诺兑现。反过来,凡是‘只有作者知道跑没跑通’的东西,比如‘多 Provider 支持’,就该待在非目标栏里,不进承诺栏。”

小A把范围文档往下翻,念出其中一条:“模型输出、文件内容和工具参数,都视为不可信……”

“对。路径检查只能形成路径边界,不能阻止 TOCTOU,也不能限制 shell 已拥有的网络、进程或凭据权限。”老Z说,“这一条决定后面每一章怎么写代码。”

工作场景与用户故事 ​

小A:“那我到底在造什么?用户拿它干嘛?”

老Z:“先把用户故事讲清楚:”

用户故事

用户说“把配置文件改掉并跑检查”,这个需求看起来很小,为什么不直接让模型执行 shell?

因为用户真正委托的是一条可检查的工作流:模型提出动作,程序验证边界,执行器返回结果,下一轮再根据事实决定。用户不是把机器的全部权限交给模型,而是要求它在当前工作区协助完成一件事。

小A:“正常流程和失败流程,都得有?”

“都有,失败故事同样是产品。”老Z说,“这个参考实现的正常故事是:用户给出文本任务;runAgent() 将任务写入消息;fake 或生产客户端返回文本或工具请求;工具在工作区内执行;结果再次进入消息。失败故事也一样:缺少模型配置、工具参数不合法、路径逃逸、审批拒绝、空模型响应、预算不足,每一种都必须留下清楚结果或异常,不能伪装成完成。”

小A把“失败故事同样是产品”记了下来,又问:“每个失败都要写成用户故事吗?会不会太啰嗦?”

“不用写成故事,但范围里得给每个失败一个位置。”老Z说,“你数一数刚才那一串:缺少模型配置是启动期失败,由 main 抛错;工具参数不合法和路径逃逸是执行期失败,由工具返回 isError 结果;审批拒绝由 approval hook 决定;空模型响应由 loop 抛异常;预算不足由 trimContext 抛错。每个失败都有归属层,没有一个是‘到时候再说’。范围文档的任务,是确认每一种失败都有人负责:谁抛、抛给谁、记录成什么样。这张归属表在,后面每一章的代码才有验收对象。”

“预算不足为什么抛错?截断一下不行吗?”小A追问。

“trimContext 的裁剪单位是‘最小的自洽消息组’,一组带结果的工具调用。预算小到连一组都装不下,裁剪就无从谈起,这时候静默返回空数组会毒化整个上下文。”老Z说,“context.test.ts 里专门有一条 assert.throws(() => trimContext(messages, 1), /smallest consistent/),钉住的就是这个语义。”

目录是架构图 ​

小A打开编辑器,准备从空目录开始搭。老Z按住他的手:“先别急着写文件。目录先照这个摆:”

下面的目录树是核心文件节选,不是最终完整清单。src 下实际有 9 个 TypeScript 文件,test 下有 8 个测试文件。

text
examples/mini-agent/
  src/types.ts          契约
  src/model-client.ts   Provider 适配器
  src/agent.ts          控制循环
  src/tools.ts          工作区能力
  src/session.ts        JSONL 记录
  src/context.ts        字符预算
  test/agent.test.ts    fake 集成测试

小A:“就这么几个文件?”

“够了。重点是依赖方向:从 types.ts 向外,模型客户端和工具实现契约,Agent 组合它们,测试再替换模型客户端。这样测试不需要网络,也能覆盖从模型‘提出调用’到文件被写入的完整控制流。”

老Z画了一张依赖方向的图:

text
types.ts(契约,不依赖任何人)
    ▲          ▲
model-client.ts   tools.ts(实现契约)
    ▲          ▲
      agent.ts(组合两者)
          ▲
      test/(替换 model-client 为 fake)

“注意,这张图里 agent.ts 是唯一‘知道两边’的文件。”老Z说,“它 import 契约类型,调用 client.stream(),也调用 tool.execute(),两侧依赖全是接口。test/ 站在最顶上,替换的是 model-client.ts 那一侧,tools.ts 这一侧保持真实。为什么不全 fake?工具是副作用边界,测试恰恰要看真实的文件读写有没有被正确约束。‘模型可替、工具真实’,为的就是让每个文件都待在它该被测试的位置。”

“session.ts 和 context.ts 呢?图里没画。”小A指着目录清单。

“它们不在主链路上,是 agent 的附加能力。”老Z说,“agent.ts 在循环外加载会话、在请求前裁剪上下文,都没有动‘模型提出、宿主执行’这个主干,只是改了发给模型的 messages 长什么样。这张目录图的完整读法是:主干三条线,契约、客户端、工具;agent 是组合点;session 和 context 是组合点上的两个可选插件。”

本章其余小节为付费内容

登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。