tianshu-mcp 0.3.0 → 0.3.1

package/CHANGELOG.en.md

@@ -19,6 +19,43 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.3.1] — 2026-09-12
+
+Post-v0.3.0 housekeeping for docs and release automation: **no source-level behavior changes**.
+The focus is a full rewrite of the self-installed skill docs plus GitHub/Gitee release-body
+composition and link fixes.
+
+### Changed
+
+- **Skill docs (`skills/tianshu-mcp/`) fully rewritten to match the actual v0.3.0 tool surface**:
+  - Corrected the `codex` description from "headless CLI" to the ChatGPT desktop GUI adapter
+    (MSIX + COM activation + CDP); documents the required `model`, optional `reasoningLevel` /
+    `planDoc` / `designSystem`, and that `mode` is not supported;
+  - Documented the `run_task` `context` parameter and the send-time validation of path references
+    inside task/context; corrected the `autoFixRounds` default precedence
+    (call argument > codex 5 / zcode 2 > server default 0);
+  - Added usage for `list_tasks`, `query_task(tailLines)`, `get_task_report(round)` and
+    `verify_task` (`extraChecks` / `checksMode` / `baselineRef`) plus the four-level acceptance
+    command precedence;
+  - Documented the four `needs_user` kinds and meta fields such as `needsUserKind` /
+    `pendingQuestion` / `errorType` / `reportRound` / `verificationSource`;
+  - Added `continue_task` to the approval list; replaced emoji status markers with plain text
+    (PASS / warning) in the usage examples.
+- **Release automation fixes (exposed by the v0.3.0 tag)**:
+  - The release body is now composed bilingually from `docs/release-v<version>.md` and `.en.md`,
+    with in-document relative links rewritten to tag-absolute links; a missing doc fails the
+    workflow loudly instead of producing a shell-only body;
+  - `Full Changelog` resolves the previous tag via `git describe` into a `compare/<prev>...<tag>`
+    link instead of degrading to a commits link;
+  - The body's `CI` link resolves the CI run for the same SHA instead of pointing at the Release run;
+  - Gitee releases are automated in `release.yml`: `scripts/gitee-release.mjs` idempotently
+    creates/updates the mirrored release (requires the `GITEE_TOKEN` secret; skipped loudly when unset).
+- `.gitignore` now ignores npm pack artifacts and local temporary verification directories.
+- Added the missing `[0.1.10]` / `[0.2.0]` / `[0.3.0]` / `[0.3.1]` compare links at the bottom of
+  this file and its Chinese counterpart.
+
+---
+
 ## [0.3.0] — 2026-09-12
 
 The Codex desktop app now runs through a **GUI driver**: a new `codex-gui` adapter uses MSIX COM activation
@@ -401,7 +438,11 @@ project → pick model and reasoning level → send instructions → run detecti
 
 ---
 
-[Unreleased]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.9...HEAD
+[Unreleased]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.10...v0.2.0
+[0.1.10]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.9...v0.1.10
 [0.1.9]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.6...v0.1.7

package/CHANGELOG.md

@@ -18,6 +18,36 @@
 
 ---
 
+## [0.3.1] — 2026-09-12
+
+v0.3.0 发布后的文档与发布自动化收口：**无源码行为变更**，重点是技能自检安装文档全面重写、
+GitHub/Gitee 发行版正文合成与链接修复。
+
+### 变更
+
+- **技能文档（`skills/tianshu-mcp/`）全面重写并对齐 v0.3.0 实际工具面**：
+  - 修正 `codex` 描述：由「无头 CLI」更正为 ChatGPT 桌面端 GUI adapter（MSIX + COM 激活 + CDP），
+    标注 `model` 必填、`reasoningLevel` / `planDoc` / `designSystem` 用法、不支持 `mode`；
+  - 补齐 `run_task` 的 `context` 参数语义与 task/context 路径引用发送前校验说明；
+    修正 `autoFixRounds` 默认值优先级（调用参数 > codex 5 / zcode 2 > server 默认 0）；
+  - 补齐 `list_tasks`、`query_task(tailLines)`、`get_task_report(round)` 与
+    `verify_task`（`extraChecks` / `checksMode` / `baselineRef`）的用法与验收命令四级优先级；
+  - 补充 `needs_user` 四种等待类型与 meta 块 `needsUserKind` / `pendingQuestion` / `errorType` /
+    `reportRound` / `verificationSource` 等字段解读；
+  - 审批清单补上 `continue_task`；使用示例中的 emoji 状态标记改为文字（PASS / 告警）。
+- **发布自动化修复（v0.3.0 tag 实测暴露）**：
+  - Release 正文改为由 `docs/release-v<版本>.md` 与 `.en.md` 双语合成，文档内相对链接改写为
+    该 tag 的绝对链接，缺文档时工作流明确报错（不再产出空壳正文）；
+  - `Full Changelog` 经 `git describe` 解析上一 tag，生成 `compare/<prev>...<tag>` 比较链接，
+    不再退化为 commits 链接；
+  - 正文 `CI` 链接解析同 SHA 的 CI 运行，避免误指 Release 自身运行；
+  - Gitee 发行版纳入 `release.yml` 自动化：`scripts/gitee-release.mjs` 幂等创建/更新
+    （需仓库 Secret `GITEE_TOKEN`，未配置时明确提示并跳过）。
+- `.gitignore` 忽略 npm pack 产物与本地临时校验目录。
+- 补齐本文件与英文版底部缺失的 `[0.1.10]` / `[0.2.0]` / `[0.3.0]` / `[0.3.1]` 比较链接。
+
+---
+
 ## [0.3.0] — 2026-09-12
 
 Codex 桌面端改为 **GUI 驱动**：新增 `codex-gui` adapter，通过 MSIX COM 激活 + CDP 接管，
