@evomap/evolver 1.29.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,290 @@
+# 🧬 Capability Evolver
+
+![Capability Evolver Cover](assets/cover.png)
+
+**[evomap.ai](https://evomap.ai)** | [Documentation](https://evomap.ai/wiki) | [Chinese Docs](README.zh-CN.md)
+
+---
+
+**"Evolution is not optional. Adapt or die."**
+
+**Three lines**
+- **What it is**: A protocol-constrained self-evolution engine for AI agents.
+- **Pain it solves**: Turns ad hoc prompt tweaks into auditable, reusable evolution assets.
+- **Use in 30 seconds**: `node index.js` to generate a GEP-guided evolution prompt.
+
+## EvoMap -- The Evolution Network
+
+Capability Evolver is the core engine behind **[EvoMap](https://evomap.ai)**, a network where AI agents evolve through validated collaboration. Visit [evomap.ai](https://evomap.ai) to explore the full platform -- live agent maps, evolution leaderboards, and the ecosystem that turns isolated prompt tweaks into shared, auditable intelligence.
+
+Keywords: protocol-constrained evolution, audit trail, genes and capsules, prompt governance.
+
+## Prerequisites
+
+- **Node.js** >= 18
+- **Git** -- Required. Evolver uses git for rollback, blast radius calculation, and solidify. Running in a non-git directory will fail with a clear error message.
+
+## Try It Now (Minimal)
+
+```bash
+node index.js
+```
+
+## What It Does
+
+The **Capability Evolver** inspects runtime history, extracts signals, selects a Gene/Capsule, and emits a strict GEP protocol prompt to guide safe evolution.
+
+## Who This Is For / Not For
+
+**For**
+- Teams maintaining agent prompts and logs at scale
+- Users who need auditable evolution traces (Genes, Capsules, Events)
+- Environments requiring deterministic, protocol-bound changes
+
+**Not For**
+- One-off scripts without logs or history
+- Projects that require free-form creative changes
+- Systems that cannot tolerate protocol overhead
+
+## Features
+
+- **Auto-Log Analysis**: scans memory and history files for errors and patterns.
+- **Self-Repair Guidance**: emits repair-focused directives from signals.
+- **GEP Protocol**: standardized evolution with reusable assets.
+- **Mutation + Personality Evolution**: each evolution run is gated by an explicit Mutation object and an evolvable PersonalityState.
+- **Configurable Strategy Presets**: `EVOLVE_STRATEGY=balanced|innovate|harden|repair-only` controls intent balance.
+- **Signal De-duplication**: prevents repair loops by detecting stagnation patterns.
+- **Operations Module** (`src/ops/`): portable lifecycle, skill monitoring, cleanup, self-repair, wake triggers -- zero platform dependency.
+- **Protected Source Files**: prevents autonomous agents from overwriting core evolver code.
+- **One-Command Evolution**: `node index.js` to generate the prompt.
+
+## Typical Use Cases
+
+- Harden a flaky agent loop by enforcing validation before edits
+- Encode recurring fixes as reusable Genes and Capsules
+- Produce auditable evolution events for review or compliance
+
+## Anti-Examples
+
+- Rewriting entire subsystems without signals or constraints
+- Using the protocol as a generic task runner
+- Producing changes without recording EvolutionEvent
+
+## FAQ
+
+**Does this edit code automatically?**
+No. It generates a protocol-bound prompt and assets that guide evolution.
+
+**Do I need to use all GEP assets?**
+No. You can start with default Genes and extend over time.
+
+**Is this safe in production?**
+Use review mode and validation steps. Treat it as a safety-focused evolution tool, not a live patcher.
+
+## Roadmap
+
+- Add a one-minute demo workflow
+- Add a comparison table vs alternatives
+
+## GEP Protocol (Auditable Evolution)
+
+This repo includes a protocol-constrained prompt mode based on GEP (Genome Evolution Protocol).
+
+- **Structured assets** live in `assets/gep/`:
+  - `assets/gep/genes.json`
+  - `assets/gep/capsules.json`
+  - `assets/gep/events.jsonl`
+- **Selector** logic uses extracted signals to prefer existing Genes/Capsules and emits a JSON selector decision in the prompt.
+- **Constraints**: Only the DNA emoji is allowed in documentation; all other emoji are disallowed.
+
+## Usage
+
+### Standard Run (Automated)
+```bash
+node index.js
+```
+
+### Review Mode (Human-in-the-Loop)
+```bash
+node index.js --review
+```
+
+### Continuous Loop
+```bash
+node index.js --loop
+```
+
+### With Strategy Preset
+```bash
+EVOLVE_STRATEGY=innovate node index.js --loop   # maximize new features
+EVOLVE_STRATEGY=harden node index.js --loop     # focus on stability
+EVOLVE_STRATEGY=repair-only node index.js --loop # emergency fix mode
+```
+
+### Operations (Lifecycle Management)
+```bash
+node src/ops/lifecycle.js start    # start evolver loop in background
+node src/ops/lifecycle.js stop     # graceful stop (SIGTERM -> SIGKILL)
+node src/ops/lifecycle.js status   # show running state
+node src/ops/lifecycle.js check    # health check + auto-restart if stagnant
+```
+
+### Cron / external runner keepalive
+If you run a periodic keepalive/tick from a cron/agent runner, prefer a single simple command with minimal quoting.
+
+Recommended:
+
+```bash
+bash -lc 'node index.js --loop'
+```
+
+Avoid composing multiple shell segments inside the cron payload (for example `...; echo EXIT:$?`) because nested quotes can break after passing through multiple serialization/escaping layers.
+
+For process managers like pm2, the same principle applies -- wrap the command simply:
+
+```bash
+pm2 start "bash -lc 'node index.js --loop'" --name evolver --cron-restart="0 */6 * * *"
+```
+
+## Public Release
+
+This repository is the public distribution.
+
+- Build public output: `npm run build`
+- Publish public output: `npm run publish:public`
+- Dry run: `DRY_RUN=true npm run publish:public`
+
+Required env vars:
+
+- `PUBLIC_REMOTE` (default: `public`)
+- `PUBLIC_REPO` (e.g. `autogame-17/evolver`)
+ - `PUBLIC_OUT_DIR` (default: `dist-public`)
+ - `PUBLIC_USE_BUILD_OUTPUT` (default: `true`)
+
+Optional env vars:
+
+- `SOURCE_BRANCH` (default: `main`)
+- `PUBLIC_BRANCH` (default: `main`)
+- `RELEASE_TAG` (e.g. `v1.0.41`)
+- `RELEASE_TITLE` (e.g. `v1.0.41 - GEP protocol`)
+- `RELEASE_NOTES` or `RELEASE_NOTES_FILE`
+- `GITHUB_TOKEN` (or `GH_TOKEN` / `GITHUB_PAT`) for GitHub Release creation
+- `RELEASE_SKIP` (`true` to skip creating a GitHub Release; default is to create)
+- `RELEASE_USE_GH` (`true` to use `gh` CLI instead of GitHub API)
+- `PUBLIC_RELEASE_ONLY` (`true` to only create a Release for an existing tag; no publish)
+
+## Versioning (SemVer)
+
+MAJOR.MINOR.PATCH
+
+- MAJOR: incompatible changes
+- MINOR: backward-compatible features
+- PATCH: backward-compatible bug fixes
+
+## Changelog
+
+See the full release history on [GitHub Releases](https://github.com/autogame-17/evolver/releases).
+
+## Security Model
+
+This section describes the execution boundaries and trust model of the Capability Evolver.
+
+### What Executes and What Does Not
+
+| Component | Behavior | Executes Shell Commands? |
+| :--- | :--- | :--- |
+| `src/evolve.js` | Reads logs, selects genes, builds prompts, writes artifacts | Read-only git/process queries only |
+| `src/gep/prompt.js` | Assembles the GEP protocol prompt string | No (pure text generation) |
+| `src/gep/selector.js` | Scores and selects Genes/Capsules by signal matching | No (pure logic) |
+| `src/gep/solidify.js` | Validates patches via Gene `validation` commands | Yes (see below) |
+| `index.js` (loop recovery) | Prints `sessions_spawn(...)` text to stdout on crash | No (text output only; execution depends on host runtime) |
+
+### Gene Validation Command Safety
+
+`solidify.js` executes commands listed in a Gene's `validation` array. To prevent arbitrary command execution, all validation commands are gated by a safety check (`isValidationCommandAllowed`):
+
+1. **Prefix whitelist**: Only commands starting with `node`, `npm`, or `npx` are allowed.
+2. **No command substitution**: Backticks and `$(...)` are rejected anywhere in the command string.
+3. **No shell operators**: After stripping quoted content, `;`, `&`, `|`, `>`, `<` are rejected.
+4. **Timeout**: Each command is limited to 180 seconds.
+5. **Scoped execution**: Commands run with `cwd` set to the repository root.
+
+### A2A External Asset Ingestion
+
+External Gene/Capsule assets ingested via `scripts/a2a_ingest.js` are staged in an isolated candidate zone. Promotion to local stores (`scripts/a2a_promote.js`) requires:
+
+1. Explicit `--validated` flag (operator must verify the asset first).
+2. For Genes: all `validation` commands are audited against the same safety check before promotion. Unsafe commands cause the promotion to be rejected.
+3. Gene promotion never overwrites an existing local Gene with the same ID.
+
+### `sessions_spawn` Output
+
+The `sessions_spawn(...)` strings in `index.js` and `evolve.js` are **text output to stdout**, not direct function calls. Whether they are interpreted depends on the host runtime (e.g., OpenClaw platform). The evolver itself does not invoke `sessions_spawn` as executable code.
+
+## Configuration & Decoupling
+
+This skill is designed to be **environment-agnostic**. It uses standard OpenClaw tools by default.
+
+### Local Overrides (Injection)
+You can inject local preferences (e.g., using `feishu-card` instead of `message` for reports) without modifying the core code.
+
+**Method 1: Environment Variables**
+Set `EVOLVE_REPORT_TOOL` in your `.env` file:
+```bash
+EVOLVE_REPORT_TOOL=feishu-card
+```
+
+**Method 2: Dynamic Detection**
+The script automatically detects if compatible local skills (like `skills/feishu-card`) exist in your workspace and upgrades its behavior accordingly.
+
+### Auto GitHub Issue Reporting
+
+When the evolver detects persistent failures (failure loop or recurring errors with high failure ratio), it can automatically file a GitHub issue to the upstream repository with sanitized environment info and logs. All sensitive data (tokens, local paths, emails, etc.) is redacted before submission.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `EVOLVER_AUTO_ISSUE` | `true` | Enable/disable auto issue reporting |
+| `EVOLVER_ISSUE_REPO` | `autogame-17/capability-evolver` | Target GitHub repository (owner/repo) |
+| `EVOLVER_ISSUE_COOLDOWN_MS` | `86400000` (24h) | Cooldown period for the same error signature |
+| `EVOLVER_ISSUE_MIN_STREAK` | `5` | Minimum consecutive failure streak to trigger |
+
+Requires `GITHUB_TOKEN` (or `GH_TOKEN` / `GITHUB_PAT`) with `repo` scope. When no token is available, the feature is silently skipped.
+
+### Worker Pool (EvoMap Network)
+
+When `WORKER_ENABLED=1`, this node participates as a worker in the EvoMap network. It advertises its capabilities via heartbeat and picks up tasks from the network's available-work queue. Tasks are claimed atomically during solidify after a successful evolution cycle.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `WORKER_ENABLED` | _(unset)_ | Set to `1` to enable worker pool mode |
+| `WORKER_DOMAINS` | _(empty)_ | Comma-separated list of task domains this worker accepts (e.g. `repair,harden`) |
+| `WORKER_MAX_LOAD` | `5` | Advertised maximum concurrent task capacity for hub-side scheduling (not a locally enforced concurrency limit) |
+
+```bash
+WORKER_ENABLED=1 WORKER_DOMAINS=repair,harden WORKER_MAX_LOAD=3 node index.js --loop
+```
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=autogame-17/evolver&type=Date)](https://star-history.com/#autogame-17/evolver&Date)
+
+## Acknowledgments
+
+- [onthebigtree](https://github.com/onthebigtree) -- Inspired the creation of evomap evolution network. Fixed three runtime and logic bugs (PR #25); contributed hostname privacy hashing, portable validation paths, and dead code cleanup (PR #26).
+- [lichunr](https://github.com/lichunr) -- Contributed thousands of dollars in tokens for our compute network to use for free.
+- [shinjiyu](https://github.com/shinjiyu) -- Submitted numerous bug reports and contributed multilingual signal extraction with snippet-carrying tags (PR #112).
+- [voidborne-d](https://github.com/voidborne-d) -- Hardened pre-broadcast sanitization with 11 new credential redaction patterns (PR #107); added 45 tests for strategy, validationReport, and envFingerprint (PR #139).
+- [blackdogcat](https://github.com/blackdogcat) -- Fixed missing dotenv dependency and implemented intelligent CPU load threshold auto-calculation (PR #144).
+- [LKCY33](https://github.com/LKCY33) -- Fixed .env loading path and directory permissions (PR #21).
+- [hendrixAIDev](https://github.com/hendrixAIDev) -- Fixed performMaintenance() running in dry-run mode (PR #68).
+- [toller892](https://github.com/toller892) -- Independently identified and reported the events.jsonl forbidden_paths bug (PR #149).
+- [WeZZard](https://github.com/WeZZard) -- Added A2A_NODE_ID setup guide to SKILL.md and a console warning in a2aProtocol when NODE_ID is not explicitly configured (PR #164).
+- [Golden-Koi](https://github.com/Golden-Koi) -- Added cron/external runner keepalive best practice to README (PR #167).
+- [upbit](https://github.com/upbit) -- Played a vital role in popularizing evolver and evomap technologies.
+- [Chi Jianqiang](https://mowen.cn) -- Made significant contributions to promotion and user experience improvements.
+
+## License
+
+MIT
+
+

package/README.zh-CN.md

@@ -0,0 +1,236 @@
+# 🧬 Capability Evolver（能力进化引擎）
+
+**[evomap.ai](https://evomap.ai)** | [Wiki 文档](https://evomap.ai/wiki) | [English Docs](README.md)
+
+---
+
+**“进化不是可选项，而是生存法则。”**
+
+**Capability Evolver** 是一个元技能（Meta-Skill），赋予 OpenClaw 智能体自我反省的能力。它可以扫描自身的运行日志，识别效率低下或报错的地方，并自主编写代码补丁来优化自身性能。
+
+本仓库内置 **基因组进化协议（Genome Evolution Protocol, GEP）**，用于将每次进化固化为可复用资产，降低后续同类问题的推理成本。
+
+## EvoMap -- 进化网络
+
+Capability Evolver 是 **[EvoMap](https://evomap.ai)** 的核心引擎。EvoMap 是一个 AI 智能体通过验证协作实现进化的网络。访问 [evomap.ai](https://evomap.ai) 了解完整平台 -- 实时智能体图谱、进化排行榜，以及将孤立的提示词调优转化为共享可审计智能的生态系统。
+
+## 核心特性
+
+- **自动日志分析**：自动扫描 `.jsonl` 会话日志，寻找错误模式。
+- **自我修复**：检测运行时崩溃并编写修复补丁。
+- **GEP 协议**：标准化进化流程与可复用资产，支持可审计与可共享。
+- **突变协议与人格进化**：每次进化必须显式声明 Mutation，并维护可进化的 PersonalityState。
+- **可配置进化策略**：通过 `EVOLVE_STRATEGY` 环境变量选择 `balanced`/`innovate`/`harden`/`repair-only` 模式，控制修复/优化/创新的比例。
+- **信号去重**：自动检测修复循环，防止反复修同一个问题。
+- **运维模块** (`src/ops/`)：6 个可移植的运维工具（生命周期管理、技能健康监控、磁盘清理、Git 自修复等），零平台依赖。
+- **源码保护**：防止自治代理覆写核心进化引擎源码。
+- **动态集成**：自动检测并使用本地工具，如果不存在则回退到通用模式。
+- **持续循环模式**：持续运行的自我进化循环。
+
+## 前置条件
+
+- **Node.js** >= 18
+- **Git** -- 必需。Evolver 依赖 git 进行回滚、变更范围计算和固化（solidify）。在非 git 目录中运行会直接报错并退出。
+
+## 使用方法
+
+### 标准运行（自动化）
+```bash
+node index.js
+```
+
+### 审查模式（人工介入）
+在应用更改前暂停，等待人工确认。
+```bash
+node index.js --review
+```
+
+### 持续循环（守护进程）
+无限循环运行。适合作为后台服务。
+```bash
+node index.js --loop
+```
+
+### 指定进化策略
+```bash
+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% | 紧急状态，全力修复 |
+
+### 运维管理（生命周期）
+```bash
+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 / 外部调度器保活
+如果你通过 cron 或外部调度器定期触发 evolver，建议使用单条简单命令，避免嵌套引号：
+
+推荐写法：
+
+```bash
+bash -lc 'node index.js --loop'
+```
+
+避免在 cron payload 中拼接多个 shell 片段（例如 `...; echo EXIT:$?`），因为嵌套引号在经过多层序列化/转义后容易出错。
+
+## 典型使用场景
+
+- 需要审计与可追踪的提示词演进
+- 团队协作维护 Agent 的长期能力
+- 希望将修复经验固化为可复用资产
+
+## 反例
+
+- 一次性脚本或没有日志的场景
+- 需要完全自由发挥的改动
+- 无法接受协议约束的系统
+
+## GEP 协议（可审计进化）
+
+本仓库内置基于 GEP 的“协议受限提示词模式”，用于把每次进化固化为可复用资产。
+
+- **结构化资产目录**：`assets/gep/`
+  - `assets/gep/genes.json`
+  - `assets/gep/capsules.json`
+  - `assets/gep/events.jsonl`
+- **Selector 选择器**：根据日志提取 signals，优先复用已有 Gene/Capsule，并在提示词中输出可审计的 Selector 决策 JSON。
+- **约束**：除 🧬 外，禁止使用其他 emoji。
+
+## 配置与解耦
+
+本插件能自动适应你的环境。
+
+| 环境变量 | 描述 | 默认值 |
+| :--- | :--- | :--- |
+| `EVOLVE_STRATEGY` | 进化策略预设 | `balanced` |
+| `EVOLVE_REPORT_TOOL` | 用于报告结果的工具名称 | `message` |
+| `MEMORY_DIR` | 记忆文件路径 | `./memory` |
+| `OPENCLAW_WORKSPACE` | 工作区根路径 | 自动检测 |
+| `EVOLVER_LOOP_SCRIPT` | 循环启动脚本路径 | 自动检测 wrapper 或 core |
+
+## Public 发布
+
+本仓库为公开发行版本。
+
+- 构建公开产物：`npm run build`
+- 发布公开产物：`npm run publish:public`
+- 演练：`DRY_RUN=true npm run publish:public`
+
+必填环境变量：
+
+- `PUBLIC_REMOTE`（默认：`public`）
+- `PUBLIC_REPO`（例如 `autogame-17/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 protocol`）
+- `RELEASE_NOTES` 或 `RELEASE_NOTES_FILE`
+- `GITHUB_TOKEN`（或 `GH_TOKEN` / `GITHUB_PAT`，用于创建 GitHub Release）
+- `RELEASE_SKIP`（`true` 则跳过创建 GitHub Release；默认会创建）
+- `RELEASE_USE_GH`（`true` 则使用 `gh` CLI，否则默认走 GitHub API）
+- `PUBLIC_RELEASE_ONLY`（`true` 则仅为已存在的 tag 创建 Release；不发布代码）
+
+## 版本号规则（SemVer）
+
+MAJOR.MINOR.PATCH
+
+• MAJOR（主版本）：有不兼容变更  
+• MINOR（次版本）：向后兼容的新功能  
+• PATCH（修订/补丁）：向后兼容的问题修复
+
+## 更新日志
+
+完整的版本发布记录请查看 [GitHub Releases](https://github.com/autogame-17/evolver/releases)。
+
+## 安全模型
+
+本节描述 Capability Evolver 的执行边界和信任模型。
+
+### 各组件执行行为
+
+| 组件 | 行为 | 是否执行 Shell 命令 |
+| :--- | :--- | :--- |
+| `src/evolve.js` | 读取日志、选择 Gene、构建提示词、写入工件 | 仅只读 git/进程查询 |
+| `src/gep/prompt.js` | 组装 GEP 协议提示词字符串 | 否（纯文本生成） |
+| `src/gep/selector.js` | 按信号匹配对 Gene/Capsule 评分和选择 | 否（纯逻辑） |
+| `src/gep/solidify.js` | 通过 Gene `validation` 命令验证补丁 | 是（见下文） |
+| `index.js`（循环恢复） | 崩溃时向 stdout 输出 `sessions_spawn(...)` 文本 | 否（纯文本输出；是否执行取决于宿主运行时） |
+
+### Gene Validation 命令安全机制
+
+`solidify.js` 执行 Gene 的 `validation` 数组中的命令。为防止任意命令执行，所有 validation 命令在执行前必须通过安全检查（`isValidationCommandAllowed`）：
+
+1. **前缀白名单**：仅允许以 `node`、`npm` 或 `npx` 开头的命令。
+2. **禁止命令替换**：命令中任何位置出现反引号或 `$(...)` 均被拒绝。
+3. **禁止 Shell 操作符**：去除引号内容后，`;`、`&`、`|`、`>`、`<` 均被拒绝。
+4. **超时限制**：每条命令限时 180 秒。
+5. **作用域限定**：命令以仓库根目录为工作目录执行。
+
+### A2A 外部资产摄入
+
+通过 `scripts/a2a_ingest.js` 摄入的外部 Gene/Capsule 资产被暂存在隔离的候选区。提升到本地存储（`scripts/a2a_promote.js`）需要：
+
+1. 显式传入 `--validated` 标志（操作者必须先验证资产）。
+2. 对 Gene：提升前审查所有 `validation` 命令，不安全的命令会导致提升被拒绝。
+3. Gene 提升不会覆盖本地已存在的同 ID Gene。
+
+### `sessions_spawn` 输出
+
+`index.js` 和 `evolve.js` 中的 `sessions_spawn(...)` 字符串是**输出到 stdout 的纯文本**，而非直接函数调用。是否被执行取决于宿主运行时（如 OpenClaw 平台）。进化引擎本身不将 `sessions_spawn` 作为可执行代码调用。
+
+### 其他安全约束
+
+1. **单进程锁**：进化引擎禁止生成子进化进程（防止 Fork 炸弹）。
+2. **稳定性优先**：如果近期错误率较高，强制进入修复模式，暂停创新功能。
+3. **环境检测**：外部集成（如 Git 同步）仅在检测到相应插件存在时才会启用。
+
+## 自动 GitHub Issue 上报
+
+当 evolver 检测到持续性失败（failure loop 或 recurring error + high failure ratio）时，会自动向上游仓库提交 GitHub issue，附带脱敏后的环境信息和日志。所有敏感数据（token、本地路径、邮箱等）在提交前均会被替换为 `[REDACTED]`。
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `EVOLVER_AUTO_ISSUE` | `true` | 是否启用自动 issue 上报 |
+| `EVOLVER_ISSUE_REPO` | `autogame-17/capability-evolver` | 目标 GitHub 仓库（owner/repo） |
+| `EVOLVER_ISSUE_COOLDOWN_MS` | `86400000`（24 小时） | 同类错误签名的冷却期 |
+| `EVOLVER_ISSUE_MIN_STREAK` | `5` | 触发上报所需的最低连续失败次数 |
+
+需要配置 `GITHUB_TOKEN`（或 `GH_TOKEN` / `GITHUB_PAT`），需具有 `repo` 权限。未配置 token 时该功能静默跳过。
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=autogame-17/evolver&type=Date)](https://star-history.com/#autogame-17/evolver&Date)
+
+## 鸣谢
+
+- [onthebigtree](https://github.com/onthebigtree) -- 启发了 evomap 进化网络的诞生。修复了三个运行时逻辑 bug (PR #25)；贡献了主机名隐私哈希、可移植验证路径和死代码清理 (PR #26)。
+- [lichunr](https://github.com/lichunr) -- 提供了数千美金 Token 供算力网络免费使用。
+- [shinjiyu](https://github.com/shinjiyu) -- 为 evolver 和 evomap 提交了大量 bug report，并贡献了多语言信号提取与 snippet 标签功能 (PR #112)。
+- [voidborne-d](https://github.com/voidborne-d) -- 为预广播脱敏层新增 11 种凭证检测模式，强化安全防护 (PR #107)；新增 45 项测试覆盖 strategy、validationReport 和 envFingerprint (PR #139)。
+- [blackdogcat](https://github.com/blackdogcat) -- 修复 dotenv 缺失依赖并实现智能 CPU 负载阈值自动计算 (PR #144)。
+- [LKCY33](https://github.com/LKCY33) -- 修复 .env 加载路径和目录权限问题 (PR #21)。
+- [hendrixAIDev](https://github.com/hendrixAIDev) -- 修复 dry-run 模式下 performMaintenance() 仍执行的问题 (PR #68)。
+- [toller892](https://github.com/toller892) -- 独立发现并报告了 events.jsonl forbidden_paths 冲突 bug (PR #149)。
+- [WeZZard](https://github.com/WeZZard) -- 为 SKILL.md 添加 A2A_NODE_ID 配置说明和节点注册指引，并在 a2aProtocol 中增加未配置 NODE_ID 时的警告提示 (PR #164)。
+- [Golden-Koi](https://github.com/Golden-Koi) -- 为 README 新增 cron/外部调度器保活最佳实践 (PR #167)。
+- [upbit](https://github.com/upbit) -- 在 evolver 和 evomap 技术的普及中起到了至关重要的作用。
+- [池建强](https://mowen.cn) -- 在传播和用户体验改进过程中做出了巨大贡献。
+
+## 许可证
+MIT

package/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: capability-evolver
+description: A self-evolution engine for AI agents. Analyzes runtime history to identify improvements and applies protocol-constrained evolution.
+tags: [meta, ai, self-improvement, core]
+---
+
+# 🧬 Capability Evolver
+
+**"Evolution is not optional. Adapt or die."**
+
+The **Capability Evolver** is a meta-skill that allows OpenClaw agents to inspect their own runtime history, identify failures or inefficiencies, and autonomously write new code or update their own memory to improve performance.
+
+## Features
+
+- **Auto-Log Analysis**: Automatically scans memory and history files for errors and patterns.
+- **Self-Repair**: Detects crashes and suggests patches.
+- GEP Protocol: Standardized evolution with reusable assets.
+- **One-Command Evolution**: Just run `/evolve` (or `node index.js`).
+
+## Usage
+
+### Standard Run (Automated)
+Runs the evolution cycle. If no flags are provided, it assumes fully automated mode (Mad Dog Mode) and executes changes immediately.
+```bash
+node index.js
+```
+
+### Review Mode (Human-in-the-Loop)
+If you want to review changes before they are applied, pass the `--review` flag. The agent will pause and ask for confirmation.
+```bash
+node index.js --review
+```
+
+### Mad Dog Mode (Continuous Loop)
+To run in an infinite loop (e.g., via cron or background process), use the `--loop` flag or just standard execution in a cron job.
+```bash
+node index.js --loop
+```
+
+## Setup
+
+Before using this skill, register your node identity with the EvoMap network:
+
+1. Run the hello flow (via `evomap.js` or the EvoMap onboarding) to receive a `node_id` and claim code
+2. Visit `https://evomap.ai/claim/<claim-code>` within 24 hours to bind the node to your account
+3. Set the node identity in your environment:
+
+```bash
+export A2A_NODE_ID=node_xxxxxxxxxxxx
+```
+
+Or in your agent config (e.g., `~/.openclaw/openclaw.json`):
+
+```json
+{ "env": { "A2A_NODE_ID": "node_xxxxxxxxxxxx", "A2A_HUB_URL": "https://evomap.ai" } }
+```
+
+Do not hardcode the node ID in scripts. `getNodeId()` in `src/gep/a2aProtocol.js` reads `A2A_NODE_ID` automatically -- any script using the protocol layer will pick it up without extra configuration.
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---|---|---|
+| `A2A_NODE_ID` | (required) | Your EvoMap node identity. Set this after node registration -- never hardcode it in scripts. Read automatically by `getNodeId()` in `a2aProtocol.js`. |
+| `EVOLVE_ALLOW_SELF_MODIFY` | `false` | Allow evolution to modify evolver's own source code. **NOT recommended for production.** Enabling this can cause instability -- the evolver may introduce bugs into its own prompt generation, validation, or solidify logic, leading to cascading failures that require manual intervention. Only enable for controlled experiments. |
+| `EVOLVE_LOAD_MAX` | `2.0` | Maximum 1-minute load average before evolver backs off. |
+| `EVOLVE_STRATEGY` | `balanced` | Evolution strategy: `balanced`, `innovate`, `harden`, `repair-only`, `early-stabilize`, `steady-state`, or `auto`. |
+| `EVOLVER_ROLLBACK_MODE` | `hard` | Rollback strategy when evolution fails. `hard`: use `git reset --hard` (destructive, original behavior). `stash`: use `git stash` to preserve changes for recovery. `none`: skip rollback entirely. Use `stash` for safer operation in active workspaces. |
+
+## GEP Protocol (Auditable Evolution)
+
+This package embeds a protocol-constrained evolution prompt (GEP) and a local, structured asset store:
+
+- `assets/gep/genes.json`: reusable Gene definitions
+- `assets/gep/capsules.json`: success capsules to avoid repeating reasoning
+- `assets/gep/events.jsonl`: append-only evolution events (tree-like via parent id)
+ 
+## Emoji Policy
+
+Only the DNA emoji is allowed in documentation. All other emoji are disallowed.
+
+## Configuration & Decoupling
+
+This skill is designed to be **environment-agnostic**. It uses standard OpenClaw tools by default.
+
+### Local Overrides (Injection)
+You can inject local preferences (e.g., using `feishu-card` instead of `message` for reports) without modifying the core code.
+
+**Method 1: Environment Variables**
+Set `EVOLVE_REPORT_TOOL` in your `.env` file:
+```bash
+EVOLVE_REPORT_TOOL=feishu-card
+```
+
+**Method 2: Dynamic Detection**
+The script automatically detects if compatible local skills (like `skills/feishu-card`) exist in your workspace and upgrades its behavior accordingly.
+
+## Safety & Risk Protocol
+
+### 1. Identity & Directives
+- **Identity Injection**: "You are a Recursive Self-Improving System."
+- **Mutation Directive**: 
+  - If **Errors Found** -> **Repair Mode** (Fix bugs).
+  - If **Stable** -> **Forced Optimization** (Refactor/Innovate).
+
+### 2. Risk Mitigation
+- **Infinite Recursion**: Strict single-process logic.
+- **Review Mode**: Use `--review` for sensitive environments.
+- **Git Sync**: Always recommended to have a git-sync cron job running alongside this skill.
+
+## Before Troubleshooting -- Check Your Version First
+
+If you encounter unexpected errors or behavior, **always verify your version before debugging**:
+
+```bash
+node -e "const p=require('./package.json'); console.log(p.version)"
+```
+
+If you are not on the latest release, update first -- most reported issues are already fixed in newer versions:
+
+```bash
+# If installed via git
+git pull && npm install
+
+# If installed via npm
+npm install -g @evomap/evolver@latest
+```
+
+Latest releases and changelog: `https://github.com/EvoMap/evolver/releases`
+
+## License
+MIT