dsh-nuke-plugin

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

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

为什么需要它

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 的插件残留，先预演不要真删

安全纪律（设计原则）

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

崩溃后恢复

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 拉高；
                残差消失 → δ→0，迭代收敛的终点）

学什么：Platt 截距式校准

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

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

证据纪律：已对账步骤 < 5 → 不修正（没有统计力就不动，诚实留白）
钳制：δ ∈ [−5, +5]；修正后 p ∈ [0.001, 0.999]
耗时同理：中位耗时比（实际/预测）向 1 收缩为修正因子，钳制 [0.25, 4]——预测系统性偏乐观 3× 就放大 3×（按证据权重打折）

用在哪：写侧与读侧同源

引擎存证（写侧）：commit 前的预测存证直接落校准后口径，detail 记录 calibrationDelta / calibrationEvidence——存证与推演同一套修正，对账才有收敛意义
先知推演（读侧）：nuke_oracle 逐步与事务成功率给出校准后口径，叙事直白交代病史：自我校准后成功率 74%（历史预测过自信：存证均值 90% vs 实际 55%，12 步证据 → logit 位移 −0.75）
故障纪律：校准器抛错 → 恒等存证/恒等推演（学习失败绝不阻断真实清理）；未注入 → V5.4 语义完全兼容

为什么这样设计

logit 空间线性——概率靠近 0/1 时偏差被天然放大（0.99→0.95 与 0.6→0.56 的"严重性"不可同日而语），logit 位移对此无偏
证据收缩而非全信——6 步证据只信 43%（w=6/14），50 步信 86%；小样本的极端战绩不会把预测甩飞
存证口径 = 推演口径——若存证用原始值、推演用校正值，对账永远学不到真残差，闭环退化成摆设

V5.4 先知问责制：预测若不可证伪，就与巫术无异

V5.3 之前，先知在事务执行前报出"成功率 87%"，但没有任何机制核对这句话：预测过了就过了，说 60% 报 95% 无人知晓。V5.4 给预测装上存证 + 对账两翼，先知从"预测者"升格为"可问责的决策顾问"：

commit 前（写侧）：预测存证
   逐步预测（predictedP / estimatedBytes / predictedDurationMs）
      + 事务级成功率 → 写入 hash chain 审计链
   ✓ 预测先于结局（时间戳为证）   ✓ 事后不可篡改（链哈希）
   ✓ 统计增强能力：构建/存证失败只记日志，绝不阻断真实清理

执行后（读侧）：nuke_scorecard 对账
   预测存证 × 步骤结局 × 事务终结 → 三方证据对账
      → Brier 分（预测校准度的事实标准）
      → 技能分 SS = 1 − Brier/Brier_baseline（对照"无技能基线"：
        总是预测平均成功率的家伙 —— 跑赢他才算有本事）
      → 耗时偏差分布（预测 p50 / 实际耗时 的比率中位数）
      → 逐步命中明细（预测 0.87 的那步，究竟成了没有）

耗时模型：从"会不会成"到"要等多久"

每动作学习耗时分布（时间加权 p50/p90，半衰期 30 天，墙钟口径含重试退避等待 —— 用户等的就是这个数）；成败双向计入（失败步骤的耗时同样是"这步要多久"的证据）
nuke_oracle 报告新增预计耗时（各步 p50 之和）与悲观上界（各步 p90 之和，"每步都跑在最慢 10%"）；任一步零历史 → 整体 null 诚实留白（不用先验冒充耗时证据）

重试疗效学习：常数 0.5 退役

V5.3 假设"单次重试对瞬态失败的成功率是 0.5"——一个没有证据的常数。V5.4 用引擎自己的历史成绩说话：

营救池 = 审计链中所有 retries ≥ 1 的步骤
   → 营救率 r̂ = (rescued + a·r₀)/(pool + a)（向先验收缩，a=4）
   → 反解单次疗效 ê = 1−(1−r̂)^(1/R)（R=引擎重试上限）
   → 投影 p_adj = p + (1−p)·t·(1−(1−ê)^R)

