beijingwahw/dsh-nuke-plugin

dsh-nuke-plugin

DeepSeek Harness 的工业级 Nuke 环境清理引擎 — 事务回滚 · 崩溃自恢复 · 审计链 · 先知推演 · 混沌演习 · 贝叶斯自学习 · 预测存证问责 · 自我校准 · Thompson 探索

Release
Tests
TypeScript
License: MIT

把"删除插件并清理残留"这件危险的事，做成一套可验证、可撤销、可审计的事务系统。

为什么需要它

dsh 的一切皆插件 —— 但插件的装卸会在 .dsh/、Nuke 目录、系统 TEMP 等处留下残留。手工清理容易误删，脚本清理不可逆，出了事无从追溯。本插件用数据库级的纪律来做这件事：

| 痛点 | 解法 |
|---|---|
| 删错无法挽回 | 每个动作自带 validate / preview / execute / undo，目录删除 = 原子改名进回收区 |
| 清理途中崩溃 | WAL 预写日志 + 备份区，nuke_recover 重放并反向补偿；nuke_drill 随时实战验证这条退路 |
| 出事无从追责 | hash chain 审计日志，任何篡改可被 nuke_verify 检出 |
| 并发清理打架 | 跨进程读写锁（O_EXCL + bootToken 归属核验 + guard 目录互斥） |
| 不知道能删多少 | 五因子评分 + 趋势回归 + 磁盘写满预测，先预演后执行 |
| 不知道"删了会怎样" | nuke_oracle 先知推演：基于历史执行数据预测事务成功率、期望回收、最脆弱步骤 |

安装

dsh plugin add beijingwahw/dsh-nuke-plugin --profile web

安装后直接对话即可，例如：

帮我扫描一下 web profile 的插件残留，先预演不要真删

安全纪律（设计原则）

1. fail-closed — 校验器/健康检查自身失败时同样拒绝操作，绝不"查不到就放行"
2. 路径 Containment — 所有路径操作限制在授权目录内；txId 白名单 [A-Za-z0-9_-]{1,64} 防穿越注入
3. TOCTOU 复验 — 分析与执行是两个时刻，执行前重验指纹（size + SHA-256 + mtime）
4. 诚实记账 — bytesSaved 只计真正释放的空间（nlink>1 的硬链接替换不虚增）
5. 保护名单 + 限额 + 黑窗 — 作为引擎 pre-hook veto，超限即拒绝（纵深防御，不依赖单层检查）
6. 回收区代替物理删除 — commit 后才允许 purge；restore 失败或存在孤儿产物时绝不 purge

工具速查（25 个）

所有工具注册为 dsh Agent 工具，安装后直接让 Agent 调用即可。

感知 — 先看清现状

| 工具 | 说明 |
|---|---|
| nuke_list | 列出 profile 下已安装的第三方插件 |
| nuke_scan | 残留扫描（配置引用/目录/TEMP），五因子评分 + 可回收空间统计；省略插件名进入全局模式 |
| nuke_deps | 依赖关系检测：谁引用了目标插件（删除前必查） |
| nuke_orphans | 全局孤儿扫描：node_modules 未声明包 / 无主附件 / TEMP 过期条目 |
| nuke_health | 健康检查：config/dependency/runtime/residue 四组，critical 失败自动阻断清理 |

决策 — 评估风险与收益

| 工具 | 说明 |
|---|---|
| nuke_blastradius | 爆炸半径沙盘推演（what-if，零副作用）：删除会损坏谁、可级联谁、风险几级 |
| nuke_strategies | 查看三级策略（safe / balanced / aggressive）的动作集 |
| nuke_policy | 查看守卫配置：保护名单 / 批量上限 / 回收上限 / 磁盘下限 / 时间黑窗 |
| nuke_trend | 历史趋势：字节/天变化率、30 天外推、3σ̂ 异常检测（失控写盘早期信号） |
| nuke_forecast | 磁盘写满预测：趋势 × 实时余量 → 倒计时与分级建议 |
| nuke_oracle | 先知推演：概率化后果预测——事务成功率、期望回收（校准分布修正）、最脆弱步骤、爆炸半径、磁盘倒计时延长、预计耗时（p50 与悲观 p90）、下行风险 CVaR₁₀、Thompson 探索口径与信息价值排序（建议先执行哪步以最快积累证据）；基于历史执行数据贝叶斯自学习 + 从战绩自我校准，零副作用不拿锁 |
| nuke_failures | 失败档案：每类动作的历史失败模式诊断（EBUSY 锁定/超时/权限/校验拒绝…）、瞬态份额与处方；⚡瞬态引擎自动重试、🔒永久需人工介入 |
| nuke_scorecard | 先知战绩对账单：执行前已存证进 hash chain 的预测（成功率/耗时）vs 实际结局——Brier 技能分（对照无技能基线）、逐步命中明细、耗时偏差分布、重试疗效学习值、系统性偏差诊断与自我校准位移；回答"先知的数字到底可不可信、偏在哪、纠了没有" |

