会话清理 Winnie-0721/dsh-dialogue-cleanup

dsh-dialogue-cleanup

English · 简体中文

在运行中的 DeepSeek Harness Web 界面里删掉会话 —— 不用重启，也不用离开当前窗口。
会话行 ... 菜单里一项做单条删除，另有一页批量管理面板挂在设置页里。

安装 ·界面 ·实现 ·发布流程 · Releases

为什么会有它

一句话定位：删会话就该真的删掉。 DeepSeek Harness 把一条会话同时放在四个地方 ——内存 live 条目、工作区记录、注册表残留（pin / archive）、以及磁盘上的目录。只清掉其中一处，留下的就是一行幽灵会话、一条过期的工作区记录，或者一个还在悄悄占磁盘的目录。
下面每一条，都是这个定位的具体落实：

- 一个不可逆操作，只实现一次。 删除逻辑在宿主（lib/service.js 的 deleteSession），由两个薄适配层通向它 —— HTTP 契约与 slot UI —— 因此单条删除与批量删除不可能各自漂移。
- 运行中的会话是「拒绝」，不是「猜」。 deletable 由宿主判定，UI 不去猜；宿主会拒的，界面根本不给选。
- 已归档默认仍然显示。 归档不等于删除：归档会话照样占磁盘，默认藏起来恰好会藏掉你想清理的那些。
（官方侧栏默认隐藏；这里是三选一 —— 隐藏已归档 / 全部对话 / 仅显示已归档，且默认显示已归档。）
- 空会话默认隐藏（照官方侧栏）。空会话 = 从未收到过任何用户消息的会话：日志只有五个初始化事件（约 588 字节），既没有 user/message 也没有 session/title，本来就无标题可显示。
它们数量往往远多于真会话（某宿主 254 条里 199 条），一行一条正是过去把面板刷成一片 （无标题） 的原因。官方侧栏 sessionVisible() 写的是
if (session.blank && session.id !== current) return false;。这里是三选一 ——
隐藏空会话 / 全部 / 仅显示空会话，默认隐藏；另给两个显式档位，是因为清理磁盘才是本插件的职责，空会话仍需能被批量删掉。列表返回 blank: { filter, total, hiddenInView } —— total 是全库口径（同 archived.total），hiddenInView 是本视图在其它筛选生效后实际藏掉的条数。条数直接写在下拉框自己的选中文字里（隐藏空会话（7 条）），所以数字永远描述用户正在看的这个列表，而且同一件事只在一处出现 —— 不再另起一条「已隐藏 N 条」的常驻横条把下拉已经说过的话再说一遍。一键即可切换档位，任何东西都不会「悄悄消失」。
- 子代理行明确标注。 官方侧栏把 origin: 'subagent' 的行整个藏起来，所以一旦这些行出现（kind = 子代理 / 全部），每一行都会显式打上徽标 —— 子代理会话绝不能看起来像普通对话。
- 它如实汇报做了什么。 结果行给出 成功 / 失败 / 降级 / 删掉的目录数，每条失败原因原样保留。
摘不掉 live store 条目时，插件报 detached: false，而不是假装成功。
- 错误码是语义正确的。 与上游包（永远回 200）不同，这里用真实状态码： 400 / 403 / 404 / 405 / 409 / 429 / 500。

界面速览

确认框：不可逆，并且明说。 只有两条关闭路径 —— 显式「取消」按钮，或 Esc。
点击遮罩故意不关闭：一次误点不该让你损失一次确认机会。

这个浮层是原生 + showModal() 驱动的，因此进入浏览器的 top layer，能盖在打开它的设置面板之上（普通定位元素做不到）。同时白送真正的焦点陷阱与正确的 Esc 语义，而且不需要把 DOM 挂到组件树之外。

批量面板（挂在设置页） —— 搜索、项目 / 状态 / 会话类型 / 归档四组筛选、排序、分页，以及逐行状态徽标。上面截图里的徽标（空闲 / 运行中 / 子代理 / 已归档）来自真实渲染输出： 运行中 的行不可勾选。

两张截图都由 scripts/render-shot.mjs 从真实组件树 + 真实 CSS 生成，再用无头 Edge 栅格化 —— 不是手画的示意图；但也不是在运行中的 GUI 里拍的照片，详见下面的已知限制。

快速开始

dsh plugin --profile web add dsh-dialogue-cleanup

