tianshu-mcp 0.5.0 → 0.5.1

package/CHANGELOG.en.md

@@ -10,16 +10,6 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ## [Unreleased]
 
-### Tests
-
-- Two additional real-browser-gated visual cases (added after v0.5.0): screenshots succeed when the project path contains CJK characters and spaces; a main-document 302 redirect to a non-allowlisted origin is blocked by policy and passes once explicitly allowed. Full suite: **486 passed / 10 skipped**.
-- New `npm run evidence:visual:windows` (`scripts/evidence-visual-windows.mjs`): collects the full Windows 10 local functional matrix (existing/static/command sources, port conflict that blocks without terminating another service, bounded readiness failure that cleans up the child process, local Edge isolated instance and version mismatch, missing-browser blocker), 9/9 passed.
-- Collected macOS 13+ platform evidence: on macOS 15 hardware runners, Intel x64 and Apple Silicon arm64 (Node 20/22/24) each passed 10 files with 51 cases; raw records are committed under `docs/visual-validation-evidence/`.
-
-### Docs
-
-- `docs/visual-validation{,.en}.md` rewritten with full platform evidence tables (system, Node, browser version, command, result), plus the new `docs/visual-validation-evidence/` raw machine-readable records.
-
 ### Planned
 
 - More external AI-Agent adapters (a new agent = one profile + an optional adapter file).
@@ -31,6 +21,32 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.5.1] — 2026-09-14
+
+Documentation and validation-evidence completion; **no runtime behaviour changes**. See the [v0.5.1 release notes](docs/release-v0.5.1.en.md) for details.
+
+### Added
+
+- `npm run evidence:visual:windows` (`scripts/evidence-visual-windows.mjs`): collects the full Windows 10 local functional matrix (existing/static/command sources, port conflict that blocks without terminating another service, bounded readiness failure that cleans up the child process, local Edge isolated instance and version mismatch, missing-browser blocker), 9/9 passed.
+- `docs/visual-validation-evidence/`: raw machine-readable validation records (Windows 10 matrix JSON and test output, macOS dual-architecture `environment.json`, macOS CI summaries), distributed with the package.
+
+### Fixed
+
+- Stale `package-lock.json` root version: the lockfile still said `0.4.1` at the v0.5.0 release while `package.json` said `0.5.0`; both are now synced to `0.5.1`.
+
+### Tests
+
+- Two additional real-browser-gated visual cases: screenshots succeed when the project path contains CJK characters and spaces; a main-document 302 redirect to a non-allowlisted origin is blocked by policy and passes once explicitly allowed. Full suite: **486 passed / 10 skipped**.
+- Collected macOS 13+ platform evidence: on macOS 15 hardware runners, Intel x64 and Apple Silicon arm64 (Node 20/22/24) each passed 10 files with 51 cases.
+
+### Docs
+
+- **Skill docs (`skills/tianshu-mcp/`) aligned with the code**: `SKILL.md` now lists all 11 tools with capability/approval columns (including `prepare_visual_baseline`/`approve_visual_baseline`), gives visual acceptance its own section (blockers do not trigger repair; `rework_task` re-verifies first; baseline approval and freezing), adds `setup_recovery` and the `errorType` value set to the error table, corrects agent status semantics (`traework` is always `ready`; `codex` is platform-dependent) and notes that `continue_task` only supports codex/zcode. `usage-examples.md` fixes the claim that `get_task_report` carries a meta block, removes the mis-listed `reasoningLevel` from the meta table, distinguishes the auto repair-plan location per agent (codex writes inside the project's `.zcode/plans/`; others write to the task directory), and adds the actual `list_tasks` output columns plus the visual CLI commands.
+- `docs/visual-validation{,.en}.md` rewritten with full platform evidence tables (system, Node, browser version, command, result).
+- Bilingual README and HANDOFF updated against the current code and commit history.
+
+---
+
 ## [0.5.0] — 2026-09-14
 
 Adds an **optional visual acceptance module** that wires screenshot comparison and static image specification checks into the "develop → verify → repair → re-verify" loop. Projects that do not enable visuals behave compatibly, and legacy reports and task snapshots remain readable. See the [v0.5.0 release notes](docs/release-v0.5.0.en.md) for the full description.

package/CHANGELOG.md

@@ -9,16 +9,6 @@
 
 ## [未发布]
 
-### 测试
-
-- 视觉验收补两条真实浏览器门禁用例（v0.5.0 之后补充）：项目路径含中文与空格时截图正常；主文档 302 跳转到未放行来源时按策略拦截，显式放行后通过。全量测试 **486 passed / 10 skipped**。
-- 新增 `npm run evidence:visual:windows`（`scripts/evidence-visual-windows.mjs`）：在 Windows 10 本机采集完整功能矩阵证据（`existing`/静态/命令三种来源、端口冲突阻塞且不结束他人服务、就绪失败有界阻塞并清理子进程、本机 Edge 独立实例与版本不匹配、缺浏览器阻塞），9/9 通过。
-- 采集 macOS 13+ 平台证据：macOS 15 真机 runner 上 Intel x64 与 Apple Silicon arm64（Node 20/22/24）各跑通 10 文件 51 用例；原始记录随 `docs/visual-validation-evidence/` 入库。
-
-### 文档
-
-- `docs/visual-validation{,.en}.md` 重写为完整平台证据表（系统、Node、浏览器版本、命令、结果），并新增 `docs/visual-validation-evidence/` 原始机器可读记录。
-
 ### 计划中
 
 - 更多外部 AI-Agent 适配（新 agent = 一个 profile +（如需）一个 adapter 文件）。
@@ -29,6 +19,32 @@
 
 ---
 
+## [0.5.1] — 2026-09-14
+
+文档与验证证据补齐；**无运行时行为变更**。完整说明见 [v0.5.1 发布说明](docs/release-v0.5.1.md)。
+
+### 新增
+
+- `npm run evidence:visual:windows`（`scripts/evidence-visual-windows.mjs`）：在 Windows 10 本机采集完整功能矩阵证据（`existing`/静态/命令三种来源、端口冲突阻塞且不结束他人服务、就绪失败有界阻塞并清理子进程、本机 Edge 独立实例与版本不匹配、缺浏览器阻塞），9/9 通过。
+- `docs/visual-validation-evidence/`：视觉验收验证的原始机器可读记录（Windows 10 矩阵 JSON 与测试输出、macOS 双架构 `environment.json`、macOS CI 摘要），随包分发。
+
+### 修复
+
+- `package-lock.json` 根包版本滞后：v0.5.0 发布时锁文件仍为 `0.4.1`（与 `package.json` 的 `0.5.0` 不一致），本版本同步为 `0.5.1`。
+
+### 测试
+
+- 视觉验收补两条真实浏览器门禁用例：项目路径含中文与空格时截图正常；主文档 302 跳转到未放行来源时按策略拦截，显式放行后通过。全量测试 **486 passed / 10 skipped**。
+- 采集 macOS 13+ 平台证据：macOS 15 真机 runner 上 Intel x64 与 Apple Silicon arm64（Node 20/22/24）各跑通 10 文件 51 用例。
+
+### 文档
+
+- **技能文档（`skills/tianshu-mcp/`）对齐代码实况**：`SKILL.md` 补全 11 个工具表与能力/审批列（含 `prepare_visual_baseline`/`approve_visual_baseline`），视觉验收独立成节（阻塞不触发返修、`rework_task` 先重新验收、基准审批与冻结），错误码表补 `setup_recovery` 与 `errorType` 取值，修正 agent 状态语义（`traework` 恒为 `ready`、`codex` 平台相关）与 `continue_task` 仅支持 codex/zcode；`usage-examples.md` 修正 `get_task_report` 不带 meta 块、移除 meta 表误列的 `reasoningLevel`、按 agent 区分自动修复计划落盘位置（codex 在项目内 `.zcode/plans/`、其余在任务目录），并补 `list_tasks` 实际输出列与视觉 CLI 命令。
+- `docs/visual-validation{,.en}.md` 重写为完整平台证据表（系统、Node、浏览器版本、命令、结果）。
+- 双语 README 与 HANDOFF 按当前代码与提交历史更新。
+
+---
+
 ## [0.5.0] — 2026-09-14
 
 新增**可选视觉验收模块**：把页面截图对比与静态图片规格检查接入「开发 → 验收 → 返修 → 再验收」闭环。未启用视觉的项目行为兼容；旧报告与旧任务快照仍可读取。完整说明见 [v0.5.0 发布说明](docs/release-v0.5.0.md)。

package/README.en.md

@@ -8,7 +8,7 @@
 
 # tianshu-mcp
 
-Visual acceptance (v0.5.0): [English guide](docs/visual-acceptance.en.md) · [Validation record](docs/visual-validation.en.md) · [Release notes](<docs/release-v0.5.0.en.md>).
+Visual acceptance (since v0.5.0): [English guide](docs/visual-acceptance.en.md) · [Validation record](docs/visual-validation.en.md) · [Latest release notes](<docs/release-v0.5.1.en.md>).
 
 **Tianshu × AI-Agent orchestration MCP server**
 
@@ -36,7 +36,7 @@ Registered by Tianshu as a standard MCP server, it dispatches external AI-Agents
 
 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 GUI) is the "worker" that does the development.
 
