关于 Reqly
Reqly 是面向 AI Agent 和开发团队的本地优先 API 测试应用及 MCP 服务。它将集合保存为仓库中的纯 YAML,并通过 Agent 工具、命令行和 Web UI 支持请求测试、流程编排、流量捕获及 CI 导出。
主要功能
- 01以仓库 YAML 保存集合
- 02创建并运行带断言的 API 请求
- 03将请求串联为多步流程
- 04依据 OpenAPI 规范验证响应
- 05捕获入站和出站流量
- 06导出集合和 CI 工作流
适用场景
- 01根据应用路由构建请求集合
- 02测试身份验证和响应断言
- 03运行登录到结账的流程
- 04将 API 测试导出至 CI
MCP 相关
Reqly 在本地运行 MCP 服务,向 Agent 提供创建集合与请求、运行测试、串联流程、捕获流量和导出集合等工具。其命令行可为受支持的 Agent 宿主配置 MCP 连接。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
我们还没有获取到这个服务的安装包或远程地址,请按项目 README 中的说明安装。
工具
本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。
详细介绍
██████╗ ███████╗ ██████╗ ██╗ ██╗ ██╗ ██╔══██╗██╔════╝██╔═══██╗██║ ╚██╗ ██╔╝ ██████╔╝█████╗ ██║ ██║██║ ╚████╔╝ ██╔══██╗██╔══╝ ██║▄▄ ██║██║ ╚██╔╝ ██║ ██║███████╗╚██████╔╝███████╗██║ ╚═╝ ╚═╝╚══════╝ ╚══▀▀═╝ ╚══════╝╚═╝
专为 AI Agent 打造的 API 测试应用
在一个 Agent 会话中,从集合到 CI 测试,一气呵成。
纯 YAML · 本地优先 · MCP 服务 · CLI 和 Web UI · 自动捕获 · 流程 · REST · GraphQL · gRPC
安装 · 工作原理 · MCP 工具 · 流程 · 常见问题 · 版本发布
你的 Agent 会读取代码库、构建集合、编写断言、导出 GitHub Actions 工作流,并将其交付给 CI。你无需动手。
npm install -g getreqly
reqly setup

