Skip to main content
Glama

面向 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 文件,零改编排核心。

NOTE

本 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 工具只回文本

所有结果统一为「人类可读文本 + ---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。」

「在项目 D:\xxx 用 opendesign、designDirection=prototype 实现『任务』;它会按设计方向驱动 Open Design 桌面端,然后发任务、自动验收,失败自动生成修复计划并返修。」

工具面

8 个工具(v0.9.0 起由 13 个按域合并),按能力分为三族:read(读 / 查询,无副作用)、write(有副作用,全部需审批)、execute(执行项目侧命令但不改源码,当前仅 verify_task,仍免审批)。

工具

能力 / 审批

作用

run_task

write + 审批

派活(可带自动验收 / 自动返修),异步返回 taskId;可选 idempotencyKey、acceptanceOverride 与 dryRun

query_task

read

轮询状态 / 进度 / 日志尾 / 最近细粒度事件(可选 eventLimit)

manage_task

write + 审批

任务生命周期管理,action 三选一:cancel 取消运行中任务(CLI kill 进程树;GUI 经 CDP 尽力点停止并在 gui.cancelWaitMs(默认 15s)内有界等待;对已终态 GUI 任务兼任人工确认入口),可带 reason;continue 恢复 needs_user 的原会话(ZCode / Codex / Kimi Code / Open Design / MiniMax Code 各有恢复语义),message 必填;rework 手动返修(把失败报告喂回同一 agent),可选 feedback / repairHint(≤4000 字符)。含破坏性 action

verify_task

execute(不改源码,免审批)

对任务 / 项目路径做一次验收。会跑项目配置命令、可能产生构建产物,故 MCP readOnlyHint 为 false,但不改源码、仍免审批;可选 idempotencyKey

query_info

read

统一信息查询,type 三选一:tasks 历史任务过滤列表(可按 projectPath / status 过滤,limit 默认 50、上限 200);report 某轮验收报告全文(round 0-based、缺省最新);profiles 查看 agent 适配与可执行探测结果

wait_task

read

阻塞等待任务到达停点(终态或 needs_user)或超时。单任务传 taskId;批量传 taskIds(1..20,校验全部存在、缺一即报错)等数组顺序首个停者,返回其快照 + 全部任务当前状态。timeoutMs 缺省 50000、上限 600000,超时返回后再调一次继续等。纯只读、无害

prepare_visual_baseline

write + 审批

截图或导入参考图,生成待审阅候选和摘要

approve_visual_baseline

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

说明

codex

gui / codex-gui

ready(macOS 为 research)

Codex 桌面端 GUI(Windows:MSIX COM 激活 + CDP;macOS:spawn .app + CDP);支持 model / reasoningLevel / planDoc / designSystem;等待用户确认、取消与重派护栏均已真机验证

zcode

gui / zcode-gui

ready(Windows 真机闭环;macOS 未验证)

