ostar-dsh-left-sidebar

---

📖 项目简介

ostar-dsh-left-sidebar 是一个 DSH(DeepSeek Harness)Web 客户端插件,为左侧边栏的「工作区 / 会话」浏览区域补充管理能力:

• 批量删除工作区(可连同其会话一起删除)
• 批量删除会话 与 单选删除会话(行内删除按钮 / ··· 菜单「删除会话」)
• 迁移会话 / 复制会话 到其他工作区(含对话、轨迹全部会话数据)
• 一键折叠全部 / 展开全部 所有工作区与会话组

同时,官方浏览器的一切都被完整保留:标题行的 ⌕ 搜索(展开式输入框 + 内容全文搜索)、☰ 视图选项(分组方式:按工作区 / 单列表;排序方式:手动 / 最近更新)、＋ 添加工作区(系统目录选择器);工作区行的文件夹图标(开/合、当前会话高亮)、悬停箭头、··· 菜单(重命名 / 删除工作区)、＋ 新建会话、悬浮卡片(名称 / 路径 / 创建日期);会话行的官方状态点(空闲=绿色圆环、进行中=蓝色矩阵追逐动画、等待=橙色圆环)、相对时间、··· 菜单(重命名 / 分叉 / 归档 / 迁移 / 复制 / 删除会话)、悬浮卡片(名称 / 时间 / 工作状态);以及点击外部关闭菜单、行悬停操作、视口级悬浮定位等全部交互。

技术背景:侧边栏「工作区」浏览区域在 DSH 中是一个单插槽(sidebar.workspaces),由官方 ui-workspace 浏览器整体渲染。本插件以外部插件的负优先级注册方式接管该区域,并在其中逐项复刻官方浏览器的行为,再叠加管理功能 —— 因此使用体验与官方一致,同时获得官方没有的管理能力。

✨ 功能一览

能力	说明
🗑️ 批量删除工作区	批量选中模式:每个工作区行复选框 + 「全选」+「删除选中」;可选「连同会话删除」(默认开启)
💬 批量删除会话	每个会话行复选框,支持多选后一次性删除
🎯 单选删除会话	会话行内「删除」按钮;会话 ··· 菜单新增「删除会话」项(红色,二次确认)
🔀 迁移会话	会话 ··· 菜单「迁移会话」:选择目标工作区,完整复制对话/轨迹数据后归档原会话(从列表隐藏)
📋 复制会话	会话 ··· 菜单「复制会话」:选择目标工作区,在目标工作区生成完整副本,原会话不变
⏷ 一键展开全部	展开所有工作区与会话组(含「未分组」)
⏶ 一键折叠全部	折叠所有工作区与会话组
🛡️ 删除确认	所有删除操作均有二次确认条,展示将删除的工作区 / 会话数量
🔄 状态同步	删除走官方客户端服务(workspaces.delete / workspaces.archiveSession),与产品自带 UI 同一路径,删除后列表自动同步;复制/迁移成功后自动刷新列表
🖥️ 官方复刻	搜索 / 视图选项 / 添加工作区 / 行菜单 / 悬浮卡片 / 状态点 / 字体(标题 14px、时间 12px)/ 行高(工作区 34px、会话 32px)与官方逐项一致
🎨 主题一致	全部使用官方主题 token(--dsw-alias-*、--dsw-static-*),明暗主题自动适配

🏗️ 工作原理

┌─────────────────────────────────────────────────┐
│ 侧边栏 (sidebar)                                │
│  ┌───────────────────────────────────────────┐ │
│  │ 工作区浏览区域 (sidebar.workspaces 槽)     │ │
│  │  ⌕ 搜索 · ☰ 视图选项 · ＋ 添加工作区        │ │
│  │  ⏷ 展开全部 · ⏶ 折叠全部 · ☑ 批量选中  ←新增│ │
│  │  ┌ 工作区 ──────────── ···  ＋ ┐           │ │
│  │  │  • 会话  ● 5 分钟前   ···  │           │ │
│  │  └─────────────────────────────┘           │ │
│  └───────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

