tianshu-mcp

<p align="center"> <img src="./assets/tianshu-mcp-banner.svg" alt="天枢编排 MCP tianshu-mcp" width="100%"> </p> <h1 align="center">天枢编排 MCP tianshu-mcp</h1> <p align="center"> <b>把开发交给 AI-Agent，把验收交给运行时 · Dispatch with agents, verify with evidence.</b> </p> <p align="center"> <a href="https://lanaiw.top"><b>官网</b></a> · <a href="https://github.com/lanlan0811/tianshu-mcp"><b>GitHub 主仓</b></a> · <a href="https://gitee.com/lan0811/tianshu-mcp"><b>Gitee 镜像</b></a> · <a href="https://github.com/huiliyi37/Tianshu-harness"><b>天枢 Tianshu</b></a> · 简体中文 · <a href="README.en.md">English</a> </p> <p align="center"> <a href="ARCHITECTURE.md"><b>架构说明</b></a> · <a href="docs/agent-profiles.md"><b>Agent 配置</b></a> · <a href="docs/acceptance-config.md"><b>验收配置</b></a> · <a href="docs/visual-acceptance.md"><b>视觉验收</b></a> · <a href="docs/event-stream.md"><b>事件流</b></a> · <a href="docs/gui-log-viewer.md"><b>日志台 GUI</b></a> · <a href="HANDOFF.md"><b>交接文档</b></a> </p> <p align="center"> <img src="https://img.shields.io/github/actions/workflow/status/lanlan0811/tianshu-mcp/ci.yml?branch=master&style=for-the-badge&logo=github&label=CI" alt="CI"> <img src="https://img.shields.io/npm/v/tianshu-mcp?style=for-the-badge&logo=npm&logoColor=white&label=npm&color=cb3837" alt="npm version"> <img src="https://img.shields.io/github/stars/lanlan0811/tianshu-mcp?style=for-the-badge&logo=github&label=stars&color=24292e" alt="GitHub stars"> <img src="https://img.shields.io/badge/License-Apache%202.0-3B5BDB?style=for-the-badge&logo=apache" alt="License"> <img src="https://img.shields.io/badge/TypeScript-5.7-3178c6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript"> <img src="https://img.shields.io/badge/node-%E2%89%A520-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node"> <img src="https://img.shields.io/badge/MCP%20SDK-1.x-6f42c1?style=for-the-badge" alt="MCP SDK"> <img src="https://img.shields.io/badge/Tests-1383%20Passed-green?style=for-the-badge" alt="Tests"> </p> <p align="center"> <a href="https://www.npmjs.com/package/tianshu-mcp"><img src="https://img.shields.io/npm/d18m/tianshu-mcp?style=for-the-badge&logo=npm&logoColor=white&label=MCP%20%E4%B8%8B%E8%BD%BD%E6%AC%A1%E6%95%B0&color=cb3837" alt="MCP 下载次数（npm）"></a> <a href="https://github.com/lanlan0811/tianshu-mcp/releases?q=v&expanded=true"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Flanlan0811%2Ftianshu-mcp%2Fmaster%2Fupdate%2Fstats.json&query=%24.mcpDownloads&style=for-the-badge&logo=github&logoColor=white&label=MCP%20%E5%8E%8B%E7%BC%A9%E5%8C%85%E4%B8%8B%E8%BD%BD%E6%AC%A1%E6%95%B0&color=2ea44f" alt="MCP 压缩包下载次数（GitHub 发行）"></a> <a href="https://github.com/lanlan0811/tianshu-mcp/releases?q=gui-v&expanded=true"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Flanlan0811%2Ftianshu-mcp%2Fmaster%2Fupdate%2Fstats.json&query=%24.guiDownloads&style=for-the-badge&logo=github&logoColor=white&label=GUI%20%E4%B8%8B%E8%BD%BD%E6%AC%A1%E6%95%B0&color=1f6feb" alt="日志台 GUI 下载次数（GitHub 发行）"></a> </p>

---

<p align="center"> <img src="./assets/mcp-running.png" alt="天枢 harness 桌面端通过 tianshu-mcp 调用 ZCode 完成开发" width="100%"> <br> 天枢 harness 桌面端实况 —— <b>天枢</b>经 MCP 调用 <b>tianshu-mcp</b> 编排 <b>ZCode</b> 完成一次开发任务：左侧派发与跟踪任务，中间是 tianshu-mcp 的工具调用与事件流（<code>mcp__tianshu-mcp__query_task</code> 轮询运行中的任务），右侧 ZCode 正在执行实际开发 </p>

