dsh-browser-bridge 1.6.2

统一维护 Chrome 扩展、本机 HTTP/WebSocket 服务和 MCP、DSH、CLI 入口。三个入口共用 lib/runtime.js，并从 tools.manifest.json 注册 27 个工具。

阅读顺序

• 首次使用：按本文启动服务、加载扩展，再运行下面的端到端示例。

• 理解控制流与安全边界：架构说明。

• 配置、升级或排查连接：运维说明；DSH 宿主另见 DSH 接入。

• 编排请求或维护适配器：协议说明、适配器维护，参数以 tools.manifest.json 为准。

• 查询版本变化：CHANGELOG。历史实施与验收记录从其中链接进入，不作为当前操作步骤。

Related MCP server: Browser MCP

目录与启动

dsh-browser-bridge/
  bridge/                 本地服务和独占控制管理（CommonJS）
  extension/              Chrome 加载的扩展目录
  lib/                    共享客户端与 DSH 原生入口（ESM）
  examples/               MCP、CLI 入口和 MCP 配置示例
  scripts/                语法检查、图标生成
  tests/                  行为、控制权、扩展和传输测试
  docs/                   接入、协议和运维说明
  tools.manifest.json     工具单一事实源
  package.json            全项目依赖与命令入口

以克隆目录为项目根目录。在 Chrome 的 chrome://extensions 启用开发者模式，选择“加载已解压的扩展程序”，加载项目的 extension 子目录。迁移路径时先移除旧扩展，避免两个扩展交替连接同一服务。

在项目根目录执行 npm start 可独立运行共享服务；MCP 默认也能按需自启。npm run cli -- status 查看状态，npm run check 和 npm test 执行检查。环境与故障处理见 运维说明。

已有依赖可直接复用，不必重复安装。新的 Git 克隆不包含 node_modules；新机器需准备 Node 22+，并在允许安装依赖后执行 npm ci。扩展不需要构建；Git 克隆后可直接加载 extension。

第一个端到端调用

先在项目根目录的一个终端运行 npm start，并加载扩展；在另一个 PowerShell 终端执行 node examples/cli.mjs status，确认 connected=true、versionsMatch=true。CLI 不会自动启动服务。

以下示例只创建和操作本地 /test 页，不读取或修改业务页面。每次运行生成独立任务身份，同一轮的所有命令复用它：

& {
    $agentId = [guid]::NewGuid().ToString()

    # 所有步骤复用同一身份；失败立即停止，不自动重放写操作。
    function Invoke-BridgeExample {
        param([string[]] $CliArguments)
        $output = & node examples/cli.mjs @CliArguments "--agentId=$agentId"
        if ($LASTEXITCODE -ne 0) { throw '调用失败：请检查错误和 requestId，停止后续步骤。' }
        ($output -join "`n") | ConvertFrom-Json
    }

    $tab = Invoke-BridgeExample -CliArguments @('open', 'http://127.0.0.1:8765/test')
    Invoke-BridgeExample -CliArguments @('wait', [string]$tab.id, '#box', '10000') | Out-Null
    Invoke-BridgeExample -CliArguments @('type', [string]$tab.id, '#box', 'hello bridge') | Out-Null
    Invoke-BridgeExample -CliArguments @('click', [string]$tab.id, '#btn') | Out-Null
    $result = Invoke-BridgeExample -CliArguments @('extract', [string]$tab.id, '#result')
    if ($result.items[0].text -ne 'clicked: hello bridge') { throw '测试页结果不符合预期，请保留页面核验。' }
    $result.items[0].text

    # 验证通过后，只关闭本轮创建的测试页；失败时保留现场。
    Invoke-BridgeExample -CliArguments @('close', [string]$tab.id) | Out-Null
}

预期输出 clicked: hello bridge。失败时不要重跑整段；若写请求为 unknown，先按原 requestId 查询结果并核验页面，见 协议说明。

当前版本与升级

• 适配器、bridge 和扩展版本均为 1.6.2；协议版本 3，能力标识包含 atomic-session-v1 与 native-dialog-v1。运行时仍会分别报告实际加载版本，磁盘版本不代替运行版本核验。

• 需要 Node 22+、Chrome 120+；继续使用现有依赖，不需要新增软件包。

• 当前默认读取预算、后台打开与定位要求见“工具”和“输出和恢复”；版本变化见 CHANGELOG。

