Postman Collection 转 Codex Skill：让智能体直接调用 API 资产

1. 为什么要把 Postman 的 API 能力塞进 Codex1.1 一个真实痛点接口调试和智能体开发是割裂的我平时的工作流大概是这样接口调试在 Postman 里做环境变量、鉴权、断言脚本、Mock 服务全在那边而写代码、让智能体帮忙补全逻辑、生成调用代码又切到 Codex 这类 AI 编程助手这边。两边来回倒腾最烦的不是切换窗口而是上下文丢失——Postman 里刚调通的那个请求参数结构、返回字段、错误码我得手动复制粘贴给 Codex它才能理解我要干什么。时间一长我就想能不能让 Codex 直接“看见”我在 Postman 里积累的 API 资产换句话说把 Postman 的 Collection、环境变量、请求示例变成 Codex 可以调用的一个 Skill技能。这样我在写代码时直接说“帮我按订单服务的接口规范生成一个重试封装”Codex 就能自己去查我 Postman 里的接口定义而不是我一句句喂给它。这个想法落地之后效果比我预想的好。核心逻辑其实不复杂Postman 本身有完整的 API 来描述你的接口资产Codex 这类智能体框架又支持通过 Skill 扩展能力中间缺的就是一个“翻译层”。把 Postman 的 Collection 转成智能体可读的结构化描述再包装成一个 Skill 注册进去整条链路就通了。1.2 这个方案适合谁解决什么问题先说清楚适用人群免得你看到一半发现不是自己需要的后端和全栈开发者手里有一堆 Postman Collection想让 AI 助手直接基于这些接口定义生成调用代码、测试用例、文档。智能体应用开发者正在用 Codex 或类似框架搭智能体需要给它接入外部 API 能力但不想每个接口都手写一遍工具描述。API 平台维护者团队内部有统一的接口规范希望智能体在生成代码时自动遵循这些规范减少“AI 瞎编字段名”的情况。它解决的核心问题是API 资产复用。你花时间在 Postman 里维护的接口定义不应该只用于手动点“Send”。把它变成 Skill 之后智能体在需要调用某个接口时能拿到准确的 URL、方法、请求头、请求体结构、返回示例甚至能根据你写的测试脚本推断出边界条件。这比让 AI 凭空猜要靠谱得多。注意这里说的“插件”不是指 Postman 官方插件市场里的东西而是指你为 Codex 这类智能体框架开发的一个 Skill 扩展。叫法不同本质一样——都是给智能体加一个可调用的能力单元。1.3 整体思路一句话概括用一句话说清楚我要做的事读取 Postman Collection 的 JSON 导出文件解析出接口的元数据按照智能体 Skill 的规范生成描述文件注册到 Codex 中让智能体在需要时能查询和调用这些 API。听起来简单但中间有几个坑Collection 的 JSON 结构在不同版本间有差异环境变量怎么处理鉴权信息不能明文塞进去Skill 的描述要足够清晰否则智能体不知道该在什么时候调用它。这些细节后面会一个个拆。2. 核心细节拆解Postman Collection 里到底有什么可用2.1 Collection JSON 的结构速览Postman 导出的 Collection 是一个 JSON 文件顶层大概长这样{ info: { name: 订单服务, schema: https://schema.getpostman.com/json/collection/v2.1.0/collection.json }, item: [ { name: 创建订单, request: { method: POST, header: [...], body: {...}, url: {...} }, response: [...] } ], variable: [...] }关键字段就几个info.name是集合名item是接口列表可以嵌套文件夹每个 item 里的request是请求定义response是保存的响应示例。variable是集合级别的变量。我实际解析的时候发现不同人导出的 Collection 规范程度差别巨大。有的人每个接口都有完整的 response 示例和测试脚本有的人只有 URL 和方法。所以解析逻辑要能容错缺字段就跳过不能因为一个接口不完整就整个失败。2.2 哪些字段对智能体最有价值不是所有字段都值得传给智能体。我筛选了一遍按价值排序字段价值说明request.method高决定调用方式必须保留request.url.raw高完整 URL但要注意变量替换request.header高鉴权、Content-Type 等关键信息request.body高请求体结构智能体生成代码的核心依据response示例中高让智能体知道返回结构便于生成解析代码request.description中接口说明帮助智能体判断何时调用event测试脚本中能推断出断言逻辑但不是所有接口都有variable中环境相关需要单独处理我的做法是把 method、url、header、body、response 示例、description 这六项提取出来组装成一个结构化的接口描述。其他字段先忽略避免信息过载。2.3 环境变量和鉴权信息的处理原则这是最容易出安全问题的地方。Postman 里经常有{{base_url}}、{{token}}这样的变量直接导出会把变量名带出来但值在环境文件里。我的处理原则是变量名保留值不写入 Skill 描述。比如 URL 里保留{{base_url}}在 Skill 的说明里告诉智能体“base_url 需要从环境配置读取”。鉴权头只保留键名不保留值。比如Authorization: Bearer {{token}}只写键和变量占位绝不把真实 token 写进去。敏感字段做标记。如果某个 header 或 body 字段名字里带password、secret、key在描述里标注“敏感字段运行时注入”。实操心得我一开始图省事直接把导出的 JSON 整个塞给智能体结果它有时候会把示例里的假 token 当成真的用。后来改成只传结构不传值问题就没了。这个坑值得你提前避开。2.4 为什么选择“生成描述文件”而不是“实时查询”有两种实现路径一是每次智能体需要时实时去读 Postman 的 APIPostman 有 API 可以拉 Collection二是提前把 Collection 转成静态描述文件注册进 Skill。我选了后者理由有三稳定性不依赖 Postman 服务在线也不受网络波动影响。速度静态文件读取是毫秒级实时 API 调用有延迟。可控性生成描述文件时可以过滤敏感信息、裁剪冗余字段实时查询做不到这么细。代价是 Collection 更新后需要重新生成一次。但这个频率不高而且可以写个脚本一键跑完全能接受。3. 实操过程从 Collection 到 Skill 的完整链路3.1 第一步导出并清洗 Collection先在 Postman 里把目标 Collection 导出。右键集合 → Export → 选 Collection v2.1 → 导出为 JSON 文件。拿到文件后我写了个 Python 脚本做清洗。核心逻辑是递归遍历item把嵌套文件夹拍平提取每个请求的关键字段。代码大概这样import json def flatten_items(items, prefix): result [] for item in items: name prefix item.get(name, unnamed) if item in item: result.extend(flatten_items(item[item], name /)) elif request in item: req item[request] result.append({ name: name, method: req.get(method, GET), url: req.get(url, {}).get(raw, ), headers: [ {key: h[key], value: h.get(value, )} for h in req.get(header, []) ], body: req.get(body, {}), description: req.get(description, ), responses: [ { code: r.get(code), body: r.get(body, ) } for r in item.get(response, [])[:2] ] }) return result with open(collection.json, r, encodingutf-8) as f: data json.load(f) apis flatten_items(data.get(item, [])) print(f共解析出 {len(apis)} 个接口)跑完这一步你会得到一个干净的接口列表。我实测一个中等规模的 Collection大概 80 个接口解析耗时不到 1 秒。注意response我只取前两个示例因为有些接口保存了几十个响应全带上会让描述文件膨胀得没法看。两个足够智能体理解返回结构了。3.2 第二步生成 Skill 描述文件Codex 这类智能体框架的 Skill 通常需要一个描述文件告诉智能体“这个技能是干什么的、什么时候用、怎么调用”。格式各家不同但核心要素差不多名称、描述、输入参数、执行逻辑。我生成的描述文件结构是这样的{ name: postman_api_lookup, description: 查询 Postman 中维护的 API 接口定义。当需要了解某个接口的请求方法、URL、参数结构或返回格式时使用此技能。, parameters: { type: object, properties: { keyword: { type: string, description: 接口名称或路径关键词用于模糊匹配 } }, required: [keyword] }, api_catalog: [ { name: 订单服务/创建订单, method: POST, url: {{base_url}}/api/v1/orders, headers: [ {key: Content-Type, value: application/json}, {key: Authorization, value: Bearer {{token}}} ], body_schema: { product_id: string, quantity: integer, remark: string, optional }, response_example: { code: 0, data: {order_id: string, status: created} } } ] }这里有个关键设计api_catalog是内嵌在 Skill 描述里的而不是让智能体去读外部文件。原因是智能体在调用 Skill 时如果能直接从描述里拿到接口清单就不需要额外的文件读取步骤响应更快也更不容易出错。body_schema是我从 Postman 的 body 示例里推断出来的。如果 body 是 raw JSON直接解析如果是 form-data就提取字段名和类型。推断不出来的字段标成unknown让智能体知道这里信息不全。3.3 第三步注册 Skill 并验证把生成的描述文件放到 Codex 的 Skill 目录下具体路径看你的框架文档一般是skills/或.codex/skills/然后在配置里启用。验证分两步静态验证检查描述文件格式是否正确字段是否齐全。我写了个简单的校验脚本确保name、description、parameters三个必填项都在。动态验证在 Codex 里问一个需要用到接口定义的问题比如“订单服务的创建订单接口需要哪些参数”看它能不能正确调用 Skill 并返回结果。我第一次验证时失败了智能体说“找不到相关技能”。排查发现是描述文件里的name字段和配置里引用的名字不一致。改过来就好了。这种低级错误很常见建议你注册后先做一次静态检查。3.4 参数计算与选择描述文件多大合适这里有个权衡描述文件越大智能体能拿到的信息越多但加载和解析的开销也越大。我实测了几种规模接口数量文件大小加载耗时智能体响应质量20 个约 15KB100ms好80 个约 60KB约 200ms好300 个约 220KB约 800ms开始下降500 个以上400KB1.5s明显下降结论是单次注册的接口数量控制在 100 个以内比较稳妥。如果 Collection 很大按业务模块拆成多个 Skill比如“订单服务 Skill”“用户服务 Skill”让智能体按需调用。这样既控制了单个文件大小又提高了检索精度。4. 常见问题与排查技巧实录4.1 智能体不调用 Skill 怎么办这是最常见的问题。表现是你问了一个明明需要查接口的问题智能体却自己瞎编答案完全不碰 Skill。排查顺序检查 Skill 是否启用。有些框架需要显式在配置里开启默认是关闭的。检查 description 是否足够明确。如果描述写得太泛比如“查询 API”智能体不知道什么时候该用。改成“当需要了解接口的请求方法、参数结构或返回格式时使用”触发率会明显提高。检查参数定义。如果parameters里要求的参数智能体没法从对话中提取它就会放弃调用。把参数设计得宽松一点比如用keyword而不是exact_name。我踩过的坑一开始 description 写的是“Postman 接口查询工具”智能体基本不调用。后来改成“查询团队维护的 API 接口定义用于生成调用代码或测试用例”调用率从几乎为零变成十次有七八次会触发。4.2 解析 Collection 时字段缺失报错不同版本的 Postman 导出的 JSON 结构有细微差异。比如 v2.0 和 v2.1 在url字段上就不一样前者可能是字符串后者是对象。我的处理方式是全部用.get()加默认值绝不直接索引。比如req.get(url, {}).get(raw, )这样即使url是字符串.get也不会报错字符串没有.get方法但这里req.get(url, {})返回的是字符串再.get就会 AttributeError。更稳妥的写法是加类型判断url req.get(url, ) if isinstance(url, dict): url url.get(raw, )这种防御性编程在解析外部数据时是必须的。我见过太多因为一个字段类型不对导致整个脚本崩溃的情况。4.3 环境变量替换的坑Postman 的变量语法是{{variable_name}}但有些人在 URL 里写的是:variable_name路径参数这两种要区别对待。{{...}}是环境/集合变量值在环境文件里Skill 描述里保留占位符。:...是路径参数值在运行时传入Skill 描述里要标注“路径参数需替换”。我写了个正则同时匹配两种模式分别打标签。这样智能体拿到描述后知道哪些需要从环境读哪些需要从用户输入取。4.4 常见问题速查表问题现象可能原因解决方法智能体不调用 Skilldescription 不明确改成场景化描述说明何时使用解析脚本报 KeyError字段缺失或类型不符全部用.get()加类型判断生成的描述文件过大接口太多或 response 示例太多拆分 Skillresponse 只留 1-2 个智能体返回错误的 URL变量未替换在描述里明确标注变量来源敏感信息泄露直接导出了真实值清洗阶段过滤 token、password 等字段Skill 注册后不生效名称不一致或未启用检查配置引用名确认已开启4.5 独家避坑技巧技巧一给接口加“使用场景”标签。我在生成描述时会根据接口名称和路径自动打标签比如/orders打上“订单相关”/users打上“用户相关”。智能体在检索时能更快定位。这个标签不用很精确有就行。技巧二保留一个“最小可用示例”。每个接口的 response 示例只留一个最典型的不要留多个变体。多个示例会让智能体困惑不知道以哪个为准。技巧三定期重新生成。我设了个每周提醒重新导出 Collection 并生成 Skill 描述。因为接口会变描述文件不更新的话智能体拿到的就是过时信息。这个维护成本很低但收益很大。技巧四用版本号管理描述文件。在文件名或内容里加个版本号比如postman_api_lookup_v3.json。这样出问题时能快速回滚到上一个可用版本。5. 进阶玩法让 Skill 不只是“查询”5.1 从查询到生成让智能体直接产出调用代码基础版 Skill 只提供接口信息查询。但我后来发现可以在 Skill 里加一个“代码生成模板”字段让智能体在拿到接口定义后直接按模板生成调用代码。比如在描述文件里加code_template: { python: import requests\n\ndef call_{name}(payload):\n resp requests.{method}(\n {url},\n headers{headers},\n jsonpayload\n )\n return resp.json(), javascript: async function call{Name}(payload) {\n const resp await fetch({url}, {\n method: {method},\n headers: {headers},\n body: JSON.stringify(payload)\n });\n return resp.json();\n} }智能体在生成代码时会优先使用这个模板而不是自己从头写。这样生成的代码风格统一也减少了出错概率。5.2 结合测试脚本做断言推断Postman 的 Collection 里经常有测试脚本event字段里面包含断言逻辑。虽然这些脚本是 JavaScript但可以提取出关键断言转成自然语言描述。比如脚本里有pm.response.to.have.status(200)就提取出“期望状态码 200”。有pm.expect(jsonData.code).to.eql(0)就提取出“期望返回体 code 字段等于 0”。把这些断言描述加到 Skill 里智能体在生成测试用例时就能直接参考不用你再说一遍。5.3 多环境支持的处理方式一个 Collection 可能对应多个环境开发、测试、生产URL 前缀不同。我的做法是在 Skill 描述里不写死环境而是定义一个environment参数让智能体在调用时指定。parameters: { type: object, properties: { keyword: {type: string}, environment: { type: string, enum: [dev, test, prod], default: dev } } }然后在api_catalog里URL 用{{base_url}}占位实际值根据environment参数在运行时替换。这样一套 Skill 能覆盖多个环境不用为每个环境单独生成。提示生产环境的鉴权信息尤其要小心建议在 Skill 里只保留结构真实凭证通过环境变量注入绝不写入描述文件。6. 我实际用下来的体会这套东西我用了大概两个月最大的感受是前期投入半小时后期每天省十分钟。以前每次让 AI 帮忙写接口调用代码都要复制粘贴一堆上下文现在直接说“按订单服务的规范生成”它自己去查准确率高很多。另一个意外收获是接口定义的规范性提升了。因为知道这些定义会被智能体读取团队里的人在 Postman 里写 description 和 response 示例时认真多了。以前随便写写现在会考虑“AI 能不能看懂”。这算是倒逼了文档质量。如果你也想试我的建议是从小处着手先拿一个接口数量不多、结构清晰的 Collection 练手跑通整条链路再逐步扩大范围。别一上来就搞几百个接口的巨型 Collection那样调试起来很痛苦。最后分享一个小技巧在 Skill 的 description 里加一句“如果接口信息不完整请提示用户补充”这样智能体遇到缺字段的接口时不会瞎编而是会告诉你哪里缺信息。这个细节能省掉很多排查时间。