疗效观测惨淡（比如 EBUSY 常驻锁 8 次重试 0 次救回）→ 学习值自动拉低投影，先知不再对无效重试抱有幻想；零观测时退回 0.75 总营救率先验（与 V5.3 默认一致）。严格往返保证：r̂=0.64, R=2 → ê=0.4 → 复合回 1−(1−0.4)²=0.64。

V5.3 失败模式智能：从"会挂"到"为什么挂、怎么办"

V5.2 之前，系统学习"这步会挂"（概率），但不学习"以什么方式挂、挂了怎么办"。失败被回滚后，下一次清理迎面撞上同一个失败。V5.3 闭环了预测 → 诊断 → 处方 → 自愈 → 再学习：

失败分类学（契约层单一事实源）
   ├── 分类器：错误文本 → 10 种规范模式（locked/timeout/resource/space/
   │   vanished/permission/validation/dependency/io/unknown）
   ├── 瞬态性：transient（EBUSY/超时/句柄…重试有救）vs permanent（校验/权限/依赖…重试纯浪费）
   └── 处方：每个模式一条人类可读的修复指引
        ↓ 写方（引擎）与读方（模型）共享 —— 分类规则永不漂移
   ├── 引擎：步骤级模式感知重试（瞬态 → 有界指数退避自动重试；永久 → 立即失败快速回滚）
   ├── 模型：从审计链学习每动作的失败模式分布 + 瞬态份额
   │         → 重试调整成功率 p_adj = p + (1-p)·t·(1-(1-e)^R)
   └── 先知：重试感知事务成功率（两档口径并列）+ 最脆弱步骤的模式诊断与处方
             + 计划合成候选取重试调整口径（预测与引擎真实行为对齐）

三个关键设计：

模式感知重试，不是盲目重试——EBUSY（文件被占用）稍后自愈概率高，指数退避后重试（默认 2 次、退避 150ms 起步、单次等待上限 2s）；E_VALIDATION（策略拒绝）重试一万次结果相同，立即回滚省时间。命令级重试（exec-ops 的 spawn 错误）之上补齐了步骤级（fs/edit 操作失败同样覆盖）
投影不双重计息——基础 p 取经验值（历史若已含重试自愈效果则一并计入），重试调整投影建立在经验之上：p_adj = p + (1-p)·t·(1-(1-e)^R)（t=瞬态份额，R=重试上限，e=单次重试成功率默认 0.5）。引擎一直开着重试时投影收敛于经验值，永不发散
审计即学习数据——引擎把 retries 与 failureMode 写进步骤审计 detail；可靠性模型优先读显式 failureMode（新条目），缺失时从 error 文本现场分类（旧条目兼容）—— 迁移零成本

nuke_oracle 输出升级：♻️ 重试感知成功率（两档口径并列）、逐步推演附模式画像（locked⚡80% = 80% 的历史失败是锁定、瞬态可自愈）、最脆弱步骤附🩺 主导失败模式 + 💊 处方。新工具 nuke_failures 给出全部动作的失败档案。

V5.2 决策智能：帕累托计划合成（先知从"预测者"到"决策顾问"）

先知此前只回答"这个事务多危险"；V5.2 让它回答"那我该怎么办"。

计划合成器（Optimizer）

在成功率 × 回收量的双目标上合成帕累托最优的动作子集（Saga 语义：P(S)=∏p_i，E(S)=P·Σw_i）：

求解（世界级惯例：小规模精确、大规模启发式）：
  n ≤ 16 → 2^n 精确枚举（65,536 子集，毫秒级）→ 数学最优前沿
  n > 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 引入协变量调制：

四层收缩：桶 → 动作 → 全局 → 设计先验
  桶边界：<1MB（small）/ 1MB~100MB（medium）/ ≥100MB（large）
  桶层：α_b = p_action·κ_b + s_b（κ_b=5，桶样本被三桶摊薄 → 更快向动作层让位）
  失败样本同样归桶（审计失败事件已带 estimated）→ 双向归桶无偏
  桶内零样本 → 调制不生效（诚实返回动作层估计，sizeBucket.selfWeight=0）

