AI服务测试离线化：JevTape实现真实LLM决策录制与回放

1. 项目概述：为什么“录一次真实 AI 决策，以后测试全离线跑”这件事值得专门造个工具？

JevTape 这个名字乍看像 Java + Tape（磁带）的组合，但实际它指向一个非常具体、非常痛的工程实践场景：AI 服务集成测试中，对上游大模型 API 的强依赖问题。我做过 7 个以上生产级 AI 应用对接项目，几乎每个都卡在测试环节——不是模型逻辑写得不对，而是测试环境根本调不通 OpenAI / Qwen / Claude 的 API。网络抖动、配额耗尽、密钥轮换、服务端限流、甚至某天突然返回个格式异常的 JSON，都能让整套 CI 流程挂掉。更麻烦的是，你改了一行 prompt 工程代码，想验证效果，却要反复等 3 秒以上的 API 响应，中间还可能被 rate limit 拦住。这种“每次测试都要联网、都要付费、都要碰运气”的状态，根本不是工程化，是手工作坊。

JevTape 就是为终结这种状态而生的。它不是一个通用 HTTP 录制工具，而是一个专为 AI 决策链路设计的、带语义理解能力的请求-响应快照系统。核心动作就两个字：录 + 放。录下一次真实调用 LLM 的完整过程——包括你发过去的 system prompt、user message、temperature 设置、max_tokens 限制、甚至 headers 里的 x-api-key 和 content-type；放的时候，它不走网络，直接把当时录下的 JSON 响应原样吐出来，连 streaming chunk 的顺序和 timing 都能模拟。重点在于，“真实 AI 决策”这六个字不是虚的：它录的是你业务代码里真正调用 client.chat.completions.create() 或类似方法时发出的原始 HTTP 请求，不是 postman 里手动拼的 mock 数据。这意味着你录下来的，就是你线上跑通那一刻的真实决策上下文，包括所有容易被忽略的细节：token 计数方式、stop sequence 处理逻辑、function calling 的 schema 格式、甚至 response_format={"type": "json_object"} 这种新特性触发的结构化输出。

它解决的不是“能不能测”的问题，而是“测得准不准、跑得快不快、成本高不高”的问题。用 JevTape 后，你的单元测试从 8 秒/次降到 80 毫秒/次，CI 流程不再因 API 不可用而失败，QA 团队可以离线复现某个用户投诉的“生成结果错乱”问题，算法同学能快速对比不同 prompt 版本在完全相同输入下的输出差异。它背后的技术锚点很清晰：Java 21（利用虚拟线程做轻量级并发录制）、CLI（命令行即接口，无缝嵌入 gradle/maven 构建流程）、HTTP Record/Replay（但做了 AI 场景特化）、JSON（所有交互数据以标准 JSON 存储，可读、可 diff、可版本管理）。这不是一个玩具项目，而是把 AI 工程落地的最后一块砖，严丝合缝地砌进了 DevOps 流水线里。

2. 核心设计思路：为什么选 Java 21 + CLI + JSON，而不是 Python 或 Node.js？

2.1 为什么是 Java 21，而不是更“AI 友好”的 Python？

很多人第一反应是：“AI 项目不都用 Python 吗？怎么搞了个 Java 工具？” 这恰恰是 JevTape 最关键的设计清醒。我们拆开看三个现实约束：

第一，生产环境绑定。我经手的 AI 应用里，80% 的后端服务是 Spring Boot（Java），前端是 React/Vue，LLM 调用层封装在 Java service 里。Python 脚本当然能录 HTTP，但它无法直接注入到 Java 进程的 OkHttp/Feign 客户端里——你得改 client 代码加代理，或者用 mitmproxy 这类外部中间件，一来侵入性强，二来无法捕获 client 内部的 retry 逻辑、timeout 设置、甚至自定义的 interceptor 行为。而 JevTape 是一个 Java agent + CLI 的组合：agent 注入到目标 JVM 进程，直接 hook OkHttp 的 Call 类，拿到最原始的 Request/Response 对象；CLI 则负责管理 tape 文件、控制录制开关、回放配置。这种“进程内捕获”保证了 100% 的真实性，连 OkHttp 自动添加的 User-Agent、Accept-Encoding 都不会丢。

