会话文件夹 DmitriyValetov/dsh-session-folders

dsh-session-folders

Fork 说明。 这是 EugeneVl/dsh_session_folders（MIT，© Eugene）移植到 DSH 0.2.0-rc.1 的版本，发布名为 dsh-session-folders (npm: the maintainer-scoped fork package)，维护仓库在 DmitriyValetov/dsh-session-folders。上游包面向 0.1.x 客户端契约，在 0.2.x 上无法激活。本 fork 的每一处改动及原因都列在 FORK-NOTES.md；简而言之：客户端 store seed、用于导航/归档/目录选择的 ctx.uiWorkspace.、用于「在文件夹中打开」的 /open-in-app/ 路由对、带权重后缀的图标名、内联的 storage-domain 辅助函数、作为真实依赖的 zod，以及没有 Auto rename。下面的上游文档描述的是共有行为；凡是提到 Auto rename 或 0.1.x 兼容性的地方，以本说明为准。

中文版 README · Русская версия README

DeepSeek Harness Web UI 的会话文件夹插件：把侧边栏的工作区浏览器替换成一个新浏览器，新增会话文件夹——每个工作区一层命名文件夹。会话可以拖进文件夹，也可以通过右键菜单移动；文件夹数据保存在服务端，刷新页面后依然存在。状态徽标与内置会话浏览器保持一致。无需改动 harness。

截图

功能

整理

- 会话文件夹：每个工作区一层命名文件夹；文件夹之外的会话放在「收件箱」（散放）桶里
- 移动会话：把会话拖到文件夹上，或者用行右键菜单——「移动到文件夹…」，其中「新建文件夹…」这一项会当场创建文件夹并把会话移进去；子菜单里的「工作区」项把会话从文件夹退回散放桶
- 文件夹管理：新建、重命名、删除（带确认）；名称在每个工作区内唯一（不区分大小写）
- 就地重命名：双击会话标题即可原地重命名——Enter 提交，Esc 取消
- 拖拽排序：拖动工作区行可以调整工作区顺序；拖动文件夹行可以调整它所在工作区内的文件夹顺序（文件夹始终排在散放会话上方，会话按时间排序的规则不变）；顺序保存在服务端
- 每个文件夹和 Archive 块里的 Show more / Show less：最多显示五个会话，点击溢出那一行才展开；展开状态按文件夹记，只存在当前浏览器会话里

会话操作

- 上下文菜单：右键点击任意会话 / 文件夹 / 工作区行，都会打开它的操作菜单（每行的「…」按钮已移除）；每个操作都带图标
- 固定 / 取消固定会话：固定的会话永远排在最前，在它所属的文件夹里或散放区里都是如此；固定状态保存在服务端，会话移动时跟着一起走；固定会话如果没有状态徽标，就在状态槽位显示一个小图钉图标
- 悬停快速归档：鼠标悬停在会话行上，时间戳会换成一个小归档图标——点一下即可归档该会话（和上下文菜单里的操作一样）；替换是原地发生的，所以布局不会跳动
- 会话 ID 徽标：就在快速归档图标旁边，悬停会话行还会露出一个小 ID 徽标——点一下即可把该行的 session-<id> 复制到剪贴板
- 新建会话按钮：工作区行上的加号图标会在该工作区里新建会话；文件夹行上更小的加号会直接在该文件夹里新建会话（新建的空白会话会移入该文件夹并打开）
- 状态徽标 Running / Completed——与内置的会话浏览器一致

归档与恢复

- Archive 块：工作区行上的归档图标用来显示/隐藏一个虚拟的 Archive 文件夹，里面是该工作区所有已归档的会话；显示时，图标会渲染成带删除线的样式。显示该文件夹的同时也会把它展开；它按最新归档的会话排在最前（前五个，带一行「Show N more / Show less」），并且支持拖放：把会话拖到它上面即可归档（和上下文菜单里的操作一样）；把已归档的会话拖到某个文件夹或散放区，就在那里恢复它
- 从 Archive 恢复：右键点击已归档的会话，会提供「Restore to original folder」（会话回到归档时所在的文件夹，或回到散放区）；左键点击则把会话恢复到工作区的 Restored 文件夹（按需创建）并在聊天中打开。恢复的会话与常规会话分开存放：Restored 文件夹永远排在最前（紧挨在 Archive 块下方），只要里面没有可见会话就自动隐藏

