claude-coder 1.8.3 → 1.9.0

package/README.md

@@ -6,7 +6,7 @@
 
 ### 亮点
 
-- **Harness 生命周期管理**：统一的 Harness 类封装环境准备、任务调度、校验、回滚、推送全生命周期，含 AI 驱动的 JSON 自愈修复
+- **Session 生命周期管理**：Session 类封装 SDK 管理、query 执行、hooks、indicator 全生命周期，runner 编排循环含 AI 驱动的 JSON 自愈修复
 - **Hook 提示注入**：通过 JSON 配置在工具调用时向模型注入上下文引导，零代码修改即可扩展规则（[机制详解](design/hook-mechanism.md)）
 - **长时间自循环编码**：多 session 编排 + 倒计时活跃度监控 + git 回滚重试，Agent 可持续编码数小时不中断（[守护机制](design/session-guard.md)）
 - **配置驱动**：支持 Claude 官方、Coding Plan 多模型路由、DeepSeek 等任意 Anthropic 兼容 API
@@ -41,6 +41,7 @@ claude-coder run "实现用户注册和登录功能"
 |------|------|
 | `claude-coder setup` | 交互式配置（模型、MCP、安全限制、自动审查） |
 | `claude-coder init` | 初始化项目环境（扫描技术栈、生成 profile） |
+| `claude-coder init --deploy-templates` | 部署模板和食谱到项目目录（可自定义） |
 | `claude-coder plan "需求"` | 生成计划方案 |
 | `claude-coder plan -r [file]` | 从需求文件生成计划 |
 | `claude-coder plan --planOnly` | 仅生成计划文档，不分解任务 |
@@ -52,7 +53,7 @@ claude-coder run "实现用户注册和登录功能"
 | `claude-coder run --max 1` | 单次执行 |
 | `claude-coder run --dry-run` | 预览模式（查看任务队列） |
 | `claude-coder simplify [focus]` | 代码审查和简化 |
-| `claude-coder auth [url]` | 导出 Playwright 登录状态 |
+| `claude-coder auth [url]` | 配置浏览器测试工具 / 导出登录状态 |
 | `claude-coder status` | 查看进度和成本 |
 
 **选项**：`--max N` 限制 session 数（默认 50），`--pause N` 每 N 个 session 暂停确认，`--model M` 指定模型。
@@ -68,26 +69,26 @@ claude-coder run "实现用户注册和登录功能"
                                  │  3 步流程    │
                                  └──────┬──────┘
                                         │
