diff --git a/README.md b/README.md
index 7a24bfe..f85aef6 100644
--- a/README.md
+++ b/README.md
@@ -106,7 +106,7 @@ rep.save('gsm8k.report.json')
 | `--env NAME` | agent 环境（`bfcl_mock` 等） |
 | `--perf` | 采集流式 TTFT / ITL / 重试率入报告 |
 | `--hf-endpoint URL` | 数据下载端点（如 `https://hf-mirror.com`，免手动 export） |
-| `--cache-dir DIR` | 缓存根（数据缓存 + 断点同根） |
+| `--cache-dir DIR` | 缓存根目录（数据缓存 + 断点同根；默认 `$EVALHARNESS_CACHE` 或 `~/.cache/evalharness`） |
 | `--out FILE` / `--out-dir DIR` | 报告落盘；多 bench 时写 `reports/` + `viz/` + `summary.md` |
 | `--style text\|md\|md_compare\|excel\|radar\|errors` | 结果渲染样式 |
 | `--no-progress` | 关闭 Rich 进度条（重定向日志时用） |
@@ -133,6 +133,15 @@ evalharness data show gsm8k -n 2                # 看前 2 条样本
 evalharness data unload gsm8k                   # 删缓存
 ```
 
+- 缓存根目录由 `--cache-dir` 指定（或环境变量 `$EVALHARNESS_CACHE`，默认 `~/.cache/evalharness`），结构：
+
+```
+<cache-dir>/
+├── datasets/<bench>/<subset>_<split>-<hash>/   数据缓存（raw/ 原始字节 + samples.jsonl 统一样本）
+├── .raw/<repo-hash>/                           跨条目共享的下载 blob（多子集只下载一次）
+└── ckpt/<bench>[_<subset>].jsonl               预测断点（每条完成即追加）
+```
+
 - 数据缓存内容寻址（subset/split/source 变更自动新条目），位置 `<cache-dir>/datasets/`
 - 断点每条预测即写盘；**改了 prompt 模板须删旧断点**（`rm <cache-dir>/ckpt/<bench>*.jsonl`），否则复用旧预测
 - 网络抖动三层防护：15s 连接超时快速失败 → 池内换端点 → 分钟级退避重试，断网不丢批次