示例

OptAgent 的可运行示例单独维护在公开仓库，公开文档负责说明每类问题要表达的建模语义、代码目录结构、入口脚本和运行注意事项：

https://github.com/Dongbox/optagent-examples

完整可运行代码、示例专用测试和小型公开数据文件以 optagent-examples 为准。MkDocs 页面不再内嵌完整文件，但必须保留足够的问题说明和代码骨架，方便读者判断应该从哪个示例开始。

代码目录结构

optagent-examples 的主结构如下：

optagent-examples/
  examples/
    linear/          # 0/1 选择、指派、选址、线性化路由
    scheduling/      # job shop、flow shop、sequence/interval 调度
    blackbox/        # Python 黑盒评分、TSP、启发式搜索
    hybrid/          # 线性计划 + 调度变量 + 多阶段编排
    presets/         # 内置预设、自动预设、外部 preset 文件
    mps/             # MPS 文件导入、窗口模型重建、后端切换
    steel/           # 钢卷排序、焊接兼容性、搜索归因
    resource_flow/   # 资源流 CP/MILP 双建模与滚动窗口
    mg/              # SQLite 驱动的 MG 迁移示例
  tests/             # 示例回归测试
  scripts/           # 可重复实验脚本
  requirements-dev.txt
  pyproject.toml

运行入口统一从仓库根目录执行，常见形式为：

PYTHONPATH=. python examples/linear/knapsack_mathopt.py
PYTHONPATH=. python examples/scheduling/job_shop_small.py
PYTHONPATH=. python examples/blackbox/tsp_blackbox_small.py

示例分类

• 快速开始：最小建模、求解和结果读取闭环。
• 线性问题：MILP / MathOpt / HiGHS、指派、选址、MPS 相关入口。
• 调度问题：sequence_var、interval_var、no_overlap、precedence 和 CP-SAT。
• 黑盒优化：external_call、Python 评分函数、TSP 和序列启发式。
• 混合优化：同一 DAG 中组合线性数量、区间调度、启发式和精确阶段。
• 预设示例：内置策略预设、自动预设选择和外部 preset 文件。
• MPS 示例：从 MPS 数据重建模型、比较 heuristic / hybrid / exact 路径。
• 钢卷排序：直接焊接兼容性、DAG 路径模型和搜索归因。
• 资源流：资源网络流转、CP/MILP 两种 formulation 和滚动窗口。
• MG 迁移：APS 兼容 SQLite 数据流、黑盒规则评分和生产输出表。

仓库边界

核心实现、内部文档和核心测试保留在主仓库。公开 optagent-examples 仓库承载可运行样例，并应满足：

• 每个样例有独立 README
• README 写明依赖安装、运行命令和预期输出
• 测试数据只使用可公开的小型 SQLite、JSON、CSV、MPS 等文件
• 不包含私有业务数据、内部绝对路径或内部系统链接

运行注意事项

• 通用示例使用当前 OptAgent 支持的 Python 版本和公开/批准的 OptAgent 安装包。
• 精确求解示例可能需要 ortools 或 highspy。
• MG 示例需要 Python 3.9，并且需要额外安装管理员提供的 APS wheel；该 wheel 不随公开仓库分发。
• 迁移型比较脚本如果依赖外部系统或历史工程，只用于迁移验证，不作为默认公开运行路径。