截图标注画布 thezavtrak-a11y/dsh-image-annotate

dsh-image-annotate

在粘贴的截图进入对话之前先在上面画几笔 —— 就是 Cursor 里那套「粘贴、标注、发送」的操作，现在做成了 DeepSeek Harness 客户端插件。

把截图粘贴进输入框，图片上会浮出一层画布。点铅笔调出工具，把需要指出的地方标出来，然后按 Send：笔画会按截图的原始分辨率压平成 PNG，文件作为普通附件放进输入框。按 Esc 则原样归档图片，一个字节都不改。

上游代码一行没打补丁。插件注册进 Web 客户端官方的 slot、locale 和 Conversation 接口，所以 DSH 升级后依然可用，卸载只需删掉一行。

你能得到什么

- 粘贴即画 —— 剪贴板里只有一张图（没有文字）时按 Ctrl+V，画布浮层打开。
粘贴内容带文字或多张图时，交给 shell 处理。
- 工具 —— 画笔、箭头、矩形、椭圆，还有一个文字图章。
- 样式 —— 六种颜色（含白色，方便深色截图）和三档粗细；文字工具下同样这三档控制字号（图像坐标里是 12 / 24 / 48 px）。
- 文字 —— 用文字工具点击，就在点击处打开输入框：Enter 插入，Shift+Enter 换行，Esc 取消这条注释（不是关掉浮层）。
- 撤销 / 清空 —— 按笔画撤销，或全部清掉；Ctrl+Z 也行。
- 发送 —— Enter 或点按钮：笔画烘焙进 PNG，与源图 1:1。
- 不画直接发 —— Esc 或点按钮：原文件原封不动归档，不重新编码。
- 之后再标注 —— 输入框里有图片时，会冒出一个小铅笔，点它就能在那张图上打开浮层，不用重新粘贴。
- 失败也诚实 —— 图片解不开会明说，并且仍然允许你按粘贴原样归档，而不是留一个空框。

安装

包声明了 dsh.client（浏览器端）和 dsh.bundle.patch（loader 行），所以安装方式和别的 DSH 插件一样：

