开源雷达 2026-11-01

来源:github · 原文链接:https://github.com/pingdotgg/t3code · 整理:github_bot · 发布时间:2026-11-01


一、项目概览

T3 Code 给自己的定位是 “agent harness control surface”——智能体框架控制面。这个说法值得先拆开看:它不生产模型,也不做智能体本身,而是把已经跑在你机器上的编程智能体(Claude Code、Codex、Cursor、Grok Build、OpenCode、Google Antigravity)统一接管,然后提供一套移动端、Web 端和桌面端都能使用的操作界面。换句话说,它关心的是“怎么用”而不是“用什么模型”。

项目由 pingdotgg 团队开发,采用 MIT 许可,主力语言是 TypeScript,官网为 t3.codes。截至目前约 3.5 万 Star、8700 余 Fork,这个数字对于一个 2026 年才立项的项目来说相当惊人,也说明“统一控制本机 Agent”这个需求确实被大量开发者共同感受到。

不过作者在 README 里说得很直白:“We are very very early in this project. Expect bugs.” 并且明确表示目前基本不接受外部贡献,大功能不收,小修复可以考虑。这一点很重要——它决定了你该以“使用一个产品”还是“读一份架构参考”的心态来对待这个仓库。前者需要容忍不稳定性,后者则能获得相当多收获。

二、核心特性速览

能力具体表现对使用者的意义
三端同控iOS / Android 原生 App、Web App、Electron 桌面端,共用同一套会话状态在手机上看长跑任务的进度,回到桌面继续编辑
多 Agent 兼容Claude Code、Codex、Cursor、Grok Build、OpenCode、Antigravity 六家不必为每家 Agent 各装一个 GUI,只用一个入口
复用本机订阅直接接管已 login 的 CLI,不引入新的计费通道已付费的订阅不浪费,也不需要重新配置密钥
命令行安装curl 脚本、PowerShell 脚本,或 npx t3@latest 免装试用上手成本极低,试错成本也低
后台常驻t3 service install 注册为系统服务智能体能一直在后台运行,不依赖前台进程
全渠道分发winget、scoop、Homebrew Cask、.deb、AUR、nixpkgs各平台都有符合习惯的安装方式,不必自己编译

一个容易被忽略的细节是:它支持的六家 Agent 里,只有 Antigravity 不需要 CLI(在设置里点“Install Antigravity”并用 Google 登录即可),其余五家都要求你先在系统里装好 CLI 并完成认证。这说明 T3 Code 的接入模型是寄生式的——它不替你做认证,而是读取你已有的认证状态。好处是零迁移成本,坏处是它对各家 CLI 的版本和行为有硬依赖。

三、系统架构设计

T3 Code 系统架构

从目录结构看,这个仓库几乎是教科书式的 monorepo 分层。apps/ 下并列 desktop、mobile、web、server 四个应用,packages/ 下按领域切分几十个包,infra/ 放 relay 与 task-cache,native/ 放平台相关的原生能力(browser-secret、hyprland-snap-shot、kde-snap-shot、libghostty-vt、resource-monitor)。整套架构可以按三个层面理解。

交互接入层。最上面是 apps/desktop(Electron)、apps/mobile(Expo / React Native)和 apps/web,三者共享 packages/client-runtime 的会话逻辑。此外还有一个 apps/marketing 负责官网,与产品本体解耦。客户端不直接跟 Agent 打交道,它只跟本地服务通信,因此三端的行为能保持一致——这是“远程就绪”的架构前提,而不是事后补上的功能。

核心编排层。中间是 apps/server,对外暴露 HTTP / WebSocket,对内路由到 packages/provider-core。provider 这一族包是整套系统最核心的抽象:provider-acp、provider-cursor、provider-grok、provider-opencode、provider-muse、provider-pi、provider-fx 各自实现一家 Agent 的适配,provider-acp-registry 负责注册与发现。其中 packages/effect-codex-app-server 专门对接 Codex 的 app-server 协议,packages/effect-acp 则是对 ACP(Agent Client Protocol)的 Effect 风格封装。packages/contracts 提供跨包共享的类型契约,是整个 monorepo 的类型基座。

能力与外部层。往下是两类横向能力。其一是源码托管:source-control-github、source-control-gitlab、source-control-bitbucket、source-control-azure-devops、source-control-forgejo、source-control-gitcafe 六个实现,加上 source-control-core 与 source-control-definitions 做统一抽象——这意味着 PR、评论、分支状态这些信息能在同一个界面里呈现,而不必跳转到各家网站。其二是远程与凭证:packages/ssh 处理远程主机连接,packages/tailscale 打通内网穿透,infra/relay 提供设备间中继,secret-provider-onepassword 与 secret-provider-definitions 构成密钥托管体系。权限管控则贯穿编排层与外部层之间,任何一次工具调用都要先过审批规则。

这个分层有一个明显优点:新增一家 Agent,只需实现一个 provider-* 包并注册进 registry,UI 与服务层基本不用改;新增一家代码托管平台,同样只需加一个 source-control-*。扩展点被规整地安排在了正确的位置。

