02 三层边界 每一层守住的东西，正好是上一层不想知道的东西

先记住这一句

这个分层最实用的用途是定位问题：模型返回格式不对 → ai；工具跑了但结果没进上下文 → agent；工具行为不符合预期 → coding-agent。

第一层：pi-ai 只做「统一 provider」这一件事

它的自我定义写在 README 第一句：统一的 LLM API，带 provider 集合、自动认证解析、token 与成本跟踪，以及简单的上下文持久化与中途换模型的交接。ai/README.md:3

它还有一条显式的收录标准：

**Note**: This library only includes models that support tool calling (function calling),
as this is essential for agentic workflows.

第二层：pi-agent-core 的工具是「抽象工具」

packages/agent 里确实有 bash/read/write/edit 四个工具实现，但它们接受一个注入的执行环境（ExecutionEnv、FileSystem、Shell），而不是直接调 node:fs。harness/types.ts:315

这就是 第 15 章里 Gondolin 扩展能把工具路由进 micro-VM 的原因：工具逻辑与「在哪执行」是分开的。而 coding-agent 有自己那套 7 个工具（多了 grep/find/ls），面向真实文件系统。

顺带一提，这是全书第二处「同名双份实现」——第一处是压缩（第 06 章，漂移 d3）。两处的成因相同：harness-v2 迁移期，新旧两套并存。

第三层：coding-agent 承担全部产品决策

packages/agent 对这些一无所知——它只提供机制。

核心最小化是写进贡献指南的

If your feature does not belong in the core, it should be an extension.
PRs that bloat the core will likely be rejected.

Pi's core exists to be minimal and to be extensible so that it can be influenced and
manipulated by extensions.  Even hook points for extensions however should be well
considered and discussed to avoid adding unmaintainable bloat and complex interactions.

边界画在哪里，决定了什么能被替换

把「一轮对话」的概念留在 agent 而不是 ai，意味着换 provider 不影响循环；把「文件系统」留在注入接口而不是硬编码，意味着换执行环境不影响工具逻辑；把「UI」留在 coding-agent 而 tui 零依赖，意味着无头运行不需要 mock UI。

三条边界都遵循同一个判据：一个东西如果可能有第二种实现，就把它做成注入点。

代价：同一个概念在三层各有一份类型

一条消息在 ai 里是 Message，在 agent 里是 AgentMessage，在 coding-agent 里还有扩展出来的自定义 role。第 05 章那两道闸就是这个代价的具体形态——每次 LLM 调用都要做一次类型转换。

换来的是每层可以独立演化。coding-agent 加一种消息类型不需要动 ai；ai 加一个 provider 不需要动 agent。

「核心最小」与「产品层 12 万行」并不矛盾

容易误读的一点：CONTRIBUTING.md 说核心要最小，但 coding-agent 有 12 万行。这不矛盾——「核心」指的是 packages/agent（2 万行）。产品层大是正常的，因为产品决策就是多。

真正的约束落在别处：coding-agent 里那些「本可以做成扩展」的功能，才是这条规则要拦的。而它给出的出路是扩展系统（第 12 章）——所以扩展系统的能力边界，直接决定了这条规则可执行到什么程度。

• 层与层之间存在同名双份实现。compaction（06）与工具（本章）各有两份。这是迁移期的中间态，但对库使用者是当下的事实：import 的路径决定了你拿到哪一份。
• coding-agent 是唯一没有「向上一层」的层。它没有稳定 API 承诺（相对于 ai 与 agent 的公开 npm 包）。想复用它的能力，路径是 SDK 或扩展（第 14 章），不是直接 import 内部模块。
• 分层不阻止产品决策泄漏进下层。例如 agent 里的 DEFAULT_COMPACTION_SETTINGS 已经带上了具体数字（16384 / 20000），那本质上是产品决策。

• 用「这一层刻意不知道什么」来定义边界，比用「这一层负责什么」更清楚。前者可证伪——你可以 grep 有没有泄漏。 适用条件：任何分层设计。写进 README 后它就成了可检查的约束。
• 可能有第二种实现的东西，做成注入点。pi 把「执行环境」注入到工具里，于是 micro-VM 路由变成一个扩展就能做的事。 适用条件：你能预见第二种实现。为想象中的第二种实现做抽象是过度设计。
• 「核心最小」这条规则只有配上一个够强的扩展系统才可执行。否则被拒的 PR 无处可去，规则会变成「我们不接受贡献」的委婉说法。 适用条件：你打算用这条规则拒 PR。

给场景，判断 pi 会怎么做