• 数据:消费槽标准 hooks(useSessions / useWorkspaces,官方 session/workspace 快照 store),会话标题、分组、归档标记、运行状态全部来自官方数据流,无需额外 RPC。
• 删除:客户端 ctx.workspaces.delete(workspaceId) 与 ctx.workspaces.archiveSession(sessionId) —— 与官方浏览器完全相同,客户端 store 自动同步。
• 迁移 / 复制:官方模型里工作区归属 = 会话创建时的 cwd 目录,官方没有跨工作区移动/复制会话的 API(insertSessionBefore 仅限同工作区排序,fork 副本继承原 cwd)。因此 Host 半区提供同源路由 /ostar-dsh-left-sidebar/migrate,按官方 fork 的实现路径(agents.create + seed 完整事件日志)在目标工作区路径下创建副本,再 attachSession 更新目标工作区账目 —— 对话、轨迹数据完整复制;「迁移」在复制后归档原会话。复制成功后 client 调用运行时 refresh() 强制刷新列表。
• UI:官方 SVG 图标以数据形式内联复刻(插件运行时无法 import 官方图标组件);样式使用官方主题 token。

📁 目录结构

ostar-dsh-left-sidebar/
├── src/
│   ├── index.js          # Host 半区:迁移/复制会话路由(/ostar-dsh-left-sidebar/migrate)
│   └── client.js         # Client 半区:完整浏览器 + 管理功能(全部 UI 逻辑)
├── dsh.plugin.json       # 插件清单(id / main / client.main / contributes)
├── cordis.patch.yml      # bundle patch:CLI 安装时自动追加挂载行
├── package.json          # npm 包元数据(dsh.bundle.patch / client.platform)
├── README.md             # 本文档
└── LICENSE               # MIT

🚀 安装

前置:已安装 DSH(dsh web 可正常运行),Node.js ≥ 20。

方式一:官方 CLI(推荐,直接从 GitHub 安装)

dsh plugin --profile web add github:ostar999/ostar-dsh-left-sidebar

• pnpm 原生支持 github:user/repo 形式;CLI 会自动把依赖写入 profile 的 package.json,并依据包的 cordis.patch.yml(dsh.bundle 声明)自动对账进 dsh.profile.bundles,无需手动改文件。
• 装完完全重启 DSH(host 半区变更需要重启)→ 浏览器硬刷新(Cmd/Ctrl+Shift+R)。
• 提示:✕ missing peer ... 是 peer 依赖警告(其它插件声明的 react/cordis 等由 DSH 运行时提供),不影响安装与运行。

方式二:从源码安装(本地开发调试)

1. git clone https://github.com/ostar999/ostar-dsh-left-sidebar.git
   cd ostar-dsh-left-sidebar

2. 在 DSH profile 的 package.json 中把依赖指向本地克隆:
   ~/.dsh/profiles/web/package.json
     "dependencies": {
       "ostar-dsh-left-sidebar": "link:<克隆目录的绝对路径>"
     }

3. 在 ~/.dsh/profiles/web/cordis.patch.yml 追加挂载行:
   - insert:
       - id: left-sidebar-manager
         name: 'ostar-dsh-left-sidebar'

4. 在 ~/.dsh/profiles/web 目录执行:
   pnpm install

5. 重启 DSH + 硬刷新浏览器,即可在工作区按钮行看到新增按钮。

找不到 ~/.dsh/profiles/web?先跑一次 dsh web 初始化 profile。

🔄 更新

CLI 方式(推荐):

dsh plugin --profile web add github:ostar999/ostar-dsh-left-sidebar@latest

从源码方式:

cd <克隆目录>
git pull
# host 半区有改动时,在 ~/.dsh/profiles/web 下 pnpm install

然后硬刷新浏览器即可(client 改动热加载生效,无需重启 DSH;host 半改动才需重启)。

🗑️ 卸载

CLI 方式(推荐):

dsh plugin --profile web remove ostar-dsh-left-sidebar

手动方式:从 ~/.dsh/profiles/web/package.json 删除依赖行与 dsh.profile.bundles 中的条目 → pnpm install → 重启 DSH。

卸载不会删除任何工作区或会话数据 —— 插件只操作官方注册表 / 归档集合,不触碰会话日志;迁移/复制产生的副本是真实会话,卸载后仍保留。

🛠️ 开发

环境

git clone https://github.com/ostar999/ostar-dsh-left-sidebar.git
cd ostar-dsh-left-sidebar
# 纯 JS 源码,无需构建;按「方式二」link 到 profile 即可迭代

修改与验证

1. 修改 src/client.js(浏览器与全部管理逻辑)或 src/index.js(Host 半区);
2. 浏览器 硬刷新(Cmd/Ctrl+Shift+R)加载新 client 代码 —— client 改动无需重启 DSH;
3. Host 半区改动需要重启 DSH。

架构要点(改代码前必读)

