Skip to content

CLAUDE.md

Latest commit

 

History

History
206 lines (176 loc) · 8.47 KB

CLAUDE.md

File metadata and controls

206 lines (176 loc) · 8.47 KB

CLAUDE.md

本文件用于指导 Claude Code 在本仓库中进行代码开发、修复和优化。

项目概述

AutoSolver-Evolve 是一个基于 LLM 驱动的求解器自动进化系统，用于求解"配送订单-骑手分配问题"。

核心思路：不让 LLM 直接求解，而是让 LLM 不断生成/改进求解器代码，由自动评测器打分，保留高分求解器，循环进化（AlphaEvolve 风格）。

常用命令

# 运行单次求解
python main.py solve eval_cases/small/sample.json --solver seed_solvers.local_search --time-limit 2

# 运行演化流程（dry-run 测试管线）
python main.py run --config configs/debug.yaml

# 运行演化流程（正式模式，需配置 LLM API key）
python main.py run --config configs/default.yaml

# 生成边界用例
python main.py gen-cases --output-dir eval_cases/generated

# 运行全部测试
python -m pytest -q

# 运行单类测试
python -m pytest tests/test_solver_interface.py -v

依赖安装：pip install -r requirements.txt（当前需 pytest, pyyaml, anthropic, openai）

项目架构

AutoSolver-Evolve/
├── autosolver/              # 共享基础库
│   ├── models.py            #   数据模型（Order, Rider, Instance, Solution, EvaluationResult）
│   ├── parser.py            #   JSON → Instance 解析
│   ├── validator.py         #   约束验证（容量、pair 存在性、重复检查）
│   ├── evaluator.py         #   评分（先验证再计算 accepted_count + total_score）
│   └── io.py                #   Solution → JSON 序列化
│
├── seed_solvers/            # 人工编写的种子求解器
│   ├── greedy_single.py     #   贪心：按 score 升序单次分配
│   ├── greedy_multi.py      #   贪心：支持 max_riders_per_order > 1
│   └── local_search.py      #   贪心初始化 + swap/insert/remove 局部搜索
│
├── generated_solvers/       # LLM 生成的求解器变体
│
├── evolve/                  # 演化框架
│   ├── controller.py        #   主循环编排器
│   ├── state.py             #   全局演化状态（SolverRecord, EvolutionState）
│   ├── planner.py           #   根据状态决定下一步行动（mutate/repair/switch/stop）
│   ├── observation.py       #   收集/汇总每轮观察数据
│   ├── reflector.py         #   反思分析（本地规则 + LLM 深度模式）
│   ├── model_router.py      #   按任务类型路由 LLM 模型（主模型 + 备选链）
│   ├── budget.py            #   时间/资源预算追踪
│   ├── baseline_guard.py    #   基线保护，防止求解质量严重退化
│   ├── artifact_manager.py  #   产物管理（prompts/日志/策略笔记）
│   ├── database.py          #   运行记录 JSONL 读写 + 排名查询
│   │
│   ├── prompt_sampler.py    #   提示词构造（加载模板 + 采样用例 + 填充变量）
│   ├── llm_mutator.py       #   LLM 变异器（生成/修复/验证三种模式）
│   ├── code_extractor.py    #   从 LLM 响应提取纯 Python 代码
│   ├── diff_applier.py      #   unified diff 应用 + generated_solvers/ 管理
│   ├── sandbox.py           #   子进程沙箱编译 + 执行（安全隔离）
│   ├── evaluator_pool.py    #   完整评测流程：编译→沙箱→验证→评估→汇总
│   │
│   ├── llm_clients/         #   LLM 客户端层
│   │   ├── base.py          #     抽象基类 + LLMResponse
│   │   ├── anthropic_client.py  # Anthropic Claude
│   │   ├── openai_client.py     # OpenAI / 兼容接口
│   │   ├── ollama_client.py     # 本地 Ollama
│   │   └── factory.py           # 工厂函数
│   │
│   └── prompts/             #   提示词模板（Markdown，支持 {{变量}} 替换）
│       ├── mutate_solver.md
│       ├── repair_compile_error.md
│       ├── repair_validation_error.md
│       ├── reflect_failures.md
│       └── summarize_best_solvers.md
│
├── case_generator/          # 用例生成器
│   ├── random_case.py       #   随机用例
│   └── edge_case.py         #   边界用例（空/完全连接/稀疏/容量不均衡/大方差）
│
├── configs/                 # YAML 配置文件
│   ├── debug.yaml           #   调试（dry-run, 小数据集, 3 代）
│   ├── default.yaml         #   默认（需 LLM, 10 代）
│   └── full_run.yaml        #   正式（20 代, 全部用例）
│
├── eval_cases/              # 评测用例
│   ├── small/               #   sample.json, sample_multi.json
│   ├── medium/              #   medium_01.json, medium_02.json
│   ├── large/
│   ├── stress/
│   └── generated/           #   自动生成的边界用例
│
├── results/                 # 实验记录
│   ├── runs.jsonl           #   运行记录
│   ├── prompts/             #   LLM 提示词存档
│   ├── logs/                #   逐代日志
│   └── strategy_notes.md    #   策略笔记
│
├── tests/
│   ├── test_solver_interface.py  # 对所有 seed_solver × 所有用例的参数化测试
│   ├── test_validator.py         # validator 各种非法输入
│   ├── test_evaluator.py         # evaluator + is_better 优先级逻辑
│   └── test_evolve_smoke.py      # 演化框架冒烟测试
│
└── main.py                 # CLI 入口（solve / run / gen-cases 三个子命令）

