dsh-auto-approval-llm

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 判档），两者作用于不同档位、可同时启用。

---

特性

1. 静态规则 + LLM 分类器 —— 只读/会话/工作区常规操作直接放行；危险、外部写、凭据外泄、受保护路径直接拒绝；模糊操作交 LLM 预分类。
2. 写向量完整性加固 —— 含真实文件写重定向的命令段脱离只读快径；POSIX tee / dd of= / sed -i / truncate / install 以操作数目标参与按目标闸门；直写插件运行态文件无条件硬拒。
3. 12 分类三态开关 + 信任目录双模式 —— 每类可配 auto / ask / deny，默认全部 inherit（HARD_LOCKED 的 delete / disk 除外——未配置也恒被接管为 ask 倒计时）；delete / disk / privilege / protected 四类保持锁定，trustedDirs 与 categoryMode 控制「常规位置」范围（分层细节见 docs/17）。→ docs/17
4. 双通道模型来源 —— 快速判断与深度评审各可独立选择：跟随会话模型（默认）/ DSH 已配置模型 / 自定义端点。端点密钥存 DSH 凭据存储，前端只显示「已配置」、永不回显。
5. 分级倒计时 + 超时兜底 + LLM 接管 —— 低/中/高三档倒计时（默认 5 / 8 / 10 秒）；超时按 timeoutAction（拒绝 / 通过 / 低风险自动同意）结算；中风险下 LLM 在窗口内给出明确结论即接管。关浏览器也不悬挂（host 计时器独裁）。
6. 熔断与循环防护 —— 连续/累计被 LLM 拒绝达阈值则转人工（/approval-reset 重置）；循环防护（默认关）把「被自动放行面连续放行的同一调用」转为钉死拒绝倒计时。
7. 声明式规则 rulesText —— 工具(正则) | allow|deny|human [| 字段]，支持 [agent:…] / [workspace:…] 维度限定；解析出错时整段失效（设置卡有警示）。
8. 确认制学习（默认关）—— 同一签名被人工反复确认达阈值后自动放行，每次放行前仍过一次标准在线评审；条目可查看与吊销。→ docs/18
9. 可审计、可观测 —— history.jsonl + append-only audit.jsonl；LLM 评审真实耗时统计；瞬时网关故障自动重试一次（认证类错误不重发凭据）。

---

工作方式

flowchart TD
    A["模型发起工具调用"] --> B["② tools.guard：同步硬拒闸门<br/>凭据 / 受保护路径 / 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：唯一终结裁决<br/>规则 → 名单 → 类别 → 评审模式 → 熔断 → 学习 → 风险分档"]
    E -->|"LOW / LLM 接管"| Y
    E -->|"MEDIUM / HIGH"| G["人工面板 + 倒计时<br/>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；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 为完整支持（peer 区间 >=0.2.0-rc.2 <2）。长期规则：宿主线跟着用户实际在跑的宿主走，上游进入新 tuple 的 alpha 时再逐条追加（HOST_LINES 同步加行）。peer 区间是安装准入面——区间内未测的线不受支持，上界 <2 只是范围上界；该区间的下界就是承诺线本身，与它同 tuple，因此单臂即可表达承诺面，不另加第二个比较子。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/created prepend）；插件加载时对已 live 会话做一次启动扫描，agent/created 兜底。迁移只重写 durable raw identity（permission/preset），不写旋钮、不调用 permissionPresets.set()。
• 自有档 spec enforcement：auto-approval 会话的 effective-never（approval: never，或 approval: null + base policy never）由插件写回 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 档由插件客户端自行弹确认。

---

快速开始

1. 把会话/预设切到 Auto 档：/permission auto-approval。
2. 打开侧边栏 插件 → auto-approval-llm，在该插件的行列表里点「配置 <行名>」打开行配置页，确认设置表单出现（宿主未交出该命名空间的配置表单时，该页只读展示当前生效值）。默认配置即可工作（常规操作静态放行；模糊操作走会话模型评审；超时按 timeoutAction 兜底，默认拒绝）。
3. 想让审批走指定模型：在「在线评审模型」卡把通道来源设为「DSH 模型」并从列表选，或选「自定义端点」填协议 / 地址 / 模型 / 密钥 → 保存 → 测试连接。
4. 嫌弹窗频繁：调大「中风险倒计时」，或把「超时动作」改为 拒绝 / 低风险自动同意。

会话命令（默认不注册）：/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、trustedDirs、trustedDshSubpaths、maintenanceDshPaths、rulesDryRun、breakerAntiHijackMs、reviewMaxRetries 等）用 patch / YAML 配置，设置卡保存不会抹掉；「高级」子卡把它们连同当前生效值列为只读清单（无控件），并说明 DSH_HOME 写入的操作者开口与没有开口的族。

---

数据文件

规范位置：<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