tianshu-mcp 0.5.6 → 0.5.8

package/CHANGELOG.en.md

@@ -8,6 +8,45 @@ 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
+
+- **The orchestration skill docs (`skills/tianshu-mcp/`) were rewritten item by item against the current code** (`SKILL.md` + `usage-examples.md`; the server idempotently syncs them into `~/.rivet/skills/tianshu-mcp/`). Every claim was checked against `src/mcp/tools.ts`, `src/config/schema.ts`, `src/tasks/task.ts`, `src/tasks/task-manager.ts`, `src/loop/fix-loop.ts`, `src/mcp/formatter.ts`, `src/agents/builtin.ts` and the five adapters:
+  - Added a **parameter compatibility matrix** (projectPath / model / modelSource / reasoningLevel / mode / planDoc / designSystem / allowCreateProject / continue_task across five agents) that states plainly what is rejected rather than silently ignored.
+  - Corrected the **Kimi Code tier domain**: it previously read `Low`/`High`/`Max`, but only `低/low`, `高/high`, `max`, `on` and `off` are accepted (deliberately no `中`/`medium`); the tier set is validated against the labels the UI actually renders, and an omitted tier forces `on` for unofficial models.
+  - Corrected the **`autoVerify` default** (on by default at the server level, previously undocumented) and completed the **`autoFixRounds` defaults** (codex 5 / zcode 2 / kimicode 2 / qoder 3 / traework falls back to the server default 0) plus the full `taskTimeoutMs` precedence.
+  - Added a full **qoder** section: `modelSource` disambiguation, saving and reading back the tier in Model Management, the global preference never being restored, send/answer checkpoints that never resend, automatic and manual repair both writing a plan and sending its full text back, macOS dispatch being disabled, and a multi-question JSON answer example.
+  - Added a **`needsUserKind` × agent × `continue_task` behaviour matrix** (six wait kinds × four agents), which previously was scattered per agent and never stated which kinds are confirmation-only and which re-send the complete brief.
+  - Added an **`agentEndReason` → terminal-state mapping** (`task_timeout` / `idle_timeout` / `cdp_disconnected` versus other hard failures landing in `needs_attention` or `failed(spawn)`), plus the missing `project_not_registered`, `unsupported_platform` and `qoder_error` (18 concrete codes) entries.
+  - Completed the **meta field table** with `qoderSessionId`, `actualModel`, `actualReasoningLevel`, `modelSource` and `guiStop`, and noted that `reasoningLevel` is an input that is never echoed while codex's effective tier is only visible in its panel.
+  - Clarified the three **`verify_task`** modes (task re-verification only updates the verdict fields; an independent `projectPath` accepts only a git ref as `baselineRef`; manual verification allocates a new report round) and the required arguments of `prepare_visual_baseline` / `approve_visual_baseline` (UUID plus a 64-hex digest).
+  - Removed duplicated material and split responsibilities: the main file teaches the method, the sub-file gives copy-ready shapes with wording matched to the real error strings.
+
 ## [0.5.6] - 2026-09-22
 
 ### Added
@@ -814,6 +853,8 @@ 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
 [0.5.4]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.5.3...v0.5.4

package/CHANGELOG.md

@@ -7,6 +7,45 @@
 
 ---
 
