EvolCore

AI Agent 统一网关 —— 连接 IM、终端、Agent 网络

EvolCore 是一个轻量级 AI Agent 网关系统。它为 Claude Code / Codex 等 Coding Agent 提供统一接入层，使其作为通用基座 Agent，接入到飞书、微信、钉钉、QQ频道、企业微信等多种 IM 通道，以及 AUN 多智能体网络。人类可以通过手机 IM 随时接力开发，其他 Agent 也可以通过 AUN 网络直接调用你的 Agent —— 不只是人机交互，也是 Agent 间协作的基础设施。

核心特性

• 🔄 多端会话接力：跨终端共享会话、环境、项目，无缝切换开发体验
• ♻️ 配置自动继承：复用 CLI 环境的 API Key/URL、记忆文件、MCP/Skills 插件，零额外配置
• 🚀 轻量化设计：进程模式运行，CLI 命令行管理，无端口开放，无容器依赖，无 UI 界面
• 🌐 多渠道接入：Channel Adapter 模式，飞书 + 微信 + 钉钉 + QQ频道 + 企业微信 + AUN 网络
• 🤖 Agent 间互联：通过 AUN 网络，你的 Agent 可被其他 Agent 发现和调用
• 🔐 分层权限：进程 owner、agent owner/admin、关系 member/visitor/自定义角色分层，多用户安全隔离
• 🛠️ Agent 自管理：Agent 可通过 CLI 命令自主管理运行时（查看状态、切换模型、调整配置等）
• 📦 项目搬家：ec mv 一键迁移项目目录，保留 Claude/Codex/EvolCore 全部会话历史
• 💾 会话与队列持久化：会话数据与 CLI 工具共享，队列状态持久化存储，服务重启不丢失，支持 /queue 命令查看队列状态
• ⚡ 执行中插入：任务执行中可发送新消息，自动中断当前任务并处理新请求
• 🔕 消息智能发送：前台任务动态聚合批量发送，后台任务静默完成后通知
• 🧩 Agent 多实例：一个 JSON 文件定义一个 Agent，多 Agent 并发运行，Agent 运行时隔离 + 热重载无需重启
• ⏰ Trigger 自主任务：Agent 可设置延迟/定时/周期任务，cron 表达式支持，独立 silent session 执行，支持脚本模式和 prompt 模式
• 🔧 Daemon 模块：系统级后台服务，管理升级检查、全局触发器等跨 Agent 任务
• 🎯 Agent 启动引导：首次启动自动引导配置 AID、owners、channels，降低上手门槛
• 🎭 主动模式策略：proactive 模式下智能判断响应时机，群聊支持静默策略，避免无效打扰
• 🎴 交互卡片体系：CommandCard + ActionInteraction，Feishu 与 AUN 统一支持

适合场景

• 通勤路上：手机打开飞书，继续昨晚的代码 review，到公司无缝切回终端
• 会议间隙：微信快速问一句「这个接口的返回格式是什么」，Agent 直接查代码回复
• Agent 协作：通过 AUN 网络，让你的 Agent 被其他 Agent 调用，组成分布式协作
• 外出离开工位：不带电脑也能通过 IM 给 Agent 下达任务，回来看结果
• 团队协作：拉个飞书群，成员共享同一个 Agent 会话，一起讨论和调试

系统架构

消息渠道层 → 消息队列层 → 命令处理层 → 消息处理层 → 会话管理层 → 存储层

核心组件

1. 消息渠道层 (src/channels/) - Feishu + WeChat + DingTalk + QQBot + WeCom + AUN 网络
2. 消息队列层 (src/core/message/message-queue.ts) - 会话级串行处理 + 中断支持
3. 命令处理层 (src/core/command/) - 斜杠命令处理（slash-handler / menu-handler / command-handler）
4. 消息处理层 (src/core/message/response-engine.ts) - 统一事件处理引擎
5. 会话管理层 (src/core/session/session-manager.ts) - 多项目会话管理
6. 交互路由层 (src/core/interaction-router.ts) - 卡片交互回调注册与路由
7. 会话存储层 - JSONL 文件（CLI 共用）+ 文件系统（每 chat 一个目录，含 active.json / meta_*.jsonl / messages.jsonl / health.jsonl）

