@aibyzero/byz 0.1.1 → 0.1.3

package/workflows/cm-plugin/skills/cm-plugin-devops-engineer/references/cws-submission-checklist.md

@@ -0,0 +1,87 @@
+# Submission Checklist
+
+## Manifest (`manifest.json`)
+
+- [ ] `"manifest_version": 3`
+- [ ] `name` ≤ 45 chars
+- [ ] `version` follows semver (`1.0.0`)
+- [ ] `description` ≤ 132 chars
+- [ ] Only required permissions listed
+- [ ] No `eval`, `new Function()`, or inline script injection
+- [ ] `content_security_policy` restrictive (no `unsafe-eval`, no remote scripts)
+- [ ] `host_permissions` scoped to minimum required domains
+- [ ] `web_accessible_resources` limited to necessary files
+
+## Required Assets
+
+### Icons (PNG, no transparency issues)
+
+| Size | Use |
+|------|-----|
+| 16×16 | Favicon, extension list |
+| 32×32 | Windows taskbar |
+| 48×48 | Extensions management page |
+| 128×128 | Chrome Web Store listing |
+
+### Screenshots
+
+- Min 1, max 5
+- Dimensions: **1280×800** or **640×400** (exact)
+- Format: PNG or JPEG
+- Show real UI — no placeholder or stock images
+- Annotate key features
+
+### Promotional Images (optional but recommended)
+
+| Size | Use |
+|------|-----|
+| 440×280 | Small tile |
+| 920×680 | Large tile |
+| 1400×560 | Marquee (featured) |
+
+## Privacy Policy
+
+- Required if extension collects **any** user data
+- Must be hosted at a publicly accessible URL
+- Must describe: what data, why collected, how stored, how shared
+- Include data retention and deletion policy
+- Add URL in Developer Dashboard submission form
+
+## Permission Justifications
+
+Required for these permissions in submission form:
+
+- `tabs` — explain why tab info needed
+- `history` — explain usage
+- `bookmarks` — explain usage
+- `cookies` — explain scope and purpose
+- `<all_urls>` / broad host permissions — justify need
+- `webRequest` / `declarativeNetRequest` — explain filtering purpose
+- Any permission accessing user data
+
+## Single Purpose Compliance
+
+- Define one clear primary purpose
+- All features must serve that purpose
+- Remove unrelated functionality
+- Document purpose in description and permission justifications
+
+## Data Handling Disclosure
+
+In Developer Dashboard under "Privacy practices":
+
+- [ ] Declare what user data is collected
+- [ ] Specify data use (functionality, analytics, advertising)
+- [ ] Confirm data is not sold to third parties
+- [ ] Confirm no deceptive data use
+- [ ] List any third-party services receiving data
+
+## Build Verification
+
+- [ ] Pack extension: `zip -r extension.zip . --exclude "*.git*" "node_modules/*" "*.map"`
+- [ ] Load unpacked in Chrome to verify zip works
+- [ ] Test all features in incognito mode
+- [ ] Test on fresh Chrome profile (no existing extension state)
+- [ ] Verify all external URLs/APIs are reachable
+- [ ] Check console for errors on all extension pages
+- [ ] Confirm version number incremented from last submission

