MV3 扩展工程骨架：五个入口、一个 manifest，和一条「build 过了但类型是错的」

import { defineManifest } from '@crxjs/vite-plugin';
import pkg from '../package.json';

export default defineManifest({
  manifest_version: 3,
  name: '效率工具',
  version: pkg.version,          // ← 只在 package.json 改一处

  // 自托管更新：Chrome 周期性拉这个 XML，里面写着最新版本号 + .crx 地址
  update_url: 'https://example.com/updates.xml',

  // ★ 固定扩展 ID = 这个公钥对应的那串。见下面那段说明
  key: '<你的 .crx 私钥对应的公钥，SPKI DER base64>',

  action: {
    default_popup: 'src/popup/index.html',
    // 工具栏图标显式给 16/24/32：不写的话 Chrome 拿最近的尺寸缩到 16，
    // 高 DPI 屏还要再缩一次，线条会发虚
    default_icon: { 16: 'icons/icon16.png', 24: 'icons/icon24.png', 32: 'icons/icon32.png' },
  },

  // ⚠ side_panel 一旦存在，Chrome 强制要求 default_path。
  //   空对象 {} 会报「Manifest key is required」直接加载不了。
  //   「只在某些标签页显示」靠 background 的 per-tab setOptions 控制，不是靠这里
  side_panel: { default_path: 'src/sidepanel/index.html' },

  options_ui: { page: 'src/options/index.html', open_in_tab: true },
  background: { service_worker: 'src/background/index.ts', type: 'module' },

  content_scripts: [ /* 见下 */ ],

  // ★ content script 用 fetch 读扩展自带的文件，必须在这里声明，否则被拦
  web_accessible_resources: [
    { resources: ['local-auth-whitelist.signed.json', 'icons/*'], matches: ['https://app.example.com/*'] },
  ],

  permissions: ['storage', 'scripting', 'activeTab', 'cookies', 'alarms', 'sidePanel', 'tabs'],
  host_permissions: ['https://app.example.com/*'],
});

async function bootstrap(): Promise<void> {
  // 1) 第一件事：打构建标记 + 当前在哪个 frame。
  //    走 debug 级（默认关）—— 页面 iframe 多，每个 frame 都打一条属于噪音
  log.debug(BUILD_TAG, isTopFrame() ? '(top)' : `(iframe ${location.pathname})`);

  // 2) 配置必须先就绪：后面所有读配置的地方都假定它已经 init 过
  const cfg = await configClient.init();

  // 3) ★ 布局相关的东西立刻启动，并且单独 try/catch
  //    原来它在最下面，结果被后面某个 await 卡住 → 表现为「面板不挂载」
  try { startLayoutTweaks(); } catch (e) { log.error('startLayoutTweaks error:', e); }

  // 4) 仅顶层帧：工具栏、监控桥、自动回复……每个都单独 try/catch
  if (isTopFrame()) {
    try { mountHeaderOrb(); } catch (e) { log.error('mountHeaderOrb error:', e); }
    try { startMonitorBridge(); } catch (e) { log.error('startMonitorBridge error:', e); }
    try { await initAutoReply(); } catch (e) { log.error('initAutoReply error:', e); }
  }

  // 5) 键位注册：**所有 frame**。焦点可能落在任意 iframe 里
  keybindingManager.register(/* … */);
  keybindingManager.install();
}

- run: npm run build
# 类型检查：存量债清零后提升为硬 gate —— 新增类型错误直接 fail CI
- run: npm run typecheck