tianshu-mcp 0.1.10 → 0.2.0

package/CHANGELOG.en.md

@@ -18,6 +18,30 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.2.0] — 2026-09-11
+
+### Added
+
+- Dedicated `zcode-gui` Electron CDP adapter with data-driven Windows/macOS discovery, dynamic ports, product/process checks, and a global serial lock.
+- Exact ZCode project binding, guarded native folder pickers, `provider/model`, Full Access read-back, and idempotent sending.
+- Paused `needs_user` state and approval-gated `continue_task` for original-session answers and environment rechecks after instance, login, or permission handling.
+- Multi-signal liveness, progress events, UI preservation, default auto-verification, and two same-session repair rounds. Repair plans stay in MCP task storage.
+- `scripts/probe-zcode.mjs`, fake-CDP/state/path/model tests, and bilingual documentation.
+
+### Safety and compatibility
+
+- GUI profiles support an explicit `adapter`; legacy `driver="gui"` profiles retain TraeWork behavior.
+- The built-in ZCode profile remains `research` until both real platform loops pass.
+- No private `app-server`, credential access, automatic user-instance termination, or fixed screen coordinates.
+
+### Fixed and verified
+
+- Fixed ZCode read-back for dynamic model labels, transient renderer load/reload, delayed new-session registration, and stale session-ID contamination.
+- `AskUserQuestion` continuation now selects and submits an exact accessible option in the original session; zero or ambiguous matches fail closed.
+- Windows 10 x64 passed three hardware loops: real file development, same-session repair after a controlled failure, and `continue_task` after a model question. macOS hardware evidence remains pending.
+
+---
+
 ## [0.1.10] — 2026-09-10
 
 ### Fixed

package/CHANGELOG.md

@@ -17,6 +17,30 @@
 
 ---
 
+## [0.2.0] — 2026-09-11
+
+### 新增
+
+- 独立 `zcode-gui` Electron CDP adapter：数据驱动 Windows/macOS 安装探测、动态端口、产品/进程归属核验和全局串行锁。
+- ZCode 精确项目绑定、受守卫的原生文件夹面板、`供应商/模型`、完全访问回读和幂等发送。
+- `needs_user` 暂停状态与需审批的 `continue_task`，支持原会话问题回答及旧实例、登录、系统权限处理后的环境复检。
+- 多信号运行检测、进度事件、现场保留、默认自动验收和 2 轮同会话返修；返修计划只写 MCP 任务数据目录。
+- `scripts/probe-zcode.mjs`、假 CDP/状态机/路径/模型测试和中英文文档。
+
+### 安全与兼容
+
+- GUI profile 新增显式 `adapter`；旧 `driver="gui"` 配置继续按 TraeWork 兼容。
+- ZCode 双平台真实闭环证据完成前，内置 profile 保持 `research`。
+- 不调用未公开 `app-server`，不读取凭证，不关闭用户实例，不使用固定屏幕坐标。
+
+### 修复与验收
+
+- 修复 ZCode 动态模型标签的回读解析、渲染器短暂繁忙/重载、新会话延迟登记和旧会话 ID 污染。
+- 续答 `AskUserQuestion` 时改为在原会话可访问问题卡片中精确选项并提交；零匹配或多匹配时 fail-closed。
+- Windows 10 x64 真机已通过文件开发、受控失败后同会话返修、模型提问后 `continue_task` 续跑三个闭环；macOS 真机仍待补齐。
+
+---
+
 ## [0.1.10] — 2026-09-10
 
 ### 修复

package/README.en.md

@@ -34,11 +34,11 @@ 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 CLI, TraeWork GUI) is the "worker" that does the development.
 
-- **8 MCP tools**: `run_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles`.
+- **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.
 - **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.
