npm - @jayyuen66/dsh-ocr-review - Versions diffs - 0.1.7 → 0.1.9 - Mend

@jayyuen66/dsh-ocr-review 0.1.7 → 0.1.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/host.js CHANGED Viewed

@@ -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);
@@ -409,24 +591,45 @@ function arrayViolations(schema, value, path, walk) {
 *  能嵌套任意多个候选起点，而「run 内是否存在数字或大写」这类前瞻要把后面整段 run 反向
 *  回溯一遍——逐起点相乘就是 O(n²)（实测 400_000 字符 51 秒，正好是 `stdoutMaxBytes`
 *  的默认档）。run 是首个 `-` 之后的那一段：前缀只含字母，故首个 `-` 必是分界。 */
-const STANDALONE_KEY = /\b[A-Za-z]{2,5}-[A-Za-z0-9_-]{20,}\b/gu;
+const STANDALONE_KEY = /\b[A-Za-z]{2,5}-[\w-]{20,}\b/gu;
 /** `Authorization: <scheme> <value>` / `Proxy-Authorization: …`：认**头名**而不是
 *  枚举认证方案。头名本身就是「后面跟着凭据」的信号，Basic / Token / Digest 乃至
 *  vendor 自定义 scheme 都不会漏；而只认头名还避开了正文里「token based
 *  authentication」这类措辞被误抹。scheme 组连同其后的空白一起捕获，回填时凭据被
 *  替换而 scheme 词保留。 */
-const AUTH_HEADER_VALUE = /(?<name>\b(?:proxy-)?authorization["'\s]*[:=]["'\s]*)(?:(?<scheme>[a-z][a-z0-9_-]*[ \t]+))?[^\s"',;)}\]]{4,}/giu;
+const AUTH_HEADER_VALUE = /(?<name>\b(?:proxy-)?authorization["'\s]*[:=]["'\s]*)(?<scheme>[a-z][\w-]*[ \t]+)?[^\s"',;)}\]]{4,}/giu;
 /** 裸 scheme + 值（没有头名时 OCR 也会整行回显）。scheme 只留 bearer：它在散文中几乎
 *  不出现，而 token / basic 之类会撞上「token count」「basic usage」等普通措辞。 */
-const BEARER_VALUE = /(?<scheme>\bbearer[ \t]+)[a-z0-9._~+/=-]{4,}/giu;
+const BEARER_VALUE = /(?<scheme>\bbearer[ \t]+)[\w.~+/=-]{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|access[_-]?key|secret[_-]?key|client[_-]?secret|password|token)["'\s]*[:=]["'\s]*)(?<scheme>[a-z][\w-]*[ \t]+)?[^\s"',;)}\]]{4,}/giu;
+/** GitHub 系 token 的**下划线**形态（`ghp_…`、`github_pat_…`）：STANDALONE_KEY 要求
+*  「字母前缀 + 连字符」分界，这类值里没有连字符，前缀后又紧跟下划线，故单列一条。
+*  不并进 STANDALONE_KEY 是为了不放开那里的连字符要求——那条要求同时承担「别把
+*  kebab 小写路径当 key 抹掉」的职责。 */
+const UNDERSCORE_TOKEN = /\b(?:gh[pousr]|github_pat)_\w{20,}\b/gu;
 const REDACTION = "***REDACTED***";