• 修改磁盘源码不等于运行进程已升级。重启 bridge、重载扩展并重连 MCP 客户端；DSH 接入方式见 DSH 接入。

• 不具备所需能力的旧扩展/bridge 下，新适配器的 status/tabs 可诊断；对应能力的动作明确返回 UPGRADE_REQUIRED，避免以旧实现假装完成新行为。

MCP 配置

保留已有服务配置；将示例中的 C:/path/to/dsh-browser-bridge 替换为实际项目绝对路径。若宿主的 PATH 中没有 Node，将 command 改为 node.exe 的实际绝对路径：

[mcp_servers.dsh_browser_bridge]
command = 'node'
args = ["C:/path/to/dsh-browser-bridge/examples/mcp-server.mjs"]
startup_timeout_sec = 15.0

[mcp_servers.dsh_browser_bridge.env]
DSH_BRIDGE_AUTOSTART = "true"

默认自动使用同项目内的 bridge，无需配置 DSH_BROWSER_BRIDGE_DIR；该变量仅用于显式覆盖服务目录。JSON 配置见 examples/mcp.json，复制其中服务项并调整绝对路径，保留宿主其他配置。MCP 宿主应直接执行 node + examples/mcp-server.mjs，避免 npm 的日志混入 stdio 协议。

DSH_BRIDGE_URL 支持自定义本机端口；自启会使用此 URL 的端口。DSH_BRIDGE_TOKEN 同时用于健康检查和动作请求。401 或非桥接服务不会触发重复启动。客户端只管理自己启动的 bridge 进程，外部服务生命周期不受影响。

工具

原生空白弹窗

扩展清单声明 debugger 必需权限，由用户在 Chrome 加载/重新加载扩展时检查并确认权限变更；插件不会调用可选权限申请或自动接受授权。

权限获准后，在扩展弹出页点击“启用原生弹窗识别”。功能仍默认关闭，权限获准或重载本身不会自动启用；仅观测当前受控页面，Chrome 可能显示正在调试的提示条，不会自动确认 alert/confirm/prompt/beforeunload。若当前运行清单未更新或权限未获准，按钮禁用并提示重新加载，不再重复发起无效申请。

启用后，browser_dialog 和 browser_session_status 返回 dialog.known / blocked / active；空正文仍是实际弹窗，active.blank=true。已观测的弹窗会使 DOM 读取返回 NATIVE_DIALOG_OPEN，避免把旧结果误当新操作成功。处理弹窗需最新 dialogId 和明确的 accept，prompt 可传 promptText；关闭弹窗不代表原查询成功，不能重放 unknown 请求。

观测前已打开的弹窗没有可靠的打开事件补发保证。短时只读脚本探测未响应时只标记 known=false / blocked=true，返回 PAGE_SCRIPT_BLOCKED，提示用户人工核验，不伪造弹窗类型或空白正文。用户停止后，agent 不能调用恢复工具；用户可在浏览器原生弹窗或扩展弹出页手动处理。仍须等待实际旧脚本结束才能移交控制。

当前启用与故障处置见 运维说明，历史修订和验证记录见 CHANGELOG。

输出和恢复

• 正文默认 8000 字符，不默认传输 HTML；offset/nextOffset 支持续读。

• extract 的 max 为字段序列化总预算，默认 8000；默认最多 20 项，返回 totalCount、returnedCount、truncated、nextOffset。单项 textTruncated 可改用 browser_read 的精确 selector/offset 续读。

• MCP 截图返回原生 image 内容块；DSH/CLI 将截图保存为 PNG 并返回路径，不输出 Base64 文本。DSH_BRIDGE_ARTIFACT_DIR 可设置目录，默认系统临时目录下的 dsh-browser-bridge。

• type 返回状态与字符数，不回显长文本。命令成功只说明该动作的验证范围，不等于后端业务已完成；使用 wait/read 验证页面后置条件。

• batch 最多 20 步，在 bridge 写队列中连续执行，失败停止，无业务回滚。默认输出预算 16000 字符，过量步骤结果标记 omitted。

• 页面首次使用自动申请独占控制；适配器按任务身份缓存 session，绝不按共享进程或 tabId 继承其他任务的占用。

• requestId 用于查询/去重；unknown 不能自动重放。记录保留约 5 分钟、最多 1000 项，服务重启清空；查不到记录不代表未执行。

