0 Fork 0

Files

T

guzhujushi 5319589dfd chore: 初始化 MCM/ICM Toolkit 仓库骨架

审查并精简 ChatGPT 的建库建议后落地的第一版骨架，只定接口不写实现。

- 建议审查：14 个包 → 7 个；约 250 个函数 → 约 40 个；5 个 Result 类 → 1 个
  （docs/01-suggestion-review.md）
- docs/：架构、路线图（含永久不做清单）、环境、Git 工作流、函数卡片模板
- src/mcm_toolkit/：core / data / stats / models / solve / decision / viz
  共 23 个模块，均为签名 + docstring + NotImplementedError
- tests/：9 个文件，其中 test_api_surface.py 已通过（20 passed）
- examples/ problems/ notebooks/ figures/ tables/ 骨架
- pyproject.toml（核心依赖 4 个 + 6 组 extras）、environment.yml
- scripts/：setup-venv.ps1（ASCII + LF）、setup-conda.ps1、doctor.ps1
- 环境：.venv（system-site-packages）与 conda 环境 mcm-toolkit 均已建好，
  数值栈版本与 base 完全对齐（numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6，MKL 后端）

2026-10-01 17:43:48 +08:00

3.4 KiB

Raw Blame History

Git 工作流与远程托管

本仓库目前是本地仓库，之后托管到你自己的 Gitea。

一、仓库约定

行尾

由 .gitattributes 强制：仓库内一律 LF，checkout 时不做自动转换。

原因：AGENTS.md 要求 shell 脚本 UTF-8 无 BOM + LF；而这个仓库会被队友在 Windows / WSL / Linux 上 clone。不固定行尾的话，每次提交都会出现 "整个文件都变了"的假 diff，review 时根本看不出真实改动。

例外：*.bat / *.cmd 保持 CRLF（cmd 解析需要）。

Windows 用户建议同时设：

git config --global core.autocrlf false
git config --global core.eol lf

什么不入库

见 .gitignore。重点是三条：

忽略	为什么
`.venv/`、`.conda/`	环境可由 `scripts/setup-*.ps1` 重建，不该进版本库
`problems//raw/`、`/.xlsx`、`problems//.csv`	赛题原始数据体积大、可重新下载；只提交处理脚本和结论
`figures/.png`、`figures/.pdf`、`tables/*.csv`	中间产物。定稿的图请放进 `problems/<年份>_<题号>/figures/` 再提交

判断标准：这个东西能不能由仓库里的其他文件重新生成？ 能 → 不入库。

二、日常提交

git add -A
git commit -m "feat(stats): 实现 bootstrap_ci"

提交信息建议带模块前缀，方便以后回溯"这个函数是哪次加的"：

前缀	用途
`feat(<模块>)`	新增函数 / 功能
`fix(<模块>)`	修 bug
`test(<模块>)`	只改测试
`docs`	只改文档
`env`	环境、依赖、脚本
`chore`	其他杂项

提交前跑一遍：

.\scripts\doctor.ps1

它会同时检查 venv 和 conda 两套环境并跑测试。

三、推到自己的 Gitea

1. 在 Gitea 上建空仓库

不要勾选"初始化仓库"（不要生成 README / .gitignore / LICENSE），否则首次 push 会冲突。

2. 加远程并推送

cd D:\MCM&ICM_Toolkit

# 换成你自己的 Gitea 地址
git remote add origin https://git.你的域名/用户名/mcm-icm-toolkit.git

# 如果 Gitea 用的是自签证书，先在浏览器里访问一次并信任，或：
# git config --global http.sslBackend schannel

git branch -M main
git push -u origin main

3. 用 SSH（推荐，免密）

ssh-keygen -t ed25519 -C "guzhu@mcm-toolkit"
Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub" | Set-Clipboard
# 粘贴到 Gitea → 设置 → SSH/GPG 密钥

git remote set-url origin git@git.你的域名:用户名/mcm-icm-toolkit.git
git push -u origin main

4. 如果不想公开

Gitea 建仓库时选 Private。队友通过仓库设置 → 协作者 → 添加成员授权。

四、给队友的说明

队友 clone 后只需要：

git clone <你的仓库地址>
cd mcm-icm-toolkit
.\scripts\setup-venv.ps1      # 零下载，复用他们自己的 Anaconda base
.\scripts\doctor.ps1

setup-venv.ps1 用的是 --system-site-packages，所以他们本机得先有 Anaconda。如果队友没有 Anaconda，让他走 scripts/setup-conda.ps1。

五、回滚

环境升级出问题时的回退手段：

# conda 自己保留了 revision 历史
conda list -n base --revisions
conda install -n base --revision <N>

# 代码回滚
git log --oneline
git revert <commit>

3.4 KiB Raw Blame History Unescape Escape