前言¶
在 DSH 里审阅代码或文档时，常见流程是：打开右侧文件预览，发现一个问题，把位置描述成文字粘进输入框。问题在于，描述“第几行附近有别扭”这件事本身很费字，而且粘贴后和原文已经断了关联，读消息的人只能靠猜。
对比已有做法：Better Sidebar 的「添加到对话」插入的是文件名与行号，适合整段上下文；想做具体的局部评论，就得自己打引用文字。dsh-file-annotations 走的是另一条路——在预览里直接圈选文字或区域，写成带坐标和裁剪图的批注，排在输入框上方随消息一起发出。
这是什么¶
DEVbyQIN 维护的 DSH 客户端插件，名称为 dsh-file-annotations，当前版本 0.6.2，节点要求 ^22.19.0 || >=24。它把“预览期间的临时草稿”编译成可发送的引用，解决的是：标注位置和评论内容要么丢失、要么退化成一大段手打文字。
需要说明的是，批注是预览期间的草稿，侧边栏收起、切换标签页或切换会话时会保留；确认关闭预览后，该文件的 JSON、localStorage、待发送卡片、蓝色引用和图片预览缓存会被清理，10 秒内可点「撤销」。
核心功能¶
文字批注¶
TXT、JSON、Markdown、源码等可选文字预览，以及带可选文字层的 PDF 支持文字批注。兼容 Better Sidebar 的 CodeMirror 编辑器，文件内容区的选字可以批注；搜索框等普通输入框不弹批注。
选中文字后，文字与代码文件上的「批注」和 Better Sidebar 的「添加到对话」显示为同一个选区工具条，后者保留原有文件、行号和插入行为。Better Sidebar 打开的 HTML 可以在渲染网页中直接选字，也可以点「选元素」再点段落、标题或图片，对整个元素加批注。跨 DOM 片段和跨行文字按完整引用匹配，保存偏移、上下文和 PDF 页码。网页仍使用原有沙箱，不开启同源访问，也不提供 OCR。
区域批注¶
PDF、图片、HTML 预览头部提供「框选」。拖拽接收层只覆盖内容可见部分，标签栏和退出按钮仍可操作；松手后出现输入条，保存后在区域上显示框和编号，Esc 或再点框选按钮退出。写评论期间保留虚线框，取消则清理。
PDF 页码读取预览器的真实页标记，未渲染页不借用相邻页的画布。PDF 和图片裁剪为 PNG；HTML 保存元素选择器、引用文字及元素内坐标，不提供裁剪图。旧版 HTML 只存视口坐标，无法可靠推断原元素，旧记录保留在历史中，新旧记录不会被自动改写。
待发送列表与历史¶
批注保存后出现在主输入框上方的待发送列表，按当前会话隔离。可以折叠列表、编辑评论、移除批注，或点文件名打开原文件。输入框里有一枚简短的「文件批注」引用，发送时展开为本轮批注的文件路径、引用或区域坐标、评论和裁剪图路径。保存批注不会自动发消息。
删除蓝色引用等价于把本批批注移出待发送列表，其他消息文字和批注历史保留，刷新后也不会自动加回；需要恢复时，在文件头部的「批注」历史中点「加入待发送」。宿主确认接收后批注移入历史，提交失败则保留批注并由 DSH 恢复文字草稿，可修改后重试。
存储¶
<工作区>/.dsh/annotations.json
<工作区>/.dsh/annotations/crops/<批注 id>.png
存储格式仍为 version 2，兼容已有记录。一条记录包含 id、sessionId、path、rel、quote、comment、createdAt，以及可选的 anchor、htmlAnchor、region、crop、sentAt、detached。其中 sentAt 表示宿主已接收该批消息，不代表 AI 已处理完成。
宿主路由均为 POST，位于 /api/dsh-file-annotations/ 下，覆盖 resolve、read、write、crop、crop-preview。缩略图读取只接受工作区和批注 id，不接受任意文件路径。
安装与启用¶
桌面版在 DSH 中打开「插件 → 添加插件 → 安装已有插件」，输入 dsh-file-annotations 或 github:DEVbyQIN/dsh-file-annotations，安装并启用，卸载同样在应用内插件管理器操作。npm 包地址为 https://www.npmjs.com/package/dsh-file-annotations。
Web 版安装命令：
dsh plugin --profile web add dsh-file-annotations@0.6.2
# 或从 GitHub 安装同一版本
dsh plugin --profile web add 'github:DEVbyQIN/dsh-file-annotations#v0.6.2'
安装后重启 DSH。卸载：
dsh plugin --profile web remove dsh-file-annotations
典型用法¶
下面按插件文档里的使用流程走一遍。
- 打开右侧文件预览。选中文字后点选区旁的「批注」，或在 PDF、图片、HTML 预览中点「框选」并拖出区域。
- 输入评论并保存。批注出现在主输入框上方的待发送列表，按当前会话隔离。关闭会清理批注的文件预览前会弹出确认，点「取消」或按 Esc 可继续批注；没有批注时直接关闭。
- 在列表中核对引用、评论和区域缩略图，可编辑或移除。
- 在原生输入框补充总要求，再点 DSH 的发送按钮或按 Enter。只有批注、没有额外文字也可以发送。
- 宿主确认接收后，本次批注移入历史；失败则保留批注并恢复文字草稿，可修改后重试。
PDF 默认保持阅读和选字。手动开启框选后，写批注时暂停框选，保存或取消后可继续框选下一处；切换文件或会话会退出框选。PDF 预览的虚线矩形图标用于开启和退出框选，开启时变蓝，旁边的「打开 PDF 时默认框选」可设为自动或手动，设置会记住并应用于以后打开的 PDF，初始为手动。
快捷键方面，macOS 桌面首次加载时会将打开文件改为 ⌘O、选区批注改为 ⌘P；网页端保留 ⌘⇧E（Windows 为 Ctrl+Shift+E），Linux 网页端默认不绑定。输入条内 ⌘Enter / Ctrl+Enter 保存当前批注并发送本会话全部待发送批注。
适用场景与注意¶
适合需要围绕文件局部内容提问、评审或讨论的场景，尤其是 PDF、图片、HTML 预览中这类无法用行号表达的区域。
以下几点在安装前应该看清：
- 插件以当前 dsh 进程的权限运行，宿主接口暴露了读写工作区和生成裁剪图的能力。安装前应打开源码与许可协议核对，仓库许可证为 MIT。
- 只覆盖右侧文件预览，没有 diff，也没有按代码行号的精确锚定。
- 文件内容变化后不会自动迁移，也不会判定旧批注过期。
- 待发送列表依赖 DSH 的
conversation、sessions和inputTriggers客户端服务，宿主接口变化需要重新验证兼容性。 - 多个独立浏览器同时修改同一工作区的存储仍可能互相覆盖，目前没有协同编辑协议。
社区目录页与仓库地址：https://www.skillhub.cn/plugins/DEVbyQIN/dsh-file-annotations 、 https://github.com/DEVbyQIN/dsh-file-annotations