package/workflows/cm-plugin/skills/cm-plugin-doc-syncer/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: cm-plugin-doc-syncer
+description: 文档同步 Skill，开发完成后自动更新 README、.claude/ 配置、specs CHANGELOG，保持文档与代码一致
+---
+
+# cm-plugin-doc-syncer — 文档同步器
+
+在所有开发任务完成后，自动同步更新项目文档。确保文档和代码保持一致。
+
+## 触发条件
+
+由 `/cm-plugin:ai` 在所有 feature 开发完成后自动调用。
+
+## 输入
+
+- specs 文件夹路径
+- 代码项目路径（可多个）
+- LESSONS.md 中积累的架构决策
+
+## 执行步骤
+
+### 1. 扫描变更
+
+对每个代码项目，先读其 CLAUDE.md「版本控制」字段，按值选变更识别方式（显式分支，不得自行发明）：
+
+- `remote` / `local` → `git diff {基线}..HEAD` 获取变更文件。基线按序尝试：① 上一份 CHANGELOG 头部记录的 `base-commit`（见步骤 5）→ ② 无则取首个 scaffold/初始 commit → ③ 仍无法确定则按全量文件清单处理，并在输出中注明「基线不明，按全量」
+- `none` 或项目无 `.git` → **降级为文件扫描**：遍历源码目录，结合 specs 各 feature 的 tasks.md 勾选项反推本次变更集（与 cm-plugin:init 的 none 降级约定对齐）
+- 字段缺失但有 `.git` → 按 `local` 处理
+
+随后（与版本控制方式无关）：
+
+- 识别新增的目录、模块、API、数据模型
+- 从 specs 的 requirements.md 获取功能描述；requirements.md 缺失 → 该 feature 跳过描述提取并在最终输出中上报「specs 不完整」，不得凭 tasks.md 猜功能描述
+- 从 LESSONS.md 获取架构决策和踩坑记录；文件不存在 → 按 0 条处理，不报错不中断
+
+### 2. 更新 README.md
+
+对每个代码项目的 README 进行精炼更新：
+
+**必须覆盖：**
+
+- **项目简介** — 一句话说清楚是什么
+- **架构概览** — 技术栈、目录结构、核心模块关系
+- **快速开始** — 安装、配置环境变量、运行的最少步骤
+- **功能模块** — 各模块简述，本次新增的功能标注
+- **API/接口** — 扩展内消息契约概览、后端关键接口说明（如有后端）
+- **权限清单** — manifest 声明的权限及各自用途（用户和审核者都看这个）
+- **安装与发布** — 开发者模式加载步骤、构建打包命令、商店发布状态
+
+**原则：**
+
+- 精炼，开发者能在 2 分钟内理解项目全貌
+- 已有的 README 合理内容保留，只更新/补充变更涉及的部分
+- 如项目没有 README → 新建完整版
+- 不写废话，不放过时信息
+
+### 3. 更新 .claude/CLAUDE.md
+
+检查变更是否影响项目结构，保持 ≤150 行：
+
+- 新增了目录 → 更新「目录结构」
+- 新增了常用命令 → 更新「常用命令」
+- 引入了新技术栈 → 更新「技术栈」
+- 新增了 rules 文件 → 更新引用列表
+
+### 4. 更新 .claude/rules/
+
+检查变更中是否出现了新的模式或约定，按下表判据决定（满足才建，不满足不建，无中间态）：
+
+| 变更特征 | 动作 |
+| ---- | ---- |
+| 新增 ≥2 个路由/接口文件（如 `server/**`、`api/**`） | 创建 `rules/backend-api.md` |
+| 出现 manifest/扩展入口但无 `rules/chrome-extension.md` | 创建 `rules/chrome-extension.md`（缺它属规范欠账） |
+| 仅模型/工具文件 | 约定并入最近的既有 rules，不另建 |
+| 已有 rules 的 globs 与实际目录不符 | 更新 globs 路径 |
+
+新建 rules 一律用 `~/.claude/templates/cm-plugin-rules/{名称}.md` 骨架（frontmatter 含 description + globs），模板不存在则参照项目内既有 rules 的格式。
+
+本步完成后**回到步骤 3 回填** CLAUDE.md 的 rules 引用列表（步骤 3 执行时 rules 尚未定稿，引用列表以本步结果为准）。
+
+### 4.5 LESSONS.md 归档（防膨胀深井）
+
+LESSONS.md 超过 50 条时执行归档：
+
+- 归档判据（按序适用）：① 条目带 feature 标签且标签不属于当前活跃 feature → 归档；② **横切/全局决策**（不属于任何单一 feature 的约定，如"统一用 pnpm"）→ 豁免，留在主文件；③ 无标签且无法判断归属 → 留在主文件（宁留勿丢）
+- 归档条目移入 `{SPECS_DIR}/LESSONS-archive.md`（全文保留）
+- 主文件索引**按 feature 聚合为一行**（`- {feature名} {N} 条 → archive`），不逐条留行——逐条索引会让主文件列表项总数不降，归档失去防膨胀意义
+- N1/N7 只加载主文件——上下文轮换的成本因此有上界；archive 仍在审计链内随时可查
+
+### 5. 生成 specs CHANGELOG
+
+在 specs 文件夹下创建 CHANGELOG 文件，文件名日期取**执行同步的当日**（不是 feature 提交日），如 `CHANGELOG-2026-04-12.md`；同日重复执行则覆盖更新同名文件：
+
+```markdown
+# 变更日志 — 2026-04-12
+
+> base-commit: {本次同步时的 HEAD hash；版本控制 none 的项目写 none}   # 下次同步的 diff 基线，步骤 1 读取
+
+## Feature 1: {feature名}
+
+### 新增
+- {功能描述}
+
+### 关键文件
+- `{path}` — {说明}
+
+### 架构决策
+- {从 LESSONS.md 中提取的相关决策}
+
+## Feature 2: {feature名}
+
+...
+```
+
+多次开发产生多个日期文件，形成完整的变更历史。
+
+### 6. 验证文档一致性
+
+最后检查：
+
+- CLAUDE.md 中引用的 rules 文件都存在
+- rules 中的 globs 与实际目录匹配
+- README 中的命令与 package.json / Makefile 一致
+- 环境变量文档与 `.env.example` 一致
+
+发现不一致时按两态处理（修复方向一律**以代码/配置为准改文档**，不得反向改代码）：
+
+- **只改文档就能一致**（如 README 写错命令、CLAUDE.md 引用了不存在的 rules）→ 修复并计数
+- **需要改代码/配置/新建非文档文件才能一致**（如 `.env.example` 缺失、脚本指向不存在的文件）→ **不修**，在输出「一致性」行报「发现 N 处待人工」——doc-syncer 无权创建或修改文档之外的任何文件
+
+## 禁止（红线，违反任何一条即任务失败）
+
+- **不得虚构**：接口、命令、权限用途、环境变量只写代码或 specs 中实际存在的；桩实现/空函数按 specs 口径描述时必须注明「以 specs 为准，实现未完成」
+- **不得删除用户手写内容**：README 中无法从代码/specs 再生的段落（徽章、致谢、许可、手写背景说明）一律原样保留，更新只增改与变更相关的部分
+- **不得触碰文档之外的文件**：代码、配置、`.env*`、CI 一律只读；发现问题只上报「待人工」，不代修
+- **归档不得丢条目**：归档前后条目总数必须守恒（主文件活跃条数 + archive 条数 = 原总数），执行后自查一次
+- **代码与 specs 不符时不得按 specs 想象功能**：以代码实际行为为准描述，差异作为「待人工」写入 CHANGELOG 上报
+
+## 输出
+
+```text
+📝 文档同步完成
+
+README: {更新/新建} {N} 个项目
+CLAUDE.md: {更新/无变化}
+Rules: {新增 N 个 / 更新 N 个 / 无变化}
+CHANGELOG: {N} 个 feature
+一致性: {PASSED / 有 N 处已修复 / 发现 N 处待人工}   # 三态可并存，如「2 处已修复,1 处待人工」
+```