-- **9 MCP tools**: `run_task / continue_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles`.
+- **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).
@@ -195,6 +195,7 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
 | [docs/codex-gui-cdp.en.md](docs/codex-gui-cdp.en.md) | Codex desktop GUI driver: MSIX COM activation, CDP attach, selectors, run detection, verify/repair |
 | [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/release-v0.5.1.en.md](<docs/release-v0.5.1.en.md>) | v0.5.1 release notes (skill/validation docs, archived platform evidence, lockfile version sync; no runtime changes) |
 | [docs/release-v0.5.0.en.md](<docs/release-v0.5.0.en.md>) | v0.5.0 release notes (optional visual acceptance: screenshots, image specs, baseline approval, offline report) |
 | [docs/visual-acceptance.en.md](<docs/visual-acceptance.en.md>) | Visual acceptance primer and full configuration: three page sources, baseline candidates/approval, rule freezing, thresholds and troubleshooting |
 | [docs/visual-validation.en.md](<docs/visual-validation.en.md>) | Visual acceptance validation progress: full Windows 10 matrix and macOS Intel/Apple Silicon platform evidence (system/Node/browser/command/result) |
@@ -236,9 +237,9 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
   - Zcode headless entry (Z1) verified: ZCode desktop ships no headless CLI → unsupported
 - **R1–R8 / S1–S6 — two acceptance hardening rounds** ✅ (cancel / timeout / baseline attribution / parameter semantics / hot reload / CI hardening) — **72 tests**
 - **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.0 tag) and `Release` (tag-triggered) both green
+  - 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.0`)
+  - npm package name `tianshu-mcp` published continuously since v0.1.1 (currently `0.5.1`)
 - **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)
@@ -307,6 +308,11 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
   - **MCP/CLI**: new `prepare_visual_baseline` / `approve_visual_baseline` and the `tianshu-mcp visual` subcommand family, dispatched before the stdio connection
   - **Reports and recovery**: `VerifyReport` gains an optional `visual` section and offline HTML (status filter, opacity overlay, region location); visual blockers enter `needs_attention` and `rework_task` re-verifies first so only real defects consume repair budget
   - **Gates**: CI adds a four-system, three-Node real-browser matrix plus isolated production-package consumer acceptance; release requires a successful CI for the target commit and blocks when Gitee credentials are missing rather than claiming success
+- **M20 — skill/validation docs aligned + platform evidence archived + v0.5.1** (2026-09-14) — **486 tests**
+  - Skill docs aligned item by item with the code: a full 11-tool table with capability/approval columns, visual acceptance given its own section, `setup_recovery` added to the error table, and fixes to agent status semantics plus the `get_task_report`/`repair-plan` doc drift
+  - Visual acceptance platform evidence archived: Windows 10 local full functional matrix **9/9** (`npm run evidence:visual:windows`), and macOS 15 hardware Intel x64 plus Apple Silicon arm64 with 10 files / 51 cases each
+  - Fixed the stale `package-lock.json` root version (was `0.4.1` at v0.5.0)
+  - **No runtime behaviour changes**; no migration needed
 
 ## Agent support status
 
@@ -379,7 +385,7 @@ Behavior and limits:
 
 | Document | Content |
 |---|---|
-| [CHANGELOG.en.md](<CHANGELOG.en.md>) | Version history (v0.1.0 → v0.5.0) |
+| [CHANGELOG.en.md](<CHANGELOG.en.md>) | Version history (v0.1.0 → v0.5.1) |
 | [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 |

package/README.md

@@ -8,7 +8,7 @@
 
 # tianshu-mcp
 
-视觉验收（v0.5.0）：[中文指南](docs/visual-acceptance.md) · [验证记录](docs/visual-validation.md) · [发布说明](<docs/release-v0.5.0.md>)。
+视觉验收（v0.5.0 起）：[中文指南](docs/visual-acceptance.md) · [验证记录](docs/visual-validation.md) · [最新发布说明](<docs/release-v0.5.1.md>)。
 
 **天枢 × AI-Agent 编排 MCP server**
 
@@ -36,7 +36,7 @@
 
 天枢的角色是总指挥；本 MCP server 是**调度层 + 执行面 + 客观验收仪**；外部 AI-Agent（Codex / TraeWork / ZCode GUI）是执行开发的「工人」。
 
-- **9 个 MCP 工具**：`run_task / continue_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles`。
+- **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`）。
 - **客观验收**：自动命令检查（typecheck/lint/test/build，缺则跳过 + 技术栈推导）+ 程序化代码分析（变更清单/diffstat/TODO·debugger·密钥形态等可疑标记），全部相对 **git 基线**，不自动 commit/stash。验收引擎 **fail-closed**：测试命令退出码为 0 但输出显示零用例时判失败；git 项目默认要求相对动工前基线产生变更（纯分析任务可在 `.tianshu-mcp/acceptance.json` 设 `"requireChanges": false` 显式关闭）。
 - **验收并行度**：命令检查默认**有界并行**（`verifyConcurrency`，默认 2、范围 1–4）。检查项之间有顺序依赖时（后续检查读取 build 产物、带 `--fix`、共享缓存目录）请设 `1` 完全退化为串行；项目级 `.tianshu-mcp/acceptance.json` 可覆盖，server 级在 `config.json`。报告与日志格式不变（结果按声明顺序返回）。