执行 — 事务化清理

| 工具 | 说明 |
|---|---|
| nuke_clean | 事务化强力卸载：健康闸门 → 独占锁 → 计划 → 预演/提交；失败自动 Saga 回滚 |
| nuke_dedup | 内容寻址去重：三级瀑布（尺寸 → 采样指纹 → SHA-256）分析，apply=true 时硬链接实收 |
| nuke_restorepoint | 配置还原点：list / create / restore / prune |

恢复与审计 — 出事有退路

| 工具 | 说明 |
|---|---|
| nuke_status | 查询事务状态：带 tx_id 返回步骤明细与回收统计；省略 tx_id 列出活跃事务与崩溃残留的未终结事务 |
| nuke_locks | 锁诊断（零副作用）：全部锁文件的持有者现场 —— 进程存活 / TTL 状态 / PID 复用甄别 / 自动回收倒计时；E_LOCK_HELD 排障第一工具 |
| nuke_recover | 崩溃恢复：扫描未终结事务的 WAL，反向补偿恢复到执行前状态 |
| nuke_verify | 审计链完整性校验（hash chain 任何篡改均可定位） |

运维 — 日常保养

| 工具 | 说明 |
|---|---|
| nuke_doctor | 一键全科体检：健康 + 残留 + 孤儿 + 评分 → P1/P2/P3 优先级处方 |
| nuke_guardian | 守卫者巡检：磁盘倒计时 / 趋势异常 / 未终结事务 → 带建议的分级告警 |
| nuke_gc | 备份 GC：按宽限期（默认 14 天）+ 空间配额清理已终结事务的备份区，未终结事务永不淘汰；dir-move 隔离量结算为真实物理回收（台账 pending→freed） |
| nuke_ledger | 空间台账：每字节回收可溯源，按动作/profile/日聚合，freed/pending 双轨 |
| nuke_drill | 混沌演习：沙箱中执行真实事务 → 第 N 步后模拟“断电”（不回滚、锁悬挂）→ 走真实恢复路径 → 逐项验证数据字节级还原 / 审计链完整 / WAL 终结 → 签发崩溃安全证书 |

典型工作流

第一次清理（推荐路径）

1. nuke_scan                    # 看清残留与可回收空间
2. nuke_oracle                  # 先知推演：做了会怎样（成功率/期望回收/最脆弱步骤）
3. nuke_blastradius [插件]       # 零副作用推演：会不会误伤
4. nuke_clean --dry_run true    # 预演：只出计划，不动文件
5. nuke_clean                   # 执行：失败自动回滚，全程审计

aggressive 策略（需要确认令牌）

nuke_clean --strategy aggressive \
--confirmation_token "CONFIRM:web:,"

崩溃后恢复

1. nuke_status                  # 查看未终结事务（省略 tx_id = 清单模式）
2. nuke_recover                 # WAL 重放 + 反向补偿
3. nuke_verify                  # 校验审计链完整性

日常保养

nuke_guardian                   # 一键巡检，输出带建议的告警
nuke_forecast                   # 磁盘还能撑几天
nuke_drill                      # 定期混沌演习，确认崩溃退路始终有效

核心创新：会自我学习的清理引擎

传统工具的“预演”只能告诉你“我打算做什么”。本插件更进一步——用历史执行数据回答“做了会怎样”，并用真实崩溃验证“出了事能否退回”。

先知引擎（nuke_oracle）— 概率化后果推演

