create-vibe-workflow 0.1.0 → 0.2.0

package/templates/skills/frontend/frontend-patterns/SKILL.md.ejs

@@ -0,0 +1,195 @@
+# Frontend Patterns — 前端开发模式
+
+> 使用此 skill 时：实现 UI 组件、管理状态、优化前端性能时。
+
+## 组件组合模式
+
+### 原则
+
+```text
+【组合优于继承】
+- 小组件组合成复杂 UI
+- 每个组件只有一个职责
+- 组件不应知道父组件的内部细节
+
+【容器 vs 展示】
+- 容器组件：管理状态和数据获取
+- 展示组件：纯渲染，通过属性接收数据和回调
+```
+
+### 组件结构模板
+
+```text
+Component/
+├── Component.{ext}          # 主组件
+├── Component.types.{ext}    # 类型定义
+├── Component.styles.{ext}   # 样式
+├── Component.test.{ext}     # 测试
+├── parts/                   # 子组件
+│   ├── PartA.{ext}
+│   └── PartB.{ext}
+└── index.{ext}              # 重导出
+```
+
+## 状态管理决策矩阵
+
+| 场景 | 方案 | 说明 |
+|------|------|------|
+| 局部 UI 状态（表单输入、折叠展开） | 组件内局部状态 | 最简单的方案，不需要外部管理 |
+| 子组件需要访问父组件状态 | 属性传递（Props Drilling） | 1-2 层时适用 |
+| 多个不相关组件需要共享状态 | 提升状态（Lifting State Up） | 移到最近的共同祖先 |
+| 深层嵌套组件需要共享状态 | 上下文（Context） | 避免多层属性传递 |
+| 上下文+复杂更新逻辑 | 上下文 + Reducer | 类似 Redux 但内置 |
+| 跨页面/全局状态 | 专用状态管理库 | 如 Zustand、Pinia、Redux Toolkit |
+| 服务端数据缓存 | 数据获取库 | 如 React Query、SWR、Apollo |
+
+### 受控 vs 非受控
+
+```text
+受控组件：
+  值由父组件通过属性控制 + 通过回调通知变更
+  适用场景：需要实时验证、条件禁用、联动逻辑
+
+非受控组件：
+  值由组件自身管理，父组件通过 ref 获取
+  适用场景：简单表单、非关键输入、第三方集成
+
+规则：优先受控，只在确实不需要控制时才非受控。
+```
+
+### 上下文 + Reducer 模式
+
+```text
+适用场景：多个子组件共享状态，且有复杂更新逻辑
+
+结构：
+  [Provider 组件]
+    - 创建上下文
+    - 包装 Reducer（状态 + 分发函数）
+    - 提供状态和方法给子组件
+
+  [子组件]
+    - 通过上下文读取状态
+    - 通过分发函数发送动作
+
+限制：
+  - 上下文值变化时所有消费者重新渲染
+  - 不适合高频更新场景
+  - 拆分上下文避免不必要的重渲染
+```
+
+## 自定义 Hooks / Composables 模式
+
+### Hook 设计规则
+
+```text
+1. 以 use- 前缀命名（约定）
+2. 一个 hook 只做一件事
+3. 返回对象而非数组（调用方不需要记住顺序）
+4. 副作用集中管理
+5. 暴露 loading/error/data 三元状态
+```
+
+### 常见 Hook 类型
+
+```text
+数据获取 Hook：
+  use{Resource}() → { data, isLoading, error, refetch }
+
+状态管理 Hook：
+  use{Feature}State() → { state, actions, reset }
+
+事件处理 Hook：
+  use{Event}(handler) → 自动绑定和清理
+
+交叉观察 Hook：
+  use{Observer}(ref, options) → { entry, isIntersecting }
+
+媒体查询 Hook：
+  useMediaQuery(query) → boolean
+
+定时器 Hook：
+  useInterval(callback, delay) → { start, stop, isRunning }
+```
+
+## 性能优化模式
+
+### 优化策略决策
+
+| 场景 | 策略 | 实现方式 |
+|------|------|---------|
+| 计算开销大的纯函数 | 记忆化 | 缓存计算结果，输入不变时复用 |
+| 列表渲渲染 | 虚拟化 | 只渲染可见区域的元素 |
+| 大组件渲染 | 懒加载 | 按需加载组件代码 |
+| 图片加载 | 懒加载 | Intersection Observer + placeholder |
+| 不必要的重渲染 | 属性比较 | 减少不必要的重新渲染 |
+| 首次加载过慢 | 代码分割 | 按路由/按功能分包 |
+
+### 通用性能检查清单
+
+```
+[ ] 列表项有唯一且稳定的 key
+[ ] 大数据列表使用虚拟化
+[ ] 大文件/组件按需懒加载
+[ ] 图片使用适当大小和懒加载
+[ ] 计算密集型操作用记忆化
+[ ] 不必要属性传递已合并或消除
+[ ] 事件监听在组件卸载时清理
+[ ] 动画使用 GPU 加速属性（transform/opacity）
+```
+
+## 表单处理模式
+
+```text
+【表单模式三选一】
+
+简单表单（3-5 个字段）：
+  组件内状态管理
+  → 手动验证 → 提交
+
+中等表单（5-15 字段，有联动）：
+  表单库
+  → Schema 验证 → 自动错误展示 → 提交
+
+复杂表单（15+ 字段，多步骤，动态字段）：
+  表单库 + 状态管理
+  → Schema 验证 → 分步保存 → 最终提交
+```
+
+## 错误边界模式
+
+```text
+策略：每层 UI 区域包裹错误边界
+
+布局层：
+  → 全局错误页面（整个应用崩溃时显示）
+
+功能模块层：
+  → 模块降级（该模块不可用但不影响其他模块）
+
+单个组件层：
+  → 组件回退（显示占位或重试按钮）
+
+错误边界应提供：
+  1. 用户友好提示
+  2. 重试按钮
+  3. 错误日志上报（开发者可追溯）
+```
+
+## 无障碍（Accessibility）
+
+```text
+最低标准（必须做到）：
+  [ ] 所有交互元素可通过键盘操作
+  [ ] 图片有 alt 文本
+  [ ] 表单输入有 label
+  [ ] 颜色对比度 ≥ 4.5:1
+  [ ] 动态内容更新有 aria-live 区域
+
+进阶标准（推荐做到）：
+  [ ] 页面有合理的 heading 层级
+  [ ] 焦点顺序符合视觉顺序
+  [ ] 自定义组件有正确的 ARIA role
+  [ ] 错误提示通过 aria-describedby 关联
+  [ ] 支持减少动效（prefers-reduced-motion）
+```

