Solver Iteration Lab

这个 skill 用于把“面向评测器迭代 solver”的过程变成可审计、可复盘、可复用的工程循环。它适合 FunSearch 类任务、竞赛题、算法 benchmark、启发式优化、代码生成评测、自动调参、排行榜冲分等场景。

核心原则：先保证评分器可信，再优化 solver。每一次 solver 修改都必须有明确假设、可回滚快照、评测证据和复盘记录。

启动检查

开始前先确认以下信息。原因是迭代系统的质量由评测目标、权限边界和记录协议共同决定。

任何新自迭代任务都先输出一个启动清单。即使用户没有主动提到 token，也必须把 token 预算和每轮 token 粗估列为待确认项或给出默认建议。原因是自迭代任务容易在多轮评测、长日志分析和 subagent 分工中快速扩大成本。

1. 评分器状态
   - 用户是否已有评分器、测试集、样例输入输出或 leaderboard 脚本？
   - 若没有，优先协助用户构建或完善评分器，而不是直接写 solver。
   - 确认指标目标：用户想达到什么效果、目标值是多少、最低可接受阈值是多少。
   - 确认分数方向：越大越好、越小越好，或多指标权衡。
   - 确认中断条件：达到目标值、达到可接受阈值、超过成本预算、连续无提升或用户审核暂停。
   - 确认评测是否稳定：是否有随机性、时间波动、外部依赖或隐藏状态。

2. 文件权限
   - 明确哪些文件允许修改，通常只允许修改 solver 或指定模块。
   - 默认把评分器、测试集、benchmark 数据视为只读。
   - 只有用户明确允许时，才修改评分器；修改前必须说明原因。

3. 运行模式
   - 人工审核模式：每轮或每 N 轮暂停，让用户查看决策、diff、分数和复盘。
   - 沙箱自治模式：在限定目录、命令、轮数、时间和可写文件后自由迭代。
   - 混合模式：默认推荐。连续运行若干轮，遇到破纪录、大重构、评分器异常或长期无提升时请求用户审核。

4. 预算和停止条件
   - 确认最大轮数、最大时间、单轮超时、目标分数、最低可接受分数和连续无提升阈值。
   - 确认 token 预算。若用户没有 token 感知，先给粗略建议：轻量文本评测约 5k-15k tokens/轮；中等代码修改和复盘约 15k-40k tokens/轮；复杂多文件改动、subagent 分工或长日志分析约 40k-100k+ tokens/轮。
   - 根据 token 预算反推建议轮数。例如 300k tokens 适合约 8-15 轮中等复杂迭代，或 3-6 轮带 subagent 的复杂迭代。
   - 默认连续 3 轮无提升时更换策略族，连续 5 轮无提升时进入策略重构模式。
   - 默认达到用户目标指标、评分器异常、结果不可重复、权限不清、token 预算接近耗尽或评测成本异常时暂停。

5. 是否使用 subagent
   - 简单任务先用单 Agent 跑通闭环。
   - 复杂任务可拆分为 Planner、Executor、Evaluator、Reviewer 和 Diversity Explorer。
   - subagent 的写入范围必须互不冲突，Executor 默认只改 solver。

6. 跨平台约束
   - 默认支持 Windows、Linux 和 macOS。
   - 脚本优先使用 Python 标准库和 pathlib，不要依赖 Bash、PowerShell 或某个平台的路径写法。
   - 命令示例同时考虑 PowerShell 与 POSIX shell；复杂 JSON 输入优先使用文件，而不是在命令行内手写转义。
   - 评测命令如果需要长期自动运行，优先保存为 argv 数组或项目已有脚本入口，减少 shell 差异。
   - 不要写死 /tmp、rm、cp、nohup、kill、open、xdg-open 等平台相关命令；需要时给出等价替代或用 Python 实现。

工程目录

在目标项目根目录创建 .funsearch-runs/。原因是所有迭代证据必须集中存放，便于恢复、审计和复用。

.funsearch-runs/
  config.json
  current_state.md
  best_summary.md
  active_strategy.md
  context_pack.md
  leaderboard.jsonl
  strategy_bank.jsonl
  wins.jsonl
  failures.jsonl
  observations.jsonl
  iteration-0001/
    decision.md
    solver_snapshot/
    patch.diff
    evaluation_stdout.txt
    evaluation_stderr.txt
    metrics.json
    retrospective.md

参考 references/artifact_schema.md 查看字段定义。使用 scripts/init_lab.py 初始化目录，使用 scripts/build_context_pack.py 生成每轮决策上下文。

跨平台初始化示例：

python scripts\init_lab.py --project-root . --project-name my-project --evaluation-command "python evaluate.py" --evaluation-arg python --evaluation-arg evaluate.py --solver-path solver.py

python scripts/init_lab.py --project-root . --project-name my-project --evaluation-command "python evaluate.py" --evaluation-arg python --evaluation-arg evaluate.py --solver-path solver.py

每轮循环

每一轮都按这个顺序执行。原因是先决策、再修改、再评测、再复盘，才能让结果可解释。

1. 读取状态
   - 读取 .funsearch-runs/current_state.md
   - 读取 .funsearch-runs/best_summary.md
   - 查看 .funsearch-runs/leaderboard.jsonl 的近期趋势
   - 运行 scripts/build_context_pack.py 生成或刷新 .funsearch-runs/context_pack.md