dry-run 是确定性预演，先知是概率化推演。每次清理的每个步骤都会入审计链，先知从中学习：

- 贝叶斯可靠性模型（经验贝叶斯收缩）：每个动作的成败率向全局均值收缩——
p̂ = (s + κ·μ) / (n + κ)。执行过 100 次的动作自信报数，只跑过 1 次的动作自动向全局均值靠拢，不会被单次运气带偏
- 设计先验冷启动（V5.1.1 修复）：零历史时全局均值向设计先验 0.95 收缩而非硬币 0.5 ——
事务引擎 validate 前置 + 快照备份 + 回滚保护，步骤失败是设计上的例外。旧硬币先验在 Saga 连乘下指数塌缩（4 步 6%），把“零信息”误渲染成“高故障”；现在零历史 3 步事务报 85.7%，且置信度诚实标 low、逐步明细标 🧭（纯先验）、CI 仍宽开（Wilson 不假装知道）。约 20 次全局观测后历史数据权重过半，先验自动让位
- 校准分布：追踪“预估回收 vs 实际回收”的比率历史，用中位数修正乐观估计——预演说能回收 1GB，历史上实际只有 90%，先知就按 90% 报
- 事务成功率：各步骤成功概率连乘，一眼看出整条链的把握有多大
- 期望回收：Σ(步骤回收量 × 校准系数) × 事务成功率——不是“最多能回收多少”，是“预期能回收多少”
- 最脆弱步骤：成功率贡献最小的一环，建议先修它（比如先解依赖再清理）
- 零副作用：影子上下文执行 preview，不拿锁、不落盘

混沌演习（nuke_drill）— 崩溃安全证书

“有恢复机制”和“恢复机制真的有效”是两回事。演习不承诺，只验证：

沙箱搭建 → 真实事务执行 → 第 N 步成功落盘后模拟进程死亡
（跳过回滚、跳过锁释放——最恶劣的崩溃现场）
→ 模拟重启 → 走真实 nuke_recover 路径 → 逐项验证：
✓ 崩溃注入生效          ✓ 事务完整回滚
✓ 数据字节级还原         ✓ 审计链完整（hash chain）
✓ 新事务畅通无阻塞       ✓ WAL 正确终结
→ 通过则签发崩溃安全证书（含耗时与验证明细）

随时可跑、不触碰真实环境。升级、改配置、怀疑人生时，跑一次就知道退路还在不在。

数据闭环

执行（审计链记录每步成败与预估/实际）
→ 可靠性模型（贝叶斯学习：动作成功率 + 校准分布）
→ 先知引擎（预测下次：成功率 / 期望回收 / 最脆弱步骤）
→ 决策（先修最弱步骤，或换 safe 策略）
→ 再执行 → 数据更准 → ...

V5.6 探索智能：从纯利用到知情探索，从期望值到下行风险
V5.5 之前的学习系统有一个结构性死锁：所有预测取后验均值，决策永远偏向历史证据充分的动作——新动作/新尺寸桶收缩向先验，在均值口径下永远竞争不过“老将”，于是永远不被执行、永远没有数据、先验永远不被修正（多臂老虎机的“富者愈富”）。V5.6 用两个世界级机制补全决策智能的最后两块：

Thompson 受控探索（后验采样决策）

纯利用（旧）：决策 = argmax 后验均值      → 富者愈富，新动作饿死
Thompson（新）：决策 = argmax 后验抽样 p̃  → 后验宽（数据少）的动作
偶尔被抽得很高 → 获得执行机会
→ 产生数据 → 后验收窄
→ 探索/利用比例由不确定性自动调节

- sampleBeta：Marsaglia-Tsang Gamma + Box-Muller 的种子化 Beta 采样（零依赖，逐位可复现）
- 可靠性模型暴露最终层 Beta 后验参数（与均值点估计同源，桶调制后即桶层后验）
- nuke_oracle 输出探索口径（采样成功率 vs 均值成功率并列）与信息价值排序：不确定敞口 = 后验 σ × 失败敞口——“这步的不确定度值多少字节”，数据最少、牵扯最大的步骤最先被建议执行
- 探索是建议不是行为：执行决策权仍在用户/Agent，种子固定可复现

