tianshu-mcp 0.7.8 → 0.7.9

package/CHANGELOG.en.md

@@ -60,6 +60,50 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.7.9] - 2026-10-06
+
+### Fixed
+
+- **Dead link to `docs/agent-profiles.md` inside the npm package**: three places in the README (including
+  the top navigation "Agent Profiles" entry) point at that document, but it was missing from the
+  `package.json` `files` allowlist — users installing from npm hit a 404. Both `docs/agent-profiles.md`
+  and `.en.md` are now included. **This defect predates 0.7.8; it was not introduced by it.**
+
+### Docs
+
+- **Completed the documentation surface for the MiniMax Code adapter**: 0.7.8 shipped the full
+  `src/agents/minimax/` implementation and `docs/minimax-cdp.md`, but **the other documents that describe
+  agents were not synchronised** — this release fills in 4 files and 23 places:
+  - `README.md` / `README.en.md` (5 each): the agent banner, the `continue_task` resume-semantics list,
+    a new `minimax` row in the agent capability table, the `reasoningLevel` validation footnote, and the
+    version-history table.
+  - `docs/agent-profiles.md` / `.en.md` (4 each): the `adapter` enum comment, the `driver=gui` table's
+    agent list (**which had also been missing qoder / opendesign**), cross-document links, and a new
+    complete `minimax` profile example section.
+  - `skills/tianshu-mcp/SKILL.md` (35): the header `description` and `triggers` (**without which the skill
+    cannot be keyword-triggered**), the tool-surface `continue_task` support list, a new 8th column and a
+    `contextWindow` row in the §3.1 parameter matrix, a new minimax subsection in §3.2, the §3.3 platform
+    status, all six `needsUserKind` rows plus the anchor field in the §5 resume matrix, and minimax
+    semantics for six error codes in §9.
+  - `skills/tianshu-mcp/usage-examples.md` (9): a new §2.9 minimax example (including a **candidate table
+    for all four measured model shapes**), renumbering of the `codex-cli` section (**fixing a duplicate
+    `### 2.10` in the original**), a `contextWindow` row in the parameter-rejection table, and updates to
+    the `autoFixRounds` defaults and the session-anchor field table.
+
+  Every concrete assertion in these docs was **verified against the source** rather than recalled, and the
+  behavioural differences were exercised with a real probe:
+  `defaultAutoFixRounds=2` / `cdpPort=9999` / `permissionMode=始终授权` / the platform status check live in
+  `src/agents/minimax/profile.ts`; `contextWindow` is minimax-only per `src/mcp/handlers.ts:476`;
+  and **minimax is the only adapter that accepts `中`/`medium`** — it accepts `极高`/`最大` but
+  **rejects `关闭思考`** (confirmed by probe).
+
+### Changed
+
+- Version `0.7.8` → `0.7.9` (`package.json` and `src/version.generated.ts`).
+  This release contains **no logic changes** — documentation and the packaging allowlist only.
+
+---
+
 ## [0.7.8] - 2026-10-06
 
 ### Added

package/CHANGELOG.md

@@ -58,6 +58,42 @@
 
 ---
 
+## [0.7.9] - 2026-10-06
+
+### 修复
+
+- **npm 包内 `docs/agent-profiles.md` 死链**：README 有 3 处（含顶部导航「Agent 配置」）指向该文档，
+  但它不在 `package.json` 的 `files` 白名单里——从 npm 安装的用户点进去是 404。
+  已补 `docs/agent-profiles.md` 与 `.en.md`。**这是 0.7.8 之前就存在的缺陷，不是 0.7.8 引入的。**
+
+### 文档
+
+- **补全 MiniMax Code 适配的文档面**：0.7.8 发布了 `src/agents/minimax/` 全套实现与
+  `docs/minimax-cdp.md`，但**其它描述 agent 的文档面没同步**——本轮补齐 4 个文件共 23 处：
+  - `README.md` / `README.en.md`（各 5 处）：Agent 横幅、`continue_task` 恢复语义列表、
+    agent 能力表新增 `minimax` 行、`reasoningLevel` 校验规则脚注、版本线历史表。
+  - `docs/agent-profiles.md` / `.en.md`（各 4 处）：`adapter` 枚举注释、`driver=gui` 表格的
+    agent 列表（**此前连 qoder / opendesign 也漏了**）、文档互链、新增完整 `minimax` profile 示例段。
+  - `skills/tianshu-mcp/SKILL.md`（35 处）：头部 `description` 与 `triggers`（**否则关键词触发不到该技能**）、
+    工具面 `continue_task` 支持列表、§3.1 参数兼容矩阵新增第 8 列与 `contextWindow` 行、
+    §3.2 新增 minimax 小节、§3.3 平台状态、§5 恢复矩阵六类 `needsUserKind` 与锚点字段、
+    §9 六条错误码补 minimax 语义。
+  - `skills/tianshu-mcp/usage-examples.md`（9 处）：新增 §2.9 minimax 完整示例（含**四种模型形态的
+    候选对照表**）、`codex-cli` 小节顺延（**修掉原文重复的两个 `### 2.10`**）、参数拒绝表补 `contextWindow`、
+    `autoFixRounds` 缺省与会话锚点字段表。
+
+  文档里的具体断言均**回源码核验**而非凭记忆，并对其中的行为差异跑了实测：
+  `defaultAutoFixRounds=2` / `cdpPort=9999` / `permissionMode=始终授权` / 平台状态判定见
+  `src/agents/minimax/profile.ts`；`contextWindow` 仅 minimax 见 `src/mcp/handlers.ts:476`；
+  **minimax 是唯一接受 `中`/`medium` 的适配器**，接受 `极高`/`最大` 但**拒绝 `关闭思考`**（实测确认）。
+
+### 变更
+
+- 版本号 `0.7.8` → `0.7.9`（`package.json` 与 `src/version.generated.ts`）。
+  本版**无代码逻辑变更**，仅文档与打包白名单。
+
+---
+
 ## [0.7.8] - 2026-10-06
 
 ### 新增

