tianshu-mcp 0.5.7 → 0.5.8

package/CHANGELOG.en.md

@@ -8,6 +8,30 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.5.8] - 2026-09-23
+
+### Changed
+
+- **The four primary documents were rewritten item by item against the code** (bilingual README / HANDOFF / bilingual ARCHITECTURE). The audit covered `src/mcp/`, `src/tasks/`, `src/loop/`, `src/agents/` (all five GUI adapters), `src/verify/`, `src/visual/`, `src/config/` and `src/util/`:
+  - **Acceptance stage order fixed**: the built-in `git-diff-check` runs **before** the configured checks, and the visual stage runs **after** the command checks (the old text had it reversed).
+  - **The real boundary of `visual.enabled=false`**: snapshot freezing and integrity checking run **unconditionally**, independent of `enabled`; `enabled` only decides whether screenshots/specs/content judgement actually run — which is exactly what detects edits to the acceptance config or baselines.
+  - **Tool result contract fixed**: `prepare_visual_baseline` / `approve_visual_baseline` success results also carry no meta block, and neither does any tool's error result (the old text claimed only `get_task_report` was an exception).
+  - **All five agent tables now include Qoder CN**: the agent list, driver list, `endReason` table, `needsUserKind` table, cancellation-capability table, registry special discovery branches, GUI instance lifecycle and test-layer descriptions were corrected from "four drivers" to "five", and Qoder CN's execution order and completion criterion were added to the architecture document.
+  - **`endReason` / `needsUserKind` verified value by value**: added Kimi Code's `system_permission` / `setup_recovery`; noted that Qoder CN is the only adapter able to emit all six kinds and that it **never emits `idle_timeout`** (static screen without this-turn evidence → `needs_user(setup_recovery)`); noted that Codex has no `close_existing_instance` path because `needsClose` never returns true; and that ZCode and TraeWork never click a stop button and never report `guiStop`.
+  - **Cancellation semantics** are now split per adapter capability; **checkpoints** now state that `qoder-session.json` is the only persisted checkpoint (with all four phases and their read/write points) while the rest keep in-memory state.
+  - Corrected the **Kimi Code tier domain** (README front-page example and milestone text changed from `Low`/`High`/`Max` to `低/low`, `高/high`, `max`, `on`, `off`), the **test baseline** (776 tests/73 files → 826 passed / 12 skipped across 81 files, broken down as unit 54 / integration 26 / protocol 1) and the **runtime dependency licence table** (Apache-2.0 and ISC entries added, "all MIT" corrected).
+  - The architecture document gained a callout for **declared-but-unused profile fields** (`gui.windowMode`, `gui.modelRequired`, ZCode's `gui.stallTimeoutMs` / `gui.cancelWaitMs`), and the known-gaps list now carries two real debts instead of a stale tool-count note.
+
+### Fixed
+
+- **Distribution gap**: `scripts/probe-traework.mjs` was not in `package.json`'s `files`, yet the docs tell users to run that probe — npm consumers could not get it. It is now shipped, and the `probe:traework` / `probe:zcode` / `probe:codex` npm scripts were added (previously only `probe:kimicode` / `probe:qoder` existed although the corresponding scripts had long been published).
+- **Source comments and strings**: the "9 tools" header comments in `src/mcp/handlers.ts` and `src/server.ts` now say 11; the MCP `instructions` string mentions `kimicode` / `qoder`; `src/agents/gui-instance.ts` lists all five users; `src/tasks/task.ts` fixes a Kimi Code comment that sat on the Qoder fields and notes that `qoderTurnId` has no writer. **No runtime behaviour change.**
+
+### Tests
+
+- Full regression: **826 passed / 12 skipped** (Windows 10 x64, Node 24.18.0); typecheck and lint pass; `npm pack` (231 files) verified to include all five probe scripts.
+- Documentation link check: the four primary documents plus the skill docs contain **255 relative links, 0 broken**.
+
 ## [0.5.7] - 2026-09-22
 
 ### Changed
@@ -829,6 +853,7 @@ project → pick model and reasoning level → send instructions → run detecti
 
 ---
 
+[0.5.8]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.5.7...v0.5.8
 [0.5.7]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.5.6...v0.5.7
 [0.5.6]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.5.5...v0.5.6
 [0.5.5]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.5.4...v0.5.5

package/CHANGELOG.md

@@ -7,6 +7,30 @@
 
 ---
 
+## [0.5.8] - 2026-09-23
+
+### 变更
+
+- **四份主文档按代码逐项核对重写**（README 双语 / HANDOFF / ARCHITECTURE 双语），核对范围覆盖 `src/mcp/`、`src/tasks/`、`src/loop/`、`src/agents/`（五个 GUI 适配器全部）、`src/verify/`、`src/visual/`、`src/config/`、`src/util/`：
+  - **验收阶段顺序修正**：内置 `git-diff-check` 在配置的检查项**之前**执行，视觉检查在命令检查**之后**执行（旧文档写反）。
+  - **`visual.enabled=false` 的真实边界**：快照冻结与完整性核对**恒定执行**，与 `enabled` 无关；`enabled` 只决定是否真的跑截图/规格/内容判定（这正是检出「验收配置或基准被改」的机制）。
+  - **工具返回契约修正**：`prepare_visual_baseline` / `approve_visual_baseline` 的成功结果同样不带 meta 块，任何工具的错误结果也不带（旧文档称仅 `get_task_report` 例外）。
+  - **五份 agent 表补齐 Qoder CN**：agent 列表、driver 列表、`endReason` 表、`needsUserKind` 表、取消能力表、registry 特殊探测分支、GUI 实例生命周期、测试分层说明全部由「四个 driver」更正为「五个」，并把 Qoder CN 执行顺序与完成判定写入架构文档。
+  - **`endReason` / `needsUserKind` 逐值核对**：补 Kimi Code 的 `system_permission` / `setup_recovery`；注明 Qoder CN 是唯一能产出全部 6 种 kind 的适配器且**不产出 `idle_timeout`**（静止而无本轮完成证据 → `needs_user(setup_recovery)`）；注明 Codex 因 `needsClose` 从不返回 true 而没有 `close_existing_instance` 路径；注明 ZCode 与 TraeWork 不点界面停止按钮也不回传 `guiStop`。
+  - **取消语义**改为按适配器能力分列；**检查点**明确 `qoder-session.json` 是唯一持久化检查点（含四个 phase 的读写点），其余为内存态判断。
+  - 修正 **Kimi Code 档位取值域**（README 首页示例与里程碑文字由 `Low`/`High`/`Max` 改为 `低/low`、`高/high`、`max`、`on`、`off`）、**测试基线**（776 项/73 文件 → 826 passed / 12 skipped、81 文件，并给出单元 54 / 集成 26 / 协议 1 的构成）、**运行时依赖许可表**（补 Apache-2.0 与 ISC 项，纠正「均为 MIT」）。
+  - 架构文档新增「声明了但当前无消费方」的 profile 字段提示框（`gui.windowMode`、`gui.modelRequired`、ZCode 的 `gui.stallTimeoutMs` / `gui.cancelWaitMs`），并把已知缺口更新为两条真实技术债。
+
+### 修复
+
+- **分发缺口**：`scripts/probe-traework.mjs` 此前不在 `package.json` 的 `files` 中，而文档要求用户运行该探针——npm 包内拿不到该脚本。现已纳入分发，并补齐 `probe:traework` / `probe:zcode` / `probe:codex` 三个 npm script（此前只有 `probe:kimicode` / `probe:qoder`，而对应脚本早已随包发布）。
+- **源码注释与描述**：`src/mcp/handlers.ts`、`src/server.ts` 头注「9 个工具」更正为 11；MCP `instructions` 补 `kimicode` / `qoder`；`src/agents/gui-instance.ts` 头注补全五个使用者；`src/tasks/task.ts` 修正贴在 Qoder 字段上的 Kimi Code 注释并注明 `qoderTurnId` 无写入方。**均无运行时行为变更。**
+
+### 测试
+
+- 全量 **826 passed / 12 skipped**（Windows 10 x64，Node 24.18.0）；类型检查与 lint 通过；`npm pack`（231 文件）核验包含五个探针脚本。
+- 文档相对链接检查：四份主文档 + 技能文档共 **255 条相对链接、0 条失效**。
+
 ## [0.5.7] - 2026-09-22
 
 ### 变更
@@ -724,6 +748,7 @@ Codex 桌面端改为 **GUI 驱动**：新增 `codex-gui` adapter，通过 MSIX
 
 ---
 
+[0.5.8]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.5.7...v0.5.8
 [0.5.7]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.5.6...v0.5.7
 [0.5.6]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.5.5...v0.5.6
 [0.5.5]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.5.4...v0.5.5

package/README.en.md

@@ -8,7 +8,7 @@
 
 # tianshu-mcp
 
-Visual acceptance (since v0.5.0, with optional AI content validation since v0.5.4): [English guide](docs/visual-acceptance.en.md) · [Validation record](docs/visual-validation.en.md) · [Latest release notes](<docs/release-v0.5.6.en.md>).
+Visual acceptance (since v0.5.0, with optional AI content validation since v0.5.4): [English guide](docs/visual-acceptance.en.md) · [Validation record](docs/visual-validation.en.md) · [Latest release notes](<docs/release-v0.5.8.en.md>) · [All versions](CHANGELOG.en.md).
 
 **Tianshu × AI-Agent orchestration MCP server**
 
@@ -35,14 +35,14 @@ Registered by Tianshu as a standard MCP server, it dispatches external AI-Agents
 
 ## What this is
 
-Tianshu plays the role of the overall commander; this MCP server is the **scheduler + execution surface + objective acceptance gate**; the external AI-Agent (Codex / TraeWork / ZCode / Kimi Code GUI) is the "worker" that does the development.
+Tianshu plays the role of the overall commander; this MCP server is the **scheduler + execution surface + objective acceptance gate**; the external AI-Agent (Codex / TraeWork / ZCode / Kimi Code / Qoder CN GUI) is the "worker" that does the development.
 
 - **11 MCP tools**: `run_task / continue_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles`, plus `prepare_visual_baseline / approve_visual_baseline` for visual acceptance
 - **Async contract**: `run_task` returns a `taskId` immediately; long-running work is polled via `query_task` (never blocks `tools/call`).
 - **Objective acceptance**: automated command checks (typecheck/lint/test/build — skipped when absent, plus tech-stack derivation) + programmatic code analysis (changed-file list / diffstat / suspicious signals such as TODO, debugger, secret-like patterns), all relative to a **git baseline**; never auto-commits or stashes. The acceptance engine is **fail-closed**: a test check fails when its output reports zero executed tests even if the exit code is 0; git projects must produce changes relative to the pre-work baseline by default (pure analysis tasks can opt out with `"requireChanges": false` in `.tianshu-mcp/acceptance.json`).
 - **Acceptance parallelism**: command checks run **bounded-parallel** by default (`verifyConcurrency`, default 2, range 1–4). When checks depend on an order (a later check reading build output, `--fix`, shared cache dirs), set it to `1` for fully serial behaviour; a project can override it in `.tianshu-mcp/acceptance.json`, and the server level lives in `config.json`. Report and log formats are unchanged (results are returned in declaration order).
 - **Rework loop**: automatic rework (`autoFixRounds`) + manual `rework_task`; on verification failure a repair-plan file is generated and fed back to the agent; when rounds run out → `needs_attention` awaiting Tianshu's verdict.
-- **Execution surfaces**: `driver: "gui"` selects an explicit, isolated Codex/TraeWork/ZCode/Kimi Code CDP adapter; `driver: "spawn"` runs an external CLI child process.
+- **Execution surfaces**: `driver: "gui"` selects an explicit, isolated Codex/TraeWork/ZCode/Kimi Code/Qoder CN CDP adapter; `driver: "spawn"` runs an external CLI child process.
 - **Project-less dispatch (ZCode, issue #12)**: `run_task`'s `projectPath` may be omitted — ZCode runs the task in its `default` workspace without registering/importing a project, collecting a Git baseline, or running project acceptance (the result is marked structurally as `verificationNotApplicable: "no_project"` and `verify_task`/`get_task_report` return a not-applicable explanation). The companion `allowCreateProject: false` stops dispatch before any import side effect when the target directory is unregistered. See the [ZCode CDP adapter](docs/zcode-cdp.en.md).
 - **Scheduling discipline**: per-project serial queue + global concurrency cap (default 2, configurable).
 - **Optional AI content validation (v0.5.4, off by default)**: validates whether the **content** of an image or page screenshot matches an expectation you declare explicitly. Judgement is fully **delegated to a local command you supply** (the MCP reads, stores, and forwards no keys and ships no model client), it **warns only** by default and can be upgraded to failing per rule, and it debounces with majority sampling plus a task-level cache; split votes or confidence below the threshold yield `uncertain`, which never gates and never triggers rework. Configuration and the command contract are in [visual acceptance](docs/visual-acceptance.en.md).
@@ -70,7 +70,7 @@ git clone https://github.com/lanlan0811/tianshu-mcp.git
 cd tianshu-mcp
 npm ci
 npm run build        # sync-version + tsc → dist/
-npm test             # 776 tests across 73 files, including Codex/ZCode/TraeWork/Kimi Code unit/fake-CDP/restart/recovery/repair loops and visual acceptance
+npm test             # 826 passed / 12 skipped (838 tests, 81 files: unit/integration/protocol plus 3 real-browser files skipped by design)
 ```
 
 ### Install the npm package
@@ -158,14 +158,27 @@ For Kimi Code, `model` is required and takes the UI model name directly, while `
 
 ```text
 run_task(projectPath=D:/xxx/my-app, agentId=kimicode, task="Implement `./plan.md`",
-         model=K3, reasoningLevel=High, autoVerify=true, autoFixRounds=2)
+         model=K3, reasoningLevel=high, autoVerify=true, autoFixRounds=2)
 ```
 
 > Kimi Code is a plain Electron install (measured 1.0.2): injecting `--remote-debugging-port` and driving it over CDP is enough — no MSIX COM activation.
 > **The model menu, thinking tiers and execution-mode menu render in a separate `Kimi Browser Overlay` renderer window**, while the workspace menu and the "switch model" dialog stay in the main window.
 > A task must bind a workspace folder (**project-less dispatch is not supported**); an unregistered workspace is imported through the native "add workspace" dialog.
-> `reasoningLevel`: official models use `Low` / `High` / `Max`; **unofficial models (e.g. `stepfun/step-3.7-flash:free`) only have `on` / `off`**,
-> and a tier the UI does not render fails loudly before sending. The `mode` parameter is not supported. See the [Kimi Code CDP adapter](docs/kimi-cdp.en.md).
+> `reasoningLevel`: official models use `低/low`, `高/high` and `max`; **unofficial models (e.g. `stepfun/step-3.7-flash:free`) only have `on` / `off`**.
+> The domain deliberately excludes `中`/`medium`; tiers are validated against the label set the UI actually renders, and a tier the UI does not render fails loudly before sending. The `mode` parameter is not supported. See the [Kimi Code CDP adapter](docs/kimi-cdp.en.md).
+
+For Qoder CN, an existing `projectPath` and a readable `planDoc` are mandatory:
+
+```text
+run_task(projectPath=D:/xxx/my-app, agentId=qoder, planDoc=./plans/development.md,
+         modelSource=custom, model=<UI model name>, reasoningLevel=极高,
+         task="Implement the project per the plan", autoVerify=true, autoFixRounds=3)
+```
+
+> **Qoder CN only** (the international edition or a similarly titled window is not a substitute). `modelSource=default|custom` disambiguates identical names across the default/custom groups;
+> the thinking tier is saved in Model Management as a **global Qoder preference** (never restored afterwards) and read back by reopening the dialog, and an unsupported tier fails before sending;
+> the permission mode is retained as-is. Both automatic and manual repair **write the plan first**, then send its filename, full path and complete text to the original conversation.
+> macOS is `research` and dispatch is disabled. See the [Qoder CN adapter](docs/qoder-cdp.en.md).
 
 ## Tool surface (11 tools)
 
@@ -215,6 +228,7 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
 | [docs/codex-windows-smoke.en.md](docs/codex-windows-smoke.en.md) | Codex Windows hardware record (incl. verify-fail → auto plan → repair-pass loop) |
 | [docs/release-v0.3.4.en.md](<docs/release-v0.3.4.en.md>) | v0.3.4 release notes (ZCode project/model read-back, initialization recovery, session dispatch confirmation, issues #8/#9/#10) |
 | [docs/qoder-cdp.en.md](docs/qoder-cdp.en.md) | Qoder CN GUI driver: installation discovery and instance reuse, full-path workspaces with native import, `modelSource` and global Model Management reasoning tiers, send/answer checkpoints, liveness judging and same-session repair, hardware evidence and uncovered items |
+| [docs/release-v0.5.8.en.md](<docs/release-v0.5.8.en.md>) | v0.5.8 release notes (the four primary documents rewritten against the code, plus the missing TraeWork probe and three probe scripts; no runtime change) |
 | [docs/release-v0.5.7.en.md](<docs/release-v0.5.7.en.md>) | v0.5.7 release notes (orchestration skill docs rewritten against the code: parameter matrix, default precedence, tier correction and the qoder section; no runtime change) |
 | [docs/release-v0.5.6.en.md](<docs/release-v0.5.6.en.md>) | v0.5.6 release notes (Qoder CN GUI adapter, hardware acceptance scope, macOS research boundary) |
 | [docs/release-v0.5.5.en.md](<docs/release-v0.5.5.en.md>) | v0.5.5 release notes (Kimi Code GUI adapter: dual renderer processes, full-path workspace binding with native import, three-stage model selection and tier validation, run detection and recovery) |
@@ -265,7 +279,7 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
 - **Engineering / CI** ✅
   - GitHub Actions: `CI` (`build-test` ubuntu/windows/macos × Node 20/22/24 + `pack-check`, plus a `visual-browser` real-browser matrix ubuntu/windows/macos-15-intel/macos-15 × Node 20/22/24, all green with the v0.5.1 tag) and `Release` (tag-triggered) both green
   - Skill self-install verified idempotent on this machine's real `~/.rivet/skills/tianshu-mcp`
-  - npm package name `tianshu-mcp` published continuously since v0.1.1 (currently `0.5.7`)
+  - npm package name `tianshu-mcp` published continuously since v0.1.1 (currently `0.5.8`)
 - **Real Tianshu host integration (DoD #6)** ✅ (2026-09-07)
   - Configured the local mode in the real `D:\Tianshu` desktop host `mcp.servers` → sidecar reported `MCP: 2 servers connected, 10 tools` (including this server's 8 tools), spawned the child process and connected over stdio
   - Exposed and fixed a skill-install source-path bug (fileURLToPath, commit 55cf2d0)
@@ -359,7 +373,7 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
 - **M24 — Kimi Code GUI adapter (fourth GUI agent) + v0.5.5** (2026-09-20) — **764 tests**
   - **Dual-renderer CDP driver**: the model / thinking-tier / execution-mode menus render in the separate `Kimi Browser Overlay` window while the workspace menu and the "switch model" dialog stay in the main window
   - **Full-path workspace binding**: an unregistered directory is imported through the native "add workspace" dialog (Win32 coordinate clicks plus `WM_SETTEXT`/`WM_GETTEXT` read-back), and same-name/different-directory cases fail closed
-  - **Three-stage model selection and tier validation**: pill read-back → overlay shortcut menu → "more models…" dialog; tiers are validated against **the set the UI actually renders** (official `Low/High/Max`, unofficial `On/Off`), and a tier the UI does not render fails before sending
+  - **Three-stage model selection and tier validation**: pill read-back → overlay shortcut menu → "more models…" dialog; tiers are validated against **the set the UI actually renders** (official models `低/low`, `高/high`, `max`; unofficial models only `on`/`off`), and a tier the UI does not render fails before sending
   - **Run detection and recovery**: `button.stop` / `send.is-starting` are the authoritative signals; the six `needs_user` kinds recover via `continue_task`, and an uncertain send is never repeated
   - See the [Kimi Code guide](docs/kimi-cdp.en.md) and the [v0.5.5 release notes](<docs/release-v0.5.5.en.md>)
 - **M25 — Qoder CN GUI adapter (fifth GUI agent) + v0.5.6** (2026-09-22) — **826 tests**
@@ -375,6 +389,12 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
   - **Kimi Code tier domain corrected** (`低/low`, `高/high`, `max`, `on`, `off` — deliberately without `中`/`medium`) and the qoder section completed (`modelSource` disambiguation, tier saved then read back, checkpoints that prevent resends, repair writing a plan before sending its full text, macOS dispatch disabled)
   - **New `needsUserKind` × agent × `continue_task` matrix** and an `agentEndReason` → terminal-state mapping, plus `project_not_registered`/`unsupported_platform`/`qoder_error` and the new meta fields
   - See the [v0.5.7 release notes](<docs/release-v0.5.7.en.md>)
+- **M27 — The four primary documents rewritten against the code + packaging fix + v0.5.8** (2026-09-23) — **826 tests** (no runtime change)
+  - **Item-by-item audit of the four primary documents** (bilingual README / HANDOFF / bilingual ARCHITECTURE): corrected the **acceptance stage order** (the built-in `git-diff-check` runs before the configured checks and the visual stage after them), the fact that **`visual.enabled=false` still freezes and compares snapshots**, and the **tool result contract** (the two baseline tools and every error result carry no meta block either)
+  - **All five agent tables now include Qoder CN** (driver list, `endReason`, `needsUserKind`, cancellation capability, registry discovery branches, instance lifecycle), noting that Qoder CN is the only adapter able to emit all six wait kinds and that it **never emits `idle_timeout`**
+  - Corrected the Kimi Code tier domain, the test baseline (826 passed / 12 skipped across 81 files) and the runtime dependency licence table (Apache-2.0 / ISC), and added a callout for **declared-but-unused profile fields**
+  - **Fixed a distribution gap**: `scripts/probe-traework.mjs` was not shipped although the docs tell users to run it → added to `files`, plus the missing `probe:traework` / `probe:zcode` / `probe:codex` scripts
+  - See the [v0.5.8 release notes](<docs/release-v0.5.8.en.md>)
 
 ## Agent support status
 
@@ -451,7 +471,7 @@ Behavior and limits:
 
 | Document | Content |
 |---|---|
-| [CHANGELOG.en.md](<CHANGELOG.en.md>) | Version history (v0.1.0 → v0.5.7) |
+| [CHANGELOG.en.md](<CHANGELOG.en.md>) | Version history (v0.1.0 → v0.5.8) |
 | [CONTRIBUTING.en.md](CONTRIBUTING.en.md) | Dev setup, conventions, commit/release flow, adding an agent |
 | [SECURITY.en.md](SECURITY.en.md) | Security model (zero credentials / command whitelist / process & desktop-automation boundaries) and private reporting |
 | [CODE_OF_CONDUCT.en.md](CODE_OF_CONDUCT.en.md) | Contributor Code of Conduct |
@@ -510,13 +530,17 @@ The software is provided **"AS IS"**, without warranties or conditions of any ki
 
 ### Third-party dependency licenses
 
-Runtime dependencies are all **MIT**-licensed and compatible with Apache-2.0:
+Runtime dependencies are licensed as follows (all permissive and Apache-2.0 compatible):
 
 | Dependency | License | Purpose |
 |---|---|---|
 | [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/sdk) | MIT | MCP protocol implementation |
 | [`zod`](https://github.com/colinhacks/zod) | MIT | External input validation |
 | [`cross-spawn`](https://github.com/moxystudio/node-cross-spawn) | MIT | Cross-platform child processes |
+| [`puppeteer-core`](https://github.com/puppeteer/puppeteer) | Apache-2.0 | Drives the headless browser for visual acceptance |
+| [`@puppeteer/browsers`](https://github.com/puppeteer/puppeteer) | Apache-2.0 | Installs and version-locks the managed Chrome/Edge |
+| [`pixelmatch`](https://github.com/mapbox/pixelmatch) | ISC | Page-screenshot pixel comparison |
+| [`sharp`](https://github.com/lovell/sharp) (optional) | Apache-2.0 | Image decoding and spec validation; the visual module blocks explicitly when it is missing |
 
 Development dependencies (TypeScript, ESLint, Prettier, Vitest, Vite, tsx, etc.) follow their own open-source licenses and are not distributed with the npm package.
 

package/README.md

@@ -8,7 +8,7 @@
 
 # tianshu-mcp
 
-视觉验收（v0.5.0 起，含 v0.5.4 可选 AI 内容校验）：[中文指南](docs/visual-acceptance.md) · [验证记录](docs/visual-validation.md) · [最新发布说明](<docs/release-v0.5.6.md>)。
+视觉验收（v0.5.0 起，含 v0.5.4 可选 AI 内容校验）：[中文指南](docs/visual-acceptance.md) · [验证记录](docs/visual-validation.md) · [最新发布说明](<docs/release-v0.5.8.md>) · [全部版本](CHANGELOG.md)。
 
 **天枢 × AI-Agent 编排 MCP server**
 
@@ -35,7 +35,7 @@
 
 ## 这是什么
 
-天枢的角色是总指挥；本 MCP server 是**调度层 + 执行面 + 客观验收仪**；外部 AI-Agent（Codex / TraeWork / ZCode / Kimi Code GUI）是执行开发的「工人」。
+天枢的角色是总指挥；本 MCP server 是**调度层 + 执行面 + 客观验收仪**；外部 AI-Agent（Codex / TraeWork / ZCode / Kimi Code / Qoder CN GUI）是执行开发的「工人」。
 
 - **11 个 MCP 工具**：`run_task / continue_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles`，外加视觉验收的 `prepare_visual_baseline / approve_visual_baseline`
 - **异步契约**：`run_task` 秒回 `taskId`，长任务用 `query_task` 轮询（长任务不卡 `tools/call`）。
@@ -70,7 +70,7 @@ git clone https://github.com/lanlan0811/tianshu-mcp.git
 cd tianshu-mcp
 npm ci
 npm run build        # sync-version + tsc → dist/
-npm test             # 776 项测试：73 个文件，含 Codex/ZCode/TraeWork/Kimi Code 单元/假 CDP/重启/恢复/返修闭环与视觉验收
+npm test             # 826 passed / 12 skipped（838 项，81 个测试文件：单元/集成/协议 + 3 个真实浏览器文件按设计 skip）
 ```
 
 ### 安装 npm 包
@@ -154,14 +154,27 @@ ZCode 提问、需要登录、旧实例无 CDP、系统权限不足，或自动
 
 ```text
 run_task(projectPath=D:/xxx/my-app, agentId=kimicode, task=「按 `./plan.md` 完成开发」,
-         model=K3, reasoningLevel=High, autoVerify=true, autoFixRounds=2)
+         model=K3, reasoningLevel=high, autoVerify=true, autoFixRounds=2)
 ```
 
 > Kimi Code 为普通 Electron 安装（实测 1.0.2），以 `--remote-debugging-port` 注入后经 CDP 驱动，无需 MSIX COM 激活。
 > **模型菜单 / 思考档位 / 执行模式菜单渲染在独立的 `Kimi Browser Overlay` 浮层窗口**，工作区菜单与「切换模型」对话框仍在主窗口。
 > 任务必须绑定工作区文件夹（**不支持无项目派发**）；未登记的工作区会经原生「添加工作区」对话框导入。
-> `reasoningLevel`：官方模型为 `Low` / `High` / `Max`；**非官方模型（如 `stepfun/step-3.7-flash:free`）只有 `on` / `off`**，
-> 传了界面不存在的档位会在发送前响亮报错。`mode` 参数不支持。详见 [Kimi Code CDP 适配器](docs/kimi-cdp.md)。
+> `reasoningLevel`：官方模型为 `低/low`、`高/high`、`max`；**非官方模型（如 `stepfun/step-3.7-flash:free`）只有 `on` / `off`**，
+> 取值域刻意不含 `中`/`medium`；档位以界面实际渲染的标签集合校验，传了界面不存在的档位会在发送前响亮报错。`mode` 参数不支持。详见 [Kimi Code CDP 适配器](docs/kimi-cdp.md)。
+
+驱动 Qoder CN 时必须提供已有 `projectPath` 与可读 `planDoc`：
+
+```text
+run_task(projectPath=D:/xxx/my-app, agentId=qoder, planDoc=./plans/development.md,
+         modelSource=custom, model=<界面模型名>, reasoningLevel=极高,
+         task=「按计划实现项目」, autoVerify=true, autoFixRounds=3)
+```
+
+> **仅 Qoder CN**（国际版或同名窗口不算）。`modelSource=default|custom` 用于消除「默认/自定义」两组同名；
+> 思考等级经「模型管理」保存为 **Qoder 全局偏好**（任务结束不还原）并重新打开回读，不支持的档位在发送前报错；
+> 权限模式沿用当前设置。自动与手动返修都**先落修复计划**，再把文件名、完整路径与全文发回原会话。
+> macOS 为 `research` 且禁止派发。详见 [Qoder CN 适配器](docs/qoder-cdp.md)。
 
 ## 工具面（11 个）
 
@@ -212,6 +225,7 @@ run_task(projectPath=D:/xxx/my-app, agentId=kimicode, task=「按 `./plan.md`
 | [docs/kimi-cdp.md](docs/kimi-cdp.md) | Kimi Code GUI 驱动：双渲染进程（主窗口 + `Kimi Browser Overlay`）、工作区完整路径绑定与原生对话框导入、模型三级选择与思考档位、执行模式、运行检测与排障 |
 | [docs/codex-windows-smoke.md](docs/codex-windows-smoke.md) | Codex Windows 真机验收记录（含验收失败→自动生成计划→返修通过闭环） |
 | [docs/qoder-cdp.md](docs/qoder-cdp.md) | Qoder CN GUI 驱动：安装发现与实例复用、完整路径工作区与原生导入、`modelSource` 与模型管理全局思考等级、发送/答题检查点、运行判定与原会话返修、真机证据与未覆盖项 |
+| [docs/release-v0.5.8.md](<docs/release-v0.5.8.md>) | v0.5.8 发布说明（四份主文档按代码逐项核对重写 + 补发 TraeWork 探针与三个 probe script；无运行时变更） |
 | [docs/release-v0.5.7.md](<docs/release-v0.5.7.md>) | v0.5.7 发布说明（编排技能文档按代码实况重写：参数兼容矩阵、默认值优先级、档位修正与 qoder 章节；无运行时变更） |
 | [docs/release-v0.5.6.md](<docs/release-v0.5.6.md>) | v0.5.6 发布说明（Qoder CN GUI 适配、真机验收范围与 macOS research 边界） |
 | [docs/release-v0.5.5.md](<docs/release-v0.5.5.md>) | v0.5.5 发布说明（Kimi Code GUI 适配：双渲染进程、工作区完整路径绑定与原生导入、模型三级选择与档位校验、运行检测与恢复） |
@@ -266,7 +280,7 @@ run_task(projectPath=D:/xxx/my-app, agentId=kimicode, task=「按 `./plan.md`
 - **工程 / CI** ✅
   - GitHub Actions：`CI`（`build-test` ubuntu/windows/macos × Node 20/22/24 + `pack-check`，另加 `visual-browser` 真实浏览器矩阵 ubuntu/windows/macos-15-intel/macos-15 × Node 20/22/24，随 v0.5.1 tag 全绿）与 `Release`（tag 触发）均绿
   - 技能自检安装已在本机真实 `~/.rivet/skills/tianshu-mcp` 验证生效且幂等
-  - npm 包名 `tianshu-mcp` 自 v0.1.1 起持续发布（当前 `0.5.7`）
+  - npm 包名 `tianshu-mcp` 自 v0.1.1 起持续发布（当前 `0.5.8`）
 - **天枢宿主真实接入（DoD #6）** ✅（2026-09-07，[host-integration-record.md](docs/host-integration-record.md)）
   - 在真实 `D:\Tianshu` 桌面宿主 `mcp.servers` 配置本地模式 → sidecar `MCP: 2 servers connected, 10 tools`（含本 server 8 工具），spawn 子进程并 stdio 连通
   - 实测暴露并修复技能安装源路径 bug（fileURLToPath，提交 55cf2d0）
@@ -360,7 +374,7 @@ run_task(projectPath=D:/xxx/my-app, agentId=kimicode, task=「按 `./plan.md`
 - **M24 — Kimi Code GUI 适配（第四个 GUI agent）+ v0.5.5**（2026-09-20）— **764 测试**
   - **双渲染进程 CDP 驱动**：模型 / 思考档位 / 执行模式菜单渲染在独立的 `Kimi Browser Overlay` 浮层窗口，工作区菜单与「切换模型」对话框仍在主窗口
   - **工作区完整路径绑定**：未登记目录经原生「添加工作区」对话框导入（Win32 坐标点击 + `WM_SETTEXT`/`WM_GETTEXT` 回读），同名不同目录一律 fail-closed
-  - **模型三级选择与档位校验**：pill 回读 → overlay 快捷菜单 → 「更多模型…」对话框；档位按**界面实际渲染的集合**校验（官方 `Low/High/Max`，非官方 `On/Off`），请求不存在的档位在发送前报错
+  - **模型三级选择与档位校验**：pill 回读 → overlay 快捷菜单 → 「更多模型…」对话框；档位按**界面实际渲染的集合**校验（官方模型 `低/low`、`高/high`、`max`，非官方模型仅 `on`/`off`），请求不到的档位在发送前报错
   - **运行检测与恢复**：`button.stop` / `send.is-starting` 为权威信号；`needs_user` 六类由 `continue_task` 恢复，发布发送确认失败绝不重发
   - 详见 [Kimi Code 文档](docs/kimi-cdp.md) 与 [v0.5.5 发布说明](<docs/release-v0.5.5.md>)
 - **M25 — Qoder CN GUI 适配（第五个 GUI agent）+ v0.5.6**（2026-09-22）— **826 测试**
@@ -376,6 +390,12 @@ run_task(projectPath=D:/xxx/my-app, agentId=kimicode, task=「按 `./plan.md`
   - **修正 Kimi Code 档位取值域**（`低/low`、`高/high`、`max`、`on`、`off`，刻意不含 `中`/`medium`）与 qoder 章节（`modelSource` 消歧、档位保存回读、检查点不重发、返修先落计划再回发全文、macOS 禁止派发）
   - **新增 `needsUserKind` × agent × `continue_task` 行为矩阵**与 `agentEndReason` → 终态映射，补 `project_not_registered`/`unsupported_platform`/`qoder_error` 等错误码与 meta 新字段
   - 详见 [v0.5.7 发布说明](<docs/release-v0.5.7.md>)
+- **M27 — 四份主文档按代码实况重写 + 打包一致性修复 + v0.5.8**（2026-09-23）— **826 测试**（无运行时变更）
+  - **四份主文档按代码逐项核对**（README 双语 / HANDOFF / ARCHITECTURE 双语）：修正**验收阶段顺序**（内置 `git-diff-check` 在配置检查项之前、视觉在命令检查之后）、**`visual.enabled=false` 仍会冻结核对快照**、**工具返回契约**（两个视觉基准工具与所有错误结果也不带 meta 块）
+  - **五份 agent 表补齐 Qoder CN**（driver 列表、`endReason`、`needsUserKind`、取消能力、registry 探测分支、实例生命周期），并注明 Qoder CN 是唯一能产出全部 6 种等待类型且**不产出 `idle_timeout`** 的适配器
+  - 修正 Kimi Code 档位取值域、测试基线（826 passed / 12 skipped、81 文件）、运行时依赖许可表（Apache-2.0 / ISC），并新增「声明了但无消费方」的 profile 字段提示
+  - **修复分发缺口**：`scripts/probe-traework.mjs` 未随包发布（文档却要求用户运行它）→ 纳入 `files`，并补齐 `probe:traework` / `probe:zcode` / `probe:codex` script
+  - 详见 [v0.5.8 发布说明](<docs/release-v0.5.8.md>)
 
 ## Agent 适配现状
 
@@ -453,7 +473,7 @@ run_task(projectPath=/path/to/项目, agentId=codex-cli, task="任务书", autoV
 | 文档 | 内容 |
 |---|---|
 | [HANDOFF.md](HANDOFF.md) | 项目交接文档：当前状态快照、架构导览、硬性红线、已知限制、接手建议 |
-| [CHANGELOG.md](<CHANGELOG.md>) | 版本变更日志（v0.1.0 → v0.5.7） |
+| [CHANGELOG.md](<CHANGELOG.md>) | 版本变更日志（v0.1.0 → v0.5.8） |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | 开发环境、工程规范、提交与发布流程、如何新增 agent |
 | [SECURITY.md](SECURITY.md) | 安全模型（凭证零管理/命令白名单/进程与桌面自动化边界）与私密报告渠道 |
 | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | 贡献者行为准则 |
@@ -512,13 +532,17 @@ run_task(projectPath=/path/to/项目, agentId=codex-cli, task="任务书", autoV
 
 ### 第三方依赖许可
 
-运行时依赖均为 **MIT** 许可，与 Apache-2.0 兼容：
+运行时依赖的许可如下（均为与 Apache-2.0 兼容的宽松许可）：
 
 | 依赖 | 许可 | 用途 |
 |---|---|---|
 | [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/sdk) | MIT | MCP 协议实现 |
 | [`zod`](https://github.com/colinhacks/zod) | MIT | 外部输入校验 |
 | [`cross-spawn`](https://github.com/moxystudio/node-cross-spawn) | MIT | 跨平台子进程 |
+| [`puppeteer-core`](https://github.com/puppeteer/puppeteer) | Apache-2.0 | 视觉验收驱动无头浏览器 |
+| [`@puppeteer/browsers`](https://github.com/puppeteer/puppeteer) | Apache-2.0 | 托管 Chrome/Edge 的安装与版本锁定 |
+| [`pixelmatch`](https://github.com/mapbox/pixelmatch) | ISC | 页面截图像素比对 |
+| [`sharp`](https://github.com/lovell/sharp)（optional） | Apache-2.0 | 图片解码与规格校验；缺失时视觉模块明确阻塞 |
 
 开发依赖（TypeScript、ESLint、Prettier、Vitest、Vite、tsx 等）各自遵循其开源许可，且不随 npm 发布产物分发。
 

package/dist/agents/gui-instance.js

@@ -1,5 +1,5 @@
 /**
- * GUI 桌面实例（ZCode / Codex / TraeWork）的 spawn 选项。
+ * GUI 桌面实例（TraeWork / ZCode / Codex / Kimi Code / Qoder CN）的 spawn 选项。
  *
  * `detached: true` 是**不变量**，不是平台偏好：桌面实例必须自成进程组、脱离父进程，否则父进程
  * （MCP server，或一次性 smoke / probe 脚本）退出时会把它连坐杀掉，`run_task` 的 `keptInstance`

package/dist/mcp/handlers.js

@@ -1,5 +1,5 @@
 /**
- * 9 个工具的具体 handler。统一返回 ToolResult（文本 + meta 块）。
+ * 11 个工具的具体 handler。统一返回 ToolResult（文本 + meta 块）。
  * run_task / rework / verify 依赖 AppContext 提供的 manager/engine/services。
  */
 import fsp from "node:fs/promises";

package/dist/server.js

@@ -1,6 +1,6 @@
 /**
  * server.ts：组装 —— 加载配置、初始化数据目录/日志、TaskManager/AcceptanceEngine/
- * Registry、注册 9 个工具到 McpServer、触发技能自检安装。被 index.ts 调用以 stdio 启动。
+ * Registry、注册 11 个工具到 McpServer、触发技能自检安装。被 index.ts 调用以 stdio 启动。
  */
 import path from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -45,7 +45,7 @@ export async function buildServer(opts = {}) {
     });
     const server = new McpServer({ name: "tianshu-mcp", version: MCP_SERVER_VERSION }, {
         capabilities: { tools: {} },
-        instructions: "tianshu-mcp：调度外部 AI-Agent（codex/zcode/traework）完成项目开发、验收、返修闭环。ZCode 提问或等待用户环境处理时进入 needs_user，可用 continue_task 恢复原会话。run_task 异步返回 taskId，再用 query_task 轮询。",
+        instructions: "tianshu-mcp：调度外部 AI-Agent（codex/zcode/traework/kimicode/qoder）完成项目开发、验收、返修闭环。ZCode 提问或等待用户环境处理时进入 needs_user，可用 continue_task 恢复原会话。run_task 异步返回 taskId，再用 query_task 轮询。",
     });
     for (const tool of TOOL_DEFS) {
         const handler = handlers[tool.name];

package/dist/version.generated.js

@@ -4,4 +4,4 @@
  * 本文件由 scripts/sync-version.mjs 在每次 build 前重新生成。
  */
 // generated: 勿手改 —— 运行 `npm run build` 自动同步
-export const MCP_SERVER_VERSION = "0.5.7";
+export const MCP_SERVER_VERSION = "0.5.8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tianshu-mcp",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "天枢 × AI-Agent 编排 MCP server —— 驱动 Codex、TraeWork、ZCode、Kimi Code 与 Qoder CN 完成项目开发、验收、失败返修与再验收闭环。",
   "type": "module",
   "license": "Apache-2.0",
@@ -24,6 +24,7 @@
     "docs/visual-validation.md",
     "docs/visual-validation.en.md",
     "docs/visual-validation-evidence",
+    "scripts/probe-traework.mjs",
     "scripts/probe-zcode.mjs",
     "scripts/probe-codex.mjs",
     "scripts/probe-kimicode.mjs",
@@ -62,6 +63,9 @@
     "check:stdio": "node scripts/check-stdio.mjs --entry dist/index.js",
     "check:stdio:src": "node scripts/check-stdio.mjs --entry src/index.ts --tsx",
     "smoke:zcode": "node scripts/smoke-zcode.mjs",
+    "probe:traework": "node scripts/probe-traework.mjs",
+    "probe:zcode": "node scripts/probe-zcode.mjs",
+    "probe:codex": "node scripts/probe-codex.mjs",
     "probe:kimicode": "node scripts/probe-kimicode.mjs",
     "probe:qoder": "node scripts/probe-qoder.mjs",
     "fixture:zcode": "node scripts/prepare-zcode-fixture.mjs",

package/scripts/probe-traework.mjs

@@ -0,0 +1,108 @@
+/**
+ * TraeWork CDP 真机探针（开发计划 §7：真机探针不入 CI，手动运行）。
+ *
+ * 用法：
+ *   node scripts/probe-traework.mjs                 # 连接并 dump 选择器状态
+ *   node scripts/probe-traework.mjs selectors       # 同上（显式）
+ *   node scripts/probe-traework.mjs send "任务书"    # 端到端：新建会话 → 发送 → 等回复
+ *   node scripts/probe-traework.mjs project <路径>   # 新建会话 → 绑定项目文件夹
+ *
+ * 前提：TraeWork 已以 --remote-debugging-port=<port> 启动且窗口可见。
+ * 端口取 TRAEWORK_CDP_PORT 环境变量，默认 9222。
+ */
+import { TraeworkCdpClient } from "../dist/agents/traework/cdp/client.js";
+import { SELECTORS, resolveSelectors } from "../dist/agents/traework/cdp/selectors.js";
+import { startNewSession, bindProject, listSessions, readProjectItems, readMode, ensureMode } from "../dist/agents/traework/ui/session.js";
+import { typeAndSend } from "../dist/agents/traework/ui/composer.js";
+import { judgePoll, makeMarker, parseAdded } from "../dist/agents/traework/ui/reply.js";
+
+const PORT = Number(process.env.TRAEWORK_CDP_PORT || 9222);
+const mode = process.argv[2] || "selectors";
+
+const logger = {
+  info: (m) => console.log(`[probe] ${m}`),
+  warn: (m) => console.warn(`[probe][warn] ${m}`),
+  error: (m) => console.error(`[probe][error] ${m}`),
+  debug: (m) => console.log(`[probe][debug] ${m}`),
+};
+
+const cdp = new TraeworkCdpClient({ port: PORT });
+await cdp.connect();
+console.log(`[probe] CDP 已连接（端口 ${PORT}）`);
+
+if (mode === "selectors") {
+  console.log("[probe] 选择器实测状态：");
+  for (const key of Object.keys(SELECTORS)) {
+    const spec = SELECTORS[key];
+    const exists = await cdp.exists(key);
+    const text = exists ? (await cdp.text(key)).slice(0, 60) : "";
+    const mark = exists ? "OK  " : "MISS";
+    console.log(`  ${mark} ${key.padEnd(22)} verified=${spec.verified ? "Y" : "N"} ${exists ? JSON.stringify(text) : `(${resolveSelectors(key)[0]})`}`);
+  }
+  const liveness = await cdp.probeLiveness();
+  console.log("[probe] 运行状态探针：", JSON.stringify(liveness));
+  console.log("[probe] 任务列表：", (await listSessions(cdp)).slice(0, 10).join(" | ") || "(空)");
+}
+
+if (mode === "project") {
+  const target = process.argv[3];
+  if (!target) {
+    console.error("[probe] 用法: node scripts/probe-traework.mjs project <项目绝对路径>");
+    process.exit(1);
+  }
+  await startNewSession(cdp, { logger });
+  console.log("[probe] 已新建会话");
+  const items = await readProjectItems(cdp);
+  console.log(`[probe] 下拉项目 ${items.length} 项：`, items.map((i) => i.name).join("、") || "(空)");
+  const r = await bindProject(cdp, target, { logger });
+  console.log("[probe] 绑定结果：", JSON.stringify(r));
+}
+
+if (mode === "mode") {
+  const target = process.argv[3];
+  console.log("[probe] 当前模式:", (await readMode(cdp)) || "(读不到)");
+  if (!target) {
+    console.log("[probe] 用法: node scripts/probe-traework.mjs mode <Work|Code|Design>");
+  } else if (!["Work", "Code", "Design"].includes(target)) {
+    console.error("[probe] 模式必须是 Work | Code | Design");
+    process.exit(1);
+  } else {
+    const ok = await ensureMode(cdp, target, { logger });
+    console.log(`[probe] 切换到 ${target} 结果:`, ok, "| 当前:", (await readMode(cdp)) || "(读不到)");
+  }
+}
+
+if (mode === "send") {
+  const text = process.argv[3];
+  if (!text) {
+    console.error('[probe] 用法: node scripts/probe-traework.mjs send "任务书"');
+    process.exit(1);
+  }
+  await startNewSession(cdp, { logger });
+  const marker = makeMarker();
+  await typeAndSend(cdp, marker + text, { logger });
+  console.log("[probe] 已发送，开始轮询…");
+  const base = await cdp.text("messageContainer");
+  let state = { prev: "", stable: 0, idleSince: 0 };
+  const deadline = Date.now() + 180_000;
+  for (;;) {
+    if (Date.now() > deadline) {
+      console.log("[probe] 超时");
+      break;
+    }
+    await new Promise((r) => setTimeout(r, 3000));
+    const current = await cdp.text("messageContainer");
+    const liveness = await cdp.probeLiveness();
+    const v = judgePoll(current, marker, base, state, 12, { liveness, idleTimeoutMs: 10 * 60_000 });
+    if (v.kind === "finished" || v.kind === "ask_user" || v.kind === "idle") {
+      const parsed = parseAdded(v.added);
+      console.log(`[probe] 结束（${v.kind}），正文 ${parsed.content.length} 字符：`);
+      console.log(parsed.content.slice(0, 2000));
+      break;
+    }
+    state = v.state;
+  }
+}
+
+cdp.disconnect();
+console.log("[probe] 完成");

package/skills/tianshu-mcp/SKILL.md

@@ -39,7 +39,7 @@ run_task（秒回 taskId，异步）
 | `run_task` | write + 审批 | 派活给外部 agent；**异步**返回 `taskId` | 见 §3 |
 | `query_task` | read | 轮询状态 + agent 日志尾（`tailLines` 缺省 40 行） | `taskId`、`tailLines?` |
 | `list_tasks` | read | 查历史任务（每行：taskId / status / agent / project / 摘要） | `projectPath?`、`status?`、`limit?`（缺省 50，上限 200） |
-| `get_task_report` | read | 读某轮验收报告 **Markdown 全文**（唯一不带 meta 块的工具） | `taskId`、`round?`（0-based，缺省最新） |
+| `get_task_report` | read | 读某轮验收报告 **Markdown 全文** | `taskId`、`round?`（0-based，缺省最新） |
 | `verify_task` | read | 对任务或任意项目**独立验收**（不改源码、无需审批） | `taskId` 或 `projectPath` 二选一、`extraChecks?`、`checksMode?`、`baselineRef?` |
 | `rework_task` | write + 审批 | 手动返修：终态任务重新入队续跑（同 agent/项目、同一轮次记账） | `taskId`、`feedback?` |
 | `continue_task` | write + 审批 | 恢复 `needs_user`（仅 codex/zcode/kimicode/qoder） | `taskId`、`message`（必填） |
@@ -207,7 +207,7 @@ meta 的 `needsUserKind` 给出等待类型，`pendingQuestion` 给出问题原
 
 ### 8.1 验收报告解读
 
-`get_task_report(taskId, round?)` 返回报告 Markdown 全文（**唯一不带 meta 块的工具**；其他工具结果末尾都带 `---tianshu-mcp-meta---` JSON 块，字段全表见 usage-examples.md §4）。
+`get_task_report(taskId, round?)` 返回报告 Markdown 全文。**注意：报告类与视觉基准类工具的成功结果不带 meta 块**——`get_task_report` 返回报告原文，`prepare_visual_baseline` / `approve_visual_baseline` 返回视觉操作的 JSON 原文；其余工具结果末尾都带 `---tianshu-mcp-meta---` JSON 块（字段全表见 usage-examples.md §4），任何工具的**错误**结果也不带 meta 块。
 
 - `checks[]`：每项 PASS / FAIL / SKIP + 输出尾部。默认**并行 2 条**（`verifyConcurrency`，1–4）；checks 之间有顺序依赖（后续读 build 产物、带 `--fix`、共享缓存目录）时**必须显式设 1**，否则偶发误报。
 - `analysis`：变更清单、diffstat、可疑标记命中（TODO/FIXME、`console.log`/`debugger`、疑似密钥形态、超大单文件改动告警）。这是**确定性规则，不是 LLM 评审**，命中只提示人工，不等同于任务失败。

package/skills/tianshu-mcp/usage-examples.md

@@ -219,7 +219,11 @@ run_task(projectPath=/path/to/项目, agentId=codex-cli,
 
 ## 4. meta 块解读（字段全表）
 
-除 `get_task_report` 外，各工具结果文本末尾都是「人类可读文本 + 结构化 meta」：
+除下列情况外，各工具结果文本末尾都是「人类可读文本 + 结构化 meta」：
+
+- `get_task_report` 成功时直接返回 `report-<round>.md` 原文；
+- `prepare_visual_baseline` / `approve_visual_baseline` 成功时直接返回视觉操作的 JSON 原文；
+- **任何工具的错误结果**都只有 `Error: …` 文本，不带 meta 块。
 
 ```text
 ---tianshu-mcp-meta---