feat(models): 落地 compare_models（指标名别名映射）+ 同步你的三条入口口径

你的三条改动（决策 61，已复测入库）：
- verify_yt_yp 拦 Inf：rmse([1.0, inf], ...) 从安静返回 inf 变成 ValueError。
- 至少 2 个样本：rmse(1.0, 1.0) 不再被当成 1 个样本算出 0.0。
- mape 从"只拦 0"改成拦 y_true <= 0：原来对负数返回 -1.0（无意义）。
Codex 侧把这三条写进 7 处 Raises（易错点 30 复发 1 次），
test_mape_rejects_zero_in_y_true 的 match 文案改为"非正数"，另补 Inf / 样本数两条测试。

compare_models（决策 62，A 档，Codex 实现）：
- 别名映射 _METRIC_FUNCS：r2 与 r2_score 指向同一个函数，传哪个列名就叫哪个，
  两个一起传报 ValueError；adjusted_r2 不进表（需要 n_features）。
- cv=0 全量拟合后打分；cv>=2 用手写 K 折（get_rng(random_state).permutation +
  np.array_split），不引入 sklearn 依赖；报折间均值；每折至少 2 个样本 => cv <= n // 2。
- 排序方向跟第一个指标走（误差类升序、R² 降序）；models 必须传模型对象（fit/predict），
  X 必须二维，metrics 必须是 tuple/list。
- 原 test_compare_models_... 的用法是错的（传拟合结果当模型），改成测试桩后摘 skip。

tests/test_models.py：23 -> 31 条（排序两条、别名、坏指标名 / 坏 models / 坏 cv、
每折下限、random_state 可复现）。

三连：pytest 233 passed / 25 skipped（258 收集）、ruff 0、pyright 0。

文档：STATUS 决策 61 / 62 + 第十轮（第九轮那 4 条标办结）；CHANGELOG 本轮条目；
personal-pitfalls 易错点 30 记复发 1 次 + 新增 33（多行文案少引号 / ValueError 多参数）。

STATUS.md

@@ -1,6 +1,6 @@
 # STATUS — 当前进度
 
-> 更新日期：2026-10-10
+> 更新日期：2026-10-12
 
 ## 本次任务
 
@@ -24,8 +24,9 @@
 `monte_carlo_probability`、`monte_carlo_integral`、`random_walk`、`markov_simulate`、
 `markov_steady_state`、`mm1_metrics`（**均为用户写**）—— `solve` 层的 L1 清单**已全部落地**。
 剩余 1 项：`save_figure`（Codex 写）。
-**`models/metrics.py` 已开工**：6 个指标（`rmse` / `mae` / `mape` / `smape` / `r2_score` / `adjusted_r2`）
-+ 共享入口 `verify_yt_yp` **由用户写**、Codex 审（第九轮）；同文件只剩 `compare_models` 未实现。
+**`models/metrics.py` 已完成（第九～十轮）**：6 个指标（`rmse` / `mae` / `mape` / `smape` / `r2_score` /
+`adjusted_r2`）+ 共享入口 `verify_yt_yp` **由用户写**、Codex 审；`compare_models` 由 Codex 按 A 档落地
+（含指标名**别名映射**）。`models` 下一步是 `regression.py`。
 `monte_carlo` 的口径已拍板（决策 48）；`monte_carlo_probability` / `random_walk` 的待办**均已办结**；
 `markov_simulate`（决策 56）/ `markov_steady_state`（决策 57）/ `mm1_metrics`（决策 58）
 的入口口径**已办掉大半**，各剩 1～2 条细枝末节（详见"下一步"第八轮）。
@@ -395,7 +396,7 @@
 
 | 检查 | venv | conda `mcm-toolkit` |
 |---|---|---|
-| `pytest` | 见下（单列） | **224 passed, 26 skipped（0 xfail）** |
+| `pytest` | 见下（单列） | **233 passed, 25 skipped（0 xfail）** |
 | `import mcm_toolkit` | 0.0.1 / 16 项 | 0.0.1 / 16 项 |
 | `ruff check` | All checks passed | **All checks passed**（0 error） |
 | `scripts/doctor.ps1` | 跑通 | — |
@@ -405,9 +406,9 @@
   （修配置之前是 17 errors，全是"无法解析导入 numpy / pandas"，见决策 29 与
   `docs/04-environment.md` 坑 7）
 - base 亦已复核：numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6（与两套环境一致）
-- **250 条用例：224 passed / 26 skipped / 0 xfail**。收集数按文件：`test_data.py` 52、`test_api_surface.py` 20、
+- **258 条用例：233 passed / 25 skipped / 0 xfail**。收集数按文件：`test_data.py` 52、`test_api_surface.py` 20、
   `test_core.py` 23、`test_solve.py` 64、`test_viz.py` 8、`test_decision.py` 7、