@@ -88,7 +88,7 @@ npm install -g tianshu-mcp
 | 命令 | `npx` | `node` |
 | 参数（空格分隔） | `-y tianshu-mcp` | `<仓库绝对路径>/dist/index.js` |
 
-> - 服务器 ID 即工具前缀：填 `tianshu-mcp` 后工具名为 `mcp__tianshu-mcp__run_task` 等 9 个。
+> - 服务器 ID 即工具前缀：填 `tianshu-mcp` 后工具名为 `mcp__tianshu-mcp__run_task` 等 11 个。
 > - 参数按空格分隔填写，**不要加引号**；本地开发模式请把 `<仓库绝对路径>` 换成真实绝对路径（如 `D:/Trae项目/tianshu-mcp/dist/index.js`）。
 > - 界面未提供环境变量输入框；如需自定义数据目录，改用下面的 `config.json` 方式设置 `TIANSHU_MCP_HOME`。
 > - 添加后连接成功即完成；新开会话即可看到 11 个工具。
@@ -190,6 +190,7 @@ ZCode 提问、需要登录、旧实例无 CDP、系统权限不足，或自动
 | [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/codex-windows-smoke.md](docs/codex-windows-smoke.md) | Codex Windows 真机验收记录（含验收失败→自动生成计划→返修通过闭环） |
+| [docs/release-v0.5.1.md](<docs/release-v0.5.1.md>) | v0.5.1 发布说明（技能/验证文档补齐、平台证据归档、锁文件版本同步；无运行时变更） |
 | [docs/release-v0.5.0.md](<docs/release-v0.5.0.md>) | v0.5.0 发布说明（可选视觉验收模块：截图对比、图片规格、基准批准、离线报告） |
 | [docs/visual-acceptance.md](<docs/visual-acceptance.md>) | 视觉验收入门与完整配置：三种页面来源、基准候选/批准、规则冻结、阈值与排查 |
 | [docs/visual-validation.md](<docs/visual-validation.md>) | 视觉验收验证进度：Windows 10 完整功能矩阵与 macOS Intel/Apple Silicon 平台证据（系统/Node/浏览器/命令/结果） |
@@ -235,9 +236,9 @@ ZCode 提问、需要登录、旧实例无 CDP、系统权限不足，或自动
   - Zcode 无头接口（Z1）实测定论：ZCode 桌面无随包 headless CLI → unsupported
 - **R1–R8 / S1–S6 — 两轮验收整改** ✅（取消/超时/基线归因/参数语义/热加载/CI 加固）— **72 测试**
 - **工程 / 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.0 tag 全绿）与 `Release`（tag 触发）均绿
