网页浮窗助手 flymysql/dsh-browser-client

DSH 浏览器客户端

让 LLM 通过浏览器浮窗会话，理解并操作用户当前浏览的任意页面。

核心能力：在任意网页右下角浮窗中运行 DSH 会话 —— LLM 通过 page_ 工具读取页面快照、执行 JS、点击/输入/滚动、截图，操作的是用户已登录的真实浏览器（cookie/SSO/内网权限天然现成）。

┌─ 浏览器 ──────────────────────────────────────────────┐ │ content script（页面内执行 snapshot/eval/act） │ │ ↕ chrome.runtime.sendMessage │ │ 面板 iframe（聊天 UI + 双向 control WebSocket） │ │ ↕ HTTP RPC (/ext-api) + WS (/ext-api-control) │ ├─ DSH Host ─────────────────────────────────────────────┤ │ dsh-browser-host 插件 │ │ · /ext-api RPC 代理（复用官方 apiProxy 通道） │ │ · /ext-events.mux 事件流 │ │ · /ext-api-control 双向通道（工具请求↔回包） │ │ · page_ 工具注册（harness → tools.register） │ └───────────────────────────────────────────────────────┘

结构

lib/
index.js # 插件入口：路由/WS/工具注册 bridge.js # 双向通道：工具请求挂起/回包路由/超时/断连 tools.js # 6 个 page_* 工具定义（中继到扩展执行） browser-ext/extension/ manifest.json # MV3 扩展（storage/activeTab/scripting/tabs） content/content.js # 浮窗气泡 + Shadow DOM 面板注入 content/page-tools.js # 页面执行核心（snapshot/eval/act/...） background/background.js # 配置 + URL→目录映射 + 截图 panel/ # 浮窗聊天 UI common/dsh-client.js # 双向 wire client docs/ BUSINESS_PLAN.md # 完整商用方案 USER_GUIDE.md # 安装/使用/故障排查 test/ bridge-unit-test.mjs # 通道生命周期单测（通过） e2e-page-tool.mjs # 全链路 E2E（LLM→工具→通道→扩展→回包→回答）

页面工具

| 工具 | 作用 |
| page_snapshot | 页面结构化快照（URL/标题/可见文本/交互元素+坐标） |
| page_eval | 页面 MAIN world 执行任意 JS 读数据 |
| page_act | 点击/输入/滚动/键盘/清除（坐标或选择器） |
| page_navigate | 跳转/后退/前进/刷新 |
| page_wait | 等待选择器/网络空闲/延时 |
| page_screenshot | 截图（视口/元素/整页） |
| page_network | 读取页面 fetch/XHR 请求（URL/方法/状态/响应体预览） |

⚠ 工具名用下划线不用点号（page_snapshot 而非 page.snapshot）：腾讯 intranet 网关拒绝含点号的工具名。详见 docs/BUSINESS_PLAN.md 的踩坑记录。

快速开始

1. Host 插件：把 cordis.patch.yml 插入 DSH profile，重启 DSH。启动日志打印 token 并注册 6 个工具。
2. 扩展：Chrome → chrome://extensions → 开发者模式 → 加载已解压 → 选 browser-ext/extension。
3. 配置：面板 ⚙ 填 Host 地址 + token（$DSH_HOME/browser-client-token）。
4. 使用：浮窗里问"这个页面现在显示什么？" → LLM 调 page_snapshot 回答。

详见 docs/USER_GUIDE.md。

测试

1. 通道单元测试（不需要 DSH 进程）
node test/bridge-unit-test.mjs

2. 全链路 E2E（需要：DSH 测试实例 + LLM key） boot test/env 实例 + 模拟扩展回包，验证 LLM→工具→通道→页面→回答
node test/e2e-page-tool.mjs
node test/e2e-page-network.mjs

3. 真实浏览器 E2E（需要：360Chrome 加载扩展 + DSH 实例）真实面板 + 真实 content script 执行 page_snapshot，LLM 读取真实页面数据
node test/live-e2e-real.mjs

实机验证记录

在 360Chrome（Chromium 132）加载扩展 + DSH host（:3999）实测通过：

- 页面右下角浮窗注入（Shadow DOM）✅
- 面板连接 host、绑定工作区、加载会话列表 ✅
- 真实链路：面板提问 → LLM 调用 page_snapshot → 控制通道 → 面板 → content script → 读取真实页面 DOM（"机械键盘 ¥299 / 降噪耳机 ¥899 / 4K 显示器 ¥1999"）→ 回传 → LLM 完整作答 ✅

⚠ Chrome 151+ 在 macOS 上禁用了 --load-extension 命令行加载；实测 360Chrome 支持。Chrome 用户需通过 chrome://extensions 开发者模式手动加载。

状态
- ✅ 阶段 1（双向通道 + 6 个 page_* 工具 + E2E 验证）完成
- 🔜 阶段 2（操作审批流、页面笔记、多 tab 编排）
- 🔜 阶段 3（浮窗 UI 升级、打包 crx、视觉闭环打磨）

详见 docs/BUSINESS_PLAN.md。

验证规范（重要）

绝不启停 3080 生产实例。所有验证通过独立新端口实例进行：

启动隔离实例（默认 4101，可指定任意端口） ./test/verify-boot.sh 4101 停止 ./test/verify-boot.sh 4101 stop

指向该实例跑测试（token 是 per-port 的）
DSH_BASE=http://127.0.0.1:4101 TOKEN_FILE=test/env/browser-client-token-4101 \
node test/workflow-store-test.mjs

- 每个端口实例有独立 token 文件（browser-client-token-）和日志（boot-.log）
- 存储后端共享 $DSH_HOME，天然验证跨实例持久化

网页工作流功能（面向非研发人员）

用户用对话描述重复性网页工作 → LLM 生成可保存/重跑的工作流 → 自动执行。

能力一览

| 能力 | 说明 |
| workflow_generate 工具 | LLM 把对话需求转化为结构化工作流并保存 |
| page_record / page_highlight | 录制用户演示 + 元素高亮确认 |
| 执行器 | 按步执行：navigate/action/extract/wait/ask/approve/loop/subflow/branch，重试+ask-user 自愈 |
| 持久化 | storageDomain（跨实例验证） |
| 定时触发 | trigger.kind=schedule，30s tick 检查 |
| 技能封装 | 每个工作流自动注册为 DSH skill（模型可发现） |
| 斜杠命令 | /workflows 列出、/run 运行 |
| 场景模板 | 6 类高频场景（批量填表/采集/搬运/批量操作/多账号/巡检） |
| 模板分享 | export/import 参数化 JSON |
| 面板 UI | 工作流 tab：列表/运行/删除/模板/进度 |

工作流数据模型见 lib/workflow/schema.js（WorkflowDefinition + ElementTarget 多路语义定位）。

测试
node test/workflow-store-test.mjs # 保存/校验/持久化
node test/workflow-executor-test.mjs # 执行器全链路（ask/approve/重试）

探索模式（复杂任务的关键能力）

用户需求复杂时，LLM 可能无法一次给出方案。探索模式让 LLM 边操作边学： explore_start → 反复 explore_act（试错，成功/失败都记录）→ explore_check 验证目标 → explore_finish 把验证过的成功路径提炼成干净的工作流（失败的尝试自动丢弃）。

node test/explore-mode-test.mjs # 探索→提炼→保存 闭环验证

面向非研发人员的交互
- 系统提示词段：LLM 用大白话沟通、复述确认需求、主动引导、失败说人话
- 面板探索横幅：实时显示"正在尝试… / 需要你回答… / 完成"
- 场景模板 + 引导式提问，不让普通用户面对空白画布