归档会话管理huahai0202/dsh-better-archive

DSH Better Archive

为 DeepSeek Harness (DSH) Web GUI 提供完整、可管理的已归档会话视图。

dsh-better-archive 在 DSH 的设置区域和会话区右侧的 Sidebar 各提供一个「已归档」入口（右侧是 archive 页面类型，从引导页的入口胶囊打开）。归档会话时右上角会弹出可撤销的提示条。你可以查找和筛选归档会话、恢复会话，或按需永久删除不再需要的归档记录。

界面

全部为深色模式。左上起：右侧 Sidebar 的「已归档」tab、设置区的「已归档」一节、右侧 Sidebar 的引导页（入口胶囊）、归档提示条。

| 右侧 Sidebar「已归档」 | 设置区「已归档」 |
| :---: | :---: |
|  |  |
| 引导页入口胶囊 | 归档提示条 |
|  |  |

功能

- 在 DSH 设置区提供独立的「已归档」页面。
- 在会话区右侧的 Sidebar 提供一个「已归档」页面 tab：以 sidebar://archive 页面类型（kind archive）注册，引导页的入口胶囊打开它，chip 带归档图标，正文在面板窄列里沿用同一套搜索 / 筛选 / 排序 / 删除界面。0.7.0 曾引入的左侧一级页面与侧边导航行已在 0.8.1 移除，设置区与右侧栏是仅有的两个入口。
- 归档会话时右上角弹出提示条，带「查看」（直达右侧 Sidebar 的「已归档」tab）、「撤销」（取消归档）与「关闭」。右侧栏是每会话一份的面，所以当前没有打开的会话时，「查看」会先打开最近的一个会话（一个都没有时由 DSH 新开一个空会话）再打开该 tab。悬停不自动消失。
- 按项目查看归档会话；支持关键词搜索、项目筛选，以及按更新时间或名称排序。
- 一键取消归档。归档集合经由 workspace 快照推送，恢复的会话自动回到会话列表（0.8.3 起不再整表刷新，无列表重排闪动）。
- 支持删除单个会话、某个项目下的全部归档会话，或清空全部归档会话；仍在使用的会话会在重启 DSH 后自动删除。永久删除走 DSH 自己的风险确认：需要先勾选「我已了解」才能按下确认按钮。
- 页面文案跟随 DSH 的语言设置，中英文切换无需刷新页面。
- 界面直接使用 DSH 自身的 UI 组件：弹出菜单是 DSH 的 Menu，永久删除确认是 DSH 的 RiskConfirmation，按钮、图标与卡片沿用同一套基础组件，因此外观、交互、键盘行为与明暗主题都和 DSH 保持一致。

界面实现

浏览器端不自己实现弹层与对话框，而是 require('@deepseek-ai/dsh-client-ui-primitives') 并直接渲染 DSH 自己的组件：

| 界面元素 | 使用组件 |
| --- | --- |
| 排序 / 项目筛选下拉、项目行「⋯」菜单 | Menu（锚点定位、点击外部关闭、Esc 关闭、选中打勾） |
| 排序 / 项目筛选下拉的触发器 | Button（ghost 形状）+ DSH 设置页选择器同款底色 --dsw-alias-bg-module-platform |
| 永久删除确认（单个 / 整个项目 / 全部） | RiskConfirmation（基于 Modal，自带警告图标、勾选确认与「确认按钮在勾选前保持禁用」的门禁） |
| 全部删除、取消归档、图标按钮 | Button（outline / ghost 变体与 sm / md 尺寸） |
| 归档提示条 | 自建外壳（DSH 的 Toast 只支持文字+图标，没有按钮位），取 DSH 的菜单表面、elevation 与「solid」反色药丸配方；内含 IconArchiveOutline20 与 Button |
| 右侧 Sidebar「已归档」tab | ctx.sidebarRightTabs 注册页面类型（kind archive，引导页入口胶囊）+ keyed sidebar.right.pane.tab 正文与 sidebar.right.pane.tab.title chip 图标；正文接收框架注入的 useSessions / useWorkspaces，按面板窄列自适应布局；提示条「查看」经 ctx.sidebarRight.openTab('archive') 打开它。该列每会话一份，因此主视图没有会话时「查看」先经 ctx.uiWorkspace.openSession 打开最近的非归档会话（一个都没有时 startSession 新开一个空会话），再等 seat 挂载后打开 tab；是否有会话打开读会话摘要的 retainedBy.mainView（会话列表快照本身没有 current 字段） |
| 图标 | IconArchiveOutline20、IconTrashOutline16、IconSearchOutline16、IconChevronDownOutline14、IconEllipsisOutline16、IconFolderOpen16、IconCloseOutline16 |

