dsh-browser-live · 看得见的 Agent 浏览器（DSH 标准插件）
让 agent 驱动本机真实 Chrome/Edge/Brave（CDP 直连，无 vendored 运行时、无裸 npm 依赖），
并在右下角开一块实时观察窗：agent 在网页上干什么，你全程看得见，还能直接接管鼠标键盘。
v0.5.0 起还可选接管你自己的日常浏览器（装一个 MV3 扩展，带你的登录态/代理，P0 只读）。
设计灵感来自 dsh-ego-browser（MIT）。本插件是自研实现：
不携带 ego-lite 运行时、零裸 import，与 link: 本地安装工作流完全兼容（同 dsh-bg-atelier / dsh-cache-control 约定）。
它解决什么
DSH 内置的 web_search/web_fetch 只能"读"；凡是必须真浏览器的活（登录态、动态渲染、表单、验证码、
需真人会话的站点）就干不了。装上本插件后，agent 获得 18 个 browser_* 工具，能真正在页面里
点击、输入、提交、滚动、取快照；你在观察窗里实时看到每一步，卡在验证码时点进面板亲手代打，
完事再把鼠标还给 agent。
组成
| 文件 | 职责 |
|---|
index.js | Host（ESM）：拉起/接管 Chrome → CDP；注册 18 个 browser_* 工具；/bl/* 观察窗后端（SSE 帧流 + 输入回传 + 设置/代理 + 下载取回 + /bl/view 独立网页 + /bl/bridge 桥状态） |
bridge.js | 用户浏览器桥（P0）：127.0.0.1 WS 服务端 + token 握手 + 与 Cdp 同形的 send/on/alive/close |
extension/ | Chrome MV3 扩展（P0）：service worker 当"反向 CDP 客户端"（chrome.debugger），弹窗逐站点授权；见 extension/README.md |
client.js | Client 单文件：侧栏 🌐 按钮（无 slots 环境退化为自建浮球；与 bg-atelier 宝珠叠列共存）+ 观察窗（实时帧、标签条、agent 动作条、鼠标键盘接管、FPS/画质、下载取回；内嵌面板可拖动贴边，或切成独立网页） |
cordis.patch.yml | bundle 装载声明（行 id == 包名，客户端模块扫描按 manifest name 匹配） |
package.json | dsh.bundle.patch + dsh.client（platform web，注入 runtime/ui-slots） |
安装（本机 link，与 dsh-bg-atelier 同套路）
dsh plugin --profile web add link:D:\DeepSeek\dsh-plugins\dsh-browser-live
装完重启一次 DSH Desktop。设置 → 插件 里可开关；侧栏底部出现 🌐 观察窗按钮。
换台机器：可迁移性与必须手动的步骤
给后续在任何一台机器上接手的人或 agent —— 本插件有一部分能力拿不到就是拿不到，必须人手动做，
别在换了机器之后以为"克隆+重启就完事"。起因：用户 2026-09-12 反馈
"工作电脑上传，回家发现可用性很差，一定需要手动操作，比如到浏览器安装本地插件"。
分两档能力，先认清你要哪一档：
| 能力 | 需要什么 | 能自动吗 |
|---|
| 插件自带实例（独立窗口 + 独立 profile，免逐站点授权） | 只要插件装好 + 重启 | ✅ 全自动，browser_open 直接开 |
| 接管你的日常浏览器（要你的登录态：后台/飞书/公司系统） | 必须装浏览器扩展（MV3，本仓库 extension/ 里）+ 粘 token + 逐站点授权 | ❌ 扩展安装与授权只能在浏览器里点 |
B 档的四步手工操作（agent 只能把现场备好，点不了）
- 打开扩展管理页：Chrome
chrome://extensions / Edge edge://extensions → 开开发者模式
- 加载解压缩的扩展 → 选中本仓库的
extension/ 目录
- 点扩展图标打开弹窗 → 粘贴 token → 「连接」
- token 在哪：
$DSH_HOME/dsh-browser-live/bridge.json 的 token 字段
- 省事做法：让 agent 调
browser_ext_setup —— 它会置 userBridge=true、把 token 放进剪贴板、
打开扩展页、并在文件管理器里打开 extension/ 目录；人只剩"开发者模式 + 加载 + 粘贴 + 连接"这四下
- 在扩展弹窗里逐站点授权：每个要操作的站点点「允许」（默认只读）；要真点击/打字/上传，
还得打开「允许操作」（
allowInput），否则 agent 只能看不能动
其余换机事实（都不随仓库走）
- 状态与凭据全在
$DSH_HOME/dsh-browser-live/：settings.json（含 userBridge / headless /
浏览器路径 / 代理等）、bridge.json（端口 + token）、chrome-profile/（登录态）、
downloads/、shots/、audit/（留痕）。换机器后 userBridge 是空的 ⇒ 桥不会自己开，
要重跑一次 browser_ext_setup 或手动置 userBridge: true。
- 扩展是 MV3 本地加载的，不是商店包 ⇒ 换机器/换浏览器/换 profile 都要重装一遍（第 1–3 步）。
扩展掉线时 host 会自动回退到"插件自带实例"这一档，所以"接管失败"往往表现为换了个后端而不是报错。
- 浏览器探测：本机装了 Chrome/Edge/Brave 任一即可；
headless=true 时无头也能全通，但画面是虚拟的
（观察窗看的是渲染结果）。首选浏览器起不来会自动降级到下一个候选，并补试兼容参数 --in-process-gpu。
- 留痕（v0.9.0 起）：所有
browser_* 调用与页面自身跳转都追加到
$DSH_HOME/dsh-browser-live/audit/YYYY-MM-DD.jsonl（append-only + 哈希链）。
node tools/verify-audit-chain.mjs 验链；node tools/verify-audit.mjs 离线自检 15 项。
- 已知宿主坑（三个插件共有）：部分 DSH Desktop 版本启动时的
installGeneration 迁移会把
link: 挂载的插件重新 stage，并把绝对路径当相对路径拼接 ⇒ ENOENT、迁移 defer、
插件可能不加载。本机靠应用 bundle 的本地补丁（KEEP_IN_SHARED_TREE）绕过，该补丁不在本仓库；
识别：启动日志 migration deferred / could not stage。DSH 每次升级都会覆盖它，升级后要重跑。
设置导出/导入（换机器一键搬配置，v0.9.0 新增）
node tools/settings.mjs export --out D:\bl-settings.json # 旧机器
node tools/settings.mjs import D:\bl-settings.json --yes # 新机器（覆盖前自动备份 settings.json.bak-*）
show 看当前值；不带 --yes 演练。会搬 fps / 质量 / 无头 / 窗口尺寸 / 代理 / 观察窗形态 /
拟人轨迹与速度 / userBridge / backendMode / userDefault / 端口，并主动提示两件换机后必须人做的事：
userBridge=true 说明还要人工装扩展 + 重跑 browser_ext_setup；chromePath 指向的路径在新机器上可能不存在（空了会自动探测）。
不含：浏览器扩展、bridge.json 的 token、chrome-profile/ 登录态、audit/ 留痕 —— 这四样本就该每台机器各自一份。
换机后自查
node tools/verify-audit.mjs # 期望 PASS 15 项
node tools/verify-host.mjs # 期望 58 passed（3 项 fail 是套件无真 Chrome 的既有失败）
node tools/verify-audit-chain.mjs # 期望 0 = 链完整（还没留痕时会跳过并返回 0）
工具一览（agent 侧）
| 工具 | 说明 |
|---|
browser_open | 启动/接管浏览器（懒启动），可选 url / newTab / use |
browser_ext_setup | 一键备好"接管你日常浏览器"的现场：开桥（userBridge=true）→ token 进剪贴板 → 打开目标浏览器的扩展页 → 资源管理器里打开 extension/ 目录，并把步骤列出。kind 选 edge/chrome，open:false 只返回路径与 token |
browser_navigate | 导航并等加载完成 |
browser_snapshot | 结构化快照：可见交互元素清单（ref 编号+坐标）+ 正文节选。点击前先拿 ref |
browser_click | ref / CSS selector / 坐标三选一，真实鼠标事件（右键、双击可选）；默认走拟人贝塞尔轨迹（instant:true 可瞬移） |
browser_move | 拟人移动鼠标（触发 :hover/下拉/tooltip）；hold 按住左键、instant 瞬移 |
browser_type | 聚焦输入框（自动全选便于替换）+ 插入文本，可回车 |
browser_upload | 本机文件塞进 <input type=file>（不弹系统对话框）；ref/selector 可指上传按钮/拖拽区容器，自动解析其中隐藏 input（Meta Ads 等 React 自定义上传组件适用）；触发 change 事件 |
browser_press | 按键/组合键：Enter、ctrl+a、alt+ArrowLeft… |
browser_scroll | 滚轮方向+像素 |
browser_wait | 等文本出现 / 选择器命中 / URL 片段 / 纯等待，带超时 |
browser_eval | 页内 JS 表达式（returnByValue + await 可选） |
browser_text | 正文分块提取（比快照省 token） |
browser_screenshot | 可视区/整页 PNG 落盘，路径可直接交给读图工具 |
browser_tabs | 标签页 list/new/select/close |
browser_history | 前进/后退/刷新（可强刷） |
browser_downloads | 下载目录清单（观察窗里也能一键取回；用户浏览器那档仍只列插件实例的目录） |
browser_close | 关浏览器（profile 保留，登录态不丢）；用户浏览器那档只断开调试器，不关你的浏览器 |
每个工具都带一个 use 参数（v0.7.0）——'plugin' / 'chrome' / 'edge' / 'user' / 'auto'，
用来在同一个会话里指定这次调用落在哪台浏览器上（详见「接管你自己的浏览器」一节）。
不写 use = 沿用上一次调用用的那台。
所有工具串行互斥（一次只跑一个）；首次调用自动拉起浏览器并弹观察窗。
拟人轨迹（v0.3.0）
agent 的鼠标移动（browser_click / browser_move）默认不再是"瞬移出现"：
三次贝塞尔弧线 + 两端慢中间快的缓动 + 随进度衰减的正弦抖动 + 偶发微停顿，
事件仍从 CDP 输入管线注入（isTrusted === true，与真鼠标同层）。
- 设置项：
humanize（默认 true，关掉回到瞬移）、humanSpeed（0.34，默认 1，约 0.150.45s/中程）。
- 单点距离 < 6px 自动走直线，不做无意义插值。
- 观察窗接管的实时输入不走插值（你的手感必须即时），它本身就是真人轨迹。
- 注意：插值只作用于页面感知到的鼠标，Windows 系统光标不会跟着动（OS 级注入是另一层，未做）。
观察窗
两种形态（设置页「观察窗形态」可切换，切换当场就把窗口交接过去、不用退出重进；面板标题栏 ⧉ 也能随时弹出独立页）：
- 内嵌面板：DSH 右下角浮动窗，可按住标题栏拖动、拖近边缘自动贴边、位置记忆在 localStorage；
- 独立网页
/bl/view：新标签/新窗口里的全屏观察窗，适合丢到副屏或 F11 盯着看；
选了这个形态后，🌐 与 agent 冷启动自动弹的都走独立页（浏览器拦弹窗时自动退回内嵌面板）。
共同能力：
- 直播：
/bl/stream SSE 推 JPEG 帧（FPS/画质在窗内可调）。
- 接管：窗里鼠标点击/滚轮/键盘 →
/bl/input → CDP Input，作用在同一个页面上；
坐标按 vw/渲染宽 等比映射，缩放窗格不会点偏。
- 透明：窗底一行"🤖 最近动作"，agent 每步工具调用都可见；标签条可点切换会话页。
- 取回：下载完成自动出现 ⬇ 链接，点了直接经
/bl/download 拿文件。
- 不常驻：agent 冷启动浏览器时自动弹一次；你主动 ✕ 收走后，本页生命周期内不再自动打扰。
- 不挡路（v0.4.2 浮球 / v0.4.3 面板）：
- 浮球：侧栏 🌐 与叠列地球钮是
position:fixed + 近上限 z-index，正常页面上必须
盖住侧栏才点得到；设置页/对话框开着时它会沉到那层遮罩底下（不是消失）——和壁纸宝珠同一待遇：
宝珠没有任何特殊样式，它看着朦胧只是因为被设置页那层半透明 + backdrop-filter 的遮罩盖着。
做法：在浮球中心做一次 elementsFromPoint，取"盖住 ≥1/4 视口"的那个元素，沿祖先链找最大数值
z-index，浮球 z 设成它 − 1，同一层磨砂把它一起糊掉；弹层关掉自动浮回原层级。量不到遮罩层级时
（设置页不是带层级的固定遮罩那一类）退回就地磨砂：opacity .3 + blur(2px) 再垫一块自带
backdrop-filter 的小玻璃板，看着仍是一层影而不是硬压在内容上。
- 面板：560px 那块窗沉下去就等于什么都看不见，所以 v0.4.3 改成收进独立页：设置页一开，
摊着的内嵌面板自动收掉并弹
/bl/view（可丢副屏、F11，与设置页互不干扰）；离开设置页时，你已经
把独立页关了才还回面板，还开着就不动 —— 不会出现同一画面两份。window.open 被浏览器拦掉时
（非用户手势有可能）不收，面板留着至少还能看。showPanel 也认这个状态，所以在设置页里
agent 冷启动浏览器时同样直接弹独立页，不会把面板摊在设置内容上。
数据与隐私
全部落在 $DSH_HOME/dsh-browser-live/：settings.json、state.json、bridge.json（用户浏览器桥的端口与 token）、
chrome-profile/（登录态）、downloads/、shots/、audit/（留痕，见下）。CDP 只绑 127.0.0.1；
观察窗路由与宿主其他插件路由（/bga/*、/cc/*、/api/*）互不重叠。
不关闭浏览器时它会一直在——用完调 browser_close 或点面板 ⏹。
留痕（v0.9.0：agent 用浏览器做过的每一步都落盘）
动机很直接：agent 完全可以"开浏览器 → 操作 → 自己关掉"，事后你只剩一个空窗口。
v0.9.0 起，每一次 browser_* 工具调用（含 browser_open / browser_close）和
每一次页面自己发起的跳转都会追加到 $DSH_HOME/dsh-browser-live/audit/YYYY-MM-DD.jsonl：
| 字段 | 含义 |
|---|
type | boot（宿主启动）/ tool（工具调用）/ nav（页面发起的跳转） |
tool / args | 工具名与参数原文（超 4000 字截断并标注原文长度，不假装完整） |
ok / err / ms | 成功与否、错误信息、耗时 |
urlBefore / urlAfter | 调用前后所在页面的 URL —— "他点了什么、落到哪一页"看这里 |
prev / h | 哈希链：h 是本条内容的 sha256，prev 指向上一条的 h |
收口点只有一个：所有工具都在 index.js 的注册循环里被 withAudit() 包了一层
（不是逐个工具加埋点 —— 那样必然会漏，新增工具时还会再漏）。
node tools/verify-audit-chain.mjs # 校验今天的留痕链是否完整
node tools/verify-audit-chain.mjs <文件或目录>
能力边界（别把它当保险箱）：追加写 + 哈希链能查出"删了一行 / 改了一行"——
tools/verify-audit.mjs 里就有这两条断链断言。但日志和 agent 在同一台机器、同一个用户下，
拥有完整写权限的人可以把整条链重算一遍，因此它挡的是"顺手抹掉一两步"，不是防篡改。
真要不可抹，得把这条 JSONL 实时送到 agent 够不到的地方（另一个进程 / 另一台机器）。
另外，"关掉 agent 自己开的页面"这个权限本来就不在 agent 手里：它由浏览器右上角扩展弹窗里的
「允许关闭 agent 自己打开的标签页」开关控制（extension/popup.js + background.js 的
allowCloseOwn 判定，默认开；关掉之后连它自己开的也关不了），你手动开的页面任何情况下都不在范围内。
前置条件
- Node ≥ 22（DSH Desktop 自带）；宿主 ≥ 0.1.2（defineTool 解析带 lite 兜底，装不上也只降级不崩）。
- 本机任一 Chromium 系浏览器：Chrome / Edge / Brave（自动探测；探测失败在设置里填
chromePath）。
- 无头服务器也可用：设置
headless=true 后工具全通，只是画面是虚拟的。
- 调试提示：若你在受限沙箱终端里跑本插件的 e2e 脚本，Chrome 会因命名管道被拒而
FATAL mojo platform_channel (0x5) 自杀——表现为 CDP 连上后立刻 1006 断开。
这不是插件问题：宿主内正常运行不受影响；离线验证请用允许命名管道的会话跑
node 03-调试临时\bl-e2e.mjs。
接管你自己的浏览器（v0.5.0 起；v0.7.0 起 Chrome / Edge 可同时接入）
默认后端是插件自拉的隔离实例（独立 profile，登录态是插件自己的）。
想要 agent 用你日常那个浏览器的登录态/代理/扩展，走扩展路线：
host(index.js) ──WS──> 扩展（extension/, MV3，Chrome 和 Edge 各装一份）
└── chrome.debugger ──> 各自真实的标签页
Chrome 与 Edge 各装一份扩展，两条连接可以同时挂在桥上；每次工具调用用 use 指定用哪台。
会话状态（标签页列表、当前标签、CDP 会话）按浏览器分开存，不会串台；
sessionId 一律带 <浏览器>: 前缀，桥靠这个前缀把请求和事件路由到正确的那条连接
（协议见 docs/MULTI-BROWSER.md）。
为什么必须装扩展、不能直接 CDP attach 你的浏览器：Chrome/Edge 136+ 在默认 user-data-dir 上
直接忽略 --remote-debugging-port / --remote-debugging-pipe（安全加固，CVE-2025-4051/4052）。
本机 Chrome 153、Edge 152 都早就过了这道线，chrome.debugger 是唯一像样的路。
开启：设置页「浏览器观察窗 → 用户浏览器」点成「桥已开启」（面板显示端口 + token，可一键复制），
然后按 extension/README.md 在 Chrome 和 Edge 里各加载一次扩展并粘 token。
同一个 token 两边通用；桥只绑 127.0.0.1，握手要 token，升级请求只认 chrome-extension:// 的 Origin
（网页里的 ws://127.0.0.1 连不进来）。设置页会列出当前已接入的浏览器，并可指定
use:"user" 默认用哪台（直接写 use:"edge" / use:"chrome" 永远优先于这个默认值）。
日常用法（"免登录页 / 要登录的页"分工）：默认档 auto 下，免登录的网页一律走插件自带实例
（不受逐站点授权限制、可 newTab 新开页）；只有确实要你的登录态时才切到你的浏览器：
- 在那台浏览器的扩展弹窗里给该站点点「允许」（整批页面可点「允许当前所有标签页」；
要真点击/打字再打开「允许操作」）；
browser_open { url, use: "edge" } → agent 在 Edge 当前标签页里导航/操作。v0.3.2 扩展起它也能
newTab 新开页（开到你指定的 http/https，弹窗「允许 agent 新开标签页」控制，默认开）；
新开的页记在 agent 名下，所以可被它自己关，你原有的标签页一个字都不动；- 完事
browser_open { use: "plugin" } 切回独立窗口，后面的免登录活继续不受授权限制。
use 取值：plugin（自带实例）/ chrome / edge（你的浏览器，必须已接入）/ user（settings.userDefault 那台）/
auto（桥连着就用你的浏览器）。不写 use = 沿用上一次调用用的那台，冷启动默认 plugin；
显式指定的浏览器没接入时会明确报错并列出当前已接入的 —— 绝不静默换到另一台去操作。
browser_open 的返回值里 browser 字段告诉你当前实际用的是哪个（插件自带实例 / 你的 Edge），
connected 列出当前已接入的浏览器，hint 直接给出下一步该传什么。
三层开关（都在扩展弹窗里，逐层收紧；两台浏览器各自一套）：
| 开关 | 默认 | 作用 |
|---|
| 逐站点「允许」 | 无授权 | 没点过的站点，url/标题对 agent 一律打码，调试器也附加不上 |
| 「允许当前所有标签页」 | — | 一次性把该浏览器里所有 http(s) 标签页的 origin 并入白名单（不打开「允许所有网站」） |
| 「撤销全部授权」 | — | 清空白名单（有二次确认） |
| 允许操作（v0.6.0 / P1） | 关 | 打开后才放行 Input.* 与 DOM.setFileInputFiles（真点击/打字/按键/滚轮/上传） |
| 允许所有网站 | 关 | 高风险：放弃逐站点确认 |
只读能力（永远可用）：browser_snapshot / browser_text / browser_screenshot /
browser_tabs list / browser_navigate / browser_wait。观察窗照样直播（帧也是经扩展回的
Page.captureScreenshot），/bl/view 与内嵌面板会亮红标：只读时「🔴 正在读取你的 Edge」，
打开「允许操作」后变成「🔴 正在操作你的 Edge（可点击/打字）」。
P1 操作能力（需打开「允许操作」）：browser_click / browser_move / browser_type /
browser_press / browser_scroll / browser_upload —— 事件经 chrome.debugger 注入
（isTrusted:true，与真人同层），拟人鼠标轨迹照旧生效。
实机测出来的三条硬约束（v0.6.0 已处理，但你必须知道）：
- 输入只送到「可见 + 窗口有焦点」的标签页。后台标签、失焦窗口下 Chrome 会静默丢弃
Input.dispatchMouseEvent（键盘偶尔能过，所以看起来"半好"）。扩展在发任何输入前会
chrome.tabs.update({active:true}) + chrome.windows.update({focused:true})，
等窗口真的拿到焦点后再等 300ms 才发事件 —— 也就是说 agent 动手时会把 Chrome 拉到前台。
Windows 的前台锁定可能拒绝被抢焦点（任务栏闪烁而不切换），这时需要你手动点一下 Chrome 窗口。
只读命令（截图 / 取文本 / 快照）不会抢你的前台标签。
disabled 的表单控件收不到鼠标事件（Chrome 行为，不是接管失败）：真点击一个 disabled
输入框会"没反应"。实测番茄渠道商后台「新增推广链」里的「书籍ID + 搜书」搜索框就是
disabled:true（要先选「选择包」等前置项），点它没反应是页面状态；同对话框里可用的
「书籍ID」表单项真点击/真打字正常。- 坐标必须一次到位：元素若在测量后被页面重排（Element UI 的对话框滚动），点击会落空。
用
instant:true 可把"测量→下发"的间隔压到一个往返，成功率高得多。
仍然被拒（扩展侧硬拒，会以错误结果返回，不会静默）：
| 被拒 | 原因 |
|---|
browser_tabs new/close | new 需扩展 v0.3.2+ 且弹窗「允许 agent 新开标签页」开着（自带实例档无条件允许）；close 只关 agent 自己开的页（Target.closeTarget，你手动开的一律拒绝） |
browser_downloads | 列的仍是插件实例的 downloads/ 目录，看不到你 Chrome 自己的下载（接 chrome.downloads 属 P2） |
| 未授权站点 | 逐 origin 授权；没授权时连调试器都附加不上，开了「允许操作」也进不去 |
| 改网络 / 模拟器 / 改属性 | Network.setExtraHTTPHeaders、Emulation.*、DOM.setAttributeValue 不在接管范围 |
兜底：扩展掉线 → 下一次工具调用自动回退插件实例（行为与 v0.4.3 完全一致）；
browser_close 在用户浏览器模式下只拆调试器，绝不关你的浏览器；
扩展侧会话失效（SW 重启 / DevTools 抢走调试器）时 host 会自动清 session 重试一次。
已知缺口：Runtime.evaluate 在扩展白名单里（snapshot/text 靠它取正文），所以扩展拦得住
"合成输入"，拦不住页面内 JS 自己点按钮 —— 也就是说 browser_eval 理论上仍能代打。
真正的护栏是逐站点授权 + 「允许操作」开关 + Chrome 那条无法隐藏的「正在调试此浏览器」横幅。
收窄 evaluate（改成固定脚本下发）仍是待办。
已知边界（v0.5.0）
- 观察窗单实例（整个宿主一个浏览器会话，不做多会话隔离）；多 agent 并发浏览请串行使用
（多个会话共用同一受控 Chrome 时会互相抢标签页，这是设计如此，不是 bug）。
- 默认后端仍是插件自拉实例；接管你日常浏览器是 v0.5.0 的扩展路线（P0 只读，见上），
P1（输入接管）/ P2（审批联动、evaluate 收窄）未做。
Page.captureScreenshot 取帧（非 screencast 事件流），高 FPS 下 CPU 开销线性上涨，默认 2fps。browser_upload 支持 <input type=file>（含隐藏 input、React 自定义组件的 label 包裹）；纯 HTML5 拖拽（无 input）与跨 origin iframe 内交互未做。- 拟人轨迹 = 页面侧事件流仿真；系统光标位置不动，比对
screenX 与 OS 光标高阶风控理论上可辨（极少数场景）。
- agent 靠 DOM 快照决策，"看不懂" Canvas 图表/图片内容——视觉闭环留 v1（DOM 为主、截图+视觉模型为辅）。
投放/运营场景模板（开箱即用）
把下面这些当 prompt 直接发给带本插件的 agent 即可；它们都遵循"只读→半自动→人工终审"的稳妥节奏。
- 竞对情报（零风险，先跑这个）
用 browser_open 打开 Meta 广告资料库，搜 "GoodNovel"，snapshot 后把近 7 天投放的
文案钩子 / 素材形式 / 起量日期 / 落地页 URL 抽成表格存成 csv。
公开数据、无登录墙、无风控。抽出的结构化数据可直接喂给 LLM 产素材变体。
- 落地页巡检（真浏览器 + 真地区才有价值）
依次用 --window-size=390,844（iPhone 视口）打开这几条落地页，每张存图并检查：
付费按钮是否存在、首章文案有无截断、深链是否 404、像素有无发起请求。
需要查地区差异时，在设置页「代理服务器」填 http://<国家代理>（或 socks5://…）——
它直接翻成 Chrome 的 --proxy-server，等价于以前往 extraArgs 里手写参数，下次拉起浏览器生效。
- 半自动发布（人机协作，别全自动点 Publish）
在 Ads Manager 建好 Ad Set（预算/国家/兴趣词/落地页），素材用 browser_upload 传入，
填完文案后停在 Publish 前，打开观察窗等我人工确认。
配合已装的 dsh-approval-gate：可配成 browser_click 默认放行、唯独命中 Publish 转人工审批。
风控纪律：主账户只走"前端 UI 自动化"（等价真人点击）；browser_eval 打内部 GraphQL 取 JSON
属于灰色地带，仅限只读且用独立测试账户隔离——"能拿到数据" ≠ "应该这么做"。Google Ads 对此更敏感。
版本与变更记录
-
v0.8.3：「不动你正在看的页面」＋「Chrome 起不来不是提权，是安全软件拦了 GPU 沙箱」 ——
① 接管你的浏览器时，"当前页未授权、目标站已授权"不再就地导航（那会把你正在读的页面换掉），
改成 chrome.tabs.create 新开一个标签页、附加到新标签页，你原来的页面一个字都不动；
扩展把真实 tabId 报回 host，host 据此纠正映射（否则列表显示"旧标签页已附加"、操作却落在新标签页上）。
② 更正 v0.8.2 的错误归因：Chrome 静默退出不是"DSH 以管理员运行"—— 本机用计划任务
（干净父进程、中完整性、脱离 DSH 作业对象）复测照样起不来，而加 --in-process-gpu 就正常；
真凶是火绒 HipsDaemon 拦掉 Chrome GPU 进程的沙箱初始化（Edge 因微软签名被放行）。
启动链因此改成"先常规试 → 失败补试 --in-process-gpu → 成功就记进 state.json 下次直接用"，
并刻意不用 --no-sandbox（渲染器沙箱要留着），verify-launcher 有断言钉死这条底线。
-
v0.8.2：「Chrome 起不来 = 整个插件不可用」＋「中文用户名下浏览器根本拉不起来」 ——
启动链上两个只在真实机器暴露的坑。① VBS 独立启动器原来用 UTF-8 写、wscript 按 ANSI 读，
中文用户名（C:\Users\陈道云\…）被读成乱码路径 → 浏览器一个进程都不起，对外只报「未响应 CDP 端口」，
还在 C:\Users 下留下乱码目录；现在写 UTF-16LE + BOM。
② 首选浏览器起不来时不再全盘失败：findChromiumExes() 返回候选列表
（chromePath → 环境变量 → Chrome → Edge → Brave）逐个尝试并自动降级。
这条是实测逼出来的：DSH Desktop 以管理员身份运行时，Chrome 会因无法在提权父进程下初始化沙箱
而静默退出（加 --no-sandbox 才起，但默认不关沙箱），Edge 不受影响 —— 也就是说"装了个 Chrome"
反而可能让插件彻底不可用。同时：端口改成跳过"已有别的 CDP 在听"的（避免附加到错误的浏览器），
每个浏览器各自一个 profile 目录（chrome-profile-chrome / -msedge / …）。
新增回归测试 tools/verify-launcher.mjs（10 条）。
-
v0.8.1：「我允许了目标站点，你却还在报未授权」 —— 用户浏览器档的判权用的是标签页当前 URL，
于是"允许了 github.com、前台却开着别的页"这种最常见用法必然被闸死。
现在 browser_open {use:"edge", url} / browser_navigate {url} 会把目标 URL 传进 Target.attachToTarget
的 intendedUrl，扩展在当前页未授权、目标页已授权时先导航、再附加（最多等 5s 落在已授权 origin）。
隐私底线不变：attach 永远在导航之后，agent 拿不到未授权页面的调试器。- v0.8.0：装扩展不再靠“看文档” —— 新增 browser_ext_setup，并把“桥没开”和“扩展没装”分开报。
- 背景：接管你的浏览器要三件事同时成立（桥开着 / 扩展装着 / token 粘对），而 v0.7.x 只把它们写成文字说明：
use:"edge" 在桥没开时也报“扩展还没连接”，把人引去装一个装了也连不上的扩展；
报错不给 extension/ 绝对路径、不说 token 在哪；面板在桥没开时显示空 token，步骤却照旧摆着。
- 新工具
browser_ext_setup：开桥（userBridge=true，即时生效）→ token 进剪贴板 →
打开目标浏览器的扩展页 → 资源管理器里打开本包 extension/ 目录，并把 5 步操作原样列出。
kind:'edge'|'chrome'（默认 settings.userDefault）， 只返回路径与 token、不动 UI。
许可与致谢
- 本插件源码：MIT © 2026 Raylen-berry（作者 / 维护者）。
- 灵感来源（原作者）：dsh-ego-browser，
MIT © Fisfzy and dsh-ego-browser contributors。其"把 agent 接进 DSH 的真浏览器 + 观察窗"
设计（含 ego-lite 运行时，© CitroLabs / ego-lite contributors，MIT）证明了这条路走得通。
- 本仓库是独立自研的干净实现（clean-room re-implementation）：不含 ego-browser / ego-lite 的任何一行代码，
不携带其运行时 vendored 源码，仅借鉴其功能思路与交互范式。商标与名称归各自所有者。
感谢 ego-browser 作者把"接进 DSH 的 agent 浏览器 + 观察窗"这条路趟通。
完整署名与上游声明见仓库根目录 NOTICE 文件。
