文章目录

AutoResearchClaw 项目深度分析

在这里插入图片描述

一、项目简介

AutoResearchClaw 是一个全自主、自进化、协作式的学术研究自动化引擎。用户只需输入一个研究主题（idea），系统即可自动完成从文献检索、假设生成、实验设计、代码生成与执行、结果分析、论文撰写到最终可投稿 LaTeX 输出的全 23 阶段流水线。核心口号：“Chat an Idea. Get a Paper.”——对话一个想法，获得一篇论文。

功能定位：You think it. AutoResearchClaw writes it. You guide the key decisions. ——用户只需给出一个研究主题，即可获得一篇包含真实文献（OpenAlex/Semantic Scholar/arXiv）、硬件感知沙盒实验、统计分析、多Agent同行评审、可投稿LaTeX的完整学术论文。实验失败时自动修复，假设不成立时自动转向（PIVOT），引用造假时自动清除，用户想引导时暂停聆听。

已验证的跨领域能力：项目Showcase展示了8篇跨8个领域的全自主生成论文——数学（随机矩阵论）、统计学（弱工具变量估计）、生物学（SIR/SEIR可识别性）、数值计算（Krylov预条件）、NLP（LoRA自适应秩）、强化学习（稀疏奖励探索）、计算机视觉（频谱感知Token合并）、知识蒸馏（鲁棒蒸馏）。8篇论文合计54,348行代码、~27小时运行时间、291篇引用（99.7%验证通过）、50张自动生成图表、121页NeurIPS格式输出——全部从一行主题生成，无需人工干预。

二、核心内容概述

2.1 核心能力

能力 说明
全自主 23 阶段流水线 从研究主题到可投稿论文的端到端自动化，含门控/回滚/决策循环。一条命令researchclaw run --topic "..." --auto-approve即可出论文
实验-分析-决策循环 双层循环：内层代码自愈（Stage 13）+ 外层策略调整（PIVOT/REFINE），四层递进处理机制
真实文献检索 对接 OpenAlex、Semantic Scholar、arXiv 真实 API，查询扩展+去重+熔断降级，无幻觉引用
4 层引用验证 arXiv ID → CrossRef/DataCite DOI → Semantic Scholar → LLM 相关性评分，幻觉引用自动移除
硬件感知 自动检测 GPU（NVIDIA CUDA / Apple MPS / CPU-only），适配代码生成
自进化学习 每次运行提取教训（lessons），跨运行注入后续流水线
人机协作 Co-Pilot 6 种干预模式 + SmartPause 置信度驱动 + 3 个协作工作坊
反捏造系统 VerifiedRegistry 强制论文仅使用真实实验数据，自动诊断失败实验并修复后再写，未验证数值自动清洗
多 Agent 子系统 CodeAgent、BenchmarkAgent、FigureAgent 三大多智能体协作
9 领域适配 25+ 领域配置 YAML + PromptAdapter 适配器，覆盖 ML/物理/生物/化学/经济/数学/神经科学/机器人/安全

2.2 输出产物

产物 描述
paper_draft.md 完整学术论文（Introduction → Conclusion）
paper.tex 可编译 LaTeX（NeurIPS/ICML/ICLR 模板）
references.bib 真实 BibTeX 引用
verification_report.json 4 层引用完整性验证报告
experiment runs/ 实验代码 + 沙盒结果 + 结构化 JSON 指标
charts/ 自动生成对比图表（含误差线和置信区间）
reviews.md 多 Agent 同行评审
deliverables/ 所有最终输出的合集——Overleaf 直接编译

三、主要运行逻辑

3.1 流水线架构：23 阶段、8 阶段组

Phase A: 研究范围界定          Phase E: 实验执行
  1. TOPIC_INIT（主题初始化）      12. EXPERIMENT_RUN（实验运行）
  2. PROBLEM_DECOMPOSE（问题分解） 13. ITERATIVE_REFINE（迭代优化）← 自愈

Phase B: 文献发现              Phase F: 分析与决策
  3. SEARCH_STRATEGY（搜索策略）   14. RESULT_ANALYSIS（结果分析）← 多Agent
  4. LITERATURE_COLLECT（文献采集）15. RESEARCH_DECISION（研究决策）← PIVOT/REFINE
  5. LITERATURE_SCREEN（文献筛选）[门控]
  6. KNOWLEDGE_EXTRACT（知识提取） Phase G: 论文撰写
                                     16. PAPER_OUTLINE（论文大纲）
Phase C: 知识综合                17. PAPER_DRAFT（论文初稿）
  7. SYNTHESIS（综合聚类）          18. PEER_REVIEW（同行评审）← 证据一致性检查
  8. HYPOTHESIS_GEN（假设生成）← 辩论 19. PAPER_REVISION（论文修订）

Phase D: 实验设计              Phase H: 终结化
  9. EXPERIMENT_DESIGN（实验设计）[门控] 20. QUALITY_GATE（质量门控）[门控]
 10. CODE_GENERATION（代码生成）      21. KNOWLEDGE_ARCHIVE（知识归档）
 11. RESOURCE_PLANNING（资源规划）     22. EXPORT_PUBLISH（导出发布）← LaTeX
                                      23. CITATION_VERIFY（引用验证）← 相关性检查

各阶段组的功能性职责：

阶段组 功能 用户可见价值
A: 研究范围界定 将模糊主题分解为结构化问题树和研究问题 明确研究边界，避免漫无目的
A+: 硬件感知 自动检测GPU（CUDA/MPS/CPU），限制不足时告警，适配代码生成 无需手动配置，代码自动适配硬件
B: 文献发现 三源搜索（OpenAlex→Semantic Scholar→arXiv）获取真实论文，按相关性筛选，提取知识卡片 获得真实文献而非幻觉引用
C: 知识综合 聚类发现→识别研究间隙→多Agent辩论生成可证伪假设 提出真正新颖可验证的研究假设
D: 实验设计 设计实验计划、生成硬件感知可运行Python、预估资源需求 一键获得可执行的实验代码
E: 实验执行 沙盒运行→NaN/Inf检测→自愈修复→迭代优化 实验失败自动修复，无需手动调试
F: 分析与决策 多Agent分析→自主决策PROCEED/REFINE/PIVOT 实验不好自动调整方向
G: 论文撰写 大纲→逐节撰写(5000-6500词)→同行评审(含方法论-证据一致性检查)→修订 获得会议级论文而非草稿
H: 终结化 质量门控→知识归档→LaTeX导出(会议模板)→引用完整性+相关性验证 Overleaf直接编译的可投稿论文包

