tianshu-mcp 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.en.md

@@ -0,0 +1,107 @@
+<div align="center">
+
+# tianshu-mcp
+
+**Tianshu × AI-Agent orchestration MCP server**
+
+Registered by Tianshu as a standard MCP server, it dispatches external AI-Agent CLIs (Codex; Zcode and TraeWork/TRAE SOLO CN verified to lack headless interfaces → unsupported; architecture stays horizontally extensible) to drive the closed loop of **project development → acceptance → failure rework → re-acceptance**.
+
+TypeScript · Node.js ≥ 20 · `@modelcontextprotocol/sdk` (stdio)
+
+</div>
+
+---
+
+## What this is
+
+Tianshu plays the role of the overall commander; this MCP server is the **scheduler + execution surface + objective acceptance gate**; the external AI-Agent CLI (e.g. Codex) 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`.
+- **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`; when rounds run out → `needs_attention` awaiting Tianshu's verdict.
+- **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
+
+```bash
+npm install
+npm run build        # → dist/
+npm test             # 53 tests: unit + stub-agent 3-playbook integration + protocol + cancel/timeout/baseline/params regression
+```
+
+Register as a Tianshu MCP server (local dev mode):
+
+```jsonc
+{
+  "mcp": {
+    "servers": {
+      "tianshu-mcp": {
+        "command": "node",
+        "args": ["<absolute-repo-path>/dist/index.js"],
+        "env": { "TIANSHU_MCP_HOME": "<absolute-repo-path>/.tianshu-mcp" }
+      }
+    }
+  }
+}
+```
+
+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:
+
+```text
+run_task(projectPath=D:/xxx/my-app, task=「…task brief…」, agentId=codex, autoVerify=true, autoFixRounds=2)
+  → taskId → poll query_task(taskId) → succeeded / failed / needs_attention → get_task_report
+```
+
+## Documentation
+
+| Doc | Content |
+|---|---|
+| [docs/tianshu-integration.md](docs/tianshu-integration.md) | Two config.json integration modes, UI/API steps, smoke test, FAQ |
+| [docs/agent-profiles.md](docs/agent-profiles.md) | Agent profile field reference + real-machine samples (codex M2 finalized) |
+| [docs/adapter-matrix.md](docs/adapter-matrix.md) | Agent capability research matrix (Codex/Zcode/TraeWork/extension slots) |
+| [docs/m2-smoke-record.md](docs/m2-smoke-record.md) | M2 real-Codex smoke record (run_task→verify_task passed + bug fixes) |
+| [docs/m2-rework-record.md](docs/m2-rework-record.md) | M2 codex rework-loop record (failure→rework_task→re-verify, with artifacts) |
+| [docs/acceptance-config.md](docs/acceptance-config.md) | Project-level `.tianshu-mcp/acceptance.json` acceptance config spec |
+| English docs | [acceptance-config.en.md](docs/acceptance-config.en.md) · [tianshu-integration.en.md](docs/tianshu-integration.en.md) · [agent-profiles.en.md](docs/agent-profiles.en.md) · [adapter-matrix.en.md](docs/adapter-matrix.en.md) |
+| [skills/tianshu-mcp/](skills/tianshu-mcp/SKILL.md) | Skill teaching Tianshu how to orchestrate this MCP (with usage examples) |
+
+## 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 — **53/53 green** (incl. R1–R5 cancel/timeout/baseline/params regressions)
+- **M2 — Real Codex CLI smoke + rework loop** ✅ (2026-09-07)
+  - Real `codex exec` completed `run_task → query_task → verify_task` (see [m2-smoke-record.md](docs/m2-smoke-record.md))
+  - Real **failure → rework_task → re-verify succeeded** loop ([m2-rework-record.md](docs/m2-rework-record.md), artifacts in `docs/m2-evidence/`)
+  - 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
+- **M3 — TraeWork research + full delivery** ✅ (2026-09-07 T1 settled + delivery ready)
+  - T1 settled: local TRAE SOLO CN v1.107.1 verified **unsupported** (no headless programmable agent interface; VS Code-family CLI only; see [adapter-matrix.md](docs/adapter-matrix.md))
+  - npm name `tianshu-mcp` available; npm publish needs an npmjs token
+  - Real Tianshu-session skill-trigger validation (DoD #8) needs a GUI session (skill self-installed and ready)
+
+## Acceptance remediation (R1–R8, 2026-09-07)
+
+Per the acceptance-remediation plan, all P1/P2 findings are fixed with regression tests (total **53/53**):
+
+- **R1** ✅ cancel/interrupt state persistence (`cancel_requested → cancelled`, cancelReason/finishedAt/errorType, restart-recoverable, idempotent, bounded shutdown)
+- **R2** ✅ call-level `taskTimeoutMs` wins (adapter no longer overrides); POSIX process-group SIGTERM→SIGKILL with exit polling; Windows `taskkill /T /F`; single kill-tree impl + abort-race guard
+- **R3** ✅ git baseline participates in diff (baseline.head boundary; agent commits don't lose changes; dirty-worktree hash attribution; `--untracked-files=all`)
+- **R4** ✅ params: `round=0` valid; manual verify allocates next round (no overwrite); `extraChecks` append + `checksMode=replace`; `optional` doesn't fail verdict; `baselineRef` validated
+- **R5** ✅ hardcoded paths removed (`{LOCALAPPDATA}` placeholders + platform defaults); mtime+size hot reload for config/profile/projects
+- **R6** ✅ CI matrix win/mac/linux × Node 20/22 all green (run 25); Release version consistency (tag=package=tarball, v0.1.1 draft OK); tarball content check
+- **R7** 🟡 real Tianshu loop: host connect (DoD #6) + skill install verified; GUI-session invoke needs a user session
+- **R8** 🔄 docs synced (ZH/EN + dev-plan checklist); see [remediation-recheck report](.codex/review/2026-09-07-remediation-recheck.md)
+
+## Recommended phrasing (for Tianshu)
+
+> "In project D:\xxx, implement 『task』 with codex. First run run_task(autoVerify:true, autoFixRounds:2), then check with query_task; if the report says needs_attention, feed the failed items from get_task_report as feedback into rework_task and verify again; when everything passes, report changedFiles and diffstat."
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -0,0 +1,115 @@
+<div align="center">
+
+# tianshu-mcp
+
+**天枢 × AI-Agent 编排 MCP server**
+
+由天枢（Tianshu）当作标准 MCP server 接入，调度外部 AI-Agent CLI（Codex；Zcode 与 TraeWork/TRAE SOLO CN 经实测无无头接口标 unsupported，架构可横向扩展）完成 **项目开发 → 验收 → 失败返修 → 再验收** 的闭环。
+
+TypeScript · Node.js ≥ 20 · `@modelcontextprotocol/sdk`（stdio）
+
+</div>
+
+---
+
+## 这是什么
+
+天枢的角色是总指挥；本 MCP server 是**调度 + 执行面 + 客观验收仪**；外部 AI-Agent CLI（Codex 等）是执行开发的"工人"。
+
+- **8 个 MCP 工具**：`run_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`；轮次用尽 → `needs_attention` 等天枢裁决。
+- **调度纪律**：每项目串行队列 + 全局并发上限（默认 2，可配）。
+- **不碰密钥**：各 agent 用自己的登录态；本 server 不保存/转发任何 API key。
+- **可扩展**：新 agent = 一个 profile（数据）+（如需）一个 adapter 文件，零改编排核心。
+
+## 快速开始
+
+```bash
+npm install
+npm run build        # → dist/
+npm test             # 53 项测试：单元 + stub-agent 三剧本集成 + 协议 + 取消/超时/基线/参数回归
+```
+
+配置为天枢 MCP server（本地开发模式）：
+
+```jsonc
+{
+  "mcp": {
+    "servers": {
+      "tianshu-mcp": {
+        "command": "node",
+        "args": ["<仓库绝对路径>/dist/index.js"],
+        "env": { "TIANSHU_MCP_HOME": "<仓库绝对路径>/.tianshu-mcp" }
+      }
+    }
+  }
+}
+```
+
+新开会话后，工具面出现 `mcp__tianshu-mcp__run_task` 等 8 个工具。用 stub 预演（不碰真实登录态）→ 切 codex 跑真实任务：
+
+```text
+run_task(projectPath=D:/xxx/my-app, task=「…任务书…」, agentId=codex, autoVerify=true, autoFixRounds=2)
+  → taskId → query_task(taskId) 轮询 → succeeded / failed / needs_attention → get_task_report 读报告
+```
+
+## 文档
+
+| 文档 | 内容 |
+|---|---|
+| [docs/tianshu-integration.md](docs/tianshu-integration.md) | 天枢 config.json 两种接入模式、UI/API 操作、冒烟步骤、FAQ |
+| [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/m2-smoke-record.md](docs/m2-smoke-record.md) | M2 真实 codex 冒烟记录（run_task→verify_task 通过 + 缺陷修复） |
+| [docs/m2-rework-record.md](docs/m2-rework-record.md) | M2 codex rework 闭环记录（失败→rework_task→再验收，含物证） |
+| [docs/host-integration-record.md](docs/host-integration-record.md) | 天枢宿主真实接入实测（DoD #6：2 servers / 10 tools） |
+| [docs/acceptance-config.md](docs/acceptance-config.md) | 项目级 `.tianshu-mcp/acceptance.json` 验收配置规范 |
+| English docs | [acceptance-config.en.md](docs/acceptance-config.en.md) · [tianshu-integration.en.md](docs/tianshu-integration.en.md) · [agent-profiles.en.md](docs/agent-profiles.en.md) · [adapter-matrix.en.md](docs/adapter-matrix.en.md) |
+| [skills/tianshu-mcp/](skills/tianshu-mcp/SKILL.md) | 教天枢编排本 MCP 的技能（含使用示例） |
+
+## 里程碑状态
+
+- **M1 — 核心引擎 + stub-agent 全链路** ✅
+  - 8 工具、TaskManager 状态机/队列/并发闸/cancel(kill tree)/事件流落盘
+  - 验收引擎（git 基线/diff、默认集推导、命令 runner、代码分析、report.md/json）
+  - fix-loop 自动返修 + needs_attention；技能自检安装（已在本机真实 `~/.rivet/skills` 验证）
+  - stub-agent 三剧本（good/fix-on-first/never）集成测试 + 协议测试，**53/53 绿**（含 R1–R5 取消/超时/基线/参数回归）
+- **M2 — 真实 Codex CLI 冒烟 + rework 闭环** ✅（2026-09-07）
+  - 真实 `codex exec` 跑通 `run_task → query_task → verify_task`（[m2-smoke-record.md](docs/m2-smoke-record.md)）
+  - 真实 **失败→rework_task→再验收 succeeded** 闭环（[m2-rework-record.md](docs/m2-rework-record.md)，物证 `docs/m2-evidence/`）
+  - 修复冒烟暴露的 3 个真实缺陷（Windows npm 垫片 / spawn 日志竞态崩溃 / codex flags 互斥）并各加回归测试
+  - Zcode 无头接口（Z1）实测定论：ZCode 桌面无随包 headless CLI → unsupported
+- **工程/CI** ✅（2026-09-07）
+  - GitHub Actions 实测：`CI`（Node 20/22 矩阵）与 `Release`（tag v0.1.0 触发）均绿（提交 d91aea8/2a9ac82 起）
+  - 技能自检安装已在本机真实 `~/.rivet/skills/tianshu-mcp` 验证生效且幂等
+  - npm 包名 `tianshu-mcp` 在 npmjs 可用（未占用）
+- **天枢宿主真实接入（DoD #6）** ✅（2026-09-07，[host-integration-record.md](docs/host-integration-record.md)）
+  - 在真实 `D:\Tianshu` 桌面宿主 `mcp.servers` 配置 §11.1 本地模式 → sidecar `MCP: 2 servers connected, 10 tools`（含本 server 8 工具），spawn 子进程并 stdio 连通
+  - 实测暴露并修复技能安装源路径 bug（fileURLToPath，提交 55cf2d0）
+- **M3 — TraeWork 调研 + 全套交付** ✅（2026-09-07 T1 定论 + 交付就绪）
+  - T1 定论：本机 TRAE SOLO CN v1.107.1 实测 **unsupported**（无无头可编程 agent 接口，仅 VS Code 家族 CLI；见 [adapter-matrix.md](docs/adapter-matrix.md)）
+  - npm 包名 `tianshu-mcp` 可用；npm publish 需 npmjs token
+  - GUI 聊天会话内实际调用工具（DoD #8 最后一环）需用户开天枢新会话（宿主连通与 8 工具注册已就位）
+
+## 验收整改（R1–R8，2026-09-07）
+
+按 [验收修复计划](.zcode/plans/tianshu-mcp-development-plan.md) 与 `.codex/plans/2026-09-07-acceptance-remediation-plan.md` 完成：
+
+- **R1** ✅ 取消/中断状态机持久化：运行中取消 `cancel_requested → cancelled`（cancelReason/finishedAt/errorType 落盘）、重启可恢复、幂等、shutdown 有界等待。
+- **R2** ✅ 调用级 `taskTimeoutMs` 覆盖生效（adapter 不再用 profile 覆盖）、POSIX 进程组 SIGTERM→SIGKILL、Windows taskkill /T /F，kill-tree 单实现。
+- **R3** ✅ Git 基线参与差异计算：以 baseline.head 为边界，agent 提交不丢变更、脏工作区 hash 归因、porcelain 逐文件展开。
+- **R4** ✅ 参数语义：`get_task_report(round=0)` 合法、手动验收分配新轮次不覆盖、`extraChecks` 追加 + `checksMode=replace`、`optional` 不影响 verdict、`baselineRef` 校验。
+- **R5** ✅ 移除路径硬编码（`{LOCALAPPDATA}` 等占位符 + 平台标准候选），config/profile/projects mtime 热加载。
+- **R6** 🔄 CI 矩阵扩到 Windows/macOS/Linux × Node 20/22；Release 版本一致性校验；tarball 内容校验。
+- **R7** 🟡 天枢真实闭环：宿主连通（DoD #6）与技能安装已实测；GUI 会话内工具调用待用户开天枢新会话。
+- **R8** 🔄 文档同步 + 最终复验。
+
+## 推荐用法（给天枢的提示语）
+
+> "在项目 D:\xxx 用 codex 实现『任务』。先跑 run_task(autoVerify:true, autoFixRounds:2)，完成后用 query_task 看结果；若报告显示 needs_attention，把 get_task_report 的失败项摘要作为 feedback 调 rework_task 再验一轮；全部通过后向我汇报 changedFiles 与 diffstat。"
+
+## 许可
+
+[MIT](LICENSE)

package/dist/agents/adapter.d.ts

@@ -0,0 +1,76 @@
+/**
+ * AgentAdapter 接口（开发计划 §7.1）：统一抽象，横向扩展点。
+ * 实现基于 profile 数据驱动：resolve 探测可执行，buildInvocation 构造命令，
+ * parseExit 判定结果。新增 agent = 新 profile +（如需）子类 adapter。
+ */
+import type { SpawnSpec } from "./spawn.js";
+import type { AgentProfile } from "../config/schema.js";
+export interface ResolvedAgent {
+    id: string;
+    displayName: string;
+    profile: AgentProfile;
+    command: string;
+    argsTemplate: string[];
+    ok: boolean;
+    message: string;
+    /** resolve 成功后缓存的探测信息 */
+    discovered?: {
+        source: "explicit" | "fallback" | "discovery";
+        version?: string;
+    };
+}
+export interface TaskContext {
+    taskId: string;
+    projectPath: string;
+    displayPath: string;
+    agentId: string;
+    task: string;
+    context?: string;
+    round: number;
+    feedback?: string;
+    taskDir: string;
+    workDir: string;
+    taskTimeoutMs: number;
+}
+export interface SpawnInvocation {
+    spec: Omit<SpawnSpec, "logFile" | "timeoutMs">;
+    promptText: string;
+    stdinText?: string;
+    timeoutMs: number;
+    logFile: string;
+}
+export interface AgentRunResult {
+    ok: boolean;
+    exitCode: number | null;
+    timeout: boolean;
+    killed: boolean;
+    error?: string;
+    durationMs: number;
+    logFile: string;
+    hardFailure?: boolean;
+}
+/** parseExit: SpawnResult → AgentRunResult，按 agent 语义 */
+export type ParseExitFn = (res: {
+    ok: boolean;
+    exitCode: number | null;
+    timeout: boolean;
+    killed: boolean;
+    error?: string;
+    durationMs: number;
+    logFile: string;
+}) => AgentRunResult;
+export interface AgentAdapter {
+    id: string;
+    /** 构造一次调用（命令/参数/工作目录/env/prompt 传递） */
+    buildInvocation(ctx: TaskContext, resolved: ResolvedAgent): SpawnInvocation;
+    /** 将子进程退出结果翻译为语义结果 */
+    parseExit(res: {
+        ok: boolean;
+        exitCode: number | null;
+        timeout: boolean;
+        killed: boolean;
+        error?: string;
+        durationMs: number;
+        logFile: string;
+    }): AgentRunResult;
+}

package/dist/agents/adapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adapter.js.map

package/dist/agents/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/agents/adapter.ts"],"names":[],"mappings":""}

package/dist/agents/builtin.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 内置 agent profiles（开发计划 §7.2）。用户数据目录 agent-profiles.json 可整键覆盖。
+ * 代码优先、profile 可配：真实路径属于机器/环境数据 → 默认只给结构与探测规则。
+ */
+import type { AgentProfile } from "../config/schema.js";
+export declare const BUILTIN_PROFILES: Record<string, AgentProfile>;
+export declare const BUILTIN_PROFILE_IDS: string[];

package/dist/agents/builtin.js

@@ -0,0 +1,51 @@
+export const BUILTIN_PROFILES = {
+    codex: {
+        displayName: "Codex (OpenAI 桌面端 CLI)",
+        type: "cli",
+        status: "ready",
+        command: null,
+        argsTemplate: ["exec", "<prompt:arg>", "--skip-git-repo-check", "--sandbox", "workspace-write"],
+        promptMode: "arg",
+        cwd: "task",
+        env: {},
+        timeoutMs: 30 * 60_000,
+        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"],
+            fileNames: ["codex.exe", "codex"],
+            fallbackCommand: "codex",
+        },
+        note: "M2 真实冒烟已定稿（见 docs/m2-smoke-record.md）：--sandbox workspace-write 非交互通过",
+    },
+    zcode: {
+        displayName: "Zcode (ZCode 桌面)",
+        type: "cli",
+        status: "unsupported",
+        command: null,
+        argsTemplate: [],
+        promptMode: "arg",
+        cwd: "task",
+        env: {},
+        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）",
+    },
+    traework: {
+        displayName: "TraeWork (TRAE SOLO CN)",
+        type: "cli",
+        status: "unsupported",
+        command: null,
+        argsTemplate: [],
+        promptMode: "arg",
+        cwd: "task",
+        env: {},
+        timeoutMs: 30 * 60_000,
+        killTree: "taskkill",
+        authNote: "",
+        note: "T1 实测（2026-09-07）：本机 D:/TRAE Work CN = TRAE SOLO CN v1.107.1，仅有 VS Code 家族 CLI（open/serve-web/扩展管理），无 codex 风格无头 agent-exec，builtin-mcp 为 MCP 客户端扩展。无可编程无头驱动接口 → unsupported（详见 docs/adapter-matrix.md §T1）。若 Trae 未来提供 headless agent CLI 可重评",
+    },
+};
+export const BUILTIN_PROFILE_IDS = Object.keys(BUILTIN_PROFILES);
+//# sourceMappingURL=builtin.js.map

package/dist/agents/builtin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin.js","sourceRoot":"","sources":["../../src/agents/builtin.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,gBAAgB,GAAiC;IAC5D,KAAK,EAAE;QACL,WAAW,EAAE,wBAAwB;QACrC,IAAI,EAAE,KAAK;QACX,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,IAAI;QACb,YAAY,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,uBAAuB,EAAE,WAAW,EAAE,iBAAiB,CAAC;QAC/F,UAAU,EAAE,KAAK;QACjB,GAAG,EAAE,MAAM;QACX,GAAG,EAAE,EAAE;QACP,SAAS,EAAE,EAAE,GAAG,MAAM;QACtB,QAAQ,EAAE,UAAU;QACpB,QAAQ,EAAE,uEAAuE;QACjF,mBAAmB,EAAE;YACnB,IAAI,EAAE,CAAC,iCAAiC,EAAE,8CAA8C,EAAE,oDAAoD,CAAC;YAC/I,SAAS,EAAE,CAAC,WAAW,EAAE,OAAO,CAAC;YACjC,eAAe,EAAE,OAAO;SACzB;QACD,IAAI,EAAE,uEAAuE;KAC9E;IACD,KAAK,EAAE;QACL,WAAW,EAAE,kBAAkB;QAC/B,IAAI,EAAE,KAAK;QACX,MAAM,EAAE,aAAa;QACrB,OAAO,EAAE,IAAI;QACb,YAAY,EAAE,EAAE;QAChB,UAAU,EAAE,KAAK;QACjB,GAAG,EAAE,MAAM;QACX,GAAG,EAAE,EAAE;QACP,SAAS,EAAE,EAAE,GAAG,MAAM;QACtB,QAAQ,EAAE,UAAU;QACpB,QAAQ,EAAE,gBAAgB;QAC1B,IAAI,EAAE,4LAA4L;KACnM;IACD,QAAQ,EAAE;QACR,WAAW,EAAE,yBAAyB;QACtC,IAAI,EAAE,KAAK;QACX,MAAM,EAAE,aAAa;QACrB,OAAO,EAAE,IAAI;QACb,YAAY,EAAE,EAAE;QAChB,UAAU,EAAE,KAAK;QACjB,GAAG,EAAE,MAAM;QACX,GAAG,EAAE,EAAE;QACP,SAAS,EAAE,EAAE,GAAG,MAAM;QACtB,QAAQ,EAAE,UAAU;QACpB,QAAQ,EAAE,EAAE;QACZ,IAAI,EAAE,gPAAgP;KACvP;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC"}

package/dist/agents/cli.d.ts

@@ -0,0 +1,15 @@
+import type { AgentAdapter, AgentRunResult, ResolvedAgent, SpawnInvocation, TaskContext } from "./adapter.js";
+import type { SpawnResult } from "./spawn.js";
+export declare const PROMPT_ARG = "<prompt:arg>";
+export declare const PROMPT_STDIN = "<prompt:stdin>";
+export declare const PROMPT_FILE = "<prompt:file>";
+export declare class CliAdapter implements AgentAdapter {
+    readonly id: string;
+    constructor(id: string);
+    buildInvocation(ctx: TaskContext, resolved: ResolvedAgent): SpawnInvocation;
+    /** file 模式下写 prompt 文件（幂等，可重复调用） */
+    prepare(ctx: TaskContext, resolved: ResolvedAgent): Promise<void>;
+    private promptFilePath;
+    private homeDir;
+    parseExit(res: SpawnResult): AgentRunResult;
+}