1. 单条删除 —— 鼠标移到侧栏的会话行，打开 ... 菜单选 删除会话 （注册在 order: 500，紧跟官方 archive 项 = 400 之后）。确认框弹出后确认，即清掉 live 条目、工作区记录、注册表残留与磁盘工件。
2. 批量删除 —— 打开 设置 → 对话清理。勾选若干行（或「全选本页可删除项」），一次请求删完。
3. 宿主半改动需要重启 DSH 进程；客户端半不需要（见 docs/RELEASING.md 的表）。

兼容 DSH 0.2.0-rc.2。npm 包与 GitHub Release 一起发布；版本号规则与发布链路见 docs/RELEASING.md。

它怎么实现的

一个 npm 包同时装两半，按官方插件规范装进宿主：

- 宿主半（仓库进程） —— lib/index.js 是 Cordis 函数插件，只具名导出 name / inject / apply；它注册一条 ctx.webServer 前缀路由，删除实现全部留在 lib/service.js。磁盘删除与路径约束在 lib/artifacts.js，审计在 lib/audit.js。
- 客户端半（浏览器） —— client.js，单文件 bundle，经
window.__ModuleLoader__.load({ id, factory }) 注册，除 require("react") 外零依赖。
- 两个入口都是官方 slot，都不碰 DOM：
- sidebar.workspaces.session.menu.item，order: 500 → 单条删除那一项。
- settings.section（id: dialogue-cleanup，order: 25，排在官方
account(-10) / general(0) / models(10) / plugins(15) / agent-presets(20) 之后）
→ 入口和面板。一个注册项 = 设置里的一页，内容渲染在设置面板的内容列里。
- 面板因此不需要 layout 服务，也不往 main / sidebar 抢位置 ——少一个可选依赖、少一处降级分支。
- 样式表跟着组件走。 菜单项把 渲染在自己的树里 （这就是本项目自查发现的 H1：那一行原本完全没样式，因为样式表只在设置页路径上注入过）。

删除的六个步骤

1. 拒绝运行中的会话 —— 409 refused。
2. 摘掉 live store 条目 —— 否则删掉的会话会以幽灵行留在界面上。
3. 清理工作区记录 —— 只统计真正摘掉的那些工作区。
4. 清注册表残留 —— pin / archive 记录，走公开的幂等 API。
5. 删除磁盘工件 —— <DSH_HOME>/sessions/<project>/<sessionId>，外加派生的投影缓存。
每个目录真正 rm 之前还会再判一次运行态（见下）。
6. 写一行审计 —— <DSH_HOME>/logs/dialogue-cleanup.jsonl。

为什么第 5 步要「再判一次」

第 1 步判定到第 5 步真正删除之间存在时间窗。窗口内会话可能开始运行，那就删掉了一个正在用的会话 —— 不可逆。

DSH 本身有内核级会话写锁（SessionWriteLease，Windows 命名信号量 / POSIX fd 锁），但它没有暴露给插件（唯一外部表现是 resume 时的 session/writer-held 错误码）。
所以本插件拿不到原子互斥，只能采用公开 API 下最保守的策略：在每个 rm 之前紧贴地再判一次运行态，把窗口从「整个事务」压到「单次探测 → rm」。
二次确认判定 running 或状态不可知时拒绝删除该目录，并如实进 degradations （step: "preDeleteRecheck"），绝不静默当成 idle 删掉。

残余风险如实说明：窗口被压到单条语句级，但不为零。彻底消除需要宿主把写锁挂到公开服务上。详见 docs/删除安全残留分析.md。

删除是不可逆的

没有回收站、没有撤销。确认框里明说这一点，并且只有两条关闭路径（显式「取消」或 Esc）。
运行中 的行不可勾选 —— 宿主会拒的，界面根本不给选。

批量删除部分失败时怎么重试

批量结果是逐条的，不会因为一条失败就整批回滚。返回里有：

| 字段 | 含义 |
| requested / duplicates / total | 你提交了几条 / 其中重复几条 / 实际处理几条（重复 id 已去重） |
| ok / fail | 成功 / 失败条数 |
| complete / degraded / noop | 完整成功 / 成功但有降级 / 什么都没删到 |
| allComplete | 整批全绿才为 true；任一子项有降级即 false |
| outcomes[] | 逐条：outcome（deleted/noop/refused/blocked/failed）+ retryable |
| retry[] | 只含需要重试的 id（失败或降级的），已完整成功的不在内 |
| degradations[] | 逐条降级明细（sessionId + step + reason） |

