Letter2025/dsh-approval-llm

面向 DeepSeek Harness 的模型审批插件（approve-for-me）。

English | 中文

一个社区插件：为 DeepSeek Harness 增加一个**"帮我批准"权限模式**。在该模式下，approval/request 的审批请求由独立的评审模型代替人工判定——评审模型给出 ALLOW / DENY / ESCALATE，只有拿不准或模型故障时才转人工。在其他任何权限模式下插件保持沉默，模型审批永远不会抢在人工审批前面。

它对应 Codex 的 approvals_reviewer=auto_review（--approve-for-me），并遵循 AGENTSCOPE-PLAN-058 / 062 / 063 的评审设计（正交的 reviewer 维度、三值决策、路由策略、Prompt 隔离、fail-to-human、熔断）。

警告：AI 评审是一种策略选择，不是安全保证。它可能被工具输出或 agent 自身理由中的提示注入欺骗。建议用于低风险工作流；务必收紧 humanOnlyList、denyList 和熔断参数。

设计对照

本插件概念	Codex	AGENTSCOPE-PLAN-058
专门的权限模式激活评审模型	approvals_reviewer: auto_review + --approve-for-me	UI 档位 帮我批准 = DEFAULT + ApprovalReviewer=MODEL
该模式之外全部委托	人工审批不变	请求批准 = DEFAULT + HUMAN
应答 approval/request 瀑布	approvals_reviewer: auto_review	ApprovalReviewer = MODEL（与权限模式正交）
模型调用前的确定性路由	"确定性沙箱/网络 allowlist 在 guardian 评审之前执行"	SAFE_ALLOW / DENY / HUMAN_ONLY 路由策略
评审模型判定 ALLOW / DENY / ESCALATE	Guardian 子代理（Approved / Denied / TimedOut / Abort）	ALLOW / DENY / ESCALATE
评审模型持有隔离的安全策略	Guardian prompt 与主 agent 隔离	§4.5 Prompt 隔离
评审时动态注入工具描述	—	§4.5 工具描述动态注入
从会话日志取回工具参数	信任分层（评审参数而非只看工具名）	§4.4 参数级风险
模型故障 → 转人工，不计熔断	fail-closed guardian	§4.8 fail-to-human 与策略拒绝分离
连续 DENY 达阈值 → 转人工	熔断（连续 3 次）	§4.14 熔断
显式 provider/model，否则回退会话路由	—	PLAN-062 每 agent 配置 + 回退
决策以用户可见消息写入会话	UI 上的 guardian 徽标	DENY 事件推送到前端（§4.17.5）

工作方式

approval/request（瀑布）
   │
   ├─ enabled=false？ ────────────────────────────► next()（原样委托）
   │
   ├─ 模式门：会话 preset ≠ modePreset ───────────► next()（人工审批不变）
   │    （默认 modePreset = model-approval）
   │
   ├─ RoutingPolicy（确定性，无模型调用）
   │    ├─ 命中 denyList ─────────────────────────► 'rejected'
   │    ├─ 命中 allowlist ────────────────────────► 'allowed-once'
   │    ├─ 命中 humanOnlyList ────────────────────► next()（人工决定）
   │    └─ 其余：REVIEW
   │
   ├─ 熔断：连续 DENY ≥ max ──────────────────────► next()（人工接管）
   │
   ├─ 评审模型（隔离的安全策略 prompt）
   │    输入：工具名 + 描述（ctx.tools）
   │         + reason + 工具参数（来自会话日志 tool/call）
   │    判定：ALLOW ──────────────────────────────► 'allowed-once'（计数归零）
   │           DENY ──────────────────────────────► 'rejected'（计数 +1）
   │           ESCALATE ──────────────────────────► next()
   │           超时 / 解析失败 / 模型故障 ─────────► next()（fail-to-human）
   │
   └─ ALLOW / DENY 还会往会话追加一条用户可见的决策消息，
      主链路因此记录"为什么通过/拒绝"。