package/README.en.md

@@ -63,7 +63,7 @@ Tianshu (TUI × GUI)              ← commander / user surface / verdict
               ↓  MCP over stdio (stdout carries JSON-RPC only)
         tianshu-mcp              ← scheduling · execution surface · acceptance gate
               ↓
-Codex · TraeWork · ZCode · Kimi Code · Qoder CN · Open Design
+Codex · TraeWork · ZCode · Kimi Code · Qoder CN · Open Design · MiniMax Code
               ↓ (GUI driven over CDP; CLI via child process)
         target project workspace ← git repo + tests + .tianshu-mcp/
 ```
@@ -227,7 +227,7 @@ run_task(projectPath=D:/xxx/my-app, task="…task brief…", agentId=codex,
 | Tool | Capability / approval | Purpose |
 |---|---|---|
 | `run_task` | write + approval | Dispatch work (optionally with auto-verify / auto-rework), returning a `taskId` asynchronously; optional `idempotencyKey`, `acceptanceOverride` and `dryRun` |
-| `continue_task` | write + approval | Resume a `needs_user` session (ZCode / Codex / Kimi Code / Qoder CN each have their own resume semantics) |
+| `continue_task` | write + approval | Resume a `needs_user` session (ZCode / Codex / Kimi Code / Qoder CN / MiniMax Code each have their own resume semantics) |
 | `query_task` | read | Poll status / progress / log tail / recent fine-grained events (optional `eventLimit`) |
 | `list_tasks` | read | Filtered list of historical tasks |
 | `get_task_report` | read | Full text of one round's acceptance report (`report.md`) |
@@ -256,9 +256,10 @@ run_task(projectPath=D:/xxx/my-app, task="…task brief…", agentId=codex,
 | `kimicode` | `gui` / `kimicode-gui` | **ready** (`research` on macOS) | Kimi Code desktop (Electron); **dual renderer processes** (main window plus a `Kimi Browser Overlay` that hosts the model / reasoning / mode menus); workspaces bind by full path; supports `model` / `reasoningLevel`, **not `mode`**, and **not project-less dispatch** |
 | `qoder` | `gui` / `qoder-gui` | closed-loop verified on Windows; **research** on macOS | Qoder CN only; requires an existing `projectPath` and a readable `planDoc`; `modelSource=default\|custom` disambiguates same-named models, and the reasoning level is saved as a global preference via "Model management" and read back |
 | `opendesign` | `gui` / `opendesign-gui` | **ready** (`research` on macOS) | Open Design desktop GUI; selectors are taken from the product's own web-frontend `data-testid` hooks, the full 12-step execution chain is wired, and the acceptance → auto-rework → re-acceptance loop is connected; it is the only driver with an "artifact signal" (file mtime / size fingerprint) |
+| `minimax` | `gui` / `minimax-gui` | **ready** (`research` on macOS) | MiniMax Code desktop (Electron); **dual renderer processes** (main window plus a `Model menu` popup); the reasoning level / context window live in a **second-level submenu that only appears on hovering a model row**, and their **candidate sets vary per model** (requesting them on a submenu-less model is fail-closed); supports `model` / `reasoningLevel` / **`contextWindow`** (this adapter only), **not `mode`**, and **not project-less dispatch**; "New project" takes **two steps: in-app modal → native `Select Directory` → modal submit** |
 | `stub` | `spawn` | tests only | `test/stub-agent/stub-agent.mjs` with three scripts (good / fix-on-first / never) |
 
-> `mode` supports `Work` / `Code` / `Design` (TraeWork only) and is inferred from the task text when omitted. Kimi Code's `reasoningLevel` is validated against the **set of levels actually rendered by the UI** (official models `low` / `high` / `max`; unofficial models only `on` / `off`). Adding an agent is usually just a profile — see [docs/agent-profiles.en.md](docs/agent-profiles.en.md) and [CONTRIBUTING.en.md](CONTRIBUTING.en.md).
+> `mode` supports `Work` / `Code` / `Design` (TraeWork only) and is inferred from the task text when omitted. Kimi Code's `reasoningLevel` is validated against the **set of levels actually rendered by the UI** (official models `low` / `high` / `max`; unofficial models only `on` / `off`). MiniMax Code's `reasoningLevel` / `contextWindow` are likewise validated against the **actual UI candidates** (e.g. `M3.1-Flash-Preview` offers `default`/`low`/`medium`/`high`/`xhigh`/`max` plus `512K`/`1M`, while `M3` has no level group and `deepseek-v4.1-flash` has no window group); an out-of-range or unreadable value is fail-closed. Adding an agent is usually just a profile — see [docs/agent-profiles.en.md](docs/agent-profiles.en.md) and [CONTRIBUTING.en.md](CONTRIBUTING.en.md).
 
 ### macOS headless path: codex-cli (user profile)
 
@@ -370,6 +371,7 @@ Allowing and disabling (a CLI flag or its equivalent environment variable; `--no
 | Visual and idempotency | 0.5.x | Visual acceptance (0.5.0) + optional AI content validation (0.5.4), ZCode project-less dispatch, Kimi Code / Qoder CN adapters, idempotency keys (0.5.10) |
 | Hardening and observability | 0.6.x | Skill self-install hardening (0.6.0), GUI selector drift fixes (0.6.2), fine-grained event stream, structured repair directives, dryRun, three-level acceptance config inheritance, terminal-state webhook |
 | Open Design | 0.7.x | Open Design desktop adapter (0.7.1), ZCode 3.14.x binding-contract fix (0.7.4) |
