#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 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)) // 同步
  }
}

#概念

#cassette

{
  "format": "mooncassette",
  "version": 1,
  "meta": {
    "generator": "mooncassette/0.3.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

#CLI

mooncassette verify <cassette.json>              # 解码 + 完整性校验，非零退出码表示失败
mooncassette show   <cassette.json>              # 打印概要（版本、记录数、token、模型）
mooncassette diff   <old.json> <new.json>        # 报告两次录制之间的漂移，有漂移则退出码 1
mooncassette help

#设计取舍（已知边界）

#测试与验证

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（这是异步接入的前提）；
• 手动录入返回的是脱敏后的响应，与回放返回的内容一致（否则首次运行与后续运行会看到不同的值）。

#包结构

#已完成

#许可