dsh-better-sidebar

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







右侧栏 + 底部面板双工作台，并把 ctx.betterSidebar 服务开放给所有插件——
通过 registerTab / registerFileViewer 注册新的侧边栏页面与文件预览器。

📑 目录

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

✨ 功能一览

• 🗂️ 文件工作台：资源管理器（懒加载目录树；软链接按目标类型展示——目录软链接可展开、失效链接标红）+ 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 + VSCode 式 diff tab、历史、右键暂存 / 提交 / 还原；工作区容器下自动发现子仓库并显示仓库选择器，支持 linked worktree 变更发现
• 🧩 后台任务页：subagent 拓扑 + 后台任务（退出码 / 实时输出 / 强制终止）
• 💬 侧边对话(beta)：Codex 风格的侧边线程——继承主会话完整上下文（含进行中的回合与工具调用）独立运行，不进入主会话；线程内可持续追问，一键「保存为新会话」提升为顶层会话
• 🪟 双工作台：右侧栏 + 底部面板；拖 Tab 拆分 / 合并分栏（可跨面板），移动端自动合并全宽抽屉
• 🪟 自由窗口：把标签栏的任一 tab 拖到主会话区域——成为可移动 / 缩放 / 置顶的悬浮窗口（默认 390×780），拖回侧边栏 pane 即停靠，随会话持久化；features 含 'floatWindows'，插件 tab 无差别支持
• 🔁 会话隔离：布局 / Tab / 面板按会话持久化，陈旧状态自动净化
• ⚙️ 声明式设置：设置页「侧边卡片」逐项独立开关，二级设置经齿轮弹窗
• ⚡ 按需加载：启动只拉 ~325KB 核心，终端 / 编辑器 / Mermaid 图表等重依赖用到才按需拉取（设计文档）
• 🌏 多语言：界面文案跟随 DSH 语言（zh / en）实时切换；安装 @huanlin/dsh-plugin-better-locale 后支持日语（ja）等第三语言覆盖（见下方「🌏 第三语言覆盖」）

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

🚀 安装

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

支持的 DSH 版本：

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

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 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

🖼️ 特性巡礼

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

🗂️ 文件工作台：资源管理器 支持两种格式的资源管理器：内嵌在文件预览中 / 独立显示文件树。懒加载目录树、软链接按目标类型展示（目录软链接可展开、失效链接标红）、全局文件名搜索、上传文件/文件夹与拖放上传、右键菜单（在新 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 面板 暂存 / 取消暂存 / 提交（Ctrl+Enter）/ 还原，历史列表；点击改动文件打开 VSCode 式 diff tab（红绿行级对比）。
🌐 内嵌浏览器 多开网页 tab：后退 / 前进 / 刷新 / 地址栏；内容运行在不透明源沙箱 iframe（界面实时显示沙箱状态，可按页面临时解锁）；聊天里的外链点击可被接管到侧边栏打开（按协议分流，可配）。	🧩 任务页：子代理拓扑 + 后台任务 子代理树实时拓扑（运行状态、批量实时预览）+ 后台任务清单（退出码 / 实时输出 / 强制终止）；新子代理 / 新任务可自动展开侧边栏（可关）。
💬 侧边对话(beta) Codex 风格侧边线程：每个对话一个独立 Tab；线程继承主会话完整上下文（含进行中回合，以 interrupted 诚实冻结）独立运行，不污染主会话；可持续追问、重启冷恢复；一键「保存为新会话」提升为顶层会话。	🪟 双工作台：右侧栏 + 底部面板 + 分栏 右侧栏与底部面板可同时展开；拖 Tab 到分栏边缘拆分、拖到中间合并（可跨面板）；面板宽高左缘/上缘拖拽调节；移动端自动合并为全宽抽屉；把 tab 拖到主会话区域可变为自由窗口（悬浮 / 缩放 / 置顶，拖回 pane 停靠）。
⚙️ 声明式设置 设置页「侧边卡片」分区：每个 tab / 预览器一张小卡片，独立开关（高亮启用态 + 品牌开关滑块）；二级设置经卡片底部「功能设置」条弹窗（开关 / 文本 / 数字 / 下拉）；插件自有设置持久化在 pluginSettings。	📱 移动端 窄屏（<768px）自动切换为全宽抽屉：底栏 tab 一次性并入右侧栏，触屏拖拽可调。

