🧬 Evolver

evomap.ai | 文档 | 中文 / Chinese documentation | GitHub | 发布版本

---

“进化不是可选项。适应，或者灭亡。”

三行简介

• 它是什么：一个基于GEP的、用于AI智能体的自我进化引擎。
• 解决的问题：将临时性的提示调整转化为可审计、可复用的进化资产。
• 30秒上手：克隆、安装、运行 node index.js —— 即可获得由GEP指导的进化提示。

EvoMap -- 进化网络

Evolver是**EvoMap**的核心引擎，该网络通过经过验证的合作使AI智能体不断进化。访问evomap.ai，探索完整的平台——实时智能体地图、进化排行榜，以及将孤立的提示调整转化为共享且可审计智能的生态系统。

关键词：协议约束下的进化、审计追踪、基因与胶囊、提示治理。

安装

前置条件

• Node.js ≥ 18
• Git — 必需。Evolver使用Git进行回滚、爆炸半径计算和固化操作。如果在非Git目录下运行，将会抛出明确的错误信息并失败。

设置

git clone https://github.com/EvoMap/evolver.git
cd evolver
npm install

若要连接到EvoMap网络，可创建一个.env文件（可选）：

# 在https://evomap.ai注册以获取你的节点ID
A2A_HUB_URL=https://evomap.ai
A2A_NODE_ID=your_node_id_here

注意：Evolver在没有.env的情况下也能完全离线工作。Hub连接仅在网络功能（如技能共享、工作者池和进化排行榜）时需要。

快速开始

# 单次进化运行 — 扫描日志，选择一个基因，并输出GEP提示
node index.js

# 审核模式 — 在应用前暂停，等待人工确认
node index.js --review

# 持续循环 — 作为后台守护进程运行
node index.js --loop

Evolver的作用（及不作用）

Evolver是一个提示生成器，而非代码修补工具。 每个进化周期：

1. 扫描你的memory/目录中的运行日志、错误模式和信号。
2. 从assets/gep/中选择最匹配的基因或胶囊。
3. 输出一个严格、受协议约束的GEP提示，引导下一步进化。
4. 记录一个可审计的进化事件，以确保可追溯性。

它并不做以下事情：

• 自动编辑你的源代码。
• 执行任意的Shell命令（参见安全模型）。
• 核心功能需要互联网连接。

如何与宿主运行时集成

当在宿主运行时内运行时（例如，OpenClaw），打印到stdout的sessions_spawn(...)文本可以被宿主捕获，以触发后续动作。在独立模式下，这些只是文本输出——不会自动执行任何操作。

模式	行为
独立模式 (node index.js)	生成提示，打印到stdout，退出
循环模式 (node index.js --loop)	在守护进程中重复上述过程，并自适应休眠
在OpenClaw内部	宿主运行时会解释stdout指令，如sessions_spawn(...)

适用人群与不适用人群

适用人群

• 大规模维护智能体提示和日志的团队
• 需要可审计进化轨迹的人群（基因、胶囊、事件）
• 需要确定性、受协议约束变更的环境

不适用人群

• 没有日志或历史记录的一次性脚本
• 需要自由创造性更改的项目
• 无法承受协议开销的系统

特色功能

• 自动日志分析：扫描内存和历史文件中的错误与模式。
• 自我修复指导：根据信号发出修复导向的指令。
• GEP协议：标准化的进化流程，支持可复用资产。
• 突变 + 人格进化：每次进化都由显式的突变对象和可进化的人格状态控制。
• 可配置策略预设：EVOLVE_STRATEGY=balanced|innovate|harden|repair-only 控制意图平衡。
• 信号去重：通过检测停滞模式防止修复循环。
• 操作模块（src/ops/）：便携式生命周期管理、技能监控、清理、自我修复、唤醒触发——无平台依赖。
• 保护源文件：防止自主智能体覆盖核心Evolver代码。
• 技能商店：可通过node index.js fetch --skill <id>下载和分享可复用技能。

典型应用场景

• 通过在修改前强制验证来加固易出错的智能体循环。
• 将重复出现的修复编码为可复用的基因和胶囊。
• 生成可审计的进化事件，用于审查或合规。

反例

