前言¶
在 DSH 里让 Agent 改文档或解释某段内容时，常见做法是复制路径、粘贴原文片段，再在输入框里补一句「这里有问题」。文件一换行、预览和对话不在同一侧时，引用容易错位，来回核对也费时间。下面介绍的 dsh-doc-annotate 是维护者 YHzed 发布的客户端插件：在右侧边栏打开文件或文档，对选中文字或框选区域写批注，再把批注（含位置与原文引用）放进当前 Agent 对话草稿，由你检查后自行发送。批注只保存在本机浏览器，不依赖账号、数据库或额外服务。
这是什么¶
dsh-doc-annotate（仓库 YHzed/dsh-doc-annotate）面向在 DSH Web 界面里做文档阅读与对话协作的场景。插件通过 DSH 客户端注入右侧边栏与会话相关 UI，复用 DSH 自带的文件预览能力；宿主侧入口为空壳加载客户端，属于该插件的正常实现方式。当前 README 标注版本为 0.2.0-personal.1，许可证 MIT；社区目录页见 SkillHub。
核心功能¶
依据仓库 README 与 package.json 描述，已核实能力包括：
- 右侧预览与打开文件：在会话顶部通过「文档批注」入口，输入文件路径或从文件树打开文档。
- 文字批注与区域批注：在预览中选中文字后点浮动「批注」；对图片等无法用选区覆盖的内容，可用顶部框选按钮划定区域。
- 批注管理与分类：评论可保存；支持按建议、问题、疑问等分类，以及标记已解决、筛选、编辑、归档和撤销。
- 送入 Agent 对话：点「发给 Agent」时，将文件位置、原文与评论写入输入框草稿，不会自动替你发送，也不自动启动另一套 Agent 或改文件。
- 本地存储：新批注保存在当前浏览器、当前 DSH 地址的 localStorage；无跨设备同步。卸载插件本身不会主动清除浏览器批注数据（勿随意清除网站数据）。
旧版本批注可通过「预览升级批注 → 确认升级批注」迁移；默认按原会话分组，迁移备份会保留。保存依赖浏览器 Web Locks（当前 Chrome / Edge 的 localhost 支持）；无 Web Locks 时保持只读。PDF、Office、图片的页码或区域引用不能当作源代码行号；「重新定位引用」仅在用户确认后更新位置，不改源文。
安装与启用¶
在 DSH 侧栏「插件」页安装，来源填写（与 README 一致）：
github:YHzed/dsh-doc-annotate
也可使用 DSH CLI（web 为目标 profile）：
dsh plugin --profile web add github:YHzed/dsh-doc-annotate
仓库已包含构建后的客户端，一般用户无需自行构建。安装后确认「文档批注」已启用。若插件页已装旧版，建议先保存或复制未保存草稿，再卸载旧版并安装上述来源；CLI 可直接执行上述命令替换。替换已加载版本后，重启 DSH 并刷新页面。尚未发布 npm 包。
插件以当前 DSH 进程与浏览器环境运行；安装前请自行查看 GitHub 源码 与 MIT 许可证，确认符合你的使用与合规要求。
典型用法¶
README 给出的主流程如下，可按顺序复现：
- 点击会话顶部「文档批注」，输入文件路径或打开文件树。
- 在预览里选中文字，点击浮动「批注」；图片等也可使用顶部的框选按钮。
- 写评论并保存。第一次使用无需建立工作区或填写任何标识。
- 可按建议／问题／疑问分类，标记已解决、筛选、编辑、归档和撤销。
- 点「发给 Agent」将文件位置、原文和评论放进输入框，检查后自己发送。
HTML iframe、Excel 画布等无法选中文字时，用框选代替选区批注。
适用场景与注意¶
适合：在 DSH 里对照工作区文件做代码或文档 review，希望批注与原文位置绑定，再一次性整理进 Agent 对话的场景。
注意：
- 批注与浏览器、DSH 访问地址绑定；换浏览器、换端口或清除网站数据不会自动带走数据。
- 发送只填对话草稿，不代替你点击发送；也不修改源文件。
- 个人版定位明确：未接入的宿主持久化、独立任务等实验能力不随安装包发布，也不是日常使用前置条件。
维护者仓库内开发需 Node.js 22+；验证命令为 npm run build、npm run test:smoke、npm test，面向贡献者而非普通安装路径。
结尾¶
dsh-doc-annotate 把「右侧读文档 → 本地批注 → 草稿进 Agent 对话」收成一条可重复流程，减少手工复制路径与片段。目录与说明以社区站点与 GitHub 为准：