package/templates/skills/skill-manifest.json

@@ -0,0 +1,59 @@
+{
+  "version": 1,
+  "domains": {
+    "workflow": {
+      "always": true,
+      "label": "工作流核心",
+      "desc": "开发流程强制执行",
+      "skills": [
+        "tdd-workflow",
+        "verification-loop",
+        "security-review",
+        "coding-standards",
+        "search-first",
+        "strategic-compact"
+      ]
+    },
+    "frontend": {
+      "projectTypes": ["web", "fullstack"],
+      "label": "前端开发",
+      "desc": "组件/状态/性能模式",
+      "skills": ["frontend-patterns"]
+    },
+    "backend": {
+      "projectTypes": ["api", "fullstack"],
+      "label": "后端开发",
+      "desc": "API/仓储/服务层模式",
+      "skills": ["backend-patterns"]
+    },
+    "database": {
+      "needsDb": true,
+      "label": "数据库",
+      "desc": "索引/迁移/查询优化",
+      "skills": ["postgres-patterns", "database-migrations"]
+    },
+    "testing": {
+      "projectTypes": ["web", "api", "fullstack"],
+      "label": "测试",
+      "desc": "E2E 自动化测试",
+      "skills": ["e2e-testing"]
+    },
+    "devops": {
+      "manual": true,
+      "label": "DevOps",
+      "desc": "Docker/CI/CD/部署",
+      "skills": ["docker-patterns", "deployment-patterns"]
+    },
+    "advanced": {
+      "userLevel": "developer",
+      "label": "进阶技能",
+      "desc": "诊断/架构审计/精简沟通",
+      "skills": [
+        "caveman",
+        "diagnose",
+        "improve-codebase-architecture",
+        "grill-with-docs"
+      ]
+    }
+  }
+}

