# 插件加载实测:onInstalled("install") 触发机制与 bind mount 方案可行性

本文是 `docs/extension-bind-mount-minimal.md` 的实测补充与结论。
全部结论均在**生产同款浏览器 CloakBrowser 146.0.7680.177** 上实测得到
(不是 Playwright 自带的 Chromium 153),可用 `node/scripts/probe-install-modes.ts` 复现。

## 1. 目标

1. 按 bind mount 文档重构插件加载方式(共享扩展代码目录,不再每 Profile 复制一份)。
2. 开发一个小插件,测试**每次浏览器启动是否都会触发 `onInstalled("install")`**。
3. 目标:让 `install` **只在首次触发**。

## 2. 实测环境

| 项 | 值 |
|---|---|
| 浏览器 | `/home/bigcode/data/.cloakbrowser/chromium-146.0.7680.177.5/chrome`(CloakBrowser 146) |
| 启动方式 | 直接 `spawn` 真实二进制 + `--headless=new`(**不走 Playwright**,原因见文末) |
| 探针扩展 | `node/tests/fixtures/probe-extension/`(MV3,`key` 内嵌固定公钥,ID 恒为 `lhfmmbkophlpeoebdjpgfampblhkdmjg`) |
| 观测方式 | CDP 在扩展 service worker 上下文求值 `chrome.storage.local.get(['installs','boots'])` |

探针扩展把**每次** `onInstalled` 追加写入 `chrome.storage.local.installs`,并用 `boots` 计数
区分「扩展被加载」与「install 事件触发」——这两者不是一回事,必须分开看。

> 踩过的坑:第一版探针用 `fetch` 上报到本地收集器,结果 146 上被策略拦截,读数恒为 0,
> 一度误判成「扩展没加载」。**观测必须走扩展自己的 storage,不能走网络。**

## 3. 核心实测结果

### 3.1 现状(`--load-extension`,即 cloakbrowser 的 `extensionPaths`)

```
launch 1: installs=1 boots=1 reasons=["install"]
launch 2: installs=2 boots=2 reasons=["install"]
launch 3: installs=3 boots=3 reasons=["install"]
```

**每次启动都触发 `onInstalled(reason="install")`,3 次启动 3 次事件。**

原因在 Chromium 内部写得很清楚:这种扩展在 `Default/Preferences` 里记为

```
location        = 8        (COMMAND_LINE)
creation_flags  = 38
path            = <共享解压目录>
disable_reasons = []
```

`location=8` 意味着它**与命令行绑定**:每次启动命令行都重新「安装」一遍,故 `install` 必然重发。
这是 `--load-extension` 的固有语义,不是 bug。

### 3.2 替代路线逐条实测

| # | 方案 | install 次数 | 扩展是否加载 | 关键证据 |
|---|---|---|---|---|
| 1 | bind mount 到 `Default/Extensions/<id>/<version>`,启动不带任何扩展参数 | 0 | **否** | 目录里文件在(只读、hash 一致),但 Chromium 根本不扫描 `Default/Extensions` |
| 2 | 手改 `Default/Preferences` 伪造注册条目(`location=4`) | 0 | **否** | 回写后 `disable_reasons=[16777216]`(MAC 校验失败被禁用) |
| 3 | CDP `Extensions.loadUnpacked`(浏览器级) | — | — | 146 上 `Extensions.getExtensions` 未实现、`loadUnpacked` 报 `Method not available`;加 `--enable-unsafe-extension-debugging` 仍不行 |
| 4 | 策略 `ExtensionSettings` + `force_installed` + 本地 CRX/update 服务 | 0 | **否** | 日志确认读到策略文件(`Found mandatory policy file`),但外部安装器**从不启动**,update 服务 0 次请求 |
| 5 | CRX 外部安装,只放文件不写对清单键名 | 0 | **否** | 见 3.3 的键名问题,`external_extensions.json` 用文档里的 `path` 会被判 `key external_extensions is not a valid id` |
| 6 | `chrome://extensions` UI「加载未打包的扩展程序」 | — | — | 按钮点击后弹**系统原生文件框**;无 `xdotool`、`Page.setInterceptFileChooserDialog` 拦不到(`fileChooserOpened` 事件 0 次) |
| 7 | **真实外部安装**:`external_extensions.json` + 内部键名 + 浏览器自打 CRX | **3/3** | **是** | 装成 `location=2`(EXTERNAL_DOWNLOAD),`Default/Extensions/<id>/1.0.0_0` 落盘,跨启动存活、`disable_reasons=[]`——**但 install 事件照样每次启动重发** |

