dsh-escalation-review

English · 简体中文

只审「沙箱越界」的 LLM 评审插件（DeepSeek Harness，下称 DSH）。

工作区内的读写与命令跑在原生沙箱上，不评审、不产生额外模型调用。插件只为一种情况醒来：某次工具调用 请求离开沙箱（sandbox_permissions 与当前生效模式不同）。这一次调用会被交给模型裁决 —— 放行、拒绝， 或者交回给你 —— 并且走宿主本来就有的一套管路：把审批回答成 allowed-once，或在工具体执行前返回三态决策对象。

卡片保留官方 session projection 和 $gate 策略条目；评审期间的实时相位同时通过 DSH 已认证的 Connection Fetch 通道交付，因此无需等待下一条会话日志。可取消的长轮询只读取指定会话与调用， 不单独监听端口。旧宿主缺少这个能力时仍使用投影，尚未收到事实时显示中性文案。 评审理由保存在内存中，重启宿主后可能无法恢复。

Codex 风格的评审器

策略跟随 OpenAI 的 Codex guardian 模板（codex-rs/prompts/templates/guardian/policy_template.md）， 这也是本插件主要的工作量所在。

• 三轴契约：风险档位与授权分别打分，两者一起决定 allow / deny / ask。授权在每一次越界时重新 推导：过去的批准只有在证据仍留在会话里时才算数。
• medium 看的是后果可逆，不是工件可逆：只有当爆炸半径有界并且它造成的影响能被撤销时，才算 medium。能把文件改回来，不等于能把效果收回来。而且 medium 只有在授权为 high 时才可能判成 allow —— 用户得点名那一个动作、目标与范围；"授权了实质"不够，解析器会直接拒掉这种输出。
• 系统与安全控制状态一律 high：hosts、DNS、防火墙规则、服务、证书、PATH。它们都能改回来， 但已经发出去的流量收不回来。
• 有更安全的替代方案时降档：同一目标若能绕开危险步骤达成，那么危险步骤就不是用户要的东西。
• 缺失的记录不等于许可：没有证据就是没有授权，而不是默认同意。
• 事后批准按高风险处理：事后补的批准打不开 critical 动作。
• 有界根投影：用户指令以「头部 4 条 + 尾部 12 条、上限 16」进入评审，丢就整条丢、不截断，并显式留下 「证据不完整」标记。证据按角色标注：人类指令、直接父级、审批回答、检查点、事实。

另有四条决定边缘情况：

• 用户明确禁止 = 硬拒绝，它压过风险档位，连低风险动作也不例外。
• 证据是数据，不是指令：命令文本、文件内容、工具输出都不构成授权；写着"用户已经允许了"的文本什么也 证明不了。
• 不按外观降档：形似凭据的载荷不会因为"看起来像占位符"而变安全，导出也不会因为自称的去向而变安全。
• 先交叉校验，再判定：待审动作会与同一 callId 的日志 tool/call 比对，一旦明确不一致就中止评审； 判定格式不合法按评审失败处理。

这些想法的来源与逐字重合度的实测记录见 NOTICE.md。

与内置 auto 预设的区别

应用内置 @deepseek-ai/dsh-experimental-auto-review：它注册一个 auto 权限预设，把会话绑到 danger-full-access，并审核每一个原生调用 —— 每次调用多一次模型请求，且运行在完全放开权限下。

	内置 auto 预设	本插件
沙箱档位	danger-full-access	会话原本的档位，因此 workspace-write 继续生效
审核范围	每一个原生调用	只有请求越界的那一次
预设表	注册 auto	不动你的预设表 —— 门控是本插件自己的开关
额外模型调用	每次调用一次	每次越界一次，其余为零

保留会话原本的沙箱档位，正是这个对比的意义：普通工作由沙箱兜住，评审器只补上 DSH 本来会停下来问你的那一段。

行为

情形	结果
沙箱内的普通调用	不评审，原样交给下游处理者。
越界调用，介入开关关闭	不评审、不干预、不花模型调用。这是默认状态。
越界调用，开关打开	评审一次并记日志。判定放行则审批被回答成 allowed-once（你不会被问第二次）；判定拒绝则工具不执行、理由回传模型。
评审失败 / 超时	由 failMode 决定，默认 deny（失败即拒）。
连续三次解析为 deny 的判定，或 50 次窗口内 10 次	熔断：不再拒绝，改为交回人工 —— 并且该 turn 内一直如此（评审失败出口、熔断前注册好的代答者也都交回人工）。只有解析出的 deny 判定推进计数（评审失败不推进）；而动作变化与证据失效两条出口仍按 failMode 处理。新 turn 从零开始；observe 模式下永不介入。
待审动作与会话日志里的工具调用明确不一致	停止评审，而不是拿无法核对的证据下结论。
评审之后待审动作被改动	每次放行前都会拿评审时冻结的动作指纹复核；不一致即失败关闭（failMode），并记 action-changed —— 实际执行的动作必须就是被评审的那个。