门控阶段（5、9、20）在人工审批时暂停，--auto-approve自动通过；拒绝时触发回滚（阶段5拒→回4，阶段9拒→回8，阶段20拒→回16）。

Co-Pilot模式下深度协作发生在阶段7-8（Idea Workshop）、阶段9（Baseline Navigator）、阶段16-17（Paper Co-Writer），其余阶段自动执行+SmartPause监控。

3.2 核心：实验-分析-决策循环（阶段 10-15）

整体循环架构

                    ┌──────────────────────────────────────────────────┐
                    │         外层循环: PIVOT/REFINE 递归回滚          │
                    │                                                  │
                    │   ┌──────────────────────────────────────────┐   │
                    │   │      内层循环: Stage 13 for迭代优化       │   │
                    │   │                                          │   │
                    │   │  for i in 1..max_iterations:             │   │
                    │   │    LLM improve代码 → AST校验              │   │
                    │   │    → 沙盒运行 → 检测NaN/Inf              │   │
                    │   │    → 有问题? → LLM repair → 重跑一次      │   │
                    │   │    → 比较指标 → 更新best                  │   │
                    │   │    → 连续2轮无改善? → 收敛退出             │   │
                    │   └──────────────────────────────────────────┘   │
                    │                                                  │
                    │  Stage 14: 多视角分析 + 实验诊断 + 修复循环      │
                    │  Stage 15: LLM决策 → _parse_decision()          │
                    │       │                                          │
                    │       ├── "proceed" → 阶段16（写论文）           │
                    │       ├── "refine"  → 递归execute_pipeline(13)   │
                    │       └── "pivot"   → 递归execute_pipeline(8)    │
                    └──────────────────────────────────────────────────┘

Stage 13 内层循环的精确逻辑（_execution.py:753-1120）

# 核心循环结构（简化）
for iteration in range(1, max_iterations + 1):  # max_iterations = min(config, 10)
    # 1. 超时保护：整个Stage 13有壁钟时间上限（1.5×per_iter_budget）
    if elapsed > max_refine_wall_sec: break

    # 2. LLM改进代码：iterative_improve 子提示词
    #    输入：当前best_files + 历史run_summaries + 实验计划锚点
    #    输出：改进后的多文件代码
    response = chat(iterative_improve, files_context, run_summaries, ...)
    candidate_files = extract_multi_file_blocks(response)

    # 3. AST校验 → 不通过则 iterative_repair 修复
    validation = validate_code(candidate_files["main.py"])
    if not validation.ok:
        repair_response = chat(iterative_repair, issues, ...)
        candidate_files["main.py"] = extract_code_block(repair_response)

    # 4. 沙盒运行改进后的代码
    rerun = sandbox.run_project(version_dir, timeout_sec=time_budget)

    # 5. 检测运行时问题（NaN/Inf/除零/overflow）
    runtime_issues = detect_runtime_issues(rerun)
    if runtime_issues:
        # 6. LLM修复运行时问题 → 修复后重跑一次
        repair_resp = chat(iterative_repair, runtime_issues, ...)
        rerun2 = sandbox.run_project(...)  # 修复后再跑一次
        metric_val = find_metric(rerun2.metrics, metric_key)

    # 7. 指标比较与更新
    if is_better(metric_val, best_metric):
        best_metric = metric_val
        best_files = candidate_files  # 更新best
        no_improve_streak = 0
    else:
        no_improve_streak += 1

    # 8. 收敛检测（提前退出）
    if consecutive_no_metrics >= 3: break   # 连续3轮无指标
    if no_improve_streak >= 2: break         # 连续2轮无改善 → 认为收敛

额外注入机制：

  • 条件覆盖缺口检测：如果stdout中没有condition=标签 → 注入多条件提示
  • 基准饱和检测：如果指标≥0.999 → 注入"增加难度"提示
  • 超时感知注入：如果前序实验超时且无结果 → 注入"大幅缩减实验规模"提示

Stage 15 外层循环的精确逻辑（_analysis.py:789-938 + runner.py:682-770）

决策解析：LLM 输出 markdown，_parse_decision() 从 ## Decision 标题后提取关键词：

def _parse_decision(text: str) -> str:
    """从LLM的markdown输出中解析PROCEED/PIVOT/REFINE"""
    # 1. 找 ## Decision 段落
    # 2. 找独立成行的关键词（PROCEED/PIVOT/REFINE）
    # 3. Fallback: 正则匹配独立关键词（排除"PIVOT is not warranted"这种否定句）
    # 4. Last resort: 取最后出现的关键词（最终结论更可靠）
    # 默认返回 "proceed"

决策提示词注入：Stage 15 有三重注入影响决策：

  • _degenerate_hint：检测退化REFINE循环（指标全饱和/全相同）→ 注入"应选PROCEED"
  • _diagnosis_hint：实验诊断发现不足 → 注入"可选REFINE，但2+轮后应PROCEED"
  • _ablation_refine_hint：>50%消融无效 → 注入"强烈推荐REFINE"

回滚执行（runner.py:682-738）：

DECISION_ROLLBACK = {
    "pivot": Stage.HYPOTHESIS_GEN,     # → 回到阶段8重新假设
    "refine": Stage.ITERATIVE_REFINE,  # → 回到阶段13重新优化
}
MAX_DECISION_PIVOTS = 2

# 当 Stage 15 完成且 decision in DECISION_ROLLBACK:
if pivot_count > 0 and _consecutive_empty_metrics(run_dir, pivot_count):
    # 安全阀1：连续REFINE产生空指标 → 强制PROCEED
