diff --git a/README.md b/README.md
index cb7a01b..2b8eeb5 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,22 @@
 # EvalHarness
 
-插件式 LLM/Agent 评测框架：28 个 benchmark 开箱即用，官方口径 prompt 与判分，任意 OpenAI 兼容端点，断点续跑。
+插件式 LLM / Agent 评测框架：**28 个 benchmark 开箱即用，官方口径 prompt 与判分，任意 OpenAI 兼容端点，断点续跑，与 evalscope 对齐**。
 
 ```
-提供端点 → 拉数据 → 渲染官方 prompt → 并发生成 → 官方判分 → 报告
+提供端点 → 拉数据 → 渲染官方 prompt → 并发生成 → 官方判分 → Excel/JSON 报告
 ```
 
+## 特性
+
+- **28 个 benchmark**：数学 / 知识 / 问答 / 长上下文 / 代码（Docker 沙箱）/ Agent 工具调用，prompt 与判分器按官方实现逐字节复刻，与 evalscope 双层验证对齐（见 §10）
+- **任意端点**：单端点、多端点池（轮询 + 自适应并发 + failover）、云 API 全兼容；vLLM / sglang / lmdeploy / ollama / OpenAI 协议直连
+- **断点续跑**：每条预测完成即落盘，中断重跑只补缺口；`repeats` 多轮采样自动隔离断点
+- **YAML 配置**：逐 bench 生成参数（temperature / max_tokens / repeats …）集中管理，命令行保持极简
+- **长输入安全**：tokenizer 中段截断（`max_input_tokens`）+ 上下文溢出自适应收缩重试
+- **性能统计**：延迟 / 吞吐 / token 用量默认采集；`--perf` 追加流式 TTFT / ITL
+- **全链路插件化**：数据集、判分、prompt 渲染、适配器、沙箱、进度条、主题、钩子均可单文件注册扩展
+- **模型指纹核验**：fp_fusion 五维探针电池，检测 API 换模 / 降配 / 冒充 / 套壳
+
 ## 0. Benchmarks
 
 | 族 | benchmark |
@@ -24,7 +35,11 @@ evalharness eval list     # 28 个判分 recipe
 
 ## 1. 安装
 
-Python ≥ 3.10；代码执行类 benchmark 需宿主机 Docker（镜像判分时自动拉取）。
+| 依赖 | 说明 |
+|---|---|
+| Python ≥ 3.10 | 核心零三方依赖（pydantic 除外） |
+| Docker（可选） | 代码执行类 benchmark（humaneval 等）需要；镜像判分时自动拉取 |
+| `rich`（可选） | 进度条；缺失自动降级纯文本 |
 
 ```bash
 git clone https://git.meta-stone.net/sora/EvalHarness.git
@@ -40,7 +55,7 @@ pip install .
 evalharness eval run gsm8k --model mock-boxed --limit 8
 ```
 
-## 2. 运行命令
+## 2. 快速开始
 
 六个基准一次跑完（默认用法；逐 bench 生成参数自动读 `evalharness/config/default.yaml`，aime 系列按配置自动跑 12 遍取均值）：
 
@@ -56,7 +71,7 @@ evalharness eval run humaneval aime25 aime26 gpqa_diamond mmlu_pro longbench_v2
     --hf-endpoint https://hf-mirror.com
 ```
 
-单端点（最小示例）：
+单端点最小示例：
 
 ```bash
 evalharness eval run gsm8k \