• ALLOW / DENY / ESCALATE 与 dsh 结果词汇一一对应（allowed-once / rejected / 委托）。ESCALATE 和模型故障永远不会伪造拒绝——它们把请求交给下一个 answerer（人工 UI）；没有人工 answerer 的部署按 fail-closed 解析为 unavailable，调用方视为拒绝，与 Codex 的 fail-closed guardian 一致。
• 模式门保证各模式互斥。在 帮我批准 预设下评审模型应答；在 请求批准（及其他预设）下插件全部委托，人工审批行为与装插件前完全一致。两个预设共享 sandbox/approval 旋钮，靠记录的 permission/preset 选择区分。
• 一个部署一个 terminal answerer。dsh 审批链不是多个裁判的优先级列表——只组合一个 answerer。要保留人工兜底，就把人工 UI answerer 放在本插件之后（瀑布的 next() 会到达它）。
• 参数从会话日志读取，而非审批请求本身（审批请求刻意不带参数，避免渲染出第二份可能漂移的副本）。

配置

所有字段都由 Loader schema 校验，省略时取默认值。

字段	默认值	含义
enabled	true	总开关；false 时所有请求原样委托。
modePreset	model-approval	激活评审模型的权限预设名。设置后，只有当会话的有效预设等于该值时插件才应答；其他会话全部委托给人工通道。设为 '' 则审查所有请求。
provider / model	未设置	显式评审路由。必须成对出现；未设置时复用会话日志中最后一次 request/header 的对话路由，日志中没有则 fail-to-human。
timeoutMs	60000	评审请求端到端超时；超时后转人工（TIMEOUT，不计熔断）。
maxOutputTokens	256	评审输出上限。
systemPrompt	内置策略	评审模型的自定义安全策略。内置策略是"默认放行、关键危害才拒绝"的短规则集，见 src/reviewer.ts。
allowlist	[]	免模型调用直接放行的工具名（SAFE_ALLOW）。
denyList	[]	免模型调用直接拒绝的工具名。优先于 allowlist。
humanOnlyList	[]	必须人工决定的工具名；绝不自动评审。
maxConsecutiveDenials	3	每会话连续 DENY 阈值，达到后评审模型转人工；0 关闭熔断。ALLOW 会重置计数。
maxArgsChars	4000	渲染给评审模型的工具参数 JSON 上限。
includeArgs	true	是否从会话日志取回工具参数参与评审。
notifyUser	true	每次模型 ALLOW/DENY 后往会话追加一条用户可见的决策消息（✅ 模型审批通过 / ❌ 模型审批拒绝，含风险与理由），主链路可复查。

示例覆盖层（profile 的 cordis.patch.yml）：

- id: approval-llm
  config:
    provider: deepseek-official
    model: deepseek-v4-flash
    allowlist: [read, read_image, glob, grep]
    humanOnlyList: [delete, terminal_send]
    denyList: [job_kill]
    maxConsecutiveDenials: 3

安装

复制给 AI 的一句话——把这一句话交给任意 AI 编程 agent，让它帮你完成安装："请阅读 https://github.com/Letter2025/dsh-approval-llm/blob/main/README.md 并遵循其『## 安装』章节，把 dsh-approval-llm bundle 安装进 DeepSeek Harness 的 web profile，然后重启 dsh web 服务，并确认权限选择器里出现带盾牌+星芒图标的 model-approval（帮我批准）预设。"

作为可安装 bundle（推荐）

本包在 package.json 中声明了 dsh.bundle.patch，安装后会激活一个配置层：既插入插件行，也往 permission 权限表添加 model-approval（"帮我批准"）预设——无需再手动配置预设：

dsh plugin --profile web add dsh-approval-llm   # 从 npm 安装已发布的包

重启 dsh web，然后在权限选择器（输入栏的 Access chip，带盾牌+星芒图标）里选 帮我批准，即可把该会话的审批人切换为模型。预设表是进程级的，修改预设需要重启 dsh。