CDP GUI adapter;支持无项目派发、allowCreateProject 与 reasoningLevel(档位集合随模型变化,越权在发送前报错);v0.7.4 适配 3.14.x 的路径契约缺席(绑定判据改为「路径优先、无路径渠道时按显示名 + 全局同名消歧」,同名即 fail-closed);v0.7.6 修掉绑定死锁(侧边栏 workspace-item-* 滚出视口仍被采集 → 唯一可信的菜单渠道被短路)、运行期 CDP 断连的恢复入口(重连观察一次、绝不重发,失败落 needs_user(setup_recovery))与两级模型菜单(provider 分组须 hover 才渲染子项);v0.8.0 恢复轮保留原会话权限(issue #30:continue_task / rework_task 不再被 profile 默认值静默覆盖)

kimicode

gui / kimicode-gui

ready(macOS 为 research)

Kimi Code 桌面端(Electron);双渲染进程(主窗口 + Kimi Browser Overlay 浮层承载模型 / 档位 / 模式菜单);工作区以完整路径绑定;支持 model / reasoningLevel,且不支持无项目派发

opendesign

gui / opendesign-gui

ready(macOS 为 research)

Open Design 桌面端 GUI;选择器取自产品自身 Web 前端的 data-testid 钩子,12 步执行链全部接线,并接入验收 → 自动返修 → 再验收闭环;它是唯一带「产物信号」(文件 mtime / 大小指纹)的 driver

minimax

gui / minimax-gui

ready(macOS 为 research)

MiniMax Code 桌面端(Electron);双渲染进程(主窗口 + Model menu 弹层);推理等级 / 上下文窗口在悬停模型项展开的二级子菜单里,且候选集合随模型变化(无子菜单的模型请求这两项即 fail-closed);支持 model / reasoningLevel / contextWindow(本适配器专属),且不支持无项目派发;「新建项目」为应用内模态框 → 原生 Select Directory → 模态框提交两步

stub

spawn

仅测试

test/stub-agent/stub-agent.mjs 三剧本(good / fix-on-first / never)

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", "<模型名>"。

权限与安全边界

能力三族

能力

含义

审批

工具

read

只读 / 查询,无副作用

免审批

query_task / list_tasks / get_task_report / get_profiles / wait_task / wait_any

write

有副作用

需审批

run_task / continue_task / cancel_task / rework_task / 两个视觉基准工具

execute

执行项目侧命令,不改源码

免审批

verify_task

readOnlyHint 由 capability === "read" 推导,因此 verify_task 的该注解为 false;它不是审批信号——审批与否由 _meta.requireApproval 单独承载。

硬性红线

  1. 绝不按进程树盲杀 GUI 实例 —— 只终止本模块创建、且命令行核对通过的 PID。

  2. 默认复用用户实例 —— 绝不新起第二个;受管实例也不触碰用户手动打开的实例。

  3. computer-use 白名单 —— 原生文件夹选择对话框需经窗口标题 + 宿主进程双校验,其余窗口一律拒绝。

  4. 凭证零管理 —— 不读取 / 解密 / 转发任何 agent 凭证;GUI adapter 只驱动 UI。

  5. 命令不拼 shell —— 验收命令是结构化 argv,shell:false。

  6. 不自动 commit / stash / 回滚 —— 动工前采集 git 基线,报告相对基线计算。

  7. 路径不硬编码 —— 机器路径 / 用户名 / 端口走 profile 或占位符。

  8. stdout 只承载 JSON-RPC —— 所有诊断日志走 stderr(并同源追加到 logs/server.log)。

  9. 技能内容只来自包自身 —— 待安装技能经 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 统一闭环(开发 → 受控失败 → 同会话返修 → continue_task)

Codex 桌面端

0.3.x

Codex MSIX COM 激活 + CDP(破坏性:codex 由无头改为 GUI);等待用户检测、取消真停 GUI、验收引擎 fail-closed

macOS 与闸门

0.4.x

macOS 双驱动(spawn .app + CDP)、projectPath 安全闸门、验收命令有界并行(测试套件 267s → 51s)

视觉与幂等

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);真机取证修正三处结构假设(二级子菜单 / 集合随模型变化 / 项目创建两步),新增 contextWindow 参数与只读诊断探针

恢复语义修正

0.8.0

