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 的 标签中
• 附带 指导 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/EvoSkills 仓库拉取 MCP 服务器定义
• 自动安装 pip 依赖、配置环境变量
• 10 分钟缓存 TTL

4.4 配置系统 (Configuration)

四级优先级合并 (settings.py):

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) 提供全局路径解析：

支持运行时动态切换：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

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",
):
    # 处理每个状态快照
    ...

---

附录: 技术栈一览