Cumcm Code Writer

数模代码编写 Skill

定位：这是写作向技能——输入是模型与算法约定，输出是可运行代码与两份提交级文档。查代码用 代码编写评价/（cumcm-code-reviewer），两者不要混用。 依据：references/（风格与规范）＋ references/algorithm_library/（精选参考实现）＋ references/official/（国赛 2026 格式规范的附录与支撑材料条款）。 边界：只写代码与两份文档，不写论文正文，不给奖项位次、不给分数。

何时使用

• 用户给出模型、算法或框架，要求“按这个思路写代码”“把这题实现出来”“出附录和结果”。
• 用户提供了赛题并用代码求解，需要交付可运行程序与结果材料。

不适用：只想评价已有代码（转 代码编写评价）；只想评论文（转 数学模型评价）。

输入要求

必给：

1. 模型与算法：这一问要建什么模型、用什么算法或求解器。
2. 模型框架：变量与符号、目标函数、约束、参数含义与单位；有公式就给公式。
3. 数据：需要数据的题目必须提供文件（CSV/XLSX/JSON/txt/mat），并说明每列含义与单位；确实不需要数据的要明说“无需数据”。

可选：赛题原文或年份题号（用于对齐小问与红线）、论文提纲或已有草稿（用于对齐符号与结果口径）、指定语言（默认 Python，备选 MATLAB）。

硬门禁（未通过不写代码）

按序检查 G0→G3，任一未过即输出《待补清单》并停止，清单里写清缺什么、怎么补、补齐后能继续到哪一步。

工具缺失的处理：Python 依赖可在工作区虚拟环境 工具/code_env/ 内自动安装（需联网）；Python 本身缺失时不降级、不出图，直接请用户安装；MATLAB 或工具箱缺失只报告并给出替代方案，不静默降级。

五阶段流程

1. 拆题冻结：把赛题或用户描述切成小问，逐问写清“建什么模型、用什么算法、输出什么数值/表/图”。冻结后不在中途增删小问。
2. 数据与环境：跑 G1/G2，产出 work/<项目名>/数据说明.md 与 work/<项目名>/环境快照.md；缺失即停。
3. 参考命中与写码：按 G3 命中算法模板，读懂接口约定与常见坑，再按 references/代码风格规范_竞赛可读版.md 写代码：小问分脚本＋公共模块＋总运行入口，公式编号写进注释，固定随机种子。同时写 work/<项目名>/参考依据.md（模板见 templates/参考依据模板.md），记录每个小问引用了哪个模板、沿用了什么、按题目改了什么、为什么改。
4. 三轮自测：scripts/selftest.py 依次跑三轮并把输出写进 work/<项目名>/自测记录.md：
   • 第一轮：语法与依赖、端到端跑通、输入输出形状与量纲。
   • 第二轮：数值与算法正确性对照（小规模暴力解、解析解或成熟库实现三者互证），边界与极端输入。
   • 第三轮：多种子稳定性、关键参数敏感性、结果与论文口径（若给了提纲/草稿）一致性。 任一轮失败就回到写码阶段修，修完重跑该轮，不允许带着失败结论进入交付。第二轮不得空转：校验脚本必须打印 CHECK-SUMMARY total=.. passed=.. baselines=..，且 total≥3、baselines≥1（baselines 指由另一条代码路径算出的基准值）；缺校验机制或校验强度不足一律判未通过并阻塞交付，只有用户明示豁免（--allow-missing-verify）才放行，且必须在结果文档的限制说明里写明。
5. 交付：写码时同步登记 work/<项目名>/论文口径.md（模板见 templates/论文口径模板.md），把论文里写下的关键数值逐条列出；随后跑 scripts/check_gates.py --project <项目名>，七项门禁（数据说明／环境快照／参考依据／三轮自测／代码体检／图件合规／论文口径）全绿才允许生成文档；然后 scripts/build_appendix.py 生成附录（支撑材料文件列表＋运行说明＋全部完整源码＋数据说明＋参考依据与偏离说明，逐文件哈希校对），scripts/build_results_doc.py 生成结果文档（逐问结果表＋图＋运行说明＋环境快照）。缺 参考依据.md 时附录脚本直接报错不出文档。默认同时给 Markdown 源与 DOCX 成品。

代码风格要点

• 竞赛可读优先：一个问一个脚本，公共函数抽到 common/，根目录一个 run_all.py 或 main.m 顺序调用；附录里能直接读懂。
• 注释与 docstring 只写两块：公式/符号与代码的对应、非显然的算法步骤。不写“初始化变量”“开始循环”这类废话。
• 禁止在注释/docstring 里留流程与修订痕迹（S3R/S4B/P1-x/work/.../_s3r*/方案 §x/假设 Ax/“等价性对照”“开箱复现”“性能改造”等）——附录要像正常竞赛代码，不能暴露流水线与修订过程；改完代码若注释提到旧文件名或旧路径，一并清掉。
• 随机算法固定种子并记录；迭代类算法输出收敛过程；结果文件带表头与单位。
• 数据校验与异常处理保留最小必要部分，不写整屏 try/except 包装。
• 不为了“显得专业”引入用不到的抽象层、设计模式或第三方库。

完整规则见 references/代码风格规范_竞赛可读版.md 与 references/低AI味代码规范.md。

性能与效率（硬规则：能快必须快，且不许改口径）

