sillyspec 3.8.4 → 3.8.6

package/templates/quick.md

@@ -0,0 +1,135 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+## 核心约束（必须遵守）
+- ❌ 不写测试（底线是仍然要写测试）
+- ❌ 修改无关文件
+- ❌ 跳过测试因为"任务太简单"
+
+## 用法
+
+- `/sillyspec:quick "修复用户创建接口漏了手机号校验"` — 独立记录到按用户名隔离的 QUICKLOG
+- `/sillyspec:quick --change user-module "修复用户创建接口漏了手机号校验"` — 追加到 user-module 变更的 tasks.md
+
+## 任务
+$ARGUMENTS
+
+---
+
+## 流程
+
+1. **解析参数：** 检查是否携带 `--change <变更名>`，确定记录方式
+1.5 **归属检查：** 如果没有 `--change` 参数，检查 `.sillyspec/changes/` 下是否有非 archive 的活跃变更目录：
+   ```bash
+   ls -d .sillyspec/changes/*/ 2>/dev/null | grep -v archive
+   ```
+   - 有活跃变更 → AskUserQuestion 询问本次 quick 归属哪个变更，默认选当前活跃的
+   - 用户选择后将日志写入 `.sillyspec/changes/<变更名>/quicklog/` 而非独立 QUICKLOG
+   - 用户选择"无归属" → 走原有的独立 QUICKLOG 流程
+   - 无活跃变更 → 走原有的独立 QUICKLOG 流程
+2. **理解任务：** 模糊则问一个问题确认
+3. **加载上下文：** `cat .sillyspec/docs/<project>/scan/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null`
+3b. **编码规范扫描：** 检测项目中的编码规范配置文件（`.eslintrc*`、`.prettierrc*`、`tsconfig.json`、`.editorconfig`、`tailwind.config.*`、`CONTRIBUTING.md`），提取关键规则生成摘要。写作代码时必须严格遵守这些规则（分号/引号/缩进/命名风格等），如不确定优先遵守规范约束。
+4. **知识库查询（强制步骤）：**
+   ```bash
+   cat .sillyspec/knowledge/INDEX.md 2>/dev/null
+   ```
+   根据当前任务描述中的关键词匹配 INDEX.md 条目，命中时 `cat` 对应知识文件，将内容纳入后续开发考量。未命中则跳过。
+   **MCP 检测：** 检查当前可用工具列表中是否存在 MCP 工具（Context7/浏览器/数据库/搜索等），根据检测结果动态利用：
+   - 有 Context7 → 查询不熟悉库/API 的最新文档
+   - 有浏览器 MCP → 验证页面改动效果
+   - 有数据库 MCP → 查询表结构和数据验证（只读）
+   - 有搜索 MCP → 搜索最佳实践和解决方案
+   - 有其他 MCP → 按任务需要灵活使用
+   - 无 MCP → 使用 web search
+5. **先读后写：** 调用已有方法前 `cat` 源文件确认签名，`grep` 确认方法存在
+6. **数据操作安全：** 任何改变现有数据的操作（非 SELECT 的数据库操作）必须暂停并报告给用户确认，不得自动执行。新建表不受此限制
+6. **TDD 执行：**
+   ```
+   🔴 RED    → 先写测试，运行确认失败
+   🟢 GREEN  → 写最少代码让测试通过
+   🔵 REFACTOR → 清理，保持测试通过
+   ✅ STAGE   → git add 暂存（测试文件必须包含在暂存中）
+   ```
+   测试文件必须保留在项目中，不能删除。违反 TDD → 删掉代码从测试重新开始。
+   - 纯配置/数据/文档可跳过 TDD
+   - 其他情况一律走 TDD
+7. **运行测试：** 先检查 local.yaml 构建命令配置：
+```bash
+cat .sillyspec/local.yaml 2>/dev/null
+```
+如果有则使用 local.yaml 中的命令；否则使用默认命令：
+```bash
+mvn test -pl <模块> -Dtest=<测试类> 2>/dev/null || ./gradlew test --tests <测试类> 2>/dev/null || pnpm test 2>/dev/null || npm test 2>/dev/null || pytest <测试文件> 2>/dev/null
+```
+8. **Lint 校验（如项目配置了）：** 写完代码后、暂存前，运行项目的 lint 工具验证代码质量：
+   ```bash
+   # 检测并运行可用的 lint 工具
+   npx eslint <修改的文件> 2>/dev/null || \
+   npx prettier --check <修改的文件> 2>/dev/null || \
+   npx tsc --noEmit 2>/dev/null || \
+   true  # 没有 lint 工具则跳过
+   ```
+   - **有报错 → 自动修复：** `npx eslint --fix <修改的文件>` / `npx prettier --write <修改的文件>`
+   - **修复后仍有报错 → 在 QUICKLOG 中标注，提醒用户手动处理**
+   - **工作区模式下，在子项目目录中执行，不要在主项目目录执行**
+9. **Git 暂存：** `git add -A`。**不要 commit**，由用户通过 `/sillyspec:commit` 统一提交。**工作区模式下，确认当前在正确的子项目目录中执行暂存。**
+10. **记录：**
+   - **有 `--change`：** 在 `.sillyspec/changes/<变更名>/tasks.md` 追加 task 并勾选，**记录精确到秒的时间戳**：
+
+```
+- [x] [YYYY-MM-DD HH:MM:SS] 任务描述
+```
+   - **无 `--change` 但步骤 1.5 确认了归属变更：** 记录到 `.sillyspec/changes/<变更名>/quicklog/YYYY-MM-DD-HHMMSS-任务简述.md`，格式：
+
+```markdown
+# quick: 任务描述
+
+- 时间：YYYY-MM-DD HH:MM:SS
+- 关联变更：<变更名>
+- 修改文件：
+  - `path/to/file1`
+  - `path/to/file2`
+- 改动说明：（2-3 句描述做了什么）
+- 发现的坑：（如有，简要记录）
+```
+
+   - **无 `--change` 且无归属：** 记录到 `.sillyspec/quicklog/QUICKLOG-<git用户名>.md`（见下方规则）
+10. **检查复杂度：** 任务比预期复杂 → 建议用完整流程
+
+11. **记录发现的坑：** 执行过程中如果发现项目特有的规律、陷阱或约定（如"某方法参数顺序容易搞反"、"某表有隐藏软删除字段"），追加到 `.sillyspec/knowledge/uncategorized.md`，格式：
+
+```markdown
+### [待确认] {简短标题}
+> 来源：quick / {时间戳}
+
+{坑的具体描述}
+```
+
+**工作区模式下：** 只影响当前子项目 → 写入当前子项目 `.sillyspec/knowledge/uncategorized.md`；影响多个子项目 → 写入工作区根目录 `.sillyspec/knowledge/uncategorized.md`。
+
+12. **知识库审阅提示：** 如果本次执行向 knowledge/ 写入了新条目，提示用户：
+> 📚 本次 quick 发现了新知识，请审阅：`cat .sillyspec/knowledge/uncategorized.md`
+> 确认后请将 `[待确认]` 改为 `[已确认]`，并可归类到 knowledge/ 下的专题文件中更新 INDEX.md。
+
+### QUICKLOG 规则
+
+**按 git 用户名隔离，避免多人同时操作冲突：**
+
+```bash
+USER=$(git config user.name 2>/dev/null || echo "default")
+LOG_FILE=".sillyspec/quicklog/QUICKLOG-${USER}.md"
+```
+
+文件路径：`$LOG_FILE`
+
+**追加记录格式（时间精确到秒）：**
+```markdown
+## YYYY-MM-DD HH:MM:SS | fix: 任务描述
+- 文件：`修改的文件列表`
+- 关联归档：`相关的已归档变更名`（如有）
+```
+
+**文件轮转：** 追加前检查文件大小，超过 500 行则：
+1. 将当前文件重命名为 `QUICKLOG-${USER}-YYYY-MM-DD.md`
+2. 创建新的空 `QUICKLOG-${USER}.md`