nuke_oracle 的逐步推演与计划合成全部使用操作级成功率，nuke_oracle 输出新增帕累托前沿阶梯（激进端→保守端，★ 标推荐点）与剔除理由清单。

V5.1 长期方案：外部工具治理（单一事实源）

真实故障复盘：dsh CLI 经 nvm 安装，用户 shell 的 rc 文件注入 PATH 而宿主进程不加载 rc → 宿主 PATH 缺口 → spawnSync('dsh') ENOENT。此时系统中有三处独立探测（健康检查 / standard-remove / pnpm-prune）各自解释"什么算可用"，一处误报 critical 即阻断全部清理 —— 即便 dsh 实际就装在 ~/.nvm/versions/node/v24/bin/dsh。

长期方案把外部工具解析收敛为一份实现、一个事实源：

工具注册表（ToolRegistry）

解析链（顺序固定，全系统只此一份）：
  ① 显式环境变量 DSH_BIN / PNPM_BIN
     → 用户显式指定的路径失效时响亮报错，绝不静默降级
  ② 裸名探测（PATH 语义）
     → exit 0 = ok；exit 非 0 但进程已执行 = ok（旗标差异不算缺失）
  ③ spawn ENOENT → 全局 bin 候选目录救援（nvm/volta/asdf/npm 前缀）
     → 救援命中 = rescued（附宿主 PATH 修复提示）；全落空 = missing

治理原则：

语义漂移在结构上不可能 —— 健康检查、standard-remove、pnpm-prune、doctor 全部委托同一注册表，"什么算可用"只存在一份定义
能力映射降级 —— 每个工具声明 affects（依赖它的动作清单）；缺失时只降级这些动作并给出 fixHint，永不全局阻断清理
TTL 缓存（60s） —— 一次事务内多次探测共享结果；环境变化后可 invalidate() 强制重解析
逃生通道 —— DSH_BIN / PNPM_BIN 环境变量显式指定路径，绕过 PATH 缺口

doctor 环境矩阵

nuke_doctor 报告新增环境矩阵：全部已注册外部工具的解析结果（状态 + 来源 + 路径 + 版本 + 影响面 + 修复建议），与 runtime 健康检查同源（共享注册表缓存）—— 两处输出永远一致，排查环境问题一次到位。

─ 环境矩阵（外部工具）─
  ✅ dsh: 版本: 0.1.0-rc.6
  🟡 pnpm: 可用: 9.12.0（救援路径 /home/t/.nvm/.../bin/pnpm；宿主 PATH 未含该目录，建议修复）
  ❌ node: node 命令未找到（宿主 PATH 与常见全局 bin 目录均无 node）
     🔧 安装 node 或将其所在目录加入 PATH

V5 全模块升级总览

V5 聚焦 V4 未覆盖的模块与一处真实整合缺口，全部向后兼容，零新增运行时依赖。

关键修复：V4 整合缺口（真实缺陷）

V4 在契约中定义了 freezeWindows/maxFilesPerTx，但守卫从未执行（hitFreezeWindow 零调用、fileCount 无人供给）。V5 补全完整链条：

FREEZE_WINDOW：hitFreezeWindow 纯函数（跨零点/多窗支持）接入 policy-guard 首查
TOO_MANY_FILES：dirStats（一次遍历产出字节+文件数）→ fs-ops/edit-ops preview 填充 OperationPlan.fileCount → commit 前预飞 dry-run 汇总 → 守卫第二道闸门
commit 前预飞复查：执行前零副作用预演拿真实文件数再过策略（预演结果同时预热 estimates，零额外成本）

infra 剩余模块