• browser_session_status 是返回时的已确认快照，canWrite=true 只表示该时刻控制权有效；实际动作仍会在队列和扩展派发前再次确认。browser_ensure_session 只恢复租约，不抢占其他任务、不绕过用户停止，也不重放 unknown 动作。

• 默认 open 使用 active=false。截图和 activate 会影响焦点；hover/key 为合成事件，不承诺浏览器默认动作。

• frameId/documentId、CSS 的 >>> open-shadow 穿透、text=/label=/placeholder=/role= 可用于明确定位。仅增加原生 JavaScript 弹窗的窄 CDP 能力；closed shadow、文件选择、其他系统对话框和通用 CDP 后端仍不在此版本范围。

验证

npm run check
npm test
npm run test:native-browser
npm run test:live-browser
npm run cli -- status
npm run cli -- tabs

普通测试启动随机本机端口的隔离 bridge 和模拟扩展，不修改用户标签页。native-browser 使用已安装 Chromium、原始 manifest 和隔离配置；live-browser 是显式发布验收，需没有其他受控任务并已手动启用原生观测。后者仅新建本地 /test 标签页和固定公开搜索，实际等待五分钟，结束关闭自身页面，报告与截图写入忽略的 .verify/。详见 docs/runbook.md 与 docs/bridge-api.md。

独占控制与手动终止

页面右上角显示“任务名 正在控制此页面”，附“停止控制”按钮；扩展图标徽标和弹窗也展示状态。无法注入的保护页面使用弹窗作为操作入口。刷新/跳转后恢复提示。控制提示不进入正文/元素读取结果。

同一标签页只允许一个任务；其他任务立即收到 TAB_OCCUPIED，既不排队也不自动接管。status/tabs 可查看占用情况；read/extract/wait/frames 与写操作一样要求任务归属。服务端和扩展端都检查控制会话。

• 租约与空闲保持时间均为 5 分钟，常驻适配器每 20 秒续租；无执行中命令且 300 秒无页面活动后回收。策略集中在 tools.manifest.json.controlPolicy；单纯心跳或续租不延长空闲保持上限。

• agent 崩溃或 CLI 进程退出后，没有续租则约 5 分钟回收；未结束的旧脚本仍等待扩展确认结束，不能因到期交给其他任务。CLI 连续命令通过相同任务标识恢复同一归属。

• 写队列最多 100 项，未执行的取消项可即时移除。续租在共享 runtime 内单轮不重叠，跨任务最多 4 组并发，避免积压连接请求。页面提示条每个 document 只保留一个未完成注入和最新状态，避免重复注入，也不阻塞控制确认。控制流见 架构说明。

• “停止控制”先在扩展本地撤销，再通知 bridge 取消未执行命令；离线也记录停止状态。旧任务不能自动重新占用，用户可在提示条/弹窗点“允许旧任务”恢复其申请资格。

• 已注入且未结束的脚本保留“停止中”，直至结束或确认旧 document 已被刷新替换；无法确认时不自动交给其他任务。停止不回滚已发生的点击、提交或网络副作用。

• 停止状态在 Chrome storage.session 中保存，跨扩展 worker 重启恢复。浏览器整体退出不会保留控制会话。

调用者身份

DSH 原生入口采用宿主 exec.agent 对象区分任务。MCP 使用宿主元数据 dsh/agentId；宿主未提供时，调用参数必须含稳定且唯一的 agentId（建议任务 UUID），可附 agentName。也可用环境变量 DSH_AGENT_ID，但只能用于确实由单一任务专用的 MCP 进程。不要把不同任务配置为同一个 id。

同一任务的每次调用保持相同 agentId，例如：{"tabId":123,"selector":"#query","agentId":"task-unique-uuid","agentName":"报表核验"}。

适配器生成归属凭据；进程级命名空间防止两个 MCP 进程的同名任务被合并。MCP 进程重启后身份凭据重建，旧占用通过 TTL/用户停止回收。CLI 多次启动需设置同一个 DSH_AGENT_ID 或传 --agentId；多个 CLI 任务必须使用不同 id。

这些机制用于合作式 agent 的冲突隔离，不是针对恶意本机进程的身份认证。直接 HTTP 调用也必须携带 X-DSH-Owner；重放旧 sessionId 不能绕过其他 owner。