• 注册方式:Client 半区通过 slots.inject('sidebar.workspaces', ...) 注册浏览器组件;sidebar.workspaces 是 single 槽,动态插件负优先级胜出,替换官方浏览器。⚠️ 不要在该注册中声明 children 子槽(sidebar.workspaces.directoryFlow 已由官方声明,重复声明会报 slot "..." is already declared)。
• React 环境:Client 半区以 DSH 外部插件规范提供 —— window.__ModuleLoader__.load({ id, factory }),工厂内 require('react') 解析到 shell 共享的 React,不 import 任何包;若改为独立打包发布,需按外部插件规范显式声明 peerDependencies 并构建。
• 图标:全部为官方 SVG path 的内联复刻(搜索 / 视图选项 / 添加工作区 / 文件夹 / 箭头 / 省略号 / 加号 / 编辑 / 删除 / 分叉 / 归档 / 展开 / 折叠 / 批量选中)。
• 状态点:官方 StateDot 的复刻 —— 空闲=绿色圆环(:before 10% 外圈 + :after 60% 内核)、进行中=3×3 矩阵追逐动画(8 个 2px 格,125ms 负延迟)、等待=橙色圆环。
• 悬浮元素:菜单 / 悬浮卡片 / tooltip 一律 position: fixed 视口定位 + 自动避让边缘 —— 侧边栏浏览容器是 overflow: hidden,行内绝对定位会被裁剪;菜单打开时渲染全屏透明遮罩实现「点击外部关闭」。
• ··· 菜单交互:··· 按钮不显示悬浮提示(noTip,与官方一致仅保留 aria-label);点击打开菜单时立即清除该行悬浮卡片,且菜单打开期间该行不再显示悬浮卡片(官方 HoverCard 的 disabled: menuOpen 行为)。
• 迁移/复制(Host 半区):路由 /ostar-dsh-left-sidebar/migrate 处理跨工作区复制 —— sessionQuery.readSession 读完整日志 → agents.create({ seed, meta: { cwd: 目标工作区路径, parentSession, seedLength, agentPreset } })(与官方 fork 同路径)→ target.attachSession(childId) 更新账目(触发 client 实时同步)→ 「迁移」再 archiveSession(源)。与官方 fork 一致:仅复制到最后一个完成的 turn;副本标题继承日志内 title 事件。client 成功后调用运行时 sessions.refresh() / workspaces.refresh() 兜底刷新列表。
• 主题:只用官方 token(--dsw-alias-* / --dsw-static-*),并带 fallback,保证明暗主题一致。
• 删除语义:工作区删除 = 注册移除(会话落入「未分组」);会话删除 = 归档(从分组面隐藏,日志保留)。如需真正物理删除会话,需另行扩展 Host 半区。

常见问题

现象	原因与解决
报 slot "sidebar.workspaces.directoryFlow" is already declared	注册 sidebar.workspaces 时带了 children 声明。删除注册选项中的 children(子槽由官方声明)。
报 loaded without registering ... via __ModuleLoader__.load	client 入口必须是 window.__ModuleLoader__.load({ id, factory }) 形式(参见 src/client.js),不能是普通 ESM 导出。
报 single slot "sidebar.workspaces" already has a registration at priority 0	注册 sidebar.workspaces 时必须显式 priority: -100 压过官方浏览器。
页面出现两个工作区列表	双挂载:profile 的 cordis.patch.yml 有旧挂载行 + bundle patch 同时生效。删除旧的手动挂载行。
安装时出现 ✕ missing peer ...	peer 依赖警告(其它插件声明的 react/cordis/dsh-* 由 DSH 运行时提供),不影响安装与运行。
复制/迁移成功但列表不显示新会话	旧版本缺少列表刷新。更新到最新版(client 成功后自动调用 refresh());仍不显示则硬刷新浏览器。
迁移会话报 workspace-move-invalid: the session is not accounted	旧版本误用 insertSessionBefore 跨工作区移动(官方仅支持同工作区排序)。更新到最新版(走 host 日志级复制)。
改了代码没效果	client 改动需硬刷新(Cmd/Ctrl+Shift+R);host 改动需重启 DSH。
报 Ignored build scripts	pnpm 拦截构建脚本,在 profile 目录跑 pnpm approve-builds --all(本插件纯 JS 无构建脚本,通常不受影响)。
提示 dsh: command not found	先安装 DSH;或 npx -y --package @deepseek-ai/dsh dsh plugin ...。

📄 许可证

MIT © ostar999