
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% | 日常运行,稳步成长 |
innovate | 5% | 10% | 80% | 5% | 系统稳定,快速出新功能 |
harden | 40% | 35% | 20% | 5% | 大改动之后,聚焦稳固 |
repair-only | 80% | 18% | 0% | 2% | 紧急状态,全力修复 |
early-stabilize | 60% | 22% | 15% | 3% | 初期循环,先把存量问题压下去 |
steady-state | 55% | 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_LOAD | 5 | 广播给 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_URL | EvoMap Hub 地址 | 未设置,离线模式 |
A2A_NODE_ID | 你在网络中的节点身份 | 根据设备指纹自动生成 |
HEARTBEAT_INTERVAL_MS | Hub 心跳间隔 | 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 只是纯文本,不会自动触发任何动作;只有在能解释这些指令的宿主运行时里才会被接管。
- 许可证、版本、配额与平台功能可能变化,具体以官网当前信息为准。