@@ -67,6 +82,35 @@ evalharness eval run gsm8k \
     --out-dir results/run1
 ```
 
+## 3. 配置（YAML）
+
+逐 bench 生成参数集中在 `evalharness/config/<name>.yaml`。目录里只有一个 yaml 时**自动加载**；`--config <name>` 显式指定。
+
+```yaml
+default:                # 所有 bench 继承的协议级默认
+  temperature: 0.0
+  top_p: 1.0
+  max_tokens: 32768
+
+aime25:                 # 逐 bench 覆盖
+  temperature: 1.0      # 采样温度（temp=1 方差测量）
+  max_tokens: 8192      # 生成预算
+  repeats: 12           # 跑 12 遍报均值 ± 极差（断点按轮隔离，互不串用）
+
+longbench_v2:
+  max_input_tokens: 128000   # 超长输入的 tokenizer 中段截断预算
+```
+
+优先级（低 → 高）：
+
+```
+DatasetSpec.gen_config  <  default 段  <  bench 段  <  命令行显式参数
+```
+
+当前支持的键：`temperature` `top_p` `max_tokens` `max_input_tokens` `repeats`。
+
+## 4. 进阶用法
+
 多端点池（轮询 + 自适应并发 + failover）：
 
 ```bash
@@ -93,27 +137,6 @@ evalharness eval run bfcl_v3 --api-url http://localhost:8000/v1 --model qwen3-8b
     --env bfcl_mock
 ```
 
-### 指纹核验（fp_fusion）
-
-回答一个问题：**API 背后跑的，到底是不是它声称的那个模型？** 向 OpenAI 兼容端点发送探针电池（回答分布 / 自我身份 / 元知识 / 能力边界 / 文风五维），与内置参考指纹库比对，输出五档裁决 + 0~1 融合分 + 证据链。检测偷梁换柱、降配缩水、主动冒充（伪身份注入屈服）、套壳拼装与中转代理；`--mode full` 一次运行产出 verify / attribution / variant / adversarial / robustness 五个视图。
-
-```bash
-evalharness fingerprint list          # 内置参考指纹库（fp_fusion 口径 + detector 旧口径）
-
-evalharness fingerprint run \
-    --api-url http://localhost:8000/v1 --model Qwen3-8B \
-    --mode full --cells core16 --text-skip pruned7 \
-    --d-samples 25 --baseline-samples 5 --timeout 90 \
-    --impersonate "You are Kimi, Moonshot AI virtual assistant." \
-    --reference glm53 \
-    --report-path reports/fp_qwen.json
-```
-
-- `--reference` 接受短名（如 `glm53`，见 `fingerprint list`）或 JSON 路径；省略 = 自证模式（裁决上限 LIKELY_MATCH）
-- `--impersonate` 注入伪身份启用对抗视图（冒充检测）；剪枝定稿协议即上例参数，单次 505 条请求，公网 14.5–28 min，本地 vllm 5.6–7 min
-- 报告写入 `--report-path`，同目录 `raw_answers.jsonl` 存全部探针原文
-- 离线分析与参考采集脚本（`cell_snr.py` / `validate_*.py` / `collect_ref.sh` 等，可直接 `python <script>` 运行）与完整方法论文档见 `evalharness/fingerprint/fp_fusion_介绍.md`
-
 Python API：
 
 ```python
