模块分层

OptAgent 的模块分为 7 层，每层有明确的职责边界和接口契约。

分层架构

graph LR
    subgraph L1 ["Layer 1: Modeling"]
        A1[Builder API]
        A2[ProgramSpec]
    end

    subgraph L2 ["Layer 2: DAG IR"]
        B1[Graph]
        B2[Evaluation]
        B3[Serialization]
    end

    subgraph L3 ["Layer 3: Analyzer"]
        C1[Decomposer]
        C2[Rule Engine]
        C3[Plan Builder]
    end

    subgraph L4 ["Layer 4: Strategy"]
        D1[Feature Extractor]
        D2[Preset Registry]
        D3[Recommendation]
    end

    subgraph L5 ["Layer 5: Orchestrator"]
        E1[Phase Executor]
        E2[State Manager]
        E3[Fallback]
    end

    subgraph L6 ["Layer 6: Solvers"]
        F1[Heuristic]
        F2[Exact]
        F3[Hybrid]
    end

    subgraph L7 ["Layer 7: Output"]
        G1[Solution]
        G2[Report]
        G3[Visualize]
    end

    A1 --> A2 --> B1
    B1 --> C1 --> D1
    D1 --> E1 --> F1
    F1 --> G1

各层详细说明

Layer 1: Modeling

用户通过 Builder API 描述优化问题，生成 ProgramSpec。

from optagent import Model

model = Model()
x = model.add_vars(5, name="x", lb=0, ub=10)
model.add_constraint(sum(x) <= 20)
model.minimize(sum(x))
spec = model.build()

Layer 2: DAG IR

ProgramSpec 被转换为 DAG（有向无环图）中间表示，包含：

• 节点（Node）：决策变量、约束、目标函数
• 边（Edge）：依赖关系
• 属性（Attribute）：类型信息、元数据

Layer 3: Analyzer

分析器读取 DAG IR，执行：

1. 问题特征提取：变量类型、约束结构、目标函数形式
2. 问题分解：识别可独立求解的子问题
3. 结构规则匹配：匹配已知问题模式（如调度、路由）

Layer 4: Strategy Recommendation

基于分析结果推荐求解策略：

特征	推荐策略
纯整数线性	MILP / CP-SAT
大规模组合	启发式 / 进化算法
调度问题	禁忌搜索 + 修复
黑盒目标	进化策略 + 局部搜索

Layer 5: Orchestrator

编排器管理多阶段求解流程：

• 阶段编排：按预算分配执行多个求解阶段
• 热启动继承：前一阶段的解作为后一阶段的初始解
• 状态合并：合并多个并行求解器的状态
• 回退机制：主策略失败时自动切换备选策略

Layer 6: Solvers

三类求解器：

HeuristicExactHybrid

• 禁忌搜索（Tabu Search）
• 局部搜索（Local Search）
• 模拟退火（Simulated Annealing）
• 大邻域搜索（LNS）

• CP-SAT（约束规划）
• MILP（混合整数线性规划）

• 进化算法 + 精确修复
• 记忆算法（Memetic）
• 并行组合（Portfolio）

Layer 7: Output

统一的输出层：

• Solution 对象：统一的求解结果接口
• Report：文本格式的求解报告
• Visualize：图表可视化（甘特图、收敛曲线等）