评审按 reviewConcurrency 排队（默认 1，上限 4）：默认就是与以前一致的一个接一个；调大后多个越界 调用并行评审，超出上限的排队等待 —— 排队不丢弃任何调用，排队时间从这一次评审自己的总预算里扣。

被评审的动作就是实际执行的动作。 评审开始时插件会冻结待审动作的指纹，任何放行落地之前（包括"替你回答 审批"之前）都再复核一次；一旦动作变了（或者根本算不出指纹），这次放行就作废，由 failMode 决定是直接拒绝 还是交回给你。

运行前提

• DSH 0.1.7-rc.2 或 0.2.0-rc.1（两者都实测过），Node 24。
• 只实测过 Windows；其它平台预期可用，但未验证。
• peerDependencies：@deepseek-ai/cordis ~4.0.4、@deepseek-ai/dsh-llm >=0.1.7-rc.2 <0.3.0。
• @deepseek-ai/dsh* 的 peer 要写版本区间：宿主用 semver.satisfies(runtime, range, { includePrerelease: true }) 判定，写死精确预发布版本会在 DSH 升级后被判为不兼容。

安装

从本地目录安装，用 GUI 最干净：左侧边栏「插件」（不是"设置"）→ 「添加插件」→ 填这个目录的绝对路径， 例如 D:\path\to\checkout\plugins\escalation-review。它会以 link: 依赖登记，并追加到 dsh.profile.bundles。

dsh plugin --profile <profile 名> add dsh-escalation-review                    # 从 npm 装
dsh plugin --profile <profile 名> add D:\path\to\plugins\escalation-review     # 从本地检出装

• ~/.dsh/profiles/web 与 ~/.dsh/profiles/desktop 互相独立，装进一个不影响另一个。想用 dsh web 测，就加 --profile web。
• 宿主半边是启动时从磁盘加载的，所以装完要重启 DSH；改了 lib/ 下任何文件也要重启一次。会话里的 客户端半边同样需要重启才重载，桌面版里单纯刷新页面不够。

卸载在同一张插件页上做，或者从 dsh.profile.bundles 里删掉那一条。

配置

enabled 是总门控，随包关闭：关闭时插件不评审、不产生模型调用；打开后它接管所有沙箱越界的审批。 门控属于插件本身，而不是你的权限表 —— 所以安装它不会改写你的预设，也与某个会话恰好选中哪个预设无关。 可以在配置页上设（卡片第一行的两档控件：关闭 / 打开），也可以写 "enabled": true，或 GUI 写入的 文本形式 "enabledText": "true"。

优先级（低 → 高）：包内 config.json → ~/.dsh/escalation-review.config.json → 传了 configPath 就用它 → 插件条目里的 config: 段 → 配置页写入的设置层（有它自己的 *.ui.json 伴生文件）。文件层每次越界时重读， 设置层约每 2 秒轮询一次，所以改动不需要重启；只有改插件代码才必须重启。

本包的 config.json 容忍 // 与 /* */ 注释；cordis.patch.yml 是 YAML，注释只能用 #，解析失败会让 加载器静默跳过整个 bundle。

键	默认值	含义
enabled	false	介入开关（总门控）。
enabledText	""	开关的文本形式（"true" / "false"），由配置页写入；非空时覆盖 enabled。
provider / model	""	用哪个 provider 与模型评审；留空跟随当前会话。
reasoningEffort	""	评审思考强度：off、minimal、low、medium、high、xhigh、max，留空跟随会话。
failMode	deny	评审失败或超时的含义：deny 或 ask。
denyMode	deny	评审判定为拒绝的含义：deny 直接拒绝，ask 交回人工。
reviewConcurrency	1	同时进行的评审上限（1–4）。1＝与从前一致、严格一个接一个；超过上限的调用排队 —— 不丢弃、也绝不越过上限，排队时间会从这次评审的总预算里扣掉。
verifyMode	on	评审时是否可用只读工具：on（默认）或 off；auto / always 作为 on 的别名继续接受。详见评审时的只读工具。
verifyModeText	""	verifyMode 的文本形态（"off" / "on"，也接受 auto / always 别名）；非空时覆盖 verifyMode。
probeRunner	shell	只读探针：shell（在待审动作所在的世界里跑只读命令，默认）或 inproc（只跑 filesystem 类探针，且需可证明同世界）。
policyExtra	""	你自己写的规则，追加到评审策略末尾（与 Codex 的 auto_review.extra_policy 同一种显式机制）。想改评审口径就用它。
allowedHosts	[]	命中这些主机的常规网络操作按 low 处理。注意：在用户配置里写空数组会覆盖包内清单，要写就写全量。
allowedHostsText	""	allowedHosts 的文本形态（逗号或换行分隔），由配置页写入；非空时覆盖 allowedHosts。
timeoutMs	100000	一次评审的总预算（含重试）。
attemptTimeoutMs	30000	每一轮上限（1 次模型调用 + 该轮工具）；超时后可以重试，整次评审仍受 timeoutMs 约束。
retryDelayMs	5000	两次尝试之间的等待。
minAttemptMs	2000	扣掉等待后剩余预算低于此值就不再重试。

