dsh-ui-session-archive

DSH Web GUI 的会话归档管理器插件（双面：host 命令 + browser UI）。

管理已归档的会话：归档 / 查看 / 恢复 / 打开 / 永久删除 / 批量操作。

快速开始

npm 安装（已发布，推荐）：

dsh plugin --profile web add --config.minimumReleaseAge=0 dsh-ui-session-archive

本地源码安装（开发调试，需先构建）：

cd packages/dsh-ui-session-archive
pnpm install
pnpm run build
# 在插件目录内运行，file:$PWD 自动展开为当前绝对路径：
dsh plugin --profile web add file:$PWD   # file: 而非 link:（见下）

安装后重启 dsh web 进程，侧边栏「新会话」下方出现「会话归档」入口即生效。

一键测试流程：本地改代码后，可用仓库内 build-install-restart.bat 自动完成 构建 → 安装（含 file: 安装与 release-age 门禁绕开）→ 重启 dsh web → 校验：

.\build-install-restart.bat            # 构建+安装+重启+校验
.\build-install-restart.bat nobuild    # 跳过构建，仅重装

⚠️ 必须用 file: 而不是 link:：link: 只建 junction、不安装本包依赖，运行时 import 按仓库 物理路径解析（@deepseek-ai/dsh-settings 等解析不到），dsh web 启动即崩溃（ERR_MODULE_NOT_FOUND）。 file: 会把包复制进 profile 的 node_modules 并安装其 dependencies（详见 docs/installation.md）。 Windows cmd 中 $PWD 不会展开（PowerShell / bash 才有效）。在插件目录内用 PowerShell 运行上面的命令即可； 若必须用 cmd，请改用绝对路径（file:<完整路径>）。

能力

| 操作 | 说明 | | --- | --- | | 归档当前会话 | 从侧边栏分组隐藏（DSH 内置能力），日志与槽位保留 | | 查看 | 面板列出全部已归档会话（标题 / 更新时间 / 工作区 / 运行中徽标） | | 恢复 | 取消归档，会话回到侧边栏分组（支持单条与批量） | | 打开 | 直接打开归档会话查看历史 | | 永久删除 | 仅限已归档且非运行中的会话；删除会话日志目录，不可恢复（有二次确认，支持单条与批量；会话目录之外的共享数据不在删除范围） | | 批量操作 | 多选 → 批量恢复 / 批量删除；全选 / 取消全选；批量删除前预览计划（删除 N 个、跳过 M 个受保护会话及原因） |

受保护会话（批量删除时自动跳过并提示原因）：运行中（有未结束回合）、当前正在查看的会话、不在归档集合中的会话。单条删除遇到运行中或当前查看的会话同样拒绝。

限制（摘要）

• 恢复/删除经插件内置 RPC 通道直达 host，无需打开会话（旧版命令代理需当前会话作执行代理，已弃用）；
• 删除仅限已归档且非运行中（无未结束回合）的会话；
• 归档会话仍可能出现在 host 的 session.search（上游行为）；
• 批量删除按单条规则逐一会话执行（受保护项跳过、其余删除），不提供 linxin666 版的全族级联删除与自动归档/删除策略（本包保持轻量 RPC 架构，未引入完整 inventory 数据面）。

原理一句话

DSH 已内置归档集合（WorkspaceRegistry.archivedSessionIds）但无 UI、无 unarchive、无删除 API；本插件 host half 注册全局命令 /session-archive 补齐恢复与删除（桥接 registry 公开写链 + node fs 物理删除），browser half 提供侧边栏入口与归档面板，经插件内置 RPC 通道（connection.rpc）与全局命令联动。详见 docs/architecture.md。

文档

| 文档 | 内容 | | --- | --- | | docs/architecture.md | 双面插件架构、模块职责、数据流、桥接与删除设计决策 | | docs/installation.md | 安装 / 手动挂载 / 卸载 / 生效 | | docs/usage.md | 用户操作指南（归档/查看/恢复/打开/删除）与边界行为 | | docs/protocol.md | /session-archive 命令协议：语法、语义、返回、错误清单、调用示例 | | docs/development.md | 开发者指南：目录结构、构建、扩展点、发布 | | docs/troubleshooting.md | 故障排查：症状 → 原因 → 处理 | | ../../docs/PACKAGE-TEMPLATE.md | 本仓库插件包统一规范 |

测试

