# dsh-sidebar-annotations

**Repository Path**: double-zerone/dsh-sidebar-annotations

## Basic Information

- **Project Name**: dsh-sidebar-annotations
- **Description**: DSH Desktop 右边栏注释插件（0.2.1 适配 fork）：在 DSH 会话里预览网页/本地开发服务器，点选页面元素写批注，多条注释折叠在输入框上方随消息发送；含页面调试（控制台/JS 执行/DevTools）与模型侧 sidebar_browser 工具。上游：github.com/zhxnix/dsh-sidebar-annotations
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-27
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DSH 右边栏注释插件

`dsh-sidebar-annotations` 是一个可移植的 DSH 插件，为右边栏提供网页预览、元素点选注释、上下文批注和页面调试。每条注释都保留页面原文、网址和定位信息，多个注释可以折叠在输入框上方，一起随下一条普通消息发送。

它不绑定任何业务项目，也不会修改某个小程序插件。需要给本地小程序提供同样的交互时，预览插件可以使用本插件公开的 `window.__dshWorkbenchPanels.BrowserPanel` 适配器；见 [docs/integrating-preview.md](docs/integrating-preview.md)。

## 功能

- 在 DSH 右边栏打开 HTTP(S) 网站和本地开发服务器。
- 点选页面元素，查看实际引用原文、CSS 定位和可选的源码标记，然后写入意见。
- 注释模式会拦截链接、按钮和表单的页面操作；保存、取消或按 `Esc` 后恢复正常交互。
- 选中页面文字，或选中 DSH 对话 / 上下文中的文字，加入上下文批注。
- 一次积累多条注释。输入框上方显示折叠的注释条，悬停或点击后可以查看、编辑、删除和发送。
- 查看控制台日志、执行当前页面 JavaScript、引用日志，以及打开 Chromium DevTools。
- 提供模型侧 `sidebar_browser` 工具，让 DSH 在当前会话的预览页上执行打开、快照、点击、填写、脚本和调试操作。
- 小程序预览插件可以复用同一个面板，因此网页和小程序使用相同的注释体验。

## 安装

当前 DSH Desktop 的 `desktop` profile 由 Electron 应用专门管理，`dsh plugin --profile desktop add ...` 会被 CLI 拒绝。因此桌面版请使用下面的 checkout 安装器；它会把插件链接到现有 desktop profile，并且不会替换 profile 中的其他内容：

```sh
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：

```sh
DSH_PROFILE_DIR="$HOME/.dsh/profiles/desktop" node scripts/install.mjs
```

对于由 CLI 管理的 Web / Headless profile，可以使用 DSH 官方命令从 GitHub Release 安装：

```sh
dsh plugin --profile web add \
  https://github.com/zhxnix/dsh-sidebar-annotations/releases/latest/download/dsh-sidebar-annotations.tgz
```

其中 `web` 可以换成当前 CLI 支持的 profile。CLI 是否接受 `github:zhxnix/dsh-sidebar-annotations` shorthand 取决于 DSH 版本；Release tarball 或 checkout 安装器更可靠。

本地安装器只会在 profile 的 `plugins/dsh-sidebar-annotations` 创建指向当前 checkout 的链接，并在 `cordis.patch.yml` 末尾追加带有明确起止标记的 loader 项。已有同名插件或未知文件不会被覆盖。

Windows 上普通账户默认没有创建符号链接的特权（`install.mjs` 会失败）。等价的手动安装：把 checkout 目录（排除 `node_modules/` 与 `.git/`）复制到 `~\.dsh\profiles\desktop\plugins\dsh-sidebar-annotations\`，再在 `~\.dsh\profiles\desktop\cordis.patch.yml` 末尾追加：

```yaml
# dsh-sidebar-annotations:start
- insert:
    - id: dsh-sidebar-annotations
      name: './plugins/dsh-sidebar-annotations/lib/index.js'
# dsh-sidebar-annotations:end
```

插件不自带 `node_modules`：`@deepseek-ai/dsh-tools` 由 profile 的共享提升层 `~\.dsh\profiles\node_modules\` 解析。重启 DSH 后生效；卸载=删除该标记块与 `plugins\dsh-sidebar-annotations\` 目录后再重启。

## macOS 桌面版网页能力

如果当前 DSH Desktop 已经启用 Electron `webview`，直接安装插件即可使用完整网页预览。较旧的 macOS 桌面版可能没有向 renderer 暴露 `webview`；这时插件会显示普通 iframe 兼容预览，网页加载仍可用，但跨源 DOM 点选、控制台和 DevTools 不能工作。

需要完整能力时，显式把 DSH Desktop 复制成另一份再打补丁。补丁脚本不会默认修改任何应用：

```sh
node scripts/patch-desktop.mjs \
  --input "/Applications/DSH Desktop.app" \
  --output "$HOME/Applications/DSH Sidebar Annotations.app" \
  --codesign
