dsh-better-sidebar

一个服务化的侧边栏框架，一套开箱即用的完整工作台

右侧栏 + 底部面板双工作台，并把 ctx.betterSidebar 服务开放给所有插件——

通过 registerTab / registerFileViewer 注册新的侧边栏页面与文件预览器。

🌏 中文 · English

dsh-better-sidebar 工作台截图

📑 目录

✨ 功能一览
🚀 安装
🖼️ 特性巡礼
🌐 插件生态
🆕 最近更新
⌨️ 快捷键
🔌 服务化扩展
🛠️ 开发与构建
🔐 安全 · ⚠️ 已知限制 · 🖥️ 平台支持
💬 社区 · 🤝 参与贡献 · ⭐ Star History · 🔗 友情链接

✨ 功能一览

🗂️ 文件工作台：资源管理器（懒加载目录树；软链接按目标类型展示——目录软链接可展开、失效链接标红）+ CodeMirror 编辑器；图片 / Markdown（含 Mermaid 图表，strict 安全渲染 + 点击放大；README 级内嵌 HTML——徽章墙 / `` 折叠 / 表格内联标签经 DOMPurify 消毒真实渲染；浮动目录大纲一键跳转）/ HTML / PDF
🌐 内嵌浏览器：多开网页 tab，后退 / 前进 / 刷新；内容运行在沙箱 iframe；外链默认按协议分流——HTTP 在侧边栏打开、HTTPS 走系统浏览器（设置页可分别调整）
💻 真实终端：xterm.js + node-pty 真实 shell，断线重连回放；可选为模型注入 terminal_* 工具
📂 模型侧边栏打开（可选）：全局设置开启后注入 sidebar_open 工具——模型可主动在侧边栏打开文件 / 文件夹（树以该目录为根）/ HTTP(S) 网页
🌿 文件变动：Git 视角（真 diff / 历史 / 暂存·提交·还原 / worktree·子仓库选择）与本轮文件视角（模型读 / 写 / 编辑实时追踪，按文件分组、按类型筛选）双视角合一；统一 diff 渲染（改蓝配对 + 行内字符级高亮 + 语法着色 + 上下文折叠），底部可拖拽预览面板，可一键展开为独立 diff tab（默认自由浮窗，可在设置改为面板下半 split）
🧩 后台任务页：subagent 拓扑 + 后台任务（退出码 / 实时输出 / 强制终止）
💬 侧边对话(beta)：Codex 风格的侧边线程——继承主会话完整上下文（含进行中的回合与工具调用）独立运行，不进入主会话；线程内可持续追问，一键「保存为新会话」提升为顶层会话
🪟 双工作台：右侧栏 + 底部面板；拖 Tab 拆分 / 合并分栏（可跨面板），移动端自动合并全宽抽屉
🪟 自由窗口：把标签栏的任一 tab 拖到主会话区域——成为可移动 / 缩放 / 置顶的悬浮窗口（默认 390×780），拖回侧边栏 pane 即停靠，随会话持久化；features 含 'floatWindows'，插件 tab 无差别支持
📌 固定终端：右键终端 Tab 可「固定到工作区 / 固定到全局」——固定后切换会话不消失，在 TabBar 内联呈现（跨会话虚拟 Tab，点击就地激活，PTY 按 home 会话 id+tab 直连宿主 PTY，无需切回宿主会话）；Agent 终端被 reconcile 移除时豁免保留
🔁 会话隔离：布局 / Tab / 面板按会话持久化，陈旧状态自动净化
⚙️ 声明式设置：设置页「侧边卡片」逐项独立开关，二级设置经齿轮弹窗
⚡ 按需加载：启动只拉 ~325KB 核心，终端 / 编辑器 / Mermaid 图表等重依赖用到才按需拉取（设计文档）
🌏 多语言：界面文案跟随 DSH 语言（zh / en）实时切换；安装 @huanlin/dsh-plugin-better-locale 后支持日语（ja）等第三语言覆盖（见下方「🌏 第三语言覆盖」）

