EvoScientist 架构设计

定位: 面向自动化科学实验与发现的多智能体 AI 系统
版本: 0.0.3 | 框架: deepagents + LangGraph + LangChain
范式: Human-on-the-Loop (人在环上)

目录

1. 设计哲学
2. 系统总览
3. 分层架构
4. 核心子系统
5. 数据流与交互模式
6. 安全模型
7. 扩展机制
8. 部署拓扑

1. 设计哲学

1.1 Human-on-the-Loop (人在环上)

EvoScientist 超越了传统 Human-in-the-Loop 模式。在"人在环上"范式下，AI 并非等待人类逐步审批的执行器，而是作为自主研究伙伴运行——独立完成从问题定义、文献调研、实验设计、代码实现到论文撰写的全链路科研任务，人类以监督者和协作者的身份参与关键决策节点。

核心主张：

• 基线优先，迭代演进：先建立 baseline，再逐轮消融（ablation-friendly）
• 每次迭代只改变一个核心变量（数据、模型、目标函数或训练方案）
• 永不捏造结果：无法运行的实验如实声明，并提出最小可行的下一步
• 激进委派：主 Agent 优先将子任务委派给专业子 Agent，而非自行处理

1.2 自我进化 (Self-Evolving)

系统通过三层记忆机制实现跨会话的持续学习与进化：

1.3 技能即工作流 (Skills as Workflows)

技能（Skills）是系统的一等公民。每个技能封装一个结构化的研究工作流（如 idea-tournament、experiment-pipeline、paper-writing），Agent 在执行任务时主动匹配并遵循技能的 SKILL.md 中定义的流程，而非即兴发挥。技能可动态安装，使系统能力随生态成长。

2. 系统总览

                          ┌─────────────────────────────────────────┐
                          │            用户接入层 (Channels)          │
                          │  Telegram │ Slack │ Discord │ WeChat │… │
                          └────────────────┬────────────────────────┘
                                           │ InboundMessage
                                           ▼
                          ┌─────────────────────────────────────────┐
                          │          消息总线 (MessageBus)           │
                          │    inbound ◄──── queue ────► outbound    │
                          └────────────────┬────────────────────────┘
                                           │
                                           ▼
                          ┌─────────────────────────────────────────┐
                          │        消费者 (InboundConsumer)          │
                          │   会话管理 │ HITL │ ask_user │ 流式推理   │
                          └────────────────┬────────────────────────┘
                                           │ stream_agent_events
                                           ▼
          ┌─────────────────────────────────────────────────────────────────┐
          │                    主 Agent (EvoScientist)                       │
          │                                                                 │
          │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
          │  │ planner  │  │ research │  │   code   │  │  debug   │       │
          │  │  -agent  │  │  -agent  │  │  -agent  │  │  -agent  │       │
          │  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
          │  ┌──────────┐  ┌──────────┐                                    │
          │  │  data-   │  │ writing  │     Middleware:                     │
          │  │ analysis │  │  -agent  │     - EvoMemory (注入+自动提取)      │
          │  │  -agent  │  │          │     - AskUser (交互式提问)           │
          │  └──────────┘  └──────────┘     - ToolErrorHandler (异常兜底)   │
          │                                                                 │
          │  Tools: think_tool │ tavily_search │ skill_manager │ MCP tools  │
          └─────────────────────────────────────────────────────────────────┘
                                           │
                    ┌──────────────────────┼──────────────────────┐
                    ▼                      ▼                      ▼
          ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
          │  Backend (I/O)  │  │  LLM Provider   │  │  Session Store  │
          │  Composite      │  │  Anthropic      │  │  SQLite (async) │
          │  ├─ Sandbox     │  │  OpenAI         │  │                 │
          │  ├─ Skills (RO) │  │  Google GenAI   │  │                 │
          │  └─ Memory (FS) │  │  + 10 others    │  │                 │
          └─────────────────┘  └─────────────────┘  └─────────────────┘

3. 分层架构

3.1 接入层 (Channel Layer)

