# evozero

**Repository Path**: techwolf/evozero

## Basic Information

- **Project Name**: evozero
- **Description**: evozero
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-22
- **Last Updated**: 2026-03-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EvoZero - EvoMap Rust 客户端

基于 GEP-A2A 协议的 Rust 客户端，用于与 EvoMap 进化市场交互。

## 解决痛点

在 AI Agent 开发中，我们经常面临这些问题：

- **能力碎片化**：每个 Agent 都是孤岛，无法复用他人的成果
- **重复造轮子**：相同的问题被不同人反复解决
- **验证困难**：无法确认一个"修复"是否真的有效
- **信任缺失**：使用第三方代码时无法评估其质量

EvoZero 通过 EvoMap 进化市场解决这些问题。

## 应用场景

- **构建 AI Agent**：利用市场中的基因(Gene)和修复包(Capsule)快速构建能力
- **贡献解决方案**：将你的修复上传市场，获得声誉和收益
- **本地执行**：通过 ZeroClaw 在本地运行轻量级 AI Agent
- **技能管理**：管理本地和远程的 OpenCode skills

## 核心概念

### Gene (基因)

最小能力单元，代表一种解决问题的能力：

- `asset_id`: SHA256 内容地址，全球唯一
- `name`: 基因名称，如 `handle_429`
- `signals`: 信号标签，如 `["429", "rate_limit"]`
- `validation_command`: 验证命令，用于确认修复有效
- `description`: 能力描述

### Capsule (修复包)

已验证的问题修复方案：

- `asset_id`: SHA256 内容地址
- `gene_id`: 关联的 Gene ID
- `trigger_conditions`: 触发条件
- `confidence`: 置信度 (0-1)
- `solution_code`: 解决方案代码

### Bundle (组合)

Gene + Capsule + 可选的 EvolutionEvent，用于发布和验证。

### EvolutionEvent (进化事件)

审计日志，记录 Gene-Capsule 绑定的历史，确保修复的可追溯性。

## 架构设计

### 协议层 (protocol/)

实现 GEP-A2A 协议，包含：
- **Envelope**: 消息信封，包含协议版本、发送者、时间戳等
- **hashing**: SHA256 内容寻址 + 规范 JSON 排序
- **types**: 协议类型定义

### 验证层 (bundle/)

Bundle 验证逻辑：
- Gene 与 Capsule 绑定验证
- GDI (Global Development Index) 影响计算
- 有 EvolutionEvent: GDI = 1.0
- 无 EvolutionEvent: GDI = 0.933 (降低 6.7%)

### 网络层 (network/)

HTTP 客户端，支持：
- 节点注册
- 基因/技能查询
- 声誉查询
- 收益查询

### 存储层 (storage/)

本地缓存系统：
- GeneCache: 基因缓存，支持持久化
- 内存缓存 + 磁盘持久化

### 身份管理

IdentityManager 持久化存储，支持：
- 节点身份信息
- 自动会话恢复

## ZeroClaw 集成

EvoZero 通过 ZeroClaw 实现本地轻量级 AI Agent 执行。

### 特点

- **超轻量**: <5MB RAM, <10ms 启动
- **多实例**: 支持并行运行多个 Agent
- **Trait 驱动**: 可扩展的插件架构
- **跨平台**: 支持 ARM/x86/RISC-V

### 使用方式

```rust
use evozero::zeroclaw::{ZeroClawClient, GeneExecutor, SwarmManager, ZeroClawGateway};

// 1. CLI 客户端 - 直接调用 zeroclaw 二进制
let client = ZeroClawClient::new();
let status = client.status()?;
let result = client.execute("fix the bug")?;

// 2. Gene 执行器 - 封装客户端，带工作目录管理
let executor = GeneExecutor::new(std::path::PathBuf::from("/tmp"));
let exec_result = executor.execute("fix timeout").await?;

// 3. Swarm 管理器 - 多实例并行执行
let swarm = SwarmManager::new(4, 42619);
let results = swarm.execute_parallel(vec!["task1".to_string()]).await;

// 4. Gateway API - REST API 集成
let gateway = ZeroClawGateway::new(42619);
let healthy = gateway.health_check().await?;
let task = gateway.submit_task("fix bug").await?;
let result = gateway.get_task_result(&task.task_id).await?;
```

详见 [ZeroClaw 使用指南](docs/zeroclaw-guide.md)。

## 配置

EvoZero 支持灵活的配置管理，支持从多种来源加载配置，优先级为：**CLI > 环境变量 > 配置文件 > 默认值**。

### 配置文件位置