第 7 条是唯一拿到「正式注册」的路线(详见 3.3),但它**依然没解决本问题**:
Chromium 每次启动都会把外部安装重新走一遍,于是每次都重新发 `install`。

补充:CRX 打包时**签名私钥必须与 `manifest.json` 的 `key` 同一把**,否则 CRX 头里的
`crx_id` 与 manifest 推导出的 ID 不一致,Chromium 直接拒装。
第一版测试就栽在这里(`scripts/mkcrx.py` 现在会强制回写 `key` 对齐)。

### 3.3 真实外部安装能装上,但仍然每次触发 install

这是本轮最关键的一条,补充记录成方法论:

**能装上的写法**(位置 `<USER_DATA>/External Extensions/external_extensions.json`):

```json
{ "<扩展ID>": { "external_crx": "/abs/path/probe.crx", "external_version": "1.0.0" } }
```

三个坑,每个都对应一次失败:

1. **键名不是文档里的那套。** 顶层必须是 `{"<id>": {...}}` 字典(不是
   `{"external_extensions":[...]}` 列表);条目里认的是 `external_crx` / `external_update_url`
   这类内部键,不是 `path`。用错时的报错分别是
   `key external_extensions is not a valid id`、
   `Exactly one of the following keys should be used: external_crx, external_update_url`、
   `external_crx and external_version must be used together`。
2. **CRX 必须用浏览器自己打。** 手写的 CRX3 被拒:`程序包无效:"CRX_REQUIRED_PROOF_MISSING"`。
   可用 `chrome --pack-extension=<dir> --pack-extension-key=<pem>` 生成。
3. **CRX 的 manifest 里不能留 `key` 字段**(或必须与签名公钥一致),否则 ID 对不上。

装上之后的实测:

```
location = 2 (EXTERNAL_DOWNLOAD)
path     = <id>/1.0.0_0        # 版本目录带 _N 后缀 = 每次启动重新装一遍
disable_reasons = []
```

`external_update_url` 那条路在这个浏览器上是死的:`ExternalCrxInstaller` /
`ExternalDownloader` 符号在二进制里 **0 命中**(所有 build 都没有),
只有 `CrxUpdateService` 在,拉不到 CRX。本地 update 服务 0 次请求。

**而事件计数(3 次启动):**

```
launch 1: installs=1
launch 2: installs=2
launch 3: installs=3
```

**结论:在 CloakBrowser 146 上,不存在任何一种加载方式能让
`onInstalled("install")` 只触发一次。** 连「正式的外部安装」都做不到,
因为它每次启动同样会重跑安装流程。

### 3.3 重要副作用:扩展数据其实是持久的

首启写入 `marker`,后续不带任何标记重启:

```
B marker = {"boots":2,"marker":"written-in-first-launch"}
C marker = {"boots":3,"marker":"written-in-first-launch"}
```

即 **`chrome.storage.local` 跨启动保留,数据不丢**;重发的只是 `install` 事件本身。
另外 `Default/Extensions` 目录**根本不存在**——扩展代码只有共享目录那一份,
`USER_DATA` 里只留运行态数据(`Default/Local Extension Settings/<id>`)。

## 4. 结论

### 4.1 关于 bind mount 文档

文档第 12.4 节自己已经写明了这个前提:

> bind mount 本身不会改变 Chromium 的 Extension 生命周期。它只解决文件存储层共享问题。
> 要避免 `--load-extension` 每次启动产生的 install 行为,必须使用正常的 Extension 安装/注册方式。

实测把这句话补全了:**在 CloakBrowser 146 上,「正常的安装/注册方式」无法自动化。**
「只触发一次」要求扩展被写进 `Secure Preferences` 且 HMAC 正确,唯一能产生这个结果的
入口(外部安装器 / `loadUnpacked` / UI 加载)在此版本全部不可用。

所以:**照 bind mount 文档改,能达成「共享代码、不复制多份」,但达不成「install 只触发一次」。**

### 4.2 一个反直觉的结论:bind mount 想要的收益,现状已经拿到了

现状(`--load-extension` + 共享解压目录)其实**已经**满足文档第 1 节的目标
「让多个 Profile 共用同一份 Extension 文件」:

- 扩展代码:只有 `data/extensions/<extId>/` 一份,各 Profile 共享;
- `USER_DATA/Default/Extensions` 不存在,没有重复副本;
- 运行态数据:每 Profile 独立在 `Default/Local Extension Settings/<id>`。

也就是说,**改 bind mount 主要是把「共享」这件事从「共享目录 + 命令行指路」换成
「共享目录 + 挂载到 Profile 内」,收益是结构上的整洁,不是磁盘占用的大幅下降。**
(除非某些扩展会往自身目录写文件,那种情况下 bind mount 还能顺带省空间。)

### 4.3 想要「install 只触发一次」的可落地做法

> **2026-10-01 更新:本节"做不到"的结论已被静默安装方案推翻**,见 §7——
> 第 7 条路线的探针把 CRX 放在 Profile **外部**,这是「每次重装」的混淆变量;
> CRX 放进 Profile 内部(External Extensions 目录)后 install 天然只发一次。
> 下面的垫片方案保留,现仅用于 `EXTENSION_INSTALL_MODE=loadext` 回退链路。

**先说死结论:在 CloakBrowser 146 上做不到。** 3.2 的七条路线里,连拿到正式注册的
第 7 条(真实外部安装)都每次重发 `install`。事件本身无法阻止。

能落地的是**让这件事无害**,SerpMax 侧已实现的做法是「幂等安装垫片」:

- 实现:`node/src/core/browser/extension.install-shim.ts`
- 落点:`extension.sync.ts` 解压完插件后,把垫片拼到后台脚本(`sw.js` /
  `service_worker.js` / `background.js`)最前面,把 `chrome.runtime.onInstalled.addListener`
  包一层幂等闸门——首次放行,之后直接吞掉。
- 开关:`EXTENSION_INSTALL_SHIM`(默认开,置 `0` 关闭回到插件原始行为)。
- 标记键:`chrome.storage.local.__serpmax_init_done`,随 Profile 持久化,
  因此「首次」是**每个 Profile 的首次**,跨浏览器重启有效。

实测(同一 Profile 连开 3 次,真实二进制 CloakBrowser 146):

| 模式 | install 事件 | 插件初始化真正执行次数 |
|---|---|---|
| `loadext`(现状) | 1 → 2 → 3 | 1 → 2 → 3 |
| `external`(真实外部安装) | 1 → 2 → 3 | 1 → 2 → 3 |
| `shim`(垫片) | 1 → 1 → 1 | 1 → 1 → **1** |

`shim` 那一行 `install 事件` 也是 1,是因为连探针自己的计数回调都被闸门挡住了——
这正是效果:**从插件视角看,install 只发生了第一次**。

> 垫片的取舍:它改的是第三方插件的后台脚本。SerpMax 的插件是用户上传的产物,
> 我们不掌握其源码,所以只能像这样在分发前注入。风险点是改坏了插件,
> 因此默认开但可一键关闭,且注入位置/幂等性都有单测覆盖
> (`node/tests/extension-install-shim.test.ts`)。
> 如果某个插件自己已经幂等,注入是无害的(闸门只会让它更早返回)。

