mrzhangkris/dsh-session-pruner

dsh-session-pruner

DSH 会话生命周期管理插件 — 全类型会话生命周期管理：one-shot 完成即归档、可续子代理与主会话闲置归档、容量保底、连带清理 projcache 缓存。从源头杜绝会话库堆积导致的卡顿。

每类会话都有明确的归宿：跑完的一次性子代理自动归档、闲置的可续子代理/主会话归档、总量超限按优先级回收。先归档（可恢复）再到期删除，GUI 30 秒内自动同步，全程面板配置、热加载生效。

English · Apache-2.0 · npm · npm version · 更新日志

背景

DSH（DeepSeek Harness）的 session_projcache.json 缓存每个会话的完整投影（token 统计、context 压力等），且存储后端每次写入都全量序列化 + 原子替换。当会话库堆积上千个子代理会话时：

- 缓存膨胀到 100MB+，每次 checkpoint 全量重写 → 主进程 CPU 250%+
- 单线程事件循环被占满 → 所有会话加载卡顿，甚至 GET / 超时

管理会话生命周期（本插件）是治本：会话不堆积 → 缓存条目不产生 → 卡顿不复发。

功能：全类型生命周期

| 会话类型 | 触发 | 动作 | 默认 |
|---|---|---|---|
| one-shot 子代理 | subagent/end / agent/disposed 事件（+ 宽限） | 秒级归档（事件驱动） | 事件 + 3 分钟宽限 |
| continuable 子代理 | 闲置超过 N 天 | 归档（可恢复） | 关闭（0 天） |
| 主会话（main） | 闲置超过 N 天 | 归档（可恢复） | 关闭（0 天） |
| 任意类型 | 总量超过容量保底 | 按「one-shot → continuable → main」+ 最旧回收 | 400 个 |
| 归档目录 | 保留超过 N 小时 | 物理删除 | 24 小时 |

行为说明（v0.2.3+）：one-shot 子代理统一按 oneShotMinAgeMinutes（默认 3 分钟）闲置阈值归档，有/无 end-seed 阈值一致。早期版本中「未写 end-seed 的 one-shot 需闲置满 1 小时才归档」的兜底已移除。

归档机制（可恢复）

被清理的会话先移入 ~/.dsh/sessions-archive/（保留 工作区/会话ID 结构）——GUI 立即消失（列表只读 sessions 目录），但文件还在，可手动恢复：

恢复：mv 回 sessions 目录
mv ~/.dsh/sessions-archive// ~/.dsh/sessions//

⚠️ 恢复后请立即 pin（或打开）该会话——打开前它不受 live 保护，
一个扫描周期内若命中闲置判定（如 one-shot 超阈值、main 超闲置天数）
会被再次归档。把会话 ID 加入设置卡片的「Pin 白名单」即可。

也可选「直接删除」（不归档，不可恢复）。

安全保护（双保险）

- 运行中的会话绝不动：live 会话（内存 session store 里还挂着、被打开/加载中）跳过——且 live 检查 fail-closed：store 查询异常时视为 live，不确定时绝不删除
- 闲置 = 最后一次日志写入：闲置按会话日志文件 mtime（最后写入时刻）判定，而非目录 mtime——DSH 追加写 session.jsonl.zstd，活跃会话的 mtime 持续刷新，永不被误判闲置
- one-shot：完成的一次性子代理统一按 oneShotMinAgeMinutes 闲置阈值归档（有无 end-seed 同阈值）；容量保底额外跳过缺 session/end-seed 的会话
- 主会话默认不参与容量回收（可配置）
- 单点失败隔离：每个动作独立 try/catch

工作原理

双轨触发（事件为热路径，磁盘为权威）
┌─ 事件驱动（秒级）：subagent/end + agent/disposed
│     ├─ 500ms 批窗口合并风暴 → oneShotMinAge 宽限复查
│     └─ 单会话判定（内存优先，磁盘只解压一个）→ 归档
└─ 定时对账（兜底，默认 60min）
├─ pruneArchive：归档目录超期物理删除
├─ 遍历 ~/.dsh/sessions// 解压会话日志（系统 zstd，多帧）
│     ├─ origin: main | subagent       （会话头）
│     ├─ mode: one-shot | continuable  （subagent/descriptor 事件）
│     └─ ended: 是否含 session/end-seed
├─ one-shot 闲置超阈值 ──→ 归档（archiveMode）
├─ continuable/main 闲置 N 天 ──→ 归档
├─ 总量 > cap ──→ 按优先级+最旧 归档（跳过运行中/live）
└─ 每次归档连带：删 projcache 行 + workspace 记账

GUI 同步双轨（变更驱动为主，全量兜底为辅）：
- dirty-flag（主路径）：host 每次归档写内存变更日志（单调 seq）；client 每 3s
轮询 /plugins/dsh-session-pruner/archived，只有有变更才发 refreshList()
+ refreshSubagents()——侧边栏/任务管理面板秒级一致，无变更零 RPC。
- 全量兜底：client 每 uiRefreshSeconds 秒刷新两套数据源——主会话列表
refreshList() + 各父会话子代理目录 refreshSubagents()（dirty-flag
失效（host 旧版/路由不可用）时兜底，无需刷新页面）。