-- **Two execution surfaces**: `driver: "spawn"` runs an external CLI child process (Codex); `driver: "gui"` drives a desktop UI (TraeWork over CDP, with an optional `model` and `mode` — Work/Code/Design).
+- **Two execution surfaces**: `driver: "spawn"` runs an external CLI child process (Codex); `driver: "gui"` selects an explicit, isolated TraeWork or ZCode CDP adapter.
 - **Scheduling discipline**: per-project serial queue + global concurrency cap (default 2, configurable).
 - **No key handling**: each agent uses its own login state; this server never stores or forwards any API key.
 - **Extensible**: a new agent = one profile (data) + (if needed) one adapter file — no changes to the orchestration core.
@@ -49,7 +49,7 @@ Tianshu plays the role of the overall commander; this MCP server is the **schedu
 
 | Item | Requirement |
 |---|---|
-| Node.js | ≥ 20 (CI covers 20 / 22) |
+| Node.js | ≥ 20 (CI covers 20 / 22 / 24) |
 | Package manager | npm (the repo ships a `package-lock.json`) |
 | OS | Windows / macOS / Linux (verified by the three-platform CI matrix) |
 | Git | Optional; acceptance baseline analysis is more complete inside a git repository |
@@ -63,7 +63,7 @@ git clone https://github.com/lanlan0811/tianshu-mcp.git
 cd tianshu-mcp
 npm ci
 npm run build        # sync-version + tsc → dist/
-npm test             # 196 tests across 30 files (19 unit + 10 integration + 1 protocol)
+npm test             # 262 tests across 37 files, including ZCode unit/fake-CDP/restart/repair coverage
 ```
 
 ### Install the npm package
@@ -86,10 +86,10 @@ In Tianshu go to **Settings → MCP Servers → Add** and fill in the fields bel
 | Command | `npx` | `node` |
 | Arguments (space-separated) | `-y tianshu-mcp` | `<absolute-repo-path>/dist/index.js` |
 
-> - The server ID becomes the tool prefix: with `tianshu-mcp` the tools are `mcp__tianshu-mcp__run_task` and 7 others.
+> - The server ID becomes the tool prefix: with `tianshu-mcp` the tools are `mcp__tianshu-mcp__run_task` and 8 others.
 > - Arguments are space-separated, **no quotes**; for local dev replace `<absolute-repo-path>` with a real path (e.g. `D:/TraeProject/tianshu-mcp/dist/index.js`).
 > - The dialog has no env-var field; to customize the data directory, use the `config.json` method below and set `TIANSHU_MCP_HOME`.
-> - Once the server connects, open a new session and the 8 tools appear.
+> - Once the server connects, open a new session and the 9 tools appear.
 
 ### Or edit config.json (supports env vars)
 
@@ -109,7 +109,7 @@ Register as a Tianshu MCP server (local dev mode):
 }
 ```
 
