guzhujushi/MCM-ICM_Toolkit
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
27 Commits 1 Branch 0 Tags
a1cc26e0424cbea4340dfa19f1d9875e6b454c4f
Commit Graph
14 Commits
Author SHA1 Message Date
guzhujushi a1cc26e042 feat(stats): bootstrap_ci 落地（L0 10/12，S 档）+ 卡片；修掉 rng 绕过 get_rng 与 lambda 名字死分支 
## 审查结论
算法移植是对的：大样本正态下百分位区间半宽与解析 `2 × 1.96 × se` 差 < 2%，
按块重采样（batch_size=1000）也照 docstring 的 Notes 做了。以下是要改的部分。

## Fixed
- `random_state=None` 时另开 `np.random.default_rng()`,**绕过了 `core.get_rng`** ——
  与决策 24 冲突：`set_seed` 对它无效，同一段脚本重跑区间就变。改成无条件 `get_rng(random_state)`（决策 46）。
- `metrics["statistic_name"]` 用 `hasattr(statistic, "__name__")` 判不出 lambda：
  lambda 的 `__name__` 恒为 `"<lambda>"`，于是 `else "custom"` 是**死代码**，
  实测自定义统计量拿到的是 `"<lambda>"`。改成 `getattr(f, "__name__", None)` + 判 `"<lambda>"`（易错点 17）。
- docstring 补齐 `Parameters` / `Returns` / `Raises`（§4.7），并如实写明 `method="bca"` **尚未实现**
  （此前 docstring 承诺支持、实现却抛 `NotImplementedError`）。
- ruff 两条：I001（导入块拆成三行且用了绝对导入）、F541（`f"暂不支持bca"` 无占位符）。

## Tests
- **摘掉 3 条 `skip`**：等 `bootstrap_ci` 的那 3 条一直挂着，实现写完照样全绿 —— 易错点 9 复发，
  已在 `personal-pitfalls.md` 把该条 `复发` 记到 1 并注明本次经过。
- 新增 6 条：`estimate` 等于原样本统计量、`confidence` 单调性、五种容器一致、
  自定义 lambda 走回退分支、**不给种子时跟随 `set_seed`**（钉住上面那个 rng 修复）、非法/未实现 method。
- 写测试时踩到一个真性质：极差的重采样值**永远 ≤ 原样本极差**，`high` 会正好等于 `estimate`，
  断言不能写 `estimate < high`。这条已写进卡片 §5。
- 全量 **177 条：143 passed / 34 skipped / 0 xfail**；ruff 0，pyright 0；`examples/01` 跑通。

## Docs
- `docs/algorithms/bootstrap_ci.md`：**第 2 张 S 档卡片**（模板九节 + §10 待拍板）。
  `docs/algorithms/README.md` 进度表打勾。
- `docs/dev/personal-pitfalls.md`：新增第 17 条（`hasattr(f, "__name__")` 挡不住 lambda，`else` 分支即死代码），
  索引补到 17；第 9 条记一次复发。
- `STATUS.md`：E 节记 `bootstrap_ci`（L0 10/12 → 剩余 `monte_carlo` `save_figure`），决策 46，
  「下一步」第 1 条改写、新增第 8 条列 5 个待拍板口径。

## 待用户拍板（Codex 一律未动，按决策 39）
- `x` 里的 NaN 静默传进统计量 → `nan` 区间（`confidence_interval` / `t_test` 都是先丢 NaN 的，口径不齐）
- `n_resamples <= 0` 现在抛 `IndexError: index -1 is out of bounds`（应在入口给可读 ValueError）
- `confidence` 越界交给 numpy 抛 `Percentiles must be in the range [0, 100]`
- `method="bca"`：补实现（≈25 行，S 档）还是从 docstring 删掉
- `bootstrap_statistic` 仍是 `NotImplementedError`，而 `bootstrap_ci` 把那段重采样循环内联了 ——
  建议抽出去让 `bootstrap_ci` 调它（易错点 16 的变体）
 2026-10-03 19:59:38 +08:00
