diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cc4bb1c..3ffc93a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -81,30 +81,4 @@ jobs: windows: name: Windows client - runs-on: windows-latest - timeout-minutes: 20 - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 - with: - persist-credentials: false - - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 - with: - node-version: "24" - - run: rustup toolchain install stable --profile minimal --component rustfmt --component clippy - - run: rustup default stable - - run: npm install --ignore-scripts --no-audit --no-fund - - run: powershell -NoProfile -File tools/ci-windows.ps1 -Task check - - name: Diagnose Windows command startup on failure - if: failure() - run: powershell -NoProfile -File tools/ci-windows.ps1 -Task diagnose - - run: powershell -NoProfile -File tools/ci-windows.ps1 -Task windows:shell:check - - run: powershell -NoProfile -File tools/ci-windows.ps1 -Task package:windows - - run: powershell -NoProfile -File tools/ci-windows.ps1 -Task package:windows:check - - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 - with: - name: windows-client-unsigned - path: | - dist/releases/*windows-x64-unsigned.zip - dist/releases/*windows-x64-unsigned.zip.sha256 - if-no-files-found: error - retention-days: 30 + uses: ./.github/workflows/windows-client.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index f143617..f9ed1fa 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -95,8 +95,12 @@ jobs: retention-days: 14 linux-client: uses: ./.github/workflows/linux-client.yml + windows-client: + uses: ./.github/workflows/windows-client.yml + with: + artifact-name: release-Windows npm: - needs: [build, linux-client] + needs: [build, linux-client, windows-client] if: vars.NPM_PUBLISH_ENABLED == 'true' runs-on: ubuntu-latest timeout-minutes: 15 @@ -137,8 +141,8 @@ jobs: if [[ "$GITHUB_REF_NAME" == *-* ]]; then distribution=next; fi npm publish dist/releases/*.tgz --access public --provenance --tag "$distribution" github-release: - needs: [build, linux-client, npm] - if: always() && needs.build.result == 'success' && needs.linux-client.result == 'success' && (needs.npm.result == 'success' || needs.npm.result == 'skipped') + needs: [build, linux-client, windows-client, npm] + if: always() && needs.build.result == 'success' && needs.linux-client.result == 'success' && needs.windows-client.result == 'success' && (needs.npm.result == 'success' || needs.npm.result == 'skipped') runs-on: ubuntu-latest permissions: contents: write @@ -169,6 +173,14 @@ jobs: sha256sum --check --strict -- "${checksums[@]}" cp -- "${archives[@]}" "$GITHUB_WORKSPACE/release/" sha256sum -- "${archives[@]}" > "$GITHUB_WORKSPACE/release/SHA256SUMS" + - name: Verify Windows release assets + working-directory: release + shell: bash + run: | + set -euo pipefail + archive="aBridge-${GITHUB_REF_NAME#v}-windows-x64-unsigned.zip" + test -f "$archive" + sha256sum --check --strict -- "$archive.sha256" - name: Create GitHub release env: GH_TOKEN: ${{ github.token }} diff --git a/.github/workflows/windows-client.yml b/.github/workflows/windows-client.yml new file mode 100644 index 0000000..e852d19 --- /dev/null +++ b/.github/workflows/windows-client.yml @@ -0,0 +1,39 @@ +name: Windows client +on: + workflow_call: + inputs: + artifact-name: + type: string + default: windows-client-unsigned +permissions: + contents: read +jobs: + build: + name: Build and verify ZIP + runs-on: windows-latest + timeout-minutes: 20 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 + with: + persist-credentials: false + - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 + with: + node-version: "24" + - run: rustup toolchain install stable --profile minimal --component rustfmt --component clippy + - run: rustup default stable + - run: npm install --ignore-scripts --no-audit --no-fund + - run: powershell -NoProfile -File tools/ci-windows.ps1 -Task check + - name: Diagnose Windows command startup on failure + if: failure() + run: powershell -NoProfile -File tools/ci-windows.ps1 -Task diagnose + - run: powershell -NoProfile -File tools/ci-windows.ps1 -Task windows:shell:check + - run: powershell -NoProfile -File tools/ci-windows.ps1 -Task package:windows + - run: powershell -NoProfile -File tools/ci-windows.ps1 -Task package:windows:check + - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 + with: + name: ${{ inputs.artifact-name }} + path: | + dist/releases/*windows-x64-unsigned.zip + dist/releases/*windows-x64-unsigned.zip.sha256 + if-no-files-found: error + retention-days: 30 diff --git a/README.md b/README.md index f872405..c54f4f8 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [快速开始](#快速开始) · [选择客户端](#选择客户端) · [评测与验证](#评测与验证) · [Yuxi 集成](#与-yuxi-一起使用) · [开发与文档](#开发与文档) · [下载](https://github.com/xerrors/aBridge/releases/latest) -aBridge 由 Server 和按需安装的客户端组成。Server 提供统一的 MCP 入口和授权管理,客户端在对应设备或 Chrome Profile 上执行操作。你可以为每个 Agent 单独指定设备、能力和有效期。 +在自己的机器上运行 aBridge Server,再把要用的设备接进来。你可以为每个 Agent 单独指定设备、能力和有效期。 ## 选择客户端 @@ -20,7 +20,7 @@ aBridge 由 Server 和按需安装的客户端组成。Server 提供统一的 MC ![Agent 通过 MCP 连接 aBridge Server,macOS、Windows、Linux、Android 和浏览器客户端分别通过 WebSocket 连接 Server。](docs/assets/architecture.svg) -各客户端独立安装、授权并直接连接 Server。桌面和浏览器可以分别接入。一个 Chrome Profile 对应一个浏览器设备,扩展在该 Profile 内为任务创建独立标签页。 +Agent 通过 MCP 把请求交给 Server,Server 核对授权后再派发给客户端。桌面客户端和 Chrome 扩展可以各自接入。每个 Chrome Profile 都可以注册为一个浏览器设备,并为任务打开独立标签页。 ## 快速开始 @@ -83,7 +83,7 @@ console.log(process.env.ABRIDGE_PUBLIC_ORIGIN + "/#admin_token=" + encodeURIComp - **浏览器扩展**。在想授权的 Profile 中安装扩展并完成浏览器授权。[Chrome 应用商店](https://chromewebstore.google.com/detail/abridge-for-browser/jbkhngckehhhhkbgpjlifbbchhbeodjc) · [源码安装](docs/browser-profile-design.md) - **macOS App**。下载 macOS ZIP,经浏览器授权后在系统设置中开启所需权限。v0.4.23 的 ZIP 使用 ad hoc 签名。[发布产物](https://github.com/xerrors/aBridge/releases/tag/v0.4.23) · [安装与权限](docs/deployment.md#macos-app) -- **Windows 客户端预览**。从 GitHub Actions 获取未签名便携 ZIP,或在 Windows 上从源码构建。完整解压后启动 `aBridge.exe`,填写服务端网址并在浏览器中确认授权。[下载、安装与绑定](docs/windows-client.md) +- **Windows 客户端预览**。下载未签名便携 ZIP,完整解压后启动 `aBridge.exe`,填写服务端网址并在浏览器中确认授权。[下载、安装与绑定](docs/windows-client.md) - **Linux CLI**。下载对应架构的包,用管理台签发的 Device Token 绑定。[发布产物](https://github.com/xerrors/aBridge/releases/tag/v0.4.23) · [安装与绑定](apps/linux-client/README.md#安装与绑定) - **Android App**。下载签名 APK,用 Device Key 绑定,在 Android 设置开启无障碍,再回到 App 允许 Agent 操作。[发布产物](https://github.com/xerrors/aBridge/releases/tag/v0.4.23) · [安装与绑定](apps/android/README.md) @@ -118,16 +118,14 @@ codex ## 与 Yuxi 一起使用 -aBridge 可以与 [Yuxi](https://github.com/xerrors/Yuxi) 一起部署,复用 Yuxi 的账户体系;通过 Yuxi 的对外入口及容器内部网络集成,无需为 aBridge 单独开放公网端口。设备仍连接到部署中为 aBridge 配置的可达地址。 - -两种接入路径的区别: +aBridge 可以和 Yuxi 一起部署,使用 Yuxi 的账户和对外入口。服务之间通过容器网络通信,设备仍使用部署时为 aBridge 配置的地址。[Yuxi](https://github.com/xerrors/Yuxi) | 路径 | 账户登录 | MCP 调用认证 | | ------------- | ------------------ | ------------------------------------------ | | **独立使用** | 管理员创建本地账户 | 管理台生成的 Agent Key | | **Yuxi 集成** | OIDC 单点登录 | 显式启用平台委托后,由平台签发短期委托令牌 | -OIDC 登录本身不授予 MCP 调用权限,浏览器 ID Token 也不能直接作为 MCP 访问令牌。平台连接仍受用户设备授权、本机开关与系统权限限制。部署参数、回调地址及容器内认证请求配置见 [OIDC 登录与平台 MCP 委托](docs/deployment.md#可选-oidc-登录与平台-mcp-委托)。 +OIDC 用于登录管理台。通过 Yuxi 调用 MCP 时,还需要启用委托并由 Yuxi 签发短期令牌。平台连接可以使用哪些设备和能力,仍由用户授权、本机开关和系统权限决定。[OIDC 登录与平台 MCP 委托](docs/deployment.md#可选-oidc-登录与平台-mcp-委托) ## 评测与验证 @@ -150,9 +148,9 @@ OIDC 登录本身不授予 MCP 调用权限,浏览器 ID Token 也不能直接 -真实 **gpt-6.1-sol(medium)Agent** 通过 aBridge 完成公开 MiniWoB++ 任务:**12/12(100.0%)**。任务、种子和预算在跑分前冻结,无重试,全部结果保留。 +使用 **gpt-6.1-sol(medium)** 运行 MiniWoB++ 适配任务,共完成 **12/12(100.0%)**。任务、种子和预算在运行前确定,每例运行一次。 -同模型目录与评测器的基线 **5/12** → 修复后 **12/12**;模型、任务 prompt、seed 0/1 和预算不变。基线已包含真实浏览器启动修复;两侧均固定同一份现有模型元数据,避免目录刷新超时。另用额外 seed=2 验证:**6/6**,单独统计。标准审核剔除 **0** 例。 +主对照使用种子 0 和 1,基线完成 **5/12**,修复后完成 **12/12**。基线已包含浏览器启动修复。两侧使用相同的模型目录、评测器、任务提示和预算。额外种子 2 单独运行,完成 **6/6**。审核排除 **0** 例。 ![浏览器工具优化前后对照](docs/benchmarks/miniwob-v2-comparison.svg) @@ -165,17 +163,17 @@ OIDC 登录本身不授予 MCP 调用权限,浏览器 ID Token 也不能直接 | `click-menu-2` | 2/2 | 2/2 | 60.1 | 8 | 321924 / 812 | 2/2 | | `multi-layouts` | 1/2 | 2/2 | 66.0 | 10 | 361814 / 820 | 2/2 | -每例限 180 秒 / 40 次工具调用,并发 2;仅开放观察、读取、操作、等待,支持 DOM 与截图,不开放 JS 执行、源码直接读取或判分接口。P50 包含 CLI 启动和模型调用,已启动的失败也计时。表中 token 为已知样本合计(输入含缓存),超时未返回用量视为未知,不能按 0 计费;CLI 不提供实际美元账单。 +每例限 180 秒和 40 次工具调用,并发 2。Agent 可以通过 DOM 和截图观察页面,也可以读取、操作和等待。P50 从 CLI 启动开始计时,包含模型调用及已启动的失败任务。表中的 token 是已报告样本的合计,输入包含缓存。缺少用量的样本记为未知。 -失败分类:无。用量覆盖 12/12;会话清理 12/12。 +失败分类:无。用量覆盖 12/12,会话清理 12/12。 -模型元数据通过CLI本地目录参数固定,未改全局配置、模型或任务prompt;这不消除网络和模型响应波动。失败全部保留,不能仅凭小样本宣称稳定速度或成本优势。 +两侧都通过 CLI 参数加载同一份从缓存逐字复制的模型目录,以避开目录刷新超时。实际耗时仍会随模型服务和网络变化。 -模型目录 SHA-256:578e4bab76fbd3999747b7d3c8c34b83a4cdbef4a3bd033f21f0399e094f1c3d;逐字复制实际缓存的元数据,不修改模型指令或能力。 +模型目录的 SHA-256 为 `578e4bab76fbd3999747b7d3c8c34b83a4cdbef4a3bd033f21f0399e094f1c3d`。 -测量快照:v0.4.16 / c02c42b。环境:Apple M4 / darwin arm64 / Chrome/153.0.8010.12 / Node v22.23.5 / codex-cli 0.166.0;记录时间 2026-11-18T02:07:05.629Z。 +测量版本为 v0.4.16(c02c42b)。环境为 Apple M4 / darwin arm64 / Chrome/153.0.8010.12 / Node v22.23.5 / codex-cli 0.166.0,记录于 2026-11-18T02:07:05.629Z。 -这是 **6 类任务、每类 2 个种子的小样本适配子集**,原始任务限时统一延长至 180 秒,不是官方榜单成绩;单次前后对照仍有模型随机性,也不能单独证明 aBridge 优于其他工具或覆盖 macOS App。固定策略的 30/30 仅作为执行链冒烟历史数据,与 Agent 分数分开。[方法与限制](docs/benchmarks/miniwob.md) · [工具修复报告](docs/benchmarks/browser-reliability-v2.md) · [全量报告](docs/benchmarks/cases-all.md) · [标准审核报告](docs/benchmarks/cases-conforming.md) · [逐次实测数据](docs/benchmarks/miniwob-v2-results.json)。 +结果对应 Chrome 扩展上的 6 类适配任务,每类 2 个种子,采用这里列出的时间预算。早期固定策略的 30/30 见执行链冒烟记录。[评测方法](docs/benchmarks/miniwob.md) · [工具修复报告](docs/benchmarks/browser-reliability-v2.md) · [全量报告](docs/benchmarks/cases-all.md) · [标准审核报告](docs/benchmarks/cases-conforming.md) · [逐次实测数据](docs/benchmarks/miniwob-v2-results.json) ```sh npm run benchmark:miniwob @@ -191,10 +189,10 @@ npm run benchmark:miniwob ## 授权与安全边界 -- **设备与能力显式授权**:每个 Agent 连接可选择设备、能力和有效期;设备本机可以暂停或关闭能力,自动重连不会解除这些限制。 -- **凭据各司其职**:Admin Token 用于实例管理,Device Key 用于设备连接,Agent Key 用于 MCP 调用,三者不能互换。 -- **沿用用户的执行环境**:浏览器脚本具有当前站点登录用户的页面权限;Shell 与文件工具在已授权设备上执行。请按任务分配所需能力。 -- **未知操作不盲目重放**:断连或超时可能发生在副作用之后;应查询原操作状态、重新观察,再决定下一步。撤销权限不能回滚已执行的操作。 +- 在管理台为每个 Agent 选择设备、能力和有效期。设备本机可以随时暂停访问或关闭能力,这些设置会在重连后继续生效。 +- 用 Admin Token 管理实例,用 Device Key 连接设备,用 Agent Key 调用 MCP。 +- 浏览器任务沿用该 Profile 的网站登录状态,页面脚本拥有当前用户的页面权限。Shell 和文件工具使用客户端所在账户的系统权限。 +- 操作途中断连或超时时,先查询原操作状态,再检查页面或文件是否已经改变。撤销权限会阻止后续操作,已发生的修改需要另行处理。 ## 开发与文档 diff --git a/apps/android/README.md b/apps/android/README.md index 6732863..c952113 100644 --- a/apps/android/README.md +++ b/apps/android/README.md @@ -1,6 +1,14 @@ # aBridge for Android -Development preview for Android 11 and newer. Use a Server built from this branch or a later build that includes the Android device time handshake. The app registers as an independent computer device and connects directly to the server. Use a computer Device Key whose grant includes the capabilities you intend to enable. +The Android app supports Android 11 and later. Install the signed APK from GitHub Releases and use a Server version that supports Android devices. [GitHub Releases](https://github.com/xerrors/aBridge/releases/latest) + +In the management console, create an Android device and copy its Device Key. Open the app, enter the Server address and key, then enable the aBridge accessibility service in Android Settings. Choose the capabilities and working directory in **设置**, then tap **允许 Agent 操作**. Use **暂停 Agent 操作** to pause access while keeping the device connected. + +Use HTTPS for remote connections. If you enter an HTTP address, the app asks you to confirm it because the key and device traffic will travel without encryption. The confirmation applies to the saved address, and a device bound over HTTPS keeps using HTTPS. + +To update the signed app, go to **设置 → 检查更新**. Open the downloaded APK and follow the Android installer. [Android release process](../../docs/releasing.md#android) + +## Build for development ```sh npm run build @@ -12,11 +20,9 @@ The Android build requires JDK 17 and Android SDK Platform 36. Gradle consumes t The [Android App workflow](../../.github/workflows/android.yml) builds Debug and Release APKs and runs Android Lint on pull requests and pushes to `main`. Download the installable Debug APK from the run's **abridge-android-debug** artifact. -For normal use, install the signed Android APK from a GitHub Release when available. **设置 → 检查更新** checks the current version against the latest stable release and opens the official APK download. Open the downloaded APK to confirm the update in Android's installer. See the [Android release process](../../docs/releasing.md#android). - Debug and Release APKs use R8 to remove unused code and compress the remaining DEX bytecode. Release packaging recompresses the APK before signing and checks the complete signed file against a 200,000-byte budget. Android extracts the bytecode during installation, so the APK size and installed storage usage differ. -Open the app, enter the server address and Device Key, and enable the aBridge accessibility service in Android Settings. HTTPS is recommended. Binding over HTTP requires explicit confirmation because the key and subsequent device traffic are unencrypted. This confirmation is tied to the saved address, and an HTTPS connection never falls back to HTTP. Configure capabilities and choose a working directory in **设置**. Select **允许 Agent 操作** to accept authorized requests or **暂停 Agent 操作** to close access. The device can stay connected in either mode, and local access changes take effect before the Server receives the update. +## Tools | Capability | Supported requests | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/apps/linux-client/README.md b/apps/linux-client/README.md index 69710b7..128117a 100644 --- a/apps/linux-client/README.md +++ b/apps/linux-client/README.md @@ -1,6 +1,6 @@ # aBridge Linux CLI -原生 Rust 客户端,提供 `shell` 和 `files`,直接连接 aBridge Server。运行时不需要 Node、npm、浏览器或图形环境。Shell 和文件访问使用运行客户端的普通用户权限;它们不是隔离沙箱。不提供 `screen`、`input` 或 `browser`。 +用 Linux CLI 将开发机或服务器接入 aBridge,供 Agent 执行 Shell 和文件任务。客户端可以在无图形环境的机器上运行。Shell 和文件操作使用启动客户端的账户权限。 ## 安装与绑定 @@ -40,7 +40,7 @@ systemctl --user restart abridge-client.service 暂停和能力开关持久化;自动重连或服务重启不会恢复被暂停的访问。`stop` 停止当前操作,`systemctl --user stop abridge-client.service` 停止后台客户端。断线后建立新会话,结果未知的操作不会自动重放。 -服务执行环境不等同于交互式登录 Shell,不自动加载 `.bashrc`、`.zshrc` 或激活虚拟环境。命令应明确工作目录,工具可使用绝对路径或显式传入 `env.PATH`。 +后台服务从 systemd 继承环境。需要特定工作目录、可执行文件或虚拟环境时,请用绝对路径,或在请求中显式设置 `cwd` 和 `env.PATH`。 默认状态目录是 `$XDG_DATA_HOME/abridge/linux-client` 或 `~/.local/share/abridge/linux-client`,绑定文件权限为 `0600`、目录为 `0700`。`--state-dir /absolute/path` 可用于独立实例的配置与前台运行。实际路径加上 `/control.sock` 须符合本机 Unix socket 路径长度限制,绑定时会校验。用户级服务固定为一个 `abridge-client.service`,再次安装时使用指定状态目录。卸载服务: @@ -48,7 +48,7 @@ systemctl --user restart abridge-client.service ~/.local/lib/abridge-client/abridge-client service uninstall ``` -卸载不删除绑定与操作去重记录。更新前停止当前任务,用新版二进制执行 `service install`,继续使用相同状态目录。Linux 第一版通过手动安装更新,不在后台下载或替换自身。 +卸载服务会保留绑定和操作去重记录。手动更新时先停止当前任务,再用新版二进制执行 `service install`,沿用原状态目录。 ## 从源码构建 diff --git a/apps/server/README.md b/apps/server/README.md index 76d9f4c..0251ae5 100644 --- a/apps/server/README.md +++ b/apps/server/README.md @@ -1,14 +1,14 @@ # aBridge Server -MCP 与设备连接网关,包含预构建的管理台。需要 Node.js 22.13.0+ 与 npm;运行时不需要编译 TypeScript 或启动前端开发服务器。 +Server 提供 MCP 入口和设备连接,管理台随包提供。直接运行需要 npm 和 Node.js 22.13.0+(22.x)、23.4.0+(23.x)或 24 及以上版本。 -公开 npm 包名为 `@xerrors/abridge`。发布完成后可使用 `npx @xerrors/abridge --web`;本地分发候选使用实际生成的 tarball 路径运行: +从 GitHub Releases 下载 Server tarball,再将实际路径传给 npm。[下载发布包](https://github.com/xerrors/aBridge/releases/latest) ```sh npm exec --package /absolute/path/to/server.tgz -- abridge --web ``` -安装到自己的 npm 环境后,入口命令为 `abridge`。下文以该入口展示;通过本地 tarball 运行时,沿用开头的 `npm exec --package … --` 前缀。此包只包含 Server,不含桌面运行时或 Cua SDK,不提供 `client` 子命令。App 和浏览器扩展独立安装。 +安装到 npm 环境后,直接使用 `abridge`。从本地 tarball 运行下面的命令时,在命令前加 `npm exec --package … --`。电脑客户端和浏览器扩展各自在设备上安装。 ## 首次配置 @@ -20,7 +20,7 @@ Token 保存在数据库旁的 `<数据库文件>.admin-token`(权限 `600`) ## 管理员 API -外部程序使用 `Authorization: Bearer `,管理台使用独立的管理员 Cookie。普通账户、Device Key 和 Agent Key 均不能调用这些接口。管理员身份只授予全局统计与创建用户权限,不代替普通账户或设备授权。 +管理员 API 用于创建普通账户和查看全局统计。外部程序使用 `Authorization: Bearer `,管理台使用管理员 Cookie。绑定设备和分配 Agent 权限在普通账户下完成。 | 方法 | 路径 | 作用 | | -------- | --------------------- | ---------------------------------------------------- | @@ -87,7 +87,7 @@ Origin 必须是纯 `scheme://host[:port]`,没有路径、查询、fragment } ``` -Device Key 用于设备连接,Agent Key 用于 MCP 调用,两者不能互换。电脑与浏览器是独立设备,扩展只提供 `browser`;桌面 App 提供屏幕、键鼠、Shell 与文件。任务按设备 ID 建立会话,完成后关闭会话;暂停只能由本机操作者恢复。 +设备使用 Device Key 连接,Agent 使用 Agent Key 调用 MCP。电脑和浏览器分别注册,工具随客户端和授权范围而定。按设备 ID 开启任务会话,完成后关闭。访问已暂停时,请在设备本机恢复。 ## 设备信息 diff --git a/apps/web/src/features/devices/list.tsx b/apps/web/src/features/devices/list.tsx index c9d70d6..ba323d5 100644 --- a/apps/web/src/features/devices/list.tsx +++ b/apps/web/src/features/devices/list.tsx @@ -148,7 +148,7 @@ export function DevicesPage({ diff --git a/apps/web/src/features/devices/setup.tsx b/apps/web/src/features/devices/setup.tsx index fc08e15..3c04abe 100644 --- a/apps/web/src/features/devices/setup.tsx +++ b/apps/web/src/features/devices/setup.tsx @@ -15,7 +15,7 @@ const platforms = ["macos", "windows", "linux", "android", "browser"] as const; type Platform = (typeof platforms)[number]; const release = "https://github.com/xerrors/aBridge/releases/latest"; const clients: Record< - Exclude, + Platform, { kind: DeviceKind; requirements: string; @@ -35,6 +35,19 @@ const clients: Record< tokenInstructions: "在 macOS 客户端设置的「绑定方式」中选择 Device Token,填入服务地址和凭证,再点击「验证并连接」。", }, + windows: { + kind: "computer", + requirements: "Windows 10/11 x64,未签名便携 ZIP", + download: { + href: "https://xerrors.github.io/aBridge/windows-client.html#下载与安装", + label: "查看 Windows 下载与安装", + }, + capabilities: ["screen", "input", "shell", "files"], + browserAuthorization: + "完整解压后启动 aBridge.exe,在「连接」中填写服务端网址,点击「连接并授权」,并在浏览器中确认。", + tokenInstructions: + "在 Windows 客户端填写服务端网址,展开「使用 Device Token」并粘贴凭证,再点击「连接并授权」。", + }, linux: { kind: "computer", requirements: "Linux CLI,amd64 / arm64", @@ -88,8 +101,8 @@ export function DeviceSetupPage({ initialPlatform?: string; }) { const platform = platforms.find((value) => value === initialPlatform) ?? "macos"; - const client = platform === "windows" ? undefined : clients[platform]; - const [method, setMethod] = useState(client?.browserAuthorization ? "browser" : "token"); + const client = clients[platform]; + const [method, setMethod] = useState(client.browserAuthorization ? "browser" : "token"); const [saved, setSaved] = useState(false); const [submitting, setSubmitting] = useState(false); const [credential, setCredential] = useState<{ id: string; key: string }>(); @@ -145,187 +158,175 @@ export function DeviceSetupPage({ ))} - {client ? ( -
    -
  1. -
    -
    -
    -

    安装客户端

    -

    {client.requirements}

    - {client.installGuide && ( - - 安装与校验说明 - - )} -
    - - {client.download.label} - +
      +
    1. +
      +
      +
      +

      安装客户端

      +

      {client.requirements}

      + {client.installGuide && ( + + 安装与校验说明 + + )}
      + + {client.download.label} +
      -
    2. -
    3. -
      -

      绑定设备

      - {client.browserAuthorization && ( -
      - - -
      +
      +
    4. +
    5. +
      +

      绑定设备

      + {client.browserAuthorization && ( +
      + + +
      + )} +
      + {androidNeedsAddress ? ( + <> + 服务地址 +

      Android 真机请填写设备能访问的 HTTPS 服务地址。

      + + ) : ( + <> + +
      + + + 复制地址 + +
      + )} -
      - {androidNeedsAddress ? ( - <> - 服务地址 -

      Android 真机请填写设备能访问的 HTTPS 服务地址。

      - - ) : ( +
      + {method === "browser" ? ( +
      +

      {client.browserAuthorization}

      + + 授权后到设备列表确认上线 +
      + ) : ( +
      +

      设备凭证

      +

      {client.tokenInstructions}

      + {credential ? ( <> - -
      - - - 复制地址 - + {!revoked && ( + <> +

      凭证仅在这里显示一次。请复制到客户端。

      +
      + + + 复制设备凭证 + +
      + + + )} +
      +

      +

      + {device?.status === "online" ? ( + + ) : revoked ? ( + + ) : ( + + )}
      + ) : ( +
      { + setSubmitting(true); + try { + const result = await api( + "/api/devices", + z.object({ id: z.string(), key: z.string() }), + { + name: form.get("name"), + kind: client.kind, + capabilities: client.capabilities, + }, + ); + setCredential(result); + } finally { + setSubmitting(false); + } + void refresh().catch(() => notify("设备凭证已生成,暂时无法刷新连接状态。")); + }} + > + +

      + 设备能力: + {client.capabilities + .map((value) => + platform === "android" && value === "input" ? "触摸输入" : capabilityLabels[value], + ) + .join("、")} +

      + )} -
      - {method === "browser" ? ( -
      -

      {client.browserAuthorization}

      - - 授权后到设备列表确认上线 -
      - ) : ( -
      -

      设备凭证

      -

      {client.tokenInstructions}

      - {credential ? ( - <> - {!revoked && ( - <> -

      凭证仅在这里显示一次。请复制到客户端。

      -
      - - - 复制设备凭证 - -
      - - - )} -
      -

      -

      - {device?.status === "online" ? ( - - ) : revoked ? ( - - ) : ( - - )} -
      - - ) : ( -
      { - setSubmitting(true); - try { - const result = await api( - "/api/devices", - z.object({ id: z.string(), key: z.string() }), - { - name: form.get("name"), - kind: client.kind, - capabilities: client.capabilities, - }, - ); - setCredential(result); - } finally { - setSubmitting(false); - } - void refresh().catch(() => notify("设备凭证已生成,暂时无法刷新连接状态。")); - }} - > - -

      - 设备能力: - {client.capabilities - .map((value) => - platform === "android" && value === "input" - ? "触摸输入" - : capabilityLabels[value], - ) - .join("、")} -

      - - )} -
      - )} -
      -
    6. -
    - ) : ( -
    -

    Windows 原生客户端尚未发布

    -

    你可以通过 Chrome 扩展接入 Windows 上的浏览器。

    - - 添加浏览器扩展 -
    - )} + + )} +
    +
  2. +
); } diff --git a/apps/web/src/features/devices/styles.css b/apps/web/src/features/devices/styles.css index a2c7d6d..e380916 100644 --- a/apps/web/src/features/devices/styles.css +++ b/apps/web/src/features/devices/styles.css @@ -208,8 +208,7 @@ flex: 1; min-width: 0; } -.setup-journey h2, -.setup-unavailable h2 { +.setup-journey h2 { font-size: 15px; font-weight: 600; letter-spacing: 0; @@ -296,12 +295,6 @@ font-size: 12px; color: var(--muted); } -.setup-unavailable { - display: grid; - justify-items: start; - gap: 10px; - padding: 24px 0; -} .access-row .cap { padding: 0; background: transparent; diff --git a/apps/windows/tests/desktop.test.ts b/apps/windows/tests/desktop.test.ts index 5d65c52..102c290 100644 --- a/apps/windows/tests/desktop.test.ts +++ b/apps/windows/tests/desktop.test.ts @@ -291,6 +291,8 @@ test("Shell captures unicode output directly, strips unrequested env and bounds const executor = new LocalExecutor(new Native()); process.env.ABRIDGE_PRIVATE_FIXTURE = "must-not-inherit"; const result = await executor.commandExecute("shell", { + // Cold PowerShell compilation on hosted Windows runners can consume the default deadline. + timeout: 75, command: process.platform === "win32" ? "[Console]::Write('😀 中文'); [Console]::Error.Write('error'); if (-not $env:ABRIDGE_PRIVATE_FIXTURE) { [Console]::Write('unset') }" diff --git a/docs/architecture.md b/docs/architecture.md index 8c94908..c3c05d0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -53,11 +53,15 @@ MCP 客户端 ─ Agent Key ─ /mcp ──────────┐ 源码中的领域名统一为 `AgentConnection`(Agent 的持久授权连接)、`DeviceConnection`(设备当前传输连接)、`ControlSession`(控制会话)和 `Operation`(一次操作)。管理接口使用 `/api/agent-connections`,列表字段为 `connections`,操作及会话通过 `agent_connection_id` 引用授权连接;设备派发中的 `device_credential_version` 表示 Device Key 版本,不表示 Agent 连接策略版本。`operation_status` 与 `operation_cancel` 面向所有操作,包括 Shell 和浏览器代码。 -工具参数由协议包的 `toolArgumentSchemas` 定义,`DeviceToolRequest` 关联工具名与参数类型。MCP 使用同一字段定义,Server 和执行端在各自输入边界解析;默认值、范围及跨字段约束保持单源。执行时仍独立核对授权、取消、连接代次、观察引用和当前目标。管理 API 的公共视图及输入契约位于 `packages/protocol/src/management.ts`,Server 构造与 Web 解析共用类型;数据库实体及本地界面状态不是公共视图。 +协议包中的 `toolArgumentSchemas` 定义工具参数,`DeviceToolRequest` 把工具名和参数类型对应起来。MCP、Server 和执行端各自在入口按同一契约解析,执行时再核对授权、取消、连接代次、观察引用和目标。 -共享线协议版本为 `abridge/1`。进程边界使用运行时 schema 校验,TypeScript 包使用严格类型与未使用声明检查,原生运行时使用 Swift 6 严格并发检查;类型声明不替代不可信消息的解析。软件版本只从根 `package.json` 读取,扩展 manifest 和分发版本在构建时生成。原生客户端使用协议包生成的 `desktop-contract.json` 校验消息、参数与默认值;跨字段约束由共享可移植规则表达,回归测试对照 Zod 和 Swift 的接受结果与规范化值。 +管理 API 与管理台共用 `packages/protocol/src/management.ts` 中的输入与响应类型,数据库实体和界面状态由各自模块维护。 -Server 使用 Fastify 5 和官方 MCP TypeScript SDK v2。MCP HTTP transport 状态按请求隔离,设备操作会话由 `ControlService` 管理,二者不是同一个生命周期。管理台是预构建 Preact 11 静态产物,正常运行不启动前端开发服务器。 +设备通信使用 `abridge/1`。进程边界通过运行时 schema 校验消息。TypeScript 使用严格类型检查,Swift 6 使用严格并发检查。原生客户端读取协议包生成的 `desktop-contract.json`,按共享规则处理消息、参数、默认值和跨字段约束。回归测试对照 Zod 和 Swift 的接受结果与规范化值。 + +根 `package.json` 提供软件版本,扩展 manifest 和分发包在构建时读取它。 + +Server 使用 Fastify 5 和官方 MCP TypeScript SDK v2。MCP HTTP transport 按请求维护状态,设备操作会话由 `ControlService` 持续管理。管理台是随 Server 提供的预构建 Preact 11 静态页面。 管理台源码按职责收拢在 `apps/web/src/`:`app/` 负责入口、导航、工作区布局与跨功能弹窗编排,`components/` 提供公共控件,`features/` 按 auth、overview、devices、connections、activity、admin 放置页面及相关逻辑,`lib/` 放置请求、公共类型与展示标签。页面不作为其他模块的公共类型出口;连接权限计算集中在 connections 的 policy 模块。表单与弹窗共享提交状态,保留在同一组件文件中。 @@ -67,13 +71,15 @@ Server 使用 Fastify 5 和官方 MCP TypeScript SDK v2。MCP HTTP transport 状 ## Linux CLI 客户端 -`apps/linux-client/` 使用 Rust 实现独立的 `abridge-client`,仅提供 `shell` 和 `files`,以 `computer` / `linux` 身份直接连接 `/ws/device`。它不依赖 Node、图形环境或桌面 SDK。CLI 和后台服务使用同一个二进制,后台生命周期由用户级 systemd 管理;非 systemd 环境可以使用前台 `run`。 +`apps/linux-client/` 提供 Rust 可执行文件 `abridge-client`。它在无图形环境中也能运行,以 `computer` / `linux` 身份连接 `/ws/device`,提供 `shell` 和 `files`。同一个二进制可以在用户级 systemd 中运行,也可以用 `run` 在前台运行。 `main.rs` 负责命令解析和 Device Token 绑定,`runtime.rs` 是连接代次、操作调度及本机策略的唯一所有者,`executor.rs` 执行 Shell/文件,`storage.rs` 维护私有绑定与操作日志,`service.rs` 管理用户服务。运行时先取得独占锁再读取绑定,配置与凭据作为同一份 0600 文件原子提交;本机控制通过同用户私有 Socket 进行。新绑定须先验证 Server 的设备身份,并要求停止原运行时。 Linux 构建消费 `@abridge/protocol/desktop-contract` 导出的能力、常量、JSON Schema 和 portable 约束;版本也由该契约从根 `package.json` 生成。Rust 解释器应用共享默认值、字段范围、未知字段策略和跨字段约束,对不支持的新规则拒绝启动并使契约检查失败。跨语言测试对照 Zod 的解析结果,避免独立维护第二套参数规则。 -执行前同步保存并刷盘操作 ID、请求哈希和执行意图,完成后保存终态;不记录命令、文件正文、输出或凭据。重启时执行中的记录转为结果未知,日志压缩保留所有操作身份而不自动过期。终态落盘失败仍报告已确认的执行回执,并阻止新操作直到修复存储并重启。暂停、能力关闭和撤销先停止接收相关操作并发出取消,再等待进程清理;连接代次隔离迟到输出,重连不恢复旧会话或解除暂停。Shell 采用独立进程组,结束、超时和取消时清理组内进程;文件权限及 UTF-8 行为与现有协议一致。该客户端不提供隔离沙箱。 +设备在执行前把操作 ID、请求哈希和执行意图同步写入日志,完成后保存终态。日志只记录这些操作元信息,压缩时仍保留历史操作身份。重启时,执行中的记录变为结果未知。若终态落盘失败,设备会保留已确认的执行回执,并停止接收新操作,直到修复存储并重启。 + +暂停、关闭能力或撤销时,客户端先停止接收相关操作,取消在途任务,再等待进程退出。重连沿用暂停状态并开启新的连接代次。Shell 在独立进程组中执行,结束、超时或取消时清理组内进程。Shell 和 UTF-8 文件操作使用客户端所在账户的权限。 `npm run linux:check` 执行 Rust 格式、测试、Clippy 及真实 Server 联调,Linux CI 另验收用户 systemd 安装/停止/重启/卸载。`npm run package:linux` 仅打包 Linux ELF,生成校验和、第三方许可及体积记录;可执行文件和压缩包预算分别为 15 MiB、5 MiB。安装、能力控制和后台运行见[部署说明](deployment.md#linux-cli)。 @@ -100,19 +106,21 @@ Linux 构建消费 `@abridge/protocol/desktop-contract` 导出的能力、常量 ## Windows 客户端 -Windows PC 客户端位于 `apps/windows/windows-native-shell/`,Rust 原生运行时直接连接 Server,Win32 实现设置、托盘与活动边框。同一个 `aBridge.exe` 通过 `--native-host` 启动独立运行时,私有 stdio 保留窗口命令和事件契约。`runtime/` 管理授权、会话、SQLite 去重、操作调度、Shell 和文件;嵌入的 PowerShell/UIA 驱动检查本机权限、焦点、遮挡和人工输入。`apps/windows/src/` 保留此前 TypeScript 行为参考及驱动源,不作为运行依赖分发。 +Windows 客户端位于 `apps/windows/windows-native-shell/`。Win32 外壳负责窗口和本机控制,从同一个 `aBridge.exe` 启动 `--native-host` 运行时,通过私有 stdio 传递命令及事件。运行时直接连接 Server,处理授权、会话、SQLite 去重、操作调度、Shell 和文件。内嵌 PowerShell/UIA 驱动在输入前核对本机权限、焦点、遮挡和人工输入。旧 TypeScript 实现及驱动源保存在 `apps/windows/src/`,供对照测试。 Windows 壳消息和平台动作契约维护在 `packages/protocol/src/windows-shell.ts`、`windows-computer.ts`;平台动作仅接受 foreground 模式,保留现有服务端的公共工具 schema。[Windows 安装与验证](windows-client.md)。 -外壳仅负责设置窗口、托盘、暂停快捷键、桌面活动边框和子进程生命周期;运行时保留原状态文件、SQLite 表及私有控制管道格式,使用协议包生成的契约校验外部输入。暂停、撤销和能力关闭优先于网络重连与执行,未知写操作不重放。活动边框属于外壳进程,保持分屏物理坐标、鼠标穿透、不激活和工具窗口样式,供驱动识别与排除。便携包不依赖 Node、WinUI 或外置下载运行时;构建和仓库外验包将完整程序目录严格限制在 10,000,000 字节以内。 +外壳显示设置、托盘和活动边框,也处理暂停快捷键与子进程退出。边框使用物理屏幕坐标,允许鼠标穿透并保持当前窗口焦点,驱动会将它从操作目标中排除。运行时沿用原状态文件、SQLite 表和私有控制管道,并用生成的契约校验输入。暂停、撤销和能力开关在重连后继续生效。遇到结果未知的写操作时,先核对原操作及设备状态。 + +便携包包含原生程序及其资源,使用 Windows 自带的运行组件。构建和仓库外验包均要求完整程序目录小于 10,000,000 字节。 ## 身份与授权 -实例管理员通过独立的 Admin Token 或管理员 Cookie 创建普通用户、查看全局用户及设备统计;本地账户统一由 `/api/admin/users` 创建;可选 OIDC 外部身份在首次验证登录时建立独立账户。管理员不自动拥有普通账户身份,也不能用管理员凭据调用设备或 MCP 接口。Token 默认在数据库旁私有保存,支持 `ABRIDGE_ADMIN_TOKEN` 覆盖;浏览器用 Token 兑换 30 天签名 Cookie,会话与普通用户登录相互独立、跨重启保留,Token 重置使全部旧管理员会话失效。 +管理员通过 Admin Token 或管理员 Cookie 进入「实例管理」。可以用 `/api/admin/users` 创建本地普通账户,并查看全局用户和设备统计。设备和 MCP 操作使用各自的凭据。Admin Token 默认保存在数据库旁,可用 `ABRIDGE_ADMIN_TOKEN` 覆盖。浏览器用它换取有效期 30 天的签名 Cookie,管理员与普通用户各有自己的会话,Server 重启后仍有效。重置 Token 会使此前的管理员会话失效。 设备名称可在管理台、Mac App 和浏览器扩展中修改,服务端在连接欢迎消息及心跳确认中同步最新名称。管理台的设备设置只允许改名,设备本机能力由客户端管理并只读展示;首次绑定时确认的能力范围和 Agent 连接策略继续限制访问。新设备 ID 使用 12 位随机 Base64URL 字符,生成时检查重复;已有设备 ID 保持不变,ID 不作为认证凭据。 -普通管理账户负责维护自己的设备与 Agent 连接。Device Key 标识设备,Agent Key 标识调用 MCP 的连接,二者不可互换。可选 OIDC 外部登录按 issuer + sub 映射本地普通账户,不保存外部用户密码;启用平台委托后,首次登录建立默认覆盖全部设备(含新设备)的平台连接,能力仍受设备授权、本机开关与就绪状态限制。显式开启委托后,Server 通过提供方公钥验证用途、受众、客户端和最长 60 秒有效期的访问令牌,映射同一个持久平台连接。平台连接没有 Agent Key,撤销不因重新登录恢复;原有本地账户、Agent Key 和设备绑定保持独立。部署和失效约束见[可选 OIDC 登录](deployment.md#可选-oidc-登录与平台-mcp-委托)。 +普通账户管理自己的设备与 Agent 连接。设备用 Device Key 认证,MCP 请求用 Agent Key 认证。开启 OIDC 后,首次登录按 `(issuer, sub)` 建立独立普通账户。平台委托使用提供方签发的短期令牌,Server 验证签名、用途、受众、客户端和最长 60 秒的有效期,再找到对应平台连接。初始平台连接覆盖本账户全部设备(含新设备),实际能力取决于设备授权、本机开关和就绪状态。撤销后需要显式重新授权。[配置 OIDC 与平台委托](deployment.md#可选-oidc-登录与平台-mcp-委托) 连接具有稳定 ID、名称、设备策略和可选的到期时间;修改策略不更换 Key,轮换 Key 不改变策略。设备类型限制能力上限:`computer` 为 `screen`、`input`、`shell`、`files`,`browser` 仅为 `browser`。 @@ -125,7 +133,7 @@ Windows 壳消息和平台动作契约维护在 `packages/protocol/src/windows-s - `selected`:显式列出每台设备及其能力;新增设备不会自动加入。 - `all`:覆盖当前及以后加入的同账户设备,默认能力与设备类型、设备授权取交集;逐设备覆盖可缩小或调整能力,空覆盖表示排除该设备。 -管理台提供连接视角的设备预览,展示同账户设备的授权范围、在线状态与可用能力。MCP 的 `devices_list` 只返回该连接获准访问且具有有效能力的设备,并附带非秘密的连接 ID 与名称;它不公开未授权设备或账户设备总数。设备在线不等于每个连接都获准访问。 +在管理台的连接预览里,可以看到该连接有权使用哪些设备以及设备当前的状态和能力。MCP 的 `devices_list` 返回当前连接获准且具有有效能力的设备,以及连接 ID 和名称。 `session_open` 保留顶层会话字段和 `server_time`,并在 `device` 中附带与 `devices_list` 一致的设备摘要,包含名称、类型、平台、连接状态和可用的系统与浏览器版本信息。管理台及已授权 Agent 的 `device_get` 可读取完整详情,包括主机名、型号、运行用户和归属账户。 @@ -158,7 +166,7 @@ Agent 高频使用的公开引用保持短:`observation_id` 为 `obs_` 加 8 `computer_windows` 按应用 PID 列出窗口,包含屏幕外窗口。`computer_observe` 在 macOS 上只传 `pid` 刷新同一应用时复用当前会话已选窗口。如果已选窗口消失,需显式选择新窗口。首次选择该应用时,唯一窗口直接观察;多个窗口返回 `window_selection_required`,提示先调用 `computer_windows(pid=...)` 再传 `pid` 与 `window_id` 选择;没有窗口返回 `window_unavailable`。显式传入 `window_id` 时须同时提供 `pid`,且 ID 必须是有效的正安全整数;缺少 PID 或 ID 非法时返回 `invalid_arguments`,错误信息说明缺失字段或提示从 `computer_windows` 取得有效 ID。省略目标时复用会话已选窗口,无目标返回 `target_required`;失败不会替换已选窗口。空窗口列表不能单独证明权限或 Space 问题。 -只有显式 `desktop=true` 才选择整屏,并且不能与窗口目标同时指定。整屏观察不以焦点确认为截图前提:观察前后均确认恰好一个前台普通应用,且其唯一可判定的屏幕内普通前窗保持一致时,返回 `focus_status=confirmed`;焦点无法确认、查询失败或期间切换时,仍返回观察及请求的截图,标记 `focus_status=unconfirmed`、`pixel_actions=false`。截图自身的错误、取消与会话关闭仍正常返回失败。 +每次观察选择一个目标。整屏观察传 `desktop=true`,窗口观察传窗口目标。整屏截图前后都能确认同一个前台应用的唯一普通前窗时,结果标记 `focus_status=confirmed`。焦点查询有歧义、失败或期间切换时,仍返回可取得的观察和请求的截图,并标记 `focus_status=unconfirmed`、`pixel_actions=false`。截图错误、取消和会话关闭照常报告失败。 macOS 观察优先返回 `observation_id`、`available_actions` 和适用的恢复提示,其后是目标窗口、截图几何与有界控件列表。桌面引用最长有效 120 秒,截图坐标的底层凭据可能更早过期。一次刷新从选窗开始就使旧引用失效。枚举或读取失败后仍可重试原目标,取得新引用再继续。动作投递也会消耗当前引用。元素点击使用观察中的元素引用;坐标点击必须使用同一观察的可操作截图和截图像素坐标。macOS 的中键点击和双击均使用截图坐标。窗口坐标点击默认 `action.delivery_mode=background`,由驱动按指定窗口投递。macOS 后台坐标点击重新校验目标窗口的可见性、几何及点击点的同应用覆盖。观察期间被同应用窗口覆盖的点在覆盖消失后仍须重新观察。窗口坐标点击投递前,客户端用相同方式重新截取该窗口并比对整窗像素。图像改变或无法核实时返回 `stale_observation`;动态窗口优先使用新观察中的可用元素引用。可识别的普通文档窗口使用 SDK 原图;需要系统单窗裁取的叠层在像素几何无法确认时仅提供可取得的辅助功能观察。 @@ -174,13 +182,17 @@ macOS 窗口观察的 `keyboard_focus` 分别报告已确认的窗口和接收 每个扩展安装实例注册为独立设备;Profile 由会话的 `device_id` 确定。`browser_open(url=...)` 仅导航自有任务标签,并固定附带新页面观察,不公开关闭观察的选项。`browser_act` 支持 `click`、`fill`、`press`、`select`、`scroll`、`hover`,默认在动作完成后等待 `2000` 毫秒,再附带新观察;外层参数 `wait_after_ms` 可设为 `0–10000` 的整数毫秒,`observe_after=false` 时不等待。`browser_observe` 用于刷新、聚焦查询或检查仍在加载的同一任务页。 -导航加载超时保留任务页,返回 `navigation_state=loading`。导航等待与后观察(含 debugger 初始化)共享 15 秒内部预算;后观察遇导航竞态,最多只读重试两次,额外预算不超过 2 秒。不重新打开标签,也不重放点击或填充。该内部预算不等于标签创建、导航提交或 DOM 动作的总执行期限。 +导航加载超时会保留任务页并返回 `navigation_state=loading`。导航等待与后观察(含 debugger 初始化)共享 15 秒内部预算。后观察遇到导航竞态时,最多再做两次只读重试,额外预算不超过 2 秒。接下来可继续观察同一任务页,原点击或填充回执保持有效。 + +动作后的等待计入现有预算,暂停、取消或关闭会话可以打断等待。动作已经投递时,结果会保留执行状态。后观察显示页面仍在加载时,继续观察同一目标。 + +浏览器观察的 JSON 文本预算约为 7,000 字符,图片有独立预算。正文优先,最多 4,000 字符,剩余空间留给控件和链接。`query` 对正文和控件做忽略大小写的子串匹配,接受一个非空字符串或 1–20 个非空字符串,数组中任一项命中即可。每项最多 200 字符,总长最多 2,000 字符。匹配会去重,截断信息说明本次扫描的范围。链接中的 `target` 是站点声明,实际打开的子标签见 `opened_tabs`。 -动作后的等待计入已有操作与后观察时间预算,不延长超时上限。等待期间暂停、取消或关闭会话仍优先;已执行的动作不会因等待或观察失败而重放。固定等待不保证所有异步任务已完成,页面仍在加载时继续观察同一目标。 +浏览器引用绑定到会话、文档版本和目标,最长有效 60 秒,动作或导航后刷新。工具和脚本里的 `page` 都指向当前任务页。需要访问已观察到的链接时,可以把 URL 交给 `browser_open` 或 `page.goto`。 -浏览器观察文本 JSON 总预算约 7000 字符,不含独立图片;正文优先且上限 4000 字符,再分配交互元素和链接。`query` 接受非空字符串或1–20个非空字符串:单串按整段不区分大小写做子串匹配,数组任一项匹配即可,正文和控件使用同一规则;每项最多200字符、数组总长最多2000字符。匹配结果去重并保持原观察预算。零结果只表示本次扫描的已加载正文与控件未匹配,截断不表示内容不存在,未显示字段也不能用于推断站点全部能力。链接附带声明的 `target` 属性,它不证明已经打开新标签。 +`browser_exec` 在 Server 的 QuickJS 引擎运行。每个浏览器步骤独立核对授权,使用派生操作 ID,并遵循普通动作的去重和取消规则。脚本保留会话独占,回执记录 `steps_completed` 和 `failed_step`。页面动作完成后如果观察失败,回执仍为 `executed`,并附 `observation_error`。默认脚本时限为 20 秒,可设至 120 秒。MCP 默认等待 15 秒,之后可用 `operation_status` 查询或 `operation_cancel` 取消。 -浏览器引用最长有效 60 秒,按会话、文档版本和目标绑定,动作与导航后失效。所有工具及代码中的 `page` 固定指向当前任务页;点击成功不表示导航成功,新标签不会自动接管。访问已观察链接可把其 URL 交给 `browser_open` 或 `page.goto`。点击、键盘与悬停自动滚动并检查目标,在元素准备后通过 CDP Input 执行;滚动修改最近可滚动容器或页面的 DOM 偏移并返回实际 delta,不发送 wheel 事件;已知只读、错误目标类型与当前覆盖层在无副作用预检中拒绝并保留任务页,嵌套滚动容器裁剪则允许显露后再次命中检查;填充使用浏览器文本输入,原生下拉选择触发 DOM 语义事件。站点仍可能拒绝操作。`browser_exec` 在 Server 的隔离 QuickJS 引擎中组织浏览器代码,通过受会话约束的内部工具执行;`page.evaluate` 可执行任务页 JavaScript,原始 CDP 不对 Agent 开放。页面脚本具有该站点登录用户的页面权限,因此固定观察的密码过滤不约束脚本读取。`browser_read` 保存有界文本或表格快照并支持缓存分页;`browser_wait` 支持有期限的条件等待。代码运行与普通动作共用授权、去重和取消,单会话代码执行期间拒绝其他操作;每个浏览器步骤独立检查授权并持有派生操作 ID。脚本失败保留 `steps_completed` 和有界的 `failed_step`(步骤操作 ID、方法、状态及原始错误);首次执行前的明确拒绝为 `refused`,已有步骤完成后的明确失败为 `failed`,在途超时、断连或无确认回执保持 `outcome_unknown`。纯脚本错误为 `failed`,明确取消与结果未知分别报告,不能用步骤数为零推断没有副作用;输入准备的滚动和 focus 也会触发页面事件。动作成功后观察失败仍为 `executed` 并附 `observation_error`。代码默认最多20秒,可设至120秒,MCP等待默认15秒后可通过 `operation_status` 查询或 `operation_cancel` 取消。同一任务页的重复清理等待同一次清理结果,新任务页不能越过清理;清理失败保留原始原因、`cleanup_error` 与必要的恢复信息,无客户端确认时不宣称任务页已清理。控制会话仍有效而任务页缺失返回 `task_tab_missing`,用 `browser_open` 创建任务页;真实停止或过期仍需新建控制会话。详细生命周期及代码接口见 [浏览器客户端](browser-profile-design.md)。 +`page.evaluate` 在任务页中用网站当前用户的页面权限执行,能读取页面向 JavaScript 开放的数据。它和固定观察的字段过滤有各自的访问范围。关于观察、浏览器输入、快照分页、异常回执和清理,见浏览器客户端文档。[浏览器客户端](browser-profile-design.md) ## Shell、文件与结果 @@ -188,17 +200,17 @@ macOS 窗口观察的 `keyboard_focus` 分别报告已确认的窗口和接收 Shell 完整 JSON 默认返回预算 `output_limit_chars=6000`,可设为 1024–12000。`output_truncated` 表示还有保留文本,使用原操作 ID 与 `next_output_offsets` 继续读取;偏移按解码字符计算。`capture_truncated` 表示执行捕获时已丢失内容,分页无法恢复。运行中的滚动窗口可报告 `output_unavailable_before`,最终结果可能仍保留相应前缀。分页只读缓存。 -文件工具仅处理 UTF-8 文本与目录列表,遵循当前用户的系统文件权限。读写正文上限为 1 MiB;写入已存在文件需要显式 `overwrite=true`。Shell 与文件能力不提供隔离沙箱。 +文件工具提供 UTF-8 文本读写和目录列表,正文上限为 1 MiB。覆盖现有文件时,显式使用 `overwrite=true`。Shell 和文件工具使用客户端所在账户的系统权限,可以访问该账户有权限使用的资源。 新操作通常省略 `operation_id`。显式提供时,它是当前 Agent 连接与会话内的请求去重键;Server 将其映射为短规范执行 ID,数据库、设备日志和响应使用该 ID。完整作用域键的 SHA-256 仅保存在数据库内部 `key_hash`,先按完整键查找已有操作;短 ID 碰撞时另选候选,不把不同请求键合并为一次操作。自动分配的短 ID 同样检查数据库重复。`op_` 加恰好 8 位 Base64URL 是 Server 返回 ID 的保留格式,调用方不要用它自建请求键;未知的该格式 ID 会被拒绝。重试同一会话中的同一请求可复用原键或返回 ID,同 ID 改参数会被拒绝;不同会话可独立使用同一原键,已返回的执行 ID 不能用于另一会话。查询和取消只使用响应的 `operation_id`。设备保存执行意图和终态,恢复后不自动重放。Server 仅短期缓存返回内容;SQLite 不保存命令、输入、文件正文或截图。服务重启后未完成操作标为结果未知。 -图片通过原生 MCP `ImageContent` 返回,不在 JSON 中重复嵌入 base64。原始图片上限为 4 MiB,设备 WebSocket 消息上限为 8 MiB。`executed` 仅表示执行回执,业务结果还需检查退出码、文件内容或后续观察。取消和关闭不能回滚已发生的副作用。 +图片通过 MCP `ImageContent` 单独返回,原始图片上限 4 MiB,设备 WebSocket 消息上限 8 MiB。收到 `executed` 后,可通过退出码、文件内容或新观察核对业务结果。取消和关闭只影响后续执行,已经发生的修改需要另行处理。 ## 运行环境与打包 Server 的运行环境按根 `package.json` 的 `engines` 约定:Node.js 22.x 最低 22.13.0,23.x 最低 23.4.0,支持 24 及以上主版本。macOS App 目标为 Apple Silicon/macOS 14+,无需 Node、npm 或 Python。`NativeDriver.swift` 直接使用 Cua Driver 0.47.8 的版本化 C ABI(1.1),按需创建同进程实例并验证 embedded 模式与空 socket 路径。原生会话维持 standard 权限上限,不开启 unrestricted 或浏览器 profile 授权。Server 分发不携带该 SDK。 -App 包内包含 AppKit 主程序、Swift 设备客户端、独立 Swift 更新器、共享契约资源及裁剪到 arm64 的 Cua dylib;不分发 Node、JavaScript 桌面程序或 npm 依赖树。Foundation 负责 WebSocket/HTTP,系统 SQLite 保存操作去重日志,POSIX 进程组实现 Shell 取消,文件操作使用系统 API。凭据、暂停与本机状态保留在 App Bundle 外的私有目录。原生代码或签名变化可能影响系统权限,构建和协议测试不能证明实际已安装 App 的截图或输入可用。 +macOS App 包含 AppKit 主程序、Swift 设备客户端、更新器、共享契约和 arm64 Cua dylib。Foundation 处理 WebSocket 和 HTTP,系统 SQLite 保存去重日志,Shell 通过 POSIX 进程组取消,文件读写使用系统 API。凭据、暂停和本机状态位于 App Bundle 外的私有目录。更换原生代码或签名后,请在实际安装的 App 中检查截图和输入权限。 桌面接管保护只覆盖在途输入,读取和普通鼠标移动不触发暂停。手动暂停持久保存,远程请求不能解除。依赖及许可见 [第三方说明](third-party-notices.md)。 diff --git a/docs/benchmarks/browser-reliability-v2.md b/docs/benchmarks/browser-reliability-v2.md index ce729fc..c427e13 100644 --- a/docs/benchmarks/browser-reliability-v2.md +++ b/docs/benchmarks/browser-reliability-v2.md @@ -1,6 +1,6 @@ # 浏览器通用可靠性与固定环境对照 -本轮从 main 的 0.4.14 重新审查并移植通用修复,再整合 main `0bda49d`(0.4.16,Swift 6 原生桌面架构),最终测量产品提交 `c02c42b`。旧开发分支的修复尚未合入 main,不能直接用旧版本结果代表当前实现。没有加入具体任务的选择器、收件人、日期、答案或操作路径,也没有增加 Agent 可用的工具、Skill、时间或调用预算。 +这次对照从 0.4.14 开始,比较启动修复版与完整的浏览器工具修复版。最终测量的提交为 `c02c42b`,已整合 main 的 `0bda49d`(0.4.16 和 Swift 6 原生桌面架构)。两侧使用同一组任务、可用工具和预算,修复范围集中在扩展启动、页面观察与原生输入。 ## 修复范围 @@ -17,25 +17,25 @@ ## 对照设计 -未修改的 0.4.14 在真实 Chrome 中无法完成设备绑定。这是启动故障,保留其日志,不伪装成12道任务全部失败的得分。先单独提交最小启动修复 `6014447`,再将这个**可启动基线**与完整工具修复版作正式对照。 +0.4.14 在真实 Chrome 中的设备绑定会失败。先做最小启动修复 `6014447`,让浏览器能够接入 Server,然后以这个版本作为基线。绑定阶段的故障保留在日志中,任务评分从浏览器可用后开始。 -两侧使用逐字相同的评测器源码、任务 prompt、`gpt-6.1-sol` / medium、主集合 seed 0/1、每例180秒/40次调用、并发2,无逐例重试。额外 seed=2 另行统计;它仍是同六类任务,开发过程中曾使用,不是独立盲测或六类新题。 +基线和修复版使用同一个评测器、任务提示和模型(`gpt-6.1-sol`,medium)。主集合用种子 0 和 1,每例 180 秒、最多 40 次调用,并发 2,每例运行一次。开发期间也使用过种子 2,因此把它作为同六类任务的额外运行单独统计。 -本轮使用 Codex 的 `--model-catalog` 评测参数,最终传递官方 `model_catalog_json` CLI配置项。模型条目从本机已有缓存逐字复制,不编写替代指令、不修改模型能力。基线与修复版共用同一份文件,运行前后核验 SHA-256,并随结果记录摘要。它只固定元数据,不能消除模型响应或网络波动,也不能把历史未固定目录的成绩当成严格受控对照。 +通过 `--model-catalog` 将同一份目录传入两侧的 Codex 子进程,对应 `model_catalog_json` 配置。目录条目从本机缓存逐字复制,运行前后核对 SHA-256,摘要随结果保存。这样可以避开模型目录刷新超时。网络和模型响应时间仍会波动。 [官方本地目录说明](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#distribute-a-local-catalog) · [配置参考](https://learn.chatgpt.com/docs/config-file/config-reference)。使用临时子进程配置,不修改用户全局 Codex 配置或认证。 -另显式关闭评测子进程的 `features.plugins`、`features.remote_plugin`,避免用户全局插件市场后台刷新占用本轮预算。空 `plugins={}` 不能替代功能开关。[官方功能开关说明](https://learn.chatgpt.com/docs/enterprise/managed-configuration#control-plugin-availability)。只修改本次子进程设置,不改变用户全局配置。 +运行时关闭评测子进程的 `features.plugins` 和 `features.remote_plugin`,避免后台刷新插件市场占用任务预算。功能开关只应用于本次子进程。[官方功能开关说明](https://learn.chatgpt.com/docs/enterprise/managed-configuration#control-plugin-availability) -真实链路为 Codex → MCP → Server → WebSocket → 实际扩展 → Chrome。Actor 仅可使用 browser_observe/read/act/wait,不能执行 JS、直接读取源码或访问判分状态;初始化和判分由控制器单独执行。继续使用[固定上游与评分方法](miniwob.md)。 +Codex 通过 MCP 调用 Server,再由实际的 Chrome 扩展执行操作。Agent 可调用 `browser_observe`、`browser_read`、`browser_act` 和 `browser_wait`。控制器单独初始化和判分。[上游任务与评分方法](miniwob.md) ## 结果与审核 -结果由 README 表格和原始快照生成,不手写分数:[可启动基线](miniwob-v2-baseline.json)、[修复版主集合](miniwob-v2-results.json)、[额外种子](miniwob-v2-extra.json)。 +README 的表格从原始快照生成。[试验基线](miniwob-v2-baseline.json) · [修复版主集合](miniwob-v2-results.json) · [额外种子](miniwob-v2-extra.json) -[全量案例](cases-all.md)与[按标准审核后的案例](cases-conforming.md)分开提供。沿用[任务有效性政策](https://github.com/xerrors/aBridge/blob/main/tools/bench-case-policy.json),失败、超时、工具不足或 CLI 故障均不能作为剔除依据;当前没有任务不符合约定的独立证据。未知奖励与用量保持未知,不能当作零或推算完整美元成本。 +本轮审核保留所有案例,失败和超时照常计入分母。缺少奖励或用量的记录保留为未知。[全量案例](cases-all.md) · [任务审核](cases-conforming.md) · [审核标准](https://github.com/xerrors/aBridge/blob/main/tools/bench-case-policy.json) -历史结果保留在[之前开发分支的快照](https://github.com/xerrors/aBridge/tree/b335d16b28eca4ce801e2dee687c0bfffce5a331/docs/benchmarks),不从不同版本抽取最好样本,也不将额外种子或重复运行混入主集合分母。 +不同版本的历史运行各自统计,额外种子和重复运行也单独保留。[历史快照](https://github.com/xerrors/aBridge/tree/b335d16b28eca4ce801e2dee687c0bfffce5a331/docs/benchmarks) ## 最终结果与剩余问题 @@ -46,13 +46,13 @@ | 工具调用尝试总数 | 102 | 67 | | 用量覆盖 | 10/12 | 12/12 | -额外seed=2为6/6,37次调用,单独统计、不合并主集合分母。最终18例会话清理均成功,实际越权为0,未见目录刷新、插件诊断或终止错误事件。但**不是零工具错误**:主集合与额外集合各2次可恢复invalid_action,Agent恢复后完成任务。详见[审计计数](miniwob-v2-diagnostics.json)。 +额外种子 2 完成 6/6,共调用 37 次。主集合和额外集合的 18 个会话均成功清理。两组各有两次可恢复的 `invalid_action`,Agent 恢复后完成了任务。运行日志里的越权、目录刷新错误、插件诊断和终止错误均为 0。[审计计数](miniwob-v2-diagnostics.json) -本次完整运行没有失败案例;这不表示历史问题被删除。整合0.4.16前,0.4.14完整修复版的[主集合11/12](miniwob-v2-premerge-results.json)、[额外6/6](miniwob-v2-premerge-extra.json)与[对应基线](miniwob-v2-premerge-baseline.json)均保留。那轮book-flight seed1在渲染准备后目标复核失败,按未知结果保护关闭任务页;保留task_tab_lost和未知奖励,没有重放或加入专用规则。本轮完整重跑两例订票均成功,不能据此断言该偶发风险已消失。 +整合 0.4.16 前,0.4.14 修复版的主集合完成 11/12。失败的是 `book-flight` 的种子 1。渲染准备后目标复核失败,任务页关闭,记录为 `task_tab_lost`,奖励未知。本轮重跑的两例订票都成功。[整合前主集合](miniwob-v2-premerge-results.json) · [额外种子](miniwob-v2-premerge-extra.json) · [对应基线](miniwob-v2-premerge-baseline.json) -基线仍为0.4.14最小启动修复版 `6014447`,不是未修改的0.4.16。比较固定了评测器、模型目录和环境,但跨越了main集成,不能把全部差异单独归因某一项工具改动。整合后额外修复Swift 6对同步C ABI借用指针的隔离编译错误;原生SDK只读调用和App构建通过,不代表系统权限或真实桌面输入已验收。 +对照的起点是 0.4.14 启动修复版,终点包括浏览器修复和 0.4.16 的整合,因此表格反映两者之间的整体差异。整合后也修复了 Swift 6 对同步 C ABI 借用指针的编译错误,通过原生 SDK 只读调用和 App 构建检查。桌面权限和真实输入需要在实际安装的 App 中单独验收。 -耗时改善包含较少重复观察和输入失败,也仍受模型/网络时间波动影响,不能单独等同于桥接执行器更快。基线2例缺失usage,已知token合计不能当作完整总成本;CLI没有实际美元账单。 +修复后减少了重复观察和输入失败,也可能受到模型及网络耗时波动影响。基线有两例缺少用量,成本分析限于 CLI 实际返回的 token 数据。 本地 `npm run check` 已通过,300/300自动测试通过;9/9组真实Chrome自有fixture通过。检查还包括格式、架构、类型、分发和离线安装;GitHub CI按五个Node/系统组合另行验证。公开数据生成README和图,并通过输入摘要核对一致性。 @@ -60,11 +60,11 @@ 第一轮固定目录后,正式基线3/12、候选原始8/12。候选有一例官方奖励1、CLI正常退出,却因插件市场更新超时产生的纯诊断 `item.type=error` 被误算为未知工具调用。判分器现只将已知 `id/type/message` 形态归为诊断;带执行字段或未知字段仍拒绝,实际工具白名单没有放宽。 -对两侧全部原始日志重解析后,基线仍3/12,候选9/12;仅该例的错误越权标签被纠正,任务、奖励、耗时、用量与分母不变。这是判分器修复,不是剔除案例,也未将时间预算失败改成成功。 +重新解析双方完整日志后,基线为 3/12,候选为 9/12。唯一更正是上述一例的越权标签,原有任务结果、奖励、耗时、用量和分母均保留。 [第一轮基线](miniwob-v2-stage1-baseline.json) · [候选原始8/12](miniwob-v2-stage1-results.json) · [重算9/12](miniwob-v2-stage1-rescored.json) · [逐例修正记录](miniwob-v2-stage1-adjudication.json)。第一轮命令因误判越权非零退出,额外种子尚未运行;没有借用其他版本的额外成绩。 -随后双方均使用相同的禁用插件配置重新跑完整集合。不能把不同配置的最好结果混成最终成绩。此前清理Docker后的[主集合8/12](miniwob-clean-host-results.json)与[额外4/6](miniwob-clean-host-extra.json)也保留为历史记录,因版本与CLI目录配置不同,不作为本轮受控基线。 +之后双方按相同的禁用插件配置重跑完整集合。更早的 Docker 清理后运行使用不同的版本和目录配置,单独保留在历史记录中。[历史主集合 8/12](miniwob-clean-host-results.json) · [额外种子 4/6](miniwob-clean-host-extra.json) ## 独立验证与复现 @@ -81,4 +81,4 @@ python3 tools/bench-plot.py 本地模型目录应来自实际模型提供方或已缓存的匹配条目;不得使用文档示例替换真实模型的指令和能力。认证、Profile、截图与原始 CLI/网关日志保留在忽略的 `.local/bench/`,不随公开结果上传。制图单独需要 matplotlib 与 CJK 字体,默认 CI 不安装 Python。 -这是小样本、单模型、单机器的适配子集,不是官方 MiniWoB 榜单或竞品比较。单次点估计达到80%–90%不等于已经证明长期稳定的泛化成功率;网络、模型服务和宿主机资源仍会变化。真实浏览器回归不证明 macOS App 权限或系统输入已经验收。 +这组结果对应一台机器上的一个模型和六类适配任务。复现时,网络、模型服务和宿主机资源都会影响耗时和成功率。 diff --git a/docs/benchmarks/cases-all.md b/docs/benchmarks/cases-all.md index 9eadd38..615fce4 100644 --- a/docs/benchmarks/cases-all.md +++ b/docs/benchmarks/cases-all.md @@ -1,15 +1,13 @@ # 全量案例报告 -政策版本:task-validity-v1。包含全部最终尝试,失败、超时和采集异常不隐去。 +本表列出每次最终尝试,包括失败、超时和采集异常。审核规则版本为 task-validity-v1。 | 集合 | 严格成功 / 分母 | | --------------- | --------------- | | 主对照 seed 0/1 | 12/12 | | 额外 seed 2 | 6/6 | -两侧使用相同模型目录与评测器;网络、模型响应及工具等待均可能影响端到端预算。超时全部保留,不属于任务不合规,不能据此剔除。 - -任务未初始化仅指Agent动作前已由独立证据确认的错误。操作后的异常、任务失败、预算耗尽、模型或工具能力不足都不是排除理由。判分采集异常与任务合规性分别记录;已超时即严格失败,不因奖励未知而剔除。 +两侧使用相同的模型目录和评测器。网络、模型响应和工具等待都计入端到端时间。超时按失败计入分母,即使原始奖励未知。判定任务未初始化时,以 Agent 动作前取得的独立证据为准。判分采集异常另行记录。 | 集合 | 任务 | seed | 严格成功 | 原始奖励 | 失败记录 | 标准审核 | | ------ | ---------------------- | ---- | -------- | -------- | -------- | ---------- | @@ -32,7 +30,7 @@ | extra | click-menu-2 | 2 | 是 | 1 | — | 符合,保留 | | extra | multi-layouts | 2 | 是 | 1 | — | 符合,保留 | -## 版本历史(不混入最终分母) +## 历史运行 | 版本 | 全量严格成功 | 原始数据 | | -------------------------------- | ------------ | -------------------------------------------- | @@ -45,11 +43,11 @@ | 整合0.4.16前的0.4.14完整修复版 | 11/12 | [逐次结果](miniwob-v2-premerge-results.json) | | 当前版本 | 12/12 | [逐次结果](miniwob-v2-results.json) | -历史数据保留,不用不同版本的最好成绩拼接最终结果。配置不同的历史分数不能用来单独归因本轮优化。stage1原始8/12因CLI诊断误判越权,全量重解析后9/12,见[修正记录](miniwob-v2-stage1-adjudication.json),没有删除任何样本。额外种子另列,不将重复尝试混入主对照。 +历史运行和额外种子各自统计。第一阶段原始得分为 8/12,其中一例的 CLI 诊断消息被误判为越权。重新解析完整日志后,得分为 9/12,分母仍为 12。[修正记录](miniwob-v2-stage1-adjudication.json) ## 剔除清单 -无。当前没有证据证明这些任务违反约定,不能为提高分数而强行剔除。 +本轮所有任务均保留。 ## 审核标准 @@ -58,8 +56,8 @@ - undeclared_external_prerequisite:任务实际依赖评测约定未提供的外部账号、服务或数据 - outside_declared_task_scope:任务本身要求声明范围之外的操作,须有独立任务契约证据;工具实现缺陷不属于此类 -固定上游任务在本地运行;日期范围和界面变化属于原始任务内容,不因难度或缺少语义标注而排除。工具不足应作为产品问题修复。 +在本机运行固定版本的上游任务,保留原有日期范围与界面。任务难度、语义标注缺失和工具能力不足均记录在试验结果中。 [原始逐次结果](miniwob-v2-results.json) · [额外种子结果](miniwob-v2-extra.json) · [通用修复报告](browser-reliability-v2.md) -这是小样本、单模型的探索性结果,不是官方榜单或大样本泛化结论。 +本次测量覆盖一个模型和这组适配任务。评测范围和复现方式见 [MiniWoB++ 方法](miniwob.md)。 diff --git a/docs/benchmarks/cases-conforming.md b/docs/benchmarks/cases-conforming.md index 7e8bd27..72af559 100644 --- a/docs/benchmarks/cases-conforming.md +++ b/docs/benchmarks/cases-conforming.md @@ -1,15 +1,13 @@ # 按任务标准审核后的报告 -政策版本:task-validity-v1。本轮剔除 0 例。 +审核按 task-validity-v1 执行,本轮排除 0 例。 | 集合 | 严格成功 / 分母 | | --------------- | --------------- | | 主对照 seed 0/1 | 12/12 | | 额外 seed 2 | 6/6 | -两侧使用相同模型目录与评测器;网络、模型响应及工具等待均可能影响端到端预算。超时全部保留,不属于任务不合规,不能据此剔除。 - -任务未初始化仅指Agent动作前已由独立证据确认的错误。操作后的异常、任务失败、预算耗尽、模型或工具能力不足都不是排除理由。判分采集异常与任务合规性分别记录;已超时即严格失败,不因奖励未知而剔除。 +两侧使用相同的模型目录和评测器。网络、模型响应和工具等待都计入端到端时间。超时按失败计入分母,即使原始奖励未知。判定任务未初始化时,以 Agent 动作前取得的独立证据为准。判分采集异常另行记录。 | 集合 | 任务 | seed | 严格成功 | 原始奖励 | 失败记录 | 标准审核 | | ------ | ---------------------- | ---- | -------- | -------- | -------- | ---------- | @@ -32,7 +30,7 @@ | extra | click-menu-2 | 2 | 是 | 1 | — | 符合,保留 | | extra | multi-layouts | 2 | 是 | 1 | — | 符合,保留 | -## 版本历史(不混入最终分母) +## 历史运行 | 版本 | 全量严格成功 | 原始数据 | | -------------------------------- | ------------ | -------------------------------------------- | @@ -45,11 +43,11 @@ | 整合0.4.16前的0.4.14完整修复版 | 11/12 | [逐次结果](miniwob-v2-premerge-results.json) | | 当前版本 | 12/12 | [逐次结果](miniwob-v2-results.json) | -历史数据保留,不用不同版本的最好成绩拼接最终结果。配置不同的历史分数不能用来单独归因本轮优化。stage1原始8/12因CLI诊断误判越权,全量重解析后9/12,见[修正记录](miniwob-v2-stage1-adjudication.json),没有删除任何样本。额外种子另列,不将重复尝试混入主对照。 +历史运行和额外种子各自统计。第一阶段原始得分为 8/12,其中一例的 CLI 诊断消息被误判为越权。重新解析完整日志后,得分为 9/12,分母仍为 12。[修正记录](miniwob-v2-stage1-adjudication.json) ## 剔除清单 -无。当前没有证据证明这些任务违反约定,不能为提高分数而强行剔除。 +本轮所有任务均保留。 ## 审核标准 @@ -58,8 +56,8 @@ - undeclared_external_prerequisite:任务实际依赖评测约定未提供的外部账号、服务或数据 - outside_declared_task_scope:任务本身要求声明范围之外的操作,须有独立任务契约证据;工具实现缺陷不属于此类 -固定上游任务在本地运行;日期范围和界面变化属于原始任务内容,不因难度或缺少语义标注而排除。工具不足应作为产品问题修复。 +在本机运行固定版本的上游任务,保留原有日期范围与界面。任务难度、语义标注缺失和工具能力不足均记录在试验结果中。 [原始逐次结果](miniwob-v2-results.json) · [额外种子结果](miniwob-v2-extra.json) · [通用修复报告](browser-reliability-v2.md) -这是小样本、单模型的探索性结果,不是官方榜单或大样本泛化结论。 +本次测量覆盖一个模型和这组适配任务。评测范围和复现方式见 [MiniWoB++ 方法](miniwob.md)。 diff --git a/docs/benchmarks/miniwob.md b/docs/benchmarks/miniwob.md index bd4bb49..17639b6 100644 --- a/docs/benchmarks/miniwob.md +++ b/docs/benchmarks/miniwob.md @@ -1,6 +1,6 @@ # 真实 Agent 浏览器任务评测 -本评测衡量固定 Agent 使用 aBridge 完成公开浏览器任务的效果与资源消耗。真实链路为 **Codex Agent → HTTP MCP → Server → WebSocket → 实际加载的 aBridge 扩展 → Chrome CDP 输入 → 上游判分**。任务求解没有人工操作或预写答案脚本。它评测的是这一整套模型与工具配置,不能将成功或失败全部归因于 aBridge。 +这组评测记录 Codex Agent 通过 aBridge 完成 MiniWoB++ 浏览器任务所需的时间和工具调用。Agent 从网页读取任务并操作实际加载的扩展,MiniWoB++ 独立判分。结果对应下面列出的模型、工具和运行环境。 ## 快速复现 @@ -11,7 +11,7 @@ npm install --ignore-scripts npm run benchmark:miniwob ``` -默认运行冻结的 12 个样本,会真实消耗模型用量。优先发现本机 Playwright 缓存中的 Chrome for Testing,也可用 `ABRIDGE_BENCH_CHROME=/absolute/path/to/chrome` 指定。不需要 Python、Selenium、BrowserGym 或新 npm 运行依赖。使用隔离的有界面 Chrome、临时 Server 和虚构设备,不连接个人 Profile 或真实业务账户。普通 Chrome 可能禁止命令行加载扩展;找不到实际扩展 worker 会失败,不使用扩展替身。 +默认运行 12 个任务与种子组合,会产生实际模型用量。脚本优先使用本机 Playwright 缓存的 Chrome for Testing,也可以通过 `ABRIDGE_BENCH_CHROME=/absolute/path/to/chrome` 指定。运行时会创建隔离的浏览器 Profile、临时 Server 和虚构设备。若遇到扩展加载失败,请确认浏览器支持 `--load-extension`。 先用不计分的简单任务检查认证、MCP 和浏览器: @@ -19,21 +19,19 @@ npm run benchmark:miniwob npm run benchmark:miniwob -- --preflight ``` -生成新的完整结果并更新 README: +单独保存本地运行结果: ```sh -npm run benchmark:miniwob -- --out docs/benchmarks/miniwob-agent-results.json -npm run benchmark:report -npm run check +npm run benchmark:miniwob -- --out .local/bench/result.json ``` -真实模型评测不进入默认 CI。CI 只运行确定性测试、校验冻结协议、完整样本集合及 README 与快照的一致性。任务失败是跑分数据;基础设施、越权、清理失败则命令非零退出。预检任何失败都非零退出。 +CI 用 `npm run benchmark:report:check` 核对仓库中的评测结果、README 和图表。需要从已登记的快照重新生成报告时,用 `npm run benchmark:report`。真实模型评测按需运行。基础设施、越权或清理失败会使命令返回非零状态,普通任务失败则记录在结果中。 ## 数据来自哪里 -使用 [Farama Foundation MiniWoB++](https://github.com/Farama-Foundation/miniwob-plusplus/tree/33c3b4ddef8c6eb67c57a29663d844b1eda7e614),固定 commit `33c3b4ddef8c6eb67c57a29663d844b1eda7e614`,MIT 许可。任务、脚本、样式、图像保持上游原样;[来源清单](https://github.com/xerrors/aBridge/blob/main/tools/bench/miniwob-agent-source.json) 保存每个文件的 SHA-256,下载缓存逐项校验。数据不是我们编写的业务题或根据模型成绩挑选的样例。 +任务、脚本、样式和图片使用 Farama Foundation MiniWoB++ 的固定提交,许可为 MIT。下载时根据来源清单逐项校验文件的 SHA-256。[上游源码](https://github.com/Farama-Foundation/miniwob-plusplus/tree/33c3b4ddef8c6eb67c57a29663d844b1eda7e614) · [来源清单](https://github.com/xerrors/aBridge/blob/main/tools/bench/miniwob-agent-source.json) -[冻结协议](https://github.com/xerrors/aBridge/blob/main/tools/bench/agent-suite.json) 在正式运行前确定以下任务,每类使用数字种子 `0、1`,test 模式。上游通过种子生成文字、目标和界面布局,控制器调用 `Math.seedrandom(seed)`、`core.setDataMode('test')`、`core.startEpisodeReal()`。不手写答案,不根据失败修改样例,不重试或挑选最好结果。 +评测前先定下下表中的任务,每类在 test 模式下使用种子 0 和 1,各运行一次。控制器依次调用 `Math.seedrandom(seed)`、`core.setDataMode('test')` 和 `core.startEpisodeReal()`,由上游任务生成目标和页面。[评测配置](https://github.com/xerrors/aBridge/blob/main/tools/bench/agent-suite.json) | 任务 | 内容 | 原始限时 | | ------------------------ | ------------------------ | -------- | @@ -44,11 +42,11 @@ npm run check | `click-menu-2` | 选择文字或图标菜单项 | 10 秒 | | `multi-layouts` | 在变化布局中填写表单 | 20 秒 | -这些任务覆盖顺序操作、自然语言定位、树结构、视觉目标和布局变化,但不等于复杂企业流程。邮件 test 模式的措辞模板有限,航班日期来自上游旧任务。每类仅两个种子,结果方差可能很大。 +任务覆盖顺序操作、自然语言定位、树结构、视觉目标和布局变化。邮件任务沿用 test 模式的措辞模板,航班日期来自上游任务。每类只取两个种子,尤其是耗时统计容易随样本变化。 ## 固定 Agent 与权限边界 -模型 `gpt-6.1-sol`,reasoning `medium`,独立 ephemeral Codex 进程,每例新会话、不携带上例聊天。统一限时 **180 秒**、最多 **40 次工具调用**、并发 **2**。限时包括 CLI 启动与模型请求。上游原始限时过短,因此统一覆盖为 180 秒,奖励函数和答案不变:这是适配子集,不能与官方原始限时榜单直接比较。 +每例使用独立的 Codex 进程和新会话,模型为 `gpt-6.1-sol`,推理等级为 `medium`。统一限时 **180 秒**、最多 **40 次工具调用**、并发 **2**,CLI 启动和模型请求也计时。结果对应这一组延长限时的适配任务,奖励函数和答案沿用上游。 Agent 只拿到可见任务指令、当前会话 ID 和四个工具:`browser_observe`、`browser_read`、`browser_act`、`browser_wait`。首次要求观察截图,后续可使用 DOM 与截图。独立 MCP 网关限制工具、会话和读取范围,不暴露 `browser_exec`、会话管理、源码直接读取或判分接口。CLI 关闭 shell、其他 MCP、插件、web search 和多 Agent;工具轨迹按允许列表审计。超出调用预算的请求在转发前拒绝。 @@ -62,28 +60,28 @@ Agent 只拿到可见任务指令、当前会话 ID 和四个工具:`browser_o - **严格成功 `success`**:任务完成,且 Agent 正常退出、未超时、未超调用预算、无工具越权。README 使用此口径。任务已完成但 Agent 超时仍计失败,原始完成状态可复核。若动作失败导致产品关闭任务页,记为 `task_tab_lost`,判分值为 `null`;只确认端到端未完成,不推测已经消失页面的奖励。 - **分母**:冻结的全部 12 个任务/种子,包括失败;每例不重试。启动环境失败不生成有效分数;已开始的逐例异常记录为失败并保留原因。 - **Agent 耗时**:从启动 CLI 前到进程退出,包含模型、MCP 和浏览器等待,不含页面初始化、判分、清理及一次性环境启动。已开始的失败/超时同样进入统计,尚未启动为 `null`。P50 是中位数,P95 是 nearest-rank;每类两个样本不足以推断稳定尾延迟。 -- **工具调用**:Agent 发到网关的调用尝试总数,包括错误与预算拒绝,不是鼠标点击次数。准备和判分不计入。 -- **token 消耗**:CLI 完整 turn 返回的输入、缓存输入、输出 token。输入包含缓存;缓存不能重复相加。超时或中断可能缺少 usage,因此同时报告已知合计与覆盖率,未知不等于 0。reasoning 未提供时为 `null`。 -- **美元成本**:CLI 不返回实际账单,`costUsd=null`,不编造金额,也不拿不完整 token 合计计算每次成功的完整成本。 +- **工具调用**统计 Agent 发到网关的调用尝试,含错误与预算拒绝。准备和判分由控制器执行,另行记录。 +- **token 消耗**来自 CLI 的用量报告。输入总量已包含缓存。超时或中断时,缺失的 usage 记为未知,同时报告已知合计和覆盖率。缺少 reasoning 时记为 `null`。 +- **美元成本**字段保留为 `costUsd=null`,测量只收集 CLI 提供的 token 用量。 - **清理**:关闭会话后 10 秒内确认本次唯一标签已消失。任务成功与清理独立记录,清理失败使命令失败。 ## 证据与局限 -[逐次结果](miniwob-agent-results.json) 保存每例判分、失败原因、耗时、工具数、用量及环境;README 自动生成,不手填成绩。运行前冻结协议和 benchmark 文件哈希,运行后确认文件未变。结果包含扩展 worker SHA-256 和产品基线提交;新增 benchmark 尚未提交时,其准确版本由文件哈希描述。 +逐次结果包含判分、失败原因、耗时、工具调用数、用量和环境,README 由登记的快照生成。评测前后会核对任务文件哈希,结果也记录扩展 worker 的 SHA-256 与产品提交。[当前逐次结果](miniwob-v2-results.json) · [此前运行](miniwob-agent-results.json) 原始 CLI JSONL(含截图)、stderr、网关轨迹、隔离 Profile、临时凭据和数据库只保留在忽略的 `.local/bench/runs/agent-*/`,不公开上传。正常结束和 SIGINT/SIGTERM 都清理本次服务与浏览器,证据文件保留。公开快照不含原始提示回复、会话 ID 或凭据。 开发预检修复了 MCP Accept 头、CLI 工具审批配置和任务页丢失的错误分类;分类缺陷的未完成批次中止并保留在本地,正式结果使用修复后同一冻结协议的完整批次,未混用最好成绩。 -这是首次小样本基线,单模型、单机器、无竞争工具对照。公开任务可能存在训练污染风险;同一种子跨环境仍可能受浏览器、日期、模型后端和网络影响。要形成比较结论,应先扩大冻结种子,再对不同 aBridge 版本或工具后端使用相同任务、模型、预算作配对评测,同时报告失败分类、完整用量覆盖与置信区间。当前结果不能证明跨模型泛化或工具性能优势。 +本次运行覆盖一个模型和一台机器。公开任务可能进入过模型训练数据,同一任务也会受浏览器、日期、模型后端和网络影响。若要比较不同版本,可固定任务、模型和预算,增加配对种子,并一起报告失败分类、用量覆盖和置信区间。 ## 独立的执行链冒烟与负对照 -此前固定可见 DOM 策略的 `click-test`、`enter-text`、`read-table` 30/30 是[冒烟历史数据](miniwob-results.json),不是 Agent 能力得分。其源码使用上游原始 10 秒限时;不与本次真实 Agent 合并统计。历史快照的源码哈希代表当时版本,不保证与后续重构逐字一致。 +历史冒烟测试使用固定 DOM 策略,在上游 10 秒限时下完成 `click-test`、`enter-text` 和 `read-table`,共 30/30。它与 Agent 评测各自统计,历史源码版本可通过快照中的哈希核对。[冒烟历史数据](miniwob-results.json) ```sh npm run benchmark:smoke -- --episodes 1 npm run benchmark:smoke -- --episodes 1 --negative-controls ``` -[负对照结果](miniwob-controls.json) 分别验证不操作导致超时、错误文本、错误表格答案会被上游拒绝。人为制造的错误仅验证判分器,绝不混入真实 Agent 失败率。 +负对照用三种预期失败的情况检查判分器:等待超时、提交错误文本和提交错误表格答案。这些例子单独统计。[负对照结果](miniwob-controls.json) diff --git a/docs/browser-profile-design.md b/docs/browser-profile-design.md index 38907df..0d96029 100644 --- a/docs/browser-profile-design.md +++ b/docs/browser-profile-design.md @@ -4,23 +4,29 @@ aBridge for Browser 是 TypeScript 实现的独立 Chromium 扩展,每个安装实例注册为一个 `browser` 设备,直接连接 Server。不同浏览器或 Profile 中的扩展分别命名、绑定、暂停和撤销。扩展与 App 独立运行。 -Agent 通过 `devices_list` 选择设备 ID,再创建仅含 `browser` 的会话。Profile 已由设备身份确定,导航工具不接受 Profile 名称、默认项或配置目录,也不能在会话失联后自动切换账号。 +Agent 用 `devices_list` 找到浏览器设备,再用设备 ID 开启只请求 `browser` 能力的会话。这个设备 ID 已经选定 Profile。会话失联后,请重新连接原设备并建立会话。 ## 首次绑定 -先运行 `npm run build`,再通过开发者模式加载 `dist/browser/` 中已构建的扩展。源 TypeScript 目录不能直接加载。点击扩展图标并选择「连接浏览器」,在绑定标签页填写 Server 地址和设备名称。使用远程 HTTP 时先在表单中确认,再向 Chrome 授予站点访问权限。扩展通过 `chrome.identity.launchWebAuthFlow` 打开管理台授权页;用户在浏览器中登录并确认后,扩展用一次性授权码和 PKCE 兑换 Device Key,只保存设备凭据。绑定时授权访问所填 Server 地址;远程连接推荐 HTTPS/WSS;公网 HTTP/WS 需在客户端确认风险,本机回环 HTTP/WS 无需额外确认。 +在选好的 Chrome Profile 中安装扩展。开发时先运行 `npm run build`,再到 `chrome://extensions` 加载 `dist/browser/`。[Chrome 应用商店](https://chromewebstore.google.com/detail/abridge-for-browser/jbkhngckehhhhkbgpjlifbbchhbeodjc) -首次绑定的名称默认为 `Chrome · Profile`,可直接修改。已获 `identity.email` 可选权限时,通过 `chrome.identity.getProfileUserInfo({ accountStatus: "ANY" })` 读取当前 Profile 的账户邮箱,建议名称为 `Chrome · 邮箱`;未获权限时,只有点击“使用 Profile 账户”才请求读取权限,不自动弹出授权或打开网页登录。浏览器 API 不提供 Profile 的本地昵称,也不保证未登录、隐身或其他 Chromium 浏览器能返回邮箱;无邮箱或读取失败时保留通用默认名。账户信息只用于未编辑的首次绑定表单,不覆盖手动修改、已保存设备名称或等待中的授权名称;最终设备名称仍随绑定请求发送给 Server。 +点击工具栏图标,选择「连接浏览器」,填写 Server 地址和设备名称。远程连接建议使用 HTTPS。使用远程 HTTP 时,先确认地址,再允许扩展访问该站点。本机回环地址只需授予站点访问权限。 -扩展直接连接 `/ws/browser`,在首条认证消息传递设备凭据,不将凭据放入 URL。Agent Key 只用于 MCP 调用,不能作为设备凭据。使用“指定设备”的 Agent 连接时,在管理台为该浏览器开启 `browser`;选择“全部设备(含新设备)”且默认能力包含 `browser` 的连接自动覆盖新注册的浏览器。连接策略可编辑,无需重新配置 MCP Key。 +选择「在浏览器授权」后,扩展通过 `chrome.identity.launchWebAuthFlow` 打开管理台。登录并确认后,扩展用一次性授权码和 PKCE 换取 Device Key,保存在本地。 -扩展向 Server 发起授权后,由后台 worker 持有该流程。工具栏弹窗可以查看进度,在连接标签页可以取消绑定请求。授权窗口的等待独立于配置消息队列,不阻塞状态读取和本机控制。授权回调固定为当前扩展 ID 的 `https://.chromiumapp.org/abridge-authorize`;取消、拒绝或过期不会写入绑定。浏览器或 worker 异常退出后重新发起授权,不自动批准旧请求。 +首次绑定时的默认名称是 `Chrome · Profile`,你可以直接修改。点击「使用 Profile 账户」时,扩展按需请求 `identity.email` 权限,用 `chrome.identity.getProfileUserInfo({ accountStatus: "ANY" })` 读取邮箱,并建议 `Chrome · 邮箱` 作为名称。浏览器未提供邮箱时保留默认名称。建议仅用于尚未编辑的首次绑定表单,授权进行中和已保存的名称会原样保留。Server 收到的是你最终选定的设备名称。 -绑定、持久暂停和任务会话互相独立。任务结束、扩展重启或网络重连不要求重新绑定;撤销凭据后不会自动注册新设备。网站登录过期仍需要正常登录,设备授权并不延长站点会话。 +扩展通过 `/ws/browser` 连接,在首条认证消息中提交 Device Key。为 Agent 配置 MCP 时使用 Agent Key。 + +如果 Agent 连接只允许访问指定设备,请在管理台为这台浏览器开启 `browser`。如果连接允许全部设备(含新设备),且默认能力包含 `browser`,新浏览器会自动加入。修改连接范围后可以继续使用原 Agent Key。 + +发起授权后,后台 worker 负责等待浏览器回调,期间仍可读取状态和使用本机控制。工具栏弹窗可以查看进度,连接页可以取消申请。回调地址为 `https://.chromiumapp.org/abridge-authorize`,其中 `` 为当前扩展 ID。绑定只在授权成功后写入。浏览器异常退出、请求被取消或过期时,请重新发起授权。 + +任务结束、扩展重启或网络重连时继续使用现有绑定,暂停设置也会保留。设备凭据被撤销后,需要重新绑定。网站会话到期时,请按网站提示重新登录。 ## 任务与工具 -每个任务会话创建自己的后台标签页,复用所在 Profile 的网站登录态。任务只导航和操作自有标签页,不接管原有个人标签;正常会话关闭、断连和停止时清理任务资源。浏览器的标签恢复行为可能受浏览器设置影响,清理失败会保留记录并阻止新任务。 +每个会话会在当前 Profile 中打开自己的后台任务标签页,沿用这个 Profile 的网站会话。任务只在这些标签中运行。关闭会话、断连或停止任务时,扩展会清理任务资源。标签页也受浏览器的恢复设置影响。清理失败时,扩展保留记录并暂停接收新任务。 | 工具 | 行为 | | ----------------- | ----------------------------------------------------- | @@ -30,32 +36,42 @@ Agent 通过 `devices_list` 选择设备 ID,再创建仅含 `browser` 的会 `browser_act` 的外层参数 `wait_after_ms` 决定动作完成后、读取页面与截图前的等待时间,默认 `2000` 毫秒,可设 `0–10000` 的整数;例如 `3000` 等待 3 秒,`0` 立即观察。`observe_after=false` 不等待,单独的 `browser_open` 与 `browser_observe` 不新增固定等待。等待计入已有时间预算,可被取消或会话关闭打断;动作已经执行但后续观察失败时,只重新观察,不重复点击。 -观察返回可见文本、交互元素、链接和明确截断标记。语义控件优先;无语义文本可通过 StaticText 引用精确定位字形范围,未命名 CSS 图标通过有界可见 pointer 目标发现并绑定原 DOM 身份。`observation_id` 与桌面统一为 `obs_` 加 8 位 Base64URL,原样传回,不自行生成。`query` 可为整段子串或1–20项字符串数组,不区分大小写;数组任一项匹配即可,正文与控件遵循同一规则。每项非空且最多200字符,数组总长最多2000字符。查询另附未过滤的短摘要 `page_summary`。返回 `scan`、`elements_total` 和 `elements_returned`;有更多匹配元素时,将 `next_element_offset` 作为 `element_offset`,沿用相同查询继续。续页重新扫描当前页面并签发新引用,动态页面可能改变顺序。正文长文本可用 `browser_read` 的快照分页。结果去重并保持原预算,零结果仅表示本次已加载正文与控件扫描未匹配。链接的 `target` 是 DOM 声明,不是实际打开事件。引用按会话与文档版本绑定,最长有效 60 秒,动作和导航后失效。截图需显式请求,通过原生 MCP 图片块返回。具体预算与恢复语义见 [执行契约](architecture.md)。 +一次观察包括页面可见文本、控件和链接。观察会优先返回有语义的控件,也可以用 StaticText 引用定位文字、用指针目标定位未命名的可见图标。后续动作应原样传回 `observation_id`(`obs_` 加 8 位 Base64URL)。引用绑定到会话和文档版本,最长有效 60 秒,执行动作或导航后需要刷新。 + +`query` 接受一个非空字符串或 1–20 个非空字符串。正文与控件都按忽略大小写的子串匹配,数组中命中任一项即可。每项最多 200 字符,总长最多 2,000 字符。`page_summary` 提供未过滤的短摘要,`scan`、`elements_total` 和 `elements_returned` 说明扫描范围。还想看后续匹配控件时,用同一查询,把 `next_element_offset` 传入 `element_offset`。续页会重新扫描当前页面并签发引用,动态页面上的顺序可能变化。读取长正文可用 `browser_read`。 + +零个匹配表示本次扫描在已加载内容中没有找到结果。链接的 `target` 来自页面声明,实际新标签见回执中的 `opened_tabs`。需要截图时,在观察请求中明确开启,MCP 会返回图片块。[执行契约](architecture.md) + +点击、按键和悬停由扩展通过 Chrome debugger 执行。原生动作会先滚动并核对目标。填充使用浏览器文本输入,原生下拉框使用 DOM 语义事件。`scroll` 改变最近可滚动容器或页面的 DOM 偏移,回执返回实际移动量。Document 引用可用于按键和滚动,并保留当前键盘焦点。指针准备保持原焦点,按元素引用发送按键时才定位焦点。 -扩展通过固定 Chrome debugger 通道执行授权的操作。点击、按键和悬停使用 CDP Input;滚动直接修改最近可滚动容器或页面的 DOM 偏移并返回实际 delta,不发送 wheel 事件;填充使用浏览器文本输入,原生 select 使用 DOM 语义事件。原始 CDP 不对 Agent 开放。代码模式的 `page.evaluate` 在任务页执行 JavaScript,具有该页登录用户权限,固定观察中的密码过滤不能约束脚本读取。只读、错误目标类型和当前覆盖层在无副作用预检中拒绝并保留任务页;嵌套滚动容器裁剪允许滚动显露后再核对命中。Document 引用允许按键与滚动,保留当前键盘焦点。指针准备不提前 focus;元素按键才定位焦点。原生动作已自动滚动并检查目标,不必先用 evaluate 模拟滚动或点击。页面可拒绝操作,执行回执不能代替实际业务效果确认;点击成功也不表示已导航。所有工具及代码中的 `page` 固定操作当前任务页,链接产生的新标签不会自动接管;访问已观察链接可将其 URL 传给 `browser_open` 或 `page.goto`。动作回执及后续观察通过 `opened_tabs` 返回输入期间确认由任务页打开的最多三个子标签,含标签 ID 及可得的标题和 HTTP(S) 地址。已登记的子标签可在输入投递结束后 5 秒内补录首次 HTTP(S) 地址和对应标题,后续导航不会替换该地址。地址超长或回包预算不足时只返回标签 ID 和 `url_omitted: true`。可用 `browser_open` 在任务页打开完整地址,子页中的脚本或 POST 状态仅存在于原标签。批量操作与自定义数据提取可用 `browser_exec`。 +发现目标只读、类型不匹配或被覆盖时,扩展会在预检中拒绝并保留任务页。若是嵌套容器裁剪,扩展可以尝试滚动到可见位置后再次检查。收到执行回执后,使用新观察核对站点是否完成了预期操作或导航。 + +所有工具和代码里的 `page` 都指向当前任务页。`opened_tabs` 最多返回三个由这次输入打开的子标签,包含 ID 和可取得的标题及 HTTP(S) 地址。登记后 5 秒内可以补录第一个 HTTP(S) 地址,此后保留首次记录。地址太长或超出回包预算时,回执提供 ID 和 `url_omitted: true`。要继续访问链接,可以把完整地址交给 `browser_open` 或 `page.goto`。子页的脚本和 POST 状态留在原标签中。 + +批量操作或提取数据时可以使用 `browser_exec`。如调用 `page.evaluate`,JavaScript 会在任务页中按当前网站用户的权限执行,可以读取页面开放给脚本的数据,包括普通观察会过滤的内容。 ## 连接与本机控制 扩展在连接握手中上报浏览器声明的平台标签与扩展版本,并在可得时上报浏览器品牌、浏览器主版本、宿主系统和平台架构。macOS 和 Android 仅在浏览器提供可用的宿主版本时上报该值。设备名可由用户填写为 Profile 标签,宿主主机名与运行用户名由原生客户端上报。Server 保存最近一次成功连接的上报信息,更新扩展后成功重连即可刷新详情。 -后台通过 WebSocket 心跳确认连接,并通过 Chrome alarms 恢复被意外终止的 worker。恢复沿用同一设备身份与暂停状态,不要求打开弹窗。浏览器完全退出或整机睡眠时无法保持在线,纯扩展不能自行冷启动浏览器或唤醒整机。 +后台通过 WebSocket 心跳确认在线。只要浏览器还在运行,Chrome alarms 就可以重新唤起被终止的 worker,并使用原来的设备身份和暂停状态。退出浏览器或整机进入睡眠后,设备会离线。 -工具栏弹窗显示当前浏览器和连接状态,提供暂停、恢复访问和停止当前任务。连接标签页用于首次或重新绑定;绑定后,通过工具栏的「管理连接」在同一页查看 Server 地址、修改浏览器名称、查看诊断或解除绑定。暂停持久保存,自动重连不解除暂停;恢复只能由本机操作者执行。停止清理当前任务,不解除长期绑定;解除绑定则移除本机凭据并通知 Server 撤销。 +工具栏弹窗显示浏览器和当前连接状态,可以暂停访问、恢复访问或停止任务。暂停由本机用户解除,重连时继续保留。停止任务会清理任务标签,设备继续连接。需要改名、查看 Server 地址、排障或解除绑定时,从工具栏打开「管理连接」。解除绑定会删除本机凭据,并通知 Server 撤销设备。 -连接只读诊断包含启动、确认心跳、关闭时间和关闭码,不包含凭据。已配置、已连接与已暂停是不同状态,配置存在不表示浏览器正在在线。 +遇到连接问题时,先在弹窗检查在线与暂停状态,再到「管理连接」查看启动时间、最近确认的心跳、关闭时间和关闭码。 ## 限制 -- 仅支持 HTTP(S) 页面,不能导航浏览器内部页面。 -- 下拉选择使用 DOM 语义事件;密码管理器、原生对话框、验证码和多因素验证可能需要用户操作。 +- 支持 HTTP(S) 任务页面。 +- 密码管理器、原生对话框、验证码和多因素验证可能需要用户操作。 - 网站登录、浏览器调试提示、跨进程 iframe 和各站点后台行为受浏览器与站点实现约束。 -- 自动化 API 替身测试不能证明所有浏览器版本和网站行为;涉及新场景时,应使用自有测试页面核对实际效果。 +- 接入新场景时,可以先用自有页面在目标浏览器中验证。 ## 编程执行与按需读取 公开工具增加 `browser_read`、`browser_wait` 和 `browser_exec`。`browser_act` 增加 `press`、`select`、`scroll`、`hover`;引用的单次使用和60秒期限保持原契约。代码中的 locator 每步重新解析唯一 CSS 目标,省去每字段一次整页观察及固定等待;不接受模糊多目标选择。 -`browser_exec` 的 `code` 是 async JavaScript 函数体,可使用 `page`、`state`、`console` 和 `return`。代码在 QuickJS WASM 中运行,无 Node、文件、终端或直接网络接口;`page.evaluate` 是显式的页面内代码通道,网站网络请求仍由浏览器执行。每段创建新的执行上下文,只有 JSON `state` 跨调用保存,局部变量和函数不跨调用延续。状态归当前会话所有,关闭、断连、暂停或 Server 重启后清除;状态不是持久业务数据库。 +`browser_exec` 接收异步 JavaScript 函数体,可使用 `page`、`state`、`console` 和 `return`。外层代码运行在 QuickJS WASM 中,网页脚本通过 `page.evaluate` 在任务页执行。每次调用都有独立的执行上下文,只有 JSON `state` 在同一会话的调用间保存。关闭、断连、暂停或 Server 重启后会清除状态。 ```javascript // browser_exec.code;重复调用使用同一个 session_id。 @@ -91,9 +107,15 @@ return { completed: state.completed }; 代码默认限20秒,`timeout_ms` 可设至120秒;`wait_seconds` 默认15秒,等待返回后原操作可能仍在执行,应使用同一 `operation_id` 查询 `operation_status`,或 `operation_cancel` 取消。每段最多1000个浏览器步骤,QuickJS内存16MiB,连续纯计算有中断限额。日志最多100条/12000字符,状态和内部序列化结果最多1MiB;最终 value 超24000字符返回明确截断预览,建议在脚本内汇总或用快照分页。完整 JSON state 在正常序列化后保存;取消、超时或执行失败不能保证 state 包含最后一步进度,恢复应核对回执与实际页面。 -每个浏览器调用都必须 `await`,不支持返回后继续后台写入。批次不是事务;第八步失败不会撤销前七步。回执附带 `steps_completed`,失败时还保留有界 `failed_step`(`operation_id`、`method`、`status`、`error`),外层和每个步骤分别记录操作ID。首次执行前明确拒绝为 `refused`;已有步骤完成后明确失败为 `failed`;在途超时、断连或无确认回执仍为 `outcome_unknown`,并可按失败步骤ID核对。纯脚本异常为 `failed`,没有在途未知步骤的明确取消为 `cancelled`。完成步数不能证明失败步骤无副作用,输入准备中的滚动与 focus 也可能触发页面事件。不重放整段;执行期间同会话独占,取消会终止运行并取消在途浏览器步骤。当前不提供业务事实 `expect` 与人工接管恢复协议。 +在脚本中逐个 `await` 浏览器方法。中途失败时,先查看 `steps_completed` 与 `failed_step`。后者包含步骤 ID、方法、状态及错误信息。外层操作和页面步骤分别有自己的操作 ID。已完成的动作仍然生效,结果未知的步骤也可能已经触发滚动、聚焦或输入。检查原步骤的操作状态和实际页面后,再继续剩余步骤。 + +首步执行前明确拒绝时返回 `refused`。已有步骤完成后出错,或遇到纯脚本异常,则返回 `failed`。在途步骤超时、断连或缺少确认回执时报告 `outcome_unknown`。明确取消且没有未知步骤时返回 `cancelled`。脚本执行期间独占该会话,取消会终止脚本并请求取消在途步骤。 + +`browser_read` 在会话中缓存一份快照,最多 100 万字符。新快照替换旧快照。续页传回当前 `snapshot_id`(`snap_` 加 8 位 Base64URL)和 `offset`,默认沿用快照格式。文本按字符分页,表格按行分页,每页最多 200 行,保留合并单元格。响应标明来源 URL、缓存与截断情况。快照范围是已加载的主文档或创建时明确选定的同源 frame,适合读取数据。输入时要获取当前文档的操作引用。 + +等待条件最多 20 秒。提交页面脚本前的校验失败会保留任务页。脚本提交后如果执行或结果处理失败,扩展会等待清理并报告结果未知。对同一任务页发起的关闭、取消和停止会等待同一次清理。清理失败时,先按 `recovery` 提示停止任务以重试,诊断见 `cause` 和 `cleanup_error`。新任务会等待清理完成,迟到的旧会话清理只处理原任务页。 -`browser_read` 缓存单份当前会话快照,最多100万字符;`snapshot_id` 为 `snap_` 加 8 位 Base64URL,新快照替换旧快照,旧 ID 和其他会话的 ID 不能用于读取当前快照。续页只需传 snapshot_id 与 offset;省略 mode 时沿用快照格式。容器和 frame 在建立快照时固定。文本按字符分页,表格按行分页,每页最多200行,并保留单元格行列合并信息。响应标记来源URL、缓存与截断,覆盖范围为已加载的主文档或显式同源 frame,不包含未加载分页或虚拟列表外的数据。缓存只供阅读,不授予动作权限。等待上限20秒,不自动重新提交动作;页面脚本一旦提交,执行或结果处理失败都可能已有副作用,会等待任务页清理并报告结果未知;提交前明确校验失败保留任务页。清理只执行一次,重复关闭、取消或停止等待相同结果;清理失败保留原始 `cause`、`cleanup_error` 与 `recovery`,不会宣称任务页已释放,需先停止任务重试清理。新任务页等待进行中的清理,旧会话迟到的清理不影响新页。控制会话仍活跃但任务页已缺失返回 `task_tab_missing`,此时使用 `browser_open`;控制会话真实停止、过期或断连仍遵循原会话恢复契约。 +若控制会话仍有效但任务页已丢失,返回 `task_tab_missing`,使用 `browser_open` 创建任务页。会话已停止、到期或断连时,需要按会话恢复流程新建会话。 ### 原生长按与等待 diff --git a/docs/changelog.md b/docs/changelog.md index d2eadf9..bd01fbf 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,10 +1,18 @@ # 变更记录 -此文件记录产品行为变更;部署日志、私人任务结果与模型验收流水不作为版本记录。 +## 0.5.0 — 正式发布(2026-11-20) -## 未发布 +### Windows 客户端 -- 新增 Windows 10/11 x64 原生客户端预览,支持截图、前台键鼠、Shell 和 UTF-8 文件读写。可通过浏览器授权或已有电脑设备的 Device Token 接入现有 Server。[下载与安装](windows-client.md) +Windows 10/11 x64 现在可以接入 aBridge。客户端支持截图、前台键鼠、Shell 和 UTF-8 文件读写。你可以从客户端发起浏览器授权,也可以在管理台的「添加设备 → Windows」生成 Device Token,再填入客户端。 + +GitHub Release 提供未签名的便携 ZIP 和 SHA-256 校验文件。[Windows 安装指南](windows-client.md) + +### 升级 + +- 如果已安装 **Windows 预览版**,先从托盘退出旧客户端,再解压新版。沿用原来的状态目录即可保留绑定和设置。[更新步骤](windows-client.md#更新、退出和卸载) +- 从 0.4.23 升级 **Server** 时,继续使用原来的数据目录或 Docker 卷。两个版本都使用 schema 6。 +- **Linux** 的 amd64 和 arm64 下载包可以用同一份 `SHA256SUMS` 校验。 ## 0.4.23 — 正式发布(2026-11-19) @@ -14,7 +22,7 @@ ## 0.4.22 — 正式发布(2026-11-19) - Android 正式版支持绑定 HTTP 服务器。界面提示 Device Key 与操作数据会明文传输,并要求用户确认当前地址后才发起连接。更换地址需重新确认。 -- 推荐继续使用 HTTPS。通过 HTTPS 绑定的设备不会自动回退到 HTTP。 +- 已通过 HTTPS 绑定的设备会继续使用 HTTPS。 ## 0.4.21 — 正式发布(2026-11-19) @@ -177,4 +185,4 @@ - 区分闲置到期、停止、连接中断和服务重启,结果未知的动作不自动重放。 - Host/Origin 使用明确白名单;首次管理账户的浏览器配置仅限回环空数据库与一次性令牌。 -本版本的构建、协议与打包检查不代表实际 App 系统权限、桌面输入或既有线上服务已完成替换验收。 +该版本完成了构建、协议和打包检查。实际 App 权限、桌面输入及线上服务替换仍需在部署环境中验证。 diff --git a/docs/chrome-store.md b/docs/chrome-store.md index 53b47fe..7d046d5 100644 --- a/docs/chrome-store.md +++ b/docs/chrome-store.md @@ -4,9 +4,9 @@ 执行 `npm run build && npm run package && npm run package:check`,上传 `dist/releases/abridge-browser-.zip`。ZIP 根目录包含生成版本的 manifest 与已构建 JavaScript;不要上传源码目录、Server tarball 或 App。 -商店 ZIP 的 manifest 故意不带 `key`;源码和 `dist/browser/` 中的加载开发版仍保留开发公钥及其身份,不能直接把该目录压缩上传商店。打包检查同时核对商店 manifest 无 `key` 且版本与根 `package.json` 相同。 +上传商店时使用打包工具生成的 ZIP。打包工具会移除 manifest 的 `key` 并核对版本。用 `dist/browser/` 本地调试时,manifest 保留开发公钥,以便继续使用同一扩展 ID。 -首次上传可先保存草稿。商店分配的 Item ID 与开发版当前 ID 不应假定相同;需要统一开发 ID 时,在草稿的 Package 页面查看商店公钥,再按 [Chrome 官方 key 流程](https://developer.chrome.com/docs/extensions/reference/manifest/key)回填开发 manifest。扩展公钥不是秘密;商店 ID 变化不保证保留另一扩展 ID 的本地绑定。 +首次上传可先保存草稿,在 Package 页查看商店分配的 ID 和公钥。想让开发版使用同一个 ID,可以把公钥填回开发 manifest。若切换到另一个扩展 ID,请检查本地绑定并按需重新连接。[Chrome 的 key 配置说明](https://developer.chrome.com/docs/extensions/reference/manifest/key) ## 商店介绍草稿 @@ -26,18 +26,18 @@ You must run or have access to an aBridge Server and configure an MCP client wit ## Privacy practices 填写依据 -商店字段与 [隐私政策](privacy.md) 必须一致。扩展会将授权任务页的数据交给用户配置的 Server 和 Agent,不能仅因没有开发者运营的收集端就声明“不处理用户数据”。Chrome 要求准确披露收集、使用及共享方,并在指定字段提供可访问的政策链接。[官方隐私政策要求](https://developer.chrome.com/docs/webstore/program-policies/privacy) +填写表单时,按实际处理的数据逐项说明用途和接收方。扩展会把授权任务页的数据交给用户配置的 Server 和 Agent。将政策链接填入表单对应字段,确保内容与实际版本一致。[aBridge 隐私政策](privacy.md) · [商店隐私政策要求](https://developer.chrome.com/docs/webstore/program-policies/privacy) 建议根据提交时的实际版本逐项核对数据类别: -| 类别 | 当前处理情况 | -| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| Website content | 页面可见正文、表单观察、控件及按需截图,可能含个人或敏感内容 | -| User activity | 用户授权的导航、点击、填充及执行结果;不是后台收集全部浏览记录 | -| Authentication information | 设备 Key 的本地保存和认证传输;绑定时通过指定 Server 的浏览器授权页确认,扩展不读取管理账户密码。Agent 提供的填充内容也可能敏感 | -| Web history / personal identifiers | 任务 URL、标题、账户名或页面内容可能落入这些类别;按实际处理定义选择,不能把“不读取全局历史数据库”等同“不涉及任何 URL 或身份数据” | +| 类别 | 当前处理情况 | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| Website content | 页面可见正文、表单观察、控件及按需截图,可能含个人或敏感内容 | +| User activity | 已授权任务的导航、点击、填充及执行结果 | +| Authentication information | 设备 Key 的本地保存和认证传输;绑定时通过指定 Server 的浏览器授权页确认,扩展不读取管理账户密码。Agent 提供的填充内容也可能敏感 | +| Web history / personal identifiers | 按类别定义核对所处理的任务 URL、标题、账户名和页面内容 | -最后的认证声明应由发布者按事实核对;上表不是对审核结论的保证。 +提交前由发布者按当前版本核对认证声明。 权限理由草稿: @@ -57,7 +57,7 @@ You must run or have access to an aBridge Server and configure an MCP client wit 当前扩展将观察、输入、读取、等待和任务页执行通道打包在本地 JavaScript 内。Server 提交已定义工具及参数;代码模式在 Server 的 QuickJS 引擎组织流程,并可通过 `page.evaluate` 在自有任务页执行 JavaScript。原始 CDP 不对 Agent 开放,也没有专用 Cookie 导出工具;页面脚本可读取站点向页面开放的数据,不能把固定观察的敏感字段过滤视为脚本限制。浏览器执行通过 `chrome.debugger` 完成,生命周期和权限以[浏览器客户端](browser-profile-design.md)为准。 -MV3 对远程执行有严格要求,Debugger API 有特定例外;例外不豁免隐私、用途或可审查性要求。提交时应准确解释固定实现和有限参数,不能据此宣称“一定通过审核”。[官方 MV3 要求](https://developer.chrome.com/docs/webstore/program-policies/mv3-requirements) +提交时说明扩展内置了哪些操作、Server 传入哪些参数,以及页面脚本在哪里执行。对照 MV3 的 Debugger API 条款及隐私、用途和可审查性要求。[官方 MV3 要求](https://developer.chrome.com/docs/webstore/program-policies/mv3-requirements) ## 素材 @@ -76,7 +76,7 @@ MV3 对远程执行有严格要求,Debugger API 有特定例外;例外不豁 5. 按 `tools/fixtures/README.md` 启动自有表单目标,用浏览器会话打开 `/seed`,再在另一个任务会话中观察登录态、填入文字并提交。关闭会话,检查任务页清理。 6. 在工具栏暂停访问,确认 Agent 无法继续;恢复访问后使用新会话。测试后撤销临时 Agent Key 并删除本次临时状态。 -本机步骤要求审核环境能够运行 Node 和自有 Server,并不保证审核人员一定采用此方式。若商店要求在线测试,需另行提供受限的 HTTPS 演示 Server、独立可撤销测试身份及完整说明;没有准备演示服务时,不得填写一个实际不可访问的 localhost 地址当作在线测试账号。 +以上流程在审核人员自己的机器上启动 Server。如果商店要求在线测试,提供审核人员可访问的 HTTPS 演示 Server、独立的可撤销测试账户和操作说明。 ## 更新 diff --git a/docs/deployment.md b/docs/deployment.md index 9533e4c..a254874 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -2,9 +2,9 @@ ## 环境与分发 -当前为 0.4 开发候选。Server 运行环境支持 Node 22.x(最低 22.13.0)、23.x(最低 23.4.0)及 24 以上版本;源码构建需要 npm。两个最低补丁版本均来自内置 `node:sqlite` 取消实验启动参数的版本,22.0–22.12 和 23.0–23.3 不在支持范围内。[Node 22 官方说明](https://nodejs.org/en/blog/release/v22.13.0) · [Node 23 官方说明](https://nodejs.org/en/blog/release/v23.4.0) macOS App 目标为 Apple Silicon、macOS 14+,原生编译另需 Xcode Command Line Tools。Server 不需要桌面 SDK、Chrome 或图形环境。 +可以通过 GitHub Release 的 Server 包、Docker 镜像或源码运行 aBridge。直接运行 Server 需要 Node.js 22.13.0+(22.x)、23.4.0+(23.x)或 24 及以上版本。从源码构建还需要 npm。Node 版本要求来自内置的 `node:sqlite`。[Node 22 发布说明](https://nodejs.org/en/blog/release/v22.13.0) · [Node 23 发布说明](https://nodejs.org/en/blog/release/v23.4.0) -Server、管理台和扩展从同一套 TypeScript 源码构建。用户运行预构建 JavaScript,管理台作为静态资源随 Server 提供,不启动 Vite 等开发服务器。管理台脚本入口为 `apps/web/src/app/main.tsx`,样式入口为 `apps/web/src/styles/index.css`;构建分别产出 `web/app.js` 和 `web/app.css`。候选 npm 包尚未公开发布,不能把示例包名当作已可执行的公共 `npx` 入口。 +Server 包内含预构建的管理台,可以部署在无图形环境的机器上。想先用发布包跑通一次连接,可从快速开始里的命令开始。[快速开始](guide/start.md) ## 从源码运行 Server @@ -14,7 +14,7 @@ npm run build npm start -- --web ``` -`abridge` 默认等同于 `abridge serve`。每次启动只输出普通地址;`--web` 在本机浏览器打开带管理员 Token 的管理链接,终端不输出凭据。首次启动自动生成实例管理员 Token,保存在数据库旁的 `<数据库文件>.admin-token`,文件权限为 `600`,之后重启复用。也可用 `ABRIDGE_ADMIN_TOKEN` 覆盖,值须为 32–512 个不含空白的可打印 ASCII 字符;环境变量覆盖不会改写已保存的 Token。 +`abridge` 默认启动 Server,等同于 `abridge serve`。终端显示访问地址,`--web` 把带凭据的管理员链接直接交给本机浏览器。首次启动会在数据库旁生成 `<数据库文件>.admin-token`(权限为 `600`),后续重启继续使用它。也可设置 `ABRIDGE_ADMIN_TOKEN`,指定 32–512 个不含空白的可打印 ASCII 字符,文件中的 Token 会原样保留。 打开管理链接后,前端立即清除 URL fragment 中的 Token,再通过 API 兑换有效期 30 天的 `HttpOnly`、`SameSite=Strict` Cookie;HTTPS 使用 `Secure`。管理员会话跨 Server 重启保留,在同一浏览器、同一 Origin 下再次访问普通地址即可恢复。退出管理员清除浏览器会话;重置 Token 会使旧 Token 和全部旧管理员会话失效。自动生成的 Token 使用以下命令重置并启动: @@ -22,9 +22,9 @@ npm start -- --web node dist/server/cli.js --reset-admin-token ``` -环境变量配置的 Token 通过修改变量并重启更换。管理链接包含实例管理员凭据,不写入终端或请求日志;也可通过已配置的管理员 Token 登录。普通用户使用不带 fragment 的地址。 +若使用环境变量配置 Token,修改变量后重启即可。请把管理员链接保存在私下,分享给普通用户时使用 Server 的访问地址。 -实例管理员独立于普通账户,进入“实例管理”即可创建用户、查看用户及其设备统计,不需要先登录普通账户。第一个用户和后续用户统一由管理员 API 创建,不提供 CLI 创建用户或公开注册入口。普通账户登录后维护自己的设备与 Agent 连接,管理员凭据不授予设备操作权限。完整接口与外部调用示例见 [Server API](https://github.com/xerrors/aBridge/blob/main/apps/server/README.md#管理员-api)。 +用管理员身份进入「实例管理」,创建用户并查看设备统计。普通用户再用自己的账户登录,管理设备和 Agent 连接。自动化建账可调用管理员 API。[Server API](https://github.com/xerrors/aBridge/blob/main/apps/server/README.md#管理员-api) ### 配置 @@ -46,16 +46,16 @@ Server 还接受 `ABRIDGE_HOST`、`ABRIDGE_PORT`、`ABRIDGE_DB`、`ABRIDGE_PUBLI ### 反向代理与网络 -跨机器连接使用 HTTPS/WSS 反向代理,或经 SSH 隧道访问回环服务。默认 Host/Origin 防护保留;反向代理明确配置外部 Origin: +跨机器连接可以用 HTTPS/WSS 反向代理,也可以通过 SSH 隧道访问回环服务。使用反向代理时,将对外地址配置为 Server 的 `public-origin`。 ```sh node dist/server/cli.js --data-dir /absolute/path/to/state \ --public-origin https://bridge.example.com ``` -Origin 必须是纯 `scheme://host[:port]`,不带路径、凭据、查询、fragment 或结尾斜杠。它也决定管理台同源检查和安全 Cookie,不依赖未受信任的转发头推断。 +地址写成 `scheme://host[:port]` 即可,例如 `https://bridge.example.com`。Server 根据这个地址检查管理台请求是否同源,并决定是否给 Cookie 设置 `Secure`。 -仅在需要额外地址时使用 `--allowed-hosts bridge.example.com:8443` 或 `--allowed-origins https://mcp-client.example.com`。Origin 带协议,Host 不带协议;额外 Origin 不放宽管理 API 同源要求。代理须支持 WebSocket,并转发需要的 Host 与认证头。回环 HTTP 不直接作为公网入口。 +如果还要允许其他 Host 或 MCP Origin,可设置 `--allowed-hosts bridge.example.com:8443` 或 `--allowed-origins https://mcp-client.example.com`。管理 API 仍按 `public-origin` 检查同源。代理需要支持 WebSocket,并转发 Host 与认证头。 也可由操作者使用已有 SSH 连接转发端口: @@ -67,7 +67,7 @@ ssh -N -L 127.0.0.1:8765:127.0.0.1:8765 bridge-host ## 本地 Server 分发包 -构建输出按产品收拢:`dist/server/cli.js` 与同目录 `web/`、`dist/desktop/cli.js`、`dist/browser/`。Server 和 Desktop 使用各自入口,没有混合分发 CLI。 +构建后,Server 入口位于 `dist/server/cli.js`,管理台资源在同目录的 `web/`。桌面和扩展产物分别在 `dist/desktop/` 和 `dist/browser/`。 运行分发工具,在 `dist/releases/` 生成 Server tarball 与扩展 ZIP,并检查分发边界: @@ -76,13 +76,45 @@ npm run package npm run package:check ``` -分发构建包含 Server 所需的预构建 CLI、管理台,以及通过 `bundleDependencies` 随包携带的生产依赖闭包,剥离桌面 SDK。从源码安装时在本地生成的 `package-lock.json` 提取 Server 生产依赖锁,通过 `npm ci` 安装本次构建解析出的固定依赖;分发检查根据根锁核验 tarball 中的依赖路径与版本,不依赖 npm 12 已移除的 `shrinkwrap` 命令或 `npm-shrinkwrap.json` 支持。版本由根 `package.json` 生成。使用构建工具生成的本地 tarball 验证安装,再决定是否发布到 npm。 +Server 包包含预构建 CLI、管理台和生产依赖。打包时从本地 `package-lock.json` 提取 Server 的依赖锁,用 `npm ci` 安装并通过 `bundleDependencies` 随包分发。验包会按照根锁比对 tarball 中的依赖路径和版本。软件版本来自根 `package.json`。 -`npm exec --package <本地tgz路径> -- abridge --web` 的 package 参数必须指向实际生成的文件,不能替换为尚未发布的候选包名。npx/npm exec 的临时包目录仅用于运行程序;数据库仍由 `--data-dir` 或 `--db` 指向持久位置。 +用 `npm exec --package <本地tgz路径> -- abridge --web` 试运行本地包。数据库继续由 `--data-dir` 或 `--db` 指向持久目录。 + +## Docker 镜像 + +Server 和管理台随 `ghcr.io/xerrors/abridge` 一起提供,支持 `linux/amd64` 和 `linux/arm64`。示例固定使用已发布的 `0.4.23`,`latest` 随正式镜像更新。[GHCR 镜像列表](https://github.com/xerrors/aBridge/pkgs/container/abridge) + +```sh +docker run -d --name abridge --restart unless-stopped \ + -p 127.0.0.1:8765:8765 \ + -v abridge-data:/data \ + -e ABRIDGE_PUBLIC_ORIGIN=http://127.0.0.1:8765 \ + ghcr.io/xerrors/abridge:0.4.23 +``` + +将 `ABRIDGE_PUBLIC_ORIGIN` 换成实际访问地址;使用 HTTPS 反向代理时填外部 HTTPS Origin。远程连接推荐 HTTPS/WSS;公网 HTTP 需要客户端明确确认。命名卷保存数据库和管理员凭据,更新镜像时复用同一数据卷;不要同时启动两个容器使用同一个卷。 + +```sh +curl -f http://127.0.0.1:8765/health +docker stats --no-stream abridge +docker logs --tail 30 abridge +``` + +输出管理员链接(包含私密凭据,不转发): + +```sh +docker exec abridge node -e ' +const fs = require("node:fs"); +const token = process.env.ABRIDGE_ADMIN_TOKEN || fs.readFileSync("/data/server.db.admin-token", "utf8").trim(); +console.log(process.env.ABRIDGE_PUBLIC_ORIGIN + "/#admin_token=" + encodeURIComponent(token)); +' +``` + +更新时先备份数据,再停止并删除旧容器。用新镜像和原来的端口、环境变量、数据卷重建容器,继续使用 `abridge-data` 中的数据库和凭据。 ## macOS App -在完整源码目录安装: +macOS App 支持 Apple Silicon 和 macOS 14 及以上版本。可从 Release 下载 ZIP,解压后将 App 放进 Applications。若要从源码构建,先安装 Xcode Command Line Tools,再在仓库根目录运行以下命令。 ```sh npm install @@ -91,7 +123,7 @@ npm run desktop:install open "$HOME/Applications/aBridge.app" ``` -App 使用 Swift 原生客户端和原生更新器,直接加载锁定的 Cua Driver 0.47.8 dylib。构建时从锁文件固定的 SDK 包提取 arm64 原生库并签名,分发不包含 Node、JavaScript 或 npm 依赖树。安装器将完整 App 复制到目标目录;运行不依赖源码目录、开发工具或 npm 缓存。Server 分发不包含桌面 SDK。 +Swift 客户端、更新器和 Cua Driver 0.47.8 随 App 一起安装。构建从锁定的 SDK 包提取并签名 arm64 原生库,安装器再把完整 App 复制到目标目录。 | 内容 | 默认位置 | | -------------------- | --------------------------------------------------------------- | @@ -109,9 +141,9 @@ node --import tsx tools/build-native.ts \ --output /absolute/path/to/aBridge.app ``` -使用 `--signing-identity` 或 `ABRIDGE_SIGNING_IDENTITY` 指定本机已有证书;默认 ad hoc 签名。原生代码或签名变化后,macOS 可能要求重新授予屏幕录制或辅助功能权限。应用内更新使用 GitHub Latest 正式 Release;候选构建成功不能代表真实安装和系统权限验收已通过。 +构建默认使用 ad hoc 签名。可用 `--signing-identity` 或 `ABRIDGE_SIGNING_IDENTITY` 指定本机证书。更换二进制或签名后,请在实际安装的 App 中检查屏幕录制和辅助功能权限。 -从 0.4.15 及更早版本升级时,旧更新器要求 Node 运行时,不能安装原生包。请退出旧版 App,解压 Release ZIP 后替换原位置的 `aBridge.app`,保留 `~/Library/Application Support/aBridge` 中的绑定、设备身份和暂停设置。原生版本后续可继续使用应用内更新。 +从 0.4.15 及更早版本升级时,请退出旧版 App,解压 Release ZIP 并替换原位置的 `aBridge.app`。保留 `~/Library/Application Support/aBridge`,原来的绑定、身份和暂停设置随之保留。装好原生版本后,可继续通过应用内更新升级。 ### 绑定与控制 @@ -120,11 +152,11 @@ node --import tsx tools/build-native.ts \ 3. 为实际安装的 App 授予所需系统权限。仅 Shell/文件操作不需要桌面权限。 4. 创建 Agent 连接,选择指定设备或全部设备(包含以后新增设备),按设备设置能力;默认持续有效,也可指定到期日期。将生成的 Agent Key 配入 MCP 客户端。 -连接范围、能力和期限可以编辑,修改策略不更换现有 Key。密钥轮换是单独操作,旧 Key 立即失效。连接预览显示已授权设备数量和每台设备的实际可用状态;设备在线不代表已加入该连接。 +连接范围、能力和期限可以随时调整,现有 Key 继续有效。轮换密钥时,旧 Key 会立即失效。在连接预览中可以看到该 Agent 能使用哪些设备,以及每台设备的状态。 -菜单与设置提供暂停/恢复、停止、能力开关、重连、环境检查和日志。恢复只能由本机操作者执行;重连不解除暂停。环境检查只刷新原生运行时、驱动与权限状态,不自动下载依赖或重置授权。运行文件缺失时,退出 App 后从完整源码目录重新安装。 +在菜单或设置中可以暂停、停止任务、重连和查看日志。暂停状态会在重连后保留,恢复访问由本机用户操作。「环境检查」可刷新运行时、驱动和权限状态。缺少运行文件时,退出 App 并重新安装完整应用。 -设置的“系统权限”提供当前运行 App 的可拖拽图标,以及“在 Finder 中显示”入口。先打开对应系统权限设置,将图标拖入支持添加应用的权限列表,或使用列表的添加按钮选择同一个 App,再由用户开启权限;拖拽本身不等于授权。权限状态仍以系统检测为准。[Apple 辅助功能说明](https://support.apple.com/guide/mac-help/allow-accessibility-apps-to-access-your-mac-mh43185/mac) · [Apple 屏幕录制说明](https://support.apple.com/guide/mac-help/control-access-screen-system-audio-recording-mchld6aa7d23/mac) +在「系统权限」中可以拖动 App 图标,也可以选择「在 Finder 中显示」。将正在运行的 App 添加到对应的 macOS 权限列表,然后打开它的权限开关。[Apple 辅助功能说明](https://support.apple.com/guide/mac-help/allow-accessibility-apps-to-access-your-mac-mh43185/mac) · [Apple 屏幕录制说明](https://support.apple.com/guide/mac-help/control-access-screen-system-audio-recording-mchld6aa7d23/mac) 可使用已安装运行时的 CLI 读取状态,或从构建目录诊断: @@ -133,17 +165,27 @@ dist/desktop/aBridge.app/Contents/MacOS/abridge-desktop status dist/desktop/aBridge.app/Contents/MacOS/abridge-desktop diagnose ``` -自定义状态目录使用 `--state-dir`,日志相应位于 `/logs/client.log`。终端诊断的权限责任链不等于 App 的责任链;实际窗口截图和输入需在 App 环境中用自有目标核对。 +自定义状态目录使用 `--state-dir`,日志位于 `/logs/client.log`。检查屏幕录制及辅助功能时,请打开实际安装的 App,用自己的窗口验证截图和输入。 + +### 应用内更新 + +在 macOS 菜单选择“检查更新…”,或在设置的“软件更新”中检查。发现正式新版后,依次点击“下载更新”和“安装并重启”。下载期间可以继续使用;安装会结束当前执行,保留设备绑定、能力开关、暂停状态和数据目录。应用必须位于可写的本机目录;从磁盘镜像或 App Translocation 启动时先移入 Applications。 + +更新器读取 `xerrors/aBridge` 的 GitHub Latest 正式 Release,优先选择公证的 Apple Silicon ZIP,否则选择现有 unsigned 包。下载校验 GitHub 提供的 SHA-256 和大小,再核对 Bundle ID、版本与代码签名;已使用团队签名的应用拒绝换成其他团队或 ad hoc 包。应用在原安装路径替换,收到新版 App 及原生客户端的启动确认后才清理旧版;启动失败恢复并重新打开旧版,错误写入数据目录的 `logs/update-error.log` 并在设置显示。 + +更新沿用 Bundle ID、安装路径和用户状态。使用 ad hoc 签名的版本更新后,macOS 可能要求重新授予录屏和辅助功能权限。使用同一 Developer ID 签名可以延续签名身份。更新后从 Finder 打开 App 时,仍会使用此前设置的数据目录。 + +开发验证:`npm run check`;macOS 可另运行 `npm run test:desktop:update:live`,使用独立临时 App 验证真实下载、原路径替换、启动确认与失败回滚,不替换已安装客户端。 ## Windows PC 客户端 -Windows 10/11 x64 预览版提供截图、前台键鼠、Shell 和 UTF-8 文件读写。通过 GitHub Actions 获取未签名便携 ZIP,或在 Windows 上从源码构建。完整解压后启动 `aBridge.exe`,填写客户端能访问的 Server 地址并完成浏览器授权。[下载、安装与绑定](windows-client.md) +Windows 10/11 x64 预览版提供截图、前台键鼠、Shell 和 UTF-8 文件读写。下载未签名便携 ZIP,完整解压后启动 `aBridge.exe`,填写客户端能访问的 Server 地址并完成浏览器授权。[下载、安装与绑定](windows-client.md) 桌面操作需要已解锁的交互式桌面。客户端通过「本机能力」控制开放的能力,通过设置窗或托盘暂停、停止任务和退出。更新前退出旧客户端,解压新包并沿用原状态目录,默认位于 `%LOCALAPPDATA%\aBridge`。[更新、退出和卸载](windows-client.md#更新、退出和卸载) ## Linux CLI -Linux 客户端是独立 Rust 可执行文件,只提供 `shell/files`,使用现有设备协议直接连接 Server。安装后不需要 Node、浏览器或图形环境;需要系统 `/bin/sh` 和可信 CA 证书。设备以 `computer` 类型和 `linux` 平台显示,能力仍受设备授权、Agent 策略和本机开关共同限制。 +Linux CLI 适合在开发机或服务器上执行 Shell 和文件任务。客户端是独立的 Rust 可执行文件,运行需要系统 `/bin/sh` 和可信 CA 证书,可在无图形环境中使用。连接后,管理台会显示一台 Linux 电脑。可用能力由设备授权、Agent 策略和本机开关共同决定。 在管理台创建电脑设备并取得 Device Token,解压已校验的对应架构分发包后运行: @@ -155,9 +197,9 @@ Linux 客户端是独立 Rust 可执行文件,只提供 `shell/files`,使用 `setup` 隐藏输入 Token,先校验再保存。连接远程 HTTP 时,终端先显示 Origin 并要求确认,再提示输入 Token。无人值守绑定使用 `setup --stdin` 从私有输入读取绑定 JSON,远程 HTTP 须提供完全匹配的 `http_confirmed_origin`。 -默认安装当前普通用户的 systemd 服务,可执行文件复制到 `~/.local/lib/abridge-client/abridge-client`。`service install --linger` 额外请求开启用户 linger,使退出登录后继续运行并在开机时启动;系统可能要求管理员预先授权,客户端不自动调用 sudo。日志使用 `logs` 或 `journalctl --user -u abridge-client.service` 查看。没有 systemd 时用 `run` 交给现有进程管理器。 +默认安装当前账户的 systemd 服务,程序复制到 `~/.local/lib/abridge-client/abridge-client`。如果希望开机启动、退出登录后仍运行,可以用 `service install --linger`,按系统提示处理权限。日志可以用 `logs` 或 `journalctl --user -u abridge-client.service` 查看。使用其他进程管理器时,执行 `run` 在前台运行。 -暂停、能力开关和绑定保存在用户私有状态目录;可用 `--state-dir` 指定。服务重启和重连不解除暂停,未知结果操作不重放。更新时停止任务,用新版二进制执行 `service install` 并保留相同状态目录;`service uninstall` 移除服务但保留用户状态。 +暂停、能力开关和绑定保存在用户私有状态目录,重启或重连后继续生效。更新时先停止任务,再用新版二进制执行 `service install`。自定义状态目录的用户可通过 `--state-dir` 继续使用原目录。`service uninstall` 会移除服务并保留状态目录。遇到结果未知的操作时,先检查原操作状态。 源码构建使用 `npm run linux:build`,Rust 检查使用 `npm run linux:check`,Linux 候选包使用 `npm run package:linux`。分发包含单个可执行文件、说明和许可证,并输出 SHA-256、实际体积报告;构建强制执行 15 MiB 二进制和 5 MiB 下载包预算。原生 Linux amd64/arm64 CI 另验证协议和真实 systemd 生命周期。完整命令、依赖和目标平台说明见 [Linux 客户端](https://github.com/xerrors/aBridge/blob/main/apps/linux-client/README.md)。 @@ -167,23 +209,23 @@ Linux 客户端是独立 Rust 可执行文件,只提供 `shell/files`,使用 npm run build ``` -在 `chrome://extensions` 开启开发者模式,加载 `dist/browser/`,不能直接加载 `apps/browser/src/`。独立分发使用构建工具生成的扩展 ZIP,解压后加载;版本由根项目版本生成。 +在 `chrome://extensions` 开启开发者模式,选择「加载已解压的扩展程序」,再选 `dist/browser/`。也可以解压构建生成的扩展 ZIP 后按同样方式加载。扩展版本来自根 `package.json`。 点击扩展图标,选择「连接浏览器」,在打开的标签页填写 Server 地址和设备名,按表单提示确认后点击「在浏览器授权」,登录管理台并确认绑定当前 Profile。远端 Server 推荐 HTTPS/WSS;公网 HTTP/WS 需在客户端确认风险,本机回环 HTTP/WS 无需额外确认。绑定时只需允许扩展访问所填 Server 地址。 -每个扩展安装实例注册为独立浏览器设备,仅有 `browser` 能力;在管理台加入所需 Agent 连接。任务无需在 App 中选择窗口或准备浏览器连接。更新构建文件后在扩展管理页“重新加载”,再确认连接状态;绑定与暂停保留。更多约束见 [浏览器客户端](browser-profile-design.md)。 +扩展独立注册为浏览器设备。在管理台把它加入所需的 Agent 连接,并授予 `browser` 能力。更新构建文件后,在扩展管理页选择「重新加载」并确认已连接,原绑定和暂停状态会保留。[浏览器客户端](browser-profile-design.md) ## 数据与更新 -每个数据库只启动一个 Server 实例;实例锁防止同一路径被第二个服务同时持有。Server 重启会断开内存连接,设备重连后新建任务会话,不恢复未知在途动作。 +每个数据库由一个 Server 实例使用,启动时会锁定该路径。重启后设备会重新连接,任务需要新建会话。重启前结果未知的操作,可先查询状态,再检查实际结果。 -备份使用 SQLite 备份接口,或先停止服务再保留数据库及 WAL;不要只复制运行中的主数据库。凭据、日志和备份须限制访问。开发数据库必须匹配当前 schema,结构冲突直接调整开发数据,不提供兼容迁移脚本。 +在线备份请使用 SQLite 备份接口。手工复制前先停止服务,再一并保留数据库和 WAL。把凭据、日志和备份保存在访问受限的目录里。旧开发数据库应先备份,再在副本上转换到当前 schema 或重新初始化。 -更新前结束活动任务,保留需要的状态与备份。源码、候选分发包、实际安装和真实业务验证是不同范围,交付时分别说明。 +更新前结束活动任务并备份状态。更新后重新连接一台设备,用实际安装的客户端确认所需能力可用。 ## 发布与便携 App -tag 驱动的正式分发和 Windows 预览版的 CI 打包流程见[发布说明](releasing.md)。`npm run package:macos` 生成无需 Node 的便携原生 App ZIP;未配置 Developer ID 时文件名标注 unsigned。 +各客户端的 tag 分发流程见[发布说明](releasing.md)。`npm run package:macos` 生成无需 Node 的便携原生 App ZIP;未配置 Developer ID 时文件名标注 unsigned。 ## 可选 OIDC 登录与平台 MCP 委托 @@ -200,7 +242,7 @@ ABRIDGE_DELEGATION_ENABLED=true ABRIDGE_OIDC_BACKCHANNEL_ORIGIN=http://api:5050 ``` -公开 issuer 在容器内部不能直接访问时,可显式配置 `ABRIDGE_OIDC_BACKCHANNEL_ORIGIN` 为内部 HTTP(S) 纯 Origin,不含路径、结尾斜杠、凭据、查询或 fragment。只有与 issuer 相同 Origin 的服务端认证请求(discovery、token、JWKS)会改用该地址,保留原有路径和查询;浏览器链接、issuer 和令牌校验不变。不跟随重定向,不将其他域名自动映射为内部地址;未配置时保持正常公开访问。HTTP backchannel 会承载客户端秘密和令牌,仅可用于可信私有网络;它只改变内部传输,不会自动允许公开 HTTP。 +容器访问不到公开 issuer 时,可以把 `ABRIDGE_OIDC_BACKCHANNEL_ORIGIN` 设为内部 `scheme://host[:port]`。与 issuer 同源的 discovery、token 和 JWKS 请求会改用这个内部地址,并保留路径和查询参数。浏览器继续使用公开地址,issuer 和令牌校验照常进行。内部请求只访问配置的地址,遇到重定向会停止。HTTP backchannel 会传输客户端秘密和令牌,请只在可信私网内使用。 必须在提供方登记固定回调 `https://bridge.example.com/api/auth/oidc/callback`,客户端认证方式为 `client_secret_post`。登录入口 `GET /api/auth/oidc/login`,可用 `return_to=/?authorize=` 保留现有设备绑定确认流程,仅接受本地限定入口;发现状态 `GET /api/auth/oidc/config`;请求 scope 为 `openid profile`,显示名使用可选的 `name`。提供方 issuer 必须精确匹配 discovery。默认要求非回环端点使用 HTTPS。需要公网 HTTP 时,可在 Server 启动参数中显式添加 `--allow-insecure-http`,或设置 `ABRIDGE_ALLOW_INSECURE_HTTP=true`;该开关允许 HTTP 的 aBridge 对外地址和 OIDC 提供方端点,不关闭 PKCE、state、nonce、签名、issuer 或 audience 校验。仅提供部分配置时拒绝启动。关闭委托但保留 OIDC 时仍可登录管理台、使用手工 Agent Key。 @@ -213,59 +255,19 @@ ABRIDGE_ALLOW_INSECURE_HTTP=true `public-origin` 会自动允许该地址的 Host 和同源请求,无需再对它重复设置 `allowed-hosts`。提供方须登记同一地址的 `/api/auth/oidc/callback`;提供方的浏览器登录入口也必须能被用户访问。HTTP 下 Cookie 不带 `Secure`,会话、凭据和业务数据未经传输加密;保持 `HttpOnly`、`SameSite` 及其他身份校验。此开关只能由部署管理员配置,登录页无法在启动校验之前切换它。 -首次登录按 `(issuer, sub)` 创建没有本地密码的普通账户,不匹配用户名或邮箱,不接管已有账户。启用平台委托后,每个外部身份和客户端拥有一个持久“平台连接”,默认覆盖该账户的全部设备(含新设备)和设备支持的能力,仍与设备授权、本机开关及就绪状态取交集;用户可编辑连接缩小范围。可选 `ABRIDGE_OIDC_CLIENT_NAME` 设置平台显示名称,未配置时使用 client ID。该连接无 Agent Key、不支持密钥轮换;撤销后再次登录也不恢复授权。当前已撤销的平台连接直接显示在 Agent 连接列表,用户可显式点击“重新授权”(`POST /api/agent-connections/:id/reconnect`),确认允许访问全部设备(含新设备)后创建新的平台连接。已有连接的自定义策略不因升级或再次登录改变。旧授权与会话保持撤销,重复点击旧记录不能重建授权,其他用户和手工 Key 连接不能使用此入口。 +首次登录时,Server 按 `(issuer, sub)` 创建一个独立账户。用户通过身份提供方登录,可以为自己的设备配置权限。启用委托后,每个外部身份和客户端组合有一个持久的平台连接,初始范围覆盖本账户的全部设备(含新设备)和设备支持的能力。用户可以缩小范围,实际可用能力依然受设备授权、本机开关和就绪状态限制。设置 `ABRIDGE_OIDC_CLIENT_NAME` 可指定显示名称,默认使用 client ID。 -显式启用委托时,`POST /mcp` 接受同一 issuer 签发的 RS256 JWT:`sub` 为登录时的稳定主体、`aud` 精确为 `${ABRIDGE_PUBLIC_ORIGIN}/mcp`、`client_id` 为配置的 OIDC client ID、`purpose` 为 `abridge-delegation`,必须包含 `iat`、`exp`,最长 60 秒。公钥来自提供方 discovery 的 JWKS,浏览器 ID Token 不具备这些访问声明,不可用于 MCP。委托只解析已经登录建立的身份;不能通过 MCP 自动开户。个人设备列表通过 MCP `devices_list` 读取,无需为 HTTP 管理 API增加 Bearer 登录方式。 +平台通过短期令牌访问 MCP。账户可以在 Agent 连接列表中看到已撤销的平台连接。需要重新开放时,点击「重新授权」(`POST /api/agent-connections/:id/reconnect`),确认允许访问本账户全部设备(含新设备)。管理台会创建新连接,之后可以缩小范围。旧连接及其会话保持撤销。升级或再次登录会保留已有连接的自定义策略。 -浏览器会话仍由 aBridge 持有,有效期 12 小时。退出/停用提供方账户不会立即注销已有 aBridge Cookie;平台停用用户后应停止签发委托,已签发令牌最多保留 60 秒。aBridge 本地撤权即时应用于后续操作与已有控制会话,不能回滚已发生副作用。身份提供方不可用时新登录和委托验证可能失败,本地账号与 Agent Key 继续工作。密钥轮换须保留旧验证公钥至少到已签发令牌过期,JWKS 缓存也需要考虑。 +显式启用委托后,先登录管理台建立身份,再用同一 issuer 签发的 RS256 委托 JWT 调用 `POST /mcp`。令牌中的 `sub` 为登录时的主体,`aud` 为 `${ABRIDGE_PUBLIC_ORIGIN}/mcp`,`client_id` 为配置的 OIDC client ID,`purpose` 为 `abridge-delegation`。令牌须带 `iat` 和 `exp`,有效期最长 60 秒。Server 使用提供方 discovery 的 JWKS 验签。通过 MCP 的 `devices_list` 可以查看该连接获准使用的设备。 -数据库开发 schema 为 6,设备表保存最近上报的 `platform`、`version` 和可空的 `details`,操作表以内部 `key_hash` 唯一映射完整作用域去重键到短执行 ID。历史开发数据库不能直接打开;请备份并在隔离副本中明确转换或重新初始化,禁止用现有服务的数据目录试运行。更换 issuer 或 sub 会建立新身份,必须事先安排设备归属恢复,不能靠显示名自动合并。 - -### 应用内更新 - -在 macOS 菜单选择“检查更新…”,或在设置的“软件更新”中检查。发现正式新版后,依次点击“下载更新”和“安装并重启”。下载期间可以继续使用;安装会结束当前执行,保留设备绑定、能力开关、暂停状态和数据目录。应用必须位于可写的本机目录;从磁盘镜像或 App Translocation 启动时先移入 Applications。 - -更新器读取 `xerrors/aBridge` 的 GitHub Latest 正式 Release,优先选择公证的 Apple Silicon ZIP,否则选择现有 unsigned 包。下载校验 GitHub 提供的 SHA-256 和大小,再核对 Bundle ID、版本与代码签名;已使用团队签名的应用拒绝换成其他团队或 ad hoc 包。应用在原安装路径替换,收到新版 App 及原生客户端的启动确认后才清理旧版;启动失败恢复并重新打开旧版,错误写入数据目录的 `logs/update-error.log` 并在设置显示。 - -Bundle ID、安装路径和用户状态保持稳定,更新器不重置系统权限。ad hoc 签名绑定具体代码版本,更新仍可能触发录屏/辅助功能重新授权;要稳定延续签名身份,应持续使用同一 Developer ID 签名,不能靠放宽代码要求规避系统校验。自定义数据目录在更新重启后按安装路径保存在 macOS 偏好中,后续从 Finder 打开仍使用该目录。 - -开发验证:`npm run check`;macOS 可另运行 `npm run test:desktop:update:live`,使用独立临时 App 验证真实下载、原路径替换、启动确认与失败回滚,不替换已安装客户端。 - -## Docker 镜像 - -正式 Server 镜像为 `ghcr.io/xerrors/abridge`,提供 `linux/amd64` 和 `linux/arm64`。此处示例使用已发布的 `0.4.23` 标签。查看 [GHCR 镜像列表](https://github.com/xerrors/aBridge/pkgs/container/abridge) 确认可用标签;`latest` 指向最近由镜像工作流发布的正式版本。仅包含 Server 和管理台,不包含桌面 SDK。 - -```sh -docker run -d --name abridge --restart unless-stopped \ - -p 127.0.0.1:8765:8765 \ - -v abridge-data:/data \ - -e ABRIDGE_PUBLIC_ORIGIN=http://127.0.0.1:8765 \ - ghcr.io/xerrors/abridge:0.4.23 -``` - -将 `ABRIDGE_PUBLIC_ORIGIN` 换成实际访问地址;使用 HTTPS 反向代理时填外部 HTTPS Origin。远程连接推荐 HTTPS/WSS;公网 HTTP 需要客户端明确确认。命名卷保存数据库和管理员凭据,更新镜像时复用同一数据卷;不要同时启动两个容器使用同一个卷。 - -```sh -curl -f http://127.0.0.1:8765/health -docker stats --no-stream abridge -docker logs --tail 30 abridge -``` - -输出管理员链接(包含私密凭据,不转发): - -```sh -docker exec abridge node -e ' -const fs = require("node:fs"); -const token = process.env.ABRIDGE_ADMIN_TOKEN || fs.readFileSync("/data/server.db.admin-token", "utf8").trim(); -console.log(process.env.ABRIDGE_PUBLIC_ORIGIN + "/#admin_token=" + encodeURIComponent(token)); -' -``` +浏览器会话仍由 aBridge 持有,有效期 12 小时。退出/停用提供方账户不会立即注销已有 aBridge Cookie;平台停用用户后应停止签发委托,已签发令牌最多保留 60 秒。aBridge 本地撤权即时应用于后续操作与已有控制会话,不能回滚已发生副作用。身份提供方不可用时新登录和委托验证可能失败,本地账号与 Agent Key 继续工作。密钥轮换须保留旧验证公钥至少到已签发令牌过期,JWKS 缓存也需要考虑。 -更新时先备份数据,再停止并删除旧容器,使用新镜像及相同端口、环境变量和数据卷重建。`docker rm abridge` 不删除命名卷;不要执行 `docker volume rm abridge-data`。 +更换 issuer 或 sub 前,请先安排新身份下的设备归属。Server 会把新的 `(issuer, sub)` 当作独立账户。数据库和操作记录的存储方式见架构文档。[架构与执行契约](architecture.md) ## 两种设备绑定方式 -macOS、Windows 和浏览器扩展支持浏览器授权和 Device Token。浏览器授权通过登录与确认自动领取设备凭证。Windows 预览版可直接从客户端启动浏览器授权,也可填写已有的电脑设备 Device Token。其他客户端手动绑定时,在管理台「添加设备」选择对应平台,在「绑定设备」中生成仅显示一次的设备凭证。macOS 和扩展将凭证填在 Device Token 栏,点击「验证并连接」;Linux CLI 在 `setup` 提示时粘贴 Device Token;Android 在 App 中填写 Device Key 和 Server 地址后绑定。已有设备可在详情设置中重新生成凭证,旧凭证和当前设备连接会立即失效。 +macOS、Windows 和浏览器扩展支持浏览器授权和 Device Token。浏览器授权通过登录与确认自动领取设备凭证。手动绑定时,在管理台「添加设备」选择对应平台,在「绑定设备」中生成仅显示一次的设备凭证。macOS 和扩展将凭证填在 Device Token 栏,点击「验证并连接」。Windows 在「使用 Device Token」中填写凭证,点击「连接并授权」。Linux CLI 在 `setup` 提示时粘贴 Device Token。Android 在 App 中填写 Device Key 和 Server 地址后绑定。已有设备可在详情设置中重新生成凭证,旧凭证和当前设备连接会立即失效。 设备凭证只用于设备绑定。macOS、Windows、浏览器扩展和 Linux CLI 先调用 `GET /api/device` 验证设备凭证及类型,再提交本地绑定。无效、撤销或类型不匹配的凭证不替换旧绑定。凭证通过私有输入管道或扩展消息传递,不放入命令行、URL 或日志,绑定后保存在原设备凭据存储中,暂停状态保留。 diff --git a/docs/design.md b/docs/design.md index 983f3ba..28c762d 100644 --- a/docs/design.md +++ b/docs/design.md @@ -11,7 +11,7 @@ | 悬停 | `#0058C2` | | 浅蓝背景 | `#EDF4FF` | -品牌、按钮及在线状态不使用绿色。状态栏使用单色模板图,随 macOS 明暗主题呈现。字标使用 Helvetica Bold,保留双层 `a` 并将右下脚修为平直竖向收尾,导出为矢量路径,不依赖接收端安装字体。 +品牌和在线状态使用蓝色。macOS 状态栏使用随系统明暗主题变化的单色模板图。字标以 Helvetica Bold 为基础,保留双层 `a`,将右下脚修成平直的竖向收尾,再导出成矢量路径。 管理台采用中性表面与黑色主操作:画布 `#FAFAFA`、表面 `#FFFFFF`、正文及主按钮 `#171717`、次级文字 `#666666`、边框 `#E5E5E5`。蓝色保留给品牌、在线与可用状态、链接和键盘焦点。应用控件圆角为 6px,列表表面为 8px,弹窗为 12px;以 1px 边框分组,阴影只用于浮层。管理台自托管 Geist Sans 的 400、500、600 字重,中文使用系统字体,代码使用系统等宽字体;不依赖外部字体服务。 @@ -33,29 +33,29 @@ 扩展工具栏弹窗显示当前浏览器、连接状态和暂停、恢复、停止任务等即时操作。连接标签页承担绑定、改名、解除绑定和诊断,按绑定状态显示相应内容;Chrome 权限提示切走焦点时保留绑定表单。App 状态栏提供常用控制,设置窗按连接、本机能力和系统权限分组,运行诊断默认折叠。管理台采用固定左侧导航与右侧工作区,围绕概览、设备、Agent 连接和操作记录组织;主要面向桌面宽度,不维护超窄屏专用布局。概览并列展示设备卡片和 Agent 连接,未完成接入时只显示一个下一步入口。连接权限按设备编辑,设备范围明确区分指定设备与包含新设备的全部设备;密钥轮换与权限编辑分开。 -App 设置使用原生控件和随系统明暗变化的分组表面;系统权限只显示 App 的实际授权,驱动执行权限、Node 和 Cua Driver 状态放在运行诊断中。诊断展开或收起时窗口随内容调整高度。 +App 设置使用原生控件和随系统明暗变化的分组表面。「系统权限」显示当前 App 的授权情况,「运行诊断」显示驱动及运行时状态。打开或收起诊断时,窗口随内容调整高度。 Android 客户端使用随 APK 打包的 Tamagui 界面。设备连接状态和 Agent 访问状态分别显示,绑定后默认关闭 Agent 访问。首页显示当前可用的本机能力,能力选择保留在「能力设置」中。文件能力依赖系统选择器授予的目录读写权限。 设备列表采用卡片网格,整张卡片进入独立详情页,停止操作保留单独按钮,不因当前没有在途操作而禁用。详情页分为概况、操作记录与设置;概况展示名称、状态、类型、平台、ID、只读本机能力和可访问此设备的 Agent,设置集中改名、重新生成凭据与解绑。停止与解绑保持独立。全局操作记录按设备、Agent 连接及具体操作类型组合筛选,设备详情固定当前设备范围;记录在服务端筛选后分页,设备与 Agent 分列;设备详情省略重复的设备列,保留已解绑设备和已撤销连接的历史。 -用布局、分组和层级解释结构。只保留必要的状态、字段、动作和错误,不增加描述段落或重复提示。保留键盘焦点、必要的加载和失败状态;连接未知时不能保留“已连接”的旧状态。 +用分组、对齐和间距说明界面结构。文案说明当前状态、可用动作和错误后的下一步。连接状态未知时显示「状态未知」,并为键盘操作提供清晰的焦点反馈。 管理台设备列表支持按名称、平台或 ID 搜索,并按类型与状态筛选;空列表直接提供电脑和浏览器绑定入口。停止、复制和表单提交显示执行反馈,处理中禁止重复提交;复制失败保留可选中的原文。解除绑定和撤销连接须在确认窗中说明目标与后果。更多操作支持点外部或按 Escape 收起;弹窗关闭后返回触发控件。 ## 接入流程 -添加设备页按 macOS、Windows、Linux、Android 和浏览器扩展展示入口。macOS 和扩展可选择浏览器授权或设备凭证,Linux 和 Android 直接生成设备凭证。Windows 页提供浏览器扩展入口,使用 [Windows 客户端预览](windows-client.md) 时从客户端发起浏览器授权。浏览器授权后到设备列表确认状态。生成凭证后,页面按返回的设备 ID 跟踪连接状态,仍保留凭证供用户保存。 +添加设备页按 macOS、Windows、Linux、Android 和浏览器扩展展示入口。macOS、Windows 和扩展可选择浏览器授权或设备凭证,Linux 和 Android 直接生成设备凭证。浏览器授权后到设备列表确认状态。生成凭证后,页面按返回的设备 ID 跟踪连接状态,仍保留凭证供用户保存。 Agent 连接采用“设置访问权限 → 配置 Agent”两步流程。创建后直接显示一次性 Key、MCP 地址及可复制 JSON,确认保存后进入连接详情。详情以深链接提供设备权限、接入配置、操作记录和设置;记录固定当前连接范围。权限选择明确区分指定设备与包含新设备的全部设备,切换范围分别保留选择。 一次性凭据未确认保存时,站内导航、浏览器返回与刷新均提供离开提示;账户退出或身份切换仍立即清空旧凭据。创建成功后的列表刷新失败不清除已返回的凭据。连接、设备和记录的空状态给出具体下一步;离线、暂停及状态未知不能显示为就绪。 -内容区以对齐和间距组织层级,移除介绍性副标题与重复说明。接入流程采用居中限宽单列和横向进度;详情页用行列布局展示权限、能力及基础信息,不以大卡片包裹全部内容。只保留状态、操作名称、字段与必要的权限后果说明。 +接入流程用居中的单列布局和横向进度。详情页用行列展示权限、能力和基础信息,在改变权限的操作旁说明影响。 ## 图标 -通用界面图标使用 `lucide-preact` 的具名组件,构建仅包含实际引用的图标;不手绘通用 SVG 或用文本符号代替图标。操作图标为 16px,导航为 18px,设备为 22–24px,线宽统一为 1.75。图标不替代必要的可访问名称。 +通用界面图标使用 `lucide-preact` 的具名组件。操作图标为 16px,导航为 18px,设备为 22–24px,线宽统一为 1.75。给只显示图标的操作加上可访问名称。 平台图标源文件放在 `docs/assets/brand/platforms/`,构建复制到管理台静态资源。Chrome、Linux、Windows、Android 使用 SVG Logos(`@iconify-json/logos` 1.2.20);macOS 使用 Finder 蓝白笑脸 SVG 图标(用户提供),不使用通用 Apple 标识。保留原始配色和比例,只根据明确的平台标识选择品牌;未知平台及仅上报“Browser extension”的浏览器设备使用通用图标。添加设备页中的 Chrome 表示扩展安装入口,不表示所有浏览器设备都是 Chrome。 diff --git a/docs/guide/start.md b/docs/guide/start.md index b25fdc7..08fc80d 100644 --- a/docs/guide/start.md +++ b/docs/guide/start.md @@ -1,10 +1,10 @@ # 快速开始 -启动 aBridge Server,绑定一台设备,再将它授权给支持 Streamable HTTP 的 MCP 客户端。可以先接入 Chrome 扩展或 Windows 客户端。 +这个例子把 Server、客户端和 Agent 跑在同一台电脑上。启动 Server 后,接入 Chrome 扩展或 Windows 客户端,最后让 Agent 列出刚绑定的设备。 ## 启动 Server -准备 npm 和 Node.js 22.13+(22.x)、23.4+(23.x)或 24 及以上版本。在终端运行: +准备 npm 和 Node.js 22.13+(22.x)、23.4+(23.x)或 24 及以上版本。macOS 和 Linux 终端用下面的命令启动 Server。 ```sh npm exec --yes \ @@ -12,19 +12,19 @@ npm exec --yes \ -- abridge --web ``` -在 Windows PowerShell 中运行: +如果使用 Windows PowerShell,运行下面这条命令。 ```powershell npm.cmd exec --yes --package=https://github.com/xerrors/aBridge/releases/download/v0.4.23/xerrors-abridge-0.4.23.tgz -- abridge --web ``` -浏览器会打开本机的「实例管理」。在这里创建普通账户,然后用普通账户登录 [本机管理台](http://127.0.0.1:8765)。实例管理员链接包含凭据,请妥善保管。 +浏览器会打开「实例管理」。创建一个普通账户,再用它登录本机管理台。请妥善保管含有凭据的实例管理员链接。[打开管理台](http://127.0.0.1:8765) 如果 Server 运行在另一台机器,请先配置设备和 Agent 都能访问的地址。详见[反向代理与网络](../deployment.md#反向代理与网络)。 ## 绑定设备 -按需要选择一个客户端。Server 和客户端在同一台电脑时,服务端网址可填 `http://127.0.0.1:8765`。跨机器连接时,填写客户端能访问的 Server 地址。 +下面两种客户端选一个即可。同一台电脑上使用 `http://127.0.0.1:8765`。跨机器连接时,填客户端能访问的 Server 地址。 ### Chrome 扩展 {#绑定浏览器} @@ -42,17 +42,17 @@ npm.cmd exec --yes --package=https://github.com/xerrors/aBridge/releases/downloa 在「Agent 连接」中创建连接,选中刚绑定的设备,设置能力和有效期。保存生成的 **Agent Key**,通过「复制接入参数」获取 MCP 端点和请求头。 -以本机 Codex CLI 为例,先通过环境变量 `ABRIDGE_AGENT_KEY` 向 Codex 提供密钥,再执行: +Agent 需要支持 Streamable HTTP。以本机 Codex CLI 为例,把密钥放进环境变量 `ABRIDGE_AGENT_KEY`,然后添加 MCP Server 并启动新会话。 ```sh codex mcp add abridge --url http://127.0.0.1:8765/mcp --bearer-token-env-var ABRIDGE_AGENT_KEY codex ``` -在新会话中输入: +在新会话里请 Agent 查一次设备列表。 > 请调用 aBridge 的 `devices_list`,列出我已授权的设备和可用能力。 -返回列表中出现刚绑定的设备,即表示 Agent 已连接。如果列表为空,请在管理台核对该设备所属账户和 Agent 的授权范围。 +看到刚绑定的设备,就可以用这个连接开始任务了。列表为空时,在管理台核对设备所属账户和 Agent 的授权范围。 验证 Windows 屏幕能力时,可请 Agent 截取当前桌面,并在 Agent 界面确认结果中显示了截图。 diff --git a/docs/releasing.md b/docs/releasing.md index 8d0f882..d279ab4 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -1,14 +1,14 @@ # 发布 -软件版本只修改根 `package.json`。发布使用 `v` tag,tag 必须与该版本完全相同,提交必须在 `main` 历史中。`.github/workflows/release.yml` 在 tag 推送后验证源码,在 Linux 打包并验证最终 Server 和浏览器 ZIP,在 macOS 构建并验证 Apple Silicon App,并运行 Linux CLI 发布检查。 +1. 从上个发布 tag 开始核对变更,在根 `package.json` 中修改版本号。把版本、日期和变更写入变更记录。涉及协议、数据库或安装方式的调整,一起写清升级步骤。[变更记录](changelog.md) +2. 版本提交进入 `main` 后,在该提交上创建并推送对应的 `v` tag。发布工作流会核对版本和提交归属。 +3. Release 工作流构建并验证 Server、浏览器扩展、macOS App、Linux CLI 和 Windows 预览包。启用 Android 签名时,也会打包 APK。构建成功后检查 GitHub Release 中的文件和校验和。 -创建 tag 前,将本次版本号、日期、发布状态及变更摘要写入[变更记录](changelog.md)顶部,与版本号一起提交。对照上一发布 tag 核对实际交付内容;涉及协议、数据库或安装方式变化时,写明受影响的用户和升级步骤。 - -项目采用根目录 [Apache-2.0](https://github.com/xerrors/aBridge/blob/main/LICENSE);第三方组件保留各自许可证。候选构建成功、上传到商店、商店审核通过和 npm 实际可安装是不同状态。 +分发包内应保留项目和第三方组件的许可证。[Apache-2.0](https://github.com/xerrors/aBridge/blob/main/LICENSE) · [第三方许可](third-party-notices.md) ## npm -公开分发包默认名为 `@xerrors/abridge`,内部 `@abridge/server` workspace 不公开发布。分发只有编译后的 Server、管理台及服务端依赖,不包含桌面 SDK。可用仓库变量 `NPM_PACKAGE_NAME` 调整公开包名。 +公开包默认为 `@xerrors/abridge`,包含编译后的 Server、管理台和服务端依赖。更名时设置仓库变量 `NPM_PACKAGE_NAME`。 第一次发布前,在已登录 npm 的终端构建公开包: @@ -20,7 +20,7 @@ npm run package:check npm publish dist/releases/*.tgz --access public ``` -也可以使用 npm staged publishing 先暂存再确认。网页已登录不等于 CLI 已登录;首次发布可能需要 npm 账户验证。不要把凭据放入仓库。完成首包后,在 npm 包 Settings 中添加 Trusted Publisher: +也可以用 npm staged publishing 暂存首包,核对后再确认。发布前检查 npm CLI 的登录状态,按提示完成账户验证。首包发布后,在 npm 包的 Settings 添加 Trusted Publisher。 | 字段 | 值 | | -------------------- | ------------------------------------ | @@ -37,17 +37,13 @@ npm publish dist/releases/*.tgz --access public 带预发布后缀的版本使用 npm `next`,并标记为 GitHub Pre-release。无后缀的版本作为正式版发布,使用 npm `latest`。已存在版本不可覆盖;修改版本后再创建新的 tag。 -发布验证后,Server 的使用入口为 `npx @xerrors/abridge --web`;在确认 npm 上实际存在之前,不将这个入口表述为已可用。 +npm 发布完成后,用 `npx @xerrors/abridge --web` 验证可安装性。通过 GitHub Release 分发时,按快速开始里的 tarball 命令验证。[快速开始](guide/start.md) [npm 官方可信发布说明](https://docs.npmjs.com/trusted-publishers/) · [npm trust 的包存在前提](https://docs.npmjs.com/cli/v11/commands/npm-trust/) ## macOS -**编译不要求 Apple Developer 证书。** GitHub `macos-15` Apple Silicon runner 构建 `aBridge--macos-arm64-unsigned.zip`,其中 App 为 ad hoc 签名候选,未公证。下载后不能宣称已通过 Gatekeeper 分发审核。 - -App 内含 Swift 客户端、独立原生更新器和 arm64 Cua dylib;所有程序与资源从 App Bundle 相对解析,用户数据仍在 `~/Library/Application Support/aBridge`。产物不包含 CI 用户名、构建目录或本机凭据。将 App 拖入 Applications 后即可运行,不需要源码目录、Python 或本机 npm 环境。 - -Server 最低支持 Node 22.13.0,CI 覆盖最低补丁版本及 Node 22、24、26。npm 发布 job 单独使用 Node 26 附带的新 npm,以满足可信发布要求;这不提高产品的最低运行版本。 +GitHub 的 `macos-15` Apple Silicon runner 先构建 ad hoc 签名、未经公证的 `aBridge--macos-arm64-unsigned.zip`。App 随包带上 Swift 客户端、更新器和 arm64 Cua dylib,用户数据保存在 `~/Library/Application Support/aBridge`。应用支持 Apple Silicon 和 macOS 14 及以上版本。 本地构建: @@ -69,21 +65,21 @@ npm run package:macos -- --reuse-build 设置仓库变量 `APPLE_SIGNING_ENABLED=true` 才执行签名公证。缺任一输入会明确失败,不把未签名产物冒充正式包。临时 keychain 与私钥在该步骤退出时清理;内嵌 Mach-O 先签名,再签 App;公证 Accepted 后 staple 并输出 `*-notarized.zip`。 -当前仅支持 Apple Silicon/macOS14+。构建与运行时自检不等于用户设备已授予录屏和辅助功能;ad hoc 原生签名改变还可能影响现有系统授权。不要放宽 designated requirement 来规避权限校验。 +验收时解压实际发布的 App,检查启动、录屏和辅助功能权限。ad hoc 签名变化后,macOS 可能要求重新授权。继续使用同一 Developer ID 签名,可保持发布身份一致。 [Apple 官方公证说明](https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution) · [GitHub 官方 runner 列表](https://docs.github.com/en/actions/reference/runners/github-hosted-runners) ## Windows -Windows x64 预览包由 `ci.yml` 的 **Windows client** 任务构建。在 Windows runner 上运行 `npm run windows:shell:check`、`npm run package:windows` 和 `npm run package:windows:check` 后,CI 将未签名 ZIP 及其 SHA-256 校验文件上传到 **windows-client-unsigned**,保留 30 天。完整解压后的程序目录须小于 10,000,000 字节。 +CI 和 tag 发布复用 `windows-client.yml`。Windows runner 执行 `npm run check`、`npm run windows:shell:check`、`npm run package:windows` 和 `npm run package:windows:check`。完整解压后的程序目录须小于 10,000,000 字节。 -当前 `release.yml` 的 tag 分发范围为 Server、Chrome 扩展、macOS、Linux 及启用签名时的 Android APK。Windows 用户可通过 CI 或源码构建取得预览包。[Windows 安装与验证](windows-client.md) +CI 上传 **windows-client-unsigned**,保留 30 天。tag 发布另将 `aBridge--windows-x64-unsigned.zip` 和同名 `.sha256` 附在 GitHub Release 中。创建 Release 前会再次核对 ZIP 的 SHA-256。Windows 仍以未签名便携预览包分发。[Windows 安装与验证](windows-client.md) ## Android -Set `ANDROID_SIGNING_ENABLED=true` and configure repository secrets `ANDROID_KEYSTORE_BASE64` (single-line Base64 of the release keystore), `ANDROID_KEYSTORE_PASSWORD`, `ANDROID_KEY_ALIAS`, and `ANDROID_KEY_PASSWORD`. The tag workflow recompresses and aligns the standalone APK before signing. It verifies the signed `aBridge--android.apk` and enforces a 200,000-byte size limit before including it in the GitHub Release. +发布正式 APK 时,设置 `ANDROID_SIGNING_ENABLED=true`,并配置 `ANDROID_KEYSTORE_BASE64`(密钥库的单行 Base64)、`ANDROID_KEYSTORE_PASSWORD`、`ANDROID_KEY_ALIAS` 和 `ANDROID_KEY_PASSWORD`。工作流重新压缩并对齐 APK,然后签名。在加入 GitHub Release 前,检查 `aBridge--android.apk` 签名和 200,000 字节的体积上限。 -Use the same signing key for subsequent releases to allow in-place upgrades. Android checks package identity, signing identity, and version when the user opens the downloaded APK. The Debug APK uses a development signature and is intended for testing. +后续版本继续使用同一签名密钥,已安装用户即可原地升级。Android 安装器会检查包标识、签名和版本。调试 APK 使用开发签名,供本地和 CI 测试。 ## Linux @@ -93,10 +89,10 @@ Use the same signing key for subsequent releases to allow in-place upgrades. And `dist/releases/abridge-browser-.zip` 是商店上传包。首次上传在开发者信息中心完成,需准备商店名称、简要说明、用途、截图、图标、隐私政策及权限用途说明。上传后还需完成商店审核并取得 item ID;首次发布状态以信息中心为准。 -当前 tag 工作流生成可上传 ZIP,不自动代替商店提交与审核。后续自动上传需要已建立的 item ID 和 Chrome Web Store API 凭据;不把 Google 登录 Cookie 或账号密码放进 CI。 +tag 工作流会生成商店 ZIP。到开发者信息中心提交审核,再核对上架状态。若以后启用自动上传,使用已登记的 item ID 和 Chrome Web Store API 凭据。 ## 容器镜像发布 `release.yml` 在正式 GitHub Release 创建成功后显式调用可复用的 `.github/workflows/container.yml` 构建镜像,也支持手动输入已发布的正式 tag 补发。使用 `GITHUB_TOKEN` 创建 Release 不会触发另一个 release 事件工作流,因此发布链路直接调用。带预发布后缀的版本不生成容器镜像。使用对应 tag 的源码和当前 Dockerfile,在原生 amd64、arm64 Linux runner 分别构建并验收健康接口、页面脚本、管理员认证及 Server 分发边界,再向 GHCR 推送版本和 `latest` 多架构清单。发布权限使用临时 `GITHUB_TOKEN`,不配置长期 registry token。 -首次推送后须在 GitHub Package 设置中将镜像设为 Public,并验证匿名拉取;仓库公开不代表首次创建的容器包自动公开。部署命令见[Docker 镜像](deployment.md#docker-镜像)。 +首次推送后,在 GitHub Package 设置中把镜像可见性设为 Public,并实际验证匿名拉取。[Docker 部署](deployment.md#docker-镜像) diff --git a/docs/windows-client-design.md b/docs/windows-client-design.md index 18d9da5..070262d 100644 --- a/docs/windows-client-design.md +++ b/docs/windows-client-design.md @@ -1,13 +1,13 @@ # Windows 客户端界面 -Windows 客户端使用 Rust 调用 Win32 原生控件、系统托盘与桌面活动边框,不包含 Electron、Chromium 或 WebView。窗口集中展示设备、连接状态、暂停/停止与四项本机能力;服务器绑定和运行诊断按需展开。关闭窗口保留托盘,退出等待所属设备进程确认完成。 +Windows 客户端用 Rust 调用 Win32 控件、系统托盘和桌面活动边框。主窗口显示设备、连接状态、暂停和停止按钮以及四项本机能力。服务器绑定和运行诊断可以按需展开。关闭窗口后客户端留在托盘,从托盘退出时会等待设备进程结束。 ## 参考 - [Flow Launcher](https://github.com/Flow-Launcher/Flow.Launcher):参考轻量常驻 Windows 工具的原生窗口和托盘交互。 - [Microsoft PowerToys](https://github.com/microsoft/PowerToys):参考系统工具的设置分组与清晰状态呈现。 -仅参考交互与布局,不引入上述项目的代码、品牌、图像或依赖。品牌蓝用于主操作及在线状态;外观支持系统、浅色和深色。 +主操作和在线状态使用 aBridge 的品牌蓝。外观可以跟随系统,也可以固定为浅色或深色。 ## 状态与交互 diff --git a/docs/windows-client.md b/docs/windows-client.md index 262bcfd..688deb0 100644 --- a/docs/windows-client.md +++ b/docs/windows-client.md @@ -1,32 +1,35 @@ # Windows PC 客户端 -Windows 客户端预览版提供截图、前台键鼠输入、Shell 和 UTF-8 文件读写,可直接连接现有 aBridge Server。使用 Windows 10 或 11 x64,并保留系统自带的 Windows PowerShell 5.1。截图和键鼠操作需要解锁的交互式桌面。ARM64 尚未验证。 +在 Windows 10 或 11 x64 上安装客户端,就可以把这台电脑接入现有 aBridge Server。客户端提供截图、前台键鼠输入、Shell 和 UTF-8 文件读写,使用系统自带的 Windows PowerShell 5.1。要让 Agent 操作桌面,请保持桌面已解锁。ARM64 尚未验证。 ## 下载与安装 -预览版以**未签名便携 ZIP** 分发,解压后即可运行,无需管理员权限、Node.js 或 .NET。GitHub Actions 的下载需要登录 GitHub,产物保留 30 天。也可以在 Windows 上[从源码构建](#源码构建)。 +在发布页面的 **Assets** 下载未签名便携包 `aBridge-<版本>-windows-x64-unsigned.zip` 和同名 `.sha256`。用普通 Windows 账户解压后即可运行,安装环境只需要上面列出的系统组件。[GitHub Releases](https://github.com/xerrors/aBridge/releases/latest) -1. 打开主分支的 CI 运行列表,选择 **Windows client** 检查成功且有 **windows-client-unsigned** 产物的运行。[GitHub Actions](https://github.com/xerrors/aBridge/actions/workflows/ci.yml?query=branch%3Amain) -2. 下载并解开产物的外层 ZIP,得到 `aBridge-<版本>-windows-x64-unsigned.zip` 和同名 `.sha256` 文件。 -3. 在 PowerShell 中运行 `Get-FileHash .\aBridge-<版本>-windows-x64-unsigned.zip -Algorithm SHA256`(将文件名换成实际下载的名称),与 `.sha256` 中的哈希值核对。 -4. 将客户端 ZIP **完整解压**到自己的固定目录,例如 `%LOCALAPPDATA%\Programs\aBridge-preview-<提交号>`,然后打开解压后 `aBridge` 文件夹中的 **aBridge.exe**。未签名包可能受 Windows 或组织策略限制。 +1. 在 PowerShell 中运行 `Get-FileHash .\aBridge-<版本>-windows-x64-unsigned.zip -Algorithm SHA256`(将文件名换成实际下载的名称),与 `.sha256` 中的哈希值核对。 +2. 将客户端 ZIP **完整解压**到自己的固定目录,例如 `%LOCALAPPDATA%\Programs\aBridge-preview-<版本>`,然后打开解压后 `aBridge` 文件夹中的 **aBridge.exe**。未签名包可能受 Windows 或组织策略限制。 + +要试用主分支上的新构建,登录 GitHub,打开一次通过 **Windows client** 检查的运行。下载 **windows-client-unsigned** 并解开外层 ZIP,可以找到客户端包和校验文件。每次构建的产物保留 30 天。[GitHub Actions](https://github.com/xerrors/aBridge/actions/workflows/ci.yml?query=branch%3Amain) ## 绑定设备 -1. 在客户端的「连接」中填写 Server 地址,点击「连接并授权」。在打开的浏览器中以普通账户登录管理台并确认。已有这台电脑的 **Device Token** 时,也可以在「使用 Device Token」中填写。 -2. 在「本机能力」里打开所需的屏幕、输入、Shell 或文件能力,再到管理台「设备」页确认 Windows 设备已上线。 -3. 在管理台的「Agent 连接」中选择这台设备,授予任务所需的能力与有效期。在 Agent 端运行 `devices_list` 检查设备列表。[连接 Agent](https://xerrors.github.io/aBridge/guide/start.html#连接-agent) +1. 在「连接」中填写 Server 地址,点击「连接并授权」。浏览器打开后,用普通账户登录管理台并确认。 +2. 在客户端的「本机能力」中打开任务需要的能力,回到管理台的「设备」页确认这台电脑已上线。 +3. 在「Agent 连接」中选中这台电脑,设置能力与有效期。让 Agent 调用 `devices_list` 查看设备。[连接 Agent](https://xerrors.github.io/aBridge/guide/start.html#连接-agent) + +也可以在管理台「添加设备 → Windows → 设备凭证」生成 **Device Token**,填入客户端的「使用 Device Token」,再点击「连接并授权」。 -跨机器连接建议使用 HTTPS。使用非本机 HTTP 地址时,客户端会先要求确认完整地址。Device Token 仅用于设备绑定。需要使用 Chrome Profile 的登录态时,请单独安装并授权扩展。[浏览器客户端](https://xerrors.github.io/aBridge/browser-profile-design.html) +跨机器连接建议使用 HTTPS。使用 HTTP 时,客户端会显示完整地址并请你确认。要让 Agent 在已有登录状态的 Chrome Profile 中操作网页,请在该 Profile 里安装并授权扩展。[浏览器客户端](https://xerrors.github.io/aBridge/browser-profile-design.html) ## 更新、退出和卸载 -- 预览版使用手动更新。**先从托盘退出旧客户端**,再完整解压新 ZIP 到新的程序目录,启动新目录的 EXE。保留旧目录即可回退程序文件。 -- 默认凭据、绑定、暂停状态和操作日志位于 `%LOCALAPPDATA%\aBridge`,与程序目录分开。更新程序不要删除或覆盖这个状态目录;使用过 `--state-dir` 或私有 `deployment.json` 的用户应继续指定原状态目录,不要将这些私有文件上传到 GitHub。 -- 如需自定义状态目录,可运行 `aBridge.exe --state-dir "D:\自己的私有状态目录"`。首次使用新的空状态目录需要重新授权。 -- 状态目录优先级为 `--state-dir`、程序旁的 `deployment.json` 中的 `state_dir`、`%LOCALAPPDATA%\aBridge`。Rust 外壳与旧 WPF 外壳使用相同的目录规范化、互斥锁和激活事件名称;同一目录重复启动只唤起已有窗口。外观仍保存在该目录的 `windows-ui/native-preferences.json`,无需转换设备配置。 -- 暂停和关闭能力不会因重连自动解除。更新后确认 Server 地址、设备和本机能力是否正确。 -- 卸载时退出客户端,删除该版本的程序目录和自己建立的快捷方式即可;默认保留状态。彻底移除访问权限还需在管理台撤销设备,确认不再需要后再自行删除私有状态目录。 +**更新**时先从托盘退出旧客户端,再把新 ZIP 完整解压到另一个目录,启动其中的 `aBridge.exe`。保留旧程序目录即可回退。更新后检查 Server 地址、设备和本机能力。暂停和能力开关会随原来的状态一起保留。 + +绑定、凭据、暂停状态和日志默认保存在 `%LOCALAPPDATA%\aBridge`。更新时保留这个目录。自定义目录时,客户端依次读取 `--state-dir`、程序旁的 `deployment.json` 中的 `state_dir` 和默认路径。继续使用旧目录可以直接沿用设备配置和 `windows-ui/native-preferences.json` 中的外观设置。再次从同一个状态目录启动时,客户端会唤起已打开的窗口。 + +例如,使用 `aBridge.exe --state-dir "D:\自己的私有状态目录"` 可以指定目录。空目录需要重新授权。请将含有凭据和日志的状态文件留在本机。 + +**卸载**时先退出,再删除解压出的程序目录和快捷方式。要一并撤销设备访问权限,请在管理台解绑。确认用不到本机记录后,可以删除状态目录。 ## 源码构建 @@ -44,10 +47,11 @@ npm run desktop:windows ## 能力边界和排障 -- UIA 引用和截图坐标会检查窗口身份、焦点、几何位置、遮挡和人工输入。提升权限的窗口、UAC 安全桌面及客户端自身控件不接受输入。 -- Windows 输入采用前台操作,不支持后台输入;调用参数必须符合所连接 Server 的公共工具 schema。客户端专有坐标与滚动参数不代表所有 Server 都接受它们。 -- 在线但操作失败时,先查看客户端错误码、本机能力开关和 Server 授权。`invalid_dispatch` 表示帧契约校验失败,不能仅凭版本数字判断需要升级 Server。日志只报告安全字段诊断,不应包含凭据或操作正文。 -- 截图用例需在实际使用的 Agent 页面验证:设备在线后请求截图,确认返回真实图片,而不只是“已连接”或文字宣称成功。 +Windows 输入在前台窗口执行。客户端会在投递前检查窗口身份、焦点、位置、遮挡和本机人工输入。遇到管理员权限窗口、UAC 安全桌面或客户端自己的控件,请由本机用户操作。传坐标或滚动参数时,以所连接 Server 的公开工具参数为准。 + +设备在线但操作失败时,先检查本机能力开关和 Agent 授权,再看客户端错误码。`invalid_dispatch` 表示收到的执行请求未通过协议校验,可以用日志中的诊断字段对照 Server 和客户端的契约。 + +验证截图时,在实际使用的 Agent 页面请求截取 Windows 桌面,然后打开返回的图片。 ## 验证 @@ -59,8 +63,8 @@ npm run package:windows npm run package:windows:check ``` -测试使用虚构身份和自有 fixture。真实桌面输入用例需要显式设置 `ABRIDGE_WINDOWS_LIVE=1`,并使用专用测试窗口;CI 不连接真实账号、桌面或服务。单元测试和包启动检查不能代替多显示器、UAC、真实输入或 Yuxi 截图端到端验收。 +CI 使用虚构身份和独立测试环境。实际使用中的多显示器、UAC、桌面输入和 Yuxi 截图需要在对应环境中核对。测试真实输入时,设置 `ABRIDGE_WINDOWS_LIVE=1` 并使用专用测试窗口。 -`package:windows:check` 在仓库外解压包,检查完整目录大小、原生 PE、许可和 SHA-256,并通过自有回环 Server 验证浏览器授权、Token 绑定、Shell/文件效果、重复写入不重放、暂停、能力关闭、解绑及退出。新旧客户端的运行时实现不同,验收比较协议、状态和操作结果。 +`package:windows:check` 在仓库外解压包,检查目录大小、原生 PE、许可和 SHA-256。随后通过独立的回环 Server 验证两种绑定方式、Shell 和文件操作,以及去重、暂停、能力开关、解绑和退出。升级验收关注新旧客户端的协议、状态和操作结果。 外壳升级对照可使用 `$env:ABRIDGE_WINDOWS_LIVE='1'; npm run test:windows:shell:live -- <旧包解压目录> <新包解压目录>`。使用隔离状态目录验证关闭隐藏、跨版本互斥与激活、快捷键只暂停、原外观偏好保留。托盘菜单和真实桌面输入须从解压 EXE 另行对照,记录响应与失败提示。 diff --git a/package.json b/package.json index 1505499..bc9d2e5 100644 --- a/package.json +++ b/package.json @@ -61,7 +61,7 @@ "vitepress": "^1.6.4", "vue": "^3.5.45" }, - "version": "0.4.23", + "version": "0.5.0", "type": "module", "workspaces": [ "apps/*", diff --git a/tools/bench-report.ts b/tools/bench-report.ts index 494dff7..9175d9d 100644 --- a/tools/bench-report.ts +++ b/tools/bench-report.ts @@ -169,7 +169,9 @@ const reports = [false, true].map((filtered) => { const lines = [ `# ${filtered ? "按任务标准审核后的报告" : "全量案例报告"}`, "", - `政策版本:${casePolicy.version}。${filtered ? `本轮剔除 ${casePolicy.exclusions.length} 例。` : "包含全部最终尝试,失败、超时和采集异常不隐去。"}`, + filtered + ? `审核按 ${casePolicy.version} 执行,本轮排除 ${casePolicy.exclusions.length} 例。` + : `本表列出每次最终尝试,包括失败、超时和采集异常。审核规则版本为 ${casePolicy.version}。`, "", "| 集合 | 严格成功 / 分母 |", "| --- | --- |", @@ -178,9 +180,7 @@ const reports = [false, true].map((filtered) => { return `| ${group === "paired" ? "主对照 seed 0/1" : "额外 seed 2"} | ${es.filter((e) => e.success).length}/${es.length} |`; }), "", - "两侧使用相同模型目录与评测器;网络、模型响应及工具等待均可能影响端到端预算。超时全部保留,不属于任务不合规,不能据此剔除。", - "", - "任务未初始化仅指Agent动作前已由独立证据确认的错误。操作后的异常、任务失败、预算耗尽、模型或工具能力不足都不是排除理由。判分采集异常与任务合规性分别记录;已超时即严格失败,不因奖励未知而剔除。", + "两侧使用相同的模型目录和评测器。网络、模型响应和工具等待都计入端到端时间。超时按失败计入分母,即使原始奖励未知。判定任务未初始化时,以 Agent 动作前取得的独立证据为准。判分采集异常另行记录。", "", "| 集合 | 任务 | seed | 严格成功 | 原始奖励 | 失败记录 | 标准审核 |", "| --- | --- | --- | --- | --- | --- | --- |", @@ -191,7 +191,7 @@ const reports = [false, true].map((filtered) => { return `| ${e.group} | ${e.task} | ${e.seed} | ${e.success ? "是" : "否"} | ${e.rawReward ?? "未知"} | ${e.failure ?? "—"}${e.timedOut ? "(已超时)" : ""} | ${ex ? ex.reason : "符合,保留"} |`; }), "", - "## 版本历史(不混入最终分母)", + "## 历史运行", "", "| 版本 | 全量严格成功 | 原始数据 |", "| --- | --- | --- |", @@ -202,23 +202,23 @@ const reports = [false, true].map((filtered) => { ), `| 当前版本 | ${total.succeeded}/${snapshot.episodes.length} | [逐次结果](miniwob-v2-results.json) |`, "", - "历史数据保留,不用不同版本的最好成绩拼接最终结果。配置不同的历史分数不能用来单独归因本轮优化。stage1原始8/12因CLI诊断误判越权,全量重解析后9/12,见[修正记录](miniwob-v2-stage1-adjudication.json),没有删除任何样本。额外种子另列,不将重复尝试混入主对照。", + "历史运行和额外种子各自统计。第一阶段原始得分为 8/12,其中一例的 CLI 诊断消息被误判为越权。重新解析完整日志后,得分为 9/12,分母仍为 12。[修正记录](miniwob-v2-stage1-adjudication.json)", "", "## 剔除清单", "", ...(casePolicy.exclusions.length ? casePolicy.exclusions.map((x) => `- ${x.group}/${x.task}/${x.seed}:${x.reason};证据:${x.evidence}`) - : ["无。当前没有证据证明这些任务违反约定,不能为提高分数而强行剔除。"]), + : ["本轮所有任务均保留。"]), "", "## 审核标准", "", ...casePolicy.exclusionReasons.map((r) => `- ${r.id}:${r.definition}`), "", - "固定上游任务在本地运行;日期范围和界面变化属于原始任务内容,不因难度或缺少语义标注而排除。工具不足应作为产品问题修复。", + "在本机运行固定版本的上游任务,保留原有日期范围与界面。任务难度、语义标注缺失和工具能力不足均记录在试验结果中。", "", "[原始逐次结果](miniwob-v2-results.json) · [额外种子结果](miniwob-v2-extra.json) · [通用修复报告](browser-reliability-v2.md)", "", - "这是小样本、单模型的探索性结果,不是官方榜单或大样本泛化结论。", + "本次测量覆盖一个模型和这组适配任务。评测范围和复现方式见 [MiniWoB++ 方法](miniwob.md)。", ]; return { name: filtered ? "cases-conforming.md" : "cases-all.md", text: lines.join("\n") }; }); @@ -227,9 +227,9 @@ const fmt = (n: number | null) => (n === null ? "—" : (n / 1000).toFixed(1)); const content = [ "", "", - `真实 **${suite.requestedModel}(${suite.reasoningEffort})Agent** 通过 aBridge 完成公开 MiniWoB++ 任务:**${total.succeeded}/${total.episodes}(${((100 * total.succeeded) / total.episodes).toFixed(1)}%)**。任务、种子和预算在跑分前冻结,无重试,全部结果保留。`, + `使用 **${suite.requestedModel}(${suite.reasoningEffort})** 运行 MiniWoB++ 适配任务,共完成 **${total.succeeded}/${total.episodes}(${((100 * total.succeeded) / total.episodes).toFixed(1)}%)**。任务、种子和预算在运行前确定,每例运行一次。`, "", - `同模型目录与评测器的基线 **${previousSuccess}/${baseline.episodes.length}** → 修复后 **${total.succeeded}/${total.episodes}**;模型、任务 prompt、seed 0/1 和预算不变。基线已包含真实浏览器启动修复;两侧均固定同一份现有模型元数据,避免目录刷新超时。另用额外 seed=2 验证:**${heldSuccess}/${holdout.episodes.length}**,单独统计。标准审核剔除 **${casePolicy.exclusions.length}** 例。`, + `主对照使用种子 0 和 1,基线完成 **${previousSuccess}/${baseline.episodes.length}**,修复后完成 **${total.succeeded}/${total.episodes}**。基线已包含浏览器启动修复。两侧使用相同的模型目录、评测器、任务提示和预算。额外种子 2 单独运行,完成 **${heldSuccess}/${holdout.episodes.length}**。审核排除 **${casePolicy.exclusions.length}** 例。`, "", "![浏览器工具优化前后对照](docs/benchmarks/miniwob-v2-comparison.svg)", "", @@ -240,21 +240,21 @@ const content = [ `| \`${r.task}\` | ${baselineRows.find((b) => b.task === r.task)!.succeeded}/${r.episodes} | ${r.succeeded}/${r.episodes} | ${fmt(r.agentP50Ms)} | ${r.toolCalls} | ${r.knownInputTokens} / ${r.knownOutputTokens} | ${r.usageEpisodes}/${r.episodes} |`, ), "", - `每例限 ${suite.episodeLimitMs / 1000} 秒 / ${suite.maxToolCalls} 次工具调用,并发 ${suite.concurrency};仅开放观察、读取、操作、等待,支持 DOM 与截图,不开放 JS 执行、源码直接读取或判分接口。P50 包含 CLI 启动和模型调用,已启动的失败也计时。表中 token 为已知样本合计(输入含缓存),超时未返回用量视为未知,不能按 0 计费;CLI 不提供实际美元账单。`, + `每例限 ${suite.episodeLimitMs / 1000} 秒和 ${suite.maxToolCalls} 次工具调用,并发 ${suite.concurrency}。Agent 可以通过 DOM 和截图观察页面,也可以读取、操作和等待。P50 从 CLI 启动开始计时,包含模型调用及已启动的失败任务。表中的 token 是已报告样本的合计,输入包含缓存。缺少用量的样本记为未知。`, "", `失败分类:${ Object.entries(total.failures) .map(([k, v]) => k + " × " + v) .join(";") || "无" - }。用量覆盖 ${total.usageEpisodes}/${total.episodes};会话清理 ${total.cleaned}/${total.episodes}。`, + }。用量覆盖 ${total.usageEpisodes}/${total.episodes},会话清理 ${total.cleaned}/${total.episodes}。`, "", - "模型元数据通过CLI本地目录参数固定,未改全局配置、模型或任务prompt;这不消除网络和模型响应波动。失败全部保留,不能仅凭小样本宣称稳定速度或成本优势。", + "两侧都通过 CLI 参数加载同一份从缓存逐字复制的模型目录,以避开目录刷新超时。实际耗时仍会随模型服务和网络变化。", "", - `模型目录 SHA-256:${snapshot.modelCatalogSha256};逐字复制实际缓存的元数据,不修改模型指令或能力。`, + `模型目录的 SHA-256 为 \`${snapshot.modelCatalogSha256}\`。`, "", - `测量快照:v${snapshot.productVersion} / ${snapshot.productCommit.slice(0, 7)}。环境:${env.cpu} / ${env.platform} ${env.arch} / ${env.chrome} / Node ${env.node} / ${env.codex};记录时间 ${snapshot.recordedAt}。`, + `测量版本为 v${snapshot.productVersion}(${snapshot.productCommit.slice(0, 7)})。环境为 ${env.cpu} / ${env.platform} ${env.arch} / ${env.chrome} / Node ${env.node} / ${env.codex},记录于 ${snapshot.recordedAt}。`, "", - "这是 **6 类任务、每类 2 个种子的小样本适配子集**,原始任务限时统一延长至 180 秒,不是官方榜单成绩;单次前后对照仍有模型随机性,也不能单独证明 aBridge 优于其他工具或覆盖 macOS App。固定策略的 30/30 仅作为执行链冒烟历史数据,与 Agent 分数分开。[方法与限制](docs/benchmarks/miniwob.md) · [工具修复报告](docs/benchmarks/browser-reliability-v2.md) · [全量报告](docs/benchmarks/cases-all.md) · [标准审核报告](docs/benchmarks/cases-conforming.md) · [逐次实测数据](docs/benchmarks/miniwob-v2-results.json)。", + "结果对应 Chrome 扩展上的 6 类适配任务,每类 2 个种子,采用这里列出的时间预算。早期固定策略的 30/30 见执行链冒烟记录。[评测方法](docs/benchmarks/miniwob.md) · [工具修复报告](docs/benchmarks/browser-reliability-v2.md) · [全量报告](docs/benchmarks/cases-all.md) · [标准审核报告](docs/benchmarks/cases-conforming.md) · [逐次实测数据](docs/benchmarks/miniwob-v2-results.json)", "", "```sh", "npm run benchmark:miniwob",