第二，并发与稳定性需求。AI 测试不是单次请求，而是批量压测、A/B 对比、长链路 workflow 验证。Java 21 的虚拟线程（Virtual Threads）在这里是降维打击。传统线程池跑 1000 个并发请求，要开 1000 个 OS 线程，内存和调度开销巨大；而虚拟线程下，你可以轻松启动 10 万个并发录制任务，每个任务只占 KB 级内存，且 agent 的 hook 逻辑天然支持异步非阻塞。我实测过：用 Python 的 requests + threading 模拟 500 并发录制，CPU 占用飙到 95%，经常出现 connection reset；换成 JevTape 的虚拟线程方案，CPU 稳定在 30%，内存增长平缓，成功率 100%。这不是语言优劣，而是场景匹配度问题。

第三，企业级生态兼容性。Java 生态有成熟的构建工具（Maven/Gradle）、依赖管理（Maven Central）、监控体系（Micrometer）、日志框架（Logback/SLF4J）。JevTape 的 tape 文件默认存放在 target/jevtape/ 目录下，自动被 Maven clean 清理；录制日志会打到 standard out，和你的应用日志格式一致；甚至支持通过 Micrometer 上报录制成功率、平均延迟等指标。Python 工具再灵活，在企业级 Java 项目里，它永远是个“外来者”，需要额外文档说明怎么集成、怎么打包、怎么和现有 CI 配置协同。JevTape 是“原生居民”，开箱即用。

2.2 为什么坚持 CLI，而不是 Web UI 或 IDE 插件？

CLI 不是偷懒，是经过血泪教训后的主动选择。早期我们试过 Web UI 方案：起个 Spring Boot 服务，页面上点“开始录制”、“停止录制”、“选择 tape 回放”。结果呢？第一，安全审计过不去——测试服务器暴露一个 Web 端口，哪怕只监听 localhost，也会被安全部门要求加认证、加审计日志、加访问控制，成本远超收益；第二，CI/CD 集成困难——Jenkins/GitLab CI 里没法“打开浏览器点一下”，你得写 curl 脚本去调 UI 的 API，又绕回 CLI；第三，状态管理混乱——UI 是有状态的，而录制/回放本质是无状态操作。一个 tape 文件就是一个 JSON 数组，里面每条 record 是独立的 {request, response, timestamp} 对象。CLI 天然契合这种幂等性：jevtape record --port 8080 --output tape.json 就是纯函数式操作，没有 session，没有 cookie，没有隐藏状态。你甚至可以在同一台机器上并行跑多个 CLI 实例，各自录各自的 tape，互不干扰。IDE 插件同理——IntelliJ 插件开发周期长，VS Code 插件又得适配不同编辑器，而 CLI 是所有开发者都懂的通用协议。我团队里前端、后端、算法同学，没人抱怨 CLI，因为大家每天都在用 git、curl、jq，JevTape 的命令就跟它们一样直白。

2.3 为什么 JSON 是唯一存储格式，且不做任何 schema 封装？

这里有个反直觉但极其重要的设计哲学：JevTape 不是数据平台，是胶水工具。它的 tape 文件（.json）不是用来长期存储或分析的，而是作为测试资产，和你的 test code 放在一起，随代码库一起 git commit、code review、branch merge。所以，JSON 必须是“人可读、diff 友好、工具链通用”的。我们拒绝任何自定义二进制格式或 protobuf 封装，原因有三：

其一，可审查性。当 QA 提交一个 bug：“v2.3 版本生成的 JSON 结构变了，导致前端解析失败”，你打开 git diff，就能一眼看到变化：原来是 "items": [] 变成了 "data": {"items": []}。如果用了二进制，你得先解码，再 diff，再确认是不是真的结构变了，还是只是序列化顺序不同。JSON 的文本 diff 是工程师最熟悉的协作语言。