package/templates/skills/skills-lock.template.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "skills": {},
+  "_comment": "在此记录手动安装的外部技能。格式参考 _example",
+  "_example": {
+    "agent-browser": {
+      "source": "vercel-labs/agent-browser",
+      "sourceType": "github",
+      "computedHash": ""
+    }
+  }
+}

package/templates/skills/testing/e2e-testing/SKILL.md.ejs

@@ -0,0 +1,224 @@
+# E2E Testing — 端到端自动化测试
+
+> 使用此 skill 时：编写浏览器自动化测试、设计测试套件结构、调试测试失败时。
+
+## 测试结构规范
+
+### 测试文件组织
+
+```text
+e2e/
+├── specs/                        # 测试用例文件
+│   ├── auth/                     # 按功能模块分组
+│   │   ├── login.spec.{ext}
+│   │   ├── register.spec.{ext}
+│   │   └── password-reset.spec.{ext}
+│   ├── checkout/
+│   │   ├── cart.spec.{ext}
+│   │   ├── payment.spec.{ext}
+│   │   └── order-confirmation.spec.{ext}
+│   └── profile/
+│       └── edit-profile.spec.{ext}
+├── pages/                        # Page Object 模型
+│   ├── LoginPage.{ext}
+│   ├── CheckoutPage.{ext}
+│   └── ProfilePage.{ext}
+├── fixtures/                     # 测试夹具（登录状态、测试数据）
+│   ├── auth-fixtures.{ext}
+│   └── test-users.json
+└── helpers/                      # 工具函数
+    ├── test-utils.{ext}
+    └── db-helpers.{ext}
+```
+
+### 测试用例命名
+
+```text
+// 描述格式：{功能} — {场景} — {期望结果}
+
+"用户登录 — 输入正确凭据 — 重定向到首页"
+"用户登录 — 输入错误密码 — 显示错误提示"
+"用户登录 — 连续 5 次失败 — 账号被临时锁定"
+```
+
+## Page Object 模式
+
+### 结构规范
+
+```text
+每个页面一个类，包含：
+  1. 页面选择器（data-testid 优先）
+  2. 页面操作（方法）
+  3. 页面断言（验证方法）
+
+示例结构：
+  class LoginPage {
+    // === 选择器 ===
+    emailInput()           // data-testid="login-email"
+    passwordInput()        // data-testid="login-password"
+    submitButton()         // data-testid="login-submit"
+    errorMessage()         // data-testid="login-error"
+    loadingIndicator()     // data-testid="login-loading"
+
+    // === 操作 ===
+    async navigate()       // 导航到登录页
+    async login(email, password)  // 执行登录流程
+    async getErrorMessage()       // 获取错误文案
+
+    // === 断言 ===
+    async expectLoginSuccess()    // 验证登录成功
+    async expectValidationError() // 验证验证错误
+    async expectRateLimited()     // 验证限流提示
+  }
+```
+
+### Selector 策略
+
+```text
+【优先级从高到低】
+
+1. data-testid（首选）
+   [data-testid="login-submit"]
+   优点：与样式/语义解耦，UI 变更不影响测试
+
+2. 文本内容（推荐）
+   text="提交"
+   优点：接近用户视角
+   注意：注意国际化文案变化
+
+3. ARIA 属性
+   [role="button"][name="提交"]
+   优点：语义清晰，辅助无障碍测试
+
+4. CSS 选择器（次选）
+   .form > .actions > button.primary
+   注意：对 UI 变化敏感
+
+5. XPath（不推荐，除非上面都不行）
+   脆弱、难读、POS 维护
+```
+
+## Wait 策略
+
+```text
+【规则】
+  - 优先用自动等待（内置 auto-waiting）
+  - 特定场景用显式等待
+  - 禁止固定 sleep/等待
+
+推荐方式（按优先级）：
+  1. 自动等待
+     点击/输入等操作自动等待元素可交互
+
+  2. 定位器断言
+     expect(element).toBeVisible()
+     自动重试直到断言通过
+
+  3. 特定 URL/网络等待
+     waitForURL('**/dashboard')
+     waitForResponse(res => res.url().includes('/api/orders'))
+
+  4. 自定义等待（最后一招）
+     waitForFunction(() => document.title === 'Dashboard')
+
+不推荐：
+  wait(3000)  // 固定等待 — 慢且不可靠
+```
+
+## 测试数据管理
+
+```text
+【测试数据策略】
+
+独立数据：
+  每个测试创建自己的数据
+  优点：测试隔离性好
+  缺点：慢
+
+共享数据：
+  beforeAll 创建一次，多个测试复用
+  优点：快
+  缺点：测试间耦合
+
+推荐：独立数据（默认）+ 共享数据（只读场景）
+
+数据清理：
+  - 每个测试清理自己创建的数据
+  - 或使用事务回滚（DB 测试）
+  - 或使用测试容器（Docker 重置）
+
+测试账号：
+  - 专用测试账号（不要用真实用户）
+  - 每个环境使用不同账号
+  - 密码使用环境变量或 CI secret
+```
+
+## 失败诊断机制
+
+```text
+失败时自动收集：
+
+截图（Screenshot）：
+  - 测试失败时自动截图
+  - 保留失败时的页面状态
+  - 命名：{测试文件}-{测试名}-{时间戳}.png
+
+视频（Video）：
+  - 录制整个测试运行过程
+  - 回放看到每一步操作
+  - 注意存储空间（差异压缩）
+
+Trace（追踪）：
+  - 记录每个操作的完整上下文
+  - 包括：网络请求、Console 日志、源码映射
+  - 可回放查看失败前的操作序列
+
+Console 日志：
+  - 收集所有 console.error / console.warn
+  - 关联到具体测试用例
+```
+
+## CI 集成配置
+
+```text
+CI 运行策略：
+  - 只在包含 E2E 相关变更时触发
+  - 并行运行（分片）减少等待时间
+  - 重试策略：失败自动重试 1-2 次（针对 flaky 测试）
+
+并行策略：
+  shardCount: 4               // 4 个分片并行
+  workers: 2                   // 每个分片 2 个 worker
+
+重试策略：
+  retries: 2                   // 失败重试 2 次
+  maxFailures: 10              // 超过 10 个失败停止
+
+环境变量：
+  BASE_URL                     // 测试目标 URL
+  CI                           // CI 环境标识
+  RETRY_COUNT                  // 重试次数
+```
+
+## Flaky 测试处理
+
+```text
+识别 flaky 测试：
+  - 同一测试有时过有时不过
+  - 和代码变更无关的失败
+
+常见原因及修复：
+  原因                    | 修复
+  ------------------------|-------------------------------
+  时序问题（异步未完成）    | 用显式等待代替固定等待
+  测试间数据干扰           | 每个测试独立数据
+  环境/网络不稳定          | 合理重试策略
+  选择器脆弱               | 使用 data-testid
+  状态未清理               | beforeEach 清理状态
+
+处理流程：
+  1. 标记为 flaky 但不阻塞 CI
+  2. 分析失败原因（trace + screenshot）
+  3. 修复根本原因
+  4. 验证不再 flaky 后取消标记
+```