package/workflows/cm-plugin/skills/cm-plugin-extension-engineer/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: cm-plugin-extension-engineer
+description: 浏览器扩展工程师 Skill，执行 Chrome 扩展（MV3）开发任务——manifest、service worker、content script、popup/options/side panel、消息通信、chrome.storage，自动适配脚手架（WXT/Plasmo/CRXJS/原生）
+---
+
+# cm-plugin-extension-engineer — 浏览器扩展工程师
+
+执行 Chrome 扩展（Manifest V3）开发任务。自动识别项目脚手架与技术栈，遵循项目 `.claude/rules/` 中的规范（`chrome-extension.md` 是本工种铁律）。
+
+## 触发条件
+
+由 `/cm-plugin:ai` 自动调用，当 task 涉及扩展本体开发时触发（manifest / service worker / content script / 各 UI 表面 / 存储 / 消息通信）。
+
+**与 cm-plugin-ui-engineer 的分工**：feature 存在设计基准（design-baseline/）时，popup/options/side panel 的 UI 还原由 `cm-plugin-ui-engineer` 前置完成——本 skill **直接消费其组件与 design.md 组件契约，不重写其样式**；无基准时 UI 按 design.md 自行实现。
+
+**与 cm-plugin-backend-engineer 的分工**：配套服务端（API 代理、账号、同步）归后端工种；本 skill 只写扩展侧的调用层。**API 密钥等机密永远不进扩展包**——扩展包等于公开源码，需要密钥的调用必须走后端代理，发现 design.md 让密钥落在扩展侧时停下上报。
+
+## 工作流程
+
+### 1. 识别脚手架与技术栈
+
+读取项目配置自动判断，不做硬编码假设：
+
+- **脚手架**：`wxt.config.ts` → WXT（entrypoints 目录约定，manifest 由配置生成）；`plasmo` 依赖 → Plasmo（文件名即入口约定）；`@crxjs/vite-plugin` → CRXJS（手写 manifest + Vite）；都没有 → 原生（手写 manifest，注意构建产物路径）
+- **manifest 源头**：先弄清 manifest 是手写文件还是构建生成——改错地方（直接改 dist 里的生成物）是脚手架项目最常见的白改
+- `package.json` → UI 框架（React/Vue/Svelte/原生）、样式方案、构建工具
+- 目标浏览器（CLAUDE.md「交付形态」字段）→ 是否经 webextension-polyfill 调 API、是否有双 manifest 构建
+
+### 2. 读取上下文
+
+- `.claude/rules/chrome-extension.md`、`frontend.md`、`coding-style.md`（如存在）
+- design.md 中当前任务相关的模块设计与**消息契约**
+- 扫描现有代码，弄清三件事：各表面入口在哪、消息通信封装在哪（有封装必须复用，禁止散落裸调 `chrome.runtime.sendMessage`）、storage 读写层在哪
+
+### 3. 开发
+
+**manifest 纪律（每次触碰都过一遍）：**
+
+- 只声明本任务确需的权限；能用 `activeTab` 就不申请 `host_permissions`，能窄匹配（`*://example.com/*`）就不用 `<all_urls>`
+- 新增任何 permission / host_permission → 在任务汇报里写一行用途理由（商店提审要用，人审要看）
+- manifest 变更不与业务代码混在一个提交里静默带过，提交信息单独说明
+
+**service worker（MV3 后台）：**
+
+- **它会随时休眠，全局变量必然丢**——跨事件状态一律落 `chrome.storage.session`/`local`，不留内存
+- 事件监听器必须在顶层同步注册，不得包在 async 初始化之后（休眠唤醒时只重放顶层注册）
+- 没有 DOM——需要解析 DOM/播放音频/用 canvas 时走 offscreen document，用完即关
+- 定时任务用 `chrome.alarms`，不用 `setTimeout`/`setInterval`（休眠即失效）
+
+**content script：**
+
+- 运行在 isolated world：与宿主页共享 DOM、不共享 JS 变量；需要读宿主页 JS 状态时注入 main world 脚本并用 postMessage 桥接
+- 注入 UI 必须做样式隔离（shadow DOM 优先，或强前缀 class）——宿主页样式什么都可能覆盖你，你也不许污染宿主页
+- 宿主页是 SPA 时，URL 变化不触发重新注入——监听路由变化（`Navigation API`/history hook/MutationObserver 择一），初始化要幂等
+- 对宿主页 DOM 结构的依赖集中到选择器常量层，宿主页改版时只改一处
+
+**消息通信：**
+
+- 严格按 design.md 消息契约实现（type / payload / 响应结构）；契约没写的消息形状，先补进 design.md 的口径再写码，不各写各的
+- 异步响应要 `return true`（callback 风格）或统一用 Promise 风格，一个项目只用一种
+- 高频通信（如 devtools/side panel 实时数据）用 `chrome.runtime.connect` 长连接，不高频轮发单次消息
+
+**存储：**
+
+- 分区按用途：`sync`（小体量用户设置，注意 100KB/8KB per-item 配额）、`local`（大数据）、`session`（service worker 临时状态）
+- 读写统一走项目的 storage 封装层，schema 变更要写迁移逻辑（老用户的存量数据不会自己变形状）
+
+**UI 表面（popup / options / side panel）：**
+
+- popup 每次打开都是全新页面且失焦即销毁——不在 popup 里放长任务，长任务交 service worker，popup 只读状态
+- 组件复用、样式方案、状态管理遵循 frontend.md 与项目既有模式
+
+### 4. 验证
+
+```bash
+# 根据项目实际命令执行
+npm run lint
+npm run typecheck
+npm run build
+```
+
+**构建产物必须真实加载验证**（扩展的"编译通过"与"能跑"距离极远，也是 N5 运行观察闸的要求）：项目有 E2E 基座（bootstrap T-005 从 `~/.claude/templates/cm-plugin-e2e/` harness 建的）→ 跑冒烟用例，**读全 passed/failed 计数**；没有 → 至少本机 Chrome 开发者模式 Load unpacked 一次，确认 manifest 无报错、service worker 注册成功、本任务触碰的表面能打开。加载验证结果写进任务汇报。
+
+## 常见坑
+
+| 问题 | 处理 |
+| ---- | ---- |
+| service worker 全局变量"莫名"丢失 | 休眠所致，状态迁到 chrome.storage.session |
+| 监听器时灵时不灵 | 注册被包进了 async 流程，移到顶层同步注册 |
+| content script 读不到宿主页 JS 变量 | isolated world 隔离，注入 main world 脚本桥接 |
+| 注入 UI 被宿主页样式打爆 | shadow DOM 包裹，不裸放 DOM |
+| SPA 网站切页后功能失效 | 监听路由变化重挂载，初始化写成幂等 |
+| sendMessage 响应一直 undefined | 接收端异步未 `return true`，或消息发给了已休眠且无该监听的目标 |
+| chrome.storage.sync 写入报配额错 | 超 8KB/item 或 100KB 总量，大数据改 local |
+| 改了 manifest 不生效 | 改的是构建生成物；找到源头（wxt.config/plasmo 约定/源 manifest）再改 |
+| CSP 报错 eval/远程脚本被拒 | MV3 禁止，改为打包进产物；第三方库依赖 eval 的换库 |
+| Firefox 行为不一致 | API 名与回调风格差异，统一走 webextension-polyfill |
+
+## 输出
+
+- 创建/修改的文件列表
+- 验证结果（lint + typecheck + build + 真实加载冒烟）
+- manifest/权限变更及用途理由（无则写"无"）
+- 新增或依赖的消息契约（无则写"无"）
+- 需要其他工种配合的事项