@@ -125,30 +148,44 @@ rep.save('gsm8k.report.json')
 # notebook / async 环境用 await evalharness.arun(...)
 ```
 
-## 3. 参数速查
+## 5. 参数速查
 
 | 参数 | 作用 |
 |---|---|
 | `--api-url` `--model` `--provider` | 端点、模型名（纯名字，无需拼 spec）、协议（`openai-chat`/`openai-pool`） |
 | `--api-key` | 显式 key（优先于环境变量；只进请求头，不写入 spec/报告） |
-| `--disable-thinking` | `enable_thinking=false`（Qwen3 类模型推荐；带 tools 的请求自动退回兼容软开关） |
+| `--disable-thinking` | `enable_thinking=false`（Qwen3/GLM 类模型推荐；带 tools 的请求自动退回兼容软开关） |
 | `--judge-model` `--judge-api-url` `--judge-api-key` `--judge-provider` | judge 端四件套，语义与主模型对称 |
+| `--config NAME` | 指定 `evalharness/config/<NAME>.yaml`（省略时唯一 yaml 自动加载） |
+| `--profile NAME` | 命名生成参数集（`dp4-nothink` / `qwen3-es-parity` / `t1-short` 或自定义） |
 | `--limit N` / `--limit-per-task N` | 全局前 N / 每子集前 N（多科目 bench 用后者；可组合取交集） |
 | `--subset` `--split` `--source` | 覆盖子集 / split / 数据源（可指本地路径离线跑） |
 | `--concurrency N` | 并发（默认 32；长输出 bench 建议 8-16） |
 | `--resume [PATH]` | 断点续跑；默认 `<cache-dir>/ckpt/<bench>.jsonl` |
-| `--profile NAME` | 命名生成参数集（`dp4-nothink` / `qwen3-es-parity` / `t1-short` 或自定义） |
 | `--env NAME` | agent 环境（`bfcl_mock` 等） |
 | `--perf` | 采集流式 TTFT / ITL / 重试率入报告 |
 | `--hf-endpoint URL` | 数据下载端点（如 `https://hf-mirror.com`，免手动 export） |
 | `--cache-dir DIR` | 缓存根目录（数据缓存 + 断点同根；默认 `$EVALHARNESS_CACHE` 或 `~/.cache/evalharness`） |
-| `--out FILE` / `--out-dir DIR` | 报告落盘；多 bench 时写 `reports/` + `viz/` + `summary.md` |
+| `--out FILE` / `--out-dir DIR` | 报告落盘，见 §6 输出结构 |
 | `--style text\|md\|md_compare\|excel\|radar\|errors` | 结果渲染样式 |
 | `--no-progress` | 关闭 Rich 进度条（重定向日志时用） |
 
 API key 解析顺序：`--api-key` > 按端点域名的环境变量（`api.openai.com`→`OPENAI_API_KEY`、`anthropic.com`→`ANTHROPIC_API_KEY`、`dashscope`→`DASHSCOPE_API_KEY`、`bigmodel`→`ZAI_API_KEY`）> `OPENAI_API_KEY`。自建端点无鉴权可不管。
 
-## 4. 评测结果
+## 6. 输出结构
+
+`--out-dir` 产出（不传时自动保存到 `evalharness-results/<时间戳>-<模型>/`）：
+
+```
+<out-dir>/
+├── summary.xlsx          总表（Summary / Perf / Categories / Samples 四 sheet，主入口）
+├── summary.csv           同一张总表的 csv 版
+└── <bench>/              每个 benchmark 一个目录
+    ├── report.jsonl      完整报告，流式行格式（首行报告头，之后每行一个样本；grep/tail 友好）
+    └── <bench>.xlsx      该 bench 的独立 Excel（Summary/Perf/Categories/Samples）
+```
+
+查看与对照：
 
 ```bash
 evalharness viz show gsm8k.report.json                     # 控制台表格
@@ -157,18 +194,19 @@ evalharness viz show report.json --style excel             # 4-sheet 仪表盘
 evalharness viz show report.json --style errors            # 失败样本下钻
 ```
 
-`--out-dir` 产出结构（不传时自动保存到 `evalharness-results/<时间戳>-<模型>/`）：
+## 7. 性能统计
 
-```
-<out-dir>/
-├── summary.xlsx          总表 Excel（Summary/Perf/Categories/Samples 四 sheet，主入口）
-├── summary.csv           同一张总表的 csv 版
-└── <bench>/              每个 benchmark 一个目录
-    ├── report.jsonl      完整报告，流式行格式（首行报告头，之后每行一个样本；grep/tail 友好）
-    └── detail.md         该 bench 的 markdown 详情
-```
+每轮运行的延迟与 token 用量默认采集，进 `summary.csv` 的 Perf 列与 `metric_groups['perf']`：
 