2. 检索经验
   - 从 strategy_bank.jsonl 找到与当前失败原因或策略标签相关的记录。
   - 从 failures.jsonl 找到相似失败，避免重复尝试。
   - 从 wins.jsonl 找到可复用的成功模式。

3. 写入本轮决策
   - 在 iteration-N/decision.md 记录本轮假设、选择原因、预期收益、风险和回退条件。
   - 如果连续无提升达到阈值，必须切换策略族，而不是继续微调。

4. 修改 solver
   - 只修改允许的 solver 文件。
   - 优先使用项目已有库、成熟算法和现有组件，非必要不手动造轮子。
   - 修改后保存 solver 快照和 diff。

5. 运行评测
   - 使用用户确认的评测命令。
   - 优先通过项目已有命令运行，例如 python evaluate.py、pytest、npm test 或 cargo test。
   - 若评测命令包含复杂 shell 语法，先询问用户是否可以改为跨平台脚本入口。
   - 记录 stdout、stderr、退出码、耗时和结构化指标。
   - 如果评测失败，先判断是代码错误、环境错误、评分器错误还是目标理解错误。

6. 复盘结果
   - 在 retrospective.md 写清楚分数变化、证据、原因分析和下一步建议。
   - 更新 leaderboard.jsonl、strategy_bank.jsonl、wins.jsonl 或 failures.jsonl。
   - 若产生新最好结果，更新 best_summary.md 并保留对应快照。

策略切换规则

策略切换用于避免陷入局部最优。原因是连续小改但无提升，通常说明当前假设空间已经耗尽。

默认规则：

• 连续 3 轮无提升：停止当前策略族，选择不同策略类型。
• 连续 5 轮无提升：做一次策略重构，重新分析评分器、case 分布和历史经验。
• 连续失败原因相同：先增强诊断或修复边界理解，再继续优化。
• 分数退化但发现有价值 insight：记录经验，不保留为 best。

可选策略族：

• exploit-current-best：沿当前最好方案做小改。
• algorithm-replacement：换算法范式，例如贪心、动态规划、搜索、局部搜索、启发式。
• ablation-simplify：删除复杂逻辑，验证是否过拟合或引入噪音。
• case-error-analysis：按 case 分类找退化来源。
• performance-pass：优先降低时间或内存。
• hybrid-combine：组合两个已知有效策略。
• diversity-jump：刻意尝试与当前路线差异较大的方案。

经验复用

默认采用 Markdown + JSONL + 标签检索，不默认引入向量数据库。原因是这种方式简单、可审计、可跨语言使用，适合多数项目。

每轮决策前，先生成 context_pack.md，只把当前最相关的经验放入上下文。不要把全部历史无差别塞进上下文，因为旧噪音会稀释当前判断。

当策略记录超过 200 条、需要跨项目复用，或同类经验难以用标签检索时，再建议升级为成熟检索方案，例如 SQLite FTS、LanceDB、Chroma 或 FAISS。

追加复杂经验记录时，优先把 JSON 写入临时文件，然后用 --record-file。原因是 Windows PowerShell、cmd、Bash 和 zsh 对引号的处理不同，命令行内直接传 JSON 容易损坏。

python scripts\append_experience.py --project-root . --kind observation --record-file .funsearch-runs\new_observation.json

python scripts/append_experience.py --project-root . --kind observation --record-file .funsearch-runs/new_observation.json

经验写入要求：

• 成功经验写入 wins.jsonl，包含适用条件和复用建议。
• 失败经验写入 failures.jsonl，包含失败原因和避免重复的提示。
• 中性观察写入 observations.jsonl，例如 case 分布、评分器特性、性能瓶颈。
• 所有策略尝试写入 strategy_bank.jsonl，即使失败也要记录。

subagent 分工

仅当用户允许 subagent 模式，或任务复杂到单 Agent 难以稳定推进时使用。原因是并行能提升探索效率，但会增加协调成本。

• Planner：读取历史和 context_pack，提出下一轮策略。
• Executor：执行代码改动，只写允许的 solver 文件。
• Evaluator：运行评测，抽取指标，判断结果是否可信。
• Reviewer：复盘成功或失败原因，更新经验库。
• Diversity Explorer：提出与当前主线不同的候选策略，防止局部最优。

并行写代码时必须声明文件所有权。不要让多个 agent 同时修改同一个 solver 文件，除非主 Agent 明确负责合并。

人工审核点

在以下情况暂停并向用户汇报。原因是这些情况可能改变目标、成本或风险。

• 需要修改评分器或测试集。
• 需要扩大可写文件范围。
• 计划进行大规模重构。
• 评测结果不可重复或分数异常跳变。
• 连续多轮无提升，需要切换到完全不同的策略。
• 发现当前评分器可能与用户真实目标不一致。
• 沙箱预算即将耗尽。

输出格式

向用户汇报时保持简洁，但必须包含：

• 启动清单：评分器状态、目标指标/目标值、权限边界、运行模式、轮数/时间/token 预算。
• 当前最好分数和对应轮次。
• 当前指标距离目标值还有多少。
• 已用预算和剩余预算，包括时间、轮数和 token 粗估。
• 本轮决策原因。
• 本轮改动摘要。
• 评测结果和是否可信。
• 成功/失败复盘。
• 下一步策略。

不要只报告“跑完了”或“失败了”。每次迭代都要让后续决策获得信息。