用途
Chrome Extension Best Practices 是一份针对 Chrome 扩展（Manifest V3）的性能与代码质量指南，包含 67 条规则，分为 12 个类别，并按影响程度排定优先级，用于指导自动化重构与代码生成。
何时适用
在以下情况可参考这些规则：
- 编写新的 Chrome 扩展代码
- 从 Manifest V2 迁移到 Manifest V3
- 优化 Service Worker 生命周期与状态管理
- 实现用于页面交互的内容脚本
- 调试扩展中的性能问题
规则类别与优先级
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | Service Worker 生命周期 | CRITICAL | sw- |
| 2 | 内容脚本优化 | CRITICAL | content- |
| 3 | 消息传递效率 | HIGH | msg- |
| 4 | 存储操作 | HIGH | storage- |
| 5 | 网络与权限 | MEDIUM-HIGH | net- |
| 6 | 内存管理 | MEDIUM | mem- |
| 7 | UI 性能 | MEDIUM | ui- |
| 8 | API 使用模式 | LOW-MEDIUM | api- |
| 9 | 代码风格与命名 | MEDIUM | style- |
| 10 | 组件模式 | MEDIUM | comp- |
| 11 | 错误处理 | HIGH | err- |
| 12 | 测试模式 | MEDIUM | test- |
快速参考
1. Service Worker 生命周期（CRITICAL）
- sw-persist-state-storage - 使用 chrome.storage 持久化状态，而非全局变量
- sw-avoid-keepalive - 避免人为的 Service Worker 保活模式
- sw-use-alarms-api - 使用 chrome.alarms 代替 setTimeout/setInterval
- sw-return-true-async - 在消息监听器中返回 true 以进行异步响应
- sw-register-listeners-toplevel - 在顶层注册事件监听器
- sw-use-offscreen-for-dom - 使用 offscreen 文档处理 DOM API
2. 内容脚本优化（CRITICAL）
- content-use-specific-matches - 使用具体的 URL 匹配模式
- content-use-document-idle - 使用 document_idle 注入内容脚本
- content-programmatic-injection - 优先使用以编程方式注入，而非 manifest 声明
- content-minimize-script-size - 最小化内容脚本包体积
- content-batch-dom-operations - 批量执行 DOM 操作以减少重排
- content-use-mutation-observer - 使用 MutationObserver 代替轮询
3. 消息传递效率（HIGH）
- msg-use-ports-for-frequent - 频繁消息交换使用端口连接
- msg-minimize-payload-size - 最小化消息负载大小
- msg-debounce-frequent-events - 对高频事件在发消息前进行防抖
- msg-check-lasterror - 始终检查 chrome.runtime.lastError
- msg-avoid-broadcast-to-all-tabs - 避免向所有标签页广播消息
4. 存储操作（HIGH）
- storage-batch-operations - 批量执行存储操作，而非逐次调用
- storage-choose-correct-type - 根据用例选择正确的存储类型
- storage-cache-frequently-accessed - 缓存频繁访问的存储值
- storage-use-session-for-temp - 临时运行时数据使用 storage.session
- storage-avoid-storing-large-blobs - 避免存储大型二进制块
5. 网络与权限（MEDIUM-HIGH）
- net-use-declarativenetrequest - 使用 declarativeNetRequest 代替 webRequest
- net-request-minimal-permissions - 请求最小必要权限
- net-use-activetab - 使用 activeTab 权限代替宽泛的主机权限
- net-limit-csp-modifications - 避免修改内容安全策略（CSP）响应头
6. 内存管理（MEDIUM）
- mem-cleanup-event-listeners - 内容脚本卸载时清理事件监听器
- mem-avoid-detached-dom - 避免持有已分离 DOM 节点的引用
- mem-avoid-closure-leaks - 避免意外的闭包内存泄漏
- mem-clear-intervals-timeouts - 在清理时清除 interval 与 timeout
- mem-use-weak-collections - 对 DOM 元素引用使用 WeakMap 与 WeakSet
7. UI 性能（MEDIUM）
- ui-minimize-popup-bundle - 最小化 popup 包体积以加快启动
- ui-render-with-cached-data - 优先使用缓存数据渲染 popup UI
- ui-batch-badge-updates - 批量更新徽章以避免闪烁
- ui-use-options-page-lazy - 延迟加载选项页面分区
8. API 使用模式（LOW-MEDIUM）
- api-use-promises-over-callbacks - 使用基于 Promise 的 API 调用替代回调
- api-query-tabs-efficiently - 使用具体过滤器查询标签页
- api-avoid-redundant-api-calls - 避免在循环中重复调用 API
- api-use-alarms-minperiod - 遵守 alarms API 的最小周期
- api-handle-context-invalidated - 处理扩展上下文失效错误
- api-use-declarative-content - 对页面操作使用 declarative content API
9. 代码风格与命名（MEDIUM）
- style-boolean-naming - 布尔变量使用 is/has/should 前缀
- style-cache-naming - 使用一致的缓存变量命名
- style-constants - 为魔法值定义常量
- style-directory-structure - 按功能/分层组织代码
- style-file-naming - 使用一致的文件命名约定
- style-function-naming - 使用描述性函数名
- style-import-type - 对类型使用 type-only 导入
- style-index-entry-points - 使用 index 文件作为模块入口
- style-message-enums - 消息类型使用枚举
- style-type-naming - 类型与接口使用 PascalCase
10. 组件模式（MEDIUM）
- comp-adapter-interface - 对浏览器 API 使用适配器模式
- comp-content-script-structure - 一致地组织内容脚本结构
- comp-css-class-patterns - 使用 BEM 或带前缀的 CSS 类
- comp-manager-class - 复杂状态使用管理器类
- comp-type-guards - 使用类型守卫进行运行时校验
- comp-ui-components - 创建可复用的 UI 组件
11. 错误处理（HIGH）
- err-context-invalidation - 处理扩展上下文失效
- err-early-return - 使用提前返回进行错误处理
- err-null-coalescing - 使用空值合并提供默认值
- err-promise-barrier - 使用 promise barrier 进行协调
- err-storage-operations - 处理存储操作失败
- err-url-parsing - 使用 try/catch 安全解析 URL
- err-validation-pattern - 在边界处校验输入
12. 测试模式（MEDIUM）
- test-browser-api-mocking - 在测试中 mock chrome API
- test-organization - 按功能组织测试
- test-validation-functions - 彻底测试校验函数
如何使用
阅读各个参考文件以获取详细说明与代码示例：
- Section definitions - 类别结构与影响级别
- Rule template - 添加新规则的模板
完整汇编文档
如需包含所有规则的单一完整指南，请参见 AGENTS.md。
参考文件
| 文件 | 说明 |
|---|---|
| AGENTS.md | 包含所有规则的完整汇编指南 |
| references/_sections.md | 类别定义与排序 |
| assets/templates/_template.md | 新规则模板 |
| metadata.json | 版本与参考信息 |
限制
关于该技能的具体安装方式、收费模式、价格、平台支持范围与许可信息，资料中暂未提供。