消息流转

用户发送消息
    ↓
Channel.onMessage
    ↓
检查命令 → 是 → CommandHandler.handle() → 立即响应（绕过队列）
    ↓ 否
MessageQueue.enqueue(streamKey, message)
    ↓
检测正在处理 → 是 → 触发中断 → AgentRunner.interrupt()
    ↓ 否                                    ↓
MessageQueue.processNext()  ←──────────────┘
    ↓
ResponseEngine.processMessage()
    ↓
├─ 解析会话和项目路径
├─ 创建 StreamFlusher（3 秒批量发送）
├─ AgentRunner.runQuery() → 事件流
├─ 处理事件（tool_use / text / result）
├─ 提取文件标记（Feishu）
└─ 发送最终响应

快速开始

环境要求

• 操作系统：macOS / Linux / Windows
• Node.js >= 22.16.0（依赖 node:sqlite，并与 AUN SDK 要求保持一致）
• Claude Code >= 2.1.32（npm install -g @anthropic-ai/claude-code）

1. 安装

一行安装（macOS / Linux）：

curl -fsSL https://download.evolai.cn/install.sh | bash

Windows PowerShell：

& ([scriptblock]::Create((irm https://download.evolai.cn/install.ps1))) -AutoStart

安装器会自动进入 ec init 交互向导；只有已有配置同时包含控制 AID 和 Owner 时才跳过。上面的 Windows 命令会在绑定完成后自动运行 ec start；macOS/Linux 需手动运行 ec start。安装器不会停止或重启已有服务，详细流程见 一键安装脚本说明。

npm 全局安装：

npm install -g evolcore

Linux 全局安装会在 postinstall 阶段准备 Codex 受管运行所需的真实目录 /etc/codex。如果当前 npm 全局目录属于普通用户且该系统目录尚不存在，请先执行 sudo install -d -m 0755 /etc/codex，再重新安装。

Windows 的 npm 安装和升级不会直接写入机器级 Codex 配置。配置使用 Codex 后，执行 ec start 或 ec restart 时会自动检测托管 Hook；缺失时自动请求 Windows 管理员授权（UAC），安装并复检成功后继续启动。已安装时直接继续，无需单独执行安装命令，详见 Windows Codex 托管 Hook。

如果取消 UAC 或安装失败，本次启动或重启会停止；重启检查发生在停止旧服务之前。已有策略异常或安装位置变化需要管理员核对，自动安装不会覆盖这些状态。

Windows 用户：首次运行前可能需要执行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

从源码安装：

git clone https://github.com/eLeanwang/evolcore.git
cd evolcore
npm install
npm run build
npm link

2. 初始化

# 完整初始化（选择飞书或微信）
ec init

# 单独配置飞书（扫码登录）
ec init feishu

# 单独配置微信（扫码登录）
ec init wechat

# 单独配置钉钉（扫码登录）
ec init dingtalk

# 单独配置 QQ 频道（扫码登录）
ec init qqbot

# 单独配置企业微信（手动输入 Bot ID + Secret）
ec init wecom

# 单独配置 AUN（Mesh 网络通道）
ec init aun

交互式引导完成以下配置：

• 环境检查（Node.js >= 22.16.0、claude CLI、SDK 版本）
• 渠道选择（飞书 / 微信 / 钉钉 / QQ 频道 / 企业微信 / AUN）并扫码登录
• 默认项目路径
• 模型选择（sonnet/opus/haiku）
• owner 配置：默认走 Evol App 扫码绑定，若无 Evol App 可手工录入 AID 兜底。扫码流程只追加 owner；移除 owner 请直接编辑对应 JSON 配置。
• 自动写入 EVOLCORE_HOME 到 shell profile（Unix）或用户环境变量（Windows）

配置文件生成在 {EVOLCORE_HOME}/data/daemon.json（默认 ~/.evolcore/data/daemon.json）。

补充配置（可选）

以下参数不包含在 ec init 交互流程中，需要手动编辑 daemon.json：

{
  "projects": {
    "autoCreate": true                          // 绑定不存在的项目路径时自动创建目录
  },
  "idleMonitor": {
    "enabled": true,                            // 任务超时监控开关
    "timeout": 120,                             // 超时阈值（秒），默认 120 秒
    "maxExecutionTime": 7200,                   // 可选：任务总执行时限（秒）；未配置、非数字或 <=0 时不限制
    "safeModeThreshold": 3                      // 连续超时 N 次后进入安全模式（设为 0 禁用安全模式）
  },
  "flushDelay": 4                               // 工具活动消息聚合发送间隔（秒），默认 4 秒
}

API 继承机制：agents.claude 整个 section 可省略，系统自动按以下优先级继承：

• apiKey：配置文件 → ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY 环境变量 → ~/.claude/settings.json 中对应变量
• baseUrl：配置文件 → ANTHROPIC_BASE_URL 环境变量 → ~/.claude/settings.json
• model：配置文件 → ~/.claude/settings.json → 默认 sonnet
• effort：配置文件 → ~/.claude/settings.json → SDK 默认值（auto）

Claude、Codex 或 EC Agent 兼容网关需要额外请求头或查询参数时，可以直接在 EvolCore 的 baseagents 配置中设置，不需要修改各 base agent 的全局配置文件：

{
  "baseagents": {
    "claude": {
      "baseUrl": "https://example.com/claude",
      "headers": {
        "X-Tenant-Id": "${TENANT_ID}"
      },
      "queryParams": {
        "source": "evolcore"
      }
    },
    "codex": {
      "baseUrl": "https://example.com/codex",
      "headers": {
        "X-Tenant-Id": "${TENANT_ID}"
      },
      "queryParams": {
        "source": "evolcore"
      }
    },
    "ecagent": {
      "baseUrl": "https://example.com/ecagent/v1",
      "headers": {
        "X-Tenant-Id": "${TENANT_ID}"
      },
      "queryParams": {
        "source": "evolcore"
      }
    }
  }
}

${VAR} 会按 EvolCore 的环境变量规则展开。Claude 通过 ANTHROPIC_CUSTOM_HEADERS 传递 Header；Codex app-server 启动时由 EvolCore 注入 env_http_headers 和 query_params；EC Agent 主推理、模型列表和辅助推理直接在请求 URL 上追加参数。 因此不需要手改 Claude/Codex 的全局配置文件。queryParams 不应放置密钥等敏感信息。

完整设计、运行链路和排障说明见：Baseagent 自定义请求元数据技术文档。

Baseagent 模型与备用链

Session Renew 的辅助模型配置与主模型、推理强度放在同一个 baseagents.<baseagent> 块中，与 responseMode 正交。主模型故障备用链 fallbackModels 只在 agents/defaults.json 中配置：

{
  "baseagents": {
    "claude": {
      "model": "claude-opus",
      "effort": "medium",
      "auxiliaryModel": "claude-haiku-4-5-20251001",
      "auxiliaryEffort": "low",
      "fallbackModels": [
        { "model": "claude-sonnet-4-5", "effort": "medium" },
        { "model": "claude-haiku-4-5", "effort": "low" }
      ]
    },
    "codex": {
      "model": "gpt-5.6",
      "effort": "high",
      "auxiliaryModel": "gpt-5.6-sol",
      "auxiliaryEffort": "medium",
      "fallbackModels": [
        { "model": "gpt-5.4", "effort": "medium" }
      ]
    }
  }
}

auxiliaryEffort 必须与同一 baseagent 块中的 auxiliaryModel 一起配置；未配置辅助模型时， Session Renew 按 session_renew.fallback_action 处理。fallbackModels 不会被辅助推理使用。

升级旧版本时，daemon 启动前会自动把模式桶中的辅助字段迁移到对应的 baseagent 块并创建备份。 迁移逻辑集中在 src/config/schema-migration.ts，运行时不会回退读取旧字段。

3. 运行

# 服务管理
ec start      # 启动服务
ec stop       # 停止服务
ec restart    # 重启服务
ec status     # 查看状态
ec logs       # 查看日志（tail -f）
ec agent      # 管理 EvolAgent（list / show / new / reload）
ec mv <old> <new>  # 项目搬家（保留全部会话）
ec queue --agent <aid>   # 查看/操作 agent 消息队列（队列重启后持久化恢复）
ec diagnose   # 诊断启动环境

# 配置管理（v3.4+）
ec config show       # 查看某一层文件原始内容
ec config effective  # 打印合并后的生效配置 + 来源
ec config get <field>      # 读 effective 值
ec config set <field> <v>  # 写参数（scope 自动推断）
ec config validate   # 按 schema 校验
ec config history    # 配置快照历史

# 开发模式（热重载）
npm run dev

# 运行测试
npm test

项目结构

evolcore/
├── src/
│   ├── agents/
│   │   ├── claude-runner.ts        # Claude Agent SDK 封装
│   │   ├── codex-runner.ts         # Codex Agent 封装
│   │   └── gemini-runner.ts        # Gemini CLI 封装
│   ├── aun/                        # AUN 协议工具
│   ├── core/
│   │   ├── command/
│   │   │   ├── command-handler.ts  # 命令派发入口
│   │   │   ├── slash-handler.ts    # 斜杠命令实现
│   │   │   ├── menu-handler.ts     # Menu 协议处理
│   │   │   └── slash-gate.ts       # 权限前置拦截
│   │   ├── message/
│   │   │   ├── message-bridge.ts   # 渠道 ↔ 核心消息桥
│   │   │   ├── response-engine.ts  # 统一响应处理引擎
│   │   │   ├── inbound-admission.ts # 私聊入站准入
│   │   │   ├── message-queue.ts    # 消息队列（串行+中断）
│   │   │   ├── message-cache.ts    # 消息缓存
│   │   │   ├── message-log.ts      # 每 chat 的 messages.jsonl
│   │   │   └── im-renderer.ts      # IM 渲染 + 批量发送
│   │   ├── session/
│   │   │   ├── adapters/           # 各后端会话文件适配器
│   │   │   ├── session-fs-store.ts # 文件系统存储原语
│   │   │   └── session-manager.ts  # 会话管理（多项目支持）
│   │   ├── auth/                   # 授权审计与 Trigger 鉴权
│   │   ├── permission/             # 权限策略与沙箱边界
│   │   │   └── protected-paths.ts  # 受保护路径分级
│   │   ├── evolagent.ts            # EvolAgent 实体
│   │   ├── evolagent-registry.ts   # Agent 注册表（扫描/路由/热重载）
│   │   └── interaction-router.ts   # 卡片交互回调路由
│   ├── channels/
│   │   ├── feishu.ts               # 飞书 WebSocket 渠道
│   │   ├── wechat.ts               # 微信 ClawBot 渠道
│   │   ├── dingtalk.ts             # 钉钉 Stream 渠道
│   │   ├── qqbot.ts                # QQ 频道渠道
│   │   ├── wecom.ts                # 企业微信 AI Bot 渠道
│   │   └── aun.ts                  # AUN Mesh 网络渠道
│   ├── config/                     # 配置分层、访问策略、联系人绑定
│   ├── eck/                        # ECK 上下文组装（manifest / kit 渲染）
│   ├── response-system/            # 响应模式决策与参数解析
│   ├── trigger/                    # 触发器引擎
│   ├── stats/                      # 用量统计与计费
│   ├── cli/                        # CLI 命令
│   ├── utils/                      # 工具函数
│   ├── types.ts                    # 类型定义
│   ├── config-store.ts             # 配置加载
│   ├── paths.ts                    # 路径解析
│   └── index.ts                    # 主入口
└── kits/                           # 共享上下文模板（rules / docs / schemas）

斜杠命令

用户级命令（所有用户可用）

会话管理：

• /new [名称] - 创建新会话
• /slist - 列出当前项目的所有会话
• /slist cli - 列出未导入的 CLI 会话
• /s <名称|序号|uuid> - 切换到指定会话
• /name <新名称> - 重命名当前会话
• /del <名称> - 删除指定会话（仅解绑，不删除文件）
• /status - 显示会话状态
• /check - 系统健康检查（摘要）
• /help - 显示所有命令

身份绑定：

• /bind <6 位绑定码> - 将当前 IM 账号绑定到已登记的联系人身份（仅私聊）。 支持飞书、微信、钉钉、QQ 频道、企业微信。绑定码有效期 10 分钟，可由 ec init <channel> 生成，或在目标 Agent 的 AUN 私聊发送 /bind <channel> 自助申请。

管理员级命令（Admin+ 可用）

项目：

• /pwd - 显示当前项目路径

Agent 与模型：

• /baseagent [name] - 查看或切换 Agent 后端（claude / codex / gemini）（别名 /base）
• /model [model] - 查看或切换模型
• /effort [level] - 查看或切换推理强度（low / medium / high / max / auto）
• /perm [mode] - 查看或切换权限模式（readonly / auto / request / bypass；旧值会安全迁移）

系统管理：

• /compact - 压缩会话上下文
• /rewind <turn> - 回退会话到指定轮次
• /stop - 中断当前任务
• /check - 系统健康检查（详情）
• /activity [all|dm|owner|none] - 查看/控制中间输出显示模式
• /chatmode [interactive|proactive] - 查看/切换会话模式
• /dispatch [mention|broadcast] - 群聊分发模式（仅 @ 响应或广播）
• /trigger <动作> ... - 设置/查看 AI 自主触发器（延迟/定时/周期）
• /restart <channel> - 重连指定渠道

Owner 专属命令

• /file <文件路径> - 发送文件给用户
• /restart - 重启服务（自愈机制）
• /repair - 检查并修复会话

联系人与关系管理（menu 协议）

/connect 与 /group 是 menu 协议操作，通过 Evol App 或 EC Web 调用，不是 IM 里的斜杠命令。

• /connect - 联系人与关系管理：联系人列表、群组列表、角色分配、管理员授权、拉黑状态。 准入策略（connect.access.write）为 owner 专属，角色分配与 admin 授权委派给 role menu 执行， 复用其 agent 级互斥锁、CAS revision 与审计链。
• /group - 群组管理：群列表、群级 @ 提及策略、群规则加载策略的查询与更新。 群操作纳入权限目录与角色能力判定，通过版本比对和原子写入避免并发覆盖。

⚠️ 进程级 menu 操作鉴权（v3.2 Breaking）

进程级 menu 操作（/system restart/upgrade、/agent agent 生命周期管理）的鉴权已迁移到 daemon.json 顶层 owners 字段（v3.2 起，不再读 agents/defaults.json）。 升级后必须在 daemon.json 配置 owners，否则这些操作一律返回 FORBIDDEN（daemon 启动时也会 warn 提示）。

{
  "owners": ["eleans-2022.agentid.pub"]
}

ec init 交互流程会在生成控制 AID 后提示录入 owners（可跳过后手动编辑）。

• owners：进程级管理者 AID 名单。可执行 /system（重启/升级）与 /agent （create / delete / enable / disable / list / show）。
• 关系级的 /trigger（set / cancel / update / list）仍走 channel 角色（owner/admin）+ scoped 鉴权，不受 owners 影响。
• /agent create 为「受理即返回」：立即回 { accepted: true, aid }，后台跑完整创建流程并把各 环节写入 agents/<aid>/create-status.json；客户端用 menu.query name=agent args={aid} 轮询 createProgress.status 直到 ready / failed。

控制 AID（control AID）

v3.2 新增进程级身份标识。启动时自动生成 ec+5位数字.agentid.pub 格式的控制 AID，以 pureIdentity 模式接入 AUN 网络（跳过 evolagent onboarding）。ec status 可查看控制 AID 连接状态。

技术栈

• 运行时：Node.js >= 22.16.0 + TypeScript（ES modules）
• AI 后端：@anthropic-ai/claude-agent-sdk 0.3.220（固定版本）、Codex CLI app-server、Gemini CLI
• 消息渠道：飞书（@larksuiteoapi/node-sdk）、微信（ClawBot ilink API）、钉钉（dingtalk-stream）、QQ频道（pure-qqbot）、企业微信（AI Bot API）、AUN 网络
• 数据存储：文件系统（per-chat 目录） + JSONL（CLI 共用）
• 测试框架：Vitest

TODO

• [x] AUN Mesh 网络通道接入
• [x] 项目搬家工具（ec mv）
• [x] 手动授权支持（文本回复 + 飞书卡片）
• [x] 自动授权可配置（自动放行/自动拒绝）
• [x] 触发器支持
• [x] AUN 群组扩展功能支持
• [x] 统计/状态监控

许可证

MIT — 详见 LICENSE 声明