create-vibe-workflow 0.1.0 → 0.2.0

package/dist/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/dist/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): 这个查询需要加索引
+
+// 不需要的注释 — 代码本身已表达意图时
+// ❌ 遍历用户列表 ← 这行代码已经说明了一切
+```

package/dist/templates/skills/workflow/search-first/SKILL.md.ejs

@@ -0,0 +1,103 @@
+# Search-First — 研究优先于编码
+
+> 使用此 skill 时：在实现任何新功能之前、在引入新依赖之前、在解决不熟悉的错误之前。
+
+## 工作流
+
+开始编码之前，先执行研究：
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  ① 需求分析   明确要解决的问题、输入输出、约束条件                     │
+│  ② 并行搜索   同时搜索多个渠道（GitHub / 包管理器 / 文档 / 项目内）  │
+│  ③ 方案评估   对比候选方案的匹配度、维护状态、学习成本                │
+│  ④ 决策       选择策略：复用/扩展/组合/自建                          │
+│  ⑤ 实现       开始编码                                              │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## ① 需求分析 — 明确搜索目标
+
+在搜索前，先明确：
+
+```text
+- 要解决什么具体问题？
+- 输入是什么、输出是什么？
+- 有什么约束（性能、安全、兼容性）？
+- 是全新需求还是替代现有方案？
+- 是否有内部已有类似实现？
+```
+
+## ② 并行搜索 — 多源获取信息
+
+同时搜索以下渠道：
+
+### 搜索渠道清单
+
+| 渠道 | 场景 | 搜索什么 |
+|------|------|---------|
+| GitHub 代码搜索 | 寻找参考实现 | 类似功能的仓库、代码片段、Issue 讨论 |
+| 包管理器（npm/PyPI/crates.io 等） | 寻找可复用库 | 功能匹配的包、下载量、最近更新 |
+| 官方文档 | 确认 API 用法 | 版本迁移、配置项、最佳实践 |
+| 项目内代码 | 复用已有模式 | 相邻模块的实现方式、工具函数库 |
+| AI 知识库 | 模式/最佳实践 | 常用设计模式、已知解决方案 |
+
+### 搜索方法
+
+```text
+// GitHub 搜索示例
+搜索: "language:{lang} {keyword} implementation"
+搜索: "topic:{topic} language:{lang}"
+
+// 包管理器搜索
+搜索: "{keyword}" → 检查：最近更新、周下载量、依赖树大小
+
+// 项目内搜索
+搜索: 相邻功能模块的目录结构和使用模式
+搜索: 项目中已使用的类似库/工具
+```
+
+## ③ 方案评估 — 对比候选方案
+
+对每个候选方案，评估以下维度：
+
+| 维度 | 评估问题 |
+|------|---------|
+| 功能匹配 | 覆盖需求的百分之多少？ |
+| 维护状态 | 最近更新？Issue 响应？主仓库活跃？ |
+| 成熟度 | 版本号（<1.0 谨慎）、Star 数、被依赖数 |
+| 学习成本 | 文档质量、示例数量、概念复杂度 |
+| 集成成本 | 需要多少胶水代码？和现有技术栈兼容？ |
+| 安全 | 已知漏洞？权限模型？ |
+| 性能 | 基准测试？内存/CPU 影响？ |
+| 社区 | 问题是否有解答？Stack Overflow 讨论？ |
+
+## ④ 决策矩阵 — 选择策略
+
+| 情况 | 策略 | 行动 |
+|------|------|------|
+| 有成熟的库覆盖 90%+ 需求 | **采用（Adopt）** | 引入依赖，按文档使用 |
+| 有接近的库但需少量定制 | **扩展（Extend）** | 引入后包装/配置/插件 |
+| 多个库各覆盖一部分 | **组合（Compose）** | 引入多个库，编写胶水层 |
+| 没有合适的库 | **自建（Build）** | 参考调研结果自行实现 |
+
+### 不引入依赖的情况
+
+```text
+- 功能少于 50 行代码可实现
+- 库有已知安全漏洞且不及时修复
+- 库的依赖树过大（间接引入 >50 个包）
+- 库与项目技术栈不兼容
+- 只有一个函数需要但库是整个框架
+```
+
+## ⑤ 反模式
+
+| 反模式 | 问题 | 正确做法 |
+|--------|------|---------|
+| 已知有库但非要自建 | 浪费时间，维护成本高 | 先用库，不够再替换 |
+| 先写代码再搜索 | 可能走错方向 | 先搜索再编码 |
+| 只看第一个结果 | 错过更好的方案 | 至少对比 3 个候选 |
+| 引入大库只用小功能 | 膨胀依赖树 | 自己写或用微库 |
+| 不验证就采用 | 发现不匹配时已投入大量时间 | 先写 PoC 验证 |
+| 搜索完不看 License | 法律风险 | 确认 License 兼容性 |

package/dist/templates/skills/workflow/security-review/SKILL.md.ejs

@@ -0,0 +1,146 @@
+# Security Review — 提交前安全检查
+
+> 使用此 skill 时：在准备提交代码前，或者修改了涉及认证/授权/用户数据/支付/外部 API 调用的代码时。
+
+## 安全检查清单
+
+以下所有检查项必须在每次提交前执行：
+
+### 1. 密钥管理
+
+```
+[ ] 无硬编码密钥（API Key、密码、Token、JWT Secret）
+[ ] 无硬编码数据库连接字符串
+[ ] 无硬编码第三方服务凭据
+[ ] 配置文件中无真实凭据（只有占位符或环境变量引用）
+```
+
+### 2. 输入验证
+
+```
+[ ] 所有用户输入使用 schema 校验（长度/格式/类型/范围）
+[ ] 文件上传有类型/大小限制
+[ ] 批量操作有数量上限
+[ ] URL 参数/路径参数已校验
+```
+
+### 3. SQL / NoSQL 注入防护
+
+```
+[ ] 使用参数化查询或 ORM 内置防护
+[ ] 无字符串拼接 SQL 语句
+[ ] NoSQL 查询使用参数化（非原始字符串注入）
+```
+
+### 4. XSS 防护
+
+```
+[ ] 用户生成内容输出时已转义
+[ ] 富文本内容经 HTML Sanitizer 过滤
+[ ] CSP（Content Security Policy）已配置
+[ ] 无 `innerHTML` / `dangerouslySetInnerHTML` 等危险 API
+```
+
+### 5. CSRF 防护
+
+```
+[ ] 有状态修改操作（POST/PUT/DELETE）有 CSRF 保护
+[ ] SameSite Cookie 已设置
+[ ] API 使用 Token 认证时无需额外 CSRF（但需确认）
+```
+
+### 6. 认证与授权
+
+```
+[ ] 认证失败的响应不泄露用户是否存在
+[ ] 令牌有有效期和刷新机制
+[ ] 每次操作验证资源所有权（防止 IDOR）
+[ ] 未认证用户无法访问受保护资源
+[ ] 权限不足的用户得到 403 而非 401
+```
+
+### 7. 速率限制
+
+```
+[ ] 认证端点有登录尝试限制
+[ ] 公开 API 端点有速率限制
+[ ] 文件上传端点有额外限制
+```
+
+### 8. 错误消息与日志
+
+```
+[ ] 错误消息不泄露内部细节（堆栈、路径、SQL、配置）
+[ ] 日志中不记录密码、Token、信用卡等敏感数据
+[ ] 生产环境关闭调试模式/详细错误
+```
+
+## 常见漏洞修复模板
+
+### 修复硬编码密钥
+
+```text
+// ❌ 错误
+apiKey = "sk-xxxxxxxxxxxxxxxx"
+
+// ✅ 正确
+apiKey = env("API_KEY")
+if apiKey is empty → throw "API_KEY not configured"
+```
+
+### 修复 SQL 注入
+
+```text
+// ❌ 错误
+query = "SELECT * FROM users WHERE id = '" + userId + "'"
+
+// ✅ 正确
+query = "SELECT * FROM users WHERE id = $1"
+execute(query, [userId])
+```
+
+### 修复 IDOR（越权）
+
+```text
+// ❌ 错误 — 只检查资源存在，不检查所有权
+resource = db.find(resourceId)
+return resource
+
+// ✅ 正确 — 验证当前用户拥有该资源
+resource = db.find(resourceId)
+if resource.ownerId != currentUserId → throw 403
+return resource
+```
+
+### 安全错误响应
+
+```text
+// ❌ 错误 — 泄露内部信息
+response 500: { "error": "Cannot read property 'x' of null at /src/services/user.js:42" }
+
+// ✅ 正确 — 泛化错误
+response 500: { "error": "Internal server error" }
+// 日志中保留完整信息供调试
+```
+
+## 安全扫描命令
+
+```bash
+# 依赖漏洞扫描
+audit                            # 检查依赖中的已知漏洞
+
+# 密钥扫描（防止敏感信息提交）
+# 使用 pre-commit hook 或 CI 中的密钥扫描工具
+
+# 静态安全分析
+lint --security                  # 运行安全规则集
+```
+
+## 严重程度分级
+
+| 级别 | 定义 | 行动要求 |
+|------|------|---------|
+| CRITICAL | 可直接导致数据泄露/服务入侵 | 必须修复，阻断提交 |
+| HIGH | 在特定条件下可被利用 | 必须修复 |
+| MEDIUM | 增加攻击面 | 建议修复 |
+| LOW | 最佳实践偏离 | 记录待办 |