fde2e-bu 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fde2e-bu",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "FDE2E Browser Use CLI —— skills 管理＋MCP server＋扩展配对（零运行时依赖）",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -14,8 +14,9 @@ import { runServe } from './mcp/serve.mjs';
 import { runHttpServe, DEFAULT_HTTP_PORT } from './mcp/http.mjs';
 import { runNmHost } from './nm/host.mjs';
 import { cmdBindInstall, cmdBindStatus, cmdBindRemove, assertBindPlatform } from './nm/bind.mjs';
+import { cmdSelfUpdate, DEFAULT_FEED_URL } from './nm/update.mjs';
 import { resolveConfigDir } from './configdir.mjs';
-import { cmdStatus, cmdDoctor, cmdUpdate } from './misc.mjs';
+import { cmdStatus, cmdDoctor } from './misc.mjs';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -35,7 +36,8 @@ const MAIN_HELP = `fde2e-bu —— FDE2E Browser Use 命令行（零运行时依
               serve（stdio JSON-RPC 2.0；--http＝仅回环 token 端点）| add | list | remove
   status    桥服务（omni /healthz）健康探测，离线降级提示；顶部显示已配对执行器
   doctor    自检：node 版本 / 配置路径 / 环境变量 / 扩展 zip / NM manifest / pairing
-  update    更新提示（尊重 npm，不自作下载器）
+  update    扩展自更新：发现 unpacked 安装 → feed 检查 → 下载校验原子替换
+              [--ext-dir <dir>] [--feed <url>] [--dry-run]
   bind      扩展↔CLI 一次性配对（Chrome Native Messaging）
               install | status | remove
 
@@ -112,6 +114,29 @@ flag 面按子命令收窄（C1）：不适用 flag 与多余位置参数一律
 （如 mcp list --profile-id x 不再被静默忽略）；--port/--token 仅 --http 模式可用。
 --home/--dir 显式重定向配置根与工作区根（测试用，不碰真实家目录）。`;
 
