@jayyuen66/dsh-ocr-review 0.1.0

package/host.js

@@ -0,0 +1,2936 @@
+// GENERATED by build-host.mjs — edit host.ts / lib/*.ts, then run `node build-host.mjs`.
+import { createRequire } from "node:module";
+import Schema from "@deepseek-ai/schemastery";
+import { chmodSync, copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { credentialRef, isCredentialRefName } from "@deepseek-ai/dsh-credentials";
+import { jobOutcomeOf } from "@jayyuen66/dsh-plugin-shared/lib/job-outcome";
+import { guardBody, sendJson } from "@jayyuen66/dsh-plugin-shared/lib/http";
+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 { 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: {
+		middleEllipsis: " …[中间省略]… ",
+		execTimedOut: "ocr 执行超时（实际生效 {minutes} 分钟 = min(请求, shell.maxTimeoutMs)）：请缩小审查范围（exclude/--commit/更小改动）、调低 OCR 每组 --timeout，调大 settings.yaml shell.maxTimeoutMs，或改用 wait=false 后台模式（无超时）",
+		execAborted: "ocr 执行被中止",
+		execNotFound: "ocr 命令不存在：请先 `brew install open-code-review` 或 `npm i -g @alibaba-group/open-code-review`",
+		execFailed: "ocr 执行失败（exit={exitCode}）",
+		detailSeparator: "：",
+		stdoutTruncated: "[ocr-review] 注意：输出超过 {limit} 字节上限已截断{spill}",
+		outputSpill: "（完整输出已落盘：{path}）",
+		backgroundPolling: "稍候用 ocr_session(action=list) 找本仓库最新会话（启动几秒后出现，按 scanPaths/时间匹配）；completed_files == selected_files 即已完成；再 ocr_session(action=comments, id) 取全部评论、ocr_session(action=show, id) 看元数据与逐文件检查点。后台运行不设宿主超时，只在 2 小时后兜底回收（挂死不动会一直占着官方作业桶），取消本工具调用即终止该后台 OCR（宿主 kill + 命令内回收守护）。",
+		jobReasonAborted: "ocr-review 工具调用被中止",
+		jobReasonTimeout: "ocr-review 后台评审超过 2 小时，兜底回收",
+		jobReasonUnload: "ocr-review 插件卸载",
+		jobOutputGap: "\n[ocr-review] 注意：有一次输出读取失败，已按原游标重试（这段可能不完整）",
+		requiredNotArray: "parameters.required 必须是字符串数组",
+		requiredItemNotString: "parameters.required 元素必须是字符串",
+		argsMustBeObject: "ocr {name}: 入参必须是 JSON 对象（收到 {received}）",
+		missingRequiredArgs: "ocr {name}: 缺少必填参数 {keys}（缺失即拒绝，不产生副作用）",
+		bodyMustBeObject: "body 必须是 JSON 对象",
+		outputFileMissing: "ocr 未写出 --output 文件（{path}）：{cause}——请确认 ocr 版本支持 --output，或用 ocr_session 查询会话结果",
+		settingsServiceGone: "{ns} 所在的设置服务在读取过程中已不可用",
+		repoRequired: "repo 必填，且为 Git 仓库绝对路径",
+		repoRequiredUnknownWorkspace: "repo 必填：当前会话工作区未知，请显式传入 Git 仓库绝对路径",
+		repoMustBeAbsolute: "repo 必须是绝对路径（以 / 开头）：{root}",
+		noNulBytes: "{name} 不能包含 NUL 字节",
+		mustBeString: "{name} 必须是字符串（收到 {received}）",
+		listItemsMustBeString: "{name} 数组元素必须是字符串",
+		mustBeStringOrList: "{name} 必须是字符串或字符串数组",
+		intFlagMustBeInt: "{flag} 需要为 ≥{min} 的整数，收到 {received}",
+		scopeBranchCommitExclusive: "scope=branch/from/to 与 commit 互斥（一次只能选一种审查范围）",
+		branchNeedsFromAndTo: "scope=branch 需要同时提供 from 与 to",
+		commitNeedsValue: "scope=commit 需要 commit 参数",
+		unknownScope: "未知 scope：{scope}（workspace/commit/branch）",
+		pathsRequired: "paths 必填：至少传一个待审查文件的仓库相对路径",
+		invalidAction: "action 非法：{action}（期望 {expected}）",
+		resultSchemaViolation: "ocr {tool}: 返回值不符合该工具的 output schema：{violations}",
+		resultSchemaUnsupported: "ocr {tool}: 返回形态守卫不支持 output schema 关键字 {keyword}（插件内 bug：lib/output.ts 的关键字子集没跟上 schema）",
+		ocrNotJson: "OCR 未返回合法 JSON 输出",
+		ocrNotObject: "OCR JSON 输出不是对象",
+		ocrStatusInvalid: "OCR 输出 status 非法或缺失：{status}（期望 {expected}）；exit 0 不代表评审完成，请查 stderr 与 ~/.opencodereview/sessions/",
+		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」当作「代码干净」。",
+		lineZeroNote: "(line 0: 定位失败，按 existing_code 手动定位)",
+		parseFailedWithReason: "{tool} 输出解析失败：{message}\n原始内容前 {limit} 码元（已脱敏）：\n{raw}",
+		parseFailedPlain: "{tool} 输出解析失败\n原始内容前 {limit} 码元（已脱敏）：\n{raw}",
+		sourceSettingsUnavailable: "dsh 设置服务（ctx.settings）未装配：本插件需要它读取已配置的 provider 列表",
+		sourceSettingsFailed: "调用 dsh 设置服务失败：{message}",
+		sourceNamespaceUnavailable: "dsh 配置里没有 {ns} 命名空间：未安装 pi-ai 适配器，或还没配置任何 provider",
+		sourceCredentialsUnavailable: "dsh 凭据服务（ctx.credentials）未装配：无法确认 provider 的 API key 是否已配置",
+		badEnvKey: "非法 env key：{key}",
+		configNotJson: "{where} 不是合法 JSON，已中止写入以保护既有配置（请先修复或删掉该文件）：{cause}",
+		configNotObject: "{where} 顶层不是 JSON 对象，已中止写入以保护既有配置",
+		providerNotInList: "provider 不在 dsh 配置的 {ns}.providers 列表：{provider}",
+		modelNotInList: "model 不在 {provider} 的 models 列表中：{model}",
+		ocrConfigPathInvalid: "设置项 ocrConfigPath 必须是绝对路径或 ~ 开头的路径：{path}",
+		noApiKeyEnv: "provider {provider} 未声明 apiKeyEnv，无法动态读取 key（OCR 自定义 provider 不支持无 key 解析）",
+		keyNotResolvable: "provider {provider} 的 API key 未配置：dsh 凭据服务未解析到 {ref}",
+		credScriptMissing: "get-cred 脚本缺失：{path}（api_key_cmd 无法工作）",
+		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' 通过。",
+		scanToolDescription: "用 open-code-review（ocr）做全文件扫描审查（无需 Git 变更/无 diff，适合审计陌生代码库或指定目录）。--path 逗号分隔的仓库相对目录/文件（缺省整个仓库）。与 ocr_review 一样由 OCR 自身 LLM 独立审查，返回聚合评论摘要。",
+		previewToolDescription: "open-code-review 委托模式第 1 步：列出待审查文件清单（mode/ref/merge_base/reviewable 文件路径+状态+增删行/被排除文件及原因），不调 LLM、秒级返回。用于确认 ocr_review/ocr_scan 的审查范围，或配合 ocr_delegate_rule 后由你自己（dsh 会话模型）读取 diff 完成审查。scope 与 ocr_review 一致（workspace/commit/branch）。",
+		ruleToolDescription: "open-code-review 委托模式第 2 步：按文件路径返回适配的审查规则（按规则内容分组，共享规则的多个文件归一组）。把 ocr_delegate_preview 得到的 reviewable 路径传进来，作为你自己审查时的检查清单。规则文本较长时按批传入。",
+		sessionToolDescription: "查询 open-code-review 的历史评审会话：action=list 列最近会话（含 session_id/mode/model/评论数，可用于 ocr_review --resume 恢复中断的评审）；action=show 查看单个会话元数据与逐文件检查点；action=comments 取单个会话的评论明细。session_id 也可从 ocr_review/ocr_scan 的返回结果直接获取。",
+		paramRepo: "Git 仓库绝对路径（可选：缺省=当前会话工作区）",
+		paramScope: "审查范围（缺省 workspace）",
+		paramCommit: "scope=commit 时必填：提交哈希",
+		paramFrom: "scope=branch 时必填：对比起点 ref（如 main）",
+		paramTo: "scope=branch 时必填：对比终点 ref（如 feature/x）",
+		paramCommitShort: "scope=commit 时必填",
+		paramFromShort: "scope=branch 时必填",
+		paramToShort: "scope=branch 时必填",
+		paramEffort: "投入档位（缺省 medium）",
+		paramBackground: "需求/业务上下文（官方 skill 推荐：调用前先用 git log/diff/提交信息快速分析变更意图，提取 3-5 句业务背景传入，是提升评审质量最有效的参数；从其它 agent 调用时始终携带 PR 描述/需求）",
+		paramBackgroundShort: "需求/业务上下文",
+		paramBackgroundPreview: "业务上下文（会出现在输出中供审查参考）",
+		paramExclude: "gitignore 风格排除模式（可多值）",
+		paramExcludeShort: "排除模式",
+		paramWait: "true（缺省）=等待完成并返回聚合摘要；false=后台启动立即返回（2 小时后兜底回收），用 ocr_session 轮询结果。两种模式都带宿主回收守护：dsh 退出（含 kill -9）时 OCR 进程一并结束",
+		paramProvider: "本次运行临时指定已配置 provider",
+		paramModel: "本次运行临时覆盖 model",
+		paramResume: "从之前中断的会话 id 恢复（会话 id 在返回结果里）",
+		paramScanPath: "仓库相对目录或文件（缺省整仓，可多值）",
+		paramBatch: "分批策略",
+		paramPaths: "待查询的仓库相对文件路径（至少 1 个，最多 200）",
+		paramSessionAction: "list：列最近会话（缺省）/ show：查看单个 / comments：取评论",
+		paramSessionId: "action=show/comments 时的会话 id",
+		paramSessionLimit: "list 上限 1-100（缺省 10）",
+		unitGroup: "组",
+		unitFile: "文件",
+		tuningConcurrency: "并发{unit}数（OCR --concurrency；缺省不传=OCR 原生 8）",
+		tuningTimeout: "每{unit}任务超时分钟（OCR --timeout；0=不限时；缺省不传=OCR 原生 15）",
+		tuningMaxTools: "每{unit}工具调用轮数上限（OCR --max-tools；0=模板默认；缺省不传=模板默认）",
+		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。",
+		ruleHint: "按分组规则逐个审查对应文件，输出评论建议格式：{path, content, start_line, end_line, category, severity}。",
+		sessionEmpty: "（暂无历史评审会话：先跑一次 ocr_review/ocr_scan 再查询）",
+		sessionTruncated: "…[截断] 完整内容见 ~/.opencodereview/sessions/",
+		sessionResumeHint: "要恢复中断的区间/commit 评审：ocr_review ... --resume <session_id>（工作区评审不支持恢复）。",
+		routingText: `
+- 用户要求「审查代码/Review/检查我的改动/审这个 commit/PR」时，用 ocr 工具做代码审查：
+  - ocr_review：OCR 用自己配置的 LLM 独立审查工作区/commit/分支变更（effort 控制深度，可给 background 上下文）。
+  - ocr_scan：对无 git 历史的目录或指定路径做全文件审查。
+  - ocr_delegate_preview / ocr_delegate_rule：只取「文件清单 + 适配规则」的确定性脚手架（OCR 端零 LLM 消耗），
+    配合 git diff 由你自己完成审查——适合复用本会话模型能力、或先确认审查范围再决定是否跑 ocr_review。
+  - 审查前若不确定范围，先 ocr_delegate_preview（不花 token）；范围过大时用 exclude 收敛或按 commit 拆。
+- OCR 端点/provider/model 由「设置 → 插件 → ocr-review 卡片」从 dsh 的 settings.yaml providers 选择；
+  也可在工具参数里用 --provider/--model 临时覆盖。
+- 调用 ocr_review / ocr_scan 前，先用 git log/diff/提交信息快速分析变更意图，提取 3-5 句业务上下文
+  传入 background（open-code-review 官方 skill 明确推荐"始终携带"，是质量提升最有效的单一参数）。
+- 若 ocr_review/ocr_scan 输出含 "No tool calls parsed" 或大量 "Max tool requests reached"，
+  是当前模型的工具调用能力问题——建议在 ocr-review 卡片换一个支持原生工具调用的模型（sensenova、deepseek、glm、qwen 系），
+  不要反复重试同一个模型。
+- LLM 调用本身有重试：OCR 内置重试（429/408/409 与 5xx 自动退避重试）；per-file 组失败被隔离并进 warnings，不整体重跑。
+  工具层超时（10 分钟）或部分文件失败后，可 ocr_session 查 session_id、用 ocr_review --resume 恢复中断的区间/commit 评审。
+`.trim()
+	},
+	en: {
+		middleEllipsis: " …[middle omitted]… ",
+		execTimedOut: "ocr timed out (effective {minutes} min = min(request, shell.maxTimeoutMs)): narrow the review scope (exclude / --commit / a smaller diff), lower OCR's per-group --timeout, raise shell.maxTimeoutMs in settings.yaml, or switch to background mode with wait=false (no timeout)",
+		execAborted: "ocr execution aborted",
+		execNotFound: "ocr command not found: install it first with `brew install open-code-review` or `npm i -g @alibaba-group/open-code-review`",
+		execFailed: "ocr failed (exit={exitCode})",
+		detailSeparator: ": ",
+		stdoutTruncated: "[ocr-review] note: output exceeded the {limit}-byte cap and was truncated{spill}",
+		outputSpill: " (full output spilled to {path})",
+		backgroundPolling: "Look up this repository's newest session shortly with ocr_session(action=list) (it appears a few seconds after start; match by scanPaths/time); completed_files == selected_files means it is done. Then ocr_session(action=comments, id) for all comments and ocr_session(action=show, id) for metadata and per-file checkpoints. Background runs get reclaimed by a 2-hour backstop (a wedged one would otherwise keep occupying the official job bucket); cancelling this tool call terminates the background OCR (host kill + the reaper guard inside the command).",
+		jobReasonAborted: "ocr-review tool call aborted",
+		jobReasonTimeout: "ocr-review background review exceeded 2 hours and was reclaimed",
+		jobReasonUnload: "ocr-review plugin unloaded",
+		jobOutputGap: "\n[ocr-review] note: one output read failed and was retried from the same offset (this stretch may be incomplete)",
+		requiredNotArray: "parameters.required must be an array of strings",
+		requiredItemNotString: "parameters.required items must be strings",
+		argsMustBeObject: "ocr {name}: arguments must be a JSON object (got {received})",
+		missingRequiredArgs: "ocr {name}: missing required parameter(s) {keys} (rejected outright, no side effects)",
+		bodyMustBeObject: "body must be a JSON object",
+		outputFileMissing: "ocr did not write the --output file ({path}): {cause} — check that your ocr version supports --output, or query the session with ocr_session",
+		settingsServiceGone: "the settings service holding {ns} became unavailable while being read",
+		repoRequired: "repo is required and must be the absolute path of a Git repository",
+		repoRequiredUnknownWorkspace: "repo is required: the current session workspace is unknown, pass the absolute path of a Git repository explicitly",
+		repoMustBeAbsolute: "repo must be an absolute path (starting with /): {root}",
+		noNulBytes: "{name} must not contain NUL bytes",
+		mustBeString: "{name} must be a string (got {received})",
+		listItemsMustBeString: "the items of {name} must be strings",
+		mustBeStringOrList: "{name} must be a string or an array of strings",
+		intFlagMustBeInt: "{flag} must be an integer ≥ {min}, got {received}",
+		scopeBranchCommitExclusive: "scope=branch/from/to and commit are mutually exclusive (only one review scope at a time)",
+		branchNeedsFromAndTo: "scope=branch requires both from and to",
+		commitNeedsValue: "scope=commit requires the commit parameter",
+		unknownScope: "unknown scope: {scope} (workspace/commit/branch)",
+		pathsRequired: "paths is required: pass at least one repo-relative path of a file to review",
+		invalidAction: "invalid action: {action} (expected {expected})",
+		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",
+		ocrNotObject: "the OCR JSON output is not an object",
+		ocrStatusInvalid: "OCR output has an invalid or missing status: {status} (expected {expected}); exit 0 does not mean the review completed — check stderr and ~/.opencodereview/sessions/",
+		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\".",
+		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}",
+		sourceSettingsUnavailable: "the dsh settings service (ctx.settings) is not wired up: this plugin needs it to read the configured provider list",
+		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}",
+		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}",
+		ocrConfigPathInvalid: "the ocrConfigPath setting must be absolute or start with ~: {path}",
+		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)",
+		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.",
+		scanToolDescription: "Whole-file scan review with open-code-review (ocr) — no Git changes or diff required, good for auditing an unfamiliar repository or given directories. --path takes comma-separated repo-relative directories/files (default: the whole repo). Like ocr_review, OCR's own LLM reviews independently and an aggregated comment summary is returned.",
+		previewToolDescription: "Step 1 of open-code-review delegate mode: list the files to review (mode/ref/merge_base/reviewable path+status+added/removed lines, plus excluded files and why). No LLM call, returns in seconds. Use it to confirm the scope of ocr_review/ocr_scan, or together with ocr_delegate_rule to review the diffs yourself (the dsh session model). scope matches ocr_review (workspace/commit/branch).",
+		ruleToolDescription: "Step 2 of open-code-review delegate mode: return the review rules that fit the given file paths (grouped by rule content; files sharing a rule land in one group). Feed the reviewable paths from ocr_delegate_preview and use the rules as your own review checklist. Pass paths in batches when the rule text is long.",
+		sessionToolDescription: "Query open-code-review's past review sessions: action=list shows recent sessions (session_id/mode/model/comment counts, usable for ocr_review --resume of interrupted reviews); action=show prints one session's metadata and per-file checkpoints; action=comments returns one session's comment details. session_id is also returned by ocr_review/ocr_scan.",
+		paramRepo: "Absolute path to the Git repository (optional: default = current session workspace)",
+		paramScope: "Review scope (default workspace)",
+		paramCommit: "Required with scope=commit: commit hash",
+		paramFrom: "Required with scope=branch: comparison start ref (e.g. main)",
+		paramTo: "Required with scope=branch: comparison end ref (e.g. feature/x)",
+		paramCommitShort: "Required with scope=commit",
+		paramFromShort: "Required with scope=branch",
+		paramToShort: "Required with scope=branch",
+		paramEffort: "Effort level (default medium)",
+		paramBackground: "Requirements/business context (official skill recommends: analyse the change intent via git log/diff/commit messages first and pass 3-5 sentences of context — the single most effective parameter for review quality; always carry the PR description/requirements when called from another agent)",
+		paramBackgroundShort: "Requirements/business context",
+		paramBackgroundPreview: "Business context (it shows up in the output for review reference)",
+		paramExclude: "gitignore-style exclusion patterns (multiple allowed)",
+		paramExcludeShort: "Exclusion patterns",
+		paramWait: "true (default) = wait for completion and return the aggregated summary; false = start in the background and return immediately (a 2-hour backstop reclaims it), poll with ocr_session. Both modes carry the host reaper guard: when dsh exits (including kill -9) the OCR process is terminated too",
+		paramProvider: "Temporarily use a configured provider for this run",
+		paramModel: "Temporarily override the model for this run",
+		paramResume: "Resume from a previously interrupted session id (the id is in the result)",
+		paramScanPath: "Repo-relative directories or files (default: whole repo, multiple allowed)",
+		paramBatch: "Batching strategy",
+		paramPaths: "Repo-relative file paths to look up (at least 1, at most 200)",
+		paramSessionAction: "list: recent sessions (default) / show: one session / comments: comment list",
+		paramSessionId: "Session id for action=show/comments",
+		paramSessionLimit: "list cap 1-100 (default 10)",
+		unitGroup: "group",
+		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)",
+		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).",
+		ruleHint: "Review the files of each group against its rule and emit comment suggestions in the shape {path, content, start_line, end_line, category, severity}.",
+		sessionEmpty: "(no review sessions yet: run ocr_review/ocr_scan once before querying)",
+		sessionTruncated: "…[truncated] full content in ~/.opencodereview/sessions/",
+		sessionResumeHint: "To resume an interrupted range/commit review: ocr_review ... --resume <session_id> (workspace reviews cannot be resumed).",
+		routingText: `
+- When the user asks to "review the code / Review / check my changes / review this commit or PR", use the ocr tools:
+  - ocr_review: OCR reviews workspace/commit/branch changes with its own configured LLM (effort controls depth, background carries context).
+  - ocr_scan: whole-file review of directories without git history, or of given paths.
+  - ocr_delegate_preview / ocr_delegate_rule: deterministic scaffolding that only returns "file list + fitting rules"
+    (zero LLM cost on the OCR side); pair it with git diff and review yourself — good for reusing this session's model,
+    or for confirming the scope before deciding to run ocr_review.
+  - Unsure about the scope? Run ocr_delegate_preview first (costs no tokens); if the scope is huge, narrow it with
+    exclude or split by commit.
+- The OCR endpoint/provider/model comes from "Settings → Plugins → ocr-review card", fed by dsh's settings.yaml
+  providers; --provider/--model can override per call.
+- Before ocr_review / ocr_scan, analyse the change intent via git log/diff/commit messages and pass 3-5 sentences of
+  business context as background (the official open-code-review skill says "always carry it" — the single most
+  effective quality knob).
+- If ocr_review/ocr_scan output contains "No tool calls parsed" or many "Max tool requests reached", the current
+  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.
+`.trim()
+	}
+};
+/** 花括号占位符（键限 \w+；`{path, content}` 这类字面花括号不匹配）。 */
+const PLACEHOLDER = /\{(?<key>\w+)\}/gu;
+/**
+* host 半的 `{name}` 插值：与卡片侧官方 Translate 同语法（宿主那份实现在
+* dsh-client-locale 里，host 侧没有 i18n 面，只能自带这一小段）。
+* @param template - 带 `{name}` 占位符的文案模板。
+* @param params - 占位符 → 已字符串化的值；缺项替换为空串（不抛）。
+* @returns 插值后的文本。
+*/
+function format(template, params) {
+	return template.replaceAll(PLACEHOLDER, (_all, key) => params[key] ?? "");
+}
+//#endregion
+//#region lib/output.ts
+/** 守卫支持的 schema 关键字（官方 enforced subset 的全部关键字，见
+*  installed dsh-tools lib/index.js:206；description/title/default/examples 是
+*  官方同样忽略的注解）。 */
+const SUPPORTED_KEYWORDS = /* @__PURE__ */ new Set([
+	"type",
+	"oneOf",
+	"properties",
+	"required",
+	"additionalProperties",
+	"items",
+	"const",
+	"enum",
+	"description",
+	"title",
+	"default",
+	"examples"
+]);
+/** schema 里的关键字必须全部落在守卫支持的子集内（递归查 oneOf/properties/items）。
+*  违例抛错而不是当违规值报：schema 是插件自己的代码，错的是代码不是模型的数据。 */
+function assertGuardable(schema, toolName, messages) {
+	for (const keyword of Object.keys(schema)) if (!SUPPORTED_KEYWORDS.has(keyword)) throw new Error(format(messages.resultSchemaUnsupported, {
+		tool: toolName,
+		keyword
+	}));
+	for (const branch of schema.oneOf ?? []) assertGuardable(branch, toolName, messages);
+	for (const property of Object.values(schema.properties ?? {})) assertGuardable(property, toolName, messages);
+	const { items } = schema;
+	if (items !== void 0) assertGuardable(items, toolName, messages);
+}
+/** 标量分支的形态判定（true = 不合形态；判据对齐官方 checkValue 的标量臂：
+*  number 须为有限 JSON 数、integer 须整数值）。 */
+function scalarMismatch(type, value) {
+	if (type === "string") return typeof value !== "string";
+	if (type === "number") return typeof value !== "number" || !Number.isFinite(value);
+	if (type === "integer") return typeof value !== "number" || !Number.isInteger(value);
+	if (type === "boolean") return typeof value !== "boolean";
+	return value !== null;
+}
+/** object 分支：isRecord → additionalProperties:false 的多余键 → required（缺键与
+*  「键在但值是 undefined」同判，与官方一致）→ 逐声明字段递归。 */
+function objectViolations(schema, value, path, walk) {
+	if (!isRecord(value)) return [`${path}: expected object`];
+	const { properties, required, additionalProperties } = schema;
+	if (additionalProperties === false) {
+		const extra = Object.keys(value).filter((key) => properties?.[key] === void 0);
+		if (extra.length > 0) return [`${path}: fields outside the schema: ${extra.join(", ")}`];
+	}
+	for (const key of required ?? []) if (!(key in value) || value[key] === void 0) return [`${path}: missing required field ${key}`];
+	const violations = [];
+	for (const key of Object.keys(value)) {
+		const child = properties?.[key];
+		if (child !== void 0) violations.push(...walk(child, value[key], `${path}.${key}`));
+	}
+	return violations;
+}
+/** array 分支：Array.isArray → 无 items 视为任意元素 → 逐元素递归（违规一次列全）。 */
+function arrayViolations(schema, value, path, walk) {
+	if (!Array.isArray(value)) return [`${path}: expected array`];
+	const { items } = schema;
+	if (items === void 0) return [];
+	return value.flatMap((item, index) => walk(items, item, `${path}[${index}]`));
+}
+/** 官方子集的迷你走查（path 限定违规位置，一次列全）。oneOf 语义与官方一致：
+*  恰好一支命中，多支/零支都算违规。 */
+function violationsOf(schema, value, path) {
+	if (schema.oneOf !== void 0) {
+		const passing = schema.oneOf.filter((branch) => violationsOf(branch, value, path).length === 0);
+		if (passing.length !== 1) return [`${path}: matched ${passing.length} of ${schema.oneOf.length} oneOf branches`];
+		return [];
+	}
+	const { type } = schema;
+	if (type === "object") return objectViolations(schema, value, path, violationsOf);
+	if (type === "array") return arrayViolations(schema, value, path, violationsOf);
+	if (type === void 0) return [];
+	if (scalarMismatch(type, value)) return [`${path}: expected ${type}`];
+	if (schema.const !== void 0 && value !== schema.const) return [`${path}: must be exactly ${JSON.stringify(schema.const)}`];
+	if (schema.enum !== void 0 && !schema.enum.includes(value)) return [`${path}: must be one of ${schema.enum.map((entry) => JSON.stringify(entry)).join("/")}`];
+	return [];
+}
+/**
+* 校验并放行工具返回值：必须命中该工具自己的 output schema。
+* 违规抛错而非静默裁剪——静默修正是第二个 bug 的开始，抛错让回归在开发期
+* （vitest/首次调用）就炸出来。
+* @param schema 该工具注册时声明的 output.schema（与宿主校验用的是同一个对象）
+* @param value execute 交回的 canonical 值（结构化对象 / 数组 / 标量 / null）
+* @param toolName 工具名（违规信息要点名，模型才知道该重试哪一次调用）
+* @param messages 双语文案
+* @returns 原值（校验只读不改，值原样交给宿主）
+*/
+function assertToolOutput(schema, value, toolName, messages) {
+	assertGuardable(schema, toolName, messages);
+	const violations = violationsOf(schema, value, "result");
+	if (violations.length > 0) throw new Error(format(messages.resultSchemaViolation, {
+		tool: toolName,
+		violations: violations.join("; ")
+	}));
+	return value;
+}
+/** provider key 形状：`sk-…`/`ark-…`/`ghp-…` 一类「短前缀 + 长随机串」。
+*
+*  为什么额外要求随机串里至少有一个数字或大写字母：真实 key 是随机 base62（32 位
+*  纯小写的概率约 1e-12），而审查输出里的 kebab 小写长串几乎只可能是文件路径
+*  （`src/my-super-long-directory-name/index.ts`）。少了这道约束，session/delegate
+*  透传出的路径会被抹成 ***REDACTED***，模型拿不到可行动的位置信息。 */
+const STANDALONE_KEY = /\b[A-Za-z]{2,5}-(?=[A-Za-z0-9_-]{20,}\b)(?=[A-Za-z0-9_-]*[0-9A-Z])[A-Za-z0-9_-]{20,}\b/gu;
+/** `Authorization: Bearer xxx` / `bearer xxx`。
+*
+*  字符集写 `[a-z…]` 而不是 `[A-Za-z…]`：本条带 `i` 旗标，`a-z` 在大小写不敏感下
+*  已同时匹配 `A-Z`——再并列一枚 `A-Z` 是同一个字符集抄两遍（sonarjs 判为字符类内重复），
+*  删掉重复的那一位，匹配语言不变。 */
+const BEARER_VALUE = /(?<scheme>\bbearer\s+)[a-z0-9._~+/=-]{12,}/giu;
+/** `api_key: "xxx"`、`apiKey=xxx`、`token: xxx`、`x-api-key: xxx` 等赋值形态。 */
+const KEY_ASSIGNMENT = /(?<name>\b(?:api[_-]?key|apikey|access[_-]?key|secret[_-]?key|client[_-]?secret|password|token)["'\s]*[:=]["'\s]*)[^\s"',;)}\]]{6,}/giu;
+const REDACTION = "***REDACTED***";
+/**
+* 抹掉文本里 key 形状的片段。
+*
+* 为什么需要：OCR 会把 provider 配置错误连同请求头/端点整段回显到 stderr，
+* `ocr llm test` 的输出又直通设置卡片；工具错误文本还会被持久化进会话日志
+* （session log），一次回显就等于把明文 key 写进了长期存储。本插件的既定
+* 决策是「key 绝不落盘、绝不过 HTTP」，故所有原始输出出口都必须过这道闸
+* （harness 同方向的红线见 packages/settings/settings/src/redact.ts）。
+*
+* 只做「形态匹配」替换：赋值/Bearer 形态一律从严（宁可多抹），独立 key 形态则
+* 要求随机串特征，避免把要交给模型的文件路径一起抹掉。
+*/
+function redactKeyMaterial(text) {
+	return text.replaceAll(BEARER_VALUE, `$<scheme>${REDACTION}`).replaceAll(KEY_ASSIGNMENT, `$<name>${REDACTION}`).replaceAll(STANDALONE_KEY, REDACTION);
+}
+//#endregion
+//#region lib/argv-guard.ts
+/** POSIX sh 单引号转义：' → '\''。把任意字符串安全放进单引号内，防注入。 */
+function shq(value) {
+	return `'${value.replaceAll("'", String.raw`'\''`)}'`;
+}
+/** 绝对路径校验（macOS/Linux）：非空、以 / 开头、无 NUL 字节。 */
+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 EFFORTS = [
+	"low",
+	"medium",
+	"high"
+];
+/** effort 参数：非法值回默认（配置/medium 由调用方决定回退），此处只钳到合法集。 */
+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 会跳过稀疏数组的空洞，
+*  空洞本是「非字符串元素」这一条该拦的形态，跳过就等于静默少一项过滤条件。 */
+function listSourceItems(value, name, messages) {
+	if (typeof value === "string") return value.split(",");
+	if (Array.isArray(value)) {
+		const items = [];
+		for (const item of value) {
+			if (typeof item !== "string") throw new TypeError(format(messages.listItemsMustBeString, { name }));
+			items.push(item);
+		}
+		return items;
+	}
+	throw new TypeError(format(messages.mustBeStringOrList, { name }));
+}
+/** 原始项 → 取值（commaList 的第二段：只判内容，NUL 抛错、trim、丢空串，满 limit 即止）。 */
+function takeTrimmedItems(items, name, limit, messages) {
+	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;
+	}
+	return out;
+}
+/** 字符串数组 → 逗号拼接（--exclude/--path 契约）。
+*  元素类型严格：`value.map(String)` 会把对象变成 `[object Object]` 静默混入
+*  模式串（过滤条件失效 = 审查范围被扩大），故非字符串元素一律抛错。
+*  防注入由调用点 shq() 兜底。 */
+function commaList(value, name, limit, messages) {
+	if (value === void 0 || value === null) return [];
+	return takeTrimmedItems(listSourceItems(value, name, messages), name, limit, messages);
+}
+const REVIEW_OUTPUT_FORMATS = [
+	"json",
+	"text",
+	"sarif"
+];
+/**
+* `--format` 白名单钳制（命令注入防线）。
+*
+* 为什么必须白名单：format 不在任何工具的 parameters schema 里（模型传不进、
+* 但 PTC/直连调用方能传），而宿主对工具入参零校验；构造出的命令串最终会被
+* `wrapWithHostReaper` 塞进 `bash -c '<inner>'`。历史上这里是裸拼接
+* （`parts.push("--format", args.format ?? "json")`），实测
+* `format: "json; touch /tmp/PWNED; echo"` 可在宿主进程内任意执行命令。
+* 转义不是修复——一个「本该只有三个取值的枚举」出现任意字符串就是攻击意图，
+* 一律回落到默认值，绝不进入命令串。
+*/
+function resolveOutputFormat(value) {
+	return REVIEW_OUTPUT_FORMATS.find((candidate) => candidate === value) ?? "json";
+}
+//#endregion
+//#region lib/cli.ts
+/** `ocr review|scan|delegate preview` 的背景说明 flag（三处命令构造共用一条）。
+*  pushTextFlag 按 `flag.slice(2)` 反推报错用的参数名，故值必须带 `--` 前缀。 */
+const BACKGROUND_FLAG = "--background";
+/** root 解析：显式绝对路径优先；缺失/空串回退到当前会话工作区。 */
+function resolveRoot(value, fallback, messages) {
+	if (typeof value === "string" && value.trim().length > 0) return assertAbsoluteRoot(value.trim(), messages);
+	if (typeof fallback === "string" && fallback.trim().length > 0) return assertAbsoluteRoot(fallback.trim(), messages);
+	throw new Error(messages.repoRequiredUnknownWorkspace);
+}
+/** 报错用的值形态（永不调用可能被劫持的 toJSON/toString）。 */
+function describeValue(value) {
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
+	return Array.isArray(value) ? "array" : typeof value;
+}
+/** 字符串标量参数：键存在即必须是字符串。
+*
+* 为什么拒绝而不是忽略：宿主对工具入参零校验（dsh tools index.ts
+* `execute(exec.arguments, exec)` 原样下发、schema 只发给模型），错类型一旦
+* 被「当作缺省」就会静默改变语义——实测 `{commit: 12345}` 无 scope 时退化成
+* workspace 审查并把结果当 verdict 报给用户（审查范围被静默扩大）。空串按
+* 缺省处理（与既有语义一致）。 */
+function idValue(value, name, messages) {
+	if (value === void 0 || value === null) return "";
+	if (typeof value !== "string") throw new TypeError(format(messages.mustBeString, {
+		name,
+		received: describeValue(value)
+	}));
+	const trimmed = value.trim();
+	if (trimmed.includes("\0")) throw new Error(format(messages.noNulBytes, { name }));
+	return trimmed;
+}
+/**
+* 数值 flag 忠实透传（桥接层不设钳制——OCR 原生语义：0 = 配置/模板默认或不限，
+* 负数/非整数由 OCR 侧报错，但桥接层先做同源校验给出更早的错误）。
+* value 为 undefined/null 时省略 flag（跟随 OCR flag 默认值）。
+*
+* 注入面：数值经 `String(num)` 落进命令串（不走 shq）。Number.isInteger 对
+* 1e21 为 true 而 String() 会写成 `1e+21`，故再加一道「只含数字」的形态校验：
+* 命令串里的数值 token 结构上不可能带 shell 元字符。
+*/
+function pushIntFlag(parts, flag, value, min, messages) {
+	if (value === void 0 || value === null) return;
+	const num = typeof value === "number" ? value : Number(value);
+	const text = String(num);
+	if (!Number.isInteger(num) || num < min || !/^\d+$/u.test(text)) throw new Error(format(messages.intFlagMustBeInt, {
+		flag,
+		min: String(min),
+		received: describeValue(value)
+	}));
+	parts.push(flag, text);
+}
+/** 模式参数解析：workspace（默认）/commit/branch 互斥，非法组合与错类型抛错。
+*
+* 互斥判定必须在两个模式分支之前一次做完：若先判 commit（`commit 非空` 时条件
+* 恒真），后面的「branch 与 commit 互斥」就永不可达，`{scope:branch, commit:x}`
+* 会被静默降级成 commit 审查——审错范围却按结论上报。 */
+function scopeFlags(args, messages) {
+	const scopeName = idValue(args.scope, "scope", messages).toLowerCase();
+	const scope = scopeName === "" ? "workspace" : scopeName;
+	const from = idValue(args.from, "from", messages);
+	const to = idValue(args.to, "to", messages);
+	const commit = idValue(args.commit, "commit", messages);
+	const wantsBranch = scope === "branch" || from !== "" || to !== "";
+	const wantsCommit = scope === "commit" || commit !== "";
+	if (wantsBranch && wantsCommit) throw new Error(messages.scopeBranchCommitExclusive);
+	if (wantsBranch) {
+		if (from === "" || to === "") throw new Error(messages.branchNeedsFromAndTo);
+		return [
+			"--from",
+			shq(from),
+			"--to",
+			shq(to)
+		];
+	}
+	if (wantsCommit) {
+		if (scope === "commit" && commit === "") throw new Error(messages.commitNeedsValue);
+		return ["--commit", shq(commit)];
+	}
+	if (scope !== "workspace") throw new Error(format(messages.unknownScope, { scope }));
+	return [];
+}
+/** 可选文本 flag：值缺省/空串则省略，错类型抛错（静默丢弃等于悄悄改变语义）。 */
+function pushTextFlag(parts, flag, value, messages) {
+	const text = idValue(value, flag.slice(2), messages);
+	if (text !== "") parts.push(flag, shq(text));
+}
+/** --exclude/--background/--provider/--model 等通用 flag。
+* 注意：ocr 的 --exclude 是 String 类型（实测 v1.12.0 多 flag 实例只认最后一个，
+* 逗号分隔才生效）——多值必须合并为一个 flag 逗号连接，绝不能展开多个。
+*/
+function optionalFlags(args, messages) {
+	const parts = [];
+	const excludes = commaList(args.exclude, "exclude", 50, messages);
+	if (excludes.length > 0) parts.push("--exclude", shq(excludes.join(",")));
+	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;
+}
+/**
+* 宿主回收守护：把 review/scan 长命令包进 `bash -c`，保证 dsh 进程以任何方式
+* 退出时 OCR 都不会变成孤儿继续跑（用户要求：dsh 彻底退出 → OCR 必须结束）。
+*
+* 为什么需要：macOS 上 dsh 硬退出（kill -9/崩溃）后，detached 子进程被 launchd
+* 收养——subprocess-local 源码自述 "macOS has no supported persistent
+* process-range owner"，只能由进程自己看护自己。
+*
+* 两层互补：
+*  - 优雅退出（exit 命令 / Ctrl+C / SIGTERM）：宿主 teardown 向组发 TERM，
+*    守护的 `trap 'reap; exit 143' TERM INT` 收到后转发 reap。（bash 语义坑：
+*    reap 自毙后 trap 里的 exit 不会执行，所以 reap 必须自带完整链——TERM→宽限
+*    →补 KILL 全部目标，自我清场的组 KILL 排在最后一步。）
+*  - 硬退出：守护随 launchd 收养后 ppid 改变，监视循环探测 ppid != 初始值 →
+*    reap 后退出。TERM 先行是因 OCR 原生 signal.Notify
+*    （cmd/opencodereview/interrupt.go:48）会优雅落盘会话清单再退。
+*
+* 组语义：dsh shell runner 以 detached:true（setsid）启动 `bash -c <cmd>`，
+* 守护即组长，`kill -- -$$` 覆盖组内任意深度后代；守护另有组长判定，非组长
+* （手测/异常）绝不发起组杀（防误伤宿主组），改走「$ocr+递归后代快照」回退。
+*
+* 语义实测（本机 bash 3.2，均为源码模板逐字提取的产物）：
+*  - stdio 与退出码透传（OUT/ERR/rc=7），正常退出路径绝不触发 reap；
+*  - 组长场景（detached 复刻 runner）dsh 硬退出后 +2s：stub 走 trap 优雅收尾、
+*    孙进程随组消亡——只杀 $ocr 与其直接子级会漏孙进程（实测泄漏被收养）；
+*  - 非组长场景守护收 TERM：stub/stub 包装层/孙进程全部消亡。
+* 只包 review/scan（分钟级任务）；delegate/session/llm-test 秒级命令不包。
+*/
+function wrapWithHostReaper(command) {
+	if (process.platform === "win32") return command;
+	return `bash -c ${shq([
+		`p0=$(ps -o ppid= -p $$ | tr -d ' ')`,
+		`{ ${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 ' ')" = "$$" ]; }`,
+		`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`,
+		`kill -0 "$ocr" 2>/dev/null && reap`,
+		`wait "$ocr"; exit $?`
+	].join("; "))}`;
+}
+function locateLauncher() {
+	let launcher = null;
+	try {
+		const entry = createRequire(import.meta.url).resolve("@alibaba-group/open-code-review/package.json");
+		const candidate = path.join(path.dirname(entry), "bin", "ocr.js");
+		if (existsSync(candidate)) launcher = candidate;
+	} catch {}
+	return launcher;
+}
+/** 进程级记忆槽（默认那一档）：整包共用一次解析结果。 */
+const memoBox = {};
+/** 解析出的 `ocr` 命令词（已 shq 转义）：随包入口的绝对路径，或 PATH 上的裸 `ocr`。
+*  惰性求值 + 每进程记忆一次，与 dsh 核心解析 @vscode/ripgrep 同款：解析失败绝不在
+*  装载期抛，否则整包会因为一个可选二进制而下线。
+*  导出给同包的命令构造单测——它们按同一个解析结果写期望值，测试与生产同源，
+*  而不是各自把「ocr 还是某个绝对路径」写死一遍。
+* @param locate 随包 launcher 的定位口（默认实现即生产那一档）。
+* @param memo 记忆槽（默认进程级单例；单测传自己的盒以便反复构造两条分支）。
+*/
+function ocrCommand(locate = locateLauncher, memo = memoBox) {
+	if (memo.value === void 0) {
+		const launcher = locate();
+		memo.value = launcher === null ? "ocr" : shq(launcher);
+	}
+	return memo.value;
+}
+/**
+* 构造 `ocr review` 命令。--output 固定为调用方给定的临时文件路径（防截断），
+* --audience agent --format json 是默认（结构化、无进度行）。
+* outputPath 缺省（后台模式）省略 --output：结果以 OCR 会话记录为准。
+* 返回裸命令；宿主回收守护由调用方（host.ts）在执行点套 wrapWithHostReaper。
+*/
+function buildReviewCommand(args, outputPath, messages) {
+	const repo = assertAbsoluteRoot(args.repo, messages);
+	const parts = [
+		ocrCommand(),
+		"review",
+		"--audience",
+		"agent",
+		"--format",
+		resolveOutputFormat(args.format)
+	];
+	const effort = clampEffort(args.effort, "medium");
+	parts.push("--effort", effort);
+	pushIntFlag(parts, "--concurrency", args.concurrency, 1, messages);
+	pushIntFlag(parts, "--timeout", args.timeoutMinutes, 0, 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));
+	if (outputPath !== void 0) parts.push("--output", shq(outputPath));
+	return {
+		command: parts.join(" "),
+		workdir: repo
+	};
+}
+/** 构造 `ocr scan` 命令（无 git diff 的全文件扫描）。
+* 与 review 相同的坑：--path/--exclude 都是 String 类型，多值必须逗号连接
+* （实测 v1.12.0：多 flag 实例不生效），绝不能展开多个。
+* outputPath 缺省（后台模式）省略 --output：结果以 OCR 会话记录为准。 */
+function buildScanCommand(args, outputPath, messages) {
+	const repo = assertAbsoluteRoot(args.repo, messages);
+	const parts = [
+		ocrCommand(),
+		"scan",
+		"--audience",
+		"agent",
+		"--format",
+		resolveOutputFormat(args.format)
+	];
+	const paths = commaList(args.path, "path", 100, messages);
+	if (paths.length > 0) parts.push("--path", shq(paths.join(",")));
+	const excludes = commaList(args.exclude, "exclude", 50, messages);
+	if (excludes.length > 0) parts.push("--exclude", shq(excludes.join(",")));
+	pushTextFlag(parts, "--batch", args.batch, messages);
+	pushIntFlag(parts, "--concurrency", args.concurrency, 1, messages);
+	pushIntFlag(parts, "--timeout", args.timeoutMinutes, 0, 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);
+	pushTextFlag(parts, BACKGROUND_FLAG, args.background, messages);
+	if (outputPath !== void 0) parts.push("--output", shq(outputPath));
+	return {
+		command: parts.join(" "),
+		workdir: repo
+	};
+}
+/** 构造 `ocr delegate preview` 命令（只列文件清单，不跑 LLM）。 */
+function buildDelegatePreviewCommand(args, messages) {
+	const repo = assertAbsoluteRoot(args.repo, messages);
+	const scopeArgs = {
+		...args,
+		format: "json"
+	};
+	const parts = [
+		ocrCommand(),
+		"delegate",
+		"preview",
+		"--format",
+		"json",
+		...scopeFlags(scopeArgs, messages)
+	];
+	const excludes = commaList(args.exclude, "exclude", 50, messages);
+	if (excludes.length > 0) parts.push("--exclude", shq(excludes.join(",")));
+	pushTextFlag(parts, BACKGROUND_FLAG, args.background, messages);
+	return {
+		command: parts.join(" "),
+		workdir: repo
+	};
+}
+/** 构造 `ocr delegate rule` 命令（路径为位置参数，逐条 shq 转义）。 */
+function buildDelegateRuleCommand(args, messages) {
+	const repo = assertAbsoluteRoot(args.repo, messages);
+	const paths = commaList(args.paths, "paths", 200, messages).map((filePath) => shq(filePath));
+	if (paths.length === 0) throw new Error(messages.pathsRequired);
+	return {
+		command: [
+			ocrCommand(),
+			"delegate",
+			"rule",
+			"--format",
+			"json",
+			"--",
+			...paths
+		].join(" "),
+		workdir: repo
+	};
+}
+/** session 子命令白名单（子命令名裸拼进命令串，只可能是这三个字面量）。 */
+const SESSION_ACTIONS = [
+	"list",
+	"show",
+	"comments"
+];
+/** 构造 `ocr session list/show/comments` 命令（历史评审会话闭环，Json 输出）。 */
+function buildSessionCommand(args, messages) {
+	const repo = assertAbsoluteRoot(args.repo, messages);
+	const id = idValue(args.id, "id", messages);
+	const action = idValue(args.action, "action", messages);
+	const requested = SESSION_ACTIONS.find((name) => name === action);
+	if (action !== "" && requested === void 0) throw new Error(format(messages.invalidAction, {
+		action,
+		expected: SESSION_ACTIONS.join("/")
+	}));
+	let sub;
+	if (requested === "comments" || requested === "show") sub = id === "" ? "list" : requested;
+	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));
+	return {
+		command: parts.join(" "),
+		workdir: repo
+	};
+}
+//#endregion
+//#region lib/severity.ts
+const SEVERITY_ORDER = [
+	"critical",
+	"high",
+	"medium",
+	"low"
+];
+/**
+* 严重度归一：白名单外的值（含 OCR 自造等级、大小写异形）一律按 medium。
+* 聚合与排序共用这一个函数——此前两处各自实现（排序 indexOf 未命中得 -1 而把
+* UNKNOWN 排到 critical 之前，聚合却归 medium），同一份数据两种口径。
+*/
+function normalizeSeverity(severity) {
+	return SEVERITY_ORDER.find((level) => level === severity) ?? "medium";
+}
+/** 排序位：critical→high→medium→low（未知已归 medium，永不为 -1）。 */
+function severityRank(severity) {
+	return SEVERITY_ORDER.indexOf(normalizeSeverity(severity));
+}
+/** 聚合评论：按严重度/类别计数。severity 归类以 critical→high→medium→low 基准。 */
+function aggregateComments(comments) {
+	const bySeverity = {
+		critical: 0,
+		high: 0,
+		medium: 0,
+		low: 0
+	};
+	const byCategory = {};
+	for (const comment of comments) {
+		const sev = normalizeSeverity(comment.severity);
+		bySeverity[sev] += 1;
+		if (comment.category) byCategory[comment.category] = (byCategory[comment.category] ?? 0) + 1;
+	}
+	return {
+		total: comments.length,
+		bySeverity,
+		byCategory
+	};
+}
+//#endregion
+//#region lib/parse.ts
+/**
+* OCR 评审 JSON 的 status 枚举（docs/cli-reference + 1.12.0 实测）。
+* 白名单外的一律视为失败：exit 0 不等于评审成功——`{"error":"auth failed"}`
+* 这类「没有 status 的错误对象」若被当作 ok:true，模型会把「0 条评论」读成
+* 「代码干净」，是最坏的一类假阳性。
+*/
+const REVIEW_STATUSES = [
+	"success",
+	"complete",
+	"completed_with_warnings",
+	"completed_with_errors",
+	"skipped"
+];
+/** 未知 JSON 值 → 安全字符串（非字符串/缺省给 ''）。 */
+function str(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	return "";
+}
+/**
+* 数值字段解析：number 与「数字字符串」都接受（OCR 部分 provider 实测把
+* start_line 输出成 "42"，一律当 0 会把真实评论判成「未锚定」而被摘要丢掉），
+* 空串/NaN/Infinity/其它类型回 0。
+*/
+function num(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : 0;
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (trimmed === "") return 0;
+		const parsed = Number(trimmed);
+		return Number.isFinite(parsed) ? parsed : 0;
+	}
+	return 0;
+}
+function commentOf(raw) {
+	if (!isRecord(raw)) return null;
+	const content = str(raw["content"]);
+	if (content.length === 0) return null;
+	return {
+		path: str(raw["path"]),
+		content,
+		startLine: num(raw["start_line"]),
+		endLine: num(raw["end_line"]),
+		category: str(raw["category"]),
+		severity: (str(raw["severity"]) || "medium").toLowerCase(),
+		existingCode: str(raw["existing_code"]),
+		suggestionCode: str(raw["suggestion_code"])
+	};
+}
+/** 失败摘要（status 非法/JSON 不合形态时的统一返回，避免多处重复骨架）。 */
+function reviewFailure(status, message) {
+	return {
+		ok: false,
+		status,
+		message,
+		skipped: false,
+		summary: null,
+		comments: [],
+		warnings: [],
+		sessionId: "",
+		droppedComments: 0
+	};
+}
+/**
+* 解析 review/scan JSON。text 应为 `ocr review --format json` 的完整 stdout/
+* 输出文件内容。解析失败（非 JSON）或 status 不在白名单（含缺失，例如
+* `{"error":"..."}` 这类 exit 0 的错误对象）返回 ok=false，由调用方报错。
+*/
+function parseReviewOutput(text, messages) {
+	let doc;
+	try {
+		doc = JSON.parse(text);
+	} catch {
+		return reviewFailure("unparseable", messages.ocrNotJson);
+	}
+	if (!isRecord(doc)) return reviewFailure("unparseable", messages.ocrNotObject);
+	const root = doc;
+	const rawStatus = root["status"];
+	const status = REVIEW_STATUSES.find((level) => level === rawStatus);
+	if (status === void 0) return reviewFailure("invalid", format(messages.ocrStatusInvalid, {
+		status: str(rawStatus) || messages.statusNone,
+		expected: REVIEW_STATUSES.join("/")
+	}));
+	const commentsRaw = root["comments"];
+	if (commentsRaw !== void 0 && !Array.isArray(commentsRaw)) return reviewFailure("invalid", messages.ocrCommentsNotArray);
+	const comments = [];
+	let droppedComments = 0;
+	const rawComments = commentsRaw ?? [];
+	for (const raw of rawComments) {
+		const comment = commentOf(raw);
+		if (comment === null) droppedComments += 1;
+		else comments.push(comment);
+	}
+	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) => {
+		if (typeof warn === "string") return warn;
+		if (isRecord(warn)) return [str(warn["file"]), str(warn["error"])].filter(Boolean).join(messages.warningSeparator);
+		return "";
+	}).filter(Boolean) : [];
+	return {
+		ok: true,
+		status,
+		message: str(root["message"]),
+		skipped,
+		summary: sum ? {
+			filesReviewed: num(sum["files_reviewed"]),
+			comments: num(sum["comments"]),
+			totalTokens: num(sum["total_tokens"]),
+			inputTokens: num(sum["input_tokens"]),
+			outputTokens: num(sum["output_tokens"]),
+			elapsed: str(sum["elapsed"])
+		} : null,
+		comments,
+		warnings: warningsArr,
+		sessionId: str(root["session_id"]),
+		droppedComments
+	};
+}
+/** 默认摘要计划（no-object-as-default-parameter：避免对象字面量作参数默认值）。 */
+const DEFAULT_PLAN = {
+	maxComments: 12,
+	includeZeroLine: false
+};
+/** 单条评论的 top 位置（0 行未锚定降级为 :0）。 */
+function locationOf(comment) {
+	const fallbackPath = comment.path || "(path unknown)";
+	if (comment.startLine <= 0) return `${fallbackPath}:0`;
+	const suffix = comment.endLine > comment.startLine ? `-${comment.endLine}` : "";
+	return `${fallbackPath}:${comment.startLine}${suffix}`;
+}
+/**
+* 生成工具返回给模型的结构化摘要（省 token：给聚合与 top-N 评论，不塞全量）。
+* 输出为可直接 render 的普通对象，避免 JSON 里塞超大字符串。
+*/
+function summarizeReview(parsed, messages, plan = DEFAULT_PLAN) {
+	const agg = aggregateComments(parsed.comments);
+	const unlimited = plan.maxComments <= 0;
+	const keepZeroLine = plan.includeZeroLine === true;
+	const ranked = [...parsed.comments].toSorted((x, y) => severityRank(x.severity) - severityRank(y.severity) || x.startLine - y.startLine).filter((comment) => unlimited || keepZeroLine || comment.startLine > 0).slice(0, unlimited ? void 0 : plan.maxComments);
+	return {
+		status: parsed.status,
+		skipped: parsed.skipped,
+		message: parsed.message || null,
+		summary: parsed.summary ?? null,
+		sessionId: parsed.sessionId || null,
+		aggregation: agg,
+		totalCommentCount: parsed.comments.length,
+		droppedCount: parsed.comments.length - ranked.length,
+		invalidCommentCount: parsed.droppedComments,
+		topComments: ranked.map((comment) => ({
+			location: locationOf(comment),
+			severity: comment.severity,
+			category: comment.category,
+			content: comment.content,
+			suggestion: comment.suggestionCode || null
+		})),
+		warnings: parsed.warnings,
+		hint: messages.reviewSummaryHint
+	};
+}
+/** preview/rule 文档各自的契约键：一个都不命中即视为「不是该命令的输出」。 */
+const DELEGATE_PREVIEW_KEYS = [
+	"mode",
+	"repository",
+	"total_files",
+	"reviewable_files"
+];
+const DELEGATE_RULE_KEYS = ["groups", "schema_version"];
+function hitsContract(root, keys) {
+	return keys.some((key) => root[key] !== void 0);
+}
+/** preview 失败骨架（解析失败/非对象/不合契约三处共用）。 */
+function delegatePreviewFailure() {
+	return {
+		ok: false,
+		mode: "",
+		repository: "",
+		totalFiles: 0,
+		reviewable: [],
+		excluded: [],
+		mergeBase: ""
+	};
+}
+/** 解析 `ocr delegate preview --format json` 输出。 */
+function parseDelegatePreview(text) {
+	let doc;
+	try {
+		doc = JSON.parse(text);
+	} catch {
+		return delegatePreviewFailure();
+	}
+	if (!isRecord(doc)) return delegatePreviewFailure();
+	const root = doc;
+	if (!hitsContract(root, DELEGATE_PREVIEW_KEYS)) return delegatePreviewFailure();
+	const reviewable = Array.isArray(root["reviewable_files"]) ? root["reviewable_files"].map((fileRaw) => {
+		if (!isRecord(fileRaw)) return null;
+		return {
+			path: str(fileRaw["path"]),
+			status: str(fileRaw["status"]),
+			insertions: num(fileRaw["insertions"]),
+			deletions: num(fileRaw["deletions"])
+		};
+	}).filter((fileEntry) => fileEntry !== null && fileEntry.path.length > 0) : [];
+	const excluded = Array.isArray(root["excluded_files"]) ? root["excluded_files"].map((fileRaw) => {
+		if (!isRecord(fileRaw)) return null;
+		return {
+			path: str(fileRaw["path"]),
+			reason: str(fileRaw["reason"])
+		};
+	}).filter((fileEntry) => fileEntry !== null && fileEntry.path.length > 0) : [];
+	return {
+		ok: true,
+		mode: str(root["mode"]),
+		repository: str(root["repository"]),
+		totalFiles: num(root["total_files"]) || num(root["reviewable_count"]),
+		reviewable,
+		excluded,
+		mergeBase: str(root["merge_base"])
+	};
+}
+/** 解析 `ocr delegate rule --format json` 输出。 */
+function parseDelegateRules(text) {
+	let doc;
+	try {
+		doc = JSON.parse(text);
+	} catch {
+		return {
+			ok: false,
+			groups: []
+		};
+	}
+	if (!isRecord(doc)) return {
+		ok: false,
+		groups: []
+	};
+	const root = doc;
+	if (!hitsContract(root, DELEGATE_RULE_KEYS)) 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) : []
+	};
+}
+//#endregion
+//#region lib/routing.ts
+const ROUTING_NAME = "ocr-review-routing";
+const ROUTING_ORDER = 1555;
+//#endregion
+//#region lib/provider-projection.ts
+/** llm-pi-ai 命名空间里 provider 表的字段名。 */
+const PROVIDERS_FIELD = "providers";
+/** 原始 model 对象 → DshModel（缺 id 视为无效，返回 null）。 */
+function modelFromRaw(modelRaw) {
+	if (!isRecord(modelRaw)) return null;
+	const rec = modelRaw;
+	const id = typeof rec["id"] === "string" ? rec["id"] : "";
+	if (!id) return null;
+	return {
+		id,
+		name: typeof rec["name"] === "string" && rec["name"] ? rec["name"] : id
+	};
+}
+/** 原始 provider 对象 → DshProvider（缺 baseURL 视为无效，返回 null）。 */
+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 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) : [];
+	return {
+		name,
+		displayName: typeof entry["displayName"] === "string" && entry["displayName"] ? entry["displayName"] : name,
+		apiKeyEnv,
+		protocol,
+		baseURL,
+		models
+	};
+}
+/**
+* settings 命名空间解析值 → provider 列表（纯投影，不含任何 key 值）。
+* 上游形状（settings 里 llm-pi-ai.providers.<name>）：
+*   { displayName?, apiKeyEnv?, api: openai-completions|openai-responses,
+*     baseURL, models?: [{id,name,…}] }
+* 形状不合的条目整条丢弃（读侧宽容：卡片要能打开让用户去修），写侧才 fail-loud。
+*/
+function providersFromSettingsValue(value) {
+	const providers = fieldOf(value, PROVIDERS_FIELD);
+	if (!isRecord(providers)) return [];
+	const out = [];
+	for (const [name, raw] of Object.entries(providers)) {
+		const parsed = providerFromRaw(name, raw);
+		if (parsed !== null) out.push(parsed);
+	}
+	return out;
+}
+//#endregion
+//#region lib/provider-source.ts
+/** provider 清单所在的官方 settings 命名空间（base bundle 的 pi-ai 适配器注册）。 */
+const PI_AI_NAMESPACE = "llm-pi-ai";
+const SOURCE_READY = {
+	status: "ready",
+	message: ""
+};
+/**
+* 读 provider 清单并把一切失败折进 source（不抛）：会话热路径与 webServer 端点
+* 都只消费返回值，服务缺席/抛错时卡片仍能显示原因。
+*/
+function readProviders(gateway, messages) {
+	const health = gateway.health();
+	if (!health.settings) return {
+		providers: [],
+		source: {
+			status: "settings-unavailable",
+			message: messages.sourceSettingsUnavailable
+		}
+	};
+	let descriptors;
+	try {
+		descriptors = gateway.descriptors();
+	} catch (error) {
+		return {
+			providers: [],
+			source: {
+				status: "settings-failed",
+				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
+			}
+		};
+	}
+	const hit = descriptors.find((descriptor) => descriptor.ns === PI_AI_NAMESPACE);
+	if (hit === void 0) return {
+		providers: [],
+		source: {
+			status: "namespace-unavailable",
+			message: format(messages.sourceNamespaceUnavailable, { ns: PI_AI_NAMESPACE })
+		}
+	};
+	const providers = providersFromSettingsValue(hit.value);
+	if (!health.credentials) return {
+		providers,
+		source: {
+			status: "credentials-unavailable",
+			message: messages.sourceCredentialsUnavailable
+		}
+	};
+	return {
+		providers,
+		source: SOURCE_READY
+	};
+}
+/** 逐 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);
+		return {
+			...providerCfg,
+			hasKey
+		};
+	}));
+}
+//#endregion
+//#region lib/config-store.ts
+/** api_key_cmd 脚本名（pluginDir 兜底路径的唯一拼法来源）。 */
+const GET_CRED_SCRIPT = path.join("scripts", "get-cred.mjs");
+/** 未知值 → 安全字符串（非字符串给 ''）。 */
+function strOf(value) {
+	return typeof value === "string" ? value : "";
+}
+/** 读取外部 ocr CLI config.json 的当前形态（不含 key 值）。
+*  只读侧刻意保持宽容：坏 JSON 也要能让设置卡片打开（用户正是靠卡片去修），
+*  写侧由 parseExistingConfig fail-loud——两者语义不同，不可照抄。 */
+function loadOcrConfig(configJsonText) {
+	let doc;
+	try {
+		const parsed = JSON.parse(configJsonText);
+		doc = isRecord(parsed) ? parsed : {};
+	} catch {
+		doc = {};
+	}
+	const provider = strOf(fieldOf(doc, "provider"));
+	const custom = fieldOf(doc, "custom_providers");
+	const entry = isRecord(custom) ? fieldOf(custom, provider) : void 0;
+	return {
+		current: {
+			provider,
+			model: isRecord(custom) ? strOf(fieldOf(entry, "model")) : "",
+			keyIsDynamic: isRecord(custom) && strOf(fieldOf(entry, "api_key_cmd")).length > 0,
+			url: isRecord(custom) ? strOf(fieldOf(entry, "url")) : ""
+		},
+		raw: doc
+	};
+}
+/** config.json 的当前文本（读不到/不存在一律空串，交由 loadOcrConfig 的宽容读侧处理）。 */
+function readText(configPath) {
+	try {
+		return readFileSync(configPath, "utf8");
+	} catch {
+		return "";
+	}
+}
+/** 单引号转义（api_key_cmd 内嵌命令用，模块级纯函数）。 */
+function shqDyn(value) {
+	return `'${value.replaceAll("'", String.raw`'\''`)}'`;
+}
+/** api_key_cmd 值构造：把脚本路径与 env key 名 shq 转义后拼成 shell 命令。 */
+function buildApiKeyCmd(scriptPath, envKey, messages) {
+	if (!/^[A-Z0-9_]+$/u.test(envKey)) throw new Error(format(messages.badEnvKey, { key: envKey }));
+	return `node ${shqDyn(scriptPath)} ${shqDyn(envKey)}`;
+}
+/** 现有 config 文本 → 盘面对象。
+*
+* 解析失败必须抛错而非给 `{}`：调用方（renderSelectedConfig /
+* migratePlaintextKeys）拿返回值做「保留未知键」的基准，静默变成空对象就等于
+* 把用户全部 providers/keys/mcp_servers 配置当成「不存在」写掉——一个手滑写坏
+* 的 config.json（合法场景：OCR 崩溃时留下半截文件）从此再也回不来。 */
+function parseExistingConfig(text, where, messages) {
+	if (!text.trim()) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw new Error(format(messages.configNotJson, {
+			where,
+			cause: String(error)
+		}), { cause: error });
+	}
+	if (!isRecord(parsed)) throw new Error(format(messages.configNotObject, { where }));
+	return parsed;
+}
+/**
+* 把「读 config.json → 改 → 原子写回」整段串行化。
+*
+* 为什么需要：落盘交给官方异步 `writeFileAtomic` 之后，原本同处一个
+* event-loop tick 内的读写对被拆开了——卡片的「应用 provider」与「一键迁移」并发
+* 时可以各自用旧快照覆盖对方的整份文档，最坏情况是刚迁走的明文 api_key 又被写回来。
+* 锁用官方 `dsh-atomic-write` 的 `withFileLock`（`<目标>.lock`、`wx` 独占创建、
+* 持锁进程已退出按 pid 探活接管、`finally` 删除），本仓不自制互斥件。
+* 先补一次父目录：官方件只在写目标文件时建目录，而锁文件本身就落在那个目录里，
+* 首写（目录尚不存在）时不先建就会 ENOENT。
+*/
+async function updateConfigLocked(targetPath, operation) {
+	await mkdir(path.dirname(targetPath), {
+		recursive: true,
+		mode: 448
+	});
+	return withFileLock(targetPath, operation);
+}
+/**
+* 原子写回 config.json：先留 `.bak` 备份，再交官方 `writeFileAtomic` 落盘。
+* 此前是 `writeFileSync` 直写：进程/磁盘在写入中途出问题就会留下半截配置
+* （OCR 与用户都读不到），且没有任何回滚点。rename 在同目录内是原子的。
+*
+* 随机后缀临时文件 + `wx` 独占创建、失败清临时文件、Windows rename 重试、父目录
+* 创建（`dirMode`）与新 inode 携带 `mode` 全是官方件既有行为，本仓不再手抄
+* （实测）。本地只剩 `.bak`：官方写文件面无备份语义，且备份必须落在
+* rename **之前**——挪到之后备份到的就是新内容。
+*/
+async function writeConfigAtomic(targetPath, text) {
+	const bakPath = `${targetPath}.bak`;
+	if (existsSync(targetPath)) {
+		copyFileSync(targetPath, bakPath);
+		chmodSync(bakPath, 384);
+	}
+	await writeFileAtomic(targetPath, text, {
+		mode: 384,
+		dirMode: 448
+	});
+}
+/**
+* 生成「选择 provider+model」后的 config.json 全文。
+* - provider 顶层设为目标名；custom_providers.<name> 写 url/protocol/model/
+*   api_key_cmd；同条目残留明文 api_key 清除。
+* - 目标条目上已有的其它键（extra_headers/temperature/timeout_seconds…）与
+*   其余顶层键（language/max_tokens/effort/mcp_servers…）、其它
+*   custom_providers 条目一律原样保留，绝不丢配置。
+*/
+function renderSelectedConfig(input, messages) {
+	const doc = parseExistingConfig(input.existingText, input.configLabel, messages);
+	const target = input.providers.find((providerCfg) => providerCfg.name === input.provider);
+	if (!target) throw new Error(format(messages.providerNotInList, {
+		ns: PI_AI_NAMESPACE,
+		provider: input.provider
+	}));
+	if (!(target.models.length === 0 || target.models.some((model) => model.id === input.model))) throw new Error(format(messages.modelNotInList, {
+		provider: input.provider,
+		model: input.model
+	}));
+	const customsRaw = fieldOf(doc, "custom_providers");
+	const customs = isRecord(customsRaw) ? customsRaw : {};
+	const existingRaw = fieldOf(customs, input.provider);
+	const entry = {
+		...isRecord(existingRaw) ? existingRaw : {},
+		url: target.baseURL,
+		protocol: target.protocol,
+		model: input.model,
+		api_key_cmd: input.apiKeyCmd
+	};
+	delete entry["api_key"];
+	customs[input.provider] = entry;
+	doc["provider"] = input.provider;
+	doc["custom_providers"] = customs;
+	if (input.language !== void 0) doc["language"] = input.language;
+	return `${JSON.stringify(doc, null, 2)}\n`;
+}
+/**
+* 家目录展开交官方 `expandHomePath`，只有 POSIX 上的 `~\x` 由本地拦下：官方吃
+* `~/` 与 `~\` 两条前缀，在 POSIX 上会把 `~\notes.txt` 折成 `<home>/\notes.txt`
+* ——一枚合法的反斜杠文件名，等于把用户打错的相对路径静默变成家目录里的怪文件，
+* 比现状（报"必须是绝对路径"）更坏。原样放行让它落到调用方（lib/ocr-config.ts 的
+* resolveOcrConfigPath）那道绝对性闸门去报错。
+* sep 作参数而不是就地读 `path.sep`：两个分支都要能被断言（同 plugin-hot-reload
+* 的 shellQuoted(bin, viaShell) 手法）。
+*/
+function expandHomeForSeparator(value, sep) {
+	if (sep === "/" && value.startsWith("~\\")) return value;
+	return expandHomePath(value);
+}
+/** api_key_cmd 脚本在插件目录里的固定落点（host.ts 与兜底路径共用这一处）。 */
+function defaultCredScriptPath(pluginDir) {
+	return path.join(pluginDir, GET_CRED_SCRIPT);
+}
+/** api_key_cmd 脚本落点：显式路径优先，否则按 pluginDir 兜底。 */
+function credentialScriptPath(paths) {
+	return paths.getCredScript === "" ? defaultCredScriptPath(paths.pluginDir) : paths.getCredScript;
+}
+//#endregion
+//#region lib/ocr-config.ts
+/** 外部 ocr CLI 的默认配置目录/文件名（宿主服务管不到，只能由本包直读直写）。 */
+const OCR_CONFIG_DIR = ".opencodereview";
+const OCR_CONFIG_FILE = "config.json";
+/** 无凭据可问时的一律 false（卡片据 source 显示原因，不显示假的「未配置 key」）。 */
+function withoutKeyFlags(providers) {
+	return providers.map((providerCfg) => ({
+		...providerCfg,
+		hasKey: false
+	}));
+}
+/**
+* OCR 配置文件路径：设置项 ocrConfigPath 覆盖，未覆盖时按 os.homedir() 派生。
+* 家目录展开交官方 `expandHomePath`，但本地保留两条它没有的判据（见
+* `expandHomeForSeparator` 与下面的绝对性闸门）：直写相对路径会把配置落到
+* 「当时的工作区」，用户找不到也修不了。
+*/
+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 }));
+	return expanded;
+}
+/**
+* 组装设置页数据（绝不返回 key 明文；credentials 缺席时 hasKey 全 false 并给出原因，
+* 让卡片显示「为什么不可用」而不是假装每个 provider 都没配 key）。
+*/
+async function providersForCard(gateway, paths, messages) {
+	const { providers, source } = readProviders(gateway, messages);
+	const keyed = source.status === "ready" ? await markKeyFlags(gateway, providers) : withoutKeyFlags(providers);
+	const { current } = loadOcrConfig(readText(paths.ocrConfigJson));
+	return {
+		providers: keyed,
+		current,
+		getCredReady: existsSync(credentialScriptPath(paths)),
+		source
+	};
+}
+/**
+* 应用选择：官方通道取 provider 清单 → 校验 key 可解析 → 生成新配置 → 写回（0600）。
+* 任何一步不合条件都抛可读错误（webServer 端点兜成 400，卡片显示原因）。
+*/
+async function applyProviderSelection(gateway, paths, selection, messages) {
+	const { provider, model } = selection;
+	const { providers, source } = readProviders(gateway, messages);
+	if (source.status !== "ready") throw new Error(source.message);
+	const target = providers.find((providerCfg) => providerCfg.name === provider);
+	if (!target) throw new Error(format(messages.providerNotInList, {
+		ns: PI_AI_NAMESPACE,
+		provider
+	}));
+	if (target.apiKeyEnv === null || target.apiKeyEnv === "") throw new Error(format(messages.noApiKeyEnv, { provider }));
+	if (!await gateway.credentialResolvable(target.apiKeyEnv)) throw new Error(format(messages.keyNotResolvable, {
+		provider,
+		ref: target.apiKeyEnv
+	}));
+	const scriptPath = credentialScriptPath(paths);
+	if (!existsSync(scriptPath)) throw new Error(format(messages.credScriptMissing, { path: scriptPath }));
+	const apiKeyCmd = buildApiKeyCmd(scriptPath, target.apiKeyEnv, messages);
+	await updateConfigLocked(paths.ocrConfigJson, async () => {
+		const next = renderSelectedConfig({
+			existingText: readText(paths.ocrConfigJson),
+			configLabel: paths.ocrConfigJson,
+			providers,
+			provider,
+			model,
+			apiKeyCmd,
+			...selection.language === void 0 ? {} : { language: selection.language }
+		}, messages);
+		await writeConfigAtomic(paths.ocrConfigJson, next);
+	});
+	return {
+		provider: target.name,
+		model,
+		url: target.baseURL,
+		protocol: target.protocol
+	};
+}
+/**
+* 迁移单条 custom provider 条目：有明文 api_key 且能找到 envKey → 改写入
+* api_key_cmd 并删除明文，返回 'migrated'；找不到 envKey 或构造命令失败 →
+* 'unknown'；无明文 → 'noPlain'（不动作）。
+*/
+function migrateEntry(entry, envKey, scriptPath, 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);
+	} catch {
+		return "unknown";
+	}
+	delete entry["api_key"];
+	return "migrated";
+}
+/**
+* 迁移：把自定义 provider 条目里的明文 api_key 改为 api_key_cmd（动态读凭据）。
+* api_key_cmd 优先于 api_key，因此清除明文即可。
+* 对「明文 api_key + 无 api_key_cmd」的条目，依据 settings 里该 provider 的
+* apiKeyEnv 补充命令；settings 里找不到的 provider 不动（不破坏既有配置），
+* 在返回信息里说明。credentials 缺席不阻断本操作（它只要 name→apiKeyEnv 映射），
+* settings 侧读不到则抛错——那正是「不知道该写哪条命令」的状态，静默跳过会让用户
+* 以为迁移过了。
+* 返回 { migrated: string[]; skippedUnknown: string[] }。
+*/
+async function migratePlaintextKeys(gateway, paths, messages) {
+	const precheck = readText(paths.ocrConfigJson);
+	if (!precheck.trim()) return {
+		migrated: [],
+		skippedUnknown: []
+	};
+	const { providers, source } = readProviders(gateway, messages);
+	if (source.status !== "ready" && source.status !== "credentials-unavailable") throw new Error(source.message);
+	parseExistingConfig(precheck, paths.ocrConfigJson, messages);
+	const scriptPath = credentialScriptPath(paths);
+	if (!existsSync(scriptPath)) return {
+		migrated: [],
+		skippedUnknown: []
+	};
+	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 () => {
+		const doc = parseExistingConfig(readText(paths.ocrConfigJson), paths.ocrConfigJson, messages);
+		const customsRaw = fieldOf(doc, "custom_providers");
+		if (!isRecord(customsRaw)) return {
+			migrated: [],
+			skippedUnknown: []
+		};
+		const customs = customsRaw;
+		const migrated = [];
+		const skippedUnknown = [];
+		for (const [name, raw] of Object.entries(customs)) if (isRecord(raw)) {
+			const result = migrateEntry(raw, envByProvider.get(name), scriptPath, messages);
+			if (result === "migrated") migrated.push(name);
+			else if (result === "unknown") skippedUnknown.push(name);
+		}
+		if (migrated.length === 0) return {
+			migrated,
+			skippedUnknown
+		};
+		await writeConfigAtomic(paths.ocrConfigJson, `${JSON.stringify(doc, null, 2)}\n`);
+		return {
+			migrated,
+			skippedUnknown
+		};
+	});
+}
+//#endregion
+//#region host.ts
+const PLUGIN_DIR = import.meta.dirname;
+const MAX_TIMEOUT_REQUEST_MS = 2147483647;
+const LLM_TEST_TIMEOUT_MS = 9e4;
+const STDOUT_MAX_BYTES = 4e5;
+/** 解析失败时回显给模型的原始内容长度上限（UTF-16 码元；已脱敏）。
+*  单位写码元而不是"字符"：本常量喂给 `echoRaw`→`truncateEnd`，那一刀按码元数计
+*  （一张 emoji = 2 枚），写"字符"会把给模型的说明夸大约一倍。 */
+const RAW_ECHO_LIMIT = 500;
+const BODY_MAX_BYTES = 8192;
+/** 评论截断条数的内置默认（旧 BUILTIN_BASE 的那一项）：schema 的 `.default()` 与
+*  「读到坏值时的回退」（readMaxComments）共用这一个数，两处不许各写一份字面量。 */
+const MAX_COMMENTS_DEFAULT = 12;
+/** 会话内 CSRF token 头名（与 lesson-loop/zvec-grep 同族命名）。 */
+const OCR_CSRF_HEADER = "x-ocr-csrf";
+const PROVIDERS_PATH = "/_dsh/ocr-review/providers";
+const SELECT_PATH = "/_dsh/ocr-review/select";
+const MIGRATE_PATH = "/_dsh/ocr-review/migrate";
+const TEST_PATH = "/_dsh/ocr-review/test";
+/** 官方注册表里本包作业的 kind；宿主据此签发的 id 形如 `ocr-review-N`。 */
+const OCR_JOB_KIND = "ocr-review";
+/**
+* 后台评审的兜底上限。本包刻意不套宿主 timeoutMs（`onExpiry: "none"`：外部 CLI 的正常
+* 时长跨度太大，套了就等于替用户砍掉长评审），但换装后"完全没有终点"有了新的受害者——
+* 未拥有作业共用一只 10 格的桶（实测 `running` 与 `stopping` 都计数，满员是**拒绝**
+* 后来的 start），一条挂死的 CLI 会永久占一格，连别的插件也起不来。2 小时远超正常评审，
+* 到点经注册表收：记录推到 stopping，理由落进模型可见的 detail。
+*/
+const OCR_BACKGROUND_MAX_MS = 72e5;
+/** "仍在跑"的两枚官方状态：`stopping` 是取消已发出、进程还没收完。 */
+function isLiveOcrStatus(status) {
+	return status === "running" || status === "stopping";
+}
+/**
+* 剪掉本 kind 最老的已落定记录，给下一次登记腾出窗口（注册表按登记序返回，故取头部）。
+* 在跑与正在收的一条不动：官方件对活作业的 remove 直接抛，而"静默杀掉用户发起的评审"
+* 正是这次换装要消灭的形态。
+* @param jobs 官方注册表
+* @returns {void}
+*/
+function pruneOcrJobHistory(jobs) {
+	const settled = jobs.list().filter((job) => job.kind === OCR_JOB_KIND && !isLiveOcrStatus(job.status));
+	const excess = settled.length - 9;
+	for (const job of settled.slice(0, Math.max(excess, 0))) jobs.remove(job.id);
+}
+/**
+* 在 controller 闸门下起一条未拥有作业，起完立刻摘掉。
+*
+* 实测：挂上即放行、摘掉即恢复"没有 controller 服务这个 owner"的拒绝、可反复；而 global 层
+* 那串 token 只被 `servesOwner` 读（installed dsh-jobs-local 全文唯一消费点），作业后续的
+* read/kill/落定都不依赖它。所以常驻一枚等于在"宿主故意没装 job 工具"的组成里替全宿主
+* 开着那道闸门——官方契约写的是"生产者不能起一台 owner 收不掉、停不掉的作业"。
+*/
+function startUnderOcrController(jobs, spec) {
+	const detach = jobs.attachController("ocr-review: background");
+	try {
+		return jobs.start(spec);
+	} finally {
+		detach();
+	}
+}
+/**
+* 等到兜底 deadline 到点，然后把仍在跑的那条经注册表收掉。
+*
+* 用注册表自己的 `wait(id, ms)` 而不是宿主 timer，也不是裸 `setTimeout`：前者要把
+* `timer` 写进 HostCtx 的**必需**服务面（装载守卫一扩，没装那件的宿主连前台评审都装载
+* 不了），后者会活过插件卸载。实测 `wait` 只等不杀、作业一落定就解掉它内部的定时器，
+* 也不推进输出游标（模型侧 job_output 的读数不受影响）——所以落定时这里看一眼状态就返回。
+* @param jobs 官方注册表
+* @param id 这次后台评审的作业 id
+* @param reason 到点回收时写进模型可见 detail 的理由
+* @returns 等完这一条的兜底窗口；抛错一律就地收敛（记录没了就等于无事可做）
+*/
+async function enforceOcrDeadline(jobs, id, reason, backgroundMaxMs) {
+	try {
+		if ((await jobs.wait(id, backgroundMaxMs)).status === "running") jobs.kill(id, void 0, reason);
+	} catch {}
+}
+/**
+* 卸载时收掉本包仍在跑（或正在收尾）的作业。
+*
+* 注册表随宿主活着，不会因为我们卸载而杀进程：一条留在 `running` 的 OCR 既继续占着未拥有
+* 那一桶的容量位（实测满员是拒绝别人的 start），又没人再等它的输出。遍历的是注册表的
+* `list()` 而不是本包记的账——本包不留常驻状态，跨会话/跨 fiber 起的作业也要能被收掉。
+* @param jobs 官方注册表
+* @param reason 写进模型可见 detail 的理由（双语字典取）
+* @returns {void}
+*/
+function reclaimOcrJobs(jobs, reason) {
+	const mine = jobs.list().filter((job) => job.kind === OCR_JOB_KIND);
+	for (const job of mine) if (isLiveOcrStatus(job.status)) jobs.kill(job.id, void 0, reason);
+	else jobs.remove(job.id);
+}
+/** 当前会话工作区（repo 缺省回退源）；非字符串视为缺。
+*  官方形状：`agent?: Agent` → `session: Session` → `header: SessionHeader` →
+*  `cwd?: string`。下面的逐层 `?.` 与 `typeof` 复核是跨进程契约的运行时闸：宿主半装配
+*  递来的 agent 可能是 `null`、也可能没有 `session`/`header`（test/host.test.ts 钉住
+*  这两条 fail-closed 路径），值一律经 `unknown` 读，绝不只信声明。 */
+function sessionHeaderCwd(exec) {
+	const raw = exec.agent?.session?.header?.cwd;
+	return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+}
+/** 服务面校验：对象存在且声明的方法全部可调用。
+*  只做 `typeof value["shell"] === "object"` 的话，守卫声称的是「有 shell 服务」
+*  而实际证明的只是「有个对象」——运行到一半才炸。逐个点名方法，守卫才名副其实
+*  （HostCtx 用到的每个方法都在这里被验证过一遍）。 */
+function hasMethods(value, methods) {
+	if (!isRecord(value)) return false;
+	for (const method of methods) if (typeof value[method] !== "function") return false;
+	return true;
+}
+/** host 是否为本插件所需服务面（settings/shell/tools/systemPrompt/get/inject 及
+*  其上要调用的方法）。守卫仅压缩类型面、避开 `as unknown as HostCtx` 断言。
+*  settings 这里点名的两个方法都会被调用：configure 登记本页的页面策略、describe
+*  跨命名空间读（provider 清单 + 官方 locale 偏好）；inject 挂那条页面策略的 effect。
+*  0.1.7 起 settings 再无 register/get，多点名一个就是永不成立的死分支。 */
+function isOcrReviewHost(value) {
+	if (!isRecord(value)) return false;
+	const { settings, shell, tools, systemPrompt, inject, get } = value;
+	return hasMethods(settings, ["configure", "describe"]) && hasMethods(shell, ["resolve", "execute"]) && hasMethods(tools, ["register"]) && hasMethods(systemPrompt, ["section"]) && typeof inject === "function" && typeof get === "function";
+}
+/** 从插件 Context 解析宿主服务面（守卫收窄，不做 `as unknown as` 断言）。 */
+function resolveHost(ctx) {
+	if (!isOcrReviewHost(ctx)) throw new Error("ocr-review: 宿主缺少所需的 shell/tools/settings/systemPrompt/inject 服务界面（或其方法）");
+	return ctx;
+}
+/** describe() 行里按命名空间取解析值（0.1.7 的跨命名空间读只有 describe() 一条路：
+*  `settings.get(ns)` 已删）。未注册该命名空间 → undefined，调用侧按默认值降级。
+*  @param rows - `ctx.settings.describe()` 的返回（全部条目的表单投影）。
+*  @param ns - 要读的命名空间（官方字段名是 `ns`，上游有改名 namespace 的 TODO）。
+*/
+function describedValue(rows, ns) {
+	return rows.find((row) => row.ns === ns)?.value;
+}
+/**
+* 取本包 host 侧文案（按官方 locale 偏好现取现用）：设置页「常规」里换语言后，
+* 下一次工具调用/端点请求即换新文案，不需要重启或重装插件。
+* locale 命名空间未注册（无官方 client-locale 包）→ describe() 里没有这条 →
+* undefined → 中文默认。
+*/
+function localeMessages(host) {
+	const preference = describedValue(host.settings.describe(), LOCALE_SETTINGS_NAMESPACE);
+	return messagesFor(MESSAGES, resolveLocalePreference(preference));
+}
+/**
+* render 只做 model-facing 展示：把 canonical value 本身 pretty-print 成文本块。
+* execute 直返结构化对象（不再 stringify 进 `{ text }`），所以这里 stringify 的是
+* 第一层也是唯一一层 JSON；循环结构/不可序列化值的两级兜底是防御，不是常规路径。
+*/
+function textBlock(value) {
+	let text;
+	try {
+		const json = JSON.stringify(value, null, 2);
+		text = typeof json === "string" ? json : String(value);
+	} catch {
+		try {
+			text = String(value);
+		} catch {
+			text = "[unrenderable value]";
+		}
+	}
+	return [{
+		type: "text",
+		text
+	}];
+}
+/** 可空 string 字段的 schema 片段（官方子集单类型，null 分支用 oneOf 表达）。 */
+const NULLABLE_STRING = { oneOf: [{ type: "string" }, { type: "null" }] };
+/** ocr_review / ocr_scan 的输出：wait=false = 后台回执对象；前台成功 = 摘要对象；
+*  前台解析失败 = 一段诚实的说明字符串。三者恰一（required 逐字段声明保证两个
+*  对象分支互斥）。 */
+const REVIEW_OUTPUT_SCHEMA = { oneOf: [
+	{
+		type: "object",
+		additionalProperties: false,
+		required: [
+			"started",
+			"mode",
+			"tool",
+			"repo",
+			"processStatus",
+			"polling"
+		],
+		properties: {
+			started: {
+				type: "boolean",
+				const: true
+			},
+			mode: {
+				type: "string",
+				const: "background"
+			},
+			tool: { type: "string" },
+			repo: { type: "string" },
+			processStatus: {
+				type: "string",
+				enum: [
+					"running",
+					"completed",
+					"killed"
+				]
+			},
+			polling: { type: "string" }
+		}
+	},
+	{
+		type: "object",
+		additionalProperties: false,
+		required: [
+			"status",
+			"skipped",
+			"message",
+			"summary",
+			"sessionId",
+			"aggregation",
+			"totalCommentCount",
+			"droppedCount",
+			"invalidCommentCount",
+			"topComments",
+			"warnings",
+			"hint"
+		],
+		properties: {
+			status: {
+				type: "string",
+				enum: [
+					"success",
+					"complete",
+					"completed_with_warnings",
+					"completed_with_errors",
+					"skipped"
+				]
+			},
+			skipped: { type: "boolean" },
+			message: NULLABLE_STRING,
+			summary: { oneOf: [{ type: "null" }, {
+				type: "object",
+				additionalProperties: false,
+				required: [
+					"filesReviewed",
+					"comments",
+					"totalTokens",
+					"inputTokens",
+					"outputTokens",
+					"elapsed"
+				],
+				properties: {
+					filesReviewed: { type: "number" },
+					comments: { type: "number" },
+					totalTokens: { type: "number" },
+					inputTokens: { type: "number" },
+					outputTokens: { type: "number" },
+					elapsed: { type: "string" }
+				}
+			}] },
+			sessionId: NULLABLE_STRING,
+			aggregation: {
+				type: "object",
+				additionalProperties: false,
+				required: [
+					"total",
+					"bySeverity",
+					"byCategory"
+				],
+				properties: {
+					total: { type: "integer" },
+					bySeverity: {
+						type: "object",
+						additionalProperties: false,
+						required: [
+							"critical",
+							"high",
+							"medium",
+							"low"
+						],
+						properties: {
+							critical: { type: "integer" },
+							high: { type: "integer" },
+							medium: { type: "integer" },
+							low: { type: "integer" }
+						}
+					},
+					byCategory: { type: "object" }
+				}
+			},
+			totalCommentCount: { type: "integer" },
+			droppedCount: { type: "integer" },
+			invalidCommentCount: { type: "integer" },
+			topComments: {
+				type: "array",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					required: [
+						"location",
+						"severity",
+						"category",
+						"content",
+						"suggestion"
+					],
+					properties: {
+						location: { type: "string" },
+						severity: { type: "string" },
+						category: { type: "string" },
+						content: { type: "string" },
+						suggestion: NULLABLE_STRING
+					}
+				}
+			},
+			warnings: {
+				type: "array",
+				items: { type: "string" }
+			},
+			hint: { type: "string" }
+		}
+	},
+	{ type: "string" }
+] };
+/** ocr_delegate_preview：成功 = 清单对象；解析失败 = 说明字符串。 */
+const PREVIEW_OUTPUT_SCHEMA = { oneOf: [{
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"mode",
+		"repository",
+		"reviewableCount",
+		"insertions",
+		"deletions",
+		"reviewableFiles",
+		"excludedFiles",
+		"hint"
+	],
+	properties: {
+		mode: { type: "string" },
+		repository: { type: "string" },
+		reviewableCount: { type: "integer" },
+		insertions: { type: "number" },
+		deletions: { type: "number" },
+		reviewableFiles: {
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				required: [
+					"path",
+					"status",
+					"insertions",
+					"deletions"
+				],
+				properties: {
+					path: { type: "string" },
+					status: { type: "string" },
+					insertions: { type: "number" },
+					deletions: { type: "number" }
+				}
+			}
+		},
+		excludedFiles: {
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				required: ["path", "reason"],
+				properties: {
+					path: { type: "string" },
+					reason: { type: "string" }
+				}
+			}
+		},
+		hint: { type: "string" }
+	}
+}, { type: "string" }] };
+/** ocr_delegate_rule：成功 = 分组对象；解析失败 = 说明字符串。 */
+const RULES_OUTPUT_SCHEMA = { oneOf: [{
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"groupCount",
+		"groups",
+		"hint"
+	],
+	properties: {
+		groupCount: { type: "integer" },
+		groups: {
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				required: [
+					"source",
+					"pattern",
+					"files",
+					"rule"
+				],
+				properties: {
+					source: { type: "string" },
+					pattern: { type: "string" },
+					files: {
+						type: "array",
+						items: { type: "string" }
+					},
+					rule: { type: "string" }
+				}
+			}
+		},
+		hint: { type: "string" }
+	}
+}, { type: "string" }] };
+/** ocr_session：sessionOutput 本身就是一手透传的字符串（诚实的值），外层仍是对象
+*  好让 hint 有处安放。 */
+const SESSION_OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	required: ["sessionOutput", "hint"],
+	properties: {
+		sessionOutput: { type: "string" },
+		hint: { type: "string" }
+	}
+};
+/** 失败详情：stderr 优先、空则退 stdout；先脱敏再截断（明文 key 绝不进工具错误
+*  ——错误文本会被持久化进会话日志）。省略标记是文案，故脱敏与截断的位置不变，
+*  只把中间的连接标记换成当前语言的那一份。两半各用一个函数，因为它们是两种缺陷：
+*  前切点会留下孤立**高**代理（`truncateEnd` 丢掉它），后切点会留下孤立**低**代理
+*  （`truncateStart` 丢掉它）。把两个函数对调同样不留孤立代理，只是头尾内容掉头
+*  ——故 test/host.test.ts 里另有一组哨兵断言钉住顺序。 */
+function failureDetail(result, messages) {
+	const detail = redactKeyMaterial(result.stderr.text === "" ? result.stdout.text : result.stderr.text);
+	return detail.length <= 800 ? detail : `${truncateEnd(detail, 400)}${messages.middleEllipsis}${truncateStart(detail, 400)}`;
+}
+/** 前台执行：失败抛错（含给模型的行动提示），成功返回 stdout 文本。
+* timeoutMs 恒有值（tuningOf(config)），宿主按 min(请求, shell.maxTimeoutMs) 收口。
+* signal 必传：harness ToolExecution.signal 是必填的调用方取消权。 */
+async function runForeground(host, command, workdir, run, signal) {
+	const messages = localeMessages(host);
+	const spec = host.shell.resolve({
+		command,
+		workdir,
+		timeoutMs: run.timeoutMs,
+		stdoutMaxBytes: run.stdoutMaxBytes,
+		signal
+	});
+	const result = await (await host.shell.execute(spec)).result();
+	if (result.exitCode !== 0 || result.timedOut || result.aborted) {
+		if (result.timedOut) {
+			const minutes = Math.round(run.timeoutMs / 6e4);
+			throw new Error(format(messages.execTimedOut, { minutes: String(minutes) }));
+		}
+		if (result.aborted) throw new Error(messages.execAborted);
+		if (result.exitCode === 127) throw new Error(messages.execNotFound);
+		const detail = failureDetail(result, messages);
+		const head = format(messages.execFailed, { exitCode: String(result.exitCode) });
+		throw new Error(detail === "" ? head : `${head}${messages.detailSeparator}${detail}`);
+	}
+	const { text, truncated, spillPath } = result.stdout;
+	if (truncated) {
+		const spill = typeof spillPath === "string" ? format(messages.outputSpill, { path: spillPath }) : "";
+		return `${text}\n${format(messages.stdoutTruncated, {
+			limit: String(run.stdoutMaxBytes),
+			spill
+		})}`;
+	}
+	return text;
+}
+/**
+* 终止 OCR 进程，忽略"已经没有必要杀"的那一类异常（进程自然退出、已被注册表或宿主回收）。
+*
+* 这层兜不是风格：官方契约明写生产者的 `cancel` 会往上抛（installed
+* `dsh-jobs/lib/types/types.d.ts:98-102` "throws propagate"），而 `killJob` 裸调
+* `job.cancel(reason)`、只有 teardown 那一臂逐条 try/catch（同包 `lib/index.js:611-622`
+* 对照 `:805-824`）。本包的 `cancel` 是从 `AbortSignal` 监听器里被回调的，Node 对监听器
+* 抛出的处理是 `process.nextTick(() => { throw err })` ⇒ **未捕获异常、宿主进程退出**
+* （本机实跑复现）。一次取消杀掉整个 dsh 不是可接受的失败形态。
+*/
+function killProc(proc) {
+	try {
+		proc.kill();
+	} catch {}
+}
+/**
+* 进程的两条流作为注册表 pull source（与宿主 bash 工具的 processSources 同一形状）。
+* 交给注册表按它自己的节奏泵 ⇒ 没人来看时输出也照样进环；dsh-shell 的 `observed` 是
+* **非消费**的按偏移读，与 `readOutput()` 的游标互不争夺（installed
+* dsh-shell/lib/types/types.d.ts:196-203）。
+*
+* 外面再兜一道：官方泵对"源抛错"的答法是**此后不再排这一路**（实测——作业照样落定，
+* 但后续增量一条都不进环，环上一个标记也没有）。所以这里把抛错翻译成"游标原地不动 +
+* 一次性说明"：读得回来时下一拍照常续读，读不回来模型至少知道这段不可靠。说明只写一次，
+* 免得每拍 150ms 把同一句话灌进环里。
+*/
+function reviewSources(proc, messages) {
+	const source = (channel) => {
+		let failed = false;
+		return {
+			channel,
+			read: (fromByte) => {
+				if (failed) return {
+					text: "",
+					nextOffset: fromByte,
+					lossy: true
+				};
+				try {
+					return proc.observed[channel].readFrom(fromByte);
+				} catch {
+					failed = true;
+					return {
+						text: messages.jobOutputGap,
+						nextOffset: fromByte,
+						lossy: true
+					};
+				}
+			}
+		};
+	};
+	return [source("stdout"), source("stderr")];
+}
+/**
+* 作业生产者的 `done`：等子进程落定，再把终态折算成注册表结局。
+* 注册表在 `start` 那一刻就要拿到这个 Promise，所以由 async 函数现造一个，
+* 而不是在 spec 字面量里挂 `.then`（本仓口径见 lint 基线 `promise/prefer-await-to-then`）。
+*/
+async function outcomeWhenSettled(proc) {
+	await proc.done;
+	return jobOutcomeOf(proc);
+}
+/** 子进程落定后摘掉 abort 监听：fire-and-forget 的一臂，等的是收尾而不是启动。 */
+async function detachWhenSettled(proc, detach) {
+	await proc.done;
+	detach();
+}
+/**
+* 后台启动：resolve 显式带 `onExpiry: "none"`，故不套宿主 deadline（0.1.7 起
+* bash-local 缺省是 'kill'，不传就会被缺省 timeoutMs 杀掉），启动准备完成即返回，不等
+* 运行结束、不写 --output。结果以 OCR 会话记录为准（增量落盘），由模型经
+* ocr_session 工具轮询。dsh 无论优雅退出（teardown 组 TERM→KILL）还是硬退出
+* （kill -9/崩溃后被 launchd 收养），命令里的宿主回收守护（cli.ts
+* wrapWithHostReaper）都会把 OCR 一并结束，不留孤儿进程烧 token。
+*
+* 那次子进程现在同时是一枚**官方作业**（kind `ocr-review`）：官方 `job_list` /
+* `job_output` / `job_kill` 从此看得见它，本包不再需要为"起完就没人管"负责。
+* 工具的返回值是下面的结构化回执对象（canonical 值直返；作业面换装只动了"谁能看见
+* 并停掉它"，这份回执的内容自此未变——变的只是不再包一层 `{ text }` 字符串）。
+*
+* 取消语义（此前句柄被直接丢弃 → 工具调用被中止后外部 CLI 仍在跑）：
+*  - spec 带 signal：取消落在「启动准备阶段」时由宿主直接拒绝启动；
+*  - 已拿到句柄后 abort：经注册表 `kill(id, undefined, reason)` 收，它把记录推到
+*   stopping、把 reason 落进 detail，再回调本包的 `cancel()` 去杀进程；
+*  - 进程自然落定（done 永不 reject）后摘掉 abort 监听，不在长会话里堆监听器。
+* `kill` 的 reason 只在这一处带：注册表在 killed 时会把同一个 reason 追加进 detail，
+* 生产者的 `done` 结局再带一遍就是把同一句写两遍（`jobOutcomeOf` 因此刻意不带）。
+*
+* @param host 宿主服务面
+* @param job 这次后台评审的描述
+* @param signal 工具调用的中止信号
+* @returns 后台启动回执（canonical 对象，模型侧契约）
+*/
+async function startBackground(host, job, signal) {
+	const registry = host.get("jobs");
+	if (registry === void 0) throw new Error("background review unavailable: the host provides no ctx.jobs (load @deepseek-ai/dsh-jobs-local); run it with wait:true instead");
+	const spec = host.shell.resolve({
+		command: job.command,
+		workdir: job.workdir,
+		onExpiry: "none",
+		stdoutMaxBytes: job.stdoutMaxBytes,
+		signal
+	});
+	const proc = await host.shell.execute(spec);
+	pruneOcrJobHistory(registry);
+	const messages = localeMessages(host);
+	let jobId;
+	try {
+		jobId = startUnderOcrController(registry, {
+			kind: OCR_JOB_KIND,
+			label: `${job.tool} ${job.repo}`,
+			output: reviewSources(proc, messages),
+			run: () => ({
+				cancel: () => {
+					killProc(proc);
+				},
+				done: outcomeWhenSettled(proc)
+			})
+		});
+	} catch (error) {
+		killProc(proc);
+		throw error;
+	}
+	enforceOcrDeadline(registry, jobId, messages.jobReasonTimeout, job.backgroundMaxMs);
+	const stop = () => {
+		try {
+			registry.kill(jobId, void 0, messages.jobReasonAborted);
+		} catch {
+			killProc(proc);
+		}
+	};
+	const detach = () => {
+		signal.removeEventListener("abort", stop);
+	};
+	if (signal.aborted) stop();
+	else {
+		signal.addEventListener("abort", stop, { once: true });
+		detachWhenSettled(proc, detach);
+	}
+	return {
+		started: true,
+		mode: "background",
+		tool: job.tool,
+		repo: job.repo,
+		processStatus: proc.status,
+		polling: messages.backgroundPolling
+	};
+}
+/** 只收集不抛错（llm test 等需要展示原始失败的命令）。输出必先脱敏（直通卡片）。 */
+async function runCollect(host, command, workdir, run) {
+	const spec = host.shell.resolve({
+		command,
+		workdir,
+		timeoutMs: run.timeoutMs,
+		stdoutMaxBytes: run.stdoutMaxBytes
+	});
+	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}`;
+	return {
+		exitCode: result.exitCode,
+		output: truncateEnd(redactKeyMaterial(joined), 8e3)
+	};
+}
+function readEffort(config) {
+	const raw = config.effort.get();
+	return raw === "low" || raw === "high" ? raw : "medium";
+}
+function readLanguage(config) {
+	const lang = config.language.get();
+	return typeof lang === "string" && (lang === "中文" || lang === "English") ? lang : void 0;
+}
+function readAutoVerify(config) {
+	return config.autoVerify.get() !== false;
+}
+function readMaxComments(config) {
+	const raw = config.maxComments.get();
+	const num = typeof raw === "number" ? raw : Number(raw);
+	if (Number.isSafeInteger(num) && num >= 0) return num;
+	return MAX_COMMENTS_DEFAULT;
+}
+/**
+* 外层墙钟超时（分钟）→ 实际请求毫秒。0/未设置 = 请求宿主上限（宿主按
+* min(请求, shell.maxTimeoutMs) 收口，见 MAX_TIMEOUT_REQUEST_MS 注释）；
+* >0 = 指定分钟（同样被宿主 clamp）。非法值按 0 处理。
+*/
+function readTimeoutMinutes(config) {
+	const raw = config.timeoutMinutes.get();
+	const num = typeof raw === "number" ? raw : Number(raw);
+	if (Number.isSafeInteger(num) && num > 0) return num * 6e4;
+	return MAX_TIMEOUT_REQUEST_MS;
+}
+/** 一次前台执行的两枚部署值：墙钟每次现读（`timeoutMinutes` 是 volatile 设置项），
+*  stdout 上限取 entry config（非 volatile，装载期定值）。 */
+function tuningOf(config) {
+	return {
+		timeoutMs: readTimeoutMinutes(config),
+		stdoutMaxBytes: config.stdoutMaxBytes
+	};
+}
+/** parameters.required 的读取（本插件自己写的 schema，但门缺一即放行 = 副作用
+*  照跑，故不合形态就抛错，绝不静默当「无必填」）。 */
+function requiredKeys(parameters, messages) {
+	const raw = parameters["required"];
+	if (raw === void 0) return [];
+	if (!Array.isArray(raw)) throw new TypeError(messages.requiredNotArray);
+	const out = [];
+	for (const key of raw) {
+		if (typeof key !== "string") throw new TypeError(messages.requiredItemNotString);
+		out.push(key);
+	}
+	return out;
+}
+/** 宿主对工具入参零校验（execute 收原始 arguments）→ 非对象入参必须当场拒绝，
+*  否则 spread / 必填门都会按「缺省」语义静默跑一次真实评审。 */
+function execArgs(args, name, messages) {
+	if (!isRecord(args)) throw new TypeError(format(messages.argsMustBeObject, {
+		name,
+		received: Array.isArray(args) ? "array" : typeof args
+	}));
+	return args;
+}
+function define(host, spec) {
+	const { name, description, parameters, schema, run } = spec;
+	const required = requiredKeys(parameters, localeMessages(host));
+	host.tools.register({
+		name,
+		description,
+		parameters,
+		output: {
+			schema,
+			render: (_args, value) => textBlock(value)
+		},
+		execute: async (args, exec) => {
+			const messages = localeMessages(host);
+			const values = execArgs(args, name, messages);
+			const missing = required.filter((key) => values[key] === void 0);
+			if (missing.length > 0) throw new Error(format(messages.missingRequiredArgs, {
+				name,
+				keys: missing.join(", ")
+			}));
+			return assertToolOutput(schema, await run(values, exec), name, messages);
+		}
+	});
+}
+/** body 文本 → JSON 对象（空 body = {}；非对象抛错）。 */
+function parseJsonBody(text, messages) {
+	if (text.trim() === "") return {};
+	const parsed = JSON.parse(text);
+	if (!isRecord(parsed)) throw new Error(messages.bodyMustBeObject);
+	return parsed;
+}
+/**
+* POST 端点统一前置：405 → 跨域 → CSRF → body 上限（shared.guardBody）。
+*
+* 此前只有 sec-fetch-site（curl/本地进程可伪造头，且空头直通），而写端点会改
+* ~/.opencodereview/config.json；/migrate 与 /test 甚至从不读 body——keep-alive
+* 连接上未读尽的请求体会把残余字节留给后续响应，且超限请求可以一直占内存。
+* 返回 null 表示已就地响应，调用方必须立即返回。
+*/
+async function guardPost(req, res, csrf) {
+	if (req.method !== "POST") {
+		res.setHeader("Allow", "POST");
+		sendJson(res, 405, {
+			ok: false,
+			error: "POST only"
+		});
+		return null;
+	}
+	return await guardBody(req, res, {
+		maxBytes: BODY_MAX_BYTES,
+		csrf: {
+			token: csrf,
+			headerName: OCR_CSRF_HEADER
+		}
+	});
+}
+/** 原始输出回显给模型/卡片前的两道收口：截断 + 明文 key 脱敏。 */
+function echoRaw(text, limit) {
+	return redactKeyMaterial(truncateEnd(text, limit));
+}
+/** 读 --output 落盘结果。OCR exit 0 却没写出文件（版本漂移/被中途 kill）时给
+*  可行动的错误，而不是把裸 ENOENT 栈丢给模型。 */
+function readOutFile(outPath, messages) {
+	try {
+		return readFileSync(outPath, "utf8");
+	} catch (error) {
+		throw new Error(format(messages.outputFileMissing, {
+			path: outPath,
+			cause: errorText(error)
+		}), { 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，
+* 语言随设置页偏好走）；OCR 侧语义见 shared_flags.go:52-58 与 scan_cmd.go:231-236。
+*/
+function tuningParams(messages, unit) {
+	const of = (template) => ({
+		type: "integer",
+		description: format(template, { unit })
+	});
+	return {
+		concurrency: of(messages.tuningConcurrency),
+		timeoutMinutes: of(messages.tuningTimeout),
+		maxTools: of(messages.tuningMaxTools),
+		maxTokens: of(messages.tuningMaxTokens),
+		maxTokensBudget: {
+			type: "integer",
+			description: messages.tuningMaxTokensBudget
+		}
+	};
+}
+/** settings 命名空间与 loader 行 config 共用同一 schema（单源，防漂移）。
+*  值名退避为 configSchema：避免与同名 interface Config 触发 no-redeclare；
+*  外部仍以 `Config` 名导入（export as），公开 API 不变。 */
+const configSchema = Schema.object({
+	effort: Schema.union([
+		"low",
+		"medium",
+		"high"
+	]).default("medium").volatile(),
+	language: Schema.union(["中文", "English"]).default("中文").volatile(),
+	autoVerify: Schema.boolean().default(true).volatile(),
+	maxComments: Schema.natural().default(MAX_COMMENTS_DEFAULT).volatile(),
+	timeoutMinutes: Schema.natural().default(0).volatile(),
+	ocrConfigPath: Schema.string().volatile(),
+	llmTestTimeoutMs: Schema.natural().min(1).default(LLM_TEST_TIMEOUT_MS),
+	ocrBackgroundMaxMs: Schema.natural().min(1).default(OCR_BACKGROUND_MAX_MS),
+	stdoutMaxBytes: Schema.natural().min(1).default(STDOUT_MAX_BYTES)
+});
+/** 设置项里的 ocrConfigPath：非字符串或空白一律视为「未覆盖」。 */
+function readOcrConfigPath(config) {
+	const raw = config.ocrConfigPath.get();
+	return typeof raw === "string" && raw.trim() !== "" ? raw.trim() : void 0;
+}
+/** 本包剩下的文件路径：只剩外部 ocr CLI 的 config.json（可被设置项覆盖）+ 脚本位置。
+*  messages 只用于「设置项里的路径不合形态」那条可读错误。 */
+function pluginPaths(config, messages) {
+	return {
+		ocrConfigJson: resolveOcrConfigPath(readOcrConfigPath(config), messages),
+		pluginDir: PLUGIN_DIR,
+		getCredScript: defaultCredScriptPath(PLUGIN_DIR)
+	};
+}
+/** 服务界面齐备才算可用（get() 可能返回半装配对象，也可能返回 undefined）。 */
+function usableService(value, methods) {
+	return value !== void 0 && hasMethods(value, methods) ? value : void 0;
+}
+/**
+* 装配 dsh 官方配置/凭据通道（lib/provider-source.ts 只认这个门面）。
+*
+* 探测放 host 侧：只有这里知道 ctx 上到底装没装那两个服务；lib 拿到的是 health 布尔
+* + 已收窄的服务，据此产出卡片可读的降级原因。所有分支都不许抛穿到会话热路径。
+* credentials 的 describe/resolve 只回「是否已配置 / 值能否解析」，resolve 拿到的
+* 值当场丢弃——明文 key 绝不出宿主（更不进 HTTP）。
+*/
+function createGateway(host) {
+	const settingsService = () => usableService(host.get("settings"), ["describe"]);
+	const credentialsService = () => usableService(host.get("credentials"), ["describe", "resolve"]);
+	return {
+		health: () => ({
+			settings: settingsService() !== void 0,
+			credentials: credentialsService() !== void 0
+		}),
+		descriptors: () => {
+			const svc = settingsService();
+			if (svc === void 0) throw new Error(format(localeMessages(host).settingsServiceGone, { ns: PI_AI_NAMESPACE }));
+			return svc.describe();
+		},
+		credentialConfigured: async (envKey) => {
+			const svc = credentialsService();
+			if (svc === void 0 || !isCredentialRefName(envKey)) return false;
+			try {
+				return (await svc.describe(credentialRef(envKey))).configured;
+			} catch {
+				return false;
+			}
+		},
+		credentialResolvable: async (envKey) => {
+			const svc = credentialsService();
+			if (svc === void 0 || !isCredentialRefName(envKey)) return false;
+			try {
+				const resolved = await svc.resolve(credentialRef(envKey));
+				return resolved !== void 0 && resolved.value.length > 0;
+			} catch {
+				return false;
+			}
+		}
+	};
+}
+/** repo 解析：显式绝对路径优先，缺省回退当前会话工作区（导出仅供单测，
+*  同 plugin-hot-reload 把内部纯函数导出的惯例）。 */
+function ocrRepo(args, exec, messages) {
+	return resolveRoot(args["repo"], sessionHeaderCwd(exec), messages);
+}
+/** POST select 的响应：把 body 里的 provider/model 应用到 OCR 配置，按需附带 llm test 回执。 */
+async function sendSelectResponse(text, res, deps) {
+	const msgs = deps.messages();
+	let body;
+	try {
+		body = parseJsonBody(text, msgs);
+	} catch (error) {
+		sendJson(res, 400, {
+			ok: false,
+			error: format(msgs.bodyParseFailed, { message: errorText(error) })
+		});
+		return;
+	}
+	const provider = typeof body["provider"] === "string" ? body["provider"] : "";
+	const model = typeof body["model"] === "string" ? body["model"] : "";
+	if (provider === "" || model === "") {
+		sendJson(res, 400, {
+			ok: false,
+			error: msgs.providerModelRequired
+		});
+		return;
+	}
+	try {
+		const language = readLanguage(deps.config);
+		const applied = await applyProviderSelection(deps.gateway, pluginPaths(deps.config, msgs), {
+			provider,
+			model,
+			...language === void 0 ? {} : { language }
+		}, msgs);
+		let llmTest = null;
+		if (readAutoVerify(deps.config)) llmTest = await runLlmTest(deps.host, deps.config);
+		sendJson(res, 200, {
+			ok: true,
+			applied,
+			llmTest
+		});
+	} catch (error) {
+		sendJson(res, 400, {
+			ok: false,
+			error: errorText(error)
+		});
+	}
+}
+/** 注册 webServer 配置端点（卡片专用：providers/select/migrate/test）。
+*  csrf 为每次 apply 生成的会话内 token：GET providers 下发、三个写端点回填
+*  校验（sec-fetch-site 只挡浏览器，挡不住能构造请求头的本地进程）。
+*  ctx 只用来挂释放器，给的是 `inject(["webServer"])` 子 fiber 的上下文。 */
+function registerConfigEndpoints(ctx, host, config, csrf) {
+	const webServer = host.get("webServer");
+	if (!webServer) return;
+	const servingNonLoopback = webServer.host === "0.0.0.0";
+	const gateway = createGateway(host);
+	const messages = () => localeMessages(host);
+	const disposeProviders = webServer.register({
+		kind: "exact",
+		path: PROVIDERS_PATH,
+		handler: async (req, res) => {
+			if (!guardTrust(req, res, { servingNonLoopback })) return;
+			try {
+				const msgs = messages();
+				const payload = await providersForCard(gateway, pluginPaths(config, msgs), msgs);
+				sendJson(res, 200, {
+					...payload,
+					csrf
+				});
+			} catch (error) {
+				sendJson(res, 500, {
+					ok: false,
+					error: errorText(error)
+				});
+			}
+		}
+	});
+	const disposeSelect = webServer.register({
+		kind: "exact",
+		path: SELECT_PATH,
+		handler: async (req, res) => {
+			if (!guardTrust(req, res, { servingNonLoopback })) return;
+			const text = await guardPost(req, res, csrf);
+			if (text === null) return;
+			await sendSelectResponse(text, res, {
+				config,
+				gateway,
+				host,
+				messages
+			});
+		}
+	});
+	const disposeMigrate = webServer.register({
+		kind: "exact",
+		path: MIGRATE_PATH,
+		handler: async (req, res) => {
+			if (!guardTrust(req, res, { servingNonLoopback })) return;
+			if (await guardPost(req, res, csrf) === null) return;
+			try {
+				const msgs = messages();
+				const result = await migratePlaintextKeys(gateway, pluginPaths(config, msgs), msgs);
+				sendJson(res, 200, {
+					ok: true,
+					...result
+				});
+			} catch (error) {
+				sendJson(res, 400, {
+					ok: false,
+					error: errorText(error)
+				});
+			}
+		}
+	});
+	const disposeTest = webServer.register({
+		kind: "exact",
+		path: TEST_PATH,
+		handler: async (req, res) => {
+			if (!guardTrust(req, res, { servingNonLoopback })) return;
+			if (await guardPost(req, res, csrf) === null) return;
+			try {
+				const llmTest = await runLlmTest(host, config);
+				sendJson(res, 200, {
+					ok: llmTest.ok,
+					output: llmTest.output
+				});
+			} catch (error) {
+				sendJson(res, 400, {
+					ok: false,
+					error: errorText(error)
+				});
+			}
+		}
+	});
+	ctx.effect(() => () => {
+		disposeProviders();
+		disposeSelect();
+		disposeMigrate();
+		disposeTest();
+	}, "ocr-review: config endpoints");
+}
+function registerReviewTool(host, config) {
+	const msgs = localeMessages(host);
+	define(host, {
+		name: "ocr_review",
+		description: msgs.reviewToolDescription,
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				repo: {
+					type: "string",
+					description: msgs.paramRepo
+				},
+				scope: {
+					type: "string",
+					enum: [
+						"workspace",
+						"commit",
+						"branch"
+					],
+					description: msgs.paramScope
+				},
+				commit: {
+					type: "string",
+					description: msgs.paramCommit
+				},
+				from: {
+					type: "string",
+					description: msgs.paramFrom
+				},
+				to: {
+					type: "string",
+					description: msgs.paramTo
+				},
+				effort: {
+					type: "string",
+					enum: [
+						"low",
+						"medium",
+						"high"
+					],
+					description: msgs.paramEffort
+				},
+				background: {
+					type: "string",
+					description: msgs.paramBackground
+				},
+				exclude: {
+					type: "array",
+					items: { type: "string" },
+					description: msgs.paramExclude
+				},
+				...tuningParams(msgs, msgs.unitGroup),
+				wait: {
+					type: "boolean",
+					description: msgs.paramWait
+				},
+				provider: {
+					type: "string",
+					description: msgs.paramProvider
+				},
+				model: {
+					type: "string",
+					description: msgs.paramModel
+				},
+				resume: {
+					type: "string",
+					description: msgs.paramResume
+				}
+			}
+		},
+		schema: REVIEW_OUTPUT_SCHEMA,
+		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 outPath = tmp === void 0 ? void 0 : path.join(tmp, "out.json");
+			try {
+				const { command, workdir } = buildReviewCommand({
+					...args,
+					repo,
+					effort: eff
+				}, outPath, runMsgs);
+				const guarded = wrapWithHostReaper(command);
+				if (outPath === void 0) return await startBackground(host, {
+					command: guarded,
+					workdir,
+					tool: "ocr_review",
+					repo,
+					stdoutMaxBytes: config.stdoutMaxBytes,
+					backgroundMaxMs: config.ocrBackgroundMaxMs
+				}, exec.signal);
+				await runForeground(host, guarded, workdir, tuningOf(config), exec.signal);
+				const text = readOutFile(outPath, runMsgs);
+				const parsed = parseReviewOutput(text, runMsgs);
+				if (!parsed.ok) return format(runMsgs.parseFailedWithReason, {
+					tool: "ocr",
+					message: parsed.message,
+					limit: String(RAW_ECHO_LIMIT),
+					raw: echoRaw(text, RAW_ECHO_LIMIT)
+				});
+				return summarizeReview(parsed, runMsgs, { maxComments: readMaxComments(config) });
+			} finally {
+				if (tmp !== void 0) rmSync(tmp, {
+					recursive: true,
+					force: true
+				});
+			}
+		}
+	});
+}
+function registerScanTool(host, config) {
+	const msgs = localeMessages(host);
+	define(host, {
+		name: "ocr_scan",
+		description: msgs.scanToolDescription,
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				repo: {
+					type: "string",
+					description: msgs.paramRepo
+				},
+				path: {
+					type: "array",
+					items: { type: "string" },
+					description: msgs.paramScanPath
+				},
+				background: {
+					type: "string",
+					description: msgs.paramBackgroundShort
+				},
+				exclude: {
+					type: "array",
+					items: { type: "string" },
+					description: msgs.paramExclude
+				},
+				batch: {
+					type: "string",
+					enum: [
+						"none",
+						"by-language",
+						"by-directory"
+					],
+					description: msgs.paramBatch
+				},
+				...tuningParams(msgs, msgs.unitFile),
+				wait: {
+					type: "boolean",
+					description: msgs.paramWait
+				}
+			}
+		},
+		schema: REVIEW_OUTPUT_SCHEMA,
+		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 outPath = tmp === void 0 ? void 0 : path.join(tmp, "out.json");
+			try {
+				const { command, workdir } = buildScanCommand({
+					...args,
+					repo
+				}, outPath, runMsgs);
+				const guarded = wrapWithHostReaper(command);
+				if (outPath === void 0) return await startBackground(host, {
+					command: guarded,
+					workdir,
+					tool: "ocr_scan",
+					repo,
+					stdoutMaxBytes: config.stdoutMaxBytes,
+					backgroundMaxMs: config.ocrBackgroundMaxMs
+				}, exec.signal);
+				await runForeground(host, guarded, workdir, tuningOf(config), exec.signal);
+				const text = readOutFile(outPath, runMsgs);
+				const parsed = parseReviewOutput(text, runMsgs);
+				if (!parsed.ok) return format(runMsgs.parseFailedWithReason, {
+					tool: "ocr scan",
+					message: parsed.message,
+					limit: String(RAW_ECHO_LIMIT),
+					raw: echoRaw(text, RAW_ECHO_LIMIT)
+				});
+				return summarizeReview(parsed, runMsgs, { maxComments: readMaxComments(config) });
+			} finally {
+				if (tmp !== void 0) rmSync(tmp, {
+					recursive: true,
+					force: true
+				});
+			}
+		}
+	});
+}
+function registerDelegatePreviewTool(host, config) {
+	const msgs = localeMessages(host);
+	define(host, {
+		name: "ocr_delegate_preview",
+		description: msgs.previewToolDescription,
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				repo: {
+					type: "string",
+					description: msgs.paramRepo
+				},
+				scope: {
+					type: "string",
+					enum: [
+						"workspace",
+						"commit",
+						"branch"
+					],
+					description: msgs.paramScope
+				},
+				commit: {
+					type: "string",
+					description: msgs.paramCommitShort
+				},
+				from: {
+					type: "string",
+					description: msgs.paramFromShort
+				},
+				to: {
+					type: "string",
+					description: msgs.paramToShort
+				},
+				background: {
+					type: "string",
+					description: msgs.paramBackgroundPreview
+				},
+				exclude: {
+					type: "array",
+					items: { type: "string" },
+					description: msgs.paramExcludeShort
+				}
+			}
+		},
+		schema: PREVIEW_OUTPUT_SCHEMA,
+		run: async (args, exec) => {
+			const runMsgs = localeMessages(host);
+			const repo = ocrRepo(args, exec, runMsgs);
+			const { command, workdir } = buildDelegatePreviewCommand({
+				...args,
+				repo
+			}, runMsgs);
+			const text = await runForeground(host, command, workdir, tuningOf(config), exec.signal);
+			const parsed = parseDelegatePreview(text);
+			if (!parsed.ok) return format(runMsgs.parseFailedPlain, {
+				tool: "ocr delegate preview",
+				limit: String(RAW_ECHO_LIMIT),
+				raw: echoRaw(text, RAW_ECHO_LIMIT)
+			});
+			return {
+				mode: parsed.mode,
+				repository: parsed.repository,
+				reviewableCount: parsed.reviewable.length,
+				insertions: parsed.reviewable.reduce((acc, file) => acc + file.insertions, 0),
+				deletions: parsed.reviewable.reduce((acc, file) => acc + file.deletions, 0),
+				reviewableFiles: parsed.reviewable,
+				excludedFiles: parsed.excluded,
+				hint: runMsgs.previewHint
+			};
+		}
+	});
+}
+function registerDelegateRuleTool(host, config) {
+	const msgs = localeMessages(host);
+	define(host, {
+		name: "ocr_delegate_rule",
+		description: msgs.ruleToolDescription,
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				repo: {
+					type: "string",
+					description: msgs.paramRepo
+				},
+				paths: {
+					type: "array",
+					items: { type: "string" },
+					description: msgs.paramPaths
+				}
+			},
+			required: ["paths"]
+		},
+		schema: RULES_OUTPUT_SCHEMA,
+		run: async (args, exec) => {
+			const runMsgs = localeMessages(host);
+			const { command, workdir } = buildDelegateRuleCommand({
+				repo: ocrRepo(args, exec, runMsgs),
+				paths: args["paths"]
+			}, runMsgs);
+			const text = await runForeground(host, command, workdir, tuningOf(config), exec.signal);
+			const parsed = parseDelegateRules(text);
+			if (!parsed.ok) return format(runMsgs.parseFailedPlain, {
+				tool: "ocr delegate rule",
+				limit: String(RAW_ECHO_LIMIT),
+				raw: echoRaw(text, RAW_ECHO_LIMIT)
+			});
+			return {
+				groupCount: parsed.groups.length,
+				groups: parsed.groups.map((group) => ({
+					source: group.source,
+					pattern: group.pattern,
+					files: group.files,
+					rule: group.rule
+				})),
+				hint: runMsgs.ruleHint
+			};
+		}
+	});
+}
+function registerSessionTool(host, config) {
+	const msgs = localeMessages(host);
+	define(host, {
+		name: "ocr_session",
+		description: msgs.sessionToolDescription,
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				repo: {
+					type: "string",
+					description: msgs.paramRepo
+				},
+				action: {
+					type: "string",
+					enum: [
+						"list",
+						"show",
+						"comments"
+					],
+					description: msgs.paramSessionAction
+				},
+				id: {
+					type: "string",
+					description: msgs.paramSessionId
+				},
+				limit: {
+					type: "integer",
+					description: msgs.paramSessionLimit
+				}
+			}
+		},
+		schema: SESSION_OUTPUT_SCHEMA,
+		run: async (args, exec) => {
+			const runMsgs = localeMessages(host);
+			const repo = ocrRepo(args, exec, runMsgs);
+			const { command, workdir } = buildSessionCommand({
+				...args,
+				repo
+			}, runMsgs);
+			const text = await runForeground(host, command, 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);
+			return {
+				sessionOutput: empty ? runMsgs.sessionEmpty : capped,
+				hint: runMsgs.sessionResumeHint
+			};
+		}
+	});
+}
+function apply(ctx, config) {
+	const host = resolveHost(ctx);
+	ctx.effect(() => () => {
+		const jobs = ctx.get("jobs");
+		if (jobs !== void 0) reclaimOcrJobs(jobs, localeMessages(ctx).jobReasonUnload);
+	}, "ocr-review: background jobs");
+	host.inject(["settings"], (child) => {
+		child.effect(() => child.settings.configure({ auto: false }, host.fiber));
+	});
+	registerReviewTool(host, config);
+	registerScanTool(host, config);
+	registerDelegatePreviewTool(host, config);
+	registerDelegateRuleTool(host, config);
+	registerSessionTool(host, config);
+	host.systemPrompt.section({
+		name: ROUTING_NAME,
+		order: ROUTING_ORDER,
+		text: localeMessages(host).routingText
+	});
+	host.inject(["webServer"], (child) => {
+		registerConfigEndpoints(child, host, config, randomUUID());
+	});
+}
+var host_default = {
+	inject: [
+		"settings",
+		"shell",
+		"tools",
+		"systemPrompt"
+	],
+	Config: configSchema,
+	apply
+};
+//#endregion
+export { configSchema as Config, createGateway, host_default as default, ocrRepo, parseJsonBody, registerConfigEndpoints, requiredKeys };