+  - 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.0`）
+  - npm 包名 `tianshu-mcp` 自 v0.1.1 起持续发布（当前 `0.5.1`）
 - **天枢宿主真实接入（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）
@@ -306,6 +307,11 @@ ZCode 提问、需要登录、旧实例无 CDP、系统权限不足，或自动
   - **MCP/CLI**：新增 `prepare_visual_baseline` / `approve_visual_baseline` 与 `tianshu-mcp visual` 子命令族；CLI 在 stdio 连接前分流
   - **报告与恢复**：`VerifyReport` 新增可选 `visual` 与离线 HTML（状态过滤、透明叠加、区域定位）；视觉阻塞进 `needs_attention`，`rework_task` 先重新验收、仅真实缺陷才消耗返修预算
   - **门禁**：CI 新增真实浏览器四系统三 Node 矩阵与生产包独立消费者验收；release 要求目标提交存在成功 CI，缺少 Gitee 凭据时阻塞不冒充成功
+- **M20 — 技能/验证文档对齐 + 平台证据归档 + v0.5.1**（2026-09-14）— **486 测试**
+  - 技能文档逐项对齐代码实况：11 工具表（补能力/审批列）、视觉验收独立成节、错误码补 `setup_recovery`、修正 agent 状态语义与 `get_task_report`/`repair-plan` 的文档偏差
+  - 归档视觉验收平台证据：Windows 10 本机完整功能矩阵 **9/9**（`npm run evidence:visual:windows`）、macOS 15 真机 Intel x64 与 Apple Silicon arm64 各 10 文件 51 用例
+  - 修复 `package-lock.json` 根包版本滞后（v0.5.0 时为 `0.4.1`）
+  - 本版本**无运行时行为变更**，升级无需迁移
 
 ## Agent 适配现状
 
@@ -379,7 +385,7 @@ run_task(projectPath=/path/to/项目, agentId=codex-cli, task="任务书", autoV
 | 文档 | 内容 |
 |---|---|
 | [HANDOFF.md](HANDOFF.md) | 项目交接文档：当前状态快照、架构导览、硬性红线、已知限制、接手建议 |
-| [CHANGELOG.md](<CHANGELOG.md>) | 版本变更日志（v0.1.0 → v0.5.0） |
+| [CHANGELOG.md](<CHANGELOG.md>) | 版本变更日志（v0.1.0 → v0.5.1） |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | 开发环境、工程规范、提交与发布流程、如何新增 agent |
 | [SECURITY.md](SECURITY.md) | 安全模型（凭证零管理/命令白名单/进程与桌面自动化边界）与私密报告渠道 |
 | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | 贡献者行为准则 |

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.0";
+export const MCP_SERVER_VERSION = "0.5.1";

package/docs/visual-validation.en.md

@@ -72,7 +72,7 @@ Note: these are real macOS systems and real architectures on GitHub-hosted macOS
 - GitHub release: `tag v0.5.0` (not a draft) with asset `tianshu-mcp-0.5.0.tgz` and a bilingual body.
 - Gitee release: `tag v0.5.0` (id 1143672) targeting `b1505f5`, with a bilingual body.
 - Both repos are consistent: `github/master`, `gitee/master`, both remotes' `v0.5.0` tags and the local tag all resolve to `b1505f5` (later `master` advanced to the record commit `de34278`).
-- **npm registry is out of scope this round**: per the plan ("does not additionally add npm registry publishing"), the npm package remains at `0.4.1`.
+- **npm publish (outside the plan, per explicit user instruction)**: the maintainer's npm account is logged in and owns the package; `npm publish` successfully published `tianshu-mcp@0.5.0` to `latest` (confirmed by a direct registry query; `dist.shasum` = `85c39756…`, matching the local build). A fresh `npm install tianshu-mcp@0.5.0` in an isolated directory passes all four `visual doctor` checks. Plan §7 originally stated "does not additionally add npm registry publishing"; this publish was performed on the user's explicit instruction so the README's "published continuously" statement stays consistent across versions.
 
 ## 4. Known limitations
 

package/docs/visual-validation.md

@@ -72,7 +72,7 @@
 - GitHub 发行：`tag v0.5.0`（非草稿），资产 `tianshu-mcp-0.5.0.tgz`，正文为双语发行说明。
 - Gitee 发行：`tag v0.5.0`（id 1143672），目标提交 `b1505f5`，正文为双语发行说明。
 - 双仓一致：`github/master`、`gitee/master`、两仓 `v0.5.0` 标签与本地标签均指向 `b1505f5`（其后 `master` 前进到 `de34278` 的记录提交）。
-- **npm registry 未在本次范围内**：按计划「不额外增加 npm registry 发布」，npm 包仍停留在 `0.4.1`。
+- **npm 发布（计划外，按用户指示执行）**：维护者 npm 账号已登录且为包所有者，`npm publish` 成功将 `tianshu-mcp@0.5.0` 发布到 `latest`（registry 直查确认，`dist.shasum` = `85c39756…`，与本地构建一致）。独立目录 `npm install tianshu-mcp@0.5.0` 后 `visual doctor` 四项全通过。开发计划 §7 原本「不额外增加 npm registry 发布」，本次按用户明确指示补发，以保持 README「持续发布」表述与历史版本一致。
 
 ## 四、已知限制
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tianshu-mcp",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "天枢 × AI-Agent 编排 MCP server —— 驱动 Codex CLI、TraeWork GUI 与 ZCode GUI 完成项目开发、验收、失败返修与再验收闭环。",
   "type": "module",
   "license": "Apache-2.0",

package/skills/tianshu-mcp/SKILL.md

@@ -1,33 +1,41 @@
 ---
 name: tianshu-mcp
-description: 让外部 AI-Agent（codex/zcode/traework）做项目开发并自动验收、失败返修的编排方法。当任务需要"叫一个 AI-Agent 去开发/改代码/补测试并验收，不行就返修"时先加载本技能：按它用 mcp__tianshu-mcp__ 的 11 个工具（run_task/continue_task/query_task/list_tasks/get_task_report/verify_task/rework_task/cancel_task/get_profiles）派活、暂停继续、轮询、查历史、读验收报告、驱动返修，并按硬失败错误码快速定位卡点。小改动或纯问答不需要。
+description: 让外部 AI-Agent（codex/zcode/traework）做项目开发并自动验收、失败返修的编排方法。当任务需要"叫一个 AI-Agent 去开发/改代码/补测试并验收，不行就返修"时先加载本技能：按它用 mcp__tianshu-mcp__ 的 11 个工具（run_task/continue_task/query_task/list_tasks/get_task_report/verify_task/rework_task/cancel_task/get_profiles/prepare_visual_baseline/approve_visual_baseline）派活、暂停继续、轮询、查历史、读验收报告、驱动返修、管理视觉基准，并按硬失败错误码快速定位卡点。小改动或纯问答不需要。
 triggers: '开发|编码|写代码|改代码|实现功能|加功能|修复|重构|补测试|写测试|验收|返修|返工|重做|自动验收|自动返修|任务书|ai.?agent|子代理|外部.?agent|agent|codex|zcode|traework|claude|编排|项目开发|派活|派单'
 ---
 
 # tianshu-mcp 编排技能：叫外部 AI-Agent 开发并验收
 
-## 视觉验收与基准保护
+**首行强指令**：你正处理"派外部 AI-Agent 开发并验收、失败返修"类任务。动手前先通读本技能全文；任务书模板、四种 agent 派活示例、meta 块字段全表、错误码速查、返修提示语模板在同目录 `usage-examples.md`，需要时用读取文件工具查看，长方法论不必背。
 
-项目启用 visual 后，继续通过 run_task/verify_task 验收，读取报告的独立 visual 结果及 HTML/图片证据。视觉缺陷返修时附检查 ID、路由/文件、视口、实际指标与差异区域。不得修改基准、阈值、屏蔽区域或关闭规则绕过失败。
+## 工具面（11 个）
 
-prepare_visual_baseline 只准备候选；approve_visual_baseline 只能在用户查看候选并明确授权后调用，必须带预期摘要和批准说明。审批标注不能替代宿主实际授权控制。自动返修不得批准基准。needs_attention 的视觉阻塞先处理环境或审批，再 rework_task；系统应先重新验收，通过后无需启动 agent。
-
-Visual acceptance uses the existing task tools and independent visual evidence. Never weaken baselines, thresholds, masks or enabled rules to bypass failures. Baseline approval requires explicit user review and authorization; automatic repair must never approve candidates. Resolve blockers before rework_task, which verifies first.
-
-**首行强指令**：你正处理"派外部 AI-Agent 开发并验收、失败返修"类任务。动手前先通读本技能全文；任务书模板、三种 agent 派活示例、meta 块字段全表、错误码速查、返修提示语模板在同目录 `usage-examples.md`，需要时用读取文件工具查看，长方法论不必背。
+| 工具 | 能力 / 审批 | 作用 |
+|---|---|---|
+| `run_task` | write + 审批 | 派活给外部 agent 开发；异步返回 taskId |
+| `query_task` | read | 轮询状态与 agent 日志尾 |
+| `list_tasks` | read | 按项目/状态查历史任务 |
+| `get_task_report` | read | 读某轮验收报告全文（Markdown） |
+| `verify_task` | read | 对任务或任意项目独立验收（不改源码） |
+| `rework_task` | write + 审批 | 手动返修；对视觉阻塞任务先重新验收 |
+| `cancel_task` | write + 审批 | 取消运行中的任务 |
+| `continue_task` | write + 审批 | 恢复 `needs_user`（仅 codex/zcode） |
+| `get_profiles` | read | 查看 agent 适配与可执行探测结果 |
+| `prepare_visual_baseline` | write + 审批 | 视觉基准**候选**准备（截图或导入参考图） |
+| `approve_visual_baseline` | write + 审批 | 用户审阅后批准候选，写入正式基准 |
 
 ## 何时不要用（边界）
 
 - 小改动 / 纯问答 / 只读代码分析：不需要本技能与 MCP，直接做。
 - 本 MCP 未连接：工具面里看不到 `mcp__tianshu-mcp__*` 时，先提示用户按天枢 `config.json → mcp.servers.tianshu-mcp` 接入（见项目 docs/tianshu-integration.md），**不要空转**，更不要假装调用。
 
-## 1. 选 agent（默认三者均为 GUI 驱动：CDP 控制桌面端，非 CLI）
+## 1. 选 agent（默认均为 GUI 驱动：CDP 控制桌面端，非 CLI）
 
-- `codex`（默认，推荐先试）：ChatGPT 桌面端。**model 必填**（面板可选模型名，如 `GPT-5.6 Sol`）；可选 `reasoningLevel`（低/中/高 或 low/medium/high）、`planDoc`（计划文档路径）、`designSystem`（设计系统目录路径）；**不支持 `mode`**。Windows 经 MSIX COM 激活 + CDP（冷启动实测 60–90 秒，首轮偏慢属正常）；macOS 直接 spawn `ChatGPT.app` + CDP。
+- `codex`（默认，推荐先试）：ChatGPT/Codex 桌面端。**model 必填**（面板可选模型名，如 `GPT-5.6 Sol`）；可选 `reasoningLevel`（低/中/高 或 low/medium/high）、`planDoc`（计划文档路径）、`designSystem`（设计系统目录路径）；**不支持 `mode`**（传了直接报错）。Windows 经 MSIX COM 激活 + CDP（冷启动实测 60–90 秒，首轮偏慢属正常）；macOS 直接 spawn `ChatGPT.app` + CDP。
 - `zcode`：ZCode 桌面端（Electron CDP）。要求已安装、已登录；**model 必填**且格式为 `供应商/模型`（如 `DeepSeek/deepseek-flash`）；**不支持 `mode`**；发送前确认「完全访问」权限模式。
-- `traework`：TraeWork（TRAE SOLO CN）桌面端。要求已登录、窗口保持可见。`model` 可选；`mode` 可选（`Work`/`Code`/`Design`；不传时从任务书文本识别「切换 X 模式」，识别不到保持 `Work`；实现顺序为「新建会话 → 切模式 → 在目标模式内绑定项目」）。
-- `codex-cli`（可选，用户自建 profile，非内置）：不想依赖 GUI 自动化时的**无头**路径，走 `codex exec`。需用户先在数据目录 `agent-profiles.json` 加一个 `driver=spawn` 的 profile（示例见 README「macOS 无头路径：codex-cli」）。`model` 对它不生效，模型取 CLI 的 `~/.codex/config.toml`。注意 CLI 版本：≤0.130.0 签名证书已被吊销，macOS Gatekeeper 会直接 SIGKILL，需 ≥0.154.0。
-- 状态语义：`ready` 表示当前平台闭环已验证；`research` 表示已实现但矩阵未覆盖（**仍可执行**）。Windows 上 `codex`/`traework` 为 `ready`、`zcode` 为 `research`；macOS 上 `codex`/`zcode` 基本闭环已真机验证，但取消/返修/新建项目矩阵未覆盖，两者 darwin 仍为 `research`。
+- `traework`：TraeWork（TRAE SOLO CN）桌面端。要求已登录、窗口保持可见。**`model` 可选**；**`mode` 可选**（`Work`/`Code`/`Design`；不传时从任务书文本识别「切换 X 模式」，识别不到保持 `Work`；实现顺序为「新建会话 → 切模式 → 在目标模式内绑定项目」）。`continue_task` **不支持 traework**。
+- `codex-cli`（可选，用户自建 profile，非内置）：不想依赖 GUI 自动化时的**无头**路径，走 `codex exec`。需用户先在数据目录 `agent-profiles.json` 加一个 `driver=spawn` 的 profile（示例见 README「macOS 无头路径：codex-cli」）。`model` 参数对它**不生效**，模型取 CLI 的 `~/.codex/config.toml`。注意 CLI 版本：≤0.130.0 签名证书已被吊销，macOS Gatekeeper 会直接 SIGKILL，需 ≥0.154.0。
+- 状态语义：`ready` 表示当前平台闭环已验证；`research` 表示已实现但矩阵未覆盖（**仍可执行**）。内置取值：`traework` 为 `ready`，`zcode` 为 `research`，`codex` 在 Windows 为 `ready`、在 darwin 为 `research`（macOS 上 `codex`/`zcode` 基本闭环已真机验证，但取消/返修/新建项目矩阵未覆盖）。注意 `ready` 不等于全平台无限制：TraeWork 在 macOS 下的可执行探测与原生对话框驱动仍 fail-closed（见 README 计划中条款）。
 - 不确定时问用户，或读项目 `projects.json` 的 `defaultAgentId`；用 `get_profiles` 看当前机器实际探测结果（含可执行探测、未安装提示与用户自定义 profile）。
 
 ## 2. 派活：run_task
@@ -36,11 +44,11 @@ Visual acceptance uses the existing task tools and independent visual evidence.
 
 - `projectPath`：**必须**是项目绝对路径（如 `D:\repo\my-app`），且提交即过安全闸门（见 §2.1）。
 - `task`：自然语言任务书。要写清 **目标 / 验收要点 / 约束 / 相关文件 / 上下文**，模板见 usage-examples.md。
-- `agentId`：默认取项目 default 或 codex；`model`/`mode`/`reasoningLevel` 等约束见 §1。
+- `agentId`：默认取项目 default 或 codex；`model`/`mode`/`reasoningLevel` 等约束见 §1（按 agent 生效，传错会被明确拒绝）。
 - `context`：补充上下文/约束文本，会以【上下文与约束】拼进 agent 初始指令。task/context 中反引号包裹或路径形态的引用会在发送前校验（必须存在且在项目内），写错立即报错。
-- `autoVerify: true`：跑完自动验收（命令检查 + 代码分析）。
-- `autoFixRounds: N`（0–10）：>0 才开启失败自动返修。优先级：调用参数 > agent 缺省（codex 5、zcode 2）> server 默认 0（不开启）。
-- `taskTimeoutMs`：任务级超时；缺省 30 分钟。
+- `autoVerify: true`：跑完自动验收（命令检查 + 代码分析；启用视觉的项目再加视觉检查）。
+- `autoFixRounds: N`（0–10）：>0 才开启失败自动返修。优先级：调用参数 > agent 缺省（codex 5、zcode 2；traework 未设缺省）> server 默认 0（不开启）。
+- `taskTimeoutMs`：任务级超时。优先级：调用参数 > profile 的 `timeoutMs` > server 默认 30 分钟。
 
 返回立刻给 `taskId`（异步契约）。**不要把任务书当同步调用等结果。**
 
@@ -63,40 +71,53 @@ Visual acceptance uses the existing task tools and independent visual evidence.
 
 ## 4. needs_user：continue_task
 
-meta 块中 `needsUserKind` 给出等待类型、`pendingQuestion` 给出问题原文：
+meta 块中 `needsUserKind` 给出等待类型、`pendingQuestion` 给出问题原文。**仅 codex/zcode 可恢复**，traework 会被拒绝。
 
 - `agent_question`（zcode）：agent 提了问题 → 用 `continue_task(taskId, message=<答案>)`，message 会发到原会话。
 - `close_existing_instance` / `system_permission` / `setup_recovery`（zcode）：需用户先处理（关闭旧实例 / 授系统权限 / 在 ZCode 里确认目标项目或手工完成绑定）→ 用户处理完后调 `continue_task(taskId, message=<已处理说明>)`，message 仅作为已处理的确认（**不会**当问题发送）。
 - `user_confirmation`（codex）：Codex 停在等待用户确认界面（方案确认卡/订阅确认等），turn 暂停而非结束 → 用户在 **Codex 窗口**完成处理后调 `continue_task(taskId, message=<已处理说明>)`；恢复后仅重新接入观察 GUI 内运行（**不发送消息**），turn 完成/失败由观察得出。
-- `login_required`（codex/zcode）：Codex 需要登录 → 在窗口完成登录后 `continue_task(taskId, message=<已处理说明>)`；codex 会复检环境后重新派发任务书。
+- `login_required`（codex/zcode）：需要登录 → 在窗口完成登录后 `continue_task(taskId, message=<已处理说明>)`；codex 会复检环境后重新派发任务书（新会话 + 项目绑定 + 完整初始指令）。
 
 限制与纪律：
 
 - `continue_task` 只接受 `needs_user` 状态；其他状态会被明确拒绝。
 - codex 只支持 `login_required` / `user_confirmation` 两种等待类型，其余会拒绝。
-- zcode 恢复依赖原会话定位信息（`zcodeSessionId`）；定位信息丢失时明确拒绝恢复，**不会**擅自打开"最近会话"。
+- zcode `agent_question` 恢复依赖原会话定位信息（`zcodeSessionId`）；定位信息丢失时明确拒绝恢复，**不会**擅自打开"最近会话"。
 - 禁止新开会话冒充恢复。
 
 ## 5. 终态解读
 
 - `succeeded`：用 `get_task_report(taskId, round?)`（round 为 0-based 报告轮次，缺省最新）取 changedFiles / diffstat / checks，向用户汇报变更与结论。
 - `failed`：**未开自动返修或硬失败**。读 meta 的 `errorType` 与 `get_task_report` 定位失败 checks；如可修 → `rework_task(taskId, feedback=失败摘要)` 手动续修（feedback 会作为追加指示给下一轮 agent）；再轮询或 `verify_task`。
-- `needs_attention`：自动返修轮次已用尽仍失败。同样先读报告，给**针对性** feedback 调 `rework_task`（不要无脑重复同样的话）。多次仍不过或不可修：如实向用户汇报并给建议（人工看报告 / 换 agent / 缩小任务），**不要反复空转重试**。
+- `needs_attention`：两类含义——①自动返修轮次已用尽仍失败；②**验收阻塞**（配置/完整性错误，或视觉阻塞如缺基准、页面不可达、资源被拦）。同样先读报告，给**针对性** feedback 调 `rework_task`。视觉阻塞时 `rework_task` 会**先重新验收、不先启动 agent**：通过即结束，仍阻塞则回到 `needs_attention`，只有出现真实缺陷才启动返修。多次仍不过或不可修：如实向用户汇报并给建议（人工看报告 / 换 agent / 缩小任务），**不要反复空转重试**。
 - `cancelled` / `interrupted`：用户取消或超时/中断（meta 的 `abortSource` 区分 user/shutdown/timeout/internal）。`running` 卡死可用 `cancel_task(taskId, reason)` 终止：CLI agent 终止进程树；GUI agent（codex/zcode/traework）尽力点击界面停止按钮并等待 GUI 空闲（有界超时），取消文案会如实标注 GUI 侧是否已停止——若标注"未确认停止"，窗口内的运行可能仍在继续，需人工检查，**不要在确认停止前重派同项目任务**（会新旧交叠；重派护栏也会以 `instance_busy` 直接拒绝派发）。
 - `needs_user` 状态下取消：run 协程已退出、CDP 已断开，MCP 侧无法再点 GUI 停止按钮，取消文案会提示"GUI 内可能仍有等待中的会话，请人工检查"。
 
 ## 6. 验收报告解读要点
 
-- 结果文本末尾有 `---tianshu-mcp-meta---` 块（JSON），天枢可正则抽取；字段全表见 usage-examples.md。
-- 报告全文走 `get_task_report`：`checks[]`（每项 PASS/FAIL/SKIP + 输出尾部）、`analysis`（变更清单、diffstat、可疑标记命中计数、超大单文件改动告警）。
-- `verify_task` 可对任务或任意项目独立验收（**不改源码、无需审批**）：`taskId` / `projectPath` 二选一；`extraChecks` 临时加验（`checksMode` 默认 append 追加，`replace` 才替换）；`baselineRef` 可填任务 ID（用该任务动工前基线）或 git ref（如 `HEAD~1`）；独立 projectPath 不设 baselineRef 时按当前基线做健康检查。
+- 除 `get_task_report`（直接返回报告 Markdown 原文）外，其余工具结果文本末尾都带 `---tianshu-mcp-meta---` 块（JSON），天枢可正则抽取；字段全表见 usage-examples.md。
+- 报告全文走 `get_task_report(taskId, round?)`：`checks[]`（每项 PASS/FAIL/SKIP + 输出尾部）、`analysis`（变更清单、diffstat、可疑标记命中计数、超大单文件改动告警）、以及在启用视觉时的独立 `visual` 段落。`round` 为 0-based 报告轮次，缺省取最新；显式 `round: 0` 合法。
+- `verify_task` 可对任务或任意项目独立验收（**不改源码、无需审批**）：`taskId` / `projectPath` 二选一；`extraChecks` 临时加验（`checksMode` 默认 append 追加，`replace` 才替换）；`baselineRef` 可填任务 ID（用该任务动工前基线）或 git ref（如 `HEAD~1`）；独立 projectPath 不设 baselineRef 时按当前基线做健康检查。对任务 ID 验收只更新其验收结论字段（`latestVerificationVerdict`），**不改写原任务终态**；独立 projectPath 且遇配置/视觉阻塞时，独立 vfy 记录落 `needs_attention`。
 - 验收命令优先级：`extraChecks` > 项目 `.tianshu-mcp/acceptance.json` > projects.json 管理员补录 > 按技术栈推导的默认集。
 - **检查项默认并行 2 条**（`verifyConcurrency`，范围 1–4，v0.4.0 起；此前为串行）。项目级 `.tianshu-mcp/acceptance.json` 可覆盖。若 checks 之间有顺序依赖（后续读 build 产物、带 `--fix`、共享缓存目录），需把 `verifyConcurrency` 显式设为 `1` 退化为串行，否则会偶发误报。
 - `requireChanges` 门禁：项目配置默认开启——相对动工前基线**零变更**会被判失败（防止 agent"什么都没做却报成功"）。纯只读/纯排查类任务要在 `.tianshu-mcp/acceptance.json` 设 `requireChanges: false`，否则必然失败。
 - 注意：代码分析是确定性规则（TODO/FIXME、console.log/debugger、疑似密钥形态、超大改动），**不是** LLM 评审——命中仅提示人工，不等同于任务失败。
 - changedFiles/diffstat 都相对**动工前 git 基线**（run_task 自动采集，含未跟踪新增）。MCP 不自动 commit/stash；需要回滚时由用户基于报告决定。
 
-## 7. 硬失败与错误码速查
+## 7. 视觉验收与基准保护
+
+项目在 `.tianshu-mcp/acceptance.json` 配置 `visual` 且 `enabled: true` 后，`run_task`/`verify_task` 自动带上截图对比与静态图片规格检查，**不需要新工具**。
+
+- 验收结论：视觉缺陷（布局差异、图片规格错误、可定位的交互失败）按 `autoFixRounds` 返修；视觉阻塞（缺基准、页面不可达、浏览器缺失、资源被策略拦截、截图不稳定）进 `needs_attention`，**不触发 agent 返修**——`rework_task` 会先只重新验收，不启动 agent、不额外消耗返修轮次，通过即结束，仍阻塞则回到 `needs_attention`。
+- 读 `get_task_report` 的 `visual` 段落与 `files.html` 离线报告（图片并排、透明叠加、区域定位）。返修时报告会给出检查 ID、路由/文件、视口、预期与实际指标、差异区域及证据路径。
+- **基准必须由用户审阅批准**：`prepare_visual_baseline` 只生成候选（返回 candidateId/digest/preview），`approve_visual_baseline` 只能在用户查看候选并明确授权后调用，且必须带 `expectedDigest` 与 `approvalNote`。缺基准只能生成候选、**不能判视觉通过**。
+- **禁止绕过**：不得为通过而修改基准、阈值、屏蔽区域或关闭规则——规则冻结会检出并报 `VISUAL_INTEGRITY`；配置或基准变化需用 `tianshu-mcp visual rules review/approve` 重建任务快照（CLI 在 stdio 前分流）。
+- **自动返修禁止调用批准入口**；两个工具都是有副作用的 `write` 操作，宿主必须实施实际授权控制（审批标注不能替代）。
+- 阻塞处理流程：先处理环境或完成审批，再 `rework_task`（系统先重新验收，通过后无需启动 agent）。
+
+Visual acceptance reuses the existing task tools with independent evidence. Never weaken baselines, thresholds, masks or enabled rules to bypass failures; baseline approval requires explicit user review and authorization, and automatic repair must never approve candidates. Resolve blockers before `rework_task`, which verifies first.
+
+## 8. 硬失败与错误码速查
 
 任务报告 `needs_attention` / `failed` 且属**硬失败**（`hardFailure`，不进验收与返修）时，读 meta 的 `agentEndReason` / `errorType` / `message` 直接定位，不要把硬失败当成"agent 没做好"反复重试。常见码：
 
@@ -114,12 +135,15 @@ meta 块中 `needsUserKind` 给出等待类型、`pendingQuestion` 给出问题
 | `session_lost` | zcode 找不到原会话锚点 | 用新任务重派（不要指望恢复原会话） |
 | `input_mismatch` / `send_unknown` | 发送前回读不一致 / 发送结果无法确认（**不重复发送**，避免重发） | 人工看窗口状态，必要时 `continue_task` 或重派 |
 | `idle_timeout` | GUI 长时间静止且无完成标志（现场已保留） | 看窗口里 agent 是否真的卡住；必要时 `continue_task` 或取消 |
+| `setup_recovery` | zcode 初始化/原生面板操作超时或恢复预算用尽 | 进 `needs_user`：请用户在 ZCode 确认项目/绑定后 `continue_task` |
 | `task_timeout`（`errorType=timeout`） | 任务级超时 | 大任务调大 `taskTimeoutMs`；或拆小任务 |
 | `aborted`（`errorType=cancelled`/`interrupted`） | 被取消/中断 | 按 §5 处理 |
 
-## 8. 纪律
+`errorType` 取值：`timeout` / `spawn` / `agent_failed` / `verify_failed` / `cancelled` / `interrupted` / `agent_unresolved` / `internal`。
+
+## 9. 纪律
 
-- 写/执行类工具（run/cancel/rework/continue）需审批：不绕过、不替用户代点同意；query/list/report/verify/get_profiles 为只读，无需审批。
+- 写/执行类工具（`run_task` / `cancel_task` / `rework_task` / `continue_task` / `prepare_visual_baseline` / `approve_visual_baseline`）需审批：不绕过、不替用户代点同意；`query_task` / `list_tasks` / `get_task_report` / `verify_task` / `get_profiles` 为只读，无需审批。
 - 不代替外部 agent 手改项目代码；不改用户 git 历史；不读取/转发任何 agent 密钥（登录态各 agent 自持）。
 - 验收命令来自白名单式配置、按 argv 分词执行，不做 shell 注入。
 - 本技能由 server 启动时幂等同步到 `~/.rivet/skills/tianshu-mcp/`（内容 hash 变化才覆盖，旧文件备份为 `.bak-<时间戳>`）；改技能以本仓库 `skills/` 为准。
@@ -128,5 +152,5 @@ meta 块中 `needsUserKind` 给出等待类型、`pendingQuestion` 给出问题
 
 1. `get_profiles` → 确认目标 agent 可用（看 status 与可执行探测结果）。
 2. `run_task(projectPath=<绝对路径>, task=<任务书>, agentId=codex, model=GPT-5.6 Sol, autoVerify=true, autoFixRounds=5)` → 拿 taskId（model 以 get_profiles/面板实际为准）。
-3. `query_task(taskId)` 每 ~8 秒轮询到终态；遇 `needs_user` 按 §4 处理，遇硬失败按 §7 定位。
-4. 终态处理见 §5；汇报时带 `get_task_report` 的 changedFiles 与 diffstat。
+3. `query_task(taskId)` 每 ~8 秒轮询到终态；遇 `needs_user` 按 §4 处理，遇硬失败按 §8 定位。
+4. 终态处理见 §5；汇报时带 `get_task_report` 的 changedFiles 与 diffstat；启用视觉时一并读 `visual` 段落与 HTML。

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

@@ -1,6 +1,6 @@
 # tianshu-mcp 使用示例（子文件）
 
-正文过长方法论不背：任务书模板、四种 agent 派活示例、meta 块字段全表、错误码速查、验收与返修模板、needs_user/取消示例都在这里，按需用读取文件工具查看。
+正文过长方法论不背：任务书模板、四种 agent 派活示例、meta 块字段全表、错误码速查、验收与返修模板、视觉验收与基准保护、needs_user/取消示例都在这里，按需用读取文件工具查看。
 
 ## 1. 任务书模板
 
@@ -76,6 +76,7 @@ continue_task(taskId=tsk_..., message=采用 PostgreSQL 方案)
 
 - `needsUserKind=agent_question`：message 作为答案发送到原会话。
 - `needsUserKind=close_existing_instance / login_required / system_permission / setup_recovery`：先让用户处理（关旧实例 / 登录 / 授系统权限 / 在 ZCode 里确认目标项目），message 仅作为用户已处理的确认。
+- **traework 不支持 `continue_task`**；若 traework 任务停在 `needs_user`，需人工处理后重派新任务。
 
 ### 2.3 traework（model 可选；唯一支持 mode）
 
@@ -102,10 +103,17 @@ run_task(projectPath=/path/to/项目, agentId=codex-cli,
 - `model` 参数对 spawn 类 agent **不生效**：CLI 用 `~/.codex/config.toml` 的默认模型；要锁模型可在 `argsTemplate` 里追加 `"-m", "<模型名>"`。
 - codex CLI 版本要求 ≥0.154.0（≤0.130.0 签名证书已吊销，macOS Gatekeeper 直接 SIGKILL）。
 - 写入被 `workspace-write` 沙箱限制在项目目录内；POSIX 下取消/超时对进程组 SIGTERM→SIGKILL。
+- **无头路径无 GUI 交互**：不存在 `user_confirmation` 这类 GUI 等待，`continue_task` 不适用；失败直接看 `agentEndReason` 与日志。
+
+### 2.5 返回与继续的通用约定
+
+- `run_task` 是**异步契约**：立即返回 `taskId`，不要当同步调用等结果。
+- 轮询间隔约 5–10 秒（`query_task` 缺省返回 agent 日志末 40 行）；同项目串行 + 全局并发默认 2，重复派单只会排队。
+- 只有 `needs_user` 可用 `continue_task` 恢复，且**仅 codex/zcode**；其余状态/agent 会被明确拒绝。
 
 ## 3. meta 块解读（字段全表）
 
-`run_task` / `query_task` 等结果文本末尾的结构化块：
+`run_task` / `query_task` / `verify_task` 等结果文本末尾的结构化块（**例外**：`get_task_report` 直接返回报告 Markdown 原文，不带 meta 块）：
 
 ```text
 ---tianshu-mcp-meta---
