原始流数据样本目录

该目录只保留上游真实 SSE 原始流，用于本地回放、字段分析和回归测试。

样本分类

该目录下的样本分成两类：

canonical 默认样本：由 manifest.json 的 default_samples 指定，默认回放工具优先跑这组稳定样本
扩展样本：保留真实问题或特定协议行为，用于排障、字段分析和定向回归，不一定默认纳入全量回放

当前目录里除了 canonical 样本，还包含例如：

markdown-format-example-20260405
markdown-format-example-20260405-spacefix
continue-thinking-snapshot-replay-20260405

其中 continue-thinking-snapshot-replay-20260405 是一个多轮样本，覆盖 completion + continue 的原始 SSE 重放场景，用于验证接续思考去重。

如果要看默认固定回放集，以 manifest.json 为准，而不是按目录数量人工判断。更完整的协议级行为结构说明见 docs/DeepSeekSSE行为结构说明-2026-04-05.md。

自动采集接口

本地启动服务后，可以直接调用专用接口自动落盘一份 raw-only 样本：

POST /admin/dev/raw-samples/capture

这个接口会：

接收一个普通的 OpenAI chat completions 请求体
走项目内同一条处理链
自动保存请求元信息 meta.json
自动保存上游原始流 upstream.stream.sse

采集接口的响应体仍然是项目当次的实际输出，但它不会再写入样本目录。这样样本树始终只保留原始流，后续回放时再按需本地生成派生结果。

如果问题已经在当前进程的内存抓包里复现过，也可以先查再存：

GET /admin/dev/raw-samples/query?q=关键词&limit=20
POST /admin/dev/raw-samples/save

这条链路适合把“刚刚发生的一次真实问题”快速转成可回放样本，而不用重新触发请求。

目录规范

每个样本一个子目录，且只保留下面两类文件：

meta.json：样本元信息（问题、模型、采集时间、备注）
upstream.stream.sse：完整原始 SSE 文本（event: / data: 行）

meta.json 的关键字段通常包括：

sample_id
captured_at_utc
source
request
capture

对于多轮样本，capture.rounds 会记录每一轮上游请求，例如首轮 deepseek_completion 和后续 deepseek_continue。

回放与对比

回放工具会读取 upstream.stream.sse，在本地自动生成当前解析结果，并把派生结果写到 artifacts/raw-stream-sim/<run-id>/<sample-id>/，例如：

replay.output.txt：本次回放生成的最终可见文本
report.json：本次回放的结构化报告，包含事件数、chunk 数、终态、引用泄露检查等信息

运行全部 canonical 样本：

./tests/scripts/run-raw-stream-sim.sh

运行全部样本目录（不只 manifest 默认样本），并逐个打印 token 对齐结果：

for d in tests/raw_stream_samples/*; do
  [ -d "$d" ] || continue
  sid="$(basename "$d")"
  [ -f "$d/upstream.stream.sse" ] || continue
  node tests/tools/deepseek-sse-simulator.mjs --samples-root tests/raw_stream_samples --sample-id "$sid"
done

回放输出会显示 tokens=<parsed>/<expected>；默认只记录 token 差异，不因 token 不一致失败。如需把 token 差异作为失败条件，给模拟器增加 --fail-on-token-mismatch。report.json 中也会包含：

raw_expected_output_tokens
raw_parsed_output_tokens
raw_token_mismatch

运行单个样本并和已有基线比对：

./tests/scripts/compare-raw-stream-sample.sh markdown-format-example-20260405-spacefix

如果你已经有历史基线目录，也可以把它作为第二个参数传进去，脚本会对比当前回放结果和基线输出。

扩展方式

抓取一次真实请求。
直接调用 /admin/dev/raw-samples/capture，或者先用 /admin/dev/raw-samples/query + /admin/dev/raw-samples/save 从内存抓包落盘；也可以手工新建 <sample-id>/ 目录并放入 meta.json + upstream.stream.sse。
运行回放工具或对比脚本，生成本地派生结果并检查是否回归。

注意：样本可能包含搜索结果正文与引用信息，请勿放入敏感账号/密钥。

4.3 KiB Raw Blame History Unescape Escape