api-designer

Skill: API Designer

基于时序图设计 OpenAPI 3.0+ YAML 规格，让 API 从场景中自然浮现而非凭空定义。每个端点可追溯到时序图的 Step 编号，确保"无场景不设计 API"。

触发条件

• 用户要求设计 API 或编写 API 文档
• 用户提到 "Phase 3 Step 2"、"API 设计"
• 已有场景时序图，需要细化 API 规格
• 用户提供了一个 API 端点需要详细设计

前置依赖

• logos/resources/prd/3-technical-plan/2-scenario-implementation/ 中包含场景时序图
• logos/resources/prd/3-technical-plan/1-architecture/ 中包含架构概要（确认前后端分离方式、认证方案等）
• logos-project.yaml 的 tech_stack 已填写

如果时序图目录为空，提示用户先完成 Phase 3 Step 1（scenario-architect）。

核心能力

1. 从时序图中提取所有跨系统边界的 API 调用
2. 去重、合并、按领域分组，形成端点清单
3. 设计 OpenAPI 3.0+ YAML 规格（路径、参数、请求体、响应结构）
4. 定义统一的错误响应格式和错误码体系
5. 设计认证方案（Bearer Token / API Key / Cookie）
6. 设计分页、排序、过滤的标准化参数

执行步骤

Step 1: 读取场景上下文

读取以下文件建立完整上下文：

• 场景时序图（logos/resources/prd/3-technical-plan/2-scenario-implementation/）：提取所有跨系统边界的箭头
• 架构概要（logos/resources/prd/3-technical-plan/1-architecture/）：确认认证方案、前后端分离方式、API 网关等
• logos-project.yaml：读取 tech_stack 确认后端框架和部署方式

Step 2: 提取端点清单

遍历所有场景时序图，收集每个跨系统边界的调用箭头：

1. 识别"跨系统边界"的箭头——客户端到服务端、服务端到外部服务、服务间调用
2. 为每个箭头提取：HTTP 方法、路径、所属场景编号和 Step 编号
3. 去重合并——同一个端点可能在多个场景中出现（如 POST /api/auth/login 可能在 S02 和 S03 都有）
4. 输出端点清单摘要供用户确认：

从时序图中识别到 N 个 API 端点：

| # | 方法 | 路径 | 来源场景 | 领域 |
|---|------|------|---------|------|
| 1 | POST | /api/auth/register | S01 Step 2 | auth |
| 2 | POST | /api/auth/login | S02 Step 1 | auth |
| 3 | GET  | /api/projects | S04 Step 1 | projects |

Step 3: 按领域分组

将端点按业务领域分组，每组对应一个 YAML 文件：

• auth.yaml — 认证相关（注册、登录、登出、重置密码）
• projects.yaml — 核心业务对象的 CRUD
• billing.yaml — 支付和订阅

分组原则：

• 同一数据实体的操作放在一起
• 认证/授权独立分组
• 第三方服务回调（如支付回调）放在对应业务领域

Step 4: 设计统一约定

在生成具体端点前，先确定全局约定：

认证方案（从架构概要中读取）：

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

统一错误响应：

components:
  schemas:
    ErrorResponse:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: 机器可读的错误码（如 EMAIL_EXISTS）
        message:
          type: string
          description: 人类可读的错误描述
        details:
          type: object
          description: 附加错误信息（如字段级校验错误）

分页参数（适用于列表端点）：

parameters:
  - name: page
    in: query
    schema: { type: integer, minimum: 1, default: 1 }
  - name: per_page
    in: query
    schema: { type: integer, minimum: 1, maximum: 100, default: 20 }

Step 5: 逐端点设计详细规格

为每个端点设计完整的 OpenAPI 规格，逐领域输出，每完成一个领域暂停让用户 review：

每个端点必须包含：