+const UPDATE_HELP = `fde2e-bu update —— 扩展自更新（unpacked 独立安装）
+
+用法：
+  fde2e-bu update [--ext-dir <dir>] [--feed <url>] [--dry-run]
+      发现本机 unpacked 安装（Chrome 系浏览器 Preferences/Secure Preferences 的
+      extensions.settings[meojillndgamkbfjijfehjaefolnfopn].path，多浏览器多
+      profile 全扫）→ fetch feed（缺省 ${DEFAULT_FEED_URL}）→ semver 只认 > →
+      下载（https 强制）→ sha256/字节数双校验 → staging 解压（zip-slip/条目数/
+      根 manifest/总量四重防护）→ rm+rename 原子替换（Windows 瞬态占用退避）。
+      多处安装全部应用；任一失败不回滚其它。受 FDE2E Omni 桌面版管理的安装
+      （~/fde2e/bu/ 内或目录旁 .browser-extension-state.json）自动跳过——随 App 更新。
+      --ext-dir <dir>    显式指定安装目录（复核 manifest.json 在场即可，免扫描）
+      --feed <url>       覆写 feed 地址（测试/私有部署；仍强制 https）
+      --dry-run          只报发现与目标版本，不写盘
+      0 命中 → exit 1＋指引（浏览器未开过本插件/装在非常规处时用 --ext-dir）。
+      CLI 本体的更新仍走 npm：npm i -g fde2e-bu@latest。
+
+环境变量（NM host 路径也生效）：
+  BU_UPDATE_BASE      下载基址/白名单重定向（测试假 feed server/私有部署；
+                      信任重定向到指定基址，不是放宽为任意域）
+
+设计：openspec/changes/bu-online-selfupdate（proposal/design C）。`;
+
 const BIND_HELP = `fde2e-bu bind —— 扩展↔CLI 一次性配对（Chrome Native Messaging）
 
 平台：支持 macOS 与 Linux（NM 清单按 Chrome 规范路径文件落盘）；Windows 需注册表
@@ -296,18 +321,42 @@ export async function main(argv) {
       return cmdDoctor({ home: values.home, dir: values.dir, json: values.json, configDir: values['config-dir'], manifestsDir: values['manifests-dir'] });
     }
     case 'update': {
-      // C1：update 除 help 外无 flag（--json 等一律 exit 2），多余位置参数同样拒绝
-      assertFlags(rest, ['help'], 'update', { help: MAIN_HELP });
+      // A3（bu-online-selfupdate）：--ext-dir/--feed/--dry-run；不适用 flag 与多余
+      // 位置参数一律 exit 2（cli-tooling 规格）；--feed 在参数面即强制 https。
+      assertFlags(rest, ['ext-dir', 'feed', 'dry-run', 'help'], 'update', { help: UPDATE_HELP });
       const { positionals, values } = parse(rest, {
-        options: { help: { type: 'boolean', short: 'h' } },
-        help: MAIN_HELP,
+        options: {
+          'ext-dir': { type: 'string' },
+          feed: { type: 'string' },
+          'dry-run': { type: 'boolean' },
+          help: { type: 'boolean', short: 'h' },
+        },
+        help: UPDATE_HELP,
       });
       if (values.help) {
-        console.log(MAIN_HELP);
+        console.log(UPDATE_HELP);
         return 0;
       }
-      assertNoPositionals(positionals, 'update', { help: MAIN_HELP });
-      return cmdUpdate();
+      assertNoPositionals(positionals, 'update', { help: UPDATE_HELP });
+      if (values['ext-dir'] !== undefined && values['ext-dir'] === '') {
+        throw new UsageError('--ext-dir 不能为空', { help: UPDATE_HELP });
+      }
+      if (values.feed !== undefined) {
+        let u;
+        try {
+          u = new URL(values.feed);
+        } catch {
+          throw new UsageError(`--feed url 无法解析：${values.feed}`, { help: UPDATE_HELP });
+        }
+        if (u.protocol !== 'https:') {
+          throw new UsageError(`--feed 必须 https（收到 ${u.protocol}//${u.host}）`, { help: UPDATE_HELP });
+        }
+      }
+      return cmdSelfUpdate({
+        ...(values['ext-dir'] !== undefined ? { extDir: values['ext-dir'] } : {}),
+        ...(values.feed !== undefined ? { feed: values.feed } : {}),
+        dryRun: Boolean(values['dry-run']),
+      });
     }
     case 'bind': {
       // A3：bind install/status/remove；--help/-h → BIND_HELP exit 0；裸 bind → 帮助 exit 2

package/src/misc.mjs

@@ -1,4 +1,5 @@
-// status / doctor / update（tasks 1.2 / 1.3 / 4.2；C2 P2-7；A5＝pairing 消费）。
+// status / doctor（tasks 1.2 / 1.3；C2 P2-7；A5＝pairing 消费）。
+// （update 组自 bu-online-selfupdate A3 起改走 src/nm/update.mjs 的 cmdSelfUpdate。）
 import { existsSync, readdirSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
@@ -8,7 +9,6 @@ import { findSkillsWorkspace } from './skills/skills.mjs';
 import { resolveConfigDir } from './configdir.mjs';
 import { readPairing, defaultProfileId } from './nm/host.mjs';
 import { manifestTargets, readManifest, hostScriptExecutable } from './nm/bind.mjs';
-import pkg from '../package.json' with { type: 'json' }; // P1-3：update 文案版本真值单源
 
 // ---------- status（task 1.2 + C2）：/healthz 探活＋绑定配置面＋六落点注册清单 ----------
 
@@ -227,15 +227,3 @@ export async function cmdDoctor({ home, dir, json, fetchImpl, healthzTimeoutMs,
   }
   return counts.fail > 0 ? 1 : 0;
 }
-
-// ---------- update（task 4.2）：尊重 npm，不自作下载器 ----------
-
-/** P1-3：版本真值取 package.json（不再写死 0.1.0/「尚未发布」——发布与否是
- *  registry 侧事实，CLI 只如实报当前版本与更新命令，404 语义交给用户对照）。 */
-export function cmdUpdate() {
-  console.log(`当前 fde2e-bu@${pkg.version}；更新走 npm（不自作下载器）：`);
-  console.log('  npm i -g fde2e-bu@latest     # 全局安装形态');
-  console.log('  npx -y fde2e-bu@latest …     # 免装直跑（生产建议 pin 版本）');
-  console.log('若 npm registry 报 404（E404/PACKAGE_VERSION_NOT_FOUND），说明该版本尚未发布——属正常现象，等发布即可。');
-  return 0;
-}

package/src/nm/host.mjs

@@ -1,25 +1,34 @@
-// Native Messaging host（change bu-bind-http-publish A1/A2）——Chrome NM 帧协议
-// 与 bu:pair 配对消息处理。隐蔽子命令 `fde2e-bu __nm-host` 直通本模块 runNmHost。
+// Native Messaging host（change bu-bind-http-publish A1/A2；bu-online-selfupdate A2
+// 增 bu:update）——Chrome NM 帧协议与 bu:pair/bu:update 消息处理。隐蔽子命令
+// `fde2e-bu __nm-host` 直通本模块 runNmHost。
 //
 // 帧协议（Chrome Native Messaging 规范）：
 //   4 字节小端长度前缀 + UTF-8 JSON 载荷；单帧上限 1MB（超限回错误帧，不崩不退出
 //   ——长度前缀流无法重同步，按「4+声明长度」流式丢弃该帧字节后继续解后续帧）。
-// 消息（扩展 → CLI，唯一受支持类型）：
+// 消息（扩展 → CLI）：
 //   {type:'bu:pair', version:'<manifest version>',
 //    bindings:[{profileId, role:'master'|'cluster', name?, server?}]}
 //   （bindings 来自扩展绑定表快照；空数组合法——照常落盘并如实显示 0 条。）
+//   {type:'bu:update', feedVersion, url, sha256, size, runningVersion}
+//   （bu-online-selfupdate design C4：SW 判定有新版后请 host 定位 unpacked 安装并
+//   下载校验原子替换；url 相对形态按官方 downloads 基址解析，域名硬白名单。）
 // 应答（CLI → 扩展）：
 //   成功 {type:'bu:pair:ok', cli:'fde2e-bu', version:<pkg>, saved:N}
+//        {type:'bu:update:ok', from, to, paths:[…]}（多命中全部应用）
 //   失败 {type:'bu:pair:error', message:<原因>}（未知类型/校验不过/落盘失败）
+//        {type:'bu:update:error', code, message, paths?}
+//        （code ∈ managed|not-found|verify|bad-url|io|bad-msg——面板按码映射文案）
 // 落盘：pairing.json（{version, savedAt, bindings}，atomicWrite 0600——复用
-// src/mcp/config.mjs 的原子写底座）。pairing 只含 profileId/role/name/server 等
-// 非敏感标识，绝不含 token/credential。
+//   src/mcp/config.mjs 的原子写底座）。pairing 只含 profileId/role/name/server 等
+//   非敏感标识，绝不含 token/credential。
 // 生命周期：stdin EOF → 退出 0；一切日志只走 stderr（stdout 只有协议帧）。
 
 import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { atomicWrite } from '../mcp/config.mjs';
 import { resolveConfigDir } from '../configdir.mjs';
+import { locateInstalls, applyUpdate, EXTENSION_ID, resolveNmUrl } from './update.mjs';
 import pkg from '../../package.json' with { type: 'json' };
 
 export const NM_HOST_NAME = 'com.fde2e.bu';
@@ -166,6 +175,112 @@ export function validatePairMessage(msg) {
   return { ok: true, bindings };
 }
 
+// ---------- bu:update 校验与处理（bu-online-selfupdate A2，design C4） ----------
+
+/**
+ * 校验 bu:update 消息形状：{type, feedVersion, url, sha256, size, runningVersion}
+ * 六字段齐备（url/sha256/size 后续在下载层再深校验——此处先拒结构性畸形）。
+ * @returns {{ ok:true } | { ok:false, message:string }}
+ */
+export function validateUpdateMessage(msg) {
+  if (msg === null || typeof msg !== 'object' || Array.isArray(msg)) {
+    return { ok: false, message: '消息须为 JSON 对象' };
+  }
+  if (msg.type !== 'bu:update') {
+    return { ok: false, message: `未知消息类型：${JSON.stringify(msg.type ?? null)}` };
+  }
+  for (const k of ['feedVersion', 'url', 'runningVersion']) {
+    if (typeof msg[k] !== 'string' || msg[k] === '') {
+      return { ok: false, message: `bu:update.${k} 须为非空字符串（收到 ${JSON.stringify(msg[k] ?? null)}）` };
+    }
+  }
+  if (typeof msg.sha256 !== 'string' || !/^[0-9a-fA-F]{64}$/.test(msg.sha256)) {
+    return { ok: false, message: 'bu:update.sha256 须为 64 位 hex 字符串' };
+  }
+  if (!Number.isSafeInteger(msg.size) || msg.size <= 0) {
+    return { ok: false, message: `bu:update.size 须为正整数（收到 ${JSON.stringify(msg.size ?? null)}）` };
+  }
+  return { ok: true };
+}
+
+function updateErrorReply(code, message, paths) {
+  return paths === undefined
+    ? { type: 'bu:update:error', code, message }
+    : { type: 'bu:update:error', code, message, paths };
+}
+
+/**
+ * 处理 bu:update（async——下载/替换是异步动作）：locateInstalls 定位 → 受管拒更 →
+ * 多命中全部应用（同一 zip 逐一 applyUpdate；任一失败聚合 error，已成功的不回滚、
+ * paths 如实全列）。依赖全注入可测（home/platform/fetch/sleep/env）。
+ * @param {{ home?: string, platform?: string, extId?: string,
+ *           fetchImpl?: Function, sleepImpl?: Function, env?: object }} [deps]
+ * @returns {Promise<{type:'bu:update:ok', from, to, paths}
+ *                 |{type:'bu:update:error', code, message, paths?}>}
+ */
+export async function handleUpdateMessage(msg, deps = {}) {
+  const check = validateUpdateMessage(msg);
+  if (!check.ok) return updateErrorReply('bad-msg', check.message);
+  try {
+    resolveNmUrl(msg.url, deps.env ?? process.env); // 白名单前置：坏 url 先拒（省一次定位）
+  } catch (err) {
+    return updateErrorReply('bad-url', err?.message ?? 'url 非法');
+  }
+  let located;
+  try {
+    located = locateInstalls({
+      home: deps.home ?? homedir(),
+      platform: deps.platform,
+      extId: deps.extId ?? EXTENSION_ID,
+      runningVersion: msg.runningVersion,
+    });
+  } catch (err) {
+    return updateErrorReply('io', `安装定位失败：${err?.message ?? err}`);
+  }
+  if (located.matches.length === 0) {
+    if (located.managed.length > 0) {
+      // 全部命中都是受管安装 → 让路 omni App（proposal 硬约束 1）
+      return updateErrorReply('managed', '安装由 FDE2E Omni 桌面版管理，插件随 App 更新', located.managed.map((m) => m.path));
+    }
+    const clue = located.rejected.length > 0
+      ? `（发现 ${located.rejected.length} 处版本不符的旧拷贝：${located.rejected.map((r) => `${r.path}（v${r.found}≠v${r.expected}）`).join('；')}）`
+      : '';
+    return updateErrorReply('not-found', `未发现运行 v${msg.runningVersion} 的 unpacked 安装${clue}`);
+  }
+  const results = [];
+  const failures = [];
+  for (const m of located.matches) {
+    try {
+      results.push(await applyUpdate({
+        url: msg.url, sha256: msg.sha256, size: msg.size, destDir: m.path,
+        ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}),
+        ...(deps.sleepImpl ? { sleepImpl: deps.sleepImpl } : {}),
+        ...(deps.env ? { env: deps.env } : {}),
+      }));
+    } catch (err) {
+      failures.push({ path: m.path, code: ['verify', 'bad-url', 'io'].includes(err?.code) ? err.code : 'io', message: err?.message ?? String(err) });
+    }
+  }
+  if (failures.length > 0) {
+    // 聚合报错但已成功的不回滚：paths 如实列出全部（成功在前、失败在后）
+    return updateErrorReply(
+      failures[0].code,
+      `已应用 ${results.length}/${located.matches.length}，失败：${failures.map((f) => `${f.path}（${f.code}：${f.message}）`).join('；')}`,
+      [...results.map((r) => r.path), ...failures.map((f) => f.path)],
+    );
+  }
+  return {
+    type: 'bu:update:ok',
+    from: results[0]?.from ?? msg.runningVersion,
+    to: results[0]?.to ?? msg.feedVersion,
+    paths: results.map((r) => r.path),
+    // 部分受管时如实让面板知情（对抗审查 P2.4——静默跳过会让「全成功」失真）
+    ...(located.managed.length > 0
+      ? { skippedManaged: located.managed.map((m) => m.path) }
+      : {}),
+  };
+}
+
 // ---------- 消息处理（依赖注入，可测） ----------
 
 function errorReply(message) {
@@ -174,17 +289,27 @@ function errorReply(message) {
 
 /**
  * 单条 NM 消息 → 应答对象（不碰流；落盘经 deps 注入，纯逻辑可测）。
+ * bu:update 走异步 handleUpdateMessage（返回 Promise——runNmHost 的写队列统一
+ * 序列化应答帧）；其余（bu:pair/未知类型）同步应答，行为不变。
  * @param {unknown} msg 解析后的 JSON 值
- * @param {{ version?: string, now?: () => string, save?: (pairing:object) => void }} [deps]
+ * @param {{ version?: string, now?: () => string, save?: (pairing:object) => void,
+ *           home?: string, platform?: string, extId?: string,
+ *           fetchImpl?: Function, sleepImpl?: Function, env?: object }} [deps]
  *   save 注入落盘动作；缺省＝写 resolveConfigDir() 下 pairing.json（调用时才解析
- *   env/家目录——测试可用 BU_CONFIG_DIR 重定向）。
+ *   env/家目录——测试可用 BU_CONFIG_DIR 重定向）。home/platform/fetchImpl/
+ *   sleepImpl/env 属 bu:update 通道（定位与下载注入）。
  * @returns {{type:'bu:pair:ok', cli:string, version:string, saved:number,
  *            received:number, truncated:boolean}
- *          |{type:'bu:pair:error', message:string}}
+ *          |{type:'bu:pair:error', message:string}
+ *          |Promise<{type:'bu:update:ok'|'bu:update:error', …}>}
  *   P1-2：received＝收到的原始条数、truncated＝扩展侧是否声明截断——截断要如实
  *   回执给 UI 显示「K 条未同步」，不再只报 saved 装作全量。
  */
 export function handleNmMessage(msg, deps = {}) {
+  // bu:update 分流（唯一异步通道）：形状校验/定位/下载全在 handleUpdateMessage 内
+  if (msg !== null && typeof msg === 'object' && !Array.isArray(msg) && msg.type === 'bu:update') {
+    return handleUpdateMessage(msg, deps);
+  }
   const version = deps.version ?? pkg.version;
   const check = validatePairMessage(msg);
   if (!check.ok) return errorReply(check.message);
@@ -235,6 +360,21 @@ export function runNmHost({ stdin = process.stdin, stdout = process.stdout, stde
         stderr.write(`nm-host: 应答帧写出失败：${err?.message ?? err}\n`);
       }
     };
+    // A2（bu-online-selfupdate）：应答帧统一经写队列串行化——bu:update 的应答是
+    // 异步产物（下载/替换），与后续消息的同步应答必须保序；同步应答只多等一个
+    // microtask，对端无感。处理异常（含 Promise 拒绝）兜底回 bu:pair:error 帧。
+    let writeChain = Promise.resolve();
+    const enqueueReply = (produce) => {
+      writeChain = writeChain.then(
+        () => Promise.resolve().then(produce).then(writeFrame, (err) => {
+          stderr.write(`nm-host: 消息处理异常：${err?.message ?? err}\n`);
+          writeFrame(errorReply(`处理异常：${err?.message ?? err}`));
+        }),
+        (err) => {
+          stderr.write(`nm-host: 应答写出失败：${err?.message ?? err}\n`);
+        },
+      );
+    };
     let buf = Buffer.alloc(0);
     // P2-1：超限帧流式丢弃——不清空整个缓冲（那会把同批到达的后续合法帧一起杀
     // 掉），改为按「4+声明长度」记账，随到达字节扣减；扣完即恢复常规解帧。
@@ -258,7 +398,7 @@ export function runNmHost({ stdin = process.stdin, stdout = process.stdout, stde
         const r = decodeFrame(buf);
         if (r.error === 'too-large') {
           stderr.write(`nm-host: 帧超限（声明 ${r.declared}B > ${MAX_FRAME_BYTES}B）——流式丢弃 ${4 + r.declared}B\n`);
-          writeFrame(errorReply(`帧超限：声明 ${r.declared}B > 上限 ${MAX_FRAME_BYTES}B`));
+          enqueueReply(() => errorReply(`帧超限：声明 ${r.declared}B > 上限 ${MAX_FRAME_BYTES}B`));
           const total = 4 + r.declared;
           const take = Math.min(buf.length, total);
           discard = total - take;
@@ -273,15 +413,10 @@ export function runNmHost({ stdin = process.stdin, stdout = process.stdout, stde
           msg = JSON.parse(r.payload);
         } catch {
           stderr.write('nm-host: 帧载荷不是合法 JSON\n');
-          writeFrame(errorReply('帧载荷不是合法 JSON'));
+          enqueueReply(() => errorReply('帧载荷不是合法 JSON'));
           continue;
         }
-        try {
-          writeFrame(handleNmMessage(msg, deps));
-        } catch (err) {
-          stderr.write(`nm-host: 消息处理异常：${err?.message ?? err}\n`);
-          writeFrame(errorReply(`处理异常：${err?.message ?? err}`));
-        }
+        enqueueReply(() => handleNmMessage(msg, deps));
       }
     });
     stdin.on('end', () => finish(0)); // 客户端断开（Chrome 端 port.disconnect）→ 干净退出 0

package/src/nm/update.mjs

@@ -0,0 +1,727 @@
+// 扩展在线自更新（change bu-online-selfupdate A1/A3）——安装目录发现＋下载应用
+// ＋`fde2e-bu update` 子命令。host 侧接线见 nm/host.mjs 的 bu:update。
+//
+// 设计要点（design C1~C5）：
+//   - locateInstalls：扫 Chrome 系浏览器根（多平台、platform 可注入）各 profile 的
+//     Preferences/Secure Preferences → extensions.settings[<extId>].path（unpacked），
+//     复核 manifest version（与 SW 上报 runningVersion 相符——防误伤旧拷贝）；
+//     受管目录（~/fde2e/bu/ 内或目录旁 .browser-extension-state.json）让路 omni App。
+//   - applyUpdate：https + 域名硬白名单（NM 路径；CLI 路径 httpsOnly 仅强制 https——
+//     C5 运维明知故为）；流式落盘＋字节数/sha256 双校验（不符不动旧目录）；
+//     staging 解压（zip-slip/条目数/根 manifest/总量四重防护——对齐 omni pack.ts
+//     extractZipSafely 语义，参数按本包收敛为 256 条/64MB）；rm+rename 原子替换
+//     （Windows 瞬态占用指数退避 6 次 250ms 起截断 8s——对齐 omni buPlugin.ts）；
+//     finally 清 temp/staging；绝不写 sidecar（受管语义归 App 写入者）。
+//   - 零运行时依赖：zip 解析手写（store + deflate via zlib，zip64 拒绝）。
+import { createHash } from 'node:crypto';
+import {
+  createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync,
+  renameSync, rmSync, writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { inflateRawSync } from 'node:zlib';
+
+/** 扩展稳定 ID（manifest 固定 key 派生）——与 nm/bind.mjs 的 EXTENSION_ID 同值；
+ * 不跨模块引用是刻意的：bind→host→update→bind 会成环（bind 顶层常量在环上 TDZ 炸），
+ * 测试以「两处常量相等」断言防漂移。 */
+export const EXTENSION_ID = 'meojillndgamkbfjijfehjaefolnfopn';
+
+/** 官方 feed（C5 缺省；--feed 可覆写——测试/私有部署）。 */
+export const DEFAULT_FEED_URL = 'https://www.fde2e.com/downloads/fde2e-bu-feed.json';
+/** feed 内相对 url 的解析基址（design B）。 */
+export const DOWNLOADS_BASE = 'https://www.fde2e.com/downloads/';
+/** NM 路径下载域名硬白名单（C3：防 feed 被用作任意下载器）。 */
+export const UPDATE_HOST_ALLOWLIST_HOST = 'www.fde2e.com';
+/** omni App 受管标记：目录旁 sidecar 文件名（proposal 硬约束 1）。 */
+export const SIDECAR_NAME = '.browser-extension-state.json';
+/** 解压防护上限（对齐 omni extractZipSafely 语义、按本包收敛的参数）。 */
+export const EXTRACT_MAX_ENTRIES = 256;
+export const EXTRACT_MAX_BYTES = 64 * 1024 * 1024;
+/** Windows 瞬态占用退避（对齐 omni buPlugin.ts 实证参数）。 */
+export const RETRY_MAX = 6;
+export const RETRY_BASE_MS = 250;
+export const RETRY_CAP_MS = 8_000;
+/** 目录替换可重试的瞬态错误码（Windows 文件占用家族；EEXIST 同族兜底）。 */
+export const TRANSIENT_FS_CODES = new Set(['EPERM', 'EBUSY', 'EACCES', 'ENOTEMPTY', 'EEXIST']);
+
+/** 更新流程错误：code ∈ bad-url|verify|io（host 侧再映射 managed/not-found/bad-msg）。 */
+export function updateError(code, message) {
+  const err = new Error(message ?? code);
+  err.name = 'UpdateError';
+  err.code = code;
+  return err;
+}
+
+// ---------- semver（C5：feed 比较只认 >；等/低 no-op） ----------
+
+/**
+ * 解析版本串（Chrome manifest 口径：1~4 段数字，可带 -prerelease/+build）。
+ * @returns {number[]|null} 数值段数组（短缺补 0 到 3 段）；不可解析 → null
+ */
+export function parseSemver(v) {
+  if (typeof v !== 'string') return null;
+  const core = v.trim().replace(/^v=/, '').replace(/^v/, '').split('+')[0];
+  const [numsRaw, pre] = core.split('-');
+  const parts = numsRaw.split('.').map((s) => (/^\d+$/.test(s) ? Number(s) : NaN));
+  if (parts.length < 1 || parts.length > 4 || parts.some((n) => !Number.isSafeInteger(n) || n < 0)) return null;
+  while (parts.length < 3) parts.push(0);
+  return { nums: parts, pre: pre === undefined ? null : pre };
+}
+
+/** semver 比较：a>b → 1、相等 → 0、a<b → -1（prerelease 按 semver 点 11：无 > 有）。 */
+export function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return NaN; // 调用方保证可解析（feed/manifest 均先校验）
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] > pb.nums[i] ? 1 : -1;
+  }
+  if (pa.pre === pb.pre) return 0;
+  if (pa.pre === null) return 1; // 无 prerelease > 有
+  if (pb.pre === null) return -1;
+  const sa = pa.pre.split('.');
+  const sb = pb.pre.split('.');
+  for (let i = 0; i < Math.max(sa.length, sb.length); i++) {
+    const x = sa[i];
+    const y = sb[i];
+    if (x === undefined) return -1; // 短前缀 < 长
+    if (y === undefined) return 1;
+    const xn = /^\d+$/.test(x);
+    const yn = /^\d+$/.test(y);
+    if (xn && yn) {
+      if (Number(x) !== Number(y)) return Number(x) > Number(y) ? 1 : -1;
+    } else if (xn !== yn) {
+      return xn ? -1 : 1; // 数值标识 < 字母数字标识
+    } else if (x !== y) {
+      return x > y ? 1 : -1;
+    }
+  }
+  return 0;
+}
+
+// ---------- C1 目录发现 ----------
+
+/**
+ * Chrome 系浏览器用户数据根（存在才扫；platform 可注入供测试）。
+ * @returns {{ label:string, root:string }[]} label ∈ chrome|chrome-beta|chrome-dev|
+ *   chrome-canary|chromium（macOS 的 Chromium 双路径同 label、按路径去重）
+ */
+export function browserScanRoots(home = homedir(), platform = process.platform) {
+  let roots;
+  if (platform === 'win32') {
+    const lad = join(home, 'AppData', 'Local'); // %LOCALAPPDATA% 缺省位置
+    roots = [
+      ['chrome', join(lad, 'Google', 'Chrome', 'User Data')],
+      ['chrome-beta', join(lad, 'Google', 'Chrome Beta', 'User Data')],
+      ['chrome-dev', join(lad, 'Google', 'Chrome Dev', 'User Data')],
+      ['chrome-canary', join(lad, 'Google', 'Chrome Canary', 'User Data')],
+      ['chromium', join(lad, 'Chromium', 'User Data')],
+    ];
+  } else if (platform === 'linux') {
+    const cfg = join(home, '.config');
+    roots = [
+      ['chrome', join(cfg, 'google-chrome')],
+      ['chromium', join(cfg, 'chromium')],
+      ['chromium', join(cfg, 'chromium-browser')],
+    ];
+  } else {
+    // macOS（及其它平台按 macOS 路径兜底——与 bind.browserManifestDirs 同策略）
+    const as = join(home, 'Library', 'Application Support');
+    roots = [
+      ['chrome', join(as, 'Google', 'Chrome')],
+      ['chrome-beta', join(as, 'Google', 'Chrome Beta')],
+      ['chrome-dev', join(as, 'Google', 'Chrome Dev')],
+      ['chrome-canary', join(as, 'Google', 'Chrome Canary')],
+      ['chromium', join(as, 'Google', 'Chromium')], // 任务规格字面路径
+      ['chromium', join(as, 'Chromium')], // macOS Chromium 平台规范路径
+    ];
+  }
+  const seen = new Set();
+  return roots.filter(([label, root]) => (seen.has(root) ? false : (seen.add(root), true)))
+    .map(([label, root]) => ({ label, root }));
+}
+
+/** profile 目录名（Chrome 约定：Default / Profile N）。 */
+export function isProfileDir(name) {
+  return name === 'Default' || /^Profile \d+$/.test(name);
+}
+
+/** 读 profile 的 Preferences/Secure Preferences → extensions.settings[extId].path。
+ * 存在 path 字段即视为 unpacked（design C1.2）；坏 JSON/无条目 → null。 */
+export function readUnpackedPath(profileDir, extId = EXTENSION_ID) {
+  for (const file of ['Preferences', 'Secure Preferences']) {
+    let data;
+    try {
+      data = JSON.parse(readFileSync(join(profileDir, file), 'utf8'));
+    } catch {
+      continue; // 不存在/坏 JSON → 换下一个来源
+    }
+    const entry = data?.extensions?.settings?.[extId];
+    if (entry && typeof entry === 'object' && typeof entry.path === 'string' && entry.path !== '') {
+      return { path: entry.path, source: file };
+    }
+  }
+  return null;
+}
+
+/** 目录内 manifest.json 的 version（缺失/坏 JSON/无 version → null）。 */
+export function readDirVersion(dir) {
+  try {
+    const m = JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8'));
+    return typeof m?.version === 'string' && m.version !== '' ? m.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 受管判定（C2）：规范化路径位于 <home>/fde2e/bu/ 内，或目录旁存在 sidecar。 */
+export function isManagedPath(absDir, home = homedir()) {
+  const managedRoot = resolve(home, 'fde2e', 'bu');
+  if (absDir === managedRoot || absDir.startsWith(managedRoot + sep)) return true;
+  return existsSync(join(dirname(absDir), SIDECAR_NAME));
+}
+
+/**
+ * 扫描本机 unpacked 安装（C1）。
+ * @param {{ home?: string, extId?: string, runningVersion?: string,
+ *           platform?: string }} opts
+ *   runningVersion 给定（NM 路径）→ manifest version 必须相等，否则进 rejected
+ *   （旧拷贝，如实列出）；undefined（CLI 路径）→ 不做版本过滤（各安装自带版本
+ *   参与后续 semver 比较）。
+ * @returns {{ matches: Array<{path, browser, profile, version}>,
+ *             rejected: Array<{path, browser, profile, reason, found?, expected?}>,
+ *             managed: Array<{path, browser, profile}> }}
+ *   跨浏览器/多 profile 引用同一目录时按规范化路径去重（首见归属）。
+ */
+export function locateInstalls({ home = homedir(), extId = EXTENSION_ID, runningVersion, platform = process.platform } = {}) {
+  const matches = [];
+  const rejected = [];
+  const managed = [];
+  const seen = new Set();
+  for (const { label, root } of browserScanRoots(home, platform)) {
+    let profiles;
+    try {
+      profiles = readdirSync(root).filter(isProfileDir);
+    } catch {
+      continue; // 根不存在/不可读 → 该浏览器无安装
+    }
+    for (const profile of profiles) {
+      const found = readUnpackedPath(join(root, profile), extId);
+      if (!found) continue;
+      const path = resolve(found.path);
+      if (seen.has(path)) continue;
+      seen.add(path);
+      const at = { path, browser: label, profile };
+      if (isManagedPath(path, home)) {
+        managed.push(at);
+        continue;
+      }
+      const version = readDirVersion(path);
+      if (version === null) {
+        rejected.push({ ...at, reason: 'no-manifest' });
+        continue;
+      }
+      if (runningVersion !== undefined && version !== runningVersion) {
+        rejected.push({ ...at, reason: 'version-mismatch', found: version, expected: runningVersion });
+        continue;
+      }
+      matches.push({ ...at, version });
+    }
+  }
+  return { matches, rejected, managed };
+}
+
+// ---------- zip 解析（零依赖：store + deflate；zip64 拒绝） ----------
+
+const EOCD_SIG = 0x06054b50;
+const CDE_SIG = 0x02014b50;
+const LFH_SIG = 0x04034b50;
+
+/** 解析 zip 中央目录（纯函数）。@returns {{ entries, base }}——base＝前缀偏移修正。 */
+export function listZipEntries(buf) {
+  const minEocd = 22;
+  const maxScan = Math.min(buf.length, minEocd + 0xffff); // EOCD + 最大注释区
+  let eocd = -1;
+  for (let i = buf.length - minEocd; i >= buf.length - maxScan && i >= 0; i--) {
+    if (buf.readUInt32LE(i) === EOCD_SIG) { eocd = i; break; }
+  }
+  if (eocd < 0) throw updateError('verify', '更新包不是合法 zip（缺少 EOCD 结尾记录）');
+  const count = buf.readUInt16LE(eocd + 10);
+  const cdSize = buf.readUInt32LE(eocd + 12);
+  const cdOff = buf.readUInt32LE(eocd + 16);
+  if (count === 0xffff || cdOff === 0xffffffff) {
+    throw updateError('verify', '更新包为 zip64 形态（不支持——本包体积上限 64MB 无需 zip64）');
+  }
+  // 前缀偏移修正（自解压头等场景：EOCD 声明的偏移与实际位置差值即前缀长度）
+  let base = 0;
+  if (cdOff + cdSize !== eocd) {
+    base = eocd - cdSize - cdOff;
+    if (base < 0) throw updateError('verify', '更新包中央目录定位失败');
+  }
+  const entries = [];
+  let p = cdOff + base;
+  for (let i = 0; i < count; i++) {
+    if (p + 46 > buf.length || buf.readUInt32LE(p) !== CDE_SIG) {
+      throw updateError('verify', '更新包中央目录损坏');
+    }
+    const method = buf.readUInt16LE(p + 10);
+    const csize = buf.readUInt32LE(p + 20);
+    const usize = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const cmtLen = buf.readUInt16LE(p + 32);
+    const lho = buf.readUInt32LE(p + 42);
+    if (csize === 0xffffffff || usize === 0xffffffff || lho === 0xffffffff) {
+      throw updateError('verify', '更新包为 zip64 形态（不支持）');
+    }
+    entries.push({
+      name: buf.subarray(p + 46, p + 46 + nameLen).toString('utf8'),
+      method,
+      csize,
+      usize,
+      lho,
+    });
+    p += 46 + nameLen + extraLen + cmtLen;
+  }
+  return { entries, base };
+}
+
+/** 解出单条目数据（store 直取；deflate 走 zlib，maxOutputLength 防单条炸弹）。 */
+function readZipEntryData(buf, entry, base) {
+  const lho = entry.lho + base;
+  if (lho + 30 > buf.length || buf.readUInt32LE(lho) !== LFH_SIG) {
+    throw updateError('verify', `更新包条目头损坏：${entry.name}`);
+  }
+  const nameLen = buf.readUInt16LE(lho + 26);
+  const extraLen = buf.readUInt16LE(lho + 28);
+  const start = lho + 30 + nameLen + extraLen;
+  const end = start + entry.csize;
+  if (end > buf.length) throw updateError('verify', `更新包条目数据截断：${entry.name}`);
+  const raw = buf.subarray(start, end);
+  if (entry.method === 0) return Buffer.from(raw);
+  if (entry.method === 8) {
+    let out;
+    try {
+      out = inflateRawSync(raw, { maxOutputLength: EXTRACT_MAX_BYTES + 1 });
+    } catch (err) {
+      if (err?.code === 'ERR_BUFFER_TOO_LARGE') throw updateError('verify', `更新包条目解压超限：${entry.name}`);
+      throw updateError('verify', `更新包条目解压失败（${err?.message ?? err}）：${entry.name}`);
+    }
+    return out;
+  }
+  throw updateError('verify', `更新包条目压缩方式不支持（method=${entry.method}）：${entry.name}`);
+}
+
+/**
+ * 安全解压（对齐 omni pack.ts extractZipSafely 语义，参数按本包收敛）：
+ * zip-slip 拒绝（规范化后必须落在 destDir 内；绝对路径/../盘符/UNC 一律拒）＋
+ * 条目数 ≤256 ＋ 根必须有 manifest.json ＋ 总解压体积 ≤64MB。
+ * @returns {object} 根 manifest.json 解析结果（含 version 等）
+ */
+export function extractZipSafely(zipPath, destDir, { rootFile = 'manifest.json', what = '更新包' } = {}) {
+  let buf;
+  try {
+    buf = readFileSync(zipPath);
+  } catch (err) {
+    throw updateError('io', `读取更新包失败：${err?.message ?? err}`);
+  }
+  const { entries, base } = listZipEntries(buf);
+  if (entries.length > EXTRACT_MAX_ENTRIES) {
+    throw updateError('verify', `${what}条目数超限（${entries.length} > ${EXTRACT_MAX_ENTRIES}）`);
+  }
+  const destAbs = resolve(destDir);
+  mkdirSync(destAbs, { recursive: true });
+  let total = 0;
+  for (const entry of entries) {
+    const name = entry.name.replace(/\\/g, '/');
+    if (name.startsWith('/') || /^[A-Za-z]:/.test(name) || name.startsWith('//')) {
+      throw updateError('verify', `${what}含非法路径条目（绝对路径）：${entry.name}`);
+    }
+    const segs = name.split('/').filter((s) => s !== '' && s !== '.');
+    if (segs.length === 0 || segs.includes('..')) {
+      throw updateError('verify', `${what}含非法路径条目（越界）：${entry.name}`);
+    }
+    const target = join(destAbs, ...segs);
+    if (target !== destAbs && !target.startsWith(destAbs + sep)) {
+      throw updateError('verify', `${what}含非法路径条目（逃逸 staging）：${entry.name}`);
+    }
+    if (name.endsWith('/')) {
+      mkdirSync(target, { recursive: true }); // 目录条目
+      continue;
+    }
+    total += entry.usize;
+    if (total > EXTRACT_MAX_BYTES) {
+      throw updateError('verify', `${what}解压总量超限（> ${EXTRACT_MAX_BYTES} 字节）`);
+    }
+    const data = readZipEntryData(buf, entry, base);
+    if (data.length !== entry.usize) {
+      throw updateError('verify', `${what}条目尺寸与目录声明不符：${entry.name}`);
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, data);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(destAbs, rootFile), 'utf8'));
+  } catch {
+    throw updateError('verify', `${what}缺 ${rootFile} 或不可解析（包结构不符）`);
+  }
+  return manifest;
+}
+
+// ---------- 下载策略（BU_UPDATE_BASE：测试/私有部署覆写） ----------
+
+/**
+ * 下载基址与白名单（NM 路径用）。BU_UPDATE_BASE 覆写＝信任重定向到指定基址
+ * （E2E 假 feed server / 私有部署用），**不是**放宽为任意域：允许域＝基址 host，
+ * http 仅当基址显式为 http（本机回环假服务器）。缺省＝www.fde2e.com 硬白名单。
+ */
+export function downloadPolicy(env = process.env) {
+  const override = env.BU_UPDATE_BASE;
+  if (override !== undefined && override !== '') {
+    let u;
+    try {
+      u = new URL(override);
+    } catch {
+      throw updateError('bad-url', `BU_UPDATE_BASE 无法解析：${override}`);
+    }
+    return {
+      base: override.endsWith('/') ? override : `${override}/`,
+      allowHost: u.hostname,
+      allowHttp: u.protocol === 'http:',
+    };
+  }
+  return { base: DOWNLOADS_BASE, allowHost: UPDATE_HOST_ALLOWLIST_HOST, allowHttp: false };
+}
+
+/** NM 路径 url 校验：相对形态按基址解析；协议/域名过白名单（C3 硬白名单）。 */
+export function resolveNmUrl(raw, env = process.env) {
+  const policy = downloadPolicy(env);
+  let u;
+  try {
+    u = new URL(String(raw), policy.base);
+  } catch {
+    throw updateError('bad-url', `下载 url 无法解析：${raw}`);
+  }
+  const wantProto = policy.allowHttp ? /^https?:$/ : /^https:$/;
+  if (!wantProto.test(u.protocol)) {
+    throw updateError('bad-url', `下载 url 协议必须 ${policy.allowHttp ? 'http(s)' : 'https'}（收到 ${u.protocol}//${u.hostname}）`);
+  }
+  if (u.hostname !== policy.allowHost) {
+    throw updateError('bad-url', `下载 url 域名不在白名单（只允许 ${policy.allowHost}，收到 ${u.hostname}）`);
+  }
+  return u;
+}
+
+// ---------- C3 下载与应用 ----------
+
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** 陈旧 temp/staging 清扫：属主 pid 已死才清（活进程的产物不动）。 */
+export function sweepStaleArtifacts(parentDir) {
+  let names;
+  try {
+    names = readdirSync(parentDir);
+  } catch {
+    return;
+  }
+  for (const n of names) {
+    const m = /^\.bu-update-(\d+)\.zip$/.exec(n) ?? /^\.browser-extension\.update-(\d+)$/.exec(n)
+      ?? /\.old-(\d+)$/.exec(n);
+    if (!m) continue;
+    const pid = Number(m[1]);
+    if (pid === process.pid) continue;
+    try {
+      process.kill(pid, 0); // ESRCH＝属主已死才可清；EPERM＝活着但无权探测 → 不清
+      continue;
+    } catch (err) {
+      if (err?.code === 'EPERM') continue;
+    }
+    try {
+      rmSync(join(parentDir, n), { recursive: true, force: true });
+    } catch { /* 清扫失败不阻断更新 */ }
+  }
+}
+
+/**
+ * 目录原子替换：三步交换（rename 旧→.old → rename staging→dest → 清 .old），任一步
+ * 瞬态占用（EPERM/EBUSY/EACCES/ENOTEMPTY，Windows 杀软/索引器/浏览器正读）指数退避
+ * 重试（6 次 250ms 起截断 8s）。第二步失败时回滚（.old → dest），旧目录始终在场——
+ * 杜绝「rm 成功 + rename 耗尽」把安装目录清空的毁灭尾迹（对抗审查 P1-1）；进程在
+ * 步骤间被杀留下的 .old-<pid>/staging 残留由 sweepStaleArtifacts 按属主探活清理。
+ * rm/rename/sleep 可注入（单测占用重试矩阵用 fast-sleep 不实等 7.9s）。
+ */
+export async function replaceDirAtomic(staging, dest, {
+  sleepImpl = defaultSleep, rmImpl = rmSync, renameImpl = renameSync,
+} = {}) {
+  const old = `${dest}.old-${process.pid}`;
+  rmImpl(old, { recursive: true, force: true });
+  const run = async (label, fn) => {
+    let lastErr;
+    for (let attempt = 0; attempt < RETRY_MAX; attempt++) {
+      try {
+        return fn();
+      } catch (err) {
+        if (!TRANSIENT_FS_CODES.has(err?.code)) {
+          const wrapped = updateError('io', `目录替换失败（${label}）：${err?.message ?? err}`);
+          wrapped.causeCode = err?.code; // 调用方按原始错误码分流（如 ENOENT＝dest 不在场）
+          throw wrapped;
+        }
+        lastErr = err;
+        if (attempt < RETRY_MAX - 1) {
+          await sleepImpl(Math.min(RETRY_BASE_MS * 2 ** attempt, RETRY_CAP_MS));
+        }
+      }
+    }
+    throw updateError('io', `目录替换失败（${label}，瞬态占用重试 ${RETRY_MAX} 次后放弃）：${lastErr?.message ?? lastErr}`);
+  };
+  // 让位：dest 存在 → rename 到 .old（瞬态退避）；dest 不存在（ENOENT＝全新安装）→ 跳过
+  let hasOld = false;
+  try {
+    await run('旧目录让位', () => renameImpl(dest, old));
+    hasOld = true;
+  } catch (err) {
+    rmImpl(old, { recursive: true, force: true });
+    if (err?.causeCode !== 'ENOENT') throw err;
+    // ENOENT：dest 不在场＝全新安装，无旧可让/可回滚
+  }
+  try {
+    await run('新目录就位', () => renameImpl(staging, dest));
+  } catch (err) {
+    if (hasOld) {
+      try { await run('回滚', () => renameImpl(old, dest)); } catch { /* 回滚也败：.old 在场，下次 sweep/重试自愈 */ }
+    }
+    throw err;
+  }
+  if (hasOld) rmImpl(old, { recursive: true, force: true });
+}
+
+/**
+ * 下载并应用更新到 destDir（C3 全流程）。
+ * @param {{ url: string, sha256: string, size: number, destDir: string,
+ *           fetchImpl?: Function, sleepImpl?: Function, httpsOnly?: boolean,
+ *           env?: object }} opts
+ *   httpsOnly（CLI 路径，C5）：只强制 https、不限域名（运维明知故为）；
+ *   缺省（NM 路径）：https + www.fde2e.com 硬白名单（BU_UPDATE_BASE 可重定向）。
+ * @returns {Promise<{from: string|null, to: string, path: string}>}
+ *   from＝旧目录 manifest version（目录缺失 → null）、to＝新包 manifest version。
+ * @throws {Error&{code:'bad-url'|'verify'|'io'}} 失败时旧目录保持原样（verify/bad-url
+ *   绝不触碰；io 仅替换阶段可能已 rm——rename 失败重试耗尽属不可恢复 IO 错）。
+ */
+export async function applyUpdate({ url, sha256, size, destDir, fetchImpl, sleepImpl, httpsOnly = false, env = process.env }) {
+  // 1. url 校验（CLI：绝对 https 任意域；NM：基址解析 + 硬白名单）
+  let u;
+  if (httpsOnly) {
+    try {
+      u = new URL(String(url));
+    } catch {
+      throw updateError('bad-url', `下载 url 无法解析：${url}`);
+    }
+    if (u.protocol !== 'https:') {
+      throw updateError('bad-url', `下载 url 协议必须 https（收到 ${u.protocol}//${u.hostname}）`);
+    }
+  } else {
+    u = resolveNmUrl(url, env);
+  }
+  if (typeof sha256 !== 'string' || !/^[0-9a-fA-F]{64}$/.test(sha256)) {
+    throw updateError('verify', 'sha256 须为 64 位 hex');
+  }
+  if (!Number.isSafeInteger(size) || size <= 0) {
+    throw updateError('verify', 'size 须为正整数');
+  }
+  const dest = resolve(String(destDir));
+  const parent = dirname(dest);
+  mkdirSync(parent, { recursive: true });
+  sweepStaleArtifacts(parent); // 前次中断残留（属主已死）顺手清
+  const tempZip = join(parent, `.bu-update-${process.pid}.zip`);
+  const staging = join(parent, `.browser-extension.update-${process.pid}`);
+  rmSync(tempZip, { force: true });
+  rmSync(staging, { recursive: true, force: true });
+  const fetchFn = fetchImpl ?? globalThis.fetch;
+  if (typeof fetchFn !== 'function') throw updateError('io', '无可用 fetch（Node >= 18）');
+
+  try {
+    // 2. 流式下载（超出 size 即断——feed 声明即预算，不做无界落盘）；
+    //    redirect:'error' 拒绝跟随 30x——白名单只校验首跳 URL（对抗审查 P2.1 收紧）
+    let res;
+    try {
+      res = await fetchFn(u.href, { redirect: 'error' });
+    } catch (err) {
+      throw updateError('io', `下载失败（${u.host}）：${err?.message ?? err}`);
+    }
+    if (!res || typeof res.ok !== 'boolean' || !res.ok) {
+      throw updateError('io', `下载失败（${u.host}）：HTTP ${res?.status ?? '???'}`);
+    }
+    if (!res.body) throw updateError('io', '下载响应无 body');
+    const source = res.body.getReader ? Readable.fromWeb(res.body) : Readable.from(res.body);
+    const hash = createHash('sha256');
+    const sink = createWriteStream(tempZip);
+    let bytes = 0;
+    try {
+      await pipeline(source, async function* verifyAndPass(chunks) {
+        for await (const chunk of chunks) {
+          bytes += chunk.length;
+          if (bytes > size) {
+            throw updateError('verify', `下载数超预期（>${size}B——feed 声明与实际不符）`);
+          }
+          hash.update(chunk);
+          yield chunk;
+        }
+      }, sink);
+    } catch (err) {
+      if (err?.code === 'verify') throw err;
+      throw updateError('io', `下载中断：${err?.message ?? err}`);
+    } finally {
+      sink.destroy();
+    }
+
+    // 3. 字节数 + sha256 双校验（不符删 temp 报 verify——绝不碰旧目录）
+    if (bytes !== size) {
+      throw updateError('verify', `字节数不符（feed=${size}，实收=${bytes}）`);
+    }
+    const hex = hash.digest('hex');
+    if (hex !== sha256.toLowerCase()) {
+      throw updateError('verify', `sha256 不符（feed=${sha256.toLowerCase()}，实算=${hex}）`);
+    }
+
+    // 4. staging 解压（zip-slip/条目/形状/总量四重防护）＋读新版本
+    const manifest = extractZipSafely(tempZip, staging);
+    if (typeof manifest?.version !== 'string' || manifest.version === '') {
+      throw updateError('verify', '更新包 manifest.json 缺 version（包结构不符）');
+    }
+    const from = readDirVersion(dest);
+
+    // 5. 原子替换（瞬态占用退避）；finally 清 temp/staging；不写任何 sidecar
+    await replaceDirAtomic(staging, dest, sleepImpl ? { sleepImpl } : {});
+    return { from, to: manifest.version, path: dest };
+  } finally {
+    rmSync(tempZip, { force: true });
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+// ---------- feed 契约（B）＋ CLI 直跑（C5） ----------
+
+/** feed 形状校验：{version, url, sha256, size} 必填（date/notes 可选）。 */
+export function validateFeed(feed) {
+  if (!feed || typeof feed !== 'object' || Array.isArray(feed)) return 'feed 须为 JSON 对象';
+  if (typeof feed.version !== 'string' || feed.version === '') return 'feed.version 须为非空字符串';
+  if (parseSemver(feed.version) === null) return `feed.version 不是合法版本串：${feed.version}`;
+  if (typeof feed.url !== 'string' || feed.url === '') return 'feed.url 须为非空字符串';
+  if (typeof feed.sha256 !== 'string' || !/^[0-9a-fA-F]{64}$/.test(feed.sha256)) return 'feed.sha256 须为 64 位 hex';
+  if (!Number.isSafeInteger(feed.size) || feed.size <= 0) return 'feed.size 须为正整数';
+  return null;
+}
+
+/**
+ * `fde2e-bu update` 子命令（C5）：发现（--ext-dir 免扫描 / 缺省 C1 扫描）→
+ * feed 检查（semver 只认 >）→ 逐目录 applyUpdate（httpsOnly）。
+ * 0 命中 exit 1＋指引；受管安装让路（含 --ext-dir 指向受管目录）；--dry-run 只报不写。
+ * @returns {Promise<number>} exit code
+ */
+export async function cmdSelfUpdate({
+  extDir, feed = DEFAULT_FEED_URL, dryRun = false,
+  home = homedir(), platform = process.platform,
+  fetchImpl, sleepImpl, env = process.env,
+} = {}) {
+  // 1. 发现（先于任何网络访问——0 命中不需要 feed）
+  let targets = [];
+  if (extDir !== undefined) {
+    const abs = resolve(String(extDir));
+    if (isManagedPath(abs, home)) {
+      console.error(`跳过：${abs} 由 FDE2E Omni 桌面版管理，插件随 App 更新。`);
+      return 1;
+    }
+    const version = readDirVersion(abs);
+    if (version === null) {
+      console.error(`--ext-dir 目录缺 manifest.json（或无 version 字段）：${abs}`);
+      return 1;
+    }
+    targets = [{ path: abs, browser: 'ext-dir', profile: '-', version }];
+  } else {
+    const found = locateInstalls({ home, platform }); // CLI 无 runningVersion：不过滤版本
+    for (const m of found.managed) console.log(`跳过（受 FDE2E Omni 桌面版管理，插件随 App 更新）：${m.path}`);
+    for (const r of found.rejected) console.log(`跳过（manifest 缺失或不可解析）：${r.path}`);
+    targets = found.matches;
+    if (targets.length === 0) {
+      console.error('未找到 unpacked 安装（0 命中）。');
+      console.error('  1. 确认浏览器已装 FDE2E 扩展（unpacked 加载）后重试；');
+      console.error('  2. 安装在非常规位置时用 --ext-dir <目录> 显式指定；');
+      console.error('  3. 受 FDE2E Omni 桌面版管理的安装随 App 更新，不走本命令。');
+      return 1;
+    }
+  }
+  console.log(`发现 ${targets.length} 处安装：`);
+  for (const t of targets) console.log(`  - ${t.path}（${t.browser}/${t.profile}，v${t.version}）`);
+
+  // 2. feed（--feed 仅强制 https——C5 运维明知故为）
+  let feedUrl;
+  try {
+    feedUrl = new URL(String(feed));
+  } catch {
+    console.error(`--feed url 无法解析：${feed}`);
+    return 1;
+  }
+  if (feedUrl.protocol !== 'https:') {
+    console.error(`--feed 必须 https（收到 ${feedUrl.protocol}//${feedUrl.host}）`);
+    return 1;
+  }
+  const fetchFn = fetchImpl ?? globalThis.fetch;
+  let feedJson;
+  try {
+    const res = await fetchFn(feedUrl.href);
+    if (!res || !res.ok) throw new Error(`HTTP ${res?.status ?? '???'}`);
+    feedJson = JSON.parse(await res.text());
+  } catch (err) {
+    console.error(`feed 获取失败（${feedUrl.href}）：${err?.message ?? err}`);
+    return 1;
+  }
+  const shapeErr = validateFeed(feedJson);
+  if (shapeErr !== null) {
+    console.error(`feed 形状不符：${shapeErr}`);
+    return 1;
+  }
+  const base = new URL('./', feedUrl).href;
+  let dl;
+  try {
+    dl = new URL(feedJson.url, base);
+  } catch {
+    console.error(`feed.url 无法按基址解析：${feedJson.url}（基址 ${base}）`);
+    return 1;
+  }
+  console.log(`feed：v${feedJson.version}（${dl.href}，${feedJson.size}B）`);
+
+  // 3. semver 比较（只认 >；等/低 no-op）
+  const due = targets.filter((t) => compareSemver(feedJson.version, t.version) > 0);
+  const fresh = targets.filter((t) => compareSemver(feedJson.version, t.version) <= 0);
+  for (const t of fresh) console.log(`已是最新（v${t.version}）：${t.path}`);
+  if (due.length === 0) {
+    console.log('没有需要更新的安装。');
+    return 0;
+  }
+  if (dryRun) {
+    for (const t of due) console.log(`[dry-run] 将更新：${t.path}（v${t.version} → v${feedJson.version}）`);
+    console.log('dry-run：未写盘。');
+    return 0;
+  }
+
+  // 4. 逐目录应用（多命中全部应用；任一失败不回滚其它——如实逐条报告）
+  let failed = 0;
+  for (const t of due) {
+    try {
+      const r = await applyUpdate({
+        url: dl.href, sha256: feedJson.sha256, size: feedJson.size, destDir: t.path,
+        ...(fetchImpl ? { fetchImpl } : {}), ...(sleepImpl ? { sleepImpl } : {}),
+        httpsOnly: true,
+      });
+      console.log(`已更新：${t.path}（v${r.from ?? '(无旧版本)'} → v${r.to}）`);
+    } catch (err) {
+      failed++;
+      console.error(`更新失败（${err?.code ?? 'io'}）：${t.path}——${err?.message ?? err}`);
+    }
+  }
+  return failed > 0 ? 1 : 0;
+}