#mooncassette

#为什么需要它

开发阶段   真实调用 ──▶ 录制 ──▶ demo.cassette.json ──▶ 提交进版本控制
测试 / CI  无网络   ──▶ 回放 ──▶ 逐字节一致的结果，零密钥

#安装

moon add weopqrst/mooncassette

import {
  "weopqrst/mooncassette",
  "weopqrst/mooncassette/core",
  "weopqrst/mooncassette/providers",
}

#30 秒上手

moon run examples/offline_demo --target js     # 录制 → 落盘 → 回放 → 漂移检测
moon run examples/openai_protocol --target js  # 真实 provider 报文 → 录制 → 离线回放
moon run examples/streaming_demo --target js   # SSE 流式 → 逐帧递给应用 → 离线逐帧回放
moon run cmd/main --target js -- verify examples/demo.cassette.json
moon run cmd/main --target js -- show   examples/demo.cassette.json
moon run cmd/main --target js -- diff   examples/demo.cassette.json examples/demo.drifted.cassette.json
moon test --target wasm-gc

#核心保证（不变量）

1. 回放模式绝不发起真实调用。 Mode::Playback 的会话在构造上就不持有 Transport，因此「不小心打到线上」在类型层面被排除。
2. 落盘内容一定经过脱敏，而真实调用一定保留密钥。 同一次业务请求被派生为 两个形态：发给 provider 的保留密钥（否则鉴权会失败），写入 cassette 的已脱敏。 录制与回放两侧走同一条派生链，否则会出现「录得进去、回放不出来」。
3. 规范文本是确定的。 对象键按 UTF-8 字节序排序，与 Map 迭代顺序无关， 因此同一份 cassette 在任何后端、任何运行下都产出相同字节。
4. 指纹跨目标稳定。 不使用标准库 Hasher（其实现与后端相关）， 而是自实现 FNV-1a 64 位，并用官方测试向量校验。
5. 指纹相同 ≠ 请求相同。 指纹只用于索引；最终判据是规范文本全等。 一旦检出真实碰撞会显式报错，而不是静默返回错误结果。
6. 文件被手工改动一定会被发现 —— 包括响应。 cassette 里保存了两个不同 覆盖范围的摘要，解码时都会重算比对（详见下文「两个摘要」）。
7. Interaction 完全确定。 时间戳等非确定字段只允许出现在 CassetteMeta， 从类型结构上杜绝「测试随机挂掉」。

#快速上手

#1. 定义你的 Transport

///|
struct MyHttpTransport {
  client : MyHttpClient
}

///|
fn MyHttpTransport::send(
  self : MyHttpTransport,
  request : @core.Request,
) -> @core.Response raise @core.CassetteError {
  let response = self.client.post(request.model, request.body) catch {
    error => raise @core.CassetteError::TransportFailure(error.to_string())
  }
  @core.Response::ok(response.body, usage=response.usage)
}

#2. 开发时：自动录制

let session = @mooncassette.auto_session(
  @core.Cassette::new("chat-demo"),
  MyHttpTransport::new(client),
)
let _ = session.send(request)
// 把结果写入 tests/cassettes/chat-demo.cassette.json 并提交进版本控制
@fs.write_string_to_file(path, @mooncassette.save(session))

#3. 测试时：只读回放

///|
test "chat returns the recorded answer" {
  let session = @mooncassette.replay_session(recorded_text)
  let response = session.send(request)
  assert_eq(response.body, Json::string("录下来的答案"))
}

#接入真实 provider

• 各家的路径与鉴权头差异；
• usage 字段命名差异（OpenAI 是 prompt_tokens，Anthropic 是 input_tokens）；
• 错误响应也要能录下来——否则「限流时怎么办」没法写回归测试；
• 网关返回 HTML 错误页时不会把响应体丢掉，而是包成 {"raw_body": "…"}；
• 报文体中若显式写了 model，必须与 Request.model 一致，否则直接报错 （这类静默不一致会同时污染指纹与计费口径，很难排查）。

#你需要实现的只有「发出去」这一步

///|
let sender = @providers.FunctionSender::new(fn(request) {
  MyClient::call(request) // (HttpRequest) -> HttpResponse raise CassetteError
})

///|
let transport = @providers.ProviderTransport::new(
  @providers.OpenAiChat::new(api_key, base_url="https://api.deepseek.com/v1"),
  sender,
)

///|
let session = @mooncassette.auto_session(@core.Cassette::new("chat"), transport)

#关于异步 HTTP 客户端（重要）

