dsh-tower 1.2.0 → 2.0.0

package/docs/zh/guide/hot-reload.md

@@ -0,0 +1,178 @@
+# 热重载（开发）
+
+[English](../../guide/hot-reload.md) | **简体中文**
+
+Tower 是 Host 插件：它的工具与提示段落在 DSH 启动时加载。DSH 已内置 `@deepseek-ai/dsh-hmr` 服务，
+它**在原位对账 profile**——重新读取 profile 的 patch 层，替换文件已变更的模块（包括 `dsh-tower`
+检出这样的 linked 包），重启受影响的 Loader 条目，并报告哪些情况需要完整重启。Tower 在开发中使用
+该服务，因此 Host 侧改动无需重启 DSH 即可生效。
+
+本页讲的是开发循环，使用 Tower 本身并不需要它。
+
+## HMR 做什么、不做什么
+
+`dsh --profile <name> --dump-config` 会打印组合后的 hmr 行：
+
+```yaml
+- id: hmr
+  name: '@deepseek-ai/dsh-hmr'
+  disabled: !!js '!ctx.get(''profileContext'')'
+  config:
+    root: []
+```
+
+- `root: []` 是随包默认值：**不监视任何源码文件**。HMR 已挂载，但文件监视处于空闲状态，因此编辑
+  检出后运行中的 DSH 不会自动重载。
+- 仍然可以显式请求对账（`/tower reload`、`tower_reload` 或 `plugin_manager`）；即使 `root: []`，
+  它也会比较已加载模块与磁盘，并替换发生变化的模块。监视只是让保存后自动触发这次对账。
+- HMR 只为 profile 启动挂载（没有 `profileContext` 时 `disabled`）。没有 profile 启动的进程会报告
+  reload 不可用（`dev.hotReload` 开启时 `tower_reload` 仍注册，因此返回 `reload-unavailable`，
+  而不是消失）。
+- profile patch 层在 DSH 启动时加载。编辑它——实际就是 hmr 的 `root` 列表——需要**重启一次 DSH**
+  才生效。运行中的进程不会重新读取 HMR 行自身的配置。
+
+## 为检出开启监视
+
+在本仓库的检出目录中执行：
+
+```powershell
+npm run dev:hmr
+# equivalent to:
+node scripts/enable-dev-hmr.mjs
+```
+
+脚本会向 profile 的用户 patch 层
+`<DSH_HOME>/profiles/<profile>/cordis.patch.yml` 追加一个带标记的块（`DSH_HOME` 默认 `~/.dsh`；
+Windows 上通常是 `C:\Users\<you>\.dsh`）：
+
+```yaml
+# dsh-tower:dev-hmr
+- id: hmr
+  config:
+    root:
+      - 'D:/work/dsh-tower'
+```
+
+选项：
+
+| 参数 | 含义 |
+|---|---|
+| `--profile <name>` | 要编辑的 profile。默认 `desktop`（桌面应用启动的 profile）。 |
+| `--root <dir>` | 要监视的仓库目录。默认：当前工作目录的规范路径。 |
+| `--dry-run` | 打印 patch 文件的 diff 后退出，不写入。 |
+| `--remove` | 再次删除该标记块。 |
+
+说明：
+
+- 脚本是幂等的：重复运行会替换标记块，且不触碰 patch 文件的其余行。请在仓库根目录运行，或传入
+  `--root D:\work\dsh-tower`。
+- 写入的值是 root 的 `realpath`，使用正斜杠。**HMR 的 `root` 接受绝对路径**；相对路径会相对
+  profile 目录解析，很容易出错，因此脚本总是写入绝对路径。
+- profile 必须已存在。脚本不会创建 profile，也不会在 `<DSH_HOME>/profiles/<profile>/` 之外创建目录。
+- 选择桌面应用实际启动的 profile（默认 `desktop`）。desktop profile 由 Electron 应用管理，请退出并
+  重新启动 DSH 来完成重启。
+
+写入该块后**重启一次 DSH**。重启之后：
+
+- HMR 会监视检出（`node_modules`、点目录、`cache` 与 `data` 被随包 `ignored` 列表排除），并在 DSH
+  保持打开时于编辑后对账 profile。
+- `/tower reload`（以及注册后的 `tower_reload` 工具）可以按需对账，即使文件不在监视范围内。
+
+停止监视：运行 `npm run dev:hmr -- --remove`，再重启一次 DSH。
+
+## 编辑循环
+
+1. 编辑 `lib/*.js`、`index.js`、`worker.js`、`reviewer.js` 或 `skills.js`。
+2. 保存文件。监视器会去抖（DSH 默认 100 ms）并对账 profile；变更的模块被替换，受影响的 Loader
+   条目重启。
+3. 观察 DSH 日志中的 `reload plugin at <path>` / `restart required: …` 消息。
+4. 可选：调用 `/tower reload` 或 `tower_reload` 立即对账，而不必等监视器。
+
+编辑仓库的 bundle patch（`cordis.patch.yml`）会改变插件声明本身；此类改动后请重启 DSH，不要假设
+热替换会生效。
+
+工具背后的桥接遵循 `dev` 配置组：
+
+| 配置键 | 含义 |
+|---|---|
+| `dev.hotReload` | 注册 `tower_reload`；关闭时 `/tower reload` 也被禁用（默认 `true`）。无 HMR 服务时工具仍注册，以便返回 `reload-unavailable`。 |
+| `dev.reloadDelayMs` | 计划中的对账运行前的延迟，单位毫秒（默认 `50`），让工具/命令结果先送达模型，再替换插件。 |
+| `dev.reloadRequiredIds` | profile 必须保持活跃的 Loader 条目 id（默认 `tower`、`tower-skills`、`preset-tower-worker`、`preset-tower-reviewer`）。即使某个 required 条目早已处于非活跃状态，也会被报告为重载失败。 |
+
+重载是**调度而非等待**：`/tower reload` 与 `tower_reload` 立即返回 `scheduled`、`delayMs`、
+`requiredIds`（以及存在待处理错误时的 `lastError`），随后 HMR 在延迟后对账 profile。这是有意为之——
+工具结果必须先送达，Tower 插件才能替换自身。两个后果：
+
+- 延迟窗口内的一批重载请求会合并为一次对账；
+- 对账失败会记录为 `lastError`，而不会从工具调用返回，因此重载后请检查 `tower_mode.hotReload`
+  与 DSH 日志。
+
+### 阅读重载结果
+
+计划中的对账结果会出现在：
+
+- **DSH 日志** —— 被替换模块的 `reload plugin at <path>`，以及 HMR 自身的告警与
+  `restart required: <reason>` 消息。
+- **`tower_mode.hotReload`** —— `{available, requiredIds, delayMs, scheduled, lastRunAt, lastError}`；
+  `lastError` 保留最近一次失败，并在下次成功重载后清除。
+
+对账本身还会返回 `warnings`、`pending`（仍运行旧代码的模块）以及可选的 `restartReason`。由 Tower
+触发重载时，这些不会返回给模型，因此把“新代码没有出现”视为需要重启 DSH 的信号，而不是反复重试。
+
+没有 HMR 时，`/tower reload` 会回答不可用消息，且 `tower_reload` 根本不会注册（两者都在会话启动时
+由 HMR 服务决定是否启用）。
+
+## plugin_manager 与 linked 包
+
+`plugin_manager` 操作（`install_bundle`、`set_plugin`、升级）会立即作用于运行中的 profile——它们
+自己会对账 profile，因此安装或更新 bundle 不需要重启。开发时安装 `dsh-tower` 的推荐方式就是如此：
+把检出作为 bundle 添加（`dsh plugin --profile <profile> add <repo-root>` 或 `install_bundle`），
+然后让 HMR 与重载工具接住代码编辑。
+
+检出作为 linked 包目标时，检出内的文件变更会在下一次 `reconcileProfile` 或 `plugin_manager` 操作时
+被替换，**无需重启**——即使 `root: []` 意味着该变更没有被监视。真正需要重启的是：
+
+- hmr 行自身的配置（`root`），因为该列表在服务激活时读取；
+- 报告在 `pending` 下或带 `restartReason` 的模块。
+
+## 故障恢复
+
+| 症状 | 处理 |
+|---|---|
+| `[tower:reload-unavailable]` / “Tower reload is unavailable” | 该进程没有 HMR 服务（未带 profile 启动、profile 中 HMR 被禁用，或服务在关闭过程中已 dispose）。重启 DSH。要检查 hmr 行，在非 desktop profile 上运行 `dsh --profile <name> --dump-config`（desktop profile 由 Electron 应用管理，拒绝 dump）。 |
+| `hotReload.lastError` 中出现 `[tower:reload-failed]` 且伴随语法/导入错误 | 修复文件后重启 DSH。替换失败会停掉旧插件实例，旧代码不再运行；重载本身不会回滚。 |
+| `HMR is disposed` | 服务随进程关闭。重启 DSH。 |
+| `HMR transactions cannot be nested` | 在另一个 HMR 事务内部请求了显式重载；请从普通工具回合调用。 |
+| `pending` 非空或设置了 `restartReason` | 先重启 DSH，再相信重载结果。 |
+| 已保存但没有任何重载 | 确认文件位于配置的 `root`（绝对路径）下，未被 `ignored`（`node_modules`、点目录、`cache`、`data`）排除，且 profile patch 包含标记块。运行 `/tower reload` 手动对账。 |
+| 重载持续报告某个 required 条目非活跃 | 该 Loader 条目被禁用或启动失败：检查 profile 的插件/bundle（移除 Tower preset bundle 后 `preset-tower-*` 条目会缺失），修复后重启。 |
+
+离线桥接测试属于常规测试套件：
+
+```powershell
+node --test tests/hmr.test.mjs
+```
+
+## Client bundle（`ui-bundle`）不同
+
+HMR 替换的是 **Host** 插件与提示/工具代码。可选的 `ui-bundle` 是 Client 小部件：它的 JavaScript 由
+Web 页面下载并执行，而不是 Host 进程。Host 重载或 Client bundle 安装/更新后，已打开的页面可能仍保留
+旧小部件——在认为改动失败之前，先刷新 Web 页面（如果工具 schema 有变化，再打开新会话）。Tower UI
+小部件只是一个提示，与热重载没有依赖关系。
+
+要在隔离 profile 上对重载路径做实机检查，使用
+[`tests/live/hmr.cjs`](../../../tests/live/hmr.cjs)，并把 `DSH_TEST_URL` 指向一次性服务器 URL
+（见 [tests/README.md](../../../tests/README.md)）；它不会触碰 desktop profile 或在线会话。
+
+## 安全
+
+HMR 会在 **DSH Host 进程内**执行它在被监视 root 中找到的代码，使用你的操作系统用户权限，并在保存时
+重载。请像对待 shell 启动文件一样对待 profile patch 层：
+
+- 只把 `root` 指向你信任的仓库（本检出），并保持列表小而绝对；
+- 不要加入主目录、下载目录或共享/网络路径；
+- 被 patch 的 profile 属于同用户可信配置；能写它的人就能在你的 DSH 进程中执行代码；
+- 不再需要监视时，移除该块（`--remove`）并重启一次。
+
+另见：[安装、升级与迁移](install-upgrade-migration.md)、
+[配置参考](../reference/config.md)、[错误码](../reference/errors.md)。

