validate-api

验收 — API

像真正的客户端那样测试正在运行的服务。单元测试依据代码自身的假设通过；这能验证线路行为——状态码、JSON 结构，以及重新加载后仍保留的副作用。

由 validate-feature 使用验收台账中的一组条目调用；也可以直接针对 API 变更运行，此时请先根据变更的验收标准（规范或涉及的端点）整理检查清单。无论哪种情况，都要按顺序逐项检查。

1. 启动服务——并记录启动方式

阅读 docs/agents/project.md，查找 Run locally (dev) 条目。如果存在，使用其中的命令启动后端。如果不存在：从代码库中查找启动命令（Cargo 可执行文件 / tauri / package.json 脚本 / Makefile），启动服务并确认它能响应（健康检查路由，或第一条检查清单请求返回任何响应），然后将启动命令和就绪信号写入 project.md 的 ## Run locally (dev) 标题下。完成条件：服务能响应请求，且启动命令已记录在 project.md 中。

前置条件——身份验证、数据、环境。 如果任何端点需要身份验证（令牌、预先填充的测试账户）、fixture/种子数据或环境配置（环境变量、测试数据库），请查明代码库如何提供这些内容，并将相关信息与启动命令一并记录在 project.md 中。如果验收运行因 401 或数据库为空而停滞，测试的是测试框架，而不是功能——请解决前置条件并注明，而不是将该条目标记为无法验证。

API 标准文档（可选）

适用范围： 检查清单条目为 HTTP/RPC API。加载： skills/project/define-system-doc/consult-recipe.md。路径： docs/standards/api.md。 如已批准则查阅；不存在则跳过；如果缺失会造成实质影响，则仅建议一次 /define-system-doc standards/api；切勿自动调用。

2. 将每条检查清单转化为真实请求

对于台账中的每个 API 条目，写出客户端发送的具体请求——方法、路径、标头、请求体——以及预期响应：状态码、请求体字段（名称、大小写、ID 类型）和任何副作用。明确涵盖边缘条件：字段为空/仅含空白字符 → 文档规定的错误；未知 ID → 文档规定的状态码；请求体格式错误；重复调用。

3. 针对运行中的服务进行测试

发送每个请求（使用 curl / http / 脚本），并断言完整预期，而不只是 2xx：状态码、请求体结构，以及——验收标准要求“持久化”时——通过新的 GET 请求读取数据；要求“重启后仍保留”时，重启服务后再次读取。对台账中的每一项记录实际结果与预期结果。完成条件：每个 API 条目都有实测结果。

4. 修复问题

必需的子技能：使用 root-cause——失败的请求已经构成可快速反馈的循环。修复根本原因，添加回归测试，然后重新运行该条目。

5. 转化为持久化测试

将已测试的请求转化为已提交的测试，测试需访问服务（或通过处理程序的实际接口），并按照 docs/agents/project.md 中的约定标注需求 ID，使其纳入验证套件，并在本次运行后持续保障该行为。完成条件：持久化测试已提交、已标注且通过。