1. 时间预算：全流程（含校验与出图）默认目标 ≤120 s；超过就在结果文档《运行说明》里写清每阶段耗时与优化方案。交付前记录一次基准运行时间。
2. 线性代数不许手写循环：时间步里的隐式求解一律用 scipy.linalg.solve_banded / scipy.sparse.linalg / numpy.linalg.solve；禁止在 Python for 里手写追赶法（网格数 ≥10 时）。实测：20 格追赶法每步 ~2.4 ms，换 banded 求解可快 2–4 倍。
3. 每步只做一次向量化：物性、界面系数、装配用 numpy 数组一次算完；不在不动点迭代里重复构造常量数组或重复 np.exp 全场。
4. 大结果文件用 xlsxwriter：行数 >1 万的表用 xlsxwriter（constant_memory=True + write_row）或 pandas.ExcelWriter(engine="xlsxwriter")，禁止逐格写；写出的数值必须是数字类型，工作表名/表头/A 列/列序/末列名一律不变（实测 59370×22×2：openpyxl 13.0 s → xlsxwriter 9.7 s）。
5. 积分步长 ≠ 输出步长：模板要求"每 1 s 输出"不等于必须 1 s 积分。允许内部用较粗步长积分、再插值到输出网格，但必须先做 ≥3 档步长的收敛验证（关键量偏差 ≤0.1%，必要时更严），并在结果文档写明口径；不通过就退回 1 s 积分。
6. 独立小问并行：各问互不依赖时用进程级并行（ProcessPoolExecutor 或并行脚本），保留 --jobs 开关；并行不得改变随机种子与数值结果。
7. 增量重跑：入口脚本支持 --only q3 之类的子集开关与结果缓存（按输入哈希跳过未变体），改一处不重跑全部。
8. 性能日志：每个小问、每轮校验打印耗时（[time] q3 solver 12.3 s），汇总进《运行说明》。
9. 性能回归：任何改动若使整轮运行时间上升 >30%，必须在修订记录里说明原因与取舍。

可视化要求

所有交付图件必须由 Python + matplotlib 生成，MATLAB 只负责计算，不允许用 MATLAB 出交付图；本机没有可用 Python 时停止并请用户安装（Python 3.10+，https://www.python.org/downloads/），再跑 scripts/bootstrap_env.py --install-optional。 统一 300dpi、色盲友好配色、中文字体显式设置、坐标轴带单位、图号与题号对应；每问除规范图外再给一张信息量更高的组合主图（多子图、带注释或不确定性区间）。绘图脚本与数据分离，保证重跑可复现。细则见 references/可视化规范.md，检查由 scripts/check_figures.py 执行。

输出与命名

默认写 代码编写/output/<项目名>/，绝不在 数据集/ 下产生任何文件。 技能被安装到全局（~/.codex/skills/）后，可用环境变量 CUMCM_CODE_PROJECT 指定项目根目录，产物会写到 <该目录>/output/ 与 <该目录>/work/，避免把结果堆在技能目录里。

output/<项目名>/
├── code/                     # 可运行代码（含数据接口说明）
├── figures/                  # 每图 PNG(300dpi) + PDF(矢量)
├── tables/                   # 逐问结果表（CSV + Markdown）
├── <项目名>_附录.md / .docx    # 附录：支撑材料列表 + 全部源码
├── <项目名>_结果文档.md / .docx  # 结果：逐问结论、图表、运行说明
└── 运行说明.md                # 环境、命令、产物清单

支撑材料只生成文件列表（写在附录），不打包压缩包。

阅读预算

• 算法库有 90 个算法、180 个模板：只读命中的 1–3 个 meta.yaml 与对应 python/main.py／matlab/main.m，不要通读 algorithm_library/。
• 需要按题型找算法时读 references/算法-模型对照表.md 或 index.md 的目录表，再定位到具体模板。
• 方法公式口径以 references/来源与方法依据.md 登记的权威来源为准，摘要片段在 references/_methods/<id>.md。
• 参考库依赖与许可看 manifest.csv，外部下载记录看 manifest_sources.csv。

边界与规则

• 只写代码与两份文档；论文正文、摘要、奖项位次不在职责内。
• 结果必须来自真实运行；没跑通就写“未跑通”并说明卡在哪，不虚构数值。
• 参考库只复制宽松许可实现并登记来源；生成用户代码时按公式自行重写，不整段搬运。
• 数据与产物不写入 数据集/；用户数据只做只读使用，不改变原始文件。
• 涉密或未授权数据不复制进参考库与附录样例。

references 索引

• references/算法-模型对照表.md：题型 ↔ 算法 ↔ 成立条件 ↔ 必需库 ↔ 常见误用（拆题与选型时必读）。
• references/代码风格规范_竞赛可读版.md：文件组织、命名、注释、随机性、结果输出规范（写码前必读）。
• references/低AI味代码规范.md：反 AI 味的正反例与自检清单。
• references/数据交接规范.md：数据提交清单、数据说明模板、缺失与异常处理口径。
• references/环境与工具检查规范.md：工具探测项、虚拟环境策略、缺失时的报告口径。
• references/可视化规范.md：字体、配色、图种选择、创意主图与自检清单。
• references/附录与结果文档规范.md：两份文档的结构、合规要求与命名。
• references/official/：国赛 2026 格式规范中附录与支撑材料条款原文。
• references/algorithm_library/：精选参考实现，manifest.csv 为索引，index.md 为可读目录。

scripts 索引