[!IMPORTANT]
已适配 DSH 原生侧边栏 API（v0.19.0 起，DSH 0.1.5-rc.1+）：右列就是 DSH 自己的右侧栏——插件的每个 tab 类型与 tab 体通过 ctx.sidebarRightTabs / ctx.sidebarRight 注册与打开，聊天里的文件打开统一走 ctx.sidebarRight.openResource('dsh-resource://file/…')，插件不再自绘右侧面板（旧的浮窗能力同步移除）。自绘的底部工作台与开放给其他插件的 ctx.betterSidebar 服务保持不变，接入方式见插件接入指南。
📑 目录
✨ 功能一览
- 🗂️ 文件工作台：资源管理器（懒加载目录树；软链接按目标类型展示——目录软链接可展开、失效链接标红）+ CodeMirror 编辑器；图片 / Markdown（含 Mermaid 图表，strict 安全渲染 + 点击放大；README 级内嵌 HTML——徽章墙 /
<details> 折叠 / 表格内联标签经 DOMPurify 消毒真实渲染；浮动目录大纲一键跳转）/ HTML / PDF
- 🌐 内嵌浏览器：多开网页 tab，后退 / 前进 / 刷新；内容运行在沙箱 iframe；外链默认按协议分流——HTTP 在侧边栏打开、HTTPS 走系统浏览器（设置页可分别调整）
- 💻 真实终端：xterm.js + node-pty 真实 shell，断线重连回放；可选为模型注入
terminal_* 工具
- 📂 模型侧边栏打开（可选）：全局设置开启后注入
sidebar_open 工具——模型可主动在侧边栏打开文件 / 文件夹（树以该目录为根）/ HTTP(S) 网页
- 🌿 文件变动：Git 视角（真 diff / 历史 / 暂存·提交·还原 / worktree·子仓库选择）与本轮文件视角（模型读 / 写 / 编辑实时追踪，按文件分组、按类型筛选）双视角合一；统一 diff 渲染（改蓝配对 + 行内字符级高亮 + 语法着色（含 mjs/cjs/mts/cts、CSS/SCSS/Less、HTML/XML/SVG/Vue、GraphQL、JSONC/JSON5）+ 上下文折叠），底部可拖拽预览面板，可一键展开为独立 diff tab（落进工作台的 diff 分栏）；
.md 操作（读 / 写 / 编辑）预览头部可切换阅读模式——经共享 MarkdownText 渲染 GFM 表格 / 任务列表 / 删除线 / 脚注 / 数学公式，本地图片自动改写为 /sidebar/file 媒体路由；含 ```mermaid 围栏时走编辑器同款懒加载 mermaid 渲染器（图可点击缩放 / 平移）；敏感内容脱敏**——凭据形态路径整文件遮罩、普通文件按内容形态遮值（api_key: / Bearer / sk- / AKIA / ghp_ / PEM 等，字段名保留），默认开启、预览面板一键开关（localStorage 记忆），仅影响显示、不改会话数据。已知边界：mermaid 无引号节点标签含被遮密钥时，图回退源码（规避：标签加引号）；.html 操作（读 / 写 / 编辑）预览头部可切换渲染模式——复用编辑器同款 /sidebar/html 路由 iframe，相对资源（./style.css、img/x.png）同路由解析，分段读取也渲染完整文档，恒定沙箱（opaque origin + CSP 头，无逃生门）；.pdf 操作（读 / 写 / 编辑）同样可切换渲染模式**——复用编辑器同款 PDF 预览（媒体路由字节流 + 显式 Blob，浏览器原生查看器内嵌，附下载入口）
- 🧩 后台任务页：subagent 拓扑 + 后台任务（退出码 / 实时输出 / 强制终止）
- 💬 侧边对话(beta)：Codex 风格的侧边线程——继承主会话完整上下文（含进行中的回合与工具调用）独立运行，不进入主会话；线程内可持续追问，一键「保存为新会话」提升为顶层会话
- 🖥️ 原生右侧栏 + 底部工作台：右列交给 DSH 0.1.5 的原生右侧栏——插件把每个 tab 类型注册成原生 tab（文件打开走
dsh-resource://file/**，并接管内置「文件」页 / 文件树），插件自己只保留底部工作台（分栏 / 终端 / 随会话持久化），开合按钮挂在会话头右侧
- 📌 固定终端：右键终端 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 版本：
📌 正式版：v0.19.0 起适配 DSH 0.1.5-rc.1+（npm dist-tag latest）。仍停在 DSH 0.1.5-alpha.2 的用户请固定安装 [email protected]；0.1.2-rc.1 稳定线用户继续用 [email protected]；DSH ≤ 0.1.1-rc.2 请用 [email protected]。
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 的常见问题表。
方式三：一键脚本——克隆本仓库后执行 bash scripts/install.sh（macOS / Linux / Windows Git Bash；Windows 原生环境用 install.ps1；-h 查看参数），自动完成 add → 放行构建脚本 → 重跑安装。
更新
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（徽章墙 <div align=center>、<details> 折叠块内嵌 markdown、表格单元格内联标签——DOMPurify 白名单消毒真实渲染，<script> 等活性内容剥除，本地图片经会话媒体路由重写）与浮动目录大纲（≥3 标题出现，点击平滑跳转、自动展开折叠块）；图片 / PDF 走媒体路由内联展示；Office 三件套由生态插件补齐。
|
🖥️ 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 诚实冻结）独立运行，不污染主会话；可持续追问、重启冷恢复；一键「保存为新会话」提升为顶层会话。
|
🖥️ DSH 原生右侧栏 + 插件底部工作台
<su |
DSH-better-sidebar 是面向 DSH（DeepSeek Harness）编程代理宿主的服务化侧边栏框架，添加了右侧边栏加底部面板的工作台，并暴露「betterSidebar」服务，让第三方插件可以注册自己的侧边栏页面和文件查看器。