原型标注 Yuuuyi/dsh-design-annotate

设计标注 · Design Annotation for DeepSeek Harness

给 HTML 原型加标注和流程录制的 DeepSeek Harness 插件。

打开一个原型 → 点选元素写注释 → 流程走到对应状态时注释自动出现 → 一键导出可分享的标注包或带批注的流程图。

不修改原型文件：所有标注写在原型旁边的 sidecar JSON 里。

特性

- 选中即锚定：点哪个元素就标哪个，记录稳定选择器、文本快照与位置。
- 跟着界面状态出现：标注时自动采集当前浮层状态（aria-hidden、is-open 之类的状态类、display），之后只有回到那个状态才显示，不会在所有页面上一股脑铺满。
- 标注模式常开：可以连着标多个元素，点中的位置会锁定，鼠标移到右侧写备注不会跑；Shift 轻按开关，Ctrl/⌘ + Enter 保存。
- 零安装分发：导出 .annotated.html，原型 + 标注合成一个文件，对方双击就能看，不需要装插件。
- 保存源文件：把原型 + 标注存成可再次打开的副本，下次直接选它继续编辑。
- 流程录制：正常操作原型，每次点击立刻冻结一帧，结束后自动排成带箭头、动作标签和触发位置的流程图，可导出 PNG 或可交互的 HTML。
- 画板自适应：自动识别 App / PDA 原型与 PC 原型，画板尺寸随之切换。

截图

| 标注面板 | 流程看板 |
| 标注面板 | 流程看板 |

| 导出的交互式流程板 | PC 原型画板 |
| 导出的流程板 | PC 画板 |

环境要求

- DeepSeek Harness 桌面端 0.2.x
- 已在 macOS 上验证；Windows / Linux 的文件选择与保存对话框使用 PowerShell / zenity 实现

安装

1. 下载本仓库（git clone 或下载 ZIP 后解压）。
2. 打开 DeepSeek Harness → 设置 → 插件 → 添加插件，粘贴解压后这一层的绝对路径（里面有 package.json 的那一层，例如 ~/dsh-plugins/dsh-design-annotate）。
3. 完全退出 Harness 再打开，左侧出现「设计标注」。

没有 npm 依赖、没有构建步骤；bridge.js 与 export-viewer.js 由 Host 按相对路径读取，整个目录搬到哪都能用。

使用

标注

1. 侧边栏点「设计标注」。
2. 点「打开原型」（或已打开时的「更换」）→ 弹出系统文件选择器，选一个本地 HTML；系统对话框不可用时可回退到手动输入路径 / 扫描目录。
3. 打开「标注模式」，点原型里任意元素 → 右侧写注释 → 「保存标注」。
4. 原型照常点，流程走到该状态时，元素右上角出现编号 pin；右侧列表点条目可跳转定位。

标注模式会一直保持开启：再点一次「标注模式」或按 Esc 才关闭。

快捷键

| 快捷键 | 作用 |
| Ctrl/⌘ + Enter | 保存当前标注 |
| Shift（轻按一下） | 开 / 关标注模式 |
| Esc | 退出标注模式 |

在备注输入框里按 Shift 打大写字母不会切换模式。

流程录制

1. 点顶部「📹 流程录制」。
2. 在原型里正常操作，每次点击都会截取当前页面；没有点击的等待状态点「插入步骤」补一帧。
3. 点「结束生成」，进入流程看板。

看板里鼠标移到某一步的卡片上，会在缩略图里用红色闪烁框标出这一步的触发位置；右上角可直接改流程名称。

- 「下载 PNG」：流程图 + 右侧静态备注栏，一张长图。
- 「下载流程板」：单文件 HTML，左边流程图、右边备注栏，鼠标移到数字上会高亮对应备注（其余编号淡出 40%），可双击打开。

导出与保存

- 导出标注包：生成只读的 <原型名>.annotated.html，对方双击即可查看（无需插件）。
- 保存源文件：生成可再次打开的副本；在这个文件上继续标注会写入它旁边的 .annotations.json。

数据存储

标注默认写在原型旁边：

index.html
index.html.annotations.json # 标注数据

{
"version": 1,
"file": "/abs/path/index.html",
"annotations": [
{
"id": "a-...",
"selector": "#chatInput",
"page": "#chatPage",
"note": "对话输入区没有语音入口", "status": "open",
"conditions": [
{ "selector": "#chatPage", "sig": { "ariaHidden": "false", "cls": ["is-open"], "display": "flex" } }
],
"snapshot": { "tag": "input", "text": "请输入", "rect": { "x": 12, "y": 820, "w": 359, "h": 28 } }
}
]
}

- selector：id > 唯一 data-* > DOM 路径；失配时用 snapshot 辨认与人工重挂。
- conditions：出现条件，全部成立才显示。
- status：open / resolved。

保存源文件 生成的副本会把标注以 window.__DSH_ANNOTATE_DATA__ 内联在 HTML 里；再次打开时自动读回，编辑后写入同目录 sidecar。

画板自适应

| 原型 | 判定 | 画板 |
| App / PDA | ，宽度 280–700 | 按声明宽度，高度取渲染后的内容高度 |
| PC / Web | 无以上声明 | 1280×800，等比缩放到面板内 |

已知限制

- 标注只支持 .html / .htm 单文件原型（或资源内联的自包含原型）；多页面目录的相对跳转尚未做路由映射。
- 流程录制的冻结帧是静态 DOM（不执行脚本）：自包含原型几乎无损；依赖外部相对资源或 canvas 运行时结果的页面可能缺失部分内容。
- 元素选择器依附 DOM 结构，原型大改后需要重新标注。
- 流程看板目前不持久化，关闭面板后需要重新录制。

目录结构

.
├── package.json # DSH bundle 清单（Host + Client 入口） ├── cordis.patch.yml # 插件行定义与默认配置 ├── index.js # Host：/annotate-api 路由（serve / 标注读写 / 导出 / 保存 / 原生文件对话框） ├── client.js # Client：侧边栏入口、标注面板、流程看板 ├── bridge.js # 注入原型的脚本：选元素、状态条件、pin、录制冻结帧 ├── export-viewer.js # 导出文件内联的只读查看器 ├── vendor/html2canvas.min.js # 录制光栅化（MIT，1.4.1） ├── locale/ # 插件元数据（中/英） └── icon.svg

License

MIT

vendor/html2canvas.min.js 为 html2canvas 1.4.1，遵循其 MIT 许可（文件头保留原始版权声明）。