alaliqing/dsh-annotate

dsh-annotate

English · 简体中文

CI
npm
许可证：MIT
Node.js 20+

直接指出界面问题，把准确上下文交给编程助手。

dsh-annotate 为 DeepSeek Harness 网页端增加了一个可视化评审面板。打开本地应用，
点选想改的元素，逐条留下意见，再把整份评审以结构化文本发进当前对话。

dsh-annotate 中的本地应用、批注列表和页面编号标记

⌘/Ctrl ⇧ B → 选择本地应用 → 标注 → 点选 → 写批注 → 发送

安装

把下面这段话交给能访问 Harness 所在电脑的编程助手：

阅读 https://github.com/alaliqing/dsh-annotate，按说明将最新已发布版本安装到本机 DeepSeek Harness 的 web profile。保留已有配置，不要中断当前 Harness 会话。验证安装结果，并说明如何重启 Harness、打开「标注」面板。

也可以手动安装，需要 Node.js 20+、dsh CLI 和 PATH 中可用的 pnpm：

dsh plugin --profile web add dsh-annotate

当前版本还需要在 $DSH_HOME/profiles/web/cordis.patch.yml（默认
~/.dsh/profiles/web/cordis.patch.yml）中启用。保留现有配置，只添加一次：

- insert:
- name: dsh-annotate

用 dsh --profile web --dump-config 确认输出中出现 dsh-annotate。
重启 web profile、刷新浏览器后，点击标注或按 ⌘/Ctrl⇧B。
如果使用 npx @deepseek-ai/dsh web，把上述命令中的 dsh 换成
npx @deepseek-ai/dsh。已测试版本和限制见兼容性记录。

核心能力

- 零配置发现正在运行的本地开发服务器，同时支持 IPv4 和 IPv6，并优先列出属于当前
工作区的服务。
- 静态页面无需服务器： 工作区里的 index.html，或 dist/、build/、out/、
public/ 下已构建的页面，会直接列出，并以所在目录为根进行预览。
- 元素级上下文： CSS 选择器及命中数量、语义属性、React 组件链、几何信息、
计算样式和可见文本。
- 始终跟随元素的标记： 支持窗口滚动、内层滚动、尺寸变化和布局位移。
- 两种明确的发送方式： 单独发送评审，或加入当前草稿；发送失败也不会丢批注。
- 彼此隔离的预览： 保留应用路由、资源、fetch 和 WebSocket，同时不与 Harness 共用源。
- 中英双语界面，可在工具栏切换。

插件不会截图，也不会修改应用样式。默认只发现你已经运行的服务器；只有显式配置了
启动命令，才会启用进程控制。

使用

1. 启动应用的开发服务器。
2. 打开一个 Harness 对话，然后按 ⌘/Ctrl⇧B 或点击顶部的标注按钮。
3. 选择检测到的服务、工作区内的静态页面，或手动输入端口/回环 URL。
4. 点击左下角的标注，点选元素并写下意见。
5. 点击编号图标查看批注，点击别处关闭；要继续添加批注，请再次点击左下角的标注。
6. 选择加入输入框或发送批注。

| 按键 | 操作 |
| --- | --- |
| Enter | 保存并退出标注状态 |
| Shift+Enter | 换行 |
| Esc | 取消并退出标注状态 |
| ⌘/Ctrl + 点击 | 保存并发送整批内容 |

批注和草稿按 Harness 会话与完整应用 URL 存储，因此不同路由可以独立恢复，
不同会话也不会串数据。

列表按“有多大概率是你自己的”排序：进程启动目录落在当前对话工作区内的服务会打上
当前项目 标签，工作区在 package.json 或 Vite 配置里声明过的端口会打上
配置端口 标签，之后才按常见端口顺序排列。静态页面单独成段；当候选只有一个时会
自动打开——只有在完全没有任何服务运行时，才轮到静态页面。

模型会收到什么

🎯 界面标注 · /settings · 视口 1440×900（1 条）
#1 button.primary  组件: SubmitButton
语义: aria-label="保存修改" · data-testid=save
组件链: SettingsPage > SettingsForm > SubmitButton
选择器: #root > form > button.primary（命中 1 个元素）
位置/尺寸: 96×32 @ (640, 512) · 视口 正中
当前样式: display:inline-block; padding:8px 16px; …
文本: 保存修改
批注: 表单没有变化时，这个按钮应该禁用。

React 组件名需要开发构建才能可靠获取；可见文本最多保留 120 个字符。

预览隔离

普通跨源 iframe 无法暴露 DOM。dsh-annotate 不会把应用搬到 Harness 源上，
而是为每个会话/应用组合创建独立的临时回环源，并注入一层很小的 shim 和点选覆盖层。

- 面板与覆盖层通信时同时校验消息来源和源站。
- 目标仅允许 localhost、127.0.0.1 和 [::1]。
- 静态页面由插件自身以只读方式、在所在目录上以回环源提供：仅允许 GET/HEAD，
不越出工作区，不提供点文件，单文件上限 64 MiB。
- 应用 cookie 带独立命名空间；没有前缀的 cookie 会在两个方向都被移除。
- 关闭面板、返回服务列表或切换应用时会释放对应预览；其他窗口仍在使用的预览会保留。
异常退出后，五分钟没有活动或续期的预览会被回收；插件销毁时关闭所有剩余服务和 socket。

这是本地开发工具，不是浏览器沙箱。OAuth、严格源白名单、Service Worker、限制性 CSP、
Shadow DOM 内部、跨源子 frame 和 Canvas 内部对象，可能需要正常浏览器或应用专门配置。
完整 cookie 模型目前只在 Chromium 上验证过。

可选配置

- insert:
- name: dsh-annotate
config:
detect:
extraPorts: [4321]
probeTimeoutMs: 900
cacheMs: 2000
staticPorts: false
staticFiles: false

detect.staticPorts: false 会停止盲扫常见端口，只保留真实监听；detect.staticFiles:
false 不再列出工作区里的静态页面；detect.extraPorts 用于补充习惯使用的端口。

仓库还包含 dsh-app-bridge，用于必须把应用挂载到
Harness 源固定路径下的少数情况。它只是反向代理，不提供批注界面。

开发

npm ci
npx playwright install chromium
npm run check
npm test

要使用尚未发布的检出，可链接进 web profile，然后按上面的说明启用：

git clone https://github.com/alaliqing/dsh-annotate.git
cd "${DSH_HOME:-$HOME/.dsh}/profiles/web"
npx --yes pnpm@10 add "link:/绝对路径/dsh-annotate/packages/dsh-annotate"

默认测试会在 Chromium 中驱动真实的 client、shim 和 overlay 构建产物，使用 Harness
测试替身，不调用模型。npm run test:harness 则在独立的真实 Harness 中安装打包产物，
使用本地模型替身验证完整接入。packages/dsh-annotate/lib/ 下的生成文件会提交到仓库，
必须与源码保持同步。

仓库约定见 CONTRIBUTING.md；安全问题请按
SECURITY.md 私下报告。

许可证

MIT，第三方归属见 NOTICE。

这是独立的社区插件，与 DeepSeek 没有隶属或背书关系。