# 用 Archify 方法分析 pi

目标仓库：`git@github.com:earendil-works/pi.git`，revision `531340f100c6b682a602657b699a0ac27d522c30`（浅克隆，工作区仅多出 `.ua/` 与 `.archify/`）。

产物（均可直接双击打开，单文件、离线、无外部依赖）：

| 文件 | 类型 | 回答的问题 |
| --- | --- | --- |
| `architecture-pi-runtime-20261027-173615/pi-runtime-architecture.html` | architecture | pi 由哪些角色组成，谁拥有什么，边界在哪 |
| `sequence-pi-turn-20261027-174000/pi-turn-sequence.html` | sequence | 一次提问在进程内到底走了哪几步 |

两张图都通过了 Archify 的全部门禁：`validate`（9 项产物检查 + showcase 组合检查 0 error / 0 warning）、`deliver`、`check`、`browser-check`、`visual-check`（containment / readability / viewerChrome / themeStates / captures 全 pass）。

---

## 1. 方法：Archify 的三条硬约束

Archify 不是画图工具，是一套**有证据约束的架构表达流程**。它强制三件事，恰好治好了上一轮分析"乱"的毛病：

**① 冻结身份。** 图里必须钉死 40 位 revision，所有 `sources` 的行号都相对这个 commit 有效。不是"我印象中 pi 是这样"，而是"在 `531340f` 上，第 379 行是 `class AgentSession`"。证据失效可以被机器检测出来。

**② 每个断言都要有出处。** 组件要么有 `sources`（path + line，最多 3 条），要么根本不配被画进去。图里 12 个仓库内组件全部带行号；只有 `终端用户`、`厂商 API` 这类外部角色没有来源——因为它们不在仓库里，这一点本身就是事实。

**③ 边界必须表达真实事实。** `region` 只能表达真实的进程/运行时/归属隔离，不能拿来当"视觉分组"。所以图里只有两层边界：`pi 进程（Node.js，可信核心）` 和嵌在其中的 `用户代码沙箱边界：扩展 / skills`。

切片的依据也不是感觉，而是清单 + 入口 + 注册点：`packages/*/package.json` 定义包边界，`packages/coding-agent/src/main.ts` 是唯一进程入口，工具与扩展都在 `core/tools/` 与 `core/extensions/` 里注册。

---

## 2. 规模事实（先看数字，再看结构）

TS/TSX 代码量（`wc -l`，含测试，排除 node_modules）：

| 包 | 文件数 | 行数 | 角色 |
| --- | ---: | ---: | --- |
| `coding-agent` | 688 | 164,445 | 产品层：CLI、模式外壳、会话、工具、扩展 |
| `ai` | 403 | 79,996 | 模型层：统一消息模型 + 各家 provider 适配 |
| `durable` | 219 | 73,943 | 持久化执行 |
| `chord` | 107 | 34,644 | 增量/合并算法 |
| `tui` | 99 | 40,302 | 终端渲染引擎 |
| `mcp` | 25 | 4,939 | MCP 协议客户端 |
| `codemode` | 28 | 5,237 | 代码模式 |
| `agent` | 16 | 6,929 | **agent 循环本体**（`src/` 仅 6 文件 / 2,541 行） |
| `env` / `evals` / `telemetry` | 8 / 15 / 5 | 3,560 / 3,342 / 2,571 | 支撑 |

关键反差：**agent 循环的 `src/` 只有 6 个源文件、2,541 行**（整包含测试 6,929 行），而 `coding-agent` 整包 164,445 行，是它的 24 倍（同含测试口径）。pi 的复杂度不在"agent 智能"，而在"把 agent 塞进一个真实终端产品"所需的胶水——这正是架构图必须把 `AgentSession` 和模式外壳分开画的原因。

---

## 3. 子系统与职责（对应 architecture 图）

| 组件 | 真实职责 | 证据 |
| --- | --- | --- |
| CLI 入口 | 解析参数，按模式分发，是唯一进程入口 | `main.ts:623`、`main.ts:950-988` |
| 交互模式 | 全屏 TUI 外壳，把渲染委托给 `packages/tui` | `interactive-mode.ts:453` |
| Print / RPC 模式 | 同一会话的另外两个输出通道 | `print-mode.ts:33`、`rpc-mode.ts:54` |
| TUI 引擎 | 差分渲染 + 组件树，独立于 agent 语义 | `tui.ts:506`、`tui-main-screen.ts:124` |
| AgentSession | 会话装配、模型状态、上下文压缩、事件分发 | `agent-session.ts:379`、`:2092` |
| Agent Loop | 流式消息 → 工具执行 → 再请求的闭环 | `agent.ts:194`、`agent-loop.ts:251` |
| LLM SDK | 统一消息/事件模型，唯一模型出口 `streamFn` | `stream-fn.ts:15`、`models.ts:1077` |
| Provider 适配层 | 协议差异收敛在此，只有它发 HTTP | `anthropic-messages.ts:660`、`providers/anthropic.ts:19` |
| 工具 | 实际改动世界：bash / read / write / edit | `tools/index.ts:1`、`bash.ts:434` |
| 扩展 / Skills | jiti 即时编译的用户代码，注册工具并提供调用门禁 | `extensions/loader.ts:831`、`extensions/runner.ts:364` |
| 会话存储 | JSONL 逐条追加，可恢复 | `session-manager.ts:1187` |
| 工作区 | 文件系统 + shell：真正的副作用边界 | `write.ts:82` |

