sillyspec 3.8.5 → 3.8.7

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          # 录制生成代码
+```

package/templates/status.md

@@ -0,0 +1,75 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+## 核心约束（必须遵守）
+- ❌ 修改任何文件（只读）
+
+---
+
+## 流程
+
+### Step 1: 检查工作区模式
+
+```bash
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .
+```
+
+**工作区模式：** 读取每个 `projects/*.yaml` 子项目列表，对每个子项目检查 PROJECT.md、docs/<project>/scan/ 文档数、进行中变更、归档数。**同时检查工作区根目录 `.sillyspec/changes/` 下的未归档变更。** 检查共享规范和工作区概览。输出汇总后结束，不执行单项目流程。
+
+工作区变更检查命令：
+```bash
+# 工作区根目录的变更
+ls .sillyspec/changes/ 2>/dev/null | grep -v archive
+ls .sillyspec/changes/archive/ 2>/dev/null | wc -l
+
+# 每个子项目的变更
+for f in .sillyspec/projects/*.yaml; do
+  [ -f "$f" ] || continue
+  proj_name=$(basename "$f" .yaml)
+  proj_path=$(grep '^path:' "$f" | head -1 | sed 's/^path:[[:space:]]*//')
+  echo "=== $proj_name changes ==="
+  ls "$proj_path"/.sillyspec/changes/ 2>/dev/null | grep -v archive
+  ls "$proj_path"/.sillyspec/changes/archive/ 2>/dev/null | wc -l
+done
+```
+
+**汇总输出格式：**
+```
+📊 SillySpec 状态
+📋 工作区模式 — N 个子项目
+
+工作区变更：
+  🔄 进行中：sec-bonus-penalty（tasks: 3/5）
+  ✅ 已归档：1 个
+
+主项目（工作区根目录）：
+  📂 代码库文档：— （主项目通常无独立代码）
+  🔄 进行中：N 个变更
+  ✅ 已归档：N 个变更
+
+┌───────────────────┬────────────┬────────────┬────────┬────────┐
+│ 子项目            │ PROJECT.md │ 代码库文档 │ 进行中 │ 已归档 │
+├───────────────────┼────────────┼────────────┼────────┼────────┤
+│ back-service      │ ✗          │ 7 份       │ 1      │ 0      │
+└───────────────────┴────────────┴────────────┴────────┴────────┘
+```
+
+**单项目模式：** 继续 Step 2。
+
+### Step 2-5: 单项目检查
+
+1. **项目基础：** PROJECT.md、docs/<project>/scan/ 文档、REQUIREMENTS.md、ROADMAP.md
+2. **进行中变更：** 对每个变更检查 design/tasks 完成度
+3. **归档历史：** `ls .sillyspec/changes/archive/ | wc -l`
+4. **代码库文档：** `ls .sillyspec/docs/<project>/scan/`
+
+### Step 6: 输出
+
+```
+📊 SillySpec 状态
+📋 项目：xxx（已初始化/未初始化）
+📂 代码库：已扫描（7 份文档）/ 未扫描
+🔄 进行中：N 个变更
+✅ 已归档：N 个变更
+💡 下一步：/sillyspec:continue
+```

package/templates/verify.md

@@ -0,0 +1,236 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+> **可选阶段。** execute 完成后会询问是否需要 verify，也可以手动调用。
+
+## 核心约束（必须遵守）
+- ❌ 修改任何代码（只做检查和报告）
+- ❌ 自行推进到下一阶段
+
+
+
+## 工作区模式处理
+
+如果 `.sillyspec/projects/` 目录下有 yaml 文件：
+
+1. 检查工作区根目录 `.sillyspec/changes/` 下的未归档变更
+2. 检查每个子项目 `<子项目路径>/.sillyspec/changes/` 下的未归档变更
+3. 列出所有未归档变更，让用户选择要验证哪个
+4. 根据 $ARGUMENTS 或用户选择，cd 到对应目录执行验证
+
+---
+
+## 流程
+
+### 1. 加载规范
+
+```bash
+# 确定变更目录
+if [ -n "$ARGUMENTS" ]; then
+  CHANGE_DIR=".sillyspec/changes/$ARGUMENTS"
+else
+  CHANGE_DIR=$(ls -d .sillyspec/changes/*/ 2>/dev/null | grep -v archive | tail -1)
+fi
+cat "$CHANGE_DIR"/{design,tasks}.md 2>/dev/null
+cat .sillyspec/local.yaml 2>/dev/null
+```
+
+锚定确认实际存在的文件。
+
+### 2. 逐项检查 tasks.md
+
+对每个 checkbox 报告：✅ 已完成 / ❌ 未完成 / ⚠️ 部分完成
+
+### 3. 对照 design.md
+
+架构决策？文件变更一致性？数据模型？API 设计？
+
+### 4. 运行测试套件
+
+```bash
+pnpm test 2>/dev/null || npm test 2>/dev/null || pytest 2>/dev/null || go test ./... 2>/dev/null
+```
+
+### 4b. E2E 测试
+
+检测项目中是否有 E2E 测试或测试步骤文件：
+```bash
+ls tests/e2e/ e2e/ cypress/e2e/ 2>/dev/null | head -5
+cat .sillyspec/changes/*/e2e-steps.md 2>/dev/null | head -5
+```
+
+**无任何测试** → 跳过此步骤。
+
+**有测试** → 确认修复策略（AskUserQuestion）：
+1. 自动修复，同一用例最多 5 次（超过停止，提示人工介入）
+2. 一直修复直到全绿
+3. 只报告，不自动修复
+
+**按优先级执行：**
+
+**优先级 1：专业 E2E 框架（Playwright/Cypress）**
+```bash
+npx playwright test 2>/dev/null || npx cypress run 2>/dev/null
+```
+
+**优先级 2：通用测试框架（jest/vitest）**
+```bash
+npx vitest run 2>/dev/null || npx jest 2>/dev/null
+```
+
+**优先级 3：浏览器 MCP + e2e-steps.md（兜底）**
+读取 `.sillyspec/changes/<变更名>/e2e-steps.md`，按步骤逐条执行。每条标注 ✅/❌，断言失败记为 FAILED。
+> ⚠️ 使用 MCP 执行时 AI 判断可能不如测试框架精确。追求可靠性建议安装 Playwright。
+
+**自动修复循环（选了策略 1 或 2 时）：**
+
+必须按以下流程严格执行，不可跳过：
+
+```
+ROUND = 1
+MAX_ROUNDS = 策略1时为5，策略2时为50
+
+while ROUND <= MAX_ROUNDS:
+    1. 运行失败测试，捕获完整输出（错误信息、堆栈、期望值 vs 实际值）
+    2. 如果全部通过 → 跳出循环，标记 ✅
+    3. 读取 .sillyspec/local.yaml 中当前变更的 fixAttempts
+    4. 对每个失败测试：
+       a. 如果 fixAttempts >= MAX_ROUNDS → 跳过，标记 ❌ MAX_REACHED
+       b. 否则 → 调 /sillyspec:quick 修复，prompt 必须包含：
+          - 失败的测试文件路径和测试名
+          - 完整错误信息（含期望值 vs 实际值）
+          - 相关源文件路径
+          - "只修复这个测试失败，不要改其他代码"
+       c. 修复后重跑该测试确认是否通过
+       d. 通过 → fixAttempts 保持不变；仍失败 → fixAttempts + 1
+    5. 写入 .sillyspec/local.yaml     6. ROUND++
+    7. 如果本轮无任何修复（所有失败都已 MAX_REACHED）→ 跳出循环
+```
+
+**quick 修复 prompt 模板：**
+```
+/sillyspec:quick "修复测试失败：<测试文件路径>:<测试名>
+
+错误信息：
+<完整错误输出，包含期望值和实际值>
+
+相关文件：
+<被测源文件路径>
+
+只修复这个测试失败，不要改其他代码。修完后运行该测试确认通过。"
+```
+
+**禁止行为：**
+- ❌ 只看错误摘要就修复（必须看完整输出）
+- ❌ 跳过 fixAttempts 计数
+- ❌ 一次 quick 修复多个不相关的失败（逐个修复，每次修复后重跑确认）
+- ❌ 主代理直接修改代码（verify 阶段禁止改代码，必须通过 /sillyspec:quick）
+
+**更新测试结果到 `.sillyspec/local.yaml`（按变更名隔离，覆盖写入）：**
+```yaml
+e2e:
+  {变更名}:
+    login.spec.ts:
+      status: passed
+      fixAttempts: 0
+    form-submit.spec.ts:
+      status: failed
+      fixAttempts: 3
+```
+
+### 5. 代码质量扫描
+
+```bash
+grep -r "TODO\|FIXME\|HACK\|XXX" src/ lib/ app/ --include="*.ts" --include="*.tsx" --include="*.py" --include="*.js" 2>/dev/null | head -20
+```
+
+审查 design.md「文件变更」中列出的文件：安全问题（输入校验、SQL拼接、硬编码敏感信息）、潜在 bug（空值、边界条件）、与 CONVENTIONS.md 一致性。每个问题标 🔴必须 / 🟡建议 / 🔵优化。
+
+### 5.5 MCP 基础设施验证
+
+检测已配置的 MCP 服务，利用它们做实际验证（不只查文档）：
+
+**MCP 能力检测：**
+
+不要只检查配置文件路径（不同客户端配置位置不同），直接检查当前可用工具列表中是否存在以下工具：
+
+- 数据库相关工具（包含 postgres/sqlite/mysql/redis 关键词）
+- 浏览器相关工具（包含 browser/chrome/puppeteer/playwright/devtools 关键词）
+- 搜索相关工具（包含 search/web_search 关键词）
+
+**判断方式：** 尝试调用或列出当前可用的 MCP 工具，有就用来验证，没有就跳过。
+
+**按检测结果执行对应验证：**
+
+**数据库 MCP（postgres/sqlite/mysql/redis）：**
+- 对照 design.md 中的数据模型，验证表/集合是否存在
+- 验证字段类型、约束（主键、外键、唯一索引）是否与设计一致
+- 验证新增的 API 是否能正确读写对应数据
+- ⚠️ 只执行 SELECT 查询，禁止任何写操作
+
+**浏览器 MCP（chrome-devtools/puppeteer/playwright）：**
+- 验证页面能否正常加载（无 404/500 错误）
+- 验证关键 UI 元素是否存在（导航、表单、按钮等）
+- 验证基础交互（点击、提交、跳转）
+
+**API MCP：**
+- 验证新增接口是否可达
+- 验证请求/响应格式是否与设计一致
+
+**无 MCP → 跳过此步骤，不影响验证结论。**
+
+将验证结果纳入验证报告。
+
+### 6. Lint / Format 检查
+
+自动检测并运行项目配置的 lint/format 工具，验证代码是否符合规范：
+
+```bash
+# ESLint
+if [ -f .eslintrc -o -f .eslintrc.js -o -f .eslintrc.cjs -o -f .eslintrc.json -o -f .eslintrc.yml ] || grep -q '"eslint"' package.json 2>/dev/null; then
+  echo "=== ESLint ==="
+  npx eslint . --max-warnings 0 2>&1 | tail -50
+fi
+
+# Prettier（检查而非修复）
+if [ -f .prettierrc -o -f .prettierrc.js -o -f .prettierrc.json -o -f .prettierrc.yml ] || grep -q '"prettier"' package.json 2>/dev/null; then
+  echo "=== Prettier ==="
+  npx prettier --check . 2>&1 | tail -30
+fi
+
+# TypeScript 类型检查
+if [ -f tsconfig.json ]; then
+  echo "=== TypeScript ==="
+  npx tsc --noEmit 2>&1 | tail -30
+fi
+
+# Stylelint
+if [ -f .stylelintrc -o -f .stylelintrc.js -o -f .stylelintrc.json ] || grep -q '"stylelint"' package.json 2>/dev/null; then
+  echo "=== Stylelint ==="
+  npx stylelint "**/*.{css,scss,less}" 2>&1 | tail -30
+fi
+```
+
+**处理策略（AskUserQuestion）：**
+1. **自动修复** — 对支持 `--fix` 的工具（ESLint、Prettier、Stylelint）自动修复后重跑检查，同一问题最多修复 3 次
+2. **只报告** — 仅列出所有 lint 错误，不修改代码
+
+将 lint 结果纳入验证报告（步骤 7）。
+
+### 7. 输出验证报告
+
+```markdown
+# SillySpec 验证报告
+## 任务完成度：X/Y
+## 设计一致性
+## 测试结果：passed N, failed N
+## 技术债务标记
+## 代码审查：🔴 N / 🟡 N / 🔵 N
+## Lint 检查：ESLint ✅/❌ | Prettier ✅/❌ | TypeScript ✅/❌ | Stylelint ✅/❌
+## MCP 基础设施验证：数据库 ✅/❌/跳过 | 页面 ✅/❌/跳过 | API ✅/❌/跳过
+## E2E 测试：passed N / failed N / fixAttempts 详情
+## 结论：✅ PASS / ⚠️ PASS WITH NOTES / ❌ FAIL
+```
+
+### 7. 完成
+