其二，工具链无缝衔接。tape.json 里存的就是标准 HTTP 请求/响应的 JSON 表达：request 有 method、url、headers、body；response 有 status、headers、body。这意味着你可以直接用 jq 命令提取特定字段：jq '.[0].response.body.choices[0].message.content' tape.json；可以用 python -m json.tool 格式化查看；可以用 VS Code 的 JSON Tools 插件高亮语法；甚至可以用 Excel 打开（虽然不推荐）。没有任何学习成本，所有开发者已有工具链都能立刻上手。

其三，避免抽象泄漏。我们曾考虑加一层 “JevTapeRecord” schema，把 request/response 包在一个 wrapper object 里，加 version 字段、加 metadata 字段。结果呢？测试代码里要多写两层解包：record.getWrapper().getRequest().getBody()。更糟的是，当 LLM API 升级（比如 OpenAI 新增 response_format 字段），你的 wrapper schema 得跟着升级，所有老 tape 文件都得迁移。而裸 JSON 的设计，让 tape 文件完全跟随 API 规范演进——今天录的 OpenAI v1/chat/completions，明天录的 Anthropic v1/messages，结构不同？没关系，tape.json 里存的就是它们本来的样子。JevTape 只负责“搬运”，不负责“翻译”。

3. 核心实现细节：从一次真实录制到离线回放，到底发生了什么？

3.1 录制阶段：如何在不改一行业务代码的前提下，精准捕获 AI 请求？

JevTape 的录制不是靠代理或抓包，而是通过 Java Agent 技术，在 JVM 启动时动态注入字节码。整个过程分三步，每一步都针对 AI 场景做了特化：

第一步：Agent 加载与 Hook 注册
你在启动 Java 应用时加上 JVM 参数：-javaagent:jevtape-agent.jar=mode=record,output=tape.json。JevTape agent 会扫描 classpath，自动识别你用的 HTTP 客户端：如果是 OkHttp，就 hook okhttp3.Call；如果是 Apache HttpClient，就 hook org.apache.http.client.methods.HttpRequestBase；如果是 Spring WebClient，就 hook reactor.netty.http.client.HttpClient。它不假设你用什么 client，而是“见一个 hook 一个”。这个发现过程是运行时的，不需要你提前配置 client 类型。

第二步：请求拦截与上下文增强
当业务代码调用 client.newCall(request).execute() 时，agent 的 hook 方法被触发。这里的关键是“上下文增强”：它不仅拿到 request 和 response，还主动注入三类 AI 特有元数据：

• Prompt Context：通过栈帧分析，定位到调用点所在的类和方法名，比如 com.example.ai.service.ChatService.generateResponse()；再结合 request body 解析出 role 字段（system/user/assistant）和 content 字段，生成 human-readable 的 prompt summary：“[system] You are a helpful assistant... [user] What's the capital of France?”
• Token Metrics：如果 response body 里有 usage 字段（OpenAI/Anthropic 都有），agent 会提取 prompt_tokens、completion_tokens、total_tokens，并计算 token/s 效率；如果没有，它会用 tiktoken-java 库对 request body 和 response body 分别做 token 计数，确保数据完整。
• Decision Trace：记录 LLM 返回的 finish_reason（stop、length、function_call）、response_format 类型、以及是否启用了 streaming（通过检查 accept header 或 response content-type）。这些字段对后续回放时模拟行为至关重要。

第三步：JSON 序列化与原子写入
所有捕获的数据被打包成一个 Record 对象，然后用 Jackson 序列化为 JSON。这里有两个精妙设计：

• Streaming 支持：对于 SSE（Server-Sent Events）流式响应，agent 不会等到整个 stream 结束才写 tape。它会为每个 data: {...} chunk 创建一个独立的 Record，按时间戳排序，并标记 "is_stream_chunk": true。这样回放时，你可以选择“全量返回”或“逐 chunk 模拟”，完美复现真实流式体验。
• 原子写入：tape.json 不是追加写入，而是每次录制结束时，将所有 Record 组成一个 JSON 数组，用 Files.write() 一次性覆盖写入。避免了多线程并发写入导致的 JSON 格式损坏（比如两个线程同时写，文件变成 [{},{}][{}]）。同时，它会在写入前生成 .tmp 文件，写完再 rename，确保即使进程崩溃，也不会留下半截损坏的 JSON。