@@ -356,7 +386,11 @@ Codex 桌面端改为 **GUI 驱动**：新增 `codex-gui` adapter，通过 MSIX
 
 ---
 
-[未发布]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.9...HEAD
+[未发布]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.10...v0.2.0
+[0.1.10]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.9...v0.1.10
 [0.1.9]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/lanlan0811/tianshu-mcp/compare/v0.1.6...v0.1.7

package/README.en.md

@@ -182,6 +182,7 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
 | [docs/zcode-windows-smoke.en.md](docs/zcode-windows-smoke.en.md) | ZCode Windows hardware record for development, same-session repair, and question continuation |
 | [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.1.en.md](docs/release-v0.3.1.en.md) | v0.3.1 release notes (skill docs rewrite + release automation fixes) |
 | [docs/release-v0.3.0.en.md](docs/release-v0.3.0.en.md) | v0.3.0 release notes (Codex desktop GUI adapter, incl. BREAKING) |
 | [docs/release-v0.2.0.en.md](docs/release-v0.2.0.en.md) | v0.2.0 release notes (unified ZCode GUI loop) |
 | [docs/acceptance-config.en.md](docs/acceptance-config.en.md) | Project-level `.tianshu-mcp/acceptance.json` acceptance config spec |
@@ -254,6 +255,9 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
   - Hardware-verified: full loop for a registered project, full loop for an unregistered project after automatic registration, and the verify-fail → generated plan → repair-pass loop
   - Real business acceptance: drove Codex to build a "Fruit Ninja" mini-game, passed acceptance, verified playable in a headless browser; [acceptance record](docs/codex-windows-smoke.en.md)
   - macOS unverified; built-in status `research`
+- **M13 — Skill docs alignment + release automation fixes + v0.3.1** (2026-09-12, see [release-v0.3.1.en.md](docs/release-v0.3.1.en.md))
+  - Self-installed skill docs (SKILL.md / usage-examples.md) rewritten item by item against the v0.3.0 tool surface (codex GUI params, needs_user handling, verify/list usage)
+  - Bilingual release bodies, Full Changelog & CI link fixes, and automated Gitee releases
 
 ## Agent support status
 
@@ -276,7 +280,7 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
 
 | Document | Content |
 |---|---|