@deepseek-ai/dsh-client-ui-primitives 是 DSH 内核在启动时注入浏览器模块表的基础模块，因此无需在 dsh.client.external 中声明。插件自己的样式只剩下组件无法表达的布局、下拉底色、归档提示条外壳、一个破坏性强调色和滚动条皮肤。

不要用 Button 的 toolbar 变体做普通控件：它画的是 --dsw-alias-button-tool-bar-fill，这个令牌在 DSH 自带主题和第三方主题里都是同一个固定的半透明深灰（rgba(84,85,87,0.5)），叠在任何浅色底上都会变成中灰药丸。它只适合压在深色浮层上的工具栏。

安装
需要 dsh 0.1.5-rc.2+、Node.js 22.19+ 和 pnpm（0.8.5 起不再适配更早的 dsh 版本）。

dsh plugin --profile web add github:huahai0202/dsh-better-archive

安装完成后重启 dsh web。插件会自动加入该 profile 的 dsh.profile.bundles；若未自动加入，请在该数组中添加 "dsh-better-archive"，然后重启 DSH Web。

0.8.8 提示条「查看」不再时有时无：此前它用会话列表快照的 list.current 判断有没有会话打开，而该快照根本没有这个字段——判断恒为 false，「查看」实际从未渲染。现在改读会话摘要的 retainedBy.mainView（DSH 设置外壳判断「是否打开着会话」用的同一个信号）。「查看」同时改为始终可用：右侧栏是每会话一份的面，主视图没有会话时先打开最近的非归档会话（按 updatedAt，优先非空会话；一个都没有时由 startSession 新开一个空会话），再等该会话的 seat 挂载后打开 tab——openTab 在 seat 未挂载时会抛错，所以这一段按 100ms × 50 次重试，超时只记一条警告。

0.8.7 三处收尾。① 取消归档现在可回滚：它会先清掉待删除标记再改写归档集合，此前若集合写入失败，标记已经没了——「重启后删除」的意图被静默丢弃，而删除路径一直有对称的回滚（restoreDeleteState），现在由 restorePendingDeletion 把标记写回，失败依旧如实报出（写回也失败时抛 AggregateError）。② 读取待删除状态不再为每个归档 id 重读一次会话表头：在真实 JSONL 后端里一次表头读取 = 目录扫描 + 解压首行，而页面每次挂载都会问一次这个接口，所以现在按后端在进程内记忆已解析出的会话目录；只有这条读路径记忆，删除路径照旧读表头确认会话文件真的还在——记忆的目录绝不能替代「文件是否还存在」这个判断。③ 客户端不再在每次操作后重取待删除集合，改为按响应增量推进（批量删除中途失败时响应本身就带 scheduled，同样先镜像再报错），顺带消掉「删除已经成功、却因为待删除状态读取失败而弹错」；面板行与提示条「撤销」两个取消归档入口共用同一条缓存更新路径。

0.8.6 修复永久删除后左侧会话列表又冒出该会话、点开提示会话不存在的问题：0.8.3 依赖归档集合来隐藏被删会话，但删除本身会把 id 从归档集合里移走，而浏览器手里的会话列表只在页面加载时拉过一次——于是这一行重新可见，点开却已没有会话文件。现在每次物理删除都补发 DSH 自己的 api-session/removed（api-session-controller 在 session/disposed 上发的同一个事件，浏览器收到后只摘掉这一行），因此无需重拉整张列表。

0.8.5 移除对旧版 dsh 的适配，只支持 0.1.5-rc.2+：Host 侧不再兼容 0.1.2-alpha.1 的 inspect(id) / 表头形 list()（统一走 stat(id) 与快照形 list()）；客户端把 sidebarRightTabs / sidebarRight 声明进激活依赖（取代 0.8.4 的等待重试，从机制上消除激活时序竞态），并移除 toast 阶段字段缺失的回退与各处防御性降级。

0.8.4 修复右侧 Sidebar 的「已归档」tab 在某些重启后消失的问题：sidebarRightTabs 由右侧栏特性在自己的 apply 里提供，包之间的激活顺序没有保证——本插件先激活时一次性检查拿不到服务，整个右侧栏注册被静默跳过。现在注册等待服务出现（有界重试约 12 秒，随插件 fiber 清理），服务就绪立即注册；旧版 dsh 无该服务时依旧降级，其余入口不受影响。（0.8.5 已改由激活依赖声明根治。）

