MCM-ICM_Toolkit/STATUS.md

# STATUS — 当前进度

> 更新日期：2026-10-01

## 本次任务

**第一阶段（已完成）**：审查并精简 ChatGPT 的建库建议 → 生成骨架文件 →
配置 conda 与 venv 环境 → 初始化 git 仓库 → 接入 Gitea 远端。
两套环境均已建成并通过验证，仓库已推送到 `code.guzhujushi.cn`。

**第二阶段（进行中）**：按 `docs/03-roadmap.md` 的 L0 → L1 顺序**逐个实现函数**，
用户本人写 `src/`、Codex 负责审查 + `tests/`（决策 25）。
当前 3/12：`Result`、`get_rng`/`set_seed`、`load_table`/`save_table`。

## 任务清单

### ✅ 已完成

**A. 建议审查与精简**
- [x] 通读 `chatGPT_Suggestion.md`（33 节，约 2.4 万字），输出 `docs/01-suggestion-review.md`
  - 总裁决：**方向对，量级错**
  - 14 个包 → **7 个**；约 250 个函数 → **约 40 个**；5 个 Result 类 → **1 个**
  - 单函数文档要求 10 项 → **2 档**（只有约 15 个招牌算法写完整卡片）
  - 逐项给出"砍什么 / 为什么 / 替代什么"，并补上原文缺失的六件事
    （论文产出链路、指标方向与量纲、时间预算、可复现性、测试测什么、离线约束）

**B. 骨架文件生成**（76 个文件，约 6800 行）
- [x] `docs/02-architecture.md` 架构、`docs/03-roadmap.md` 路线图与**永久不做清单**
- [x] `docs/04-environment.md` 环境文档、`docs/dev/function-card-template.md` 卡片模板
- [x] `src/mcm_toolkit/` 7 个包 23 个模块（**只有签名 + docstring + `NotImplementedError`**）
- [x] `tests/` 9 个文件、`examples/` 4 个、`problems/` `notebooks/` `figures/` `tables/`
- [x] `pyproject.toml`（核心依赖 4 个 + 6 组 extras）、`environment.yml`
- [x] `.gitignore` `.gitattributes` `.editorconfig` `LICENSE` `CHANGELOG.md` `README.md`
- [x] 脚本 `scripts/setup-venv.ps1` `setup-conda.ps1` `doctor.ps1`

**C. 环境配置**
- [x] **venv 已建好**：`.venv`（10.5 MB，Anaconda base + `--system-site-packages`）
      + `pip install -e . --no-deps --no-build-isolation`；
      可直接导入 numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6 / matplotlib 3.11.2 /
      sklearn 1.9.1 / statsmodels 0.15.0 / networkx 3.6.1 / sympy 1.14.0
      （版本随 base 走，base 升级后自动同步）
- [x] **conda 环境已建好**：`D:\anaconda\envs\mcm-toolkit`（1.55 GB，Python 3.13.15）
      - 科学栈：numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6 / matplotlib 3.11.2 /
        sklearn 1.9.1 / statsmodels 0.15.0 / networkx 3.6.1 / sympy 1.14.0（MKL 后端）
      - 已补装 pip-only 依赖：SALib、pymoo 0.6.2、pyright 1.1.414
      - 已在本项目中可编辑安装
      - 实测耗时 868 秒，下载约 3 GB
- [x] **Anaconda base 已升级** 2025.12 → **2026.07**（365 个包，下载 638 MB，耗时 1033 秒）
      - conda 自身 25.11.1 → **26.7.3**（实测复核）
      - 并把项目环境 numpy 对齐到 base 的 2.4.6，**两套环境数值栈现已完全一致**（MKL 后端）
      - 升级前已用 `conda list -n base --revisions` 留了回滚点
- [x] 环境脚本按实测结果重写：`setup-conda.ps1` 默认改为**精准包列表**
      （`--clone base` 实测会走完整下载安装，不再是"离线快捷方式"）

**D. Git 仓库**
- [x] `git init -b main`，`core.autocrlf=false`，首次提交
      `5319589`（76 文件 / 6812 行），工作区干净