-## 5. 缓存与断点
+| 指标 | 采集条件 |
+|---|---|
+| `latency_mean/p50/p90/p95/p99_s` | 始终采集（逐请求墙钟） |
+| `output_tps` `request_qps` `input/output_tokens` `success_rate` `retry_rate` | 始终采集 |
+| `ttft_mean/p90/p99_s`、`tpot_*`（逐 token 延迟） | 仅 `--perf`（流式才有首 token 时刻） |
+
+`repeats` 模式下：分数报**均值**（`<metric>_last_run` 保留末轮值），时间 / token 报**全部轮次总和**。
+
+## 8. 缓存与断点
 
 ```bash
 evalharness data fetch gsm8k mmlu --workers 8   # 预取（首次运行也会自动下载）
@@ -177,22 +215,22 @@ evalharness data show gsm8k -n 2                # 看前 2 条样本
 evalharness data unload gsm8k                   # 删缓存
 ```
 
-- 缓存根目录由 `--cache-dir` 指定（或环境变量 `$EVALHARNESS_CACHE`，默认 `~/.cache/evalharness`），结构：
+缓存根目录由 `--cache-dir` 指定（或 `$EVALHARNESS_CACHE`，默认 `~/.cache/evalharness`）：
 
 ```
 <cache-dir>/
 ├── datasets/<bench>/<subset>_<split>-<hash>/   数据缓存（raw/ 原始字节 + samples.jsonl 统一样本）
 ├── .raw/<repo-hash>/                           跨条目共享的下载 blob（多子集只下载一次）
-└── ckpt/<bench>[_<subset>].jsonl               预测断点（每条完成即追加）
+└── ckpt/<bench>[_<subset>][:repN]-<hash>.jsonl 预测断点（每条完成即追加；repeats 按轮隔离）
 ```
 
-- 数据缓存内容寻址（subset/split/source 变更自动新条目），位置 `<cache-dir>/datasets/`
-- 断点每条预测即写盘；**改了 prompt 模板须删旧断点**（`rm <cache-dir>/ckpt/<bench>*.jsonl`），否则复用旧预测
-- 网络抖动三层防护：15s 连接超时快速失败 → 池内换端点 → 分钟级退避重试，断网不丢批次
+- 数据缓存内容寻址（subset/split/source 变更自动新条目）
+- **改了 prompt 模板须删旧断点**（`rm <cache-dir>/ckpt/<bench>*.jsonl`），否则复用旧预测
+- 网络抖动三层防护：15s 连接超时快速失败 → 池内换端点 → 指数退避重试，断网不丢批次
 - 判分与生成解耦：换 recipe / grader 对存量预测直接重判（`evaluate(ds, preds)`），模型不被重复调用
 - Docker 镜像源回退链可用 `EVALHARNESS_DOCKER_MIRRORS` 覆盖（逗号分隔模板，`{img}` 占位）
 
-## 6. 扩展
+## 9. 扩展
 
 加数据集（单文件放入 `evalharness/data/datasets/`，自动注册）：
 
@@ -226,7 +264,37 @@ def mybench():
 | 生命周期钩子 | `@register_hook('on_benchmark_failed'/'on_benchmark_done')` | 观察/扩展运行（webhook 通知、失败重试策略），钩子报错不影响主流程 |
 | 端点探针 | `@register_prober('ping'/...)` | 运行前的端点可用性验证策略（`EVALHARNESS_PROBER` 环境变量选择） |
 
