1. 为什么要把 Postman 的 API 能力塞进 Codex 的 Skill 体系很多人第一次听到给 Codex 做插件这个说法第一反应是Codex 不是写代码的智能体吗Postman 不是调接口的工具吗这俩凑一起能干嘛我一开始也这么想直到我在一个真实项目里被反复折磨——每次让智能体帮我联调一个后端接口它要么凭记忆瞎编请求体要么把鉴权头写错要么根本不知道我们内部 API 的字段约定。我手动在 Postman 里调通了把 curl 复制给它它才能勉强跑对一次。下次换个接口同样的流程再来一遍。这个痛点本质上是智能体有推理能力但没有接口事实。而 Postman 里恰好沉淀了最完整的接口事实——URL、方法、Header、鉴权方式、请求体 schema、示例响应、环境变量。把这些事实变成 Codex 能直接调用的 Skill智能体就不再是猜接口而是查接口。这里要先厘清一个概念避免后面混淆。所谓给 Codex 做插件在工程上通常有两种落地形态一种是把 Postman 的 Collection 导出成结构化描述注册成 Codex 的一个Skill技能让智能体在需要时按需加载另一种是写一个真正的插件/扩展在 Codex 的运行环境里挂一个本地服务实时把 Postman 的接口元数据喂给模型。前者轻、易维护、适合大多数团队后者重、实时性强、适合接口频繁变动的场景。这篇我主要讲第一种因为它复现成本最低也是我个人在团队里推得最顺的方案。关键词里出现了 Postman、Codex、插件、API、智能体这几个词它们其实构成了一条完整的链路Postman 是接口知识的源头API 是知识的载体插件/Skill 是知识的封装形式智能体是知识的消费者。理解这条链路比记住任何具体操作都重要。因为工具会变Postman 可能换成别的Codex 可能升级但这套把接口知识结构化后喂给智能体的思路是长期有效的。适合谁来读这篇三类人最有用一是天天和接口打交道、想让智能体帮忙联调的后端或全栈二是正在做智能体落地、苦于模型不知道内部系统长什么样的工程同学三是想理解 Skill 机制到底怎么设计的产品或技术负责人。不需要你精通 Postman 高级功能也不需要你懂模型微调只要你会导出 Collection、会写一点 JSON 或 Python就能跟着做下来。2. 拆解 Postman Collection 里到底藏着哪些可被智能体利用的信息2.1 Collection 的层级结构不是随便设计的Postman 的 Collection 看起来只是个文件夹树但它的层级其实天然对应了 API 的语义分组。一个典型的 Collection 长这样Collection 下面是 FolderFolder 下面是 RequestRequest 里包含 method、url、header、body、auth、tests、examples。这个结构不是装饰它直接决定了你后面怎么切分 Skill 的粒度。我的经验是Folder 对应一个业务域Request 对应一个具体能力。比如用户中心这个 Folder 下有登录获取用户信息更新头像三个 Request。当你把这个 Folder 转成一个 Skill 时智能体看到的就是用户中心这个能力包里面有三个可调用的动作。粒度太粗整个 Collection 一个 Skill智能体加载时上下文爆炸粒度太细一个 Request 一个 SkillSkill 数量失控、检索变慢。Folder 级别通常是最舒服的切分点。2.2 请求体 schema 才是真正的金矿很多人导出 Collection 只关注 URL 和方法这是巨大的浪费。真正让智能体会用接口的是请求体的字段结构。Postman 里如果你认真维护过 Request 的 Bodyraw JSON 或 form-data那里面就包含了字段名、类型、是否必填、示例值。这些信息转成 JSON Schema 或 TypeScript 类型后智能体就能自己构造合法请求而不是瞎编字段。我踩过的一个坑早期我导出的 Skill 只写了POST /api/user/login参数 username 和 password结果智能体经常把字段名写成 user_name 或 userName。后来我把完整的示例请求体塞进 Skill 描述里字段名错误率直接降到接近零。示例比描述更有约束力这是给智能体写 Skill 的一条铁律。2.3 环境变量与鉴权最容易被忽略的运行时信息Postman 的 Environment 里通常存着 base_url、token、app_key 这类变量。导出 Collection 时如果不处理URL 里会残留{{base_url}}这种占位符智能体看到会一脸懵。正确做法是在生成 Skill 时把变量替换成说明性文字比如把{{base_url}}/api/user转成{BASE_URL}/api/user并在 Skill 的说明里注明BASE_URL 由运行环境注入。鉴权同理。Postman 的 Auth 配置Bearer Token、API Key、OAuth2要显式写进 Skill告诉智能体调用前需要 Authorization 头。我见过太多 Skill 因为漏了鉴权说明导致智能体调一次失败一次最后被判定为这个接口不可用。鉴权不是细节是接口能否被调用的前提。2.4 示例响应让智能体学会解析返回值请求能发出去只是第一步智能体还得看懂返回。Postman 的 Examples 功能如果维护了里面就有真实的响应体样例。把这些样例放进 Skill智能体就能知道成功时返回 code0 和 data 字段失败时返回 code 非零和 message。这样它在多步任务里才能做条件判断比如如果登录返回 token 为空就重试。下面这张表是我总结的 Collection 字段与 Skill 用途的对应关系做转换时可以直接对照Collection 字段转换后的 Skill 内容对智能体的价值Folder 名称Skill 名称与描述决定技能检索命中率Request method url动作签名知道怎么发起调用Request body 示例参数 schema构造合法请求体Auth 配置鉴权说明避免 401/403Environment 变量占位符说明正确拼接 URLExamples 响应返回结构说明解析结果、做分支判断Tests 脚本业务规则备注理解成功/失败判定3. 从 Collection 到 Skill一条可复现的转换流水线3.1 第一步导出并清洗 Collection在 Postman 里选中目标 Collection右键 Export选 Collection v2.1 格式得到一个 JSON 文件。这个文件通常几百 KB 到几 MB直接丢给智能体是不行的必须清洗。清洗的目标有三个去掉和接口语义无关的字段比如 Postman 内部的_postman_id、protocolProfileBehavior、把环境变量占位符替换成可读说明、把每个 Request 的 body 示例提取出来。我一般写一个 Python 脚本做这件事核心逻辑就是递归遍历item数组遇到有request字段的节点就抽 method、url、header、body。这里有个细节url 在 v2.1 里可能是字符串也可能是{raw, host, path}对象两种都要处理。我第一版脚本只处理了字符串结果遇到对象格式的 URL 全丢了排查了半天才发现是格式差异。import json def clean_url(url): if isinstance(url, str): return url return url.get(raw, ) def extract_requests(items, folder): result [] for item in items: if item in item: # 是文件夹递归 result.extend(extract_requests(item[item], item.get(name, folder))) elif request in item: req item[request] body if isinstance(req.get(body), dict): body req[body].get(raw, ) result.append({ folder: folder, name: item.get(name, ), method: req.get(method, GET), url: clean_url(req.get(url, )), body: body, }) return result with open(collection.json, encodingutf-8) as f: data json.load(f) requests extract_requests(data.get(item, [])) print(f共提取 {len(requests)} 个接口)3.2 第二步按 Folder 聚合成 Skill 单元清洗完得到的是一个扁平的接口列表接下来按 folder 分组。每个 folder 生成一个 Skill 描述文件我习惯用 Markdown 加 YAML front matter 的格式因为这种格式智能体读起来最自然人也能直接看懂。front matter 里放 Skill 的名称、描述、触发条件正文里放接口清单。触发条件这一项特别关键它决定了智能体什么时候会想起用这个 Skill。写得太宽比如处理用户相关任务会频繁误触发写得太窄比如当用户明确要求调用 /api/user/login 时又几乎不会触发。我的经验是写成当任务涉及 XX 业务域的接口调用时把业务域说清楚让语义检索能命中。3.3 第三步给每个接口写人话说明这是最费时间但最值钱的一步。自动提取出来的接口信息是机器视角的智能体需要的是任务视角的。举个例子自动提取的结果是POST /api/order/create body: {sku_id: , count: 0, address_id: }我会手动补一句创建订单。调用前需确保用户已登录且地址已存在sku_id 来自商品详情接口返回。 这句话把接口放进了业务流程里智能体才知道调用顺序。接口之间的依赖关系是自动工具永远提取不出来的必须人工补。3.4 第四步注册到 Codex 并验证触发把生成的 Skill 文件放到 Codex 约定的技能目录下不同版本路径不同一般在配置里能看到 skills 或 plugins 目录。注册后不要急着上生产先做触发测试给智能体几个典型任务描述看它是否会加载正确的 Skill。我常用的测试集是帮我登录一下查一下订单状态给用户改个昵称分别对应三个不同 Skill看命中是否准确。如果命中不准八成是 Skill 的 description 写得不够有区分度。这时候不要改智能体改 Skill 描述。我调过最久的一次是因为两个 Skill 的描述都用了用户这个词导致检索混淆后来把其中一个改成账号凭证与登录态管理立刻就分开了。4. 让 Skill 真正被智能体用起来的三个关键设计4.1 描述要写什么时候用而不是这是什么这是我在多个项目里反复验证的一条。Skill 的 description 如果写成用户登录接口的封装智能体很难判断该不该用写成当需要获取访问令牌、验证账号密码、或处理登录态失效时使用命中率会高出一大截。原因是智能体的技能检索本质上是任务描述与技能描述的语义匹配任务描述里出现的是登录令牌鉴权这类词技能描述里就得有对应的词。我做过一个粗糙的对比测试同一批 20 个任务用是什么式描述正确触发 11 次改成什么时候用式描述后正确触发 18 次。差距非常明显。所以写 Skill 描述时先想用户在什么场景下会需要这个能力把那个场景的话写进去。4.2 参数说明要带约束不能只列字段名智能体构造请求时最容易犯的错是类型和格式。比如时间字段你只写create_time它可能传2024-01-01也可能传时间戳还可能传now。正确做法是在 Skill 里写清楚create_time: 字符串格式 YYYY-MM-DD HH:mm:ss必填。枚举字段更要把可选值列全比如status: 枚举可选 pending/paid/shipped/closed。我还会在 Skill 里加一条常见错误小节把历史上智能体踩过的坑写进去比如不要传 user_id服务端从 token 解析。这种负面清单的效果出奇地好因为智能体对不要做什么的遵循度往往高于要做什么。4.3 返回结构要给出成功与失败的判定依据智能体调用接口后需要判断这次调用是否成功才能决定下一步。如果 Skill 里只写返回订单信息它可能把任何返回都当成成功。我会明确写成功时 code0data 内含 order_id失败时 code 非 0message 为错误原因。有了这个智能体就能自己写重试逻辑或向用户报错。这里有个进阶技巧把幂等性写进 Skill。比如创建订单接口非幂等重复调用会产生多笔订单重试前需先查询。这条信息能避免智能体在超时后盲目重试造成脏数据。这类业务约束是区分能用和好用的分水岭。5. 实测中暴露的问题与我的处理方式5.1 上下文膨胀Skill 太多会把窗口撑爆一开始我很兴奋把公司所有 Collection 都转成了 Skill结果智能体响应变慢、还经常忘记前面的对话。排查后发现是技能索引太大每次检索都要扫描大量描述。解决办法是分层高频核心接口做成常驻 Skill低频接口做成按需加载的 Skill只在明确提到相关业务域时才加载。具体做法是在 Skill 描述里加一个priority字段核心的标 high边缘的标 low。检索时优先匹配 high命中不了再往下找。这个改动让平均响应时间从 8 秒降到 3 秒左右效果立竿见影。5.2 接口变更后 Skill 过期这是最隐蔽的坑。后端改了字段名Postman 里更新了但 Skill 文件还是旧的智能体照着旧 Skill 调用报错还找不到原因。我的处理方式是把 Skill 生成脚本接入 CI每次 Collection 有更新自动重新生成 Skill 并跑一遍触发测试测试不过就阻断合并。如果团队没有 CI 条件至少做个定时任务每天拉一次 Collection 重新生成。我见过有团队因为 Skill 过期智能体连续一周调用失败最后被业务方投诉这个智能体根本不能用。Skill 的时效性维护比 Skill 的初次生成更重要。5.3 敏感信息泄漏风险Postman 的 Environment 里经常有真实的 token、密钥。导出和转换时如果不小心这些会直接进 Skill 文件进而可能被智能体在输出里带出来。我的原则是Skill 里只放占位符绝不放真实凭证。所有密钥通过运行环境的变量注入Skill 里写{API_TOKEN}并注明来源。另外示例响应里如果有真实用户手机号、身份证号也要脱敏后再放进 Skill。这一步不能省我见过因为示例数据没脱敏导致的信息暴露事故代价很大。5.4 智能体过度自信地调用有时候智能体明明没有对应 Skill却硬要用一个相似的接口去凑结果调用失败还编造理由。这是模型的行为特性不是 Skill 的问题。我的应对是在 Skill 描述里加一句若当前任务不匹配本技能的业务域请明确告知用户该能力暂不支持不要尝试用其他接口替代。这句话能显著降低乱调用率。6. 几个能直接抄的 Skill 模板与配置片段6.1 单个业务域的 Skill 模板下面这个模板我用了大半年改改就能用。front matter 里的字段按你所用 Codex 版本的规范调整正文结构基本通用。--- name: user-center description: 当任务涉及账号登录、获取用户资料、修改用户信息、处理登录态时使用 priority: high --- ## 能力概述 本技能封装用户中心的接口覆盖登录、查询、更新三类操作。 ## 接口清单 ### 登录 - 方法: POST - 路径: {BASE_URL}/api/user/login - 鉴权: 无需 - 请求体: - username: 字符串必填 - password: 字符串必填明文传输由网关加密 - 成功判定: code0data.token 非空 - 失败判定: code 非 0message 为原因 - 注意: 非幂等失败重试前无需查询 ### 获取用户信息 - 方法: GET - 路径: {BASE_URL}/api/user/profile - 鉴权: 需要 Authorization: Bearer {TOKEN} - 成功判定: code0data 含 nickname、avatar - 注意: token 失效返回 401需重新登录 ## 常见错误 - 不要传 user_id服务端从 token 解析 - 时间字段格式为 YYYY-MM-DD HH:mm:ss6.2 批量生成脚本的关键片段如果你有几十个 Folder手写不现实。我在清洗脚本后面接了一段模板渲染用 Jinja2 把每个 folder 渲染成上面的模板接口部分自动填充人工只补注意和常见错误。from jinja2 import Template SKILL_TEMPLATE Template(--- name: {{ folder_slug }} description: 当任务涉及{{ folder_name }}相关接口调用时使用 priority: {{ priority }} --- ## 接口清单 {% for r in requests %} ### {{ r.name }} - 方法: {{ r.method }} - 路径: {{ r.url }} - 请求体: {{ r.body or 无 }} {% endfor %} ) for folder, reqs in grouped.items(): content SKILL_TEMPLATE.render( folder_slugslugify(folder), folder_namefolder, priorityhigh if len(reqs) 5 else low, requestsreqs, ) with open(fskills/{slugify(folder)}.md, w, encodingutf-8) as f: f.write(content)6.3 触发测试的最小用例集生成完别急着用跑一遍这个测试集。每个用例是一句任务描述加期望命中的 Skill 名人工核对或写个简单脚本比对。任务描述期望命中 Skill帮我登录一下系统user-center查一下这个订单现在什么状态order-query把用户的昵称改成小明user-center创建一个新订单商品是 Aorder-create今天天气怎么样无不应命中任何接口 Skill最后一行是负样本专门测误触发。很多人只测正样本结果智能体见谁都调接口反而更糟。7. 我对这套方案边界的几点真实体会这套方案不是万能的用之前得清楚它的边界。它适合接口相对稳定、有 Postman 维护习惯的团队。如果你们接口天天变、Postman 里全是过期的测试数据那先治理 Collection 比做 Skill 更紧迫。我见过有团队跳过治理直接做 Skill结果智能体学了一堆错误接口越用越乱。另外Skill 解决的是接口事实问题解决不了业务逻辑问题。比如下单前要校验库存、扣减积分、发通知这种跨接口的编排Skill 只能提供单个接口的能力编排逻辑还得靠智能体的推理或者你额外写的工作流。别指望一个 Skill 就能让智能体变成全自动业务系统。我在实际使用中最大的收获其实是倒逼团队把接口文档写规范了。因为要转成 Skill字段类型、必填项、错误码这些必须写清楚写不清楚智能体就用不对。这个过程反过来提升了 Postman Collection 的质量算是意外之喜。如果你正在推接口规范化但推不动不妨用我们要做智能体接入这个理由试试往往比为了文档规范更有说服力。最后一个实用建议先做一个业务域跑通闭环再铺开。我第一版一口气做了十几个 Skill结果问题一堆、排查困难。后来收缩到一个用户中心把生成、注册、触发、维护整条链路跑顺再复制到其他域效率高得多。智能体接入这件事慢就是快。