guzhujushi b70a96dd0c refactor(core): 统一入口 as_array —— 六处手抄的入参处理收成一处（决策 44/45） 
## 新增
- `core.validate.as_array(x, *, numeric_only=True, dtype=float, ndim=None) -> (arr, kind)`：
  一次做完"类型白名单 + 转 ndarray + 报告原来是什么容器"。`kind` 是 `"frame"` / `"series"` / `"array"`。
- **还原不代做**（用户拍的板）：`describe` / `correlation_*` / `confidence_interval` / `t_test` 的
  输出天生与输入不同形，统一还原只会重演易错点 14；所以只报告 `kind`，调用方自己手写三行。
- `core/__init__.py` 导出 `as_array`；`check_array`（L1 未实现）的 docstring 注明实现时复用它。
- 入口三条硬规矩：**默认绝不摊平**（要摊平显式 `ndim=1`）；**不删缺失值**；
  `numeric_only` 按"输出是否与输入同形"选，不按喜好选。

## 去重
- `normalize` / `standardize` / `log_transform` / `zscore` / `confidence_interval` / `t_test`
  六处手抄的 `isinstance(x, pd.DataFrame)` / `select_dtypes` / `np.asarray` 全部删掉，各剩 1 行入口。
- `data/transform.py` 的 `_NUMERIC_TYPES` 白名单连同 3 份副本一起删除 ——
  这类判断原来散在 **5 个文件 31 处**。
- `transform` 的三个函数走 `numeric_only=False`：它们的输出必须与输入同形，跳过非数值列会少列。

## 修掉
- `zscore` / `normalize` / `standardize` / `log_transform` 的 Series 分支**补回 `name`** ——
  此前 `pd.Series(result, index=...)` 会把 `name` 丢掉，管道里 `concat` 会变成无名列。
- "容器对、内容转不成 float"的错误类型，由 numpy 的 `ValueError` 统一成 `TypeError`（决策 45，**待确认**）。

## 测试与文档
- `tests/test_core.py` 新增 `TestAsArray` 8 条：五种容器的 kind、默认只取数值列、
  `numeric_only=False` 遇文本报错、默认不摊平、`ndim=2` 只校验不重塑、白名单外一律 TypeError、
  **保留 NaN**、`dtype=None` 保持原 dtype；`tests/test_stats.py` 新增 1 条（Series 保住 index/name）。
- 全量 **171 条：134 passed / 37 skipped / 0 xfail**；ruff 0，pyright 0；`examples/01` 跑通（exit 0）。
- `docs/02-architecture.md` 新增 §4.8「入口只有一个：`core.validate.as_array`」，目录树补 `as_array`；
  `docs/03-roadmap.md` 的 L1 表下补说明；`docs/dev/personal-pitfalls.md` 新增第 16 条并把索引补到 16。
- `STATUS.md`：决策 44 / 45，E 节记 as_array，「下一步」第 7 条列 3 个待拍板口径。

## 待用户拍板（Codex 一律未代选）
- `int` / `float` 标量是否继续留在白名单（现在会产出 0 维数组，`axis=0` 的算法照样炸）。
- "内容转不成 float" 该用 `TypeError`（现状）还是 `ValueError`。
- 要不要让 `as_array` 顺带返回选中的列（改三元组），省掉 `frame` 分支重写 `select_dtypes`。
 2026-10-03 19:17:22 +08:00
guzhujushi f95fbd2726 fix(stats): t_test/confidence_interval 收口 —— 307/308 是存根误报，CI 的夹取才是真 bug（L1 提前 2 个） 
## 用户问的「t_test 307 / 308 两行报错」
- 那两行是 `float(res.statistic)` / `float(res.pvalue)`，报错来自 scipy 的 `TtestResult`：
  它和 `PearsonRResult` 一样是 `_make_tuple_bunch` **运行时**拼出来的类，存根里没有这两个字段。