🔌 核心理念：服务优先——内置的 8 tab + 6 viewer 与第三方插件通过同一套 ctx.betterSidebar API 注册，能力完全对等；官方不再内置、可由生态提供的功能，交由生态插件实现（已有 28+ 生态插件，见下方「🌐 插件生态」）。接入文档见「🔌 服务化扩展」与外部插件接入指南。

🚀 安装

前置：已装好 DSH（dsh web 能正常运行），Node.js ≥ 20、pnpm ≥ 10。

支持的 DSH 版本：

🧪 alpha 通道：v0.18.0-alpha.0 起适配 DSH 0.1.2-alpha.x（npm dist-tag alpha），不再支持 0.1.0-rc.8 ~ 0.1.1-rc.2——DSH stable 用户请继续用 @latest（v0.17.1）；DSH 0.1.2-alpha.3 用户安装 dsh-better-sidebar@alpha。

dsh plugin --profile web add dsh-better-sidebar@latest   # 首次会因 pnpm 11 拦截 node-pty 构建脚本而失败（依赖已写入）
cd ~/.dsh/profiles/web && pnpm approve-builds --all      # 放行构建脚本（自动重跑安装）
dsh plugin --profile web add dsh-better-sidebar@latest   # 重跑即成功

装完硬刷新浏览器（Cmd/Ctrl+Shift+R）即可看到侧边栏（DSH 对 client 改动热加载，无需重启；仅 host 半更新时需要重启）。

方式二：让 DSH 自己装——把下面这段提示词发给任意一个 DSH 会话：

帮我安装 dsh-better-sidebar 插件（DSH 侧边栏工作台），步骤：
1. 执行 dsh plugin --profile web add dsh-better-sidebar@latest（首次会被 pnpm 11 拦截 node-pty 构建脚本而失败，属正常）
2. 在 ~/.dsh/profiles/web 下执行 pnpm approve-builds --all（放行构建脚本，会自动重跑安装）
3. 再次执行 dsh plugin --profile web add dsh-better-sidebar@latest
4. 完成后提醒我硬刷新浏览器（Cmd/Ctrl+Shift+R）
遇到报错先查 https://github.com/omdsh-dev/DSH-better-sidebar README 的常见问题表。

更新

dsh plugin --profile web add dsh-better-sidebar@latest

也可把 ~/.dsh/profiles/web/package.json 里的版本号改高后 pnpm install。改完硬刷新浏览器（Cmd/Ctrl+Shift+R）即可（client 改动无需重启 DSH）。

常见问题

现象	原因与解决
报 `Ignored build scripts`	pnpm 11 拦截构建脚本。在 profile 目录（`~/.dsh/profiles/web`）跑 `pnpm approve-builds --all`。
报 `minimum release age` / 版本不足 24h	装的版本发布不足 24 小时。等 24h 或重跑一次（pnpm 会自动补 `minimumReleaseAgeExclude`）。
报「找不到 profile 目录」	先跑一次 `dsh web`，让它初始化 `~/.dsh/profiles/web`。
页面出现两个侧边栏	双挂载。旧的手动挂载行：`~/.dsh/profiles/web/cordis.patch.yml` 还留着 `- insert: ... better-sidebar ...`，删掉那段（同 id 重复挂载 loader 会直接报 `duplicate loader entry id`）。聚合包（如 `@linxin666/dsh-web-ui-all`）以不同 id 挂载本包时，0.13.x 起插件自身 bundle patch 会自动退让（检测到已有启用中的同包名挂载就不挂自己），无需手动处理；若仍双挂载，先确认聚合包的 bundle 顺序在 `dsh-better-sidebar` 之前。
Windows 下终端无法使用	`node-pty` 依赖预编译二进制；若当前 Node 版本没有对应产物，需装编译工具链（VS Build Tools）。主流 Node 版本一般已有预编译。
终端提示「node-pty 加载失败」	`node-pty` 安装缺失/损坏（如 pnpm 拦截了构建脚本）。终端横幅会给出修复命令：复制到 DSH 所在环境的终端/cmd 执行（在 `~/.dsh/profiles/web` 下 `pnpm approve-builds --all && pnpm rebuild node-pty`），完成后重启 DSH 并点重试。插件与 DSH 核心使用同一 `node-pty@^1.1.0`，修复后两者同步恢复。
提示 `dsh: command not found`	先安装 DSH；或直接用 `npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsh-better-sidebar@latest`。

