Orchid 实战教程：用零插桩代理给 AI Agent 装上一台网络流量时间机器

调试 AI Agent 的痛苦每个开发者都经历过——LLM 调用藏在一层层框架后面，工具调用结果不明确，每次失败都要 grep 日志来回翻。如果能让你的 AI Agent 拥有”时间旅行”能力，在完成运行后逐帧回放每一笔网络请求，问题定位会不会简单得多？

本文将介绍 Orchid（Apache-2.0, GitHub 4⭐）——一个本地优先、零插桩的 AI Agent 网络流量录制与回放工具。它通过轻量级代理拦截 Agent 的 HTTP 流量，记录每一次 LLM 调用和工具请求，并提供 Web 可视化界面和内置 MCP 服务器让 AI 编程助手直接查询记录。

为什么需要 Orchid？

传统 LLM 可观测方案通常需要：

• 侵入式 SDK：包裹每一个 LLM 客户端初始化，修改代码路径
• 外部 SaaS 平台：数据上传到云端，有隐私合规风险
• 日志文件分析：全靠事后 grep，效率低下

Orchid 的方案完全不同——它采用 APM 风格的 Thin SDK，在 HTTP 传输层打补丁（Python 的 httpx/requests，Node 的 fetch），所有 LLM 调用自动路由至本地代理，无需修改任何业务代码。所有数据留在本地 SQLite 数据库中，永不离开你的基础设施。

快速上手：5 分钟搭建 Orchid

0. 拉取代理镜像

Orchid 以 Docker 容器形式分发：

docker pull ghcr.io/mario-guerra/orchid-proxy:latest

1. 生成 API 密钥

docker run --rm ghcr.io/mario-guerra/orchid-proxy:latest generate-api-key

2. 启动代理

docker run -d \
  --name orchid-proxy \
  -p 4320:4320 \
  -p 4321:4321 \
  -v orchid-data:/data \
  -e ORCHID_API_KEY=your-generated-key \
  -e ORCHID_DB_PATH=/data/orchid.db \
  ghcr.io/mario-guerra/orchid-proxy:latest

启动后：

• 录制代理端口 4320：所有 HTTP 请求通过这里被捕获
• 查询/可视化端口 4321：Web UI 和 REST API 入口

⚠️ 在 Docker 中运行时必须设置 ORCHID_API_KEY，否则代理会拒绝启动。健康检查和静态资源不需要密钥，但所有数据 API 均需认证。

3. 将应用指向代理

Orchid 提供两种方式来路由流量到代理：

方案 A：使用 Thin SDK（推荐）

安装 SDK 后在应用最前面初始化：

Python：

pip install orchid-sdk

import orchid

orchid.init()

from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

TypeScript/Node：

npm install orchid-sdk

import { init } from "orchid-sdk";

// 必须在初始化任何 LLM 客户端前调用
await init();

// 之后所有 LLM 调用自动被记录

方案 B：原生 Base URL 路由（无需 SDK）

如果不使用 SDK，直接修改 LLM 客户端的 base_url：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4320/v1",
    default_headers={
        "X-Orchid-Api-Key": "your-generated-key"
    }
)

三种录制模式

Orchid 的代理是头部驱动状态机，通过 HTTP 头部 X-Orchid-Mode 控制每种请求的处理方式：

使用 SDK 控制模式

orchid.init(mode="capture")

with orchid.session("bug-fix-session", mode="capture"):
    agent.run()  # 这个会话里的 LLM 调用全部被记录

使用 HTTP 头部控制

response = requests.post(
    "http://localhost:4320/v1/chat/completions",
    headers={
        "X-Orchid-Mode": "capture",
        "X-Orchid-Session-Id": "feature-x-test",
        "X-Orchid-Api-Key": "your-key"
    },
    json={"model": "gpt-4", "messages": [...]}
)

会话管理：按功能、测试或用户组织追踪

Orchid 的会话 ID 解析优先级从高到低：

1. 全局覆盖（MCP set_active_session 工具或 POST /sessions/active API）
2. SDK 作用域（orchid.session("my-test", mode="capture") 代码块）
3. HTTP 头部（X-Orchid-Session-Id）
4. 环境变量（ORCHID_SESSION_ID）
5. 代理默认值（默认 "default-session"）