///|
// 命中就回放，未命中就发一次并录下来。
let response = match session.try_replay(request) {
  Some(recorded) => recorded
  None => {
    let http_request = protocol.encode(request) // 同步
    let http_response = my_client.send(http_request) // ← 只有这一步需要 await
    session.record(request, protocol.decode(http_response)) // 同步
  }
}

#接入你自己的 HTTP 客户端

#自定义协议：实现 Protocol

///|
pub impl @providers.Protocol for MyProtocol with fn name(_self) {
  "my-vendor"
}

///|
pub impl @providers.Protocol for MyProtocol with fn encode(self, request) {
  @providers.HttpRequest::new(
    "POST",
    self.base_url + "/v1/complete",
    [("content-type", "application/json")],
    @canon.to_canonical_string(request.body),
  )
}

///|
pub impl @providers.Protocol for MyProtocol with fn decode(_self, response) {
  // 自己解析报文。`usage` 尽量填 provider 上报的真实值：
  // 回放、成本与漂移检测都读它；不填仍能回放，但「精确」那一半就没了。
  @core.Response::new(response.status, @json.parse(response.body))
}

///|
let transport = @providers.ProviderTransport::new(
  MyProtocol::new("https://api.my-vendor.com"),
  @providers.FunctionSender::new(fn(request) { MyClient::call(request) }),
)

#接完先自证：ScriptedHttpSender

///|
test "my protocol sends what I think it sends" {
  let sender = @providers.ScriptedHttpSender::new()
  sender.on(
    @providers.HttpRequest::new(
      "POST",
      "https://api.my-vendor.com/v1/complete",
      [("content-type", "application/json")],
      expected_body,
    ),
    @providers.HttpResponse::new(200, "{\"text\":\"hi\"}"),
  )
  let transport = @providers.ProviderTransport::new(
    MyProtocol::new("https://api.my-vendor.com"),
    sender,
  )
  let response = transport.send(request)
  assert_eq(response.status, 200)
  assert_eq(sender.call_count(), 1)
}

#量化指标

• 一条记录约 815 字节（紧凑编码）；
• 紧凑编码比 2 空格缩进省 46%；
• 每条记录的开销从 10 条到 1000 条保持稳定，说明增长是线性的。

#精确，而不是估算

moon run cmd/main --target js -- tokens <你的 cassette.json>

#接入 CI

1. 开发时录制。 用 Auto 模式跑一遍（命中就回放，未命中就真实调用并记下）， 把 tests/cassettes/ 下的文件提交进仓库；
2. 测试里回放。 加载 cassette 时自动完成完整性校验，不需要额外的检查步骤；
3. CI 里 moon test。 不需要 API Key，也不访问网络。

tests/
  cassettes/
    chat.cassette.json
    streaming.cassette.json

- name: Set up MoonBit
  run: |
    curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash
    echo "$HOME/.moon/bin" >> $GITHUB_PATH

- name: Replay recorded LLM interactions (no network, no API key)
  run: moon test --target js

///|
test "chat completes without a network" {
  let text = @fs.read_file_to_string("tests/cassettes/chat.json")
  let session = @mooncassette.replay_session(text)
  let response = session.send(my_request()) catch {
    error => fail("replay failed: " + error.to_string())
  }
  assert_eq(response.status, 200)
}

• 篡改会被挡在加载这一步。 cassette 里存了两个摘要（请求指纹 + 整条记录的摘要）， 手工改动任何一个字段，replay_session 就会在解码时报错并指出路径。你不需要为此 写额外的校验步骤，也就不存在「忘了校验」这回事。
• 「没有密钥」这件事是可以被证明的。 CI 里不配置任何 API Key，测试照样全绿； 反过来，若有哪条路径偷偷发起真实调用，它必然失败 —— 回放会话在构造上不持有 Transport。
• 漂移检测是独立的一步。 想知道「换了模型版本之后行为是否变了」，写一个小测试即可：

///|
test "no behavioural drift since the recording was accepted" {
  let old = @codec.decode(@fs.read_file_to_string("tests/cassettes/chat.json"))
  let fresh = @codec.decode(
    @fs.read_file_to_string("tests/cassettes/chat.new.json"),
  )
  let report = @mooncassette.compare_recordings(old, fresh)
  if !report.is_clean() {
    fail("drift detected: " + report.summary())
  }
}

#概念

#cassette

