# 本次修订与验证

## 目录清理、去敏与文档合并（本轮）

### 身份信息去敏（队号改为运行期参数）

队号属身份信息，不再出现在代码、测试、示例与文档中：

- `src/mcm26b/cli.py`：`sim-check` 的 `--robot-id` 默认值由真实队号改为与赛事无关的
  `SIMCHECK`；`run` 子命令本就 `required=True`。**对接官方模拟器的队号一律由命令行传入**。
- `src/mcm26b/harness/simulator.py`、`referee/src/referee/simulator.py`：
  `robot_id` 由带默认值改为**必填**，杜绝把队号固化进可提交代码。
- `scripts/run_practice_episodes.py`：`--robot-id` 改为必填。
- `scripts/build_core_notebook.py` 及重新生成的 `mcm26b-核心代码.ipynb`：
  离线自检单元用中性标识 `OFFLINE`；命令示例同步为 `python -m mcm26b.cli run`。
- 测试、`README.md`、`referee/README.md`、referee WebUI 提示文本：
  真实队号统一替换为中性占位符 `TEAM-0001`。
- `referee-data/` 与 `examples/replay/` 下的演练/正式日志（共 110 个文件）：
  `robot_id` 字段统一为中性占位符，**位置、示向度、时间等证据字段原样未动**；
  改后复算结果完全一致（44 局全清、计时偏差仍为 0.000000 s）。

### 清理无用文件

- 删除本机工作区 `tmp/`（43 MB，含历史留档、截图与中间草稿）、`.zcode/`；
- 删除论文不再使用的 MATLAB 出图链路：`scripts/matlab/`（17 个文件）、
  `scripts/build_figure_data.py`、`scripts/render_q1_figures.py`；
  论文插图现全部由 `scripts/plot_paper_figures.py` 生成；
- 删除 LaTeX 陈旧产物（`main-updated.pdf`、`main-check.*`、`main copy.*`）与
  未被引用的 `docs/paper/sections/comparison.tex`；
- 删除 `docs/figures/flow-overall-architecture.png` 及其生成函数：
  对应的四层主线图已从论文中移除，不再有插图引用它。

### 优化 .gitignore

按"只跟踪可复现结果所需的最小集合"重写，补齐 Python/构建/编辑器/操作系统条目，
新增忽略 `docs/paper/support-materials.zip`（脚本产物）、`.piptmp/`、`uv-temp/`、`pip-temp/`、
`.idea/`、`.zcode/`；保留 `referee-data/` 的版本控制并注明其身份信息已去敏。

### 文档合并到 README

论文已完整给出四问的模型、推导与结果分析，故删除 13 份算法与设计说明文档
（`docs/algo-*.md`、两份优化方案、示意图册、总体思路、执行时间、协议规则表、
最优与基线对比、论文列表），只保留复现所必需的说明：

- 根 `README.md` 重写为单一操作手册：环境 → 运行程序 → 自建模拟器 →
  复现论文数据 → 复现插图 → 编译论文 → 单文件核心代码与测试 → 目录结构；
- `docs/README.md` 改为最小索引；
- `docs/paper/README.md` 与 `docs/figures/README.md` 同步更新（数据分工、重算与编译步骤、
  插图清单与来源）。
- 源码/测试/脚本中原先指向被删文档的注释，统一改为指向论文对应章节，不留悬空引用。

### 验证

- `uv run pytest tests referee/tests`：**263 passed, 5 skipped**
  （5 项为需要 `output/q1/practice` 官方演练采集的可选夹具，缺失时按 skip 处理）；
- `python scripts/build_practice_data.py`：44 局复算，计时偏差 0.000000 s；
- `scripts/build_paper_support.py --package`：278 个文件、3.6 MB，未超 20 MB；
- `latexmk -xelatex -outdir=build`：56 页，无未解析引用、无超宽表格；
- 绘图脚本无告警，`docs/figures/` 只保留论文实际引用的 10 张 PNG。

## VS Code 配方与图 2 箭头（前轮）

- **LaTeX Workshop 默认配方换成与本项目编译口令一致的配方**：
  `.vscode/settings.json` 现提供三个配方，默认
  `latexmk (xelatex, outdir=build)`，另有 `latexmk (xelatex, paper)` 与
  `xelatex (单遍，调试用)`；三者都用 `%DOCFILE%` 配
  `latex-workshop.latex.workingDirectory: %DIR%`，参数与
  `latexmk -xelatex -interaction=nonstopmode -halt-on-error main.tex` 对齐。
  两条 latexmk 配方均已实测：多遍编译后均为 57 页、无未解析引用。