重试方法：把 retry 数组原样作为下一次 sessionIds 提交即可 ——不要重跑整批，那样会把已完整成功的条目再做一次无意义的操作。
refused 的条目要先在界面上关掉那个会话（或等它跑完）再重试； noop 的条目不需要重试（它本来就不存在）。

HTTP 契约

| 方法 | 路径 | 用途 |
| POST | /api-ext/dialogue-cleanup/delete | { "sessionId": "..." } 删一条；{ "sessionIds": [...] } 批量删（宿主逐条走同一个 deleteSession，返回逐条结果） |
| POST/GET | /api-ext/dialogue-cleanup/list | 会话行，带 deletable / blockedReason / classification / titleState |
| GET | /api-ext/dialogue-cleanup/status | 能力、配置、运行时路径 |

信封：{ ok: true, value } / { ok: false, error: { code, message, hint? } }。

每行带 titleState，用来区分 title 为空的四种不同成因。把它们压成一句「（无标题）」正是一屏看起来像坏了的原因：

| titleState | 含义 | 重试有用吗 |
| ready | 有标题 | — |
| blank | blank: true —— 从未收到过用户消息（日志只有初始化事件） | 没用，它本来就不该有 |
| empty | 有内容，但宿主明确答复没有标题（例如只跑了 turn/start → turn/end 的子代理会话） | 没用 |
| unread | 有内容，本次没读到（超出 titleLimit 预算，或读取失败） | 有用 |

empty 靠 titleConfirmed 集合支撑，只收宿主成功答复过的 id，所以「超预算」或「这一批 RPC 失败」永远不会被伪装成「本来就没有标题」。客户端据此渲染三种不同占位文案，并对 empty 与 unread 都印出会话 id（两者都是真会话，而删除不可逆），blank 则不印（实测 254 条里 199 条是空会话，铺满 UUID 会把真会话淹掉）。

配置

所有可调项都在插件 Config（lib/config.js）里，因此用户的 patch 层能跨升级保留。
注意：匹配到的 override 会整体替换 config —— 你在意的字段要全写上。

| 键 | 默认 | 含义 |
| maxBodyBytes | 65536 | 请求体上限（上游：1 MiB） |
| readTimeoutMs | 10000 | 读体超时（上游：无） |
| audit / auditPath | true / null | 审计日志；null → <DSH_HOME>/logs/... |
| rateLimitPerMinute | 60 | 每分钟删除请求配额（一次批量算一次）；0 关闭 |
| requireIdleSession | true | 运行中会话拒绝逻辑的安全阀 |
| stopIdleAgent | false | 见下方「已知限制」 |
| matchAlternateIdSpelling | true | 带守卫地探测另一种 session- 拼写 |
| removeProjectionCache | true | 同时删掉派生的投影缓存 |
| clearRegistryRecords | true | 解除 pin / archive 残留 |
| confirmInUi | true | UI 确认（宿主不信任它） |
| announceRemoval | true | 删除后广播 session.removed，让别的视图同步移除该行 |
| titleCacheTtlMs | 300000 | 标题折叠缓存 TTL；0 关闭 |
| titleFetchConcurrency | 8 | 折叠标题时的分片并发 |
| titleLimit | 100 | 每页最多为多少行折叠标题；0 完全跳过标题读取 |
| titleSearchLimit | 40 | 搜索时单独的标题预算（与 titleLimit 独立）；预算外如实计入 titles.truncated |
| runningProbeTtlMs | 1000 | 运行态快照复用的时长。把批量删除从「O(N) 次全量清单调用」变成 O(1)；0 则逐条重探。注意：删除前的最后一道判定不吃这个缓存（见「删除的六个步骤」） |
| auditMaxBytes | 4194304 | 审计文件轮转阈值（4 MiB）。超过就把当前文件改名为 .1，旧的依次后推；0 = 不轮转 |
| auditRotateKeep | 3 | 轮转保留的历史份数（不含当前文件）。超出该份数的最旧一份会被删除 |

审计日志在哪、留多久

默认写到 <DSH_HOME>/logs/dialogue-cleanup.jsonl（DSH_HOME 通常是 ~/.dsh），一行一条 JSONL。可用 auditPath 改位置，但路径会被规范化并校验必须落在 <DSH_HOME> 之内 —— 越界配置会被拒绝写入并如实上报（audit.ok=false），不会静默写去别处。