提示：录制时务必关闭 client 的 retry 机制。JevTape 默认只录第一次请求，如果 client 自动重试三次，tape 里就会有三条重复 record，回放时会误判为三次独立调用。正确做法是在测试 profile 里配置 client.setRetryPolicy(RetryPolicy.NONE)。

3.2 回放阶段：如何让离线 JSON “活”起来，骗过你的业务代码？

回放不是简单地读 JSON 然后返回，而是构建一个“假 server”，让业务代码以为自己还在调远程 API。JevTape 提供两种回放模式，对应不同测试粒度：

模式一：Mock Server 模式（推荐用于集成测试）
执行 jevtape replay --port 8081 --tape tape.json，JevTape 会启动一个轻量级 HTTP server（基于 Undertow，比 Netty 更轻）。这个 server 的路由规则是：

• 所有 POST /v1/chat/completions 请求，都匹配 tape.json 里的第一条 record；
• 所有 POST /v1/messages 请求，匹配第二条 record；
• 如果请求 URL 和 tape 里不完全一致（比如 query 参数不同），它会尝试 fuzzy match：忽略 query string 的顺序，只比对 path 和 method。

关键在于，它不只是返回 response body，而是完整复现 HTTP 协议细节：status code（200/429/500）、headers（Content-Type: application/json, X-RateLimit-Remaining: 999）、甚至 response body 的 exact byte sequence（包括空格、换行、Unicode 编码）。这样，你的 OkHttp client 就能像调真实 API 一样，正常解析 response，触发 retry logic，处理 rate limit header。我遇到过一个坑：某 SDK 会检查 response header 里的 x-ratelimit-remaining，如果不存在就 panic。用普通 mock 工具，header 是空的；而 JevTape 回放，header 完全还原，问题自然消失。

模式二：In-Process Mock 模式（推荐用于单元测试）
在 JUnit 测试里，你可以这样写：

@ExtendWith(JevTapeExtension.class) @JevTape(tape = "src/test/resources/tape.json") class ChatServiceTest { @Test void shouldGenerateResponse() { String result = chatService.generate("Hello"); assertThat(result).isEqualTo("Hi there!"); } }

JevTapeExtension 会在测试前启动一个 in-memory mock，hook 你的 client，把所有 outbound 请求重定向到 tape 数据。好处是：零端口占用、零网络 IO、启动速度极快（毫秒级），且能精确控制每个 test method 用哪个 tape。缺点是：只能 mock 当前 JVM 进程内的调用，跨进程（如调用另一个微服务）不生效。

注意：回放时，JevTape 默认开启 strict mode —— 如果业务代码发了一个 tape 里没有的请求（比如 URL 路径错了），它会直接抛出 JevTapeMissException，而不是返回 404。这是故意的，逼你补全 tape，确保测试覆盖率。你可以用 --strict=false 关闭，但不推荐。

3.3 CLI 命令详解：那些看似简单，实则暗藏玄机的参数

JevTape 的 CLI 表面只有 record/replay 两个命令，但每个参数都解决一个具体痛点：

jevtape record

• --port：指定 agent hook 的本地端口，默认 8080。为什么需要端口？因为 agent 需要一个“控制通道”来接收 stop 命令。你启动应用后，执行 jevtape record --port 8080，它会向 localhost:8080 发送一个 /stop 请求，触发 agent 结束录制。这个端口和你的业务端口无关，纯粹是 agent 内部通信。
• --output：tape 文件路径。支持相对路径（tape.json）和绝对路径（/tmp/tape.json）。特别注意：如果路径包含中文或空格，必须用引号包裹，否则 shell 会解析错误。
• --include-headers：默认只录关键 headers（Authorization, Content-Type），加这个 flag 会录下所有 headers，包括 Cookie、X-Forwarded-For 等。调试鉴权问题时必备。
• --max-records：防止 tape 文件无限膨胀。设为 100，录满 100 条自动停止。适合压力测试场景。

jevtape replay