从源码安装 / 开发（可选，替代 npm 方式）

调试本地改动或跟随开发分支时，把依赖指向本地克隆并自行构建：

1. git clone https://github.com/omdsh-dev/DSH-better-sidebar.git ~/Code/DSH-better-sidebar
   cd ~/Code/DSH-better-sidebar && pnpm install && pnpm build
2. ~/.dsh/profiles/web/package.json 的 dependencies 写 "dsh-better-sidebar": "link:"
3. ~/.dsh/profiles/web/cordis.patch.yml 追加挂载行（需要指定终端 shell 时，在行内加 `config.shell`；`config.shellArgs` 可带参启动，非空时替换默认的 `-l`。不填则自动解析 `$SHELL` / 登录 shell / powershell.exe）：
   - insert:
       - id: better-sidebar
         name: 'dsh-better-sidebar'
         config:
           shell: /bin/zsh
           shellArgs:
             - --noprofile
             - --no-rc
4. 在 ~/.dsh/profiles/web 执行 pnpm install
5. 硬刷新浏览器（Cmd/Ctrl+Shift+R）即可看到效果（client 改动无需重启 DSH；host 半改动才需重启）

更新：git pull && pnpm install && pnpm build → 硬刷新浏览器即可（client 改动热加载生效，无需重启 DSH；host 半改动才需重启）。切回 npm 通道时，把依赖改回 "dsh-better-sidebar": "^0.16.1" 再 pnpm install。

通过 plugin-registry 安装（可选，与上述二选一）

前置：DSH 已集成 plugin-registry（dsh registry 可用）。同时启用两个通道会双挂载（Node 半挂两次、页面两个侧边栏）。

git clone https://github.com/omdsh-dev/DSH-better-sidebar.git && cd DSH-better-sidebar
pnpm install && pnpm build
node scripts/package-registry.mjs   # 组装 registry/ 暂存（含清单 + 产物 + README，不入库）
dsh registry install ./registry     # 安装（默认禁用）
dsh registry enable dsh-external/dsh-better-sidebar

更新：git pull && pnpm install && pnpm build → node scripts/package-registry.mjs → dsh registry uninstall/install/enable。切换通道前先移除另一通道的挂载。

🖼️ 特性巡礼

以下均为真实界面实拍（每行两张，点击可放大）。


🗂️ 文件工作台：资源管理器
支持两种格式的资源管理器：内嵌在文件预览中 / 独立显示文件树。懒加载目录树、软链接按目标类型展示（目录软链接可展开、失效链接标红）、全局文件名搜索、上传文件/文件夹与拖放上传、右键菜单（在新 Tab 打开 / 在侧边打开 / 复制路径）、悬浮 `@文件` 一键引用进输入框。

文件资源管理器

| 📝 Markdown · 图片 · PDF 内联预览 Markdown 预览支持 Mermaid 图表（securityLevel: 'strict' 安全渲染 + 二次清洗；点击图表弹窗放大、滚轮缩放、拖拽平移）、README 级内嵌 HTML（徽章墙、 折叠块内嵌 markdown、表格单元格内联标签——DOMPurify 白名单消毒真实渲染， 等活性内容剥除，本地图片经会话媒体路由重写）与浮动目录大纲（≥3 标题出现，点击平滑跳转、自动展开折叠块）；图片 / PDF 走媒体路由内联展示；Office 三件套由生态插件补齐。

Markdown + Mermaid 预览