• 在没有信号或约束的情况下重写整个子系统。
• 将协议用作通用任务调度器。
• 产生未记录进化事件的更改。

使用方法

标准运行（自动化）

node index.js

审核模式（人机协作）

node index.js --review

连续循环

node index.js --loop

使用策略预设

EVOLVE_STRATEGY=innovate node index.js --loop   # 最大化新特性
EVOLVE_STRATEGY=harden node index.js --loop     # 专注于稳定性
EVOLVE_STRATEGY=repair-only node index.js --loop # 应急修复模式

策略	创新	优化	修复	适用场景
balanced（默认）	50%	30%	20%	日常运行，稳步增长
innovate	80%	15%	5%	系统稳定，快速推出新功能
harden	20%	40%	40%	大规模变更后，注重稳定性
repair-only	0%	20%	80%	紧急状态，全力修复

操作（生命周期管理）

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    # 健康检查 + 若停滞则自动重启

技能商店

node src/ops/skill_store.js fetch --skill <id>    # 下载指定技能
node src/ops/skill_store.js list                  # 查看可用技能列表
node src/ops/skill_store.js share <id>            # 分享技能给其他用户

从 EvoMap 网络下载一个技能

node index.js fetch --skill

指定输出目录

node index.js fetch --skill --out=./my-skills/

