postman

Postman Agent Skill

版本：1.1.0（阶段 1 - 核心 API 兼容性） API 支持：Postman v10+（兼容降级支持 v9）

🚀 快速开始

首次使用此技能时，Claude 将自动：

1. ✅ 验证你的 API 密钥和连接
2. 📁 检查你的工作区配置
3. 📊 统计你的集合和资源数量
4. 💡 如果设置未完成，提供后续步骤建议

首次设置验证：

# Claude will run this automatically on first use
python scripts/validate_setup.py

可立即使用的常见入门问题：

• “我有多少个集合？” - 列出工作区中的所有集合
• “显示我的工作区” - 显示可用的工作区
• “验证我的设置” - 运行全面诊断
• “创建一个名为 ‘Test API’ 的新集合” - 立即开始构建

🤖 给 Claude 的说明：在对话中首次使用此技能时，始终运行：

python scripts/validate_setup.py

这样可在处理用户请求前立即提供诊断信息和上下文。

✅ 网络兼容性

正确配置代理后，此技能可在多个 Claude 环境中运行。

此技能适用的环境

环境	状态	说明
Claude Web 界面	✅ 完全支持	可在已配置代理的情况下运行
Claude API（代码执行）	✅ 完全支持	没有网络限制
本地 Python 脚本	✅ 完全支持	在你的计算机上直接执行
Claude Desktop	⚠️ 有限支持	需要将 api.getpostman.com 添加到网络允许列表

代理配置

此技能专为代理环境设计：

• 保留代理环境变量，以确保正确进行 DNS 解析
• 处理来自代理服务的嵌套 HTTP 响应
• 支持通过代理传输 HTTP/2 响应
• 可使用 POSTMAN_DEBUG=1 环境变量启用调试模式

如何使用此技能

选项 1：Claude Web 界面（推荐） 直接在 Claude Web 界面中使用此技能。代理已预先配置，可自动处理所有网络请求。

选项 2：启用代码执行的 Claude API 通过启用了代码执行的 Anthropic API 使用此技能。此方式没有网络限制。

选项 3：本地 Python 脚本 在你的计算机上直接运行脚本：

python scripts/list_collections.py
python scripts/manage_collections.py --list

概述

此技能赋予 Claude 与 Postman API 交互的能力，以管理完整的 API 生命周期。它支持发现工作区资源、执行测试集合、分析监控结果等。

v1.1 新增内容（阶段 1）

✨ 增强的错误处理：提供实用解决建议的自定义异常类 🔀 类似 Git 的工作流：分叉集合、创建拉取请求并合并更改 🔐 自动检测机密信息：自动保护敏感环境变量 🔄 智能复制：完整复制集合和环境 📡 API 版本检测：自动检测并发出兼容性警告 🎯 改进开发者体验：简化 API 并提供更清晰的错误消息

功能

• 发现：列出工作区中的集合、API、规范、环境和监视器
• 设计：管理 API 规范、验证架构、比较版本并定义 API
  • 🆕 规范中心：创建和管理 API 规范（OpenAPI 3.0、AsyncAPI 2.0）
  • 🆕 多文件规范：支持将规范拆分为多个独立架构文件
  • 🆕 双向生成：从规范生成集合，或从集合生成规范
  • 验证 API 架构并比较版本
• 构建：创建、更新和删除集合与环境
  • 🆕 分支与合并：为集合提供类似 Git 的版本控制（v10+）
  • 🆕 拉取请求：支持协作编辑集合的工作流（v10+）
  • 🆕 智能复制：复制集合和环境，并保留完整元数据
• 测试：使用 Newman 运行集合测试套件并分析结果
• 安全：检查身份验证配置和安全设置
  • 🆕 自动检测密钥：自动将敏感变量标记为密钥
  • 🆕 保留密钥类型：在操作过程中保留密钥类型
• 部署：创建和管理用于 API 原型设计的模拟服务
• 观测：创建、管理和分析监视器，持续监控 API
• 分发：查看和评估 API 文档质量

