Modeling Code Builder

---
name: modeling-code-builder
description: 当使用者说“按我的模型写代码”“把方程实现成 Python/MATLAB/R”“调试这段建模代码”“补验证和灵敏度分析”“让结果可复现”时使用。只实现学生已确认的模型与数据契约，先写实现合同、手算小例、不变量和验收矩阵，再按读取、变换、求解、验证、敏感性与导出拆分；执行后记录输入快照、种子、环境、求解设置和输出，不静默修数据、不硬编码结果、不替学生发明模型或伪造数据。
category: modeling/implementation
version: 0.1.2
status: draft
priority: P0
compatible_agents:
  - claude-code
  - codex
  - cursor
  - codebuddy
  - nestudy
  - generic-llm-agent
display_name: 建模代码助手
outputs:
  - chat
max_rounds: 40
suggest_hint: 模型和方程定了？用「建模代码助手」把它实现成有小例验证、运行清单和可重建结果的代码
---

# 建模代码助手 / 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

```markdown
## 实现合同
| 组件 | 对应 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 实现时，可在聊天中返回完整候选代码与运行步骤；规则未明确的课程作业、
竞赛或评分项目只返回实现合同、伪代码、测试和对学生已有代码的局部补丁。没说明是否受评时按后者处理，并问一句。

```markdown
## 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 |