@jayyuen66/dsh-ocr-review 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -4,10 +4,37 @@
 [语义化版本](https://semver.org/lang/zh-CN/)，最新版本在最上。条目自 0.1.0 起；更早的
 1.0.0 / 0.6.x 是作用域迁移前的历史编号，npm 已永久记录，不在本文件重建。
 
+## 0.1.10
+
+一轮跨面审查修复：路径闸、MCP 配置写面与并发覆盖、provider 面与解析判据收口；设置卡与工具出口同步加固。对外工具与 Remote 方法名单不变。
+
+### Changed
+
+- **MCP 写面加 revision 基线**：`mcp()` 回执新增 `revision`，`saveMcp` 入参加可选 `revision`——带基线时锁内比对，过期整笔拒绝回 `mcpSaveConflict`；不带基线沿用旧的后写覆盖语义（旧客户端兼容）。双开卡片或手改 config.json 时后保存者不再静默抹掉他人更新。
+- **发布链加固**（`.github/workflows/publish.yml`）：发布步 `pnpm install --ignore-scripts`、构建移至无凭据步、`pnpm publish --ignore-scripts`，生命周期脚本不再能接触发布凭据；`prepack` 删除改 `prepare`（同为双构建）。
+- **依赖与元数据**：js-yaml 改精确钉 `5.4.3`；`@deepseek-ai/schemastery` peer 放宽为 `^3.18.6-alpha.1`；catalog 的 shared 抬到 0.2.2；author 改对象形（name+url）。
+
+### Fixed
+
+- **路径闸**（`lib/argv-guard.ts`）：归一后落在文件系统根（`/`、盘符根、UNC 根）一律拒绝，堵 `--rule /etc/passwd` 被当仓内文件读进 OCR；`statSync` 改 `throwIfNoEntry: false`；会话根判定改 `path.isAbsolute`（Windows `C:/…` 不再落相对分支）。
+- **Remote 拒绝判据**（`lib/remote-shape.ts`）：`isRemoteRefused` 收 `unknown`，须同时满足 `ok===false`、非空 `error`、整数 `status`，null/NaN/原始值不再误判；状态码集中为导出常量 `OCR_REFUSE_STATUS`。
+- **MCP 配置**（`lib/mcp-config.ts`）：写失败独立文案；输出容器改 null 原型（`__proto__` 键不再丢失/污染）；写侧把盘上同条目的未知字段接回；providers.chatgpt 非法改显式报错；读侧加 64 KiB 上限；URL 判据拒空主机。
+- **OCR config 迁移**（`lib/ocr-config.ts`）：不覆写已有非空 `api_key_cmd`；provider/model 入口一次 trim；空白 `language` 不落键；迁移写回统一走 `renderConfigDoc`。
+- **provider 面**（`lib/provider-projection.ts`、`lib/provider-source.ts`）：baseURL 禁内嵌 `user:pass@`、空白/控制字符与无主机；`apiKeyEnv` 按导出白名单收口，非法 ref 单独暴露；health 与探测异常收口，失败出口统一 `settingsFailed()`。
+- **解析与聚合**（`lib/parse.ts`、`lib/severity.ts`）：`isCount` 限安全整数域、`toolCallsOf` 总数口径、warnings 限流；`hitsContract` 只认 reviewable 文件/组，`{"error":…}` 载荷不再假报 0 文件；`byCategory` 落 null 原型。
+- **工具出口守卫**（`lib/output.ts`）：新增容器形状闸；违规收集改 `ViolationSink`，收集期截断 20 条/2000 字，不再先攒几十万条。
+- **host**（`host.ts`）：后台作业剪枝与取文案包 try 并先 killProc（不留无主 OCR 进程）；saveMcp/chatGpt 加外层 try 回可读回执；装载期 fire-and-forget 自检包 try（防未处理 rejection 终止宿主）；effort 未知值回落设置卡值。
+- **设置卡**（`src/client-entry.ts`）：channel 改逐值比对；MCP 未读成功时禁编辑/保存；llmTest 失败按失败着色；refresh 并发只认最后一次。
+- **CLI 与凭据脚本**（`lib/cli.ts`、`scripts/get-cred.mjs`）：pgrep 探针退出码 1（无匹配）不再算被拒；preview 也转发 `--max-tokens`；YAML 报错不再读 message/toString，防明文 snippet 外泄。
+
+### Added
+
+- **测试三层**：`test/e2e/stub-ocr.e2e.test.ts`（官方执行器真 spawn stub 全链路）、`test/e2e/real-cli.e2e.test.ts`（真 ocr 二进制对照，缺席显式跳过）、`test/platform/guards.platform.test.ts`、`test/property/parse-chain.property.test.ts`（fast-check）、`test/ref-syntax-parity.test.ts`、`test/write-surface.test.ts`；devDependencies 新增 fast-check 4.10.2 与 `@deepseek-ai/dsh-bash-local` / `@deepseek-ai/dsh-subprocess-local`。
+
 ## 0.1.9
 
 这一版把后台评审的作业归属钉到发起会话，并把设置卡与读面校验统一到 shared 组件和 zod；
-插件页展示面进包，宿主开发线抬到 0.2.2-alpha.2。对外工具与 Remote 方法面不变。
+插件页展示面进包，宿主开发线抬到 0.2.2-alpha.2。对外工具与 Remote 方法名单不变，后台作业的可见性按发起会话收紧。
 
 ### Changed
 
@@ -23,7 +50,7 @@
 - **插件页展示面进包**：新增 `locale/en.json`、`locale/zh.json` 与 `docs/DETAIL.md`、
   `docs/DETAIL.zh.md`；`exports` 增加 `./locale/*.json`，`files` 收进 locale 与 docs。
 - **宿主开发线抬到 `0.2.2-alpha.2`**：devDependencies 与 catalog/overrides 同值；`engines.dsh`
-  与 peer 仍写支持窗口 `^0.2.1-rc.3`，README 补滚动窗口说明。
+  与 peer 写支持窗口 `^0.2.1-rc.3`，README 补滚动窗口说明。
 - **正则常量提升**：argv-guard / config-store / mcp-config / output / parse / provider-projection
   的内联正则提取为命名常量，行为不变，满足 lint 的重复字面量门禁。
 

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 JayYuen666
+Copyright (c) 2026 JayYuen (JayYuen666)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -53,7 +53,7 @@
 - **One settings card also carries the admin surfaces**: a validated MCP servers JSON editor (saving touches only `mcp_servers`) and a ChatGPT section that reports `ocr auth` status and switches OCR's provider/model. Both are human-managed; neither is a model tool (a stdio MCP server runs commands, and OAuth sign-in needs a browser plus a local callback).
 - **Wraps the external `ocr` (open-code-review) CLI into seven model tools.** The host validates tool arguments not at all, so every shape, type and enum gate lives in this package: user-controlled strings are single-quote escaped, enums are whitelist-clamped, and wrong-typed values error instead of silently narrowing or widening a review.
 - **One settings card** (the web client half) picks provider/model from the host's own `llm-pi-ai` settings entry and key status from the host credentials service. When either service is absent the card shows the degradation reason; tools and settings keep working.
-- **Applying a selection writes the CLI's own `~/.opencodereview/config.json`** — as an `api_key_cmd` command that reads the host credential ref at OCR runtime. A plaintext key is never written anywhere.
+- **Applying a selection writes the CLI's own `~/.opencodereview/config.json`** — as an `api_key_cmd` command that reads the host credential ref at OCR runtime. The plugin never writes a plaintext key into `config.json`; the `.bak` it copies before the first rewrite keeps whatever the file held before, which may include a pre-migration plaintext key (mode 0600) — delete that backup after migrating.
 - **Results are a structured summary with two distinct notions**: what OCR found (`status`, `aggregation`, `topComments`, `warnings`) and whether the run actually covered the selected files (`coverage`, `budgetExceeded`, `toolCalls`). The CLI is invoked with `--audience agent`, which suppresses its progress output — the second notion is only reachable through those fields.
 - **CLI availability is one judgement** (`resolveOcrAvailability` in `lib/cli.ts`): pure filesystem, never a spawn, re-read per call. The card status row, the detail-page badge and the activation guidance all render that one answer, so "which copy is in use" cannot be told three ways.
 - **Background runs (`wait: false`) are official host jobs**: `job_list` / `job_output` / `job_kill` can observe and stop a review that outlives the tool call.
@@ -67,10 +67,10 @@ dsh plugin --profile web add @jayyuen66/dsh-ocr-review
 Remove with `dsh plugin --profile web remove @jayyuen66/dsh-ocr-review`. The package is on the public npm registry, so installation needs no credentials.
 
 - **Upgrading an installed copy is remove-then-add.** On a profile running HMR (the shipped ones do), `add` on a package the profile already depends on refuses before pnpm runs (`already-installed`) — run `remove` first, then `add` the target version; the new one starts without a restart. Without HMR the same `add` runs pnpm and reports `restart-required`.
-- **Requires Node.js `>= 22.12` and host `dsh` on the `0.2.1-rc.3` line.** The host reads `engines.dsh` (`^0.2.1-rc.3`) and decides on it alone; prereleases participate in the comparison. An incompatible host needs the explicit risk grant `dsh plugin --profile <p> allow-version @jayyuen66/dsh-ocr-review@<version> --dsh-version <exact> --accept-risk`. The support window rolls: this package is verified against the three most recently released host versions at publish time and re-verified once the window moves, so the version number in this bullet is not a standing promise.
+- **Requires Node.js `>= 22.12` and host `dsh` on the `0.2.1-rc.3` / `0.2.2-alpha.2` line.** The host reads `engines.dsh` (`^0.2.1-rc.3`) and decides on it alone; prereleases participate in the comparison. An incompatible host needs the explicit risk grant `dsh plugin --profile <p> allow-version @jayyuen66/dsh-ocr-review@<version> --dsh-version <exact> --accept-risk`. The support window rolls: this package is verified against the three most recently released host versions at publish time and re-verified once the window moves, so the version number in this bullet is not a standing promise.
 - **No `@deepseek-ai/*` under `dependencies`, by contract** (`test/publish-manifest.test.ts` enforces it). Consumer profiles install with `nodeLinker: hoisted` and `autoInstallPeers: false`, so a host package there is materialized as a real directory next to the copy the running host already loaded. `@deepseek-ai/dsh-tools` keys its scheduler with a plain `Symbol` (not `Symbol.for`), so symbol identity is per instance and **every native tool call in that profile throws** — while this package's build, typecheck and coverage gates stay green right up to that moment.
 - **The five host packages `host.js` imports as values are required peers**: `@deepseek-ai/schemastery` (the host fork — only it resolves `.volatile()` fields), `@deepseek-ai/dsh-credentials`, `@deepseek-ai/dsh-home-paths`, `@deepseek-ai/dsh-atomic-write` and `@deepseek-ai/dsh-typert-protocol` (the Remote service base). Each is repeated in `devDependencies` at the same pin so this repository's own typecheck resolves them; the build externalizes all manifest tables, keeping bare specifiers in the artifact.
-- **What ships**: `host.js`, `client.js`, `cordis.patch.yml`, `scripts/`, `icon.svg`, `CHANGELOG.md` and `THIRD_PARTY_NOTICES.md`. `prepack` rebuilds the bundles, so nothing stale is published.
+- **What ships** (see `files` in `package.json`): `host.js`, `client.js`, `cordis.patch.yml`, `scripts/`, `locale/*.json`, `docs/`, `icon.svg`, `CHANGELOG.md` and `THIRD_PARTY_NOTICES.md`. `prepare` rebuilds the bundles, so nothing stale is published.
 
 ### <img src="https://api.iconify.design/lucide/arrow-down-to-line.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> Shared version floor
 
@@ -105,7 +105,7 @@ npm i -g @alibaba-group/open-code-review@1.13.3      # pinned to the version thi
 - **It does not install or upgrade the CLI.** The brew/npm commands are shown, never run; there is no update action and no clipboard API (a non-secure context would fail silently, looking like a dead button).
 - **No HTTP route of its own.** The data plane is one official Typert Remote namespace (`ocrReview`) through the host `/api` gateway; authentication, Host / DNS-rebinding / Origin checks and body limits are the gateway's. This package holds no CSRF token, no body cap and no route disposer.
 - **No CLI subcommand.** `dsh ocr …` does not exist.
-- **It reads no file outside** the CLI's config path, the temp files it creates itself, and the host settings / credentials services it is handed.
+- **The plugin itself reads no file outside** the CLI's config path, the host credential document and `$DSH_HOME/.env` (through `scripts/get-cred.mjs`), the PATH directories it probes for the `ocr` binary, the OCR session store it lists, the temp files it creates, and the host settings / credentials services it is handed. Repository contents are read by the `ocr` child process as the reviewed input.
 - What it *does* consume: the host `settings` and `credentials` services (provider list, key status), `shell` (every `ocr` subprocess), `jobs` (background runs) and `systemPrompt` (one routing section). A missing settings or credentials service degrades the card only — the tools keep working.
 
 ## <img src="https://api.iconify.design/lucide/plug.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> Enabling it in dsh
@@ -128,7 +128,7 @@ npm i -g @alibaba-group/open-code-review@1.13.3      # pinned to the version thi
 | `ocr_llm` | action providers/models: read-only LLM catalogue queries; no review and no connectivity test |
 | List caps | exclude and path take up to 2000 entries each; exceeding the cap rejects the call. Entries are never silently dropped — "reviewed fewer files than the list" must not be reportable as success |
 
-`wait: false` starts a background run with no host deadline (poll `ocr_session`; the subprocess is also an official job, see [Background runs as host jobs](#background-runs-as-host-jobs)), and the reaper guard takes the OCR process tree down when dsh exits in any way. Cancelling the tool call stops the corresponding background process.
+`wait: false` starts a background run with no host deadline (poll `ocr_session`; the subprocess is also an official job, see [Background runs as host jobs](#background-runs-as-host-jobs)), and on POSIX the reaper guard takes the OCR process tree down when dsh exits in any way (Windows has no reaper, see [Platforms](#platforms)). Cancelling the tool call stops the corresponding background process.
 
 ## <img src="https://api.iconify.design/lucide/sliders-horizontal.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> Settings
 
@@ -165,8 +165,8 @@ One official Typert Remote namespace, `ocrReview` (`OCR_REMOTE_NAMESPACE` in `li
 | `migrate()` | — | `{ok, migrated, skippedUnknown}` |
 | `test()` | — | `{ok, output}` — `ok` is the **test verdict**, not whether the call ran; output is redacted first, then cut to 8000 characters |
 | `probe()` | — | `{ok, version, expectedVersion, consistent, output, reason, changeText}` — one `ocr version` under a 15 s wall clock, with `OCR_NO_UPDATE=1`. `consistent` is three-state (`null` = nothing was measured, where claiming a mismatch would be claiming without evidence); `reason` names the failure arm; `changeText` carries the install/upgrade sentence only when there is a command to give |
-| `mcp()` | — | `{ok, json}` — only the `mcp_servers` object as pretty JSON, never providers or keys |
-| `saveMcp(request)` | `{json}` — raw JSON text, at most 64 KiB; stdio/remote entries are validated field by field | `{ok, count}` — writes only `mcp_servers`; other config is preserved |
+| `mcp()` | — | `{ok, json, revision}` — only the `mcp_servers` object as pretty JSON, never providers or keys; `revision` is that branch's digest |
+| `saveMcp(request)` | `{json, revision?}` — raw JSON text, at most 64 KiB; stdio/remote entries are validated field by field; `revision` is the digest from `mcp()` | `{ok, count, revision}` — writes only `mcp_servers`; other config is preserved. A stale `revision` refuses the whole write (nothing is written) and returns a readable "changed after it was read" error; omitting it keeps the old last-writer-wins behavior |
 | `auth()` | — | `{ok, output, loginCommand}` — read-only `ocr auth status --provider chatgpt`; sign-in itself stays a terminal action because it needs a browser and a local callback |
 | `chatGpt(request)` | `{model}` | `{ok, model}` — sets `provider: "chatgpt"` and `providers.chatgpt.model`, writes no key |
 
@@ -201,7 +201,7 @@ Refusals answer `{ok: false, error, status}` where `status` is a **retained sema
 | --- | --- |
 | Process boundary | The reviewed repository's paths and diff content go into the `ocr` child process, and the CLI sends them to the LLM endpoint configured in its own config.json — that egress is the review feature itself and does not pass through the dsh host. Plaintext keys never appear in tool results or Remote payloads; a value resolved by the host is used only to confirm "it resolves right now" and is discarded on the spot |
 | Redaction | All raw CLI stdout/stderr leaving this package (failure details, llm test, parse-failure echoes, session passthrough) goes through `redactKeyMaterial()`: bearer and assignment forms strictly, the standalone-key form only with random-string features, so file paths handed to the model are not erased with it |
-| On disk | Two places only: the CLI's `config.json` (plus its temp sibling, the `.bak` backup and the short-lived lock) and `ocr-review-*` / `ocr-scan-*` temp files, deleted right after reading. Pre-migration plaintext may persist in that `.bak` (mode 0600) — delete the backup yourself to be rid of it. Outside these two, the only writer is the CLI's own npm wrapper unless `ocrNoAutoUpdate` is on |
+| On disk | The CLI's `config.json` (plus its temp sibling, the `.bak` backup and the short-lived lock), the `ocr-review-*` / `ocr-scan-*` temp files (deleted right after reading), and `ocr-session-export-*` directories, which hold the HTML returned by `ocr_session` `export` and are left in place for the caller. Pre-migration plaintext may persist in that `.bak` (mode 0600) — delete the backup yourself to be rid of it. Outside these, the only writer is the CLI's own npm wrapper unless `ocrNoAutoUpdate` is on |
 
 ## <img src="https://api.iconify.design/lucide/triangle-alert.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> Known boundaries
 
@@ -219,7 +219,7 @@ Refusals answer `{ok: false, error, status}` where `status` is a **retained sema
 | Exit 0 was taken as a successful review | Exit 0 is not success: any `status` outside success / complete / partial / completed_with_warnings / completed_with_errors / skipped reports as failure. `partial` means some files failed while coverage and the comments stand. A parse failure echoes the first 500 redacted UTF-16 code units of the raw output |
 | Did the summary cover everything? | Two notions, neither replaces the other. `droppedCount` / `invalidCommentCount` say whether **this summary** listed every comment (raise `maxComments` or set 0 and re-check). Whether **the run** covered the selected files is `coverage` (`selected` is the denominator, `failedItems` names the files with their reasons) plus `budgetExceeded` and `toolCalls` |
 | `add` was refused with `already-installed` | HMR profiles refuse `add` on an already-installed package before pnpm runs — `remove` first, then `add` the target version (see Install) |
-| What happens to background processes when dsh exits? | The reaper guard takes the review/scan process tree down with TERM→1s→KILL on any host exit (including kill -9 followed by adoption); cancelling the tool call stops the corresponding background process |
+| What happens to background processes when dsh exits? | On POSIX the reaper guard takes the review/scan process tree down with TERM→1s→KILL on any host exit (including kill -9 followed by adoption); Windows has no reaper, so a hard host exit can leave an orphaned process. Cancelling the tool call stops the corresponding background process |
 | Where might a plaintext key still sit? | Nowhere this package writes. A pre-migration config's plaintext may survive in the `.bak` produced by the first write after you migrate (mode 0600); delete that backup to be rid of it |
 
 ## <img src="https://api.iconify.design/lucide/wrench.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> Development
@@ -231,7 +231,7 @@ pnpm run check   # typecheck (both sides) → lint → client build → host bui
 
 - Coverage thresholds are **100%** across four metrics over the surface `vitest.config.ts` opts into (`coverageInclude`: `host.ts` + `lib/**`); two areas are deliberately outside it: the client half (`src/**`) is exercised through the bundle and the settings-card tests, and `scripts/get-cred.mjs` is driven by process-level tests spawning a child (v8 coverage cannot see a child process) — its behavioral gate lives in `test/get-cred.test.ts`.
 - Adding this package's **local directory** to a profile (`pnpm add <path>`) needs pnpm ≥ 12.3.0: earlier pnpm 12 releases resolve an unaliased local path as a registry package name (upstream #14437, fixed in 12.3.0). Installing from the registry is unaffected.
-- Bundle freshness is pinned by `test/build-host.test.ts`: a stale `host.js` / `client.js` fails the suite. Never hand-edit the bundles; `prepack` rebuilds them.
+- Bundle freshness is pinned by `test/build-host.test.ts`: a stale `host.js` / `client.js` fails the suite. Never hand-edit the bundles; `prepare` rebuilds them.
 - The plugin source is TypeScript loaded directly by the host's cordis loader (Node ≥ 22.18 type stripping); the bundles exist for the published npm surface.
 
 ## <img src="https://api.iconify.design/lucide/scale.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> License

package/README.zh-CN.md

@@ -53,7 +53,7 @@
 - **设置卡还承载两块管理面**：可校验的 MCP servers JSON 编辑器（保存只改 `mcp_servers`），以及报告 `ocr auth` 登录态并切换 OCR provider/model 的 ChatGPT 区。两块都由人操作，不是模型工具（stdio MCP server 会执行命令，OAuth 登录需要浏览器与本地回调）。
 - **把外部 `ocr`（open-code-review）CLI 封装成七个模型工具。** 宿主对工具入参零校验，形状、类型与枚举闸全在本包内：用户可控字符串一律单引号转义，枚举一律白名单钳制，错类型直接报错——绝不静默收窄或放宽审查范围。
 - **一张设置卡片**（client 半）从宿主自己的 `llm-pi-ai` 设置条目取 provider/model 清单、从宿主凭据服务取 key 状态。两个服务缺席时卡片显示降级原因，工具与设置照常可用。
-- **应用一次选择写的是 CLI 自己的 `~/.opencodereview/config.json`**——写进去的是 `api_key_cmd` 命令，OCR 运行期经它读宿主凭据 ref；任何地方都不落明文 key。
+- **应用一次选择写的是 CLI 自己的 `~/.opencodereview/config.json`**——写进去的是 `api_key_cmd` 命令，OCR 运行期经它读宿主凭据 ref；本包不把明文 key 写进 `config.json`，但首次改写前复制的 `.bak` 保留改写前的整份内容，其中可能有迁移前的明文 key（权限 0600），迁移后自行删除该备份。
 - **评审结果是一份结构化摘要，字段分两套口径**：OCR 审出了什么（`status`/`aggregation`/`topComments`/`warnings`），以及这一场有没有真把选中的文件审完（`coverage`/`budgetExceeded`/`toolCalls`）。CLI 以 `--audience agent` 被调用，进度输出被它压掉——后一套口径只能从这些字段里读。
 - **CLI 可得性只有一份判据**（`lib/cli.ts` 的 `resolveOcrAvailability`）：纯读文件系统、绝不起进程、每次调用现读。设置卡状态行、插件详情页徽标与启用指引渲染的都是这同一份答案，「用的是哪一份」不许有三套说法。
 - **后台运行（`wait: false`）是官方宿主作业**：`job_list` / `job_output` / `job_kill` 看得见、读得到、也停得掉一场超出工具调用生命周期的评审。
@@ -67,10 +67,10 @@ dsh plugin --profile web add @jayyuen66/dsh-ocr-review
 卸载用 `dsh plugin --profile web remove @jayyuen66/dsh-ocr-review`。包在公共 npm 上，安装不需要凭据。
 
 - **升级已装的那一份要「先 remove 再 add」。** profile 跑着 HMR（出厂那几个都跑）时，`add` 一个 profile 已经依赖着的包会在 pnpm 动手之前就被拒（`already-installed`）——先 `remove` 再 `add` 目标版本，新版不必重启就起跑。没跑 HMR 时同一个 `add` 照样走 pnpm，报 `restart-required`。
-- **要求 Node.js `>= 22.12`，宿主 dsh 在 `0.2.1-rc.3` 线上。** 宿主只读 `engines.dsh`（`^0.2.1-rc.3`）并独立裁决，预发布号参与比较。不合的宿主要显式登记风险豁免：`dsh plugin --profile <p> allow-version @jayyuen66/dsh-ocr-review@<版本> --dsh-version <确切运行版本> --accept-risk`。支持窗口是滚动的：本包在发布时最近的三个已发布宿主版本上逐版取证，窗口滚动后重新取证，不把这一句里的版本号当长期承诺。
+- **要求 Node.js `>= 22.12`，宿主 dsh 在 `0.2.1-rc.3` / `0.2.2-alpha.2` 线上。** 宿主只读 `engines.dsh`（`^0.2.1-rc.3`）并独立裁决，预发布号参与比较。不合的宿主要显式登记风险豁免：`dsh plugin --profile <p> allow-version @jayyuen66/dsh-ocr-review@<版本> --dsh-version <确切运行版本> --accept-risk`。支持窗口是滚动的：本包在发布时最近的三个已发布宿主版本上逐版取证，窗口滚动后重新取证，不把这一句里的版本号当长期承诺。
 - **`dependencies` 里不放任何 `@deepseek-ai/*`，这是契约**（`test/publish-manifest.test.ts` 钉着）。消费方 profile 用 `nodeLinker: hoisted` 与 `autoInstallPeers: false` 安装，宿主包进了那张表就会落成真实目录，与宿主进程已加载的那份并存。`@deepseek-ai/dsh-tools` 的调度器键是普通 `Symbol`（不是 `Symbol.for`），符号身份按实例计算——那个 profile 里**每一次原生工具调用都抛**，而本包的构建、类型检查与覆盖率门在此前一路绿。
 - **`host.js` 以值导入的五枚宿主包是非 optional 的 peer**：`@deepseek-ai/schemastery`（宿主 fork——`.volatile()` 的解析只在它有实现）、`@deepseek-ai/dsh-credentials`、`@deepseek-ai/dsh-home-paths`、`@deepseek-ai/dsh-atomic-write` 与 `@deepseek-ai/dsh-typert-protocol`（Remote 的 Service 基类）。五枚同时以同一钉版另列进 `devDependencies`，本仓自己的类型检查才解析得到；构建对 manifest 三张表一律外部化，产物里保持裸说明符。
-- **发布面**：`host.js`、`client.js`、`cordis.patch.yml`、`scripts/`、`icon.svg`、`CHANGELOG.md` 与 `THIRD_PARTY_NOTICES.md`。`prepack` 重建两个 bundle，发出去的永远是当前源码的产物。
+- **发布面**（以 `package.json` 的 `files` 为准）：`host.js`、`client.js`、`cordis.patch.yml`、`scripts/`、`locale/*.json`、`docs/`、`icon.svg`、`CHANGELOG.md` 与 `THIRD_PARTY_NOTICES.md`。`prepare` 重建两个 bundle，发出去的永远是当前源码的产物。
 
 ### <img src="https://api.iconify.design/lucide/arrow-down-to-line.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> shared 的版本下限
 
@@ -105,7 +105,7 @@ npm i -g @alibaba-group/open-code-review@1.13.3      # 钉在本包核对的那
 - **它不安装、不升级 CLI。** brew/npm 命令只展示、不执行；没有更新动作，也不接剪贴板 API（非安全上下文会静默失败，看上去像按钮没反应）。
 - **没有自己的 HTTP 路由。** 数据面是一枚官方 Typert Remote 命名空间（`ocrReview`），经宿主 `/api` 网关到达；认证、Host / DNS 重绑定 / Origin 判据与请求体上限都是网关的。本包没有 CSRF token、没有 body 上限，也没有路由释放器。
 - **没有 CLI 子命令。** 不存在 `dsh ocr …`。
-- **不读以下范围之外的文件**：CLI 配置路径、自己创建的临时文件、以及宿主交给它的设置 / 凭据服务。
+- **本插件自己不读以下范围之外的文件**：CLI 配置路径、宿主凭据文档与 `$DSH_HOME/.env`（经 `scripts/get-cred.mjs`）、为找 `ocr` 二进制而探测的 PATH 目录、`ocr_session` 列出的会话存储、自己创建的临时文件，以及宿主交给它的设置 / 凭据服务。被审查仓库的内容由 `ocr` 子进程作为评审输入读取。
 - 它*确实*消费的：宿主 `settings` 与 `credentials` 服务（provider 清单、key 状态）、`shell`（每一条 `ocr` 子进程）、`jobs`（后台运行）与 `systemPrompt`（一段路由）。settings 或 credentials 缺席只降级卡片——工具照常可用。
 
 ## <img src="https://api.iconify.design/lucide/plug.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> 在 dsh 里启用
@@ -128,7 +128,7 @@ npm i -g @alibaba-group/open-code-review@1.13.3      # 钉在本包核对的那
 | `ocr_llm` | action providers/models：只读查询 LLM 清单；不评审、不测连通性 |
 | 清单上限 | exclude 与 path 各收 2000 条；超限直接拒绝整次调用。条目绝不静默丢弃——「比清单少审了几份」不许以成功的口径上报 |
 
-`wait: false` 起后台运行、不挂宿主 deadline（用 `ocr_session` 轮询；该子进程同时是一枚官方作业，见[后台运行与官方作业](#后台运行与官方作业)）；dsh 以任何方式退出时，收割守护把 OCR 进程树收走。取消工具调用即终止对应的后台进程。
+`wait: false` 起后台运行、不挂宿主 deadline（用 `ocr_session` 轮询；该子进程同时是一枚官方作业，见[后台运行与官方作业](#后台运行与官方作业)）；POSIX 上 dsh 以任何方式退出时，收割守护把 OCR 进程树收走（Windows 没有收割，见「已知边界」）。取消工具调用即终止对应的后台进程。
 
 ## <img src="https://api.iconify.design/lucide/sliders-horizontal.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> 设置项
 
@@ -165,8 +165,8 @@ npm i -g @alibaba-group/open-code-review@1.13.3      # 钉在本包核对的那
 | `migrate()` | — | `{ok, migrated, skippedUnknown}` |
 | `test()` | — | `{ok, output}`——`ok` 是**测试结论**，不是这次调用成没成；output 先脱敏再截 8000 字符 |
 | `probe()` | — | `{ok, version, expectedVersion, consistent, output, reason, changeText}`——15 秒墙钟内跑一次 `ocr version`，恒定带 `OCR_NO_UPDATE=1`。`consistent` 是三态（`null` = 没量到，此时宣称「不一致」就是把没证据的事说成结论）；`reason` 点名失败那一档；`changeText` 只在真有一条该给的命令时非空 |
-| `mcp()` | — | `{ok, json}`——只回 `mcp_servers` 对象（pretty JSON），不含 providers/keys |
-| `saveMcp(request)` | `{json}`——原始 JSON 文本，上限 64 KiB；stdio/remote 条目逐字段校验 | `{ok, count}`——只写 `mcp_servers`，其他配置原样保留 |
+| `mcp()` | — | `{ok, json, revision}`——只回 `mcp_servers` 对象（pretty JSON），不含 providers/keys；`revision` 是这一支的摘要 |
+| `saveMcp(request)` | `{json, revision?}`——原始 JSON 文本，上限 64 KiB；stdio/remote 条目逐字段校验；`revision` 取 `mcp()` 交回的那一枚 | `{ok, count, revision}`——只写 `mcp_servers`，其他配置原样保留。基线过期时整笔拒绝（盘上不动）并回可读的「读取之后已被改动」；不带基线则沿用原来的后写覆盖 |
 | `auth()` | — | `{ok, output, loginCommand}`——只读 `ocr auth status --provider chatgpt`；登录本身要浏览器与本地回调，仍留在终端执行 |
 | `chatGpt(request)` | `{model}` | `{ok, model}`——写 `provider: "chatgpt"` 与 `providers.chatgpt.model`，不写 key |
 
@@ -201,7 +201,7 @@ npm i -g @alibaba-group/open-code-review@1.13.3      # 钉在本包核对的那
 | --- | --- |
 | 进程边界 | 被审查仓库的路径与 diff 内容进 `ocr` 子进程，CLI 再把它们发给自己在 config.json 里配置的 LLM 端点——这条外发是审查功能本身，不经 dsh 宿主。明文 key 不进工具返回、也不进 Remote 应答；宿主侧解析到的值只用于确认「现在解析得到」，当场丢弃 |
 | 原始输出脱敏 | 本包出去的 CLI 原始 stdout/stderr（失败详情、llm test、解析失败回显、session 透传）统一过 `redactKeyMaterial()`：Bearer 与赋值形态从严抹除，独立 key 形态额外要求随机串特征，免得把要交给模型的文件路径一起抹掉 |
-| 写盘范围 | 只有两处：CLI 的 `config.json`（含临时文件、`.bak` 备份与短暂的锁）与系统临时目录下的 `ocr-review-*` / `ocr-scan-*`（读完即删）。迁移前的明文可能留在那次写入产生的 `.bak` 里（权限 0600）——要彻底清掉需自行删除该备份。这两处之外，`ocrNoAutoUpdate` 没置真时唯一的写者就是 CLI 自己那层 npm 包装 |
+| 写盘范围 | CLI 的 `config.json`（含临时文件、`.bak` 备份与短暂的锁）、系统临时目录下的 `ocr-review-*` / `ocr-scan-*`（读完即删），以及 `ocr-session-export-*` 目录——那是 `ocr_session` 的 `export` 返回的 HTML，留给调用方，不自动删除。迁移前的明文可能留在那次写入产生的 `.bak` 里（权限 0600）——要彻底清掉需自行删除该备份。这些之外，`ocrNoAutoUpdate` 没置真时唯一的写者就是 CLI 自己那层 npm 包装 |
 
 ## <img src="https://api.iconify.design/lucide/triangle-alert.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> 已知边界
 
@@ -231,7 +231,7 @@ pnpm run check   # typecheck（两侧）→ lint → client 构建 → host 构
 
 - 覆盖率阈值**四项 100%**，分母是 `vitest.config.ts` 里 `coverageInclude` 选定的那一面（`host.ts` + `lib/**`）；两块刻意在分母外：客户端半（`src/**`）经 bundle 与设置卡用例覆盖，`scripts/get-cred.mjs` 由进程级用例另起进程驱动（v8 覆盖率看不到子进程），它的行为门禁在 `test/get-cred.test.ts`。
 - 往 profile 加本包的**本地目录**（`pnpm add <路径>`）需要 pnpm ≥ 12.3.0：更早的 pnpm 12 把无别名的本地路径当 registry 包名解析（上游 #14437，12.3.0 修复）。从 registry 装不受影响。
-- 产物新鲜度由 `test/build-host.test.ts` 钉着：`host.js` / `client.js` 落后于源码就红。发布物不手改；`prepack` 重建。
+- 产物新鲜度由 `test/build-host.test.ts` 钉着：`host.js` / `client.js` 落后于源码就红。发布物不手改；`prepare` 重建。
 - 插件源码是 TypeScript，由宿主的 cordis Loader 直接加载（Node ≥ 22.18 类型剥离）；bundle 只为 npm 发布面存在。
 
 ## <img src="https://api.iconify.design/lucide/scale.svg?color=%23658EFF&height=22" height="22" width="22" align="absmiddle" alt="" /> 许可

package/THIRD_PARTY_NOTICES.md

@@ -25,6 +25,32 @@
 `currentColor` 换成本包插件图标配色（`#658EFF` 主色 + `#54ECE7` 底衬），并把外层 `<g>` 与
 画布尺寸对齐本族插件统一的 `36×36` / `viewBox 0 0 24 24` 规格。
 
+`icon.svg` 随包分发，没有独立的 npm 包承载上游许可文本，因此在下文完整保留 MIT 正文：
+
+```text
+MIT License
+
+Copyright (c) Paweł Kuna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## 机制与接口来源：open-code-review（ocr CLI）
 
 - 上游项目：`open-code-review`
@@ -56,7 +82,8 @@
 | 依赖 | 版本 | 许可 | 引入方 |
 | --- | --- | --- | --- |
 | `@alibaba-group/open-code-review` | 1.13.3（核对版本，非依赖） | Apache-2.0（Alibaba） | **不在依赖表里**：用户自选 `brew install open-code-review` 或 `npm i -g @alibaba-group/open-code-review@<版本>`，本包只 spawn 它 |
-| `js-yaml` | ^5.4.3 | MIT | `scripts/get-cred.mjs` 读 dsh 托管凭据文档 |
+| `js-yaml` | 5.4.3（精确钉版） | MIT | `scripts/get-cred.mjs` 读 dsh 托管凭据文档 |
+| `@jayyuen66/dsh-plugin-shared` | catalog（伞根 0.2.2） | MIT | `host.ts` / `lib/*` / `src/*` 的 job-outcome、locale、record、errors、card-* 等公共面（值导入，构建时外部化） |
 | `zod` | catalog（伞根 4.6.7） | MIT | 设置卡 `src/remote.ts` 的 strict codec 形状校验；client 产物由宿主 `PLATFORM_MODULES` 提供 |
 
 dsh 宿主侧的包分两档：产物里以**值**导入、且列在 `peerDependencies` 的五枚（`@deepseek-ai/schemastery` 宿主 fork、`@deepseek-ai/dsh-credentials`、`@deepseek-ai/dsh-home-paths`、`@deepseek-ai/dsh-atomic-write` 与 `@deepseek-ai/dsh-typert-protocol`）由宿主在场提供、不随本包分发；其余 `@deepseek-ai/dsh-*` 与 `@deepseek-ai/cordis` 只在 `devDependencies` 里，用途是把类型绑到官方声明上（type-only 绑定），产物里不留说明符。本包按 dsh `0.2.2-alpha.2` 逐条核对过（同版的 cordis `4.0.6-alpha.1` 与 schemastery `3.18.6-alpha.1` fork 一并核对）。

package/client.js

@@ -21,7 +21,6 @@ const UI_MESSAGES = {
 		save: "保存",
 		saving: "保存中…",
 		revert: "撤销",
-		saveFailed: "保存失败：",
 		saveRefused: "未写入（宿主拒收或跳过）：{fields}",
 		loadProvidersFailed: "加载 providers 失败：{error}（远程面未就绪？重启 dsh 后重试）",
 		remoteUnavailable: "远程服务不可用：宿主没有挂上本插件的设置通道。",
@@ -74,6 +73,7 @@ const UI_MESSAGES = {
 		mcpSaving: "保存中…",
 		mcpSaved: "MCP servers 已保存",
 		mcpLoadFailed: "读取 MCP 配置失败：",
+		mcpNotLoaded: "还没读到当前 MCP 配置，先等读取完成（失败时先修好读取）再保存",
 		chatGptTitle: "ChatGPT（OCR auth）",
 		chatGptHint: "登录态由 ocr auth 管理；本卡片只读查询状态，并在登录后把 provider 切到 chatgpt。",
 		chatGptCheck: "检查登录态",
@@ -91,7 +91,7 @@ const UI_MESSAGES = {
 		binaryUnknown: "状态未取到：刷新本页，或确认 dsh 的 web 服务已起来",
 		binaryBundled: "随本插件分发的兜底入口已就位：{path}（{channel}）",
 		binaryPath: "用 PATH 上的全局安装：{path}（{channel}）",
-		binaryNone: "未找到 ocr：PATH 与随包兜底两条路都没有可执行候选。装法与版本看下一行（由插件按核对版本给出）",
+		binaryNone: "未找到 ocr：PATH 与随包兜底两条路都没有可执行候选",
 		channelBrew: "brew formula",
 		channelNpm: "npm 全局包",
 		channelUnknown: "装法未识别",
@@ -122,7 +122,6 @@ const UI_MESSAGES = {
 		save: "Save",
 		saving: "Saving…",
 		revert: "Revert",
-		saveFailed: "save failed: ",
 		saveRefused: "not written (host refused or skipped): {fields}",
 		loadProvidersFailed: "failed to load providers: {error} (remote face not ready? restart dsh and retry)",
 		remoteUnavailable: "remote service unavailable: the host did not mount this plugin's settings channel",
@@ -175,6 +174,7 @@ const UI_MESSAGES = {
 		mcpSaving: "Saving…",
 		mcpSaved: "MCP servers saved",
 		mcpLoadFailed: "Failed to read the MCP config: ",
+		mcpNotLoaded: "The current MCP config has not loaded yet; wait for the read (or fix it) before saving",
 		chatGptTitle: "ChatGPT (OCR auth)",
 		chatGptHint: "Sign-in is managed by ocr auth; this card only reports the status and switches OCR's provider to chatgpt after you sign in.",
 		chatGptCheck: "Check sign-in",
@@ -192,7 +192,7 @@ const UI_MESSAGES = {
 		binaryUnknown: "status not reported: reload this page, or check that the dsh web server is up",
 		binaryBundled: "bundled fallback entry in place: {path} ({channel})",
 		binaryPath: "using the global install on PATH: {path} ({channel})",
-		binaryNone: "ocr not found: neither PATH nor the bundled fallback has an executable candidate. The install command and version are on the next line (this plugin states the version its contract was verified against)",
+		binaryNone: "ocr not found: neither PATH nor the bundled fallback has an executable candidate",
 		channelBrew: "brew formula",
 		channelNpm: "npm global package",
 		channelUnknown: "install method unrecognised",
@@ -201,7 +201,7 @@ const UI_MESSAGES = {
 		versionDiverged: "this machine reports {actual}, which is not the verified {expected}: comment wording and severity may drift between versions",
 		badgeDiverged: "ocr version differs",
 		detectCli: "Detect version",
-		detecting: "Detecting...",
+		detecting: "Detecting…",
 		probeVersion: "ocr version: {version}",
 		probeReason: "no version read: {reason}",
 		badgeBundled: "ocr from bundled fallback",
@@ -827,7 +827,10 @@ const SELECT_SCHEMA = zod.z.object({
 	model: zod.z.string({ error: SELECT_MESSAGE })
 }, { error: "select request must be an object" });
 const MCP_SAVE_MESSAGE = "mcp save request requires a string json";
-const MCP_SAVE_SCHEMA = zod.z.object({ json: zod.z.string({ error: MCP_SAVE_MESSAGE }) }, { error: MCP_SAVE_MESSAGE });
+const MCP_SAVE_SCHEMA = zod.z.object({
+	json: zod.z.string({ error: MCP_SAVE_MESSAGE }),
+	revision: zod.z.string().optional()
+}, { error: MCP_SAVE_MESSAGE });
 const CHAT_GPT_MESSAGE = "chatgpt request requires a string model";
 const CHAT_GPT_SCHEMA = zod.z.object({ model: zod.z.string({ error: CHAT_GPT_MESSAGE }) }, { error: CHAT_GPT_MESSAGE });
 /** 把宿主那九个方法挂到客户端远程面上的描述符（`id` 的形状照生成器：`<包>#<命名空间>/<方法>`）。
@@ -953,9 +956,10 @@ const OCR_DESCRIPTORS = [
 const isRemoteMounter = (value) => e$3(value) && typeof value["$mount"] === "function";
 /** 同上：命名空间服务（挂载之后才有，缺它说明网关没认这枚贡献）。 */
 const isOcrNamespace = (value) => e$3(value) && typeof value["providers"] === "function" && typeof value["select"] === "function" && typeof value["migrate"] === "function" && typeof value["test"] === "function" && typeof value["probe"] === "function" && typeof value["mcp"] === "function" && typeof value["saveMcp"] === "function" && typeof value["auth"] === "function" && typeof value["chatGpt"] === "function";
-/** 网关回执 → 值；载体/网关失败抛（卡片那层按「请求失败」显示）。 */
+/** 网关回执 → 值；载体/网关失败抛（卡片那层按「请求失败」显示）。
+*  机器码放 `cause`：卡片只展示 message，`REMOTE_...` 这类内部标识不是给用户看的。 */
 function unwrap(result) {
-	if (!result.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
+	if (!result.ok) throw new Error(result.error.message, { cause: { code: result.error.code } });
 	return result.value;
 }
 /**
@@ -971,7 +975,7 @@ function buildOcrReader(ctx) {
 	let mounted;
 	const remoteOf = () => {
 		const remote = ctx.get?.("remote", false);
-		if (!isRemoteMounter(remote)) throw new Error("remote 未提供：当前部署没有远程读面（每次读取都会重新解析）");
+		if (!isRemoteMounter(remote)) throw new Error("remote 未提供：当前部署没有远程读面");
 		return remote;
 	};
 	const namespaceOf = async () => {
@@ -987,7 +991,10 @@ function buildOcrReader(ctx) {
 			throw error;
 		}
 		const namespace = ctx.get?.(OCR_SERVICE_KEY, false);
-		if (!isOcrNamespace(namespace)) throw new Error(`${OCR_SERVICE_KEY} 未提供：宿主网关没有挂上这枚命名空间`);
+		if (!isOcrNamespace(namespace)) {
+			mounted = void 0;
+			throw new Error(`${OCR_SERVICE_KEY} 未提供：宿主网关没有挂上这枚命名空间`);
+		}
 		return namespace;
 	};
 	return {
@@ -1012,8 +1019,11 @@ function buildOcrReader(ctx) {
 		async mcp() {
 			return unwrap(await (await namespaceOf()).mcp());
 		},
-		async saveMcp(json) {
-			return unwrap(await (await namespaceOf()).saveMcp({ json }));
+		async saveMcp(json, revision) {
+			return unwrap(await (await namespaceOf()).saveMcp(revision === void 0 ? { json } : {
+				json,
+				revision
+			}));
 		},
 		async auth() {
 			return unwrap(await (await namespaceOf()).auth());
@@ -1253,14 +1263,13 @@ function currentConfigText(t, current) {
 		keyPart: t(current.keyIsDynamic ? "dynamicKey" : "plainKeyWarning")
 	});
 }
-/** 装法枚举到文案键：查表而不是嵌套三元（本仓 lint 禁嵌套三元），查不到就是「未识别」那一档。 */
-const CHANNEL_KEYS = {
-	brew: "channelBrew",
-	npm: "channelNpm"
-};
-/** 那份 CLI 是怎么装上的，翻成人话。判不出来源（含 host 没报这一档）不猜。 */
+/** 那份 CLI 是怎么装上的，翻成人话。判不出来源（含 host 没报这一档）不猜。
+*  逐个比对已知值而不是查一张普通对象表：`channel` 来自 wire，只校验了「是字符串」，
+*  用属性查表时 `"toString"`、`"constructor"` 一类会命中原型上的成员，把函数当文案键传下去。 */
 function channelText(t, channel) {
-	return t(CHANNEL_KEYS[channel ?? ""] ?? "channelUnknown");
+	if (channel === "brew") return t("channelBrew");
+	if (channel === "npm") return t("channelNpm");
+	return t("channelUnknown");
 }
 /**
 * 外部 CLI 可得性那一行的文本。三档来源与「宿主没报」四种说法，判据全在 host 侧
@@ -1719,7 +1728,7 @@ function buildMcpAdmin(props) {
 	const textarea = (0, react.createElement)("textarea", {
 		"data-field": "mcpJson",
 		value: props.mcpJson,
-		disabled: !props.writable || props.mcpBusy || !props.available,
+		disabled: !props.writable || props.mcpBusy || !props.available || !props.mcpReady,
 		"aria-label": t("mcpTitle"),
 		className: "dsu-input dsu-textarea dsu-mono ocr-adminTextarea",
 		onChange: (event) => {
@@ -1730,7 +1739,7 @@ function buildMcpAdmin(props) {
 		type: "button",
 		className: "dsu-btn",
 		"data-field": "mcpSave",
-		disabled: !props.writable || props.mcpBusy || !props.available,
+		disabled: !props.writable || props.mcpBusy || !props.available || !props.mcpReady,
 		onClick: props.onMcpSave
 	}, props.mcpBusy ? t("mcpSaving") : t("mcpSave"));
 	const message = props.mcpMsg === null ? null : (0, react.createElement)("p", { className: "dsu-hint" }, props.mcpMsg);
@@ -1825,7 +1834,8 @@ function readerPost(reader, t) {
 		}
 	};
 }
-/** POST select：把选中的 provider/model 写进 OCR 配置，回执里按 autoVerify 决定是否带 llm test。 */
+/** POST select：把选中的 provider/model 写进 OCR 配置，回执里按 autoVerify 决定是否带 llm test。
+*  导出与 `runProbe` 同因：卡片上的动作以纯函数形态可测（回执着色与文案都在这里定）。 */
 async function runApplySelection(deps) {
 	const { t, effectiveProvider, effectiveModel } = deps;
 	if (!effectiveProvider || !effectiveModel) {
@@ -1844,10 +1854,12 @@ async function runApplySelection(deps) {
 		})).json();
 		if (i$1(selJson, "ok") === true) {
 			let testText;
+			let verified = true;
 			const llmTestRaw = i$1(selJson, "llmTest");
 			if (e$3(llmTestRaw)) {
 				const testOutput = strOf(i$1(llmTestRaw, "output")).slice(0, 400);
-				testText = i$1(llmTestRaw, "ok") === true ? t("llmTestPassed") : `${t("llmTestFailed")}${testOutput}`;
+				verified = i$1(llmTestRaw, "ok") === true;
+				testText = verified ? t("llmTestPassed") : `${t("llmTestFailed")}${testOutput}`;
 			} else testText = t("notVerified");
 			const appliedText = t("applied", {
 				provider: effectiveProvider,
@@ -1855,7 +1867,7 @@ async function runApplySelection(deps) {
 				test: testText
 			});
 			deps.setActionMsg({
-				ok: true,
+				ok: verified,
 				text: appliedText
 			});
 			deps.refresh();
@@ -1888,7 +1900,9 @@ async function runMigrateKeys(deps) {
 		const migrated = Array.isArray(migratedVal) ? migratedVal.filter((item) => typeof item === "string") : [];
 		const skipped = Array.isArray(skippedVal) ? skippedVal.filter((item) => typeof item === "string") : [];
 		const ok = i$1(json, "ok") === true;
-		const head = ok ? (migrated.length > 0 ? t("migratedPrefix") + migrated.join(", ") : t("noPlainKey")) + (skipped.length > 0 ? t("skippedPrefix") + skipped.join(", ") : "") : t("migrateFailed");
+		const migratedText = migrated.length > 0 ? t("migratedPrefix") + migrated.join(", ") : t("noPlainKey");
+		const skippedText = skipped.length > 0 ? t("skippedPrefix") + skipped.join(", ") : "";
+		const head = ok ? migratedText + skippedText : t("migrateFailed");
 		deps.setActionMsg({
 			ok,
 			text: head
@@ -2026,16 +2040,14 @@ function buildProviderPanel(deps) {
 	const { actionMsg } = deps;
 	return [buildProviderSection(deps), actionMsg ? (0, react.createElement)("p", { className: statusClass(actionMsg.ok) }, actionMsg.text) : null];
 }
-/** 管理区的状态与动作（MCP 配置 + ChatGPT 登录态/切换）；OcrCard 只负责摆位置。 */
-function useAdminPanel(reader, t) {
+/** MCP 配置编辑器的状态与动作：读、写，以及「没读成功不许写」的判据。 */
+function useMcpPanel(reader, t) {
 	const [mcpJson, setMcpJson] = (0, react.useState)("{}");
 	const [mcpBusy, setMcpBusy] = (0, react.useState)(false);
 	const [mcpMsg, setMcpMsg] = (0, react.useState)(null);
-	const [authOutput, setAuthOutput] = (0, react.useState)(null);
-	const [authBusy, setAuthBusy] = (0, react.useState)(false);
-	const [authMsg, setAuthMsg] = (0, react.useState)(null);
-	const [authModel, setAuthModel] = (0, react.useState)("");
-	const [loginCommand, setLoginCommand] = (0, react.useState)("ocr auth login --provider chatgpt");
+	const [mcpReady, setMcpReady] = (0, react.useState)(false);
+	const mcpDirtyRef = (0, react.useRef)(false);
+	const mcpRevisionRef = (0, react.useRef)(void 0);
 	const loadMcp = (0, react.useCallback)(async () => {
 		if (reader === void 0) {
 			setMcpMsg(t("adminUnavailable"));
@@ -2043,10 +2055,17 @@ function useAdminPanel(reader, t) {
 		}
 		try {
 			const reply = await reader.mcp();
-			if ("status" in reply) setMcpMsg(reply.error);
-			else setMcpJson(reply.json);
+			if ("status" in reply) {
+				setMcpMsg(reply.error);
+				setMcpReady(false);
+			} else {
+				if (!mcpDirtyRef.current) setMcpJson(reply.json);
+				mcpRevisionRef.current = reply.revision;
+				setMcpReady(true);
+			}
 		} catch (error) {
 			setMcpMsg(`${t("mcpLoadFailed")}${String(error)}`);
+			setMcpReady(false);
 		}
 	}, [reader, t]);
 	(0, react.useEffect)(() => {
@@ -2057,17 +2076,48 @@ function useAdminPanel(reader, t) {
 			setMcpMsg(t("adminUnavailable"));
 			return;
 		}
+		if (!mcpReady) {
+			setMcpMsg(t("mcpNotLoaded"));
+			return;
+		}
 		setMcpBusy(true);
 		setMcpMsg(null);
 		try {
-			const reply = await reader.saveMcp(mcpJson);
-			setMcpMsg("status" in reply ? reply.error : t("mcpSaved"));
+			const reply = await reader.saveMcp(mcpJson, mcpRevisionRef.current);
+			if ("status" in reply) setMcpMsg(reply.error);
+			else {
+				mcpDirtyRef.current = false;
+				mcpRevisionRef.current = reply.revision;
+				setMcpMsg(t("mcpSaved"));
+			}
 		} catch (error) {
 			setMcpMsg(String(error));
 		} finally {
 			setMcpBusy(false);
 		}
 	}
+	return {
+		mcpJson,
+		mcpReady,
+		mcpBusy,
+		mcpMsg,
+		onMcpChange: (value) => {
+			mcpDirtyRef.current = true;
+			setMcpJson(value);
+		},
+		onMcpSave: () => {
+			saveMcp();
+		}
+	};
+}
+/** 管理区的状态与动作（MCP 配置 + ChatGPT 登录态/切换）；OcrCard 只负责摆位置。 */
+function useAdminPanel(reader, t) {
+	const mcp = useMcpPanel(reader, t);
+	const [authOutput, setAuthOutput] = (0, react.useState)(null);
+	const [authBusy, setAuthBusy] = (0, react.useState)(false);
+	const [authMsg, setAuthMsg] = (0, react.useState)(null);
+	const [authModel, setAuthModel] = (0, react.useState)("");
+	const [loginCommand, setLoginCommand] = (0, react.useState)("ocr auth login --provider chatgpt");
 	async function checkAuth() {
 		if (reader === void 0) {
 			setAuthMsg(t("adminUnavailable"));
@@ -2107,18 +2157,12 @@ function useAdminPanel(reader, t) {
 	}
 	return {
 		available: reader !== void 0,
-		mcpJson,
-		mcpBusy,
-		mcpMsg,
+		...mcp,
 		authOutput,
 		authBusy,
 		authMsg,
 		authModel,
 		loginCommand,
-		onMcpChange: setMcpJson,
-		onMcpSave: () => {
-			saveMcp();
-		},
 		onAuthModelChange: setAuthModel,
 		onCheckAuth: () => {
 			checkAuth();
@@ -2140,10 +2184,19 @@ function OcrCard(props) {
 	const [busy, setBusy] = (0, react.useState)(null);
 	const [actionMsg, setActionMsg] = (0, react.useState)(null);
 	const [probeMsg, setProbeMsg] = (0, react.useState)(null);
-	const refresh = (0, react.useCallback)(async () => refreshProviders(props.reader, t, {
-		setData,
-		setFetchError
-	}), [props.reader, t]);
+	const refreshSeq = (0, react.useRef)(0);
+	const refresh = (0, react.useCallback)(async () => {
+		refreshSeq.current += 1;
+		const seq = refreshSeq.current;
+		return refreshProviders(props.reader, t, {
+			setData: (payload) => {
+				if (seq === refreshSeq.current) setData(payload);
+			},
+			setFetchError: (message) => {
+				if (seq === refreshSeq.current) setFetchError(message);
+			}
+		});
+	}, [props.reader, t]);
 	(0, react.useEffect)(() => {
 		refresh();
 	}, [refresh]);
@@ -2323,6 +2376,7 @@ exports.inject = inject;
 exports.isOwnSubject = isOwnSubject;
 exports.loadCliStatus = loadCliStatus;
 exports.providerOptionLabel = providerOptionLabel;
+exports.runApplySelection = runApplySelection;
 exports.runProbe = runProbe;
 exports.saveSettingsDraft = saveSettingsDraft;
     return module.exports;