- **默认写 `build/` 的真实原因**：Windows 下 PDF 预览会锁住已打开的
  `docs/paper/main.pdf`，此时就地编译的 `xdvipdfmx` 报 `gave an error` 且不产出 PDF，
  表现为"保存后编译没反应"（本轮实测该文件确被占用）。
  写到 `build/` 后预览读 `docs/paper/build/main.pdf`，与源码目录互不抢占，
  `autoBuild.run: onSave` 才能稳定工作；需就地产出时切换配方并先关闭预览。
  该目录已在 `.gitignore` 中。
- **图 1 箭头重叠**：原来四条 L2→L3 的箭头收在同一个点上，箭头头部挤成一团。
  现改为先接到 L3 上方的一条汇流线，再由单个箭头进入 L3；线不交叉、箭头不重叠。
- **图 2 箭头穿框**：原来四条箭头从 L2 框的顶边出发、并在框内斜穿，
  终点又都落在一起。现改为从框的底边出发汇入一条水平汇流线，
  再由单箭头落到 L3 顶边；闭环回路的四个箭头也改为严格从框边到框边。
  同时删去与文本框重叠的"闭环"标注，并把画布裁到内容外沿。
- 复算：`latexmk -xelatex` 通过，57 页，无未解析引用、无超宽表格；绘图脚本无告警。

## 图 5 重做、删除图 11、射线加粗（前轮）

- **修复图 5(a) 空白**：上一轮把坐标范围写死为 $x\in[-400,1900]$、$y\in[-400,1400]$，
  而该算例的观测点与定位区域都在 $(560,-1570)$ 附近，整幅画面因此落在视野之外，
  角域交会示意只剩坐标轴。现改为**由观测点与定位区域的外包框自动确定视野**，
  并保留足够边距，两者同时入画。
- **图 5 三幅等高**：把原"交会+放大"两幅图与独立的等边三角形反例合并为一张三幅图
  （`geo-q1-geometry.png`），三幅统一取 $1.15$ 的高宽比与相同宽度，
  轴框尺寸完全一致，版面高度严格相等；正文引用宽度改为整栏。
  合并后省去一次浮动与一个图注，原来的两张 PNG 与 `fig_q1_counterexample` 一并删除。
- **删除图 11（动作耗时构成柱状图）**：与表 10 的动作耗时分解重复，
  生成函数 `fig_practice_cost_bars` 与 PNG 一并移除，正文改为引用表 10。
- **图 9、图 10 射线加粗**：示向度射线由 $0.5$ pt、透明度 $0.5$ 提高到 $1.1$ pt、透明度 $0.75$
  并改实心端帽；检测点标记同步放大（圆点 $16$、菱形 $18$、叉号 $12$），
  轨迹线 $1.0\to1.4$ pt；两图在正文中由 $0.85$ 放大到 $0.94$ 栏宽。
- 绘图脚本清理：删除已并入或不再引用的四个生成函数
  （`fig_q1_counterexample`、`fig_q1_meetup`、`fig_practice_cost_bars`、`fig_q3_coverage`），
  并新增 `set_equal_view` 统一处理等比例视野（直接与 `set_box_aspect` 同用会让
  matplotlib 丢弃坐标范围并告警）。
- 复算：`latexmk -xelatex` 通过，57 页，无未解析引用、无超宽表格；绘图脚本无告警。

## 版面精简与可读性（前轮）

- **摘要压缩**：删除"结论：1.2.3."与全部定量数字，只说明本文针对四问各做了什么工作，
  结尾一句交代数据分工，整页容下摘要与关键词。
- **图 1、图 2 紧凑化**：两张流程图的画布分别由 $8.0\times4.8$ 与 $5.8\times4.2$ 英寸
  收紧到 $7.6\times4.9$ 与 $7.6\times5.3$，并按最终缩放比例重设字号；
  正文引用宽度改为 $0.74$ 与 $0.62$，不再各占近半页。
- **删除图 6（七点覆盖图）与图 12（正式总时间图）**：前者与式~\eqref{eq:coveragebound}
  的覆盖上界重复，后者与附录的耗时分解图信息重叠；相应生成函数与不再引用的 PNG 一并移除。
- **图 9、图 10 射线加粗**：示向度射线由 $0.5$ pt、透明度 $0.5$ 提高到 $1.1$ pt、透明度 $0.75$
  并改为实心端帽；检测点标记同步放大（圆点 $16$、菱形 $18$、叉号 $12$），
  轨迹线由 $1.0$ pt 加粗到 $1.4$ pt；两图在正文中由 $0.85$ 放大到 $0.94$ 栏宽。
