# MIP-coder

面向混合整数规划（MIP）的 **研究—编程—求解评测** 协作原型。通过 MCP 连接外部 agent，通过 skill 提供方法参考，由 COPT 执行求解并返回可核查的实验反馈。

**版本 0.11.0 · 工程原型。** 已验证真实求解和工具执行链路，尚未证明真实 LLM 自主研发的性能收益。三个角色不等同于三个已经完成自主协作验证的 LLM。

## 研究动机与架构

受 auto-research 的“提出假设—实现—实验—修订”范式启发，项目探索如何把算法研发与 MIP 求解状态连接起来。[LLM4MIP](https://llm4mip.github.io/skill/) 的 primal/dual skill 对照结果为经验跨实例复用提供了积极依据，但不等于本系统的泛化或性能已经得到验证。

```text
人的 idea / 研究 agent
        ↓ 结构化假设、适用条件、实验方案
研究协调器 ──MCP──→ 编程 agent
        ↑                 ↓ 候选代码与冻结快照
        └──实验反馈── 求解评测宿主 + COPT
                          ↓
                 预算、验解、配对比较、日志
```

- **研究角色**：提出与筛选方向，读取实验反馈，决定修复、扩展或终止。
- **编程角色**：实现候选策略，接受语法、接口和运行反馈。
- **求解评测角色**：执行 COPT、校验完整解、计量预算并生成报告；当前主要由确定性程序承担。
- **人与 agent 的交互**：本地聊天工作台支持讨论、草稿、人工审阅、不可变归档与 MCP 递交。

接下来重点研究：根据当前求解状态决定何时调用何种算子，以及如何在不同算子、辅助求解和研发尝试之间分配有限预算。性能需要在相同预算下与原生求解器和空策略对照验证。

## 当前能力与边界

| 能力 | 状态 |
| --- | --- |
| 通用 MCP 接口、讨论与 idea 归档 | 已实现；外部客户端可选自己的模型 |
| 研究任务、后台编程、版本快照与实验反馈 | 已用离线模型回复及真实 COPT 验证 |
| v1 完整原始解策略 | 支持 START / MIPRELAX，独立验解后提交 |
| v2 连续补全和辅助 MIP | 独立工程实验可用；默认关闭，需要显式预算 |
| 正式研究中的 v2 | 尚未接入；研究/R1 仍采用冻结的 v1 契约 |
| 真实 LLM 多轮自主研发 | 尚未完成验证，当前不宣称已发现新算法 |
| 自定义割、分支或对偶证书接口 | 尚未开放 |

v2 支持固定全部整数变量后的 LP 连续补全，以及固定部分变量或限制二进制 Hamming 距离的受限 MIP。宿主在独立单线程进程中重建模型，对返回向量检查原模型和受限模型；子问题的界与最优/不可行状态不会冒充原模型的全局证明。

启动、复制、序列化、辅助求解和验解开销都计入任务。提供调用次数、累计时间和单次时间限制，外层硬超时回收进程树。进程隔离用于生命周期管理，不是操作系统安全沙箱；当前无内存配额。

## 安装与快速开始

Python 3.11+；目前完整本地验证环境为 Windows、Python 3.13、COPT 8.0.7。

```sh
git clone https://github.com/leeskywalker060726-star/MIP-coder.git
cd MIP-coder
python -m venv .venv
```

激活环境：Windows PowerShell 使用 `.\.venv\Scripts\Activate.ps1`，Linux/macOS 使用 `source .venv/bin/activate`。

```sh
python -m pip install -e ".[mcp,research]"
python -m mip_coder demo
python -m mip_coder workbench
```

工作台地址为 `http://127.0.0.1:8765`。`demo` 使用确定性离线回复验证工具循环，不调用 LLM 或求解器。未配置讨论模型时，工作台支持手动讨论和外部 MCP agent 接入。

需要真实求解时：

```sh
python -m pip install -e ".[copt,mcp,research]"
python -m mip_coder doctor
python scripts/check_copt_installation.py
python -m mip_coder.auxiliary_demo
```

请自行按 [COPT 官方说明](https://guide.coap.online/copt/en-doc/pythoninterface.html) 配置许可证。`doctor` 不申请许可证；安装检查与演练会执行真实求解。仓库不包含任何个人许可证或求解器二进制。

## MCP、skill 与模型

```sh
python -m mip_coder mcp --workspace /absolute/path/to/MIP-coder --profile research
python -m mip_coder mcp --workspace /absolute/path/to/MIP-coder --profile coding
python -m mip_coder mcp --workspace /absolute/path/to/MIP-coder --profile workbench
```

路径替换成自己的项目绝对路径。客户端配置示例在 [configs](configs)；其中示例路径也需要替换。工作台讨论不会自动启动研究或求解。

- `get_algorithm_reference`：读取 12 张带来源的方法卡；方法卡不是 12 个已实现算法。
- `get_primal_template`：读取 v1 基线或实验性 v2 的 `auxiliary_portfolio`。
- `load_skill`：按需加载 [mip-coding](mip_coder/skills/mip-coding/SKILL.md) 或 [mip-research](mip_coder/skills/mip-research/SKILL.md)。
- 研究 MCP 负责结构化任务与反馈；编程 MCP 提供代码、检查和实验工具。

内置模型 provider 当前为 Anthropic Messages，真实配置参考 [coding_profiles.example.json](configs/coding_profiles.example.json)。凭据只通过宿主环境变量引用。兼容任意 MCP 客户端不代表内置 provider 已支持所有模型 API；OpenAI 格式适配尚待完成。源码测试中的本地 HTTP 模拟服务也不代表真实模型已接通。

## v2 演练与验证记录

```sh
python -m mip_coder check-candidate mip_coder/policies/auxiliary_portfolio.py --allow-auxiliary
python -m mip_coder.auxiliary_demo
```

演练生成 3 个小模型，运行 native、policy_noop、candidate，共 9 次求解。无需下载外部数据。输出在本地 `.mip-coder/latest-auxiliary-demo.json`，每次运行保存源码、请求、结果及辅助求解记录。

[公开验证摘要](release/verification-v0.11.0.json)：

- 本地完整回归 164 项测试通过。
- 9 次真实 COPT 求解均为 OPTIMAL，最终目标值与两种对照相同。
- 4 次辅助调用，包含主求解回调中的邻域求解。
- 候选耗时约为原生 COPT 的 1.64 倍、空策略的 1.76 倍；这是工程验证，没有加速结论。
- 使用手写策略，外部 LLM 调用为 0。

公开摘要剔除了本机路径和私有运行存储；可通过演练脚本重新生成自己的完整记录。GitHub CI 只执行不需要商业许可证的核心测试；完整测试需要本地 COPT 环境：

```sh
python -m unittest discover -s tests -v
```

## 数据与评测协议

仓库仅提供实例来源、哈希和划分清单，以及人工生成的协议输入；不分发下载的 MIPLIB 模型、解或私有实验结果。下载和恢复脚本为 `scripts/prepare_miplib_smoke.py`、`scripts/prepare_research_data.py`。

研究流程冻结数据、代码、宿主和预算；开发、验证、测试分离。失败和负结果保留。旧会话遇到宿主哈希变化时不能直接沿用旧分数继续评测。历史状态文档中的 `.mip-coder/` 链接指向本地记录，不随源码发布。

## 文档与来源

- [工作台](WORKBENCH.md)、[COPT 接口](COPT_INTEGRATION.md)
- [研究设计](RESEARCH_DESIGN.md)、[R2 评测流程](R2_STATUS.md)、[R3 启动准备](R3_STATUS.md)
- [策略与状态路由](PRIMAL_STATUS.md)、[报告和导出](REPORTING_STATUS.md)
- [上游机制对应关系](UPSTREAM.md)、[第三方声明](THIRD_PARTY_NOTICES.md)

执行循环与会话机制参考固定版本的 `ultraworkers/claw-code`，可运行层为本项目的 Python 适配；不宣称这是 Anthropic 官方源码，也不分发完整上游或本地 Rust 原文摘录。方法库参考 LLM4MIP skills，保留来源与许可；上游成绩不能当作本项目成绩。

原始项目贡献采用 [MIT License](LICENSE)。第三方材料保留各自声明，COPT 及外部依赖按其自身许可使用。