-After opening a new session, the 8 tools such as `mcp__tianshu-mcp__run_task` appear. Rehearse with the stub agent first (no real login state), then switch to the `codex` profile for real tasks:
+After opening a new session, the 9 tools such as `mcp__tianshu-mcp__run_task` appear. Rehearse with the stub agent first (no real login state), then switch to the `codex` profile for real tasks:
 
 ```text
 run_task(projectPath=D:/xxx/my-app, task=「…task brief…」, agentId=codex, autoVerify=true, autoFixRounds=2)
@@ -126,11 +126,21 @@ run_task(projectPath=D:/xxx/my-app, agentId=traework, task=「Switch to Code mod
 > `mode` accepts `Work` / `Code` / `Design`; when omitted it is detected from the task text (e.g. "switch to Code mode"), otherwise `Work` is kept.
 > TraeWork's three modes **each keep an independent project binding**, so the order is: new session → switch to target mode → bind the project inside that mode.
 
-## Tool surface (8 tools)
+For ZCode, `model` must be an exact `provider/model` and `mode` is rejected:
+
+```text
+run_task(projectPath=D:/xxx/my-app, agentId=zcode, task="Implement `./plan.md`",
+         model=DeepSeek/deepseek-flash, autoVerify=true)
+```
+
+Questions, login, an existing non-CDP instance, or system permission pause as `needs_user`; call `continue_task(taskId, message)` to resume the recorded session. See [docs/zcode-cdp.en.md](docs/zcode-cdp.en.md).
+
+## Tool surface (9 tools)
 
 | Tool | Capability / approval | Purpose |
 |---|---|---|
 | `run_task` | write + approval | Dispatch work (optional auto-verify / auto-rework); returns `taskId` asynchronously |
+| `continue_task` | write + approval | Resume the original ZCode session from `needs_user` |
 | `query_task` | read | Poll status / progress / log tail |
 | `list_tasks` | read | Filtered history of tasks |
 | `get_task_report` | read | Full text of a verification round's report (`report.md`) |
@@ -161,6 +171,9 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
 | [docs/agent-profiles.en.md](docs/agent-profiles.en.md) | Agent profile field reference + real-machine samples |
 | [docs/adapter-matrix.en.md](docs/adapter-matrix.en.md) | Agent capability research matrix (Codex/Zcode/TraeWork/extension slots) |
 | [docs/traework-cdp.en.md](docs/traework-cdp.en.md) | TraeWork GUI driver (CDP): mechanism, config, mode switching, selectors, safety invariants, pitfalls, verification record |
+| [docs/zcode-cdp.en.md](docs/zcode-cdp.en.md) | ZCode GUI driver: discovery, exact project/model, Full Access, pause/continue, verification and platform evidence |
+| [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/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 |
 | [docs/release-v0.1.9.en.md](docs/release-v0.1.9.en.md) | v0.1.9 release notes (TraeWork task liveness and instance retention) |
 | [docs/release-v0.1.10.en.md](docs/release-v0.1.10.en.md) | v0.1.10 release notes (stdio log pollution fix: diagnostics on stderr) |
@@ -223,13 +236,16 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
 - **M10 — stdio log pollution fix + v0.1.10** ✅ (2026-09-10, see [release-v0.1.10.en.md](docs/release-v0.1.10.en.md)) — **issue #1**
   - The unified logger now sends all levels to stderr, leaving stdout for MCP JSON-RPC messages only
   - Added a strict stdio smoke (real-process byte-stream validation, 6 scenarios), Node 24 CI coverage, and an installed-package protocol gate
+- **M11 — ZCode GUI unified loop + v0.2.0** (2026-09-11, see [release-v0.2.0.en.md](docs/release-v0.2.0.en.md)) — **262 tests**
+  - Windows hardware passed real development, same-session repair after a controlled failure, and `AskUserQuestion → continue_task`; see the [acceptance record](docs/zcode-windows-smoke.en.md)
+  - macOS hardware is pending, so the built-in profile remains `research` as required by the plan
 
 ## Agent support status
 
 | agentId | driver | status | Notes |
 |---|---|---|---|
 | `codex` | `spawn` | **ready** | Reuses `~/.codex` login state; `codex exec` headless; passed real M2 smoke |
-| `zcode` | `spawn` | **unsupported** | ZCode desktop ships no headless CLI (Z1 conclusion) |
+| `zcode` | `zcode-gui` | **research** | CDP GUI adapter and Windows hardware loop passed; remains non-ready until macOS hardware passes |
 | `traework` | **`gui`** | **ready** | CDP-driven TRAE SOLO CN desktop UI; all three panel modes machine-verified |
 | `stub` | `spawn` | tests only | `test/stub-agent/stub-agent.mjs` with 3 playbooks (good/fix-on-first/never) |
 
@@ -245,7 +261,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.1.10) |
+| [CHANGELOG.en.md](CHANGELOG.en.md) | Version history (v0.1.0 → v0.2.0) |
 | [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

@@ -34,11 +34,11 @@
 
 天枢的角色是总指挥；本 MCP server 是**调度层 + 执行面 + 客观验收仪**；外部 AI-Agent（Codex CLI、TraeWork GUI）是执行开发的「工人」。
 
-- **8 个 MCP 工具**：`run_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles`。
+- **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。
 - **失败返修闭环**：自动返修（`autoFixRounds`）+ 手动 `rework_task`；验收失败时自动生成修复计划文件并回填给 agent；轮次用尽 → `needs_attention` 等天枢裁决。
-- **两种执行面**：`driver: "spawn"` 走外部 CLI 子进程（Codex）；`driver: "gui"` 走桌面 UI 自动化（TraeWork 经 CDP 驱动，可选 `model` 指定模型、`mode` 指定 Work/Code/Design 面板模式）。
+- **两种执行面**：`driver: "spawn"` 走外部 CLI 子进程（Codex）；`driver: "gui"` 由显式 adapter 驱动桌面 UI（TraeWork 与 ZCode 各自使用隔离的 CDP 流程）。
 - **调度纪律**：每项目串行队列 + 全局并发上限（默认 2，可配）。
 - **不碰密钥**：各 agent 用自己的登录态；本 server 不保存/转发任何 API key。
 - **可扩展**：新 agent = 一个 profile（数据）+（如需）一个 adapter 文件，零改编排核心。
@@ -49,7 +49,7 @@
 
 | 项 | 要求 |
 |---|---|
-| Node.js | ≥ 20（CI 覆盖 20 / 22） |
+| Node.js | ≥ 20（CI 覆盖 20 / 22 / 24） |
 | 包管理器 | npm（仓库含 `package-lock.json`） |
 | 操作系统 | Windows / macOS / Linux（CI 三平台矩阵验证） |
 | Git | 可选；验收的基线分析在 git 仓库内更完整 |
@@ -63,7 +63,7 @@ git clone https://github.com/lanlan0811/tianshu-mcp.git
 cd tianshu-mcp
 npm ci
 npm run build        # sync-version + tsc → dist/
-npm test             # 196 项测试：30 个文件（单元 19 + 集成 10 + 协议 1）
+npm test             # 262 项测试：37 个文件，含 ZCode 单元/假 CDP/重启/返修闭环
 ```
 
 ### 安装 npm 包