何时使用此技能

在以下情况下，Claude 应使用此技能：

• 提到 Postman、集合、API 规范或 API 测试
• 想要创建或管理 API 规范（OpenAPI、AsyncAPI、Swagger）
• 需要将 API 规范上传或导入 Postman
• 想要根据 API 规范生成集合
• 想要根据现有集合生成规范
• 想要验证 API 架构或比较版本
• 想要创建、更新或删除集合或环境
• 需要复制或整理集合和环境
• 请求检查身份验证或安全配置
• 请求创建用于原型设计的模拟服务
• 请求运行测试或检查测试结果
• 想要查看可用的 API、集合或规范
• 需要创建、管理或分析监视器
• 询问 API 正常运行时间、监控或可观测性
• 想要检查监视器状态或运行历史记录
• 询问 API 文档的质量或访问权限

前提条件

此技能需要一个包含 Postman API 密钥的 .env 文件。该文件应包含在技能包中，并会在运行任何脚本时自动加载。

重要：如果此技能提示输入 API 密钥，说明 .env 文件可能：

• 未包含在技能包中
• 为空或格式不正确
• 脚本无法读取

修复方法：确保技能包中包含带有以下内容的 .env 文件：

POSTMAN_API_KEY=PMAK-your-key-here

.env 中的可选配置：

POSTMAN_WORKSPACE_ID=your-workspace-id
POSTMAN_RATE_LIMIT_DELAY=60
POSTMAN_MAX_RETRIES=3
POSTMAN_TIMEOUT=30
# POSTMAN_USE_PROXY=false  # Keep this false to bypass proxies (default)

代理配置（企业网络环境下请注意）

默认情况下，此技能会绕过所有代理服务器，以避免 Claude Desktop 中常见的“403 Forbidden”代理错误。

如果出现以下错误：

• ProxyError: Unable to connect to proxy
• Tunnel connection failed: 403 Forbidden

此技能会自动处理，无需采取任何操作。最新版本默认会绕过代理。

如果你处于企业网络环境中，需要使用代理：

1. 在 .env 文件中添加 POSTMAN_USE_PROXY=true
2. 确保代理允许连接到 api.getpostman.com

获取 Postman API 密钥

1. 前往 https://web.postman.co/settings/me/api-keys
2. 点击“Generate API Key”
3. 复制密钥（以 PMAK- 开头）
4. 将密钥添加到技能目录中的 .env 文件

如何使用此技能 - 重要

⚠️ 关键：所有 Postman API 调用都必须通过 Python 脚本完成

此技能使用 Python 脚本与 Postman API 交互。不要尝试直接使用 HTTP 请求调用 api.postman.com，因为这会因浏览器环境中的 CORS（跨域资源共享）限制而失败。

始终使用 Python 脚本：

# ✅ CORRECT: Use Python scripts
python /path/to/postman-skill/scripts/list_collections.py

# ❌ WRONG: Direct API calls will fail with CORS errors
# fetch('https://api.getpostman.com/collections')  # This will NOT work

原因：

• Python requests 库不受 CORS 限制
• 浏览器直接调用 api.postman.com API 会被 CORS 阻止
• 所有脚本都会自动从 .env 文件加载你的 API 密钥

可用工作流

发现资源

文件：workflows/test/list_collections.md

列出工作区中的所有集合、环境和监视器，了解有哪些资源可用。

验证 API 架构

文件：workflows/design/validate_schema.md

根据 OpenAPI/Swagger 标准验证 API 架构。检查架构结构、获取 API 版本，并确保 API 定义在部署前格式正确。

比较 API 版本

文件：workflows/design/version_comparison.md

比较 API 的不同版本，以识别变更、破坏性更新和迁移要求。这对于 API 治理和版本管理至关重要。

管理 API 规范（Spec Hub）

文件：workflows/design/manage_specs.md

