前言¶
在 DeepSeek Harness（DSH）里改科研图，常见返工意见都是位置性的：标号指错、图例缺一条、误差棒过长。用文字描述慢，也容易和模型理解错位；只发一张截图，模型往往只知道「有个红框」，不知道框对应哪一行元素或哪段 SVG。
dsh-figmark 是维护者 KafukaTree 发布的客户端类 DSH 插件：在右侧栏文档预览里直接圈画批注图片、SVG、PDF 或本机网页，把几何位置、元素锚点和你的修改说明合成一条用户消息交给智能体，让它去改 Python、DOT、SVG 等生成源，而不是在导出的位图上涂改。原文档不会被插件改写，批注落在侧车文件里；安装与用法以 GitHub 仓库 与 SkillHub 目录页 为准。
这是什么¶
dsh-figmark（npm 包名 dsh-figmark）面向「配图审阅 → 智能体改图」这条链路：你在预览里画箭头、框选、圈选、手绘或单点 Pin，并可选中 SVG 图元、HTML 元素；发送时插件注入结构化批注与（按规则生成的）附图，并附带系统提示，要求智能体改生成源、未标注处不动。
插件以 MIT 许可发布；package.json 中当前版本为 1.2.3，引擎要求 Node ^22.19.0 || >=24.0.0、DSH >=0.2.1-rc.2。社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系，DSH 生态本身是「一切皆插件」的思路，安装前建议自行查看源码与许可证——插件随当前 dsh 进程权限运行。
核心功能¶
交给智能体的三样东西¶
每条批注消息里，插件尽量把下面三类信息一起给出（README 中的设计说明）：
- 图面坐标 —— 箭头两端、框的对角、单点位置等几何；
- 落在哪个元素上 —— SVG 侧有
tag/id/包围盒等；静态 HTML 与本机网页侧有可从body命中的selector（消息里会过滤掉说不清的冗长字段，保留能回源码定位的路径）； - 你的说明 —— 每条标注一段「这个元素要改什么」，以及可选的「整张图整体方向」。
栅格图（PNG/JPEG 等）只有像素坐标，没有元素锚定；SVG 与本机网页支持元素级定位。
支持范围¶
| 文档类型 | 后缀 | 状态 |
|---|---|---|
| 图片 | png jpg jpeg gif webp bmp ico |
支持 |
| SVG | svg |
支持，内联渲染，可选中图元 |
pdf |
支持，逐页批注，保存为原生 PDF 注释对象 | |
| 静态 HTML | html htm |
只读预览，可跑自包含脚本；无 Figmark 标注工具与侧车 |
| 本机网页 | http://localhost / 127.0.0.1 / [::1] |
在右侧栏「本机网页」中打开运行中的 loopback 服务 |
| Office | doc docx ppt 等 |
待接入，仍由内置预览器打开 |
另有测试功能：在输入框附图缩略图上直接标注，「加入输入框」生成标注 PNG 并追加评论到草稿；不写侧车、不建批注队列，细节见仓库内 docs/attachment-annotator-testing.md。
侧车产物与不改动原文件¶
批注不修改原图/PDF 源文件，常见侧车命名带被批注文件自己的扩展名，例如 fig1.svg 对应：
| 文件 | 内容 |
|---|---|
fig1.svg.annot.json |
图信息（路径、sha256；PDF 含 pageCount）、marks[]、总体目标 |
fig1.svg.annotated.png |
图片/SVG：原图与批注合成图（最高 2×），随消息附件 |
fig1.svg.annotated.pdf |
PDF：原件副本 + 原生注释对象，随消息附件 |
本机服务页不留侧车文件，消息携带页面 URL 与 anchor.selector。静态 HTML 预览不产生批注文件或消息。原图重新生成导致 sha256 变化时，插件会提示旧批注可能失准。
同一工作区姊妹批注器 Sati 使用 v2 侧车形状；本插件能读 v2、继续写 v1，互通时 v2 独有字段回存可能丢失。
安装与启用¶
下面三条路径均来自 README，任选其一；装完后需 完全退出并重开 DSH（README 写为 Cmd+Q，Linux 上对应完全结束 dsh 进程后再启动）。
从插件市场安装（推荐）¶
在 DSH 打开 侧栏 → 插件 → 实验性插件 → 更多 → 自定义插件市场，添加索引：
https://raw.githubusercontent.com/KafukaTree/dsh-figmark/main/market/index.json
在发现页搜索 figmark 安装。
从 npm 安装¶
dsh plugin add dsh-figmark
命令会把依赖写入 profile 并加入 dsh.profile.bundles。
从源码开发¶
需要本地构建时，在克隆后的目录执行 pnpm install 与 pnpm run build，再用本地路径安装：
dsh plugin add "$PWD"
改动 Host 半后必须重启宿主进程；Client 半刷新页面即可。开发时可使用隔离实例，例如：
DSH_HOME=/tmp/figmarkdev dsh --profile figmarkdev --port 3099 --no-open
典型用法¶
在右侧预览里标注文件¶
- 在右栏打开图片、SVG、PDF，或在本机网页里打开正在运行的 loopback 服务。
- 左侧浮条切换工具：选择、箭头、框选、圈选、手绘、单点；除「选择」外，画完会自动回到选择并弹出说明框。
- 底部浮条：样式、撤销/重做、总体目标、标注清单，以及两个发送入口（见下表）。
- 编辑会自动保存（防抖 600ms）；只有发送成功后才清空面板并删除磁盘上的批注文件。
| 按钮 | 行为 |
|---|---|
| 发送给智能体 | 批注与标注图作为一条用户消息直接进入当前会话 |
| 发送到对话框 | 写入输入框草稿（含图片附件），由你确认后再发送 |
交互要点：图上只画标记，不把说明文字烧进图；双击标注编辑说明，Delete/Backspace 删除选中项；两条浮条可拖动，位置保存在浏览器本地。
本机网页与静态 HTML 的区别¶
静态 .html 走 Figmark 只读预览，没有底部标注工具。要标注 Vite、Next 等开发中的页面，先在右栏进入「本机网页」：Host 会按 bounded 规则发现最近地址、package.json 里写明的端口及常见开发端口，不会全端口扫描，也不会替你执行任意启动命令。选中地址后通过 live proxy 打开 127.0.0.1 上的页面，元素模式可落带 selector 的元素标注；纯元素或纯 pin 批注可不生成截图，消息标记为「位置标注」；含可见绘图的批注会截当前可见 surface。
适用场景与注意¶
适合：用 DSH 迭代 matplotlib / Graphviz / 手写 SVG 等流水线，需要把「指这里、改那里」精确交给智能体；需要在 PDF 上留可在阅读器里继续编辑的原生注释；需要在本地 dev server 页面上点选 DOM 元素写修改意见。
务必知晓的限制（README「已知限制」）：
- 插件只采集批注，不做图面编辑；修图靠改生成源。
- PDF 一次一页，无文本层、无连续滚动；注释不烧进页面内容，不渲染注释的阅读流程看不到标记（可依赖消息附带的每页图）。
- 本机网页必须有正在运行的 loopback 服务；静态 HTML 不能 Figmark 标注。
- Office 尚未接入。
安装前请自行审阅 https://github.com/KafukaTree/dsh-figmark 源码与 MIT 许可证；插件能力以仓库 README、CHANGELOG 为准。
结尾¶
dsh-figmark 把科研配图返工从「长段文字描述位置」变成「预览里圈画 + 结构化消息」，并强调改图源、不动未标注区域。进一步了解可访问目录页 https://www.skillhub.cn/plugins/KafukaTree/dsh-figmark 与 GitHub https://github.com/KafukaTree/dsh-figmark。
