AutoResearchClaw 架构分析

- 对内,它把“选题 → 检索 → 假设 → 实验 → 分析 → 写作 → 审校 → 导出”组织成一个可恢复、可回滚、可插拔的 23 阶段状态机。 - 对外,它又暴露成一个可被 CLI、OpenClaw、ACP Agent、Web 界面、HITL 协作模式、外部领域 Agent 和基准评测套件共同驱动的平台。

目录
  1. 1. 项目定位
  2. 2. 一张图看整体架构
  3. 3. 仓库分层理解
  4. 3.1 顶层结构
  5. 3.2 为什么说这是“复合仓库”
  6. 4. 核心运行主线:CLI → Config → Runner → Stage Executor
  7. 4.1 入口层:CLI 是主要控制面
  8. 4.2 配置层:RCConfig 是统一的系统装配面
  9. 4.3 编排层:Runner 负责“跑起来”
  10. 4.4 执行层:Executor 是状态机与业务逻辑之间的桥
  11. 5. 状态机内核:23 阶段流水线
  12. 5.1 状态机是第一公民
  13. 5.2 8 个阶段组
  14. 5.3 Gate 和回滚是状态机价值的核心
  15. 6. Stage Contract 与 Artifact-First 设计
  16. 6.1 合同驱动的阶段边界
  17. 6.2 为什么 artifact-first 很重要
  18. 7. Pipeline 代码结构:从“大执行器”向“阶段实现模块化”演进
  19. 7.1 现在的拆分方式
  20. 7.2 这说明什么
  21. 8. LLM 抽象层:把不同模型接入统一成一种聊天协议
  22. 8.1 统一工厂
  23. 8.2 LLMClient 的定位
  24. 8.3 ACP 的意义
  25. 9. Prompt 层:领域感知的 PromptManager
  26. 10. 文献子系统:真实世界检索,而不是“让模型编参考文献”
  27. 10.1 真实数据源优先
  28. 10.2 架构意义
  29. 11. 领域路由层:Domain Profile 让系统从“单一 ML 流程”扩展为“多学科平台”
  30. 11.1 profile 机制
  31. 11.2 检测逻辑
  32. 11.3 架构价值
  33. 12. 实验执行子系统:从本地沙盒到外部 Agent 的多后端执行面
  34. 12.1 工厂模式
  35. 12.2 这层解决的核心问题
  36. 12.3 执行层的设计思想
  37. 13. OpenCode / Code Agent:复杂代码生成的旁路系统
  38. 13.1 为什么需要旁路
  39. 13.2 Beast Mode 的本质
  40. 14. 多 Agent 子系统:增强型能力不是塞进主流水线,而是独立编排
  41. 14.1 公共基类
  42. 14.2 BenchmarkAgent
  43. 14.3 FigureAgent
  44. 14.4 架构意义
  45. 15. HITL / Co-Pilot:把人放回流水线中间,而不是只能在开头给 topic
  46. 15.1 HITL 不是附加功能,而是第二控制面
  47. 15.2 它解决的问题
  48. 15.3 设计思想
  49. 16. Adapter 层:外部系统集成的总线
  50. 16.1 为什么这层很关键
  51. 16.2 直接收益
  52. 17. Knowledge / Memory / Evolution / MetaClaw:系统的长期记忆层
  53. 17.1 Knowledge Base:面向 artifact 的结构化沉淀
  54. 17.2 Memory:更像检索式短中期记忆
  55. 17.3 Evolution:跨运行 lesson 注入
  56. 17.4 MetaClaw:把 lesson 升级成 skill
  57. 18. 技能系统:把领域知识打包成可装载单元
  58. 19. 质量控制链:不是只在最后评分,而是贯穿多层
  59. 19.1 前置层
  60. 19.2 过程层
  61. 19.3 后置层
  62. 20. 导出与写作层:从实验结果到论文交付物
  63. 20.1 这一层的职责
  64. 21. Server / Dashboard / Web:运行中的可视化和服务化方向
  65. 21.1 FastAPI 服务端
  66. 21.2 Dashboard
  67. 21.3 前端现状的架构信号
  68. 22. 外部 Agent 集成:AutoResearchClaw 不试图自己做所有科学计算
  69. 23. ARC-Bench:把产品能力外化成可比较的 benchmark
  70. 23.1 范围
  71. 23.2 作用
  72. 23.3 架构含义
  73. 24. 测试结构:系统复杂度已经进入“平台级”规模
  74. 25. 设计思想总结
  75. 25.1 状态机优先,而非 prompt 串联
  76. 25.2 Artifact-first,而非内存上下文优先
  77. 25.3 配置驱动的平台化
  78. 25.4 分层 agent orchestration
  79. 25.5 人机协作是主路径,而不是补丁
  80. 25.6 外部世界接入是真实研究的必要条件
  81. 25.7 跨运行学习
  82. 26. 这个架构的优势
  83. 26.1 可恢复性强
  84. 26.2 易于审查
  85. 26.3 扩展路径清晰
  86. 26.4 多运行模式共存
  87. 26.5 适合研究场景
  88. 27. 这个架构的代价与复杂性来源
  89. 27.1 仓库边界较宽
  90. 27.2 配置面很大
  91. 27.3 流程与子系统交叉较多
  92. 27.4 Web 面还在演化
  93. 28. 如何理解这个项目的“架构中心”
  94. 29. 推荐的阅读顺序
  95. 30. 结论