| | 🖥️ CodeMirror 代码编辑器

CodeMirror 代码编辑器

| 🖼️ 图片内联预览

图片内联预览

| | 💻 真实终端 xterm.js + node-pty 真实 shell（不是模拟器）：断线重连 transcript 回放、shell / shellArgs 可配置（设置页或 cordis.patch.yml）、可选为模型注入 terminal_* 工具（agent 可直接开终端跑命令）。

真实终端

| 🌿 文件变动：Git 视角 + 本轮文件 双视角合一：Git 视角保留完整源代码管理（暂存 / 取消暂存 / 提交（Ctrl+Enter）/ 还原、历史、worktree 与子仓库选择）；本轮文件视角实时折叠会话事件日志，记录模型读 / 写 / 编辑的每个文件（按文件分组、按类型筛选、操作数角标）。点击任意改动在底部可拖拽预览面板查看统一 diff——删红 / 增绿 / 改蓝配对 + 行内字符级高亮 + 语法着色 + 上下文折叠——也可一键展开为 VSCode 式独立 diff tab（同一渲染栈）。

文件变动

| | 🌐 内嵌浏览器 多开网页 tab：后退 / 前进 / 刷新 / 地址栏；内容运行在不透明源沙箱 iframe（界面实时显示沙箱状态，可按页面临时解锁）；聊天里的外链点击可被接管到侧边栏打开（按协议分流，可配）。

内嵌浏览器

| 🧩 任务页：子代理拓扑 + 后台任务 子代理树实时拓扑（运行状态、批量实时预览）+ 后台任务清单（退出码 / 实时输出 / 强制终止）；新子代理 / 新任务可自动展开侧边栏（可关）。

任务页：子代理拓扑

| | 💬 侧边对话(beta) Codex 风格侧边线程：每个对话一个独立 Tab；线程继承主会话完整上下文（含进行中回合，以 interrupted 诚实冻结）独立运行，不污染主会话；可持续追问、重启冷恢复；一键「保存为新会话」提升为顶层会话。

侧边对话(beta)

| 🪟 双工作台：右侧栏 + 底部面板 + 分栏 右侧栏与底部面板可同时展开；拖 Tab 到分栏边缘拆分、拖到中间合并（可跨面板）；面板宽高左缘/上缘拖拽调节；移动端自动合并为全宽抽屉；把 tab 拖到主会话区域可变为自由窗口（悬浮 / 缩放 / 置顶，拖回 pane 停靠）。

双工作台（右侧栏 + 底部面板）

| | ⚙️ 声明式设置 设置页「侧边卡片」分区：每个 tab / 预览器一张小卡片，独立开关（高亮启用态 + 品牌开关滑块）；二级设置经卡片底部「功能设置」条弹窗（开关 / 文本 / 数字 / 下拉）；插件自有设置持久化在 pluginSettings。

声明式设置：侧边卡片

| 📱 移动端 窄屏（

移动端全宽抽屉

🌐 插件生态

ctx.betterSidebar 服务向所有插件开放两个扩展点：registerTab（注册侧边栏页面） 与 registerFileViewer（注册文件预览器）。内置的 8 tab + 6 viewer 与第三方插件走同一套 API，能力完全对等。

import type {} from 'dsh-better-sidebar'  // 触发 ctx.betterSidebar 类型合并
export const inject = ['betterSidebar']
export function apply(ctx: Context) {
  ctx.effect(() => ctx.betterSidebar.registerTab({
    id: 'my-plugin:db', title: 'Database', component: ({ scope }) => ,
  }))
  ctx.effect(() => ctx.betterSidebar.registerFileViewer({
    id: 'my-plugin:csv', exts: ['csv'], fetchStrategy: 'custom',
    load: async (path, scope) => parseCsv(await fetchText(scope, path)),
    component: ({ customData }) => ,
  }))
}

GitHub topic dsh-better-sidebar 下已有 28+ 生态插件（持续增长中）：