使用 Postman 的 Spec Hub 创建和管理 API 规范。这是管理 API 定义的现代推荐方法。

🆕 新功能：

• 直接创建规范（OpenAPI 3.0、AsyncAPI 2.0）
• 支持单文件和多文件规范
• 根据规范自动生成集合
• 根据现有集合生成规范
• 支持 YAML 和 JSON 格式
• 取代已弃用的 create_api() 工作流

管理集合

文件：workflows/build/manage_collections.md

创建、更新、删除和复制 Postman 集合。构建新的测试集合、整理现有集合，并以编程方式管理集合生命周期。

🆕 v1.1 增强功能：

• 分叉集合以进行独立开发
• 创建和管理拉取请求
• 合并分叉中的变更
• 复制集合并完整保留元数据

管理环境

文件：workflows/build/manage_environments.md

创建、更新、删除和复制 Postman 环境。为不同阶段（开发、预发布、生产）设置环境变量，并管理环境配置。

🆕 v1.1 增强功能：

• 自动检测敏感变量（api_key、token、password 等）中的密钥
• 部分更新时保留现有密钥
• 复制环境时保留密钥
• 通过简化的基于 dict 的 API 快速创建环境

运行集合测试

文件：workflows/test/run_collection.md

使用 Newman 执行集合的测试套件，并获取格式化结果，显示通过和失败情况以及详细诊断信息。需要安装 Newman CLI。

检查身份验证

文件：workflows/secure/check_auth.md

检查集合中的身份验证配置。识别身份验证类型、检查安全设置，并获取改善 API 安全性的建议。

管理模拟服务

文件：workflows/deploy/manage_mocks.md

创建、更新和管理用于 API 原型设计和前端开发的模拟服务。无需实现后端即可进行测试。

管理监视器

文件：workflows/observe/manage_monitors.md

创建、更新、删除和分析 Postman 监视器，以持续监控 API。查看监视器运行历史记录、成功率和性能指标，确保 API 的可靠性。

查看文档

文件：workflows/distribute/view_documentation.md

访问 API 文档并评估其质量。检查文档完整性、查看端点说明，并获取改进文档的建议。

架构

此技能采用渐进式披露：

1. 元数据（始终加载）：YAML 前置内容中的技能名称和描述
2. SKILL.md（触发时加载）：此概览文档
3. 工作流文件（按需加载）：具体的分步说明
4. Python 脚本（执行，不加载）：实际的 API 交互代码

文件结构

postman-skill/
├── SKILL.md                      # This file - skill overview
├── workflows/
│   ├── test/
│   │   ├── list_collections.md   # Discovery workflow
│   │   └── run_collection.md     # Test execution workflow
│   ├── design/
│   │   ├── manage_specs.md       # 🆕 Spec Hub management workflow (NEW!)
│   │   ├── validate_schema.md    # Schema validation workflow
│   │   └── version_comparison.md # API version comparison workflow
│   ├── build/
│   │   ├── manage_collections.md # Collection management workflow
│   │   └── manage_environments.md # Environment management workflow
│   ├── secure/
│   │   └── check_auth.md         # Authentication check workflow
│   ├── deploy/
│   │   └── manage_mocks.md       # Mock server management workflow
│   ├── observe/
│   │   └── manage_monitors.md    # Monitor management workflow
│   └── distribute/
│       └── view_documentation.md # Documentation access workflow
├── scripts/
│   ├── config.py                 # Configuration management
│   ├── postman_client.py         # API client with CRUD + Spec Hub operations (now uses curl)
│   ├── validate_setup.py         # 🆕 Comprehensive setup validation & diagnostics
│   ├── list_collections.py       # Collection discovery script (enhanced with context)
│   ├── list_workspaces.py        # 🆕 Workspace discovery and navigation
│   ├── manage_collections.py     # Collection management CLI
│   ├── manage_environments.py    # Environment management CLI
│   ├── manage_pet_store_spec.py  # 🆕 Spec Hub example script (NEW!)
│   ├── manage_pet_store_api.py   # Legacy API example (deprecated)
│   ├── run_collection.py         # Newman test execution wrapper
│   └── manage_monitors.py        # Monitor management CLI
├── utils/
│   ├── retry_handler.py          # Retry logic with backoff
│   ├── formatters.py             # Output formatting (collections, monitors, runs)
│   └── exceptions.py             # 🆕 Custom exception classes with helpful messages
├── tests/
│   ├── test_phase1_manual.py     # 🆕 Phase 1 test suite
│   └── README.md                 # 🆕 Testing guide
└── docs/
    ├── assessment-report.md      # 🆕 Current state analysis
    ├── api-compatibility-matrix.md # 🆕 API endpoint coverage
    ├── gap-analysis.md           # 🆕 Implementation roadmap
    └── compatibility-strategy.md # 🆕 v10+ compatibility approach

