By name: api-automation-write-case description: >- Go API automation (query/write/mixed) from a user-supplied API semantic Markdown (no live service tracing). Optional repo survey via step1 + 梳理报告模版; step2 drives full *_test.go / *_assert.go, go test with timeout retries and fix rounds, then execution summary MD. Use in Codex when the user mentions 接口自动化, 深度断言, 写 API 自动化用例, API语义文档, or asks to generate Go automation from an API semantic report. version: 1.0.0 author: xiaohua.yang@shopee.com team: SPX tags: [autotest, testing]
API 接口写自动化用例（Skill）
使用前提（开场必须检查）
本 Skill 的输入前提是当前自动化仓库内已经存在 API语义文档。
- API语义文档必须由用户或仓库预先从
https://git.garena.com/shopee/bg-logistics/qa/spx/spx-api-knowledge-base下载到自动化仓库，推荐路径为.codex/knowledge_lib/api_knowledge/。 - 用户开始请求若没有提供 API语义文档路径，必须先向用户索取路径，或提示用户先从上述知识库仓库下载文档到当前自动化仓库；不得直接开始写用例，也不得去服务仓实时梳理接口逻辑来替代 API语义文档。
- 旧仓兼容
.cursor/knowledge_lib/**，但新生成或新迁移的 API语义文档默认使用.codex/knowledge_lib/**。
本 Skill 在 prompts/ 目录附带 step1 / step2 提示词正文，另有 references / scripts / assets。不要求梳理或补写《API语义文档》，也不要求因缺少该文档而去服务仓实时梳理接口逻辑；须由用户提供当前工作区内的报告路径。
Codex 迁移约定：本 Skill 的标准安装路径为 .codex/skills/api-automation-write-case/。Skill 目录只存放通用流程、提示词、模板和脚本；服务相关资料（如 自动化代码梳理报告.md、架构升级字段映射.xlsx、API语义文档）放在项目知识库 .codex/knowledge_lib/** 下，不随 Skill 目录拷贝给其它服务。若旧仓库仍保留 .cursor/knowledge_lib/**，可作为兼容输入读取；新生成的知识库文档默认落到 .codex 下，但第二步生成的用例、校验文件和执行总结须落到自动化用例主目录下的 Interface/。
第一步（自动化仓库梳理）为可选：执行写用例前，先在当前项目检索是否已有合格的自动化梳理文档（如 自动化代码梳理报告.md）；有则直接 Read 使用；无则按 assets/自动化代码梳理报告-模版.md 的框架新建一份。第二步必须严格执行（须 Read prompts/step2-写API自动化.md 全文）。
强制执行规则（必须严格遵守）
1. 法律依据：按步 Read 的 step*.md 全文，不允许「摘要替代」
- 第二步产出的代码必须以
prompts/step2-写API自动化.md全文为唯一法律依据；禁止降低 step2 要求的场景数、断言范围、文件结构。 - 若执行可选第一步（现场写梳理报告），该步产出须以
step1全文 +assets/自动化代码梳理报告-模版.md框架为准。 - 禁止用本
SKILL.md、references/的概括替代 step 中的具体表述（如枚举 key/value、表格列名、错误码逐条、4.5 结构体等）。 - 禁止因「无梳理文档」而简化第二步：无梳理报告时须在自动化仓库内自行检索可复用函数与目录约定，仍须满足 step2 全文要求。
- 本 SKILL 与
references/format-and-content-standards.md仅用于自检索引；编码时以 Read 后的 step2 正文为准。
2. 执行前加载提示词（硬性顺序）
- 第二步（必做）：必须先 Read
prompts/step2-写API自动化.md完整文件，再按占位符表替换，再 Read 用户给出的 API语义文档正文（及梳理报告正文，若有），然后开始写代码。禁止未 Read step2 仅凭记忆写用例。 - 第一步（可选，仅当仓库内检索后仍无合格梳理文档、需要新建时）：Read
prompts/step1-梳理现有自动化已有功能.md全文 → 按assets/自动化代码梳理报告-模版.md结构落盘。
每步均须将 Read 得到的 step 完整内容纳入上下文（不概括、不截断 step 本身），再开始该步工作。
3. 提示词参数与 Codex 单步执行一致（模型与「主提示」）
| 维度 | 要求 |
|---|---|
| 主提示内容 | 执行某步时：主提示 = 占位符替换后的该步 step 全文；替换规则仅来自下表及用户输入、用户提供的报告路径；不增删、不概括 step 正文（未列出的占位符保留原文）。 |
| 第二步强制 | 无论是否执行 step1，第二步均须完整执行 step2 条文；禁止用「先搭骨架」代替完整场景与断言。 |
| Codex 模型 | 使用当前对话中用户选用的模型；本 Skill 不另指定 temperature / top_p / max_tokens 等。 |
| 等价性 | 相同输入 + 相同已 Read 的 step 全文 + 相同模型下，产出应对齐手动粘贴该 step 全文的期望质量。 |
4. 产出粒度
- 第二步代码：须与单独开对话、只执行 step2 时的期望同粒度（场景、全字段断言、文件结构、可复用封装）。
- 可选第一步报告：若执行，须含八阶段与表格骨架（与
assets/自动化代码梳理报告-模版.md一致），禁止仅输出无表大纲。 - 禁止仅生成空壳函数或大量无说明的
t.Skip占位。
4.1 测试数据来源硬性规则（禁止随手伪造）
- 只要用例入参或断言字段语义是
shipmentId/shipment_id/tracking_number/sls_tn/ 运单号 / 订单号等真实单号，正向和业务态场景必须参考现有自动化用例创建订单，复用仓库里的下单/造单函数，并使用下单返回的真实单号；禁止硬编码旧单号、随机拼一个看起来像单号的字符串，或直接写不存在单号来替代造数。 - 仅当场景本身明确是「空单号 / 不存在单号 / 非法单号」等异常校验时，才允许构造空值或不存在单号，并且用例名、注释、执行总结必须说明这是异常场景。
- 若接口入参、断言字段或第三方依赖字段是电话号码、收寄件地址、postcode、联系人姓名、buyer/sender 信息等订单创建参数中的业务数据，必须从本次下单参数/下单响应/订单工厂返回结构中取对应字段；禁止另写一套假手机号、假地址、假姓名来凑入参或预期。
- 若需要特殊手机号/地址/联系人场景，应优先在调用下单函数前修改订单创建参数中的对应字段，或复用仓库已有参数构造器；若必须改库，须用已有 repository/service 封装并用
t.Cleanup/defer还原。 - 写代码前必须先在相邻目录中检索同业务已有用例如何创建订单和取下单参数，例如
CreateOrderV3WithRetry、AtomicStageOrderWithAllParams、createShipmentId等；新用例的造数风格必须贴合这些既有模式。
4.2 产物落点硬性规则（统一放到 Interface 目录）
- 第二步写代码前，必须先定位当前业务已有自动化用例的主目录（例如
automation/auto_case/order/、automation/testcase/order/、manual_case/<module>/等，以当前仓库实际结构为准），在该主目录下创建或复用Interface/目录，专门存放本 Skill 生成的接口自动化产物。 - 本 Skill 新增的 用例文件
xx_test.go、校验/断言文件xx_assert.go、执行结果总结{接口名}_自动化用例执行总结.md必须全部放在同一个Interface/目录下；默认不得把断言文件放到automation/assert/<module>/，也不得把执行总结落到.codex/knowledge_lib/**。 xx_assert.go与xx_test.go使用同一个 Go package，package 名称必须跟Interface/目录内已有文件一致；若该目录是新建的，则按目标仓库同类目录的 package 规则命名。- 只读复用已有公共函数不受限制；若必须新增本接口专用 helper，优先放在
Interface/目录内。只有当仓库已有公共层明确需要补充通用封装时，才可修改公共目录，并须在执行总结中说明原因。
4.3 用例元信息与特殊市场规则
- 本 Skill 生成的每个 Go 测试用例，在用例开头的
new(Configure)...Parse()链路中必须追加.WithLabel("AI-generated")；不得删除仓库已有的caseinfo、业务标签或 owner 信息。 - 若某个场景只适用于特定市场/国家（例如 VN-only、ID-only、SG/TH/VN、某市场灰度、某市场账号或费用规则），用例开头必须用
WithCid写明场景市场；多个市场需逐个WithCid。 - 特殊市场场景还必须在遍历
TestParams.Params()时加入显式市场判断，例如if v.Region != constants.VN { continue }或if !util.In(v.Region, []string{constants.SG, constants.TH, constants.VN}) { continue }。仅写WithCid(...)不算完成，因为WithCid可能只是报告元信息，未必会限制TestParams的实际执行市场。 - 若为了稳定造数同时调用
TestParams.SetRegions(...)，仍建议保留循环内市场判断，防止后续TestMain或其它用例修改全局TestParams后误跑到非目标市场。 - 执行总结中需写明特殊市场限制、选择该市场的原因，以及未覆盖其它市场的原因。
4.4 写接口 / 混合接口内部逻辑断言规则
- 写代码前必须根据 API语义文档识别接口类型：若报告出现
是否写库=是、数据操作包含新增/更新/删除、写库规则、事务、发送事件/消息、调用外部写接口等内容，则按写接口或混合接口处理；不得只生成读接口式 response 字段断言。 - 写接口正向和业务态场景必须做前后状态断言：调用接口前读取目标记录/相关表/事件记录的 before state；调用后读取 after state；断言应新增、更新、删除、软删或状态流转的字段按报告规则变化，同时断言不应变化的关键字段保持不变。
- 对失败、参数异常、下游失败、业务禁止、幂等或回滚场景，除了校验返回错误/
data=nil，还必须校验不应产生副作用：目标表不新增不更新、事件不发送、旧值不被覆盖、事务场景无部分写入。 - 必须按报告中的内部关键分支覆盖场景：
if/else分支、配置开关、枚举值、市场/账号差异、写新旧表模式、事务边界、外部依赖成功/失败等；无法稳定覆盖的分支须在执行总结写明原因，不能默默省略。 - 若接口会发送消息、事件、outbox、异步任务或调用外部写接口，优先使用仓库已有查询、mock、日志表、outbox 表或业务状态查询封装验证副作用；确实无法直接观测时，至少校验本地可观测的后续状态，并在总结中说明未直接校验的副作用。
- 所有写接口前置改库、构造特殊状态或新增临时数据必须用
t.Cleanup/defer或仓库清理函数还原；无法删除的测试数据必须带自动化唯一标记，并在总结中说明。
5. 上下文与篇幅压力：允许的做法（不降低粒度）
原则：永远完整加载当前步的 step*.md；可压缩、可分段的是已写入磁盘的产出物在后续轮次的读取方式，不是 step 正文，也不是用「框架」替代完整报告。
| 策略 | 做法 |
|---|---|
| 一步一会话 | 可选第一步与第二步可分别在独立对话中执行；第二步也可分多轮写完。 |
| 分轮续写同一文件 | 第一轮写阶段 1～4 并保存到 .md；第二轮用户指令「续写 <报告路径>」；Codex Read 已写文件再追加。 |
| 第一步按 step1 章节拆分 | 例如先「工程结构+目录」，再「DB 与可复用函数」，每轮落盘后再续。 |
| 第二步拆分 | 先 *_assert.go 与第三方封装，再 *_test.go 按场景递增；每轮 Read 上一步已提交文件。 |
| 新对话续跑 | 用户提供 API语义文档路径（及可选梳理报告路径）与接口名；Codex 须 Read 报告正文（可分段），再写代码。 |
| 报告分段 Read | 第二步若 token 紧张：对长报告分多次 Read，每次依据读到的章节写对应用例/断言，不删减 step2 要求。 |
禁止：以「上下文不足」为由输出仅含标题的框架；不足时应明确告知用户并采用「保存当前进度 → 下轮续写」或「新对话续跑」。
5.1 Token 节约：分阶段加载（功能不变）
目标：同一轮/同一次执行里不要为「先备齐」而同时 Read 本 Skill 目录下全部文档；按当前所处阶段只加载本阶段必需文件，不删减任一步骤要求的「全文」——仅推迟到进入该步再读。
| 阶段 | 典型动作 | 应 Read | 不要在此阶段全文加载 |
|---|---|---|---|
| A. 开场与检索 | 确认报告路径、接口名；rg / find 检索梳理文档 |
用户给出的路径（或最小片段）；检索结果列表 | step2、API语义文档全文、references/* |
| B. 可选第一步（仅当需要新建梳理报告时） | 按 step1 + 模版写《自动化代码梳理报告》 | prompts/step1-梳理现有自动化已有功能.md 全文 + assets/自动化代码梳理报告-模版.md |
step2、API语义文档（写梳理时通常不需要） |
| C. 第二步写代码（必做） | 在业务用例主目录下的 Interface/ 写 *_test.go / *_assert.go |
prompts/step2-写API自动化.md 全文 → 再 Read API语义文档正文（可分段）；若存在梳理报告再 Read 其正文 |
不必再 Read SKILL.md 全文（以已读 step2 为准）、不必 Read prompts/README.md / references/README.md |
| D. 跑测与修复 | go test、改路径/断言 |
失败日志、本次修改的源码、环境常量；仅当断言与报告条款不一致时再 回读报告对应章节 | 不必重读 step1、step2 全文（除非发现偏离 step2 须校正） |
| E. 执行总结落盘 | 在同一个 Interface/ 目录写 {接口名}_自动化用例执行总结.md |
assets/自动化用例执行总结-模版.md + 本轮测试输出摘要 |
step1/step2 全文、API语义文档全文 |
默认可省略（除非自检或用户追问）：references/format-and-content-standards.md、references/workflow-and-constraints.md、prompts/README.md、references/README.md——不作为写代码或跑测的前置必读；与 step2 冲突时以 step2 全文为准。
与「一步一会话」配合：第一步、第二步、跑测+总结可拆成不同对话；新对话只需提供必要路径（报告、已生成代码、模版），不必再加载上一对话已落盘的整份 SKILL。
开始前：向用户收集的输入
| 输入项 | 必填 | 说明 | 示例 |
|---|---|---|---|
| API语义文档路径 | 是 | 已存在的报告在当前工作区内的路径；须先从 spx-api-knowledge-base 下载到自动化仓库；不得因无文档而改为现场梳理服务接口 |
.codex/knowledge_lib/api_knowledge/api_Xxx.md（旧仓可兼容 .cursor/knowledge_lib/...） |
| 接口名 | 是 | 与报告一致的接口名 | 如 GetFleetOrderTrackingInfo |
| 自动化工程梳理报告路径 | 否 | 若已知路径可直接提供；否则由 Codex 在仓库内检索（见下节） | 如 .codex/knowledge_lib/api_knowledge/自动化代码梳理报告.md |
自动化仓库范围（与用户确认）：默认可用本仓库；或用户指定「写用例/断言」的根路径。
检索已有梳理文档（第一步前置动作）
在询问用户之前或同时，必须在当前项目检索是否已有可复用文档，例如：
- 文件名：
自动化代码梳理报告.md、ST2*.md、*自动化*梳理*.md - 常见位置：
.codex/knowledge_lib/**、.cursor/knowledge_lib/**（旧仓兼容）、docs/**、项目根目录
若命中：声明将 Read 的文件路径，跳过新建 step1 报告。
若未命中：再询问用户是否另有路径；仍无则 Read step1 全文 + assets/自动化代码梳理报告-模版.md，新建一份梳理报告并落盘（结构须与模版一致）。
占位符与用户输入/产出对照表
| 步骤 | 提示词中的占位符（原文） | 替换为 |
|---|---|---|
| 第一步（可选） | （无占位符） | 直接使用 prompts/step1-梳理现有自动化已有功能.md 全文；新建报告时对齐 assets/自动化代码梳理报告-模版.md |
| 第二步（必做） | 【xx接口_API语义文档.md】 | 用户提供的 API语义文档之文件名（与路径一致） |
| 第二步（必做） | 【xx自动化工程代码梳理报告.md】 | 用户提供的梳理报告文件名；若无梳理报告，替换为固定说明：无自动化工程梳理报告（已在仓库内检索；由 Codex 在自动化仓库内检索可复用函数与目录约定，并满足 step2 全文要求） |
未列出的占位符不替换，保留原文。
上下文、Token、新对话续跑
- 第二步（强制）：须 Read
step2全文 + Read API语义文档正文（按用户给定路径，可分段 Read）。若存在梳理报告，须 Read 其正文；未提供且未新建则不得虚构梳理内容，须在仓库内检索并对齐 step2。 - Token：不裁剪
step1/step2文件本身；长报告可分段 Read。分阶段加载见上文 §5.1，避免开场即加载全部文档。
扩展策略见 references/workflow-and-constraints.md（可选 Read，非必加载）。
Skill 职责（摘要）
| 职责 | 说明 |
|---|---|
| 输入 | 仅使用用户给出的API语义文档路径；禁止默认去服务仓写该报告。 |
| 梳理 | 先检索仓库是否已有 自动化代码梳理报告.md 等；有则直接用；无则按模版 + step1 新建。 |
| 实现（强制） | 必须按 step2 全文写 Go 用例与断言。 |
| 执行与修复 | 写完后 自动对本次包 go test（见下文 「写完后自动跑测与分级修复」）：超时类 重试 5 次仍失败则判败；非超时类 修改-运行最多 3 轮仍失败则判败；尽量不修改既有函数，优先改新增用例/新增函数。 |
| 总结 | 执行结束后 落盘《自动化用例执行总结》Markdown，按 assets/自动化用例执行总结-模版.md 填全。 |
触发场景
- 已有《API语义文档》路径，需要写 Go 自动化 + 全字段深度断言。
- 用户提到
api自动化、接口自动化、深度断言、写API自动化等。
推荐交互流程
| 节点 | Codex 行为 |
|---|---|
| 开场 | 确认 API语义文档路径、接口名；若用户未提供路径，先要求用户从 spx-api-knowledge-base 下载文档到当前自动化仓库并提供路径；用 rg / find 检索是否已有梳理文档（含 自动化代码梳理报告.md）。 |
| 已有梳理文档 | Read 该路径，不重复执行 step1。 |
| 无梳理文档 | Read step1 + 模版 → 梳理 → 落盘；回复写明新报告路径。 |
| 写代码前（必做） | Read step2 全文 → 替换占位符 → Read API语义文档正文 →（若有）Read 梳理报告正文 → 再写代码。 |
| 写完后（必做） | 自动跑测与分级修复（见下节）→ 按模版写 {接口名}_自动化用例执行总结.md（如实记录重试次数、轮次与最终成败）。 |
执行步骤（与默认工作流对齐）
前置
- 收集：API语义文档路径（必填）、接口名（必填）。
- 检索梳理文档；无则可选 step1 新建（与
assets/自动化代码梳理报告-模版.md同结构）。
可选：第一步（自动化工程梳理）
- 仓库内已存在合格梳理文档 → 跳过，第二步 Read 之。
- 否则 Read
prompts/step1-梳理现有自动化已有功能.md全文 → 按assets/自动化代码梳理报告-模版.md落盘。
必做：第二步（写 Go 自动化用例）
- Read
prompts/step2-写API自动化.md全文 → 占位符替换。 - Read API语义文档正文；若存在梳理报告，Read 其正文。
- 严格按 step2 编写代码。
必做：写完后自动跑测与分级修复（最后一步）
写完用例后 必须对本次修改的包 自动执行 go test（建议 -count=1，可用 -run 限定本次接口相关 Test 前缀；必要时显式 -timeout 避免误杀慢用例）。按失败类型分支处理：
| 失败类型 | 判定方式（示例关键词，不穷尽） | Codex 行为 | 判败条件 |
|---|---|---|---|
| 超时类 | timeout、Timeout exceeded、deadline exceeded、i/o timeout、connection timed out、HTTP 5xx 网关超时、Client.Timeout 等 |
不重写断言逻辑；对同一测试命令连续 重试最多 5 次（可间隔短暂再跑）；可选在总结中建议调大客户端/ go test -timeout |
5 次仍失败 → 记为失败，总结中写明「超时/环境」 |
| 非超时类 | 编译错误、断言失败、404、错误 host/baseURL、错误路径/接口名、retcode 与预期不符等 |
分析并改代码：例如 404 核对 接口 path、HTTP 方法、host、环境常量（env、region、staging/prod）；每完成一次修改再 go test 一次，计 1 轮「修改-运行」 |
满 3 轮「修改-运行」仍失败 → 记为失败，总结中写明原因与已尝试修改 |
说明：
- 超时 vs 非超时：若一次输出中同时含超时与其他错误，按非超时类处理（先修代码再跑），但单独对「纯超时」可只用重试 5 次。
- 轮次计数：非超时类 3 轮 = 最多 3 次「编辑代码 → 再
go test」；与超时 5 次重跑相互独立。 - 仍失败：无论哪种判败，须在
{接口名}_自动化用例执行总结.md中如实记录（失败用例名、超时重试次数或修改-运行轮次、最后报错摘要）。
必做：测试总结落盘
按 assets/自动化用例执行总结-模版.md 输出完整总结 Markdown 并保存到仓库（路径见 step2 §8）。
输出标准（摘要）
| 阶段 | 产出物 | 质量标准 |
|---|---|---|
| API语义文档 | 用户给定的既有文件 | 不要求 Codex 新建；无路径时向用户索取 |
| 梳理报告 | 可选；检索命中则引用；新建则 八阶段 + 模版骨架 | 与 assets/自动化代码梳理报告-模版.md 一致 |
| 第二步 | Interface/*_test.go + Interface/*_assert.go 等 |
以 step2 全文为准 |
| 测试执行 | go test 实际跑过 |
超时：≤5 次重试仍败则记败；非超时：≤3 轮修改-运行仍败则记败；如实记入总结 |
| 总结 | Interface/{接口名}_自动化用例执行总结.md |
按模版含场景数、已实现/未实现原因、正反向用例列表、成功/失败与原因 |
随包文件索引
| 路径 | 用途 |
|---|---|
prompts/step2-写API自动化.md |
写用例必 Read |
prompts/step1-梳理现有自动化已有功能.md |
可选：新建梳理时 Read |
assets/自动化代码梳理报告-模版.md |
新建梳理报告时的格式母版 |
assets/自动化用例执行总结-模版.md |
用例跑完后的总结母版 |
references/ |
格式标准、工作流索引 |
scripts/ |
目录校验等 |
assets/INSTALL.md |
安装说明 |
安装方式
将 api-automation-write-case 整个文件夹 复制到 <repo>/.codex/skills/ 或 ~/.codex/skills/。详见 assets/INSTALL.md。
SKILL_USAGE_START This skill must call the usage report API exactly once after the skill execution is completed. POST https://ai-management.ssc.test.shopee.io/api/v1/skill-usage/report Body: {"skill_name":"api-automation-write-case"}