tianshu-mcp 0.7.2 → 0.7.3

package/CHANGELOG.en.md

@@ -8,6 +8,35 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.7.3] - 2026-09-28
+
+### Fixed
+
+- **Skill docs had drifted from the implementation** (`skills/tianshu-mcp/`):
+  - `usage-examples.md` carried a **duplicate `### 2.9`** (codex-cli and the shared-conventions section
+    collided) → the latter is now `### 2.10`;
+  - `SKILL.md` §9 did not state that its error-code table is a subset — `endReason` is typed as an optional
+    `string` (`src/agents/adapter.ts:93`) with **no enum constraint**, so an adapter can add a value without a
+    type change. The doc now says so, and points readers at the adapter's `run.ts` for unknown values;
+  - added three high-frequency `endReason` values that were missing from the table: `input_mismatch`
+    (a leftover draft makes the task land inside stale text), `send_unknown` (delivery unconfirmable —
+    **never resends**), and `reply_stable` (normal completion, not an error).
+
+### Docs
+
+- **Documented Open Design artifact retrieval** (a `v0.7.1` capability, previously absent from the skill):
+  designs live in the product's artifact store `<dataRoot>/projects/<projectId>/<entry>`, **not** in the
+  task directory; once terminal the adapter copies it into `projectPath`.
+- **Documented the daemon-readiness precondition**: the product completes an auth handshake with its daemon
+  before opening the folder picker (measured ~30s after launch); when unready the product **opens no dialog
+  at all**.
+- **Marked the `zip` export as a known limitation** (the product's main process takes over downloads,
+  overriding CDP's handling; the `html` path is fully working).
+
+> This release contains **no runtime code changes** (only `skills/` docs and the version bump), so upgrading
+> from `0.7.2` changes no behaviour; it syncs docs with implementation and aligns tag / Release / npm on a
+> single commit.
+
 ## [0.7.2] - 2026-09-28
 
 ### Fixed

package/CHANGELOG.md

@@ -7,6 +7,29 @@
 
 ---
 
+## [0.7.3] - 2026-09-28
+
+### 修复
+
+- **skill 文档与实现脱节**（`skills/tianshu-mcp/`）：
+  - `usage-examples.md` 存在**两个 `### 2.9`**（codex-cli 与通用约定撞号）→ 后者改为 `### 2.10`；
+  - `SKILL.md` §9 的错误码表未声明「这是子集而非闭集」—— `endReason` 在类型层面只是可选
+    `string`（`src/agents/adapter.ts:93`），**没有枚举约束**，适配器新增分支无需改类型即可引入新取值。
+    现已显式声明，并提示读者遇到表外取值时去读对应适配器的 `run.ts`；
+  - 补入三个真机高频但表中缺失的 `endReason`：`input_mismatch`（输入框残留导致任务被插进残文）、
+    `send_unknown`（无法确认落地，**绝不重发**）、`reply_stable`（正常完成，非错误）。
+
+### 文档
+
+- **补写 Open Design 产物取回**（`v0.7.1` 起的能力，此前未进 skill 正文）：设计稿存在产品的产物存储
+  `<dataRoot>/projects/<projectId>/<entry>` 而**不在任务目录**，终态后由适配器复制到 `projectPath`。
+- **补写 daemon 就绪前置**：产品打开文件夹选择器前需与 daemon 完成鉴权握手（实测启动后约 30s 才驻留），
+  未就绪时产品**根本不弹对话框**。
+- **标注 `zip` 导出为已知限制**（产品主进程接管下载，CDP 接管被覆盖；`html` 路径完全可用）。
+
+> 本版**不含运行时代码变更**（仅 `skills/` 文档 + 版本号），从 `0.7.2` 升级无功能差异；
+> 发布目的是让文档与实现同步、并让 tag / Release / npm 收敛到同一 commit。
+
 ## [0.7.2] - 2026-09-28
 
 ### 修复

package/dist/version.generated.js

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

package/package.json

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

package/skills/tianshu-mcp/SKILL.md

@@ -264,6 +264,11 @@ meta 的 `needsUserKind` 给出等待类型，`pendingQuestion` 给出问题原
 
 `agentEndReason` 与终态映射（先记住这张表，再看错误码表）：
 
+> **下面的错误码表是「常见子集」而非闭集**：`endReason` 在类型层面只是一个可选 `string`
+> （`src/agents/adapter.ts:93`），没有枚举约束，某个适配器新增分支时无需改类型就能引入新取值。
+> 因此看到表里没有的取值时，**按名字猜语义不如去读该适配器的 `run.ts`**，或看 `query_task` 的
+> 日志尾部与 `progressSummary`。
+
 | `agentEndReason` | 任务终态 |
 |---|---|
 | `task_timeout` | `needs_attention` + `errorType=timeout`（GUI：codex/zcode）；qoder 落 `failed(timeout)` |
@@ -273,6 +278,9 @@ meta 的 `needsUserKind` 给出等待类型，`pendingQuestion` 给出问题原
 | `agentEndReason` | 含义 | 处置 |
 |---|---|---|
 | `setup_failed` | 找不到安装 / 实例未就绪 / 点不到「新对话」 | 让用户确认已安装且能手动打开；重试一次 |
+| `input_mismatch` | 任务输入框回读与本次标记不符（真机常见成因：输入框残留模板/草稿，任务被插进残文里） | 适配器已先清空再输入；若仍失败，让用户手动清空输入框后重派 |
+| `send_unknown` | 点了发送但**无法确认消息落地** | 适配器**绝不重发**（避免重复派活）；请用户在界面确认是否已发出，再决定重派或 `continue_task` |
+| `reply_stable` | **正常完成**：对话与产物均已静止 | 不是错误；去读验收报告 |
 | `project_ambiguous` | 项目同名或路径重复，无法消歧 | 已转 `needs_user(setup_recovery)`：请用户确认目标项目后 `continue_task` |
 | `project_mismatch` | 项目绑定或回读不一致，幂等重试仍失败 | 同上：请用户在 GUI 里确认/手工绑定 |
 | `project_create_failed` | 在 GUI 内新建项目失败 | 让用户手动把项目加进 agent，或换 `projectPath` |

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

@@ -193,7 +193,16 @@ run_task(projectPath=D:/repo/design, agentId=opendesign,
 - `designSystem` 传**设计系统名**（如 `Claude`、`Neutral Modern`），不是目录路径——与 codex 的 `designSystem` 语义不同（那边是目录）。
 - `mode` 不支持（那是 traework 的面板模式）；`model` 必填，按名字**精确匹配**菜单项，未命中会报错并**回显当前可见候选**，不会退化成模糊匹配。
 - 目录绑定按「展开工作目录 → 选择目录 → 原生『选择文件夹』填绝对路径 → **回读显示值校验**」；已是目标目录则跳过。
-- 视觉验收要求项目里有可截图的页面来源；适配器只**推导建议**（静态入口优先），**不会自动修改** `.tianshu-mcp/acceptance.json`。
+  （绑目录前适配器会先等 **daemon sidecar 就绪** —— 产品打开文件夹选择器前要与 daemon 完成鉴权握手，
+  实测启动后约 30s 才驻留；未就绪时产品只会显示自己的提示、**根本不弹对话框**。）
+- **产物会自动取回任务目录**（`v0.7.1` 起）：Open Design 的设计稿存在它自己的产物存储
+  `<dataRoot>/projects/<projectId>/<entry>`，**不在任务目录里**。终态后适配器把它复制到
+  `projectPath`，视觉验收随后可推导静态入口（`onboarding-guide.html` → 路由 `/onboarding-guide.html`）。
+  取回是**增值步骤**：失败只写进 `progressSummary`，**不改变任务终态**。
+- **`zip` 导出方式尚未打通**（已知限制）：产品的下载由主进程接管，CDP 的下载接管被覆盖；
+  `html` 路径完全可用，zip 待后续优化。
+- 视觉验收要求项目里有可截图的页面来源；适配器只**推导建议**（静态入口优先，白名单未命中时
+  若项目根下 html **恰好唯一**也认它），**不会自动修改** `.tianshu-mcp/acceptance.json`。
 - 修复/优化计划落项目根 `.opendesign/plans/`（Open Design 只能读它工作目录白名单内的文件）。
 - 可正常派活（Windows 真机取证；macOS 为 `research` 且禁止派发）。仍 **fail-closed**：选择器漂移时硬失败 `selector_drift` 并列出缺失键，模型未命中报 `model_unavailable` 并回显可见候选，设计方向非法在**入口**即拒绝。
   详见 [docs/opendesign-cdp.md](../../docs/opendesign-cdp.md) 与 `.dsh/plans/opendesign-gui-adapter-plan.md`。
@@ -212,7 +221,7 @@ run_task(projectPath=/path/to/项目, agentId=codex-cli,
 - 写入被 `workspace-write` 沙箱限制在项目目录内；POSIX 下取消/超时对进程组 `SIGTERM`→`SIGKILL`。
 - **无头路径没有 GUI 交互**：不存在 `user_confirmation` 这类等待，`continue_task` 不适用；失败直接看 `agentEndReason` 与日志。
 
-### 2.9 通用约定
+### 2.10 通用约定
 
 - `run_task` 是**异步契约**：立即返回 `taskId` + 队列位置，不要当同步调用等结果。
 - 轮询间隔 5–10 秒（`query_task` 缺省返回 agent 日志末 40 行）；同项目串行 + 全局并发默认 2，重复派单只会排队。