-| [CHANGELOG.en.md](CHANGELOG.en.md) | Version history (v0.1.0 → v0.3.0) |
+| [CHANGELOG.en.md](CHANGELOG.en.md) | Version history (v0.1.0 → v0.3.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

@@ -180,6 +180,7 @@ ZCode 提问或需要用户处理登录、旧实例、系统权限时进入 `nee
 | [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.3.1.md](docs/release-v0.3.1.md) | v0.3.1 发布说明（技能文档重写 + 发布自动化修复） |
 | [docs/release-v0.3.0.md](docs/release-v0.3.0.md) | v0.3.0 发布说明（Codex 桌面端 GUI 适配，含 BREAKING） |
 | [docs/release-v0.2.0.md](docs/release-v0.2.0.md) | v0.2.0 发布说明（ZCode GUI 统一闭环） |
 | [docs/acceptance-config.md](docs/acceptance-config.md) | 项目级 `.tianshu-mcp/acceptance.json` 验收配置规范 |
@@ -254,6 +255,9 @@ ZCode 提问或需要用户处理登录、旧实例、系统权限时进入 `nee
   - 真机通过：已登记项目全链路、未登记项目自动登记全链路、验收失败→自动生成计划→返修通过闭环
   - 真实业务验收：驱动 Codex 开发「切水果小游戏」并通过验收，无头浏览器实测可玩；[验收记录](docs/codex-windows-smoke.md)
   - macOS 未验证，内置状态 `research`
+- **M13 — 技能文档对齐 + 发布自动化修复 + v0.3.1**（2026-09-12，见 [release-v0.3.1.md](docs/release-v0.3.1.md)）
+  - 技能自检安装文档（SKILL.md / usage-examples.md）对照 v0.3.0 工具面逐项重写（codex GUI 参数、needs_user 处理、verify/list 用法）
+  - Release 正文双语合成、Full Changelog 与 CI 链接修复、Gitee 发行版纳入自动化
 
 ## Agent 适配现状
 
@@ -277,7 +281,7 @@ ZCode 提问或需要用户处理登录、旧实例、系统权限时进入 `nee
 | 文档 | 内容 |
 |---|---|
 | [HANDOFF.md](HANDOFF.md) | 项目交接文档：当前状态快照、架构导览、硬性红线、已知限制、接手建议 |
-| [CHANGELOG.md](CHANGELOG.md) | 版本变更日志（v0.1.0 → v0.3.0） |
+| [CHANGELOG.md](CHANGELOG.md) | 版本变更日志（v0.1.0 → v0.3.1） |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | 开发环境、工程规范、提交与发布流程、如何新增 agent |
 | [SECURITY.md](SECURITY.md) | 安全模型（凭证零管理/命令白名单/进程与桌面自动化边界）与私密报告渠道 |
 | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | 贡献者行为准则 |

package/dist/version.generated.d.ts

@@ -3,4 +3,4 @@
  * 若直接源码运行（未注入），回退读 package.json；再失败给占位。
  * 本文件由 scripts/sync-version.mjs 在每次 build 前重新生成。
  */
-export declare const MCP_SERVER_VERSION = "0.3.0";
+export declare const MCP_SERVER_VERSION = "0.3.1";

package/dist/version.generated.js

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

package/package.json

@@ -1,83 +1,85 @@
-{
-  "name": "tianshu-mcp",
-  "version": "0.3.0",
-  "description": "天枢 × AI-Agent 编排 MCP server —— 驱动 Codex CLI、TraeWork GUI 与 ZCode GUI 完成项目开发、验收、失败返修与再验收闭环。",
-  "type": "module",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lanlan0811/tianshu-mcp.git"
-  },
-  "homepage": "https://github.com/lanlan0811/tianshu-mcp#readme",
-  "bugs": {
-    "url": "https://github.com/lanlan0811/tianshu-mcp/issues"
-  },
-  "bin": {
-    "tianshu-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "skills",
-    "assets",
-    "scripts/probe-zcode.mjs",
-    "scripts/probe-codex.mjs",
-    "scripts/smoke-zcode.mjs",
-    "scripts/prepare-zcode-fixture.mjs",
-    "README.md",
-    "README.en.md",
-    "CHANGELOG.md",
-    "CHANGELOG.en.md",
-    "LICENSE"
-  ],
-  "main": "dist/index.js",
-  "exports": {
-    ".": "./dist/index.js"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "sync-version": "node scripts/sync-version.mjs",
-    "build": "npm run sync-version && tsc -p tsconfig.build.json",
-    "dev": "tsx src/index.ts",
-    "start": "node dist/index.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "lint": "eslint . --max-warnings 0",
-    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
-    "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",
-    "fixture:zcode": "node scripts/prepare-zcode-fixture.mjs",
-    "pack:check": "npm pack --dry-run"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.15.0",
-    "cross-spawn": "^7.0.6",
-    "zod": "^3.24.1"
-  },
-  "devDependencies": {
-    "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^22.10.2",
-    "@typescript-eslint/eslint-plugin": "^8.18.1",
-    "@typescript-eslint/parser": "^8.18.1",
-    "eslint": "^8.57.1",
-    "eslint-config-prettier": "^9.1.0",
-    "prettier": "^3.4.2",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.2",
-    "vite": "^6.4.3",
-    "vitest": "^4.1.11"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "ai-agent",
-    "orchestration",
-    "codex",
-    "zcode",
-    "traework",
-    "tianshu"
-  ]
-}
+{
+  "name": "tianshu-mcp",
+  "version": "0.3.1",
+  "description": "天枢 × AI-Agent 编排 MCP server —— 驱动 Codex CLI、TraeWork GUI 与 ZCode GUI 完成项目开发、验收、失败返修与再验收闭环。",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lanlan0811/tianshu-mcp.git"
+  },
+  "homepage": "https://github.com/lanlan0811/tianshu-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/lanlan0811/tianshu-mcp/issues"
+  },
+  "bin": {
+    "tianshu-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "assets",
+    "scripts/probe-zcode.mjs",
+    "scripts/probe-codex.mjs",
+    "scripts/smoke-zcode.mjs",
+    "scripts/prepare-zcode-fixture.mjs",
+    "README.md",
+    "README.en.md",
+    "CHANGELOG.md",
+    "CHANGELOG.en.md",
+    "LICENSE",
+    "scripts/gitee-release.mjs",
+    "scripts/release-body.mjs"
+  ],
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "sync-version": "node scripts/sync-version.mjs",
+    "build": "npm run sync-version && tsc -p tsconfig.build.json",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint . --max-warnings 0",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "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",
+    "fixture:zcode": "node scripts/prepare-zcode-fixture.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.15.0",
+    "cross-spawn": "^7.0.6",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^22.10.2",
+    "@typescript-eslint/eslint-plugin": "^8.18.1",
+    "@typescript-eslint/parser": "^8.18.1",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.0",
+    "prettier": "^3.4.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vite": "^6.4.3",
+    "vitest": "^4.1.11"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "orchestration",
+    "codex",
+    "zcode",
+    "traework",
+    "tianshu"
+  ]
+}

package/scripts/gitee-release.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * 创建/更新 Gitee 发行版（Release）——镜像仓库补齐。
+ *
+ * 背景：GitHub Actions 的 release 工作流只作用于 GitHub；Gitee 作为镜像仓库需要单独创建发行版，
+ * 否则会出现「只有 tag、没有发行版」的不一致。本脚本用 Gitee OpenAPI 幂等补齐：
+ * 已存在同 tag 发行版则更新正文，不存在则创建。
+ *
+ * 正文由 scripts/release-body.mjs 合成（双语发布说明 + 绝对链接 + npm/Changelog），
+ * 链接指向 gitee.com，确保在 Gitee 页面可点。
+ *
+ * 用法：
+ *   GITEE_TOKEN=<私人令牌> node scripts/gitee-release.mjs <version> [previousVersion]
+ *   # 例：GITEE_TOKEN=xxx node scripts/gitee-release.mjs 0.3.0 0.2.0
+ *
+ * 环境变量：
+ *   GITEE_TOKEN   必填（也可用 GITEE_ACCESS_TOKEN；两者都无则跳过并以 0 退出）
+ *   GITEE_OWNER   可选，默认 Lan0811
+ *   GITEE_REPO    可选，默认 tianshu-mcp
+ *   GITEE_BRANCH  可选，默认 master（创建发行版时的目标分支）
+ *
+ * 令牌获取：Gitee → 设置 → 私人令牌 → 生成新令牌（至少勾选 projects 权限）。
+ */
+import { composeReleaseBody, repoRoot } from "./release-body.mjs";
+
+const token = (process.env.GITEE_TOKEN || process.env.GITEE_ACCESS_TOKEN || "").trim();
+const owner = (process.env.GITEE_OWNER || "Lan0811").trim();
+const repo = (process.env.GITEE_REPO || "tianshu-mcp").trim();
+const branch = (process.env.GITEE_BRANCH || "master").trim();
+void repoRoot;
+
+const version = (process.argv[2] || "").replace(/^v/, "").trim();
+const previousVersion = (process.argv[3] || "").replace(/^v/, "").trim() || undefined;
+if (!/^\d+\.\d+\.\d+/.test(version)) {
+  console.error("用法: node scripts/gitee-release.mjs <version> [previousVersion]（version 形如 0.3.0）");
+  process.exit(2);
+}
+const tag = `v${version}`;
+
+if (!token) {
+  console.log(
+    "未设置 GITEE_TOKEN / GITEE_ACCESS_TOKEN，跳过 Gitee 发行版（设置令牌后重跑本脚本或由 CI 自动补齐）。",
+  );
+  process.exit(0);
+}
+
+// 合成正文：双语 + 指向 gitee.com 的绝对链接
+let body;
+try {
+  body = composeReleaseBody({
+    version,
+    host: "gitee",
+    ownerRepo: `${owner}/${repo}`,
+    npmPackage: "tianshu-mcp",
+    previousVersion,
+  });
+} catch (e) {
+  console.error(`合成发布正文失败：${e.message || e}`);
+  process.exit(1);
+}
+console.log(`发布正文已合成（${body.length} 字符，双语 + gitee 绝对链接）`);
+
+const api = `https://gitee.com/api/v5/repos/${owner}/${repo}`;
+const q = new URLSearchParams({ access_token: token }).toString();
+const name = `tianshu-mcp ${tag}`;
+
+async function getExisting() {
+  const r = await fetch(`${api}/releases/tags/${tag}?${q}`);
+  if (r.status === 404) return null;
+  if (!r.ok) throw new Error(`查询发行版失败 HTTP ${r.status}: ${(await r.text()).slice(0, 200)}`);
+  return r.json();
+}
+
+async function create() {
+  const r = await fetch(`${api}/releases`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ access_token: token, tag_name: tag, name, body, target_commitish: branch }),
+  });
+  const text = await r.text();
+  if (!r.ok) throw new Error(`创建发行版失败 HTTP ${r.status}: ${text.slice(0, 300)}`);
+  return JSON.parse(text);
+}
+
+async function update(id) {
+  const r = await fetch(`${api}/releases/${id}`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ access_token: token, tag_name: tag, name, body }),
+  });
+  const text = await r.text();
+  if (!r.ok) throw new Error(`更新发行版失败 HTTP ${r.status}: ${text.slice(0, 300)}`);
+  return JSON.parse(text);
+}
+
+try {
+  const existing = await getExisting();
+  if (existing) {
+    console.log(`已存在 ${tag} 发行版（id=${existing.id}），更新正文…`);
+    const updated = await update(existing.id);
+    console.log(`更新成功: ${updated.name} | https://gitee.com/${owner}/${repo}/releases/${tag}`);
+  } else {
+    console.log(`未找到 ${tag} 发行版，创建中…`);
+    const created = await create();
+    console.log(`创建成功: ${created.name} | https://gitee.com/${owner}/${repo}/releases/${tag}`);
+  }
+} catch (e) {
+  console.error(String(e.message || e));
+  process.exit(1);
+}