1. 项目定位

AutoResearchClaw 不是一个单一的“论文生成脚本”,而是一个研究流程操作系统:

  • 对内,它把“选题 → 检索 → 假设 → 实验 → 分析 → 写作 → 审校 → 导出”组织成一个可恢复、可回滚、可插拔的 23 阶段状态机。
  • 对外,它又暴露成一个可被 CLI、OpenClaw、ACP Agent、Web 界面、HITL 协作模式、外部领域 Agent 和基准评测套件共同驱动的平台。
从仓库结构看,它是一个典型的核心引擎 + 多个增强子系统 + 多种接入界面 + 基准/展示资产的复合型仓库,而不是只包含 researchclaw/ 包本身。


2. 一张图看整体架构

如果用一句话概括:ResearchClaw 的内核是“状态机编排器”,其余多数模块都围绕“给状态机提供能力、约束、记忆、协作和出口”而存在。


3. 仓库分层理解

3.1 顶层结构

仓库大致可以分成六层:

层级目录/文件作用
核心引擎层researchclaw/真实产品内核:配置、状态机、执行器、实验、写作、协作、服务端等
使用与集成层README.md、RESEARCHCLAW_AGENTS.md、RESEARCHCLAW_CLAUDE.md、config.researchclaw.example.yaml供用户、OpenClaw、CLI Agent 和开发者接入系统
文档层docs/HITL、集成、领域扩展、多语言 README、展示文档
研究基准层experiments/arc_bench/55-topic ARC-Bench、baseline adapter、judge、run scripts
展示/界面层website/、frontend-legacy/静态官网与旧版前端原型
运维/辅助层scripts/、sentinel.sh、run_hep_pipeline.sh、tests/、external/看门狗、专项运行脚本、测试、外部 agent 接入

3.2 为什么说这是“复合仓库”

因为它同时承担了四种角色:

1. 研究流水线产品本体:researchclaw/ 2. 可接入 Agent 的技能包/服务:RESEARCHCLAW_AGENTS.md、ACP/OpenClaw 集成 3. 研究平台增强实验场:HITL、MetaClaw、Memory、Knowledge Graph、Server、Dashboard 4. 评测与展示资产仓库:ARC-Bench、website、showcase、多语言文档

这解释了为什么仓库看起来“范围很广”:它不是一个纯 library,而是一个完整研究自动化生态的宿主仓库。


4. 核心运行主线:CLI → Config → Runner → Stage Executor

这是整个系统最重要的主链路。

4.1 入口层:CLI 是主要控制面

入口在 researchclaw/cli.py,pyproject.toml 将 researchclaw = "researchclaw.cli:main" 暴露为命令。

CLI 提供的不是单一命令,而是一组面向“研究运行生命周期”的控制命令:

  • researchclaw init:生成本地配置
  • researchclaw validate:校验配置
  • researchclaw doctor:环境诊断
  • researchclaw run:执行 23 阶段流水线
  • report / attach / approve / reject / guide 等:服务于 HITL 和 detached operation
这说明 CLI 的设计思想不是“脚本入口”,而是本地控制平面(local control plane)。

4.2 配置层:RCConfig 是统一的系统装配面

核心配置在 researchclaw/config.py,RCConfig 聚合了大量子配置:

  • project:项目模式与 profile
  • research:研究主题与质量阈值
  • runtime:并发、重试、超时
  • notifications
  • knowledge_base
  • openclaw_bridge
  • llm
  • security
  • experiment
  • export
  • prompts
  • web_search
  • metaclaw_bridge
  • memory
  • skills
  • knowledge_graph
  • compute_servers
  • mcp
  • overleaf
  • server
  • dashboard
  • trends
  • copilot
  • quality_assessor
  • calendar
  • hitl
