Chrome 扩展前端质量规范

已确认的工具链

包管理器是 pnpm 11.7.0，Node.js 版本范围是 >=22.22.2 <23。
共享 TypeScript 配置开启 strict: true、forceConsistentCasingInFileNames: true，模块目标是 NodeNext。
根级脚本提供 pnpm dev、pnpm build、pnpm typecheck、pnpm test、pnpm format 和 pnpm format:check；业务命令通过 --if-present 调用各包同名脚本。
仓库统一使用 Oxfmt；lint-staged 只格式化暂存文件，Husky 在 pre-commit 阶段触发该检查。
扩展包使用 Vite 6.x 和 TypeScript 5.7.x。typecheck 执行 tsc -p tsconfig.json --noEmit，build 先检查类型再执行 vite build，test 使用 Node 内置 test runner；尚无 lint 脚本。
Vite 依赖的 esbuild 安装脚本在根 pnpm-workspace.yaml 的 allowBuilds 中显式允许。
代码格式统一使用根目录 Oxfmt，缩进为 4 个空格；VSCode 保存格式化使用工作区推荐的 oxc.oxc-vscode，不得使用其它 formatter。

必须遵守

新增 TypeScript 必须通过共享配置的严格类型检查。
依赖、脚本和构建配置写入 apps/chrome-extension/package.json；不要把包专属依赖堆到根 package.json。
扩展与服务端的消息、配置和 API 数据在边界处定义类型，避免在多个组件中各自解释同一原始对象。
新增可交互 UI 时，至少验证键盘操作、错误状态和加载/空状态；具体测试工具确定后再把命令写入本文件。

禁止做法

未经任务说明直接引入 UI 框架、状态库、请求库或测试框架。
使用 any 掩盖尚未设计的接口；必须先明确类型边界。
把服务端源码、构建产物或密钥放入扩展包。
只修改一个包却随意改根 workspace 脚本，除非确实需要改变所有包的执行方式。

验证命令

pnpm format:check
pnpm typecheck
pnpm build
pnpm test

编辑器保存格式化必须与 pnpm format 相同。VSCode 使用 .vscode/settings.json 指向根 .oxfmtrc.json；未安装 Oxc 扩展时关闭 formatOnSave，不要让内置 TypeScript formatter 或其它 formatter 生成提交前会被改写的代码。

其中 typecheck 会执行严格 TypeScript 检查，build 会生成 apps/chrome-extension/dist/，test 会执行 apps/chrome-extension/test/*.test.js。新增非平凡逻辑时，应补充最小可运行测试。

评审清单

是否确认改动属于扩展包，并遵守包边界？
是否使用严格类型而不是无理由的类型断言或 any？
是否新增了尚未登记的依赖、状态或数据请求机制？
global-sources、onetalk、made-in-china 和 lib 是否遵守模块依赖方向？
Popup 移动后，Vite input、TypeScript include、Manifest 路径和 dist/ 产物是否一致？
是否覆盖了用户可见的加载、空、错误和键盘交互状态？
是否执行了当前可用的根级验证命令，并如实说明跳过项？
编辑器保存后的代码是否仍通过 Oxfmt 检查，并保持 4 个空格缩进？

3.1 KiB Raw Blame History Unescape Escape