01 · 产品边界与系统全景

不是 IDE，也不只是聊天 UI

T3 Code 自称 agent harness control surface。这个定位精确地区分了三类职责：

它不试图把五个 Agent 的推理语义做成完全相同，也不托管用户仓库。它统一的是控制协议和可恢复状态： 开始会话、发送 turn、流式消息、活动、审批、用户输入、取消、停止与回滚。

四类运行进程

1. 客户端进程负责交互和本地显示缓存。它可以消失并重建。
2. T3 Server是权威执行进程，通常和仓库位于同一台开发机。
3. Provider 进程/SDK执行真正的 Agent 会话，协议各不相同。
4. 可选云控制面帮助发现和接入执行环境，但不拥有工作区热路径上的业务状态。

Electron 把前两者打包得像一个应用，但代码仍然保留进程边界。这样，同一 Server 既能由桌面 UI 控制， 也能由浏览器或手机控制。

领域对象：Project、Thread、Session、Turn

阅读代码前必须区分四个经常被混用的词：

• Project：一个工作目录及其 UI 配置。它是线程容器，不等于 Git repository；非 Git 目录也可以存在。
• Thread：用户看到的长期对话与工作单元，拥有标题、归档/置顶/稍后处理状态、消息、活动和 checkpoints。
• Provider session：某个具体 Provider 的运行会话。Thread 可以恢复或替换底层 session，并记录 instance 绑定。
• Turn：一次用户输入到 Agent 本轮结束的生命周期，是 checkpoint、状态和分页的关键粒度。

这个模型解释了为什么不能简单地把 Provider 的 session ID 当 thread ID：Provider 可能崩溃、切换账号、 更换运行模式或无法恢复，而用户的 Thread 历史仍必须存在。

两条数据路径

写路径：命令先被接受，再执行副作用

客户端的动作通过 Effect RPC 进入 Server，转换为 OrchestrationCommand。编排引擎验证当前 read model， 产生并事务性追加事件；随后 reactor 观察“请求发送 turn”等意图事件，调用 Provider。也就是说：

RPC → command → decide → append event → update projection → reactor → provider

“命令接受成功”与“Provider 最终成功”是两个事实。把它们分开，才能在 Provider 超时或 Server 重启后 保留用户意图，并把失败显式写回活动/会话状态。

读路径：快照建立基线，事件推进版本

客户端连接后先读取项目/线程快照，再订阅 Server 的事件流。事件带有全局顺序，用于增量推进； 如果客户端落后太多，Server 不会无限补发，而会要求重新取快照。

persisted projection → initial snapshot → event subscription → local atoms/stores

这是一种“快照 + 有界增量”的同步协议。它比只广播临时 WebSocket 消息更可恢复，也避免无限 event replay 把慢客户端拖成内存风险。

为什么本地优先

本地执行不是情怀，而是由工作负载决定：

• Agent 需要低延迟访问整个工作区、Git、终端和本机工具链；
• 用户已在各 Provider CLI 中登录，复用订阅和凭据比重新托管授权简单；
• 未提交代码和环境变量不必上传到中心服务；
• 桌面断网后，Server 与 Agent 仍可继续工作。

代价也真实存在：远程发现、穿透、配对、版本兼容、后台保活和移动端断线恢复都必须由 T3 Code 解决。 因此它的复杂度集中在“本地服务如何成为可靠的远程端点”，而不是传统 SaaS 的多租户计算层。

源码锚点

• 内部架构概览
• 共享领域模型与 Schema
• Server 组合根
• Web 入口
• Desktop 主进程入口
• Mobile 入口

可迁移经验

1. 先定义执行边界，再选 UI 技术。 只有一个进程拥有工作区副作用，其他端才可能共享协议。
2. 用户对象与供应商对象分离。 Thread 是产品概念，provider session 是基础设施概念。
3. 远程控制不等于云端执行。 控制面可以帮助发现与授权，数据热路径仍保持端到端。
4. 同步协议必须包含重建路径。 增量事件永远可能丢失或超过保留窗口，快照不是优化而是正确性机制。