-                                   Harness 校验
+                                   runner 校验
                                    (含 AI 自愈)
                                         │
                               通过 → simplify? → push → 下一个任务
                               失败 → git 回滚 + 重试
 ```
 
-每个 session 内，Agent 自主执行 3 步：**实现**（任务上下文由 harness 注入，编码实现） → **验证**（按 category 选最轻量测试） → **收尾**（git commit + 写 session_result.json）。
+每个 session 内，Agent 自主执行 3 步：**实现**（任务上下文由 prompt 注入，编码实现） → **验证**（按 category 选最轻量测试） → **收尾**（git commit + 写 session_result.json）。
 
-Harness 在 session 结束后自动校验 `session_result.json` + git 进度。校验失败时 AI 自动尝试修复损坏的 JSON 文件（`repair.js`），仍失败则回滚代码并重试。
+Runner 在 session 结束后自动校验 `session_result.json` + git 进度。校验失败时 AI 自动尝试修复损坏的 JSON 文件（`repair.js`），仍失败则回滚代码并重试。
 
 ## 机制文档
 
 | 文档 | 说明 |
 |------|------|
-| [技术架构](design/ARCHITECTURE.md) | 核心设计规则、Harness 类职责、模块关系、Prompt 注入架构 |
+| [技术架构](design/ARCHITECTURE.md) | 核心设计规则、Session 类职责、模块关系、Prompt 注入架构 |
 | [Hook 注入机制](design/hook-mechanism.md) | SDK Hook 调研、GuidanceInjector 三级匹配、配置格式、副作用评估 |
 | [Session 守护机制](design/session-guard.md) | 中断策略、倒计时活跃度检测、工具运行状态追踪、防刷屏 |
 | [Go 指令流程](design/go-flow.md) | AI 驱动的需求组装、食谱系统、与 plan 衔接 |
-| [测试凭证方案](docs/PLAYWRIGHT_CREDENTIALS.md) | Playwright 登录态导出、API Key 持久化 |
+| [浏览器测试工具](docs/PLAYWRIGHT_CREDENTIALS.md) | Playwright MCP / Chrome DevTools MCP 对比、安装、凭证管理 |
 | [SDK 使用指南](docs/CLAUDE_AGENT_SDK_GUIDE.md) | Claude Agent SDK 接口参考 |
 
 ## 使用场景
@@ -96,11 +97,57 @@ Harness 在 session 结束后自动校验 `session_result.json` + git 进度。
 
 **已有项目**：`claude-coder run "新增头像上传功能"` — 先扫描现有代码和技术栈，再增量开发。
 
-**需求文档驱动**：在项目根目录创建 `requirements.md`，运行 `claude-coder run`。需求变更后 `claude-coder add -r` 同步新任务。
+**需求文档驱动**：在项目根目录创建 `requirements.md`，运行 `claude-coder plan -r requirements.md` 分解任务后 `claude-coder run` 执行。
 
 **AI 驱动需求组装**：`claude-coder go "用户管理页面"` — AI 扫描内置食谱库，自动组装完整需求方案，一键进入 plan 分解任务。支持对话模式 (`go`) 逐步引导非技术人员。
 
-**自动测试 + 凭证持久化**：`claude-coder auth http://localhost:3000` — 导出浏览器登录态，Agent 测试时自动使用。详见 [测试凭证方案](docs/PLAYWRIGHT_CREDENTIALS.md)。
+**自动测试 + 凭证持久化**：`claude-coder auth http://localhost:3000` — 导出浏览器登录态，Agent 测试时自动使用。详见 [浏览器测试工具指南](docs/PLAYWRIGHT_CREDENTIALS.md)。
+
+## 浏览器测试工具
+
+支持两种 MCP 浏览器测试工具，通过 `WEB_TEST_TOOL` 环境变量切换：
+
+| 维度 | Playwright MCP | Chrome DevTools MCP |
+|------|---------------|---------------------|
+| **维护方** | 微软 | Google |
+| **核心优势** | 25+ 自动化工具，多实例并行 | 连接已打开 Chrome，调试能力强 |
+| **多实例** | 支持 | 不支持（单实例，多开请用 Playwright） |
+| **安装依赖** | `npx playwright install chromium` | Node.js v20.19+ / Chrome 144+ |
+| **凭证方案** | persistent 模式复用登录态 | 直接复用已打开 Chrome 的登录态 |
+| **适合场景** | CI/CD、多并行测试、需要 Chromium 隔离 | 本地开发、调试、利用已有 Chrome 环境 |
+
+### 安装步骤
+
+```bash
+# Playwright MCP（推荐）
+claude-coder setup          # → 选择「Playwright MCP」→ 选择模式
+npx playwright install chromium
+claude-coder auth http://your-app.com   # 导出登录态
+
+# Chrome DevTools MCP（需 Node.js v20.19+）
+claude-coder setup          # → 选择「Chrome DevTools MCP」
+# 打开 Chrome → chrome://inspect/#remote-debugging → 启用远程调试
+claude-coder auth           # 配置 .mcp.json
+```
+
+### 常见问题
+
+**Q: Playwright 和 Chrome DevTools 该选哪个？**
+A: 如果你需要多实例并行测试或 CI/CD 集成，选 Playwright MCP。如果你只需要本地调试、想复用已打开 Chrome 的登录态和扩展，选 Chrome DevTools MCP。
+
+**Q: Chrome DevTools MCP 报 `chrome-devtools-mcp` 安装失败？**
+A: 确保 Node.js ≥ v20.19。nvm 用户执行 `nvm alias default 22 && nvm use 22`，然后重新安装 `npm install -g @anthropic-ai/claude-code`。
+
+**Q: Playwright 浏览器启动后白屏或超时？**
+A: 运行 `npx playwright install chromium` 确保浏览器已安装。persistent 模式下检查 `.claude-coder/.runtime/browser-profile/` 目录是否存在。
+
+**Q: 切换工具后需要重新认证吗？**
+A: 不需要。`claude-coder setup` 切换时自动更新 `.env` 和 `.mcp.json`。之前的认证数据（如 browser-profile）保留，切回时直接可用。
+
+**Q: 两个工具可以同时启用吗？**
+A: 不可以。`.mcp.json` 中同时只保留一个工具的配置，切换时自动替换。
+
+详见 [浏览器测试工具完整文档](docs/PLAYWRIGHT_CREDENTIALS.md)。
 
 ## 模型支持
 
