jonah791/dsh-clyan

dsh-clyan

一句话：把 clyan 磁盘清理 CLI 包成 16 个工具——从「 ⚠ 含破坏性操作：clyan_clean（autoSafe/deep+yes）、clyan_auto_clear 会真删文件。默认一律 dry-run 预览；实际删除需显式参数。删除属「须请示」类动作——授权与判断归人。

能力

| 工具 | 用途 |
|------|------|
| clyan_pulse | 磁盘健康检查（minSizeMB） |
| clyan_doctor | Clyan 系统诊断：模块可导入性/数据库/磁盘/providers/缓存一致性检查 |
| clyan_reclaim | 完整回收计划（=全量扫描→去重→按 recovery_cost 分阶段 none/low/medium/high/unknown）。默认聚合摘要；默认 dry-run |
| clyan_clean | 清理执行。安全闸门（fail-closed）：受保护路径 + 非缓存语义路径会被强制拦截（blocked_items），不再仅警告。默认 dry-run；实际删除需 autoSafe=true（仅 confidence>=0.9 且 safety=safe）或 deep=true+yes=true |
| clyan_smart_clear | 智能清理链：扫描 → 只挑 recovery_cost=none & safety=safe & confidence>=0.9 的安全项 → 返回建议集。执行仍默认预览 |
| clyan_auto_clear | 零决策自动清理：只删 recovery_cost=none 项（Temp/npx/缩略图/WER 等）。实际执行会删文件——调用前确认 |
| clyan_history | 查看清理历史：最近操作列表，或按 id 查看单次详情 |
| clyan_undo | 撤销一次清理操作（从回收站恢复）。需要操作 ID（来自 history） |
| clyan_verify | 清理验证：无 id 时对比当前磁盘状态（pulse）与最近清理历史；有 id 时返回单次详情（含 before/after free） |
| clyan_schedule | 定时清理任务管理：create=创建每周定时清理，remove=移除，缺省=查看。注意：自主性铁律下不自动创建定时删除，此工具供主人安排时使用 |
| clyan_trust | 可信路径管理：list=查看，add=添加（跳过保护警告），remove=移除，audit=查看 trust 放行审计日志（记录时间/来源/原因，可追溯） |

快速开始

1) 装依赖：

"dsh-clyan": "link:/self-plugins/dsh-clyan"

2) 挂组合（clyanBin 指向目标环境里的 CLI；defaultPath 是缺省盘）：

- id: clyan
name: dsh-clyan
config:
clyanBin: clyan
defaultPath: 'C:\'
timeoutMs: 180000

3) 30 秒验证（只读，零风险）：

clyan_pulse {}                      → 期望返回空闲空间（/clyan-trace.jsonl*（设 DSH_CLYAN_TRACE=0 可静默关闭）：

| 阶段 | 含义 |
|------|------|
| boot | 插件装载（含 pid、build、注册的全部工具名列表、配置快照） |
| cli | CLI 子进程调用（参数摘要经脱敏、退出码、stdout/stderr 量级） |
| call | 工具调用收口（工具名、耗时、结果规模） |
| scan-shape | 扫描结果形状（items 数、分类分布）——只记形状不记路径正文 |

一条命令答五问：
bash
tail -3 "$DSH_HOME/clyan-trace.jsonl"
① 跑的是哪个构建   → build = "@"；boot 行还有 pid 与工具清单
② 谁发起/调了什么   → phase + op（哪个 clyan_ 工具）+ 脱敏后的参数摘要
③ 断在哪一段       → phase 枚举（boot/cli/call/scan-shape）；cli 行的退出码/stderr 即失败点
④ 结果质量         → scan-shape 的 items 数与分类分布（形状对不上 = 解析或 CLI 版本问题）
⑤ 耗时与预算       → call/cli 行的 durationMs vs 配置 timeoutMs

写盘失败一律吞错返回 false，绝不影响清理流程。

生效判据与回退

