docs: update documentation for raw stream test samples

tests/raw_stream_samples/README.md

@@ -2,14 +2,22 @@
 
 该目录只保留**上游真实 SSE 原始流**，用于本地回放、字段分析和回归测试。
 
-## 默认永久样本
+## 样本分类
 
-仓库当前保留两份 canonical 默认样本：
+该目录下的样本分成两类：
 
-- `guangzhou-weather-reasoner-search-20260404`：包含 `reference:N` 引用标记的天气搜索流，用于验证引用清理与正文输出。
-- `content-filter-trigger-20260405-jwt3`：真实命中的 `CONTENT_FILTER` 风控流，用于验证终态处理与拒答格式。
+- canonical 默认样本：由 [`manifest.json`](./manifest.json) 的 `default_samples` 指定，默认回放工具优先跑这组稳定样本
+- 扩展样本：保留真实问题或特定协议行为，用于排障、字段分析和定向回归，不一定默认纳入全量回放
 
-默认回放工具会优先读取 [`manifest.json`](./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`](./manifest.json) 为准，而不是按目录数量人工判断。
 更完整的协议级行为结构说明见 [docs/DeepSeekSSE行为结构说明-2026-04-05.md](../../docs/DeepSeekSSE行为结构说明-2026-04-05.md)。
 
 ## 自动采集接口
@@ -29,6 +37,15 @@ POST /admin/dev/raw-samples/capture
 
 采集接口的响应体仍然是项目当次的实际输出，但它不会再写入样本目录。这样样本树始终只保留原始流，后续回放时再按需本地生成派生结果。
 
+如果问题已经在当前进程的内存抓包里复现过，也可以先查再存：
+
+```bash
+GET /admin/dev/raw-samples/query?q=关键词&limit=20
+POST /admin/dev/raw-samples/save
+```
+
+这条链路适合把“刚刚发生的一次真实问题”快速转成可回放样本，而不用重新触发请求。
+
 ## 目录规范
 
 每个样本一个子目录，且只保留下面两类文件：
@@ -36,6 +53,16 @@ POST /admin/dev/raw-samples/capture
 - `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>/`，例如：
@@ -60,7 +87,7 @@ POST /admin/dev/raw-samples/capture
 ## 扩展方式
 
 1. 抓取一次真实请求。
-2. 直接调用 `/admin/dev/raw-samples/capture`，或者手工新建 `<sample-id>/` 目录并放入 `meta.json` + `upstream.stream.sse`。
+2. 直接调用 `/admin/dev/raw-samples/capture`，或者先用 `/admin/dev/raw-samples/query` + `/admin/dev/raw-samples/save` 从内存抓包落盘；也可以手工新建 `<sample-id>/` 目录并放入 `meta.json` + `upstream.stream.sse`。
 3. 运行回放工具或对比脚本，生成本地派生结果并检查是否回归。
 
 > 注意：样本可能包含搜索结果正文与引用信息，请勿放入敏感账号/密钥。