@@ -85,10 +85,10 @@ npm install -g tianshu-mcp
 | 命令 | `npx` | `node` |
 | 参数（空格分隔） | `-y tianshu-mcp` | `<仓库绝对路径>/dist/index.js` |
 
-> - 服务器 ID 即工具前缀：填 `tianshu-mcp` 后工具名为 `mcp__tianshu-mcp__run_task` 等 8 个。
+> - 服务器 ID 即工具前缀：填 `tianshu-mcp` 后工具名为 `mcp__tianshu-mcp__run_task` 等 9 个。
 > - 参数按空格分隔填写，**不要加引号**；本地开发模式请把 `<仓库绝对路径>` 换成真实绝对路径（如 `D:/Trae项目/tianshu-mcp/dist/index.js`）。
 > - 界面未提供环境变量输入框；如需自定义数据目录，改用下面的 `config.json` 方式设置 `TIANSHU_MCP_HOME`。
-> - 添加后连接成功即完成；新开会话即可看到 8 个工具。
+> - 添加后连接成功即完成；新开会话即可看到 9 个工具。
 
 ### 或改 config.json（可配环境变量）
 
@@ -108,7 +108,7 @@ npm install -g tianshu-mcp
 }
 ```
 
-新开会话后，工具面出现 `mcp__tianshu-mcp__run_task` 等 8 个工具。用 stub 预演（不碰真实登录态）→ 切 codex 跑真实任务：
+新开会话后，工具面出现 `mcp__tianshu-mcp__run_task` 等 9 个工具。用 stub 预演（不碰真实登录态）→ 切 codex 跑真实任务：
 
 ```text
 run_task(projectPath=D:/xxx/my-app, task=「…任务书…」, agentId=codex, autoVerify=true, autoFixRounds=2)
