前言¶
在 DeepSeek Harness 里改 HTML 页面时，常见做法是口头描述「把标题改短一点」「按钮颜色不对」，Agent 只能凭文件名和上下文猜位置。以前若要可视化标注，往往要在页面里手动挂 agentation.js、起本地同步服务（例如 8765 端口），再在列表里选预览目标，步骤多、环境重。
dsh-annotate-sync 把批注叠在 DSH 右侧 Files 面板打开的 .html / .htm 预览上：悬停高亮、点元素写说明，批注按文件持久化，整批送进当前对话；Agent 通过 read_annotations 拿到文件路径 + 选择器 + 说明，直接改工作区里的 HTML/CSS。无需额外 HTTP 服务、无需在页面里插 <script>、也无需再选「预览目标」。维护者为 chopperH0824，许可证 MIT，当前 package 版本 2.0.0。
这是什么¶
DeepSeek Harness 插件，接管 DSH 对 HTML 文档的预览渲染：打开任意 HTML（含 Agent 刚生成的文件）时，预览内自动出现 点选批注 / Mark 浮层与工具栏。批注数据落在本机目录，并通过 Cordis 向模型注册 read_annotations、set_annotation_status、clear_annotations 三个工具。
核心功能¶
预览内点选批注¶
- 在右侧 Files 打开
.html/.htm后，浮层按钮可用；进入点选模式后悬停高亮、点击元素写 note，按Enter确认，Esc退出点选。 - 编号 pin 随滚动、缩放和布局变化跟随；每条批注保存选择器、文本采样、计算样式与修改意图。
- 预览上方工具栏显示文件名、待处理数量，以及发送、自动发送、清空。
与对话和 Agent 协作¶
- 默认开启 Auto-send：退出点选时会把当前批次作为结构化消息写入当前对话；也可随时点 Send to Agent，或关闭自动发送。
- Agent 调用
read_annotations读取批注（默认 pending）；Markdown 输出里按文件带文件：<path>。 - 改完源文件后预览会重建，批注仍保留；Agent 可用
set_annotation_status标记已应用；若未主动读批注，可在对话里说明「apply my annotations」促使其调用read_annotations。
与旧版 Agentation 演示的差异¶
README 说明：保留类似的点选体验，但不再需要手动添加 agentation.js、不需要 8765 sync server、也没有本地服务列表要选。v2 移除了本地服务预览和右侧独立批注面板；旧 annotations.json 会自动迁移，legacy HTTP 桥 /api/annotate-sync/annotations 仍可配置保留。
模型工具一览¶
| 工具 | 用途 |
|---|---|
read_annotations({ status?, pageUrl?, includeDone? }) |
读取批注；默认 pending |
set_annotation_status({ ids?, status, all?, pageUrl? }) |
编辑后标记 applied 或改回 pending |
clear_annotations({ pageUrl? }) |
清空，可按页面/文件限定 |
批注 JSON 结构含 page.path、file.path、selector、note、styles、rect 等字段；存储为 ~/.dsh/annotate-sync/annotations.json，并生成可读的 annotations.md。v0/v1/v2 数据会自动迁到 v3。
安装与启用¶
插件以当前 DSH 进程权限运行，安装前建议浏览 GitHub 仓库 源码与 MIT 许可证。
macOS Desktop bundled CLI¶
"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" \
plugin --profile desktop add dsh-annotate-sync@2.0.0
也可在 ~/.dsh/profiles/desktop/package.json 的 dsh.profile.bundles 中加入 "dsh-annotate-sync"，然后完全退出并重启 DeepSeek Harness。
本地开发或 tarball¶
npm pack
dsh plugin --profile desktop add /absolute/path/to/dsh-annotate-sync-2.0.0.tgz
依赖 Node >=20；peer 为 @deepseek-ai/cordis ~4.0.4。
典型用法¶
- 重启 DSH。
- 在右侧 Files 打开任意
.html，或打开插件自带的demo/index.html试跑。 - 点击预览中的 点选批注 / Mark，再点页面元素。
- 输入说明并
Enter；Esc结束点选（默认会自动把批次送入当前对话）。 - 让 Agent 根据
read_annotations结果修改对应路径下的 HTML/CSS；文件变更后预览刷新，批注仍在。 - 需要时在对话中明确要求应用批注，或让 Agent 调用
set_annotation_status标记完成。
配置与架构要点¶
在 cordis.patch.yml 的 config 中可调整：
| 字段 | 默认值 | 说明 |
|---|---|---|
dir |
~/.dsh/annotate-sync |
批注存储目录 |
route |
/__dsh-annotate-sync |
内部 API/浮层前缀 |
legacyRoute |
/api/annotate-sync/annotations |
旧 sync 桥；设空可禁用 |
maxBodyBytes |
262144 |
请求体上限 |
tool |
true |
是否注册模型工具 |
架构上：DSH Web 侧用自定义 HTML 文档预览渲染器（高优先级），在 opaque blob iframe 中注入 window.__DSH_ANNOTATE__ 与 overlay.js；浮层与文档组件仅通过 postMessage 通信，Host 侧提供路由、v3 存储与三个工具。不启动额外 HTTP 服务，也不向页面注入对外网络请求。
适用场景与限制¶
适合：在 DSH 里迭代静态 HTML 落地页、演示页、Agent 生成的 .html 时，用可视化批注代替纯文字描述，并让 Agent 按路径和选择器改源文件。
已知限制（来自 README）：
- 页面 CSP 若禁止外部脚本，浮层会被挡；预览本身仍可渲染。
- 自定义渲染器始终允许页面自有脚本（浮层需要）；不受内置「交互预览」开关约束。
- 跨源 iframe、closed shadow root 内元素无法点选。
- 仅接管
.html/.htm；其他文档类型仍用内置预览。 - Pin 依赖选择器与几何；DOM 大改可能导致 pin 错位，但 note 与文件路径仍有效。
从 1.x 升级：v2 不再需要 sync-server.mjs；旧数据迁移后 legacy 桥仍可保留。
结尾¶
dsh-annotate-sync 把 HTML 预览变成可点选、可持久化、可整批交给 Agent 的批注面，并用工具把「改哪里、改什么」绑回工作区文件路径。社区目录页：skillhub.cn/plugins/chopperH0824/dsh-annotate-sync；源码与完整说明：github.com/chopperH0824/dsh-annotate-sync。
