pp-postman-explore

Postman Explore — Printing Press CLI

前置条件：安装 CLI

此技能由 postman-explore-pp-cli 二进制文件驱动。调用此技能中的任何命令之前，必须确认已安装 CLI。 如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install postman-explore --cli-only
   

2. 验证：postman-explore-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent／运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接 Go 安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/developer-tools/postman-explore/cmd/postman-explore-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。在验证成功之前，不要继续执行此技能的命令。

何时使用此 CLI

当你需要以编程方式发现、比较或监控社区贡献的 Postman 集合／工作区／API／流程时，选择此 CLI。它非常适合需要为某个供应商寻找权威 Postman 集合的 AI Agent、需要比较某个类别中发布者的 API 策展人，以及监控网络变化的脚本。请勿使用此 CLI 管理自己的私有 Postman 工作区——那需要调用经过身份验证的 Postman 产品 API，完全属于不同的接口。

独特功能

这些功能在用于此 API 的其他工具中均不可用。

本地累积的发现能力

• canonical — 使用一条命令查找最适合某个供应商的社区 Postman 集合，并根据发布者验证状态、分叉数和最近更新时间进行排名。

  当用户要求 Agent 查找某个供应商的 Postman 集合时，此命令可通过一次调用直接返回最佳权威选择，无需 Agent 对搜索结果列表去重。

  postman-explore-pp-cli canonical stripe --json
  

• top — 按任意指标（weekForks、monthViewCount 等）对实体排名，并可进一步限定类别和实体类型。

  当 Agent 需要推荐本周分叉数最多的集合，而不是历史排名靠前的集合时，只有这条路径可行。

  postman-explore-pp-cli top --metric weekForkCount --type collection --category payments --limit 10
  

• similar — 给定实体数字 ID，返回名称、摘要和类别重叠的集合，并根据与种子实体文本的 FTS 相关性得分进行排名。

  当集成方找到一个集合但想与其他选项比较时，此命令可通过一次调用返回竞品，无需重新搜索。

  postman-explore-pp-cli similar 10289 --limit 5 --json
  

对比分析

• publishers top — 汇总某个类别中各发布者所有实体的分叉数，并按社区影响力总和对团队排名。

  需要在供应商之间做比较的 API 策展人，以及需要据此选出集成合作伙伴的 Agent，都可以使用此命令。

  postman-explore-pp-cli publishers top --category developer-productivity --limit 5 --json
  

• category landscape — 对于某个类别 slug，返回：每种类型的实体总数、按分叉数总和排名的前 5 位发布者，以及按 viewCount 排名的前 5 个实体。一条命令即可获得一个结构化数据包。

  评估某个垂直领域（支付、AI、devops）的 API 策展人需要了解谁占主导地位、什么最受欢迎；此命令正好提供这样的概览。

  postman-explore-pp-cli category landscape payments --json
  

基于时间窗口的信号

• drift — 报告本地已同步实体中，API 端 updatedAt 时间戳落在指定时间窗口内的实体。

  追踪近期更新的供应商集合的 Agent，可在定期执行 sync 后使用此命令；它展示的是指定时间窗口内更新过的实体，而不是对比两个快照以找出已移除实体。

  postman-explore-pp-cli drift --since 7d --type collection --json
  

• velocity — 按加速度比率对集合排名：(weekForkCount × 4) / monthForkCount。可发现尚未登上热门榜单、但正在迅速崛起的集合。

  对于追踪新兴供应商的 API 策展人来说，在某个集合登上热门排序榜之前发现它具有很高价值。

  postman-explore-pp-cli velocity --type collection --top 10
  

质量信号

• browse — 使用 --verified-only 时，browse 命令会筛选由已设置 verified-team 标记的发布者拥有的实体。

  如果你只想要官方供应商的集合（而非社区分支），这是最简洁的筛选方式。

  postman-explore-pp-cli browse collection --verified-only --category payments --json --limit 5
  

HTTP 传输

此 CLI 使用兼容 Chrome 的 HTTP 传输来访问面向浏览器的端点。常规 API 调用无需常驻浏览器进程。

发现信号

此 CLI 根据浏览器观察到的流量上下文生成。

• 捕获覆盖范围：24 个网络条目中包含 17 个 API 条目
• 协议：rest_json（置信度 60%）、rpc_envelope（置信度 95%）
• 身份验证信号：无
• 生成提示：client_pattern:proxy-envelope, uses_browser_http_transport, no_auth_required, skip_clearance_cookie
• 已生成的命令：browse；networkentity get-network-entity；networkentity get-network-entity-counts；category list-categories；category get；team get-workspaces；team get；search-all

命令参考

category — 管理类别

• postman-explore-pp-cli category get — 根据类别的 URL slug 返回完整详情（例如，artificial-intelligence、developer-productivity、...
• postman-explore-pp-cli category list-categories — 返回用于整理 API 网络的所有类别（例如，AI、电商、通信、DevOps）。类别...

networkentity — 管理 networkentity

• postman-explore-pp-cli networkentity get-network-entity — 根据内部数字 ID 返回完整实体记录（listNetworkEntities 中的 id 字段，而不是 entityId UUID）。
• postman-explore-pp-cli networkentity get-network-entity-counts — 返回整个公共 API 网络的汇总数量：集合、工作区、API、流程、笔记本，...
• postman-explore-pp-cli networkentity list-network-entities — 列出公共集合、工作区、API 或流程。支持按类别筛选、分页和最低分支数...