CVaR₁₀ 下行风险（最差 10% 情形能剩多少）

蒙特卡洛分布不止报 P10/P90 悲观-乐观带，新增条件风险值：最差 10% 抽样的平均回收。Saga 全或无语义下成功率 > 90% 时尾部由失败回滚（=0）过渡到最小的成功抽样——诚实回答“最坏情形我能接受吗”，而不是只给让人舒服的期望值。

V5.5 自我校准：对账不止打分，还驱动再学习

V5.4 让预测可问责（存证 + Brier 对账），但问责本身不改善预测——先知报 95% 实际只有 60%，计分器只是把这件尴尬的事写下来。V5.5 闭环最后一段：从已对账的 (预测, 结局) 对学习系统性偏差，动态修正未来预测：

预测 → 存证（hash chain）→ 执行 → 对账（Brier/技能分）
↑                                      ↓
└──── 校准位移 δ 修正未来预测 ←── 从残差学习 δ
（过自信 → δ0 拉高；
残差消失 → δ→0，迭代收敛的终点）

学什么：Platt 截距式校准

对账侧（nuke_scorecard 同源逻辑）从步骤级 (预测, 结局) 对学习：

meanPred = 存证均值          actualRate = 实际率（Laplace +1/+2 收缩）
δ_raw = logit(actualRate) − logit(meanPred)     ← 系统性偏差的 logit 口径
δ     = δ_raw · w,  w = n/(n+K)                 ← 证据权重收缩（K=8）

- 证据纪律：已对账步骤  16 → 贪心剔除序列（按 bytes/pct 性价比）+ 2-swap 局部改善

三种问法（同一前沿）：
max-reclaim {minSuccess}  → 成功率达标下回收最大（概率背包）
max-success {minReclaim}  → 回收达标下成功率最大
pareto                    → 全前沿 + 拐点推荐（边际收益崩塌处）

两个数学事实贯穿设计：

- 全集不一定帕累托最优：E=∏p·Σw 下，剔除“低成功率大动作”可能同时提升两目标（成功率大涨、回收微降）——推荐计划可能优于“全都要”
- 空集不是解：不清理就无需跑事务，解空间从首个非空子集开始

可解释性：每个被剔除动作附带账单——+2.1pct 成功率 / 代价 340MB（162MB/pct），推荐不是黑箱。

操作级成功率：大小分桶（三层收缩）

“remove-node-modules 的成功率”是动作级粗粒度——删 2GB 和删 5MB 的失败模式完全不同（EBUSY/长路径/超时集中于大目录）。V5.2 引入协变量调制：

四层收缩：桶 → 动作 → 全局 → 设计先验
桶边界：/.nuke/（wal/ backups/ audit/ ledger/ history/ policy.json restore-points/）

开发

git clone https://github.com/beijingwahw/dsh-nuke-plugin
cd dsh-nuke-plugin
npm install
npm run typecheck    # tsc --noEmit（零错误）
npm run lint         # eslint 严格基线（strictTypeChecked，零告警门禁）
npm test             # vitest（758 用例 / 47 文件）
npm run build        # tsdown 构建
npm run dev          # 开发期热更新进程（见下）

热更新（HMR）

| 层 | 方法 | 生效范围 |
|---|---|---|
| 运行配置 | 编辑 dsh 用户层 cordis.patch.yml（~/.dsh/profiles// 或 ~/.dsh/），保存即生效 | dsh 原生监视用户层，事务性重载该行（bundle 层默认值已全量列出，照抄整行覆盖即可） |
| 开发期代码 | npm run dev 起独立 cordis + HMR 进程 | 保存 src/ 下任意文件或 cordis.yml → 旧实例卸载（effect 回卷）→ 新代码挂载，无需重启 |
| 安装产物 | 改代码 → npm run build → 重新 dsh plugin add → 重启 dsh | 更新已安装的插件 |
npm run dev 的组成：仓库根 cordis.yml 依次挂 logger / timer / hmr / 宿主桩 / 本插件（直接加载 src/index.ts）；
dev/host-stubs.ts 提供 dsh 宿主 tools 服务的最小桩（本插件 inject ['tools']，缺桩会永远 PENDING）。