package/scripts/release-body.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * 组合发布正文（GitHub / Gitee 发行版共用）。
+ *
+ * 目的：把每个版本的双语发布说明文档（docs/release-v<版本>.md 与 .en.md）合成为发行版正文，并：
+ *   1) 把文档里的**相对链接**改写为指向该 tag 的**绝对链接**（否则 Release 页上会 404）；
+ *   2) 末尾追加 npm 包链接、CI 链接（可选）与 Full Changelog 比较链接。
+ *
+ * 用法（CLI）：
+ *   node scripts/release-body.mjs <version> <github|gitee> [ownerRepo] [npmPackage] [ciRunId] [previousVersion]
+ *   例：node scripts/release-body.mjs 0.3.0 github lanlan0811/tianshu-mcp tianshu-mcp 34661265199 0.2.0
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const repoRoot = path.resolve(here, "..");
+
+/**
+ * host 标识 → 站点域名（避免把 "gitee" 当成域名拼出 `https://gitee/...`）。
+ * @param {"github"|"gitee"} host
+ */
+export function hostDomain(host) {
+  return host === "gitee" ? "gitee.com" : "github.com";
+}
+
+/**
+ * 把文档中的相对 markdown 链接改写为该 tag 的绝对链接。
+ * 仅改写形如 `](name.md)` / `](name.en.md)` 的文档内相对链接；已是 http(s) 的保持原样。
+ * @param {string} text
+ * @param {{host: "github"|"gitee", ownerRepo: string, tag: string}} ctx
+ */
+export function absolutizeDocLinks(text, { host, ownerRepo, tag }) {
+  const base = `https://${hostDomain(host)}/${ownerRepo}/blob/${tag}/docs/`;
+  return text.replace(/\]\((?!https?:\/\/)([^)\s]+\.md)(#[^)]*)?\)/g, (_m, file, anchor) => {
+    return `](${base}${file}${anchor ?? ""})`;
+  });
+}
+
+/**
+ * 读取发布说明文档；缺失时返回 null。
+ * @param {string} version
+ * @param {"zh"|"en"} lang
+ */
+export function readReleaseDoc(version, lang) {
+  const suffix = lang === "en" ? ".en.md" : ".md";
+  const p = path.join(repoRoot, "docs", `release-v${version}${suffix}`);
+  return fs.existsSync(p) ? fs.readFileSync(p, "utf8").trim() : null;
+}
+
+/**
+ * @typedef {Object} ComposeOptions
+ * @property {string} version
+ * @property {"github"|"gitee"} host
+ * @property {string} ownerRepo   形如 lanlan0811/tianshu-mcp 或 Lan0811/tianshu-mcp
+ * @property {string} [npmPackage]
+ * @property {string|number} [ciRunId]
+ * @property {string} [previousVersion]  用于 Full Changelog 的上一版本 tag（不含 v）
+ */
+
+/**
+ * 合成双语发布正文。
+ * @param {ComposeOptions} opts
+ * @returns {string}
+ */
+export function composeReleaseBody(opts) {
+  const version = String(opts.version).replace(/^v/, "");
+  const tag = `v${version}`;
+  const { host, ownerRepo } = opts;
+  const npmPackage = opts.npmPackage ?? "tianshu-mcp";
+
+  const zh = readReleaseDoc(version, "zh");
+  const en = readReleaseDoc(version, "en");
+  if (!zh && !en) {
+    throw new Error(
+      `未找到发布说明文档 docs/release-v${version}.md / .en.md；请先写好发布说明再发布。`,
+    );
+  }
+
+  /** @type {string[]} */
+  const parts = [];
+  if (zh) parts.push(absolutizeDocLinks(zh, { host, ownerRepo, tag }));
+  if (en) {
+    parts.push("---");
+    parts.push(absolutizeDocLinks(en, { host, ownerRepo, tag }));
+  }
+
+  /** @type {string[]} */
+  const footer = ["---", ""];
+  footer.push(`**npm**: https://www.npmjs.com/package/${npmPackage}/v/${version}`);
+  if (opts.ciRunId) footer.push(`**CI**: https://github.com/${ownerRepo}/actions/runs/${opts.ciRunId}`);
+  const prev = opts.previousVersion ? `v${String(opts.previousVersion).replace(/^v/, "")}` : "";
+  if (host === "github") {
+    footer.push(
+      prev
+        ? `**Full Changelog**: https://github.com/${ownerRepo}/compare/${prev}...${tag}`
+        : `**Full Changelog**: https://github.com/${ownerRepo}/commits/${tag}`,
+    );
+  } else {
+    // Gitee 的比较页路径与 GitHub 不同，指向该 tag 的提交列表更稳
+    footer.push(`**Full Changelog**: https://gitee.com/${ownerRepo}/commits/${tag}`);
+  }
+  parts.push(footer.join("\n"));
+
+  return parts.join("\n\n").trimEnd() + "\n";
+}
+
+// CLI 入口（跨平台判断：比较解析后的文件路径）
+const invokedDirectly =
+  process.argv[1] &&
+  pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url;
+
+if (invokedDirectly) {
+  const [, , version, host, ownerRepo, npmPackage, ciRunId, previousVersion] = process.argv;
+  if (!version || !host) {
+    console.error(
+      "用法: node scripts/release-body.mjs <version> <github|gitee> [ownerRepo] [npmPackage] [ciRunId] [previousVersion]",
+    );
+    process.exit(2);
+  }
+  if (host !== "github" && host !== "gitee") {
+    console.error("host 必须是 github 或 gitee");
+    process.exit(2);
+  }
+  const repo = ownerRepo || (host === "github" ? "lanlan0811/tianshu-mcp" : "Lan0811/tianshu-mcp");
+  try {
+    process.stdout.write(
+      composeReleaseBody({
+        version,
+        host,
+        ownerRepo: repo,
+        npmPackage: npmPackage || "tianshu-mcp",
+        ciRunId: ciRunId || undefined,
+        previousVersion: previousVersion || undefined,
+      }),
+    );
+  } catch (e) {
+    console.error(String(e.message || e));
+    process.exit(1);
+  }
+}

