2. Monorepo 拓扑¶
2.1 代码体量¶
| 语言 | 文件数 | 代码行 | 占比 |
|---|---|---|---|
| TypeScript | 1125 | 209,631 | 80.9% |
| Markdown | 97 | 23,925 | 9.2% |
| JSON | 46 | 13,582 | 5.2% |
| JavaScript | 34 | 8,141 | 3.1% |
| YAML | 14 | 1,743 | 0.7% |
| 其他 | 13 | 1,632 | <1% |
| 合计 | 1333 | 259,066 | 100% |
2.2 包清单（10 个）¶
README 只列 5 个；另外 5 个在代码层面存在并在
package.json的workspaces下，但未出现在README.md。
| 序 | 包 | 文件数 | 描述 | README | 状态 |
|---|---|---|---|---|---|
| 1 | pi-coding-agent | 634 | Coding agent CLI with read, bash, edit, write tools and session management | ✅ | production |
| 2 | pi-ai | 326 | Unified LLM API with automatic model discovery and provider configuration | ✅ | production |
| 3 | pi-tui | 92 | Terminal User Interface library with differential rendering | ✅ | production |
| 4 | pi-agent-core | 86 | General-purpose agent with transport abstraction, state management, and attachment support | ✅ | production |
| 5 | pi-session-backends | 37 | session 持久化后端 (sqlite-node 等) | ❌ | 🚧 experimental |
| 6 | pi-server | 23 | experimental server package for pi | ❌ | 🚧 experimental |
| 7 | pi-client | 18 | Transport-neutral client for remote pi sessions over framed CBOR bytes | ❌ | production-bleed |
| 8 | pi-evals | 18 | 评测工具集 | ❌ | production |
| 9 | pi-protocol | 17 | Transport-neutral CBOR protocol for remote pi sessions | ❌ | production-bleed |
| 10 | pi-telemetry | 12 | Vendor-neutral telemetry contracts and typed schema utilities for pi | ✅ | production |
2.3 依赖方向¶
┌──────────────────────────────────────────┐
│ coding-agent (CLI, 634 files) │
│ 所有可能性的末端；通过相对路径聚合下层 │
└────┬──────────────┬──────────────┬───────┘
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ server │ │ client │ │ evals │
│ (exp 23) │ │ (18, framed │ │ (18) │
│ │ │ CBOR) │ │ │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────────────────────┐
│ protocol (17) │
└──────────────────┬───────────────────────┘
│
┌───────────────────┴───────────────────────┐
│ agent-core (86) + session-backends │
│ ─── Agent, state, harness, transport │
└───────────────────┬───────────────────────┘
▼
┌──────────────┐
│ pi-ai (326)│
│ multi-provider│
└──────┬───────┘
│
┌──────────────┴──────────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ pi-tui (92) │ │pi-telemetry │
│ TUI 组件库 │ │ (12) │
└──────────────┘ └──────────────┘
2.4 Build 顺序（来自 package.json）¶
tui → telemetry → ai → agent → session-backends/sqlite-node
→ protocol → client → server → coding-agent
即：底层先于应用层构建。与依赖图一致的 toposort。
2.5 包版本同步¶
- 每个独立子包各自有 version，目前全部为
0.84.1 - 通过
scripts/sync-versions.js+ 顶层version:patch / version:minor / version:major / version:set命令统一 bump - 所有 release commit 使用
Release v<X>.<Y>.<Z>前缀
2.6 工作树外的产物¶
/tmp/pi-snap/ (28 MB → 79 MB after unshallow)
├── .git/ depth = full (5,650 commits)
├── packages/ 10 个子包
├── scripts/ release / check / model-data 脚本
├── .pi/ 内部配置
├── package.json workspace root
├── tsconfig.base.json + tsconfig.json
├── biome.json linter/formatter
├── test.sh · pi-test.sh · pi-test.{bat,ps1}
└── uv.lock · package-lock.json
/tmp/pi-inspect/ 独立索引目录，13 MB：
- snapshot.json —— 仓库身份元数据
- files.txt —— 1325 个文件清单
- symbols.jsonl —— 56,905 个 ctags 符号
- cloc.json —— 17 种语言 × {files, code, blank, comment}
- history.tsv —— 5,333 commit × {hash, author-iso, subject}
检查点的 hash 一致性
Snapshot-A 的 hash 2a9b4ebc... 同时落在：
- git -C /tmp/pi-snap rev-parse HEAD
- /tmp/pi-inspect/snapshot.json: commit
- GitHub REST API commits?per_page=1
三路一致 → Snapshot-A 是干净的。