-/** 独立 key 形态的替换臂：随机串段里真有数字或大写才抹，否则原样交回（文件路径要保持可读）。 */
-function redactStandaloneKey(match) {
-	return /[0-9A-Z]/u.test(match.slice(match.indexOf("-") + 1)) ? REDACTION : match;
+/** token 尾部至少一枚非 `-` 的字母/数字。 */
+const TOKEN_TAIL_CHARACTER = /[0-9A-Z]/u;
+/** 独立 key 形态的替换臂：随机串段里真有数字或大写才抹，否则原样交回（文件路径要保持可读）。
+*  两侧任一是路径分隔符的匹配是路径段而非 key：ocr CLI 会把仓库路径拍平成 kebab 段嵌进
+*  session 的 file_path（`…/sessions/Users-yuanjiang-Documents-…/uuid.jsonl`），原路径里
+*  只要有大写组件（macOS 的 Documents/Desktop 一类）就过得了「数字或大写」那道护栏——
+*  裸 key 从不出现在斜杠两侧，路径段也从不出现在别处，按上下文分比按字符集猜稳。 */
+function redactStandaloneKey(match, offset, whole) {
+	const before = whole[offset - 1];
+	const after = whole[offset + match.length];
+	if (before === "/" || after === "/" || before === "\\" || after === "\\") return match;
+	return TOKEN_TAIL_CHARACTER.test(match.slice(match.indexOf("-") + 1)) ? REDACTION : match;
 }
 /**
 * 抹掉文本里 key 形状的片段。
@@ -441,7 +644,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 +669,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 +701,10 @@ function assertToolOutput(schema, value, toolName, messages) {
 	}
 	return value;
 }
-//#endregion
-//#region lib/argv-guard.ts
+// lib/argv-guard.ts
+/** 归一后剥掉的尾随分隔符。 */
+const TRAILING_POSIX_SLASHES = /\/+$/u;
+const TRAILING_PATH_SEPARATORS = /[\\/]+$/u;
 /**
 * POSIX sh 单引号转义：' → '\''。把任意字符串安全放进单引号内，防注入。
 *
@@ -513,22 +718,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(TRAILING_POSIX_SLASHES, "") : normalized;
+	}
+	if (process.platform === "win32" && path.win32.isAbsolute(trimmed)) {
+		const normalized = path.win32.normalize(trimmed);
+		return normalized.length > 3 ? normalized.replace(TRAILING_PATH_SEPARATORS, "") : 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 +816,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 +863,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,15 +898,22 @@ const REVIEW_OUTPUT_FORMATS = [
 function resolveOutputFormat(value) {
 	return REVIEW_OUTPUT_FORMATS.find((candidate) => candidate === value) ?? "json";
 }
-//#endregion
-//#region lib/cli.ts
-/** `ocr review|scan|delegate preview` 的背景说明 flag（三处命令构造共用一条）。
-*  pushTextFlag 按 `flag.slice(2)` 反推报错用的参数名，故值必须带 `--` 前缀。 */
+// lib/cli.ts
+/** Homebrew 安装路径（`Cellar` / `Homebrew` 任一段）。 */
+const HOMEBREW_PATH = /(?:^|[/\\])(?:Cellar|Homebrew)(?:[/\\]|$)/iu;
+/** `ocr` 版本行：`open-code-review v1.13.3`（允许预发布/构建元数据）。 */
+const OCR_VERSION = /open-code-review\s+v?(?<version>\d+\.\d+(?:\.\d+)?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)/u;
 /** `--exclude` 的模式条数上限。**不是审查范围的上限**，只是防一条失控输入把命令串撑爆；
 *  真实使用里几十条就到头，给到 2000 是为了"尽量不截断"——超了会明确告警，不静默丢。 */
 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";
+/** `ocr review|scan|delegate preview` 的背景说明 flag（三处命令构造共用一条）。
+*  pushTextFlag 按 `flag.slice(2)` 反推报错用的参数名，故值必须带 `--` 前缀。 */
 const BACKGROUND_FLAG = "--background";
 /**
 * 本包的契约是按外部 `ocr` CLI 的哪一版核对的（README 的前置条件、装法建议与工具回显里
@@ -620,19 +924,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 +997,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 +1080,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：值缺省/空串则省略，错类型抛错（静默丢弃等于悄悄改变语义）。 */
@@ -834,7 +1201,7 @@ function realPathOrSelf(candidate) {
 function inferOcrInstallChannel(candidate) {
 	const resolved = realPathOrSelf(candidate);
 	if (resolved.includes("node_modules")) return "npm";
-	return /(?:^|[/\\])(?:Cellar|Homebrew)(?:[/\\]|$)/iu.test(resolved) ? "brew" : "unknown";
+	return HOMEBREW_PATH.test(resolved) ? "brew" : "unknown";
 }
 /** brew 的 formula 名与 npm 的包名不同：formula 不带 scope。 */
 const OCR_BREW_FORMULA = "open-code-review";
@@ -973,7 +1340,7 @@ function buildVersionCommand() {
 * 读不出即 null：未发布构建的 `<Version>` 是 `dev`，没有版本号可报，猜一个等于编一个。
 */
 function parseOcrVersion(text) {
-	return /open-code-review\s+v?(?<version>\d+\.\d+(?:\.\d+)?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)/u.exec(text)?.groups?.["version"] ?? null;
+	return OCR_VERSION.exec(text)?.groups?.["version"] ?? null;
 }
 /**
 * `--format` 交给 OCR 的取值：本包只认 json——`lib/parse.ts` 的解析层只解 JSON 一份形状。
@@ -996,6 +1363,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 +1372,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 +1391,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 +1414,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 +1425,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 +1468,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 +1483,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 +1561,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 +1708,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 +1717,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 +1730,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 +1744,21 @@ function aggregateComments(comments) {
 		unknownSeverityCount
 	};
 }
-//#endregion
-//#region lib/parse.ts
+// lib/parse.ts
+/** 只认十进制整数的行号/计数文本。 */
+const DECIMAL_INTEGER = /^\d+$/u;
 /**
 * 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 +1792,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/
@@ -1251,7 +1802,7 @@ function num(value) {
 	if (typeof value === "number") return nonNegativeInt(value);
 	if (typeof value === "string") {
 		const trimmed = value.trim();
-		if (!/^\d+$/u.test(trimmed)) return 0;
+		if (!DECIMAL_INTEGER.test(trimmed)) return 0;
 		return nonNegativeInt(Number(trimmed));
 	}
 	return 0;
@@ -1265,6 +1816,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 - 已渲染的明细行
@@ -1280,7 +1867,7 @@ function capLines(lines, total, messages) {
 *  否则 "x" 或 -1 会被 num 折成 0，把「读不出」伪装成「零失败」）。 */
 function isCount(value) {
 	if (typeof value === "number") return Number.isSafeInteger(value) && value >= 0;
-	return typeof value === "string" && /^\d+$/u.test(value.trim());
+	return typeof value === "string" && DECIMAL_INTEGER.test(value.trim());
 }
 /**
 * 解析 `tool_calls`。字段缺失或为 null（这一场没有工具调用记录）返回 null；
@@ -1401,6 +1988,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 +2018,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 +2034,8 @@ function diagnosticsOf(root, messages) {
 	return {
 		warnings,
 		toolCalls: toolCalls.view,
-		coverage: coverage.view
+		coverage: coverage.view,
+		limitReached
 	};
 }
 /**
@@ -1469,13 +2069,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 +2087,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 +2135,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,80 +2299,747 @@ 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
 	};
 }
-/**
+/** 一个 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
+	};
+}
+/** 解析 `ocr session compare --json`：四个桶与两侧会话标识。 */
+function parseSessionCompare(text) {
+	let doc;
+	try {
+		doc = JSON.parse(text);
+	} catch {
+		return {
+			ok: false,
+			view: null
+		};
+	}
+	if (!isRecord(doc)) return {
+		ok: false,
+		view: null
+	};
+	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 {
+		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
+		}
+	};
+}
+// 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
+		},
+		mode: {
+			type: "string",
+			const: "background"
+		},
+		tool: { type: "string" },
+		repo: { type: "string" },
+		processStatus: {
+			type: "string",
+			enum: [
+				"running",
+				"completed",
+				"killed"
+			]
+		},
+		jobId: { type: "string" },
+		polling: { type: "string" }
+	}
+};
+/** 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" }
+			}
+		}] },
+		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";
+/** provider 的 baseURL 只认 http(s)。 */
+const HTTP_URL$1 = /^https?:\/\//iu;
+/**
+* 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 || !HTTP_URL$1.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,
@@ -1762,13 +3051,12 @@ function providersFromSettingsValue(value) {
 	if (!isRecord(providers)) return [];
 	const out = [];
 	for (const [name, raw] of Object.entries(providers)) {
-		const parsed = providerFromRaw(name, raw);
+		const parsed = isUsableProviderName(name) ? providerFromRaw(name, raw) : null;
 		if (parsed !== null) out.push(parsed);
 	}
 	return out;
 }
-//#endregion
-//#region lib/provider-source.ts
+// lib/provider-source.ts
 /** provider 清单所在的官方 settings 命名空间（base bundle 的 pi-ai 适配器注册）。 */
 const PI_AI_NAMESPACE = "llm-pi-ai";
 const SOURCE_READY = Object.freeze({
@@ -1813,7 +3101,19 @@ function readProviders(gateway, messages) {
 			}
 		};
 	}