🌐 插件生态

ctx.betterSidebar 服务向所有插件开放两个扩展点：registerTab（注册侧边栏页面） 与 registerFileViewer（注册文件预览器）。内置的 7 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 }) => <DbView sessionId={scope.sessionId} />,
  }))
  ctx.effect(() => ctx.betterSidebar.registerFileViewer({
    id: 'my-plugin:csv', exts: ['csv'], fetchStrategy: 'custom',
    load: async (path, scope) => parseCsv(await fetchText(scope, path)),
    component: ({ customData }) => <CsvGrid rows={customData} />,
  }))
}

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

设置页「侧边卡片」内置「添加插件」弹窗：推荐目录 + 一键复制安装命令 + 直达 GitHub topic

📑 Tab 插件（注册侧边栏页面）

24 个插件（点击展开）

插件	⭐	简介
ChenRuoT/dsh-sidebar-qa		划选追问侧边页：类 Codex 侧边提问 / Claude Code /btw
fuhefei/dsh-sentinel		条件驱动唤醒系统：文件 / 命令 / HTTP / 进程 / Webhook 监视，到点唤醒 agent；dock + 侧栏分支 + 全局仪表盘
Fisfzy/ego-browser		Agent 浏览器：i18n 感知的本机浏览器 Tab（@dsh-external/ego-browser，装了 better-sidebar 自动注册侧边栏页，未装回退浮动浮窗观察）
jiuge2467/dsh-studio		全栈增强工作台：多源 MCP 可视化调试中枢、视觉思考引擎
Iwctwbh/dsh-flowglass		流镜 Flowglass：会话流程图实时可视化（消息 / 工具组 / 子代理分支）
FeatherHunter/dsh-mattpocock-skills-deck		mattpocock/skills 游戏化任务系统：地图拨迷雾、任务栏推进
GULI-lab/DSH-element-source		点击页面任意 UI 元素直达 Vue / React / Svelte / Angular 源码并送入会话
Lzh3070/dsh-file-review-tab		文件改动审查页：行级红绿 diff + 撤销 + chat 行深链
yq04/dsh-git-remotes		Git 远程页：分支 / 上游 / ahead-behind，fetch 可 prune、ff-only pull、确认后 push
ztyhehe/dsh-better-sidebar-svn		SVN 源码管理页：status / diff / log / commit / update / revert / 冲突解决，与内置 Git 面板对称
Melody-max114/dsh-excel-panel		Excel 编辑页：xlsx 预览 / 编辑、公式实时计算、合并单元格、保存回原文件
v587d/dsh-anysearch-refs		AnySearch 搜索结果引用卡片：搜索词、来源摘要、关键词高亮
mlosun/dsh-docs-panel		全局文档面板：随身 Markdown 笔记，任何工作区随时可读
lnyuqian/dsh-skill-sidebar		技能面板：扫描本机技能目录，4-6 字功能短语 + 一键复制调用 + 置顶
g-yixuan/dsh-sidechat		Codex 风格侧边对话 + 划选引用注释（轻量消费插件）
thirsty5034/dsh-ssh-tunnel		多主机 SSH 隧道 + SSH 管理器页
thirsty5034/dsh-git-forge		GitHub / Gitea 账号、项目授权与推送策略
YesSanSan/dsh-conversation-outline		对话大纲页：按轮次结构化展示、一键跳转、LLM 一句话标题
Wulabalabo/dsh-sidebar-Explorer-Plus		文件管理页：上传 / 移动 / 删除 / 重命名 / 新建文件夹（补全写操作）
yq04/dsh-turn-review		本轮审查：逐回合审查 agent 改动
Ghz114514/dsh-refpics		Pinterest 风格参考图搜索：瀑布流、侧栏画板、下载与 Eagle 收藏
yzlin499/dsh-yzlin499-easy-plugins		实用小工具集（毛坯房 DSH 友好）
dong-victor/dsh-better-sidebar-starter		运行配置页：IDEA 式 Run/Debug 配置（npm / springboot / python / custom）——一键启动、历史保存、WebSocket 实时日志（ANSI 彩色）、多实例并行、进程树跨平台杀死
baosfeng/my-dsh-plugins		个人多插件合集（dsh-file-activity）：侧边栏文件活动页——记录文件读取 / 新增 / 修改历史与统计，按文件夹平铺，点击用原生预览打开

