MCM-ICM_Toolkit/STATUS.md

# STATUS — 当前进度

> 更新日期：2026-10-01

## 本次任务

审查并精简 ChatGPT 的建库建议 → 生成骨架文件 → 配置 conda 与 venv 环境。

**结论：全部完成。** 两套环境均已建成并通过验证。

## 任务清单

### ✅ 已完成

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

**B. 骨架文件生成**（78 个文件，约 6500 行）
- [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` `.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 3.13.9 + `--system-site-packages`）
      + `pip install -e . --no-deps --no-build-isolation`；
      可直接导入 numpy 2.3.5 / scipy 1.16.3 / pandas 2.3.3 / matplotlib 3.10.6 /
      sklearn 1.7.2 / statsmodels 0.14.5 / networkx 3.5 / sympy 1.14.0
- [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` 实测会走完整下载安装，不再是"离线快捷方式"）

### 验证结果

| 检查 | venv | conda `mcm-toolkit` |
|---|---|---|
| `pytest` | 20 passed, 49 skipped | 20 passed, 49 skipped |
| `import mcm_toolkit` | 0.0.1 / 16 项 | 0.0.1 / 16 项 |
| `ruff check` | All checks passed | — |
| `scripts/doctor.ps1` | 跑通 | — |
| SALib / pymoo / pyright | 缺失 | 已装 |

- skip 的都是等实现的算法行为测试；通过的 20 条是 `tests/test_api_surface.py` 的公开 API 契约测试
- 三个 `.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。
- [ ] 所有函数实现尚未开始（按 L0 → L1 顺序，见 `docs/03-roadmap.md`）
- [ ] Gitea 远程尚未配置（本地仓库已初始化并完成首次提交，推送步骤见 `docs/05-git-workflow.md`）
- [ ] 本次执行环境的 `exec_command` 在沙箱模式下**完全不可用**
      （`helper_unknown_error: setup refresh had errors`），
      只有提权（`require_escalated`）模式可用。沙箱模式只允许写
      `D:\MCM&ICM_Toolkit`，因此前面一轮只能用 Node 子进程作为执行通道。

## 决策记录

| # | 决策 | 理由 |
|---|---|---|
| 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 |

## 下一步

1. 按 `docs/03-roadmap.md` 的 **L0（12 个函数）** 顺序填实现，先写测试再写代码。
2. 每写完一个函数，在 `examples/` 里加一行最小用法，并更新本文件。
3. 在 Gitea 建空仓库 → `git remote add origin ...` → `git push -u origin main`
   （命令见 `docs/05-git-workflow.md`）。
4. L0 跑通后，找一道真题（建议 2025 C）走完整流程，反向沉淀函数。