dsh-better-sidebar
一个服务化的侧边栏框架，一套开箱即用的完整工作台
右侧栏 + 底部面板双工作台，并把
ctx.betterSidebar 服务开放给所有插件——
通过
registerTab /
registerFileViewer 注册新的侧边栏页面与文件预览器。
✨ 功能一览
- 🗂️ 文件工作台：资源管理器（懒加载目录树；工作区多个文件夹并排成根；软链接按目标类型展示——目录软链接可展开、失效链接标红）+ CodeMirror 编辑器；图片 / Markdown / HTML / PDF / Office 内联预览
- 🌐 内嵌浏览器：多开网页 tab，后退 / 前进 / 刷新；内容运行在沙箱 iframe；外链默认按协议分流——HTTP 在侧边栏打开、HTTPS 走系统浏览器（设置页可分别调整）
- 💻 真实终端：xterm.js + node-pty 真实 shell，断线重连回放；可选为模型注入
terminal_* 工具
- 🌿 Git 面板：真 diff + VSCode 式 diff tab、历史、右键暂存 / 提交 / 还原
- 🧩 后台任务页：subagent 拓扑 + 后台任务（退出码 / 实时输出 / 强制终止）
- 🪟 双工作台：右侧栏 + 底部面板；拖 Tab 拆分 / 合并分栏（可跨面板），移动端自动合并全宽抽屉
- 🔁 会话隔离：布局 / Tab / 面板按会话持久化，陈旧状态自动净化
- ⚙️ 声明式设置：设置页「侧边卡片」逐项独立开关，二级设置经齿轮弹窗
- ⚡ 按需加载：启动只拉 ~325KB 核心，终端 / 编辑器等重依赖用到才按需拉取（设计文档）
- 🌏 多语言：界面文案跟随 DSH 语言（zh / en）实时切换
🔌 核心理念：服务优先——内置的 7 tab + 6 viewer 与第三方插件通过同一套 ctx.betterSidebar API 注册，能力完全对等；官方不再内置、可由生态提供的功能，交由生态插件实现。接入文档见下方「🔌 服务化」与 外部插件接入指南。
StarPivot 0.13.5
这是 omdsh-dev/DSH-better-sidebar 的 StarPivot fork。相对上游：
- 文件树刷新按钮移到右上角按钮簇，仅在右边栏打开时显示；文件树搜索框旁不再放折叠按钮
- 打开「自动化」等 shell overlay 页面时隐藏整组按钮
- 「位置兼容模式」默认开启，折叠按钮整体下移躲开桌面窗口标题栏
- 工作区关联多个文件夹时，文件树把每个文件夹都作为可折叠的根目录列出
- 浏览器地址栏把「前往 / 在浏览器中打开」收成一组附属按钮
- 包名改为
@starpivot/dsh-better-sidebar
不要和上游 dsh-better-sidebar 同时安装。
🆕 最近更新
v0.12.3
✨ 新功能
- 🎨 皮肤兼容（令牌驱动）：全面消费 DSH 设计令牌，与 dsh-web-ui 皮肤中心 10 款皮肤兼容，换肤自动跟随；终端/编辑器表面在透明/半透明玻璃值下回退不透明底色，文字不叠在皮肤背景上（#110，修复 #106 #105 #90 #60，附带 #52 #57 #92）
- 🗂️ 统一路径处理：UNC 路径 / 软链接分类（目录软链接可展开、失效链接标红）、HTML 路由平台守卫（#134，#65 #67 #43 #79 #115）
- 🖥️ 终端 shell 可配置：设置项自定义 shell，Windows 自动探测 pwsh（#95）
- 📝 编辑器新增语言：C# / Kotlin / Swift 语法高亮（#120）
- 🧭 设置页导航图标：设置页导航图标与布局优化（#114）
- ➕ 推荐插件目录新增：
dsh-git-remotes——Git 远程 Tab（分支/上游/ahead-behind、fetch 可 prune、ff-only pull、确认后才 push，不替换内置暂存/提交）（#91）；dsh-video-preview——视频内联预览（.mp4/.webm/.mov/.mkv/.avi 等，自带 /video 宿主路由支持 HTTP Range 206 拖进度条，不受 20MB mediaLimit 限制）（#126）
🐛 修复
- 🔧 xterm 依赖迁移：弃用的 xterm 迁移至
@xterm/xterm（Closes #122，#128）
- 📝 Markdown 编辑器：选区转对话弹窗恢复可用（#24）
- 🐛 node-pty 加载失败不再拖垮 server（#140）：宿主半改为懒加载 node-pty，缺失时插件照常挂载，终端以修复提示横幅（可复制命令 + 重试按钮）呈现，agent 终端工具自动跳过
- 🧪 测试工程：单元测试拆分（#141）+ smoke 偶发失败修复
🚀 工程
- 接入 GitHub Release 自动发版 npm（Trusted Publishing，产物带 provenance），本版起打 tag 即自动发布（#148）
v0.12.2
- 📐 位置兼容模式：设置页新增开关：为 Windows 右上角原生标题栏预留顶部空间，侧边栏按钮与内容整体下移（默认关闭）；下移距离可在齿轮弹窗中自定义（0–120px）
- 🔌 服务化基座：完整类型导出 +
version/features 能力探测、状态订阅（getSnapshot/subscribeState）、tab 角标、onOpen/onActivate/onClose 生命周期回调、updateTab/activateTab/openFile、定向打开、meta 跨刷新持久化、插件自有设置（pluginToggles/render）、外链点击目标认领（urlTarget）
- ➕ 添加插件：设置页「推荐插件目录」+ 一键复制安装命令；内置 Office 预览迁至推荐插件
- 🖱️ 标签页滚轮：标签页栏支持鼠标滚轮横向滚动
- 🐛 修复：远程访问 403（信任栅栏改用
trustedHosts）、侧边栏崩溃 #31、Windows 下 HTML 预览盘符路径
v0.12.1
- 🔌 服务化基座：完整类型导出 +
version/features 能力探测、状态订阅（getSnapshot/subscribeState）、tab 角标、onOpen/onActivate/onClose 生命周期回调、updateTab/activateTab/openFile、定向打开、meta 跨刷新持久化、插件自有设置（pluginToggles/render）
- ➕ 添加插件：设置页「推荐插件目录」+ 一键复制安装命令；内置 Office 预览迁至推荐插件
- 🖱️ 标签页滚轮：标签页栏支持鼠标滚轮横向滚动
- 🐛 修复：远程访问 403（信任栅栏改用
trustedHosts）、侧边栏崩溃 #31、Windows 下 HTML 预览盘符路径
📝 说明：0.12.0 正式版因 npm 判定版本已发布无法复用，正式发布改用 0.12.1，两者内容一致。
v0.12.0
- 🔌 服务化基座：完整类型导出 +
version/features 能力探测、状态订阅、tab 角标、生命周期回调、定向打开、meta 跨刷新持久化、插件自有设置
- ➕ 添加插件：设置页「推荐插件目录」+ 一键复制安装命令；内置 Office 预览迁至推荐插件
- 🖱️ 标签页滚轮：标签页栏支持鼠标滚轮横向滚动
- 🐛 修复：远程访问 403（信任栅栏改用
trustedHosts）、侧边栏崩溃 #31、Windows 下 HTML 预览盘符路径
🚀 安装
前置：已装好 DSH（dsh web 能正常运行），Node.js ≥ 20、pnpm ≥ 10。
dsh plugin --profile web add @starpivot/dsh-better-sidebar@latest
装完硬刷新浏览器（Cmd/Ctrl+Shift+R）即可看到侧边栏（DSH 对 client 改动热加载，无需重启；仅 host 半更新时需要重启）。
更新
dsh plugin --profile web add @starpivot/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 ...。 |
| 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 @starpivot/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 追加挂载行：
- insert:
- id: better-sidebar
name: 'dsh-better-sidebar'
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.12.3" 再 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。切换通道前先移除另一通道的挂载。
⌨️ 快捷键
| 操作 | 按键 |
|---|
| 保存编辑 | Ctrl/Cmd + S |
| Git 提交 | Ctrl + Enter |
| 关闭 Tab | 鼠标中键 |
| 拆分/合并分栏 | 拖 Tab 到分栏边缘 / 中间 |
| 引用文件到输入框 | 悬浮行尾 @文件 按钮 |
| 复制文件路径 | 右键行 → 复制相对/绝对地址 |
🔌 服务化：注册 tab 与文件预览器
从 v0.4.0 起暴露 ctx.betterSidebar 服务，其他插件可注册侧边栏页面与文件预览器（内置 7 tab + 6 viewer 亦通过同一服务注册）：
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 }) => <DbView sessionId={scope.sessionId} />,
}))
}
v0.12.1 补齐基座能力（完整类型导出、能力探测、状态订阅、tab 角标、生命周期回调、定向打开、插件自有设置等），详见下方接入文档。
完整接入文档：
➕ 添加插件（推荐插件目录）
设置页「侧边卡片」两个网格末尾的虚线卡片分别打开 Tab / 预览插件弹窗：声明扩展点、「在 GitHub 上浏览更多插件」按钮（GitHub topic dsh-better-sidebar）、推荐插件目录（名字 / 仓库 / 简介 / 安装脚本），每个条目「跳转」直达仓库、「复制」把安装命令写入剪贴板。
收录新插件：向 src/client/plugins-tabs.ts（Tab 注册）或 src/client/plugins-viewers.ts（文件预览注册）追加一条 PluginEntry，并把仓库打上 dsh-better-sidebar topic；数据完整性由 tests/plugin-list.spec.ts 守护。
🛠️ 开发与构建
pnpm install # @deepseek-ai/* 已发布到 npm（^0.1.0-rc.6），直接解析、无需令牌
pnpm typecheck # tsc --noEmit
pnpm build # → lib/index.js + lib/invariant.js + lib/client.js + lib/client-registry.js + lib/types
pnpm test # vitest（含 manifest 一致性守卫，需先 build）
pnpm watch # tsdown --watch
架构：单 npm 包、host/client 双半结构——host（src/index.ts）：/sidebar/api/* JSON API、/sidebar/file 媒体路由、/sidebar/html 预览路由、/sidebar/ws/terminal WebSocket（fs / git / pty / 预览，全部会话级 + 信任围栏）；client（src/client/index.tsx）：portal 侧边栏 + 各视图 + 拦截；状态按会话持久化 localStorage。插件按 DSH 官方规范组织（无 default 导出、双 client bundle），运行期不依赖 npm / checkout（@deepseek-ai/* 由 web profile 提供）。
🔐 安全
- 路由受 Host 头信任围栏保护（与
/api 一致）；fs.write 原子写入；媒体/预览路由仅限工作区文件夹内文件；git 只调 CLI、绝不设置身份
- HTML 预览与浏览器 tab 的内容在不透明源沙箱 iframe 中渲染（无
allow-same-origin/allow-top-navigation、no-referrer、权限策略全禁）；/sidebar/html 路由带 CSP sandbox + 大小/路径边界；地址栏拒绝 javascript:/data:/file: 与 localhost 等本机地址
- 界面实时显示沙箱状态（关闭时红色警示），可临时解锁当前页面；设置页可按功能关闭沙箱（默认关闭该设置，带警告文案）——关闭后内容与界面同源，仅建议对完全可信内容使用
⚠️ 已知限制
- Git 无 push/pull/fetch；无文件 watcher（手动刷新）；工具行内文件打开按钮不可拦截
- 终端 Tab 拖到另一分栏会重挂载（shell 重开）
- Office 三件套预览（.docx/.xlsx/.pptx）已移至「推荐插件」（Office 预览插件，见设置页「添加插件」弹窗）；未安装时此类文件走代码/下载查看兜底
- 浏览器沙箱无登录态/第三方 Cookie 受限，部分站点登录需走弹窗；被
X-Frame-Options/frame-ancestors 拒绝嵌入的站点（如 arxiv.org）显示原因面板（含「在浏览器中打开」）；iframe 内部跳转不进后退栈
- HTML 预览渲染的是已保存文件（不反映未保存草稿）
- 移动端（<768px）无底部面板：进入窄屏时其标签页一次性并入右侧栏（迁移后回桌面仍保留在右侧栏），桌面端的底部面板只在宽视口下可用；移动端底部首展自动开终端不触发
🖥️ 平台支持
Windows / Linux / macOS 三平台适配（macOS 日常验证；其余经单元测试覆盖）；node-pty 优先预编译二进制，失败需编译工具链（Windows VS Build Tools / Linux make+g+++python3 / macOS Xcode CLT）。
🔗 友情链接
- dsh-tianshu-tui：DeepSeek Harness 交互式终端 UI 插件（渲染核心由自研 harness agent Tianshu-Tui 演进而来），在官方基础上增加 TDD 与证据门等工作流
- dsh-TUI：Claude Code 风格全屏交互终端插件——像素鲸鱼顶栏、实时工作状态行、思考流式展开、双击 Esc 回滚、上下文进度条 + TPS 仪表，npm 一键安装
- dshfind 插件超市：三方插件市场——GitHub topic
dsh-plugin 下的公开仓库清单，每日同步 star、贡献者与增长数据
- DeepSeek Harness Desktop：为 DeepSeek Harness 生态打造的现代化桌面端——无需配置 Node.js 或执行命令即可启动和管理本地 Harness 服务；官网
