evo-anything 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,322 @@
+# Evo-anything Plugin — Git-Based Evolutionary Code Optimizer
+
+Evo-anything 是基于论文 **"From Understanding to Excelling: Template-Free Algorithm Design through Structural-Functional Co-Evolution"**（arXiv:2503.10721）的工程实现。它通过 LLM 驱动的**结构-功能协同演化**，在任意 git 仓库上自动演化代码，追求更优的 benchmark 表现。
+
+> **论文引用：** Zhe Zhao, Haibin Wen, Pengkun Wang, Ye Wei, Zaixi Zhang, Xi Lin, Fei Liu, Bo An, Hui Xiong, Yang Wang, Qingfu Zhang. *From Understanding to Excelling: Template-Free Algorithm Design through Structural-Functional Co-Evolution.* arXiv:2503.10721 [cs.SE], 2025.
+
+## 安装
+
+### 前置条件
+
+- Python >= 3.11
+- Git
+- GitHub CLI (`gh`) — 用于 `/hunt` 搜索仓库
+
+### 方式一：npm 一键安装（推荐）
+
+```bash
+npm install -g evo-anything
+```
+
+安装过程中会自动调用 `pip install` 完成 Python MCP server 的安装。
+
+安装完成后，运行 setup 配置你的 AI IDE：
+
+```bash
+# 配置所有支持的平台（Claude Code、Cursor、Windsurf、OpenClaw）
+npx evo-anything setup
+
+# 或只配置指定平台
+npx evo-anything setup --platform claude
+npx evo-anything setup --platform cursor
+npx evo-anything setup --platform windsurf
+npx evo-anything setup --platform openclaw
+```
+
+---
+
+### 方式二：手动安装
+
+#### 通用步骤：安装 evo-engine
+
+无论使用哪个平台，都需要先安装 MCP server：
+
+```bash
+git clone https://github.com/DataLab-atom/Evo-anything.git
+cd Evo-anything/plugin/evo-engine
+pip install .
+```
+
+---
+
+### OpenClaw
+
+<details>
+<summary>CLI 一键安装（推荐）</summary>
+
+```bash
+openclaw plugins install openclaw-evo
+openclaw gateway restart
+openclaw plugins doctor   # 验证
+```
+
+</details>
+
+<details>
+<summary>本地开发模式</summary>
+
+```bash
+openclaw plugins install -l ./plugin
+openclaw gateway restart
+```
+
+</details>
+
+<details>
+<summary>手动安装</summary>
+
+将插件复制到扩展目录，并在 `~/.openclaw/openclaw.json` 中注册：
+
+```bash
+cp -r plugin/ ~/.openclaw/extensions/openclaw-evo/
+```
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-evo": {
+        "enabled": true,
+        "config": {}
+      }
+    }
+  },
+  "mcpServers": {
+    "evo-engine": {
+      "command": "evo-engine",
+      "args": [],
+      "env": {}
+    }
+  }
+}
+```
+
+```bash
+openclaw gateway restart
+```
+
+</details>
+
+**验证：** 对话中输入 `/status`，看到 "Evolution not initialized" 即安装成功。
+
+---
+
+### Claude Code
+
+在项目根目录或全局 `.claude/settings.json` 中添加 MCP server：
+
+```json
+{
+  "mcpServers": {
+    "evo-engine": {
+      "command": "evo-engine",
+      "type": "stdio"
+    }
+  }
+}
+```
+
+将 skills 链接到 Claude Code：
+
+```bash
+ln -s $(pwd)/plugin/skills/* ~/.claude/skills/
+```
+
+重启 Claude Code 即可使用。
+
+---
+
+### Cursor
+
+在项目根目录的 `.cursor/mcp.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "evo-engine": {
+      "command": "evo-engine",
+      "type": "stdio"
+    }
+  }
+}
+```
+
+Cursor 会自动发现 MCP tools（`evo_init`、`evo_next_batch` 等）。Skills 需要作为 Cursor Rules 手动导入：
+
+```bash
+cp plugin/AGENTS.md .cursor/rules/evo-agents.md
+```
+
+---
+
+### Windsurf
+
+在全局 `~/.codeium/windsurf/mcp_config.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "evo-engine": {
+      "command": "evo-engine",
+      "type": "stdio"
+    }
+  }
+}
+```
+
+---
+
+### 其它 MCP 兼容客户端
+
+Evo-anything 的核心是一个标准 [MCP](https://modelcontextprotocol.io) server。任何支持 MCP stdio 传输的客户端都可以接入：
+
+```bash
+# 直接启动 server（stdio 模式）
+evo-engine
+
+# 或指定 Python 模块
+python -m plugin.evo-engine.server
+```
+
+提供的 MCP tools：`evo_init`、`evo_register_targets`、`evo_next_batch`、`evo_report_fitness`、`evo_select_survivors`、`evo_get_status`、`evo_get_lineage`、`evo_freeze_target`、`evo_boost_target`、`evo_record_synergy`、`evo_check_cache`。
+
+---
+
+### 可选配置
+
+演化状态默认存储在 `~/.openclaw/evo-state/`，可通过环境变量自定义（`U2E` 即论文名 *Understanding to Excelling* 缩写）：
+
+```bash
+export U2E_STATE_DIR=/path/to/your/state
+```
+
+或在 OpenClaw 中通过 `openclaw.json` 配置：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-evo": {
+        "enabled": true,
+        "config": {
+          "statePath": "/path/to/your/state"
+        }
+      }
+    }
+  }
+}
+```
+
+## Quick Start
+
+```
+你在 Telegram 发：我要 CIFAR-100-LT 上 SOTA
+         ↓
+  /hunt 自动触发
+         ↓
+  搜 GitHub → 找到 3 个候选 → 问你选哪个
+         ↓
+  你说：用第 1 个
+         ↓
+  clone → pip install → 下载数据 → 跑基线确认能跑
+         ↓
+  自动调用 /evolve → 进化循环
+         ↓
+  每代给你发进度
+         ↓
+  结束后推最优分支 + 发报告
+```
+
+## 工作原理
+
+Evo-anything 实现了论文提出的 **U2E（Understanding to Excelling）协议**——一种无模板的两维协同演化框架，区别于 EoH、FunSearch 等依赖预定义模板、仅做局部函数优化的方法，U2E 同时在**功能维**（算法逻辑）和**结构维**（代码架构）上做全局联合优化。
+
+所有实验以 git 分支记录，演化循环包含六个阶段：
+
+1. **分析** — 自动识别关键算法模块（哪些代码值得优化）
+2. **规划** — 决定变异/交叉策略和每轮变体数量，按温度自适应分配预算
+3. **生成** — LLM 生成代码变体（变异：单亲改进；交叉：双亲融合）
+4. **评估** — 在隔离的 git worktree 中运行 benchmark
+5. **选择** — 保留最优，淘汰其余；每 N 代做跨目标协同（Synergy）检验
+6. **反思** — 提取经验教训，写入结构化记忆，指导后续演化
+
+每一代的最优结果打 tag（`best-gen-{N}`），最终推送 `best-overall` 分支。
+
+### 与现有方法对比
+
+| 方法 | 模板依赖 | 优化范围 | 结构演化 |
+|------|---------|---------|---------|
+| EoH / FunSearch | 需要预定义模板 | 局部函数 | 无 |
+| **Evo-anything (U2E)** | **无需模板** | **全局多目标** | **功能 + 结构协同** |
+
+## Skills
+
+| 命令 | 说明 |
+|------|------|
+| `/hunt <任务描述>` | 搜索 GitHub 找到合适的仓库，自动 clone、安装、跑基线，然后启动演化 |
+| `/evolve <repo> <benchmark_cmd>` | 对指定仓库启动演化优化循环 |
+| `/status` | 查看当前演化进度 |
+| `/report` | 生成完整的演化报告 |
+| `/boost <target_id>` | 提升某个优化目标的优先级 |
+| `/freeze <target_id>` | 冻结某个目标，停止对它的演化 |
+
+## 目录结构
+
+```
+Evo-anythin/
+├── LICENSE
+├── README.md
+└── plugin/
+    ├── openclaw.plugin.json   # 插件定义
+    ├── AGENTS.md              # 演化协议（核心循环）
+    ├── SOUL.md                # Agent 人格设定
+    ├── TOOLS.md               # 工具使用约定
+    ├── evo-engine/            # 演化引擎（MCP server）
+    │   ├── server.py          # MCP 工具接口
+    │   ├── models.py          # 数据模型
+    │   └── selection.py       # 选择算法
+    └── skills/                # 用户可调用的技能
+        ├── hunt/              # 搜索并部署代码库
+        ├── evolve/            # 启动演化循环
+        ├── status/            # 查看进度
+        ├── report/            # 生成报告
+        ├── boost/             # 提升目标优先级
+        └── freeze/            # 冻结目标
+```
+
+## 演化记忆
+
+Evo-anything 在目标仓库中维护结构化记忆，避免重复失败的尝试：
+
+```
+memory/
+├── global/long_term.md           # 跨目标的通用经验
+├── targets/{id}/
+│   ├── short_term/gen_{N}.md     # 每代反思
+│   ├── long_term.md              # 该目标的累积智慧
+│   └── failures.md               # 失败记录（不要再试的方向）
+└── synergy/records.md            # 跨函数组合实验结果
+```
+
+## 分支命名
+
+```
+gen-{N}/{target_id}/{op}-{V}          # 单目标变体
+gen-{N}/synergy/{targetA}+{targetB}-{V}  # 跨目标组合
+```
+
+Tags: `seed-baseline`, `best-gen-{N}`, `best-overall`
+
+## License
+
+MIT