@glittering0717/ai-browser 1.2.2 → 1.3.0

package/README.md

@@ -1,5 +1,9 @@
 <h1 align="center">AI Browser</h1>
 
+<p align="center">
+  <b>中文读者请看这里：<a href="README-CN.md">README-CN.md（3 分钟速读 + 中文安装指引）</a></b>
+</p>
+
 <p align="center">
   <b>A real browser whose only operator is your agent.</b><br>
   It reads pages as a semantic tree instead of screenshots, acts through trusted browser input —
@@ -11,18 +15,24 @@
   <img alt="MIT" src="https://img.shields.io/badge/license-MIT-blue.svg">
   <img alt="Electron" src="https://img.shields.io/badge/built%20with-Electron%2033-9cf">
   <img alt="Platforms" src="https://img.shields.io/badge/platforms-macOS%20%E2%80%A2%20Linux-blueviolet">
-  <img alt="Tests" src="https://img.shields.io/badge/tests-427%20unit%20%2B%20428%20e2e-2ea043">
+  <img alt="Tests" src="https://img.shields.io/badge/tests-658%20unit%20%2B%20447%20e2e-2ea043">
   <img alt="MCP" src="https://img.shields.io/badge/spec-MCP%20(stdio)-f5b23b">
 </p>
 
 <p align="center">
-  <em>One agent, no coordinates: open Bing → type through trusted key events (live suggestions) → scroll the results → open page 2 → back to page 1 → open the project site in a new tab → keep scrolling there. Every target was found in the semantic tree by role/label.</em><br>
-  <a href="docs/marketing/demo.gif"><img src="docs/marketing/demo.gif" alt="AI Browser demo: search, paginate, and open a website — all driven by the semantic tree" width="860"></a><br>
-  Reproduce: <code>npm start</code> then <code>node examples/demo.mjs</code>
+  <em>A noisy real-world feed (300+ accessibility nodes) becomes a typed structure — then one <code>ui.act</code> switches the feed and the tree changes with it. Every call is a raw JSON-RPC message over one WebSocket: no SDK, no coordinates.</em><br>
+  <a href="docs/marketing/demo.gif"><img src="docs/marketing/demo.gif" alt="AI Browser demo: navigate a crowded feed page, get the whole page as one semantic tree, extract typed items, and act on an element id — all over raw WebSocket JSON-RPC" width="860"></a><br>
+  Reproduce: <code>npm start</code> then <code>node examples/feed-tree.mjs</code>
+</p>
+
+<p align="center">
+  <em>Human + agent, same browser, same socket. The agent drives, then simply stops and watches; a person clicks an article in the real window, the agent notices the new tab on its next read, and continues on the page the human chose. No lock, no hand-off API.</em><br>
+  <a href="docs/marketing/demo2.gif"><img src="docs/marketing/demo2.gif" alt="Human takeover demo: the agent lists a feed and pauses; a human clicks an article in the real browser window; the agent detects the new tab and resumes scrolling on the chosen page" width="860"></a><br>
+  Try it yourself: <code>npm start</code> then <code>node examples/human-takeover.mjs</code> — click anything when it says <em>YOUR TURN</em>.
 </p>
 
 **What it is.** An Electron app that exposes its tabs over two equivalent interfaces — an MCP server
-(17 `browse_*` tools) and a raw WebSocket JSON-RPC API (`ws://localhost:9223`, methods `ui.*`). Your
+(20 `browse_*` tools) and a raw WebSocket JSON-RPC API (`ws://localhost:9223`, methods `ui.*`). Your
 agent navigates, reads a structured semantic tree (`role` / `label` / `value` / `states` / `actions`),
 and clicks or types by `data-ai-id`. There is no screenshot step and no OCR: `src/` contains no
 capture call at all.
@@ -38,11 +48,36 @@ is a conversation between the agent and the user, not a browser API.
 
 ## Install
 
-Requires **Node ≥ 18** and a desktop session (this is a GUI app).
+**Install the prebuilt package unless you have a reason not to.** Option A is one file you
+double-click: no Node.js, no dependency tree, no build step. Source install (Option C) pulls a
+~276 MB `node_modules` plus a ~100 MB Electron engine download on top — only use it when no
+package fits your platform, the package misbehaves, or you specifically need to run from source.
+
+### Option A — macOS install package (recommended)
 