- 探针实测 `TtestResult(statistic=3.873, pvalue=0.0305)`，运行时取值完全正常 —— **不是真 bug**。
- 按决策 40 的路子补 `_statistic(result: Any) -> float`（与 `_pvalue` 成对），一行 `# type: ignore` 都没挂。
  详情见 `docs/04-environment.md` 坑 10（已扩写为 pvalue / statistic 两条）。

## 顺手查出来的真 bug：`confidence_interval`
- 原码 `return (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`。
- 入参放宽到 `list` / `tuple` / `ndarray` / `Series` / `DataFrame`：
  docstring 的 Examples 传 list、L0 用例传 ndarray，原来**两条都直接 `TypeError`**。

## t_test
- docstring 补齐 `Parameters` / `Returns` / `Raises` / `Notes`（§4.7）；
  `_clean_data` 改用 `isinstance(data, pd.DataFrame)` 收窄（坑 8 的 `cast`）；
  `alpha` 开区间校验；`df` 按 Welch–Satterthwaite / pooled / paired 分别给。
- **4 个口径未代选**（决策 39），已记进 `STATUS.md`「下一步」第 6 条待用户拍板：
  单样本结论文案、`paired` 的 NaN 对齐、`value` 被静默忽略、`DataFrame` 摊平多列。

## 测试与文档
- `tests/test_stats.py` +10 条（36 → 46），含把原先挂 skip 的
  `test_confidence_interval_matches_scipy` 转正；对照一律用解析式（z 公式 / Welch df / t 公式）。
- 全量：**125 passed / 37 skipped / 0 xfail**，ruff 0，pyright 0。
- 个人易错点新增第 15 条，并把**停在 6 号**的索引表补齐到 15（只补索引，正文未动）。
- `docs/04-environment.md` 顺手修掉残留的 `[FENCE]` 代码围栏占位符与一处重复的 `---`。
- `STATUS.md`：L0 记 9/12；校正测试数为 162 条；新增决策 42 / 43。
 2026-10-03 18:40:41 +08:00
guzhujushi 95f5266563 feat(stats): correlation_matrix 按方案 A 拆成三个函数，收口返回契约（L0 9/12） 
用户 2026-10-03 拍板方案 A（见决策 41），由 Codex 落地。

拆成三个函数:
- correlation_matrix  -> 数值系数矩阵（对角线 1.0）
- correlation_pvalues -> 数值 p 值矩阵（对角线 NaN）
- correlation_table   -> 星标字符串表（对角线 1.000 不带星）
三者共用 _check_corr_args 守卫与成对删缺失口径；correlation_table 在最外层调另外两个。
理由: 字符串表做不了后续计算（挑高相关对、喂聚类/PCA、画热力图），反过来随时能格式化；
      一旦返回字符串，数值信息不可逆地丢失。

顺带修掉两处:
- 对角线 p 值由 0.0 改成 NaN —— 写 0 会被下游读成"极显著"，而"自己和自己"没有 p 值
- p 值与 r 现在用同一批观测: 先成对 dropna() 再算，并同样尊重 min_periods。
  此前 corr 是成对删缺失、pearsonr 不删，两者样本量不同，r 与 p 对不上
- p 值只算上三角再镜像（成对变量的 p 天然对称），省一半重复计算

tests: test_correlation_matrix_diagonal_is_one 摘掉 xfail 转正；新增 8 条
  （数值性+对称性、非数值列跳过、p 值对照解析式 t = r*sqrt((n-2)/(1-r^2))、
   对角线 NaN、成对删缺失口径、min_periods、对角线无星标、表格与数值输出一致）。
  测试 105 passed / 38 skipped / 1 xfail -> 114 passed / 38 skipped / 0 xfail。

验证: pytest 114 passed / 38 skipped；ruff All checks passed；pyright 0 errors。