模块	升级
policy-guard	冻结窗/文件数上限真正执行；策略文件加载校验（非法配置 fail-closed 忽略并定位到字段级 issue）；全部违规附带人类可读修复建议
path-resolver	NFC Unicode 归一（杜绝同形异码绕过白名单）；控制字符路径拒绝；darwin/win32 大小写不敏感白名单匹配
validator	`validateAll` 批量校验一次返回全部错误；profile 字符集与插件名对齐
logger	结构化 JSONL 模式（机器可读）；`child(bindings)` 上下文子日志器
reporter	Markdown/JSON 报告汇总统计区（按动作分组回收量、成功率、总量）

engine 剩余模块

模块	升级
transaction-engine	dry-run 预览有界并发（默认 4，输出顺序稳定）；commit 每步耗时进审计 detail
hook-registry	钩子优先级排序；单钩子错误隔离（veto 仍立即短路）；注册级超时
blast-radius	直接/传递依赖方分层（1 跳 vs 2+ 跳）；按 profile 影响计数
orphan-detector	多 profile 检测并行化（输出稳定排序）
restore-point	`maxPoints` 保留策略（在用还原点宁可多留不误删）；创建后读回 hash 校验（fail-closed）
health-inspector	四组检查并行执行（组序稳定）；inode 压力检查（探测不到标记 skipped）

V4 全模块升级总览

V4 对五层架构的每个模块做了系统性升级，全部向后兼容（API 只增不改），零新增运行时依赖。

infra 基建层

模块	升级
审计链	`appendMany` 批量追加共享一次 fdatasync；`verifyIncremental` 从可信锚点增量校验（锚点失配/截断攻击均 fail-closed）
WAL	已终结事务归档至 `archive/`（replay 仍可读，扫描只扫活跃区）；尾部半行自动截断修复（中间行损坏拒绝修复）；父目录 fsync
锁	等待重试升级指数退避 + 等值抖动（防惊群）；`autoRenewMs` 后台心跳自动续期
备份区	`restoreAll` 依赖分层并行恢复（同层并发、层间串行）；恢复后 size/hash 指纹复验
fs-utils	统一 `walk()` 流式遍历原语（AbortSignal/深度限制/不走 symlink）；`withTransientRetry` 瞬态错误退避重试（EMFILE/ENFILE/EBUSY）
扫描缓存	命中刷新 LRU 热度（热条目不因 TTL 被逐）；容量上限驱逐
可靠性模型	Wilson score 可信区间（小样本天然有界）；校准分位数指数时间加权（近期样本权重更高）

engine 引擎层

模块	升级
先知引擎	蒙特卡洛模拟（带种子可复现，2000 次抽样）输出回收 P10/P50/P90 分布；最脆弱步骤附带"修复收益"量化
趋势追踪	时间加权 Theil-Sen（近期样本权重更高）；CUSUM 变点检测识别增长率突变；30 天预测区间
磁盘预测	写满倒计时 95% 置信区间（不确定性传播），分级按区间悲观侧判定
评分器	五因子权重可配置，输出各因子贡献度明细（解释性）
依赖图	文件指纹缓存（mtime+size），未变文件解析结果增量复用
残留扫描	迁移至流式 walk（可中断）；进度事件限频防风暴
去重	采样指纹升级头+中+尾三段（大文件中部参与指纹，降低碰撞误判）
混沌演习	`matrix=true` 崩溃注入点矩阵（plan 后/第 1 步后/第 2 步后），每点独立验证签发证书
守卫者	告警去重键 + 抑制窗口；"全部被抑制"不再谎报"一切正常"

operations / contracts 层

模块	升级
exec-ops	外部命令瞬态重试（指数退避）+ 超时硬上限 fail-closed；stdout/stderr/exitCode/durationMs 结构化捕获进审计
fs-ops	preview 附带目录 top-N 大文件/子目录影响面明细
edit-ops	幂等化（引用不存在 → skipped 语义，不报错不产生空操作）；YAML 摘除字节级保持（注释/顺序/CRLF 原样透传）
策略编译	动作集元数据化（riskLevel + 描述，表驱动）；`makeOperationPlan` 零副作用计划预览
契约增量	`freezeWindows` 多重时间黑窗、`maxFilesPerTx` 文件数上限、`DryRunReport.actions` 动作级明细（含风险分级与跳过标记）

