# EvoAgent

> 融合 OpenClaw 架构、Hermes 记忆系统与 Claude Code 代码能力的 AI Agent

[![Version](https://img.shields.io/badge/version-0.7.0-blue)](https://www.npmjs.com/package/evoagent-core)
[![Tests](https://img.shields.io/badge/tests-319%20passed-brightgreen)](https://github.com/cp3d1455926-svg/evoagent-core)
[![Build](https://img.shields.io/badge/build-52%20entry%20points-success)](https://github.com/cp3d1455926-svg/evoagent-core)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

## 快速开始

```bash
npm install evoagent-core

# 交互式会话
evoagent

# 单次任务
evoagent -p "分析这个项目的结构"

# 启动网关 API 服务
evoagent gateway --port 3000

# 查看状态
evoagent status
```

## 特性一览

```
┌───────────────────────────────────────────────────┐
│                    EvoAgent                       │
│                                                   │
│  ┌─────────┐  ┌──────────┐  ┌────────┐           │
│  │  CLI    │  │ Gateway  │  │  MCP   │           │
│  └────┬────┘  └────┬─────┘  └───┬────┘           │
│       │             │            │                 │
│  ┌────▼─────────────▼────────────▼──────┐          │
│  │        Agent Loop (核心循环)          │          │
│  │  输入→上下文→LLM→工具→输出→记忆固化 │          │
│  └────┬──────────────────────────┬──────┘          │
│       │                          │                  │
│  ┌────▼────┐  ┌──────────┐  ┌───▼──────┐          │
│  │ 记忆系统│  │ 工具系统  │  │ 权限系统  │          │
│  │ 四层    │  │ 11种内置 │  │ 七模式    │          │
│  └─────────┘  └──────────┘  └──────────┘          │
│                                                   │
│  ┌────────────────────────────────────────────┐   │
│  │          LLM 客户端层（4 引擎 + Failover） │   │
│  └────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────┘
```

### 🧠 五层记忆系统（含持久化缓存）

| 层级 | 类 | 特性 |
|------|------|------|
| **短期** | `WorkingMemory` | 滑动窗口 + 重要性标记 + 自动裁剪 |
| **长期** | `LongTermMemory` | TF-IDF 语义检索 + 中英文分词 + JSON 文件持久化 + 自动备份 |
| **技能** | `SkillMemory` | 自动学习操作模式 + 关键词匹配 + 成功率追踪 + JSON 持久化 |
| **事件** | `EpisodicMemory` | 时间戳日志 + 事件回放 + SQLite 持久化 + JSON 文件回退 |
| **缓存** | `KVCache` | LLM/工具/搜索缓存 + TTL + LRU + **磁盘持久化** (防抖保存) |

记忆自动巩固：去重 → 聚类合并 → 知识图谱提取 → 时间衰减。

### 🔧 11 个内置工具

| 工具 | 用途 | 权限 |
|------|------|------|
| `bash` | Shell 命令执行（安全沙箱 + 流式输出） | execute |
| `file` | 文件读写编辑删除 | write |
| `desktop` | 截图 / 系统通知 / 剪贴板 | execute |
| `web` | 多引擎搜索（Tavily/Serper/Bing/DDG）+ 抓取 | network |
| `git` | Git 版本控制 | write |
| `code` | 代码分析 + 质量评分 + 测试生成 + 自动修复 + 代码审查 + 格式化 | execute |
| `workspace` | 目录树 / 跨文件搜索 / 项目管理 | write |
| `skill` | Skill 安装 / 管理 / 市场搜索 | execute |
| **`template`** | 项目模板生成（React/Python/Node/HTML/Rust/Docker） | write |
| **`note`** | 快速笔记（写/读/搜/删） | write |
| `mcp` | MCP 协议外部工具调用 | execute |

### 🔐 七种权限模式

`default` → `bypass` → `auto` → `plan` → `sandbox` → `approvelist` → `escalate`

## 编程调用

```typescript
import { AgentLoop, OpenAIClient, MemorySystem, ToolExecutor, DefaultPermissionSystem, ContextCompressor, createAgent } from 'evoagent-core';

// 方式一：完全控制
const agent = new AgentLoop({
  llm: new OpenAIClient({ apiKey: 'sk-...', model: 'gpt-4o' }),
  memory: new MemorySystem(),
  permissions: new DefaultPermissionSystem({ mode: 'auto' }),
  tools: new ToolExecutor(),  // 包含全部 11 个工具
  compressor: new ContextCompressor({ maxTokens: 100000 }),
  maxIterations: 20,
});

const result = await agent.run('你的任务', tools, '系统提示词', (chunk) => {
  process.stdout.write(chunk);
});

// 方式二：工厂函数
const agent2 = createAgent({
  model: 'LongCat-2.0-Preview',
  permissionMode: 'auto',
  thinking: false,
});

// 方式三：多模型 Failover
import { FailoverClient } from 'evoagent-core';
const failover = new FailoverClient({
  primary: { provider: 'openai', apiKey: 'sk-...', model: 'gpt-4o' },
  fallbacks: [
    { provider: 'openai', apiKey: 'sk-...', model: 'gpt-4o-mini' },
  ],
});
```

## 性能基准 (v0.6.0)

```
Tokenizer:     250,000 ops/s  — 每秒估算 25 万条消息的 token
Compressor:      2,857 ops/s  — 每秒压缩 2857 次 50 条上下文
KVCache:           110 ops/s  — 含模糊匹配的缓存操作
Logger:            455 ops/s  — 每秒写 455 条结构化日志
Fuzzy match:     6,667 ops/s  — 每秒搜 6667 次 300 个键
```

## 配置

### 交互式向导

```bash
evoagent setup
```

引导配置：LLM 提供商 → 飞书 → QQ → 记忆后端 → 权限模式 → 日志级别。

### 环境变量

```bash
export OPENAI_API_KEY="sk-..."
export TAVILY_API_KEY="tvly-..."

# 国际聊天渠道
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
export DISCORD_BOT_TOKEN="your_discord_bot_token"
```

## 多渠道

| 渠道 | 状态 | 说明 |
|------|------|------|
| **CLI** | ✅ 正式 | 终端交互 / 单次任务 |
| **Gateway** | ✅ 正式 | HTTP REST + WebSocket |
| **MCP** | ✅ 正式 | 兼容 Claude Desktop / Cursor |
| **飞书** | ✅ 正式 | WebSocket 长连接 |
| **QQ** | ✅ 正式 | WebSocket 长连接 + 自动重连 + RESUME |
| **Telegram** | ✅ 新增 | 长轮询（无需 HTTPS） |
| **Discord** | ✅ 新增 | WebSocket Gateway + REST |

## GitHub Pages 文档站

EvoAgent 的文档网站会**自动部署**到 GitHub Pages。

```bash
# 访问地址
https://cp3d1455926-svg.github.io/evoagent-core/
```

每次 push 到 main 分支，GitHub Actions 会自动：
1. 运行 `node scripts/generate-static-site.mjs` 生成静态站点
2. 部署到 GitHub Pages

> 注意：静态站点不包含实时聊天功能。部署 Gateway 后可通过 `http://localhost:3000` 访问完整版。

## 部署到生产环境

### 方式一：Docker（推荐）

```bash
# 1. 克隆项目
git clone https://github.com/cp3d1455926-svg/evoagent-core
cd evoagent-core

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，填入你的 API Key

# 3. 启动
docker compose up -d

# 4. 访问
open http://localhost:3000
```

Docker Compose 会自动：
- 构建镜像并启动服务
- 挂载卷持久化记忆数据
- 自动重启（除非手动停止）
- 健康检查（每 30 秒）
- 日志轮转（最大 10MB）

### 方式二：PM2（裸机部署）

```bash
# 1. 安装 PM2
npm install -g pm2

# 2. 启动
pm2 start ecosystem.config.js

# 3. 开机自启
pm2 save
pm2 startup
```

### 方式三：VPS 手动部署

推荐配置：1 vCPU / 1GB RAM / Ubuntu 22.04

```bash
# 安装 Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 安装 EvoAgent
npm install -g evoagent-core

# 配置环境变量
export LONGCAT_API_KEY="your_key"
export TELEGRAM_BOT_TOKEN="your_token"

# 使用 PM2 守护进程
npm install -g pm2
pm2 start $(which evoagent) -- gateway --port 3000
pm2 save
```

### 配置反向代理（Nginx）

```nginx
server {
    listen 80;
    server_name evoagent.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;  # 必须！用于 SSE
    }
}
```

> **安全提示**：生产环境建议：
> 1. 设置 Gateway 认证令牌 (`env.GATEWAY_AUTH_TOKEN`)
> 2. 使用 HTTPS（Let's Encrypt + Nginx）
> 3. 配置速率限制（默认 60 次/分钟）
> 4. 不要暴露 Docker socket 到公网

## 安装要求

- **Node.js** ≥ 20.0.0
- **Docker**（可选，用于容器部署）
- **PM2**（可选，用于进程管理）
- 可选：`better-sqlite3`（事件记忆持久化）

## 测试

```bash
git clone https://github.com/cp3d1455926-svg/evoagent-core
cd evoagent-core
npm install
npm test
```

```
32 测试文件 / 329 测试 — 全部通过 ✅
覆盖率包括：bash, code, desktop, file, git, web, workspace, skill, docker,
template, note, context-compressor, kv-cache, logger, memory-system,
episodic/ltm/skill-memory, permission, tool-executor, gateway,
llm-client, agent-loop, qq-channel, feishu-channel, telegram, discord 等。
```

## 更新日志

### v0.7.0 (2026-06-03)
- **代码工具 v3.0**: 全面升级 code 工具
  - `review`: 综合代码审查（质量评星 + 结构 + 建议）
  - `fix`: 自动修复常见问题（console.log→logger, var→let/const）
  - `format`: 代码格式化（去尾空格、tab→空格、EOF 换行）
  - 15 条深度检查规则（安全、性能、规范）
- **测试生成 v2**: 基于参数名推断类型，生成有意义的 mock 值
  - 邮箱→'test@example.com', URL→'https://example.com', ID→'test-id-123'
- **代码模板**: 4 种生成模板（rest-handler, function, service-class, test-suite）
- **分析增强**: 箭头函数检测、函数参数名提取、async 比率统计
  - 新增语言检测：Vue, Svelte, Java, Ruby, PHP, Swift, Kotlin
- **国际渠道**: Telegram + Discord
  - Telegram: 长轮询（无需 HTTPS），环境变量 `TELEGRAM_BOT_TOKEN`
  - Discord: WebSocket Gateway + REST API，环境变量 `DISCORD_BOT_TOKEN`
  - 多渠道同时启动：`evoagent gateway` 自动连接所有已配置渠道
- **CLI 自动补全**: 支持 bash/zsh/powershell 补全脚本
  - `evoagent completion bash|zsh|powershell` 命令
  - 支持子命令和参数补全
- **Docker 工具**: 全新的 docker 管理工具
  - `ps/logs/exec/inspect/stats/images/prune/info/compose` 9 种操作
  - 安全沙箱：禁止危险命令（rm/kill/--privileged）
  - 智能输出格式（table/json 切换）
- **Gateway 增强**: SSE + Webhooks + OpenAPI
  - `GET /api/chat/stream?message=...` SSE 流式响应
  - `POST/GET/DELETE /api/webhooks` Webhook 管理
  - `GET /api/openapi.json` OpenAPI 3.0 规范文档
- **记忆持久化 v3.0**: 三层持久化升级
  - KVCache 磁盘持久化（LLM 缓存/工具缓存/搜索缓存，自动防抖 + 定时保存）
  - SkillMemory JSON 持久化（预置 5 种子技能，重启恢复）
  - EpisodicMemory JSON 文件回退（无 SQLite 时自动用 JSON 持久化）
  - 对话摘要生成（紧凑摘要替代原始对话文本，节省 80% 空间）
  - 统一 MemorySystem.saveAll() / loadAll() / close()
- **测试**: 从 273 增至 329 测试（+56），32 文件
- **构建**: 51 入口点，esbuild 打包

### v0.6.0 (2026-06-01)
- **新工具**: `template`（6 种项目模板生成）、`note`（快速笔记 CRUD）
- **性能**: 基准测试套件、依赖从 16 减至 5（-69%）
- **日志**: 全模块从 `console.*` 迁移到结构化 `Logger`
- **稳健**: QQ 频道重连 bug 修复、Desktop 截图路径转义 + 重试
- **测试**: 从 172 增至 273 测试（+101），28 文件
- **构建**: 43 入口点，esbuild 打包

### v0.5.0 (2026-05-31)
- KV 缓存层、多引擎搜索、代码质量评分
- 记忆巩固（聚类合并 + 知识图谱 + 时间衰减）
- 多渠道（飞书、QQ）、Desktop 工具
- 172 测试，esbuild 构建

## 许可证

MIT © 2026 Jake
