tianshu-mcp
This server is an MCP orchestration layer that dispatches work to AI agents, tracks tasks asynchronously, and verifies outcomes objectively against a Git baseline.
Dispatch development tasks to supported GUI/CLI agents (Codex, ZCode, Kimi Code, Open Design, MiniMax Code, and custom spawn profiles), with options for model, reasoning level, context window, plan docs, dry runs, auto-verification, auto-rework, and idempotent retries.
Query task status, progress, recent log tails, and fine-grained agent events; wait for a single task or a batch of tasks to reach a stop point.
Manage task lifecycle: cancel running tasks, continue
needs_usertasks with a message, or rework failed/needs_attentiontasks with feedback and structured repair hints.Run acceptance verification with command checks and code analysis relative to the pre-work Git baseline, including extra checks and fail-closed protections; verification does not modify source code.
Query historical tasks, retrieve full verification reports for specific rounds, and inspect configured agent profiles and executable detection results.
Prepare visual baseline candidates and approve visual baselines only after explicit user review and digest validation; approval is destructive and requires approval controls.
Enables verification of agent changes against a Git baseline, including command checks, code analysis, diffstat, and fail-closed detection of missing net changes.
Provides tools for dispatching and controlling OpenAI Codex desktop agent tasks via CDP, including task execution, monitoring, cancellation, and handling login/confirmation states.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tianshu-mcp Have Codex implement the login page in D:/my-app, verify and rework up to 2 rounds"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
面向 AI-Agent 的编排层与客观验收仪
tianshu-mcp 是被 天枢(Tianshu) 当作标准 MCP server 接入的编排层。天枢是总指挥与用户交互面,本 server 承担三件事:调度(队列 / 并发闸 / 状态机 / 取消)、执行面(把任务书送达外部 AI-Agent)、客观验收仪(相对 git 基线做命令检查、代码分析与可选视觉比对)。
它要回答的核心问题是:Agent 说「做完了」,谁来证明真的做完了。 为此「完成」必须有运行时证据,验收不合格自动生成修复计划并返修,轮次耗尽则交由天枢裁决。
天枢 Tianshu(TUI × GUI) ← 总指挥 / 交互面 / 裁决
↓ MCP over stdio(stdout 仅承载 JSON-RPC)
tianshu-mcp ← 调度 · 执行面 · 验收仪
↓
Codex · ZCode · Kimi Code · 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 文件,零改编排核心。
本 server 是标准 MCPstdio server:stdout 只承载 MCP JSON-RPC 消息,所有级别诊断日志(DEBUG/INFO/WARN/ERROR)写入 stderr 并同源追加到 <数据目录>/logs/server.log。因此 stderr 里出现 INFO / WARN 不代表服务器出错。数据目录默认 ~/.tianshu-mcp,可用环境变量 TIANSHU_MCP_HOME 覆盖。
目录
Related MCP server: tianshu-mcp
项目图解
五幅概念插画,概括本 server 的形态与机制(插画为概念示意,非逐字对应的结构图);其后是按源码实测规模绘制的结构导图,用于快速建立分层认知。
为什么需要编排层与验收仪
问题:Agent 说「做完了」,谁来证明
把开发任务交给 AI-Agent 之后,真正的困难不在「它能不能干活」,而在怎么确认它真的干完了、干对了:
自述不可信 —— agent 的「已完成」是自然语言结论,不是证据。没有独立验收时,半成品与真交付长得一模一样。
环境是黑盒 —— 桌面 agent 的请求在传输层加密(如 ZCode 的 TTNet 层 TDE),无法在客户端外构造,唯一可行路径是驱动 UI 取结果。
宿主工具面很窄 —— 天枢的 MCP 工具只回文本(
content[].text被拼成字符串、isError透传),且按次同步调用,长任务必须自己异步化,也不能依赖服务端推送。失败后没人接手 —— 验收不通过时,如果没有人把「哪一行错了、该改什么」喂回去,agent 只会重复同一次错误。
本项目的形态不是自由设计的结果,而是这几条实测硬约束逼出来的:
# | 实测约束 | 架构后果 |
C1 | 天枢的 MCP 工具只回文本 | 所有结果统一为「人类可读文本 + |
C2 | 天枢按次同步调用 | 长任务异步化: |
C3 | 桌面 agent 请求在传输层加密,无法在客户端外构造 | 只能 CDP 驱动桌面 UI,从 DOM 提取结果 |
C4 | Codex 桌面端是 MSIX 商店包,无法直接 | 必须经 COM 激活并注入专属 |
解法:把「谁来干活」与「怎么算干得好」拆开
调度层负责纪律 —— 每项目串行队列 + 全局并发闸(默认 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(仓库含 |
操作系统 | 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 |
|
|
传输方式 |
|
|
命令 |
|
|
参数(空格分隔) |
|
|
服务器 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。」
「在项目
D:\xxx用 opendesign、designDirection=prototype实现『任务』;它会按设计方向驱动 Open Design 桌面端,然后发任务、自动验收,失败自动生成修复计划并返修。」
工具面
8 个工具(v0.9.0 起由 13 个按域合并),按能力分为三族:read(读 / 查询,无副作用)、write(有副作用,全部需审批)、execute(执行项目侧命令但不改源码,当前仅 verify_task,仍免审批)。
工具 | 能力 / 审批 | 作用 |
| write + 审批 | 派活(可带自动验收 / 自动返修),异步返回 |
| read | 轮询状态 / 进度 / 日志尾 / 最近细粒度事件(可选 |
| write + 审批 | 任务生命周期管理, |
| execute(不改源码,免审批) | 对任务 / 项目路径做一次验收。会跑项目配置命令、可能产生构建产物,故 MCP |
| read | 统一信息查询, |
| read | 阻塞等待任务到达停点(终态或 |
| write + 审批 | 截图或导入参考图,生成待审阅候选和摘要 |
| write + 审批 | 用户审阅后校验摘要并写入基准与审批记录 |
返回统一为「人类可读文本 +
---tianshu-mcp-meta---JSON 块」,便于宿主正则抽取。路径安全闸门(v0.4.0 起):
projectPath在提交时校验——必须绝对路径、目录必须存在、符号链接经 realpath 归一;主目录本身与系统 / 根级目录直接拒绝,防止 worker 写权限覆盖整棵系统子树;git 仓库有未提交变更时回执附带共处警示。
支持的 Agent
driver: "gui" 由显式 adapter 驱动桌面 UI(各自使用隔离的 CDP 流程);driver: "spawn" 走外部 CLI 子进程。
agentId | driver / adapter | status | 说明 |
|
| ready(macOS 为 | Codex 桌面端 GUI(Windows:MSIX COM 激活 + CDP;macOS:spawn .app + CDP);支持 |
|
| ready(Windows 真机闭环;macOS 未验证) | CDP GUI adapter;支持无项目派发、 |
|
| ready(macOS 为 | Kimi Code 桌面端(Electron);双渲染进程(主窗口 + |
|
| ready(macOS 为 | Open Design 桌面端 GUI;选择器取自产品自身 Web 前端的 |
|
| ready(macOS 为 | MiniMax Code 桌面端(Electron);双渲染进程(主窗口 + |
|
| 仅测试 |
|
mode已废弃(v0.9.9 起):它是早期 GUI 适配器的 Work / Code / Design 面板模式,该适配器已移除,现没有任何适配器消费;传入会被 handler 统一拒绝并提示改用designDirection(Open Design)。Kimi Code 的reasoningLevel按界面实际渲染的档位集合校验(官方模型低/高/max,非官方模型仅on/off)。MiniMax Code 的reasoningLevel/contextWindow同样按界面实际候选校验(如M3.1-Flash-Preview为default/low/medium/high/xhigh/max与512K/1M,而M3无档位组、deepseek-v4.1-flash无窗口组),越权或读不到即 fail-closed。新增 agent 通常只需加一个 profile,详见 docs/agent-profiles.md 与 CONTRIBUTING.md。
macOS 无头路径:codex-cli(用户 profile)
内置 codex 走桌面端 GUI 驱动;若不想依赖 GUI 自动化,codex CLI 无头模式在 macOS 全程可用——无需改 server 代码,在数据目录加一个 driver=spawn 的用户 profile 即可:
{
"profiles": {
"codex-cli": {
"displayName": "Codex CLI (OpenAI 无头)",
"type": "cli",
"driver": "spawn",
"status": "ready",
"command": null,
"argsTemplate": ["exec", "<prompt:arg>", "--skip-git-repo-check", "--sandbox", "workspace-write"],
"promptMode": "arg",
"cwd": "task",
"env": {},
"timeoutMs": 1800000,
"killTree": "taskkill",
"authNote": "复用 ~/.codex 登录态;勿与 --approve-for-me 同用(实测互斥)",
"executableDiscovery": {
"dirs": ["/opt/homebrew/bin", "/usr/local/bin"],
"fileNames": ["codex"],
"fallbackCommand": "codex"
}
}
}
}前置:
npm i -g @openai/codex(⚠️ 请保持最新,≤0.130.0 签名证书已被吊销,macOS Gatekeeper 会直接Killed: 9)并已codex login。用法与内置 agent 一致:
run_task(projectPath=/path/to/项目, agentId=codex-cli, task="任务书", autoVerify=true, autoFixRounds=2)。model参数对 spawn agent 不生效——CLI 使用~/.codex/config.toml的默认模型;要锁模型可在argsTemplate追加"-m", "<模型名>"。
权限与安全边界
能力三族
能力 | 含义 | 审批 | 工具 |
| 只读 / 查询,无副作用 | 免审批 |
|
| 有副作用 | 需审批 |
|
| 执行项目侧命令,不改源码 | 免审批 |
|
readOnlyHint由capability === "read"推导,因此verify_task的该注解为 false;它不是审批信号——审批与否由_meta.requireApproval单独承载。
硬性红线
绝不按进程树盲杀 GUI 实例 —— 只终止本模块创建、且命令行核对通过的 PID。
默认复用用户实例 —— 绝不新起第二个;受管实例也不触碰用户手动打开的实例。
computer-use 白名单 —— 原生文件夹选择对话框需经窗口标题 + 宿主进程双校验,其余窗口一律拒绝。
凭证零管理 —— 不读取 / 解密 / 转发任何 agent 凭证;GUI adapter 只驱动 UI。
命令不拼 shell —— 验收命令是结构化 argv,
shell:false。不自动 commit / stash / 回滚 —— 动工前采集 git 基线,报告相对基线计算。
路径不硬编码 —— 机器路径 / 用户名 / 端口走 profile 或占位符。
stdout 只承载 JSON-RPC —— 所有诊断日志走 stderr(并同源追加到
logs/server.log)。技能内容只来自包自身 —— 待安装技能经
import.meta.url相对包定位,不从process.cwd()发现内容。
运行时契约
stdio 与日志
本 server 严格遵守 MCP stdio 传输契约:stdout 只承载 JSON-RPC 消息,任何诊断日志都写入 stderr 并同源追加到 <数据目录>/logs/server.log(UTF-8,ISO 时间戳,含级别标签)。排查连接问题时以 server.log 为准;不要因为 stderr 有输出就判定 server 异常。只有启动失败(tianshu-mcp 启动失败:)才是致命错误,并会以非 0 退出码结束。
数据目录
<数据目录>/ 默认 ~/.tianshu-mcp(可用 TIANSHU_MCP_HOME 覆盖)
├── config.json server 配置(并发、超时、技能开关、通知)
├── agent-profiles.json 用户自定义 / 覆盖的 agent profile
├── projects.json 项目登记表(含每项目验收配置)
├── idempotency.json 幂等键映射(TTL + 容量裁剪)
├── logs/server.log 全级别诊断日志(与 stderr 同源)
└── tasks/<taskId>/ 单任务隔离目录(事件流 / 报告 / 日志 / 视觉证据)技能自检安装
启动时把包内 skills/tianshu-mcp/ 幂等同步到 ~/.rivet/skills/tianshu-mcp/,让宿主在新会话里读到编排技能。三个要点:
技能内容只来自包自身 —— 源目录由
import.meta.url相对定位(dev 直跑与 dist 运行都指向包内skills/),不从当前工作目录发现内容。找不到源时跳过安装并告警。不一致时不静默覆盖 —— 安装目录内维护清单
<目标>/.tianshu-mcp-install.json(版本 + 内容 hash),据此仅在可证未被改动时自动升级;检出你改过文件或来源不明 → 默认保留你的版本并告警。覆盖是原子的 —— 先装到
.incoming-*,再备份旧目录为.bak-<时间戳>,最后换入;失败回滚,不留半成品。
// <数据目录>/config.json
{
"skills": {
"autoInstall": true, // true(默认)| "prompt" | false
"backupKeep": 3 // 覆盖后保留的历史备份个数;0 = 不清理
}
}放行与关闭(命令行参数或等价环境变量;--no-skill-install / autoInstall:false 的否决权最高):
--approve-skill-update(或TIANSHU_MCP_APPROVE_SKILL_UPDATE=1):本次启动允许「需变更」的技能目录由包内版本覆盖(先备份)。对已确证含用户本地修改的目录不生效。--no-skill-install(或TIANSHU_MCP_NO_SKILL_INSTALL=1):本次启动不做任何技能安装与检查。
里程碑
阶段 | 版本 | 交付概要 |
编排骨架 | 0.1.x | 8 工具、状态机 / 队列 / 并发闸 / 取消(kill tree)、验收引擎、自动返修;首个 CDP 桌面驱动接入 |
ZCode GUI | 0.2.0 | ZCode 统一闭环(开发 → 受控失败 → 同会话返修 → |
Codex 桌面端 | 0.3.x | Codex MSIX COM 激活 + CDP(破坏性: |
macOS 与闸门 | 0.4.x | macOS 双驱动(spawn .app + CDP)、 |
视觉与幂等 | 0.5.x | 视觉验收(0.5.0)+ 可选 AI 内容校验(0.5.4)、ZCode 无项目派发、Kimi Code / Open Design 适配、幂等键(0.5.10) |
加固与可观测 | 0.6.x | 技能自装加固(0.6.0)、GUI 选择器漂移修复(0.6.2)、细粒度事件流、结构化修复指令、dryRun、验收配置三级继承、终态通知 |
Open Design | 0.7.x | Open Design 桌面端适配(0.7.1)、ZCode 3.14.x 绑定契约修复(0.7.4) |
MiniMax Code | 0.7.8 | 第七个 GUI agent 接入(0.7.8);真机取证修正三处结构假设(二级子菜单 / 集合随模型变化 / 项目创建两步),新增 |
恢复语义修正 | 0.8.0 | TraeWork 移除跨模式项目绑定兜底(#35:兜底结构性不可达且静默改写目标模式);ZCode 恢复轮保留原会话权限(#30:发送前无条件覆盖默认值已移除) |
完成判定加固 | 0.8.1 | 四个 driver(ZCode / Kimi Code / MiniMax Code / Open Design)补上「曾观测到运行信号」门(#31:选择器漂移时不再把进行中的任务误判成功); |
Codex 模型回读 | 0.8.2 | 模型触发器回读改读结构(#34:真机按钮的 |
TraeWork 绑定链路 | 0.8.3 | footer 点击改「副作用驱动三级阶梯」(#38: |
工具面瘦身 | 0.8.4 |
|
CDP 底座重构 | 0.9.8 |
|
移除 TraeWork | 0.9.9 | 破坏性:彻底移除 |
移除 Qoder CN | 0.9.10 | 破坏性:彻底移除 |
参数面收敛 | 1.0.0-beta.1 | 移除 TraeWork 专属的 |
脚本与 CI 收口 | 1.0.0-beta.2 | 删已移除 agent 的探针/冒烟脚本与 CDP 文档( |
文档收口与零残留门禁 | 1.0.0-beta.3 | 文档全量收口 + 新增常驻门禁 |
日志台 GUI |
|
|
完整逐版记录见 CHANGELOG.md,交接状态与排障手册见 HANDOFF.md,工程质量口径见 ARCHITECTURE.md。
日志台 GUI
mcp-gui/ 是本仓库的第二个交付面(issue #25):一个本地只读的桌面应用(Tauri 2.x + Vue 3 + Vite + TypeScript),把 MCP 落盘的日志与任务产物统一到一个界面里查看。它与 MCP server 的关系只有一条——共享同一批落盘事实,不产生第二个事实来源:
不依赖 server 在运行 —— 纯读文件系统,数据目录按与 server 完全相同的规则解析(
TIANSHU_MCP_HOME→~/.tianshu-mcp),并可在多个数据目录之间切换 / 追加 / 移除。只读消费方 —— 全程不改动任何业务数据(唯一写入是应用自身偏好,落在系统应用配置目录),也不替代面向机器的
query_task/get_task_report。四类日志与产物 —— 全局运行日志、任务事件流、原始执行日志、验收报告;视觉离线 HTML 在 sandbox iframe 中渲染(禁用脚本、阻断外部资源)。
数据源 | 路径(相对数据目录) | 界面位置 |
全局运行日志 |
| 工作区 · 运行日志 |
任务事件流 |
| 工作区 · 事件流 |
原始执行日志 |
| 工作区 · Agent 日志 / 验收日志 |
验收报告 |
| 工作区 · 验收报告 |
主要能力:
大日志与实时跟随 —— 首屏只读尾部 64 KiB 窗口、向前按块加载并显示「已加载 N / 共 M」;文件被追加时增量刷新,上翻自动暂停跟随,可一键「跳到最新」。
洞察(效能 / 归因 / 趋势) —— 只读聚合:按 Agent 与按项目的效能看板(任务数 / 成功率 / 平均轮次 / 一次通过率 / 平均验收耗时 / 报告缺失)、四类失败归因 TOP 列表(
errorType/ 失败检查项 / 阻塞问题 / 代码信号)、按天 / 按周的任务量与成功率、返修率趋势(纯内联 SVG,不引图表库)。口径显式标注(UTC 日期、周一为周始、「一次通过」= 成功且仅 1 轮、只统计每个任务的最新一轮报告),只读统计、不提供删除 / 清理。结构化筛选 / 多任务对比 / 命令面板 —— 概览页筛选新增错误类型 / 干跑 / 返修 / 视觉验收四项(口径与任务快照字段一一对应,前后端同口径);洞察页新增「任务对比」子分区,勾选 2–4 个 任务并排看状态 / 轮次 / 验收耗时 / 改动行数 / 最新报告判定等指标(报告按需读取并缓存,缺失一律显示
—,不编造);Ctrl/Cmd + K打开命令面板(子序列模糊匹配,跳页面 / 切数据目录 / 直接打开任务),Ctrl/Cmd + R刷新,全部为只读交互。基线与复盘 / 阶段甘特 / 磁盘占用 / 深链 —— 工作区新增**「基线」分区(动工前
baseline.json摘要并与最新报告改动对照,缺失如实提示);事件流新增「阶段」视图**(状态跃迁甘特,按需读一次全量,最后一段标「进行中」不编造时长);洞察页新增**「磁盘占用」**(总量 / logs 占比 / 体积 TOP 20 / 只提示不删除的「可清理」相对判据);支持tianshu://task/<任务ID>深链(冷启动 + 热启动、单实例唤出已有窗口,Rust 侧处理故不给 webview 多余权限)。报告与多轮对比 ——
.md渲染、.json结构化卡片、视觉.html沙箱预览;dry-run-report-*与report-*分开展示(静态分析 vs 真实命令验收,结论口径不同),多轮报告可并排对比。界面与主题 —— 中英双语、跟随系统 / 浅色 / 深色三选一;自研「黑曜石终端」设计系统,零 UI 库、零外链、零字体文件,图标一律内联 SVG。
系统托盘与关闭行为 —— 常驻托盘(「显示日志台 / 退出日志台」,文案随界面语言即时切换),默认 关闭窗口 = 缩小到托盘,可在设置面板改为「关闭应用」。
更新日志窗口与双源自动更新 —— 启动静默检查更新,命中即弹「更新日志」(下载并安装 / 忽略此版本 / 稍后),正文即该版本的双语发行说明,与发行页同源同一份(正文缺失即拒绝发版,不产出空正文 / 单行标题);更新源由 Gitee / GitHub 并发实测择优(不依赖系统区域)决定并如实展示,包体经 minisign 验签,验签不通过一律拒绝安装。
解耦与发布边界(改这里之前先读):
边界 | 约定 |
数据 | GUI 只读业务目录;唯一写入是应用自身偏好与用户显式选择的导出 / 更新文件 |
代码 |
|
打包 | 根 |
发版 | GUI 独立版本号与独立 tag( |
构建 | 本机不执行 Rust 侧构建与检查( |
双份 schema 的防漂移:事件分类在 Rust 侧与前端各有一份镜像,真源始终是
src/tasks/task.ts与src/agents/agent-events.ts;mcp-gui/scripts/check-schema-parity.mjs在 CI 中做三方集合比对,任一不一致即 fail。使用与开发说明见 日志台文档,真机记录见 issue-25 记录。
文档导航
使用与集成
文档 | 说明 |
架构说明:分层模型与模块边界、状态机、验收流水线、驱动层契约、扩展点与已知缺口 | |
核心原理分析:四条硬约束如何逼出当前架构、核心机制逐条拆解与自洽性总结 | |
天枢 config.json 两种接入模式、UI / API 操作、冒烟步骤、FAQ | |
agent profile 字段说明 + 真实机器样例 | |
各 Agent 能力调研矩阵 | |
npm 发布步骤与凭证说明 | |
教天枢编排本 MCP 的技能(含使用示例) |
Agent 适配(CDP 驱动)
文档 | 说明 |
Codex 桌面端:MSIX COM 激活、CDP 接管、选择器、运行检测、验收返修 | |
ZCode:安装探测、精确项目 / 模型、完全访问、暂停继续、无项目派发与双平台状态 | |
Kimi Code:双渲染进程、工作区完整路径绑定与原生导入、模型三级选择与思考档位 | |
Open Design:数据目录推导、sidecar 根进程判定、选择器取证表与 12 步执行链、传输层双路径、失败码表 | |
docs/minimax-cdp.md | MiniMax Code:双渲染进程、模型二级子菜单(推理等级 / 上下文窗口)与逐模型候选、完整路径项目绑定、 |
验收与可观测
文档 | 说明 |
项目级与三级继承的验收配置规范 | |
结构化修复指令:来源、回退语义与已知限制 | |
dryRun 干跑模式:只读约束、零改动门禁、方案文档 | |
细粒度事件流:词表、落盘与读取侧有界窗口 | |
docs/notifications.md | 任务终态通知:webhook 契约、去重与签名 |
docs/wait-task.md | 等待原语: |
视觉验收入门与完整配置(含可选 AI 内容校验) | |
视觉验收验证进度与平台证据 | |
上述验证的原始机器可读记录 | |
日志台 GUI( |
真机验收记录
文档 | 说明 |
M2 真实 codex 冒烟与 rework 闭环记录 | |
docs/zcode-windows-smoke.md · docs/zcode-issue-8-10-validation.md · docs/zcode-issue-12-windows-evidence.md | ZCode Windows 真机验收记录 |
Codex Windows 真机验收记录(含失败 → 自动生成计划 → 返修通过) | |
docs/host-integration-record.md · docs/issue-1-host-reconnect-record.md | 天枢宿主真实接入与重连验收 |
docs/dod7-release-record.md · docs/dod8-session-record.md · docs/s7-session-recheck.md | npm 发布、真实会话实测与二次整改复测 |
docs/issue-16-skill-install-hardening-record.md · docs/issue-17-small-fixes-record.md · docs/issue-23-selector-drift-record.md | 技能自装加固、小项扫尾、选择器漂移记录 |
docs/issue-18-21-real-machine-record.md · docs/issue-19-22-real-machine-record.md | 事件流 / 修复指令 / dryRun / 验收继承 / 通知的真机记录 |
docs/issue-25-gui-real-machine-record.md · docs/gui-0.1.0-release-record.md | 日志台 GUI 真机验收与正式版发布记录 |
面向开发者
Node.js ≥ 20 · TypeScript 5.7 · Vitest · tsup-free(tsc 直出 dist/)+ tsx 开发。
npm ci
npm run build # sync-version + tsc → dist/
npm test # 全量用例
npm run typecheck # 类型检查(tsc --noEmit)
npm run lint # ESLint(--max-warnings 0)
npm run check:stdio # 严格 stdio 冒烟(真实进程字节流校验)新增 CLI agent —— 通常只需在
<数据目录>/agent-profiles.json加一个driver: "spawn"的 profile,零改代码。新增 GUI agent —— 新写一个 adapter 目录(
adapter.ts/discovery.ts/cdp.ts/selectors.ts/project.ts/liveness.ts/run.ts),并在agents/registry.ts与agents/builtin.ts注册。新增 MCP 工具 ——
src/mcp/tools.ts增元数据 +src/mcp/handlers.ts增实现 +src/config/schema.ts增入参 schema。调 UI 选择器 —— profile
gui.selectors覆盖(客户端升级导致选择器漂移时,先用npm run probe:*诊断)。版本号三处必须同步:
package.json、package-lock.json、src/version.generated.ts(后者由scripts/sync-version.mjs在 build 前生成,勿手改)。
安全
路径边界强制 ——
projectPath经 realpath 归一;主目录与系统 / 根级目录子树拒绝;glob/grep/diff 拒绝..穿越。不自动改动仓库历史 —— 动工前采集 git 基线,报告相对基线计算;MCP 从不自动 commit / stash / checkout。
凭证零管理 —— 不读取 / 解密 / 转发任何 agent 凭证;AI 内容校验同样不引入凭证管理——判定命令自己管密钥。
命令不拼 shell —— 验收命令是结构化 argv,
shell:false,无 shell 注入面。桌面自动化边界 —— 默认复用用户实例、computer-use 白名单、归属核对后才终止进程。
安全漏洞请按 SECURITY.md 私密报告,不要开公开 Issue。
社区与支持
使用问题 / 讨论 → GitHub Issues(附
logs/server.log输出可加速定位)主仓库 → https://github.com/lanlan0811/tianshu-mcp(GitHub)
镜像仓库 → https://gitee.com/lan0811/tianshu-mcp(Gitee)
贡献代码 → CONTRIBUTING.md · 安全模型 → SECURITY.md · 行为准则 → CODE_OF_CONDUCT.md
交接状态 / 排障手册 → HANDOFF.md · 版本变更 → CHANGELOG.md · 依赖清单 → DEPENDENCIES.md
贡献者
感谢以下通过 Issue 与 PR 为本项目做出贡献的社区成员(按首次参与顺序排列):
Star History
许可证
本项目以 Apache License 2.0 发布,完整法律文本见 LICENSE。版权归 tianshu-mcp 贡献者所有(Copyright 2026 tianshu-mcp contributors)。简言之:你可以商业使用、修改、分发与私用,并获授贡献者专利许可;分发时须随附 LICENSE 全文并标注修改;本许可不授予商标使用权,对贡献者发起专利诉讼将导致专利授权自动终止;软件按「现状」提供,不附带任何担保。
第三方依赖许可
运行时依赖的许可如下(完整依赖清单——逐项版本、开发依赖、桌面端 Rust 依赖、间接依赖许可证分布与 SBOM 复现命令——见 DEPENDENCIES.md):
依赖 | 许可 | 用途 |
MIT | MCP 协议实现 | |
MIT | 外部输入校验 | |
MIT | 跨平台子进程 | |
Apache-2.0 | 视觉验收驱动无头浏览器 | |
Apache-2.0 | 托管 Chrome/Edge 的安装与版本锁定 | |
ISC | 页面截图像素比对 | |
| Apache-2.0 | 图片解码与规格校验;缺失时视觉模块明确阻塞 |
sharp本体为 Apache-2.0,但其可选平台二进制(@img/sharp-*)声明为 LGPL-3.0-or-later,以未修改的预编译动态库使用——不安装sharp时依赖树中不含任何 LGPL 组件。
开发依赖(TypeScript、ESLint、Prettier、Vitest、Vite、tsx 等)各自遵循其开源许可,且不随 npm 发布产物分发。
与安全边界的关系
本 MCP 不保存、不读取、不转发任何 AI-Agent 的 API key 或登录态(详见 SECURITY.md)。许可条款不改变这一设计边界。
英文文档见 README.en.md 与 ARCHITECTURE.en.md;完整文档地图与状态快照见 HANDOFF.md。
Available Tools
8 toolsapprove_visual_baselineapprove_visual_baselineADestructive
仅在用户明确审阅并授权后批准视觉基准。必须核对候选摘要与批准说明;自动返修禁止调用。宿主必须实施实际审批控制。
Inputs: candidateId (required), approvalNote (required), expectedDigest (required), taskId.
manage_taskmanage_taskADestructive
任务生命周期管理(合并原 cancel_task / continue_task / rework_task),用 action 区分:action=cancel 取消运行中任务(CLI 终止进程树;GUI 点击界面停止按钮并等待空闲,未确认停止时结果中明示。排队中任务直接移除。对已终态的 GUI 任务兼任人工确认入口:核实窗口无残留运行后调用可清除 guiStopUnconfirmed 标记)——可选 reason 为取消原因;action=continue 恢复 needs_user 状态的任务(message 必填):zcode 在 agent_question 时把 message 发往原会话,关闭旧实例/登录/系统权限场景中 message 仅作已处理确认;codex 的 user_confirmation 重新接入观察(不发送消息)、login_required 复检环境后重发任务书;kimicode/minimax 的 agent_question 把 message 发往原会话。审批或环境处理后仅恢复观察,提交不明时禁止重发;action=rework 手动返修终态任务(failed/needs_attention)重新入队续跑,同一 agent/项目与轮次记账:feedback 为追加指示(建议带上一次验收失败摘要),repairHint 为可选的结构化修复提示(自由字符串,上限 4000 字符)——写「文件:行 / 问题 / 做什么」,会以【结构化修复提示】块置于 feedback 之前,不传则行为不变。注意:本工具含破坏性 action(cancel / rework)。
Inputs: action (required), taskId (required), reason, message, +2 more.
prepare_visual_baselineprepare_visual_baselineA
准备视觉基准候选,返回摘要与预览;不采用正式基准。需要用户授权。
Inputs: projectPath (required), caseIds, imports, viewportIds.
query_infoquery_infoARead-only
统一信息查询入口(合并原 list_tasks / get_task_report / get_profiles),用 type 区分:type=tasks 列出历史任务(可按 projectPath / status 过滤,limit 默认 50、上限 200);type=report 取某轮验收报告全文 report.md(taskId 必填,round 0-based、缺省取最新一轮);type=profiles 查看当前 agent 适配与可执行探测结果(含未安装/调研占位提示)。
Inputs: type (required), limit, round, status, +2 more.
query_taskquery_taskARead-only
查询任务状态 / 进度 / 最近日志尾部(默认 agent.log 末 40 行)/ 最近细粒度事件。返回任务 meta 与日志片段。meta.recentEvents 为最近 N 条 agent 事件(eventLimit 缺省 10、上限 50),取值 task_dispatched / confirmation_dialog_detected / awaiting_user_authorization / file_modification_started / rework_triggered —— 长任务下可据此区分「正常执行」与「卡在弹窗等人」。未实现事件上报的适配器该数组为空,其余字段不变。
Inputs: taskId (required), tailLines, eventLimit.
run_taskrun_taskAIdempotent
派活:启动外部 AI-Agent 开发任务并可自动验收返修,异步返回 taskId。ZCode 要求 model=供应商/模型。mode 与 modelSource 已废弃(原为已移除的 GUI 适配器参数),传入会被拒绝(设计取向请改用 designDirection)。task/context 内的 ZCode 项目路径引用会在发送前校验。思考等级按界面实际档位核对,权限模式不变;macOS research 禁止派发。可选 idempotencyKey(1..128 字符):同一 key 在 TTL(默认 24h)内重复提交恒返回原 taskId 与当前状态、不新建任务,参数变更则报冲突——重试请复用同一 key。 可选 dryRun=true 进入干跑模式(先审后做):agent 只分析规划、输出将要修改的文件清单与方案、不动源码;验收引擎只做静态分析(引用文件是否存在、拟改位置是否存在、明显逻辑冲突),跳过 typecheck/test/build。dryRun 需提供 projectPath、忽略 autoVerify、不进入自动返修;产物为独立报告(meta.dryRunReportFiles,不消耗验收轮次)与方案文档(meta.dryRunPlanDoc,可直接作为后续正式任务的 planDoc)。默认关闭。
Inputs: task (required), mode, model, dryRun, +16 more.
verify_taskverify_taskBIdempotent
对已完成任务或项目路径执行一次验收(不改源码):自动命令检查 + 代码分析(相对 git 基线)。可用 extraChecks 临时加验。需任务/项目二选一。可选 idempotencyKey:同一 key 重试不重跑验收——执行中的同键请求返回进行中提示,已完成的直接返回既有报告与轮次,参数变更则报冲突。
Inputs: taskId, checksMode, baselineRef, extraChecks, +3 more.
wait_taskwait_taskARead-only
等待任务到达停点(阻塞只读原语,合并原 wait_task / wait_any)。单任务模式:提供 taskId,轮询至终态(succeeded/failed/needs_attention/cancelled/interrupted)或 needs_user。批量模式:提供 taskIds(1..20 个,开始前校验全部存在、缺一即报错),等待数组顺序首个到达停点者,返回其快照与全部任务当前状态。两参数必须且只能提供一个。超时(timeoutMs 缺省 50000ms、上限 600000ms)后返回当前状态快照;超时返回时请再次调用本工具继续等待——本调用不影响任务本体,超时/中断均无害。
Inputs: taskId, taskIds, timeoutMs.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have sharply distinct roles: run_task creates work, wait_task blocks, verify_task audits, and the two visual-baseline tools are clearly paired. The one real overlap is query_info vs query_task — both 'read task state', with query_info(type=tasks/report) also touching task listing and reports that query_task seems adjacent to. manage_task's multi-action design (cancel/continue/rework) is internally differentiated by the action parameter but is a lot of behavior behind one name.
All eight names follow snake_case verb_noun (run_task, verify_task, wait_task, prepare_visual_baseline, approve_visual_baseline), which is predictable. The deviation is query_info, a generic bucket name that breaks the resource-specific *_task pattern and sits awkwardly next to query_task. Within-tool parameter naming (action=, type=) is consistent with the consolidation approach.
Eight tools is well within a healthy range for an agent-dispatch/verification server, and the authors clearly consolidated rather than proliferated. The tradeoff is that manage_task and query_info are each effectively 3 tools in one, pushing complexity into parameter space rather than the tool list. Slightly heavy per-tool surface, but the count itself is appropriate.
The lifecycle is well covered: dispatch, monitor (query_task events/logs), wait, verify, recover (cancel/continue/rework), historical listing and report retrieval, plus a visual-baseline approval flow. Gaps are minor but real — no way to delete/archive tasks or fetch dryRun plan/report artifacts directly, and agent/model capability discovery is only partially exposed via query_info(type=profiles).
Maintenance
Related MCP Connectors
Task manager for AI agents. Orchestrate agents to achieve large goals in unified control plane.
AI-powered spec-to-task decomposition and execution orchestration for coding agents.
Shared task layer for AI agents: tasks, handoffs and decisions that persist across tools.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceCoordinates parallel AI coding agents by providing task ownership, scoped file locks, handoffs, and verification workflows.MIT
- AlicenseAqualityBmaintenanceEnables orchestrating external AI agents to execute development tasks with asynchronous management, automated acceptance verification, failure rework loops, and optional visual baseline validation.1118 npmApache 2.0
- AlicenseCqualityBmaintenanceEnables multiple CLI-based AI agents to collaborate as a coordinated team through shared task queues, shared memory, and a message bus, with DAG orchestration, rate-limit avoidance, parallel dispatching, and long-task management.633MIT
- AlicenseAqualityBmaintenanceEnables AI agents to delegate complex coding tasks, refactorings, and automated code reviews to OpenAI Codex and Google Antigravity CLIs, running them autonomously in YOLO mode with process supervision.6MIT