docs: STATUS.md（L0 9/12 + 决策 41 + 下一步）；CHANGELOG；
      personal-pitfalls 追加第 14 条（把"能看的表"和"能算的表"塞进同一个返回值）；
      roadmap 记录 correlation_matrix 的两个伴随函数
 2026-10-03 14:53:05 +08:00
guzhujushi 3432bf3e50 fix(stats): correlation_matrix 修硬 bug，两处 pyright 报错按坑 8/10 正经修（无 ignore） 
用户报的是"63 行 p 值赋值报错"。查下来：63 行运行完全正常（p 是 np.float64），
pyright 那条是 scipy 存根的缺陷。但顺着看发现了真正跑不起来的第 41 行。

correlation_matrix:
- 硬 bug: `if numeric_cols == 0` 拿 Index 和标量比 -> 得到布尔数组。
  0 列时静默不报错、1 列时碰巧能跑、>=2 列直接 ValueError 崩（而 >=2 列正是常见情况）。
  改成 len(numeric_cols) == 0，并加回归用例
- pyright 两处报错都不是运行时问题，且一处 # type: ignore 都没挂:
  - data[numeric_cols] 是坑 8 的 DataFrame | Series 重载 -> cast 收窄
  - `_, p = stats.pearsonr(...)` 解包退化成 object（scipy 的返回值是 _make_tuple_bunch
    运行时拼的类，存根里没有 pvalue）-> 新增 _pvalue(result: Any) -> float 小助手统一取，
    后面 t_test / anova / chi_square_test 可复用
- method 校验提到最前；add_stars 的 elif 链改 if；清掉 3 条 F541 与 1 条 I001，ruff 归零
- 顺带记录两处待定：对角线被标了 ***；含 NaN 时 corr 成对删失而 pearsonr 不删，r 与 p 对不上

tests:
- test_correlation_matrix_diagonal_is_one 由 skip 改成 xfail(strict=False)（决策 30）:
  契约要数值矩阵、实现返回带星标字符串表，口径待拍板
- 新增 2 条：多列数值表能跑通、非法输入报错

验证: pytest 105 passed / 38 skipped / 1 xfail；ruff All checks passed；pyright 0 errors。

docs: STATUS.md（correlation_matrix 进行中 + 决策 40 + 下一步 A/B/C 选项）；CHANGELOG；
      personal-pitfalls 追加第 13 条（Index == 标量 得到布尔数组）；
      docs/04-environment.md 追加坑 10（scipy 检验结果的存根缺陷）
 2026-10-03 14:45:10 +08:00
guzhujushi cfc1be31ca fix(stats): CV 改用 |mean|，并记录决策 37/38/39 与经验 12 
coefficient_of_variation:
- 分母由 mean 改为 |mean|（用户本人改），均值为负时 CV 不再是负值
- docstring 摘要 / Returns / Notes 同步，加一条测试钉住"均值为负时 CV 仍为正"

口径拍板（2026-10-03）:
- 决策 37: 非数值列的处置按输出契约分，不按包分 —— describe/zscore 丢掉（吐数值结果表），
  detect_outliers 保留列、掩码恒 False（吐与原表同形的掩码），刻意不统一
- 决策 38: CV 用 sigma/|mean|
- 决策 39: 工作约定 —— 语义/非法输入口径由用户拍板，Codex 只列选项不代选；
  ruff / STATUS.md / CHANGELOG.md / tests / docstring 这类与算法无关的工程事务 Codex 顺手补

经验（docs/dev/personal-pitfalls.md，只追加）:
- 第 12 条: 三个并列的 if 让后面的静默覆盖前面的（transform.normalize 三种 method 实际只走 max）
  第 11 条（上一轮）是 descriptive 的 .loc 对齐失败静默填 NaN —— 两条的共同点是"不抛异常"

验证: pytest 103 passed / 39 skipped；ruff All checks passed；pyright 0 errors。