这反映出一个非常明确的设计:系统的能力扩展优先通过配置装配,而不是修改核心 runner。

同时,RCConfig.load() 还支持:

  • 搜索默认配置文件顺序:config.arc.yaml → config.yaml
  • project.profile / --profile 驱动的领域部署默认值注入
  • YAML → typed dataclass 的转换和校验
因此,配置层不仅是参数容器,也是系统变体选择器。

4.3 编排层:Runner 负责“跑起来”

researchclaw/pipeline/runner.py 是真正的编排器,负责:

  • 从某个 stage 开始执行
  • 逐阶段写 checkpoint
  • 写 heartbeat 供 sentinel 监控
  • 处理 resume/restart
  • 汇总 pipeline summary
  • 与知识库、evolution、HITL、诊断/修复逻辑联动
这里的重点不是“简单 for 循环执行 23 个阶段”,而是把一次研究运行变成了具备恢复能力的长期任务。

4.4 执行层:Executor 是状态机与业务逻辑之间的桥

researchclaw/pipeline/executor.py 的角色非常关键:

  • 它维护 _STAGE_EXECUTORS,把 Stage 枚举映射到具体执行函数
  • 它统一处理:
  • stage 目录创建
  • 输入 artifact 检查
  • LLM client 构造
  • PromptManager 装配
  • stage 执行异常封装
  • 输出 artifact 验证
  • gate/HITL 钩子
也就是说,runner 负责“调度”,executor 负责“执行协议”,stage_impl 负责“阶段业务”。这是本项目最清晰的一层分工。


5. 状态机内核:23 阶段流水线

5.1 状态机是第一公民

researchclaw/pipeline/stages.py 定义了:

  • Stage:23 个阶段
  • StageStatus:pending/running/blocked_approval/failed/done 等状态
  • TransitionEvent:start/succeed/approve/reject/fail/retry/resume/pause
  • NEXT_STAGE / PREVIOUS_STAGE
  • GATE_STAGES
  • GATE_ROLLBACK
  • DECISION_ROLLBACK
  • NONCRITICAL_STAGES
  • PHASE_MAP
  • advance():显式状态推进逻辑
这意味着项目不是用“约定式流程”驱动,而是用显式、可推理、可测试的状态机驱动。

5.2 8 个阶段组

23 个阶段被分成 8 个 phase:

1. Research Scoping 2. Literature Discovery 3. Knowledge Synthesis 4. Experiment Design 5. Experiment Execution 6. Analysis & Decision 7. Paper Writing 8. Finalization

这种分组既服务于系统内部,也服务于:

  • CLI / status 展示
  • Dashboard 分组
  • 文档解释
  • HITL checkpoint 模式
所以它不仅是逻辑分层,也是产品交互分层。

5.3 Gate 和回滚是状态机价值的核心

本项目最重要的非线性逻辑不是“23 个 stage”,而是:

  • Gate stage:默认是 5、9、20
  • 拒绝后回滚:
  • 5 → 4
  • 9 → 8
  • 20 → 16
  • Research decision(15)允许:
  • pivot → 回到假设生成
  • refine → 回到迭代实验
这让流水线不再是僵硬的 DAG,而是一种带反馈回路的研究控制回路。


6. Stage Contract 与 Artifact-First 设计

6.1 合同驱动的阶段边界

researchclaw/pipeline/contracts.py 为每个阶段定义:

  • input_files
  • output_files
  • dod(Definition of Done)
  • error_code
  • max_retries
这是一种很工程化的做法:每个阶段不是只靠 prompt 暗示输出,而是有文件级合同约束。

6.2 为什么 artifact-first 很重要

系统并不把“上下文”主要保存在内存对象里,而是大量落盘到 run_dir/stage-XX/:

  • goal.md
  • search_plan.yaml
  • candidates.jsonl
  • hypotheses.md
  • exp_plan.yaml
  • experiment/
  • runs/
  • analysis.md
  • paper_draft.md
  • reviews.md
  • quality_report.json
  • verification_report.json
配套还有:
  • checkpoint.json
  • heartbeat.json
  • pipeline_summary.json
这体现了项目的一条根本设计思想:artifact 是唯一可靠的跨阶段接口。

这样做带来的收益:

1. 便于恢复与重跑 2. 便于人类审查 3. 便于 detached interaction 4. 便于 Dashboard / report / benchmark judge 读取 5. 便于把 LLM 生成内容转化为可验证的文件系统状态


7. Pipeline 代码结构:从“大执行器”向“阶段实现模块化”演进

researchclaw/pipeline/ 体现出一个明显的演化轨迹。

7.1 现在的拆分方式

当前结构已经不是把 23 个阶段全塞进一个文件,而是拆成:

  • stages.py:状态机
  • contracts.py:阶段合同
  • runner.py:编排
  • executor.py:统一执行协议
  • stage_impls/
  • _topic.py
  • _literature.py
  • _synthesis.py
  • _experiment_design.py
  • _code_generation.py
  • _execution.py
  • _analysis.py
  • _paper_writing.py
  • _review_publish.py
  • _helpers.py:公共帮助函数
  • _domain.py:领域检测桥接

7.2 这说明什么

这说明项目在向“稳定内核 + 可演化阶段实现”的结构靠拢:

  • 内核接口稳定:Runner / Executor / Stage / Contract
  • 阶段业务可持续重写:拆到 stage_impls
这是一种很适合 agentic 系统的架构,因为变化最多的是 prompt、阶段策略和阶段逻辑,不该是状态机骨架本身。


8. LLM 抽象层:把不同模型接入统一成一种聊天协议

8.1 统一工厂

researchclaw/llm/__init__.py 通过 create_llm_client() 统一创建:

  • OpenAI-compatible client
  • Anthropic adapter
  • Kimi-Anthropic adapter
  • ACP client

8.2 LLMClient 的定位

researchclaw/llm/client.py 并不是复杂的 SDK wrapper,而是一个偏“最低公共能力抽象”的客户端:

  • fallback model chain
  • chat_completions / responses 切换
  • max_tokens vs max_completion_tokens 兼容
  • exponential backoff
  • JSON mode
  • preflight
  • MetaClaw proxy/fallback
它的设计重点不是“适配所有 provider 的高阶特性”,而是:

只保留流水线稳定运行所需的统一最小能力。

这让上层阶段逻辑不必关心具体模型供应商。

8.3 ACP 的意义

ACP 让 AutoResearchClaw 可以把“LLM 后端”换成任意 ACP-compatible agent CLI,而不只是 API 模型。这把系统从“模型调用器”拓展成了Agent orchestration shell。


9. Prompt 层:领域感知的 PromptManager

researchclaw/prompts/manager.py 管理 prompt bank:

  • 支持不同 domain 的 prompt bank:ml、hep_ph、biology_metabolic
  • 支持 YAML 覆盖
  • 支持 prompts.extra_prompts 按阶段附加额外指导
  • 支持 evolution overlay 注入
这意味着 prompt 不是散落在各 stage 中的字符串,而是一个独立的策略层。

这层的设计价值在于:

1. prompt 与业务逻辑解耦 2. 领域差异集中管理 3. 用户可配置性更强 4. evolution / MetaClaw 可以在较少侵入的情况下注入经验


10. 文献子系统:真实世界检索,而不是“让模型编参考文献”

10.1 真实数据源优先

researchclaw/literature/ 与 researchclaw/web/ 共同承担文献搜集能力:

  • OpenAlex
  • Semantic Scholar
  • arXiv
  • Scholar / crawl / PDF extraction
researchclaw/literature/search.py 体现了典型的现实世界数据工程思路:
  • 多源检索
  • 去重(DOI → arXiv ID → title fuzzy match)
  • 排序
  • 缓存
  • 限流容错
  • 某源失败时用其他源补偿

10.2 架构意义

这部分的存在说明 AutoResearchClaw 不把“研究”理解为纯语言生成,而是把它理解为:

LLM + 外部学术数据源 + 本地结构化处理 的组合系统。

这也是它与普通“论文写作 agent”最重要的分野之一。


11. 领域路由层:Domain Profile 让系统从“单一 ML 流程”扩展为“多学科平台”

11.1 profile 机制