面向 AI-Agent 的编排层与客观验收仪

tianshu-mcp 是被 天枢（Tianshu） 当作标准 MCP server 接入的编排层。天枢是总指挥与用户交互面，本 server 承担三件事：调度（队列 / 并发闸 / 状态机 / 取消）、执行面（把任务书送达外部 AI-Agent）、客观验收仪（相对 git 基线做命令检查、代码分析与可选视觉比对）。

它要回答的核心问题是：Agent 说「做完了」，谁来证明真的做完了。 为此「完成」必须有运行时证据，验收不合格自动生成修复计划并返修，轮次耗尽则交由天枢裁决。

天枢 Tianshu（TUI × GUI）        ← 总指挥 / 交互面 / 裁决
              ↓  MCP over stdio（stdout 仅承载 JSON-RPC）
        tianshu-mcp              ← 调度 · 执行面 · 验收仪
              ↓
Codex · TraeWork · ZCode · Kimi Code · Qoder CN · Open Design · MiniMax Code
              ↓（GUI 经 CDP 驱动桌面 UI；CLI 走子进程）
        目标项目工作区            ← git 仓库 + 测试 + .tianshu-mcp/

• 8 个 MCP 工具（v0.9.0 起由 13 个按域合并）—— run_task / query_task / manage_task / verify_task / query_info / wait_task，外加视觉验收的 prepare_visual_baseline / approve_visual_baseline。合并映射：cancel_task+continue_task+rework_task → manage_task；list_tasks+get_task_report+get_profiles → query_info；wait_any → wait_task（增强）。
• 异步契约，长任务不卡 tools/call —— run_task 秒回 taskId，用 wait_task 阻塞等到停点（终态或 needs_user）、或用 query_task 轮询；进度只落盘、不推送，调用方看到的始终是「最后一次落盘的事实」。
• 等待原语（issue #28；v0.9.0 合并） —— wait_task(taskId) 或 wait_task(taskIds) 一次调用即等到任务到达停点（终态或 needs_user），专为回合驱动调用方设计：run_task 后在本回合内直接等结果，无需自行轮询；纯只读、超时/中断对任务本体零影响。
• 客观验收，fail-closed —— 自动命令检查 + 程序化代码分析，全部相对动工前的 git 基线，绝不自动 commit / stash / 回滚；「测试退出码 0 但零用例」「git 项目零净变更」都判失败，杜绝假绿。
• 失败返修闭环 —— 自动返修（autoFixRounds）+ 手动 rework_task；失败原因被解析为可直接执行的动作随计划喂回 agent，轮次耗尽转 needs_attention 等天枢裁决。
• 六个 GUI 执行面（CDP） —— 各 agent 使用隔离的 CDP 流程驱动桌面 UI，并在关键节点上报细粒度事件，query_task 因此能区分「agent 正在干活」与「卡在弹窗等人工介入」。
• 可扩展 —— 新 agent = 一个 profile（数据）+（如需）一个 adapter 文件，零改编排核心。

[!NOTE] 本 server 是标准 MCP stdio server：stdout 只承载 MCP JSON-RPC 消息，所有级别诊断日志（DEBUG/INFO/WARN/ERROR）写入 stderr 并同源追加到 <数据目录>/logs/server.log。因此 stderr 里出现 INFO / WARN 不代表服务器出错。数据目录默认 ~/.tianshu-mcp，可用环境变量 TIANSHU_MCP_HOME 覆盖。

目录

• 为什么需要编排层与验收仪
• 核心特性
• 快速开始
• 工具面
• 支持的 Agent
• 权限与安全边界
• 运行时契约
• 里程碑
• 日志台 GUI
• 文档导航
• 面向开发者
• 安全
• 社区与支持

为什么需要编排层与验收仪

问题：Agent 说「做完了」，谁来证明

把开发任务交给 AI-Agent 之后，真正的困难不在「它能不能干活」，而在怎么确认它真的干完了、干对了：