package/workflows/cm-plugin/skills/cm-plugin-product-manager/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: cm-plugin-product-manager
+description: 产品经理 Skill，负责需求分析、用户故事与验收标准编写、歧义清单生成、变更影响分析、业务验收走查；把关型角色，不做技术设计与技术测试
+---
+
+# cm-plugin-product-manager — 产品经理
+
+把关型角色：把需求问对、拆对、验收对。**本 skill 的产出是结构化的问题和标准，业务拍板永远是人**——绝不替用户做业务决策。
+
+## 触发条件
+
+- `/cm-plugin:prd` 需求分析阶段（Step 5 / 5.5）自动调用
+- `/cm-plugin:prd --change` 变更影响分析（Step C4）时调用
+- `/cm-plugin:ai` 的 N6 中，feature 完成触发的 QA 通过后，执行业务验收走查
+
+## 职责边界
+
+- **管**：需求提取、用户故事、验收标准、优先级建议、歧义识别、变更影响分析、业务验收走查
+- **不管**：技术设计（→ 各工种 skill）、技术测试（→ cm-plugin-qa-engineer）、业务决策（→ 人）
+
+## 工作流程
+
+### 1. 需求分析（服务 /cm-plugin:prd Step 5）
+
+**输入前置**：原始需求文档缺失、为空或不可读 → 直接上报「输入不完整」终止本步，不得凭目录名/项目名想象需求；文档存在但某功能只有标题无描述 → 该功能整体进歧义清单，不产出想象的 AC。
+
+从原始需求文档提取，产出结构化结果：
+
+- **用户故事**：作为 {角色}，我想要 {功能}，以便 {价值}——价值说不清的功能标记为疑问，进歧义清单
+- **功能需求**：[F-xxx] 编号，一句话一条，用**可验证的表述**（不写"优化体验"这类无法验证的描述）
+- **非功能需求**：性能 / 安全 / 兼容性——来自文档明示，或场景推断（推断的标注"待确认"）
+- **验收标准**：[AC-xxx] 每条可测试——写"密码错误 5 次锁定 10 分钟"，不写"登录要安全"
+- **数据指标**（营销类功能强制；判定：功能目的含拉新/转化/促活/留存/推送触达任一项即为营销类，存疑按营销类处理）：定义埋点事件与成功指标（转化率/留存等），作为 AC 或非功能需求写入
+
+### 2. 歧义清单（服务 Step 5.5，反问式）
+
+对每个功能过一遍五问，答不上的进开放问题清单：
+
+1. 目标用户是谁？多角色时权限差异是什么？
+2. 边界在哪？本期做到什么程度，明确**不做**什么？交付形态是否与现有项目一致（存量插件项目上出现"网站/App/后台系统"字样、或要求新增表面（如从 popup 扩到 content script 注入）= 架构变更信号，必须显式确认）？
+3. 什么算成功？有没有可观察的完成判据？
+4. 异常怎么办？失败 / 超时 / 冲突时用户看到什么？
+5. 有没有敏感操作？支付 / 删除 / 隐私相关 → 必须人工确认；插件专属追问：这个功能需要**新增权限或读取用户页面数据**吗（权限扩张与数据收集都是商店合规与用户信任的敏感面）？
+
+**克制原则**：只列真正无法合理推断的问题；可以合理默认的写成"默认 X，如不符请指出"——不做无限追问式的确认（SuperPowers 的教训）。
+
+### 3. 拆分与优先级建议（服务 Step 6-7）
+
+- feature 按**用户可感知的完整功能**切，不按技术层切（技术分层是 task 的事）
+- MVP 优先：主流程 feature 在前，增强类在后
+- 标注 feature 间依赖，给执行顺序建议
+
+### 4. 变更影响分析（服务 --change 模式）
+
+- 对比新旧需求 → 新增 / 修改 / 删除清单
+- 影响面评估：波及哪些**已完成任务**（返工风险）、哪些验收标准失效
+- 输出变更摘要供人审，不自行决定取舍
+
+### 5. 业务验收走查（服务 N6，feature 级 QA 通过后）
+
+技术测试归 QA，本步是**用户视角**的走查：
+
+- **AC 逐条对照**：每条标注 通过 / 不通过 / 需人工验证，**结果回写 requirements.md 的 AC checkbox**（与 QA 的技术核验共用同一落盘位置）。**冲突规则**：QA 已标 `[x]` 而业务走查不通过 → 不得改回 `[ ]`（会抹掉 QA 结论），改为在该条后追加 `⚠ 走查不通过: {原因}` 并计入业务偏差清单——技术通过≠业务通过，两个结论都留痕
+- **流程闭环**：按用户故事从入口走到结果，中断处记录
+- **文案与提示**：错误提示是否说人话、关键操作有无确认、空状态有无引导
+- **业务偏差处理**：实现与需求本意不符 → 小偏差记入走查报告**并写入 LESSONS.md**（走查报告是会话输出，落盘靠 LESSONS）；涉及需求本意的偏差 → **暂停问人**，不自行认定"也可以"
+
+## 常见坑
+
+| 问题 | 处理 |
+| ---- | ---- |
+| 验收标准写成技术指标 | AC 用用户可观察的行为表述，技术指标归入非功能需求 |
+| 需求按技术层拆成 feature | 按用户可感知功能切；前端/后端分工是 task 层的事 |
+| 歧义问题一次问太多 | 只问无法合理默认的，其余写"默认 X，如不符请指出" |
+| 业务走查时替用户拍板 | 偏差只记录和上报，是否接受由人决定 |
+| 用户故事沦为格式套话 | 写不出"以便 {价值}"的功能，本身就是一个开放问题 |
+
+## 输出
+
+- **需求分析**：用户故事 + 编号功能需求 + 验收标准（直接进 requirements.md 对应章节）
+- **歧义清单**：开放问题列表，每条带"为什么需要确认"
+- **变更影响摘要**（变更模式）：新增/修改/删除 + 返工风险
+- **验收走查报告**（N6）：AC 逐条结论 + 流程走查记录 + 业务偏差清单