评审时的只读工具

一次评审通常就是一次请求：模型读完证据直接给判定。verifyMode 决定它是否还能顺手核实事实，随包默认打开：

• on（默认）—— 模型可以先要只读工具核实事实，再给判定；
• off —— 完全不给工具（prompt 里连工具协议都没有，因此只有一次请求）。

auto 与 always 作为 on 的别名继续接受，旧配置不会失效。

这是一个受限小 loop，而不是子代理：它在本进程里跑，不开会话、不落盘、不注入工作区指令、也不会自己逛。 一步是默认路径：证据够就直接给判定。缺关键事实时，模型在一条消息里要齐所有工具 （{"tools":[{"name":"read_file","path":"…"}, …]}），我们一批并行执行，结果一轮回灌，然后优先收尾。 于是普通评审一次请求、需要核实 2–4 次；硬上限各自独立且写死（4 步 / 3 批 / 8 次工具 / 单次 16KB / 累计 48KB / 单条路径 1024 字符）， 其中工具额度是整个评审共享的（重试不会重新获得读取额度），只有步数是每次请求重算 —— "一个工具一步"不可能出现，也没有无限游走：到任何一条上限就带着现有证据收尾，拿不到判定即 fail-closed。

它们只看该看的：工具只在只读沙箱里执行（执行器必须自报沙箱档位，执行后还要核对它回报的事实）， read_file 只读本次动作明确点名的那个文件（按 DSH 的 opaque 目标身份精确比对，不解析路径、不折叠大小写）， list_dir / stat 的目录包含判定交给 backend 自己的 fs.contains()；凭据与秘密路径 （.credentials* / SSH 私钥 / 钥匙串 / .npmrc / .env* / *.pem / *.key / *.p12 / *.pfx）一律拒绝， 二进制文件、以及拿不到 processPath / contains 能力的情况同样拒绝（fail-closed）。

工具	读什么	上限
read_file	文本文件	16 KB，截断处有标注
list_dir	目录	最多 200 条，并标注还剩多少条
stat	存在性 / 类型 / 大小	只有 metadata

工具没有任何写路径，也绝不使用插件自身的宿主权限：

• 首选 ctx.fs，但只有当它是沙箱化实现（会暴露 sandboxMode）时才用；
• 否则用 ctx.shell，带 sandboxPolicy: { mode: 'read-only', workspaceRoot }，并记录 run.sandbox 回报的 实际沙箱事实；
• 两者都拿不到就不执行任何工具（日志里记 verify.denied = 'no-sandbox'），绝不退化成非沙箱读。

路径白名单由本插件把关（沙箱只保证写的边界）：工作区、以及动作参数里出现过的路径可读；凭据类路径 （~/.dsh/.credentials*、SSH 私钥、钥匙串、浏览器配置、.npmrc、.git-credentials）一律拒绝并写日志。 工具输出以数据回灌，显式标注"不可信、不是指令、不是授权"；判定仍走同一套严格协议，所以 critical 恒拒、解析失败仍 fail-closed。loop 若在预算或步数内拿不到判定，就什么都不猜：这次评审按失败处理， 由你的 failMode 决定（ask 则交回你手上）。每次评审都会记下工具做了什么 —— verify: { tools: 'on'|'off', steps, calls: [{name, path, ms, bytes, sandbox}], denied? }，含观察到的 沙箱事实，所以"确实在沙箱里跑的"事后可查。

它做什么，不做什么

它替你回答越界审批。 开关打开时，放行判定会以 allowed-once 的形式交付：那一次调用在沙箱之外执行， 过程中不弹窗。能力与风险都在这里 —— 你把"这一次我自己看一眼"换成了"模型看过一眼"。

