tianshu-mcp 0.1.9 → 0.2.0

package/CHANGELOG.en.md

@@ -18,6 +18,64 @@ 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
+
+- **Fixed stdio log pollution (issue #1)**: the unified logger previously sent only ERROR to
+  `console.error` while INFO/WARN/DEBUG went to `console.log`, sharing stdout with MCP JSON-RPC
+  messages and breaking handshakes or tool calls in strict stdio clients. All levels passing the
+  threshold now go to stderr, leaving stdout for valid MCP messages only.
+- Log file appending, timestamps, level tags and the `<data dir>/logs/server.log` path are unchanged;
+  a startup failure is still reported on stderr.
+
+### Added
+
+- New `scripts/check-stdio.mjs` strict stdio smoke: a real child process validates the complete
+  stdout/stderr byte stream, allowing only newline-delimited, schema-valid MCP JSON-RPC messages on
+  stdout; empty lines, non-JSON lines, parser errors, or trailing fragments at exit fail the run.
+  It covers six scenarios: first start, second start with matching skills, `--no-skill-install`,
+  a corrupt `config.json`, logs during a stub task, and clean EOF shutdown.
+- New `npm run check:stdio` and `npm run check:stdio:src` scripts.
+
+### Tests
+
+- New `test/unit/log.test.ts`: real-child-process checks for the four log levels' channels, default
+  INFO filtering, threshold-filtered file logging, and UTF-8 content (4/6 failed before the fix; see
+  `docs/m2-evidence/issue1-old-impl-log-test-failure.txt`).
+- CI's three-platform matrix now includes Node 24; the build step runs the strict stdio check instead
+  of an EOF-exit-only smoke.
+- CI `pack-check` and Release install the freshly built tarball into a clean consumer directory, read
+  the installed bin dynamically, and reuse the same strict stdio check; Release adds `lint` and the
+  installed-package protocol gate, failing before a draft is created.
+- ESLint enables `no-console` (allowing `error` only) for `src/**/*.ts` to prevent new direct stdout writes.
+
+---
+
 ## [0.1.9] — 2026-09-09
 
 ### Fixed

package/CHANGELOG.md

@@ -17,6 +17,58 @@
 
 ---
 
+## [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
+
+### 修复
+
+- **修复 stdio 日志污染（issue #1）**：统一日志模块此前只有 ERROR 走 `console.error`，
+  INFO/WARN/DEBUG 都走 `console.log`，与 MCP JSON-RPC 消息共用 stdout，导致严格 stdio 客户端
+  握手或工具调用失败。现在所有通过阈值的级别一律写 stderr，stdout 只承载合法 MCP 消息。
+- 日志文件追加、时间戳、级别标签与 `<数据目录>/logs/server.log` 路径保持不变；启动失败仍以 stderr 报错。
+
+### 新增
+
+- 新增 `scripts/check-stdio.mjs` 严格 stdio 冒烟：真实子进程按字节校验完整 stdout/stderr，
+  stdout 只允许有换行分隔的合法 MCP JSON-RPC 消息（官方 schema 校验），空行 / 非 JSON / parser error /
+  退出残留片段任意一条即失败。覆盖首次启动、已有技能再次启动、`--no-skill-install`、
+  损坏 `config.json`、stub 任务运行期日志、正常 EOF 关闭六个场景。
+- 新增 `npm run check:stdio` 与 `npm run check:stdio:src` 脚本。
+
+### 测试
+
+- 新增 `test/unit/log.test.ts`：以真实子进程验证四级日志的输出通道、默认 INFO 过滤、阈值过滤后的
+  文件日志与 UTF-8 内容（修复前 4/6 失败，见 `docs/m2-evidence/issue1-old-impl-log-test-failure.txt`）。
+- CI 三平台矩阵增加 Node 24；构建后用严格 stdio 检查替换仅验证 EOF 退出的冒烟。
+- CI `pack-check` 与 Release 把本次 tarball 安装到干净消费者目录，动态读取已安装 bin 并复用同一严格
+  stdio 检查；Release 增加 `lint` 与安装包协议门禁，失败即阻断草稿创建。
+- ESLint 对 `src/**/*.ts` 启用 `no-console`（仅允许 `error`），防止再次向 stdout 直接输出。
+
+---
+
 ## [0.1.9] — 2026-09-09
 
 ### 修复

package/README.en.md

@@ -34,21 +34,44 @@ 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.
 
 ## Quick start
 
+### Prerequisites
+
+| Item | Requirement |
+|---|---|
+| 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 |
+
+The data directory defaults to `~/.tianshu-mcp` and can be overridden with the `TIANSHU_MCP_HOME` environment variable; it is created automatically on first start.
+
+### Build from source
+
 ```bash
-npm install
-npm run build        # → dist/
-npm test             # 181 tests: unit + stub-agent 3-playbook integration + protocol + TraeWork fake-CDP + cancel/timeout/baseline/params/config regression
+git clone https://github.com/lanlan0811/tianshu-mcp.git
+cd tianshu-mcp
+npm ci
+npm run build        # sync-version + tsc → dist/
+npm test             # 262 tests across 37 files, including ZCode unit/fake-CDP/restart/repair coverage
+```
+
+### Install the npm package
+
+```bash
+npx -y tianshu-mcp            # run without installing
+# or
+npm install -g tianshu-mcp
 ```
 
 ### Add it in Tianshu (recommended)
@@ -63,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)
 
