更新了保存图表模块

你的三条改动（决策 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 多参数）。

CHANGELOG.md

@@ -6,6 +6,7 @@
 ## [Unreleased]
 
 ### Added
+- `viz.save_figure`：L0 最后一项落地（Codex 写）。入口校验先于副作用，支持 `png` / `pdf` / `svg` / `eps` / `ps` / `jpg` / `jpeg` / `tif` / `tiff` / `webp`；`path` 带图片后缀时自动去后缀。`tests/test_viz.py` 去掉模块级 skip 并新增 8 条保存测试。
 - 仓库骨架：`src/mcm_toolkit/` 7 个包（core / data / stats / models / solve / decision / viz）
 - 顶层 `__init__.py` 只导出 7 个子包 + 8 个快捷函数，`__all__` 即公开 API 清单
 - `core.Result`：唯一的结果对象（替代原建议里的 5 个 Result 类）
@@ -19,6 +20,39 @@
 - `scripts/setup-conda.ps1` / `scripts/setup-venv.ps1` / `scripts/doctor.ps1`
 - `environment.yml`：需联网时的精确复现方案
 - `pyproject.toml`：核心依赖只 4 个，其余走 extras
+- `docs/02-architecture.md` §4.7「类型约定」：注解要写全、numpy 标量的判断写法、
+  非法类型必须抛 `TypeError`。配套在 `docs/03-roadmap.md` 的开发纪律里加了指针。
+- `docs/dev/personal-pitfalls.md`：个人易错点清单，**只追加、不通读**
+- `data.clean`：四个函数落地（**由用户本人实现**）——`clean_missing`（L0 第 4 项）、
+  `impute_missing` / `detect_outliers` / `winsorize`（原属 L1，顺手写了）。
+- `tests/test_data.py`：新增 13 条 clean 行为测试，覆盖 `clean_missing` 的阈值语义与轴向、
+  `impute_missing` 的 mean/ffill/mode 与全 NaN 列、`winsorize` 的分位点与异常类型。
+- `tests/test_data.py`：另加 7 条 `xfail`，把**已知但未修的契约**钉在测试报告里（见 Notes）。
+- `docs/algorithms/detect_outliers.md`：**第一张 S 档函数卡片**（roadmap §3.1 要求
+  约 15 张，这是第 1 张）。除模板九节外，额外记了三条容易踩的判断：为什么不返回 `Result`、
+  非数值列恒 `False` 的两条备选路各错在哪、以及 `ddof` 口径与 `stats.zscore` 不一致。
+- `examples/01_clean_and_describe.py`：`load_table` / `save_table` / `clean_missing` /
+  `impute_missing` / `detect_outliers` / `winsorize` 六个函数的最小用法，实测跑通（exit 0）；
+  末尾留 `TODO(L0)` 等 `stats.describe`。
+- `tests/test_data.py`：`data` 的 transform 段 **18 条用例** —— `normalize` 的三种 method、
+  `feature_range` 区间与两条校验、常量列不出 nan、docstring 那个 Examples 的精确值、按列语义；
+  `standardize` 的按列与 `ddof`（用解析关系钉住：`ddof=1` 时结果的 std = `sqrt((n-1)/n)`）；
+  `log_transform` 的定义域平移；`one_hot_encode` 的自动识别、`drop_first`、列不存在报错。
+  其中两条是把原先挂着的 `skip` 转为实跑（见坑 9 / 个人易错点 9）。
+
+- `tests/test_stats.py`：新写 **20 条**用例 —— `describe` 的方向约定（行 = 指标、列 = 变量）、
+  `missing` / `missing_ratio` / `skewness` / `kurtosis` 四行**不能是 NaN**、非数值列自动跳过、
+  接受 ndarray / list / Series、加权均值与加权标准差对照手算公式、5 种非法 `weights`；
+  `zscore` 的手算对照 / 按列 / 常量列 / 非法类型；`coefficient_of_variation` 的手算对照、
+  单列 DataFrame、均值为 0 抛 `ValueError`、空数组与二维输入。
+- `examples/01_clean_and_describe.py`：填掉末尾的 `TODO(L0)`，加一段 `describe` 输出（实测 exit 0）。
+
+### Added
+- `stats.correlation_pvalues` / `stats.correlation_table`：`correlation_matrix` 的伴随函数
+  （**方案 A**，用户 2026-10-03 拍板，见决策 41）——
+  `correlation_matrix` 只返回**数值**矩阵；`correlation_pvalues` 给数值 p 值矩阵、
+  `correlation_table` 给"系数 + 显著性星标"的论文表格。
+  三者共用 `_check_corr_args` 入参守卫与**成对删缺失**口径，`correlation_table` 在最外层调另外两个。
 
 ### Changed
 - `core.get_rng` / `core.set_seed`：实现（L0 第 2 项）。`get_rng` 收 `int` / `np.integer` /
@@ -31,25 +65,617 @@
   `na_values` 默认吃下空串 / `NA` / `N/A` / `#N/A` / `null` / `-`。
 - `data.save_table`：实现（原属 L1，顺手落地）。按扩展名分派，父目录不存在时自动创建，
   返回实际写入的 `Path`。
-
+- `data.load_table` / `data.save_table`：docstring 补 `Parameters` / `Raises`
-### Added
+  （`docs/02-architecture.md` §4.7 对每个公开函数的硬要求）。
-- `docs/02-architecture.md` §4.7「类型约定」：注解要写全、numpy 标量的判断写法、
+- `data.load_table` 的返回注解 `Any` → `pd.DataFrame`，与 docstring 的承诺对齐。
-  非法类型必须抛 `TypeError`。配套在 `docs/03-roadmap.md` 的开发纪律里加了指针。
+- `data.clean`：docstring 按 `docs/02-architecture.md` §4.7 补全 Parameters / Returns / Raises
-- `docs/dev/personal-pitfalls.md`：个人易错点清单，**只追加、不通读**
+  （Codex 代写，与 io.py 同一套 numpydoc 格式）。
-
+- `data.clean`：ruff 从 6 条清到 1 条——导入分组（I001）、elif 链改 if 加末尾无条件 return
-### Fixed
+  （RET505 / RET503）、去掉多余 f 前缀（F541）、删掉只会被覆盖的 mask 初始化（死代码）、
+  去掉行尾空白（W293）。
+- `pyright` 报"无法解析导入 numpy / pandas"（17 errors）的原因：分析器会去 PATH 上找 python，
+  本机 PATH 上只有 Codex 运行时的 3.14 shim（无科学栈），且 pyright 不认
+  `pyvenv.cfg` 的 `include-system-site-packages`。
+  改为 `[tool.pyright]` 指定 `venvPath = "."` / `venv = ".venv"` /
+  `pythonVersion = "3.13"`，并让 `scripts/setup-venv.ps1` 往 `.venv` 里写一个
+  指向 base site-packages 的 `.pth`。pyright 17 errors → **0**。
+  详见 `docs/04-environment.md` 坑 7。
+- `tests/test_data.py`：`df["b"].isna().all()` 的类型是 `Series | bool`，
+  直接当断言条件 pyright 会报"条件操作数无效"，外面套 `bool()`；
+  两条故意传错类型的用例加 `# type: ignore[arg-type]`。
+- `data.save_table` 的后缀校验排在 `path.parent.mkdir(...)` **之后**，传 `.txt` 会先留下一个
+  空目录再抛 `ValueError`。改为**先校验、后副作用**，并加回归测试。
+- `data/io.py` 里 `__all__` 与下一个 `def` 之间只有 1 个空行（PEP 8 要 2 个）。
 - `tests/test_data.py` 顶上的**模块级** `pytestmark = pytest.mark.skip(...)` 会连带跳过同文件里
   已经写好的函数，导致 `load_table` 零覆盖。改为逐条 skip 未实现的算法，并补 8 条 io 测试
   （编码探测、NA 归一、后缀校验、缺文件报错、往返读写、类型校验）。测试数 31 → **39 passed**。
 - conda base 里 zstandard 的 `*.conda_trash` 残骸目录被 Python 当成 namespace package 导入，
   使 `.venv`（= base）的 `pd.read_csv` 抛 `ImportError: Can't determine version for zstandard`。
   已把残骸目录改名禁用（**可逆**，未删除），详见 `docs/04-environment.md` 坑 6。
+- `data.clean` 第二轮审查（2026-10-02），Codex 直接修掉 4 处**轻度**问题：
+  `winsorize(Series)` 因 `select_dtypes` 在 `Series` 上不存在而直接崩（Series 分支提到最前，
+  并加数值 dtype 守卫）；`winsorize` 的 `data.quantile()` 改为只在数值列上算
+  （文本列不再崩，与已有的 `numeric_cols` 判断对齐）；删掉 `detect_outliers` 里已成空操作的
+  `df = pd.DataFrame(data)`（数据在更早处就转过了，顺手去掉 `df` 这个别名）；
+  清掉行尾空白（W293）、函数体内的连续空行，并把 `clean_missing` 的嵌套 `if` 合并
+  （SIM102，ruff 最后 1 条）。ruff `1 error` → **`All checks passed`**，pyright 仍 0。
+- `tests/test_data.py`：5 条 `xfail` 经 XPASS 信号确认已修好，**摘掉 mark 转正式用例**
+  （`detect_outliers` 的 4 条 + `winsorize` 混合类型 1 条）。测试 **53 passed / 7 xfailed →
+  58 passed / 2 xfailed**。
+- `CHANGELOG.md`：[Unreleased] 里有一句被重复追加撑坏
+  （"…删掉它即全绿。：分析器会去 PATH 上找 python，"），已修。
+- `data.detect_outliers` 收尾（2026-10-02，**由用户本人实现**）：统计量（`quantile` /
+  `mean` / `std`）与掩码写入**都**收窄到数值列，含文本列的赛题表不再崩；
+  非数值列在掩码里恒 `False`（用户本人定的语义，见决策 32）。docstring `Notes` 补上这条语义。
+- `data.detect_outliers` 里 `data=data.copy()` 是死代码：下面的 `to_frame()` / `pd.DataFrame()`
+  本来就返回新对象，函数全程也没原地改过 `data`，白白复制一份数据；而且它排在类型分派
+  **之前**，会把错误入参的报错从 `ValueError` 变成 `AttributeError`。已删。
+- `data.detect_outliers`：删掉那行死代码后 pyright 反而报了 1 个真错 ——
+  `df[Index]` 被类型存根当成 `Series`，`.std()` 于是被判成标量、`std.replace(...)` 非法。
+  在取列子表处用 `cast(pd.DataFrame, ...)` 按运行时真值收窄。详见 `docs/04-environment.md` 坑 8。
+- `tests/test_data.py`：`test_detect_outliers_survives_text_columns` 摘掉 xfail 并加强断言
+  （文本列必须恒 `False`）；新增 `test_detect_outliers_all_text_frame_returns_all_false`
+  钉住"整表没有数值列"这条边界。测试 **58 passed / 2 xfailed → 60 passed / 1 xfailed**。
+- `docs/dev/personal-pitfalls.md`：追加第 8 条（限制掩码 ≠ 限制统计量）。
+- `data.impute_missing` 的 mode 分支改为**返回新表**（原先 `data[col] = ...` 会就地改调用方的
+  DataFrame，另外四支都返回新对象）。最后一条 `xfail` 随之转正，**测试里 `xfail` 清零**。
+- `data.detect_outliers` 补**入参类型校验**（§4.7：非法类型抛 `TypeError`，不静默兜底）：
+  接受 `DataFrame` / `Series` / `list` / `tuple` / `ndarray`。`tuple` 同时补进 `is_ld_array`，
+  与 `list` 同等对待；`dict` 不再被接受（以前靠 `pd.DataFrame()` 碰巧能过，见决策 33）。
+- `tests/test_data.py`：摘掉最后一条 `xfail`（mode 就地改）并加强断言；新增 3 条
+  （非法类型抛 `TypeError`、元组按一维数组型处理、全 NaN 列与单元素列不抛异常）。
+  测试 **60 passed / 1 xfailed → 64 passed / 0 xfailed**。
+- `data.transform` 四个函数实现（**由用户本人写**）：`normalize`（minmax / vector / max，均按列）、
+  `standardize`（按列，`ddof` 真的传下去）、`log_transform`（`offset=None` 时自动取 `1 - min(x)`）、
+  `one_hot_encode`。`data/` 下的 L0 至此结清。
+- `data.transform`：Codex 清掉 5 条 ruff —— RET503（`normalize` 末尾缺无条件 `return`）、
+  F541（无占位符的 f-string）、RET504（多余的 `result` 中转）、RET505（`return` 后的 `elif`）、
+  SIM108（`log_transform` 的 if/else 改三元）。
+- `data.transform.normalize`：`supported_method` 与 `feature_range` 的校验提到 `np.asarray` **之前**
+  （§4.7 的"守卫集中在开头"）；并修掉说反的报错文案 —— 条件是要求下界 < 上界，
+  原文却写"上界必须小于下界"，且 `TypeError` 那条用了无占位符 f-string。
+- `data.transform.one_hot_encode`：自动识别类别列时显式加上 `'str'` / `'string'`。
+  原来只写 `['object', 'category']`，在 pandas 3 上是**已弃用路径**（每次调用发 `Pandas4Warning`），
+  未来会变成一列都选不中的**静默错误**。详见坑 9。
+- 测试计数：**64 passed → 82 passed**（新增 18 条，另两条 skip 转为实跑），skip 42 → 40。
+
+
+- `data.transform`：修掉上一版引入的 **3 处真 bug**（**Codex 代修，用户授权"报错顺手修掉"**）。
+  症状是 7 条测试变红 + pyright 在 `transform.py:105` / `:133` 报 `reportArgumentType`。
+  **这不是编辑器误报** —— pyright CLI 与 `pytest` 都能复现，所以**一行 `# type: ignore` 都没加**：
+  - 输入白名单漏了 `pd.DataFrame`：`standardize(df)` / `log_transform(df)` 抛 `TypeError`，
+    函数体里的 `is_df` 分支全是**死代码**。白名单统一成模块级 `_NUMERIC_TYPES` 并移到 `np.asarray` 之前。
+  - `normalize` 的三个 method 分支**互相覆盖**：`minmax` / `vector` 算完的结果被末尾无条件的
+    `x / max` 冲掉，三种 method 实际都只走 max（`test_normalize_*` 5 条因此变红）。改成 `if / elif / else`。
+  - `one_hot_encode` 把 `get_dummies` 的结果按 `data.columns` 重包一层 `DataFrame`：
+    哑变量列名（`city_A`）与原列名（`city`）对不上 → 编码列被**整列丢掉**。改为直接返回 `get_dummies` 结果。
+  - `log_transform` 的 `offset` 守卫条件**写反**（`offset > 0` 就抛错，恰好把唯一合法用例拒掉），
+    改为校验定义域前提 `min(x) + offset > 0`；`offset=0` 对全正数据合法（见决策 35）。
+- `data.transform` 四个函数的 docstring 按 `docs/02-architecture.md` §4.7 补齐
+  `Parameters` / `Returns` / `Raises`（Codex 代写，与 `io.py` / `clean.py` 同一套 numpydoc 格式），
+  并把常量列行为（决策 34）写进 `Notes`。
+- `data.transform`：口径定稿后 ruff 剩的 4 条 RET505（`return` 后的 `elif`）一并清掉 ——
+  `All checks passed`；pyright **2 errors → 0 errors**；测试 **7 failed / 75 passed → 82 passed / 40 skipped**。
+
+- `stats.describe`：实现落地（**由用户本人写**，Codex 审查 + 代修），并修掉一个**静默 bug** ——
+  `df_num.describe().T` 把表转反了（行 = 变量、列 = 指标），而 docstring 与
+  `test_describe_reports_expected_keys` 定的是"行 = 指标、列 = 变量"。
+  转置后 `.loc[指标名] = <按变量索引的 Series>` 与列名**零交集**，pandas 不报错，
+  直接把这四行（`missing` / `missing_ratio` / `skewness` / `kurtosis`）**整行填成 NaN**；
+  `weights` 分支则报 `cannot set a row with mismatched columns`。去掉 `.T` 一处修好三件事。
+  另补 `median` 行（pandas 只有 `50%`，测试契约定的是 `median`）、入参放宽到
+  `list` / `tuple` / `ndarray`（`00_quickstart.py` 传的就是 ndarray）、
+  `weights` 校验补齐（维度 / 长度 / NaN / 负值 / 和为 0，原先和为 0 时裸抛 `ZeroDivisionError`）、
+  docstring 按 §4.7 补 `Parameters` / `Returns` / `Raises`。
+- `stats.zscore`：修 RET505；docstring 按 §4.7 补齐；DataFrame 取列处按坑 8 用 `cast` 收窄
+  （pyright 的 `DataFrame | Series` 重载）。
+- `stats.coefficient_of_variation`：均值为 0 由 `TypeError` 改为 `ValueError`
+  （那是**取值**问题不是类型问题，§4.7）；空数组提前抛 `ValueError`（原先静默返回 nan + RuntimeWarning）；
+  报错文案里"异变系数"的错别字与 "N 维数组" 改为 "N 列"。
+- `stats.coefficient_of_variation`：分母由 `mean` 改为 `|mean|`（**用户本人改的**，决策 38）——
+  均值为负时 `σ/μ` 会给出负值，容易被读成"波动更小"；现在 CV 恒非负。docstring 的 `Notes` 同步，
+  并加一条测试钉住"均值为负时 CV 仍为正"。
+- `tests/test_stats.py`：去掉**模块级** `pytestmark = pytest.mark.skip` —— 它把该文件 6 条测试
+  **全部**跳过（包括已经实现好的 `describe`），正是决策 26 要禁的写法：实现零覆盖而测试全绿。
+  改为逐条 skip 未实现的 5 条。
+- 测试计数：**82 passed / 40 skipped → 103 passed / 39 skipped**（新增 21 条）；
+  ruff 7 error → **All checks passed**；pyright **1 error → 0**。
+
+- `stats.correlation_matrix`：实现落地（**由用户本人写**，Codex 审查 + 代修），修掉一个**硬 bug** ——
+  `if numeric_cols == 0:` 拿 `Index` 和标量比，得到的是布尔**数组**：0 列时静默不报错、
+  1 列时碰巧能跑、**≥2 列直接 `ValueError: The truth value of an array ... is ambiguous`** ——
+  而"≥2 个数值列"正是最常见的情况，等于整个函数不可用。改成 `len(numeric_cols) == 0`，
+  并加回归用例（见易错点 13）。
+- `stats.correlation_matrix`：pyright 的两处报错**都不是运行时问题，也都没挂 `# type: ignore`** ——
+  `data[numeric_cols]` 是坑 8 的 `DataFrame | Series` 重载（`cast` 收窄）；
+  `_, p = stats.pearsonr(...)` 解包后会退化成 `object`（scipy 的返回值是 `_make_tuple_bunch`
+  在运行时拼的类，存根里看不到 `pvalue`）。新增 `_pvalue(result: Any) -> float` 小助手统一取 p 值，
+  后面 `t_test` / `anova` / `chi_square_test` 可复用（见 `docs/04-environment.md` 坑 10、决策 40）。
+- `stats.correlation_matrix`：`method` 校验提到最前（守卫集中开头）；`add_stars` 的 `elif` 链改 `if`
+  （RET505）；清掉 3 条 F541 与 1 条 I001（import 未排序）—— ruff 归零。
+- `tests/test_stats.py`：`test_correlation_matrix_diagonal_is_one` 由 `skip` 改成 `xfail(strict=False)`
+  （决策 30）—— 契约要**数值**矩阵，实现返回带星标的字符串表，口径待拍板；
+  另新增 2 条（多列数值表能跑通、非法输入报错）。
+- 测试计数：**103 passed / 39 skipped → 105 passed / 38 skipped / 1 xfail**。
+
+- `stats.correlation_matrix`：按**方案 A** 拆开 —— 只返回**数值**矩阵，不再返回带星标的字符串表。
+  字符串表做不了后续计算（挑高相关对、喂聚类 / PCA、画热力图），而反过来随时能格式化；
+  一旦返回字符串，数值信息不可逆地丢失（见易错点 14）。
+- `stats.correlation_pvalues`：**对角线由 `0.0` 改成 `NaN`** —— 写成 0 会被下游读成"极显著"，
+  而"自己和自己相关"根本没有 p 值可言。
+- `stats.correlation_pvalues`：p 值与 r 现在用**同一批观测** —— 先成对 `dropna()` 再算，
+  并同样尊重 `min_periods`（不足给 NaN）。此前 `corr` 是成对删缺失、`pearsonr` 不删，
+  两者基于不同的样本量，r 和 p 对不上。
+- `stats.correlation_pvalues`：只算上三角再镜像到对称位置（成对变量的 p 天然对称），
+  省掉一半重复计算。
+- `tests/test_stats.py`：`test_correlation_matrix_diagonal_is_one` 摘掉 `xfail` 转正；
+  新增 8 条（数值性 + 对称性、非数值列跳过、p 值对照**解析式** `t = r·sqrt((n-2)/(1-r²))`、
+  对角线 NaN、成对删缺失口径、`min_periods`、对角线无星标、表格与数值输出一致）。
+- 测试计数：**105 passed / 38 skipped / 1 xfail → 114 passed / 38 skipped / 0 xfail**。
 
 ### Notes
+- `detect_outliers` 原有的三个 bug 加一处设计空白**已全部收口**：`threshold` 范围校验挪进
+  `clean_missing`、`is_series` / `is_ld_array` 提到类型转换**之前**、统计量与掩码都限制在数值列、
+  非数值列恒 `False`（决策 32）、入参类型校验补上（决策 33）。
+  S 档卡片与 `examples/` 用法也已落地 —— `detect_outliers` 这条线**结清**。
+- `transform.py` 的 **4 个口径已全部收口**：① 三个函数共用 `_NUMERIC_TYPES` 白名单（含 `DataFrame`）；
+  ② 全部接受 `DataFrame` 且保持"DataFrame 进 DataFrame 出"；③ 显式 `offset` 按定义域校验
+  （`min(x) + offset > 0`，见决策 35，**待用户确认**）；④ 常量列行为写进 docstring 的 `Notes`；
+  另外 `Parameters` / `Returns` / `Raises` 已按 §4.7 补齐。
+- 新增易错点第 10 条：**把真报错当成"编辑器误报"** —— 红线先跑 CLI 与 `pytest` 再判断（`docs/dev/personal-pitfalls.md`）。
+- `stats` 这条线开工了：`describe` 落地，填掉 `examples/01_clean_and_describe.py` 的 `TODO(L0)`；
+  `correlation_matrix` 功能上也能跑了（硬 bug 已修）。
+- `correlation_matrix` 的返回契约已按**方案 A** 定案（决策 41）：数值归 `correlation_matrix`、
+  p 值归 `correlation_pvalues`、星标表归 `correlation_table`。对角线不带星、p 与 r 同批观测两条也一并修掉。
+- `correlation_matrix` 仍只收 `DataFrame`（`describe` / `zscore` / `transform` 都收 ndarray）——
+  要不要放开由用户决定，记在 `STATUS.md`「下一步」第 5 条。
+- 三处口径已拍板（2026-10-03）：`log_transform` 的 `offset` 维持现状（决策 35）；
+  `describe` / `zscore` **默认丢掉**非数值列、与 `detect_outliers` 的"保留列"刻意不统一（决策 37）；
+  变异系数改用 `σ/|μ|`（决策 38）。另立决策 39 明确分工：语义口径用户拍板、工程事务 Codex 顺手补。
+- 已实现函数的 `examples/` 最小用法仍不全：`00_quickstart.py` 要等 `bootstrap_ci` / `viz`，
+  `Result` 的用法届时并进去。
+- 已知缺口：
 - 除 `core.Result`、`core.get_rng`、`core.set_seed`、`data.load_table`、`data.save_table` 外，其余函数体**尚未实现**（统一 `raise NotImplementedError` + `TODO(L0/L1/v0.2)` 标记）。
   这是刻意的：先定接口，再按 `docs/03-roadmap.md` 的 L0 → L1 顺序填实现。
 - 已知缺口：`SALib`（Sobol/Morris）、`pymoo`、`pyright` 已装进 conda 环境 `mcm-toolkit`，`.venv` 里没有。
 
+### Fixed
+- `stats.confidence_interval`：修掉一个**会给出错误数字**的硬 bug —— 原码返回
+  `(float(min(0.0, lower)), float(max(upper, 1.0)))`，`min` / `max` 的**参数写反**（下界被钉死成 `0.0`），
+  而且**无条件**把区间夹到 `[0, 1]`。实测 `confidence_interval(rng.normal(170, 8, 50), method="t")`
+  的下界是 `0.0`（正确是 `171.0 ± 2.1`）；`confidence=1.5` 被夹成 `(0.0, nan)` 而不报错。
+  现在**只有 `proportion` 夹到 `[0, 1]`**（决策 42），`normal` / `t` 直接返回 `mean ± z|t·se`；
+  `method` 非法改抛 `ValueError`、`confidence` 按 `(0, 1)` 开区间校验、样本量 < 2 抛 `ValueError`。
+- `stats.confidence_interval` 的入参曾只收 `DataFrame`，而 docstring 的 Examples 传 `list`、
+  L0 用例传 `ndarray` —— **两条都会 `TypeError`**。现放宽到 `list` / `tuple` / `ndarray` / `Series` / `DataFrame`。
+
+### Added
+- `stats.inference._statistic(result: Any) -> float` 助手，与 `_pvalue` 成对（决策 43）。
+  scipy 的 `TtestResult` 与 `PearsonRResult` 同源，都是 `_make_tuple_bunch` 运行时拼的类，
+  存根里 `.statistic` / `.pvalue` 都看不到。用户报告的 `t_test` 「307 / 308 两行报错」即此，
+  **不是真 bug**（探针实测 `TtestResult(statistic=3.873, pvalue=0.0305)`，运行时完全正常）；
+  换成助手后 pyright 归零，**一行 `# type: ignore` 都没挂**。见 `docs/04-environment.md` 坑 10。
+- `stats.t_test`（L1 提前落地）：docstring 补齐 `Parameters` / `Returns` / `Raises` / `Notes`；
+  `_clean_data` 改用 `isinstance(data, pd.DataFrame)` 收窄（坑 8 的 `cast`）；`alpha` 开区间校验；
+  `df` 按 Welch–Satterthwaite / pooled / paired 分别给。
+- `tests/test_stats.py`：**+10 条（36 → 46）**，含把原先挂着 `skip` 的
+  `test_confidence_interval_matches_scipy` 转正。对照一律用解析式（z 公式、Welch `df` 公式、
+  `t = (mean − value)/(s/√n)`），不拿实现对自己。
+- `docs/dev/personal-pitfalls.md`：新增第 15 条「区间被无条件夹到 `[0, 1]`，且 `min` / `max` 参数写反」；
+  并把**停在 6 号就没人管**的索引表补齐到 15（只补索引，正文一个字没动）。
+- `docs/04-environment.md`：坑 10 扩写成 `pvalue` / `statistic` 两条；顺手修掉残留的
+  `[FENCE]` 代码围栏占位符与一处重复的 `---`。
+
+### Changed
+- `STATUS.md`：L0 记为 **9/12**（另 L1 的 `confidence_interval` / `t_test` 提前落地）；
+  校正测试数为 **162 条 / 125 passed / 37 skipped**；新增决策 42 / 43；「下一步」列出
+  **`t_test` 待用户拍板的 4 个口径**（单样本结论文案、`paired` 的 NaN 对齐、`value` 被静默忽略、
+  `DataFrame` 摊平多列）—— 按决策 39，Codex 只列选项、不代选。
+
+### Added
+- `core.validate.as_array`：**所有收数值函数的统一入口**（决策 44）。
+  一次做完"类型白名单 + 转 `ndarray` + 报告原来是什么容器"，返回 `(arr, kind)`，
+  `kind` 是 `"frame"` / `"series"` / `"array"`。**还原不代做** —— 调用方按 `kind` 手写，
+  因为 `describe` / `correlation_*` / `confidence_interval` / `t_test` 的输出天生与输入不同形。
+  入口三条硬规矩：`numeric_only` 按"输出是否与输入同形"选、**默认绝不摊平**（要摊平显式 `ndim=1`）、
+  **不删缺失值**（删缺失是各函数的语义）。见 `docs/02-architecture.md` §4.8。
+
+### Changed
+- **入口去重**：`normalize` / `standardize` / `log_transform` / `zscore` / `confidence_interval` /
+  `t_test` 六处各自手抄的 `isinstance(x, pd.DataFrame)` / `select_dtypes` / `np.asarray` 全部删掉，
+  各只剩 1 行 `as_array(...)`；`data/transform.py` 的 `_NUMERIC_TYPES` 白名单连同 3 份副本一起删除。
+  原来这类判断散在 **5 个文件 31 处**。
+- `data.transform` 的 `normalize` / `standardize` / `log_transform` 走 `numeric_only=False`：
+  它们的输出必须与输入**同形**，跳过非数值列会让返回的表少列、对不上原表。
+- `zscore` / `normalize` / `standardize` / `log_transform` 的 Series 分支**补回 `name`** ——
+  此前 `pd.Series(result, index=...)` 会把 `name` 丢掉，管道里 `concat` 会变成无名列。
+- 测试：`tests/test_core.py` 新增 `TestAsArray` **8 条**（五种容器的 `kind`、只取数值列、
+  `numeric_only=False` 遇文本报错、默认不摊平、`ndim=2` 只校验不重塑、白名单外一律 `TypeError`、
+  **保留 NaN**、`dtype=None` 保持原 dtype）；`tests/test_stats.py` 新增 1 条（`zscore` 保住 Series 的
+  `index` 与 `name`）。全量 **171 条 / 134 passed / 37 skipped**。
+- `docs/02-architecture.md`：新增 §4.8「入口只有一个：`core.validate.as_array`」；
+  目录树里 `validate.py` 补上 `as_array`。
+- `docs/dev/personal-pitfalls.md`：新增第 16 条「同一段入口转换抄了 N 遍，还当它是约定」，索引补齐到 16。
+
+### Fixed
+- `normalize(含文本列的表)` 等"容器对、内容转不成 float"的情况，错误类型由 numpy 的 `ValueError`
+  统一收成 `TypeError`（决策 45，**Codex 代选、待用户确认**）—— 与 `t_test` / `confidence_interval`
+  已经写进 docstring 的口径一致。
+
+### Added
+- `stats.bootstrap_ci`（**L0 第 10 项，S 档**，实现由用户本人写）：百分位法 bootstrap 置信区间，
+  `statistic` 可以是任意 `f(sample) -> float`（默认 `np.mean`）。返回 `Result`，
+  `params = {estimate, low, high, confidence, n_resamples}`、`metrics.statistic_name`。
+  重采样**按块处理**（`batch_size=1000`），不落地 `B × n` 整矩阵。
+- `docs/algorithms/bootstrap_ci.md`：**第 2 张 S 档函数卡片**。除模板九节外，记了一条非平凡性质 ——
+  **统计量有上界时百分位区间会塌到上界**（极差的重采样值永远 ≤ 原样本极差，实测 `high == estimate`），
+  以及 5 个待拍板口径。`docs/algorithms/README.md` 的进度表同步打勾。
+
+### Fixed
+- `bootstrap_ci` 的 `random_state=None` 分支原来另开 `np.random.default_rng()`，**绕过了 `core.get_rng`** ——
+  与决策 24 冲突：`set_seed` 对它无效、区间不可复现。改成无条件 `get_rng(random_state)`（决策 46）。
+- `bootstrap_ci` 的 `metrics["statistic_name"]`：`hasattr(statistic, "__name__")` 判不出 lambda ——
+  lambda 的 `__name__` 恒为 `"<lambda>"`，于是 `else "custom"` 是**死代码**，自定义统计量拿不到 `"custom"`。
+  改成 `getattr(f, "__name__", None)` 再判 `name in (None, "<lambda>")`（易错点 17）。
+- `bootstrap_ci` 的 docstring 补齐 `Parameters` / `Returns` / `Raises`（§4.7），并如实写明
+  `method="bca"` **尚未实现**（此前 docstring 承诺支持、实现却抛 `NotImplementedError`）。
+
+### Changed
+- `tests/test_stats.py`：**摘掉 3 条 `skip`**（等 `bootstrap_ci` 的那 3 条），并新增 6 条断言 ——
+  `estimate` 等于原样本统计量、`confidence` 单调性、五种容器结果一致、自定义 lambda 走回退分支、
+  **不给种子时跟随 `set_seed`**、非法/未实现 `method`。bootstrap 段共 9 条。
+  全量 **177 条：143 passed / 34 skipped**；ruff 0，pyright 0。
+- `docs/dev/personal-pitfalls.md`：**第 9 条「实现写完了测试还挂着 skip」复发 +1**（这次是 `bootstrap_ci` ——
+  实现写完、3 条测试仍挂 skip、全量照样全绿）；新增第 17 条「`hasattr(f, "__name__")` 挡不住 lambda，
+  `else` 分支是死代码」；索引补到 17。
+- `STATUS.md`：E 节记 `bootstrap_ci`（L0 10/12），决策 46，「下一步」改写并新增第 8 条列 5 个待拍板口径。
+
+### Changed
+- `tests/test_solve.py`：模块级 `pytestmark = pytest.mark.skip(...)` 拆成 **9 条逐条**
+  `@pytest.mark.skip(reason=_NOT_IMPLEMENTED)` —— 模块级 skip 会把整个文件吞掉（决策 26、易错点 9）。
+  用例数与跳过数不变（177 收集 / 143 passed / 34 skipped），仅粒度变细。
+- `STATUS.md`：新增**分工硬规矩（决策 47）** —— 算法一律由用户本人写（即便用户改口也不代写）、
+  工程事务由 Codex 写；L0 计数 9/12 → **10/12**；「下一步」新增「⭐ 明天从这里开始」区块
+  （`monte_carlo` 的契约 / 向量化要求 / 三条测试建议 / 卡片路径 / 一个待拍板口径）；
+  验证结果里的 skip 说明由 37 条订正为 **34 条**。
+
+### Added
+- `solve.monte_carlo` 落地（**L0 第 11 项，S 档**，实现由用户本人写）：向量化"采样 → 仿真 → 汇总"，
+  返回 `Result`（8 个 metrics：mean / std / median / p05 / p95 / ci_low / ci_high），随机数无条件走 `get_rng`。
+  配套 `tests/test_solve.py` **10 条**测试（含"`simulator` 只被调用一次"这条可执行的向量化断言）。
+
+### Fixed
+- `monte_carlo` 的**布尔结果**此前让 `np.std` 在 numpy 2 里抛 `numpy boolean subtract ... is not supported`，
+  整个函数判失败 —— 而"事件是否发生"是 MC 最常见的用法。入口改为 `np.asarray(..., dtype=float)`（布尔按 0/1 统计）；
+  字符串结果也从"ufunc isnan 不支持"变成可读的 `could not convert string to float`。由行为探针挖出。
+- `monte_carlo` 的 docstring `Examples` 跑不通：原采样器返回标量，实测 `success=False`
+  （"simulator 返回的结果数量(1)必须与模拟次数 n(1000)一致"）；改成向量化写法。
+- `monte_carlo` 的 ruff 三条（I001 合并同源 import、F541 空 f-string ×2）、`success= True` 的空格、
+  失败文案"重采样" → "模拟"（从 `bootstrap_ci` 抄过来忘改）。
+
+### Changed
+- `monte_carlo` 按 §4.7 收严 `n`：`np.int64` 不再被误拒（注解放宽为 `int | np.integer`）；
+  `n=True` / 浮点 `n` 抛 `TypeError`；`n<=0` 抛 `ValueError`。
+- 用户第二轮改的三处口径（决策 48）：批量大小改由实现传 `sampler(rng, size=n)`；结果含 NaN 判 `success=False`；
+  `np.std` 显式 `ddof=0`。docstring 同步改写（`sampler` 契约、`Raises`、`Notes` 的 NaN 口径）。
+- `STATUS.md`：L0 10/12 → **11/12**，新增决策 48；验证计数更新为 **187 收集 / 153 passed / 34 skipped**。
+
+### Changed
+- 工作约定收窄（**决策 49**）：**入口没收紧 / 少考虑情况 / 不符合简单原则**这三类改动交回用户本人写，
+  Codex 只报告 + 列选项（判据：这处改动要不要"想一下才对"）。决策 47 里"入口 / 校验重构归 Codex"的部分作废。
+- `docs/dev/personal-pitfalls.md`：新增 **第 18 / 19 / 20 条**（入口校验没照 §4.7 清单逐条过 / 只想着主路径那种值 /
+  "不简单"的信号是同一个信息要写两遍），第 1 条（类型判断只写 `int`）**复发 +1**，索引补到 20。
+- `STATUS.md`：新增决策 49 与两个待拍板小口径（`random_state` 注解是否全项目对齐、`std` 的 `ddof` 是否统一）。
+
+### Added
+- `solve.monte_carlo_probability` 落地（**L1，S 档**，实现由用户本人写）：向量化 `event(batch) -> bool 数组`，
+  返回 `Result`（`probability` / `ci_low` / `ci_high` / `std_error`），区间是 Wald 区间并夹在 `[0, 1]`（沿用决策 42 口径）。
+  `tests/test_solve.py` 新增 5 条 + **摘掉 2 条 skip**（实现已写完却还挂着，易错点 9），`solve` 段共 24 条。
+
+### Fixed
+- `monte_carlo_probability` 的 docstring `Examples` 跑不通：原采样器返回标量，实测 `success=False`
+  （"event 返回的结果数量(1)必须与模拟次数 n(2000)一致"）；改成批量采样写法并实测通过。
+- `monte_carlo_probability` 的 ruff 六条：SIM300（`0.0 >= confidence` 写成 Yoda 条件）、W291 ×2、W293 ×2、F541。
+- 该函数 NaN 提示里的 "simulator" 改成 "event"（从 `monte_carlo` 抄来没改）；`metrics` 缩进与 `{"n":n}` 空格。
+
+### Changed
+- `monte_carlo_probability` 的 docstring 补齐 `Parameters` / `Raises`（原文只有 Returns / Notes / Examples），
+  并把"Wald 区间 + 夹到 [0,1]"与"`p <= 1e-3` 判失败"两条现状如实写进 Returns / Notes。
+- `STATUS.md`：L1 清单加入 `monte_carlo_probability`；验证计数更新为 **192 收集 / 160 passed / 32 skipped**；
+  「下一步」新增该函数的 **6 条待办口径**（全部留给用户，Codex 未动）。
+
+### Fixed
+- **`monte_carlo_probability` 的 `z_score^2` 是异或不是乘方**（Python `^` 语义）：`np.float64 ^ 2` 直接抛
+  `TypeError: ufunc 'bitwise_xor' not supported`，被 `except Exception` 吞成 `success=False` —— 函数实际上**整个不可用**，
+  6 条测试全红才暴露。改成 `z_score**2`。新增经验第 21 条。
+- `monte_carlo_probability` 的 message 在没有警告时留了个尾逗号；`{"confidence":confidence}` 补空格。
+
+### Changed
+- 用户第二轮改定（**决策 50**）：区间由 **Wald 换成 Wilson score**（实测 p=1、n=1000 从退化的 `(1.0, 1.0)`
+  变成 `(0.99617, 1.0)`；p=0 从"判失败"变成 `(0.0, 0.00383)`）；小概率不再判失败，改为 message 里的警告；
+  `confidence` 记进 `Result.params`；`callable` 入口校验（现在抛 `TypeError`）；`float()` 统一 `ci_*` 类型；
+  `n` 注解放宽为 `int | np.integer`。
+- `tests/test_solve.py`：新增 1 条对照测试（区间必须等于 `statsmodels.proportion_confint(method="wilson")`），
+  共 25 条；全量 **193 收集 / 161 passed / 32 skipped / 0 xfail**。
+- `docs/dev/personal-pitfalls.md`：新增第 **21** 条（公式里的 `^` 不是乘方，且被 `except` 吞成 `success=False`），索引补到 21。
+- docstring 的 "Wald 区间" 同步改为 "Wilson score 区间"。
+
+### Added
+- `solve.monte_carlo_integral` 落地（**L1，S 档**，实现由用户本人写）：`bounds` → 自造 `(n, d)` 均匀样本 → 逐点求值 →
+  `mean(func(X) × 体积)`；内部自造 `sampler` / `simulator` 再复用 `monte_carlo` —— "造批 → 一次算 → 汇总"的第二次复用。
+  `params` 额外记 `bounds` / `dimension`；配套 `tests/test_solve.py` 新增 4 条 + 摘 1 条 skip。
+
+### Fixed
+- **`monte_carlo_integral` 的体积符号写反**（真 bug，按决策 31 修）：写成 `wights = lows - highs`，奇数维体积为负 ——
+  1D `x²` 于 `[0,1]` 实测 **-0.3324**（应 +1/3）、3D `x` 得 **-0.5005**（应 +1/2）；**2D `x·y` 却得 +0.2499 "看着对"**
+  （两个负号相乘抵消，把 bug 藏住）。改成 `widths = highs - lows` 后复测 **0.3324 / 0.5005 / 1.9971（`[0,2]`）** 全部正确。
+- `monte_carlo_integral` 的 docstring `Examples` 跑不通：断言 `abs(r.data - 1 / 3) < 0.01`，而 `data` 是 n 个样本的贡献数组，
+  `bool(数组)` 会抛 `ValueError: truth value ... is ambiguous`；改成断言 `metrics["mean"]`。
+- 格式：`simulate.py` 里 `def random_walk` 前只留了 1 个空行；`tests/test_solve.py` 有 3 处留了 3 个空行。
+
+### Changed
+- `monte_carlo_integral` 的 docstring 补齐 `func` / `n` / `random_state` 三节 `Parameters` 与 `Raises`（原文只有 `bounds` +
+  Notes + Examples）；`Returns` 写清"**`metrics["mean"]` 才是积分估计值**，`data` 是 n 个样本各自的贡献"（**决策 51**）。
+- `tests/test_solve.py`：摘掉 `test_monte_carlo_integral_converges_to_analytic_value` 的 skip，新增 3 条"抓符号"用例
+  （3D 奇数维、`[0,2]` 宽度、2D + `name`/`dimension`/`bounds` 三个 params）与 1 条非法 `bounds` 抛 `ValueError`；
+  `solve` 段 25 → **30** 条，全量 **197 收集 / 166 passed / 31 skipped / 0 xfail**（ruff 0 / pyright 0）。
+- `STATUS.md`：L1 清单加入 `monte_carlo_integral`；新增**决策 51** 与「`monte_carlo_integral` 的 3 条待办」；
+  「下一步」改成从 `random_walk` 接着写；验证计数更新为 166 / 31；`monte_carlo_probability` 的 6 条待办收窄到 1 条。
+- `docs/dev/personal-pitfalls.md`：新增第 **22 / 23** 条（失败结果的 `message` 被包装层无条件覆盖；体积/宽度也会减反、
+  维度奇偶会把符号错误藏住），第 3 条（注解与 docstring 不一致）**复发 +1**，索引补到 23。
+- `tmp/type_demo.py`（gitignored）：用 pyright 证明 `Callable[..., bool]` 会**拒绝**一个注解良好的向量化 `event`
+  （`ndarray` 与 `bool` 不兼容），`Callable[..., Any]` 才收 —— 这是决策 50 那条遗留的实际代价。
+
+### Fixed
+- `monte_carlo_integral` 的 `bounds` 形状校验缺失（用户第二轮补齐）：`bounds=[0, 1]` 从裸 `IndexError: too many indices`
+  变成可读 `ValueError`（带当前形状与"请检查是否漏了括号"）；`[]` / 非 `list`-`tuple` / 参差不齐的输入也一并收口。
+- `monte_carlo_integral` 的失败 `message` 被包装层覆盖（用户第二轮改成 `if result.success:` / `else:` 两支）：
+  `func` 返回标量时不再是 `success=False` + "成功"文案，而是"蒙特卡洛多重积分失败：维度 1，体积 1.0000，模拟 100 次。
+  蒙特卡洛模拟失败：TypeError - object of type 'float' has no len()"。
+- 格式：`simulate.py` 两行"只有空格的行"（ruff W293 ×2，Codex 顺手补）。
+
+### Changed
+- `monte_carlo_probability` 的 `event` 注解 `Callable[..., bool]` → `Callable[..., Any]`（用户改，**决策 50 的遗留清零**）：
+  pyright 实测原注解会**拒绝**一个注解良好的向量化事件函数（`ndarray` 与 `bool` 不兼容），运行期却一直收得下。
+- `monte_carlo_integral` 的 `n` 注解放宽为 `int | np.integer`（与全模块对齐，易错点 1 的老口径）。
+- `monte_carlo_integral` 的 docstring：`bounds` 入参说明与 `Raises` 同步到新入口校验（补"非空 `list`/`tuple`、形状 `(d, 2)`"）。
+- `tests/test_solve.py`：非法 `bounds` 从 1 类扩到 4 类（`[(1, 0)]` / `[0, 1]` / `[]` / 参差不齐），新增"失败 message 不许出现
+  '成功'"与 `np.int64` 两条；`solve` 段 30 → **32** 条，全量 **199 收集 / 168 passed / 31 skipped / 0 xfail**（ruff 0 / pyright 0）。
+- `STATUS.md`：integral 的 3 条待办标记办结、概率函数的 6 条待办全部办结；新增**决策 52** 与 2 条新口径
+  （`bounds` 收不收 ndarray、`if`/`else` 里那三行重复）；验证计数更新为 168 / 31。
+
+### Added
+- `solve.random_walk` 落地（**L1，S 档**，实现由用户本人写）：`step_sampler(rng, size=(n_paths, n_steps))` 一次抽完整批增量 →
+  `np.cumsum(..., axis=1)` → 首列填 `start`、其余列 `start + cumsum`；`data` 形状 `(n_paths, n_steps + 1)`。
+  配套 `tests/test_solve.py` **新增 6 条**（此前这个函数一条测试都没有）。
+
+### Fixed
+- **`random_walk` 的默认采样器整个不可用**（真 bug，按决策 31 修）：`rng.integers(0, 2, size=size, dtype=float)`
+  被 numpy 拒掉（`TypeError: Unsupported dtype dtype('float64') for integers`）—— 默认路径 100% `success=False`、
+  `data=None`，连 docstring 的 Examples 都跑不通。改成 `rng.integers(0, 2, size=size) * 2 - 1`
+  （由后面的 `np.asarray(..., dtype=float)` 统一转 float）；实测形状 `(5, 101)`、步长恒 ±1、同种子可复现。
+- 格式：`simulate.py` 又两行"只有空格的行"（ruff W293 ×2）。
+
+### Changed
+- `monte_carlo_integral` 按用户第二轮口径收口（**决策 52**）：`bounds` 现在也收 `np.ndarray`；
+  `name` / `params["bounds"]` / `params["dimension"]` 从 `if` / `else` 两支提到 `if` 之前，只让 `message` 分两支。
+- `random_walk` 的 docstring 补全（原文只有 `step_sampler` 一节）：补齐 `n_steps` / `n_paths` / `start` / `random_state`
+  与 `Returns` / `Raises` / `Notes`，并写清 `step_sampler` 收的是**二维** `size=(n_paths, n_steps)`。
+- `tests/test_solve.py`：新增 6 条 `random_walk` 测试（形状与 `start` 列、默认步长恒 ±1、同种子可复现、
+  自定义高斯采样器、3 类非法入参、docstring Example 真能跑）；`solve` 段 32 → **38** 条，
+  全量 **205 收集 / 174 passed / 31 skipped / 0 xfail**（ruff 0 / pyright 0）。
+- `STATUS.md`：新增**决策 53** 与 `random_walk` 的 4 条待办；`monte_carlo_integral` 的 2 条新口径办结 1 条
+  （剩"第一道 `isinstance` 分支已冗余"）；「下一步」推进到 `markov_simulate` / `markov_steady_state`。
+
+### Fixed
+- **`random_walk` 的失败路径全部炸成 `UnboundLocalError`**（真 bug，按决策 31 修）：`call_params = {...}` 写在 `try:` 里，
+  而 `except` 分支要引用它 —— 实测 5 种失败输入（形状不对 / 增量含 NaN / 采样器抛异常 / `start` 非数值 / 返回 1-D 数组）
+  **5 个全中**，本该返回 `success=False` 的 `Result`，变成把异常抛给调用方。按原意把 `call_params` 前移到 `try` 之前，
+  未改任何口径；失败时照样带上 `n_steps` / `n_paths` / `start` / `random_state`。
+
+### Changed
+- `random_walk` 按用户第二轮口径改定（**决策 54**）：`n_steps` / `n_paths` 拆成 `TypeError`（类型）/ `ValueError`（取值）；
+  新增 `steps.shape != (n_paths, n_steps)` 与 `np.isnan(steps).any()` 两条校验；默认步长改 `rng.choice([-1.0, 1.0], size=size)`；
+  `params` 补 `random_state`；`metrics` 由"抄 params"改成 `mean_terminal` / `std_terminal`（终点位置，`ddof=0`）。
+- `random_walk` 的 docstring 同步：`Returns` 写实际 metrics、`Raises` 改成"类型错 `TypeError` / 取值错 `ValueError`"、
+  去掉已不存在的 `start` 校验、`Notes` 记明形状与 NaN 都判失败。
+- `tests/test_solve.py`：+3 条（"失败也必须返回带 params 的 Result"、NaN 判失败、终点 `std ≈ √t`），
+  `start="a"` 改为断言 `success is False`（口径待定）；`solve` 段 38 → **41** 条，
+  全量 **208 收集 / 177 passed / 31 skipped / 0 xfail**（ruff 0 / pyright 0）。
+- `STATUS.md`：新增**决策 54** 与 `random_walk` 的 3 条新口径；4 条待办标记办结；验证计数更新为 177 / 31。
+- `docs/dev/personal-pitfalls.md`：新增第 **26** 条（`except` 用到的变量在 `try` 里才赋值 —— 每条失败路径都炸）。
+
+### Changed
+- `random_walk` 收口 2 条口径（用户第二轮改动）：恢复 `start` 的入口类型校验（`isinstance(start, (int, float, np.number))`）；
+  签名注解放宽为 `n_steps: int | np.integer` / `n_paths: int | np.integer`（与 §4.7 及 `monte_carlo_integral` 的 `n` 对齐）。
+- `random_walk` 的 `start` 报错文案（Codex 顺手）：原文"start必须是整数"与校验本身矛盾 —— 这条校验**收 float**，
+  改成"start 必须是数值"；类型名统一 `{type(start).__name__}`（全模块口径）；`n_paths: int | np.integer= 1` 补空格。
+- `random_walk` 的 docstring 同步：`start` 的说明去掉"入口不校验类型"，`Raises` 补回 `start` 的 `TypeError`。
+- `tests/test_solve.py`：`start="a"` 恢复断言 `TypeError`；补回 `np.int64` 的 `n_steps` / `n_paths`；
+  `solve` 段 41 → **42** 条，全量 **209 收集 / 178 passed / 31 skipped / 0 xfail**（ruff 0 / pyright 0）。
+- `STATUS.md`：新增**决策 55**（`n_paths == n_steps` 的"方阵歧义"留作已知边界，A 接受 / B 换契约两条路）；
+  3 条口径办结 2 条，验证计数更新为 178 / 31。
+
+### Changed
+- `random_walk` 的 `step_sampler` 契约按**方案 B** 重定（用户拍板，**决策 55**）：`size` 由 `(n_paths, n_steps)` 改为**整数**
+  `n_paths * n_steps`，必须返回**一维**数组，内部 `reshape(n_paths, n_steps)`（行主序）。
+  **动因**：转置 `(n_steps, n_paths)` 与目标 `(n_paths, n_steps)` 在 `n_paths == n_steps` 时形状相同，形状校验天生分不出来（易错点 25）。
+  探针实测：默认采样器 `(5, 101)` 正常；转置二维 / 方阵二维 / 长度 +1 / `(N, 1)` 四种返回一律判失败。
+  **关键点：不要用 `.ravel()` 救场**，那会把转置的二维摊平、歧义原样回来。红利：与 `monte_carlo` 的 `sampler`（决策 48 的 `size=n`）
+  契约统一，给 `monte_carlo` 写的采样器可直接复用（实测通过）。
+- `random_walk` 的 docstring 同步：`step_sampler` 说明改为"整数 `size` + 一维返回 + 行主序"，`Notes` 记明二维返回一律判失败。
+- `tests/test_solve.py`：把"转置采样器"那条改成 `test_random_walk_rejects_2d_step_sampler`（含方阵情形），
+  新增 `test_random_walk_step_sampler_gets_flat_size_and_is_row_major`（验 `size == 6` 与 `cumsum` 的行主序结果）；
+  `solve` 段 42 → **43** 条，全量 **210 收集 / 179 passed / 31 skipped / 0 xfail**（ruff 0 / pyright 0）。
+- `STATUS.md`：决策 55 改为"已选 B 并落地"；`random_walk` 的 7 条待办全部办结；验证计数更新为 179 / 31。
+
+### Added
+- `solve.markov_simulate` 落地（**L1，S 档**，实现由用户本人写）：`arr[current_states]` 取当前状态那一行 →
+  `cumsum` 得累积分布 → 用 `[0, 1)` 均匀数"落格"（`(cum_probs < r[:, None]).sum(axis=1)`）→ 写进下一列；
+  `data` 形状 `(n_paths, steps + 1)`、值是整数状态编号。Codex 审查结论：**算法本体正确**
+  （探针实测 200 步后终点频率 `[0.657, 0.343]` 对照平稳分布 `[2/3, 1/3]`、同种子可复现）。
+- `tests/test_solve.py`：新增 9 条 `markov_simulate` 测试（此前 0 条）—— 形状 / 首列 / 状态取值 / 整数 dtype、
+  单位矩阵吸收态自锁、可复现（同种子相同、异种子不同）、终点频率收敛到 `[2/3, 1/3]`、metrics = 终点状态、
+  非法转移矩阵（非方阵 / 行和不为 1）、非法 `steps` / `n_paths`（0 / float / bool）、`np.int64` 可收、docstring Example 真能跑。
+
+### Changed
+- `markov_simulate` 的 docstring 从一行补到完整的 `Parameters` / `Returns` / `Raises` / `Notes` / `Examples`。
+- `markov_simulate` 的工程侧清理：`kind` 全程未用 → `arr, _`；`马尔科夫` → `马尔可夫`（3 处）、
+  `initail` → `initial`、半角逗号 → 全角；`paths[:,0]` → `paths[:, 0]`；ruff 8 条全清（`I001` + `W291` / `W293`）。
+- `STATUS.md`：新增**决策 56**（`initial` 的语义待拍板，含 A / B / C 三个选项）与 5 条待办；
+  验证计数更新为 **188 passed / 31 skipped（219 收集）**。
+
+### Notes
+- **`markov_simulate` 的 5 条口径留给用户**（决策 49）：`initial` 语义（标量按路径数 / 数组按状态数，两条口径互相矛盾）、
+  转移矩阵未查非负（行和恰为 1.0 的 `[[1.5, -0.5], [0, 1]]` 会静默给出全 0）、`paths[:, 0]` 赋值在 `try` 之外
+  （长度不匹配时裸抛 `ValueError`）、状态越界没在入口拦、`std_terminal` 对分类状态的意义。
+
+### Added
+- `solve.markov_steady_state` 落地（**L1，S 档**，实现由用户本人写）：`v` 从均匀分布出发，`v_next = v @ arr`
+  反复推进（行随机矩阵按行向量右乘），直到 `max|v_next - v| < tol` 或耗尽 `max_iter`；
+  `data` 是平稳分布向量、`metrics={"converged", "iterations"}`。Codex 审查结论：**算法本体正确** ——
+  3 状态与 `np.linalg.eig(P.T)` 特征值 1 的特征向量逐位一致、200×200 一致到 `1.9e-12`（6 次迭代 / 0.10s）、
+  与 `markov_simulate` 的终点频率互验 `[0.6702, 0.3298]` vs `[0.6667, 0.3333]`。
+- `tests/test_solve.py`：摘掉 `test_markov_steady_state_two_state_chain` 的 skip，另新增 7 条 ——
+  与特征分解对拍、`data` 是分布（和为 1 / 非负 / `float64`）、慢混合链迭代次数 > 100、`np.int64` 的 `max_iter`、
+  非法转移矩阵、`max_iter=0` / `tol=0`、docstring Example 真能跑。
+
+### Changed
+- `markov_steady_state` 的 docstring 补全：`max_iter` / `tol` 两个参数、`Raises` 一节，
+  并写清 `tol` 是**相邻差口径**（实测慢混合链 `tol=1e-10` 的实际误差 `4.6e-9`，被 `1/(1-|λ2|)` 放大约 50 倍）。
+- `markov_steady_state` 的 Notes 修正"周期链会不收敛"的说法：可约链的实情是**平稳分布不唯一**，
+  迭代法给出的是"离初值最近的那个"（均匀初值对双随机矩阵本身就是不动点，所以 `iterations=1` 不代表链唯一平稳）。
+- `markov_steady_state` 的工程侧清理：ruff 5 条 `W293`；`mm1_metrics` 前 4 个空行 → 2；失败文案 `失败: ` → `失败：`。
+- `STATUS.md`：新增**决策 57**（6 条待拍板口径）与「下一步」第六轮；验证计数更新为 **196 passed / 30 skipped（226 收集）**。
+- `docs/dev/personal-pitfalls.md`：新增易错点 28（数值阈值参数的 `bool` / NaN 漏网）。
+
+### Notes
+- **`markov_steady_state` 的 6 条口径留给用户**（决策 49）：转移矩阵未查非负（行和恰为 1.0 的 `[[1.5, -0.5], [0, 1]]`
+  会溢出成 `nan`，而 `data=[nan, nan]` 却 `success=True`，违反决策 48 的 NaN 口径；附带的 `RuntimeWarning`
+  在 pyproject 里被设成 error，**测试会直接报错**）、`tol=True` 被当 `tol=1` 静默放行（`isinstance(True, int)`）、
+  `tol=np.nan` 穿过校验白跑迭代、`converged=False` 仍 `success=True`、
+  类型错也抛 `ValueError`（与决策 54 分工不一致）、`params` 没记转移矩阵。
+
+### Added
+- `solve.mm1_metrics` 落地（**L1，S 档**，实现由用户本人写）：闭式解 `ρ = λ/μ`、`L = ρ/(1-ρ)`、
+  `Lq = ρ²/(1-ρ)`、`W = 1/(μ-λ)`、`Wq = W - 1/μ`；`λ >= μ` 走"系统不稳定"分支返回 `success=False`。
+  Codex 审查结论：**公式全对**（探针实测 3 组参数 `(2,3)` / `(1,4)` / `(0.5,1.0)` 与闭式公式逐位一致，
+  `W = Wq + 1/μ` 恒等式成立）。至此 `solve` 层的 L1 清单**全部落地**。
+- `markov_simulate` / `markov_steady_state` 增加**非负校验**（用户 2026-10-09 改定）：含负元素的行随机矩阵
+  现在入口即报错，不再静默给出错结果（前者会"全落 0"，后者会溢出成 `nan` 却报成功）。
+- `markov_steady_state` 的 `params` 补 `transition`（`arr.tolist()`）；`success=converged`
+  （未收敛判失败，口径 B）；`tol` 拆成 `TypeError` / `ValueError` 且先判 `bool`。
+- `tests/test_solve.py`：摘掉 2 条 `mm1_metrics` 的 skip，新增 4 条（含 `λ == μ` 的回归测试）；本轮累计 +6 条。
+
+### Fixed
+- **`mm1_metrics` 的稳定性分界写错**（真 bug，按决策 31 修）：`service_rate < arrival_rate` 与 docstring / 既有测试的
+  `λ >= μ` 口径不符 —— `λ == μ` 会掉进 `try`、`rho == 1.0` → `ZeroDivisionError`，被吞成 `success=False`
+  （结果碰巧对，但 message 成了"计算失败：ZeroDivisionError - float division by zero"）。改成 `<=` 并加回归测试；
+  **两个分支的可观测输出完全相同（`success=False` / `metrics={}` / `data=None`），故未动任何口径**。
+- **三处报错文案的参数名抄错**：`markov_steady_state` 的 `max_iter <= 0` 写成"tol 必须是正数"；
+  `mm1_metrics` 的 `service_rate` 两条报错都写成 "tol"。顺带把半角逗号统一成全角。
+
+### Changed
+- `mm1_metrics` 的 docstring 补 `Raises` 与 `data` 说明；`call_params = {{...}}` 补空格；
+  ruff 6 条（5 处 `W293` + `F541` f-string 无占位符 + `W292` 文件末尾无换行）。
+- `markov_steady_state` 的 `try` 前 3 个空行 → 1；`异常: ` → `异常：`。
+- `STATUS.md`：决策 56 / 57 更新办结项，新增**决策 58**（`mm1_metrics` 的 4 条待拍板）；「下一步」推进到第七轮；
+  验证计数更新为 **202 passed / 28 skipped（230 收集）**。
+- `docs/dev/personal-pitfalls.md`：新增易错点 29（同一个校验里的两把尺子）。
+
+### Notes
+- **待用户拍板的口径**（Codex 只报不改）：`markov_simulate` 4 条（`initial` 语义 A/B/C、`paths[:, 0]` 赋值位置、
+  状态越界、`std_terminal` 对分类量）、`markov_steady_state` 3+2 条（`tol` 的 NaN、`max_iter` 类型错、
+  非负校验的**容差**、未收敛却带 `data`）、`mm1_metrics` 4 条（`λ = 0`、numpy 标量、`data=metrics`、
+  失败分支丢 `rho`）。详见 `STATUS.md` 决策 56 / 57 / 58。
+
+### Added
+- `tests/test_solve.py`：本轮再 +2（`markov_simulate` 的 `terminal_distribution` 口径、
+  `mm1_metrics` 的 `λ = 0` 空系统），并把受口径变更影响的 5 条测试同步到新行为。
+
+### Changed
+- `markov_simulate`：非负校验带容差 `-1e-12`（浮点归一化的 `-1e-16` 残渣不再被误判）；
+  `initial` 收 `np.integer`；`paths` 构造与首列赋值挪进 `try`（长度不匹配 / 状态越界不再裸抛）；
+  `params` 键 `n_steps` → `steps`、`initial` 存成可 JSON 化的标量 / 列表；
+  `metrics` 的 `std_terminal` → `terminal_distribution`（`{状态: 频率}`，只列出现过的状态）。
+- `markov_steady_state`：非负校验带容差；`max_iter` 类型错改抛 `TypeError`；`tol` 增加 `np.isnan` 拦截；
+  非方阵改抛 `TypeError`。
+- `mm1_metrics`：`arrival_rate` 放开为**非负**（`λ = 0` = 空系统，`L = Lq = Wq = 0`、`W = 1/μ` 取极限值）；
+  两个速率收 `np.number`；不稳定分支保留 `rho` 并写进 message；`data=metrics.copy()`（去掉同一个 dict 对象的别名）。
+- docstring 同步：`markov_simulate` 的 `Returns` 与"遗留"段、`markov_steady_state` 的 `Raises`（TypeError / ValueError 分工）、
+  `mm1_metrics` 的 `Parameters` / `Returns` / `Raises`。
+- ruff：`B905`（`zip` 缺 `strict`）+ 2 条空白 → 0；`markov_simulate` 里 `rng` 之后的双空行 → 1。
+- `STATUS.md`：决策 56 / 57 / 58 更新到"只剩 5 条小口径"，「下一步」推进到第八轮，
+  并写入**第八轮备忘：`models` 与 `decision` 各是干什么的**（含两包的 19 / 8 个函数清单、使用顺序、建议开工顺序）。
+- `docs/dev/personal-pitfalls.md`：新增易错点 30（口径一改，docstring / 测试 / STATUS 三处会同时过期）。
+
+### Notes
+- **只剩 5 条口径待拍板**（Codex 只报不改）：`markov_simulate` 的 `bool` 漏网与 `initial` 的 A/B/C、
+  `markov_steady_state` 未收敛时是否带 `data`、非方阵的 `TypeError` / `ValueError` 不一致、
+  `mm1_metrics` 的 `data` 该不该是 dict。
+
+### Added
+- `models/metrics.py`：6 个回归指标落地（**由用户本人实现**）—— `rmse` / `mae` / `mape` / `smape` /
+  `r2_score` / `adjusted_r2`，共用一个入口守卫 `verify_yt_yp`（`as_array` → 形状 / 空 / NaN 三道校验）。
+  `compare_models` 仍是 `TODO(L1)`。
+- `tests/test_models.py`：5 条 → **23 条**。`test_metrics_known_values` / `test_r2_is_one_for_perfect_fit`
+  两条摘掉 `skip` 转正，另新增 18 条 —— 形状不一致 / 空 / NaN / `str` 被 `TypeError` 挡、四种入参
+  （`DataFrame` / `Series` / `ndarray` / `list`）结果一致 ×5、`mape` 遇 0、`smape` 全 0 且**不许漏告警**、
+  `adjusted_r2` 的 `bool` / `float` / `0` / 分母保护 / `np.int64` / 惩罚单调性，以及 `r2_score` 的
+  **非完美拟合**解析值与 `sklearn.metrics.r2_score` 对照。
+
+### Changed
+- `models/metrics.py`：`r2_score` 的 `SS_tot` 基准由 `np.mean(y_pred)` 改为 `np.mean(y_true)`（**真 bug**，
+  由用户亲手改定，见 STATUS 决策 59 / 个人易错点 31），`ss_tol` 随之改名 `ss_tot`；修前 0.8803827751196172、
+  修后 0.875（与 sklearn 一致），`adjusted_r2` 同步修正。
+- `models/metrics.py`：`smape` 的零除改用 `np.divide(..., out=..., where=denom != 0.0)` ——
+  `np.where` 的两条分支都会被求值，原写法在 `filterwarnings = ["error::RuntimeWarning"]` 下会让
+  "含 0 的 smape"测试直接失败（决策 60）。数值结果与口径不变。
+- `models/metrics.py`：补 7 处 docstring（`Parameters` / `Returns` / `Raises`），把"NaN 报错 / `mape` 遇 0 报错 /
+  `r2_score` 常量 y 报错 / `adjusted_r2` 的分母保护"写成契约；`n_features` 的口径写明**不含截距**。
+- `models/metrics.py`：报错文案统一为"参数名 + 实际值"（形状不一致会带上两个 `shape`）；
+  ruff 9 条清零（6 条 `F541` 无占位符 f-string + 3 条 `W293`）+ 补函数间空行。
+- `STATUS.md`：新增**决策 59 / 60**，「下一步」推进到第九轮（含 4 条待拍板口径）；
+  验证计数更新为 **224 passed / 26 skipped（250 收集）**。
+- `docs/dev/personal-pitfalls.md`：新增易错点 31（公式的"基准量"抄错对象，且完美拟合会掩盖它）、
+  32（`np.where` 掩码防不住零除）。
+
+### Notes
+- **4 条口径待用户拍板**（Codex 只报不改）：`mape` 遇负 `y_true` 现在返回负数、只拦 `NaN` 不拦 `inf`、
+  `rmse(1.0, 1.0)` 这类标量被当成 1 个样本、`compare_models` 的键名 `"r2"` 与函数名 `r2_score` 不一致。
+  详见 `STATUS.md`「第九轮新增：4 条口径待你拍板」。
+
+### Added
+- `models.compare_models`：落地（**Codex 按 A 档实现**，决策 62）。返回 `pd.DataFrame`（行 = 模型、列 = 指标），
+  按第一个指标排序（误差类升序、R² 降序）。`cv=0` 全量拟合后打分；`cv >= 2` 用**手写 K 折**
+  （`get_rng(random_state).permutation` + `np.array_split`，**不引入 sklearn 依赖**）报折间均值。
+- `models/metrics.py` 的**指标名别名映射** `_METRIC_FUNCS`：`"r2"` 与 `"r2_score"` 指向同一个函数，
+  传哪个名字列名就叫哪个；两个一起传报 `ValueError`。`adjusted_r2` 不进表（需要 `n_features`）。
+- `tests/test_models.py`：23 → **31 条**。首列排序（升序 / 降序）、别名映射、坏指标名 / 坏 `models` / 坏 `cv`、
+  每折样本数下限、`random_state` 可复现；另新增 `Inf` 与"至少 2 个样本"两条入口测试。
+  原 `test_compare_models_returns_table_sorted_by_first_metric` 的**用法是错的**（把拟合结果当模型传），
+  已改写成用测试桩 `_MeanModel` / `_LinearModel` 并摘掉 `skip`。
+
+### Changed
+- `models/metrics.py`：用户的第三轮入口改动入库（决策 61）—— `verify_yt_yp` 增加 `Inf` 拦截、
+  增加"至少 2 个样本"（标量不再被当成 1 个样本）；`mape` 由"只拦 0"改成拦 `y_true <= 0`
+  （原式对负数返回**负数**，实测 `-1.0`）。
+- `models/metrics.py`：三条新口径同步进 7 处 `Raises`，`mape` 的 `Returns` 与摘要改为"`y_true` 必须全为正数"
+  （**易错点 30 复发 1 次**：口径一改、docstring 立刻过期）。
+- `models/metrics.py`：`compare_models` 的入口收口 —— `X` 必须二维（`as_array(ndim=2)` 不替你猜）、
+  `cv` 白名单（`bool` 拒收 / `cv=1` 无意义 / `cv <= n // 2`）、`models` 必须是"有 `fit` / `predict` 的对象"、
+  `metrics` 必须是 `tuple` / `list`（单个字符串给专门的报错文案）。
+- `models/metrics.py`：模块 docstring 改为"指标函数只返回 `float`，唯一例外是 `compare_models`（返回 `DataFrame`）"。
+- `STATUS.md`：新增**决策 61 / 62**，第九轮那 4 条口径标记办结，「下一步」推进到第十轮；
+  验证计数更新为 **233 passed / 25 skipped（258 收集）**。
+- `docs/dev/personal-pitfalls.md`：易错点 30 记为**复发 1 次**；新增易错点 33
+  （多行报错文案少引号 / `raise ValueError("a", "b")` 多参数 —— ruff 一秒能抓，别等运行时）。
+
+### Notes
+- **1 条小口径待用户拍板**：`verify_yt_yp` 里 `yt.ndim == 0` 是死代码（`as_array(ndim=1)` 必然摊平），
+  可塌成 `if yt.shape[0] <= 1:`。详见 `STATUS.md`「第十轮新出现的 1 条小口径」。
+- **等 `fit_linear` 落地时补一条集成测试**：`compare_models` + 真实模型对象。
+
 ## [0.0.1] - 2026-10-01
 
 ### Added

STATUS.md

@@ -1,6 +1,6 @@
 # STATUS — 当前进度
 
-> 更新日期：2026-10-01
+> 更新日期：2026-10-18
 
 ## 本次任务
 
@@ -8,9 +8,30 @@
 配置 conda 与 venv 环境 → 初始化 git 仓库 → 接入 Gitea 远端。
 两套环境均已建成并通过验证，仓库已推送到 `code.guzhujushi.cn`。
 
-**第二阶段（进行中）**：按 `docs/03-roadmap.md` 的 L0 → L1 顺序**逐个实现函数**，
+**第二阶段（进行中）**：按 `docs/03-roadmap.md` 的 L0 → L1 顺序**逐个实现函数**。
-用户本人写 `src/`、Codex 负责审查 + `tests/`（决策 25）。
+
-当前 3/12：`Result`、`get_rng`/`set_seed`、`load_table`/`save_table`。
+**分工硬规矩（决策 47，用户 2026-10-03 明确）**：
+- **算法一律由用户本人写**（S 档尤其）—— 即便用户说"你写吧"也不代写，
+  要保住"一边学一边自己写"的路径。
+- **工程事务由 Codex 写、用户读**：入口/校验重构、`tests/`、docstring、ruff、
+  `STATUS.md` / `CHANGELOG.md`、函数卡片、`.gitignore` 等。
+- A 档**薄封装**（`rmse`/`mae`/`fit_linear`/`train_test_split`…）算工程，Codex 可直接实现。
+- 分地盘按**文件**划，不按函数划（同一文件两人各写一半曾导致用户编辑器保存失败）。
+
+当前 **L0 12/12（已全部完成）**：`Result`、`get_rng`/`set_seed`、`load_table`/`save_table`、`clean_missing`、
+`detect_outliers`、`normalize`/`standardize`、`describe`、`correlation_matrix`、`bootstrap_ci`、
+`monte_carlo`（**用户写**，2026-10-04）；另**提前落地**了 L1 的 `confidence_interval` / `t_test` /
+`monte_carlo_probability`、`monte_carlo_integral`、`random_walk`、`markov_simulate`、
+`markov_steady_state`、`mm1_metrics`（**均为用户写**）—— `solve` 层的 L1 清单**已全部落地**。
+`save_figure` 已于 2026-10-18 由 Codex 落地，L0 收官。
+**`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 条细枝末节（详见"下一步"第八轮）。
+另 3 个小口径仍悬着：`ci_low`/`ci_high` 的语义、`monte_carlo_integral` 的第一道 `isinstance` 分支可塌成两行、
+`random_state` 注解与 `std` 的 `ddof` 是否全项目对齐。
 
 ## 任务清单
 
@@ -62,7 +83,7 @@
 - [x] 推送通道：公网 22 被防火墙过滤 → 改用 Tailscale（`100.115.86.48:22`），
       `~/.ssh/config` 加了一条域名别名，remote 里仍写域名
 
-**E. L0 实现进度（3/12）**
+**E. L0 实现进度（10/12）**
 - [x] `core/result.py` 的 `Result`
       - `__repr__`：单行紧凑；`data` 只给类型与规模，**绝不**整数组打印
         （十万级数组的 repr 实测仍 < 200 字符）；`success` 恒在
@@ -85,25 +106,319 @@
         utf-8 → utf-8-sig → gbk → gb18030，显式传 `encoding=` 时不再探测
       - `na_values` 默认吃下空串 / `NA` / `N/A` / `#N/A` / `null` / `-`
       - 不支持的扩展名抛 `ValueError`；文件不存在抛带路径的 `FileNotFoundError`
-      - 测试：`tests/test_data.py` 由 1 条（且被模块级 skip 掉）扩到 **8 条**
+      - `save_table` 的校验顺序已修正：后缀判断提到 `mkdir` 之前
-- [ ] 剩余 9 项（10 个函数）：`clean_missing`
+        （此前传 `.txt` 会先留下一个空目录再抛错）
-      `detect_outliers` `normalize` `standardize` `describe` `correlation_matrix`
+      - 测试：`tests/test_data.py` 由 1 条（且被模块级 skip 掉）扩到 **9 条**
-      `bootstrap_ci` `monte_carlo` `save_figure`
+      - docstring 的 `Parameters` / `Raises` 已按 §4.7 补齐（Codex 代写，用户授权）——
+        numpydoc 格式，对齐参考实现 `core/random.py` 的 `get_rng`
+- [x] `data/clean.py` 的 `clean_missing`（L0 第 4 项）
+      - 实现由**用户本人**写，Codex 只做审查、补测试与文档
+      - `threshold` 用 `math.ceil` 算 `min_non_na`：3 列、阈值 0.5 时必须是 2，
+        写 `int()` 截断会漏删
+      - 顺手落地兄弟函数 `impute_missing` / `winsorize`（原属 L1）
+- [x] `data/clean.py` 的 `detect_outliers`（L0 第 5 项，S 档，**实现由用户本人写**）
+      - 语义由用户本人定：**非数值列不参与统计，掩码里恒 `False`**（见决策 32）
+      - 三轮修掉的 4 个 bug：`threshold` 范围校验放错函数、IQR 上界符号、
+        `is_series` / `is_ld_array` 判在类型转换之后（永远为 False）、文本列上算分位数直接崩
+      - 关键教训：**限制掩码 ≠ 限制统计量** —— 只把 `mask[numeric_cols] = ...`
+        收窄是不够的，`quantile()` / `mean()` / `std()` 也要一起收窄（见坑 8 / 个人易错点 8）
+      - 返回形状与输入同形；Series 进 Series 出（列名保留）、一维数组进一维布尔数组出
+      - **S 档函数卡片已写**：`docs/algorithms/detect_outliers.md`
+        （含"为什么不返回 `Result`"、非数值列恒 `False` 的两条备选路、`ddof` 口径不一致等）
+      - 测试：`tests/test_data.py` 该函数共 **9 条**
+- [x] `data/clean.py` 的两处收尾（**Codex 代写，用户授权**）
+      - `impute_missing` 的 mode 分支改为**返回新表**（原先就地改调用方的表，与另外四支不一致）
+        —— 最后一条 `xfail` 随之转正，**`xfail` 清零**
+      - `detect_outliers` 补**入参类型校验**（§4.7 要求非法类型抛 `TypeError`）：
+        接受 `DataFrame` / `Series` / `list` / `tuple` / `ndarray`，`dict` 不再接受（决策 33）
+- [x] `examples/01_clean_and_describe.py`：`load_table` / `save_table` / `clean_missing` /
+      `impute_missing` / `detect_outliers` / `winsorize` 六个函数的最小用法，实测可直接跑通
+- [x] `data/transform.py` 的四个函数（**由用户本人实现**）：`normalize` / `standardize`（L0 第 6、7 项）、
+      `log_transform` / `one_hot_encode`（原属 L1，顺手写了）
+      - `normalize`：三种 method（`minmax` / `vector` / `max`）都**按列**；`feature_range` 校验下界 < 上界；
+        常量列压到下界而不出 nan（决策 34）
+      - `standardize`：按列，`ddof` 真的传下去 —— 测试用解析关系钉住
+        （`ddof=0` → std 恰为 1；`ddof=1` → `sqrt((n-1)/n)` = 0.866）
+      - `log_transform`：`offset=None` 时自动取 `1 - min(x)`，保证 `x + offset >= 1`
+      - `one_hot_encode`：自动识别的 dtype 集合已显式补上 `'str'` / `'string'`（见坑 9）
+      - Codex 清掉 5 条 ruff（RET503 / F541 / RET504 / RET505 / SIM108），并把 `feature_range`
+        的两条校验提到 `np.asarray` **之前**、修掉说反的报错文案（条件是"下界必须小于上界"）
+      - 测试：**新写 18 条**，其中两条是把原先挂着的 `skip` 转为实跑 —— 见 `tests/test_data.py` 的 transform 段
+- [x] **`transform.py` 的 4 个口径已收口**（2026-10-02，Codex 代修，用户授权"报错顺手修掉"）：
+      - 输入白名单统一成模块级 `_NUMERIC_TYPES`，**`DataFrame` 补进去**并移到 `np.asarray` 之前
+        （此前 `DataFrame` 不在白名单 → `standardize(df)` / `log_transform(df)` 直接 `TypeError`，
+        函数体里所有 `is_df` 分支都是**死代码**）
+      - 三个函数都保持"DataFrame 进 DataFrame 出"（列名 + 索引原样带回），Series 进 Series 出
+      - `normalize` 的三个 method 分支原来**互相覆盖**（`minmax` / `vector` 算完的结果被末尾
+        无条件的 `x / max` 冲掉，三种 method 实际都只走 max），改成 `if / elif / else`
+      - `one_hot_encode` 不再拿 `data.columns` 重包一层（哑变量列名对不上 → 编码列整列丢失）
+      - `log_transform` 的 `offset` 守卫**写反了**（`offset > 0` 就抛错，恰好拒掉唯一合法用例），
+        改成校验真正的定义域前提 `min(x) + offset > 0`（见决策 35）
+      - docstring 按 §4.7 补齐 `Parameters` / `Returns` / `Raises`（Codex 代写，与 `io.py` 同一套 numpydoc 格式）
+      - 口径定稿后 ruff 4 条 RET505 一并清掉 → `All checks passed`；pyright **2 errors → 0**
+- [x] `stats/descriptive.py` 的 `describe`（L0 第 8 项，**由用户本人实现**，Codex 审查 + 代修）
+      - **一个静默 bug（最危险的那种）**：`df_num.describe().T` 把表转反了（行 = 变量、列 = 指标），
+        而 docstring 与 `test_describe_reports_expected_keys` 都要求"行 = 指标、列 = 变量"。
+        转置后 `.loc[指标名] = <按变量索引的 Series>` 与列名**零交集**，pandas 不报错，
+        直接把这四行（`missing` / `missing_ratio` / `skewness` / `kurtosis`）**整行填成 NaN**。
+        去掉 `.T` 一处即修好三件事：方向对了、NaN 没了、`weights` 分支不再报
+        `cannot set a row with mismatched columns`（见易错点 11、决策 36）
+      - `median` 行补上（pandas 的 `describe()` 只有 `50%`，而测试契约定的是 `median`）
+      - 入参放宽到 `list` / `tuple` / `ndarray`（兄弟函数都收，`00_quickstart.py` 传的就是 ndarray）
+      - `weights` 校验补齐：长度、非一维、NaN/inf、负值、和为 0 都抛带原因的错误
+        （原先和为 0 时裸抛 `ZeroDivisionError`）
+      - `zscore`：修 RET505，docstring 补 `Parameters` / `Returns` / `Raises`；
+        `coefficient_of_variation`：均值为 0 由 `TypeError` 改为 `ValueError`（那是取值问题不是类型问题）、
+        空数组提前报错（原先静默返回 nan + RuntimeWarning）、改掉"异变系数"错别字；分母改用 `|mean|`（**用户本人定**，见决策 38）
+      - pyright 的 `DataFrame | Series` 重载问题按坑 8 用 `cast` 收窄；ruff 7 条清到 0
+      - 测试：`test_stats.py` 去掉**模块级** `pytestmark`（它把 6 条测试**全部**跳过了 ——
+        决策 26 说的就是这个，实现写完了却零覆盖），改成逐条 skip 未实现的 5 条，
+        并新写 20 条 describe / zscore / 变异系数用例
+- [x] `examples/01_clean_and_describe.py`：填掉末尾的 `TODO(L0)`，加一段 `describe` 输出
+- [x] `stats/inference.py` 的 `correlation_matrix`（L0 第 9 项，**由用户本人实现**，Codex 审查 + 代修）
+      - **硬 bug**：`if numeric_cols == 0:` 拿 `Index` 和标量比，得到的是布尔**数组** ——
+        0 列时静默不报错、1 列时碰巧能跑、**≥2 列直接 `ValueError` 崩**；
+        而"≥2 个数值列"正是最常见的情况，等于整个函数不可用。改成 `len(numeric_cols) == 0`（易错点 13）
+      - pyright 的报错也都不是运行时问题：`data[numeric_cols]` 是坑 8 的 `DataFrame | Series` 重载
+        （`cast` 收窄）；`_, p = stats.pearsonr(...)` 解包会退化成 `object` —— scipy 的返回值是
+        `_make_tuple_bunch` 运行时拼的类、存根里看不到 `pvalue`（见 `docs/04-environment.md` 坑 10）。
+        加了 `_pvalue(result: Any)` 小助手统一取 p 值，**一处都没挂 `# type: ignore`**
+      - `method` 校验提到最前、清掉 3 条 F541 / 1 条 RET505 / I001，ruff 归零
+      - **现在返回**：`correlation_matrix` → 数值系数矩阵（对角线 1.0）；
+        `correlation_pvalues` → 数值 p 值矩阵（**对角线 NaN**）；
+        `correlation_table` → 星标字符串表（**对角线 `1.000` 不带星**）。
+      - **返回契约冲突（已解决）**：上一版返回的是**带星标的字符串表**（`1.000***`），
+        而 docstring 契约与 L0 用例都要求**数值矩阵**（对角 = 1.0）；按方案 A 拆成三个函数（见下）
+- [x] `correlation_matrix` 的**返回契约**按**方案 A** 落地（2026-10-03，用户拍板）：
+      `correlation_matrix` 只返回**数值**矩阵；星标表拆成 `correlation_table`、p 值拆成
+      `correlation_pvalues`（三者共用 `_check_corr_args` 守卫与**成对删缺失**口径，见决策 41）。
+      顺带修掉两处：**对角线不再带 `***`**（p 值矩阵的对角线是 NaN、"自己和自己"没有显著性）；
+      **p 值与 r 用同一批观测**（都成对删缺失、都尊重 `min_periods`），不再各算各的样本量。
+      p 值只算上三角再镜像，省一半重复计算。测试 **+8 条**（含用解析式 `t = r·sqrt((n-2)/(1-r²))` 对照）
+- [x] `stats/inference.py` 的 `confidence_interval` / `t_test`（**L1 提前落地，实现由用户本人写**，Codex 审查 + 代修）
+      - **用户问的「307/308 两行报错」不是真错**：那两行是 `float(res.statistic)` / `float(res.pvalue)`，
+        报错来自 scipy 的 `TtestResult` —— 它和 `PearsonRResult` 一样是 `_make_tuple_bunch` **运行时**拼的类，
+        存根里没有这两个字段。探针实测 `TtestResult(statistic=3.873, pvalue=0.0305)`，运行时取值完全正常。
+        按决策 40 的路子补了一个 `_statistic(result: Any) -> float` 助手（与 `_pvalue` 成对），
+        **一行 `# type: ignore` 都没挂**。详见 `docs/04-environment.md` 坑 10
+      - **`confidence_interval` 有真 bug（已修）**：原来返回 `(float(min(0.0, lower)), float(max(upper, 1.0)))` ——
+        `min` / `max` 的**参数写反**（下界被钉死成 `0.0`），而且**无条件**把所有 method 的区间夹到 `[0, 1]`。
+        实测 `confidence_interval(rng.normal(170, 8, 50), method="t")` 的下界是 `0.0`（正确是 `171.0 ± 2.1`）；
+        `confidence=1.5` 更是被夹成 `(0.0, nan)` 而不报错。现在**只有 `proportion` 夹**（决策 42），
+        `normal` / `t` 直接返回 `mean ± z|t·se`；`method` 非法改抛 `ValueError`（§4.7）、
+        `confidence` 按 `(0, 1)` **开区间**校验、样本量 < 2 抛 `ValueError`
+      - `confidence_interval` 的入参放宽到 `list` / `tuple` / `ndarray` / `Series` / `DataFrame`：
+        docstring 的 Examples 传 list、L0 用例传 ndarray，原来**两条都直接 `TypeError`**
+      - `t_test`：`_clean_data` 改用 `isinstance(data, pd.DataFrame)` 收窄（坑 8 的 `cast`）、`alpha` 开区间校验、
+        `df` 按 Welch–Satterthwaite / pooled / paired 分别给，docstring 补齐 `Parameters` / `Returns` / `Raises` / `Notes`（§4.7）
+      - 测试 `tests/test_stats.py`：**+10 条（36 → 46）**，含把原先挂着 skip 的 `test_confidence_interval_matches_scipy` 转正；
+        对照一律用解析式（z 公式、Welch `df` 公式、`t = (mean − value)/(s/√n)`），不拿实现对自己
+      - ⚠️ **`t_test` 还有 3 个口径待用户拍板**（Codex 未改，见「下一步」第 6 条）
+- [x] **`core/validate.py` 的 `as_array`**（统一入口，2026-10-03 落地）
+      - 用户提出"每个函数都抄一遍入口/校验/交换太麻烦"。结论：**入口能统一，出口不能一刀切** ——
+        还原要求"输出与输入同形"，而 `describe` / `correlation_*` / `confidence_interval` / `t_test`
+        的输出形状天生和输入不同，硬套只会重演易错点 14。
+      - 契约：`as_array(x, *, numeric_only=True, dtype=float, ndim=None) -> (arr, kind)`，
+        `kind` 是 `"frame"` / `"series"` / `"array"`（**只报告原类型，还原由调用方手写**，用户拍的板）。
+      - 覆盖掉重复：原先 `select_dtypes` / `isinstance(..., pd.DataFrame|Series)` 散在 **5 个文件 31 处**；
+        现在 `normalize` / `standardize` / `log_transform` / `zscore` / `confidence_interval` / `t_test`
+        各只剩 1 行入口。`data/transform.py` 的 `_NUMERIC_TYPES` 白名单连同 3 份副本一起删掉。
+      - 两条硬规矩：**默认绝不摊平**（要摊平显式 `ndim=1`）；**不删缺失值**（删缺失是各函数的语义，
+        见决策 45 与易错点 15）。`numeric_only` 按"输出是否与输入同形"选，不按喜好选（决策 44）。
+      - `check_array`（L1，未实现）实现时直接复用 `as_array`，一份实现两张脸
+- [x] `stats/bootstrap.py` 的 `bootstrap_ci`（L0 第 10 项，**S 档**，实现由用户本人写，Codex 审查 + 代修）
+      - 移植正确性已用**解析解**钉住：大样本正态下百分位区间半宽 ≈ `2 × 1.96 × se`（容差 10%）
+      - **Codex 代修的三处**：
+        ① `random_state=None` 时原来另开了 `np.random.default_rng()`，**绕过了 `get_rng`** ——
+           与决策 24 冲突（`set_seed` 后仍然不可复现）。改成无条件的 `get_rng(random_state)`；
+        ② `statistic_name` 写成 `hasattr(statistic, "__name__")`，而 lambda 的 `__name__` 恒为 `"<lambda>"`，
+           导致 `else` 分支是**死代码**、自定义统计量拿不到 `"custom"`（见易错点 17）；
+        ③ ruff 两条（I001 导入块、F541 空 f-string），并把 docstring 的 `Parameters` / `Returns` / `Raises` 补齐（§4.7）
+      - **测试是重点**：用户实现写完后，`tests/test_stats.py` 里等它的 3 条**仍然挂着 `skip`**，
+        全量照样显示"全绿" —— 正是易错点 9 的复发（已把该条 `复发` 记到 1）。
+        已摘掉 3 条 skip，并新增 6 条：`estimate` 等于原样本统计量、`confidence` 单调性、
+        五种容器一致、自定义 lambda 走回退分支、**不给种子时跟随 `set_seed`**、非法 `method` 抛错。
+      - **S 档函数卡片已写**：`docs/algorithms/bootstrap_ci.md`（第 2 张），
+        记了"极差统计量的区间上界必然塌到 `estimate`"这个非平凡性质，以及 5 个待拍板口径
+      - 测试：`tests/test_stats.py` 的 bootstrap 段共 **9 条**
+- [x] **工程收尾（本轮）**：`tests/test_solve.py` 的模块级 `pytestmark = pytest.mark.skip(...)`
+      拆成 **9 条逐条** `@pytest.mark.skip(reason=_NOT_IMPLEMENTED)` —— 模块级 skip 会把整个文件吞掉，
+      正是易错点 9 的根源（决策 26）。收集数不变（177）、跳过数不变（34），只是粒度变细。
+- [x] `solve/simulate.py` 的 `monte_carlo`（**L0 第 11 项，S 档，算法由用户本人写**，2026-10-04）
+      - 核心逻辑：向量化采样 → 一次仿真 → 8 个指标；`get_rng` 无条件调用（决策 46 已内化）
+      - 用户第二轮改了三处（见决策 48）：批量大小改由实现传 `sampler(rng, size=n)`；
+        结果含 NaN 判失败；`np.std(data, ddof=0)` 写明
+      - **Codex 只碰工程侧，算法一行未动**：
+        ① ruff 三条（I001 合并同源 import、F541 空 f-string ×2）
+        ② docstring：补 `Parameters`（原文漏 `random_state` / `**kwargs`）与 `Raises`；按新契约改写
+           `sampler` 说明（必须能接住 `size`，且 `**kwargs` 里别再传 `size`）；`Notes` 记 NaN 口径；
+           **修掉跑不通的 Examples**（原版 `lambda rng, **k: rng.normal(0, 1)` 返回标量，实测 `success=False`）
+        ③ 按 §4.7 收严 `n` 校验：`np.int64` 不再被拒、`n=True` 改抛 `TypeError`、浮点 `n` 归 `TypeError`、
+           `n<=0` 归 `ValueError`
+        ④ 格式与文案：`success= True` → `success=True`；失败文案"重采样" → "模拟"（从 `bootstrap_ci` 抄来没改）
+        ⑤ **入口统一 `dtype=float`** —— 修掉一个真 bug：布尔结果（"事件是否发生"，MC 最常见的用法）
+           会让 `np.std` 在 numpy 2 里抛 `boolean subtract ... is not supported`，整个函数判失败；
+           字符串结果也从"ufunc isnan 不支持"变成可读的 `could not convert string to float`
+      - **测试：10 条**（`tests/test_solve.py`）—— 返回长度与 8 个 key、`simulator` 只被调用一次（向量化的可执行版本）、
+        同种子可复现、省略种子时跟随 `set_seed`、E[X²]=1（n=2e5）、docstring Example 真能跑、`np.int64` 的 n、
+        布尔结果按 0/1 统计、NaN 结果判失败、5 个非法入参
+      - 行为探针实测：`simulator` 调用次数 = **1**（真向量化）；20/20 次区间覆盖 0
+- [x] `solve/simulate.py` 的 `monte_carlo_probability`（**L1，S 档，算法由用户本人写**，2026-10-05）
+      - 核心：向量化 `event(batch) -> bool 数组` → `p = mean(data)` → **Wilson score 区间**并夹到 `[0, 1]`
+        （比例量纲，沿用决策 42 的口径——同类问题没重犯）
+      - 用户第二轮（2026-10-05）按 6 条待办改掉 5 条：Wilson 替 Wald、`callable` 入口校验、
+        `confidence` 记进 `params`、`float()` 统一 ci 类型、小概率不再判失败（改成 message 里的警告）——见决策 50
+      - **Codex 第三轮只碰工程侧**：① `z_score^2` → `z_score**2` —— **真 bug**：`^` 是异或，
+        numpy 浮点直接抛 `TypeError`，被 `except` 吞成 `success=False`，6 条测试全红才暴露（易错点 21）；
+        ② message 无警告时的尾逗号；③ `{"confidence":confidence}` 的空格；④ docstring 的 "Wald" → "Wilson"；
+        ⑤ 新增 1 条对照测试：区间必须等于 `statsmodels.proportion_confint(method="wilson")`
+      - 行为探针实测：p≈0.5 正确（0.49991 @ n=2e5）、`confidence` 变大区间变宽、
+        同种子可复现、省略种子跟随 `set_seed`、`np.int64` 的 n 可收、`confidence=1.5` 抛 `ValueError`
+      - **Codex 只碰工程侧，算法一行未动**：
+        ① ruff 六条（SIM300 Yoda、W291 ×2、W293 ×2、F541）
+        ② docstring：补 `Parameters`（原文只有 Returns/Notes/Examples）与 `Raises`，
+           **修掉跑不通的 Examples**（原 `lambda rng, **k: rng.normal(0, 1)` 返回标量，实测 `success=False`），
+           并把"Wald 区间 + 夹到 [0,1]"与"`p <= 1e-3` 判失败"两条**现状**如实写进 Returns / Notes
+        ③ 格式：`metrics` 字典缩进、`{"n":n, ...}` 空格、行尾空白
+        ④ 文案：NaN 提示里的 "simulator" 改成 "event"（从 `monte_carlo` 抄来没改）
+      - **测试：摘掉 2 条 skip**（`test_monte_carlo_probability_of_standard_normal`、`test_monte_carlo_is_reproducible`
+        —— 实现写完还挂着 skip，正是易错点 9）并新增 5 条，`solve` 段共 24 条
+- [x] `solve/simulate.py` 的 `monte_carlo_integral`（**L1，S 档，算法由用户本人写**，2026-10-05）
+      - 核心：`bounds` → 自己造 `(n, d)` 均匀样本 → 逐点求值 → `mean(func(X) × 体积)`；
+        自造 `sampler` / `simulator` 再复用 `monte_carlo` —— "造批 → 一次算 → 汇总"这套骨架的第二次复用
+      - **Codex 只改了一处真 bug（决策 31，纯 bug）**：体积写成 `wights = lows - highs`（名字打错 + 减反）。
+        奇数维体积为负：1D `x²` 于 `[0,1]` 实测 **-0.3324**（应 +1/3）、3D `x` 得 **-0.5005**（应 +1/2）；
+        而 **2D `x·y` 得 +0.2499 "看着对"** —— 两个负号相乘抵消，把 bug 藏住了。
+        改成 `widths = highs - lows` 后复测 **0.3324 / 0.5005 / 1.9971（`[0,2]`）** 全部正确
+      - **Codex 只碰工程侧**：① docstring 补 `func` / `n` / `random_state` 三节 `Parameters` 与 `Raises`；
+        ② `Returns` 写清"**`metrics["mean"]` 才是积分估计值**，`data` 是 `n` 个样本各自的贡献"；
+        ③ **修掉跑不通的 Examples**（原版断言 `abs(r.data - 1 / 3) < 0.01` —— `data` 是数组，
+        `bool(数组)` 会抛 `ValueError: truth value ... is ambiguous`），改成断言 `metrics["mean"]`；
+        ④ 格式：`bounds_arr[:,0]` → `[:, 0]`、函数间空行（`def random_walk` 前只留了 1 个空行）
+      - **测试：新增 4 条 + 摘掉 1 条 skip**（`solve` 段共 30 条）—— 1D 收敛到 1/3（n=2e5）、
+        **3D 抓体积符号**（奇数维）、**`[0,2]` 抓宽度**（偶数维藏不住）、2D + `name`/`dimension`/`bounds` 三个 params、
+        `(1, 0)` 抛 `ValueError`。三条"抓符号"用例就是照着上面那个"2D 掩盖效应"设计的
+      - ✅ **3 条待办已由用户第二轮办结**（同日）：`message` 改成 `if result.success:` / `else:` 两支（失败语义不再被覆盖）；
+        入口补 `isinstance(bounds, (list, tuple))` + `ndim == 2 and shape[1] == 2` 两道（`[0, 1]` 从裸 `IndexError` 变成可读 `ValueError`）；
+        `n` 注解放宽为 `int | np.integer`。⏳ 尚有 2 条新口径（`bounds` 收不收 ndarray、`if`/`else` 三行重复）见"下一步"
+- [x] `solve/simulate.py` 的 `random_walk`（**L1，S 档，算法由用户本人写**，2026-10-05）
+      - 核心：`step_sampler(rng, size=(n_paths, n_steps))` 一次抽完整批增量 → `np.cumsum(..., axis=1)` →
+        首列填 `start`、其余列 `start + cumsum`。`data` 形状 `(n_paths, n_steps + 1)`
+      - **Codex 改了一处真 bug（决策 31，纯 bug）**：默认采样器写 `rng.integers(0, 2, size=size, dtype=float)`，
+        而 numpy 的 `integers` 不收 `dtype=float`（`TypeError: Unsupported dtype dtype('float64') for integers`）
+        —— **默认路径 100% 失败**（`success=False`、`data=None`），连 docstring 的 Examples 都跑不通。
+        改成 `rng.integers(0, 2, size=size) * 2 - 1`（后面的 `np.asarray(..., dtype=float)` 负责转 float）。
+        实测：`(5, 101)` 形状、`diff` 恒为 ±1、同种子可复现
+      - **Codex 只碰工程侧**：① ruff 两处 W293（只有空格的行）；② docstring 补全（原只有 `step_sampler` 一节，
+        现补齐 `n_steps` / `n_paths` / `start` / `random_state` + `Returns` / `Raises` / `Notes`，
+        并写清 `step_sampler` 收的是**二维** `size=(n_paths, n_steps)`）；③ Examples 增加一条"步长恒为 ±1"的断言
+      - **测试：新增 6 条**（此前 `random_walk` **一条测试都没有**）—— 形状与 `start` 列、默认步长恒 ±1、
+        同种子可复现、自定义高斯采样器（带漂移）、3 类非法入参、docstring Example 真能跑
+      - **用户第二轮（2026-10-05）按 4 条待办改定**：`n_steps` / `n_paths` 拆成 `TypeError`（类型）/ `ValueError`（取值）；
+        加 `steps.shape != (n_paths, n_steps)` 与 NaN 两条校验；默认采样器换成 `rng.choice([-1.0, 1.0], size=size)`；
+        `params` 补 `random_state`；`metrics` 由"抄 params"改成 `mean_terminal` / `std_terminal`（终点位置，`ddof=0`）
+      - **Codex 第二轮又抓到一处真 bug（决策 31）**：用户把 `call_params = {...}` 写进了 `try` 里，而 `except` 分支要引用它 ——
+        **5 种失败输入 5 个全炸** `UnboundLocalError`（本该返回 `success=False` 的 `Result`，变成把异常抛给调用方）。
+        按原意把 `call_params` 移到 `try` 之前（不动任何口径），实测失败路径全部恢复正常；新增一条"必然失败"的回归测试（易错点 26）
+      - **测试：本轮再 +3 → 共 9 条**（新增"失败也必须返回 Result 且带 params"、NaN 判失败、`√t` 扩散）；
+        `start="a"` 那条恢复成 `pytest.raises(TypeError)`（用户恢复了入口校验，见下）
+      - **第三轮（2026-10-05）**：`start` 校验恢复、注解放宽为 `int | np.integer`；最后一条"方阵歧义"用户选**方案 B**，
+        `step_sampler` 契约改为"整数 `size=n_paths * n_steps` + 必须返回一维 + 内部行主序 `reshape`"（决策 55，Codex 代改）
+
+- [x] `solve/simulate.py` 的 `markov_simulate`（**L1，S 档，算法由用户本人写**，2026-10-05）
+      - 核心：`arr[current_states]` 取当前状态那一行 → `cumsum` 得累积分布 → 用 `[0, 1)` 均匀数"落格"
+        （`(cum_probs < r[:, None]).sum(axis=1)`）→ 写进下一列。`data` 形状 `(n_paths, steps + 1)`，值是整数状态编号
+      - **Codex 审查结论：算法本体正确**（探针实测 `(2000, 201)`、状态 ∈ {{0,1}}、200 步后终点频率
+        `[0.657, 0.343]` 对照平稳分布 `[2/3, 1/3]`、同种子可复现）
+      - **Codex 只碰工程侧**：① ruff 8 条全清（`I001` 导入排序 + 5 处 `W293` / 2 处 `W291` 空白）；
+        ② `arr, kind = as_array(...)` 的 `kind` 全程未用 → 改 `arr, _`；
+        ③ docstring 从一行补到完整的 `Parameters` / `Returns` / `Raises` / `Notes` / `Examples`；
+        ④ 文案：`马尔科夫` → `马尔可夫`（3 处）、`initail` → `initial`、半角逗号 → 全角；`paths[:,0]` → `paths[:, 0]`
+      - **测试：新增 9 条**（此前 `markov_simulate` 一条都没有）—— 形状 / 首列 / 状态取值 / 整数 dtype、
+        单位矩阵吸收态自锁、可复现（同种子相同、异种子不同）、终点频率收敛到 `[2/3, 1/3]`、
+        metrics = 终点状态、非法转移矩阵（非方阵 / 行和不为 1）、非法 `steps` / `n_paths`（0 / float / bool）、
+        `np.int64` 可收、docstring Example 真能跑
+      - **第二轮（2026-10-09）**：用户补了 `np.any(arr < 0)` 非负校验 → 待办 ② 办结；
+        Codex 补一条"行和是 1 但含负元素"的回归测试
+      - **第三轮（2026-10-10，用户改定）**：非负校验改带容差 `-1e-12`（⑦ 办结）；
+        `initial` 注解放宽到 `(int, np.integer)`（`np.int64` 已收）；`paths` 的构造与首列赋值**挪进 `try`**（③ 办结，
+        长度不匹配/越界不再裸抛）；`params` 的键 `n_steps` → `steps`（与参数名对齐）、`initial` 存成可 JSON 化的标量/列表；
+        `metrics` 去掉 `std_terminal`、换成 `terminal_distribution`（`{状态: 频率}` dict，⑤ 办结）
+        —— Codex 同步 docstring 与 3 条测试（含"只列出现过的状态"这条口径）
+      - ⏳ **余下 4 条**见"下一步 → markov_simulate 待你拍板"（全是入口口径与少考虑情况，决策 49）
+
+- [x] `solve/simulate.py` 的 `markov_steady_state`（**L1，S 档，算法由用户本人写**，2026-10-09）
+      - 核心：`v` 从均匀分布出发，`v_next = v @ arr` 反复推进（行随机矩阵按**行向量右乘**），
+        直到 `max|v_next - v| < tol` 或耗尽 `max_iter`；`data` 是平稳分布向量，`metrics={"converged", "iterations"}`
+      - **Codex 审查结论：算法本体正确**（探针实测）—— 2 状态 `[2/3, 1/3]`（58 次迭代）、3 状态与 `np.linalg.eig(P.T)`
+        特征值 1 对应的特征向量逐位一致（39 次）、随机 6 状态一致（13 次）、200×200 一致到 `1.9e-12`（6 次、0.10s）、
+        与 `markov_simulate` 的终点频率互验 `[0.6702, 0.3298]` vs `[0.6667, 0.3333]`、`sum(data) = 1.0`
+      - **Codex 只碰工程侧**：① ruff 5 条 `W293` 全清，`mm1_metrics` 前 4 个空行 → 2；
+        ② docstring 补 `max_iter` / `tol` 两个参数（原来 Parameters 里只有 `transition`）、补 `Raises`，
+        写清 `tol` 是**相邻差口径**（实测慢混合链 `tol=1e-10` → 实际误差 `4.6e-9`，被 `1/(1-|λ2|)` 放大）；
+        ③ 修正 Notes 里"周期链会不收敛"的说法（可约链的实情是"平稳分布不唯一、迭代法给离初值最近的那个"）；
+        ④ 失败文案 `失败: ` → `失败：`（与文件内其它函数统一）
+      - **测试：+8 条、摘掉 1 条 skip**（此前该函数只有 1 条挂着的 skip）—— 2 状态 `[2/3, 1/3]` + `converged` / `iterations`、
+        3 状态与特征分解对拍、`data` 是分布（和为 1 / 非负 / `float64`）、慢混合链迭代次数 > 100、
+        `np.int64` 的 `max_iter`、非法转移矩阵、`max_iter=0` / `tol=0`、docstring Example 真能跑
+      - **第二轮（2026-10-09，用户改定）**：补非负校验（① 办结）、`params` 记 `transition`（⑥ 办结）、
+        `success=converged`（选口径 B，④ 办结）、`tol` 拆成 `TypeError` / `ValueError` 且先判 `bool`（② 办结）；
+        Codex 顺手修文案（`max_iter <= 0` 那条写成 "tol 必须是正数"）与 `异常: ` → `异常：`，
+        并补 2 条测试（负元素矩阵、`max_iter=3` 未收敛走 `success=False`）
+      - **第三轮（2026-10-10，用户改定）**：非负校验带容差 `-1e-12`（⑦ 办结）；`max_iter` 类型错改抛 `TypeError`（⑤ 办结）；
+        `tol` 加 `np.isnan` 拦截（③ 办结）；非方阵改抛 `TypeError`
+      - ⏳ **只剩 2 条**（⑧ 未收敛带 `data`、非方阵的 `TypeError`/`ValueError` 与 `markov_simulate` 不一致）见"下一步"（决策 57）
+
+- [x] `solve/simulate.py` 的 `mm1_metrics`（**L1，S 档，算法由用户本人写**，2026-10-09）
+      - 核心：闭式解 `ρ = λ/μ`、`L = ρ/(1-ρ)`、`Lq = ρ²/(1-ρ)`、`W = 1/(μ-λ)`、`Wq = W - 1/μ`；
+        `λ >= μ` 走"系统不稳定"分支返回 `success=False`
+      - **Codex 审查结论：公式全对**（探针实测 3 组参数 `(2,3)` / `(1,4)` / `(0.5,1.0)` 与闭式公式逐位一致，
+        `W = Wq + 1/μ` 恒等式也成立）
+      - **Codex 修了一处边界 bug（决策 31，纯 bug）**：稳定性判断写成 `service_rate < arrival_rate`，
+        而 docstring 与既有测试的口径都是 `λ >= μ` —— 于是 `λ == μ` 掉进 `try`、`rho == 1.0` →
+        `ZeroDivisionError` 被 `except` 吞成 `success=False`（结果碰巧对，message 却是"计算失败：ZeroDivisionError"）。
+        两支的可观测输出完全相同（`success=False` / `metrics={}` / `data=None`），改 `<=` 只换 message，故直接修并加回归测试
+      - **Codex 只碰工程侧**：① ruff 6 条（5 处 `W293` + `F541` f-string 无占位符 + `W292` 文件末尾无换行）；
+        ② 文案：`service_rate` 的报错写成 "tol"、`max_iter` 的也写成 "tol"（同一轮里 3 处参数名抄错）、半角逗号 → 全角；
+        ③ `call_params={...}` → `call_params = {...}`；④ docstring 补 `Raises` + 说明 `data` 与 `metrics` 同值
+      - **测试：+6 条、摘掉 2 条 skip**（此前只有 2 条挂着的 skip）—— 闭式公式逐项对拍（含 `W = Wq + 1/μ`）、
+        `λ == μ` 与 `λ > μ` 都判失败且带"不稳定"文案、入口（0 / 负数 / `bool` / 非数值）、
+        `λ == μ` 不能靠 `ZeroDivisionError` 落到失败分支、docstring Example
+      - **第三轮（2026-10-10，用户改定）**：`arrival_rate` 放开到"非负"（`λ = 0` 空系统合法，① 办结）、
+        两个速率都收 numpy 标量（`np.number`，② 办结）、不稳定分支**保留 `rho`** 并写进 message（④ 办结）、
+        `data=metrics.copy()` 去掉同一个 dict 对象的别名（③ 部分办结：仍是 dict，只是不再别名）
+        —— Codex 同步 docstring 与 4 条测试
+      - ⏳ **只剩 1 条**（`data` 该不该是 dict）见"下一步 → mm1_metrics 待你拍板"（决策 58）
+
+- [ ] 剩余 1 项：`save_figure`（A 档 = 工程，**Codex 直接写**）
 
 ### 验证结果
 
 | 检查 | venv | conda `mcm-toolkit` |
 |---|---|---|
-| `pytest` | **39 passed, 44 skipped** | **39 passed, 44 skipped** |
+| `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 |
+| `ruff check` | All checks passed | **All checks passed**（0 error） |
 | `scripts/doctor.ps1` | 跑通 | — |
 | SALib / pymoo / pyright | 缺失 | 已装 |
 
+- `pyright`（分析目标 = 工作区 `.venv`）：**0 errors, 0 warnings**
+  （修配置之前是 17 errors，全是"无法解析导入 numpy / pandas"，见决策 29 与
+  `docs/04-environment.md` 坑 7）
 - base 亦已复核：numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6（与两套环境一致）
-- skip 的都是等实现的算法行为测试；通过的 39 条 = 20 条公开 API 契约测试
+- **258 条用例：233 passed / 25 skipped / 0 xfail**。收集数按文件：`test_data.py` 52、`test_api_surface.py` 20、
-  （`tests/test_api_surface.py`）+ 11 条 `core` 行为测试（`tests/test_core.py`）
+  `test_core.py` 23、`test_solve.py` 64、`test_viz.py` 8、`test_decision.py` 7、
-  + 8 条 `data` 行为测试（`tests/test_data.py`）
+  `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`
+- 28 条 skip 是等实现的算法（`train_test_split`、`anova`、`fit_distribution`、`knapsack_dp`、
+  `linear_program`、`simulated_annealing` 等）；
+  `monte_carlo_probability` / `monte_carlo_integral` / `markov_steady_state` / `mm1_metrics` 已落地，分别摘掉 2 / 1 / 1 / 2 条 skip；`markov_simulate` 新增的 9 条全部实跑；
+  `TestValidate` 的 4 条仍挂着 —— `check_*` 还是 `NotImplementedError`，但它们实现时应当直接复用 `as_array`
+- **本轮回归（已修）**：`transform.py` 上一版有 3 处真 bug —— 修前 **7 failed / 75 passed**，
+  且 pyright 在同一处报 `reportArgumentType`。**不是静态误报**：pyright CLI 复现 + 测试真红。
+  结论：见到红线先跑 CLI 与 `pytest`，**不许直接挂 `# type: ignore`**（见个人易错点 10）
 - 三个 `.ps1` 通过 PowerShell AST 语法解析
 
 ### ⚠️ 需要注意 / 遗留
@@ -113,8 +428,11 @@
       只差 Python 补丁号（3.13.9 vs 3.13.15）。详见 `docs/04-environment.md` §5。
 - [x] ~~Gitea 远程尚未配置~~ → **已配置并推送完成**，见上面 D 节与决策 19/20。
       note：仓库当前是 **Public**（匿名 `git ls-remote` 可读），要改私有去 Gitea 仓库设置。
-- [ ] L0 完成 **3/12**（`Result`、`get_rng`/`set_seed`、`load_table`/`save_table`），其余按 `docs/03-roadmap.md` 的 L0 → L1 顺序推进；
+- [x] L0 完成 **12/12**（`Result`、`get_rng`/`set_seed`、`load_table`/`save_table`、`clean_missing`、
-      详情见上面 E 节
+      `detect_outliers`、`normalize`、`standardize`、`describe`、`correlation_matrix`、`bootstrap_ci`、
+      `monte_carlo`（用户写，2026-10-04））；另 L1 的 `confidence_interval` / `t_test` /
+      `monte_carlo_probability` / `monte_carlo_integral` 已提前落地；
+      **L0 已全部完成**（`save_figure` 于 2026-10-18 落地），详情见"下一步"第十一轮
 - [ ] 本机 `exec_command` 在沙箱模式下**完全不可用**
       （`helper_unknown_error: setup refresh had errors`），只有提权
       （`require_escalated`）模式可用。沙箱模式只允许写 `D:\MCM&ICM_Toolkit`。
@@ -155,19 +473,442 @@
 | 24 | `get_rng(None)` **复用同一个模块级生成器**（会推进），不每次新建 | **用户本人提出**，取代 Codex 原来"每次新建 `default_rng(全局种子)`"的写法——那样两个都省略 `random_state` 的函数会抽到完全相同的数。共享单例既保证重跑一致，又让流自然推进 |
 | 25 | `src/` 下的实现默认由**用户本人**写，Codex 只改 `tests/` 与 `docs/` | 目标是"一边学一边自己写"。曾出现 Codex 直接落盘 `random.py`、与用户编辑器缓冲区冲突导致保存失败。需要代写时用户会明说 |
 | 26 | 未实现的算法用**逐条** `@pytest.mark.skip`，禁用模块级 `pytestmark` | 模块级 skip 会把同文件里**已经写好**的函数一起跳过。本次 `test_data.py` 就这样让 `load_table` 零覆盖，直到有人手动数才被发现 |
+| 30 | 已知待修的契约用 `@pytest.mark.xfail(strict=False)`，不用 skip | skip 会让"契约还没写"和"写了但实现有问题"混在一起，5 条 skip 曾把 `clean.py` 的 bug 全藏住。xfail 照样进报告，修好后自动变 XPASS，是"修好了"的信号，而且 XPASS 不失败，不会卡住提交 |
+| 29 | 静态分析器钉死到工作区 `.venv`，并把 base 的 site-packages 用 `.pth` 链进去 | pyright / Pylance **不认** `pyvenv.cfg` 的 `include-system-site-packages`，`.venv` 自己只有 `pip`；不钉的话它们会去 PATH 上找 python，本机 PATH 上那个是 Codex 运行时的 3.14 shim，没有科学栈，于是报"无法解析导入"。`.pth` 是唯一被 pyright 认的转发手段 |
+| 28 | 不启用 ruff 的 preview 规则集 | `E302`（函数间要 2 个空行）在 ruff 0.16 里是 preview 规则，`select = ["E"]` 默认**不包含**它——所以少一个空行 ruff 照样报 "All checks passed"。行数空行得自己盯，别指望 lint |
+| 34 | 常量列（`max == min`）不定区间也不崩：`normalize` 压到 `feature_range` 下界，`standardize` 给 0 | 除零必须有个确定的答案，不能出 nan / inf。给 0 与 `sklearn` 的 `MinMaxScaler` / `StandardScaler` 一致（sklearn 把常量列的 scale 设为 1，结果就是 0），换库不换结论。行为已由 `test_normalize_constant_column_stays_finite` 与 `test_standardize_constant_column_stays_finite` 钉住 |
+| 33 | `detect_outliers` 只接受 `DataFrame` / `Series` / `list` / `tuple` / `ndarray`，`dict` 一律 `TypeError` | §4.7 要求非法类型抛 `TypeError` 而非静默兜底。`dict` 以前能"碰巧"被 `pd.DataFrame()` 转成表，但那不是文档承诺的形状，静默接受会让调用方以为传什么都行；`tuple` 则补进文档与 `is_ld_array`，与 `list` 同等对待 |
+| 32 | `detect_outliers` 对非数值列恒返回 `False`（既不跳过也不报错） | **用户本人在两条路里选的**。跳过会让 docstring 里"与原数据同形"变成谎话（形状对不上，没法按位置对回原表）；报错则让一张带 `city` 列的真题表直接不可用。`False` 的读法是"这一列没有离群点"，对文本列是最不坏的解释，也让整表能一次跑完 |
+| 31 | Codex 可**直接改** `src/` 的范围：纯 bug（不改接口与语义）、格式、死代码 | 决策 25 说实现归用户，但"能跑"是底线：`winsorize(pd.Series)` 因 `select_dtypes` 在 `Series` 上不存在而直接崩、测试变红，这种必须当场修。凡是要**选一个语义**的（文本列返回什么、mode 要不要就地改）一律留给用户本人，Codex 只把选项和影响列清楚 |
 | 27 | base 里的 zstandard 残骸目录**改名禁用**，不删除、不重装 | 删掉不可逆；`pip install zstandard` 会给 base 塞一个 conda 记录里根本没有的包，下次 `conda update --all` 又要重新判断。改名后 `import` 变回正常 `ModuleNotFoundError`，pandas 自动跳过 |
+| 35 | `log_transform` 的显式 `offset` 按**定义域前提**校验：`min(x) + offset > 0` 才放行 |
+| 36 | `describe` 的返回表**不转置**：行 = 指标、列 = 变量 |
+| 37 | 非数值列的处置**按输出契约分**，不按包分：`describe` / `zscore` 直接丢掉；`detect_outliers` 保留列、掩码恒 `False` |
+两族函数的产出物不一样：`describe` / `zscore` 吐的是**数值结果表**，文本列塞不进去，丢掉才能得到一张干净、可直接贴论文的表；`detect_outliers` 吐的是**与原表同形的掩码**，必须能按位置对回原表，丢列就废了。"不统一"不是前后矛盾，是契约不同。用户 2026-10-03 拍板：丢掉更好 |
+| 38 | `coefficient_of_variation` 用 `σ / |mean|`（**用户本人改的**） |
+均值为负时 `σ/μ` 会给出负值，容易被读成"波动更小"，其实只是符号跟着均值走。取绝对值后 CV 恒非负。可比性仍只在均值远离 0 的比率尺度数据上成立（已写进 docstring 的 Notes） |
+| 39 | 工作约定：**语义 / 非法输入口径由用户拍板，Codex 只列选项与影响、不代选**；**ruff、`STATUS.md`、`CHANGELOG.md`、`tests/`、docstring 这类与算法无关的工程事务，Codex 顺手补掉** |
+| 40 | scipy 的检验结果统一走 `_pvalue(result: Any) -> float` 助手取 p 值，不逐处挂 `# type: ignore` |
+| 41 | `correlation_matrix` **只返回数值矩阵**；星标表拆 `correlation_table`、p 值拆 `correlation_pvalues` |
+用户 2026-10-03 选方案 A。数值矩阵能做的事（挑高相关对、喂聚类 / PCA、画热力图）字符串表都做不了，而反过来随时能格式化 —— 展示需求属于**输出端**，不该侵占返回值；一旦返回字符串，数值信息不可逆地丢失。三个函数共用 `_check_corr_args` 守卫与成对删缺失口径，`correlation_table` 在**最外层**调另外两个（计算型当主、展示型当辅）。见易错点 14 |
+| 42 | `confidence_interval` **只有 `proportion` 夹到 `[0, 1]`**；`normal` / `t` 是**均值**区间，一律不夹 |
+原码把三种 method 的区间**无条件**夹进 `[0, 1]`，且 `min` / `max` 参数写反（见易错点 15），实测把身高均值区间下界压成 `0.0`。均值区间的量纲本来就不在 `[0, 1]` 里；只有比例 `p ± z·√(p(1−p)/n)` 的边界才有意义。**Codex 代改、待用户确认** —— 若原意是"什么区间都夹"，改回 `_clip` 一行即可 |
+| 43 | scipy 检验结果的**统计量**也走 `_statistic(result: Any) -> float` 助手，与决策 40 的 `_pvalue` 成对 |
+`TtestResult` 与 `PearsonRResult` 同源（`_make_tuple_bunch` 运行时拼类），存根里 `.statistic` / `.pvalue` 都没有。用户报的「307 / 308 行报错」就是这两处，**不是真 bug**（探针实测取值正常）。见 `docs/04-environment.md` 坑 10 |
+| 44 | 所有收数值的函数**统一从 `core.validate.as_array` 进**；**还原不代做**，调用方按返回的 `kind` 自己手写 |
+用户 2026-10-03 提"每个函数都抄一遍入口/校验/交换太麻烦"。能统一的只有**入口**：出口要求"输出与输入同形"，而 `describe` / `correlation_*` / `confidence_interval` / `t_test` 天生不同形，硬套会重演易错点 14。用户明确"不要三个函数""转换回去自己手打"，所以 `as_array` 只返回 `(arr, kind)`，`ArraySpec` / `restore` 都不做。`numeric_only` 默认 `True`（用户拍的板），但**按输出契约选**：同形函数必须显式 `False` |
+| 45 | `as_array` **不删缺失值**；容器类型/内容转换失败**统一抛 `TypeError`** |
+删缺失是**语义**（`df.corr` 成对删、`describe` 整列统计、`paired=True` 的 t 检验必须成对删），在入口层删掉就把行对应关系永久丢了 —— 这正是 `t_test` 待拍板的口径之一。错误口径统一为 `TypeError` 是**Codex 代选、待用户确认**：`normalize(含文本列的表)` 原先由 numpy 抛 `ValueError`，现在是 `TypeError`（内容转不成 float）；`describe` 的 `weights` 同类情况目前仍抛 `ValueError`（决策 39 说不统一就列出来） |
+| 46 | `bootstrap_ci` 的随机数**无条件走 `core.get_rng`**；`statistic_name` 用 `getattr(f, "__name__", None)` 再判 `"<lambda>"` |
+原码 `random_state=None` 时另开 `np.random.default_rng()`，等于绕开决策 24（`set_seed` 对它无效，区间不可复现）。**Codex 代改**：`get_rng(None)` 本来就是设计好的"复用模块级生成器且推进"，直接传下去即可。`statistic_name` 的 `else "custom"` 是死代码 —— lambda 也有 `__name__`（值恒为 `"<lambda>"`），实测拿不到 `"custom"`，见易错点 17 |
+`PearsonRResult` / `SignificanceResult` 是 `_make_tuple_bunch` 在**运行时**拼出来的类，存根里没有 `pvalue` 字段：解包会退化成 `object`、属性访问会报"未知"。运行时完全正常（实测三个函数返回的都是 `np.float64`）。收成 `Any` 是**一处**收窄，调用点仍然干净；`# type: ignore` 要挂在每一处，且会连带关掉该行后面的检查。见 `docs/04-environment.md` 坑 10 |
+用户 2026-10-03 明确：没考虑到的非法情况"告诉我我自己改"——因为那是设计决策，得由写实现的人形成判断；而 lint / 进度板 / 测试这类机械活再由用户动手只是浪费。这条与决策 25 / 31 配套：25 定"谁写 src"，31 定"Codex 可改的 bug 范围"，39 定"非算法事务的默认归口" |
+docstring 与 `test_describe_reports_expected_keys` 早就写死了这个方向，实现里多做的 `.T` 是净负担 —— 且不是"风格不同"那么轻：转置后 `.loc[指标名] = <按变量索引的 Series>` 与列名零交集，pandas **不报错**、把四行整行填成 NaN。方向约定以"能按列名对齐"为准，见易错点 11 |
+原码写的是 `if offset > 0: raise`，把唯一合法的用例（正 offset 正好抬定义域）全拒了，报错文案却是"offset 必须大于 0"，自相矛盾。改成校验真正的前提：`log` 要求自变量取正。`offset=0` 对全正数据合法（`offset=None` 的自动分支本来就取 0）。**Codex 代选、待用户确认** —— 若原意是"只收正 offset"，改回即可 |
+| 47 | **算法一律由用户本人写；工程由 Codex 写**（用户 2026-10-03 明确） |
+用户原话："记住算法的东西一定要我来写，以后就算我说让你来写你也不要帮我写，工程我觉得我还可以，你写我看吧"。
+这条比决策 25 更硬：25 说"默认归用户"，47 说"**即便用户改口也不代写**"——目的是保住"一边学一边自己写"的学习路径。
+工程侧（入口/校验、`tests/`、lint、文档、卡片、`.gitignore`）反过来由 Codex 直接落盘，用户只读；
+分地盘按**文件**划，不按函数划。决策 39 的"语义由用户拍板"继续有效。
 
+| 48 | `monte_carlo` 的四个口径由**用户拍板**：实现传 `size=n`；结果含 NaN 判失败；`std` 用 `ddof=0`；出错仍统一返回 `success=False` |
+用户 2026-10-04 直接改在代码里。① 批量大小由实现传（`sampler(rng, size=n, **kwargs)`）：调用方少写一次，
+代价是**每个 sampler 都必须能接住 `size`**，且 `**kwargs` 里不能再传 `size`（会重复传参）—— 已写进 docstring。
+② 结果里只要出现 NaN 就 `success=False`：MC 的 NaN 多来自除零 / 模型发散，静默统计只会得到一列 nan 指标。
+③ `np.std` 默认 `ddof=0`，现在显式写明（与 `describe` 那条线的 `ddof=1` 不一致，属已知差异）。
+④ 计算期异常仍全部包成 `success=False`（保留 `try/except Exception`）；代价是自己写错代码时没有 traceback。
+配套 Codex 代改：入口 `np.asarray(..., dtype=float)` —— 布尔结果此前会让 `np.std` 抛错（真 bug，已修）。
+**唯一未定**：`ci_low`/`ci_high` 保持"结果的分位数"（现状）还是改成"均值的置信区间"。
+
+| 49 | **这类改动归用户本人**：入口没收紧、少考虑情况、不符合简单原则 —— 用户 2026-10-04 明确"交给我改，不要帮我改" |
+用户原话："以后像这种入口没收紧、少考虑情况、不符合简单原则的情况交给我改，不要帮我改，把这几条经验写入经验文档"。
+这是决策 47 的**收窄**：47 把"入口 / 校验重构"划给了 Codex，49 把它收回 —— 凡是**带判断、取舍、设计成分**的，
+一律由用户写，Codex 只报告 + 列选项（与决策 39 同一逻辑）。判据一句话：**这处改动要不要"想一下才对"** ——
+要，就留给用户；不要（ruff、格式化、docstring 缺节、`tests/`、`STATUS` / `CHANGELOG`、函数卡片）才由 Codex 顺手补。
+本轮实例（本该留给用户，Codex 已代改、用户可回退重写）：`monte_carlo` 的 `n` 按 §4.7 收严；入口 `np.asarray(..., dtype=float)`。
+经验已写入 `docs/dev/personal-pitfalls.md` **第 18 / 19 / 20 条**，并把第 1 条（类型判断只写 `int`）**复发 +1**。
+
+| 50 | `monte_carlo_probability` 的区间由 **Wald 改 Wilson score**；小概率不再判失败（改成 message 警告）；`confidence` 记进 `params` |
+用户 2026-10-05 按"6 条待办"自行改定。Wilson 在 p 贴近 0 / 1 时不会退化成零宽：实测 p=1、n=1000 从 `(1.0, 1.0)`
+变成 `(0.99617, 1.0)`；p=0 从"判失败"变成 `(0.0, 0.00383)`（原 Wald 是 0）。区间口径与
+`statsmodels.proportion_confint(method="wilson")` 对齐，已加成对照测试。
+**遗留**（2026-10-05 第二轮复核，同日**已清**）：~~`event: Callable[..., bool]` 注解与"吃整批、返回数组"不符~~ → 已改 `Callable[..., Any]`；
+警告文案把 p≈1 也说成"小概率事件" —— **用户已于同日改掉**（现在两半都覆盖，见 CHANGELOG 本轮）。
+
+| 51 | `monte_carlo_integral` 的 `data` = **n 个样本各自的贡献**（`func(X_i) × 体积`）；积分估计值看 `metrics["mean"]` |
+用户 2026-10-05 写完实现。Codex 审查只改了一处**纯 bug**（决策 31）：体积 `lows - highs` → `highs - lows` ——
+奇数维体积为负（1D `x²` 于 `[0,1]` 实测 **-0.3324**、3D `x` 得 **-0.5005**），而 **2D 因两个负号相乘"看着对"**
+（+0.2499），把 bug 藏住了；改后实测 0.3324 / 0.5005 / 1.9971 全部正确。docstring 与测试都按上述口径写死。
+**留给用户 3 条**：① `result.message` 无条件覆盖（失败被写成"成功"）；② `bounds` 形状没校验（`[0, 1]` 抛裸 `IndexError`）；
+③ `n: int` 与全模块的 `int | np.integer` 不一致。
+
+| 52 | `monte_carlo_integral` 的入口口径由**用户第二轮**改定：`message` 只在成功分支改写；`bounds` 必须是非空 `list`/`tuple` 且形状 `(d, 2)`；`n` 收 `int \| np.integer` |
+用户 2026-10-05 按 Codex 报的 3 条自行改定。`message` 走 `if result.success:` / `else:`（失败分支保留失败语义并追加追溯信息：
+维度 / 体积 / 模拟次数）—— 修掉"`success=False` + 一句成功文案"的自相矛盾。`bounds` 入口两道校验把
+`[0, 1]` 从 `IndexError: too many indices` 变成带当前形状的可读 `ValueError`。遗留 2 条新口径：
+① `isinstance(bounds, (list, tuple))` 把 `np.array([[0, 1]])` 也拒了，与"尽量传 ndarray"的偏好冲突；
+② `if` / `else` 两支里 `name` / `params["bounds"]` / `params["dimension"]` 各写了一遍（易错点 20）。
+
+| 53 | `random_walk` 的默认步长采样器**不能用 `rng.integers(..., dtype=float)`**（numpy 直接抛 `TypeError`）；`step_sampler` 收到的 `size` 是**二维** `(n_paths, n_steps)` |
+用户 2026-10-05 写完第一版。默认采样器原写 `rng.integers(0, 2, size=size, dtype=float) * 2.0 - 1.0` ——
+`Generator.integers` 不收浮点 dtype（`TypeError: Unsupported dtype dtype('float64') for integers`），
+于是**整个默认路径 100% 失败**，连 docstring 的 Examples 都跑不通；Codex 按决策 31 改成 `rng.integers(0, 2, size=size) * 2 - 1`
+（交给后面的 `np.asarray(..., dtype=float)` 转类型），实测形状 `(5, 101)`、步长恒 ±1、同种子可复现。
+`step_sampler` 的 `size` 是 `(n_paths, n_steps)` 而不是 `monte_carlo` 那样的一个整数 —— 契约已写进 docstring，
+**遗留 4 条待办**见"下一步"（`TypeError`/`ValueError` 分工、`steps` 形状校验、NaN 口径、`params` 缺 `random_state`）。
+
+| 54 | `random_walk` 第二轮口径由**用户**改定：`n_steps`/`n_paths` 类型错抛 `TypeError`、取值错抛 `ValueError`；加形状与 NaN 两条校验；默认步长改 `rng.choice([-1.0, 1.0])`；`params` 补 `random_state`；`metrics` 改 `mean_terminal`/`std_terminal` |
+用户 2026-10-05 自行改定，Codex 只修了一处**纯 bug**：`call_params` 定义在 `try` 内、却被 `except` 引用，
+导致**所有失败路径**抛 `UnboundLocalError`（实测 5/5 失败输入全中）。按原意前移到 `try` 之前，未改任何口径。
+**遗留 3 条**：① `start` 的入口类型校验被删（`start="a"` 从 `TypeError` 变成 `success=False`），是有意还是顺手删的？
+② 签名 `n_steps: int` / `n_paths: int` 与运行期收 `np.int64` 不一致（§4.7；`monte_carlo_integral` 的 `n` 已放宽）；
+③ `n_paths == n_steps` 时，返回转置形状的采样器仍会静默通过（形状校验天生发现不了，见易错点 25）。
+
+| 55 | `step_sampler` 的"方阵歧义"按**方案 B** 解决：`size` 改成整数 `n_paths * n_steps`、必须返回**一维**数组，内部 `reshape(n_paths, n_steps)` |
+形状校验（决策 54）对"方阵"天生失效 —— 转置 `(n_steps, n_paths)` 正好等于目标 `(n_paths, n_steps)`。
+**用户 2026-10-05 拍板选 B**（Codex 代改，用户明确要求）。转置 `(n_steps, n_paths)` 与目标 `(n_paths, n_steps)` 在方阵时形状相同，
+校验从形状上无法区分 —— 根源是**契约本身有歧义**（一个 tuple 尺寸给了两种朝向）。改成整数尺寸 + **要求一维**后，
+二维返回一律判失败，转置问题从根上消失。顺带与 `monte_carlo` 的 `sampler` 契约（决策 48 的 `size=n`）统一：
+实测给 `monte_carlo` 写的采样器可以直接丢给 `random_walk`。**关键点：不要用 `.ravel()` 救场** —— 那会把转置的二维摊平，
+歧义原样回来。**代价（已写进 docstring）**：`step_sampler` 不能再返回二维，步与路径的对应关系是**行主序**。
+探针实测：默认采样器 `(5, 101)` 正常；后四种（转置二维 / 方阵二维 / 长度 +1 / `(N, 1)`）一律判失败。
+
+| 56 | `markov_simulate` 的 `initial` 语义**待用户拍板**（Codex 只报选项，未代改，决策 49） |
+现状用 `isinstance(initial, int)` 区分"标量状态 / 状态数组"，两条分支的口径互相打架：标量分支按**路径数**铺满
+（`np.full(n_paths, initial)`），数组分支却按**状态数**校验长度（`len(initial) != s` 直接报错）——
+于是数组分支只有 `n_paths == s` 时才可能跑通；而 `paths[:, 0] = current_states` 又写在 `try` **外面**，
+长度不匹配时**裸抛** `ValueError`（本该 `success=False`，同易错点 26 一族）。另有三个口子：
+`np.int64(0)` 掉进数组分支、被 `as_array` 拒（与 `steps`/`n_paths` 收 `np.integer` 不一致，易错点 1 复发）；
+`True` 因 `isinstance(True, int)` 为真被当状态 1 **静默放行**；越界状态（如 `initial=5`、`s=2`）只在
+第一轮索引时才炸、被 `except` 吞成 `success=False`。
+**2026-10-09 更新**：② 已办结（用户补了 `np.any(arr < 0)`，含负元素的行随机矩阵现在入口直接报错）。
+**2026-10-10 更新**：③ 办结（`paths` 的构造与首列赋值挪进 `try`，长度不匹配/越界不再裸抛）；
+④ 办结（越界现在被吞成 `success=False`，但仍没在入口拦）；⑤ 办结（`std_terminal` → `terminal_distribution`）；
+② 升级为带容差 `-1e-12`；`params` 的 `n_steps` → `steps`、`initial` 存成可 JSON 化的值。
+**只剩 ①**：`bool` 仍被当状态 1（`np.integer` 已收），以及"数组按状态数 vs 按路径数"两条口径的矛盾（A / B / C）。
+
+| 57 | `markov_steady_state` 的口径：**4 条已办、3 条 + 2 个新口子仍待拍板**（Codex 只报选项，未代改，决策 49） |
+**2026-10-09 用户第二轮办结**：① 补 `np.any(arr < 0)`（含负元素的行随机矩阵现在入口即报错，原先会溢出成 `nan`
+却报 `success=True`）；② `tol` 拆成 `TypeError`（类型 + `bool`）与 `ValueError`（取值）；
+④ **选口径 B**：`converged=False` → `success=False`；⑥ `params` 补 `transition`（`arr.tolist()`，可 JSON 化）。
+**仍待拍板**：③ `tol=np.nan`（`nan <= 0` 为假，穿过校验白跑 §max_iter 次迭代）；
+⑤ `max_iter` 的类型错仍抛 `ValueError`（与决策 54 的"类型错 `TypeError`"不一致）；
+⑦ **两把尺子宽严不一**——非负校验用精确 `arr < 0`，同一个函数里的行和校验却用宽容的 `np.allclose`，
+实测 `[[1.0, -1e-16], [0.5, 0.5]]`（行和都是 1）会被判非法，建议改成 `< -1e-12` 这类容差；
+⑧ 未收敛时 `success=False` 但 `data` 仍是未收敛向量（文件内唯一"失败却带 `data`"的分支）—— 保持还是 `data=None`？
+**2026-10-10 更新**：③（`tol` 拦 NaN）、⑤（`max_iter` 类型错 → `TypeError`）、⑦（非负校验带容差）办结。
+**只剩 2 条**：⑧（上面那条），以及新出现的"非方阵抛 `TypeError`，而 `markov_simulate` 的同一条校验抛 `ValueError`"不一致。
+
+| 58 | `mm1_metrics` 的稳定性分界由 Codex 按**决策 31** 直接修（`<` → `<=`），另有 4 条口径待用户拍板 |
+docstring 与既有测试写的都是 `λ >= μ` 不稳定，代码却写 `service_rate < arrival_rate` —— 于是 `λ == μ`
+掉进 `try`、`rho == 1.0` → `ZeroDivisionError`，被 `except` 吞成 `success=False`
+（碰巧对，但 message 成了"计算失败：ZeroDivisionError - float division by zero"）。两支的可观测输出完全相同
+（`success=False` / `metrics={}` / `data=None`），改 `<=` 只换 message，故直接修 + 加回归测试。
+**待拍板**：① `λ = 0` 现在被 `ValueError` 拒（数学上是合法退化解：空系统 `L = W = 0`）；
+② `np.int64` / `np.float32` 全被 `TypeError` 拒（文件内 `random_walk` 的 `start` 收 `np.number`、
+整数参数收 `np.integer`，§4.7 有共识）；③ `data=metrics` —— **同一个 dict 对象**（`r.data is r.metrics`），
+且成功分支给 dict、失败分支给 `None`，与文件内"`data` 是数组"的习惯不同；
+④ 失败分支的 `metrics={}` 会丢掉 `rho` 等已算出的量（可选保留）。
+**2026-10-10 更新**：① ② ④ 办结（`λ = 0` 放开为合法空系统、两个速率收 `np.number`、失败分支报 `rho`）；
+③ 只办了一半（`data=metrics.copy()` 去掉了同一个 dict 对象的别名，但 `data` 仍是 dict、失败时仍是 `None`）—— 只剩这一条。
+
+| 59 | `models/metrics.py` 开工：6 个指标 + 共享入口 `verify_yt_yp` **由用户写**，Codex 只做工程侧审查（决策 47 的延续） |
+本轮把 `metrics.py` 的 L1 `TODO` 转成实现（`compare_models` 仍 `NotImplementedError`）。六个指标共用一个入口
+`verify_yt_yp`：`as_array(ndim=1)` → 形状不一致 / 长度 0 / 含 `NaN` 一律 `ValueError`（与决策 48 的"NaN 判失败"同口径）。
+Codex 侧（决策 47 授权范围）：补 7 处 docstring（`Parameters` / `Returns` / `Raises`）、统一报错文案为"参数名 + 实际值"、
+清 6 条 `F541` + 3 条 `W293`、补空行；`tests/test_models.py` 两条指标测试转正 + 新增 18 条。
+**用户侧拍板并亲手改**：`r2_score` 的 `ss_tol` 基准从 `np.mean(yp)` 改成 `np.mean(yt)`（真 bug，见决策 60 与易错点 31），
+顺带把无意义的 `ss_tol` 改名 `ss_tot`。Codex 探针实测：修前 0.8803827751196172、修后 0.875 = `sklearn.metrics.r2_score` 一致。
+**另有 4 条口径仍待拍板**：`mape` 遇负 `y_true`（现在返回无意义的负数）、只拦 `NaN` 不拦 `inf`、
+`rmse(1.0, 1.0)` 标量被当 1 个样本、`compare_models` 的键名 `"r2"` 与函数名 `r2_score` 对不上。
+
+| 60 | `smape` 的零除告警按**决策 31** 由 Codex 直接修（`np.where` → `np.divide(..., where=)`），数值结果不变 |
+原式 `np.where(denom == 0, 0.0, 2 * |yt - yp| / denom)` 的**结果是对的**（分母 0 记 0），但 `np.where` 两条分支都会被求值，
+分母为 0 时仍触发 `RuntimeWarning: invalid value encountered in divide`；而 `pyproject.toml` 开了
+`filterwarnings = ["error::RuntimeWarning"]` —— 于是任何"含 0 的 smape"测试都会直接红（探针复现）。
+改成 `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` 可复现。
 ## 下一步
 
-1. **`data/io.py` 待你修两处**（`src/` 归你，Codex 不代写，见决策 25）：
+### ⭐ 当前进度与待办（2026-10-18 第十一轮）
-   - `save_table` 把 `path.parent.mkdir(parents=True, exist_ok=True)` 放在了**后缀校验之前**，
+
-     传个 `.txt` 会先建出一个空目录再抛 `ValueError`。
+**本轮：L0 收官 —— `save_figure` 落地（Codex 写，A 档）。**
-     把校验（后缀 + `isinstance(df, pd.DataFrame)`）挪到 `mkdir` 前面即可。
+
-   - 两个函数都缺 `Raises` 段落（`docs/02-architecture.md` §4.7 要求写全）；
+- `viz/export.py`：实现 `save_figure`。入口先校验 `fig` / `dpi` / `formats` / `bbox_inches` /
-     `load_table` 的返回注解建议从 `Any` 改成 `pd.DataFrame` —— docstring 已经承诺返回 DataFrame，
+  `transparent` / `path`，**全部校验通过后才建目录、写文件**；`formats` 支持大小写归一，
-     注解写 `Any` 等于同一个契约写了两遍（`docs/dev/personal-pitfalls.md` 条目 3，本次已复发一次）。
+  空 / 未知 / 重复格式一律报错；`path` 带图片后缀时自动去后缀（不会写出 `fig1.png.png`）。
-2. 继续 L0，**下一个：`data/clean.py` 的 `clean_missing`**（L0 / A 档，直接能写）。
+- `tests/test_viz.py`：去掉违反决策 26 的模块级 `pytestmark`，改为逐条 skip；
-   同文件的 `detect_outliers` 是 **S 档**，要先按 `docs/dev/function-card-template.md`
+  `test_save_figure_writes_png_and_pdf` 不再依赖未实现的 `plot()`，改用 `plt.subplots()` 构造图。
-   把函数卡片写出来再动手。
+  新增 8 条：后缀剥离、自动建目录、格式归一与顺序、单个字符串 / 空 / 未知 / 重复格式、
-3. 每写完一个函数，在 `examples/` 里加一行最小用法，并更新本文件。
+  校验先于副作用、坏 `dpi` / `bbox_inches` / `transparent` / 非 `Figure`。
-4. L0 跑通后，找一道真题（建议 2025 C）走完整流程，反向沉淀函数。
+- 三连：`pytest` **242 passed / 24 skipped**、`ruff` **0**、`pyright` **0**。
+
+**下一步**
+1. `models/regression.py` 的 `fit_linear` / `fit_polynomial`（A 档）。**开工前先定返回契约**：
+   `Result` 没有 `fit/predict/score`，与 `compare_models` 要求 `Model` 协议的入参对不上，
+   需要定成"`Result.data` 放已拟合模型 + `compare_models` 接受两种入参"之类的桥接方案。
+2. `decision/entropy_weights`（S 档，用户写）；Codex 先补函数卡片 / 测试骨架。
+3. 集中拍板 `STATUS.md` 里挂着的小口径（`t_test` / `as_array` / `bootstrap_ci` / `markov_*` / `mm1` / 死代码）。
+
+### ⭐ 当前进度与待办（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` /
+`r2_score` / `adjusted_r2`）加一个共享入口 `verify_yt_yp`；`compare_models` 仍是 `NotImplementedError`。
+Codex 只碰工程侧：7 处 docstring（补 `Parameters` / `Returns` / `Raises`，把口径写成契约）、报错文案统一成
+"参数名 + 实际值"、清 6 条 `F541` + 3 条 `W293` + 空行、`tests/test_models.py` 5 条 → 23 条（两条转正 + 18 条新增）。
+
+**Codex 找到 1 个真 bug（已由你亲手改定）**：`r2_score` 的 `ss_tot` 用了 `np.mean(yp)`，基准必须是 `np.mean(yt)`。
+探针实测（`y_true=[1,2,3,4,5]`、`y_pred=[1.5,2.5,2.5,4.5,5.5]`）：修前 **0.8803827751196172**、修后 **0.875**，
+与 `sklearn.metrics.r2_score` 完全一致。它会连带污染 `adjusted_r2`。**注意 `r2_score(y, y) == 1` 仍成立** ——
+完美拟合与常量 y 都会掩盖这类错，所以新增的测试特意用"非完美拟合"的数据（见个人易错点 31）。
+
+**另修一处会真炸的工程问题（决策 60）**：`smape` 的 `np.where` 掩码防不住零除，`filterwarnings=error::RuntimeWarning`
+下任何含 0 的测试都会红 → 改 `np.divide(..., where=)`，数值结果不变，并补测试钉住"不许告警"。
+
+三连：`pytest` **224 passed / 26 skipped（250 收集）**、`ruff` **0**、`pyright` **0**。
+
+**接下来（按 roadmap §四，`models` 的完成标志就是 `compare_models`）**
+1. `compare_models`（同文件最后一块；`cv=0` 走"全量拟合后打分"分支，返回按第一列指标排序的 `DataFrame`，
+   依赖 `pd.DataFrame`，顺带定 `metrics` 的键名口径）。
+2. `regression.py` 的 `fit_linear` / `fit_polynomial`（把 `models/base.py` 的 `Model` 协议三件套跑通）。
+3. 然后转 `decision/entropy_weights`（**S 档，你写**，三个坑：方向 / 量纲 / 零值）。
+
+### ✅ 第九轮那 4 条口径（2026-10-12 全部办结）
+
+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 第八轮）
+
+**本轮：你按第七轮的清单改了 5 处口径** —— `markov_simulate`（非负校验带容差、收 `np.integer`、赋值挪进 `try`、
+`metrics` 换成 `terminal_distribution`）、`markov_steady_state`（容差、`max_iter` 的 `TypeError`、
+`tol` 拦 NaN）、`mm1_metrics`（`λ = 0` 放开、收 numpy 标量、失败分支报 `rho`、`data` 去别名）。
+**三处算法本体仍然正确**（探针复测：终点分布 `{0: 0.6644, 1: 0.3356}` 对照 `[2/3, 1/3]`；
+`λ = 0` 给 `L = Lq = Wq = 0`、`W = 1/μ`；`r.data is r.metrics` 已为 `False`）。
+Codex 只同步 docstring + 6 条测试、清 ruff（`B905` 的 `zip` 缺 `strict` + 2 条空白）。
+三连：`pytest` **204 passed / 28 skipped**、`ruff` 0、`pyright` 0。
+
+**接下来三件事**
+1. 下面只剩 **5 条小口径**，基本都是"一个值 / 一个类型"级别的决定。
+2. L0 最后一项 `save_figure`（A 档 = 工程，`viz/export.py`）—— **Codex 直接实现**，你只读。
+3. 之后往 `models` / `decision` 走（见下方第八轮备忘）。
+
+### ⏳ 只剩这 5 条口径待你拍板（Codex 只报不改）
+
+**① `markov_simulate` 的 `bool` 漏网**：`isinstance(True, (int, np.integer))` 为真 → `initial=True` 被当成状态 1。
+实测现在**不再静默给错答案**（`np.full(n_paths, True)` 让后面 `arr[current_states]` 变成布尔掩码、崩掉后吞成 `success=False`），
+但 message 是个看不懂的广播错误 —— 建议入口先判 `bool` → `TypeError`，把易错点 1 的最后一格补上。
+
+**② `markov_simulate` 数组分支的长度口径**（决策 56 的 ①，仍是最大的那条）：标量按**路径数**铺满、数组按**状态数**校验，
+两条对不上（只有 `n_paths == s` 才通）。A / B / C 三个选项见决策 56。
+
+**③ `markov_steady_state` 的 `data`**：`converged=False` → `success=False`，但 `data` 仍是未收敛向量
+（文件内唯一"失败却带 `data`"的分支）。保持（B）还是 `data=None`（C）？
+
+**④ 非方阵的异常类型两处不一致**：`markov_steady_state` 抛 `TypeError`、`markov_simulate` 抛 `ValueError`
+（同一条"不是二维方阵"的校验）。numpy 自己对形状问题抛的是 `ValueError`；要统一成哪个？
+
+**⑤ `mm1_metrics` 的 `data`**：现在是 `metrics.copy()`（不再是同一个对象），但仍是 **dict**，失败分支是 `None`。
+选项：**A** 保持；**B** `data=None`；**C** `data` 给一个 5 元素数组。
+
+### 📦 第八轮备忘：`models` 与 `decision` 是干什么的
+
+这两个包**目前一行都没实现**（全部 `TODO` + `NotImplementedError`），是 `solve` 之后的两大块。分工完全不同：
+
+| | `models` —— 建模 | `decision` —— 评价决策 |
+|---|---|---|
+| 回答的问题 | "这条规律是什么？能不能预测？" | "这几个方案哪个好？" |
+| 输入 | 特征 `X` + 目标 `y`（有监督）或只有 `X`（聚类/降维） | **决策矩阵**（行 = 方案、列 = 指标），通常无标签 |
+| 输出 | 模型对象 + 预测值 + 指标；`compare_models` 出对比表 | 权重向量 + 排序表（`rank`） |
+| 主要依赖 | sklearn / statsmodels（**薄封装**） | numpy 手写为主（S 档：熵权、AHP、GM(1,1)、TOPSIS） |
+| 美赛场景 | 预测题（人口、销量、气温）、"要不要上复杂模型" | 中文赛 / ICM 的评价题（AHP、TOPSIS、灰色关联、熵权） |
+| roadmap 时间盒 | 第 2–3 周 | 第 4 周 |
+
+`models`（19 个函数，5 个文件）：`base.py` 已写好 `Model` 协议（`fit / predict / score` 三件套，已实现）；
+`metrics.py` 是 8 个指标 + `compare_models`（返回 DataFrame，可直接 `save_table(fmt="latex")`）；
+`regression.py` / `timeseries.py` / `ml.py` 全是"一行转发 + 参数校验 + `Result` 包装"。
+注意两处：① `rmse` / `mae` / `r2_score` 的注释写的是 `TODO(L0)`，但 roadmap 的 L0 12 项里没有它们，
+它们属于 L1 的 `models` 清单 —— 注释待统一；② `tests/test_models.py` 用的是**模块级** `pytestmark`，
+违反决策 26（逐条 skip），开写时要拆开。
+
+`decision`（8 个函数，4 个文件）：`weighting.py`（等权 / 熵权 / CRITIC）、`ahp.py`（判断矩阵 + 一致性比率 `CR`）、
+`topsis.py`、`grey.py`（灰色关联 + GM(1,1) 预测）。
+**使用顺序是硬规矩**（`decision/__init__.py` 里写着）：先 `normalize` 无量纲化 → 再声明方向 `benefit_columns`
+→ 再 `entropy_weights` / `ahp_weights` → 最后 `topsis`。跳过第一步直接算权重是评价类题最常见的翻车方式。
+S 档（要配函数卡片）三个：`entropy_weights` / `ahp_weights` / `gm11_fit_predict`，另有 `topsis` 也标了卡片。
+永久不做：`dea_efficiency`（要解一串 LP、低频）、`fuzzy_comprehensive_evaluation`（隶属度函数没有通用形式）。
+
+**建议的开工顺序**：先 `models/metrics.py`（纯函数、最容易、`compare_models` 是"要不要上复杂模型"的裁判，
+也是 roadmap §四里 `models` 的完成标志）→ 再 `fit_linear` / `fit_polynomial`（把 `Model` 协议跑通）
+→ 然后 `decision` 的 `entropy_weights`（S 档、20 行、三个坑：方向 / 量纲 / 零值）→ `topsis` → `ahp` → `gm11`。
+
+### ✅ random_walk 的 4 条待办（2026-10-05 已办结）
+
+- ~~① 非整数 `n_steps` 抛 `ValueError`~~ → 已拆成两条：类型错 `TypeError`、取值错（`<= 0`）`ValueError`，`n_paths` 同样处理。
+- ~~② `steps` 没有形状校验~~ → 已加 `steps.shape != (n_paths, n_steps)` 判失败（实测转置采样器现在能拦住）。
+- ~~③ NaN 不判失败~~ → 已加 `np.isnan(steps).any()`，与 `monte_carlo` 的 NaN 口径（决策 48）拉齐。
+- ~~④ `params` 少 `random_state` / `metrics` 抄了一遍~~ → 已补 `random_state`；`metrics` 换成 `mean_terminal` / `std_terminal`
+  （终点位置的均值与标准差，`ddof=0`）—— 这才是"游走"该看的指标，测试里还顺手验了 `std ≈ √t`。
+
+### ✅ random_walk 的口径（2026-10-05 全部办结）
+
+- ~~① `start` 的入口类型校验被删~~ → 已恢复；文案的"必须是整数"改成"必须是数值"（这条校验本来就收 float），
+  类型名统一 `{type(start).__name__}`。
+- ~~② 签名注解比行为窄~~ → 已改成 `int | np.integer`，`np.int64` 的测试补回来。
+- ~~③ `n_paths == n_steps` 的方阵歧义~~ → 用户选**方案 B**（决策 55）：`size=n_paths * n_steps`（整数）、
+  要求返回一维、内部 `reshape(n_paths, n_steps)`；二维返回一律判失败。实测转置二维 / 方阵二维 / 长度不符全部拦下，
+  且 `monte_carlo` 风格的采样器可直接复用。
+
+### ✅ monte_carlo_probability 的 6 条待办（2026-10-05 全部办结）
+
+- ~~① `p <= 1e-3` 判 `success=False`~~ → 改成 `warning_message`，仍返回区间（实测 p=0 → `(0.0, 0.00383)`）。
+- ~~② Wald 在 p 靠近 1 时退化~~ → 换 **Wilson**（p=1、n=1000：`(1.0, 1.0)` → `(0.99617, 1.0)`）。
+- ~~③ `call_params` 没记 `confidence`~~ → 已加。
+- ~~④ `event` / `sampler` 不可调用被吞成 `success=False`~~ → 已加 `callable` 校验，现在抛 `TypeError`。
+- ~~⑤ `metrics` 混 `np.float64`~~ → `float()` 统一（实测 4 个 key 全是 `float`）。
+- ~~⑥ `n: int`~~ → 已改 `int | np.integer`。
+
+**~~还剩 1 条~~ → 已办（本轮）**
+1. ~~`event: Callable[..., bool]` 的注解与行为不符~~ → 已改 `Callable[..., Any]`，与 `sampler` / `simulator` 对齐。
+   pyright 复测：向量化事件函数不再被拒（原注解会报 `reportArgumentType`）。**决策 50 的遗留清零。**
+
+### ✅ monte_carlo_integral 的 3 条待办（2026-10-05 已办结）
+
+- ~~① `result.message` 被无条件覆盖~~ → 已改成 `if result.success:` / `else:` 两个分支；
+  失败时是"蒙特卡洛多重积分失败：维度 1，体积 1.0000，模拟 100 次。蒙特卡洛模拟失败：TypeError - ..."，
+  `success` 与 `message` 不再打架。
+- ~~② `bounds` 形状没校验~~ → 入口加了 `isinstance(bounds, (list, tuple))` 与 `ndim == 2 and shape[1] == 2` 两道；
+  `bounds=[0, 1]` 现在报"bounds 必须形如 [(lo, hi), ...]，当前形状为 (2,)，请检查是否漏了括号"。
+- ~~③ `n: int`~~ → 已改 `int | np.integer`。
+
+### ✅ monte_carlo_integral 的 2 条新口径（2026-10-05 已办 1 条、剩 1 条）
+
+- ~~① `bounds` 把 ndarray 拒了~~ → 已加 `isinstance(bounds, np.ndarray)` 分支，`np.array([[0.0, 1.0]])` 现在能收。
+- ~~② `if` / `else` 里那三行重复~~ → 已把 `name` / `params["bounds"]` / `params["dimension"]` 提到 `if` 之前，只剩 `message` 分两支。
+
+**还剩 1 条（你的活）**
+1. **第一道 `isinstance` 分支现在是冗余的**：`np.asarray` 本来就同时收 list / tuple / ndarray，
+   而 `[]`、`"abc"`、标量这些都会被下面那句形状校验抓住（报"当前形状为 (0,)"等）。
+   整段可以塌成两行：`bounds_arr = np.asarray(bounds)` + 形状校验 —— 顺带 `bounds.copy()` 也是多余的一次拷贝。
+
+### ⏳ monte_carlo 只剩 1 个口径要你确认
+
+**`ci_low` / `ci_high` 是不是就按"结果的分位数"定？**
+
+现状 `np.percentile(data, [2.5, 97.5])`。实测 n=2e5、E[X²]=1 给出 `[0.001, 5.0455]` ——
+这是**模拟结果的分散度**（预测区间），与 `p05` / `p95` 同类，只是分位点不同。
+而"均值估计的置信区间"（MC 的统计误差）是 `mean ± 1.96·std/√n` = `[0.9962, 1.0086]`，
+两者差两个数量级，论文话术也完全不同：
+
+- A（现状）：写"95% 的模拟结果落在 [a, b]"（描述风险分布）
+- B：改成均值 CI → 写"估计值 1.0024 ± 0.0043（95% CI）"（证明 n 够大）
+- C：两者都要 → 指标要改名（如 `p025`/`p975` + `mean_ci_low`/`mean_ci_high`）
+
+注意：`monte_carlo_probability` 里的 `ci_*` 已经是**估计量的 CI**（Wilson 区间，决策 50），所以这两个函数的 `ci_*`
+目前**含义不同**——这正是要给它们定口径的原因之一。
+
+### ✅ 已拍板（决策 48）
+
+- 批量大小由实现传 `size=n`；`sampler` 必须能接住 `size`，`**kwargs` 里不要再传 `size`。
+- 结果含 NaN → `success=False`（不落 metrics）。
+- `std` 用 `ddof=0`。
+- 出错仍统一返回 `success=False`（`try/except Exception` 保留）。
+
+### ⏳ 另外两个小口径（你说了算）
+
+- **`random_state` 的注解**：经验文档第 3 条写的标准是 `int | np.integer | np.random.Generator | None`，
+  但 `stats/bootstrap.py`、`solve/simulate.py`、`stats/inference.py` 现在都写 `int | None`（只有 `core/random.py` 是全的）——
+  要不要全项目对齐？（运行期 `get_rng` 收 `np.int64`，所以是注解与行为不一致，不是功能 bug）
+- **`std` 的 `ddof`**：`monte_carlo` 用 `ddof=0`，`describe` 那条线用 `ddof=1`。要不要统一？
+
+### 其余待办
+
+1. L0 的最后一项是 `save_figure`（**A 档 = 工程**，`viz/export.py`）—— **由 Codex 直接实现**，用户只读。
+2. L0 跑通后，找一道真题（建议 2025 C）走完整流程，反向沉淀函数。
+3. 已拍板的旧口径（留档）：`log_transform` 的 `offset` 维持现状（决策 35）；
+   `describe` / `zscore` 默认丢掉非数值列（决策 37）；变异系数用 `σ / |μ|`（决策 38）；
+   分工见决策 39；`correlation_matrix` 走方案 A（决策 41）。
+4. **仍未答的一个小问题**：`correlation_matrix` 现在只收 `DataFrame`，
+   而 `describe` / `zscore` / `transform` 都收 ndarray —— 要不要也放开？（你说了算）
+
+5. **`t_test` 有 4 个口径等你拍板（Codex 一律没动，按决策 39）**：
+   - **① 单样本的结论文案说错了。** `b=None` 时 `test_name` 已经是"单样本 t 检验"，
+     但 `conclusion` 仍写"两组数据存在统计学上的显著差异" —— 单样本根本没有第二组。
+     建议按分支拼文案（单样本说"该样本均值与 `value` 有显著差异"）。
+   - **② `paired=True` 时 NaN 是按各自的位置丢的**，会把不同行配成一对（静默错位，不报错）。
+     两个方向：配对前先**成对删缺失**，或**直接拒绝含 NaN 的配对输入**。你定。
+   - **③ `value` 只在 `b is None` 时生效**，同时传 `b` 和 `value` 会被静默忽略 —— 要不要改成报错？
+   - **④ `t_test(DataFrame)` 会把所有数值列摊平成一个样本**（已写进 `Notes`）。
+     多列不同量纲（`gdp` + `pop`）会被混在一起，而且**没法**拿"一张表里两列"当两组比。
+     要不要改成：多数值列的 DataFrame 直接 `ValueError`、强制先自己取列？
+
+6. **`as_array` 落地后留下的 3 个小口径（Codex 没代选，按决策 39）**：
+   - `int` / `float` 标量还在白名单里（为兼容 `normalize` / `standardize` / `log_transform`
+     三个 docstring 写的"数值型标量"）。但标量进来是 **0 维数组**，`axis=0` 的算法照样炸 ——
+     要不要把标量摘掉、同时改三处 docstring？
+   - 内容转不成 float 时统一抛 `TypeError`（决策 45）—— `normalize(含文本列的表)` 原来抛 `ValueError`。
+     要不要改回 `ValueError`（"取值问题"）？
+   - 现在 `kind == "frame"` 时你要自己再写一遍 `x.select_dtypes(include=[np.number]).columns` 取列名。
+     嫌烦的话可以让 `as_array` 顺带把选中的列返回（改成三元组），一句话的事。
+
+7. **`bootstrap_ci` 的 5 个待拍板口径**（Codex 一律没动，按决策 39；详见 `docs/algorithms/bootstrap_ci.md` §10）：
+   - `x` 里的 **NaN** 静默传进统计量 → `nan` 区间（`confidence_interval` / `t_test` 都是先丢掉的，口径不齐）
+   - `n_resamples <= 0` → 现在抛 `IndexError: index -1 is out of bounds`（应在入口给可读 `ValueError`）
+   - `confidence` 越界 → 现在由 numpy 抛 `Percentiles must be in the range [0, 100]`
+   - `method="bca"` → docstring 承诺过、实测 `NotImplementedError`（补实现 ≈25 行，还是从 docstring 删掉？）
+   - `bootstrap_statistic` 仍是 `NotImplementedError`，而 `bootstrap_ci` 把那段重采样循环**内联**了 ——
+     建议抽出去让 `bootstrap_ci` 调它（易错点 16 的变体：同一段算法写了两遍，只实现了一遍）

docs/02-architecture.md

@@ -24,7 +24,7 @@ src/mcm_toolkit/
 ├── core/                ① 基础设施 —— 所有包的地基
 │   ├── result.py        Result
 │   ├── random.py        set_seed / get_rng
-│   └── validate.py      check_array / check_same_length / check_probability / check_square
+│   └── validate.py      as_array（统一入口）/ check_array / check_same_length / check_probability / check_square
 │
 ├── data/                ② 数据进出 —— 最高频
 │   ├── io.py            load_table / save_table
@@ -183,6 +183,32 @@ docstring 给人看。两处打架时，合法用法会被标红，真正的错
 
 参考实现：`core/random.py` 的 `get_rng`。
 
+### 4.8 入口只有一个：`core.validate.as_array`
+
+**凡是要数值数组的函数，第一行都从 `as_array` 进**，不要各自抄
+`isinstance(x, pd.DataFrame)` / `select_dtypes` / `np.asarray`：
+
+```python
+arr, kind = as_array(x, numeric_only=False)   # 入口：白名单 + 转 ndarray + 报告原类型
+...                                           # 中间只写算法
+if kind == "frame":                           # 出口：自己手写，各函数形状不同，没法一刀切
+    return pd.DataFrame(result, index=x.index, columns=x.columns)
+if kind == "series":
+    return pd.Series(result, index=x.index, name=x.name)
+return result
+```
+
+三条硬规矩：
+
+1. **`numeric_only` 按"输出契约"选，不按喜好选**：输出要与输入**同形**的函数
+   （`normalize` / `standardize` / `log_transform`）必须 `False` —— 跳过非数值列会让返回的表少列、
+   对不上原表；输出是"一张数值结果表"的（`zscore` / `confidence_interval` / `t_test`）用默认的 `True`。
+2. **默认不摊平**。要摊平必须显式 `ndim=1`（`t_test` 曾因静默摊平把 `gdp` 和 `pop` 混成一个样本）。
+3. **`as_array` 不删缺失值**。`df.corr` 成对删、`describe` 整列统计、`paired=True` 的 t 检验必须**成对**删 ——
+   在这一层删掉，行与行的对应关系就永久丢了。删缺失是**语义**，归各函数。
+
+只走入口、不走出口的（输出与输入不同形）：`describe`、`correlation_*`、`confidence_interval`、`t_test`。
+
 ---
 
 ## 五、测试策略

docs/03-roadmap.md

@@ -26,6 +26,9 @@
 | `monte_carlo` | `solve/simulate.py` | **S** |
 | `save_figure` | `viz/export.py` | A |
 
+> `correlation_matrix` 有两个**伴随函数**（决策 41）：`correlation_pvalues` 给 p 值矩阵、
+> `correlation_table` 给"系数 + 星标"的论文表格。三者共用同一套入参守卫与**成对删缺失**口径。
+
 ### L1 —— v0.1（共约 40 个）
 
 在 L0 基础上补齐：
@@ -34,6 +37,8 @@
 |---|---|
 | `core` | `check_array` `check_same_length` `check_probability` `check_square_matrix` |
 | `data` | `impute_missing` `winsorize` `log_transform` `one_hot_encode` `train_test_split` `kfold_split` `bootstrap_sample` |
+
+> `core.validate.as_array`（**统一入口**，决策 44）已提前落地。它不是"多一个公开 API"，
 | `stats` | `zscore` `coefficient_of_variation` `confidence_interval` `t_test` `anova` `chi_square_test` `fit_distribution` `goodness_of_fit` `bootstrap_statistic` |
 | `models` | `rmse` `mae` `mape` `smape` `r2_score` `adjusted_r2` `compare_models` `fit_linear` `fit_polynomial` `fit_nonlinear` `predict` `exponential_smoothing` `fit_arima` `forecast` `fit_forest` `fit_logistic` `kmeans` `pca` `cross_validate` |
 | `solve` | `minimize` `linear_program` `integer_program` `dynamic_programming` `knapsack_dp` `simulated_annealing` `pareto_front` `monte_carlo_probability` `monte_carlo_integral` `random_walk` `markov_simulate` `markov_steady_state` `mm1_metrics` `local_sensitivity` `one_at_a_time` `parameter_sweep` `robustness_test` `sobol_analyze` `morris_analyze` |

docs/04-environment.md

@@ -164,6 +164,176 @@ Move-Item -LiteralPath 'D:\anaconda\Lib\site-packages\zstandard' `
 改名后 `import zstandard` 变成正常的 `ModuleNotFoundError`，pandas 会安静地跳过它。
 本次已按此处理，`.venv` 的 `pd.read_csv` 恢复正常。
 
+**坑 7 —— 编辑器报"无法解析导入 numpy / pandas"，但解释器明明是对的。**
+
+现象：`.venv` 与 conda 环境里 `import numpy, pandas` 都正常，pytest 也全过，
+只有编辑器/pyright 满屏 `无法解析导入"numpy"`。
+
+原因是**静态分析器自己挑了一个 python**，跟你运行代码用的那个没关系。本机上
+`pyright --verbose` 一跑就露馅：
+
+```text
+Assuming Python version 3.14.6.final.0
+  Search paths:
+    c:\Users\guzhu\AppData\Roaming\Python\Python314\site-packages
+    c:\Users\guzhu\AppData\Local\Python\pythoncore-3.14-64\Lib\site-packages
+    ...            <- 一个 Anaconda 路径都没有
+```
+
+那个 3.14 来自 PATH 上的 `python`，而 PATH 上的 `python` 是本机唯一的 python：
+
+```text
+where python  ->  C:\Users\guzhu\agent-tools\bin\python.cmd
+                  \-> C:\Users\guzhu\.cache\codex-runtimes\...\python\python.exe
+```
+
+**Codex 运行时的 shim**（Python 3.14，没有 numpy/pandas）。分析器从 PATH 找到它，
+自然解析不到科学栈。注意持久化的 User/Machine PATH 里**并没有**这一项，
+它是被 Codex 进程临时注入的——所以"我的终端里没问题"和"工具有问题"可以同时成立。
+
+还有第二层原因：`.venv` 是 `--system-site-packages` 建的，三方包都在
+`D:\anaconda\Lib\site-packages`，而 **pyright / Pylance 不认 `pyvenv.cfg` 里的
+`include-system-site-packages`**，只会去 `.venv\Lib\site-packages` 找——
+那里只有 `pip`，于是照样报解析不到。
+
+修法（两件事都要做）：
+
+1. 在 `pyproject.toml` 里把分析器钉到工作区 venv，别让它去 PATH 上碰运气：
+
+```toml
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+pythonVersion = "3.13"     # 不写就跟着 PATH 上那个 3.14 走
+```
+
+2. 在 `.venv\Lib\site-packages` 放一个 `.pth` 指向 base 的 site-packages。
+   pyright **不读** `pyvenv.cfg`，但**会读 `.pth`**：
+
+```powershell
+& 'D:\anaconda\python.exe' -c "import sysconfig; print(sysconfig.get_paths()['purelib'])"
+# 把输出的那一行原样写进 .venv\Lib\site-packages\_mcm_base_site_packages.pth
+```
+
+`scripts/setup-venv.ps1` 已经自动做这一步（第 [2/4] 步），换机重建 `.venv` 不用手动补。
+
+改完 pyright 从 `17 errors` 掉到 `0 errors`。IDE 侧还要各做一件事：
+
+* **VS Code / Cursor**：`Ctrl+Shift+P` → Python: Select Interpreter → 选
+  `D:\anaconda\envs\mcm-toolkit\python.exe`（或 `.venv\Scripts\python.exe`），
+  然后 Developer: Reload Window。Pylance 有缓存，不重载不生效。
+* **PyCharm**：Settings → Project → Python Interpreter 选同一个，
+  再 File → Invalidate Caches / Restart。
+
+**一句诊断口诀**：编辑器说"解析不到包"时，先跑 `pyright --verbose` 看它的
+`Search paths`，而不是先去 `pip install`。
+
+**坑 8 —— `df[Index]` 被 pyright 当成 `Series`，`.std()` 的结果于是被判成标量。**
+
+现象：`data/clean.py` 里
+
+```python
+numeric = data[numeric_cols]        # numeric_cols = df.select_dtypes(...).columns
+std = numeric.std()
+std = std.replace(0, np.nan)        # pyright: 无法访问类"float"的属性"replace"
+```
+
+运行时 `numeric` 明明是 DataFrame、`std` 明明是按列的 Series，pyright 却报这个错。
+
+原因：pandas 自带的类型注解里，`DataFrame.__getitem__` 只声明了「`Hashable` → `Series`」
+这一支。拿一个 `Index` 去索引时它挑中这个重载，`numeric` 就被推断成 `Series | DataFrame`；
+而 `Series.std()` 返回的是**标量**，两支一取并集就把 `float` 带了进来 —— `float` 当然没有
+`.replace`。用 `reveal_type` 一问就现原形：
+
+```text
+“numeric”的类型为“Series | Unknown | Self@DataFrame”
+“numeric.std(axis=0)”的类型为“Series | float | Unknown”
+```
+
+几个**没用**的修法（都实测过）：
+
+- `numeric.std(axis=0)` —— 接收方本身还是并集，重载照样解析成并集；
+- `data[list(numeric_cols)]` —— 不改变重载选择；
+- 把参数改由一个类型明确的 `frame` 局部变量承接 —— `frame` 确实干净了，
+  但 `frame[Index]` 还是同一个重载问题。
+
+有效的修法是**只在取列子表那一句上按运行时的真值收窄**：
+
+```python
+from typing import cast
+
+numeric = cast(pd.DataFrame, data[numeric_cols])
+```
+
+`cast` 零运行时开销，而且能把**下面所有行**留在类型检查范围内 —— 比在 `.replace` 那一行
+挂 `# pyright: ignore` 好：那样等于连带放弃后面每一行的检查。
+
+**一句诊断口诀**：pyright 说某行"属性不存在"、但运行时确实能跑，先 `reveal_type(...)`
+把真实推断打出来，看并集里混进了什么，别急着加 `# type: ignore`。
+
+**坑 9 —— pandas 3 起字符串列的 dtype 是 `str`，`select_dtypes(include=["object"])` 已走弃用路径。**
+
+现象：`one_hot_encode` 自动识别类别列时只写了 `['object', 'category']`，
+功能看起来正常，但**每次调用都发一条 `Pandas4Warning`**，而且 warning 里写着这个行为
+"will be removed in a future version"。
+
+```text
+For backward compatibility, 'str' dtypes are included by select_dtypes when 'object'
+dtype is specified. This behavior is deprecated and will be removed in a future version.
+```
+
+原因：pandas 3 起字符串列的 dtype 是 `str`（不再是 `object`）。当前版本为了向后兼容
+仍然把 `str` 列算进 `object`，但那是**过渡行为**。等它真的移除，`include=['object']`
+会一列都选不中 —— 那时 `one_hot_encode(df)` 会**静默**返回未编码的原表，
+不报错、不告警，是最难查的那类错。
+
+实测（本机 pandas 3.0.6）：
+
+| 写法 | 选中 | 告警 |
+|---|---|---|
+| `include=['object', 'category']` | ✅ | **1 条** |
+| `include=['object', 'category', 'str', 'string']` | ✅ | 0 |
+| `include=['str', 'string']` | ✅ | 0 |
+
+修法：把 `'str'` / `'string'` 显式写进 `include`（这也是 pandas 官方迁移指南推荐的写法，
+同时兼容 pandas 2 与 3）。配套测试用 `warnings.catch_warnings(record=True)` 断言
+**一条告警都不该有**，这样以后 pandas 再收紧行为时会立刻变红，不会静默。
+
+**一句诊断口诀**：`select_dtypes` 选不中东西时，先 `print(df[col].dtype)` 看真实 dtype，
+别照着记忆里的 `object` 写。
+
+---
+
+**坑 10 —— scipy 的检验结果在类型检查器里没有 `pvalue` / `statistic` 字段。**
+
+现象：`_, p = stats.pearsonr(x, y)` 运行没问题，但 pyright 报
+`无法将 "_T_co@tuple" 类型的参数分配给 ... 的 "float"`；改成 `.pvalue` 又报
+`无法访问类 "PearsonRResult" 的属性 "pvalue"`。两条都像"库的锅"，其实是存根看不全。
+
+原因：`PearsonRResult` / `SignificanceResult` 不是普通的 `namedtuple`，
+而是在 `scipy/stats/_stats_py.py` 里用 `_make_tuple_bunch(...)` 在**运行时**拼出来的类
+（`PearsonRResult` 还继承自 `PearsonRResultBase`）。类型检查器看不到运行时才生成的字段，
+于是解包会退化成 `object`、属性访问会报"未知"。
+**这不是运行时问题** —— `pearsonr` / `kendalltau` / `spearmanr` 返回的 p 实测都是 `np.float64`。
+
+修法：不要逐处挂 `# type: ignore`，写一个小助手把结果显式收成 `Any`：
+
+```python
+def _pvalue(result: Any) -> float:
+    return float(result.pvalue)
+
+def _statistic(result: Any) -> float:
+    return float(result.statistic)
+```
+
+一处收窄、调用点全干净，`t_test` / `anova` / `chi_square_test` / `fit_distribution` 都能复用。
+
+**`TtestResult` 同理。** `stats.ttest_1samp` / `ttest_ind` / `ttest_rel` 返回的也是
+`_make_tuple_bunch` 在运行时拼出来的类，存根里 `.statistic` 和 `.pvalue` **两个字段都没有**。
+`inference.py` 的 `t_test` 里 `float(res.statistic)` / `float(res.pvalue)` 两行就是这么被 pyright 标红的
+（实测：`TtestResult(statistic=3.873, pvalue=0.0305)`，运行时取值完全正常）。
+换成 `_statistic(res)` / `_pvalue(res)` 后红线消失，**一行 `# type: ignore` 都没挂**。
+
 ---
 
 ## 五、两套环境的实际版本（已对齐）
@@ -187,10 +357,10 @@ Move-Item -LiteralPath 'D:\anaconda\Lib\site-packages\zstandard' `
 
 ### base 升级记录
 
-[FENCE]powershell
+```powershell
 conda update -n base --all -y      # 365 个包更新，下载 638 MB，耗时 1033 秒
 conda install -n mcm-toolkit numpy=2.4.6 -y   # 把项目环境对齐到 base 的 numpy
-[FENCE]
+```
 
 * `conda` 本身从 25.11.1 升到 **26.7.3**。
 * 升级前 `conda list -n base --revisions` 里已留有 revision 记录，可回滚：

docs/algorithms/README.md

@@ -7,8 +7,8 @@ S 档（自己实现的招牌算法）的**函数卡片**放这里，模板见
 
 | 卡片 | 对应函数 | 状态 |
 |---|---|---|
-| `detect_outliers.md` | `data.detect_outliers` | ⬜ |
+| `detect_outliers.md` | `data.detect_outliers` | ✅ 2026-10-02 |
-| `bootstrap_ci.md` | `stats.bootstrap_ci` | ⬜ |
+| `bootstrap_ci.md` | `stats.bootstrap_ci` | ✅ 2026-10-03（§10 有 5 个口径待拍板）|
 | `monte_carlo.md` | `solve.monte_carlo` | ⬜ |
 | `monte_carlo_probability.md` | `solve.monte_carlo_probability` | ⬜ |
 | `monte_carlo_integral.md` | `solve.monte_carlo_integral` | ⬜ |

docs/algorithms/bootstrap_ci.md

@@ -0,0 +1,127 @@
+# bootstrap_ci
+
+| 项 | 内容 |
+|---|---|
+| 模块 | `mcm_toolkit.stats.bootstrap` |
+| 档位 | S |
+| 参考来源 | Efron (1979)；Efron & Tibshirani (1993) *An Introduction to the Bootstrap*；
+|  | `scipy.stats.bootstrap`（只做对照，没有调用） |
+| 状态 | 实现已落地（2026-10-03），§10 有 4 个口径待拍板 |
+
+## 1. 数学定义
+
+给定样本 `x_1..x_n` 与统计量 `T(·)`：从 `x` 中**有放回**抽 `n` 个得到 `x*`，重复 `B` 次，
+得 `T*_1..T*_B`。百分位法区间
+
+```text
+estimate = T(x)                        # 用**原样本**，不是重采样分布的均值
+alpha    = 1 - confidence
+low      = T*_(alpha/2)                # 经验分布的 alpha/2 分位
+high     = T*_(1 - alpha/2)
+```
+
+输入是一个一维样本，输出是「点估计 + 区间」两个标量 —— 这是**非参数**区间，
+不假设正态、也不需要 `T` 的标准误解析式。
+
+## 2. 适用场景
+
+**用**：`T` 没有解析分布（中位数、极差、自定义指标）；样本有偏或分布未知；
+想给区间但不想假设正态（`mean ± z·s/√n` 的替代品）。
+
+**不用**：`n < 10` —— 经验分布太粗，`x` 能重采样出的不同样本极少；
+数据有**强时间相关性**（股票、气温），此时必须用 block bootstrap；
+要估的是**极值**（最大值本身就是上界，见 §5）。
+
+## 3. 参数与返回值
+
+| 参数 | 类型 | 默认 | 含义 | 取值影响 |
+|---|---|---|---|---|
+| `x` | Any | — | 样本；走 `core.as_array(x, numeric_only=True, ndim=1)` | DataFrame 只取数值列，再摊平 |
+| `statistic` | Callable | `np.mean` | 任意 `f(sample) -> float` | 换 `np.median` 就得到中位数的区间 |
+| `confidence` | float | 0.95 | 置信水平 | 越大区间越宽 |
+| `n_resamples` | int | 10000 | 重采样次数 `B` | 越大端点越稳；10000 通常够 |
+| `method` | str | `"percentile"` | 区间算法 | `"bca"` 尚未实现，传了抛 `NotImplementedError` |
+| `random_state` | int \| None | `None` | 随机种子 | `None` 时复用 `core.get_rng` 的模块级生成器且会推进 |
+
+返回 `Result`：
+
+| 字段 | 内容 |
+|---|---|
+| `params` | `estimate` / `low` / `high` / `confidence` / `n_resamples` |
+| `metrics` | `statistic_name`（`np.mean` → `"mean"`；lambda → `"custom"`）|
+| `data` | 不使用 |
+
+## 4. 复杂度
+
+- 时间：`O(B · n)`（`B` 次重采样，每次都要在 `n` 个值上算一次 `T`）
+- 空间：`O(B)` —— **按块处理**，每批 `batch_size = 1000` 行，绝不落地 `B × n` 的整矩阵
+- **什么时候会跑不完**：
+  - `n = 1e4, B = 1e4` → `1e8` 次操作，秒级，正常；
+  - `n = 1e6, B = 1e4` → `1e10` 次操作，**跑不完**；而且 1000×1e6 的单批索引矩阵就要 8 GB，
+    此时应改用解析近似，或把 `B` 降到 1e3 以下、换更便宜的 `T`。
+
+## 5. 数值稳定性
+
+- **统计量有上界时，百分位区间会「塌」到上界。** 极差 `max - min` 的重采样值**永远不可能超过**
+  原样本极差，`B` 个值里有相当比例正好等于它（抽到原样本极值点的那些），
+  于是 `high == estimate` 精确成立。这不是 bug，是 bootstrap 的固有性质 ——
+  区间端点是**样本**的经验分位数，不能给出样本之外的结论。要估极值请用极值理论。
+- 分块只是省内存，不改结果：每批都从同一个 `rng` 按顺序抽索引，等价于一次抽 `B × n`。
+- 随机数**只来自 `core.get_rng`**（决策 24）：给了种子可复现，不给则跟随 `set_seed`。
+- **NaN 目前不处理**：`x` 里的 NaN 会直接进 `T`，`np.mean` 于是给出 `nan` 区间。见 §10。
+
+## 6. 常见错误
+
+1. 不写 seed → 每次跑出来的区间都不一样，论文里的数字对不上 → 传 `random_state` 或先 `set_seed`。
+2. 以为 bootstrap 能得出**比样本更极端**的结论 → 区间端点就是样本的经验分位数，
+   "95% 置信上限 173.2cm" 不可能超过样本最大值。
+3. 拿它估最大值 / 最小值 → 区间会塌成一个点（原因同 §5），该换极值理论。
+4. `n < 10` 硬跑 → 能抽出的不同重采样样本太少，区间没有统计意义。
+5. 把 `n_resamples` 当成"样本量"写进论文 → 论文里要同时写清 `n`、`B`、seed、method。
+
+## 7. 最小示例
+
+```python
+import numpy as np
+
+from mcm_toolkit.stats import bootstrap_ci
+
+r = bootstrap_ci(heights, statistic=np.median, n_resamples=10000, random_state=42)
+print(r.params["low"], r.params["estimate"], r.params["high"])
+print(r.summary())          # 可直接贴进论文的 Markdown 表
+```
+
+## 8. 单元测试要点
+
+| 测什么 | 期望 | 对应测试 |
+|---|---|---|
+| 大样本正态，`statistic=np.mean` | 区间半宽 ≈ `2 × 1.96 × se`，容差 10% | `test_bootstrap_ci_matches_normal_theory_on_large_n` |
+| 任意统计量（中位数，对数正态样本） | 区间包含样本中位数 | `test_bootstrap_ci_works_for_arbitrary_statistic` |
+| 同种子两次 | `low` 完全相等 | `test_bootstrap_ci_is_reproducible` |
+| 不给种子 | 跟随 `set_seed`（决策 24） | `test_bootstrap_ci_follows_get_rng_when_no_seed_is_given` |
+| `estimate` | 等于原样本上的 `T(x)` | `test_bootstrap_ci_reports_the_original_estimate` |
+| `confidence` 0.80 → 0.95 | 区间单调变宽 | `test_bootstrap_ci_interval_widens_with_confidence` |
+| 极差作为统计量 | `high <= estimate`（原子点塌陷） | `test_bootstrap_ci_works_for_a_custom_lambda` |
+| 五种容器 | DataFrame/Series/ndarray/list/tuple 结果一致 | `test_bootstrap_ci_accepts_the_documented_containers` |
+| `method` 非法 / `"bca"` | `ValueError` / `NotImplementedError` | `test_bootstrap_ci_rejects_unknown_method` |
+
+## 9. MCM/ICM 用法
+
+- **哪类题**：任何要"给结论 + 给不确定性"的题 —— 评价类（排名稳定性）、预测类（区间预测）。
+- **论文里怎么表述**："采用非参数 bootstrap（`B = 10000`，`seed = 42`）估计中位数的 95% 置信区间。"
+- **图**：预测曲线 + 阴影置信带（`viz.plot` / `viz.save_figure`）。
+- **踩坑提醒**：必须报 `B` 和 seed；说清用的是 percentile 还是 BCa（目前只有 percentile）；
+  被问到"为什么不用 ±1.96σ"时就答"统计量是中位数，没有解析标准误"。
+
+## 10. 待拍板（未定稿，Codex 不代选）
+
+| # | 口径 | 现状 | 可选 |
+|---|---|---|---|
+| 1 | `x` 里的 NaN | 静默传进 `T` → `nan` 区间 | 像 `confidence_interval` 一样丢掉 / 直接报错 / 维持现状 |
+| 2 | `n_resamples <= 0` | 走到 `np.percentile` 抛 `IndexError: index -1 is out of bounds` | 入口 `ValueError（必须 ≥ 1）` |
+| 3 | `confidence` 越界 | 由 numpy 抛 `ValueError: Percentiles must be in the range [0, 100]` | 入口 `ValueError + 可读文案` |
+| 4 | `method="bca"` | docstring 承诺过，实测 `NotImplementedError` | 补 BCa 实现（S 档，约 25 行）/ 从 docstring 删掉 |
+| 5 | `bootstrap_statistic` | 仍是 `NotImplementedError`，而 `bootstrap_ci` 把重采样循环内联了 | 抽出去让 `bootstrap_ci` 调它（易错点 16 的变体） |
+
+> 口径 5 尤其值得做：`bootstrap_statistic` 的 docstring 与 `bootstrap_ci` 里那段循环说的是同一件事，
+> 现在等于把同一段算法写了两遍，只实现了一遍。

docs/algorithms/detect_outliers.md

@@ -0,0 +1,172 @@
+# detect_outliers
+
+| 项 | 内容 |
+|---|---|
+| 模块 | `mcm_toolkit.data.clean` |
+| 档位 | S |
+| 参考来源 | Tukey (1977) *Exploratory Data Analysis*（1.5·IQR 围栏的出处）；3σ 准则见 NIST/SEMATECH e-Handbook §1.3.5.17；实现直接调用 `pandas.DataFrame.quantile` / `mean` / `std` |
+| 实现状态 | 已实现（2026-10-02），`tests/test_data.py` 中 9 条用例覆盖 |
+
+## 1. 数学定义
+
+设某列数值样本 `x_1..x_n`，记 `Q_1 = quantile(0.25)`、`Q_3 = quantile(0.75)`，
+四分位距 `IQR = Q_3 - Q_1`。对每个 `x_i` 给出布尔判定：
+
+**IQR 法**（默认）：
+
+```text
+m_i = (x_i < Q_1 - k·IQR)  or  (x_i > Q_3 + k·IQR)     默认 k = 1.5
+```
+
+**z-score 法**：
+
+```text
+z_i = (x_i - x̄) / s        s 为样本标准差（ddof = 1）
+m_i = |z_i| > t                                     默认 t = 3.0
+```
+
+输入：一张表（`DataFrame`）或一维序列；输出：**与原数据同形的布尔掩码**，
+`True` 表示该位置是离群点。数学上它是逐元素定义的二值函数，不依赖行与行之间的关系。
+
+## 2. 适用场景
+
+**用**：
+
+- 数据录入错误（身高 260 cm、年龄 −10）这类"明显不可能"的点，先标出来给人看。
+- 建模前的敏感性分析：删与不删各跑一遍，看结论动不动 —— 这比直接删更有说服力。
+- 论文要交代"异常值怎么处理"时，这是最容易被评审接受的判据（有文献、可复现、无随机性）。
+
+**不用**：
+
+- **别拿它当自动清洗**。偏态、幂律、小样本（`n < 20`）时 IQR 围栏会误杀 ——
+  重尾数据里"离群"常常就是信号本身。
+- z-score 法**前提是近似正态**。右偏数据（收入、人口、成绩分布）用它会把整片上尾标红。
+- 时间序列里的"离群"可能来自趋势或季节项，应先去趋势/差分再判，否则会把拐点当异常。
+- 多变量离群（单变量看都正常、组合起来才异常）它看不出来，那要用马氏距离或 `IsolationForest`。
+
+## 3. 参数与返回值
+
+| 参数 | 类型 | 默认 | 含义 | 取值影响 |
+|---|---|---|---|---|
+| `data` | `DataFrame` / `Series` / `list` / `tuple` / `ndarray` | 必填 | 待判数据 | 非数值列不参与统计，掩码里恒 `False`（见下） |
+| `method` | `"iqr"` / `"zscore"` | `"iqr"` | 判据 | IQR 对重尾稳健；zscore 只在近似正态时可靠 |
+| `k` | `float` | `1.5` | 仅 IQR：围栏倍数 | 1.5 是 Tukey 的 "outlier"、3.0 是 "far outlier"；调小 → 标出更多 |
+| `threshold` | `float` | `3.0` | 仅 zscore：\|z\| 阈值 | 3.0 ≈ 正态下的 0.27%；调小 → 标出更多 |
+
+`k` 与 `threshold` 通过 `**kwargs` 传入，**传错了不会报错**（`k` 只在 iqr 分支被读）。
+
+### 为什么它不返回 `Result`
+
+模板里"返回 `Result`"这一节对它**不适用**，这是刻意的：`Result` 承载的是"一次计算的
+参数 + 指标 + 数据"，而 `detect_outliers` 不改数据、不产生标量指标，它只是一个逐元素的
+布尔判断。包成 `Result` 会多一层壳，调用方反而要写 `r.data` 才能拿到掩码。
+
+返回值按输入形状分派：
+
+| 输入 | 输出 |
+|---|---|
+| `DataFrame` | 同形布尔 `DataFrame` |
+| `Series` | 布尔 `Series`，**列名保留** |
+| 一维 `list` / `tuple` / `ndarray` | 一维布尔 `ndarray` |
+| 二维 `ndarray` | 同形布尔 `DataFrame` |
+
+### 非数值列为什么恒 `False`
+
+两条备选路都被否掉了：
+
+- **跳过**（把非数值列从掩码里去掉）→ docstring 承诺的"与原数据同形"就是假话，
+  形状对不上，也就没法按位置把掩码和原表对回去；
+- **报错** → 一张带 `city` 列的真题表直接不可用，而 `city` 列本来就不该影响数值列判定。
+
+`False` 的读法是"这一列没有离群点"，对文本列而言这是最不坏的解释，
+而且让整表能一次跑完。**但要注意**：这只是"不报错"，
+不代表文本列可以当数值列进模型 —— 编码是 `one_hot_encode` 的事。
+
+## 4. 复杂度
+
+- 时间：`O(n·p)`（n 行、p 列；分位数和均值各扫一遍，比较再扫一遍）。
+- 空间：`O(n·p)` —— 掩码与原表同形，这是主要开销。
+- **什么时候会跑不完**：单机几千万行以上时，同形掩码会把内存吃满
+  （1e7 行 × 20 列 `float64` 约 1.6 GB，掩码再来一份 `bool` 约 0.2 GB，
+  但 `quantile` 内部还会再复制）。真到那一步应该分块流式处理，而不是加内存。
+
+## 5. 数值稳定性
+
+- **`std == 0`（整列同值）**：代码里先 `std.replace(0, np.nan)`，让该列 z 全为 NaN、
+  一律判 `False`。少这一步会得到 `inf` / `0/0` 并伴随 RuntimeWarning。
+- **NaN**：比较结果是 `False`，所以缺失值**不会**被标成离群。这是有意的 ——
+  缺失归 `clean_missing` / `impute_missing` 管，两件事不该混。
+- **`n = 1`**：`std` 是 NaN、分位数等于该值本身，掩码全 `False`。小样本别指望它。
+- **边界值**：`x_i` 恰好等于围栏值时**不算**离群（用的是严格 `<` / `>`）。
+  这是刻意选的：边界值不该被当异常。
+- **`ddof` 口径**：本函数用 pandas 的 `Series.std()`，默认 `ddof = 1`（样本标准差），
+  而 `numpy.std` 默认 `ddof = 0`（总体标准差）。小样本下差别不小：`[1,2,3,4,1000]` 的
+  std 是 446.1（ddof=1）对 399.0（ddof=0），z 值直接差一成。**本项目 `stats.zscore` 的默认
+  也是 `ddof = 0`**，两处口径不一致是已知问题 —— 论文里报 |z| 时必须写明用的哪一个。
+  （分位数这边反而没问题：pandas `quantile` 与 `numpy.percentile` 默认都是线性插值，结果一致。）
+
+## 6. 常见错误
+
+1. 把返回值当筛选结果：`df = detect_outliers(df)` → 表变成布尔掩码。
+   正确做法是 `mask = detect_outliers(df)`，然后**自己决定**删不删。
+2. 对含文本列的真题表直接调用 → 老版本在 `quantile()` 上崩。现在非数值列恒 `False`，
+   但要记得"不崩"不等于"文本列进了模型"。
+3. 用 z-score 判右偏数据 → 整片上尾被标红，删完结论就变了。先画分布再选方法。
+4. 看到离群就删 → 论文里没有交代、评审必问。先报告个数与占比，再做删/不删对照。
+5. 只报"删了 5 个" → 没给比例、没给判据、没给 `k`。论文里这三个数缺一不可。
+6. 以为要设 seed → 本函数**不含随机成分**；但后续若用 bootstrap 比较"删前后"的差异，
+   那条链必须 `set_seed`，否则"可复现"是假的。
+
+## 7. 最小示例
+
+```python
+import numpy as np
+import pandas as pd
+
+from mcm_toolkit.data import detect_outliers
+
+df = pd.DataFrame({"city": list("abcd"), "v": [1.0, 2.0, 3.0, 1000.0]})
+
+mask = detect_outliers(df)          # IQR，默认 k=1.5；只标不删
+print(mask)
+#    city      v
+# 0  False  False
+# 1  False  False
+# 2  False  False
+# 3  False   True
+
+print(np.asarray(mask).sum())       # 1
+print(detect_outliers(df["v"]).tolist())   # Series 进 Series 出
+# [False, False, False, True]
+
+# 想改成更激进的判定：k 调小
+print(np.asarray(detect_outliers(df, k=0.5)).sum())
+```
+
+## 8. 单元测试要点
+
+| 测什么 | 期望 |
+|---|---|
+| 埋 3 个远离主体的点（IQR 默认） | 正好命中 3 个，且位置对得上 |
+| 埋 1 个点（zscore 默认 t=3） | 正好命中 1 个 |
+| 返回形状 | 与输入同形；Series 进 Series 出且列名保留；一维数组进一维布尔出 |
+| 含文本列的表 | 不崩，文本列恒 `False`，数值列照常判定 |
+| 整表没有数值列 | 不崩，返回全 `False` 掩码 |
+| `method="bogus"` | `ValueError`，报错信息里带方法名 |
+| `data = 42 / 3.14 / "123" / None / dict` | `TypeError`（§4.7：非法类型不静默兜底） |
+| 全 NaN 列、单元素列 | 全 `False`，不抛异常 |
+| 元组入参 | 按一维数组型处理，结果与传 list 一致 |
+
+## 9. MCM/ICM 用法
+
+- **哪类题**：所有要写"数据预处理"小节的题（几乎全部）。评价类与预测类尤其要做，
+  因为离群点对均值、回归系数的影响最大。
+- **论文里怎么表述**：
+  "采用 Tukey (1977) 的 1.5×IQR 围栏识别异常值：记 Q1、Q3 为第一、三四分位数，
+  凡落在 [Q1 − 1.5·IQR, Q3 + 1.5·IQR] 之外者标为可疑点，共 N 个（占 x%）。
+  我们保留全部原始数据，并给出剔除/不剔除两版对照结果（见附录 B）。"
+- **图**：箱线图（标出被标红的点）+ 直方图叠围栏竖线；用 `viz.plot(kind="box")`
+  与 `viz.plot(kind="hist")`，保存用 `viz.save_figure`。
+- **踩坑提醒**：评审最可能追问三件事 ——
+  ① 为什么是 1.5 而不是 3？② 删了多少、删完结论变了吗？③ 这些点是"错误"还是"真实极端值"？
+  三个问题都要在论文里先答，别等被问。

docs/dev/personal-pitfalls.md

@@ -26,6 +26,30 @@
 | 2 | 以为 `# TODO(L0)` 只是普通注释 | 2026-10-01 |
 | 3 | 签名里的类型注解和 docstring 说的不一致 | 2026-10-01 |
 | 4 | 只覆盖自己的状态，忘了第三方库还在用 numpy 旧全局 | 2026-10-01 |
+| 5 | 参数校验排在副作用（建目录 / 写文件）之后 | 2026-10-01 |
+| 6 | 把 lint 的"没报错"当成"没问题" | 2026-10-01 |
+| 7 | 写"守卫子句"时，忘了不是所有入参都长一样 | 2026-10-02 |
+| 8 | 改了一处，忘了同源的另一处 | 2026-10-02 |
+| 9 | 实现写完了，测试还挂着 skip —— 绿灯是假的 | 2026-10-02 |
+| 10 | 把真报错当成"编辑器误报" | 2026-10-02 |
+| 11 | pandas 对不齐就静默填 NaN，不报错 | 2026-10-03 |
+| 12 | 三个并列的 `if`，后面的静默覆盖前面的 | 2026-10-03 |
+| 13 | `Index == 标量` 得到布尔数组，`if` 要等到第 2 列才炸 | 2026-10-03 |
+| 14 | 把"能看的表"和"能算的表"塞进同一个返回值 | 2026-10-03 |
+| 15 | 区间被无条件夹到 `[0, 1]`，且 `min` / `max` 参数写反 | 2026-10-03 |
+| 16 | 同一段入口转换抄了 N 遍，还当它是"本项目的写法" | 2026-10-03 |
+| 17 | `hasattr(f, "__name__")` 挡不住 lambda，`else` 分支是死代码 | 2026-10-03 |
+| 18 | 入口校验"想起什么写什么"，没照 §4.7 清单逐条过 | 2026-10-04 |
+| 19 | 只想着主路径那种值，忘了布尔 / NaN / 长度不对 | 2026-10-04 |
+| 20 | "不简单"的信号：同一个信息要在调用方写两遍 | 2026-10-04 |
+| 21 | 公式里的 `^` 不是乘方，而且被 `except` 吞成 success=False | 2026-10-05 |
+| 22 | 失败结果的 `message` 被包装层无条件覆盖 —— 对外永远报"成功" | 2026-10-05 |
+| 23 | 体积/宽度这种"看着总为正"的量也会减反，维度奇偶还会把符号错误藏住 | 2026-10-05 |
+| 24 | 默认参数路径从没被执行过 —— 默认采样器用了库不接受的参数 | 2026-10-05 |
+| 25 | 两个维度相等时，转置的形状检查会静默通过 | 2026-10-05 |
+| 26 | `except` 用到的变量在 `try` 里才赋值 —— 每条失败路径都炸 | 2026-10-05 |
+| 22 | 失败结果的 `message` 被包装层无条件覆盖 —— 对外永远报"成功" | 2026-10-05 |
+| 23 | 体积/宽度这种"看着总为正"的量也会减反，维度奇偶还会把符号错误藏住 | 2026-10-05 |
 
 ---
 
@@ -37,7 +61,10 @@
 - 以后怎么防：写类型分支时默认假设"这个值可能来自 numpy"。判断用 `isinstance(x, (int, np.integer))`，
   取值统一 `int(x)` 归一化；并且给所有非预期类型加 `raise TypeError` 兜底——
   **宁可报错，也不要静默走默认分支**。
-- 首次：2026-10-01｜复发：0
+- 复发（2026-10-04）：`monte_carlo` 的 `n` 只写了 `isinstance(n, int)` —— `np.int64(1000)` 被 `ValueError` **误拒**，
+  而 `n=True` 反而放行（`bool` 是 `int` 子类，判断顺序又反了）。
+  同一张 §4.7 表的第一、三行，症状从"静默兜底"变成"误拒 + 误收"：**规则没换，只是没去查**（见第 18 条）。
+- 首次：2026-10-01｜复发：0 → **1（2026-10-04）**
 
 ### 2. 以为 `# TODO(L0)` 只是普通注释
 
@@ -55,7 +82,10 @@
   两处打架时合法用法会被 IDE 标红，真正的错误反而看不出来。
 - 以后怎么防：改签名和改 docstring 必须同一次做完。
   本项目所有 `random_state` 的注解统一写 `int | np.integer | np.random.Generator | None`。
-- 首次：2026-10-01｜复发：1
+- 复发（2026-10-05）：`monte_carlo_probability` 写 `event: Callable[..., bool]`，docstring 却说"返回长度为 `n` 的**布尔数组**"
+  —— 注解只描述"返回一个 bool"。pyright 实测：这样写会**拒绝**任何注解良好的向量化事件函数（`ndarray` 与 `bool` 不兼容），
+  而运行期它一直都收得下。同一个坑从"收什么"换到了"返回什么"：**注解是契约，不是备注**。
+- 首次：2026-10-01｜复发：1 → **2（2026-10-05）**
 
 ### 4. 只覆盖自己的状态，忘了第三方库还在用 numpy 旧全局
 
@@ -66,3 +96,467 @@
 - 以后怎么防：凡是"设全局状态"的函数，先列清单——自己的、numpy 旧的、标准库 `random` 的、
   第三方框架的，逐个决定要不要一起设，并在 docstring 里写清到底覆盖了哪几个。
 - 首次：2026-10-01｜复发：0
+
+
+### 5. 参数校验排在副作用（建目录 / 写文件）之后
+
+- 现象：`save_table` 先 `path.parent.mkdir(parents=True, exist_ok=True)`，再在
+  `if suffix == '.csv' ... else: raise ValueError` 里判断后缀。传 `sub/x.txt` 时，
+  空目录 `sub\` 已经建出来了，函数才抛 `ValueError`——错误路径上留下垃圾。
+- 为什么会错：函数体是照着"顺利流程"顺着写下来的——先建目录、再按分支干活；
+  校验顺手塞进分支的 `else` 里，于是校验自动排到了最后。分支越多，越会有路径漏掉。
+  会传染：`isinstance` 校验改到 `mkdir` 前面之后，后缀校验**还是**留在原地，
+  因为它藏在分支里，看起来"已经检查过了"。
+- 以后怎么防：函数体分三段写——**① 所有校验 → ② 所有副作用（建目录 / 写文件 /
+  联网 / 改全局状态）→ ③ 主逻辑**。校验用守卫子句集中在开头，不要塞进分支里；
+  凡是 `raise` 的行，位置必须在校验段内，不能出现在副作用段之后。
+  写完自问一句："这个参数不合法时，磁盘 / 网络 / 全局状态会不会已经动过了？"
+- 首次：2026-10-01｜复发：0
+
+### 6. 把 lint 的"没报错"当成"没问题"
+
+- 现象：`__all__` 与下一个 `def` 之间只留了 1 个空行（PEP 8 要求 2 个），
+  `ruff check src tests` 照样打印 "All checks passed!"。
+- 为什么会错：版本号看着一样，覆盖的规则却是两回事。ruff 0.16 里 `E302`
+  （函数间空行）属于 **preview 规则**，不在 `select = ["E"]` 的默认集合里——
+  加了也会被"because preview is not enabled"忽略掉，安安静静不报。
+  根本问题是：**lint 只检查你 select 的那部分**，而默认规则集本来就不是 PEP 8 全集。
+  把"我配的检查全过了"读成"这份代码符合规范"，是把自己没开的检查当成了已经通过的检查。
+- 以后怎么防：把 lint 结论限定成"我 select 的规则里没问题"，别说成"没问题"。
+  想看全貌就偶尔跑一次 `ruff check --select ALL --preview`（只当参考，别直接开进 CI，
+  会淹没在噪声里）；纯格式问题交给 `ruff format`，它是 formatter，不受 `select` 影响。
+- 首次：2026-10-01｜复发：0
+
+### 7. 写"守卫子句"时，忘了不是所有入参都长一样
+
+- 现象：`winsorize` 开头先算 `numeric_cols = data.select_dtypes(include=['number']).columns`
+  挡"空数值列"，但 `winsorize` 同时收 `DataFrame` 和 `Series` ——
+  **`Series` 上没有 `select_dtypes`**，传 Series 直接 `AttributeError`，
+  而且报错就报在守卫那一行（全函数看起来最"安全"的地方）。
+- 为什么会错：写的时候只想"要防住空数值列"，顺手把守卫放在函数最上面，
+  没回头确认**这个函数还收哪些类型**。守卫本身没错，错的是它的**位置**：
+  它对 `DataFrame` 成立、对 `Series` 根本不合法，所以必须排在
+  `isinstance(data, pd.Series)` 的类型分派**之后**。
+  本质是：**先做类型分派，再写只对其中一支成立的逻辑**。
+- 以后怎么防：写"开头集中校验"之前，先把入参的**全部类型**列一遍，
+  逐条问"这句话对每种类型都成立吗"；不成立的往后挪，
+  挪进 `if isinstance(...)` 里面，让它只有对应的那一支能走到。
+- 首次：2026-10-02｜复发：0
+
+### 8. 改了一处，忘了同源的另一处
+
+- 现象：给 `detect_outliers` 加"文本列不参与"的修复时，只把**掩码写入**收窄到数值列
+  （`mask[numeric_cols] = ...`），却让 `data.quantile()` / `data.mean()` / `data.std()`
+  继续在全表上算。测试照样红 —— 文本列在**算统计量**那一步就崩了，跟掩码怎么写没关系。
+- 为什么会错：眼睛盯着"结果往哪放"（掩码），没回头问"这些数是从哪儿来的"。
+  同一份数据在函数里要过两道加工：**先出统计量（分位数 / 均值 / 标准差），再拿去比较**。
+  只把后一道收窄、前一道还是全表，等于没修。
+  修完测试报告里那条仍是 XFAIL，就是这个信号 —— 报告没变绿，说明根因没抓着。
+- 以后怎么防：修"某处不该参与计算"这类问题时，顺着数据从入到出**走一遍**，
+  把该收窄的地方一次列全，别改完第一处就收手；
+  并且以测试信号（XFAIL → XPASS）为准，别以"我改的那一行看起来对了"为准。
+- 首次：2026-10-02｜复发：0
+
+### 9. 实现写完了，测试还挂着 skip —— 绿灯是假的
+
+- 现象：`transform.py` 四个函数都写完了，`pytest` 一片绿（`64 passed`），
+  但 `test_normalize_minmax_range` / `test_standardize_has_zero_mean_unit_std` 两条
+  还挂着 `@pytest.mark.skip(reason=_NOT_IMPLEMENTED)` —— 新代码**一条测试都没跑到**。
+  顺带还漏掉一个真错：`normalize` 少了兄弟函数都有的类型守卫，`normalize(None)` 静默返回 NaN。
+- 为什么会错：`skip` 是"还没写"的意思，写完实现后该由**写的人**把它摘掉；
+  但摘 mark 这个动作不在"写函数"的肌肉记忆里，跑一次 `pytest` 看到全绿就以为收工了。
+  这是决策 26 埋下的反面：逐条 skip 比模块级 skip 精确，但**数量得自己盯**。
+- 以后怎么防：每次写完实现，用 `pytest -q -rs`（或 `--collect-only`）**核对 skip 条数掉没掉**；
+  条数没变就说明实现没被验证过。另一个信号是 `pytest --collect-only` 的收集数 ——
+  新写的测试没进收集列表，就是名字或位置不对。
+- 复发（2026-10-03）：`bootstrap_ci` 写完了，`tests/test_stats.py` 里等它的 3 条仍然挂着 skip，
+  全量照样 134 passed / 37 skipped 全绿 —— 连 `_NOT_IMPLEMENTED` 这个常量名都没提示你。
+- 首次：2026-10-02｜复发：0 → **1（2026-10-03）**
+
+### 10. 把真报错当成"编辑器误报"
+
+- 现象：`transform.py` 改完后编辑器（Pylance）在 `pd.DataFrame(result, columns=x.columns,
+  index=x.index)` 两行画红线，第一反应是"静态检查又误报了，挂个 `# type: ignore` 就完了"。
+  实际跑一遍：**pyright CLI 报同样的 2 个错**（Pylance 就是 pyright 的内核），
+  而且 `pytest` **7 条红**（`normalize` 的三种 method 全走错、`one_hot_encode` 把编码列整列丢掉）。
+  红线只是**症状**，病在代码里。
+- 为什么会错：编辑器把错误显示在**它看得见的那一行**，而那一行的类型确实和来源不符；
+  但"类型不符"既可能是检查器保守（误报），也可能是**上游真的算错了**。
+  不验证就下"误报"结论，等于用一个假设替代一次检查。
+- 以后怎么防：见到红线先做两件事，再谈 `# type: ignore` ——
+  ① 在**终端**跑同引擎的 CLI（`python -m pyright`），排除编辑器缓存/配置差异；
+  ② 跑 `pytest`，看对应的行为断言红不红。两条都过、确认只是检查器保守推断，
+  才在**最小范围**加 `# type: ignore[具体错误码]`；裸 `# type: ignore` 会连带关掉后面所有行
+  （更好的写法见 `docs/04-environment.md` 坑 8 的 `cast`）。
+- 首次：2026-10-02｜复发：0
+
+### 11. pandas 对不齐就静默填 NaN，不报错
+
+- 现象：`describe` 里为了"行 = 变量、列 = 指标"多做了一次 `.T`，然后
+  `table.loc["missing"] = df_num.isna().sum()`。跑起来**一声不响**，表里却多出四行
+  **全 NaN**（`missing` / `missing_ratio` / `skewness` / `kurtosis`）。
+  `.loc[新行标签] = Series` 是按**列名**对齐的：Series 的索引是变量名、表的列名是
+  指标名，两边**没有一个交集**，pandas 于是把整行填成 NaN —— 不抛异常。
+  同一个 `.T` 让 `weights` 分支换成 ndarray 后反而直接报
+  `ValueError: cannot set a row with mismatched columns` —— 那个报错才是救命的。
+- 为什么会错：脑子里想的是"给这一行赋值"，pandas 做的是"按标签对齐再赋值"。
+  对齐失败在 pandas 里是**合法结果**（就是缺失），不是错误 —— 它不会替你判断
+  "这次对齐失败是不是手滑"。
+- 以后怎么防：① 往表里加一行前，先确认 Series 的索引 == 目标轴的标签（列名），
+  拿不准就 `print(list(series.index))` 对着 `list(table.columns)` 看一眼；
+  ② 新加的行/列**立刻断言不是全 NaN**，别只看"代码跑过去了"；
+  ③ 记住这次的信号差异：长度不对（ndarray）会报错，Series **不会** —— 后者更危险。
+- 首次：2026-10-03｜复发：0
+
+### 12. 三个并列的 `if`，后面的静默覆盖前面的
+
+- 现象：`normalize` 里三种 method 写成了**三个并列的 `if`**（而不是 `if / elif / else`）：
+  `if method == "minmax": result = ...`、`if method == "vector": result = ...`，
+  末尾再来一句无条件的 `result = arr / x_max` 兜住 max。
+  读起来像"三种方法各算各的"，实际是**三段顺序执行、逐次覆盖**同一个 `result`：
+  不管传 minmax 还是 vector，算完都被最后那段冲掉 —— 三种方法**实际只走了 max**。
+  docstring 里那行 `>>> normalize([1, 2, 3]).tolist()` → `[0.0, 0.5, 1.0]` 就是活规格，
+  实测出来是 `[0.33, 0.67, 1.0]`，5 条测试一起红。
+- 为什么会错：脑子里想的是"按 method 分派"，手上写成了"按顺序执行"。
+  写第一个 `if` 的时候没意识到"少了 `elif` 就没有互斥"，而 `result` 又是同一个变量 ——
+   `if` 只会让**条件为真时**赋值，`elif`/`else` 才负责让**其余分支不执行**。
+  这类错**不报错、不抛异常**，只有断言能抓。
+- 以后怎么防：① 同一个变量被多个分支赋值时，一律 `if / elif / else`，或让每个分支 `return`，
+  绝不写并列 `if`；② 分派逻辑写完先跑最朴素的那个用例（docstring 的 Examples 就是最好的靶子），
+  别等全量测试；③ 注意 ruff 的 `RET505` 抓的是**反方向**（`return` 后还有 `elif`），
+  并列 `if` 覆盖它完全管不着 —— **lint 不会替你发现这个**。
+- 同一轮的另一个同类例子见第 11 条（`.loc` 对齐失败静默填 NaN）：
+  这两个 bug 的共同点是"**不抛异常**"，靠的是断言而不是报错。
+- 首次：2026-10-03｜复发：0
+
+### 13. `Index == 标量` 得到布尔数组，`if` 要等到第 2 列才炸
+
+- 现象：`correlation_matrix` 里的判空写成了 `if numeric_cols == 0:`，本意是"一个数值列都没有就报错"。
+  实际行为分成三段，**每一段都不一样**：
+  - **0 列**：`array([], dtype=bool)` → `bool(...)` 是 `False` → **静默不报错**，带着空表继续往下跑；
+  - **1 列**：`array([False])` → 单元素数组能转 `bool` → **碰巧正常**；
+  - **≥2 列**：`array([False, False, ...])` → `ValueError: The truth value of an array
+    with more than one element is ambiguous` → **直接崩**。
+  而"≥2 个数值列"恰恰是最常见的情况，所以这一行等于让整个函数不可用。
+- 为什么会错：`Index` 重载了 `==`，做的是**逐元素比较**，返回的是**数组**不是 `bool`。
+  脑子里比的是"这个序列是不是空的"，手上写的是"这个序列的每个元素是不是 0"。
+  更阴的是 1 列时它能跑通 —— 拿单列试一下就会以为这行没问题。
+- 没被抓住的原因：对应的 L0 用例当时还挂着 `skip`（见第 9 条），所以实现零覆盖。
+- 以后怎么防：① 判"空"一律 `len(x) == 0`（或 `.empty`），绝不用 `== 0`；
+  ② 判断容器里有没有东西，用 `if not len(...)` 而**不是** `if x:` ——
+  `if x:` 对 `DataFrame` / `Index` / 多元素 `ndarray` 会抛同一个歧义错误；
+  ③ 新写的分支，**至少拿 0 / 1 / 多三种形状各跑一遍**，单列能过不代表多列能过。
+- 首次：2026-10-03｜复发：0
+
+### 14. 把"能看的表"和"能算的表"塞进同一个返回值
+
+- 现象：`correlation_matrix` 返回的是一张**带显著性星标的字符串表**（`1.000***` 这种），
+  直接贴论文很爽。但同一个函数在 docstring 里承诺的是"值 = 相关系数"，
+  L0 用例也断言 `np.allclose(np.diag(...), 1.0)` —— 字符串表两样都做不到：
+  拿到结果的人**没法**挑高相关对、喂给聚类 / PCA、画热力图。
+  于是这条用例只能先挂 `xfail`，实现和契约顶在那里。
+- 为什么会错：写的时候想的是"我最后要看到什么"（论文里的那张表），
+  没想"调用方还要拿它**算什么**"。展示需求是**输出端**的事，不该侵占返回值。
+  一旦返回字符串，数值信息就**不可逆地丢了**（你可以随时把数字格式化成字符串，
+  但没法把 `"0.570***"` 还原成 `0.570` 和小数点后丢失的精度）。
+- 以后怎么防：① 一个函数只返回**一种东西** —— 要么是数据，要么是给人看的展示；
+  ② 判据是"这个返回值还能不能参与下一步计算"：不能，就该拆成两个函数；
+  ③ 拆的时候让**计算型**当主函数、**展示型**去调它（`correlation_table` 调
+  `correlation_matrix` + `correlation_pvalues`），而不是反过来。
+- 首次：2026-10-03｜复发：0
+
+### 15. 区间被无条件夹到 `[0, 1]`，且 `min` / `max` 的参数写反了
+
+- 现象：`confidence_interval` 的返回写成了
+  `return (float(min(0.0, lower)), float(max(upper, 1.0)))`，本意是"比例区间不能越界"。
+  三个毛病叠在一起：
+  ① **参数写反**：要夹下界应该写 `max(0, lower)`，写成了 `min(0.0, lower)` —— `0.0` 比任何正的下界都小，
+     `min` 取到的永远是它，于是**下界恒为 0**；上界那条 `max(upper, 1.0)` 同样是反的，
+     只是它在 `upper > 1` 时凑巧看不出问题。
+  ② **无条件夹**：三种 method（含 `normal` / `t` 这两种**均值**区间）全被夹。
+     均值区间的量纲根本不在 `[0, 1]` 里：实测
+     `confidence_interval(rng.normal(170, 8, 50), method="t")` 的下界是 **0.0**，
+     而正确结果是 `171.0 ± 2.1`。这种错**不抛异常**，只有把数字打印出来才会发现"身高的下界是 0"。
+  ③ **夹子会吞掉报错信号**：`confidence=1.5` 时 `z` 是 `nan`，`min(0.0, nan)` 返回 `0.0`
+     （`min` 在遇到 `nan` 之前先锁定了第一个参数），于是本该报错的入参被盖成 `(0.0, nan)`。
+     另外 `confidence=0` 也一路放行（定义域应是 `(0, 1)` **开区间**）。
+- 为什么会错：脑子里记的是"clamp(x, lo, hi)"这个整体，手上却从两个方向各写了一个 `min` / `max`；
+  更要命的是**试数据选了 `[1, 2, 3, 4, 5]`** —— 它恰好落在 `[0, 1]` 附近，夹不夹都看不出来。
+  换一个量纲明显不在 `[0, 1]` 的例子（身高 170、GDP 十亿）跑第一遍，这个 bug 一秒现形。
+- 以后怎么防：① 夹子只写一个方向：`np.clip(x, lo, hi)`，或 `max(lo, min(hi, x))`；
+  不要手写两个 `min` / `max` —— 它们看起来对称，其实一个管下界一个管上界，最容易写反。
+  ② **写"区间"函数先做量纲检查**：拿一个边界外的数值当输入，结果被夹到 0 / 1 就是 bug。
+  ③ 边界参数一律按开区间校验（`0 < confidence < 1`），并用 `np.isnan` 兜住参数异常产生的 nan。
+  ④ 记住 `min` / `max` **不传播 nan、结果还取决于参数顺序**（`min(0.0, nan)` → `0.0`、
+  `min(nan, 0.0)` → `nan`）—— "夹一下"就能把 nan 悄悄换成边界值。
+- 首次：2026-10-03｜复发：0
+
+### 16. 同一段入口转换抄了 N 遍，还当它是"本项目的写法"
+
+- 现象：`normalize` / `standardize` / `log_transform` / `zscore` / `confidence_interval` / `t_test`
+  六个函数各自抄了同一段 5~8 行：白名单 `isinstance` → `is_df` / `is_series` → 抓 `columns` / `index`
+  → `np.asarray`。这类判断一度散在 **5 个文件 31 处**。抄到第三遍时已经不觉得是重复了，
+  反而觉得"这就是本项目的入参写法"。
+- 为什么会错：重复代码每次只多 3~5 行，看着不痛；但每多一处就多一次**口径分叉**的机会 ——
+  而且真的分叉了：`normalize` 拿整表 `np.asarray`（遇文本列直接抛）、`zscore` 用 `select_dtypes`
+  只取数值列、`confidence_interval` 还多一个 `.ravel()`。同一件事三种口径，出 bug 时你还得先判断
+  "这是哪个副本的行为"。
+- 以后怎么防：① 同一段入参处理**抄到第 2 遍**就该抽，别等第 3 遍；
+  ② 抽之前先问一句"输出的形状是不是和输入一样"——**入口能统一、出口不能一刀切**
+  （`describe` / `correlation_*` 的输出天生不同形，硬套还原会重演第 14 条）；
+  ③ 抽出来的函数只干**一件事**：把容器转成数组、并告诉调用方原来是什么。
+  选列 / 摊平 / 删缺失这些是**语义**，必须留在各函数里（否则重演第 15 条与 `paired=True` 的 NaN 错位）。
+- 首次：2026-10-03｜复发：0
+
+### 17. `hasattr(f, "__name__")` 判断"是不是具名函数"—— lambda 也有 `__name__`
+
+- 现象：`bootstrap_ci` 想给 `metrics["statistic_name"]` 一个名字，写成了
+  `statistic.__name__ if hasattr(statistic, '__name__') else "custom"`。
+  本意是"认得的内置统计量给名字、自定义的标 custom"，实际传 lambda 时得到的是
+  **字符串 `"<lambda>"`** —— 因为 lambda 有 `__name__`，只是值恒为 `"<lambda>"`。
+  也就是说 `else` 那支**几乎永远走不到**，是死代码。
+- 为什么会错：`__name__` 在脑子里等于"函数的名字"，于是 `hasattr` 就等于"这是个函数"。
+  实际上 `__name__` 是**属性存在性**，不是"名字有意义"：lambda、`functools.partial` 包过的函数、
+  `numpy` 的 ufunc（`np.mean.__name__` 是 `"mean"`，能过）各有各的情况，
+  真正拿不到的只有**没有 `__name__` 的可调用对象**（比如带 `__call__` 的类实例）。
+  同类陷阱还有 `hasattr(x, "__len__")` 判容器（`str` 也有）、`hasattr(x, "__iter__")` 判列表。
+- 以后怎么防：① 判"是不是我想要的那类函数"，用**显式白名单**（`if statistic in [np.mean, np.median, ...]`），
+  别用属性存在性推断语义；② 真要取名字就写成
+  `name = getattr(f, "__name__", None)` 再判断 `name in (None, "<lambda>")`，
+  把"没有名字"和"名字是占位符"两种情况都覆盖；③ 每个 `else`/兜底分支都问一句
+  "**这条到底测得到吗**"——走不到的分支就是 bug 伪装成的防御性代码。
+- 首次：2026-10-03｜复发：0
+
+### 18. 入口校验"想起什么写什么"，没有照着清单逐条过
+
+- 现象：`monte_carlo` 的入口只写了"n 是整数、n 为正"，没写"那 `n=True` / `n=np.int64` / `n=10.0` 各走哪条"。
+  结果 `np.int64(1000)` 被误拒、`n=True` 被放行、浮点 `n` 报的是 `ValueError` 而不是 `TypeError`。
+  §4.7 那张判断顺序表早就写死了，写代码时一次都没翻。
+- 为什么会错：校验是"防御性代码"，写的时候满脑子是主路径（"次数当然是整数"），
+  **不会自然想到 `True`、`np.int64`、`None`、0 这些"合法类型里的例外值"**。
+  清单存在的意义正是替代这种直觉——但清单要主动去查才有用；不查就等于没有。
+  同类：第 1 条（只写 `int`）、第 7 条（守卫子句的位置）、`random_state=None` 绕开 `get_rng`（决策 46）。
+- 以后怎么防：每个公开函数写完，把 §4.7 的表当 checklist **逐行过一遍**
+  （int + np.integer / bool 排在 int 前 / float + np.floating / 数组先 `np.asarray`），
+  再用三个探针各打一枪：`f(x=np.int64(1))`、`f(x=True)`、`f(x=1.0)`。
+  **这一步是本人的活**（决策 49）：要不要放宽、报什么错、算不算合法，都是取舍，不是机械活。
+- 复发（2026-10-05）：`random_walk` 的 `n_steps = 2.5` / `n_steps = True` 又都走 `ValueError("必须是正整数")` ——
+  同模块的 `monte_carlo` 早就是"类型不对 `TypeError`、取值不对 `ValueError`"。表就在那儿，还是没翻。
+- 首次：2026-10-04｜复发：**1（2026-10-05）**
+
+### 19. 只想着主路径上的那种值，忘了同一位置还会出现别的类型 / 值
+
+- 现象：`monte_carlo` 的 `simulator` 返回**布尔**数组（"事件是否发生"，MC 最常见的用法）时，
+  `np.asarray(...)` 原样保留 bool，`np.std` 在 numpy 2 上直接抛
+  `numpy boolean subtract ... is not supported`，整个函数判失败；字符串结果则给出
+  "ufunc isnan not supported"这种看不懂的话。同一轮还漏了：结果里含一个 NaN 时 8 个指标全 NaN 却报 `success=True`。
+- 为什么会错：写的时候脑子里只有"年收益 = 浮点数"这一种结果，
+  "0/1 事件"、"NaN"、"长度对不上"都不在主路径上。而**这个函数恰恰是这几类输入的高发区**
+  （事件概率、模型发散、批量大小写错），所以它们不是边角料，是常规用法。
+- 以后怎么防：写完一个"吃调用方数组"的函数，除了主路径，按五类各跑一次：
+  **布尔 / 整数 / 含 NaN / 全相同（常量）/ 长度不对**。
+  类型归一化放在**入口一处**做（`np.asarray(x, dtype=float)`），后面所有指标就都安全了——
+  这正是 §4.7 表最后一行与 §4.8 存在的理由。
+- 首次：2026-10-04｜复发：0
+
+### 20. "不简单"的最早信号：同一个信息要在调用方写两遍
+
+- 现象：第一版 `monte_carlo` 的契约是 `sampler(rng, **kwargs)`，但采样器**拿不到 n**，
+  于是调用方必须写 `n=1000, size=1000` —— 同一个数写两遍，还要靠 `len(data) != n` 事后兜底。
+  改成实现自己传 `sampler(rng, size=n, **kwargs)` 之后，调用方只写 `n=1000`。
+  同一处的后遗症：`**kwargs` 里再传 `size` 会撞成 `got multiple values for keyword argument`。
+- 为什么会错：设计签名时只想着"参数全靠 `**kwargs` 透传"这一条好处（灵活），
+  没数"调用方为了让它跑起来还得额外写什么"。
+  **重复的那一个数是症状，不是问题**：真正的问题是"批量大小"这个信息在接口里**没有归属**。
+- 以后怎么防：写完签名，立刻写出**最小调用示例**，然后数两件事：
+  ① 有没有哪个信息写了两遍；② 有没有哪一步"只有我知道"。有 → 把它吸收进实现，而不是写进文档。
+  简单 ≠ 参数少，而是**调用方不用重复表达**。
+- 首次：2026-10-04｜复发：0
+
+### 21. 把数学公式抄进代码时，`^` 当成乘方 —— 还被 `except` 吞成 `success=False`
+
+- 现象：`monte_carlo_probability` 的 Wilson 区间里写 `z_score^2 / n`。Python 的 `^` 是**按位异或**，
+  对 `np.float64` 直接抛 `TypeError: ufunc 'bitwise_xor' not supported`；因为整段计算在
+  `try/except Exception` 里，对外只表现为 `success=False` + 一句 message ——
+  最后是 6 条测试全红（`KeyError: 'ci_high'`）才把它挖出来。
+- 为什么会错：纸上的 `z²`、`x²` 抄进代码时手会自动敲 `^`（数学记号、Excel、LaTeX 都是这个符号），
+  而 Python 的乘方是 `**`。更险的是 `^` 在**整数**上是合法异或：`3^2` 得到 1、不报错，只算错。
+  第二层原因是 `try/except Exception` 把"代码写错"和"数据不合法"混成一个出口，
+  错误现场（哪一行、哪个异常）被压成一句字符串，静态检查也看不见（pyright 当时 0 error）。
+- 以后怎么防：① 公式里的幂一律写 `**`（或 `np.power`），见到 `^` 就当 bug 处理；
+  ② 新函数写完先**手动跑一次正常输入**，`success` 必须是 `True` —— 这条一跑就现形；
+  ③ 给算法配一条**独立实现的对照测试**（Wilson 对 `statsmodels.proportion_confint(method="wilson")`），
+  这类"公式抄错"会被直接钉死；④ 记住 `except Exception` 越宽，错误越难看见。
+- 首次：2026-10-05｜复发：0
+
+### 22. 失败结果的 `message` 被包装层无条件覆盖 —— 对外永远报"成功"
+
+- 现象：`monte_carlo_integral` 里内层 `monte_carlo` 已经返回 `success=False`（`func` 返回了标量），
+  但包装层接着无条件执行 `result.message = "蒙特卡洛多重积分成功：…"`。对外就是 `success=False` + 一句"成功"文案。
+- 为什么会错：把 `result` 当成"自己的返回值"直接美化，忘了它是**可能失败**的通道。
+  `success` 和 `message` 是同一份状态的两个视图，分开写就一定有机会不一致 —— 与第 12 条（后面的 `if` 静默覆盖前面的）同源。
+- 以后怎么防：包装函数里只改"成功才会有意义"的字段（`name` / `params` / `metrics`），改 `message` 一律包在
+  `if result.success:` 里；或者只**追加**、不覆盖。写完先跑一次**注定失败**的输入，看对外那两个字段是否自洽。
+- 首次：2026-10-05｜复发：0
+
+### 23. 体积/宽度这种"看着总为正"的量也会减反，维度奇偶还会把符号错误藏住
+
+- 现象：多重积分里体积写成 `wights = lows - highs`（名字打错 + 减反）。奇数维（1D、3D）估计值全为负、
+  而 **2D 看起来完全正常**（`∫∫ x·y` 得 +0.2499，正确值 0.25）—— 两个负号相乘抵消，把错误藏住了。
+- 为什么会错：① "上界减下界"被顺手写成了"参数顺序相减"，而变量名 `wights` 又不像 `lows` / `highs` 那样自带方向提示；
+  ② 验算时只挑了一个二维例子（乘法的对称性恰好掩盖了符号），**维度是奇是偶没进脑子**。
+  同源教训见第 19 条（只想着主路径那种值）。
+- 以后怎么防：长度/宽度/体积一律写 `high - low`，并在心里念一遍"大的减小的"；
+  验算**至少各挑一个奇数维和一个偶数维**（1D + 3D 都能一秒现形）；
+  拿到 `mean` 之后先跟解析值比**符号**，再看数值大小。
+- 首次：2026-10-05｜复发：0
+
+### 24. 默认参数路径从没被执行过 —— 默认采样器用了库不接受的参数
+
+- 现象：`random_walk` 的默认步长采样器写 `rng.integers(0, 2, size=size, dtype=float)`。numpy 的 `Generator.integers`
+  **不收浮点 dtype**（`TypeError: Unsupported dtype dtype('float64') for integers`），于是 `random_walk(100, 5)`
+  这种最普通的调用 100% 返回 `success=False`、`data=None`；连 docstring 里那条 `>>> r.data.shape (5, 101)` 都跑不通。
+- 为什么会错：写的时候验的是**自定义采样器**那条分支，默认分支（`step_sampler is None`）一次都没执行过；
+  更巧的是 `try/except Exception` 把它压成了一句 message，看起来像"输入不合法"而不是"代码写错了"。
+  与第 21 条同源：**错误现场被 `except` 藏起来**，静态检查（pyright）也看不见。
+- 以后怎么防：新函数写完，**第一个跑的就是"什么参数都不填的默认调用"**，`success` 必须是 `True`；
+  再把 docstring 的 Examples 真执行一遍（它们是最便宜的一组冒烟测试）。
+  凡是用到"库函数 + 一串可选参数"的地方，别凭记忆写，跑一次看它收不收。
+- 首次：2026-10-05｜复发：0
+
+### 25. 两个维度恰好相等时，转置的形状检查会静默通过
+
+- 现象：`random_walk` 把 `size=(n_paths, n_steps)` 交给 `step_sampler`，但没校验它返回的形状。
+  实测一个返回**转置**形状 `(n_steps, n_paths)` 的采样器：`n_paths=6, n_steps=4` 时报错（好事），
+  而 `n_paths=n_steps=5` 时 `success=True`、`data` 形状 `(5, 6)` 也"对"—— 里面的路径却是转置过来的，**静默错**。
+- 为什么会错：形状检查依赖"两个维度不相等"这个前提才生效；`cumsum(axis=1)` + 赋值广播在方阵上完全合法。
+  验算时只挑了一组 `n_paths == n_steps` 的参数，正好落在唯一发现不了的那个点上。
+  与第 23 条同一个思路的不同侧面：**对称/相等会把错误藏起来**。
+- 以后怎么防：验算参数**把两个维度取成不同值**（`n_paths=3, n_steps=100` 这种），别用正方形；
+  对外部传进来的批量数组显式校验 `shape == (n, d)`，别指望后面的运算替你把关。
+- 首次：2026-10-05｜复发：0
+
+
+
+### 26. `except` 用到的变量在 `try` 里才赋值 —— 每条失败路径都炸
+
+- 现象：`random_walk` 把 `call_params = {...}` 写在 `try:` 里面，但 `except` 分支要 `params=call_params`。
+  于是**每一个失败路径**都变成 `UnboundLocalError: cannot access local variable 'call_params' where it is not associated with a value`
+  —— 实测 5 种失败输入（形状不对 / 增量含 NaN / 采样器抛异常 / `start` 非数值 / 返回 1-D 数组）**5 个全中**，
+  本该返回 `success=False` 的 `Result`，变成了把异常直接抛给调用方。
+- 为什么会错：写的时候脑子里只过"成功路径"，`except` 是照上一版的结构留下来的；
+  **异常分支只有真抛异常才会执行**，正常跑一遍、ruff、pyright 全都看不见（当时两个都 0 error）。
+  与第 24 条（默认路径没跑过）是同一类：**分支覆盖靠"我以为"，不靠执行**。
+  还有一层：`params` 里那几个值（`n_steps` / `n_paths` / `start` / `random_state`）在 `try` 之前就已经定了，
+  它们本来就**不属于**"可能失败的计算"，放进去纯属位置错误。
+- 以后怎么防：① 写 `except` 时，逐个变量问"它是在 `try` 里才被赋值的吗"——**失败的返回要在 `try` 之前准备好**；
+  ② 每写一个 `try`，必须配一个**注定失败**的用例（`assert r.success is False`），专门喂 `except` 分支；
+  ③ 包装层的失败结果也要带 `params`，出问题才追得回去。
+- 首次：2026-10-05｜复发：0
+
+### 27. 入口按类型分成两条路，两条路的校验口径互相矛盾
+
+- 现象：`markov_simulate` 的 `initial` 用 `isinstance(initial, int)` 分流。标量那条按**路径数**铺满
+  （`np.full(n_paths, initial)`），数组那条却按**状态数**校验（`len(initial) != s` 报错），
+  而真正写进去的是 `paths[:, 0] = current_states`，长度要等于**路径数**。于是"数组 + `n_paths != s`"
+  这条组合永远跑不通；`n_paths == s` 时又能跑通 —— **同一个入口，两个维度各管一半**。
+  实测 `initial=[0.5, 0.5], n_paths=5` 直接在 `try` 外抛 `ValueError`（本该 `success=False`）。
+- 为什么会错：写校验时是"顺着刚写完的那一行"补的 —— 标量分支当年是为了铺满路径，数组分支是照着"转移矩阵的状态数"
+  顺手写的，两边各自看着都对。**没有回到参数本身的语义上问一句"它到底是按谁计数"**。
+  同族：`np.int64(0)` 掉进数组分支（`isinstance` 只写了 `int`，易错点 1）、`True` 被当状态 1 静默放行。
+- 以后怎么防：① 一个参数有多条类型分支时，**把每条分支的"计数维度"写在一张纸上**（按路径数？按状态数？按列数？），
+  对不上就说明口径没定清，**先定语义再写代码**；② 分流用的 `isinstance` 必须把 `np.integer` / `bool` 一起想到（易错点 1）；
+  ③ 任何"写进结果数组"的赋值，问一遍"它的长度约束和上面校验用的是同一个下标维度吗"。
+- 首次：2026-10-05｜复发：0
+
+### 28. 数值阈值参数的两个漏网：`bool` 和 NaN
+
+- 现象：`markov_steady_state` 的 `tol` 只写了 `if not isinstance(tol, (int, float)) or tol <= 0`。
+  `tol=True` → `isinstance(True, int)` 为真、`True > 0` 也为真 → 阈值变成 `1`，
+  **第 1 次迭代就"收敛"**，返回 `[0.55, 0.45]` 这种假答案，而且 `success=True, converged=True`。
+  `tol=np.nan` → `nan <= 0` 为假 → 穿过校验 → 白跑满 `max_iter` 次迭代。
+  同一个函数里 `max_iter` 查了 `bool`、`tol` 没查 —— 说明是**逐条手动补的**，不是照着清单过的。
+- 为什么会错：脑子里"阈值 = 一个正数"，于是校验只写"是数 & 大于 0"；而 `bool` 是 `int` 的子类、
+  NaN 与任何数比较都是 `False`，这两条都恰好从"是数 & 大于 0"里漏出去。**与易错点 1 同根**，
+  只是这次漏的是"比较"而不是"类型判断"。
+- 同族（同一轮发现的）：只校验"转移矩阵行和 = 1.0"就以为矩阵合法 —— `[[1.5, -0.5], [0, 1]]` 行和也是 1.0，
+  但含负元素，迭代时 `v` 指数发散、最后 `data=[nan, nan]` 却 `success=True`。
+  **"行和 = 1"不等于"是概率矩阵"**，还要 `arr >= 0`。另外这类溢出会抛 `RuntimeWarning`，
+  而本项目 `filterwarnings = ["error::RuntimeWarning"]` —— **测试会直接报错**，别指望测试能兜住静默错。
+- 以后怎么防：① 校验数值阈值时，脑子里过一遍"三件套"：**类型（含 `bool` / `np.integer` 例外）、
+  有限性（`np.isfinite`，挡 NaN / inf）、取值区间**；② 同一函数里同类参数（`max_iter` / `tol` / `n` / `tol`）
+  用**同一套模板**写，别一个查 `bool` 一个不查；③ 校验"概率/权重"这类输入时，除了和为 1，还要问一句"有没有可能是负数/NaN"。
+- 首次：2026-10-09｜复发：0
+
+### 29. 同一个校验里的两把尺子：一个宽容、一个精确
+
+- 现象：`markov_simulate` / `markov_steady_state` 校验转移矩阵时有两条：
+  `if not np.allclose(arr.sum(axis=1), 1.0)`（**宽容**，默认 `atol=1e-8`）和 `if np.any(arr < 0)`（**精确**）。
+  实测 `[[1.0, -1e-16], [0.5, 0.5]]`：行和都是 1.0，但左边那行有个 `-1e-16` 的归一化残渣 →
+  被判"含负元素"直接报错。**这个矩阵在数学上没问题，是校验太严**。
+- 为什么会错：两条校验是分两次、照着不同念头写的 —— 行和那条想着"浮点比较不能写 `==`"，
+  非负那条想着"概率怎么能为负"。各自都对，**放在一起就成了一严一宽**。建模时矩阵常常是
+  `df / df.sum()` 归一化出来的，这类 `-1e-17` 残渣非常常见，比赛现场会直接卡住。
+- 同族（同一轮里一起犯的）：① 边界比较与文档口径不一致 —— `mm1_metrics` 写 `service_rate < arrival_rate`，
+  而 docstring 与测试都写 `λ >= μ` 不稳定，于是 `λ == μ` 掉进正常计算分支、`rho = 1` →
+  `ZeroDivisionError`（结果碰巧对，message 却是"计算失败：ZeroDivisionError"）；
+  ② 一批报错文案是复制粘贴的，**参数名忘了改** —— 同一轮里 `max_iter` 的文案写 "tol"、
+  `service_rate` 的两条文案也都写 "tol"。两条都是"看着像对的、跑起来也行、但口径/文案是错的"。
+- 以后怎么防：① 同一个量的多条校验，**先把容差定下来再写**（要么都用 `np.allclose` / 小 `eps`，要么都精确），
+  写完回头对一眼"这几条的严格程度一致吗"；② 阈值类比较（`<` / `<=`）**对着 docstring 读一遍**，
+  特别是 == 落在哪边；③ 复制粘贴报错文案时，逐个把参数名念出来。
+- 首次：2026-10-09｜复发：0
+
+### 30. 改了口径（返回值 / 键名 / 分支），下游三处会同时过期
+
+- 现象：`markov_simulate` 这一轮把 `metrics` 从 `std_terminal` 换成 `terminal_distribution`、
+  `mm1_metrics` 的不稳定分支从 `metrics={}` 变成 `metrics={"rho"}`、`arrival_rate=0` 从"报错"变成"合法"。
+  代码本身没问题，但**同一轮的测试 5 条全红**（都在断言旧键名 / 旧分支），docstring 的 `Returns` 也还在写 `std_terminal`。
+- 为什么会错：改的时候注意力全在"新行为对不对"，**看不见的契约**（测试断言、docstring、STATUS 的口径表）没人提醒你。
+  这三处过期不会报错，只会"文档说 A、代码做 B"，过几天自己都分不清哪个是准的。
+- 以后怎么防：① 动返回值 / 键名 / 分支前，先 `rg` 一下这个名字在全仓的出现位置（`rg "std_terminal" `），
+  把"要一起改的地方"列出来再动手；② 改完立刻跑 `pytest` —— 红的测试就是"过期契约"的清单；
+  ③ docstring 的 `Returns` / `Raises` 属于**契约的一部分**，和代码同一次改完，别留到"下次顺手"。
+- 首次：2026-10-10｜复发：0
+
+### 31. 公式里的"基准量"抄错了对象，而且完美拟合会把错掩盖掉（R² 的 SS_tot）
+
+- 现象：`models/metrics.py` 写 `ss_tol = np.sum((yt - np.mean(yp)) ** 2)` —— 分母的基准该是 `y_true` 的均值，
+  写成 `y_pred` 的均值了。实测（`y_true=[1,2,3,4,5]`、`y_pred=[1.5,2.5,2.5,4.5,5.5]`）：错版 **0.8803827751196172**，
+  正确版 **0.875** = `sklearn.metrics.r2_score`。**而 `r2_score(y, y)` 照样返回 1**，常量 y 那条照样报错 ——
+  两种最常见的测试输入都盖住了这个错。
+- 为什么会错：R² 的分子用 `y_pred`、分母用 `y_true` 的均值，两个变量名只差一个字母（`yt` / `yp`），
+  是从同一个表达式复制过来的。这种错"看起来像对、跑起来不报错、只有对着数据才露馅"。
+- 以后怎么防：① 写完公式**逐个念一遍每个量的"是谁的"**（这个均值是 `y_true` 的还是 `y_pred` 的？）；
+  ② 指标类函数至少测一条**非完美拟合**的数据（完美拟合 / 常量 / 全 0 都是"天然掩盖 bug"的输入）；
+  ③ 拿成熟库当**独立参照物**（`sklearn.metrics.r2_score`、`scipy.stats`），别自己算自己；
+  ④ 变量名别用 `ss_tol`（无意义），写 `ss_tot`（total sum of squares）—— 名字说得清，错法就少一半。
+- 首次：2026-10-10｜复发：0
+
+### 32. `np.where` 的掩码防不住零除（两条分支都会被求值）
+
+- 现象：`smape` 写 `np.where(denom == 0, 0.0, 2 * |yt - yp| / denom)`。分母为 0 时**数值结果是对的**（记 0），
+  但 `RuntimeWarning: invalid value encountered in divide` 仍会漏出来；本项目 `pyproject.toml` 开了
+  `filterwarnings = ["error::RuntimeWarning"]`，于是任何"含 0 的 smape"测试**直接判失败**。
+- 为什么会错：`np.where` 是"**先把两条分支都算好，再按掩码挑**"，不是 `if / else` 的短路求值。
+  "结果对" 和 "没有副作用" 是两件事，告警就是那个副作用。
+- 以后怎么防：① 除法一律写 `np.divide(a, b, out=..., where=掩码)`（或临时 `with np.errstate(invalid="ignore")`），
+  不要拿 `np.where` 当挡箭牌；② 写完拿最脏的输入跑一遍（全 0、单个点、常量列），**盯着 warning 看**；
+  ③ 项目开了 warning-as-error 时，"不告警"就是契约的一部分，要有一条测试专门钉住它。
+- 首次：2026-10-10｜复发：0
+
+### 33. 长报错文案拆行时少一个引号 / 多一个逗号（`ruff` 一秒能抓，别等运行时）
+
+- 现象：两条都在同一轮里写出来 —— ① `raise TypeError(` 下面的长中文 f-string 拆成两行，第一行**忘写结尾引号**，
+  Python 直接 `SyntaxError: unterminated f-string literal`（`ruff` 报 `invalid-syntax`，`import` 也跑不了）；
+  ② `raise ValueError(
+    f"...",
+    "..."
+)` —— 想拼接两段文案却写成**两个参数**，
+  message 就成了元组的字符串 `('...', '...')`，看着像"报错文案有点怪"，很难一眼看出是参数个数的问题。
+- 为什么会错：中文文案长，按习惯拆行；`+` / 隐式拼接 / 逗号在编辑器里长得差不多。
+  这类错**不是逻辑错**，是"手滑"，但会在最不该花时间的地方浪费两分钟。
+- 以后怎么防：① 写完多行字符串，**立刻**跑一次 `ruff check`（或 `python -c "import ..."`）—— 语法错它必抓；
+  ② 相邻字符串字面量的隐式拼接**不要夹逗号**，要拼接就老老实实写 `+` 或一次写完；
+  ③ `Raises` 里放的不是长句而是"参数名 + 实际值"，本身就不用拆行。
+- 首次：2026-10-12｜复发：0

examples/01_clean_and_describe.py

@@ -0,0 +1,63 @@
+"""data + stats 最小用法：读 → 清 → 补 → 判离群 → 缩尾 → 描述。
+
+每一步都对应 `tests/test_data.py` 里的一条用例；体量刻意压到最小。
+`stats.describe` 收尾：行 = 指标、列 = 变量，可直接贴进论文。
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+import mcm_toolkit as mcm
+
+
+def main() -> None:
+    mcm.set_seed(20260101)
+
+    # 1) 假装这是从 Excel 导出的赛题数据：带文本列、带缺失、带两个录入错误
+    df = pd.DataFrame(
+        {
+            "city": ["A", "B", "C", "D", "E", "F"],
+            "gdp": [1000.0, 1100.0, np.nan, 1300.0, 1400.0, 9999.0],
+            "pop": [10.0, 11.0, np.nan, np.nan, 20.0, 15.0],
+            "notes": ["ok", "ok", np.nan, "ok", np.nan, "异常"],
+        }
+    )
+
+    with tempfile.TemporaryDirectory() as tmp:
+        path = Path(tmp) / "demo.csv"
+
+        # 2) 写盘再读回：load_table 按扩展名分派，.csv 会自动探测编码
+        mcm.data.save_table(df, path)
+        loaded = mcm.data.load_table(path)
+        print(f"读回 {loaded.shape[0]} 行 × {loaded.shape[1]} 列")
+
+        # 3) 缺失太多的行先删：缺失比例 > 0.5 的走人（4 列，阈值 0.5 -> 至少要 2 个非空）
+        kept = mcm.data.clean_missing(loaded, axis=0, threshold=0.5)
+        print(f"按缺失比例删行：{loaded.shape[0]} -> {kept.shape[0]}")
+
+        # 4) 剩下的缺失做填补。mean 只作用于数值列，notes 列原样保留缺失
+        filled = mcm.data.impute_missing(kept, method="mean")
+        print("填补后每列缺失数：", filled.isna().sum().to_dict())
+
+        # 5) 找离群点：只标不删，删不删由人决定
+        mask = mcm.data.detect_outliers(filled, method="iqr", k=1.5)
+        print("检出离群点：")
+        print(mask)
+        print(f"共 {int(mask.sum().sum())} 个；notes 列恒 False（非数值列不参与统计）")
+
+        # 6) 不删也能用：缩尾把极端值压到分位点上，而不是丢掉整行
+        w = mcm.data.winsorize(filled, lower=0.01, upper=0.99)
+        print(f"gdp 最大值 {filled['gdp'].max():.1f} -> 缩尾后 {w['gdp'].max():.1f}")
+
+    # 7) 描述统计：行 = 指标、列 = 变量，可直接贴进论文
+    table = mcm.stats.describe(filled[["gdp", "pop"]])
+    print(table.round(2))
+
+
+if __name__ == "__main__":
+    main()

examples/README.md

@@ -4,6 +4,9 @@
 
 > **当前状态**：这些脚本是**用法规格**，函数实现填好之前跑不通
 > （会抛 `NotImplementedError`）。实现顺序见 `docs/03-roadmap.md`。
+>
+> `00_quickstart.py` 与 `01_clean_and_describe.py` 用到的函数大多已实现，可以跑；
+> 两者末尾各有 `TODO(L0)`，等 `stats` / `viz` 补齐。
 
 | 文件 | 对应模块 | 覆盖的 L 档 |
 |---|---|---|

pyproject.toml

@@ -62,3 +62,10 @@ filterwarnings = ["error::RuntimeWarning"]
 [tool.pyright]
 include = ["src", "tests"]
 typeCheckingMode = "basic"
+# 不写 venvPath/venv 的话，pyright 会去 PATH 上找 python；本机 PATH 上的
+# python 是 agent-tools 的 shim（Codex 运行时，Python 3.14，没有 numpy/pandas），
+# 于是全部报 "无法解析导入 numpy/pandas"。指到工作区的 .venv 才稳定。
+venvPath = "."
+venv = ".venv"
+# 与两套环境一致（venv 3.13.9 / conda 3.13.15）；不写会跟着 PATH 上那个 3.14 走。
+pythonVersion = "3.13"

scripts/setup-venv.ps1

@@ -52,18 +52,29 @@ if (Test-Path -LiteralPath $venvDir) {
 }
 
 if (-not (Test-Path -LiteralPath $venvDir)) {
-    Write-Host '[1/3] creating .venv (--system-site-packages, reuses Anaconda base) ...'
+    Write-Host '[1/4] creating .venv (--system-site-packages, reuses Anaconda base) ...'
     & $Python -m venv --system-site-packages --prompt 'mcm-toolkit' $venvDir
     if ($LASTEXITCODE -ne 0) { throw 'venv creation failed' }
 }
 
 $venvPy = Join-Path $venvDir 'Scripts\python.exe'
+$venvSitePackages = Join-Path $venvDir 'Lib\site-packages'
 
-Write-Host '[2/3] editable install of mcm-toolkit (--no-deps --no-build-isolation) ...'
+Write-Host '[2/4] linking base site-packages for static analyzers (.pth) ...'
+# pyright / Pylance do NOT honour "include-system-site-packages" in pyvenv.cfg,
+# but they DO read *.pth files found in site-packages. Without this file they see
+# only .venv\Lib\site-packages (which holds just pip), so every "import numpy"
+# in the editor is reported as unresolved even though the interpreter is right.
+$baseSitePackages = (& $Python -c "import sysconfig; print(sysconfig.get_paths()['purelib'])").Trim()
+if (-not (Test-Path -LiteralPath $baseSitePackages)) { throw "base site-packages not found: $baseSitePackages" }
+Set-Content -LiteralPath (Join-Path $venvSitePackages '_mcm_base_site_packages.pth') -Value $baseSitePackages -Encoding ASCII
+Write-Host "    -> $baseSitePackages"
+
+Write-Host '[3/4] editable install of mcm-toolkit (--no-deps --no-build-isolation) ...'
 & $venvPy -m pip install -e $repoRoot --no-deps --no-build-isolation --disable-pip-version-check
 if ($LASTEXITCODE -ne 0) { throw 'pip install -e failed' }
 
-Write-Host '[3/3] verifying ...'
+Write-Host '[4/4] verifying ...'
 & $venvPy -c "import mcm_toolkit, numpy, scipy, pandas, matplotlib; print('mcm_toolkit', mcm_toolkit.__version__); print('numpy', numpy.__version__)"
 
 Write-Host ''

src/mcm_toolkit/core/__init__.py

@@ -1,4 +1,4 @@
-"""core —— 基础设施：结果对象、随机数、参数校验。
+"""core —— 基础设施：结果对象、随机数、参数校验与入口转换。
 
 其他所有包都依赖本包；本包**不**依赖任何其他子包。
 """
@@ -6,6 +6,7 @@
 from .random import get_rng, set_seed
 from .result import Result
 from .validate import (
+    as_array,
     check_array,
     check_probability,
     check_same_length,
@@ -14,6 +15,7 @@ from .validate import (
 
 __all__ = [
     "Result",
+    "as_array",
     "get_rng",
     "set_seed",
     "check_array",

src/mcm_toolkit/core/validate.py

@@ -1,33 +1,147 @@
-"""参数校验。
+"""参数校验与入口转换。
 
 目的不是"教用户用库"，而是**把错误提前到调用点**：
 比赛时最贵的是 debug 时间，一个 `ValueError: 数组长度不一致` 比
 十层 traceback 里的 `IndexError` 值钱得多。
+
+**所有收数值的函数都从 `as_array` 进**：它一次做完"类型白名单 + 转 ndarray + 告诉调用方原来是什么"，
+省掉每个函数各抄一遍 `isinstance(x, pd.DataFrame)` / `select_dtypes` / `np.asarray`。
 """
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Literal, cast
 
 import numpy as np
+import pandas as pd
 
 __all__ = [
+    "as_array",
     "check_array",
     "check_probability",
     "check_same_length",
     "check_square_matrix",
 ]
 
+ArrayKind = Literal["frame", "series", "array"]
+
+_INPUT_TYPES = (pd.DataFrame, pd.Series, np.ndarray, list, tuple, int, float)
+
+
+def as_array(
+    x: Any,
+    *,
+    numeric_only: bool = True,
+    dtype: Any = float,
+    ndim: int | None = None,
+) -> tuple[np.ndarray, ArrayKind]:
+    """统一入口：把入参收成 `ndarray`，并告诉调用方"原来是什么"。
+
+    Parameters
+    ----------
+    x:
+        `pandas.DataFrame` / `pandas.Series` / `numpy.ndarray` / `list` / `tuple`。
+        其余类型一律 `TypeError` —— 注意 `str` **也是可迭代对象**，白名单必须显式挡住，
+        否则 `"abc"` 会被当成三个字符悄悄算下去。
+    numeric_only:
+        默认 `True`：`DataFrame` **只取数值列**，非数值列自动跳过（一列都没有则 `ValueError`）。
+        走"元素级、输入输出同形"的函数（`normalize` / `standardize` / `log_transform`）
+        必须写 `numeric_only=False`：跳过列会让返回的表**少列**，与输入对不上；
+        输出是"一张数值结果表"的函数（`zscore` / `confidence_interval` / `t_test`）用默认值。
+        对 `Series` / 数组 / 列表无意义，自动忽略。
+    dtype:
+        目标 dtype，默认 `float`；传 `None` 表示保持原 dtype。
+    ndim:
+        期望维度，默认 `None` 表示**保持原样、绝不摊平**。
+        `1` 会**摊平**成一维（"一串样本"的函数如 `t_test` / `confidence_interval` 要显式写）；
+        `2` 只**校验**不重塑 —— 一维数据到底是"1 个样本"还是"1 个特征"没有唯一答案，不能替你猜。
+
+    Returns
+    -------
+    (numpy.ndarray, ArrayKind)
+        第二个元素是 `"frame"` / `"series"` / `"array"`，表示 `x` 原来是哪一类。
+        还原**故意不代做**，调用方自己手写（同一个函数不同形，没法一刀切）：
+
+        ```python
+        arr, kind = as_array(x, numeric_only=False)
+        ...                                              # 只写算法
+        if kind == "frame":
+            return pd.DataFrame(result, index=x.index, columns=x.columns)
+        if kind == "series":
+            return pd.Series(result, index=x.index, name=x.name)
+        return result
+        ```
+
+        `numeric_only=True` 时列名要用**同一份口径**：
+        `x.select_dtypes(include=[np.number]).columns`。
+
+    Raises
+    ------
+    TypeError
+        `x` 不在白名单里，或内容转不成 `dtype`。
+    ValueError
+        `numeric_only=True` 但 `DataFrame` 里一列数值都没有；`ndim` 不是 `None` / `1` / `2`；
+        `ndim=2` 但 `x` 不是二维。
+
+    Notes
+    -----
+    **本函数不删缺失值。** `DataFrame.corr` 是成对删、`describe` 是整列统计、
+    `paired=True` 的 t 检验必须**成对**删 —— 一旦在这里写 `arr[~isnan(arr)]`，
+    行与行的对应关系就永久丢了。删缺失是**语义**，交给各函数自己决定。
+
+    Examples
+    --------
+    >>> arr, kind = as_array(pd.DataFrame({"a": [1, 2], "city": ["X", "Y"]}))
+    >>> arr.shape, kind
+    ((2, 1), 'frame')
+    """
+    if isinstance(x, pd.DataFrame):
+        kind: ArrayKind = "frame"
+        source: Any = x
+        if numeric_only:
+            numeric_cols = x.select_dtypes(include=[np.number]).columns
+            if len(numeric_cols) == 0:
+                raise ValueError(f"x 里一列数值都没有，只有 {list(x.columns)}")
+            # x[Index] 在 pandas 存根里是 DataFrame | Series 重载，按运行时真值收窄（坑 8）
+            source = cast(pd.DataFrame, x[numeric_cols])
+    elif isinstance(x, pd.Series):
+        kind = "series"
+        source = x
+    elif isinstance(x, _INPUT_TYPES):
+        kind = "array"
+        source = x
+    else:
+        raise TypeError(
+            f"x 必须是 DataFrame / Series / ndarray / list / tuple，你传入了 {type(x).__name__}"
+        )
+
+    try:
+        arr = np.asarray(source, dtype=dtype)
+    except (ValueError, TypeError) as e:
+        raise TypeError(f"x 的内容转不成 {dtype} 数组：{e}") from None
+
+    if ndim is not None:
+        if ndim not in (1, 2):
+            raise ValueError(f"ndim 只能是 None / 1 / 2，你传入了 {ndim}")
+        if ndim == 1:
+            arr = arr.ravel()
+        elif arr.ndim != 2:
+            raise ValueError(f"ndim=2 要求二维输入，但 x 是 {arr.ndim} 维")
+
+    return arr, kind
+
 
 def check_array(x: Any, ndim: int | None = None, finite: bool = True) -> np.ndarray:
     """转成 ndarray 并做基本检查（维度、有限值）。
 
+    实现时应当复用 `as_array`（丢掉第二个返回值即可），不要重写一遍转换逻辑。
+
     Examples
     --------
     >>> check_array([1, 2, 3]).shape
     (3,)
     """
-    # TODO(L0)
+    # TODO(L1)
     raise NotImplementedError
 
 
@@ -38,17 +152,17 @@ def check_same_length(*arrays: Any) -> None:
     --------
     >>> check_same_length([1, 2], [3, 4])
     """
-    # TODO(L0)
+    # TODO(L1)
     raise NotImplementedError
 
 
 def check_probability(p: float) -> float:
     """检查 p 落在 [0, 1]，返回 float。"""
-    # TODO(L0)
+    # TODO(L1)
     raise NotImplementedError
 
 
 def check_square_matrix(a: Any) -> np.ndarray:
     """检查是方阵，返回 ndarray。AHP 判断矩阵、转移矩阵都要用。"""
-    # TODO(L0)
+    # TODO(L1)
     raise NotImplementedError

src/mcm_toolkit/data/clean.py

@@ -7,7 +7,11 @@
 
 from __future__ import annotations
 
-from typing import Any, Literal
+import math
+from typing import Any, Literal, cast
+
+import numpy as np
+import pandas as pd
 
 __all__ = ["clean_missing", "detect_outliers", "impute_missing", "winsorize"]
 
@@ -17,17 +21,49 @@ def clean_missing(data: Any, axis: int = 0, threshold: float | None = None) -> A
 
     Parameters
     ----------
+    data:
+        要清洗的表，必须是 `pandas.DataFrame`。
     axis:
-        0 = 按行删，1 = 按列删。
+        `0` = 按行删，`1` = 按列删。
     threshold:
-        缺失比例超过该值就删；`None` 表示只要有缺失就删。
+        缺失比例**超过**该值就删，取值 0–1；`None` 表示只要有缺失就删。
+
+    Returns
+    -------
+    pandas.DataFrame
+        清洗后的新表（不改原表）。
+
+    Raises
+    ------
+    TypeError
+        `data` 不是 `pandas.DataFrame`。
+    ValueError
+        `axis` 既不是 0 也不是 1。
 
     Examples
     --------
     >>> clean_missing(df, threshold=0.5)     # doctest: +SKIP
     """
-    # TODO(L0)
+    if axis == 0:
-    raise NotImplementedError
+        target_axis = 'index'
+    elif axis == 1:
+        target_axis = 'columns'
+    else:
+        raise ValueError(f"axis参数只能是 0 或 1,你传入了{axis}")
+
+    if not isinstance(data,pd.DataFrame):
+        raise TypeError(f"data必须是pandas DataFrame,你传入了{type(data)}")
+
+    if threshold is not None and not 0 <= threshold <= 1:
+        raise ValueError(f"threshold必须在0和1之间,你传入了{threshold}")
+
+    if threshold is None:
+        return data.dropna(axis=target_axis,how='any')
+
+    total_len = data.shape[1 -axis]
+    min_non_na = math.ceil(total_len * (1 - threshold))
+
+    return data.dropna(axis=target_axis,thresh=min_non_na)
 
 
 def impute_missing(data: Any, method: str = "mean", **kwargs: Any) -> Any:
@@ -35,16 +71,56 @@ def impute_missing(data: Any, method: str = "mean", **kwargs: Any) -> Any:
 
     Parameters
     ----------
+    data:
+        要填补的表，必须是 `pandas.DataFrame`。
     method:
-        `"mean"` / `"median"` / `"mode"` / `"ffill"` / `"interpolate"` / `"knn"`。
+        `"mean"` / `"median"` / `"mode"` / `"ffill"` / `"interpolate"`。
+    **kwargs:
+        原样转交给底层的 `fillna` / `ffill` / `interpolate`。
+
+    Returns
+    -------
+    pandas.DataFrame
+        填补后的表。
+
+    Raises
+    ------
+    TypeError
+        `data` 不是 `pandas.DataFrame`。
+    ValueError
+        `method` 不在支持列表里（报错信息会列出全部支持的方法）。
 
     Notes
     -----
     论文里必须说明用了哪种填补、为什么。填 `mean` 之前先想一下
     "这个缺失是不是非随机缺失（MNAR）"，否则结论可能被填补方式带偏。
     """
-    # TODO(L0)
+    if not isinstance(data,pd.DataFrame):
-    raise NotImplementedError
+        raise TypeError(f"data必须是pandas DataFrame,你传入了{type(data)}")
+
+    supported_method = ['mean','median','mode','ffill','interpolate']
+    if method not in supported_method:
+        raise ValueError(f"不支持的填补方式:{method},仅支持:{supported_method}")
+
+    # 上面已校验 method 合法，所以每条 return 之后不必再写 elif；
+    # 最后一行无条件 return 兜住仅剩的 interpolate，函数就没有"隐式返回 None"的路径了。
+    if method == 'mean':
+        return data.fillna(data.mean(numeric_only=True),**kwargs)
+    if method == 'median':
+        return data.fillna(data.median(numeric_only=True),**kwargs)
+    if method == 'mode':
+        # 只有这一支要逐列赋值，所以在这里单独复制一份，别就地改调用方的表
+        # （其余四支走 fillna / ffill / interpolate，本来就返回新对象）。
+        result = data.copy()
+        mode_df = result.mode()
+        for col in result.columns:
+            if mode_df[col].empty:
+                continue
+            result[col] = result[col].fillna(mode_df[col].iloc[0])
+        return result
+    if method == 'ffill':
+        return data.ffill(**kwargs)
+    return data.interpolate(**kwargs)
 
 
 def detect_outliers(data: Any, method: Literal["iqr", "zscore"] = "iqr", **kwargs: Any) -> Any:
@@ -52,30 +128,139 @@ def detect_outliers(data: Any, method: Literal["iqr", "zscore"] = "iqr", **kwarg
 
     Parameters
     ----------
+    data:
+        `pandas.DataFrame` / `pandas.Series`，或 `list` / `tuple` / `numpy.ndarray`。
     method:
         `"iqr"`：Q1-1.5·IQR 之外（`k` 可调，默认 1.5）；
         `"zscore"`：|z| > threshold（默认 3.0）。
+    **kwargs:
+        给对应方法用的参数：`k` 只对 `"iqr"` 生效，`threshold` 只对 `"zscore"` 生效。
 
     Returns
     -------
     与原数据同形的布尔 DataFrame/ndarray，`True` 表示该点是离群点。
 
+    Raises
+    ------
+    TypeError
+        `data` 既不是 `pandas.DataFrame` / `pandas.Series`，也不是 `list` / `tuple` / `numpy.ndarray`。
+    ValueError
+        `method` 既不是 `"iqr"` 也不是 `"zscore"`。
+
     Notes
     -----
     **只标不删**是刻意的：删点是有代价的判断，必须由人来做，
     并且要在论文里写清楚删了几个、依据是什么。
 
+    非数值列**不参与统计**，掩码里恒为 `False`：均值和分位数对文本没有意义，
+    但"这一列没有离群点"比"整张表算不出来"有用得多。
+
     Examples
     --------
     >>> mask = detect_outliers([1, 2, 3, 4, 100], method="iqr")
     >>> bool(mask[-1])
     True
     """
-    # TODO(L0)  ★ S 档：配完整函数卡片
+    if not isinstance(data, (pd.DataFrame, pd.Series, list, tuple, np.ndarray)):
-    raise NotImplementedError
+        raise TypeError(f"data必须是pandas DataFrame/Series 或数组型,你传入了{type(data)}")
+
+    is_series = isinstance(data, pd.Series)
+    is_ld_array = isinstance(data, (list, tuple, np.ndarray)) and np.array(data).ndim == 1
+
+    if isinstance(data,pd.Series):
+        data = data.to_frame()
+    elif not isinstance(data,pd.DataFrame):
+        data = pd.DataFrame(data)
+
+    if method == 'iqr':
+        k = kwargs.get("k", 1.5)
+    elif method == 'zscore':
+        threshold = kwargs.get("threshold", 3.0)
+    else:
+        raise ValueError(f"不支持的方法:{method},仅支持'iqr'或'zscore'")
+
+    numeric_cols = data.select_dtypes(include=['number']).columns
+    mask = pd.DataFrame(False,index=data.index,columns=data.columns)
+    # 取列子表得到的一定是 DataFrame，但 pandas 的类型存根只声明了「Hashable -> Series」，
+    # pyright 于是把 numeric 当成 Series，再把 `.std()` 的返回当成标量、判 `.replace` 非法。
+    # 这里按运行时的真值显式收窄，让下面几行继续参与类型检查。
+    numeric = cast(pd.DataFrame, data[numeric_cols])
+
+    if method == 'iqr':
+        Q1 = numeric.quantile(0.25)
+        Q3 = numeric.quantile(0.75)
+        IQR = Q3 - Q1
+        lower_bound = Q1 - k * IQR
+        upper_bound = Q3 + k * IQR
+
+        mask[numeric_cols] = (numeric < lower_bound) | (numeric > upper_bound)
+
+    elif method == 'zscore':
+        mean = numeric.mean()
+        std = numeric.std()
+
+        std = std.replace(0, np.nan)
+        z_scores = (numeric - mean) / std
+        mask[numeric_cols] = z_scores.abs() > threshold
+
+    if is_series:
+        return mask.iloc[:,0]
+    if is_ld_array:
+        return mask.values.flatten()
+
+    return mask
 
 
 def winsorize(data: Any, lower: float = 0.01, upper: float = 0.99) -> Any:
-    """缩尾：把超出分位数的值压到分位点，而不是删除。"""
+    """缩尾：把超出分位数的值压到分位点，而不是删除。
-    # TODO(L1)
+
-    raise NotImplementedError
+    Parameters
+    ----------
+    data:
+        `pandas.DataFrame` 或 `pandas.Series`。
+    lower:
+        下分位点，默认 0.01（1%）。
+    upper:
+        上分位点，默认 0.99（99%）。
+
+    Returns
+    -------
+    pandas.DataFrame | pandas.Series
+        与输入同类型，超出分位点的值被压到分位点上。
+
+    Raises
+    ------
+    TypeError
+        `data` 既不是 `pandas.DataFrame` 也不是 `pandas.Series`。
+    ValueError
+        分位数不满足 `0 < lower < upper < 1`。
+    """
+    if not isinstance(data, (pd.DataFrame, pd.Series)):
+        raise TypeError(f"data必须是pandas DataFrame 或 Series,你传入了{type(data)}")
+
+    if not (0 < lower < upper < 1):
+        raise ValueError(f"分位数必须满足0 < lower < upper < 1,你传入了lower={lower},upper={upper}")
+
+    if isinstance(data,pd.Series):
+        if not pd.api.types.is_numeric_dtype(data):
+            return data.copy()
+        lower_val = data.quantile(lower)
+        upper_val = data.quantile(upper)
+        return data.clip(lower=float(lower_val),upper=float(upper_val))
+
+    numeric_cols = data.select_dtypes(include=['number']).columns
+    if len(numeric_cols) == 0:
+        return data.copy()
+
+    lower_bounds = data[numeric_cols].quantile(lower)
+    upper_bounds = data[numeric_cols].quantile(upper)
+
+    result = data.copy()
+
+    result[numeric_cols] = result[numeric_cols].clip(
+        lower=lower_bounds,
+        upper=upper_bounds,
+        axis=1
+    )
+
+    return result

src/mcm_toolkit/data/io.py

@@ -15,7 +15,7 @@ import pandas as pd
 __all__ = ["load_table", "save_table"]
 
 
-def load_table(path: str | Path, **kwargs: Any) -> Any:
+def load_table(path: str | Path, **kwargs: Any) -> pd.DataFrame:
     """按扩展名自动选择读取方式，返回 DataFrame。
 
     约定：
@@ -24,6 +24,27 @@ def load_table(path: str | Path, **kwargs: Any) -> Any:
     * `.xlsx` / `.xls` 需要 `openpyxl`（`pip install "mcm-toolkit[excel]"`）；
     * `na_values` 默认包含空串、`"NA"`、`"N/A"`、`"#N/A"`、`"null"`、`"-"`。
 
+    Parameters
+    ----------
+    path:
+        文件路径。扩展名决定用哪个读取器，大小写不敏感。
+    **kwargs:
+        原样转交给 `pandas.read_csv` / `pandas.read_excel`。
+        `.csv` 传了 `encoding=` 就照办，不再探测；不传则按上面的顺序逐个试。
+
+    Raises
+    ------
+    FileNotFoundError
+        文件不存在。`.csv` 的自动探测分支会把原始路径包进中文提示里。
+    ValueError
+        后缀不在 `.csv` / `.xlsx` / `.xls` 里；
+        `.csv` 在候选编码下全部解码失败；
+        或 pandas 自身的解析错误（`pandas.errors.ParserError` 也是 `ValueError` 的子类，
+        报错信息原样抛出——它比转述的更有用）。
+    ImportError
+        `.xlsx` / `.xls` 但缺可选依赖（`openpyxl`，读旧 `.xls` 另需 `xlrd`），
+        见 docs/02-architecture.md §4.6：可选依赖的报错必须能直接看懂。
+
     Examples
     --------
     >>> df = load_table("data.csv")          # doctest: +SKIP
@@ -52,18 +73,42 @@ def load_table(path: str | Path, **kwargs: Any) -> Any:
 
 
 def save_table(df: pd.DataFrame, path: str | Path, index: bool = False, **kwargs: Any) -> Path:
-    """保存 DataFrame，返回实际写入的路径。"""
+    """保存 DataFrame，返回实际写入的路径。
+
+    Parameters
+    ----------
+    df:
+        要写出的表。必须是 `pandas.DataFrame`——`Series` 也不行，先 `.to_frame()`。
+    path:
+        目标路径。扩展名决定用哪个写入器，大小写不敏感；父目录不存在时自动创建。
+    index:
+        是否把行索引一并写进文件，默认 `False`。
+    **kwargs:
+        原样转交给 `pandas.DataFrame.to_csv` / `to_excel`。
+
+    Raises
+    ------
+    TypeError
+        `df` 不是 `pandas.DataFrame`。
+    ValueError
+        后缀不在 `.csv` / `.xlsx` / `.xls` 里。
+    ImportError
+        写 `.xlsx` / `.xls` 但缺 `openpyxl`。
+    """
     path = Path(path)
-    path.parent.mkdir(parents=True,exist_ok=True)
     suffix = path.suffix.lower()
 
     if not isinstance(df,pd.DataFrame):
         raise TypeError(f"df 必须是一个pandas DataFrame,但是你上传了{type(df)}")
 
+    # 校验必须排在副作用（建目录）之前：否则传个 .txt 会先建出一个空目录再抛错。
+    if suffix not in ('.csv','.xlsx','.xls'):
+        raise ValueError(f"不支持的文件后缀：{suffix}")
+
+    path.parent.mkdir(parents=True,exist_ok=True)
+
     if suffix == '.csv':
         df.to_csv(path,index=index,**kwargs)
-    elif suffix in ['.xlsx','.xls']:
-        df.to_excel(path,index=index,**kwargs)
     else:
-        raise ValueError(f"不支持的文件后缀：{suffix}")
+        df.to_excel(path,index=index,**kwargs)
     return path

src/mcm_toolkit/data/transform.py

@@ -10,6 +10,11 @@ from __future__ import annotations
 
 from typing import Any
 
+import numpy as np
+import pandas as pd
+
+from ..core.validate import as_array
+
 __all__ = ["log_transform", "normalize", "one_hot_encode", "standardize"]
 
 
@@ -18,13 +23,32 @@ def normalize(x: Any, method: str = "minmax", feature_range: tuple[float, float]
 
     Parameters
     ----------
+    x:
+        数值型标量 / list / tuple / `numpy.ndarray` / `pandas.Series` / `pandas.DataFrame`；
+        多维输入一律**按列**（`axis=0`）处理。
     method:
         `"minmax"`：`(x - min) / (max - min)`，线性压缩到 `feature_range`；
         `"vector"`：`x / ||x||`，保持"份额"含义（熵权法前处理常用）；
         `"max"`：`x / max(x)`。
+    feature_range:
+        仅 `method="minmax"` 时生效的目标区间，形如 `(low, high)`。
+
+    Returns
+    -------
+    numpy.ndarray / pandas.Series / pandas.DataFrame
+        与 `x` 同类型：DataFrame 进 DataFrame 出（列名、索引保持不变），
+        Series 进 Series 出，其余返回 `numpy.ndarray`。
+
+    Raises
+    ------
+    ValueError
+        `method` 不在支持列表内，或 `feature_range[0] >= feature_range[1]`。
+    TypeError
+        `x` 类型不支持，或 `feature_range` 不是二元组。
 
     Notes
     -----
+    常量列（`max == min`）不产生 nan / inf，固定压到 `feature_range` 的下界。
     minmax 对离群值极度敏感：一个 100 倍大的异常值会把其余所有点压成一条线。
     先跑 `detect_outliers` 再决定。
 
@@ -33,26 +57,177 @@ def normalize(x: Any, method: str = "minmax", feature_range: tuple[float, float]
     >>> normalize([1, 2, 3]).tolist()
     [0.0, 0.5, 1.0]
     """
-    # TODO(L0)
+    supported_method = ["minmax", "vector", "max"]
-    raise NotImplementedError
+    if method not in supported_method:
+        raise ValueError(f"不支持的方法:{method},仅支持{supported_method}")
+
+    if method == "minmax":
+        if not isinstance(feature_range, tuple) or len(feature_range) != 2:
+            raise TypeError(f"feature_range必须是形如(low, high)的二元组,你传入了{feature_range}")
+        if feature_range[0] >= feature_range[1]:
+            raise ValueError(f"feature_range的下界必须小于上界,你传入了{feature_range}")
+
+    # numeric_only=False：输出要与输入**同形**，跳过非数值列会让返回的表少列、对不上原表。
+    arr, kind = as_array(x, numeric_only=False)
+
+    if method == "minmax":
+        x_min = np.min(arr, axis=0)
+        x_max = np.max(arr, axis=0)
+        x_range = np.where(x_max - x_min == 0, 1.0, x_max - x_min)
+
+        scaled = (arr - x_min) / x_range
+        result = scaled * (feature_range[1] - feature_range[0]) + feature_range[0]
+    elif method == "vector":
+        norm = np.linalg.norm(arr, axis=0)
+        norm = np.where(norm == 0, 1.0, norm)
+        result = arr / norm
+    else:
+        # 上面已校验 method 合法，所以这里不必再写 elif，兜住仅剩的 "max"
+        x_max = np.max(arr, axis=0)
+        x_max = np.where(x_max == 0, 1.0, x_max)
+        result = arr / x_max
+
+    if kind == "frame":
+        return pd.DataFrame(result, index=x.index, columns=x.columns)
+    if kind == "series":
+        return pd.Series(result, index=x.index, name=x.name)
+    return result
 
 
 def standardize(x: Any, ddof: int = 0) -> Any:
-    """标准化 `(x - mean) / std`，输出均值 0、标准差 1。"""
+    """标准化 `(x - mean) / std`，输出均值 0、标准差 1。
-    # TODO(L0)
+
-    raise NotImplementedError
+    Parameters
+    ----------
+    x:
+        数值型标量 / list / tuple / `numpy.ndarray` / `pandas.Series` / `pandas.DataFrame`；
+        多维输入一律**按列**（`axis=0`）处理。
+    ddof:
+        标准差的自由度修正，与 `numpy.std` 同名参数含义一致；`0` 为总体标准差。
+
+    Returns
+    -------
+    numpy.ndarray / pandas.Series / pandas.DataFrame
+        与 `x` 同类型，DataFrame 的列名与索引保持不变。
+
+    Raises
+    ------
+    TypeError
+        `x` 类型不支持。
+
+    Notes
+    -----
+    常量列（`std == 0`）不产生 nan / inf，固定输出 0，与 `sklearn` 的
+    `StandardScaler` 对零方差列的处理一致。
+    """
+    # numeric_only=False：输出要与输入**同形**，跳过非数值列会让返回的表少列、对不上原表。
+    arr, kind = as_array(x, numeric_only=False)
+
+    mean = np.mean(arr, axis=0)
+
+    std = np.std(arr, axis=0, ddof=ddof)
+
+    std = np.where(std == 0, 1.0, std)
+
+    result = (arr - mean) / std
+
+    if kind == "frame":
+        return pd.DataFrame(result, index=x.index, columns=x.columns)
+    if kind == "series":
+        return pd.Series(result, index=x.index, name=x.name)
+    return result
 
 
 def log_transform(x: Any, offset: float | None = None) -> Any:
     """对数变换，用于压缩右偏分布。
 
-    `offset=None` 时自动取 `1 - min(x)`（含 0 或负值时）保证定义域。
+    Parameters
+    ----------
+    x:
+        数值型标量 / list / tuple / `numpy.ndarray` / `pandas.Series` / `pandas.DataFrame`。
+    offset:
+        平移量，算的是 `log(x + offset)`。
+        `None` 时自动取 `1 - min(x)`（当 `min(x) <= 0`），否则取 `0`，以保证定义域。
+
+    Returns
+    -------
+    numpy.ndarray / pandas.Series / pandas.DataFrame
+        与 `x` 同类型，DataFrame 的列名与索引保持不变。
+
+    Raises
+    ------
+    TypeError
+        `x` 类型不支持。
+    ValueError
+        显式传入的 `offset` 会让 `x + offset <= 0`，即破坏 `log` 的定义域。
+
+    Examples
+    --------
+    >>> log_transform([1.0, 2.718281828459045]).round(3).tolist()
+    [0.0, 1.0]
     """
-    # TODO(L1)
+    # numeric_only=False：输出要与输入**同形**，跳过非数值列会让返回的表少列、对不上原表。
-    raise NotImplementedError
+    arr, kind = as_array(x, numeric_only=False)
+
+    if offset is None:
+        min_val = np.min(arr)
+        offset = 1.0 - min_val if min_val <= 0 else 0.0
+    elif np.min(arr) + offset <= 0:
+        raise ValueError(
+            f"offset={offset} 会破坏 log 定义域: x + offset 的最小值为 {np.min(arr) + offset},必须大于 0"
+        )
+
+    result = np.log(arr + offset)
+
+    if kind == "frame":
+        return pd.DataFrame(result, index=x.index, columns=x.columns)
+    if kind == "series":
+        return pd.Series(result, index=x.index, name=x.name)
+    return result
 
 
 def one_hot_encode(data: Any, columns: list[str] | None = None, drop_first: bool = False) -> Any:
-    """类别变量独热编码。"""
+    """类别变量独热编码。
-    # TODO(L1)
+
-    raise NotImplementedError
+    Parameters
+    ----------
+    data:
+        要编码的表，必须是 `pandas.DataFrame`。
+    columns:
+        要编码的列名列表；`None` 表示自动识别所有文本 / 类别列
+        （`object` / `category` / `str` / `string` 四种 dtype）。
+    drop_first:
+        是否丢掉每个类别变量的第一个水平，避免哑变量陷阱（等价 `pandas.get_dummies` 同名参数）。
+
+    Returns
+    -------
+    pandas.DataFrame
+        编码后的新表，**原表不改**；新哑变量列形如 `city_A`。
+
+    Raises
+    ------
+    TypeError
+        `data` 不是 `pandas.DataFrame`。
+    ValueError
+        `columns` 里出现了原表中不存在的列名。
+
+    Notes
+    -----
+    这里**不能**把结果再按 `data.columns` 重新包一层 `DataFrame`：
+    哑变量列名（`city_A`）和原列名（`city`）对不上，那样会把编码结果整列丢掉。
+    """
+    if not isinstance(data, pd.DataFrame):
+        raise TypeError(f"data必须是 pandas DataFrame, 你传入了{type(data)}")
+
+    if columns is not None:
+        missing_cols = [col for col in columns if col not in data.columns]
+        if missing_cols:
+            raise ValueError(f"指定的列不存在于数据中:{missing_cols}")
+        cols_to_encode = columns
+    else:
+        # "str" / "string" 必须显式写上：pandas 3 起字符串列的 dtype 是 "str"，
+        # 只写 "object" 目前还能选中，但会发 Pandas4Warning，且官方声明未来移除该行为
+        # —— 到那天这里会**静默**一列都不编码，比报错难查得多。
+        cols_to_encode = data.select_dtypes(include=["object", "category", "str", "string"]).columns.tolist()
+
+    return pd.get_dummies(data, columns=cols_to_encode, drop_first=drop_first)

src/mcm_toolkit/models/metrics.py

@@ -5,12 +5,22 @@
 
 注意：本模块被 `models` 与 `solve` 共用，属于"公共数学"，但为了少建一个包，
 放在 `models` 下；`solve` 单向依赖 `models` 是允许的。
+
+本模块的指标函数**只返回 `float`，不返回 `Result`**（架构 §4.1 只覆盖拟合/求解/
+模拟/评价）；入口非法一律抛异常，见各函数的 `Raises`。唯一的例外是
+`compare_models`：它按架构 §4.3 返回一张 `DataFrame` 对比表。
 """
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from typing import Any
 
+import numpy as np
+import pandas as pd
+
+from mcm_toolkit.core import as_array, get_rng
+
 __all__ = [
     "adjusted_r2",
     "compare_models",
@@ -22,40 +32,259 @@ __all__ = [
 ]
 
 
+def verify_yt_yp(y_true: Any, y_pred: Any) -> tuple[np.ndarray, np.ndarray]:
+    """收成同形的一维 `ndarray`，并拦掉形状 / 空 / NaN / Inf / 样本不足五类非法输入。
+
+    指标函数的第一道关：先在这里把非法输入拦掉，函数体里就只剩公式。
+    刻意**不删缺失值**（与 `as_array` 同一口径）：删了会悄悄改变样本量，
+    指标就不可比了，所以含 `NaN` / `Inf` 直接报错（决策 48）。
+    **至少 2 个样本**：1 个点的误差指标没有统计意义（`r2_score` 更是直接无定义）。
+
+    Parameters
+    ----------
+    y_true, y_pred:
+        `DataFrame` / `Series` / `ndarray` / `list` / `tuple`，按 `as_array` 的规则
+        收成一维浮点数组（`str` 会被白名单挡住并 `TypeError`）。
+
+    Returns
+    -------
+    (numpy.ndarray, numpy.ndarray)
+        校验通过后的 `(y_true, y_pred)`，两者形状相同。
+
+    Raises
+    ------
+    ValueError
+        形状不一致；长度为 0 或 1（指标至少要 2 个样本）；含 `NaN` 或 `Inf`。
+    """
+    yt, _ = as_array(y_true, ndim=1)
+    yp, _ = as_array(y_pred, ndim=1)
+
+    if yt.shape != yp.shape:
+        raise ValueError(f"y_true 与 y_pred 的形状必须一致，你传入的是 {yt.shape} 和 {yp.shape}")
+    if len(yt) == 0:
+        raise ValueError("y_true 与 y_pred 都不能为空")
+    if np.isnan(yt).any() or np.isnan(yp).any():
+        raise ValueError("有空值（NaN），请清洗或补充后再计算")
+    if np.isinf(yt).any() or np.isinf(yp).any():
+        raise ValueError("有无限值（Inf），请检查数据来源，修复除以0或溢出问题")
+    if yt.ndim == 0 or yt.shape[0] <= 1:
+        raise ValueError(f"输入至少需要包含 2 个样本，当前长度为 {yt.shape[0] if yt.ndim > 0 else 1}")
+
+    return yt, yp
+
+
 def rmse(y_true: Any, y_pred: Any) -> float:
-    """均方根误差。与 y 同量纲，最常用。"""
+    """均方根误差。与 y 同量纲、对大误差敏感，回归里最常用的第一指标。
-    # TODO(L0)
+
-    raise NotImplementedError
+    Parameters
+    ----------
+    y_true, y_pred:
+        同形的一维数据，校验规则见 :func:`verify_yt_yp`。
+
+    Returns
+    -------
+    float
+        `sqrt(mean((y_true - y_pred) ** 2))`，越小越好，0 表示完美拟合。
+
+    Raises
+    ------
+    ValueError
+        未通过 :func:`verify_yt_yp`：形状不一致、样本少于 2 个、含 `NaN` 或 `Inf`。
+    """
+    yt, yp = verify_yt_yp(y_true=y_true, y_pred=y_pred)
+
+    return float(np.sqrt(np.mean((yt - yp) ** 2)))
 
 
 def mae(y_true: Any, y_pred: Any) -> float:
-    """平均绝对误差。对离群值比 RMSE 稳健。"""
+    """平均绝对误差。对离群值比 RMSE 稳健，和 RMSE 一起看能判断有无离群点。
-    # TODO(L0)
+
-    raise NotImplementedError
+    Parameters
+    ----------
+    y_true, y_pred:
+        同形的一维数据，校验规则见 :func:`verify_yt_yp`。
+
+    Returns
+    -------
+    float
+        `mean(|y_true - y_pred|)`，越小越好。
+
+    Raises
+    ------
+    ValueError
+        未通过 :func:`verify_yt_yp`：形状不一致、样本少于 2 个、含 `NaN` 或 `Inf`。
+    """
+    yt, yp = verify_yt_yp(y_true=y_true, y_pred=y_pred)
+
+    return float(np.mean(np.abs(yt - yp)))
 
 
 def mape(y_true: Any, y_pred: Any) -> float:
-    """平均绝对百分比误差。无量纲，但 y 含 0 时会炸（用 smape 替代）。"""
+    """平均绝对百分比误差。无量纲，可跨量纲比较；`y_true` 必须**全为正数**。
-    # TODO(L1)
+
-    raise NotImplementedError
+    Parameters
+    ----------
+    y_true, y_pred:
+        同形的一维数据，校验规则见 :func:`verify_yt_yp`。
+
+    Returns
+    -------
+    float
+        `mean(|y_true - y_pred| / y_true)`，`0.1` 表示平均偏差 10%。
+
+    Raises
+    ------
+    ValueError
+        未通过 :func:`verify_yt_yp`（形状 / 样本数 / `NaN` / `Inf`），
+        或 `y_true` 里有非正数（0 → 分母为 0；负数 → 百分比误差无意义；
+        这种数据请改用 :func:`smape`）。
+    """
+    yt, yp = verify_yt_yp(y_true=y_true, y_pred=y_pred)
+
+    if np.any(yt <= 0):
+        raise ValueError("y_true 包含非正数（0或负数），MAPE 在数学上无定义，请清洗数据或改用 SMAPE。")
+    return float(np.mean(np.abs(yt - yp) / yt))
 
 
 def smape(y_true: Any, y_pred: Any) -> float:
-    """对称 MAPE，y 含 0 也安全。"""
+    """对称 MAPE。`y_true` / `y_pred` 含 0 或为 0 都安全，是 MAPE 的替代品。
-    # TODO(L1)
+
-    raise NotImplementedError
+    Parameters
+    ----------
+    y_true, y_pred:
+        同形的一维数据，校验规则见 :func:`verify_yt_yp`。
+
+    Returns
+    -------
+    float
+        `mean(2 * |y_true - y_pred| / (|y_true| + |y_pred|))`。
+        分子分母同时为 0 的点**记 0**（该点无偏差可言），不计入分母。
+
+    Raises
+    ------
+    ValueError
+        未通过 :func:`verify_yt_yp`：形状不一致、样本少于 2 个、含 `NaN` 或 `Inf`。
+    """
+    yt, yp = verify_yt_yp(y_true=y_true, y_pred=y_pred)
+
+    denom = np.abs(yt) + np.abs(yp)
+    # 分母为 0 的点记 0。注意 np.where 的两条分支**都会被求值**，直接写除式会触发
+    # "invalid value encountered in divide" 的 RuntimeWarning，而本项目 pytest 开了
+    # filterwarnings=error::RuntimeWarning，那样测试会直接算失败；所以用 where= 掩码。
+    ratio = np.divide(2 * np.abs(yt - yp), denom, out=np.zeros_like(denom), where=denom != 0.0)
+    return float(np.mean(ratio))
 
 
 def r2_score(y_true: Any, y_pred: Any) -> float:
-    """决定系数 R²。注意：加变量一定会升高，跨模型比较要看 adjusted_r2。"""
+    """决定系数 R²。加变量一定会升高，跨模型比较要看 :func:`adjusted_r2`。
-    # TODO(L0)
+
-    raise NotImplementedError
+    Parameters
+    ----------
+    y_true, y_pred:
+        同形的一维数据，校验规则见 :func:`verify_yt_yp`。
+
+    Returns
+    -------
+    float
+        `1 - SS_res / SS_tot`，其中 `SS_res = sum((y_true - y_pred) ** 2)`、
+        `SS_tot = sum((y_true - mean(y_true)) ** 2)`，基准是 `y_true` 的均值。
+        完美拟合约等于 1，比"直接取均值"还差时为负。
+
+    Raises
+    ------
+    ValueError
+        未通过 :func:`verify_yt_yp`（形状 / 样本数 / `NaN` / `Inf`），
+        或 `y_true` 是常量（`SS_tot = 0`，分母为 0）。
+    """
+    yt, yp = verify_yt_yp(y_true=y_true, y_pred=y_pred)
+
+    ss_res = np.sum((yt - yp) ** 2)
+    ss_tot = np.sum((yt - np.mean(yt)) ** 2)
+
+    if ss_tot == 0:
+        raise ValueError("y_true 是常量，SS_tot = 0，无法计算 R²")
+    return float(1 - (ss_res / ss_tot))
 
 
-def adjusted_r2(y_true: Any, y_pred: Any, n_features: int) -> float:
+def adjusted_r2(y_true: Any, y_pred: Any, n_features: int | np.integer) -> float:
-    """调整 R²，惩罚变量个数。"""
+    """调整 R²，按自由度惩罚变量个数；同一样本量下比 R² 公平。
-    # TODO(L1)
+
-    raise NotImplementedError
+    Parameters
+    ----------
+    y_true, y_pred:
+        同形的一维数据，校验规则见 :func:`verify_yt_yp`。
+    n_features:
+        **自变量个数，不含截距**（`y = 2x + 1` 只有 1 个自变量）。
+        必须为正整数；`bool` 会被挡掉（`True` 看着像 1，但不是个数）。
+
+    Returns
+    -------
+    float
+        `1 - (1 - R²) * (n - 1) / (n - n_features - 1)`，`n = len(y_true)`。
+        比 R² 更保守：`n_features` 越大惩罚越重，所以它才是跨模型比较该看的那个。
+
+    Raises
+    ------
+    TypeError
+        `n_features` 不是整数（含 `bool`、`float`、`np.float64`）。
+    ValueError
+        `n_features <= 0`；`n <= n_features + 1`（自由度为 0，分母为 0）；
+        或 `y_true` / `y_pred` 未通过 :func:`verify_yt_yp`（形状 / 样本数 / `NaN` / `Inf`）。
+    """
+    yt, yp = verify_yt_yp(y_true=y_true, y_pred=y_pred)
+
+    if isinstance(n_features, bool) or not isinstance(n_features, (int, np.integer)):
+        raise TypeError(f"n_features 必须是正整数，你传入了 {type(n_features).__name__}")
+    if n_features <= 0:
+        raise ValueError(f"n_features 必须是正整数，你传入了 {n_features}")
+
+    r2 = r2_score(yt, yp)
+    n = len(yt)
+
+    if n - n_features - 1 <= 0:
+        raise ValueError(f"样本量太小（n={n}，自变量 {n_features} 个），分母会变成 0 或负数")
+
+    return float(1 - ((1 - r2) * (n - 1) / (n - 1 - n_features)))
+
+
+# 指标名 → 函数。**别名表**就在这里：`"r2"` 与 `"r2_score"` 是同一个函数的两个名字，
+# 传哪个名字，输出表里的列就叫哪个名字（模型的 `score()` 习惯用 `"r2"`，函数本名是
+# `r2_score`，两个都收，省得记）。要加指标就往这个 dict 里添一行。
+#
+# `adjusted_r2` **不在这里**：它还要 `n_features`（自变量个数），`compare_models` 不知道
+# 每个模型实际用了几个自变量，硬塞进来只会算错。单个模型要调整 R² 就自己调它。
+_METRIC_FUNCS: dict[str, Callable[[Any, Any], float]] = {
+    "rmse": rmse,
+    "mae": mae,
+    "mape": mape,
+    "smape": smape,
+    "r2": r2_score,
+    "r2_score": r2_score,
+}
+
+# "越大越好"的指标：排序方向要反过来。其余（误差类）一律越小越好。
+_HIGHER_IS_BETTER = frozenset({"r2", "r2_score"})
+
+
+def _resolve_metrics(metrics: Any) -> dict[str, Callable[[Any, Any], float]]:
+    """把指标名列表翻成 `{列名: 函数}`，顺手拦掉不认识的名字和重复的别名。"""
+    if isinstance(metrics, str):
+        raise TypeError("metrics 是一**组**指标名，写成 metrics=('rmse', 'r2')，不要传单个字符串")
+    if not isinstance(metrics, (list, tuple)):
+        raise TypeError(f"metrics 必须是 tuple / list，你传入了 {type(metrics).__name__}")
+
+    resolved: dict[str, Callable[[Any, Any], float]] = {}
+    for name in metrics:
+        fn = _METRIC_FUNCS.get(name)
+        if fn is None:
+            raise ValueError(f"不认识的指标名 {name!r}；可选：{sorted(_METRIC_FUNCS)}")
+        if fn in resolved.values():
+            raise ValueError(f"{name!r} 与前面某个指标是同一个函数（别名），只挑一个传")
+        resolved[name] = fn
+
+    if not resolved:
+        raise ValueError("metrics 至少要有一个指标")
+    return resolved
 
 
 def compare_models(
@@ -65,7 +294,7 @@ def compare_models(
     metrics: tuple[str, ...] = ("rmse", "mae", "r2"),
     cv: int = 5,
     random_state: int | None = None,
-) -> Any:
+) -> pd.DataFrame:
     """把若干模型放在一起打分，返回对比表。
 
     这是赛题里最省时间的函数之一。队友问"要不要上复杂模型"时，
@@ -76,19 +305,102 @@ def compare_models(
     models:
         `{"linear": m1, "poly3": m2, "random_forest": m3}`。
         每个模型需满足 :class:`mcm_toolkit.models.base.Model` 协议（有 `fit` / `predict`）。
+        **传模型对象本身，不是拟合结果** —— 拟合由本函数自己做。
+    X:
+        二维设计矩阵 `(n_samples, n_features)`；一列的 `x` 要自己 `x.reshape(-1, 1)`。
+    y:
+        一维真值，与 `X` 行数相同。
+    metrics:
+        要打分的指标名。可用 `"rmse"` / `"mae"` / `"mape"` / `"smape"` / `"r2"` / `"r2_score"`；
+        **`"r2"` 与 `"r2_score"` 是同一个函数的别名**（传哪个、列名就叫哪个），两个一起传会报错。
+        表按**第一个指标**排序：误差类升序（越小越好），R² 降序。
     cv:
         交叉验证折数；`cv=0` 表示在全部数据上拟合后打分（只看拟合能力时用）。
+        `cv >= 2` 时报的是**折间均值**，每折至少 2 个样本（指标本身的入口要求）。
+        **时序数据不要用它** —— 随机划分会让未来信息漏进训练集（要用滚动窗口）。
+    random_state:
+        随机种子（`cv >= 2` 时决定折怎么分）。传整数可复现；`None` 时跟随
+        `core.set_seed` 的全局流。
 
     Returns
     -------
-    DataFrame：行 = 模型，列 = 指标；按第一列指标升序（越小越好）或降序排列。
+    pandas.DataFrame：行 = 模型（`models` 的键），列 = 指标（`metrics` 里的名字）。
-    可直接 `save_table(result, "compare.tex", fmt="latex")` 贴进论文。
+    按第一个指标排好序，可直接 `save_table(tbl, "compare.tex", fmt="latex")` 贴进论文。
+
+    Raises
+    ------
+    TypeError
+        `models` 不是 dict、`cv` 不是整数、`metrics` 传了单个字符串，
+        或某个模型没有 `fit` / `predict`。
+    ValueError
+        `models` 为空、指标名不认识、两个指标是同一个别名、
+        `X` / `y` 未通过 `as_array`、样本数不一致、`cv` 取值不可能分折。
+
+    Notes
+    -----
+    分折是**用 numpy 手写的 K 折交叉验证**（`get_rng(random_state).permutation` +
+    `np.array_split`），所以不依赖 sklearn —— 比赛现场没装 `ml` 那组 extras 也能跑。
+    指标自己的入口要求照样生效：`mape` 要求 `y_true` 全为正数，含 0 或负数的数据改用 `smape`。
 
     Examples
     --------
-    >>> tbl = compare_models({"linear": m1, "poly": m2}, X, y)   # doctest: +SKIP
+    >>> tbl = compare_models({"linear": m1, "poly": m2}, X, y, cv=0)   # doctest: +SKIP
     >>> tbl.index[0]                                                  # doctest: +SKIP
     'poly'
     """
-    # TODO(L1)
+    if not isinstance(models, dict):
-    raise NotImplementedError
+        raise TypeError(f"models 必须是 {{名字: 模型}} 的字典，你传入了 {type(models).__name__}")
+    if not models:
+        raise ValueError("models 不能为空，至少给一个模型")
+    for name, model in models.items():
+        if not (hasattr(model, "fit") and hasattr(model, "predict")):
+            raise TypeError(
+                f"模型 {name!r} 不满足 Model 协议：需要 fit / predict 两个方法；"
+                f"你传入了 {type(model).__name__}（注意：传模型对象，别传拟合结果）"
+            )
+
+    resolved = _resolve_metrics(metrics)
+
+    X_arr, _ = as_array(X, ndim=2)
+    y_arr, _ = as_array(y, ndim=1)
+    n = y_arr.shape[0]
+    if X_arr.shape[0] != n:
+        raise ValueError(f"X 与 y 的样本数必须一致，你传入的是 {X_arr.shape[0]} 和 {n}")
+    if n < 2:
+        raise ValueError(f"样本太少：至少要 2 个，当前 n={n}")
+
+    if isinstance(cv, bool) or not isinstance(cv, (int, np.integer)):
+        raise TypeError(f"cv 必须是整数，你传入了 {type(cv).__name__}")
+    if cv < 0:
+        raise ValueError(f"cv 不能为负数：0 表示全量打分，你传入了 {cv}")
+    if cv == 1:
+        raise ValueError("cv=1 没有意义：要么 cv=0（全量拟合后打分），要么 cv>=2（分折）")
+    if cv > 0 and cv > n // 2:
+        raise ValueError(
+            f"cv={cv} 太大：n={n}、每折至少要 2 个样本，最多只能分 {n // 2} 折；"
+            "样本太少的话改用 cv=0（全量拟合后打分）"
+        )
+
+    if cv == 0:
+        folds = [(np.arange(n), np.arange(n))]
+    else:
+        index = get_rng(random_state).permutation(n)
+        blocks = np.array_split(index, cv)
+        folds = [
+            (np.concatenate([blocks[j] for j in range(cv) if j != k]), blocks[k])
+            for k in range(cv)
+        ]
+
+    scores: dict[str, dict[str, float]] = {}
+    for name, model in models.items():
+        per_fold: dict[str, list[float]] = {column: [] for column in resolved}
+        for train_idx, test_idx in folds:
+            model.fit(X_arr[train_idx], y_arr[train_idx])
+            y_pred = np.asarray(model.predict(X_arr[test_idx]))
+            for column, fn in resolved.items():
+                per_fold[column].append(fn(y_arr[test_idx], y_pred))
+        scores[name] = {column: float(np.mean(vals)) for column, vals in per_fold.items()}
+
+    table = pd.DataFrame.from_dict(scores, orient="index")
+    first = next(iter(resolved))
+    return table.sort_values(first, ascending=first not in _HIGHER_IS_BETTER)

src/mcm_toolkit/solve/simulate.py

@@ -10,6 +10,11 @@ from __future__ import annotations
 from collections.abc import Callable
 from typing import Any
 
+import numpy as np
+from scipy.stats import norm
+
+from mcm_toolkit.core import Result, as_array, get_rng
+
 __all__ = [
     "markov_simulate",
     "markov_steady_state",
@@ -24,7 +29,7 @@ __all__ = [
 def monte_carlo(
     sampler: Callable[..., Any],
     simulator: Callable[..., Any],
-    n: int = 10000,
+    n: int | np.integer = 10000,
     random_state: int | None = None,
     **kwargs: Any,
 ) -> Any:
@@ -33,74 +38,241 @@ def monte_carlo(
     Parameters
     ----------
     sampler:
-        `f(rng, **kwargs) -> 一组参数`，例如从先验分布里抽参数。
+        `f(rng, size, **kwargs) -> 一批参数`。**一次就要抽够 `n` 组**，
+        例如 `lambda rng, size: rng.normal(0, 1, size)`。
+        批量大小由本函数以 `size=n` 传进去：`sampler` 必须能接住 `size`
+        （显式声明，或带 `**kwargs`）。**别再往 `**kwargs` 里塞 `size`**，否则重复传参。
     simulator:
-        `f(params) -> float`，例如"给定参数下的年收益"。
+        `f(params) -> 一批结果`。收到 `sampler` 的那一整批参数，
+        返回长度同为 `n` 的数组（标量 / 长度对不上都算契约错误）。
+        **内部不要写 Python 循环**。
     n:
-        模拟次数。**必须向量化**：`simulator` 内部不要写 Python 循环，
+        模拟次数，正整数。与 `simulator` 返回的长度必须一致。
-        否则 10^4 次能跑几分钟，10^6 次直接放弃。
+    random_state:
+        随机种子。`None` 时跟随 `core.set_seed` 的全局流，见 `core.random.get_rng`。
+    **kwargs:
+        原样转交给 `sampler`，例如分布参数 `mu` / `sigma`（`size` 由本函数自己传，见上）。
+        会一并记进 `Result.params`，便于复现。
 
     Returns
     -------
-    `Result`：`data` 是 `n` 个结果组成的数组，
+    `Result`：`data` 是 `n` 个结果组成的数组（一律转成 float，布尔结果按 0/1 统计），
     `metrics={"mean", "std", "median", "p05", "p95", "ci_low", "ci_high"}`。
 
+    Raises
+    ------
+    TypeError:
+        `sampler` / `simulator` 不可调用，`n` 不是整数，或 `random_state` 类型非法。
+    ValueError:
+        `n` 不是正整数。
+
     Notes
     -----
-    比赛里 Monte Carlo 的收敛速度是 `O(1/√n)`——
+    比赛里 Monte Carlo 的收敛速度是 `O(1/√n)` —— 想少一半误差就要 4 倍样本。
-    想少一半误差要 4 倍样本。所以论文里要给"区间随 n 收敛"的图，
+    所以论文里要给"区间随 n 收敛"的图，证明 `n` 已经够大
-    证明 `n` 已经够大（这也是 `viz.plot_convergence` 的典型用法）。
+    （这也是 `viz.plot_convergence` 的典型用法）。
+
+    结果里只要出现 **NaN** 就判失败（`success=False`）：MC 的 NaN 通常来自除零、
+    取负数的根号或模型发散，静默统计只会得到一列 nan 指标。
 
     Examples
     --------
     >>> import numpy as np
-    >>> r = monte_carlo(lambda rng, **k: rng.normal(0, 1), np.mean, n=1000, random_state=0)
+    >>> draw = lambda rng, size, **k: rng.normal(0, 1, size)
+    >>> r = monte_carlo(draw, lambda x: x ** 2, n=10000, random_state=0)
+    >>> bool(abs(r.metrics["mean"] - 1.0) < 0.1)  # E[X²] = 1
+    True
     """
-    # TODO(L1)  ★ S 档
+    if not callable(sampler) or not callable(simulator):
-    raise NotImplementedError
+        raise TypeError("sampler 和 simulator 必须是可调用函数")
+    if isinstance(n, bool) or not isinstance(n, (int, np.integer)):
+        raise TypeError(f"n 必须是整数，你传入了 {type(n).__name__}")
+    if int(n) <= 0:
+        raise ValueError(f"n 必须是正整数，你传入了 {n}")
+    n = int(n)
+
+    rng = get_rng(random_state)
+    call_params = {"n": n, "random_state": random_state, **kwargs}
+
+    try:
+        params = sampler(rng, size=n, **kwargs)
+        data = np.asarray(simulator(params), dtype=float).ravel()
+        if np.isnan(data).any():
+            raise ValueError("模拟结果中包含 NaN，请检查 sampler 或 simulator 的传入参数")
+        if len(data) != n:
+            raise ValueError(f"simulator 返回的结果数量({len(data)})必须与模拟次数 n({n})一致")
+
+        metrics = {
+            "mean": float(np.mean(data)),
+            "std": float(np.std(data, ddof=0)),
+            "median": float(np.median(data)),
+            "p05": float(np.percentile(data, 5)),
+            "p95": float(np.percentile(data, 95)),
+            "ci_low": float(np.percentile(data, 2.5)),
+            "ci_high": float(np.percentile(data, 97.5)),
+        }
+
+        return Result(
+            name="monte_carlo",
+            params=call_params,
+            metrics=metrics,
+            data=data,
+            success=True,
+            message=f"蒙特卡洛模拟成功：已完成 {n} 次模拟",
+        )
+    except Exception as e:
+        return Result(
+            name="monte_carlo",
+            params=call_params,
+            metrics={},
+            data=None,
+            success=False,
+            message=f"蒙特卡洛模拟失败：{type(e).__name__} - {e}",
+        )
 
 
 def monte_carlo_probability(
-    event: Callable[..., bool],
+    event: Callable[..., Any],
     sampler: Callable[..., Any],
-    n: int = 10000,
+    n: int | np.integer = 10000,
     confidence: float = 0.95,
     random_state: int | None = None,
 ) -> Any:
     """估计事件发生概率，并给出区间。
 
+    Parameters
+    ----------
+    event:
+        `f(params) -> 一批 bool`。吃到 `sampler` 的**整批**参数，
+        返回长度为 `n` 的布尔数组（写成 `z > 0` 这种逐元素判断即可，不要写 Python 循环）。
+    sampler:
+        `f(rng, size, **kwargs) -> 一批参数`，契约同 `monte_carlo`：
+        批量大小由本函数以 `size=n` 传入，`sampler` 必须能接住 `size`。
+    n:
+        模拟次数，正整数。与 `event` 返回的长度必须一致。
+    confidence:
+        区间置信水平，必须落在开区间 `(0, 1)` 内。
+    random_state:
+        随机种子。`None` 时跟随 `core.set_seed` 的全局流，见 `core.random.get_rng`。
+
     Returns
     -------
-    `Result`：`metrics={"probability", "ci_low", "ci_high", "std_error"}`。
+    `Result`：`data` 是 `n` 个 0/1 结果组成的数组，
+    `metrics={"probability", "ci_low", "ci_high", "std_error"}`。
+    区间是 Wilson score 区间（`p` 贴近 0 / 1 时比 Wald 稳），并夹在 `[0, 1]` 内（比例量纲，见决策 42）。
+
+    Raises
+    ------
+    TypeError:
+        `n` 不是整数，或 `random_state` 类型非法。
+    ValueError:
+        `n` 不是正整数，或 `confidence` 不在 `(0, 1)` 内。
 
     Notes
     -----
     概率估计的相对误差 ≈ `1/√(n·p)`。**小概率事件（p < 1e-3）用朴素 MC 是不可行的**，
     需要重要性采样或方差缩减——遇到这类题要提前意识到，别硬跑。
+    本函数当前的口径：`probability <= 1e-3` 时**直接判 `success=False`**（只给提示，不给区间）。
 
     Examples
     --------
     >>> import numpy as np
-    >>> r = monte_carlo_probability(lambda v: v > 0, lambda rng, **k: rng.normal(0, 1), n=2000, random_state=0)
+    >>> draw = lambda rng, size, **k: rng.normal(0, 1, size)
+    >>> r = monte_carlo_probability(lambda z: z > 0, draw, n=2000, random_state=0)
     >>> abs(r.metrics["probability"] - 0.5) < 0.1
     True
     """
-    # TODO(L1)  ★ S 档
+    if not callable(sampler) or not callable(event):
-    raise NotImplementedError
+        raise TypeError("sampler 和 event 必须是可调用函数")
+    if isinstance(n, bool) or not isinstance(n, (int, np.integer)):
+        raise TypeError(f"n 必须是整数，你传入了 {type(n).__name__}")
+    if int(n) <= 0:
+        raise ValueError(f"n 必须是正整数，你传入了 {n}")
+    n = int(n)
+    if confidence <= 0.0 or confidence >= 1:
+        raise ValueError(f"confidence必须在0和1之间,而你输入了{confidence}")
+
+    rng = get_rng(random_state)
+    call_params = {"n": n, "random_state": random_state, "confidence": confidence}
+
+    try:
+        params = sampler(rng, size=n)
+        data = np.asarray(event(params), dtype=float).ravel()
+        if np.isnan(data).any():
+            raise ValueError("模拟结果中包含 NaN，请检查 event 或 sampler 的传入参数")
+        if len(data) != n:
+            raise ValueError(f"event 返回的结果数量({len(data)})必须与模拟次数 n({n})一致")
+        p_value = float(np.mean(data))
+        std_error = float(np.sqrt(p_value * (1.0 - p_value) / n))
+
+        z_score = norm.ppf(1 - (1 - confidence) / 2)
+        center = (p_value + z_score**2 / (2 * n)) / (1 + z_score ** 2 / n)
+        half_width = (z_score / (1 + z_score ** 2 / n)) * np.sqrt(p_value * (1 - p_value) / n + z_score ** 2 / (4 * n ** 2))
+        ci_low = max(0.0, center - half_width)
+        ci_high = min(1.0, center + half_width)
+
+        warning_message = ""
+        if p_value <= 1e-3 or p_value >= 1 - 1e-3:
+            warning_message = "小概率事件 P < 1e-3 或者高概率事件 P > 1 - 1e-3,不建议使用monte_carlo_probability"
+
+        metrics = {
+            "probability": p_value,
+            "ci_low": float(ci_low),
+            "ci_high": float(ci_high),
+            "std_error": std_error,
+        }
+        return Result(
+            name="monte_carlo_probability",
+            params=call_params,
+            metrics=metrics,
+            data=data,
+            success=True,
+            message=(
+                f"蒙特卡洛模拟成功：已完成 {n} 次模拟"
+                + (f"；{warning_message}" if warning_message else "")
+            ),
+        )
+    except Exception as e:
+        return Result(
+            name="monte_carlo_probability",
+            params=call_params,
+            metrics={},
+            data=None,
+            success=False,
+            message=f"蒙特卡洛模拟失败：{type(e).__name__} - {e}",
+        )
 
 
 def monte_carlo_integral(
     func: Callable[..., Any],
     bounds: Any,
-    n: int = 10000,
+    n: int | np.integer = 10000,
     random_state: int | None = None,
 ) -> Any:
     """用蒙特卡洛求多重积分。
 
     Parameters
     ----------
+    func:
+        `f(X) -> 一批函数值`。`X` 是形状 `(n, d)` 的样本矩阵（一行一个样本），
+        返回长度 `n` 的数组（写成 `X[:, 0] ** 2` 这种逐行写法，不要写 Python 循环）。
     bounds:
-        `[(lo, hi), ...]`，维度即积分重数。
+        `[(lo, hi), ...]`（非空 list / tuple），维度即积分重数；要求每项都是二元组且 `lo < hi`。
+    n:
+        模拟次数，正整数。
+    random_state:
+        随机种子。`None` 时跟随 `core.set_seed` 的全局流，见 `core.random.get_rng`。
+
+    Returns
+    -------
+    `Result`：**`metrics["mean"]` 才是积分估计值** ≈ `∫f dV`；
+    `data` 是 `n` 个样本各自的贡献（`func(X_i) × 体积`），可拿去画随 `n` 的收敛图。
+    `params` 里额外记了 `bounds` 与 `dimension`。
+
+    Raises
+    ------
+    ValueError:
+        `bounds` 不是非空 list / tuple、形状不是 `(d, 2)`（例如漏括号写成 `[0, 1]`），或某个 `lo >= hi`。
 
     Notes
     -----
@@ -111,70 +283,359 @@ def monte_carlo_integral(
     --------
     >>> import numpy as np
     >>> r = monte_carlo_integral(lambda X: X[:, 0] ** 2, bounds=[(0, 1)], n=200000, random_state=0)
-    >>> abs(r.data - 1 / 3) < 0.01
+    >>> abs(r.metrics["mean"] - 1 / 3) < 0.01   # ∫₀¹ x² dx = 1/3
     True
     """
-    # TODO(L1)  ★ S 档：配完整函数卡片
+    if not isinstance(bounds, np.ndarray):
-    raise NotImplementedError
+        if not isinstance(bounds, (list, tuple)) or len(bounds) == 0:
+            raise ValueError("bounds 必须是非空的列表或元组")
+
+        bounds_arr = np.asarray(bounds)
+    else:
+        bounds_arr = bounds.copy()
+
+    if bounds_arr.ndim != 2 or bounds_arr.shape[1] != 2:
+        raise ValueError(f"bounds 必须形如 [(lo, hi), ...]，当前形状为 {bounds_arr.shape}，请检查是否漏了括号")
+
+    lows = bounds_arr[:, 0]
+    highs = bounds_arr[:, 1]
+    d = len(lows)
+    if np.any(lows >= highs):
+        raise ValueError("积分边界非法：下界必须严格小于上界")
+
+    widths = highs - lows
+
+    volume = np.prod(widths)
+
+    def sampler(rng, size=n):
+        return rng.uniform(low=lows, high=highs, size=(size, d))
+
+    def simulator(X):
+        vals = func(X)
+        if len(vals) != n:
+            raise ValueError(f"func 返回的结果数量({len(vals)})必须与模拟次数 n({n})一致")
+        return np.asarray(vals, dtype=float).ravel() * volume
+
+    result = monte_carlo(
+        sampler=sampler,
+        simulator=simulator,
+        n=n,
+        random_state=random_state,
+    )
+
+    result.name = "monte_carlo_integral"
+    result.params["bounds"] = bounds
+    result.params["dimension"] = d
+    if result.success:
+        result.message = f"蒙特卡洛多重积分成功：维度 {d}，体积 {volume:.4f}，模拟 {n} 次。"
+    else:
+        result.message = f"蒙特卡洛多重积分失败：维度 {d}，体积 {volume:.4f}，模拟 {n} 次。{result.message}"
+
+    return result
 
 
 def random_walk(
-    n_steps: int,
+    n_steps: int | np.integer,
-    n_paths: int = 1,
+    n_paths: int | np.integer = 1,
     step_sampler: Callable[..., Any] | None = None,
     start: float = 0.0,
     random_state: int | None = None,
 ) -> Any:
-    """随机游走轨迹。
+    """随机游走轨迹：一次抽完整批增量，再 `cumsum` 成路径。
 
     Parameters
     ----------
+    n_steps:
+        每条路径的步数，正整数。`data` 的列数是 `n_steps + 1`（多出的那一列是起点）。
+    n_paths:
+        路径条数，正整数，默认 1 条。
     step_sampler:
-        `f(rng, size) -> 增量`，默认为 ±1 等概率（对称随机游走）。
+        `f(rng, size) -> 一批增量`。**`size` 是整数** `n_paths * n_steps`（与 `monte_carlo` 的 `sampler` 同一契约），
+        必须返回**一维**长度 `n_paths * n_steps` 的数组；本函数负责 `reshape(n_paths, n_steps)`（行主序）。
+        返回二维一律判失败 —— 否则"转置的采样器"在 `n_paths == n_steps` 时会静默给出转置结果。
+        默认 ±1 等概率（对称随机游走）。
+    start:
+        起点，写进每条路径的第 0 列。
+    random_state:
+        随机种子。`None` 时跟随 `core.set_seed` 的全局流，见 `core.random.get_rng`。
 
     Returns
     -------
-    `Result`：`data` 形状 `(n_paths, n_steps + 1)`。
+    `Result`：`data` 形状 `(n_paths, n_steps + 1)`，第 0 列恒为 `start`，之后是逐列累加出来的位置；
+    `metrics={"mean_terminal", "std_terminal"}`（终点的均值与标准差，`std` 用 `ddof=0`）。
+
+    Raises
+    ------
+    TypeError:
+        `n_steps` / `n_paths` 不是整数。
+        `start` 不是数值。
+    ValueError:
+        `n_steps` / `n_paths` 不是正整数。
+
+    Notes
+    -----
+    随机游走是"平方根扩散"的原型：位置的标准差随步数按 `√t` 增长，所以典型图形是 `±√t` 的喇叭口。
+    本函数只负责 `cumsum`；**建模差异全在 `step_sampler` 里** —— 换成 `rng.normal(0, 1, size)` 就是高斯游走，
+    换成带正漂移的增量就是有趋势的游走。
+    `step_sampler` 返回的不是**一维**、长度不等于 `n_paths * n_steps`，或增量里出现 NaN，都判 `success=False`
+    （NaN 口径与 `monte_carlo` 一致）；其余异常同样统一走失败分支。
+    步与路径的对应关系是**行主序**：一维数组的前 `n_steps` 个元素属于第 1 条路径。
 
     Examples
     --------
+    >>> import numpy as np
     >>> r = random_walk(n_steps=100, n_paths=5, random_state=0)
     >>> r.data.shape
     (5, 101)
+    >>> bool(np.all(np.abs(np.diff(r.data, axis=1)) == 1))   # 默认步长恒为 1
+    True
     """
-    # TODO(L1)
+    if isinstance(n_steps, bool) or not isinstance(n_steps, (int, np.integer)):
-    raise NotImplementedError
+        raise TypeError(f"n_steps 必须是整数，你传入了 {type(n_steps).__name__}")
+    if n_steps <= 0:
+        raise ValueError(f"n_steps 必须是正整数，你传入了 {n_steps}")
+
+    if isinstance(n_paths, bool) or not isinstance(n_paths, (int, np.integer)):
+        raise TypeError(f"n_paths 必须是整数，你传入了 {type(n_paths).__name__}")
+    if n_paths <= 0:
+        raise ValueError(f"n_paths 必须是正整数，你传入了 {n_paths}")
+
+    if not isinstance(start, (int, float, np.number)):
+        raise TypeError(f"start 必须是数值，你传入了 {type(start).__name__}")
+
+    rng = get_rng(random_state)
+
+    if step_sampler is None:
+        def _default_step_sampler(rng, size):
+            return rng.choice([-1.0, 1.0], size=size)
+
+        step_sampler = _default_step_sampler
+
+    call_params = {
+        "n_steps": n_steps,
+        "n_paths": n_paths,
+        "start": start,
+        "random_state": random_state,
+    }
+
+    try:
+        steps = np.asarray(step_sampler(rng, size=n_paths * n_steps), dtype=float)
+        if steps.shape != (n_paths * n_steps,):
+            raise ValueError(
+                f"step_sampler 返回长度必须为 {n_paths * n_steps}，实际得到了 {steps.shape}"
+            )
+        if np.isnan(steps).any():
+            raise ValueError("step_sampler 生成的增量数据中包含 NaN，请检查采样逻辑")
+
+        steps = steps.reshape(n_paths, n_steps)   # 行主序：前 n_steps 个属于第 1 条路径
+
+        cumsum = np.cumsum(steps, axis=1)
+
+        paths = np.zeros((n_paths, n_steps + 1), dtype=float)
+        paths[:, 0] = start
+        paths[:, 1:] = start + cumsum
+
+        terminal_positions = paths[:, -1]
+        metrics = {
+            "mean_terminal": float(np.mean(terminal_positions)),
+            "std_terminal": float(np.std(terminal_positions))
+        }
+
+        return Result(
+            name="random_walk",
+            params=call_params,
+            metrics=metrics,
+            data=paths,
+            success=True,
+            message=f"随机游走模拟成功：生成了 {n_paths} 条路径，每条路径 {n_steps} 步。"
+        )
+    except Exception as e:
+        return Result(
+            name="random_walk",
+            params=call_params,
+            metrics={},
+            data=None,
+            success=False,
+            message=f"随机游走模拟失败：{type(e).__name__} - {str(e)}"
+        )
 
 
 def markov_simulate(
     transition: Any,
     initial: Any,
-    steps: int = 100,
+    steps: int | np.integer = 100,
-    n_paths: int = 1,
+    n_paths: int | np.integer = 1,
     random_state: int | None = None,
 ) -> Any:
-    """马尔可夫链模拟，返回状态序列。"""
+    """马尔可夫链模拟：从 `initial` 出发，按 `transition` 逐行走 `steps` 步。
-    # TODO(L1)
-    raise NotImplementedError
-
-
-def markov_steady_state(transition: Any, max_iter: int = 10000, tol: float = 1e-10) -> Any:
-    """平稳分布。
 
     Parameters
     ----------
     transition:
-        行随机矩阵（每行和为 1）。
+        行随机矩阵（每行和为 1）的二维方阵，状态数就是它的阶数 `s`。
+    initial:
+        初始状态。**标量整数**时所有路径都从同一状态出发；
+        否则按一维数组处理，长度必须等于状态数 `s`，再写进每条路径的第 0 列
+        —— 只有 `n_paths == s` 时两者才对得上，见 Notes。
+    steps:
+        每条路径的步数，正整数。`data` 的列数是 `steps + 1`（多出的第 0 列是初始状态）。
+    n_paths:
+        路径条数，正整数，默认 1 条。
+    random_state:
+        随机种子。`None` 时跟随 `core.set_seed` 的全局流，见 `core.random.get_rng`。
 
     Returns
     -------
-    `Result`：`data` 是平稳分布向量，`metrics={"converged", "iterations"}`。
+    `Result`：`data` 是形状 `(n_paths, steps + 1)` 的整数状态序列，第 0 列是初始状态；
+    `metrics={"mean_terminal", "terminal_distribution"}` —— 前者是终点状态的均值，
+    后者是 `{状态: 出现频率}` 的 dict（按终点统计，只含**实际出现过**的状态，没出现的状态没有 key）。
+
+    Raises
+    ------
+    TypeError:
+        `transition` 不是二维数组；`initial` 数组长度不等于状态数；
+        `steps` / `n_paths` 不是整数。
+    ValueError:
+        `transition` 不是方阵，或某一行和不等于 1.0；`steps` / `n_paths` 不是正整数。
+
+    Notes
+    -----
+    抽样用逆变换法：`cumsum` 得到累积分布，再拿 `[0, 1)` 的均匀数去"落格"。
+    一次抽完 `n_paths` 个状态，路径之间相互独立；步与步之间只能串行，因为下一步依赖当前状态。
+    `cum_probs[:, -1] = 1.0` 是为了压掉浮点累加误差，避免随机数落在 `[1 - 1e-16, 1)` 时索引越界。
+    终点分布随步数收敛到平稳分布：这既是本函数的自检手段，也是论文里值得写一句的性质。
+
+    遗留（决策 56）：`initial` 靠 `isinstance(initial, (int, np.integer))` 区分"标量状态 / 状态数组"，
+    `np.int64` 已收，但 `bool` 仍会被当成状态 1（`isinstance(True, int)` 为真）；
+    且数组分支"按**状态数**校验长度"与真正写进去时"要按**路径数**"仍互相矛盾 —— 只有 `n_paths == s` 才跑得通。
+    状态越界（如 `initial=5`、`s=2`）也要等第一轮索引才炸。口径定了这段随之改写。
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> P = np.array([[0.9, 0.1], [0.2, 0.8]])
+    >>> r = markov_simulate(P, initial=0, steps=50, n_paths=4, random_state=0)
+    >>> r.data.shape
+    (4, 51)
+    >>> bool(np.all(r.data[:, 0] == 0))
+    True
+    """
+    arr, _ = as_array(transition)
+    if arr.ndim != 2 or arr.shape[0] != arr.shape[1]:
+        raise ValueError(f"transition 必须是二维方阵，你传入的形状是 {arr.shape}")
+    if np.any(arr < -1e-12):
+        raise ValueError("transition 矩阵的元素必须是非负的")
+    if not np.allclose(arr.sum(axis=1), 1.0):
+        raise ValueError("transition 每一行的和必须是 1.0")
+    s = arr.shape[0]
+
+    if isinstance(n_paths, bool) or not isinstance(n_paths, (int, np.integer)):
+        raise TypeError(f"n_paths 必须是整数，你传入了 {type(n_paths).__name__}")
+    if n_paths <= 0:
+        raise ValueError(f"n_paths 必须是正整数，你传入了 {n_paths}")
+    if isinstance(steps, bool) or not isinstance(steps, (int, np.integer)):
+        raise TypeError(f"steps 必须是整数，你传入了 {type(steps).__name__}")
+    if steps <= 0:
+        raise ValueError(f"steps 必须是正整数，你传入了 {steps}")
+
+    rng = get_rng(random_state)
+
+    if isinstance(initial, (int,np.integer)):
+        current_states = np.full(n_paths, initial)
+        initial_param = int(initial)
+    else:
+        current_states, _ = as_array(initial, ndim=1)
+        if len(current_states) != s:
+            raise TypeError(f"initial 的长度必须是 {s}，而你传入的是 {len(current_states)}")
+        initial_param = current_states.tolist()
+
+    call_params = {
+        "steps": steps,
+        "n_paths": n_paths,
+        "initial": initial_param,
+        "random_state": random_state
+    }
+
+    try:
+        paths = np.zeros((n_paths, steps + 1), dtype=int)
+        paths[:, 0] = current_states
+        for t in range(steps):
+            probs = arr[current_states]
+
+            cum_probs = np.cumsum(probs, axis=1)
+            cum_probs[:, -1] = 1.0
+
+            r = rng.random(n_paths)
+            next_states = (cum_probs < r[:, None]).sum(axis=1)
+
+            paths[:, t + 1] = next_states
+            current_states = next_states
+
+        terminal_positions = paths[:, -1]
+        unique, counts = np.unique(terminal_positions, return_counts=True)
+        terminal_dist = {int(state): float(count) / n_paths for state, count in zip(unique, counts, strict=True)}
+
+        metrics = {
+            "mean_terminal": float(np.mean(terminal_positions)),
+            "terminal_distribution": terminal_dist
+        }
+        return Result(
+            name="markov_simulate",
+            params=call_params,
+            metrics=metrics,
+            data=paths,
+            success=True,
+            message=f"马尔可夫链模拟成功，生成了 {n_paths} 条路径，每条路径 {steps} 步",
+        )
+    except Exception as e:
+        return Result(
+            name="markov_simulate",
+            params=call_params,
+            metrics={},
+            data=None,
+            success=False,
+            message=f"马尔可夫链模拟失败：{type(e).__name__} - {str(e)}",
+        )
+
+
+def markov_steady_state(transition: Any, max_iter: int | np.integer = 10000, tol: float = 1e-10) -> Any:
+    """迭代法求马尔可夫链的平稳分布（`v @ P` 反复推进，直到相邻两次几乎不变）。
+
+    Parameters
+    ----------
+    transition:
+        行随机矩阵（每行和为 1）的二维方阵。
+    max_iter:
+        迭代上限，正整数，默认 10000。
+    tol:
+        收敛阈值，正数，默认 1e-10。判据是**相邻两次迭代的最大分量差**
+        `max|v_k+1 - v_k| < tol`，不是"到不动点的距离"，见 Notes。
+
+    Returns
+    -------
+    `Result`：`data` 是一维平稳分布向量（和为 1）；
+    `metrics={"converged", "iterations"}`（是否在 `max_iter` 内向容、实际迭代次数）。
+
+    Raises
+    ------
+    TypeError:
+        `transition` 不是二维方阵；`max_iter` 不是整数；`tol` 不是数值。
+    ValueError:
+        `transition` 含负元素、或某一行和不等于 1.0；
+        `max_iter` 不是正整数；`tol` 不是正数（NaN 也算非法）。
 
     Notes
     -----
     用迭代法而不是特征分解：迭代法能顺便告诉你"收敛快不快"，
     而收敛速度本身就是论文里值得写一句的性质。
-    **不可约 + 非周期**才有唯一平稳分布，周期链会不收敛，要检查。
+    初值是**均匀分布** `1/s`；**不可约 + 非周期**才有唯一平稳分布。
+    可约链（如单位阵 `eye(2)`）的平稳分布不唯一，迭代法给出的是"离初值最近的那个"
+    —— 均匀初值对双随机矩阵本身就是不动点，所以 `converged=True, iterations=1` 只说明"初值恰是不动点"，
+    不代表这条链有唯一平稳分布；周期链从一般初值出发会一直振荡、`converged=False`。
+
+    `tol` 是**相邻差**口径，实际误差约被 `1 / (1 - |λ2|)` 放大：实测双状态慢混合链
+    `[[0.999, 0.001], [0.02, 0.98]]`（`|λ2| = 0.979`）用默认 `tol=1e-10` 停在第 867 次，
+    与特征向量相差 `4.6e-9`（约 50 倍）。慢混合链要更准，把 `tol` 压小即可。
 
     Examples
     --------
@@ -184,8 +645,67 @@ def markov_steady_state(transition: Any, max_iter: int = 10000, tol: float = 1e-
     >>> bool(np.allclose(r.data, [2 / 3, 1 / 3], atol=1e-6))
     True
     """
-    # TODO(L1)
+    arr, _ = as_array(transition)
-    raise NotImplementedError
+    if arr.ndim != 2 or arr.shape[0] != arr.shape[1]:
+        raise TypeError(f"transition 必须是二维方阵，你传入的形状是 {arr.shape}")
+    if np.any(arr < -1e-12):
+        raise ValueError("transition 矩阵的元素必须是非负的（概率不能为负）")
+    if not np.allclose(arr.sum(axis=1), 1.0):
+        raise ValueError("transition 每一行的和必须是 1.0")
+
+    if isinstance(max_iter, bool) or not isinstance(max_iter, (int, np.integer)):
+        raise TypeError(f"max_iter 必须是正整数，你传入了 {type(max_iter).__name__}")
+    if max_iter <= 0:
+        raise ValueError(f"max_iter 必须是正整数，你传入了 {max_iter}")
+    if not isinstance(tol, (int, float)) or isinstance(tol, bool):
+        raise TypeError(f"tol 必须是浮点数，你传入了 {type(tol).__name__}")
+    if tol <= 0 or np.isnan(tol):
+        raise ValueError(f"tol 必须是正数，你传入了 {tol}")
+
+    s = arr.shape[0]
+    v = np.full(s, 1.0 / s)
+
+    iterations = 0
+    converged = False
+    call_params = {
+        "transition": arr.tolist(),
+        "max_iter": max_iter,
+        "tol": tol,
+    }
+
+    try:
+        for _ in range(max_iter):
+            v_next = v @ arr
+            error = np.max(np.abs(v_next - v))
+            v = v_next
+            iterations += 1
+
+            if error < tol:
+                converged = True
+                break
+
+        metrics = {
+            "converged": converged,
+            "iterations": iterations
+        }
+
+        return Result(
+            name="markov_steady_state",
+            params=call_params,
+            metrics=metrics,
+            data=v,
+            success=converged,
+            message=f"平稳分布求解{'成功' if converged else '失败：未在最大迭代次数内收敛'}，迭代 {iterations} 次。"
+        )
+    except Exception as e:
+        return Result(
+            name="markov_steady_state",
+            params=call_params,
+            metrics={},
+            data=None,
+            success=False,
+            message=f"平稳分布求解异常：{type(e).__name__} - {str(e)}"
+        )
 
 
 def mm1_metrics(arrival_rate: float, service_rate: float) -> Any:
@@ -194,13 +714,23 @@ def mm1_metrics(arrival_rate: float, service_rate: float) -> Any:
     Parameters
     ----------
     arrival_rate, service_rate:
-        到达率 λ 与服务率 μ。`λ >= μ` 时系统不稳定，队列长度无界——
+        到达率 λ 与服务率 μ，都收 `int` / `float` / numpy 标量。
-        这种情况下函数返回 `success=False` 并说明原因，而不是返回 `inf`。
+        `λ` 允许为 0（空系统：`L = Lq = Wq = 0`，`W` 取极限值 `1/μ`）；
+        `λ >= μ` 时系统不稳定、队列长度无界 —— 这种情况返回 `success=False` 并说明原因，而不是返回 `inf`。
 
     Returns
     -------
     `Result`：`metrics={"rho", "L", "Lq", "W", "Wq"}`
-    （系统利用率、系统内平均顾客数、队列长度、平均逗留时间、平均等待时间）。
+    （系统利用率、系统内平均顾客数、队列长度、平均逗留时间、平均等待时间）；
+    `data` 与 `metrics` 同值（闭式解没有样本数组），但**不是同一个对象**。
+    不稳定时 `success=False`、`metrics={{"rho"}}`（只报利用率）、`data=None`。
+
+    Raises
+    ------
+    TypeError:
+        `arrival_rate` / `service_rate` 不是数值（`bool` 也判非法）。
+    ValueError:
+        `arrival_rate` 是负数；`service_rate` 不是正数。
 
     Notes
     -----
@@ -214,5 +744,57 @@ def mm1_metrics(arrival_rate: float, service_rate: float) -> Any:
     >>> round(r.metrics["rho"], 4)
     0.6667
     """
-    # TODO(L1)
+    if not isinstance(arrival_rate, (int, float, np.number)) or isinstance(arrival_rate, bool):
-    raise NotImplementedError
+        raise TypeError(f"arrival_rate 必须是浮点数，你传入了 {type(arrival_rate).__name__}")
+    if arrival_rate < 0:
+        raise ValueError(f"arrival_rate 必须是非负数，你传入了 {arrival_rate}")
+    if not isinstance(service_rate, (int, float, np.number)) or isinstance(service_rate, bool):
+        raise TypeError(f"service_rate 必须是浮点数，你传入了 {type(service_rate).__name__}")
+    if service_rate <= 0:
+        raise ValueError(f"service_rate 必须是正数，你传入了 {service_rate}")
+
+    call_params = {"arrival_rate": float(arrival_rate), "service_rate": float(service_rate)}
+
+    if arrival_rate >= service_rate:
+        rho = arrival_rate / service_rate
+        return Result(
+            name="mm1_metrics",
+            params=call_params,
+            metrics={"rho": float(rho)},
+            data=None,
+            success=False,
+            message=f"系统不稳定：λ >= μ，队列无界。当前利用率 rho={rho:.4f}"
+        )
+    try:
+        rho = arrival_rate / service_rate
+        L = rho / (1.0 - rho)                   # 系统内平均顾客数
+        Lq = rho ** 2 / (1.0 - rho)             # 队列中平均等待顾客数
+        W = 1.0 / (service_rate - arrival_rate) # 平均逗留时间
+        Wq = W - 1.0 / service_rate             # 平均等待时间
+
+        metrics = {
+            "rho": float(rho),
+            "L": float(L),
+            "Lq": float(Lq),
+            "W": float(W),
+            "Wq": float(Wq)
+        }
+
+        return Result(
+            name="mm1_metrics",
+            params=call_params,
+            metrics=metrics,
+            data=metrics.copy(),
+            success=True,
+            message="M/M/1 排队系统指标计算成功。"
+        )
+
+    except Exception as e:
+        return Result(
+            name="mm1_metrics",
+            params=call_params,
+            metrics={},
+            data=None,
+            success=False,
+            message=f"计算失败：{type(e).__name__} - {str(e)}"
+        )

src/mcm_toolkit/stats/__init__.py

@@ -11,6 +11,8 @@ from .inference import (
     chi_square_test,
     confidence_interval,
     correlation_matrix,
+    correlation_pvalues,
+    correlation_table,
     fit_distribution,
     goodness_of_fit,
     t_test,
@@ -21,6 +23,8 @@ __all__ = [
     "zscore",
     "coefficient_of_variation",
     "correlation_matrix",
+    "correlation_pvalues",
+    "correlation_table",
     "confidence_interval",
     "t_test",
     "anova",

src/mcm_toolkit/stats/bootstrap.py

@@ -10,6 +10,10 @@ from __future__ import annotations
 from collections.abc import Callable
 from typing import Any
 
+import numpy as np
+
+from ..core import Result, as_array, get_rng
+
 __all__ = ["bootstrap_ci", "bootstrap_statistic"]
 
 
@@ -42,23 +46,46 @@ def bootstrap_ci(
 
     Parameters
     ----------
+    x:
+        样本：`pandas.DataFrame` / `pandas.Series` / `numpy.ndarray` / list / tuple。
+        走 `core.as_array(x, numeric_only=True, ndim=1)` —— DataFrame 只取数值列，再摊平成一串样本。
     statistic:
         任意把样本映射成标量的函数，默认 `np.mean`。
         换成 `np.median` / `np.std` / 自定义的 `lambda s: s.max() - s.min()` 都能用，
         这是 bootstrap 相对于 `mean ± z·s/√n` 的核心优势。
+    confidence:
+        置信水平，取 `(0, 1)` 开区间，默认 0.95。
+    n_resamples:
+        重采样次数，默认 10000。论文里必须写明。
     method:
         `"percentile"`：直接取经验分布的 α/2 与 1-α/2 分位（最常用，默认）；
-        `"bca"`：偏差校正 + 加速，区间更准但慢，样本有偏时用。
+        `"bca"`：偏差校正 + 加速，区间更准但慢，样本有偏时用 —— **尚未实现**，传了抛
+        `NotImplementedError`。
+    random_state:
+        随机种子。传 `None` 时复用 `core.get_rng` 的**模块级生成器且会推进**，
+        所以同一段脚本里连调两次结果不同；要完全可复现就显式给种子，或先 `core.set_seed`。
 
     Returns
     -------
-    `Result`：`params={"estimate", "low", "high", "confidence", "n_resamples"}`。
+    `Result`：`params={"estimate", "low", "high", "confidence", "n_resamples"}`；
+    `metrics["statistic_name"]` 是统计量的名字（自定义 lambda 时是 `"custom"`）。
+
+    Raises
+    ------
+    TypeError
+        `x` 不是受支持的容器，或内容转不成数值（由 `as_array` 抛）。
+    ValueError
+        `DataFrame` 里一列数值都没有；`method` 不在支持列表内。
+    NotImplementedError
+        `method="bca"`。
 
     Notes
     -----
     * 重采样时必须**按块处理**，不要一次生成 `(10000, n)` 的整矩阵（n 大时会爆内存）。
     * 样本量 n < 10 时 bootstrap 不可靠，先补数据。
-    * 比赛写论文时要注明：n_resamples、seed、用的是 percentile 还是 BCa。
+    * 比赛写论文时要注明：n_resamples、seed、用的是 percentile 还是 BCa（目前只实现了 percentile）。
+    * **缺失值目前不处理**：`x` 里的 NaN 会直接进统计量，`np.mean` 于是给出 nan 区间。
+      `confidence_interval` / `t_test` 都是先丢掉 NaN 的，两边口径尚未统一。
 
     Examples
     --------
@@ -67,5 +94,57 @@ def bootstrap_ci(
     >>> r.params["low"] < 3 < r.params["high"]
     True
     """
-    # TODO(L0)  ★ S 档：配完整函数卡片
+    if statistic is None:
-    raise NotImplementedError
+        statistic = np.mean
+
+    rng = get_rng(random_state)
+
+    arr, _ = as_array(x=x, dtype=float, ndim=1)
+
+    original_estimate = float(statistic(arr))
+
+    n = len(arr)
+    batch_size = 1000
+    boot_stats = []
+
+    for i in range(0, n_resamples, batch_size):
+        current_batch = min(batch_size, n_resamples - i)
+        indices = rng.integers(0, n, size=(current_batch, n))
+        batch_samples = arr[indices]
+
+        if statistic in [np.mean, np.median, np.std, np.min, np.max]:
+            batch_stats = statistic(batch_samples, axis=1)
+        else:
+            batch_stats = np.array([statistic(s) for s in batch_samples])
+
+        boot_stats.extend(np.asarray(batch_stats).ravel().tolist())
+
+    boot_stats = np.array(boot_stats)
+
+    if method == 'percentile':
+        alpha = 1 - confidence
+        lower = np.percentile(boot_stats, alpha / 2 * 100)
+        upper = np.percentile(boot_stats, (1 - alpha / 2) * 100)
+    elif method == 'bca':
+        # TODO(L1): BCa = 偏差校正 + 加速，属于 S 档、留给用户自己补的算法。
+        raise NotImplementedError("BCa 还没实现，先用 method='percentile'")
+    else:
+        raise ValueError(f"不支持的方法:{method},仅支持'percentile'")
+
+    # lambda 也有 __name__（值恒为 "<lambda>"），所以只判断 hasattr 会让 "custom" 这支变成死代码。
+    name = getattr(statistic, "__name__", None)
+    statistic_name = "custom" if name in (None, "<lambda>") else str(name)
+
+    return Result(
+        name="bootstrap_ci",
+        params={
+            "estimate": original_estimate,
+            "low": float(lower),
+            "high": float(upper),
+            "confidence": confidence,
+            "n_resamples": n_resamples
+        },
+        metrics={
+            "statistic_name": statistic_name,
+        }
+    )

src/mcm_toolkit/stats/descriptive.py

@@ -6,35 +6,204 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, cast
+
+import numpy as np
+import pandas as pd
+
+from ..core.validate import as_array
 
 __all__ = ["coefficient_of_variation", "describe", "zscore"]
 
 
-def describe(x: Any, weights: Any | None = None) -> Any:
+def describe(x: Any, weights: Any | None = None) -> pd.DataFrame:
     """一张表看完集中趋势、离散程度、偏度峰度、缺失情况。
 
     `weights` 非空时给出加权均值与加权标准差（权重是"频数"或"重要性"时用）。
 
+    Parameters
+    ----------
+    x:
+        `pandas.DataFrame` / `pandas.Series` / list / tuple / `numpy.ndarray`。
+        **只描述数值列**，非数值列自动跳过。
+    weights:
+        与 `x` 行数等长的**非负**权重，类型同 `x` 可接受的那几种；
+        `None` 表示不给加权行。
+
     Returns
     -------
-    DataFrame，行是指标，列是被描述的变量。
+    pandas.DataFrame
+        行是指标，列是被描述的变量。指标依次为
+        `count` / `mean` / `std` / `min` / `25%` / `50%` / `75%` / `max` /
+        `median` / `missing` / `missing_ratio` / `skewness` / `kurtosis`；
+        给了 `weights` 时再追加 `weighted_mean` / `weighted_std`。
+        返回的是新表，原表不改。
+
+    Raises
+    ------
+    TypeError
+        `x` 或 `weights` 的类型不支持。
+    ValueError
+        `x` 里没有数值列；或 `weights` 无法转成数值、不是一维、长度与行数不符、
+        含 NaN / inf、含负值、求和为 0。
+
+    Notes
+    -----
+    每个指标都**按列独立**计算；含缺失时 pandas 会自动跳过该单元格（`count` 因此
+    可能小于行数，缺失量看 `missing` / `missing_ratio`）。
+    加权标准差用总体口径（`ddof=0`）。含 NaN 的列加权后仍是 NaN ——
+    加权前请先用 `impute_missing` 补好。
 
     Examples
     --------
     >>> describe(df).loc["mean"]              # doctest: +SKIP
     """
-    # TODO(L0)
+    allowed_types = (pd.DataFrame, pd.Series, list, tuple, np.ndarray)
-    raise NotImplementedError
+    if not isinstance(x, allowed_types):
+        raise TypeError(f"x 必须是{allowed_types},而你输入了{type(x)}")
+
+    if not isinstance(x, pd.DataFrame):
+        x = pd.DataFrame(x)
+
+    numeric_cols = x.select_dtypes(include=["number"]).columns
+    if len(numeric_cols) == 0:
+        raise ValueError("x 里没有数值列,无法描述")
+
+    # df[Index] 在 pandas 存根里是 DataFrame | Series 重载，按运行时真值收窄（坑 8）
+    df_num = cast(pd.DataFrame, x[numeric_cols])
+
+    # 这里**不要转置**。describe() 出来就是"行 = 指标、列 = 变量"，正好让下面
+    # `.loc[指标名] = <按变量索引的 Series>` 能按列名对齐；一旦转置，Series 的索引
+    # 与表的列名不相交，pandas 会不报错地**把整行填成 NaN**（旧的静默 bug）。
+    table = df_num.describe()
+    table.loc["median"] = df_num.median()
+    table.loc["missing"] = df_num.isna().sum()
+    table.loc["missing_ratio"] = df_num.isna().mean()
+    table.loc["skewness"] = df_num.skew()
+    table.loc["kurtosis"] = df_num.kurt()
+
+    if weights is not None:
+        allowed_weight_types = (list, tuple, np.ndarray, pd.Series)
+        if not isinstance(weights, allowed_weight_types):
+            raise TypeError(f"weights 必须是{allowed_weight_types},而你输入了{type(weights)}")
+
+        try:
+            w_arr = np.asarray(weights, dtype=float)
+        except (ValueError, TypeError) as e:
+            raise ValueError(f"weights 无法转成数值数组,请检查是否含非数值字符:{e}") from None
+
+        if w_arr.ndim != 1:
+            raise ValueError(f"weights 必须是一维数组,而你传入了 {w_arr.ndim} 维")
+        if len(w_arr) != len(df_num):
+            raise ValueError(f"权重 weights 的长度({len(w_arr)})必须与数据的行数({len(df_num)})一致")
+        if not np.isfinite(w_arr).all():
+            raise ValueError("weights 含 NaN 或 inf,无法加权")
+        if (w_arr < 0).any():
+            raise ValueError("weights 不能含负值")
+        if w_arr.sum() == 0:
+            raise ValueError("weights 之和为 0,无法加权")
+
+        weighted_mean = np.average(df_num, axis=0, weights=w_arr)
+        weighted_std = np.sqrt(np.average((df_num - weighted_mean) ** 2, axis=0, weights=w_arr))
+
+        table.loc["weighted_mean"] = weighted_mean
+        table.loc["weighted_std"] = weighted_std
+
+    return table
 
 
 def zscore(x: Any, ddof: int = 0) -> Any:
-    """标准化到 z 分数，顺带回答了"这个值离均值几个标准差"。"""
+    """标准化到 z 分数，顺带回答了"这个值离均值几个标准差"。
-    # TODO(L0)
+
-    raise NotImplementedError
+    Parameters
+    ----------
+    x:
+        `pandas.DataFrame` / `pandas.Series` / list / tuple / `numpy.ndarray`。
+        DataFrame **只取数值列**，非数值列不会出现在结果里。
+    ddof:
+        标准差的自由度修正，与 `numpy.std` 同名参数含义一致；`0` 为总体标准差。
+
+    Returns
+    -------
+    numpy.ndarray / pandas.Series / pandas.DataFrame
+        与 `x` 同类型；DataFrame 只保留数值列，列名与索引不变。
+        常量列（`std == 0`）不产生 nan / inf，固定输出 0（决策 34）。
+
+    Raises
+    ------
+    TypeError
+        `x` 类型不支持。
+    ValueError
+        DataFrame 里一列数值列都没有。
+
+    Notes
+    -----
+    与 `data.transform.standardize` 是同一个公式；差别只在 DataFrame 里遇到
+    非数值列时：这里**跳过**，`standardize` 会直接抛错。
+    """
+    arr, kind = as_array(x, numeric_only=True)
+
+    mean = np.mean(arr, axis=0)
+    std = np.std(arr, axis=0, ddof=ddof)
+
+    std = np.where(std == 0, 1.0, std)
+
+    result = (arr - mean) / std
+    if kind == "frame":
+        # 列名口径与 as_array(numeric_only=True) 一致，都是只取数值列
+        cols = x.select_dtypes(include=[np.number]).columns
+        return pd.DataFrame(result, index=x.index, columns=cols)
+    if kind == "series":
+        return pd.Series(result, index=x.index, name=x.name)
+    return result
 
 
 def coefficient_of_variation(x: Any) -> float:
-    """变异系数 `std / mean` —— 跨量纲比较"谁更波动"时的唯一正确做法。"""
+    """变异系数 `std / |mean|` —— 跨量纲比较"谁更波动"时的唯一正确做法。
-    # TODO(L1)
+
-    raise NotImplementedError
+    Parameters
+    ----------
+    x:
+        一维数据：`pandas.Series` / list / tuple / `numpy.ndarray`，
+        或只有一列的 `pandas.DataFrame`。
+
+    Returns
+    -------
+    float
+        `std / |mean|`，标准差按总体口径（`ddof=0`）。恒非负。
+
+    Raises
+    ------
+    TypeError
+        `x` 类型不支持。
+    ValueError
+        数据为空、不是一维（或 DataFrame 列数不为 1）、或均值为 0。
+
+    Notes
+    -----
+    分母取的是 `|mean|`：均值为负时 CV 仍是正数，不会因为符号反过来被误读成"波动更小"。
+    但 CV 的**可比性**仍然只在均值远离 0 的比率尺度数据上成立 —— 均值接近 0 时
+    CV 会被放大到任意大，那种数据请换用别的离散度指标。
+    """
+    allowed_type = (list, tuple, np.ndarray, pd.Series)
+    if isinstance(x, pd.DataFrame):
+        if x.shape[1] != 1:
+            raise ValueError(f"变异系数只适用于一维数据,而你传入了 {x.shape[1]} 列的 DataFrame")
+        arr = np.asarray(x.iloc[:, 0], dtype=float)
+    elif isinstance(x, allowed_type):
+        arr = np.asarray(x, dtype=float)
+        if arr.ndim != 1:
+            raise ValueError(f"变异系数只适用于一维数据,而你传入了 {arr.ndim} 维数组")
+    else:
+        raise TypeError(f"x 必须是{allowed_type}或单列 pd.DataFrame,而你传入了{type(x)}")
+
+    if arr.size == 0:
+        raise ValueError("数据为空,无法计算变异系数")
+
+    mean = np.mean(arr)
+    std = np.std(arr, ddof=0)
+
+    if mean == 0:
+        raise ValueError("均值为 0,无法计算变异系数(分母为 0)")
+
+    return np.abs(float(std / mean))

src/mcm_toolkit/stats/inference.py

@@ -7,32 +7,209 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Literal, cast
+
+import numpy as np
+import pandas as pd
+import scipy.stats as stats
+
+from ..core.validate import as_array
 
 __all__ = [
     "anova",
     "chi_square_test",
     "confidence_interval",
     "correlation_matrix",
+    "correlation_pvalues",
+    "correlation_table",
     "fit_distribution",
     "goodness_of_fit",
     "t_test",
 ]
 
 
-def correlation_matrix(data: Any, method: str = "pearson", min_periods: int = 1) -> Any:
+def _pvalue(result: Any) -> float:
-    """相关矩阵 + 显著性星标。
+    """把 scipy 检验结果取成 p 值（float）。
+
+    scipy 的 `SignificanceResult` / `PearsonRResult` 是 `_make_tuple_bunch` 在**运行时**
+    拼出来的类，类型检查器看不到 `pvalue` 字段 —— 这里显式收成 `Any` 再取，
+    比给每一处调用挂 `# type: ignore` 干净，后面 `t_test` / `anova` 也能复用。
+    """
+    return float(result.pvalue)
+
+
+def _statistic(result: Any) -> float:
+    """把 scipy 检验结果取成**统计量**（float）。
+
+    与 `_pvalue` 同一个原因：`TtestResult` 也是 `_make_tuple_bunch` 运行时拼的类，
+    存根里看不到 `statistic` 字段（见 `docs/04-environment.md` 坑 10）。
+    """
+    return float(result.statistic)
+
+
+_VALID_CORR_METHODS = ("pearson", "kendall", "spearman")
+_VALID_CONFIDENCE_METHODS = ("normal", "t", "proportion")
+
+
+def _check_corr_args(data: Any, method: str) -> pd.DataFrame:
+    """三个 `correlation_*` 共用的入参守卫，返回收窄后的**数值子表**。"""
+    if not isinstance(data, pd.DataFrame):
+        raise TypeError(f"data必须是 pd.DataFrame,而你传的是{type(data)}")
+    if method not in _VALID_CORR_METHODS:
+        raise ValueError(f"不支持的方法:{method},仅支持{list(_VALID_CORR_METHODS)}")
+    numeric_cols = data.select_dtypes(include=[np.number]).columns
+    if len(numeric_cols) == 0:
+        raise ValueError("没有找到数值列")
+    # data[Index] 在 pandas 存根里是 DataFrame | Series 重载，按运行时真值收窄（坑 8）
+    return cast(pd.DataFrame, data[numeric_cols])
+
+
+def correlation_matrix(
+    data: Any,
+    method: Literal["pearson", "kendall", "spearman"] = "pearson",
+    min_periods: int = 1,
+) -> pd.DataFrame:
+    """相关系数矩阵（**数值**，不带星标）。
+
+    Parameters
+    ----------
+    data:
+        必须是 `pandas.DataFrame`。**只有数值列参与**，非数值列自动跳过。
+    method:
+        `"pearson"` / `"kendall"` / `"spearman"`。
+    min_periods:
+        每对变量至少要有这么多个**共同非缺失**的观测才给相关系数，透传给 `DataFrame.corr`。
+        （pandas 对每对变量都是**成对删缺失**，不是整行删。）
 
     Returns
     -------
-    DataFrame，值 = 相关系数；`min_periods` 控制缺失值容差。
+    pandas.DataFrame
+        对称矩阵，对角线恒为 `1.0`；观测不足的格子是 NaN。
+
+    Raises
+    ------
+    TypeError
+        `data` 不是 `pandas.DataFrame`。
+    ValueError
+        `data` 里没有数值列，或 `method` 不在支持列表内。
+
+    Notes
+    -----
+    要"系数 + 显著性星标"的论文表格用 `correlation_table`；要 p 值矩阵用 `correlation_pvalues`。
+    之所以拆开：这张表是**数值**，能挑高相关对、喂聚类 / PCA、画热力图；星标字符串表这些都做不了。
 
     Examples
     --------
     >>> correlation_matrix(df).round(3)       # doctest: +SKIP
     """
-    # TODO(L0)
+    df_num = _check_corr_args(data, method)
-    raise NotImplementedError
+    return df_num.corr(method=method, min_periods=min_periods)
+
+
+def correlation_pvalues(
+    data: Any,
+    method: Literal["pearson", "kendall", "spearman"] = "pearson",
+    min_periods: int = 1,
+) -> pd.DataFrame:
+    """`correlation_matrix` 对应的 **p 值矩阵**（数值，不含星标）。
+
+    Parameters
+    ----------
+    data / method / min_periods:
+        含义与 `correlation_matrix` 完全一致，两者一定同形。
+
+    Returns
+    -------
+    pandas.DataFrame
+        对称矩阵。**对角线是 NaN** —— "自己和自己相关"没有 p 值可言，
+        写成 `0.0` 会被下游读成"极显著"。
+
+    Raises
+    ------
+    TypeError / ValueError:
+        同 `correlation_matrix`。
+
+    Notes
+    -----
+    每对变量都先**成对删缺失**再算，与 `DataFrame.corr` 的口径一致 ——
+    否则 r 和 p 会基于不同的样本量，对不上；成对有效观测少于 `min_periods` 时给 NaN。
+    只算上三角再镜像，成对变量的 p 天然对称，省掉一半重复计算。
+    """
+    df_num = _check_corr_args(data, method)
+    corr = df_num.corr(method=method, min_periods=min_periods)
+
+    p_values = pd.DataFrame(np.nan, index=corr.index, columns=corr.columns, dtype=float)
+    for i in range(len(corr.columns)):
+        for j in range(i + 1, len(corr.columns)):
+            pair = df_num.iloc[:, [i, j]].dropna()
+            if len(pair) < min_periods:
+                continue
+            x = pair.iloc[:, 0]
+            y = pair.iloc[:, 1]
+            if method == "pearson":
+                p = _pvalue(stats.pearsonr(x, y))
+            elif method == "kendall":
+                p = _pvalue(stats.kendalltau(x, y))
+            else:
+                p = _pvalue(stats.spearmanr(x, y))
+            p_values.iloc[i, j] = p
+            p_values.iloc[j, i] = p
+    return p_values
+
+
+def _star(value: float, p: float) -> str:
+    """把系数与 p 值拼成 `"0.812**"`。p 为 NaN（对角线 / 观测不足）时不加星标。"""
+    text = f"{value:.3f}"
+    if p < 0.001:
+        return text + "***"
+    if p < 0.01:
+        return text + "**"
+    if p < 0.05:
+        return text + "*"
+    return text
+
+
+def correlation_table(
+    data: Any,
+    method: Literal["pearson", "kendall", "spearman"] = "pearson",
+    min_periods: int = 1,
+) -> pd.DataFrame:
+    """可直接贴论文的相关性表：**系数 + 显著性星标**。
+
+    Parameters
+    ----------
+    data / method / min_periods:
+        含义与 `correlation_matrix` 完全一致。
+
+    Returns
+    -------
+    pandas.DataFrame
+        每个格子是字符串，形如 `"0.812**"`。
+        星标：`***` p < 0.001、`**` p < 0.01、`*` p < 0.05，其余不带星。
+        **对角线只显示 `1.000` 不带星标** —— 自己和自己没有显著性可言。
+
+    Raises
+    ------
+    TypeError / ValueError:
+        同 `correlation_matrix`。
+
+    Notes
+    -----
+    这张表**只能看**：格子里是字符串，做不了后续计算。
+    要数值请用 `correlation_matrix`（系数）与 `correlation_pvalues`（p 值）。
+
+    Examples
+    --------
+    >>> print(correlation_table(df))           # doctest: +SKIP
+    """
+    corr = correlation_matrix(data, method=method, min_periods=min_periods)
+    p_values = correlation_pvalues(data, method=method, min_periods=min_periods)
+
+    table = corr.astype(str)
+    for i in range(len(corr)):
+        for j in range(len(corr.columns)):
+            table.iloc[i, j] = _star(corr.iloc[i, j], p_values.iloc[i, j])
+    return table
 
 
 def confidence_interval(
@@ -44,29 +221,152 @@ def confidence_interval(
 
     Parameters
     ----------
+    x:
+        样本。`list` / `tuple` / `numpy.ndarray` / `pandas.Series` / `pandas.DataFrame`；
+        传 DataFrame 时**所有数值列会被摊平成一个样本**，非数值列跳过。
+    confidence:
+        置信水平，取 `(0, 1)` 开区间，默认 0.95。
     method:
         `"normal"`：`mean ± z·s/√n`（n 大时用）；
         `"t"`：小样本用 t 分布（更保守，n < 30 建议用这个）；
-        `"proportion"`：比例的标准误 `√(p(1-p)/n)`。
+        `"proportion"`：比例的标准误 `√(p(1-p)/n)`，结果会被夹到 `[0, 1]`。
+
+    Returns
+    -------
+    tuple[float, float]
+        `(下限, 上限)`，双侧区间。
+
+    Raises
+    ------
+    TypeError
+        `x` 不是受支持的容器类型，或里面的元素转不成数值。
+    ValueError
+        `x` 里没有可用数值；`confidence` 不在 `(0, 1)` 内；
+        `method` 不在支持列表内；样本量不足 2（估不出标准差）。
+
+    Notes
+    -----
+    **只有 `proportion` 会把结果夹到 `[0, 1]`** —— 比例的区间不可能越界。
+    `normal` / `t` 是**均值**的区间，量纲上完全可以落在 `[0, 1]` 之外
+    （平均身高 170cm 的区间下界不可能是 0）；夹一下只会给出**错的下界**。
 
     Examples
     --------
     >>> lo, hi = confidence_interval([1, 2, 3, 4, 5], confidence=0.95)
     """
-    # TODO(L0)
+    # 入口统一走 as_array（容器类型/数值转换的错误口径只有一处）；样本是"一串数"，显式摊平。
-    raise NotImplementedError
+    arr, _ = as_array(x, numeric_only=True, ndim=1)
 
+    if method not in _VALID_CONFIDENCE_METHODS:
+        raise ValueError(f"不支持的方法:{method},仅支持{list(_VALID_CONFIDENCE_METHODS)}")
+    if not 0 < confidence < 1:
+        raise ValueError(f"confidence 必须在 (0, 1) 开区间内,而你传入了{confidence}")
+
+    arr = arr[~np.isnan(arr)]
+    n = len(arr)
+    if n < 2:
+        raise ValueError(f"样本量至少要有 2 个才估得出标准差,而你只有{n}个")
+
+    if method == "proportion":
+        p = float(np.mean(arr))
+        se = float(np.sqrt(p * (1 - p) / n))
+        z = float(stats.norm.ppf(1 - (1 - confidence) / 2))
+        return (max(0.0, p - z * se), min(1.0, p + z * se))
+
+    mean = float(np.mean(arr))
+    se = float(np.std(arr, ddof=1)) / np.sqrt(n)
+    if method == "normal":
+        half = float(stats.norm.ppf(1 - (1 - confidence) / 2)) * se
+    else:
+        half = float(stats.t.ppf(1 - (1 - confidence) / 2, df=n - 1)) * se
+    return (mean - half, mean + half)
 
 def t_test(a: Any, b: Any | None = None, value: float = 0.0, equal_var: bool = False, paired: bool = False, alpha: float = 0.05) -> Any:
-    """t 检验。`b=None` 时是单样本检验。
+    """t 检验：两组均值有没有统计学差异。`b=None` 时是单样本检验。
+
+    Parameters
+    ----------
+    a:
+        第一组样本（`DataFrame` / `Series` / list / tuple / `ndarray`），缺失值自动剔除。
+    b:
+        第二组样本；`None` 表示单样本检验（对照 `value`）。
+    value:
+        单样本检验的原假设均值，`b is None` 时生效。
+    equal_var:
+        `True` 走学生 t（假设方差齐性），`False` 走 Welch（不假设，默认，更稳）。
+    paired:
+        配对样本检验；要求 `a` 与 `b` 等长。
+    alpha:
+        显著性水平，取 `(0, 1)` 开区间。
 
     Returns
     -------
-    dict：`{"statistic", "pvalue", "df", "significant", "conclusion"}`。
+    dict
+        `{"statistic", "pvalue", "df", "significant", "conclusion"}`。
         `conclusion` 是一句能直接抄进论文的中文结论。
+
+    Raises
+    ------
+    TypeError
+        样本转不成数值数组。
+    ValueError
+        `alpha` 不在 `(0, 1)` 内；样本里没有数值列；样本量不足 2；
+        配对检验时两组长度不一致。
+
+    Notes
+    -----
+    传 `DataFrame` 时**所有数值列会被摊平成一个样本** —— 多列不同量纲时请先自己取列。
     """
-    # TODO(L1)
+    if not (0 < alpha < 1):
-    raise NotImplementedError
+        raise ValueError(f"显著性水平 alpha 必须在 (0, 1) 之间，你传入了 {alpha}")
+    def _clean_data(data: Any) -> np.ndarray:
+        arr, _ = as_array(data, numeric_only=True, ndim=1)
+        return arr[~np.isnan(arr)]
+
+    a_arr = _clean_data(a)
+
+    if len(a_arr) < 2:
+        raise ValueError("样本 a 的数据量少于 2 个，无法进行 t 检验")
+    if b is None:
+        res = stats.ttest_1samp(a_arr, popmean=value)
+        df = len(a_arr) - 1
+        test_name = f"单样本 t 检验 (检验均值是否等于 {value})"
+    else:
+        b_arr = _clean_data(b)
+        if paired:
+            if len(a_arr) != len(b_arr):
+                raise ValueError("配对 t 检验要求两组数据长度一致")
+            res = stats.ttest_rel(a_arr, b_arr)
+            df = len(a_arr) - 1
+            test_name = "配对样本 t 检验"
+        else:
+            res = stats.ttest_ind(a_arr, b_arr, equal_var=equal_var)
+            if equal_var:
+                df = len(a_arr) + len(b_arr) - 2
+                test_name = "独立双样本 t 检验 (假设方差齐性)"
+            else:
+                v1, v2 = np.var(a_arr, ddof=1), np.var(b_arr, ddof=1)
+                n1, n2 = len(a_arr), len(b_arr)
+                df = (v1/n1 + v2/n2)**2 / ((v1/n1)**2/(n1-1) + (v2/n2)**2/(n2-1))
+                test_name = "Welch's 独立双样本 t 检验"
+
+    statistic = _statistic(res)
+    pvalue = _pvalue(res)
+    significant = bool(pvalue < alpha)
+
+    if significant:
+        conclusion = f"在 {alpha} 显著性水平下，{test_name} 结果显著 (p={pvalue:.4f} < {alpha})，拒绝原假设，认为两组数据存在统计学上的显著差异。"
+    else:
+        conclusion = f"在 {alpha} 显著性水平下，{test_name} 结果不显著 (p={pvalue:.4f} >= {alpha})，不能拒绝原假设，认为两组数据没有统计学上的显著差异。"
+
+    # 6. 返回字典
+    return {
+        "statistic": statistic,
+        "pvalue": pvalue,
+        "df": float(df),
+        "significant": significant,
+        "conclusion": conclusion
+    }
 
 
 def anova(*groups: Any, alpha: float = 0.05) -> Any:

src/mcm_toolkit/viz/export.py

@@ -9,36 +9,132 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any
 
+import numpy as np
+from matplotlib.figure import Figure
+
 __all__ = ["save_figure", "save_table"]
 
+_ALLOWED_FORMATS = frozenset({"png", "pdf", "svg", "eps", "ps", "jpg", "jpeg", "tif", "tiff", "webp"})
+
+
+def _normalize_formats(formats: Any) -> tuple[str, ...]:
+    """校验并规范化输出格式；重复、空列表、单个字符串都在入口拦下。"""
+    if isinstance(formats, str):
+        raise TypeError("formats 必须是 tuple / list，不要传单个字符串（会把 'png' 拆成 p/n/g）")
+    if not isinstance(formats, (tuple, list)):
+        raise TypeError(f"formats 必须是 tuple / list，收到 {type(formats).__name__}")
+    if not formats:
+        raise ValueError("formats 不能为空")
+
+    normalized: list[str] = []
+    for fmt in formats:
+        if not isinstance(fmt, str):
+            raise TypeError(f"formats 里的每一项都必须是字符串，收到 {type(fmt).__name__}")
+        key = fmt.lower().lstrip(".")
+        if key not in _ALLOWED_FORMATS:
+            allowed = ", ".join(sorted(_ALLOWED_FORMATS))
+            raise ValueError(f"不支持的图片格式：{fmt!r}；可选：{allowed}")
+        if key in normalized:
+            raise ValueError(f"formats 里有重复的格式：{key!r}")
+        normalized.append(key)
+    return tuple(normalized)
+
 
 def save_figure(
     fig: Any,
     path: str | Path,
-    dpi: int = 300,
+    dpi: int | np.integer = 300,
-    formats: tuple[str, ...] = ("png", "pdf"),
+    formats: tuple[str, ...] | list[str] = ("png", "pdf"),
-    bbox_inches: str = "tight",
+    bbox_inches: str | None = "tight",
     transparent: bool = False,
 ) -> list[Path]:
     """保存图，默认同时出 PNG（预览用）和 PDF（LaTeX 插图用）。
 
     Parameters
     ----------
+    fig:
+        `matplotlib.figure.Figure`（`plt.subplots()` 的第一个返回值）。
+    path:
+        文件名**主干**。若带了 `png` / `pdf` 等图片后缀，会先去掉后缀，
+        再按 `formats` 逐个生成；父目录不存在时自动创建。
+    dpi:
+        输出分辨率，默认 300 —— 美赛送稿的 DPI 底线。
     formats:
-        美赛论文如果用 LaTeX 排版，**矢量图（PDF/EPS）比 PNG 清晰得多**，
+        要写的格式，tuple / list，大小写不敏感，顺序决定返回顺序。
-        所以默认两种都出。
+        支持 png / pdf / svg / eps / ps / jpg / jpeg / tif / tiff / webp。
+    bbox_inches:
+        传给 `Figure.savefig`；默认 `"tight"` 去掉多余白边，`None` 用 matplotlib 默认值。
+    transparent:
+        是否透明背景。正文用图一般保持 `False`，叠加图例或封面图可以用 `True`。
 
     Returns
     -------
-    实际写出的文件路径列表。
+    实际写出的文件路径列表，顺序与 `formats` 一致。
+
+    Raises
+    ------
+    TypeError
+        `fig` 不是 `Figure`；`formats` 不是 tuple / list、含非字符串项；
+        `dpi` / `transparent` / `bbox_inches` 类型不对。
+    ValueError
+        `formats` 为空、含不支持的格式或重复格式；`dpi <= 0`；
+        `path` 为空或是一个目录。
 
     Notes
     -----
+    所有校验都在建目录、写文件**之前**完成，传错格式不会留下空目录。
     建议配合项目的 figure 目录约定：`figures/fig{序号}_{短名}.pdf`，
     图号与正文引用一一对应，最后核对时不容易错位。
+
+    Examples
+    --------
+    >>> fig, ax = plt.subplots()             # doctest: +SKIP
+    >>> paths = save_figure(fig, "figures/fig1")
+    >>> [p.suffix for p in paths]
+    ['.png', '.pdf']
     """
-    # TODO(L0)
+    if not isinstance(fig, Figure):
-    raise NotImplementedError
+        raise TypeError(f"fig 必须是 matplotlib 的 Figure，收到 {type(fig).__name__}")
+
+    if isinstance(dpi, bool) or not isinstance(dpi, (int, np.integer)):
+        raise TypeError(f"dpi 必须是正整数，收到 {type(dpi).__name__}")
+    if dpi <= 0:
+        raise ValueError(f"dpi 必须大于 0，收到 {dpi}")
+
+    if not isinstance(transparent, bool):
+        raise TypeError(f"transparent 必须是 bool，收到 {type(transparent).__name__}")
+
+    if bbox_inches is not None:
+        if not isinstance(bbox_inches, str):
+            raise TypeError(f"bbox_inches 必须是字符串或 None，收到 {type(bbox_inches).__name__}")
+        if not bbox_inches.strip():
+            raise ValueError("bbox_inches 不能是空字符串")
+
+    if not isinstance(path, (str, Path)):
+        raise TypeError(f"path 必须是 str 或 Path，收到 {type(path).__name__}")
+    base = Path(path)
+    if not base.name:
+        raise ValueError(f"path 不能为空：{path!r}")
+    if base.is_dir():
+        raise ValueError(f"path 是一个目录，请给文件名主干：{base}")
+    if base.suffix and base.suffix.lower().lstrip(".") in _ALLOWED_FORMATS:
+        base = base.with_suffix("")
+
+    normalized = _normalize_formats(formats)
+    base.parent.mkdir(parents=True, exist_ok=True)
+
+    written: list[Path] = []
+    for fmt in normalized:
+        target = base.with_suffix(f".{fmt}")
+        fig.savefig(
+            target,
+            dpi=int(dpi),
+            bbox_inches=bbox_inches,
+            transparent=transparent,
+            format=fmt,
+        )
+        written.append(target)
+    return written
 
 
 def save_table(

tests/test_core.py

@@ -1,11 +1,12 @@
 """core 包测试。
 
-TODO(L0)：TestValidate 实现后去掉 skip 标记（Result 与 Random 已完成）。
+TODO(L0)：TestValidate 的 check_* 实现后去掉 skip 标记（Result / Random / as_array 已完成）。
 """
 
 from __future__ import annotations
 
 import numpy as np
+import pandas as pd
 import pytest
 
 
@@ -96,6 +97,83 @@ class TestValidate:
             check_square_matrix([[1, 2, 3], [4, 5, 6]])
 
 
+class TestAsArray:
+    """`as_array` 是所有收数值函数的统一入口：白名单 + 转 ndarray + 报告原类型。"""
+
+    def test_reports_kind_for_every_supported_container(self):
+        from mcm_toolkit.core import as_array
+
+        df = pd.DataFrame({"a": [1.0, 2.0], "city": ["X", "Y"]})
+        series = pd.Series([1.0, 2.0], index=["u", "v"], name="s")
+
+        assert as_array(df)[1] == "frame"
+        assert as_array(series)[1] == "series"
+        for raw in (np.array([1.0, 2.0]), [1.0, 2.0], (1.0, 2.0)):
+            assert as_array(raw)[1] == "array"
+
+    def test_frame_keeps_only_numeric_columns_by_default(self):
+        # numeric_only 默认 True：一列数值都没有就报 ValueError（与 describe / zscore 同口径）
+        from mcm_toolkit.core import as_array
+
+        df = pd.DataFrame({"a": [1.0, 2.0], "b": [3.0, 4.0], "city": ["X", "Y"]})
+        arr, kind = as_array(df)
+
+        assert arr.shape == (2, 2) and kind == "frame"
+        assert list(df.select_dtypes(include=[np.number]).columns) == ["a", "b"]
+
+        with pytest.raises(ValueError, match="数值"):
+            as_array(pd.DataFrame({"city": ["X", "Y"]}))
+
+    def test_frame_with_text_and_numeric_only_false_raises(self):
+        # 元素级函数（normalize / standardize / log_transform）走 numeric_only=False，
+        # 因为跳过列会让返回的表少列、与输入对不上；转不动就该报错，不能静默丢列。
+        from mcm_toolkit.core import as_array
+
+        df = pd.DataFrame({"a": [1.0, 2.0], "city": ["X", "Y"]})
+        with pytest.raises(TypeError, match="转不成"):
+            as_array(df, numeric_only=False)
+
+    def test_default_never_flattens(self):
+        # 摊平曾是 t_test(DataFrame) 静默混合多列的根源，必须是显式行为
+        from mcm_toolkit.core import as_array
+
+        df = pd.DataFrame({"a": [1.0, 2.0, 3.0], "b": [4.0, 5.0, 6.0]})
+        assert as_array(df)[0].shape == (3, 2)
+        assert as_array(df, ndim=1)[0].shape == (6,)
+        assert as_array(pd.Series([1.0, 2.0, 3.0]), ndim=1)[0].shape == (3,)
+
+    def test_ndim_2_checks_instead_of_reshaping(self):
+        # 一维数据是"1 个样本"还是"1 个特征"没有唯一答案，不能替调用方猜
+        from mcm_toolkit.core import as_array
+
+        assert as_array([[1.0, 2.0]], ndim=2)[0].shape == (1, 2)
+        with pytest.raises(ValueError, match="二维"):
+            as_array([1.0, 2.0], ndim=2)
+        with pytest.raises(ValueError, match="ndim"):
+            as_array([1.0, 2.0], ndim=3)
+
+    def test_rejects_types_outside_the_whitelist(self):
+        from mcm_toolkit.core import as_array
+
+        # str 也是可迭代对象：不显式挡住，"abc" 会被当成三个字符算下去
+        for bad in ("abc", {1, 2}, {"a": 1}, None, object()):
+            with pytest.raises(TypeError):
+                as_array(bad)
+
+    def test_keeps_missing_values(self):
+        # 删缺失是各函数的**语义**（corr 成对删、t_test 配对要成对删），不能在这里做
+        from mcm_toolkit.core import as_array
+
+        arr = as_array([1.0, np.nan, 3.0])[0]
+        assert arr.shape == (3,) and np.isnan(arr[1])
+
+    def test_dtype_none_keeps_original_dtype(self):
+        from mcm_toolkit.core import as_array
+
+        assert as_array([1, 2, 3], dtype=None)[0].dtype.kind == "i"
+        assert as_array([1, 2, 3])[0].dtype.kind == "f"
+
+
 def test_result_repr_is_readable():
     from mcm_toolkit.core import Result
 

tests/test_data.py

@@ -47,9 +47,11 @@ def test_load_table_maps_na_like_tokens_to_nan(tmp_path):
     p = tmp_path / "na.csv"
     p.write_text("a,b,c\n1,NA,\n2,-,#N/A\n", encoding="utf-8")
     df = load_table(p)
-    assert df["b"].isna().all()
+    # 外面套 bool()：df["b"] 的类型是 Series | DataFrame，直接当条件用 pyright 会报
-    assert df["c"].isna().all()
+    # "条件操作数无效"；套上 bool() 既满足类型检查，又能在它真返回 Series 时当场炸掉。
-    assert df["a"].notna().all()
+    assert bool(df["b"].isna().all())
+    assert bool(df["c"].isna().all())
+    assert bool(df["a"].notna().all())
 
 
 def test_load_table_respects_explicit_encoding(tmp_path):
@@ -102,24 +104,189 @@ def test_save_table_rejects_non_dataframe(tmp_path):
     from mcm_toolkit.data import save_table
 
     with pytest.raises(TypeError):
-        save_table([1, 2, 3], tmp_path / "bad.csv")
+        save_table([1, 2, 3], tmp_path / "bad.csv")  # type: ignore[arg-type]  # 就是要传错
 
 
-# ------------------------------------------------- 以下为未实现算法（L0/L1 待写）
+def test_save_table_validates_before_touching_disk(tmp_path):
+    """校验必须早于副作用：参数不合法时，一个目录、一个文件都不能留下。"""
+    from mcm_toolkit.data import save_table
+
+    with pytest.raises(ValueError, match=r"\.txt"):
+        save_table(pd.DataFrame({"a": [1]}), tmp_path / "d1" / "x.txt")
+    with pytest.raises(TypeError):
+        save_table([1, 2, 3], tmp_path / "d2" / "x.csv")  # type: ignore[arg-type]  # 就是要传错
+
+    assert sorted(p.name for p in tmp_path.iterdir()) == []
+
+
+# --------------------------------------------------------------- data: clean
+
+
+def test_clean_missing_default_drops_any_missing():
+    """不传 threshold 时是"只要有缺失就删"。"""
+    from mcm_toolkit.data import clean_missing
+
+    df = pd.DataFrame({"a": [1.0, np.nan, 3.0], "b": [1.0, 2.0, np.nan]})
+    out = clean_missing(df)
+    assert len(out) == 1
+    assert list(out.columns) == ["a", "b"]
+
+
+def test_clean_missing_threshold_keeps_rows_within_limit():
+    """四行三列、阈值 0.5：缺 2/3 的两行要删，剩 2 行。
+
+    3 列时 min_non_na 必须是 ceil(3*0.5)=2；写成 int() 截断就会漏删。
+    """
+    from mcm_toolkit.data import clean_missing
+
+    df = pd.DataFrame(
+        {
+            "a": [1.0, np.nan, np.nan, 4.0],
+            "b": [1.0, np.nan, np.nan, 4.0],
+            "c": [1.0, 2.0, np.nan, 4.0],
+        }
+    )
+    out = clean_missing(df, axis=0, threshold=0.5)
+    assert len(out) == 2
+    assert out["a"].tolist() == [1.0, 4.0]
+
+
+def test_clean_missing_axis1_drops_empty_column():
+    """axis=1 按列删：整列全空（缺失率 1.0 > 0.5）要掉。"""
+    from mcm_toolkit.data import clean_missing
+
+    df = pd.DataFrame({"x": [1.0, 2.0, 3.0], "y": [np.nan, np.nan, np.nan]})
+    assert list(clean_missing(df, axis=1, threshold=0.5).columns) == ["x"]
+
+
+def test_clean_missing_rejects_bad_axis():
+    from mcm_toolkit.data import clean_missing
+
+    with pytest.raises(ValueError, match="axis"):
+        clean_missing(pd.DataFrame({"a": [1.0]}), axis=2)
+
+
+def test_clean_missing_rejects_non_dataframe():
+    from mcm_toolkit.data import clean_missing
+
+    with pytest.raises(TypeError):
+        clean_missing([[1.0, 2.0]])
+
+
+def test_impute_missing_mean_and_ffill():
+    from mcm_toolkit.data import impute_missing
+
+    df = pd.DataFrame({"a": [1.0, np.nan, 3.0]})
+    assert impute_missing(df, method="mean")["a"].tolist() == [1.0, 2.0, 3.0]
+    assert impute_missing(df, method="ffill")["a"].tolist() == [1.0, 1.0, 3.0]
+
+
+def test_impute_missing_mode_survives_all_nan_column():
+    """整列全 NaN 时 mode() 给不出众数：不能崩，也不能硬填一个值进去。"""
+    from mcm_toolkit.data import impute_missing
+
+    df = pd.DataFrame({"a": [np.nan, np.nan], "b": [1.0, np.nan]})
+    out = impute_missing(df, method="mode")
+    assert bool(out["a"].isna().all())
+    assert out["b"].tolist() == [1.0, 1.0]
+
+
+def test_impute_missing_rejects_unknown_method():
+    from mcm_toolkit.data import impute_missing
+
+    with pytest.raises(ValueError, match="bogus"):
+        impute_missing(pd.DataFrame({"a": [1.0]}), method="bogus")
+
+
+def test_impute_missing_rejects_non_dataframe():
+    from mcm_toolkit.data import impute_missing
+
+    with pytest.raises(TypeError):
+        impute_missing([[1.0, 2.0]])
+
+
+def test_winsorize_clips_series_to_quantiles():
+    from mcm_toolkit.data import winsorize
+
+    s = pd.Series([1.0, 2.0, 3.0, 4.0, 1000.0])
+    out = winsorize(s, lower=0.1, upper=0.9)
+    assert float(out.iloc[0]) == pytest.approx(1.4)
+    assert float(out.iloc[-1]) == pytest.approx(601.6)
+    assert float(out.max()) < 1000.0
+
+
+def test_winsorize_rejects_bad_quantile_order():
+    from mcm_toolkit.data import winsorize
+
+    with pytest.raises(ValueError, match="lower"):
+        winsorize(pd.Series([1.0, 2.0]), lower=0.9, upper=0.1)
+
+
+def test_winsorize_rejects_non_frame_with_typeerror():
+    """§4.7：类型不对必须抛 TypeError，不能抛 ValueError。"""
+    from mcm_toolkit.data import winsorize
+
+    with pytest.raises(TypeError):
+        winsorize([1.0, 2.0, 3.0])
+
+
+def test_detect_outliers_rejects_unknown_method():
+    """方法名校验在取默认取值之前，所以这条现在就是绿的。"""
+    from mcm_toolkit.data import detect_outliers
+
+    with pytest.raises(ValueError, match="bogus"):
+        detect_outliers([1.0, 2.0], method="bogus")  # type: ignore[arg-type]
+
+
+def test_detect_outliers_rejects_bad_type():
+    """§4.7：类型不对必须抛 TypeError，不能让它一路飘进 pandas 里去。"""
+    from mcm_toolkit.data import detect_outliers
+
+    for bad in (42, 3.14, "123", None, {"a": [1, 2]}):
+        with pytest.raises(TypeError):
+            detect_outliers(bad)
+
+
+def test_detect_outliers_survives_degenerate_columns():
+    """全 NaN 列与单元素列都不能抛异常，判定一律为 False。"""
+    from mcm_toolkit.data import detect_outliers
+
+    df = pd.DataFrame({"all_nan": [np.nan, np.nan, np.nan], "one": [1.0, 2.0, 3.0]})
+    assert not bool(np.asarray(detect_outliers(df)).any())
+    assert not bool(np.asarray(detect_outliers([5.0])).any())
+    assert not bool(np.asarray(detect_outliers([5.0], method="zscore")).any())
+
+
+def test_detect_outliers_accepts_tuple_as_1d():
+    """元组按一维数组型处理，返回值与传 list 一致。"""
+    from mcm_toolkit.data import detect_outliers
+
+    mask = np.asarray(detect_outliers((1.0, 2.0, 3.0, 4.0, 1000.0)))
+    assert mask.shape == (5,)
+    assert mask.dtype == bool
+    assert bool(mask[-1])
+
+
+# ------------------------ 曾经 xfail 的契约，现已全部实现（留作回归）
+#
+# 这些用例写的是**文档里已经承诺的行为**。实现没跟上时用 xfail，让它们照样出现在
+# 报告里（显示成 x）；修好之后会自动变成 XPASS —— 看到 XPASS 就把 mark 摘掉。
+#
+# 已摘掉：threshold 范围校验、IQR 的 UnboundLocalError、(n,1) 形状、zscore 默认阈值、
+# winsorize 的文本列、detect_outliers 的文本列、impute_missing 的 mode 就地修改。
+# **当前 0 条 xfail** —— 以后新增契约照旧：先写测试 + xfail，实现跟上就摘 mark。
 
 
-@pytest.mark.skip(reason=_NOT_IMPLEMENTED)
 def test_detect_outliers_finds_planted_points():
     """人工埋 3 个离群点，IQR 法应正好命中 3 个。"""
     from mcm_toolkit.data import detect_outliers
 
     x = np.concatenate([np.arange(100.0), [1e6, -1e6, 1e7]])
     mask = np.asarray(detect_outliers(x, method="iqr"))
-    assert mask.sum() == 3
+    assert int(mask.sum()) == 3
-    assert mask[-3:].all()
+    assert bool(mask[-3:].all())
 
 
-@pytest.mark.skip(reason=_NOT_IMPLEMENTED)
 def test_detect_outliers_returns_mask_not_filtered_data():
     """约定：只标不删——返回与原数据同形的布尔掩码。"""
     from mcm_toolkit.data import detect_outliers
@@ -130,8 +297,68 @@ def test_detect_outliers_returns_mask_not_filtered_data():
     assert mask.dtype == bool
 
 
-@pytest.mark.skip(reason=_NOT_IMPLEMENTED)
+def test_detect_outliers_zscore_flags_planted_point():
+    from mcm_toolkit.data import detect_outliers
+
+    x = np.concatenate([np.zeros(99), [1e6]])
+    mask = np.asarray(detect_outliers(x, method="zscore"))
+    assert int(mask.sum()) == 1
+    assert bool(mask[-1].all())
+
+
+def test_detect_outliers_survives_text_columns():
+    """赛题表几乎都带文本列：分位数只在数值列上算，文本列恒 False。"""
+    from mcm_toolkit.data import detect_outliers
+
+    df = pd.DataFrame({"city": ["a", "b", "c", "d"], "v": [1.0, 2.0, 3.0, 1000.0]})
+    mask = detect_outliers(df)
+    assert int(np.asarray(mask).sum()) == 1
+    assert not bool(np.asarray(mask["city"]).any())
+    assert bool(np.asarray(mask["v"]).any())
+
+
+def test_detect_outliers_all_text_frame_returns_all_false():
+    """整表没有数值列时不报错，返回全 False 掩码（语义：这一列没有离群点）。"""
+    from mcm_toolkit.data import detect_outliers
+
+    df = pd.DataFrame({"a": ["x", "y"], "b": ["z", "w"]})
+    mask = detect_outliers(df)
+    assert mask.shape == df.shape
+    assert not bool(np.asarray(mask).any())
+
+
+def test_winsorize_survives_text_columns():
+    """文本列必须原样留着：分位数只在数值列上算。"""
+    from mcm_toolkit.data import winsorize
+
+    df = pd.DataFrame({"city": ["a", "b", "c", "d"], "v": [1.0, 2.0, 3.0, 1000.0]})
+    out = winsorize(df)
+    assert out["city"].tolist() == ["a", "b", "c", "d"]
+    assert float(out["v"].iloc[-1]) < 1000.0
+
+
+def test_clean_missing_rejects_out_of_range_threshold():
+    from mcm_toolkit.data import clean_missing
+
+    with pytest.raises(ValueError, match="threshold"):
+        clean_missing(pd.DataFrame({"a": [1.0, np.nan]}), threshold=1.5)
+
+
+def test_impute_missing_mode_does_not_mutate_input():
+    """mode 分支也必须返回新表：不能顺手把调用方的表改了。"""
+    from mcm_toolkit.data import impute_missing
+
+    df = pd.DataFrame({"a": [1.0, np.nan, 1.0]})
+    out = impute_missing(df, method="mode")
+    assert out["a"].tolist() == [1.0, 1.0, 1.0]
+    assert bool(df["a"].isna().any())
+
+
+# ------------------------------------------------------ data: transform
+
+
 def test_normalize_minmax_range(rng):
+    """minmax 是**按列**压到 [0, 1]，不是整表压一次。"""
     from mcm_toolkit.data import normalize
 
     x = rng.normal(size=(50, 3))
@@ -140,7 +367,54 @@ def test_normalize_minmax_range(rng):
     assert np.allclose(out.max(axis=0), 1.0)
 
 
-@pytest.mark.skip(reason=_NOT_IMPLEMENTED)
+def test_normalize_minmax_doctest_values():
+    """docstring 里那个 Examples 就是规格，不能只有形似。"""
+    from mcm_toolkit.data import normalize
+
+    assert normalize([1, 2, 3]).tolist() == [0.0, 0.5, 1.0]
+
+
+def test_normalize_respects_feature_range():
+    from mcm_toolkit.data import normalize
+
+    out = np.asarray(normalize([1.0, 2.0, 3.0], feature_range=(-1.0, 1.0)))
+    assert np.allclose(out, [-1.0, 0.0, 1.0])
+
+
+def test_normalize_constant_column_stays_finite():
+    """常量列 max == min，不能出 nan / inf；固定压到 feature_range 的下界。"""
+    from mcm_toolkit.data import normalize
+
+    out = np.asarray(normalize([[2.0, 1.0], [2.0, 3.0], [2.0, 5.0]]))
+    assert np.allclose(out[:, 0], 0.0)
+    assert bool(np.isfinite(out).all())
+
+
+def test_normalize_vector_method_gives_unit_columns():
+    from mcm_toolkit.data import normalize
+
+    out = np.asarray(normalize([[3.0, 0.0], [4.0, 0.0]], method="vector"))
+    assert np.allclose(np.linalg.norm(out, axis=0), [1.0, 0.0])
+
+
+def test_normalize_max_method_scales_by_column_max():
+    from mcm_toolkit.data import normalize
+
+    out = np.asarray(normalize([[1.0, 10.0], [2.0, 20.0]], method="max"))
+    assert np.allclose(out, [[0.5, 0.5], [1.0, 1.0]])
+
+
+def test_normalize_rejects_bad_method_and_feature_range():
+    from mcm_toolkit.data import normalize
+
+    with pytest.raises(ValueError, match="bogus"):
+        normalize([1.0, 2.0], method="bogus")
+    with pytest.raises(ValueError, match="feature_range"):
+        normalize([1.0, 2.0], feature_range=(1.0, 0.0))
+    with pytest.raises(TypeError, match="feature_range"):
+        normalize([1.0, 2.0], feature_range=(0.0, 1.0, 2.0))  # type: ignore[arg-type]
+
+
 def test_standardize_has_zero_mean_unit_std(rng):
     from mcm_toolkit.data import standardize
 
@@ -150,6 +424,106 @@ def test_standardize_has_zero_mean_unit_std(rng):
     assert abs(out.std() - 1.0) < 1e-9
 
 
+def test_standardize_is_per_column(rng):
+    """按列标准化：每列各自均值 0、标准差 1。"""
+    from mcm_toolkit.data import standardize
+
+    x = rng.normal(size=(200, 3)) * [1.0, 10.0, 100.0] + [0.0, 50.0, -3.0]
+    out = np.asarray(standardize(x))
+    assert np.allclose(out.mean(axis=0), 0.0, atol=1e-12)
+    assert np.allclose(out.std(axis=0), 1.0, atol=1e-12)
+
+
+def test_standardize_honours_ddof():
+    """ddof 要真的传下去：ddof=0 才得到单位方差；ddof=1 时结果的 std = sqrt((n-1)/n)。
+
+    除以更大的样本标准差，结果自然更小 —— 所以 ddof=1 时 out.std() **小于** 1。
+    """
+    from mcm_toolkit.data import standardize
+
+    x = np.array([1.0, 2.0, 3.0, 4.0])
+    assert np.allclose(standardize(x, ddof=0).std(), 1.0)
+    assert np.allclose(standardize(x, ddof=1).std(), np.sqrt(3.0 / 4.0))
+
+
+def test_standardize_constant_column_stays_finite():
+    from mcm_toolkit.data import standardize
+
+    out = np.asarray(standardize([[2.0, 1.0], [2.0, 3.0]]))
+    assert np.allclose(out[:, 0], 0.0)
+    assert bool(np.isfinite(out).all())
+
+
+def test_standardize_rejects_bad_type():
+    from mcm_toolkit.data import standardize
+
+    with pytest.raises(TypeError):
+        standardize("abc")
+
+
+def test_log_transform_shifts_to_keep_domain():
+    """含 0 或负值时自动取 offset = 1 - min(x)，保证 log 的定义域。"""
+    from mcm_toolkit.data import log_transform
+
+    x = np.array([-5.0, 0.0, 5.0])
+    out = np.asarray(log_transform(x))
+    assert bool(np.isfinite(out).all())
+    assert np.allclose(out, np.log(x + 6.0))
+
+
+def test_log_transform_positive_data_needs_no_offset():
+    from mcm_toolkit.data import log_transform
+
+    assert np.allclose(log_transform([1.0, np.e]), [0.0, 1.0])
+
+
+def test_log_transform_rejects_bad_type():
+    from mcm_toolkit.data import log_transform
+
+    with pytest.raises(TypeError):
+        log_transform("abc")
+
+
+def test_one_hot_encode_auto_detects_text_columns_quietly():
+    """pandas 3 起字符串列的 dtype 是 'str'：要能选中，且不能走已弃用的 select_dtypes 路径。"""
+    import warnings
+
+    from mcm_toolkit.data import one_hot_encode
+
+    df = pd.DataFrame({"city": ["A", "B", "C"], "v": [1.0, 2.0, 3.0]})
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        out = one_hot_encode(df)
+
+    messages = [str(w.message) for w in caught]
+    assert not messages, f"自动识别不该产生任何告警，实际：{messages}"
+    assert "city_A" in out.columns
+    assert "v" in out.columns
+
+
+def test_one_hot_encode_explicit_columns_and_drop_first():
+    from mcm_toolkit.data import one_hot_encode
+
+    df = pd.DataFrame({"city": ["A", "B", "C"], "v": [1.0, 2.0, 3.0]})
+    out = one_hot_encode(df, columns=["city"], drop_first=True)
+    assert "city_A" not in out.columns
+    assert "city_B" in out.columns
+    assert "city_C" in out.columns
+
+
+def test_one_hot_encode_rejects_missing_column_and_non_frame():
+    from mcm_toolkit.data import one_hot_encode
+
+    df = pd.DataFrame({"city": ["A"], "v": [1.0]})
+    with pytest.raises(ValueError, match="nope"):
+        one_hot_encode(df, columns=["nope"])
+    with pytest.raises(TypeError):
+        one_hot_encode([1, 2, 3])
+
+
+# ------------------------------------------------- 以下为未实现算法（L0/L1 待写）
+
+
 @pytest.mark.skip(reason=_NOT_IMPLEMENTED)
 def test_train_test_split_sizes_and_no_overlap(rng):
     from mcm_toolkit.data import train_test_split

tests/test_models.py

@@ -3,11 +3,13 @@
 from __future__ import annotations
 
 import numpy as np
+import pandas as pd
 import pytest
 
-pytestmark = pytest.mark.skip(reason="未实现：见 docs/03-roadmap.md L1")
+_NOT_IMPLEMENTED = "未实现：见 docs/03-roadmap.md L1"
 
 
+@pytest.mark.skip(reason=_NOT_IMPLEMENTED)
 def test_fit_linear_recovers_known_coefficients(linear_data):
     """真值 y = 2x + 1，拟合系数应在 1% 内。"""
     from mcm_toolkit.models import fit_linear
@@ -18,6 +20,7 @@ def test_fit_linear_recovers_known_coefficients(linear_data):
     assert np.isclose(r.params["intercept"], 1.0, atol=0.05)
 
 
+@pytest.mark.skip(reason=_NOT_IMPLEMENTED)
 def test_fit_polynomial_matches_numpy(linear_data):
     from mcm_toolkit.models import fit_polynomial
 
@@ -43,16 +46,302 @@ def test_r2_is_one_for_perfect_fit():
     assert np.isclose(r2_score(y, y), 1.0)
 
 
+class _MeanModel:
+    """最笨的模型：永远预测训练集的均值（`compare_models` 的对照组）。"""
+
+    def fit(self, X, y):
+        self.mu_ = float(np.mean(y))
+        return self
+
+    def predict(self, X):
+        return np.full(X.shape[0], self.mu_)
+
+
+class _LinearModel:
+    """一列特征的普通最小二乘（`compare_models` 的"好模型"）。"""
+
+    def fit(self, X, y):
+        self.coef_ = np.polyfit(X[:, 0], y, 1)
+        return self
+
+    def predict(self, X):
+        return np.polyval(self.coef_, X[:, 0])
+
+
 def test_compare_models_returns_table_sorted_by_first_metric(linear_data):
-    from mcm_toolkit.models import compare_models, fit_linear, fit_polynomial
+    from mcm_toolkit.models import compare_models
+
+    x, y = linear_data
+    tbl = compare_models(
+        {"mean": _MeanModel(), "linear": _LinearModel()}, x.reshape(-1, 1), y, cv=0
+    )
+
+    assert list(tbl.columns) == ["rmse", "mae", "r2"]
+    assert list(tbl.index) == ["linear", "mean"]  # 首列 rmse 升序 → 好的模型在前
+    assert tbl.loc["linear", "rmse"] < tbl.loc["mean", "rmse"]
+
+
+def test_metrics_reject_mismatched_shapes():
+    from mcm_toolkit.models import rmse
+
+    with pytest.raises(ValueError, match="形状必须一致"):
+        rmse([1.0, 2.0], [1.0, 2.0, 3.0])
+
+
+def test_metrics_reject_empty_input():
+    from mcm_toolkit.models import rmse
+
+    with pytest.raises(ValueError, match="不能为空"):
+        rmse(np.array([]), np.array([]))
+
+
+def test_metrics_reject_nan_instead_of_dropping_it():
+    """含 NaN 一律报错，**绝不静默删点**：删了样本量就变了，指标不可比。"""
+    from mcm_toolkit.models import rmse
+
+    with pytest.raises(ValueError, match="NaN"):
+        rmse([1.0, np.nan, 3.0], [1.0, 2.0, 3.0])
+    with pytest.raises(ValueError, match="NaN"):
+        rmse([1.0, 2.0, 3.0], [1.0, np.nan, 3.0])
+
+
+def test_metrics_reject_non_whitelisted_type():
+    """`str` 也是可迭代对象，必须被入口白名单挡住，不能被当成三个字符算下去。"""
+    from mcm_toolkit.models import rmse
+
+    with pytest.raises(TypeError):
+        rmse("abc", "abc")  # type: ignore[arg-type]
+
+
+@pytest.mark.parametrize("name", ["rmse", "mae", "mape", "smape", "r2_score"])
+def test_metrics_agree_across_input_types(name):
+    """`DataFrame` / `Series` / `ndarray` / `list` 四种入参必须给出同一个数。"""
+    import mcm_toolkit.models as models
+
+    yt = [1.0, 2.0, 3.0, 4.0]
+    yp = [1.1, 1.9, 3.2, 3.8]
+    fn = getattr(models, name)
+    base = fn(yt, yp)
+
+    assert np.isclose(fn(np.array(yt), np.array(yp)), base)
+    assert np.isclose(fn(pd.Series(yt), pd.Series(yp)), base)
+    assert np.isclose(fn(pd.DataFrame({"y": yt}), pd.DataFrame({"y": yp})), base)
+
+
+def test_mape_rejects_non_positive_y_true():
+    """`y_true` 非正时 MAPE 无定义 —— 拦住并点名改用 smape，而不是返回负数或 inf。"""
+    from mcm_toolkit.models import mape
+
+    with pytest.raises(ValueError, match="非正数"):
+        mape([0.0, 2.0], [1.0, 2.0])
+    with pytest.raises(ValueError, match="非正数"):
+        mape([-1.0, 2.0], [1.0, 2.0])
+
+
+def test_metrics_reject_infinite_input():
+    """`Inf` 与 `NaN` 一样直接拦：算出来是 `inf` 的指标没有任何意义。"""
+    from mcm_toolkit.models import rmse
+
+    with pytest.raises(ValueError, match="Inf"):
+        rmse([1.0, np.inf], [1.0, 2.0])
+    with pytest.raises(ValueError, match="Inf"):
+        rmse([1.0, 2.0], [1.0, -np.inf])
+
+
+def test_metrics_require_at_least_two_samples():
+    """1 个点的误差指标没有统计意义；标量也会被这条拦住（不是被当成 1 个样本）。"""
+    from mcm_toolkit.models import rmse
+
+    with pytest.raises(ValueError, match="至少需要包含 2 个样本"):
+        rmse([1.0], [1.0])
+    with pytest.raises(ValueError, match="至少需要包含 2 个样本"):
+        rmse(1.0, 1.0)
+
+
+def test_smape_is_silent_when_denominator_is_zero():
+    """分子分母同时为 0 的点记 0，且**不能漏出 RuntimeWarning**。
+
+    本仓库 `pyproject.toml` 里开了 `filterwarnings = ["error::RuntimeWarning"]`，
+    所以这条测试同时守着"零除"这个坑：`np.where` 的两条分支都会被求值，
+    直接写除式就会把告警漏出来，测试会红。
+    """
+    from mcm_toolkit.models import smape
+
+    assert smape([0.0, 0.0], [0.0, 0.0]) == 0.0
+    assert smape([0.0, 2.0], [0.0, 2.0]) == 0.0
+    assert np.isclose(smape([1.0, 1.0], [0.0, 1.0]), 1.0)
+
+
+def test_adjusted_r2_rejects_invalid_n_features():
+    from mcm_toolkit.models import adjusted_r2
+
+    yt = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
+    yp = np.array([1.5, 2.5, 2.5, 4.5, 5.5])
+
+    for bad in (True, 1.0, np.float64(1.0)):
+        with pytest.raises(TypeError):
+            adjusted_r2(yt, yp, bad)  # type: ignore[arg-type]
+    with pytest.raises(ValueError, match="正整数"):
+        adjusted_r2(yt, yp, 0)
+    with pytest.raises(ValueError, match="样本量太小"):
+        adjusted_r2(yt, yp, 4)  # n = 5，分母 n - k - 1 = 0
+
+
+def test_adjusted_r2_accepts_numpy_integer():
+    from mcm_toolkit.models import adjusted_r2
+
+    yt = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
+    yp = np.array([1.5, 2.5, 2.5, 4.5, 5.5])
+
+    assert adjusted_r2(yt, yp, np.int64(1)) == adjusted_r2(yt, yp, 1)
+
+
+def test_adjusted_r2_penalises_extra_features():
+    """同一份数据、同一个 R²，自变量越多，调整 R² 越小（没用的变量只吃惩罚）。"""
+    from mcm_toolkit.models import adjusted_r2
+
+    yt = np.array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0])
+    yp = np.array([1.2, 2.1, 3.3, 3.8, 5.1, 6.2])
+
+    assert adjusted_r2(yt, yp, 3) < adjusted_r2(yt, yp, 2) < adjusted_r2(yt, yp, 1)
+
+
+def test_r2_matches_analytic_formula():
+    """`R² = 1 - SS_res / SS_tot`，且 `SS_tot` 的基准必须是 **y_true 的均值**。
+
+    这里刻意用**非完美拟合**的数据：完美拟合（R² = 1）和常量 y（R² = 0）都能把
+    "基准量抄错对象"这类 bug 掩盖掉（个人易错点 31）。
+    """
+    from mcm_toolkit.models import r2_score
+
+    yt = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
+    yp = np.array([1.5, 2.5, 2.5, 4.5, 5.5])
+    ss_res = np.sum((yt - yp) ** 2)
+    ss_tot = np.sum((yt - np.mean(yt)) ** 2)
+
+    assert np.isclose(r2_score(yt, yp), 1 - ss_res / ss_tot)
+    assert np.isclose(r2_score(yt, yp), 0.875)
+
+
+def test_r2_matches_sklearn():
+    """拿成熟库当**独立的参照物**：自实现指标最容易"自己算自己"。"""
+    sk = pytest.importorskip("sklearn.metrics")
+
+    from mcm_toolkit.models import r2_score
+
+    rng = np.random.default_rng(0)
+    yt = rng.normal(size=50)
+    yp = yt + rng.normal(scale=0.5, size=50)
+
+    assert np.isclose(r2_score(yt, yp), sk.r2_score(yt, yp))
+
+
+def test_r2_is_negative_when_worse_than_predicting_the_mean():
+    from mcm_toolkit.models import r2_score
+
+    assert np.isclose(r2_score([1.0, 2.0, 3.0], [3.0, 2.0, 1.0]), -3.0)
+
+
+def test_adjusted_r2_matches_analytic_formula():
+    from mcm_toolkit.models import adjusted_r2, r2_score
+
+    yt = np.array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0])
+    yp = np.array([1.2, 2.1, 3.3, 3.8, 5.1, 6.2])
+    n, k = len(yt), 2
+    r2 = r2_score(yt, yp)
+
+    assert np.isclose(adjusted_r2(yt, yp, k), 1 - (1 - r2) * (n - 1) / (n - k - 1))
+
+
+def test_compare_models_treats_r2_names_as_aliases(linear_data):
+    """`"r2"` 与 `"r2_score"` 是同一个指标的别名：传哪个、列名就叫哪个，数值相同。"""
+    from mcm_toolkit.models import compare_models
 
     x, y = linear_data
     X = x.reshape(-1, 1)
+    short = compare_models({"m": _LinearModel()}, X, y, metrics=("rmse", "r2"), cv=0)
+    full = compare_models({"m": _LinearModel()}, X, y, metrics=("rmse", "r2_score"), cv=0)
+
+    assert list(short.columns) == ["rmse", "r2"]
+    assert list(full.columns) == ["rmse", "r2_score"]
+    assert np.isclose(short.loc["m", "r2"], full.loc["m", "r2_score"])
+
+
+def test_compare_models_sorts_descending_when_first_metric_is_r2(linear_data):
+    """误差类是**越小越好**、R² 是**越大越好**，排序方向必须跟着首列指标走。"""
+    from mcm_toolkit.models import compare_models
+
+    x, y = linear_data
     tbl = compare_models(
-        {"linear": fit_linear(X, y), "poly2": fit_polynomial(X, y, degree=2)},
+        {"mean": _MeanModel(), "linear": _LinearModel()},
-        X,
+        x.reshape(-1, 1),
         y,
+        metrics=("r2",),
         cv=0,
     )
-    assert set(tbl.index) >= {"linear", "poly2"}
+
-    assert "rmse" in tbl.columns
+    assert list(tbl.index) == ["linear", "mean"]  # r2 降序 → 好的模型仍在前
+
+
+def test_compare_models_rejects_bad_metric_names(linear_data):
+    from mcm_toolkit.models import compare_models
+
+    x, y = linear_data
+    X = x.reshape(-1, 1)
+
+    with pytest.raises(ValueError, match="不认识的指标名"):
+        compare_models({"m": _MeanModel()}, X, y, metrics=("mse",), cv=0)
+    with pytest.raises(ValueError, match="别名"):
+        compare_models({"m": _MeanModel()}, X, y, metrics=("r2", "r2_score"), cv=0)
+    with pytest.raises(TypeError, match="不要传单个字符串"):
+        compare_models({"m": _MeanModel()}, X, y, metrics="rmse", cv=0)  # type: ignore[arg-type]
+    with pytest.raises(TypeError, match="tuple / list"):
+        compare_models({"m": _MeanModel()}, X, y, metrics=None, cv=0)  # type: ignore[arg-type]
+
+
+def test_compare_models_rejects_bad_models_and_cv(linear_data):
+    from mcm_toolkit.models import compare_models
+
+    x, y = linear_data
+    X = x.reshape(-1, 1)
+
+    with pytest.raises(TypeError, match="字典"):
+        compare_models([_MeanModel()], X, y)  # type: ignore[arg-type]
+    with pytest.raises(ValueError, match="不能为空"):
+        compare_models({}, X, y)
+    with pytest.raises(TypeError, match="Model 协议"):
+        compare_models({"bad": object()}, X, y, cv=0)
+    with pytest.raises(ValueError, match="cv=1"):
+        compare_models({"m": _MeanModel()}, X, y, cv=1)
+    with pytest.raises(ValueError, match="太大"):
+        compare_models({"m": _MeanModel()}, X, y, cv=1000)
+    with pytest.raises(ValueError, match="样本数必须一致"):
+        compare_models({"m": _MeanModel()}, X, y[:-1], cv=0)
+
+
+def test_compare_models_needs_two_samples_per_fold():
+    """每折至少 2 个样本（指标自己的入口要求），所以 cv 最多 n // 2。"""
+    from mcm_toolkit.models import compare_models
+
+    X = np.arange(4, dtype=float).reshape(-1, 1)
+    y = np.arange(4, dtype=float)
+
+    assert compare_models({"m": _MeanModel()}, X, y, cv=2, random_state=0).shape == (1, 3)
+    with pytest.raises(ValueError, match="太大"):
+        compare_models({"m": _MeanModel()}, X, y, cv=3, random_state=0)
+    with pytest.raises(ValueError, match="样本太少"):
+        compare_models({"m": _MeanModel()}, X[:1], y[:1], cv=0)
+
+
+def test_compare_models_is_reproducible_with_random_state(linear_data):
+    """分折用了随机数，所以必须服从 `random_state`（架构 §4.2）。"""
+    from mcm_toolkit.models import compare_models
+
+    x, y = linear_data
+    X = x.reshape(-1, 1)
+    models = {"mean": _MeanModel(), "linear": _LinearModel()}
+
+    first = compare_models(models, X, y, cv=5, random_state=42)
+    second = compare_models(models, X, y, cv=5, random_state=42)
+
+    assert first.equals(second)

tests/test_solve.py

@@ -5,7 +5,12 @@ from __future__ import annotations
 import numpy as np
 import pytest
 
-pytestmark = pytest.mark.skip(reason="未实现：见 docs/03-roadmap.md L0/L1")
+_NOT_IMPLEMENTED = "未实现：见 docs/03-roadmap.md L0/L1"
+
+
+def _normal_batch(rng, size, **kwargs):
+    """`monte_carlo` 的 sampler 契约：收下实现传来的 `size`，一次抽够。"""
+    return rng.normal(0, 1, size)
 
 
 def test_monte_carlo_integral_converges_to_analytic_value():
@@ -13,39 +18,610 @@ def test_monte_carlo_integral_converges_to_analytic_value():
     from mcm_toolkit.solve import monte_carlo_integral
 
     r = monte_carlo_integral(lambda X: X[:, 0] ** 2, bounds=[(0, 1)], n=200_000, random_state=0)
-    assert abs(r.data - 1 / 3) < 0.01
+    assert r.success
+    assert abs(r.metrics["mean"] - 1 / 3) < 0.01   # 体积必须是正的
+    assert len(r.data) == 200_000                 # data 是 n 个样本各自的贡献
+
+
+def test_monte_carlo_integral_odd_dimension_sign():
+    """∫∫∫ x dV over [0,1]³ = 1/2 —— 奇数维最容易暴露"体积符号写反"。"""
+    from mcm_toolkit.solve import monte_carlo_integral
+
+    r = monte_carlo_integral(lambda X: X[:, 0], bounds=[(0, 1)] * 3, n=200_000, random_state=0)
+    assert abs(r.metrics["mean"] - 0.5) < 0.01
+
+
+def test_monte_carlo_integral_signed_bounds():
+    """∫₀² x dx = 2 —— 边界带宽度时，体积算错和符号写反都会现形。"""
+    from mcm_toolkit.solve import monte_carlo_integral
+
+    r = monte_carlo_integral(lambda X: X[:, 0], bounds=[(0, 2)], n=200_000, random_state=0)
+    assert abs(r.metrics["mean"] - 2.0) < 0.02
+
+
+def test_monte_carlo_integral_2d_and_params():
+    from mcm_toolkit.solve import monte_carlo_integral
+
+    bounds = [(0, 1), (0, 1)]
+    r = monte_carlo_integral(lambda X: X[:, 0] * X[:, 1], bounds=bounds, n=200_000, random_state=0)
+    assert abs(r.metrics["mean"] - 0.25) < 0.01
+    assert r.name == "monte_carlo_integral"
+    assert r.params["dimension"] == 2
+    assert r.params["bounds"] == bounds
+
+
+def test_monte_carlo_integral_rejects_bad_bounds():
+    """四类非法 bounds 都要在入口抛 ValueError：区间反了 / 漏括号 / 空 / 参差不齐。"""
+    from mcm_toolkit.solve import monte_carlo_integral
+
+    for bad in ([(1, 0)], [0, 1], [], [(0, 1), (0, 2, 3)]):
+        with pytest.raises(ValueError):
+            monte_carlo_integral(lambda X: X[:, 0], bounds=bad, n=100, random_state=0)
+
+
+def test_monte_carlo_integral_failure_message_stays_failure():
+    """失败时 message 不能被包装层改写成"成功"（易错点 22）。"""
+    from mcm_toolkit.solve import monte_carlo_integral
+
+    r = monte_carlo_integral(lambda X: 1.0, bounds=[(0, 1)], n=100, random_state=0)
+    assert r.success is False
+    assert "成功" not in r.message
+    assert "失败" in r.message
+    assert r.params["dimension"] == 1          # 失败也要留下追溯信息
+
+
+def test_monte_carlo_integral_accepts_numpy_integer_n():
+    """§4.7：`np.int64` 不是 `int` 的子类，注解与运行期都要收（易错点 1）。"""
+    from mcm_toolkit.solve import monte_carlo_integral
+
+    r = monte_carlo_integral(lambda X: X[:, 0], bounds=[(0, 1)], n=np.int64(1000), random_state=0)
+    assert r.success
+    assert len(r.data) == 1000
 
 
 def test_monte_carlo_probability_of_standard_normal():
     """P(Z > 0) = 0.5，n=5000 时误差应 < 0.05。"""
     from mcm_toolkit.solve import monte_carlo_probability
 
-    r = monte_carlo_probability(
+    r = monte_carlo_probability(lambda z: z > 0, _normal_batch, n=5000, random_state=0)
-        lambda z: z > 0,
+    assert r.success
-        lambda rng, **kw: rng.standard_normal(),
-        n=5000,
-        random_state=0,
-    )
     assert abs(r.metrics["probability"] - 0.5) < 0.05
 
 
 def test_monte_carlo_is_reproducible():
     from mcm_toolkit.solve import monte_carlo_probability
 
-    args = (lambda z: z > 0, lambda rng, **kw: rng.standard_normal())
+    a = monte_carlo_probability(lambda z: z > 0, _normal_batch, n=1000, random_state=9)
-    a = monte_carlo_probability(*args, n=1000, random_state=9)
+    b = monte_carlo_probability(lambda z: z > 0, _normal_batch, n=1000, random_state=9)
-    b = monte_carlo_probability(*args, n=1000, random_state=9)
     assert a.metrics["probability"] == b.metrics["probability"]
 
 
+def test_monte_carlo_returns_n_results_and_documented_metrics():
+    from mcm_toolkit.solve import monte_carlo
+
+    r = monte_carlo(_normal_batch, lambda x: x**2, n=2000, random_state=0)
+    assert r.success
+    assert r.data.shape == (2000,)
+    assert set(r.metrics) == {"mean", "std", "median", "p05", "p95", "ci_low", "ci_high"}
+
+
+def test_monte_carlo_calls_simulator_only_once():
+    """`simulator` 只被调用一次 —— 这是"必须向量化"的可执行版本。"""
+    from mcm_toolkit.solve import monte_carlo
+
+    counter = {"calls": 0}
+
+    def simulator(params):
+        counter["calls"] += 1
+        return params
+
+    r = monte_carlo(_normal_batch, simulator, n=1000, random_state=0)
+    assert r.success
+    assert counter["calls"] == 1
+
+
+def test_monte_carlo_data_is_reproducible_with_same_seed():
+    from mcm_toolkit.solve import monte_carlo
+
+    a = monte_carlo(_normal_batch, lambda x: x, n=2000, random_state=11)
+    b = monte_carlo(_normal_batch, lambda x: x, n=2000, random_state=11)
+    assert np.array_equal(a.data, b.data)
+
+
+def test_monte_carlo_follows_set_seed_when_random_state_omitted():
+    from mcm_toolkit.core import set_seed
+    from mcm_toolkit.solve import monte_carlo
+
+    set_seed(5)
+    a = monte_carlo(_normal_batch, lambda x: x, n=500)
+    set_seed(5)
+    b = monte_carlo(_normal_batch, lambda x: x, n=500)
+    assert np.array_equal(a.data, b.data)
+
+
+def test_monte_carlo_estimates_known_expectation():
+    """E[X²] = 1（X ~ N(0, 1)）；n = 2e5 时误差应 < 0.02。"""
+    from mcm_toolkit.solve import monte_carlo
+
+    r = monte_carlo(_normal_batch, lambda x: x**2, n=200_000, random_state=0)
+    assert abs(r.metrics["mean"] - 1.0) < 0.02
+
+
+def test_monte_carlo_docstring_example_runs():
+    """docstring 的 Examples 必须真的能跑通（此前那一版是坏的）。"""
+    from mcm_toolkit.solve import monte_carlo
+
+    draw = lambda rng, size, **k: rng.normal(0, 1, size)  # noqa: E731
+    r = monte_carlo(draw, lambda x: x**2, n=10000, random_state=0)
+    assert r.success
+    assert abs(r.metrics["mean"] - 1.0) < 0.1
+
+
+def test_monte_carlo_accepts_numpy_integer_n():
+    """§4.7：`np.int64` 不是 `int` 的子类，不能漏。"""
+    from mcm_toolkit.solve import monte_carlo
+
+    r = monte_carlo(_normal_batch, lambda x: x, n=np.int64(100), random_state=0)
+    assert r.success
+    assert r.data.shape == (100,)
+
+
+def test_monte_carlo_counts_boolean_outcomes():
+    """布尔结果按 0/1 统计 —— 事件概率是 MC 最常见的用法。"""
+    from mcm_toolkit.solve import monte_carlo
+
+    r = monte_carlo(
+        lambda rng, size, **k: rng.normal(0, 1, size) > 0,
+        lambda x: x,
+        n=5000,
+        random_state=0,
+    )
+    assert r.success
+    assert r.data.dtype == float
+    assert abs(r.metrics["mean"] - 0.5) < 0.05
+
+
+def test_monte_carlo_rejects_nan_results():
+    """结果里出现 NaN 就判失败，不静默给出一列 nan 指标。"""
+    from mcm_toolkit.solve import monte_carlo
+
+    r = monte_carlo(
+        lambda rng, size, **k: np.r_[np.zeros(size - 1), np.nan],
+        lambda x: x,
+        n=10,
+        random_state=0,
+    )
+    assert not r.success
+    assert "NaN" in r.message
+
+
+def test_monte_carlo_rejects_bad_arguments():
+    from mcm_toolkit.solve import monte_carlo
+
+    with pytest.raises(TypeError):
+        monte_carlo(123, lambda x: x)  # type: ignore[arg-type]  # 就是要传错
+    with pytest.raises(TypeError):
+        monte_carlo(_normal_batch, 123)  # type: ignore[arg-type]  # 就是要传错
+    with pytest.raises(TypeError):
+        monte_carlo(_normal_batch, lambda x: x, n=True)
+    with pytest.raises(TypeError):
+        monte_carlo(_normal_batch, lambda x: x, n=10.0)  # type: ignore[arg-type]  # 就是要传错
+    with pytest.raises(ValueError):
+        monte_carlo(_normal_batch, lambda x: x, n=0)
+
+
+def test_monte_carlo_probability_returns_documented_metrics():
+    from mcm_toolkit.solve import monte_carlo_probability
+
+    r = monte_carlo_probability(lambda z: z > 0, _normal_batch, n=20000, random_state=0)
+    assert r.success
+    assert set(r.metrics) == {"probability", "ci_low", "ci_high", "std_error"}
+    assert r.data.shape == (20000,)
+    assert 0.0 <= r.metrics["ci_low"] <= r.metrics["probability"]
+    assert r.metrics["probability"] <= r.metrics["ci_high"] <= 1.0
+
+
+def test_monte_carlo_probability_std_error_matches_binomial_formula():
+    """`std_error` 就是比例的标准误 √(p(1-p)/n)。"""
+    from mcm_toolkit.solve import monte_carlo_probability
+
+    n = 20000
+    r = monte_carlo_probability(lambda z: z > 0, _normal_batch, n=n, random_state=0)
+    p = r.metrics["probability"]
+    assert np.isclose(r.metrics["std_error"], np.sqrt(p * (1 - p) / n))
+
+
+def test_monte_carlo_probability_ci_narrows_with_n():
+    """区间宽度随 n 增大而收窄（O(1/√n)）。"""
+    from mcm_toolkit.solve import monte_carlo_probability
+
+    def width(n):
+        r = monte_carlo_probability(lambda z: z > 0, _normal_batch, n=n, random_state=0)
+        return r.metrics["ci_high"] - r.metrics["ci_low"]
+
+    assert width(100_000) < width(1_000)
+
+
+def test_monte_carlo_probability_higher_confidence_is_wider():
+    from mcm_toolkit.solve import monte_carlo_probability
+
+    def width(confidence):
+        r = monte_carlo_probability(
+            lambda z: z > 0, _normal_batch, n=5000, random_state=0, confidence=confidence
+        )
+        return r.metrics["ci_high"] - r.metrics["ci_low"]
+
+    assert width(0.99) > width(0.90)
+
+
+def test_monte_carlo_probability_ci_matches_statsmodels_wilson():
+    """区间必须对得上独立实现（statsmodels 的 wilson）—— `^` 写成异或那次就靠它拦住。"""
+    from statsmodels.stats.proportion import proportion_confint
+
+    from mcm_toolkit.solve import monte_carlo_probability
+
+    n = 5000
+    r = monte_carlo_probability(lambda z: z > 0, _normal_batch, n=n, random_state=0)
+    count = int(r.data.sum())
+    lo, hi = proportion_confint(count, n, alpha=0.05, method="wilson")
+    assert np.isclose(r.metrics["ci_low"], lo)
+    assert np.isclose(r.metrics["ci_high"], hi)
+
+
+def test_monte_carlo_probability_rejects_bad_confidence():
+    from mcm_toolkit.solve import monte_carlo_probability
+
+    for bad in (0.0, 1.0, -0.5, 1.5):
+        with pytest.raises(ValueError):
+            monte_carlo_probability(lambda z: z > 0, _normal_batch, n=100, confidence=bad)
+
+
+def test_random_walk_shape_and_start():
+    """`data` 形状 (n_paths, n_steps + 1)，第 0 列是起点。"""
+    from mcm_toolkit.solve import random_walk
+
+    r = random_walk(n_steps=100, n_paths=5, start=2.5, random_state=0)
+    assert r.success
+    assert r.data.shape == (5, 101)
+    assert np.all(r.data[:, 0] == 2.5)
+
+
+def test_random_walk_default_steps_are_plus_minus_one():
+    """默认是对称随机游走：每一步都恰好是 ±1。"""
+    from mcm_toolkit.solve import random_walk
+
+    r = random_walk(n_steps=200, n_paths=3, random_state=0)
+    assert set(np.unique(np.diff(r.data, axis=1))) == {-1.0, 1.0}
+
+
+def test_random_walk_is_reproducible():
+    from mcm_toolkit.solve import random_walk
+
+    a = random_walk(n_steps=50, n_paths=4, random_state=7)
+    b = random_walk(n_steps=50, n_paths=4, random_state=7)
+    assert np.array_equal(a.data, b.data)
+
+
+def test_random_walk_accepts_custom_step_sampler():
+    """换成高斯增量就是带漂移的高斯游走 —— 建模差异全在 step_sampler 里。"""
+    from mcm_toolkit.solve import random_walk
+
+    r = random_walk(
+        n_steps=100,
+        n_paths=3,
+        step_sampler=lambda rng, size: rng.normal(0.5, 1.0, size),
+        random_state=0,
+    )
+    assert r.success
+    assert r.data.shape == (3, 101)
+    assert abs(r.data[:, -1].mean() - 50.0) < 20.0   # 100 步 × 漂移 0.5
+
+
+def test_random_walk_rejects_bad_arguments():
+    """§4.7 的分工：类型不对抛 TypeError，取值不对（<= 0）抛 ValueError。"""
+    from mcm_toolkit.solve import random_walk
+
+    with pytest.raises(TypeError):
+        random_walk(n_steps=2.5)  # type: ignore[arg-type]  # 就是要传错
+    with pytest.raises(TypeError):
+        random_walk(n_steps=True)
+    with pytest.raises(TypeError):
+        random_walk(n_steps=10, n_paths=1.5)  # type: ignore[arg-type]  # 就是要传错
+    with pytest.raises(ValueError):
+        random_walk(n_steps=0)
+    with pytest.raises(ValueError):
+        random_walk(n_steps=10, n_paths=0)
+    with pytest.raises(TypeError):
+        random_walk(n_steps=10, start="a")  # type: ignore[arg-type]  # 就是要传错
+
+
+def test_random_walk_rejects_2d_step_sampler():
+    """`step_sampler` 必须返回**一维** —— 二维返回（含方阵）一律判失败（易错点 25 的根治）。"""
+    from mcm_toolkit.solve import random_walk
+
+    def transposed(rng, size):
+        return rng.normal(0, 1, (4, 3))          # 无论要多少，一律给二维
+
+    r = random_walk(n_steps=4, n_paths=3, step_sampler=transposed, random_state=0)
+    assert r.success is False                    # 失败也要返回 Result，不能抛给调用方
+    assert "长度" in r.message
+    assert r.params["n_paths"] == 3              # 失败也要留下追溯信息
+    assert r.data is None
+
+    # 旧方案在 n_paths == n_steps 时对"转置"完全无感；现在同样拦住
+    assert random_walk(n_steps=3, n_paths=3, step_sampler=transposed, random_state=0).success is False
+
+
+def test_random_walk_step_sampler_gets_flat_size_and_is_row_major():
+    """契约：`size` 是整数 `n_paths * n_steps`，一维增量按**行主序**切成 n_paths 行。"""
+    from mcm_toolkit.solve import random_walk
+
+    seen = {}
+
+    def sampler(rng, size):
+        seen["size"] = size
+        return np.arange(1, size + 1, dtype=float)   # 1, 2, 3, 4, 5, 6
+
+    r = random_walk(n_steps=3, n_paths=2, step_sampler=sampler, random_state=0)
+    assert seen["size"] == 6                                  # 整数，不是 (n_paths, n_steps)
+    assert r.data.tolist() == [[0, 1, 3, 6], [0, 4, 9, 15]]   # cumsum(1,2,3) / cumsum(4,5,6)
+
+
+def test_random_walk_rejects_nan_steps():
+    """增量含 NaN 判失败 —— 与 monte_carlo 的 NaN 口径（决策 48）一致。"""
+    from mcm_toolkit.solve import random_walk
+
+    r = random_walk(
+        n_steps=4,
+        n_paths=2,
+        step_sampler=lambda rng, size: np.full(size, np.nan),
+        random_state=0,
+    )
+    assert r.success is False
+    assert "NaN" in r.message
+
+
+def test_random_walk_accepts_numpy_integer():
+    """§4.7：`np.int64` 不是 `int` 的子类，注解与运行期都要收（易错点 1）。"""
+    from mcm_toolkit.solve import random_walk
+
+    r = random_walk(n_steps=np.int64(20), n_paths=np.int64(3), random_state=0)
+    assert r.success
+    assert r.data.shape == (3, 21)
+
+
+def test_random_walk_metrics_are_terminal_positions():
+    """终点位置的标准差按 √t 扩散（t = n_steps）—— 随机游走的核心性质。"""
+    from mcm_toolkit.solve import random_walk
+
+    n_steps = 100
+    r = random_walk(n_steps=n_steps, n_paths=2000, start=5.0, random_state=0)
+    assert abs(r.metrics["mean_terminal"] - 5.0) < 5.0              # 对称游走，期望还在起点附近
+    assert abs(r.metrics["std_terminal"] - np.sqrt(n_steps)) < 5.0  # √t 扩散
+
+
+def test_random_walk_docstring_example_runs():
+    from mcm_toolkit.solve import random_walk
+
+    r = random_walk(n_steps=100, n_paths=5, random_state=0)
+    assert r.data.shape == (5, 101)
+    assert np.all(np.abs(np.diff(r.data, axis=1)) == 1)
+
+def test_markov_simulate_shape_start_and_states():
+    """`data` 形状 (n_paths, steps + 1)，第 0 列是初始状态，取值只能是合法状态编号。"""
+    from mcm_toolkit.solve import markov_simulate
+
+    P = np.array([[0.9, 0.1], [0.2, 0.8]])
+    r = markov_simulate(P, initial=0, steps=100, n_paths=5, random_state=0)
+    assert r.success
+    assert r.data.shape == (5, 101)
+    assert np.all(r.data[:, 0] == 0)
+    assert set(np.unique(r.data)) <= {0, 1}
+    assert np.issubdtype(r.data.dtype, np.integer)
+
+
+def test_markov_simulate_absorbing_states_never_move():
+    """单位转移矩阵：状态自锁，整条路径恒等于初始状态（确定性自检）。"""
+    from mcm_toolkit.solve import markov_simulate
+
+    r = markov_simulate(np.eye(2), initial=1, steps=30, n_paths=4, random_state=0)
+    assert r.success
+    assert np.all(r.data == 1)
+    assert r.metrics["mean_terminal"] == 1.0
+    assert r.metrics["terminal_distribution"] == {1: 1.0}
+
+
+def test_markov_simulate_is_reproducible():
+    from mcm_toolkit.solve import markov_simulate
+
+    P = np.array([[0.7, 0.3], [0.4, 0.6]])
+    a = markov_simulate(P, initial=0, steps=40, n_paths=6, random_state=11)
+    b = markov_simulate(P, initial=0, steps=40, n_paths=6, random_state=11)
+    c = markov_simulate(P, initial=0, steps=40, n_paths=6, random_state=12)
+    assert np.array_equal(a.data, b.data)
+    assert not np.array_equal(a.data, c.data)
+
+
+def test_markov_simulate_terminal_frequency_matches_stationary():
+    """终点频率收敛到平稳分布 [2/3, 1/3] —— 马尔可夫链模拟的核心性质。"""
+    from mcm_toolkit.solve import markov_simulate
+
+    P = np.array([[0.9, 0.1], [0.2, 0.8]])
+    r = markov_simulate(P, initial=0, steps=200, n_paths=20000, random_state=0)
+    freq = np.bincount(r.data[:, -1], minlength=2) / r.data.shape[0]
+    assert np.allclose(freq, [2 / 3, 1 / 3], atol=0.02)
+
+
+def test_markov_simulate_metrics_are_terminal_states():
+    """`metrics` 只看终点：均值 + `{状态: 频率}`（频率之和为 1、与逐条统计一致）。"""
+    from mcm_toolkit.solve import markov_simulate
+
+    P = np.array([[0.9, 0.1], [0.2, 0.8]])
+    r = markov_simulate(P, initial=0, steps=50, n_paths=500, random_state=3)
+    terminal = r.data[:, -1]
+    dist = r.metrics["terminal_distribution"]
+    assert r.metrics["mean_terminal"] == float(np.mean(terminal))
+    assert np.isclose(sum(dist.values()), 1.0)
+    for state, freq in dist.items():
+        assert np.isclose(freq, float(np.mean(terminal == state)))
+
+
+def test_markov_simulate_terminal_distribution_only_lists_seen_states():
+    """只含实际出现过的状态（没出现的状态没有 key）—— docstring 已写明这条口径。"""
+    from mcm_toolkit.solve import markov_simulate
+
+    r = markov_simulate(np.eye(3), initial=2, steps=5, n_paths=4, random_state=0)
+    assert r.metrics["terminal_distribution"] == {2: 1.0}
+
+
+def test_markov_simulate_rejects_bad_transition():
+    """非方阵、行和不为 1 都要在入口直接报错，不能悄悄模拟。"""
+    from mcm_toolkit.solve import markov_simulate
+
+    with pytest.raises(ValueError):
+        markov_simulate(np.array([[0.5, 0.5, 0.0], [0.2, 0.8, 0.0]]), initial=0)
+    with pytest.raises(ValueError):
+        markov_simulate(np.array([[0.5, 0.4], [0.2, 0.8]]), initial=0)
+    with pytest.raises(ValueError):
+        markov_simulate(np.array([[1.5, -0.5], [0.0, 1.0]]), initial=0)  # 行和是 1，但含负元素
+
+
+def test_markov_simulate_rejects_bad_arguments():
+    """§4.7：步数 / 路径数的类型与正负都要卡住（bool 先判，易错点 1）。"""
+    from mcm_toolkit.solve import markov_simulate
+
+    P = np.array([[0.9, 0.1], [0.2, 0.8]])
+    with pytest.raises(ValueError):
+        markov_simulate(P, initial=0, steps=0)
+    with pytest.raises(ValueError):
+        markov_simulate(P, initial=0, n_paths=0)
+    with pytest.raises(TypeError):
+        markov_simulate(P, initial=0, steps=1.5)  # type: ignore[arg-type]  # 就是要传错
+    with pytest.raises(TypeError):
+        markov_simulate(P, initial=0, n_paths=1.5)  # type: ignore[arg-type]  # 就是要传错
+    with pytest.raises(TypeError):
+        markov_simulate(P, initial=0, steps=True)  # type: ignore[arg-type]  # 就是要传错
+    with pytest.raises(TypeError):
+        markov_simulate(P, initial=0, n_paths=True)  # type: ignore[arg-type]  # 就是要传错
+
+
+def test_markov_simulate_accepts_numpy_integer():
+    from mcm_toolkit.solve import markov_simulate
+
+    P = np.array([[0.9, 0.1], [0.2, 0.8]])
+    r = markov_simulate(P, initial=0, steps=np.int64(10), n_paths=np.int64(2), random_state=0)
+    assert r.success
+    assert r.data.shape == (2, 11)
+
+
+def test_markov_simulate_docstring_example_runs():
+    from mcm_toolkit.solve import markov_simulate
+
+    P = np.array([[0.9, 0.1], [0.2, 0.8]])
+    r = markov_simulate(P, initial=0, steps=50, n_paths=4, random_state=0)
+    assert r.data.shape == (4, 51)
+    assert np.all(r.data[:, 0] == 0)
+
+
 def test_markov_steady_state_two_state_chain():
     """P=[[0.9,0.1],[0.2,0.8]] 的平稳分布是 [2/3, 1/3]。"""
     from mcm_toolkit.solve import markov_steady_state
 
     r = markov_steady_state(np.array([[0.9, 0.1], [0.2, 0.8]]))
+    assert r.success
     assert np.allclose(r.data, [2 / 3, 1 / 3], atol=1e-6)
+    assert r.metrics["converged"] is True
+    assert r.metrics["iterations"] > 0
 
 
+def test_markov_steady_state_matches_eigenvector():
+    """与特征分解对拍：取特征值 1 对应的左特征向量（只是检验手段，实现仍走迭代）。"""
+    from mcm_toolkit.solve import markov_steady_state
+
+    P = np.array([[0.5, 0.25, 0.25], [0.1, 0.8, 0.1], [0.2, 0.2, 0.6]])
+    eigenvalues, eigenvectors = np.linalg.eig(P.T)
+    ref = np.real(eigenvectors[:, int(np.argmin(np.abs(eigenvalues - 1.0)))])
+    ref = ref / ref.sum()
+
+    r = markov_steady_state(P)
+    assert np.allclose(r.data, ref, atol=1e-6)
+
+
+def test_markov_steady_state_is_a_distribution():
+    from mcm_toolkit.solve import markov_steady_state
+
+    P = np.array([[0.7, 0.2, 0.1], [0.1, 0.6, 0.3], [0.05, 0.15, 0.8]])
+    r = markov_steady_state(P)
+    assert r.data.shape == (3,)
+    assert np.isclose(float(np.sum(r.data)), 1.0)
+    assert np.all(r.data >= 0.0)
+    assert r.data.dtype == np.float64
+
+
+def test_markov_steady_state_slow_mixing_needs_more_iterations():
+    """慢混合链：迭代次数显著变多，但结果仍要对得上特征向量（tol 是相邻差口径）。"""
+    from mcm_toolkit.solve import markov_steady_state
+
+    P = np.array([[0.999, 0.001], [0.02, 0.98]])
+    r = markov_steady_state(P)
+    assert r.metrics["iterations"] > 100
+    assert np.allclose(r.data, [0.9523809524, 0.0476190476], atol=1e-6)
+
+
+def test_markov_steady_state_accepts_numpy_integer():
+    """§4.7：`np.int64` 不是 `int` 的子类，注解与运行期都要收（易错点 1）。"""
+    from mcm_toolkit.solve import markov_steady_state
+
+    P = np.array([[0.9, 0.1], [0.2, 0.8]])
+    r = markov_steady_state(P, max_iter=np.int64(10000))
+    assert r.success
+    assert r.metrics["converged"] is True
+
+
+def test_markov_steady_state_rejects_bad_transition():
+    from mcm_toolkit.solve import markov_steady_state
+
+    with pytest.raises(TypeError):
+        markov_steady_state(np.ones((2, 3)) / 3)  # 形状不对 → TypeError（口径见决策 57）
+    with pytest.raises(ValueError):
+        markov_steady_state(np.array([[0.5, 0.4], [0.2, 0.8]]))
+    with pytest.raises(ValueError):
+        markov_steady_state(np.array([[1.5, -0.5], [0.0, 1.0]]))  # 行和是 1，但含负元素
+
+
+def test_markov_steady_state_non_convergence_is_success_false():
+    """`max_iter` 不够时按"未收敛"处理：`success=False` 且 `converged=False`（口径 B）。"""
+    from mcm_toolkit.solve import markov_steady_state
+
+    P = np.array([[0.9, 0.1], [0.2, 0.8]])
+    r = markov_steady_state(P, max_iter=3)
+    assert r.success is False
+    assert r.metrics["converged"] is False
+    assert r.metrics["iterations"] == 3
+    assert "未在最大迭代次数内收敛" in r.message
+
+
+def test_markov_steady_state_rejects_bad_arguments():
+    """取值错一律 `ValueError`（类型错要不要拆 `TypeError` 待定，见 STATUS 决策 57）。"""
+    from mcm_toolkit.solve import markov_steady_state
+
+    P = np.array([[0.9, 0.1], [0.2, 0.8]])
+    with pytest.raises(ValueError):
+        markov_steady_state(P, max_iter=0)
+    with pytest.raises(ValueError):
+        markov_steady_state(P, tol=0)
+
+
+def test_markov_steady_state_docstring_example_runs():
+    from mcm_toolkit.solve import markov_steady_state
+
+    P = np.array([[0.9, 0.1], [0.2, 0.8]])
+    r = markov_steady_state(P)
+    assert bool(np.allclose(r.data, [2 / 3, 1 / 3], atol=1e-6))
+
+
+
+@pytest.mark.skip(reason=_NOT_IMPLEMENTED)
 def test_knapsack_dp_known_optimum():
     from mcm_toolkit.solve import knapsack_dp
 
@@ -54,6 +630,7 @@ def test_knapsack_dp_known_optimum():
     assert np.isclose(r.metrics["total_weight"], 7.0)
 
 
+@pytest.mark.skip(reason=_NOT_IMPLEMENTED)
 def test_linear_program_basic():
     from mcm_toolkit.solve import linear_program
 
@@ -63,20 +640,79 @@ def test_linear_program_basic():
 
 
 def test_mm1_metrics_closed_form():
+    """与闭式公式逐项对拍（ρ = λ/μ，L = ρ/(1-ρ)，Wq = ρ/(μ-λ)，W = Wq + 1/μ）。"""
     from mcm_toolkit.solve import mm1_metrics
 
-    r = mm1_metrics(arrival_rate=2, service_rate=3)
+    arrival_rate, service_rate = 2, 3
-    assert np.isclose(r.metrics["rho"], 2 / 3, rtol=1e-6)
+    rho = arrival_rate / service_rate
-    assert np.isclose(r.metrics["L"], 2.0, rtol=1e-6)
+    r = mm1_metrics(arrival_rate=arrival_rate, service_rate=service_rate)
+
+    assert r.success
+    assert np.isclose(r.metrics["rho"], rho, rtol=1e-12)
+    assert np.isclose(r.metrics["L"], rho / (1 - rho), rtol=1e-12)
+    assert np.isclose(r.metrics["Lq"], rho**2 / (1 - rho), rtol=1e-12)
+    assert np.isclose(r.metrics["W"], 1 / (service_rate - arrival_rate), rtol=1e-12)
+    assert np.isclose(r.metrics["Wq"], rho / (service_rate - arrival_rate), rtol=1e-12)
+    assert np.isclose(r.metrics["W"], r.metrics["Wq"] + 1 / service_rate, rtol=1e-12)
 
 
 def test_mm1_rejects_unstable_system():
-    """λ >= μ 时系统不稳定，应 success=False 而不是返回 inf。"""
+    """λ >= μ 时系统不稳定，应 success=False 而不是返回 inf（λ == μ 也要走这一支）。"""
     from mcm_toolkit.solve import mm1_metrics
 
-    assert mm1_metrics(arrival_rate=3, service_rate=3).success is False
+    equal = mm1_metrics(arrival_rate=3, service_rate=3)
+    assert equal.success is False
+    assert "不稳定" in equal.message
+    assert equal.metrics == {"rho": 1.0}  # 失败时也把 rho 报出来（决策 58 的 ④）
+    assert equal.data is None
+
+    assert mm1_metrics(arrival_rate=3, service_rate=2).success is False
 
 
+def test_mm1_allows_zero_arrival_rate_as_empty_system():
+    """λ = 0 是合法退化解：空系统（L = Lq = Wq = 0，W 取极限值 1/μ）。"""
+    from mcm_toolkit.solve import mm1_metrics
+
+    r = mm1_metrics(arrival_rate=0, service_rate=3)
+    assert r.success
+    assert r.metrics["rho"] == 0.0
+    assert r.metrics["L"] == 0.0
+    assert r.metrics["Lq"] == 0.0
+    assert r.metrics["Wq"] == 0.0
+    assert np.isclose(r.metrics["W"], 1 / 3)
+
+
+def test_mm1_rejects_bad_arguments():
+    """λ 非负、μ 必须为正；bool 与非数值都要在入口拦下。"""
+    from mcm_toolkit.solve import mm1_metrics
+
+    with pytest.raises(ValueError):
+        mm1_metrics(arrival_rate=-1, service_rate=3)
+    with pytest.raises(ValueError):
+        mm1_metrics(arrival_rate=2, service_rate=0)
+    with pytest.raises(TypeError):
+        mm1_metrics(arrival_rate=True, service_rate=3)
+    with pytest.raises(TypeError):
+        mm1_metrics(arrival_rate=2, service_rate="3")  # type: ignore[arg-type]  # 就是要传错
+
+
+def test_mm1_docstring_example_runs():
+    from mcm_toolkit.solve import mm1_metrics
+
+    r = mm1_metrics(arrival_rate=2, service_rate=3)
+    assert round(r.metrics["rho"], 4) == 0.6667
+
+
+def test_mm1_stability_boundary_is_success_not_exception():
+    """λ == μ 不能靠 ZeroDivisionError 落到失败分支：必须是显式的"不稳定"口径。"""
+    from mcm_toolkit.solve import mm1_metrics
+
+    r = mm1_metrics(arrival_rate=5, service_rate=5)
+    assert r.success is False
+    assert "ZeroDivisionError" not in r.message
+
+
+@pytest.mark.skip(reason=_NOT_IMPLEMENTED)
 def test_simulated_annealing_finds_quadratic_minimum():
     from mcm_toolkit.solve import simulated_annealing
 

tests/test_stats.py

@@ -1,14 +1,29 @@
 """stats 包测试。
 
 原则（见 docs/02-architecture.md §5）：**测已知解析解，不测实现细节**。
+
+未实现的函数**逐条** `skip`——**不要**用模块级 `pytestmark`：那会把同文件里
+已经写好的函数一起跳过，绿灯就是假的（决策 26 / 个人易错点 9）。
 """
 
 from __future__ import annotations
 
 import numpy as np
+import pandas as pd
 import pytest
 
-pytestmark = pytest.mark.skip(reason="未实现：见 docs/03-roadmap.md L1")
+_NOT_IMPLEMENTED = "未实现：见 docs/03-roadmap.md L1"
+
+
+def _pearson_p_from_r(r: float, n: int) -> float:
+    """Pearson 相关系数的 p 值**解析式**（测解析解，不测实现细节）：
+
+    ``t = r * sqrt((n - 2) / (1 - r^2))``，``p = 2 * P(T > |t|)``，``T ~ t(n - 2)``。
+    """
+    from scipy import stats as sps
+
+    t_stat = r * np.sqrt((n - 2) / (1 - r**2))
+    return float(2 * sps.t.sf(abs(t_stat), n - 2))
 
 
 def test_bootstrap_ci_matches_normal_theory_on_large_n(rng):
@@ -40,6 +55,82 @@ def test_bootstrap_ci_is_reproducible(rng):
     assert a.params["low"] == b.params["low"]
 
 
+def test_bootstrap_ci_reports_the_original_estimate(rng):
+    """`params["estimate"]` 必须是**原样本**上的统计量，不是重采样分布的均值。"""
+    from mcm_toolkit.stats import bootstrap_ci
+
+    x = rng.normal(10, 2, size=200)
+    r = bootstrap_ci(x, statistic=np.mean, n_resamples=500, random_state=0)
+
+    assert r.params["estimate"] == pytest.approx(float(np.mean(x)))
+    assert set(r.params) == {"estimate", "low", "high", "confidence", "n_resamples"}
+    assert r.params["n_resamples"] == 500
+    assert r.metrics["statistic_name"] == "mean"
+
+
+def test_bootstrap_ci_interval_widens_with_confidence(rng):
+    """置信水平越高区间必须越宽 —— 结构性检查，不依赖任何具体分布。"""
+    from mcm_toolkit.stats import bootstrap_ci
+
+    x = rng.normal(size=300)
+    width = [
+        bootstrap_ci(x, np.mean, confidence=c, n_resamples=2000, random_state=7).params["high"]
+        - bootstrap_ci(x, np.mean, confidence=c, n_resamples=2000, random_state=7).params["low"]
+        for c in (0.80, 0.95)
+    ]
+    assert width[0] < width[1]
+
+
+def test_bootstrap_ci_accepts_the_documented_containers(rng):
+    """DataFrame 只取数值列后摊平；Series / ndarray / list 都收。"""
+    from mcm_toolkit.stats import bootstrap_ci
+
+    x = rng.normal(size=200)
+    ref = bootstrap_ci(x, np.mean, n_resamples=500, random_state=0).params
+
+    for wrapped in (pd.Series(x), pd.DataFrame({"a": x}), list(x), tuple(x)):
+        got = bootstrap_ci(wrapped, np.mean, n_resamples=500, random_state=0).params
+        assert got["low"] == pytest.approx(ref["low"])
+
+
+def test_bootstrap_ci_works_for_a_custom_lambda(rng):
+    """不认识的统计量走逐样本回退分支（这里是极差）。"""
+    from mcm_toolkit.stats import bootstrap_ci
+
+    x = rng.normal(size=200)
+    r = bootstrap_ci(x, statistic=lambda s: float(s.max() - s.min()), n_resamples=500, random_state=0)
+
+    # 极差的重采样值**永远不会超过原样本极差**（原样本本身就是上界），
+    # 所以百分位区间的上界会正好落在 estimate 上，不能再断言 estimate < high。
+    assert r.params["estimate"] == pytest.approx(float(x.max() - x.min()))
+    assert r.params["low"] > 0
+    assert r.params["low"] < r.params["high"] <= r.params["estimate"]
+    assert r.metrics["statistic_name"] == "custom"
+
+
+def test_bootstrap_ci_follows_get_rng_when_no_seed_is_given(rng):
+    """不给种子时必须跟随 `get_rng` 的模块级生成器（决策 24），不能另开一个 default_rng。"""
+    from mcm_toolkit.core import set_seed
+    from mcm_toolkit.stats import bootstrap_ci
+
+    x = rng.normal(size=200)
+    set_seed(0)
+    first = bootstrap_ci(x, np.mean, n_resamples=300).params["low"]
+    set_seed(0)
+    second = bootstrap_ci(x, np.mean, n_resamples=300).params["low"]
+
+    assert first == second
+
+
+def test_bootstrap_ci_rejects_unknown_method(rng):
+    from mcm_toolkit.stats import bootstrap_ci
+
+    with pytest.raises(ValueError, match="bogus"):
+        bootstrap_ci(rng.normal(size=50), np.mean, method="bogus", n_resamples=10)
+    with pytest.raises(NotImplementedError):
+        bootstrap_ci(rng.normal(size=50), np.mean, method="bca", n_resamples=10)
+
+
 def test_confidence_interval_matches_scipy(rng):
     from scipy import stats
 
@@ -51,17 +142,461 @@ def test_confidence_interval_matches_scipy(rng):
     assert np.allclose([lo, hi], ref, rtol=1e-6)
 
 
+def test_confidence_interval_normal_matches_z_formula(rng):
+    """normal 走 z 解析式：`mean ± z·s/√n`，s 用**样本**标准差（ddof=1）。"""
+    from scipy import stats as sps
+
+    from mcm_toolkit.stats import confidence_interval
+
+    x = rng.normal(8.5, 1, size=200)
+    lo, hi = confidence_interval(x, confidence=0.95, method="normal")
+
+    half = float(sps.norm.ppf(0.975)) * x.std(ddof=1) / np.sqrt(len(x))
+    assert lo == pytest.approx(x.mean() - half)
+    assert hi == pytest.approx(x.mean() + half)
+
+
+def test_confidence_interval_mean_is_not_clamped_to_unit_range(rng):
+    """均值区间不该被夹到 [0, 1]：平均身高 170cm 的下界不可能是 0。"""
+    from mcm_toolkit.stats import confidence_interval
+
+    x = rng.normal(170, 8, size=50)
+    lo, hi = confidence_interval(x, method="t")
+
+    assert lo > 100.0
+    assert lo < hi
+
+
+def test_confidence_interval_proportion_stays_in_unit_interval():
+    """比例的区间必须落在 [0, 1] 里 —— 只有这一种 method 需要夹。"""
+    from mcm_toolkit.stats import confidence_interval
+
+    y = [0.0, 1.0, 1.0, 1.0, 0.0, 1.0]
+    lo, hi = confidence_interval(y, method="proportion")
+
+    assert 0.0 <= lo < hi <= 1.0
+
+
+def test_confidence_interval_accepts_documented_containers():
+    """docstring 的 Examples 传 list、L0 用例传 ndarray，两边都得收。"""
+    from mcm_toolkit.stats import confidence_interval
+
+    data = [1.0, 2.0, 3.0, 4.0, 5.0]
+    expected = confidence_interval(data)
+
+    assert confidence_interval(pd.Series(data)) == pytest.approx(expected)
+    assert confidence_interval(np.asarray(data)) == pytest.approx(expected)
+    assert confidence_interval(pd.DataFrame({"x": data})) == pytest.approx(expected)
+
+
+def test_confidence_interval_rejects_bad_input(rng):
+    from mcm_toolkit.stats import confidence_interval
+
+    x = rng.normal(size=20)
+    with pytest.raises(TypeError):
+        confidence_interval("abc")
+    with pytest.raises(ValueError):
+        confidence_interval(x, method="bogus")
+    with pytest.raises(ValueError):
+        confidence_interval(x, confidence=1.5)
+    with pytest.raises(ValueError):
+        confidence_interval(x, confidence=0.0)
+    with pytest.raises(ValueError):
+        confidence_interval(pd.DataFrame({"city": ["X", "Y"]}))
+    with pytest.raises(ValueError):
+        confidence_interval([1.0])
+
+
+# ------------------------------------------------------ stats: t_test
+
+
+def test_t_test_one_sample_matches_analytic_formula(rng):
+    """单样本：`t = (mean - value) / (s/√n)`，`df = n - 1`，`p = 2·P(T > |t|)`。"""
+    from scipy import stats as sps
+
+    from mcm_toolkit.stats import t_test
+
+    x = rng.normal(5, 1, size=30)
+    r = t_test(x, value=5.0)
+
+    t_stat = (x.mean() - 5.0) / (x.std(ddof=1) / np.sqrt(len(x)))
+    assert r["statistic"] == pytest.approx(t_stat)
+    assert r["pvalue"] == pytest.approx(float(2 * sps.t.sf(abs(t_stat), len(x) - 1)))
+    assert r["df"] == pytest.approx(29.0)
+    assert r["significant"] == (r["pvalue"] < 0.05)
+    assert isinstance(r["conclusion"], str) and r["conclusion"]
+
+
+def test_t_test_two_sample_welch_df_matches_formula(rng):
+    """默认 Welch：`df` 用 Welch–Satterthwaite 公式解析对照。"""
+    from mcm_toolkit.stats import t_test
+
+    a = rng.normal(0, 1, size=25)
+    b = rng.normal(1, 4, size=35)
+    r = t_test(a, b)
+
+    v1, v2 = a.var(ddof=1), b.var(ddof=1)
+    n1, n2 = len(a), len(b)
+    expected_df = (v1 / n1 + v2 / n2) ** 2 / ((v1 / n1) ** 2 / (n1 - 1) + (v2 / n2) ** 2 / (n2 - 1))
+    assert r["df"] == pytest.approx(expected_df)
+    assert r["pvalue"] < 0.05
+
+
+def test_t_test_equal_var_uses_pooled_df(rng):
+    from mcm_toolkit.stats import t_test
+
+    a = rng.normal(0, 1, size=25)
+    b = rng.normal(1, 1, size=35)
+
+    assert t_test(a, b, equal_var=True)["df"] == pytest.approx(58.0)
+
+
+def test_t_test_paired_reports_key_set_and_df(rng):
+    from mcm_toolkit.stats import t_test
+
+    a = rng.normal(size=20)
+    r = t_test(a, a + rng.normal(0, 0.1, 20), paired=True)
+
+    assert set(r) == {"statistic", "pvalue", "df", "significant", "conclusion"}
+    assert r["df"] == pytest.approx(19.0)
+
+
+def test_t_test_rejects_bad_input(rng):
+    from mcm_toolkit.stats import t_test
+
+    a = rng.normal(size=20)
+    with pytest.raises(ValueError):
+        t_test(a, alpha=1.5)
+    with pytest.raises(ValueError):
+        t_test([1.0])
+    with pytest.raises(ValueError):
+        t_test(a, rng.normal(size=19), paired=True)
+    with pytest.raises(ValueError):
+        t_test(pd.DataFrame({"city": ["X", "Y"]}))
+    with pytest.raises(TypeError):
+        t_test("abc")
+
+
 def test_correlation_matrix_diagonal_is_one(rng):
     from mcm_toolkit.stats import correlation_matrix
 
-    x = rng.normal(size=(200, 4))
+    x = pd.DataFrame(rng.normal(size=(200, 4)), columns=["a", "b", "c", "d"])
     c = correlation_matrix(x)
+
     assert np.allclose(np.diag(np.asarray(c)), 1.0)
 
 
+def test_correlation_matrix_is_numeric_and_symmetric(rng):
+    """方案 A：返回**数值**矩阵（不是带星标的字符串表），能直接参与后续计算。"""
+    from mcm_toolkit.stats import correlation_matrix
+
+    x = pd.DataFrame(rng.normal(size=(200, 3)), columns=["a", "b", "c"])
+    c = correlation_matrix(x)
+
+    assert all(np.issubdtype(dtype, np.floating) for dtype in c.dtypes)
+    assert np.allclose(np.asarray(c), np.asarray(x.corr(method="pearson", min_periods=1)))
+    assert np.allclose(np.asarray(c), np.asarray(c.T))
+
+
+def test_correlation_matrix_runs_on_multicolumn_frame(rng):
+    """回归：`if numeric_cols == 0` 拿 Index 跟 0 比，多列数值表当场 ValueError 崩掉。"""
+    from mcm_toolkit.stats import correlation_matrix
+
+    x = pd.DataFrame(rng.normal(size=(50, 3)), columns=["a", "b", "c"])
+    out = correlation_matrix(x)
+
+    assert out.shape == (3, 3)
+    assert list(out.columns) == ["a", "b", "c"]
+    assert list(out.index) == ["a", "b", "c"]
+
+
+def test_correlation_matrix_skips_non_numeric_columns(rng):
+    from mcm_toolkit.stats import correlation_matrix
+
+    x = pd.DataFrame({"a": rng.normal(size=30), "b": rng.normal(size=30), "city": ["X"] * 30})
+    assert list(correlation_matrix(x).columns) == ["a", "b"]
+
+
+def test_correlation_matrix_rejects_bad_input():
+    from mcm_toolkit.stats import correlation_matrix
+
+    with pytest.raises(TypeError):
+        correlation_matrix([[1.0, 2.0]])
+    with pytest.raises(ValueError):
+        correlation_matrix(pd.DataFrame({"city": ["X", "Y"]}))
+    with pytest.raises(ValueError):
+        correlation_matrix(pd.DataFrame({"a": [1.0, 2.0]}), method="bogus")  # type: ignore[arg-type]
+
+
+def test_correlation_pvalues_matches_analytic_formula(rng):
+    from mcm_toolkit.stats import correlation_matrix, correlation_pvalues
+
+    x = pd.DataFrame(rng.normal(size=(80, 3)), columns=["a", "b", "c"])
+    corr = correlation_matrix(x)
+    p = correlation_pvalues(x)
+
+    for i in ["a", "b", "c"]:
+        for j in ["a", "b", "c"]:
+            if i == j:
+                continue
+            assert p.loc[i, j] == pytest.approx(_pearson_p_from_r(corr.loc[i, j], 80))
+
+
+def test_correlation_pvalues_diagonal_is_nan(rng):
+    """对角线写 0 会被下游读成"极显著"；"自己和自己相关"没有 p 值，必须是 NaN。"""
+    from mcm_toolkit.stats import correlation_pvalues
+
+    p = correlation_pvalues(pd.DataFrame(rng.normal(size=(50, 2)), columns=["a", "b"]))
+
+    assert np.isnan(p.loc["a", "a"])
+    assert np.isnan(p.loc["b", "b"])
+
+
+def test_correlation_pvalues_uses_the_same_observations_as_r(rng):
+    """含缺失时 p 要和 r 用**同一批**观测：成对删缺失，而不是整行删、也不是干脆不删。"""
+    from mcm_toolkit.stats import correlation_pvalues
+
+    a = rng.normal(size=40)
+    b = rng.normal(size=40)
+    a[[3, 7, 11]] = np.nan
+    x = pd.DataFrame({"a": a, "b": b})
+
+    pair = x.dropna()
+    r = float(np.corrcoef(pair["a"], pair["b"])[0, 1])
+
+    assert correlation_pvalues(x).loc["a", "b"] == pytest.approx(_pearson_p_from_r(r, len(pair)))
+
+
+def test_correlation_pvalues_respects_min_periods(rng):
+    from mcm_toolkit.stats import correlation_pvalues
+
+    a = rng.normal(size=10)
+    a[:5] = np.nan
+    x = pd.DataFrame({"a": a, "b": rng.normal(size=10)})
+
+    assert np.isnan(correlation_pvalues(x, min_periods=6).loc["a", "b"])
+    assert np.isfinite(correlation_pvalues(x, min_periods=5).loc["a", "b"])
+
+
+def test_correlation_table_diagonal_has_no_stars():
+    """对角线是"自己和自己"，不该有显著性星标；完全负相关则必然是 ***。"""
+    from mcm_toolkit.stats import correlation_table
+
+    x = pd.DataFrame({"a": np.arange(30.0), "b": np.arange(30.0) * -2.0})
+    table = correlation_table(x)
+
+    assert table.loc["a", "a"] == "1.000"
+    assert table.loc["a", "b"] == "-1.000***"
+
+
+def test_correlation_table_matches_the_numeric_outputs(rng):
+    from mcm_toolkit.stats import correlation_matrix, correlation_pvalues, correlation_table
+
+    x = pd.DataFrame(rng.normal(size=(60, 3)), columns=["a", "b", "c"])
+    corr = correlation_matrix(x)
+    p = correlation_pvalues(x)
+    table = correlation_table(x)
+
+    assert list(table.columns) == list(corr.columns)
+    assert table.loc["a", "a"] == "1.000"
+    assert np.isnan(p.loc["a", "a"])
+
+    pv = p.loc["a", "b"]
+    stars = "***" if pv < 0.001 else "**" if pv < 0.01 else "*" if pv < 0.05 else ""
+    value = corr.loc["a", "b"]
+    assert table.loc["a", "b"] == f"{value:.3f}" + stars
+
+
+# ------------------------------------------------------ stats: describe
+
+
 def test_describe_reports_expected_keys(rng):
     from mcm_toolkit.stats import describe
 
     table = describe(rng.normal(size=(100, 3)))
     for key in ["mean", "std", "min", "max", "median"]:
         assert key in table.index
+
+
+def test_describe_rows_are_metrics_and_columns_are_variables():
+    """方向约定：行 = 指标，列 = 变量。多转置一次就反了。"""
+    from mcm_toolkit.stats import describe
+
+    df = pd.DataFrame({"a": [1.0, 2.0, 3.0], "b": [10.0, 20.0, 30.0]})
+    table = describe(df)
+
+    assert list(table.columns) == ["a", "b"]
+    assert table.loc["mean", "a"] == pytest.approx(2.0)
+    assert table.loc["max", "b"] == pytest.approx(30.0)
+    assert table.loc["median", "b"] == pytest.approx(20.0)
+
+
+def test_describe_missing_and_shape_rows_are_not_nan():
+    """曾经的静默 bug：转置后 `.loc[指标名] = <按变量索引的 Series>` 对不上列，
+    整行会被填成 NaN —— 不报错，但数据全丢。"""
+    from mcm_toolkit.stats import describe
+
+    df = pd.DataFrame({"a": [1.0, np.nan, 3.0, 4.0], "b": [1.0, 2.0, 3.0, 4.0]})
+    table = describe(df)
+
+    assert table.loc["missing", "a"] == pytest.approx(1.0)
+    assert table.loc["missing", "b"] == pytest.approx(0.0)
+    assert table.loc["missing_ratio", "a"] == pytest.approx(0.25)
+    assert table.loc["missing_ratio", "b"] == pytest.approx(0.0)
+    assert table.loc["skewness", "b"] == pytest.approx(0.0, abs=1e-12)
+    extra = table.loc[["missing", "missing_ratio", "skewness", "kurtosis"]]
+    assert not bool(extra.isna().all(axis=None))
+
+
+def test_describe_skips_non_numeric_columns():
+    from mcm_toolkit.stats import describe
+
+    df = pd.DataFrame({"a": [1.0, 2.0], "city": ["X", "Y"]})
+    table = describe(df)
+
+    assert list(table.columns) == ["a"]
+
+
+def test_describe_accepts_ndarray_list_and_series(rng):
+    """兄弟函数都收 ndarray / list，describe 没理由只收 DataFrame。"""
+    from mcm_toolkit.stats import describe
+
+    assert "mean" in describe(rng.normal(size=(50, 2))).index
+    assert "mean" in describe([[1.0, 2.0], [3.0, 4.0]]).index
+    assert "mean" in describe(pd.Series([1.0, 2.0, 3.0])).index
+
+
+def test_describe_weighted_rows_match_manual_formula():
+    from mcm_toolkit.stats import describe
+
+    df = pd.DataFrame({"a": [1.0, 2.0, 3.0]})
+    w = np.array([1.0, 1.0, 2.0])
+    table = describe(df, weights=w)
+
+    expect_mean = np.average(df["a"], weights=w)
+    expect_std = np.sqrt(np.average((df["a"] - expect_mean) ** 2, weights=w))
+    assert table.loc["weighted_mean", "a"] == pytest.approx(expect_mean)
+    assert table.loc["weighted_std", "a"] == pytest.approx(expect_std)
+
+
+@pytest.mark.parametrize(
+    ("weights", "exc"),
+    [
+        (np.ones(2), ValueError),
+        (np.zeros(3), ValueError),
+        (np.array([1.0, -1.0, 1.0]), ValueError),
+        (np.array([1.0, np.nan, 1.0]), ValueError),
+        ("abc", TypeError),
+    ],
+)
+def test_describe_rejects_bad_weights(weights, exc):
+    from mcm_toolkit.stats import describe
+
+    with pytest.raises(exc):
+        describe(pd.DataFrame({"a": [1.0, 2.0, 3.0]}), weights=weights)
+
+
+def test_describe_rejects_unsupported_type_and_all_text_frame():
+    from mcm_toolkit.stats import describe
+
+    with pytest.raises(TypeError):
+        describe({"a": [1.0]})
+    with pytest.raises(ValueError):
+        describe(pd.DataFrame({"city": ["X", "Y"]}))
+
+
+# ------------------------------------------------------ stats: zscore
+
+
+def test_zscore_matches_manual_formula():
+    from mcm_toolkit.stats import zscore
+
+    x = np.array([1.0, 2.0, 3.0, 4.0])
+    assert np.allclose(np.asarray(zscore(x)), (x - x.mean()) / x.std())
+
+
+def test_zscore_is_per_column_and_keeps_frame(rng):
+    from mcm_toolkit.stats import zscore
+
+    df = pd.DataFrame({"a": rng.normal(size=200), "b": rng.normal(5, 3, size=200)})
+    out = zscore(df)
+
+    assert isinstance(out, pd.DataFrame)
+    assert list(out.columns) == ["a", "b"]
+    assert np.allclose(np.asarray(out).mean(axis=0), 0.0, atol=1e-12)
+    assert np.allclose(np.asarray(out).std(axis=0), 1.0, atol=1e-12)
+
+
+def test_zscore_constant_column_stays_zero():
+    from mcm_toolkit.stats import zscore
+
+    assert np.allclose(np.asarray(zscore([2.0, 2.0, 2.0])), 0.0)
+
+
+def test_zscore_series_keeps_index_and_name(rng):
+    """Series 进 Series 出，索引和 name 都要带回来 —— 否则管道里 concat 会丢列名。"""
+    from mcm_toolkit.stats import zscore
+
+    s = pd.Series(rng.normal(size=50), index=[f"r{i}" for i in range(50)], name="price")
+    out = zscore(s)
+
+    assert isinstance(out, pd.Series)
+    assert out.name == "price"
+    assert list(out.index) == list(s.index)
+
+
+def test_zscore_rejects_bad_type_and_all_text_frame():
+    from mcm_toolkit.stats import zscore
+
+    with pytest.raises(TypeError):
+        zscore("abc")
+    with pytest.raises(ValueError):
+        zscore(pd.DataFrame({"city": ["X"]}))
+
+
+# ------------------------------------------- stats: coefficient_of_variation
+
+
+def test_coefficient_of_variation_matches_manual_formula():
+    from mcm_toolkit.stats import coefficient_of_variation
+
+    x = np.array([1.0, 2.0, 3.0, 4.0])
+    assert coefficient_of_variation(x) == pytest.approx(x.std() / x.mean())
+
+
+def test_coefficient_of_variation_accepts_single_column_frame():
+    from mcm_toolkit.stats import coefficient_of_variation
+
+    df = pd.DataFrame({"a": [1.0, 2.0, 3.0]})
+    single = coefficient_of_variation([1.0, 2.0, 3.0])
+    assert coefficient_of_variation(df) == pytest.approx(single)
+
+
+def test_coefficient_of_variation_uses_absolute_mean():
+    """均值为负时 CV 仍是**正数**：符号不该被读成"波动更小"。"""
+    from mcm_toolkit.stats import coefficient_of_variation
+
+    x = np.array([-1.0, -2.0, -3.0, -4.0])
+    assert coefficient_of_variation(x) == pytest.approx(x.std() / abs(x.mean()))
+    assert coefficient_of_variation(x) > 0
+
+
+def test_coefficient_of_variation_zero_mean_is_value_error():
+    """均值为 0 是**取值**问题不是类型问题：必须是 ValueError 而不是 TypeError。"""
+    from mcm_toolkit.stats import coefficient_of_variation
+
+    with pytest.raises(ValueError):
+        coefficient_of_variation([-1.0, 1.0])
+
+
+def test_coefficient_of_variation_rejects_empty_2d_and_bad_type():
+    from mcm_toolkit.stats import coefficient_of_variation
+
+    with pytest.raises(ValueError):
+        coefficient_of_variation([])
+    with pytest.raises(ValueError):
+        coefficient_of_variation([[1.0, 2.0], [3.0, 4.0]])
+    with pytest.raises(ValueError):
+        coefficient_of_variation(pd.DataFrame({"a": [1.0], "b": [2.0]}))
+    with pytest.raises(TypeError):
+        coefficient_of_variation(5.0)

tests/test_viz.py

@@ -1,6 +1,7 @@
 """viz 包测试。
 
 绘图测试不比对像素——只验证"能画出来、能存成文件、尺寸符合美赛要求"。
+未实现的函数按决策 26 **逐条** skip，不用模块级 `pytestmark`。
 """
 
 from __future__ import annotations
@@ -11,18 +12,30 @@ matplotlib.use("Agg")
 
 import pytest
 
-pytestmark = pytest.mark.skip(reason="未实现：见 docs/03-roadmap.md L0/L1")
+_NOT_IMPLEMENTED = "未实现：见 docs/03-roadmap.md L0/L1"
 
 
+@pytest.fixture
+def fig():
+    """最小 Figure；测试结束统一关闭，避免 matplotlib 的"图开太多"告警。"""
+    import matplotlib.pyplot as plt
+
+    figure, _ = plt.subplots(figsize=(2, 2))
+    yield figure
+    plt.close(figure)
+
+
+@pytest.mark.skip(reason=_NOT_IMPLEMENTED)
 @pytest.mark.parametrize("kind", ["line", "scatter", "hist", "box", "bar"])
 def test_plot_kinds_produce_figure(kind, rng):
     from mcm_toolkit.viz import plot
 
     x = rng.normal(size=100)
-    fig, ax = plot(x, x, kind=kind)
+    figure, ax = plot(x, x, kind=kind)
-    assert fig is not None and ax is not None
+    assert figure is not None and ax is not None
 
 
+@pytest.mark.skip(reason=_NOT_IMPLEMENTED)
 def test_mcm_style_sets_300dpi():
     from mcm_toolkit.viz import mcm_style
 
@@ -31,15 +44,93 @@ def test_mcm_style_sets_300dpi():
     assert matplotlib.rcParams["font.size"] >= 8.0
 
 
-def test_save_figure_writes_png_and_pdf(tmp_path, rng):
+def test_save_figure_writes_png_and_pdf(fig, tmp_path):
-    from mcm_toolkit.viz import plot, save_figure
+    from mcm_toolkit.viz import save_figure
 
-    fig, _ = plot(rng.normal(size=50), rng.normal(size=50), kind="scatter")
     paths = save_figure(fig, tmp_path / "fig1", formats=("png", "pdf"))
-    assert {p.suffix for p in paths} == {".png", ".pdf"}
+    assert [p.suffix for p in paths] == [".png", ".pdf"]
     assert all(p.exists() and p.stat().st_size > 0 for p in paths)
 
 
+def test_save_figure_strips_an_image_suffix_from_path(fig, tmp_path):
+    """`fig1.png` 当主干用：不能写出 `fig1.png.png`。"""
+    from mcm_toolkit.viz import save_figure
+
+    paths = save_figure(fig, tmp_path / "fig1.png", formats=("pdf",))
+    assert paths == [tmp_path / "fig1.pdf"]
+    assert paths[0].exists()
+
+
+def test_save_figure_creates_parent_directories(fig, tmp_path):
+    from mcm_toolkit.viz import save_figure
+
+    target = tmp_path / "nested" / "deeper" / "fig1"
+    paths = save_figure(fig, target, formats=("png",))
+    assert paths[0] == tmp_path / "nested" / "deeper" / "fig1.png"
+    assert paths[0].exists()
+
+
+def test_save_figure_normalizes_format_case_and_keeps_order(fig, tmp_path):
+    from mcm_toolkit.viz import save_figure
+
+    paths = save_figure(fig, tmp_path / "fig1", formats=("PDF", "png"))
+    assert [p.suffix for p in paths] == [".pdf", ".png"]
+    assert all(p.exists() for p in paths)
+
+
+def test_save_figure_rejects_a_single_string_as_formats(fig, tmp_path):
+    from mcm_toolkit.viz import save_figure
+
+    with pytest.raises(TypeError, match="不要传单个字符串"):
+        save_figure(fig, tmp_path / "fig1", formats="png")  # type: ignore[arg-type]
+
+
+def test_save_figure_rejects_bad_formats(fig, tmp_path):
+    from mcm_toolkit.viz import save_figure
+
+    with pytest.raises(ValueError, match="不能为空"):
+        save_figure(fig, tmp_path / "fig1", formats=())
+    with pytest.raises(ValueError, match="不支持"):
+        save_figure(fig, tmp_path / "fig1", formats=("gif",))
+    with pytest.raises(ValueError, match="重复"):
+        save_figure(fig, tmp_path / "fig1", formats=("png", "PNG"))
+
+
+def test_save_figure_validates_before_creating_directories(fig, tmp_path):
+    """格式错时不能先建目录留下副作用。"""
+    from mcm_toolkit.viz import save_figure
+
+    nested = tmp_path / "should_not_exist" / "fig1"
+    with pytest.raises(ValueError, match="不支持"):
+        save_figure(fig, nested, formats=("gif",))
+    assert not nested.parent.exists()
+
+
+def test_save_figure_rejects_bad_render_options(fig, tmp_path):
+    from mcm_toolkit.viz import save_figure
+
+    with pytest.raises(TypeError, match="dpi"):
+        save_figure(fig, tmp_path / "fig1", dpi=300.0)  # type: ignore[arg-type]
+    with pytest.raises(TypeError, match="dpi"):
+        save_figure(fig, tmp_path / "fig1", dpi=True)
+    with pytest.raises(ValueError, match="dpi"):
+        save_figure(fig, tmp_path / "fig1", dpi=0)
+    with pytest.raises(TypeError, match="bbox_inches"):
+        save_figure(fig, tmp_path / "fig1", bbox_inches=3)  # type: ignore[arg-type]
+    with pytest.raises(ValueError, match="bbox_inches"):
+        save_figure(fig, tmp_path / "fig1", bbox_inches="")
+    with pytest.raises(TypeError, match="transparent"):
+        save_figure(fig, tmp_path / "fig1", transparent="yes")  # type: ignore[arg-type]
+
+
+def test_save_figure_rejects_non_figure(tmp_path):
+    from mcm_toolkit.viz import save_figure
+
+    with pytest.raises(TypeError, match="Figure"):
+        save_figure(object(), tmp_path / "fig1")  # type: ignore[arg-type]
+
+
+@pytest.mark.skip(reason=_NOT_IMPLEMENTED)
 def test_save_table_writes_latex_with_caption(tmp_path):
     import pandas as pd