用途
api-discovery 用于在动手新建之前,先确认已经存在哪些 API、集合、规范或请求,并回答它们之间关系的问题。它属于 Postman 面向 Claude Code 的插件技能。
两条独立的数据路径
该技能包含两个互不连接的数据源,应根据数据来源而非问题形态来选择:
- search / context:检索某人在 Postman 中保存的 Postman 产物,包括集合(collections)、请求(requests)、规范(specs)、Mock(mocks)、工作区(workspaces)、环境(environments)、流程(flows)和文档(documents)。它做文本匹配,不做推理,适合回答“是否存在名为 X 或形态类似 X 的东西”。
- context-graph ask:面向一个单独填充的工程服务图(由仓库与流量扫描构建,不是 Postman 内容),对已发现的服务及其之间的依赖边做自然语言问答。适合回答“什么依赖 billing-api”这类架构问题——这类问题 search 在结构上无法回答,因为依赖边没有对应关键词。
在一个数据源里查不到,不代表另一个数据源里也没有;不要因为 search 为空就退回到 Context Graph,反之亦然。
search 用法
基本形式为 search <type> <query>,其中 type 可为 requests、collections、workspaces、flows、specs、mocks、environments 或 documents。
默认 --ownership organization 只在本组织内搜索;在得出“不存在此 API”的结论前,应先传 external 或 all,因为发布在组织之外的伙伴或公开 API 在默认范围下不可见。可用 --filter "method=POST AND workspaceId=ws-123" 进一步收窄,完整过滤字段与运算符语法参见 reference/search_filters.md。
context-graph 用法
交互式使用时推荐 context-graph ask "<question>" --wait,它会阻塞并打印答案。不加 --wait 时,ask 立即返回一个 id,之后用 status <askId> 查询进度(仍在运行时退出码为 3),适合耗时较长的问题或按自有节奏轮询的脚本。查询针对由 API key 推导出的团队运行,没有工作区/团队选择。--max-steps 可限制服务对每个问题的推理量。
答案由生成而非逐字检索,因此在用于任何有后果的决策前,应通过重新提问或更窄的查询加以核实,与对待任何 AI 生成主张的方式一致。
内置发现流程说明
Postman 自带一套供 AI 编码代理使用的发现工作流,可通过 postman context instructions discovery 打印。在基于 search/context 原语自行搭建发现流程之前,应先阅读它——这是 Postman 推荐的顺序(仅用 search/context,不含 context-graph),不是可以随意重造的白纸。
发现之后:复用找到的内容
dependency add <type> <nameOrId> 可将另一个工作区中找到的集合、环境或 Mock 正式添加为当前工作区的依赖,这是 search/context 找到可复用对象后的下一步(例如用于应用测试的契约匹配),而非手动复制。该命令接收 Postman 实体 ID,因此只能承接 search/context 的结果;context-graph 的发现给出的是服务名而非 ID,需先用 search 找到该服务的集合。
关键规则
- context-graph 与 search/context 不共享数据集;在向用户报告“不存在”之前,应针对其自身的数据源核实,而不要用另一个工具。
- 默认范围内的空搜索结果不能证明不存在;在报告“没有此 API”之前,用
--ownership all重试。 - Context Graph 的答案是生成的推理,不是数据库读取;在将其视为事实(尤其用户会据此行动的内容)之前,应针对具体来源核实。
- search、context-graph 与 context 属于 Beta 或近期新增接口;如果安装的 CLI 版本比该文件所假设的更新,使用前应重新运行
-h确认标记名称,这些命令最可能已发生变化。
验证
应说明究竟是哪个工具回答了问题(search 还是 Context Graph),以及在什么 --ownership 范围下、或用了什么 --max-steps/查询。发现答案的可信度取决于其运行范围。
限制
现有资料未提供价格、平台支持范围或性能数据。该技能面向 Postman 与 Claude Code 插件环境,相关命令标记可能随 CLI 版本变化。