CUMCM Workflow

简体中文 | English

一套面向全国大学生数学建模竞赛的 AI agent 工作流：从官方材料出发，把建模、计算、复核、论文和最终交付串成一条可检查、可追溯的证据链。

官方材料固定 → 题目拆解 → 候选模型试算 → 正式计算 → 独立复核 → LaTeX 论文 → PDF QA 与交付

它不提供现成答案，也不替你判断模型是否正确；它负责让每一个写进论文的结论都能追回到官方题目和一次真实发生过的计算，并在模型选择、写论文前的结论、最终交付三个关键节点把决定交还给你。

支持 Codex 与 Claude Code。当前版本 v0.6；不向下兼容旧版本工作区。

快速开始

1. 准备材料

把当届官方材料集中放进一个本地目录。工作流初始化时会复制这些文件并固定身份，不会修改原目录。

2. 确认路径格式

• macOS / MacBook：路径示例为 /Users/你的名字/Documents/赛题资料。
• Windows（推荐 WSL2）：在 WSL2 的 Linux 环境中运行 agent 与工作流工具。Windows 的 C:\Users\你的名字\Documents\赛题资料 在 WSL 中通常对应 /mnt/c/Users/你的名字/Documents/赛题资料；新项目路径可用 /home/你的WSL用户名/cumcm-projects/2026B。
• Windows 原生 PowerShell：后文的 Bash 示例，尤其 $S、$PWD、ln -s，不能直接照抄。当前 CI 在 Linux 上运行，尚未完成 Windows 原生端到端验证，因此优先使用 WSL2。

提示词中的材料路径和输出路径必须采用 agent 实际运行环境看到的格式，不要混用 Windows 与 WSL 路径。Python、所选计算后端和 XeLaTeX 也必须安装在该执行环境中。

3. 对话一：下载工作流并配置环境

第一次使用时，先打开一个独立对话，只完成工作流下载和环境准备，不要放入赛题路径，也不要初始化项目。在一个可写的本地工作目录中发送：

请为 https://github.com/Lucasuiii/cumcm-workflow 的最新 main 工作流准备运行环境。
本对话只负责下载工作流、读取使用说明、检查并配置环境；
不要读取赛题、不要初始化赛题项目，也不要开始建模。

先只读检查当前工作目录。用 git clone 将仓库下载到独立的工具目录；
若已有同源仓库，先检查远端、版本和本地改动，不要覆盖已有内容，
必要时另建干净副本。
完整读取工具目录中的 .agents/skills/cumcm-workflow/SKILL.md，
使用该 Skill 的绝对路径检查 Python 3.10+、所需 Python 依赖、
可用的 MATLAB 或 Python 计算后端，以及 XeLaTeX 和 PDF 渲染环境。

如需安装依赖或修改系统环境，先列出变更并等我明确同意。
环境就绪后停止，向我报告工作流目录、Skill 绝对路径、
实际检测到的版本、可用后端和仍存在的限制，供下一个对话使用。

如果 Skill 已经安装，也仍建议用这个对话确认仓库版本、Skill 实际路径和运行环境；不要把“能触发 Skill”当成环境已经就绪。

4. 对话二：初始化赛题并开始流程

对话一确认环境就绪后，新建第二个对话。把它报告的工作流目录，以及你自己的官方材料目录和新项目输出目录，填入下面的提示：

请使用已经准备好的 CUMCM Workflow 开始本次赛题。

工作流工具目录：/绝对路径/cumcm-workflow
官方材料目录：/绝对路径/赛题资料
新项目输出目录：/绝对路径/尚不存在的目录

先只读检查工作流目录和官方材料目录，确认工作流版本与工作区状态，
不要覆盖任何已有内容。完整读取
.agents/skills/cumcm-workflow/SKILL.md，并使用该 Skill 的绝对路径调用脚本。
确认对话一准备的 Python 依赖、计算后端和 XeLaTeX 环境仍然可用；
如环境不满足要求，停止并说明缺失项，不在本对话安装或修改系统环境。

识别原题、附件、结果模板及当届格式/提交/AI 使用规定，
从官方材料初始化新项目，然后按 Skill 开始读题与问题拆解。
在模型选择、写论文前的结论、最终交付三个节点停下来等我明确确认。

已安装 Skill 时，可在第二个对话用 Codex 的 $cumcm-workflow 或 Claude Code 的 /cumcm-workflow 触发，但仍应同时提供工作流目录、官方材料目录和新项目输出目录。

