前言¶

在 DeepSeek Harness（DSH）里，一个工作区对应「一个项目目录 + 跑在该目录下的会话」。实际开发时，这些目录常常成批落在同一个父路径下：十几个插件仓库、demo、沙箱项目并排注册，侧边栏默认「按工作区」平铺一长列，切换和定位成本很高。

官方侧边栏已经提供 「按工作区树」 视图（groupBy = "workspace-tree"），会把每个工作区挂到最近的已注册祖先工作区下面。难点在于：树要有「父节点」，而你往往只注册了叶子项目目录，没有为共同的上级目录单独建工作区。

社区插件 dsh-plugin-better-folders（维护者 huguangyu666，分类：客户端）做的是：按规则把共同上级目录注册成文件夹节点，让内置树视图自动把同级工作区收进去，而不是重写侧边栏 UI。

这是什么¶

更好的 DSH 文件夹 是 DSH 客户端侧插件：自动整理工作区列表，把同一上级目录下满足条件的多个工作区汇合成一个可折叠的文件夹节点。视觉上的折叠与层级由 @deepseek-ai/dsh-client-ui-workspace 提供的「按工作区树」完成；插件侧主要是注册上级目录为工作区，并可选切换分组方式。

它解决什么问题¶

README 中的典型布局如下：多个项目都在 MyProjects 或 code 下，平铺时每一行都是一个工作区。整理后，共同父目录会变成文件夹节点，子工作区嵌在其下；只有一个工作区的路径仍保持原样。

工作原理可以概括为：

把相同上一级目录的工作区汇合在一起，等价于把那个共同的上级目录本身注册成一个工作区（文件夹节点）。

因此插件不覆盖官方 UI，依赖已有树视图渲染，避免「插件一挂、侧边栏白屏」类问题。

核心功能¶

按上级目录自动 / 手动整理¶

整理规则可在设置中调整（默认值来自 README）：

插件对自己创建的文件夹节点做了级联防护；用户手动注册的父级工作区不受此限制；根目录（C:\、/）永远不建节点。

「表」：自定义工作区集合¶

除磁盘层级决定的汇合外，插件支持 表：自定义名称下的工作区 id 集合，不创建目录、不改 cwd、不碰会话历史。同一工作区可属于多张表；删表不删工作区或会话。入口在侧边栏「工作区」标题行旁的 📋（与 📁 整理按钮同排；定位失败时会退回底部「整理文件夹」按钮）。

斜杠指令示例：

/folders tables                        # 列出所有表
/folders tables new 性能对比            # 建表
/folders tables add 性能对比 titan      # 把工作区加进去（按路径片段匹配）
/folders tables remove 性能对比 titan   # 移出
/folders tables rename 性能对比 A/B     # 改名
/folders tables delete 性能对比         # 删表（不删任何东西）

模型侧可用工具 manage_workspace_tables。

安全边界（使用前建议通读）¶

• 只增不删：整理只调用 workspaceRegistry.create()，不删除工作区、目录或会话历史。
• 还原：unmerge 仅删除本插件创建且没有任何会话的文件夹节点；状态记录在 ~/.dsh/better-folders/state.json。
• 还原会关闭 autoOrganize，避免删节点后又被自动整理重建。
• 删除工作区注册不等于删除磁盘数据；重复整理幂等。

HTTP API（同源）¶

Host 通过 ctx.webServer 注册前缀路由，例如：GET /better-folders/api/status、POST /better-folders/api/preview、POST /better-folders/api/apply、POST /better-folders/api/unmerge 等（完整列表见仓库 README）。

安装与启用¶

插件以源码构建后写入 DSH profile，README 未提供 dsh plugin add 一类的一行命令。当前 package 版本为 0.5.2（MIT），要求 Node >= 22.5，peer 依赖 @deepseek-ai/dsh（>=0.1.2-rc.1）等。

下面步骤来自仓库 README：先构建，可选 dry-run，再安装到 profile（示例为 web；桌面版常用 desktop，需与当前正在使用的 profile 一致）。

npm install
npm run build
npm test
node tools/install-into-profile.mjs --profile web --dry-run
node tools/install-into-profile.mjs --profile web

从 GitHub 获取源码后，在同一目录内执行：

git clone https://github.com/huguangyu666/dsh-plugin-better-folders.git
cd dsh-plugin-better-folders
npm install && npm run build
node tools/install-into-profile.mjs --profile web

装完后重启 DSH；桌面版还需刷新页面以加载客户端半。卸载：

node tools/install-into-profile.mjs --profile web --uninstall

DSH 社区插件目录 SkillHub 条目 可查阅简介与分类；目录站为社区生态，与 DeepSeek / 幻方无官方从属关系。安装前请自行阅读源码与许可证；插件在当前 DSH 进程权限下运行。

典型用法¶

装上并重启后，多数情况下无需额外操作：

1. 自动整理在启动约 4 秒后运行一次，将合格的上级目录注册为文件夹节点。
2. 若 autoTreeView 为 true 且存在可汇合目录，客户端会尝试把侧边栏切到「按工作区树」。不切到该视图时，列表可能只多出几个条目，看不出折叠效果。

手动流程：

1. 打开 设置 → 插件 → 更好的 DSH 文件夹。
2. 点 预览 查看将新建的文件夹节点。
3. 点 一键整理；必要时在 视图选项 → 分组方式 → 按工作区树 手动切换，或刷新页面。
4. 不满意则 还原（会关闭自动整理；需在面板中重新打开 autoOrganize 若仍要自动汇合）。

对话中可执行：

/folders            # 查看现状
/folders plan       # 预览
/folders organize   # 执行整理
/folders unmerge    # 还原

没看到效果时，README 建议核对：profile 是否对应当前进程、客户端半是否加载、分组是否为「按工作区树」。排查信息可写在 ~/.dsh/better-folders/diag.json（接口 /better-folders/api/diag）。

适用场景与注意¶

• 适合：同一父目录下注册了多个 DSH 工作区（多插件仓、多 demo、多沙箱），希望侧边栏按文件夹折叠，又愿意使用官方「按工作区树」而非第三方改 DOM 的方案。
• 适合：需要把分散路径上的工作区收进自定义「表」，在侧边栏按集合浏览，甚至下钻到会话级跳转。
• 注意：汇合依赖「注册上级目录为工作区」；minChildren、maxDepth 会改变哪些目录会变成节点。还原仅针对插件创建且无会话的节点。
• 注意：安装涉及本地构建与 install-into-profile.mjs，请只在信任的来源（上述 GitHub 仓库）操作，并确认 target profile。

结尾¶

更好的 DSH 文件夹把「同级目录太多、侧边栏平铺难找」的问题，收敛成可配置的注册与视图切换：算法在 Host 端规划与创建节点，展示交给 DSH 内置工作区树；并附带表、斜杠指令、Agent 工具与 HTTP API，便于人工和自动化共用同一套整理逻辑。

• 社区目录：https://www.skillhub.cn/plugins/huguangyu666/dsh-plugin-better-folders
• 源码与完整说明：https://github.com/huguangyu666/dsh-plugin-better-folders