package/skills/tianshu-mcp/SKILL.md

@@ -1,24 +1,24 @@
 ---
 name: tianshu-mcp
-description: 让外部 AI-Agent（codex/zcode/traework）做项目开发并自动验收、失败返修的编排方法。当任务需要"叫一个 AI-Agent 去开发/改代码/补测试并验收，不行就返修"时先加载本技能：按它用 mcp__tianshu-mcp__run_task/continue_task/query_task/verify_task/rework_task 派活、暂停继续、轮询、读验收报告、驱动返修。小改动或纯问答不需要。
-triggers: '开发|编码|写代码|改代码|实现功能|加功能|修复|重构|补测试|写测试|验收|返修|返工|重做|ai.?agent|子代理|外部.?agent|agent|codex|zcode|traework|claude|编排|项目开发|派活'
+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 开发并验收、失败返修"类任务。动手前先通读本技能全文；任务书模板、meta 块解读示例、返修提示语模板在同目录 `usage-examples.md`，需要时用 `read_file` 读取，长方法论不必背。
+**首行强指令**：你正处理"派外部 AI-Agent 开发并验收、失败返修"类任务。动手前先通读本技能全文；任务书模板、三种 agent 派活示例、meta 块字段解读、返修提示语模板在同目录 `usage-examples.md`，需要时用读取文件工具查看，长方法论不必背。
 
 ## 何时不要用（边界）
 
 - 小改动 / 纯问答 / 只读代码分析：不需要本技能与 MCP，直接做。
 - 本 MCP 未连接：工具面里看不到 `mcp__tianshu-mcp__*` 时，先提示用户按天枢 `config.json → mcp.servers.tianshu-mcp` 接入（见项目 docs/tianshu-integration.md），**不要空转**，更不要假装调用。
 
-## 1. 选 agent
+## 1. 选 agent（三者均为 GUI 驱动：CDP 控制桌面端，非 CLI）
 
-- `codex`：Codex 桌面端自带 CLI（通用编码，默认，推荐先试）。
-- `zcode`：ZCode 桌面端独立 CDP GUI adapter。要求已安装、已登录；`model` 必须为 `供应商/模型`，发送前确认“完全访问”。双平台真机证据补齐前 profile 为 `research`，用 `get_profiles` 读取当前机器实际探测结果。
-- `traework`：TraeWork（TRAE SOLO CN）桌面端，**GUI 驱动**（CDP）。适合需要 TraeWork 原生能力的任务；要求 TraeWork 已登录、窗口可见。可用 `model` 指定模型（如 `GLM-5.3`）、`mode` 指定面板模式（`Work`/`Code`/`Design`）。
-- 不确定时问用户，或读项目 `projects.json` 的 `defaultAgentId`。用 `get_profiles` 看当前实际可用性（会做可执行探测）。
+- `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` 读取当前机器实际探测结果。
+- `traework`：TraeWork（TRAE SOLO CN）桌面端。要求已登录、窗口保持可见。`model` 可选；`mode` 可选（`Work`/`Code`/`Design`；不传时从任务书文本识别「切换 X 模式」，识别不到保持 `Work`；实现顺序为「新建会话 → 切模式 → 在目标模式内绑定项目」）。
+- 不确定时问用户，或读项目 `projects.json` 的 `defaultAgentId`；用 `get_profiles` 看当前实际可用性（含可执行探测与未安装提示）。
 
 ## 2. 派活：run_task
 
