审批风险解读 marksimZ/dsh-approval-guide

dsh-approval-guide

一个 DeepSeek Harness 插件，用大白话解释待处理的审批请求——不碰原生审批界面。

composer area
┌───────────────────────────────────────────────────────────────┐
│ ⚠ 高风险 递归或强制删除文件 · 工作区 [详情] │ ← this plugin ├───────────────────────────────────────────────────────────────┤ │ … the native approval card (command, Allow, Deny) stays … │ ← untouched └───────────────────────────────────────────────────────────────┘

展开这一行，会多出 判定依据（命令 / 路径）、影响范围（工作区 / 工作区之外 / 系统目录 / 网络）、建议，以及智能体自己给出的 原始原因。它从不提供 Allow/Deny：决定权留在该留的地方。

为什么不放进审批卡片里

conversation.approval.detail 是唯一的席位，带 replaceRisk: "shadows-shipped-ui"；当前占用它的是内置的 ApprovalCommand。注册进去会替换原生卡片（连同按钮），而不是在它旁边追加。所以这个插件渲染到 conversation.input.dock，把原生卡片当作只读。

怎么分类

一张保守的词法表——从不猜测语义，匹配不上的一律是 无法判断风险，请人工确认，绝不判成「安全」。

| 级别 | 信号（示例） | 含义 |
| 高风险 | rm -rf、git clean -fdx、git reset --hard、git push --force、mkfs/dd、sudo、shutdown、taskkill /f、curl … \| sh、Drop Table、npm publish、docker system prune、chmod -R/777、改系统注册表 | 不可逆、提权或远程执行 |
| 注意 | 安装包、git commit/push、docker run/build、下载、mv/cp、sed -i、写文件类工具 | 改动文件、依赖或 Git 历史 |
| 只读 | ls、cat、grep、git status、node -v、read/glob/grep 工具 | 只做查看 |
| 无法判断 | 匹配不上的任何东西 | 问人——绝不假设安全 |

额外规则：

- 范围：路径或命令碰到系统位置，或工作区之外的绝对路径，升级为高风险，并标注 工作区之外 / 系统目录；
- 网络：web_fetch / web_search / curl / wget 标上 网络 范围；
- 写文件类工具（write、edit、str_replace_editor 等）在工作区内算中风险，在工作区外算高风险；
- 脱敏摘要：文件内容、补丁和提示词在 Host 上过线之前，先替换成 <N chars>；预览长度受 previewChars 限制。

这张表放在 src/client.js 里，叫 HIGH_RULES / MEDIUM_RULES / LOW_RULES；加一条规则就是加一个对象。scripts/client-spec.mjs 把整张表和「未知仍是未知」这条规则钉死。

环境要求

- 一个组装了 webServer 和 sessionProjections 的 DSH 客户端（Desktop 客户端和 dsh web）。
- 只有测试/安装脚本需要 Node 20+；插件没有构建步骤。

安装

sh
git clone https://github.com/marksimZ/dsh-approval-guide.git dsh-approval-guide
dsh web --patch /absolute/path/to/dsh-approval-guide/cordis.patch.yml

or permanently:

node scripts/install.mjs --dry-run
node scripts/install.mjs
node scripts/verify-deployed.mjs --url http://127.0.0.1:<GUI 端口>

配置

| 键 | 默认值 | 含义 |
| widgets.explainer | true | 注册说明行 |
| minLevel | medium | 显示的最低级别：high / medium / low（unknown 始终显示） |
| showLow | false | 同时显示只读审批 |
| previewChars | 400 | 脱敏后参数预览的最大字符数 |
| extraHighRisk | [] | 额外的高风险正则表达式（比如你自己定义的危险命令） |

架构 text Host half (src/index.ts)
ctx.on('session/event') → tool/call cache, approval/asked, approval/decided
ctx.sessionProjections.stateOf('workingDirectory') → scope for the digest
GET /dsh-approval-guide/pending?session=… → pending list with sanitized digests globalThis.__DSH_APPROVAL_GUIDE_CONFIG__ → display switches + custom rules

Browser half (src/client.js)
conversation.input.dock → poll pending, classify, render one explanation line

为什么需要 Host half？ 审批载荷和关联的工具调用参数都在 Host 的会话日志里，浏览器只收到摘要。分类逻辑本身是纯函数，跑在浏览器里，所以这份代码随组件一起分发。

测试 sh
npm test # classifier spec + bundle smoke + theme tokens + visual tokens
npm run test:host # approval lifecycle over the real pending route
npm run verify # read-only probe of a running GUI

| 脚本 | 锁定内容 |
| scripts/client-spec.mjs | 每个规则族、工具名映射、作用域升级、unknown 默认值、显示阈值、最差待审批项的选择 |
| scripts/client-smoke.mjs | 打包契约、dock 注册、说明开关 |
| scripts/host-smoke.mjs | 待审批生命周期、摘要提取、载荷脱敏、调用晚到时刷新摘要、路由边界 |
| scripts/theme-tokens.mjs | 每个 var(--dsw-*) 都由随包主题声明 |
| scripts/visual-tokens.mjs | 不使用原始颜色，圆角与字号取自主题刻度，不使用无限动画 |
| scripts/verify-deployed.mjs | 运行中的 GUI 能提供打包文件和待审批路由 |

限制

- 只看字面，不看语义。 混淆过的命令（base64 -d | sh、生成的脚本）会落到 无法判断；这是有意为之的保守行为。
- 只看审批点名的内容。 风险根据被批准的工具调用来判断，不看它背后的整体计划。
- 按设计不提供决策按钮。 允许/拒绝由原生卡片负责，这个插件只做解释。
- 插件加载后才开始解释。 如果 Host half 加载前已有审批在等待 mounted 没有缓存的工具调用，所以这一行可能显示 无法匹配已知规则，直到看到该调用为止。

许可证

MIT — 见 LICENSE。