开发

环境准备、WXT dev 模式、load unpacked、4 个调试入口、常用命令、分发流程

环境要求

  • pnpm ≥ 10.32（根目录 packageManager 已锁定）
  • Node.js ≥ 20
  • Chrome / Edge / Brave —— 任一 Chromium 内核浏览器
  • 正在运行的后端：pnpm dev:server（web 路径，ws://localhost:8001/ws/browser）或 pnpm dev:desktop（desktop 路径，ws://127.0.0.1:48123）

两种运行方式

A —— WXT dev 模式（日常迭代推荐）

pnpm dev:ext

WXT 起一个独立 Chrome profile，预装扩展，随文件改动自动 reload：

  • Popup 和 options HTML 页面有 HMR（热模块替换）
  • Background service worker 和 content scripts 改动后自动 reload
  • 终端实时输出每次 rebuild

首次运行可能提示 Chrome 可执行文件路径——可在 web-ext.config.ts 里持久化。

B —— Load unpacked（真实 profile）

需要真实登录态（Gmail 等）或验证上架前行为时用这个。

pnpm build:ext
  1. 打开 chrome://extensions
  2. 打开右上角 开发者模式 (Developer mode)
  3. 点 加载已解压的扩展程序 (Load unpacked)，选 apps/bua/.output/chrome-mv3/
  4. 把扩展图钉固定到工具栏

改代码后：pnpm build:ext → 在扩展卡片上点 🔄 刷新。

配对扩展

跑一个后端，把凭证复制到扩展 Options 里。

后端获取 serverUrl + pairingToken 的位置
Web (pnpm dev:server + pnpm dev:web)登录后访问应用的 /settings/browser-extension
Desktop (pnpm dev:desktop)同一路由，经 IPC 从 <userData>/browser-bridge-token 取回

扩展里：Options → 粘贴 Server URL + Pairing token → Save。Popup 应在一秒内切到 Connected。

4 个调试入口

入口怎么打开你看到什么
Popup点工具栏图标 → 在弹窗上右键 → 检查 (Inspect)Session 面板 React 渲染、kill switch 事件
Optionschrome://extensions → 扩展程序选项 (Extension options) → F12Allowlist CRUD、config 读 / 存 / 清空
Background SWchrome://extensions → 找到 Zapvol → 点 service worker 链接WS 连接状态、CDP attach/detach、session 状态机、agent 日志
Content script打开任意页面 → F12 → Console → 过滤 [zapvol]DOM 辅助日志、注入元素查找

Service worker 可能显示非活动 (inactive)—— MV3 正常行为。点链接会唤醒并显示最新日志；有消息进来也会触发唤醒。

常用命令

命令用途
pnpm dev:extWXT dev 模式 + HMR
pnpm build:ext构建 .output/chrome-mv3/（生产、压缩）
pnpm --filter @zapvol/bua build:firefox构建 Firefox 版
pnpm --filter @zapvol/bua zip打包 .output/*.zip 用于分发
pnpm --filter @zapvol/bua compile仅类型检查（tsc --noEmit）
pnpm --filter @zapvol/bua lintESLint

故障排查

现象可能原因解决
工具栏显示拼图图标而非 Zapvol 闪电auto-icons 没跑 / 产物过时重跑 pnpm build:ext；确认 .output/chrome-mv3/icons/ 有 16/32/48/128
Popup 一直卡在 “Connecting…”Server URL 或 pairing token 错回 /settings/browser-extension 重新复制两个值
chrome.debugger.attach 失败同 tab 开着 DevTools 或另一个调试器已挂关 DevTools；或换一个 tab
黄色调试条关不掉Chrome 强制行为 —— 是特性不是 bug等 session 结束或点横幅上的 Cancel
Agent 意外收到 domain_blocked目标域在用户 blocklist 里从 Options → Blocklist 移除该域，或换一个目标（终止错误，agent 不应重试）
Chrome 黄条 Cancel 后 action 挂住v4 前的 bug：attached set 未在 onDetach 清理v4 已修：handleDebuggerDetached 先调 debuggerController.detach(tabId) 再结束 session
Service worker 一直 inactiveMV3 空闲终止在 chrome://extensions 点链接唤醒；经 console 日志验证
Tailwind class 没生效entrypoint 漏 import "../../globals.css"每个 main.tsx 都要 import 全局样式表
扩展连不上 Electron desktop 后端防火墙 / loopback 禁用用 WS client 验证 ws://127.0.0.1:48123 可达；查 Electron 日志里的 browser-bridge.server.listening

分发（三段式）

不要跳阶段。带 debugger 权限的 BUA 扩展在 Chrome Web Store 会被额外审查，前两段走稳再提交。

阶段产出分发方式自动更新
1. 开发pnpm dev:ext → unpackedchrome://extensions → Load unpacked手动 reload
2. 内测pnpm --filter @zapvol/bua zipGitHub Release / 内部渠道用户重新安装
3. 公开同 zipChrome Web Store（$5 注册 + 隐私政策 + 审核 1–7 天）商店自动

隐私政策必须明确：扩展仅在用户显式的按域名、有时效的 session 内下发调试器命令，无后台页面内容遥测。

文件级约束

“如何新增一个 action / entrypoint / capability” 的 checklist 见 repo 里的 .claude/rules/bua.md。那个文件是贡献者的强制事实源；本页是入门导览。

这页有帮助吗？
在 GitHub 编辑