安装

从 npm（推荐）

dsh plugin --profile web add dsh-session-pruner

从源码（开发）

dsh plugin --profile web add /path/to/dsh-session-pruner

安装后重启 dsh web 生效（launchctl kickstart -k gui/$(id -u)/com.deepseek.dsh-web）。

配置（设置面板，热加载）

设置面板

安装后打开 设置 → 插件配置 → 会话生命周期管理 卡片，10 项配置保存即热加载（无需重启）。常用 6 项默认可见，4 项低频兜底收在「高级设置」折叠区（高级项有未保存更改时折叠标题会提示）：

| 字段 | 默认 | 说明 |
|---|---|---|
| 扫描间隔（分钟） | 60 | 对账兜底周期（事件驱动为主路径） |
| 容量保底（会话数） | 400 | 超限按优先级+最旧回收 |
| 界面兜底刷新间隔（秒） | 30 | dirty-flag 为主（3s 变更检测），此为全量兜底 |
| 归档保留（小时） | 24 | 归档目录到期物理删除 |
| 归档方式 | 归档 | 归档（可恢复）/ 直接删除（不可恢复） |
| 可续子代理闲置归档（天） | 0 | 超过 N 天未活动归档，0 = 关闭 |
| 主会话闲置归档（天） | 0 | 超过 N 天未活动归档，0 = 关闭 |
| 超限时清理主会话 | 关 | 容量超限时 main 参与回收 |
| one-shot 闲置归档阈值（分钟） | 3 | 所有 one-shot 闲置超 N 分钟即归档（有/无 end-seed 统一） |
| Pin 白名单（每行一个会话 ID） | 空 | 名单内会话永不自动清理（恢复会话后建议立即 pin） |

卡片展开后还有实时状态行（30s 轮询）：归档数量与最早到期时间、会话总量（含超限提示）、最近一轮清理数量与时间、已固定数量。

环境变量（兜底，面板配置优先）：DSH_SESSION_PRUNER_INTERVAL_MS / _MAX / _CLEAN_MAIN / _ARCHIVE_HOURS / _ARCHIVE_MODE / _CONTINUABLE_IDLE_DAYS / _MAIN_IDLE_DAYS / _ONE_SHOT_MIN_AGE_MINUTES / _PINNED_IDS（逗号分隔）。

日志

输出在 guard 的 server-.out.log：

[dsh-session-pruner] armed: interval=60min cap=400 cleanMain=false
[dsh-session-pruner] hot-reloaded: interval=60min cap=400 ... contIdle=0d mainIdle=0d pinned=0
[dsh-session-pruner] archived a1b2c3d4 (subagent/one-shot) one-shot idle cache=true
[dsh-session-pruner] archive pruned: 2 expired

cache=true/false 表示 projcache 缓存行是否连带清理成功。

测试

npm test               # 回归套件：审计 PoC 校验 + 完整 e2e（隔离的临时 DSH_HOME）
node test/dry-run.js   # 只读扫描全库，验证识别逻辑（不删除）
node test/e2e.js       # 构造 fake one-shot 会话，验证真实清理链路
node test/poc-audit.js # 审计回归：ended 误判 / 双源漂移 / 归档孤儿 / pin 拦截

实现要点

- 多帧 zstd：DSH 会话日志是多 zstd frame 拼接（append 写入），Node zlib 只解单帧，插件调用系统 zstd 命令（macOS: brew install zstd）
- 缓存行删除：storageDomain.get('session_projcache').table('sessions').delete(id) 走官方写链（原子持久化 + 内存同步）
- workspace 记账：归档时同步从 workspace 域移除 sessionId，数据源与磁盘一致
- 零捆绑依赖：运行时模块（@deepseek-ai/dsh-settings、schemastery）由 DSH 宿主提供，插件自身不携带依赖
- 面板与热加载：installSettingsSection + 手写 client 卡片（__ModuleLoader__ bundle），onChange 即时重排定时器

开发文档

- docs/DEVELOPMENT-GUIDE.md — DSH 插件开发实践指南（架构、Host/Client、设置面板、部署运维、坑与解法），为后续插件开发打基础
- docs/DESIGN.md — 设计决策与理由（三层策略、双轨触发、fail-closed 安全矩阵、关键不变量）
- docs/TESTING.md — 测试矩阵、验证金字塔（V0/V2/V3）、发布 checklist
- docs/PROJECT-STATUS.md — 项目状态快照与 backlog，给新贡献者/新会话

已知限制

- 完成事件丢失时（如 host 中途重启），已完成的 one-shot 子代理要等下一轮对账扫描才发现——最坏一个 intervalMinutes（默认 60 分钟）
- mv 恢复的会话在打开前不受 live 保护——请 pin 住度过窗口期（见「归档机制」）
- 依赖系统 zstd 命令
- 根治性修复在上游：projcache 陈旧会话淘汰 / storage-json 增量写，见 deepseek-harness Discussion #1550

许可证

Apache-2.0