保留策略：当前文件超过 auditMaxBytes（默认 4 MiB）就整份改名为 .1， .1→.2、.2→.3，超出 auditRotateKeep（默认 3 份）的最旧一份删除。
所以默认最多占用约 4 份 × 4 MiB。轮转用 rename 搬走整份，不会截断正在写入的日志；轮转失败时不阻断写入（日志继续长总比丢审计好），只把 rotateError 作为降级返回。

字段最小化：一行只写诊断必需字段（时间 / 操作 / actor / phase / sessionId / 结果码 / 文件与缓存计数 / 耗时 / 降级步骤）。整份 runtime、会话标题、全量路径数组 都不写 —— 旧实现把那些都塞进一行，实测 910 B/行；现在实测 196 B/行。
需要明细时按 sessionId 去宿主日志里查。

审计失败与删除结果是两件不同的事实：audit.ok=false 只表示留痕失败，会进结果的 degradations（step: "audit"），但不会把已经执行的删除伪报成回滚。

已知限制

以下都是对着真实运行时测出来的，与上游包的假设不同。如实写出，而不是粉饰：

- 没有公开的「停掉空闲 agent」接口。 公开的 Agent 类型是 { readonly id: SessionId } ——没有 status、没有 ctx。因此上游的 agent.status === "running" 与
agent.ctx.fiber._unload() 都不可依赖（_unload 是 Cordis 的私有方法，这里刻意永不调用）。
「是否在跑」来自公开的 sessionController.list() → SessionSummary.running。
仍挂着 agent、又无法安全停掉的会话会被拒绝，且界面会说明原因。
- 摘 live 条目是尽力而为。 公开的 sessions 服务提供 create/prepare/enter/announce/flush/get/list/fork —— 没有公开的 detach。
插件先试公开方法，再试内部 store 条目；两者都拿不到时如实报 detached: false，而不是宣称成功。
- 磁盘上并存两种 id 拼写。 在同一个 <DSH_HOME> 里观察到： ...\<uuid>\session.v4.jsonl.zstd 与 ...\session-<uuid>\session.v4.jsonl.zstd。
按精确 id 拼接永远删不掉带前缀的那一半。本插件只在能确认候选不是另一个真实会话时才探测另一种拼写；没有这种证据就什么都不删，宁可漏删也不误删邻居。
- 截图是真实渲染输出，不是在跑着的 GUI 里拍的照片。 它们来自真实组件树 + 真实 CSS，无头栅格化；主题令牌固定为浅色，行数据是演示用的假会话。
面板在真实主题下的样子，本仓库没有拍过。

开发与验收

全套门禁：node --check + 契约/渲染/发布等回归套件
node scripts/run-tests.mjs

只跑发布门禁（不改版本、不打包、不发布） pwsh -File scripts/release.ps1 -LocalOnly

用真实组件树重新生成两张文档截图
node scripts/render-shot.mjs

不要写成 node --test "test//.test.mjs"：glob 展开是 Node 22+ 才有的，而 engines.node 声明 >=20。在 Node 20 上这句会直接报 Could not find '.../test//.test.mjs'。scripts/run-tests.mjs 由 Node 自己枚举 test/.test.mjs 再交给 node --test，三个版本、两个平台行为一致（CI 已覆盖）。

当前共 302 条测试 / 18 个文件（其中 3 条是平台相关用例，每个平台实际跑 299 条）：

