sillyspec 3.7.2 → 3.7.4

package/package.json

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

package/src/setup.js

@@ -1,10 +1,22 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync } from 'fs';
 import { join, dirname } from 'path';
 import { execSync } from 'child_process';
 import chalk from 'chalk';
 import ora from 'ora';
 import { checkbox, confirm, input, select } from '@inquirer/prompts';
 
+// ── 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 +278,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 +373,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 +410,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

@@ -54,12 +54,97 @@ cat .sillyspec/knowledge/INDEX.md 2>/dev/null
 
 子代理遇到不熟悉的库或 API 时，优先使用已配置的 MCP 工具（Context7 等）或 web search 查最新文档，不要凭记忆猜测用法。
 
-**MCP 能力检测（主代理执行）：**
+**编码规范扫描（主代理执行）：**
+主代理在 dispatch 子代理前，扫描项目中常见的编码规范配置文件，将关键规则注入子代理 prompt 的「编码规范约束」段。
+
 ```bash
-for cfg in .claude/mcp.json .cursor/mcp.json; do
-  [ -f "$cfg" ] && echo "=== $cfg ===" && cat "$cfg"
+# 检测存在的配置文件
+for f in .eslintrc .eslintrc.js .eslintrc.cjs .eslintrc.json .eslintrc.yml \
+         .prettierrc .prettierrc.js .prettierrc.json .prettierrc.yml \
+         tsconfig.json tsconfig.base.json \
+         .editorconfig \
+         .tailwind.config.js .tailwind.config.ts \
+         .stylelintrc .stylelintrc.js .stylelintrc.json \
+         CONTRIBUTING.md CODE_STYLE.md; do
+  [ -f "$f" ] && echo "=== $f ===" && cat "$f"
 done
+# 也检查 package.json 中的 lint/format 脚本
+cat package.json 2>/dev/null | grep -A5 '"lint\|"format\|"typecheck\|"type-check'
+```
+
+扫描后，主代理根据检测结果生成**编码规范摘要**（不是原文粘贴，是提炼关键约束），格式如下。如果某个类别未检测到对应配置文件，则省略该段：
+
+```
+## 编码规范约束（自动扫描）
+
+### ESLint
+{提取的关键规则，如：禁止 var、要求分号、禁止未使用变量、特定插件规则等}
+
+### Prettier
+{提取的格式化规则，如：单引号、2空格缩进、无分号、行宽 80 等}
+
+### TypeScript
+{从 tsconfig 提取的严格模式设置，如：strict: true、noUncheckedIndexedAccess 等}
+
+### Import / 命名约定
+{从 eslint/import 插件或 editorconfig 提取的导入排序、命名风格等}
+
+### 框架约定
+{检测到的框架特定约定，如：Next.js App Router、Tailwind 类名风格等}
+```
+
+将此摘要注入到每个子代理 prompt 的「项目约定」段之后，并追加一条铁律：
+> **10. 遵守编码规范：** 以上「编码规范约束」中的所有规则必须严格遵守。如规则与任务描述冲突，优先遵守规范约束并报告。
+
+**测试模式扫描（主代理执行）：**
+对包含 E2E/测试任务时，扫描项目已有的测试文件，提取测试风格注入子代理 prompt 的「测试模式参考」段。
+
+```bash
+# 检测测试框架
+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 查询最新官方文档`
@@ -103,6 +188,12 @@ done
 ## 项目约定
 {CONVENTIONS.md 全文}
 
+## 编码规范约束（自动扫描）
+{主代理扫描项目配置文件后生成的规范摘要，见上方「编码规范扫描」步骤}
+
+## 测试模式参考（自动扫描，仅 E2E/测试任务注入）
+{主代理扫描项目已有测试文件后生成的测试风格摘要，见上方「测试模式扫描」步骤。非 E2E/测试任务省略此段}
+
 ## 项目架构
 {ARCHITECTURE.md 全文}
 
@@ -129,9 +220,15 @@ 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 中「编码规范约束」段的所有规则必须严格遵守。如规范与任务描述冲突，优先遵守规范并报告
 
 ## 完成后报告（严格按此格式）
 