researchclaw/domains/detector.py 定义 DomainProfile,并从 researchclaw/domains/profiles/*.yaml 加载领域配置。当前仓库里可见 27 个 profile 文件。

profile 里不仅有“领域名称”,还有:

  • 实验范式
  • 术语映射
  • 典型文件结构
  • entry point
  • 核心依赖
  • baseline 与 metric 约定
  • figure 类型
  • 检索关键词
  • prompt hints
  • deployment defaults

11.2 检测逻辑

领域检测是三级策略:

1. 强制 profile 2. 关键词匹配 3. LLM 分类 4. 最后回退到 generic

11.3 架构价值

这意味着系统不是在每个 stage 里硬编码“如果是 biology 就怎样”,而是把跨领域差异抽象为配置化的领域画像。

因此系统的扩展单位从“写死一个新 stage”变成了:

  • 新 profile
  • 新 sandbox/backend
  • 新 prompt bank
  • 必要时的新外部 agent
这是平台化设计的关键。


12. 实验执行子系统:从本地沙盒到外部 Agent 的多后端执行面

12.1 工厂模式

researchclaw/experiment/factory.py 按 experiment.mode 创建不同 backend:

  • sandbox
  • docker
  • ssh_remote
  • colab_drive
  • collider_agent
  • biology_agent
  • stat_agent
另有 create_agentic_sandbox() 支持 agentic 模式。

12.2 这层解决的核心问题

研究自动化最大的难点不是“生成代码”,而是把代码安全、稳定、可约束地跑起来。

因此 researchclaw/experiment/ 下并不只有一个 runner,而是形成了一套执行生态:

  • sandbox.py:本地 subprocess
  • docker_sandbox.py:容器隔离、GPU 直通、网络策略
  • ssh_sandbox.py:远端服务器
  • colab_sandbox.py:Google Drive 轮询式 Colab
  • agentic_sandbox.py:把实验交给 coding agent
  • *_agent_sandbox.py:领域专用外部 agent
  • validator.py:语法/安全/导入检查与修复
  • visualize.py:实验图表生成

12.3 执行层的设计思想

这一层体现出三个重要理念:

1. 后端多样性优先:不同研究场景需要不同执行环境 2. 安全与可控优先:不是让模型直接在宿主机乱跑 3. 代码生成与代码执行分离:生成逻辑在 pipeline,运行策略在 experiment


13. OpenCode / Code Agent:复杂代码生成的旁路系统

13.1 为什么需要旁路

对于复杂实验,仅靠一次 LLM 生成单文件脚本常常不够,因此系统引入了:

  • researchclaw/pipeline/opencode_bridge.py
  • researchclaw/experiment/code_agent.py

13.2 Beast Mode 的本质

opencode_bridge.py 会先做 complexity scoring:

  • 组件复杂度
  • 多文件暗示
  • 领域复杂度
  • 条件/ablation 数量
  • 历史失败
  • 依赖深度
再决定是否路由到 OpenCode CLI。

这是一种典型的策略路由式架构:

  • 简单问题:走普通 code generation
  • 复杂问题:升级到更强的外部 coding agent
这比“全量默认调用最重 agent”更工程化,也更符合成本/可靠性平衡。


14. 多 Agent 子系统:增强型能力不是塞进主流水线,而是独立编排

researchclaw/agents/ 代表项目的一种重要组织原则:

当一个能力本身已经像一个小流水线时,不把它写成一个 stage 内的大函数,而把它做成独立 orchestrator。

14.1 公共基类

researchclaw/agents/base.py 提供:

  • BaseAgent
  • AgentOrchestrator
  • AgentStepResult
说明作者试图给“子 agent 系统”建立统一语义,而不是各写各的。

14.2 BenchmarkAgent

researchclaw/agents/benchmark_agent/ 是一个四段式子系统:

  • Surveyor
  • Selector
  • Acquirer
  • Validator
输出 BenchmarkPlan,服务于实验设计和代码生成。

14.3 FigureAgent

researchclaw/agents/figure_agent/ 是一个更典型的 multi-agent pipeline:

  • Decision Agent
  • Planner
  • CodeGen
  • Renderer
  • Critic
  • Integrator
  • Nano Banana(图像生成)
它解决的是“论文图形生产”这个独立问题域。

14.4 架构意义

这说明 AutoResearchClaw 的总体结构不是“单层 agent”,而是:

  • 主流水线作为 macro orchestrator
  • 若干子系统作为 micro orchestrator
这是一个分层 agent orchestration 架构。


15. HITL / Co-Pilot:把人放回流水线中间,而不是只能在开头给 topic

15.1 HITL 不是附加功能,而是第二控制面

与人机协作直接相关的代码主要分布在两处:

  • researchclaw/hitl/:更完整的 HITL session、暂停、恢复、协作、TUI、workshop 体系
  • researchclaw/copilot/:更轻量的 Co-Pilot 控制器、反馈处理、分支控制
其中 researchclaw/hitl/ 规模更大,覆盖:
  • intervention enum / protocol
  • session
  • quality predictor
  • smart pause
  • claim verifier
  • branching
  • collaboration / chat
  • TUI
  • workshops
researchclaw/hitl/session.py 表明 HITL 是可持久化 session,能在 pipeline pause/resume 中跨进程存在;而 researchclaw/copilot/controller.py 则体现了另一条更偏“控制策略层”的协作接口。

15.2 它解决的问题

LLM research pipeline 的难点往往在关键决策节点:

  • hypothesis 是否值得做
  • baseline 是否完整
  • 实验输出是否可信
  • draft 是否有真实贡献
所以项目不是简单加一个 --interactive,而是实现了:
  • 不同 intervention mode
  • per-stage policy
  • detached attach/approve/reject/guide
  • collaboration mode
  • file-based fallback waiting

15.3 设计思想

这里体现的不是“人类兜底”,而是:

把人类视为系统中的高价值稀缺计算资源,只在最值得的地方插入。

这也是 README 和 docs/HITL_GUIDE.md 一直强调的 Co-Pilot 思路。


16. Adapter 层:外部系统集成的总线

researchclaw/adapters.py 定义了一组 protocol:

  • CronAdapter
  • MessageAdapter
  • MemoryAdapter
  • SessionsAdapter
  • WebFetchAdapter
  • BrowserAdapter
并通过 AdapterBundle 聚合。

16.1 为什么这层很关键

它让 pipeline 可以依赖“能力接口”,而不是依赖某个具体平台:

  • 有 OpenClaw / MCP 时,接入对应 adapter
  • 没有时,用 recording stub
与此相配套,researchclaw/mcp/ 还提供了 client/server/tools/transport,说明项目并不把 MCP 当成单点工具,而是当成正式的集成通道。

这是一种经典的ports and adapters / hexagonal architecture 思路。

16.2 直接收益

1. 更容易测试 2. 更容易集成 OpenClaw 3. 更容易接 Web / messaging / cron / browser 4. 更容易在无外部平台时退化运行


17. Knowledge / Memory / Evolution / MetaClaw:系统的长期记忆层

这部分是项目区别于“一次性执行型 agent”的关键。

17.1 Knowledge Base:面向 artifact 的结构化沉淀

researchclaw/knowledge/base.py 把阶段产物按类别写入知识库:

  • questions
  • literature
  • experiments
  • findings
  • decisions
  • reviews
支持 markdown 和 obsidian backend。

这说明知识库不是向量库优先,而是可读性优先的 markdown knowledge log。

17.2 Memory:更像检索式短中期记忆

researchclaw/memory/store.py 提供:

  • ideation / experiment / writing 三类 memory
  • embedding 字段
  • confidence
  • access count
  • prune/save/load
这是一个比 knowledge base 更“机器友好”的存储层。

17.3 Evolution:跨运行 lesson 注入

researchclaw/evolution.py 用 JSONL 记录 lesson,并能生成 overlay 注入未来 prompt。

重点不在复杂算法,而在一个很清晰的闭环:

1. 本次运行失败/退化/卡住 2. 提取 lesson 3. lesson 存盘 4. 下次同阶段 prompt 自动吸收经验

17.4 MetaClaw:把 lesson 升级成 skill

researchclaw/metaclaw_bridge/ 做的是更激进的跨运行学习:

  • skill effectiveness tracking
  • PRM gate
  • lesson-to-skill
换句话说:
  • Evolution 更像“本地经验叠层”
  • MetaClaw 更像“外部元学习/技能生态桥”
这让系统有了从单次运行优化走向跨运行能力演化的趋势。


18. 技能系统:把领域知识打包成可装载单元

researchclaw/skills/ 支持:

  • SKILL.md
  • YAML / JSON legacy formats
  • registry / matcher / loader
这意味着 skills 在项目中不是纯文档,而是一种可发现、可匹配、可注入的能力单元。

从设计角度看,skills 把“经验/知识/流程”从代码里抽出来,形成了第三种扩展方式:

1. 改代码 2. 改配置/profile 3. 加 skill

这对 agent 生态非常关键,因为很多增强并不值得写进核心逻辑。


19. 质量控制链:不是只在最后评分,而是贯穿多层

AutoResearchClaw 的质量控制不是单点,而是多层链路:

19.1 前置层

  • Config validate
  • preflight
  • doctor
  • code validator

19.2 过程层

  • stage contract
  • gate approval
  • HITL pause
  • experiment diagnosis / repair
  • benchmark/figure agent validator

19.3 后置层

  • peer review
  • paper revision
  • quality gate
  • citation verify
  • paper verifier / assessor / verified registry
这表明系统在架构上采用的是多重弱保证叠加,而不是相信某一个 stage 会“生成正确结果”。


20. 导出与写作层:从实验结果到论文交付物

写作与导出相关能力分布在:

  • pipeline/stage_impls/_paper_writing.py
  • pipeline/stage_impls/_review_publish.py
  • researchclaw/templates/
  • researchclaw/assessor/
  • researchclaw/overleaf/

20.1 这一层的职责

  • 生成 outline / draft / review / revision
  • 把实验结果转成 paper 内容
  • 生成图表、表格、BibTeX、conference-specific output
  • 做 paper quality scoring
  • 同步 Overleaf / conference style
说明项目并不把“导出”视作末端格式化,而是把它视作研究产物编译链的一部分。


21. Server / Dashboard / Web:运行中的可视化和服务化方向

21.1 FastAPI 服务端

researchclaw/server/app.py 创建 FastAPI 应用,提供:

  • /api/health
  • /api/config
  • pipeline/projects/chat/voice routes
  • /ws/events WebSocket

21.2 Dashboard

researchclaw/dashboard/ 中:

  • collector.py 负责收集 run snapshot
  • broadcaster.py 定期把变化推送到 WebSocket
  • metrics.py 提供展示数据
这说明 dashboard 不是另建数据库,而是从 run_dir artifact 反向构建视图。

21.3 前端现状的架构信号

仓库中同时存在:

  • website/:静态官网/产品说明站
  • frontend-legacy/:旧版前端原型
  • researchclaw/server/app.py:会尝试挂载 frontend/ 目录
这表明 Web 产品面仍在演进中,当前更像:
  • 一套稳定的静态展示站
  • 一套实验性/遗留前端
  • 一个已经具备服务化接口的后端
也就是说,服务端能力已经先行,统一前端产品形态还在收敛中。


22. 外部 Agent 集成:AutoResearchClaw 不试图自己做所有科学计算

external/agents/README.md 讲得很清楚:某些领域不是在主仓库里自己实现全部 scientific pipeline,而是接外部 Claude-Code agent:

  • Biology-Agent
  • stat_research_agent
  • ColliderAgent
AutoResearchClaw 的职责变成:

1. 识别领域 2. 选择 experiment mode 3. 准备 prompt / workspace / skill mounting 4. 调用外部 agent 5. 回收结果并继续主流水线

这是一种很成熟的边界意识:

ResearchClaw 做编排平台,不强迫自己成为所有学科的执行引擎。


23. ARC-Bench:把产品能力外化成可比较的 benchmark

experiments/arc_bench/ 不是附带 demo,而是一套结构非常完整的 benchmark 体系。

23.1 范围

当前公开结构里包含 55 个 topic:

  • ML:25
  • Physics:10
  • Quantum:10
  • Biology:7
  • Statistics:3

23.2 作用

它承担了三种角色:

1. 外部比较基准:与 AIDE、AgentLaboratory、AI Scientist v2 等比较 2. 内部回归场:新功能可以在 bench 上验证 3. 方法论文资产:证明系统不是“看起来能跑”,而是“可以被统一 rubric 评估”

23.3 架构含义

很多 agent 项目只有产品,没有 benchmark;AutoResearchClaw 把 benchmark 放进主仓库,说明它很重视:

  • 可复现性
  • 可审计性
  • 系统级比较
这也是一种研究系统而非普通应用系统的典型特征。


24. 测试结构:系统复杂度已经进入“平台级”规模

tests/ 下当前可见 85 个测试文件,覆盖面很广:

  • CLI / config / stages / contracts / runner / executor
  • literature / llm / prompts / kb / evolution
  • docker / ssh / colab / validators
  • HITL 全链路
  • figure agent / benchmark agent / code searcher
  • mcp / metaclaw / overleaf / memory / dashboard / server
这说明项目已经不是“少量 e2e + 若干 happy path unit tests”的阶段,而是在向复杂平台的回归网靠近。


25. 设计思想总结

综合代码和文档,这个项目有几条非常鲜明的设计思想。

25.1 状态机优先,而非 prompt 串联

核心不是“23 个 prompt 模板”,而是一个可审计的状态机。

25.2 Artifact-first,而非内存上下文优先

阶段之间主要通过文件系统产物衔接,因此系统天然更可恢复、可检查、可基准化。

25.3 配置驱动的平台化

大量能力通过 config / profile / adapter / skill 装配,而不是写死在 runner。

25.4 分层 agent orchestration

主流水线是 macro orchestrator,FigureAgent/BenchmarkAgent 等是 micro orchestrator。

25.5 人机协作是主路径,而不是补丁

HITL/Co-Pilot 不是后装 UI,而是第二控制面。

25.6 外部世界接入是真实研究的必要条件

文献 API、实验后端、外部 agent、ACP、MCP、OpenClaw,构成了系统的现实接触面。

25.7 跨运行学习

Knowledge、Memory、Evolution、MetaClaw 共同表明它不满足于一次性运行,而想做“会积累经验的研究系统”。


26. 这个架构的优势

26.1 可恢复性强

checkpoint + artifact + heartbeat + sentinel 让长流程更稳。

26.2 易于审查

每个阶段都有显式产物,适合人工 review、自动 judge 和 benchmark。

26.3 扩展路径清晰

新增领域、后端、技能、agent、prompt bank 都有明确挂点。

26.4 多运行模式共存

full-auto、gate-only、co-pilot、ACP/OpenClaw、Web server 都能共享同一个内核。

26.5 适合研究场景

真实文献、真实实验、质量门控、引用校验,让它比“直接写论文”更接近研究工作流。


27. 这个架构的代价与复杂性来源

27.1 仓库边界较宽

核心引擎、站点、前端、benchmark、外部 agent 接入、server 都在同仓库,理解成本较高。

27.2 配置面很大

RCConfig 已经承担了很多系统变体,灵活但也增加了认知负担。

27.3 流程与子系统交叉较多

一个 stage 可能同时接触:

  • prompt
  • llm
  • domain profile
  • HITL
  • adapters
  • KB
  • quality logic
  • experiment backend
因此问题定位需要较强的系统视角。

27.4 Web 面还在演化

website/、frontend-legacy/、server/app.py 中的 frontend/ 挂载预期,显示前端产品面仍处于收敛阶段。


28. 如何理解这个项目的“架构中心”

如果只看目录,很容易误以为系统中心是:

  • LLM client
  • 实验沙盒
  • HITL
  • OpenClaw 集成
但真正的架构中心其实是:

researchclaw/pipeline/ 里的状态机 + 合同 + 执行协议

原因很简单:

  • 没有它,LLM 只是聊天接口
  • 没有它,实验后端只是若干 runner
  • 没有它,HITL 只是暂停工具
  • 没有它,Knowledge/Evolution 也无从挂接
所以这套系统的真正核心不是“某个最炫的子模块”,而是一个相对朴素但非常关键的可恢复状态机骨架。


29. 推荐的阅读顺序

如果要继续深入源码,推荐按这个顺序阅读:

1. README.md 2. researchclaw/cli.py 3. researchclaw/config.py 4. researchclaw/pipeline/stages.py 5. researchclaw/pipeline/contracts.py 6. researchclaw/pipeline/runner.py 7. researchclaw/pipeline/executor.py 8. researchclaw/pipeline/stage_impls/ 9. researchclaw/experiment/ 10. researchclaw/domains/ 11. researchclaw/hitl/ 12. researchclaw/agents/ 13. researchclaw/knowledge/、researchclaw/memory/、researchclaw/evolution.py 14. experiments/arc_bench/

这样读,最容易先把“稳定骨架”抓住,再看各类能力插件。


30. 结论

AutoResearchClaw 的架构本质上是:

一个以 23 阶段状态机为核心、以 artifact 为主接口、以配置/adapter/profile/skill 为扩展点、同时支持自治运行与人机协作的研究自动化平台。

它最突出的地方不只是“能写论文”,而是:

  • 把研究工作流拆成显式阶段
  • 把阶段边界落成文件合同
  • 把执行环境做成可切换后端
  • 把人类反馈做成第一等控制面
  • 把跨运行经验做成长期记忆层
  • 把外部 Agent 和 benchmark 体系也纳入同一仓库生态
因此,从架构视角看,它更像一个研究自动化操作系统 / 编排平台,而不是一个单点功能 agent。

👍 1

想参与讨论或点赞?登录后使用完整功能

讨论回复(0)

暂无回复,登录后可参与讨论
合作

智谱 GLM-5 已上线

在智谱开放平台 BigModel.cn 打造 AI 应用。新一代旗舰模型 GLM-5 在推理、代码、智能体综合能力达到开源模型 SOTA。

领取 2000万 Tokens