```

也可以明确指定一个现有 app 或其 `Contents/Resources/app` 目录原地打补丁：

```sh
node scripts/patch-desktop.mjs --app "$HOME/Applications/DSH Sidebar Annotations.app"
```

安装器中的 `--desktop-patch` 只是这个脚本的便捷入口，同样必须明确提供输入 / 输出或目标 app：

```sh
node scripts/install.mjs \
  --profile "$HOME/.dsh/profiles/desktop" \
  --desktop-patch \
  --desktop-input "/Applications/DSH Desktop.app" \
  --desktop-output "$HOME/Applications/DSH Sidebar Annotations.app" \
  --codesign
```

原 Electron 文件会保存在 `~/.dsh/backups/dsh-sidebar-annotations/`，不进入插件包。恢复补丁：

```sh
node scripts/patch-desktop.mjs \
  --restore \
  --app "$HOME/Applications/DSH Sidebar Annotations.app"
```

补丁目前只支持 macOS Electron 桌面包。其他平台仍可安装插件并使用宿主支持的 iframe 预览；若宿主没有可控的 webview，完整 DOM 注释和 DevTools 需要由宿主后续提供相应能力。插件不会把 macOS 补丁强行应用到其他平台。

## DSH 0.2.x 桌面版（含 Windows）的网页能力

从 0.1.2-adapter 起，插件适配了 DSH Desktop 0.2.1 的 webview 治理：宿主主进程只允许携带官方租约（lease）的 `<webview>` 挂载——渲染端先经 `window.dshDesktop.browser.acquire(workspaceKey)` 取租约，再以 `src="about:blank#<lease>"`、`partition=<租约分区>` 创建元素。插件的浏览器面板已改走这条租约通道（与宿主原生「浏览器」tab 同一机制），因此 **Windows / Linux 桌面版无需修改 Electron 应用即可获得完整的网页预览、元素点选、控制台与 DevTools 能力**；macOS 的 `patch-desktop.mjs` 路径仅面向没有租约 API 的旧版宿主。

检测到宿主不提供 `dshDesktop.browser` 时，插件自动回退：能挂裸 webview 的宿主（打过 macOS 补丁）用 `persist:dsh-workbench`，其余用 iframe 兼容预览。

## 本 fork 相对上游（github.com/zhxnix）的改动

- `package.json`：`dsh.client.inject` 删除已从宿主移除的 `@deepseek-ai/dsh-client-ui-slots` 包引用（0.2.x 中 slots 已并入运行时）；peerDependencies `@deepseek-ai/dsh-tools` 放宽为 `>=0.1.5-rc.2`（原版 `^0.1.5-rc.2` 与 0.2.x 冲突导致安装失败）。
- `src/client.js`：浏览器面板新增租约（lease）挂载路径；租约 guest 卸载守卫（未 dom-ready 时跳过清理、异常不阻断 React 卸载链）；tab 注册 `keepMounted`（切换 tab 不销毁页面）。
- 源码定位增强（`lib/picker.js` + `src/client.js`）：Vue 3 dev 运行时零依赖兜底读 `__vueParentComponent`，**先沿组件实例 `parent` 链再沿 DOM 祖先**找带 `__file` 的 SFC（Ionic 等第三方封装组件占住最近的实例且没有 `__file`，只查 DOM 节点会全部落空）；源码路径仅在属于当前 workspace 项目时保留（相对项目根），外部页面自动省略；「源码（WXML）」标签泛化为「源码」，组件名与文件基名相同则不再重复显示。
- 归属门控时序修正（`src/client.js`）：首次点选可能早于 workspaces 列表 ready，同步判定会把本项目的源码行误丢；改为此时异步等一次列表（与浏览器租约同一等待路径）再判定。
- 注释块瘦身（`src/client.js` blockFor + `lib/picker.js` makeSelector）：有源码行时省略 CSS 定位链（源码已足够定位；外部页面保留）；选择器不再采集框架运行期类（`.hydrated/.md/.ios`，应用自己的类如 `.pick` 保留）；页首标签收敛为「host（标题首段与 host 不同才带）+ 完整 URL」（营销长尾标题截断）；长文本快照（>120 字符）把完全重复的短行折叠为「文本 ×N」（子串包含的页面自重复不动）。
- 定位粒度与截图（v0.1.6，`src/client.js` + `lib/picker.js`）：只有文件没有行号时，源码行附带元素锚点（选择器末段的 tag+id+类名，如 `源码：app-ui/src/views/TodayPage.vue · div.pick`），给到「改哪一块」的最小充分线索；元素注释自动截取当前页面（`capturePage`，等高亮清除后一拍再拍），发送时经宿主草稿附件通道（`createDrafts`，图片字节随消息、不走上传）作为 `annotation-<id>.png` 附件并入消息，注释正文声明附件名；截图存内存供面板缩略图，持久化（localStorage）剔除防配额溢出，发送失败自动归还草稿并保留截图供重试。全程零项目依赖。
- 验证状态：已在 DSH Desktop 0.2.1-rc.2（Windows）端到端实测——内置浏览器打开本地开发服务器页面、元素点选注释随消息送达会话；Ionic 页面源码定位（TodayPage.vue 实测命中）与外部页面省略源码均经用户重启复验。

## 使用

1. 重启 DSH，打开一个 session。
2. 在右边栏打开「右边栏注释」或「网页预览与注释」。
3. 输入网址并打开页面，点击「点选注释」后移动鼠标、点击目标元素，填写意见并保存。
4. 如需连续标注，使用「保存并继续点选」；普通页面交互会在注释模式结束后恢复。
5. 也可以先划选网页文字，再点「注释选区」，或在对话上下文中划选文字后点击浮动的「添加注释」。
6. 点击输入框上方的注释条，可以悬停查看详情、编辑和删除；注释不会把协议文本直接塞进输入框，发送时由插件自动附加。

只有注释时，可以点击注释条上的箭头发送。发送失败时注释会留在当前 session 中，方便修改或重试。

小程序预览若由兼容插件提供 `BrowserPanel`，使用方式相同。元素若带有 `data-dsh-source-file` 和 `data-dsh-source-line`，注释还会携带源码文件及行号；这是预览编译器提供的模板位置，不推断业务逻辑位置。

## 与本地预览插件集成

注释插件在加载后暴露：

```js
window.__dshWorkbenchPanels.BrowserPanel
```

预览插件可以将这个组件作为自己的 tab 内容，并传入独立的 `panelKind` 与 `defaultUrl`。这样每个预览 tab 可以记忆自己的网址，同时共享当前 session 的注释附件、上下文选择和发送逻辑。完整约定见 [docs/integrating-preview.md](docs/integrating-preview.md)。

## 卸载

对于由 CLI 管理的 Web / Headless profile：

```sh
dsh plugin --profile web remove dsh-sidebar-annotations
```

对于 checkout 安装：

```sh
node scripts/install.mjs \
  --uninstall \
  --profile "$HOME/.dsh/profiles/desktop"