package/docs/zh/guide/install-upgrade-migration.md

@@ -0,0 +1,57 @@
+# 安装、升级与迁移
+
+[English](../../guide/install-upgrade-migration.md) | **简体中文**
+
+## 环境要求
+
+- DSH `0.2.1-rc.2` 或更新版本
+- Node.js 22+
+- Git（本地 worktree；不需要网络访问）
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-tower
+```
+
+或在 DSH 内执行：`plugin_manager({ action: "install_bundle", target: "dsh-tower" })`。从本地 checkout 安装：
+
+```bash
+dsh plugin --profile web add github:louifinn/dsh-tower
+```
+
+Host 插件在 DSH 启动时加载：**安装或更新后需要重启 DSH**。
+
+## 升级
+
+1. 阅读 [CHANGELOG.md](../../../CHANGELOG.md) 了解行为变化。
+2. 更新依赖（`dsh plugin --profile web add dsh-tower@latest` 或你固定的版本）。
+3. 重启 DSH；用 `tower_mode` 检查 `allowAgentControl` 是否符合预期。
+4. 既有 mission state 保持兼容：1.2/1.3 的状态 schema 未变。
+
+## 迁移说明
+
+- **1.x → 2.0（未发布）**：不需要迁移状态（`schemaVersion` 保持 1；新字段都是可选的）。需要留意的
+  行为变化：Tower 模式激活期间，`mode.denyTools` 现在还会拒绝 `workflow`、`ralph`、`subagent`、
+  `subagent_fork`、`wait_agent` 与 `team_task_list`（可用显式列表覆盖）；`spawn.maxLiveWorkers`
+  默认为 4；`mode.workspaceLock` 默认关闭。worker 不能再直接完成/放弃/扩大 mission 的 scope——
+  请使用 `tower_complete`。新工具：`tower_interrupt`，以及 HMR 可用时的 `tower_reload`。升级后重启
+  一次 DSH；见[热重载](hot-reload.md)。
+- **1.3 → 1.4**：不需要迁移状态。新增：仓库级配置（`<git-common-dir>/dsh-tower/config.json`）、
+  稳定的 `[tower:<code>]` 工具错误、`tower_findings`，以及 `id`/`missionId` 与 snake/camel 输入
+  别名。既有调用保持可用；重启 DSH 以加载新工具面（`tower_findings` 与更新的 output schema）。
+- **1.2 → 1.3**：reviewer 从共享的 `tower-worker` preset 迁移到新的只读 `tower-reviewer` preset。
+  重新安装/重启，确保两个 preset 行都存在。`tower_spawn role=reviewer` 现在要求 mission 为
+  `completed`。
+- **1.1 → 1.2**：合并失败新增 `merge-hook-failed`、`cleanup` 与对账行为；不需要迁移状态。
+- **1.0 → 1.1**：包名从 `@local/dsh-tower` 改为 `dsh-tower`。先移除旧 bundle
+  （`remove_bundle` 目标 `@local/dsh-tower`），再安装 `dsh-tower`。
+
+## 卸载
+
+```text
+plugin_manager({ action: "remove_bundle", target: "dsh-tower" })
+```
+
+重启 DSH。`<git-common-dir>/dsh-tower/` 下的 mission state 与
+`<主检出父目录>/.dsh-tower-worktrees/` 下的 worktree 会保留；确认没有活跃 mission 后再手工清理。

package/docs/zh/guide/quickstart.md

@@ -0,0 +1,96 @@
+# 快速开始
+
+[English](../../guide/quickstart.md) | **简体中文**
+
+前置要求：DSH `0.2.1-rc.2`+、Node.js 22+、Git。安装 `dsh-tower` 并重启 DSH（见
+[安装](install-upgrade-migration.md)）。
+
+## 1. 进入 Tower 模式
+
+```
+/tower
+```
+
+会话会报告 `Tower mode ON`。此时你是控制塔；goal/todo/team 委派工具保留给普通模式。
+
+## 2. 初始化与计划
+
+```
+tower_init repoRoot=D:\work\repo
+tower_plan repoRoot=D:\work\repo missions=[{"title":"Feature A","scope":["src/a/**"],"tasks":["implement the feature","commit the change"],"kind":"build"}]
+```
+
+`tower_plan` 返回 mission id（`M1`）。每个 mission 在 spawn 时获得独立分支和 worktree。
+Tower 工具同时接受 `missionId` 与 `id` 两种写法（见[输入别名](../reference/tools.md#输入别名)）。
+
+## 3. 运行 worker
+
+```
+tower_spawn repoRoot=D:\work\repo missionId=M1 role=worker
+```
+
+调用立即返回子代理 id。worker 在 mission worktree 内工作、提交、把任务标记完成，并调用
+`tower_complete`；它的最终报告会送回本会话。用 `tower_roster` 观察活动，不要循环轮询。
+
+## 4. 审查
+
+```
+tower_spawn repoRoot=D:\work\repo missionId=M1 role=reviewer
+```
+
+reviewer 使用只读的 `tower-reviewer` preset。它查看 `tower_diff` 并提交 `tower_review`。只有
+`clean` + `merge` 的结论才允许合并。
+
+## 5. 门禁、合并与清理
+
+```
+tower_preflight repoRoot=D:\work\repo missionId=M1
+tower_merge     repoRoot=D:\work\repo missionId=M1
+tower_teardown  repoRoot=D:\work\repo
+```
+
+审查前运行 `tower_preflight` 预期报告 `no-review`；干净审查之后应为 `ok:true`。存在 blocker 时
+`tower_merge` 拒绝合并。`tower_teardown` 移除已 merged/abandoned 的 worktree 与分支。
+
+```
+/tower off
+```
+
+## 如果失败
+
+阅读 blocker code 并查阅 [blocker 参考](../reference/blockers.md)。最常见的情况：`stale-base`
+（执行 `tower_rebase`）、`no-review`（spawn reviewer）、`merge-hook-failed`（重试，或调大
+`timeoutMs`）、`tip-moved`（审查后分支已变化，需要重新审查）。
+
+工具抛出的错误带 `[tower:<code>]` 前缀；见[错误码](../reference/errors.md)（例如
+`preset-missing` 表示安装 bundle 后需要重启 DSH，`not-initialized` 表示先运行 `tower_init`）。
+
+## 可选：仓库级配置
+
+不修改 DSH profile，仓库也能调整 review、merge、worktree 与 spawn 策略。把 JSON 文件放到
+`<git-common-dir>/dsh-tower/config.json`（普通检出通常是 `.git/dsh-tower/config.json`）：
+
+```json
+{
+  "review": { "maxRoundsPerReviewer": 3 },
+  "merge": { "timeoutMs": 1800000 },
+  "worktrees": { "root": "D:/tower-worktrees" }
+}
+```
+
+仓库配置层覆盖 profile 配置；单次工具参数又覆盖两者。完整键表与优先级见
+[配置参考](../reference/config.md)。
+
+## 可选：finding
+
+scope 之外的观察用 `tower_finding` 记录。之后可以列出或关闭它们，而不必改代码：
+
+```
+tower_findings repoRoot=D:\work\repo
+tower_findings repoRoot=D:\work\repo id=F1 status=fixed note="fixed in M2"
+```
+
+状态为 `open → triaged → fixed` / `wontfix`，且 `fixed`/`wontfix` 可重新打开为 `open`。只有控制塔
+或 worker 可以修改 finding；reviewer 只能列出和读取。
+
+完整可复制示例：[examples/first-mission.md](../../examples/first-mission.md)（英文）。

package/docs/zh/operations/security.md

@@ -0,0 +1,42 @@
+# 安全模型
+
+[English](../../operations/security.md) | **简体中文**
+
+Tower 提供的是**协作层面的保证**，不是沙箱。需要理解哪些约束由插件强制执行、哪些依赖部署环境。
+
+## 由插件强制执行的约束
+
+- **审查绑定。** `tower_review` 会记录它检查的分支 tip；tip 变化后门禁会拒绝（`tip-moved`），除非
+  一次干净且无冲突的 rebase 给予了豁免。reviewer 在 spawn 之后修改分支会被拒绝
+  （`reviewer must not modify the mission branch`）。
+- **角色强制。** 调用方会根据 roster 解析。worker 的 mission 更新仅限于 task/blocker/note；
+  `completed`、`abandoned`、扩大 scope 与清除 blocker 仅限控制塔，完成（连同未读消息/提交门禁）必须
+  走 `tower_complete`。仅限控制塔的工具会以 `[tower:not-authorized]` 拒绝 roster 中的 worker。
+  每个 mission 只能有一个活跃 worker；接管已停止的 worker 必须显式声明。
+- **只读 reviewer preset。** `tower-reviewer` preset 从工具面移除 `write`、`edit`、`pwsh`、
+  `tower_mission` 与 `tower_complete`；reviewer 只能读、看 diff、发消息、记录 finding 和提交审查。
+- **Scope 门禁。** mission 只能修改其声明 scope glob 匹配的文件；越界改动会阻止合并。
+- **Worktree 隔离。** worker 在独立 worktree 与分支上工作；主检出只会被 merge/teardown 触及。
+- **人类掌握模式。** `/tower` 归用户所有。开启 `mode.allowAgentControl` 后模型可以切换，但必须
+  给出理由；随包 patch 默认开启——设为 `false` 可让模式只由人类控制。
+- **不自动恢复 goal。** 进入模式会暂停活跃 goal；退出时不会恢复它。
+- **建议性 workspace 锁。** `mode.workspaceLock` 防止两个 Tower 会话意外驱动同一个仓库；它是同用户
+  之间的协调锁，不是用户间的认证机制。
+
+## 不由插件强制执行的约束（部署关注点）
+
+- **沙箱。** Host 插件运行在文件系统沙箱之外；reviewer 的 shell 能力是在工具面层面移除的，但底层
+  进程仍拥有 DSH 的 OS 权限。需要硬隔离的部署必须自行限制进程/用户。
+- **reviewer 信任。** 审查是 reviewer agent/模型给出的背书；插件能把它绑定到提交，但无法证明
+  reviewer 真的推理正确。高价值分支建议使用独立模型/角色。
+- **仓库钩子。** `git merge` 会运行目标仓库的钩子（`pre-merge-commit` 等）。Tower 无法让这些钩子
+  变安全；在不受信任的仓库上运行 Tower 前请先审查钩子。
+- **HMR 重载。** 开启 `dev.hotReload` 时，`/tower reload`/`tower_reload` 会让 DSH 从磁盘重新导入
+  插件。只为你信任的检出配置 HMR 监视 root；重载会执行这些文件当前的代码。
+- **提示注入。** reviewer 会读取不受信任的分支内容（diff/评论）。只读 preset 限制了影响面，但模型侧
+  没有绝对防护。
+- **基线分支保护。** Tower 会写入本地基线分支；服务端的 branch protection/push 规则不属于本插件。
+
+## 报告问题
+
+不要在公开 issue 中粘贴密钥、token 或会话日志。见 [SECURITY.md](../../../SECURITY.md)。

package/docs/zh/reference/blockers.md

@@ -0,0 +1,62 @@
+# blocker 与失败码
+
+[English](../../reference/blockers.md) | **简体中文**
+
+`tower_preflight` 返回 `{ok:false, blockers:[{code, detail}]}`。`tower_merge` 与 `tower_rebase`
+在操作失败时返回相同结构。code 稳定；detail 面向人。
+
+## 门禁 blocker（26 个）
+
+| Code | 含义 / 下一步 |
+|---|---|
+| `mission-missing` | 未知 mission id。用 `tower_status` 查看。 |
+| `mission-not-completed` | mission 不是 `completed`；只有 `completed`（等待审查）的 mission 才能合并。 |
+| `tasks-open` | 仍有未完成任务；worker 必须先完成，或带理由 `task_drop`。 |
+| `blockers-present` | mission 仍有 blocker；解决后清除。 |
+| `no-check-evidence` | 启用了 `gates.requireChecks` 且完成报告没有 `checks`。把 completed mission 退回 `active`，带 checks 重新调用 `tower_complete`，然后重新审查。 |
+| `branch-missing` | 还没有 worktree/分支：先 spawn worker。 |
+| `stale-base` | 分支不包含基线 tip：执行 `tower_rebase`。 |
+| `read-only-survey` | survey mission 修改了文件；survey mission 必须只读。 |
+| `out-of-scope` | 改动文件超出 mission scope；有意为之就扩大 scope，否则回退。 |
+| `base-dirty` | 主检出存在未提交改动，合并会覆盖它们。 |
+| `deps-unmerged` | 依赖 mission 尚未 merged/abandoned。 |
+| `no-review` | 分支上没有审查：spawn reviewer。 |
+| `review-mission-mismatch` | 最新审查属于另一个 mission。 |
+| `not-clean` | 最新审查是 `p1-Nitems`/`p2-Nitems`；需要再来一轮。 |
+| `review-hold` | 最新审查建议 hold；必须由后续的干净审查取代。 |
+| `review-not-approved` | 最新干净审查给出的是 `fix-then-merge` 或 `hold`；只有 `merge` 才算批准。 |
+| `tip-moved` | 审查之后分支发生变化；重新审查（或使用干净 rebase 的免审豁免）。 |
+| `worker-busy` | 该 mission 的 roster agent 正在运行；等待或让其退役。 |
+| `worker-status-unknown` | 父目录不可用，无法证明 live roster agent 已停止；等目录恢复后重试，或先 adopt。 |
+| `base-wrong-branch` | 主检出不在记录的基线分支上。 |
+| `branch-owned-by-closed-missions` | mission 已 merged/abandoned；用新标题重新 plan。 |
+| `worker-stale` | 该 mission 的 roster worker 超过 `spawn.staleMs` 没有目录活动；合并前 adopt（只有确实还在运行时才 interrupt）。 |
+| `tests-missing` | 启用了 `gates.requireTests` 且没有针对被审查 tip 的通过测试回执；运行 `tower_test` 或 `tower_complete`。 |
+| `tests-failed` | 最新测试发现回执失败，或不满足 minCount/required 检查。修复测试并重跑。 |
+| `review-exemption-invalid` | mission 请求 `reviewPolicy:"none"`，但 `gates.allowReviewExemption` 关闭（或缺少理由）。 |
+| `merge-intent-pending` | 崩溃/失败前记录了合并意图；先运行 `tower_merge` 对账，再进行其他门禁。 |
+
+## 合并失败（4 个）
+
+| Code | 含义 / 下一步 |
+|---|---|
+| `merge-conflict` | 真实的 index 冲突；mission 变为 `blocked`。解决后把 mission 恢复为 `active`/`completed`，再重试。 |
+| `merge-hook-failed` | 在产生提交之前钩子/进程失败；仓库已恢复，mission 保持 `completed`。重试；`timeout: true` 表示 git 进程超时，慢钩子请调大 `timeoutMs`。 |
+| `merge-shape` | Git 产生了意外的合并父提交；检查仓库，不要强推。 |
+| `batch-invalid` | batch id/成员/回执/检查引用无效，或 close 证据不完整。 |
+
+已经落地的合并不是 blocker：`tower_merge` 会记录它（`reconciled`、`alreadyLanded`），或从失败调用中恢复
+（`recoveredFromFailure`、`warnings`）。
+
+## rebase 失败（3 个；`worker-busy` 与门禁共用）
+
+| Code | 含义 / 下一步 |
+|---|---|
+| `worktree-dirty` | 提交或丢弃 worktree 改动后重试。 |
+| `rebase-conflict` | 真实冲突；mission 变为 `blocked`。手工解决后将其恢复为 `active`，再重试。 |
+| `worker-busy` | 该 mission 有 agent 正在运行；先等待或让其退役。 |
+
+分支已包含在基线中时，`tower_rebase` 返回 `alreadyMerged: true`；此时调用 `tower_merge` 记录这次
+已落地的合并。
+
+稳定的 blocker code 共 32 个（26 个门禁 + 4 个合并失败 + 2 个 rebase 专属；`worker-busy` 与门禁共用）。

package/docs/zh/reference/config.md

@@ -0,0 +1,113 @@
+# 配置参考
+
+[English](../../reference/config.md) | **简体中文**
+
+每个键都是可选的；默认值即随包行为。未知顶层键会被拒绝。
+`section` 与 `allowAgentControl` 是 `mode.promptSection` 与 `mode.allowAgentControl` 的兼容别名。
+兼容别名只用于补缺：同时设置两种写法时，规范的 `mode.*` 键优先。
+
+## 层级与优先级
+
+从低到高：
+
+1. 代码默认值（下表中的默认值），
+2. profile 配置（挂载 `dsh-tower` 的 Cordis patch 传给 `apply()` 的配置），
+3. 仓库配置 `<git-common-dir>/dsh-tower/config.json`（通常是 `.git/dsh-tower/config.json`），
+4. 单次工具参数，例如 `worktreeRoot` 与 `timeoutMs`。
+
+每次 Tower 工具打开仓库时都会读取仓库配置层，因此仓库可以在不修改 profile 的情况下调整 review、
+merge、worktree 与 spawn 策略。它使用与 profile 配置相同的 JSON 形状（相同的分组与兼容别名），
+并按分组合并：仓库设置的键优先，仓库未设置的 profile 键保留。`tower_status` 会报告
+`config.path` 与 `config.repoConfigPresent`。
+
+```json
+{
+  "review": { "maxRoundsPerReviewer": 3 },
+  "merge": { "timeoutMs": 1800000 },
+  "worktrees": { "root": "D:/tower-worktrees" },
+  "spawn": { "reviewerPreset": "tower-reviewer", "maxDepth": 2 }
+}
+```
+
+`mode.*` 分组是会话级的，不是仓库级的：为兼容 schema，它可以在仓库文件中出现，但只有 profile
+配置能控制 Tower 模式提示与模型切换开关。文件格式错误、值不是对象、未知顶层键，或违反声明 schema
+的值（例如 `merge.timeoutMs` 小于 1000）会以稳定的 `config-invalid` / `config-unknown-key`
+工具错误码失败。
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `section` | `''` | 兼容别名：替换整段 Tower 模式提示文案。空值保留内置提醒。 |
+| `allowAgentControl` | `false`（随包 patch：`true`） | 兼容别名：注册 `tower_control`。 |
+| `init.autoGitInit` | `false`（随包 patch：`true`） | 当 `repoRoot` 是绝对、已存在但不是仓库的目录时，`tower_init` 可以执行 `git init` 并创建一个空的初始提交。 |
+| `init.snapshotDirty` | `false` | `tower_init` 可以把未提交的**已跟踪**改动快照为游离提交作为 mission 基线（不含未跟踪文件；该提交通过 `refs/tower/snapshot/*` 保持存活）。 |
+| `mode.promptSection` | `''` | 替换用的提示文案（与 `section` 同时设置时优先）。 |
+| `mode.sectionAppend` | `''` | 追加在提醒之后的额外文本（团队约定）。 |
+| `mode.allowAgentControl` | `false` | 注册 `tower_control`；模型可带理由进入/退出。 |
+| `mode.autoPauseGoal` | `true` | 进入模式时暂停活跃 goal；退出时不会自动恢复。 |
+| `mode.requireResumeAuthorization` | `false` | 恢复因 `pauseCause:user` 暂停的 mission 时，必须提供 `authorization` 引用。 |
+| `mode.workspaceLock` | `false`（随包 patch：`true`） | 每个仓库只允许一个 Tower 会话（`tower.lock`）；其他会话得到 `workspace-busy`。 |
+| `mode.workspaceLockScope` | `all` | `all` 锁定所有仓库工具；`mutations` 对只读工具跳过 workspace 锁。 |
+| `mode.planModePolicy` | `clear` | 进入 Tower 模式会清除活跃的 plan mode（或 `refuse` 直到退出计划）；前置步骤也会清除稍后激活的计划。 |
+| `mode.workspaceStaleMs` | `300000` | 超过该时长的 workspace 锁可以被接管。 |
+| `mode.heartbeatMs` | `10000` | workspace 锁的心跳间隔。 |
+| `mode.denyTools` | goal/todo/team/workflow/subagent 工具（默认 12 个） | 模式激活期间被拒绝的工具。 |
+| `mode.storePath` | `$DSH_HOME/tower-mode` | `modes.json` 所在目录。 |
+| `mode.maxEntries` | `200` | 最多持久化的模式条目数（1–2000）。 |
+| `review.maxRoundsPerReviewer` | `5` | 每个 reviewer 对每条分支的审查轮数上限。 |
+| `merge.timeoutMs` | `900000`（15 分钟） | `tower_merge` 默认超时，包含钩子；单次调用的 `timeoutMs` 优先。 |
+| `merge.maxBufferBytes` | `67108864`（64 MB） | 合并输出缓冲区。 |
+| `worktrees.root` | `''` | 默认 worktree 父目录；空值推导为 `<主检出父目录>/.dsh-tower-worktrees/<hash>`。 |
+| `spawn.workerPreset` | `tower-worker` | `role=worker` 使用的 preset。 |
+| `spawn.reviewerPreset` | `tower-reviewer` | `role=reviewer` 使用的 preset。 |
+| `spawn.maxDepth` | `1` | spawn 时请求的子代理深度。 |
+| `spawn.provider` | `''` | 子代理 provider id；空值优先 `spawn`，否则取第一个 provider。 |
+| `spawn.workerModel` | `{}` | worker 可选模型路由 `{provider, model, reasoningEffort, maxTokens}`。 |
+| `spawn.reviewerModel` | `{}` | reviewer 可选模型路由；使用不同模型可获得更强的独立审查。 |
+| `spawn.maxLiveWorkers` | `4` | 每个仓库同时存活的 worker 上限（空闲 `inactive`、failed/interrupted/missing/stale/retired 不计入）；超过返回 `worker-limit`。 |
+| `spawn.staleMs` | `15000` | 超过该时长没有目录活动的 roster 条目会被标记为 `stale` 并阻止合并（`worker-stale`）；0 关闭。 |
+| `spawn.maxWaitMs` | `90000` | `tower_spawn.waitMs` 的上限（与 Kimi 兼容的 90s 默认值）。 |
+| `spawn.requireLease` | `''` | worker spawn 前必须持有的可选租约名。 |
+| `send.maxPerMinute` | `120` | 每个仓库的 `tower_send` 每分钟速率限制（0 关闭）；超出返回 `rate-limited`。 |
+| `send.interruptDefault` | `false`（随包 patch：`true`） | `tower_send.interrupt` 的默认值（投递前先中断运行中的回合）。 |
+| `tests.enabled` | `true` | worktree 的 `package.json` 配置了测试发现时运行它。 |
+| `tests.admission` | `complete` | `spawn` 在启动 worker 前运行发现（fail-closed，不启动子代理）；`complete` 在 `tower_complete` 时运行；`off` 只在显式 `tower_test` 时运行。 |
+| `tests.timeoutMs` | `60000` | 每条发现命令的超时。 |
+| `tests.maxBytes` | `16777216`（16 MiB） | 每条命令捕获的 stdout 上限。 |
+| `tests.autoChecks` | `true` | 向完成报告附加自动 `tests` 检查。 |
+| `tests.allowPackageDiscovery` | `true` | 允许仓库控制的 `tower.testDiscovery` 命令（会执行 worktree 代码；见安全页）。 |
+| `gates.requireChecks` | `false` | 合并前要求至少一条 `tower_complete.checks` 证据（`no-check-evidence`）。 |
+| `gates.requireTests` | `false` | 要求针对被审查 tip 的通过测试回执（`tests-missing`）。 |
+| `gates.allowReviewExemption` | `false` | 允许用 `reviewPolicy:"none"` + 理由跳过审查 blocker；默认故意关闭。 |
+| `docs.board` | `true` | 变更后写入 `MISSIONS.md`。 |
+| `docs.boardLocation` | `common` | `common` = `<git-common-dir>/dsh-tower/MISSIONS.md`；`repo` = `<repoRoot>/MISSIONS.md`。 |
+| `leases.ttlMs` | `900000` | 默认咨询式租约寿命；过期不会自动释放。 |
+| `dev.hotReload` | `true` | 注册 `tower_reload`；关闭时 `/tower reload` 也被禁用。无 HMR 服务时调用返回 `reload-unavailable`。 |
+| `dev.reloadDelayMs` | `50` | 计划中的 reload 延迟，先让工具结果送达。 |
+| `dev.reloadRequiredIds` | 四个 Tower loader id | 作为 required 传给 `reconcileProfile` 的条目 id。 |
+
+## 示例
+
+```yaml
+- id: tower
+  name: 'dsh-tower'
+  config:
+    mode:
+      allowAgentControl: true
+      sectionAppend: 'Team conventions: tests are mandatory.'
+      workspaceLock: true
+    review:
+      maxRoundsPerReviewer: 3
+    merge:
+      timeoutMs: 1800000
+    spawn:
+      reviewerModel:
+        provider: deepseek-account
+        model: deepseek-flash
+    dev:
+      hotReload: true
+```
+
+## 查看实际生效的 schema
+
+插件声明 `Config` 后（本版本已声明），用 `cordis_inspect_query` 调用
+`Config.listConfigs({ name: "dsh-tower" })` 可返回投影后的 JSON Schema。

package/docs/zh/reference/doctor.md

@@ -0,0 +1,30 @@
+# Doctor
+
+[English](../../reference/doctor.md) | **简体中文**
+
+`tower_doctor({repoRoot})` 是只读的。它从不获取 state 锁、写状态或改动 Git。它返回：
+
+```json
+{
+  "ok": true,
+  "checks": [
+    { "id": "git", "status": "pass", "detail": "git version 2.55.0" },
+    { "id": "state", "status": "pass", "detail": ".../state.json revision 7" }
+  ],
+  "environmentContract": {
+    "platform": "win32",
+    "gitVersion": "git version 2.55.0",
+    "repoRoot": "D:/repo",
+    "commonDir": "D:/repo/.git",
+    "stateDir": "D:/repo/.git/dsh-tower"
+  }
+}
+```
+
+检查覆盖：git 可用性、仓库身份、state schema/加载、仓库配置是否存在、worker/reviewer preset 名称、
+subagents 与 HMR 服务、workspace 锁持有者/是否过期、实时 roster、worktree 是否存在/归属/是否脏、
+test-discovery 策略、旧版快照、batch 与租约。`warn` 是提示；`fail` 表示仓库在 spawn/merge 前需要
+处理。state 加载失败会作为失败的检查报告而不是抛出，因此 doctor 在损坏的仓库上仍然有用。
+
+环境契约仅供参考；它不是身份或授权证明。`tower_init` 仍要求控制塔角色，`tower_spawn` 仍会检查
+实时子代理目录。

package/docs/zh/reference/errors.md

@@ -0,0 +1,52 @@
+# 工具错误码
+
+[English](../../reference/errors.md) | **简体中文**
+
+工具失败是抛出的错误，不是 `{ok:false}` 结果（门禁结果是例外：见 [blockers.md](blockers.md)）。
+每个抛出的错误都以稳定 code 作为消息前缀：
+
+```
+[tower:mission-not-found] unknown mission "M9"
+```
+
+调用方可以匹配前缀，而不必匹配文案。下面的 code 保留给对应条件；没有更具体匹配的消息会报告为
+`tool-internal`。
+
+| Code | 含义 | 典型触发 |
+|---|---|---|
+| `invalid-argument` | 工具参数缺失、格式错误或不被允许。 | 缺少 `missionId`/`id`；未知状态；空 report；非法 scope glob；`timeoutMs < 1000`；更新时传入 `status: "all"`。 |
+| `repo-invalid` | `repoRoot` 缺失、是相对路径，或不在 Git 仓库内。 | 传入的路径所在目录不是仓库 |
+| `not-initialized` | 该仓库尚未初始化 Tower。 | 在 `tower_init` 之前调用读取类工具 |
+| `mission-not-found` | 不存在该 id 的 mission。 | 过期或拼错的 `M9` |
+| `finding-not-found` | 不存在该 id 的 finding。 | `tower_findings({id:"F99"})` |
+| `invalid-transition` | 请求的状态转换不被允许。 | 尝试 blocked→merged；finding 状态图之外的流转；reviewer 修改 finding；在还有未完成任务、blocker、无提交或未读消息时完成 mission。 |
+| `state-locked` | 另一个 Tower 写入者持有 state 锁。 | 锁超时后的并发写 |
+| `state-corrupt` | Tower state 文件不可读或无效。 | 手工编辑过的 `state.json` |
+| `config-invalid` | Tower 配置无效。 | 格式错误的仓库 `config.json`、违反 schema 的值 |
+| `config-unknown-key` | Tower 配置存在未知顶层键。 | 例如把键拼成 `allowAgentToggle` |
+| `git-failed` | git 命令因未归入其他分类的原因失败。 | 被拒绝的合并命令、非法 ref |
+| `git-timeout` | git 命令超时或输出超出缓冲区。 | 慢 pre-merge 钩子、超大 diff |
+| `spawn-unavailable` | subagents 服务不可用。 | 没有 `subagents` 的 Host |
+| `provider-missing` | 没有注册的 subagent provider。 | provider 列表为空 |
+| `preset-missing` | 配置的 agent preset 未注册。 | 缺少 `tower-worker`/`tower-reviewer` preset 行、DSH 未重启 |
+| `reviewer-prerequisite` | reviewer spawn 的前置条件未满足。 | mission 尚未 `completed` 或还没有 worktree 就 spawn reviewer |
+| `not-authorized` | 调用方 agent 角色无权执行该操作。 | worker 调用仅限控制塔的工具，或修改 mission 状态/scope；reviewer 修改 finding |
+| `workspace-busy` | 另一个 Tower 会话持有该仓库的 workspace 锁。 | `mode.workspaceLock:true` 时第二个会话调用仓库级工具 |
+| `worker-limit` | 仓库达到 `spawn.maxLiveWorkers` 个活跃 worker。 | 默认上限下 spawn 第五个 worker |
+| `rate-limited` | 达到 `tower_send` 的每分钟速率限制。 | 超出 `send.maxPerMinute`；稍后重试 |
+| `takeover-refused` | mission 仍有运行中的 worker。 | 在 `tower_interrupt` 之前调用 `tower_spawn({takeover:true})` |
+| `reload-unavailable` | 当前 profile 中没有可用的 DSH HMR 服务。 | 在没有 HMR 的 profile 上调用 `tower_reload` / `/tower reload` |
+| `reload-failed` | HMR reload 失败。 | `reconcileProfile` 抛错；检查 DSH 日志并重启 |
+| `tests-failed` | 声明的测试发现失败，或不满足准入要求。 | 命令非零退出、输出格式错误、minCount/required 不足 |
+| `tests-timeout` | 测试发现超出时间或输出预算。 | `tests.timeoutMs`，或 stdout 超过 `tests.maxBytes` |
+| `lease-busy` | 另一个持有者拥有请求的咨询式租约。 | `heavy-ci` 被持有时调用 `tower_resource acquire` |
+| `lease-token` | 租约释放 token 与持有者不匹配。 | 用另一个会话的 token 释放 |
+| `batch-invalid` | batch 请求或其 close 证据无效。 | 未知成员、重复 id、不安全的回执路径、缺少回执哈希 |
+| `legacy-invalid` | 旧版快照或映射无效。 | 未知 schema、源路径位于 Tower state 目录内、映射重写 |
+| `tool-internal` | 意外失败。 | bug；阅读消息与 activity 日志 |
+
+## 为什么抛出？
+
+返回 `{ok:false}` 的形状保留给控制塔能决定的预期策略结果（`tower_merge`/`tower_rebase` 的门禁
+blocker 以及 `tower_preflight`）。任何阻止工具给出决策的问题都会抛出，以免模型把它误当成正常的
+否定结果。