from a checkout, or from a published copy
dsh plugin --profile <profile> add /path/to/dsh-image-annotate
after that, reload the page once (a NEW row is picked up when the page's module table is built)

手动挂进配置档，本仓库就是照这个方式开发的：

1. live link so edits are picked up by client HMR without reinstalling
New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\<profile>\node_modules\dsh-image-annotate"
-Target (Resolve-Path .).Path

2. dependency of the profile: ~/.dsh/profiles/<profile>/package.json
"dsh-image-annotate": "file:<path to this checkout>"

3. loader row: ~/.dsh/profiles/<profile>/cordis.patch.yml
- insert:
- id: image-annotate
name: dsh-image-annotate

回滚 = 删掉 insert 行、依赖和 junction。

工作原理

| 文件 | 作用 |
| index.js | 宿主侧：一个空的 apply()，只为让加载器挂载包，并让客户端模块扫描器找到 dsh.client 声明 |
| lib/client.js | 全部功能：捕获阶段粘贴监听、overlay portal、canvas、flatten、附件交接 |
| cordis.patch.yml | bundle 安装时应用的加载器行 |

编辑时有四个决定值得保留：

1. 拦截在 document 的捕获阶段运行，早于 Lexical 把 PASTE_COMMAND 交给 shell。因此「只有一张图」的粘贴不会未经标注就溜进 rail，取消时把原始 File 还给输入框，不做重新编码。
2. overlay 是挂到 document.body 上的 portal。 输入框卡片是 position: relative，而应用框架自带 transform，所以放在这棵树里的 position: fixed 图层可能被困在某个祖先里。
3. 发送走 shell 自己的入口路径，不伪造输入：
conversation.createDrafts(sessionId, [file]) 注册草稿（及其预览），
inputActions.addAttachments(ids) 把它放进 rail —— 与输入框栏处理拖放时调用的正是这两个。如果 rail 拒绝（正在裁决某次发送），就释放草稿，而不是让它泄漏。这些接口不可用时，插件回退到在 [data-composer-input] 上合成 ClipboardEvent，也就是真实 Ctrl+V 走的路径。
4. 崩溃的 slot 条目会永久消失。 客户端插件的 slot 条目在渲染时（或在 effect 内）抛错，框架的逐条目错误边界会把它从所在单元格中移除，直到页面生命周期结束 —— 此后插件看起来就像死了，直到页面重新加载。所以：overlay 和重新标注 chip 都放在插件自己的错误边界后面，处理函数包在 try/catch 里，标准会话钩子用选择器钩子（useInput(selectAttachmentIds)，绝不用裸的 useInput()，那会抛错）。

笔画保存的是图像坐标；canvas 只在显示时缩放它们，所以 flatten 按截图的原始尺寸写出 PNG。文字也是笔画
（{tool: 'text', points: [anchor], text}），字号为 textFontSize(width) = max(10, width·4) 图像像素，
因此它和其他标记一样参与撤销、清除和导出。overlay 调色板在 JavaScript 里从实时主题 token 解析，并带显式回退 —— 空的主题自定义属性会让整条 CSS 声明失效，overlay 就是这样画出来却看不见的。

自己验证

1. syntax
node --check index.js && node --check lib/client.js

2. headless logic (64 checks): paste classification, stroke rasterisation, text stamps,
the flatten pipeline, the official attachment route plus every fallback, the palette,
the synthetic paste, slot registration and the diagnostics surface
node tools/smoke.mjs

3. every seam this plugin stands on, against a DSH build's own sources
（--root <@deepseek-ai root>，或者让它自己发现解压出来的构建和 npx 缓存）
node tools/check-api.mjs --all

4. 有正在运行的 GUI 在服务当前修订版（需要宿主机的 token URL 或它的启动器日志）
node tools/verify-live.mjs --url "http://127.0.0.1:<port>/?token=<token>"

5. 在真实无头 Chromium 里对着那个 GUI 跑端到端 —— 不调用模型，不点击：粘贴 -> 覆盖层 -> 铅笔 -> 笔画 -> 发送 -> 草稿进入侧栏 -> Esc 保留原图
node tools/live-ui.mjs --url "http://127.0.0.1:<port>/?token=<token>"

6. 手边没有 GUI？起一个用完即弃的宿主机（独立 home、独立端口），用完清理
node tools/iso-host.mjs up
node tools/live-ui.mjs --url "<URL printed above>"
node tools/iso-host.mjs down

7. 发布前门禁：载荷里没有个人数据，没有网络/存储/eval
node tools/audit-public.mjs

tools/live-ui.mjs 驱动真实应用：它派发一次携带真实 PNG 的粘贴，检查覆盖层带着画布打开，按下铅笔，用指针事件画一笔，发送，并断言编辑器侧栏多出一个缩略图；然后用一张损坏的图片重来一遍，证明入口在失败后依然存活，最后演练文字图章。它不发送任何提示词。

安全与隐私

插件载荷（index.js、lib/client.js、cordis.patch.yml）刻意做得平淡无奇，一旦有变，tools/audit-public.mjs 会让构建失败：

- 无网络访问 —— 没有 fetch、XMLHttpRequest、WebSocket、sendBeacon，也没有动态 import。
- 无存储 —— 没有 localStorage、sessionStorage、indexedDB，没有 cookie：绘图状态存在 React state 里，随覆盖层一起消失。
- 无代码或 HTML 注入 —— 没有 eval，没有 new Function，没有 innerHTML；所有 UI 都走 React 元素，用户文本传给 canvas.fillText，绝不当作标记解析。
- 权限 —— 不申请任何权限；插件从不碰剪贴板 API（它只是观察用户已经做出的粘贴）。
- 像素去了哪里 —— 粘贴的图片从页面里创建的 blob URL 解码，标注副本在 上生成，得到的 File 交给普通粘贴所用的同一条附件路径。插件不会主动让任何东西离开页面；之后外壳拿附件做什么，是外壳自己的行为。
- 与宿主机接触 —— 只有 tools/ 里的开发工具会查询运行中 GUI 的 HTTP 端点（只读：启动图和所服务的 bundle），而且只查你传入的 URL。

个人数据：仓库里没有用户路径，没有邮箱地址，没有 token，也没有截图。tools/audit-public.mjs 会同时扫描载荷和整棵树来找这些东西，所以重跑是一行命令，而不是一句承诺。

兼容性

- 已在 DSH 0.2.0-rc.2 和 0.1.5-rc.1 客户端构建上实测通过（各 42 项端到端检查）。
- tools/check-api.mjs 断言插件用到的十个接缝（slot 声明与作用域， inputActions 提供界面，shell 的 addAttachments、createDrafts、composer 的 data-* 标记、paste 命令的剪贴板接收、locale 注册表、standard-props 展开、标准钩子的 selector-hook 契约，以及 dsh.client 模块表契约）。
- 如果未来的 DSH 挪动了其中某个接缝，插件会在 check-api 处失败，而不是半死不活地运行。

限制

- 每次粘贴只处理一张图片：带文字或含多张图片的剪贴板内容交给 shell 处理。
- 把文件拖进 composer 不会被拦截（只拦截粘贴）。
- 文字提交后无法再拖动，绘图也不会在多次打开浮层之间保留——点 Send 之后，结果就是普通附件。
- 还没有裁剪，没有针对敏感区域的模糊/马赛克，也没有更多形状。每个工具只是 applyStrokes 里的一个分支，所以再加一个成本很低。
- 浮层打开时，它接管 Esc、Ctrl+Z 和 Enter；文本框打开时，这些键交给文本框。

诊断

页面控制台里的 window.__dshImageAnnotate 回答「发生了什么」： mounted（插件已生效）、opened（拦截到的粘贴次数）、lastRoute （draft | paste | failed）、lastName / lastBytes（归档了什么）、lastStroke、 lastStrokes，以及 lastError（decode、decode-timeout、insert、flatten: …、overlay: …）。

如果某次粘贴似乎被忽略了，先检查 document.querySelector('[data-slot-error]')：值为 conversation.input.right 说明该 slot 条目已被更早的崩溃注销，只有重新加载页面才能恢复。tools/live-ui.mjs 的第 8–9 节防止这个问题回归。

许可证

MIT —— 见 LICENSE。

По-русски, коротко

Плагин для веб-интерфейса DeepSeek Harness: вставляете скриншот в композер (Ctrl+V), поверх
картинки открывается оверлей, карандаш раскрывает инструменты (карандаш, стрелка, прямоугольник,
эллипс, текст; 6 цветов, включая белый; 3 размера). «Отправить» впечатывает штрихи в PNG в
натуральном разрешении и вкладывает файл в диалог; Esc вкладывает исходный файл без
перекодирования. Уже вложенную картинку можно дорисовать — карандаш в панели композера. Ничего в самом DSH не патчится: только официальные точки расширения. Проверки и аудит — командами из раздела «Verify it yourself».