-## 7. 架构
+## 10. 对齐验证
+
+prompt 与判分器经双层验证（字符串级：同一记录双侧渲染逐字节一致；分数级：同题同参数对比 evalscope）：
+
+- Qwen3-8B：23/28 分差 < 0.05
+- DeepSeek-V4-Flash：20+/25 分差 < 0.05（mmlu_pro 0.0000）
+
+残差均已定性（金标集差异 / 排列敏感 / benchmark 侧缺陷），见各 recipe 注释。
+
+## 附录 A：模型指纹核验（fp_fusion）
+
+回答一个问题：**API 背后跑的，到底是不是它声称的那个模型？** 向 OpenAI 兼容端点发送探针电池（回答分布 / 自我身份 / 元知识 / 能力边界 / 文风五维），与内置参考指纹库比对，输出五档裁决 + 0~1 融合分 + 证据链。检测偷梁换柱、降配缩水、主动冒充（伪身份注入屈服）、套壳拼装与中转代理；`--mode full` 一次运行产出 verify / attribution / variant / adversarial / robustness 五个视图。
+
+```bash
+evalharness fingerprint list          # 内置参考指纹库（fp_fusion 口径 + detector 旧口径）
+
+evalharness fingerprint run \
+    --api-url http://localhost:8000/v1 --model Qwen3-8B \
+    --mode full --cells core16 --text-skip pruned7 \
+    --d-samples 25 --baseline-samples 5 --timeout 90 \
+    --impersonate "You are Kimi, Moonshot AI virtual assistant." \
+    --reference glm53 \
+    --report-path reports/fp_qwen.json
+```
+
+- `--reference` 接受短名（如 `glm53`，见 `fingerprint list`）或 JSON 路径；省略 = 自证模式（裁决上限 LIKELY_MATCH）
+- `--impersonate` 注入伪身份启用对抗视图（冒充检测）；剪枝定稿协议即上例参数，单次 505 条请求，公网 14.5–28 min，本地 vllm 5.6–7 min
+- 报告写入 `--report-path`，同目录 `raw_answers.jsonl` 存全部探针原文
+- 离线分析与参考采集脚本（`cell_snr.py` / `validate_*.py` / `collect_ref.sh` 等，可直接 `python <script>` 运行）与完整方法论文档见 `evalharness/fingerprint/fp_fusion_介绍.md`
+
+## 附录 B：架构
 
 ```
 data/      统一 Sample schema，惰性物化，内容寻址缓存（28 个单文件插件）
@@ -242,11 +310,19 @@ progress/  Rich 每样本进度（缺 rich 自动降级）
 
 层间严格分离：数据层只回答"题目与金标"，判分层只回答"如何评判"，模型层只回答"如何触达"；预测是不可变 artifact。
 
-## 8. 对齐验证
+## 附录 C：常见问题
 
-prompt 与判分器经双层验证（字符串级：同一记录双侧渲染逐字节一致；分数级：同题同参数对比 evalscope）：
+**端点不可达（ConnectError，跑样本前即中止）**
+探针在首个样本前发 1-token ping，失败即给出 curl 验证命令并中止，零 token 浪费。按提示 `curl -m 5 <api-url>/chat/completions ...` 手工确认服务在跑。
 
-- Qwen3-8B：23/28 分差 < 0.05
-- DeepSeek-V4-Flash：20+/25 分差 < 0.05（mmlu_pro 0.0000）
+**上下文溢出（400 maximum context length）**
+自动截短 prompt 15% 重试（跨 tokenizer 安全边际，1-2 次收敛）；`max_input_tokens`（YAML）可预先做中段截断，长上下文 bench 建议配置。
 
-残差均已定性（金标集差异 / 排列敏感 / benchmark 侧缺陷），见各 recipe 注释。
+**思考模式（thinking）关不掉？**
+`--disable-thinking` 走 `chat_template_kwargs`，非流式请求完全生效（sglang/vLLM 已验证）。注意：部分网关在**流式**路径会剥掉该参数——本框架仅在 `max_tokens > 100000` 时自动转流式（聚合还原为非流式响应），常规 8k/32k 预算不受影响。智谱云 API 风格的 `thinking: {"type": ...}` 参数 sglang 不识别，自建端点请用本框架的开关。
+
+**GLM 大预算生成挂起**
+非流式大 body（100k+ token 输出）部分网关会缓冲到超时；自动流式路径已内置（见上条），无需手工干预。
+
+**Docker 拉镜像慢/失败**
+`EVALHARNESS_DOCKER_MIRRORS="mirror.example.com/{img},docker.io/{img}"` 覆盖回退链。
diff --git a/evalharness/config/README.md b/evalharness/config/README.md
index 3fbc609..723b307 100644
--- a/evalharness/config/README.md
+++ b/evalharness/config/README.md
@@ -1,63 +1,60 @@
 # 配置目录
 
-每个模型/协议一个文件夹，内含逐 bench 的 YAML 配置。
+逐 bench 生成参数的 YAML，`eval run` 时自动应用。
 
 ```
 config/
