wayfinder-mathmodel

Files (15)

• SKILL.md
• openai.yaml · agents/
• external-resolver.md · references/
• paper-structure.md · references/
• result-contract.md · references/
• wayfinder-contract.md · references/
• check_claims.py · scripts/
• check_pdf.sh · scripts/
• compile_pdf.sh · scripts/
• render_latex.py · scripts/
• data.csv · scripts/tests/fixtures/cumcm_2024_c_smoke/
• problem.md · scripts/tests/fixtures/cumcm_2024_c_smoke/
• solve.py · scripts/tests/fixtures/cumcm_2024_c_smoke/
• test_wayfinder.py · scripts/tests/
• wayfinder.py · scripts/

SKILL.md (first lines)

# Wayfinder 数学建模

这是 MathModelAgent 的唯一用户入口。它把题面理解、建模、计算、写作和验收组织成一个可恢复的 Wayfinder 决策图；用户不需要依次调用内部 skill。规划和执行属于同一次任务：首次调用创建地图，之后每次调用从现有地图继续，直到交付 PDF、遇到必须由用户决定的问题，或明确阻塞。

## Destination

默认目的地是一个可提交的中文 CUMCM 数学建模论文工作区：

- paper/main.pdf：最终 PDF；
- paper/main.tex 与 paper/sections/*.tex：唯一排版源；
- paper/structure.md 与 results/*.md：论文结构和事实源；
- code/、figures/、problem_files/：可复核的输入、程序和证据。

正文必须是正式论文的一部分：不出现 AI、agent、ticket、草稿、占位符、内部流程或“不能作为因果证据”一类元话语。证据不足时，改写成证据支持的统计/预测/关联结论，不把免责声明塞进正文。

## First call and resume

1. 读取用户给出的题目正文和附件；Codex 能直接读取的文件直接使用，不强制引入 OCR 或文档摄取平台。
2. 以题目目录为 ROOT，运行 scripts/wayfinder.py init ROOT；已有 map.md 时只恢复，不覆盖。
3. map.md 只保留 Wayfinder 的五个地图区段：Destination、Notes、Decisions so far、Not yet specified、Out of scope。地图是索引；详细问题、答案和资产链接在 issues/。
4. 从题面生成首批子问题和必要决策票据，计算 frontier，认领一个可执行票据并处理它。研究票据可以并行；其他票据遵守“一次会话一个票据”。
5. 票据解决后立刻写回答案/资产链接、更新地图和 frontier；重新进入本 skill 时从未解决的已认领票据或 frontier 继续。

工作区固定为：

    ROOT/
    ├── map.md
    ├── issues/
    ├── problem_files/
    ├── code/
    ├── results/
    ├── figures/
    └── paper/
        ├── structure.md
        ├── sections/
        ├── main.tex
        └── main.pdf

## Wayfinder ticket contract

只使用四种票据类型：research、prototype、grilling、task。不要发明 decision、validation 或自定义状态。

- 票据正文主要只有 Question 段；答案写在解决时的 Resolution 段，资产用相对链接，不把大段数据粘进票据。
- claim 先写 assignee，再开始工作。depends_on 决定阻塞关系；未关闭依赖的票据不在 frontier。
- research 是 AFK 候选，可派生一个短生命周期研究上下文，按 Wayfinder 约定使用 research/name throwaway branch/context pointer；子上下文只返回研究结果和引用，父票据负责归并和解决。
- prototype 与 grilling 是 HITL 候选；task 可根据风险决定 AFK 或 HITL。
- 关闭票据只意味着该问题的答案或证据已经写入；重要解释仍需在论文源中用正式文字表达。

用脚本保持这些语义：

    python scripts/wayfinder.py init ROOT --destination "..."
    python scripts/wayfinder.py new ROOT --title "..." --type research --question "..."
    python scripts/wayfinder.py frontier ROOT
    python scripts/wayfinder.py claim ROOT --title "..." --assignee codex
    python scripts/wayfinder.py resolve ROOT --title "..." --resolution-file answer.md

面向用户显示票据标题，不显示裸 ID。失败的建模路线不删除：另建一个有依赖关系的新票据，在原票据答案中记录失败原因。

## Input gate

题面、数据列名、单位、图表或附件若不可读或有会改变模型的歧义，立即在聊天中停止并指出文件名、页码/位置、具体问题和用户需要采取的动作。此时不建票据、不写猜测数据、不生成部分论文。用户补充后，从地图恢复。

对能读出的事实由 agent 处理；只把不可约的人类选择交给用户，例如题意解释、关键假设、模型路线、最终发布。每次 HITL 问题都遵守零上下文原则：短、独立、面向初学者，并附推荐项：

    ❓ Q - 采用哪种题意解释？
    题面中的“覆盖”可能指 A（至少一次）或 B（累计次数）。
    A：……；B：……。
    ➡️ 建议：A，因为它与题目给出的评价指标一致。

用户回复 y 表示接受当前所有清晰的推荐；有歧义或高副作用时只追问一个聚焦问题。不要要求用户复述前文。

## Modeling and computation

把每个有实质影响的未知点拆成票据，而不是预先强行套固定六阶段。通常按以下条件调用内部解析器：

1. 2analysis-modeling：将当前问题闭合为变量、假设、目标、约束、求解方法和校验口径；最多保留两个候选模型族，先按正确性、可解释性、可计算性、验证性和稳定性比较，再考虑复杂度/新颖性。
2. 3coding-visual：只实现已经认领的建模票据，使用 Python 和仓库已有依赖；程序必须实际运行，优化先检验可行性，预测有验证划分或误差评价，图表必须由数据生成。
3. 4drawio：仅在整体思路或机制图能帮助读者理解时调用；不为装饰生成图。
4. 5writing：从 paper/structure.md 和结果事实生成 paper/sections/*.tex，只使用 LaTeX/CUMCM 模板；main.tex 是生成物，不手工维护。
5. 6verity：执行文本、引用、数值、代码和 LaTeX/PDF 检查；失败则回到产生该证据的票据，不用验收阶段掩盖问题。

默认使用“最简单的充分模型”。只有题目要求或验证显示收益明确时才升级复杂度。研究/原型的目标是消除不确定性，不是增加方法数量。
若宿主提供外部 GitHub 数学建模 skill，遵循 references/external-resolver.md：当前票据最多绑定一个最匹配的外部 resolver，完成后仍由本 skill 归并和验收。

## Evidence contract

results/ 是数值和结论的事实源。每条论文级结论至少有一个 Markdown 结果条目，字段见 references/result-contract.md：

    ---
    claim: "..."
    value: "..."
    unit: "..."
    method: "..."
    source_artifact: "code/solve.py"
    validation: "..."
    execution_status: "passed"
    run_command: "python code/solve.py"
    reported_value: "..."
    ---

禁止编造、手算后伪装成运行结果或用未记录的四舍五入替代原值。随机算法记录 seed；运行命令在不明显时记录。图表、表格和正文数字都必须能追溯到结果条目及其源资产。

## Adaptive paper contract

先读 references/paper-structure.md，再为当前题目生成 paper/structure.md。它是自适应章节图，不是固定目录。优秀 CUMCM 论文常见的可选骨架是：

- 摘要（问题、方法、关键数字、结论）；
- 问题重述、问题分析、符号与假设；
- 数据处理/探索性分析（仅在有用时集中写）；
- 每个子问题一个闭环：分析 → 假设/变量 → 模型 → 求解 → 结果 → 验证/解释；
- 模型评价、敏感性/稳健性、推广与局限；
- 参考文献、代码/数据附录。

不机械复制示例论文，也不因为题目没有三问而强行补三章。每张图表都有问题、数据源、生成程序、正文解释和 caption；没有证据支撑的图表不进入正文。论文正文先在 sections/*.tex 完成，模板只负责排版。

## Finish gates

只在以下条件同时满足时向用户交付“最终”：

From Antrairs/mathmodel-skills, Apache-2.0.

More from Antrairs/mathmodel-skills