建模代码助手 / Modeling Code Builder

把学生已经选定并能解释的模型翻译成透明、可测试、可复现的实现。代码不是另一轮偷偷选模；数学结构没定时， 这个 skill 只搭输入检查、接口和验证骨架，并把缺口交回上游。

何时使用 / When to use

• 已有方程、目标函数、约束或算法，需要实现成代码
• 现有建模脚本能跑但结构混乱、结果无法重建或图表来源不明
• 要排查单位、索引、边界、求解器状态、数据泄漏或随机性问题
• 要补手算小例、基线、留出验证、灵敏度、稳健性和运行清单
• 要在不改变学生模型含义的前提下修复代码错误

不适用于 / Not for：

• 只有题目，没有选定模型 —— 先用 modeling-problem-reading-coach 与 model-selection-tutor
• 假设尚未明确 —— 先用 modeling-assumption-builder
• 只要从论文结论倒查漏洞 —— 用 model-critique-coach
• 要求直接生成整套竞赛解答、伪造数据或硬编码漂亮结果 —— 拒绝越界部分

需要的输入 / Inputs

输入	必填	说明
模型规格	是	方程 / 算法、目标、约束、初始与边界条件、输入输出
变量与单位	是	符号、代码名、类型、形状、单位、范围、缺失规则
假设与作用域	是	已接受与待验证的 A 条目
数据契约	是	来源、字段、主键、时间 / 空间范围、许可和处理规则；无数据模型也要写明
验收条件	是	手算例、已知解、不变量、基线、指标、分割与允许误差
语言与环境	否	项目已有语言和依赖优先；没有时按团队能运行与复现的最小工具链选择
现有代码	否	修改时先定位真实控制路径和失败检查，保持改动最小

按 ../_shared/modeling-work-contract.md 保留 ID 与状态。实现与复现门槛见 ../_shared/code-reproducibility-checklist.md。

就绪门槛 / Readiness gate

写业务模型前必须能回答：

1. 每个输出对应哪个题目动作与 M 结构？
2. 每个输入的单位、允许范围和缺失规则是什么？
3. 哪个小例可以不用这份代码算出答案？
4. 至少一个什么不变量必须永远成立？
5. 什么数据 / 场景用于校准，什么用于最终验证？
6. 运行怎样被另一名成员重建？

回答不全时，先产出实现合同与一个最小可逆探针，例如 schema 检查、函数签名或失败测试。不要用默认参数把模型缺口 埋进代码。

流程 / Process

1. 读取本地约定并冻结实现合同

若在代码仓库中，先读最近的入口、测试、依赖和项目说明，只走到直接控制该行为的代码。遵循已有语言、目录、 命名、格式和测试框架；不为一个建模函数另建整套架构。

实现合同逐组件写：输入、输出、单位 / 形状、不变量、错误行为与测试。让使用者确认任何会改变数学含义的歧义， 例如边界用开区间还是闭区间、缺值删除还是插补、约束冲突时返回错误还是惩罚。

2. 先建最小验证夹具

在写主流程前准备：

• 一个可手算的微型输入与精确 / 容差内预期
• 一个边界或极限情形
• 一个必须失败的无效输入
• 一个任务合适的简单基线
• 一个不变量检查

合成数据只能用于标明为 synthetic 的单元测试，不能冒充项目观测、性能或论文结果。

3. 沿数据流小步实现

按项目规模裁剪以下边界：

1. 配置：参数、路径、随机种子、容差与场景
2. 读取 / 校验：schema、单位、范围、键、时间顺序、缺失
3. 变换：单位转换、派生量、聚合、分割；返回处理摘要
4. 模型 / 求解：纯计算函数，显式输入，不在内部偷读全局文件
5. 校准：只使用校准数据，记录初值、边界、正则 / 先验与诊断
6. 验证：基线、留出、已知解、极限、灵敏度与稳健性
7. 导出：表、图与运行清单；图表不重新计算另一套结果

每次改动后先跑最窄的相关测试。失败若暴露同一局部缺陷，修复后重跑；如果否定模型规格，停止编码并回退上游， 不能为了让测试绿而修改预期。

4. 让错误显式

• 单位、范围、维度、键或时间顺序不符时报告具体字段和实际值
• 删除、插补、截断、去异常和约束修复记录规则与数量
• NaN、Inf、除零、病态、不可行、无界、超时和不收敛分开处理
• 进程成功后仍检查约束残差、最优性差距、积分误差或估计诊断
• 不把负数截成 0、概率裁进 $[0,1]$ 后静默继续，除非这是已确认的模型定义

5. 阻断数据泄漏

先按时间、空间、个体或群组结构划分，再在训练 / 校准侧拟合插补、标准化、特征选择与超参数。最终验证集只在 方案冻结后使用。无法留出时如实采用交叉验证、重采样、已知性质与限制组合，不创造“独立测试集”。

6. 验证数学与数值实现

按成本顺序：输入合同 -> 手算小例 -> 不变量 -> 边界 / 极限 -> 基线 -> 校准外验证 -> 灵敏度 / 不确定性 -> 稳健性。数值模型再检查步长、网格、容差、初值与随机种子变化。

结果未超过基线不是代码故障；如实记录，并回到选模或结论阶段判断复杂模型是否值得保留。

7. 生成 Run Manifest

每次用于论文表图或结论的运行，按 ../_shared/code-reproducibility-checklist.md §7 的字段逐项记录；该节是 Run Manifest 的唯一 schema，包括运行状态 status 与测试记录 tests。无法取得某项时写 missing，不空口称可复现。