兼容: Cursor · Claude Code · Gemini CLI · VS Code(Claude 扩展)
完整的零人工参与流水线
/goal Read my Express routes, build a collection with assertions, write an
e2e flow for login → checkout, and export it to CI - don't stop until it's green.
1. "Read my Express routes and build a collection with assertions"
→ agent calls create_collection + create_request for every endpoint
2. "Write an e2e flow for the login → checkout path"
→ agent calls create_flow + add_flow_step, runs it, all green
3. "Export it to CI"
→ agent calls export_flow_ci
→ .github/workflows/checkout-flow.yml written automatically
→ installs Reqly, runs the flow, uploads JUnit results as a build artifact
在 Claude Code 中,/goal 可让 Agent 在一个会话中持续完成整个流水线,无需在每个步骤都重新输入提示词——Reqly 的 MCP 工具专为这种串联方式打造。
无需配置 bru run。无需手动编写 Actions YAML。无需设置环境。只需一个 Agent 会话,测试便会永远在 CI 中运行。
Reqly 作为后台服务在本地运行,并通过同一引擎提供两个界面:
- MCP 服务(stdio) - Agent 连接一次即可使用完整工具集。无需 UI,我们这边也不会产生 LLM 费用。
- 本地主机 Web UI - 打开
localhost:4242浏览集合、查看 Agent 的工作过程并手动发送请求。
集合以纯 YAML 文件形式存储在代码库中的 .reqly/ 目录下。原生支持 Git、便于人类阅读,Agent 也可直接写入。
目录
- 安装
- 工作原理
- MCP 工具
- CLI 运行器
- 流程
- AWS SigV4 身份验证
- 导出集合
- 模拟服务
- 捕获传入请求
- 集合和断言
- 效果证明
- 为何 Reqly 胜过 Postman、Insomnia 和 Bruno,适合 AI 原生开发者
- 近期发布
- 参与贡献
- 常见问题
- Star 历史
- 版本发布
实证(30 秒)
真实开发工作流中的时间节省:
| 任务 | 手动操作(Postman/Bruno) | Reqly + Agent | 节省时间 |
|---|---|---|---|
| 搭建 20 个 REST 端点 | 45 分钟 | 2 分钟 | 95% |
| 编写身份验证和校验测试 | 25 分钟 | 3 分钟 | 88% |
| 串联登录 → 结账流程 | 30 分钟 | 4 分钟 | 86% |
| 设置 CI 流水线(GitHub Actions) | 20 分钟 | 1 分钟 | 95% |
| 入职总耗时 | 120 分钟 | 10 分钟 | 91% |
Reqly 将 API 测试从繁琐的手动工作转变为快速的 Agent 驱动工作流。你的 Agent 编写 YAML、构建流程并导出 CI 配置——这一切都无需离开编辑器。
对于 AI 原生开发者,Reqly 为何胜过 Postman、Insomnia 和 Bruno(45 秒)
集合以纯 YAML 格式保存在你的仓库中。 其他所有工具都会将集合存储为专有格式或数据库(Insomnia 使用 NeDB 二进制文件,Postman 则要求通过云账户访问)。Reqly 的 .reqly/ 文件夹会通过 git 随代码一起管理——可读、可比较差异、可提交。AI Agent 无需调用任何工具,就能直接读取和编写集合文件。
Git 就是你的企业级 RBAC。 不必再为每位用户支付企业许可证费用,只为设置 API 集合的权限。由于 Reqly 集合是仓库中的文件,你会自动继承 Git 提供商的安全策略。使用分支保护和 CODEOWNERS 限制可编辑生产流程的人员。
Reqly 是 MCP 服务,而非 MCP 客户端。 Insomnia 最近添加了 MCP 客户端,因此可以调用外部工具。Reqly 更进一步:它本身就是 MCP 服务。你的 AI Agent 在 Cursor 或 Claude Code 中只需连接一次,就能获得一整套工具,用于发送请求、串联响应、运行集合和验证断言——无需 UI,也无需额外配置。桌面 UI(即将推出)只是同一无头引擎的外壳——无论窗口打开还是关闭,MCP 连接都会保持活跃。其他从 GUI 优先出发的工具只能事后才提取无头运行时;Reqly 从第一天起就是无头的。
自动捕获,无需手动操作。 Reqly 可以通过代理捕获开发服务器的出站流量(reqly exec npm run dev),通过一行中间件捕获入站流量,还可以通过公共隧道捕获入站 Webhook——然后自动将所有内容保存到集合中。没有其他工具能同时做到这三点。
不依赖云服务。 Reqly 没有云服务。集合保存在你的仓库中。密钥保存在你机器上的 ~/.reqly/config.json 中。不会向 Reqly 的服务器发送任何内容——因为 Reqly 根本没有服务器。无需账户、没有遥测,也没有同步。
让 PM 和 QA 也能轻松进行测试。 对非开发者来说,Postman 的 UI 令人望而生畏。使用 Reqly,非技术团队成员只需向 AI 提问:“运行结账流程,告诉我税额计算是否正确。” AI 会处理身份验证、格式转换和 JSON 负载,然后用通俗易懂的语言解释响应。无需开发者手把手指导。
Agent 会话示例(15 秒)
1. "Read my routes and build a collection" → agent calls create_collection + create_request for each endpoint
2. "Run the collection and check for failures" → agent calls run_collection, assertions pass/fail
3. "Write an e2e flow for the login → checkout path" → agent calls create_flow + add_flow_step, runs it
安装(45 秒)
Reqly 可在 macOS、Linux 和 Windows 上运行。有三种接入方式:
# 1. On any platform via npm (CLI + MCP server + web UI)
npm install -g getreqly
# 2. On macOS via Homebrew (CLI only)
brew tap RutvikPansare/reqly
brew install reqly
# 3. On macOS via Homebrew (Desktop App + CLI)
brew install --cask reqly
或者从 GitHub Releases 直接下载 DMG——无需 npm、Homebrew 或终端。桌面应用自带一份 Reqly 服务,因此完全独立运行。
**VS Code 扩展:**从 VS Code Marketplace 安装 reqly.reqly(适用于 Cursor、Windsurf 和所有兼容 VS Code 的编辑器)。它会在活动栏中提供集合树,在状态栏中提供环境切换器,提供 Reqly: 命令面板命令,在 JS/TS 的 fetch/axios/got 调用上方提供 “▶ Run with Reqly” CodeLens,并为所有 .reqly/ YAML 文件提供自动补全和架构验证。它连接到同一个本地服务,因此请先安装 Reqly 本身(上述三种方式任选其一)。
连接你的 AI Agent:
- **桌面应用用户:**首次启动时会出现设置向导(“Connect your AI Agent”),其中提供适用于 Claude Desktop、Cursor、Windsurf 和 VS Code 的一键按钮。每个按钮都会为你写入对应 Agent 的 MCP 配置——无需编辑 JSON。之后也可以随时从托盘菜单(“AI Agent Connections...”)重新打开。如果你已安装 CLI(通过 Homebrew 或 npm),向导会让 Agent 使用你的 CLI,这样
brew upgrade就能让它们保持最新;否则则使用捆绑的服务。 - **CLI 用户:**运行
reqly setup
这会一次性配置 Cursor、Claude Desktop、Claude Code、Gemini CLI 和 Codex。若只想配置特定工具:reqly setup cursor、reqly setup claude、reqly setup gemini。
重启你的 AI 工具,然后询问它:“列出我的 Reqly 集合”。
项目目录解析
Reqly 根据 4 级优先级链确定要操作的项目目录:
- 标志:
--project-dir(最高优先级) - 环境变量:`REQLY_PROJECT_DIR`
- **已保存的配置:**运行 `reqly use ` 设置的路径
- 当前目录:`process.cwd()`
按宿主类型设置:
- **基于 VS Code 的编辑器(Cursor、Windsurf):**这些编辑器支持动态宏插值。`reqly setup` 会将它们配置为传入 `--project-dir ${workspaceFolder}`,让 Reqly 动态跟随编辑器窗口中当前打开的项目。
- 独立宿主(Claude Desktop、Gemini CLI、Antigravity):这些工具会启动一个供所有项目共享的全局 MCP 服务进程,并且不支持宏插值。`reqly setup` 会完全省略该标志。对于这些工具,你必须在项目目录中运行 `reqly use `,告知全局 Reqly 进程要查看哪个项目。
30 秒快速体验
暂时无需 API 或设置 Agent。在任意目录中运行:
reqly init
reqly start
打开 localhost:4242——你就会得到一个可用的集合,它针对 JSONPlaceholder 配置好了请求链、变量、断言和流程。然后连接你的 Agent,让它扩展这个集合。
(注意:reqly init 会自动创建 .reqly/,并将其运行时状态文件添加到 .gitignore。)
使用你自己的 API 快速上手(60 秒)
无需捕获流量,也无需手动编写 YAML——只需让你的 Agent 阅读代码:
"Read my Express routes and build a Reqly collection for every endpoint"
Agent 会读取你的代码库,并为它找到的每个路由调用 create_collection 和 create_request。无需捕获流量——它已经能从代码中了解你的 API。
你的 Agent 可以做什么(45 秒)
Reqly 不是 AI——它是为你的 AI 提供支持的引擎。连接一次,你的 Agent 就能使用完整的工具集。 | | 能力 | 含义 | |---|---|---| | 🗂️ | 构建集合 | 读取你的路由并搭建请求,无需手动编写 YAML | | ⚡ | 发送并断言 | 发送请求,检查状态码/正文/延迟,并返回每项断言的通过/失败结果 | | 🔗 | 串联流程 | 支持提取、轮询和条件分支的多步骤序列 | | 📋 | 验证契约 | 指定 OpenAPI 规范,自动检查每个响应 | | 🎭 | 提供模拟服务 | 根据已保存的示例模拟后端,无需实时服务 | | 🕵️ | 捕获流量 | 代理出站流量、通过中间件处理入站流量,并为 Webhook 建立隧道 | | 📤 | 导出集合 | 生成 OpenAPI 规范、Postman 文件或 Markdown 文档 |
查看全部 30 多种 MCP 工具
📂 工作区和项目
| 工具 | 功能 |
|---|---|
get_project | 返回当前活动项目目录及其解析方式 |
switch_project | 在运行时切换活动项目目录 |
list_workspace_projects | 列出多项目工作区中的所有项目目录 |
add_workspace_project | 将项目目录添加到多项目工作区 |
remove_workspace_project | 从工作区中移除项目目录 |
create_workspace | 在 ~/.reqly/workspaces/<name>/workspace.yaml 创建具名工作区 |
link_workspace_repo | 将本地仓库链接到具名工作区,并使用稳定别名 |
use_workspace | 设置活动的具名工作区(持久化到 ~/.reqly/config.json) |
list_workspaces | 列出所有具名工作区及当前活动的工作区 |
🗂️ 集合和请求
| 工具 | 功能 |
|---|---|
list_collections | 列出项目中的所有集合和请求 |
create_collection | 搭建新集合 |
create_request | 添加请求。支持 {{variables}}、断言、前/后置脚本、脚本文件(preScriptFile/postScriptFile)、身份验证和 multipart 正文 |
run_request | 发送请求,返回状态码、正文、标头、延迟、断言结果、差异和契约违规情况 |
move_request | 将请求从一个集合移至另一个集合 |
run_collection | 按顺序发送集合中的所有请求 |
duplicate_collection | 复制整个集合 |
get_response | 获取上次保存的响应(已截断) |
get_response_full | 获取上次保存的完整响应 |
export_collection | 导出为 Postman v2.1、OpenAPI 3.0 JSON 或 Markdown API 文档 |
import_collection | 导入 Postman v2.1 或 Bruno 集合 |
🌍 环境和变量
| 工具 | 功能 |
|---|---|
set_environment | 更改活动环境 |
create_environment | 创建包含变量的具名环境 |
duplicate_environment | 复制现有环境 |
set_variable | 在环境中设置变量 |
get_variables | 列出环境变量(附带来源标签) |
delete_variable | 移除变量 |
get_collection_variables | 列出集合级变量 |
set_collection_variable | 设置集合级变量 |
delete_collection_variable | 删除集合级变量 |
set_dotenv_files | 配置自动加载的 .env 文件 |
get_dotenv_files | 列出已配置的 dotenv 文件 |
get_secret | 解析保险库密钥 URI(bw://project/secret),并返回截断的预览,绝不返回完整值 |
get_secret_status | 列出在 .env 中检测到的保险库 URI,并显示每个键的解析状态 |
configure_secret_provider | 将提供方凭据保存到 ~/.reqly/config.json,并重新解析 .env |
🔐 身份验证
| 工具 | 功能 |
|---|---|
get_collection_auth | 获取集合的默认认证配置 |
set_collection_auth | 为所有请求设置 Bearer / API Key / Basic / OAuth 2.0 / AWS SigV4(awsv4)认证 |
delete_collection_auth | 移除集合级认证 |
📋 OpenAPI 契约验证
| 工具 | 功能 |
|---|---|
set_collection_spec | 将集合关联到 OpenAPI 规范(文件路径或 URL) |
get_collection_spec | 获取规范配置和加载状态 |
delete_collection_spec | 从集合中移除规范 |
list_spec_operations | 列出已加载规范中的所有操作 |
validate_response | 重新验证上一个响应,无需重新发送请求 |
🔗 工作流
| 工具 | 功能 |
|---|---|
create_flow | 创建新的工作流 |
get_flow | 获取工作流的配置和步骤 |
list_flows | 列出所有工作流 |
delete_flow | 删除工作流 |
add_flow_step | 追加一个步骤(run / extract / assert / poll / conditional) |
update_flow_step | 原位替换一个步骤 |
delete_flow_step | 移除一个步骤 |
run_flow | 执行工作流并返回各步骤的结果 |
export_flow_ci | 生成 GitHub Actions 工作流并将其写入 .github/workflows/ |
🕵️ 捕获和代理
| 工具 | 功能 |
|---|---|
start_proxy | 自动将出站流量捕获到集合中 |
stop_proxy | 停止流量拦截 |
get_proxy_status | 报告代理是否正在运行、代理端口以及目标集合 |
exec_with_proxy | 启动代理并运行注入了代理的开发命令 |
install_middleware | 返回适用于你所用框架的入站流量捕获代码片段 |
🌐 GraphQL
| 工具 | 功能 |
|---|---|
introspect_graphql | 对 GraphQL 端点执行完整的架构内省;返回结构化的类型 / 字段 / 参数摘要;为 UI 缓存架构 |
⚡ gRPC
| 工具 | 功能 |
|---|---|
list_grpc_services | 从启用了反射的 gRPC 服务端发现服务(无需 .proto 文件);返回 { services: [{ name }], fileDescriptorCount } |
run_request 和 create_request 均原生支持 type: grpc。将 proto 文件放在 .reqly/protos/ 中。认证配置会自动注入到 gRPC Metadata 中。
- Markdown 文档导出 - 直接从集合生成精美的 Markdown API 参考文档
- 流程 - 多步骤自动化测试(运行、提取、断言、轮询、条件判断),支持数据驱动。在同一流程中串联 REST、GraphQL 和 gRPC 步骤。
- OpenAPI 契约验证 - 将集合关联到规范;自动检查每个响应
- 多部分请求正文编辑器 - 发送包含文件和文本部分的
multipart/form-data - 响应差异对比 - 检测两次运行之间的变化:状态、延迟差异、正文差异
- 模拟服务 - 将已保存的示例作为真正的 HTTP 服务提供,用于前端开发和 Agent 测试
- 前置/后置脚本 - 每个请求都可运行沙盒化 JS,在请求发送前后读写环境变量
- AWS Signature V4 身份验证 - 为 REST/GraphQL 计算并注入
Authorization+X-Amz-Date;为 AppSync、IoT Core 和 API Gateway WebSocket API 预签名 WebSocket URL。支持临时 STS 凭证(sessionToken)。 - gRPC 支持 - 功能全面,超越 BloomRPC:一元 RPC、服务端/客户端/双向流式传输、支持跨文件导入的 proto 文件加载、服务端反射(无需 .proto)、自动将身份验证配置注入 Metadata、通过
create_request自动生成 JSON 消息框架 - GraphQL 工作区 - 专用编辑器,包含 Headers 选项卡、完整的架构内省(带缓存)、Docs Explorer 侧边栏、已保存请求浏览器、operationName 多操作下拉菜单、支持外部
.graphql文件的queryFile、格式化、复制为 cURL、GraphQL 感知型响应查看器(data/errors/extensions 分区),以及通过 graphql-ws 实时订阅流 - cURL 导入 - 粘贴任意 cURL 命令;字段会立即填充
- TypeScript 接口生成器 - 根据任意 JSON 响应正文推断出带类型的 TS 接口
- .env 集成 - 零配置:如果项目根目录存在
.env,就会自动加载
流程(60 秒)
流程是由你的 Agent 一次构建、由 CI 永久运行的多步骤序列。每个步骤都会串联到下一步——从一个响应中提取值,并自动将其注入下一个请求。
flowchart LR
A(["▶ run\nFire a request"]) --> B(["⬇ extract\nPull value from response"])
B --> C(["✓ assert\nCheck the response"])
C --> D{"⎇ conditional\nBranch on result"}
D -->|"pass"| E(["▶ run\nNext request"])
D -->|"retry"| F(["↻ poll\nRepeat until condition met"])
F --> E
style A fill:#1e3a5f,stroke:#3b82f6,color:#e2e8f0
style B fill:#1e3a5f,stroke:#3b82f6,color:#e2e8f0
style C fill:#14532d,stroke:#22c55e,color:#e2e8f0
style D fill:#3b1f1f,stroke:#ef4444,color:#e2e8f0
style E fill:#1e3a5f,stroke:#3b82f6,color:#e2e8f0
style F fill:#3b2f0a,stroke:#f59e0b,color:#e2e8f0
示例:登录 → 创建帖子 → 验证帖子是否存在
# .reqly/flows/e2e-post.yaml
steps:
- type: run
request: auth/login
- type: extract
from: response.body.token
into: authToken # now available as {{authToken}}
- type: run
request: posts/create-post
- type: extract
from: response.body.id
into: postId
- type: assert
field: status
operator: eq
value: 201
- type: run
request: posts/get-post # uses {{postId}} in the URL
- type: assert
field: body
path: post.title
operator: eq
value: "Hello world"
运行:
reqly run-flow "e2e-post"
reqly run-flow "e2e-post" --reporter json
reqly run-flow "e2e-post" --data-row '{"userId":"42"}'
只需一条命令即可导出到 CI:
reqly export-flow "e2e-post" --format github-actions
# Writes .github/workflows/e2e-post.yml - installs Reqly, runs the flow, uploads JUnit results
Agent 也可以通过 export_flow_ci MCP 工具完成相同操作,无需手动编写 YAML。
AWS Signature Version 4(SigV4)身份验证
Reqly 内置支持对任意 AWS API 的请求签名:API Gateway、AppSync、Bedrock、S3、IoT Core 等。使用身份验证类型 awsv4。
REST 和 GraphQL - 标头签名
# Per-request auth in collection YAML
name: invoke-bedrock
method: POST
url: https://bedrock-runtime.us-east-1.amazonaws.com/model/anthropic.claude-v2/invoke
auth:
type: awsv4
credentials:
accessKey: "{{env.AWS_ACCESS_KEY_ID}}"
secretKey: "{{env.AWS_SECRET_ACCESS_KEY}}"
region: us-east-1
service: bedrock
sessionToken: "{{env.AWS_SESSION_TOKEN}}" # optional - for STS temporary creds
headers:
Content-Type: application/json
body: '{"prompt": "Hello from Reqly"}'
Reqly 会在发送前计算并注入以下标头:
Authorization: AWS4-HMAC-SHA256 Credential=AKID/date/region/service/aws4_request, SignedHeaders=..., Signature=...X-Amz-Date: 20260702T163930ZX-Amz-Security-Token: <token>(仅当设置了sessionToken时)
在集合级别设置,让每个请求都继承此配置——适用于整个 AWS API 集合:
"Set collection auth for my-bedrock-api to awsv4 with region us-east-1 and service bedrock"
你的 Agent 调用 set_collection_auth,并传入 type: "awsv4" 和凭证字段。该集合中的所有请求都会自动签名。
| 凭证字段 | 必填 | 示例 |
|---|---|---|
accessKey | 是 | AKIAIOSFODNN7EXAMPLE |
secretKey | 是 | wJalrXUtn... |
region | 是 | us-east-1、eu-west-1 |
service | 是 | execute-api、bedrock、s3、appsync、sts |
sessionToken | 否 | STS 会话令牌(临时凭证) |
WebSocket - URL 预签名(AppSync、IoT Core)
浏览器 WebSocket API 无法发送自定义标头。Reqly 会改为对连接 URL 进行预签名——将 X-Amz-Algorithm、X-Amz-Date、X-Amz-Credential 和 X-Amz-Signature 作为查询参数附加。始终保留 wss:// 协议。
通过 run_realtime MCP 工具:
{
"type": "websocket",
"url": "wss://abc123.appsync-realtime-api.us-east-1.amazonaws.com/graphql",
"awsAuth": {
"accessKey": "AKIAIOSFODNN7EXAMPLE",
"secretKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"region": "us-east-1",
"service": "appsync"
},
"captureTimeout": 5
}
最佳实践:使用环境变量
在 Reqly 中将凭据存储为环境变量,切勿将其硬编码到集合 YAML 中:
# In Reqly UI or via MCP set_environment
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtn...
AWS_REGION=us-east-1
AWS_SESSION_TOKEN=FQoGZXIv... # if using temporary creds
然后在请求身份验证块中使用 {{env.AWS_ACCESS_KEY_ID}} 引用。凭据会保留在环境配置中,不会提交到 git 中的 YAML 集合文件。
📤 导出集合(30 秒)
你永远不会被 Reqly 锁定。 由于集合是纯 YAML 文件,你始终拥有自己的数据。为了让迁移更加轻松,Reqly 内置了多种自由导出格式,可立即将集合迁移到其他工具、文档站点或 API 网关:
- 📮 Postman (
postman):导出标准的 Postman v2.1 JSON 文件。非常适合直接导入 Postman、Insomnia 或其他 HTTP 客户端。 - ⚙️ OpenAPI (
openapi):生成 OpenAPI 3.0 JSON 规范。非常适合 Swagger UI、生成客户端 SDK 或配置 API 网关。 - 📖 Markdown 文档 (
docs):生成精美的 Markdown (.md) API 参考文档,可直接提交到代码仓库、wiki 或静态站点生成器。
通过 CLI:
reqly export docs my-collection
reqly export docs my-collection --output docs/api/my-collection.md
通过 AI Agent:
只需向 Agent 提出请求即可。它们可以通过调用 export_collection MCP 工具自动导出你的 API:
"Export my 'users' collection to a Postman file so I can share it with the frontend team."
捕获入站请求(中间件)(45 秒)
如果代码库过于复杂或缺少文档,无法使用 AI 编写集合的工作流,请安装 reqly-middleware,自动捕获每个进入应用的请求:
npm install reqly-middleware
// Express
import { reqlyMiddleware } from 'reqly-middleware'
app.use(reqlyMiddleware())
// Next.js (middleware.ts at project root)
import { reqlyNextMiddleware } from 'reqly-middleware/next'
export default reqlyNextMiddleware()
// Fastify
import { reqlyMiddlewareHook } from 'reqly-middleware'
fastify.addHook('onRequest', reqlyMiddlewareHook())
重启开发服务器后,Reqly 就会开始将入站请求捕获到 Captured 集合中。仅用于本地开发——它会连接到 localhost:4242,在生产环境中不会产生任何影响。让你的 Agent 调用 install_middleware,即可获取适用于你的框架的准确代码片段。
集合的工作方式(30 秒)
集合以易读的 YAML 文件形式存储在项目目录中的 .reqly/ 下。它们支持变量、身份验证配置和测试断言。
请求 YAML 示例:
name: create-user
method: POST
url: "{{baseUrl}}/api/users"
headers:
Content-Type: application/json
body:
email: [email protected]
assertions:
- field: status
operator: eq
value: 201
- field: body
path: user.id
operator: neq
value: ""
断言(45 秒)
每次执行请求后都会自动运行断言。每个断言检查一项内容:
| 属性 | 值 | 说明 |
|---|---|---|
field | status | body | latency | 必填。 使用 field,不要使用 type。 |
operator | eq | neq | contains | lt | gt | 必填。 |
value | string、number 或 boolean | 必填。 预期值。 |
path | 点号表示法字符串 | 当 field 为 body 时必填。JSON 正文中的路径,例如 user.id 或 data.items.0.name。 |
常见错误: 写成 type: "status" 而不是 field: "status"——这会悄无声息地产生一个永远不匹配的断言,并始终报错“got undefined”。
示例:
assertions:
- field: status # HTTP status code
operator: eq
value: 200
- field: body # JSON body field at path
path: user.active
operator: eq
value: true
- field: latency # response time in ms
operator: lt
value: 2000
CLI 运行器(45 秒)
你可以在终端或 CI/CD 流水线中使用 Reqly 运行测试套件。
reqly run users
支持以下报告器格式和环境:
reqly run users --env prod --reporter json
reqly run users --reporter tap
reqly run users --reporter junit > results.xml
--reporter junit 会将标准的 JUnit XML <testsuite>/<testcase> 文档写入 stdout——将其重定向到文件,供 CI 获取。请求中的每个断言都会成为一个 <testcase>;没有断言的请求会成为一个隐式测试用例,只有当其状态码 >= 500 时才会失败。
运行流程
reqly run-flow "Login Flow"
reqly run-flow "Login Flow" --reporter json
reqly run-flow "Login Flow" --reporter tap
reqly run-flow "Login Flow" --reporter junit > results.xml
reqly run-flow "Signup Flow" --data-row '{"email":"[email protected]"}'
将流程导出到 CI
reqly export-flow "Login Flow" --format github-actions
会写入 .github/workflows/Login Flow.yml(如果需要会创建目录),该文件会安装并启动 Reqly,使用 --reporter junit > results.xml 运行流程,并在推送和拉取请求时将 results.xml 作为构建产物上传。如果流程需要调用本地 API,请在“Run flow”之前添加一个“Start server”步骤。
希望你的 Agent 按计划重新检查 API,而不是只在推送时检查?在 Claude Code 中:
/schedule every morning at 9am, run reqly run-flow "Login Flow" --reporter junit and tell me if anything broke
模拟服务
将已保存的示例响应作为真正的 HTTP 服务提供,这样前端代码或 Agent 就能针对受控响应发起请求,而无需连接实际后端:
reqly mock <collection> # default port 4243
reqly mock <collection> --port 5000
工作区管理
你可以将 Reqly 配置为同时从多个项目目录加载集合。这非常适合微服务或单体仓库场景,例如同时打开多个相关 API。
reqly workspace add <absolute_path> # Adds a project to your workspace
reqly workspace remove <absolute_path> # Removes it
reqly workspace list # Lists all configured projects and named workspaces
对于微服务团队,还有一种命名工作区模型:工作区会将稳定的仓库别名(由团队成员共享)映射到本机路径,并存储在 ~/.reqly/workspaces/<name>/workspace.yaml 中(永远不会提交到任何仓库)。
reqly workspace create checkout-team # scaffold the workspace
reqly workspace link checkout-team auth /repos/auth-svc # alias "auth" -> local path
reqly workspace link checkout-team payments /repos/pay-svc
reqly workspace use checkout-team # set active workspace
Agent 也可以通过 create_workspace、link_workspace_repo、use_workspace 和 list_workspaces MCP 工具执行相同操作;界面还在项目列表上方提供了工作区下拉菜单。别名是跨仓库工作流的基础(接下来将支持在工作流步骤中使用 repo: auth)。
启动时,Reqly 会打印所有活动路由的表格(方法、路径、示例数量)。按 Ctrl+C 停止。
若要为每个请求选择特定示例,请设置 X-Reqly-Example: <name> 请求头。如果未设置,则会提供第一个已保存的示例。
模拟服务器还会在主服务(端口 4242)上提供 REST 路由,以供界面和程序化控制:
POST /api/mock/start { collection, port? }
POST /api/mock/stop
GET /api/mock/status
参与贡献(60 秒)
Reqly 是一款为 AI Agent 打造的开源执行引擎。我们欢迎你参与各个方面的贡献!
你可以如何提供帮助
- 引擎与协议: 添加新的身份验证类型(Digest、NTLM),或为 JS 脚本沙箱扩展更多内置辅助库(例如模拟数据生成)。
- MCP 工具集: 在
src/mcp/tools/中编写新工具(例如用于 Swagger 2.0 或 Insomnia 的导入器),为 Agent 提供更多能力。 - 界面与完善: 改进 React 前端(
src/ui/),添加主题、优化语法高亮,或修复界面问题。
核心架构原则:工具优先
每项能力都必须先实现为工具。 如果无法通过 MCP 调用,就不算一项功能。界面只是围绕相同工具构建的可视化封装——它绝不会拥有 MCP 接口不具备的能力。将 AI 逻辑留在引擎之外;Reqly 是供智能 Agent 使用的简洁执行层。
本地设置
git clone https://github.com/RutvikPansare/Reqly.git
cd Reqly
npm install
npm run dev
测试规范
我们使用 Vitest(npm test)。引擎逻辑(src/engine/)和 MCP 工具契约(src/mcp/)要求严格采用 TDD,覆盖率达到 100%。 界面交互采用灵活的测试方式。提交 PR 前,请确保所有测试均通过。
常见问题
使用 Reqly 需要 AI Agent 吗?
不需要。`localhost:4242` 上的本地界面可以独立运行——你可以创建集合、发送请求、检查响应,全程无需 Agent。MCP 接口是额外提供的:连接后,Agent 就能通过工具获得相同的能力。你也可以同时使用两者。
这和 Postman 或 Insomnia 有什么区别?
主要有三点:
- 集合是仓库中的 YAML 文件,不会锁定在云账户或专有二进制格式中。它们通过 git 与代码一同管理,Agent 可以直接读取和写入,你也可以在 PR 中查看差异。
- Reqly 是一款 MCP 服务。你的 AI Agent 可以连接到它并使用完整的工具集——发送请求、运行工作流、验证契约——而无需打开界面。Postman 和 Insomnia 以界面为先;Reqly 则以 Agent 为先。
- 绝不依赖云服务。 无需账户,无需同步,也没有遥测。所有内容都在你的机器上运行。
这和 Bruno 有什么区别?
Bruno 是最接近的对比对象——它同样是本地的、基于文件的,并且与 git 原生集成。主要区别在于 Agent 接口。Bruno 没有 MCP 服务;你的 Agent 无法调用 Bruno 工具来发送请求或以编程方式构建集合。Reqly 从第一天起就以 AI Agent 为主要用户进行设计,界面则是查看同一引擎的次要入口。
Reqly 会向云端发送任何数据吗?
不会。Reqly 是本地进程。集合保存在你仓库中的
.reqly/ 目录下。你的 API 密钥保存在本机的 ~/.reqly/config.json 中。所有请求都不会经过 Reqly 的服务器,因为 Reqly 根本没有服务器。
不使用 Cursor 或 Claude Code 也能使用 Reqly 吗?
可以。任何兼容 MCP 的客户端都能使用:Cursor、Claude Code、Claude Desktop、Gemini CLI、Codex,或任何支持 MCP stdio 传输的工具。如果你的 Agent 尚不支持 MCP,仍可使用 CLI(
reqly run、reqly run-flow)和 localhost UI,无需使用任何 Agent。
macOS 提示桌面应用“无法打开,因为无法验证开发者”——这样安全吗?
安全。目前 Reqly 桌面应用尚未签名(我们还没有 Apple Developer 账户)——这是 macOS Gatekeeper 对任何未签名应用的标准警告,并不表示应用有问题。右键点击应用,选择 打开,然后在对话框中选择 仍要打开。每台设备只需执行一次。通过 Homebrew cask 安装则完全不会出现此警告。
运行安装程序时,Windows SmartScreen 提示“未知发布者”——这样安全吗?
安全。目前安装程序尚未签名(我们还没有 EV 证书)——这是 SmartScreen 对任何新的、下载量较低的安装程序发出的标准警告。点击 更多信息,然后点击 仍要运行。安装程序积累足够的下载信誉后,警告便会自动消失。即使尚未获得 SmartScreen 信任,二进制文件仍使用 Sigstore/cosign 签名,以便检测篡改。
桌面窗口变成空白/黑屏了。发生了什么?
应用会自动恢复:渲染进程崩溃后会自动重新加载;服务器连接中断时会显示“正在启动 Reqly...”画面,并在服务器响应后立即重新连接;服务器进程退出后,内置看门狗会重新启动它。如果你看到持续显示的错误画面,请检查
~/.reqly/desktop.log——每次崩溃、加载失败和服务器重启都会带时间戳记录在其中。提交问题时请附上该文件。
桌面应用需要安装 CLI 吗?
不需要。从 T-233 开始,桌面应用会自带一份 Reqly 服务,并使用应用自身的运行时运行——无需安装 Node、npm 或 Homebrew。如果你确实安装了 CLI(通过 Homebrew 或 npm),应用会自动优先使用它(优先级:Homebrew CLI,然后是 PATH 中的 npm CLI,最后是捆绑的服务),因此你的 Agent 会继续使用
brew upgrade/npm update -g 安装的版本。设置向导中的“安装 CLI”可选按钮会将捆绑的服务符号链接到 /usr/local/bin/reqly,供终端使用。
我的 Agent 在错误的目录中查找集合。该怎么办?
当你的 AI 工具从项目目录以外的工作目录启动 Reqly 进程时,就会发生这种情况。你可以通过以下任一方式解决:
- Cursor/大多数编辑器——在项目目录中再次运行
reqly setup cursor。设置命令会将${workspaceFolder}写入 MCP 配置,以便 Cursor 在启动时传入正确的路径。 - Claude Desktop——运行
reqly use /path/to/your/project,全局设置当前项目,然后重启 Claude Desktop。 - 手动覆盖——在 AI 工具的配置中,为 MCP 服务条目设置
REQLY_PROJECT_DIR环境变量。
我可以在没有 AI Agent 的情况下于 CI 中使用 Reqly 吗?
可以,这正是
reqly run 和 reqly run-flow 的用途。你的 Agent 在本地构建并维护集合;CI 只负责执行。使用 --reporter junit 可生成 JUnit XML 输出,GitHub Actions、GitLab CI 和 Jenkins 都能原生解析并生成测试仪表板。
reqly run my-collection --reporter junit > results.xml
或者自动生成完整的 GitHub Actions 工作流:
reqly export-flow "my-flow" --format github-actions
中间件会在生产环境中捕获请求吗?
不会,这是有意设计的。
reqly-middleware 会连接到 localhost:4242,如果 Reqly 未运行,就会静默地什么也不做。在没有 Reqly 的生产环境中,它绝不会捕获流量,也不会缓冲或延迟请求(发送后不等待响应,并吞掉错误)。
Reqly 支持哪些身份验证类型?
Bearer 令牌、API Key(请求头或查询参数)、Basic 身份验证、带 PKCE 的 OAuth 2.0、mTLS(客户端证书),以及适用于 AWS API(API Gateway、AppSync、Bedrock、S3、IoT Core)的AWS Signature Version 4。身份验证可以在集合级别设置(应用于所有请求),也可以按请求覆盖。你的 Agent 可以通过
set_collection_auth MCP 工具配置身份验证,无需手动编辑 YAML。对于 AWS SigV4,传入 type: "awsv4",并提供 accessKey、secretKey、region 和 service 凭据。
我可以导入现有的 Postman 或 Bruno 集合吗?
可以。Reqly 开箱即支持导入 Postman v2.1 集合和 Bruno 集合:
reqly import postman-collection.json
reqly import bruno-collection/
也可以通过 MCP 工具导入:你的 Agent 可以调用 import_collection 并传入文件路径。如果需要反向转换,Reqly 也支持导出为 Postman v2.1 和 OpenAPI 3.0。
环境变量如何工作?
Reqly 有三个变量层,按以下顺序解析:
- .env 文件——从项目根目录自动加载(也可以通过
set_dotenv_files配置) - 环境变量——存储在
.reqly/environments.yaml中的命名集合,例如dev、staging、prod - 集合变量——作用域限定为单个集合,适用于
baseUrl等值
在 URL、请求头或请求体中的任意位置使用 {{varName}}。通过 reqly run --env prod 或 UI 下拉菜单切换环境。
Reqly 支持 GraphQL 吗?
支持。UI 提供专用的 GraphQL 工作区,包含架构内省、语法高亮和变量面板。GraphQL 请求与 REST 请求一样存储在集合中,你的 Agent 可以通过相同的 MCP 工具创建并运行这些请求。
我可以在团队中使用 Reqly 吗?如何共享集合?
集合是项目仓库中
.reqly/ 目录里的纯 YAML 文件。共享只需使用 git——提交该目录,团队中的每个人就都能获得相同的集合。无需账号、工作区邀请或云同步。密钥和 API Key 会保存在每位开发者本机的 ~/.reqly/config.json 中,绝不会提交到仓库。
Reqly 需要什么版本的 Node.js?
Node.js 18 或更高版本。Reqly 使用原生
fetch、ES 模块和 MCP SDK,这些都要求 Node 18 及以上版本。使用 node --version 查看你的版本。
端口 4242 已被占用。我可以更改端口吗?
可以。启动时传入
--port:
reqly start --port 4243
前置/后置脚本如何工作?
每个请求都可以配置
preScript 和 postScript——在请求发送前后运行的小型沙盒 JavaScript 代码片段。它们可以访问 reqly 对象,并通过其中的方法读写环境变量:
// preScript - set a dynamic header before the request
reqly.setEnvVar('timestamp', Date.now().toString())
// postScript - extract a value from the response into an env var
const token = reqly.response.body.access_token
reqly.setEnvVar('authToken', token)
// You can also use reqly.setVar(key, val) / reqly.getVar(key) to store collection-scoped variables in memory
脚本在隔离环境中运行,无法访问文件系统或网络,只能与 Reqly 的变量存储和响应对象交互。
对于较长的脚本,请改用 preScriptFile / postScriptFile——将值设为相对于集合文件夹的路径(例如 "scripts/post.js")。Reqly 会在运行时读取文件,因此你可以直接编辑文件,无需修改 YAML。无需进行 JSON 转义。
// create_request({ postScriptFile: "scripts/post.js", ... })
// then edit .reqly/<collection>/scripts/post.js freely
如何停止 Reqly?
reqly stop # stops the running instance
reqly status # check if an instance is running and which project it's on
reqly app # opens the running instance's UI in your browser
或者,在运行 Reqly 的终端中按 Ctrl+C。Reqly 会在 ~/.reqly/running.json 写入锁定文件以跟踪运行中的实例——reqly stop 会读取该文件以找到进程并向其发送信号。
不重启就能切换项目吗?
可以。如果 Reqly 实例已经在运行,在另一个项目目录中启动新实例,就能热切换当前项目,无需重启服务:
cd /path/to/other-project
reqly start
# "Switched active project to /path/to/other-project"
新进程会将控制权交给现有实例,然后退出。MCP 连接会保持活动状态,并立即看到新项目的集合。
有办法测试 Webhook 吗?
可以——使用隧道命令将本地服务暴露到互联网,并捕获传入的 Webhook 负载:
reqly exec --tunnel npm run dev
此命令会启动开发服务并提供一个公开的 HTTPS URL。发送到该 URL 的任何请求都会被代理到本地服务,并自动保存到 Captured 集合中。
Star 历史
如果 Reqly 为你节省了时间,点个 Star 就能帮助其他 AI 原生开发者发现它。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。