-	const hit = descriptors.find((descriptor) => descriptor.ns === PI_AI_NAMESPACE);
+	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: {
@@ -1821,7 +3121,8 @@ function readProviders(gateway, messages) {
 			message: format(messages.sourceNamespaceUnavailable, { ns: PI_AI_NAMESPACE })
 		}
 	};
-	if (!isRecord(fieldOf(hit.value, "providers"))) return {
+	const providersValue = fieldOf(hit.value, "providers");
+	if (!isRecord(providersValue)) return {
 		providers: [],
 		source: {
 			status: "namespace-unavailable",
@@ -1860,17 +3161,26 @@ async function markKeyFlags(gateway, providers) {
 			...providerCfg,
 			hasKey: false
 		};
-		const hasKey = await gateway.credentialConfigured(ref).catch(() => false);
+		let hasKey;
+		try {
+			hasKey = await gateway.credentialConfigured(ref);
+		} catch {
+			hasKey = false;
+		}
 		return {
 			...providerCfg,
 			hasKey
 		};
 	}));
 }
-//#endregion
-//#region lib/config-store.ts
+// lib/config-store.ts
 /** api_key_cmd 脚本名（pluginDir 兜底路径的唯一拼法来源）。 */
 const GET_CRED_SCRIPT = path.join("scripts", "get-cred.mjs");
