Browser

设备侧是一个自带的 Chrome（browser 程序）：它既是 MCP 工具服务，也提供实时画面流。 UI 与 AI 共享同一个浏览器实例和同一个页面，人工与 AI 可以同时操作。

安装与构建

Desktop 与 CLI 发行包预装本包并附带预编译的 bin/browser：pod 启动时自动定版到 ~/.aic/packages/browser，开箱即有 browser 命令，无需安装与 Go 工具链；包随 pod 版本整体更新，不可 commands install/update/uninstall。

源码运行 pod（没有随包二进制的环境）才需要手动构建：

# 平台 exec 先允许写设备包目录（本机 owner 终端按本机权限执行）
grant fs <设备用户 home 的绝对路径>/.aic/packages/browser

cd ~/.aic/packages/browser/src
cp go.mod.example go.mod
go mod tidy
mkdir -p ../bin
go build -o ../bin/browser .

配置：命令定义级配置（统一面）

应用配置与沙箱策略是同一张表里的同一件事——「这条命令定义的运行配置」。 写面只有 commands config，按定义身份存储（与 alias 同名替换无关）：

# 应用配置（环境变量）：AI 可直接写
commands config browser AIC_BROWSER_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
commands config browser BROWSER_SECURE_ORIGINS="http://localhost:4000"

# 免沙箱：Chrome 自身沙箱在 pod 沙箱里起不来（ERR_ABORTED）。
# 这是提权项——平台会话需人工批准（未批准会被明确拒绝），本机 owner 直接执行不需要。
commands config browser --no-sandbox

# 查看 / 撤销
commands config browser
commands config browser --unset BROWSER_SECURE_ORIGINS
commands config browser --sandbox

包也会读 ~/.aic/browser/config.env（同名键值，仅在环境变量未设置时生效）—— 那是 owner 的可选便捷项，不是平台的配置面。

AIC Desktop 自带 Chrome：桌面版启动后端时会注入 AIC_BROWSER_PATH（随包 Chrome for Testing 的可执行文件路径，不是目录）。换浏览器用 commands config browser AIC_BROWSER_PATH=… 覆盖（命令定义级配置优先于继承环境）。 独立 CLI / Docker 不带浏览器，需自装 Chrome 并同样用 commands config 指定。

配置后：

grant cmd browser
browser
browser navigate --input - --json

设备侧程序

源码在 src/（Go，只入库源码；二进制与构建产物不入库）。程序两种形态：

• stdio（默认）：MCP 工具服务；同时在 BROWSER_STREAM_ADDR 指定的地址上开一个 TCP 流，供实时画面使用。
• --http <addr>：自带 HTTP MCP 服务（进程已在设备上、Pod 只做代理时用）。

工具面

MCP 工具（browser <tool> --input '{...}' --json，标量参数自动映射为同名 flag）：

页面级工具接受可选 target_id；UI 始终显式传递，避免并行操作抢改共享 session。 AI 可先 attach 选定当前页后省略。元素引用取自最近一次快照；先看 schema 再传参。

复杂参数走 stdin：

echo '{"url":"https://example.com/"}' | browser navigate --input - --json

实时画面

• 推帧：CDP Page.startScreencast，Chrome 合成器出帧即推；页面静止时不产帧（正常语义）。
• 背压：页面画完才回 ack，设备再 ack Chrome，Chrome 才推下一帧 → 端到端只有一帧在途， 缓冲不会堆积；页面慢就掉帧，不会拖垮链路。实测动画页面 60fps、每帧约 6KB。
• 帧格式：裸 JPEG 字节，私有协议 browser/stream-v2 全二进制 （[u8 kind][u32 payloadLen][u64 seq][payload]），链路上没有 base64、没有 JSON。
• 人工输入与画面共用同一条流：坐标是视口归一化值 [0,1]，支持鼠标、滚轮、键盘、中文输入。
• 没有人观看时设备停止 screencast（避免持续合成占满 CPU）。

配置面

BROWSER_STREAM_ADDR 由 pod 在启动时注入，包内 UI 的流名为 view，无需手工配置。

注意

1. 内网 http 站点若被 Chrome 自动升级到 https，将 origin 写入 BROWSER_SECURE_ORIGINS。
2. 浏览器服务通常需要 commands config browser --no-sandbox，否则 Chrome 自身沙箱无法初始化。
3. 服务调用与流权限统一为 grant cmd browser。
4. 预装包随 pod 版本更新（启动定版为内嵌内容）；不可 commands update/uninstall。
5. 视口比例固定为 BROWSER_WINDOW_SIZE；不做移动端模拟。
6. 不做远端剪贴板读取与本地文件拖放。
7. 同一个资料目录同一时刻只能有一个 Chrome 实例：不要拿 BROWSER_PROFILE 指向的目录 再手动开一个 Chrome（会被 SingletonLock 挡住，表现为 DevTools 端点一直等不到）。 想人工操作同一个浏览器，用 BROWSER_HEADLESS=0 让服务自己把窗口显示出来。
8. BROWSER_CDP_URL 接入自己的浏览器时，那个浏览器必须是你自己带 --remote-debugging-port=9222 启动的；Chrome 136+ 对默认资料目录直接忽略 调试开关，必须同时给一个非默认 --user-data-dir（官方安全策略，防被接管盗号）。 接入后 AI 能读到那些页面的内容并按你的登录态操作，只在你明确要这样时才配置。

画面链路的三个硬约束（2026-10-30 实测后定）

1. ack Chrome 绝不能在 CDP 读循环里同步发：CDP 响应只能由读循环读出来， 在读循环里等响应就是自锁（每帧卡满 5 秒超时，画面从 60fps 掉到 0.2fps）。 ackCastFrame 走后台 goroutine。
2. 每个订阅者只保最新一帧（队列深度 1，满了丢旧的）：慢订阅者不拖住链路， 画面宁可跳帧也不堆积。
3. 僵尸订阅者会被摘掉：一直给它帧、它却 30 秒不确认，就当它死了、关掉连接。 流的维护归 pod——链路断就关流；页面重新活跃时自己新建流。