🖼️ 预览插件（注册文件预览器）

3 个插件（点击展开）

插件	⭐	简介
HuanLinOTO/dsh-plugin-better-sidebar-plugin-office		Office 三件套预览（.docx / .xlsx / .pptx），独立 bundle 瘦身主体（官方推荐目录收录）
zemul/dsh-video-preview		视频内联预览：.mp4 / .webm / .mov / .mkv / .avi，自带 /video 路由支持 HTTP Range 拖进度条
dong-victor/dsh-better-sidebar-jupyter		.ipynb 可运行 Notebook 视图：懒启动 Python kernel、流式输出、保存回写

🧰 增强与工具

2 个插件（点击展开）

插件	⭐	简介
dong-victor/dsh-better-sidebar-terminal-plus		终端增强：内嵌 Nerd Font 图标字体、修复 xterm 图标渲染、稳定终端 cwd
Max-Null/dsh-sidebar-preview-select		预览划选增强：侧边栏预览里划选文本 → 浮动「发送到会话」

📣 上架你的插件：给仓库打上 dsh-better-sidebar topic 即出现在 topic 页；再向 src/client/plugins-tabs.ts / src/client/plugins-viewers.ts 提一条 PluginEntry PR，即可进入设置页内置推荐目录（数据完整性由 tests/plugin-list.spec.ts 守护）。

🆕 最近更新

支持的 DSH 版本： · 完整发布历史见 Releases

v0.16.1

自 v0.16.0 以来的全部更改：

🐛 修复

• 🧊 Git 面板卡死 + 重启死循环（#376，修复 #369）：开启「源代码管理」面板可能整页冻结、重启后自动恢复冻结状态且无法退出——三层无上限操作叠加所致，现已全部设界：① status 截断——git status --untracked-files=all 响应上限 2000 条（超限置 truncated，面板显示截断提示，对齐 fs.read 截断语义；worktree 变更计数同步有界），海量未跟踪文件不再冻结浏览器主线程；② 仓库发现限界——cwd 非 Git 仓库（如家目录）时不再对每个可见子目录串行无界探测：探测超时 30s→5s、子目录探测上限 200 个、并发请求共享同一次扫描并按 60s TTL 缓存，家目录不再引发 git rev-parse 进程风暴；③ 重置逃生通道——带 ?dsh-sidebar-reset 打开页面即丢弃持久化布局（含共享宽度）从默认布局启动，即使原页面已卡死也能自救，移除参数后恢复持久化；statusTruncated 文案同步全部 19 个词典

v0.16.0

自 v0.15.2 以来的全部更改：

✨ 新功能

