20 借鉴清单与失效条件 哪些能直接抄，哪些抄了会疼，哪些赌注还没结算

先说本章的性质

读完全书，pi 的设计哲学可以压成一句：把防御预算花在能真正守住的关口上，守不住的地方就明说守不住。

这条原则解释了它几乎所有看似矛盾的决定：

它的一致性在于：从不在守不住的地方摆一个看起来像防线的东西。这是本书作者认为 pi 最值得学的一点，也是最容易被误读成「不负责任」的一点。

九条，按可抄性排序

• 生命周期脚本白名单用 包@精确版本 → 理由 的 Map。数据结构强制写理由，升级自动作废旧审查结论。pi 的白名单只有两条，各带一句说明。（16） 几乎无条件适用于任何允许安装脚本的包管理器。成本：一个文件、二十行。
• 贡献判据定成「你能否解释你的代码」，而不是「是否用了 AI」。后者不可验证也不该验证；前者在 review 中天然可测。（18） 适用于所有接受外部贡献的项目。成本：改一句 CONTRIBUTING.md。
• 把 stopReason === "length" 当整批 tool call 的毒丸。流式参数的容错解析会产出「能解析、能过校验、但内容不完整」的调用——这是最难查的一类 bug。（03） 条件：你用流式 tool call 且做了 JSON 容错。参数只在完整消息上一次性解析的实现不存在这个坑。
• 压缩先确定「哪些位置切了不违反协议」，再谈保留多少 token。toolResult 必须紧跟 tool call 是全 provider 通用的硬约束；token 预算只是软目标。（06） 适用于所有做上下文裁剪的 agent。顺序反过来会产出被 provider 拒绝的请求。
• 多后端存储：先写一套一致性测试，再写第二个实现。否则「契约」只是第一个实现的行为。pi 的 memory / JSONL / SQLite 三家共用一份 createSessionBackendConformance。（07） 条件：存储后端可插拔。单后端时它就是普通单测，仍然有价值。
• 规则文件写成「不要 X + 因为 Y + 改为做 Z」三段式。只有「不要 X」的规则会在边缘情况被模型自行放宽。（17） 适用于所有 agent 规则文件。对人类同事反而该用抽象原则——具体清单显得不信任。
• 大重构时让未完成接口抛专有异常，并把「没有任何未完成方法报告看似成功」写成验收测试。pi 的 F0 工作包就干了这一件事，交付物是 22 个 HarnessNotImplemented。（08） 条件：多人/多 agent 并行开发同一个新接口。单人顺序开发时空实现危害小得多。
• 文档里主动告诉读者「你这类用户不该用这个特性」。锚点时 1578 行的 RPC 文档在第 5 行劝退 Node 用户。（14） 条件：同一能力有多条接入路径。成本为零，收益是所有人的时间。
• 快照是权威，事件是瞬态提示——写进协议规范。让事件通道可以不可靠，代价只是重连重传快照。（14） 条件：高频事件 + 可能断线的客户端。低频事件系统可以让客户端归约，省掉快照。

五条：pi 做对了，但换个环境就不成立

• 「不做权限系统」。pi 的论证在它的用户身上成立——能配 micro-VM 的开发者确实不需要进程内假边界。但这个论证有个漏洞：它用「防不住攻击者」的理由，一并否掉了「防模型犯错」的护栏，而后者是高频事件。（15） 失效条件：用户不做容器化（默认情况）、需要集中审计的组织、或非专业开发者。此时你得到的不是「诚实的无边界」，是「实际的无防护」。
• 贡献者门禁默认自动关闭。它成立的前提是维护者真的每天审阅被关队列。（18） 失效条件：维护者已倦怠。此时同一套机制退化成自动拒绝机器人，而外部无从分辨这两者。先问自己能不能兑现每日审阅，再决定抄不抄。
• 共享工作区 + 纪律，而不是 worktree 隔离。pi 用 AGENTS.md 的命令级黑名单替代物理隔离，换来共享构建产物的效率。（17） 失效条件：会话很长。规则文件会被压缩掉（06：没有 pin 机制），纪律在长会话末期最松，而那恰恰是改动最多的时候。这个失效是结构性的，不是执行问题。
• 自研终端 UI 库。3.2 万行 + 两个平台原生模块 + 四份终端兼容文档。（11） 失效条件：终端体验不是你的核心产品。判据很简单——「重绘模型」是不是你要解决的主要问题？不是就用现成方案。
• 把设计文档当任务队列。41 个工作包 + git 当分布式锁，零基础设施。（19） 失效条件：没有单一权威。这套协议的争议解决机制是「去 Discord 找 Mario」——具名到一个人。也失效于 PR 队列以天计的项目：认领提交排队期间，别人可能已经落地了冲突的认领。

四件到快照时还没有答案的事

这一节不是批评。它列的是已经下注、但结果尚未揭晓的决定——如果你在评估是否依赖 pi，这四条是真正的风险点。

• harness-v2 会不会完工。41 个包完成 11 个，30 个未动，而且没有任何机制保证它们会被完成。存储底座已经落地（07），执行器是空壳（08）。把 lanes / durable runs 当成 pi 的能力来做技术选型，是拿别人的路线图当自己的依赖。
• 两处「同名双份实现」会不会收敛。compaction（06，漂移 d3）与工具（02）各有两份，从两个已发布的 npm 包导出同名函数。这是迁移中间态，但对库使用者是当下的事实，且文档没有任何提示。收敛需要 coding-agent 迁到新 harness——而设计文档明确说这不在本次计划范围内。
• 「让 agent 解释自己」这条路径的实际效果。README 建议读者直接问 agent，skills 文档说「pi 可以给你造 skill」。第 13 章验证了它的准备工作是实的（AGENTS.md、prompt 模板、机读的工作包协议），但路径本身的效果无法从仓库验证——它取决于模型能力和提问方式。
• 贡献者门禁的长期效应。240 个已批准账号说明门在开。但这套机制运行时间不长，它对「路过发现真 bug 的资深工程师」的净影响还看不出来——这类人被自动关闭后大概率不会回来，而他们的流失是静默的、不可测量的。

本书自身的边界

为了让读者能校准信任：

• 本书读的是代码和文档，没有运行过 pi 做端到端验证。所有「已发布」判定基于调用链追踪（构造点 → 循环），不是行为观察。
• 没有审计 packages/tui 的差分渲染正确性、也没有审计 packages/ai 各 provider 适配的正确性。这两处占了全仓 36% 的代码，本书只描述了它们的设计意图。
• 漂移记录只有 3 条，来自写作过程中的顺手发现，不是系统性扫描的结果。一次针对 32945 行 markdown 的完整核对必然会找出更多。
• 本章是判断，不是事实。§2/§3/§4 的分类反映的是本书作者的取舍偏好；同样的证据，别人可以得出不同的排序。

本书从头到尾只做了一件方法上的事：不相信文档，去找那个 new Agent(。

结果是一个 3437 行的设计文档、一个 22 个方法抛错的类、一个只被自己测试引用的接线文件，和一条从 sdk.ts:294 出发的、真实在跑的调用链。这四样东西的关系，是任何一份 README 都不会告诉你的。

如果你要评估、依赖、或借鉴一个处于类似阶段的项目，这个方法比读一百页文档更快。

全书的行号引用可在 溯源索引 一次性核对；文档与代码不一致之处记在 漂移记录。