@jayyuen66/dsh-ocr-review 0.1.3 → 0.1.4-rc

package/README.md

@@ -20,7 +20,7 @@ English · [中文](README.zh-CN.md)
 - Platforms: macOS and Linux are the targets. Process reaping (the reaper guard around `ocr_review` / `ocr_scan`) depends on a POSIX toolchain - bash traps and job control plus the process-group semantics of `ps` / `pgrep` / `kill`. None of that exists on Windows, so the package runs the bare command there (guarded by `process.platform`): no reaping, but it still works. The cost is that a hard host exit can leave an orphaned OCR process.
 - The provider list and the key status come from the official host channels `ctx.settings.describe()` (the `value.providers` of the `llm-pi-ai` entry) and `ctx.credentials`.
 - When either is missing the card shows the degradation reason while tools and settings keep working.
-- The host must be `>=0.2.0-rc.2`: declared in `peerDependencies` (the host checks it on plugin install from 0.1.7-rc; alpha.1 has no such gate yet) and in `engines.dsh` (same value, read by nothing).
+- The host must be `>= 0.2.1-alpha.1`: declared in `peerDependencies` (the host checks it on plugin install from 0.1.7-rc; alpha.1 has no such gate yet) and in `engines.dsh` (same value, read by nothing).
 
 ## Installation
 
@@ -30,7 +30,10 @@ dsh plugin --profile web add @jayyuen66/dsh-ocr-review
 
 - The packages are on the public npm registry, so installation needs no credentials.
 - The published files are only `host.js`, `client.js`, `cordis.patch.yml` and `scripts` (`prepack` rebuilds both bundles); source repository: see `repository.url` in package.json.
-- Runtime value dependencies are `@jayyuen66/dsh-plugin-shared`, `@deepseek-ai/schemastery` (the host's fork of schemastery — only it implements the 0.1.7 `.volatile()` resolution) and `js-yaml` (the last one used only by `scripts/get-cred.mjs`).
+- No `@deepseek-ai/*` goes in `dependencies`, and that is not a style preference. Consumers of this package are dsh plugins installed into a profile (`nodeLinker: hoisted`, `autoInstallPeers: false`), so any host package listed under `dependencies` is written into that profile as a **real directory**, coexisting with the copy the host process already loaded. `@deepseek-ai/dsh-tools` keys its `TOOL_RUNTIME_SCHEDULER` with a plain `Symbol` (not `Symbol.for`), so symbol identity is per module instance: the host's `dsh-agent-loop` reads a `ToolRuntime` mounted from the duplicate using its own copy's symbol, gets `undefined`, and **every native tool call throws** `Cannot read properties of undefined (reading 'prepare')` — the whole profile loses its tools. This package's build, typecheck and tests all stay green right up to that point, so `test/publish-manifest.test.ts` pins the invariant in the manifest instead.
+- The four host packages this bundle imports as **values** are required (non-optional) `peerDependencies`: `@deepseek-ai/schemastery` (the host's fork of schemastery — only it implements the 0.1.7 `.volatile()` resolution), `@deepseek-ai/dsh-credentials`, `@deepseek-ai/dsh-home-paths` and `@deepseek-ai/dsh-atomic-write`. The host provides them at runtime, and a profile installs no peers, so no duplicate appears. `build-host.mjs` externalizes `dependencies` *and* `peerDependencies`, so `host.js` keeps the bare specifiers unchanged.
+- Those four are repeated in `devDependencies` — that is what lets this repository's own typecheck, build and tests resolve them. Every other `@deepseek-ai/*` is type-only (erased at build, no specifier left in `host.js`) and stays in `devDependencies` alone.
+- What is left in `dependencies` is genuinely this package's own runtime code: `@jayyuen66/dsh-plugin-shared` and `js-yaml` (the last one used only by `scripts/get-cred.mjs`).
 
 ## pnpm blocks the dependency script on install (ERR_PNPM_IGNORED_BUILDS)
 

package/README.zh-CN.md

@@ -19,7 +19,7 @@
 - 平台：目标平台是 macOS / Linux。进程收割（`ocr_review` / `ocr_scan` 的 reaper 守护）依赖 POSIX 工具链——bash 的 trap 与作业控制，加上 `ps` / `pgrep` / `kill` 的进程组语义。Windows 上这层整体缺席，本包按 `process.platform` 直接放行裸命令（不收割但能跑）；代价是宿主硬退出后 OCR 可能留下孤儿进程。
 - provider 清单与 key 状态走宿主官方通道 `ctx.settings.describe()`（`llm-pi-ai` 那条的 `value.providers`）与 `ctx.credentials`。
 - 两者缺席时卡片显示降级原因，工具与设置照常可用。
-- 宿主版本要求 `>=0.2.0-rc.2`：写在 `peerDependencies`（0.1.7-rc 起宿主装插件时校验它；alpha.1 还没有这道门）与 `engines.dsh`（同值、无人读）。
+- 宿主版本要求 `>= 0.2.1-alpha.1`：写在 `peerDependencies`（0.1.7-rc 起宿主装插件时校验它；alpha.1 还没有这道门）与 `engines.dsh`（同值、无人读）。
 
 ## 安装
 
@@ -56,7 +56,10 @@ allowBuilds:
 **关于这个 postinstall：** 它在正常路径下什么都不做。平台二进制由上游的 `optionalDependencies`（`@alibaba-group/ocr-<os>-<arch>`，各自带 `os` / `cpu` 字段，pnpm 只装匹配当前平台的那个）提供，`install.js` 检测到就打印 `Binary provided by platform package, skipping download.` 后直接返回。实测放行与不放行都能让 `ocr` 正常执行，差别只是要不要在安装期跑那段脚本——它只在平台包装不上时才下载兜底，而在 pnpm 下平台包必然装得上。
 
 如果你更希望完全不执行安装期脚本，可以写 `'@alibaba-group/open-code-review': false`：`ocr` 同样可用（launcher 直接从平台包目录取二进制），但宿主 `readPendingBuilds()` 只认值为 `set this to true or false` 的条目，改成 `false` 后官方审批流程就不再能代为授权，只能手工维护。
-- 运行期值依赖 `@jayyuen66/dsh-plugin-shared`、`@deepseek-ai/schemastery`（宿主 fork 的 schemastery，0.1.7 的 `.volatile()` 解析只在它有实现）与 `js-yaml`（后者只被 `scripts/get-cred.mjs` 用）。
+- `dependencies` 里不放任何 `@deepseek-ai/*`，这不是风格偏好。本包的消费方是 dsh 插件，被装进 profile（`nodeLinker: hoisted`、`autoInstallPeers: false`），只要宿主包出现在 `dependencies`，pnpm 就会把它在那颗 profile 里落成**真实目录**，与宿主进程已经加载的那份并存。而 `@deepseek-ai/dsh-tools` 的 `TOOL_RUNTIME_SCHEDULER` 是普通 `Symbol`（不是 `Symbol.for`），符号身份按模块实例计算——宿主 `dsh-agent-loop` 拿自己那份的 Symbol 去读由副本挂载出来的 `ToolRuntime`，得到 `undefined`，于是**每一次原生工具调用都抛** `Cannot read properties of undefined (reading 'prepare')`，整个 profile 的工具一起失效。本包的构建、类型检查与测试在这之前全部照绿，所以判据只能由 `test/publish-manifest.test.ts` 落在 manifest 面。
+- 产物里以**值**导入的四枚宿主包是非 optional 的 `peerDependencies`：`@deepseek-ai/schemastery`（宿主 fork 的 schemastery，0.1.7 的 `.volatile()` 解析只在它有实现）、`@deepseek-ai/dsh-credentials`、`@deepseek-ai/dsh-home-paths`、`@deepseek-ai/dsh-atomic-write`。运行期由宿主在场提供，而 profile 不装 peer，所以不产生副本；`build-host.mjs` 对 `dependencies` 与 `peerDependencies` 两张表一律外部化，`host.js` 里的裸说明符因此一字不变。
+- 这四枚同时另列一份进 `devDependencies`——那才是本包自己的 typecheck、build、test 解析得到它们的方式。其余 `@deepseek-ai/*` 全是 type-only（构建即擦除，`host.js` 里不留说明符），只留在 `devDependencies`。
+- `dependencies` 剩下的确实是本包自己的运行期代码：`@jayyuen66/dsh-plugin-shared` 与 `js-yaml`（后者只被 `scripts/get-cred.mjs` 用）。
 
 ## 在 dsh 里启用
 

package/client.js

@@ -126,14 +126,12 @@ const UI_MESSAGES = {
 	}
 };
 //#endregion
-//#region node_modules/.pnpm/@jayyuen66+dsh-plugin-shared@0.1.0_@deepseek-ai+cordis@4.0.4_eslint-plugin-sonarjs@4.2._a5b0027b68963132c312048d042510c0/node_modules/@jayyuen66/dsh-plugin-shared/dist/record.js
-/** 对象类型守卫：非 `null` 的 `object` 且非数组（`Record` 索引签名投影的基础）。 */
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+//#region node_modules/.pnpm/@jayyuen66+dsh-plugin-shared@0.1.3_@deepseek-ai+cordis@4.0.5-alpha.1_@deepseek-ai+dsh-c_6c028874c2202469b2088f67c885abe7/node_modules/@jayyuen66/dsh-plugin-shared/dist/record.js
+function e(e) {
+	return typeof e == `object` && !!e && !Array.isArray(e);
 }
-/** 从 `unknown` 投影单个字段；非 `Record` → `undefined`。 */
-function fieldOf(value, key) {
-	return isRecord(value) ? value[key] : void 0;
+function t(t, n) {
+	return e(t) ? t[n] : void 0;
 }
 //#endregion
 //#region src/client-entry.ts
@@ -176,43 +174,43 @@ function errorSummary(error) {
 }
 function modelOf(raw) {
 	return {
-		id: strOf(fieldOf(raw, "id")),
-		name: strOf(fieldOf(raw, "name"))
+		id: strOf(t(raw, "id")),
+		name: strOf(t(raw, "name"))
 	};
 }
 function providerOf(raw) {
-	const modelsArr = fieldOf(raw, "models");
+	const modelsArr = t(raw, "models");
 	const models = Array.isArray(modelsArr) ? modelsArr.map((item) => modelOf(item)) : [];
-	const apiKeyEnvRaw = fieldOf(raw, "apiKeyEnv");
+	const apiKeyEnvRaw = t(raw, "apiKeyEnv");
 	return {
-		name: strOf(fieldOf(raw, "name")),
-		displayName: strOf(fieldOf(raw, "displayName")),
+		name: strOf(t(raw, "name")),
+		displayName: strOf(t(raw, "displayName")),
 		apiKeyEnv: typeof apiKeyEnvRaw === "string" ? apiKeyEnvRaw : null,
-		baseURL: strOf(fieldOf(raw, "baseURL")),
+		baseURL: strOf(t(raw, "baseURL")),
 		models,
-		hasKey: fieldOf(raw, "hasKey") === true
+		hasKey: t(raw, "hasKey") === true
 	};
 }
 function providersPayloadOf(json) {
-	const providersArr = fieldOf(json, "providers");
+	const providersArr = t(json, "providers");
 	const providers = Array.isArray(providersArr) ? providersArr.map((item) => providerOf(item)) : [];
-	const currentRaw = fieldOf(json, "current");
+	const currentRaw = t(json, "current");
 	const current = {
-		provider: strOf(fieldOf(currentRaw, "provider")),
-		model: strOf(fieldOf(currentRaw, "model")),
-		keyIsDynamic: fieldOf(currentRaw, "keyIsDynamic") === true,
-		url: strOf(fieldOf(currentRaw, "url"))
+		provider: strOf(t(currentRaw, "provider")),
+		model: strOf(t(currentRaw, "model")),
+		keyIsDynamic: t(currentRaw, "keyIsDynamic") === true,
+		url: strOf(t(currentRaw, "url"))
 	};
-	const sourceRaw = fieldOf(json, "source");
+	const sourceRaw = t(json, "source");
 	return {
 		providers,
 		current,
-		getCredReady: fieldOf(json, "getCredReady") === true,
+		getCredReady: t(json, "getCredReady") === true,
 		source: {
-			status: strOf(fieldOf(sourceRaw, "status")),
-			message: strOf(fieldOf(sourceRaw, "message"))
+			status: strOf(t(sourceRaw, "status")),
+			message: strOf(t(sourceRaw, "message"))
 		},
-		csrf: strOf(fieldOf(json, "csrf"))
+		csrf: strOf(t(json, "csrf"))
 	};
 }
 /** 三行表单控件（数字/文本/下拉）共用的类名 = CARD_CSS 里 `.ocr-select{…}` 那条规则。
@@ -698,7 +696,7 @@ async function refreshProviders(sinks) {
 	try {
 		const res = await fetch(PROVIDERS_URL, { headers: { accept: "application/json" } });
 		if (!res.ok) {
-			const detail = strOf(fieldOf(await res.json().catch(() => ({})), "error"));
+			const detail = strOf(t(await res.json().catch(() => ({})), "error"));
 			throw new Error(detail === "" ? `HTTP ${res.status}` : detail);
 		}
 		const payload = providersPayloadOf(await res.json());
@@ -729,11 +727,11 @@ async function postWithCsrf(url, body, deps) {
 }
 /** POST select：把选中的 provider/model 写进 OCR 配置，回执里按 autoVerify 决定是否带 llm test。 */
 async function runApplySelection(deps) {
-	const { t, effectiveProvider, effectiveModel } = deps;
+	const { t: t$1, effectiveProvider, effectiveModel } = deps;
 	if (!effectiveProvider || !effectiveModel) {
 		deps.setActionMsg({
 			ok: false,
-			text: t("pickProviderModel")
+			text: t$1("pickProviderModel")
 		});
 		return;
 	}
@@ -744,14 +742,14 @@ async function runApplySelection(deps) {
 			provider: effectiveProvider,
 			model: effectiveModel
 		}))).json();
