123

docs/figures/README.md

@@ -0,0 +1,62 @@
+# docs/figures —— 论文插图
+
+每张图只输出 PNG，由 `scripts/make_figures.py` 用 matplotlib 生成。
+`manifest.json` 记录每张图的数据来源（路径 + sha256 前 12 位 + 行数）与生成命令。
+
+```bash
+uv run python scripts/make_figures.py                 # 全部 11 张
+uv run python scripts/make_figures.py --list          # 图名
+uv run python scripts/make_figures.py --only geo-q3-seven-point-coverage
+uv run python scripts/make_figures.py --scale 1.5     # 整体放大（尺寸倍率）
+```
+
+依赖：`matplotlib`、`Pillow`、`docs/paper/fonts/` 下的字体。
+`matplotlib` 缓存写入仓库内 `.mpl-cache/`，不污染用户目录。
+
+## 约定
+
+- 图内不放标题、图注与解释性文字，只保留坐标轴、图例与数据标注；
+  图的含义由文件名与下表承担，解释写在论文正文。
+- 配色（`scripts/make_figures.py::C`）：深蓝 `#1f4e79` 主流程与协议，
+  砖红 `#b03a2e` 真值源与关键结论，墨绿 `#1e7a5f` 清除与通过项，
+  土黄 `#b8860b` 后备与警示，灰色只用于网格与次要文字。
+- 字体：中文宋体 `SongtiSC-Regular/Bold`，标题黑体 `HeitiSC-Light/Medium`，
+  数字与西文 Times New Roman，均取自 `docs/paper/fonts/`，与 `main.tex` 一致。
+- 输出为 PNG（`savefig.dpi = 200`，另有 `--scale` 倍率），按 160 mm 宽排版时
+  与正文同字号。
+
+## 图清单
+
+| 文件 | 内容 | 数据来源 |
+| --- | --- | --- |
+| `flow-overall-architecture.png` | 总体思路：题面抽象、在线三层、四问主线、三条闭环 | `src/mcm26b/config.py`、`docs/B题建模分析与实施计划.md` |
+| `steps-state-machine.png` | 会话状态机（IDLE / 倒计时 / OPEN / CLOSED） | `docs/协议规则表与状态机.md`、`src/mcm26b/protocol/client.py` |
+| `timing-attachment-example-105-111-194-199.png` | 附件计时示例逐步推演 | `docs/协议规则表与状态机.md` |
+| `timing-measured-q3-10-sources.png` | 实测一局的虚拟时间分解（累计曲线 + 构成） | `referee-data/sessions/BBM9-HZG2-77N5-NKKC/log.jsonl` |
+| `geo-q1-convex-intersection-zoom.png` | 问题一：角域交会总览 + 定位区域放大（直径圆与 MEC） | `output/q1/practice/U5ZW-P9KN-TCAG-R7ST_observations.json` |
+| `geo-q1-diameter-circle-counterexample.png` | 问题一：直径圆不覆盖的反例（等边三角形布站） | `examples/q1/triangle.json` |
+| `geo-q2-guaranteed-reception-disk.png` | 问题二：候选盘、截断角域外接圆、安全盘 `B(c, 1000−a)` | `src/mcm26b/config.py`、`docs/algo-2.md` |
+| `geo-q3-seven-point-coverage.png` | 问题三：七点覆盖（7 个 1000 m 接收盘的并集覆盖 Ω）与三套计划对比 | `src/mcm26b/planner/seven.py`、`docs/algo-3.md` |
+| `geo-q4-minimum-cover-31-points.png` | 问题四：31 点最小命中集与 `forward_half_disk` 语义 | `src/mcm26b/guarantee/plans/q4_mincover_v2.json` |
+| `replay-webui-q3-omnidirectional.png` | WebUI 回放画布复现（全向局，10 源全清） | `referee-data/sessions/BBM9-HZG2-77N5-NKKC/log.jsonl` |
+| `replay-webui-q4-directional.png` | WebUI 回放画布复现（定向源局） | `referee-data/sessions/GM56-DFXZ-XKDM-XYV7/log.jsonl` |
+
+后两张对应 WebUI 的预览功能：把回放器画布上的 Ω 与真值源、运动轨迹、
+检测示向度射线、清除标记，以及右侧事件流水与底部虚拟时间轴一起导出。
+
+## 数据来源与复现
+
+- `timing-measured-*`、`replay-webui-*` 读评测机行为日志（JSONL，含真值）。
+  `referee-data/` 被 `.gitignore` 忽略，因此另归档两局到 `examples/replay/`；
+  没有评测机数据时脚本自动改读归档，图一致。
+
+  ```bash
+  uv run python scripts/archive_replay_logs.py --list        # 本机有哪些局
+  uv run python scripts/archive_replay_logs.py <案例编码>     # 追加归档
+  ```
+
+- `geo-q1-convex-intersection-zoom.png` 读官方演练留档
+  `output/q1/practice/*_observations.json`（同样被忽略）。文件缺失时改读
+  `examples/q1/triangle.json` 反例算例，图仍可用，只是案例不同。
+- 问题一的几何量由生产求解器 `mcm26b.geometry.solve` 现算；
+  问题三、问题四直接读覆盖计划与证书，不手抄数字。

