tianshu-mcp

天枢 × AI-Agent 编排 MCP server

由天枢（Tianshu）当作标准 MCP server 接入，调度外部 AI-Agent（Codex 桌面端、TraeWork/TRAE SOLO CN、ZCode 均经 CDP 驱动桌面 UI）完成 项目开发 → 验收 → 失败返修 → 再验收 的闭环（架构可横向扩展）。

天枢官方仓库：github.com/huiliyi37/Tianshu-harness —— 基于 harness 工程的终端编程智能体运行时（TUI × GUI），本 MCP 作为其 MCP server 接入。

English · 简体中文

这是什么

天枢的角色是总指挥；本 MCP server 是调度层 + 执行面 + 客观验收仪；外部 AI-Agent（Codex / TraeWork / ZCode GUI）是执行开发的「工人」。

• 9 个 MCP 工具：run_task / continue_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles。
• 异步契约：run_task 秒回 taskId，长任务用 query_task 轮询（长任务不卡 tools/call）。
• 客观验收：自动命令检查（typecheck/lint/test/build，缺则跳过 + 技术栈推导）+ 程序化代码分析（变更清单/diffstat/TODO·debugger·密钥形态等可疑标记），全部相对 git 基线，不自动 commit/stash。
• 失败返修闭环：自动返修（autoFixRounds）+ 手动 rework_task；验收失败时自动生成修复计划文件并回填给 agent；轮次用尽 → needs_attention 等天枢裁决。
• 执行面：driver: "gui" 由显式 adapter 驱动桌面 UI（Codex / TraeWork / ZCode 各自使用隔离的 CDP 流程）；driver: "spawn" 走外部 CLI 子进程。
• 调度纪律：每项目串行队列 + 全局并发上限（默认 2，可配）。
• 不碰密钥：各 agent 用自己的登录态；本 server 不保存/转发任何 API key。
• 可扩展：新 agent = 一个 profile（数据）+（如需）一个 adapter 文件，零改编排核心。

快速开始

前置条件

数据目录默认 ~/.tianshu-mcp，可用环境变量 TIANSHU_MCP_HOME 覆盖；首次启动自动创建。

从源码构建

git clone https://github.com/lanlan0811/tianshu-mcp.git
cd tianshu-mcp
npm ci
npm run build        # sync-version + tsc → dist/
npm test             # 332 项测试：39 个文件，含 Codex/ZCode 单元/假 CDP/重启/返修闭环

安装 npm 包

npx -y tianshu-mcp            # 免安装直接拉起
# 或
npm install -g tianshu-mcp

在天枢里添加（推荐）

天枢「设置 → MCP 服务器 → 添加」，按下面填写即可（传输方式选 stdio（本地进程））：

• 服务器 ID 即工具前缀：填 tianshu-mcp 后工具名为 mcp__tianshu-mcp__run_task 等 9 个。
• 参数按空格分隔填写，不要加引号；本地开发模式请把 <仓库绝对路径> 换成真实绝对路径（如 D:/Trae项目/tianshu-mcp/dist/index.js）。
• 界面未提供环境变量输入框；如需自定义数据目录，改用下面的 config.json 方式设置 TIANSHU_MCP_HOME。
• 添加后连接成功即完成；新开会话即可看到 9 个工具。

或改 config.json（可配环境变量）

配置为天枢 MCP server（本地开发模式）：

{
  "mcp": {
    "servers": {
      "tianshu-mcp": {
        "command": "node",
        "args": ["<仓库绝对路径>/dist/index.js"],
        "env": { "TIANSHU_MCP_HOME": "<仓库绝对路径>/.tianshu-mcp" }
      }
    }
  }
}

新开会话后，工具面出现 mcp__tianshu-mcp__run_task 等 9 个工具。用 stub 预演（不碰真实登录态）→ 切 codex 跑真实任务：

run_task(projectPath=D:/xxx/my-app, task=「…任务书…」, agentId=codex,
         model=「GPT-5.6 Sol」, reasoningLevel=「高」, autoVerify=true, autoFixRounds=5)
  → taskId → query_task(taskId) 轮询 → succeeded / failed / needs_attention → get_task_report 读报告