四、核心流程

T3 Code 会话主循环

一个完整的会话从设备接入开始,到结果回写结束,大致经过六个环节。

  1. 设备接入:用户在手机、浏览器或桌面端打开 T3 Code,客户端与本地服务建立 WebSocket 长连接。如果身处外网,则经由 infra/relay 或 Tailscale 打洞回到本机服务。
  2. 发现 Agent:服务端扫描本机已安装并已认证的 CLI,把可用的 Provider 列表回传给客户端。这一步决定了界面上能看到哪些 Agent 可选。
  3. 建立会话:用户选择工作区与 Agent,服务端为该会话绑定上下文的初始状态(session state),后续所有消息都挂在这个会话下。
  4. 下发任务:用户输入指令,服务端通过对应的 provider-* 适配层把指令翻译成该 Agent 能理解的协议格式,驱动底层实例执行。这一步是主循环的焦点:指令的语义在此被跨协议归一化。
  5. 权限审批:Agent 请求执行文件写入或 shell 命令时,会话的权限模式会决定是自动放行、逐次询问,还是直接拒绝。docs/user/permission-modes.md 对此有专门说明,实际使用中这是最需要按项目调优的部分。
  6. 流式回显:Agent 的输出以流的形式回传,服务端广播给所有在线客户端;同一会话在多端同时打开时,状态会实时同步,这就是 hub 上标注的“状态回写 / 结果同步”。 这个循环值得注意的地方在于“会话上下文”处于中心位置:不管用户从哪个设备接入,看到的都是同一份会话状态,客户端本身无状态。这种设计让“在手机上瞄一眼、回桌面接着干”成为自然行为,而不是需要额外功能支持。

五、核心模块解析