@@ -86,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)
@@ -103,6 +126,43 @@ 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.
 
+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`) |
+| `cancel_task` | write + approval | Cancel a running task (kill process tree) |
+| `verify_task` | read | Run one verification pass on a task/project path (no source changes) |
+| `rework_task` | write + approval | Manual rework (feed the failure report back to the same agent) |
+| `get_profiles` | read | Inspect agent adapters and executable discovery results |
+
+> Every result is "human-readable text + a `---tianshu-mcp-meta---` JSON block" so the host can extract it with a regex.
+
+## Logging & stdio contract
+
+This server is a standard MCP **stdio server** and follows the transport contract strictly:
+
+- **stdout carries MCP JSON-RPC messages only.** No diagnostic log is ever written to stdout — doing so corrupts the JSON-RPC stream and makes strict clients fail to handshake or call tools.
+- **All log levels (DEBUG/INFO/WARN/ERROR) go to stderr** and are appended to `logs/server.log` under the data directory (UTF-8, ISO timestamp, with a level tag).
+- Therefore **an `INFO`/`WARN` line on stderr does not mean the server failed**; it is normal diagnostics. Only a startup failure (`tianshu-mcp 启动失败:`) is fatal, and it exits with a non-zero code.
+
+The data directory defaults to `~/.tianshu-mcp` (override with `TIANSHU_MCP_HOME`); the log file lives at `<data dir>/logs/server.log`.
+
+Use `server.log` when troubleshooting connections; do not treat stderr output itself as a server fault.
+
 ## Documentation
 
 | Doc | Content |
@@ -111,27 +171,38 @@ run_task(projectPath=D:/xxx/my-app, agentId=traework, task=「Switch to Code mod
 | [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) |
 | [docs/release-v0.1.8.en.md](docs/release-v0.1.8.en.md) | v0.1.8 release notes (atomic-write concurrency fix) |
 | [docs/release-v0.1.7.en.md](docs/release-v0.1.7.en.md) | v0.1.7 release notes (binding root cause: native path) |
 | [docs/release-v0.1.6.en.md](docs/release-v0.1.6.en.md) | v0.1.6 release notes (project-folder binding fix) |
 | [docs/release-v0.1.5.en.md](docs/release-v0.1.5.en.md) | v0.1.5 release notes (mode switching, README/icon, release artifacts) |
+| [skills/tianshu-mcp/SKILL.md](skills/tianshu-mcp/SKILL.md) | Skill that teaches Tianshu how to orchestrate this MCP (with usage examples) |
 
 > Chinese documentation: see [README.md](README.md).
+> Some milestone/evidence records are **Chinese-only** (no English translation yet): [HANDOFF.md](HANDOFF.md),
+> [docs/npm-publish-guide.md](docs/npm-publish-guide.md), [docs/m2-smoke-record.md](docs/m2-smoke-record.md),
+> [docs/m2-rework-record.md](docs/m2-rework-record.md), [docs/host-integration-record.md](docs/host-integration-record.md),
+> [docs/dod7-release-record.md](docs/dod7-release-record.md), [docs/dod8-session-record.md](docs/dod8-session-record.md),
+> [docs/s7-session-recheck.md](docs/s7-session-recheck.md).
 
 ## Milestone status
 
 - **M1 — Core engine + stub-agent end-to-end** ✅
   - 8 tools, TaskManager state machine / queue / concurrency gate / cancel (kill tree) / event-stream persistence
   - Acceptance engine (git baseline & diff, default-set derivation, command runner, code analysis, report.md/json)
-  - fix-loop auto rework + needs_attention; skill self-install
-  - Stub-agent 3 playbooks (good / fix-on-first / never) integration tests + protocol tests — **72/72 green** (incl. R1–R5/S1–S6 cancel/timeout/baseline/params/config regressions)
+  - fix-loop auto rework + needs_attention; skill self-install (verified on this machine's real `~/.rivet/skills`)
+  - Stub-agent 3 playbooks (good / fix-on-first / never) integration tests + protocol tests
 - **M2 — Real Codex CLI smoke + rework loop** ✅ (2026-09-07)
   - Real `codex exec` completed `run_task → query_task → verify_task`
   - Real **failure → rework_task → re-verify succeeded** loop, with artifacts
   - Fixed 3 real bugs the smoke exposed (Windows npm shim / spawn log race crash / codex flag conflict) + regression tests
   - Zcode headless entry (Z1) verified: ZCode desktop ships no headless CLI → unsupported
+- **R1–R8 / S1–S6 — two acceptance hardening rounds** ✅ (cancel / timeout / baseline attribution / parameter semantics / hot reload / CI hardening) — **72 tests**
 - **Engineering / CI** ✅
   - GitHub Actions: `CI` (ubuntu/windows/macos × Node 20/22 + tarball check, **7/7 green**) and `Release` (tag-triggered) both green
   - Skill self-install verified idempotent on this machine's real `~/.rivet/skills/tianshu-mcp`
@@ -142,19 +213,43 @@ run_task(projectPath=D:/xxx/my-app, agentId=traework, task=「Switch to Code mod
 - **M3 — TraeWork research + full delivery** ✅ (2026-09-07, **npm published**)
   - T1 settled: local TRAE SOLO CN v1.107.1 verified to have **no headless programmable agent interface** (VS Code-family CLI only)
   - npm published from `tianshu-mcp@0.1.1` (`npx -y tianshu-mcp` raises and connects 8 tools)
-- **M4 — TraeWork GUI driver (CDP)** ✅ (2026-09-08, see [traework-cdp.en.md](docs/traework-cdp.en.md))
+- **M4 — TraeWork GUI driver (CDP)** ✅ (2026-09-08, see [traework-cdp.en.md](docs/traework-cdp.en.md)) — **153 tests**
   - Correction: no headless CLI exists, but `--remote-debugging-port` can drive the chat UI; `traework` is now `driver=gui` / `status=ready`
   - Capabilities: launch/reuse instance → new session → bind project folder (dropdown first, restricted computer-use native dialog as fallback) → optional model selection → read-back-verified send → poll to completion → auto-verify → repair-plan file + same-session rework on failure
   - Safety: reuse the user's instance by default, never kill a process tree, verify the command line before terminating; computer-use is limited to TraeWork's folder picker
   - Machine-verified: `run_task(agentId=traework, model=GLM-5.3, autoVerify=true)` drove TraeWork to create a file and passed acceptance
-- **M5 — Mode switching + v0.1.5 release** ✅ (2026-09-08, see [release-v0.1.5.en.md](docs/release-v0.1.5.en.md))
+- **M5 — Mode switching + v0.1.5 release** ✅ (2026-09-08, see [release-v0.1.5.en.md](docs/release-v0.1.5.en.md)) — **167 tests**
   - `run_task` gained `mode` (Work/Code/Design), explicit parameter plus task-text fallback; all three modes **machine-verified end-to-end**
   - Key finding: the three modes keep independent project bindings → order is new session → switch mode → bind project inside that mode
-  - README rewritten (bilingual + stack badges + dedicated SVG icon/banner); tests 153 → **167**
-
-- **M6 — Project-folder binding fix + v0.1.6** ✅ (2026-09-08, see [release-v0.1.6.en.md](docs/release-v0.1.6.en.md))
+  - README rewritten (bilingual + stack badges + dedicated SVG icon/banner)
+- **M6 — Project-folder binding fix + v0.1.6** ✅ (2026-09-08, see [release-v0.1.6.en.md](docs/release-v0.1.6.en.md)) — **172 tests**
   - Fixed three stacked defects: footer click never verified the popup, detection budget eaten by PowerShell cold start, CJK paths destroyed by the console code page
-  - Added a Work fallback for non-Work binding; machine-verified "new project absent from the dropdown + mode=Code" end-to-end; tests 167 → **172**
+  - Added a Work fallback for non-Work binding; machine-verified "new project absent from the dropdown + mode=Code" end-to-end
+- **M7 — Binding root-cause fix + v0.1.7** ✅ (2026-09-08, see [release-v0.1.7.en.md](docs/release-v0.1.7.en.md)) — **178 tests**
+  - Root cause: MCP passed a normalized path (`d:/a/b`) that the Windows native picker rejects → switched to `toNativeWindowsPath()` (`D:\a\b`)
+  - Supporting fixes: `WM_GETTEXT` read-back verification after writing, hwnd threaded through the flow, stale-dialog cleanup
+- **M8 — Atomic-write concurrency fix + v0.1.8** ✅ (2026-09-08, see [release-v0.1.8.en.md](docs/release-v0.1.8.en.md)) — **181 tests**
+  - `writeJsonAtomic` / `writeTextAtomic` shared a temp filename under concurrency → randomized suffix + rename back-off retry (the real root cause of flaky CI windows/Node20 failures)
+- **M9 — TraeWork task liveness detection + v0.1.9** ✅ (2026-09-09, see [release-v0.1.9.en.md](docs/release-v0.1.9.en.md)) — **196 tests**
+  - The stop button / loading task tail became authoritative running signals that outrank the completion mark; stable rounds only start the idle timer (default 10 minutes) before returning `idle`
+  - CDP disconnects reject all pending requests + a 15s per-command timeout; abnormal endings (idle/timeout/aborted/cdp_lost) keep the instance and record `agentEndReason` / `keptInstance`
+- **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` | `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) |
+
+> Adding an agent usually needs only a profile — see [docs/agent-profiles.en.md](docs/agent-profiles.en.md) and [CONTRIBUTING.en.md](CONTRIBUTING.en.md).
 
 ## Recommended phrasing (for Tianshu)
 
@@ -166,14 +261,58 @@ run_task(projectPath=D:/xxx/my-app, agentId=traework, task=「Switch to Code mod
 
 | Document | Content |
 |---|---|
-| [CHANGELOG.en.md](CHANGELOG.en.md) | Version history (v0.1.0 → v0.1.5) |
+| [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 |
-| [LICENSE](LICENSE) | Apache License 2.0 |
+| [LICENSE](LICENSE) | Apache License 2.0 (detailed explanation below) |
+
+- **Primary repository**: <https://github.com/lanlan0811/tianshu-mcp> (GitHub)
+- **Mirror repository**: <https://gitee.com/lan0811/tianshu-mcp> (Gitee)
+- **Feedback**: bugs / feature requests via the repo Issue templates; report security vulnerabilities privately per [SECURITY.en.md](SECURITY.en.md) — **do not** open a public issue.
 
-> Chinese counterparts: see [README.md](README.md).
+> Chinese counterparts: see [README.md](README.md). The handoff document [HANDOFF.md](HANDOFF.md) is Chinese-only.
 
 ## License
 
-[Apache-2.0](LICENSE)
+This project is released under the **Apache License 2.0**; the full legal text is in [LICENSE](LICENSE). Copyright belongs to the tianshu-mcp contributors (Copyright 2026 tianshu-mcp contributors).
+
+### Rights granted to you
+
+- **Commercial use**: use it in commercial products and services;
+- **Modification**: modify the source freely;
+- **Distribution**: redistribute the original or modified versions;
+- **Private use**: use it privately inside your organization;
+- **Patent use**: contributors grant you a license to any patents covered by their contributions (subject to the termination clause below).
+
+### Obligations you must meet
+
+1. **Keep the notices**: when distributing, include the full LICENSE text and retain its copyright, license, and disclaimer notices;
+2. **Mark modifications**: if you modify files, carry a prominent "modified" notice in the changed files;
+3. **Preserve NOTICE**: if the original work includes a NOTICE file, retain its contents when distributing (this project currently has **no** NOTICE file);
+4. **No additional restrictions**: you may not impose further restrictions on the rights granted by this license.
+
+### Not granted / termination
+
+- **Trademarks**: this license does **not** grant any right to use trademarks, trade names, or service marks;
+- **Patent termination**: if you institute patent litigation against this project or its contributors (including cross-claims and counter-claims), your patent grant under this license **terminates automatically**.
+
+### Disclaimer
+
+The software is provided **"AS IS"**, without warranties or conditions of any kind, either express or implied, including but not limited to the implied warranties of merchantability, fitness for a particular purpose, and non-infringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability arising from, out of, or in connection with the software or the use or other dealings in the software, whether in an action of contract, tort, or otherwise.
+
+### Third-party dependency licenses
+
+Runtime dependencies are all **MIT**-licensed and compatible with Apache-2.0:
+
+| Dependency | License | Purpose |
+|---|---|---|
+| [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/sdk) | MIT | MCP protocol implementation |
+| [`zod`](https://github.com/colinhacks/zod) | MIT | External input validation |
+| [`cross-spawn`](https://github.com/moxystudio/node-cross-spawn) | MIT | Cross-platform child processes |
+
+Development dependencies (TypeScript, ESLint, Prettier, Vitest, Vite, tsx, etc.) follow their own open-source licenses and are not distributed with the npm package.
+
+### Relationship to the security boundary
+
+This MCP **never stores, reads, or forwards** any AI-Agent API key or login state (see [SECURITY.en.md](SECURITY.en.md)). The license terms do not change this design boundary.