• 🪟 自由窗口（#354）：把标签栏的任意 tab（内置或插件注册）拖到主会话区域——会话列出现虚线提示浮层，松开即成为悬浮窗口（默认 390×780，手机竖屏比例，创建时按视口钳制后居中于松点）；窗口支持头部拖动移动、右下角 SE 缩放（≥320×200）、点击任意处置顶、头部右键「回到侧边栏 / 关闭」、X 走 closeTab 正常关闭生命周期（释放终端等）；拖到侧边栏 pane 上时该 pane 高亮、松开即停靠合并回该 pane；floats 随会话持久化（刷新原样恢复，宽容 sanitize + 几何钳入视口）；服务语义：features 新增 'floatWindows'——openTab 的 dedupe/id 聚焦命中浮动 tab = 置顶窗口（不重复开、不展开面板），closeTab / activateTab 对浮窗正常关窗 / 置顶并照常触发回调，浮窗内 tab visible 恒 true，agent 终端 reconcile 覆盖浮窗；tab 内容复用常规渲染、插件 tab 与 pane 完全同契约；附带文件二级页面 8px 网格间距规整（设计文档）
• 📂 模型主动打开（sidebar_open 工具）（#353）：侧边栏新增全局设置 agentOpenTools（默认关闭），开启后向模型注入一个工具——模型可在调用方会话的侧边栏打开本地文件（editor tab，按 path 去重）、文件夹（全窗树窗口，以该目录为根，meta.dir）与 HTTP(S) 网页（browser tab，URL 预填）；关闭设置即注销工具并清空未投递队列，已打开 tab 保留；非激活会话的打开排队、下次可见时重放（/sidebar/ws/agent-opens 推送，同一 trust fence）；无新增公共 API、不改变 BetterSidebarService（设计文档）
• 📝 Markdown README 级内嵌 HTML + 目录大纲（TOC）（#360）：Markdown 预览现在真实渲染块级内嵌 HTML——徽章墙 <div align=center>、<details> 折叠块内嵌 markdown、表格单元格 <br/>/<sub>/<img>、<video>/<picture> 全部经 DOMPurify 白名单消毒（<script> 等活性内容剥除、<a> 强制 _blank rel=noopener），本地媒体 src 重写为会话媒体路由；≥3 标题出现浮动目录大纲按钮，点击平滑滚动并自动展开折叠 <details>，HTML 段内标题同样收录；渲染器仍是宿主 MarkdownText（shiki / KaTeX / GFM 保留），纯 markdown（零 HTML）文档走原路径零回归（设计文档）
• 🌏 第三语言覆盖（19 语言）（#339）：接入可选 peer @huanlin/dsh-plugin-better-locale——ja / de / fr / pt / ko / ar / hi / id / tr / vi / th / ru / it / nl / sv / pl / zh-HK / zh-TW / zh-MO 全量词典（每种约 340 keys）；覆盖借用 DSH 英文槽位（DSH active=en 时生效，zh 下完全惰性、界面不混语言）；19 语言词典同时注册进 better-locale，外部 ctx.locale.lookup('betterSidebar', key) 调用者同样可拿覆盖文本；未安装时 ctx.get('betterLocale') 为 undefined、整段 no-op，zh/en 行为不变
• 🌿 Git 多仓库选择 + linked worktree 变更发现（#326 #285）：会话 cwd 是工作区容器（非 Git 仓库）时自动发现直接子仓库并显示仓库选择器——status / 分支 / 历史 / diff / 暂存 / 提交 / 还原 / cherry-pick / 文件打开全部按所选仓库线程化；linked worktree 的变更发现与按工作树操作（含延迟分页响应的事务一致性），并拒绝过期 / 可修剪的 worktree 命令目标、对单库存取失败降级
• 🖥️ 浏览器本地回环允许清单（#365）：新增侧边卡设置 browserAllowedLoopback（逗号分隔 host 或 host:port；裸 host 匹配任意端口、带有端口精确匹配）——显式信任的本地开发服务器（如 Vite）可导航，并额外获得 iframe allow-same-origin 令牌（模块 / HMR / fetch 管线需要真实 origin，否则白屏）；页面相对 GUI 与其他站点仍是跨源；服务端 browser.probe 镜像同一允许清单，本地服务器不再被误拒
• 📝 编辑器 Vue + 28 种 legacy 语言语法高亮（#202）：.vue 映射 @codemirror/lang-vue（template / script / style 按 lang 属性分派、<style lang="scss"> 预处理器）；零新依赖用 legacy-modes 补齐 scss/sass/less/stylus/ruby/lua/perl/r/dart/scala/groovy/powershell/diff/protobuf/cmake/pug/tcl/haskell/clojure/erlang/julia/pascal/vb/vhdl/stex/objectivecpp；语言工厂抛错降级纯文本（console.warn），不再炸编辑器；.v / .m 跨语言歧义故意不映射
• 🔄 编辑器预览刷新三件套（#215 #228，修复 #167）：文本预览新增手动刷新按钮；编辑保存后切回预览自动重载（dirty 时抑制，草稿不丢）；预览模式下保存成功边沿自动重载；移除自动轮询与 fs.stat 版本端点（后台 API 零流量）
• 🖼️ Markdown 本地 / 相对图片（#292）：![alt](./img.png)、/cwd/img.png 与引用式 [id]: url 目标重写为 /sidebar/file 媒体 URL（会话 cwd 边界不变）——预览不再只显示 alt 文本
• ➕ 推荐插件目录新增 ego-browser（#340）：@dsh-external/ego-browser Agent 浏览器 Tab（会话侧边栏自动注册本机浏览器页，无 better-sidebar 时回退浮动浮窗）；描述词典 19 语言补全（#371）

🐛 修复

