refactor: replace processed output comparison with baseline-based validation in SSE simulator

tests/raw_stream_samples/README.md

@@ -1,10 +1,10 @@
 # 原始流数据样本目录
 
-该目录用于存放**上游真实 SSE 原始流**样本，供本地仿真测试和解析适配使用。
+该目录只保留**上游真实 SSE 原始流**，用于本地回放、字段分析和回归测试。
 
 ## 默认永久样本
 
-仓库当前只保留两份永久默认样本：
+仓库当前保留两份 canonical 默认样本：
 
 - `guangzhou-weather-reasoner-search-20260404`：包含 `reference:N` 引用标记的天气搜索流，用于验证引用清理与正文输出。
 - `content-filter-trigger-20260405-jwt3`：真实命中的 `CONTENT_FILTER` 风控流，用于验证终态处理与拒答格式。
@@ -13,7 +13,7 @@
 
 ## 自动采集接口
 
-本地启动服务后，可以直接调用专用接口自动落盘一份永久样本：
+本地启动服务后，可以直接调用专用接口自动落盘一份 raw-only 样本：
 
 ```bash
 POST /admin/dev/raw-samples/capture
@@ -23,39 +23,43 @@ POST /admin/dev/raw-samples/capture
 
 - 接收一个普通的 OpenAI chat completions 请求体
 - 走项目内同一条处理链
-- 自动保存 `meta.json`
+- 自动保存请求元信息 `meta.json`
 - 自动保存上游原始流 `upstream.stream.sse`
-- 自动保存项目最终输出 `openai.stream.sse` 或 `openai.response.json`
 
-响应体仍然是项目最终输出，同时会额外带上 `X-Ds2-Sample-*` 头，方便脚本和手工检查。
+采集接口的响应体仍然是项目当次的实际输出，但它不会再写入样本目录。这样样本树始终只保留原始流，后续回放时再按需本地生成派生结果。
 
 ## 目录规范
 
-每个样本一个子目录：
+每个样本一个子目录，且只保留下面两类文件：
 
 - `meta.json`：样本元信息（问题、模型、采集时间、备注）
 - `upstream.stream.sse`：完整原始 SSE 文本（`event:` / `data:` 行）
-- `openai.stream.sse`：项目最终输出的 SSE 形式，或
-- `openai.response.json`：项目最终输出的非流式 JSON 形式
-- `openai.output.txt`：项目最终输出的纯文本摘要，供回放工具直接比对
 
-## 扩展方式
+## 回放与对比
 
-1. 抓取一次真实请求（建议开启 `DS2API_DEV_PACKET_CAPTURE=1`）。
-2. 直接调用 `/admin/dev/raw-samples/capture`，或者手工新建 `<sample-id>/` 目录并放入 `meta.json` + `upstream.stream.sse` + `openai.stream.sse` / `openai.response.json`。
-3. 运行独立仿真工具（可被其他测试脚本调用）：
+回放工具会读取 `upstream.stream.sse`，在本地自动生成当前解析结果，并把派生结果写到 `artifacts/raw-stream-sim/<run-id>/<sample-id>/`，例如：
+
+- `replay.output.txt`：本次回放生成的最终可见文本
+- `report.json`：本次回放的结构化报告，包含事件数、chunk 数、终态、引用泄露检查等信息
+
+运行全部 canonical 样本：
 
 ```bash
 ./tests/scripts/run-raw-stream-sim.sh
 ```
 
-该工具默认按 `manifest.json` 中声明的永久样本重放并验证：
+运行单个样本并和已有基线比对：
 
-- 不会把上游 `status=FINISHED` 片段当正文输出（防泄露）。
-- 能正确检测 `response/status=FINISHED` 流结束信号。
-- 会把样本里的 `openai.stream.sse` / `openai.response.json` 当作最终输出基线，和重放后的结果比对。
-- 生成可归档 JSON 报告（`artifacts/raw-stream-sim/`）。
+```bash
+./tests/scripts/compare-raw-stream-sample.sh markdown-format-example-20260405-spacefix
+```
 
-如果 `manifest.json` 不存在，则回退为遍历目录中的全部样本。
+如果你已经有历史基线目录，也可以把它作为第二个参数传进去，脚本会对比当前回放结果和基线输出。
+
+## 扩展方式
+
+1. 抓取一次真实请求。
+2. 直接调用 `/admin/dev/raw-samples/capture`，或者手工新建 `<sample-id>/` 目录并放入 `meta.json` + `upstream.stream.sse`。
+3. 运行回放工具或对比脚本，生成本地派生结果并检查是否回归。
 
 > 注意：样本可能包含搜索结果正文与引用信息，请勿放入敏感账号/密钥。