@jayyuen66/dsh-ocr-review 0.1.7 → 0.1.8

package/host.js

@@ -12,9 +12,9 @@ import { truncateEnd, truncateStart } from "@jayyuen66/dsh-plugin-shared/lib/tex
 import { fieldOf, hasMethods, isRecord } from "@jayyuen66/dsh-plugin-shared/lib/record";
 import { expandHomePath, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { errorText } from "@jayyuen66/dsh-plugin-shared/lib/errors";
-import { mkdir } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import { withFileLock, writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
-//#region lib/messages.ts
+// lib/messages.ts
 const MESSAGES = {
 	zh: {
 		middleEllipsis: " …[中间省略]… ",
@@ -46,9 +46,17 @@ const MESSAGES = {
 		settingsServiceGone: "{ns} 所在的设置服务在读取过程中已不可用",
 		repoRequired: "repo 必填，且为 Git 仓库绝对路径",
 		repoRequiredUnknownWorkspace: "repo 必填：当前会话工作区未知，请显式传入 Git 仓库绝对路径",
-		repoMustBeAbsolute: "repo 必须是绝对路径（以 / 开头）：{root}",
+		repoMustBeAbsolute: "repo 必须是绝对路径：{root}",
 		noNulBytes: "{name} 不能包含 NUL 字节",
-		listTruncated: "{name} 超过 {limit} 条上限，已丢弃 {dropped} 条——审查范围会因此小于你给的清单",
+		boolMustBeBoolean: "{name} 必须是布尔值（true/false），收到 {received}",
+		repoRootUnreadable: "repo 根目录不可读：{path}",
+		repoFileMissing: "{name} 指向的文件不存在：{path}",
+		repoFileOutside: "{name} 必须指向 repo 根目录内的文件：{path}",
+		repoFileNotFile: "{name} 必须指向普通文件：{path}",
+		repoFileTooLarge: "{name} 文件过大（{path}，上限 {limit} 字节）",
+		previewNeedsForeground: "preview 是秒级前台操作，不能与 wait=false 同用",
+		previewRejectsResume: "preview 不读写会话，不能与 resume 同用",
+		listOverLimit: "{name} 超过 {limit} 条上限（多出 {dropped} 条）——命令未构造，本轮一条都没有审：请精简清单后重试，或按 commit/目录拆成多批分别调用",
 		mustBeString: "{name} 必须是字符串（收到 {received}）",
 		listItemsMustBeString: "{name} 数组元素必须是字符串",
 		mustBeStringOrList: "{name} 必须是字符串或字符串数组",
@@ -58,6 +66,7 @@ const MESSAGES = {
 		branchNeedsFromAndTo: "scope=branch 需要同时提供 from 与 to",
 		commitNeedsValue: "scope=commit 需要 commit 参数",
 		unknownScope: "未知 scope：{scope}（workspace/commit/branch）",
+		scopeMismatch: "scope={scope} 与 {given} 不能同时给（scope 是声明，{given} 属于另一种范围；两者冲突时按哪个审没有正确答案）",
 		resumeNeedsScope: "resume 需要 scope=commit 或 scope=branch（workspace 工作区评审不支持恢复，OCR 会直接拒绝）；请同时给出 commit 或 from/to",
 		waitMustBeBoolean: "wait 必须是布尔值（true/false），收到 {received}",
 		pathsRequired: "paths 必填：至少传一个待审查文件的仓库相对路径",
@@ -66,16 +75,41 @@ const MESSAGES = {
 		listRejectsId: "action=list 不接受 id（查单个会话请用 action=show 或 action=comments）",
 		resultSchemaViolation: "ocr {tool}: 返回值不符合该工具的 output schema：{violations}",
 		resultSchemaUnsupported: "ocr {tool}: 返回形态守卫不支持 output schema 关键字 {keyword}（插件内 bug：lib/output.ts 的关键字子集没跟上 schema）",
+		resultSchemaMalformed: "ocr {tool}: output schema 自身不合法——{detail}（插件内 bug：schema 的写法超出了返回形态守卫支持的官方子集）",
 		ocrNotJson: "OCR 未返回合法 JSON 输出",
 		ocrNotObject: "OCR JSON 输出不是对象",
 		ocrStatusInvalid: "OCR 输出 status 非法或缺失：{status}（期望 {expected}）；exit 0 不代表评审完成，请查 stderr 与 ~/.opencodereview/sessions/",
 		statusNone: "（无）",
+		ocrStatusFailed: "OCR 回执自报 status=failed（这一场评审没有成功完成）",
 		ocrCommentsNotArray: "OCR 输出 comments 字段不是数组，无法确认评论完整性",
 		warningSeparator: "：",
 		reviewSummaryHint: "完整评论与逐文件失败详情请用 `ocr_session(action=show/comments, id=<session_id>)` 查看；start_line=0 表示 OCR 未能锚定行号，可依据 suggestion/existing_code 在文件中定位。两套口径不要混：droppedCount 与 invalidCommentCount 同时为 0 只说明**本摘要**列全了 OCR 产出的评论（否则调大 maxComments 或置 0 后复核）；而**这一场有没有审完**看 coverage（selected 是分母，completed/reused/failed/waived 是它的互斥划分；coverage 为 null 时退回看 warnings 与 status=partial）和 budgetExceeded（true = token 预算花完提前收工，status 里只写 partial，看不出这一层）。toolCalls.failure 大于 0 说明当前模型的工具调用没跑通，换模型比重试同一个更省 token。切勿把「本摘要无 critical」当作「代码干净」。",
 		lineZeroNote: "(line 0: 定位失败，按 existing_code 手动定位)",
 		parseFailedWithReason: "{tool} 输出解析失败：{message}\n原始内容前 {limit} 码元（已脱敏）：\n{raw}",
 		parseFailedPlain: "{tool} 输出解析失败\n原始内容前 {limit} 码元（已脱敏）：\n{raw}",
+		previewParseFailed: "OCR 的 --preview 回执不是可识别的文件清单（files 缺失或条目形状不合）",
+		rulesPathRequired: "rules check 的 path 必填（待查询的文件路径）",
+		textTruncated: "…[截断] 输出超过 {limit} 字符上限",
+		mcpReadFailed: "读取 MCP 配置失败（{where}）：{cause}",
+		mcpJsonInvalid: "MCP 配置不是合法 JSON：{cause}",
+		mcpJsonTooLarge: "MCP 配置超过 {limit} 字节上限",
+		mcpShapeInvalid: "MCP 配置必须是 {{name: entry}} 形式的对象",
+		mcpTooManyServers: "MCP servers 最多 {limit} 个",
+		mcpServerInvalid: "MCP server「{name}」的 {field} 不合法：{reason}",
+		mcpSaved: "MCP servers 已保存（{count} 个）",
+		chatGptModelRequired: "ChatGPT 模型名必填",
+		chatGptSaved: "已切换到 ChatGPT provider，模型：{model}",
+		chatGptSaveFailed: "写入 ChatGPT 配置失败：{cause}",
+		compareNeedsBoth: "action=compare 需要同时给出 before 与 after 两个会话 id",
+		compareRejectsArgs: "action=compare 不接受 id/limit/severity/category",
+		exportRejectsArgs: "action=export 不接受 before/after/limit/severity/category",
+		exportOutputRequired: "action=export 需要宿主给出输出路径",
+		beforeAfterOnlyForCompare: "before/after 只适用于 action=compare",
+		filtersOnlyForComments: "severity/category 过滤只适用于 action=comments",
+		filtersNeedId: "severity/category 过滤需要同时给出会话 id",
+		invalidSeverity: "severity 过滤值必须是 critical/high/medium/low 之一，收到 {value}",
+		sessionCompareHint: "四桶含义：new=只在后一次出现；persisting=两次都有；resolved=只在前一次出现且后一次审过该文件；not_reviewed=只在前一次出现且后一次没审该文件（不算已解决）。",
+		sessionExportHint: "已导出为自包含 HTML 文件；路径在 sessionOutput 里，直接用浏览器打开即可（文件留在临时目录，不会自动删除）。",
 		sourceSettingsUnavailable: "dsh 设置服务（ctx.settings）未装配：本插件需要它读取已配置的 provider 列表",
 		sourceSettingsFailed: "调用 dsh 设置服务失败：{message}",
 		sourceNamespaceUnavailable: "dsh 配置里没有 {ns} 命名空间：未安装 pi-ai 适配器，或还没配置任何 provider",
@@ -83,6 +117,7 @@ const MESSAGES = {
 		badEnvKey: "非法 env key：{key}（get-cred 只接受 ^[A-Z0-9_]+$ 的大写 ref 名；请在 dsh 配置里把该 provider 的 apiKeyEnv 改成大写字母/数字/下划线）",
 		configNotJson: "{where} 不是合法 JSON，已中止写入以保护既有配置（请先修复或删掉该文件）：{cause}",
 		configNotObject: "{where} 顶层不是 JSON 对象，已中止写入以保护既有配置",
+		configUnreadable: "{where} 读不动，已中止写入以保护既有配置（既有文件不会被覆盖）：{cause}",
 		providerNotInList: "provider 不在 dsh 配置的 {ns}.providers 列表：{provider}",
 		modelNotInList: "model 不在 {provider} 的 models 列表中：{model}",
 		protocolUnsupported: "provider {provider} 的 api 协议 {protocol} 无法映射到 OCR 支持的 protocol（openai/openai-responses/anthropic）；请在 dsh 配置里改用 openai-completions/openai-responses/anthropic-messages，或升级本插件",
@@ -96,16 +131,19 @@ const MESSAGES = {
 		warningUnreadable: "（一条格式无法解析的 warning：既不是字符串，也没有 file/message/type 字段）",
 		diagnosticUnreadable: "（OCR 的 {field} 字段形态不合，这一场的诊断数据读不出来）",
 		diagnosticOmitted: "（另有 {count} 条同类明细已省略，全量见 ocr_session 的 show/comments）",
-		commaInListItem: "{name} 的数组形式里有一项自身含逗号：{item}。数组与逗号字符串两条路径 join 后无法区分，而 glob 花括号（{ts,tsx}）恰好含逗号——静默拆成多项会改变审查/过滤范围。改用逗号字符串形式。",
+		commaInListItem: "{name} 的数组形式里有一项自身含逗号：{item}。值最终按逗号拼接传给 ocr，含逗号的模式必被拆开、静默改变审查/过滤范围。请改写成不含逗号的等价模式（如把 {ts,tsx} 展开成两条），或去掉该条",
+		commaInStringBraces: "{name} 的字符串形式里有 glob 花括号内含逗号：{item}。按逗号拆分后花括号会被撕成多个无效模式，过滤条件失效、审查范围被无声扩大。请把花括号展开成多条模式（{ts,tsx} 即两条）后再传入",
 		probeNoVersion: "ocr version 跑通了（exit 0），但回执里读不出版本号：那通常是未发布构建。",
 		probeTimedOut: "ocr version 超时（{seconds} 秒内没回来）：那条进程已被收走。稍后重试，或直接在终端里跑 ocr version——本插件不会替它代跑安装或升级。",
 		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 独立审查，返回聚合评论摘要。",
+		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 提供需求/业务上下文能显著提升质量。preview=true 只做文件选择（零 LLM、不建会话）；noFilter 保留全部评论；rule/backgroundFile 只收 repo 根内文件。首次审查前确保 ocr 已配置且 'ocr llm test' 通过。",
+		scanToolDescription: "用 open-code-review（ocr）做全文件扫描审查（无需 Git 变更/无 diff，适合审计陌生代码库或指定目录）。--path 逗号分隔的仓库相对目录/文件（缺省整个仓库，路径不存在会报错）。与 ocr_review 一样由 OCR 自身 LLM 独立审查，返回聚合评论摘要。preview=true 只列扫描范围；noPlan/noDedup/noSummary 降本；resume 续扫；rule 只收 repo 根内文件。",
 		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 的返回结果直接获取。",
+		sessionToolDescription: "查询 open-code-review 的历史评审会话：action=list 列最近会话（含 session_id/mode/model/评论数，可用于 ocr_review/ocr_scan --resume 恢复中断的评审）；action=show 查看单个会话元数据与逐文件检查点；action=comments 取单个会话的评论明细（可按 severity/category 过滤）；action=compare 比较两次会话的 new/persisting/resolved/not_reviewed 四桶；action=export 导出自包含 HTML。session_id 也可从 ocr_review/ocr_scan 的返回结果直接获取。",
+		rulesCheckToolDescription: "调试 open-code-review 的规则解析：对给定文件路径打印最终命中的规则层（--rule/项目/全局/内置）、glob 模式与规则正文。不调用 LLM、不建会话；用于排查「我的规则为什么没生效」。",
+		llmToolDescription: "只读查询 open-code-review 的 LLM 配置面：action=providers 列内置 provider；action=models 列当前 ChatGPT 账号可用的模型（需要先完成 ocr auth 登录）。不发起评审、不测试连通性。",
 		paramRepo: "Git 仓库绝对路径（可选：缺省=当前会话工作区）",
 		paramScope: "审查范围（缺省 workspace）",
 		paramCommit: "scope=commit 时必填：提交哈希",
@@ -114,7 +152,7 @@ const MESSAGES = {
 		paramCommitShort: "scope=commit 时必填",
 		paramFromShort: "scope=branch 时必填",
 		paramToShort: "scope=branch 时必填",
-		paramEffort: "投入档位（缺省 medium）",
+		paramEffort: "投入档位 low/medium/high；不给时取设置卡默认（出厂 auto=跟随 OCR 自身配置）",
 		paramBackground: "需求/业务上下文（官方 skill 推荐：调用前先用 git log/diff/提交信息快速分析变更意图，提取 3-5 句业务背景传入，是提升评审质量最有效的参数；从其它 agent 调用时始终携带 PR 描述/需求）",
 		paramBackgroundShort: "需求/业务上下文",
 		paramBackgroundPreview: "业务上下文（会出现在输出中供审查参考）",
@@ -124,32 +162,54 @@ const MESSAGES = {
 		paramProvider: "本次运行临时指定已配置 provider",
 		paramModel: "本次运行临时覆盖 model",
 		paramResume: "从之前中断的会话 id 恢复（会话 id 在返回结果里）",
-		paramScanPath: "仓库相对目录或文件（缺省整仓，可多值；上限 2000 条，超出会直接报错）",
+		paramScanPath: "仓库相对目录或文件（缺省整仓，可多值；上限 2000 条，超出会直接报错；路径不存在会报错而不是空扫描）",
+		paramPreview: "true=只列文件清单与排除原因，不调用 LLM、不建会话（秒级返回）；与 resume/wait=false 互斥",
+		paramNoFilter: "true=跳过 OCR 的 LLM 评论后过滤，保留全部评论（召回优先，噪音更多）",
+		paramMaxGitProcs: "git 子进程并发上限（OCR --max-git-procs；缺省不传=原生 16）",
+		paramRule: "repo 根内的自定义规则 JSON 路径（OCR --rule；只允许仓库内普通文件）",
+		paramBackgroundFile: "repo 根内的 Markdown 需求文件路径（OCR --background-file；优先于 background）",
+		paramNoPlan: "true=跳过 scan 的逐文件 PLAN_TASK 预检（降本）",
+		paramNoDedup: "true=跳过 scan 的批内 DEDUP_TASK（降本）",
+		paramNoSummary: "true=跳过 scan 结束后的 PROJECT_SUMMARY_TASK（降本）",
+		paramScanResume: "从之前中断的 scan 会话 id 恢复",
 		paramBatch: "分批策略",
 		paramPaths: "待查询的仓库相对文件路径（至少 1 个，最多 200）",
-		paramSessionAction: "list：列最近会话（缺省）/ show：查看单个 / comments：取评论",
-		paramSessionId: "action=show/comments 时的会话 id",
+		paramSessionAction: "list：列最近会话（缺省）/ show：查看单个 / comments：取评论 / compare：比较两次会话 / export：导出 HTML",
+		paramSessionId: "action=show/comments/export 时的会话 id（export 缺省=最新一场）",
+		paramSessionBefore: "action=compare 时必填：较早的会话 id",
+		paramSessionAfter: "action=compare 时必填：较晚的会话 id",
+		paramSessionSeverity: "action=comments 时按严重度过滤（critical/high/medium/low）",
+		paramSessionCategory: "action=comments 时按类别过滤（如 bug/security）",
 		paramSessionLimit: "list 上限 1-100（缺省 10）",
+		paramRulesPath: "待查询的文件路径（仓库相对或绝对；仅用于规则匹配）",
+		paramLlmAction: "providers：内置 provider 列表 / models：ChatGPT 账号模型列表",
 		unitGroup: "组",
 		unitFile: "文件",
 		tuningConcurrency: "并发{unit}数（OCR --concurrency；缺省不传=OCR 原生 8）",
-		tuningTimeout: "每{unit}任务超时分钟（OCR --timeout；0=不限时；缺省不传=OCR 原生 15）",
+		tuningTimeout: "每{unit}任务超时分钟（OCR --timeout；review 会按 effort 轮数线性放大，scan 不放大；0=不限时；缺省不传=OCR 原生 15）",
 		tuningMaxTools: "每{unit}工具调用轮数上限（OCR --max-tools；0=模板默认；1-49 会被 OCR 抬到 50，帮助文本 min 50；缺省不传=模板默认）",
 		tuningMaxToolsScan: "每{unit}工具调用轮数上限（OCR --max-tools；0=模板默认；只在大于模板默认值时生效，不抬到 50；缺省不传=模板默认）",
 		tuningMaxTokens: "每{unit}提示词 token 上限（OCR --max-tokens；0=配置/模板默认；缺省不传=模板默认）",
 		tuningMaxTokensBudget: "本次运行 total token（input+output）预算闸门，超出即停止派发部分结果（OCR --max-tokens-budget；0=不限；缺省不传=不限）",
 		previewHint: "对每个 reviewable 文件：用 git diff <merge_base>..<to> -- <path>（branch）/git show <commit> -- <path>（commit）/ git diff HEAD -- <path> 或直接读文件（workspace 新文件）取 diff。",
+		filePreviewHint: "这是文件选择预览：没有调用 LLM、没有创建会话。要真正审查请去掉 preview 后重跑。列表按上限截断；truncated=true 时请用 exclude/path 缩小范围。",
 		ruleHint: "按分组规则逐个审查对应文件，输出评论建议格式：{path, content, start_line, end_line, category, severity}。",
 		sessionEmpty: "（暂无历史评审会话：先跑一次 ocr_review/ocr_scan 再查询）",
 		sessionTruncated: "…[截断] 完整内容见 ~/.opencodereview/sessions/",
-		sessionResumeHint: "要恢复中断的区间/commit 评审：ocr_review ... --resume <session_id>（工作区评审不支持恢复）。",
+		sessionResumeHint: "要恢复中断的区间/commit 评审：ocr_review ... --resume <session_id>（工作区评审不支持恢复）；scan 会话用 ocr_scan ... --resume <session_id>。",
+		rulesCheckHint: "输出里的 Source 是命中的层（--rule/项目/全局/内置），Pattern 是命中的 glob；规则按声明顺序先到先得。",
+		llmHint: "providers 是内置清单，models 是 ChatGPT 账号专属列表；评审实际用哪个 provider/model 仍以 OCR 配置为准。",
 		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_review / ocr_scan 的 preview=true：只列文件选择与排除原因，零 LLM、不建会话；scan 还支持
+    noPlan/noDedup/noSummary 降本与 resume 续扫。
+  - ocr_session：list/show/comments（可按 severity/category 过滤）/compare（new/persisting/resolved/not_reviewed）/export。
+  - ocr_rules_check / ocr_llm：规则解析与 LLM 清单的只读诊断，不评审、不花 token。
+  - 审查前若不确定范围，先 ocr_delegate_preview 或 preview=true（不花 token）；范围过大时用 exclude 收敛或按 commit 拆。
 - OCR 端点/provider/model 由「设置 → 插件 → ocr-review 卡片」从宿主设置服务的 provider 清单选择
   （key 只按 api_key_cmd 动态读取，不落盘明文）；也可在工具参数里用 provider/model 逐次覆盖。
 - 调用 ocr_review / ocr_scan 前，先用 git log/diff/提交信息快速分析变更意图，提取 3-5 句业务上下文
@@ -162,7 +222,7 @@ const MESSAGES = {
 - LLM 调用本身有重试：OCR 内置重试（429/408/409 与 5xx 自动退避重试）；per-file 组失败被隔离，进
   coverage.failedItems（产出里没有 manifest 时进 warnings），不整体重跑。
   工具层超时（min(请求, shell 执行器自己设置项里的 maxTimeoutMs)，缺省 10 分钟）或部分文件失败后，可
-  ocr_session 查 session_id、用 ocr_review --resume 恢复中断的区间/commit 评审。
+  ocr_session 查 session_id、用 ocr_review --resume 恢复中断的区间/commit 评审，或 ocr_scan --resume 续扫。
 `.trim()
 	},
 	en: {
@@ -195,8 +255,16 @@ const MESSAGES = {
 		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}",
-		listTruncated: "{name} exceeds the {limit}-item cap; {dropped} item(s) were dropped - the review will cover less than the list you passed",
+		repoMustBeAbsolute: "repo must be an absolute path: {root}",
+		boolMustBeBoolean: "{name} must be a boolean (true/false), got {received}",
+		repoRootUnreadable: "the repo root is not readable: {path}",
+		repoFileMissing: "{name} points at a file that does not exist: {path}",
+		repoFileOutside: "{name} must point at a file inside the repo root: {path}",
+		repoFileNotFile: "{name} must point at a regular file: {path}",
+		repoFileTooLarge: "{name} file is too large ({path}, cap {limit} bytes)",
+		previewNeedsForeground: "preview is a fast foreground operation and cannot be combined with wait=false",
+		previewRejectsResume: "preview does not read or write sessions and cannot be combined with resume",
+		listOverLimit: "{name} exceeds the {limit}-item cap ({dropped} extra) - the command was not constructed and nothing has been reviewed: trim the list and retry, or split the run into smaller batches by commit/directory",
 		noNulBytes: "{name} must not contain NUL bytes",
 		mustBeString: "{name} must be a string (got {received})",
 		listItemsMustBeString: "the items of {name} must be strings",
@@ -207,6 +275,7 @@ const MESSAGES = {
 		branchNeedsFromAndTo: "scope=branch requires both from and to",
 		commitNeedsValue: "scope=commit requires the commit parameter",
 		unknownScope: "unknown scope: {scope} (workspace/commit/branch)",
+		scopeMismatch: "scope={scope} cannot be combined with {given} (scope declares one range, {given} belongs to another; there is no correct way to pick one)",
 		resumeNeedsScope: "resume requires scope=commit or scope=branch (workspace reviews cannot be resumed; OCR rejects it outright); pass commit or from/to as well",
 		waitMustBeBoolean: "wait must be a boolean (true/false), got {received}",
 		pathsRequired: "paths is required: pass at least one repo-relative path of a file to review",
@@ -215,16 +284,41 @@ const MESSAGES = {
 		listRejectsId: "action=list does not take an id (use action=show or action=comments for a single session)",
 		resultSchemaViolation: "ocr {tool}: the tool result does not match its output schema: {violations}",
 		resultSchemaUnsupported: "ocr {tool}: the result guard does not support the output schema keyword {keyword} (plugin bug: the keyword subset in lib/output.ts lags the schema)",
+		resultSchemaMalformed: "ocr {tool}: the output schema itself is malformed — {detail} (plugin bug: the schema goes beyond the official subset the result guard supports)",
 		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)",
+		ocrStatusFailed: "the OCR receipt reports status=failed (this review run did not complete)",
 		ocrCommentsNotArray: "the comments field of the OCR output is not an array, comment completeness cannot be confirmed",
 		warningSeparator: ": ",
 		reviewSummaryHint: "Use `ocr_session(action=show/comments, id=<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. Keep the two notions apart: droppedCount and invalidCommentCount both being 0 only means THIS SUMMARY listed every comment OCR produced (otherwise raise maxComments, or set it to 0, and re-check). Whether the run itself covered everything is answered by coverage (selected is the denominator, completed/reused/failed/waived are its disjoint partition; fall back to warnings and status=partial when coverage is null) and by budgetExceeded (true = the token budget stopped the run early — status still only says partial). A toolCalls.failure above 0 means the current model's tool calls did not work: switch models instead of retrying the same one. 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}",
+		previewParseFailed: "the OCR --preview receipt is not a recognizable file list (files missing or every entry malformed)",
+		rulesPathRequired: "rules check requires path (the file to look up)",
+		textTruncated: "…[truncated] output exceeded the {limit}-character cap",
+		mcpReadFailed: "failed to read the MCP config ({where}): {cause}",
+		mcpJsonInvalid: "the MCP config is not valid JSON: {cause}",
+		mcpJsonTooLarge: "the MCP config exceeds the {limit}-byte cap",
+		mcpShapeInvalid: "the MCP config must be an object of {name: entry}",
+		mcpTooManyServers: "at most {limit} MCP servers are allowed",
+		mcpServerInvalid: "MCP server \"{name}\" has an invalid {field}: {reason}",
+		mcpSaved: "MCP servers saved ({count})",
+		chatGptModelRequired: "a ChatGPT model slug is required",
+		chatGptSaved: "switched to the ChatGPT provider, model: {model}",
+		chatGptSaveFailed: "failed to write the ChatGPT config: {cause}",
+		compareNeedsBoth: "action=compare requires both before and after session ids",
+		compareRejectsArgs: "action=compare does not take id/limit/severity/category",
+		exportRejectsArgs: "action=export does not take before/after/limit/severity/category",
+		exportOutputRequired: "action=export requires an output path from the host",
+		beforeAfterOnlyForCompare: "before/after only apply to action=compare",
+		filtersOnlyForComments: "severity/category filters only apply to action=comments",
+		filtersNeedId: "severity/category filters require a session id",
+		invalidSeverity: "severity filter values must be one of critical/high/medium/low, got {value}",
+		sessionCompareHint: "Bucket meanings: new = only in the later run; persisting = in both; resolved = only in the earlier run and the later run reviewed that file; not_reviewed = only in the earlier run and the later run never looked at that file (not resolved).",
+		sessionExportHint: "Exported as a self-contained HTML file; the path is in sessionOutput — open it in a browser. It stays in the temp directory and is not deleted automatically.",
 		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",
@@ -232,6 +326,7 @@ const MESSAGES = {
 		badEnvKey: "invalid env key: {key} (get-cred only accepts uppercase ref names matching ^[A-Z0-9_]+$; change the provider's apiKeyEnv in the dsh configuration to uppercase letters/digits/underscores)",
 		configNotJson: "{where} is not valid JSON; the write was aborted to protect the existing configuration (fix or delete that file first): {cause}",
 		configNotObject: "the top level of {where} is not a JSON object; the write was aborted to protect the existing configuration",
+		configUnreadable: "{where} could not be read; the write was aborted so the existing configuration is left untouched: {cause}",
 		providerNotInList: "provider is not in the {ns}.providers list configured by dsh: {provider}",
 		modelNotInList: "model is not in the models list of {provider}: {model}",
 		protocolUnsupported: "the api protocol {protocol} of provider {provider} cannot be mapped to an OCR-supported protocol (openai/openai-responses/anthropic); use openai-completions/openai-responses/anthropic-messages in the dsh configuration, or upgrade this plugin",
@@ -245,16 +340,19 @@ const MESSAGES = {
 		warningUnreadable: "(one unreadable warning entry: neither a string nor an object with file/message/type)",
 		diagnosticUnreadable: "(the {field} field of the OCR output is malformed; its diagnostics cannot be read for this run)",
 		diagnosticOmitted: "({count} more entries of the same kind were omitted; use ocr_session show/comments for the full list)",
-		commaInListItem: "an item of the array form of {name} contains a comma itself: {item}. The array form and the comma-joined string are indistinguishable after joining, and glob braces ({ts,tsx}) contain commas — silently splitting changes the review/filter scope. Use the comma-separated string form.",
+		commaInListItem: "an item of the array form of {name} contains a comma itself: {item}. Values reach ocr comma-joined, so a pattern containing a comma is certain to be torn apart, silently changing the review/filter scope. Rewrite it as comma-free equivalents (e.g. expand {ts,tsx} into two patterns) or drop the item",
+		commaInStringBraces: "the string form of {name} contains a comma inside a glob brace: {item}. Splitting on commas tears the brace into several invalid patterns, silently changing the review/filter scope. Expand the brace into separate patterns ({ts,tsx} means two) and pass those",
 		probeNoVersion: "ocr version ran fine (exit 0), yet no version could be read from its output: that usually means an unreleased build",
 		probeTimedOut: "ocr version timed out (nothing back within {seconds}s): that process was reaped. Retry later, or run ocr version in a terminal yourself — this plugin never runs an install or upgrade on your behalf",
 		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.",
+		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. preview=true selects files only (no LLM, no session); noFilter keeps every comment; rule/backgroundFile accept repo-root files only. 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; a nonexistent path errors). Like ocr_review, OCR's own LLM reviews independently and an aggregated comment summary is returned. preview=true lists the scan scope only; noPlan/noDedup/noSummary reduce cost; resume continues an interrupted scan; rule accepts a repo-root file only.",
 		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.",
+		sessionToolDescription: "Query open-code-review's past review sessions: action=list shows recent sessions (session_id/mode/model/comment counts, usable for ocr_review/ocr_scan --resume of interrupted reviews); action=show prints one session's metadata and per-file checkpoints; action=comments returns one session's comment details (optionally filtered by severity/category); action=compare compares two sessions into new/persisting/resolved/not_reviewed; action=export writes a self-contained HTML file. session_id is also returned by ocr_review/ocr_scan.",
+		rulesCheckToolDescription: "Debug open-code-review rule resolution: for a given file path, print the winning rule layer (--rule/project/global/built-in), the glob pattern and the rule body. No LLM call and no session; use it when a custom rule is not firing.",
+		llmToolDescription: "Read-only queries over open-code-review's LLM configuration: action=providers lists built-in providers; action=models lists the current ChatGPT account's models (requires an ocr auth sign-in first). It never runs a review or a connectivity test.",
 		paramRepo: "Absolute path to the Git repository (optional: default = current session workspace)",
 		paramScope: "Review scope (default workspace)",
 		paramCommit: "Required with scope=commit: commit hash",
@@ -263,7 +361,7 @@ const MESSAGES = {
 		paramCommitShort: "Required with scope=commit",
 		paramFromShort: "Required with scope=branch",
 		paramToShort: "Required with scope=branch",
-		paramEffort: "Effort level (default medium)",
+		paramEffort: "Effort level low/medium/high; when omitted the settings card default applies (factory auto = follow the OCR config)",
 		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)",
@@ -273,25 +371,43 @@ const MESSAGES = {
 		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; cap 2000 - exceeding it is an error, never a silent drop)",
+		paramScanPath: "Repo-relative directories or files (default: whole repo, multiple allowed; cap 2000 - exceeding it is an error; a nonexistent path errors instead of scanning nothing)",
+		paramPreview: "true = list files and exclusion reasons only; no LLM call, no session, returns in seconds. Mutually exclusive with resume/wait=false",
+		paramNoFilter: "true = skip OCR's LLM post-filter and keep every comment (recall over noise)",
+		paramMaxGitProcs: "Concurrent git subprocess cap (OCR --max-git-procs; unset = native 16)",
+		paramRule: "Path to a custom rule JSON inside the repo root (OCR --rule; regular files only)",
+		paramBackgroundFile: "Path to a Markdown requirements file inside the repo root (OCR --background-file; takes precedence over background)",
+		paramNoPlan: "true = skip scan's per-file PLAN_TASK pre-pass (cheaper)",
+		paramNoDedup: "true = skip scan's per-batch DEDUP_TASK (cheaper)",
+		paramNoSummary: "true = skip scan's post-run PROJECT_SUMMARY_TASK (cheaper)",
+		paramScanResume: "Resume a previously interrupted scan session id",
 		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",
+		paramSessionAction: "list: recent sessions (default) / show: one session / comments: comment list / compare: two sessions / export: HTML",
+		paramSessionId: "Session id for action=show/comments/export (export defaults to the newest)",
+		paramSessionBefore: "Required for action=compare: the older session id",
+		paramSessionAfter: "Required for action=compare: the newer session id",
+		paramSessionSeverity: "action=comments severity filter (critical/high/medium/low)",
+		paramSessionCategory: "action=comments category filter (e.g. bug/security)",
 		paramSessionLimit: "list cap 1-100 (default 10)",
+		paramRulesPath: "File path to look up (repo-relative or absolute; used only for rule matching)",
+		paramLlmAction: "providers: built-in provider list / models: ChatGPT account model list",
 		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)",
+		tuningTimeout: "Per-{unit} task timeout in minutes (OCR --timeout; review scales it by the effort round count, scan does not; 0 = unlimited; unset = OCR native 15)",
 		tuningMaxTools: "Per-{unit} tool-call round cap (OCR --max-tools; 0 = template default; 1-49 is raised to 50 by OCR, help text says min 50; unset = template default)",
 		tuningMaxToolsScan: "Per-{unit} tool-call round cap (OCR --max-tools; 0 = template default; only takes effect above the template default, never raised to 50; unset = template default)",
 		tuningMaxTokens: "Per-{unit} prompt token cap (OCR --max-tokens; 0 = config/template default; unset = template default)",
 		tuningMaxTokensBudget: "Total token (input+output) budget gate for this run; dispatch stops once exceeded (OCR --max-tokens-budget; 0 = unlimited; unset = unlimited)",
 		previewHint: "For each reviewable file, get its diff with git diff <merge_base>..<to> -- <path> (branch) / git show <commit> -- <path> (commit) / git diff HEAD -- <path>, or read the file directly (new workspace files).",
+		filePreviewHint: "This is a file-selection preview: no LLM call and no session were created. Drop preview and rerun to actually review. Lists are capped; when truncated=true, narrow the scope with exclude/path.",
 		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).",
+		sessionResumeHint: "To resume an interrupted range/commit review: ocr_review ... --resume <session_id> (workspace reviews cannot be resumed); scan sessions use ocr_scan ... --resume <session_id>.",
+		rulesCheckHint: "Source names the winning layer (--rule/project/global/built-in) and Pattern the glob; rules are first-match in declaration order.",
+		llmHint: "providers is the built-in catalogue; models is the ChatGPT account-specific list; the effective review provider/model still comes from OCR's own config.",
 		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).
@@ -299,7 +415,11 @@ const MESSAGES = {
   - 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
+  - preview=true on ocr_review / ocr_scan: list the file selection and exclusion reasons only — zero LLM, no session;
+    scan also supports noPlan/noDedup/noSummary to cut cost and resume to continue an interrupted scan.
+  - ocr_session: list/show/comments (severity/category filters)/compare (new/persisting/resolved/not_reviewed)/export.
+  - ocr_rules_check / ocr_llm: read-only diagnostics for rule resolution and the LLM catalogue; no review, no tokens.
+  - Unsure about the scope? Run ocr_delegate_preview or preview=true 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 the provider list of
   the host settings service (the key is read dynamically through api_key_cmd and never stored in plaintext);
@@ -317,7 +437,7 @@ const MESSAGES = {
   isolated and land in coverage.failedItems (in warnings when the output carries no manifest) instead of re-running
   everything. After a tool-layer timeout (min(request, the maxTimeoutMs setting of the shell executor itself,
   10 minutes by default) or partial file failures, use ocr_session to find the session_id and ocr_review --resume
-  to continue an interrupted range/commit review.
+  to continue an interrupted range/commit review, or ocr_scan --resume to continue a scan.
 `.trim()
 	}
 };
@@ -333,8 +453,7 @@ const PLACEHOLDER = /\{(?<key>\w+)\}/gu;
 function format(template, params) {
 	return template.replaceAll(PLACEHOLDER, (_all, key) => params[key] ?? "");
 }
-//#endregion
-//#region lib/output.ts
+// lib/output.ts
 /** 守卫支持的 schema 关键字（官方 enforced subset 的全部关键字，见
 *  installed dsh-tools lib/index.js:206；description/title/default/examples 是
 *  官方同样忽略的注解）。 */
@@ -352,14 +471,77 @@ const SUPPORTED_KEYWORDS = /* @__PURE__ */ new Set([
 	"default",
 	"examples"
 ]);
-/** schema 里的关键字必须全部落在守卫支持的子集内（递归查 oneOf/properties/items）。
-*  违例抛错而不是当违规值报：schema 是插件自己的代码，错的是代码不是模型的数据。 */
-function assertGuardable(schema, toolName, messages) {
+/** 官方子集只认这几个标量类型名（`SCHEMA_TYPES`）；`type` 写数组官方直接拒。 */
+const SCHEMA_TYPES = /* @__PURE__ */ new Set([
+	"object",
+	"array",
+	"string",
+	"number",
+	"integer",
+	"boolean",
+	"null"
+]);
+/**
+* schema 里的关键字必须全部落在守卫支持的子集内（递归查 oneOf/properties/items），
+* 关键字的**取值形态**也必须合法。
+*
+* 违例抛错而不是当违规值报：schema 是插件自己的代码，错的是代码不是模型的数据。
+*
+* 为什么取值形态也要查：只查键名的话，`type: ["string","null"]` 这种官方子集不认的
+* 写法会让 `scalarMismatch` 走进最后那支 `value !== null`——于是 `null` 放行、字符串
+* 反而判违规，守卫给出的结论与它自己声称支持的子集无关。`enum` 写成字符串同理：
+* 走到 `enum.includes` 时成了子串匹配，非字符串值还会抛 `map is not a function`。
+*/
+function malformed(toolName, detail, messages) {
+	return new Error(format(messages.resultSchemaMalformed, {
+		tool: toolName,
+		detail
+	}));
+}
+/** 关键字白名单：守卫只认官方子集，多一个都算插件自己的 schema 写错了。 */
+function assertKnownKeywords(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);
+}
+/** `type` 的取值形态：官方明确不接受类型数组，只收单个类型名。 */
+function assertTypeShape(type, toolName, messages) {
+	if (type === void 0) return;
+	if (typeof type === "string" && SCHEMA_TYPES.has(type)) return;
+	throw malformed(toolName, `type 必须是单个类型名（${[...SCHEMA_TYPES].join("/")}），收到 ${JSON.stringify(type)}`, messages);
+}
+/** `oneOf` 的取值形态：至少两项的分支数组（单项等价于直接写那个分支，多半是漏写了别的分支）。 */
+function assertOneOfShape(oneOf, toolName, messages) {
+	if (oneOf === void 0) return;
+	if (Array.isArray(oneOf) && oneOf.length >= 2) return;
+	throw malformed(toolName, "oneOf 必须是至少两项的数组", messages);
+}
+/** `enum` 的取值形态：非空数组。写成字符串时 `enum.includes` 会退化成子串匹配。 */
+function assertEnumShape(enumValues, toolName, messages) {
+	if (enumValues === void 0) return;
+	if (Array.isArray(enumValues) && enumValues.length > 0) return;
+	throw malformed(toolName, "enum 必须是非空数组", messages);
+}
+/**
+* schema 里的关键字必须全部落在守卫支持的子集内（递归查 oneOf/properties/items），
+* 关键字的**取值形态**也必须合法。
+*
+* 违例抛错而不是当违规值报：schema 是插件自己的代码，错的是代码不是模型的数据。
+*
+* 为什么取值形态也要查：只查键名的话，`type: ["string","null"]` 这种官方子集不认的
+* 写法会让 `scalarMismatch` 走进最后那支 `value !== null`——于是 `null` 放行、字符串
+* 反而判违规，守卫给出的结论与它自己声称支持的子集无关。`enum` 写成字符串同理：
+* 走到 `enum.includes` 时成了子串匹配，非字符串值还会抛 `map is not a function`。
+*/
+function assertGuardable(schema, toolName, messages) {
+	assertKnownKeywords(schema, toolName, messages);
+	const { type, oneOf, enum: enumValues } = schema;
+	if (type !== void 0 && oneOf !== void 0) throw malformed(toolName, "type 与 oneOf 不能同时声明", messages);
+	assertTypeShape(type, toolName, messages);
+	assertOneOfShape(oneOf, toolName, messages);
+	assertEnumShape(enumValues, toolName, messages);
+	for (const branch of Array.isArray(oneOf) ? 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);
@@ -421,8 +603,20 @@ const AUTH_HEADER_VALUE = /(?<name>\b(?:proxy-)?authorization["'\s]*[:=]["'\s]*)
 const BEARER_VALUE = /(?<scheme>\bbearer[ \t]+)[a-z0-9._~+/=-]{4,}/giu;
 /** `api_key: "xxx"`、`apiKey=xxx`、`token: xxx`、`x-api-key: xxx` 等赋值形态。
 *  值下限取 4 且容许一个 scheme 词：`token: Basic <base64>` 里赋值形态先能吃到的只是
-*  scheme 词（Basic 恰好 5 字符），下限更高时整条失配，后面那个 base64 就原样进了日志。 */
-const KEY_ASSIGNMENT = /(?<name>\b(?:api[_-]?key|apikey|access[_-]?key|secret[_-]?key|client[_-]?secret|password|token)["'\s]*[:=]["'\s]*)(?:(?<scheme>[a-z][a-z0-9_-]*[ \t]+))?[^\s"',;)}\]]{4,}/giu;
+*  scheme 词（Basic 恰好 5 字符），下限更高时整条失配，后面那个 base64 就原样进了日志。
+*
+*  左边界用 `(?<![A-Za-z0-9])` 而**不是** `\b`：`_` 也属 `\w`，`DEEPSEEK_API_KEY=` 里
+*  `KEY` 之前的那个位置对 `\b` 不成立，于是最常见的环境变量写法整条失配——而「把
+*  `XXX_API_KEY=…` 抹掉」正是这道闸最该管的一类。
+*
+*  字符类写 `[A-Z0-9]` 而不是 `[A-Za-z0-9]`：这条正则带 `i` 标志，两者等价，
+*  而重复的字符区间会让静态检查报 duplicates-in-character-class。 */
+const KEY_ASSIGNMENT = /(?<name>(?<![A-Z0-9])(?:api[_-]?key|apikey|access[_-]?key|secret[_-]?key|client[_-]?secret|password|token)["'\s]*[:=]["'\s]*)(?:(?<scheme>[a-z][a-z0-9_-]*[ \t]+))?[^\s"',;)}\]]{4,}/giu;
+/** GitHub 系 token 的**下划线**形态（`ghp_…`、`github_pat_…`）：STANDALONE_KEY 要求
+*  「字母前缀 + 连字符」分界，这类值里没有连字符，前缀后又紧跟下划线，故单列一条。
+*  不并进 STANDALONE_KEY 是为了不放开那里的连字符要求——那条要求同时承担「别把
+*  kebab 小写路径当 key 抹掉」的职责。 */
+const UNDERSCORE_TOKEN = /\b(?:gh[pousr]|github_pat)_[A-Za-z0-9_]{20,}\b/gu;
 const REDACTION = "***REDACTED***";
 /** 独立 key 形态的替换臂：随机串段里真有数字或大写才抹，否则原样交回（文件路径要保持可读）。 */
 function redactStandaloneKey(match) {
@@ -441,7 +635,7 @@ function redactStandaloneKey(match) {
 * 要求随机串特征，避免把要交给模型的文件路径一起抹掉。
 */
 function redactKeyMaterial(text) {
-	return text.replaceAll(AUTH_HEADER_VALUE, `$<name>$<scheme>${REDACTION}`).replaceAll(BEARER_VALUE, `$<scheme>${REDACTION}`).replaceAll(KEY_ASSIGNMENT, `$<name>$<scheme>${REDACTION}`).replaceAll(STANDALONE_KEY, redactStandaloneKey);
+	return text.replaceAll(AUTH_HEADER_VALUE, `$<name>$<scheme>${REDACTION}`).replaceAll(BEARER_VALUE, `$<scheme>${REDACTION}`).replaceAll(KEY_ASSIGNMENT, `$<name>$<scheme>${REDACTION}`).replaceAll(UNDERSCORE_TOKEN, REDACTION).replaceAll(STANDALONE_KEY, redactStandaloneKey);
 }
 /** ECMA-48 的 CSI 序列：ESC `[` + 参数位 + 中间位 + 终结位（SGR 颜色码就是终结位 `m`）。 */
 const ANSI_CSI = new RegExp(`${String.fromCodePoint(27)}\\[[0-?]*[ -/]*[@-~]`, "gu");
@@ -466,8 +660,8 @@ function violationsOf(schema, value, path) {
 		if (passing.length !== 1) violations.push(`${path}: matched ${passing.length} of ${oneOf.length} oneOf branches`);
 	}
 	const { type } = schema;
-	if (type === "object") violations.push(...objectViolations(schema, value, path, violationsOf));
-	else if (type === "array") violations.push(...arrayViolations(schema, value, path, violationsOf));
+	if (type === "object") for (const violation of objectViolations(schema, value, path, violationsOf)) violations.push(violation);
+	else if (type === "array") for (const violation of arrayViolations(schema, value, path, violationsOf)) violations.push(violation);
 	else if (type !== void 0 && scalarMismatch(type, value)) violations.push(`${path}: expected ${type}`);
 	if (schema.const !== void 0 && value !== schema.const) violations.push(`${path}: must be exactly ${JSON.stringify(schema.const)}`);
 	if (schema.enum !== void 0 && !schema.enum.includes(value)) violations.push(`${path}: must be one of ${schema.enum.map((entry) => JSON.stringify(entry)).join("/")}`);
@@ -498,8 +692,7 @@ function assertToolOutput(schema, value, toolName, messages) {
 	}
 	return value;
 }
-//#endregion
-//#region lib/argv-guard.ts
+// lib/argv-guard.ts
 /**
 * POSIX sh 单引号转义：' → '\''。把任意字符串安全放进单引号内，防注入。
 *
@@ -513,22 +706,96 @@ function shq(value) {
 	return `'${value.replaceAll("'", String.raw`'\''`)}'`;
 }
 /**
-* 绝对路径校验（macOS/Linux）：非空、trim 后以 / 开头、无 NUL 字节。
+* 绝对路径校验：非空、trim 后是绝对路径、无 NUL 字节；交出前按路径形态归一成唯一形态。
 *
 * 先 trim 再判：调用点会先 trim 再传进来，而直接调用 `args.repo` 的路径若带首尾空白，
 * 会被「必须是绝对路径」这条误导性文案拦下——读起来像是路径写错了格式，实际只是多了
 * 几个空格。顺带也挡住全空白（trim 后为空 ⇒ 触发 repoRequired）。
+*
+* 归一（posix.normalize + 去尾随斜杠）的目的：同一个仓库只允许一种字符串形态到达下游。
+* `/repo//sub`、`/repo/./a`、`/repo/` 与 `/repo/sub` 是同一目录的几种写法，而会话目录
+* 等按路径派生的键会把这些写法各存一份；`..` 段按词法折叠成实际目标（`/repo/../..`
+* 落到 `/`）——折叠是 normalize 对绝对路径的既有行为，不存在「解析后仍含 `..`」的
+* 形态，所以这里没有可写的拒绝分支。
 */
 function assertAbsoluteRoot(root, messages) {
 	const trimmed = typeof root === "string" ? root.trim() : "";
 	if (trimmed.length === 0) throw new Error(messages.repoRequired);
 	if (trimmed.includes("\0")) throw new Error(format(messages.noNulBytes, { name: "repo" }));
-	if (!trimmed.startsWith("/")) throw new Error(format(messages.repoMustBeAbsolute, { root: trimmed }));
-	return trimmed;
+	if (trimmed.startsWith("/")) {
+		const normalized = path.posix.normalize(trimmed);
+		return normalized.length > 1 ? normalized.replace(/\/+$/u, "") : normalized;
+	}
+	if (process.platform === "win32" && path.win32.isAbsolute(trimmed)) {
+		const normalized = path.win32.normalize(trimmed);
+		return normalized.length > 3 ? normalized.replace(/[\\/]+$/u, "") : normalized;
+	}
+	throw new Error(format(messages.repoMustBeAbsolute, { root: trimmed }));
+}
+/**
+* `--rule` / `--background-file` 的路径闸：只允许 repo 根内的普通文件。
+*
+* 这两个 flag 会把文件内容读进 OCR 并可能送给 LLM；OCR 子进程以
+* `danger-full-access` 运行，若放任 `../../.ssh/id_rsa` 之类的路径，一次工具调用就能
+* 把仓库外的文件送进模型。realpath 先解开符号链接再比较，`path.resolve` 的文本前缀
+* 判据挡不住指向仓库外的软链。
+*
+* @param root - 已校验为绝对路径的 repo 根
+* @param value - 模型给的路径（相对 repo 或绝对）
+* @param name - 参数名（报错点名）
+* @param maxBytes - 允许的字节上限
+* @param messages - 双语文案
+* @returns 归一后的绝对路径
+*/
+function resolveRepoFile(root, value, name, maxBytes, messages) {
+	if (typeof value !== "string") throw new TypeError(format(messages.mustBeString, {
+		name,
+		received: typeof value
+	}));
+	const text = value.trim();
+	if (text === "") throw new Error(format(messages.repoFileMissing, {
+		name,
+		path: ""
+	}));
+	if (text.includes("\0")) throw new Error(format(messages.noNulBytes, { name }));
+	let rootReal;
+	try {
+		rootReal = realpathSync(root);
+	} catch (error) {
+		throw new Error(format(messages.repoRootUnreadable, { path: root }), { cause: error });
+	}
+	let real;
+	try {
+		real = realpathSync(path.resolve(rootReal, text));
+	} catch (error) {
+		throw new Error(format(messages.repoFileMissing, {
+			name,
+			path: text
+		}), { cause: error });
+	}
+	const rel = path.relative(rootReal, real);
+	if (path.isAbsolute(rel) || rel === ".." || rel.startsWith(`..${path.sep}`)) throw new Error(format(messages.repoFileOutside, {
+		name,
+		path: text
+	}));
+	const stat = statSync(real);
+	if (!stat.isFile()) throw new Error(format(messages.repoFileNotFile, {
+		name,
+		path: text
+	}));
+	const { size } = stat;
+	if (size > maxBytes) throw new Error(format(messages.repoFileTooLarge, {
+		name,
+		path: text,
+		limit: String(maxBytes)
+	}));
+	return real;
 }
 /** limit 非法（NaN / ≤0 / 非整数）时的保守兜底上限：宁可比调用方的意图更严。 */
 const DEFAULT_LIST_LIMIT = 200;
+/** `auto` = 不传 `--effort`，让 OCR 自己的配置决定；工具 schema 仍只暴露三档。 */
 const EFFORTS = [
+	"auto",
 	"low",
 	"medium",
 	"high"
@@ -537,11 +804,28 @@ const EFFORTS = [
 function clampEffort(value, fallback) {
 	return EFFORTS.find((level) => level === value) ?? fallback;
 }
+/** 字符串里第一个落在 glob 花括号内的逗号位置（没有则 -1）。 */
+function firstCommaInsideBraces(text) {
+	let depth = 0;
+	for (let index = 0; index < text.length; index += 1) {
+		const ch = text[index];
+		if (ch === "{") depth += 1;
+		else if (ch === "}" && depth > 0) depth -= 1;
+		else if (ch === "," && depth > 0) return index;
+	}
+	return -1;
+}
 /** 入参 → 原始项序列（commaList 的第一段：只判「值从哪来」，不判内容）。
 *  数组分支保留逐元素 for-of 而不是 `value.map`：map 会跳过稀疏数组的空洞，
 *  空洞本是「非字符串元素」这一条该拦的形态，跳过就等于静默少一项过滤条件。 */
 function listSourceItems(value, name, messages) {
-	if (typeof value === "string") return value.split(",");
+	if (typeof value === "string") {
+		if (firstCommaInsideBraces(value) >= 0) throw new TypeError(format(messages.commaInStringBraces, {
+			name,
+			item: value
+		}));
+		return value.split(",");
+	}
 	if (Array.isArray(value)) {
 		const items = [];
 		for (const item of value) {
@@ -567,14 +851,15 @@ function takeTrimmedItems(items, name, limit, messages) {
 		if (trimmed.length > 0 && out.length >= cap) dropped += 1;
 		else if (trimmed.length > 0) out.push(trimmed);
 	}
-	if (dropped > 0) throw new Error(format(messages.listTruncated, {
+	if (dropped > 0) throw new Error(format(messages.listOverLimit, {
 		name,
 		dropped: String(dropped),
 		limit: String(cap)
 	}));
 	return out;
 }
-/** 字符串数组 → 逗号拼接（--exclude/--path 契约）。
+/** 入参 → 规范化条目数组（--exclude/--path 契约）。返回值是**条目数组**；把数组按逗号
+*  拼接成 flag 值由调用点负责（lib/cli.ts 的 `shq(excludes.join(","))`）。
 *  元素类型严格：`value.map(String)` 会把对象变成 `[object Object]` 静默混入
 *  模式串（过滤条件失效 = 审查范围被扩大），故非字符串元素一律抛错。
 *  防注入由调用点 shq() 兜底。 */
@@ -601,8 +886,7 @@ const REVIEW_OUTPUT_FORMATS = [
 function resolveOutputFormat(value) {
 	return REVIEW_OUTPUT_FORMATS.find((candidate) => candidate === value) ?? "json";
 }
-//#endregion
-//#region lib/cli.ts
+// lib/cli.ts
 /** `ocr review|scan|delegate preview` 的背景说明 flag（三处命令构造共用一条）。
 *  pushTextFlag 按 `flag.slice(2)` 反推报错用的参数名，故值必须带 `--` 前缀。 */
 /** `--exclude` 的模式条数上限。**不是审查范围的上限**，只是防一条失控输入把命令串撑爆；
@@ -610,6 +894,10 @@ function resolveOutputFormat(value) {
 const EXCLUDE_LIST_LIMIT = 2e3;
 /** `--path` 的路径条数上限（同 EXCLUDE_LIST_LIMIT 的取向：够大 + 超限告警）。 */
 const PATH_LIST_LIMIT = 2e3;
+/** `--rule` / `--background-file` 的文件大小上限：规则是检查清单，背景是需求文档。 */
+const RULE_FILE_MAX_BYTES = 262144;
+const BACKGROUND_FILE_MAX_BYTES = 1048576;
+const MAX_GIT_PROCS_FLAG = "--max-git-procs";
 const BACKGROUND_FLAG = "--background";
 /**
 * 本包的契约是按外部 `ocr` CLI 的哪一版核对的（README 的前置条件、装法建议与工具回显里
@@ -620,19 +908,27 @@ const BACKGROUND_FLAG = "--background";
 * test/readme-parity.test.ts 再断言两侧 README 写的也是它。三处只有一处是人写的、
 * 靠门禁钉住另两处，就不会出现「README 教用户装 A、代码按 B 校验」这种两边各自自洽的错。
 */
-const EXPECTED_OCR_CLI_VERSION = "1.13.0";
-/** 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);
-}
+const EXPECTED_OCR_CLI_VERSION = "1.13.3";
 /** 报错用的值形态（永不调用可能被劫持的 toJSON/toString）。host.ts 的入参闸
 *  （effort/wait）复用同一口径，故导出。 */
 function describeValue(value) {
 	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
 	return Array.isArray(value) ? "array" : typeof value;
 }
+/** root 解析：显式绝对路径优先；缺失/空串回退到当前会话工作区。
+*
+* 错类型必须抛错，不能落进 fallback：宿主对工具入参零校验（见 `idValue` 的说明），
+* `{repo: 123}` 静默回退成当前会话工作区，等于「调用方明确指定了仓库」被换成另一个
+* 仓库去审，而回执里不会留下任何痕迹。空串/缺省才是「没指定」。 */
+function resolveRoot(value, fallback, messages) {
+	if (value !== void 0 && value !== null && typeof value !== "string") throw new TypeError(format(messages.mustBeString, {
+		name: "repo",
+		received: describeValue(value)
+	}));
+	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);
+}
 /** 字符串标量参数：键存在即必须是字符串。
 *
 * 为什么拒绝而不是忽略：宿主对工具入参零校验（dsh tools index.ts
@@ -685,17 +981,73 @@ function pushIntFlag(parts, flag, value, min, messages) {
 	}));
 	parts.push(flag, String(num));
 }
+/** 布尔 flag：undefined/null 视为 false；其余非布尔值抛错（字符串 "false" 不能当真值）。 */
+function boolFlag(value, name, messages) {
+	if (value === void 0 || value === null) return false;
+	if (typeof value !== "boolean") throw new TypeError(format(messages.boolMustBeBoolean, {
+		name,
+		received: describeValue(value)
+	}));
+	return value;
+}
+function pushBoolFlag(parts, flag, value, name, messages) {
+	if (boolFlag(value, name, messages)) parts.push(flag);
+}
+/** `--rule` / `--background-file`：缺省/空串视为未给；其余交给路径闸（repo 根内普通文件）。 */
+function repoFileOf(value, repo, name, maxBytes, messages) {
+	if (value === void 0 || value === null) return null;
+	if (typeof value === "string" && value.trim() === "") return null;
+	return resolveRepoFile(repo, value, name, maxBytes, messages);
+}
+/** 预览与正常审查共用的选择面：exclude、rule、max-git-procs。 */
+function selectionFlags(args, repo, messages) {
+	const parts = [];
+	const excludes = commaList(args.exclude, "exclude", EXCLUDE_LIST_LIMIT, messages);
+	if (excludes.length > 0) parts.push("--exclude", shq(excludes.join(",")));
+	const rule = repoFileOf(args.rule, repo, "rule", RULE_FILE_MAX_BYTES, messages);
+	if (rule !== null) parts.push("--rule", shq(rule));
+	pushIntFlag(parts, MAX_GIT_PROCS_FLAG, args.maxGitProcs, 1, messages);
+	return parts;
+}
 /** 模式参数解析：workspace（默认）/commit/branch 互斥，非法组合与错类型抛错。
 *
 * 互斥判定必须在两个模式分支之前一次做完：若先判 commit（`commit 非空` 时条件
 * 恒真），后面的「branch 与 commit 互斥」就永不可达，`{scope:branch, commit:x}`
 * 会被静默降级成 commit 审查——审错范围却按结论上报。 */
-function scopeFlags(args, messages) {
+const KNOWN_SCOPES = /* @__PURE__ */ new Set([
+	"workspace",
+	"commit",
+	"branch"
+]);
+/** 与 `scope` 冲突时报告的是哪一种范围参数（两者都没给时返回空串）。 */
+function otherScopeOf(commit, from, to) {
+	if (commit !== "") return "commit";
+	return from === "" && to === "" ? "" : "from/to";
+}
+/**
+* `scope` 是**声明**，不是从别的参数反推出来的结论：先按 from/to/commit 推模式再看
+* scope，`{scope:"nope", from:"a", to:"b"}` 会被当成 branch 静默放行，而调用方声明的
+* 范围与真正审的范围不是一回事。
+*/
+function declaredScopeOf(args, messages) {
 	const scopeName = idValue(args.scope, "scope", messages).toLowerCase();
-	const scope = scopeName === "" ? "workspace" : scopeName;
+	if (scopeName === "") return "workspace";
+	if (!KNOWN_SCOPES.has(scopeName)) throw new Error(format(messages.unknownScope, { scope: scopeName }));
+	return scopeName;
+}
+function scopeFlags(args, messages) {
+	const scope = declaredScopeOf(args, messages);
+	const explicit = idValue(args.scope, "scope", messages) !== "";
 	const from = idValue(args.from, "from", messages);
 	const to = idValue(args.to, "to", messages);
 	const commit = idValue(args.commit, "commit", messages);
+	if (explicit && scope === "workspace") {
+		const given = otherScopeOf(commit, from, to);
+		if (given !== "") throw new Error(format(messages.scopeMismatch, {
+			scope,
+			given
+		}));
+	}
 	const wantsBranch = scope === "branch" || from !== "" || to !== "";
 	const wantsCommit = scope === "commit" || commit !== "";
 	if (wantsBranch && wantsCommit) throw new Error(messages.scopeBranchCommitExclusive);
@@ -712,7 +1064,6 @@ function scopeFlags(args, messages) {
 		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：值缺省/空串则省略，错类型抛错（静默丢弃等于悄悄改变语义）。 */
@@ -996,6 +1347,7 @@ function jsonOnlyFormat(value, messages) {
 function buildReviewCommand(args, outputPath, messages) {
 	const repo = assertAbsoluteRoot(args.repo, messages);
 	const outputFormat = jsonOnlyFormat(args.format, messages);
+	const preview = boolFlag(args.preview, "preview", messages);
 	const parts = [
 		ocrCommand(),
 		"review",
@@ -1004,8 +1356,18 @@ function buildReviewCommand(args, outputPath, messages) {
 		"--format",
 		outputFormat
 	];
+	const resume = idValue(args.resume, "resume", messages);
+	if (preview) {
+		if (resume !== "") throw new Error(messages.previewRejectsResume);
+		parts.push("--preview", ...scopeFlags(args, messages), ...selectionFlags(args, repo, messages));
+		if (outputPath !== void 0) parts.push("--output", shq(outputPath));
+		return {
+			command: parts.join(" "),
+			workdir: repo
+		};
+	}
 	const effort = clampEffort(args.effort, "medium");
-	parts.push("--effort", effort);
+	if (effort !== "auto") 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);
@@ -1013,7 +1375,12 @@ function buildReviewCommand(args, outputPath, messages) {
 	pushIntFlag(parts, "--max-tokens-budget", args.maxTokensBudget, 0, messages);
 	const scopeParts = scopeFlags(args, messages);
 	parts.push(...scopeParts, ...optionalFlags(args, messages));
-	const resume = idValue(args.resume, "resume", messages);
+	pushBoolFlag(parts, "--no-filter", args.noFilter, "noFilter", messages);
+	const rule = repoFileOf(args.rule, repo, "rule", RULE_FILE_MAX_BYTES, messages);
+	if (rule !== null) parts.push("--rule", shq(rule));
+	const backgroundFile = repoFileOf(args.backgroundFile, repo, "backgroundFile", BACKGROUND_FILE_MAX_BYTES, messages);
+	if (backgroundFile !== null) parts.push("--background-file", shq(backgroundFile));
+	pushIntFlag(parts, MAX_GIT_PROCS_FLAG, args.maxGitProcs, 1, messages);
 	if (resume !== "") {
 		if (scopeParts.length === 0) throw new Error(messages.resumeNeedsScope);
 		parts.push("--resume", shq(resume));
@@ -1031,6 +1398,9 @@ function buildReviewCommand(args, outputPath, messages) {
 function buildScanCommand(args, outputPath, messages) {
 	const repo = assertAbsoluteRoot(args.repo, messages);
 	const outputFormat = jsonOnlyFormat(args.format, messages);
+	const preview = boolFlag(args.preview, "preview", messages);
+	const resume = idValue(args.resume, "resume", messages);
+	if (preview && resume !== "") throw new Error(messages.previewRejectsResume);
 	const parts = [
 		ocrCommand(),
 		"scan",
@@ -1039,19 +1409,25 @@ function buildScanCommand(args, outputPath, messages) {
 		"--format",
 		outputFormat
 	];
+	if (preview) parts.push("--preview");
 	const paths = commaList(args.path, "path", PATH_LIST_LIMIT, messages);
 	if (paths.length > 0) parts.push("--path", shq(paths.join(",")));
-	const excludes = commaList(args.exclude, "exclude", EXCLUDE_LIST_LIMIT, messages);
-	if (excludes.length > 0) parts.push("--exclude", shq(excludes.join(",")));
-	pushTextFlag(parts, "--batch", args.batch, messages);
-	pushTextFlag(parts, "--provider", args.provider, messages);
-	pushTextFlag(parts, "--model", args.model, messages);
-	pushIntFlag(parts, "--concurrency", args.concurrency, 1, messages);
-	pushIntFlag(parts, "--timeout", args.timeoutMinutes, 0, messages);
-	pushIntFlag(parts, "--max-tools", args.maxTools, 0, messages);
-	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 (!preview) {
+		pushTextFlag(parts, "--batch", args.batch, messages);
+		pushTextFlag(parts, "--provider", args.provider, messages);
+		pushTextFlag(parts, "--model", args.model, messages);
+		pushIntFlag(parts, "--concurrency", args.concurrency, 1, messages);
+		pushIntFlag(parts, "--timeout", args.timeoutMinutes, 0, messages);
+		pushIntFlag(parts, "--max-tools", args.maxTools, 0, messages);
+		pushIntFlag(parts, "--max-tokens", args.maxTokens, 0, messages);
+		pushIntFlag(parts, "--max-tokens-budget", args.maxTokensBudget, 0, messages);
+		pushBoolFlag(parts, "--no-plan", args.noPlan, "noPlan", messages);
+		pushBoolFlag(parts, "--no-dedup", args.noDedup, "noDedup", messages);
+		pushBoolFlag(parts, "--no-summary", args.noSummary, "noSummary", messages);
+		if (resume !== "") parts.push("--resume", shq(resume));
+	}
+	parts.push(...selectionFlags(args, repo, messages));
+	if (!preview) pushTextFlag(parts, BACKGROUND_FLAG, args.background, messages);
 	if (outputPath !== void 0) parts.push("--output", shq(outputPath));
 	return {
 		command: parts.join(" "),
@@ -1076,6 +1452,11 @@ function buildDelegatePreviewCommand(args, messages) {
 	const excludes = commaList(args.exclude, "exclude", EXCLUDE_LIST_LIMIT, messages);
 	if (excludes.length > 0) parts.push("--exclude", shq(excludes.join(",")));
 	pushTextFlag(parts, BACKGROUND_FLAG, args.background, messages);
+	const backgroundFile = repoFileOf(args.backgroundFile, repo, "backgroundFile", BACKGROUND_FILE_MAX_BYTES, messages);
+	if (backgroundFile !== null) parts.push("--background-file", shq(backgroundFile));
+	const rule = repoFileOf(args.rule, repo, "rule", RULE_FILE_MAX_BYTES, messages);
+	if (rule !== null) parts.push("--rule", shq(rule));
+	pushIntFlag(parts, MAX_GIT_PROCS_FLAG, args.maxGitProcs, 1, messages);
 	return {
 		command: parts.join(" "),
 		workdir: repo
@@ -1086,25 +1467,74 @@ 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);
+	const parts = [
+		ocrCommand(),
+		"delegate",
+		"rule",
+		"--format",
+		"json"
+	];
+	const rule = repoFileOf(args.rule, repo, "rule", RULE_FILE_MAX_BYTES, messages);
+	if (rule !== null) parts.push("--rule", shq(rule));
+	parts.push("--", ...paths);
+	return {
+		command: parts.join(" "),
+		workdir: repo
+	};
+}
+/** `ocr rules check <file>`：只做规则解析，不跑 LLM；`path` 是待查询的文件路径。 */
+function buildRulesCheckCommand(args, messages) {
+	const repo = assertAbsoluteRoot(args.repo, messages);
+	const filePath = idValue(args.path, "path", messages);
+	if (filePath === "") throw new Error(messages.rulesPathRequired);
+	const parts = [
+		ocrCommand(),
+		"rules",
+		"check",
+		"--repo",
+		shq(repo)
+	];
+	const rule = repoFileOf(args.rule, repo, "rule", RULE_FILE_MAX_BYTES, messages);
+	if (rule !== null) parts.push("--rule", shq(rule));
+	parts.push("--", shq(filePath));
 	return {
-		command: [
-			ocrCommand(),
-			"delegate",
-			"rule",
-			"--format",
-			"json",
-			"--",
-			...paths
-		].join(" "),
+		command: parts.join(" "),
 		workdir: repo
 	};
 }
-/** session 子命令白名单（子命令名裸拼进命令串，只可能是这三个字面量）。 */
+/** `ocr llm providers|models`：只读诊断命令，不需要仓库目录。 */
+function buildLlmCommand(action) {
+	const sub = action === "providers" ? "providers" : "models";
+	return `${ocrCommand()} llm ${sub} --color never`;
+}
+/** `ocr auth status`：卡片只读查询 ChatGPT 登录态。 */
+function buildAuthStatusCommand() {
+	return `${ocrCommand()} auth status --provider chatgpt --color never`;
+}
+/** 登录动作保持人工执行（OAuth 要浏览器 + 本地回调），卡片只显示这条命令。 */
+const CHATGPT_LOGIN_COMMAND = "ocr auth login --provider chatgpt";
+/** session 子命令白名单（子命令名裸拼进命令串，只可能是这些字面量）。 */
 const SESSION_ACTIONS = [
 	"list",
 	"show",
-	"comments"
+	"comments",
+	"compare",
+	"export"
+];
+const SESSION_SEVERITIES = [
+	"critical",
+	"high",
+	"medium",
+	"low"
 ];
+/** severity 过滤：大小写归一 + 白名单；未知值报错而不是交给 CLI 返回空集。 */
+function severityFilter(value, messages) {
+	return commaList(value, "severity", SESSION_SEVERITIES.length, messages).map((item) => {
+		const lower = item.toLowerCase();
+		if (!SESSION_SEVERITIES.includes(lower)) throw new Error(format(messages.invalidSeverity, { value: item }));
+		return lower;
+	});
+}
 /** session list --limit：缺省 10（OCR 原生默认 20，本包收紧；OCR 的 0=不限在本包
 * 上限 100 下无意义）。显式给出时必须是 1-100 的整数（与工具 description 的承诺
 * 一致），越界/错类型抛错而不是钳制——静默钳到 1 会把「想看更多」的 0 变成
@@ -1115,35 +1545,135 @@ function sessionLimit(value, messages) {
 	if (num === null || num < 1 || num > 100) throw new Error(format(messages.sessionLimitRange, { received: describeValue(value) }));
 	return num;
 }
-/** 构造 `ocr session list/show/comments` 命令（历史评审会话闭环，Json 输出）。 */
+function sessionListParts(ctx) {
+	if (ctx.id !== "") throw new Error(ctx.messages.listRejectsId);
+	if (ctx.before !== "" || ctx.after !== "") throw new Error(ctx.messages.beforeAfterOnlyForCompare);
+	if (ctx.hasFilters) throw new Error(ctx.messages.filtersOnlyForComments);
+	return [
+		ocrCommand(),
+		"session",
+		"list",
+		"--json",
+		"--repo",
+		shq(ctx.repo),
+		"--limit",
+		String(sessionLimit(ctx.limit, ctx.messages))
+	];
+}
+function sessionCompareParts(ctx) {
+	if (ctx.before === "" || ctx.after === "") throw new Error(ctx.messages.compareNeedsBoth);
+	if (ctx.id !== "" || ctx.limit !== void 0 && ctx.limit !== null || ctx.hasFilters) throw new Error(ctx.messages.compareRejectsArgs);
+	return [
+		ocrCommand(),
+		"session",
+		"compare",
+		"--json",
+		"--repo",
+		shq(ctx.repo),
+		"--",
+		shq(ctx.before),
+		shq(ctx.after)
+	];
+}
+function sessionExportParts(ctx) {
+	if (ctx.before !== "" || ctx.after !== "" || ctx.limit !== void 0 && ctx.limit !== null) throw new Error(ctx.messages.exportRejectsArgs);
+	if (ctx.hasFilters) throw new Error(ctx.messages.filtersOnlyForComments);
+	if (ctx.output === "") throw new Error(ctx.messages.exportOutputRequired);
+	const parts = [
+		ocrCommand(),
+		"session",
+		"export",
+		"--repo",
+		shq(ctx.repo),
+		"-o",
+		shq(ctx.output)
+	];
+	if (ctx.id !== "") parts.push("--", shq(ctx.id));
+	return parts;
+}
+function sessionCommentsParts(ctx) {
+	if (ctx.before !== "" || ctx.after !== "") throw new Error(ctx.messages.beforeAfterOnlyForCompare);
+	if (ctx.id === "") {
+		if (ctx.hasFilters) throw new Error(ctx.messages.filtersNeedId);
+		return sessionListParts({
+			...ctx,
+			hasFilters: false
+		});
+	}
+	const parts = [
+		ocrCommand(),
+		"session",
+		"comments",
+		"--json",
+		"--repo",
+		shq(ctx.repo)
+	];
+	if (ctx.severities.length > 0) parts.push("--severity", shq(ctx.severities.join(",")));
+	if (ctx.categories.length > 0) parts.push("--category", shq(ctx.categories.join(",")));
+	parts.push("--", shq(ctx.id));
+	return parts;
+}
+function sessionShowParts(ctx) {
+	if (ctx.before !== "" || ctx.after !== "") throw new Error(ctx.messages.beforeAfterOnlyForCompare);
+	if (ctx.hasFilters) throw new Error(ctx.messages.filtersOnlyForComments);
+	if (ctx.id === "") return sessionListParts({
+		...ctx,
+		hasFilters: false
+	});
+	return [
+		ocrCommand(),
+		"session",
+		"show",
+		"--json",
+		"--repo",
+		shq(ctx.repo),
+		"--",
+		shq(ctx.id)
+	];
+}
+const SESSION_BUILDERS = {
+	list: sessionListParts,
+	compare: sessionCompareParts,
+	export: sessionExportParts,
+	comments: sessionCommentsParts,
+	show: sessionShowParts
+};
+function sessionPartsOf(sub, ctx) {
+	return SESSION_BUILDERS[sub](ctx);
+}
+function inferSessionAction(requested, ctx) {
+	if (requested !== void 0) return requested;
+	if (ctx.before !== "" || ctx.after !== "") return "compare";
+	return ctx.id === "" ? "list" : "show";
+}
+/** 构造 `ocr session list/show/comments/compare/export` 命令（历史评审会话闭环）。 */
 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("/")
 	}));
-	if (requested === "list" && id !== "") throw new Error(messages.listRejectsId);
-	let sub;
-	if (requested === "comments" || requested === "show") sub = id === "" ? "list" : requested;
-	else if (requested === "list") sub = "list";
-	else sub = id === "" ? "list" : "show";
-	const parts = [
-		ocrCommand(),
-		"session",
-		sub
-	];
-	if (sub === "list") parts.push("--json", "--repo", shq(repo), "--limit", String(sessionLimit(args.limit, messages)));
-	else parts.push("--json", "--repo", shq(repo), shq(id));
+	const ctx = {
+		repo,
+		id: idValue(args.id, "id", messages),
+		before: idValue(args.before, "before", messages),
+		after: idValue(args.after, "after", messages),
+		severities: severityFilter(args.severity, messages),
+		categories: commaList(args.category, "category", 50, messages),
+		hasFilters: false,
+		limit: args.limit,
+		output: idValue(args.output, "output", messages),
+		messages
+	};
+	ctx.hasFilters = ctx.severities.length > 0 || ctx.categories.length > 0;
 	return {
-		command: parts.join(" "),
+		command: sessionPartsOf(inferSessionAction(requested, ctx), ctx).join(" "),
 		workdir: repo
 	};
 }
-//#endregion
-//#region lib/severity.ts
+// lib/severity.ts
 const SEVERITY_ORDER = [
 	"critical",
 	"high",
@@ -1162,7 +1692,7 @@ const SEVERITY_ORDER = [
 * known 一并回传：归一是「必须发生」的降级，但降级本身不该是**无痕**的——调用方要能
 * 统计出「有多少条走了兜底」，否则契约异常被彻底吞掉，聚合里看不出来、排序里也看不出来。
 */
-function normalizeSeverity(severity) {
+function classifySeverity(severity) {
 	const matched = SEVERITY_ORDER.find((level) => level === severity.trim().toLowerCase());
 	return {
 		level: matched ?? "medium",
@@ -1171,7 +1701,7 @@ function normalizeSeverity(severity) {
 }
 /** 排序位：critical→high→medium→low（未知已归 medium，永不为 -1）。 */
 function severityRank(severity) {
-	return SEVERITY_ORDER.indexOf(normalizeSeverity(severity).level);
+	return SEVERITY_ORDER.indexOf(classifySeverity(severity).level);
 }
 /** 聚合评论：按严重度/类别计数。severity 归类以 critical→high→medium→low 基准。 */
 function aggregateComments(comments) {
@@ -1184,10 +1714,11 @@ function aggregateComments(comments) {
 	const categoryCounts = /* @__PURE__ */ new Map();
 	let unknownSeverityCount = 0;
 	for (const comment of comments) {
-		const { level, known } = normalizeSeverity(comment.severity);
+		const { level, known } = classifySeverity(comment.severity);
 		bySeverity[level] += 1;
 		if (!known) unknownSeverityCount += 1;
-		if (comment.category) categoryCounts.set(comment.category, (categoryCounts.get(comment.category) ?? 0) + 1);
+		const category = comment.category.trim();
+		if (category !== "") categoryCounts.set(category, (categoryCounts.get(category) ?? 0) + 1);
 	}
 	const byCategory = Object.fromEntries(categoryCounts);
 	return {
@@ -1197,16 +1728,19 @@ function aggregateComments(comments) {
 		unknownSeverityCount
 	};
 }
-//#endregion
-//#region lib/parse.ts
+// lib/parse.ts
 /**
 * OCR 评审 JSON 的 status 枚举（判据在 CLI 侧 `cmd/opencodereview/output.go` 的 jsonOutput
 * 装配与 `internal/session/manifest.go` 的 TerminalState）。
 * 白名单外的一律视为失败：exit 0 不等于评审成功——`{"error":"auth failed"}`
 * 这类「没有 status 的错误对象」若被当作 ok:true，模型会把「0 条评论」读成
-* 「代码干净」，是最坏的一类假阳性。`failed` 也刻意留在白名单外：CLI 的退出契约是
-* 「全场失败才非零」（`review_cmd.go` 的 reviewResultError），那份文档随非零退出
-* 一起被 shell 侧的失败详情拦下，本解析拿不到它。
+* 「代码干净」，是最坏的一类假阳性。
+*
+* `failed` 在名单里，但**单独判成 ok:false**（见 `parseReviewOutput`）。两件事要分开：
+* ① 名字得认——非零退出时 CLI 照发的那份 manifest 就带 `status:"failed"`，
+* `withCoverageDetail` 要靠它读出「哪些文件没审成」；不认这个值就等于把失败明细整条丢掉。
+* ② 认了不等于成功——万一它带着 exit 0 回来，把它当 ok:true 就会把一份全场失败的回执
+* 摘要成「0 条评论」，那正是本段开头要避免的假阳性。
 *
 * partial 是 manifest 终态之一：部分文件失败但整体有覆盖、以及 token 预算截断后仍有
 * 覆盖，都以 exit 0 + status "partial" 输出。此前白名单漏了它，整场已花费 token 的
@@ -1240,9 +1774,8 @@ function str(value) {
 * 故作兜底值。
 */
 function nonNegativeInt(value) {
-	const truncated = Math.trunc(value);
-	if (!Number.isSafeInteger(truncated) || truncated < 0) return 0;
-	return truncated;
+	if (!Number.isSafeInteger(value) || value < 0) return 0;
+	return value;
 }
 /** 数值字段解析：number 与「数字字符串」都接受（OCR 部分 provider 实测把 start_line
 *  输出成 "42"，一律当 0 会把真实评论判成「未锚定」而被摘要丢掉），空串/NaN/Infinity/
@@ -1265,6 +1798,42 @@ const DIAGNOSTIC_DETAIL_LIMIT = 8;
 function boolOf(value) {
 	return value === true;
 }
+/** 走 plan 预算/工具轮次上限的两枚警告：它们是「限流截断」的唯一结构化信号。 */
+const LIMIT_WARNING_TYPES = /* @__PURE__ */ new Set(["review_limit_reached", "token_budget_reached"]);
+/** 把 project_summary 截到摘要预算内；截断事实单独带出，别让模型把半截当全文。 */
+const PROJECT_SUMMARY_LIMIT = 4e3;
+/** `llm` 身份：两个字段都读不出时回 null，而不是造一个空模型。 */
+function llmOf(raw) {
+	if (!isRecord(raw)) return null;
+	const provider = str(raw["provider"]).trim();
+	const model = str(raw["model"]).trim();
+	if (provider === "" && model === "") return null;
+	return {
+		provider: provider === "" ? null : provider,
+		model
+	};
+}
+/** `resume` 回执：字段全空时回 null（CLI 只在真的续审时发这个对象）。 */
+function retryOf(raw) {
+	if (!isRecord(raw)) return null;
+	const view = {
+		totalRetries: num(raw["total_retries"]),
+		recoveredRequests: num(raw["recovered_requests"]),
+		failedRequests: num(raw["failed_requests"])
+	};
+	return view.totalRetries === 0 && view.recoveredRequests === 0 && view.failedRequests === 0 ? null : view;
+}
+function resumeOf(raw) {
+	if (!isRecord(raw)) return null;
+	const view = {
+		resumedFrom: str(raw["resumed_from"]),
+		reusedFiles: num(raw["reused_files"]),
+		rerunFiles: num(raw["rerun_files"]),
+		previousModel: str(raw["previous_model"]),
+		currentModel: str(raw["current_model"])
+	};
+	return view.resumedFrom === "" && view.reusedFiles === 0 && view.rerunFiles === 0 && view.previousModel === "" && view.currentModel === "" ? null : view;
+}
 /**
 * 明细行收尾：截断时补一条「另有 N 条已省略」，让读的人知道后面还有，而不是以为看到了全部。
 * @param lines - 已渲染的明细行
@@ -1401,6 +1970,14 @@ function reviewFailure(status, message) {
 		skipped: false,
 		summary: null,
 		budgetExceeded: false,
+		limitReached: false,
+		llm: null,
+		projectSummary: null,
+		projectSummaryTruncated: false,
+		resume: null,
+		groupCount: 0,
+		retry: null,
+		traceId: null,
 		comments: [],
 		warnings: [],
 		toolCalls: null,
@@ -1423,9 +2000,13 @@ function reviewFailure(status, message) {
 */
 function diagnosticsOf(root, messages) {
 	const warnings = [];
+	let limitReached = false;
 	const warningsRaw = root["warnings"];
 	if (warningsRaw !== void 0) {
-		if (Array.isArray(warningsRaw)) for (const warn of warningsRaw) warnings.push(warningLineOf(warn, messages));
+		if (Array.isArray(warningsRaw)) for (const warn of warningsRaw) {
+			warnings.push(warningLineOf(warn, messages));
+			limitReached ||= isRecord(warn) && LIMIT_WARNING_TYPES.has(str(warn["type"]));
+		}
 		else warnings.push(messages.warningUnreadable);
 	}
 	const toolCalls = toolCallsOf(root["tool_calls"], messages);
@@ -1435,7 +2016,8 @@ function diagnosticsOf(root, messages) {
 	return {
 		warnings,
 		toolCalls: toolCalls.view,
-		coverage: coverage.view
+		coverage: coverage.view,
+		limitReached
 	};
 }
 /**
@@ -1469,13 +2051,17 @@ function parseReviewOutput(text, messages) {
 		else comments.push(comment);
 	}
 	const skipped = status === "skipped";
+	const ok = status !== "failed";
+	const message = str(root["message"]) || (ok ? "" : messages.ocrStatusFailed);
 	const sumRaw = root["summary"];
 	const sum = isRecord(sumRaw) ? sumRaw : void 0;
 	const diagnostics = diagnosticsOf(root, messages);
+	const rawProjectSummary = str(root["project_summary"]);
+	const projectSummaryTruncated = rawProjectSummary.length > PROJECT_SUMMARY_LIMIT;
 	return {
-		ok: true,
+		ok,
 		status,
-		message: str(root["message"]),
+		message,
 		skipped,
 		summary: sum ? {
 			filesReviewed: num(sum["files_reviewed"]),
@@ -1483,9 +2069,19 @@ function parseReviewOutput(text, messages) {
 			totalTokens: num(sum["total_tokens"]),
 			inputTokens: num(sum["input_tokens"]),
 			outputTokens: num(sum["output_tokens"]),
+			cacheReadTokens: num(sum["cache_read_tokens"]),
+			cacheWriteTokens: num(sum["cache_write_tokens"]),
 			elapsed: str(sum["elapsed"])
 		} : null,
 		budgetExceeded: sum === void 0 ? false : boolOf(sum["budget_exceeded"]),
+		limitReached: diagnostics.limitReached,
+		llm: llmOf(root["llm"]),
+		projectSummary: rawProjectSummary === "" ? null : rawProjectSummary.slice(0, PROJECT_SUMMARY_LIMIT),
+		projectSummaryTruncated,
+		resume: resumeOf(root["resume"]),
+		groupCount: Array.isArray(root["groups"]) ? root["groups"].length : 0,
+		retry: retryOf(root["retry_report"]),
+		traceId: str(root["trace_id"]) || null,
 		comments,
 		warnings: diagnostics.warnings,
 		toolCalls: diagnostics.toolCalls,
@@ -1521,6 +2117,14 @@ function summarizeReview(parsed, messages, plan = DEFAULT_PLAN) {
 		message: parsed.message || null,
 		summary: parsed.summary ?? null,
 		budgetExceeded: parsed.budgetExceeded,
+		limitReached: parsed.limitReached,
+		llm: parsed.llm,
+		projectSummary: parsed.projectSummary,
+		projectSummaryTruncated: parsed.projectSummaryTruncated,
+		resume: parsed.resume,
+		groupCount: parsed.groupCount,
+		retry: parsed.retry,
+		traceId: parsed.traceId,
 		sessionId: parsed.sessionId || null,
 		aggregation: agg,
 		totalCommentCount: parsed.comments.length,
@@ -1677,327 +2281,1034 @@ function parseDelegateRules(text) {
 		groups
 	};
 }
-//#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";
-/**
-* llm-pi-ai 的 `api` 协议 → OCR config 的 `protocol` 映射。
-*
-* 两侧枚举的对照（dsh packages/llm/llm-pi-ai/src/provider.ts:44-48 的 PROTOCOLS
-* 对 OCR config_cmd.go:796 的 "Protocol values: anthropic, anthropic-bedrock,
-* openai, openai-responses"）：openai-completions 与 OCR 的 openai 是同一条
-* OpenAI Chat Completions 线协议；anthropic-messages 即 OCR 的 anthropic。
-* 此前「非 openai-responses 一律 openai」的二值映射会把 anthropic-messages 的
-* 端点按 OpenAI 线协议打出去——select 成功、OCR 调不通。表外值透传，让
-* renderSelectedConfig 的白名单给出可读错误。
-*/
-const OCR_PROTOCOL_BY_API = /* @__PURE__ */ new Map([
-	["openai-completions", "openai"],
-	["openai-responses", "openai-responses"],
-	["anthropic-messages", "anthropic"]
-]);
-/** 对象/数组形态的 `api` 的透传标记：可读，但绝不会被误认成任何合法协议名。 */
-const API_UNREADABLE = "[unreadable]";
+/** 预览列表的条数上限：整仓扫描可能列出几千个文件，摘要只留足以判断范围的一截。 */
+const PREVIEW_FILE_LIMIT = 200;
+function previewFileOf(raw) {
+	if (!isRecord(raw)) return null;
+	const filePath = str(raw["path"]);
+	if (filePath === "") return null;
+	return {
+		path: filePath,
+		status: str(raw["status"]),
+		insertions: num(raw["insertions"]),
+		deletions: num(raw["deletions"]),
+		willReview: raw["will_review"] === true,
+		excludeReason: str(raw["exclude_reason"])
+	};
+}
 /**
-* settings 里的 `api` 字段 → 协议查表用的键。
+* 解析 `ocr review --preview --format json` / `ocr scan --preview --format json`。
 *
-* 三种形态必须分开，否则畸形声明会被静默降级成「能用的」配置：
-*   - 未声明（undefined / null）⇒ ""，交给 llm-pi-ai 的 openai-completions 兜底语义；
-*   - 字符串 ⇒ trim 后原样（表外值原样透传，由写侧白名单拒绝）；
-*   - 数字 / 布尔 ⇒ String()，同样落进「表外值」这条正路；
-*   - 对象 / 数组 ⇒ 固定标记。用 String(raw) 会走 Object.prototype.toString 得到
-*     "[object Object]"，那既无信息量又看着像协议名；显式标记更能说明「这里读不出来」。
+* 预览是 `model.Preview` 的裸对象（键 `files`），与 review/scan 的摘要**不是**同一
+* 形状；把它喂给 parseReviewOutput 只会得到一条解析失败。契约键一个都不命中、或
+* 条目全是坏形状时判失败，不能报成「0 个文件可审」。
 */
-function apiKeyOf(raw) {
-	if (raw === void 0 || raw === null) return "";
-	if (typeof raw === "string") return raw.trim();
-	if (typeof raw === "number" || typeof raw === "boolean") return String(raw);
-	return API_UNREADABLE;
+function parsePreviewOutput(text) {
+	let doc;
+	try {
+		doc = JSON.parse(text);
+	} catch {
+		return {
+			ok: false,
+			view: null
+		};
+	}
+	if (!isRecord(doc) || !Array.isArray(doc["files"])) return {
+		ok: false,
+		view: null
+	};
+	const parsed = doc["files"].map((entry) => previewFileOf(entry)).filter((entry) => entry !== null);
+	if (doc["files"].length > 0 && parsed.length === 0) return {
+		ok: false,
+		view: null
+	};
+	const reviewable = parsed.filter((entry) => entry.willReview);
+	const excluded = parsed.filter((entry) => !entry.willReview);
+	const countOf = (key, fallback) => {
+		const raw = doc[key];
+		return isCount(raw) ? num(raw) : fallback;
+	};
+	return {
+		ok: true,
+		view: {
+			totalFiles: countOf("total_files", parsed.length),
+			reviewableCount: countOf("reviewable_count", reviewable.length),
+			excludedCount: countOf("excluded_count", excluded.length),
+			totalInsertions: num(doc["total_insertions"]),
+			totalDeletions: num(doc["total_deletions"]),
+			reviewableFiles: reviewable.slice(0, PREVIEW_FILE_LIMIT),
+			excludedFiles: excluded.slice(0, PREVIEW_FILE_LIMIT),
+			truncated: reviewable.length > PREVIEW_FILE_LIMIT || excluded.length > PREVIEW_FILE_LIMIT
+		}
+	};
 }
-/** 原始 model 对象 → DshModel（缺 id 视为无效，返回 null）。 */
-function modelFromRaw(modelRaw) {
-	if (!isRecord(modelRaw)) return null;
-	const rec = modelRaw;
-	const id = typeof rec["id"] === "string" ? rec["id"].trim() : "";
-	if (!id) return null;
-	const name = typeof rec["name"] === "string" ? rec["name"].trim() : "";
+/** 每个桶的展示上限：四桶全铺开会把 compare 变成第二份全量评论。 */
+const COMPARE_BUCKET_LIMIT = 20;
+function compareSideOf(raw) {
 	return {
-		id,
-		name: name === "" ? id : name
+		sessionId: isRecord(raw) ? str(raw["session_id"]) : "",
+		reviewMode: isRecord(raw) ? str(raw["review_mode"]) : "",
+		range: isRecord(raw) ? str(raw["range"]) : ""
 	};
 }
-/** 原始 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 api = apiKeyOf(entry["api"]);
-	const protocol = api === "" ? "openai" : OCR_PROTOCOL_BY_API.get(api) ?? api;
-	const baseURL = typeof entry["baseURL"] === "string" ? entry["baseURL"].trim() : "";
-	if (!baseURL) return null;
-	const models = Array.isArray(entry["models"]) ? entry["models"].map(modelFromRaw).filter((model) => model !== null) : [];
+function compareCommentOf(raw) {
+	const comment = commentOf(raw);
+	if (comment === null) return null;
 	return {
-		name,
-		displayName: typeof entry["displayName"] === "string" && entry["displayName"] ? entry["displayName"] : name,
-		apiKeyEnv,
-		protocol,
-		baseURL,
-		models
+		location: locationOf(comment),
+		severity: comment.severity,
+		category: comment.category,
+		content: comment.content
 	};
 }
-/**
-* settings 命名空间解析值 → provider 列表（纯投影，不含任何 key 值）。
-* 上游形状（settings 里 llm-pi-ai.providers.<name>）：
-*   { displayName?, apiKeyEnv?, api: openai-completions|openai-responses|anthropic-messages,
-*     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 = Object.freeze({
-	status: "ready",
-	message: ""
-});
-/** settings 通道侧抛错（health / descriptors / 投影三处共用同一状态与同一份文案）。 */
-const SOURCE_SETTINGS_FAILED = "settings-failed";
-/**
-* 读 provider 清单并把一切失败折进 source（不抛）：会话热路径与卡片读面
-* 都只消费返回值，服务缺席/抛错时卡片仍能显示原因。
-*/
-function readProviders(gateway, messages) {
-	let health;
-	try {
-		health = gateway.health();
-	} catch (error) {
-		return {
-			providers: [],
-			source: {
-				status: SOURCE_SETTINGS_FAILED,
-				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
-			}
-		};
-	}
-	if (!health.settings) return {
-		providers: [],
-		source: {
-			status: "settings-unavailable",
-			message: messages.sourceSettingsUnavailable
-		}
+/** 一个 compare 桶：缺失/非数组判整个 compare 失败，部分条目坏只丢该条并计入 dropped。 */
+function compareBucketOf(raw) {
+	if (!Array.isArray(raw)) return null;
+	return {
+		items: raw.map((entry) => compareCommentOf(entry)).filter((entry) => entry !== null).slice(0, COMPARE_BUCKET_LIMIT),
+		total: raw.length
 	};
-	let descriptors;
+}
+/** 解析 `ocr session compare --json`：四个桶与两侧会话标识。 */
+function parseSessionCompare(text) {
+	let doc;
 	try {
-		descriptors = gateway.descriptors();
-	} catch (error) {
+		doc = JSON.parse(text);
+	} catch {
 		return {
-			providers: [],
-			source: {
-				status: SOURCE_SETTINGS_FAILED,
-				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
-			}
+			ok: false,
+			view: null
 		};
 	}
-	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 })
-		}
-	};
-	if (!isRecord(fieldOf(hit.value, "providers"))) return {
-		providers: [],
-		source: {
-			status: "namespace-unavailable",
-			message: format(messages.sourceNamespaceUnavailable, { ns: PI_AI_NAMESPACE })
-		}
+	if (!isRecord(doc)) return {
+		ok: false,
+		view: null
 	};
-	let providers;
-	try {
-		providers = providersFromSettingsValue(hit.value);
-	} catch (error) {
-		return {
-			providers: [],
-			source: {
-				status: SOURCE_SETTINGS_FAILED,
-				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
-			}
-		};
-	}
-	if (!health.credentials) return {
-		providers,
-		source: {
-			status: "credentials-unavailable",
-			message: messages.sourceCredentialsUnavailable
-		}
+	const newBucket = compareBucketOf(doc["new"]);
+	const persisting = compareBucketOf(doc["persisting"]);
+	const resolved = compareBucketOf(doc["resolved"]);
+	const notReviewed = compareBucketOf(doc["not_reviewed"]);
+	if (newBucket === null || persisting === null || resolved === null || notReviewed === null) return {
+		ok: false,
+		view: null
 	};
+	const droppedCount = newBucket.total + persisting.total + resolved.total + notReviewed.total - (newBucket.items.length + persisting.items.length + resolved.items.length + notReviewed.items.length);
 	return {
-		providers,
-		source: SOURCE_READY
+		ok: true,
+		view: {
+			before: compareSideOf(doc["before"]),
+			after: compareSideOf(doc["after"]),
+			new: newBucket.items,
+			persisting: persisting.items,
+			resolved: resolved.items,
+			notReviewed: notReviewed.items,
+			counts: {
+				new: newBucket.total,
+				persisting: persisting.total,
+				resolved: resolved.total,
+				notReviewed: notReviewed.total
+			},
+			droppedCount
+		}
 	};
 }
-/** 逐 provider 问凭据服务「有没有 key」（并行；只回布尔）。 */
-async function markKeyFlags(gateway, providers) {
-	return await Promise.all(providers.map(async (providerCfg) => {
-		const ref = providerCfg.apiKeyEnv;
-		if (ref === null || ref === "") return {
-			...providerCfg,
-			hasKey: false
-		};
-		const hasKey = await gateway.credentialConfigured(ref).catch(() => false);
-		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")) : ""
+// lib/tool-schemas.ts
+/** 可空 string 字段的 schema 片段（官方子集单类型，null 分支用 oneOf 表达）。 */
+const NULLABLE_STRING = { oneOf: [{ type: "string" }, { type: "null" }] };
+/** ocr_review / ocr_scan 的 wait=false 回执（startBackground 的返回对象）。 */
+const BACKGROUND_RECEIPT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"started",
+		"mode",
+		"tool",
+		"repo",
+		"processStatus",
+		"jobId",
+		"polling"
+	],
+	properties: {
+		started: {
+			type: "boolean",
+			const: true
 		},
-		raw: doc
-	};
-}
-/** config.json 的当前文本（读不到/不存在一律空串，交由 loadOcrConfig 的宽容读侧处理）。 */
-function readText(configPath) {
-	try {
-		return readFileSync(configPath, "utf8");
-	} catch {
-		return "";
-	}
-}
-/**
-* api_key_cmd 内嵌值的转义。POSIX 走单引号（ocr 在 Unix 用 `sh -c` 跑 api_key_cmd，
-* keycmd_unix.go）；Windows 的 ocr 用 **cmd.exe** 跑它（keycmd_windows.go），单引号
-* 在那里是普通字符、命令必坏，故走双引号：值内 `"` 翻倍、收尾反斜杠再翻倍（防被
-* CommandLineToArgvW 当成转义吃掉收尾引号）。ref 名白名单 `^[A-Z0-9_]+$` 不含两种
-* 引号；脚本与数据目录是盘上常规路径。已知残留：cmd.exe 会对双引号内的 `%VAR%`
-* 做环境展开，路径含 `%` 的 Windows 部署需自行规避（Windows 非目标平台，此处只
-* 保证常规路径形态正确）。
-*/
-function shqDyn(value) {
-	if (process.platform === "win32") return `"${value.replaceAll("\"", "\"\"").replace(/\\+$/u, (backslashes) => backslashes + backslashes)}"`;
-	return `'${value.replaceAll("'", String.raw`'\''`)}'`;
-}
-/** api_key_cmd 值构造：脚本路径与 env key 名（及可选的 dsh 数据目录）shq 转义后
-*  拼成 shell 命令。第三参数是 get-cred.mjs 数据目录定位的**第一档**（显式参数 >
-*  $DSH_HOME > homedir()/.dsh）：ocrConfigPath 重定向 ocr 子进程的 HOME 后，
-*  get-cred 的 homedir() 兜底会跟着跑偏，须在宿主侧把解析出的数据目录显式钉进
-*  命令。undefined（未重定向）时省略，沿用 env/默认档。
-*  env key 白名单维持 ^[A-Z0-9_]+$（刻意比宿主 CredentialRef 的语法紧：OCR 侧
-*  惯例大写，且这是写进 config.json 的可信输入）。 */
-function buildApiKeyCmd(scriptPath, envKey, dshHome, messages) {
-	if (!/^[A-Z0-9_]+$/u.test(envKey)) throw new Error(format(messages.badEnvKey, { key: envKey }));
-	const parts = [
-		"node",
-		shqDyn(scriptPath),
-		shqDyn(envKey)
-	];
-	if (dshHome !== void 0) parts.push(shqDyn(dshHome));
-	return parts.join(" ");
-}
-/**
-* 读一个 shq 单引号串：解出它的值与结束位置。
-*
-* 认的是 shqDyn 自己写出的转义形态——值里的单引号被写成四字符的 '\''。所以遇到
-* 单引号时，只有后面紧跟这四字符才算转义，否则是真闭合。未闭合（串被截断）返回
-* undefined：宁可判「读不懂」，也不要把半截命令当成可信输入。
-*/
-function readShqToken(text, start) {
-	let value = "";
-	let i = start + 1;
-	let closed = false;
-	while (i < text.length && !closed) {
-		const ch = text[i];
-		if (ch === "'" && text.startsWith(String.raw`'\''`, i)) {
-			value += "'";
-			i += 4;
-		} else if (ch === "'") {
-			closed = true;
-			i += 1;
-		} else {
-			value += ch;
-			i += 1;
-		}
+		mode: {
+			type: "string",
+			const: "background"
+		},
+		tool: { type: "string" },
+		repo: { type: "string" },
+		processStatus: {
+			type: "string",
+			enum: [
+				"running",
+				"completed",
+				"killed"
+			]
+		},
+		jobId: { type: "string" },
+		polling: { type: "string" }
 	}
-	return closed ? {
-		value,
-		next: i
-	} : null;
-}
-/** shq 串 → token 列表；形态不符（未闭合 / 出现裸词）返回 null。 */
-function readShqTokens(body) {
-	const tokens = [];
-	let i = 0;
-	let malformed = false;
-	while (i < body.length && !malformed) {
-		while (i < body.length && (body[i] === " " || body[i] === "	")) i += 1;
-		if (i >= body.length) break;
-		if (body[i] === "'") {
-			const token = readShqToken(body, i);
-			if (token === null) malformed = true;
-			else {
-				tokens.push(token.value);
-				i = token.next;
+};
+/** summarizeReview(...) 的对象形状（lib/parse.ts 的 ReviewSummaryView，逐字段对齐）。 */
+const REVIEW_SUMMARY_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"status",
+		"skipped",
+		"message",
+		"summary",
+		"budgetExceeded",
+		"limitReached",
+		"llm",
+		"projectSummary",
+		"projectSummaryTruncated",
+		"resume",
+		"groupCount",
+		"retry",
+		"traceId",
+		"sessionId",
+		"aggregation",
+		"totalCommentCount",
+		"droppedCount",
+		"invalidCommentCount",
+		"topComments",
+		"warnings",
+		"toolCalls",
+		"coverage",
+		"hint"
+	],
+	properties: {
+		status: {
+			type: "string",
+			enum: [
+				"success",
+				"complete",
+				"partial",
+				"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",
+				"cacheReadTokens",
+				"cacheWriteTokens",
+				"elapsed"
+			],
+			properties: {
+				filesReviewed: { type: "number" },
+				comments: { type: "number" },
+				totalTokens: { type: "number" },
+				inputTokens: { type: "number" },
+				outputTokens: { type: "number" },
+				cacheReadTokens: { type: "number" },
+				cacheWriteTokens: { type: "number" },
+				elapsed: { type: "string" }
 			}
-		} else malformed = true;
-	}
-	return malformed ? null : tokens;
-}
-/**
-* 读一个 cmd.exe 双引号串：解出它的值与结束位置（`""` 是翻倍的引号）。
-* 未闭合返回 null：宁可判「读不懂」，也不把半截命令当可信输入。
-*/
-function readDqToken(body, start) {
-	let value = "";
-	let i = start + 1;
-	let closed = false;
-	while (i < body.length && !closed) {
-		const ch = body[i];
-		if (ch === "\"" && body[i + 1] === "\"") {
-			value += "\"";
-			i += 2;
+		}] },
+		budgetExceeded: { type: "boolean" },
+		limitReached: { type: "boolean" },
+		llm: { oneOf: [{ type: "null" }, {
+			type: "object",
+			additionalProperties: false,
+			required: ["provider", "model"],
+			properties: {
+				provider: NULLABLE_STRING,
+				model: { type: "string" }
+			}
+		}] },
+		projectSummary: NULLABLE_STRING,
+		projectSummaryTruncated: { type: "boolean" },
+		groupCount: { type: "integer" },
+		retry: { oneOf: [{ type: "null" }, {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"totalRetries",
+				"recoveredRequests",
+				"failedRequests"
+			],
+			properties: {
+				totalRetries: { type: "number" },
+				recoveredRequests: { type: "number" },
+				failedRequests: { type: "number" }
+			}
+		}] },
+		traceId: NULLABLE_STRING,
+		resume: { oneOf: [{ type: "null" }, {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"resumedFrom",
+				"reusedFiles",
+				"rerunFiles",
+				"previousModel",
+				"currentModel"
+			],
+			properties: {
+				resumedFrom: { type: "string" },
+				reusedFiles: { type: "number" },
+				rerunFiles: { type: "number" },
+				previousModel: { type: "string" },
+				currentModel: { type: "string" }
+			}
+		}] },
+		sessionId: NULLABLE_STRING,
+		aggregation: {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"total",
+				"bySeverity",
+				"byCategory",
+				"unknownSeverityCount"
+			],
+			properties: {
+				total: { type: "integer" },
+				unknownSeverityCount: { 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" }
+		},
+		toolCalls: { oneOf: [{ type: "null" }, {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"total",
+				"failure",
+				"failures"
+			],
+			properties: {
+				total: { type: "integer" },
+				failure: { type: "integer" },
+				failures: {
+					type: "array",
+					items: { type: "string" }
+				}
+			}
+		}] },
+		coverage: { oneOf: [{ type: "null" }, {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"selected",
+				"completed",
+				"reused",
+				"failed",
+				"waived",
+				"failedItems"
+			],
+			properties: {
+				selected: { type: "integer" },
+				completed: { type: "integer" },
+				reused: { type: "integer" },
+				failed: { type: "integer" },
+				waived: { type: "integer" },
+				failedItems: {
+					type: "array",
+					items: { type: "string" }
+				}
+			}
+		}] },
+		hint: { type: "string" }
+	}
+};
+/** review/scan `preview:true` 的文件清单对象（lib/parse.ts 的 PreviewView）。 */
+const PREVIEW_FILE_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"path",
+		"status",
+		"insertions",
+		"deletions",
+		"willReview",
+		"excludeReason"
+	],
+	properties: {
+		path: { type: "string" },
+		status: { type: "string" },
+		insertions: { type: "number" },
+		deletions: { type: "number" },
+		willReview: { type: "boolean" },
+		excludeReason: { type: "string" }
+	}
+};
+/** ocr_review / ocr_scan 的输出：wait=false = 后台回执对象；前台成功 = 摘要对象；
+*  preview=true = 文件预览对象；前台解析失败 = 一段诚实的说明字符串。四者恰一。 */
+const REVIEW_OUTPUT_SCHEMA = { oneOf: [
+	BACKGROUND_RECEIPT_SCHEMA,
+	REVIEW_SUMMARY_SCHEMA,
+	{
+		type: "object",
+		additionalProperties: false,
+		required: [
+			"totalFiles",
+			"reviewableCount",
+			"excludedCount",
+			"totalInsertions",
+			"totalDeletions",
+			"reviewableFiles",
+			"excludedFiles",
+			"truncated",
+			"hint"
+		],
+		properties: {
+			totalFiles: { type: "number" },
+			reviewableCount: { type: "number" },
+			excludedCount: { type: "number" },
+			totalInsertions: { type: "number" },
+			totalDeletions: { type: "number" },
+			reviewableFiles: {
+				type: "array",
+				items: PREVIEW_FILE_SCHEMA
+			},
+			excludedFiles: {
+				type: "array",
+				items: PREVIEW_FILE_SCHEMA
+			},
+			truncated: { type: "boolean" },
+			hint: { type: "string" }
+		}
+	},
+	{ type: "string" }
+] };
+/** ocr_delegate_preview：成功 = 清单对象；解析失败 = 说明字符串。 */
+const PREVIEW_OUTPUT_SCHEMA = { oneOf: [{
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"mode",
+		"repository",
+		"mergeBase",
+		"reviewableCount",
+		"insertions",
+		"deletions",
+		"reviewableFiles",
+		"excludedFiles",
+		"hint"
+	],
+	properties: {
+		mode: { type: "string" },
+		repository: { type: "string" },
+		mergeBase: NULLABLE_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_RAW_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	required: ["sessionOutput", "hint"],
+	properties: {
+		sessionOutput: { type: "string" },
+		hint: { type: "string" }
+	}
+};
+/** compare 的结构化四桶（lib/parse.ts 的 CompareView）。 */
+const COMPARE_COMMENT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"location",
+		"severity",
+		"category",
+		"content"
+	],
+	properties: {
+		location: { type: "string" },
+		severity: { type: "string" },
+		category: { type: "string" },
+		content: { type: "string" }
+	}
+};
+const COMPARE_SIDE_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"sessionId",
+		"reviewMode",
+		"range"
+	],
+	properties: {
+		sessionId: { type: "string" },
+		reviewMode: { type: "string" },
+		range: { type: "string" }
+	}
+};
+const SESSION_OUTPUT_SCHEMA = { oneOf: [SESSION_RAW_SCHEMA, {
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"before",
+		"after",
+		"new",
+		"persisting",
+		"resolved",
+		"notReviewed",
+		"counts",
+		"droppedCount",
+		"hint"
+	],
+	properties: {
+		before: COMPARE_SIDE_SCHEMA,
+		after: COMPARE_SIDE_SCHEMA,
+		new: {
+			type: "array",
+			items: COMPARE_COMMENT_SCHEMA
+		},
+		persisting: {
+			type: "array",
+			items: COMPARE_COMMENT_SCHEMA
+		},
+		resolved: {
+			type: "array",
+			items: COMPARE_COMMENT_SCHEMA
+		},
+		notReviewed: {
+			type: "array",
+			items: COMPARE_COMMENT_SCHEMA
+		},
+		counts: {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"new",
+				"persisting",
+				"resolved",
+				"notReviewed"
+			],
+			properties: {
+				new: { type: "integer" },
+				persisting: { type: "integer" },
+				resolved: { type: "integer" },
+				notReviewed: { type: "integer" }
+			}
+		},
+		droppedCount: { type: "integer" },
+		hint: { type: "string" }
+	}
+}] };
+/** rules check / llm 这类只读文本诊断工具：一手输出 + hint。 */
+const TEXT_OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	required: ["output", "hint"],
+	properties: {
+		output: { type: "string" },
+		hint: { type: "string" }
+	}
+};
+// lib/routing.ts
+const ROUTING_NAME = "ocr-review-routing";
+const ROUTING_ORDER = 1555;
+// lib/provider-projection.ts
+/** llm-pi-ai 命名空间里 provider 表的字段名。 */
+const PROVIDERS_FIELD = "providers";
+/**
+* llm-pi-ai 的 `api` 协议 → OCR config 的 `protocol` 映射。
+*
+* 两侧枚举的对照（dsh packages/llm/llm-pi-ai/src/provider.ts:44-48 的 PROTOCOLS
+* 对 OCR config_cmd.go:796 的 "Protocol values: anthropic, anthropic-bedrock,
+* openai, openai-responses"）：openai-completions 与 OCR 的 openai 是同一条
+* OpenAI Chat Completions 线协议；anthropic-messages 即 OCR 的 anthropic。
+* 此前「非 openai-responses 一律 openai」的二值映射会把 anthropic-messages 的
+* 端点按 OpenAI 线协议打出去——select 成功、OCR 调不通。表外值透传，让
+* renderSelectedConfig 的白名单给出可读错误。
+*/
+/** Map 而非对象字面量：查表键来自用户可写的 settings 值，对象会继承 Object.prototype，
+*  于是 api="constructor" 取到 Object 这个构造函数、"__proto__" 取到 Object.prototype，
+*  `?? api` 的原样透传兜底失效——protocol 被写成函数/对象，直接违反 `DshProvider.protocol
+*  的 string 声明，还会让 apply 侧的白名单错误文案里出现 "function toString() { [native
+*  code] }"。Map.get 不查原型链，这两类键安全 miss 并落回「原样透传」这条正路。
+*  provider 名那一侧的同款防护见文件下方的 UNUSABLE_PROVIDER_NAMES。 */
+const OCR_PROTOCOL_BY_API = /* @__PURE__ */ new Map([
+	["openai-completions", "openai"],
+	["openai-responses", "openai-responses"],
+	["anthropic-messages", "anthropic"]
+]);
+/** 不能落进 config.json `custom_providers.<name>` 的 provider 名：`__proto__` 在普通对象
+*  上是 setter（赋值被静默忽略、写入凭空丢失），`constructor` / `prototype` 是继承属性
+*  名，与写侧的普通对象赋值组合都不是普通自有键。空名/全空白名单独由 trim 判据拦。 */
+const UNUSABLE_PROVIDER_NAMES = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/** 1.13.3 的 `validateProviderName` 口径：点号分段不能为空或全空白。 */
+function isUsableProviderName(name) {
+	if (UNUSABLE_PROVIDER_NAMES.has(name)) return false;
+	return name.split(".").every((segment) => segment.trim() !== "");
+}
+/** 对象/数组形态的 `api` 的透传标记：可读，但绝不会被误认成任何合法协议名。 */
+const API_UNREADABLE = "[unreadable]";
+/**
+* settings 里的 `api` 字段 → 协议查表用的键；「未声明」以 null 表达。
+*
+* 四种形态必须分开，否则畸形声明会被静默降级成「能用的」配置：
+*   - 未声明（undefined / null）⇒ null，交给 llm-pi-ai 的 openai-completions 兜底语义；
+*   - 字符串 ⇒ trim 后原样，**含空串**（表外值原样透传，由写侧白名单拒绝——显式
+*     `api: ""` 在上游同样不走 `??` 默认，兜底它等于把畸形声明改写成可用配置）；
+*   - 数字 / 布尔 ⇒ String()，同样落进「表外值」这条正路；
+*   - 对象 / 数组 ⇒ 固定标记。用 String(raw) 会走 Object.prototype.toString 得到
+*     "[object Object]"，那既无信息量又看着像协议名；显式标记更能说明「这里读不出来」。
+*/
+function apiKeyOf(raw) {
+	if (raw === void 0 || raw === null) return null;
+	if (typeof raw === "string") return raw.trim();
+	if (typeof raw === "number" || typeof raw === "boolean") return String(raw);
+	return API_UNREADABLE;
+}
+/** 原始 model 对象 → DshModel（缺 id 视为无效，返回 null）。 */
+function modelFromRaw(modelRaw) {
+	if (!isRecord(modelRaw)) return null;
+	const rec = modelRaw;
+	const id = typeof rec["id"] === "string" ? rec["id"].trim() : "";
+	if (!id) return null;
+	const name = typeof rec["name"] === "string" ? rec["name"].trim() : "";
+	return {
+		id,
+		name: name === "" ? id : name
+	};
+}
+/** 原始 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 api = apiKeyOf(entry["api"]);
+	const protocol = api === null ? "openai" : OCR_PROTOCOL_BY_API.get(api) ?? api;
+	const baseURL = typeof entry["baseURL"] === "string" ? entry["baseURL"].trim() : "";
+	if (!baseURL || !/^https?:\/\//iu.test(baseURL)) return null;
+	const modelsRaw = Array.isArray(entry["models"]) ? entry["models"] : [];
+	const models = modelsRaw.map((model) => modelFromRaw(model)).filter((model) => model !== null);
+	if (modelsRaw.length > 0 && models.length === 0) return null;
+	const displayName = typeof entry["displayName"] === "string" ? entry["displayName"].trim() : "";
+	return {
+		name,
+		displayName: displayName === "" ? name : displayName,
+		apiKeyEnv,
+		protocol,
+		baseURL,
+		models
+	};
+}
+/**
+* settings 命名空间解析值 → provider 列表（纯投影，不含任何 key 值）。
+* 上游形状（settings 里 llm-pi-ai.providers.<name>）：
+*   { displayName?, apiKeyEnv?, api: openai-completions|openai-responses|anthropic-messages,
+*     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 = isUsableProviderName(name) ? providerFromRaw(name, raw) : null;
+		if (parsed !== null) out.push(parsed);
+	}
+	return out;
+}
+// lib/provider-source.ts
+/** provider 清单所在的官方 settings 命名空间（base bundle 的 pi-ai 适配器注册）。 */
+const PI_AI_NAMESPACE = "llm-pi-ai";
+const SOURCE_READY = Object.freeze({
+	status: "ready",
+	message: ""
+});
+/** settings 通道侧抛错（health / descriptors / 投影三处共用同一状态与同一份文案）。 */
+const SOURCE_SETTINGS_FAILED = "settings-failed";
+/**
+* 读 provider 清单并把一切失败折进 source（不抛）：会话热路径与卡片读面
+* 都只消费返回值，服务缺席/抛错时卡片仍能显示原因。
+*/
+function readProviders(gateway, messages) {
+	let health;
+	try {
+		health = gateway.health();
+	} catch (error) {
+		return {
+			providers: [],
+			source: {
+				status: SOURCE_SETTINGS_FAILED,
+				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
+			}
+		};
+	}
+	if (!health.settings) return {
+		providers: [],
+		source: {
+			status: "settings-unavailable",
+			message: messages.sourceSettingsUnavailable
+		}
+	};
+	let descriptors;
+	try {
+		descriptors = gateway.descriptors();
+	} catch (error) {
+		return {
+			providers: [],
+			source: {
+				status: SOURCE_SETTINGS_FAILED,
+				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
+			}
+		};
+	}
+	let hit;
+	try {
+		if (!Array.isArray(descriptors)) throw new TypeError(`ctx.settings.describe() 没有给出数组（收到 ${typeof descriptors}）`);
+		hit = descriptors.find((descriptor) => descriptor.ns === PI_AI_NAMESPACE);
+	} catch (error) {
+		return {
+			providers: [],
+			source: {
+				status: SOURCE_SETTINGS_FAILED,
+				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
+			}
+		};
+	}
+	if (hit === void 0) return {
+		providers: [],
+		source: {
+			status: "namespace-unavailable",
+			message: format(messages.sourceNamespaceUnavailable, { ns: PI_AI_NAMESPACE })
+		}
+	};
+	const providersValue = fieldOf(hit.value, "providers");
+	if (!isRecord(providersValue)) return {
+		providers: [],
+		source: {
+			status: "namespace-unavailable",
+			message: format(messages.sourceNamespaceUnavailable, { ns: PI_AI_NAMESPACE })
+		}
+	};
+	let providers;
+	try {
+		providers = providersFromSettingsValue(hit.value);
+	} catch (error) {
+		return {
+			providers: [],
+			source: {
+				status: SOURCE_SETTINGS_FAILED,
+				message: format(messages.sourceSettingsFailed, { message: errorText(error) })
+			}
+		};
+	}
+	if (!health.credentials) return {
+		providers,
+		source: {
+			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 ref = providerCfg.apiKeyEnv;
+		if (ref === null || ref === "") return {
+			...providerCfg,
+			hasKey: false
+		};
+		let hasKey;
+		try {
+			hasKey = await gateway.credentialConfigured(ref);
+		} catch {
+			hasKey = false;
+		}
+		return {
+			...providerCfg,
+			hasKey
+		};
+	}));
+}
+// 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 的当前文本，读不到一律空串。
+*
+*  只给「读侧要宽容」的那一类调用用（设置卡打开时渲染当前选择：盘上文件坏了也必须
+*  能打开卡片，用户正是靠卡片去修）。**写侧不能用它**——把 EACCES/EIO 折成空串等于
+*  把「读不到」当成「文件不存在」，随后整份覆盖就丢掉了用户既有的全部配置；写侧走
+*  readExistingText。 */
+function readText(configPath) {
+	try {
+		return readFileSync(configPath, "utf8");
+	} catch {
+		return "";
+	}
+}
+/** 文件不存在是正常态（首写、被用户删掉），其余读失败不是。 */
+function isNotFound$1(error) {
+	return isRecord(error) && fieldOf(error, "code") === "ENOENT";
+}
+/** 写侧专用：把「文件不存在 / 内容为空」与「文件读不动」分开。
+*
+*  前者返回空串，`parseExistingConfig` 依约给出 `{}`，写出来的就是只含本次选择的
+*  新文档；后者必须抛错——这一层往下是「读 → 改 → 整份写回」，把读不到当成空文档
+*  会让一次瞬时 EIO 变成用户全部 providers / keys / mcp_servers / language 被覆盖，
+*  而备份（`.bak`）也救不了第二次。 */
+function readExistingText(configPath, messages) {
+	try {
+		return readFileSync(configPath, "utf8");
+	} catch (error) {
+		if (isNotFound$1(error)) return "";
+		throw new Error(format(messages.configUnreadable, {
+			where: configPath,
+			cause: errorText(error)
+		}), { cause: error });
+	}
+}
+/**
+* api_key_cmd 内嵌值的转义。POSIX 走单引号（ocr 在 Unix 用 `sh -c` 跑 api_key_cmd，
+* keycmd_unix.go）；Windows 的 ocr 用 **cmd.exe** 跑它（keycmd_windows.go），单引号
+* 在那里是普通字符、命令必坏，故走双引号：值内 `"` 翻倍、收尾反斜杠再翻倍（防被
+* CommandLineToArgvW 当成转义吃掉收尾引号）。ref 名白名单 `^[A-Z0-9_]+$` 不含两种
+* 引号；脚本与数据目录是盘上常规路径。已知残留：cmd.exe 会对双引号内的 `%VAR%`
+* 做环境展开，路径含 `%` 的 Windows 部署需自行规避（Windows 非目标平台，此处只
+* 保证常规路径形态正确）。
+*/
+function shqDyn(value) {
+	if (process.platform === "win32") return `"${value.replaceAll("\"", "\"\"").replace(/\\+$/u, (backslashes) => backslashes + backslashes)}"`;
+	return `'${value.replaceAll("'", String.raw`'\''`)}'`;
+}
+/** api_key_cmd 值构造：脚本路径与 env key 名（及可选的 dsh 数据目录）shq 转义后
+*  拼成 shell 命令。第三参数是 get-cred.mjs 数据目录定位的**第一档**（显式参数 >
+*  $DSH_HOME > homedir()/.dsh）：ocrConfigPath 重定向 ocr 子进程的 HOME 后，
+*  get-cred 的 homedir() 兜底会跟着跑偏，须在宿主侧把解析出的数据目录显式钉进
+*  命令。undefined（未重定向）时省略，沿用 env/默认档。
+*  env key 白名单维持 ^[A-Z0-9_]+$（刻意比宿主 CredentialRef 的语法紧：OCR 侧
+*  惯例大写，且这是写进 config.json 的可信输入）。 */
+function buildApiKeyCmd(scriptPath, envKey, dshHome, messages) {
+	if (!/^[A-Z0-9_]+$/u.test(envKey)) throw new Error(format(messages.badEnvKey, { key: envKey }));
+	const parts = [
+		"node",
+		shqDyn(scriptPath),
+		shqDyn(envKey)
+	];
+	if (dshHome !== void 0) parts.push(shqDyn(dshHome));
+	return parts.join(" ");
+}
+/**
+* 读一个 shq 单引号串：解出它的值与结束位置。
+*
+* 认的是 shqDyn 自己写出的转义形态——值里的单引号被写成四字符的 '\''。所以遇到
+* 单引号时，只有后面紧跟这四字符才算转义，否则是真闭合。未闭合（串被截断）返回
+* undefined：宁可判「读不懂」，也不要把半截命令当成可信输入。
+*/
+function readShqToken(text, start) {
+	let value = "";
+	let i = start + 1;
+	let closed = false;
+	while (i < text.length && !closed) {
+		const ch = text[i];
+		if (ch === "'" && text.startsWith(String.raw`'\''`, i)) {
+			value += "'";
+			i += 4;
+		} else if (ch === "'") {
+			closed = true;
+			i += 1;
+		} else {
+			value += ch;
+			i += 1;
+		}
+	}
+	return closed ? {
+		value,
+		next: i
+	} : null;
+}
+/** shq 串 → token 列表；形态不符（未闭合 / 出现裸词）返回 null。 */
+function readShqTokens(body) {
+	const tokens = [];
+	let i = 0;
+	let malformed = false;
+	while (i < body.length && !malformed) {
+		while (i < body.length && (body[i] === " " || body[i] === "	")) i += 1;
+		if (i >= body.length) break;
+		if (body[i] === "'") {
+			const token = readShqToken(body, i);
+			if (token === null) malformed = true;
+			else {
+				tokens.push(token.value);
+				i = token.next;
+			}
+		} else malformed = true;
+	}
+	return malformed ? null : tokens;
+}
+/**
+* 读一个 cmd.exe 双引号串：解出它的值与结束位置（`""` 是翻倍的引号）。
+* 未闭合返回 null：宁可判「读不懂」，也不把半截命令当可信输入。
+*/
+function readDqToken(body, start) {
+	let value = "";
+	let i = start + 1;
+	let closed = false;
+	while (i < body.length && !closed) {
+		const ch = body[i];
+		if (ch === "\"" && body[i + 1] === "\"") {
+			value += "\"";
+			i += 2;
 		} else if (ch === "\"") {
 			closed = true;
 			i += 1;
@@ -2230,8 +3541,7 @@ function repointDanglingKeyScripts(doc, current, messages) {
 		return [name];
 	}) };
 }
-//#endregion
-//#region lib/ocr-config.ts
+// lib/ocr-config.ts
 /** 外部 ocr CLI 的默认配置目录/文件名（宿主服务管不到，只能由本包直读直写）。 */
 const OCR_CONFIG_DIR = ".opencodereview";
 const OCR_CONFIG_FILE = "config.json";
@@ -2352,7 +3662,7 @@ async function applyProviderSelection(gateway, paths, selection, messages) {
 	const apiKeyCmd = buildApiKeyCmd(scriptPath, target.apiKeyEnv, resolveDshHome(), messages);
 	await updateConfigLocked(paths.ocrConfigJson, async () => {
 		const next = renderSelectedConfig({
-			existingText: readText(paths.ocrConfigJson),
+			existingText: readExistingText(paths.ocrConfigJson, messages),
 			configLabel: paths.ocrConfigJson,
 			providers,
 			provider,
@@ -2396,7 +3706,7 @@ function migrateEntry(entry, envKey, context) {
 * 返回 { migrated: string[]; skippedUnknown: string[] }。
 */
 async function migratePlaintextKeys(gateway, paths, messages) {
-	const precheck = readText(paths.ocrConfigJson);
+	const precheck = readExistingText(paths.ocrConfigJson, messages);
 	if (!precheck.trim()) return {
 		migrated: [],
 		skippedUnknown: []
@@ -2423,7 +3733,7 @@ async function migratePlaintextKeys(gateway, paths, messages) {
 		messages
 	};
 	return await updateConfigLocked(paths.ocrConfigJson, async () => {
-		const doc = parseExistingConfig(readText(paths.ocrConfigJson), paths.ocrConfigJson, messages);
+		const doc = parseExistingConfig(readExistingText(paths.ocrConfigJson, messages), paths.ocrConfigJson, messages);
 		const customsRaw = fieldOf(doc, "custom_providers");
 		if (!isRecord(customsRaw)) return {
 			migrated: [],
@@ -2471,14 +3781,23 @@ async function ensureKeyScriptPointer(paths, messages) {
 		script: scriptPath,
 		dshHome: resolveDshHome()
 	};
-	if (readText(paths.ocrConfigJson).trim() === "") return {
+	let text;
+	try {
+		text = readExistingText(paths.ocrConfigJson, messages);
+	} catch {
+		return {
+			repointed: [],
+			checked: false
+		};
+	}
+	if (text.trim() === "") return {
 		repointed: [],
 		checked: true
 	};
 	try {
 		return {
 			repointed: await updateConfigLocked(paths.ocrConfigJson, async () => {
-				const doc = parseExistingConfig(readText(paths.ocrConfigJson), paths.ocrConfigJson, messages);
+				const doc = parseExistingConfig(readExistingText(paths.ocrConfigJson, messages), paths.ocrConfigJson, messages);
 				const result = repointDanglingKeyScripts(doc, current, messages);
 				if (result.repointed.length === 0) return result.repointed;
 				await writeConfigAtomic(paths.ocrConfigJson, renderConfigDoc(doc));
@@ -2493,12 +3812,268 @@ async function ensureKeyScriptPointer(paths, messages) {
 		};
 	}
 }
-//#endregion
-//#region lib/remote-shape.ts
+// lib/remote-shape.ts
 /** 宿主服务键 = 客户端线上命名空间（两侧共用的唯一来源）。 */
 const OCR_REMOTE_NAMESPACE = "ocrReview";
-//#endregion
-//#region host.ts
+// lib/mcp-config.ts
+/** 整体上限：MCP 配置是一份人工维护的小表，不承载大文件。 */
+const MCP_MAX_BYTES = 65536;
+const MCP_MAX_SERVERS = 100;
+const MCP_MAX_ARRAY = 100;
+const MCP_MAX_TEXT = 4096;
+const KNOWN_FIELDS = /* @__PURE__ */ new Set([
+	"type",
+	"command",
+	"args",
+	"url",
+	"headers",
+	"tools",
+	"setup",
+	"env"
+]);
+function failure(name, field, reason, messages) {
+	return {
+		ok: false,
+		error: format(messages.mcpServerInvalid, {
+			name,
+			field,
+			reason
+		})
+	};
+}
+function textField(value, name, field, messages) {
+	if (typeof value !== "string" || value.trim() === "") return failure(name, field, "must be a non-empty string", messages);
+	const trimmed = value.trim();
+	if (trimmed.length > MCP_MAX_TEXT) return failure(name, field, `must be at most ${MCP_MAX_TEXT} characters`, messages);
+	return {
+		ok: true,
+		value: trimmed
+	};
+}
+function stringArray(value, name, field, messages) {
+	if (!Array.isArray(value) || value.length > MCP_MAX_ARRAY) return failure(name, field, `must be an array of at most ${MCP_MAX_ARRAY} items`, messages);
+	const out = [];
+	for (const item of value) {
+		if (typeof item !== "string" || item.length > MCP_MAX_TEXT) return failure(name, field, `items must be strings of at most ${MCP_MAX_TEXT} characters`, messages);
+		out.push(item);
+	}
+	return {
+		ok: true,
+		value: out
+	};
+}
+function headersField(value, name, messages) {
+	if (!isRecord(value) || Object.keys(value).length > 50) return failure(name, "headers", "must be an object of at most 50 string headers", messages);
+	const out = {};
+	for (const [header, raw] of Object.entries(value)) {
+		if (header.trim() === "" || typeof raw !== "string" || raw.length > MCP_MAX_TEXT) return failure(name, `headers.${header}`, "must be a non-empty name and a string value", messages);
+		out[header] = raw;
+	}
+	return {
+		ok: true,
+		value: out
+	};
+}
+function normalizeStdio(raw, name, messages) {
+	if (raw["url"] !== void 0 || raw["headers"] !== void 0) return failure(name, "type", "stdio does not accept url/headers", messages);
+	const command = textField(raw["command"], name, "command", messages);
+	if (!command.ok) return command;
+	const entry = {
+		type: "stdio",
+		command: command.value
+	};
+	if (raw["args"] !== void 0) {
+		const args = stringArray(raw["args"], name, "args", messages);
+		if (!args.ok) return args;
+		entry["args"] = args.value;
+	}
+	if (raw["env"] !== void 0) {
+		const env = stringArray(raw["env"], name, "env", messages);
+		if (!env.ok) return env;
+		if (env.value.some((item) => !item.includes("="))) return failure(name, "env", "items must be KEY=VALUE", messages);
+		entry["env"] = env.value;
+	}
+	if (raw["setup"] !== void 0) {
+		const setup = textField(raw["setup"], name, "setup", messages);
+		if (!setup.ok) return setup;
+		entry["setup"] = setup.value;
+	}
+	return {
+		ok: true,
+		value: entry
+	};
+}
+function normalizeRemote(raw, name, messages) {
+	if (raw["command"] !== void 0 || raw["args"] !== void 0 || raw["env"] !== void 0 || raw["setup"] !== void 0) return failure(name, "type", "remote does not accept command/args/env/setup", messages);
+	const url = textField(raw["url"], name, "url", messages);
+	if (!url.ok) return url;
+	if (!/^https?:\/\//iu.test(url.value)) return failure(name, "url", "must start with http:// or https://", messages);
+	const entry = {
+		type: "remote",
+		url: url.value
+	};
+	if (raw["headers"] !== void 0) {
+		const headers = headersField(raw["headers"], name, messages);
+		if (!headers.ok) return headers;
+		entry["headers"] = headers.value;
+	}
+	return {
+		ok: true,
+		value: entry
+	};
+}
+/** 单个 server 条目 → 只含已知字段的普通对象；未知字段直接拒绝，避免写出 OCR 不认的配置。 */
+function normalizeServer(name, raw, messages) {
+	if (!isRecord(raw)) return failure(name, "entry", "must be an object", messages);
+	for (const field of Object.keys(raw)) if (!KNOWN_FIELDS.has(field)) return failure(name, field, "is not a supported MCP field", messages);
+	const type = raw["type"] === void 0 ? "stdio" : raw["type"];
+	if (type !== "stdio" && type !== "remote") return failure(name, "type", "must be stdio or remote", messages);
+	const base = type === "stdio" ? normalizeStdio(raw, name, messages) : normalizeRemote(raw, name, messages);
+	if (!base.ok) return base;
+	if (raw["tools"] !== void 0) {
+		const tools = stringArray(raw["tools"], name, "tools", messages);
+		if (!tools.ok) return tools;
+		base.value["tools"] = tools.value;
+	}
+	return base;
+}
+function normalizeServers(raw, messages) {
+	if (!isRecord(raw)) return {
+		ok: false,
+		error: messages.mcpShapeInvalid
+	};
+	const names = Object.keys(raw);
+	if (names.length > MCP_MAX_SERVERS) return {
+		ok: false,
+		error: format(messages.mcpTooManyServers, { limit: String(MCP_MAX_SERVERS) })
+	};
+	const out = {};
+	for (const name of names) {
+		if (name.trim() === "" || name.includes("\0") || name.length > 64) return failure(name, "name", "must be a non-empty key of at most 64 characters", messages);
+		const parsed = normalizeServer(name, raw[name], messages);
+		if (!parsed.ok) return parsed;
+		out[name] = parsed.value;
+	}
+	return {
+		ok: true,
+		value: out
+	};
+}
+/** 读侧用异步读：卡片端点是 async 面，读大文件时不该占住事件循环。 */
+function isNotFound(error) {
+	return isRecord(error) && error["code"] === "ENOENT";
+}
+/** 读当前 `mcp_servers`，交给卡片编辑；文件不存在按空表处理，坏 JSON/读不动返回可读错误。 */
+async function readMcpServers(configPath, messages) {
+	let text;
+	try {
+		text = await readFile(configPath, "utf8");
+	} catch (error) {
+		if (!isNotFound(error)) return {
+			ok: false,
+			error: format(messages.mcpReadFailed, {
+				where: configPath,
+				cause: String(error)
+			})
+		};
+		text = "";
+	}
+	if (!text.trim()) return {
+		ok: true,
+		json: "{}"
+	};
+	let doc;
+	try {
+		doc = parseExistingConfig(text, configPath, messages);
+	} catch (error) {
+		return {
+			ok: false,
+			error: format(messages.mcpReadFailed, {
+				where: configPath,
+				cause: String(error)
+			})
+		};
+	}
+	const servers = doc["mcp_servers"];
+	if (servers === void 0 || servers === null) return {
+		ok: true,
+		json: "{}"
+	};
+	if (!isRecord(servers)) return {
+		ok: false,
+		error: messages.mcpShapeInvalid
+	};
+	return {
+		ok: true,
+		json: JSON.stringify(servers, null, 2)
+	};
+}
+/** 校验并写回 `mcp_servers`；只改这一支，其余配置原样保留。 */
+async function saveMcpServers(configPath, json, messages) {
+	if (Buffer.byteLength(json, "utf8") > MCP_MAX_BYTES) return {
+		ok: false,
+		error: format(messages.mcpJsonTooLarge, { limit: String(MCP_MAX_BYTES) })
+	};
+	let raw;
+	try {
+		raw = JSON.parse(json);
+	} catch (error) {
+		return {
+			ok: false,
+			error: format(messages.mcpJsonInvalid, { cause: String(error) })
+		};
+	}
+	const normalized = normalizeServers(raw, messages);
+	if (!normalized.ok) return normalized;
+	try {
+		return {
+			ok: true,
+			count: await updateConfigLocked(configPath, async () => {
+				const doc = parseExistingConfig(readExistingText(configPath, messages), configPath, messages);
+				doc["mcp_servers"] = normalized.value;
+				await writeConfigAtomic(configPath, `${JSON.stringify(doc, null, 2)}\n`);
+				return Object.keys(normalized.value).length;
+			})
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: format(messages.mcpReadFailed, {
+				where: configPath,
+				cause: String(error)
+			})
+		};
+	}
+}
+/** ChatGPT provider 的配置写入：不写 key，只设 provider 与模型。 */
+async function applyChatGptModel(configPath, model, messages) {
+	const trimmed = model.trim();
+	if (trimmed === "" || trimmed.length > 256 || trimmed.includes("\0")) return {
+		ok: false,
+		error: messages.chatGptModelRequired
+	};
+	try {
+		await updateConfigLocked(configPath, async () => {
+			const doc = parseExistingConfig(readExistingText(configPath, messages), configPath, messages);
+			const providers = isRecord(doc["providers"]) ? doc["providers"] : {};
+			const entry = isRecord(providers["chatgpt"]) ? providers["chatgpt"] : {};
+			delete entry["api_key"];
+			delete entry["api_key_cmd"];
+			entry["model"] = trimmed;
+			providers["chatgpt"] = entry;
+			doc["providers"] = providers;
+			doc["provider"] = "chatgpt";
+			await writeConfigAtomic(configPath, `${JSON.stringify(doc, null, 2)}\n`);
+		});
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error: format(messages.chatGptSaveFailed, { cause: String(error) })
+		};
+	}
+}
+// host.ts
 const PLUGIN_DIR = import.meta.dirname;
 const MAX_TIMEOUT_REQUEST_MS = 2147483647;
 const LLM_TEST_TIMEOUT_MS = 9e4;
@@ -2513,460 +4088,156 @@ const STDOUT_MAX_BYTES = 4e5;
 *  护栏，把「整份读进内存」的失败形态从 OOM 换成一条点名文件的错误。 */
 const OUT_FILE_MAX_BYTES = 67108864;
 /** 解析失败时回显给模型的原始内容长度上限（UTF-16 码元；已脱敏）。
-*  单位写码元而不是"字符"：本常量喂给 `echoRaw`→`truncateEnd`，那一刀按码元数计
-*  （一张 emoji = 2 枚），写"字符"会把给模型的说明夸大约一倍。 */
-const RAW_ECHO_LIMIT = 500;
-/** 评论截断条数的内置默认（旧 BUILTIN_BASE 的那一项）：schema 的 `.default()` 与
-*  「读到坏值时的回退」（readMaxComments）共用这一个数，两处不许各写一份字面量。 */
-const MAX_COMMENTS_DEFAULT = 12;
-/** 官方注册表里本包作业的 kind；宿主据此签发的 id 形如 `ocr-review-<16 位 hex>`。 */
-const OCR_JOB_KIND = "ocr-review";
-/**
-* 后台评审的兜底回收窗口（毫秒）；0 = 不设窗口，进程只由宿主退出、会话 dispose、插件卸载
-* 或显式 job_kill 结束。
-*
-* 本包刻意不套宿主 timeoutMs（`onExpiry: "none"`：外部 CLI 的正常时长跨度太大，套了就等于
-* 替用户砍掉长评审）。不设窗口的代价落在注册表上：未拥有作业共用一只 10 格的桶（实测
-* `running` 与 `stopping` 都计数，满员是**拒绝**后来的 start），一条挂死的 CLI 就永久占一格，
-* 连别的插件也起不来。要给这一格腾位的部署把本项设成非零毫秒数：到点经注册表收，记录推到
-* stopping，理由落进模型可见的 detail。
-*/
-const OCR_BACKGROUND_MAX_MS = 0;
-/** "仍在跑"的两枚官方状态：`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 的理由
-* @param backgroundMaxMs 窗口毫秒数；`<= 0`（部署级设置项 `ocrBackgroundMaxMs` 的默认值）
-*   表示这条不设兜底窗口，直接返回、不去敲 `wait`
-* @returns 等完这一条的兜底窗口；抛错一律就地收敛（记录没了就等于无事可做）
-*/
-async function enforceOcrDeadline(jobs, id, reason, backgroundMaxMs) {
-	try {
-		if (backgroundMaxMs <= 0) return;
-		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;
-}
-/** host 是否为本插件所需服务面（settings/shell/tools/systemPrompt/get/inject 及
-*  其上要调用的方法）。守卫仅压缩类型面、避开 `as unknown as HostCtx` 断言。
-*  settings 这里点名的两个方法都会被调用：configure 登记本页的页面策略、describe
-*  跨命名空间读（provider 清单 + 官方 locale 偏好）；inject 挂那条页面策略的 effect。
-*  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() 行里按命名空间取解析值（跨命名空间读只有 describe() 一条路：
-*  `settings.get(ns)` 已删）。未注册该命名空间 → undefined，调用侧按默认值降级。
-*  @param rows - `ctx.settings.describe()` 的返回（全部条目的表单投影）。
-*  @param ns - 要读的命名空间（官方字段名是 `ns`）。
+*  单位写码元而不是"字符"：本常量喂给 `echoRaw`→`truncateEnd`，那一刀按码元数计
+*  （一张 emoji = 2 枚），写"字符"会把给模型的说明夸大约一倍。 */
+const RAW_ECHO_LIMIT = 500;
+/** 评论截断条数的内置默认（旧 BUILTIN_BASE 的那一项）：schema 的 `.default()` 与
+*  「读到坏值时的回退」（readMaxComments）共用这一个数，两处不许各写一份字面量。 */
+const MAX_COMMENTS_DEFAULT = 12;
+/** 官方注册表里本包作业的 kind；宿主据此签发的 id 形如 `ocr-review-<16 位 hex>`。 */
+const OCR_JOB_KIND = "ocr-review";
+/**
+* 后台评审的兜底回收窗口（毫秒）；0 = 不设窗口，进程只由宿主退出、会话 dispose、插件卸载
+* 或显式 job_kill 结束。
+*
+* 本包刻意不套宿主 timeoutMs（`onExpiry: "none"`：外部 CLI 的正常时长跨度太大，套了就等于
+* 替用户砍掉长评审）。不设窗口的代价落在注册表上：未拥有作业共用一只 10 格的桶（实测
+* `running` 与 `stopping` 都计数，满员是**拒绝**后来的 start），一条挂死的 CLI 就永久占一格，
+* 连别的插件也起不来。要给这一格腾位的部署把本项设成非零毫秒数：到点经注册表收，记录推到
+* stopping，理由落进模型可见的 detail。
 */
-function describedValue(rows, ns) {
-	return rows.find((row) => row.ns === ns)?.value;
+const OCR_BACKGROUND_MAX_MS = 0;
+/** "仍在跑"的两枚官方状态：`stopping` 是取消已发出、进程还没收完。 */
+function isLiveOcrStatus(status) {
+	return status === "running" || status === "stopping";
 }
 /**
-* 取本包 host 侧文案（按官方 locale 偏好现取现用）：设置页「常规」里换语言后，
-* 下一次工具调用/端点请求即换新文案，不需要重启或重装插件。
-* locale 命名空间未注册（无官方 client-locale 包）→ describe() 里没有这条 →
-* undefined → 中文默认。
+* 剪掉本 kind 最老的已落定记录，给下一次登记腾出窗口（注册表按登记序返回，故取头部）。
+* 在跑与正在收的一条不动：官方件对活作业的 remove 直接抛，而"静默杀掉用户发起的评审"
+* 正是本包要消灭的形态。
+* @param jobs 官方注册表
+* @returns {void}
 */
-function localeMessages(host) {
-	const preference = describedValue(host.settings.describe(), LOCALE_SETTINGS_NAMESPACE);
-	return messagesFor(MESSAGES, resolveLocalePreference(preference));
+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);
 }
 /**
-* render 只做 model-facing 展示：把 canonical value 本身 pretty-print 成文本块。
-* execute 直返结构化对象（不再 stringify 进 `{ text }`），所以这里 stringify 的是
-* 第一层也是唯一一层 JSON；循环结构/不可序列化值的两级兜底是防御，不是常规路径。
+* 在 controller 闸门下起一条未拥有作业，起完立刻摘掉。
+*
+* 实测：挂上即放行、摘掉即恢复"没有 controller 服务这个 owner"的拒绝、可反复；而 global 层
+* 那串 token 只被 `servesOwner` 读（installed dsh-jobs-local 全文唯一消费点），作业后续的
+* read/kill/落定都不依赖它。所以常驻一枚等于在"宿主故意没装 job 工具"的组成里替全宿主
+* 开着那道闸门——官方契约写的是"生产者不能起一台 owner 收不掉、停不掉的作业"。
 */
-function textBlock(value) {
-	let text;
+function startUnderOcrController(jobs, spec) {
+	const detach = jobs.attachController("ocr-review: background");
 	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 jobs.start(spec);
+	} finally {
+		detach();
 	}
-	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",
-			"jobId",
-			"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"
-				]
-			},
-			jobId: { type: "string" },
-			polling: { type: "string" }
-		}
-	},
-	{
-		type: "object",
-		additionalProperties: false,
-		required: [
-			"status",
-			"skipped",
-			"message",
-			"summary",
-			"budgetExceeded",
-			"sessionId",
-			"aggregation",
-			"totalCommentCount",
-			"droppedCount",
-			"invalidCommentCount",
-			"topComments",
-			"warnings",
-			"toolCalls",
-			"coverage",
-			"hint"
-		],
-		properties: {
-			status: {
-				type: "string",
-				enum: [
-					"success",
-					"complete",
-					"partial",
-					"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" }
-				}
-			}] },
-			budgetExceeded: { type: "boolean" },
-			sessionId: NULLABLE_STRING,
-			aggregation: {
-				type: "object",
-				additionalProperties: false,
-				required: [
-					"total",
-					"bySeverity",
-					"byCategory",
-					"unknownSeverityCount"
-				],
-				properties: {
-					total: { type: "integer" },
-					unknownSeverityCount: { 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" }
-			},
-			toolCalls: { oneOf: [{ type: "null" }, {
-				type: "object",
-				additionalProperties: false,
-				required: [
-					"total",
-					"failure",
-					"failures"
-				],
-				properties: {
-					total: { type: "integer" },
-					failure: { type: "integer" },
-					failures: {
-						type: "array",
-						items: { type: "string" }
-					}
-				}
-			}] },
-			coverage: { oneOf: [{ type: "null" }, {
-				type: "object",
-				additionalProperties: false,
-				required: [
-					"selected",
-					"completed",
-					"reused",
-					"failed",
-					"waived",
-					"failedItems"
-				],
-				properties: {
-					selected: { type: "integer" },
-					completed: { type: "integer" },
-					reused: { type: "integer" },
-					failed: { type: "integer" },
-					waived: { type: "integer" },
-					failedItems: {
-						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",
-		"mergeBase",
-		"reviewableCount",
-		"insertions",
-		"deletions",
-		"reviewableFiles",
-		"excludedFiles",
-		"hint"
-	],
-	properties: {
-		mode: { type: "string" },
-		repository: { type: "string" },
-		mergeBase: NULLABLE_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" }
+/**
+* 等到兜底 deadline 到点，然后把仍在跑的那条经注册表收掉。
+*
+* 用注册表自己的 `wait(id, ms)` 而不是宿主 timer，也不是裸 `setTimeout`：前者要把
+* `timer` 写进 HostCtx 的**必需**服务面（装载守卫一扩，没装那件的宿主连前台评审都装载
+* 不了），后者会活过插件卸载。实测 `wait` 只等不杀、作业一落定就解掉它内部的定时器，
+* 也不推进输出游标（模型侧 job_output 的读数不受影响）——所以落定时这里看一眼状态就返回。
+* @param jobs 官方注册表
+* @param id 这次后台评审的作业 id
+* @param reason 到点回收时写进模型可见 detail 的理由
+* @param backgroundMaxMs 窗口毫秒数；`<= 0`（部署级设置项 `ocrBackgroundMaxMs` 的默认值）
+*   表示这条不设兜底窗口，直接返回、不去敲 `wait`
+* @returns 等完这一条的兜底窗口；抛错一律就地收敛（记录没了就等于无事可做）
+*/
+async function enforceOcrDeadline(jobs, id, reason, backgroundMaxMs) {
+	try {
+		if (backgroundMaxMs <= 0) return;
+		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;
+}
+/** host 是否为本插件所需服务面（settings/shell/tools/systemPrompt/get/inject 及
+*  其上要调用的方法）。守卫仅压缩类型面、避开 `as unknown as HostCtx` 断言。
+*  settings 这里点名的两个方法都会被调用：configure 登记本页的页面策略、describe
+*  跨命名空间读（provider 清单 + 官方 locale 偏好）；inject 挂那条页面策略的 effect。
+*  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() 行里按命名空间取解析值（跨命名空间读只有 describe() 一条路：
+*  `settings.get(ns)` 已删）。未注册该命名空间 → undefined，调用侧按默认值降级。
+*  @param rows - `ctx.settings.describe()` 的返回（全部条目的表单投影）。
+*  @param ns - 要读的命名空间（官方字段名是 `ns`）。
+*/
+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
+	}];
+}
 /**
 * ocr 子进程一律按 `danger-full-access` 请求（官方按调用携带的 `SandboxExecutionPolicy`）。
 *
@@ -2985,7 +4256,7 @@ const SESSION_OUTPUT_SCHEMA = {
 * 路径、没有自定义 HOME、没有目录级豁免；而 `SandboxMode` 的取值只有
 * `read-only | workspace-write | danger-full-access` 三档，中间那一档的可写根就是
 * `workspaceRoot` 一枚。两处声明都取自本包实际解析到的那版（dsh-sandbox-policy 与
-* dsh-sandbox 的 0.2.1-rc.2，`lib/types/index.d.ts`）。
+* dsh-sandbox 的 0.2.1-rc.3，`lib/types/index.d.ts`）。
 * 可选的收紧路径只有「改 ocr 自己的状态落点」或「等上游加字段」，两者都不是本包能在
 * 一次补丁里做完的事。故此处维持放开，但把边界写明：放开的是 ocr 这一个子进程的整棵
 * 文件系统写权限，不是宿主其它能力；且 ocr 读什么、写什么仍由上面那条 argv 闸与
@@ -3191,7 +4462,7 @@ async function runCollect(host, command, workdir, run) {
 }
 function readEffort(config) {
 	const raw = config.effort.get();
-	return raw === "low" || raw === "high" ? raw : "medium";
+	return raw === "auto" || raw === "low" || raw === "high" ? raw : "medium";
 }
 function readLanguage(config) {
 	const lang = config.language.get();
@@ -3360,10 +4631,11 @@ function tuningParams(messages, unit, maxToolsTemplate) {
 *  外部仍以 `Config` 名导入（export as），公开 API 不变。 */
 const configSchema = Schema.object({
 	effort: Schema.union([
+		"auto",
 		"low",
 		"medium",
 		"high"
-	]).default("medium").volatile(),
+	]).default("auto").volatile(),
 	language: Schema.union(["中文", "English"]).default("中文").volatile(),
 	autoVerify: Schema.boolean().default(true).volatile(),
 	maxComments: Schema.natural().default(MAX_COMMENTS_DEFAULT).volatile(),
@@ -3399,7 +4671,7 @@ function pluginPaths(config, messages) {
 /**
 * ocr 子进程的 HOME 重定向值（工具执行侧专用，**不抛错**）：设置项命中
 * `<X>/.opencodereview/config.json` 布局 → X；未设置/坏设置 → undefined。工具不
-* 走 pluginPaths（那会在坏设置下把五个工具一并拖死），坏设置的错误由端点侧的
+* 走 pluginPaths（那会在坏设置下把七个工具一并拖死），坏设置的错误由端点侧的
 * resolveOcrConfigPath 报给卡片——「工具与设置照常可用」的口径不变。
 */
 function ocrHome(config) {
@@ -3412,7 +4684,7 @@ function ocrHome(config) {
 * 为什么必须在这一层而不是启动时：config.json 里的脚本路径是**写那一刻**的插件安装
 * 目录，而插件会被重装、换 profile（desktop / browser / 任意自定义名）、换发布形态。
 * 目录一变那条命令就悬空，ocr 侧报的是「resolve LLM endpoint 失败」，与真因毫无
-* 关系——五个工具一次性全挂，而配置文件里没有任何线索指向「本包被挪了地方」。
+* 关系——七个工具一次性全挂，而配置文件里没有任何线索指向「本包被挪了地方」。
 * 当前路径一律取自 PLUGIN_DIR（import.meta.dirname），与 profile 命名
 * 无关，故 desktop / browser / 自定义名走的是同一条路径。
 *
@@ -3451,7 +4723,7 @@ function probeFailureReason(messages, exitCode, timedOut) {
 *    **全局安装**（`scripts/update.js` 见到更新版本就 spawnSync `npm i -g <pkg>@<latest>`，
 *    默认 18 分钟冷却一次）。状态读侧不该有写侧副作用，所以这条不受 `ocrNoAutoUpdate`
 *    那个部署开关影响，恒定带上。
-*  - HOME 与五个工具走同一个重定向口。launcher 那句「自动更新没成功，请手工执行」的
+*  - HOME 与七个工具走同一个重定向口。launcher 那句「自动更新没成功，请手工执行」的
 *    提示写在 `$HOME/.opencodereview/` 下，不带重定向就会去读另一个世界的状态，
 *    卡片报的与评审实际吃到的就不是同一份。
 * @param host 宿主服务面
@@ -3541,7 +4813,7 @@ function cliStatusPayload(status, config, messages, measured) {
 * @returns 同一份摘要，或 hint 尾部多了一句的副本。
 */
 function withCliVersionNote(summary, measured, messages) {
-	if (measured === null || measured === "1.13.0") return summary;
+	if (measured === null || measured === "1.13.3") return summary;
 	const note = format(messages.versionMismatch, {
 		actual: measured,
 		expected: EXPECTED_OCR_CLI_VERSION
@@ -3552,7 +4824,7 @@ function withCliVersionNote(summary, measured, messages) {
 	};
 }
 /** 运行 ocr llm test 校验当前配置（select 后自动验证 / 手动测试共用）。
-*  命令词与五个工具同一解析源（buildLlmTestCommand 走 ocrCommand()：卡片验的那一份与评审
+*  命令词与七个工具同一解析源（buildLlmTestCommand 走 ocrCommand()：卡片验的那一份与评审
 *  吃的那一份必须同一个二进制），HOME 随 ocrConfigPath 重定向。墙钟与输出上限都是 entry
 *  config 字段（非 volatile，改值随重启生效）。 */
 async function runLlmTest(host, config) {
@@ -3566,8 +4838,8 @@ async function runLlmTest(host, config) {
 		output
 	};
 }
-/** effort 入参闸：undefined/null → 设置卡默认；字符串 → 白名单钳制（未知值回落
-*  medium，与 --format 同一纪律）；其余类型抛错——静默回落会改变审查深度。 */
+/** effort 入参闸：undefined/null → 设置卡默认（auto 表示跟随 OCR 配置）；字符串 →
+*  白名单钳制（未知值回落 auto，与 --format 同一纪律）；其余类型抛错——静默回落会改变审查深度。 */
 function effortOf(value, config, messages) {
 	if (value === void 0 || value === null) return readEffort(config);
 	if (typeof value !== "string") throw new TypeError(format(messages.mustBeString, {
@@ -3590,6 +4862,19 @@ function waitOf(value, messages) {
 	if (typeof value !== "boolean") throw new TypeError(format(messages.waitMustBeBoolean, { received: describeValue(value) }));
 	return value;
 }
+/** session action 的只读归一：错类型交给 builder 的消息表闸。 */
+function actionOf(value) {
+	return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+/** preview 入参闸：缺省 false；非布尔抛错。 */
+function previewOf(value, messages) {
+	if (value === void 0 || value === null) return false;
+	if (typeof value !== "boolean") throw new TypeError(format(messages.boolMustBeBoolean, {
+		name: "preview",
+		received: describeValue(value)
+	}));
+	return value;
+}
 /** 服务界面齐备才算可用（get() 可能返回半装配对象，也可能返回 undefined）。 */
 function usableService(value, methods) {
 	return value !== void 0 && hasMethods(value, methods) ? value : void 0;
@@ -3809,13 +5094,93 @@ async function testReply(deps) {
 		};
 	}
 }
+async function mcpReply(deps) {
+	const msgs = deps.messages();
+	try {
+		const result = await readMcpServers(pluginPaths(deps.config, msgs).ocrConfigJson, msgs);
+		return result.ok ? {
+			ok: true,
+			json: result.json
+		} : {
+			ok: false,
+			error: result.error,
+			status: 400
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: errorText(error),
+			status: 500
+		};
+	}
+}
+async function saveMcpReply(json, deps) {
+	const msgs = deps.messages();
+	if (typeof json !== "string") return {
+		ok: false,
+		error: format(msgs.mustBeString, {
+			name: "json",
+			received: describeValue(json)
+		}),
+		status: 400
+	};
+	const result = await saveMcpServers(pluginPaths(deps.config, msgs).ocrConfigJson, json, msgs);
+	return result.ok ? {
+		ok: true,
+		count: result.count
+	} : {
+		ok: false,
+		error: result.error,
+		status: 400
+	};
+}
+async function authReply(deps) {
+	try {
+		const { exitCode, output } = await runCollect(deps.host, withHomeEnv(buildAuthStatusCommand(), ocrHome(deps.config)), process.env["HOME"] ?? "/", {
+			timeoutMs: deps.config.llmTestTimeoutMs,
+			stdoutMaxBytes: deps.config.stdoutMaxBytes,
+			env: ocrEnv(deps.config)
+		});
+		return {
+			ok: exitCode === 0,
+			output,
+			loginCommand: CHATGPT_LOGIN_COMMAND
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: errorText(error),
+			status: 400
+		};
+	}
+}
+async function chatGptReply(model, deps) {
+	const msgs = deps.messages();
+	if (typeof model !== "string") return {
+		ok: false,
+		error: format(msgs.mustBeString, {
+			name: "model",
+			received: describeValue(model)
+		}),
+		status: 400
+	};
+	const result = await applyChatGptModel(pluginPaths(deps.config, msgs).ocrConfigJson, model, msgs);
+	return result.ok ? {
+		ok: true,
+		model: model.trim()
+	} : {
+		ok: false,
+		error: result.error,
+		status: 400
+	};
+}
 /**
-* 设置卡的五条读/写方法（providers / select / migrate / test / probe）。
+* 设置卡的九条读/写方法（providers / select / migrate / test / probe / mcp / saveMcp / auth / chatGpt）。
 *
 * ⚠ 服务在**构造时**注册（cordis `Service` 的契约：`ctx.reflect.provide`，随所属 fiber
 * 卸载自动撤），所以调用方拿实例没有任何用处——装入口 `installOcrRemote` 说明了这一点。
-* 五个方法都不依赖可选宿主服务（gateway 与取用口都由 apply 交进来），故它跟着 apply
-* 无条件上线：宿主没有 web 层（TUI）时这五条照样在。
+* 九个方法都不依赖可选宿主服务（gateway 与取用口都由 apply 交进来），故它跟着 apply
+* 无条件上线：宿主没有 web 层（TUI）时这九条照样在。
 */
 var OcrReviewRemoteService = class extends TypertRemoteService {
 	deps;
@@ -3849,6 +5214,22 @@ var OcrReviewRemoteService = class extends TypertRemoteService {
 			versionSink: this.deps.extras.versionSink
 		});
 	}
+	/** 读当前 `mcp_servers`（只回这一支，不带其他配置/keys）。 */
+	async mcp() {
+		return mcpReply(this.deps);
+	}
+	/** 校验并写入 `mcp_servers`；其他配置原样保留。 */
+	async saveMcp(request) {
+		return saveMcpReply(isRecord(request) ? request.json : void 0, this.deps);
+	}
+	/** 只读查询 ChatGPT 登录态；登录命令原样带回给卡片显示。 */
+	async auth() {
+		return authReply(this.deps);
+	}
+	/** 切到 ChatGPT provider 并写模型；key 由 OCR 的 auth 凭据库管，不写明文。 */
+	async chatGpt(request) {
+		return chatGptReply(isRecord(request) ? request.model : void 0, this.deps);
+	}
 };
 /**
 * 标准装饰器的**程序化调用**：`@Remote` 的全部作用就是往类原型写一枚描述符，而标准装饰器
@@ -3873,6 +5254,10 @@ markRemote(OcrReviewRemoteService.prototype, "select");
 markRemote(OcrReviewRemoteService.prototype, "migrate");
 markRemote(OcrReviewRemoteService.prototype, "test");
 markRemote(OcrReviewRemoteService.prototype, "probe");
+markRemote(OcrReviewRemoteService.prototype, "mcp");
+markRemote(OcrReviewRemoteService.prototype, "saveMcp");
+markRemote(OcrReviewRemoteService.prototype, "auth");
+markRemote(OcrReviewRemoteService.prototype, "chatGpt");
 /**
 * 把读面装到这个上下文上（构造即注册，见类文档；host 侧唯一该调的口）。
 *
@@ -3910,6 +5295,70 @@ const productionProbe = () => resolveOcrAvailability();
 function assertOcrPresent(status, messages, install) {
 	if (status.source === "none") throw new Error(format(messages.ocrBinaryMissing, { install }));
 }
+/** review 的预览支路：零 LLM、前台、临时 --output；抽出来只为把注册函数压回行数上限。 */
+async function runReviewPreview(run) {
+	const { host, config, args, repo, signal, messages } = run;
+	if (args["wait"] !== void 0 && args["wait"] !== null && !waitOf(args["wait"], messages)) throw new Error(messages.previewNeedsForeground);
+	const tmp = mkdtempSync(path.join(tmpdir(), "ocr-review-preview-"));
+	const outPath = path.join(tmp, "preview.json");
+	try {
+		const { command, workdir } = buildReviewCommand({
+			...args,
+			repo,
+			preview: true
+		}, outPath, messages);
+		await runForeground(host, withHomeEnv(command, ocrHome(config)), workdir, tuningOf(config), signal);
+		const text = readOutFile(outPath, messages);
+		const parsed = parsePreviewOutput(text);
+		if (!parsed.ok) return format(messages.parseFailedWithReason, {
+			tool: "ocr review --preview",
+			message: messages.previewParseFailed,
+			limit: String(RAW_ECHO_LIMIT),
+			raw: echoRaw(text, RAW_ECHO_LIMIT)
+		});
+		return {
+			...parsed.view,
+			hint: messages.filePreviewHint
+		};
+	} finally {
+		rmSync(tmp, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** scan 的预览支路（与 review 同形，只是不归一化 git 顶层）。 */
+async function runScanPreview(run) {
+	const { host, config, args, repo, signal, messages } = run;
+	if (args["wait"] !== void 0 && args["wait"] !== null && !waitOf(args["wait"], messages)) throw new Error(messages.previewNeedsForeground);
+	const tmp = mkdtempSync(path.join(tmpdir(), "ocr-scan-preview-"));
+	const outPath = path.join(tmp, "preview.json");
+	try {
+		const { command, workdir } = buildScanCommand({
+			...args,
+			repo,
+			preview: true
+		}, outPath, messages);
+		await runForeground(host, withHomeEnv(command, ocrHome(config)), workdir, tuningOf(config), signal);
+		const text = readOutFile(outPath, messages);
+		const parsed = parsePreviewOutput(text);
+		if (!parsed.ok) return format(messages.parseFailedWithReason, {
+			tool: "ocr scan --preview",
+			message: messages.previewParseFailed,
+			limit: String(RAW_ECHO_LIMIT),
+			raw: echoRaw(text, RAW_ECHO_LIMIT)
+		});
+		return {
+			...parsed.view,
+			hint: messages.filePreviewHint
+		};
+	} finally {
+		rmSync(tmp, {
+			recursive: true,
+			force: true
+		});
+	}
+}
 function registerReviewTool(host, config, probe, versionSink) {
 	const msgs = localeMessages(host);
 	define(host, {
@@ -3978,6 +5427,26 @@ function registerReviewTool(host, config, probe, versionSink) {
 				resume: {
 					type: "string",
 					description: msgs.paramResume
+				},
+				preview: {
+					type: "boolean",
+					description: msgs.paramPreview
+				},
+				noFilter: {
+					type: "boolean",
+					description: msgs.paramNoFilter
+				},
+				maxGitProcs: {
+					type: "integer",
+					description: msgs.paramMaxGitProcs
+				},
+				rule: {
+					type: "string",
+					description: msgs.paramRule
+				},
+				backgroundFile: {
+					type: "string",
+					description: msgs.paramBackgroundFile
 				}
 			}
 		},
@@ -3987,6 +5456,14 @@ function registerReviewTool(host, config, probe, versionSink) {
 			const cliStatus = probe();
 			assertOcrPresent(cliStatus, runMsgs, ocrInstallText(cliStatus, config, runMsgs));
 			const repo = await canonicalReviewRoot(host, ocrRepo(args, exec, runMsgs));
+			if (previewOf(args["preview"], runMsgs)) return runReviewPreview({
+				host,
+				config,
+				args,
+				repo,
+				signal: exec.signal,
+				messages: runMsgs
+			});
 			const eff = effortOf(args["effort"], config, runMsgs);
 			const tmp = waitOf(args["wait"], runMsgs) ? mkdtempSync(path.join(tmpdir(), "ocr-review-")) : void 0;
 			const outPath = tmp === void 0 ? void 0 : path.join(tmp, "out.json");
@@ -4079,6 +5556,34 @@ function registerScanTool(host, config, probe, versionSink) {
 				wait: {
 					type: "boolean",
 					description: msgs.paramWait
+				},
+				preview: {
+					type: "boolean",
+					description: msgs.paramPreview
+				},
+				noPlan: {
+					type: "boolean",
+					description: msgs.paramNoPlan
+				},
+				noDedup: {
+					type: "boolean",
+					description: msgs.paramNoDedup
+				},
+				noSummary: {
+					type: "boolean",
+					description: msgs.paramNoSummary
+				},
+				resume: {
+					type: "string",
+					description: msgs.paramScanResume
+				},
+				maxGitProcs: {
+					type: "integer",
+					description: msgs.paramMaxGitProcs
+				},
+				rule: {
+					type: "string",
+					description: msgs.paramRule
 				}
 			}
 		},
@@ -4088,6 +5593,14 @@ function registerScanTool(host, config, probe, versionSink) {
 			const cliStatus = probe();
 			assertOcrPresent(cliStatus, runMsgs, ocrInstallText(cliStatus, config, runMsgs));
 			const repo = ocrRepo(args, exec, runMsgs);
+			if (previewOf(args["preview"], runMsgs)) return runScanPreview({
+				host,
+				config,
+				args,
+				repo,
+				signal: exec.signal,
+				messages: runMsgs
+			});
 			const tmp = waitOf(args["wait"], runMsgs) ? mkdtempSync(path.join(tmpdir(), "ocr-scan-")) : void 0;
 			const outPath = tmp === void 0 ? void 0 : path.join(tmp, "out.json");
 			await healKeyScriptPointer(host, config);
@@ -4276,7 +5789,9 @@ function registerSessionTool(host, config, probe) {
 					enum: [
 						"list",
 						"show",
-						"comments"
+						"comments",
+						"compare",
+						"export"
 					],
 					description: msgs.paramSessionAction
 				},
@@ -4284,6 +5799,24 @@ function registerSessionTool(host, config, probe) {
 					type: "string",
 					description: msgs.paramSessionId
 				},
+				before: {
+					type: "string",
+					description: msgs.paramSessionBefore
+				},
+				after: {
+					type: "string",
+					description: msgs.paramSessionAfter
+				},
+				severity: {
+					type: "array",
+					items: { type: "string" },
+					description: msgs.paramSessionSeverity
+				},
+				category: {
+					type: "array",
+					items: { type: "string" },
+					description: msgs.paramSessionCategory
+				},
 				limit: {
 					type: "integer",
 					description: msgs.paramSessionLimit
@@ -4296,6 +5829,47 @@ function registerSessionTool(host, config, probe) {
 			const cliStatus = probe();
 			assertOcrPresent(cliStatus, runMsgs, ocrInstallText(cliStatus, config, runMsgs));
 			const repo = await canonicalReviewRoot(host, ocrRepo(args, exec, runMsgs));
+			const action = actionOf(args["action"]);
+			const before = typeof args["before"] === "string" ? args["before"].trim() : "";
+			const after = typeof args["after"] === "string" ? args["after"].trim() : "";
+			if (action === "compare" || action === "" && (before !== "" || after !== "")) {
+				const { command, workdir } = buildSessionCommand({
+					...args,
+					repo
+				}, runMsgs);
+				const stdout = await runForeground(host, withHomeEnv(command, ocrHome(config)), workdir, tuningOf(config), exec.signal);
+				const parsed = parseSessionCompare(stdout.text);
+				if (parsed.ok) return {
+					...parsed.view,
+					hint: runMsgs.sessionCompareHint
+				};
+				return {
+					sessionOutput: echoRaw(stdout.text, RAW_ECHO_LIMIT) + stdoutTruncationNote(config.stdoutMaxBytes, stdout, runMsgs),
+					hint: runMsgs.sessionCompareHint
+				};
+			}
+			if (action === "export") {
+				const exportDir = mkdtempSync(path.join(tmpdir(), "ocr-session-export-"));
+				const output = path.join(exportDir, "review.html");
+				try {
+					const { command, workdir } = buildSessionCommand({
+						...args,
+						repo,
+						output
+					}, runMsgs);
+					await runForeground(host, withHomeEnv(command, ocrHome(config)), workdir, tuningOf(config), exec.signal);
+					return {
+						sessionOutput: output,
+						hint: runMsgs.sessionExportHint
+					};
+				} catch (error) {
+					rmSync(exportDir, {
+						recursive: true,
+						force: true
+					});
+					throw error;
+				}
+			}
 			const { command, workdir } = buildSessionCommand({
 				...args,
 				repo
@@ -4312,6 +5886,83 @@ function registerSessionTool(host, config, probe) {
 		}
 	});
 }
+function registerRulesCheckTool(host, config, probe) {
+	const msgs = localeMessages(host);
+	define(host, {
+		name: "ocr_rules_check",
+		description: msgs.rulesCheckToolDescription,
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				repo: {
+					type: "string",
+					description: msgs.paramRepo
+				},
+				path: {
+					type: "string",
+					description: msgs.paramRulesPath
+				},
+				rule: {
+					type: "string",
+					description: msgs.paramRule
+				}
+			},
+			required: ["path"]
+		},
+		schema: TEXT_OUTPUT_SCHEMA,
+		run: async (args, exec) => {
+			const runMsgs = localeMessages(host);
+			const cliStatus = probe();
+			assertOcrPresent(cliStatus, runMsgs, ocrInstallText(cliStatus, config, runMsgs));
+			const repo = ocrRepo(args, exec, runMsgs);
+			const { command, workdir } = buildRulesCheckCommand({
+				...args,
+				repo
+			}, runMsgs);
+			const stdout = await runForeground(host, withHomeEnv(command, ocrHome(config)), workdir, tuningOf(config), exec.signal);
+			const { text } = stdout;
+			return {
+				output: (text.length > 12e3 ? `${echoRaw(text, 11900)}\n${format(runMsgs.textTruncated, { limit: "12000" })}` : redactKeyMaterial(text)) + stdoutTruncationNote(config.stdoutMaxBytes, stdout, runMsgs),
+				hint: runMsgs.rulesCheckHint
+			};
+		}
+	});
+}
+function registerLlmTool(host, config, probe) {
+	const msgs = localeMessages(host);
+	define(host, {
+		name: "ocr_llm",
+		description: msgs.llmToolDescription,
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: { action: {
+				type: "string",
+				enum: ["providers", "models"],
+				description: msgs.paramLlmAction
+			} },
+			required: ["action"]
+		},
+		schema: TEXT_OUTPUT_SCHEMA,
+		run: async (args, exec) => {
+			const runMsgs = localeMessages(host);
+			const cliStatus = probe();
+			assertOcrPresent(cliStatus, runMsgs, ocrInstallText(cliStatus, config, runMsgs));
+			const rawAction = args["action"];
+			if (rawAction !== "providers" && rawAction !== "models") throw new Error(format(runMsgs.invalidAction, {
+				action: typeof rawAction === "string" ? rawAction : describeValue(rawAction),
+				expected: "providers/models"
+			}));
+			const stdout = await runForeground(host, withHomeEnv(buildLlmCommand(rawAction), ocrHome(config)), process.cwd(), tuningOf(config), exec.signal);
+			const { text } = stdout;
+			return {
+				output: (text.length > 12e3 ? `${echoRaw(text, 11900)}\n${format(runMsgs.textTruncated, { limit: "12000" })}` : redactKeyMaterial(text)) + stdoutTruncationNote(config.stdoutMaxBytes, stdout, runMsgs),
+				hint: runMsgs.llmHint
+			};
+		}
+	});
+}
 /** 装载期自检结论里保留的输出上限（字符）：卡片只用来提示，留全量没有意义。 */
 const ENDPOINT_VERIFY_CHARS = 400;
 /** 装载期端点自检（fire-and-forget）：跑一次 `ocr llm test`，把结论写进本次 apply 的闭包，
@@ -4378,6 +6029,8 @@ function apply(ctx, config, probe) {
 	registerDelegatePreviewTool(host, config, probe);
 	registerDelegateRuleTool(host, config, probe);
 	registerSessionTool(host, config, probe);
+	registerRulesCheckTool(host, config, probe);
+	registerLlmTool(host, config, probe);
 	host.systemPrompt.section({
 		name: ROUTING_NAME,
 		order: ROUTING_ORDER,
@@ -4407,5 +6060,4 @@ var host_default = {
 		apply(ctx, config, productionProbe);
 	}
 };
-//#endregion
 export { configSchema as Config, OcrReviewRemoteService, apply, assertOcrPresent, createGateway, host_default as default, endpointVerifyOf, installOcrRemote, joinedOutput, ocrEnv, ocrRepo, productionProbe, readLanguage, requiredKeys };