导航

- Recent 区块：位于工作区列表上方，显示最近五个工作区会话（来自文件夹或散放区），最新的排在最前；点击其中一个会在聊天中打开它，并展开折叠的工作区/文件夹层级让它可见，它在 Recent 和所属工作区/文件夹里都会保持高亮。标题栏可折叠/展开该区块（状态会持久保存）
- Recent 来源卡片：悬停 Recent 里的会话，会在该行右侧弹出一个小卡片，显示它所在的工作区和文件夹
- 文件夹树引导线：虚线从每个文件夹图标垂到它下面的会话；打开会话所在文件夹的整棵树会标成蓝色。开关在浏览器标题栏里（默认开启）
- 会话搜索，带匹配高亮 —— 按标题和内容搜索
- 打开工作区文件夹：工作区行上的第一个按钮（文件夹图标）会用操作系统默认的文件管理器打开工作区根目录，走宿主原生的 openPath API
- 全部折叠 / 展开：浏览器标题栏里的一对箭头按钮，一键折叠和展开所有工作区分组、文件夹、Recent 区块和 Archive 区块
- 工作区聚焦：工作区行上的准星开关（右键菜单里也有）会隐藏其他所有内容 —— 其他工作区、Recent、Ungrouped —— 直到再次关闭；重启后聚焦状态重置

持久化与 UI

- 服务端持久化：文件夹存在 DSH 存储域里，页面刷新后依然保留；视图状态（折叠的文件夹等）存在浏览器 localStorage 里
- 服务端是唯一事实来源：每个操作都在服务端校验（工作区是否存在、会话归属、名称冲突）；客户端只是镜像这些规则
- 双语 UI：跟随页面语言（zh / en）
- 折叠侧边栏：在窄栏里只渲染搜索和新建工作区按钮，与内置浏览器一致

安装

从 npm 安装

dsh plugin --profile web add dsh-session-folders (npm: the maintainer-scoped fork package)

从 registry 安装预构建包（不跑构建脚本，不需要 allowBuilds 步骤）。把 web 换成你的配置档 —— DeepSeek Harness 桌面应用用的是 desktop 配置档。

从 GitHub 安装

dsh plugin --profile web add 'github:DmitriyValetov/dsh-session-folders#v0.5.2'

构建产物 lib/ 已提交，所以从 git 安装不会跑构建脚本。

从本地目录安装

dsh plugin --profile web add /absolute/path/to/dsh-session-folders

从 tarball 安装

pnpm pack
dsh plugin --profile web add /absolute/path/to/dsh-session-folders-0.5.0.tgz

手动等效操作

把 "dsh-session-folders (npm: the maintainer-scoped fork package)": "^0.5.0" 加到 dependencies，把包名加到配置档 package.json 里的 dsh.profile.bundles，然后在该目录下运行 pnpm install。

安装后重启配置档（宿主插件和客户端 bundle 在启动时加载）。

用法

快速上手

1. 打开侧边栏：每个工作区里，文件夹显示在散落会话的上方

文件夹

1. 新建文件夹 —— 右键工作区行 →「New folder」；名称在工作区内必须唯一
2. 重命名 / 删除文件夹 —— 右键文件夹行 →「Rename」；删除会要求确认，文件夹里的会话会变成散落状态
3. 重新排序 —— 拖动工作区行到新位置；在所属工作区内拖动文件夹行（放到某行的上半/下半部分，即可插到它前面/后面）

会话

1. 移动会话 —— 把会话行拖到文件夹上（只能拖进同一工作区的文件夹），或者右键会话 →「移动到文件夹…」→ 选一个文件夹，也可以点「新建文件夹…」新建一个并立即移入
2. 移回散放区 —— 右键会话 →「移动到文件夹…」→「工作区」（第一项）
3. 置顶会话 —— 右键 →「置顶」：会话跳到所在文件夹（或散放区）顶部并留在那里，其他会话来来去去都不影响；「取消置顶」恢复按最新排序；已置顶但没有状态徽标的会话，会在状态位显示一个小图钉图标
4. 新建会话 —— 工作区行上的加号按钮在该工作区里新建会话；文件夹行上较小的加号直接在该文件夹里新建会话
5. 重命名会话 —— 双击标题（Enter 提交，Esc 取消），或右键 →「重命名」
6. 快速归档 —— 鼠标悬停在会话行上：时间戳会换成归档图标；点它即可归档该会话