codex 现为桌面端 GUI 驱动（driver=gui + activation=msix-com）：Codex 是 MSIX 商店包，
其 ChatGPT.exe 无法直接启动（被策略拒绝），须经 COM 激活并注入专属 --user-data-dir 后方可
用 CDP 驱动。可传 planDoc / designSystem 拼进初始指令。详见 docs/codex-gui-cdp.md
与 真机验收记录。

驱动 TraeWork 时可用 model 与 mode：

run_task(projectPath=D:/xxx/my-app, agentId=traework, task=「切换到 Code 模式，实现登录接口」,
         model=GLM-5.3, mode=Code, autoVerify=true, autoFixRounds=2)

mode 支持 Work / Code / Design；不传时从任务书文本识别（如「切换到 Code 模式」），识别不到则保持 Work。
TraeWork 的三种模式各自维护独立的项目绑定，因此实现顺序为「新建会话 → 切到目标模式 → 在目标模式内绑定项目」。

驱动 ZCode 时，model 必须使用精确的 供应商/模型，且不能传 mode：

run_task(projectPath=D:/xxx/my-app, agentId=zcode, task=「按 `./plan.md` 完成开发」,
         model=DeepSeek/deepseek-flash, autoVerify=true)

ZCode 提问或需要用户处理登录、旧实例、系统权限时进入 needs_user；处理后调用 continue_task(taskId, message) 恢复原会话。完整约束见 docs/zcode-cdp.md。

工具面（9 个）

返回统一为「人类可读文本 + ---tianshu-mcp-meta--- JSON 块」，便于宿主正则抽取。

日志与 stdio 契约

本 server 是标准 MCP stdio server，严格遵守传输契约：

• stdout 只承载 MCP JSON-RPC 消息。任何诊断日志都不会写入 stdout——否则会破坏 JSON-RPC 流，导致严格客户端握手或工具调用失败。
• 所有级别日志（DEBUG/INFO/WARN/ERROR）写入 stderr，同时追加到数据目录下的 logs/server.log（UTF-8，ISO 时间戳，含级别标签）。
• 因此 stderr 里出现 INFO/WARN 不代表服务器出错；它是正常诊断信息。只有启动失败（tianshu-mcp 启动失败:）才是致命错误，并会以非 0 退出码结束。

数据目录默认 ~/.tianshu-mcp（可用 TIANSHU_MCP_HOME 覆盖），日志文件位于 <数据目录>/logs/server.log。

排查连接问题时以 server.log 为准；不要因为 stderr 有输出就判定 server 异常。

文档

英文文档见 README.en.md；完整文档地图与状态快照见 HANDOFF.md。

里程碑状态

• M1 — 核心引擎 + stub-agent 全链路 ✅
  • 8 工具、TaskManager 状态机/队列/并发闸/cancel(kill tree)/事件流落盘
  • 验收引擎（git 基线/diff、默认集推导、命令 runner、代码分析、report.md/json）
  • fix-loop 自动返修 + needs_attention；技能自检安装（已在本机真实 ~/.rivet/skills 验证）
  • stub-agent 三剧本（good/fix-on-first/never）集成测试 + 协议测试
• M2 — 真实 Codex CLI 冒烟 + rework 闭环 ✅（2026-09-07）
  • 真实 codex exec 跑通 run_task → query_task → verify_task（m2-smoke-record.md）
  • 真实 失败→rework_task→再验收 succeeded 闭环（m2-rework-record.md，物证 docs/m2-evidence/）
  • 修复冒烟暴露的 3 个真实缺陷（Windows npm 垫片 / spawn 日志竞态崩溃 / codex flags 互斥）并各加回归测试
  • Zcode 无头接口（Z1）实测定论：ZCode 桌面无随包 headless CLI → unsupported
