前言¶
在 DeepSeek Harness（DSH）里用 Subagent 时，会话日志（session log v4）和投影缓存（projection cache）会一起记录 Subagent 面板里的条目。若面板卡住、不同步，或条目在 UI 里删不掉，往往只能对着磁盘上的 session.v4.jsonl.zstd 和 storages/session_projcache 干瞪眼。直接删日志行或改 seq 会让 v4 校验失败（例如 format v4 event N is not dense），整段会话无法加载。
下面介绍的 dsh-agent-clean（维护者 PolitaryMonicy，社区分类 admin-security）是一套面向 DSH 的清理工具：默认 dry-run、写入前全量备份，用「改类型 + 标记 ignorable」的方式移出 Subagent 条目，而不是删行；并可清理孤儿投影缓存、按需整会话 purge。同一仓库里既有可独立运行的 CLI，也有可选的 DSH Desktop 插件半部（设置页 + 退出后自动清理）。
这是什么¶
dsh-agent-clean 的定位是：清理 DSH 会话中的 Subagent 条目、整会话数据，以及「会话目录已删、投影缓存仍在」的孤儿文件。实现上零第三方依赖，仅使用 Node.js 内置模块（含 node:zlib 的 zstd）。项目背景来自一次真实故障：某会话 Subagent 面板 stuck/desync，条目无法移除；作者逆向 DSH session log v4 与 loader 后，把非破坏性修复封装成 CLI，并用回归测试覆盖。
DSH 数据默认在 DSH_HOME（一般为 ~/.dsh，Windows 为 C:\Users\<you>\.dsh），可通过环境变量覆盖。与会话相关的典型路径为：
$DSH_HOME/sessions/<escaped-workspace-name>/<session-id>/session.v4.jsonl.zstd
$DSH_HOME/storages/session_projcache/sessions/<session-id>.json
运行 CLI 需要 Node.js >= 22（启动时会检查 zstd 支持）；可选安装 DSH Desktop 以做「真实 loader」自检，否则可通过 --modules 指向含 @deepseek-ai/* 的 node_modules。
核心功能¶
非破坏性移除 Subagent 条目¶
- 不删除任何日志行，不重排
seq（v4 要求 dense seq）。 - 仅把该会话自身的
subagent/catalog行改写为subagent/catalog-dismissed，并设置ignorable: true。 - 同步把投影缓存里的
subagentCatalog写成合法的空状态（删除会话目录时，DSH 的dsh-chat-manager不会自动删掉对应投影缓存，容易留下孤儿）。
整会话 purge 与孤儿缓存¶
purge：在完整备份后删除会话目录、相关 generation 日志与投影缓存。orphans：列出或删除「会话目录已不存在、投影缓存仍在」的条目。
备份与恢复¶
每次写入前做完整备份；restore --backup <dir> 可按字节还原。
可选插件半部¶
安装 Desktop 插件后，在 Settings → 会话清理诊断 / Session cleanup 打开诊断页：扫描逻辑与 CLI 的 list + orphans 一致，展示各会话 Subagent 条目数、日志大小、缓存标题与孤儿项，并提供可复制的 dismiss / purge / orphans 命令（含一次性清理所有会话 Subagent 条目的命令）。
插件在 DSH 运行期间不会改写已提交的 session 存储（持久化契约要求 dense seq、单写者；投影缓存也无失效 API）。实际变更发生在 完全退出 DSH 之后，走与手工执行相同的 clean.mjs 流程：每会话全量备份 → 结构自检 → 真实 loader 验证。
默认开启「退出时自动清理」：每次启动 DSH 时写入开关状态，并 spawn detached helper（clean.mjs autowait --pid <DSH 进程>），等该 pid 消失后对仍有 Subagent 条目的会话执行与 dismiss --all --apply 相同的流水线，结果写入 auto-report.json。要让它真正跑完，需完全退出 DSH（仅关窗口可能仍在后台运行），等待 helper 完成后再重新打开。
安装与启用¶
作为 DSH Desktop 插件（可选）¶
在插件管理器中添加（任选一种来源，安装后需完全退出并重启 DSH）：
dsh plugin --profile desktop add dsh-agent-clean
dsh plugin --profile desktop add github:PolitaryMonicy/dsh-agent-clean
dsh plugin --profile desktop add /path/to/this/repo
卸载：
dsh plugin --profile desktop remove dsh-agent-clean
若诊断页出现「宿主返回 HTTP 404」，说明 host 半部未加载，可检查 dsh --profile desktop --dump-config 中的插件项，以及 Windows 上 %TEMP%\dsh-agent-clean-host.log。
package.json 中声明的 DSH 引擎要求为 dsh >= 0.2.0-rc.1；许可证为 MIT（npm 包版本资料中为 1.3.7）。
独立 CLI¶
无需 npm install。从 GitHub 页面 Code → Download ZIP 解压后，在仓库根目录执行（三选一）：
node clean.mjs list
chmod +x clean.sh
./clean.sh list
Windows 可用 clean.cmd list。包装脚本会依次查找 %DSH_NODE% / $DSH_NODE、PATH 上的 node 或常见安装路径。
典型用法¶
默认不带 --apply 时为 dry-run，确认输出后再加 --apply 写入。
| 命令 | 作用 |
|---|---|
list [--workspace <substr>] |
列出会话、标题、日志大小及各会话 Subagent 条目数 |
dismiss --session <id\|prefix> [--apply] |
非破坏性移除指定会话的 Subagent 条目 |
dismiss --all [--workspace <substr>] [--apply] |
对多个会话执行同样操作 |
purge --session <id\|prefix> [--apply] |
备份后删除整会话及关联缓存 |
orphans [--apply] |
列出或删除孤儿投影缓存 |
restore --backup <dir> |
从备份目录还原 |
示例：先查看，再对单个会话应用 dismiss：
node clean.mjs list
node clean.mjs dismiss --session <session-id或前缀> --apply
清理所有会话的 Subagent 条目（与插件退出后自动清理使用的逻辑一致）：
node clean.mjs dismiss --all --apply
适用场景与注意¶
适合谁： 会话 Subagent 面板异常、条目无法清除；需要批量 dismiss 或删除整会话；升级或迁移后留下无对应会话目录的投影缓存。分类落在 admin-security，属于对本地 DSH 数据的管理操作，而不是业务逻辑插件。
权限与安全： CLI 以你当前用户权限读写 DSH_HOME；插件 host 路由与 detached helper 同样在本地运行。安装前应阅读仓库源码与 MIT 许可证，确认可接受对会话文件的改写范围；生产或重要会话务必先 dry-run，并保留备份目录直至确认 UI 与 loader 均正常。
操作习惯： 插件说明强调「先 dry-run、先备份」；改完会话后需完全退出 DSH 再开，否则内存中的投影缓存仍可能是旧值。若关闭自动清理开关，诊断页给出的命令与手工 CLI 一致。
更完整的中文说明见仓库 README.zh.md。
链接¶
- 社区目录页：https://www.skillhub.cn/plugins/PolitaryMonicy/dsh-agent-clean
- 源码与文档：https://github.com/PolitaryMonicy/dsh-agent-clean
DSH 社区插件目录由 SkillHub 等站点独立维护，与 DeepSeek / 幻方无官方从属关系；选用插件时以仓库 README 与本地自检为准。