-  `test_stats.py` 53、`test_models.py` 23（第九轮 5 → 23，指标测试转正 + 18 条新增）
+  `test_stats.py` 53、`test_models.py` 31（第九轮 5 → 23、第十轮 23 → 31）
 - **`xfail` 再次清零**：`correlation_matrix` 的契约冲突已按方案 A 解决（决策 41），那条用例转正
 - 上一轮那 7 条 xfail 已全部转正，决策 30 那套信号（XPASS → 摘 mark）跑完过一个完整闭环
 - `examples/01_clean_and_describe.py` 实测跑通（exit 0）；`00_quickstart.py` 仍等 `stats` / `viz`
@@ -628,8 +629,57 @@ Codex 侧（决策 47 授权范围）：补 7 处 docstring（`Parameters` / `Re
 改成 `np.divide(..., out=np.zeros_like(denom), where=denom != 0.0)` 后告警消失、数值与口径完全不变，
 并补了一条测试把"不许告警"钉住（`test_smape_is_silent_when_denominator_is_zero`）。
 **判据**：只是防告警、不改语义 → 工程侧；如果是"改公式"（如决策 59 的 r2），一律留给用户（决策 49）。
+| 61 | `models/metrics.py` 的三条入口口径由**用户第三轮改定**（`Inf` / 至少 2 个样本 / `mape` 拦非正数），Codex 只同步 docstring + 测试 |
+前一轮报的 4 条待拍板里，用户改了前三条：① `verify_yt_yp` 增加 `np.isinf(yt).any() or np.isinf(yp).any()`
+（只拦 `NaN` 时 `rmse([1.0, inf], ...)` 会安静地返回 `inf`）；② 增加"至少 2 个样本"（1 个点的误差指标没有统计意义，
+`r2_score` 更是直接无定义），**标量也因此被拦住**（不再被当成 1 个样本悄悄算）；③ `mape` 从"只拦 0"改成
+`np.any(yt <= 0)`（原来的 `mean(|yt - yp| / yt)` 在 `yt < 0` 时返回**负数**，实测 `-1.0`）。
+Codex 侧：把这三条口径写进 7 处 `Raises`（**又是易错点 30**：口径一改、六处 docstring 立刻过期，本轮`复发 1`）；
+`test_mape_rejects_zero_in_y_true` 的 `match` 文案随新消息改为"非正数"，并新增 `Inf` / 至少 2 个样本两条测试。
+**遗留小问题（Codex 没动）**：`verify_yt_yp` 里 `yt.ndim == 0` 那一支是**死代码** ——
+`as_array(..., ndim=1)` 必然 `reshape(-1)`，`ndim` 恒为 1，可整段塌成 `if yt.shape[0] <= 1:`（真正的判定条件）。
+
+| 62 | `compare_models` 由 Codex 按 **A 档**落地，指标名口径选**别名映射**（用户 2026-10-12 拍板） |
+前一轮问的是"`metrics=("rmse","mae","r2")` 里的 `"r2"` 与函数名 `r2_score` 对不上，用哪个"。用户选**两个都收**，
+所以别名表落在模块级的 `_METRIC_FUNCS`（`"r2"` 与 `"r2_score"` 指同一个函数）：**传哪个名字，输出表的列就叫哪个名字**，
+两个一起传报 `ValueError`（否则会出两列一模一样的数字）。别名只解决"名字认不认"，不改变数值。
+实现要点：`models` 必须传**模型对象**（`fit` / `predict`），不是拟合结果；`X` 必须二维（`as_array(ndim=2)` 不替你猜）；
+分折是**手写 K 折**（`get_rng(random_state).permutation` + `np.array_split`），**不依赖 sklearn** —— 只装了 4 个核心依赖也能跑；
+`cv=0` 全量拟合后打分（`cv=1` 报错：要么 0 要么 ≥2）；`cv >= 2` 报**折间均值**；每折至少 2 个样本 ⇒ `cv <= n // 2`；
+排序方向跟着**第一个指标**走（误差类升序、R² 降序）。`adjusted_r2` **不进表**（还要 `n_features`，`compare_models` 不知道每个模型用了几列）。
+测试 23 → 31 条：首列排序（升序 / 降序两条）、别名、坏指标名、坏 `models` / `cv`、每折样本数下限、`random_state` 可复现。
 ## 下一步
 