package/templates/scan-quick.md

@@ -0,0 +1,49 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+> 本模板由 `/sillyspec:scan --quick` 触发。如需完整深度扫描，使用 `/sillyspec:scan`。
+
+## 核心约束（必须遵守）
+- ❌ 修改任何代码
+- ❌ 编造文件路径或代码模式（必须包含真实路径）
+- ❌ 读源码文件（快扫只读配置和目录）
+
+## 快速扫描流程
+
+### Step 1: 检查工作区模式
+
+```bash
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .
+```
+
+有 `projects` 字段 → 工作区模式：逐个子项目快扫。
+
+### Step 2: 读配置文件
+
+```bash
+cat package.json tsconfig.json requirements.txt Cargo.toml go.mod pom.xml build.gradle 2>/dev/null
+find . -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null
+```
+
+### Step 3: 生成文档
+
+`mkdir -p .sillyspec/codebase`，生成 4 份文档：
+
+1. **ARCHITECTURE.md** — 架构 + 技术栈（合并原 STACK.md）
+2. **STRUCTURE.md** — 目录结构（`find . -type f | head -200`）
+3. **CONVENTIONS.md** — 空骨架文件，含章节标题（注意事项、代码风格等），供后续 quick/execute 追加
+4. **PROJECT.md** — 项目概览
+
+### Step 4: 暂存修改
+
+```bash
+git add .sillyspec/
+```
+
+工作区模式在每个子项目分别暂存。
+
+💡 扫描产出已暂存。准备好后用 `/sillyspec:commit` 提交。
+
+### 完成
+
+提示用户：快扫只提取基础信息。如需完整代码规范（框架规则、实体继承、代码风格），执行 `/sillyspec:scan` 进行深度扫描。