package/templates/skills/workflow/coding-standards/SKILL.md.ejs

@@ -0,0 +1,143 @@
+# Coding Standards — 编码规范
+
+> 使用此 skill 时：在生成代码或审查代码时，应用以下标准。
+
+## 不可变性（最高优先级）
+
+**永远创建新对象，绝不修改已有对象。**
+
+```text
+// ❌ 错误 — 直接修改原对象
+updateUser(user, "name", "newName") {
+    user.name = "newName"    // 改变了原对象
+    return user
+}
+
+// ✅ 正确 — 返回新副本
+updateUser(user, "name", "newName") {
+    return { ...user, name: "newName" }
+}
+```
+
+为什么？
+- 无副作用，调用方不会被意外影响
+- 调试更容易（值不会"神秘改变"）
+- 并发安全（多个操作可安全共享数据）
+
+## 文件组织
+
+```
+【原则】多小文件 > 少大文件
+- 高内聚、低耦合
+- 每个文件 200-400 行，上限 800 行
+- 按功能/领域组织，不按类型组织
+```
+
+### 典型目录结构
+
+```text
+src/
+├── modules/
+│   └── {module-name}/
+│       ├── {module}.{ext}             # 模块入口
+│       ├── {module}.controller.{ext}  # 路由/请求处理
+│       ├── {module}.service.{ext}     # 业务逻辑
+│       ├── {module}.schema.{ext}      # 校验 schema
+│       ├── {module}.types.{ext}       # 类型定义
+│       └── {module}.test.{ext}        # 测试
+├── shared/
+│   ├── utils/                         # 通用工具函数
+│   ├── types/                         # 共享类型
+│   └── constants/                     # 常量
+└── config/                            # 配置
+```
+
+## 命名规范
+
+| 类别 | 规范 | 示例 |
+|------|------|------|
+| 文件名 | kebab-case | `user-service.{ext}` |
+| 目录名 | kebab-case | `user-module/` |
+| 变量/函数 | camelCase | `getUserById` |
+| 类/接口/类型 | PascalCase | `UserService` |
+| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| 枚举值 | UPPER_SNAKE_CASE | `Role.ADMIN` |
+| 布尔前缀 | is/has/can/should | `isActive`, `hasPermission` |
+| 私有成员 | 下划线前缀 | `_internalMethod` |
+
+## 错误处理
+
+```text
+【三条规则】
+1. 所有可能失败的 IO 操作必须用 try-catch 包裹
+2. 错误必须包含有用信息（上下文 + 原因）
+3. 边界层（API/UI）必须将错误转为用户友好的形式
+```
+
+### 错误分层
+
+```text
+系统边界层（API/Controller 等）
+  └─ 捕获所有异常，转为错误响应格式
+      └─ 业务逻辑层（Service）
+          └─ 抛出具名业务错误（ValidationError / NotFoundError 等）
+              └─ 数据访问层（Repository/DAO）
+                  └─ 包装底层错误为数据访问错误
+```
+
+## 输入验证
+
+```text
+【所有系统入口点必须验证输入】
+- API 端点参数
+- 表单提交数据
+- 文件导入内容
+- 外部 API 回调数据
+- 消息队列消息
+```
+
+## 代码质量自查清单
+
+- [ ] 命名清楚表达意图（好命名不需要注释解释）
+- [ ] 函数不超过 50 行（超过则提取子函数）
+- [ ] 文件不超过 800 行
+- [ ] 嵌套不超过 4 层（超过则提前 return 或提取函数）
+- [ ] 没有死代码（未使用的变量/函数/导入）
+- [ ] 没有循环依赖
+- [ ] 没有魔法数字/字符串（使用命名常量）
+- [ ] 错误路径已处理
+- [ ] 边界情况已覆盖（空值、零值、超长值）
+- [ ] 日志包含足够的上下文信息
+
+## 日志规范
+
+```text
+【禁止】在生产代码中使用 console.log / print / println
+
+级别使用：
+  error   — 需要人工介入的异常（不可恢复）
+  warn    — 可恢复但需要注意的情况（重试成功、降级）
+  info    — 关键业务流程节点（用户注册、下单）
+  debug   — 调试信息（仅在开发/调试环境输出）
+
+每条日志应包含：
+  1. 操作标识（操作名、请求 ID）
+  2. 上下文数据（用户 ID、资源 ID 等，不含敏感信息）
+  3. 耗时/状态
+```
+
+## 注释规范
+
+```text
+// 文档注释 — 公开 API 必须有
+/** 描述函数行为及返回值 */
+
+// 实现注释 — 解释"为什么"非"是什么"
+// 使用轮询而非 WebSocket 因为客户端环境不支持长连接
+
+// TODO 注释 — 必须有对应 Issue 跟踪
+// TODO(#1234): 这个查询需要加索引
+
+// 不需要的注释 — 代码本身已表达意图时
+// ❌ 遍历用户列表 ← 这行代码已经说明了一切
+```