-├── README.md              ← 本文件
-└── dp4-nothink/           ← 模型/协议名
-    ├── default.yaml       ← 协议级默认参数（所有 bench 继承）
-    ├── aime24.yaml        ← 逐 bench 覆盖
-    ├── aime25.yaml
-    ├── ...
-    └── swe_bench_verified.yaml
+├── README.md        ← 本文件
+└── default.yaml     ← 当前唯一配置（自动加载）
 ```
 
-## 每个 YAML 的结构
+## YAML 结构（单文件，扁平键）
 
 ```yaml
-# generation: 传给模型的参数
-generation:
-  temperature: 1.0
-  max_tokens: 8192
+default:                # 协议级默认，所有 bench 继承
+  temperature: 0.0
   top_p: 1.0
+  max_tokens: 32768
 
-# run: 运行方式
-run:
-  repeats: 12          # 跑 12 遍取均值（temp=1 方差测量用）
-  limit: null          # 全量 / limit_per_task: 10 每子集 10 条
-  checkpoint: true
-  resume: true
+aime25:                 # 逐 bench 覆盖（键与 default 同级合并）
+  temperature: 1.0      # temp=1 方差测量
+  max_tokens: 8192
+  repeats: 12           # 跑 12 遍报均值；断点按轮隔离（:rep2 :rep3 ...）
 
-# judge: LLM-judge 类 bench 需要
-judge:
-  model: dp4-flash
-  api_url: http://174.1.51.4:30000/v1
+longbench_v2:
+  max_tokens: 8192
+  max_input_tokens: 128000   # 超长输入的 tokenizer 中段截断预算
 ```
 
+## 支持的键
+
+| 键 | 作用 |
+|---|---|
+| `temperature` `top_p` `max_tokens` | 生成参数，直传模型 |
+| `max_input_tokens` | 输入截断预算（tokenized 中段截断，头部尾部保留） |
+| `repeats` | 该 bench 重复轮数；summary 报均值，时间/token 报总和 |
+
 ## 优先级
 
 ```
-DatasetSpec.gen_config  <  default.yaml  <  <bench>.yaml  <  命令行显式参数
+DatasetSpec.gen_config  <  default 段  <  bench 段  <  命令行显式参数
 ```
 
 ## 使用
 
 ```bash
-# 单 bench
-evalharness eval run aime25 --config dp4-nothink --api-url ... --model ...
+# 目录里只有一个 yaml 时自动加载；--config 显式指定（省略 .yaml 后缀）
+evalharness eval run aime25 --config default --api-url ... --model ...
 
-# 多 bench（自动读各自的 yaml）
-evalharness eval run aime24 aime25 aime26 hmmt26 --config dp4-nothink ...
-
-# 查看某 bench 的生效配置
-evalharness config show dp4-nothink aime25
+# 多 bench：各自读自己的段
+evalharness eval run aime24 aime25 aime26 hmmt26 --config default ...
 ```
 
-## 新增模型配置
+## 新增一套配置
 
 ```bash
-mkdir config/qwen3-es-parity
-cp config/dp4-nothink/default.yaml config/qwen3-es-parity/
-# 编辑 default.yaml，然后按需添加逐 bench 覆盖
+cp default.yaml glm53-nothink.yaml   # 编辑后
+evalharness eval run aime25 --config glm53-nothink ...
 ```
+
+注意：同时存在多个 yaml 时不自动加载，必须 `--config` 指明。