• operationId：唯一标识符，用于代码生成
• summary：一句话描述
• description：标注来源时序图步骤（如 来源：S01 Step 2 → Step 3）
• requestBody：包含所有字段的 schema（含 required、类型、校验规则如 minLength/format）
• responses：覆盖正常响应 + 所有已知异常（从时序图的 EX 用例中提取）

示例：

paths:
  /api/auth/register:
    post:
      operationId: register
      summary: 用户注册
      description: "来源：S01 Step 2 → Step 3"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email: { type: string, format: email }
                password: { type: string, minLength: 8 }
      responses:
        '201':
          description: 注册成功，发送验证邮件
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId: { type: string, format: uuid }
                  message: { type: string }
        '409':
          description: "邮箱已被注册（EX-2.1）"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: 请求参数校验失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

Step 6: 验证追溯完整性

输出完成后，做一次追溯检查：

1. 正向检查：每个时序图中的跨系统箭头都有对应的 API 端点
2. 反向检查：每个 API 端点的 description 都标注了来源 Step
3. 异常覆盖：时序图中的每个 EX 用例都有对应的 HTTP 错误响应

如果发现遗漏，补充后再输出最终版本。

输出规范

• 文件格式：OpenAPI 3.1 YAML
• 存放位置：logos/resources/api/
• 按领域分文件：auth.yaml、projects.yaml、billing.yaml
• 每个文件包含完整的 openapi、info、paths、components 段
• 错误响应统一引用 $ref: '#/components/schemas/ErrorResponse'
• 每个端点的 description 必须标注来源时序图步骤

YAML 格式规则（必须遵守）

YAML 对空白和特殊字符敏感。AI 生成的 YAML 经常因为特殊字符未加引号而导致解析失败。必须严格遵守以下规则：

1. description 和 summary 的值必须用双引号包裹 — 任何包含 :、→、#、&、*、!、>、|、%、@、`、{、}、[、] 的字符串都必须用 "..." 包裹。

   # ❌ 错误 — 冒号和箭头导致 YAML 解析失败
   description: 来源：S05 Step 1 → Step 4.
   
   # ✅ 正确
   description: "来源：S05 Step 1 → Step 4."
   

2. 响应状态码 key 必须加引号 — 使用 '201' 而非 201，防止 YAML 将其解析为整数。
3. 生成后自检 — 每生成一个 YAML 文件后，重新审视是否存在未加引号的特殊字符。尤其注意引用场景步骤的 description 字段（它们总是包含 :）。
4. 拿不准就加引号 — 给安全字符串加引号无害，但漏掉危险字符串的引号会导致整个文件解析失败。

实践经验

• API 从时序图浮现：如果一个 API 在时序图中找不到出处，它大概率不应该存在。先画时序图再设计 API，而非反过来
• 路径命名：RESTful 风格，使用复数名词，/api/{resource}
• 版本前缀：初期不加版本前缀（/api/auth/register），需要版本管理时再加 /api/v2/
• 状态码语义：严格遵循 HTTP 状态码语义——200 成功、201 创建、400 参数错误、401 未认证、403 无权限、404 不存在、409 冲突、422 校验失败、500 服务错误
• 幂等设计：PUT/DELETE 操作必须幂等
• 敏感数据：响应中不包含密码、token 等敏感信息的明文
• 逐领域输出：不要一次输出所有端点——按领域分批输出，每批让用户 review 后再继续
• 字段命名一致：API 中的字段名要与后续 DB 设计中的列名保持一致（或有明确的映射规则），避免代码层出现不必要的字段转换

推荐提示词

以下提示词可以直接复制给 AI 使用：

• 帮我设计 API
• 基于时序图帮我生成 OpenAPI YAML
• 帮我设计 S01 相关的 API 规格
• 帮我把所有时序图中的跨系统调用提取为 API

⚠️ 收尾步骤（强制）：更新 resource_index

完成本 Skill 的所有 OpenAPI YAML 产出后，必须将新生成的文件追加写入 logos/logos-project.yaml 的 resource_index 字段：