- **删除"未来工作"与"模型推广"**：`evaluation.tex` 只保留"模型的有效性"与
  "参数影响的解析讨论"；q4 中指向未来工作的小节引用同步删除。
- **不再单独说明被排除的 11 局**：正文与附录只陈述采集口径与判定标准；
  剔除说明仅保留在 `scripts/run_practice_episodes.py`、本文档与
  `referee-data/rejected-sessions/`（原日志仍保留，可复核）。
- 复算：`latexmk -xelatex` 通过，57 页，无未解析引用、未定义文献与超宽表格。

## 行文风格重写（前轮）

- 摘要与问题分析改为“背景条件 → 建模动机 → 分析方法 → 推导结果”的逻辑链，
  在段落内部用“由条件可知”“为探究”“在此基础上”“综上可得”等连接词串联，
  并在每个问题的推导结束后以“结论：1. 2. 3.”提炼核心发现。
- 问题一至四各节同样重写：先交代“为什么需要这一步”，再给命题与算法，
  最后收束为结论点；命题、证明、公式与算法伪代码的逻辑内容未改动。
- 清理重复论述：模型假设项中的换行、未来工作中重复出现的“样本量有限”一段已合并。

## 数据论证改为自建模拟器演练局（本轮）

- 正文全部定量论据改取自项目内自建模拟器（`referee/`）的演练局：问题三 15 局、问题四 10 局，
  源数覆盖 10 至 16；全清局共 19 局，累计清除 261 个源且清除失败为零。
- 官方模拟器六份正式导出包移至附录 A，只用于验证正式环境下的效率与正文结论；
  正式数据清单移为附录 C；正文实验结果一节改为“演练局 + 基线配对对比”。
- 新增 `scripts/build_practice_data.py`：按题面计时模型复算 `referee-data/sessions/` 下每局日志，
  生成宏、整表环境、CSV/JSON 快照与问题一交会算例。
  复算累计虚拟时间与评测机日志记录的最大偏差为 0.000000 s。
- 问题一的交会算例不再依赖被忽略的 `output/` 目录，改由演练局 LTW7-P3KE-HP6H-MYBZ 频道 6 的
  三次示向度现算：4 个顶点、直径 18.837 m、直径圆超出 0.872 m、最小包围圆半径 9.462 m，
  仍保持“直径圆不覆盖、最小包围圆可清除”这一关键对比。
- 新增插图 `practice-virtual-time.png`、`practice-cost-bars.png`；
  正式测试的两张图移入附录。

## 排版与工程修正（本轮）

- 全部图注与表题改为中文，并补齐“图/表 + 编号”的引用一致性。
- 修复 `data/*.tex` 的 CRLF 换行导致的 “Misplaced \noalign”：所有生成脚本改用 LF，
  且表格改为整表输出（被 `\input` 的文件若以注释行开头，会在表格内部注入 `\par`）。
- 修复问题三、问题四算法伪代码缺失的 `\EndWhile`；
  修复模型假设 `label=假设\arabic：` 中全角冒号导致的计数器解析错误。
- 修复 `scripts/build_paper_support.py` 读正式快照时缺少 `virtual_time_s` 等 CSV 字段的问题，
  以及支撑包未收录自建模拟器与演练日志的问题。
- 复算：`latexmk -xelatex` 通过，59 页，无未解析引用、未定义文献与超宽表格。

## 演练局数据重采（本轮）

### 问题：留档里混入了算法未优化完全时的脏数据

复核历史留档发现两类不能代表当前实现的局：
- 一局问题三演练出现 $33$ 次失败清除、虚拟时间 $8568$ s（同期其他局约 $3000$ s）；
- 问题四有 $6$ 局在"最终清完"的同时出现 $3$ 至 $114$ 次失败的 $\mathtt{/clear}$ 试探，
  以及 $2$ 局未清完全部源。

它们的共同特征是定位长期无法收缩、后备清除反复打空，
总虚拟时间与检测次数被无效试探撑大，因此不能作为性能证据。

### 重采方式

新增 `scripts/run_practice_episodes.py`：启动评测机 `referee`、按固定种子
`judge.start("q3_practice"|"q4_practice", seed=...)` 开始一局演练，
再用与 `mcm26b.cli run` 相同的生产策略对接 HTTP 接口。
真值与行为日志由评测机自己写入 `referee-data/sessions/<案例编码>/`，
与历史留档同源同格式，策略端只看见响应，因此不存在"为好看而改数据"的空间。

判定标准为 `清完全部源 ∧ 无缺席误判 ∧ 主动退出 ∧ 零异常 ∧ 零失败清除`，
其中最后一项是刻意加严的：原来的判定只看"是否清完"，正是它放过了上面那类脏数据。

