@miniidealab/openlogos 0.2.0 → 0.3.0

package/skills/test-orchestrator/SKILL.md

@@ -0,0 +1,142 @@
+# Skill: Test Orchestrator
+
+> 基于业务场景和时序图设计 **API 编排测试**用例（Phase 3 Step 3b），覆盖正常/异常/边界场景，自动识别外部依赖并应用测试策略，作为端到端 API 验收标准。**仅适用于涉及 API 的项目。**
+
+## 与 test-writer 的关系
+
+本 Skill 负责测试金字塔的**顶层**——API 编排测试（HTTP 请求级别），执行于 Phase 3 Step 3b。
+
+底层的单元测试和场景测试（函数调用级别）由 `test-writer` Skill 在 Step 3a 完成。Step 3a 是所有项目的必选步骤，Step 3b（本 Skill）仅在项目涉及 API 时执行。
+
+## 触发条件
+
+- 用户要求设计 API 编排测试
+- 用户提到 "Phase 3 Step 3b"、"API 编排"、"编排测试"
+- Step 3a（test-writer）完成后，AI 引导用户继续进入 Step 3b
+- 用户需要验收已部署的 API 代码
+
+## 前置依赖
+
+- `logos/resources/test/` 中包含测试用例规格文档（Step 3a 已完成）
+- `logos/resources/prd/3-technical-plan/2-scenario-implementation/` 中包含场景时序图
+- `logos/resources/api/` 中包含 API 规格（OpenAPI YAML）
+- `logos-project.yaml` 中包含 `external_dependencies`（如有）
+
+如果项目不涉及 API（纯 CLI 工具、纯前端等），跳过此 Skill。
+
+## 核心能力
+
+1. 从时序图和 API YAML 设计正常流程编排
+2. 基于异常用例（EX-N.M）设计异常流程编排
+3. 设计边界用例（合法但非主路径的变体）
+4. 定义变量提取和传递机制
+5. **识别外部依赖并应用测试策略**：读取 `logos-project.yaml` 的 `external_dependencies`，在涉及外部服务的步骤中自动插入 `mock` 字段
+6. 执行编排并验证结果
+
+## 执行步骤
+
+### Step 1: 读取场景上下文
+
+读取以下文件建立完整上下文：
+
+- 场景时序图（`logos/resources/prd/3-technical-plan/2-scenario-implementation/`）
+- API YAML（`logos/resources/api/`）
+- `logos-project.yaml` —— 重点读取 `external_dependencies` 字段
+
+### Step 2: 识别外部依赖
+
+将 `external_dependencies` 中的 `used_in` 与当前场景编号匹配。如果当前场景涉及外部依赖：
+
+- 记录该依赖的 `test_strategy` 和 `test_config`
+- 如果某个依赖声明了 `used_in` 但缺少 `test_strategy`，**主动询问用户**测试策略
+
+如果 `logos-project.yaml` 中没有 `external_dependencies` 字段，但时序图中存在对外部服务的调用（如发送邮件、请求支付等），也应主动提醒用户补充。
+
+### Step 3: 设计正常流程编排
+
+按时序图的 Step 编号，逐步设计 API 调用链：
+
+- 每步包含 method、url、headers、body、expected_status
+- 涉及外部依赖的步骤，插入 `mock` 字段（见输出规范）
+- 上一步响应中需要传递的变量，使用 `extract` 定义提取规则
+
+### Step 4: 设计异常流程编排
+
+为每个 EX 异常用例设计独立的编排，确保：
+
+- 异常场景也能覆盖外部依赖的失败情况
+- 使用 `mock` 字段模拟外部服务异常（如超时、返回错误等）
+
+### Step 5: 设计边界用例编排
+
+识别合法但非主路径的变体（如密码长度刚好在边界值、空字段等），补充编排。
+
+### Step 6: 输出编排 JSON
+
+按场景输出可执行的编排 JSON 文件。
+
+## 输出规范
+
+- 文件格式：JSON
+- 存放位置：`logos/resources/scenario/`
+- 按场景分文件：`user-auth.json`、`payment-flow.json`
+- 编排中的每一步对应时序图的 Step 编号
+
+### mock 字段结构
+
+当某一步涉及外部依赖时，在该 step 中添加 `mock` 字段：
+
+```json
+{
+  "step": "Step 2: 获取邮件验证码",
+  "mock": {
+    "dependency": "邮件服务",
+    "strategy": "test-api",
+    "config": "GET /api/test/latest-email?to={email}",
+    "extract": { "code": "response.body.code" }
+  },
+  "method": "GET",
+  "url": "/api/test/latest-email?to={{email}}",
+  "expected_status": 200,
+  "extract": {
+    "verification_code": "body.code"
+  }
+}
+```
+
+`mock` 字段说明：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `dependency` | string | 对应 `external_dependencies` 中的 `name` |
+| `strategy` | string | 测试策略（`test-api` / `fixed-value` / `env-disable` / `mock-callback` / `mock-service`） |
+| `config` | string | 测试策略的具体配置，来自 `test_config` |
+| `extract` | object | 从 mock 响应中提取变量（可选） |
+
+不同策略的编排表现：
+
+- **`test-api`**：该步骤的 url 替换为后门 API 地址
+- **`fixed-value`**：该步骤不发起实际请求，直接在 `extract` 中注入固定值
+- **`env-disable`**：该步骤标记为跳过，附带注释说明前提条件
+- **`mock-callback`**：在前一步完成后插入一个额外的 mock 回调请求
+- **`mock-service`**：该步骤的 url 替换为本地 mock 服务地址
+
+## 实践经验
+
+- **正常编排是骨架**：先完成正常流程编排，确保主路径可以跑通
+- **异常编排是保障**：每个外部调用至少 1 个异常编排
+- **变量传递**：前一步的响应中提取变量（如 token、user_id），传给后续步骤
+- **测试数据**：编排开始前准备测试数据，结束后清理，保证幂等性
+- **并发测试**：关键场景需要考虑并发情况（如：两人同时注册同一邮箱）
+- **外部依赖先查清单**：开始设计编排前先读 `logos-project.yaml` 的 `external_dependencies`，没有声明的外部调用要主动提醒用户补充
+- **mock 策略不要自行决定**：测试策略由 S12 技术架构设计（Phase 3 Step 0, architecture-designer）确定，编排测试阶段只负责消费，不要擅自更改
+- **与 `openlogos verify` 的关系**：API 编排测试也可产出与 `spec/test-results.md` 相同格式的 JSONL 结果。编排测试运行后，结果同样写入 `logos/resources/verify/test-results.jsonl`，`openlogos verify` 统一读取并判定验收
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我设计编排测试`
+- `基于 API 规格帮我生成 S01 的编排测试`
+- `帮我把所有场景的正常路径编排出来`
+- `帮我给 S02 补充异常路径的编排测试`

package/skills/test-writer/SKILL.md

@@ -0,0 +1,247 @@
+# Skill: Test Writer
+
+> 基于时序图、API 规格和 DB 约束，为每个业务场景设计单元测试用例和场景测试用例。适用于所有项目类型（API 服务、CLI 工具、前端应用、库等），是代码生成前的必要前置步骤。
+
+## 触发条件
+
+- 用户要求设计测试用例或测试方案
+- 用户提到 "Phase 3 Step 3"、"Step 3a"、"测试先行"、"测试设计"
+- 已有场景时序图，需要在写代码前设计测试
+- 用户指定某个场景编号（如 S01）需要设计测试
+
+## 前置依赖
+
+- `logos/resources/prd/3-technical-plan/2-scenario-implementation/` 中包含场景时序图（**必需**）
+- `logos/resources/api/` 中包含 API 规格（有则读取，无则跳过——非 API 项目可能没有）
+- `logos/resources/database/` 中包含 DB DDL（有则读取，无则跳过）
+- `logos/resources/prd/1-product-requirements/` 中包含需求文档（用于追溯验收条件）
+
+**不可跳过**：无论项目类型如何，Step 3a（本 Skill）都必须执行。
+
+## 核心能力
+
+1. 从 API 字段约束（类型、格式、长度、枚举）中提取单元测试用例
+2. 从 DB 约束（UNIQUE、CHECK、NOT NULL、FK）中提取单元测试用例
+3. 从业务规则和 EX 异常用例中的单点错误处理提取单元测试用例
+4. 从时序图 Step 序列提取场景测试用例（主路径）
+5. 从 EX 异常用例提取场景测试用例（异常路径）
+6. 从 Phase 1/2 验收条件反向校验测试覆盖完整性
+
+## 执行步骤
+
+### Step 1: 加载场景上下文
+
+读取以下文件建立完整上下文：
+
+- 场景时序图（`logos/resources/prd/3-technical-plan/2-scenario-implementation/`）
+- API YAML（`logos/resources/api/`）—— 如果存在
+- DB DDL（`logos/resources/database/`）—— 如果存在
+- Phase 1 需求文档（验收条件）
+- Phase 2 产品设计文档（交互级验收条件）
+
+确认当前场景的：
+- **Step 数量**：时序图中有多少个 Step
+- **EX 数量**：有多少个异常用例
+- **API 端点**：涉及哪些端点及其字段约束
+- **DB 表**：涉及哪些表及其约束
+
+### Step 2: 设计单元测试用例
+
+从三类来源提取单元测试用例：
+
+#### 2a: API 字段约束
+
+逐个检查 API 端点的 `requestBody` 和 `parameters`：
+
+- `type` → 类型错误用例（传入错误类型）
+- `format`（email、uuid、date-time）→ 格式校验用例
+- `minLength` / `maxLength` → 边界值用例（刚好达到、超出 1 位）
+- `required` → 必填缺失用例
+- `enum` → 枚举值用例（合法值 + 非法值）
+- `minimum` / `maximum` → 数值范围用例
+
+#### 2b: DB 约束
+
+逐个检查相关表的约束：
+
+- `UNIQUE` → 重复插入用例
+- `NOT NULL` → 空值插入用例
+- `CHECK` → 违反检查条件的用例
+- `FOREIGN KEY` → 引用不存在记录的用例
+- `DEFAULT` → 不传值时默认值验证
+
+#### 2c: 业务规则
+
+从时序图 Step 说明和 EX 异常用例中提取单点业务逻辑：
+
+- 权限检查（未登录、无权限）
+- 状态机转换（只有特定状态才能执行操作）
+- 限流 / 频控规则
+- 数据计算逻辑（金额计算、折扣规则）
+
+**每个单元测试用例格式**：
+
+| 字段 | 说明 |
+|------|------|
+| ID | `UT-{场景编号}-{序号}`，如 `UT-S01-01` |
+| 描述 | 测试什么行为 |
+| 来源 | 约束出处（如 `auth.yaml → register → email: format:email`） |
+| 前置条件 | 测试前需要的状态 |
+| 输入 | 具体输入值 |
+| 预期输出 | 期望的返回值或错误信息 |
+
+### Step 3: 设计场景测试用例
+
+从两类来源提取场景测试用例：
+
+#### 3a: 主路径（时序图 Step 序列）
+
+将时序图的完整 Step 1 → Step N 视为一次端到端代码调用链：
+
+- 确定场景的入口和出口
+- 标注每个 Step 之间的数据传递（前一步输出作为后一步输入）
+- 验证最终状态（数据库记录、返回值）
+
+#### 3b: 异常路径（EX 异常用例）
+
+将每个 EX 异常用例展开为场景测试用例：
+
+- 标注异常在哪个 Step 触发
+- 验证异常触发后的处理逻辑（错误返回、补偿/回滚）
+- 验证异常未影响其他数据的完整性
+
+**每个场景测试用例格式**：
+
+| 字段 | 说明 |
+|------|------|
+| ID | `ST-{场景编号}-{序号}`，如 `ST-S01-01` |
+| 描述 | 测试什么场景流程 |
+| 覆盖 Steps | 覆盖时序图的哪些 Step（如 `Step 1→6`）或哪个 EX（如 `EX-2.1`） |
+| 前置条件 | 测试前需要的状态和数据 |
+| 操作序列 | 按 Step 顺序的操作列表 |
+| 预期结果 | 最终状态（返回值 + 数据库状态 + 副作用） |
+
+### Step 4: 覆盖度校验
+
+反向校验测试用例是否覆盖了所有关键约束：
+
+- [ ] Phase 1 每个正常验收条件至少对应 1 个 ST 用例
+- [ ] Phase 1 每个异常验收条件至少对应 1 个 ST 或 UT 用例
+- [ ] 每个 EX 异常用例至少对应 1 个 ST 用例
+- [ ] API 每个 `required` 字段至少 1 个 UT 用例
+- [ ] DB 每个 `UNIQUE` / `CHECK` 约束至少 1 个 UT 用例
+
+如有未覆盖项，补充用例或向用户说明理由。
+
+### Step 5: 验收条件追溯
+
+将 Phase 1 需求文档中的每个 GIVEN/WHEN/THEN 验收条件提取出来，为每条分配一个追溯 ID，并关联到覆盖该条件的测试用例 ID。
+
+#### 验收条件 ID 规则
+
+- 格式：`{场景编号}-AC-{两位序号}`，如 `S01-AC-01`、`S01-AC-02`
+- 按需求文档中出现的顺序编号，正常和异常条件统一编号
+- 同一场景的 AC ID 必须连续且唯一
+
+#### 追溯表填写规则
+
+1. 从需求文档读取当前场景的所有验收条件（正常 + 异常）
+2. 为每条验收条件分配 AC ID
+3. 找到覆盖该条件的测试用例 ID（可以是 UT 或 ST），填入「覆盖用例」列
+4. 每个 AC 至少关联 1 个测试用例；如果无法覆盖，在「覆盖用例」列注明原因
+
+`openlogos verify` 会解析此追溯表，将 AC → 用例 ID → 运行结果三层联动，生成完整的验收追溯报告。
+
+### Step 6: 输出测试用例规格文档
+
+按场景输出 Markdown 格式的测试用例规格文档。
+
+### Step 7: 引导后续操作
+
+根据项目类型引导用户进入下一步：
+
+- **涉及 API** → 「继续进入 Step 3b 设计 API 编排测试？」
+- **不涉及 API** → 「测试设计已完成，建议进入代码生成：对我说『按 S01 的规格帮我实现』」
+
+## 输出规范
+
+- **文件格式**：Markdown
+- **存放位置**：`logos/resources/test/`
+- **命名规则**：`{场景编号}-test-cases.md`（如 `S01-test-cases.md`）
+- 每个文件包含：单元测试用例（按来源分组）+ 场景测试用例（主路径 + 异常路径）
+- 用例 ID 全局唯一：`UT-{场景编号}-{序号}` / `ST-{场景编号}-{序号}`
+
+### 文档结构模板
+
+```markdown
+# {场景编号}: {场景名称} — 测试用例
+
+## 一、单元测试用例
+
+### 1.1 {分组名称}（来源：{约束出处}）
+
+| ID | 描述 | 来源 | 前置条件 | 输入 | 预期输出 |
+|----|------|------|---------|------|---------|
+| UT-S01-01 | ... | ... | ... | ... | ... |
+
+## 二、场景测试用例
+
+### 2.1 主路径：{场景名称}
+
+| ID | 描述 | 覆盖 Steps | 前置条件 | 操作序列 | 预期结果 |
+|----|------|-----------|---------|---------|---------|
+| ST-S01-01 | ... | Step 1→6 | ... | ... | ... |
+
+### 2.2 异常路径
+
+| ID | 描述 | 覆盖 EX | 前置条件 | 触发条件 | 预期结果 |
+|----|------|--------|---------|---------|---------|
+| ST-S01-02 | ... | EX-2.1 | ... | ... | ... |
+
+## 三、覆盖度校验
+
+- [x] Phase 1 正常验收条件：全部覆盖
+- [x] Phase 1 异常验收条件：全部覆盖
+- [x] EX 异常用例：全部覆盖
+- [x] API required 字段：全部覆盖
+- [x] DB UNIQUE/CHECK 约束：全部覆盖
+
+## 四、验收条件追溯
+
+| AC ID | 验收条件 | 覆盖用例 |
+|-------|---------|---------|
+| S01-AC-01 | 正常：全新项目初始化 — 创建完整目录结构 | ST-S01-01 |
+| S01-AC-02 | 正常：显式项目名与配置文件不一致时确认 | ST-S01-02 |
+| S01-AC-03 | 异常：项目已初始化 — 显示错误提示 | ST-S01-03, UT-S01-05 |
+```
+
+## 用例 ID 合约
+
+用例 ID（`UT-S01-01`、`ST-S01-01`）是设计文档与运行时的**绑定合约**：
+
+- 在 test-cases.md 中定义的 ID，必须在生成的测试代码中被原样使用
+- 测试代码的 reporter 会把每个用例的 ID 和运行结果写入 JSONL 文件
+- `openlogos verify` 通过 ID 将运行结果映射回测试用例规格，自动判定验收
+- 修改用例 ID 时必须同步修改测试代码中的 ID
+
+详细的 JSONL 格式定义和各语言 reporter 代码模板见 `spec/test-results.md`。
+
+## 实践经验
+
+- **测试用例是设计文档，不是代码**：本 Skill 产出的是 Markdown 格式的测试用例规格，具体的测试代码在 Step 4 代码生成阶段由 AI 基于此规格实现
+- **先单元后场景**：单元测试用例覆盖单个函数的正确性，场景测试覆盖跨模块串联——先确保积木正确，再验证积木拼接
+- **不要遗漏 DB 约束**：很多 Bug 来自数据库层面的约束违反，DB 约束是单元测试用例的重要来源
+- **场景测试关注数据传递**：Step 间的数据传递（前一步输出 → 后一步输入）是最容易出错的地方
+- **EX 异常用例必须有对应的场景测试**：时序图中标注的每个 EX 都应该在场景测试中有体现
+- **边界值优先**：单元测试用例优先覆盖边界值（刚好合法、刚好非法），而不是随机值
+- **与 test-orchestrator 互补**：本 Skill 设计代码层面的测试（函数调用级），test-orchestrator 设计 API 层面的测试（HTTP 请求级）。二者共同覆盖"测试金字塔"的不同层级
+- **用例 ID 是跨阶段合约**：ID 贯穿 test-cases.md → 测试代码 → test-results.jsonl → acceptance-report.md，任何一处不一致都会导致 `openlogos verify` 报告不完整
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我设计测试用例`
+- `帮我设计 S01 的单元测试和场景测试`
+- `帮我给所有 P0 场景设计测试用例`
+- `帮我检查 S01 的测试覆盖度`