AutoSci vs EvoScientist：系统性架构与实现对比

> 对比基准：AutoSci（北京大学 DAIR Lab，arXiv:2605.31468）与 EvoScientist（arXiv:2603.08127，ICAIS 2025 Best Paper）。 > 分析维度涵盖设计哲学、架构分层、运行时机制、记忆系统、交互层、安全模型、工程实践与扩展生态。

---

1. 项目概览与定位

维度	AutoSci	EvoScientist
核心定位	Memory-centric agentic system for the full scientific research lifecycle	Towards self-evolving AI scientists for end-to-end scientific discovery
主导范式	Human-in-the-Loop（人逐步审批与协作）	Human-on-the-Loop（人监督而非微管理）
技术报告	arXiv:2605.31468	arXiv:2603.08127
机构/团队	北京大学 DAIR Lab（Weitong Qian 等）	国际联合团队（Xi Zhang, Yougang Lyu, Dinos Papakostas 等）
开源许可	MIT	Apache-2.0
Python 版本	≥3.9	≥3.11（Ruff target py311）
包管理器	pip + venv	uv（首选），支持 conda/pip
入口形态	Claude Code 技能集（`/command`）	独立 CLI/TUI 应用（`EvoSci` / `evoscientist`）

1.1 产品哲学差异

AutoSci 将自身定位为「Claude Code 的科研技能扩展包」。它假设用户已经在使用 Claude Code 作为日常开发/研究助手，通过 30+ 个 /command 技能将科研生命周期（文献摄入、想法生成、实验设计、论文撰写、审稿回复）嵌入到现有的 Claude Code 工作流中。其口号是 *"Read, think, experiment, write, evolve — the AI research agent with memory that compounds across every project."*

EvoScientist 则是一个独立的、自包含的 Agent 运行时。它不依附于任何特定 IDE 或 CLI 助手，而是构建了一个完整的多 Agent 操作系统，支持 TUI、CLI、Telegram、Slack、Discord、微信、飞书等 10+ 渠道接入。其口号是 *"Towards Self-Evolving AI Scientists"*，强调 Agent 团队的自主演化能力与跨会话记忆积累。

---

2. 架构设计思想对比

2.1 核心抽象：Wiki-centric vs Agent-graph-centric

AutoSci：以 Wiki 为唯一事实来源（Single Source of Truth）

AutoSci 的架构核心是 ΩmegaWiki——一个基于 Markdown + YAML Frontmatter + JSONL 图边的文件型知识库。所有技能（/ingest、/ideate、/exp-run 等）的本质都是「对 Wiki 的读写操作」。

实体类型（runtime/schema/entities.yaml）：papers、concepts、topics、people、ideas、methods、experiments、Summary、foundations，共 9 种。
边类型（runtime/schema/edges.yaml）：14 种语义边（如 builds_on、challenges、introduces_concept、addresses_gap）+ cites 引用边。
存储格式：每个实体是一个 Markdown 文件，YAML frontmatter 存元数据，正文存语义内容；图边存储在 wiki/graph/edges.jsonl 和 citations.jsonl 中。
生命周期：runtime/loader.py 在 import 时从 YAML schema 推导验证规则，添加新实体/边类型无需修改代码。

这种设计的优势是极致的透明度和可审计性：用户可以随意打开 wiki/papers/ 下的任意文件查看和编辑，知识库完全「人类可读」。其代价是并发控制能力弱（依赖 append-only 语义和文件锁的缺失），以及大规模查询性能受限（依赖 Python 脚本遍历文件系统）。

EvoScientist：以 Agent 图（LangGraph）为执行引擎

EvoScientist 的架构核心是 deepagents + LangGraph 构成的状态机图。知识不是存储在文件系统中供人阅读，而是存储在内存、SQLite checkpoint、MEMORY.md三层记忆体系中，供 Agent 在图执行过程中读取。