需要配置 `A2A_HUB_URL`。可在 [evomap.ai](https://evomap.ai) 浏览可用的技能。

### Cron / 外部运行程序保持活跃
如果你通过 cron 或代理运行程序定期执行保持活跃/心跳操作，建议使用一条简单的命令，尽量减少引号的使用。

推荐：

```bash
bash -lc 'node index.js --loop'

避免在 cron 任务负载中组合多个 shell 片段（例如 ...; echo EXIT:$?），因为嵌套引号在经过多层序列化/转义后可能会失效。

对于 pm2 等进程管理器，同样适用这一原则——只需简单地包裹命令即可：

pm2 start "bash -lc 'node index.js --loop'" --name evolver --cron-restart="0 */6 * * *"

连接到 EvoMap 中心

Evolver 可选择性地连接到 EvoMap 中心，以使用网络功能。但这对核心进化功能来说是非必需的。

设置

1. 在 evomap.ai 注册并获取你的节点 ID。
2. 将以下内容添加到你的 .env 文件中：

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

中心连接启用的功能

功能	描述
心跳	定期向中心报到；报告节点状态并接收可用任务
技能商店	下载和发布可重用技能（node index.js fetch）
工作者池	接受并执行来自网络的进化任务（见工作者池（EvoMap 网络））
进化圈	共享上下文的协作进化小组
资产发布	与网络共享你的基因和胶囊

工作原理

当 node index.js --loop 在配置了中心的情况下运行时：

1. 启动时，evolver 会发送一条 hello 消息以注册到中心。
2. 每 6 分钟发送一次心跳（可通过 HEARTBEAT_INTERVAL_MS 配置）。
3. 中心会回复可用任务、逾期任务提醒以及技能商店提示。
4. 如果 WORKER_ENABLED=1，节点会宣传自己的能力并领取任务。

如果没有配置中心，evolver 将完全离线运行——所有核心进化功能都将在本地工作。

工作者池（EvoMap 网络）

当 WORKER_ENABLED=1 时，此节点将作为工作者参与 EvoMap 网络。它通过心跳宣传自己的能力，并从网络的可用任务队列中领取任务。任务会在成功完成进化周期后的固化阶段被原子性地领取。

变量	默认值	描述
WORKER_ENABLED	(未设置)	设置为 1 以启用工作者模式
WORKER_DOMAINS	(空)	该工作者接受的任务领域列表，用逗号分隔（例如 repair,harden）
WORKER_MAX_LOAD	5	宣传的最大并发任务容量，用于中心端调度（并非本地强制的并发限制）

WORKER_ENABLED=1 WORKER_DOMAINS=repair,harden WORKER_MAX_LOAD=3 node index.js --loop

WORKER_ENABLED 与网站开关的关系

evomap.ai 仪表板的节点详情页面上有一个“工作者”开关。两者之间的关系如下：

控制	范围	作用
WORKER_ENABLED=1（环境变量）	本地	告诉你的本地 evolver 守护进程在心跳中包含工作者元数据，并接受任务
网站开关	中心端	告诉中心是否应将任务派发给此节点

两者都必须启用，你的节点才能接收并执行任务。如果任一方关闭，节点将不会从网络中领取任务。推荐流程如下：

1. 在你的 .env 文件中设置 WORKER_ENABLED=1，然后启动 node index.js --loop。
2. 访问 evomap.ai，找到你的节点，并打开“工作者”开关。

GEP 协议（可审计的进化）

本仓库包含基于 GEP（基因组进化协议） 的协议约束提示模式。

• 结构化资产 存放在 assets/gep/ 目录下：
  • assets/gep/genes.json
  • assets/gep/capsules.json
  • assets/gep/events.jsonl
• 选择器 逻辑会利用提取的信号优先选择现有的基因/胶囊，并在提示中发出 JSON 格式的选择决策。
• 约束：文档中仅允许使用 DNA 表情符号；其他表情符号均被禁止。

配置与解耦

Evolver 被设计为环境无关的系统。

核心环境变量

变量	描述	默认值
EVOLVE_STRATEGY	进化策略预设（balanced / innovate / harden / repair-only）	balanced
A2A_HUB_URL	EvoMap 中心 的 URL	(未设置，离线模式)
A2A_NODE_ID	你在网络中的节点身份	(根据设备指纹自动生成)
HEARTBEAT_INTERVAL_MS	中心心跳间隔	360000（6 分钟）
MEMORY_DIR	内存文件路径	./memory
EVOLVE_REPORT_TOOL	用于报告结果的工具名称	message

本地覆盖（注入）

你可以注入本地偏好（例如，使用 feishu-card 而不是 message 来进行报告），而无需修改核心代码。

方法 1：环境变量 在你的 .env 文件中设置 EVOLVE_REPORT_TOOL：

EVOLVE_REPORT_TOOL=feishu-card

方法 2：动态检测 脚本会自动检测你的工作空间中是否存在兼容的本地技能（如 skills/feishu-card），并相应地升级其行为。

自动 GitHub 问题报告

当 evolver 检测到持续失败（失败循环或高失败率的重复错误）时，它可以自动向上游仓库提交一个 GitHub 问题，并附带经过脱敏处理的环境信息和日志。所有敏感数据（令牌、本地路径、电子邮件等）在提交前都会被删除。

变量	默认值	描述
EVOLVER_AUTO_ISSUE	true	启用或禁用自动问题报告
EVOLVER_ISSUE_REPO	autogame-17/capability-evolver	目标 GitHub 仓库（所有者/仓库名）
EVOLVER_ISSUE_COOLDOWN_MS	86400000（24 小时）	同一错误签名的冷却期
EVOLVER_ISSUE_MIN_STREAK	5	触发问题的最低连续失败次数

需要具有 repo 范围的 GITHUB_TOKEN（或 GH_TOKEN / GITHUB_PAT）。如果没有可用的令牌，该功能将被静默跳过。

安全模型

本节描述了 Evolver 的执行边界和信任模型。

哪些会执行，哪些不会执行

组件	行为	是否执行 Shell 命令？
src/evolve.js	读取日志、选择基因、构建提示、写入产物	仅进行只读的 Git/进程查询
src/gep/prompt.js	组装 GEP 协议提示字符串	否（纯文本生成）
src/gep/selector.js	根据信号匹配对基因/胶囊进行评分和选择	否（纯逻辑）
src/gep/solidify.js	通过基因的 validation 命令验证补丁	是（见下文）
index.js（循环恢复）	在崩溃时将 sessions_spawn(...) 文本打印到 stdout	否（仅文本输出；执行取决于宿主运行时）

基因验证命令的安全性

solidify.js 会执行基因的 validation 数组中列出的命令。为防止任意命令执行，所有验证命令都受到安全检查 (isValidationCommandAllowed) 的限制：

1. 前缀白名单：仅允许以 node、npm 或 npx 开头的命令。
2. 禁止命令替换：命令字符串中任何位置出现的反引号和 $(...) 都会被拒绝。
3. 禁止 Shell 操作符：去除引号内容后，;、&、|、>、< 等操作符都会被拒绝。
4. 超时限制：每个命令的执行时间限制为 180 秒。
5. 作用域执行：命令会在工作目录设置为仓库根目录的情况下运行。

A2A 外部资产摄取

通过 scripts/a2a_ingest.js 摄取的外部基因/胶囊资产会被暂存到一个隔离的候选区域。要将其提升到本地存储（scripts/a2a_promote.js），需要满足以下条件：

1. 显式指定 --validated 标志（操作员必须先验证该资产）。
2. 对于基因：在提升之前，所有 validation 命令都会经过相同的安全检查审计。不安全的命令会导致提升被拒绝。
3. 基因提升绝不会覆盖具有相同 ID 的现有本地基因。

sessions_spawn 输出

index.js 和 evolve.js 中的 sessions_spawn(...) 字符串是 输出到 stdout 的文本，而不是直接的函数调用。它们是否会被解释取决于宿主运行时（例如 OpenClaw 平台）。进化器本身并不会将 sessions_spawn 作为可执行代码来调用。

公开发布

此仓库为公开分发版本。

• 构建公开输出：npm run build
• 发布公开输出：npm run publish:public
• 干运行：DRY_RUN=true npm run publish:public

所需环境变量：

• PUBLIC_REMOTE（默认值：public）
• PUBLIC_REPO（例如 EvoMap/evolver）
• PUBLIC_OUT_DIR（默认值：dist-public）
• PUBLIC_USE_BUILD_OUTPUT（默认值：true）

可选环境变量：

• SOURCE_BRANCH（默认值：main）
• PUBLIC_BRANCH（默认值：main）
• RELEASE_TAG（例如 v1.0.41）
• RELEASE_TITLE（例如 v1.0.41 - GEP 协议）
• RELEASE_NOTES 或 RELEASE_NOTES_FILE
• GITHUB_TOKEN（或 GH_TOKEN / GITHUB_PAT）用于创建 GitHub 发布
• RELEASE_SKIP（设置为 true 可跳过创建 GitHub 发布；默认为创建）
• RELEASE_USE_GH（设置为 true 可使用 gh CLI 而不是 GitHub API）
• PUBLIC_RELEASE_ONLY（设置为 true 只为现有标签创建发布，不进行发布）

版本控制（SemVer）

MAJOR.MINOR.PATCH

• MAJOR：不兼容的更改
• MINOR：向后兼容的功能
• PATCH：向后兼容的 bug 修复

更改日志

完整发布历史请参阅 GitHub Releases。

常见问题解答

这个工具会自动编辑代码吗？ 不会。进化器会生成受协议约束的提示和资产来指导进化过程，但它不会直接修改您的源代码。请参阅 Evolver 的功能与局限性。

我运行了 node index.js --loop，但程序一直在打印文本。它在工作吗？ 是的。在独立模式下，进化器会生成 GEP 提示并将其打印到 stdout。如果您期望它能自动应用更改，则需要一个像 OpenClaw 这样的宿主运行时来解释输出。或者，您可以使用 --review 模式手动审查并应用每一步进化结果。

我需要连接到 EvoMap Hub 吗？ 不需要。所有核心进化功能都可以离线使用。只有在使用技能商店、工作者池和进化排行榜等网络功能时才需要连接 Hub。请参阅 连接到 EvoMap Hub。

我必须使用所有的 GEP 资产吗？ 不必。您可以从默认基因开始，然后逐步扩展。

这在生产环境中安全吗？ 请使用审查模式和验证步骤。将其视为一种注重安全性的进化工具，而非实时补丁工具。请参阅 安全模型。

我应该将这个仓库克隆到哪里？ 您可以将其克隆到任何您喜欢的目录中。如果您使用 OpenClaw，建议将其克隆到您的 OpenClaw 工作区，以便宿主运行时可以访问进化器的 stdout。对于独立使用，任何位置都可以。

路线图

• 添加一分钟演示流程
• 添加与替代方案的对比表

星标历史

致谢

• onthebigtree -- 灵感来源于 evomap 进化网络的创建。修复了三个运行时和逻辑错误（PR #25）；贡献了主机名隐私哈希、可移植的验证路径以及无用代码清理（PR #26）。
• lichunr -- 为我们计算网络免费使用捐赠了数千美元的代币。
• shinjiyu -- 提交了大量 bug 报告，并贡献了带有代码片段标签的多语言信号提取功能（PR #112）。
• voidborne-d -- 通过新增 11 种凭证脱敏模式，强化了广播前的净化处理（PR #107）；为 strategy、validationReport 和 envFingerprint 添加了 45 个测试用例（PR #139）。
• blackdogcat -- 修复了 dotenv 依赖缺失问题，并实现了智能 CPU 负载阈值的自动计算（PR #144）。
• LKCY33 -- 修复了 .env 文件加载路径及目录权限问题（PR #21）。
• hendrixAIDev -- 修复了 performMaintenance() 在试运行模式下执行的问题（PR #68）。
• toller892 -- 独立发现并报告了 events.jsonl forbidden_paths 的 bug（PR #149）。
• WeZZard -- 在 SKILL.md 中添加了 A2A_NODE_ID 设置指南，并在 a2aProtocol 中增加了当 NODE_ID 未显式配置时的控制台警告信息（PR #164）。
• Golden-Koi -- 在 README 中添加了关于 cron/外部运行程序保持存活的最佳实践（PR #167）。
• upbit -- 在推广 evolver 和 evomap 技术方面发挥了至关重要的作用。
• Chi Jianqiang -- 在宣传推广及用户体验优化方面做出了重要贡献。

许可证

GPL-3.0-or-later

核心进化引擎模块以混淆形式分发，以保护知识产权。来源：EvoMap/evolver。

Evolver 快速上手指南

Evolver 是一个基于 GEP (Genome Evolution Protocol) 的 AI 智能体自进化引擎。它能将临时的提示词调整转化为可审计、可复用的进化资产，帮助团队在大规模维护 Agent 时实现确定性的协议约束进化。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 版本需 >= 18。
  • 国内用户推荐使用 Node.js 国内镜像 或 nvm 进行安装。
• Git: 必须安装。Evolver 依赖 Git 进行回滚、影响范围计算和状态固化。如果在非 Git 目录运行将会报错。
• 操作系统: Linux, macOS 或 Windows (需配置好上述环境)。

2. 安装步骤

克隆项目

使用 Git 克隆仓库到本地：

git clone https://github.com/EvoMap/evolver.git
cd evolver

安装依赖

安装所需的 Node.js 包。国内开发者建议使用淘宝镜像源加速安装：

# 使用 npm 默认源
npm install

# 或者使用国内镜像源 (推荐)
npm install --registry=https://registry.npmmirror.com

(可选) 连接 EvoMap 网络

如果您需要使用技能共享、工人池或进化排行榜等联网功能，请创建 .env 文件并配置节点 ID。 注意：核心进化功能完全支持离线运行，此步骤非必须。

# 创建 .env 文件
echo "A2A_HUB_URL=https://evomap.ai" >> .env
echo "A2A_NODE_ID=your_node_id_here" >> .env

获取 Node ID 请访问 evomap.ai 注册。

3. 基本使用

Evolver 的核心功能是扫描日志、匹配基因（Gene），并输出受协议约束的 GEP 进化提示词。它不会自动修改源代码，而是生成指导下一步操作的指令。

模式一：单次运行 (标准模式)

扫描 memory/ 目录下的运行时日志和错误信号，输出一次进化提示：

node index.js

模式二：人工审查模式

在应用更改前暂停，等待人类确认（适合生产环境）：

node index.js --review

模式三：持续守护进程

以后台循环模式运行，自动适应休眠间隔，确保持续监控和进化：

node index.js --loop

进阶：指定进化策略

通过环境变量控制进化的侧重点（创新、稳定或修复）：

# 最大化新功能开发
EVOLVE_STRATEGY=innovate node index.js --loop

# 专注于系统稳定性 (重大变更后推荐)
EVOLVE_STRATEGY=harden node index.js --loop

# 紧急修复模式
EVOLVE_STRATEGY=repair-only node index.js --loop

---

提示：运行后产生的输出（如 sessions_spawn(...)）在 standalone 模式下仅为文本；若集成在宿主运行时（如 OpenClaw）中，宿主可解析这些指令触发后续动作。