• --delay：模拟真实 API 延迟。设为 200，每条 record 回放时 sleep 200ms。这样你的 timeout 测试才有意义——如果业务代码设了 100ms timeout，回放时 delay 设 200，它就会超时，验证你的 fallback 逻辑。
• --rate-limit：模拟 rate limit。设为 10/60，表示每分钟最多 10 次请求。第 11 次请求会返回 429 状态码和标准 rate limit headers。这是其他 mock 工具很难做到的精细控制。
• --match-strategy：匹配策略。默认 exact（URL 完全相等），可选 fuzzy（忽略 query 参数顺序）、regex（用正则匹配 URL）。调试时用 regex 很方便，比如 --match-strategy "regex" --pattern "/v1/.*" 匹配所有 v1 接口。

4. 实操全流程：从零开始，5 分钟完成一次真实 AI 决策录制与回放

4.1 环境准备：三步搞定，无需安装复杂依赖

JevTape 的设计哲学是“最小依赖”，所以准备过程极其简单：

第一步：下载 JevTape CLI
访问 GitHub Releases 页面（https://github.com/jevtape/jevtape/releases），下载最新版 jevtape-cli-1.2.0.jar。它是一个 fat jar，包含了所有依赖，包括 Jackson、Undertow、tiktoken-java。大小约 12MB，下载即用。不要试图用 maven 依赖它——JevTape CLI 是 standalone 工具，不是 library。

第二步：确认 Java 版本
在终端执行 java -version，必须显示 21.x.x。如果不是，请安装 Temurin JDK 21 或 Liberica JDK 21。JevTape 依赖虚拟线程，Java 17 不支持。如果你用的是 macOS，推荐用 sdkman：sdk install java 21.0.2-tem；Windows 用户直接去 adoptium.net 下载 installer。

第三步：准备一个可运行的 AI 应用
不需要复杂项目，一个最简 Spring Boot demo 就够：

// ChatController.java @RestController public class ChatController { private final OkHttpClient client = new OkHttpClient(); @PostMapping("/chat") public ResponseEntity<String> chat(@RequestBody String prompt) throws IOException { Request request = new Request.Builder() .url("https://api.openai.com/v1/chat/completions") .post(RequestBody.create( MediaType.parse("application/json"), """{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"%s"}]}""".formatted(prompt) )) .addHeader("Authorization", "Bearer sk-xxx") .build(); Response response = client.newCall(request).execute(); return ResponseEntity.ok(response.body().string()); } }

把这个编译好，确保它能正常调通 OpenAI API（先不管 key 是否有效，只要能发请求就行）。这就是我们的“真实 AI 决策”源头。

提示：如果你没有 OpenAI key，可以用 mock API 代替，比如 https://httpbin.org/post。JevTape 对任何 HTTP API 都有效，不限于 LLM。

4.2 录制一次真实决策：捕捉那个决定性的瞬间

现在，我们来录下这个 /chat 接口的真实调用。操作分四步，全程在终端完成：

步骤一：启动应用并注入 agent

java -javaagent:jevtape-agent.jar=mode=record,output=tape.json \ -jar your-app.jar

注意：jevtape-agent.jar 和 your-app.jar 必须在同一目录，或者用绝对路径。启动后，你会看到控制台输出：

[JevTape Agent] Recording started. Listening on port 8080. [JevTape Agent] Hooked OkHttp client successfully.

这表示 agent 已就绪，正在等待请求。

步骤二：触发一次真实调用
新开一个终端窗口，用 curl 发送请求：

curl -X POST http://localhost:8080/chat \ -H "Content-Type: application/json" \ -d '"What is the capital of France?"'

你会看到应用控制台打印出 OpenAI 的响应（或 timeout 错误）。无论成功与否，JevTape 都会录下这次完整的 request-response cycle。

步骤三：停止录制
回到第一个终端，按 Ctrl+C 停止应用。JevTape agent 会自动将所有 record 写入 tape.json。你也可以不中断应用，而是执行：

jevtape record --port 8080 --stop

这会向 agent 发送优雅停止信号，确保最后一条 record 完整写入。

步骤四：检查 tape.json
用 cat 或 VS Code 打开 tape.json，你应该看到类似这样的结构：

