运行本书的示例
拿到本书所运行的代码,安装锁定的 Pi 发布版,验证章节与代码一致,并弄清由此得到的证据能证明什么、又不能证明什么。
本书中的每一个 typescript 代码块都带有一个标记,指明它取自哪个文件;而一旦某一章与它的源文件产生了漂移,一个脚本就会让构建失败。这就是本书方法背后的机制:你读到的代码是真正运行过的代码,运行的发布版正是文本当初所对照检查过的那一个。
这一页讲的就是怎么把它拿到手。
获取代码
示例存放在本书的仓库里,位于 examples/ 目录中:
ernanhughes/pi → examples/
克隆它,然后在那个目录里安装:
git clone https://github.com/ernanhughes/pi.git
cd pi/examples
npm install
npm run verify-examples
在锁定发布版上的预期结果:
> tsc -p .
(no output — clean)
checked 65 embedded block(s); all match their source
tests 279
pass 279
fail 0
typecheck 什么都不打印,那就是成功。那三个数字来自三个不同的阶段——check-embedded 报告的是代码块的同步情况,而 tests/pass/fail 那几行来自 node --test——所以 65 个代码块与 277 个测试这两个数字本来就不一样。
**仓库尚未公开。**在写作本书时,
github.com/ernanhughes/pi是私有的,所以上面那条克隆命令只对有访问权限的人有效。如果你读的是本书的某个出版副本,而克隆以 404 失败,那就是原因——不是命令里有个笔误。这些示例同时也作为本书自身的源码发布:不经过上面任何一步,每一章里的每一个typescript代码块也都可以完整读到。
从某个特定修订开始
本书的论断描述的是一个发布版,而示例锁定在它上面。如果你想要的是本文撰写时所对照的那个修订,而不是 main 现在的样子:
git clone https://github.com/ernanhughes/pi.git
cd pi
git checkout 54e13e8 # the revision this page describes
cd examples
npm install
npm run verify-examples
当某个检查失败时,这样做是值得的,因为它能把"本书错了"和"仓库已经往前走了一步"区分开。main 上的一个新提交并不是 Pi 行为的一次改变,而示例也不会随 Pi 漂移——它们被 package.json 锁定在 1.0.4 上,无论你签出的是本书的哪一个修订。
简短版本
如果你已经有这个仓库,那么全部的准备工作就是这些:
cd examples
npm install
npm run verify-examples
接下来讲的是每一部分各自是什么意思,以及那些不那么显眼的前置条件。
开始之前
| 需求 | 为什么需要 | 怎么检查 |
|---|---|---|
| Node.js 22.19 或更高版本 | Pi 所要求的版本,也是不需要构建步骤就能运行 TypeScript 的版本 | node --version |
| npm | 用来安装那些锁定的包 | npm --version |
一个 POSIX shell(bash) |
有两个测试会执行真正的 shell 脚本 | bash --version |
| Git | 第 14 章的检查脚本用 git rev-parse 找到仓库 |
git --version |
Windows 上的 shell
这是会绊住人们的那一个前置条件。在 Windows 上,你 PATH 上的 bash 通常是 C:\WINDOWS\system32\bash.exe——WSL 的启动器。在没有安装任何发行版的情况下,它会以非零码退出,并打印 execvpe(/bin/bash) failed,这读起来就像一个故意失败的 shell 脚本。ch14-skill-files/ 里有两个测试会仅因为这个原因而失败,而书和你的检出都没有任何问题。
测试骨架会先找 Git Bash(C:\Program Files\Git\bin\bash.exe),并优先使用它,而不是那个启动器。如果 Git Bash 和一个可用的 WSL 都不存在,那两个测试会带着原因被跳过,而不是失败,所以一次全绿的运行会告诉你它实际覆盖了什么。
Git
这里不是为了做版本控制,而是因为第 14 章的检查脚本用 git rev-parse --show-toplevel 来发现它的目标仓库。第 14 章会解释为什么它选择去问,而不是去数父目录的层数。
安装,以及版本为什么被锁定
cd examples
npm install # or `npm ci`, for a reproducible tree
package.json 把三个 Pi 包全部锁定在本书所描述的那个确切发布版上:
"@earendil-works/pi-agent-core": "1.0.4",
"@earendil-works/pi-ai": "1.0.4",
"@earendil-works/pi-coding-agent": "1.0.4"
这是刻意的,而它值得你去理解,而不是直接接受。本书中的每一条行为论断都是对着 1.0.4 检查过的。如果你安装的是另一个发布版,测试套件可能仍然通过,而正文描述的已不再是你正在运行的东西——而这种不匹配,正是第 40 章的证据纪律所要抓住的。第 2 章的安装一节,是说明这个锁定如何与受管理的安装程序以及传递依赖相关联的参考。
verify-examples 做什么
npm run verify-examples
三个阶段,按顺序执行,每一个回答一个不同的问题。在锁定发布版上,预期的最终状态是:typecheck 干净(没有输出)、65 个代码块全部匹配、279 个测试、0 个失败。
1. typecheck
对整个套件跑 tsc。这会抓住一个不再与锁定的类型声明匹配的示例——而在 Pi 的文档文字与它的类型不一致的地方,那些声明才是权威(第 26 章记录了这样一处不一致),所以正是这个阶段,让本书诚实地对待它自己的依据规则。
2. check-embedded
把全部 65 个内嵌的 TypeScript 代码块与它们的源文件逐一比对。
稿件中的每一个代码块前面都有一个 HTML 注释,指明它的来源,以及它属于哪一种代码块:
| 标记 | 含义 | 检查什么 |
|---|---|---|
<!-- example: path --> |
这个代码块是一个完整的文件 | 代码块与文件完全相同 |
<!-- excerpt: path --> |
这个代码块是一个文件的一部分 | 每一行都出现,且顺序一致 |
<!-- declaration: path --> |
来自 Pi 的一条类型声明 | 与 excerpt 相同,另外还要与真正导出的类型相等 |
<!-- documented-not-run --> |
真实的 Pi API 代码,但没有被运行过 | 什么都不检查;正文必须说明这一点 |
<!-- illustrative --> |
一个并不打算运行的片段 | 什么都不检查 |
一个没有标记的代码块会在这个检查中失败,而这就是为什么实际存在的那两种——documented-not-run 和 illustrative——都是诚实的声明,而不是占位符。
如果你修改了某一章所内嵌的某个示例,就运行 npm run check-embedded -- --fix,从源代码重新同步那一章。
3. test
通过 node --test 运行整个套件。在锁定发布版上,它是全绿的。
这个结果证明了什么,以及它不证明什么
这是值得读两遍的部分,因为一套通过的测试套件最常在这里被过度声明。
测试套件在大多数情况下用一个脚本化的 provider——来自 pi-ai 的 fauxProvider——来替换真实模型。这让它免费、快速且确定。这也让其中的每一个案例都成了某人事先预料到的一个案例:
使用 faux provider 的测试表明一个模型周围的代码是正确的。它们从来不是关于一个真实模型如何行为的证据。
一个脚本化的 provider 会照你说的做,包括拒绝、跑题、调用错误的工具,或者提交一个格式错乱的结果——这些都值得出现在一个测试套件里。它做不到的是让你吃惊。所以一次全绿的运行,是关于你如何处理一个响应的强证据;而对于一个模型是否会产出它,则完全没有证据。第 41 章讲的是测试的三个层级,特别是为什么第三级不能替代第一级。
还有两个限制;凡是某个结果可能被误认为比实际更多的地方,本书都会把它们说出来:
- **这里没有任何东西是对着一个真实模型运行过的。**证据账本里没有任何一条被接受的真实模型结果。有一次尝试被保留了下来,而它在模型看到提示词之前就被 provider 拒绝了;它被明确记录为不是一次结果。
- **测试套件有一小部分会运行真实的可执行文件。**第 31、32、33 和 35 章通过测试骨架把 Pi 生成为一个子进程,而它通过包自己的
bin映射解析那个二进制文件——也就是npm exec pi所运行的那个打包构建。有一个测试会对那个映射做出断言,所以这份证据不可能悄悄降级成"dist/里的某个模块"。即便如此,模型仍然是脚本化的。
证据账本
npm run evidence # rewrites examples/EVIDENCE.md and evidence.json
npm run sync-metadata # writes executable_evidence into metadata/*-chapter.yaml
在改了一批之后把两条都跑一遍,而不是每改一处就跑一遍。每一行都带着两个字段,它们是这套方法的机器可读形式:
| 字段 | 取值 | 它告诉你什么 |
|---|---|---|
claim_class |
DOCUMENTED、OBSERVED、PROPOSED |
这是谁的论断:Pi 的文档、被运行过的某个东西,还是本书自己的模式 |
evidence_scope |
declarations、in_process_runtime、shipped_binary、real_model |
这次运行到达了多远 |
读者可以筛出 PROPOSED,从而确切知道本书的哪些部分是作者的判断,而不是 Pi 的契约。
有一件事要预先想到:**账本的行数与测试用例的条数是两个不同的数字,并不相符。**一行是一个论断;一个测试用例是一次执行。多个测试可以锁定同一个论断,一个测试也可以锁定多个论断。
布局
每一个有可运行代码的章有一个目录,目录以该章命名:
examples/
├── README.md 本页的实践版
├── harness/ 共享的基础设施,不属于任何单独一章的代码
├── ch01-agent-core/ 第 1 章
├── ch38-typed-step/ 第 38 章,含它的 14 个测试
├── ch14-skill-files/ 第 14 章,含它的 8 个测试
├── ch40-composition/ 第 40 章
├── evidence.json 机器可读的账本
└── EVIDENCE.md 同一个账本的正文形式
harness/ 值得了解,因为隔离就在那里。每个测试都会拿到一个全新的 PI_CODING_AGENT_DIR 和 PI_OFFLINE=1,所以运行这个测试套件永远不会读取或写入你自己的 Pi 配置,永远不会触达网络,也永远不需要凭据。
只运行一章
node --test ch38-typed-step/step.test.ts
这些示例文件是不需要构建步骤的普通模块——Node 22.19+ 会剥掉类型——所以你也可以读一个,然后用 node path/to/file.ts 直接运行它。
接下来去哪里
- 第 11 章决定一个需求需要哪个机制。如果你是来构建一样东西的,就从那里开始,让它把你送往你需要的那一章。
- 第五部分(第 36 至 41 章)是可运行证据最密集的地方,而且它从一次单独的模型调用,一路构建到一条流水线、再到一套测试策略。
- 第 42 章是这一切不再是关于机制、而是开始关于你的智能体被允许触达什么的地方。