dsh-web-review/packages/dsh-web-review

一句话定位

在 DSH 内嵌浏览器里打开任意网页，像使用设计工具一样点选元素、填写修改意见并临时调整文本颜色字体等属性，发送后 Agent 据此修改工作区源码。

核心能力

• 在 DSH 的「网页预览」标签内加载任意无凭据 HTTP(S) 链接，会话运行在独立随机 Origin 的隔离 iframe 中。
• 悬停高亮并点选页面元素，逐个添加文字批注，单批最多 20 个元素。
• 通过展开「调整」面板临时修改文本、颜色、字体、字号、行高、尺寸、间距、布局、边框、圆角与效果等属性，改动即时预览、逐项可恢复。
• 选择元素后可查看 DOM 层级树与父/子/兄弟节点导航，支持子级、父级、上一/下一兄弟快捷定位。
• 批注附带选择器、可访问名称、可见文本与 React/Vue/Svelte 源码锚点，发送后作为独立 Browser Comments 上下文随提示词注入，由 Agent 用现有工作区工具改源码，临时样式不会写入工程。
• 内置 8 个 UI 优化 Skill（来自 jakubkrehel/skills），可在批注面板勾选，或用斜杠命令调用。

技术实现

• 语言: TypeScript（Node 端 + 浏览器端双面包），辅以 tsdown 构建；隔离 frame bridge 为独立 IIFE。
• 关键依赖: @deepseek-ai/cordis 4.0.1 / @deepseek-ai/dsh-* 0.1.0-rc.6（host-webserver、system-prompt、skill、session、agent、llm 等）/ parse5 HTML 解析 / css-selector-generator 元素选择器生成。
• 架构模式: 插件以「Node 半 + 浏览器半 + 隔离 frame IIFE」三段式注入宿主。Node 半通过 ctx.webServer.register 暴露 /webview-preview-sessions 与 /webview-annotations 同源控制接口，并启动一个绑定 127.0.0.1 随机端口的 loopback 预览代理；浏览器半注册 conversation.view（id webview）标签与 conversation.input.dock（id webview-annotations）共用同一 store；frame 通过 postMessage 版本化 bridge 与宿主通信，DOM 引用与回滚记录只活在 bridge 私有 map 里。批注上下文经 agent/pre-step 水合函数以独立 plugin-sourced user message 追加到消息批次。
• 入口文件: 浏览器端 src/client/index.ts:1-49、节点端 src/index.ts:41-89、frame bridge src/bridge/index.ts:1-49。

适用场景

前端开发者在与 DSH Agent 协作时，希望把视觉/文案/交互问题直接圈在浏览器页面上传达，而不必复制粘贴选择器或手写描述。 适合「页面已经能跑起来、需要按视觉/文案细节迭代」的场景，例如改颜色字号、调间距对齐、替换按钮文案、补可访问名称、定位多个相似元素一起改。 不适合直接套用：登录态复杂或强反爬的页面、带硬编码绝对 API 的页面、需要 HMR 实时刷新的本地开发服务，以及 file://、data:、内嵌账号密码的 URL（代理会拒绝）。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:CanglongCl/dsh-web-review/packages/dsh-web-review

配置项

唯一可调配置：autoLoadSkills 是 Cordis 配置字段，写在 dsh b 插件行的 config: 节里。配置必须在 DSH 启动前声明，运行期通过修改配置重启即可生效；不在此数组里的 Skill 仅隐藏于模型目录，不影响用户手动调用能力。

常见问题

Q: 安装后在哪里打开预览？

A: 启动 dsh web，在对话界面切换到「网页预览」标签，输入任意可访问的 HTTP(S) 链接回车即可。也可以直接在对话流里点 AI 回复给出的 HTTP(S) 链接，插件会捕获并自动切到预览。

Q: 一次可以批注多少个元素？支持改哪些属性？

A: 单批最多 20 个元素；单元素最多 48 项样式改动，整批合计不超过 200 项。可改文本、字体、字号、行高、颜色、背景、尺寸、内外边距、布局、边框、圆角与效果（透明度等），属性面板与 Figma 类似，数值字段同时接受 CSS 关键字（如 auto/normal/none）。

Q: 预览里的临时样式修改会写入工程吗？

A: 不会。所有视觉调整只是 bridge 私有回滚区的临时预览，重置、取消、关闭、成功发送、导航或 iframe 卸载都会精确还原原始 DOM；只有你点确认后形成的批注文本与属性改值会作为 Browser Comments 上下文发给 Agent。

Q: 插件如何隔离预览页面与 DSH 主站？

A: 每次预览分配一个随机的 *.localhost Origin，节点端起在 127.0.0.1 独立随机端口；DSH 宿主只提供同源控制接口，不返回目标页面字节，浏览器 Cookie 与 Authorization 一律不转发，跨域链接/重定向会进入新的隔离会话。生产代码从不直接读取 iframe.contentDocument，所有跨帧通信走版本化的 postMessage。

Q: 为什么登录页或带 Cookie 的页面在预览里看不到内容？

A: 隔离代理不会携带浏览器 Cookie，也不保留原始 Origin；登录态强校验、客户端证书或反爬机制可能渲染不完整。这是已知的安全隔离边界，没有「直连」模式可以绕过。

