前言¶
用 DeepSeek Harness 做智能体或前端协作时，经常要把本地 HTML 原型交给同事或模型看：哪里缺交互、某一步界面长什么样，往往靠截图加文字说明。原型一改，截图和说明就对不上；多状态浮层（弹窗、侧栏）更难在一张图里说清「这条注释只在打开设置时出现」。
下面介绍社区插件 dsh-design-annotate（维护者 Yuuuyi，分类：工作流）。它在 Harness 侧边栏里打开本地 .html / .htm 原型，点选元素写注释，并按界面状态控制 pin 显隐；还可录制点击流程并导出流程图或单文件标注包，且不修改原型源码，标注写在旁边的 sidecar JSON 里。
这是什么¶
dsh-design-annotate 是 DeepSeek Harness 的客户端插件（package.json 版本 0.11.0，许可证 MIT）。一句话：打开 HTML 原型 → 锚定元素加备注 → 流程走到对应 DOM 状态时注释再出现 → 导出可分享的 .annotated.html 或带批注的流程图 PNG / 交互 HTML。
插件 Host 提供 /annotate-api 路由（服务原型、读写标注、导出、保存及原生文件对话框）；bridge.js 注入原型页面负责选元素、状态条件与录制冻结帧。社区目录页：skillhub.cn/plugins/Yuuuyi/dsh-design-annotate；源码：github.com/Yuuuyi/dsh-design-annotate。目录站点为社区维护，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
元素标注与状态条件¶
- 选中即锚定：点击原型内元素，记录稳定选择器（优先
id、唯一data-*、DOM 路径）、文本快照与位置；失配时可凭snapshot辨认并重挂。 - 跟着界面状态出现：标注时采集当前浮层状态（如
aria-hidden、状态类is-open、display等），写入conditions；全部成立才显示 pin，避免全页铺满。 - 标注模式常开：可连续标多个元素；
Shift轻按开关标注模式，Ctrl/⌘ + Enter保存；在备注框内按Shift打大写不会误触开关。
导出与零安装分发¶
- 导出标注包：生成只读
<原型名>.annotated.html，对方双击即可查看，无需安装插件。 - 保存源文件：生成可再次打开的副本；标注可内联为
window.__DSH_ANNOTATE_DATA__，继续编辑时写入同目录 sidecar。
流程录制¶
正常操作原型，每次点击立刻冻结一帧；无点击的等待可用「插入步骤」补帧。结束后进入流程看板：卡片悬停时在缩略图用红色闪烁框标出触发位置。可「下载 PNG」（流程图 + 静态备注栏）或「下载流程板」（单文件 HTML，悬停步骤编号高亮对应备注）。冻结帧为静态 DOM（不执行脚本），自包含原型效果较好。
画板自适应¶
| 原型 | 判定 | 画板 |
|---|---|---|
| App / PDA | <meta name="viewport" content="width=480">，宽度 280–700 |
按声明宽度，高度取渲染后内容高度 |
| PC / Web | 无以上声明 | 1280×800，等比缩放到面板内 |
环境要求¶
- DeepSeek Harness 桌面端 0.2.x
- 已在 macOS 上验证；Windows / Linux 的文件选择与保存对话框通过 PowerShell / zenity 实现
- 无 npm 依赖、无构建步骤；整个插件目录可任意搬迁
安装与启用¶
官方 README 未提供 dsh plugin add github:... 一类命令，安装方式为本地目录注册：
- 下载本仓库（ZIP 解压或按 README 说明获取源码）。
- 打开 DeepSeek Harness → 设置 → 插件 → 添加插件，粘贴解压后含
package.json的那一层绝对路径，例如：
~/dsh-plugins/dsh-design-annotate
- 完全退出 Harness 再打开，左侧应出现「设计标注」。
bridge.js 与 export-viewer.js 由 Host 按相对路径读取，无需单独构建。
典型用法¶
标注¶
- 侧边栏点「设计标注」。
- 点「打开原型」（或「更换」）→ 系统文件选择器选本地 HTML；对话框不可用时 README 说明可回退到手动输入路径或扫描目录。
- 打开「标注模式」，点原型元素 → 右侧写注释 → 「保存标注」。
- 照常操作原型；流程到对应状态时元素右上角出现编号 pin；右侧列表点条目可跳转定位。
再点一次「标注模式」或按 Esc 关闭标注模式。
快捷键：
| 快捷键 | 作用 |
|---|---|
Ctrl/⌘ + Enter |
保存当前标注 |
Shift（轻按） |
开 / 关标注模式 |
Esc |
退出标注模式 |
流程录制¶
- 点顶部「流程录制」。
- 在原型里操作，每次点击截取当前页面；需要时用「插入步骤」补帧。
- 点「结束生成」，进入流程看板，按需下载 PNG 或流程板 HTML。
数据落盘¶
默认 sidecar 与原型同目录：
index.html
index.html.annotations.json
标注 JSON 含 version、file、annotations（每条含 selector、page、note、status、conditions、snapshot 等）。status 为 open 或 resolved。
适用场景与注意¶
适合：单文件或可内联资源的 HTML 原型评审、给 Agent 或同事发「带状态说明」的交互包、快速录一遍点击路径出流程图。
限制（README 已说明）：
- 标注仅支持
.html/.htm单文件（或资源内联的自包含原型）；多页面目录相对跳转尚无路由映射。 - 流程录制冻结帧不跑脚本，依赖外部相对资源或 canvas 运行时结果的页面可能缺内容。
- 原型 DOM 大改后选择器需重标；流程看板关闭后不持久化，需重新录制。
安全与权限：插件在当前 DSH 进程权限下运行，可读写你选择的本地 HTML 与 sidecar。安装前请自行查看 GitHub 仓库 源码与 MIT 许可证；第三方依赖含 vendor/html2canvas.min.js（html2canvas 1.4.1，MIT）。
结尾¶
dsh-design-annotate 把「点哪标哪、按状态显隐、sidecar 不动原型、单文件分发」和「点击录流程、导出 PNG / 交互流程板」收进 Harness 侧边栏，适合 HTML 原型协作与说明。进一步说明与截图见社区目录 skillhub.cn/plugins/Yuuuyi/dsh-design-annotate 与 github.com/Yuuuyi/dsh-design-annotate。