@@ -125,11 +125,21 @@ run_task(projectPath=D:/xxx/my-app, agentId=traework, task=「切换到 Code 模
 > `mode` 支持 `Work` / `Code` / `Design`；不传时从任务书文本识别（如「切换到 Code 模式」），识别不到则保持 `Work`。
 > TraeWork 的三种模式**各自维护独立的项目绑定**，因此实现顺序为「新建会话 → 切到目标模式 → 在目标模式内绑定项目」。
 
-## 工具面（8 个）
+驱动 ZCode 时，`model` 必须使用精确的 `供应商/模型`，且不能传 `mode`：
+
+```text
+run_task(projectPath=D:/xxx/my-app, agentId=zcode, task=「按 `./plan.md` 完成开发」,
+         model=DeepSeek/deepseek-flash, autoVerify=true)
+```
+
+ZCode 提问或需要用户处理登录、旧实例、系统权限时进入 `needs_user`；处理后调用 `continue_task(taskId, message)` 恢复原会话。完整约束见 [docs/zcode-cdp.md](docs/zcode-cdp.md)。
+
+## 工具面（9 个）
 
 | 工具 | 能力 / 审批 | 作用 |
 |---|---|---|
 | `run_task` | write + 审批 | 派活（可带自动验收/自动返修），异步返回 `taskId` |
+| `continue_task` | write + 审批 | 恢复 `needs_user` 的原 ZCode 会话 |
 | `query_task` | read | 轮询状态 / 进度 / 日志尾 |
 | `list_tasks` | read | 历史任务过滤列表 |
 | `get_task_report` | read | 某轮验收报告全文（`report.md`） |
@@ -160,6 +170,9 @@ run_task(projectPath=D:/xxx/my-app, agentId=traework, task=「切换到 Code 模
 | [docs/agent-profiles.md](docs/agent-profiles.md) | agent profiles 字段说明 + 真实机器样例（codex M2 定稿） |
 | [docs/adapter-matrix.md](docs/adapter-matrix.md) | 各 Agent 能力调研矩阵（Codex/Zcode/TraeWork/扩展位） |
 | [docs/traework-cdp.md](docs/traework-cdp.md) | TraeWork GUI 驱动（CDP）：原理、配置、模式切换、选择器、安全红线、踩坑记录、验证记录 |
+| [docs/zcode-cdp.md](docs/zcode-cdp.md) | ZCode GUI 驱动：安装探测、精确项目/模型、完全访问、暂停继续、验收返修与双平台状态 |
+| [docs/zcode-windows-smoke.md](docs/zcode-windows-smoke.md) | ZCode Windows 真机开发、同会话返修与提问续跑验收记录 |
+| [docs/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` 验收配置规范 |
 | [docs/release-v0.1.9.md](docs/release-v0.1.9.md) | v0.1.9 发布说明（TraeWork 任务进行中检测与实例保留） |
 | [docs/release-v0.1.10.md](docs/release-v0.1.10.md) | v0.1.10 发布说明（修复 stdio 日志污染：诊断日志统一走 stderr） |
@@ -224,13 +237,16 @@ run_task(projectPath=D:/xxx/my-app, agentId=traework, task=「切换到 Code 模
 - **M10 — stdio 日志污染修复 + v0.1.10** ✅（2026-09-10，见 [release-v0.1.10.md](docs/release-v0.1.10.md)）— **issue #1**
   - 统一 Logger 所有级别改走 stderr，stdout 只承载 MCP JSON-RPC 消息
   - 新增严格 stdio 冒烟（真实进程字节流校验，6 场景）、Node 24 CI 覆盖与安装包协议门禁
+- **M11 — ZCode GUI 统一闭环 + v0.2.0**（2026-09-11，见 [release-v0.2.0.md](docs/release-v0.2.0.md)）— **262 测试**
+  - Windows 真机通过开发、受控失败后同会话返修、`AskUserQuestion → continue_task` 三个场景；[验收记录](docs/zcode-windows-smoke.md)
+  - macOS 真机未补齐，内置 profile 依计划保持 `research`
 
 ## Agent 适配现状
 
 | agentId | driver | status | 说明 |
 |---|---|---|---|
 | `codex` | `spawn` | **ready** | 复用 `~/.codex` 登录态；`codex exec` 无头执行；M2 真实冒烟通过 |
-| `zcode` | `spawn` | **unsupported** | ZCode 桌面无随包 headless CLI（Z1 定论） |
+| `zcode` | `zcode-gui` | **research** | CDP GUI adapter 已实现且 Windows 真机闭环通过；macOS 真机完成前不标 `ready` |
 | `traework` | **`gui`** | **ready** | CDP 驱动 TRAE SOLO CN 桌面 UI；三种面板模式真机验证通过 |
 | `stub` | `spawn` | 仅测试 | `test/stub-agent/stub-agent.mjs` 三剧本（good/fix-on-first/never） |
 
@@ -247,7 +263,7 @@ run_task(projectPath=D:/xxx/my-app, agentId=traework, task=「切换到 Code 模
 | 文档 | 内容 |
 |---|---|
 | [HANDOFF.md](HANDOFF.md) | 项目交接文档：当前状态快照、架构导览、硬性红线、已知限制、接手建议 |
-| [CHANGELOG.md](CHANGELOG.md) | 版本变更日志（v0.1.0 → v0.1.10） |
+| [CHANGELOG.md](CHANGELOG.md) | 版本变更日志（v0.1.0 → v0.2.0） |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | 开发环境、工程规范、提交与发布流程、如何新增 agent |
 | [SECURITY.md](SECURITY.md) | 安全模型（凭证零管理/命令白名单/进程与桌面自动化边界）与私密报告渠道 |
 | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | 贡献者行为准则 |

package/dist/agents/adapter.d.ts

@@ -35,6 +35,18 @@ export interface TaskContext {
     model?: string;
     /** GUI 类 agent（traework）使用的面板模式；CLI 类忽略 */
     mode?: TraeworkMode;
+    /** needs_user / 返修时恢复原 GUI 会话。 */
+    resume?: {
+        kind: "continue" | "rework";
+        message?: string;
+        sendMessage: boolean;
+        sessionId?: string;
+        sessionTitle?: string;
+        boundProjectPath?: string;
+        provider?: string;
+        model?: string;
+        permissionMode?: string;
+    };
 }
 export interface SpawnInvocation {
     spec: Omit<SpawnSpec, "logFile" | "timeoutMs">;
@@ -56,6 +68,17 @@ export interface AgentRunResult {
     endReason?: string;
     /** GUI 实例是否因任务未真正完成而被保留 */
     keptInstance?: boolean;
+    needsUserKind?: "agent_question" | "close_existing_instance" | "login_required" | "system_permission";
+    pendingQuestion?: string;
+    session?: {
+        id?: string;
+        title?: string;
+        boundProjectPath?: string;
+        provider?: string;
+        model?: string;
+        permissionMode?: string;
+    };
+    progressSummary?: string;
 }
 /** parseExit: SpawnResult → AgentRunResult，按 agent 语义 */
 export type ParseExitFn = (res: {

package/dist/agents/builtin.js

@@ -13,17 +13,25 @@ export const BUILTIN_PROFILES = {
         killTree: "taskkill",
         authNote: "复用 ~/.codex 登录态（与桌面端同账号）；需本机已装 Codex 桌面端；勿与 --approve-for-me 同用（实测互斥）",
         executableDiscovery: {
-            dirs: ["{LOCALAPPDATA}/OpenAI/Codex/bin", "{USERPROFILE}/AppData/Local/OpenAI/Codex/bin", "/Applications/Codex.app/Contents/Resources/app/bin"],
+            dirs: [
+                "{LOCALAPPDATA}/OpenAI/Codex/bin",
+                "{USERPROFILE}/AppData/Local/OpenAI/Codex/bin",
+                "/Applications/Codex.app/Contents/Resources/app/bin",
+            ],
             fileNames: ["codex.exe", "codex"],
             fallbackCommand: "codex",
+            preferredDrives: [],
+            relativePaths: [],
         },
         note: "M2 真实冒烟已定稿（见 docs/m2-smoke-record.md）：--sandbox workspace-write 非交互通过",
     },
     zcode: {
         displayName: "Zcode (ZCode 桌面)",
         type: "cli",
-        driver: "spawn",
-        status: "unsupported",
+        driver: "gui",
+        adapter: "zcode-gui",
+        // macOS 真机证据完成前必须保持非 ready；research 仍允许已安装机器执行诊断/任务。
+        status: "research",
         command: null,
         argsTemplate: [],
         promptMode: "arg",
@@ -32,12 +40,46 @@ export const BUILTIN_PROFILES = {
         timeoutMs: 30 * 60_000,
         killTree: "taskkill",
         authNote: "复用本机 ZCode 登录态",
-        note: "Z1 实测（2026-09-07）：ZCode = Electron 桌面（D:/Z-Code/ZCode/ZCode.exe），无随包 headless agent-exec CLI，打包 tools 仅 cua-helper/ripgrep/ugrep → 无法无头 spawn → unsupported（详见 docs/adapter-matrix.md §Z1）",
+        executableDiscovery: {
+            dirs: [
+                "{ProgramFiles}/ZCode",
+                "{ProgramFiles(x86)}/ZCode",
+                "{LOCALAPPDATA}/Programs/ZCode",
+                "{LOCALAPPDATA}/ZCode",
+                "/Applications/ZCode.app/Contents/MacOS",
+                "{HOME}/Applications/ZCode.app/Contents/MacOS",
+            ],
+            fileNames: ["ZCode.exe", "ZCode"],
+            preferredDrives: ["D:"],
+            relativePaths: ["Z-Code/ZCode/ZCode.exe", "ZCode/ZCode.exe"],
+        },
+        gui: {
+            cdpPort: 9333,
+            cdpPortAuto: true,
+            cdpPortRange: 30,
+            exeArgs: ["--remote-debugging-port=<port>"],
+            windowMode: "reuse",
+            launchTimeoutMs: 60_000,
+            pollIntervalMs: 3_000,
+            stableRounds: 4,
+            idleTimeoutMs: 10 * 60_000,
+            cdpSendTimeoutMs: 15_000,
+            progressIntervalMs: 30_000,
+            modelSwitch: true,
+            modeSwitch: false,
+            freshSession: true,
+            selectors: {},
+            modelRequired: true,
+            defaultPermissionMode: "完全访问",
+            defaultAutoFixRounds: 2,
+        },
+        note: "ZCode Electron CDP GUI adapter。macOS 真机闭环证据完成前保持 research；已安装环境可探测和执行。",
     },
     traework: {
         displayName: "TraeWork (TRAE SOLO CN)",
         type: "cli",
         driver: "gui",
+        adapter: "traework-gui",
         status: "ready",
         command: null,
         argsTemplate: [],
@@ -60,6 +102,8 @@ export const BUILTIN_PROFILES = {
             ],
             fileNames: ["TRAE SOLO CN.exe", "TraeWork", "TraeWork CN", "Trae CN"],
             fallbackCommand: undefined,
+            preferredDrives: [],
+            relativePaths: [],
         },
         gui: {
             cdpPort: 9222,
@@ -77,6 +121,7 @@ export const BUILTIN_PROFILES = {
             modeSwitch: true,
             freshSession: true,
             selectors: {},
+            modelRequired: false,
         },
         note: "GUI 驱动（CDP）：T1 旧结论（无头 CLI 不存在）成立，但实测 --remote-debugging-port 可驱动聊天 UI（v1.107.1 已验证连接与关键选择器）。详见 docs/traework-cdp.md",
     },