tianshu-mcp 0.4.0 → 0.4.1

package/CHANGELOG.en.md

@@ -21,6 +21,42 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.4.1] — 2026-09-13
+
+Documentation release: the orchestration skill docs are aligned with the actual v0.4.0 tool
+surface, and the open-source repos now credit community contributors. No code behaviour changes.
+
+### Docs
+
+- **Skill docs fully aligned with the v0.4.0 tool surface** (`skills/tianshu-mcp/`, idempotently synced
+  into `~/.rivet/skills/tianshu-mcp/` at server startup):
+  - `SKILL.md` now documents the **projectPath safety gate** (absolute path + existing directory +
+    realpath canonicalization, rejection of the home directory and system/root directories, dirty-repo
+    warning), so an infrastructure rejection is not mistaken for an agent failure.
+  - `SKILL.md` adds a **hard-failure error-code reference** (`setup_failed`/`project_ambiguous`/
+    `project_mismatch`/`model_unavailable`/`model_mismatch`/`permission_unknown`/`cdp_disconnected`/
+    `instance_busy`/`session_lost`/`input_mismatch`/`send_unknown`/`idle_timeout` and more), stating
+    that hard failures never enter acceptance or auto-rework.
+  - `SKILL.md` covers all `needs_user` kinds, including the new `setup_recovery` (zcode initialization
+    recovery exhausted), plus `continue_task` state/type restrictions and the refusal semantics when the
+    zcode session anchor is lost.
+  - `SKILL.md` documents the `codex-cli` headless path (user-defined `driver=spawn` profile, `model` not
+    applicable, CLI ≥0.154.0 requirement), the `ready`/`research` status semantics, **default-parallel 2**
+    acceptance checks (`verifyConcurrency`), and the `requireChanges` zero-change gate.
+  - `usage-examples.md` adds: a `codex-cli` dispatch example; the **full meta-block field table** (now
+    including `agentEndReason`/`lastRunSignal`/`checks`/`round`/`keptInstance`/`zcodeSessionId`/
+    `modelProvider`/`permissionMode`/`progressSummary`); an **error-code reference table**; a project-level
+    `.tianshu-mcp/acceptance.json` template (with the parallel-interference warning and `requireChanges`
+    guidance); a `setup_recovery` recovery example; and the profile whole-key override semantics.
+- **Bilingual README contributor credits**: a new "Contributors" section lists, in order of first
+  participation, the community members who took part through Issues and pull requests (avatar + name).
+
+### Other
+
+- `package.json` version bumped to `0.4.1` (`serverInfo.version` is synced automatically at build time).
+
+---
+
 ## [0.4.0] — 2026-09-13
 
 ### Added
@@ -62,6 +98,16 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
   calls blew the `taskTimeoutMs` wall-clock budget under full-suite load.
 - CDP `connect()` failure paths now dispose of the WebSocket themselves (no longer relying on
   callers to disconnect); the `send()` timeout timer is unref'd.
