前言¶
在 DeepSeek Harness（DSH）里排查界面、对照截图时，常见做法是另开画图工具圈点，再粘贴图片并文字说明位置。图片和说明容易脱节，模型也不容易把「第几处」和图上的标记一一对应。社区插件 dsh-sidebar-annotate 把批注做在右侧边栏预览区上方：不弹居中对话框、不遮暗背景，在原图坐标上叠一层画布，发送时合成 PNG，并附带编号说明列表，走与粘贴图片后回车相同的官方草稿路径进入对话。
这是什么¶
dsh-sidebar-annotate 由维护者 HuaLQIn 发布（首版 2026-10-31，当前资料中版本为 0.7.0，MIT 许可证）。它挂载在 DSH 客户端文档预览相关能力上：在右侧栏打开图片后，预览区标题栏会出现 Annotate 按钮；进入批注模式后，工具条以半透明胶囊形式出现在图片下方，批注层与预览中的 <img> 矩形对齐，缩放、滚动与官方渲染器不被插件改写。
生态上，DSH 强调「一切皆插件」；SkillHub 目录页 是社区收录站点，与 DeepSeek / 幻方无官方从属关系。插件分类为客户端，未发布到 npm，需通过 dsh plugin add 从 GitHub 仓库安装。
核心功能¶
下面介绍 README 中已列出的能力，与「Compatibility notes」中明确未实现的部分分开说明。
原地批注与发送¶
- 在右侧栏打开支持的图片格式（png、jpg、jpeg、webp、gif、bmp、ico）。
- 点击 Annotate，在图上使用工具绘制或打点。
- 点击 Send：插件将原图与墨迹合成导出为 PNG（最长边超过 4096 px 时会先降采样），并生成编号说明；一并提交到当前对话。
发送后说明列表示例形态如下（摘自 README）：
I marked spots on this image:
1. the button in the top right
2. the spacing here
The numbers in the image match the list above.
六种工具¶
| 工具 | 作用 |
|---|---|
Mark（V） |
单击放置带编号的标记，并输入一行说明 |
Pen（P） |
按住拖动自由画线 |
Arrow（A） |
拖动绘制箭头，箭头在终点 |
Rectangle（R） |
从按下的一角拖出矩形 |
Square（S） |
同上，边长锁定为相等，取长边 |
Triangle（T） |
同上，底边在下、顶点居中 |
Mark 为蓝色圆点、白环与白字编号，锚定在归一化坐标上，窗口尺寸变化时仍可对齐。撤销 / 重做按操作时间顺序，而非按工具类别；整笔笔画或整颗标记作为一步撤销，不支持局部擦除（文档写明无 eraser）。
颜色、线宽与视图¶
胶囊工具条从左到右包含：六个工具格、四档预设色加自定义取色、三个线宽点加 1–12 px 滑块（与 [ / ] 切换预设联动）、撤销 / 重做 / 清空、标记计数、取消与发送。滚轮可放大查看细节；按住 Space 可平移。关闭批注层后恢复原图展示。
键盘与输入法¶
批注层聚焦时：Ctrl+Z 撤销，Ctrl+Shift+Z 或 Ctrl+Y 重做，Esc 先关说明卡片再退出层。说明卡片获得焦点时快捷键不抢键，便于 IME 输入中文说明。
边界行为（文档已说明）¶
- 仅图片；PDF、浏览器标签、元素拾取、文本批注未实现。
- 连续三次图片查找失败（约 1.2 s）会关闭批注层；同标签切换文件会清掉旧墨迹。
- 图片滚出视口时层隐藏但保留状态；对话正在提交附件时会拒绝发送并提示，而非静默排队。
- 超大图导出可能耗时，发送按钮会显示 sending 状态。
安装与启用¶
安装前需要 Node.js 20 或更新版本（package.json 中 engines.node）。主机需提供插槽 sidebar.right.tab.document.actions（与 document-preview 包一并引入）；README 写明在 DeepSeek Harness desktop 0.2.1-rc.2 与对应 web 客户端构建上做过测试，其他版本未测。package.json 有意不声明 engines.dsh 与 @deepseek-ai/* peer，是为避免 semver 拒绝 0.2.1-rc.2 这类预发布号导致安装被静默跳过。
推荐从仓库直接安装（命令来自 README 原文）：
dsh plugin --profile <your-profile> add git+https://github.com/HuaLQIn/dsh-sidebar-annotate.git
<your-profile> 为实际使用的 profile：web 对应浏览器构建，desktop 对应桌面应用。包名为 dsh-sidebar-annotate；CLI 会写入 profile 的 package.json 依赖与 dsh.profile.bundles 条目，不要用不同名称重复安装同一插槽。
安装后必须完全退出 DSH 再重新打开；仅刷新窗口不会加载新插件客户端 bundle。
自检是否只注册一份：
dsh --profile <your-profile> --dump-config | rg "id: dsh-sidebar-annotate"
应恰好一行。在运行中主机浏览器控制台：
window.__DSH_BOOT__.entries.find(({ id }) => id === 'dsh-sidebar-annotate')
应返回带 url 的条目；若为 undefined 表示未加载。
卸载：
dsh plugin --profile <your-profile> remove dsh-sidebar-annotate
也可手动删除 profile package.json 中的依赖与 bundles 项后同样完全重启；批注状态仅在内存中，关闭层即丢弃。
典型用法¶
交互流程可概括为：
右侧栏打开图片 → 预览标题 [Annotate] → 胶囊工具条出现在图下
→ 选工具绘制 / Mark 写说明 → [Send]
→ 合成 PNG + 编号说明列表 → 进入对话（同粘贴图片回车路径）
先做 Mark 标关键 UI 元素并各写一行，再用 Arrow 或 Rect 框区域，是 README 演示中常见的组合；发送前可用 undo / redo 调整顺序。若对话 busy，需等待提交完成再 Send。
适用场景与注意¶
适合需要在 DSH 会话里指着截图讲清楚的场景：前端布局、设计稿核对、日志截图里的异常位置等。相比外置标注工具，优势是坐标与右侧预览一致，且输出带编号列表，便于模型对齐「图中数字 ↔ 文字条目」。
安装与使用前请注意：
- 插件以当前 DSH 进程权限在客户端运行；安装前应自行查看 GitHub 源码 与 MIT 许可证，确认符合你的安全与合规要求。
- 不要用
cordis.patch.yml手工重复插入同一插件 id；遵循 README 的 Do / Don’t。 - 问题反馈可走仓库 Issues。
结尾¶
dsh-sidebar-annotate 把图片批注收进 DSH 右侧栏预览流程：六种工具、编号 Mark、合成图与说明列表一次回传，减少截图与文字错位。进一步了解可访问社区目录 SkillHub：dsh-sidebar-annotate 与源码仓库 github.com/HuaLQIn/dsh-sidebar-annotate。