elif pivot_count < MAX_DECISION_PIVOTS:
    # 正常回滚：版本化旧目录 → 递归调用execute_pipeline(from_stage=rollback_target) → break
    _version_rollback_stages(run_dir, rollback_target, pivot_count + 1)
    pivot_results = execute_pipeline(from_stage=rollback_target, ...)
    results.extend(pivot_results)
    break  # 当前循环退出，递归调用接管后续
else:
    # 安全阀2：达到最大PIVOT次数 → 强制PROCEED + quality_warning.txt

关键：循环是递归不是跳转——PIVOT/REFINE 时，当前 execute_pipeline() 的 for 循环 break 退出，新的 execute_pipeline(from_stage=rollback_target) 递归调用从回滚目标开始重新执行。递归调用会从头跑过 rollback_target → … → Stage 23（如果中间不再触发回滚）。

各阶段在循环中的职责

阶段 循环角色 关键行为
10 CODE_GENERATION 循环引擎 CodeAgent V2：架构规划→逐文件生成(依赖DAG)→AST硬校验→执行修复循环
11 RESOURCE_PLANNING 资源分配 LLM 生成调度 JSON（GPU数/预估时间/依赖/优先级），硬件感知
12 EXPERIMENT_RUN 首次执行 沙盒执行，部分结果捕获（超时不丢失已有数据）
13 ITERATIVE_REFINE 内层循环 for循环1~10轮：LLM改进→AST校验→沙盒运行→NaN检测→修复重跑→指标比较→收敛检测退出
14 RESULT_ANALYSIS 多视角分析 合并Stage12+13数据，Bootstrap 95%CI，配对t检验，实验诊断(12种缺陷)，Spec验证
15 RESEARCH_DECISION 外层循环 LLM输出markdown→_parse_decision()提取PROCEED/REFINE/PIVOT→递归回滚

产物版本化与数据晋升

回滚时旧目录版本化保存（不覆盖）：

stage-08/       ← 首次假设
stage-08-v1/    ← 第1次PIVOT后的新假设
stage-13/       ← 首次迭代优化
stage-13-v1/    ← REFINE后的重新优化
stage-14/       ← 首次结果分析
stage-14-v1/    ← 重新分析

数据晋升（_promote_best_stage14）：在进入论文撰写（Stage 16）前，从所有版本的 stage-14*/experiment_summary.json 中选质量分最高的晋升为正式的 stage-14/experiment_summary.json，确保论文使用最好的实验数据而非最新迭代的（可能更差的）数据。

3.3 结果与预期不符合时的四层递进处理

第一层：Stage 13 内层循环（代码级自愈）

每轮迭代中的处理链：

沙盒运行 → 检测NaN/Inf/除零/overflow → iterative_repair诊断根因 → 修复 → 重跑一次
→ 修复后仍有问题 → 记录到iter_record → 下一轮迭代继续尝试改进
→ 连续3轮无任何指标 → 放弃，终止Stage 13
→ 连续2轮有指标但无改善 → 认为收敛，终止Stage 13

第二层：Stage 14 后置的实验诊断与修复循环

Stage 14 完成后，_run_experiment_diagnosis() 评估实验质量，若 repair_needed=True 则触发修复循环（最多3轮）。诊断识别 12 种缺陷：

DeficiencyType 严重度 修复策略
NO_CONDITIONS_COMPLETED critical 全面重写实验代码
TOO_FEW_CONDITIONS major 减少消融条件，保留核心对比
MISSING_BASELINE/PROPOSED critical 添加标准 baseline/确保提出方法
TIME_GUARD_DOMINANT major 范围缩减：保留 baseline+proposed+1消融，减少epoch 30-50%
CODE_CRASH / GPU_OOM critical LLM诊断/减小batch size
INSUFFICIENT_SEEDS major 增加 seed 数

第三层：Stage 15 决策循环（策略级调整）

  • REFINE：保持假设方向，微调参数/增加数据 → 递归 execute_pipeline(from_stage=Stage.ITERATIVE_REFINE)
  • PIVOT：假设方向错误，换方法 → 递归 execute_pipeline(from_stage=Stage.HYPOTHESIS_GEN)

第四层：安全阀（系统级兜底）

  • MAX_DECISION_PIVOTS=2，超过后强制 PROCEED
  • _consecutive_empty_metrics()：连续REFINE产生空指标 → 强制 PROCEED
  • _check_experiment_quality()：最大PIVOT后质量检查 → 不通过则写 quality_warning.txt

3.4 完整循环时序示例

首次运行：
  Stage 10: 生成代码 → Stage 11: 资源规划
  Stage 12: 沙盒运行 → accuracy=0.72 (baseline=0.75)
  Stage 13: 内层循环：
    iter 1: LLM改进 → 沙盒运行 → 0.74 (更好, best=0.74)
    iter 2: LLM改进 → 沙盒运行 → 0.76 (更好, best=0.76)
    iter 3: LLM改进 → 沙盒运行 → 0.76 (无改善, no_improve_streak=1)
    iter 4: LLM改进 → 沙盒运行 → 0.75 (无改善, no_improve_streak=2 → 收敛退出)
  Stage 14: 多视角分析 → proposed(0.76) vs baseline(0.75), p=0.32 (不显著)
  Stage 15: LLM决策 → _parse_decision() = "refine"
  → 递归 execute_pipeline(from_stage=Stage.ITERATIVE_REFINE)

第1次 REFINE 递归：
  Stage 13(v1): 内层循环：
    iter 1: LLM改进(增加seed,调参) → 沙盒运行 → 0.79 (更好)
    iter 2: 无改善 → 收敛退出
  Stage 14(v1): 重新分析 → proposed(0.79) vs baseline(0.75), p=0.04 (显著!)
  Stage 15(v1): LLM决策 → _parse_decision() = "proceed"
  → 不触发回滚 → 继续Stage 16写论文

(如果Stage 15决策PIVOT → 递归execute_pipeline(from_stage=Stage.HYPOTHESIS_GEN)):
  Stage 08(v1): 生成新假设(完全不同的方法)
  Stage 09(v1): 重新设计实验
  Stage 10(v1): 重新生成代码
  Stage 11-15: 重新执行...
  → 如果再次PIVOT → 第2次递归（pivot_count=2达到MAX → 强制PROCEED）

3.5 阶段状态机