+/** 尾部反斜杠 / 翻倍反斜杠 / env 键 / 行首 node 命令。 */
+const TRAILING_BACKSLASHES = /\\+$/u;
+const DOUBLED_BACKSLASHES = /(?:\\\\)+$/u;
+const ENV_KEY = /^[A-Z0-9_]+$/u;
+const LEADING_NODE_CMD = /^node[ \t]+/u;
 /** 未知值 → 安全字符串（非字符串给 ''）。 */
 function strOf(value) {
 	return typeof value === "string" ? value : "";
@@ -1899,7 +3209,12 @@ function loadOcrConfig(configJsonText) {
 		raw: doc
 	};
 }
-/** config.json 的当前文本（读不到/不存在一律空串，交由 loadOcrConfig 的宽容读侧处理）。 */
+/** 读侧专用：config.json 的当前文本，读不到一律空串。
+*
+*  只给「读侧要宽容」的那一类调用用（设置卡打开时渲染当前选择：盘上文件坏了也必须
+*  能打开卡片，用户正是靠卡片去修）。**写侧不能用它**——把 EACCES/EIO 折成空串等于
+*  把「读不到」当成「文件不存在」，随后整份覆盖就丢掉了用户既有的全部配置；写侧走
+*  readExistingText。 */
 function readText(configPath) {
 	try {
 		return readFileSync(configPath, "utf8");
@@ -1907,6 +3222,27 @@ function readText(configPath) {
 		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），单引号
@@ -1917,7 +3253,7 @@ function readText(configPath) {
 * 保证常规路径形态正确）。
 */
 function shqDyn(value) {
-	if (process.platform === "win32") return `"${value.replaceAll("\"", "\"\"").replace(/\\+$/u, (backslashes) => backslashes + backslashes)}"`;
+	if (process.platform === "win32") return `"${value.replaceAll("\"", "\"\"").replace(TRAILING_BACKSLASHES, (backslashes) => backslashes + backslashes)}"`;
 	return `'${value.replaceAll("'", String.raw`'\''`)}'`;
 }
 /** api_key_cmd 值构造：脚本路径与 env key 名（及可选的 dsh 数据目录）shq 转义后
@@ -1928,7 +3264,7 @@ function shqDyn(value) {
 *  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 }));
+	if (!ENV_KEY.test(envKey)) throw new Error(format(messages.badEnvKey, { key: envKey }));
 	const parts = [
 		"node",
 		shqDyn(scriptPath),
@@ -2008,7 +3344,7 @@ function readDqToken(body, start) {
 	}
 	if (!closed) return null;
 	return {
-		value: value.replace(/(?:\\\\)+$/u, (backslashes) => "\\".repeat(backslashes.length / 2)),
+		value: value.replace(DOUBLED_BACKSLASHES, (backslashes) => "\\".repeat(backslashes.length / 2)),
 		next: i
 	};
 }
@@ -2050,13 +3386,13 @@ function readDqTokens(body) {
 * 把用户手写的凭据取用方式弄坏，而那正是本包明令不该插手的部分。
 */
 function parseApiKeyCmd(command) {
-	const body = command.replace(/^node[ \t]+/u, "");
+	const body = command.replace(LEADING_NODE_CMD, "");
 	if (body === command) return null;
 	const tokens = readShqTokens(body) ?? readDqTokens(body);
 	if (tokens === null) return null;
 	const script = tokens[0] ?? "";
 	const envKey = tokens[1] ?? "";
-	if (script === "" || tokens.length < 2 || tokens.length > 3 || !/^[A-Z0-9_]+$/u.test(envKey)) return null;
+	if (script === "" || tokens.length < 2 || tokens.length > 3 || !ENV_KEY.test(envKey)) return null;
 	return {
 		script,
 		envKey,
@@ -2230,8 +3566,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 +3687,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 +3731,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 +3758,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,34 +3806,301 @@ 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 result = repointDanglingKeyScripts(doc, current, messages);
-				if (result.repointed.length === 0) return result.repointed;
-				await writeConfigAtomic(paths.ocrConfigJson, renderConfigDoc(doc));
-				return result.repointed;
-			}),
-			checked: true
+			repointed: await updateConfigLocked(paths.ocrConfigJson, async () => {
+				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));
+				return result.repointed;
+			}),
+			checked: true
+		};
+	} catch {
+		return {
+			repointed: [],
+			checked: false
+		};
+	}
+}
+// lib/remote-shape.ts
+/** 宿主服务键 = 客户端线上命名空间（两侧共用的唯一来源）。 */
+const OCR_REMOTE_NAMESPACE = "ocrReview";
+// lib/mcp-config.ts
+/** 整体上限：MCP 配置是一份人工维护的小表，不承载大文件。 */
+const MCP_MAX_BYTES = 65536;
+/** remote MCP server 的 url 只认 http(s)。 */
+const HTTP_URL = /^https?:\/\//iu;
+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 (!HTTP_URL.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)
+			})
 		};
