@jayyuen66/dsh-ocr-review 0.1.0 → 0.1.2

package/host.js

@@ -12,10 +12,10 @@ import { guardTrust } from "@jayyuen66/dsh-plugin-shared/lib/trust";
 import { LOCALE_SETTINGS_NAMESPACE, messagesFor, resolveLocalePreference } from "@jayyuen66/dsh-plugin-shared/lib/locale";
 import { truncateEnd, truncateStart } from "@jayyuen66/dsh-plugin-shared/lib/text";
 import { fieldOf, isRecord } from "@jayyuen66/dsh-plugin-shared/lib/record";
+import { expandHomePath, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { errorText } from "@jayyuen66/dsh-plugin-shared/lib/errors";
 import { mkdir } from "node:fs/promises";
 import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
-import { expandHomePath } from "@deepseek-ai/dsh-home-paths";
 //#region lib/messages.ts
 const MESSAGES = {
 	zh: {
@@ -51,8 +51,12 @@ const MESSAGES = {
 		branchNeedsFromAndTo: "scope=branch 需要同时提供 from 与 to",
 		commitNeedsValue: "scope=commit 需要 commit 参数",
 		unknownScope: "未知 scope：{scope}（workspace/commit/branch）",
+		resumeNeedsScope: "resume 需要 scope=commit 或 scope=branch（workspace 工作区评审不支持恢复，OCR 会直接拒绝）；请同时给出 commit 或 from/to",
+		waitMustBeBoolean: "wait 必须是布尔值（true/false），收到 {received}",
 		pathsRequired: "paths 必填：至少传一个待审查文件的仓库相对路径",
 		invalidAction: "action 非法：{action}（期望 {expected}）",
+		sessionLimitRange: "limit 需要为 1-100 的整数（缺省 10），收到 {received}",
+		listRejectsId: "action=list 不接受 id（查单个会话请用 action=show 或 action=comments）",
 		resultSchemaViolation: "ocr {tool}: 返回值不符合该工具的 output schema：{violations}",
 		resultSchemaUnsupported: "ocr {tool}: 返回形态守卫不支持 output schema 关键字 {keyword}（插件内 bug：lib/output.ts 的关键字子集没跟上 schema）",
 		ocrNotJson: "OCR 未返回合法 JSON 输出",
@@ -61,7 +65,7 @@ const MESSAGES = {
 		statusNone: "（无）",
 		ocrCommentsNotArray: "OCR 输出 comments 字段不是数组，无法确认评论完整性",
 		warningSeparator: "：",
-		reviewSummaryHint: "完整评论与逐文件失败详情请用 `ocr session show <session_id>` 查看；start_line=0 表示 OCR 未能锚定行号，可依据 suggestion/existing_code 在文件中定位。判读口径：droppedCount 与 invalidCommentCount 同时为 0 时本摘要才覆盖 OCR 的全部产出；否则请调大 maxComments（或置 0 = 不截断）后复核，切勿把「本摘要无 critical」当作「代码干净」。",
+		reviewSummaryHint: "完整评论与逐文件失败详情请用 `ocr session show <session_id>` 查看；start_line=0 表示 OCR 未能锚定行号，可依据 suggestion/existing_code 在文件中定位。status=partial 表示部分文件未完成审查（失败明细在 warnings），评论仍然有效。判读口径：droppedCount 与 invalidCommentCount 同时为 0 时本摘要才覆盖 OCR 的全部产出；否则请调大 maxComments（或置 0 = 不截断）后复核，切勿把「本摘要无 critical」当作「代码干净」。",
 		lineZeroNote: "(line 0: 定位失败，按 existing_code 手动定位)",
 		parseFailedWithReason: "{tool} 输出解析失败：{message}\n原始内容前 {limit} 码元（已脱敏）：\n{raw}",
 		parseFailedPlain: "{tool} 输出解析失败\n原始内容前 {limit} 码元（已脱敏）：\n{raw}",
@@ -69,12 +73,14 @@ const MESSAGES = {
 		sourceSettingsFailed: "调用 dsh 设置服务失败：{message}",
 		sourceNamespaceUnavailable: "dsh 配置里没有 {ns} 命名空间：未安装 pi-ai 适配器，或还没配置任何 provider",
 		sourceCredentialsUnavailable: "dsh 凭据服务（ctx.credentials）未装配：无法确认 provider 的 API key 是否已配置",
-		badEnvKey: "非法 env key：{key}",
+		badEnvKey: "非法 env key：{key}（get-cred 只接受 ^[A-Z0-9_]+$ 的大写 ref 名；请在 dsh 配置里把该 provider 的 apiKeyEnv 改成大写字母/数字/下划线）",
 		configNotJson: "{where} 不是合法 JSON，已中止写入以保护既有配置（请先修复或删掉该文件）：{cause}",
 		configNotObject: "{where} 顶层不是 JSON 对象，已中止写入以保护既有配置",
 		providerNotInList: "provider 不在 dsh 配置的 {ns}.providers 列表：{provider}",
 		modelNotInList: "model 不在 {provider} 的 models 列表中：{model}",
+		protocolUnsupported: "provider {provider} 的 api 协议 {protocol} 无法映射到 OCR 支持的 protocol（openai/openai-responses/anthropic）；请在 dsh 配置里改用 openai-completions/openai-responses/anthropic-messages，或升级本插件",
 		ocrConfigPathInvalid: "设置项 ocrConfigPath 必须是绝对路径或 ~ 开头的路径：{path}",
+		configPathLayoutInvalid: "设置项 ocrConfigPath 必须是 <X>/.opencodereview/config.json 布局：{path}。OCR 端没有配置文件级的路径覆盖（只按 <HOME>/.opencodereview/config.json 定位），本插件通过给 ocr 子进程注入 HOME=<X> 让它生效；任意形状的文件路径写下去 OCR 也不会读",
 		noApiKeyEnv: "provider {provider} 未声明 apiKeyEnv，无法动态读取 key（OCR 自定义 provider 不支持无 key 解析）",
 		keyNotResolvable: "provider {provider} 的 API key 未配置：dsh 凭据服务未解析到 {ref}",
 		credScriptMissing: "get-cred 脚本缺失：{path}（api_key_cmd 无法工作）",
@@ -113,7 +119,7 @@ const MESSAGES = {
 		unitFile: "文件",
 		tuningConcurrency: "并发{unit}数（OCR --concurrency；缺省不传=OCR 原生 8）",
 		tuningTimeout: "每{unit}任务超时分钟（OCR --timeout；0=不限时；缺省不传=OCR 原生 15）",
-		tuningMaxTools: "每{unit}工具调用轮数上限（OCR --max-tools；0=模板默认；缺省不传=模板默认）",
+		tuningMaxTools: "每{unit}工具调用轮数上限（OCR --max-tools；0=模板默认；1-49 会被 OCR 抬到 50，帮助文本 min 50；缺省不传=模板默认）",
 		tuningMaxTokens: "每{unit}提示词 token 上限（OCR --max-tokens；0=配置/模板默认；缺省不传=模板默认）",
 		tuningMaxTokensBudget: "本次运行 total token（input+output）预算闸门，超出即停止派发部分结果（OCR --max-tokens-budget；0=不限；缺省不传=不限）",
 		previewHint: "对每个 reviewable 文件：用 git diff <merge_base>..<to> -- <path>（branch）/git show <commit> -- <path>（commit）/ git diff HEAD -- <path> 或直接读文件（workspace 新文件）取 diff。",
@@ -136,7 +142,7 @@ const MESSAGES = {
   是当前模型的工具调用能力问题——建议在 ocr-review 卡片换一个支持原生工具调用的模型（sensenova、deepseek、glm、qwen 系），
   不要反复重试同一个模型。
 - LLM 调用本身有重试：OCR 内置重试（429/408/409 与 5xx 自动退避重试）；per-file 组失败被隔离并进 warnings，不整体重跑。
-  工具层超时（10 分钟）或部分文件失败后，可 ocr_session 查 session_id、用 ocr_review --resume 恢复中断的区间/commit 评审。
+  工具层超时（min(请求, shell.maxTimeoutMs)，缺省 10 分钟）或部分文件失败后，可 ocr_session 查 session_id、用 ocr_review --resume 恢复中断的区间/commit 评审。
 `.trim()
 	},
 	en: {
@@ -172,8 +178,12 @@ const MESSAGES = {
 		branchNeedsFromAndTo: "scope=branch requires both from and to",
 		commitNeedsValue: "scope=commit requires the commit parameter",
 		unknownScope: "unknown scope: {scope} (workspace/commit/branch)",
+		resumeNeedsScope: "resume requires scope=commit or scope=branch (workspace reviews cannot be resumed; OCR rejects it outright); pass commit or from/to as well",
+		waitMustBeBoolean: "wait must be a boolean (true/false), got {received}",
 		pathsRequired: "paths is required: pass at least one repo-relative path of a file to review",
 		invalidAction: "invalid action: {action} (expected {expected})",
+		sessionLimitRange: "limit must be an integer 1-100 (default 10), got {received}",
+		listRejectsId: "action=list does not take an id (use action=show or action=comments for a single session)",
 		resultSchemaViolation: "ocr {tool}: the tool result does not match its output schema: {violations}",
 		resultSchemaUnsupported: "ocr {tool}: the result guard does not support the output schema keyword {keyword} (plugin bug: the keyword subset in lib/output.ts lags the schema)",
 		ocrNotJson: "OCR returned no valid JSON output",
@@ -182,7 +192,7 @@ const MESSAGES = {
 		statusNone: "(none)",
 		ocrCommentsNotArray: "the comments field of the OCR output is not an array, comment completeness cannot be confirmed",
 		warningSeparator: ": ",
-		reviewSummaryHint: "Use `ocr session show <session_id>` for the full comments and per-file failure details; start_line=0 means OCR could not anchor a line — locate it via suggestion/existing_code. How to read this summary: only when droppedCount and invalidCommentCount are both 0 does it cover everything OCR produced; otherwise raise maxComments (or set 0 = no truncation) and re-check — never treat \"no critical in this summary\" as \"the code is clean\".",
+		reviewSummaryHint: "Use `ocr session show <session_id>` for the full comments and per-file failure details; start_line=0 means OCR could not anchor a line — locate it via suggestion/existing_code. status=partial means some files were not reviewed (failure details are in warnings); the comments still stand. How to read this summary: only when droppedCount and invalidCommentCount are both 0 does it cover everything OCR produced; otherwise raise maxComments (or set 0 = no truncation) and re-check — never treat \"no critical in this summary\" as \"the code is clean\".",
 		lineZeroNote: "(line 0: not anchored, locate it via existing_code)",
 		parseFailedWithReason: "{tool} output parsing failed: {message}\nfirst {limit} UTF-16 code units of the raw output (redacted):\n{raw}",
 		parseFailedPlain: "{tool} output parsing failed\nfirst {limit} UTF-16 code units of the raw output (redacted):\n{raw}",
@@ -190,12 +200,14 @@ const MESSAGES = {
 		sourceSettingsFailed: "calling the dsh settings service failed: {message}",
 		sourceNamespaceUnavailable: "the dsh configuration has no {ns} namespace: the pi-ai adapter is not installed, or no provider is configured yet",
 		sourceCredentialsUnavailable: "the dsh credentials service (ctx.credentials) is not wired up: cannot confirm whether a provider's API key is configured",
-		badEnvKey: "invalid env key: {key}",
+		badEnvKey: "invalid env key: {key} (get-cred only accepts uppercase ref names matching ^[A-Z0-9_]+$; change the provider's apiKeyEnv in the dsh configuration to uppercase letters/digits/underscores)",
 		configNotJson: "{where} is not valid JSON; the write was aborted to protect the existing configuration (fix or delete that file first): {cause}",
 		configNotObject: "the top level of {where} is not a JSON object; the write was aborted to protect the existing configuration",
 		providerNotInList: "provider is not in the {ns}.providers list configured by dsh: {provider}",
 		modelNotInList: "model is not in the models list of {provider}: {model}",
+		protocolUnsupported: "the api protocol {protocol} of provider {provider} cannot be mapped to an OCR-supported protocol (openai/openai-responses/anthropic); use openai-completions/openai-responses/anthropic-messages in the dsh configuration, or upgrade this plugin",
 		ocrConfigPathInvalid: "the ocrConfigPath setting must be absolute or start with ~: {path}",
+		configPathLayoutInvalid: "the ocrConfigPath setting must follow the <X>/.opencodereview/config.json layout: {path}. OCR has no file-level path override (it only looks at <HOME>/.opencodereview/config.json); this plugin makes it effective by injecting HOME=<X> into the ocr subprocess. A file path of any other shape would never be read by OCR",
 		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)",
@@ -234,7 +246,7 @@ const MESSAGES = {
 		unitFile: "file",
 		tuningConcurrency: "Concurrent {unit} count (OCR --concurrency; unset = OCR native 8)",
 		tuningTimeout: "Per-{unit} task timeout in minutes (OCR --timeout; 0 = unlimited; unset = OCR native 15)",
-		tuningMaxTools: "Per-{unit} tool-call round cap (OCR --max-tools; 0 = template default; unset = template default)",
+		tuningMaxTools: "Per-{unit} tool-call round cap (OCR --max-tools; 0 = template default; 1-49 is raised to 50 by OCR, help text says min 50; unset = template default)",
 		tuningMaxTokens: "Per-{unit} prompt token cap (OCR --max-tokens; 0 = config/template default; unset = template default)",
 		tuningMaxTokensBudget: "Total token (input+output) budget gate for this run; dispatch stops once exceeded (OCR --max-tokens-budget; 0 = unlimited; unset = unlimited)",
 		previewHint: "For each reviewable file, get its diff with git diff <merge_base>..<to> -- <path> (branch) / git show <commit> -- <path> (commit) / git diff HEAD -- <path>, or read the file directly (new workspace files).",
@@ -260,9 +272,9 @@ const MESSAGES = {
   model's tool-calling ability is the problem — switch to a model with native tool calls in the ocr-review card
   (sensenova, deepseek, glm, qwen families) instead of retrying the same one.
 - LLM calls retry themselves: OCR has built-in backoff retries (429/408/409 and 5xx); per-file group failures are
-  isolated and land in warnings instead of re-running everything. After a tool-layer timeout (10 minutes) or partial
-  file failures, use ocr_session to find the session_id and ocr_review --resume to continue an interrupted
-  range/commit review.
+  isolated and land in warnings instead of re-running everything. After a tool-layer timeout (min(request,
+  shell.maxTimeoutMs), 10 minutes by default) or partial file failures, use ocr_session to find the session_id and
+  ocr_review --resume to continue an interrupted range/commit review.
 `.trim()
 	}
 };
@@ -431,13 +443,6 @@ const EFFORTS = [
 function clampEffort(value, fallback) {
 	return EFFORTS.find((level) => level === value) ?? fallback;
 }
-/** 正整数钳制（concurrency/timeout/maxTokens 用，非正整数回 fallback）。 */
-function clampPositiveInt(value, fallback, min, max) {
-	if (value === void 0 || value === null) return fallback;
-	const parsed = typeof value === "number" ? value : Number(value);
-	if (!Number.isSafeInteger(parsed)) return fallback;
-	return Math.min(max, Math.max(min, parsed));
-}
 /** 入参 → 原始项序列（commaList 的第一段：只判「值从哪来」，不判内容）。
 *  数组分支保留逐元素 for-of 而不是 `value.map`：map 会跳过稀疏数组的空洞，
 *  空洞本是「非字符串元素」这一条该拦的形态，跳过就等于静默少一项过滤条件。 */
@@ -502,7 +507,8 @@ function resolveRoot(value, fallback, messages) {
 	if (typeof fallback === "string" && fallback.trim().length > 0) return assertAbsoluteRoot(fallback.trim(), messages);
 	throw new Error(messages.repoRequiredUnknownWorkspace);
 }
-/** 报错用的值形态（永不调用可能被劫持的 toJSON/toString）。 */
+/** 报错用的值形态（永不调用可能被劫持的 toJSON/toString）。host.ts 的入参闸
+*  （effort/wait）复用同一口径，故导出。 */
 function describeValue(value) {
 	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
 	return Array.isArray(value) ? "array" : typeof value;
@@ -582,7 +588,8 @@ function pushTextFlag(parts, flag, value, messages) {
 /** --exclude/--background/--provider/--model 等通用 flag。
 * 注意：ocr 的 --exclude 是 String 类型（实测 v1.12.0 多 flag 实例只认最后一个，
 * 逗号分隔才生效）——多值必须合并为一个 flag 逗号连接，绝不能展开多个。
-*/
+* resume 不在这里：它与 scope 是互斥语义（workspace 禁恢复），由
+* buildReviewCommand 在拿到 scopeFlags 结果后前置校验。 */
 function optionalFlags(args, messages) {
 	const parts = [];
 	const excludes = commaList(args.exclude, "exclude", 50, messages);
@@ -590,7 +597,6 @@ function optionalFlags(args, messages) {
 	pushTextFlag(parts, BACKGROUND_FLAG, args.background, messages);
 	pushTextFlag(parts, "--provider", args.provider, messages);
 	pushTextFlag(parts, "--model", args.model, messages);
-	pushTextFlag(parts, "--resume", args.resume, messages);
 	return parts;
 }
 /**
@@ -662,6 +668,34 @@ function ocrCommand(locate = locateLauncher, memo = memoBox) {
 	return memo.value;
 }
 /**
+* HOME 重定向：ocrConfigPath 设置项生效的唯一通道。OCR 的 Go 侧全部家目录定位
+* （config、sessions、shell-rc 回退）都走 `os.UserHomeDir()`——Unix 上就是 `$HOME`
+* 环境变量（go doc os.UserHomeDir 原文 "On Unix, including macOS, it returns the
+* $HOME environment variable"），而 config 文件本身没有任何 env/flag 可改
+* （config_cmd.go:92-99 的 defaultConfigPath 是唯一定位，全仓 Getenv 无 config 类
+* 覆盖）。设置项命中 `<X>/.opencodereview/config.json` 布局时，本包把 X 传进来，
+* 在命令串前加 POSIX 赋值前缀 `HOME=<X>`——OCR 及其全部子孙（含 api_key_cmd 起的
+* get-cred）就在重定向后的家目录里读 config、写 sessions，world 自洽。
+*
+* home 为 undefined（默认路径）时不加前缀，命令串一字不动。win32 没有 POSIX
+* 赋值前缀与 HOME 语义（且 resolveOcrConfigPath 对自定义值的布局校验两平台一致），
+* 与 wrapWithHostReaper 同款按平台放行。
+*/
+function withHomeEnv(command, home) {
+	if (home === void 0 || process.platform === "win32") return command;
+	return `HOME=${shq(home)} ${command}`;
+}
+/**
+* `ocr llm test` 命令词（select 的 autoVerify 与卡片「测试连接」共用）。
+* 必须与五个工具走同一个解析源（ocrCommand()）：随包 launcher 装法下 PATH 上没有
+* 裸 `ocr`，硬编码字符串会让 llm test 永远 exit 127 而评审照常工作——autoVerify
+* 从此没有一次能通过，还误导用户去装全局包。`--color` 是 root 持久 flag
+* （color.go:35-39），子命令合法。
+*/
+function buildLlmTestCommand() {
+	return `${ocrCommand()} llm test --color never`;
+}
+/**
 * 构造 `ocr review` 命令。--output 固定为调用方给定的临时文件路径（防截断），
 * --audience agent --format json 是默认（结构化、无进度行）。
 * outputPath 缺省（后台模式）省略 --output：结果以 OCR 会话记录为准。
@@ -684,7 +718,13 @@ function buildReviewCommand(args, outputPath, messages) {
 	pushIntFlag(parts, "--max-tools", args.maxTools, 0, messages);
 	pushIntFlag(parts, "--max-tokens", args.maxTokens, 0, messages);
 	pushIntFlag(parts, "--max-tokens-budget", args.maxTokensBudget, 0, messages);
-	parts.push(...scopeFlags(args, messages), ...optionalFlags(args, messages));
+	const scopeParts = scopeFlags(args, messages);
+	parts.push(...scopeParts, ...optionalFlags(args, messages));
+	const resume = idValue(args.resume, "resume", messages);
+	if (resume !== "") {
+		if (scopeParts.length === 0) throw new Error(messages.resumeNeedsScope);
+		parts.push("--resume", shq(resume));
+	}
 	if (outputPath !== void 0) parts.push("--output", shq(outputPath));
 	return {
 		command: parts.join(" "),
@@ -710,6 +750,8 @@ function buildScanCommand(args, outputPath, messages) {
 	const excludes = commaList(args.exclude, "exclude", 50, messages);
 	if (excludes.length > 0) parts.push("--exclude", shq(excludes.join(",")));
 	pushTextFlag(parts, "--batch", args.batch, messages);
+	pushTextFlag(parts, "--provider", args.provider, messages);
+	pushTextFlag(parts, "--model", args.model, messages);
 	pushIntFlag(parts, "--concurrency", args.concurrency, 1, messages);
 	pushIntFlag(parts, "--timeout", args.timeoutMinutes, 0, messages);
 	pushIntFlag(parts, "--max-tools", args.maxTools, 0, messages);
@@ -769,6 +811,18 @@ const SESSION_ACTIONS = [
 	"show",
 	"comments"
 ];
+/** session list --limit：缺省 10（OCR 原生默认 20，本包收紧；OCR 的 0=不限在本包
+* 上限 100 下无意义）。显式给出时必须是 1-100 的整数（与工具 description 的承诺
+* 一致），越界/错类型抛错而不是钳制——静默钳到 1 会把「想看更多」的 0 变成
+* 「只看一条」。数字字符串接受（"3"），与 pushIntFlag 的数值槽位同一口径。 */
+function sessionLimit(value, messages) {
+	if (value === void 0 || value === null) return 10;
+	let num = NaN;
+	if (typeof value === "number") num = value;
+	else if (typeof value === "string") num = Number(value);
+	if (!Number.isInteger(num) || num < 1 || num > 100) throw new Error(format(messages.sessionLimitRange, { received: describeValue(value) }));
+	return num;
+}
 /** 构造 `ocr session list/show/comments` 命令（历史评审会话闭环，Json 输出）。 */
 function buildSessionCommand(args, messages) {
 	const repo = assertAbsoluteRoot(args.repo, messages);
@@ -779,19 +833,18 @@ function buildSessionCommand(args, messages) {
 		action,
 		expected: SESSION_ACTIONS.join("/")
 	}));
+	if (requested === "list" && id !== "") throw new Error(messages.listRejectsId);
 	let sub;
 	if (requested === "comments" || requested === "show") sub = id === "" ? "list" : requested;
+	else if (requested === "list") sub = "list";
 	else sub = id === "" ? "list" : "show";
 	const parts = [
 		ocrCommand(),
 		"session",
 		sub
 	];
-	if (sub === "list") {
-		parts.push("--json", "--repo", shq(repo));
-		const limit = clampPositiveInt(args.limit, 10, 1, 100);
-		parts.push("--limit", String(limit));
-	} else parts.push("--json", "--repo", shq(repo), shq(id));
+	if (sub === "list") parts.push("--json", "--repo", shq(repo), "--limit", String(sessionLimit(args.limit, messages)));
+	else parts.push("--json", "--repo", shq(repo), shq(id));
 	return {
 		command: parts.join(" "),
 		workdir: repo
@@ -840,14 +893,21 @@ function aggregateComments(comments) {
 //#endregion
 //#region lib/parse.ts
 /**
-* OCR 评审 JSON 的 status 枚举（docs/cli-reference + 1.12.0 实测）。
+* OCR 评审 JSON 的 status 枚举（1.12.x 源码核对：cmd/opencodereview/output.go 的
+* jsonOutput 装配 + internal/session/manifest.go:166-169 的 TerminalState）。
 * 白名单外的一律视为失败：exit 0 不等于评审成功——`{"error":"auth failed"}`
 * 这类「没有 status 的错误对象」若被当作 ok:true，模型会把「0 条评论」读成
 * 「代码干净」，是最坏的一类假阳性。
+*
+* partial 是 manifest 终态之一（StatePartial）：部分文件失败但整体有覆盖、以及
+* --max-tokens-budget 截断后仍有覆盖，都以 exit 0 + status "partial" 输出
+* （review_cmd.go 的退出注释 "complete/partial/skipped all succeed"）。此前白名单
+* 漏了它，整场已花费 token 的评审被误报成「status 非法」并丢弃全部评论。
 */
 const REVIEW_STATUSES = [
 	"success",
 	"complete",
+	"partial",
 	"completed_with_warnings",
 	"completed_with_errors",
 	"skipped"
@@ -1103,6 +1163,22 @@ const ROUTING_ORDER = 1555;
 //#region lib/provider-projection.ts
 /** llm-pi-ai 命名空间里 provider 表的字段名。 */
 const PROVIDERS_FIELD = "providers";
+/**
+* llm-pi-ai 的 `api` 协议 → OCR config 的 `protocol` 映射。
+*
+* 两侧枚举的对照（dsh packages/llm/llm-pi-ai/src/provider.ts:44-48 的 PROTOCOLS
+* 对 OCR config_cmd.go:796 的 "Protocol values: anthropic, anthropic-bedrock,
+* openai, openai-responses"）：openai-completions 与 OCR 的 openai 是同一条
+* OpenAI Chat Completions 线协议；anthropic-messages 即 OCR 的 anthropic。
+* 此前「非 openai-responses 一律 openai」的二值映射会把 anthropic-messages 的
+* 端点按 OpenAI 线协议打出去——select 成功、OCR 调不通。表外值透传，让
+* renderSelectedConfig 的白名单给出可读错误。
+*/
+const OCR_PROTOCOL_BY_API = {
+	"openai-completions": "openai",
+	"openai-responses": "openai-responses",
+	"anthropic-messages": "anthropic"
+};
 /** 原始 model 对象 → DshModel（缺 id 视为无效，返回 null）。 */
 function modelFromRaw(modelRaw) {
 	if (!isRecord(modelRaw)) return null;
@@ -1119,7 +1195,8 @@ 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 protocol = entry["api"] === "openai-responses" ? "openai-responses" : "openai";
+	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"] : "";
 	if (!baseURL) return null;
 	const models = Array.isArray(entry["models"]) ? entry["models"].map(modelFromRaw).filter((model) => model !== null) : [];
@@ -1135,7 +1212,7 @@ function providerFromRaw(name, raw) {
 /**
 * settings 命名空间解析值 → provider 列表（纯投影，不含任何 key 值）。
 * 上游形状（settings 里 llm-pi-ai.providers.<name>）：
-*   { displayName?, apiKeyEnv?, api: openai-completions|openai-responses,
+*   { displayName?, apiKeyEnv?, api: openai-completions|openai-responses|anthropic-messages,
 *     baseURL, models?: [{id,name,…}] }
 * 形状不合的条目整条丢弃（读侧宽容：卡片要能打开让用户去修），写侧才 fail-loud。
 */
@@ -1257,10 +1334,22 @@ function readText(configPath) {
 function shqDyn(value) {
 	return `'${value.replaceAll("'", String.raw`'\''`)}'`;
 }
-/** api_key_cmd 值构造：把脚本路径与 env key 名 shq 转义后拼成 shell 命令。 */
-function buildApiKeyCmd(scriptPath, envKey, messages) {
+/** api_key_cmd 值构造：脚本路径与 env key 名（及可选的 dsh 数据目录）shq 转义后
+*  拼成 shell 命令。第三参数是 get-cred.mjs 数据目录定位的**第一档**（显式参数 >
+*  $DSH_HOME > homedir()/.dsh）：ocrConfigPath 重定向 ocr 子进程的 HOME 后，
+*  get-cred 的 homedir() 兜底会跟着跑偏，须在宿主侧把解析出的数据目录显式钉进
+*  命令。undefined（未重定向）时省略，沿用 env/默认档。
+*  env key 白名单维持 ^[A-Z0-9_]+$（刻意比宿主 CredentialRef 的语法紧：OCR 侧
+*  惯例大写，且这是写进 config.json 的可信输入）。 */
+function buildApiKeyCmd(scriptPath, envKey, dshHome, messages) {
 	if (!/^[A-Z0-9_]+$/u.test(envKey)) throw new Error(format(messages.badEnvKey, { key: envKey }));
-	return `node ${shqDyn(scriptPath)} ${shqDyn(envKey)}`;
+	const parts = [
+		"node",
+		shqDyn(scriptPath),
+		shqDyn(envKey)
+	];
+	if (dshHome !== void 0) parts.push(shqDyn(dshHome));
+	return parts.join(" ");
 }
 /** 现有 config 文本 → 盘面对象。
 *
@@ -1321,6 +1410,16 @@ async function writeConfigAtomic(targetPath, text) {
 		dirMode: 448
 	});
 }
+/** 本包允许写进 custom_providers.<name>.protocol 的白名单（OCR config_cmd.go:796
+*  "Protocol values: anthropic, anthropic-bedrock, openai, openai-responses"）。
+*  本包只会经 provider-projection 的映射表产出前三种；anthropic-bedrock 无对应的
+*  llm-pi-ai 协议、不由本包写出。表外值 = 投影透传的未知 `api`：拒绝写入，绝不落
+*  一份 OCR 解析不了的配置（此前二值映射会把 anthropic-messages 静默写成 openai）。 */
+const WRITABLE_PROTOCOLS = /* @__PURE__ */ new Set([
+	"openai",
+	"openai-responses",
+	"anthropic"
+]);
 /**
 * 生成「选择 provider+model」后的 config.json 全文。
 * - provider 顶层设为目标名；custom_providers.<name> 写 url/protocol/model/
@@ -1340,6 +1439,10 @@ function renderSelectedConfig(input, messages) {
 		provider: input.provider,
 		model: input.model
 	}));
+	if (!WRITABLE_PROTOCOLS.has(target.protocol)) throw new Error(format(messages.protocolUnsupported, {
+		provider: input.provider,
+		protocol: target.protocol
+	}));
 	const customsRaw = fieldOf(doc, "custom_providers");
 	const customs = isRecord(customsRaw) ? customsRaw : {};
 	const existingRaw = fieldOf(customs, input.provider);
@@ -1391,19 +1494,44 @@ function withoutKeyFlags(providers) {
 	}));
 }
 /**
+* 自定义路径必须呈 `<X>/.opencodereview/config.json` 布局时返回 X（= 重定向给
+* ocr 子进程的 HOME），否则 null。OCR 端定位 config 只有一条路
+* `<HOME>/.opencodereview/config.json`（config_cmd.go:92-99，无 env/flag），本包
+* 让自定义值生效的唯一通道是 HOME 注入（lib/cli.ts withHomeEnv）——任意形状的
+* 文件路径写下去 OCR 也读不到，只会静默失配，必须在设置层就拒绝。
+*/
+function layoutHomeOf(configPath) {
+	const parent = path.dirname(configPath);
+	if (path.basename(configPath) !== OCR_CONFIG_FILE || path.basename(parent) !== OCR_CONFIG_DIR) return null;
+	return path.dirname(parent);
+}
+/**
 * OCR 配置文件路径：设置项 ocrConfigPath 覆盖，未覆盖时按 os.homedir() 派生。
 * 家目录展开交官方 `expandHomePath`，但本地保留两条它没有的判据（见
 * `expandHomeForSeparator` 与下面的绝对性闸门）：直写相对路径会把配置落到
-* 「当时的工作区」，用户找不到也修不了。
+* 「当时的工作区」，用户找不到也修不了。自定义值还必须是
+* `<X>/.opencodereview/config.json` 布局（见 layoutHomeOf）。
 */
 function resolveOcrConfigPath(configured, messages) {
 	const trimmed = typeof configured === "string" ? configured.trim() : "";
 	if (trimmed === "") return path.join(homedir(), OCR_CONFIG_DIR, OCR_CONFIG_FILE);
 	const expanded = expandHomeForSeparator(trimmed, path.sep);
 	if (!path.isAbsolute(expanded)) throw new Error(format(messages.ocrConfigPathInvalid, { path: trimmed }));
+	if (layoutHomeOf(expanded) === null) throw new Error(format(messages.configPathLayoutInvalid, { path: trimmed }));
 	return expanded;
 }
 /**
+* ocr 子进程的 HOME 重定向值：设置项命中 `<X>/.opencodereview/config.json` 布局时
+* 返回 X，否则 undefined（默认路径零重定向）。**绝不抛错**——布局/绝对性不合法时
+* 返回 undefined，让工具执行不受坏设置拖累（错误由 resolveOcrConfigPath 在端点侧
+* 报出，卡片显示原因，「工具与设置照常可用」的既有口径不变）。
+*/
+function ocrHomeOverride(configured) {
+	const trimmed = typeof configured === "string" ? configured.trim() : "";
+	const expanded = trimmed === "" ? "" : expandHomeForSeparator(trimmed, path.sep);
+	return (path.isAbsolute(expanded) ? layoutHomeOf(expanded) : null) ?? void 0;
+}
+/**
 * 组装设置页数据（绝不返回 key 明文；credentials 缺席时 hasKey 全 false 并给出原因，
 * 让卡片显示「为什么不可用」而不是假装每个 provider 都没配 key）。
 */
@@ -1438,7 +1566,7 @@ async function applyProviderSelection(gateway, paths, selection, messages) {
 	}));
 	const scriptPath = credentialScriptPath(paths);
 	if (!existsSync(scriptPath)) throw new Error(format(messages.credScriptMissing, { path: scriptPath }));
-	const apiKeyCmd = buildApiKeyCmd(scriptPath, target.apiKeyEnv, messages);
+	const apiKeyCmd = buildApiKeyCmd(scriptPath, target.apiKeyEnv, resolveDshHome(), messages);
 	await updateConfigLocked(paths.ocrConfigJson, async () => {
 		const next = renderSelectedConfig({
 			existingText: readText(paths.ocrConfigJson),
@@ -1463,11 +1591,11 @@ async function applyProviderSelection(gateway, paths, selection, messages) {
 * api_key_cmd 并删除明文，返回 'migrated'；找不到 envKey 或构造命令失败 →
 * 'unknown'；无明文 → 'noPlain'（不动作）。
 */
-function migrateEntry(entry, envKey, scriptPath, messages) {
+function migrateEntry(entry, envKey, scriptPath, dshHome, messages) {
 	if (typeof entry["api_key"] !== "string" || entry["api_key"].length === 0) return "noPlain";
 	if (envKey === void 0 || envKey === "") return "unknown";
 	try {
-		entry["api_key_cmd"] = buildApiKeyCmd(scriptPath, envKey, messages);
+		entry["api_key_cmd"] = buildApiKeyCmd(scriptPath, envKey, dshHome, messages);
 	} catch {
 		return "unknown";
 	}
@@ -1498,6 +1626,7 @@ async function migratePlaintextKeys(gateway, paths, messages) {
 		migrated: [],
 		skippedUnknown: []
 	};
+	const dshHome = resolveDshHome();
 	const envByProvider = /* @__PURE__ */ new Map();
 	for (const providerCfg of providers) if (providerCfg.apiKeyEnv !== null && providerCfg.apiKeyEnv !== "") envByProvider.set(providerCfg.name, providerCfg.apiKeyEnv);
 	return await updateConfigLocked(paths.ocrConfigJson, async () => {
@@ -1511,7 +1640,7 @@ async function migratePlaintextKeys(gateway, paths, messages) {
 		const migrated = [];
 		const skippedUnknown = [];
 		for (const [name, raw] of Object.entries(customs)) if (isRecord(raw)) {
-			const result = migrateEntry(raw, envByProvider.get(name), scriptPath, messages);
+			const result = migrateEntry(raw, envByProvider.get(name), scriptPath, dshHome, messages);
 			if (result === "migrated") migrated.push(name);
 			else if (result === "unknown") skippedUnknown.push(name);
 		}
@@ -1755,6 +1884,7 @@ const REVIEW_OUTPUT_SCHEMA = { oneOf: [
 				enum: [
 					"success",
 					"complete",
+					"partial",
 					"completed_with_warnings",
 					"completed_with_errors",
 					"skipped"
@@ -1852,6 +1982,7 @@ const PREVIEW_OUTPUT_SCHEMA = { oneOf: [{
 	required: [
 		"mode",
 		"repository",
+		"mergeBase",
 		"reviewableCount",
 		"insertions",
 		"deletions",
@@ -1862,6 +1993,7 @@ const PREVIEW_OUTPUT_SCHEMA = { oneOf: [{
 	properties: {
 		mode: { type: "string" },
 		repository: { type: "string" },
+		mergeBase: NULLABLE_STRING,
 		reviewableCount: { type: "integer" },
 		insertions: { type: "number" },
 		deletions: { type: "number" },
@@ -2281,18 +2413,6 @@ function readOutFile(outPath, messages) {
 		}), { cause: error });
 	}
 }
-/** 运行 ocr llm test 校验当前配置（select 后自动验证 / 手动测试共用）。
-*  墙钟与输出上限都是 entry config 字段（非 volatile，改值随重启生效）。 */
-async function runLlmTest(host, config) {
-	const { exitCode, output } = await runCollect(host, "ocr llm test --color never", process.env["HOME"] ?? "/", {
-		timeoutMs: config.llmTestTimeoutMs,
-		stdoutMaxBytes: config.stdoutMaxBytes
-	});
-	return {
-		ok: exitCode === 0,
-		output
-	};
-}
 /**
 * OCR 原生数值参数的 tool schema 片段（忠实透传语义，桥接层不设钳制）。
 * unit 区分 review（每组）/ scan（每文件）的措辞（取消息表的 unitGroup/unitFile，
@@ -2340,12 +2460,54 @@ function readOcrConfigPath(config) {
 /** 本包剩下的文件路径：只剩外部 ocr CLI 的 config.json（可被设置项覆盖）+ 脚本位置。
 *  messages 只用于「设置项里的路径不合形态」那条可读错误。 */
 function pluginPaths(config, messages) {
+	const configured = readOcrConfigPath(config);
 	return {
-		ocrConfigJson: resolveOcrConfigPath(readOcrConfigPath(config), messages),
+		ocrConfigJson: resolveOcrConfigPath(configured, messages),
+		homeOverride: ocrHomeOverride(configured),
 		pluginDir: PLUGIN_DIR,
 		getCredScript: defaultCredScriptPath(PLUGIN_DIR)
 	};
 }
+/**
+* ocr 子进程的 HOME 重定向值（工具执行侧专用，**不抛错**）：设置项命中
+* `<X>/.opencodereview/config.json` 布局 → X；未设置/坏设置 → undefined。工具不
+* 走 pluginPaths（那会在坏设置下把五个工具一并拖死），坏设置的错误由端点侧的
+* resolveOcrConfigPath 报给卡片——「工具与设置照常可用」的口径不变。
+*/
+function ocrHome(config) {
+	return ocrHomeOverride(readOcrConfigPath(config));
+}
+/** 运行 ocr llm test 校验当前配置（select 后自动验证 / 手动测试共用）。
+*  命令词与五个工具同一解析源（buildLlmTestCommand：随包 launcher 装法下 PATH 上
+*  没有裸 `ocr`），HOME 随 ocrConfigPath 重定向。墙钟与输出上限都是 entry config
+*  字段（非 volatile，改值随重启生效）。 */
+async function runLlmTest(host, config) {
+	const { exitCode, output } = await runCollect(host, withHomeEnv(buildLlmTestCommand(), ocrHome(config)), process.env["HOME"] ?? "/", {
+		timeoutMs: config.llmTestTimeoutMs,
+		stdoutMaxBytes: config.stdoutMaxBytes
+	});
+	return {
+		ok: exitCode === 0,
+		output
+	};
+}
+/** effort 入参闸：undefined/null → 设置卡默认；字符串 → 白名单钳制（未知值回落
+*  medium，与 --format 同一纪律）；其余类型抛错——静默回落会改变审查深度。 */
+function effortOf(value, config, messages) {
+	if (value === void 0 || value === null) return readEffort(config);
+	if (typeof value !== "string") throw new TypeError(format(messages.mustBeString, {
+		name: "effort",
+		received: describeValue(value)
+	}));
+	return clampEffort(value, "medium");
+}
+/** wait 入参闸：undefined → true（前台缺省）；布尔透传；其余类型抛错——字符串
+*  "false" 若被 `!== false` 当真值处理会静默从后台变前台，吞掉用户的等待语义。 */
+function waitOf(value, messages) {
+	if (value === void 0 || value === null) return true;
+	if (typeof value !== "boolean") throw new TypeError(format(messages.waitMustBeBoolean, { received: describeValue(value) }));
+	return value;
+}
 /** 服务界面齐备才算可用（get() 可能返回半装配对象，也可能返回 undefined）。 */
 function usableService(value, methods) {
 	return value !== void 0 && hasMethods(value, methods) ? value : void 0;
@@ -2608,16 +2770,17 @@ function registerReviewTool(host, config) {
 		run: async (args, exec) => {
 			const runMsgs = localeMessages(host);
 			const repo = ocrRepo(args, exec, runMsgs);
-			const eff = args["effort"] === void 0 ? readEffort(config) : args["effort"];
-			const tmp = args["wait"] !== false ? mkdtempSync(path.join(tmpdir(), "ocr-review-")) : void 0;
+			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");
+			const homeOverride = ocrHome(config);
 			try {
 				const { command, workdir } = buildReviewCommand({
 					...args,
 					repo,
 					effort: eff
 				}, outPath, runMsgs);
-				const guarded = wrapWithHostReaper(command);
+				const guarded = wrapWithHostReaper(withHomeEnv(command, homeOverride));
 				if (outPath === void 0) return await startBackground(host, {
 					command: guarded,
 					workdir,
@@ -2681,6 +2844,14 @@ function registerScanTool(host, config) {
 					],
 					description: msgs.paramBatch
 				},
+				provider: {
+					type: "string",
+					description: msgs.paramProvider
+				},
+				model: {
+					type: "string",
+					description: msgs.paramModel
+				},
 				...tuningParams(msgs, msgs.unitFile),
 				wait: {
 					type: "boolean",
@@ -2692,14 +2863,15 @@ function registerScanTool(host, config) {
 		run: async (args, exec) => {
 			const runMsgs = localeMessages(host);
 			const repo = ocrRepo(args, exec, runMsgs);
-			const tmp = args["wait"] !== false ? mkdtempSync(path.join(tmpdir(), "ocr-scan-")) : void 0;
+			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");
+			const homeOverride = ocrHome(config);
 			try {
 				const { command, workdir } = buildScanCommand({
 					...args,
 					repo
 				}, outPath, runMsgs);
-				const guarded = wrapWithHostReaper(command);
+				const guarded = wrapWithHostReaper(withHomeEnv(command, homeOverride));
 				if (outPath === void 0) return await startBackground(host, {
 					command: guarded,
 					workdir,
@@ -2776,11 +2948,12 @@ function registerDelegatePreviewTool(host, config) {
 		run: async (args, exec) => {
 			const runMsgs = localeMessages(host);
 			const repo = ocrRepo(args, exec, runMsgs);
+			const homeOverride = ocrHome(config);
 			const { command, workdir } = buildDelegatePreviewCommand({
 				...args,
 				repo
 			}, runMsgs);
-			const text = await runForeground(host, command, workdir, tuningOf(config), exec.signal);
+			const text = await runForeground(host, withHomeEnv(command, homeOverride), workdir, tuningOf(config), exec.signal);
 			const parsed = parseDelegatePreview(text);
 			if (!parsed.ok) return format(runMsgs.parseFailedPlain, {
 				tool: "ocr delegate preview",
@@ -2790,6 +2963,7 @@ function registerDelegatePreviewTool(host, config) {
 			return {
 				mode: parsed.mode,
 				repository: parsed.repository,
+				mergeBase: parsed.mergeBase === "" ? null : parsed.mergeBase,
 				reviewableCount: parsed.reviewable.length,
 				insertions: parsed.reviewable.reduce((acc, file) => acc + file.insertions, 0),
 				deletions: parsed.reviewable.reduce((acc, file) => acc + file.deletions, 0),
@@ -2828,7 +3002,7 @@ function registerDelegateRuleTool(host, config) {
 				repo: ocrRepo(args, exec, runMsgs),
 				paths: args["paths"]
 			}, runMsgs);
-			const text = await runForeground(host, command, workdir, tuningOf(config), exec.signal);
+			const text = await runForeground(host, withHomeEnv(command, ocrHome(config)), workdir, tuningOf(config), exec.signal);
 			const parsed = parseDelegateRules(text);
 			if (!parsed.ok) return format(runMsgs.parseFailedPlain, {
 				tool: "ocr delegate rule",
@@ -2888,7 +3062,7 @@ function registerSessionTool(host, config) {
 				...args,
 				repo
 			}, runMsgs);
-			const text = await runForeground(host, command, workdir, tuningOf(config), exec.signal);
+			const text = await runForeground(host, withHomeEnv(command, ocrHome(config)), workdir, tuningOf(config), exec.signal);
 			const stripped = text.trim();
 			const empty = stripped === "null" || stripped === "[]";
 			const capped = text.length > 12e3 ? `${echoRaw(text, 11900)}\n${runMsgs.sessionTruncated}` : redactKeyMaterial(text);