@@ -156,7 +164,10 @@ run_task(projectPath=/path/to/项目, agentId=codex-cli,
 | `zcodeSessionId` / `boundProjectPath` | 会话与项目绑定回执（zcode/codex） |
 | `modelProvider` / `permissionMode` | 实际生效的供应商标识与权限模式（zcode） |
 | `progressSummary` | 轮询期进度摘要 |
-| `model` / `mode` / `reasoningLevel` | 本次派单的模型 / 面板模式 / 思考等级（按 agent 生效） |
+| `finishedAt` | 终态落定时间 |
+| `model` / `mode` | 本次派单的模型 / 面板模式（按 agent 生效） |
+
+> `reasoningLevel`（codex）是**入参**，只影响派单，不回显在 meta 块里——要确认实际等级请看 Codex 面板。
 
 规则：`ok=true` 且 status=succeeded → 交付达成；否则先读 `message`，再按 `errorType`/`agentEndReason` 查 §4，最后读 `reportFiles.md` 全文定位。
 
@@ -256,6 +267,8 @@ approve_visual_baseline(candidateId=<uuid>, expectedDigest=<sha256>,
 - 不要为了通过而修改基准、阈值、屏蔽区域或关闭规则——会被规则冻结检测拦截并报 `VISUAL_INTEGRITY`。
 - 配置或基准变化时用 `tianshu-mcp visual rules review/approve` 建立新的任务快照（CLI 在 stdio 前分流）。
 - 视觉缺陷返修时，报告会给出检查 ID、路由/文件、视口、预期与实际指标、差异区域及证据路径。
+- 报告 `visual.results[]` 每项 status 为 `passed`/`failed`/`blocked`/`skipped`，并带 `optional`、稳定原因码 `code`、`repairable` 与产物路径；禁用视觉时整个 `visual` 字段省略（旧报告仍可读）。
+- CLI 辅助命令：`tianshu-mcp visual init|doctor [project]`、`visual browser install`、`visual artifacts clean <taskId> [--apply]`（默认只预览）。
 
 ## 6. 查历史：list_tasks 示例
 
@@ -267,7 +280,7 @@ list_tasks(projectPath=D:/repo/app, status=needs_attention, limit=10)
 list_tasks()
 ```
 
-返回含每条任务的 taskId/status/agentId/时间摘要，可用于接续 `get_task_report` / `rework_task`。
+返回每行一条的文本（列：taskId / status / agent / project / 任务摘要），可用于接续 `get_task_report` / `rework_task`。`projectPath` 会与 run_task 同样做 realpath 归一；`status` 传终态或过程态枚举值（如 `needs_attention`）。
 
 ## 7. 返修提示语模板
 
@@ -293,7 +306,12 @@ list_tasks()
 parameter of type 'number' (src/run.ts:42)。请只修这一处类型问题并重跑 npm run build 确认。
 ```
 
-补充：自动返修（autoFixRounds）路径下，server 会先把失败证据写成修复计划文档（写到项目 `.zcode/plans/`），并在下一轮指令中引用该文档；手动 `rework_task` 的 feedback 则按上面的针对性模板书写。
+补充：自动返修（autoFixRounds）路径下，server 会先把失败证据写成修复计划文档，再把该文档路径引用进下一轮指令。**落盘位置按 agent 不同**：
+
+- `codex`：写到**项目内** `fixPlanDir`（默认项目根 `.zcode/plans/codex-fix-r<N>.md`，文件名含轮次不覆盖历史）——因为 Codex 只能读项目工作区内的文件。
+- `zcode` / `traework` 等其余路径：写到 **MCP 任务数据目录**（`<home>/tasks/<taskId>/rework-<taskId>-r<N>.md`），避免临时计划污染项目工作区。
+
+手动 `rework_task` 的 feedback 则按上面的针对性模板书写，不生成计划文档。
 
 ## 8. needs_user 恢复与取消示例