feat-implementation

为向科学、数值计算、机器学习、仿真、数据处理或研究代码库添加功能制定严格的实施计划。当用户要求 Codex 规划编码代理如何实现某项功能时，使用此计划，尤其是在需要涵盖数学细节、受影响文件、分步实现、验证实验（如过拟合测试）、版本控制检查点以及对执行代理的严格规则的情况下。 1. **需求分析与数学建模** - 明确功能目标：清晰定义新功能在科学或工程背景下的用途（例如：引入新的正则化方法、扩展仿真边界条件、增加数据预处理步骤等）。 - 数学形式化：以数学公式精确描述新功能的核心算法（如梯度更新规则、损失函数修改、微分方程离散化方案等），确保与现有理论框架一致。 - 输入/输出规范：定义新功能的输入数据结构（张量维度、数据类型、单位等）和输出格式，确保与上下游模块兼容。 2. **影响范围评估** - 识别受影响的文件：列出所有将被修改或新增的源代码文件（如 `src/models/neural_net.py`、`utils/data_loader.py`、`tests/test_regularization.py`）。 - 依赖分析：检查新功能对第三方库（如 NumPy、PyTorch、SciPy）的版本要求，确保不破坏现有依赖。 - API 变更评估：若涉及公共接口变更，需记录旧接口的弃用策略和新接口的向后兼容性处理。 3. **分步实施步骤** - 步骤 1：创建功能分支（如 `feature/new-regularization`），基于最新主分支（`main`）检出。 - 步骤 2：实现核心算法模块，严格遵循数学公式，添加详细注释说明每行代码对应的数学操作。 - 步骤 3：编写单元测试，覆盖边界条件（如零输入、极端参数值）、数值稳定性（如浮点溢出）和梯度正确性（使用 `torch.autograd.gradcheck` 或 `numpy.testing.assert_allclose`）。 - 步骤 4：集成到主流程，确保数据流正确衔接（如训练循环中调用新模块）。 - 步骤 5：更新文档（如 docstring、README、API 文档），说明使用方法和理论依据。 4. **验证实验设计** - 过拟合测试：在小型合成数据集上训练模型，验证新功能是否能有效控制过拟合（如训练损失下降但验证损失上升时，正则化应抑制参数增长）。 - 数值一致性检验：对比新功能输出与解析解或参考实现（如 MATLAB 脚本）的差异，误差应小于 `1e-6`。 - 消融实验：在基准任务上对比“启用/禁用新功能”的性能差异（如准确率、收敛速度），确保改进具有统计显著性（p < 0.05）。 - 梯度检验：对可微模块进行梯度数值检验，确保反向传播正确。 5. **版本控制检查点** - 提交 1：初始实现（含核心算法和基础测试），消息格式：`feat: add L2-Spectral regularization module` - 提交 2：集成与接口更新，消息格式：`integrate: connect regularization to training loop` - 提交 3：测试增强与文档更新，消息格式：`test: add overfit and gradient checks; docs: update API reference` - 每次提交前运行 `pytest` 和 `mypy`，确保无回归错误。 6. **执行代理严格规则** - 禁止直接修改主分支；所有变更必须通过 Pull Request 审查。 - 所有数学表达式必须与论文或技术文档一致，偏差需显式标注并说明理由。 - 新增代码必须达到 90% 以上测试覆盖率（由 `coverage.py` 报告）。 - 禁止使用 `assert False` 或 `pass` 占位；未实现部分应抛出 `NotImplementedError` 并附带 TODO 注释。 - 所有实验结果必须可复现：固定随机种子（如 `np.random.seed(42)`），记录超参数和环境版本（通过 `pip freeze > requirements.txt`）。 7. **交付物** - 完整的功能实现代码 - 通过的测试套件 - 验证实验报告（含图表与统计结果） - 更新的文档与 API 说明 - 合并到主分支的 Pull Request，附带审查意见响应记录

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本