前言¶
让智能体改网页，最难的往往不是写 CSS，而是把问题说清楚。会话里常见的说法是「这个按钮偏了」「标题颜色不对」「移动端这里挤在一起」。模型看到的是文字，看不到你指的是哪一个 DOM 节点、计算样式实际是什么、无障碍树上的角色叫什么。截一张图贴进去，也只剩像素，选择器和布局数据还是要人再口述一遍。
DeepSeek Harness（命令名 dsh）把智能体运行时拆成可组合的插件：模型、工具、会话、沙箱和界面都可以在 Cordis 内核上增删。官方仓库把这件事概括成 Everything is a plugin（一切皆插件）。社区里因此出现了一批界面增强插件，专门补「人怎么把视觉信息交给 agent」这一层。
dsh-annotate 做的就是这件事：在 Chrome / Chromium 里点选页面元素，把选择器、DOM 事实、计算样式、无障碍数据、评论和当前视口截图，整理成下一轮对话里 agent 能直接读的结构化记录。它由 BrambleXu 维护，社区目录归在「界面增强」。
需要先说明：下文引用的目录页来自独立社区站点 DeepSeek Harness 插件库，该站 About 页写明与 DeepSeek / 幻方没有官方从属关系，不能当成官方应用商店。官方仓库是 deepseek-ai/deepseek-harness。本文按目录详情页、GitHub README / package.json / src/ / 配套扩展源码交叉核对，核实日期为 2026-08-18。
这是什么¶
dsh-annotate 是一款 DeepSeek Harness 浏览器元素可视化标注插件。目录页和仓库 README 的定位一致：捕获 DOM、样式、无障碍数据、评论与视口截图，把页面结构整理成 agent 可参考、可标注的可视化记录。
仓库归属是 BrambleXu/dsh-annotate，许可证 MIT（目录页、GitHub license 字段和仓库 LICENSE 一致），主要语言 TypeScript。package.json 里的版本是 0.1.0，要求 Node.js ^22.19.0 || >=24.0.0。截至 2026-08-18，GitHub 显示 6 星；社区目录页当时列出的是 5 星，星标以仓库页面为准。
它不是单独的截图工具，也不是通用网页爬虫。插件在 dsh 进程里注册 /annotate 命令，并在本机 loopback 上开一个 WebSocket；配套的 Chrome 扩展连上这座桥之后，才能进入选择模式。README 写明交互受到 pi-annotate 启发，但实现走的是 Harness 的 human-command、attachment 和 Agent API，用小型 loopback WebSocket，而不是 native-messaging host。
核心功能¶
在页面上点选，而不是口述¶
在已连接扩展的前提下，会话里执行 /annotate，扩展会在当前活动标签页进入选择模式。鼠标移到元素上会画出高亮框；点击后弹出评论输入。可以连续点多个节点，点 Submit 一次性提交，Escape 或 Cancel 取消。
如果命令后面带 URL，例如 /annotate http://localhost:3000，扩展会先把当前标签页导航到该地址，等加载完成再开始选择。源码里会对输入做 new URL(url) 校验，空输入则沿用当前页。
每个元素带上可核对的页面事实¶
扩展的 content.js 和插件侧的 protocol.ts 约定了同一套字段。每个被选中的元素会贡献：
- 选择器：有
id时用#id，否则沿祖先拼一段最多 4 层的tag.class:nth-of-type路径 - DOM 事实：标签名、id、class 列表、截断后的文本（最多约 500 字符）、前 20 个 HTML 属性、视口内的矩形位置
- 计算样式高亮：
display、position、color、backgroundColor、font、margin、padding、border - 无障碍数据：
role（属性或标签隐含角色）、名称、是否可聚焦、是否 disabled - 评论：你在选择时输入的那句说明
整次提交还会带上页面 URL 和视口宽高。插件把这些内容渲染成 Markdown 风格的文本，再以插件通知的形式 followup 给当前 agent，摘要类似 Captured N browser annotations.。
可选的可见视口截图¶
扩展在提交时调用 chrome.tabs.captureVisibleTab，格式是 PNG。默认配置 includeScreenshot: true 时，插件会把截图存成附件 dsh-annotate.png，和文本一起交给模型。README 把范围限定为当前可见视口，不是整页长截图。
本地桥，而不是把浏览器暴露到网上¶
桥的默认地址是 127.0.0.1:43119。apply() 里如果 host 不是 127.0.0.1、::1 或 localhost，插件直接抛错退出。WebSocket 的 verifyClient 只接受 chrome-extension:// 来源；扩展连上后先发 hello（协议 version 1 + 扩展 ID）。allowedExtensionId 为空时接受任意本机已装扩展，填了则只认这一个 ID。载荷默认上限 16 MiB，请求超时默认 300000 毫秒。
安装与启用¶
社区目录页给出的安装命令如下，在 DeepSeek Harness 终端里运行即可：
dsh plugin add github:BrambleXu/dsh-annotate
如需可复现安装，目录页建议固定 commit 哈希：
dsh plugin add github:BrambleXu/dsh-annotate#commit
把 #commit 换成实际的 commit SHA，不要照抄字面量。官方 CLI 文档里 dsh plugin 会转发到当前 profile 的 pnpm；从仓库本地检出安装时，README 用的是：
dsh plugin --profile demo add ./dsh-annotate
插件只完成 Harness 这一侧。配套扩展还要手动装进 Chrome 或 Chromium：
- 打开
chrome://extensions - 启用开发者模式
- 选择加载已解压的扩展程序，指向仓库（或已安装包）里的
browser-extension目录 - 打开扩展弹窗，保留默认 bridge 地址
ws://127.0.0.1:43119
弹窗会显示当前扩展 ID。若要把连接收窄到这一份扩展，把该 ID 写进后面说的 allowedExtensionId。
目录页有一条安全提示，需要原样理解后再装：插件以当前 dsh 进程的权限运行，安装时可能执行代码。 安装前请检查源代码仓库和许可证。扩展清单是 Manifest V3，申请了 activeTab、scripting、storage、tabs，以及 <all_urls> 的 host 权限——这是它能在任意页面注入选择层、截可见标签页的原因，装之前应当自己看过源码。
典型用法¶
扩展已连接、dsh 进程已加载该插件后，在会话里执行：
/annotate
/annotate http://localhost:3000
然后在浏览器里：
- 把鼠标移到目标元素上，确认蓝色高亮框罩住的就是你要说的节点
- 点击，在弹出的提示里写下评论，例如「桌面宽度下这个主按钮和次按钮换行了」
- 需要的话继续点其他元素
- 点工具条上的 Submit；不想提交就按 Escape
提交成功后，命令返回类似 Sent N browser annotations to the agent. 的提示；agent 下一轮会读到页面 URL、视口尺寸、每个元素的选择器 / 文本 / 样式 / 无障碍字段 / 评论，以及默认附上的视口 PNG。一个常见用法是：本地前端跑在 localhost，让 agent 改样式或修复布局，你用 /annotate 把「错的是哪一块」钉死，而不是再写一段容易对错节点的自然语言。
默认配置来自仓库的 cordis.patch.yml，README 给出的可改项如下（allowedExtensionId 示例是占位符，请换成弹窗里的真实 ID）：
- id: dsh-annotate
name: dsh-annotate
config:
host: 127.0.0.1
port: 43119
allowedExtensionId: abcdefghijklmnopqrstuvwxyzabcdef
requestTimeoutMs: 300000
maxPayloadBytes: 16777216
includeScreenshot: true
扩展未连接时，命令会报 The dsh-annotate browser extension is not connected. 改过扩展文件后，需要在 chrome://extensions 里重新加载已解压扩展。仓库开发命令是 pnpm install 和 pnpm run check（类型检查、测试、构建）。
适用场景与注意事项¶
比较适合这些情况：
- 本地前端开发，agent 负责改 CSS / 组件结构，人负责在真实页面上指出节点
- 核对计算样式、按钮是否可聚焦、
aria-disabled是否生效这类「截图里看不出来」的事实 - 一次提交多个元素，把同一屏上的几处问题绑在同一轮反馈里
0.1 版本自己划定的范围也很清楚，README 写明：一台本地 Chrome/Chromium、一个活动标签页、可见视口截图。 远程浏览器、整页截图、编辑过程录制、可拖拽的行内批注卡片都还没有。不要指望用它去标远程真机、Firefox，或把整页长图送进模型。
还需要注意：
- 选择器是启发式拼出来的，复杂页面上不一定唯一；评论仍然有用，不要只靠选择器
- 文本、属性、祖先层数都有截断，超长节点不会完整进入上下文
- 桥只绑 loopback，扩展默认连
ws://127.0.0.1:43119；改端口或 host 时两边要一起改 allowedExtensionId为空等于接受本机任意来源为chrome-extension://的连接，多扩展并存时建议改成精确 ID- 插件跟当前 dsh 进程同权限，扩展又能读当前标签页并截屏。装的是社区仓库，不是官方应用商店，源码和许可证要自己看过再执行安装命令
小结¶
dsh-annotate 把「用手指一下页面」接进了 DeepSeek Harness 的对话循环：点选、写评论、提交，agent 拿到的是选择器、DOM、样式、无障碍数据和一张视口截图，而不是一句含糊的「那边有点问题」。它目前仍是 0.1 的本地 Chrome 方案，要同时装 Harness 插件和未打包扩展，安全边界也明确写在目录页上。
目录页：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-annotate/
GitHub：https://github.com/BrambleXu/dsh-annotate
