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

本章导读: 这一步不写一行逻辑代码,只做一件事:把“做”和“不做”同时写进清单。你会建立
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 个测试文件。
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画了一张依赖方向的图:
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?登录即解锁完整章节。