sillyspec 3.7.3 → 3.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.7.3",
+  "version": "3.7.5",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "type": "module",
   "bin": {

package/src/setup.js

@@ -1,10 +1,26 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync } from 'fs';
 import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
 import chalk from 'chalk';
 import ora from 'ora';
 import { checkbox, confirm, input, select } from '@inquirer/prompts';
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ── Skill 定义 ──
+
+const SKILLS = [
+  {
+    id: 'playwright-e2e',
+    name: 'Playwright E2E 测试参考',
+    description: 'E2E 测试编写最佳实践，AI 执行测试任务时自动读取',
+    source: join(__dirname, '..', 'templates', 'skills', 'playwright-e2e'),
+    target: '.sillyspec/skills/playwright-e2e',
+  },
+];
+
 // ── MCP 工具定义 ──
 
 const MCP_TOOLS = [
@@ -266,6 +282,12 @@ export async function cmdSetup(dir, options = {}) {
     ...dbChoices,
     ...globalChoices.length > 0 ? [{ name: chalk.bold('── 全局工具 ──'), value: '_global_header', disabled: true }] : [],
     ...globalChoices,
+    ...[{ name: chalk.bold('── AI Skills（编写参考）──'), value: '_skill_header', disabled: true }],
+    ...SKILLS.filter(s => !existsSync(join(dir, s.target, 'SKILL.md'))).map(s => ({
+      name: `${s.name} — ${s.description}`,
+      value: `skill:${s.id}`,
+      checked: false,
+    })),
   ];
 
   if (allChoices.length === 0) {
@@ -355,6 +377,24 @@ export async function cmdSetup(dir, options = {}) {
     }
   }
 
+  // ── 安装 Skills ──
+
+  const selectedSkills = SKILLS.filter(s => selected.includes(`skill:${s.id}`));
+
+  if (selectedSkills.length > 0) {
+    console.log('');
+    for (const skill of selectedSkills) {
+      const spinner = ora(`安装 ${skill.name}...`).start();
+      try {
+        const targetDir = join(dir, skill.target);
+        cpSync(skill.source, targetDir, { recursive: true });
+        spinner.succeed(`${skill.name} 安装完成 → ${skill.target}/SKILL.md`);
+      } catch (err) {
+        spinner.fail(`${skill.name} 安装失败: ${err.message}`);
+      }
+    }
+  }
+
   // ── 总结 ──
 
   console.log('');
@@ -374,6 +414,10 @@ export async function cmdSetup(dir, options = {}) {
     console.log(`  🛠️  ${chalk.cyan(g.name)} — ${g.description}`);
     console.log(chalk.dim(`     ${g.url}`));
   }
+  for (const s of selectedSkills) {
+    console.log(`  📚 ${chalk.cyan(s.name)} — ${s.description}`);
+    console.log(chalk.dim(`     → ${s.target}/SKILL.md`));
+  }
   console.log('');
   if (selectedMcp.length > 0) {
     console.log(chalk.dim('  重启你的 AI 工具以使 MCP 配置生效。'));

package/templates/execute.md

@@ -96,12 +96,55 @@ cat package.json 2>/dev/null | grep -A5 '"lint\|"format\|"typecheck\|"type-check
 将此摘要注入到每个子代理 prompt 的「项目约定」段之后，并追加一条铁律：
 > **10. 遵守编码规范：** 以上「编码规范约束」中的所有规则必须严格遵守。如规则与任务描述冲突，优先遵守规范约束并报告。
 
-**MCP 能力检测（主代理执行）：**
+**测试模式扫描（主代理执行）：**
+对包含 E2E/测试任务时，扫描项目已有的测试文件，提取测试风格注入子代理 prompt 的「测试模式参考」段。
+
 ```bash
-for cfg in .claude/mcp.json .cursor/mcp.json; do
-  [ -f "$cfg" ] && echo "=== $cfg ===" && cat "$cfg"
-done
+# 检测测试框架
+cat package.json 2>/dev/null | grep -E "playwright|cypress|jest|vitest|mocha"
+
+# 查找已有测试文件
+find . -name "*.spec.ts" -o -name "*.test.ts" -o -name "*.spec.tsx" -o -name "*.spec.js" \
+     -o -name "playwright.config.*" -o -name "vitest.config.*" -o -name "jest.config.*" \
+  2>/dev/null | grep -v node_modules | head -10
+
+# 读取 1-2 个已有测试文件作为风格参考
+# 优先读 E2E 测试，其次读通用测试
+find tests/e2e e2e cypress/e2e __tests__ src -name "*.spec.ts" -o -name "*.test.ts" \
+  2>/dev/null | grep -v node_modules | head -3 | xargs cat 2>/dev/null
+```
+
+扫描后生成**测试模式摘要**：
+
+```
+## 测试模式参考（自动扫描）
+
+### 测试框架
+{检测到的框架及版本，如：Playwright 1.42、Vitest 1.2}
+
+### 断言风格
+{从已有测试提取的断言模式，如：expect(page).toHaveText()、toEqual、toBeTruthy 等}
+
+### Fixtures / Helper
+{项目自定义的 test fixtures、page objects、helper 函数}
+
+### 文件组织
+{测试文件目录结构、命名约定、文件内组织方式}
+
+### 配置要点
+{playwright.config.ts 中的 baseURL、timeout、retries 等关键配置}
 ```
+
+将此摘要注入到每个 E2E/测试子代理 prompt 的「任务描述」段之后，并追加一条铁律：
+> **11. 参照已有测试风格：** 编写新测试时必须参照以上「测试模式参考」中的风格，包括断言方式、fixtures 使用、文件组织。不要凭记忆写测试。
+> **12. 参考已有实现：** 写新功能前，先 grep 项目中类似功能的已有代码（`grep -r "关键词" src/`），照着项目现有的模式、风格和封装方式写，不要凭记忆编造。
+
+**MCP 能力检测（主代理执行）：**
+检查当前可用工具列表中是否存在以下类型的 MCP 工具（不要只依赖配置文件路径，不同客户端配置位置不同）：
+- Context7 / 文档查询工具
+- 数据库工具（postgres/sqlite/mysql/redis）
+- 浏览器工具（browser/chrome/playwright/devtools）
+- 搜索工具（search/web_search）
 根据检测结果，在子代理 prompt 的「文档查询指引」段动态注入：
 - 有 `context7` → `遇到不熟悉的库/API，使用 Context7 MCP（resolve-library-id → query-docs）查询最新文档`
 - 无 `context7` → `遇到不熟悉的库/API，使用 web search 查询最新官方文档`
@@ -148,6 +191,9 @@ done
 ## 编码规范约束（自动扫描）
 {主代理扫描项目配置文件后生成的规范摘要，见上方「编码规范扫描」步骤}
 
+## 测试模式参考（自动扫描，仅 E2E/测试任务注入）
+{主代理扫描项目已有测试文件后生成的测试风格摘要，见上方「测试模式扫描」步骤。非 E2E/测试任务省略此段}
+
 ## 项目架构
 {ARCHITECTURE.md 全文}
 
@@ -174,7 +220,12 @@ done
 4. **不自行补全：** 发现缺失接口/方法，不自己写，报告 BLOCKED
 5. **TDD 不跳步：** 按任务步骤逐步执行，每步必须运行测试命令并确认结果
 6. **测试直接通过 = 测了已有行为，重写测试**
-7. **E2E 任务：** 如果任务描述包含"E2E"或"端到端"，先 cat 相关功能代码和页面组件，理解交互逻辑。有测试框架则编写测试文件，无框架则编写 `.sillyspec/changes/<变更名>/e2e-steps.md` 结构化测试步骤（每条包含操作和断言）
+7. **E2E 任务：** 如果任务描述包含"E2E"或"端到端"：
+   - 先 cat 相关功能代码和页面组件，理解交互逻辑
+   - 参考 prompt 中「测试模式参考」段的已有测试风格
+   - **查阅 Playwright 用法：** 优先使用已安装的 playwright skill（SKILL.md），不要凭记忆写 API。未安装则通过 Context7 MCP 或 web search 查最新文档
+   - 有测试框架则编写测试文件，无框架则编写 `.sillyspec/changes/<变更名>/e2e-steps.md` 结构化测试步骤
+   - **写完必须立即跑一遍确认通过**，失败则修复后重跑，不要"写了就算完成"
 8. **暂存：** 完成后在工作目录执行 git add -A（不要 commit，由用户通过 /sillyspec:commit 统一提交）
 9. **不修改计划外的文件**，如必须修改则在报告中说明
 10. **遵守编码规范：** prompt 中「编码规范约束」段的所有规则必须严格遵守。如规范与任务描述冲突，优先遵守规范并报告

package/templates/explore.md

@@ -37,9 +37,7 @@ cat .sillyspec/knowledge/INDEX.md 2>/dev/null
 
 ## MCP 能力（按需使用）
 
-```bash
-cat .claude/mcp.json .cursor/mcp.json 2>/dev/null
-```
+检查当前可用工具列表中是否存在 MCP 工具（Context7/浏览器/数据库/搜索等），不依赖配置文件路径。
 
 - 有 Context7 → 探索时查询最新文档，验证技术方案的可行性
 - 有浏览器 MCP → 可浏览相关网站、查竞品实现

package/templates/quick.md

@@ -27,7 +27,7 @@ $ARGUMENTS
    cat .sillyspec/knowledge/INDEX.md 2>/dev/null
    ```
    根据当前任务描述中的关键词匹配 INDEX.md 条目，命中时 `cat` 对应知识文件，将内容纳入后续开发考量。未命中则跳过。
-   **MCP 检测：** `cat .claude/mcp.json .cursor/mcp.json 2>/dev/null`，根据检测结果动态利用：
+   **MCP 检测：** 检查当前可用工具列表中是否存在 MCP 工具（Context7/浏览器/数据库/搜索等），根据检测结果动态利用：
    - 有 Context7 → 查询不熟悉库/API 的最新文档
    - 有浏览器 MCP → 验证页面改动效果
    - 有数据库 MCP → 查询表结构和数据验证（只读）

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

@@ -0,0 +1,340 @@
+---
+name: playwright-e2e
+description: Playwright E2E 测试编写参考。AI 执行 E2E 任务时自动读取，不要凭记忆编写 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/verify.md

@@ -167,9 +167,14 @@ grep -r "TODO\|FIXME\|HACK\|XXX" src/ lib/ app/ --include="*.ts" --include="*.ts
 检测已配置的 MCP 服务，利用它们做实际验证（不只查文档）：
 
 **MCP 能力检测：**
-```bash
-cat .claude/mcp.json .cursor/mcp.json 2>/dev/null
-```
+
+不要只检查配置文件路径（不同客户端配置位置不同），直接检查当前可用工具列表中是否存在以下工具：
+
+- 数据库相关工具（包含 postgres/sqlite/mysql/redis 关键词）
+- 浏览器相关工具（包含 browser/chrome/puppeteer/playwright/devtools 关键词）
+- 搜索相关工具（包含 search/web_search 关键词）
+
+**判断方式：** 尝试调用或列出当前可用的 MCP 工具，有就用来验证，没有就跳过。
 
 **按检测结果执行对应验证：**