docs/figures/manifest.json

@@ -0,0 +1,192 @@
+{
+  "generator": "scripts/make_figures.py",
+  "command": "uv run python scripts/make_figures.py",
+  "palette": {
+    "ink": "#1c2430",
+    "muted": "#5c6673",
+    "grid": "#e4e9ee",
+    "primary": "#1f4e79",
+    "primary_fill": "#dce6f1",
+    "accent": "#b03a2e",
+    "accent_fill": "#f6dcd8",
+    "success": "#1e7a5f",
+    "success_fill": "#d8ece5",
+    "warn": "#b8860b",
+    "warn_fill": "#f6ecd2",
+    "violet": "#5b4b8a"
+  },
+  "fonts": {
+    "dir": "docs/paper/fonts",
+    "map": {
+      "song": "SongtiSC-Regular.ttf",
+      "song_bold": "SongtiSC-Bold.ttf",
+      "hei": "HeitiSC-Light.ttf",
+      "hei_bold": "HeitiSC-Medium.ttf",
+      "times": "Times New Roman.ttf",
+      "times_bold": "Times New Roman Bold.ttf"
+    }
+  },
+  "figures": [
+    {
+      "stem": "flow-overall-architecture",
+      "png": "docs/figures/flow-overall-architecture.png",
+      "scale": 1.0,
+      "sources": [
+        {
+          "path": "src/mcm26b/config.py",
+          "sha256_12": "c513450dc892",
+          "lines": 213
+        },
+        {
+          "path": "docs/B题建模分析与实施计划.md",
+          "sha256_12": "537aaa5790f3",
+          "lines": 237
+        }
+      ]
+    },
+    {
+      "stem": "steps-state-machine",
+      "png": "docs/figures/steps-state-machine.png",
+      "scale": 1.0,
+      "sources": [
+        {
+          "path": "docs/协议规则表与状态机.md",
+          "sha256_12": "27c8f7051b26",
+          "lines": 215
+        },
+        {
+          "path": "src/mcm26b/protocol/client.py",
+          "sha256_12": "0e9797a85cd7",
+          "lines": 333
+        }
+      ]
+    },
+    {
+      "stem": "timing-attachment-example-105-111-194-199",
+      "png": "docs/figures/timing-attachment-example-105-111-194-199.png",
+      "scale": 1.0,
+      "sources": [
+        {
+          "path": "docs/协议规则表与状态机.md",
+          "sha256_12": "27c8f7051b26",
+          "lines": 215
+        }
+      ]
+    },
+    {
+      "stem": "geo-q1-convex-intersection-zoom",
+      "png": "docs/figures/geo-q1-convex-intersection-zoom.png",
+      "scale": 1.0,
+      "sources": [
+        {
+          "path": "output/q1/practice/U5ZW-P9KN-TCAG-R7ST_observations.json",
+          "sha256_12": "d2cba13464fd",
+          "lines": 87
+        }
+      ]
+    },
+    {
+      "stem": "geo-q1-diameter-circle-counterexample",
+      "png": "docs/figures/geo-q1-diameter-circle-counterexample.png",
+      "scale": 1.0,
+      "sources": [
+        {
+          "path": "examples/q1/triangle.json",
+          "sha256_12": "eeb0c92ae21c",
+          "lines": 29
+        }
+      ]
+    },
+    {
+      "stem": "geo-q2-guaranteed-reception-disk",
+      "png": "docs/figures/geo-q2-guaranteed-reception-disk.png",
+      "scale": 1.0,
+      "sources": [
+        {
+          "path": "src/mcm26b/config.py",
+          "sha256_12": "c513450dc892",
+          "lines": 213
+        },
+        {
+          "path": "docs/algo-2.md",
+          "sha256_12": "24f3e844deb9",
+          "lines": 312
+        }
+      ]
+    },
+    {
+      "stem": "geo-q3-seven-point-coverage",
+      "png": "docs/figures/geo-q3-seven-point-coverage.png",
+      "scale": 1.0,
+      "sources": [
+        {
+          "path": "src/mcm26b/planner/seven.py",
+          "sha256_12": "6ac65bd483f8",
+          "lines": 113
+        },
+        {
+          "path": "docs/algo-3.md",
+          "sha256_12": "5638192b8669",
+          "lines": 456
+        }
+      ]
+    },
+    {
+      "stem": "geo-q4-minimum-cover-31-points",
+      "png": "docs/figures/geo-q4-minimum-cover-31-points.png",
+      "scale": 1.0,
+      "sources": [
+        {
+          "path": "src/mcm26b/guarantee/plans/q4_mincover_v2.json",
+          "sha256_12": "71e54616ae21",
+          "lines": 162
+        },
+        {
+          "path": "docs/algo-4.md",
+          "sha256_12": "1774f8bf85db",
+          "lines": 485
+        }
+      ]
+    },
+    {
+      "stem": "timing-measured-q3-10-sources",
+      "png": "docs/figures/timing-measured-q3-10-sources.png",
+      "scale": 1.0,
+      "sources": [
+        {
+          "path": "referee-data/sessions/BBM9-HZG2-77N5-NKKC/log.jsonl",
+          "sha256_12": "5a308e53ed09",
+          "lines": 133,
+          "case_code": "BBM9-HZG2-77N5-NKKC",
+          "module": "q3_practice"
+        }
+      ]
+    },
+    {
+      "stem": "replay-webui-q3-omnidirectional",
+      "png": "docs/figures/replay-webui-q3-omnidirectional.png",
+      "scale": 1.0,
+      "sources": [
+        {
+          "path": "referee-data/sessions/BBM9-HZG2-77N5-NKKC/log.jsonl",
+          "sha256_12": "5a308e53ed09",
+          "lines": 133,
+          "case_code": "BBM9-HZG2-77N5-NKKC"
+        }
+      ]
+    },
+    {
+      "stem": "replay-webui-q4-directional",
+      "png": "docs/figures/replay-webui-q4-directional.png",
+      "scale": 1.0,
+      "sources": [
+        {
+          "path": "referee-data/sessions/GM56-DFXZ-XKDM-XYV7/log.jsonl",
+          "sha256_12": "f498b2073cdf",
+          "lines": 421,
+          "case_code": "GM56-DFXZ-XKDM-XYV7"
+        }
+      ]
+    }
+  ]
+}