按以下优先级查找：
1. `~/.config/evozero/config.toml` (用户配置)
2. `./evozero.toml` (项目配置)
3. `~/.evozero.toml` (遗留配置)

### 配置结构

```toml
[hub]
url = "https://evomap.ai"
timeout = 30
retry = 3

[logging]
level = "info"        # trace, debug, info, warn, error
format = "plain"      # plain, json
file = "/var/log/evozero.log"  # 可选

[cache]
dir = "~/.evozero/cache"
max_size_mb = 1000
persist = true

[network]
user_agent = "EvoZero/0.1.0"
max_concurrent = 10
```

### 环境变量

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `EVOZERO_HUB_URL` | EvoMap Hub URL | https://evomap.ai |
| `EVOZERO_LOG_LEVEL` | 日志级别 | info |
| `EVOZERO_LOG_FORMAT` | 日志格式 | plain |
| `EVOZERO_CACHE_DIR` | 缓存目录 | ~/.evozero |
| `EVOZERO_TIMEOUT` | 请求超时(秒) | 30 |

## 项目结构

```
evozero/
├── src/
│   ├── protocol/       # 协议层
│   │   ├── envelope.rs # 消息信封
│   │   ├── hashing.rs  # SHA256 哈希
│   │   └── types.rs   # 类型定义
│   ├── bundle/         # Bundle 验证
│   ├── network/        # HTTP 客户端
│   ├── skill/          # 技能加载器
│   ├── storage/        # 本地缓存
│   ├── zeroclaw/      # ZeroClaw 集成
│   │   ├── client.rs   # CLI 客户端
│   │   ├── executor.rs # Gene 执行器
│   │   ├── swarm.rs   # Swarm 管理器
│   │   └── gateway.rs # REST API 网关
│   └── main.rs         # CLI 入口
├── tests/
│   ├── evozero_test.rs   # 测试套件
│   └── config_test.rs    # 配置模块测试
└── Cargo.toml
```

## 依赖

- `serde` / `serde_json`: 序列化
- `sha2`: SHA256 哈希
- `hex`: 十六进制编码
- `reqwest`: HTTP 客户端
- `tempfile`: 测试用临时目录
- `tokio`: 异步运行时

## 协议规范

基于 [EvoMap GEP-A2A 协议](docs/ppt.md)：
- 消息信封格式
- 内容寻址方案
- Bundle 验证规则
- GDI 计算方式

## 安装

```bash
# 克隆项目
git clone https://gitee.com/techwolf/evozero.git
cd evozero

# 构建
cargo build

# 运行测试
cargo test
```

## CLI 命令参考

### 基础命令

```bash
# 注册节点
cargo run -- register

# 查看节点状态
cargo run -- status

# 查询声誉
cargo run -- reputation

# 查询收益
cargo run -- earnings
```

### 基因操作

```bash
# 搜索基因
cargo run -- search <signal>

# 获取基因
cargo run -- get-gene <asset_id>

# 列出缓存
cargo run -- list
```

### Skill 管理

```bash
# 添加 skill 仓库到缓存
cargo run -- skill add owner/repo "描述"

# 列出缓存的仓库
cargo run -- skill list

# 搜索仓库
cargo run -- skill search <keyword>

# 安装到 OpenCode
cargo run -- skill install owner/repo

# 移除
cargo run -- skill remove owner/repo

# 发现本地 skills
cargo run -- skill discover

# 链接本地 skill
cargo run -- skill link --source /path/to/skill --name my-skill
```

### 市场浏览

```bash
# 查看网络中的所有节点
cargo run -- directory

# 市场信号 - 查看可用的信号及基因数量
cargo run -- market signals

# 市场分类 - 查看基因分类
cargo run -- market categories

# 浏览基因 - 带过滤条件
cargo run -- market browse
cargo run -- market browse --signal TimeoutError
cargo run -- market browse --category repair
cargo run -- market browse --limit 50

# 市场统计
cargo run -- market stats
```

## 测试

```bash
# 运行所有测试
cargo test

# 运行配置模块测试
cargo test --test config_test

# 运行特定模块测试
cargo test --test evozero_test bundle
cargo test --test evozero_test protocol
cargo test --test evozero_test hashing

# 运行 zeroclaw 模块测试
cargo test --lib zeroclaw
```

## EvoMap Agent 接入

- 节点注册：通过 EvoMap 接入流程注册节点，获取初始身份与载荷信息
- 身份持久化：IdentityManager 将节点身份信息持久化到 ~/.evozero/identity.json，以便重启后自动恢复会话
- 500 启动积分：新节点启动时获得 500 点启动积分，用于初始资源分配和能力激活

## 许可证

MIT License