---

## 4. 一次调用的真实路径（对应 sequence 图）

```
用户 → InteractiveMode → AgentSession.prompt() → runAgentLoop()
     → streamFn(model, ctx) → provider 适配 → 厂商 API（HTTPS/SSE）
     → assistant 消息完成
     → execute(toolCall)：validate → beforeToolCall 门禁 → tools.execute()
     → bash 在工作区起进程 / 写文件 → toolResult 回到上下文
     → 再次 streamFn（含工具结果）→ 最终文本
     → session 收尾：追加 JSONL 落盘 → 事件驱动渲染
```

三个容易被误读的点，图里都做了明确编码：

- **模型调用只有一个出口**：`streamFn`。业务代码从不直接 new 厂商 SDK 客户端，所以换 provider 不动上层。
- **工具是唯一的信任边界**：`prepare → validate → beforeToolCall → execute → afterToolCall`（`agent-loop.ts:737`、`:842`）。扩展之所以能当"权限门禁"，就是挂在这个 hook 上——这是设计上最聪明的一处复用。
- **渲染是纯消费者**：模式外壳不参与决策，只订阅事件。所以 print / rpc / interactive 三个外壳能共用同一个 `AgentSession`。

---

## 5. 结构性结论

1. **分层是单向的**。`agent → ai`，`coding-agent → ai / agent / tui / mcp / codemode`，`durable → chord / ai / telemetry`，`env → durable / chord`；没有循环依赖。
2. **核心小、边缘厚**。Agent 循环 6.9k 行；`ai` 里 200+ 文件绝大部分是 provider 适配（协议翻译），不是智能逻辑。
3. **信任边界只有一个，也很薄**。扩展与 MCP 都以用户代码身份进入进程，靠 `beforeToolCall` 单一闸门约束；工具直接碰真实文件系统和 shell，没有中间沙箱层。
4. **可恢复性是设计前提，不是补丁**。会话以 JSONL 追加写，消息一结束就落盘，崩溃后能续。
5. **热点集中**。`interactive-mode.ts` 7,110 行、`agent-session.ts` 4,458 行，两个文件承担了产品层绝大部分职责——这也是后续重构最值得动的地方。

---

## 6. 复现与维护

```bash
# 校验（含证据行号有效性）
node bin/archify.mjs validate architecture .archify/architecture-pi-runtime-20261027-173615/candidate.json \
  --repo-root [local workspace]/pi

# 重新出图（HTML 单文件）
node bin/archify.mjs finalize architecture \
  .archify/architecture-pi-runtime-20261027-173615/candidate.json \
  .archify/architecture-pi-runtime-20261027-173615/pi-runtime-architecture.html \
  --repo-root [local workspace]/pi --browser-check
```

（`bin/archify.mjs` 位于 `/tmp/archify/archify`，是 Archify v3.2 的本地克隆。）

重新基线时只需改 `meta.repository.revision`，然后重跑 `validate`：行号漂移会被直接报出来，图不会悄悄过期。

## 7. 本轮没做的事

- 未做 `--review` 的图评审 pass（需要额外 LLM 复核链路）。
- 未画 `node`/`env` 桌面端变体，也未覆盖 `durable`、`chord` 的内部结构——它们与主用户旅程距离较远。
- `sequence` 图因桌面可读性约束（画布宽 ≤945px、文字投影 ≥7px）压缩到 8 条泳道 / 13 条消息，厂商 API 被并入 `LLM SDK` 泳道，网络往返在架构图里单独表达。

## 8. 衍生交付：pi 系统学习手册

在两张图的基础上，追加了一份**面向人的学习资料**：`learn/index.html`（离线单页，中文）。

它不只复用图表，而是把三个信息源交叉对齐：

| 来源 | 取用内容 | 处理方式 |
|---|---|---|
| `packages/coding-agent/docs/`（40+ 篇） | how-pi-works、session-format、compaction、extensions、sdk、security、mcp | 作为「仓库现状」的权威描述 |
| `README.md` + 源码 | 安装方式、包结构、system prompt 组装、工具工厂、provider 数量 | 给出 `blob#Lnn` 永久链接 |
| `mariozechner.at` 三篇博客 | 设计动机、四个 API、context handoff、最小 prompt/工具集、YOLO、五条「不做」 | 英文原句 + 中文释义，标注日期 |