@@ -142,9 +189,9 @@ your-project/
     progress.json           # 会话历史 + 成本
     test.env                # 测试凭证（可选）
     go/                     # go 指令输出的方案文件
-    recipes/                # 食谱库（init 时从内置模板部署）
+    recipes/                # 食谱库（--deploy-templates 时从内置模板部署，可选）
     .runtime/
-      harness_state.json    # Harness 状态（session 计数等）
+      harness_state.json    # 运行状态（session 计数等）
       logs/                 # 每 session 独立日志
 ```
 
@@ -154,7 +201,7 @@ your-project/
 
 **中断恢复**：直接重新运行 `claude-coder run`，从上次中断处继续。
 
-**长时间无响应**：模型处理复杂任务时可能出现长思考间隔（indicator 显示黄色"工具执行中"或红色"无响应"），这是正常行为。超过阈值后 harness 自动中断并重试。通过 `claude-coder setup` 的安全限制配置或 `.env` 中 `SESSION_STALL_TIMEOUT=秒数` 调整。
+**长时间无响应**：模型处理复杂任务时可能出现长思考间隔（indicator 显示黄色"工具执行中"或红色"无响应"），这是正常行为。超过阈值后自动中断并重试。通过 `claude-coder setup` 的安全限制配置或 `.env` 中 `SESSION_STALL_TIMEOUT=秒数` 调整。
 
 **跳过任务**：将 `.claude-coder/tasks.json` 中该任务的 `status` 改为 `done`。
 

package/bin/cli.js

@@ -6,7 +6,7 @@ const pkg = require('../package.json');
 const COMMANDS = {
   run:       { desc: '自动编码循环',             usage: 'claude-coder run [--max N] [--pause N] [--dry-run]' },
   setup:     { desc: '交互式模型配置',           usage: 'claude-coder setup' },
-  init:      { desc: '初始化项目环境',           usage: 'claude-coder init' },
+  init:      { desc: '初始化项目环境',           usage: 'claude-coder init [--deploy-templates]' },
   plan:      { desc: '生成计划方案',             usage: 'claude-coder plan "需求" | plan -r requirements.md [--planOnly] [-i]' },
   simplify:  { desc: '代码审查和简化',           usage: 'claude-coder simplify [focus]' },
   auth:      { desc: '导出 Playwright 登录状态', usage: 'claude-coder auth [url]' },
@@ -31,6 +31,7 @@ function showHelp() {
   console.log('  claude-coder run --max 1             单次执行');
   console.log('  claude-coder run --max 5 --pause 5   每 5 个 session 暂停确认');
   console.log('  claude-coder run --dry-run            预览模式');
+  console.log('  claude-coder init --deploy-templates  部署模板和食谱到项目目录（可自定义）');
   console.log('  claude-coder simplify               代码审查和简化');
   console.log('  claude-coder simplify "内存效率"     聚焦特定领域审查');
   console.log('  claude-coder go                      对话式需求收集和方案组装');
@@ -50,6 +51,11 @@ function parseArgs(argv) {
   const positional = [];
 
   for (let i = 1; i < args.length; i++) {
+    // support --key=value syntax
+    if (args[i].startsWith('--') && args[i].includes('=')) {
+      const eq = args[i].indexOf('=');
+      args.splice(i, 1, args[i].slice(0, eq), args[i].slice(eq + 1));
+    }
     switch (args[i]) {
       case '--max':
         opts.max = parseInt(args[++i], 10) || 50;
@@ -87,6 +93,9 @@ function parseArgs(argv) {
       case '--interactive':
         opts.interactive = true;
         break;
+      case '--deploy-templates':
+        opts.deployTemplates = true;
+        break;
       case '--help':
       case '-h':
         showHelp();
@@ -103,7 +112,7 @@ function parseArgs(argv) {
   return { command, positional, opts };
 }
 
-async function main() {
+async function cliMain() {
   const { command, positional, opts } = parseArgs(process.argv);
 
   if (!command || command === '--help' || command === '-h') {
@@ -117,56 +126,30 @@ async function main() {
   }
 
   switch (command) {
-    case 'run': {
-      const runner = require('../src/core/runner');
-      await runner.run(opts);
-      break;
-    }
     case 'setup': {
       const setup = require('../src/commands/setup');
       await setup.setup();
-      break;
-    }
-    case 'init': {
-      const { init } = require('../src/core/init');
-      await init();
-      break;
-    }
-    case 'plan': {
-      const { run: planRun } = require('../src/core/plan');
-      const input = positional[0] || '';
-      await planRun(input, opts);
-      break;
-    }
-    case 'simplify': {
-      const { simplify } = require('../src/core/simplify');
-      await simplify(positional[0] || null, { n: opts.n });
-      break;
+      return;
     }
     case 'auth': {
       const { auth } = require('../src/commands/auth');
       await auth(positional[0] || null);
-      break;
-    }
-    case 'go': {
-      const { run: goRun } = require('../src/core/go');
-      await goRun(positional[0] || '', opts);
-      break;
+      return;
     }
     case 'status': {
       const tasks = require('../src/common/tasks');
       tasks.showStatus();
-      break;
+      return;
     }
-    default:
-      console.error(`未知命令: ${command}`);
-      showHelp();
-      process.exit(1);
   }
+
+  const { main } = require('../src');
+  await main(command, positional[0] || '', opts);
 }
 
-main().catch(err => {
-  console.error(`\n错误: ${err.message}`);
+cliMain().catch(err => {
+  const { log } = require('../src/common/config');
+  log('error', err.message);
   if (process.env.DEBUG) console.error(err.stack);
   process.exit(1);
 });

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "claude-coder",
-  "version": "1.8.3",
+  "version": "1.9.0",
   "description": "Claude Coder — Autonomous coding agent harness powered by Claude Code SDK. Scan, plan, code, validate, git-commit in a loop.",
   "bin": {
     "claude-coder": "bin/cli.js"
   },
+  "types": "types/index.d.ts",
   "files": [
     "bin/",
     "src/",
+    "types/",
+    "recipes/",
     "templates/"
   ],
   "scripts": {

package/recipes/_shared/roles/developer.md

@@ -0,0 +1,11 @@
+# 角色：开发者
+
+## Plan 阶段提示
+用户是有经验的开发者。请注意：
+- 方案可包含技术细节：API 设计、数据模型、组件结构
+- 尊重用户指定的技术约束（框架、组件库、API 风格等）
+- 如用户未指定，根据项目现有技术栈推荐
+
+## Task 分解提示
+- steps 可包含具体的技术步骤
+- 验证步骤使用技术命令：curl、Playwright、lint 检查等

package/recipes/_shared/roles/product.md

@@ -0,0 +1,12 @@
+# 角色：产品经理
+
+## Plan 阶段提示
+用户是非技术产品经理。请注意：
+- 用简单语言描述方案，避免技术术语
+- 技术选型自动采用项目现有方案或最佳推荐，不需要用户确认
+- 关注功能完整性和用户体验，而非实现细节
+- 生成方案后，输出一个功能确认清单（纯业务语言）
+
+## Task 分解提示
+- steps 描述侧重"做什么"而非"怎么做"
+- 验证步骤用业务语言描述："能看到用户列表"而非"curl GET /api/users → 200"

package/recipes/_shared/roles/tester.md

@@ -0,0 +1,12 @@
+# 角色：测试
+
+## Plan 阶段提示
+用户关注测试覆盖和质量保障。请注意：
+- 方案重点描述验收标准和测试场景
+- 每个功能点需列出正向 + 异常场景
+- 关注边界条件：空数据、超长输入、并发操作
+
+## Task 分解提示
+- 每个功能对应的 test 任务应详细列出测试用例
+- steps 用 P0/P1/P2 标记优先级
+- 包含：正向流程、异常流程、边界测试

package/recipes/_shared/test/report-format.md

@@ -0,0 +1,86 @@
+# 测试报告输出规范
+
+测试任务完成后，必须输出两个报告文件。
+
+## 1. 结构化数据：.claude-coder/test-report.json
+
+```json
+{
+  "project": "项目名",
+  "timestamp": "ISO-8601 时间戳",
+  "summary": {
+    "total": 10,
+    "passed": 8,
+    "failed": 2,
+    "skipped": 0
+  },
+  "duration_ms": 45000,
+  "cases": [
+    {
+      "id": "TC-001",
+      "name": "列表加载",
+      "priority": "P0",
+      "status": "passed",
+      "duration_ms": 2300,
+      "steps": [
+        { "description": "导航到列表页", "status": "passed" },
+        { "description": "验证表格存在", "status": "passed" }
+      ],
+      "error": null
+    },
+    {
+      "id": "TC-002",
+      "name": "新建功能",
+      "priority": "P0",
+      "status": "failed",
+      "duration_ms": 5200,
+      "steps": [
+        { "description": "点击新建按钮", "status": "passed" },
+        { "description": "填写表单", "status": "passed" },
+        { "description": "提交", "status": "failed" }
+      ],
+      "error": "表单校验未触发，直接提交成功"
+    }
+  ],
+  "environment": {
+    "browser": "chromium",
+    "baseUrl": "http://localhost:xxxx"
+  }
+}
+```
+
+## 2. 可读报告：.claude-coder/test-report.md
+
+格式模板：
+
+```markdown
+# 测试报告 — {项目名}
+
+> 时间: {timestamp} | 通过率: {passed}/{total} | 耗时: {duration}s
+
+## 摘要
+
+| 指标 | 数值 |
+|------|------|
+| 总用例 | {total} |
+| 通过 | {passed} |
+| 失败 | {failed} |
+| 跳过 | {skipped} |
+
+## 详细结果
+
+### ✅ [P0] 列表加载 — PASSED (2.3s)
+1. 导航到列表页 ✓
+2. 验证表格存在 ✓
+
+### ❌ [P0] 新建功能 — FAILED (5.2s)
+1. 点击新建按钮 ✓
+2. 填写表单 ✓
+3. 提交 ✗ — 表单校验未触发
+
+## 失败用例汇总
+
+| 用例 | 优先级 | 失败原因 |
+|------|--------|----------|
+| 新建功能 | P0 | 表单校验未触发 |
+```

package/recipes/backend/base.md

@@ -0,0 +1,27 @@
+# 后端服务 — 基础食谱
+
+## 任务分解模式
+
+后端服务按以下标准拆分：
+
+1. **infra**: 项目结构（如未有后端框架，需初始化）
+   - steps：框架搭建、目录结构、数据库连接、中间件配置
+   - 验证：服务启动成功，健康检查接口返回 200
+
+2. **backend**: 数据模型 + API 接口
+   - steps：Model 定义、CRUD Service、Controller/Router、参数校验
+   - 验证：curl 测试所有接口返回正确响应
+
+3. **backend**: 业务逻辑（复杂场景单独拆分）
+   - steps：业务规则、数据转换、关联查询
+   - 验证：curl 测试边界场景
+
+4. **test**: API 测试
+   - steps：正向流程、参数校验、权限校验、边界测试
+
+## 通用规则
+
+- 一个资源（如 users）的完整 CRUD 合为一个 backend 任务
+- 认证鉴权如果与 CRUD 无关，拆为独立任务
+- 每个接口必须有参数校验
+- 错误响应格式统一

package/recipes/backend/components/auth.md

@@ -0,0 +1,18 @@
+# 认证鉴权
+
+## 任务分解指导
+认证鉴权拆为独立 backend 任务，不与 CRUD 混合。
+
+## 实现要点
+- 注册：用户名/邮箱 + 密码，密码 hash 存储
+- 登录：验证凭证，返回 JWT token 或设置 session
+- Token 验证中间件：拦截受保护路由
+- 角色权限：admin / editor / viewer 等，按路由或按操作控制
+- Token 刷新/续期机制
+
+## 验证策略
+- curl 注册 → 201
+- curl 登录 → 200 + token
+- curl 无 token 访问受保护路由 → 401
+- curl 带 token 访问 → 200
+- curl 权限不足 → 403

package/recipes/backend/components/crud-api.md

@@ -0,0 +1,18 @@
+# RESTful CRUD API
+
+## 任务分解指导
+一个资源的完整 CRUD 合为一个 backend 任务。
+
+## 实现要点
+- RESTful 风格：GET /资源（列表）、GET /资源/:id（详情）、POST（创建）、PUT（更新）、DELETE（删除）
+- 列表分页：`?page=1&pageSize=10`，返回 `{ data: [], total: N }`
+- 搜索过滤：`?keyword=xxx&status=active`
+- 排序：`?sortBy=createdAt&order=desc`
+- 参数校验：必填项、类型、长度、格式
+- 错误响应统一格式：`{ code: 400, message: "xxx" }`
+
+## 验证策略
+- curl POST 创建 → 201 + 返回创建的数据
+- curl GET 列表 → 200 + 分页结构正确
+- curl PUT 更新 → 200 + 数据变更
+- curl DELETE → 200 + 再 GET 确认已删除

package/recipes/backend/components/file-service.md

@@ -0,0 +1,15 @@
+# 文件服务
+
+## 任务分解指导
+文件服务如逻辑简单可合入 CRUD 任务，复杂时独立拆分。
+
+## 实现要点
+- 上传接口：multipart/form-data，校验类型和大小
+- 存储：本地文件系统 / 对象存储（S3/OSS）
+- 下载/访问：静态文件服务或签名 URL
+- 文件元信息：原始名、大小、MIME 类型、上传时间
+
+## 验证策略
+- curl 上传文件 → 200 + 返回 fileId/URL
+- curl 访问上传的文件 → 200 + 内容正确
+- curl 上传超限文件 → 400 + 错误提示

package/recipes/backend/manifest.json

@@ -0,0 +1,20 @@
+{
+  "id": "backend",
+  "name": "后端服务",
+  "description": "后端 API 服务开发（RESTful CRUD、认证鉴权、文件服务等）",
+  "base": "base.md",
+  "components": [
+    { "id": "crud-api",     "label": "CRUD API",  "description": "RESTful 增删改查接口 + 分页 + 过滤", "file": "components/crud-api.md",     "default": true },
+    { "id": "auth",         "label": "认证鉴权",  "description": "登录注册、JWT/Session、角色权限",   "file": "components/auth.md",         "default": false },
+    { "id": "file-service", "label": "文件服务",  "description": "文件上传下载、存储、类型校验",      "file": "components/file-service.md", "default": false }
+  ],
+  "test": {
+    "file": "test/api-test.md",
+    "defaultEnabled": true
+  },
+  "defaults": {
+    "components": ["crud-api"],
+    "role": "developer",
+    "test": true
+  }
+}

package/recipes/backend/test/api-test.md

@@ -0,0 +1,25 @@
+# API 测试步骤模板
+
+## 标准测试用例
+
+### 【P0】CRUD 正向流程
+1. POST 创建资源 → 验证 201 + 返回数据
+2. GET 列表 → 验证新数据在列表中
+3. GET 详情 → 验证数据正确
+4. PUT 更新 → 验证数据变更
+5. DELETE 删除 → 验证 GET 返回 404
+
+### 【P0】分页和搜索
+1. 创建多条数据
+2. GET 列表 ?page=1&pageSize=2 → 验证分页字段正确
+3. GET 列表 ?keyword=xxx → 验证过滤结果
+
+### 【P1】参数校验
+1. POST 缺少必填字段 → 验证 400
+2. POST 字段格式错误 → 验证 400
+3. PUT 不存在的 ID → 验证 404
+
+### 【P1】认证鉴权（如适用）
+1. 无 token 访问 → 验证 401
+2. 错误 token → 验证 401
+3. 权限不足 → 验证 403

package/recipes/console/base.md

@@ -0,0 +1,37 @@
+# Console 管理后台 — 基础食谱
+
+## 任务分解模式
+
+管理后台 CRUD 页面按以下标准拆分任务（1 session = 1 task）：
+
+1. **backend**: API 接口层（RESTful CRUD + 分页 + 搜索过滤）
+   - steps 包含：路由定义、Controller、Service、数据模型
+   - 验证：curl 请求返回正确状态码和分页结构
+
+2. **frontend**: 列表页面（表格 + 搜索栏 + 分页组件）
+   - steps 包含：页面组件、数据请求、状态管理
+   - 验证：Playwright snapshot 验证页面元素存在
+
+3. **frontend**: 弹窗/表单（新建 + 编辑弹窗 + 表单校验）
+   - steps 包含：弹窗组件、表单项、校验规则、提交逻辑
+   - 验证：Playwright 点击按钮 → snapshot 验证弹窗打开
+
+4. **fullstack**: 联调（前后端串通 + 错误处理 + loading 状态）
+   - steps 包含：接口联调、错误提示、空状态处理
+   - 验证：Playwright 完整 CRUD 流程
+
+5. **test**: E2E 测试（可选，参考 test/crud-e2e.md）
+
+## 通用规则
+
+- 搜索框 + 表格 + 分页合并为一个 frontend 任务（不要拆太碎）
+- 弹窗 + 表单作为独立 frontend 任务（UI 和逻辑较复杂）
+- 后端 API 作为独立 backend 任务
+- 前后端联调作为 fullstack 任务
+- 每个任务必须有可执行的验证步骤
+
+## 反面案例
+
+- "搜索框"、"表格"、"分页"各拆为独立任务 → 太碎，合并
+- "全部前端"合为一个任务 → 太大（弹窗应独立）
+- 忽略验证步骤 → 每个 task 的 steps 最后一步必须是验证命令

package/recipes/console/components/modal-form.md

@@ -0,0 +1,20 @@
+# 弹窗 + 表单
+
+## 任务分解指导
+弹窗和表单作为独立的 frontend 任务。
+steps 中应包含：弹窗组件 → 表单项 → 校验规则 → 提交 → 关闭 → 列表刷新。
+
+## 实现要点
+- 新建弹窗：表单为空，提交调用 POST API
+- 编辑弹窗：表单回填已有数据，提交调用 PUT API
+- 共用同一个弹窗组件（通过 mode 区分新建/编辑）
+- 表单校验：必填项、格式校验（邮箱、手机号等）、长度限制
+- 提交 loading：防重复提交
+- 提交成功后：关闭弹窗 + 刷新列表 + 提示消息
+- 提交失败：显示错误信息，不关闭弹窗
+
+## 验证策略
+- 点击新建按钮 → snapshot 验证弹窗打开 + 表单元素存在
+- 不填必填项直接提交 → 验证校验提示出现
+- 正确填写并提交 → 验证弹窗关闭 + 列表数据更新
+- 点击编辑 → 验证弹窗打开 + 数据回填

package/recipes/console/components/pagination.md

@@ -0,0 +1,17 @@
+# 分页组件
+
+## 任务分解指导
+分页与表格合并为一个 frontend 任务，不单独拆分。
+steps 中应包含：分页参数 → 分页 UI → 翻页请求 → 总数显示。
+
+## 实现要点
+- 分页模式：offset + limit（如 `?page=1&pageSize=10`）
+- 总数显示：从 API 响应中取 total 字段
+- 默认每页条数：10 条（可配置）
+- 页码变化触发重新请求
+- URL 同步：当前页码反映在 URL query 中（可选）
+
+## 验证策略
+- 验证分页组件渲染（页码、上一页/下一页按钮）
+- 点击第 2 页 → 验证数据变化
+- 验证总数显示正确

package/recipes/console/components/search.md

@@ -0,0 +1,17 @@
+# 搜索组件
+
+## 任务分解指导
+搜索功能通常与列表任务合并为一个 frontend 任务，不单独拆分。
+steps 中应包含：搜索框 UI → 防抖处理 → API 请求参数拼接 → 列表刷新。
+
+## 实现要点
+- 输入防抖 300ms，避免频繁请求
+- 搜索关键词作为 query 参数传给列表 API（如 `?keyword=xxx`）
+- 支持清空搜索恢复全量数据
+- 搜索时显示 loading 状态
+- 如有多个筛选条件，使用表单组合（日期范围、下拉选择、关键词等）
+
+## 验证策略
+- 输入已知关键词 → snapshot 验证列表数据过滤
+- 清空搜索 → 验证恢复全量
+- 快速连续输入 → 验证只发一次请求（防抖生效）

package/recipes/console/components/table-list.md

@@ -0,0 +1,18 @@
+# 数据表格
+
+## 任务分解指导
+表格是列表页的核心，与搜索和分页合并为一个 frontend 任务。
+steps 中应包含：列定义 → 数据请求 → 渲染 → 操作列按钮。
+
+## 实现要点
+- 列定义清晰：字段名、显示名、宽度、对齐方式、渲染方式
+- 操作列：编辑、删除按钮（按业务需求扩展）
+- 空状态：无数据时显示友好提示
+- Loading 状态：请求中显示骨架屏或 spinner
+- 如需行选择：checkbox 列 + 批量操作栏
+- 如需排序：列头排序图标 + API 排序参数
+
+## 验证策略
+- snapshot 验证表格元素存在（table/thead/tbody）
+- 验证至少有 1 行数据（或空状态文案）
+- 验证操作列按钮可点击

package/recipes/console/components/tabs.md

@@ -0,0 +1,14 @@
+# 标签页
+
+## 任务分解指导
+标签页通常作为页面布局的一部分，合并到对应页面的 frontend 任务中。
+
+## 实现要点
+- Tab 切换：点击切换内容区域
+- 路由联动：Tab 与 URL hash/query 同步
+- 懒加载：未激活的 Tab 不渲染内容
+- 徽标/计数：Tab 标题旁显示数量
+
+## 验证策略
+- 点击各 Tab → 验证内容切换
+- 刷新页面 → 验证 Tab 状态保持（路由联动）