代理浏览器电子
- 作者仓库星标 39,477
- 作者仓库 airi
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @moeru-ai · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Windows
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
APP_REMOTE_DEBUG=true APP_REMOTE_DEBUG_PORT=9250 pnpm dev:tamagotchi
# Agent Browser Electron
## Overview
Inspect Electron renderer windows reliably when `agent-browser` alone is not enough to tell which CDP target maps to which visible app window.
Prefer raw CDP target discovery over guessing from `tab list`, then use `agent-browser --cdp <port> tab` stable tab IDs to interact with the renderer target you want.
## Why Raw CDP Discovery
Use raw CDP target discovery because `agent-browser` is operating as a convenience layer on top of Chrome DevTools Protocol, and that layer can hide or flatten details that matter in Electron.
Raw `/json/list` is the source of truth for CDP target discovery because it exposes Chromium's target inventory without extra interpretation. It is not the same thing as Electron's `BrowserWindow.getAllWindows()`.
In Electron, that distinction matters because:
- multiple `BrowserWindow` instances can share the same URL
- some windows are created lazily and appear only after an app action
- a visible Electron window is inspectable only after its renderer/webContents exists and is exposed as a CDP target
- detached DevTools pages and workers add noise
- `agent-browser tab list` may show only a subset of targets or present them with reduced metadata
- session state inside `agent-browser` can keep you attached to a previous renderer unless you reset and verify
In practice, the higher-level `tab list` view is useful for quick browsing, but not reliable enough for window-to-target mapping when:
- two Electron windows both look like `http://localhost:5173/#/`
- the title is empty or collapsed
- a chat or settings window exists in CDP but is not obvious in the simplified tab output
Use `curl http://127.0.0.1:<port>/json/list` first whenever correct target selection matters. Treat `agent-browser` as the interaction client after target discovery, not as the only discovery source.
If `/json/list` does not contain a window that the user says exists, do not assume `agent-browser` hid it. First consider that the window may not have been created yet, may not have loaded a renderer route yet, or may not currently be exposed as a CDP target. Trigger the window from the app UI or Electron main-process action, then enumerate `/json/list` again.
## Workflow
1. Confirm the app exposes a CDP port.
The CDP port is project- and run-command-specific. Do not assume `9222`, `9250`, or any other value is universal. If an Electron process is running but no CDP port responds, tell the user to relaunch the app with the project's remote-debug environment variables or launch flags.
For AIRI stage-tamagotchi on POSIX shells:
```bash
APP_REMOTE_DEBUG=true APP_REMOTE_DEBUG_PORT=9250 pnpm dev:tamagotchi
```
For Windows PowerShell:
```powershell
$env:APP_REMOTE_DEBUG = "true"
$env:APP_REMOTE_DEBUG_PORT = "9250"
pnpm dev:tamagotchi
```
For Windows Git Bash:
```bash
APP_REMOTE_DEBUG=true APP_REMOTE_DEBUG_PORT=9250 pnpm dev:tamagotchi
```
Adjust the port to match what the user actually started. If the project uses a different mechanism, inspect its Electron launch code before giving command advice.
2. Ensure the Electron window exists.
If the app uses lazy window creation, `agent-browser` cannot inspect a window that has not been created yet. Open it from the app UI or trigger its Electron-side open handler first.
3. Inspect raw CDP targets instead of trusting `agent-browser --cdp <port> tab`.
```bash
curl -sS http://127.0.0.1:<port>/json/list
```
Read these fields:
- `title`
- `url`
- `type`
- `webSocketDebuggerUrl`
Use `/json/version` if you need to confirm the port is a Chromium/Electron CDP endpoint or need the browser-level debugger URL:
```bash
curl -sS http://127.0.0.1:<port>/json/version
```
4. Match the target to the Electron window.
Common patterns:
- Distinct route: chat may be `http://localhost:5173/#/chat` while the main window is `http://localhost:5173/#/`.
- Distinct title: Electron window titles may surface in the target list.
- Duplicate URLs: two windows may both report `http://localhost:5173/#/`; in that case use screenshots, snapshots, and Electron app knowledge to disambiguate.
- Hidden noise: worker targets and detached DevTools targets are not your app window.
5. List the targets through `agent-browser` and switch with stable tab IDs.
```bash
agent-browser --cdp <port> tab
agent-browser --cdp <port> tab t2
```
Do not use positional integers. If `agent-browser tab` prints `[t2]`, switch with `tab t2`.
6. Verify the target immediately.
```bash
agent-browser --cdp <port> get url
agent-browser --cdp <port> get title
agent-browser --cdp <port> snapshot -i
```
7. If stable tab switching is not enough, reset session state and reconnect.
```bash
agent-browser close --all
agent-browser connect <webSocketDebuggerUrl>
agent-browser get url
```
If needed:
```bash
agent-browser --cdp <port> screenshot /tmp/electron-target.png --annotate
agent-browser --cdp <port> console
agent-browser --cdp <port> errors
```
## Fast Triage
Use this order when the Electron app has multiple windows:
1. `curl /json/list`
2. Find the renderer page target with the route or title you expect
3. Ignore `worker` targets unless the task is specifically about workers
4. Ignore `DevTools` page targets unless debugging DevTools itself
5. `agent-browser --cdp <port> tab`
6. Switch with the stable tab ID, for example `agent-browser --cdp <port> tab t3`
7. `agent-browser --cdp <port> get url`
8. `agent-browser --cdp <port> snapshot -i`
9. If the expected route is missing, trigger the lazy window from the UI and repeat from step 1
## AIRI Example
In `apps/stage-tamagotchi`, some windows are lazy-created. The main window loads `/#/`; settings loads `/#/settings`; chat loads `/#/chat`; BeatSync loads `/beat-sync.html`.
The `9250` examples below assume the app was started by the person running it with:
```bash
APP_REMOTE_DEBUG=true APP_REMOTE_DEBUG_PORT=9250 pnpm dev:tamagotchi
```
That port is not intrinsic to AIRI or Electron. It depends on the current command and environment. Most stage-tamagotchi code lives under `apps/stage-tamagotchi`; inspect that app's Electron startup and window code when the port, routes, or remote-debug behavior differ.
Relevant files:
- `apps/stage-tamagotchi/src/main/windows/chat/index.ts`
- `apps/stage-tamagotchi/src/main/windows/main/index.ts`
- `apps/stage-tamagotchi/src/main/libs/electron/window-manager/reusable.ts`
- `apps/stage-tamagotchi/src/renderer/components/stage-islands/controls-island/index.vue`
That means:
- chat does not exist in CDP until something calls `chatWindow()`
- settings and chat can be opened from the main window controls
- once created, raw CDP target discovery will show page targets such as `http://localhost:5173/#/settings` and `http://localhost:5173/#/chat`
- the stable way to inspect a window is to enumerate raw CDP targets, map them to `agent-browser` stable tab IDs, switch, and verify with `get url`
Example:
```bash
curl -sS http://127.0.0.1:9250/json/list
agent-browser --cdp 9250 tab
agent-browser --cdp 9250 tab t4
agent-browser --cdp 9250 get url
agent-browser --cdp 9250 snapshot -i
```
If settings or chat is missing, start from the main window:
```bash
agent-browser --cdp 9250 tab t2
agent-browser --cdp 9250 snapshot -i
# Click the main window control that opens the panel or launcher.
# In AIRI this is the arrow-up control in the bottom-right controls island.
# Re-snapshot after every click because refs are stale after UI changes.
agent-browser --cdp 9250 click '[i-solar\:alt-arrow-up-line-duotone]'
agent-browser --cdp 9250 snapshot -i
```
Then open the desired entry from the expanded controls and enumerate again:
```bash
agent-browser --cdp 9250 click '[i-solar\:settings-minimalistic-outline]'
agent-browser --cdp 9250 click '[i-solar\:chat-line-line-duotone]'
curl -sS http://127.0.0.1:9250/json/list
agent-browser --cdp 9250 tab
```
If the controls island is visible but the accessibility refs or CSS icon click do not expand it, inspect the Vue component as a diagnostic fallback. AIRI currently nests tooltip trigger buttons around icon buttons, so a CDP click can report success while landing on the wrapper instead of the Vue `ControlButton` listener. This fallback is for automation/debugging only; do not use it as evidence that end-user clicking works.
```bash
agent-browser --cdp 9250 eval '(() => {
const icon = document.querySelector("[i-solar\\:alt-arrow-up-line-duotone]")
let controls = icon.__vueParentComponent
for (let i = 0; i < 10; i++) controls = controls.parent
controls.devtoolsRawSetupState.expanded.value = true
controls.proxy.$nextTick()
return controls.devtoolsRawSetupState.expanded.value
})()'
```
Expected verification for chat:
- `agent-browser --cdp 9250 get url` returns `http://localhost:5173/#/chat`
- the snapshot exposes chat UI controls such as the message textbox or send button
Expected verification for settings:
- `agent-browser --cdp 9250 get url` returns `http://localhost:5173/#/settings`
- the snapshot exposes settings navigation or configuration controls
## Failure Modes
- `agent-browser tab` omits or flattens the target you need: use raw `/json/list`.
- `/json/list` and browser-level target discovery both omit the window: the renderer target is not currently exposed. Trigger the window creation/loading path, then enumerate again.
- `connect <webSocketDebuggerUrl>` appears to succeed but later commands still point at another renderer: switch with `agent-browser --cdp <port> tab tN`, or run `agent-browser close --all`, reconnect, and verify with `get url`.
- multiple windows share the same URL: use the target title, annotated screenshots, and app code to correlate them.
- `eval` returns `{}` for object values: prefer `get url`, `get title`, `snapshot -i`, or primitive-only eval return values.
- no chat or settings target appears: the window may not have been created yet, or may exist as an Electron object without an inspectable renderer target.
章节与文件索引
按说明文件中的顺序排列。
概述
为什么选择原始 CDP 发现
工作流程
快速分诊
AIRI 示例
文件/命令 -> agent-browser · tab list · agent-browser --cdp <port> tab · /json/list · BrowserWindow.getAllWindows() · BrowserWindow · agent-browser tab list · http://localhost:5173/#/
内容校验值 -> dde993724533
当前原文的自动摘译,尚未人工审校。
概述
当仅使用
agent-browser不足以判断哪个 CDP 目标映射到哪个可见应用程序窗口时,可靠地检查 Electron 渲染器窗口。首选原始 CDP 目标发现,而不是从tab list猜测,然后使用agent-browser --cdp <port> tab稳定选项卡 ID 与所需的渲染器目标进行交互。为什么选择原始 CDP 发现
使用原始 CDP 目标发现,因为
agent-browser作为 Chrome DevTools 协议之上的便利层运行,并且该层可以隐藏或扁平化 Electron 中重要的细节。 Raw/json/list是 CDP 目标发现的真相来源,因为它无需额外解释即可公开 Chromium 的目标库存。它与 Electron 的BrowserWindow.getAllWindows()不是一回事。工作流程
确认应用程序公开 CDP 端口。 CDP 端口是特定于项目和运行命令的。不要假设
9222、9250或任何其他值是通用的。如果 Electron 进程正在运行但没有 CDP 端口响应,请告诉用户使用项目的远程调试环境变量或启动标志重新启动应用程序。对于 POSIX shell 上的 AIRI stage-tamagotchi: 对于 Windows PowerShell: 对于 Windows Git Bash:快速分诊
当 Electron 应用程序有多个窗口时,请使用此顺序:
curl /json/list使用您期望的路线或标题查找渲染器页面目标 忽略worker目标,除非任务专门与工作人员相关 忽略DevTools页面目标,除非调试 DevTools 本身AIRI 示例
在
apps/stage-tamagotchi中,一些窗口是延迟创建的。主窗口加载/#/;设置加载/#/settings;聊天加载/#/chat; BeatSync 加载/beat-sync.html。下面的9250示例假设应用程序是由运行它的人启动的: 该端口不是 AIRI 或 Electron 固有的。这取决于当前的命令和环境。大多数舞台电子蛋代码都位于apps/stage-tamagotchi下;当端口、路由或远程调试行为不同时,检查该应用程序的 Electron 启动和窗口代码。