生效判据（三选一，按可靠性排序）：
1. tail -1 "$DSH_HOME/clyan-trace.jsonl" 里 build 的 mtime 等于 lib/index.js 的 mtime ⇒ 进程在跑当前构建；
2. 生态级：plugin_boot_status（dsh-plugin-bootreport）返回 liveNow 含本插件 ⇒ 同上；
3. 行为级：boot 行里的 tools 列表包含 16 个 clyan_，且 clyan_pulse 能返回空闲空间（CLI 不可用时工具在但必失败）。

注意：重新构建 ≠ 生效——产物 mtime 新只证明「构建过」，进程启动时间晚于产物 mtime 才算「在跑它」。

回退（三档）：
- 源码级：git -C self-plugins/dsh-clyan revert  → 重新构建 → 预检 → 重启；
- 组合级：预设里给 clyan 行加 disabled: true（或移除该行）→ 哨兵重启；
- 运行期：误删走 clyan_undo（回收站恢复）；轨迹文件可随时删除。本插件自身无持久业务状态（状态都在 clyan 侧）。

测试
bash
npm test        # = node --test "tests/.test.mjs"

96 例（tests/cli-contract.test.mjs / logic.test.mjs / trace.test.mjs / trace-wiring.test.mjs），覆盖：CLI 契约（参数拼装与 JSON 解析）、聚合摘要与 scan-shape 形状计算、脱敏（白名单外的键一律不记、键序稳定）、轨迹容错与尸体测试、工具注册接线。

双平台实测（2026-09-14）：Windows ℹ pass 96 / fail 0、WSL # pass 96 / fail 0。（修复记录：两例 argDigest/argvDigest 的主目录折叠断言原先用硬编码 C:\Users\tr 当夹具却依赖 os.homedir()，在 WSL 下家目录是 /root 故不折叠 → 断言不过。根因是测试的环境依赖，不是运行期缺陷；现改为把 home 显式注入被测函数——夹具不再依赖「运行平台的家目录恰好是 C:\Users\tr」。）

真实外部依赖：跑通业务需要 clyan CLI（Python 包）与 Windows 文件系统语义（AppData/回收站）；测试不需要（子进程以桩替代）。

设计要点

- fail-closed 安全闸门：clyan_clean 对受保护路径 + 非缓存语义路径强制拦截（blocked_items），不是「警告后照删」——闸门失效时的默认方向是拒绝。
- 默认 dry-run：所有清理类工具的默认行为是预览；真删需要显式参数（autoSafe=true 或 deep=true+yes=true）。一次误调用不会造成破坏。
- 摘要优先，detail 才全量：clyan_scan/clyan_reclaim 默认返回聚合摘要——全量 items 可能上万条，先要形状再要明细，避免一次调用淹掉上下文。
- recovery_cost 分级是分阶段清理的依据：none（Temp/npx/缩略图/WER）可零决策清理；low/medium/high/unknown 必须人判断。
- 可信路径有审计：clyan_trust 的放行记录时间/来源/原因——「放行」本身也要留痕，否则保护策略会被静默绕过。
- 自主性铁律落到工具层：clyan_schedule 不自动创建定时删除，只在主人安排时使用；删数据永远走显式授权。
- 观测单点落笔 + 只记形状：所有工具经同一 CLI 入口与同一观测出口；轨迹记参数摘要与结果形状，不记被扫路径正文（磁盘路径常含用户名等隐私）。

相关文档

| 文档 | 内容 |
|------|------|
| docs/semantic.md | 权威契约：定位与反定位、术语、概念模型与不变量、契约（含调用点清单）、边界与信任、可证伪验收清单、实践修订记录、未决问题 |
| alice-digital-life | 本插件所属生态的中心索引（全部自研插件） |
| 技能 workspace-file-governance | 工作空间分层治理：先量后改、温度分层、可回滚操作（清理决策的上游方法论） |
| 技能 plugin-maintainability | 插件可维护性工程（自证轨迹 / 五问可取 / 观测不反噬） |

License

MIT © jonah791

本插件属于我的数字生命爱丽丝（alice-digital-life）的 DSH 自研插件生态——50 个插件按生命/认知/感知/行动/通信/治理/呈现七层组织。