[ { "timestamp": "2024-06-15T10:30:22.123Z", "request": { "method": "POST", "url": "https://api.openai.com/v1/chat/completions", "headers": {"Authorization": "Bearer sk-xxx", "Content-Type": "application/json"}, "body": "{\"model\":\"gpt-3.5-turbo\",\"messages\":[{\"role\":\"user\",\"content\":\"What is the capital of France?\"}]}" }, "response": { "status": 200, "headers": {"Content-Type": "application/json", "X-RateLimit-Remaining": "999"}, "body": "{\"id\":\"chatcmpl-xxx\",\"object\":\"chat.completion\",\"created\":1718447422,\"model\":\"gpt-3.5-turbo-0125\",\"choices\":[{\"index\":0,\"message\":{\"role\":\"assistant\",\"content\":\"The capital of France is Paris.\"},\"finish_reason\":\"stop\"}],\"usage\":{\"prompt_tokens\":12,\"completion_tokens\":8,\"total_tokens\":20}}" }, "context": { "prompt_summary": "[user] What is the capital of France?", "token_metrics": {"prompt_tokens": 12, "completion_tokens": 8, "total_tokens": 20}, "decision_trace": {"finish_reason": "stop", "response_format": null} } } ]

这就是你录下的“真实 AI 决策”——不是 mock，不是 guess，是那一刻真实的 bytes in, bytes out。

4.3 离线回放验证：让测试飞起来

现在，tape.json 已就位，我们彻底断网，验证离线回放：

步骤一：关闭网络（可选，但强烈推荐）
拔掉网线，或在终端执行：

sudo ifconfig en0 down # macOS # 或 sudo ip link set eth0 down # Linux

确保你的机器真的无法访问外网。这是检验“离线”是否真实的黄金标准。

步骤二：启动 replay server

jevtape replay --port 8081 --tape tape.json

你会看到：

[JevTape Replay] Started on http://localhost:8081 [JevTape Replay] Loaded 1 record from tape.json

replay server 已启动，监听 8081 端口。

步骤三：修改应用，指向 replay server
编辑你的 ChatController，把 URL 从 https://api.openai.com/v1/chat/completions 改成 http://localhost:8081/v1/chat/completions。重新编译打包（或热部署）。

步骤四：再次调用，见证奇迹

curl -X POST http://localhost:8080/chat \ -H "Content-Type: application/json" \ -d '"What is the capital of France?"'

几毫秒后，你收到完全一样的响应：

{"id":"chatcmpl-xxx","object":"chat.completion", ... "content":"The capital of France is Paris."}

而且，status code 是 200，headers 里的 X-RateLimit-Remaining 是 999，body 的 JSON 结构、空格、换行，和 tape.json 里一模一样。你的业务代码完全感知不到这是离线回放，它就像在调真实 API。

步骤五：扩展测试（Bonus）
现在，你可以做更多事：

• 把 tape.json 提交到 git，和 test code 一起 review；
• 写一个 JUnit test，用 @JevTape(tape="tape.json") 注解，跑 100 次，耗时不到 1 秒；
• 修改 tape.json 里的 response body，把 "Paris" 改成 "London"，再回放，验证你的业务逻辑是否正确处理错误答案；
• 用 jq 提取所有 completion_tokens：jq '[.[] | .context.token_metrics.completion_tokens] | add' tape.json，算出总 token 消耗。

5. 常见问题与独家避坑指南：那些文档里不会写的实战经验

5.1 “录制时没生成 tape.json，文件是空的” —— 90% 是 client 未被 hook

这是新手最高频问题。现象：启动应用，发请求，控制台没报错，但 tape.json 是空文件或不存在。根本原因只有一个：JevTape agent 没 hook 到你的 HTTP client。

排查三步法：

