@quill507/dsh-auto-approval-llm
为 DeepSeek Harness 的 Auto 权限档提供 LLM 辅助自动审批 + 超时自动兜底
常规操作静态放行 · 危险与模糊操作走 LLM 评审 + 人工倒计时 · 默认 fail-closed
Auto 档（machine value auto-approval；host 显示名 Auto approval；中文客户端显示 自动审批）= sandbox: danger-full-access + approval: ask。本插件在本档会话里充当 approval/request 的唯一终结裁决者：常规操作经静态规则直接放行，危险/模糊操作走「静态规则 → LLM 分类 → LLM/人工裁决 → 倒计时兜底 → 熔断」，全程保留人工与审计兜底。宿主 >= 0.1.6 的 auto 归上游 @deepseek-ai/dsh-experimental-auto-review（Auto review / EXP），本插件只接管 auto-approval 档、上游只接管 auto 档（按 derived preset 判档），两者作用于不同档位、可同时启用。
特性
- 静态规则 + LLM 分类器 —— 只读/会话/工作区常规操作直接放行；危险、外部写、凭据外泄、受保护路径直接拒绝；模糊操作交 LLM 预分类。
- 写向量完整性加固 —— 含真实文件写重定向的命令段脱离只读快径；POSIX
tee/dd of=/sed -i/truncate/install以操作数目标参与按目标闸门；直写插件运行态文件无条件硬拒。 - 12 分类三态开关 + 信任目录双模式 —— 每类可配
auto/ask/deny，默认全部inherit（HARD_LOCKED 的 delete / disk 除外——未配置也恒被接管为ask倒计时）；delete / disk / privilege / protected 四类保持锁定，trustedDirs与categoryMode控制「常规位置」范围（分层细节见 docs/17）。→ docs/17 - 双通道模型来源 —— 快速判断与深度评审各可独立选择：跟随会话模型（默认）/ DSH 已配置模型 / 自定义端点。端点密钥存 DSH 凭据存储，前端只显示「已配置」、永不回显。
- 分级倒计时 + 超时兜底 + LLM 接管 —— 低/中/高三档倒计时（默认 5 / 8 / 10 秒）；超时按
timeoutAction（拒绝 / 通过 / 低风险自动同意）结算；中风险下 LLM 在窗口内给出明确结论即接管。关浏览器也不悬挂（host 计时器独裁）。 - 熔断与循环防护 —— 连续/累计被 LLM 拒绝达阈值则转人工（
/approval-reset重置）；循环防护（默认关）把「被自动放行面连续放行的同一调用」转为钉死拒绝倒计时。 - 声明式规则
rulesText——工具(正则) | allow|deny|human [| 字段]，支持[agent:…]/[workspace:…]维度限定；解析出错时整段失效（设置卡有警示）。 - 确认制学习（默认关）—— 同一签名被人工反复确认达阈值后自动放行，每次放行前仍过一次标准在线评审；条目可查看与吊销。→ docs/18
- 可审计、可观测 ——
history.jsonl+ append-onlyaudit.jsonl；LLM 评审真实耗时统计；瞬时网关故障自动重试一次（认证类错误不重发凭据）。
工作方式
flowchart TD
A["模型发起工具调用"] --> B["② tools.guard：同步硬拒闸门凭据 / 受保护路径 / shell 熔断 / symlink 逃逸"]
B -->|"命中"| X["拒绝结案"]
B -->|"通过"| C["③ tools/pre-execute：静态评估 + 类别收紧"]
C -->|"deny"| X
C -->|"allow"| Y["放行执行"]
C -->|"ask"| D{"LLM 预分类器快径"}
D -->|"allow"| Y
D -->|"deny"| X
D -->|"不确定"| E["④ approval/request：唯一终结裁决规则 → 名单 → 类别 → 评审模式 → 熔断 → 学习 → 风险分档"]
E -->|"LOW / LLM 接管"| Y
E -->|"MEDIUM / HIGH"| G["人工面板 + 倒计时LLM 复审并行，超时按 timeoutAction"]
G -->|"允许一次"| Y
G -->|"拒绝 / 超时"| X
Y --> H["⑥ tools/post-execute：结果与拒绝理由回灌模型"]
X --> H
- LOW：不送评审则静默放行；送评审时按结论裁决；ESCALATE 转人工。
- MEDIUM：面板 + 倒计时并行跑 LLM；
llmTakeoverScope覆盖且结论明确 → 立即跟随。 - HIGH：面板 + 倒计时，LLM 只给建议；超时严格按
timeoutAction。 - 超时标记的唯一作者是 host 计时器，客户端只上报 outcome，伪造不了。
> 完整五段钩子时序（含 ⑤ 产物登记、⑦ 通知投递）见 docs/02 · 一次工具调用的完整生命周期；两层静态面经宿主 tools/pre-execute 瀑布征询生效，对端监听的短路形态见 docs/09 · 可达性前提。
安装
前置：会话/预设处于 Auto 档（machine value auto-approval = danger-full-access + approval: ask，用 /permission auto-approval 切换）；DSH 0.2.0-rc.2 或 0.2.1-alpha.1；Node ^22.19.0 || >=24.0.0。
兼容窗口：auto 是上游 @deepseek-ai/dsh-experimental-auto-review（Auto review / EXP）的保留名，本插件只定义/接管 auto-approval，两者分档并存、可同时启用。宿主承诺每个 tuple 一条线：0.2.0-rc.2 与 0.2.1-alpha.1 均为完整支持（peer 区间 >=0.2.0-rc.2 <2 || >=0.2.1-alpha.1 <2）。长期规则：宿主线跟着用户实际在跑的宿主走，上游进入新 tuple 的 alpha 时再逐条追加（HOST_LINES 同步加行）。peer 区间是安装准入面——区间内未测的线不受支持，上界 <2 只是范围上界；承诺线跨两个 tuple，因此区间按 tuple 分臂，每条承诺线由承载它自己 tuple 的那一臂放行——不依赖宿主门禁的 includePrerelease 标志。0.1.7-rc.2 已退出承诺面，随区间抬升一并被拒装。旧机器值 auto 别名与 legacy/unknown 能力分支已随下限抬升移除（shipped patch 只定义 auto-approval）。
上游提示：0.2.0-rc.1 起未发布破坏性变更清单、未发弃用通知、其 AGENTS.md 与 0.1.7-rc.2 是同一个 git blob（37cfd8d2…），即「未稳定、消费者需自行跟进」的立场未变。社区同时报告该次升级后 13 个第三方插件中有 6 个报错徽标、无维护者回复。上述与本插件的契约面结论不冲突：本插件只测自己实际使用的 50 个符号（48/50 不变、0 删除/改名/移位，唯一新增是 dsh-session 的 ToolCallRecovery），而非一个插件可能触及的全部面；且本插件的探针能发现符号的消失或改名，发现不了符号含义的改变。
dsh plugin --profile web add @quill507/dsh-auto-approval-llm
- 安装后重启 dsh，host 侧才生效。
- 只作用于 Auto 档（其他权限档不介入）；切换用
/permission auto-approval。本插件是auto-approval档approval/request的唯一终结者 —— 同一档位不要再叠加第二个审批裁决者；上游@deepseek-ai/dsh-experimental-auto-review的auto（Auto review / EXP）是另一个档位，两者可同时启用。 - 平台：Windows + Git Bash 为主开发/测试基线；macOS / Linux / WSL 代码已适配但无真实用户验证；Android 原生环境不支持。→ docs/19
- 反馈：到 GitHub Issues 报告，注明平台、dsh 版本、插件版本、复现命令与预期行为。
- 本地开发：
npx tsc -p tsconfig.json+npx tsdown，以link:加载（host 改动需重启，client 改动自动热载）。→ docs/14
从旧 auto 档升级
- 同签名门槛：所有宿主只迁移
raw preset = auto且sandbox = danger-full-access且approval = ask的存量会话；其它auto签名（含danger-full-access + never）一律不迁移并告警。 - modern host 的主体变化：宿主
>= 0.1.6上若上游 auto-review 层持有同一签名的auto，该会话同样会被改写成auto-approval——沙箱/审批旋钮不变，但应答主体从上游换成本插件（上游不再接管该档）。这是同签名 rescue 语义的一部分，不是旋钮放宽。 - 迁移时机：归档会话不处理，只在 resume 进入 live 时懒迁移（
session/createdprepend）；插件加载时对已 live 会话做一次启动扫描，agent/created兜底。迁移只重写 durable raw identity（permission/preset），不写旋钮、不调用permissionPresets.set()。 - 自有档 spec enforcement：
auto-approval会话的 effective-never（approval: never，或approval: null+ base policynever）由插件写回ask（preset-spec-restore审计）；不会再翻转上游auto。 - fail-closed：宿主
>= 0.1.6且未装上游 auto-review、且该存量会话在permissionPresets服务构造期已 live（插件来不及先迁移）时，宿主 pin 会先于插件拒绝该会话——会话打不开，不是静默放行。处置：停 dsh → 用可选离线迁移工具或手工导出/导入 → 再启动；也可在 profile 保留上游 auto-review 层。该 boot 期缺口在插件侧无法自动修复。 - 官方权限选择器的风险确认只覆盖宿主内置的
danger-full-access；自定义auto-approval档由插件客户端自行弹确认。
快速开始
- 把会话/预设切到 Auto 档：
/permission auto-approval。 - 打开侧边栏 插件 → auto-approval-llm，在该插件的行列表里点「配置 <行名>」打开行配置页，确认设置表单出现（宿主未交出该命名空间的配置表单时，该页只读展示当前生效值）。默认配置即可工作（常规操作静态放行；模糊操作走会话模型评审；超时按
timeoutAction兜底，默认拒绝）。 - 想让审批走指定模型：在「在线评审模型」卡把通道来源设为「DSH 模型」并从列表选，或选「自定义端点」填协议 / 地址 / 模型 / 密钥 → 保存 → 测试连接。
- 嫌弹窗频繁：调大「中风险倒计时」，或把「超时动作」改为
拒绝/低风险自动同意。
> 会话命令（默认不注册）：/approval-mode 查看当前会话模式、/approval-mode manual|smart|unattended 设置、/approval-reset 与 /approval-reset-all 重置熔断 —— 需在设置卡开启 slashCommandsEnabled 并重启。
界面预览
其余界面的结构说明（计时器与熔断 / 安全规则列表 / 分类开关与信任模式 / 确认制学习 / 在线评审模型 / 权限预设）见 docs/10 · 客户端 UI。
配置项
下表只列常用键；全部键、完整语义与裁决例外见 docs/12 · 配置全景。
| 键 | 默认 | 说明 |
|---|---|---|
enabled |
true | answerer 总开关：关=本插件不再终结 approval/request（静态硬拒与 guard 仍生效） |
timeoutAction |
reject |
超时动作：拒绝 / 通过 / 仅低风险放行（删除与磁盘恒拒，不受此键影响） |
llmReviewScope |
low-or-above |
哪些风险档送 LLM 复审 |
llmTakeoverScope |
medium-or-below |
哪些档允许 LLM 结论直接接管 |
lowRiskSeconds / mediumRiskSeconds / highRiskSeconds |
5 / 8 / 10 | 三档倒计时（秒） |
defaultReviewMode |
smart |
每会话评审模式：manual / smart / unattended |
maxConsecutiveDenials / maxTotalDenials |
3 / 20 | 熔断阈值（0 关闭） |
loopDetectionThreshold |
0 | 循环防护阈值（0 = 关；仅 YAML 可配） |
rulesText |
'' | 声明式规则（支持 [agent:…] / [workspace:…]） |
allowlist / denyList / humanOnlyList |
[] | 工具名精确匹配名单 |
classifierSource / reviewerSource |
session |
两通道模型来源：session / preset / endpoint |
endpointUrl / endpointModel / endpointProtocol |
'' / '' / openai |
共享自定义端点 |
categoryPolicy / categoryMode / trustedDirs |
{} / standard / [] |
分类三态、位置模式与信任目录 |
privilegeAutoReview / protectedAutoReview |
false | 分别解锁 privilege / protected（差别见 docs/17） |
learningEnabled / learningThreshold |
false / 3 | 确认制学习开关与阈值（2–10） |
slashCommandsEnabled / directHumanEnabled |
false | 注册 /approval-* 命令 / 直接人工通道（agent 可把操作路由给人；均需重启生效） |
debug / redactResults / notifyUser |
false / false / true | 调试日志 / 结果脱敏 / 通过通知进会话 |
> 设置卡为可折叠子卡 + 顶层开关即时保存，非法配置值有红色横幅 +「尝试修复」→ docs/10。host-only 键（workspaceRoot、trustedDshSubpaths、maintenanceDshPaths、rulesDryRun、breakerAntiHijackMs、reviewMaxRetries 等）用 patch / YAML 配置，设置卡保存不会抹掉；「高级」子卡把它们连同当前生效值列为只读清单（无控件），并说明 DSH_HOME 写入的操作者开口与没有开口的族。
数据文件
规范位置：/auto-approval-llm/（刻意放在插件包目录之外 —— npm 升级会替换整个包目录）。
| 文件 | 语义 |
|---|---|
history.jsonl |
审批历史（内存窗口 200 条 + 落盘，>1MB 轮转） |
audit.jsonl |
append-only 审计：decision + clear 墓碑 + 非决策观测事件 |
review-mode.json |
每会话评审模式快照 |
llm-latency.jsonl |
LLM 真实响应耗时统计（最近 100 次，>1MB 轮转） |
approval-debug.jsonl |
仅调试模式开启时写入的评审/审批时序 |
learning.json |
学习条目（SHA-256 签名键 + 脱敏骨架；TTL 30 天，按工作区隔离） |
目录不可写时 fail-closed：审计闸拒绝全部裁决并打印一次性告警，不回退、不迁移。查询 node scripts/audit-query.mjs；只读摩擦报告 node scripts/friction-report.mjs。→ docs/11
安全模型摘要
- 唯一终结者：命中本插件档（
auto-approval）的 approval 由本插件终结（prepend + global），不双弹窗、不双写；上游 auto-review 的auto档与本档互不接管，可并存。 - fail-closed：评审超时 / 垃圾 / 失败 → 拒绝或转人；ESCALATE 一律转人，不被
timeoutAction=allow自动放行。 - reasoning-blind：评审只看工具名 + 结构化脱敏参数 + 有界直接用户消息（唯一授权证据）+ 工作区事实。
- 密钥不出 host：在线评审密钥存 DSH 凭据，每操作解析，前端仅显「已配置」。
- 审计不可手改：append-only，清空留 tombstone；
tools/guard的硬拒也先落审计再拒绝（审计失败不软化拒绝）。 - 超时标记唯一作者是 host 计时器，客户端只上报 outcome，伪造不了。
已知局限
- 对端插件短路时，静态两层与 guard 均不被征询：另一插件若在
tools/pre-execute瀑布先行返回非决策对象且不带reason，宿主直接派发执行 —— 这是插件侧无法启动期自检的形态。→ docs/09 - 循环防护不是安全边界：只防「卡死空转」，微调参数即可绕过。
rulesText解析出错 = 整段失效（fail-open 方向）；设置卡有警示但不阻断保存。protectedAutoReview开启且类别未显式配置时，受保护询问为无倒计时人工询问、永不自动结算 —— 无人值守会一直等。- 凭据物质不受解锁开关影响：
.env/.npmrc这类读取即便开启protectedAutoReview仍保持锁定（方向偏严，可能误拒）。 - opaque 行（含
(/{/$(/ heredoc 的复合命令）在类别层归为unknown：既不被解锁、也不进凭据读取地板，即不额外收紧也不额外放宽。 - 非 Windows 平台未经真实用户验证。
致谢
- 代码衍生：@nanmicoder/dsh-auto-mode（MIT License）—— 核心审批管线移植自该项目并在
src/auto/重写为独立实现；MIT 版权与许可声明随源文件及编译产物lib/auto/*.js、lib/client.js保留。 - 设计范式参考：@anionex/dsh-vision-toolkit。
- 机制对标：@moon09300731/dsh-approval-gate（确认制学习）、@a903067276-rgb/dsh-perm-guard（分类三态 + 信任目录）、@PerryLink/dsh-permission-rules（规则维度限定）。
- 贡献者：@daveycodez、@MikotoMyWife。
许可
BSD-3-Clause ｜ LICENSE