package/workflows/cm-plugin/skills/cm-plugin-qa-engineer/NOTICE.md

@@ -0,0 +1,14 @@
+# NOTICE — 第三方收编素材
+
+本 skill 的 `references/` 下两个文件收编自外部开源仓库：
+
+- 来源：[quangpl/browser-extension-skills](https://github.com/quangpl/browser-extension-skills)（MIT License, Copyright (c) 2026 quangpl）
+- 收编日期：2026-07-18
+- 文件与改动：
+
+| 本仓库文件 | 上游文件 | 改动 |
+| ---- | ---- | ---- |
+| `references/cws-scan-checklist.md` | `skills/extension-review/references/scan-checklist.md` | 仅重命名，内容未改动（grep 路径 `src/` 按项目实际结构调整的指引写在本 skill SKILL.md，不改上游原文） |
+| `references/cws-violation-codes.md` | `skills/extension-review/references/violation-codes.md` | 仅重命名，内容未改动 |
+
+上游许可为 MIT，允许再分发；本文件即为许可与来源声明的履约载体。

package/workflows/cm-plugin/skills/cm-plugin-qa-engineer/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: cm-plugin-qa-engineer
+description: QA 工程师 Skill，执行功能测试、E2E 测试、可视化回归、验收标准核验，自动适配项目测试框架
+---
+
+# cm-plugin-qa-engineer — QA 工程师
+
+在开发任务完成后执行整体质量验证。自动识别项目测试框架。
+
+## 触发条件
+
+由 `/cm-plugin:ai` 自动调用，当 task 涉及测试或全部开发完成后触发。
+
+## 工作流程
+
+### 1. 识别测试框架
+
+自动检测，不做硬编码假设：
+
+- **单元/组件测试**：Vitest / Jest / Mocha（`chrome.*` API 在单测里用 mock 层——检查项目是否已有统一 mock，没有则建一个共享的，禁止每个测试文件各 mock 各的）
+- **E2E 测试（扩展专用姿势）**：**优先用 `~/.claude/templates/cm-plugin-e2e/extension-harness.ts` 封装的底座**（bootstrap T-005 应已拷入 `tests/e2e/`）——它把五个实测坑封装好了：系统 Chrome 屏蔽 `--load-extension`（须 Chrome for Testing）、`--headless=new`（旧 headless 不支持扩展、`headless:false` 无头环境退化）、SW 注册-停机竞态（`acquireServiceWorker` 三路取先到）、`sw.evaluate` 前须 `wakeServiceWorker` 取活引用（否则 "Worker was closed"）、CfT 跨架构路径。**别自己手写 `launchPersistentContext`**，会重踩。popup 用 `chrome-extension://{id}/popup.html` 直开断言。项目无 harness（旧包/非 bootstrap 建）→ 从模板补建
+- **覆盖率工具**：c8 / istanbul
+- 如项目未配置测试框架，根据技术栈推荐并安装（E2E 基座应由 bootstrap T-005 建好，缺失时补建并记 LESSONS）
+
+### 2. 读取上下文
+
+- requirements.md 中的验收标准
+- design.md 了解功能模块和接口契约
+- `.claude/rules/testing.md`（如存在）
+- 扫描现有测试文件了解测试模式和覆盖情况
+
+### 3. 补全测试
+
+对开发阶段未写测试的代码补充：
+
+- **组件**：渲染测试、交互测试、Props 边界
+- **消息通信层**：每个消息 type 的正常流/异常 payload/无响应超时——契约是扩展的接口，测它等于测 API
+- **存储层**：chrome.storage 读写封装、schema 迁移逻辑（老数据形状喂进去不炸）
+- **service worker 生命周期**：关键状态在"休眠丢内存"前提下仍正确（测试里主动清内存态模拟唤醒）
+- **content script**：注入幂等（重复注入不重复挂 UI）、目标站点 DOM 选择器仍命中（选择器层单独可测）
+- **工具函数**：输入输出覆盖
+- **配套后端**（如有）：API 正常流、异常流、migration 可执行
+
+遵循项目已有的测试文件命名和目录约定。
+
+**二开回归范围跟波及面走**：design.md 存在「波及面」段时，回归测试范围 = 新功能 AC + 波及面清单上的存量功能逐项冒烟——新功能好不好是一半，老功能没坏才是另一半。
+
+**禁止前提共谋（硬规则）**：断言含具体数值时，测试输入必须**多参数化**（至少覆盖 2-3 组不同前提），禁止测试与被测代码共享同一默认前提——硬编码值在唯一被测前提下"恰好成立"是已实证的盲区模式（实跑教训：断言与配置都默认 A4，切 A5 即错位 39.9mm，参数化后现形）。
+
+### 4. 运行测试
+
+```bash
+# 根据项目实际命令执行
+npm run test              # 或 pnpm test / cargo test / pytest
+npm run test -- --coverage  # 覆盖率
+npx playwright test       # E2E
+```
+
+收集：通过数/失败数/覆盖率。
+
+### 5. 可视化回归（如涉及 UI）
+
+1. 以 `--load-extension` 启动加载构建产物的浏览器（popup/options/side panel 在扩展上下文里截，content script UI 在真实目标页面上截；不用脱离扩展上下文的 dev server 页面充数）
+2. 选择浏览器驱动（按优先级）：
+   - **检查项目配置**：如 `.claude/rules/testing.md` 中指定了 `browser_driver`，使用用户指定的方式
+   - **默认：Playwright CDP（无头模式）** — 不弹窗，适合截图对比、DOM 断言、样式回归等大多数场景
+   - **自动升级：Chrome DevTools MCP** — 当检测到以下场景时切换：需要登录态/Cookie 持久化、OAuth/第三方弹窗交互、需要观察真实动画/过渡效果、用户明确要求实时调试
+   - 切换前输出：`🔄 切换到 Chrome DevTools MCP — 原因: {原因}，浏览器窗口将弹出`
+3. 截图保存
+4. 对比基准截图（如有）
+
+> **用户覆盖**：在 `.claude/rules/testing.md` 中添加 `browser_driver: playwright | chrome-mcp | ask` 可固定选择或设为每次询问。
+
+### 6. 验收标准核验
+
+逐条检查 requirements.md 中的验收标准：
+
+```markdown
+- [x] [AC-001] 描述 → 已通过测试验证
+- [ ] [AC-002] 描述 → ⚠️ 需手动验证
+```
+
+标注每条的验证方式（自动/手动/无法自动化）。
+
+**核验结果必须回写 requirements.md 的验收标准 checkbox**（`[x] [AC-001] → 已通过测试验证`），不得只留在会话输出中——验收状态和任务状态一样落盘。
+
+### 6.5 商店合规检查单（涉及权限/数据收集/远程内容的 feature 必跑）
+
+被 N6 走查、/cm-plugin:prd 预扫或 devops 发布前自查引用时，逐项核对并输出结论（**把关型检查：只举旗列清单，不自行定性"能过审"**）。
+
+**检测方法（机器优先，肉眼兜底）**：先按 `references/cws-scan-checklist.md` 跑 grep 检测模式（12 类风险，源自 MIT 收编素材，见 NOTICE.md；模式里的 `src/` 路径按项目实际结构替换——WXT 是 `entrypoints/`，Plasmo 是根目录约定，manifest 按构建产物扫）；命中项的严重级与官方违规码对照 `references/cws-violation-codes.md`（CRITICAL=必拒 / HIGH=大概率拒 / MEDIUM=可能拒），举旗时带上违规码名（如 Purple Potassium），被拒申诉时能直接对上 Chrome 的拒审邮件。
+
+人工核对项：
+
+- [ ] **权限最小化**：manifest 中每个 permission / host_permission 都能对到一个已实现功能；有对不上的 → 举旗"冗余权限"
+- [ ] **单一用途**：本次 feature 与扩展声明的单一用途描述一致；功能开始发散（工具箱化）→ 举旗
+- [ ] **数据披露**：实际收集/传输的用户数据（浏览记录、页面内容、表单输入、身份信息）逐项在隐私政策与商店数据披露表覆盖；代码里传了政策里没写的 → 举旗
+- [ ] **禁远程代码**：无 eval / new Function / 远程加载执行的 JS（远程取配置、取数据可以，取可执行代码不行）
+- [ ] **内容注入克制**：content script 的 matches 范围与功能必要性一致；未经用户触发的页面改写、广告注入类行为 → 举旗
+- 结论固定格式：`商店合规: 通过 / {N} 项举旗（逐条: 检查项[违规码] → 证据位置 → 建议）`，举旗项由主流程交人裁决
+
+### 7. 处理失败
+
+- 测试失败 → 判断是代码 bug 还是测试问题
+- 代码 bug → 汇报给主 agent，重新执行开发任务
+- 测试问题 → 修复测试，重新运行
+- 最多重试 3 轮
+
+## 常见坑
+
+| 问题                     | 处理                                   |
+| ------------------------ | -------------------------------------- |
+| 测试环境和开发环境不一致 | 检查 test 配置中的环境变量和 mock 设置 |
+| 异步测试超时             | 增加 timeout，检查是否缺少 await       |
+| E2E 测试不稳定（flaky）  | 用 `waitFor` 代替固定延时，重试机制    |
+| 覆盖率统计不准           | 检查 coverage 配置的 include/exclude   |
+| E2E 里扩展没加载         | 系统 Chrome 屏蔽 --load-extension → 用 Chrome for Testing + `--headless=new`（harness 已封装） |
+| E2E 时好时坏(flaky)      | 多因 `headless:false` 在无头/CI 退化 或 SW 停机竞态——改用 harness 的 `--headless=new` + `acquireServiceWorker` |
+| sw.evaluate "Worker was closed" | SW 已 idle 停机——用 `wakeServiceWorker(ctx, extId)` 取活引用再 evaluate |
+| service worker 取不到    | 它可能已休眠——先触发一次扩展事件唤醒再 `serviceWorkers()` |
+| chrome.* mock 行为与真实不符 | mock 只兜单测；行为断言以 E2E 真实浏览器为准，两层结论冲突时信 E2E |
+
+## 输出
+
+```text
+📋 QA 报告
+
+测试: {N} 通过 / {N} 失败 / 覆盖率 {N}%
+E2E: {状态}（真实浏览器加载扩展）
+验收标准: {N}/{total} 通过, {N} 需手动验证
+商店合规: {通过 / N 项举旗 / 未触发}
+安全扫描: {状态}
+结论: {PASSED / FAILED / NEEDS_MANUAL}
+```