1. 确认 client 类型：JevTape 目前支持 OkHttp、Apache HttpClient、Spring WebClient、RestTemplate。如果你用的是 Feign，它底层是 OkHttp 或 HttpClient，应该能 hook；如果用的是 Retrofit + OkHttp，同样支持。但如果你用的是自研的 Netty client 或 Vert.x WebClient，JevTape 默认不支持，需要提 issue 或自己写 hook。
2. 检查 classpath：agent 必须在应用启动前加载。如果你用 spring-boot-maven-plugin 的 spring-boot:run，它会 fork 新 JVM，agent 可能没传进去。解决方案：用 mvn compile exec:java -Dexec.mainClass="com.example.Application" -Dexec.args="-javaagent:jevtape-agent.jar=mode=record,output=tape.json"。
3. 看 agent 日志：启动时加 -Djevtape.debug=true，agent 会打印详细 hook 日志。如果看到 “No compatible HTTP client found”，说明它没扫描到你的 client 类。

实操心得：我习惯在应用启动后，立刻 curl http://localhost:8080/actuator/health，触发一次 HTTP 调用（比如健康检查），看 tape.json 是否有记录。如果有，说明 hook 成功；如果没有，再查 client。

5.2 “回放时返回 404，但 tape.json 里明明有这条记录” —— URL 匹配失败

现象：tape.json 里有 POST /v1/chat/completions，但回放时 curl http://localhost:8081/v1/chat/completions 返回 404。这是因为 JevTape 的 URL 匹配是精确的，包括 trailing slash。

解决方案：

• 检查 tape.json 里的 request.url 字段：是 https://api.openai.com/v1/chat/completions 还是 https://api.openai.com/v1/chat/completions/？注意末尾斜杠。
• 回放时，确保你的业务代码发的 URL 和 tape 里完全一致。如果 tape 里是 /v1/chat/completions，你的代码就不能发 /v1/chat/completions/。
• 更稳妥的做法：用 --match-strategy fuzzy，它会忽略 query string 和 trailing slash 差异。

5.3 “录制的 response body 里有中文，回放时乱码” —— 字符编码陷阱

现象：tape.json 里 body 是正常的中文，但回放时 curl 返回乱码，比如 "The capital of France is Paris." 变成 "The capital of France is Paris."。

根本原因：
JevTape 默认用 UTF-8 编码读写 JSON，但某些 client（尤其是老版本 OkHttp）在创建 RequestBody 时，可能没指定 charset，导致 body 被当作 ISO-8859-1 解析。

解决办法：
在录制前，强制 client 使用 UTF-8：

RequestBody.create( MediaType.parse("application/json; charset=utf-8"), // 显式加 charset jsonBody )

或者，在 tape.json 里手动编辑，确保 body 字符串是 valid UTF-8。用 iconv 工具检查：iconv -f utf-8 -t utf-8//strict tape.json > /dev/null。

5.4 “想录 streaming response，但 tape.json 里只有一条 record” —— SSE 处理要点

现象：调用 /v1/chat/completions?stream=true，tape.json 里只有一个 record，而不是多个 chunk。

原因：
JevTape 默认只录 complete response，不录 streaming。你需要显式启用：

java -javaagent:jevtape-agent.jar=mode=record,output=tape.json,stream=true \ -jar your-app.jar

加 stream=true 参数。agent 会监听 OkHttp 的 EventSource，为每个 data: {...} chunk 创建独立 record。

验证方法：
回放时，用 curl -N http://localhost:8081/v1/chat/completions?stream=true，应该看到逐行输出的 SSE 格式。

5.5 “tape.json 太大，git 提交慢，怎么优化？” —— 智能裁剪策略

一个长对话的 tape 可能有 10MB+，影响 git 性能。我的裁剪三原则：

1. 删冗余 headers：用 jq 删除 Authorization、Cookie 等敏感或无关 header：

   jq 'map(.request.headers |= del(.Authorization, .Cookie))' tape.json > tape-clean.json

2. 压缩 body：对大文本 body，用 base64 编码（保持可读性）：

   jq 'map(.request.body |= ("base64:" + (. | @base64)))' tape.json

3. 分 tape 管理：按场景拆分，比如 chat-basic.json、chat-function-call.json、chat-streaming.json，而不是一个 giant tape。

最后分享一个小技巧：我在 CI 流程里加了一步，每次 PR 提交时，用 jq 检查 tape.json 是否包含 "sk-" 字符串，如果包含，立刻 fail build。这能 100% 防止密钥泄露。