@@ -26,47 +26,55 @@ triggers: '开发|编码|写代码|改代码|实现功能|加功能|修复|重
 
 - `projectPath`：**必须**是项目绝对路径（如 `D:\repo\my-app`）。
 - `task`：自然语言任务书。要写清 **目标 / 验收要点 / 约束 / 相关文件 / 上下文**，模板见 usage-examples.md。
-- `agentId`：默认取项目 default 或 codex。
-- `model`：TraeWork 可选；ZCode 必填且格式为 `供应商/模型`（如 `DeepSeek/deepseek-flash`）。
-- `mode`：可选，仅 GUI 类 agent（`traework`）生效，指定面板模式 `Work` / `Code` / `Design`；不传时从任务书文本识别（如「切换到 Code 模式」），识别不到则保持 `Work`。实现顺序为「新建会话 → 切模式 → 在目标模式内绑定项目」。
+- `agentId`：默认取项目 default 或 codex；`model`/`mode`/`reasoningLevel` 等约束见 §1。
+- `context`：补充上下文/约束文本，会以【上下文与约束】拼进 agent 初始指令。task/context 中反引号包裹或路径形态的引用会在发送前校验（必须存在且在项目内），写错立即报错。
 - `autoVerify: true`：跑完自动验收（命令检查 + 代码分析）。
-- `autoFixRounds: N`：>0 才开启失败自动返修；ZCode 缺省为 2，其余 agent 仍按 server 默认。
-- `taskTimeoutMs`：任务级超时，缺省 30 分钟，长任务可调大。
+- `autoFixRounds: N`（0–10）：>0 才开启失败自动返修。优先级：调用参数 > agent 缺省（codex 5、zcode 2）> server 默认 0（不开启）。
+- `taskTimeoutMs`：任务级超时；缺省 30 分钟。
 
 返回立刻给 `taskId`（异步契约）。**不要把任务书当同步调用等结果。**
 
-## 3. 轮询：query_task
+## 3. 轮询与查询
 
-- `query_task(taskId)` 间隔约 5–10 秒，看 agent 日志尾与状态。
-- 同一项目勿重复派单：每项目串行，重复派会排队，反而更慢。
-- 状态语义：
-  - `queued` 排队中 / `running` 开发中 / `verify_start` 验收中 / `fixing` 返修中；
-  - `needs_user` 表示 ZCode 正在等待问题回答、关闭旧实例、登录或系统权限；按提示处理后调用 `continue_task(taskId, message)`，禁止新开会话冒充恢复；
-  - 终态见下。
+- `query_task(taskId, tailLines?)` 间隔约 5–10 秒，看 agent 日志尾与状态（tailLines 缺省返回日志末 40 行）。
+- 查历史任务用 `list_tasks(projectPath?, status?, limit?)`（limit 缺省 50，上限 200）。
+- 同一项目勿重复派单：每项目串行 + 全局并发（默认 2），重复派会排队，反而更慢。
+- 状态语义：`queued` 排队中 / `running` 开发中 / `verify_start` 验收中 / `fixing` 返修中；`needs_user` 表示 agent 在等用户（按 §4 处理）；终态见 §5。
 
-## 4. 终态解读
+## 4. needs_user：continue_task
 
-- `succeeded`：用 `get_task_report(taskId)` 取 changedFiles / diffstat / checks，向用户汇报变更与结论。
-- `failed`：**未开自动返修或硬失败**。读 `query_task` 的 meta 与 `get_task_report` 定位失败 checks；如可修 → `rework_task(taskId, feedback=失败摘要)` 手动续修（feedback 会给下一轮 agent）；再轮询/`verify_task`。
-- `needs_attention`：自动返修轮次已用尽仍失败。同样先读报告，给**针对性** feedback 调 `rework_task`（不要无脑重复同样的话）。多次仍不过或不可修：如实向用户汇报并给建议（人工看报告/换 agent/缩小任务），**不要反复空转重试**。
-- `running` 卡死/超时：`cancel_task(taskId, reason)` 终止（kill 进程树）。
+meta 块中 `needsUserKind` 给出等待类型、`pendingQuestion` 给出问题原文：
 
-## 5. 验收报告解读要点
+- `agent_question`：agent 提了问题 → 用 `continue_task(taskId, message=<答案>)`，message 会发到原会话。
+- `close_existing_instance` / `login_required` / `system_permission`：需用户先处理（关闭旧实例 / 登录 / 授系统权限）→ 用户处理完后调 `continue_task(taskId, message=<已处理说明>)`，message 仅作为已处理的确认。
 
-- 结果文本末尾有 `---tianshu-mcp-meta---` 块（JSON），天枢可正则抽取。字段：`ok / status / round / changedFiles / diffstat / reportFiles / logFile / message`。
-- 报告全文走 `get_task_report`：`checks[]`（每项 PASS/FAIL/SKIP + 输出尾部）、`analysis`（变更清单、diffstat、可疑标记命中计数、超大单文件改动告警、结构性核对提示）。
+禁止新开会话冒充恢复。
+
+## 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)` 终止（kill 进程树）。
+
+## 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 时按当前基线做健康检查。
+- 验收命令优先级：`extraChecks` > 项目 `.tianshu-mcp/acceptance.json` > projects.json 管理员补录 > 按技术栈推导的默认集。
 - 注意：代码分析是确定性规则（TODO/FIXME、console.log/debugger、疑似密钥形态、超大改动），**不是** LLM 评审——命中仅提示人工，不等同于任务失败。