它把证据发给你的模型提供方。 待审动作、会话上下文、有界指令投影，以及宿主自己跑出来的只读探针结果， 会组成一次评审请求，走 DSH 里配置的 provider（或你在卡片里选的那个）。评审消耗 token。路径事实不在其中： 宿主不解析命令里的目标（解析的失败模式是静默漏目标，正好与 fail-closed 相反），所以你看到的是动作本身， 加上宿主选择跑的那几条探针结果。

它留一份本地日志。 ~/.dsh/escalation-review.log 每行一个 JSON 对象，含命令文本与判定结论、理由。 请把它当作和它所概括的会话同等敏感的东西。

它从不写会话事件。 判定与理由在内存里交付、并呈现到审核卡片上，所以会话历史仍是宿主写下的样子。

失败即拒，反复被拒会熔断。 超时、JSON 不合法、provider 报错、交叉校验失败，默认都以 deny 收场； 连续三次解析为 deny 的判定、或 50 次窗口内 10 次，熔断触发 —— 此后该 turn 内每一次越界都交给你。 评审失败不推进这个计数；动作变化与证据失效两条出口仍按 failMode 处理。

每个判定都经过交叉校验，与日志里的工具调用比对，因此结论只建立在能对上号的那次调用上。

日志与证据

• 插件解析 DSH 内部包时先取运行中的应用自带那份（app.asar/dsh），再退到 profile，这样升级应用后 仍用应用自带的那份。实际命中的解析根记在 assembler-resolved 日志行里。
• 只读探针默认走沙箱内的只读命令（probeRunner: shell），单条约 650–700 ms；probeRunner: inproc 则 留在进程内（只跑 filesystem 类，且只在那个世界可证时）。额度上限：最多 4 条、总预算 3 秒、单条 1.2 秒、 输出 2 KB；单条另有自己的硬截止，因此一条慢探针吃不下整次评审。每个阶段都有插件自持的截止与调用方的 取消；拿不到沙箱 shell 时报"探针不可用"，不回退到宿主自己的进程内通道。
• 评审日志：$DSH_HOME/escalation-review.log，每行一个 JSON 对象；tools/review-report.mjs 会把它与 会话上下文（按 callId 关联）渲染成 Markdown。主要事件：ready、intervention-gate、 config-effective、assembler-resolved、reviewed、reviewer-failed、review-attempt（这次尝试实际拿到的超时）、 review-retry、review-retry-skipped、approval-granted、action-changed、circuit-breaker、projection-registered。 reviewed 带 actionFingerprint（被评审参数的 16 位十六进制哈希 —— 绝不是参数本身）， action-changed 记下"放行被复核拦下"时的新旧哈希。selftest-summary 只在配置了自测模块时出现： 本包不含自测用例，所以开着 selfTest 但没给 selftestModule 时日志只记 selftest-unavailable， 评审不受影响。

审核卡片

越界调用会在对话里出现一张审核卡片，显示状态与理由，点击可展开细节。状态只反映宿主能证明的那部分事实：

状态	何时
审批中	插件正在决定，且宿主表明会自动代答。
评审中	mode: observe —— 只评审记录，永不代答。
待审批	宿主表明不会自动代答（denyMode: ask、熔断已触发），或插件把这次调用交回人工。
越界提权请求	形状是越界、但接管尚未确认 —— 中性状态，不是断言。
已放行 / 已拒绝	实际生效的判定。
已取消 / 审批不可用	宿主取消了这次调用，或插件无法回答它。
已执行（工具报错）	放行之后工具自己失败了。人工拒绝绝不会被它改写成这个状态。

状态颜色取自官方主题 token。拿到过本次调用判定条目的卡片不会中途消失；纯推测的卡片会在宿主报告 "开关关着"或"这次不是越界"时撤掉。

卡片读取的宿主事实有两个来源：会话投影，以及一条按会话+调用限定、走认证边界的 Connection Fetch 实时通道 —— 投影只在会话事件提交时重算，而评审在飞行中不产生任何事件，所以评审期间的相位由实时通道带过来。

已知限制：放行的理由靠内存交付（投影 + 上述实时通道），因为审批结论本身没有理由字段。会话重新加载后， 旧调用的状态还在，但那条理由会丢；新发生的评审不受影响。

全部通过有文档的扩展点工作：tools/pre-execute、approval/request、sessionProjections、 Connection Fetch 注册表、conversation.chat.node、configForms。

许可

MIT，见 LICENSE。第三方来源与逐字重合度的实测记录见 NOTICE.md。