-	} catch {
+	}
+}
+/** 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 {
-			repointed: [],
-			checked: false
+			ok: false,
+			error: format(messages.chatGptSaveFailed, { cause: String(error) })
 		};
 	}
 }
-//#endregion
-//#region lib/remote-shape.ts
-/** 宿主服务键 = 客户端线上命名空间（两侧共用的唯一来源）。 */
-const OCR_REMOTE_NAMESPACE = "ocrReview";
-//#endregion
-//#region host.ts
+// host.ts
 const PLUGIN_DIR = import.meta.dirname;
 const MAX_TIMEOUT_REQUEST_MS = 2147483647;
 const LLM_TEST_TIMEOUT_MS = 9e4;
@@ -2543,10 +4145,13 @@ function isLiveOcrStatus(status) {
 * @param jobs 官方注册表
 * @returns {void}
 */
-function pruneOcrJobHistory(jobs) {
-	const settled = jobs.list().filter((job) => job.kind === OCR_JOB_KIND && !isLiveOcrStatus(job.status));
+function pruneOcrJobHistory(jobs, owner, ledger) {
+	const settled = jobs.list(owner).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);
+	for (const job of settled.slice(0, Math.max(excess, 0))) {
+		jobs.remove(job.id, owner);
+		ledger.delete(job.id);
+	}
 }
 /**
 * 在 controller 闸门下起一条未拥有作业，起完立刻摘掉。
@@ -2593,380 +4198,110 @@ async function enforceOcrDeadline(jobs, id, reason, backgroundMaxMs) {
 * @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
-	}];
-}
-/** 可空 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" }
+*/
+function reclaimSessionJobs(jobs, reason, owner, ledger) {
+	for (const job of jobs.list(owner)) if (job.kind === OCR_JOB_KIND && job.owner === owner) {
+		ledger.delete(job.id);
+		if (isLiveOcrStatus(job.status)) jobs.kill(job.id, owner, reason);
+		else jobs.remove(job.id, owner);
 	}
-}, { type: "string" }] };
-/** ocr_session：sessionOutput 本身就是一手透传的字符串（诚实的值），外层仍是对象
-*  好让 hint 有处安放。 */
-const SESSION_OUTPUT_SCHEMA = {
-	type: "object",
-	additionalProperties: false,
-	required: ["sessionOutput", "hint"],
-	properties: {
-		sessionOutput: { type: "string" },
-		hint: { type: "string" }
+}
+/** 卸载时收一条有主作业：id 只有台账知道，kill/remove 必须带 owner 作 caller。 */
+function reclaimOwnedJob(jobs, id, owner, reason) {
+	try {
+		if (isLiveOcrStatus(jobs.get(id, owner).status)) jobs.kill(id, owner, reason);
+		else jobs.remove(id, owner);
+	} catch {}
+}
+/**
+* 卸载时收掉本包起过的全部作业：无主的经 `list()` 枚举，有主的只有台账知道 id
+* （注册表对没有 caller 的视图隐藏它们，且 kill/remove 必须带 owner 作 caller）。
+*/
+function reclaimAllJobs(jobs, reason, ledger) {
+	for (const job of jobs.list()) if (job.kind === OCR_JOB_KIND) {
+		if (isLiveOcrStatus(job.status)) jobs.kill(job.id, void 0, reason);
+		else jobs.remove(job.id);
 	}
-};
+	const owned = new Map(ledger);
+	ledger.clear();
+	for (const [id, owner] of owned) if (owner !== void 0) reclaimOwnedJob(jobs, id, owner, reason);
+}
+/** 工具调用发起时的会话 id；形状不对就当没有（agentless）。 */
+function sessionIdOf(exec) {
+	const id = exec.agent?.session?.id;
+	return typeof id === "string" && id.length > 0 ? id : void 0;
+}
+/** 该调用可绑定的作业 owner：会话 id 存在、且宿主注册表里确有这条活 Agent。
+*  给不出活 Agent 时退回 agentless —— 拿一个注册表不认的 id 去 start 只会整条失败。 */
+function ownerOf(host, exec) {
+	const id = sessionIdOf(exec);
+	const agents = host.get("agents");
+	return id !== void 0 && agents?.get(id) !== void 0 ? id : void 0;
+}
+/** 当前会话工作区（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 +4320,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 闸与
@@ -3122,7 +4457,7 @@ async function outcomeWhenSettled(proc) {
 * @param job 这次后台评审的描述
 * @returns 后台启动回执（canonical 对象，模型侧契约）
 */
