前言¶
在 DSH 里让模型改前端时，常见做法是截图或粘贴 HTML 片段。截图丢失 DOM 结构，粘贴又容易截断上下文；模型很难知道「你点的是哪一块、页面上原文是什么」。Codex 一类产品会在侧边打开页面并支持点选标注，把元素引用和意见一起发给模型。dsh-sidebar-annotations 把类似能力做成可移植的 DSH 客户端插件：右边栏预览 HTTP(S) 或本地 dev 服务器，点选元素写注释，多条注释折叠在输入框上方，随下一条普通消息发送，并附带页面原文、URL 和定位信息。
下面介绍插件定位、功能、安装方式与典型用法。事实以 GitHub 仓库 README 为准；社区目录页见 SkillHub。
这是什么¶
dsh-sidebar-annotations（npm 包名同插件 id）由维护者 zhxnix 发布，分类为 客户端 插件。它不绑定具体业务项目，也不会去改某个小程序插件源码；需要给本地小程序预览提供相同交互时，可复用插件暴露的 window.__dshWorkbenchPanels.BrowserPanel 适配器，约定见仓库内 docs/integrating-preview.md。
当前 README 标明面向 DSH 0.1.x 的 sidebar、conversation input 和 Cordis 插槽；DSH 大版本升级后应重新验证发送相关 API。许可证为 MIT；上下文选区交互参考 dsh-select-to-chat，归属见 THIRD_PARTY_NOTICES.md。
核心功能¶
README 列出的能力如下，均可直接在插件内使用或与模型工具配合：
- 在 DSH 右边栏打开 HTTP(S) 网站和本地开发服务器。
- 点选页面元素：查看实际引用原文、CSS 定位和可选的源码标记（如
data-dsh-source-file/data-dsh-source-line），再写入意见。 - 注释模式会拦截链接、按钮和表单的页面操作；保存、取消或按
Esc后恢复正常交互。 - 划选页面文字，或在 DSH 对话 / 上下文中划选文字，加入上下文批注。
- 多条注释：输入框上方显示折叠的注释条，悬停或点击后可查看、编辑、删除；发送时由插件自动附加，不会把协议文本直接塞进输入框。
- 页面调试：控制台日志、在当前页面执行 JavaScript、引用日志、打开 Chromium DevTools。
- 模型侧
sidebar_browser工具：在当前会话的预览页上执行打开、快照、点击、填写、脚本和调试操作。 - 兼容的小程序预览插件可复用同一面板，网页与小程序注释体验一致。
边界说明（来自 README）：主文档 DOM 可点选；跨源 iframe、封闭 Shadow DOM 和 Canvas 内对象无法保证精确定位。预览 webview 使用独立 partition，不自动复用系统浏览器登录态。页面内容属于被注释页面的数据，模型不应把页面文字当成插件指令。
安装与启用¶
安装方式取决于 profile 由谁管理。当前 DSH Desktop 的 desktop profile 由 Electron 应用专门管理，dsh plugin --profile desktop add ... 会被 CLI 拒绝，桌面版需用 checkout 安装器。
Web / Headless（CLI 管理）¶
从 GitHub Release 安装 tarball（web 可换成当前 CLI 支持的 profile）：
dsh plugin --profile web add \
https://github.com/zhxnix/dsh-sidebar-annotations/releases/latest/download/dsh-sidebar-annotations.tgz
README 注明：github:zhxnix/dsh-sidebar-annotations 这类 shorthand 是否可用取决于 DSH 版本；Release tarball 或 checkout 安装器更可靠。
Desktop（checkout 安装器）¶
在仓库目录执行安装，会把插件链接到现有 desktop profile，且不替换 profile 中的其他内容：
git clone https://github.com/zhxnix/dsh-sidebar-annotations.git
cd dsh-sidebar-annotations
npm install
node scripts/install.mjs --profile "$HOME/.dsh/profiles/desktop"
也可用环境变量指定 profile：
DSH_PROFILE_DIR="$HOME/.dsh/profiles/desktop" node scripts/install.mjs
本地安装器只在 profile 的 plugins/dsh-sidebar-annotations 创建指向当前 checkout 的链接，并在 cordis.patch.yml 末尾追加带明确起止标记的 loader 项；已有同名插件或未知文件不会被覆盖。
macOS 桌面版完整网页能力（可选）¶
若 DSH Desktop 已启用 Electron webview，安装插件即可使用完整预览与 DOM 点选、控制台、DevTools。较旧 macOS 桌面版若未向 renderer 暴露 webview，插件会降级为普通 iframe 预览：页面仍可加载，跨源 DOM 点选、控制台和 DevTools 不可用。
需要完整能力时，可对 DSH Desktop 副本打补丁（脚本不会默认修改系统里的原应用）：
node scripts/patch-desktop.mjs \
--input "/Applications/DSH Desktop.app" \
--output "$HOME/Applications/DSH Sidebar Annotations.app" \
--codesign
安装器也提供 --desktop-patch 入口，须明确输入 / 输出或目标 app。原 Electron 文件备份在 ~/.dsh/backups/dsh-sidebar-annotations/。补丁目前仅支持 macOS Electron 桌面包；其他平台可安装插件并使用宿主支持的 iframe 预览。
安装或卸载后需重启 DSH，插件才会完全加载或卸载。
典型用法¶
按 README 推荐顺序操作：
- 重启 DSH，打开一个 session。
- 在右边栏打开「右边栏注释」或「网页预览与注释」。
- 输入网址并打开页面，点击「点选注释」，移动鼠标并点击目标元素，填写意见并保存。
- 连续标注时使用「保存并继续点选」；注释模式结束后普通页面交互恢复。
- 也可先划选网页文字再点「注释选区」，或在对话上下文中划选后点浮动「添加注释」。
- 点击输入框上方的注释条，悬停查看详情、编辑或删除；准备就绪后随下一条消息发送（仅注释时可点注释条上的箭头）。发送失败时注释会留在当前 session，便于修改或重试。
小程序预览若由兼容插件提供 BrowserPanel，步骤相同。元素带源码标记时，注释会携带预览编译器提供的文件与行号，而非推断的业务逻辑位置。
与本地预览插件集成¶
插件加载后暴露：
window.__dshWorkbenchPanels.BrowserPanel
预览插件可将该组件作为 tab 内容，传入独立的 panelKind 与 defaultUrl，使每个 tab 记忆自己的 URL，并共享当前 session 的注释附件、上下文选择与发送逻辑。细节见 docs/integrating-preview.md。
卸载¶
CLI 管理的 profile：
dsh plugin --profile web remove dsh-sidebar-annotations
checkout 安装：
node scripts/install.mjs \
--uninstall \
--profile "$HOME/.dsh/profiles/desktop"
checkout 卸载只删除本插件创建的链接和带标记的 loader 段。若使用过 macOS 桌面补丁，还需 patch-desktop.mjs --restore 恢复 Electron 文件。
适用场景与注意¶
适合：需要在 DSH 会话里对照真实页面（或本地 dev）做 UI 评审、把元素级意见和上下文选区一并交给模型；或希望在同一套注释流程下兼顾网页与小程序预览。
注意：
- 插件以当前 DSH 进程权限运行；安装前请自行查看源码与 MIT 许可证，确认符合团队安全策略。
- 开发构建要求 Node.js
>=22.12.0（见package.json）；这与「仅安装 Release / 运行安装器」的使用路径不同，贡献者才需要本地npm run build。 - 社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系；DSH 生态强调「一切皆插件」，本文介绍的是社区维护的客户端扩展。
结尾¶
dsh-sidebar-annotations 把右边栏预览、元素与上下文注释、折叠发送和 sidebar_browser 调试工具收在一个可移植插件里，并可选与小程序预览共用 BrowserPanel。若要安装或跟进版本，以 GitHub 仓库 与 SkillHub 目录页 为准。