class StageStatus(str, Enum):
    PENDING = "pending"
    RUNNING = "running"
    BLOCKED_APPROVAL = "blocked_approval"  # 门控等待审批
    APPROVED = "approved"
    REJECTED = "rejected"          # 触发回滚
    PAUSED = "paused"              # HITL 暂停
    RETRYING = "retrying"
    FAILED = "failed"
    DONE = "done"

门控回滚规则：阶段5拒→回4（重采集文献）；阶段9拒→回8（重假设）；阶段20拒→回16（重写论文）

3.6 核心运行流程

  1. 入口：researchclaw run --topic "研究主题" --auto-approve
  2. 配置加载：RCConfig 从 YAML 加载，初始化 LLMClient + AdapterBundle + PromptManager
  3. 领域检测：_detect_domain(topic, context) → DomainProfile → 选择 PromptAdapter
  4. 流水线运行：execute_pipeline() 依次执行23阶段
  5. 阶段执行：execute_stage() → 领域适配注入提示词 → LLM调用 → 产物写入 → 知识库写入
  6. 门控检查：阶段5/9/20需审批（或--auto-approve自动通过）
  7. 决策回滚：Stage 15 的 PIVOT/REFINE → 递归调用 execute_pipeline(from_stage=...)
  8. 检查点持久化：每阶段写 checkpoint.json，支持 --resume 断点续跑
  9. 心跳监控：sentinel.sh 守护进程监控流水线健康
  10. 进化学习：EvolutionStore 提取教训，注入后续运行

MetaClaw跨运行学习：Run N执行→失败/警告捕获为Lessons→Lesson转Skill→存储于~/.metaclaw/skills/→Run N+1的build_overlay()注入所有LLM提示词→LLM避免已知陷阱。控制实验结果：阶段重试率-24.8%、REFINE循环数-40%、流水线完成度+5.3%、综合鲁棒性+18.3%。默认关闭，metaclaw_bridge.enabled: true开启，完全向后兼容。

四、与大模型交互机制

4.1 LLM 客户端架构

系统采用 OpenAI 兼容协议 作为核心通信接口（researchclaw/llm/client.py）：

class LLMClient:
    def chat(self, messages, *, system=None, max_tokens=None, temperature=None, json_mode=False) -> LLMResponse

关键特性：模型回退链（primary→fallback[0]→fallback[1]…）、指数退避重试（上限300s）、JSON模式（文献采集/筛选/知识提取强制JSON）、MetaClaw桥接、Anthropic/Gemini适配器。

功能价值：用户无需关心模型可用性——主模型故障时自动切换fallback模型，API限流时指数退避重试，整个23阶段流水线对LLM调用失败具有弹性容错能力。

4.2 支持的 LLM 接入方式

方式 说明
OpenAI 兼容 API base_url + api_key（OpenAI、DeepSeek、Volcengine、BytePlus等）
ACP 协议 Agent Client Protocol，接入CLI代理（Claude Code/Codex CLI/Gemini CLI），无需API Key
Anthropic/Gemini 直连 原生API适配
OpenRouter 路由到多模型

ACP模式功能价值：通过ACP协议，用户可直接使用本地安装的Claude Code、Codex CLI、Copilot CLI、Gemini CLI、Kimi CLI等作为LLM后端，无需配置API Key——Agent使用自身认证，维护跨23阶段的持久会话。

4.3 各阶段 LLM 交互模式

  • 标准模式：system + user 提示词，LLM 返回自由文本（大多数阶段）
  • JSON 模式：json_mode: true，LLM 强制返回 JSON（literature_collect/screen/knowledge_extract/resource_planning/quality_gate）
  • 多视角辩论：_multi_perspective_generate() 多视角独立生成 → _synthesize_perspectives() 综合（hypothesis_gen/result_analysis）
  • ACP 模式：通过 acp_client.py 将请求转发给CLI Agent，维护跨23阶段的持久会话

多视角辩论的功能价值：假设生成和结果分析阶段采用多Agent辩论而非单次生成——不同"角色"独立生成观点后综合，避免单一视角偏差，产出更全面、更有对抗性的研究假设和分析结论。

五、提示词设计

5.1 提示词架构

提示词系统采用外部化 YAML + 模板变量渲染（researchclaw/prompts.py）：

class PromptManager:
    def for_stage(self, stage_name, **variables) -> RenderedPrompt:
        """渲染某阶段的完整提示词（合并默认+用户覆盖+领域适配块）"""

设计原则：提示词与代码分离（prompts.default.yaml）、模板变量{var}安全渲染、可复用block、结构化输出。领域适配块通过 PromptAdapter 注入（见第七章）。

提示词工程功能价值：每个阶段的LLM角色精确定义（如"hypothesis_gen"=科学假设构建者，“peer_review”=平衡的会议审稿人），配合硬约束（禁止捏造数据、禁止虚收敛、必须引用精确数值），确保LLM输出符合学术标准而非自由发挥。提示词外部化YAML让用户无需改代码即可定制任何阶段的提示词。

5.2 各阶段提示词设计要点

阶段 System Prompt 角色 关键设计
topic_init 严谨的研究规划者 生成 SMART 研究目标
problem_decompose 高级研究策略师 分解为≥4个子问题，输出优先级排序
search_strategy 文献检索策略师 生成≥3策略×≥3查询=≥8总查询
literature_collect 文献挖掘助手 JSON输出≥20条候选，json_mode:true
literature_screen 严格领域审阅者 相关性+质量双维筛选，激进拒绝离题论文
knowledge_extract 高信号证据提取器 提取知识卡片，保留cite_key
synthesis 文献综述综合专家 聚类+研究间隙识别
hypothesis_gen 科学假设构建者 ≥2可证伪假设，含理由/可测预测/失败条件
experiment_design 主要研究者 YAML实验计划（目标/数据集/基准/方法/消融/指标/风险）
code_generation 计算科学家 多文件项目（filename:xxx.py），反模式约束，numpy 2.x兼容
result_analysis 定量 ML 分析师 必须引用精确数值，禁止发明数据
research_decision 研究项目主管 PROCEED/PIVOT/REFINE 三选一决策
paper_draft 顶会论文作者 逐节撰写5000-6500词，8条论文原则+5条常见拒因
peer_review 平衡的会议审稿人 ≥2审稿人视角，方法论-证据一致性检查，1-10评分
paper_revision 论文修订专家 仅扩展不缩短，维持最低字数
quality_gate 最终质量门控评估者 JSON输出评分+裁决+优劣势+必要行动