{
  "format": "mooncassette",
  "version": 2,
  "meta": {
    "generator": "mooncassette/0.9.0",
    "name": "chat-demo",
    "recorded_at": "2026-09-12T08:00:00Z"
  },
  "interactions": [
    {
      "fingerprint": "fnv1a64:9f2c1ab34de5f607",
      "integrity": "fnv1a64:5ae605b113f91e60",
      "request": {
        "body": { "messages": [{ "content": "你好", "role": "user" }] },
        "model": "gpt-4o",
        "provider": "openai"
      },
      "response": {
        "body": { "choices": [] },
        "status": 200,
        "usage": { "input_tokens": 10, "output_tokens": 2 }
      }
    }
  ]
}

#两个摘要，两种职责

#请求规范化

#匹配策略

#匹配的成本与指纹索引

#未命中时能看到什么

mooncassette: no recorded interaction matches request fnv1a64:2b1e... (the cassette has 2
interaction(s); closest is #0 (provider=openai model=gpt-4o), differing at $.body.messages[0].content)

• 差异只报路径，不报字段值：诊断信息常被写进测试输出或日志，而传进去的请求 未必经过脱敏；
• 路径做排序，候选按「差异最少」稳定排序，因此报告可以被断言、可以逐字比较；
• 「录制条数不够」与「请求对不上」分开报。 顺序模式下游标越界抛 Exhausted 而不是 NoMatch——前者的修法是补录制，后者是改请求或换策略，混在一起会把排查 引向错误的方向。

///|
let diagnosis = session.diagnose(request)
for line in diagnosis.lines() {
  println(line)
}

#脱敏

• 精确键名匹配（authorization、x-api-key、cookie …）；
• 后缀匹配（_key、_token、_secret …）——刻意用后缀而非子串， 以免误伤 max_tokens / total_tokens 这类计数字段；
• 字符串值中的密钥形状子串扫描（sk- 后接 8 位以上）。

#漂移检测

• 请求改动会报成「一条 Removed + 一条 Added」，而不是「一条 Changed」。 因为我们无法判断改后的请求「对应」原来哪一条；与其猜错，不如如实报告。
• 比较前会重新规范化请求。 正常录制出来的请求本就是规范化形态（再规范化是幂等的）， 但对手工构造或被外部工具改过的 cassette，这一步能避免把「易变字段残留」误判为漂移。 容错方向是「宁可少报」。

$ mooncassette diff examples/demo.cassette.json examples/demo.drifted.cassette.json
[changed] gpt-4o #0 -> #0  b862439f
drift detected: removed=0 changed=1 added=0 unchanged=1

#流式响应

线上            data: {...} ──▶ SSE 文本
                 │
      ┌──────────┴──────────┐
      ▼                     ▼
 Response.stream        Response.body
（原始帧，逐个保留）    （聚合后的最终结果，与非流式同形）

• SSE 解析严格按规范（WHATWG HTML §9.2）：三种行终止符、多行 data: 以换行连接、 注释行与 id / retry 一并忽略。末尾没有空行时最后累积的帧按规范丢弃—— 与其猜「大概只是漏了个终止空行」，不如少一帧让聚合结果对不上，而不是把一份可能 已被截断的流当作完整流转正。
• 增量按各家语义聚合：OpenAI 的 chat.completion.chunk（含分片发送的 tool_calls[].function.arguments）与 Anthropic 的命名事件（message_start / content_block_delta / message_delta …，含分片到达的 delta.partial_json）。 分片只有拼完才是合法 JSON，所以聚合中途一律只拼接、不解析。
• usage 从流里抽出来：两侧都上报才给出，缺一半时留空而不是补 0—— 补 0 会把「没上报」写成「上报了 0」，那是错误信息而不是缺失信息。
• 帧也要脱敏：帧里装的是同一份模型输出，只脱敏聚合体等于在流式路径上留后门。
• 流式与非流式自动区分：HttpResponse 只带状态码与响应体、没有 Content-Type， 因此按下议内容判断（首个非空行是 data: / event: / 注释行）。
• 回放侧也逐帧递：Session::replay_stream(request, sink) 先拿到响应，再把帧按线上 顺序递回去。录制时「逐块渲染」那段代码在离线回放时同样会被跑到，而它恰恰最容易出错。 非流式响应不触发 sink —— 那是「本来就没有分片」，不是「分片丢了」。
• 客户端自己逐块收数据也能录：decode_openai_stream_frames / decode_anthropic_stream_frames 直接收帧聚合，配合 Session::record 即可把分片回调 攒出来的结果录进 cassette。
• 仓库里的 examples/streaming_demo 端到端跑一遍：录制时逐帧递出、离线回放时逐帧 递出、两者逐帧一致，并顺带给出成本汇总。

#CLI

mooncassette verify  <cassette.json>                 # 解码 + 完整性校验，非零退出码表示失败
mooncassette show    <cassette.json>                 # 打印概要（版本、记录数、token、模型）
mooncassette diff    <old.json> <new.json>           # 报告两次录制之间的漂移，有漂移则退出码 1
mooncassette cost    <cassette.json> <prices.json>   # 按价目表汇总 token 成本
mooncassette tokens  <cassette.json>                 # 上报用量与「4 字符 1 token」估算的对照
mooncassette explain <cassette.json> <request.json>  # 判断请求能否回放，不能则说明差在哪（退出码 1）
mooncassette migrate <old.json> <new.json>           # 升到当前格式并打印变更摘要（绝不原地覆盖）
mooncassette trim    <in.json> <out.json> --keep <spec>             # 按策略裁剪记录
mooncassette merge   <out.json> <in.json> [<in.json> ...] [--policy <p>]  # 合并多份录制，丢弃完全相同的重复
mooncassette stats   <in.json> [<in.json> ...]       # 汇总多份录制（版本 / 来源 / 状态 / 模型）
mooncassette help

• cost 需要一份由你提供的价目表（{"模型名": {"input": 微美元/百万, "output": …}}， 以 _ 开头的键当作注记忽略）。本项目刻意不内置价格——价格变动频繁，内置一张 会过期的表只会让你拿到「看起来精确、其实已经错了」的数字。汇总里同时给出 priced / unpriced / no_usage 三个计数，让你看得见这个总额覆盖了多少条记录。
  在仓库里可以直接复算：

  moon run cmd/main --target js -- cost examples/demo.cassette.json examples/prices.example.json
  # cost=$0.000210  priced=2  unpriced=0  no_usage=0

• tokens 把 provider 上报的用量与「4 字符 1 token」的估算并排列出，用来回答 「估算离精确有多远」。详见下面的「精确，而不是估算」。
• explain 回答「这个请求为什么回放不出来」，用的是与库内完全相同的诊断路径， 因此输出与测试失败时的错误消息一致：

match: no
policy=Exact  cursor=0  interactions=1
  #0  provider=openai  model=gpt-4o  differs: $.body.api_key (only in the request), $.body.model (only in the recording)

• 只写新文件，绝不原地覆盖：migrate 在来源与目标相同时直接报错。 迁移是要留下痕迹的动作 —— 旧文件还在，新旧两版可以互相对照，出了问题也退得回去。
• 输出稳定可复现：分组顺序都是显式排序（条数降序、同数按标签的码点序升）， 同一组输入在任何后端、任何进程里都打印同样的字节。
• 只让信息可见，不做猜测：stats 把 unreported 单列而不并进 token 总数 （「不知道」与「是 0」是两回事）；trim 把「原有几条、留下几条」一起打印， 让越界的 index、不存在的 model 造成的少留是看得见的，而不是被吞掉。

moon run cmd/main --target js -- trim examples/demo.cassette.json /tmp/one.json --keep first:1
# trimmed  : examples/demo.cassette.json -> /tmp/one.json
# keep     : first:1
# records  : 2 -> 1

#迁移指南（历史版本 → 当前格式）

• 你想把旧版本文件显式升级为当前版本（例如提交一份统一格式的录制），或
• 你有一份手写 / 跨工具产生的旧格式 cassette，想确认它在新读端下语义不变，

#用 CLI 一键迁移

# 只写新文件，绝不原地覆盖源文件
moon run cmd/main -- migrate old.cassette.json new.cassette.json

# 迁移后自检：通过即表示语义未变（两个摘要都对齐）
moon run cmd/main -- verify new.cassette.json

• 绝不原地覆盖——来源与目标是同一文件会直接报错退出（CI 以此守卫）；
• 旧版本读入后若追加了流式记录，输出版本自动升到 2；
• verify 同时校验请求指纹摘要与记录摘要，谁手工改过文件这里就拦住。

#跨版本往返

#设计取舍（已知边界）

#测试与验证

moon test --target wasm-gc   # 默认目标
moon test --target js        # 交叉验证
moon check --target js
moon fmt && moon info

• FNV-1a 用官方测试向量校验（空串 / "a" / "foobar"）；
• 规范文本的键序、转义、幂等性；
• 环形查找的推进与回卷边界（白盒直测私有算术）；
• 篡改请求体、响应体、状态码、token 用量都必须被检出；
• 脱敏不能误伤 max_tokens / total_tokens；
• 真实调用的请求必须保留密钥（用记录型 Transport 断言）；
• 带密钥的请求「录制后立刻回放」必须命中（回归测试）；
• 回放模式下 Transport 调用次数必须为 0；
• 漂移检测：键序/易变字段变化不算漂移，而响应变化必须算；
• 漂移检测：重复的同一请求按出现顺序两两配对，报告顺序固定为 Removed → Changed → Added；
• 协议解码用真实 API 形状的报文（含 429 错误体、HTML 网关错误页、非整数 token 数）验证；
• 诊断：差异路径按字典序排序（Map 迭代顺序不保证稳定，不排序就无法断言）；
• 诊断：差异数量相同时保持录制顺序（稳定排序）；
• 诊断：$.model 与 $.body.x 能分别定位，「只在记录里」「只在请求里」与数组长度差都会被报出；
• 顺序模式耗尽抛 Exhausted，空 cassette 报 NoMatch——两者不可混；
• 手动录入（Session::record）与自动录制产出同一形态，且「录完立刻回放」必须命中；
• 手动录入绝不触碰 Transport（这是异步接入的前提）；
• 手动录入返回的是脱敏后的响应，与回放返回的内容一致（否则首次运行与后续运行会看到不同的值）；
• SSE：三种行终止符、多行 data: 连接、注释与未知字段忽略、BOM、空帧、以及「末尾无空行则丢弃」；
• SSE：render ∘ parse 收敛，且非 ASCII 载荷不错位（索引与切片全部按字符进行）；
• 事件流识别不误判 JSON、HTML 与「database error」这类前缀相似的纯文本；
• 流式聚合：分片的 tool_calls.arguments 与 partial_json 只有拼完才解析；
• 流式聚合：纯 tool call 的流写成 content: null 而非空串（两者语义不同）；
• 流式聚合：usage 缺一半时留空，而聚合体里补 0——「没上报」与「上报了 0」可区分；
• 流式聚合：错误帧原样作为响应体，不再被继续聚合；
• 流式：帧内容落盘前必须脱敏（否则流式路径会绕开「落盘必脱敏」）；
• 流式回放：replay_stream 把帧按录制顺序递出，且「录制时递出的帧」与「回放时递出的帧」逐帧一致；非流式响应不触发 sink；
• 流式：帧级聚合入口与响应级入口给出完全一致的结果（两者只是「谁来解析帧」不同）；
• 格式版本：旧版本（version 1）仍可读；「读入旧版本 → 写出旧版本」字节稳定； 追加流式记录后写出版本自动升到 2，不会写出「自称旧格式、其实含新字段」的文件；
• 诊断：差异路径按码点字典序排序（String 自带的比较不是字典序，实测表现为先比长度）；
• 成本：整数算术的取整方向是确定的，同一输入恒得同一金额；未知模型报「未知」而不是 0；
• 成本：token 数 × 价格 用 Int64（MoonBit 的 Int 是 32 位，用 32 位会静默溢出）；
• 对抗性矩阵：篡改 cassette 的每一个字段都必须被检出，且错误消息指出路径； 同时钉住 meta / version 不该报警——过度报警会让人学会忽略警告，比不报警更糟；
• 脱敏性质测试：300 组确定性随机结构，密钥以三种包装形式随机埋入任意层级， 断言序列化结果中永不出现；另验证脱敏幂等、max_tokens / total_tokens 不被误伤；
• 解析器模糊测试：对抗语料 + 600 组随机输入不崩，且 render ∘ parse 幂等；
• 形状矩阵：有无 usage、有无帧、空容器、非 ASCII、控制字符、状态码 0、 以及 20 条记录的顺序，全部稳定往返（断言的是再编码后的字节相等）；
• 脚本化应答序列：同一请求按注册顺序依次给出、用完重复最后一个；on 是追加而不是覆盖 （覆盖语义会在「我只想再补一条」时悄悄丢掉先前那条，正是重试序列最容易踩的坑）；
• 重试路径：429 → 200 的序列可以离线复现，且回放阶段一次网络调用都不发生；
• 调用次数超出录制条数时，环形策略复用最早一条、顺序策略抛 Exhausted —— 两种行为都被钉住；
• 指纹索引：有索引与无索引在每个策略、每个游标下给出同一个命中下标 —— 索引若改变结果， 症状是「回放出了另一个响应」而不是报错，属于最难查的一类错误；
• 指纹索引：录制期间不断追加后仍与记录逐位对齐，50 条记录按序命中无错位；
• 子集策略在有索引与无索引下结果一致（它本就用不上整请求指纹）。

#兼容性承诺（格式冻结）

自 0.9.0 起，下表三项被锁定为格式契约：读端向后兼容全部已发布版本；写端恒定输出当前值；升大版本（1.0）前不会变更。

#包结构

#已完成

#许可