Document match-scoped sample paths and draft-session timing lessons.

Capture the prototype findings on top-bar skins, strategy_tail polling, and why CDN-only plus session policy is enough without a real template library.

Co-authored-by: Cursor <cursoragent@cursor.com>

DESIGN.md

@@ -68,7 +68,13 @@ Valve 已明确关闭普通玩家视角的实时 draft
 
 - 选人阶段：多帧确认、允许更高分改判（`revise_gain`）
 - 决策阶段：只补空槽、禁止改判（避免皮肤顶栏覆盖默认脸结论）
-- best 帧优先选人阶段默认脸
+- best 帧优先选人阶段默认脸（`recognized` 相同时）
+- 本人英雄以 GSI `hero` 覆盖视觉结果（只覆盖自己的槽）
+
+**⑤ 截图按对局归档**
+
+GSI 会话写入 `samples/raw/{matchid}/`；手动 `capture.py` 仍写 `samples/raw/` 根目录。
+结果 JSON 仍为 `results/draft_<时间戳>.json`（内含 `match_id`）。
 
 ---
 
@@ -88,6 +94,15 @@ Valve 已明确关闭普通玩家视角的实时 draft
 
 CDN-only 开箱即用后，「打几十局攒默认脸」不再是主路径。项目改为只维护 CDN。
 
+后续审计（迁出前原型库）进一步确认：
+
+- 标注集上大量 `score=1.000` 往往是「从同帧裁进 real 再评同帧」的自证，夸大了 real 贡献。
+- 剩余 real 与 CDN（天梯遮罩）多数 ≥0.85，近乎 CDN 副本；明显偏离的极少（如军团指挥官一类边缘格）。
+- **近期问题局**（宙斯缺槽、斯拉达 CDN 分低、敌法末位、皮肤帧风行者 0.415）主要靠
+  **多帧会话 + 决策禁改判 + GSI 补自己** 凑齐，不是靠 real。
+- 皮肤变体极多，入库皮肤模板不合理；段位条/徽章每人不同，匹配时已用遮罩忽略，
+  也不该为不同段位重复存图。
+
 ### 发现三：自动标定靠玩家颜色条
 
 10 条固定玩家色定位槽位；中心用中位数槽距拟合（剔除被身后头像污染的宽条）；
@@ -109,6 +124,27 @@ GSI 不含可靠 lobby 类型时，用右下金色勋章检测（`has_ranked_ove
 定位局位置字用二值 IoU（非 OCR）。「我」优先 GSI `team_slot`；
 否则姓名亮度相对差（最亮比次亮 ≥ 25）兜底。
 
+### 发现七：客户端顶栏时机（会话策略前提）
+
+这些是实战纠正后的事实，改 `DraftSession` 时不要违背：
+
+| 现象 | 含义 |
+|------|------|
+| 顶栏默认脸 → 皮肤 | **全员选完后**才换皮肤立绘，不是一进决策就换 |
+| 本机已进 `STRATEGY_TIME` | 别人可能还在选；**不能**一进决策就永久停视觉 |
+| 空槽红旗倒计时 | 只出现在**未选**槽；揭晓后消失，不是挡脸主因 |
+| GSI | **没有**「皮肤已加载」字段；无法精确卡「人选完、皮肤前」单帧 |
+
+因此正确节奏是：选人 + 决策前期持续读，直到确认 10/10 或 `strategy_tail_polls` 用尽；
+凑齐后停视觉，再短等 GSI 补本人英雄。单帧皮肤弱识别（如决策 3D 模型挡顶栏）属预期，
+靠会话回填，不靠降阈值或堆皮肤模板。
+
+### 发现八：揭晓淡入需要可改判
+
+首帧揭晓常半透明 + 段位条，易误认（例：剑圣揭晓瞬间被认成幽鬼）。
+`confirm_polls` 后若仍禁止改判会锁死错误。选人阶段允许
+`score ≥ was_score + revise_gain` 的稳定新结果覆盖；决策阶段则关闭改判。
+
 ---
 
 ## 4. 代码结构
@@ -122,10 +158,10 @@ climperor/
 ├── autocalibrate.py / calibrate.py / capture.py
 ├── evaluate.py / roles.py / grid.py / modes.py
 ├── templates/cdn|roles|modes/
-└── samples/labels.json          # 评测真值；raw/ 见 .gitignore
+└── samples/labels.json          # 评测真值；raw/<matchid>/ 见 .gitignore
 ```
 
-运行时目录 `preview/`、`results/`、`failures/`、`samples/raw/` 不入库。
+运行时目录 `preview/`、`results/`、`failures/`、`samples/raw/`（含按对局子目录）不入库。
 
 ### 主要配置
 
@@ -135,8 +171,9 @@ climperor/
 | `match.ranked_mask` | 天梯遮罩比例 | bottom 0.32, right 0.22 |
 | `gsi.port` | 监听端口 | 3223 |
 | `gsi.confirm_polls` | 连续同结果帧数 | 2 |
-| `gsi.revise_gain` | 改判所需分数增益 | 0.15 |
+| `gsi.revise_gain` | 选人阶段改判所需分数增益 | 0.15 |
 | `gsi.strategy_tail_polls` | 决策阶段继续视觉轮询 | 8 |
+| `gsi.strategy_gsi_wait` | 视觉结束后等待本人 GSI 英雄 | 3.0 |
 
 ---
 
@@ -149,10 +186,12 @@ Dota 2 (-gamestateintegration)
   → results/draft_*.json
 ```
 
-要点：按 `matchid` 去重；识别在工作线程；未标定时降级为只截图。
+要点：按 `matchid` 去重；截图进 `samples/raw/{matchid}/`；识别在工作线程；
+未标定时降级为只截图。
 
 天梯 AP 选人按 2/2/1 成批揭晓，本轮结束前互不可见——因此必须在
-**HERO_SELECTION** 跟踪，不能只在决策时间截一张终局图。
+**HERO_SELECTION** 跟踪，不能只在决策时间截一张终局图；决策前期仍读几帧
+以吃到最后一人揭晓（见发现七）。
 
 ---