Darwinian Evolver
借助 Imbue 的进化循环来进化 prompt、regex、SQL 或代码。
Skill 元数据
| 来源 | Optional(可选)— 使用 kopi skills install official/research/darwinian-evolver 安装 |
| 路径 | optional-skills/research/darwinian-evolver |
| 版本 | 0.1.0 |
| 作者 | Bihruze (Asahi0x), KOPI AI AGENT |
| 许可证 | MIT |
| 平台 | linux, macos |
| 标签 | evolution, optimization, prompt-engineering, research |
| 相关 skill | arxiv, jupyter-live-kernel |
参考:完整的 SKILL.md
以下是当该 skill 被触发时 Kopi Agent 加载的完整 skill 定义。这就是 skill 处于激活状态时 agent 所看到的指令。
Darwinian Evolver
运行 Imbue 的 darwinian_evolver —— 一个由 LLM 驱动的进化搜索循环 —— 针对某个 fitness function(适应度函数)来优化 prompt、regex、SQL 查询或一小段代码。
状态:这是对上游工具的轻量封装(thin wrapper)。该 skill 负责安装它,引导 agent 编写一个 Problem 定义(organism(有机体)+ evaluator(评估器)+ mutator(变异器)),并通过上游 CLI 或一个小型自定义 Python driver 来驱动该循环。
许可证: 上游工具采用 AGPL-3.0。该 skill 只会通过上游 CLI 或一次 subprocess/uv run 调用来使用它(仅属聚合)。请不要将上游的类导入到 Kopi Agent 本身中。
何时使用
- 用户说"优化这个 prompt"、"为 X 进化一个 regex"、"自动改进这段代码/SQL"、"搜索更好的指令"。
- 你已经有一个 scorer(打分器)(精确匹配、regex 通过率、单元测试、LLM-judge、运行时指标)并且有一个起始候选(organism)。如果你还没有 scorer,请停下来先定义一个 —— 那才是最困难的部分。
- 成本可以接受:一次典型运行会调用 50–500 次 LLM。在 gpt-4o-mini 上这只需几美分;在 Claude Sonnet 上可能需要几美元。
不要在以下情况使用:
- 优化目标是可微的(请使用梯度下降 / DSPy)。
- 你只需要尝试 2–3 个变体 —— 直接手写即可。
- fitness 信号完全是主观的,没有任何可衡量的标准。
前置条件
- Python ≥3.11
git、uv(或pip)OPENROUTER_API_KEY、ANTHROPIC_API_KEY或OPENAI_API_KEY之一
该 skill 附带一个小型的 parrot_openrouter.py driver,它通过 OpenAI SDK 使用 OPENROUTER_API_KEY,因此 OpenRouter 上的任何 model 都可以使用。上游 CLI 本身硬编码了 Anthropic,需要 ANTHROPIC_API_KEY。
安装(一次性)
通过 terminal 工具运行:
mkdir -p ~/.kopi/cache/darwinian-evolver && cd ~/.kopi/cache/darwinian-evolver
[ -d darwinian_evolver ] || git clone --depth 1 https://github.com/imbue-ai/darwinian_evolver.git
cd darwinian_evolver && uv sync
验证:
cd ~/.kopi/cache/darwinian-evolver/darwinian_evolver \
&& uv run darwinian_evolver --help | head -5
快速上手 —— 内置的 Parrot 示例
一个很小的冒烟测试(需要 ANTHROPIC_API_KEY):
cd ~/.kopi/cache/darwinian-evolver/darwinian_evolver
uv run darwinian_evolver parrot \
--num_iterations 2 \
--num_parents_per_iteration 2 \
--mutator_concurrency 2 --evaluator_concurrency 2 \
--output_dir /tmp/parrot_demo
输出:
/tmp/parrot_demo/snapshots/iteration_N.pkl—— 每次迭代的 pickle 化 population(种群)/tmp/parrot_demo/<jsonl>—— 每次迭代的 JSON 日志(路径会在最后打印出来)
在浏览器中打开 ~/.kopi/cache/darwinian-evolver/darwinian_evolver/darwinian_evolver/lineage_visualizer.html,并加载该 JSON 日志即可查看进化树。
快速上手 —— OpenRouter Driver(无需 Anthropic Key)
该 skill 附带了 scripts/parrot_openrouter.py —— 同样的 parrot 问题,但 LLM 调用会通过 OpenRouter,因此任何 provider(服务提供商)都可以使用。
# From wherever the skill is installed:
SKILL_DIR=~/.kopi/skills/research/darwinian-evolver
DE_DIR=~/.kopi/cache/darwinian-evolver/darwinian_evolver
cd "$DE_DIR" && \
EVOLVER_MODEL='openai/gpt-4o-mini' \
uv run --with openai python "$SKILL_DIR/scripts/parrot_openrouter.py" \
--num_iterations 3 --num_parents_per_iteration 2 \
--output_dir /tmp/parrot_or
用 scripts/show_snapshot.py 检查结果:
uv run --with openai python "$SKILL_DIR/scripts/show_snapshot.py" \
/tmp/parrot_or/snapshots/iteration_3.pkl
预期输出:7 个进化后的 prompt 模板按分数排序,其中最好的大约落在 0.6–0.8(种子 Say {{ phrase }} 得分为 0.000)。
定义自定义问题
该 skill 附带了 templates/custom_problem_template.py —— 复制、编辑、运行。
有三件事你必须定义:
-
Organism—— 一个 PydanticBaseModel子类,用于承载被进化的产物(prompt_template: str、regex_pattern: str、sql_query: str、code_block: str等)。添加一个run(*args)方法来执行它。 -
Evaluator——.evaluate(organism) -> EvaluationResult(score=..., trainable_failure_cases=[...], holdout_failure_cases=[...], is_viable=True)。score位于[0, 1]中。数值越高越好。trainable_failure_cases—— mutator 所能看到的内容。要包含足够的上下文(input(输入)、expected(期望)、actual(实际)),以便 LLM 进行诊断。holdout_failure_cases—— 不让 mutator 看到。用它们来检测过拟合。- 除非 organism 完全坏掉(抛出异常、返回 None 等),否则
is_viable=True。一个得分为 0 但仍然可用的 organism 是完全可以的 —— 它只是在父代选择时会被降权。
-
Mutator——.mutate(organism, failure_cases, learning_log_entries) -> list[Organism]。 通常做法是:构建一个 LLM prompt,其中包含当前 organism + 一个失败用例 + 一个请求让其提出修复方案;解析 LLM 的响应;返回一个新的Organism。解析失败时返回[]—— 循环会处理这种情况。
然后编写一个 driver 脚本,把 Problem(initial_organism, evaluator, [mutators]) 接入 EvolveProblemLoop,并对 loop.run(num_iterations=N) 进行迭代 —— 附带的 scripts/parrot_openrouter.py 就是参考实现。
真正重要的超参数
| flag | 默认值 | 何时调整 |
|---|---|---|
--num_iterations | 5 | 当你信任 evaluator 后,提升到 10–20 |
--num_parents_per_iteration | 4 | 为了低成本探索,降到 2 |
--mutator_concurrency | 10 | 为避免速率限制,降到 2–4 |
--evaluator_concurrency | 10 | 同上;evaluator 也会调用 LLM |
--batch_size | 1 | 当你的 mutator 能处理多个失败用例后,提升到 3–5 |
--verify_mutations | 关闭 | 当 mutator 浪费较大时打开(据 Imbue 所述,后续运行可节省 >10 倍成本) |
--midpoint_score | p75 | 除非分数过于集中,否则保持不变 |
--sharpness | 10 | 保持不变 |
注意事项
Initial organism must be viable—— 即使 seed 的得分为 0,也要在你的EvaluationResult中设置is_viable=True。该循环会拒绝不可存活的 organism,因为这意味着循环没有可供演化的起点。- Provider 内容过滤器会中断运行。 由 Azure 托管的 OpenRouter 模型
会拒绝诸如 "ignore previous instructions" 之类的措辞,并返回 HTTP 400。请将
LLM 调用包装在
try/except中并返回f"<LLM_ERROR: {e}>"—— evolver 只会给该 organism 打 0 分,然后继续处理。 loop.run()是一个生成器 —— 调用它不会执行任何操作,直到 你进行迭代。请使用for snap in loop.run(num_iterations=N):。- 快照是嵌套的 pickle。
iteration_N.pkl包含一个 dict,其中population_snapshot(更多 pickle 字节)。要反序列化,你必须让Organism类可以在与其序列化时相同的点分路径下被导入。 - 并发默认值偏激进。 10/10 在大多数 provider 上 都会触发速率限制。请从 2/2 开始。
- CLI 硬编码为 Anthropic。
uv run darwinian_evolver <problem>会调用ANTHROPIC_API_KEY并使用 Claude Sonnet。要使用其他 provider,请编写类似parrot_openrouter.py的 driver。 - AGPL。 切勿在 Kopi Agent 核心中
from darwinian_evolver import ...。~/.kopi/skills/...下的自定义 driver 脚本属于用户侧,是没问题的。 - 没有 PyPI 包。
pip install darwinian-evolver会拉取错误的 内容。请始终从 GitHub 仓库安装。
验证
安装并运行一次 parrot 后,以下命令退出码为 0 即可视为通过:
DE_DIR=~/.kopi/cache/darwinian-evolver/darwinian_evolver
ls "$DE_DIR/darwinian_evolver/lineage_visualizer.html" >/dev/null && \
cd "$DE_DIR" && uv run darwinian_evolver --help >/dev/null && \
echo "darwinian-evolver: OK"