- [x] `git ls-files --eol` 复核：**全部 LF**，`.gitattributes` 生效
- [x] 仓库由**本人账户 guzhu** 创建（见决策 17）
- [x] **远端 Gitea 已接通并推送**：`origin` = `git@code.guzhujushi.cn:guzhujushi/MCM-ICM_Toolkit.git`，
      `main` 跟踪 `origin/main`，远端 HEAD = `96080b9`，76 个文件已在服务器上（见决策 19/20）
- [x] 推送通道：公网 22 被防火墙过滤 → 改用 Tailscale（`100.115.86.48:22`），
      `~/.ssh/config` 加了一条域名别名，remote 里仍写域名

**E. L0 实现进度（4/12）**
- [x] `core/result.py` 的 `Result`
      - `__repr__`：单行紧凑；`data` 只给类型与规模，**绝不**整数组打印
        （十万级数组的 repr 实测仍 < 200 字符）；`success` 恒在
      - `summary()`：Markdown 表格，可直接贴进论文；
        行序 `success` → `params.*` → `metrics.*` → `extras.*`；
        float 走 `.6g`，`|` 转义，`message` 以引用行附在表后；幂等无副作用
      - 测试：`tests/test_core.py` 去掉 skip + 新增 3 条
        （默认值/失败路径/大数组、Markdown 结构、可重复调用）
- [x] `core/random.py` 的 `get_rng` / `set_seed`（**设计由用户本人写**，Codex 补齐类型校验）
      - 无参 `get_rng()` 复用**同一个模块级生成器**且会推进：既保证重跑一致，
        又避免两个都省略 `random_state` 的函数抽到同一串数（原决策 24 的取舍已消掉）
      - `get_rng` 收 `int` / `np.integer` / `Generator` / `None`，其余类型**抛 `TypeError`**：
        `np.int64` 不是 `int` 的子类，曾因此静默退回全局流
      - `set_seed` 同时调 `np.random.seed`，覆盖 sklearn / statsmodels 走的 numpy 旧全局
        （全项目**唯一**碰旧接口的地方，带 `# noqa: NPY002` 与理由）
      - 测试：`TestRandom` 共 7 条（可复现、透传、无参跟随、旧全局、np.integer、非法类型、共享推进）
- [x] `data/io.py` 的 `load_table`（+ `save_table`，原属 L1，顺手落地）
      - 实现由**用户本人**写（决策 25），Codex 只做审查 + 补测试
      - `.csv` / `.xlsx` / `.xls` 按扩展名分派；`.csv` 默认编码探测
        utf-8 → utf-8-sig → gbk → gb18030，显式传 `encoding=` 时不再探测
      - `na_values` 默认吃下空串 / `NA` / `N/A` / `#N/A` / `null` / `-`
      - 不支持的扩展名抛 `ValueError`；文件不存在抛带路径的 `FileNotFoundError`
      - `save_table` 的校验顺序已修正：后缀判断提到 `mkdir` 之前
        （此前传 `.txt` 会先留下一个空目录再抛错）
      - 测试：`tests/test_data.py` 由 1 条（且被模块级 skip 掉）扩到 **9 条**
      - 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）
- [ ] **待修：** `detect_outliers` 已写但有 3 个 bug（见下）
- [ ] 剩余 7 项：`normalize`
      `detect_outliers` `normalize` `standardize` `describe` `correlation_matrix`
      `bootstrap_ci` `monte_carlo` `save_figure`

### 验证结果