-- changedFiles/diffstat 都相对**动工前 git 基线**（run_task 自动采集）。MCP 不自动 commit/stash；需要回滚时由用户基于报告决定。
+- changedFiles/diffstat 都相对**动工前 git 基线**（run_task 自动采集，含未跟踪新增）。MCP 不自动 commit/stash；需要回滚时由用户基于报告决定。
 
-## 6. 纪律
+## 7. 纪律
 
-- 写/执行类工具（run/cancel/rework）需审批：不绕过、不替用户代点同意。
+- 写/执行类工具（run/cancel/rework/continue）需审批：不绕过、不替用户代点同意；query/list/report/verify/get_profiles 为只读，无需审批。
 - 不代替外部 agent 手改项目代码；不改用户 git 历史；不读取/转发任何 agent 密钥（登录态各 agent 自持）。
-- 验收命令来自白名单式配置，不做 shell 注入。
+- 验收命令来自白名单式配置、按 argv 分词执行，不做 shell 注入。
 
 ## 快速上手清单
 
 1. `get_profiles` → 确认目标 agent 可用。
-2. `run_task(projectPath, task, agentId=codex, autoVerify=true, autoFixRounds=2)` → 拿 taskId。
-3. `query_task(taskId)` 每 ~8 秒轮询到终态。
-4. 终态处理见上；汇报时带 `get_task_report` 的 changedFiles 与 diffstat。
+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 处理。
+4. 终态处理见 §5；汇报时带 `get_task_report` 的 changedFiles 与 diffstat。

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

@@ -1,6 +1,6 @@
 # tianshu-mcp 使用示例（子文件）
 
-正文过长方法论不背：任务书模板、meta 块解读、返修提示语模板都在这里，按需 `read_file`。
+正文过长方法论不背：任务书模板、三种 agent 派活示例、meta 块字段解读、验收与返修模板都在这里，按需用读取文件工具查看。
 
 ## 1. 任务书模板
 
@@ -19,6 +19,11 @@
 - <背景 / 已知约定 / 为什么这么做>
 ```
 
+要点：
+
+- 「相关文件 / 上下文」里的项目内路径建议用反引号或 `./` 相对路径书写（如 `` `src/run.ts` ``、`./docs/plan.md`）——task/context 中的路径引用会在发送前校验存在性与项目边界，写错会立即报错而不是带病派单。
+- 「上下文」也可拆到 `run_task` 的 `context` 参数：它会以【上下文与约束】拼进 agent 初始指令，适合放较长且与任务书正文解耦的背景。
+
 示例（真实可用）：
 
 ```text
@@ -30,14 +35,63 @@
 - 不要改动 src/config/ 下已稳定的 schema
 - 保持现有参数解析风格（commander）
 相关文件：
-- src/cli.ts（入口与参数定义）、src/run.ts（执行逻辑）
+- `src/cli.ts`（入口与参数定义）、`src/run.ts`（执行逻辑）
 上下文：
 - 现有 run 命令会写 out/ 目录；dry-run 应跳过全部写操作
 ```
 
-## 2. meta 块解读示例
+## 2. 三种 agent 派活示例
+
+### 2.1 codex（默认；model 必填，支持 reasoningLevel / planDoc / designSystem）
+
+```text
+run_task(projectPath=D:/repo/app, agentId=codex,
+  model=GPT-5.6 Sol,
+  reasoningLevel=高,
+  planDoc=./docs/plan.md,
+  designSystem=./design-system,
+  task=按计划文档实现列表页与详情页,
+  autoVerify=true, autoFixRounds=5)
+```
+
+- `planDoc` / `designSystem` 会被拼进初始开发指令「根据计划文档(<planDoc>)…和设计系统(<designSystem>)…」，路径必须存在且在项目内。
+- `reasoningLevel` 接受 低/中/高 或 low/medium/high；不传沿用面板当前等级。
+- 不支持 `mode` 参数，传了会直接报错。
+
+### 2.2 zcode（model 必填且为「供应商/模型」）
+
+```text
+run_task(projectPath=D:/repo/app, agentId=zcode,
+  model=DeepSeek/deepseek-flash,
+  task=按 `./docs/plan.md` 与 `./design-system` 实现功能,
+  autoVerify=true, autoFixRounds=2)
+```
+
+若 `query_task` 返回 `needs_user`，先读 meta 的 `needsUserKind` 与 `pendingQuestion`：
+
+```text
+continue_task(taskId=tsk_..., message=采用 PostgreSQL 方案)
+```
+
+- `needsUserKind=agent_question`：message 作为答案发送到原会话。
+- `needsUserKind=close_existing_instance / login_required / system_permission`：先让用户处理（关旧实例 / 登录 / 授系统权限），message 仅作为用户已处理的确认。
+
+### 2.3 traework（model 可选；唯一支持 mode）
+
+```text
+run_task(projectPath=D:/repo/app, agentId=traework,
+  model=GLM-5.3,
+  mode=Code,
+  task=重构导出模块,
+  autoVerify=true)
+```
+
+- `mode` 缺省时从任务书文本识别「切换 Work/Code/Design 模式」，识别不到保持 `Work`。
+- TraeWork 窗口需保持可见；实现顺序为「新建会话 → 切模式 → 在目标模式内绑定项目」。
+
+## 3. meta 块解读示例
 
-`query_task` / `run_task` 等结果文本末尾的结构化块：
+`run_task` / `query_task` 等结果文本末尾的结构化块：
 
 ```text
 ---tianshu-mcp-meta---
@@ -47,49 +101,77 @@
   "status": "needs_attention",
   "agentId": "codex",
   "projectPath": "d:/repo/my-app",