职责: 统一多平台消息的收发，屏蔽平台差异。

设计模式: 插件式抽象基类 + 消息总线解耦

• Channel 抽象基类 (base.py) 定义统一接口：start()、_send_chunk()、receive()
• 10 个渠道实现：Telegram、Slack、Discord、WeChat（企业微信/公众号）、DingTalk、Feishu、Email、QQ、Signal、iMessage
• 入站中间件链（Dedup → AllowList → Pairing → GroupHistory → MentionGating）
• 发送端：自动分块（尊重代码块边界）、指数退避重试、per-chat 锁保序
• ChannelManager (channel_manager.py) 统一管理生命周期、健康检查、共享 Webhook 服务器

关键抽象:

ChannelPlugin (协议)
  └── Channel (抽象基类)
       ├── TelegramChannel
       ├── SlackChannel
       ├── DiscordChannel
       └── ... (每个渠道独立子包)

每个渠道子包遵循统一的三文件约定：

• channel.py — 渠道实现
• probe.py — 连通性探测
• serve.py — 独立服务入口

3.2 消息总线 (Message Bus)

职责: 解耦消息生产（渠道）与消费（Agent），实现异步削峰。

MessageBus (message_bus.py) 是一个轻量级的异步双队列：

• inbound: asyncio.Queue[InboundMessage] (maxsize=5000) — 渠道 → Agent
• outbound: asyncio.Queue[OutboundMessage] (maxsize=5000) — Agent → 渠道

消息事件模型 (events.py):

• InboundMessage: channel, sender_id, chat_id, content, media, metadata, is_group, was_mentioned
• OutboundMessage: channel, chat_id, content, reply_to, media, metadata

3.3 消费者层 (Consumer Layer)

职责: 桥接消息总线与 Agent 推理引擎，管理会话、并发与 HITL。

InboundConsumer (consumer.py) 核心设计：

• Worker Pool: 可配置数量的并发 worker（默认 5），通过 bounded queue 实现背压
• Per-chat 锁: 同一 chat 串行处理，避免消息乱序
• LRU 会话管理: sender_id → thread_id 映射，上限 10,000
• HITL 中断处理: 检测 LangGraph interrupt 事件 → 发送审批提示到渠道 → 等待用户回复 → Command(resume=...) 恢复图执行
• ask_user 处理: Agent 主动提问 → 格式化发送到渠道 → 收集回答 → 恢复图执行
• 超时保护: per-yield idle timeout 防止 Agent 推理卡死

3.4 Agent 层 (Core Intelligence)

职责: 科研任务的理解、规划、执行与协调。

3.4.1 Agent 构建

Agent 通过 deepagents.create_deep_agent() 构建（EvoScientist.py），核心参数：

Agent 图配置 recursion_limit: 1000，支持深度推理链。

3.4.2 子 Agent 架构

子 Agent 通过 YAML 声明式配置 (subagent.yaml)，由 load_subagents() (utils.py) 在运行时加载并注入工具引用。

委派策略 (prompts.py)：

• 默认单 Agent 任务，仅在实验独立时并行（如 Method A vs B vs C）
• 停止迭代的判据：基线已建立、主指标跨 ≥3 seed 稳定、消融完成、failure cases 已识别

3.4.3 Think Tool — 结构化反思

think_tool (think.py) 是一个独特的"认知检查点"工具，在七个维度引导 Agent 反思：

1. 进展 — 已完成什么？还剩什么？
2. 证据质量 — 当前证据是否充分？审稿人会接受吗？
3. 技能利用 — 是否有匹配的已安装技能？
4. 先验知识 — 是否查阅了研究记忆？
5. 策略 — 继续、调整还是转向？
6. 交接 — 当前阶段是否完成？下一阶段需要什么？
7. 资源与计算 — 预估运行时和内存，规划后台执行

3.5 Backend 层 (I/O Abstraction)

职责: 为 Agent 提供统一的虚拟文件系统抽象，隔离真实文件操作。