0.8.3 修复取消归档 / 删除后左侧会话列表被整体刷新（字幕式重排）的问题：客户端不再调用 sessions.refresh() 全量重拉会话列表。DSH 的会话树本就订阅并过滤 archivedSessionIds（ui-workspace 的 SessionTree / deriveGroups），Host 侧 registry.setState 推送归档集合变化后，列表会自动把恢复的会话显示回来、把删除的会话隐藏，无需整表重取。

0.8.2 移除右侧 Sidebar pane 里的标题行（「已归档的聊天」标题与「全部删除」按钮）：tab chip 已经显示「已归档」，列表直接以搜索/筛选行开始；整批删除仍可在设置区一节进行，行级删除与项目菜单不变。

0.8.1 移除 0.7.0 引入的左侧一级页面（main 主面板与 sidebar.panellist 导航行），归档管理统一走设置区一节与右侧 Sidebar tab。归档提示条的「查看」仅在当前打开了会话时显示（右侧栏是每会话一份的面），点击直达右侧栏的「已归档」tab；不再有回退到左侧主面板的路径。

0.8.0 新增右侧 Sidebar 的「已归档」页面 tab：会话区右侧的停靠面里可打开一个归档管理页（archive 页面类型，引导页入口胶囊打开它）。正文复用同一份归档列表，按面板窄列自适应布局（12px 内缩 + 搜索/筛选一行 + 列表为唯一滚动区）。归档提示条的「查看」改为打开该 tab（ctx.sidebarRight.openTab）。ctx.sidebarRightTabs 服务缺失（旧版 dsh）时自动降级为不提供该入口，其余入口不受影响。

0.7.7 简化提示条展示逻辑：移除卡片折叠/堆叠机制，多个提示条默认直接纵向平铺展开展示，卡片间距清晰，保留悬停暂停倒计时与独立撤销/查看/关闭能力。

0.7.6 统一提示条宽度与右对齐操作区：提示条改为统一定宽（380px，窄屏自适应），会话标题超长时自适应截断，右侧操作按钮保持对齐；修复因各会话标题长短不一导致折叠时底层卡片左右冒尖、展开时宽度错落参差的问题。

0.7.5 提示条支持多条卡片堆叠与悬停展开：连续归档多个会话时，提示条以卡片层叠方式展示（露出一截底层卡片轮廓），鼠标移入时平滑展开为纵向列表，悬停期间暂停倒计时，各提示条支持独立查看、撤销与关闭。

0.7.4 修复两个提示条问题：启动时不再误弹（工作区列表是异步装载的，之前把装载后的真实归档集合误判成“刚归档”）；提示条改为「停留 3.5 秒 → 0.2 秒淡出 → 卸载」的过渡式消失，悬停会暂停倒计时。

0.7.3 「全部删除」默认是普通按钮，悬停或键盘聚焦时才转为红色，不再常驻一块红色。

0.7.2 修正两个下拉与触发器的对齐：不再把下拉拉伸成等宽三等分（DSH 菜单最小 218px，拉伸越宽落差越明显），改为搜索框自适应占满、两个下拉按内容自适应，菜单锚定边与触发器精确对齐。

0.7.1 修正主面板里内容列没有水平居中的问题。

0.7.0 新增归档提示条与侧边栏一级页面：归档会话后弹出带「查看 / 撤销」的提示条，「查看」跳到「已归档」页，「撤销」直接取消归档；「已归档」同时注册为侧边栏一级入口（main 主面板 + sidebar.panellist 导航行）和原有的设置页一节，两处共用同一份界面。归档的监听基于归档集合的变化，无论从哪里发起归档都会提示。

0.6.2 为纯内部整理 + 一个健壮性修复：4 个路由的 method / 同源 / body / 必填 / 错误处理统一收进一个 registerRoute()；删掉客户端里永远不会触发的 notice 状态；批量删除、读待删除状态、取消归档不再因为某条归档记录找不到会话文件而整体失败（详见「删除行为」）。

0.6.1 修复浅色主题下排序 / 项目筛选两颗下拉在浅色底上显示为中灰药丸的问题：不再使用 Button 的 toolbar 变体（其底色令牌是固定值，不随主题变化），改用 ghost 形状 + DSH 设置页选择器同款的 --dsw-alias-bg-module-platform 底色。

0.6.0 起界面改为直接调用 DSH 内部 UI 组件（@deepseek-ai/dsh-client-ui-primitives 的 Menu / RiskConfirmation / Button 与图标），替换掉此前手写的下拉菜单、对话框与按钮；永久删除改为 DSH 的风险确认流程，需勾选确认后才可执行。同时修复了 0.5.1 中下拉菜单引用了已删除的 ScrollingLabel 导致「已归档」页面渲染失败的问题。这些组件需要 dsh 0.1.5-alpha.1+ 的浏览器模块表，旧版 dsh 请使用 0.5.x。