5.3 关键提示词片段

主题硬约束（topic_constraint）：论文必须关于指定主题；禁止将环境配置/调试日志当作贡献；每节必须联系核心研究问题。

计算预算约束（compute_budget）：总执行时间上限、条件缩放规则、时间估计、时间守卫。

反捏造约束（code_generation中）：禁止用random.uniform()伪造结果；禁止硬编码指标值；禁止无收敛检查的固定迭代；禁止虚收敛率返回值。

5.4 子提示词

  • code_repair：修复AST验证错误
  • iterative_improve：基于运行结果改进实验代码
  • iterative_repair：诊断NaN/Inf/除零根因并修复（不是加try/except，而是修复逻辑）

六、执行工具体系

6.1 适配器系统（AdapterBundle）

实现在 researchclaw/adapters.py，6 类 Protocol 适配器：

适配器 接口 用途
CronAdapter schedule_resume(run_id, stage_id, reason) 定时恢复研究运行
MessageAdapter notify(channel, subject, body) 进度通知（Discord/Slack/Telegram）
MemoryAdapter append(namespace, content) 跨会话知识持久化
SessionsAdapter spawn(name, command) 并行子会话
WebFetchAdapter fetch(url) 实时网络搜索（文献采集）
BrowserAdapter open(url) 浏览器论文采集

每个适配器均有 Recording* 存根（确定性测试）和 MCP* 实现。

6.2 实验执行环境

模式 实现 说明
simulated LLM生成 合成结果（快速，无代码执行）
sandbox experiment/sandbox.py 本地沙盒，AST校验+安全约束
docker experiment/docker_sandbox.py Docker容器，网络策略控制
ssh_remote experiment/ssh_sandbox.py 远程GPU服务器
colab experiment/colab_sandbox.py Google Colab

沙盒安全：AST校验（禁止subprocess/eval/exec/socket）、不可变harness、NaN/Inf快速失败、自愈修复循环（最多10轮）、部分结果捕获。

OpenCode Beast Mode：复杂实验自动路由到OpenCode，生成多文件项目（自定义架构、训练循环、消融研究），简单实验仍用内置代码生成——复杂度评分自动判定，失败时优雅降级回内置生成。

功能价值：5种执行环境覆盖从笔记本到GPU集群的全场景——本地开发用sandbox，生产实验用docker/ssh_remote，大规模训练用Colab，快速探索用simulated。OpenCode Beast Mode让复杂实验（多文件、自定义架构）也能自动生成，而非仅限单文件实验。

6.3 多 Agent 子系统

Agent 流水线 职责
CodeAgent 架构规划→依赖DAG顺序生成→AST硬校验→执行修复循环 多阶段代码生成
BenchmarkAgent Surveyor→Selector→Acquirer→Validator 自动选数据集和基准方法
FigureAgent Planner→CodeGen→Renderer→Critic→Integrator 自动生成学术论文图表

功能价值：

  • CodeAgent替代单次prompt代码生成——先生成架构蓝图再逐文件按依赖顺序生成，AST硬校验拦截相同消融和硬编码指标，执行失败时in-the-loop修复。让生成的代码从"一个main.py"升级为"多文件工程"。
  • BenchmarkAgent自动从HuggingFace Datasets和Google Scholar搜索合适数据集和baseline方法——不再依赖用户手动指定，4个子Agent协作确保选出的数据集可获取、baseline可复现。
  • FigureAgent自动生成学术论文图表——5个子Agent协作规划→生成代码→渲染→批评改进→集成到论文，每篇论文3-8张图表，含误差线和置信区间。

6.4 质量保障工具

工具 职责
VerifiedRegistry 实验数据白名单，论文只能引用真实实验值
PaperVerifier 反捏造验证
QualityAssessor 模板/占位符内容检测
Sentinel Watchdog 后台质量监控（NaN/Inf、论文-证据一致性、引用相关性）
ExperimentDiagnosis 实验失败诊断（12种缺陷类型）与修复
HardwareProfile GPU检测+分级（high/limited/cpu_only），影响代码生成和实验规模

质量保障功能价值：

  • VerifiedRegistry形成反捏造三重防线：实验数据注册→论文引用校验→未注册数值清洗。确保论文中每个数字都来自真实实验而非LLM编造
  • Sentinel Watchdog作为后台守护进程持续监控：检测NaN/Inf、校验论文-证据一致性、评分引用相关性——问题不等阶段结束就发现
  • Claim Verifier行内事实核查：提取AI生成文本中的声明，交叉验证已收集文献——标记无根据引用和捏造数值
  • 4轮论文质量审计：AI-slop检测→7维评审打分→NeurIPS清单检查→修订——产出会议级论文而非草稿
  • 成本守卫：预算监控，50%/80%/100%阈值告警，超预算自动暂停

6.5 技能系统

19 个内置技能（.claude/skills/），覆盖科学写作/文献搜索/化学/生物/a-evolve等。用户可通过 researchclaw skills install 或放入 .claude/skills/ 自定义。

技能系统功能价值：技能自动注入LLM提示词——无需手动激活。内置技能如scientific-writing（IMRAD结构、引用格式）、chemistry-rdkit（分子分析、SMILES、药物发现）、literature-search（系统综述、PRISMA方法）等开箱即用。社区贡献了150+科学技能（K-Dense-AI/claude-scientific-skills），用户也可创建自己的SKILL.md放入项目。

七、领域适配机制

7.1 三级领域检测

researchclaw/domains/detector.py 实现三级检测：

Level 1: 关键词匹配（快速确定性）→ "quantum"→physics_quantum, "single-cell"→biology_singlecell
Level 2: LLM分类（模糊主题）
Level 3: 混合解析（跨领域）→ "physics-informed neural networks" → primary:ml, secondary:physics

7.2 DomainProfile 数据结构

