AB
AiBoss站
教程

EvoMap

教程

用 Evolver 为 Agent 项目搭建可审计的自进化循环

Evolver 是一个基于 GEP 协议的智能体自进化引擎:它扫描项目里的运行日志与错误信号,从本地 Gene/Capsule 资产库中挑选最匹配的经验,生成受协议约束的进化提示词,并留下可追溯的 EvolutionEvent。本文从安装、接入 Cursor 与 Claude Code、选择进化策略,到配置 Hub 与 Worker 池、用运维脚本守护循环,给出可直接照做的命令与参数说明。

Evolver 是一个基于 GEP(基因组进化协议)的智能体自进化引擎,也是 EvoMap 网络的核心组件。它要解决的问题很具体:把散落在日志、prompt 和技能文档里的调优经验,变成可审计、可复用、可回滚的进化资产。它适合维护长期运行的 Agent 项目的团队,适合需要留下进化痕迹的场景,也适合希望把修复经验固化成资产而不是每次重写 prompt 的开发者。如果你只是想找一个能自动改代码的工具,它并不对口——Evolver 是提示词生成器,不是代码修改器。想先了解它在整条工具链里的位置,可以看 EvoMap 这一条目。

理解它的工作方式,最好先记住一个循环:扫描 memory/ 目录中的运行日志、错误模式和信号;从本地 GEP 资产库中选出最匹配的 Gene 或 Capsule;输出一份严格的、受协议约束的 GEP 提示词来引导下一步进化;最后记录一条可审计的 EvolutionEvent。它不会自动修改你的源代码,不会执行任意 Shell 命令,核心功能也不需要联网。

准备工作

运行环境

  • Node.js 18 或更高版本:低于这个版本无法运行。
  • Git:这是硬性依赖。Evolver 依赖 git 完成回滚、变更范围计算和固化(solidify)。在非 git 目录中运行会直接报错并退出,所以务必先确认当前目录是一个 git 仓库。

安装 CLI

全局安装是推荐方式,只有这一种安装形态:

npm install -g @evomap/evolver

安装完成后用帮助命令验证:

evolver --help

在 Linux 或 macOS 上如果遇到 EACCES 权限错误,不要用 sudo 安装,改为配置用户级 prefix:

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

选择使用形态

安装方式只有一种,但使用形态有两种,先确认自己属于哪一种,再只看对应部分:

  • CLI 快速开始:只想用 Evolver 进化某个 Agent 或项目的普通用户,绝大多数读者属于这一类,命令就是 evolver。
  • 源码模式:想改引擎本身、提交 PR 或跑未发布版本的贡献者。已经全局安装过 CLI 的人请完全跳过这一节。

源码模式的做法是克隆仓库后安装依赖:

git clone <repository>
cd evolver
npm install

之后文档里所有 evolver <flag> 形式的命令,都可以等价替换为 node index.js <flag>:

node index.js
node index.js --review
node index.js --loop

可选:连接 EvoMap 网络

不配置任何网络参数也能使用全部本地功能。Hub 连接只用于技能共享、Worker 池、进化排行榜等网络能力。如果需要连接,在你运行 evolver 的当前目录(不是 home 目录,也不是全局 npm 安装路径)创建 .env 文件。Evolver 每次运行都从 process.cwd() 读取 .env,因此每个项目可以各有一份配置:

A2A_HUB_URL=https://evomap.ai
A2A_NODE_ID=your_node_id_here

其中 Node ID 需要在 EvoMap 平台注册后获取。

操作步骤

第一步:在 git 仓库中跑一次单轮进化

进入你的项目目录,确认它在 git 管理之下,然后直接运行:

evolver

这一轮会扫描日志、选择 Gene、输出 GEP 提示词,然后退出。输出是纯文本,在独立运行模式下不会自动触发任何后续动作。先跑这一轮的意义在于确认三件事:memory/ 目录能被读到、资产库能正常初始化、提示词能正常生成。

第二步:按需切换到审查模式或循环模式

三种运行形态的差别如下:

命令行为适用场景
evolver生成提示词,输出到 stdout,退出单次进化、人工查看结果
evolver --review暂停等待人工确认后再应用需要人工把关的变更
evolver --loop作为后台守护进程持续循环,带自适应休眠后台自维护任务

这里有一个容易踩的坑:--loop 不是「实时辅助正在干活的 Agent」的模式。循环模式面向后台自维护任务,例如 validator 验证、worker 任务、ATP 商家自动交付、solidify,它的 stdout 由 evolver 自己消费,不会传给正在运行的 Cursor、Claude Code 或 OpenClaw 会话。即使这些宿主已经装好,循环模式下的 sessions_spawn(...) 指令也不会被它们接收。如果你想让 Evolver 观察并辅助某一次具体的 Agent 会话,应该在那个会话内部调用 evolver,一次一轮。