resource_index:
  # ...已有条目...
  - path: logos/resources/api/<文件名>.yaml
    desc: <领域名称> API 规格（OpenAPI 3.x）。涉及 <相关端点> 的请求/响应结构、状态码、认证方式时必读。

不执行此步骤将导致后续 test-writer/code-implementor 无法感知 API 规格文件，AI 将无法基于正确的接口定义编写测试和代码。

S39 delta 模式：从 effective sequence 生成唯一 API delta

激活与前置

仅当 on-touch-v1 闭包矩阵判定 API/interface 适用时启用。必须先存在 effective scenario sequence；若没有时序来源，返回 AMBIGUOUS/前置缺失，禁止直接从用户一句话猜 OpenAPI。

当前 change-writer 拥有最终文件写入权；本 Skill 返回 API 内容、验证结论与 orchestration 影响，不得创建第二份“API 基线 delta”。

适用性

以下任一成立则 API 适用：HTTP、RPC、GraphQL、稳定 CLI/进程协议、消息 topic/event、webhook 或其它跨边界公开契约。纯进程内调用且无稳定外部协议可证据化 SKIP。

adopted 历史 skip_phases: [api] 不是永久禁用；与时序冲突时必须让 plan 暴露冲突。

MODIFY

• 读取主 API + 当前同目标 delta 的 effective view；
• 对已有 endpoint/schema 做兼容修改，对新 endpoint/schema 在同一文件增加；
• 保留未变更 endpoint/schema/operationId 与稳定 ID，遵守守恒/兼容策略；
• 多场景共享一个 OpenAPI 文件时聚合为一份最终态 delta。
• 对 .yaml|.yml|.json 目标，输出必须是整文件最终态而非片段，首行为 ## MODIFIED — <canonical target>（整文件替换）；其后 payload 是完整 OpenAPI。change-writer 不得再包一层 Markdown marker。

CREATE

目标缺失时返回完整可校验接口文档，至少含：

• OpenAPI/协议版本与 info；
• servers/channels（适用时）；
• paths/operations 或消息 channel；
• 唯一 operationId/message name；
• request/response/schema 与必填/约束；
• error/状态码；
• auth/permission；
• 幂等、分页、并发或重试中适用项；
• 版本兼容/弃用策略；
• 从 scenario 步骤到 operation 的追溯。

Markdown 外的 YAML/JSON delta 在剥离首行控制 marker 后必须是有效 OpenAPI；含冒号等特殊字符的文本按项目规范引用。禁止 TODO/空 paths/只有示例无 schema。

对 non-Markdown API target，完整输出格式固定：

## ADDED — logos/resources/api/<file>.yaml（新文件，整文件）
openapi: 3.1.0
...

• 首行声明 target 必须与 delta 路径映射结果一致；CREATE 只能用 ADDED，目标必须缺失。
• marker 不是 YAML 内容；merge/lint 在 parse 前剥离且仅剥离首行，最终 API 文件不得含 marker。
• .yaml/.yml 必须 duplicate-key fail-closed 解析，.json 必须 duplicate-key-aware 解析，并通过 OpenAPI 3.x schema/ref/operationId 校验与 CREATE 完整度检查。
• marker/路径/mode/存在性/语法/引用任一失败时返回 non_markdown_delta_invalid 或 create_target_incomplete，整批零落盘。协议权威定义见 merge-executor 的 non-Markdown 整文件章节。

输出给下游

同时返回：

• 受影响 operation 与 schema 清单；
• 每个 operation 对应的 scenario step；
• 需要 test-orchestrator 覆盖的主/异常链；
• 兼容/迁移风险。

API 适用即编排测试适用；change-writer 必须规划对应唯一 orchestration target，除非已有目标 MODIFY。

完成检查

• 全部 API 可追溯到 effective sequence；
• 目标模式与磁盘事实一致；
• 同 canonical target 只有一个输出；
• 语法验证与最低完整度均通过；
• 不读 seed staging，不写 verified/确认字段，不新增 JIT 流程。