0.5.0 起适配 dsh 0.1.5-alpha.1：客户端模块系统改为 dsh-client-modules（旧版 dsh-client-runtime 已移除），Host 侧会话存储读取适配 stat(id) / 快照形 list()（仍兼容旧版的 inspect(id) / 表头形 list()）。旧版 dsh 请使用 0.4.x。

更新

通过上述 GitHub 方式安装的插件可使用以下命令更新：

dsh plugin --profile web update dsh-better-archive

更新完成后重启 dsh web，使正在运行的 Host 和客户端加载新版本。

本地开发

dsh plugin --profile web add link:

本地修改后重启 dsh web，以加载最新的插件代码。

提交前可运行以下检查：

node --check lib/index.js
node --check lib/client.js
node --test
npm pack --dry-run

删除行为

永久删除只作用于已归档会话，操作前会要求确认。针对 DSH 0.1.5-rc.2+ 的默认 JSONL 会话存储（冷读走 stat(id)，列表走快照形 list()），插件会删除会话专属目录，同步移除对应的工作区与归档记账，并把这次消失通知给所有已连接的浏览器。

DSH 的归档操作只会将会话从常规列表中隐藏，并不等于终止会话。删除行为取决于会话当前是否仍由 DSH 进程持有：

| 会话状态 | 点击删除后的行为 | 页面状态 |
| --- | --- | --- |
| 冷会话 | 立即永久删除会话目录，并同步移除工作区和归档记录 | 从界面中立即移除不再显示 |
| 当前仍存活的会话 | 写入待删除标记，下次 DSH 启动时自动完成物理删除 | 界面立即隐藏该条目（隐藏状态跨界面重开保持，不闪现；物理删除在下次启动时自动完成） |

对于存活中的会话，插件已记录待删除标记，会在下次 DSH 重启启动时自动执行物理清理；取消归档会同时清掉标记，反悔即恢复。

每次物理删除（立即删除，以及重启时的待删除清理）都会补发一次 api-session/removed。浏览器里的会话列表只在页面加载时拉一次基线，删掉会话文件它并不知道；而这条会话此前之所以不显示，只是因为它在归档集合里——删除又把 id 从归档集合里拿掉了。少了这个事件，被删会话就会重新出现在左侧会话列表里，点开则因为没有会话文件而报「会话不存在」直到刷新页面。api-session/removed 是 DSH 在 session/disposed 上发的同一个事件（dsh-api-session-controller），也在 Host 转发白名单（dsh-api-remotes）里，浏览器收到后只摘掉这一行，不需要重拉整张列表。

批量删除可以同时处理冷会话和仍存活的会话；若中途失败，接口会报告已立即删除和已安排重启后删除的会话，并刷新页面状态。

归档记账可能比会话文件活得更久（会话目录被手工删除、或后端不是 JSONL）。这类条目无法定位，插件不会让它拖垮整批操作：

- 单个删除仍会明确失败并报出该会话，因为这是针对这一条的具体操作。
- 批量删除（整个项目 / 全部）会跳过这类条目、删掉其余可删除的会话，并在响应的 unresolved 字段里列出没能定位的条目，页面会提示还有几条未能删除。这些条目仍留在归档列表里。
- 取消归档不依赖会话文件，因此仍可用它把这类条目从列表里清掉。
- 读取待删除状态会跳过这类条目（它们不可能带待删除标记），并在日志里记录一条警告。

DSH 的内容寻址附件由 DSH 独立管理，因此不会随会话记录一起删除。

开发接口

| 路由 | 方法 | 用途 |
| --- | --- | --- |
| /archived/pending | GET | 查询标记为重启后删除的会话 |
| /archived/unarchive | POST | 取消归档一个会话 |
| /archived/delete | POST | 立即删除或安排重启后删除一个归档会话 |
| /archived/delete-project | POST | 删除或安排删除一个项目的全部归档会话 |
| /archived/delete-all | POST | 删除或安排删除全部归档会话 |
三个删除路由返回 { archived, deleted, scheduled }（archived 为删除后剩余的归档 id，deleted 为已立即删除的数量，scheduled 为已安排重启后删除的 id）。两个批量路由在有条目无法定位时额外返回 unresolved: [{ id, error }]。

目录

dsh-better-archive/
├── lib/
│   ├── index.js        # DSH Host 路由与会话操作
│   └── client.js       # 归档界面（设置区 + 右侧 Sidebar）与归档提示条
├── test/
│   └── index.test.js   # Host 路由与会话操作测试
├── cordis.patch.yml    # Host 挂载配置
├── package.json        # 插件声明
└── assets/             # README 截图

License

MIT