docs: STATUS.md 决策 37/38/39 + 下一步；CHANGELOG 记录
 2026-10-03 13:26:13 +08:00
guzhujushi e9624cb3a7 feat(stats): describe 落地，修掉一个静默填 NaN 的 bug（L0 8/12） 
src/stats/descriptive.py 由用户本人实现，这里做审查 + 代修。

describe:
- 真 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

zscore: 修 RET505；docstring 补齐；DataFrame 取列处按坑 8 用 cast 收窄
coefficient_of_variation: 均值为 0 改抛 ValueError（取值问题不是类型问题）；
  空数组提前报错（原先静默 nan + RuntimeWarning）；错别字与文案修正

tests: 去掉 test_stats.py 的模块级 pytestmark —— 它把 6 条测试全部跳过（含已实现的
  describe），正是决策 26 要禁的写法。改为逐条 skip 未实现的 5 条，并新增 20 条用例。

验证：pytest 102 passed / 39 skipped（原 82/40）；ruff All checks passed；pyright 0 errors。
examples/01_clean_and_describe.py 填掉 TODO(L0)，实测 exit 0。

docs: STATUS.md L0 8/12 + 决策 35/36 + 三处待拍板口径；CHANGELOG 记录；
      personal-pitfalls 追加第 11 条（pandas 对不齐就静默填 NaN）
 2026-10-03 13:17:58 +08:00
guzhujushi 4552aee41c fix(data): 修掉 transform.py 的 3 处真 bug，并收口 4 个口径 
不是编辑器误报：pyright CLI 与 pytest 都能复现（修前 7 failed / 75 passed），
所以一行 # type: ignore 都没加。

- 输入白名单漏了 pd.DataFrame -> standardize/log_transform 直接 TypeError，
  函数体里的 is_df 分支全是死代码；统一成模块级 _NUMERIC_TYPES 并前置到 np.asarray 之前
- normalize 三个 method 分支互相覆盖（minmax/vector 的结果被末尾无条件的 x/max 冲掉，
  实际三种 method 都只走 max），改成 if/elif/else
- one_hot_encode 按 data.columns 重包一层 DataFrame -> 哑变量列名对不上，编码列整列丢失，
  改为直接返回 get_dummies 的结果
- log_transform 的 offset 守卫写反（offset > 0 就抛错，恰好拒掉唯一合法用例），
  改为校验定义域前提 min(x) + offset > 0；offset=0 对全正数据合法
- 四个函数 docstring 按 docs/02-architecture.md 4.7 补齐 Parameters/Returns/Raises
- ruff 4 条 RET505 清掉；pyright 2 errors -> 0；测试 82 passed / 40 skipped

docs: STATUS.md L0 进度 7/12 + 决策 35；CHANGELOG 记录本轮回归与修复；
      personal-pitfalls 追加第 10 条（把真报错当成编辑器误报）
 2026-10-02 21:48:27 +08:00
guzhujushi 6eab0babde feat(data): transform.py 四个函数落地；补 18 条测试、清 5 条 ruff 
实现（用户本人写）：
- normalize（minmax / vector / max，三种都按列）+ feature_range 校验 + 常量列不出 nan
- standardize（按列，ddof 真的传下去）+ 类型守卫
- log_transform（offset=None 时自动取 1 - min(x)，保证 x + offset >= 1）+ 类型守卫
- one_hot_encode（自动识别对象列 / 指定列 / drop_first）
- data/ 下的 L0 至此结清（L0 7/12）

Codex 的轻度修复（不改接口与语义）：
- 清掉 5 条 ruff：RET503 / F541 / RET504 / RET505 / SIM108
- supported_method 与 feature_range 的校验提到 np.asarray 之前（守卫集中开头）
- 修掉说反的报错文案（条件是要求下界 < 上界，原文写"上界必须小于下界"）
- one_hot_encode 自动识别时显式加上 str / string：只写 object 在 pandas 3 上是弃用路径，
  每次调用发 Pandas4Warning，未来会变成"一列都选不中"的静默错误（详见坑 9）