• 自述不可信 —— agent 的「已完成」是自然语言结论，不是证据。没有独立验收时，半成品与真交付长得一模一样。
• 环境是黑盒 —— 桌面 agent 的请求在传输层加密（如 TraeWork 的 TTNet 层 TDE），无法在客户端外构造，唯一可行路径是驱动 UI 取结果。
• 宿主工具面很窄 —— 天枢的 MCP 工具只回文本（content[].text 被拼成字符串、isError 透传），且按次同步调用，长任务必须自己异步化，也不能依赖服务端推送。
• 失败后没人接手 —— 验收不通过时，如果没有人把「哪一行错了、该改什么」喂回去，agent 只会重复同一次错误。

本项目的形态不是自由设计的结果，而是这几条实测硬约束逼出来的：

| # | 实测约束 | 架构后果 | |---|---|---| | C1 | 天枢的 MCP 工具只回文本 | 所有结果统一为「人类可读文本 + ---tianshu-mcp-meta--- JSON 块」，便于宿主正则抽取 | | C2 | 天枢按次同步调用 tools/call | 长任务异步化：run_task 秒回 taskId，用 query_task 轮询 | | C3 | 桌面 agent 请求在传输层加密，无法在客户端外构造 | 只能 CDP 驱动桌面 UI，从 DOM 提取结果 | | C4 | Codex 桌面端是 MSIX 商店包，无法直接 CreateProcess | 必须经 COM 激活并注入专属 --user-data-dir 才能开 CDP 端口 |

解法：把「谁来干活」与「怎么算干得好」拆开

• 调度层负责纪律 —— 每项目串行队列 + 全局并发闸（默认 2）、显式状态机、超时与取消语义。
• 执行面负责投递 —— 一份 AgentAdapter 契约：GUI agent 走 CDP 驱动，CLI agent 走子进程；新增 agent 通常只是一个 profile。
• 验收仪负责证据 —— 相对动工前 git 基线做命令检查、代码分析、可选视觉比对，并以 fail-closed 拦住「假绿」；报告分人读 .md 与机读 .json。
• 返修闭环负责收敛 —— 失败轮次把原因解析成可执行动作喂回同一 agent，轮次耗尽转人工裁决。

两条边界是硬性的：agent 的「完成」不是验收结论（只有 verdict.passed 才算）；环境 / 认证类错误不进验收与返修（hardFailure 直接终态失败，避免把基础设施问题当成代码问题烧掉返修轮次）。

核心特性