注意：开发基线为 Node ≥ 24.11（已在 package.json 的 engines 声明，npm 安装时自动校验）。早期 24.x（如 24.1.0）的 Node 内部接口与 cordis-plugin-loader 1.0.2 不兼容（表现为 HMR 编辑文件不触发重载），且不满足 tsdown 0.22 的引擎要求。

FAQ

Q: 清理会物理删除我的文件吗？
目录删除是原子改名进备份区（rename，跨设备回退 copy），commit 后 purge 前可 nuke_recover。restore 未全部成功或存在孤儿产物时，引擎拒绝 purge —— 这些产物可能是数据唯一副本。

Q: 去重的硬链接安全吗？
verify-then-link：canonical 与 victim 执行前重算 SHA-256 复验；跨文件系统（st_dev 不同）、符号链接、mtime 变化的 canonical 一律跳过。替换是 link→tmp→rename 原子操作，无空窗；journal 记录每一步，可 undo 复制回独立文件。

Q: 趋势预测为什么用 Theil-Sen 而不是最小二乘？
最小二乘 breakdown point 为 0% —— 单个离群点（一次异常写盘）就能把斜率拉偏，污染写满倒计时。Theil-Sen（成对斜率中位数）breakdown point 29.3%，配合 MAD×1.4826 稳健 σ，近三分之一数据被污染时预测仍然正确。

Q: 多个 dsh 实例同时清理会怎样？
nuke_clean 持有跨进程独占锁（O_EXCL 原子获取 + bootToken 归属核验 + 固定名 guard 目录互斥），后到者等待或失败，绝不会交叉写。

Q: 先知的成功率预测为什么用贝叶斯收缩，而不是直接用历史频率？
只跑过 1 次且恰好成功的动作，频率是 100%——但没人敢信。经验贝叶斯收缩 p̂ = (s + κ·μ) / (n + κ) 把小样本拉向全局均值：数据越多越自信，数据越少越保守。这与保险精算、A/B 测试平滑是同一套方法论。

Q: 刚装好还没清理过，先知报的事务成功率可信吗？
可信，且要看懂它的口径。零历史时每个动作的成功率收缩向设计先验 0.95（V5.1.1 起）——依据是引擎本身的设计：validate 前置把失败拦在 commit 之前、编辑前快照备份、目录改名进回收区、Saga 回滚。所以"没跑过"≠"五五开"，3 步事务报 0.95³≈85.7% 而不是 0.5³=12.5%。同时它诚实标注：置信度 low、纯先验步骤标 🧭、CI 宽开。跑过约 20 次清理后历史数据权重过半，预测由你的真实历史主导。若你的环境确实更脆弱，可在可靠性模型注入 priorSuccessProbability 调低锚点。

Q: nuke_scorecard 的技能分是什么口径？负分说明先知在瞎猜吗？
Brier 分 = (预测概率 − 实际结局)² 的均值（0 完美、0.25 硬币水平）。但绝对值没有参照系，所以战绩单以无技能基线为对照：一个总是预测"历史平均成功率"的傻瓜预测器的 Brier 分。技能分 SS = 1 − Brier/Brier_baseline：1 = 完美校准，0 = 不比傻瓜强，负 = 比傻瓜还差。样本 /drill// 沙箱内进行——用一份合成的插件布局（含受保护文件）执行真实事务代码路径，崩溃、恢复、验证全部发生在沙箱里，真实环境零接触。

Q: 健康检查提示 dsh CLI 不可用，但我明明装了（shell 里 dsh --version 正常）？
这是宿主进程 PATH 与用户 shell PATH 不一致的经典场景（dsh 经 nvm/npm 安装，rc 文件注入的 PATH 宿主进程看不到）。V5.1 起注册表会自动走全局 bin 救援（nvm/volta/asdf/npm 前缀目录），命中则以 rescued 状态继续工作；也可设 DSH_BIN=/完整/路径/dsh 显式指定。CLI 缺失只是 warning（附 skip_standard 降级建议），不会阻断清理事务。

Q: 我想让清理彻底绕过 dsh CLI，怎么做？
nuke_clean 传 skip_standard: true 跳过标准卸载步骤；其余配置摘除与目录回收动作不依赖任何外部 CLI。

License

MIT © 2026 beijingwahw