TraeWork 移除跨模式项目绑定兜底(#35:兜底结构性不可达且静默改写目标模式);ZCode 恢复轮保留原会话权限(#30:发送前无条件覆盖默认值已移除)

完成判定加固

0.8.1

四个 driver(ZCode / Kimi Code / MiniMax Code / Open Design)补上「曾观测到运行信号」门(#31:选择器漂移时不再把进行中的任务误判成功);fix-loop 让这三者的异常结束真正转 needs_attention 而非进验收链

Codex 模型回读

0.8.2

模型触发器回读改读结构(#34:真机按钮的 innerText 混入整条思考等级条——9 层轮播仅当前档 opacity:1,其余 display:block——旧实现整串当型号 → 三轮后 model_mismatch,阻断全部带 model 的 Codex 派发);三层回退(权威属性 → 结构节点 → innerText 兜底),matches() 判据未动

TraeWork 绑定链路

0.8.3

footer 点击改「副作用驱动三级阶梯」(#38:element.click() 返回 true ≠ 原生弹窗已唤起——旧实现据此白等满 20s 无补救;现以「对话框是否出现」为判据、坐标点击优先,真机 20s → 5.9s);总探测预算不再膨胀(检测点移到探测前,真机 28.2s → 19.2s);逻辑性 setup 失败不再落 errorType=spawn(新增 setup_failed,由适配器自归类,其余 6 个 agent 零行为变化)

工具面瘦身

0.8.4

run_task / verify_task 的 acceptanceOverride 线上声明骨架化——实测 tools/list 35581 → 11717 字符(−67.1%);根因是 VisualConfigSchema(9579 字符)在两个工具里各内联一份(MCP 每工具独立序列化,$ref 不可跨工具共享)。工具名 / 参数集 / 校验语义全部不变;校验下沉(handler 内严格复核)与本改动成对实施,否则 visual 转不透明后其内部非法输入会 fail-open

CDP 底座重构

0.9.8

TraeworkCdpClient(六个 GUI 适配器共用的传输底座)迁至 src/agents/cdp/client.ts 改名 GuiCdpClient,并把「传输 + 通用输入原语」与「选择器语义层」切开——共享传输不再 import 任何选择器表,为后续删除 TraeWork / Qoder CN 铺路。纯重构,零行为变化

移除 TraeWork

0.9.9

破坏性:彻底移除 traework agent 的调用支持(目录 / 测试 / registry 接线 / 文档全量清理);driver="gui" 缺省回落到该适配器的历史行为一并取消,改为 fail-closed 报错并给出迁移路径;mode 参数随之废弃(统一拒绝文案)。其余六个 agent 零行为变化

移除 Qoder CN

0.9.10

破坏性:彻底移除 qoder agent 的调用支持(目录 / 测试 / registry 接线 / fix-loop 分支 / 文档全量清理);modelSource 参数随之废弃(统一拒绝文案);顺带修正 actualModel 落盘(原被 qoder 门挡住,Open Design 的模型回读此前从未写入)。其余五个 agent 零行为变化

参数面收敛

1.0.0-beta.1

移除 TraeWork 专属的 mode 字段与全部透传(TaskContext / TaskMeta / NewTaskInput / formatter / context / handlers);mode 作为「已废弃的显式拒绝」保留在 schema(传入得统一迁移文案,而非被静默 strip);TraeworkMode 类型中性化为 DeprecatedPanelMode(grep traework src/ 归零)。无行为变化

脚本与 CI 收口

1.0.0-beta.2

删已移除 agent 的探针/冒烟脚本与 CDP 文档(probe/smoke-{traework,qoder}.mjs、docs/{traework,qoder}-cdp*.md、docs/qoder-evidence/);package.json 的 files/scripts/keywords 与 CI 两个必需文件清单同步。无行为变化

文档收口与零残留门禁

1.0.0-beta.3

文档全量收口 + 新增常驻门禁 scripts/check-removed-agents.mjs(src/ / scripts/ / package.json / CI 配置零容忍 traework / qoder,其余逐条白名单),接入 CI;端到端真机验证六个 agent 不受影响。无行为变化

日志台 GUI

gui-v*(独立线)

mcp-gui/ 本地只读日志台(Tauri 2.x + Vue 3),独立版本与 tag,不随 MCP 主包发布

完整逐版记录见 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 中渲染(禁用脚本、阻断外部资源)。

数据源

路径(相对数据目录)

界面位置

全局运行日志

logs/server.log

工作区 · 运行日志

任务事件流

tasks/<taskId>/task.jsonl

工作区 · 事件流

原始执行日志

tasks/<taskId>/agent-<轮次>.log、verify-<轮次>.log

工作区 · Agent 日志 / 验收日志

验收报告

tasks/<taskId>/report-<轮次>.{md,json,html}、dry-run-report-<轮次>.{md,json}

工作区 · 验收报告

主要能力:

  • 大日志与实时跟随 —— 首屏只读尾部 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 只读业务目录;唯一写入是应用自身偏好与用户显式选择的导出 / 更新文件

代码

mcp-gui/ 有自己的 package.json / tsconfig / eslint / vitest,不参与根工程门禁

打包

根 package.json 的 files 白名单不含 mcp-gui,不被打入 MCP 主包 npm 产物

发版

GUI 独立版本号与独立 tag(gui-v*),不随 MCP 主包发布(release.yml 只认 v*)

构建

本机不执行 Rust 侧构建与检查(cargo fmt / clippy / tauri build 全在 GUI workflow),本地只做前端预览与前端门禁

双份 schema 的防漂移:事件分类在 Rust 侧与前端各有一份镜像,真源始终是 src/tasks/task.ts 与 src/agents/agent-events.ts;mcp-gui/scripts/check-schema-parity.mjs 在 CI 中做三方集合比对,任一不一致即 fail。使用与开发说明见 日志台文档,真机记录见 issue-25 记录。

文档导航

使用与集成

文档

说明

ARCHITECTURE.md

架构说明:分层模型与模块边界、状态机、验收流水线、驱动层契约、扩展点与已知缺口

docs/core-principles.md

核心原理分析:四条硬约束如何逼出当前架构、核心机制逐条拆解与自洽性总结

docs/tianshu-integration.md

天枢 config.json 两种接入模式、UI / API 操作、冒烟步骤、FAQ

docs/agent-profiles.md

agent profile 字段说明 + 真实机器样例

docs/adapter-matrix.md

各 Agent 能力调研矩阵

docs/npm-publish-guide.md

npm 发布步骤与凭证说明

skills/tianshu-mcp/SKILL.md

教天枢编排本 MCP 的技能(含使用示例)

Agent 适配(CDP 驱动)

文档

说明

docs/codex-gui-cdp.md

Codex 桌面端:MSIX COM 激活、CDP 接管、选择器、运行检测、验收返修

docs/zcode-cdp.md

ZCode:安装探测、精确项目 / 模型、完全访问、暂停继续、无项目派发与双平台状态

docs/kimi-cdp.md

Kimi Code:双渲染进程、工作区完整路径绑定与原生导入、模型三级选择与思考档位

docs/opendesign-cdp.md

Open Design:数据目录推导、sidecar 根进程判定、选择器取证表与 12 步执行链、传输层双路径、失败码表

docs/minimax-cdp.md

MiniMax Code:双渲染进程、模型二级子菜单(推理等级 / 上下文窗口)与逐模型候选、完整路径项目绑定、Select Directory 原生对话框

验收与可观测

文档

说明

docs/acceptance-config.md

项目级与三级继承的验收配置规范

docs/repair-directives.md

结构化修复指令:来源、回退语义与已知限制

docs/dry-run.md

dryRun 干跑模式:只读约束、零改动门禁、方案文档

docs/event-stream.md

细粒度事件流:词表、落盘与读取侧有界窗口

docs/notifications.md

任务终态通知:webhook 契约、去重与签名

docs/wait-task.md

等待原语:wait_task / wait_any 契约、停点定义、超时矩阵与循环模式

docs/visual-acceptance.md

视觉验收入门与完整配置(含可选 AI 内容校验)

docs/visual-validation.md

视觉验收验证进度与平台证据

docs/visual-validation-evidence/

上述验证的原始机器可读记录

docs/gui-log-viewer.md

日志台 GUI(mcp-gui/):四类日志与任务产物、双源自动更新、开发与 CI 边界

真机验收记录

文档

说明

docs/m2-smoke-record.md · docs/m2-rework-record.md

M2 真实 codex 冒烟与 rework 闭环记录

docs/zcode-windows-smoke.md · docs/zcode-issue-8-10-validation.md · docs/zcode-issue-12-windows-evidence.md

ZCode Windows 真机验收记录

docs/codex-windows-smoke.md

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。

社区与支持

贡献者

感谢以下通过 Issue 与 PR 为本项目做出贡献的社区成员(按首次参与顺序排列):

Star History

许可证

本项目以 Apache License 2.0 发布,完整法律文本见 LICENSE。版权归 tianshu-mcp 贡献者所有(Copyright 2026 tianshu-mcp contributors)。简言之:你可以商业使用、修改、分发与私用,并获授贡献者专利许可;分发时须随附 LICENSE 全文并标注修改;本许可不授予商标使用权,对贡献者发起专利诉讼将导致专利授权自动终止;软件按「现状」提供,不附带任何担保。

第三方依赖许可

运行时依赖的许可如下(完整依赖清单——逐项版本、开发依赖、桌面端 Rust 依赖、间接依赖许可证分布与 SBOM 复现命令——见 DEPENDENCIES.md):

依赖

许可

用途

@modelcontextprotocol/sdk

MIT

MCP 协议实现

zod

MIT

外部输入校验

cross-spawn

MIT

跨平台子进程

puppeteer-core

Apache-2.0

视觉验收驱动无头浏览器

@puppeteer/browsers

Apache-2.0

托管 Chrome/Edge 的安装与版本锁定

pixelmatch

ISC

页面截图像素比对

sharp(optional)

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 tools
approve_visual_baselineapprove_visual_baselineA
Destructive

仅在用户明确审阅并授权后批准视觉基准。必须核对候选摘要与批准说明;自动返修禁止调用。宿主必须实施实际审批控制。

Inputs: candidateId (required), approvalNote (required), expectedDigest (required), taskId.

manage_taskmanage_taskA
Destructive

任务生命周期管理(合并原 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_infoA
Read-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_taskA
Read-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_taskA
Idempotent

派活:启动外部 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_taskB
Idempotent

对已完成任务或项目路径执行一次验收(不改源码):自动命令检查 + 代码分析(相对 git 基线)。可用 extraChecks 临时加验。需任务/项目二选一。可选 idempotencyKey:同一 key 重试不重跑验收——执行中的同键请求返回进行中提示,已完成的直接返回既有报告与轮次,参数变更则报冲突。

Inputs: taskId, checksMode, baselineRef, extraChecks, +3 more.

wait_taskwait_taskA
Read-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

    A3.8/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables orchestrating external AI agents to execute development tasks with asynchronous management, automated acceptance verification, failure rework loops, and optional visual baseline validation.
      11
      18 npm
      Apache 2.0
    • A
      license
      C
      quality
      B
      maintenance
      Enables 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.
      63
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      6
      MIT