Agent 图：主 Agent（EvoScientist.py）通过 create_deep_agent() 构建，配置 recursion_limit=1000，支持深度推理链。
子 Agent：6 个专业子 Agent（planner、research、code、debug、data-analysis、writing）通过 YAML 声明式配置（subagents/*.yaml），运行时由 load_subagents() 注入工具引用。
状态持久化：基于 AsyncSqliteSaver 的 checkpoint 方案，会话状态（messages、中间结果）存储在 SQLite 中，支持断点续传。

这种设计的优势是强大的执行控制与并发能力：LangGraph 提供了精确的状态管理、中断（interrupt）、子图调度、并行执行。其代价是知识透明度较低：人类用户需要通过 CLI 命令或 TUI 界面与 Agent 交互，无法像 AutoSci 那样直接用 Obsidian 打开整个知识库。

2.2 分层架构

AutoSci 的分层（隐式）

AutoSci 没有显式的「分层架构文档」，但其结构可归纳为：

用户 → Claude Code CLI → Claude Code Agent Runtime → Skills (/command)
                                            ↓
                                    Python 工具脚本 (tools/*.py)
                                            ↓
                                    ΩmegaWiki (wiki/ 文件系统)
                                            ↓
                                    外部 API (Semantic Scholar, DeepXiv, arXiv)

运行时层：Claude Code（Anthropic 提供的 closed-source Agent 运行时）。
技能层：.claude/skills/ 下的 Markdown 文件（SKILL.md），定义每个 /command 的工作流。
工具层：tools/*.py（如 research_wiki.py、fetch_s2.py、discover.py），被技能通过 Bash 调用。
数据层：wiki/ 目录（Markdown 实体 + JSONL 图 + Canvas 可视化）。
原始层：raw/papers/、raw/notes/、raw/web/（用户只读，技能只追加）。

EvoScientist 的分层（显式，8 层）

1. 用户接入层 (Channels)     — Telegram/Slack/Discord/微信/飞书/iMessage/Email/QQ
2. 消息总线 (MessageBus)      — asyncio 双队列解耦
3. 消费者层 (Consumer)        — InboundConsumer: Worker Pool + per-chat 锁 + HITL
4. Agent 层 (Core)            — 主 Agent + 6 子 Agent + Think Tool
5. 后端层 (Backend)           — CompositeBackend: /workspace + /skills/ + /memories/
6. LLM 层 (Model)             — 15+ 供应商统一路由
7. 会话层 (Session)           — SQLite Checkpoint
8. 流式层 (Stream)            — 13 种事件类型 → TUI/Channel 渲染

EvoScientist 的每一层都有明确的接口和实现文件，架构文档（架构.md）提供了完整的数据流图和扩展指南。

---

3. 记忆系统：文件型知识图谱 vs 三层记忆架构

3.1 AutoSci：ΩmegaWiki —— 文件型知识图谱

AutoSci 的记忆系统是其最具特色的设计。它将「科研知识」建模为一个显式的、人类可读的、版本控制友好的文件型知识图谱。

实体 Schema（runtime/schema/entities.yaml）

以 papers 实体为例：

papers:
  dir: wiki/papers/
  fields:
    title:        { type: str, required: true }
    slug:         { type: str, required: true }
    arxiv:        { type: str }
    venue:        { type: str }
    year:         { type: int }
    tags:         { type: list_str, required: true, default: [] }
    importance:   { type: int, range: [1, 5], required: true, default: 3 }
    tldr:         { type: str }
    contribution_type: { type: list_str, default: [] }
    cited_by:     { type: list_link, to: papers, default: [] }

边的 Schema（runtime/schema/edges.yaml）

builds_on:
  endpoints: { from: papers, to: papers }
  direction: directed
  workflow:  ingest
  attributes:
    confidence: { type: enum, values: [high, medium, low], required: true }
    evidence:   { type: str, required: true }

核心设计决策：

1. 双向链接约束：任何 forward link 必须在同一 turn 内写入 reverse link。例外：foundations 是 terminal 实体，不写入反向链接。 2. 工具独占写入：wiki/graph/ 目录由 tools/research_wiki.py 独占修改，技能不得直接编辑。 3. Append-only 日志：wiki/log.md 只能追加，不能原地重写。 4. 生命周期状态机：ideas（proposed → in_progress → tested → [validated|failed]）和 experiments（planned → running → [completed|abandoned]）都有显式状态转换规则。 5. Context Brief 与 Gap Map：wiki/graph/context_brief.md 和 open_questions.md 是派生文件，由工具定期重建，提供全局压缩上下文。

优势：

完全透明，可用 Obsidian 等 Markdown 编辑器直接浏览和编辑。
天然支持 Git 版本控制，diff 可读性强。
Schema 驱动，新实体类型通过修改 YAML 自动生效。

劣势：

无内置并发控制（依赖 append-only 和「sibling worktree」约定）。
查询性能受限于文件系统遍历（research_wiki.py 的 find/neighbors 是 O(N) 的）。
不支持跨会话的「Agent 状态」持久化（Claude Code 本身会维护对话上下文，但那是 black box）。

3.2 EvoScientist：EvoMemory —— 三层记忆 + 自动提取

EvoScientist 的记忆系统由 EvoMemoryMiddleware（middleware/memory.py）实现，包含双机制运作：

机制 1：注入（每次 LLM 调用）

读取 /memories/MEMORY.md 的内容，注入到 system prompt 的标签中。
附带指导 Agent 何时、如何更新记忆。

机制 2：自动提取（阈值触发）

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

三层记忆体系：

层级	载体	作用	持久化
会话记忆	SQLite Checkpoint (`~/.config/evoscientist/sessions.db`)	单次对话的完整状态，支持断点续传	跨会话
长期记忆	`/memory/MEMORY.md`	用户画像、研究偏好、实验结论	跨会话
研究记忆	`ideation-memory.md` / `experiment-memory.md`	已验证/已失败的研究方向与策略，驱动进化决策	跨项目

与 AutoSci 的关键差异：

1. 记忆不是人类可读的知识库，而是 Agent 的「个人笔记」。MEMORY.md 是 Markdown，但结构简单，目的是供 Agent 在 system prompt 中快速加载，而非供人类用 Obsidian 浏览。 2. 自动提取 vs 显式写入。AutoSci 要求技能显式调用 tools/research_wiki.py log 和 add-edge；EvoScientist 的 Agent 会自动从对话中提取记忆，无需用户显式指令。 3. 支持跨会话恢复。由于使用 SQLite checkpoint，用户可以随时 /resume 之前的会话；AutoSci 的会话上下文由 Claude Code 管理，不具备这种细粒度的恢复能力。

---

4. Agent 运行时与技能系统

4.1 AutoSci：Claude Code 技能集（Skill-as-Script）

AutoSci 的「技能」是 Claude Code 的 SKILL.md 文件——一种基于 Markdown 的声明式工作流定义。Claude Code 在接收到 /command 时，读取对应的 SKILL.md，将其作为 system prompt 的一部分注入，指导 Claude 执行特定工作流。

技能示例：/ingest（i18n/en/skills/ingest/SKILL.md）

一个典型的 SKILL.md 包含：

description 和 argument-hint（frontmatter）
输入/输出定义
Wiki 交互契约（Reads/Writes/Graph edges created）
分步骤工作流（Step 1 → Step 2 → ...）
约束条件（Constraints）
错误处理（Error Handling）
依赖声明（Dependencies：Tools、Skills、MCP Servers、Claude Code Native）

技能执行方式：

Claude Code Agent → 解析 SKILL.md → 生成 Bash/Python 命令 → 调用 tools/*.py → 修改 wiki/ 文件。

关键特征：

无显式 Agent 框架：没有 create_agent() 或 AgentGraph。Claude Code 本身是黑盒运行时，AutoSci 只是「使用说明书」（SKILL.md）。
子 Agent 通过 Claude Code 的 Agent 工具实现：例如 /ideate Phase 1 的并行搜索通过 Claude Code 原生 Agent 工具启动并行子任务。
Review LLM 通过 MCP 服务器实现：mcp__llm-review__chat 是一个 MCP 调用，将请求路由到配置好的 OpenAI 兼容 API。

4.2 EvoScientist：deepagents + LangGraph（Agent-as-Graph）

EvoScientist 的 Agent 运行时是显式构建的、可编程的状态图。

主 Agent 构建（EvoScientist.py）

create_deep_agent(
    name="EvoScientist",
    model=_ensure_chat_model(),      # LangChain ChatModel
    tools=[think_tool, skill_manager, tavily_search, ...],
    backend=CompositeBackend(...),   # /workspace + /skills/ + /memories/
    subagents=[planner, research, code, debug, data, writing],
    middleware=[
        ConfigurableModelMiddleware,
        ModelFallbackMiddleware,
        ContextOverflowMapperMiddleware,
        ToolErrorHandlerMiddleware,
        ToolSelectorMiddleware,
        EvoMemoryMiddleware,
        HumanInTheLoopMiddleware,   # HITL
        BackgroundExecutionMiddleware,
        CodeInterpreterMiddleware,
    ],
    system_prompt=get_system_prompt(),
    skills=["/skills/"],
).with_config({"recursion_limit": cfg.recursion_limit})

子 Agent 声明式配置（subagents/research.yaml）

name: research-agent
description: Web research for methods, baselines, datasets
system_prompt: |
  ...
tools: [web_search, web_fetch]
async: false   # true → 路由到 langgraph_dev/graphs.py 异步图

Think Tool（tools/think.py）

EvoScientist 的 think_tool 是一个独特的「认知检查点」工具，强制 Agent 在 7 个维度反思： 1. 进展 — 已完成什么？还剩什么？ 2. 证据质量 — 当前证据是否充分？ 3. 技能利用 — 是否有匹配的已安装技能？ 4. 先验知识 — 是否查阅了研究记忆？ 5. 策略 — 继续、调整还是转向？ 6. 交接 — 当前阶段是否完成？ 7. 资源与计算 — 预估运行时和内存，规划后台执行

这是 AutoSci 所没有的显式「元认知」机制——AutoSci 的反思嵌入在 SKILL.md 的文本指令中，而非作为可调用的工具。

关键差异：

维度	AutoSci	EvoScientist
运行时	Claude Code（closed-source）	deepagents + LangGraph（open-source）
技能定义	Markdown（SKILL.md）	外部仓库（EvoSkills）+ YAML 子 Agent
子任务调度	Claude Code `Agent` 工具	LangGraph `task` 工具 + 异步子图
状态持久化	无（依赖 Claude Code 对话历史）	SQLite checkpoint + 内存状态
执行深度	受 Claude Code 上下文限制	recursion_limit=1000，可深度推理
可编程性	低（只能通过 SKILL.md 文本调优）	高（可直接修改 Python 代码和图结构）

---

5. 多模型支持与 LLM 路由

5.1 AutoSci：双模型架构（主 + Review）

AutoSci 的模型架构非常简单：

主模型：Claude（通过 Claude Code），支持 Anthropic 协议兼容的第三方（MiMo、DeepSeek、Kimi、GLM 等）。通过 .claude/settings.json 配置 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN。
Review LLM：任意 OpenAI 兼容 API（DeepSeek、OpenAI、Qwen、OpenRouter 等），通过 .env 中的 LLM_API_KEY + LLM_BASE_URL + LLM_MODEL 配置。

设计意图：主模型负责执行，Review LLM 负责独立批判。两者在 /ideate Phase 2 中并行生成想法，互不看见对方输出（cross-model review）。

局限：

不支持运行时动态切换主模型（需重启 Claude Code 并修改 settings.json）。
Review LLM 仅通过 MCP 服务器调用，无统一的模型路由层。
无模型降级（fallback）机制——如果主模型 API 故障，整个系统停止。

5.2 EvoScientist：15+ 供应商统一路由 + 自动配置

EvoScientist 的模型层（llm/models.py）是一个成熟的多供应商路由系统：

原生供应商：Anthropic、OpenAI、Google GenAI、NVIDIA、Ollama OpenAI 路由（自定义 base_url）：DeepSeek、SiliconFlow、OpenRouter、ZhipuAI、Volcengine、DashScope、custom-openai Anthropic 路由（自定义 base_url）：MiniMax、custom-anthropic

自动配置（_apply_auto_config）：

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

兼容性修补：

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

降级机制：

ModelFallbackMiddleware：主模型失败时自动按配置链降级
ConfigurableModelMiddleware：支持通过 /model 命令运行时切换模型

缓存机制：

_chat_model_key：按 (model, provider) 缓存模型实例，避免重复初始化 HTTP 客户端
_replace_chat_model() 是唯一的模型写入点，确保缓存一致性

---

6. 交互层与多渠道支持

6.1 AutoSci：单一 CLI 入口

AutoSci 的交互层完全依赖 Claude Code CLI。用户启动 claude 后，通过 /command 调用技能。

无 TUI：没有图形化文本界面，纯命令行交互。
无多渠道路由：不支持 Telegram、Slack 等外部消息平台。
可视化：tools/serve.py 启动的 Web 服务器（端口 8765）提供知识图谱的浏览器可视化，以及 /visualize --obsidian 生成 Obsidian Canvas。但这些是「只读展示」，不是交互入口。
邮件通知：/daily-arxiv 支持邮件 digest，但这是单向推送，不是对话交互。

6.2 EvoScientist：多端统一接入（CLI + TUI + 10+ 渠道）

EvoScientist 的交互层是其架构中最复杂的子系统之一，实现了真正的 omnichannel（全渠道）Agent。

Channel 抽象（channels/base.py）

class Channel(ABC):
    @abstractmethod
    async def _send_chunk(self, chat_id, text): ...
    
    @abstractmethod
    async def receive(self) -> AsyncIterator[InboundMessage]: ...

10 个渠道实现：Telegram、Slack、Discord、微信（企业微信/公众号）、DingTalk、飞书、Email、QQ、Signal、iMessage。

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

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

消息总线（channels/bus/message_bus.py）

轻量级异步双队列：

inbound：asyncio.Queue[InboundMessage]（maxsize=5000）— 渠道 → Agent
outbound：asyncio.Queue[OutboundMessage]（maxsize=5000）— Agent → 渠道

消费者层（channels/consumer.py）

InboundConsumer 核心设计：

Worker Pool：默认 5 个并发 worker，bounded queue 背压
Per-chat 锁：同一 chat 串行处理，避免消息乱序
LRU 会话管理：sender_id → thread_id 映射，上限 10,000
HITL 中断处理：检测 LangGraph interrupt → 发送审批提示到渠道 → 等待用户回复 → Command(resume=...) 恢复
ask_user 处理：Agent 主动提问 → 格式化发送到渠道 → 收集回答 → 恢复图执行

流式事件（stream/events.py）

StreamEventEmitter 定义 13 种标准化事件类型：

事件	说明
`thinking`	模型内部推理（extended thinking）
`text`	文本输出片段
`tool_call` / `tool_result`	工具调用及返回
`subagent_start` / `subagent_end`	子 Agent 委派开始/结束
`subagent_tool_call` / `subagent_tool_result`	子 Agent 内部工具调用
`subagent_text`	子 Agent 文本输出（fallback 提取）
`done`	推理完成
`usage_stats`	Token 用量统计
`interrupt`	HITL 中断
`ask_user`	Agent 主动提问中断
`summarization`	上下文摘要
`error`	错误

这些事件被 TUI widgets 和 Channel 发送端消费，实现统一的渲染逻辑。

TUI（cli/）

基于 Textual 框架的全屏文本界面，支持：

实时流式渲染（thinking、text、tool_call、subagent 事件）
内联图片显示（base64 编码）
HITL 审批面板（1=批准, 2=拒绝, 3=全部批准）
会话列表 (/threads)、恢复 (/resume)、删除 (/delete)

---

7. 安全模型

7.1 AutoSci：依赖 Claude Code 的权限模型

AutoSci 本身没有显式的沙箱或命令验证层。其安全模型完全依赖：

1. Claude Code 的内置安全机制：Claude Code 会对 Bash 命令进行一定程度的确认（尤其是破坏性操作）。 2. SKILL.md 中的约束文本：例如 /ingest 的 Constraints 章节规定 "raw/papers/ 是 user-owned and read-only"，但这只是「建议」，无技术强制。 3. 外部 API 密钥隔离：.env 文件存储 API keys，不在版本控制中。

风险点：

如果 Claude Code 的「自动批准」模式开启，Agent 可能执行危险命令（如 rm -rf）。
无路径穿越检测：Agent 可能通过 ../../ 访问父目录。
无命令黑名单：Agent 可以执行 sudo、chmod 等系统命令（取决于 Claude Code 的权限）。

7.2 EvoScientist：多层沙箱 + HITL 审批

EvoScientist 实现了企业级的安全模型，核心在 backends.py 的 CustomSandboxBackend。

路径安全：

虚拟路径模式：Agent 看到 /file.py，实际映射到 /file.py
系统路径拦截：/Users/、/home/、/tmp/、/etc/ 等 12 个前缀被拦截
路径穿越检测：.. 作为路径组件时拦截
自动修正：LLM 幻觉的系统绝对路径（如 /Users/u/proj/file.py）被自动转换为相对路径

命令安全：

危险命令黑名单：sudo、chmod、chown、mkfs、dd、shutdown、reboot
管道感知检查：ls | sudo rm 中 sudo 仍被拦截
Shell 拆分：&&、||、;、| 操作符拆分为独立命令逐一检查
工作区字面路径替换：命令中的绝对工作区路径先替换为 ./

执行限制：

超时：300 秒（exit code 124），附带后台执行恢复建议
输出截断：100 KB 上限

访问控制：

渠道层：allowed_senders 白名单、allowed_channels 白名单、dm_policy（三种 DM 访问模式）、require_mention 提及策略
工具层：HITL 审批（interrupt_on: {execute: True}）、只读技能目录、MCP 工具白名单

HITL 系统：

1. 工具执行审批：所有 Shell 命令需人类审批（可配置 auto_approve 或 shell_allow_list 白名单跳过）。审批通过渠道消息交互：1=批准, 2=拒绝, 3=全部批准。120 秒超时自动批准。 2. Agent 主动提问：AskUserMiddleware 注册 ask_user 工具，支持 text 和 multiple_choice 两种问题类型。使用 LangGraph interrupt() 暂停图执行，通过渠道或 CLI 收集回答后 Command(resume=...) 恢复。

---

8. 工程实践与代码组织

8.1 AutoSci：轻量级脚本集合

代码结构：

AutoSci/
├── app/                    # Web SPA（图谱可视化）
├── config/                 # 配置模板
├── docs/                   # 文档
├── i18n/                   # 国际化（en/zh）
│   └── en/
│       └── skills/         # 30+ SKILL.md 文件
├── raw/                    # 用户原始数据（papers/notes/web/）
├── runtime/                # Schema + Policy + Templates
│   ├── schema/             # entities.yaml, edges.yaml, xref.yaml, conventions.yaml
│   ├── policy/             # writers.yaml
│   └── templates/          # 实体模板（*.md.tmpl）
├── templates/              # 海报模板
├── tools/                  # 19 个 Python 工具脚本
│   ├── research_wiki.py    # Wiki 引擎（核心，2861 行）
│   ├── fetch_s2.py         # Semantic Scholar API
│   ├── fetch_deepxiv.py    # DeepXiv API
│   ├── discover.py         # 论文发现
│   ├── lint.py             # Wiki 校验
│   ├── visualize.py        # 可视化生成
│   └── ...
├── wiki/                   # 知识库（运行时生成）
└── setup.sh / setup.ps1    # 一键安装脚本

工程特征：

无包管理：不是 Python package，无 pyproject.toml。依赖通过 requirements.txt + setup.sh 安装到 .venv。
无测试套件：未发现 tests/ 目录或测试框架配置。
无 CI/CD：.github/ 目录存在但内容未知，README 提到 GitHub Actions 用于 /daily-arxiv 调度。
代码风格：无 linter/formatter 配置（无 .ruff.toml、.flake8、.black 等）。
i18n 支持：通过 i18n/en/ 和 i18n/zh/ 提供双语 SKILL.md，安装时通过 --lang 参数切换。

8.2 EvoScientist：企业级 Python 包

代码结构：

EvoScientist/
├── EvoScientist/           # 可导入包（import EvoScientist）
│   ├── EvoScientist.py     # 根 Agent（懒加载单例）
│   ├── __init__.py         # __getattr__ 懒导出
│   ├── backends.py         # CompositeBackend + CustomSandboxBackend
│   ├── cli/                # Typer 命令 + Textual TUI widgets + Rich UI
│   ├── channels/           # 10 平台适配器 + bus/ + 中间件
│   ├── commands/           # 斜杠命令实现
│   ├── config/             # 配置系统 + onboarding 向导
│   ├── langgraph_dev/      # 独立 LangGraph 服务器图
│   ├── llm/                # 模型注册（5 原生 + 12 路由）
│   │   ├── models.py       # 供应商路由 + 自动配置
│   │   ├── context_window.py
│   │   └── patches.py      # 兼容性补丁
│   ├── mcp/                # MCP 客户端 + registry
│   │   ├── client.py       # 生命周期管理
│   │   └── registry.py     # Marketplace
│   ├── middleware/         # 12 个中间件
│   │   ├── memory.py       # EvoMemoryMiddleware
│   │   ├── ask_user.py     # AskUserMiddleware
│   │   ├── tool_selector.py # LLMToolSelectorMiddleware
│   │   └── ...
│   ├── stream/             # 13 事件类型 + emitter/tracker/display
│   ├── subagents/          # 6 YAML 定义子 Agent
│   ├── tools/              # 内置工具（search, think, skills）
│   └── deploy/             # `EvoSci deploy` 服务器入口
├── tests/                  # ~890 测试，36 文件，无需 API key
├── docs/                   # 示例和部署配方
├── pyproject.toml          # 包元数据、Ruff 配置、pytest 配置
├── uv.lock                 # 锁定依赖
├── Dockerfile              # 非 root `evosci` 镜像
├── docker-compose.yml
├── .pre-commit-config.yaml # Ruff v0.9.9 固定
└── 架构.md / MCP演进方案.md  # 中文架构文档

工程特征：

现代 Python 包：pyproject.toml + setuptools，EvoScientist* 包发现。
严格代码质量：Ruff（lint + format），pre-commit hooks，target-version = "py311"。启用规则集：E, W, F, I, B, C4, UP, PT, PLE, RUF, FURB。
全面测试：~890 个测试，pytest + pytest-cov + pytest-timeout（CI 30 秒/测试）。
Docker 支持：非 root 用户（evosci，UID 1000），预装 Node.js 24 LTS + uv。
CI/CD：.github/workflows/ 包含 build / lint / test / docker。
文档生成：.qoder/repowiki/ 是自动生成的中文 wiki，与代码同步。

---

9. 部署拓扑

9.1 AutoSci：本地开发机

AutoSci 的部署非常简单：

git clone https://github.com/skyllwt/AutoSci.git
cd AutoSci
chmod +x setup.sh && ./setup.sh
claude
# Then: /init [topic]

单机单用户：Claude Code 运行时绑定到本地终端。
可选 GitHub Actions：/daily-arxiv setup 生成 GitHub Actions workflow，用于定时 arXiv 推荐（需配置 CLAUDE_CODE_OAUTH_TOKEN）。
远程实验：/exp-run --env remote 通过 ssh/rsync/screen 部署到远程 GPU 服务器，最佳运行环境是 WSL2/Linux/macOS。

9.2 EvoScientist：三种部署模式

模式 1：CLI/TUI（默认）

EvoSci  # 交互式 TUI
EvoSci -p "your question"  # 单发模式

模式 2：Daemon（多端接入）

EvoSci serve  # 无头模式，仅渠道

多用户并发：Worker Pool + per-chat 锁。健康检查：GET /healthz。优雅关闭：Outbound drain + worker drain + channel stop。

模式 3：LangGraph Server

EvoSci deploy  # 独立 LangGraph 服务器，供外部 UI/SDK 调用

Docker 部署：

docker run -it --rm \
  --env-file .env \
  -v "$(pwd)/workspace:/workspace" \
  -v evosci-data:/home/evosci/.evoscientist \
  ghcr.io/evoscientist/evoscientist:latest

---

10. 扩展机制

10.1 AutoSci：修改 YAML + 编写 SKILL.md

添加新实体类型： 1. 在 runtime/schema/entities.yaml 中添加定义 2. 在 runtime/templates/ 中添加 *.md.tmpl 3. runtime/loader.py 自动推导验证规则

添加新技能： 1. 在 i18n/en/skills/ 下创建新目录 2. 编写 SKILL.md（输入输出、工作流、约束、依赖） 3. 如有需要，编写新的 tools/*.py 4. 运行 ./setup.sh --lang en 同步

添加新模型支持：

修改 .claude/settings.json 覆盖 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN（Anthropic 兼容）
或修改 .env 配置 LLM_API_KEY + LLM_BASE_URL + LLM_MODEL（OpenAI 兼容，用于 Review）

10.2 EvoScientist：模块化注册

添加新渠道： 1. mkdir EvoScientist/channels// 2. 实现 Channel 子类 + Capability 3. 在 __init__.py 中 register_channel() 4. 自动发现机制无需修改中心注册代码

添加新 LLM 供应商： 1. 在 _MODEL_ENTRIES 中添加 (short_name, model_id, provider) 2. OpenAI 兼容 → _OPENAI_ROUTED_PROVIDERS 3. Anthropic 兼容 → _ANTHROPIC_ROUTED_PROVIDERS 4. 在 _ENV_MAPPINGS 中添加 API Key 映射

添加新子 Agent： 1. 在 subagents/ 下创建 YAML 2. 指定 description, tools, system_prompt, async 3. load_subagents() 自动解析注入

添加新 MCP 服务器：

EvoSci mcp add <name> <command> [-- args...]

配置持久化到 ~/.config/evoscientist/mcp.yaml，支持环境变量插值 ${VAR}。

添加新技能：技能是外部仓库（EvoSkills），通过 skill_manager 工具动态发现和加载。系统内置技能在 EvoScientist/skills/（PyPI 包内），用户技能在 workspace/skills/（可写），全局技能在 ~/.evoscientist/skills/（只读），三层通过 MergedSkillsBackend 合并。

---

11. 具体实现细节对比

11.1 Wiki 引擎 vs Agent 图引擎

维度	AutoSci (`tools/research_wiki.py`)	EvoScientist (`EvoScientist.py` + deepagents)
核心数据结构	文件系统（Markdown + YAML + JSONL）	Python 对象图（LangGraph State + SQLite）
查询语言	Python argparse CLI（`find`, `query`, `neighbors`）	无显式查询语言，Agent 通过工具调用读取文件
并发模型	无（依赖 append-only 约定）	asyncio + per-chat 锁 + Worker Pool
状态机	YAML 定义生命周期（`lifecycle.transitions`）	LangGraph 图节点 + `interrupt()`
扩展方式	修改 YAML Schema	修改 Python 代码或 YAML 子 Agent 配置
规模限制	文件系统性能（百级实体流畅，千级需优化）	SQLite 性能（万级 checkpoint 可接受）

11.2 实验工作流

AutoSci 的实验工作流（/exp-design + /exp-run + /exp-eval）

1. /exp-design ：方法候选生成 + 5 种实验块类型 + 迭代消融循环 2. /exp-run [--env local|remote]：准备代码 → 部署 → 监控 → 收集结果 3. /exp-status：查看运行状态，自动收集完成的运行 4. /exp-eval ：Review LLM 独立评判结果，更新 idea 状态和图边

此外有 /exp-pilot-run 和 /exp-pilot-eval 用于轻量级预实验筛选。

EvoScientist 的实验工作流

实验工作流不是硬编码的 /command，而是通过子 Agent 委派实现的：

1. planner-agent：实验规划与阶段反思（MODE: PLAN / REFLECTION） 2. code-agent：代码实现与脚本编写（最小化、可复现） 3. debug-agent：运行时调试与修复（复现 → 根因 → 最小修复） 4. data-analysis-agent：数据分析与可视化（计算 → 绘图 → 解读） 5. writing-agent：实验报告撰写（不捏造结果/引用）

停止迭代的判据：基线已建立、主指标跨 ≥3 seed 稳定、消融完成、failure cases 已识别。

关键差异：AutoSci 的实验流程是命令驱动的、阶段明确的（设计→运行→评估→论文），每个阶段有明确的输入输出和 checkpoint。EvoScientist 的实验流程是Agent 自主协调的，主 Agent 根据 Think Tool 的反思决定何时委派给哪个子 Agent，何时停止迭代。

11.3 论文撰写

AutoSci：

/paper-plan：从 idea 图编译论文大纲（证据图 → 叙事结构 → 章节+图表+引用计划）
/paper-draft：从 PAPER_PLAN 起草 LaTeX（逐节从 wiki 源撰写，生成图表，验证 BibTeX）
/paper-compile：latexmk 编译 → PDF + 自动修复 + 页数/匿名性/字体检查 + 提交清单
/poster：从草稿生成 1400×900 HTML 海报（自动提取 TikZ 图表和 booktabs 表格）
/rebuttal：解析审稿意见 → 原子化关切 → 映射到 wiki → Review LLM 压力测试 → 生成 rebuttal

EvoScientist：

论文撰写由 writing-agent 子 Agent 负责，没有 AutoSci 那样细分的 /paper-plan、/paper-draft、/paper-compile 等显式阶段命令。
技能（Skills）是 EvoScientist 扩展功能的主要方式，但论文撰写的具体流程依赖于安装的 EvoSkills（ companion repo）。
支持 LaTeX（TinyTeX）但需额外安装，Docker 镜像不包含。

11.4 文献发现与摄入

AutoSci /ingest：

输入：arXiv URL / 本地 .tex / .pdf
处理：arXiv 源下载 → Semantic Scholar 元数据 → DeepXiv 语义增强 → PDF 预处理 → 生成 paper page + concept pages + method pages + people pages
图构建：add-edge（语义边）+ add-citation（引用边）
输出：完整互联的 wiki 页面集 + 终端摘要 + 可选 --discover 相关论文推荐

AutoSci /discover：

支持 --venue iclr --year 2024 等按会议筛选
从 Paper Copilot 获取论文列表，结合 wiki 兴趣排序