node test/session-archive-delete.test.js  # 删除路径行为（current 保护/队列原子化/注册表优先）（7 条）
node test/manifest.test.js                # bundle 清单与启动顺序
node test/isolated-install-cycle.test.js  # 隔离 DSH_HOME 安装/卸载循环 + 启动冒烟（需沙箱升级）

版本与兼容

包名 dsh-ui-session-archive（原 dsh-client-ui-session-archive 已删除弃用，以新名重新发布）· MIT · 已发布（当前版本见 package.json）。

版本兼容：同一份产物同时兼容 DSH 0.1.5-rc.1（当前目标 SDK）与 0.1.2-rc.1。 两代之间的破坏性差异用版本自适应（双路径）处理，详见 docs/development.md §9：

• settings 注册面：0.1.2-rc.1 删除了自由函数 installSettingsSection/settingsNamespace （静态具名 import 缺失导出 = 模块链接错误，会拖垮整棵插件树），现改为优先旧的自由函数、 否则经 ctx.settings.installSection 注册；
• RPC 通道：0.1.5-rc.1 的 dsh-client-connection 把 inject 从 ["webServer","credentials"] 收窄为 ["credentials"]，导致 ctx.connection.rpc.handle 抛 cannot get property "webServer" without inject 并让整棵插件树加载失败。 本包改为调用同一实现的 register(owner, …) 并显式传入注入了 webServer 的 owner， 因此在未打补丁的 0.1.5-rc.1 上也能加载（RPC 协议本身仍由内核实现，未重写）；
• client 侧类型来源：ClientContext 移回 cordis 的 Context， ISessions/IWorkspaces 移到 dsh-api-session-controller / dsh-api-workspace-controller， dsh.client.inject 组合边同步更新（client half 的 SDK import 全是 import type，运行时无影响）。

当前版本包含的修复：

• 0.1.13（当前）：单条删除补「当前查看会话」保护（host 校验 + client 按钮/徽标 + payload 透传；此前仅批量有）；删除整体移入 enqueueOperation 队列消除 TOCTOU；先注册表后文件（失败留孤儿目录不留幽灵行）；批量计划与预检 O(n²) 改直查；挂载等待 observer 降频（首波后转轮询）；删除确认文案修正附件过度承诺（四处文档同步）
• 0.1.10：兼容 DSH 0.1.5-rc.1（上述三处自适应 + SDK 依赖与组合边同步）；已完成 未打补丁 0.1.5-rc.1 与 0.1.2-rc.1 的隔离启动 + RPC 往返 + 真浏览器面板验证 （0.1.11/0.1.12 为发布间隙的维护版本，未在此逐条回填）
• 0.1.9：批量操作（多选恢复/删除、全选、删除前计划预览与受保护跳过原因）；修复「归档后删除经常报还有会话未结束」——hasOpenTurn 不再把缺失 events 数组的 live 对象当作「有未结束回合」（归档空闲会话常驻 live store 但无 events），运行中改为 summary.running 权威拦截
• H1：host inject 补 sessions/agents（delete 的「运行中」校验必然执行），sessionPersistence 保持可选 ctx.get()
• H2：删除前校验会话目录名 === sessionId，防止误删
• L1：hasOpenTurn 对缺失 events 的 fail-safe 兜底
• M2：删除后归档清理失败返回显式半删除错误（不再静默）
• M3：新增会话 id 格式校验（兼容真实 session-<uuid> 与纯 UUID）
• L3：面板挂载改为 MutationObserver 自愈（等待中心列出现）
• M4：docs/architecture、development、installation、protocol 与实现对齐
• N1-N4：侧边栏入口与任务看板样式对齐（内边距/间距/圆角/折叠态/选中高亮）、exports 精简、build.mjs 本地 tsc、apply-guard 全局符号守卫
• P1：修复面板定位错误（改名时 dataset 键未同步，data-dsh-session-archive-view 与 CSS 的 data-dsh-ui-session-archive-view 不匹配，导致 position:absolute;inset:0 失效、面板叠在输入框下方）。现 hostEl.dataset / entry.dataset 键统一为 dshUiSessionArchive*，与选择器对齐，面板正确铺满对话区
• P2：侧边栏入口图标与任务看板尺寸对齐（SVG 18×18、外框圆角矩形 12×11 与任务看板一致；入口行高 36px、图标容器 24×24、折叠态 36×36 圆形）