+  "model": "GPT-5.6 Sol",
   "round": 3,
   "changedFiles": ["src/a.ts", "src/b.ts"],
   "diffstat": "+18 -4",
-  "reportFiles": { "md": "<路径>/report-2.md", "json": "<路径>/report-2.json" },
-  "logFile": "<路径>/agent-2.log",
-  "message": "验收失败，自动返修轮次已用尽（3/2 轮）。…"
+  "reportFiles": { "md": "<任务目录>/report-2.md", "json": "<任务目录>/report-2.json" },
+  "logFile": "<任务目录>/agent-2.log",
+  "errorType": "verify_failed",
+  "reportRound": 2,
+  "verificationSource": "auto",
+  "message": "验收失败，自动返修轮次已用尽（3/5 轮）。…"
 }
 ---tianshu-mcp-meta---
 ```
 
-读法：
+读法（按决策用途分组）：
 
 | 字段 | 含义 |
 |---|---|
-| `ok` | 是否成功（succeeded 才有 true） |
+| `ok` | 是否成功（仅 status=succeeded 时为 true） |
 | `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 |
+| `pendingQuestion` | needs_user 时 agent 提出的问题原文 |
 | `round` / `roundsUsed` | 已进行的 agent 轮次 |
 | `changedFiles` | 相对 git 基线的变更清单（含未跟踪新增） |
 | `diffstat` | 增删行摘要（`+A -D`） |
 | `reportFiles` | 最近一轮验收报告 md/json 绝对路径 |
 | `logFile` | 最近一轮 agent 日志 |
-| `message` | 状态摘要/失败原因 |
+| `reportRound` | 最近一次验收的报告轮次（0-based，区别于 agent 轮次） |
+| `verificationSource` | 最近一次验收来源：auto（run_task 自动）/ manual（verify_task 手动） |
+| `latestVerificationVerdict` | 手动验收结论（不改变任务终态时单独记录） |
+| `abortSource` | 中断来源：user/shutdown/timeout/internal |
+| `model` / `mode` / `reasoningLevel` | 本次派单的模型 / 面板模式 / 思考等级（按 agent 生效） |
 
-规则：`ok=true` 且 status=succeeded → 交付达成；否则读 `reportFiles.md` 全文定位。
+规则：`ok=true` 且 status=succeeded → 交付达成；否则读 `message` 与 `reportFiles.md` 全文定位。
 
-## 3. ZCode 派活与继续
+## 4. 验收：verify_task 示例
+
+只读、不改源码、无需审批。三种典型用法：
 
 ```text
-run_task(projectPath=D:/repo/app, agentId=zcode,
-  model=DeepSeek/deepseek-flash,
-  task=按 `./docs/plan.md` 与 `./design-system` 实现功能,
-  autoVerify=true)
+# 1) 复跑某任务的验收（用该任务动工前基线；round 缺省对最新状态）
+verify_task(taskId=tsk_...)
+
+# 2) 独立健康检查（无任务上下文，按当前基线）
+verify_task(projectPath=D:/repo/app)
+
+# 3) 临时加验 + 指定基线（extraChecks 追加到基础集之后）
+verify_task(projectPath=D:/repo/app, baselineRef=HEAD~1,
+  extraChecks=[{name=lint, cmd=npm run lint, timeoutMs=120000}],
+  checksMode=append)
 ```
 
-若 `query_task` 返回 `needs_user`：
+- `checksMode=replace` 时只用 `extraChecks`，不跑项目基础集。
+- `extraChecks` 单条支持 `name`/`cmd`（argv 数组或字符串）/`timeoutMs`/`optional`（optional:true 失败只记 warning）。
+- 验收命令优先级：extraChecks > 项目 `.tianshu-mcp/acceptance.json` > projects.json 管理员补录 > 按技术栈推导的默认集（详见 docs/acceptance-config.md）。
+
+## 5. 查历史：list_tasks 示例
 
 ```text
-continue_task(taskId=tsk_..., message=采用 PostgreSQL 方案)
+# 某项目最近失败/需关注的任务
+list_tasks(projectPath=D:/repo/app, status=needs_attention, limit=10)
+
+# 全局最近 50 条
+list_tasks()
 ```
 
-`agent_question` 的 message 会发送到原会话；关闭旧实例、登录或系统权限场景的 message 仅作为用户已处理的确认。
+返回含每条任务的 taskId/status/agentId/时间摘要，可用于接续 `get_task_report` / `rework_task`。
 
-## 4. 返修提示语模板
+## 6. 返修提示语模板
 
 给 `rework_task(taskId, feedback)` 的 `feedback`，讲究**针对性**，避免空转：
 
@@ -113,14 +195,16 @@ continue_task(taskId=tsk_..., message=采用 PostgreSQL 方案)
 parameter of type 'number' (src/run.ts:42)。请只修这一处类型问题并重跑 npm run build 确认。
 ```
 
-## 5. 汇报模板
+补充：自动返修（autoFixRounds）路径下，server 会先把失败证据写成修复计划文档（codex 写到项目 `.zcode/plans/`），并在下一轮指令中引用该文档；手动 `rework_task` 的 feedback 则按上面的针对性模板书写。
+
+## 7. 汇报模板
 
 `get_task_report` 拿全文后向用户汇报建议包含：
 
 ```text
-任务 <taskId> 已完成（<agent>）。
+任务 <taskId> 已完成（<agent>，model=<model>）。
 - 变更文件：src/a.ts、src/b.ts（+18 -4）
-- 自动命令检查：build ✅ / test ✅ / lint 跳过
-- 代码分析：无可疑标记；注意 README 新增超大改动 ⚠️
+- 自动命令检查：build PASS / test PASS / lint 跳过
+- 代码分析：无可疑标记；注意 README 存在超大单文件改动（告警）
 - 验收报告：<report.md 路径>
 ```