设计模式: CompositeBackend + 路由式分发

CompositeBackend
  ├── / (default)  →  CustomSandboxBackend  (工作区，可读写，Shell 执行)
  ├── /skills/     →  MergedReadOnlyBackend  (技能目录，只读)
  │                    ├── primary: 用户自定义技能 (workspace/skills/)
  │                    └── secondary: 系统内置技能 (./skills/)
  └── /memory/     →  FilesystemBackend      (记忆目录，可读写)

CustomSandboxBackend (backends.py) 继承 LocalShellBackend，在文件操作和 Shell 执行之上叠加安全层：

• 路径净化: 自动修正 LLM 常见的路径幻觉（如 /Users/.../workspace/file.py → ./file.py）
• 命令验证: 拦截 .. 路径穿越、系统绝对路径、危险命令（sudo, chmod, mkfs, dd 等）
• 虚拟路径转换: 将 /main.py 等虚拟路径自动转为相对路径

3.6 LLM 层 (Model Provider)

职责: 统一多模型供应商的接入，支持自动配置与兼容性修补。

get_chat_model() (models.py) 的设计：

供应商路由:

• 原生供应商: Anthropic、OpenAI、Google GenAI、NVIDIA、Ollama
• OpenAI 路由: DeepSeek、SiliconFlow、OpenRouter、ZhipuAI、Volcengine、DashScope、custom-openai
• Anthropic 路由: MiniMax、custom-anthropic

自动配置 (_apply_auto_config):

• Anthropic: 自动启用 extended thinking（adaptive for 4-6 系列）
• OpenAI: 自动启用 reasoning（high effort + auto summary）
• Google GenAI: 自动开启 thought traces
• 第三方代理: 自动跳过不兼容特性（thinking/reasoning）

兼容性修补:

• _patch_anthropic_proxy_compat: 处理 ccproxy 等代理返回的 dict 而非对象
• _patch_openai_compat_content: 将 list content 展平为 string，兼容 DeepSeek 等严格 API

3.7 会话层 (Session Layer)

职责: 持久化多轮对话状态，支持线程 CRUD 和前缀匹配恢复。

基于 AsyncSqliteSaver (sessions.py) 的 checkpoint 方案：

• 存储位置: ~/.config/evoscientist/sessions.db
• 线程 ID: 8 位 hex（UUID 前缀）
• 元数据: agent_name, workspace_dir, model, updated_at
• 操作: list_threads, get_most_recent, find_sim_threads (前缀匹配), delete_thread, get_thread_messages

3.8 流式层 (Stream Layer)

职责: 将 Agent 推理过程转化为标准化的事件流，供 UI 层渲染。

StreamEventEmitter (emitter.py) 定义 13 种事件类型：

4. 核心子系统

4.1 记忆系统 (Memory System)

记忆系统是 EvoScientist 实现"自我进化"的核心机制，由 EvoMemoryMiddleware (memory.py) 实现。

双机制运作:

1. 注入 (每次 LLM 调用):

   • 读取 /memory/MEMORY.md 的内容
   • 注入到 system prompt 的 <evo_memory> 标签中
   • 附带 <memory_instructions> 指导 Agent 何时、如何更新记忆

2. 自动提取 (阈值触发):

   • 每 20 条 human messages 触发一次（可配置）
   • 使用 LLM（可用廉价模型）+ Structured Output 提取：
     • UserProfile — 姓名、角色、机构、语言
     • ResearchPreferences — 研究领域、框架、模型、硬件、约束
     • ExperimentConclusion — 实验标题、问题、方法、结果、结论
     • LearnedPreferences — 观察到的习惯和偏好
   • 通过 _merge_memory() 增量合并到 MEMORY.md，带去重逻辑

结构化记忆模板:

# EvoScientist Memory
## User Profile        (Name, Role, Institution, Language)
## Research Preferences (Domain, Frameworks, Models, Hardware)
## Experiment History   ([日期] 标题 + 问题 + 结果 + 结论)
## Learned Preferences  (观察到的习惯)