+### ⭐ 当前进度与待办（2026-10-12 第十轮）
+
+**本轮：你办掉第九轮那 4 条口径里的 3 条，Codex 落地 `compare_models`（别名映射）。**
+
+你改的三条（决策 61）：`verify_yt_yp` 拦 `Inf`、拦"只有 1 个样本"、`mape` 从"只拦 0"改成 `yt <= 0`。
+三条我都复测过：`rmse([1.0, inf], [1.0, 2.0])` 现在报 `ValueError`；`rmse(1.0, 1.0)` 也报错（标量不再被当成 1 个样本）；
+`mape([-1.0, 2.0], [1.0, 2.0])` 由返回 `-1.0` 变成报错。
+
+Codex 这轮：① 把三条新口径写进 7 处 `Raises`（口径一改、docstring 就过期 —— **易错点 30 复发 1 次**）；
+② `compare_models` 按 A 档实现（决策 62），指标名走**别名映射**：`_METRIC_FUNCS` 里 `"r2"` 与 `"r2_score"` 指向同一个函数，
+传哪个列名就叫哪个、两个一起传报错；③ 顺手补了 `X` 必须二维、`cv` 白名单（`bool` 不收、`cv=1` 无意义、`cv <= n // 2`）、
+`models` 必须是"有 `fit`/`predict` 的对象"等入口；④ 测试 23 → 31 条。
+
+三连：`pytest` **233 passed / 25 skipped（258 收集）**、`ruff` **0**、`pyright` **0**。
+
+**接下来（`models` 的完成标志 `compare_models` 已达成）**
+1. `regression.py` 的 `fit_linear` / `fit_polynomial`（A 档薄封装；把 `base.Model` 三件套跑通，
+   顺带把 `tests/test_models.py` 里那两条**还挂着的 `skip`** 转正）。**注意**：`fit_linear` 落地后要补一条
+   "`compare_models` + 真实模型"的集成测试 —— 原来那条跳过用例写的是 `compare_models({"linear": fit_linear(X, y)})`，
+   **把拟合结果当模型传是错的**，本轮已把它改写成用测试桩（`_MeanModel` / `_LinearModel`）。
+2. `models` 剩下的 `fit_nonlinear` / `timeseries` / `ml` 按 roadmap 走。
+3. 之后转 `decision/entropy_weights`（**S 档，你写**，三个坑：方向 / 量纲 / 零值）。
+
+### ⏳ 第十轮新出现的 1 条小口径（Codex 只报不改，决策 49）
+
+**`verify_yt_yp` 里 `yt.ndim == 0` 那一支是死代码**：`as_array(..., ndim=1)` 内部一定 `ravel()`，`ndim` 恒为 1，
+所以 `if yt.ndim == 0 or yt.shape[0] <= 1:` 里前半段永远为假，报错文案里的 `else 1` 也永远走不到。
+整段可以塌成 `if yt.shape[0] <= 1:`（行为完全不变，只是少一段"看着像在防什么、其实没防"的代码）。
+你决定改不改 —— 不改也能跑，只是以后回头看会多花几秒钟。
+
 ### ⭐ 当前进度与待办（2026-10-10 第九轮）
 
 **本轮：`models` 开工，你亲手写了 `models/metrics.py`** —— 6 个回归指标（`rmse` / `mae` / `mape` / `smape` /
@@ -653,15 +703,14 @@ Codex 只碰工程侧：7 处 docstring（补 `Parameters` / `Returns` / `Raises
 2. `regression.py` 的 `fit_linear` / `fit_polynomial`（把 `models/base.py` 的 `Model` 协议三件套跑通）。
 3. 然后转 `decision/entropy_weights`（**S 档，你写**，三个坑：方向 / 量纲 / 零值）。
 
-### ⏳ 第九轮新增：4 条口径待你拍板（Codex 只报不改，决策 49）
+### ✅ 第九轮那 4 条口径（2026-10-12 全部办结）
 
-1. **`mape` 遇负 `y_true` 不拦**：`mean(|yt - yp| / yt)` 在 `yt < 0` 时给出**负数**（实测 `mape([-1, 2], [1, 2])` → `-1.0`）。
-   MAPE 的定义域是 `y_true > 0`；两个方向：拦 `y_true <= 0`，或把分母改成 `|y_true|`（标准写法 `|(y-ŷ)/y|`）。
-2. **`inf` 不拦**：`verify_yt_yp` 只查 `np.isnan`，实测 `rmse([1.0, inf], [1.0, 2.0])` → `inf`。要不要跟 `NaN` 一样直接报错？
-3. **标量能进来**：`as_array` 的白名单含 `int` / `float`，`rmse(1.0, 1.0)` → `0.0`（被当成 1 个样本）。接受还是要求 ≥ 2 个点？
-   （与 `as_array` 那条"标量是否摘掉"的旧口径是同一个问题，见下面"其余待办"第 6 条。）
-4. **`compare_models` 的键名**：签名里写 `metrics=("rmse", "mae", "r2")`，但函数名是 `r2_score`。
-   选 `"r2"`（列名短）还是 `"r2_score"`（与函数名一致）？也可以两个都收（别名映射，最省事）。
+1. ~~`mape` 遇负 `y_true` 返回负数~~ → **用户选"拦"**：改成 `np.any(yt <= 0)` 直接报错并点名改用 `smape`
+   （另一条路是用 `|y_true|` 做分母，没选）。测试文案随之改成 `match="非正数"`。
+2. ~~`inf` 不拦~~ → **用户选"跟 `NaN` 一样拦"**：`verify_yt_yp` 增加 `np.isinf(...).any()`（`rmse` 不再安静地返回 `inf`）。
+3. ~~标量被当成 1 个样本~~ → **用户选"要求至少 2 个点"**，于是 `rmse(1.0, 1.0)` 现在报 `ValueError`。
+   注意：这与 `as_array` 白名单里"标量要不要摘掉"是**两个问题**（那条仍未拍板，见下方"其余待办"第 6 条）。
+4. ~~`compare_models` 的键名 `"r2"` vs `"r2_score"`~~ → **用户选别名映射**（两个都收），由 Codex 实现，见决策 62。
 
 ### ⭐ 当前进度与待办（2026-10-10 第八轮）