dsh-annotate-sync
Verifieddsh-annotate-sync · v2.0.0 · MIT · Web UI
DeepSeek Harness HTML 文档预览就地批注插件:打开任意 HTML 预览即出现点选批注浮层,批注按文件保存,可整批发送给当前对话的 Agent,并通过 read_annotations 工具让 Agent 直接定位并修改源文件。In-place HTML document annotation for DeepSeek Harness: the overlay appears automatically in the document preview, annotations are s
Install
dsh plugin add dsh-annotate-sync Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
dsh-annotate-sync · HTML 文档就地批注
打开一个 HTML 预览,批注浮层就在页面里;点选元素写批注,整批交给 Agent, Agent 按文件路径直接改源码。不需要起服务,不需要加
<script>,不需要选目标。
这是什么
一个 DeepSeek Harness 插件,接管 .html / .htm 的文档预览:
- 在 DSH 右侧 Files 里打开任意 HTML(包括 Agent 刚生成的),预览里自动出现 「点选批注」 浮层;
- 悬停高亮,点击元素写批注,编号 Pin 跟随滚动/缩放/布局变化;
- 批注按 文件路径 保存,带 selector、当前文本、计算样式和修改指令;
- 退出点选(
Esc)或点 发送给 Agent,整批作为一条结构化消息进入当前对话; - Agent 调
read_annotations拿到 文件路径 + selector + 备注,直接改那个 HTML/CSS; - 文件变化后预览自动重建,批注仍在;Agent 改完可
set_annotation_status标记已处理。
之前 Agentation demo 的体验保留了下来,但不再需要手工引入 agentation.js、不再需要
8765 同步服务,也没有“本地服务列表”要先选。
安装
# macOS Desktop 自带 CLI
"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" \
plugin --profile desktop add [email protected]
把 "dsh-annotate-sync" 加入 ~/.dsh/profiles/desktop/package.json 的
dsh.profile.bundles,然后完全退出并重启 DeepSeek Harness。
本地开发/分享 tarball:
npm pack
dsh plugin --profile desktop add /absolute/path/to/dsh-annotate-sync-2.0.0.tgz
使用
- 重启 DSH。
- 在右侧 Files 面板里打开任意
.html文件(或直接打开包里的demo/index.html试一下)。 - 预览里右下角出现 「点选批注」;点它,然后点击页面元素。
- 写备注,
Enter保存;Esc退出点选。 - 默认开启 自动发送:退出点选时,这一批批注会自动发进当前对话; 也可以随时点工具栏的 发送给 Agent,或关掉自动发送手动发。
- 之后 Agent 会读取批注并改源码;打开预览的文件变化后自动刷新。
- 如果 Agent 没有自动标记,直接说「按批注修改」,它会调用
read_annotations。
工具栏在预览上方:文件名、待处理数量、发送、自动发送、清空。
批注数据
{
"id": "uuid",
"page": {
"url": "dsh-resource://file/session/<sessionId>/<encoded path>",
"origin": "",
"path": "demo/index.html",
"title": "index.html"
},
"file": { "sessionId": "...", "path": "demo/index.html", "name": "index.html", "address": "dsh-resource://..." },
"selector": "#hero-title",
"tag": "h1",
"className": "hero-title",
"textSample": "把成本算清",
"styles": { "fontSize": "26px", "color": "rgb(15,23,42)", "backgroundColor": "rgba(0,0,0,0)" },
"rect": { "x": 120, "y": 340, "w": 420, "h": 32 },
"note": "把标题改短一点",
"status": "pending",
"order": 0,
"createdAt": "ISO",
"updatedAt": "ISO"
}
落盘:~/.dsh/annotate-sync/annotations.json + 人类可读的 annotations.md。
旧版 v0/v1/v2 文件自动迁移到 v3;旧 HTTP 页面批注仍可读取。
模型工具
| 工具 | 作用 |
|---|---|
read_annotations({ status?, pageUrl?, includeDone? }) |
读取批注;默认只给 pending;Markdown 每组带 文件:<path> |
set_annotation_status({ ids?, status, all?, pageUrl? }) |
改完后标记 applied(或退回 pending) |
clear_annotations({ pageUrl? }) |
清空(可限定文件) |
配置
cordis.patch.yml 中的 config:
| 字段 | 默认值 | 说明 |
|---|---|---|
dir |
~/.dsh/annotate-sync |
批注落盘目录 |
route |
/__dsh-annotate-sync |
插件内部 API/overlay 前缀 |
legacyRoute |
/api/annotate-sync/annotations |
旧版同步桥;置空关闭 |
maxBodyBytes |
262144 |
单次请求体上限 |
tool |
true |
是否注册模型工具 |
架构
DSH Web
└─ Client: 自定义 HTML 文档预览 renderer(priority: external)
├─ 复用内置 HTML 预览的 bytes-complete + 相对 CSS/JS 打包 + opaque blob iframe
├─ 注入 window.__DSH_ANNOTATE__ + overlay.js
├─ toolbar:发送 / 自动发送 / 清空
└─ postMessage 桥:overlay ↔ 文档组件
Host: 路由 + v3 批注 store + 三个模型工具
Overlay: 点选、Pin、批注卡片、状态
- 预览 iframe 仍是
sandbox="allow-scripts"的 opaque origin;overlay 与文档组件只通过postMessage通信,父侧校验event.source+ channel。 - 相对 CSS/JS 由 DSH 的 workspaceFiles 读取并打包进 blob,和内置预览一致。
- 不启动任何额外 HTTP 服务,不向被预览页面注入网络请求。
已知限制
- 页面自带 CSP 且禁止外部脚本时,overlay 会被拦截;预览本身仍可用。
- 自定义 renderer 总是允许页面脚本执行(overlay 需要),不受内置“交互式预览”开关控制。
- 跨域 iframe、closed shadow root 内的元素无法点选。
- 只接管
.html/.htm;其他文档类型仍用内置预览。 - 批注定位依赖 CSS selector 与几何矩形;元素结构大改后可能定位不准,但备注和文件路径仍在。
从 1.x 升级
v2 移除了“本地服务预览 + 右侧栏批注面板”。旧的 annotations.json 会迁移;旧的
/api/annotate-sync/annotations 同步桥仍保留。无需再启动 sync-server.mjs。
开发
npm test # node --test
npm run check # node --check 所有运行时文件
npm run pack:check
协议契约:docs/PROTOCOL.md · 发布:docs/PUBLISH.md
License
MIT。HTML 渲染器部分改编自 DeepSeek Harness(MIT),见 NOTICE。