-		if (fieldOf(selJson, "ok") === true) {
+		if (t(selJson, "ok") === true) {
 			let testText;
-			const llmTestRaw = fieldOf(selJson, "llmTest");
-			if (isRecord(llmTestRaw)) {
-				const testOutput = strOf(fieldOf(llmTestRaw, "output")).slice(0, 400);
-				testText = fieldOf(llmTestRaw, "ok") === true ? t("llmTestPassed") : `${t("llmTestFailed")}${testOutput}`;
-			} else testText = t("notVerified");
-			const appliedText = t("applied", {
+			const llmTestRaw = t(selJson, "llmTest");
+			if (e(llmTestRaw)) {
+				const testOutput = strOf(t(llmTestRaw, "output")).slice(0, 400);
+				testText = t(llmTestRaw, "ok") === true ? t$1("llmTestPassed") : `${t$1("llmTestFailed")}${testOutput}`;
+			} else testText = t$1("notVerified");
+			const appliedText = t$1("applied", {
 				provider: effectiveProvider,
 				model: effectiveModel,
 				test: testText
@@ -762,14 +760,14 @@ async function runApplySelection(deps) {
 			});
 			deps.refresh();
 		} else {
-			const failure = strOf(fieldOf(selJson, "error"));
+			const failure = strOf(t(selJson, "error"));
 			deps.setActionMsg({
 				ok: false,
-				text: failure === "" ? t("applyFailed") : failure
+				text: failure === "" ? t$1("applyFailed") : failure
 			});
 		}
 	} catch (error) {
-		const failedText = `${t("requestFailed")}${errorSummary(error)}`;
+		const failedText = `${t$1("requestFailed")}${errorSummary(error)}`;
 		deps.setActionMsg({
 			ok: false,
 			text: failedText
@@ -780,24 +778,24 @@ async function runApplySelection(deps) {
 }
 /** POST migrate：明文 api_key 一键迁到 api_key_cmd，回执把迁移/跳过两个名单拼成一行。 */
 async function runMigrateKeys(deps) {
-	const { t } = deps;
+	const { t: t$2 } = deps;
 	deps.setBusy(true);
 	deps.setActionMsg(null);
 	try {
 		const json = await (await deps.post(MIGRATE_URL)).json();
-		const migratedVal = fieldOf(json, "migrated");
-		const skippedVal = fieldOf(json, "skippedUnknown");
+		const migratedVal = t(json, "migrated");
+		const skippedVal = t(json, "skippedUnknown");
 		const migrated = Array.isArray(migratedVal) ? migratedVal.filter((item) => typeof item === "string") : [];
 		const skipped = Array.isArray(skippedVal) ? skippedVal.filter((item) => typeof item === "string") : [];
-		const ok = fieldOf(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 ok = t(json, "ok") === true;
+		const head = ok ? (migrated.length > 0 ? t$2("migratedPrefix") + migrated.join(", ") : t$2("noPlainKey")) + (skipped.length > 0 ? t$2("skippedPrefix") + skipped.join(", ") : "") : t$2("migrateFailed");
 		deps.setActionMsg({
 			ok,
 			text: head
 		});
 		deps.refresh();
 	} catch (error) {
-		const failedText = `${t("requestFailed")}${errorSummary(error)}`;
+		const failedText = `${t$2("requestFailed")}${errorSummary(error)}`;
 		deps.setActionMsg({
 			ok: false,
 			text: failedText
@@ -808,19 +806,19 @@ async function runMigrateKeys(deps) {
 }
 /** POST test：手动触发 ocr llm test，输出原样回显在动作条上。 */
 async function runTestConnection(deps) {
-	const { t } = deps;
+	const { t: t$3 } = deps;
 	deps.setBusy(true);
 	deps.setActionMsg(null);
 	try {
 		const json = await (await deps.post(TEST_URL)).json();
-		const ok = fieldOf(json, "ok") === true;
-		const testOutput = strOf(fieldOf(json, "output"));
+		const ok = t(json, "ok") === true;
+		const testOutput = strOf(t(json, "output"));
 		deps.setActionMsg({
 			ok,
-			text: (ok ? t("llmTestPassed") : t("llmTestFailed")) + testOutput
+			text: (ok ? t$3("llmTestPassed") : t$3("llmTestFailed")) + testOutput
 		});
 	} catch (error) {
-		const failedText = `${t("requestFailed")}${errorSummary(error)}`;
+		const failedText = `${t$3("requestFailed")}${errorSummary(error)}`;
 		deps.setActionMsg({
 			ok: false,
 			text: failedText

package/cordis.patch.yml

@@ -1,4 +1,4 @@
-# ocr-review（2026-09-14）：open-code-review 工作区审查插件（bundle）。
+# ocr-review：open-code-review 工作区审查插件（bundle）。
 # 双面包机制：本包含 Host 半（host.ts：5 个工具 ocr_review/ocr_scan/
 # ocr_delegate_preview/ocr_delegate_rule/ocr_session + settings namespace「ocr-review」+
 # webServer 配置端点）与 Client 半（src/client-entry.ts → client.js：设置卡片，

package/host.js

@@ -84,6 +84,9 @@ const MESSAGES = {
 		noApiKeyEnv: "provider {provider} 未声明 apiKeyEnv，无法动态读取 key（OCR 自定义 provider 不支持无 key 解析）",
 		keyNotResolvable: "provider {provider} 的 API key 未配置：dsh 凭据服务未解析到 {ref}",
 		credScriptMissing: "get-cred 脚本缺失：{path}（api_key_cmd 无法工作）",
+		reaperDegraded: "[ocr-review] 宿主回收守护已降级：ps/pgrep 不可用（进程信息命令被沙箱拒绝），改由宿主管进程树。dsh 硬退出时 ocr 可能留孤儿进程。",
+		warningUnreadable: "（一条格式无法解析的 warning：既不是字符串，也没有 file/error 字段）",
+		commaInListItem: "{name} 的数组形式里有一项自身含逗号：{item}。数组与逗号字符串两条路径 join 后无法区分，而 glob 花括号（{ts,tsx}）恰好含逗号——静默拆成多项会改变审查/过滤范围。改用逗号字符串形式。",
 		providerModelRequired: "provider 与 model 必填",
 		bodyParseFailed: "body 解析失败：{message}",
 		reviewToolDescription: "用 open-code-review（ocr）对 Git 变更做深度学习代码审查：OCR 调用其自身配置的 LLM（provider/model 在 ocr-review 设置卡选择）独立审查，返回按严重度/类别聚合的评论摘要。scope=workspace 审工作区 staged+unstaged+untracked 变更（默认）；scope=commit 审单个提交；scope=branch 用从/到分支对比（merge-base）。常用先 ocr_delegate_preview 看范围。effort 控制深度（low=1 轮/medium=2/high=3，越深越贵）。background 提供需求/业务上下文能显著提升质量。首次审查前确保 ocr 已配置且 'ocr llm test' 通过。",
@@ -211,6 +214,9 @@ const MESSAGES = {
 		noApiKeyEnv: "provider {provider} declares no apiKeyEnv, so the key cannot be read dynamically (OCR custom providers do not support keyless resolution)",
 		keyNotResolvable: "the API key of provider {provider} is not configured: the dsh credentials service resolved no {ref}",
 		credScriptMissing: "get-cred script missing: {path} (api_key_cmd cannot work)",
+		reaperDegraded: "[ocr-review] host reaper degraded: ps/pgrep are unavailable (process-info commands denied by the sandbox), so the host manages the process tree. dsh may leave an orphaned ocr process.",
+		warningUnreadable: "(one unreadable warning entry: neither a string nor an object with file/error)",
+		commaInListItem: "an item of the array form of {name} contains a comma itself: {item}. The array form and the comma-joined string are indistinguishable after joining, and glob braces ({ts,tsx}) contain commas — silently splitting changes the review/filter scope. Use the comma-separated string form.",
 		providerModelRequired: "provider and model are both required",
 		bodyParseFailed: "failed to parse the body: {message}",
 		reviewToolDescription: "Deep code review of Git changes with open-code-review (ocr): OCR runs its own configured LLM (provider/model picked in the ocr-review settings card) as an independent reviewer and returns comments aggregated by severity/category. scope=workspace reviews staged+unstaged+untracked changes (default); scope=commit reviews one commit; scope=branch compares from/to branches (merge-base). Commonly start with ocr_delegate_preview to see the scope. effort controls depth (low=1 pass / medium=2 / high=3, deeper costs more). Passing requirements/business context via background markedly improves quality. Before the first review make sure ocr is configured and 'ocr llm test' passes.",
@@ -423,17 +429,34 @@ function redactKeyMaterial(text) {
 }
 //#endregion
 //#region lib/argv-guard.ts
-/** POSIX sh 单引号转义：' → '\''。把任意字符串安全放进单引号内，防注入。 */
+/**
+* POSIX sh 单引号转义：' → '\''。把任意字符串安全放进单引号内，防注入。
+*
+* NUL 一律拒绝：POSIX 命令串根本无法表示 NUL 字节，含 NUL 的值经 `bash -c '<inner>'`
+* 会被截断或报错，产出「看起来成功但 argv 被截断」的不确定行为。当前各调用点恰好都先
+* 做了 NUL 拒绝，但那是靠调用顺序维持的隐式不变量；这里把闸下沉到实现自身，让
+* 「转义后的串一定能被 shell 完整读回」由本函数保证，而不是指望每个新调用点记得先查一遍。
+*/
 function shq(value) {
+	if (value.includes("\0")) throw new Error("shq：值里含 NUL 字节，转义后的命令串无法被 shell 完整读回（漏了上游 NUL 检查）");
 	return `'${value.replaceAll("'", String.raw`'\''`)}'`;
 }
-/** 绝对路径校验（macOS/Linux）：非空、以 / 开头、无 NUL 字节。 */
+/**
+* 绝对路径校验（macOS/Linux）：非空、trim 后以 / 开头、无 NUL 字节。
+*
+* 先 trim 再判：调用点会先 trim 再传进来，而直接调用 `args.repo` 的路径若带首尾空白，
+* 会被「必须是绝对路径」这条误导性文案拦下——读起来像是路径写错了格式，实际只是多了
+* 几个空格。顺带也挡住全空白（trim 后为空 ⇒ 触发 repoRequired）。
+*/
 function assertAbsoluteRoot(root, messages) {
-	if (typeof root !== "string" || root.length === 0) throw new Error(messages.repoRequired);
-	if (root.includes("\0")) throw new Error(format(messages.noNulBytes, { name: "repo" }));
-	if (!root.startsWith("/")) throw new Error(format(messages.repoMustBeAbsolute, { root }));
-	return root;
+	const trimmed = typeof root === "string" ? root.trim() : "";
+	if (trimmed.length === 0) throw new Error(messages.repoRequired);
+	if (trimmed.includes("\0")) throw new Error(format(messages.noNulBytes, { name: "repo" }));
+	if (!trimmed.startsWith("/")) throw new Error(format(messages.repoMustBeAbsolute, { root: trimmed }));
+	return trimmed;
 }
+/** limit 非法（NaN / ≤0 / 非整数）时的保守兜底上限：宁可比调用方的意图更严。 */
+const DEFAULT_LIST_LIMIT = 200;
 const EFFORTS = [
 	"low",
 	"medium",
@@ -452,6 +475,10 @@ function listSourceItems(value, name, messages) {
 		const items = [];
 		for (const item of value) {
 			if (typeof item !== "string") throw new TypeError(format(messages.listItemsMustBeString, { name }));
+			if (item.includes(",")) throw new TypeError(format(messages.commaInListItem, {
+				name,
+				item
+			}));
 			items.push(item);
 		}
 		return items;
@@ -460,12 +487,13 @@ function listSourceItems(value, name, messages) {
 }
 /** 原始项 → 取值（commaList 的第二段：只判内容，NUL 抛错、trim、丢空串，满 limit 即止）。 */
 function takeTrimmedItems(items, name, limit, messages) {
+	const cap = Number.isSafeInteger(limit) && limit > 0 ? limit : DEFAULT_LIST_LIMIT;
 	const out = [];
 	for (const item of items) {
 		if (item.includes("\0")) throw new Error(format(messages.noNulBytes, { name }));
 		const trimmed = item.trim();
 		if (trimmed.length > 0) out.push(trimmed);
-		if (out.length >= limit) break;
+		if (out.length >= cap) break;
 	}
 	return out;
 }
@@ -625,18 +653,26 @@ function optionalFlags(args, messages) {
 *  - 组长场景（detached 复刻 runner）dsh 硬退出后 +2s：stub 走 trap 优雅收尾、
 *    孙进程随组消亡——只杀 $ocr 与其直接子级会漏孙进程（实测泄漏被收养）；
 *  - 非组长场景守护收 TERM：stub/stub 包装层/孙进程全部消亡。
+* 降级口径：宿主文件沙箱围栏会把进程信息类命令一并 EPERM 拒绝（实测 /bin/ps），于是
+* 一次性探测 ps 与 pgrep 两个可用性（HAVEPS / HAVEPG）。**任一不可用就不挂守护**：原样
+* 跑命令、把进程树交回宿主，并向 stderr 报一次（不是每 2 秒刷屏）。为什么是「整条不挂」
+* 而不是「挂个残缺版」——pgrep 只出现在后代快照 desc() 里，它不可用时 cs 恒空，reap
+* 于是只杀得掉中间 bash 壳，真 ocr 命令与其孙进程全部存活：那不是「少一条看护」，而是
+* 伪装成看护在位却放任进程持续烧 token。
 * 只包 review/scan（分钟级任务）；delegate/session/llm-test 秒级命令不包。
 */
-function wrapWithHostReaper(command) {
+function wrapWithHostReaper(command, messages) {
 	if (process.platform === "win32") return command;
 	return `bash -c ${shq([
-		`p0=$(ps -o ppid= -p $$ | tr -d ' ')`,
+		`p0=$(ps -o ppid= -p $$ 2>/dev/null | tr -d ' '); [ -n "$p0" ] && HAVEPS=1 || HAVEPS=0`,
+		`pgrep -P 1 >/dev/null 2>&1 && HAVEPG=1 || HAVEPG=0`,
+		`[ "$HAVEPS" = 1 ] && [ "$HAVEPG" = 1 ] || { printf '%s\\n' ${shq(messages.reaperDegraded)} >&2; { ${command} ; }; exit $?; }`,
 		`{ ${command} ; } & ocr=$!`,
 		`desc() { for k in $(pgrep -P "$1" 2>/dev/null); do desc "$k"; printf '%s ' "$k"; done; }`,
-		`isl() { [ "$(ps -o pgid= -p $$ | tr -d ' ')" = "$$" ]; }`,
+		`isl() { [ "$HAVEPS" = 1 ] && [ "$(ps -o pgid= -p $$ 2>/dev/null | tr -d ' ')" = "$$" ]; }`,
 		`reap() { cs=$(desc "$ocr"); isl && kill -TERM -- -$$ 2>/dev/null; kill -TERM "$ocr" 2>/dev/null; for c in $cs; do kill -TERM "$c" 2>/dev/null; done; sleep 1; killmPid(){ kill -0 "$1" 2>/dev/null && kill -KILL "$1" 2>/dev/null; }; killmPid "$ocr"; for c in $cs; do killmPid "$c"; done; isl && kill -KILL -- -$$ 2>/dev/null; }`,
 		`trap 'reap; exit 143' TERM INT`,
-		`while kill -0 "$ocr" 2>/dev/null && [ "$(ps -o ppid= -p $$ | tr -d ' ')" = "$p0" ]; do sleep 2; done`,
+		`while kill -0 "$ocr" 2>/dev/null && { [ "$HAVEPS" = 0 ] || [ "$(ps -o ppid= -p $$ 2>/dev/null | tr -d ' ')" = "$p0" ]; }; do sleep 2; done`,
 		`kill -0 "$ocr" 2>/dev/null && reap`,
 		`wait "$ocr"; exit $?`
 	].join("; "))}`;
@@ -862,13 +898,24 @@ const SEVERITY_ORDER = [
 * 严重度归一：白名单外的值（含 OCR 自造等级、大小写异形）一律按 medium。
 * 聚合与排序共用这一个函数——此前两处各自实现（排序 indexOf 未命中得 -1 而把
 * UNKNOWN 排到 critical 之前，聚合却归 medium），同一份数据两种口径。
+*
+* trim 放在**本层**而不是留给 parse.ts：本模块声明自己是「唯一口径」，调用方不一定
+* 来自 parse.ts 的解码路径。少了它，" critical"（带首尾空白）会掉到 medium——一个
+* 高危等级被静默降级成中危，正是这层要防的事。
+*
+* known 一并回传：归一是「必须发生」的降级，但降级本身不该是**无痕**的——调用方要能
+* 统计出「有多少条走了兜底」，否则契约异常被彻底吞掉，聚合里看不出来、排序里也看不出来。
 */
 function normalizeSeverity(severity) {
-	return SEVERITY_ORDER.find((level) => level === severity) ?? "medium";
+	const matched = SEVERITY_ORDER.find((level) => level === severity.trim().toLowerCase());
+	return {
+		level: matched ?? "medium",
+		known: matched !== void 0
+	};
 }
 /** 排序位：critical→high→medium→low（未知已归 medium，永不为 -1）。 */
 function severityRank(severity) {
-	return SEVERITY_ORDER.indexOf(normalizeSeverity(severity));
+	return SEVERITY_ORDER.indexOf(normalizeSeverity(severity).level);
 }
 /** 聚合评论：按严重度/类别计数。severity 归类以 critical→high→medium→low 基准。 */
 function aggregateComments(comments) {
@@ -878,16 +925,20 @@ function aggregateComments(comments) {
 		medium: 0,
 		low: 0
 	};
-	const byCategory = {};
+	const categoryCounts = /* @__PURE__ */ new Map();
+	let unknownSeverityCount = 0;
 	for (const comment of comments) {
-		const sev = normalizeSeverity(comment.severity);
-		bySeverity[sev] += 1;
-		if (comment.category) byCategory[comment.category] = (byCategory[comment.category] ?? 0) + 1;
+		const { level, known } = normalizeSeverity(comment.severity);
+		bySeverity[level] += 1;
+		if (!known) unknownSeverityCount += 1;
+		if (comment.category) categoryCounts.set(comment.category, (categoryCounts.get(comment.category) ?? 0) + 1);
 	}
+	const byCategory = Object.fromEntries(categoryCounts);
 	return {
 		total: comments.length,
 		bySeverity,
-		byCategory
+		byCategory,
+		unknownSeverityCount
 	};
 }
 //#endregion
@@ -923,13 +974,24 @@ function str(value) {
 * start_line 输出成 "42"，一律当 0 会把真实评论判成「未锚定」而被摘要丢掉），
 * 空串/NaN/Infinity/其它类型回 0。
 */
+/**
+* 行号与增删统计的有效域：有限、非负、整数。
+*
+* 为什么把负数和小数一起挡掉：行号出现 "-3" 会被下游当成「未锚定的评论」而丢弃
+* （分类错了——它是畸形值不是缺锚点），而 insertions: -5 会原样传播进给模型看的
+* diff 统计。两者都是上游畸形值被当合法值透传。0 在下游有既定语义（未锚定 / 无统计），
+* 故作兜底值。
+*/
+function nonNegativeInt(value) {
+	if (!Number.isFinite(value) || value < 0) return 0;
+	return Math.trunc(value);
+}
 function num(value) {
-	if (typeof value === "number") return Number.isFinite(value) ? value : 0;
+	if (typeof value === "number") return nonNegativeInt(value);
 	if (typeof value === "string") {
 		const trimmed = value.trim();
 		if (trimmed === "") return 0;
-		const parsed = Number(trimmed);
-		return Number.isFinite(parsed) ? parsed : 0;
+		return nonNegativeInt(Number(trimmed));
 	}
 	return 0;
 }
@@ -995,11 +1057,18 @@ function parseReviewOutput(text, messages) {
 	const skipped = status === "skipped";
 	const sumRaw = root["summary"];
 	const sum = isRecord(sumRaw) ? sumRaw : void 0;
-	const warningsArr = Array.isArray(root["warnings"]) ? root["warnings"].map((warn) => {
+	const warningsRaw = root["warnings"];
+	let warningsArr;
+	if (warningsRaw === void 0) warningsArr = [];
+	else if (Array.isArray(warningsRaw)) warningsArr = warningsRaw.map((warn) => {
 		if (typeof warn === "string") return warn;
-		if (isRecord(warn)) return [str(warn["file"]), str(warn["error"])].filter(Boolean).join(messages.warningSeparator);
-		return "";
-	}).filter(Boolean) : [];
+		if (isRecord(warn)) {
+			const joined = [str(warn["file"]), str(warn["error"])].filter(Boolean).join(messages.warningSeparator);
+			if (joined !== "") return joined;
+		}
+		return messages.warningUnreadable;
+	}).filter(Boolean);
+	else warningsArr = [messages.warningUnreadable];
 	return {
 		ok: true,
 		status,
@@ -1095,6 +1164,10 @@ function parseDelegatePreview(text) {
 	if (!isRecord(doc)) return delegatePreviewFailure();
 	const root = doc;
 	if (!hitsContract(root, DELEGATE_PREVIEW_KEYS)) return delegatePreviewFailure();
+	for (const key of ["reviewable_files", "excluded_files"]) {
+		const value = root[key];
+		if (value !== void 0 && !Array.isArray(value)) return delegatePreviewFailure();
+	}
 	const reviewable = Array.isArray(root["reviewable_files"]) ? root["reviewable_files"].map((fileRaw) => {
 		if (!isRecord(fileRaw)) return null;
 		return {
@@ -1141,18 +1214,24 @@ function parseDelegateRules(text) {
 		ok: false,
 		groups: []
 	};
+	if (root["groups"] !== void 0 && !Array.isArray(root["groups"])) return {
+		ok: false,
+		groups: []
+	};
+	const groupsRaw = Array.isArray(root["groups"]) ? root["groups"] : [];
+	if (groupsRaw.some((groupRaw) => isRecord(groupRaw) && groupRaw["files"] !== void 0 && !Array.isArray(groupRaw["files"]))) return {
+		ok: false,
+		groups: []
+	};
 	return {
 		ok: true,
-		groups: Array.isArray(root["groups"]) ? root["groups"].map((groupRaw) => {
-			if (!isRecord(groupRaw)) return null;
-			return {
-				groupId: num(groupRaw["group_id"]),
-				source: str(groupRaw["source"]),
-				pattern: str(groupRaw["pattern"]),
-				files: Array.isArray(groupRaw["files"]) ? groupRaw["files"].map(str).filter(Boolean) : [],
-				rule: str(groupRaw["rule"])
-			};
-		}).filter((group) => group !== null && group.files.length > 0) : []
+		groups: groupsRaw.filter((groupRaw) => isRecord(groupRaw) && Array.isArray(groupRaw["files"])).map((groupRaw) => ({
+			groupId: num(groupRaw["group_id"]),
+			source: str(groupRaw["source"]),
+			pattern: str(groupRaw["pattern"]),
+			files: groupRaw.files.map((file) => str(file)).filter(Boolean),
+			rule: str(groupRaw["rule"])
+		})).filter((group) => group.files.length > 0)
 	};
 }
 //#endregion
@@ -1174,20 +1253,39 @@ const PROVIDERS_FIELD = "providers";
 * 端点按 OpenAI 线协议打出去——select 成功、OCR 调不通。表外值透传，让
 * renderSelectedConfig 的白名单给出可读错误。
 */
-const OCR_PROTOCOL_BY_API = {
-	"openai-completions": "openai",
-	"openai-responses": "openai-responses",
-	"anthropic-messages": "anthropic"
-};
+const OCR_PROTOCOL_BY_API = /* @__PURE__ */ new Map([
+	["openai-completions", "openai"],
+	["openai-responses", "openai-responses"],
+	["anthropic-messages", "anthropic"]
+]);
+/** 对象/数组形态的 `api` 的透传标记：可读，但绝不会被误认成任何合法协议名。 */
+const API_UNREADABLE = "[unreadable]";
+/**
+* settings 里的 `api` 字段 → 协议查表用的键。
+*
+* 三种形态必须分开，否则畸形声明会被静默降级成「能用的」配置：
+*   - 未声明（undefined / null）⇒ ""，交给 llm-pi-ai 的 openai-completions 兜底语义；
+*   - 字符串 ⇒ trim 后原样（表外值原样透传，由写侧白名单拒绝）；
+*   - 数字 / 布尔 ⇒ String()，同样落进「表外值」这条正路；
+*   - 对象 / 数组 ⇒ 固定标记。用 String(raw) 会走 Object.prototype.toString 得到
+*     "[object Object]"，那既无信息量又看着像协议名；显式标记更能说明「这里读不出来」。
+*/
+function apiKeyOf(raw) {
+	if (raw === void 0 || raw === null) return "";
+	if (typeof raw === "string") return raw.trim();
+	if (typeof raw === "number" || typeof raw === "boolean") return String(raw);
+	return API_UNREADABLE;
+}
 /** 原始 model 对象 → DshModel（缺 id 视为无效，返回 null）。 */
 function modelFromRaw(modelRaw) {
 	if (!isRecord(modelRaw)) return null;
 	const rec = modelRaw;
-	const id = typeof rec["id"] === "string" ? rec["id"] : "";
+	const id = typeof rec["id"] === "string" ? rec["id"].trim() : "";
 	if (!id) return null;
+	const name = typeof rec["name"] === "string" ? rec["name"].trim() : "";
 	return {
 		id,
-		name: typeof rec["name"] === "string" && rec["name"] ? rec["name"] : id
+		name: name === "" ? id : name
 	};
 }
 /** 原始 provider 对象 → DshProvider（缺 baseURL 视为无效，返回 null）。 */
@@ -1195,9 +1293,9 @@ function providerFromRaw(name, raw) {
 	if (!isRecord(raw)) return null;
 	const entry = raw;
 	const apiKeyEnv = typeof entry["apiKeyEnv"] === "string" && entry["apiKeyEnv"].trim() ? entry["apiKeyEnv"].trim() : null;
-	const api = typeof entry["api"] === "string" ? entry["api"] : "";
-	const protocol = api === "" ? "openai" : OCR_PROTOCOL_BY_API[api] ?? api;
-	const baseURL = typeof entry["baseURL"] === "string" ? entry["baseURL"] : "";
+	const api = apiKeyOf(entry["api"]);
+	const protocol = api === "" ? "openai" : OCR_PROTOCOL_BY_API.get(api) ?? api;
+	const baseURL = typeof entry["baseURL"] === "string" ? entry["baseURL"].trim() : "";
 	if (!baseURL) return null;
 	const models = Array.isArray(entry["models"]) ? entry["models"].map(modelFromRaw).filter((model) => model !== null) : [];
 	return {
@@ -1230,16 +1328,29 @@ function providersFromSettingsValue(value) {
 //#region lib/provider-source.ts
 /** provider 清单所在的官方 settings 命名空间（base bundle 的 pi-ai 适配器注册）。 */
 const PI_AI_NAMESPACE = "llm-pi-ai";
-const SOURCE_READY = {
+const SOURCE_READY = Object.freeze({
 	status: "ready",
 	message: ""
-};
+});
+/** settings 通道侧抛错（health / descriptors / 投影三处共用同一状态与同一份文案）。 */
+const SOURCE_SETTINGS_FAILED = "settings-failed";
 /**
 * 读 provider 清单并把一切失败折进 source（不抛）：会话热路径与 webServer 端点
 * 都只消费返回值，服务缺席/抛错时卡片仍能显示原因。
 */
 function readProviders(gateway, messages) {
-	const health = gateway.health();
+	let health;
+	try {
+		health = gateway.health();
+	} catch (error) {
+		return {
+			providers: [],
+			source: {
+				status: SOURCE_SETTINGS_FAILED,
+				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
+			}
+		};
+	}
 	if (!health.settings) return {
 		providers: [],
 		source: {
@@ -1254,7 +1365,7 @@ function readProviders(gateway, messages) {
 		return {
 			providers: [],
 			source: {
-				status: "settings-failed",
+				status: SOURCE_SETTINGS_FAILED,
 				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
 			}
 		};
@@ -1267,7 +1378,25 @@ function readProviders(gateway, messages) {
 			message: format(messages.sourceNamespaceUnavailable, { ns: PI_AI_NAMESPACE })
 		}
 	};
-	const providers = providersFromSettingsValue(hit.value);
+	if (!isRecord(fieldOf(hit.value, "providers"))) return {
+		providers: [],
+		source: {
+			status: "namespace-unavailable",
+			message: format(messages.sourceNamespaceUnavailable, { ns: PI_AI_NAMESPACE })
+		}
+	};
+	let providers;
+	try {
+		providers = providersFromSettingsValue(hit.value);
+	} catch (error) {
+		return {
+			providers: [],
+			source: {
+				status: SOURCE_SETTINGS_FAILED,
+				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
+			}
+		};
+	}
 	if (!health.credentials) return {
 		providers,
 		source: {
@@ -1283,7 +1412,12 @@ function readProviders(gateway, messages) {
 /** 逐 provider 问凭据服务「有没有 key」（并行；只回布尔）。 */
 async function markKeyFlags(gateway, providers) {
 	return await Promise.all(providers.map(async (providerCfg) => {
-		const hasKey = providerCfg.apiKeyEnv === null ? false : await gateway.credentialConfigured(providerCfg.apiKeyEnv);
+		const ref = providerCfg.apiKeyEnv;
+		if (ref === null || ref === "") return {
+			...providerCfg,
+			hasKey: false
+		};
+		const hasKey = await gateway.credentialConfigured(ref).catch(() => false);
 		return {
 			...providerCfg,
 			hasKey
@@ -1351,6 +1485,78 @@ function buildApiKeyCmd(scriptPath, envKey, dshHome, messages) {
 	if (dshHome !== void 0) parts.push(shqDyn(dshHome));
 	return parts.join(" ");
 }
+/**
+* 读一个 shq 单引号串：解出它的值与结束位置。
+*
+* 认的是 shqDyn 自己写出的转义形态——值里的单引号被写成四字符的 '\''。所以遇到
+* 单引号时，只有后面紧跟这四字符才算转义，否则是真闭合。未闭合（串被截断）返回
+* undefined：宁可判「读不懂」，也不要把半截命令当成可信输入。
+*/
+function readShqToken(text, start) {
+	let value = "";
+	let i = start + 1;
+	let closed = false;
+	while (i < text.length && !closed) {
+		const ch = text[i];
+		if (ch === "'" && text.startsWith(String.raw`'\''`, i)) {
+			value += "'";
+			i += 4;
+		} else if (ch === "'") {
+			closed = true;
+			i += 1;
+		} else {
+			value += ch;
+			i += 1;
+		}
+	}
+	return closed ? {
+		value,
+		next: i
+	} : null;
+}
+/** shq 串 → token 列表；形态不符（未闭合 / 出现裸词）返回 null。 */
+function readShqTokens(body) {
+	const tokens = [];
+	let i = 0;
+	let malformed = false;
+	while (i < body.length && !malformed) {
+		while (i < body.length && (body[i] === " " || body[i] === "	")) i += 1;
+		if (i >= body.length) break;
+		if (body[i] === "'") {
+			const token = readShqToken(body, i);
+			if (token === null) malformed = true;
+			else {
+				tokens.push(token.value);
+				i = token.next;
+			}
+		} else malformed = true;
+	}
+	return malformed ? null : tokens;
+}
+/**
+* api_key_cmd → 三个槽位；只认本包写出的那一种形态。
+*
+* 为什么需要反解：写进 config.json 的脚本路径是**写那一刻**的插件安装目录（绝对
+* 路径），而插件会被重装、换 profile、换发布形态——目录一变，ocr 执行 api_key_cmd
+* 就是 MODULE_NOT_FOUND，而它把这件事报成「resolve LLM endpoint 失败」，错误完全
+* 指不到「本包被挪了地方」这个真因。没有反解就无从判断一条 api_key_cmd 是否还活着。
+*
+* 为什么只认一种形态：认不出来的一律给 undefined，由调用方原样保留。改写一条读不
+* 懂的命令串，可能把用户手写的凭据取用方式弄坏，而那正是本包明令不该插手的部分。
+*/
+function parseApiKeyCmd(command) {
+	const body = command.replace(/^node[ \t]+/u, "");
+	const tokens = body === command ? null : readShqTokens(body);
+	if (tokens === null) return null;
+	const script = tokens[0] ?? "";
+	const envKey = tokens[1] ?? "";
+	if (script === "" || tokens.length < 2 || tokens.length > 3 || !/^[A-Z0-9_]+$/u.test(envKey)) return null;
+	return {
+		script,
+		envKey,
+		dshHome: tokens[2]
+	};
+}
 /** 现有 config 文本 → 盘面对象。
 *
 * 解析失败必须抛错而非给 `{}`：调用方（renderSelectedConfig /
@@ -1481,6 +1687,43 @@ function defaultCredScriptPath(pluginDir) {
 function credentialScriptPath(paths) {
 	return paths.getCredScript === "" ? defaultCredScriptPath(paths.pluginDir) : paths.getCredScript;
 }
+/** config.json 的全文渲染（与 renderSelectedConfig 末尾同一形态：两空格缩进 + 结尾换行）。 */
+function renderConfigDoc(doc) {
+	return `${JSON.stringify(doc, null, 2)}\n`;
+}
+/**
+* 把 custom_providers 里「脚本已不在」的 api_key_cmd 重指向当前安装目录。
+*
+* 为什么必须有这一步：api_key_cmd 里烤的是**写那一刻**的插件安装绝对路径。插件会被
+* 重装、换 profile（desktop / browser / 任意自定义名）、换发布形态，目录一变就悬空
+* ——而 ocr 侧的报错是「resolve LLM endpoint: api_key_cmd ... MODULE_NOT_FOUND」，完全
+* 指不到真因。没有自愈，用户只能手改一个自己都不知道错在哪的配置文件。
+*
+* 三条不越界的判据（宁可漏修也不猜）：
+*   1. 当前脚本自己都不在（包没装全）⇒ 一律不动，把「get-cred 脚本缺失」留给 apply 侧报；
+*   2. 旧脚本**还活着** ⇒ 不动。显式指定优先于 pluginDir 兜底，用户有意指到别处
+*      （自制脚本、共享副本）时不该被本包拽回来；
+*   3. 命令串读不懂（不是本包写出的形态）⇒ 不动。那多半是用户手写的，改写它就是在
+*      插手本包明令不碰的部分。
+*
+* dshHome 同样可能被搬：原值已不存在时换成宿主此刻解析出的那个。
+*/
+function repointDanglingKeyScripts(doc, current, messages) {
+	if (!existsSync(current.script)) return { repointed: [] };
+	const custom = fieldOf(doc, "custom_providers");
+	if (!isRecord(custom)) return { repointed: [] };
+	return { repointed: Object.entries(custom).flatMap(([name, entry]) => {
+		if (!isRecord(entry)) return [];
+		const raw = fieldOf(entry, "api_key_cmd");
+		if (typeof raw !== "string" || raw === "") return [];
+		const parsed = parseApiKeyCmd(raw);
+		if (parsed === null || parsed.script === current.script) return [];
+		if (existsSync(parsed.script)) return [];
+		const dshHome = parsed.dshHome !== void 0 && !existsSync(parsed.dshHome) ? current.dshHome : parsed.dshHome;
+		entry["api_key_cmd"] = buildApiKeyCmd(current.script, parsed.envKey, dshHome, messages);
+		return [name];
+	}) };
+}
 //#endregion
 //#region lib/ocr-config.ts
 /** 外部 ocr CLI 的默认配置目录/文件名（宿主服务管不到，只能由本包直读直写）。 */
@@ -1655,6 +1898,51 @@ async function migratePlaintextKeys(gateway, paths, messages) {
 		};
 	});
 }
+/**
+* 调用 ocr 之前的一次性指针自愈：把 config.json 里指向已不存在目录的 api_key_cmd
+* 拉回当前安装目录（判据见 lib/config-store.ts 的 repointDanglingKeyScripts）。
+*
+* 为什么放在调用前而不是启动时：插件可能在会话进行到一半被重装或换 profile，启动时
+* 修好的一次覆盖不了「上次跑完到这次开跑」之间发生的迁移。
+*
+* 为什么永不抛错：这是锦上添花的修复，不能因为它把工具拖死。坏 JSON、锁抢不到、权限
+* 不足、设置项写坏——一律放过，让 ocr 报它自己的原始错误，那才是诊断价值最高的形态。
+*
+* 常态零锁开销：先无锁读一次做判据，确实要改写才进 withFileLock（锁内按新快照重判，
+* 避免把并发写入的 provider 选择覆盖掉）。
+*/
+async function ensureKeyScriptPointer(paths, messages) {
+	const scriptPath = credentialScriptPath(paths);
+	if (!existsSync(scriptPath)) return {
+		repointed: [],
+		checked: false
+	};
+	const current = {
+		script: scriptPath,
+		dshHome: resolveDshHome()
+	};
+	if (readText(paths.ocrConfigJson).trim() === "") return {
+		repointed: [],
+		checked: true
+	};
+	try {
+		return {
+			repointed: await updateConfigLocked(paths.ocrConfigJson, async () => {
+				const doc = parseExistingConfig(readText(paths.ocrConfigJson), paths.ocrConfigJson, messages);
+				const result = repointDanglingKeyScripts(doc, current, messages);
+				if (result.repointed.length === 0) return result.repointed;
+				await writeConfigAtomic(paths.ocrConfigJson, renderConfigDoc(doc));
+				return result.repointed;
+			}),
+			checked: true
+		};
+	} catch {
+		return {
+			repointed: [],
+			checked: false
+		};
+	}
+}
 //#endregion
 //#region host.ts
 const PLUGIN_DIR = import.meta.dirname;
@@ -1921,10 +2209,12 @@ const REVIEW_OUTPUT_SCHEMA = { oneOf: [
 				required: [
 					"total",
 					"bySeverity",
-					"byCategory"
+					"byCategory",
+					"unknownSeverityCount"
 				],
 				properties: {
 					total: { type: "integer" },
+					unknownSeverityCount: { type: "integer" },
 					bySeverity: {
 						type: "object",
 						additionalProperties: false,
@@ -2080,6 +2370,36 @@ const SESSION_OUTPUT_SCHEMA = {
 		hint: { type: "string" }
 	}
 };
+/**
+* ocr 子进程一律按 `danger-full-access` 请求（官方按调用携带的 `SandboxExecutionPolicy`）。
+*
+* 为什么必须显式要：ocr CLI 的状态目录是 `$HOME/.opencodereview`（Go 侧 `os.UserHomeDir()`，
+* 无 `--config` 可改），落在 workspace 之外，而宿主沙箱的 `workspace-write` 只放行
+* workspaceRoot 与后端临时区——于是每次会话写入被 EPERM 拒绝。后果不是"少个功能"而是
+* **跑完的评审被丢掉**：同步调用在最后一步 `finalize session` 失败、对外整体报错；
+* 后台调用则落不了盘，作业列表、`--resume` 与进度可观测性同时失效。
+*
+* 为什么不给 `workspace-write` + 重定向 HOME 兜着：那样得把 `config.json` 搬进 workspace，
+* 密钥与状态管理跟着进仓，且换发布形态就要再搬一次——为绕开一条策略把用户目录写进用户仓。
+* owner 口径是「状态归 ocr 自己，围栏由本包显式放开」，故直接要 `danger-full-access`。
+*
+* **「能不能只放开需要写的那一条路径」：不能。** 官方按调用携带的 `SandboxPolicyRequest`
+* 只有 `session` 与 `mode` 两个字段（dsh-sandbox-policy 0.2.1-alpha.1 的
+* lib/types/index.d.ts:50），**没有**附加可写路径、没有自定义 HOME、没有目录级豁免。
+* 可选的收紧路径只有「改 ocr 自己的状态落点」或「等上游加字段」，两者都不是本包能在
+* 一次补丁里做完的事。故此处维持放开，但把边界写明：放开的是 ocr 这一个子进程的整棵
+* 文件系统写权限，不是宿主其它能力；且 ocr 读什么、写什么仍由上面那条 argv 闸与
+* 凭据链约束。
+*
+* `workspaceRoot` 在这个模式下不被消费，但官方要求「即使不消费也照样携带」（让调用方
+* 先解析一次策略、再选执行路径），故传 workdir 而不是编一个占位根。
+*/
+function ocrSandboxPolicy(workspaceRoot) {
+	return {
+		mode: "danger-full-access",
+		workspaceRoot
+	};
+}
 /** 失败详情：stderr 优先、空则退 stdout；先脱敏再截断（明文 key 绝不进工具错误
 *  ——错误文本会被持久化进会话日志）。省略标记是文案，故脱敏与截断的位置不变，
 *  只把中间的连接标记换成当前语言的那一份。两半各用一个函数，因为它们是两种缺陷：
@@ -2100,7 +2420,8 @@ async function runForeground(host, command, workdir, run, signal) {
 		workdir,
 		timeoutMs: run.timeoutMs,
 		stdoutMaxBytes: run.stdoutMaxBytes,
-		signal
+		signal,
+		sandboxPolicy: ocrSandboxPolicy(workdir)
 	});
 	const result = await (await host.shell.execute(spec)).result();
 	if (result.exitCode !== 0 || result.timedOut || result.aborted) {
@@ -2224,7 +2545,8 @@ async function startBackground(host, job, signal) {
 		workdir: job.workdir,
 		onExpiry: "none",
 		stdoutMaxBytes: job.stdoutMaxBytes,
-		signal
+		signal,
+		sandboxPolicy: ocrSandboxPolicy(job.workdir)
 	});
 	const proc = await host.shell.execute(spec);
 	pruneOcrJobHistory(registry);
@@ -2278,7 +2600,8 @@ async function runCollect(host, command, workdir, run) {
 		command,
 		workdir,
 		timeoutMs: run.timeoutMs,
-		stdoutMaxBytes: run.stdoutMaxBytes
+		stdoutMaxBytes: run.stdoutMaxBytes,
+		sandboxPolicy: ocrSandboxPolicy(workdir)
 	});
 	const result = await (await host.shell.execute(spec)).result();
 	const joined = result.stdout.text === "" || result.stderr.text === "" ? result.stdout.text + result.stderr.text : `${result.stdout.text}\n${result.stderr.text}`;
@@ -2480,6 +2803,26 @@ function pluginPaths(config, messages) {
 function ocrHome(config) {
 	return ocrHomeOverride(readOcrConfigPath(config));
 }
+/**
+* 调用 ocr 之前的一次性 api_key_cmd 指针自愈（lib/ocr-config.ts 的
+* ensureKeyScriptPointer）。
+*
+* 为什么必须在这一层而不是启动时：config.json 里的脚本路径是**写那一刻**的插件安装
+* 目录，而插件会被重装、换 profile（desktop / browser / 任意自定义名）、换发布形态。
+* 目录一变那条命令就悬空，ocr 侧报的是「resolve LLM endpoint 失败」，与真因毫无
+* 关系——五个工具一次性全挂，而配置文件里没有任何线索指向「本包被挪了地方」。
+* 当前路径一律取自 PLUGIN_DIR（import.meta.dirname，host.ts:181），与 profile 命名
+* 无关，故 desktop / browser / 自定义名走的是同一条路径。
+*
+* 与 ocrHome 同一口径：**不抛错**。pluginPaths 在坏设置下会抛，而那正是「工具照常
+* 可用、错误由端点侧报给卡片」的分工，不能因为一次自愈把工具拖死。
+*/
+async function healKeyScriptPointer(host, config) {
+	const messages = localeMessages(host);
+	try {
+		await ensureKeyScriptPointer(pluginPaths(config, messages), messages);
+	} catch {}
+}
 /** 运行 ocr llm test 校验当前配置（select 后自动验证 / 手动测试共用）。
 *  命令词与五个工具同一解析源（buildLlmTestCommand：随包 launcher 装法下 PATH 上
 *  没有裸 `ocr`），HOME 随 ocrConfigPath 重定向。墙钟与输出上限都是 entry config
@@ -2817,6 +3160,7 @@ function registerReviewTool(host, config) {
 			const eff = effortOf(args["effort"], config, runMsgs);
 			const tmp = waitOf(args["wait"], runMsgs) ? mkdtempSync(path.join(tmpdir(), "ocr-review-")) : void 0;
 			const outPath = tmp === void 0 ? void 0 : path.join(tmp, "out.json");
+			await healKeyScriptPointer(host, config);
 			const homeOverride = ocrHome(config);
 			try {
 				const { command, workdir } = buildReviewCommand({
@@ -2824,7 +3168,7 @@ function registerReviewTool(host, config) {
 					repo,
 					effort: eff
 				}, outPath, runMsgs);
-				const guarded = wrapWithHostReaper(withHomeEnv(command, homeOverride));
+				const guarded = wrapWithHostReaper(withHomeEnv(command, homeOverride), runMsgs);
 				if (outPath === void 0) return await startBackground(host, {
 					command: guarded,
 					workdir,
@@ -2909,13 +3253,14 @@ function registerScanTool(host, config) {
 			const repo = ocrRepo(args, exec, runMsgs);
 			const tmp = waitOf(args["wait"], runMsgs) ? mkdtempSync(path.join(tmpdir(), "ocr-scan-")) : void 0;
 			const outPath = tmp === void 0 ? void 0 : path.join(tmp, "out.json");
+			await healKeyScriptPointer(host, config);
 			const homeOverride = ocrHome(config);
 			try {
 				const { command, workdir } = buildScanCommand({
 					...args,
 					repo
 				}, outPath, runMsgs);
-				const guarded = wrapWithHostReaper(withHomeEnv(command, homeOverride));
+				const guarded = wrapWithHostReaper(withHomeEnv(command, homeOverride), runMsgs);
 				if (outPath === void 0) return await startBackground(host, {
 					command: guarded,
 					workdir,
@@ -2992,6 +3337,7 @@ function registerDelegatePreviewTool(host, config) {
 		run: async (args, exec) => {
 			const runMsgs = localeMessages(host);
 			const repo = ocrRepo(args, exec, runMsgs);
+			await healKeyScriptPointer(host, config);
 			const homeOverride = ocrHome(config);
 			const { command, workdir } = buildDelegatePreviewCommand({
 				...args,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jayyuen66/dsh-ocr-review",
-  "version": "0.1.3",
+  "version": "0.1.4-rc",
   "description": "dsh 工作区代码审查插件：把 open-code-review（ocr CLI）封装为 5 个模型工具 + 设置卡片（从 settings.yaml 选 provider/model 应用到 OCR 配置）。",
   "license": "MIT",
   "author": "JayYuen",
@@ -28,39 +28,39 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-atomic-write": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-credentials": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-home-paths": "0.2.0-rc.2",
-    "@deepseek-ai/schemastery": "3.18.4",
-    "@jayyuen66/dsh-plugin-shared": "^0.1.0",
+    "@jayyuen66/dsh-plugin-shared": "^0.1.3",
     "js-yaml": "^5.4.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-api-remotes": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-store": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-layout": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-jobs": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-jobs-local": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-package-manifest": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-ptc-runtime": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-sandbox": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-scope": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-session-projection": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-settings": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-shell": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-subprocess": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-user-approval": "0.2.0-rc.2",
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-api-remotes": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-atomic-write": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-locale": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-store": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-ui-layout": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-credentials": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-home-paths": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-host-webserver": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-jobs": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-jobs-local": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-package-manifest": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-scope": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-settings": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-shell": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-subprocess": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-user-approval": "0.2.1-alpha.1",
+    "@deepseek-ai/schemastery": "3.18.5-alpha.1",
     "@types/node": "26.6.3",
     "@types/react": "19.3.0",
     "@vitest/coverage-v8": "5.0.2",
@@ -75,7 +75,11 @@
     "vitest": "5.0.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh": "^0.2.0-rc.2"
+    "@deepseek-ai/dsh": "^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-atomic-write": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-credentials": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-home-paths": "0.2.1-alpha.1",
+    "@deepseek-ai/schemastery": "3.18.5-alpha.1"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh": {
@@ -87,7 +91,7 @@
   },
   "icon": "icon.svg",
   "engines": {
-    "dsh": ">=0.2.0-rc.2"
+    "dsh": ">=0.2.1-alpha.1"
   },
   "dsh": {
     "manifestVersion": 1,

package/scripts/get-cred.mjs

@@ -97,6 +97,35 @@ function isNotFound(error) {
  * @param {string} refName
  * @returns {string | undefined}
  */
+/**
+ * YAML 解析错误的**脱敏**描述：只留 reason + 行列定位，不带出错位置前后若干行的原文。
+ *
+ * 为什么必须自己拼：js-yaml 的 YAMLException 有两处会把 mark.snippet（出错点邻域的
+ * **原文**）附在文本后面——构造函数里的 `this.message = formatError(this, false)`，以及
+ * `toString()` 在 compact 为假时的分支。而 .credentials.yaml 的 refs.<REF> 里放的就是
+ * 明文 key，于是一处缩进/引号笔误就会把邻近行的真实 key 写进 stderr（OCR 会记录
+ * api_key_cmd 的 stderr，也可能进宿主日志），直接违反「明文只在取用时出现一次」。
+ * 实测 `String(err)` 与 `err.message` 两条路都会带出 snippet，只有 toString(true)
+ * （紧凑格式）是干净的。
+ *
+ * @param {unknown} error
+ * @returns {string}
+ */
+function yamlErrorDetail(error) {
+  if (error instanceof Error) {
+    // js-yaml 的 YAMLException 覆盖了 toString(compact)：传 true 走紧凑分支。
+    // 别的 Error 会忽略这个参数，返回普通的 "Name: message"，同样不含 snippet。
+    const compact = error.toString(true);
+    if (typeof compact === "string" && compact !== "") {
+      return compact;
+    }
+    return error.message;
+  }
+  // 兜底也不能用 String(error)：error 是 unknown，非字符串时会被隐式走
+  // Object.prototype.toString，产出 "[object Object]" 这种毫无信息量的文本。
+  return error instanceof Error ? error.message : "";
+}
+
 function fromCredentialsDoc(credPath, refName) {
   let text;
   try {
@@ -113,7 +142,7 @@ function fromCredentialsDoc(credPath, refName) {
     try {
       doc = load(text);
     } catch (error) {
-      problems.push(`凭证文件不是合法 YAML：${credPath} ${String(error)}`);
+      problems.push(`凭证文件不是合法 YAML：${credPath} ${yamlErrorDetail(error)}`);
     }
   }
   const refs = isRecord(doc) ? doc.refs : undefined;