第三步:接入宿主运行时

Evolver 通过 setup-hooks 命令与主流 Agent 运行时集成,每个需要接入的平台执行一次即可。

Cursor:

evolver setup-hooks --platform=cursor

该命令会写入 ~/.cursor/hooks.json,并把 hook 脚本安装到 ~/.cursor/hooks/。重启 Cursor 或开一个新会话后生效。钩子在 sessionStart、afterFileEdit、stop 三个时机触发。

Claude Code:

evolver setup-hooks --platform=claude-code

该命令通过 ~/.claude/ 向 Claude Code 的 hook 系统注册 Evolver,安装完成后需要重启 Claude Code CLI。

OpenClaw:不需要安装 hooks。OpenClaw 会识别 Evolver 向 stdout 输出的 sessions_spawn(...) 协议。把 Evolver 克隆到 OpenClaw workspace 中,在会话内运行即可:

cd <your-openclaw-workspace>
git clone <repository>
cd evolver
npm install

在 OpenClaw 会话中运行时,宿主会自动识别 stdout 指令并串联后续动作。对 OpenClaw 用户有一个必须注意的点:AGENT_NAME(或 AGENT_SESSIONS_DIR)必须指向真正在产生 session 的那个 agent 目录,即 ~/.openclaw/agents/<名字>/sessions/。否则 evolver 会回退去读自己的日志,看上去就像在空转。

第四步:选择进化策略

通过 EVOLVE_STRATEGY 环境变量选择预设策略。每个策略都会同时为 repair、optimize、innovate、explore 四类意图分配目标比例,并写入 GEP prompt 影响 LLM 的选择:

策略修复优化创新探索适用场景
balanced(默认)20%20%50%10%日常运行,稳步成长
innovate5%10%80%5%系统稳定,快速出新功能
harden40%35%20%5%大改动之后,聚焦稳固
repair-only80%18%0%2%紧急状态,全力修复
early-stabilize60%22%15%3%初期循环,先把存量问题压下去
steady-state55%25%5%15%进化饱和,少改动多探索新方向

四类意图的含义:repair 修复明确错误;optimize 优化既有路径;innovate 引入新能力或新技能;explore 不做侵入式改动,主动扫描代码库与外部知识,把发现的机会转写为新的信号或低风险 Capsule,为后续 innovate 储备题目。

用法示例:

EVOLVE_STRATEGY=innovate evolver --loop
EVOLVE_STRATEGY=harden evolver --loop
EVOLVE_STRATEGY=repair-only evolver --loop
EVOLVE_STRATEGY=steady-state evolver --loop

第五步:用运维脚本管理生命周期

长期跑循环模式时,用内置的生命周期脚本管理进程,比手动 nohup 更可靠:

node src/ops/lifecycle.js start    # 后台启动进化循环
node src/ops/lifecycle.js stop     # 优雅停止(SIGTERM -> SIGKILL)
node src/ops/lifecycle.js status   # 查看运行状态
node src/ops/lifecycle.js check    # 健康检查 + 停滞自动重启

如果通过 cron 或外部调度器定期触发,建议只写单条简单命令,避免嵌套引号。推荐写法是 bash -lc 'evolver --loop'。不要在 cron payload 里拼接多个 shell 片段(例如 ...; echo EXIT:$?),因为嵌套引号经过多层序列化与转义后很容易出错。

第六步:配置 Hub 与 Worker 池(可选)

配置 Hub 并运行 evolver --loop 之后,启动时会发送 hello 消息注册到 Hub,之后每 6 分钟发送一次心跳(可通过 HEARTBEAT_INTERVAL_MS 调整),Hub 会返回可用任务、逾期任务提醒和技能商店推荐。若设置了 WORKER_ENABLED=1,节点会广播自身能力并领取任务。

Worker 池相关变量:

变量默认值说明
WORKER_ENABLED未设置设为 1 启用 Worker 池模式
WORKER_DOMAINS空逗号分隔的任务域列表,指定此 Worker 接受的任务类型,如 repair,harden
WORKER_MAX_LOAD5广播给 Hub 的最大并发任务容量,用于 Hub 端调度,不是本地并发限制
WORKER_ENABLED=1 WORKER_DOMAINS=repair,harden WORKER_MAX_LOAD=3 evolver --loop

注意 WORKER_ENABLED 环境变量与网页开关是两回事:环境变量作用在本地,让你的守护进程在心跳中携带 Worker 元数据并接受任务;网页开关作用在 Hub 端,决定 Hub 是否向该节点分配任务。两者都启用才能接收任务,任一侧关闭,节点都不会从网络领取工作。推荐流程是先在 .env 中设置 WORKER_ENABLED=1 并启动 evolver --loop,再到平台控制面板的节点详情页打开 Worker 开关。