-### Option A — npx (recommended for MCP users)
+Grab `AI-Browser-<version>-arm64.dmg` from
+[GitHub Releases](https://github.com/Glittering/ai-browser/releases) (~110 MB to download,
+~245 MB on disk — most of it is the bundled Chromium engine, which *is* the product). Open the
+dmg, drag **AI Browser** to `/Applications`, launch it. Done.
 
-The package is published as [`@glittering0717/ai-browser`](https://www.npmjs.com/package/@glittering0717/ai-browser); no clone needed:
+Two things to know before you download it:
+
+- **It is not notarized.** macOS Gatekeeper will refuse to open it on the first try. Right-click
+  the app → **Open**, confirm once, and it runs normally afterwards. (A paid Apple Developer
+  account is what removes this step; until then, this is the honest cost.)
+- **Only macOS `arm64` is built.** Windows and Linux have no package yet, because neither has
+  been verified on this project — see [Compatibility](#compatibility).
+
+Agents still connect through the MCP server (Option B below), and the two channels cooperate:
+when the packaged app is already running, the MCP server finds it on port 9223 and **reuses it
+instead of spawning a second copy of Electron** — one browser, one login session, whichever way
+you start it. So "package for the engine + `npx` for the MCP bridge" is the normal agent setup
+too.
+
+### Option B — npx (the agent channel)
+
+The package is published as [`@glittering0717/ai-browser`](https://www.npmjs.com/package/@glittering0717/ai-browser);
+no clone needed:
 
 ```bash
 npx -y @glittering0717/ai-browser --help
@@ -54,16 +89,21 @@ To open the visible browser window directly:
 npx -y @glittering0717/ai-browser start
 ```
 
-The first launch prepares the Electron engine (~100 MB, downloaded once). npm ≥ 11 blocks
-dependency install scripts by default — the launcher detects that and runs Electron's own
-downloader itself, so nothing extra is needed. If the download from GitHub releases is slow or
-blocked (common on mainland-China networks), point it at a mirror:
+Requires **Node ≥ 18** and a desktop session (this is a GUI app). If a launch needs its own
+engine, the first run prepares it (~100 MB, downloaded once). npm ≥ 11 blocks dependency install
+scripts by default — the launcher detects that and runs Electron's own downloader itself, so
+nothing extra is needed. If the download from GitHub releases is slow or blocked (common on
+mainland-China networks), point it at a mirror:
 
 ```bash
 ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ npx -y @glittering0717/ai-browser start
 ```
 
-### Option B — from source
+### Option C — from source (fallback)
+
+Use this when there is no package for your platform, the package gives you trouble, or you need
+to modify the code. It is the heaviest of the three: `npm install` pulls the full dependency
+tree (~276 MB), then the Electron engine (~100 MB) on top.
 
 ```bash
 git clone https://github.com/Glittering/ai-browser.git
@@ -83,8 +123,8 @@ Or make it sticky by creating a `.npmrc` in the project root:
 electron_mirror=https://npmmirror.com/mirrors/electron/
 ```
 
-Confirm the binary actually landed before blaming anything else — a missing binary still leaves you
-with an "install that succeeded":
+Confirm the binary actually landed before blaming anything else — a missing binary still leaves
+you with an "install that succeeded":
 
 ```bash
 ls node_modules/electron/dist
@@ -99,6 +139,19 @@ npm start
 A 1280×800 window opens and the terminal prints `AI Browser WS server listening on ws://localhost:9223`.
 (The first tab opens on the default start page; ignore it and navigate away.)
 
+To build the package yourself:
+
+```bash
+npm install
+node scripts/build_dmg.cjs              # current arch
+node scripts/build_dmg.cjs --arch arm64 # or x64
+```
+
+Output lands in `dist/`. The script uses `@electron/packager` plus macOS's built-in `hdiutil`
+(no external binary downloads); the reasoning — including why `electron-builder` refuses to build
+this project — is documented in
+[`docs/DEPENDENCY_AND_DISTRIBUTION_AUDIT.md`](docs/DEPENDENCY_AND_DISTRIBUTION_AUDIT.md).
+
 ---
 
 ## Connect your agent
@@ -123,8 +176,9 @@ can instead point `command: "node"` at `/absolute/path/to/ai-browser/src/main/mc
 **You do not need to start the browser yourself.** On the first `browse_*` call the MCP server probes
 port 9223; if nothing is listening it spawns Electron detached and waits up to 30 seconds for the
 WebSocket server (the very first call may additionally spend time preparing the engine). If you would
-rather keep one long-lived window shared by every client, run `npx -y @glittering0717/ai-browser start`
-(or `npm start` from source) in a terminal — a second launch just focuses the existing window.
+rather keep one long-lived window shared by every client, launch the **AI Browser** app you installed
+in Option A (or run `npx -y @glittering0717/ai-browser start`, or `npm start` from source) — a second
+launch just focuses the existing window.
 
 `examples/AGENT_INSTRUCTIONS.md` has a copy-paste prompt you can drop into a `CLAUDE.md`, Cursor Rule,
 or any system prompt; it teaches the tool loop, the token-saving params, and when to ask a human.
@@ -357,7 +411,7 @@ MCP is a thin stdio adapter. Anything MCP can do is reachable directly over JSON
 | `ui.subscribe` / `ui.unsubscribe` | Event subscription; `params.events`, `"*"` for all | — (WS only — see below) |
 | `ui.downloads` | This tab's downloads with on-disk paths (`state`, `received_bytes`, `dir`) | `browse_downloads` |
 | `ui.get_focused` | The focused element subtree | — |
-| `ui.peek` | Hover a folded/hover-only affordance and return the diff, without committing | — |
+| `ui.peek` | Hover a folded/hover-only affordance and return what appeared/disappeared (`revealed` / `hidden`), without committing. Ids are real `data-ai-id`s you can hand straight to `ui.act`; `revertMs: 0` keeps the mouse there so you can click what it found | — |
 | `ui.network_body` | Response body by URL substring (`url_pattern`) | — (superseded by `browse_network`) |
 | `ui.quit` | Graceful shutdown | `browse_quit` |
 
@@ -439,7 +493,9 @@ perturbs the thing it is measuring.
 **Writing.** Actions are **trusted browser input**, not synthesized JS. The main process drives the
 page over the Chrome DevTools Protocol — `Input.dispatchMouseEvent` for clicks, and per-character
 `Input.dispatchKeyEvent` (`rawKeyDown → char → keyUp`) for typing — then validates that the click
-actually landed via `elementFromPoint`. Because the events arrive as real keyboard and mouse input,
+actually landed via `elementFromPoint` (piercing shadow roots: the plain call returns the *host* for
+anything inside a web component, which silently downgraded every such click to a synthetic one).
+Because the events arrive as real keyboard and mouse input,
 Draft.js, ProseMirror, CKEditor, Quill, and plain `<textarea>` all work through the same path without
 per-framework branches.
 
@@ -462,7 +518,9 @@ Runnable scripts live in [`examples/`](examples/) and connect straight to `ws://
 | [`AGENT_INSTRUCTIONS.md`](examples/AGENT_INSTRUCTIONS.md) | Copy-paste instructions for your agent, incl. the human hand-off protocol. |
 | [`raw-ws.mjs`](examples/raw-ws.mjs) | Smallest possible raw WebSocket client. |
 | [`read-page.mjs`](examples/read-page.mjs) | Load one page, print its interactive elements. |
+| [`feed-tree.mjs`](examples/feed-tree.mjs) | Crowded feed → typed structure → act, all over raw JSON-RPC (top demo). |
 | [`with-human.mjs`](examples/with-human.mjs) | Full flow for when a human has to step in. |
+| [`human-takeover.mjs`](examples/human-takeover.mjs) | Agent pauses, you click, agent resumes on your page (second demo). |
 
 ```bash
 node examples/read-page.mjs
@@ -551,6 +609,65 @@ not "logged in" in another:
 AI_BROWSER_USER_DATA=~/.ai-browser-work npm start
 ```
 
+**A red bar appeared at the bottom of the window.** That is a main-process exception — a bug in
+AI Browser itself, not in the page you were driving. It is deliberately *not* a modal dialog: a
+native `dialog.showMessageBox` is an `NSAlert` modal loop on macOS and blocks the whole main process
+(measured: WebSocket calls got 4ms with no dialog vs **8 seconds of no response** with one), which
+turned a self-healing JS exception into "every RPC timed out". The bar shows the message and the log
+path, the process keeps running, and you can dismiss it with `×`.
+
+Every exception is appended synchronously to `~/.ai-browser/logs/error.jsonl` (2MB × 4 rolling), with
+the last 20 WebSocket calls attached so you can see *what was being done* when it broke. Read it over
+the API with `ui.errors` / `browse_errors`, or just `tail` the file. A record of `boot` without a
+matching `shutdown` means the process died hard last time.
+
+If the exception happened before any window existed, the bar has nowhere to go, so it falls back to a
+native box once (logged as `error_dialog_fallback`) rather than leaving you with a silently dead app.
+Both paths are switchable: `AI_BROWSER_ERROR_BANNER=0` disables the bar, `AI_BROWSER_ERROR_DIALOG=1`
+forces the modal box — the latter blocks the main process, so it is only for staring at a startup
+crash on purpose.
+
+### The element is clearly on the page but not in the tree
+
+Before you write a site-specific script, work down this list. The reflex — "pin it with a
+`querySelector` chain" — is what produced 142 site-specific scripts and 731 hardcoded selectors in
+this project's own history, and almost none of them turned out to be necessary.
+
+| # | Check | How | If it is the cause |
+|---|---|---|---|
+| 1 | Is it a **read-layer** gap? | `node tools/coverage_probe.cjs https://the.site/` | the tree is missing clickable elements → report it; the fix belongs in `src/preload/extractor.cjs`, not in your script |
+| 2 | Is it an **action-layer** gap? | the node is in the tree, `ui.act` fails or does nothing | the element is readable but not reachable (iframe/OOPIF, canvas, trusted input, un-mounted input) → that is a browser-side fix too |
+| 3 | Is it **timing**? | re-read the tree 2–3s later, or `wait_until` | the SPA simply had not rendered when you read it |
+| 4 | Does it only exist **while hovered**? | `ui.peek { target, revertMs: 0 }` | the affordance is hover-rendered. `peek` hovers it and returns what appeared — pass `revertMs: 0` to keep it open, then `ui.act click` the id you got back |
+| 5 | Is it **unnamed**? | `ui.peek`, or click it and read what shows up | an icon-only button the site gave no `aria-label`/`title`/`alt` cannot be named from nothing. But the panel it opens usually is named — so open it and read that instead of guessing which icon is which |
+| 6 | Only now: **pin it yourself** | a selector in *your* script | keep it in your script. Do not encode it as "how this site works" — the next site will not match |
+
+`coverage_probe` counts what a human would call click targets — elements the browser itself renders
+with a hand cursor (`cursor:pointer`), where the pointer starts (not every descendant that inherits
+it), and reports how many of them carry a `data-ai-id`:
+
+```
+$ node tools/coverage_probe.cjs https://www.csdn.net/
+可点目标（手型边界）: 257
+  ├ 自己带 data-ai-id（直接可操作）: 257 → 100%
+  ├ 被单个交互后代盖满且它在树里（壳子，点内层等价）: 0
+  ├ 祖先歧义（同一祖先下多个手型后代，点祖先指不准）: 0
+  └ 整条祖先链无 id（真看不见）: 0
+可用率（in_tree + by_desc + anc_only）: 100 % | 真缺口: 0
+```
+
+It exits non-zero below 80% so you can drop it into CI. Measured on 2026-10-17 (Baidu / Bilibili /
+CSDN): **82% / 97% / 88%** before the click-boundary fix, **100% / 100% / 100%** after, at ~40ms
+per `ui.get_tree`.
+
+Two things the numbers do **not** cover, so you do not chase them: an element the page gives no
+readable name (image-only links with no `alt` — 53% of Bilibili's clickable nodes) can never get a
+label without inventing one, and a canvas has no DOM to read at all. Those are genuine boundaries,
+not bugs. The full write-up, including why the first measurement of this was wrong by 3× (inherited
+`cursor` inflates the denominator), is in
+[`docs/AGENT_OPERABILITY_FEEDBACK.md`](docs/AGENT_OPERABILITY_FEEDBACK.md) §6.
+
+
 ---
 
 ## Test & dev

package/bin/ai-browser.cjs

@@ -19,7 +19,7 @@ const HELP = `ai-browser ${pkg.version}
 
 Usage:
   ai-browser [start]          Launch the visible AI Browser window
-  ai-browser mcp              Run the MCP stdio server (17 browse_* tools)
+  ai-browser mcp              Run the MCP stdio server (20 browse_* tools)
   ai-browser --version        Print version
   ai-browser --help           Show this help
 

package/examples/AGENT_INSTRUCTIONS.md

@@ -15,7 +15,7 @@
 ## 中文版（copy-paste）
 
 ```text
-我可以用 AI Browser 浏览网页。它提供 MCP 服务（17 个 browse_* 工具），第一次调用时会自动
+我可以用 AI Browser 浏览网页。它提供 MCP 服务（20 个 browse_* 工具），第一次调用时会自动
 拉起一个真实可见的浏览器窗口，用完调用 browse_quit 释放。页面以结构化语义树返回，不是截图。
 
 标准循环：
@@ -30,6 +30,8 @@
                                            text_contains / url_contains
 5. browse_evaluate { js }                  在页面上下文跑 JS 表达式（上限 5000 字符，
                                            禁用 process. / require / child_process）
+6. browse_errors                           出事了先看这里：主进程异常 / 崩溃 / 导航失败 /
+                                           RPC 报错的最近记录（含调用上下文与日志路径）
 
 省 token（browse_get_tree 参数）：
 - { "subset": "interactive" }  只保留可交互节点，砍掉纯布局分支 —— 默认就该带上
@@ -39,6 +41,14 @@
 验证写操作（success 不等于做成了）：browse_diff 先 snapshot 基线，写操作之后再 diff，
 verdict 显式给出 changed / unchanged。
 
+找不到元素 / 点了没反应时的排查顺序（**别一上来就写站点专用选择器**）：
+1. 重读 browse_get_tree，或先 browse_wait —— SPA 常常只是还没渲染完
+2. 节点在树里但操作失败 → 是**动作层**问题（跨进程 iframe、canvas、需要受信输入、
+   上传控件未挂载），写选择器解决不了
+3. 树里没有、页面上明明有 → 是**读层**缺口，属于浏览器该修的东西；先跑
+   tools/coverage_probe.cjs <url> 量化，再考虑绕过
+4. 以上都不成立，才在自己脚本里用选择器兜底；别把"某个站点的选择器"记成通用知识
+
 其他：browse_scroll 滚动文档（画布类页面用 browse_act 的 wheel）；browse_list_tabs /
 browse_new_tab / browse_close_tab / browse_set_active_tab 管标签页；browse_network 拉取网络
 请求（含 POST body，免订阅）；browse_capabilities 一次探明页面该走哪条路（结构化数据 /
@@ -57,7 +67,7 @@ browse_downloads 查下载文件落盘路径；browse_repaint 在窗口画面陈
 ## English (copy-paste)
 
 ```text
-I can browse the web with AI Browser. It exposes an MCP server (17 browse_* tools), auto-starts a
+I can browse the web with AI Browser. It exposes an MCP server (20 browse_* tools), auto-starts a
 real, visible browser window on my first call, and I release it with browse_quit when done. Pages come
 back as a structured semantic tree — no screenshots, no OCR.
 
@@ -82,6 +92,16 @@ Saving tokens (browse_get_tree params):
 Verifying writes (success is not evidence): browse_diff snapshots a baseline, then diffs after the
 write and returns an explicit verdict of changed / unchanged.
 
+When an element cannot be found, or a click does nothing — work down this list, do **not** reach for a
+site-specific selector first:
+1. re-read with browse_get_tree, or browse_wait — an SPA usually just has not rendered yet
+2. the node is in the tree but the action fails → an **action-layer** gap (cross-process iframe,
+   canvas, trusted input, unmounted upload input); a selector will not fix it
+3. the node is missing though the page clearly renders it → a **read-layer** gap, i.e. something the
+   browser should fix; quantify it with `tools/coverage_probe.cjs <url>` before working around it
+4. only then pin it with a selector inside your own script — and never record "the selector for site X"
+   as general knowledge
+
 Also: browse_scroll (document scrolling; use the wheel action on canvas apps); browse_list_tabs /
 browse_new_tab / browse_close_tab / browse_set_active_tab for tabs; browse_network for captured
 requests including POST bodies (no subscription); browse_capabilities to pick a route on an

package/llms-install.md

@@ -11,18 +11,28 @@ semantic tree (roles / labels / values / actions, stable `data-ai-id` per elemen
 not screenshots. Input is trusted CDP keyboard/mouse events. A human can use the
 window's mouse and keyboard at any time (login, QR scan, CAPTCHA, payment).
 
-Two equivalent interfaces: **MCP stdio** (17 `browse_*` tools) and a raw WebSocket
+Two equivalent interfaces: **MCP stdio** (20 `browse_*` tools) and a raw WebSocket
 JSON-RPC API at `ws://localhost:9223` (`ui.*` methods).
 
 ## Requirements
 
 - Node.js **≥ 18**
 - A desktop session (GUI app): macOS or Linux. Windows is experimental/untested.
-- ~100 MB for the Electron binary (prepared on first launch / `npm install`, from GitHub releases).
+- ~110 MB download for the Electron engine (prepared on first launch / `npm install`, from GitHub
+  releases); it expands to ~245 MB on disk. Do not judge the install by the download size alone.
+
+> **Installation priority.** The prebuilt macOS `.dmg` (README "Option A") is the recommended
+> install for humans: one file, no Node.js, no dependency tree. The npx path below is for agents
+> and for machines that already have Node — it is also how the MCP server gets registered, so it
+> stays necessary even when the packaged app is installed. The two cooperate: if the packaged app
+> is already running, the MCP server reuses it on port 9223 instead of downloading a second
+> Electron. Source install is the fallback — only when no package fits, the package misbehaves,
+> or the code itself needs changes; it pulls ~276 MB of dependencies plus the engine.
 
 ## Install
 
-Preferred — npm package [`@glittering0717/ai-browser`](https://www.npmjs.com/package/@glittering0717/ai-browser),
+For agents (this is also the MCP bridge) — npm package
+[`@glittering0717/ai-browser`](https://www.npmjs.com/package/@glittering0717/ai-browser),
 no clone needed:
 
 ```bash
@@ -80,7 +90,7 @@ call can take longer if the engine download hasn't happened yet — the progress
 A long-lived shared window is also fine — run the `start` command manually; a second launch only
 focuses the existing window (single instance lock).
 
-## The 17 tools
+## The 20 tools
 
 - `browse_navigate` — load a URL in the active or given tab.
 - `browse_get_tree` — semantic tree + context (modals, toasts, required-field

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittering0717/ai-browser",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "AI-native browser — renders pixels for humans, structured semantic-tree API for agents. No screenshots, no OCR, no coordinate guessing.",
   "main": "src/main/index.js",
   "bin": {
@@ -10,6 +10,7 @@
     "bin",
     "scripts",
     "src",
+    "tools/coverage_probe.cjs",
     "examples/AGENT_INSTRUCTIONS.md",
     "examples/mcp-config.json",
     "llms-install.md",
@@ -60,6 +61,7 @@
     "canvas": "node e2e/canvas_ws.cjs",
     "focus": "node e2e/focus_ws.cjs",
     "interact": "node e2e/interact_ws.cjs",
+    "upload": "node e2e/upload_ws.cjs",
     "view": "node e2e/view_ws.cjs",
     "realsites": "node e2e/e2e_realsites.cjs",
     "realsites:meta": "vitest run tests/test_realsites_sites.js",
@@ -67,17 +69,17 @@
     "modeldiff": "node e2e/modeldiff_ws.cjs",
     "nav": "node e2e/nav_ws.cjs",
     "audit": "node e2e/audit_ws.cjs",
-    "e2e:all": "node e2e/run_all.cjs"
+    "e2e:all": "node e2e/run_all.cjs",
+    "coverage": "node tools/coverage_probe.cjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "electron": "^33.4.11",
-    "jsdom": "^29.1.1",
     "ws": "^8.0.0"
   },
   "devDependencies": {
-    "@playwright/test": "^1.45.0",
-    "playwright": "^1.45.0",
+    "@electron/packager": "^20.3.0",
+    "jsdom": "^29.1.1",
     "vitest": "^2.0.0"
   }
 }

package/scripts/build_dmg.cjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// scripts/build_dmg.cjs — 把 AI Browser 打成 macOS .app，再压成 .dmg。
+//
+// # 为什么用 @electron/packager + hdiutil，而不是 electron-builder
+//
+// electron-builder 有一条硬校验（app-builder-lib/out/util/packageMetadata.js）：
+//     const deps = ["electron", "electron-prebuilt", "electron-rebuild"];
+//     for (const name of deps) if (name in dependencies) errors.push(...)
+// `electron` 出现在 dependencies 里就直接报错，**没有任何环境变量能绕过**
+// （ALLOW_ELECTRON_BUILDER_AS_PRODUCTION_DEPENDENCY 只管 electron-builder 自己）。
+//
+// 这条校验的假设是"Electron 应用不该把 electron 当运行时依赖分发"。而本项目的
+// npm 渠道恰恰是这么设计的：`npx -y @glittering0717/ai-browser mcp` 要把 electron
+// 装进 node_modules 再拉起来。所以两个渠道对 package.json 的要求是冲突的。
+//
+// 眼前的产物只是一个**未签名、不自动更新**的 dmg，electron-builder 的核心卖点
+// （签名/公证/自动更新/NSIS/Squirrel）一个都用不上，却要为此引入架构冲突和
+// 一堆从 GitHub 下载的二进制。@electron/packager 只做"打包"这一件事，
+// hdiutil 是 macOS 自带，不需要下载任何外部工具。
+//
+// 如果将来真要签名+公证+自动更新，正确的做法是改用 electron-builder 官方推荐的
+// 双 package.json 布局（根目录放开发依赖，app/ 子目录放应用清单），而不是在这里
+// 加 hack。
+//
+// # 用法
+//   node scripts/build_dmg.cjs              # 打当前架构
+//   node scripts/build_dmg.cjs --arch arm64 # 指定架构
+//   node scripts/build_dmg.cjs --skip-dmg   # 只出 .app，不压 dmg
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const root = path.resolve(__dirname, '..');
+const pkg = require('../package.json');
+
+const APP_NAME = 'AI Browser';
+const OUT_DIR = path.join(root, 'dist');
+
+function parseArgs(argv) {
+  const args = { arch: process.arch, skipDmg: false };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--arch') args.arch = argv[++i];
+    else if (argv[i] === '--skip-dmg') args.skipDmg = true;
+    else {
+      console.error(`[build] unknown argument: ${argv[i]}`);
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+// 黑名单。用黑名单而不是白名单是因为 packager 只有 ignore 这一个过滤手段，
+// 所以每一条都要写清"为什么它不该进安装包"——
+//   outputs/        28MB 截图证据，纯本地产物
+//   docs/           内部文档，含营销资料
+//   e2e/ tests/     测试代码与夹具
+//   tools/_oneoff/  一次性调试脚本（dep_closure / peek_* 等）
+//   dist/           上一次的构建产物
+//   .git/           版本库
+//   node_modules/.cache|.bin  npm 缓存与可执行文件软链
+//   node_modules/electron    243MB 的 Electron 发行版——打包后的可执行文件
+//                   **就是** Electron，asar 里再放一份纯属浪费；src 里所有
+//                   `from 'electron'` 都由 Electron 内置模块系统解析，不经过
+//                   node_modules。（这一点和 electron-builder 的默认行为一致。）
+//   build/           图标母版与中间产物。打包只需要 build/icon.icns 这一个
+//                    文件（由下面的 icon 选项显式指定，从源目录读取），
+//                    目录里的 svg/png/iconset 都不该随包分发；src 里也没有
+//                    任何地方引用 build/。
+const IGNORE = new RegExp(
+  '(^|\\/)(\\.git|outputs|docs|e2e|tests|dist|build|node_modules\\/\\.cache|node_modules\\/\\.bin|node_modules\\/electron|tools\\/_oneoff)(\\/|$)'
+);
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { cwd: root, stdio: 'inherit', ...opts });
+  if (r.error) throw new Error(`${cmd} failed to start: ${r.error.message}`);
+  if (r.status !== 0) throw new Error(`${cmd} exited with code ${r.status}`);
+  return r;
+}
+
+function dirSize(p) {
+  let total = 0;
+  const stack = [p];
+  while (stack.length) {
+    const cur = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(cur, { withFileTypes: true }); } catch (e) { continue; }
+    for (const e of entries) {
+      const full = path.join(cur, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else { try { total += fs.statSync(full).size; } catch (_) {} }
+    }
+  }
+  return total;
+}
+
+function mb(bytes) {
+  return (bytes / 1024 / 1024).toFixed(1) + ' MB';
+}
+
+// @electron/packager 默认走 downloadElectronZip 从 GitHub 拉 Electron zip。
+// 本机到 GitHub 的连接不稳定（间歇性 502 / fetch failed），而
+// ~/Library/Caches/electron/<hash>/ 下通常已经有下载好的 zip。
+// 这里探测缓存：有对应版本的 zip 就用 electronZipDir 指过去（packager 的
+// getElectronZipPath 见到这个选项就直接用本地文件，完全不联网），
+// 没有才回落到在线下载。注意 electronZipDir 要求目录里躺着
+// electron-v<version>-<platform>-<arch>.zip。
+function findElectronZipDir(version, platform, arch) {
+  const cacheRoot = path.join(os.homedir(), 'Library', 'Caches', 'electron');
+  const zipName = `electron-v${version}-${platform}-${arch}.zip`;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(cacheRoot, { withFileTypes: true });
+  } catch (_) {
+    return null;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const dir = path.join(cacheRoot, e.name);
+    if (fs.existsSync(path.join(dir, zipName))) return dir;
+  }
+  return null;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  // @electron/packager v20 是纯 ESM（"type": "module" + exports 只指向 dist/index.js），
+  // require() 拿到的是模块命名空间而不是函数，必须用动态 import。
+  // 它的导出是命名导出 `packager`，没有 default —— 别写成 mod.default。
+  import('@electron/packager')
+    .then((mod) => build(mod.packager, args))
+    .catch((e) => {
+      console.error(`[build] FAILED: ${e.message}`);
+      process.exit(1);
+    });
+}
+
+function build(packager, args) {
+  fs.rmSync(OUT_DIR, { recursive: true, force: true });
+  fs.mkdirSync(OUT_DIR, { recursive: true });
+
+  console.log(`[build] ${APP_NAME} ${pkg.version} — darwin/${args.arch}`);
+  console.log(`[build] ignore: ${IGNORE}`);
+
+  // electron 的实际版本以 node_modules 里装的那份为准（package.json 里是 ^ 范围）
+  const electronVersion = require('electron/package.json').version;
+  const zipDir = findElectronZipDir(electronVersion, 'darwin', args.arch);
+  if (zipDir) {
+    console.log(`[build] electron zip: 使用本地缓存 ${zipDir}（不联网）`);
+  } else {
+    console.log(`[build] electron zip: 本地无缓存，将从 GitHub 下载 v${electronVersion}`);
+  }
+
+  packager({
+    dir: root,
+    name: APP_NAME,
+    platform: 'darwin',
+    arch: args.arch,
+    out: OUT_DIR,
+    overwrite: true,
+    ignore: IGNORE,
+    electronZipDir: zipDir || undefined,
+    // 只打生产依赖：npm prune --production 会把 devDependencies（vitest、jsdom、
+    // @electron/packager 自己）从安装包里剔掉。用户侧少一整套测试工具链。
+    prune: true,
+    asar: true,
+    appBundleId: 'com.glittering.ai-browser',
+    appCategoryType: 'public.app-categories.productivity',
+    // 图标必须显式传 icon 选项。@electron/packager 的 mac.js copyIcon() 在
+    // `!this.opts.icon` 时直接 return —— 它**不会**自动去 build/ 里找
+    // icon.icns（老版 electron-packager 的行为，v20 已经没有了）。
+    // normalizeIconExtension 只在源目录路径上 existsSync，与 IGNORE 无关，
+    // 所以 build/ 可以同时留在 ignore 列表里，不进安装包。
+    icon: path.join(root, 'build', 'icon.icns'),
+    // 图标母版是 build/icon.svg，由 scripts/render_icon.cjs 用项目自带的
+    // Chromium 栅格化，再经 sips + iconutil 打成 icns。改图标走这条链，
+    // 不要直接改 png。
+  })
+    .then((paths) => {
+      const appPath = paths[0];
+      const size = dirSize(appPath);
+      console.log(`[build] app bundle: ${appPath}`);
+      console.log(`[build] app size:   ${mb(size)}`);
+
+      if (args.skipDmg) {
+        console.log('[build] --skip-dmg，不压 dmg');
+        return;
+      }
+
+      const dmg = path.join(OUT_DIR, `AI-Browser-${pkg.version}-${args.arch}.dmg`);
+      console.log(`[build] creating dmg: ${dmg}`);
+      // hdiutil 是 macOS 自带的，不需要 electron-builder 那套从 GitHub 下载的
+      // dmg-license 等二进制——在国内网络下那一步经常卡住。
+      // UDZO = zlib 压缩，比 UDBZ(bzip2) 快得多，体积只大一点。
+      run('hdiutil', [
+        'create',
+        '-volname', `${APP_NAME} ${pkg.version}`,
+        '-srcfolder', appPath,
+        '-ov',
+        '-format', 'UDZO',
+        dmg,
+      ]);
+
+      const dmgSize = fs.statSync(dmg).size;
+      console.log('');
+      console.log('[build] ===== 结果 =====');
+      console.log(`[build] dmg:  ${dmg}`);
+      console.log(`[build] size: ${mb(dmgSize)}`);
+      console.log(`[build] app:  ${mb(size)}（解压后占用）`);
+      console.log('[build] 未签名、未公证：用户需要"右键 → 打开"，见 docs/ 说明');
+    })
+    .catch((e) => {
+      console.error(`[build] FAILED: ${e.message}`);
+      process.exit(1);
+    });
+}
+
+if (require.main === module) main();