-async function startBackground(host, job) {
+async function startBackground(host, job, ledger) {
 	const registry = host.get("jobs");
 	if (registry === void 0) throw new Error("background review unavailable: the host provides no ctx.jobs (load @deepseek-ai/dsh-jobs-local); run it with wait:true instead");
 	const spec = host.shell.resolve({
@@ -3134,13 +4469,14 @@ async function startBackground(host, job) {
 		sandboxPolicy: ocrSandboxPolicy(job.workdir)
 	});
 	const proc = await host.shell.execute(spec);
-	pruneOcrJobHistory(registry);
+	pruneOcrJobHistory(registry, job.owner, ledger);
 	const messages = localeMessages(host);
 	let jobId;
 	try {
 		jobId = startUnderOcrController(registry, {
 			kind: OCR_JOB_KIND,
 			label: `${job.tool} ${job.repo}`,
+			...job.owner === void 0 ? {} : { owner: job.owner },
 			output: reviewSources(proc, messages),
 			run: () => ({
 				cancel: () => {
@@ -3153,6 +4489,7 @@ async function startBackground(host, job) {
 		killProc(proc);
 		throw error;
 	}
+	ledger.set(jobId, job.owner);
 	const backstopMinutes = Math.round(job.backgroundMaxMs / 6e4);
 	enforceOcrDeadline(registry, jobId, format(messages.jobReasonTimeout, { minutes: String(backstopMinutes) }), job.backgroundMaxMs);
 	return {
@@ -3191,7 +4528,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 +4697,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 +4737,7 @@ function pluginPaths(config, messages) {
 /**
 * ocr 子进程的 HOME 重定向值（工具执行侧专用，**不抛错**）：设置项命中
 * `<X>/.opencodereview/config.json` 布局 → X；未设置/坏设置 → undefined。工具不
-* 走 pluginPaths（那会在坏设置下把五个工具一并拖死），坏设置的错误由端点侧的
+* 走 pluginPaths（那会在坏设置下把七个工具一并拖死），坏设置的错误由端点侧的
 * resolveOcrConfigPath 报给卡片——「工具与设置照常可用」的口径不变。
 */
 function ocrHome(config) {
@@ -3412,7 +4750,7 @@ function ocrHome(config) {
 * 为什么必须在这一层而不是启动时：config.json 里的脚本路径是**写那一刻**的插件安装
 * 目录，而插件会被重装、换 profile（desktop / browser / 任意自定义名）、换发布形态。
 * 目录一变那条命令就悬空，ocr 侧报的是「resolve LLM endpoint 失败」，与真因毫无
-* 关系——五个工具一次性全挂，而配置文件里没有任何线索指向「本包被挪了地方」。
+* 关系——七个工具一次性全挂，而配置文件里没有任何线索指向「本包被挪了地方」。
 * 当前路径一律取自 PLUGIN_DIR（import.meta.dirname），与 profile 命名
 * 无关，故 desktop / browser / 自定义名走的是同一条路径。
 *
@@ -3451,7 +4789,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 +4879,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 +4890,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 +4904,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 +4928,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 +5160,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 +5280,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 +5320,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,7 +5361,71 @@ const productionProbe = () => resolveOcrAvailability();
 function assertOcrPresent(status, messages, install) {
 	if (status.source === "none") throw new Error(format(messages.ocrBinaryMissing, { install }));
 }
-function registerReviewTool(host, config, probe, versionSink) {
+/** 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, ledger) {
 	const msgs = localeMessages(host);
 	define(host, {
 		name: "ocr_review",
@@ -3978,6 +5493,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 +5522,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");
@@ -4004,10 +5547,11 @@ function registerReviewTool(host, config, probe, versionSink) {
 					workdir,
 					tool: "ocr_review",
 					repo,
+					owner: ownerOf(host, exec),
 					stdoutMaxBytes: config.stdoutMaxBytes,
 					backgroundMaxMs: config.ocrBackgroundMaxMs,
 					env: ocrEnv(config)
-				});
+				}, ledger);
 				try {
 					await runForeground(host, guarded, workdir, tuningOf(config), exec.signal);
 				} catch (error) {
@@ -4031,7 +5575,7 @@ function registerReviewTool(host, config, probe, versionSink) {
 		}
 	});
 }
-function registerScanTool(host, config, probe, versionSink) {
+function registerScanTool(host, config, probe, versionSink, ledger) {
 	const msgs = localeMessages(host);
 	define(host, {
 		name: "ocr_scan",
@@ -4079,6 +5623,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 +5660,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);
@@ -4103,10 +5683,11 @@ function registerScanTool(host, config, probe, versionSink) {
 					workdir,
 					tool: "ocr_scan",
 					repo,
+					owner: ownerOf(host, exec),
 					stdoutMaxBytes: config.stdoutMaxBytes,
 					backgroundMaxMs: config.ocrBackgroundMaxMs,
 					env: ocrEnv(config)
-				});
+				}, ledger);
 				try {
 					await runForeground(host, guarded, workdir, tuningOf(config), exec.signal);
 				} catch (error) {
@@ -4276,7 +5857,9 @@ function registerSessionTool(host, config, probe) {
 					enum: [
 						"list",
 						"show",
-						"comments"
+						"comments",
+						"compare",
+						"export"
 					],
 					description: msgs.paramSessionAction
 				},
@@ -4284,6 +5867,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 +5897,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 +5954,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 的闭包，
@@ -4355,29 +6074,34 @@ function apply(ctx, config, probe) {
 	const host = resolveHost(ctx);
 	const endpointVerify = { value: null };
 	const versionSink = { value: null };
+	const jobLedger = /* @__PURE__ */ new Map();
 	if (config.startupVerify) {
 		probeEndpointAtApply(host, config, endpointVerify);
 		probeVersionAtApply(host, config, versionSink);
 	}
 	ctx.effect(() => () => {
 		const jobs = ctx.get("jobs");
-		if (jobs !== void 0) reclaimOcrJobs(jobs, localeMessages(ctx).jobReasonUnload);
+		if (jobs !== void 0) reclaimAllJobs(jobs, localeMessages(ctx).jobReasonUnload, jobLedger);
 	}, "ocr-review: background jobs");
-	ctx.effect(() => ctx.on("session/disposed", () => {
+	ctx.effect(() => ctx.on("session/disposed", (session) => {
 		const jobs = ctx.get("jobs");
 		if (jobs === void 0) return;
+		const owner = session.id;
+		if (typeof owner !== "string" || owner.length === 0) return;
 		try {
-			reclaimOcrJobs(jobs, localeMessages(ctx).jobReasonSessionStopped);
+			reclaimSessionJobs(jobs, localeMessages(ctx).jobReasonSessionStopped, owner, jobLedger);
 		} catch {}
 	}), "ocr-review: session stop reaps background runs");
 	host.inject(["settings"], (child) => {
 		child.effect(() => child.settings.configure({ auto: false }, host.fiber));
 	});
-	registerReviewTool(host, config, probe, versionSink);
-	registerScanTool(host, config, probe, versionSink);
+	registerReviewTool(host, config, probe, versionSink, jobLedger);
+	registerScanTool(host, config, probe, versionSink, jobLedger);
 	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 +6131,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 };