事务引擎与工具接线

dry-run 报告填充动作级明细：nuke_clean --dry_run 直接输出风险分级的动作清单（🟢/🟡/🔴）与幂等跳过标记
nuke_oracle 输出蒙特卡洛分位数；nuke_trend 输出变点与预测区间；nuke_forecast 输出置信区间；nuke_drill 支持 matrix 参数

独立 CLI

锁协议对齐 V4（关键安全修复）：此前 CLI 的 .nuke.lock（V3）与插件 .nuke/locks/（V4）互不感知，并发清理可能交叉写；现在 CLI 与插件共享同一锁目录、文件格式与破锁纪律（O_EXCL + bootToken 归属 + 死亡且过期才破锁）
--json 机器可读输出（scan/deps/health/sweep，CI 友好）；--version；崩溃兜底（未捕获异常 fail-closed 退出并引导提 issue）
遍历 symlink 防护 + 深度限制（防目录环/逃逸）；瞬态 IO 退避重试；修复 strategies 输出 undefined 的缺陷

事务生命周期

nuke_clean
   │
   ├─ 健康检查闸门（critical 失败 → 拒绝；检查本身失败 → 同样拒绝）
   │
   ├─ begin: 独占锁 + 事务 ID + WAL 开档
   │
   ├─ plan: 依赖校验 / 令牌校验 / 策略守卫（保护名单/上限/黑窗 veto）
   │
   ├─ dry_run? ── 是 ── 输出计划明细 → rollback 释放（零副作用）
   │
   ├─ commit（每步均经 WAL）:
   │     step-intent → 备份/stage → 副作用 → 事后断言
   │        │ 成功 → 下一步
   │        │ 失败 → Saga 反向补偿（undo 逆序）→ rollback
   │
   └─ finalize: 摘要缓存 → 释放锁 → 审计入链（hash-linked）

崩溃窗口（任意时刻断电/被杀）:
   下次 nuke_recover → WAL 重放 → 备份区逆序 restore → 全部成功才 purge
   restore 有失败或孤儿产物 → 保留备份，保持"未终结"，等待人工/重试

架构

src/
├── contracts/   # 契约层：先定义接口再实现；Result 类型消灭异常控制流
├── infra/       # 基建：WAL / 读写锁 / 备份区 / hash-chain 审计 / 台账 / 校验器 / 贝叶斯可靠性
├── engine/      # 引擎：事务 / 扫描 / 评分 / 依赖图 / 去重 / 趋势 / 守卫 / 还原点 / 先知 / 混沌演习
├── operations/  # 命令模式：每个动作自带 validate/preview/execute/undo
├── runtime.ts   # 运行时组装：全量依赖注入的唯一场所
├── tools/       # 工具注册层：感知 / 决策 / 执行 / 恢复保障四域 23 工具
└── index.ts     # 插件入口（纯组装，零业务逻辑）

数据落盘位置：<dshHome>/.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/<name>/` 或 `~/.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 = 不比傻瓜强，负 = 比傻瓜还差。样本 < 2 时诚实显示 n/a —— 对账没有统计力时绝不给出误导性结论。

Q: nuke_oracle 和 nuke_clean --dry_run 有什么区别？ dry-run 回答"我打算做什么"（确定性计划明细）；先知回答"做了会怎样"（概率化后果：成功率、期望回收、最脆弱步骤）。两者互补：先知看趋势，dry-run 看细节。

Q: 混沌演习会在我的真实环境里制造崩溃吗？ 不会。演习在 <nukeRoot>/drill/<runId>/ 沙箱内进行——用一份合成的插件布局（含受保护文件）执行真实事务代码路径，崩溃、恢复、验证全部发生在沙箱里，真实环境零接触。

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。

Installer

README