• 🛒 DSH 市场受管安装兼容（#338）：移除 peerDependencies 里的公开版 cordis（市场预览硬拒依赖字段出现 cordis，optional 无效）——npm 包满足 dsh-community-market 安装规范，dshfind / 1024Store 目录里的条目重新获得 repository_backlink 验证目标，可直接从 Desktop 市场受管安装
• 🔤 类型基底迁移到 @deepseek-ai/cordis（#338）：Context = 真实 vendored cordis Context 与结构化服务面的交集，ctx.betterSidebar 类型合并改挂 @deepseek-ai/cordis，公开版 cordis 不再被依赖。消费者迁移：import type { Context } from 'cordis' 改为 import type { Context } from '@deepseek-ai/cordis'（import type {} from 'dsh-better-sidebar' 的类型合并方式不变）；未使用该导入的插件无影响
• 🧩 插件树内 ctx.betterSidebar 读取全面修复（#357，修复 #356）：npm 安装的 DSH 0.1.1-rc.x（web bundle）下侧边栏页面每次加载即崩（cannot get property "betterSidebar" without inject）——26 处内部直读 ctx.betterSidebar 改走 ctx.get('betterSidebar')（root reflect store 解析，不受 fiber 链影响）；外部消费者 inject: ['betterSidebar'] + ctx.betterSidebar 契约不变
• 🔐 文件 API 会话工作区边界（#345，修复 #328）：fs.tree / fs.read / fs.write 的 workspace 越界访问修复；媒体、HTML 预览与上传统一 real-path 符号链接校验；新增绝对路径 / 符号链接 / 上传 / 嵌套 Git 会话回归测试
• 🪟 面板宿主层级与视口裁剪（#330 #278，修复 #277）：面板宿主层 z-index 40→25——低于 DSH cordis 动态插件面板 30，工作台不再遮挡 cordis 清单 / 审批面（AppFrame 20 之上、100+ 浮层之下）；宿主 overflow: hidden 裁剪视口边缘，收起的面板不再把文档撑出双向滚动（实测 scrollWidth 2289→1672 / scrollHeight 1280→1032，任意皮肤）
• 📐 布局推挤加固（#310 #130 #180）：对话列补 min-height: 0 + overflow: hidden + overflow-wrap: anywhere（长不可断 URL / OAuth 链接不再把 composer 与左侧设置按钮挤出视口）；layout-push effect 拆「仅设置 + 仅卸载移除」并按 panelOpen 门控宽度 push——右栏关闭时拖底部高度不再挤压对话区、松手瞬间不再整页右铺再回弹；useLayoutEffect 消除跨 paint 全宽闪帧；松手 flush 最终帧 + centerRect.right 同步提交；底部高度按 viewportHeight - PANEL_MIN 封顶；拖拽手柄拖动中不再高亮
• 📱 移动端无会话状态说明 + 1px 溢出修复（#254）：无会话时开关改用 aria-disabled 保持不可执行语义、同时允许触摸 / 键盘聚焦显示「选择一个会话以使用侧边栏」提示；panel 改 border-box——移动端 100vw 含左边框，不再产生 1px 横向溢出
• 📏 侧边栏宽度跨会话共享（#36）：面板宽度是布局偏好而非会话内容——「最后一次拖拽胜出」写入全局 dsh-sidebar:v1:width，缓存会话切换与新建会话即时跟随；无全局键（首次运行 / 旧会话）时行为逐字节不变
• 🧹 会话删除立即关闭该会话终端（#130）：新增 PtyManager.closeSession() + 订阅 DSH session/disposed——删除会话不再等 30s 重连宽限到期（agent 终端由 agent 生命周期管理，不受影响）
• 🔍 文件名搜索跳过噪声目录（#342）：node_modules / .pnpm-store / .yarn / .turbo / .next / dist / build / coverage 等黑名单（小写不敏感，.git 仍跳）——超大依赖树不再耗尽 10 万访问预算提前 truncated，docs/ 等后序目录里的真实文件能搜到；不引入 .gitignore 语义，保持「文件名查找」
• 📝 mermaid 全局错误渲染抑制（#341）：开启 suppressErrorRendering——非法图表不再把大错误 SVG 注入 document.body；组件级错误回退与源码展示保留
• 🖥️ 终端 Nerd Font 图标字体回退（#190）：starship / powerlevel10k 提示符的补充平面 PUA 图标（Nerd Fonts v3 Material 图标集）不再显示豆腐块——withIconFontFallbacks() 为胜出的基础字体追加 Nerd Font 图标族（插入首个通用族之前、按族名去重、过滤 CSS 全局关键字、不列彩色 emoji 字体）
• 🌐 HTML 预览 UTF-8 声明（#193，修复 #170）：/sidebar/html 响应带 charset=utf-8（无 <meta charset> 的中文片段不再乱码），保留原始文件字节
• 🧪 trust-fence Origin 改按 hostname 比较（#182）：Edge 151 把非默认端口 loopback 页面的 Origin 序列化为无端口形式——http://127.0.0.1 对 Host: 127.0.0.1:3080 不再 403（对齐 DSH 官方网关栅栏）；不同 hostname / opaque null origin 仍拒绝
• 🪟 「在文件夹中显示」改为资源管理器揭示（#94）：不再把目录当文件开进编辑器（"..." is a directory）——revealInExplorer 切到资源管理器 tab、面板折叠时自动展开、展开父目录并高亮滚动到本轮产出文件；产物行数据改读引擎 Turn deliverable（与 ui-deliverables 同源）
• 🖱️ 面板拖动布局闪烁（#180）：右侧栏关闭时拖底部高度不再左移挤压对话区；松手瞬间不再整体右铺再回弹
• 🖥️ PowerShell 安装脚本修复（#47）：远程入口统一为「下载脚本 → 移除 UTF-8 BOM → 内存执行」，-Version / -DryRun 参数在 Windows PowerShell 5.1 下恢复生效（BOM 解析不再吃掉首行 param(...)）；安装前校验 pnpm --version（主版本 <10 时明确报错并以退出码 1 结束，不再写一半 profile）
• 🔄 浏览器嵌入探测 GET 兜底（#69）：HEAD 响应同时缺 CSP 与 X-Frame-Options 时回退 GET 重试一次——阿里云百炼等只在 GET 回头发嵌入策略的站点不再显示误导性「拒绝连接请求」，而是正确显示「该站点拒绝嵌入」面板 + 「在浏览器中打开」
• 🔧 git 源安装修复 unrun devDependency（#336）：tsdown 0.22 经 unrun 加载配置而 pnpm 11 不自动装 peer——git-hosted 安装的 prepare 不再报 Failed to import module "unrun"（npm tarball 不受影响）
• 🍃 ctx.effect 严格化顺手修了 4 处：拦截注册失败时 effect 体返回 undefined 改为 no-op disposer（vendored cordis 的 effect 契约要求返回 disposer，返回 undefined 属非法形状）