每个领域由 YAML 配置文件定义（domains/profiles/），含：实验范式（comparison/convergence/simulation/ablation_study/progressive_spec）、术语映射、代码结构、核心库、指标类型、标准baseline、统计检验、图表类型、代码生成提示、计算预算指导。

7.3 提示词适配器（PromptAdapter）

domains/prompt_adapter.py 定义适配器模式：

class PromptAdapter(ABC):
    def get_code_generation_blocks(self, context) -> PromptBlocks  # 代码生成阶段的领域特定块
    def get_experiment_design_blocks(self, context) -> PromptBlocks  # 实验设计阶段
    def get_result_analysis_blocks(self, context) -> PromptBlocks   # 结果分析阶段
    def get_blueprint_context(self) -> str  # 蓝图阶段的额外上下文
    def get_condition_terminology(self) -> dict  # 领域术语映射

PromptBlocks 8个字段注入到提示模板：compute_budget/dataset_guidance/hp_reporting/code_generation_hints/result_analysis_hints/experiment_design_context/statistical_test_guidance/output_format_guidance。空字符串表示"使用prompts.py默认值"。

7.4 九个领域适配器

适配器 关键差异点
ML 空块→使用prompts.py现有硬编码行为（零回归保证）
Physics 收守律验证、约化单位、解析解对比、5+细化级别收敛研究、log-log图
Biology QC+标准化、ARI/NMI聚类指标、Wilcoxon+FDR、scanpy、cap 5000 cells
Chemistry SMILES/分子指纹、RDKit、药物发现指标
Math 收敛阶分析、误差范数、数值稳定性检查
Economics 渐进规范（OLS→+FE→+IV）、工具变量、面板数据
Neuroscience BIDS格式、fMRI预处理、脑区映射
Robotics 仿真环境、控制策略、安全约束
Security 攻击/防御对比、CVE引用、可利用性评估

7.5 领域适配的注入路径

1. 阶段执行开始 → _detect_domain(topic) → DomainProfile → 选择 PromptAdapter
2. 代码生成(Stage10) → adapter.get_code_generation_blocks() + get_blueprint_context()
3. 实验设计(Stage9) → adapter.get_experiment_design_blocks() + get_condition_terminology()
4. 结果分析(Stage14) → adapter.get_result_analysis_blocks()

设计原则：ML适配器返回空块→现有prompts.py行为完全不变（零回归保证）。其他领域只增不改——通过注入额外约束来适配领域。

领域适配功能价值：同一个流水线无需任何配置即可跨领域运行——输入"量子随机矩阵"自动选physics适配器（注入守恒律验证、收敛研究），输入"单细胞RNA-seq"自动选biology适配器（注入scanpy、QC、cap 5000 cells），输入"LoRA fine-tuning"自动选ML适配器（零注入，完全使用默认行为）。用户无需为不同领域写不同代码，PromptAdapter透明完成领域特化。

八、人机协作与干预机制

8.1 六种干预模式

模式 命令 行为
Full Auto --auto-approve 纯自主，永不暂停
Gate Only --mode gate-only 仅3个门控阶段暂停
Checkpoint --mode checkpoint 每个阶段组边界暂停（8检查点）
Co-Pilot --mode co-pilot 关键阶段深度协作，其余自动
Step-by-Step --mode step-by-step 每阶段后暂停
Custom --mode custom 自定义逐阶段策略

模式选择建议：首次使用用step-by-step学习流水线；正式论文用co-pilot获最佳质量；通宵运行用gate-only减少中断；批量处理用full-auto。

典型Co-Pilot会话：流水线自动跑完阶段1-7→阶段8暂停显示假设→用户按c进入协作聊天→告诉AI"假设3需要加Dropout和Label Smoothing作baseline"→AI更新假设→用户按a批准→流水线继续。人工投入仅30-60分钟，AI自主执行2-4小时。

各模式暂停策略矩阵：

阶段 full-auto gate-only checkpoint co-pilot step-by-step
1-4 - - - - 暂停
5(门控) - 暂停 暂停 暂停+协作 暂停
8(假设) - - 边界暂停 暂停+Idea Workshop 暂停
9(门控) - 暂停 暂停 暂停+Baseline Navigator 暂停
10-13 - - - - 暂停
16-17 - - - 暂停+Paper Co-Writer 暂停
20(门控) - 暂停 暂停 暂停 暂停

8.2 SmartPause：置信度驱动动态干预

不依赖固定门控，动态判断何时需人工干预：

@dataclass
class ConfidenceSignal:
    quality_score: float = 1.0       # 输出质量 (0-1)
    confidence_score: float = 1.0    # LLM自评置信度 (0-1)
    novelty_risk: float = 0.0        # 新颖性/风险 (0-1)
    historical_rejection_rate: float = 0.0  # 历史拒绝率 (0-1)
    criticality: float = 0.5         # 阶段关键度 (0-1)
    # overall_confidence = 0.30*quality + 0.25*confidence + 0.15*(1-novelty_risk) + 0.10*(1-history) + 0.20*(1-criticality)

阶段关键度：HYPOTHESIS_GEN(0.9) > EXPERIMENT_DESIGN(0.8) > SYNTHESIS(0.7) > TOPIC_INIT(0.6) = CODE_GEN(0.6)

触发条件：overall_confidence < 0.5 或 quality_score < 0.3 或 (novelty_risk > 0.8 且 criticality > 0.7)

8.3 人工干预动作与层级

9种动作：approve/reject/edit/skip/collaborate/inject/rollback/take_over/resume

三层干预：Tier1观察（view_output/logs/llm_trace）→ Tier2引导（approve/reject/edit/inject/rollback）→ Tier3协作（start_chat/co_write/provide_resource/take_over）

8.4 三个协作工作坊

  • Idea Workshop（阶段7-8）：用户与AI辩论假设可行性，添加/删除baseline
  • Baseline Navigator（阶段9）：AI建议数据集和baseline → 用户增删 → 可复现性检查
  • Paper Co-Writer（阶段16-19）：逐节协作撰写，AI写初稿→用户编辑→AI润色，最多50轮