5. 启动后你需要做什么

第一个对话只留下可复用的工作流工具和环境报告；第二个对话复制官方材料、初始化项目，并从读题与问题拆解开始。你无需预先填写契约或手动运行每个脚本，只需在三个明确的人工确认点审阅当前材料并决定是否继续。中断后，回到第二个对话，提供输出目录并要求“继续 cumcm-workflow”。

1. 它解决什么问题

让模型自由发挥地做数模，典型失败不是"算错"，而是这五种：

它不保证的：模型在数学上正确、全局最优、统计设计合理。检查通过只意味着"结构、来源、执行记录和已记录的评审边界是一致的"。

2. 两条规则

整个 v0.6 就是这两句话的展开。

① tooling 记录机器事实，agent 写语义判断

你永远不需要手算一个哈希。如果某个改动会让 agent 把 SHA-256、退出码、页数或结果数值敲进 JSON，那个改动是错的——去扩展记录器。

② 模型是后选的，而且选择要靠证据挣来

真实建模不是"先写对合同再执行"，而是：

Problem Analysis
      │
      ▼
Model Design ─────► 候选 A / 候选 B
      │             · 为什么值得考虑（why_considered）
      │             · 用什么证据区分（discriminating_evidence）
      ▼
Computation ──────► 低成本 exploratory evaluation
      │             record_run.py --candidate CAND-A
      │             record_run.py --candidate CAND-B
      ▼
选择 A ───────────► status: selected
      │             decision_rationale 说明凭什么选它
      │             evaluation_run_ids 指向那两次探索运行
      ▼
A 做 official computation
      │             record_run.py --official
      ▼
Validation

这条链在 v0.6 里是有结构、被检查的，不只是一段建议：

• 恰好一个候选可以是 selected（MODEL-E013）；
• 被选中的候选必须引用真的评估过它的运行（MODEL-W014）；
• 选中或淘汰都要有理由（MODEL-E014）；
• 候选说不出"用什么区分"会被标出来（MODEL-W012）；
• cumcm_check.py 在报告里打印整张对比表（model_candidates）。

working 期这些是 warning，冻结时变成 error。只有一个候选是允许的（只提示 MODEL-W007）——本工作流不逼你凑候选，它只是不让你声称一场没做过的比较。

3. 七个阶段

intake → problem-analysis → model-design → computation → validation → paper → delivery

原则上 modeling、computation、validation、paper 分别在不同的 fresh task 里做。跨职责只通过四个 handoff 传递，新 task 先读 handoff、再按指针补读，不扫描整个工作区：

modeling-computation   computation-validation   validation-paper   paper-delivery

handoff 只带路径、角色、摘要和一个 upstream digest；不带完整日志、失败运行、调试历史或旧复核对话。任一上游产物变了，handoff 立刻 stale，必须重建。

4. 证据模型

三个等级

正式计算的唯一链条

RESULTS_INDEX.json → 被引用的 run_id → official_run:true 且 exit 0
                   → 当前有效的 sha256-tree-v1 源码快照
                   → locator 指向该运行声明的 claim_bearing_output

computation→validation handoff、独立复核包、paper→delivery handoff 三个消费者共用同一个解析器。任何一环缺失、失败、非 official 或 stale，三处一起明确失败——不会一个忽略、另一个才报错。

探索运行是一等公民

record_run.py --project <p> -- python3 code/try.py

零 flag，产出一份合法的 official_run: false 记录。它被记录、不被信任、永不阻断：断言失败、非零退出、缺日志、缺 capability，全都是 warning。它也不进入阶段批准范围——新增探索运行不会让已批准的 computation 失效。

这是有意的：Deferred Model Selection 的全部收益都来自"试算便宜"。

运行是追加的，证据是冻结的

--rerun 不覆盖，它追加一个新运行（RUN-Q1-001 → RUN-Q1-002），parent_run_id 指向被取代的那个。父运行连同日志原封不动留下——"改代码之前那次正式运行算出了什么"永远答得上来。

每次运行还会把 --source 和 --output 冻结进自己的目录，镜像原来的相对路径：

runs/RUN-Q1-002/
├── RUN_MANIFEST.json
├── stdout.log  stderr.log
├── source/code/solve.py        ← 执行时那一版代码的副本
└── outputs/results/q1.json     ← 那次产出的副本，locator 指这里

冻结副本不可变，所以被保留的运行永远可验证。而"改了代码却没重跑"这条最有价值的检查并没有丢——它改成比对冻结副本与当前活文件：