| 检查 | venv | conda `mcm-toolkit` |
|---|---|---|
| `pytest` | 见下（单列） | **53 passed, 42 skipped, 7 xfailed** |
| `import mcm_toolkit` | 0.0.1 / 16 项 | 0.0.1 / 16 项 |
| `ruff check` | All checks passed | **1 error**（就在 `detect_outliers` 那段待修的代码里） |
| `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（与两套环境一致）
- 53 条通过 = 20 条公开 API 契约测试 + 11 条 `core` 行为测试 + 22 条 `data` 行为测试
- 7 条 `xfail` 是**已知待修**的契约（`detect_outliers` 的 4 条、`winsorize` 混合类型、
  `clean_missing` 阈值范围、`impute_missing` 的 mode 就地修改）；
  修好后会自动变 XPASS，那时把 `xfail` 摘掉即可（决策 30）
- 42 条 skip 是等实现的算法（`normalize` / `standardize` / `train_test_split` 等）
- 三个 `.ps1` 通过 PowerShell AST 语法解析

### ⚠️ 需要注意 / 遗留

- [x] ~~两套环境版本不一致~~ → **已解决**：base 升级到 2026.07 后，
      numpy/scipy/pandas/matplotlib/sklearn/statsmodels/networkx/sympy 版本完全一致，
      只差 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 完成 **4/12**（`Result`、`get_rng`/`set_seed`、`load_table`/`save_table`、`clean_missing`），其余按 `docs/03-roadmap.md` 的 L0 → L1 顺序推进；
      详情见上面 E 节
- [ ] 本机 `exec_command` 在沙箱模式下**完全不可用**
      （`helper_unknown_error: setup refresh had errors`），只有提权
      （`require_escalated`）模式可用。沙箱模式只允许写 `D:\MCM&ICM_Toolkit`。
- [ ] **副作用**：沙箱通道（Node 子进程）以 `CodexSandboxOffline` 账户运行，
      它写出的文件 Owner 是沙箱账户而非 `guzhu`。
      实测 `guzhu` 对这些文件仍有 Modify 权限（继承自 `Authenticated Users`），
      读写不受影响；但 git 的 **dubious ownership** 检查会因此误报，
      所以 `.git` 必须由本人账户创建（见决策 17）。
      若以后再用沙箱通道写文件，注意同一问题。

## 决策记录

| # | 决策 | 理由 |
|---|---|---|
| 1 | 包数从 14 砍到 7 | `regression`/`ml` 重复；`optimization`/`simulation`/`sensitivity` 同族；`dynamics`/`network` 低频 → 降级为模块 |
| 2 | 只保留 1 个 `Result` | 第一版没有任何函数需要区分 5 种结果类型，属过早分类 |
| 3 | 函数清单从 ~250 砍到 ~40 | 4 天赛程的工具，不是 6 个月的框架；没在真题里用过三次的不写 |
| 4 | 删掉 `maximize` / 重复的 `normalize` / 13 个 `plot_*` 等 | 同义或一行转发；`plot(kind=...)` 替代 13 个函数 |
| 5 | 文档从"每函数 10 项"降到 2 档 | 10 项文档的写作成本是实现的 20 倍，是最可能导致项目停滞的一条 |
| 6 | 补上原文缺失的**论文产出链路** `save_table` / `mcm_style` | 美赛是论文比赛；原文只给了一个 `save_figure` |
| 7 | 补上**永久不做清单** | 原文用"建议不要"，防不住膨胀；写成硬规则 |
| 8 | venv 用 `--system-site-packages` | 10.5 MB、离线可用；作为轻量开发与断网兜底 |
| 9 | conda 环境用**精准包列表**而非 `--clone base` | 实测 `--clone` 会重放 base 全套包并逐个下载（连 pandoc 都下），远慢于精准列表 |
| 10 | 生成的是**签名 + docstring + NotImplementedError** | 用户要自己读代码学算法；骨架定接口，实现留给学习过程 |
| 11 | `.ps1` 写成**纯 ASCII**（英文注释/输出），而非中文 | Windows PowerShell 5.1 无 BOM 时按 GBK 解析 `.ps1`，中文直接导致语法错误；保留中文就必须加 BOM，违反 AGENTS.md |
| 12 | `.ps1` 用 LF 而非 CRLF | 遵守 AGENTS.md「shell 脚本 UTF-8 无 BOM + LF」；PS 5.1 对 LF 无问题 |
| 13 | `chatGPT_Suggestion.md` 保持原样 | 用户手写的输入文件，不属于本次产物，不做无谓改动 |
| 14 | base 升级用 `conda update -n base --all`，而不是装新 conda | 计划干净（365 更新 / 0 删除 / 0 冲突），且能保留既有的 `lingbot-map` 环境 |
| 15 | 项目环境 numpy **降**到 base 的 2.4.6 | 升 base 的 numpy 会连带把 BLAS 从 MKL 换成 OpenBLAS；宁可降一个 minor，也不动整套线性代数后端 |
| 16 | 新增 `.gitattributes` 强制 LF | 仓库要给队友在 Windows/WSL/Linux 上 clone，不固定行尾会产生"整文件都变了"的假 diff |
| 17 | `.git` 由**本人账户 guzhu** 重建，不做 `safe.directory` 豁免 | 沙箱通道建的 `.git` Owner 是 `CodexSandboxOffline`，git 会报 dubious ownership。加全局豁免是把问题藏起来；直接以本人账户重建，仓库和远程（Gitea）身份一致 |
| 18 | `core.autocrlf=false`（仓库级） | 配合 `.gitattributes` 的 LF 策略，避免 Windows 上 checkout 又转成 CRLF |
| 19 | Gitea 的 SSH **走 Tailscale 内网**，不在公网开 22 | 实测公网 `8.145.36.108:22` 超时（服务器侧过滤，本机出站 22 没被封：github.com:22 可通），而 Tailscale `100.115.86.48:22` 可达且 `git@` 认证直接过 Gitea。remote 里仍写域名，域名→内网 IP 的映射放在 `~/.ssh/config`，换机只改一处 |
| 20 | 首次推送用 `--force-with-lease` **覆盖** Gitea 的 `Initial commit` | 远端那个提交是建仓时自动初始化产生的，与本地无共同祖先，普通 push 必被拒。推送前已把其中的 LICENSE 与手写简介并入本地 `README.md`，原提交仍留在本机对象库（`1c683cf`） |
| 21 | `Result.__repr__` **不打印 `data` 内容**，只给类型与规模 | 模拟轨迹动辄十万个数，repr 一旦刷屏，traceback / 调试器 / notebook 输出就全废了。要看数据请直接取 `result.data` |
| 22 | `Result.summary()` 的行序 = 字典插入顺序，不排序 | 比赛时"想先看哪个指标"自己决定键的插入顺序即可，工具不该替人排序 |
| 23 | `set_seed` 内部**允许**调用 `np.random.seed`（带 noqa） | sklearn / statsmodels 默认走 numpy 旧全局状态，只记自己的 `_GLOBAL_SEED` 覆盖不到它们，"提交能重跑"就是假的。旧接口在这一个点上不是"取随机数"而是"设种子"，性质不同 |
| 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 |
| 27 | base 里的 zstandard 残骸目录**改名禁用**，不删除、不重装 | 删掉不可逆；`pip install zstandard` 会给 base 塞一个 conda 记录里根本没有的包，下次 `conda update --all` 又要重新判断。改名后 `import` 变回正常 `ModuleNotFoundError`，pandas 自动跳过 |

## 下一步

1. **修 `detect_outliers`**（唯一挡在 L0 前进路上的 🔴，三处都在 `src/mcm_toolkit/data/clean.py`）：
   - `clean.py:165-167` 的 `threshold` 范围校验放错了函数：`threshold` 只在 zscore 分支
     赋值，iqr 走进去就是 `UnboundLocalError`；而且 z 的阈值本来就是 3.0，
     用 `0 <= threshold <= 1` 卡它必然把默认值拒掉。
     你本意多半是想校验 `clean_missing` 的 `threshold`（那个才该是 [0,1]）——把它挪过去，
     `detect_outliers` 里删掉。ruff 剩下的那 1 条（SIM102）也在这 3 行里，删掉就全绿。
   - `clean.py:145` 的 `df.quantile()` 要在**数值列**上算：`df.select_dtypes(include='number')`，
     否则赛题表一带文本列就崩。`winsorize` 的 `clean.py:186` 同病，
     而且它的空数值列判断排在了分位数之后，等于没兜住。
   - `clean.py:130-131` 的 `is_series` / `is_ld_array` **永远为 False**：
     第 114-117 行已经把 `data` 转成 DataFrame 了，再判断 `isinstance(data, pd.Series)` 自然不成立。
     要在转换**之前**记下来，或者干脆用 `inspect` 拿原始入参。修好后
     `test_detect_outliers_returns_mask_not_filtered_data` 会从 xfail 变 XPASS。
2. **写 `detect_outliers` 的 S 档函数卡片**（`docs/algorithms/` 下，照 `docs/dev/function-card-template.md`）。
   roadmap 要求 S 档先写卡片再写码 —— 这次是反着来的，所以三个 bug 都在"该想清楚"的地方翻车：
   上界符号、布尔优先级、维度。卡片本身就是防这个的。
3. 顺手把 `impute_missing` 的 mode 分支改成**返回新表**（现在就地改调用方的 DataFrame，和另外四个分支不一致）。
4. 每写完一个函数，在 `examples/` 里加一行最小用法。
5. L0 跑通后，找一道真题（建议 2025 C）走完整流程，反向沉淀函数。