• R1–R8 / S1–S6 — 两轮验收整改 ✅（取消/超时/基线归因/参数语义/热加载/CI 加固）— 72 测试
• 工程 / CI ✅
  • GitHub Actions：CI（ubuntu/windows/macos × Node 20/22 + tarball 检查，7/7 全绿）与 Release（tag 触发）均绿
  • 技能自检安装已在本机真实 ~/.rivet/skills/tianshu-mcp 验证生效且幂等
  • npm 包名 tianshu-mcp 可用
• 天枢宿主真实接入（DoD #6） ✅（2026-09-07，host-integration-record.md）
  • 在真实 D:\Tianshu 桌面宿主 mcp.servers 配置本地模式 → sidecar MCP: 2 servers connected, 10 tools（含本 server 8 工具），spawn 子进程并 stdio 连通
  • 实测暴露并修复技能安装源路径 bug（fileURLToPath，提交 55cf2d0）
• M3 — TraeWork 调研 + 全套交付 ✅（2026-09-07，npm 已发布）
  • T1 定论：本机 TRAE SOLO CN v1.107.1 实测 无无头可编程 agent 接口（仅 VS Code 家族 CLI；见 adapter-matrix.md）
  • npm 已发布：[email protected] 起（npx -y tianshu-mcp 拉起 8 工具连通，见 dod7-release-record.md）
• M4 — TraeWork GUI 驱动接入（CDP） ✅（2026-09-08，见 traework-cdp.md）— 153 测试
  • 结论更正：无头 CLI 确实不存在，但 --remote-debugging-port 可驱动聊天 UI；traework 改为 driver=gui / status=ready
  • 能力：启动/复用实例 → 新建会话 → 绑定项目文件夹（下拉命中优先，未命中走受限 computer-use 原生对话框）→ 可选指定模型 → 任务书回读校验后发送 → 轮询到完成 → 自动验收 → 失败生成修复计划并同会话返修
  • 安全：默认复用用户实例、绝不按进程树强杀、终止前核对命令行；computer-use 仅允许 TraeWork 文件夹对话框
  • 真机验证：run_task(agentId=traework, model=GLM-5.3, autoVerify=true) 驱动 TraeWork 创建文件并验收通过
• M5 — 模式切换 + v0.1.5 发布 ✅（2026-09-08，见 release-v0.1.5.md）— 167 测试
  • run_task 新增 mode（Work/Code/Design），显式参数 + 任务书文本兜底；三种模式真机端到端验证通过
  • 实测关键点：三种模式各自维护独立项目绑定 → 顺序改为「新建会话 → 切模式 → 在目标模式绑定项目」
  • README 重写（中英双语 + 技术栈勋章 + 专属 SVG 图标/横幅）
• M6 — 项目文件夹绑定修复 + v0.1.6 ✅（2026-09-08，见 release-v0.1.6.md）— 172 测试
  • 修复三处叠加缺陷：footer 点击未确认弹窗、检测被 PowerShell 冷启动吃光预算、CJK 路径被控制台代码页破坏
  • 新增非 Work 模式绑定回落 Work 重试；真机验证「不在下拉的新项目 + mode=Code」全链路通过
• M7 — 绑定根因修复 + v0.1.7 ✅（2026-09-08，见 release-v0.1.7.md）— 178 测试
  • 真根因：MCP 传规范化路径（d:/a/b）被 Windows 原生选择器拒绝 → 改用 toNativeWindowsPath()（D:\a\b）
  • 配套：写入后 WM_GETTEXT 回读校验、hwnd 贯穿传递、遗留对话框清理
• M8 — 原子写并发缺陷修复 + v0.1.8 ✅（2026-09-08，见 release-v0.1.8.md）— 181 测试
  • writeJsonAtomic / writeTextAtomic 临时文件名并发共用 → 随机后缀 + rename 退避重试（CI windows/Node20 偶发失败真根因）
• M9 — TraeWork 任务进行中检测 + v0.1.9 ✅（2026-09-09，见 release-v0.1.9.md）— 196 测试
  • 停止按钮 / loading task tail 成为权威运行信号，优先于完成标志；稳定轮数只启动空闲计时（默认 10 分钟）才返回 idle
  • CDP 断线收敛全部 pending + 单次命令 15s 超时；异常结束（idle/timeout/aborted/cdp_lost）保留实例并写 agentEndReason / keptInstance
