拆解方法与源码基线

分析对象

本书分析 /Users/hanqing/CliX/t3code-main 本地快照。根 package.json 声明 Node ^24.13.1、 pnpm 11.10.0；核心应用与协议包版本为 0.0.33。快照没有 .git 目录，因此：

• 可以验证文件、类型、测试和构建配置之间的静态关系；
• 不能把某一行为精确归因到 commit、PR 或发布时间；
• 指向 GitHub main 的链接是导航入口，不保证与快照逐行相同。

参考拆解采用的结构

refs/dg-ai-notes 对 pi 的拆解并非 API 清单，而是围绕运行主线组织章节。本文延续它的四个优点：

1. 先建立系统地图，再钻局部。 每个细节都必须能回到一个端到端场景。
2. 源码与设计动机并列。 不仅复述 if 和类名，还解释它在并发、恢复或安全上的约束。
3. 关键状态画图。 模块图用于边界，流程图用于所有权，状态图用于生命周期。
4. 章末提炼迁移经验。 区分 T3 Code 的具体实现与可用于其他系统的模式。

不同之处是：T3 Code 的规模和平台数量更大，因此本文按“系统全景—核心运行时—Provider—客户端—平台—工程化” 分层，而不是机械映射目录。

证据优先级

例如“命令被全序处理”不是从架构图猜出来的，而是由 OrchestrationEngine.ts 里的单一 command queue 与 worker 共同证明；“离线不消耗退避次数”则需要同时看 client supervisor 的状态转移和测试。

统计口径

本书给出的数量是结构量级，不是代码质量指标：

• Rpc.make( 在 packages/contracts/src/rpc.ts 中出现 95 次；
• apps/server/src/persistence/Migrations 具有从 001 到 040 的迁移序列；
• 内置 Provider 顺序是 Codex、Claude、Cursor、Grok、OpenCode；
• apps、packages、infra 下约有 1,966 个 .ts 与 411 个 .tsx 文件，包含约 771 个测试文件；
• .repos/ 是参考仓库镜像，node_modules、生成文件和二进制资源不计入主体规模。

数量会随上游变化。真正应该记住的是：RPC 面已经接近百项、迁移已形成长期演化历史、测试密度高， 所以任何“重写成一个简单 WebSocket handler”的建议都必须先解释如何保留已有契约。

阅读源码时的切片策略

对每个主题采用五个切片：

contract → composition root → pure core → side-effect adapter → tests

以发送消息为例：

1. 在 contracts 找 RPC 输入和领域 command；
2. 在 ws.ts 找授权和 handler；
3. 在 decider.ts 找纯事件决策；
4. 在 reactor/provider 找副作用；
5. 在 ingestion/projector/test 找回流和恢复。

这种读法能避免沿 import 树无限扩散，也能清楚区分“意图已被接受”和“外部 Agent 已经执行成功”。

已知限制

此外，T3 Connect 的云端基础设施、Clerk 配置、商店签名和发布密钥依赖外部环境；本文可以拆解代码边界， 但不会声称在本地快照中验证了生产部署状态。