| 套件 | 覆盖 |
| contract.test.mjs | 宿主 ↔ 客户端契约与 slot 声明（最大的一套） |
| service.test.mjs | deleteSession 端到端行为与否决路径 |
| fault-injection.test.mjs | 逐步骤故障注入：磁盘/内存/工作区/审计/通知分别失败时不得冒充完整成功；含 §4.1 删除前二次确认竞态、§4.2 身份查询失败可观测、§4.3 链接跳过可观测、对偶拼写红线、junction 越界（静态 + 竞态） |
| isolated-integration.test.mjs | 隔离环境破坏性集成：完整副作用清理、running 零改动、真实子进程 SIGKILL 中断后重启重跑、批量部分成功后重试 |
| batch-semantics.test.mjs | 批量语义：去重、deleted/noop/refused/blocked 可区分、精确 retry 清单、allComplete |
| audit.test.mjs | 审计：字段最小化、截断、轮转（含不截断正在写的日志）、并发、路径不可写/越界、禁用、配置边界 |
| perf-regression.test.mjs | 查询性能不退化的语义护栏：冷/热结果逐字段一致、单请求不重复读标题、N 并发只读一次、失败可恢复、指标不泄露标题与 cwd |
| client.test.mjs | 注册面、id、不跨包 require |
| render.test.mjs | 组件真的被渲染（React 替身）；titleState 四种占位必须两两可区分，empty 不得复用 unread 的措辞；凡是有默认值的筛选维度（archived / kind / blank）都必须真的进到请求 URL —— 只在本地 state 里改的下拉框看着完全正常，却什么都筛不到；空会话条数必须写在下拉框自己的文字里（只此一处、用 hiddenInView、不得再有重复的提示横条） |
| artifacts.test.mjs | 路径约束、符号链接拒绝、另一种拼写的守卫、isRealPathInside 正反断言 |
| session-id.test.mjs | id 校验（不含分隔符与点号） |
| eol.test.mjs | 行尾，以及每个被跟踪文件都被 git 声明为 eol=lf |
| release-workflow.test.mjs | OIDC 发布结构（反向断言：pack-release.yml 不得自带发布步骤） |
| ps-script.test.mjs | Windows PowerShell 5.1 的 BOM / 编码坑 |
| project-identity.test.mjs | 一行的项目身份是同一个字段：显示、筛选、下拉选项全部由它派生（有 cwd 用 cwd，否则退回 workspace 路径）；大小写/分隔符变体合并成一个选项 |
| transaction-boundary.test.mjs | 删除与并发的交界：标题读取在途、批量里一条被拒 + 一条非法 id、审计在途/失败、投影缓存三态（正常 / 符号链接 fail-closed / 根路径异常） |
| title-async-prototype.test.mjs | 原型，不是生产路径：docs/TITLE-ASYNC-DESIGN.md 的参考合并状态机，对「可控闸门」的假宿主验证（首屏不阻塞、不卡 pending、旧 token 被拒、已删行不复活、empty ≠ unreadable） |
| classification.test.mjs | 会话分类三态：只出现在摘要链路上的行必须回成 unknown，绝不能再算主会话；证据只累加不相减（字段缺失不是反证）；另有一条 handler 级用例钉住 GET /list?kind=unknown 穿透 HTTP 白名单 |

另有 test/integration-real.mjs（只读真实 DSH 检查，需要活着的宿主，故不并入 .test.mjs 套件）与 test/mutate-tokens-official.mjs（变异测试，要求 survived=0）。

其中两条是因为对应的 bug 真的发出去过、之后才被发现才补上的：

- eol.test.mjs —— 第一次发版时，CI（pnpm pack）与本地（npm pack）打出的字节不一样： CI 里的 icon.svg 与 LICENSE 是 CRLF，因为 .gitattributes 只写了 * text=auto，而 GitHub 的 Windows runner 默认 core.autocrlf=true。
这条测试的第一版漏掉了它（它扫描的是硬编码扩展名清单，于是 *.svg 与没有扩展名的 LICENSE 完全不在视野里）；现在改为扫所有被 git 跟踪的文件，并用 git check-attr 读实际生效的属性。修的过程中还顺带抓出了 .gitignore。
- release-workflow.test.mjs —— OIDC 信任绑定在工作流文件名上，而「把发布步骤再写一遍」正是让另一个仓库连续两次发版失败的那个 bug。
见 docs/RELEASING.md。

仓库结构

| 路径 | 内容 |
| lib/index.js | apply(ctx, config) —— 组装并注册宿主路由 |
| lib/service.js | deleteSession —— 唯一的删除实现 |
| lib/artifacts.js | 磁盘删除 + 路径约束 |
| lib/http.js | 同源检查、请求体上限、状态码 |
| lib/config.js | Config schema 与默认值 |
| lib/audit.js | JSONL 审计 |
| client.js | Web 客户端半：slot 注册（菜单项 + 确认框 + 设置页 section） |
| cordis.patch.yml | 插入宿主半，inject: [webServer] |
| .github/workflows/ | pack-release.yml（标签 → 门禁 → 打包 → GitHub Release）与 publish-npm.yml（唯一的 npm 发布实现，由同一次标签推送并列触发，不经 workflow_call 复用） |
| docs/RELEASING.md | 版本号规则与发布链路 |
| scripts/release.ps1 | 版本递增 + 门禁（+ CI 打包发布） |
| scripts/render-shot.mjs | 重新生成文档截图 |
| test/ | 302 条回归测试 |
| VERIFICATION.md | 完整验收报告 |

关于上游

这是对 npm 包 dsh-session-cleaner@1.0.2 能力边界的合规重写，不是照抄它的实现。
上文「已知限制」里的每一条，都是与它的假设不同的地方。

许可

MIT