+## [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
+
+### 变更
+
+- **编排技能文档（`skills/tianshu-mcp/`）按当前代码逐项重写**（`SKILL.md` + `usage-examples.md`，server 启动时幂等同步到 `~/.rivet/skills/tianshu-mcp/`）。逐项核对了 `src/mcp/tools.ts`、`src/config/schema.ts`、`src/tasks/task.ts`、`src/tasks/task-manager.ts`、`src/loop/fix-loop.ts`、`src/mcp/formatter.ts`、`src/agents/builtin.ts` 与五个适配器的实际实现后修正偏差：
+  - 新增**参数兼容矩阵**（projectPath / model / modelSource / reasoningLevel / mode / planDoc / designSystem / allowCreateProject / continue_task 九个维度 × 五个 agent），明确「传错即报错」的边界。
+  - 修正 **Kimi Code 思考档位取值域**：此前写作 `Low`/`High`/`Max`，实际仅接受 `低/low`、`高/high`、`max`、`on`、`off`（刻意不含 `中`/`medium`），且档位集合按界面实际渲染标签校验、非官方模型不传时强制 `on`。
+  - 修正 **`autoVerify` 默认值**（server 默认开启，此前文档未说明），补全 **`autoFixRounds` 缺省轮数**（codex 5 / zcode 2 / kimicode 2 / qoder 3 / traework 落 server 默认 0）与 `taskTimeoutMs` 的完整优先级。
+  - 补齐 **qoder** 章节：`modelSource` 消歧、模型管理档位保存回读、全局偏好不还原、发送/答题检查点不重发、自动与手动返修均先落计划并回发全文、macOS 禁止派发；新增 qoder 多题续答 JSON 对象示例。
+  - 新增 **`needsUserKind` × agent × `continue_task` 行为矩阵**（六类等待 × 四类 agent），此前按 agent 零散描述且未写清哪些类型只作「已处理」确认、哪些会补发完整任务书。
+  - 新增 **`agentEndReason` → 终态映射表**（`task_timeout`/`idle_timeout`/`cdp_disconnected` 与其余硬失败分别落 `needs_attention` 或 `failed(spawn)`），并补 `project_not_registered`、`unsupported_platform`、`qoder_error`（含 18 个具体码）等缺失错误码。
+  - 补齐 **meta 字段全表**缺失项：`qoderSessionId`、`actualModel`、`actualReasoningLevel`、`modelSource`、`guiStop`（并说明 `reasoningLevel` 是入参不回显、codex 实际等级需看面板）。
+  - 明确 **`verify_task` 三种用法差异**（任务复验只更新结论字段；独立 projectPath 的 `baselineRef` 只能是 git ref；手动验收报告轮次分配）与 `prepare_visual_baseline`/`approve_visual_baseline` 的必填参数约束（UUID + 64 位十六进制摘要）。
+  - 清理重复与冗余内容，改为「主文件讲方法论 + 子文件给可复制形状」的分工；中英文表述与代码实际错误文案对齐。
+
 ## [0.5.6] - 2026-09-22
 
 ### 新增
@@ -709,6 +748,8 @@ 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
 [0.5.4]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.5.3...v0.5.4

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)
 
