tianshu-mcp 0.6.4 → 0.6.6

package/CHANGELOG.en.md

@@ -8,6 +8,63 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.6.6] - 2026-09-24
+
+### Added
+
+- **Dry-run mode `dryRun` for `run_task`** ([issue #21](https://github.com/lanlan0811/tianshu-mcp/issues/21)): the agent analyses and plans only — outputting the file list and approach **without touching source** — and the acceptance engine performs static analysis only (do the referenced files exist, do the proposed edit locations exist, any obvious logical conflicts), skipping typecheck/test/build. See [dryRun mode](docs/dry-run.en.md).
+- **`src/verify/dry-run.ts`**: plan schema (`path` / `action` / `reason` / `edits`), the static checks, and the report / plan-document renderers.
+- **A review-then-do loop**: the plan document produced by a dry run lands **inside the project** at `.tianshu-mcp/dry-run-plan-<taskId>.md`, with `meta.dryRunPlanDoc` giving the project-relative path, directly usable as a later real `run_task`'s `planDoc`.
+
+### Changed
+
+- **`TaskMeta` gained `dryRun` / `dryRunReportMd` / `dryRunReportJson` / `dryRunPlanMd`**; `metaFromTask` exposes `dryRun` / `dryRunReportFiles` / `dryRunPlanDoc`.
+- Report artifacts are **strictly separated**: a dry run writes `dry-run-report-<round>.md` / `.json` (the JSON carries `kind: "dry-run"`) and **never touches** `report-<round>.*`, so it consumes no acceptance round and does not pollute the regular report list.
+
+### Compatibility
+
+- **`dryRun` is a new optional argument, off by default**: when omitted, `run_task` behaves exactly as in v0.6.5.
+- No tool contract or breaking data-model changes; MCP annotations unchanged.
+
+### Notes (disclosed honestly)
+
+- **The verdict is `needs_attention`, not `failed`**: a bad plan needs a human decision, not automatic rework; a dry run **never enters the rework loop**, **ignores `autoVerify`** and **requires `projectPath`** (project-less mode rejects it explicitly).
+- **A missing plan degrades but stays visible**: `planExtracted: false` plus a `fallbackReason` stating why, with checks degrading to the zero-change gate only; both the report and the message state "plan extraction: failed" honestly instead of passing silently.
+- **The zero-change gate is the core evidence**: diffing against the pre-work baseline, changes remaining after excluding MCP-owned artifacts (the plan file and any `planDoc` named in the task book) yield `dry_run_violation` (blocking). It **does not depend on the plan being correct** — it still works when the agent produces no plan at all.
+- **The agent is not guaranteed to obey the read-only constraint**: that relies on explicit task-book instructions plus the post-hoc gate. **Violations are caught and reported honestly, but changes that already happened are not rolled back** (the MCP never auto-commits, auto-stashes or auto-checks-out).
+- **Static checks cannot judge whether a plan is sensible**: they only verify "the file exists, the location matches, no obvious contradiction" — which is exactly what the human review step is for.
+- **Adapter differences around `planDoc`**: it is currently consumed only by the **Codex and Qoder CN** prompt builders; CLI agents and ZCode / Kimi Code / TraeWork do not read it, so for those the plan path must go into the `task` text (the file is inside the project, so they can read it). This is documented in both `docs/dry-run` files and the README.
+
+## [0.6.5] - 2026-09-24
+
+### Added
+
+- **Three-level acceptance config inheritance** ([issue #20](https://github.com/lanlan0811/tianshu-mcp/issues/20)): `<data home>/acceptance.default.json` (global fallback) → `<project>/.tianshu-mcp/acceptance.json` (project override) → transient task-level override. With several similar projects under one host, the shared policy goes in the global layer instead of a file per project. See the [acceptance config spec](docs/acceptance-config.en.md).
+- **New optional `acceptanceOverride` on `run_task` / `verify_task`**: a transient task-level acceptance-config override (same format as `acceptance.json`) that applies **only to that task**, is saved with the task snapshot, writes no `acceptance*.json` and affects no other task on the same project. Project-less mode explicitly rejects the argument.
+- **`tianshu-mcp config acceptance [projectPath] [--task <taskId>]` debug command**: prints which layers exist, the effective order and the final values, so troubleshooting needs no guesswork. Each acceptance round also writes a same-source summary line to `server.log`.
+- New `src/config/acceptance-merge.ts` (a purpose-scoped merge helper, **deliberately not a general-purpose deep merge**).
+
+### Fixed
+
+- **The `.default()` pollution hazard in layered parsing**: `AcceptanceConfigSchema` puts `.default(true)` on `requireChanges`, so parsing a project file that only sets `verifyConcurrency` materializes `requireChanges: true`, which in the three-level chain would **in turn override the global layer's `false`**. A default-free `PartialAcceptanceConfigSchema` is now used for layered parsing, with defaults applied only when the final value is absent.
+
+### Changed
+
+- `resolveChecks()` now performs the three-level merge and returns the merged `visual` too; `executeVerify` no longer re-reads the project file (otherwise the `visual` from override/global layers would change meaning based on whether a project file happens to exist).
+- After the unified `LOCKFILE_PATTERN` export (v0.6.4), the bilingual `acceptance-config` precedence tables were rewritten around the three-level chain.
+
+### Compatibility
+
+- **No tool contract, data model or MCP annotation changes** (`acceptanceOverride` is a new optional argument; `extraChecks` semantics and precedence are unchanged and still rank above the base set).
+- Without creating a global `acceptance.default.json`, single-project behaviour is exactly as in v0.6.4 (an absent global layer = empty config, no error).
+- The existing semantics of the project-level `.tianshu-mcp/acceptance.json` are unchanged; error semantics remain fail-closed (only `ENOENT` counts as "layer absent").
+
+### Notes (disclosed honestly)
+
+- **Merge granularity is per field**: a field a higher layer explicitly writes wins outright; **arrays (`checks`) replace wholesale rather than concatenating** — concatenating would turn "the project adds one check" into "the project can never remove a global check".
+- **`visual` replaces wholesale and is not deep-merged across layers**: nearly every field of the `visual` schema carries a default, so deep merging would let a higher layer's "not written, present only as a default" fields silently clobber a lower layer's **explicit** values (the same pollution class as `requireChanges`). To reuse visual config across layers, write the full `visual` block in the project layer. **This is a deliberate deviation from the issue's suggested "deep merge"**, with the reasoning recorded in `docs/acceptance-config.en.md` and ARCHITECTURE §7.4.
+- **The task override is included in the idempotency argument digest**: replaying the same key with a different acceptance policy is rejected fail-closed rather than returning an old task built on a different policy.
+
 ## [0.6.4] - 2026-09-24
 
 ### Added

package/CHANGELOG.md

@@ -7,6 +7,63 @@
 
 ---
 
+## [0.6.6] - 2026-09-24
+
+### 新增
+
+- **`run_task` 干跑模式 `dryRun`**（[issue #21](https://github.com/lanlan0811/tianshu-mcp/issues/21)）：agent 只分析规划、输出将要修改的文件清单与方案、**不动源码**；验收引擎只做静态分析（引用文件是否存在、拟改位置是否存在、明显逻辑冲突），跳过 typecheck/test/build。详见 [dryRun 干跑模式](docs/dry-run.md)。
+- **`src/verify/dry-run.ts`**：计划 schema（`path` / `action` / `reason` / `edits`）、静态检查、报告与方案文档渲染。
+- **「先审后做」闭环**：dryRun 产出的方案文档落在**项目内** `.tianshu-mcp/dry-run-plan-<taskId>.md`，`meta.dryRunPlanDoc` 给出项目相对路径，可直接作为后续正式 `run_task` 的 `planDoc`。
+
+### 变更
+
+- **`TaskMeta` 新增 `dryRun` / `dryRunReportMd` / `dryRunReportJson` / `dryRunPlanMd`**；`metaFromTask` 暴露 `dryRun` / `dryRunReportFiles` / `dryRunPlanDoc`。
+- 报告产物**严格分离**：dryRun 写 `dry-run-report-<round>.md` / `.json`（json 带 `kind: "dry-run"`），**不碰** `report-<round>.*`，因此不消耗验收轮次、也不污染常规报告列表。
+
+### 兼容性
+
+- **`dryRun` 是新增可选参数，默认关闭**：不传时 `run_task` 行为与 v0.6.5 完全一致。
+- 无工具契约、数据模型破坏性变更；MCP 注解不变。
+
+### 说明（如实披露）
+
+- **判定为 `needs_attention` 而非 `failed`**：方案有问题属人工裁决，不是可以自动返修的代码缺陷；dryRun **不进入返修循环**、**忽略 `autoVerify`**、**需要 `projectPath`**（无项目模式显式拒绝）。
+- **计划缺失时降级但可见**：`planExtracted: false` + `fallbackReason` 写明原因，检查降级为仅零改动门禁；报告与文案都如实标注「计划提取: 失败」，不静默通过。
+- **零改动门禁是核心证据**：相对动工前基线求差，排除 MCP 自有产物（计划文件、任务书点名的 planDoc）后仍有变更 → `dry_run_violation`（阻断）。它**不依赖计划写对** —— agent 完全不产出计划时这条仍然有效。
+- **不保证 agent 遵守只读约束**：靠任务书里的明确指令 + 事后门禁。**违反会被拦下并如实报告，但已发生的改动不会自动回滚**（MCP 从不自动 commit / stash / checkout）。
+- **静态检查无法判断方案是否合理**：只能验证「文件存在、位置对得上、无明显矛盾」——那正是「先审」要人工做的事。
+- **`planDoc` 的适配器差异**：目前只由 **Codex 与 Qoder CN** 的提示词构造消费；CLI 类 agent 与 ZCode / Kimi Code / TraeWork 不读取它，对这些 agent 需把方案路径写进 `task` 文本（文件在项目内，它们能读）。这一点已写入 `docs/dry-run` 双语与 README。
+
+## [0.6.5] - 2026-09-24
+
+### 新增
+
+- **验收配置三级继承**（[issue #20](https://github.com/lanlan0811/tianshu-mcp/issues/20)）：`<数据目录>/acceptance.default.json`（全局兜底）→ `<project>/.tianshu-mcp/acceptance.json`（项目覆盖）→ 任务级临时覆盖。一个宿主下挂多个同类项目时，公共策略写全局层即可，不必逐项目建文件。详见 [验收配置规范](docs/acceptance-config.md)。
+- **`run_task` / `verify_task` 新增可选 `acceptanceOverride`**：任务级临时验收配置覆盖（格式同 `acceptance.json`），**仅当次生效**、随任务快照保存、不写入任何 `acceptance*.json`、不影响同项目其他任务。无项目模式显式拒绝该参数。
+- **`tianshu-mcp config acceptance [projectPath] [--task <taskId>]` 调试命令**：打印各层是否存在、实际生效顺序与最终取值，排障无需靠猜。每轮验收另往 `server.log` 写一行同源摘要。
+- 新增 `src/config/acceptance-merge.ts`（按用途收敛的合并工具，**刻意不做通用深合并**）。
+
+### 修复
+
+- **分层解析的 `.default()` 污染隐患**：`AcceptanceConfigSchema` 的 `requireChanges` 带 `.default(true)`，若用它解析「只写了 `verifyConcurrency`」的项目文件会 materialize 出 `requireChanges: true`，在三级继承里**反过来覆盖全局层的 `false`**。新增无默认值的 `PartialAcceptanceConfigSchema` 供分层解析，默认值只在最终取值缺省时兜底。
+
+### 变更
+
+- `resolveChecks()` 改为三级合并，并把合并后的 `visual` 一并返回；`executeVerify` 不再二次读取项目文件（否则 override/全局层的 `visual` 会随项目文件是否存在而改变语义）。
+- `LOCKFILE_PATTERN` 的统一导出（v0.6.4）之后，`acceptance-config` 双语优先级表按三级继承重写。
+
+### 兼容性
+
+- **无工具契约、数据模型或 MCP 注解变更**（`acceptanceOverride` 是新增可选参数；`extraChecks` 语义与优先级不变，仍高于基础集）。
+- 不创建全局 `acceptance.default.json` 时，单项目行为与 v0.6.4 完全一致（全局层缺失 = 空配置、不报错）。
+- 项目级 `.tianshu-mcp/acceptance.json` 的既有语义不变；错误语义仍是 fail-closed（仅 `ENOENT` 视为「该层不存在」）。
+
+### 说明（如实披露）
+
+- **合并粒度是「字段」**：高优先级层显式书写的字段整体取胜；**数组（`checks`）整体覆盖而非拼接** —— 拼接会让「项目追加一项检查」变成「项目无法移除全局检查」。
+- **`visual` 整体覆盖、不做跨层深合并**：`visual` 的 schema 几乎每个字段都带默认值，深合并会让低优先级层的**显式**取值被高优先级层「未书写、仅因默认值而出现」的字段静默覆盖（与 `requireChanges` 同类的污染）。需要跨层复用视觉配置时请在项目层写完整 `visual` 段。**这是与 issue 建议的「深合并」的一处有意偏离**，理由记录在 `docs/acceptance-config.md` 与 ARCHITECTURE §7.4。
+- **任务级覆盖计入幂等入参摘要**：同键换一套验收策略会被 fail-closed 拒绝，而不是返回策略不同的旧任务。
+
 ## [0.6.4] - 2026-09-24
 
 ### 新增

package/README.en.md

@@ -41,8 +41,10 @@ Tianshu plays the role of the overall commander; this MCP server is the **schedu
 - **Async contract**: `run_task` returns a `taskId` immediately; long-running work is polled via `query_task` (never blocks `tools/call`).
 - **Long-task observability (issue #18)**: adapters report fine-grained events at key nodes (`task_dispatched` / `confirmation_dialog_detected` / `awaiting_user_authorization` / `file_modification_started` / `rework_triggered`), and `query_task` returns the most recent N via `eventLimit` (default 10) — **so you can tell "the agent is working" apart from "stuck on a dialog waiting for a human"**. Event reporting is an optional capability: adapters that don't implement it behave unchanged. codex and traework report in this version. See [event stream](docs/event-stream.en.md).
 - **Structured repair directives (issue #19)**: failed rounds parse the reasons into **directly executable actions** (`file:line / issue / action`) carried in both the repair plan and the rework message, sparing the agent the cost of locating problems in a full narrative report; when extraction is unavailable it **explicitly falls back** to the full report (never a silent gap). `rework_task` also accepts an optional `repairHint`. See [structured repair directives](docs/repair-directives.en.md).
+- **Dry-run mode (issue #21)**: `run_task(dryRun=true)` makes the agent **analyse and plan only — outputting the file list and approach without touching source**; the acceptance engine then does static analysis only (do the referenced files exist, do the proposed edit locations exist, any obvious logical conflicts) and skips typecheck/test/build. A bad plan yields `needs_attention` (a human decision), never enters automatic rework, and **consumes no acceptance round**. Two separate artifacts: a static-analysis report plus a plan document inside the project (`meta.dryRunPlanDoc`, directly usable as a later real task's `planDoc`), forming a review-then-do loop. See [dryRun mode](docs/dry-run.en.md).
 - **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. The acceptance engine is **fail-closed**: a test check fails when its output reports zero executed tests even if the exit code is 0; git projects must produce changes relative to the pre-work baseline by default (pure analysis tasks can opt out with `"requireChanges": false` in `.tianshu-mcp/acceptance.json`).
 - **Acceptance parallelism**: command checks run **bounded-parallel** by default (`verifyConcurrency`, default 2, range 1–4). When checks depend on an order (a later check reading build output, `--fix`, shared cache dirs), set it to `1` for fully serial behaviour; a project can override it in `.tianshu-mcp/acceptance.json`, and the server level lives in `config.json`. Report and log formats are unchanged (results are returned in declaration order).
+- **Three-level acceptance config inheritance (issue #20)**: `<data home>/acceptance.default.json` (global fallback) → `<project>/.tianshu-mcp/acceptance.json` (project override) → the `acceptanceOverride` argument of `run_task`/`verify_task` (transient task override, applying only to that task and never written to disk as config). For the same field a higher layer wins; arrays replace wholesale rather than concatenating. Inspect the final effective configuration with `tianshu-mcp config acceptance <projectPath> [--task <id>]`. See the [acceptance config spec](docs/acceptance-config.en.md).
 - **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.
 - **Execution surfaces**: `driver: "gui"` selects an explicit, isolated Codex/TraeWork/ZCode/Kimi Code/Qoder CN CDP adapter; `driver: "spawn"` runs an external CLI child process.
 - **Project-less dispatch (ZCode, issue #12)**: `run_task`'s `projectPath` may be omitted — ZCode runs the task in its `default` workspace without registering/importing a project, collecting a Git baseline, or running project acceptance (the result is marked structurally as `verificationNotApplicable: "no_project"` and `verify_task`/`get_task_report` return a not-applicable explanation). The companion `allowCreateProject: false` stops dispatch before any import side effect when the target directory is unregistered. See the [ZCode CDP adapter](docs/zcode-cdp.en.md).
@@ -188,7 +190,7 @@ run_task(projectPath=D:/xxx/my-app, agentId=qoder, planDoc=./plans/development.m
 
 | Tool | Capability / approval | Purpose |
 |---|---|---|
-| `run_task` | write + approval | Dispatch work (optional auto-verify / auto-rework); returns `taskId` asynchronously. Optional `idempotencyKey`: a retry with the same key returns the original `taskId` instead of creating a task |
+| `run_task` | write + approval | Dispatch work (optional auto-verify / auto-rework); returns `taskId` asynchronously. Optional `idempotencyKey` (a retry with the same key returns the original `taskId` instead of creating a task), `acceptanceOverride` (transient acceptance-config override applying only to this task) and `dryRun` (dry-run mode: plan only without touching source; its artifact feeds a later `planDoc`) |
 | `continue_task` | write + approval | Resume the session behind `needs_user` (ZCode resumes the recorded session; Codex re-observes for `user_confirmation` / re-dispatches for `login_required`; Kimi Code resumes the recorded session and distinguishes question answering / re-observation / full re-dispatch) |
 | `query_task` | read | Poll status / progress / log tail / recent fine-grained events. The optional `eventLimit` (1..50, default 10) controls how many `recentEvents` the meta block carries, so long tasks can be told apart as "working normally" versus "stuck on a dialog waiting for a human" |
 | `list_tasks` | read | Filtered history of tasks |

package/README.md

@@ -42,8 +42,10 @@
 - **长任务可观测（issue #18）**：适配器在关键节点上报细粒度事件（`task_dispatched` / `confirmation_dialog_detected` / `awaiting_user_authorization` / `file_modification_started` / `rework_triggered`），`query_task` 经 `eventLimit`（默认 10）回传最近 N 条——**能区分「agent 正在干活」与「卡在弹窗等人工介入」**。事件上报是可选能力：未实现的适配器行为不变。本版 codex 与 traework 已落地上报。详见 [事件流](docs/event-stream.md)。
 - **客观验收**：自动命令检查（typecheck/lint/test/build，缺则跳过 + 技术栈推导）+ 程序化代码分析（变更清单/diffstat/TODO·debugger·密钥形态等可疑标记），全部相对 **git 基线**，不自动 commit/stash。验收引擎 **fail-closed**：测试命令退出码为 0 但输出显示零用例时判失败；git 项目默认要求相对动工前基线产生变更（纯分析任务可在 `.tianshu-mcp/acceptance.json` 设 `"requireChanges": false` 显式关闭）。
 - **验收并行度**：命令检查默认**有界并行**（`verifyConcurrency`，默认 2、范围 1–4）。检查项之间有顺序依赖时（后续检查读取 build 产物、带 `--fix`、共享缓存目录）请设 `1` 完全退化为串行；项目级 `.tianshu-mcp/acceptance.json` 可覆盖，server 级在 `config.json`。报告与日志格式不变（结果按声明顺序返回）。
+- **验收配置三级继承（issue #20）**：`<数据目录>/acceptance.default.json`（全局兜底）→ `<project>/.tianshu-mcp/acceptance.json`（项目覆盖）→ `run_task`/`verify_task` 的 `acceptanceOverride` 参数（任务级临时覆盖，仅当次生效、不落盘为配置）。同名字段高优先级取胜、数组整体覆盖不拼接。用 `tianshu-mcp config acceptance <projectPath> [--task <id>]` 查看最终生效配置。详见 [验收配置规范](docs/acceptance-config.md)。
 - **失败返修闭环**：自动返修（`autoFixRounds`）+ 手动 `rework_task`；验收失败时自动生成修复计划文件并回填给 agent；轮次用尽 → `needs_attention` 等天枢裁决。
 - **结构化修复指令（issue #19）**：失败轮次会把原因解析为**可直接执行的动作**（`文件:行 / 问题 / 做什么`），随返修计划与返修消息一起喂给 agent，省去它从整篇报告里定位的开销；提取不到时**显式回退**到完整报告（不静默留空）。`rework_task` 另可选 `repairHint` 自带提示。详见 [结构化修复指令](docs/repair-directives.md)。
+- **干跑模式 dryRun（issue #21）**：`run_task(dryRun=true)` 让 agent **只分析规划、输出将要修改的文件清单与方案、不动源码**；验收引擎只做静态分析（引用文件是否存在、拟改位置是否存在、明显逻辑冲突），跳过 typecheck/test/build。方案有问题 → `needs_attention`（人工裁决），不进入自动返修、**不消耗验收轮次**。产物分两份：静态分析报告 + 项目内的方案文档（`meta.dryRunPlanDoc`，可直接作为后续正式任务的 `planDoc`），构成「先审后做」闭环。详见 [dryRun 干跑模式](docs/dry-run.md)。
 - **执行面**：`driver: "gui"` 由显式 adapter 驱动桌面 UI（Codex / TraeWork / ZCode / Kimi Code 各自使用隔离的 CDP 流程）；`driver: "spawn"` 走外部 CLI 子进程。
 - **无项目派发（ZCode，issue #12）**：`run_task` 的 `projectPath` 可省略——ZCode 在 `default` 工作区承接任务，不登记/导入项目、不采集 Git 基线、不执行项目验收（结果以 `verificationNotApplicable: "no_project"` 结构化标注，`verify_task`/`get_task_report` 返回不适用说明）。配套 `allowCreateProject: false` 可在目标目录未登记时于任何导入副作用之前停止派发。详见 [ZCode CDP 适配器](docs/zcode-cdp.md)。
 - **幂等重试（issue #15）**：`run_task` / `verify_task` 接受可选 `idempotencyKey`——同一 key 在 TTL（默认 24h）内的重试**不会**重复派单（恒返回原 `taskId` 与当前状态）或重复跑验收（执行中返回进行中提示，已完成直接返回既有报告）；同键异参 fail-closed 报错。映射落盘于 `<数据目录>/idempotency.json`，跨 server 重启仍生效。详见 [v0.5.10 发布说明](<docs/release-v0.5.10.md>)。
@@ -184,7 +186,7 @@ run_task(projectPath=D:/xxx/my-app, agentId=qoder, planDoc=./plans/development.m
 
 | 工具 | 能力 / 审批 | 作用 |
 |---|---|---|
-| `run_task` | write + 审批 | 派活（可带自动验收/自动返修），异步返回 `taskId`；可选 `idempotencyKey`：同键重试恒返回原 `taskId`，不新建任务 |
+| `run_task` | write + 审批 | 派活（可带自动验收/自动返修），异步返回 `taskId`；可选 `idempotencyKey`（同键重试恒返回原 `taskId`，不新建任务）、`acceptanceOverride`（任务级临时验收配置覆盖，仅本任务生效）与 `dryRun`（干跑模式：只分析规划不改源码，产物可作后续 `planDoc`） |
 | `continue_task` | write + 审批 | 恢复 `needs_user` 的原会话（ZCode 恢复原会话；Codex 按 `user_confirmation` 重新观察 / `login_required` 重派；Kimi Code 恢复原会话并区分提问续答 / 重新观察 / 补发任务书） |
 | `query_task` | read | 轮询状态 / 进度 / 日志尾 / 最近细粒度事件。可选 `eventLimit`（1..50，默认 10）控制 meta 的 `recentEvents` 条数，长任务下可区分「正常执行」与「卡在弹窗等人」 |
 | `list_tasks` | read | 历史任务过滤列表 |

package/dist/config/acceptance-merge.js

@@ -0,0 +1,36 @@
+/**
+ * 合并两层配置：override 中**显式书写**的字段整体取代 base 的同名字段。
+ * `undefined` 视为「本层未书写」，不参与覆盖（否则 `{requireChanges: undefined}` 会误清空下层取值）。
+ */
+export function mergeAcceptanceConfig(base, override) {
+    const out = { ...(base ?? {}) };
+    const target = out;
+    for (const [key, value] of Object.entries(override ?? {})) {
+        if (value !== undefined)
+            target[key] = value;
+    }
+    return out;
+}
+/** 按数组顺序（低 → 高优先级）依次合并；缺失层直接跳过 */
+export function resolveAcceptanceLayers(layers) {
+    let config = {};
+    const applied = [];
+    for (const layer of layers) {
+        if (!layer.config)
+            continue;
+        config = mergeAcceptanceConfig(config, layer.config);
+        applied.push({ source: layer.source, path: layer.path });
+    }
+    return { config, applied };
+}
+/** 供调试命令/日志使用的一行摘要（不打印任何凭证，只打层与最终取值） */
+export function summarizeResolved(resolved) {
+    const c = resolved.config;
+    return [
+        `生效层=${resolved.applied.map((a) => a.source).join(">") || "（无）"}`,
+        `checks=${c.checks ? c.checks.length : "（默认集）"}`,
+        `requireChanges=${c.requireChanges ?? "（默认 true）"}`,
+        `verifyConcurrency=${c.verifyConcurrency ?? "（继承 server config）"}`,
+        `visual=${c.visual ? "已覆盖" : "（未配置）"}`,
+    ].join(" ");
+}

package/dist/config/cli.js

@@ -0,0 +1,160 @@
+/**
+ * `tianshu-mcp config …` CLI 子命令（issue #20）。
+ *
+ * 目的：三级继承（全局 / 项目 / 任务级覆盖）生效后，「最终到底用了哪几层、每层贡献了什么」
+ * 必须可查——否则排障只能靠猜。输出走 `console.log`，**绝不触碰协议 stdout**
+ * （与 `visual/cli.ts` 同一约定；本命令在创建 MCP server 之前返回）。
+ *
+ * 不挂在 `visual` 命名空间下：`acceptance.json` 是验收引擎的配置，视觉验收只是共用一个文件，
+ * 混进 visual 会误导使用者。
+ *
+ * 用法：
+ *   tianshu-mcp config acceptance [projectPath] [--task <taskId>]
+ */
+import path from "node:path";
+import { readAcceptanceLayer } from "../visual/config.js";
+import { resolveAcceptanceLayers, summarizeResolved } from "./acceptance-merge.js";
+import { resolveDataHome } from "./store.js";
+import { readJsonSafe } from "../util/fs.js";
+export async function runConfigCli(args) {
+    const [scope, ...rest] = args;
+    if (scope !== "acceptance") {
+        console.log(JSON.stringify({
+            ok: false,
+            error: `未知的 config 子命令: ${scope ?? "(空)"}`,
+            usage: [
+                "tianshu-mcp config acceptance [projectPath] [--task <taskId>]",
+                "",
+                "打印验收配置三级继承（全局 / 项目 / 任务级覆盖）的生效情况与最终取值。",
+            ],
+        }, null, 2));
+        return;
+    }
+    const result = await inspectAcceptance(rest);
+    console.log(JSON.stringify(result, null, 2));
+}
+/** 解析 `[projectPath] [--task <taskId>]`（顺序无关，两者都可省） */
+function parseArgs(rest) {
+    let projectPath;
+    let taskId;
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === "--task") {
+            taskId = rest[i + 1];
+            if (!taskId)
+                return { error: "--task 需要一个 taskId 参数" };
+            i++;
+        }
+        else if (a.startsWith("--")) {
+            return { error: `未知选项: ${a}` };
+        }
+        else if (projectPath === undefined) {
+            projectPath = a;
+        }
+        else {
+            return { error: `多余的参数: ${a}` };
+        }
+    }
+    return { projectPath, taskId };
+}
+/**
+ * 收集并解析三层配置。**不抛错**：某层写坏时把错误放进该层的 `error` 字段并让整体
+ * `ok: false`，这样调试命令仍然能把「是哪一层坏了」显示出来（而不是只吐一句异常）。
+ */
+export async function inspectAcceptance(rest) {
+    const parsed = parseArgs(rest);
+    if (parsed.error) {
+        return { ok: false, error: parsed.error, layers: [], appliedOrder: [], effective: emptyEffective(), summary: "" };
+    }
+    const home = resolveDataHome();
+    const globalPath = path.join(home, "acceptance.default.json");
+    const projectPath = parsed.projectPath ? path.resolve(parsed.projectPath) : undefined;
+    const projectFile = projectPath ? path.join(projectPath, ".tianshu-mcp", "acceptance.json") : undefined;
+    const layers = [];
+    let taskError;
+    // 层的 label 统一用 source 名（global / project）：它与 CLI 输出的 source 字段、
+    // 以及验收引擎报错文案里的层名同源，便于按字符串定位是哪一层出了问题。
+    const global = await readLayerInto(layers, "global", globalPath);
+    const project = projectFile
+        ? await readLayerInto(layers, "project", projectFile)
+        : (layers.push({ source: "project", path: "（未提供 projectPath）", present: false }),
+            undefined);
+    // 任务级覆盖来自任务快照（issue #20 把 override 持久化在 TaskMeta 上）
+    let override;
+    if (parsed.taskId) {
+        const metaPath = path.join(home, "tasks", parsed.taskId, "task.json");
+        const meta = await readJsonSafe(metaPath);
+        if (!meta) {
+            layers.push({ source: "override", path: metaPath, present: false });
+            taskError = `任务快照不可读或不存在: ${parsed.taskId}`;
+        }
+        else {
+            override = meta.acceptanceOverride;
+            layers.push({
+                source: "override",
+                path: `${metaPath}（TaskMeta.acceptanceOverride）`,
+                present: override !== undefined,
+                ...(override ? { config: override } : {}),
+            });
+        }
+    }
+    else {
+        layers.push({ source: "override", path: "（未提供 --task，无任务级覆盖）", present: false });
+    }
+    const mergedLayers = [
+        { source: "global", path: globalPath, config: global },
+        { source: "project", path: projectFile ?? "（未提供）", config: project },
+        { source: "override", path: "TaskMeta.acceptanceOverride", config: override },
+    ];
+    const resolved = resolveAcceptanceLayers(mergedLayers);
+    const anyLayerError = layers.some((l) => l.error);
+    const ok = !anyLayerError && !taskError;
+    return {
+        ok,
+        ...(projectPath ? { project: projectPath } : {}),
+        ...(parsed.taskId ? { taskId: parsed.taskId } : {}),
+        layers,
+        appliedOrder: resolved.applied.map((a) => a.source),
+        effective: {
+            checks: resolved.config.checks ? resolved.config.checks.length : "（默认集）",
+            requireChanges: resolved.config.requireChanges ?? "（默认 true）",
+            verifyConcurrency: resolved.config.verifyConcurrency ?? "（继承 server config）",
+            visual: resolved.config.visual ? "已覆盖" : "（未配置）",
+        },
+        summary: summarizeResolved(resolved),
+        ...(taskError ? { error: taskError } : {}),
+    };
+}
+async function readLayerInto(layers, source, absPath) {
+    try {
+        const config = await readAcceptanceLayer(absPath, source);
+        layers.push({
+            source,
+            path: absPath,
+            present: config !== null,
+            ...(config ? { config } : {}),
+        });
+        return config ?? undefined;
+    }
+    catch (e) {
+        // 该层写坏/读不了：如实登记为错误层，其余层继续解析（调试命令的价值正在于此）
+        layers.push({
+            source,
+            path: absPath,
+            present: true,
+            error: {
+                code: e.code ?? "CONFIG_ERROR",
+                message: e instanceof Error ? e.message : String(e),
+            },
+        });
+        return undefined;
+    }
+}
+function emptyEffective() {
+    return {
+        checks: "（默认集）",
+        requireChanges: "（默认 true）",
+        verifyConcurrency: "（继承 server config）",
+        visual: "（未配置）",
+    };
+}

package/dist/config/schema.js

@@ -47,6 +47,40 @@ export const IdempotencyScopeSchema = z.enum(["run_task", "verify_task"]);
 /** 幂等映射默认 TTL（24h）与条目上限（超限逐出最旧）。 */
 export const IDEMPOTENCY_TTL_DEFAULT_MS = 24 * 60 * 60_000;
 export const IDEMPOTENCY_MAX_ENTRIES_DEFAULT = 2000;
+/**
+ * 验收命令：**推荐数组形态**（结构化 argv，无歧义）。
+ * 字符串形态为兼容保留：经极简分词（不经过 shell），**不支持转义**，引号不闭合
+ * 不报错，含空格参数必须手写整段引号，写错会静默拆成多个 argv——详见 docs/acceptance-config.md。
+ */
+const CheckCmd = z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]);
+export const AcceptanceCheckSchema = z.object({
+    name: z.string().min(1),
+    cmd: CheckCmd,
+    timeoutMs: z.number().int().positive().optional(),
+    optional: z.boolean().optional(),
+});
+/**
+ * **分层**验收配置（issue #20）：每个字段都可选、**任何字段都不带 `.default()`**。
+ *
+ * 为什么必须与 `AcceptanceConfigSchema` 分开：`requireChanges` 在后者上有 `.default(true)`。
+ * 若用带默认值的 schema 去解析「只写了 verifyConcurrency」的项目文件，会 materialize 出
+ * `requireChanges: true`，在三级继承里**反过来把全局层的 `false` 覆盖掉** —— 这正是本次要修的隐患。
+ * 分层解析一律用本 schema，默认值只在最终生效值缺省时由消费方兜底。
+ */
+export const PartialAcceptanceConfigSchema = z.object({
+    checks: z.array(AcceptanceCheckSchema).optional(),
+    /** 注意：`visual` **不做跨层深合并**，最高优先级的层整段生效（理由见 docs/acceptance-config.md） */
+    visual: VisualConfigSchema.optional(),
+    requireChanges: z.boolean().optional(),
+    verifyConcurrency: z
+        .number()
+        .transform((n) => (Number.isFinite(n) ? Math.min(4, Math.max(1, Math.round(n))) : 1))
+        .optional(),
+});
+/** 兼容形态：在分层 schema 之上补回 `requireChanges` 的历史默认值（供既有 visual/legacy 调用方） */
+export const AcceptanceConfigSchema = PartialAcceptanceConfigSchema.extend({
+    requireChanges: z.boolean().default(true),
+});
 export const RunTaskParamsSchema = z.object({
     /**
      * 项目绝对路径。**省略** = 无项目模式（issue #12）：目前仅 ZCode 支持——任务在其 `default`
@@ -99,6 +133,21 @@ export const RunTaskParamsSchema = z.object({
      * 不新建任务；同一键携带不同参数会被 fail-closed 拒绝。不传 = 保持既有行为。
      */
     idempotencyKey: IdempotencyKeySchema.optional(),
+    /**
+     * 任务级临时验收配置覆盖（issue #20）：三级继承的最高优先级，**仅当次任务生效**。
+     * 会随任务快照保存（属任务数据，不是配置文件），rework/continue 沿用同一任务时继续生效，
+     * 不影响其他任务或项目。不传则完全沿用全局/项目层配置。
+     */
+    acceptanceOverride: PartialAcceptanceConfigSchema.optional(),
+    /**
+     * 干跑模式（issue #21）：agent **只分析、只规划**，输出将要修改的文件清单与方案，
+     * 不动源码；验收引擎只做静态分析（引用文件是否存在、拟改位置是否存在、明显逻辑冲突），
+     * 跳过 typecheck/test/build 等需要实际改动的检查。
+     *
+     * 默认关闭（缺省 = 与既有行为完全一致）。**需要 projectPath**：无项目模式没有可静态分析的基线。
+     * dryRun 下忽略 `autoVerify`、不进入自动返修。
+     */
+    dryRun: z.boolean().optional(),
 });
 /** query_task 返回的细粒度事件条数默认值（issue #18） */
 export const QUERY_TASK_EVENT_LIMIT_DEFAULT = 10;
@@ -126,18 +175,6 @@ export const CancelTaskParamsSchema = z.object({
     taskId: z.string().min(1),
     reason: z.string().optional(),
 });
-/**
- * 验收命令：**推荐数组形态**（结构化 argv，无歧义）。
- * 字符串形态为兼容保留：经极简分词（不经过 shell），**不支持转义**，引号不闭合
- * 不报错，含空格参数必须手写整段引号，写错会静默拆成多个 argv——详见 docs/acceptance-config.md。
- */
-const CheckCmd = z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]);
-export const AcceptanceCheckSchema = z.object({
-    name: z.string().min(1),
-    cmd: CheckCmd,
-    timeoutMs: z.number().int().positive().optional(),
-    optional: z.boolean().optional(),
-});
 export const VerifyTaskParamsSchema = z.object({
     taskId: z.string().optional(),
     projectPath: AbsPath.optional(),
@@ -155,6 +192,8 @@ export const VerifyTaskParamsSchema = z.object({
      * 已完成直接返回已有报告与轮次；同一键携带不同参数会被 fail-closed 拒绝。
      */
     idempotencyKey: IdempotencyKeySchema.optional(),
+    /** 任务级临时验收配置覆盖（issue #20）：三级继承的最高优先级，仅本次验收生效。 */
+    acceptanceOverride: PartialAcceptanceConfigSchema.optional(),
 });
 export const ReworkTaskParamsSchema = z.object({
     taskId: z.string().min(1),
@@ -427,14 +466,5 @@ export const ProjectRecordSchema = z.object({
 });
 /** projects.json 整体文件 schema（S5：不再用对象强制类型转换） */
 export const ProjectsFileSchema = z.record(z.string().min(1), ProjectRecordSchema);
-/* ---------------- 项目内 .tianshu-mcp/acceptance.json ---------------- */
-export const AcceptanceConfigSchema = z.object({
-    checks: z.array(AcceptanceCheckSchema).optional(),
-    visual: VisualConfigSchema.optional(),
-    requireChanges: z.boolean().default(true),
-    /** 命令检查并行度：1=串行（与历史行为一致）；缺省继承 server config.json 的 verifyConcurrency（默认 2）。越界值 clamp 到 1..4（不再株连整份 acceptance.json 失效） */
-    verifyConcurrency: z
-        .number()
-        .transform((n) => (Number.isFinite(n) ? Math.min(4, Math.max(1, Math.round(n))) : 1))
-        .optional(),
-});
+/* 项目内 .tianshu-mcp/acceptance.json 的 schema 定义见文件上方（须早于 RunTaskParamsSchema，
+   因为 run_task/verify_task 的 acceptanceOverride 参数引用它）。 */

package/dist/index.js

@@ -17,6 +17,12 @@ async function main() {
         await runVisualCli(process.argv.slice(3));
         return;
     }
+    // issue #20：验收配置三级继承的调试命令（在创建 server 之前返回，不触碰协议 stdout）
+    if (process.argv[2] === "config") {
+        const { runConfigCli } = await import("./config/cli.js");
+        await runConfigCli(process.argv.slice(3));
+        return;
+    }
     const home = resolveDataHome();
     const logger = await Logger.create(path.join(home, "logs"));
     const skipSkillInstall = process.argv.includes("--no-skill-install") || process.env.TIANSHU_MCP_NO_SKILL_INSTALL === "1";

package/dist/loop/fix-loop.js

@@ -6,11 +6,12 @@
  *
  * 并发闸/队列由 TaskManager 负责；这里只负责单任务推进（支持 AbortSignal 中止）。
  */
-import { readTextSafe, exists, readDirSafe, mkdirp, writeJsonAtomic, readJsonSafe, } from "../util/fs.js";
+import { readTextSafe, exists, readDirSafe, mkdirp, writeJsonAtomic, readJsonSafe, writeTextAtomic, } from "../util/fs.js";
 import { runChild } from "../agents/spawn.js";
 import { captureBaseline } from "../verify/git-baseline.js";
 import { summarizeReport } from "../verify/report.js";
 import { renderDirectiveLines } from "../verify/directives.js";
+import { DRY_RUN_PLAN_REL_PATH, dryRunPlanDocRelPath, renderDryRunPlanDoc, } from "../verify/dry-run.js";
 import { writeRepairPlan } from "./repair-plan.js";
 import { writeCodexFixPlan } from "../agents/codex/fixplan.js";
 import { buildFixPrompt } from "../agents/codex/input.js";
@@ -189,6 +190,47 @@ export class TaskOrchestrator {
                 if (runRes.killed) {
                     return this.abortTerminal(runRes.guiStop);
                 }
+                // ---- issue #21：dryRun 只做静态分析 ----
+                // 放在这里（agent 已返回、正常验收之前）的理由：先让 agent 跑完只读预演与计划产出，
+                // 再静态核对；硬失败/超时/取消/等人已在上面处理，不会走到这里。
+                // dryRun 刻意**忽略 autoVerify**（它本来就是「先审」而不是「验收」），也**不进返修循环**
+                // —— 方案有问题属人工决策，不是可以自动返修的代码缺陷。
+                if (meta.dryRun) {
+                    const dryReport = await this.deps.engine.runDryRun({
+                        taskId: meta.taskId,
+                        projectPath: meta.projectPath,
+                        round,
+                        baseline,
+                        taskText: meta.task,
+                        // 允许 agent 写的产物：计划文件本身，以及任务书里点名的 planDoc（若有）
+                        allowedArtifacts: [
+                            DRY_RUN_PLAN_REL_PATH,
+                            ...(meta.planDoc ? [meta.planDoc] : []),
+                        ],
+                        store,
+                    });
+                    meta.dryRunReportMd = store.dryRunReportMdPath(meta.taskId, round);
+                    meta.dryRunReportJson = store.dryRunReportJsonPath(meta.taskId, round);
+                    // 计划渲染成项目内 markdown，供后续正式任务作 planDoc 复用（「先审后做」闭环）
+                    if (dryReport.plan) {
+                        const rel = dryRunPlanDocRelPath(meta.taskId);
+                        const abs = path.join(meta.projectPath, ...rel.split("/"));
+                        await mkdirp(path.dirname(abs));
+                        await writeTextAtomic(abs, renderDryRunPlanDoc(dryReport));
+                        meta.dryRunPlanMd = abs;
+                    }
+                    const tail = [
+                        dryReport.summary,
+                        `静态分析报告：${meta.dryRunReportMd}`,
+                        meta.dryRunPlanMd
+                            ? `方案文档（可作为后续正式任务的 planDoc）：${dryRunPlanDocRelPath(meta.taskId)}`
+                            : "（未取得结构化计划，无法作为 planDoc 复用）",
+                    ].join("\n");
+                    // 方案有问题 → needs_attention（人工裁决），不是 failed（并非代码缺陷）
+                    return dryReport.passed
+                        ? this.finish("succeeded", null, tail)
+                        : this.finish("needs_attention", "verify_failed", tail);
+                }
                 if (!runRes.ok && !meta.autoVerify) {
                     return this.finish("failed", "agent_failed", runRes.error ??
                         `agent 执行失败（exit=${runRes.exitCode ?? "n/a"}）。日志 ${runRes.logFile}`);
@@ -457,6 +499,8 @@ export class TaskOrchestrator {
             round,
             config: await this.deps.dataHome.loadConfig(),
             projectVerify,
+            // issue #20：任务级临时覆盖（三级继承最高优先级），随任务快照持久化
+            acceptanceOverride: meta.acceptanceOverride,
             baseline,
             signal: this.signal,
             store,

package/dist/mcp/context.js

@@ -1,3 +1,28 @@
+/**
+ * dryRun 的只读预演约束（issue #21）。
+ *
+ * 注入点刻意选在这里而不是各个适配器的 prompt builder：全部 5 个适配器的提示词构造
+ * 都会拼 `ctx.context`（codex `input.ts`、traework `ui/composer.ts`、cli `cli.ts`、
+ * zcode/kimicode `run.ts`），因此**一次改动即覆盖全部适配器**；且 dryRun 是 round 0 的
+ * 首次派发，zcode/kimicode 仅在 `initialDispatch` 时附加 context 的守卫不会把它吞掉。
+ */
+export const DRY_RUN_CONSTRAINT = [
+    "【本任务是 dryRun 只读预演 —— 必须严格遵守】",
+    "",
+    "1. **不得创建、修改或删除任何源文件**；不要运行会改动工作区的命令（如格式化、自动修复、构建产物写入）。",
+    "   允许且**必须**写入的唯一文件是下面第 2 条要求的计划文件。",
+    "2. 必须把修改方案写成机器可读的计划文件：`.tianshu-mcp/dry-run-plan.json`（相对项目根），格式：",
+    "   ```json",
+    '   { "summary": "一句话方案", "files": [ { "path": "src/foo.ts", "action": "modify",',
+    '     "reason": "为什么要改", "edits": [ { "line": 42, "symbol": "functionName", "action": "怎么改" } ] } ] }',
+    "   ```",
+    '   `path` 必须是**项目相对路径**（不得写绝对路径、不得包含 `..`、不得指向 `.git` 或 `node_modules`）；',
+    '   `action` 取值为 `create` / `modify` / `delete`；`edits` 可选，但写了就要与文件真实内容对得上',
+    "   （行号必须在文件范围内、`symbol` 必须在文件中真实存在）—— 验收引擎会逐条静态核对。",
+    "3. 验收引擎只做静态分析（文件是否存在、拟改位置是否存在、是否有明显逻辑冲突），",
+    "   **不跑 typecheck / test / build**。因此请不要在回复里声称测试已通过。",
+    "4. 在回复里用自然语言说明方案要点即可；**不要**开始实施改动。",
+].join("\n");
 export function makeBuildCtx(services) {
     return (meta, round, feedback) => ({
         taskId: meta.taskId,
@@ -6,7 +31,10 @@ export function makeBuildCtx(services) {
         displayPath: meta.displayPath,
         agentId: meta.agentId,
         task: meta.task,
-        context: meta.context,
+        // dryRun：把只读预演约束并入 context（既有的用户 context 保留在前）
+        context: meta.dryRun
+            ? [meta.context, DRY_RUN_CONSTRAINT].filter((s) => s && s.trim() !== "").join("\n\n")
+            : meta.context,
         model: meta.model,
         reasoningLevel: meta.reasoningLevel,
         modelSource: meta.modelSource,