• 异步派单与等待 —— run_task 秒回 taskId；wait_task 阻塞等到任务到达停点（终态或 needs_user），wait_any 等一组任务的先到者；需要进度细节时用 query_task 看状态 / 进度 / 日志尾 / 最近细粒度事件（eventLimit，1..50，默认 10）。详见 等待原语。
• 客观验收引擎 —— 自动命令检查（typecheck/lint/test/build，缺则跳过 + 技术栈推导）+ 程序化代码分析（变更清单 / diffstat / TODO·debugger·密钥形态等可疑标记），全部相对 git 基线；命令默认有界并行（verifyConcurrency，默认 2，范围 1–4，1 即完全串行）。
• 三项 fail-closed 保护 —— 测试退出码为 0 但零用例判失败；git 项目默认要求相对基线产生变更（纯分析任务可在 .tianshu-mcp/acceptance.json 设 "requireChanges": false 显式关闭）；本轮被取消即 passed=false。
• 验收配置三级继承（issue #20）—— <数据目录>/acceptance.default.json（全局兜底）→ <项目>/.tianshu-mcp/acceptance.json（项目覆盖）→ acceptanceOverride 参数（任务级临时覆盖，不落盘）。用 tianshu-mcp config acceptance <projectPath> [--task <id>] 查看最终生效配置。详见 验收配置规范。
• 结构化修复指令（issue #19）—— 失败轮次把原因解析为可直接执行的动作（文件:行 / 问题 / 做什么），随返修计划与返修消息一起喂给 agent；提取不到时显式回退到完整报告（不静默留空）。rework_task 另可选 repairHint。详见 结构化修复指令。
• dryRun 干跑模式（issue #21）—— run_task(dryRun=true) 让 agent 只分析规划、输出将要修改的文件清单与方案、不动源码；验收只做静态分析（引用文件是否存在、拟改位置是否存在、明显逻辑冲突），跳过 typecheck/test/build；方案有问题 → needs_attention（人工裁决），不进入自动返修、不消耗验收轮次。详见 dryRun 干跑模式。
• 幂等重试（issue #15）—— run_task / verify_task 接受可选 idempotencyKey：同一 key 在 TTL（默认 24h）内重试不重复派单（恒返回原 taskId）或不重跑验收；同键异参 fail-closed 报错。映射落盘于 <数据目录>/idempotency.json，跨 server 重启仍生效。详见 v0.5.10 发布说明。
• 无项目派发（ZCode 专用，issue #12）—— run_task 的 projectPath 可省略，任务在 ZCode 的 default 工作区运行，不登记 / 导入项目、不采集 Git 基线、不执行项目验收（结果以 verificationNotApplicable: "no_project" 结构化标注）。配套 allowCreateProject: false 可在目标目录未登记时于任何导入副作用之前停止派发。详见 ZCode CDP 适配器。
• 细粒度事件流（issue #18）—— 适配器在关键节点上报语义事件（task_dispatched / confirmation_dialog_detected / awaiting_user_authorization / file_modification_started / rework_triggered），query_task 经 eventLimit 回传最近 N 条。事件上报是可选能力：未实现的适配器行为不变。详见 事件流。
• 终态通知 webhook（issue #22）—— 可选 notifications.webhook（全局 config.json）：任务完成 / 失败 / 进入 needs_attention 时向指定 URL 异步 POST 一条 JSON（含 taskId / event / status / 时间戳 / 报告路径），可选 HMAC-SHA256 签名。默认关闭，发送失败只记日志、绝不影响状态机。详见 任务终态通知。
• 视觉验收（可选模块，v0.5.0 起） —— 页面截图对比、静态图片规格校验、基准两阶段批准与规则冻结；缺基准不得判通过，自动返修禁止调用批准入口。另有可选 AI 内容校验（v0.5.4，默认关闭）：判定完全委托给你自备的本地命令，MCP 不读取 / 不存储 / 不转发任何密钥、不内置模型客户端，默认仅告警。详见 视觉验收。
• 技能自检安装（issue #16）—— 启动时把包内 skills/tianshu-mcp/ 幂等同步到 ~/.rivet/skills/tianshu-mcp/；仅在可证未被改动时自动升级，检出本地修改或来源不明一律保留 + 告警。详见 运行时契约。
• 独立交付面：日志台 GUI —— mcp-gui/ 提供本地只读的桌面应用，把四类日志与任务产物统一到一个界面（Tauri 2.x + Vue 3，独立版本与 tag，不随 MCP 主包发布）；详见 日志台 GUI。
• 不碰密钥 —— 各 agent 使用自己的登录态，本 server 不保存 / 转发任何 API key（详见 SECURITY.md）。
• 想理解内部结构 —— 见 ARCHITECTURE.md（分层模型、模块边界、状态机、验收流水线、扩展点与已知缺口）。

快速开始

前置条件

| 项 | 要求 | |---|---| | Node.js | ≥ 20（CI 覆盖 20 / 22 / 24） | | 包管理器 | npm（仓库含 package-lock.json） | | 操作系统 | Windows / macOS / Linux（CI 三平台矩阵验证） | | Git | 可选；验收的基线分析在 git 仓库内更完整 |

数据目录默认 ~/.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             # 1383 passed / 12 skipped（1395 项，115 个测试文件）

安装 npm 包

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

在天枢里添加（推荐）

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

| 字段 | npm 分发（推荐） | 本地开发 | |---|---|---| | 服务器 ID | tianshu-mcp | tianshu-mcp | | 传输方式 | stdio（本地进程） | stdio（本地进程） | | 命令 | npx | node | | 参数（空格分隔） | -y tianshu-mcp | <仓库绝对路径>/dist/index.js |

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

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

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

新开会话后，工具面出现 mcp__tianshu-mcp__run_task 等 8 个工具（v0.9.0 起）。一次典型闭环：

run_task(projectPath=D:/xxx/my-app, task="…任务书…", agentId=codex,
         model="GPT-5.6 Sol", reasoningLevel="高", autoVerify=true, autoFixRounds=5)
  → taskId → wait_task(taskId) 阻塞等到停点 → succeeded / failed / needs_attention → get_task_report 读报告
  （回合驱动调用方：wait_task 一次调用即等到停点；超时返回后再次调用本工具继续等待，或用 query_task 看进度细节）

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

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

「