### 采集结果

| 问题 | 种子 | 采到局数 | 有效局 | 被排除 |
| --- | --- | ---: | ---: | --- |
| 三 | 300--314 | 15 | 15 | 0 |
| 四 | 400--439 | 40 | 29 | 11 |

被排除的 $11$ 局移入 `referee-data/rejected-sessions/`（日志保留，可复算复核），
历史留档整体移入 `referee-data/superseded-sessions/`。
论文只引用声明的批次：`scripts/build_practice_data.py` 按案例编码白名单过滤，
批次外留档一律不进入统计。

新批次共 **$44$ 局，全部清完全部源且失败清除为零**，累计清除 $557$ 个源：
问题三 15 局平均总虚拟时间 $3261.579$ s，问题四 29 局平均 $8401.445$ s，
移动时间占比 $78.1\%$ 与 $75.8\%$，复算计时与日志记录的最大偏差仍为 $0.000000$ s。

### 连带更新

- 正文主局改用批次内的案例：问题三 `QS6H-CC29-PDY3-ZA54`（16 源）、
  问题四 `SWA3-C3FB-C5QC-FLW7`（16 源，其中 8 个定向源）；
- 问题一交会算例改用批次内 `8VRC-ADW4-XDXM-F62L` 频道 12：
  5 个顶点、直径 $22.187$ m、直径圆超出 $4.140$ m、最小包围圆半径 $11.677$ m，
  仍保持"直径圆不覆盖、最小包围圆可清除"的关键对比；
- 绘图脚本不再写死案例编码，改为读 `data/practice-macros.tex` 中的主局宏，
  避免正文与插图口径分叉；
- 摘要、实验设置、结论与附录 B 的局数、均值、占比全部改为引用宏，不再手写数字。

## 插图可读性修正（前轮）

- 问题四的 31 点计划图原来把一枚前向半盘楔形压在站点云与轨迹附近，语义不明。
  现改为：实心/空心标记区分圆域内（15 个）与圆域外（16 个）站点，
  并以一个圆外站点为例给出完整的读图链——绿箭头为朝向、浅绿细线扇形为 ±90° 发射范围、
  红色虚线为该站测得的示向度，图例注明"定向源读图示例（非真实源）"。
- 搜索路径图原来没有标出检测发起位置与检测结果。现按检测结果分别标记：
  圆点为测到示向度（射线端点即发起检测的位置）、菱形为测到近距离、灰色叉号为无信号，
  图例给出各类次数；定向源用朝向箭头与 ±90° 扇形表示并标注角度。
- 全向源局不再出现定向源图例文字，避免图上没有对应元素的说明。
- 图注同步改写，逐项说明图中符号与次数；docs/figures/manifest.json 补齐四张图的来源。
- 复核：latexmk -xelatex 通过，59 页，无未解析引用与超宽表格。

## 正式数据补充（前轮）

加入问题三第三次 UVUZ-B4MQ-XSUV-HQFP 和问题四第三次 K58B-V5VC-E4EF-CRTW。
两份文件均通过原始导出、结果侧文件和官方统计记录的对应校验。

| 案例 | 清除数 | 平均定位清除时间（s/个） | 程序运行时间（s） |
| --- | ---: | ---: | ---: |
| Q3-3 | 10 | 290.686 | 2.680 |
| Q4-3 | 14 | 614.884 | 6.051 |

六次累计清除 75 个源。问题三合计 38 个，问题四合计 37 个。
正式结果表、汇总公式、动作耗时图、数据清单与支撑包统一使用六份记录。

## 数学表述（前轮）

用“清除充分条件”“半径判据”替换“证书”；
用“检测状态矩阵”替换“账本”；
用“最近邻任务排序”替换“调度骨架”；
采用集合估计、关联矩阵、离散集合覆盖、网格候选集等已有概念。
实现扩展及评价限制集中于未来工作。数学证明中的必要条件、反例与适用假设保持明确。

## 模板与验证

mcm26b-paper.cls 保持与原仓库模板逐字节一致，文档沿用原模板的黑体标题及版式。
使用 latexmk 自动多遍编译并检查文献、公式、图表引用。
正式统计按官方整数微秒和毫秒计算，支撑包提供 SHA-256 清单供复核。

## 清理论文与源码附录

- 清除 7 个文件中已提交的 git 冲突标记，冲突块统一取 PNG 图版一侧。
- 附录不再逐字排版全部源码，改为“核心程序代码”：只列四问主线核心函数 32 个、约 1300 行，
  每个附一句中文说明；数学符号在 main.tex 的 corecode 样式里统一映射。