关键产出是**冲突消解**：博客（2025-11-30）明确写「不支持 MCP 且将来也不会」，而仓库（`531340f`，2026-10-27）已有 `packages/mcp`、`docs/mcp.md` 与 `pi mcp add`。手册没有二选一，而是并列呈现，并指出实现方式仍服从统一工具管线与 `--tools` 过滤——这恰好印证「原则不变、立场可变」。

页面自带交互：目录随滚动高亮、代码块一键复制、机制手风琴、图可全屏放大、支持打印。
已用 CDP 在 390 / 768 / 1440 三档宽度验证：无横向溢出、无 console 错误、两张 iframe 均解析到真实文件 URL。

### 8.1 内嵌可读性：一个被 Archify 校验覆盖不到的盲区

Archify 的 `visual-check` 按**产物自身视口**评估可读性（最小字号 7px 通过），
但学习页把图塞进 898px 的正文栏，等比压缩后：

| 图 | 画布（viewBox） | 1× 内嵌实际渲染 | 缩放比 | 最小字号 → 屏上 |
|---|---|---|---|---|
| architecture | 1750×732 | 804px | 0.46× | 7px → **3.2px** |
| sequence | 952×610 | 804px | 0.85× | 7px → 5.9px |

即架构图在内嵌状态下不可读，只有「新窗口」能救。这是**渲染宿主宽度**的问题，不是图的缺陷，
Archify 也没有告警。修复分两层：

1. **页面侧**：加 1× / 2× / 3× 档位，切换时**重建 iframe**（而非改 CSS 宽度）——
   Archify 的阅读宽度是运行时按视口测量的，只改宽度不会重新布局，实测 3× 时 SVG 仍停在 1390px。
2. **图侧**：在 `diagrams/*.html` 的 `</head>` 前注入 `html{--archify-reader-width:2900px !important}`。
   这一条是必需的：Archify 的该变量由 JS 计算且上限 1920px，在 iframe 重载时还存在竞态
   （同一 3× 档位两次测得 0.79× 与 1.07×）。改成 CSS 覆盖后结果确定。

最终实测：架构图 1× 3.2px → 2× 6.7px → 3× **10.3px**；时序图 1× 5.9px → 2× **12.4px**。
覆盖只抬高上限，1× 缩略视图与「新窗口」原始视图均无变化（1440 窗口下 SVG 仍 1346px），
删掉那一段 `<style data-learn-override>` 即回到原始行为。

教训可以复用：**凡是把宽画布产物嵌入窄栏位，都要按「渲染宽度 / viewBox 宽度」重算字号，
而不是相信产物在自己的视口里报告的通过值。**

### 8.2 形态：从单页拆成多页

单页版长到 21,300px，`⌘F` 之外没有别的定位手段。因此拆成「总览 + 每章一页」，
并保留单页全本：

```
learn/index.html          总览（章节卡片 + 三条路线 + 四个入口）
learn/01..11-*.html       每章一页（左栏：11 章列表 + 本章目录；页脚：上一章/下一章）
learn/all.html            单页全本（自包含，CSS/JS 内联，适合打印与整页分享）
learn/assets/style.css    共享设计系统
learn/assets/app.js       进度条 / 目录高亮 / 复制 / 图缩放 / 深链展开
```

拆分是用脚本做的（`/tmp/build/gen.py`），不是手抄：按 `<!-- ==== NN 标题 ==== -->`
注释切分、抽出共享 CSS/JS、并从 `<h3>` / `<summary>` / `.step > .h` 三种标题结构里生成
每章的本节目录——所以 `05`（手风琴章节，用 `<details>` 而非 `<h3>`）和 `10`（用 `.step`）
也能有目录。上一章/下一章由同一份顺序表生成，不会漏链。

拆分过程中修掉的三件事：

1. `all.html` 的 `packages` 徽章仍写着 12，实际 `packages/` 下是 11 个包——顺手改正。
2. 本章目录指向 `<details>` 时，点击只能跳到「收起的」手风琴头部；`app.js` 增加了
   hash 命中即展开（含 hashchange）。
3. 目录高亮的选择器原本硬编码 `#toc-list`，改成 `[data-spy] a[href^="#"]`，
   单页版与分章版共用同一份 JS。

验证：13 个页面在 390 / 768 / 1440 三档全部零 console 错误、零横向溢出，
外部 CSS/JS 在 `file://` 下正常加载（`document.styleSheets.length === 1`，背景色变量生效）；
静态检查确认 0 断链、0 无效锚点、标签平衡；目录高亮实测精确命中（滚到 `#t3` / `#t5` / `#t4` 均正确）。