+| MiniMax Code | 0.7.8 | Seventh GUI agent (0.7.8); real-machine evidence corrected three structural assumptions (second-level submenu / per-model candidate sets / two-step project creation), plus the `contextWindow` parameter and a read-only diagnostic probe |
 | Log viewer GUI | `gui-v*` (separate line) | `mcp-gui/` local read-only log viewer (Tauri 2.x + Vue 3), independent version and tag, **not released with the MCP main package** |
 
 > The complete per-version record is in [CHANGELOG.en.md](CHANGELOG.en.md); handoff status and the troubleshooting handbook are in [HANDOFF.md](HANDOFF.md); engineering-metric definitions are in [ARCHITECTURE.en.md](ARCHITECTURE.en.md).

package/README.md

@@ -63,7 +63,7 @@
               ↓  MCP over stdio（stdout 仅承载 JSON-RPC）
         tianshu-mcp              ← 调度 · 执行面 · 验收仪
               ↓
-Codex · TraeWork · ZCode · Kimi Code · Qoder CN · Open Design
+Codex · TraeWork · ZCode · Kimi Code · Qoder CN · Open Design · MiniMax Code
               ↓（GUI 经 CDP 驱动桌面 UI；CLI 走子进程）
         目标项目工作区            ← git 仓库 + 测试 + .tianshu-mcp/
 ```
@@ -227,7 +227,7 @@ run_task(projectPath=D:/xxx/my-app, task="…任务书…", agentId=codex,
 | 工具 | 能力 / 审批 | 作用 |
 |---|---|---|
 | `run_task` | write + 审批 | 派活（可带自动验收 / 自动返修），异步返回 `taskId`；可选 `idempotencyKey`、`acceptanceOverride` 与 `dryRun` |
-| `continue_task` | write + 审批 | 恢复 `needs_user` 的原会话（ZCode / Codex / Kimi Code / Qoder CN 各有恢复语义） |
+| `continue_task` | write + 审批 | 恢复 `needs_user` 的原会话（ZCode / Codex / Kimi Code / Qoder CN / MiniMax Code 各有恢复语义） |
 | `query_task` | read | 轮询状态 / 进度 / 日志尾 / 最近细粒度事件（可选 `eventLimit`） |
 | `list_tasks` | read | 历史任务过滤列表 |
 | `get_task_report` | read | 某轮验收报告全文（`report.md`） |
@@ -256,9 +256,10 @@ run_task(projectPath=D:/xxx/my-app, task="…任务书…", agentId=codex,
 | `kimicode` | `gui` / `kimicode-gui` | **ready**（macOS 为 `research`） | Kimi Code 桌面端（Electron）；**双渲染进程**（主窗口 + `Kimi Browser Overlay` 浮层承载模型 / 档位 / 模式菜单）；工作区以完整路径绑定；支持 `model` / `reasoningLevel`，**不支持 `mode`**，且**不支持无项目派发** |
 | `qoder` | `gui` / `qoder-gui` | Windows 真机闭环通过；macOS **research** | 仅 Qoder CN；必须提供已有 `projectPath` 与可读 `planDoc`；`modelSource=default\|custom` 消除同名模型歧义，思考等级经「模型管理」保存为全局偏好并回读 |
 | `opendesign` | `gui` / `opendesign-gui` | **ready**（macOS 为 `research`） | Open Design 桌面端 GUI；选择器取自产品自身 Web 前端的 `data-testid` 钩子，12 步执行链全部接线，并接入验收 → 自动返修 → 再验收闭环；它是唯一带「产物信号」（文件 mtime / 大小指纹）的 driver |
+| `minimax` | `gui` / `minimax-gui` | **ready**（macOS 为 `research`） | MiniMax Code 桌面端（Electron）；**双渲染进程**（主窗口 + `Model menu` 弹层）；推理等级 / 上下文窗口在**悬停模型项展开的二级子菜单**里，且**候选集合随模型变化**（无子菜单的模型请求这两项即 fail-closed）；支持 `model` / `reasoningLevel` / **`contextWindow`**（本适配器专属），**不支持 `mode`**，且**不支持无项目派发**；「新建项目」为**应用内模态框 → 原生 `Select Directory` → 模态框提交**两步 |
 | `stub` | `spawn` | 仅测试 | `test/stub-agent/stub-agent.mjs` 三剧本（good / fix-on-first / never） |
 
-> `mode` 支持 `Work` / `Code` / `Design`（仅 TraeWork），不传时从任务书文本识别。Kimi Code 的 `reasoningLevel` 按**界面实际渲染的档位集合**校验（官方模型 `低` / `高` / `max`，非官方模型仅 `on` / `off`）。新增 agent 通常只需加一个 profile，详见 [docs/agent-profiles.md](docs/agent-profiles.md) 与 [CONTRIBUTING.md](CONTRIBUTING.md)。
+> `mode` 支持 `Work` / `Code` / `Design`（仅 TraeWork），不传时从任务书文本识别。Kimi Code 的 `reasoningLevel` 按**界面实际渲染的档位集合**校验（官方模型 `低` / `高` / `max`，非官方模型仅 `on` / `off`）。MiniMax Code 的 `reasoningLevel` / `contextWindow` 同样按**界面实际候选**校验（如 `M3.1-Flash-Preview` 为 `default`/`low`/`medium`/`high`/`xhigh`/`max` 与 `512K`/`1M`，而 `M3` 无档位组、`deepseek-v4.1-flash` 无窗口组），越权或读不到即 fail-closed。新增 agent 通常只需加一个 profile，详见 [docs/agent-profiles.md](docs/agent-profiles.md) 与 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
 ### macOS 无头路径：codex-cli（用户 profile）
 
@@ -370,6 +371,7 @@ run_task(projectPath=D:/xxx/my-app, task="…任务书…", agentId=codex,
 | 视觉与幂等 | 0.5.x | 视觉验收（0.5.0）+ 可选 AI 内容校验（0.5.4）、ZCode 无项目派发、Kimi Code / Qoder CN 适配、幂等键（0.5.10） |
 | 加固与可观测 | 0.6.x | 技能自装加固（0.6.0）、GUI 选择器漂移修复（0.6.2）、细粒度事件流、结构化修复指令、dryRun、验收配置三级继承、终态通知 |
 | Open Design | 0.7.x | Open Design 桌面端适配（0.7.1）、ZCode 3.14.x 绑定契约修复（0.7.4） |
+| MiniMax Code | 0.7.8 | 第七个 GUI agent 接入（0.7.8）；真机取证修正三处结构假设（二级子菜单 / 集合随模型变化 / 项目创建两步），新增 `contextWindow` 参数与只读诊断探针 |
 | 日志台 GUI | `gui-v*`（独立线） | `mcp-gui/` 本地只读日志台（Tauri 2.x + Vue 3），独立版本与 tag，**不随 MCP 主包发布** |
 
 > 完整逐版记录见 [CHANGELOG.md](CHANGELOG.md)，交接状态与排障手册见 [HANDOFF.md](HANDOFF.md)，工程质量口径见 [ARCHITECTURE.md](ARCHITECTURE.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.7.8";
+export const MCP_SERVER_VERSION = "0.7.9";

package/docs/agent-profiles.en.md

@@ -0,0 +1,443 @@
+# Agent Profiles & Dynamic Discovery (English summary)
+
+Full Chinese spec: [agent-profiles.md](agent-profiles.md). External AI-Agents plug in via **profiles** — declarative data in `~/.tianshu-mcp/agent-profiles.json` (env `TIANSHU_MCP_HOME` overrides). Adding an agent = one profile (no code change) unless custom output parsing is needed.
+
+## Merge order
+
+built-in (`src/agents/builtin.ts`) → user `agent-profiles.json` overrides by `id`.
+
+> Beyond profiles, server-level switches live in `<data home>/config.json`: `concurrency.maxRunning` (2),
+> `defaultTaskTimeoutMs`, `verifyCommandTimeoutMs`, `verifyConcurrency`, `skills.autoInstall`
+> (`true` \| `"prompt"` \| `false`), `skills.backupKeep` (default 3; historical skill backups kept after an
+> overwrite, `0` = never prune), and
+> **`shutdown.guiStopWaitMs` (15000)** — the **globally shared** bound for a GUI task's "best-effort stop click plus
+> bounded idle wait" when the server shuts down (issue #14). If it expires without a confirmation, the terminal message
+> states the stop is unconfirmed and sets `guiStopUnconfirmed`; it never claims the stop happened. Raising it improves
+> the confirmation rate at the cost of a slower exit. ZCode and TraeWork never click stop, so for them the outcome is
+> always "no stop result to confirm".
+
+## Fields
+
+```jsonc
+{
+  "profiles": {
+    "<agentId>": {
+      "displayName": "…",
+      "type": "cli",                 // only cli today
+      "driver": "spawn",             // spawn = external child process (default); gui = desktop UI automation
+      "adapter": "zcode-gui",        // GUI discriminator: traework-gui | zcode-gui | codex-gui | kimicode-gui | qoder-gui | opendesign-gui | minimax-gui; missing keeps legacy TraeWork behavior
+      "status": "ready",             // ready | research | unsupported
+      "command": null,               // absolute path; null + discovery = auto-probe
+      "argsTemplate": ["exec", "<prompt:arg>"],
+      "promptMode": "arg",           // arg | stdin | file
+      "cwd": "task",                 // task = project dir, home = os home
+      "env": {},
+      "timeoutMs": 1800000,
+      "killTree": "taskkill",        // legacy; platform is decided by code
+      "executableDiscovery": {
+        "dirs": ["{LOCALAPPDATA}/OpenAI/Codex/bin"],   // env placeholders, no hardcoded users
+        "fileNames": ["codex.exe", "codex"],
+        "fallbackCommand": "codex",
+        "preferredDrives": ["D:"],
+        "relativePaths": ["Z-Code/ZCode/ZCode.exe"]
+      },
+      "gui": {                       // only for driver="gui" (e.g. traework)
+        "cdpPort": 9222, "cdpPortAuto": true, "cdpPortRange": 20,
+        "exeArgs": ["--remote-debugging-port=<port>"], "windowMode": "reuse",
+        "launchTimeoutMs": 60000, "pollIntervalMs": 3000, "stableRounds": 12,
+        "idleTimeoutMs": 600000, "cdpSendTimeoutMs": 15000, "progressIntervalMs": 30000,
+        "modelSwitch": true, "modeSwitch": true, "freshSession": true, "selectors": {},
+        "modelRequired": false, "defaultPermissionMode": "Full Access", "defaultAutoFixRounds": 2
+      },
+      "opendesign": {                // only for adapter="opendesign-gui"; every field optional
+        "supportedVersions": { "win32": ["0.24.1"] }, // version gate (criterion = install config appVersion)
+        "directionLabels": { "prototype": "原型" },   // design direction → menu label (overridable for UI copy drift)
+        "planDir": ".opendesign/plans",               // repair-plan output dir (relative to the project root)
+        "workingDirPanelTimeoutMs": 15000, "nativeDialogTimeoutMs": 20000,
+        "modelMenuTimeoutMs": 15000, "designSystemTimeoutMs": 15000,
+        "designDirectionTimeoutMs": 15000, "sendReadyTimeoutMs": 20000
+      }
+    }
+  }
+}
+```
+
+## driver (execution surface)
+
+| value | meaning |
+|---|---|
+| `spawn` (default) | launches an external CLI child process (`argsTemplate` + `promptMode`); success is decided by exit code |
+| `gui` | drives a desktop UI over CDP (currently `traework` / `zcode` / `codex` / `kimicode` / `qoder` / `opendesign` / `minimax`); no child process, and `run_task` may pass `model` to pick its model |
+
+> With `driver=gui`, `argsTemplate`/`promptMode` are unused. An explicit `adapter` isolates each GUI implementation; a legacy profile without it keeps TraeWork behavior. See [traework-cdp.en.md](traework-cdp.en.md), [zcode-cdp.en.md](zcode-cdp.en.md), [codex-gui-cdp.en.md](codex-gui-cdp.en.md), [kimi-cdp.en.md](kimi-cdp.en.md), [qoder-cdp.en.md](qoder-cdp.en.md), [opendesign-cdp.en.md](opendesign-cdp.en.md) and [minimax-cdp.en.md](minimax-cdp.en.md).
+
+TraeWork liveness fields: `stableRounds` only confirms that the DOM is stable; `idle` is returned only after another
+`idleTimeoutMs` without changes or authoritative running signals. `cdpSendTimeoutMs` bounds one CDP command, while
+`progressIntervalMs` controls progress events visible through `query_task`. Idle, timeout, cancellation, and CDP loss
+retain the instance and expose `agentEndReason` / `keptInstance` in metadata.
+
+## Discovery semantics (R5)
+
+- `dirs` supports `{LOCALAPPDATA}` `{APPDATA}` `{HOME}` `{USERPROFILE}` `{PROGRAMFILES}` `{PROGRAMFILES(X86)}` `{SYSTEMDRIVE}` and `{XDG_DATA_HOME}` placeholders. Matching is case-insensitive, while docs and built-in profiles use uppercase consistently. Unknown or unavailable placeholders remain unchanged. Empty `dirs` falls back to platform-standard locations (via PATH/OS rules, no hardcoded user names).
+- Scanning only happens when `fileNames` is non-empty (avoids misclassifying arbitrary files).
+- Resolution order: explicit existing `command` → discovery dirs (newest mtime) → PATH fallback → failure message.
+
+## Prompt mode
+
+| mode | how prompt is passed |
+|---|---|
+| `arg` | inlined into `argsTemplate` replacing `<prompt:arg>` |
+| `stdin` | written to stdin |
+| `file` | prompt file written, `<prompt:file>` points to it |
+
+## Config hot reload (R5)
+
+`config.json`, `agent-profiles.json`, `projects.json` caches are invalidated by file mtime+size on each read; registry resolve cache is keyed to the profile object identity, so edits apply without a restart. Parse failures keep the last valid config and log a warning.
+
+## Status semantics
+
+`ready` means command/discovery is usable and its release evidence is complete. `research` means an implementation exists but hardware evidence is incomplete: `run_task` is allowed when installation discovery succeeds and otherwise fails with a diagnostic. `unsupported` means explicitly not drivable.
+
+> `traework` moved from `unsupported` to `ready` + `driver=gui` on 2026-09-08 (CDP-driven desktop UI; see [traework-cdp.en.md](traework-cdp.en.md)).
+
+> `zcode` uses `driver=gui` + `adapter=zcode-gui`. It requires `provider/model`, confirms Full Access, and defaults to two automatic repair rounds. The Windows hardware loop is complete; the built-in profile remains `research` until the macOS hardware loop is recorded.
+
+> `codex` uses `driver=gui` + `adapter=codex-gui` + `activation=msix-com`. Task parameters include `model` (**required**; take it from the panel, as names drift across versions — on 26.917 this machine listed e.g. `5.6 Terra`), `reasoningLevel` (低/中/高 or low/medium/high), `planDoc` and `designSystem`; it confirms Full Access and defaults to five automatic repair rounds. Machine-verified on Windows; the built-in macOS status is `research`. See [codex-gui-cdp.en.md](codex-gui-cdp.en.md).
+
+> `kimicode` uses `driver=gui` + `adapter=kimicode-gui` + `activation=spawn` (a plain Electron install, measured 1.0.2). `model` is required and takes the UI model name directly (e.g. `K3`, `K2.8 Preview`, `stepfun/step-3.7-flash:free`), and `mode` is **not supported**; the CDP base port is `9666` (advancing through `cdpPortRange` when `cdpPortAuto`), `launchTimeoutMs` is 90000, and the defaults are the "fully automatic" permission mode and two automatic repair rounds. Machine-verified on Windows (success path / unregistered-workspace import + auto-acceptance / failure → rework → re-acceptance same-session loop); macOS is `research` and fail-closed. See [kimi-cdp.en.md](kimi-cdp.en.md).
+
+> `qoder` uses `driver=gui` + `adapter=qoder-gui` (Qoder CN only). `projectPath` and a readable `planDoc` are mandatory; `modelSource` is optional (`default` / `custom`). The CDP base port is `9777` (advancing through `cdpPortRange` when `cdpPortAuto`), `launchTimeoutMs` is 90000, `stableRounds` is 2, and the default is three automatic repair rounds. Reasoning tiers are saved in Model Management as a **global preference** and read back; the permission mode is retained and "full access" is never enabled automatically. Machine-verified on Windows (default model in an existing workspace, custom model in a newly registered workspace, controlled failure → plan → same-session repair → re-acceptance); macOS is `research` and fail-closed. See [qoder-cdp.en.md](qoder-cdp.en.md).
+
+### `reasoningLevel` domain and applicable tiers
+
+Since v0.5.5 the `run_task.reasoningLevel` domain has grown, and v0.5.6 added the Qoder tiers:
+
+| Values | Meaning |
+|---|---|
+| `low` / `medium` / `high` (aliases: `低` / `中` / `高`) | The generic three tiers, used by Codex |
+| `max` / `on` / `off` | Kimi Code's UI tiers: official models use `Low` / `High` / `Max`, unofficial models only `On` / `Off` |
+| `xhigh` / `极高`, `最大`, `关闭思考` | Qoder CN tier aliases (`最大` / `关闭思考` reuse `max` / `off`); only `qoder-gui` accepts the aliases, and other adapters reject them |
+
+Per-agent applicability and semantics:
+
+| agent | Applicable tiers | Behaviour |
+|---|---|---|
+| `codex` | `low` / `medium` / `high` | When omitted, the Codex panel's current level is kept |
+| `kimicode` | official models `low` / `high` / `max`; unofficial models `on` / `off` | The tier set comes from **the tier labels the UI actually renders** (no built-in model list). When omitted, official tiers keep the UI's current value and unofficial tiers force `on`. Requesting a tier the UI does not render fails loudly with `model_mismatch` **before sending** and is never silently kept |
+| `qoder` | 低 / 中 / 高 / 极高 (`xhigh`) / 最大 (`max`) / 关闭思考 (`off`) | The available set comes from **the options the selected model actually renders in Model Management**. An unsupported tier fails **before sending**; silent downgrades are forbidden. When omitted, the UI's current value is kept and reported; after saving, the dialog is reopened for readback, and the change persists as a global preference |
+| `traework` / `zcode` / spawn agents | not applicable | Ignored, or rejected per that adapter's semantics |
+
+## Real-machine sample
+
+### Codex desktop (GUI driver, Windows-verified 2026-09-11)
+
+```jsonc
+{
+  "profiles": {
+    "codex": {
+      "displayName": "Codex (ChatGPT desktop GUI)",
+      "type": "cli",
+      "driver": "gui",
+      "adapter": "codex-gui",
+      "status": "ready",
+      "command": null, "argsTemplate": [], "promptMode": "arg", "cwd": "task",
+      "timeoutMs": 1800000, "killTree": "taskkill",
+      "authNote": "reuses ~/.codex (shared with any instance the user opened; the managed instance uses a dedicated user-data-dir)",
+      "executableDiscovery": {
+        // Appx query first (version-agnostic); scan fallback. No version numbers / absolute paths.
+        "appxPackageName": "OpenAI.Codex",
+        "installRelativeExe": ["app/ChatGPT.exe"],
+        "scanRoots": ["{SYSTEMDRIVE}/Program Files/WindowsApps"],
+        "scanPattern": "OpenAI.Codex_*_x64__*/app/ChatGPT.exe"
+      },
+      "gui": {
+        "activation": "msix-com",
+        "userDataDir": "{LOCALAPPDATA}/tianshu-mcp/codex-gui/profile",
+        "appxPackageName": "OpenAI.Codex",
+        "cdpPort": 9333, "cdpPortAuto": true,
+        "permissionMode": "完全访问",
+        "fixPlanDir": ".zcode/plans",
+        "defaultAutoFixRounds": 5,
+        "launchTimeoutMs": 60000, "pollIntervalMs": 3000,
+        "stableRounds": 4, "idleTimeoutMs": 600000,
+        "selectors": {}
+      }
+    }
+  }
+}
+```
+
+> **Essential**: `activation: "msix-com"` and `userDataDir` are both mandatory — the GUI host `ChatGPT.exe` cannot be launched directly (policy denies), and reusing the default profile means the debug port never opens. Details: [codex-gui-cdp.en.md](codex-gui-cdp.en.md).
+
+### Kimi Code (GUI driver, Windows-verified 2026-09-20)
+
+```jsonc
+// ~/.tianshu-mcp/agent-profiles.json (Windows sample; these are the built-in defaults)
+{
+  "profiles": {
+    "kimicode": {
+      "displayName": "Kimi Code (Kimi Code desktop)",
+      "type": "cli",
+      "driver": "gui",
+      "adapter": "kimicode-gui",
+      "status": "ready",                 // "research" on darwin (fail-closed)
+      "command": null,
+      "argsTemplate": [], "promptMode": "arg", "cwd": "task",
+      "timeoutMs": 1800000, "killTree": "taskkill",
+      "authNote": "reuses the local Kimi Code login; an existing instance without CDP must be closed by the user first",
+      "executableDiscovery": {
+        "dirs": [
+          "{PROGRAMFILES}/Kimi Code",
+          "{PROGRAMFILES(X86)}/Kimi Code",
+          "{LOCALAPPDATA}/Programs/Kimi Code",
+          "{LOCALAPPDATA}/Kimi Code",
+          "/Applications/Kimi Code.app/Contents/MacOS",
+          "{HOME}/Applications/Kimi Code.app/Contents/MacOS"
+        ],
+        "fileNames": ["Kimi Code.exe", "Kimi Code"],
+        "preferredDrives": ["D:"],
+        "relativePaths": [
+          "Kimi-Code/Kimi Code/Kimi Code.exe",
+          "Kimi Code/Kimi Code.exe",
+          "Kimi/Kimi Code/Kimi Code.exe",
+          "kimi-code/kimi code/kimi code.exe"
+        ]
+      },
+      "gui": {
+        "cdpPort": 9666,                 // CDP base port; falls through cdpPortRange when taken
+        "cdpPortAuto": true,
+        "cdpPortRange": 20,
+        "exeArgs": ["--remote-debugging-port=<port>"],
+        "windowMode": "reuse",
+        "launchTimeoutMs": 90000,        // cold-start first frame + render is measurably slow; widened to 90 s
+        "pollIntervalMs": 3000,
+        "stableRounds": 4,
+        "idleTimeoutMs": 600000,
+        "stallTimeoutMs": 300000,
+        "cancelWaitMs": 15000,
+        "cdpSendTimeoutMs": 15000,
+        "progressIntervalMs": 30000,
+        "modelSwitch": true,
+        "modeSwitch": false,             // the mode parameter is not supported
+        "freshSession": true,
+        "modelRequired": true,
+        "activation": "spawn",           // plain Electron install: launch directly (no MSIX COM)
+        "permissionMode": "完全自动",
+        "defaultPermissionMode": "完全自动",
+        "defaultAutoFixRounds": 2,
+        "workspaceTriggerTimeoutMs": 15000, // optional: cap for waiting on ws-chip mounting (draft-page criterion)
+        "selectors": {}
+      }
+    }
+  }
+}
+```
+
+> **Essential**: Kimi Code is a **plain Electron install** (measured 1.0.2); injecting `--remote-debugging-port` is enough and **no** MSIX COM activation is needed.
+> **Two renderer processes**: the model / thinking-tier / execution-mode menus render in the `Kimi Browser Overlay` window, while the workspace menu and the "switch model" dialog stay in the main window.
+> Tasks are organised by **workspace** (task folder) and **project-less dispatch is not supported**: `projectPath` is mandatory, and an unregistered workspace is imported through the native "add workspace" dialog.
+> The default permission is "fully automatic" and the default is two automatic repair rounds. Details: [kimi-cdp.en.md](kimi-cdp.en.md).
+
+### Qoder CN (GUI driver, Windows-verified 2026-09-22)
+
+```jsonc
+// ~/.tianshu-mcp/agent-profiles.json (Windows sample; these are the built-in defaults)
+{
+  "profiles": {
+    "qoder": {
+      "displayName": "Qoder CN",
+      "type": "cli",
+      "driver": "gui",
+      "adapter": "qoder-gui",
+      "status": "ready",                 // "research" on darwin (fail-closed, dispatch disabled)
+      "command": null,
+      "argsTemplate": [], "promptMode": "arg", "cwd": "task",
+      "authNote": "reuses the local Qoder CN login; an existing instance that cannot be connected is handled by the user and never restarted automatically",
+      "executableDiscovery": {
+        "preferredDrives": ["D:"],
+        "relativePaths": ["Qoder CN/Qoder CN.exe", "Program Files/Qoder CN/Qoder CN.exe"],
+        "fileNames": ["Qoder CN.exe"],   // ["Qoder CN"] on macOS
+        "dirs": [
+          "{LOCALAPPDATA}/Programs/Qoder CN",
+          "{PROGRAMFILES}/Qoder CN",
+          "{PROGRAMFILES(X86)}/Qoder CN"
+        ]
+      },
+      "gui": {
+        "cdpPort": 9777,                 // CDP base port; falls through cdpPortRange when taken
+        "cdpPortRange": 20,
+        "launchTimeoutMs": 90000,
+        "cdpSendTimeoutMs": 30000,
+        "stableRounds": 2,
+        "defaultAutoFixRounds": 3,
+        "modeSwitch": false,             // the mode parameter is not supported
+        "modelRequired": false,          // model and tier may be omitted and the UI's current values are kept
+        "selectors": {}
+      }
+    }
+  }
+}
+```
+
+> **Essential**: `projectPath` and `planDoc` are mandatory; `modelSource` is optional and only needed to disambiguate identical names across the default/custom groups.
+> An invalid explicit `gui.exePath` fails loudly instead of silently falling back to another installation; an existing instance without usable CDP is preserved in place and turned into `needs_user` — it is never closed or restarted. An unregistered directory is imported through New Task → Workspace → New Workspace → Add Read/Write Folder.
+> Thinking tiers are saved in Model Management as a **global preference** (not restored afterwards) and the permission mode is retained. Details: [qoder-cdp.en.md](qoder-cdp.en.md).
+
+### Open Design (GUI driver, UI wiring complete; Windows machine-verified, macOS `research`)
+
+```json
+{
+  "profiles": {
+    "opendesign": {
+      "displayName": "Open Design (Open Design desktop)",
+      "driver": "gui",
+      "adapter": "opendesign-gui",
+      "status": "ready",                 // research on macOS (fail-closed, dispatch refused)
+      "executableDiscovery": {
+        "preferredDrives": ["D:"],
+        "relativePaths": ["Open Design/Open Design.exe"],
+        "fileNames": ["Open Design.exe"], // ["Open Design"] on macOS
+        "dirs": [
+          "{PROGRAMFILES}/Open Design",
+          "{LOCALAPPDATA}/Programs/Open Design",
+          "{LOCALAPPDATA}/Open Design"
+        ]
+      },
+      "gui": {
+        "cdpPort": 9889,                 // base port; 9777 is taken by Qoder CN, 9889-9898 does not overlap
+        "cdpPortRange": 10,
+        "exeArgs": ["--remote-debugging-port=<port>"],
+        "launchTimeoutMs": 90000,
+        "modelSwitch": true,
+        "modelRequired": true
+      },
+      "opendesign": {
+        "supportedVersions": { "win32": ["0.24.1"] },
+        "directionLabels": { "prototype": "原型", "document": "文档", "clone": "网站复刻" },
+        "planDir": ".opendesign/plans"   // repair plans go to the project root (Open Design can only read inside its working directory)
+      }
+    }
+  }
+}
+```
+
+> **Essential** (each point maps to a real-machine lesson; see [opendesign-cdp.en.md](opendesign-cdp.en.md)):
+> - **`gui.userDataDir` is intentionally unset**: the product's main process forces `app.setPath("userData", …)`,
+>   so that switch **is overridden** — writing it into the profile would be a false promise.
+> - **`exeArgs` only injects the debug port**: the command line shape stays the same, but **managed launches
+>   sanitise the environment** (dropping `ELECTRON_RUN_AS_NODE` and friends); otherwise the outer launcher
+>   degrades to Node mode and rejects `--remote-debugging-port` outright.
+> - **`supportedVersions` is the version gate**: the criterion is `appVersion` from
+>   `<install dir>/resources/open-design-config.json`, **not** CDP `/json/version`'s `Browser` (that is the
+>   Electron version).
+> - **Design direction uses the `designDirection` parameter** (not `mode`): only Prototype / Document /
+>   Website clone are supported; other UI directions (Slides / Image / HyperFrames) are rejected at the
+>   **entry point**.
+> - **`designSystem` means a design-system name** (e.g. `Claude`), which the adapter searches for and clicks
+>   in the design-system panel.
+> - An existing instance without a debug port yields `needs_user(close_existing_instance)`; user processes are
+>   **never** killed.
+>
+> **The UI driver is now wired up**: every `primary` in `selectors.ts` has landed, with evidence drawn from the
+> **product's own web-frontend artifacts** (the `data-testid` hooks inside
+> `resources/open-design-web-standalone/apps/web/.next/static/chunks/*.js`), **not from eyeballing screenshots**;
+> the 12-step execution chain after handshake (takeover → connect the main window → version gate → layout guard →
+> bind the working directory → model → design system → design direction → type the task → send → three-signal polling →
+> terminal state) and the acceptance/rework loop are all connected.
+> Windows machine-verified; macOS remains `research` (no machine evidence, so the registry refuses dispatch).
+> Still fail-closed: on selector drift, dispatching **hard-fails with `selector_drift`** listing the missing keys — it never clicks blindly.
+> `gui.selectors` supports **hot overrides keyed by semantic name** (a minor UI change needs no release).
+
+### MiniMax Code (GUI driver, Windows machine-verified; macOS `research`)
+
+```json
+{
+  "profiles": {
+    "minimax": {
+      "displayName": "MiniMax Code",
+      "driver": "gui",
+      "adapter": "minimax-gui",
+      "status": "ready",                 // `research` on macOS (fail-closed, dispatch refused)
+      "executableDiscovery": {
+        "preferredDrives": ["D:"],
+        "relativePaths": [
+          "MiniMax-Code/MiniMax Code/MiniMax Code.exe",   // measured install layout
+          "MiniMax Code/MiniMax Code.exe"
+        ],
+        "fileNames": ["MiniMax Code.exe"],               // ["MiniMax Code"] on macOS
+        "dirs": [
+          "{PROGRAMFILES}/MiniMax Code",
+          "{LOCALAPPDATA}/Programs/MiniMax Code",
+          "{LOCALAPPDATA}/MiniMax Code"
+        ]
+      },
+      "gui": {
+        "cdpPort": 9999,                 // base port; 9222/9333/9666/9777/9889 are taken by the other agents
+        "cdpPortRange": 10,
+        "exeArgs": ["--remote-debugging-port=<port>"],
+        "launchTimeoutMs": 120000,
+        "modelSwitch": true,
+        "modelRequired": true,
+        "permissionMode": "始终授权",
+        "defaultPermissionMode": "始终授权",
+        "fixPlanDir": ".minimax/plans",
+        "defaultAutoFixRounds": 2
+      },
+      "minimax": {                        // only for adapter="minimax-gui"; every field optional
+        "submenuOpenTimeoutMs": 8000,     // budget for the second-level submenu after hovering a model row
+        "modelMenuTimeoutMs": 10000,
+        "sendReadyTimeoutMs": 20000,
+        "levelLabels": {},                // tier token -> UI label (absorbs wording drift)
+        "planDir": ".minimax/plans"
+      }
+    }
+  }
+}
+```
+
+> **Key points**: `projectPath` is mandatory (**project-less dispatch is not supported**); `model` is mandatory;
+> `reasoningLevel` accepts `default` / `低·low` / `中·medium` / `高·high` / `极高·xhigh` / `最大·max`; `contextWindow`
+> (e.g. `512K` / `1M`) is a parameter **specific to this adapter** — passing it for any other agent is an error.
+> The model popup renders in a **separate renderer process** (`Model menu`), and the reasoning level / context window
+> live in a **second-level submenu that only appears on hovering a model row**, with **candidate sets that vary per model** —
+> requesting either on a submenu-less model is fail-closed and never silently keeps the UI current value.
+> "New project" takes **two steps**: the in-app "Create project" modal → "Choose folder" opens the native
+> `Select Directory` → the modal submit.
+> Read-only diagnostic probe: `npm run probe:minimax`. Details: [minimax-cdp.en.md](minimax-cdp.en.md).
+
+### Historical: Codex kernel CLI (`codex exec`, superseded by the GUI driver)
+
+```jsonc
+{
+  "profiles": {
+    "codex": {
+      "displayName": "Codex (desktop CLI)",
+      "type": "cli", "status": "ready", "promptMode": "arg", "cwd": "task",
+      "command": "C:/Users/<you>/AppData/Local/OpenAI/Codex/bin/<hash>/codex.exe",
+      "argsTemplate": ["exec", "<prompt:arg>", "--skip-git-repo-check", "--sandbox", "workspace-write"],
+      "timeoutMs": 1800000, "killTree": "taskkill",
+      "executableDiscovery": {
+        "dirs": ["{LOCALAPPDATA}/OpenAI/Codex/bin"],
+        "fileNames": ["codex.exe", "codex"], "fallbackCommand": "codex"
+      }
+    }
+  }
+}
+```
+
+> Kept as a historical record; this path is no longer the built-in default.
+
+## ZCode / Kimi Code automatic initialization recovery
+
+Override these `gui` fields in the data-home `agent-profiles.json`. Older profiles inherit the defaults; other drivers do not use these recovery settings.
+
+| Field | Default | Meaning |
+|---|---:|---|
+| `setupRecoveryTimeoutMs` | 120000 | Total initialization-through-binding budget in milliseconds |
+| `projectTriggerTimeoutMs` | 15000 | Cap for waiting on the ZCode project trigger to become ready (also the budget for confirming the menu opens after a click) |
+| `workspaceTriggerTimeoutMs` | 15000 | **Optional** (Kimi Code only): cap for waiting on the workspace trigger (`button.ws-chip`) to mount, i.e. the criterion for "the draft page really exists". ZCode does not use this field. It is deliberately optional rather than defaulted so that existing profile literals need not change |
+| `dialogProbeTimeoutMs` | 30000 | One native dialog observation, milliseconds |
+| `dialogOperationTimeoutMs` | 60000 | One folder operation, milliseconds |
+| `setupRecoveryMaxRetries` | 2 | Additional attempts for safely retryable stages (0–10) |
+
+Each wait uses the minimum of its configured cap, remaining setup time and remaining task time. Retries never reset the deadline. After binding, only the task deadline applies. Initialization progress uses `progressIntervalMs`.