@@ -214,6 +227,11 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
 | [docs/kimi-cdp.en.md](docs/kimi-cdp.en.md) | Kimi Code GUI driver: two renderer processes (main window + `Kimi Browser Overlay`), full-path workspace binding with native-dialog import, three-stage model selection and thinking tiers, execution mode, run detection and troubleshooting |
 | [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) |
 | [docs/release-v0.5.4.en.md](<docs/release-v0.5.4.en.md>) | v0.5.4 release notes (optional AI visual content validation: user-supplied command delegation, majority-vote debouncing, warning-only by default) |
 | [docs/release-v0.5.3.en.md](<docs/release-v0.5.3.en.md>) | v0.5.3 release notes (ZCode hardware-revisit fixes: instance survival across server exit, new-task page switch, send-failure attribution) |
 | [docs/release-v0.5.2.en.md](<docs/release-v0.5.2.en.md>) | v0.5.2 release notes (ZCode project-less dispatch and `allowCreateProject`, issue #12) |
@@ -261,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.4`)
+  - 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)
@@ -352,6 +370,31 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
   - **Fail-closed**: once enabled, an unresolvable command or a missing env reference yields a whole-round `configurationError` with no result rows; a single command failure produces only a blocked warning item that stays visible in the round message and in the repair plan's "warning-only items (no fix required)" section
   - **Defect fix**: the repair plan no longer lists `optional:true` failures as "must fix"
   - **CLI/diagnostics**: added `visual content probe <project> [ruleId]` and `visual content cache clear <taskId>`; `visual doctor` gained content-command resolution and budget-comparison findings
+- **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 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**
+  - **Installation discovery and instance reuse**: explicit `gui.exePath` → D-drive-first candidates → relative-path templates → standard directories, with Qoder CN identity checks; an existing instance without usable CDP is preserved in place and turned into `needs_user`, never closed or restarted
+  - **Workspaces and models**: full-path binding, with unregistered directories imported through New Task → Workspace → New Workspace → Add Read/Write Folder; `modelSource=default/custom` disambiguates cross-group name clashes; the thinking tier is saved in Model Management as a **global preference** and read back by reopening it, and an unsupported tier fails before sending
+  - **Send and answer checkpoints**: a checkpoint is written before sending the brief or submitting multi-question answers, and an unconfirmed receipt means observe-only, never an automatic resend; `continue_task` only reobserves for approval/login environment waits
+  - **Liveness and same-session repair**: completion must belong to this turn's user message (old replies, a static screen, and disconnects never qualify); both automatic and manual repair write the plan first, then send its filename, full path, and complete text to the original conversation
+  - **Platform boundary**: the Windows hardware loop passed (default/custom models, a newly registered workspace, and controlled failure → plan → same-session repair → re-acceptance); macOS is `research` and fail-closed
+  - See the [Qoder CN guide](docs/qoder-cdp.en.md) and the [v0.5.6 release notes](<docs/release-v0.5.6.en.md>)
+- **M26 — Orchestration skill docs rewritten against the code + v0.5.7** (2026-09-22) — **826 tests** (no runtime change)
+  - **Parameter compatibility matrix**: `projectPath`/`model`/`modelSource`/`reasoningLevel`/`mode`/`planDoc`/`designSystem`/`allowCreateProject`/`continue_task` across the five built-in agents, stating plainly that a wrong parameter is rejected
+  - **Default precedence**: `autoVerify` (on by default at the server level), `autoFixRounds` (codex 5 / zcode 2 / kimicode 2 / qoder 3) and `taskTimeoutMs`
+  - **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
 
@@ -428,7 +471,7 @@ Behavior and limits:
 
 | Document | Content |
 |---|---|
-| [CHANGELOG.en.md](<CHANGELOG.en.md>) | Version history (v0.1.0 → v0.5.4) |
+| [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 |
@@ -487,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 个）
 
@@ -204,13 +217,18 @@ run_task(projectPath=D:/xxx/my-app, agentId=kimicode, task=「按 `./plan.md`
 | [ARCHITECTURE.md](ARCHITECTURE.md) | **架构说明**：分层模型与模块边界、启动装配、数据目录、状态机、验收与返修流水线、Agent 驱动层契约、GUI 实例生命周期、跨平台策略、安全红线、扩展点、已知缺口 |
 | [docs/tianshu-integration.md](docs/tianshu-integration.md) | 天枢 config.json 两种接入模式、UI/API 操作、冒烟步骤、FAQ |
 | [docs/agent-profiles.md](docs/agent-profiles.md) | agent profiles 字段说明 + 真实机器样例（codex M2 定稿） |
-| [docs/adapter-matrix.md](docs/adapter-matrix.md) | 各 Agent 能力调研矩阵（Codex/Zcode/TraeWork/Kimi Code/扩展位） |
+| [docs/adapter-matrix.md](docs/adapter-matrix.md) | 各 Agent 能力调研矩阵（Codex/Zcode/TraeWork/Kimi Code/Qoder CN/扩展位） |
 | [docs/traework-cdp.md](docs/traework-cdp.md) | TraeWork GUI 驱动（CDP）：原理、配置、模式切换、选择器、安全红线、踩坑记录、验证记录 |
 | [docs/zcode-cdp.md](docs/zcode-cdp.md) | ZCode GUI 驱动：安装探测、精确项目/模型、完全访问、暂停继续、验收返修与双平台状态 |
 | [docs/zcode-windows-smoke.md](docs/zcode-windows-smoke.md) | ZCode Windows 真机开发、同会话返修与提问续跑验收记录 |
 | [docs/codex-gui-cdp.md](docs/codex-gui-cdp.md) | Codex 桌面端 GUI 驱动：MSIX COM 激活、CDP 接管、选择器、运行检测、验收返修 |
 | [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 适配：双渲染进程、工作区完整路径绑定与原生导入、模型三级选择与档位校验、运行检测与恢复） |
 | [docs/release-v0.5.4.md](<docs/release-v0.5.4.md>) | v0.5.4 发布说明（可选 AI 视觉内容校验：自备命令委托、多数票防抖、默认仅告警） |
 | [docs/release-v0.5.3.md](<docs/release-v0.5.3.md>) | v0.5.3 发布说明（ZCode 真机回访修复：实例跨 server 驻留、新建任务切页、发送失败归因） |
 | [docs/release-v0.5.2.md](<docs/release-v0.5.2.md>) | v0.5.2 发布说明（ZCode 无项目派发与 `allowCreateProject`，issue #12） |
@@ -262,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.4`）
+  - 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）
@@ -353,6 +371,31 @@ run_task(projectPath=D:/xxx/my-app, agentId=kimicode, task=「按 `./plan.md`
   - **fail-closed**：启用后命令不可解析/env 引用缺失 → 整轮 `configurationError` 且不产出结果行；单项命令失败仅产生 blocked 告警项，并在整轮消息与返修计划的「仅告警项（不必修复）」小节可见
   - **缺陷修复**：返修计划不再把 `optional:true` 的失败列为「必须修复」
   - **CLI/诊断**：新增 `visual content probe <project> [ruleId]` 与 `visual content cache clear <taskId>`；`visual doctor` 新增内容命令解析与预算对比两项 finding
+- **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`），请求不到的档位在发送前报错
+  - **运行检测与恢复**：`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 测试**
+  - **安装发现与实例复用**：显式 `gui.exePath` → D 盘优先候选 → 相对路径模板 → 标准目录；校验 Qoder CN 身份；已有实例无可用 CDP 时保留现场转 `needs_user`，绝不关闭或重启
+  - **工作区与模型**：完整路径绑定，未登记目录经「新的任务 → 工作区 → 新建工作区 → 添加可读写文件夹」原生导入；`modelSource=default/custom` 消除跨组重名；思考等级经「模型管理」保存为**全局偏好**并重新打开回读，不支持的档位在发送前报错
+  - **发送与答题检查点**：发送任务书与提交多题答案前落检查点，未确认回执时只观察、不自动重发；`continue_task` 对审批/登录等环境等待只恢复观察
+  - **运行判定与原会话返修**：完成必须绑定本轮用户消息（历史回复、界面静止、断线均不算）；自动与手动返修都先落修复计划，再把文件名、完整路径与全文发送原会话
+  - **平台边界**：Windows 真机闭环通过（默认/自定义模型、新登记工作区、受控失败 → 落计划 → 原会话返修 → 再验收）；macOS 为 `research` 且 fail-closed
+  - 详见 [Qoder CN 文档](docs/qoder-cdp.md) 与 [v0.5.6 发布说明](<docs/release-v0.5.6.md>)
+- **M26 — 编排技能文档按代码实况重写 + v0.5.7**（2026-09-22）— **826 测试**（无运行时变更）
+  - **参数兼容矩阵**：`projectPath`/`model`/`modelSource`/`reasoningLevel`/`mode`/`planDoc`/`designSystem`/`allowCreateProject`/`continue_task` 九个维度 × 五个内置 agent，写清「传错即报错」
+  - **默认值优先级**：`autoVerify`（server 默认开启）、`autoFixRounds`（codex 5 / zcode 2 / kimicode 2 / qoder 3）、`taskTimeoutMs` 取值顺序
+  - **修正 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 适配现状
 
@@ -430,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.4） |
+| [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) | 贡献者行为准则 |
@@ -489,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.6";
+export const MCP_SERVER_VERSION = "0.5.8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tianshu-mcp",
-  "version": "0.5.6",
+  "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] 完成");