## 5. 复现方式

```sh
# 三种模式对照,各连开 3 次统计 install 与初始化次数
cd node
bun scripts/probe-install-modes.ts loadext  3   # 现状:--load-extension
bun scripts/probe-install-modes.ts shim     3   # 加幂等垫片

# 真实外部安装模式需要先用浏览器自己打 CRX
EXE=/home/bigcode/data/.cloakbrowser/chromium-146.0.7680.177.5/chrome
cp -r tests/fixtures/probe-extension /tmp/pack-ext && rm -f /tmp/pack-ext/README.md
python3 - <<'PY'
import json; p='/tmp/pack-ext/manifest.json'
m=json.load(open(p)); m.pop('key', None); json.dump(m, open(p,'w'), indent=2, ensure_ascii=False)
PY
openssl genrsa -out /tmp/pack-key.pem 2048
$EXE --headless=new --no-sandbox --pack-extension=/tmp/pack-ext --pack-extension-key=/tmp/pack-key.pem
bun scripts/probe-install-modes.ts external 3 \
  CRX_PATH=/tmp/pack-ext.crx EXT_ID=$(python3 -c "
import hashlib,subprocess
subprocess.run(['openssl','rsa','-in','/tmp/pack-key.pem','-pubout','-outform','DER','-out','/tmp/pub.der'],check=True)
h=hashlib.sha256(open('/tmp/pub.der','rb').read()).hexdigest()[:32]
print(''.join(chr(ord('a')+int(c,16)) for c in h))")

# 需要自己写 CRX 打包时(会强制回写 manifest.key 与签名私钥对齐)
python3 scripts/mkcrx.py tests/fixtures/probe-extension /tmp/probe.crx /tmp/probe.pem
```

## 6. 涉及的仓库文件

- `node/tests/fixtures/probe-extension/` — 探针扩展(`manifest.json` / `sw.js` / `README.md`)
- `node/scripts/probe-install-modes.ts` — 三模式(loadext / external / shim)多启动计数脚本
- `node/scripts/probe-silent-install.ts` — **静默安装端到端探针(生产模块链,见 §7)**
- `node/scripts/mkcrx.py` — CRX3 打包(强制 manifest.key 与签名私钥一致)
- `node/src/core/browser/extension.install-shim.ts` — 幂等安装垫片(注入 + 幂等闸门,现仅 loadext 回退用)
- `node/src/core/browser/extension.silent.ts` — **静默安装(稳定私钥/CRX 打包/External Extensions 写入)**
- `node/src/core/browser/extension.sync.ts` — 同步分流:silent(默认)/ loadext 回退
- `node/tests/extension-install-shim.test.ts` — 垫片单测(定位/幂等/语法/异常兜底)
- `node/tests/extension.silent.test.ts` — 静默安装单测(buildVersion/extIdFromPem/installSilently)

> 脚本里刻意**不用 Playwright** 启动:Playwright 默认带的是**旧 headless**
> (`--headless`),旧 headless 根本不加载扩展,会读出「扩展没装」的假象。
> 必须 `--headless=new`,或直接在有显示的环境里有头启动。

## 7. 静默安装定版(2026-10-01,推翻 §4.3 的"做不到")

Policy 变更(用户定版):**插件装载从「共享目录 + `--load-extension` 命令行装载」
改为「每个 Profile 静默安装」,不再坚持插件文件共享。**

### 7.1 为什么旧探针得出"外部安装每次重发 install"的假结论

§3.2 第 7 条(真实外部安装)的探针把 CRX 放在 **Profile 外部**(如 `/tmp/probe.crx`),
`external_extensions.json` 指过去。实测版本目录出现 `_N` 后缀、install 每次重发。

2026-10-01 复测发现混淆变量:**CRX 放进 Profile 内部**(`<USER_DATA>/External Extensions/`
目录)后,install 天然只在首次触发(同 Profile 连开 3 次 installs = 1→1→1,
boots = 1→2→3,SW 每次正常唤醒)。此 build 的外部安装不落
`Default/Extensions/<id>/<version>`(始终为空),扩展直接从 CRX 路径装载。