模块职责
packages/provider-core定义 Agent Provider 的统一接口与生命周期,是所有适配器的公共基座
packages/provider-acp / provider-acp-registry实现并注册 ACP 协议 Provider,供支持该协议的 Agent 复用
packages/effect-codex-app-server对接 Codex app-server 协议,处理 Codex 特有的会话与工具调用语义
packages/provider-cursor / provider-grok / provider-opencode / provider-muse / provider-pi各家 Agent 的独立适配实现,隔离协议差异
packages/contracts跨应用、跨包共享的 TypeScript 类型契约,保证端到端类型安全
packages/client-runtime三端共用的客户端运行时,承载会话状态、连接管理与重连逻辑
packages/source-control-*GitHub / GitLab / Bitbucket / Azure DevOps / Forgejo / GitCafe 的代码托管集成
packages/ssh / packages/tailscale远程主机连接与内网穿透,支撑跨设备访问
packages/secret-provider-*密钥读写抽象与 1Password 实现,避免凭据散落在配置文件里
infra/relay / infra/task-cache设备间中继服务与任务结果缓存
native/*平台原生能力:浏览器密钥、Hyprland / KDE 截图、终端模拟、资源监控
oxlint-plugin-t3code自研 lint 插件,用规则约束仓库内部的编码约定

这张表里最值得单独说的是 provider-* 这一族。它体现了一个成熟的适配器思路:公共逻辑收在 provider-core,协议差异隔离在各自的包里,注册与发现交给 registry。对比很多项目把“支持多模型”写成一层 if/else 分支的做法,这种拆分让新增 Provider 的边际成本可控,也让测试可以针对单个 Provider 独立运行(provider-testing 就是为此存在的)。

另一个亮点是 evals/ 目录,里面包含 mcp-tool-use、thread-titles、test-signal 等评测集。一个控制面项目愿意为“工具调用正确性”和“会话标题质量”建评测,说明团队把 Agent 行为质量当成了工程指标而非玄学。

六、特色能力

手机端远程接管。这是 T3 Code 最有说服力的场景:Agent 在你的工作站上跑一条长任务,你用手机看流式输出,发现方向不对就补一句指令。docs/user/remote-access.md 描述了从手机或其他机器接入的完整路径,底层依赖 relay 与 Tailscale 两条通道。

多账号档案。Codex 与 Claude 各自有独立的账号管理文档(providers-codex.md、providers-claude.md),意味着你可以在同一台机器上挂多个账号并按项目切换,而不是全局只能有一个登录态。对同时在个人账号和公司账号之间切换的人,这个细节很实用。

MCP 反向接入。docs/user/outside-agents.md 讲的是让外部 Agent(Claude Code、Codex、ChatGPT 等)通过 MCP 连进 T3 Code。这把控制面从“我操作 Agent”扩展成“Agent 也能操作我”——比如让外部 Agent 去查询当前工作区的状态。方向反过来了,能力边界也就宽了。

细粒度个性化。键位(keybindings.md)、外观(appearance.md)、项目级设置(project-settings.md)都有独立文档,说明这些不是摆设配置,而是有实际语义的选项。

自研 lint 规则。oxlint-plugin-t3code 用自定义规则约束仓库风格,这种“把团队约定固化成工具”的做法,在快速迭代的早期项目里通常是防止代码库腐化的有效手段。

七、工具链与生态

构建工具用的是 Vite+,需要先安装全局 vp CLI:

# 安装 vp(macOS / Linux)
curl -fsSL https://vite.plus | bash

# 拉取依赖
vp i

# 或直接试用,不安装
npx t3@latest

对使用者而言,更常见的是这几条:

# 安装并启动本地服务,自动打开 Web App
curl -fsSL https://t3.codes/install.sh | sh
t3

# 常驻后台 + 升级
t3 service install
t3 update

分发渠道覆盖得相当完整:Windows 走 winget 与 scoop,macOS 走 Homebrew Cask,Debian / Ubuntu 用 .deb,Arch 有 AUR 的稳定版与 nightly 版(打包脚本就在仓库 packaging/aur 里),Nix 用户可以直接从 nixpkgs unstable 装 t3code,同时包含桌面应用与 t3 命令。移动端则通过 App Store 与 Google Play 发布,底层是 Expo。

patches/ 目录值得一提:里面躺着三十多个上游补丁,从 node-pty、react-native-reanimated 到 expo-* 全家桶、@clerk/expo-native-components、mdast-util-math 等。这说明团队在依赖链上做了大量必要修改——对 Expo + Electron 这种组合来说很常见,但也意味着升级依赖时需要持续维护这些补丁,是一笔实打实的维护负债。

八、部署与安全

部署形态有三种:一次性 npx t3@latest 试用、curl 脚本安装后前台运行、t3 service install 注册为系统后台服务。README 特别提醒要保持 app 与 server 版本同步(docs/user/updating.md),因为两端走的是自定义协议,版本错配会直接出问题。

安全上最核心的机制是权限模式。Agent 一旦能改文件、跑命令,风险就从“说错话”升级为“做错事”。T3 Code 把审批粒度做成可配置项,按项目设定哪些操作自动放行、哪些必须逐次确认。实际使用中,建议对新项目一律用最严格的模式,跑顺了再逐步放宽——这个顺序反了很容易出事故。

凭证方面由 secret-provider-* 体系托管,packages/secret-provider-onepassword 表明它可以直接对接 1Password,而不是把 token 明文写进配置。native/browser-secret 则处理浏览器侧的密钥存储。远程访问路径上,relay 与 Tailscale 二选一:前者开箱即用但流量经过中继,后者需要自己组网但链路更可控。对安全敏感的团队,Tailscale 方案更合适。

九、适用场景

手机盯盘长跑任务的人。这是最典型的用户画像:任务在桌面跑,人不在桌前,需要随时查看进度、随时打断或补指令。三端同控 + 流式回显就是为这个场景设计的。

已订阅多家 Agent 的团队。当团队里有人用 Claude Code、有人用 Codex、有人用 Cursor,统一入口能省掉大量“你用哪个工具”的沟通成本,也便于对比不同 Agent 在同一任务上的表现。

需要自托管与可 fork 的团队。MIT 许可 + 完整 monorepo + 明确的架构分层,意味着如果产品方向不合意,你有全部材料自己改。README 里那句“if we ever go the wrong direction, we want you to have everything you need to fork”,不是空话。

想研究 Agent harness 架构的工程师。provider-* 的适配器模式、contracts 的类型契约、evals 的评测设计,都是可以直接借鉴的工程范本,哪怕你最终不用这个产品。

反过来,如果你只需要一个 Agent、只在一台机器上工作、不在意远程访问,那 T3 Code 提供的价值对你来说就偏薄了——多装一层服务只是多一个故障点。

十、总结评价

T3 Code 的真正价值不在“又一个 AI 编程工具”,而在于它把控制面从模型和推理中剥离了出来。过去两年,行业把注意力集中在模型能力上,工具层的创新大多停留在“把 CLI 包一层 GUI”。T3 Code 选择的是另一条路:承认各家 Agent 会长期共存,然后做那个把差异吸收掉的中间层。这个判断如果成立,它的位置就比任何单一 Agent 的客户端都更稳固。

工程上,它的架构分层是克制且清晰的:Provider、Source Control、Secret 三族包各自独立演进,contracts 兜住类型,client-runtime 兜住多端一致性。这不是一个堆功能的项目,而是一个把扩展点想清楚了的项目。

局限同样明显。第一,早期项目,作者自己说“expect bugs”,且明确不收大功能贡献,社区想深度参与的门是关着的——这对 3.5 万 Star 的项目来说是个潜在张力。第二,寄生式接入意味着它对六家 CLI 的版本与协议变化高度敏感,任何一家改协议,适配层就要跟着动,长期维护成本不低。第三,三十多个上游补丁是便利也是负债,升级时会集中爆发。第四,协议自定义、要求 app 与 server 版本同步,这在高频迭代期会带来不少“莫名其妙连不上”的排查时间。

结论:如果你属于“多 Agent、多设备、要远程”这三类特征叠加的人群,现在就可以试,用 npx t3@latest 试一次、不满意就删,几乎没有沉没成本。如果你只是想要一个稳定的单机 Agent 界面,可以再等等——它的架构值得学习,但产品成熟度还没到可以托付日常工作的程度。

参考链接:pingdotgg/t3code · t3.codes