核心流程

seed solver 基线评测
        ↓
planner 决策（mutate / repair / switch / stop）
        ↓
选择 parent solver
        ↓
model_router 选择 LLM 模型
        ↓
prompt_sampler 构造提示词
        ↓
llm_mutator 调用 LLM 生成代码
        ↓
code_extractor 提取纯 Python 代码
        ↓
diff_applier 保存到 generated_solvers/
        ↓
sandbox 编译检查 + 子进程执行
        ↓
evaluator_pool 批量评测（验证 + 评估 + 汇总）
        ↓
baseline_guard 判断是否可接受
        ↓
database 记录 + artifact_manager 存档
        ↓
observation 生成报告 + reflector 分析
        ↓
planner 决定下一轮 / 终止

关键约束

求解器接口（所有求解器必须遵守）

def solve(instance: dict, time_limit: float) -> dict:
    """
    Args:
        instance: 问题实例，包含 orders, riders, pair_scores, max_riders_per_order, max_orders_per_rider
        time_limit: 时间限制（秒）
    Returns:
        {"assignments": [{"order_id": str, "rider_ids": [str]}]}
    """

评测目标（优先级）

  1. 最大化 accepted_count（分配订单数）
  2. 在订单数相同时，最小化 total_score（总分）
  3. is_better() 在 autosolver/models.py 是唯一比较标准

约束规则

  1. 每订单分配的骑手数 ≤ max_riders_per_order
  2. 每骑手分配的订单数 ≤ max_orders_per_rider
  3. 每个 (order_id, rider_id) 必须存在于 pair_scores
  4. 不允许重复分配（同一骑手不能分配两次给同一订单）

开发原则

  • 修改应小且集中；正确优先，再优化
  • 评测逻辑必须集中（autosolver/evaluator.py），不可在 solver 中重复实现
  • 新增 seed solver 时，注册到 evolve/controller.py 的 SEED_SOLVERS 列表
  • 新增启发式策略不能破坏已有 baseline 的可运行性
  • 所有 solver 比较必须通过统一 evaluator 完成
  • 不随意修改输入/输出格式和 validator 规则
  • 不要引入不必要的重型依赖
  • 如使用随机策略，必须固定随机种子或集中管理；沙箱执行必须能在子进程中独立运行
  • solver 不直接读写文件、不依赖交互输入、不修改全局状态

LLM 客户端使用

from evolve.llm_clients.factory import create_client
client = create_client({"provider": "anthropic", "model": "claude-sonnet-4-6"})
response = client.generate("系统提示词", "用户提示词")
print(response.content, response.usage)

支持的 provider：anthropic（需 ANTHROPIC_API_KEY 环境变量）、openai（需 OPENAI_API_KEY）、ollama（本地 http://localhost:11434/v1）

修改后验证

python -m pytest -q                          # 全部测试
python main.py solve eval_cases/small/sample.json --solver seed_solvers.local_search
python main.py run --config configs/debug.yaml   # 完整管线 dry-run