Q: 8 个 UI 优化 Skill 是什么？怎么开关？

A: 插件内置 jakubkrehel/skills 的 8 个 Skill：better-ui / better-typography / better-layout / better-writing / better-accessibility / better-colors / better-interface / interface-review。默认前 4 个对模型可见，8 个都可被用户斜杠命令调用；调整 Cordis 配置中的 autoLoadSkills 数组即可切换模型可见集合。

Q: 批注发送后 Agent 会怎么改源码？

A: 批注作为独立 plugin-sourced user message 随你的提示词一起送入模型（普通输入框文本由 DSH 原生序列化器原样发送，插件只追加自己的上下文）。Agent 使用工作区已有的工具定位并修改源码，临时预览不会落盘；改完手动刷新预览即可验收。

Q: 节点端改动后预览没生效？

A: 浏览器端代码改动刷新页面即生效；节点端代码（如 src/index.ts）改动需要重启 dsh web，因为 Web profile 下 cordis HMR 不会监听外部 bundle。

上手难度

入门 — 会装插件、会输入 URL 就能用，复杂的能力（精确 DOM 层级导航、属性面板）都有图形化提示，不需要写代码。

已知问题与限制

• 隔离代理不携带浏览器 Cookie，也不保留原始 Origin，登录态、客户端证书、强反爬页面可能渲染不完整。
• 页面 JS 中硬编码的绝对 URL 与 WebSocket 不会被改写，本地开发服务的 HMR WebSocket 无法穿透代理，实时刷新失效。
• 程序化跨域 location 赋值会让 bridge 失效，预览会自动报告「批注不可用」，不会回退到直读 DOM。
• 跨域 POST 表单被拒绝；file://、data:、javascript:、内嵌用户名密码的 URL 都被预览代理直接拒绝。
• 同一时刻只能预览一个页面，输入新 URL 或跨域跳转会自动清空当前页面的批注。
• 文本临时编辑仅对「只有一个直接文本节点」的简单元素生效，多子节点文本不会被改。
• 预览刷新需要手动触发，源码修改后 Agent 不会自动帮你点刷新。
• 节点端代码改动后必须重启 dsh web，Web profile 不对外部 bundle 做 HMR。

English

⭐ 如果这个项目对你有帮助，欢迎点个 Star 支持一下！你的支持是我持续维护和改进的动力。

在内置浏览器中，像使用设计工具一样选择页面元素、填写修改意见，并临时调整文本、颜色、字体、尺寸、间距、边框与效果。确认发送后，Agent 会结合页面批注修改当前工作区中的源码。

如果你用过 v0、Codex 等 Coding Agent 应用的内置浏览器，你应该对此会很熟悉。

安装

安装并启动：

dsh plugin --profile web add @canglongcl/dsh-web-review
dsh web

使用方法

1. 告诉启动要评审的前端页面，点击AI返回的地址页面。 也可以切换到 DSH 的「网页预览」Tab，输入页面的绝对 HTTP(S) URL。
2. 点击批注按钮，再点击页面中的目标元素。
3. 填写修改意见；如需视觉调整，展开「调整」并修改属性。
4. 点击批注工具栏中的发送按钮，发送后会自动切回「对话」Tab；或在 DSH 的输入框中填写更多提示词，然后点击 DSH 发送按钮，注释会随着你的提示词一同发送。
5. Agent 修改源码后，刷新预览进行验收；不满意可以继续下一轮批注。

主要功能

网页预览

• 在 DSH 内打开 Agent 提供的链接页面

元素批注

• 悬停高亮并点选页面元素。
• 为多个目标添加批注。
• 自动附带选择器、文本、可访问名称和源码线索，帮助 Agent 找到对应实现。

实时视觉调整

• 修改文本、颜色、字体、字号、行高、尺寸和透明度。
• 调整间距、布局、边框、圆角和效果。
• 所有修改即时预览。

AI 协作

• 批注会作为独立上下文随你的提示词注入。
• 对话中的页面批注沿用 DSH 原生折叠行：收起时显示页面与批注数，展开后只展示目标、修改意图、前后值和可用源码线索。
• Agent 根据批注修改当前工作区源码，页面中的临时调整不会直接写入工程。

UI 优化 Skills

插件内置了 Jakub Krehel 的设计 Skills：

• better-ui
• better-typography
• better-layout
• better-writing
• better-accessibility
• better-colors
• better-interface
• interface-review

你可以通过斜杠命令调用 skill，也可以在批注编辑器中选择，让 Agent 在本轮修改中参考相应规则。

插件能力评测

项目包含一套面向真实使用流程的评测，用于验证 Agent 在收到插件生成的页面批注后，能否正确定位源码并完成前端修改。

评测覆盖：

• 文案、样式、布局和响应式修改。
• 多元素与多项关联修改。
• React、Vue 和静态页面。
• 源码锚点可用及缺失时的定位。
• 语义化与无障碍要求。
• 多轮批注和修改范围判断。
• Token 使用量、执行步骤和运行耗时。

评测设计、运行方式和结果解释见 Eval suite。

参与开发

开发环境、架构说明与验证流程见 CONTRIBUTING.md。