使用示例

基本操作

列出所有集合：

python /skills/postman-skill/scripts/list_collections.py

创建新集合：

python /skills/postman-skill/scripts/manage_collections.py --create --name "My API Tests"

创建环境并自动检测密钥（v1.1）：

from scripts.postman_client import PostmanClient

client = PostmanClient()
env = client.create_environment(
    name="Production",
    values={
        "base_url": "https://api.example.com",
        "api_key": "secret-key-123",      # Auto-detected as secret! 🔐
        "bearer_token": "bearer-xyz-456"  # Auto-detected as secret! 🔐
    }
)

Spec Hub 工作流（新增！）

创建 API 规范：

import json
from scripts.postman_client import PostmanClient

client = PostmanClient()

# Create OpenAPI 3.0 spec
openapi_spec = {
    "openapi": "3.0.0",
    "info": {"title": "My API", "version": "1.0.0"},
    "paths": {"/users": {"get": {"responses": {"200": {"description": "Success"}}}}}
}

spec = client.create_spec({
    "name": "My API",
    "description": "A sample API",
    "files": [{
        "path": "openapi.json",
        "content": json.dumps(openapi_spec),
        "root": True
    }]
})
print(f"Created spec: {spec['id']}")

根据规范生成集合：

# Automatically create a collection from your spec
result = client.generate_collection_from_spec(
    spec_id,
    collection_name="My API Collection"
)

根据集合生成规范：

# Create a spec from an existing collection
result = client.generate_spec_from_collection(
    collection_id="collection-12345",
    spec_name="Generated API Spec"
)

运行完整示例：

python scripts/manage_pet_store_spec.py

版本控制工作流（需要 v1.1 - v10+）

派生集合：

# Create a fork for independent development
fork = client.fork_collection(
    collection_uid="12345-abcde",
    label="feature-new-tests"
)
print(f"Forked collection: {fork['uid']}")

创建拉取请求：

# Propose merging your changes
pr = client.create_pull_request(
    collection_uid="12345-abcde",      # Parent collection
    source_collection_uid=fork['uid'], # Your fork
    title="Add authentication tests",
    description="This PR adds comprehensive auth test coverage"
)

合并拉取请求：

# Merge approved changes
client.merge_pull_request("12345-abcde", pr['id'])

复制集合：

# Create a standalone copy (not a fork)
backup = client.duplicate_collection(
    collection_uid="12345-abcde",
    name="My Collection Backup"
)

验证 API 架构：

# See: workflows/design/validate_schema.md
from scripts.postman_client import PostmanClient
client = PostmanClient()
schemas = client.get_api_schema(api_id="<api-id>", version_id="<version-id>")

检查身份验证配置：

# See: workflows/secure/check_auth.md
collection = client.get_collection(collection_uid="<collection-id>")
auth_type = collection.get('auth', {}).get('type', 'No auth')

创建模拟服务：

# See: workflows/deploy/manage_mocks.md
mock_data = {"name": "API Mock", "collection": "<collection-uid>"}
mock = client.create_mock(mock_data)
print(f"Mock URL: {mock['mockUrl']}")