测试：
- 新写 18 条（transform 段），其中两条是把原先挂着的 skip 转为实跑 ——
  normalize / standardize 的实现此前一条测试都没跑到（详见个人易错点 9）
- 82 passed / 40 skipped / 0 xfailed；ruff 0；pyright 0

文档：
- STATUS.md：E 节 + 验证表（122 条用例分布）+ 下一步重写（transform 待定的 4 个口径）+ 决策 34
- docs/04-environment.md：新增坑 9（pandas 3 的 str dtype 与 select_dtypes 弃用路径，含实测对照表）
- docs/dev/personal-pitfalls.md：只追加第 9 条（实现写完但测试还挂 skip，绿灯是假的）
- CHANGELOG.md：本轮变更 + 记录 transform 待定的 4 个口径
 2026-10-02 20:43:03 +08:00
guzhujushi b6dc4bc5a6 feat(data): detect_outliers 收尾（文本列恒 False）+ 补测试与文档 
实现（用户本人写 + Codex 轻度收尾）：
- 统计量（quantile / mean / std）与掩码写入都收窄到数值列，含文本列的赛题表不再崩
- 非数值列在掩码里恒 False（用户定的语义），docstring Notes 补上这条
- 删掉死代码 data=data.copy()：下面的 to_frame()/pd.DataFrame() 本就返回新对象，
  函数全程只读 data，白复制一份；且它排在类型分派之前，会把错误入参的报错
  从 ValueError 变成 AttributeError
- 删掉那行死代码后 pyright 反而暴露 1 个真错：df[Index] 被类型存根当成 Series，
  .std() 于是被判成标量、std.replace(...) 非法。在取列子表处 cast 成 DataFrame
  按运行时真值收窄（详见 docs/04-environment.md 坑 8）

测试：
- 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；ruff 0；pyright 0
- 仅剩 1 条 xfail：impute_missing 的 mode 分支就地改调用方的表（要选语义，留给用户）

文档：
- STATUS.md：L0 5/12、验证结果表、下一步重写、新增决策 32（非数值列恒 False）
- docs/04-environment.md：新增坑 8（pandas 存根让 df[Index] 退化成 Series，及三种无效修法）
- docs/dev/personal-pitfalls.md：只追加第 8 条（限制掩码 ≠ 限制统计量）
- CHANGELOG.md：本轮变更
 2026-10-02 15:41:08 +08:00
guzhujushi 319b16b17c fix(data): clean.py 轻度修复 + 摘掉 5 条已修好的 xfail 
Codex 直接改的（格式 / 死代码 / 纯 bug，不动接口与语义）：
- winsorize(Series) 直接崩：select_dtypes 在 Series 上不存在，Series 分支提到最前并加数值 dtype 守卫
- winsorize 的分位数改为只在数值列上算，含文本列的赛题表不再崩（与已有 numeric_cols 判断对齐）
- 删掉 detect_outliers 里已成空操作的 df = pd.DataFrame(data)，去掉 df 别名
- clean_missing 的嵌套 if 合并（ruff SIM102），清掉 W293 行尾空白与函数内连续空行

测试：
- 5 条 xfail 经 XPASS 信号确认已修好，摘掉 mark 转正式用例
  （detect_outliers 4 条 + winsorize 混合类型 1 条）
- 53 passed / 7 xfailed  ->  58 passed / 2 xfailed
- 剩 2 条 xfail 保留，且不是漏改而是设计没定：
  detect_outliers 遇文本列返回什么、impute_missing 的 mode 分支要不要就地改调用方的表
- ruff: 1 error -> All checks passed；pyright: 0 errors 不变

文档：
- STATUS.md：L0 进度 4/12、验证结果表、下一步重写、新增决策 31
  （Codex 可直接改 src 的范围：纯 bug / 格式 / 死代码；要选语义的留给用户）