@@ -166,6 +263,20 @@ done
 
 ## 完成后
 
+**任务勾选自检（必须执行）：**
+所有任务完成后，主代理必须执行以下检查：
+
+```bash
+cat .sillyspec/changes/*/tasks.md 2>/dev/null
+```
+
+逐条验证：
+1. **所有返回 DONE/DONE_WITH_CONCERNS 的任务是否已勾选 `- [x]`？**
+2. **勾选的任务是否都记录了精确到秒的时间戳 `[YYYY-MM-DD HH:MM:SS]`？**
+3. **tasks.md 中是否还有未勾选 `- [ ]` 的已完成任务？**
+
+发现遗漏 → 立即补勾选 + 补时间戳，不要等用户提醒。
+
 **知识库审阅：** 检查是否有待确认的知识条目：
 ```bash
 grep -c '^\### \[待确认\]' .sillyspec/knowledge/uncategorized.md 2>/dev/null

package/templates/explore.md

@@ -29,10 +29,32 @@ $ARGUMENTS
 ```bash
 ls .sillyspec/changes/ 2>/dev/null | grep -v archive
 cat .sillyspec/{REQUIREMENTS,ROADMAP}.md 2>/dev/null
+cat .sillyspec/codebase/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null
+cat .sillyspec/knowledge/INDEX.md 2>/dev/null
 ```
 
 有进行中变更时读取其 design/tasks，自然引用。发现重要决策时可提议保存（不自动保存）。
 
+## MCP 能力（按需使用）
+
+检查当前可用工具列表中是否存在 MCP 工具（Context7/浏览器/数据库/搜索等），不依赖配置文件路径。
+
+- 有 Context7 → 探索时查询最新文档，验证技术方案的可行性
+- 有浏览器 MCP → 可浏览相关网站、查竞品实现
+- 有搜索 MCP → 搜索技术方案、最佳实践
+- 无 MCP → 使用 web search
+
+## 话题升级提示
+
+探索过程中，当对话达到一定深度时（讨论了 5+ 轮、或涉及具体实现方案、或用户表达"试试看"/"能不能做"/"怎么搞"），主动用 AskUserQuestion 提示用户：
+
+1. **🧠 头脑风暴** — `/sillyspec:brainstorm` 深度探索需求和方案
+2. **⚡ 快速执行** — `/sillyspec:quick` 直接动手做
+3. **📋 创建规范** — `/sillyspec:propose` 生成结构化规范
+4. **🔍 继续探索** — 还没聊透，继续
+
+不需要每次都提示，只在对话**明显转向执行意图**时触发。纯讨论、提问、查资料时不要打断。
+
 ## 没有必需的结束
 
 探索可以创建变更提案、产出文档、继续探索或结束。

package/templates/plan.md

@@ -123,6 +123,30 @@ cat .claude/mcp.json .cursor/mcp.json 2>/dev/null | grep -i "browser\|chrome\|de
 - [ ] 每个 task 有具体文件路径？
 - [ ] 标注了 Wave 和依赖关系？
 - [ ] 涉及 UI 的任务是否有对应的 E2E 测试任务？
+- [ ] **design.md 中的每个功能点是否都在 tasks.md 中有对应任务？**
+
+### 6.5 设计完整性对照（必须完成）
+
+逐条检查 design.md 中的功能描述，确保每个功能点都有对应的 task。特别关注：
+
+1. **逐功能点扫描：** 将 design.md 中描述的每个功能点（含子功能）列出，与 tasks.md 逐条对照
+2. **前后端覆盖检查：** 涉及前后端协作的功能，确认前端和后端各有独立 task
+3. **遗漏项处理：** 发现未覆盖的功能点 → 追加 task 到对应 Wave，并提示用户确认
+
+**执行方式：**
+```
+从 design.md 提取功能点清单：
+  功能 A（后端接口）
+  功能 B（前端页面）
+  功能 C（前后端联动）
+
+与 tasks.md 对照：
+  ✅ 功能 A → task-3
+  ❌ 功能 B → 无对应 task → 追加
+  ⚠️ 功能 C → 只有后端 task，缺少前端 task → 追加
+```
+
+发现遗漏时用 AskUserQuestion 确认追加内容，用户确认后再写入 tasks.md。
 
 ### 7. 完成
 

package/templates/quick.md

@@ -21,12 +21,19 @@ $ARGUMENTS
 1. **解析参数：** 检查是否携带 `--change <变更名>`，确定记录方式
 2. **理解任务：** 模糊则问一个问题确认
 3. **加载上下文：** `cat .sillyspec/codebase/{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 检测：** `cat .claude/mcp.json .cursor/mcp.json 2>/dev/null`，有 Context7 则用 MCP 查文档，无则用 web search。
+   **MCP 检测：** 检查当前可用工具列表中是否存在 MCP 工具（Context7/浏览器/数据库/搜索等），根据检测结果动态利用：
+   - 有 Context7 → 查询不熟悉库/API 的最新文档
+   - 有浏览器 MCP → 验证页面改动效果
+   - 有数据库 MCP → 查询表结构和数据验证（只读）
+   - 有搜索 MCP → 搜索最佳实践和解决方案
+   - 有其他 MCP → 按任务需要灵活使用
+   - 无 MCP → 使用 web search
 5. **先读后写：** 调用已有方法前 `cat` 源文件确认签名，`grep` 确认方法存在
 6. **数据操作安全：** 任何改变现有数据的操作（非 SELECT 的数据库操作）必须暂停并报告给用户确认，不得自动执行。新建表不受此限制
 6. **TDD 执行：**

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

@@ -47,6 +47,7 @@ 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
 ```
 
 锚定确认实际存在的文件。
@@ -97,9 +98,49 @@ npx vitest run 2>/dev/null || npx jest 2>/dev/null
 > ⚠️ 使用 MCP 执行时 AI 判断可能不如测试框架精确。追求可靠性建议安装 Playwright。
 
 **自动修复循环（选了策略 1 或 2 时）：**
-读取 `.sillyspec/local.yaml` 中当前变更的 `fixAttempts`，对每个失败测试：
-- fixAttempts 未达上限 → 调 `/sillyspec:quick "修复 E2E 失败：<失败描述>"` → 重跑该测试 → 更新 local.yaml
-- fixAttempts 达到上限 → 停止，报告失败详情，提示人工介入
+
+必须按以下流程严格执行，不可跳过：
+
+```
+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 更新 fixAttempts
+    6. ROUND++
+    7. 如果本轮无任何修复（所有失败都已 MAX_REACHED）→ 跳出循环
+```
+
+**quick 修复 prompt 模板：**
+```
+/sillyspec:quick "修复测试失败：<测试文件路径>:<测试名>
+
+错误信息：
+<完整错误输出，包含期望值和实际值>
+
+相关文件：
+<被测源文件路径>
+
+只修复这个测试失败，不要改其他代码。修完后运行该测试确认通过。"
+```
+
+**禁止行为：**
+- ❌ 只看错误摘要就修复（必须看完整输出）
+- ❌ 跳过 fixAttempts 计数
+- ❌ 一次 quick 修复多个不相关的失败（逐个修复，每次修复后重跑确认）
+- ❌ 主代理直接修改代码（verify 阶段禁止改代码，必须通过 /sillyspec:quick）
 
 **更新测试结果到 `.sillyspec/local.yaml`（按变更名隔离，覆盖写入）：**
 ```yaml
@@ -121,7 +162,78 @@ grep -r "TODO\|FIXME\|HACK\|XXX" src/ lib/ app/ --include="*.ts" --include="*.ts
 
 审查 design.md「文件变更」中列出的文件：安全问题（输入校验、SQL拼接、硬编码敏感信息）、潜在 bug（空值、边界条件）、与 CONVENTIONS.md 一致性。每个问题标 🔴必须 / 🟡建议 / 🔵优化。
 
-### 6. 输出验证报告
+### 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 验证报告
@@ -130,6 +242,8 @@ grep -r "TODO\|FIXME\|HACK\|XXX" src/ lib/ app/ --include="*.ts" --include="*.ts
 ## 测试结果：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
 ```