Postman

使用 Postman CLI 与 Postman API 完成云端资产维护和请求执行。开始前运行 postman --version，要求 >= 1.51.0。云端资源发现与 CRUD 直接使用 API 助手，不使用 Postman CLI 判断 API 登录状态，也不为 API 操作增加额外的 CLI 认证检查。

路由

• Workspace 查询，以及 Collection、Folder、Request、Example Response、Environment 的云端查询与增删改查：使用 scripts/postman-api.mjs。先阅读 references/operations.md。
• Collection 级 Authorization、Variables、Scripts 与 Settings：先读取最新 Collection，再优先使用 PATCH /collections/<collection-id> 构造最小更新；Params、Headers、Body 等 Request 字段使用 Collection Items API。具体格式见 references/collection-format.md。
• 临时 HTTP 请求：使用 postman request。
• 执行云端 Collection 或其中一个 Request：使用 postman collection run。
• 从本地代码生成或批量同步：使用 postman workspace pull/lint/prepare/push。
• Workspace 只用于查询、解析名称和确认归属；不要创建、修改或删除 Workspace。

认证

API 助手读取当前用户的 ~/.postman/postmanrc，选择 US Profile，并仅在内存中注入 X-API-Key。API 助手请求成功时直接继续任务，不再运行其他认证探测命令。

• 不向用户索取、显示或记录 API Key。
• 不把 Key 放进命令参数、项目文件、Collection、报告或错误信息。
• 仅当 API 助手明确报告凭据文件缺失、Profile 不含 API Key，或 Postman API 返回 401 时，才要求用户自行运行 postman login；不要索要 Key。
• Local Value 与 Postman Vault Secret 由用户人工维护，不自动操作。

云端修改流程

1. 用户明确指定 Workspace 时按名称或 ID 解析。未指定时调用 GET /workspaces：仅返回一个 Workspace 就直接使用；返回多个但仅有一个 visibility: "personal" 时自动使用该个人 Workspace；否则展示候选名称、ID、visibility，让用户选择，不猜测。
2. 修改前读取目标最新状态，保留服务端 ID；Collection 级字段可用 PATCH、其他字段可用细粒度 endpoint 完成时，不要全量 PUT Collection。
3. 创建、修改等已由用户明确要求的操作可以执行；删除、全量覆盖或 force-sync 必须在实际调用前再次明确影响范围并取得确认。
4. 更新只提交需要改变的字段。接口成功后重新读取目标，验证名称、ID 和关键字段。
5. 返回资源 ID、变更摘要与验证结果，不输出凭据或无关响应体。

禁止自动运行 postman workspace push --push-strategy force-sync。普通 workspace push 也会以本地文件覆盖云端元素；只在完整新建或批量同步时使用。

执行请求

临时请求优先使用：

postman request METHOD URL --timeout 30000

执行 Collection 或指定 Request：

postman collection run <collection-uid> -i <request-id-or-path> \
  -r cli,json --reporter-json-export <report.json> --bail

• GET/HEAD 等只读请求可在用户明确要求执行时直接运行。
• POST/PUT/PATCH/DELETE 或可能影响生产数据的请求，执行前确认目标、方法和影响。
• 质量判断必须综合 CLI 退出码、HTTP 状态、断言、stderr 和结构化报告。
• --response-only 只用于提取正文，不用于断言或质量门禁。
• postman request --output 的实际产物必须检查后再宣称报告已生成。

API 助手

node scripts/postman-api.mjs GET /workspaces
node scripts/postman-api.mjs GET /collections --query workspace=<workspace-id>
node scripts/postman-api.mjs GET /collections/<collection-id>
node scripts/postman-api.mjs POST /collections --query workspace=<workspace-id> --body-file collection.json
node scripts/postman-api.mjs PATCH /collections/<collection-id> --body-file collection-update.json
node scripts/postman-api.mjs POST /collections/<collection-id>/requests --body-file request.json
node scripts/postman-api.mjs PUT /collections/<collection-id>/requests/<request-id> --stdin < update.json
node scripts/postman-api.mjs DELETE /collections/<collection-id>/requests/<request-id> --confirm-delete <request-id>

使用裸 UUID 调用 Collection Items API；只有明确要求 UID 的接口才使用 userId-resourceId。请求体优先通过 --body-file 或 --stdin 传入，避免复杂 JSON 和敏感值进入 shell 历史。

失败处理

• 401：登录失效或 API Key 被轮换，提示重新 postman login。
• 403：权限、套餐或组织策略限制；不要改用更破坏性的路径绕过。
• 404：重新解析 ID 与 UID，确认资源归属。
• 409：重新读取最新资源，报告冲突，不盲目覆盖。
• 429：遵循响应中的重试时间，只做有限重试。
• API 或 CLI 输出与预期不符时停止写入，保留已知资源 ID 并说明当前状态。