feat(sync): 同步 upstream 改动并升级到 0.16.3-fork.5

2026-03-09 12:00:13 +09:00
parent 3cbc284076
commit 356e2f5f39
46 changed files with 3542 additions and 218 deletions
@@ -254,6 +254,15 @@ Most CLI flags can be set in the config file using their camelCase equivalents (
      </td>
      <td>boolean</td>
    </tr>
+    <tr>
+      <td>
+        <code>engine</code>
+      </td>
+      <td>
+        <code>--engine</code>
+      </td>
+      <td>string (<code>chrome</code>, <code>lightpanda</code>)</td>
+    </tr>
    <tr>
      <td>
        <code>colorScheme</code>
@@ -317,6 +326,8 @@ Most CLI flags can be set in the config file using their camelCase equivalents (

 `riskMode` defaults to `warn` when unset.

+`engine` defaults to `chrome`. `lightpanda` implies native mode and is headless-only.
+
 For tab grouping in CDP mode, grouping is best-effort through the extension handshake:
 extension available => grouped by session; extension missing/unavailable => silent no-op.

@@ -399,12 +410,16 @@ agent-browser --headed true open example.com  # explicit

 This applies to all boolean flags: `--headed`, `--debug`, `--json`, `--ignore-https-errors`, `--allow-file-access`, `--auto-connect`, `--resident`.

+For environment variables, headed mode accepts either `AGENT_BROWSER_HEADED=1` or `AGENT_BROWSER_HEADED=true`.
+
 ## Extensions Merging

 Extensions from user-level and project-level configs are **concatenated**, not replaced. For example, if `~/.agent-browser/config.json` specifies `["/ext1"]` and `./agent-browser.json` specifies `["/ext2"]`, the result is `["/ext1", "/ext2"]`.

 The `AGENT_BROWSER_EXTENSIONS` environment variable and CLI `--extension` flags follow the standard priority rules (env replaces config, CLI appends).

+In this fork, local launches and extension launches remain headed by default unless headless is explicitly requested.
+
 ## Environment Variables

 These environment variables configure additional daemon and runtime behavior:
@@ -450,6 +465,17 @@ These environment variables configure additional daemon and runtime behavior:
      <td>Default directory for browser downloads.</td>
      <td>(temp directory)</td>
    </tr>
+    <tr>
+      <td>
+        <code>AGENT_BROWSER_ENGINE</code>
+      </td>
+      <td>
+        Browser engine to use: <code>chrome</code> (default), <code>lightpanda</code>. Implies native mode.
+      </td>
+      <td>
+        <code>chrome</code>
+      </td>
+    </tr>
    <tr>
      <td>
        <code>AGENT_BROWSER_TAB_GROUP</code>
@@ -0,0 +1,105 @@
+import { pageMetadata } from "@/lib/page-metadata"
+
+export const metadata = pageMetadata("engines/chrome")
+
+# Chrome
+
+Chrome (and Chromium) is the default browser engine. agent-browser discovers, launches, and manages the Chrome process automatically via the Chrome DevTools Protocol (CDP).
+
+## Binary Discovery
+
+When no `--executable-path` is provided, agent-browser searches for Chrome in this order:
+
+<table>
+  <thead>
+    <tr><th>Platform</th><th>Locations checked</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>macOS</td>
+      <td>
+        <code>/Applications/Google Chrome.app</code>,
+        <code>/Applications/Google Chrome Canary.app</code>,
+        <code>/Applications/Chromium.app</code>,
+        Playwright Chromium cache
+      </td>
+    </tr>
+    <tr>
+      <td>Linux</td>
+      <td>
+        <code>google-chrome</code>,
+        <code>google-chrome-stable</code>,
+        <code>chromium-browser</code>,
+        <code>chromium</code> in PATH,
+        Playwright Chromium cache
+      </td>
+    </tr>
+    <tr>
+      <td>Windows</td>
+      <td>
+        <code>%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe</code>,
+        <code>C:\Program Files\Google\Chrome\Application\chrome.exe</code>,
+        <code>C:\Program Files (x86)\...\chrome.exe</code>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+If Chrome is not found, run `agent-browser install` to download Chromium via Playwright.
+
+## Usage
+
+Chrome is the default engine. No `--engine` flag is needed:
+
+```bash
+agent-browser open example.com
+```
+
+To be explicit:
+
+```bash
+agent-browser --engine chrome open example.com
+```
+
+## Custom Binary
+
+Point to any Chromium-based browser with `--executable-path`:
+
+```bash
+agent-browser --executable-path /path/to/chromium open example.com
+```
+
+Or via environment variable:
+
+```bash
+export AGENT_BROWSER_EXECUTABLE_PATH=/path/to/chromium
+agent-browser open example.com
+```
+
+## Chrome-Specific Features
+
+These features are available only with Chrome:
+
+<table>
+  <thead>
+    <tr><th>Feature</th><th>Flag</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>Browser extensions</td><td><code>--extension &lt;path&gt;</code></td></tr>
+    <tr><td>Persistent profiles</td><td><code>--profile &lt;path&gt;</code></td></tr>
+    <tr><td>Storage state</td><td><code>--state &lt;path&gt;</code></td></tr>
+    <tr><td>File URL access</td><td><code>--allow-file-access</code></td></tr>
+    <tr><td>Headed mode</td><td><code>--headed</code></td></tr>
+    <tr><td>Custom launch args</td><td><code>--args &lt;args&gt;</code></td></tr>
+  </tbody>
+</table>
+
+## Containers and CI
+
+In Docker, CI runners, or other sandboxed environments, Chrome's user namespace sandbox may need to be disabled:
+
+```bash
+agent-browser --args "--no-sandbox" open example.com
+```
+
+agent-browser automatically adds `--no-sandbox` when it detects a container environment (Docker, Podman, or root execution).
@@ -0,0 +1,97 @@
+import { pageMetadata } from "@/lib/page-metadata"
+
+export const metadata = pageMetadata("engines/lightpanda")
+
+# Lightpanda
+
+[Lightpanda](https://lightpanda.io/) is a headless browser engine built from scratch in Zig. It is intended for machine-driven workloads where fast startup and low memory use matter more than full Chrome compatibility.
+
+agent-browser manages Lightpanda the same way it manages Chrome: spawn the process, connect via CDP, and drive the same downstream commands (`snapshot`, `click`, `fill`, `screenshot`, and so on).
+
+## Installation
+
+Install the Lightpanda binary before using it with agent-browser:
+
+<table>
+  <thead>
+    <tr><th>Platform</th><th>Command</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>macOS (Apple Silicon)</td>
+      <td><code>curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos &amp;&amp; chmod a+x ./lightpanda</code></td>
+    </tr>
+    <tr>
+      <td>Linux (x86_64)</td>
+      <td><code>curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux &amp;&amp; chmod a+x ./lightpanda</code></td>
+    </tr>
+  </tbody>
+</table>
+
+Move the binary somewhere in your `PATH` such as `/usr/local/bin/lightpanda` or `~/.local/bin/lightpanda`.
+
+See the [Lightpanda installation docs](https://lightpanda.io/docs/open-source/installation) for more options.
+
+## Usage
+
+Use `--engine` to select Lightpanda:
+
+```bash
+agent-browser --engine lightpanda open example.com
+agent-browser --engine lightpanda snapshot
+agent-browser --engine lightpanda screenshot
+```
+
+Or set it as the default via environment variable:
+
+```bash
+export AGENT_BROWSER_ENGINE=lightpanda
+agent-browser open example.com
+```
+
+Or in `agent-browser.json`:
+
+```json
+{
+  "engine": "lightpanda"
+}
+```
+
+## Custom Binary Path
+
+If the `lightpanda` binary is not in your `PATH`, use `--executable-path`:
+
+```bash
+agent-browser --engine lightpanda --executable-path /path/to/lightpanda open example.com
+```
+
+## Differences From Chrome
+
+Lightpanda is headless-only and does not support several Chrome-specific features:
+
+<table>
+  <thead>
+    <tr><th>Feature</th><th>Status</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>Extensions (<code>--extension</code>)</td><td>Not supported</td></tr>
+    <tr><td>Persistent profiles (<code>--profile</code>)</td><td>Not supported</td></tr>
+    <tr><td>Storage state (<code>--state</code>)</td><td>Not supported</td></tr>
+    <tr><td>File access (<code>--allow-file-access</code>)</td><td>Not supported</td></tr>
+    <tr><td>Headed mode (<code>--headed</code>)</td><td>Not applicable</td></tr>
+    <tr><td>Screenshots</td><td>Depends on Lightpanda CDP support</td></tr>
+  </tbody>
+</table>
+
+agent-browser returns a clear error if you combine `--engine lightpanda` with unsupported flags.
+
+## When To Use Lightpanda
+
+Lightpanda is a good fit for:
+
+- Fast scraping and extraction jobs
+- AI agent workflows where speed and low memory matter
+- CI environments with constrained resources
+- High-volume parallel automation
+
+Use Chrome when you need full browser fidelity, extensions, or persistent profiles.
@@ -40,6 +40,13 @@ export const navigation: NavSection[] = [
      { name: "Native Mode (Experimental)", href: "/native-mode" },
    ],
  },
+  {
+    title: "Engines",
+    items: [
+      { name: "Chrome", href: "/engines/chrome" },
+      { name: "Lightpanda", href: "/engines/lightpanda" },
+    ],
+  },
  {
    title: null,
    items: [{ name: "Changelog", href: "/changelog" }],
@@ -14,6 +14,8 @@ export const PAGE_TITLES: Record<string, string> = {
  profiler: "Profiler",
  ios: "iOS Simulator",
  security: "Security",
+  "engines/chrome": "Chrome",
+  "engines/lightpanda": "Lightpanda",
  "native-mode": "Native Mode (Experimental)",
  changelog: "Changelog",
 };
@@ -0,0 +1,148 @@
+# Upstream Sync Audit (2026-03-09)
+
+Scope: compare current `main` plus the local in-progress sync worktree with `upstream/main`.
+
+## Already Synced
+
+- `de5ea1d` `fix: use reqwest for CDP port discovery instead of broken hand-rolled HTTP client (#619)`
+- `8f6ad81` `Fix dialog dismiss command parsing (#605)`
+- `7acde7e` `fix: native auth login fails due to incompatible encryption format (#648)`
+- `492830a` `Fix: Suppress Google Translate bar in native headless mode (#649)`
+- `68cebe5` `Fix Chrome extensions not loading by forcing headed mode when extensions present (#652)`
+- `b7e7a25` `fix: persist auth cookies on close in native mode (#650)`
+
+## Absorbed Locally (Not Exact Cherry-Picks)
+
+- `eaa968e` `fix: suppress spurious --native warning when set via env var (#611)`
+  - Covered by the local native CLI restoration in:
+    - [cli/src/flags.rs](/Users/leo/github.com/agent-browser/cli/src/flags.rs)
+    - [cli/src/main.rs](/Users/leo/github.com/agent-browser/cli/src/main.rs)
+    - [cli/src/connection.rs](/Users/leo/github.com/agent-browser/cli/src/connection.rs)
+    - [cli/src/native/daemon.rs](/Users/leo/github.com/agent-browser/cli/src/native/daemon.rs)
+- `788ad0e` `chore: add cargo fmt check to Rust CI and fix existing violations (#620)`
+  - The Rust CI `fmt` check is already present in [.github/workflows/ci.yml](/Users/leo/github.com/agent-browser/.github/workflows/ci.yml).
+- `aba2353` `Fix clippy warnings across CLI codebase (#654)`
+  - The current worktree already carries the relevant CLI cleanup needed for `cargo clippy -- -D warnings` to pass.
+- `d9387aa` `ci: add clippy check to Rust CI workflow (#675)`
+  - The Rust CI `clippy` check is already present in [.github/workflows/ci.yml](/Users/leo/github.com/agent-browser/.github/workflows/ci.yml).
+- `f262ff1` `docs: improve snapshot usage guidance and add reproducibility check (#630)`
+  - Safe docs-only sync. Applied locally in [skills/dogfood/SKILL.md](/Users/leo/github.com/agent-browser/skills/dogfood/SKILL.md).
+- `a0bd0c2` `Add webview support for Electron apps in native mode (#671)`
+  - Applied locally in:
+    - [cli/src/native/actions.rs](/Users/leo/github.com/agent-browser/cli/src/native/actions.rs)
+    - [cli/src/native/browser.rs](/Users/leo/github.com/agent-browser/cli/src/native/browser.rs)
+  - Broadens native target discovery from `page` to `page | webview` and adds `type` to native `tab_list` output.
+  - Does not alter the fork's Node.js stealth launch defaults.
+- `36c2e06` `add benchmarks (#637)`
+  - Applied locally in:
+    - [package.json](/Users/leo/github.com/agent-browser/package.json)
+    - [test/benchmarks/run.ts](/Users/leo/github.com/agent-browser/test/benchmarks/run.ts)
+    - [test/benchmarks/scenarios.ts](/Users/leo/github.com/agent-browser/test/benchmarks/scenarios.ts)
+  - Adds developer benchmark scripts only. No runtime or stealth launch behavior changes.
+- `0da54c7` `lightpanda (#646)` core feature set
+  - Applied locally in:
+    - [cli/src/flags.rs](/Users/leo/github.com/agent-browser/cli/src/flags.rs)
+    - [cli/src/main.rs](/Users/leo/github.com/agent-browser/cli/src/main.rs)
+    - [cli/src/connection.rs](/Users/leo/github.com/agent-browser/cli/src/connection.rs)
+    - [cli/src/native/actions.rs](/Users/leo/github.com/agent-browser/cli/src/native/actions.rs)
+    - [cli/src/native/browser.rs](/Users/leo/github.com/agent-browser/cli/src/native/browser.rs)
+    - [cli/src/native/cdp/lightpanda.rs](/Users/leo/github.com/agent-browser/cli/src/native/cdp/lightpanda.rs)
+    - [src/protocol.ts](/Users/leo/github.com/agent-browser/src/protocol.ts)
+    - [src/types.ts](/Users/leo/github.com/agent-browser/src/types.ts)
+    - [src/actions.ts](/Users/leo/github.com/agent-browser/src/actions.ts)
+    - [docs/src/app/engines/chrome/page.mdx](/Users/leo/github.com/agent-browser/docs/src/app/engines/chrome/page.mdx)
+    - [docs/src/app/engines/lightpanda/page.mdx](/Users/leo/github.com/agent-browser/docs/src/app/engines/lightpanda/page.mdx)
+    - [docs/src/lib/docs-navigation.ts](/Users/leo/github.com/agent-browser/docs/src/lib/docs-navigation.ts)
+    - [docs/src/lib/page-titles.ts](/Users/leo/github.com/agent-browser/docs/src/lib/page-titles.ts)
+    - [test/benchmarks/run.ts](/Users/leo/github.com/agent-browser/test/benchmarks/run.ts)
+    - [test/benchmarks/engine-scenarios.ts](/Users/leo/github.com/agent-browser/test/benchmarks/engine-scenarios.ts)
+    - [test/benchmarks/pages/article.html](/Users/leo/github.com/agent-browser/test/benchmarks/pages/article.html)
+    - [test/benchmarks/pages/dashboard.html](/Users/leo/github.com/agent-browser/test/benchmarks/pages/dashboard.html)
+    - [test/benchmarks/pages/ecommerce.html](/Users/leo/github.com/agent-browser/test/benchmarks/pages/ecommerce.html)
+  - Shared launch protocol now accepts `engine`. The Node path still rejects `engine=lightpanda` with a clear `--native` requirement, while the native path can launch either `chrome` or `lightpanda`.
+  - This preserves the current Node.js/Chrome stealth path while adding the native-only alternative engine surface and its supporting docs/benchmarks.
+
+## Remaining Upstream Commits
+
+Current status: there are no remaining upstream feature commits that are both codeful and safe to port directly into this fork. What remains is either release metadata or the stealth-sensitive `#607` launch-policy batch.
+
+### Low Risk / Independent Of Stealth
+
+- `94521e7` `chore: add minor changeset for release (#683)`
+  - Release metadata only.
+- `2bab729` `chore: version packages (#684)`
+  - Release/version bump only.
+- `01ac557` `chore: add patch changeset for release (#609)`
+  - Release metadata only.
+- `7d2c895` `chore: add patch changeset for release (#612)`
+  - Release metadata only.
+- `7edc5d5` `chore: version packages (#610)`
+  - Release/version bump only.
+- `794a77e` `chore: version packages (#613)`
+  - Release/version bump only.
+
+### Needs Manual Review Because It Touches Stealth-Sensitive Launch Behavior
+
+- `e5fd26e` `headed mode (#607)`
+  - Overlaps with our fork-modified launch path:
+    - `src/browser.ts`
+    - `src/daemon.ts`
+    - `cli/src/native/cdp/chrome.rs`
+    - `cli/src/connection.rs`
+  - Upstream intent:
+    - honor `AGENT_BROWSER_HEADED`
+    - support headed launch in more places
+    - add temp profile cleanup and tests
+  - Fork-specific risk:
+    - upstream changes persistent extension launch from `headless: false` to `headless: options.headless ?? true` in `src/browser.ts`
+    - our fork intentionally keeps extension launches headed by default via [src/browser.ts](/Users/leo/github.com/agent-browser/src/browser.ts#L2131)
+    - our daemon auto-launch path already honors `AGENT_BROWSER_HEADED=1` and `AGENT_BROWSER_HEADED=true` in [src/daemon.ts](/Users/leo/github.com/agent-browser/src/daemon.ts#L523)
+    - the native temp-profile cleanup and extension-headed logic from upstream are already present in [cli/src/native/cdp/chrome.rs](/Users/leo/github.com/agent-browser/cli/src/native/cdp/chrome.rs)
+    - blindly reapplying the upstream Node hunk would move extension launch defaults back toward upstream headless behavior and would change current stealth assumptions
+  - Recommendation:
+    - do not cherry-pick this commit directly
+    - keep fork ownership of headed/headless defaults in the Node.js path
+    - extract only test-only utilities or assertions that do not alter launch policy
+    - local regression tests now lock the fork policy in [src/browser.test.ts](/Users/leo/github.com/agent-browser/src/browser.test.ts), including default local headed launch and extension launches remaining headed by default
+    - Node daemon env parsing is also locked in [src/daemon.test.ts](/Users/leo/github.com/agent-browser/src/daemon.test.ts), including `AGENT_BROWSER_HEADED=true` and comma/newline parsing for extensions and args
+    - treat headless/headed defaults as a fork-owned policy decision
+
+### Already Partly Reimplemented In Fork
+
+- `139dd0e` `fix: surface daemon startup errors instead of opaque timeout message (#614)`
+  - Current fork already captures daemon stderr with `Stdio::piped()` and checks `try_wait()` during startup polling in [cli/src/connection.rs](/Users/leo/github.com/agent-browser/cli/src/connection.rs#L478) and [cli/src/connection.rs](/Users/leo/github.com/agent-browser/cli/src/connection.rs#L685).
+  - `AGENT_BROWSER_DEBUG` forwarding is already present in [cli/src/connection.rs](/Users/leo/github.com/agent-browser/cli/src/connection.rs#L550) and [cli/src/connection.rs](/Users/leo/github.com/agent-browser/cli/src/connection.rs#L651).
+  - Re-review on 2026-03-09 confirms the local implementation is functionally equivalent or stronger than upstream, with the same stderr surfacing and early-exit detection but fork-specific daemon spawn logic.
+  - Recommendation: treat `#614` as absorbed locally and do not cherry-pick it.
+
+## Fork-Specific Blockers Found During Audit
+
+- Native CLI wiring was missing during the initial audit, but has since been restored locally.
+- Remaining blocker is no longer the `--native` switch itself.
+- The real decision point is whether this fork wants to expose new native features (`--engine`, Lightpanda, Electron webview) that do not help stealth directly but do expand the maintained surface area.
+- That decision has now been made in favor of exposing them locally, so the blocker section is effectively closed for the current sync round.
+
+## Current Verification
+
+- `cd /Users/leo/github.com/agent-browser/cli && cargo fmt -- --check`
+- `cd /Users/leo/github.com/agent-browser/cli && cargo clippy -- -D warnings`
+- `cd /Users/leo/github.com/agent-browser/cli && cargo test`
+- `cd /Users/leo/github.com/agent-browser && pnpm build`
+- `cd /Users/leo/github.com/agent-browser && pnpm exec tsx test/benchmarks/run.ts --node-only --iterations 1 --warmup 0`
+- `cd /Users/leo/github.com/agent-browser && pnpm exec vitest run src/actions.test.ts test/keyboard.test.ts test/launch-options.test.ts`
+
+All checks pass against the current local sync worktree.
+
+## Recommended Migration Order
+
+1. CI hygiene batch
+   - Already absorbed locally via the current worktree.
+   - No stealth behavior change.
+2. Docs-only batch
+   - Safe to keep following `#630`-style guidance updates.
+   - No runtime behavior change.
+3. Headed-mode audit
+   - Reconcile upstream `#607` against fork-owned stealth launch defaults instead of cherry-picking it.
+4. Release metadata
+   - Keep fork-owned release/versioning flow.
+   - Do not mirror upstream changesets or version bumps unless this fork explicitly decides to realign its release train.