In-box bundle 的行名从 dsh 安装本身解析；@deepseek-ai/* 导入是 peerDependencies，由宿主 dsh 提供，所以请锁定 dsh 版本（项目处于开发者预览，有破坏性变更）。想从本地检出安装：先 pnpm run build，再在父目录执行 dsh plugin --profile web add ./dsh-approval-llm。

随包技能：引导配置评审模型

本包随附一个 bundled 技能（configure-approval-llm，source bundled），安装插件后技能自动进入目录。让任意 agent「配置审批评审模型」，或直接加载该技能——它遵循 AI 先配置、用户确认 的流程：先探测当前模型与 provider 设置，把 approval-llm 覆盖行写入 ~/.dsh/profiles/web/cordis.patch.yml，再贴出完整配置等你确认后才重启生效。指南覆盖评审模型选型（同 provider 优先、contextWindow ≥ 主模型），以及按部署收紧 allowlist / denyList / humanOnlyList / maxConsecutiveDenials。

源码覆盖层（开发用）

- insert:
    - id: approval-llm
      name: './src/index.ts'        # 本包入口的路径，或绝对路径
      config:
        provider: deepseek-official
        model: deepseek-v4-flash

用 dsh web --patch ./cordis.patch.yml 运行，或把该行并入 profile 的 cordis.patch.yml。源码覆盖层只插入插件行，不含预设——要么同时安装上面的 bundle 层，要么自己往 permission 行里加 model-approval 预设（patch 会替换整行 config，所以要写全所有预设）：

- id: permission
  config:
    presets:
      read-only:
        sandbox: read-only
        approval: ask
        name: 只读
      workspace-write:
        sandbox: workspace-write
        approval: ask
        name: 请求批准
      model-approval:
        sandbox: workspace-write
        approval: ask
        name: 帮我批准
        description: 审批由独立的评审模型决定；拿不准或模型故障时转人工。
      danger-full-access:
        sandbox: danger-full-access
        approval: never
        name: 完全放开

构建与测试

插件位于 DeepSeek Harness 检出内部的 custom_plugin/dsh-approval-llm；@deepseek-ai/* 解析到该检出自己的 node_modules（构建产物 lib 声明 + @types），因此请在仓库根目录保持 harness 已构建（pnpm run build）。指向 harness node_modules 的 junction 由检出提供。

pnpm run typecheck   # tsc --noEmit（严格模式）
pnpm run test        # vitest：39 个单元测试，无网络
pnpm run build       # tsc 产出 lib/（ESM，相对导入重写）

路线图

• 客户端徽标与开关：给本包加浏览器半（dsh.client），可以在工具卡片上渲染评审模型的决策徽标（盾牌图标），并提供写回 enabled/modePreset 的设置行（写入热重载的设置命名空间）。宿主 loader 已经从同一行发现 dsh.client 包，安装路径不变。
• 批量评审（PLAN-063）：一次评审多个待审批工具，需要 approval 服务先支持批量入口。
• 通配符 / 参数模式路由：确定性策略支持按工具名/参数模式匹配。

安全模型

• 模式门保证人工审批不变：在配置的预设之外插件全部委托，请求批准 的行为与装插件前完全一致。
• Prompt 隔离：评审 prompt 由本插件依据自身配置组装，主 agent 永远看不到安全策略，无法针对评审定制请求。工具描述取自实时注册表（ctx.tools.schemas()），参数取自持久化日志——评审模型评判的是真实调用，而不是 agent 的自述。
• fail-to-human：TIMEOUT、PARSE_ERROR 和 provider 错误产生 ESCALATE（委托），绝不伪造拒绝，且不计入熔断（PLAN-058 §4.8 模型故障与策略拒绝分离）。
• 组合即 fail-closed：没有人工 answerer 的部署解析为 unavailable，调用方按拒绝处理。
• 熔断：单会话连续 DENY 达到 maxConsecutiveDenials 后，该会话后续请求转人工——评审模型持续拒绝时就不再当裁判。
• 敏感数据：评审输入（工具参数、reason）仅用于评审请求和结构化日志，除常规会话日志与控制台输出外不额外落盘。参数敏感时可关闭 includeArgs。

已知限制

• 没有专门的机器可读审计事件。模型决策以 user/message 通知的形式出现在主链路（可持久化、可重放），内置的 approval/asked + approval/decided 审计对记录请求与结果。专门的机器可读审计事件（如携带完整评审上下文的 session/approval-llm-request）仍受 harness 对仓库外事件类型的持久化策略限制；等 harness 开放注册通道后应补充。
• 暂无客户端徽标。决策通知以对话消息呈现；Codex 式锚定在工具卡片上的盾牌图标需要客户端插件（本包暂未提供浏览器半）。见路线图。
• 一次请求一次模型调用。PLAN-063 的批量评审需要 approval 服务先支持批量入口；单请求延迟受 timeoutMs 和评审模型选择约束。
• AI 评审的信任是部署决策。评审模型可能被工具输出提示注入。请配置好 humanOnlyList、denyList 和熔断；不要在高风险无人值守工作流中启用。
• 仅精确名称路由。列表匹配完整工具名，不支持通配符或参数模式匹配。

许可证

MIT