• M10 — stdio 日志污染修复 + v0.1.10 ✅（2026-09-10，见 release-v0.1.10.md）— issue #1
  • 统一 Logger 所有级别改走 stderr，stdout 只承载 MCP JSON-RPC 消息
  • 新增严格 stdio 冒烟（真实进程字节流校验，6 场景）、Node 24 CI 覆盖与安装包协议门禁
• M11 — ZCode GUI 统一闭环 + v0.2.0（2026-09-11，见 release-v0.2.0.md）— 262 测试
  • Windows 真机通过开发、受控失败后同会话返修、AskUserQuestion → continue_task 三个场景；验收记录
  • macOS 真机未补齐，内置 profile 依计划保持 research

Agent 适配现状

新增 agent 通常只需加一个 profile，详见 docs/agent-profiles.md 与 CONTRIBUTING.md。

推荐用法（给天枢的提示语）

"在项目 D:\xxx 用 codex 实现『任务』。先跑 run_task(autoVerify:true, autoFixRounds:2)，完成后用 query_task 看结果；若报告显示 needs_attention，把 get_task_report 的失败项摘要作为 feedback 调 rework_task 再验一轮；全部通过后向我汇报 changedFiles 与 diffstat。"

"在项目 D:\xxx 用 traework、mode=Code 实现『任务』；它会先切到 Code 模式再绑定项目，然后发任务、自动验收，失败自动生成修复计划并返修。"

开源协作

• 主仓库：https://github.com/lanlan0811/tianshu-mcp（GitHub）
• 镜像仓库：https://gitee.com/lan0811/tianshu-mcp（Gitee）
• 问题反馈：Bug / 功能请求走仓库 Issue 模板；安全漏洞请按 SECURITY.md 私密报告，不要开公开 Issue。

英文版对应文档见 README.en.md。

许可

本项目以 Apache License 2.0 发布，完整法律文本见 LICENSE。版权归 tianshu-mcp 贡献者所有（Copyright 2026 tianshu-mcp contributors）。

授予你的权利

• 商业使用：可在商业产品与服务中使用；
• 修改：可自由修改源码；
• 分发：可再分发原始或修改后的版本；
• 私用：可在组织内部私有使用；
• 专利使用：贡献者授予你实施其贡献所涉专利的许可（受下述终止条款约束）。

你必须履行的义务

1. 保留声明：分发时须随附 LICENSE 全文，并保留其中的版权、许可与免责声明；
2. 标注修改：若修改了文件，须在修改的文件中附带显著的「已修改」声明；
3. 保留 NOTICE：若原作品含 NOTICE 文件，分发时须保留其内容（本项目当前无 NOTICE 文件）；
4. 不得附加限制：不得对本许可授予的权利附加额外限制。

明确不授予 / 授权终止

• 商标：本许可不授予任何商标、商号或服务标记的使用权；
• 专利终止：若你对本项目或其贡献者发起专利诉讼（包括交叉诉讼与反诉），本许可授予你的专利授权自动终止。

免责声明

软件按 「现状」 提供，不附带任何明示或暗示的担保，包括但不限于适销性、特定用途适用性和非侵权担保。在任何情况下，作者或版权持有人均不对因软件、软件的使用或其他交易而产生的任何索赔、损害或其他责任负责（无论是在合同诉讼、侵权诉讼还是其他诉讼中）。

第三方依赖许可

运行时依赖均为 MIT 许可，与 Apache-2.0 兼容：

开发依赖（TypeScript、ESLint、Prettier、Vitest、Vite、tsx 等）各自遵循其开源许可，且不随 npm 发布产物分发。

与安全边界的关系

本 MCP 不保存、不读取、不转发任何 AI-Agent 的 API key 或登录态（详见 SECURITY.md）。许可条款不改变这一设计边界。