4.2 HITL 系统 (Human-in-the-Loop)

HITL 在两个层面运作：

1. 工具执行审批 (Shell Execution Gate):

• interrupt_on={"execute": True} — 所有 Shell 命令需要人类审批
• auto_approve 配置可全局跳过
• shell_allow_list 可按命令前缀白名单跳过
• 审批通过渠道消息交互：发送审批提示 → 等待回复（1=批准, 2=拒绝, 3=全部批准）
• 120 秒超时自动批准

2. Agent 主动提问 (AskUser):

• AskUserMiddleware (ask_user.py) 注册 ask_user 工具
• 支持 text 和 multiple_choice 两种问题类型
• 使用 LangGraph interrupt() 暂停图执行
• 通过渠道或 CLI 收集回答后 Command(resume=...) 恢复

4.3 MCP 系统 (Model Context Protocol)

职责: 动态扩展 Agent 工具集，实现与外部服务的标准化集成。

mcp/client.py (client.py) 提供完整的 MCP 生命周期管理：

配置管理:

• 用户配置: ~/.config/evoscientist/mcp.yaml
• 支持环境变量插值 (\({VAR}`) - 传输协议: stdio, http, streamable_http, sse, websocket - CRUD 操作: `add_mcp_server()`, `edit_mcp_server()`, `remove_mcp_server()` **工具路由**: - 每个 MCP 服务器可配置 `tools` 白名单（支持 glob 通配符）和 `expose_to` 目标 Agent - 工具按 Agent 名称分组：`"main"` → 主 Agent，其他 → 对应子 Agent - 配置签名缓存：相同配置不重复连接 MCP 服务器 **Marketplace** ([registry.py](EvoScientist/mcp/registry.py:169)): - 从 `EvoScientist/EvoSkills` 仓库拉取 MCP 服务器定义 - 自动安装 pip 依赖、配置环境变量 - 10 分钟缓存 TTL ### 4.4 配置系统 (Configuration) **四级优先级合并** ([settings.py](EvoScientist/config/settings.py:378)): ``` CLI 参数 (最高) > 环境变量 > 配置文件 (YAML) > 默认值 (最低) ``` - 配置文件: `~/.config/evoscientist/config.yaml` - 环境变量映射: 30+ 个 `_ENV_MAPPINGS` 条目 - `.env` 文件: 通过 `python-dotenv` 自动加载 - `apply_config_to_env()`: 将配置文件中的 API Key 注入环境变量，供下游库使用 ### 4.5 路径系统 (Path Resolution) `paths.py` ([paths.py](EvoScientist/paths.py)) 提供全局路径解析： | 路径 | 默认值 | 说明 | |------|--------|------| | `WORKSPACE_ROOT` | `\)CWD 或 \(EVOSCIENTIST_WORKSPACE_DIR` | 工作区根目录 | | `MEMORY_DIR` | `/memory` | 记忆存储 | | `USER_SKILLS_DIR` | `/skills` | 用户技能 | | `RUNS_DIR` | `/runs` | 运行记录 | | `MEDIA_DIR` | `/media` | 媒体文件 | 支持运行时动态切换：`set_workspace_root()` 重新派生所有依赖路径。 --- ## 5. 数据流与交互模式 ### 5.1 完整请求生命周期 ``` 用户消息 (Telegram/Slack/CLI/...) │ ▼ Channel._on_message() │ 平台特定解析 → RawIncoming │ ▼ Channel._enqueue_raw() │ 入站中间件链: Dedup → AllowList → Pairing → GroupHistory → MentionGating │ STT 转录（如启用） │ ACK 表情反应 │ ▼ Channel.queue_message() │ 防抖 (debounce): 合并同一发送者的连续消息 │ ▼ MessageBus.publish_inbound() │ ▼ InboundConsumer._handle_message() │ 会话解析 (sender → thread_id) │ ask_user 回复检测 │ HITL 审批回复检测 │ Per-chat 锁获取 │ ▼ InboundConsumer._stream_with_hitl() │ ▼ stream_agent_events() │ ├──► Agent 推理 (LangGraph) │ │ │ ├── system_prompt + evo_memory 注入 │ ├── LLM 调用 (thinking/text/tool_call) │ ├── 工具执行 (think_tool, tavily_search, MCP, shell...) │ ├── 子 Agent 委派 (task tool) │ │ └── 子 Agent 独立推理循环 │ └── HITL interrupt / ask_user interrupt │ ├──► 事件处理 │ ├── thinking → channel.send_thinking_message() │ ├── todo → channel.send_todo_message() │ ├── text → 累积 final_content │ ├── interrupt → HITL 审批流程 │ └── ask_user → 问答收集流程 │ └──► 完成 │ ▼ MessageBus.publish_outbound(OutboundMessage) │ ▼ ChannelManager._dispatch_outbound() │ OutboundPipeline (中间件) │ ▼ Channel.send() │ 格式化 (Markdown → 平台格式) │ 分块 (respect code fences) │ 指数退避重试 │ Per-chat 锁保序 │ ▼ 用户收到回复 ``` ### 5.2 子 Agent 委派模式 ``` 主 Agent │ │ task(subagent="planner-agent", description="MODE: PLAN ...") │ ▼ planner-agent (独立推理循环) │ tools: [think_tool] │ skills: [/skills/] │ ├── think_tool: 反思计划结构 ├── read_file: 读取技能/记忆文件 └── 输出: 实验计划 Markdown │ ▼ 主 Agent 收到子 Agent 结果 │ │ 继续协调下一步... ``` ### 5.3 记忆进化循环 ``` 实验完成/失败 │ ▼ 主 Agent 检测重大结果 │ ├── 成功 → ESE (Experiment Strategy Evolution) │ → 更新 experiment-memory.md │ └── 失败 → IVE (Idea Validation Evolution) → 更新 ideation-memory.md (失败分类) idea-tournament 完成 │ ▼ IDE (Idea Direction Evolution) → 更新 ideation-memory.md 下一次实验启动 │ ▼ planner-agent 读取 ideation-memory.md + experiment-memory.md → 避免重复失败方向，复用已验证策略 ``` --- ## 6. 安全模型 ### 6.1 沙箱隔离 `CustomSandboxBackend` 实现多层防护： **路径安全**: - 虚拟路径模式: Agent 看到 `/file.py`，实际映射到 `/file.py` - 系统路径拦截: `/Users/`, `/home/`, `/tmp/`, `/etc/` 等 12 个前缀 - 路径穿越检测: `..` 作为路径组件时拦截 - 自动修正: LLM 幻觉的系统绝对路径被自动转换为相对路径 **命令安全**: - 危险命令黑名单: `sudo`, `chmod`, `chown`, `mkfs`, `dd`, `shutdown`, `reboot` - 管道感知检查: `ls | sudo rm` 中 `sudo` 仍被拦截 - Shell 拆分: `&&`, `||`, `;`, `|` 操作符拆分为独立命令逐一检查 - 工作区字面路径替换: 命令中的绝对工作区路径先替换为 `./` **执行限制**: - 超时: 300 秒（exit code 124），附带后台执行恢复建议 - 输出截断: 100 KB 上限 ### 6.2 访问控制 **渠道层**: - `allowed_senders`: 白名单控制可触发 Agent 的用户 - `allowed_channels`: 白名单控制可响应的渠道/群组 - `dm_policy`: "open" | "allowlist" | "pairing" 三种 DM 访问模式 - `require_mention`: "always" | "group" | "off" 提及策略 **工具层**: - HITL: Shell 命令需人类审批（可配置白名单跳过） - 只读技能目录: Agent 不能修改已安装的技能 - MCP 工具过滤: 每个服务器可配置工具白名单 ### 6.3 配置安全 - API Key 不进入版本控制（`.env` + `.gitignore`） - 环境变量优先于配置文件 - 敏感字段不出现在公开 API 响应中 --- ## 7. 扩展机制 ### 7.1 添加新渠道 1. 在 `EvoScientist/channels/` 下创建子包 2. 实现 `Channel` 子类（`start()`, `_send_chunk()`） 3. 定义 `ChannelCapabilities`（格式类型、群组支持、提及支持等） 4. 在 `__init__.py` 中注册 `register_channel()` 5. 自动发现机制确保无需修改中心注册代码 ### 7.2 添加新 LLM 供应商 1. 在 `_MODEL_ENTRIES` 中添加 `(short_name, model_id, provider)` 条目 2. 对于 OpenAI 兼容 API：添加到 `_OPENAI_ROUTED_PROVIDERS` 3. 对于 Anthropic 兼容 API：添加到 `_ANTHROPIC_ROUTED_PROVIDERS` 4. 在 `_ENV_MAPPINGS` 中添加 API Key 映射 5. `_apply_auto_config` 自动处理 thinking/reasoning 配置 ### 7.3 添加新子 Agent 1. 在 `subagent.yaml` 中添加声明式配置 2. 指定 `description`, `tools`, `system_prompt` (或 `system_prompt_ref`) 3. `load_subagents()` 自动解析工具引用并注入 4. 主 Agent 的 system prompt 中描述委派策略 ### 7.4 添加新 MCP 工具 1. 在 `~/.config/evoscientist/mcp.yaml` 中添加服务器配置 2. 配置 `transport`, `command`/`url`, `tools` 白名单, `expose_to` 目标 3. 支持 `\){ENV_VAR} 环境变量插值

4. 或通过 CLI: /mcp add <name> <command-or-url>

7.5 添加新技能

1. 在 /skills/ 目录下创建技能子目录
2. 编写 SKILL.md 定义工作流
3. MergedReadOnlyBackend 自动合并用户技能与系统技能
4. Agent 通过 skill_manager 工具发现和加载技能

8. 部署拓扑

8.1 CLI 模式（默认）

┌─────────────────────────┐
│  evosci / EvoSci CLI    │
│  ┌───────────────────┐  │
│  │  TUI (Textual)    │  │
│  │  or CLI (Rich)    │  │
│  └────────┬──────────┘  │
│           │             │
│  ┌────────▼──────────┐  │
│  │  Agent Runtime    │  │
│  │  (in-process)     │  │
│  └───────────────────┘  │
└─────────────────────────┘

• 入口: python -m EvoScientist 或 evoscientist / EvoSci
• UI 后端: TUI (Textual, 默认) 或 CLI (Rich)
• 会话持久化: SQLite checkpoint

8.2 Daemon 模式（多端接入）

┌──────────────────────────────────────────────┐
│  evosci serve                                │
│                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ Telegram │  │  Slack   │  │ Discord  │  │
│  │ Channel  │  │ Channel  │  │ Channel  │  │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  │
│       │              │              │        │
│       └──────────────┼──────────────┘        │
│                      ▼                       │
│              MessageBus                      │
│                      │                       │
│              InboundConsumer                 │
│              (worker pool)                   │
│                      │                       │
│              Agent Runtime                   │
│                      │                       │
│              SQLite Checkpoint               │
│                                              │
│  Health Server: GET /healthz                 │
│  Shared Webhook: 0.0.0.0:<port>             │
└──────────────────────────────────────────────┘

• 多用户并发: Worker Pool + per-chat 锁
• 健康检查: 零依赖 HTTP 端点 (/healthz)
• 优雅关闭: Outbound drain + worker drain + channel stop
• 自动重连: 指数退避（1s → 60s max）

8.3 编程式接入 (Notebook / Library)

from EvoScientist import EvoScientist_agent

for state in EvoScientist_agent.stream(
    {"messages": [HumanMessage(content="your question")]},
    config={"configurable": {"thread_id": "1"}},
    stream_mode="values",
):
    # 处理每个状态快照
    ...

附录: 技术栈一览