+- **Drive roots were not rejected by the `projectPath` gate** (Windows): `normPath` strips the
+  trailing slash (`D:\` -> `d:`), which never equals the `d:/` entries in the reject list, so the
+  gate was effectively a no-op for drive roots; a dedicated drive-root check now covers every
+  drive letter instead of relying on enumeration.
+- `test/unit/project-dir-guard.test.ts` had a non-portable system-directory assertion: `/etc` and
+  `/usr` are POSIX paths, and on Windows they hit "directory does not exist" rather than the reject
+  list; the assertion is now platform-branched and verifies drive roots plus `C:/Windows` on Windows.
+- `test/unit/acceptance-parallel.test.ts` cancellation case was flaky (green alone, red in a full
+  run): a fixed 250ms delay can precede the child spawn on slower platforms, mislabelling an
+  in-flight check as `skipped`; it now waits until both in-flight checks have really started.
 
 ### Performance
 
@@ -591,7 +637,8 @@ project → pick model and reasoning level → send instructions → run detecti
 
 ---
 
-[Unreleased]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.4...v0.4.0
 [0.3.4]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.2...v0.3.3

package/CHANGELOG.md

@@ -19,6 +19,26 @@
 
 ---
 
+## [0.4.1] — 2026-09-13
+
+文档版本：把编排技能文档对齐 v0.4.0 实际工具面，并补齐开源仓库的贡献者名录。本版本无代码行为变更。
+
+### 文档
+
+- **技能文档全面对齐 v0.4.0 工具面**（`skills/tianshu-mcp/`，server 启动时幂等同步到 `~/.rivet/skills/tianshu-mcp/`）：
+  - `SKILL.md` 新增 **projectPath 安全闸门**说明（绝对路径 + 存在目录 + realpath 归一、主目录与系统根目录拒绝、脏仓警示），避免把基础设施拒绝误判为 agent 失败。
+  - `SKILL.md` 新增 **硬失败错误码速查**（`setup_failed`/`project_ambiguous`/`project_mismatch`/`model_unavailable`/`model_mismatch`/`permission_unknown`/`cdp_disconnected`/`instance_busy`/`session_lost`/`input_mismatch`/`send_unknown`/`idle_timeout` 等），明确硬失败不进验收与自动返修。
+  - `SKILL.md` 补全 needs_user 等待类型：新增 `setup_recovery`（zcode 初始化恢复未完成）；补 `continue_task` 的状态与类型限制、zcode 会话定位信息丢失时的拒绝语义。
+  - `SKILL.md` 补 `codex-cli` 无头路径（用户自建 `driver=spawn` profile、model 不生效、CLI ≥0.154.0 版本要求）、`ready`/`research` 状态语义、验收 **默认并行 2**（`verifyConcurrency`）与 `requireChanges` 零变更门禁。
+  - `usage-examples.md` 新增：`codex-cli` 派活示例；meta 块**字段全表**（补 `agentEndReason`/`lastRunSignal`/`checks`/`round`/`keptInstance`/`zcodeSessionId`/`modelProvider`/`permissionMode`/`progressSummary` 等）；**错误码速查表**；项目级 `.tianshu-mcp/acceptance.json` 配置模板（含 `verifyConcurrency` 并行干扰警示与 `requireChanges` 用法）；`setup_recovery` 恢复示例；profile 整键覆盖语义。
+- **双语 README 补贡献者名录**：新增「贡献者 / Contributors」小节，按首次参与顺序列出通过 Issue 与 PR 参与项目的社区成员（头像 + 名字）。
+
+### 其他
+
+- `package.json` 版本号提升至 `0.4.1`（`serverInfo.version` 经 build 自动同步）。
+
+---
+
 ## [0.4.0] — 2026-09-13
 
 ### 新增
@@ -50,6 +70,9 @@
 - `get_profiles` 列出数据目录 `agent-profiles.json` 中的用户自定义 profile（此前未 resolve 不显示，`run_task` 却可用，探测反馈不一致）。
 - zcode-flow 测试桩补 `listDialogs`，消除真实 osascript/PowerShell 调用在全量负载下撞 `taskTimeoutMs` 墙钟导致的 flake。
 - CDP `connect()` 失败分支自清理 WebSocket（不再依赖调用方兜底 disconnect）；`send()` 超时定时器 unref。
+- **盘符根未被 `projectPath` 闸门拦截**（Windows）：`normPath` 会剥掉尾斜杠（`D:\` → `d:`），与拒绝清单里的 `d:/` 永不相等，故闸门对盘符根形同虚设；改为**单独的盘符根判定**，覆盖所有盘符而不依赖枚举。
+- `test/unit/project-dir-guard.test.ts` 的系统目录断言不可移植：`/etc`、`/usr` 是 POSIX 路径，Windows 上命中的是「目录不存在」而非拒绝清单；按平台分支，Windows 侧改验盘符根与 `C:/Windows`。
+- `test/unit/acceptance-parallel.test.ts` 取消用例偶发（单跑绿、全量红）：固定 250ms 在慢平台可能早于子进程 spawn，使在途 check 被误记为 `skipped`；改为**等两个在途 check 真正启动后再取消**。
 
 ### 性能
 
@@ -509,7 +532,8 @@ Codex 桌面端改为 **GUI 驱动**：新增 `codex-gui` adapter，通过 MSIX
 
 ---
 
-[未发布]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.4.0...HEAD
+[未发布]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.4...v0.4.0
 [0.3.4]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.2...v0.3.3

package/README.en.md

@@ -37,6 +37,7 @@ Tianshu plays the role of the overall commander; this MCP server is the **schedu
 - **9 MCP tools**: `run_task / continue_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles`.
 - **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 CDP adapter; `driver: "spawn"` runs an external CLI child process.
 - **Scheduling discipline**: per-project serial queue + global concurrency cap (default 2, configurable).
@@ -190,6 +191,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.4.1.en.md](<docs/release-v0.4.1.en.md>) | v0.4.1 release notes (skill docs aligned with the v0.4.0 tool surface + contributor credits) |
 | [docs/zcode-issue-8-10-validation.en.md](<docs/zcode-issue-8-10-validation.en.md>) | ZCode #8/#9/#10 Windows hardware record (cold import, imported-project reuse, same-task recovery) |
 | [docs/release-v0.3.3.en.md](<docs/release-v0.3.3.en.md>) | v0.3.3 release notes (ZCode 3.11.2 adaptation + fail-closed acceptance engine) |
 | [docs/release-v0.3.2.en.md](docs/release-v0.3.2.en.md) | v0.3.2 release notes (Codex wait-user detection + cancel truly stops the GUI) |
@@ -226,9 +228,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` (ubuntu/windows/macos × Node 20/22/24 + pack-check, **10/10 green**, re-verified with the v0.3.4 tag) and `Release` (tag-triggered) both green
+  - GitHub Actions: `CI` (ubuntu/windows/macos × Node 20/22/24 + pack-check, **10/10 green**, re-verified with the v0.4.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.3.4`)
+  - npm package name `tianshu-mcp` published continuously since v0.1.1 (currently `0.4.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)
@@ -286,6 +288,10 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
   - **projectPath safety gate**: realpath canonicalization + home/system-root rejection + dirty-repo coexistence warning — see "Path safety gate"
   - **Fixes**: `get_profiles` missing user-defined profiles; zcode macOS `needsPermission` false positives; `normalizeProjectPath` symlink ambiguity; CDP polling now reconnects across renderer replacement/transient hangs
   - **Engineering**: all `execFileSync`/`spawnSync` calls async (no more event-loop freezes during Windows polling); bounded-parallel acceptance checks (`verifyConcurrency`); test suite 267s → 51s
+- **M18 — skill docs aligned with the v0.4.0 tool surface + contributor credits + v0.4.1** (2026-09-13) — **443 tests**
+  - `skills/tianshu-mcp/` now covers every v0.3.3 → v0.4.0 tool-surface change: the projectPath safety gate, the hard-failure error-code reference, the `setup_recovery` wait kind, the codex-cli headless path, `ready`/`research` status semantics, default-parallel-2 acceptance and the `requireChanges` gate; usage-examples adds the error-code table, the full meta field table, a project-level acceptance-config template and a `codex-cli` example
+  - Bilingual README gains a contributor credits section (avatar + name, in order of first participation)
+  - **No code behaviour changes**; no migration needed
 
 ## Agent support status
 
@@ -358,7 +364,7 @@ Behavior and limits:
 
 | Document | Content |
 |---|---|
-| [CHANGELOG.en.md](<CHANGELOG.en.md>) | Version history (v0.1.0 → v0.3.4) |
+| [CHANGELOG.en.md](<CHANGELOG.en.md>) | Version history (v0.1.0 → v0.4.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 |
@@ -368,6 +374,23 @@ Behavior and limits:
 - **Mirror repository**: <https://gitee.com/lan0811/tianshu-mcp> (Gitee)
 - **Feedback**: bugs / feature requests via the repo Issue templates; report security vulnerabilities privately per [SECURITY.en.md](SECURITY.en.md) — **do not** open a public issue.
 
+### Contributors
+
+Thanks to the community members below who contributed through Issues and pull requests (listed in order of first participation):
+
+<table>
+  <tr>
+    <td align="center"><a href="https://github.com/liuchsong"><img src="https://github.com/liuchsong.png" width="72" height="72" alt="liuchsong" /><br /><sub>liuchsong</sub></a></td>
+    <td align="center"><a href="https://github.com/a13612745638"><img src="https://github.com/a13612745638.png" width="72" height="72" alt="a13612745638" /><br /><sub>a13612745638</sub></a></td>
+    <td align="center"><a href="https://github.com/king195547"><img src="https://github.com/king195547.png" width="72" height="72" alt="king195547" /><br /><sub>king195547</sub></a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://github.com/zhaoxc857"><img src="https://github.com/zhaoxc857.png" width="72" height="72" alt="zhaoxc857" /><br /><sub>zhaoxc857</sub></a></td>
+    <td align="center"><a href="https://github.com/jian-in"><img src="https://github.com/jian-in.png" width="72" height="72" alt="jian-in" /><br /><sub>jian-in</sub></a></td>
+    <td align="center"><a href="https://github.com/huiliyi37"><img src="https://github.com/huiliyi37.png" width="72" height="72" alt="huiliyi37" /><br /><sub>huiliyi37</sub></a></td>
+  </tr>
+</table>
+
 > Chinese counterparts: see [README.md](README.md). The handoff document [HANDOFF.md](HANDOFF.md) is Chinese-only.
 
 ## License

package/README.md

@@ -37,6 +37,7 @@
 - **9 个 MCP 工具**：`run_task / continue_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles`。
 - **异步契约**：`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`。报告与日志格式不变（结果按声明顺序返回）。
 - **失败返修闭环**：自动返修（`autoFixRounds`）+ 手动 `rework_task`；验收失败时自动生成修复计划文件并回填给 agent；轮次用尽 → `needs_attention` 等天枢裁决。
 - **执行面**：`driver: "gui"` 由显式 adapter 驱动桌面 UI（Codex / TraeWork / ZCode 各自使用隔离的 CDP 流程）；`driver: "spawn"` 走外部 CLI 子进程。
 - **调度纪律**：每项目串行队列 + 全局并发上限（默认 2，可配）。
@@ -185,6 +186,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.4.1.md](<docs/release-v0.4.1.md>) | v0.4.1 发布说明（技能文档对齐 v0.4.0 工具面 + 贡献者名录） |
 | [docs/release-v0.3.4.md](<docs/release-v0.3.4.md>) | v0.3.4 发布说明（ZCode 项目/模型回读、初始化恢复与会话发送确认，issue #8/#9/#10） |
 | [docs/zcode-issue-8-10-validation.md](<docs/zcode-issue-8-10-validation.md>) | ZCode #8/#9/#10 Windows 真机验收记录（冷导入、已导入复用、同任务恢复） |
 | [docs/release-v0.3.3.md](<docs/release-v0.3.3.md>) | v0.3.3 发布说明（ZCode 3.11.2 适配 + 验收引擎 fail-closed） |
@@ -225,9 +227,9 @@ ZCode 提问、需要登录、旧实例无 CDP、系统权限不足，或自动
   - Zcode 无头接口（Z1）实测定论：ZCode 桌面无随包 headless CLI → unsupported
 - **R1–R8 / S1–S6 — 两轮验收整改** ✅（取消/超时/基线归因/参数语义/热加载/CI 加固）— **72 测试**
 - **工程 / CI** ✅
-  - GitHub Actions：`CI`（ubuntu/windows/macos × Node 20/22/24 + pack-check，**10/10 全绿**，随 v0.3.4 tag 再次校验）与 `Release`（tag 触发）均绿
+  - GitHub Actions：`CI`（ubuntu/windows/macos × Node 20/22/24 + pack-check，**10/10 全绿**，随 v0.4.1 tag 再次校验）与 `Release`（tag 触发）均绿
   - 技能自检安装已在本机真实 `~/.rivet/skills/tianshu-mcp` 验证生效且幂等
-  - npm 包名 `tianshu-mcp` 自 v0.1.1 起持续发布（当前 `0.3.4`）
+  - npm 包名 `tianshu-mcp` 自 v0.1.1 起持续发布（当前 `0.4.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）
@@ -285,6 +287,10 @@ ZCode 提问、需要登录、旧实例无 CDP、系统权限不足，或自动
   - **projectPath 安全闸门**：realpath 归一 + 主目录/系统根目录拒绝 + 脏仓共处警示——见「路径安全闸门」
   - **修复**：`get_profiles` 漏列用户自定义 profile；zcode macOS `needsPermission` 误报；`normalizeProjectPath` 符号链接歧义；CDP 轮询在 renderer 替换/瞬时无响应时重连
   - **工程**：`execFileSync`/`spawnSync` 全量异步化（消除 Windows 轮询期事件循环冻结）；验收命令有界并行（`verifyConcurrency`）；测试套件 267s → 51s
+- **M18 — 技能文档对齐 v0.4.0 工具面 + 贡献者名录 + v0.4.1**（2026-09-13）— **443 测试**
+  - `skills/tianshu-mcp/` 逐项补齐 v0.3.3 → v0.4.0 的工具面变化：projectPath 安全闸门、硬失败错误码速查表、`setup_recovery` 等待类型、codex-cli 无头路径、`ready`/`research` 状态语义、验收默认并行 2 与 `requireChanges` 门禁；usage-examples 新增错误码表、meta 字段全表、项目级验收配置模板与 `codex-cli` 示例
+  - 双语 README 新增贡献者名录（头像 + 名字，按首次参与顺序）
+  - 本版本**无代码行为变更**，升级无需迁移
 
 ## Agent 适配现状
 
@@ -358,7 +364,7 @@ run_task(projectPath=/path/to/项目, agentId=codex-cli, task="任务书", autoV
 | 文档 | 内容 |
 |---|---|
 | [HANDOFF.md](HANDOFF.md) | 项目交接文档：当前状态快照、架构导览、硬性红线、已知限制、接手建议 |
-| [CHANGELOG.md](<CHANGELOG.md>) | 版本变更日志（v0.1.0 → v0.3.4） |
+| [CHANGELOG.md](<CHANGELOG.md>) | 版本变更日志（v0.1.0 → v0.4.1） |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | 开发环境、工程规范、提交与发布流程、如何新增 agent |
 | [SECURITY.md](SECURITY.md) | 安全模型（凭证零管理/命令白名单/进程与桌面自动化边界）与私密报告渠道 |
 | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | 贡献者行为准则 |
@@ -368,6 +374,23 @@ run_task(projectPath=/path/to/项目, agentId=codex-cli, task="任务书", autoV
 - **镜像仓库**：<https://gitee.com/lan0811/tianshu-mcp>（Gitee）
 - **问题反馈**：Bug / 功能请求走仓库 Issue 模板；安全漏洞请按 [SECURITY.md](SECURITY.md) 私密报告，**不要**开公开 Issue。
 
+### 贡献者
+
+感谢以下通过 Issue 与 PR 为本项目做出贡献的社区成员（按首次参与顺序排列）：
+
+<table>
+  <tr>
+    <td align="center"><a href="https://github.com/liuchsong"><img src="https://github.com/liuchsong.png" width="72" height="72" alt="liuchsong" /><br /><sub>liuchsong</sub></a></td>
+    <td align="center"><a href="https://github.com/a13612745638"><img src="https://github.com/a13612745638.png" width="72" height="72" alt="a13612745638" /><br /><sub>a13612745638</sub></a></td>
+    <td align="center"><a href="https://github.com/king195547"><img src="https://github.com/king195547.png" width="72" height="72" alt="king195547" /><br /><sub>king195547</sub></a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://github.com/zhaoxc857"><img src="https://github.com/zhaoxc857.png" width="72" height="72" alt="zhaoxc857" /><br /><sub>zhaoxc857</sub></a></td>
+    <td align="center"><a href="https://github.com/jian-in"><img src="https://github.com/jian-in.png" width="72" height="72" alt="jian-in" /><br /><sub>jian-in</sub></a></td>
+    <td align="center"><a href="https://github.com/huiliyi37"><img src="https://github.com/huiliyi37.png" width="72" height="72" alt="huiliyi37" /><br /><sub>huiliyi37</sub></a></td>
+  </tr>
+</table>
+
 > 英文版对应文档见 [README.en.md](README.en.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.4.0";
+export const MCP_SERVER_VERSION = "0.4.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tianshu-mcp",
-  "version": "0.4.0",
+  "version": "0.4.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,30 +1,32 @@
 ---
 name: tianshu-mcp
-description: 让外部 AI-Agent（codex/zcode/traework）做项目开发并自动验收、失败返修的编排方法。当任务需要"叫一个 AI-Agent 去开发/改代码/补测试并验收，不行就返修"时先加载本技能：按它用 mcp__tianshu-mcp__ 的 9 个工具（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__ 的 9 个工具（run_task/continue_task/query_task/list_tasks/get_task_report/verify_task/rework_task/cancel_task/get_profiles）派活、暂停继续、轮询、查历史、读验收报告、驱动返修，并按硬失败错误码快速定位卡点。小改动或纯问答不需要。
 triggers: '开发|编码|写代码|改代码|实现功能|加功能|修复|重构|补测试|写测试|验收|返修|返工|重做|自动验收|自动返修|任务书|ai.?agent|子代理|外部.?agent|agent|codex|zcode|traework|claude|编排|项目开发|派活|派单'
 ---
 
 # tianshu-mcp 编排技能：叫外部 AI-Agent 开发并验收
 
-**首行强指令**：你正处理"派外部 AI-Agent 开发并验收、失败返修"类任务。动手前先通读本技能全文；任务书模板、三种 agent 派活示例、meta 块字段解读、返修提示语模板在同目录 `usage-examples.md`，需要时用读取文件工具查看，长方法论不必背。
+**首行强指令**：你正处理"派外部 AI-Agent 开发并验收、失败返修"类任务。动手前先通读本技能全文；任务书模板、三种 agent 派活示例、meta 块字段全表、错误码速查、返修提示语模板在同目录 `usage-examples.md`，需要时用读取文件工具查看，长方法论不必背。
 
 ## 何时不要用（边界）
 
 - 小改动 / 纯问答 / 只读代码分析：不需要本技能与 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 桌面端（MSIX 商店包，COM 激活 + CDP，复用 `~/.codex` 登录态）。Windows 已就绪，macOS 未验证前为 `research`。**model 必填**（面板可选模型名，如 `GPT-5.6 Sol`）；可选 `reasoningLevel`（低/中/高 或 low/medium/high）、`planDoc`（计划文档路径）、`designSystem`（设计系统目录路径）；**不支持 `mode`**。冷启动实测 60–90 秒，首轮等待偏慢属正常。
-- `zcode`：ZCode 桌面端（Electron CDP）。要求已安装、已登录；**model 必填**且格式为 `供应商/模型`（如 `DeepSeek/deepseek-flash`）；**不支持 `mode`**；发送前确认「完全访问」权限模式。macOS 真机证据补齐前 profile 为 `research`，用 `get_profiles` 读取当前机器实际探测结果。
+- `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。
+- `zcode`：ZCode 桌面端（Electron CDP）。要求已安装、已登录；**model 必填**且格式为 `供应商/模型`（如 `DeepSeek/deepseek-flash`）；**不支持 `mode`**；发送前确认「完全访问」权限模式。
 - `traework`：TraeWork（TRAE SOLO CN）桌面端。要求已登录、窗口保持可见。`model` 可选；`mode` 可选（`Work`/`Code`/`Design`；不传时从任务书文本识别「切换 X 模式」，识别不到保持 `Work`；实现顺序为「新建会话 → 切模式 → 在目标模式内绑定项目」）。
-- 不确定时问用户，或读项目 `projects.json` 的 `defaultAgentId`；用 `get_profiles` 看当前实际可用性（含可执行探测与未安装提示）。
+- `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`。
+- 不确定时问用户，或读项目 `projects.json` 的 `defaultAgentId`；用 `get_profiles` 看当前机器实际探测结果（含可执行探测、未安装提示与用户自定义 profile）。
 
 ## 2. 派活：run_task
 
 参数要点：
 
-- `projectPath`：**必须**是项目绝对路径（如 `D:\repo\my-app`）。
+- `projectPath`：**必须**是项目绝对路径（如 `D:\repo\my-app`），且提交即过安全闸门（见 §2.1）。
 - `task`：自然语言任务书。要写清 **目标 / 验收要点 / 约束 / 相关文件 / 上下文**，模板见 usage-examples.md。
 - `agentId`：默认取项目 default 或 codex；`model`/`mode`/`reasoningLevel` 等约束见 §1。
 - `context`：补充上下文/约束文本，会以【上下文与约束】拼进 agent 初始指令。task/context 中反引号包裹或路径形态的引用会在发送前校验（必须存在且在项目内），写错立即报错。
@@ -34,6 +36,16 @@ triggers: '开发|编码|写代码|改代码|实现功能|加功能|修复|重
 
 返回立刻给 `taskId`（异步契约）。**不要把任务书当同步调用等结果。**
 
+### 2.1 projectPath 安全闸门（v0.4.0 起）
+
+`run_task` / `verify_task` 提交时校验，不通过直接报错（属**基础设施拒绝**，不是 agent 失败，改路径重试即可）：
+
+- 必须是绝对路径且是**已存在**的目录；`realpath` 消除符号链接（macOS `/tmp` → `/private/tmp`），回执会明示解析来源。
+- 拒绝**用户主目录本身**，以及根级/系统目录（`/`、`/etc`、`/usr`、`/var`、`/tmp`、`/Users`、`C:\`、`C:\Windows`、`C:\Users`、`C:\Program Files`、`D:\` 等，含 macOS `/private/*` realpath 形态）。**只挡精确相等的根**，其子目录（`/tmp/xxx`、`D:\repo\app`）正常可用。
+- 目标是 git 仓库且有未提交变更时，回执追加共处警示（提示该仓库同时有人的改动，agent 的 diff 不会与它们混同，但基线不同）。
+
+不要在用户没给绝对路径时擅自猜路径；宁先问用户。
+
 ## 3. 轮询与查询
 
 - `query_task(taskId, tailLines?)` 间隔约 5–10 秒，看 agent 日志尾与状态（tailLines 缺省返回日志末 40 行）。
@@ -46,37 +58,67 @@ triggers: '开发|编码|写代码|改代码|实现功能|加功能|修复|重
 meta 块中 `needsUserKind` 给出等待类型、`pendingQuestion` 给出问题原文：
 
 - `agent_question`（zcode）：agent 提了问题 → 用 `continue_task(taskId, message=<答案>)`，message 会发到原会话。
-- `close_existing_instance` / `system_permission`（zcode）：需用户先处理（关闭旧实例 / 授系统权限）→ 用户处理完后调 `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 会复检环境后重新派发任务书。
 
-禁止新开会话冒充恢复。
+限制与纪律：
+
+- `continue_task` 只接受 `needs_user` 状态；其他状态会被明确拒绝。
+- codex 只支持 `login_required` / `user_confirmation` 两种等待类型，其余会拒绝。
+- zcode 恢复依赖原会话定位信息（`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 / 缩小任务），**不要反复空转重试**。
-- `cancelled` / `interrupted`：用户取消或超时/中断（meta 的 `abortSource` 区分 user/shutdown/timeout/internal）。`running` 卡死可用 `cancel_task(taskId, reason)` 终止：CLI agent 终止进程树；GUI agent（codex 等）尽力点击界面停止按钮并等待 GUI 空闲（有界超时），取消文案会如实标注 GUI 侧是否已停止——若标注"未确认停止"，Codex 窗口内的运行可能仍在继续，需人工检查，**不要在确认停止前重派同项目任务**（会新旧交叠；重派护栏也会直接拒绝派发）。
+- `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。
+- 结果文本末尾有 `---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 时按当前基线做健康检查。
 - 验收命令优先级：`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. 硬失败与错误码速查
+
+任务报告 `needs_attention` / `failed` 且属**硬失败**（`hardFailure`，不进验收与返修）时，读 meta 的 `agentEndReason` / `errorType` / `message` 直接定位，不要把硬失败当成"agent 没做好"反复重试。常见码：
+
+| `agentEndReason` | 含义 | 处置 |
+|---|---|---|
+| `setup_failed` | 找不到安装 / 实例未就绪 / 点不到「新对话」 | 让用户确认已安装并可手动打开；重试一次 |
+| `project_ambiguous` | 项目同名或路径重复，无法消歧 | 转 `needs_user`(setup_recovery)：请用户确认目标项目后 `continue_task` |
+| `project_mismatch` | 项目绑定或回读不一致，幂等重试仍失败 | 同上，请用户在 GUI 里确认/手工绑定 |
+| `project_create_failed` | 在 GUI 内新建项目失败 | 让用户手动把项目加进 agent，或换 `projectPath` |
+| `model_unavailable` | 面板里找不到指定模型（错误文本附可见候选） | 用 `get_profiles` / 面板实际模型名重派 |
+| `model_mismatch` | 模型回读与期望不符 | 同上；确认面板模型名与 `model` 参数完全一致 |
+| `permission_unknown` | 权限模式未确认（如 ZCode 未开「完全访问」） | 让用户在 agent 内切好权限模式 |
+| `cdp_disconnected` | CDP 连接断开且未能恢复 | 让用户关掉冲突实例；重试 |
+| `instance_busy` | 同项目已有未停止的运行（重派护栏） | 先 `cancel_task` 并**确认 GUI 已停**，或等其自行结束 |
+| `session_lost` | zcode 找不到原会话锚点 | 用新任务重派（不要指望恢复原会话） |
+| `input_mismatch` / `send_unknown` | 发送前回读不一致 / 发送结果无法确认（**不重复发送**，避免重发） | 人工看窗口状态，必要时 `continue_task` 或重派 |
+| `idle_timeout` | GUI 长时间静止且无完成标志（现场已保留） | 看窗口里 agent 是否真的卡住；必要时 `continue_task` 或取消 |
+| `task_timeout`（`errorType=timeout`） | 任务级超时 | 大任务调大 `taskTimeoutMs`；或拆小任务 |
+| `aborted`（`errorType=cancelled`/`interrupted`） | 被取消/中断 | 按 §5 处理 |
+
+## 8. 纪律
 
 - 写/执行类工具（run/cancel/rework/continue）需审批：不绕过、不替用户代点同意；query/list/report/verify/get_profiles 为只读，无需审批。
 - 不代替外部 agent 手改项目代码；不改用户 git 历史；不读取/转发任何 agent 密钥（登录态各 agent 自持）。
 - 验收命令来自白名单式配置、按 argv 分词执行，不做 shell 注入。
+- 本技能由 server 启动时幂等同步到 `~/.rivet/skills/tianshu-mcp/`（内容 hash 变化才覆盖，旧文件备份为 `.bak-<时间戳>`）；改技能以本仓库 `skills/` 为准。
 
 ## 快速上手清单
 
-1. `get_profiles` → 确认目标 agent 可用。
-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 处理。
+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。

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

@@ -1,6 +1,6 @@
 # tianshu-mcp 使用示例（子文件）
 
-正文过长方法论不背：任务书模板、三种 agent 派活示例、meta 块字段解读、验收与返修模板都在这里，按需用读取文件工具查看。
+正文过长方法论不背：任务书模板、四种 agent 派活示例、meta 块字段全表、错误码速查、验收与返修模板、needs_user/取消示例都在这里，按需用读取文件工具查看。
 
 ## 1. 任务书模板
 
@@ -40,7 +40,7 @@
 - 现有 run 命令会写 out/ 目录；dry-run 应跳过全部写操作
 ```
 
-## 2. 三种 agent 派活示例
+## 2. 四种 agent 派活示例
 
 ### 2.1 codex（默认；model 必填，支持 reasoningLevel / planDoc / designSystem）
 
@@ -57,6 +57,7 @@ run_task(projectPath=D:/repo/app, agentId=codex,
 - `planDoc` / `designSystem` 会被拼进初始开发指令「根据计划文档(<planDoc>)…和设计系统(<designSystem>)…」，路径必须存在且在项目内。
 - `reasoningLevel` 接受 低/中/高 或 low/medium/high；不传沿用面板当前等级。
 - 不支持 `mode` 参数，传了会直接报错。
+- 冷启动实测 60–90 秒，首轮等待偏慢属正常，不要因慢就取消。
 
 ### 2.2 zcode（model 必填且为「供应商/模型」）
 
@@ -74,7 +75,7 @@ continue_task(taskId=tsk_..., message=采用 PostgreSQL 方案)
 ```
 
 - `needsUserKind=agent_question`：message 作为答案发送到原会话。
-- `needsUserKind=close_existing_instance / login_required / system_permission`：先让用户处理（关旧实例 / 登录 / 授系统权限），message 仅作为用户已处理的确认。
+- `needsUserKind=close_existing_instance / login_required / system_permission / setup_recovery`：先让用户处理（关旧实例 / 登录 / 授系统权限 / 在 ZCode 里确认目标项目），message 仅作为用户已处理的确认。
 
 ### 2.3 traework（model 可选；唯一支持 mode）
 
@@ -89,7 +90,20 @@ run_task(projectPath=D:/repo/app, agentId=traework,
 - `mode` 缺省时从任务书文本识别「切换 Work/Code/Design 模式」，识别不到保持 `Work`。
 - TraeWork 窗口需保持可见；实现顺序为「新建会话 → 切模式 → 在目标模式内绑定项目」。
 
-## 3. meta 块解读示例
+### 2.4 codex-cli（用户自建 profile；无头路径，无 GUI）
+
+内置 `codex` 走桌面 GUI 驱动。不想依赖 GUI 自动化（或需要可复现的 CI 式无头执行）时，在数据目录 `~/.tianshu-mcp/agent-profiles.json` 加一个 `driver=spawn` 的 profile，示例见 README「macOS 无头路径：codex-cli」。之后按普通 agent 派活：
+
+```text
+run_task(projectPath=/path/to/项目, agentId=codex-cli,
+  task=按计划实现功能, autoVerify=true, autoFixRounds=2)
+```
+
+- `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。
+
+## 3. meta 块解读（字段全表）
 
 `run_task` / `query_task` 等结果文本末尾的结构化块：
 
@@ -123,9 +137,11 @@ run_task(projectPath=D:/repo/app, agentId=traework,
 | `status` | queued/running/verify_start/fixing/needs_user/succeeded/failed/needs_attention/cancelled/interrupted |
 | `message` | 状态摘要/失败原因，最先读 |
 | `errorType` | 失败归类：timeout/spawn/agent_failed/verify_failed/cancelled/interrupted/agent_unresolved/internal |
-| `needsUserKind` | needs_user 时的等待类型：agent_question/close_existing_instance/login_required/system_permission/user_confirmation（codex 等待用户确认界面） |
-| `pendingQuestion` | needs_user 时 agent 提出的问题原文 |
-| `round` / `roundsUsed` | 已进行的 agent 轮次 |
+| `agentEndReason` | agent 侧结束原因（硬失败定位主用，取值见 §4） |
+| `lastRunSignal` | 最近一次运行观察到的信号（GUI 完成标志/空闲判定依据） |
+| `needsUserKind` | needs_user 时的等待类型：agent_question/close_existing_instance/login_required/system_permission/setup_recovery/user_confirmation |
+| `pendingQuestion` | needs_user 时 agent 提出的问题原文（或需用户处理事项的说明） |
+| `round` | 已进行的 agent 轮次（=roundsUsed） |
 | `changedFiles` | 相对 git 基线的变更清单（含未跟踪新增） |
 | `diffstat` | 增删行摘要（`+A -D`） |
 | `reportFiles` | 最近一轮验收报告 md/json 绝对路径 |
@@ -133,12 +149,41 @@ run_task(projectPath=D:/repo/app, agentId=traework,
 | `reportRound` | 最近一次验收的报告轮次（0-based，区别于 agent 轮次） |
 | `verificationSource` | 最近一次验收来源：auto（run_task 自动）/ manual（verify_task 手动） |
 | `latestVerificationVerdict` | 手动验收结论（不改变任务终态时单独记录） |
+| `checks` | 本轮检查项摘要（name/passed/durationMs） |
 | `abortSource` | 中断来源：user/shutdown/timeout/internal |
+| `cancelReason` / `cancelRequestedAt` | 取消原因与发起时间 |
+| `keptInstance` | 是否因任务未真正完成而保留了 GUI 实例 |
+| `zcodeSessionId` / `boundProjectPath` | 会话与项目绑定回执（zcode/codex） |
+| `modelProvider` / `permissionMode` | 实际生效的供应商标识与权限模式（zcode） |
+| `progressSummary` | 轮询期进度摘要 |
 | `model` / `mode` / `reasoningLevel` | 本次派单的模型 / 面板模式 / 思考等级（按 agent 生效） |
 
-规则：`ok=true` 且 status=succeeded → 交付达成；否则读 `message` 与 `reportFiles.md` 全文定位。
+规则：`ok=true` 且 status=succeeded → 交付达成；否则先读 `message`，再按 `errorType`/`agentEndReason` 查 §4，最后读 `reportFiles.md` 全文定位。
 
-## 4. 验收：verify_task 示例
+## 4. 硬失败错误码速查
+
+**硬失败**（`hardFailure`）表示基础设施/环境/前置条件问题，**不进验收、不进自动返修**——把它当"agent 没做好"反复重试是空转。读 `agentEndReason` 定位：
+
+| `agentEndReason` | 含义 | 处置 |
+|---|---|---|
+| `setup_failed` | 找不到安装 / 实例未就绪 / 点不到「新对话」 | 让用户确认已安装并可手动打开；重试一次 |
+| `project_ambiguous` | 项目同名或路径重复，无法消歧 | 已转 `needs_user`(setup_recovery)，请用户确认目标项目后 `continue_task` |
+| `project_mismatch` | 项目绑定或回读不一致，幂等重试仍失败 | 同上，请用户在 GUI 里确认或手工绑定 |
+| `project_create_failed` | 在 GUI 内新建项目失败 | 让用户手动把项目加进 agent，或换 `projectPath` |
+| `model_unavailable` | 面板里找不到指定模型（错误文本附可见候选） | 用 `get_profiles` / 面板实际模型名重派 |
+| `model_mismatch` | 模型回读与期望不符 | 同上；确认面板模型名与 `model` 参数完全一致 |
+| `permission_unknown` | 权限模式未确认（如 ZCode 未开「完全访问」） | 让用户在 agent 内切好权限模式 |
+| `cdp_disconnected` | CDP 连接断开且未能恢复 | 让用户关掉冲突实例；重试 |
+| `instance_busy` | 同项目已有未停止的运行（重派护栏） | 先 `cancel_task` 并**确认 GUI 已停**，或等其自行结束 |
+| `session_lost` | zcode 找不到原会话锚点 | 用新任务重派，不要指望恢复原会话 |
+| `input_mismatch` / `send_unknown` | 发送前回读不一致 / 发送结果无法确认（**不重复发送**） | 人工看窗口状态，必要时 `continue_task` 或重派 |
+| `idle_timeout` | GUI 长时间静止且无完成标志（现场已保留） | 看窗口里 agent 是否真卡住；必要时 `continue_task` 或取消 |
+| `task_timeout`（`errorType=timeout`） | 任务级超时 | 大任务调大 `taskTimeoutMs`；或拆小任务 |
+| `aborted` | 被取消/中断（`abortSource` 区分来源） | 按 SKILL §5 处理 |
+
+上表未覆盖的：先读 `message` 全文（多数带可执行建议），再读 `reportFiles.md`。
+
+## 5. 验收：verify_task 示例
 
 只读、不改源码、无需审批。三种典型用法：
 
@@ -159,7 +204,33 @@ verify_task(projectPath=D:/repo/app, baselineRef=HEAD~1,
 - `extraChecks` 单条支持 `name`/`cmd`（argv 数组或字符串）/`timeoutMs`/`optional`（optional:true 失败只记 warning）。
 - 验收命令优先级：extraChecks > 项目 `.tianshu-mcp/acceptance.json` > projects.json 管理员补录 > 按技术栈推导的默认集（详见 docs/acceptance-config.md）。
 
-## 5. 查历史：list_tasks 示例
+### 5.1 项目级验收配置模板（写进目标项目仓库）
+
+`<目标项目>/.tianshu-mcp/acceptance.json`：
+
+```jsonc
+{
+  // 默认 true：git 项目相对动工前基线零变更即判失败（防"什么都没做却报成功"）
+  "requireChanges": true,
+  // 命令检查并行度 1-4，缺省继承 server 的 verifyConcurrency（默认 2）
+  // ⚠ checks 之间有顺序依赖（读 build 产物 / 带 --fix / 共享缓存）时必须设 1
+  "verifyConcurrency": 1,
+  "checks": [
+    { "name": "typecheck", "cmd": ["npm", "run", "typecheck"], "timeoutMs": 120000 },
+    { "name": "lint",      "cmd": ["npm", "run", "lint"] },
+    { "name": "test",      "cmd": ["npm", "test"] },
+    // optional:true 时失败只记 warning，不影响本轮 verdict
+    { "name": "e2e", "cmd": ["npm", "run", "test:e2e"], "optional": true }
+  ]
+}
+```
+
+- `cmd` 推荐 argv 数组；字符串会被安全分词执行（`shell:false`，不拼接 shell 字符串）。
+- **纯只读/纯排查类任务**必须设 `"requireChanges": false`，否则零变更必然被判失败。
+- 非 git 项目跳过零变更门禁并在报告注明。
+- 默认并行 2 是有意为之（提速）；不确定就用 `verifyConcurrency: 1` 换确定性。
+
+## 6. 查历史：list_tasks 示例
 
 ```text
 # 某项目最近失败/需关注的任务
@@ -171,7 +242,7 @@ list_tasks()
 
 返回含每条任务的 taskId/status/agentId/时间摘要，可用于接续 `get_task_report` / `rework_task`。
 
-## 6. 返修提示语模板
+## 7. 返修提示语模板
 
 给 `rework_task(taskId, feedback)` 的 `feedback`，讲究**针对性**，避免空转：
 
@@ -195,11 +266,11 @@ list_tasks()
 parameter of type 'number' (src/run.ts:42)。请只修这一处类型问题并重跑 npm run build 确认。
 ```
 
-补充：自动返修（autoFixRounds）路径下，server 会先把失败证据写成修复计划文档（codex 写到项目 `.zcode/plans/`），并在下一轮指令中引用该文档；手动 `rework_task` 的 feedback 则按上面的针对性模板书写。
+补充：自动返修（autoFixRounds）路径下，server 会先把失败证据写成修复计划文档（写到项目 `.zcode/plans/`），并在下一轮指令中引用该文档；手动 `rework_task` 的 feedback 则按上面的针对性模板书写。
 
-## 7. needs_user 恢复与取消示例（v0.3.2 起）
+## 8. needs_user 恢复与取消示例
 
-### 7.1 codex 停在等待用户确认（user_confirmation）
+### 8.1 codex 停在等待用户确认（user_confirmation）
 
 轮询时看到任务转为 `needs_user`、`needsUserKind=user_confirmation`（Codex 停止按钮持续可见且对话长时间未变化，如方案确认卡/订阅确认页）：
 
@@ -211,34 +282,47 @@ parameter of type 'number' (src/run.ts:42)。请只修这一处类型问题并
 
 注意：若用户尚未处理就调 continue_task，任务会再次转 `needs_user`（如实反映 GUI 状态），稍后再试即可。
 
-### 7.2 codex 需要登录（login_required）
+### 8.2 codex 需要登录（login_required）
 
 ```text
 在 Codex 窗口完成登录 → continue_task(taskId, message="已登录")
 MCP 复检环境后重新派发任务书（新会话 + 项目绑定 + 完整初始指令）。
 ```
 
-### 7.3 取消 GUI agent 任务（cancel_task）
+### 8.3 zcode 初始化恢复未完成（setup_recovery）
+
+`needsUserKind=setup_recovery` 表示 ZCode 的项目设置阶段自动恢复（有限重试 + 预算）用尽——常见于项目同名歧义、绑定回读不一致、原生面板操作超时：
+
+```text
+1) 提示用户：请在 ZCode 中确认目标项目（必要时手工完成绑定/关掉多余面板）。
+2) continue_task(taskId, message="已在 ZCode 中确认目标项目")
+3) 注意 message 只是"已处理"的确认，不会作为问题发送；原任务上下文被保留。
+```
+
+### 8.4 取消 GUI agent 任务（cancel_task）
 
 ```text
 cancel_task(taskId, reason="用户要求停止")
 → 返回 meta.message：
   "已取消：…；GUI 内运行已停止。"                      ← 已确认停止，可安全重派
-  "已取消：…；GUI 内运行未确认停止，Codex 窗口中的任务可能仍在继续。" ← 需人工检查
+  "已取消：…；GUI 内运行未确认停止，…窗口中的任务可能仍在继续。" ← 需人工检查
+  "已取消（等待用户处理时）：…；GUI 内可能仍有等待中的会话，请人工检查。"
   "已请求取消，但任务尚未在本调用内落终态…"            ← 稍后 query_task 复核
 ```
 
 GUI agent 取消语义：尽力点击界面停止按钮并等待 GUI 空闲（有界超时）；**未确认停止前不要重派同项目任务**——重派护栏会以 `instance_busy` 拒绝派发（防止新旧 turn 交叠），宁可等人工确认。
 
-### 7.4 agent-profiles.json 相关配置（可选）
+### 8.5 agent-profiles.json 相关配置（可选）
 
 ```json
 {
-  "codex": {
-    "gui": {
-      "stallTimeoutMs": 300000,
-      "cancelWaitMs": 15000,
-      "selectors": { "userGate": "[class*=\"embedded-checkout\"]" }
+  "profiles": {
+    "codex": {
+      "gui": {
+        "stallTimeoutMs": 300000,
+        "cancelWaitMs": 15000,
+        "selectors": { "userGate": "[class*=\"embedded-checkout\"]" }
+      }
     }
   }
 }
@@ -247,8 +331,9 @@ GUI agent 取消语义：尽力点击界面停止按钮并等待 GUI 空闲（
 - `stallTimeoutMs`：停止按钮持续可见 + 对话无变化持续此时长 → 判定等待用户（默认 300000=5 分钟）。长命令型任务（大依赖安装/构建）建议调大。
 - `cancelWaitMs`：取消时点击停止按钮后等待 GUI 空闲的上限（默认 15000=15 秒）。
 - `selectors.userGate`：等待用户界面的检测选择器（如结账页 `embedded-checkout`、确认卡），配置后命中即快速转 `needs_user`；默认未配置=禁用，配置前请真机核对。
+- profile 的整键覆盖语义：数据目录 `agent-profiles.json` 里同名键会**覆盖**内置 profile 的对应字段；用户自定义 profile（如 `codex-cli`）会出现在 `get_profiles` 中。
 
-## 8. 汇报模板
+## 9. 汇报模板
 
 `get_task_report` 拿全文后向用户汇报建议包含：
 
@@ -259,3 +344,5 @@ GUI agent 取消语义：尽力点击界面停止按钮并等待 GUI 空闲（
 - 代码分析：无可疑标记；注意 README 存在超大单文件改动（告警）
 - 验收报告：<report.md 路径>
 ```
+
+失败/需关注时的汇报建议包含：`errorType`/`agentEndReason` 与 `message` 原文、失败的 check 名与输出尾部、变更文件与 diffstat、下一步建议（针对性返修 / 人工介入 / 换 agent / 缩小任务）。