运行指定集合：

python /skills/postman-skill/scripts/run_collection.py --collection="My API Tests"

列出所有监视器：

python /skills/postman-skill/scripts/manage_monitors.py --list

分析监视器运行历史：

python /skills/postman-skill/scripts/manage_monitors.py --analyze <monitor-id> --limit 20

错误处理（v1.1 增强）

所有脚本均包含：

• 自定义异常类：针对每种错误类型的专用异常
  • AuthenticationError (401) - API 密钥无效，并提供设置说明
  • PermissionError (403) - 权限不足，并提供解决步骤
  • ResourceNotFoundError (404) - 资源缺失，并列出可能原因
  • ValidationError (400) - 请求验证失败，并提供详情
  • RateLimitError (429) - 超出速率限制，并提供重试等待信息
  • ServerError (5xx) - 服务器错误，并提供状态页链接
  • NetworkError - 连接问题，并提供故障排查步骤
  • TimeoutError - 请求超时，并提供配置指导
• 自动重试，采用指数退避（3 次尝试）
• 实用的错误消息，提供解决指导
• API 版本检测，并显示兼容性警告
• 速率限制处理，采用自动退避

错误消息示例

之前（v1.0）：

Exception: API request failed with status 404: Resource not found

之后（v1.1）：

ResourceNotFoundError: Collection with ID '12345' was not found.

Possible reasons:
- The resource was deleted
- The ID is incorrect
- You don't have permission to access it
- The resource is in a different workspace

安全（v1.1 增强）

• 仅从环境变量读取 API 密钥
• 所有操作均限定在已配置的工作区内
• 采用自动退避处理速率限制
• 不记录或缓存敏感数据
• 🆕 自动检测密钥，适用于环境变量
• 🆕 更新和复制时保留密钥类型
• 🆕 监控 11 个敏感关键词（api_key、token、password、bearer、auth 等）
• 🆕 默认类型变量不会意外泄露凭据

限制

• 在代码执行容器中运行（API 调用不受网络访问限制）
• 技能大小上限为 8MB
• 仅使用预装的 Python 软件包
• 派生集合和拉取请求需要 Postman v10+ API
• 某些企业功能可能需要付费的 Postman 套餐

API 版本兼容性

此技能针对 Postman v10+ API 进行了优化，同时也能平稳降级：

功能	v9 API	v10+ API
集合 CRUD	✅ 尽力支持	✅ 完整支持
派生集合	❌ 不可用	✅ 完整支持
拉取请求	❌ 不可用	✅ 完整支持
环境 CRUD	✅ 尽力支持	✅ 完整支持
密钥变量	⚠️ 有限支持	✅ 完整支持
自定义异常	✅ 完整支持	✅ 完整支持
版本检测	✅ 完整支持	✅ 完整支持

客户端会自动检测你的 API 版本；如果 v10+ 功能不可用，则会显示警告。

后续步骤

加载此技能（Claude 指令）后：

1. 始终先运行设置验证：python scripts/validate_setup.py
   • 立即提供诊断信息和工作区上下文
   • 主动识别配置问题
   • 显示集合数量和实用的后续步骤
2. 如果验证失败：
   • 检查 .env 文件中是否设置了 POSTMAN_API_KEY
   • 指引用户前往 https://web.postman.co/settings/me/api-keys 获取密钥
3. 对于“有多少个集合？”这类查询：
   • 运行 python scripts/list_collections.py
   • 如果未找到集合，建议：
     • 列出工作区：python scripts/list_workspaces.py
     • 创建新集合
     • 在 .env 文件中切换工作区
4. 根据用户请求执行特定工作流

实用诊断命令：

• 设置验证：python scripts/validate_setup.py
• 列出集合：python scripts/list_collections.py
• 列出工作区：python scripts/list_workspaces.py
• 列出所有资源：python scripts/list_collections.py --all

相关资源

• Postman API 文档
• 工作流文件
• 示例响应