工作坊功能价值：

  • Idea Workshop解决的核心问题：AI缺乏判断研究新颖性和影响力的"品味"——用户辩论可补足这一短板，确保假设方向真正有价值而非看似合理
  • Baseline Navigator解决的核心问题：AI不知道审稿人期望哪些对比——用户补充领域标准baseline（如ResNet-50、ViT-B/16），避免审稿时被质疑"missing important baseline"
  • Paper Co-Writer解决的核心问题：AI产出的论文正确但平淡——用户重写关键段落引入领域洞见，AI负责润色过渡和符号一致性，人机交替产出既有深度又行文流畅的论文

流水线分支探索：不确定哪个研究方向好时，可researchclaw branch create分叉流水线并行探索多个假设，实验完成后researchclaw branch compare对比结果，researchclaw branch merge合并最佳路径——实现并行假设探索。

8.5 逐阶段策略（StagePolicy）

自定义模式下每个阶段可独立配置：auto_execute/pause_before/pause_after/require_approval/allow_edit_output/enable_collaboration/min_quality_score/max_auto_retries/human_timeout_sec(默认24h)

hitl:
  enabled: true
  mode: custom
  stage_policies:
    8: {require_approval: true, enable_collaboration: true}  # 假设生成必须审批+协作
    9: {require_approval: true, allow_edit_output: true}     # 实验设计可编辑
    15: {pause_after: true}                                  # 决策后暂停
    17: {enable_collaboration: true, min_quality_score: 0.6} # 论文协作+质量门槛

8.6 HITL 系统架构

researchclaw/hitl/
├── config.py + intervention.py    # 模式/策略/动作定义
├── smart_pause.py                 # 置信度驱动动态干预
├── session.py + chat.py           # 会话与协作聊天
├── branching.py                   # 流水线分支探索
├── claim_verifier.py              # 事实验证
├── cost_guard.py + escalation.py  # 成本守卫与升级策略
├── learning.py                    # ALHF干预学习
├── quality_predictor.py           # 质量预测
├── adapters/                      # 3种干预适配器
│   ├── cli_adapter.py             # 终端交互
│   ├── ws_adapter.py              # WebSocket（Web仪表盘）
│   └── mcp_adapter.py             # MCP（外部Agent）
└── workshops/                     # 3个协作工作坊
    ├── idea.py + baseline.py + paper.py

九、与 OpenClaw 等一般 Agent 的区别

维度 OpenClaw（通用Agent） AutoResearchClaw（专业研究Agent）
定位 通用AI助手/聊天Agent 学术研究全流程自动化引擎
架构 单轮/多轮对话 23阶段有向流水线，含门控/回滚/双层决策循环
工具使用 通用工具（搜索/代码/文件） 研究专用工具链（OpenAlex API/沙盒实验/LaTeX导出/4层引用验证）
实验执行 无/简单 5种执行环境+四层递进自愈+12种缺陷诊断+3轮修复循环
结果不符 无处理 四层递进：代码自愈→实验诊断修复→REFINE/PIVOT决策→安全阀兜底
输出 文本/代码片段 完整论文包（.md+.tex+.bib+图表+评审+验证报告）
质量保障 无/简单校验 VerifiedRegistry+4轮审计+Sentinel守护+反捏造
进化学习 无 EvolutionStore跨运行教训+MetaClaw集成(+18.3%鲁棒性)
人机协作 对话式 6种HITL模式+SmartPause+3工作坊+逐阶段策略
领域适配 无 9领域适配器+25+配置YAML+PromptAdapter零回归注入
可复现性 无 SHA256校验和+不可变清单+多级撤销+版本快照

与OpenClaw的集成关系：AutoResearchClaw是OpenClaw-compatible服务——OpenClaw读取RESEARCHCLAW_AGENTS.md→用户说"Research X"→自动clone/install/config/run→返回论文。OpenClaw Bridge提供6类适配器桥接。

集成功能性价值：

  • OpenClaw一键研究：用户在Discord/Telegram/飞书/微信中说"Research X"，OpenClaw自动完成clone→install→config→run→返回论文——无需命令行操作
  • ACP跨Agent：任何ACP兼容Agent（Claude Code/Codex CLI/Gemini CLI/Kimi CLI）均可作为LLM后端，用户无需配置API Key
  • 6类Bridge适配器：定时研究（cron）、进度通知（Discord/Slack/Telegram）、跨会话知识持久化、并行子会话、实时网络搜索、浏览器论文采集——按需开启

十、核心代码实现分析

10.1 项目结构

researchclaw/
├── cli.py                   # CLI命令（run/init/setup/status/attach/...）
├── config.py                # RCConfig全局配置（YAML加载+校验）
├── prompts.py               # PromptManager提示词管理（YAML外部化+模板渲染）
├── adapters.py              # 6类适配器Protocol+Recording存根+MCP实现
├── evolution.py             # EvolutionStore自进化（教训提取+技能注入+30天衰减）
├── quality.py               # QualityAssessor模板/占位符检测
├── hardware.py              # HardwareProfile GPU检测+分级
│
├── llm/                     # LLM客户端
│   ├── client.py            # LLMClient（OpenAI兼容+回退链+重试）
│   ├── acp_client.py        # ACP协议客户端
│   ├── anthropic_adapter.py # Anthropic原生适配
│   └── gemini_adapter.py    # Gemini原生适配
│
├── pipeline/                # 流水线核心
│   ├── runner.py            # execute_pipeline()编排+PIVOT/REFINE回滚
│   ├── executor.py          # execute_stage()阶段调度
│   ├── stages.py            # Stage(IntEnum)+状态机+门控+回滚规则
│   ├── experiment_diagnosis.py # 12种缺陷诊断
│   ├── experiment_repair.py    # 修复循环（最多3轮）
│   ├── verified_registry.py   # 实验数据白名单
│   ├── paper_verifier.py      # 反捏造验证
│   └── stage_impls/            # 按功能分组的阶段实现
│       ├── _topic.py           # 阶段1-2
│       ├── _literature.py      # 阶段3-6
│       ├── _synthesis.py       # 阶段7-8
│       ├── _experiment_design.py # 阶段9
│       ├── _code_generation.py   # 阶段10
│       ├── _execution.py         # 阶段11-13
│       ├── _analysis.py          # 阶段14-15
│       ├── _paper_writing.py     # 阶段16-19
│       └── _review_publish.py    # 阶段20-23
│
├── agents/                 # 多Agent子系统
│   ├── base.py             # BaseAgent+AgentOrchestrator
│   ├── benchmark_agent/    # Surveyor→Selector→Acquirer→Validator
│   ├── figure_agent/       # Planner→CodeGen→Renderer→Critic→Integrator
│   └── code_searcher/      # GitHub代码搜索+模式提取
│
├── experiment/             # 实验执行环境
│   ├── sandbox.py          # 本地沙盒
│   ├── docker_sandbox.py   # Docker容器
│   ├── ssh_sandbox.py      # SSH远程
│   ├── validator.py        # AST代码校验
│   └── runner.py           # 实验运行器
│
├── hitl/                   # Human-in-the-Loop（见第八章）
├── copilot/                # Co-Pilot模式
├── domains/                # 领域适配（见第七章）
├── knowledge/              # 知识库（6类写入）
├── evolution.py            # 自进化系统
├── collaboration/          # 协作（去重/发布/订阅）
├── dashboard/              # 仪表盘
├── assessor/               # 评估（评分/比较/期刊推荐）
└── calendar/               # 会议日历