### 7.2 两个杀手旗标(Playwright 默认参数集)

裸 spawn 下能装 ≠ 生产 launchPersistentContext 下能装。逐旗标二分(每轮全新 Profile)
定位出两个必须经 `launchOptions.ignoreDefaultArgs` 剔除的 Playwright 默认旗标:

| 旗标 | 效果 |
|---|---|
| `--disable-extensions` | 扩展系统整体关闭(§3.2 已知) |
| `--disable-default-apps` | **关闭 ExternalProvider,外部 CRX 静默安装直接不执行(新发现)** |

注:仅有 `--disable-extensions-except`(不带 `--load-extension`)**救不回来**——
实测装不上。cloakbrowser 的 `ignoreDefaultArgs` 字段被 `launchOptions` 展开
顺序覆盖(`dist/playwright.js` 装配顺序),所以生产代码经
`launchOptions: { ignoreDefaultArgs: ["--enable-automation", "--enable-unsafe-swiftshader", "--disable-extensions", "--disable-default-apps"] }`
一并剔除(cloak 原有两项必须保留,否则 `--enable-automation` 回来破坏隐身)。

### 7.3 稳定扩展 ID 与更新语义

- 扩展 ID = 签名公钥推导(SPKI DER → sha256 前 16 字节 → a..p)。私钥按 extId
  固定存 `{extensionDir}/{extId}.key.pem`(600)→ 重打包 ID 不变。
  **私钥不能放扩展目录内**——`--pack-extension` 遇目录内 .pem 直接拒绝
  (「此扩展程序包含密钥文件」)。manifest 必须删 `key` 字段(实测保留会 ID 漂移)。
- CRX 只能浏览器自打(§3.2 第 7 条),命令:
  `$EXE --headless=new --no-sandbox --pack-extension=<dir> --pack-extension-key=<pem>`
- **更新语义**(每轮全新 Profile 实测):
  - 同 version 覆盖 CRX → **不会更新**,一直跑旧代码;
  - manifest 版本追加第 4 段(如 `1.0.0` → `1.0.0.2`)且 `external_version` 同步 →
    下次启动 Chromium 重装,install 以 `reason="update"` 恰好重发一次
    (`previousVersion` 正确),新代码从再下一次 SW 启动生效。
  - 因此 staging 状态文件记录 `{ sha256, origVersion, build }`:zip sha256 每变化
    一次 build+1,打包版本 = `buildVersion(origVersion, build)`。

### 7.4 生产链路落点(node v0.8.0)

```
extension.sync.ts  ensureExtensionsReady → { dirs(loadext), silent(silent) }
                     staging:下载/解压/sha 增量;sha 变化时删外层旧 CRX + build+1
extension.silent.ts 稳定私钥 → manifest 变换(删 key/版本对齐)→ 浏览器自打 CRX
                     → installSilently(复制 CRX 进 Profile + external_extensions.json
                       整文件重写 + 无主 CRX 清退)
browser.manager.ts  silent:installSilently 写 Profile + ignoreDefaultArgs 剔除两旗标
                     (不再传 extensionPaths);无插件仍 --disable-extensions
```

配置:`EXTENSION_INSTALL_MODE`(默认 `silent`,`loadext` 回退旧链路,垫片只在
loadext 生效)、`EXTENSION_INSTALL_SHIM`(不变)。

复现:

```sh
cd node
xvfb-run -a bun scripts/probe-silent-install.ts 3   # 生产模块链端到端,预期 installs 1→1→1
bun test tests/extension.silent.test.ts tests/extension.sync.test.ts
```

实测记录(2026-10-01,真实二进制 cloak 146):
首装 installs=1;三连启 1→1→1;更新启动后 installs=["install","update"]、
codeTags 出现新版本标记;同 Profile 数据跨更新保留。