这让你可以在同一个代理上同时处理多个不同场景的记录，互不干扰。

配置模型定价

要跟踪 LLM 调用的费用，需要向代理注册定价表。发送 POST 请求到查询端口的 /v1/pricing：

curl -X POST http://localhost:4321/v1/pricing \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-key" \
  -d '{
    "openai": {
      "gpt-4o": {
        "prompt": 2.50,
        "completion": 10.00
      },
      "o3-mini": {
        "prompt": 1.10,
        "completion": 4.40
      }
    },
    "anthropic": {
      "claude-sonnet-4-6": {
        "prompt": 3.00,
        "completion": 15.00
      }
    }
  }'

定价以 每 100 万 token 的美金 为单位。更新定价后，可以用 POST /v1/pricing/recompute 回填之前记录的会话费用。

AI 编程助手直接查询（MCP 集成）

Orchid 内置 MCP 服务器，让 Cursor、VS Code 或 Claude Code 直接查询记录的流量：

{
  "mcpServers": {
    "orchid-local": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "orchid-proxy",
        "orchid-proxy",
        "--mcp"
      ]
    }
  }
}

配置后，你可以直接问你的 AI 编程助手：”刚才那次运行为什么失败了？帮我查一下 LLM 调用的 token 消耗和前 3 次工具调用的结果。”——它会调用 Orchid 的 MCP 工具直接查询 SQLite 数据库，返回精确的记录。

离线回放测试：零成本 CI

Orchid 最具特色的功能是确定性回放：

1. 先用 capture 模式运行测试套件，生成 JSON fixture
2. 将 fixture 提交到代码仓库
3. CI 中使用 replay 模式——阻断所有外网调用，从本地录制文件返回精确匹配的响应

docker run --rm ghcr.io/mario-guerra/orchid-proxy:latest generate-api-key
python -m pytest tests/ -s

curl -X POST http://localhost:4321/api/sessions/import \
  -H "Authorization: Bearer your-key" \
  -F "file=@test-fixture.json"
python -m pytest tests/ -s

因为回放从不调用真实 API，测试瞬间完成且费用为零。同时它隔离了网络波动，让你获得可复现的基准测试结果。

实战：调试一个 RAG Agent

来看一个实际场景——你的 RAG Agent 在回答某个问题时给出了错误答案，你需要找出原因：

1. 打开可视化面板：访问 http://localhost:4321，输入 API 密钥
2. 浏览会话：找到包含问题提问的会话记录
3. 检查 LLM 调用：看系统提示词是否准确、用户问题是否正确传入
4. 查看检索结果：检查向量数据库返回的上下文是否包含了正确的文档
5. 分析 token 消耗：对比不同会话的 token 使用量，发现是否有过长上下文被注入

Orchid 的 MCP 集成让整个过程更流畅——你的 AI 编程助手可以直接理解并诊断这些记录，帮你指出”第 3 次 LLM 调用的系统提示词中缺少了过滤指令”。

总结

Orchid 为 AI Agent 开发者提供了一个本地优先、零侵入、可回放的网络调试方案。相比传统日志分析或云端可观测平台，它的核心优势在于：

• 数据隐私：一切留在本地 SQLite，不上传任何数据
• 零侵入接入：Thin SDK 在传输层打补丁，无需改业务代码
• 确定性回放：录制一次，无限次离线回放，适合 CI 和基准测试
• MCP 集成：AI 编程助手可以直接查询和分析记录
• 内置可视化：Web 面板无需额外安装

如果你正在构建复杂的 AI Agent 应用，特别是在多模型、多工具调用的场景下，Orchid 能让你从”盲人摸象”式的日志调试中解脱出来——给你的 Agent 装上一台真正的”网络流量时间机器”。

相关链接

• Orchid 官网
• GitHub 仓库
• Orchid LangGraph 示例
• Python SDK (PyPI)
• TypeScript SDK (NPM)
• 定价参考：OpenAI 定价 | Anthropic 定价