10.2 关键实现细节

流水线运行器（pipeline/runner.py）：execute_pipeline()遍历23阶段，阶段15后检查PIVOT/REFINE→递归调用自身（execute_pipeline(from_stage=rollback_target)），版本化回滚目录，数据晋升确保论文用最好的实验数据。

阶段执行器（pipeline/executor.py）：execute_stage()→领域检测→加载前序产物→构建上下文前言（含进化overlay+技能注入+领域适配块）→调用具体实现→产物写入→知识库写入。

LLM交互：统一通过_chat_with_prompt()→PromptManager.for_stage()渲染→LLMClient.chat()调用。多视角辩论通过_multi_perspective_generate()+_synthesize_perspectives()。

自进化（evolution.py）：EvolutionStore JSONL持久化，6类教训分类（system/logic/quality/performance/evidence/safety），时间衰减weight=exp(-λ×days)（30天半衰期），build_overlay()为后续运行生成注入文本。

十一、配置体系

核心配置文件 config.arc.yaml，主要配置段：

配置段 关键字段
project name, mode
research topic, domains, quality_threshold
llm provider, base_url, api_key, primary_model, fallback_models, acp
experiment mode(sandbox/docker/ssh_remote), sandbox, docker, opencode, code_agent, benchmark_agent, figure_agent, repair
hitl enabled, mode, cost_budget_usd, stage_policies
metaclaw_bridge enabled, proxy_url, skills_dir
openclaw_bridge use_cron, use_message, use_memory, use_sessions_spawn, use_web_fetch, use_browser
prompts custom_file

十二、总结

AutoResearchClaw 是一个面向学术研究的垂直领域 Agent 系统，其核心创新在于：

  1. 23阶段有向图流水线：超越通用Agent的单轮/多轮对话模式，编码了学术研究的完整方法论
  2. 实验-分析-决策双层循环：内层代码自愈(Stage13) + 外层策略调整(PIVOT/REFINE)，四层递进处理实验失败
  3. 研究专用工具链：真实文献API + 沙盒实验 + LaTeX导出 + 4层引用验证 + 反捏造三重防线
  4. 9领域适配器：PromptAdapter零回归注入 + 25+YAML配置，从ML到物理/生物/化学/经济全领域覆盖
  5. 6种HITL模式+SmartPause：从全自主到逐步引导的人机协作光谱，置信度驱动的动态干预
  6. 自进化学习：跨运行教训提取与注入，+18.3%鲁棒性

与通用Agent的本质区别：通用Agent解决"如何完成一个任务"，AutoResearchClaw解决"如何完成一项研究"——它编码了学术研究的完整方法论（从文献到实验到论文），而非依赖LLM即兴发挥。

核心功能总结：

  • 输入：一行研究主题（idea）——如"Quantum noise as neural network regularization"
  • 输出：完整论文包——paper_draft.md + paper.tex（NeurIPS/ICML/ICLR模板）+ references.bib（真实引用）+ experiment runs/（可复现实验）+ charts/（自动图表）+ reviews.md（多Agent评审）+ verification_report.json（引用验证）→ deliverables/（Overleaf直接编译）
  • 运行方式：researchclaw run --topic "..." --auto-approve（全自主）或 --mode co-pilot（协作）
  • 跨平台：CLI独立运行 / OpenClaw一键研究 / ACP接入任何AI Agent / Discord/Telegram/飞书/微信消息触发
  • 自我修复：实验失败→代码自愈→假设调整→引用清洗→成本守卫——四层递进确保最终产出质量
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

为AI戴上“紧箍咒”：零信任架构下的实时鉴权、防攻击限流与全链路审计黑盒

avatar 龙虾开发者社区

从 ChatGPT 到 Codex：AI Agent 的本质不是聊天，而是把“意图”编译成“行动”

如果用一个概念总结 ChatGPT 和 Codex，我会说：它们正在构成一种新的意图编译器。传统编译器把代码编译成机器指令。AI Agent 把自然语言意图编译成行动序列。Agent 则把整个链路串起来。这就是 AI 真正高级的地方。它不是简单替人说话。也不是简单替人写代码。它是在重新定义软件系统如何接受人类意图。过去，人必须学习机器语言、编程语言、工具界面和操作流程，才能让系统做事。未来，系统开

avatar 龙虾开发者社区

在 PVE 上通过 LXC 部署 Ubuntu 24.04：为 OpenClaw 打造轻量高效的 AI 环境

摘要：在Proxmox VE (PVE) 上通过LXC容器部署Ubuntu 24.04，为AI应用OpenClaw打造轻量高效的运行环境。LXC容器相比虚拟机具有启动快（约1秒）、资源占用低（内存30-100MB）等优势，且PVE对Ubuntu 24.04的支持已完善。文章对比了Ubuntu 22.04和24.04的差异，建议AI应用优先选择更稳定的22.04，但24.04对新硬件支持更好。详细介

avatar 龙虾开发者社区