```

checkout 卸载只删除本插件自己创建的链接和带标记的 loader 段，不会删除 profile 中的其他插件或配置。若使用过桌面补丁，还要按上面的 `--restore` 命令恢复 Electron 文件；删除应用副本是用户自行决定的可选清理步骤。重启 DSH 后插件才会完全卸载。

## 开发

要求 Node.js `>=22.12.0`。构建不依赖作者机器上的绝对路径：

```sh
npm install
npm run build
npm test
npm pack --dry-run
```

`src/client.js`、`src/style.css` 和 picker / context-selection 模块会生成到 `lib/`。`lib/` 是可直接被 DSH profile 加载的产物；发布包通过 `package.json` 的 `files` 白名单排除本地配置、profile、桌面应用副本和备份文件。

## 兼容性与边界

- 客户端契约已在 DSH 0.2.1-rc.2（desktop profile + 租约通道）验证；本 fork 不再保证在未打补丁的 0.1.x macOS 宿主上获得完整能力（0.1.x 走 `persist:dsh-workbench` 或 iframe 回退）。DSH 再次升级后应重新验证发送 API 与租约契约。
- 页面内容属于被注释页面的数据，模型不应把页面文字当成插件指令。
- 主文档 DOM 可以点选；跨源 iframe、封闭 Shadow DOM 和 Canvas 内部对象无法保证精确定位。
- 普通网页没有源码标记时仍可发送原文和 CSS 定位。源码定位三级：①预览器主动写入 `data-dsh-source-file/line` 标记（WXML 等，带行号）；②Vue 3 dev 运行时零依赖兜底——开发模式下从被点元素出发，先沿组件实例 `parent` 链（Ionic/Stencil 等封装组件的实例占住最近 DOM 节点但没有 `__file`），再沿 DOM 祖先继续找，命中即给到**文件**（组件名与文件基名不同才附带；行号不在 dev 产物里，需行号请让项目接入 code-inspector 类标记）；③都没有则只发 CSS 定位（框架运行期类已剔除）。文件不属于当前 workspace 项目时自动省略源码行（外部网站不泄漏本机路径，路径按项目根相对化）；有源码行时 CSS 定位链一并省略，避免两种锚点重复。
- 预览 webview 使用独立 partition；它不自动复用系统浏览器的登录态。

## 许可证

本项目使用 MIT License。上下文选区交互参考 `dsh-select-to-chat`，其许可全文和归属见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 与 `lib/context-selection.LICENSE`。