# Codex Skills 教程：从 OpenAPI 规格生成可测试的本地 REST 客户端

## 身份和范围

本站原创 fixture 与人工参考；实际运行：真实 localhost HTTP 客户端与有限重试。目标代理模型、账号会话、付费 API、第三方 PR、推送和发布均未执行。公开包不含 .env；需要时仅在自己的临时练习目录从文本模板创建。

## 本地命令

```sh
python3 verify.py
```

## 七步原生操作

### 1. 先读普通业务接口合同

openapi.json 是 OpenAPI 3.1 的设备接口，/devices 分页返回 items/nextCursor，/devices/{id} 可返回 404。它不是模型 Chat/Responses 协议，servers 的端口 0 是等待本地 fixture 绑定临时端口的说明。

### 2. 安装项目级客户端技能

把 .agents/skills/devices-client/SKILL.md 放在独立项目中，核对 name/description 和读取规范、有限重试、先写 fixture 测试的说明。用 /skills 或显式 $devices-client 调用，不能仅把一段提示词起名叫技能。

### 3. 限定生成物与网络边界

要求生成 client.py 和本地测试，不添加外部域名或真实 key。技能会指导任务，不是 Codex 原生保证任意 SDK 正确的功能；依赖安装、代码运行和网络访问仍需单独检查。

### 4. 按游标分页并阻止重复游标

客户端累积两页 D01/D02/D03，在 nextCursor 为空时停止；保留 seen 集合防止同一 cursor 无限循环。不要只测试第一页就认定所有分页已合并。

### 5. 区分 404 与可重试 429

404 必须作为明确错误抛给调用者，不能伪造空成功。429 的最大重试次数固定为 2，即最多 3 次请求；检查 Retry-After 和永久限流，不能生成无上限 while True 重试。

### 6. 启动 localhost fixture 真正发请求

运行 python3 verify.py，临时端口上的 HTTP 服务返回两页数据、一次可恢复限流、永久限流及 404。result.json 的请求次数来自实际标准库 HTTP 请求，而非手填状态表。

### 7. 把实际生成客户端替换进同一测试

本站 client.py 是人工参考；你运行技能后，应把真正生成的代码放到新目录再跑同样 fixture。三条 ID、404、恢复性 429 和永久 429 次数全部符合后，才考虑连接自己的业务接口。

## 验收产物

项目 .agents/skills 中的客户端生成技能及参考规格；小型 REST 客户端、离线 fixture 测试和调用示例；明确上限与错误类型

## 门槛

- Codex skills 使用 .agents/skills 与 SKILL.md；技能并非原生保证生成任意 SDK 的内置产品功能。
- 仅使用本地假数据服务，不配置真实 API key；模型调用使用账号现有额度。
- 429 重试必须有次数上限且尊重响应约定，不生成无限重试逻辑。

## 官方来源

- https://learn.chatgpt.com/docs/build-skills

静态配图冻结于本次输入。修改输入需重新运行并自行重渲染；不把旧截图当新结果。