tianshu-mcp 0.5.0 → 0.5.2

package/CHANGELOG.en.md

@@ -10,24 +10,62 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ## [Unreleased]
 
-### Tests
-
-- Two additional real-browser-gated visual cases (added after v0.5.0): screenshots succeed when the project path contains CJK characters and spaces; a main-document 302 redirect to a non-allowlisted origin is blocked by policy and passes once explicitly allowed. Full suite: **486 passed / 10 skipped**.
-- New `npm run evidence:visual:windows` (`scripts/evidence-visual-windows.mjs`): collects the full Windows 10 local functional matrix (existing/static/command sources, port conflict that blocks without terminating another service, bounded readiness failure that cleans up the child process, local Edge isolated instance and version mismatch, missing-browser blocker), 9/9 passed.
-- Collected macOS 13+ platform evidence: on macOS 15 hardware runners, Intel x64 and Apple Silicon arm64 (Node 20/22/24) each passed 10 files with 51 cases; raw records are committed under `docs/visual-validation-evidence/`.
-
-### Docs
-
-- `docs/visual-validation{,.en}.md` rewritten with full platform evidence tables (system, Node, browser version, command, result), plus the new `docs/visual-validation-evidence/` raw machine-readable records.
-
 ### Planned
 
+- **Visual acceptance phase 2 — AI visual content validation** (issue #13): validate whether image/page-screenshot *content* matches the task description (logo elements, style match, page semantics, etc.). Marked in issue #3 as an "optional extension"; its pixel-comparison phase 1 shipped with v0.5.0. Requires settling the model/credential source (without breaking the "zero credential management" red line), judgement debouncing, and gate placement (warning-only by default is suggested).
 - More external AI-Agent adapters (a new agent = one profile + an optional adapter file).
 - TraeWork executable discovery and native-dialog driving on macOS (currently fail-closed).
 - Optional project-level skill seeding (by default nothing is written into target repos).
 - Cancel/rework/new-project matrices for the Codex and ZCode GUI drivers on macOS (both remain `research` on darwin).
 - Best-effort stop of a GUI-side pending session (via a temporary CDP connection) when cancelling
   a task in the `needs_user` state.
+- Real-machine verification of project-less dispatch on macOS (this round covers Windows 10 only).
+
+---
+
+## [0.5.2] — 2026-09-14
+
+**Project-less dispatch for ZCode (issue #12)**: `run_task`'s `projectPath` is now optional, letting ZCode run tasks in its `default` workspace; the companion `allowCreateProject` can forbid automatic project import. See the [v0.5.2 release notes](docs/release-v0.5.2.en.md) and the [Windows 10 acceptance record](docs/zcode-issue-12-windows-evidence.en.md).
+
+### Added
+
+- **Project-less dispatch for ZCode (issue #12)**: `run_task`'s `projectPath` is now optional. When omitted, ZCode runs the task in its `default` workspace — no directory assigned, no project registered or imported, no Git baseline, no project snapshot freeze, no project lock, no project acceptance. On success the task is marked structurally as `not_applicable: no_project` and the terminal message states "no project acceptance performed". `query_task` / `list_tasks` display such tasks normally; `verify_task` / `get_task_report` return an explicit not-applicable explanation instead of deriving a directory from cwd.
+- **`allowCreateProject` (ZCode-only, optional boolean)**: omitted keeps the existing "auto-import when the target is unregistered" behaviour; explicit `false` stops dispatch **before any import side effect** when the target is unregistered, returning a recognisable `project_not_registered` reason with remediation (no native folder dialog, no project added). Other agents passing this parameter get an explicit "not supported" error rather than a silent ignore.
+- **Windows 10 hardware acceptance record** (`docs/zcode-issue-12-windows-evidence{,.en}.md`): complete evidence for project-less dispatch and `allowCreateProject=false` on ZCode 3.11.2.6792, including the before/after comparison "ZCode project entries 34 → 34, 0 added / 0 removed".
+
+### Fixed
+
+- **Divergent project-trigger readiness criteria (issue #12 §5)**: waiting used `exists` (element has width/height only) while clicking went through `pick` (exactly one unclipped visible node in the winning tier), so an `exists=true` / `click=false` window existed. Waiting and clicking now share one **structured probe** that distinguishes not-mounted / mounted-but-invisible-or-clipped / ambiguous / disabled / covered / ready, plus a post-click condition: the project menu must actually open, and `menu-not-open` is classified separately.
+- **Error message contradicting behaviour**: "waiting for the project trigger timed out" is no longer used for early exits (multiple matches, disabled) or a menu that never opened; failure text carries `selector`, match count and minimal hit-node attributes, and diagnostics log attempt count, elapsed time and remaining budget.
+- **Centralised timeout**: new `gui.projectTriggerTimeoutMs` (default 15s) replaces the two hard-coded `15_000` literals; the whole "wait → one sidebar fallback → wait" sequence shares a single deadline, retries do not reset the budget, and it is clamped by the setup-recovery budget and the task deadline.
+- **`projectPath` was never opened up in the MCP schema (found on hardware)**: the handler already had the project-less branch, but `RunTaskParamsSchema.projectPath` was still required, so a real `run_task` was rejected by the SDK with `-32602 Required at projectPath`. Unit tests call the handler directly and therefore bypass `inputSchema`, which is why a green suite missed it. Changed to `AbsPath.optional()`, plus a protocol-level regression case in `test/integration/task-flow.test.ts` asserting neither `-32602` nor `Input validation error` appears.
+- **No "work outside a project" switch, and the menu click was undone by toggle semantics (found on hardware)**: ZCode's "New task" inherits the previous binding, so project-less dispatch parked at `needs_user` forever; meanwhile `clickProjectTriggerAndConfirm` kept clicking the trigger even when the project menu was **already open**, closing the Radix dropdown and then polling until its deadline, misreported as "the project menu did not open". Added the `workOutsideProject` selector and `enterDefaultWorkspace()` for an explicit switch (confirmed by `workspaceBinding` read-back, not by click success), made the click check the menu state first, and made `confirmDefaultWorkspace` return immediately for "definitely bound to a project".
+
+---
+
+## [0.5.1] — 2026-09-14
+
+Documentation and validation-evidence completion; **no runtime behaviour changes**. See the [v0.5.1 release notes](docs/release-v0.5.1.en.md) for details.
+
+### Added
+
+- `npm run evidence:visual:windows` (`scripts/evidence-visual-windows.mjs`): collects the full Windows 10 local functional matrix (existing/static/command sources, port conflict that blocks without terminating another service, bounded readiness failure that cleans up the child process, local Edge isolated instance and version mismatch, missing-browser blocker), 9/9 passed.
+- `docs/visual-validation-evidence/`: raw machine-readable validation records (Windows 10 matrix JSON and test output, macOS dual-architecture `environment.json`, macOS CI summaries), distributed with the package.
+
+### Fixed
+
+- Stale `package-lock.json` root version: the lockfile still said `0.4.1` at the v0.5.0 release while `package.json` said `0.5.0`; both are now synced to `0.5.1`.
+
+### Tests
+
+- Two additional real-browser-gated visual cases: screenshots succeed when the project path contains CJK characters and spaces; a main-document 302 redirect to a non-allowlisted origin is blocked by policy and passes once explicitly allowed. Full suite: **486 passed / 10 skipped**.
+- Collected macOS 13+ platform evidence: on macOS 15 hardware runners, Intel x64 and Apple Silicon arm64 (Node 20/22/24) each passed 10 files with 51 cases.
+
+### Docs
+
+- **Skill docs (`skills/tianshu-mcp/`) aligned with the code**: `SKILL.md` now lists all 11 tools with capability/approval columns (including `prepare_visual_baseline`/`approve_visual_baseline`), gives visual acceptance its own section (blockers do not trigger repair; `rework_task` re-verifies first; baseline approval and freezing), adds `setup_recovery` and the `errorType` value set to the error table, corrects agent status semantics (`traework` is always `ready`; `codex` is platform-dependent) and notes that `continue_task` only supports codex/zcode. `usage-examples.md` fixes the claim that `get_task_report` carries a meta block, removes the mis-listed `reasoningLevel` from the meta table, distinguishes the auto repair-plan location per agent (codex writes inside the project's `.zcode/plans/`; others write to the task directory), and adds the actual `list_tasks` output columns plus the visual CLI commands.
+- `docs/visual-validation{,.en}.md` rewritten with full platform evidence tables (system, Node, browser version, command, result).
+- Bilingual README and HANDOFF updated against the current code and commit history.
 
 ---
 

package/CHANGELOG.md

@@ -9,23 +9,61 @@
 
 ## [未发布]
 
-### 测试
-
-- 视觉验收补两条真实浏览器门禁用例（v0.5.0 之后补充）：项目路径含中文与空格时截图正常；主文档 302 跳转到未放行来源时按策略拦截，显式放行后通过。全量测试 **486 passed / 10 skipped**。
-- 新增 `npm run evidence:visual:windows`（`scripts/evidence-visual-windows.mjs`）：在 Windows 10 本机采集完整功能矩阵证据（`existing`/静态/命令三种来源、端口冲突阻塞且不结束他人服务、就绪失败有界阻塞并清理子进程、本机 Edge 独立实例与版本不匹配、缺浏览器阻塞），9/9 通过。
-- 采集 macOS 13+ 平台证据：macOS 15 真机 runner 上 Intel x64 与 Apple Silicon arm64（Node 20/22/24）各跑通 10 文件 51 用例；原始记录随 `docs/visual-validation-evidence/` 入库。
-
-### 文档
-
-- `docs/visual-validation{,.en}.md` 重写为完整平台证据表（系统、Node、浏览器版本、命令、结果），并新增 `docs/visual-validation-evidence/` 原始机器可读记录。
-
 ### 计划中
 
+- **视觉验收第二阶段——AI 视觉内容校验**（issue #13）：校验图片/页面截图**内容**是否符合任务描述（Logo 元素、风格匹配、页面语义等）。issue #3 中标注为「可选扩展」，其像素级对比第一阶段已随 v0.5.0 完成。需先确认模型与凭证来源（不得破坏「凭证零管理」红线）、判定防抖与门禁定位（建议默认仅告警）。
 - 更多外部 AI-Agent 适配（新 agent = 一个 profile +（如需）一个 adapter 文件）。
 - TraeWork 在 macOS 下的可执行探测与原生对话框驱动（当前 macOS 分支 fail-closed）。
 - 可选的项目级技能播种（默认不写入目标项目仓库）。
 - Codex 与 ZCode GUI 的 macOS 取消/返修/新建项目矩阵（当前两者 darwin 均保持 `research`）。
 - `needs_user` 状态下取消任务时经临时 CDP 连接尽力停止 GUI 内等待中的会话。
+- ZCode 无项目派发在 macOS 上的真机验证（本轮仅 Windows 10 实测）。
+
+---
+
+## [0.5.2] — 2026-09-14
+
+**ZCode 无项目派发（issue #12）**：`run_task` 的 `projectPath` 变为可选，ZCode 在 `default` 工作区承接任务；配套 `allowCreateProject` 可禁止自动导入项目。完整说明见 [v0.5.2 发布说明](docs/release-v0.5.2.md)，真机证据见 [Windows 10 验收记录](docs/zcode-issue-12-windows-evidence.md)。
+
+### 新增
+
+- **ZCode 无项目派发（issue #12）**：`run_task` 的 `projectPath` 改为可选。省略时 ZCode 在 `default` 工作区承接任务——不分配目录、不登记/导入项目、不采集 Git 基线、不冻结项目快照、不进入项目锁与项目验收；成功后以结构化字段标注 `not_applicable: no_project`，终态文案明示「未进行项目验收」。`query_task` / `list_tasks` 正常展示该类任务；`verify_task` / `get_task_report` 返回明确的不适用说明，不从 cwd 推导目录。
+- **`allowCreateProject`（ZCode 专用，可选布尔）**：省略 = 保持既有「目标未登记即自动导入」行为；显式 `false` 时，目标目录未登记即在**任何导入副作用之前**停止派发，返回可识别的 `project_not_registered` 与处理说明（不打开原生文件夹对话框、不添加项目）。其他 agent 显式传入该参数会得到明确的「不支持」错误，而不是被静默忽略。
+- **Windows 10 真机验收记录**（`docs/zcode-issue-12-windows-evidence{,.en}.md`）：ZCode 3.11.2.6792 上无项目派发与 `allowCreateProject=false` 的完整证据，含「派发前后 ZCode 项目条目 34 → 34、新增 0 / 消失 0」的对比。
+
+### 修复
+
+- **ZCode 项目触发器就绪判据不一致（issue #12 §五）**：等待用的是 `exists`（只看元素宽高），点击走的是 `pick`（要求该优先级层恰好一个未被裁剪的可见节点），两者判据不同，因此存在 `exists=true` 但 `click=false` 的窗口。现在等待与点击**共用同一份结构化探测**，区分未挂载 / 已挂载但不可见或被裁剪 / 不唯一 / 禁用 / 被遮挡 / 就绪；并新增点击后置检查——项目菜单必须真正打开，`menu-not-open` 单独归类。
+- **错误信息与行为失实**：「等待项目触发器超时」不再被用来描述早退（多匹配、禁用）或菜单未打开；失败文案携带 `selector`、匹配数与命中节点最小属性，诊断日志记录尝试次数、实际耗时与剩余预算。
+- **集中超时**：新增 `gui.projectTriggerTimeoutMs`（默认 15s）替换原先写死的两处 `15_000`；整个「等待 → 回退一次侧栏新建任务 → 再等待」共享同一截止时间，重试不重置预算，并被 setup 恢复预算与任务总时限夹住。
+- **`projectPath` 未在 MCP schema 层放开（真机发现）**：handler 已支持无项目分支，但 `RunTaskParamsSchema.projectPath` 仍是必填，真实 `run_task` 会在协议层被 SDK 拒成 `-32602 Required at projectPath`；而单元测试直接调 handler、绕过了 `inputSchema`，所以全绿也没抓到。已改为 `AbsPath.optional()`，并在 `test/integration/task-flow.test.ts` 补协议层回归用例（断言文本不出现 `-32602` / `Input validation error`）。
+- **缺少「不在项目中工作」切换，且项目菜单已开时点击被 toggle 反噬（真机发现）**：ZCode「新建任务」会继承上一次绑定，使无项目派发永久停在 `needs_user`；同时 `clickProjectTriggerAndConfirm` 在项目菜单**已经打开**时仍点击触发器，把 Radix 下拉关掉后一路轮询到 deadline，误报「项目菜单未打开」。现新增 `workOutsideProject` 选择器与 `enterDefaultWorkspace()` 显式切换（切换后以 `workspaceBinding` 回读为准），点击前先查菜单是否已开；`confirmDefaultWorkspace` 对「明确绑定着项目」立即返回而非空等。
+
+---
+
+## [0.5.1] — 2026-09-14
+
+文档与验证证据补齐；**无运行时行为变更**。完整说明见 [v0.5.1 发布说明](docs/release-v0.5.1.md)。
+
+### 新增
+
+- `npm run evidence:visual:windows`（`scripts/evidence-visual-windows.mjs`）：在 Windows 10 本机采集完整功能矩阵证据（`existing`/静态/命令三种来源、端口冲突阻塞且不结束他人服务、就绪失败有界阻塞并清理子进程、本机 Edge 独立实例与版本不匹配、缺浏览器阻塞），9/9 通过。
+- `docs/visual-validation-evidence/`：视觉验收验证的原始机器可读记录（Windows 10 矩阵 JSON 与测试输出、macOS 双架构 `environment.json`、macOS CI 摘要），随包分发。
+
+### 修复
+
+- `package-lock.json` 根包版本滞后：v0.5.0 发布时锁文件仍为 `0.4.1`（与 `package.json` 的 `0.5.0` 不一致），本版本同步为 `0.5.1`。
+
+### 测试
+
+- 视觉验收补两条真实浏览器门禁用例：项目路径含中文与空格时截图正常；主文档 302 跳转到未放行来源时按策略拦截，显式放行后通过。全量测试 **486 passed / 10 skipped**。
+- 采集 macOS 13+ 平台证据：macOS 15 真机 runner 上 Intel x64 与 Apple Silicon arm64（Node 20/22/24）各跑通 10 文件 51 用例。
+
+### 文档
+
+- **技能文档（`skills/tianshu-mcp/`）对齐代码实况**：`SKILL.md` 补全 11 个工具表与能力/审批列（含 `prepare_visual_baseline`/`approve_visual_baseline`），视觉验收独立成节（阻塞不触发返修、`rework_task` 先重新验收、基准审批与冻结），错误码表补 `setup_recovery` 与 `errorType` 取值，修正 agent 状态语义（`traework` 恒为 `ready`、`codex` 平台相关）与 `continue_task` 仅支持 codex/zcode；`usage-examples.md` 修正 `get_task_report` 不带 meta 块、移除 meta 表误列的 `reasoningLevel`、按 agent 区分自动修复计划落盘位置（codex 在项目内 `.zcode/plans/`、其余在任务目录），并补 `list_tasks` 实际输出列与视觉 CLI 命令。
+- `docs/visual-validation{,.en}.md` 重写为完整平台证据表（系统、Node、浏览器版本、命令、结果）。
+- 双语 README 与 HANDOFF 按当前代码与提交历史更新。
 
 ---
 

package/README.en.md

@@ -8,7 +8,7 @@
 
 # tianshu-mcp
 
-Visual acceptance (v0.5.0): [English guide](docs/visual-acceptance.en.md) · [Validation record](docs/visual-validation.en.md) · [Release notes](<docs/release-v0.5.0.en.md>).
+Visual acceptance (since v0.5.0): [English guide](docs/visual-acceptance.en.md) · [Validation record](docs/visual-validation.en.md) · [Latest release notes](<docs/release-v0.5.1.en.md>).
 
 **Tianshu × AI-Agent orchestration MCP server**
 
@@ -36,12 +36,13 @@ Registered by Tianshu as a standard MCP server, it dispatches external AI-Agents
 
 Tianshu plays the role of the overall commander; this MCP server is the **scheduler + execution surface + objective acceptance gate**; the external AI-Agent (Codex / TraeWork / ZCode GUI) is the "worker" that does the development.
 
-- **9 MCP tools**: `run_task / continue_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles`.
+- **11 MCP tools**: `run_task / continue_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles`, plus `prepare_visual_baseline / approve_visual_baseline` for visual acceptance
 - **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. 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).
 - **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 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).
 - **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.
@@ -195,6 +196,7 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
 | [docs/codex-gui-cdp.en.md](docs/codex-gui-cdp.en.md) | Codex desktop GUI driver: MSIX COM activation, CDP attach, selectors, run detection, verify/repair |
 | [docs/codex-windows-smoke.en.md](docs/codex-windows-smoke.en.md) | Codex Windows hardware record (incl. verify-fail → auto plan → repair-pass loop) |
 | [docs/release-v0.3.4.en.md](<docs/release-v0.3.4.en.md>) | v0.3.4 release notes (ZCode project/model read-back, initialization recovery, session dispatch confirmation, issues #8/#9/#10) |
+| [docs/release-v0.5.1.en.md](<docs/release-v0.5.1.en.md>) | v0.5.1 release notes (skill/validation docs, archived platform evidence, lockfile version sync; no runtime changes) |
 | [docs/release-v0.5.0.en.md](<docs/release-v0.5.0.en.md>) | v0.5.0 release notes (optional visual acceptance: screenshots, image specs, baseline approval, offline report) |
 | [docs/visual-acceptance.en.md](<docs/visual-acceptance.en.md>) | Visual acceptance primer and full configuration: three page sources, baseline candidates/approval, rule freezing, thresholds and troubleshooting |
 | [docs/visual-validation.en.md](<docs/visual-validation.en.md>) | Visual acceptance validation progress: full Windows 10 matrix and macOS Intel/Apple Silicon platform evidence (system/Node/browser/command/result) |
@@ -236,9 +238,9 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
   - Zcode headless entry (Z1) verified: ZCode desktop ships no headless CLI → unsupported
 - **R1–R8 / S1–S6 — two acceptance hardening rounds** ✅ (cancel / timeout / baseline attribution / parameter semantics / hot reload / CI hardening) — **72 tests**
 - **Engineering / CI** ✅
-  - GitHub Actions: `CI` (`build-test` ubuntu/windows/macos × Node 20/22/24 + `pack-check`, plus a `visual-browser` real-browser matrix ubuntu/windows/macos-15-intel/macos-15 × Node 20/22/24, all green with the v0.5.0 tag) and `Release` (tag-triggered) both green
+  - GitHub Actions: `CI` (`build-test` ubuntu/windows/macos × Node 20/22/24 + `pack-check`, plus a `visual-browser` real-browser matrix ubuntu/windows/macos-15-intel/macos-15 × Node 20/22/24, all green with the v0.5.1 tag) and `Release` (tag-triggered) both green
   - Skill self-install verified idempotent on this machine's real `~/.rivet/skills/tianshu-mcp`
-  - npm package name `tianshu-mcp` published continuously since v0.1.1 (currently `0.5.0`)
+  - npm package name `tianshu-mcp` published continuously since v0.1.1 (currently `0.5.1`)
 - **Real Tianshu host integration (DoD #6)** ✅ (2026-09-07)
   - Configured the local mode in the real `D:\Tianshu` desktop host `mcp.servers` → sidecar reported `MCP: 2 servers connected, 10 tools` (including this server's 8 tools), spawned the child process and connected over stdio
   - Exposed and fixed a skill-install source-path bug (fileURLToPath, commit 55cf2d0)
@@ -307,6 +309,11 @@ Use `server.log` when troubleshooting connections; do not treat stderr output it
   - **MCP/CLI**: new `prepare_visual_baseline` / `approve_visual_baseline` and the `tianshu-mcp visual` subcommand family, dispatched before the stdio connection
   - **Reports and recovery**: `VerifyReport` gains an optional `visual` section and offline HTML (status filter, opacity overlay, region location); visual blockers enter `needs_attention` and `rework_task` re-verifies first so only real defects consume repair budget
   - **Gates**: CI adds a four-system, three-Node real-browser matrix plus isolated production-package consumer acceptance; release requires a successful CI for the target commit and blocks when Gitee credentials are missing rather than claiming success
+- **M20 — skill/validation docs aligned + platform evidence archived + v0.5.1** (2026-09-14) — **486 tests**
+  - Skill docs aligned item by item with the code: a full 11-tool table with capability/approval columns, visual acceptance given its own section, `setup_recovery` added to the error table, and fixes to agent status semantics plus the `get_task_report`/`repair-plan` doc drift
+  - Visual acceptance platform evidence archived: Windows 10 local full functional matrix **9/9** (`npm run evidence:visual:windows`), and macOS 15 hardware Intel x64 plus Apple Silicon arm64 with 10 files / 51 cases each
+  - Fixed the stale `package-lock.json` root version (was `0.4.1` at v0.5.0)
+  - **No runtime behaviour changes**; no migration needed
 
 ## Agent support status
 
@@ -379,7 +386,7 @@ Behavior and limits:
 
 | Document | Content |
 |---|---|
-| [CHANGELOG.en.md](<CHANGELOG.en.md>) | Version history (v0.1.0 → v0.5.0) |
+| [CHANGELOG.en.md](<CHANGELOG.en.md>) | Version history (v0.1.0 → v0.5.1) |
 | [CONTRIBUTING.en.md](CONTRIBUTING.en.md) | Dev setup, conventions, commit/release flow, adding an agent |
 | [SECURITY.en.md](SECURITY.en.md) | Security model (zero credentials / command whitelist / process & desktop-automation boundaries) and private reporting |
 | [CODE_OF_CONDUCT.en.md](CODE_OF_CONDUCT.en.md) | Contributor Code of Conduct |

package/README.md

@@ -8,7 +8,7 @@
 
 # tianshu-mcp
 
-视觉验收（v0.5.0）：[中文指南](docs/visual-acceptance.md) · [验证记录](docs/visual-validation.md) · [发布说明](<docs/release-v0.5.0.md>)。
+视觉验收（v0.5.0 起）：[中文指南](docs/visual-acceptance.md) · [验证记录](docs/visual-validation.md) · [最新发布说明](<docs/release-v0.5.1.md>)。
 
 **天枢 × AI-Agent 编排 MCP server**
 
@@ -36,12 +36,13 @@
 
 天枢的角色是总指挥；本 MCP server 是**调度层 + 执行面 + 客观验收仪**；外部 AI-Agent（Codex / TraeWork / ZCode GUI）是执行开发的「工人」。
 
-- **9 个 MCP 工具**：`run_task / continue_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles`。
+- **11 个 MCP 工具**：`run_task / continue_task / query_task / list_tasks / get_task_report / cancel_task / verify_task / rework_task / get_profiles`，外加视觉验收的 `prepare_visual_baseline / approve_visual_baseline`
 - **异步契约**：`run_task` 秒回 `taskId`，长任务用 `query_task` 轮询（长任务不卡 `tools/call`）。
 - **客观验收**：自动命令检查（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`。报告与日志格式不变（结果按声明顺序返回）。
 - **失败返修闭环**：自动返修（`autoFixRounds`）+ 手动 `rework_task`；验收失败时自动生成修复计划文件并回填给 agent；轮次用尽 → `needs_attention` 等天枢裁决。
 - **执行面**：`driver: "gui"` 由显式 adapter 驱动桌面 UI（Codex / TraeWork / ZCode 各自使用隔离的 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)。
 - **调度纪律**：每项目串行队列 + 全局并发上限（默认 2，可配）。
 - **不碰密钥**：各 agent 用自己的登录态；本 server 不保存/转发任何 API key。
 - **可扩展**：新 agent = 一个 profile（数据）+（如需）一个 adapter 文件，零改编排核心。
@@ -88,7 +89,7 @@ npm install -g tianshu-mcp
 | 命令 | `npx` | `node` |
 | 参数（空格分隔） | `-y tianshu-mcp` | `<仓库绝对路径>/dist/index.js` |
 
-> - 服务器 ID 即工具前缀：填 `tianshu-mcp` 后工具名为 `mcp__tianshu-mcp__run_task` 等 9 个。
+> - 服务器 ID 即工具前缀：填 `tianshu-mcp` 后工具名为 `mcp__tianshu-mcp__run_task` 等 11 个。
 > - 参数按空格分隔填写，**不要加引号**；本地开发模式请把 `<仓库绝对路径>` 换成真实绝对路径（如 `D:/Trae项目/tianshu-mcp/dist/index.js`）。
 > - 界面未提供环境变量输入框；如需自定义数据目录，改用下面的 `config.json` 方式设置 `TIANSHU_MCP_HOME`。
 > - 添加后连接成功即完成；新开会话即可看到 11 个工具。
@@ -190,6 +191,7 @@ ZCode 提问、需要登录、旧实例无 CDP、系统权限不足，或自动
 | [docs/zcode-windows-smoke.md](docs/zcode-windows-smoke.md) | ZCode Windows 真机开发、同会话返修与提问续跑验收记录 |
 | [docs/codex-gui-cdp.md](docs/codex-gui-cdp.md) | Codex 桌面端 GUI 驱动：MSIX COM 激活、CDP 接管、选择器、运行检测、验收返修 |
 | [docs/codex-windows-smoke.md](docs/codex-windows-smoke.md) | Codex Windows 真机验收记录（含验收失败→自动生成计划→返修通过闭环） |
+| [docs/release-v0.5.1.md](<docs/release-v0.5.1.md>) | v0.5.1 发布说明（技能/验证文档补齐、平台证据归档、锁文件版本同步；无运行时变更） |
 | [docs/release-v0.5.0.md](<docs/release-v0.5.0.md>) | v0.5.0 发布说明（可选视觉验收模块：截图对比、图片规格、基准批准、离线报告） |
 | [docs/visual-acceptance.md](<docs/visual-acceptance.md>) | 视觉验收入门与完整配置：三种页面来源、基准候选/批准、规则冻结、阈值与排查 |
 | [docs/visual-validation.md](<docs/visual-validation.md>) | 视觉验收验证进度：Windows 10 完整功能矩阵与 macOS Intel/Apple Silicon 平台证据（系统/Node/浏览器/命令/结果） |
@@ -235,9 +237,9 @@ ZCode 提问、需要登录、旧实例无 CDP、系统权限不足，或自动
   - Zcode 无头接口（Z1）实测定论：ZCode 桌面无随包 headless CLI → unsupported
 - **R1–R8 / S1–S6 — 两轮验收整改** ✅（取消/超时/基线归因/参数语义/热加载/CI 加固）— **72 测试**
 - **工程 / CI** ✅
-  - GitHub Actions：`CI`（`build-test` ubuntu/windows/macos × Node 20/22/24 + `pack-check`，另加 `visual-browser` 真实浏览器矩阵 ubuntu/windows/macos-15-intel/macos-15 × Node 20/22/24，随 v0.5.0 tag 全绿）与 `Release`（tag 触发）均绿
+  - GitHub Actions：`CI`（`build-test` ubuntu/windows/macos × Node 20/22/24 + `pack-check`，另加 `visual-browser` 真实浏览器矩阵 ubuntu/windows/macos-15-intel/macos-15 × Node 20/22/24，随 v0.5.1 tag 全绿）与 `Release`（tag 触发）均绿
   - 技能自检安装已在本机真实 `~/.rivet/skills/tianshu-mcp` 验证生效且幂等
-  - npm 包名 `tianshu-mcp` 自 v0.1.1 起持续发布（当前 `0.5.0`）
+  - npm 包名 `tianshu-mcp` 自 v0.1.1 起持续发布（当前 `0.5.1`）
 - **天枢宿主真实接入（DoD #6）** ✅（2026-09-07，[host-integration-record.md](docs/host-integration-record.md)）
   - 在真实 `D:\Tianshu` 桌面宿主 `mcp.servers` 配置本地模式 → sidecar `MCP: 2 servers connected, 10 tools`（含本 server 8 工具），spawn 子进程并 stdio 连通
   - 实测暴露并修复技能安装源路径 bug（fileURLToPath，提交 55cf2d0）
@@ -306,6 +308,11 @@ ZCode 提问、需要登录、旧实例无 CDP、系统权限不足，或自动
   - **MCP/CLI**：新增 `prepare_visual_baseline` / `approve_visual_baseline` 与 `tianshu-mcp visual` 子命令族；CLI 在 stdio 连接前分流
   - **报告与恢复**：`VerifyReport` 新增可选 `visual` 与离线 HTML（状态过滤、透明叠加、区域定位）；视觉阻塞进 `needs_attention`，`rework_task` 先重新验收、仅真实缺陷才消耗返修预算
   - **门禁**：CI 新增真实浏览器四系统三 Node 矩阵与生产包独立消费者验收；release 要求目标提交存在成功 CI，缺少 Gitee 凭据时阻塞不冒充成功
+- **M20 — 技能/验证文档对齐 + 平台证据归档 + v0.5.1**（2026-09-14）— **486 测试**
+  - 技能文档逐项对齐代码实况：11 工具表（补能力/审批列）、视觉验收独立成节、错误码补 `setup_recovery`、修正 agent 状态语义与 `get_task_report`/`repair-plan` 的文档偏差
+  - 归档视觉验收平台证据：Windows 10 本机完整功能矩阵 **9/9**（`npm run evidence:visual:windows`）、macOS 15 真机 Intel x64 与 Apple Silicon arm64 各 10 文件 51 用例
+  - 修复 `package-lock.json` 根包版本滞后（v0.5.0 时为 `0.4.1`）
+  - 本版本**无运行时行为变更**，升级无需迁移
 
 ## Agent 适配现状
 
@@ -379,7 +386,7 @@ run_task(projectPath=/path/to/项目, agentId=codex-cli, task="任务书", autoV
 | 文档 | 内容 |
 |---|---|
 | [HANDOFF.md](HANDOFF.md) | 项目交接文档：当前状态快照、架构导览、硬性红线、已知限制、接手建议 |
-| [CHANGELOG.md](<CHANGELOG.md>) | 版本变更日志（v0.1.0 → v0.5.0） |
+| [CHANGELOG.md](<CHANGELOG.md>) | 版本变更日志（v0.1.0 → v0.5.1） |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | 开发环境、工程规范、提交与发布流程、如何新增 agent |
 | [SECURITY.md](SECURITY.md) | 安全模型（凭证零管理/命令白名单/进程与桌面自动化边界）与私密报告渠道 |
 | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | 贡献者行为准则 |

package/dist/agents/zcode/cdp.js

@@ -2,7 +2,7 @@ import { TraeworkCdpClient, CdpDisconnectedError, CdpUnavailableError, } from ".
 import { candidateExpr } from "./selectors.js";
 import { projectDisplayName } from "./project.js";
 import { normalizeZcodeModelSelection } from "./model.js";
-import { projectTriggerDom, workspaceBindingExpression, modelSelectionExpression, sendButtonPointExpression, } from "./dom.js";
+import { projectTriggerDom, projectTriggerProbeExpression, projectMenuOpenExpression, workOutsideProjectExpression, workspaceBindingExpression, modelSelectionExpression, sendButtonPointExpression, } from "./dom.js";
 export { CdpDisconnectedError, CdpUnavailableError };
 export async function retryZcodeEvaluation(operation, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     for (let attempt = 0;; attempt++) {
@@ -18,6 +18,8 @@ export async function retryZcodeEvaluation(operation, sleep = (ms) => new Promis
         }
     }
 }
+/** 点击后确认菜单打开的轮询间隔（不是独立超时；窗口由调用方从集中配置与总预算算出）。 */
+const PROJECT_MENU_POLL_MS = 100;
 export class ZcodeCdpClient {
     selectors;
     inner;
@@ -86,10 +88,11 @@ export class ZcodeCdpClient {
     }
     async click(key) {
         if (key === "projectTrigger") {
-            const point = await this.evaluate(`(function(){${projectTriggerDom(this.selectors)}if(!trigger)return null;const r=trigger.getBoundingClientRect();return {x:r.left+r.width/2,y:r.top+r.height/2}})()`);
-            if (!point)
+            // 与等待共用同一就绪判据：多匹配、不可见、禁用、被遮挡一律不算就绪，不发鼠标事件。
+            const probe = await this.probeProjectTrigger();
+            if (!probe.ready || !probe.point)
                 return false;
-            await this.clickAt(point.x, point.y);
+            await this.clickAt(probe.point.x, probe.point.y);
             return true;
         }
         const point = await this.evaluate(`(function(){for(const s of ${candidateExpr(key, this.selectors)}){for(const e of document.querySelectorAll(s)){const r=e.getBoundingClientRect();if(r.width&&r.height)return {x:r.left+r.width/2,y:r.top+r.height/2}}}return null})()`);
@@ -98,6 +101,48 @@ export class ZcodeCdpClient {
         await this.clickAt(point.x, point.y);
         return true;
     }
+    /** 项目触发器结构化探测（只读，不发事件）。 */
+    async probeProjectTrigger() {
+        return this.evaluate(projectTriggerProbeExpression(this.selectors));
+    }
+    /** 项目菜单是否已真正可见（点击后置条件）。 */
+    async projectMenuOpen() {
+        return this.evaluate(projectMenuOpenExpression());
+    }
+    /**
+     * 探测 → 点击 → 确认项目菜单打开。事件发出不算成功：菜单没开就返回 menu-not-open。
+     * deadline 由调用方从集中配置与 setup/task 总预算取上限（重试不重置截止时间）。
+     */
+    async clickProjectTriggerAndConfirm(deadline) {
+        const probe = await this.probeProjectTrigger();
+        // 菜单可能**已经开着**（上一次尝试或外部操作的残留）。Radix 下拉是 toggle：此时再点
+        // 触发器会把它关掉，随后整段等待都会落到 menu-not-open（3.11.2 真机实测踩过）。
+        // 所以先查后点。
+        if (await this.projectMenuOpen())
+            return { opened: true, probe };
+        if (!probe.ready || !probe.point)
+            return { opened: false, reason: "not-ready", probe };
+        await this.clickAt(probe.point.x, probe.point.y);
+        while (Date.now() < deadline) {
+            // eslint-disable-next-line no-await-in-loop
+            if (await this.projectMenuOpen())
+                return { opened: true, probe };
+            // eslint-disable-next-line no-await-in-loop
+            await new Promise((resolve) => setTimeout(resolve, PROJECT_MENU_POLL_MS));
+        }
+        return { opened: false, reason: "menu-not-open", probe };
+    }
+    /**
+     * 点击「不在项目中工作」（要求该层唯一可见）：进入 ZCode 的 default（无项目）工作区。
+     * 新建任务会继承上一次绑定，所以无项目派发必须先显式执行这一步。
+     */
+    async clickWorkOutsideProject() {
+        const found = await this.evaluate(workOutsideProjectExpression(this.selectors));
+        if (!found.point)
+            return { clicked: false, count: found.count };
+        await this.clickAt(found.point.x, found.point.y);
+        return { clicked: true, count: 1 };
+    }
     async clickExact(key, value) {
         const found = await this.evaluate(`(async function(){const norm=s=>(s||'').normalize('NFKC').trim().toLocaleLowerCase();const target=norm(${JSON.stringify(value)});const sels=${candidateExpr(key, this.selectors)};const visible=e=>{const r=e.getBoundingClientRect();if(!(r.width>0&&r.height>0&&r.bottom>0&&r.right>0&&r.top<innerHeight&&r.left<innerWidth))return false;const x=Math.max(0,Math.min(innerWidth-1,r.left+r.width/2)),y=Math.max(0,Math.min(innerHeight-1,r.top+r.height/2)),hit=document.elementFromPoint(x,y);return !!hit&&(hit===e||e.contains(hit))};const items=()=>{const out=[];for(const s of sels)for(const e of document.querySelectorAll(s))if(visible(e)&&!out.includes(e))out.push(e);return out};const leafTexts=e=>[...e.querySelectorAll('*')].filter(n=>n.children.length===0).map(n=>(n.textContent||'').trim()).filter(Boolean);const label=e=>(e.getAttribute('data-value')||e.getAttribute('data-model')||e.getAttribute('data-provider')||leafTexts(e)[0]||e.textContent||'').trim();let nodes=items();let scroller=nodes[0];while(scroller&&scroller!==document.body&&scroller.scrollHeight<=scroller.clientHeight)scroller=scroller.parentElement;const start=scroller?.scrollTop||0;if(scroller)scroller.scrollTop=0;const seen=new Map(),seenTestids=new Map(),matches=new Map();for(let i=0;i<60;i++){await new Promise(r=>setTimeout(r,25));nodes=items();for(const e of nodes){const text=label(e);const testid=e.getAttribute('data-testid')||'';const id=e.getAttribute('data-id')||e.getAttribute('data-model-id')||e.getAttribute('data-value')||e.getAttribute('data-model')||e.getAttribute('data-provider')||testid||text;const key=norm(id)+'|'+norm(text);if(testid)seenTestids.set(key,testid);if(!text)continue;seen.set(key,text);if(norm(text)===target)matches.set(key,{top:scroller?.scrollTop||0,text})}if(!scroller||scroller.scrollTop+scroller.clientHeight>=scroller.scrollHeight-1)break;const before=scroller.scrollTop;scroller.scrollTop=Math.min(scroller.scrollTop+Math.max(100,scroller.clientHeight*.8),scroller.scrollHeight);if(scroller.scrollTop===before)break}const result={available:[...seen.values()],testids:[...seenTestids.values()]};const matchesFound=[...matches.values()];if(matchesFound.length===1){if(scroller)scroller.scrollTop=matchesFound[0].top;await new Promise(r=>setTimeout(r,50));const exact=items().filter(e=>norm(label(e))===target);if(exact.length===1){exact[0].scrollIntoView({block:'center'});const r=exact[0].getBoundingClientRect();return {count:1,...result,point:{x:r.left+r.width/2,y:r.top+r.height/2}}}}if(scroller)scroller.scrollTop=start;return {count:matchesFound.length,...result}})()`);
         if (!found.point)

package/dist/agents/zcode/dom.js

@@ -74,3 +74,60 @@ export function sendButtonPointExpression(overrides) {
     return hit && (hit===e || e.contains(hit)) ? {x,y} : null;
   })()`;
 }
+/**
+ * 项目触发器结构化探测：等待与点击共用这一份就绪判据，消除「exists 说有、click 说没有」
+ * （exists 只看宽高，pick 还要求该优先级层唯一且未被祖先裁剪）。
+ *
+ * 返回 selector / 该层匹配数 count / 全部候选命中的挂载数 mounted / 命中节点最小诊断属性，
+ * 让上层区分未挂载、不可见、不唯一、禁用、遮挡与真实超时，而不是统统归成「等待超时」。
+ * 只用于项目触发器；登录页等其它 exists 调用语义不变。
+ */
+export function projectTriggerProbeExpression(overrides) {
+    return `(function(){${ZCODE_DOM}
+    const describe = e => e ? String(e.tagName || '')
+      + (e.getAttribute('data-testid') ? '#' + e.getAttribute('data-testid') : '')
+      + (e.getAttribute('aria-label') ? '[' + e.getAttribute('aria-label') + ']' : '') : '';
+    const sels = ${candidateExpr("projectTrigger", overrides)};
+    const mountedNodes = new Set();
+    for (const s of sels) for (const e of document.querySelectorAll(s)) mountedNodes.add(e);
+    const mounted = mountedNodes.size;
+    const m = pick(sels);
+    const base = { selector: m.selector, count: m.count, mounted, ready: false };
+    if (!mounted) return Object.assign({}, base, { state: 'missing' });
+    if (m.count === 0)
+      return Object.assign({}, base, { state: 'hidden', detail: describe(mountedNodes.values().next().value) });
+    if (m.count > 1) return Object.assign({}, base, { state: 'ambiguous' });
+    const node = m.node;
+    if (node.disabled || node.getAttribute('aria-disabled') === 'true')
+      return Object.assign({}, base, { state: 'disabled', detail: describe(node) });
+    const r = node.getBoundingClientRect(), x = r.left + r.width / 2, y = r.top + r.height / 2;
+    const hit = document.elementFromPoint(x, y);
+    // 命中目标本身或其子树才算命中目标；被别的元素盖住不是可点击状态。
+    if (!hit || !(hit === node || node.contains(hit)))
+      return Object.assign({}, base, { state: 'covered', detail: describe(hit) });
+    return Object.assign({}, base, { state: 'ready', ready: true, point: { x, y }, detail: describe(node) });
+  })()`;
+}
+/**
+ * 点击项目触发器后的后置条件：项目菜单必须真正可见。
+ * 鼠标事件发出去本身不算成功——菜单没开就说明这次点击没有生效。
+ */
+export function projectMenuOpenExpression() {
+    return `(function(){${ZCODE_DOM}
+    if ([...document.querySelectorAll('[role="menu"]')].some(visible)) return true;
+    return [...document.querySelectorAll('[role="menuitemcheckbox"]')].some(visible);
+  })()`;
+}
+/**
+ * 「不在项目中工作」菜单项（`composer-work-outside-project`）：ZCode 用它进入 default
+ * （无项目）工作区。要求命中层唯一可见，否则不点击——多匹配说明菜单结构已漂移，
+ * 猜一个点会把任务送到错误的工作区。
+ */
+export function workOutsideProjectExpression(overrides) {
+    return `(function(){${ZCODE_DOM}
+    const found = pick(${candidateExpr("workOutsideProject", overrides)});
+    if (!found.node) return { count: found.count };
+    const r = found.node.getBoundingClientRect();
+    return { count: found.count, point: { x: r.left + r.width / 2, y: r.top + r.height / 2 } };
+  })()`;
+}

package/dist/agents/zcode/references.js

@@ -4,18 +4,31 @@ function inside(root, candidate) {
     const rel = path.relative(root, candidate);
     return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
-export function validateTaskReferences(task, context, projectRoot) {
+/** 从任务书/上下文中抽取「像本地路径」的候选值（URL、模型名、命令文本等已被排除）。 */
+export function collectLocalReferences(task, context) {
     const text = `${task}\n${context ?? ""}`;
     const values = new Set();
     for (const m of text.matchAll(/`([^`]+)`/g))
         values.add(m[1].trim());
     for (const m of text.matchAll(/(?:^|\s)((?:[A-Za-z]:[\\/]|\/|\.\.?[\\/])[^\s，。；;]+)/gm))
         values.add(m[1].trim());
+    return [...values].filter((source) => path.isAbsolute(source) || /^\.\.?[\\/]/.test(source) || /[\\/]/.test(source));
+}
+/**
+ * 校验任务书里的本地引用。
+ *
+ * `projectRoot` 缺失（无项目模式，issue #12）时**不得**退回 cwd / 主目录 / 日志目录去解析：
+ * 识别到明确引用就直接说明需要 projectPath，没有引用则返回空表。
+ */
+export function validateTaskReferences(task, context, projectRoot) {
+    const candidates = collectLocalReferences(task, context);
+    if (!projectRoot) {
+        if (candidates.length)
+            throw new Error(`任务书包含本地文件引用（${candidates.slice(0, 5).join("、")}${candidates.length > 5 ? ` 等 ${candidates.length} 项` : ""}）；无项目模式无法解析路径，请提供 projectPath`);
+        return [];
+    }
     const out = [];
-    for (const source of values) {
-        // Backticks frequently contain identifiers/commands. Only path-like values are interpreted.
-        if (!path.isAbsolute(source) && !/^\.\.?[\\/]/.test(source) && !/[\\/]/.test(source))
-            continue;
+    for (const source of candidates) {
         const absolutePath = path.resolve(projectRoot, source);
         if (!inside(path.resolve(projectRoot), absolutePath))
             throw new Error(`引用路径越出项目范围：${source}`);