8. 交付与独立复核

交付代码变更、验证矩阵、运行清单、已知限制和未实现项。说明哪些代码由 AI 辅助生成，团队需要独立阅读数学映射、 重跑关键测试并确认竞赛规则允许的 AI 使用范围。

输出格式 / Output

## 实现合同
| 组件 | 对应 Q / M | 输入（单位 / 形状） | 输出 | 不变量 | 错误行为 | 测试 |

## 代码计划 / 已改文件
| 路径 / 模块 | 职责 | 改动 | 不改变的边界 |

## 验证矩阵
| T ID | 层级 | 输入 / 场景 | 预期 | 实际 | 状态 | 证据位置 |

## Run Manifest
<字段与 ../_shared/code-reproducibility-checklist.md §7 相同，以该节为准>
- run_id: R...
- status: not-run | failed | passed-with-warnings | passed
- code_revision:
- entry_command:
- environment:
- input_snapshots:
- configuration:
- random_seed:
- solver_and_tolerances:
- started_at:
- outputs:
- tests:
- warnings:
- supports_claims:

## 已知限制与未实现项
- <限制> —— 影响 <M / C IDs>，下一步 <动作>

## AI 辅助与团队复核
<生成 / 修改范围、已执行检查、仍需人工确认>

若宿主可以直接编辑文件，就实际做最小改动并运行检查；输出只总结，不把整份代码在对话中重复一遍。若不能写文件， 在非考核任务或规则明确允许完整 AI 实现时，可在聊天中返回完整候选代码与运行步骤；规则未明确的课程作业、 竞赛或评分项目只返回实现合同、伪代码、测试和对学生已有代码的局部补丁。没说明是否受评时按后者处理，并问一句。

## Next Handoff
- artifact_status:
- receiving_skill:
- accepted_items:
- provisional_items:
- blocking_items:
- next_action:

工具与跨 Agent 降级 / Tool fallback

• 有代码搜索、编辑和执行能力时遵循仓库本地约定，小步编辑后跑最窄测试，再跑端到端复现。
• 只有执行能力时提供补丁建议或脚本，不覆盖用户文件。
• 无执行能力时：非考核任务或规则明确允许完整 AI 实现时，给完整实现候选、测试、命令和预期；否则（受评任务规则 未明确或不允许，或没说明是否受评）只给实现合同、伪代码、测试与对学生已有代码的局部补丁。全部实际结果标 not-run。
• 无数据读取能力时实现 schema / 接口与 synthetic 小例，不声称适配真实数据。
• 无版本控制时用时间、文件清单和内容哈希的可用子集标识运行。
• 不依赖 Python、MATLAB、R 或某个 Agent 专有工具；优先项目现有、团队可运行的工具链。

边界 / Boundaries

• 不发明模型：方程、目标、约束或处理规则缺失时回退，不以代码默认值替学生作决定。
• 不虚构数据与结果：synthetic 测试夹具必须醒目标注，不能出现在经验结论中。
• 不硬编码论文答案：代码必须从登记输入计算输出；为“对上结果”写常数属于造假。
• 不静默修数据：删除、插补、裁剪、单位转换和约束修复都可追踪。
• 不把运行成功当验证：必须检查数学性质、基线和校准外证据。
• 不泄漏：最终验证数据不参与预处理拟合、特征选择、调参或模型选择。
• 不隐藏随机性与求解状态：种子、重复、容差、停止条件与警告随结果保存。
• 不借重构改变数学含义：含义变化先回写模型 / 假设契约并由使用者确认。
• 不替团队承担署名与规则责任：AI 辅助范围透明，提交前由团队独立复核和披露。
• 不代做受评实现：课程作业、评分实验、竞赛和其他受评任务先核对 AI 规则；未确认允许完整生成时， 限于实现合同、伪代码、测试与学生代码的局部调试，不交付可直接冒充本人完成的整套实现。

Token 控制 / Token discipline

• 从失败行为、入口或已有测试开始，定位直接控制路径，不先画整仓库地图
• 长数据只读 schema、摘要和最小失败样本；不把整表带入上下文
• 先实现一个可验证垂直路径，再扩展情景与图表
• 测试输出只保留失败摘要、关键诊断和运行清单，长日志写文件或压缩
• 后续修改只重读受影响组件、测试与下游产物

参考资料 / References

• ../_shared/modeling-work-contract.md —— 稳定 ID、状态与运行 / 图表交接
• ../_shared/validation-playbook.md —— 验证梯、泄漏、可辨识性与结论强度
• ../_shared/code-reproducibility-checklist.md —— 实现、数据、数值、测试检查表；§7 是 Run Manifest 的唯一 schema

变更记录 / Changelog

版本	日期	变更	类型
0.1.2	2026-09-26	不能写文件或无执行能力时按是否受评区分：受评或没说明时只给实现合同、伪代码、测试与局部补丁（共享契约 §5 同步）；Run Manifest 以 code-reproducibility-checklist §7 为唯一 schema，模板补 status 与 tests，共享契约的 R 行与运行状态改为引用该节；两条评估用例移入 tests/cases，删除 references/evaluation-cases.md	patch
0.1.1	2026-09-15	补充矛盾输入与受评任务边界违规评估用例	patch
0.1.0	2026-08-17	初始草稿：就绪门槛、实现合同、验证夹具、数据链、运行清单与跨工具降级	minor