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）。

UI 基线（0.2.0 起）：入口与面板经壳层 seat（sidebar.panellist + main）注册，要求壳层提供这两个 seat——即 0.1.7-rc.2 一代（「插件 / 计划 / 任务看板」共用同一容器的那一版）。在 0.1.5/0.1.2 一代上，host 命令、/session-archive 与 RPC 仍然可用，但 UI 不出现（静默缺席：不报错、不拖垮启动）；需要旧核上的 UI 请留在 0.1.16（那一代的入口是 DOM 注入 + 覆盖中栏）。

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

• client 设置面：0.1.7-rc.2 删除了 client 服务 settingsScope（换成 configForms/settingsSchema
  • remote.settings）。它不再列入必需 inject——必需注入里挂一个永不出现的服务，cordis 就不满足、 apply 从不执行，表现是侧边栏入口与面板静默消失且启动无报错；现改为可选 ctx.inject + 默认挂载，0.1.5 一代仍按 enabled 门控挂/卸；
• 打开会话 / 当前会话：0.1.7-rc.2 的 ctx.sessions.open() 已不存在，改走 ctx.uiWorkspace.openSession()（0.1.5 一代回退 sessions.open）；会话列表快照不再带 current， 改用行上的 retainedBy.mainView > 0 推导当前会话（内核 workspace UI 同款）；
• settings 注册面：0.1.2-rc.1 删除了自由函数 installSettingsSection/settingsNamespace （静态具名 import 缺失导出 = 模块链接错误，会拖垮整棵插件树），现统一经 ctx.settings.installSection 注册；0.1.7-rc.2 连该注册面也没有，插件降级告警 （面板与命令不依赖设置项）。同时 @deepseek-ai/dsh-settings 已降为 devDependency： 作为运行时依赖时，dsh 会把 pnpm 解析出的嵌套 [email protected] 当插件 entry 装载， 在 0.1.7-rc.2 上必报 TypeError: this.load is not a function；
• 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.2.0（当前，未发布）：面板改走壳层官方 seat，彻底移除 DOM 覆盖——侧栏行与中栏页面分别注册到 sidebar.panellist 与 main（每处都用 ctx.slots.inject 包裹，加载顺序无关；壳层不提供该 seat 时归档静默缺席而非拖垮启动），行的盒/图标盒/高亮/折叠窄栏、面板切换与窗口联动全部交回壳层，与「插件」「计划」「任务看板」同容器渲染。删除 sidebar-entry.ts（DOM 注入 + MutationObserver 自愈）、setViewOpen/isViewOpen/toggleViewOpen（<html data-dsh-ui-session-archive-active> 开关）、mountArchiveView（position:absolute;inset:0 + display:none!important 遮蔽对话列）以及整段 .dsa-entry* 行样式；「返回对话」改调 layout.selectPanel(null)；dsh.client.inject 增补 @deepseek-ai/dsh-client-ui-layout。按 VERSIONING §1.2 进位第 2 位（架构重写且对外行为发生变化）：入口从「DOM 注入的裸按钮、位置在新会话按钮下方」变为「壳层面板列表中的一行」；再次点击该行不再开合关闭，退出改走「返回对话」或侧栏其他面板行；中栏是真正的面板切换，不再是覆盖对话列的浮层。
• 0.1.16（已发布）：侧边栏入口与原生面板行逐项对齐——注入行的图标盒由 24px（内含 18px 图标）改为 16px（宽栏导航图标尺寸，SVG 同步 16px），行几何改为壳层 SidebarRoot.module.css 的 panelRow 取值（min-height:36px / padding:7px 8px / margin:0 2px / gap:8px / font:inherit 14px / line-height:22px / 圆角 12px），文字底色由 --dsw-alias-label-secondary 改为 --dsw-alias-label-primary；修复前「会话归档」相对「任务看板 / 插件」等同行图标右偏 3px、文字右偏 8px 且整行偏灰，现三行落在同一像素网格（像素测量 + 对照页实测复核）；另补原生同款 :focus-visible 焦点环，折叠窄栏规则增加 [data-sidebar-collapsed] 属性分支（不再只依赖可能失效的 sidebarCol/collapsed 类名片段），折叠态图标回到 18px。
• 0.1.15（已发布）：纯文档/元数据对齐版本，运行代码与 0.1.14 逐字节相同（lib/ 未改）。发布目的是把 README 与变更记录同已发布的 0.1.14 代码对齐（0.1.14 的 npm 包内 README 早于该次文档更新），并刷新市场可见版本、绕开 24h 发布期门禁（minimumReleaseAge）；已装 0.1.14 的机器无需升级。
• 0.1.14（已发布 npm latest）：兼容桌面版内核 DSH 0.1.7-rc.2——client settingsScope 改可选注入 + 默认挂载（原必需注入会让入口/面板静默消失）；打开会话改 uiWorkspace.openSession（回退 sessions.open）；当前会话改用 retainedBy.mainView 推导；@deepseek-ai/dsh-settings 降为 devDependency（消除 0.1.7 上的 warning: 1 entry did not activate / this.load is not a function；0.1.13 装到 0.1.7 桌面端会把整棵树拖死）；已完成隔离 DSH_HOME 的 file: 安装 + 启动 + 真浏览器面板验证，以及自 npm registry 安装的复验（发布物反查 + 干净启动）
• 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 圆形）