Orchid 完全指南：零侵入式 AI Agent 网络流量记录、调试与回放
调试 AI Agent 一直是开发者的痛点——LLM 调用藏在框架、队列和多层抽象之后，每次都要靠打印日志、手动 curl 测试、或者盯着 OpenAI 的 dashboard 猜问题。Orchid 用一个零侵入式代理解决了这个问题：它记录 Agent 的所有网络请求（LLM 调用、工具调用、外部 API），然后让你像看录像一样回放、检查、调试。
架构：零侵入代理 + 本地存储
Orchid 的核心是一个透明 HTTP 代理（orchid-proxy），运行在 Docker 容器中。Agent 的所有出站流量经过这个代理时，会被自动记录到本地的 SQLite 数据库。代理本身暴露三个端口功能：
- 4320（代理端口）：接收 Agent 的 HTTP 请求，转发到上游 API
- 4321（查询/UI/MCP 端口）：提供 Web 可视化面板、REST API 和 MCP 服务端
数据全程保存在你本地——SQLite 数据库文件保留在 Docker 挂载卷中，Authorization 头等敏感信息在写入磁盘前自动替换为 [REDACTED]，不上传任何数据到云端。
安装与快速启动
前提条件
- Docker（运行
orchid-proxy容器） - Python 3.9+ 或 Node.js 18+（根据你的项目语言选择 SDK）
第一步：拉取代理镜像
docker pull ghcr.io/mario-guerra/orchid-proxy:latest
第二步：生成 API Key
docker run --rm ghcr.io/mario-guerra/orchid-proxy:latest generate-api-key
第三步：启动代理
docker run -d \ --name orchid-proxy \ -p 4320:4320 \ -p 4321:4321 \ -v orchid-data:/data \ -e ORCHID_API_KEY=orchid-api-key \ -e ORCHID_DB_PATH=/data/orchid.db \ ghcr.io/mario-guerra/orchid-proxy:latest
核心功能详解
1. 三种流量处理模式
Orchid 代理通过 HTTP 请求头中的 X-Orchid-Mode（或 SDK 中的 mode 参数）控制对每个请求的处理方式：
| 模式 | 行为 | 适用场景 |
|---|---|---|
passthrough | 透明转发，不写入磁盘 | 生产环境不想记录流量 |
capture | 转发请求 + 将完整请求/响应写入 SQLite | 开发调试、测试录制 |
replay | 阻止所有出站流量，从 SQLite 返回已录制的响应 | CI 测试、离线调试 |
在 replay 模式下，代理会计算请求的哈希值并与数据库中的记录匹配。如果找不到匹配项，返回一个确定的模拟错误。
2. Thin SDK：一行代码接入
Orchid 通过底层 HTTP 传输层打补丁的方式实现无侵入集成——不需要修改 LLM 客户端的初始化代码。
Python 项目：
import orchid orchid.init()
orchid.init() 会自动 patch httpx 和 requests 的传输层，将后续所有 HTTP 请求路由到 localhost:4320 的代理。只需 pip install orchid-sdk。
TypeScript/Node.js 项目：
import { init } from "orchid-sdk";
// 必须在初始化任何 LLM 客户端之前调用
await init();
npm install orchid-sdk。
3. 会话管理（Session）
默认所有请求归到 "default-session" 下。你可以用以下方式组织不同测试运行的记录（按优先级从高到低）：
- SDK 上下文作用域：
with orchid.session("test-run-v2", mode="capture"): - HTTP 头：
X-Orchid-Session-Id: test-run-v2 - 环境变量：
ORCHID_SESSION_ID=test-run-v2
4. Web 可视化面板
启动代理后打开 http://localhost:4321，输入 API Key 即可进入可视化面板。支持：
- 按模型、供应商、状态、关键词搜索过滤
- 查看每次 Exchange 的完整 Prompt、Token 用量、延迟和费用
- 跨会话对比 Token 消耗和成本
- 导出会话为 JSON 快照文件
5. MCP 服务端集成
Orchid 代理内置了 MCP 服务端（运行在 4321 端口的 SSE 端点），可以让 Cursor、VS Code 或 Claude Code 直接查询已记录的流量。
配置方式（在 IDE 的 mcp_config.json 中添加）：
{
"mcpServers": {
"orchid-local": {
"command": "docker",
"args": ["exec", "-i", "orchid-proxy", "orchid-proxy", "--mcp"]
}
}
}
配置后，你可以在 IDE 中直接问 AI 助手：「刚才那次运行为什么失败了？」——助手通过 MCP 工具查询 Orchid 数据库中的记录，找出问题并修复。
6. 模型定价配置
为了跟踪成本，需要向代理注册模型定价信息。可以通过 REST API 推送：
curl -X POST http://localhost:4321/v1/pricing \
-H "Content-Type: application/json" \
-H "Authorization: Bearer orchid-api-key" \
-d '{
"google": {
"gemini-2.5-flash": {"prompt": 0.30, "completion": 2.50}
},
"openai": {
"o3-mini": {"prompt": 1.10, "completion": 4.40}
},
"anthropic": {
"claude-sonnet-4-6": {"prompt": 3.00, "completion": 15.00}
}
}'
也可以通过 MCP 工具的 update_pricing 方法配置。更新后可用 POST /v1/pricing/recompute 回溯历史会话的成本数据。
7. 确定性回放测试
这是 Orchid 最有价值的能力——录制一次，在 CI 中离线回放：
- 录制阶段：在
capture模式下运行测试套件，生成 JSON 快照 - 提交快照：将快照文件提交到仓库
- CI 回放：在 CI 中启动代理（
replay模式），加载快照，运行测试
回放模式下测试执行速度极快（响应来自本地 SQLite，零网络延迟），且不消耗任何 API 费用。还适合做性能基准测试——去掉网络延迟后，可以准确测量 Agent 自身逻辑的性能。
常见问题（FAQ）
Q: Orchid 和 LangSmith / LangFuse 有什么区别？
A: Orchid 是本地优先的流量回放调试工具，数据完全保留在你的基础设施内。LangSmith 等是托管的 LLM 可观测性平台，强调多云协作和 Dashboard 共享。Orchid 的核心差异在于零代码入侵（通过代理拦截而非 SDK wrap）和确定性离线回放能力。
Q: 数据安全怎么保证？
A: 代理启动时生成的 API Key 保护所有数据接口。Authorization 头在写入磁盘前被替换为 [REDACTED]。不过注意，Prompt 文本本身会被完整记录——如果 Prompt 中粘贴了密钥，它也会被存储。
Q: 支持哪些协议？
A: Python 侧自动 patch httpx 和 requests 传输层；TypeScript 侧 patch fetch。如果使用其他语言（Go、Java、Ruby），可以直接修改 LLM 客户端的 base_url 为 http://localhost:4320/v1 并传入 X-Orchid-Api-Key 头。
Q: 需要修改已有代码吗？
A：如果使用 Thin SDK（推荐），只需在入口处加一行 orchid.init()。也可以通过配置 LLM 客户端 base_url 的方式零 SDK 集成。
总结
Orchid 解决了 AI Agent 开发中一个长期存在的痛点——当 LLM 调用深埋在多层抽象后面时，如何高效调试。它的零侵入代理 + 本地 SQLite + MCP 集成三件套，让开发者无需修改代码就能获得完整的网络流量记录和回放能力。对于需要确定性测试和离线调试的 AI Agent 项目，Orchid 是一个实用且优雅的解决方案。
相关链接：