它是什么：一半是插件，一半是基座
dsh-better-sidebar 是一个 npm 包，内部由 host 与 client 两半组成。host 半跑在 DSH 进程里，对外开出一组会话级路由：/sidebar/api/* 的 JSON 接口、/sidebar/file 媒体路由、/sidebar/html 预览路由，以及 /sidebar/ws/terminal 终端 WebSocket，整体套在与 /api 相同的 Host 头信任围栏之后。client 半是 DSH 加载进页面的 web client；包在自己的 dsh 字段里声明了 bundle.patch，也就是说「把包装进 profile」本身就是它的用途。
有一点必须说清楚：从 v0.19.0 起，它不再自绘右侧那一列。插件的 tab 类型与 tab 体改为注册进 DSH 原生的右侧栏，聊天里打开文件统一走 dsh-resource://file/…，旧的自由浮窗 API 也在同一版里退役。它仍然自己持有的是底部工作台——一棵按会话持久化的分栏树。
同时它对外提供一个 Cordis 服务 ctx.betterSidebar：其他插件通过 registerTab 与 registerFileViewer 注册侧边栏页面和文件预览器，v0.19.0 起还多了 registerFileIcon。内置的 8 个 tab 类型与 6 个预览器走的是同一套 API，所以第三方页面在这里不是二等公民。
装完之后你实际得到什么
按 README 自己的说法，这是「一个服务化的侧边栏框架 + 一套开箱即用的工作台」。具体到功能：
- 文件工作台：懒加载目录树（软链接按目标类型展示、失效链接标红，UNC 路径也做了统一处理），配 CodeMirror 编辑器与常见语言高亮；另有全局文件名搜索、上传与拖拽、右键菜单，以及把路径引用进输入框的行尾
@文件按钮。文件与目录图标是彩色的，图形来自 DSH 自己的ui-primitives。 - 预览：图片、Markdown（Mermaid 走懒加载渲染器，
securityLevel: 'strict'；README 级内嵌 HTML 经 DOMPurify 消毒；带浮动大纲）、HTML（同路由沙箱 iframe）、PDF（浏览器原生查看器）。另有一层敏感内容脱敏：凭据形态的路径整文件遮罩、普通文件按内容形态遮值，默认开启，且只影响显示。 - 文件变动：一个 tab 里两个视角。Git 视角有真 diff、历史、暂存、提交与还原；本轮文件视角实时追踪模型读过、写过、编辑过的每个文件。diff 是统一渲染，含配对改色、行内字符级高亮与语法着色。
- 真实终端：xterm.js 接 node-pty，是真 shell 而不是模拟器；断线重连会回放 transcript，shell 与 shell 参数可配置，也能选择给模型注入
terminal_*工具。 - 内嵌浏览器：多开网页 tab，带后退/前进/刷新与地址栏，内容跑在不透明源沙箱 iframe 里，界面实时显示沙箱状态。
- 任务页：子代理拓扑，加一张后台任务清单（退出码、实时输出、强制终止）。
- 侧边对话（beta）：一条独立线程，继承主会话上下文（进行中的回合会以便于理解的方式冻结并标记为 interrupted），不进入主会话，可一键提升为顶层会话。
- 其余是声明式设置、布局与 tab 的按会话持久化，以及跟随 DSH 语言的界面文案。
面向模型的入口目前有两个，都要在设置里打开：sidebar_open（模型可主动在侧边栏打开文件、文件夹或 HTTP(S) 网页）与上面的终端工具。这是来源里写明的模型侧能力，不等于穷尽清单。
其他插件在用的那套注册接口
ctx.betterSidebar 是这个插件影响面最大的部分。它 v0.4.0 就有了，v0.12.1 补齐基座能力（完整类型导出、能力探测、状态订阅、tab 角标、生命周期回调、插件自有设置），v0.19.0 再加文件图标注册。接入方在自己的 inject 里声明服务，并在 ctx.effect(...) 里注册，卸载时 tab、预览器或图标随之消失。
图标匹配是有优先级的：精确文件名 > 扩展名 > 目录名，folder 与 folder-open 是保留的目录扩展名。注册前值得知道一个坑：exts: [] 的 catch-all 会接管内置分类器没有具体命中的所有路径。
这套设计的代价是版本耦合：README 让接入方去读仓库里的外部插件接入指南，并希望生态用这个 API，而不是用某种更聪明的 DOM 覆盖。
安装与前置条件
- DSH 需要 0.1.5-rc.1 或更新。 v0.19.1 在 DSH 0.1.5-rc.2 上完成真机挂载验证，rc.1 用户不必升 DSH 也能用同一版。老宿主必须钉老版本线：DSH 0.1.5-alpha.2 用
0.19.0-alpha.1；0.1.2-rc.1 稳定线用0.18.x；DSH 停在 0.1.1-rc.2 或更早则用0.17.1。版本配错是「装上了但行为不对」最常见的来源。 - Node.js ≥ 20、pnpm ≥ 10，并且
dsh web能正常跑起来。 - 安装不是一步。 第一次会失败，因为 pnpm 11 拦截了
node-pty的构建脚本；README 给的解法是在 web profile 目录里放行构建脚本后重跑安装（它说那时依赖已经写进去了）。此外还有一键脚本和 registry 两条可选通道，README 提醒两条通道同时开会双挂载。 - 装完要硬刷新浏览器（Cmd/Ctrl+Shift+R）。client 改动是热加载，host 半更新才需要重启 DSH。
node-pty是原生模块，优先用你 Node 版本对应的预编译二进制，否则需要编译工具链：Windows 的 VS Build Tools、Linux 的 make/g++/python3、macOS 的 Xcode CLT。好消息是它不再拖垮 server——node-pty缺失时插件照常挂载，终端以带修复命令和重试按钮的横幅呈现。
已知限制
- Git 是残缺的：没有 push、pull、fetch，远程操作交给另外的生态插件。请把它读作本地源代码管理，而不是一个 Git 客户端。
- Office 预览不是内置的：
.docx/.xlsx/.pptx已移到独立的第三方插件；没装的话这类文件走代码或下载查看兜底。 - 没有文件 watcher，也没有自动轮询。Markdown 预览只有手动刷新按钮，而且刷新前会确认是否丢弃未保存草稿。
- HTML 预览渲染的是已保存的文件，不反映编辑器里的草稿。
- 终端 tab 拖到另一个分栏会重挂载，也就是 shell 会重开。
- 内嵌浏览器没有登录态：第三方 Cookie 受限，被
X-Frame-Options/frame-ancestors拒绝嵌入的站点会显示原因面板和「在浏览器中打开」；地址栏本身拒绝javascript:、data:、file:与本机回环地址。 - 沙箱可以关掉。页面内容默认在沙箱里，但设置页能按功能关闭它（带警告文案），关掉后内容与界面同源。请把这个开关当成真正的安全边界对待，README 的警告也只针对完全可信的内容。
- 三平台验证程度并不齐：macOS 是日常验证，Windows 与 Linux 只由单元测试覆盖。跨平台测试全绿和每天真机用，不是同一种证据，来源也没有多声称什么。
- 窄屏（<768px）没有底部面板：它的标签一次性并入右侧栏，以全宽抽屉呈现。
什么情况下该用，什么情况下不该用
如果你想要的是「在对话旁边摆一套 IDE 式工作面」——读改文件、看 diff 落地、开一个 shell、盯子代理、不离开 harness 就打开网页——那么值得装。另一个更明确的理由是：你正在写一个需要侧边栏页面或文件预览器的 DSH 插件。这目前就是大家共用的注册面，基于它做的 tab 会和内置页面一起落在 DSH 原生右侧栏里。
不要因为「DSH web 界面有点空」就装它。如果你要的就是 DSH 自带的那点东西，这个插件的价值在多出来的 tab、预览器和那套扩展服务，而不在把界面换成另一种样子。
不要把它当成信任边界。README 写明的是：路由受 Host 头围栏保护、文件写入是原子的、媒体与预览路由限定在会话工作目录内、git 只调 CLI 且绝不设置身份、预览路径有沙箱——但它没有写审计、没有写认证、也没有写审核流程。本页把安全状态标成 unverified，就是这个意思。
也不要默认它是离线的。来源里没有遥测、没有 analytics、没有隐私政策；而内嵌浏览器和地址栏的存在，本来就是为了访问别的站点。没有遥测声明，不等于承诺没有遥测，这是一个悬而未决的问题。
最后，别为了 Git 远程操作或 Office 文档装它。这两件事是被有意交给生态插件的，它不会替你做。
FAQ
它是插件还是基座？
两者都是。一个包里装了两半，host 半对外发布 ctx.betterSidebar，其他插件据此注册自己的 tab、文件预览器与文件图标。内置页面走的是同一套 API，所以 README 用的说法是「能力完全对等」，而不是「在插件之上再加一层」。
它会替换 DSH 的侧边栏吗？
v0.19.0 之后恰好相反：它不再自绘右侧面板，而是把 tab 注册进 DSH 原生右侧栏，顺手退役了旧的浮窗方案。它自己保留的是底部工作台。更早的版本行为不同，所以如果你钉的是老版本，这段描述不适用。
能用 Git 面板 push、pull 或 fetch 吗？
不能。README 把「Git 无 push/pull/fetch」写在已知限制里，并明确把远程操作留给独立插件。暂存、提交、还原、历史与 diff 才是它文档化的 Git 能力面——这是有意划的界，不是没做完。
它会上报遥测、或者把我的代码发出去吗？
来源里没说。README 没有提到遥测、analytics、隐私政策，也没有提到插件自身发起的外发请求，本页不会把这份沉默翻译成承诺。你能观察到的网络行为是：当你在内嵌浏览器里打开某个站点，或让侧边栏加载模型请求的网页时，那些请求是替你发的，属于你的流量，而不是文档化的遥测上报。这个问题请按「未说明」处理。
为什么第一次安装会失败？
因为 pnpm 11 拦截了 node-pty 的构建脚本，这次失败是预期行为，不代表包坏了。README 的修法是在 ~/.dsh/profiles/web 下放行构建脚本，然后重跑安装。如果之后终端提示 node-pty 加载失败，同样是「放行 + rebuild」这套修复，再重启 DSH 并点重试。