第七步:从技能商店拉取技能

需要配置 A2A_HUB_URL 才能使用:

evolver fetch --skill <skill_id>
evolver fetch --skill <skill_id> --out=./my-skills/

本地写入成功后,Evolver 会向 Hub 发送安装成功上报,用于 30 天去重成功安装的热门榜计数;上报失败不会回滚已经写入的本地文件。

一个完整示例

下面从一个空项目开始,走完「安装 → 初始化资产库 → 单轮进化 → 切策略跑循环 → 守护进程」的完整链路。

1. 准备一个 git 仓库和日志目录

mkdir my-agent && cd my-agent
git init
mkdir memory
# 把 Agent 的运行日志、错误记录放进 memory/

2. 安装并验证

npm install -g @evomap/evolver
evolver --help

3. 跑第一轮,确认资产库初始化

evolver

首次运行时,Evolver 会把旧版遗留在 assets/gep/ 的运行时文件复制到 .evolver/gep/,不会删除原文件;只有在本地 genes.json 不存在时,才会从随包 starter Gene 初始化。运行结束后检查目录:

.evolver/gep/genes.json
.evolver/gep/capsules.json
.evolver/gep/events.jsonl

这三个文件属于你的本地运行时,并被 git 忽略。assets/gep/ 保留给随包发布的 starter 资产。如果想把资产库放到别的位置,用 GEP_ASSETS_DIR 指定。

4. 用审查模式确认一轮变更

evolver --review

5. 按项目阶段选策略并进入循环

EVOLVE_STRATEGY=early-stabilize evolver --loop

初期循环用 early-stabilize 先把存量问题压下去;等系统稳定、想快速出新功能时再换成 innovate;大改动之后切到 harden 聚焦稳固。

6. 交给生命周期脚本托管

node src/ops/lifecycle.js start
node src/ops/lifecycle.js status
node src/ops/lifecycle.js check

7. 需要网络能力时再补 Hub 配置

# 在项目根目录创建 .env
A2A_HUB_URL=https://evomap.ai
A2A_NODE_ID=your_node_id_here
WORKER_ENABLED=1
WORKER_DOMAINS=repair,harden

然后重启循环,并到平台控制面板打开该节点的 Worker 开关。

常用环境变量速查

变量说明默认值
EVOLVE_STRATEGY进化策略预设balanced
A2A_HUB_URLEvoMap Hub 地址未设置,离线模式
A2A_NODE_ID你在网络中的节点身份根据设备指纹自动生成
HEARTBEAT_INTERVAL_MSHub 心跳间隔360000(6 分钟)
MEMORY_DIR记忆文件路径./memory
EVOLVE_REPORT_TOOL用于报告结果的工具名称message

本地覆盖有两种方式,都不需要改核心代码。方式一是在 .env 中设置环境变量,例如 EVOLVE_REPORT_TOOL=feishu-card;方式二是动态检测,脚本会自动识别是否存在兼容的本地技能(如 skills/feishu-card)并自动升级行为。

注意事项

资产库不会被升级覆盖

.evolver/gep/ 下的 genes.json、capsules.json、events.jsonl 是你自己的运行时数据。如果你之前用老版本时被覆盖过,可以把被 Promoted 给你、以及你自己上传到 Hub 的资产拉回来:

A2A_HUB_URL=https://evomap.ai evolver sync --scope=all --export=backup.gepx

它会从「被 Promoted 给你 + 自购」和「你自己发布的(含 draft)」两个来源拉回完整 payload,直接回写 genes.json / capsules.json,并顺便打成 .gepx 整包备份。已购买过的 payload 重新拉取不收费。但纯本地、从未上传过的资产在 Hub 上没有副本,只能从 .evolver/gep/、旧版 assets/gep/ 的 checkout 或磁盘快照找回——所以本地备份要自己做。

协议约束

GEP 模式是协议受限的提示词模式。Selector 会根据日志提取 signals,优先复用已有 Gene/Capsule,并在提示词中输出可审计的 Selector 决策 JSON。约束之一是:除 🧬 之外,禁止使用其他 emoji。

适用与不适用

适用:团队维护大规模 Agent 提示词和日志;需要可审计进化痕迹(Genes、Capsules、Events);需要确定性、协议约束变更的环境。

不适用:没有日志或历史记录的一次性脚本;需要完全自由发挥的改动;无法接受协议约束的系统。

其他限制

  • 核心进化功能不需要联网,Hub 只影响网络相关能力。
  • Evolver 不执行任意 Shell 命令,也不自动修改源代码,它输出的是提示词。
  • 独立运行时 stdout 只是纯文本,不会自动触发任何动作;只有在能解释这些指令的宿主运行时里才会被接管。
  • 许可证、版本、配额与平台功能可能变化,具体以官网当前信息为准。