search-all — 管理全局搜索

• postman-explore-pp-cli search-all — 按自由文本查询搜索集合、工作区、请求、流程和团队。未设置 queryIndices 时，...

team — API 网络上的发布者团队

• postman-explore-pp-cli team get — 根据团队的 publicHandle 返回简要资料对象（id、name、description、publicHandle、profileURL、createdAt、updatedAt），...
• postman-explore-pp-cli team get-workspaces — 返回由指定 publicHandle 的团队拥有的公共工作区数组（例如，stripedev、...

找到合适的命令

当你知道自己想做什么，却不知道该使用哪个命令时，可以直接询问 CLI：

postman-explore-pp-cli which "<capability in your own words>"

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有足够可靠的匹配项——请改用 --help 或使用更具体的查询。

配方

查找 Stripe 的官方集合

postman-explore-pp-cli canonical stripe --json --select id,name,publisher.publicHandle,metrics.forkCount

规范命令会选出已验证发布者中分支数最多的匹配项，并将 JSON 精简为 Agent 实际需要的四个字段。

比较顶级支付领域发布者

postman-explore-pp-cli publishers top --category payments --limit 5 --json

汇总每个发布者在支付类别下全部作品集的分支数。

查看本周网络上的变化

postman-explore-pp-cli sync --resources collection,workspace,api,flow,category && postman-explore-pp-cli drift --since 7d --type collection --json

先同步，然后查询本地存储中 API 端 updatedAt 位于所需时间范围内的集合。

浏览顶级开发者效率集合，并缩小到已验证发布者

postman-explore-pp-cli browse collection --category 4 --verified-only --limit 10 --json --select name,publisher.publicHandle,metrics.viewCount,redirectURL

使用 --select 和点分隔路径，避免为每条记录提取完整的约 5 KB 指标数组，从而减少 Agent 上下文中的输出。

查找支付领域中增长加速的集合

postman-explore-pp-cli velocity --type collection --category payments --top 10

速度排名根据每周与每月的分支速率进行排序，能够找出正在崭露头角、尚未登上累计热门榜单的集合。

查找与种子相似的集合

postman-explore-pp-cli similar 10289 --limit 5 --json

针对本地 FTS 索引执行相似项查询，适合发现竞争或互补的社区集合。

获取整个类别的快照

postman-explore-pp-cli category landscape payments --json

在一个结构化数据载荷中汇总某个类别的各类型计数、热门发布者和热门实体。

身份验证设置

无需身份验证。

运行 postman-explore-pp-cli doctor 验证设置。

Agent 模式

为任何命令添加 --agent。该参数会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留一部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于内容冗长的 API，此功能对控制上下文大小至关重要：

  postman-explore-pp-cli category get mock-value --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不会发送

• 适合离线使用 — 同步／搜索命令在本地 SQLite 存储可用时可以使用它

• 非交互式 — 从不提示，每项输入都是一个标志

响应封装

从本地存储或 API 读取数据的命令会将输出封装在一个溯源信封中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 以了解数据来自实时来源还是本地来源。只有当 stdout 连接到终端时，才会将人类可读的 N results (live) 摘要打印到 stderr；通过管道传输或由 Agent 使用时，stdout 只会输出纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

postman-explore-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
postman-explore-pp-cli feedback --stdin < notes.txt
postman-explore-pp-cli feedback list --json --limit 10

条目会存储在本地的 ~/.postman-explore-pp-cli/feedback.jsonl。除非设置了 POSTMAN_EXPLORE_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 POSTMAN_EXPLORE_FEEDBACK_AUTO_SEND=true，否则绝不会执行 POST。默认情况下只保存在本地。

记录让你感到意外的地方，而不是提交错误报告。简短、具体、单行：这才是能不断积累价值的内容。

输出传递

每个命令都接受 --deliver <sink>。除 stdout 外，也可以将输出发送到指定目标，从而让 Agent 无需手动通过管道即可路由命令结果。支持三种目标：

目标	效果
stdout	默认值；仅写入 stdout
file:<path>	将输出原子写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（--compact 时使用 application/json 或 application/x-ndjson）

遇到未知方案时会拒绝处理，并返回包含受支持方案列表的结构化错误。Webhook 失败时会返回非零状态码，并在 stderr 中记录 URL 和 HTTP 状态。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。如果定时运行的 Agent 每次都以相同配置调用同一命令，就可以使用配置——类似于 HeyGen 的“Beacon”模式。

postman-explore-pp-cli profile save briefing --json
postman-explore-pp-cli --profile briefing category get mock-value
postman-explore-pp-cli profile list --json
postman-explore-pp-cli profile show briefing
postman-explore-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，让进行自省的 Agent 能在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
5	API 错误（上游问题）
7	受到速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 postman-explore-pp-cli --help 的输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何内容 → 直接使用（作为带有 --agent 的 CLI 命令执行）

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/developer-tools/postman-explore/cmd/postman-explore-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add postman-explore-pp-mcp -- postman-explore-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which postman-explore-pp-cli 如果未找到，请提供安装选项（参见本技能顶部的先决条件）。
2. 根据“独特功能”和“命令参考”中的内容，将用户查询匹配到最合适的命令。
3. 使用 --agent 标志执行：

   postman-explore-pp-cli <command> [subcommand] [args] --agent
   

4. 如果含义不明确，请查看子命令帮助：postman-explore-pp-cli <command> --help。