ERROR RUN-E020  the working tree no longer matches this official run: code/solve.py
                remediation: record_run.py --rerun RUN-Q1-001 --official

被取代的运行豁免这条（它当然不一样，这正是你取代它的原因）；反过来，改动冻结副本本身是另一类失败 RUN-E021（证据被篡改）。

superseded 由 parent_run_id 链推导，绝不回写旧 manifest——回写会改变它的哈希，把已经绑定它的 accepted decision 全部打成 stale。结果仍指着被取代的运行时报 RESULT-E017，用 index_result.py --follow-lineage 显式重新指向：换哪次运行支撑结论是语义判断，不能让工具偷偷替你做。

problem/official/ 下的 input 就地取哈希（不可变契约已保护，且附件可能很大）；其余 formal input（data/cleaned.csv 这类会被重新生成的）同样冻结，有体积上限。

还有两条记录期的硬规则，都是防伪造：

• 不能冒领输出。执行前后比对每个 declared output 的 mtime。一个 exit 0 却没写文件的程序，否则会把上一轮的结果连同真哈希一起冻结成自己的 claim 证据——真哈希、假出处。这种情况 record_run.py 直接拒绝写 manifest 并指出是哪个文件。
• 不能继承判决。--rerun 永不继承父运行的 assertions。新代码没有被旧的 pass 验证过，继承它等于凭空给 MODEL-E009（冻结模型必须有已执行的验证）喂证据。
• 手打的判决不算已验证。--assert x=pass 记为 declared（调用者备注），--assert-file 读程序自己写出的判决、记为 recorded。只有 recorded 能满足冻结模型的 verification_plan；official run 全是手打断言时报 RUN-W003。
• 证据不能在脚下移动。声明的源码和 formal input 在执行前取哈希、执行后复核——冻结发生在命令退出之后，运行中被改过的文件会被冻结成"运行从未读过的东西"。

另外 RUN-E024 真正落实了 single-backend：同一 capability 不能同时存在 MATLAB 和 Python 的当前 official run（working 是 warning，冻结时是 error）。随机模拟用 --seed 记录种子。

只有成功的 official child 才构成取代：失败或探索性的重跑什么也没替代。checker、handoff、复核包和 delivery 共用同一个解析器，所以"当前正式运行"四处含义一致。claim/figure 仍引用被取代运行时报 CLAIM-W020/FIGURE-W013。

5. 两个旋钮

v0.6 没有 profile。只有：

• working：草稿模型合同即可、CROSS_QUESTION_LEDGER.json 可选、阶段排序只是 warning。官方输入保护、真实执行、精确 locator、非伪造照样强制。preflight 显示待审查而不阻断探索；enforce 在两种模式都要求人工确认。正式运行和论文入口也检查对应确认。
• finalizing：完整模型合同（且 verification_plan 要对应到官方运行真的记录过的断言）、目标及上游阶段全部 passed、当前 accepted decision 与 snapshot、fresh handoff、独立复核、PDF QA、delivery 绑定。

阶段状态只有四个：not_started / in_progress / passed / needs_revision。

三个必需人工确认点是模型选择、写论文前的结论、最终交付。展示当前材料并收到明确回复后，用 record_decision.py --decision accepted --confirm-human，指定 --stage、--task-turn-ref 和 --summary；命令自动填入现有确认字段并推进状态。技术阶段检查通过后省略 --confirm-human。模型自审不算人工确认，记录仍依赖如实引用用户回复。

6. 一次完整走查

S="$PWD/.agents/skills/cumcm-workflow/scripts"  # 在仓库根目录设置

① 初始化（对话里直接说"用 cumcm-workflow 从 /path/to/2026B 初始化"即可，agent 会替你跑）

python3 $S/init_project.py --project ~/cumcm/2026B --project-id CUMCM-2026-B --official /path/to/2026B

官方文件被复制进 problem/official/ 并记录哈希；原目录不被修改。

② 拆题：agent 写 PROBLEM_FACTS.json（每条事实注明来源文件与位置）和 TASK_CAPABILITIES.json（每个小问一个负责人 + 可能失败的验收检查）。

③ 提候选：agent 在 MODEL_CONTRACT.json 里写 2 个候选，各带 why_considered 和 discriminating_evidence。

④ 探索评估：

python3 $S/record_run.py --project <p> --candidate CAND-A -- python3 code/try_a.py
python3 $S/record_run.py --project <p> --candidate CAND-B -- python3 code/try_b.py
pyth