💬 社区

推荐添加QQ群(577011007)

⌨️ 快捷键

🔌 服务化扩展

从 v0.4.0 起暴露 ctx.betterSidebar 服务，其他插件可注册侧边栏页面与文件预览器（内置 7 tab + 6 viewer 亦通过同一服务注册）。v0.12.1 补齐基座能力（完整类型导出、能力探测、状态订阅、tab 角标、生命周期回调、定向打开、插件自有设置等）。

完整接入文档：

• AGENTS.md——仓库内维护的接入文档（全字段、匹配算法、HMR 陷阱、声明式设置、版本探测）；
• docs/external-plugin-guide.md——面向外部插件开发者的接入指南（含完整最小示例）。

➕ 添加插件（推荐插件目录）

设置页「侧边卡片」两个网格末尾的虚线卡片分别打开 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/* devDependencies 已发布 0.1.1-rc.1，直接解析、无需令牌
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 原子写入；媒体/预览路由仅限会话 cwd 内文件；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；Markdown 预览提供手动刷新按钮，刷新未保存编辑前会确认是否丢弃草稿；无文件 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）。

🤝 参与贡献

• 代码改动走 PR：feat/* / fix/* 分支开发 → gh pr create；纯文档改动可直接推 main
• 收录生态插件：给仓库打 dsh-better-sidebar topic + 向 src/client/plugins-tabs.ts / plugins-viewers.ts 提 PR
• 提交前自检：pnpm typecheck && pnpm build && pnpm test（CI 另有 npm 打包 → 真实挂载 → 无头渲染门禁 pnpm test:mount）
• 仓库工作规范见 AGENTS.md（含仓库硬约束与 CI 说明）

⭐ Star History

👥 贡献者

感谢每一位贡献者：

🔗 友情链接

• 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 服务；官网