Contributing zh

参与开发

English | 中文 | 日本語 | 한국어 | Español | Português | Русский

命令

npm test                        # 全量测试（Node 内置 test runner，无需构建）
node --test test/foo.test.mjs   # 单文件
npm run package                 # 打版本 zip（browsa-vX.Y.Z.zip）
npm run build                   # esbuild 打 vendor（仅 build.mjs 变更后需要）
bash check-compat.sh            # 静态兼容检查

测试机的 4GB 约束：103 个测试文件（约 36 个 jsdom 重型）在 2C/4GB 上跑，脚本限并发 2，4GB 机器建议 --test-concurrency=1。禁止在测试里分配几十 MB 的 blob（44MB mock 曾把测试机 OOM——真事故）；优先纯函数测试（无 DOM、无大缓冲）。

测试哲学

• mock chrome 全局后导入真实模块；jsdom 测试用真实的 vendored marked/DOMPurify/katex/highlight.js bundle，不是替身。
• sidepanel.js 无导出——它的测试把整个 sidepanel.html 装进 jsdom 黑盒驱动（模拟点击/键盘/端口消息）。
• worker 客户端有模块级单例 → 需要「全新单例」的场景必须拆独立测试文件（test runner 按文件隔离进程）。
• lockstep 纪律：多处镜像的事实（正则、字段名、CSS/HINT 对、tab 顺序）要么收敛成单一来源，要么用源码正则钉住并在 AGENTS.md 记「改一处必改另一处」。例：subchat.test.mjs 正则锁定 pushSubChatChunk(… SUBCHAT_DONE …) 源码行；时间戳 lookbehind 在 lib-render 与 chat-handler-internals 两处 lockstep。
• 追问卡/流式类测试必须收尾回合（DONE / ■ / 关卡），否则 20s SW_PING setInterval 泄漏拖死 runner。
• WASM 例外：WebAssembly.instantiate 在 Node 直接跑，pdf-inspector 测试是真执行不是形状检查。

重构原则（踩坑换来的，摘自 AGENTS.md）

• N 个仅差字面量的 case → 表驱动；同协议两份手写实现 → 收一个带钩子的共享函数（DONE 处理器漂移是真 bug 家族）。
• 抽取前后全量测试 + check-compat.sh，node --check 什么都证明不了。
• 判死先全库 grep（含 test/）；测试专用导出不等于死代码——读注释。

dev-preview（无显示器环境预览扩展 UI）

node dev-preview/gen.mjs        # 从真实 sidepanel.html 生成预览页（改源 HTML 后重跑）
python3 -m http.server 8931     # 仓库根
# http://127.0.0.1:8931/dev-preview/sidepanel.preview.html

chrome-shim 提供最小 chrome.*（storage/runtime/tabs），seed.js 注入富历史。截图走 CDP Page.captureScreenshot（plain、无 clip/scale；page.screenshot() 在 dark 下有伪影）。预览通过 ≠ 真机正确：shim 的 sendMessage 回包必须逐字模拟真实信封；CSP 类验证必须真扩展加载。

发版流程

1. 版本号两处同步 bump：manifest.json + package.json。
2. PR → CI 绿 → squash 合入 main → dev 回灌：git reset --hard origin/main && git push --force-with-lease origin dev（merge 回灌会污染 main..dev；PR 页删分支会删掉 dev）。
3. 版本号 PR 走 release-flow 免测直通（PAT 模式）；CI 是共享 reusable workflows（xiaohuzai/release-flow@v1）。
4. 商店填写项用 .agents/skills/cws-listing（版本事实源 = tag）；CWS 审核被拒史有铁律记录。
5. 文档同步纪律（用户可见变更，同一 PR 内）：README 双语逐节对齐 → docs 官网双语 → 截图/banner/demo GIF/宣传片逐一考虑（按素材自身分辨率判可辨性；GIF 换内容必须换文件名防缓存）→ 架构级新事实记 AGENTS.md。

红线速查

不自动 commit/打包（等明确指示）· 打包前不跑全量测试（定点绿即打）· 版本用当前值不擅自 bump · 扩展私钥永不出 /root/workspace/browsa-keys/ · 面向用户文案无行话（zh 不夹英文术语）· 存储图片像素永不销毁 · thinking 默认 omit。

---

源头：AGENTS.md「Testing」「Refactoring principles」节、发版与打包纪律记忆、docs-sync convention。同步于 2026-10-01。