- CHANGELOG.md：本轮变更，并修掉 [Unreleased] 里被重复追加撑坏的一句
- docs/dev/personal-pitfalls.md：只追加第 7 条（守卫子句要排在类型分派之后）
 2026-10-02 15:18:15 +08:00
guzhujushi 6758e81c9d fix(data): 校验早于副作用，补空行；经验写入 pitfalls 
save_table 的两处收尾（用户授权代改）：

- 后缀校验原先藏在 if/else 分支的 else 里，排在 path.parent.mkdir(...) 之后，
  传 sub/x.txt 会先把 sub\ 建出来再抛 ValueError。改成守卫子句，集中在 mkdir 之前，
  校验段结束后才产生副作用；此时 else 分支自然消失，用回 if/else 两路分派
- __all__ 与下一个 def 之间补回第二个空行（PEP 8 / E302）

测试：
- 新增 test_save_table_validates_before_touching_disk，
  断言参数非法时 tmp_path 下一个条目都不留（ValueError 与 TypeError 两条路径）
- 40 passed / 44 skipped，两套环境一致；ruff All checks passed

文档：
- docs/dev/personal-pitfalls.md 追加条目 5（参数校验排在副作用之后）
  与条目 6（把 lint 的"没报错"当成"没问题"），索引表同步加行
- STATUS：io.py 收尾，L0 第 3 项完成；测试计数 40
- CHANGELOG：Fixed 段补两条
 2026-10-01 23:26:47 +08:00
guzhujushi 49fd84a2df docs: L0 进度 3/12，记录 zstandard 残骸坑与决策 26/27 
- STATUS.md：本次任务拆成「第一阶段已完成 / 第二阶段进行中」；
  L0 3/12；测试计数改为 39 passed / 44 skipped；
  下一步里写明 io.py 待修的两处（mkdir 早于校验、缺 Raises）
- docs/04-environment.md 坑 6：conda 升级留下的 *.conda_trash 残骸目录会被
  Python 当成 namespace package 导入成功（__file__ 为 None），
  pandas 3.0 因此抛 ImportError: Can't determine version for zstandard
  直接打断 pd.read_csv；含排查方法与「改名禁用」的修法
- docs/dev/personal-pitfalls.md：条目 3（注解与 docstring 打架）复发 +1
- 决策 26：未实现的算法逐条 skip，禁用模块级 pytestmark
- 决策 27：zstandard 残骸改名禁用，不删不重装
- CHANGELOG：补 load_table/save_table 与 Fixed 段
 2026-10-01 23:11:48 +08:00
guzhujushi c93810ffb1 fix(core): 补齐 get_rng 类型校验，set_seed 覆盖 numpy 旧全局 
get_rng 的"共享单例生成器"设计由用户本人提出，本提交只在其上修 bug。

- random_state 判断从 isinstance(x, int) 放宽到 (int, np.integer)：
  np.int64 不是 int 的子类，之前会静默退回全局流、种子被无声忽略
- 非预期类型改成抛 TypeError（含 bool / float / str / list），不再静默降级
- get_rng 签名补上 np.integer 与 Generator，与 docstring 的承诺一致
- set_seed 同时调用 np.random.seed：sklearn / statsmodels 走的是 numpy
  旧全局状态，不覆盖它们"提交能重跑"就有洞（带 noqa: NPY002 与理由）
- 测试：TestRandom 由 4 条增到 7 条（np.integer、非法类型、共享生成器推进）
- 新增 docs/dev/personal-pitfalls.md：个人易错点清单，只追加、不通读，
  首批记录本轮 4 个点；docs/README.md 补上 05 与该文件的索引
- STATUS.md：L0 进度说明更新，决策 24 改写（共享单例）、新增决策 25
  （src/ 实现默认由用户本人写）
 2026-10-01 19:38:59 +08:00