归档与恢复

1. 归档 —— 工作区行上的归档图标用来显示/隐藏虚拟的 Archive 文件夹（该工作区所有已归档会话，按最新排序，每次显示五个）。把会话拖到它上面即可归档；把已归档会话拖到文件夹或散放区即可恢复到那里
2. 恢复 —— 右键已归档会话 →「恢复到原文件夹」（回到原来的位置）；点击它则恢复到 Restored 文件夹，该文件夹若处于折叠状态会自动展开，并打开该会话。Restored 文件夹始终排在最前，为空时自动隐藏

查找与导航

1. 搜索 —— 浏览器顶部的输入框；匹配项会高亮，且可点击
2. 最近 —— 工作区列表上方的区域显示最近五个会话（文件夹 + 散放区）。点一个即可打开；最近列表中的行以及工作区/文件夹图标会标出当前会话。点击标题栏可折叠该区域
3. 打开工作区文件夹 —— 文件夹按钮（工作区行上的第一个）在系统文件管理器中打开工作区根目录

视图

1. 全部折叠 / 展开 —— 浏览器顶部的一对箭头按钮：
- 折叠：收起所有工作区分组和文件夹
- 展开：再次展开它们

工作原理

| 层 | 实现 |
| 宿主 | lib/index.js —— 一个 cordis 插件：9 条 POST 路由 /dsh-session-folders/{list,create,rename,delete,move,reorder-folders,reorder-workspaces,pin,unarchive}；自带存储域 dsh_session_folders（一条全局记录，保存文件夹列表）；所有变更通过一条 promise 尾串行执行，避免两个浏览器互相覆盖；工作区和会话归属通过 ctx.workspaceRegistry 校验。这个分支把域声明辅助函数内联了，没有引入 @deepseek-ai/dsh-storage-domain，因为配置档插件是从配置档解析模块的 |
| 客户端 | lib/client.js —— 通过 window.__ModuleLoader__.load 加载的 bundle，注册在 sidebar.workspaces 插槽（优先级 -1）；服务 slots / locale / sessions / workspaces；视图状态存在 localStorage（dsh.session-folders.view.v1） |

- 文件夹不参与会话记账：工作区拥有会话，文件夹只负责分组。没有列进任何文件夹的会话，按定义就是散落的
- 删除工作区不会删除文件夹记录：这些记录不再被提供（按存活的工作区 id 过滤），无害地留在存储里
- DSH 域保证写入以持久性优先；存储文件是 ~/.dsh/storages/dsh_session_folders.json
- 不改系统提示词，不加新的模型工具 —— 零 token 影响

限制

- 只支持一层文件夹：不支持嵌套文件夹
- 会话只能移进拥有它的工作区里的文件夹；不属于任何工作区的会话（未记账）无法进入文件夹
- 文件夹名上限 80 个字符；重名会被拒绝（不区分大小写）
- 重排序以服务端为准：客户端提交完整的有序 id 列表，服务端校验（工作区不能掉出存活集合，文件夹不能离开所属工作区）

兼容性

这个 fork 面向 DSH 0.2.0-rc.1（已在 macOS 上的打包桌面应用中验证）：sidebar.workspaces 插槽（以 priority: -1 注册）、uiWorkspace / sessions / workspaces 客户端服务、client-store 的 defineStore、宿主 webServer / storageDomain / workspaceRegistry 服务，以及作为包依赖的 zod ^4.4.3。更早的 0.2.x 和更晚的 0.3.x 版本可能改动这些约定；0.1.x 系列仍以上游包为准。

开发

没有构建步骤：lib/ 就是提交进仓库的 bundle（宿主 + 客户端）。直接改文件，然后做语法检查：

node --check lib/index.js
node --check lib/client.js

客户端改动（菜单项、按钮、渲染）通常只需刷新浏览器 —— bundle 按需提供；宿主改动（路由、校验）需要重启 dsh web。

发布清单

1. 在 package.json 里升 version，并在 CHANGELOG.md 加一条记录
2. 提交，打标签 vN.N.N，推送 master 和标签
3. 把配置档指向新版本：dsh plugin --profile web add 'github:EugeneVl/dsh_session_folders#vN.N.N'，然后重启 dsh web