前言¶
在 DeepSeek Harness（DSH）里，智能体每次调用敏感工具都会走 approval/request 瀑布式审批。开发或日常使用久了，常会遇到两类问题：事后说不清「当时批了什么、风险标成什么、最后成功还是失败」；高危命令若只靠人工点一次「允许」，也容易在忙乱中漏拦。社区里曾有独立的审批台账与桌面提醒插件，分装时还会在监听顺序、风险口径上各自为战。
4478sc/DSH_Monitor（npm 包名 dsh-approval-toast，当前版本 0.7.19）把审批台账与右下角桌面浮窗合并为一个 DSH 插件，维护者为 4478sc，分类属于 admin-security。台账侧记录工具、理由、风险、决策与结果，并可选 gate / auto 模式；浮窗侧在任务完成、失败、提问或等待审批时提示，点击可回到对应会话与待审批卡片。以下按功能、安装、配置与使用注意说明。
这是什么¶
一句话：在 DSH 进程内同时承担「审批观察者 + 可选决策者」和「桌面 Attention Toast」，台账写入 JSONL，宿主具备 webServer 时挂载可导出报告的审计 HTML 面板。
合并来源在 README 中有明确对照：台账能力来自对 feely0208/dsh-approval-ledger 的复刻与演进（代码在 lib/ledger/）；浮窗来自 4478sc/DSH_AttentionPlugins_Desktop（lib/attention/ 等）。合并后 lib/index.js 固定挂载顺序——先浮窗观察者，再台账决策者——避免 gate 模式先拒绝导致浮窗永远看不到「等待审批」事件。
许可证 MIT；依赖 Node >=20，DSH 版本 >=0.1.7 <0.3.0；桌面浮窗宿主支持 Windows（WPF）与 Linux（GTK3）。
审批台账¶
插件在 approval/request 上注册监听器，mode 决定除记录外是否改决策：
| 模式 | 行为 |
|---|---|
ledger（默认） |
只记：时间、会话、工具、调用 id、理由、风险、决策、结果，不改动原有审批链 |
gate |
对 rm -rf、mkfs、dd、curl \| sh、sudo、写 .ssh、danger-full-access 等高危模式直接 rejected，其余交给下游 |
auto |
allowlist 中的工具名直接 allowed-once，其余照旧 |
审批结果枚举为四种：allowed-once、rejected、cancelled、unavailable。风险分级与浮窗「预判风险」共用 lib/ledger 的 classifyRisk；denyPatterns 自定义正则同时作用于台账与浮窗。
默认写入路径：有环境变量 DSH_HOME 时为 $DSH_HOME/approval-ledger/ledger.jsonl，否则为 ~/.dsh/approval-ledger/ledger.jsonl，一行一条 JSON；写失败不阻断审批，读时坏行跳过。
向智能体暴露的查询类工具（名称以 README 为准）：
approval_ledger_query：按工具、风险、决策、结果、时间筛选approval_ledger_stats：总量、高危、拒绝、会话授权自动放行等统计与分布approval_ledger_grants：查看或撤销（action: "revoke"）生效中的会话授权
审计面板在宿主提供 webServer 时自动挂载，否则跳过：
| 路径 | 用途 |
|---|---|
/approval-ledger |
服务端渲染面板（卡片、风险分布、最近 50 条、刷新/导出） |
/approval-ledger/data |
同源 JSON：{ plan, counts, records } |
/approval-ledger/export |
带 content-disposition 的审计报告（deepwhale.approval-ledger/v1） |
桌面浮窗与点击跳转¶
浮窗在 DSH 设置 → Attention Toast 中配置。任务模式含 mainline（当前会话即时、其余汇总）、balanced（逐条）、silent（完成/失败不弹，提问与审批仍弹）；当前会话可见性为 hidden / unfocused / always。等待子智能体时，父会话结束后若仍有 running 子会话，会等整波空闲再弹。审批请求会弹出「等待审批 + 会话标题 + 工具 — 理由 — 预判风险」；用户批准或拒绝后不再弹结果卡。
点击浮窗时：原生宿主先尝试还原并前置 DSH 主窗口（Windows 用 WPF 脚本 lib/attention/toast_host.ps1；Linux 用 GTK3 lib/attention/toast_host.py），再由客户端打开注册表中的会话 id，并定位到 [data-approval-key] 待审批卡片；若已处理则提示「提醒已过期」。Linux 下窗口置前依赖 X11/XWayland 与 xdotool 或 wmctrl；Wayland 原生运行时可能无法置前，但仍会打开正确会话。
若只需台账、不需要桌面进程（无头或无桌面环境），可将 toast.spawn 设为 false。
安装与启用¶
本仓库不发布到 npm，README 要求用 tarball 安装，不要用 link:（会在 profile 里做目录联接，摘掉 profile 前删除会牵连源目录）。
在克隆或下载的仓库根目录执行：
npm install
npm pack
会产出形如 dsh-approval-toast-0.7.19.tgz 的包，然后加入 desktop profile：
dsh plugin --profile desktop add .\dsh-approval-toast-0.7.19.tgz
装完后需重启 DSH：宿主侧（lib/index.js、lib/attention/）不支持热重载；纯客户端 lib/client.js 改动可用 Ctrl+R。
配置要点¶
台账字段定义在 lib/ledger/index.js 的 DEFAULT_CONFIG，通过 DSH 插件配置读取：
| 字段 | 默认 | 说明 |
|---|---|---|
mode |
ledger |
ledger / gate / auto |
allowlist |
[] |
auto 模式直接放行的工具名 |
denyPatterns |
[] |
追加高危正则 |
ledgerDir |
'' |
空则用 $DSH_HOME/approval-ledger |
licenseKey |
'' |
形如 DWH-ENT-XXXX-XXXX 时影响面板导出标记 |
sessionGrants.enabled |
false |
会话内授权记忆 |
sessionGrants.ttlMs |
1800000 |
单次授权有效期 |
sessionGrants.maxUses |
20 |
workspace-write 档自动放行次数上限 |
sessionGrants.dangerMaxUses |
5 |
danger-full-access 档上限（硬顶 5） |
sessionGrants.alwaysAsk |
[] |
永远询问的正则 |
toast.spawn |
true |
false 只跑台账、不起浮窗进程 |
浮窗外观与语言等写在 $DSH_HOME/storages/dsh-approval-toast/config.json（设置页写入）；首次会从旧路径 storages/dsh-attention-toast/config.json 迁移。
会话内授权记忆默认关闭。打开后，同一会话内手动批准过的「工具 + sandbox 模式」组合可在预算内自动 allowed-once；设置页「启用会话授权记忆」同时覆盖 workspace-write 与 danger-full-access 两档。删除类操作（含 rm、git clean、中文「删除」等特征）即使用户仍有 danger 授权额度也会强制回到人工审批。
示例（静态配置片段，与 README 一致）：
sessionGrants:
enabled: true
ttlMs: 1800000
maxUses: 20
dangerMaxUses: 5
alwaysAsk: ['kubectl delete', 'git push --force']
适用场景与注意¶
适合需要在桌面 DSH 上长期跑 agent、既要可审计又要及时看到「等你审批」或任务终态的开发者与小团队。gate 模式适合在仍保留人工终审的前提下，对已知高危命令模式做默认拒绝；ledger 模式适合先全量记账、再按需收紧策略。
安装前建议自行阅读仓库源码与 MIT 许可证。插件以当前 DSH 进程权限运行，台账 JSONL 与导出报告可能包含会话与工具调用摘要，注意磁盘权限与备份。社区目录 SkillHub 上的 DSH_Monitor 页 与 GitHub 仓库相互独立，均非 DeepSeek / 幻方官方应用商店；生态上 DSH 奉行「一切皆插件」，目录站由社区维护。
经过上面的步骤，你可以在一条安装命令里同时获得可查询、可导出的审批台账，以及 optional 的桌面浮窗联动；高危拦截与记账共用同一套风险分类，减少「面板显示 high、账本却是 medium」的错位。
