Pi 项目全景：monorepo 结构与各 package 职责

§2.1仓库顶层结构：先认楼，再进屋

读 monorepo 的第一件事不是打开源码，而是看目录。目录结构就是团队脑子里的架构图落在磁盘上的样子。

用 Get-ChildItem C:\pi_agent_study\pi-main 看根目录，除了 .github/、.husky/（Git 钩子）、biome.json、vitest.base.ts、tsconfig.base.json 这些工程配置外，真正承载架构的是四类目录：

还要记两个全仓库级事实：其一，根 package.json 声明 "type": "module"，全部代码走 ESM；其二，engines 要求 node >= 22.19.0——Pi 明确依赖较新的 Node 运行时能力（后面 AGENTS.md 里的「erasable TypeScript / Node strip-only mode」也与此呼应）。

§2.211 个 package 职责一览：从零依赖底座到最终产品

先把每个包的一句话职责背下来，再谈分层。下表内容逐条对照各 packages/*/README.md 首屏与各 package.json 的 dependencies 核实过。

三个容易看漏的细节，值得单独点出：

• telemetry 是「契约」不是「产品」。它只定义上下文接口、span 语义、度量 schema 与一个内存参考实现；接 OpenTelemetry、Sentry 还是纯日志，由应用侧写适配器。这是典型的「端口与适配器」思路——先中立，再接后端。
• 三个零内部依赖的「能力插件」：tui、codemode、mcp。它们不依赖任何兄弟包，可被任何项目单独 npm install。尤其 mcp 和 codemode，README 明确写了可脱离 Pi 独立使用——独立成包不是目录洁癖，而是复用边界。
• chord → durable → env 是一条独立的实验线。注意 coding-agent 的依赖列表里根本没有 chord/durable/env：CLI 主线与持久化实验线共享底座（schema/telemetry/ai），但互不纠缠。

§2.3依赖方向与分层理由：为什么箭头只许朝下

把 §2.2 表格里的依赖关系画到图上，整个仓库的架构决策一目了然：依赖只允许从上往下指（上层用下层），任何反向或同层循环依赖都是结构错误。

为什么必须「只许向下」

1. 构建顺序可推导。单向无环依赖图（DAG）天然存在拓扑排序，根目录那条手工串联的 build 命令就是它的展开（§2.4）。一旦出现循环依赖，构建顺序就只能靠碰运气。
2. 底座可独立发布与替换。telemetry 不绑定后端、schema 零依赖、mcp 不依赖官方 SDK——底座越中立，上层换实现时震动越小。这与 Java 里「依赖接口模块、不依赖实现模块」是同一条纪律。
3. 实验与主线隔离。durable 整条线标记 Experimental（README 明确 API 可在版本间无通知变更），通过「它依赖 ai/chord，但 coding-agent 不依赖它」把风险圈在分支内；主线 CLI 的发布节奏不被实验代码绑架。
4. 复用边界即发布边界。能被外部项目单独使用的（tui、mcp、codemode、ai、agent-core…）都做成可发布的 npm 包；只有最终产品 coding-agent 是纯粹的「组装车间」。这个决策让 OpenClaw、pi-chat 这类第三方集成可以直接站在 pi-ai 与 SDK 上，而不必拖走整个 CLI。

§2.4npm workspaces 与构建顺序：一条脚本里的拓扑排序

Pi 用 npm 原生 workspaces 管理 monorepo，没有引入 turbo/nx/lerna。它把「构建必须按依赖顺序」这件事写成了根 package.json 里一条手工串联的长命令——丑，但完全透明。

{
  "name": "pi-monorepo",
  "private": true,
  "type": "module",
  "workspaces": [
    "packages/*",
    "apps/*",
    "packages/chord/test/examples/61-tutorial",
    "packages/coding-agent/examples/extensions/with-deps",
    "packages/coding-agent/examples/extensions/custom-provider-anthropic",
    "packages/coding-agent/examples/extensions/gondolin"
  ]
}

注意 workspaces 不只覆盖 packages/* 与 apps/* 两个通配目录，还显式纳入了 4 个「嵌在工作区内部」的示例/测试项目——它们有自己的依赖需要安装。这正是 workspaces 的核心价值：所有子包共享一个根 node_modules 与一份 package-lock.json，内部依赖以 workspace 协议链接，装一次、全仓库可用。

"build": "cd packages/telemetry  && npm run build &&
        cd ../schema       && npm run build &&
        cd ../chord        && npm run build &&
        cd ../tui          && npm run build &&
        cd ../codemode     && npm run build &&
        cd ../mcp          && npm run build &&
        cd ../ai           && npm run build &&
        cd ../durable      && npm run build &&
        cd ../env          && npm run build &&
        cd ../agent        && npm run build &&
        cd ../coding-agent && npm run build"

同文件中还有 build:offline 变体：顺序完全相同，唯一差别是 packages/ai 执行 build:offline（离线构建模型数据），对应 Nix 离线打包场景。

把这条命令与图 2-1 对照，能读出三层信息：

1. 硬约束：被依赖者先构建。telemetry/schema 最先（零依赖）；chord、ai 随后（只依赖底座）；durable 在 chord/ai/codemode 之后；env 在 durable 之后；agent 在 ai 之后；最后才轮到依赖五个包的 coding-agent。这就是依赖图的拓扑排序（topological order）。
2. 软自由：无依赖关系的包之间顺序任意。chord 与 ai 互不依赖，谁先都行——脚本把 chord 排在 ai 前，只是作者按「durable 实验线」归组的选择，不是依赖约束。同理 tui/codemode/mcp 三个零依赖库理论上可以提到最前面。所以看到构建顺序时，要能区分「必须如此」与「恰好如此」。
3. 为什么不交给工具？npm 自带 --workspaces 能按声明顺序遍历，但不保证按依赖拓扑排序（并发时更不保证）；引入任务编排器又要加一层依赖。Pi 的选择是用一条显式长命令换取零工具依赖与完全可预测——极简哲学在工程决策上的延续。

与构建配套的还有根 check 脚本（节选字段名）：biome-check、check:pinned-deps（依赖必须钉版本）、check:runtime-deps、check:ts-imports（禁止非法相对导入）、check:entry-graphs（入口图检查）、两遍 tsc --noEmit。测试侧则是 npm run test（scripts 单测 + 各包 vitest）与 test.sh、pi-test.sh/.ps1/.bat。这些名字在 §2.6 会再次出现。

§2.5.pi/ 目录：Pi 用自身管理自身

走进 .pi/，你会看到这个仓库最有趣的现象：Pi 的开发者不是「用别的工具开发 Pi」，而是「用 Pi 开发 Pi」。这叫自我托管（self-hosting / dogfooding），就像编译器用自己的语言写自己。

.pi/
├─ extensions/   # import-repro.ts · prompt-url-widget.ts · redraws.ts · tps.ts
├─ prompts/      # cl.md · deslop.md · dup.md · is.md · pr.md · sa.md · wr.md
├─ skills/       # add-llm-provider.md · github-work.md · interactive-testing.md
│                #   · p2-ui.md · release.md
├─ git/          # 含 .gitignore
└─ npm/          # 含 .gitignore

对照 coding-agent 的文档体系解读三个子目录：

• extensions/ 下的 .ts 文件是仓库自用的运行时扩展——例如 tps.ts（每秒 token 数面板）、redraws.ts（重绘统计）、prompt-url-widget.ts。扩展机制本身就是 coding-agent 的核心特性，团队拿它调自己的产品。
• prompts/ 是提示模板：cl.md（changelog）、pr.md（PR 处理）、wr.md（代码评审）、deslop.md 等，把「让 agent 干活的标准说法」固化成可复用资产。
• skills/ 是技能文件：release.md（发布流程）、github-work.md（GitHub 协作）、interactive-testing.md（tmux 测交互模式）、p2-ui.md（p2 Web UI 规范）——把「老员工脑子里的流程知识」写成 agent 可加载的操作手册。

而最硬的证据来自 AGENTS.md 本身，它直接把这些技能当依赖引用（原文节选）：

Before writing or reviewing plugin code in apps/p2 ... read
apps/p2/docs/plugin-practices.md in full and follow it.

For building or changing p2's web UI (apps/p2), load and follow
.pi/skills/p2-ui.md.

For testing pi's interactive mode with tmux, load and follow
.pi/skills/interactive-testing.md.

For release preparation ... load and follow .pi/skills/release.md.

这段引用说明了自我托管的完整闭环：流程知识（release、测试、UI 规范）以 Pi 自己的 skills 格式存放，由 Pi 的 skill 机制按需加载，用来指导 AI 协作者开发 Pi 本身。如果这套机制不好用，第一个受害者就是 Pi 团队自己——这是最诚实的质量压力测试。同时注意 .pi/git/ 与 .pi/npm/ 里各有一个 .gitignore：自托管目录同样被当作普通工程资产做版本管理纪律，而非临时实验场。

§2.6AGENTS.md：Agent 时代的工程规范长什么样

AGENTS.md 是根目录的一份「给 AI 协作者的开发规则」，与面向人类的 CONTRIBUTING.md 并列。它读起来像一份严格的 code review 意见合集——因为它的读者每天会产出成千上万行代码。

- Keep answers short and concise. No emojis. No fluff.
- Read files in full before wide-ranging changes ...
- No any unless absolutely necessary.
- Validate only at decided trust boundaries (wire input, schema-checked
  arguments and params).
- **No inline imports** (await import() ...). Top-level imports only.
- Use only erasable TypeScript syntax (Node strip-only mode) in code checked
  by the root config ...
- Never remove or downgrade code to fix type errors from outdated deps;
  upgrade the dep instead.
- If the user's instructions conflict with any rule in this document, ask
  for explicit confirmation before overriding.

逐条翻译成架构语言，这份文件在约束四件事：

1. 可验证性。风格（biome）、类型（tsc）、测试（vitest + test.sh）、依赖纪律（pinned deps、runtime deps、entry graphs）都有脚本兜底；AGENTS.md 里的大量规则其实能在 scripts/ 下找到对应的检查器。规范不是品德要求，是 CI 断言。
2. 信任边界（trust boundary）。「TypeScript 类型已保证的值不做运行时检查；只在 wire input 与 schema 校验过的参数处校验」——这与 Java 里「不要对内部调用做重复 null 检查、只在系统边界（Controller/外部 API）校验」是同一条原则，只是写得更极端。
3. 确定性优先。禁止内联动态导入、只用可擦除（erasable）TypeScript 语法以配合 Node strip-only 模式、不许靠降级代码绕开类型错误——这些都是在压缩 agent 与工具链的「解释空间」，让静态分析与直接运行的结果可预测。
4. 流程与权限。Changelog 逐包维护、[Unreleased] 区不可篡改已发布段、PR 不得随意 checkout、用户指令与规范冲突时必须先确认再覆盖——最后这条本质是给 AI 协作者划了「变更需授权」的红线。

把这些放回 §2.5 的语境：Pi 把「AI 是一等贡献者」当作既定事实，然后围绕它重建工程规范——规范的主要读者从「新人 + reviewer」变成「agent + reviewer」，且规范本身用 Pi 的 skills 机制分发。这就是「Agent 时代的工程规范」样本：不是多写一份文档，而是静态检查可执行化、流程知识结构化、信任边界显式化、变更授权明确化。

附常见误区