package/templates/scan.md

@@ -0,0 +1,172 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+你现在是 SillySpec 代码库扫描器（编排器）。**你不读源码，只编排子代理或串行执行。**
+
+## 参数处理
+- 空白 → 交互式引导（逐步询问）
+- `--deep` → 直接深度扫描
+- 其他 → 快速扫描该区域
+
+## 流程控制（必须先执行）
+
+```bash
+cat .sillyspec/STATE.md 2>/dev/null
+```
+
+有 STATE.md 且 phase 为 `scan` 或未记录 → 继续。
+其他 phase → STATE.md 中记录的下一步命令为准。
+
+---
+
+## 交互式引导（参数为空时）
+
+### 检查工作区 & 已有文档
+
+```bash
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .   # 有子项目配置 → 工作区模式
+ls .sillyspec/docs/<project>/scan/ 2>/dev/null       # 检查已有文档
+wc -l .sillyspec/docs/<project>/scan/*.md 2>/dev/null
+```
+
+- 已有 3 份 → 建议升级深度扫描
+- 已有 7 份 → 建议刷新或跳过
+- 工作区 → 逐个扫描 / 选子项目 / 退出
+
+### 选择扫描模式、范围、排除目录、确认
+按原流程交互，确认后进入扫描。
+
+---
+
+## 构建环境探测（主代理执行）
+
+```bash
+cat package.json pom.xml build.gradle go.mod Cargo.toml requirements.txt pyproject.toml Gemfile composer.json 2>/dev/null
+find . -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null
+```
+
+结果保存到 `.sillyspec/docs/<project>/scan/_env-detect.md`（临时文件，扫描完删除）。
+
+---
+
+## 深度扫描
+
+`mkdir -p .sillyspec/codebase`
+
+### 断点续扫
+
+```bash
+for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT; do
+  [ -f ".sillyspec/docs/<project>/scan/${f}.md" ] && echo "✅ ${f}.md" || echo "⬜ ${f}.md"
+done
+```
+
+只生成缺失的文档。
+
+### 检测子代理可用性
+检查是否有 Task/Spawn 工具。有 → 子代理模式，无 → 串行模式。
+
+---
+
+### 子代理模式（4 个并行）
+
+#### Agent 1: tech → ARCHITECTURE.md
+扫描技术栈 + 数据库 Schema + 架构模式。参考 `_env-detect.md`。
+用 grep/rg 搜索（`@Entity`、`schema.prisma`、`models.py` 等），**禁止读源码全文**。
+Schema 只记表名+说明+字段数。含 `## 技术栈` `## 架构概览` `## 数据模型（摘要）`。路径用反引号，不编造。
+
+#### Agent 2: conventions → CONVENTIONS.md
+扫描框架隐形规则 + 实体继承 + 代码风格。参考 `_env-detect.md`。
+用 grep 搜索拦截器/插件/逻辑删除/基类/审计字段，**禁止读源码全文**。
+根据检测到的语言/框架自行决定搜索什么模式，提取 3-5 个典型示例。
+含 `## 框架隐形规则` `## 实体继承规范` `## 代码风格`。路径用反引号，不编造。
+
+#### Agent 3: structure → STRUCTURE.md + INTEGRATIONS.md
+扫描目录结构 + 外部集成。参考 `_env-detect.md`。
+用 find/ls/tree 和 grep，**禁止读源码全文**。
+搜索 API 调用、MQ 配置、缓存、第三方 SDK。STRUCTURE.md 含目录树+模块说明。INTEGRATIONS.md 按类型分组。路径用反引号，不编造。
+
+#### Agent 4: quality → TESTING.md + CONCERNS.md + PROJECT.md
+扫描测试现状 + 技术债务 + 项目概览。参考 `_env-detect.md`。
+用 grep 搜索测试文件、TODO/FIXME、过时依赖，**禁止读源码全文**。
+TESTING.md 含测试结构。CONCERNS.md 按严重程度分组。PROJECT.md 含项目信息。路径用反引号，不编造。
+
+---
+
+### 串行模式（降级）
+无子代理时，按 tech → conventions → structure → quality 顺序执行。
+每个 area 完成后**立即写文件**，下一个 area 开始前清除源码上下文。
+
+---
+
+## 工作区模式
+对每个子项目：cd → 环境探测 → 扫描 → cd 回工作区。
+全部完成后汇总 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`（只读各子项目的 ARCHITECTURE.md + CONVENTIONS.md）。
+
+---
+
+## 扫描完成
+
+```bash
+# 路径校验
+for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT; do
+  [ -f ".sillyspec/docs/<project>/scan/${f}.md" ] && echo "✅ ${f}.md"
+done
+
+# 生成知识库骨架
+mkdir -p .sillyspec/knowledge
+if [ ! -f ".sillyspec/knowledge/INDEX.md" ]; then
+  cat > .sillyspec/knowledge/INDEX.md << 'EOF'
+# Knowledge Index
+
+> 子代理任务开始前查询此文件，按关键词匹配，只读命中的知识文件。
+> execute/quick 执行中发现的坑自动追加到 uncategorized.md，经用户确认后归类到对应文件。
+
+<!-- 格式：关键词1|关键词2|关键词3 → 文件路径 -->
+<!-- 示例：mybatis-plus|分页|Page → pagination.md -->
+<!-- 示例：跨域|CORS|preflight → cors.md -->
+EOF
+fi
+if [ ! -f ".sillyspec/knowledge/uncategorized.md" ]; then
+  cat > .sillyspec/knowledge/uncategorized.md << 'EOF'
+# 未分类知识
+
+> execute/quick 执行中发现的坑暂存于此，用户审阅后归类到对应文件并更新 INDEX.md。
+
+EOF
+fi
+
+# 更新状态
+cat > .sillyspec/STATE.md << 'EOF'
+# 项目状态
+
+## 当前阶段
+- 阶段：scan ✅
+- 下一步：/sillyspec:brainstorm
+
+## 关键决策
+- （扫描中发现的技术决策）
+
+## 历史记录
+- $(date '+%Y-%m-%d %H:%M:%S') scan 完成
+EOF
+
+# 清理
+rm -f .sillyspec/docs/<project>/scan/_env-detect.md
+git add .sillyspec/
+```
+
+💡 扫描产出已暂存。准备好后用 `/sillyspec:commit` 提交。
+
+### 自检门控
+- [ ] ARCHITECTURE.md：技术栈 + Schema 摘要？
+- [ ] CONVENTIONS.md：隐形规则 + 代码风格？
+- [ ] STRUCTURE.md：目录结构？
+- [ ] INTEGRATIONS.md：外部依赖？
+- [ ] TESTING.md：测试现状？
+- [ ] CONCERNS.md：技术债务？
+- [ ] PROJECT.md：项目概览？
+
+## 绝对规则
+- ❌ 修改代码 / 编造路径 / 主代理读源码全文
+- ✅ 交互模式每步等用户 / 文档只写 `.sillyspec/docs/<project>/scan/`

package/templates/skills/playwright-e2e/SKILL.md

@@ -0,0 +1,340 @@
+---
+name: playwright-e2e
+description: Playwright E2E 测试编写参考。当任务涉及编写端到端测试、浏览器自动化测试、Playwright 测试用例时自动读取，不要凭记忆编写 Playwright API。
+---
+
+# Playwright E2E 测试编写参考
+
+> ⚠️ 执行 E2E/测试任务时必须先读取此文件，不要凭训练数据记忆编写 Playwright API。
+
+## 测试基本结构
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('功能名称', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/');
+  });
+
+  test('具体场景', async ({ page }) => {
+    // Arrange
+    // Act
+    // Assert
+  });
+});
+```
+
+## 选择器优先级
+
+```typescript
+// ✅ 最推荐：data-testid（最稳定）
+await page.locator('[data-testid="submit-btn"]').click();
+
+// ✅ 推荐：role-based（语义化）
+await page.getByRole('button', { name: 'Submit' }).click();
+await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+// ✅ 推荐：文本匹配
+await page.getByText('Sign in').click();
+await page.getByText(/welcome back/i).click();
+
+// ✅ 可用：语义 HTML
+await page.locator('button[type="submit"]').click();
+await page.locator('input[name="email"]').fill('test@test.com');
+
+// ❌ 避免：CSS 类名和 ID（重构易变）
+// await page.locator('.btn-primary').click();
+// await page.locator('#submit').click();
+```
+
+## 断言
+
+```typescript
+// URL
+await expect(page).toHaveURL('/dashboard');
+await expect(page).toHaveURL(/.*dashboard/);
+
+// 文本
+await expect(page.locator('h1')).toHaveText('Welcome');
+await expect(page.locator('.message')).toContainText('success');
+await expect(page.locator('.items')).toHaveText(['Item 1', 'Item 2']);
+
+// 可见性
+await expect(page.locator('.modal')).toBeVisible();
+await expect(page.locator('.spinner')).toBeHidden();
+await expect(page.locator('button')).toBeEnabled();
+await expect(page.locator('input')).toBeDisabled();
+
+// 数量
+await expect(page.locator('.item')).toHaveCount(3);
+
+// 输入值
+await expect(page.locator('input')).toHaveValue('test@example.com');
+```
+
+## 表单操作
+
+```typescript
+// 文本输入
+await page.getByLabel('Email').fill('user@example.com');
+await page.getByPlaceholder('Enter your name').fill('John Doe');
+
+// 清空再输入
+await page.locator('#username').clear();
+await page.locator('#username').type('newuser', { delay: 100 });
+
+// 复选框
+await page.getByLabel('I agree').check();
+await page.getByLabel('I agree').uncheck();
+
+// 单选按钮
+await page.getByLabel('Option 2').check();
+
+// 下拉选择
+await page.selectOption('select#country', 'usa');
+await page.selectOption('select#country', { label: 'United States' });
+
+// 多选下拉
+await page.selectOption('select#colors', ['red', 'blue']);
+
+// 文件上传
+await page.setInputFiles('input[type="file"]', 'path/to/file.pdf');
+await page.setInputFiles('input[type="file"]', ['file1.pdf', 'file2.pdf']);
+```
+
+## 鼠标与键盘
+
+```typescript
+// 点击
+await page.click('button');
+await page.click('button', { button: 'right' });  // 右键
+await page.dblclick('button');                     // 双击
+
+// 悬停
+await page.hover('.menu-item');
+
+// 拖拽
+await page.dragAndDrop('#source', '#target');
+
+// 键盘
+await page.keyboard.type('Hello', { delay: 100 });
+await page.keyboard.press('Control+A');
+await page.keyboard.press('Enter');
+await page.keyboard.press('Tab');
+```
+
+## 测试数据准备
+
+```typescript
+// ⚠️ E2E 测试不能因为"没有数据"就跳过！必须确保测试数据存在。
+
+// 方案 1：通过 API 创建前置数据（推荐）
+test.beforeEach(async ({ request }) => {
+  // 调用项目 API 创建测试所需数据
+  const resp = await request.post('/api/test/setup', {
+    data: { createUser: true, createOrder: true }
+  });
+  expect(resp.ok()).toBeTruthy();
+});
+
+// 方案 2：使用 storageState 复用认证状态
+// 先登录一次保存状态，后续测试直接复用
+test.use({ storageState: 'tests/auth/user.json' });
+
+// 生成认证状态的脚本：
+// npx playwright codegen --save-storage=tests/auth/user.json http://localhost:3000/login
+
+// 方案 3：通过数据库 MCP 直接插入数据（有数据库 MCP 时）
+// 在 beforeEach 中调用数据库 MCP 执行 INSERT 语句准备数据
+
+// 方案 4：API Mock（不需要真实数据）
+test('显示用户列表', async ({ page }) => {
+  await page.route('**/api/users', route => {
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([{ id: 1, name: 'Test User' }])
+    });
+  });
+  await page.goto('/users');
+  await expect(page.locator('.user-name')).toHaveText('Test User');
+});
+
+// 清理：测试后清理数据，避免影响其他测试
+test.afterEach(async ({ request }) => {
+  await request.post('/api/test/cleanup');
+});
+```
+
+**铁律：E2E 测试禁止因"没有数据"跳过。** 必须通过以上任一方案准备数据，确保测试可独立运行。
+
+## 弹窗与 iframe
+
+```typescript
+// 新窗口/弹窗
+const [popup] = await Promise.all([
+  page.waitForEvent('popup'),
+  page.click('button.open-popup'),
+]);
+await popup.waitForLoadState();
+
+// iframe
+const frame = page.frameLocator('#my-iframe');
+await frame.locator('button').click();
+```
+
+## 截图
+
+```typescript
+// 全页截图
+await page.screenshot({ path: 'screenshot.png', fullPage: true });
+
+// 元素截图
+await page.locator('.chart').screenshot({ path: 'chart.png' });
+
+// 视觉回归对比（首次生成基线，后续对比）
+await expect(page).toHaveScreenshot('homepage.png');
+
+// ⚠️ playwright.config.ts 中配置失败自动截图：
+// screenshot: 'only-on-failure'（已包含在上方 config 模板中）
+```
+
+## 等待策略
+
+```typescript
+// ✅ 推荐：自动等待（Playwright 内置）
+await expect(page.locator('.loaded')).toBeVisible();
+
+// ✅ 推荐：等待 URL 变化
+await page.waitForURL('**/dashboard');
+
+// ✅ 推荐：等待网络响应
+const responsePromise = page.waitForResponse('**/api/users');
+await page.click('button#load-users');
+const response = await responsePromise;
+
+// ❌ 避免：硬编码 sleep
+// await page.waitForTimeout(3000);
+```
+
+## Page Object Model
+
+```typescript
+// pages/LoginPage.ts
+export class LoginPage {
+  constructor(private page: Page) {}
+
+  async goto() {
+    await this.page.goto('/login');
+  }
+
+  async login(email: string, password: string) {
+    await this.page.getByLabel('Email').fill(email);
+    await this.page.getByLabel('Password').fill(password);
+    await this.page.getByRole('button', { name: 'Submit' }).click();
+  }
+}
+
+// tests/login.spec.ts
+import { test, expect } from '@playwright/test';
+import { LoginPage } from '../pages/LoginPage';
+
+test('登录成功', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+  await loginPage.goto();
+  await loginPage.login('test@example.com', 'password123');
+  await expect(page).toHaveURL('/dashboard');
+});
+```
+
+## API Mock（隔离后端）
+
+```typescript
+test('显示用户列表', async ({ page }) => {
+  await page.route('**/api/users', route => {
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([{ id: 1, name: 'Test User' }])
+    });
+  });
+
+  await page.goto('/users');
+  await expect(page.locator('.user-name')).toHaveText('Test User');
+});
+```
+
+## 常见错误
+
+### ❌ 用 CSS 类名选择元素
+```typescript
+await page.click('.btn-primary');  // 脆弱！重构就坏
+```
+
+### ✅ 用 data-testid
+```typescript
+await page.click('[data-testid="submit-btn"]');  // 稳定
+```
+
+### ❌ 测试之间有依赖
+```typescript
+test('步骤1：登录', async ({ page }) => { /* ... */ });
+test('步骤2：需要先登录', async ({ page }) => { /* 依赖步骤1，脆弱 */ });
+```
+
+### ✅ 每个测试独立
+```typescript
+test.beforeEach(async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('test@example.com');
+  await page.getByLabel('Password').fill('password');
+  await page.getByRole('button', { name: 'Submit' }).click();
+  await expect(page).toHaveURL('/dashboard');
+});
+```
+
+### ❌ 不处理异步状态
+```typescript
+await page.click('[data-testid="submit"]');
+await expect(page.locator('.result')).toBeVisible();  // 可能还没加载完
+```
+
+### ✅ 等待操作完成
+```typescript
+await page.click('[data-testid="submit"]');
+await expect(page.locator('.result')).toBeVisible({ timeout: 10000 });
+```
+
+## playwright.config.ts 模板
+
+```typescript
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  timeout: 30000,
+  use: {
+    baseURL: 'http://localhost:3000',  // ⚠️ 根据项目实际端口调整
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  webServer: {
+    command: 'npm run dev',           // ⚠️ 根据项目实际命令调整
+    port: 3000,
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+## 调试命令
+
+```bash
+npx playwright test --headed       # 有头模式
+npx playwright test --debug         # 调试模式（带 inspector）
+npx playwright test --slowmo=1000   # 慢放
+npx playwright show-report          # 查看报告
+npx playwright codegen URL          # 录制生成代码
+```