Technical Documentation: aiming-lab/AutoResearchClaw

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

**Chat an Idea. Get a Paper. Autonomous, Collaborative & Self-Evolving.**

| | 🏆 Generated Paper Showcase
8 papers across 8 domains — math, statistics, biology, computing, NLP, RL, vision, robustness — generated fully autonomously or with Human-in-the-Loop co-pilot guidance.

|
| --- | --- |

🧪 We're looking for testers! Try the pipeline with your own research idea — from any field — and tell us what you think. Your feedback directly shapes the next version. → Testing Guide | → 中文测试指南 | → 日本語テストガイド

🔥 News Copy Chapter

• [05/19/2026] v0.5.0 — Multi-Domain Experiment Agents + ARC-Bench — Two headline updates. (1) Domain-specialist execution agents: the experiment stage (Stages 10–13) now routes beyond the default ML sandbox to specialist agents per field — high-energy physics (ColliderAgent: Lagrangian → FeynRules → MadGraph5 → Delphes via the Magnus cloud), biology (COBRApy genome-scale metabolic modelling), and statistics (simulation-study agent), with a generic Docker executor covering chemistry/materials. The pipeline auto-selects the right executor from the research domain. (2) ARC-Bench: a 55-topic open-ended autonomous-research benchmark spanning ML (25), HEP (10), quantum (10), biology (7), and statistics (3) — each topic ships a manifest (research question + conditions + metrics + datasets) and a rubric for graded scoring, all under experiments/arc_bench/, and also released on 🤗 Hugging Face. → Domain Integration Guide
• [04/01/2026] v0.4.0 — Human-in-the-Loop Co-Pilot System — AutoResearchClaw is no longer purely autonomous. New HITL system adds 6 intervention modes (full-auto, gate-only, checkpoint, step-by-step, co-pilot, custom), per-stage policies, and deep human-AI collaboration. Includes: Idea Workshop for hypothesis co-creation, Baseline Navigator for experiment design review, Paper Co-Writer for collaborative drafting, SmartPause (confidence-driven dynamic intervention), ALHF intervention learning, anti-hallucination claim verification, cost budget guardrails, pipeline branching for parallel hypothesis exploration, and CLI commands (attach/status/approve/reject/guide). → Full HITL Guide
• [03/30/2026] Flexible Skill Loading — AutoResearchClaw now supports loading open-source and custom skills from any discipline to further enhance your research experience. 20 pre-loaded skills are included as ready-to-use references, covering scientific writing, experiment design, chemistry, biology, and more — including an A-Evolve agentic evolution skill contributed by the community. Load your own via researchclaw skills install or drop a SKILL.md into .claude/skills/. See Skills Library.
• [03/22/2026] v0.3.2 — Cross-Platform Support + Major Stability — AutoResearchClaw now runs on any ACP-compatible agent backend (Claude Code, Codex CLI, Copilot CLI, Gemini CLI, Kimi CLI) and supports messaging platforms (Discord, Telegram, Lark, WeChat) via OpenClaw bridge. New CLI-agent code generation backend delegates Stages 10 & 13 to external CLI agents with budget control and timeout management. Also includes anti-fabrication system (VerifiedRegistry + experiment diagnosis & repair loop), 100+ bug fixes, modular executor refactoring, --resume auto-detection, LLM retry hardening, and community-reported fixes.

Earlier releases

• [03/18/2026] v0.3.1 — OpenCode Beast Mode + Community Contributions — New "Beast Mode" routes complex code generation to OpenCode with automatic complexity scoring and graceful fallback. Added Novita AI provider support, thread-safety hardening, improved LLM output parsing robustness, and 20+ bug fixes from community PRs and internal audit.
• [03/17/2026] v0.3.0 — MetaClaw Integration — AutoResearchClaw now supports MetaClaw cross-run learning: pipeline failures → structured lessons → reusable skills, injected into all 23 stages. +18.3% robustness in controlled experiments. Opt-in (metaclaw_bridge.enabled: true), fully backward-compatible. See Integration Guide.
• [03/16/2026] v0.2.0 — Three multi-agent subsystems (CodeAgent, BenchmarkAgent, FigureAgent), hardened Docker sandbox with network-policy-aware execution, 4-round paper quality audit (AI-slop detection, 7-dim review scoring, NeurIPS checklist), and 15+ bug fixes from production runs.
• [03/15/2026] v0.1.0 — We release AutoResearchClaw: a fully autonomous 23-stage research pipeline that turns a single research idea into a conference-ready paper. No human intervention required.

⚡ One Command. One Paper. Copy Chapter

# Fully autonomous — no human intervention
pip install -e . && researchclaw setup && researchclaw init && researchclaw run --topic "Your research idea here" --auto-approve

# Co-Pilot mode — collaborate with AI at key decision points
researchclaw run --topic "Your research idea here" --mode co-pilot

🤔 What Is This? Copy Chapter

You think it. AutoResearchClaw writes it. You guide the key decisions.

Drop a research topic — get back a full academic paper with real literature from OpenAlex, Semantic Scholar & arXiv, hardware-aware sandbox experiments (GPU/MPS/CPU auto-detected), statistical analysis, multi-agent peer review, and conference-ready LaTeX targeting NeurIPS/ICML/ICLR. Run it fully autonomous, or use Co-Pilot mode to guide the AI at critical decision points — choose research directions, review experiment designs, and co-write the paper. No hallucinated references.

The pipeline runs end-to-end — fully autonomous or with human-in-the-loop collaboration. When experiments fail, it self-heals. When hypotheses don't hold, it pivots. When citations are fake, it kills them. When you want to steer, it pauses and listens.

🌍 Run it anywhere. AutoResearchClaw isn't locked to a single platform. Use it standalone via CLI, plug it into OpenClaw, or wire it up through any ACP-compatible agent — 🤖 Claude Code, 💻 Codex CLI, 🐙 Copilot CLI, ♊ Gemini CLI, 🌙 Kimi CLI, you name it. And because OpenClaw bridges to messaging platforms, you can kick off a full research run from 💬 Discord, ✈️ Telegram, 🐦 Lark (飞书), 💚 WeChat, or wherever your team already hangs out. One topic in, one paper out — no matter where you type it.

🚀 Quick Start Copy Chapter

# 1. Clone & install
git clone https://github.com/aiming-lab/AutoResearchClaw.git
cd AutoResearchClaw
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. Setup (interactive — installs OpenCode beast mode, checks Docker/LaTeX)
researchclaw setup

# 3. Configure
researchclaw init          # Interactive: choose LLM provider, creates config.arc.yaml
# Or manually: cp config.researchclaw.example.yaml config.arc.yaml

# 4. Run
export OPENAI_API_KEY="sk-..."
researchclaw run --config config.arc.yaml --topic "Your research idea" --auto-approve

Output → artifacts/rc-YYYYMMDD-HHMMSS-<hash>/deliverables/ — compile-ready LaTeX, BibTeX, experiment code, charts.

📝 Minimum required config

project:
  name: "my-research"

research:
  topic: "Your research topic here"

llm:
  base_url: "https://api.openai.com/v1"
  api_key_env: "OPENAI_API_KEY"
  primary_model: "gpt-4o"
  fallback_models: ["gpt-4o-mini"]

experiment:
  mode: "sandbox"
  sandbox:
    python_path: ".venv/bin/python"

🧠 What Makes It Different Copy Chapter

🦞 OpenClaw Integration Copy Chapter

🚀 Use with OpenClaw (Recommended) Copy Section

If you already use OpenClaw as your AI assistant:

1️⃣  Share the GitHub repo URL with OpenClaw
2️⃣  OpenClaw auto-reads RESEARCHCLAW_AGENTS.md → understands the pipeline
3️⃣  Say: "Research [your topic]"
4️⃣  Done — OpenClaw clones, installs, configures, runs, and returns results

That's it. OpenClaw handles git clone, pip install, config setup, and pipeline execution automatically. You just chat.

💡 What happens under the hood

1. OpenClaw reads RESEARCHCLAW_AGENTS.md → learns the research orchestrator role
2. OpenClaw reads README.md → understands installation and pipeline structure
3. OpenClaw copies config.researchclaw.example.yaml → config.yaml
4. Asks for your LLM API key (or uses your environment variable)
5. Runs pip install -e . + researchclaw run --topic "..." --auto-approve
6. Returns the paper, LaTeX, experiments, and citations

🔌 OpenClaw Bridge (Advanced) Copy Section

For deeper integration, AutoResearchClaw includes a bridge adapter system with 6 optional capabilities:

# config.arc.yaml
openclaw_bridge:
  use_cron: true              # ⏰ Scheduled research runs
  use_message: true           # 💬 Progress notifications (Discord/Slack/Telegram)
  use_memory: true            # 🧠 Cross-session knowledge persistence
  use_sessions_spawn: true    # 🔀 Spawn parallel sub-sessions for concurrent stages
  use_web_fetch: true         # 🌐 Live web search during literature review
  use_browser: false          # 🖥️ Browser-based paper collection

Each flag activates a typed adapter protocol. When OpenClaw provides these capabilities, the adapters consume them without code changes. See docs/integration-guide.md for full details.

ACP (Agent Client Protocol) Copy Section

AutoResearchClaw can use any ACP-compatible coding agent as its LLM backend — no API keys required. The agent communicates via acpx, maintaining a single persistent session across all 23 pipeline stages.

# config.yaml — ACP example
llm:
  provider: "acp"
  acp:
    agent: "claude"   # Any ACP-compatible agent CLI command
    cwd: "."          # Working directory for the agent
  # No base_url or api_key needed — the agent handles its own auth.

# Just run — the agent uses its own credentials
researchclaw run --config config.yaml --topic "Your research idea" --auto-approve

🛠️ Other Ways to Run Copy Section

🔬 Pipeline: 23 Stages, 8 Phases Copy Chapter

Phase A: Research Scoping          Phase E: Experiment Execution
  1. TOPIC_INIT                      12. EXPERIMENT_RUN
  2. PROBLEM_DECOMPOSE               13. ITERATIVE_REFINE  ← self-healing

Phase B: Literature Discovery      Phase F: Analysis & Decision
  3. SEARCH_STRATEGY                 14. RESULT_ANALYSIS    ← multi-agent
  4. LITERATURE_COLLECT  ← real API  15. RESEARCH_DECISION  ← PIVOT/REFINE
  5. LITERATURE_SCREEN   [gate]
  6. KNOWLEDGE_EXTRACT               Phase G: Paper Writing
                                     16. PAPER_OUTLINE
Phase C: Knowledge Synthesis         17. PAPER_DRAFT
  7. SYNTHESIS                       18. PEER_REVIEW        ← evidence check
  8. HYPOTHESIS_GEN    ← debate      19. PAPER_REVISION

Phase D: Experiment Design         Phase H: Finalization
  9. EXPERIMENT_DESIGN   [gate]      20. QUALITY_GATE      [gate]
 10. CODE_GENERATION                 21. KNOWLEDGE_ARCHIVE
 11. RESOURCE_PLANNING               22. EXPORT_PUBLISH     ← LaTeX
                                     23. CITATION_VERIFY    ← relevance check

Gate stages (5, 9, 20) pause for human approval or auto-approve with --auto-approve. On rejection, the pipeline rolls back.

Co-Pilot mode (--mode co-pilot): Deep human-AI collaboration at Stages 7-8 (Idea Workshop), Stage 9 (Baseline Navigator), and Stages 16-17 (Paper Co-Writer). Other stages auto-execute with SmartPause monitoring.

Decision loops: Stage 15 can trigger REFINE (→ Stage 13) or PIVOT (→ Stage 8), with automatic artifact versioning.

📋 What Each Phase Does

✨ Key Features Copy Chapter

🧑‍✈️ Human-in-the-Loop Co-Pilot Copy Chapter

AutoResearchClaw v0.4.0 introduces a complete Human-in-the-Loop (HITL) system that transforms the pipeline from purely autonomous to a human-AI collaborative research engine. Choose your level of involvement:

Intervention Modes Copy Section

Co-Pilot Workflow(updated Apr 13, added experiment to prove the best) Copy Section

You: researchclaw run --topic "Quantum noise as neural network regularization" --mode co-pilot

Pipeline runs Stages 1-7 automatically...

  ┌─────────────────────────────────────────────────────────────┐
  │  HITL | Stage 08: HYPOTHESIS_GEN                            │
  │  Post-stage review                                          │
  │                                                             │
  │  Hypotheses mentioned: 3                                    │
  │  Novelty score: 0.72 (moderate)                             │
  │                                                             │
  │  [a] Approve  [r] Reject  [e] Edit  [c] Collaborate         │
  │  [i] Inject guidance  [v] View output  [q] Abort            │
  └─────────────────────────────────────────────────────────────┘

You: c  (start collaborative chat)
You: Hypothesis 3 is interesting but needs Dropout/Label Smoothing as baselines
AI:  Updated — added Dropout, Label Smoothing, MixUp, CutMix as baselines...
You: approve

Pipeline continues with your refined hypothesis...

CLI Commands Copy Section

# Start with HITL mode
researchclaw run --topic "..." --mode co-pilot

# Attach to a paused pipeline (from another terminal)
researchclaw attach artifacts/rc-2026-xxx

# Check pipeline and HITL status
researchclaw status artifacts/rc-2026-xxx

# Approve/reject from another terminal or script
researchclaw approve artifacts/rc-2026-xxx --message "LGTM"
researchclaw reject artifacts/rc-2026-xxx --reason "Missing key baseline"

# Inject guidance for a stage (even before it runs)
researchclaw guide artifacts/rc-2026-xxx --stage 9 --message "Use ResNet-50 as primary baseline"

Key Capabilities Copy Section

Configuration Copy Section

# config.arc.yaml
hitl:
  enabled: true
  mode: co-pilot                     # full-auto | gate-only | checkpoint | co-pilot | custom
  cost_budget_usd: 50.0              # Pause when cost exceeds budget (0 = no limit)

  notifications:
    on_pause: true
    on_quality_drop: true
    channels: ["terminal"]            # terminal | slack | webhook

  timeouts:
    default_human_timeout_sec: 86400  # 24h default wait
    auto_proceed_on_timeout: false

  collaboration:
    max_chat_turns: 50
    save_chat_history: true

  # Per-stage custom policies (optional, for 'custom' mode)
  stage_policies:
    8: { require_approval: true, enable_collaboration: true }
    9: { require_approval: true, allow_edit_output: true }

Backward Compatibility Copy Section

• Default: OFF. Without hitl.enabled: true or --mode, the pipeline behaves exactly as before.
• --auto-approve still works. It overrides HITL mode.
• All 2,699 existing tests pass with HITL code present.

🧠 MetaClaw Integration Copy Chapter

AutoResearchClaw + MetaClaw = A pipeline that learns from every run.

MetaClaw adds cross-run knowledge transfer to AutoResearchClaw. When enabled, the pipeline automatically captures lessons from failures and warnings, converts them into reusable skills, and injects those skills into all 23 pipeline stages on subsequent runs — so the same mistakes are never repeated.

How It Works Copy Section

Run N executes → failures/warnings captured as Lessons
                      ↓
          MetaClaw Lesson → Skill conversion
                      ↓
          arc-* Skill files stored in ~/.metaclaw/skills/
                      ↓
Run N+1 → build_overlay() injects skills into every LLM prompt
                      ↓
          LLM avoids known pitfalls → higher quality, fewer retries

Quick Setup Copy Section

# 1. Install MetaClaw (if not already)
pip install metaclaw

# 2. Enable in your config

# config.arc.yaml
metaclaw_bridge:
  enabled: true
  proxy_url: "http://localhost:30000"        # MetaClaw proxy (optional)
  skills_dir: "~/.metaclaw/skills"          # Where skills are stored
  fallback_url: "https://api.openai.com/v1" # Direct LLM fallback
  fallback_api_key: ""                      # API key for fallback URL
  lesson_to_skill:
    enabled: true
    min_severity: "warning"                 # Convert warnings + errors
    max_skills_per_run: 3

# 3. Run as usual — MetaClaw works transparently
researchclaw run --config config.arc.yaml --topic "Your idea" --auto-approve

After each run, check ~/.metaclaw/skills/arc-*/SKILL.md to see the skills your pipeline has learned.

Experiment Results Copy Section

In controlled A/B experiments (same topic, same LLM, same configuration):

Composite robustness score is a weighted average of stage completion rate (40%), retry reduction (30%), and refine cycle efficiency (30%).

Backward Compatibility Copy Section

• Default: OFF. If metaclaw_bridge is absent or enabled: false, the pipeline behaves exactly as before.
• No new dependencies. MetaClaw is optional — the core pipeline works without it.
• All 2,699 existing tests pass with the integration code present.

🧩 Skills Library Copy Chapter

AutoResearchClaw now supports loading open-source and custom skills to further enhance your research experience. We also ship with 20 pre-loaded built-in skills (scientific writing, literature search, chemistry, biology, and more) as ready-to-use references, offering a high degree of flexibility out of the box. Disable any skill by adding enabled: false to its frontmatter.

Sample built-in skills:

See all 20 skills with researchclaw skills list.

Load Your Own Skills Copy Section

# Option 1: Install a skill (persists across projects)
researchclaw skills install /path/to/my-skill/

# Option 2: Drop a SKILL.md into the project
mkdir -p .claude/skills/my-custom-skill
# Then create a SKILL.md with YAML frontmatter (name, description, trigger-keywords, applicable-stages)

# Option 3: Configure shared skill directories in config.arc.yaml
# skills:
#   custom_dirs:
#     - /path/to/team-shared-skills

Using Skills Copy Section

Skills are loaded and injected into LLM prompts automatically — no manual activation needed. Use the CLI to inspect:

researchclaw skills list               # Show all loaded skills with sources
researchclaw skills validate ./my-skill # Check SKILL.md format

Browse community skills: K-Dense-AI/claude-scientific-skills (150+ scientific skills across multiple disciplines).

⚙️ Configuration Reference Copy Chapter

Click to expand full configuration reference

/* Detailed source-code truncated for AI context efficiency. */

MiniMax presets use MINIMAX_API_KEY, MiniMax-M3 as the primary model,
and MiniMax-M2.7 in the fallback chain.

Anthropic-compatible presets require pip install "researchclaw[anthropic]".
The global and China API references are available from the
MiniMax platform and
MiniMax China platform.

🔭 HEP-ph Physics Mode (collider_agent) Copy Chapter

When project.profile=hep_ph and experiment.mode=collider_agent, the
pipeline routes Stage 12 through ColliderAgent (Lagrangian → FeynRules →
MadGraph5 → figures via Magnus cloud) instead of the default Python ML
sandbox.

Mid-stage HITL Copy Section

Stage 10 (CODE_GENERATION) becomes a HITL gate. The pipeline pauses with
collider_plan.md open in $EDITOR so you can review or edit the physics
prompt before ColliderAgent runs. Reject sends control back to Stage 9
(EXPERIMENT_DESIGN); the hypothesis from Stage 8 stays intact.

Incremental experiments (`--incremental-experiment`) Copy Section

To add new mass points or analyses to a completed run without redoing
the heavy simulation, re-launch with --incremental-experiment and either
--from-stage CODE_GENERATION (also edit the prompt) or
--from-stage EXPERIMENT_RUN (reuse existing prompt):

python -m researchclaw run --profile hep_ph --output artifacts/<run_id> \
    --from-stage CODE_GENERATION --incremental-experiment

The Stage 12 sandbox will:

1. Snapshot the existing stage-12/ tree to stage-12_v{N}/.
2. Save the previous collider_plan.md as collider_plan.prev.md.
3. Build workspace_manifest.json listing reusable artifacts.
4. Send ColliderAgent a three-part prompt:
   CONTINUATION CONTEXT + PRIOR PLAN + your new delta.
5. Merge ColliderAgent's new results.json with the snapshot's prior one
   (metrics: new wins on collisions, old-only kept; artifact lists:
   concat + dedupe). The merge is recorded in incremental_merge.json.

Stage 13 then promotes the merged state to experiment_final/ as before.

Note: re-entering at Stage 13 alone is a no-op in collider mode and will
NOT run any new physics — Stage 13 is a shutil.copy2 passthrough.
PIVOT (Stage 15 decision) intentionally remains destructive because
changing the hypothesis makes prior events invalid.

🙏 Acknowledgments Copy Chapter

Inspired by:

• 🔬 AI Scientist (Sakana AI) — Automated research pioneer
• 🧠 AutoResearch (Andrej Karpathy) — End-to-end research automation
• 🌐 FARS (Analemma) — Fully Automated Research System

📄 License Copy Chapter

MIT — see LICENSE for details.

📌 Citation Copy Chapter

If you find AutoResearchClaw useful, please cite:

@misc{liu2026autoresearchclawselfreinforcingautonomousresearch,
      title={AutoResearchClaw: Self-Reinforcing Autonomous Research with Human-AI Collaboration},
      author={Jiaqi Liu and Shi Qiu and Mairui Li and Bingzhou Li and Haonian Ji and Siwei Han and Xinyu Ye and Peng Xia and Zihan Dong and Congyu Zhang and Letian Zhang and Guiming Chen and Haoqin Tu and Xinyu Yang and Lu Feng and Xujiang Zhao and Haifeng Chen and Jiawei Zhou and Xiao Wang and Weitong Zhang and Hongtu Zhu and Yun Li and Jieru Mei and Hongliang Fei and Jiaheng Zhang and Linjie Li and Linjun Zhang and Yuyin Zhou and Sheng Wang and Caiming Xiong and James Zou and Zeyu Zheng and Cihang Xie and Mingyu Ding and Huaxiu Yao},
      year={2026},
      eprint={2605.20025},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2605.20025},
}

CHANGELOG ANTHROPIC ADAPTER (`docs/CHANGELOG_ANTHROPIC_ADAPTER.md`) Copy Section

Anthropic Messages API Adapter — 改动说明

本文档详细描述了为 ResearchClaw LLM 模块引入 Anthropic Messages API 原生支持的改动内容，
并通过架构图说明本次改动 不影响现有 OpenAI / OpenRouter / DeepSeek 等 provider 的任何行为。

目录 Copy Chapter

1. 改动背景
2. 架构总览 — 改动前后对比
3. 核心设计：适配器模式
4. 调用流程详解
5. 对现有 Provider 零影响的保证
6. 变更文件清单
7. 异常处理与重试机制
8. 配置示例
9. 新增依赖

1. 改动背景 Copy Chapter

ResearchClaw 的 LLM 模块原先仅支持 OpenAI Chat Completions API 格式（含兼容此格式的 OpenRouter、DeepSeek 等）。
Anthropic 的 Claude 系列模型使用独立的 Messages API，其请求/响应结构与 OpenAI 格式存在显著差异：

为了原生支持 Anthropic API 而不影响现有功能，我们采用了 适配器模式（Adapter Pattern）。

2. 架构总览 — 改动前后对比 Copy Chapter

改动前 Copy Section

graph TB
    subgraph "create_llm_client (工厂函数)"
        A[config.llm.provider] -->|"acp"| B[ACPClient]
        A -->|"其他所有"| C["内联构造 LLMClient<br/>使用 PROVIDER_PRESETS 填充 base_url"]
    end

    C --> D["_raw_call()<br/>urllib → OpenAI /chat/completions"]
    D --> E[LLMResponse]

    style B fill:#e1f5fe
    style C fill:#e8f5e9
    style D fill:#e8f5e9

改动后 Copy Section

graph TB
    subgraph "create_llm_client (工厂函数)"
        A[config.llm.provider] -->|"acp"| B[ACPClient]
        A -->|"其他所有"| C["LLMClient.from_rc_config()<br/>使用 PROVIDER_PRESETS 填充 base_url"]
    end

    C -->|"provider == anthropic"| F["挂载 AnthropicAdapter"]
    C -->|"其他 provider"| G["_anthropic = None"]

    subgraph "_raw_call() 内部分支"
        H{"self._anthropic<br/>是否存在?"}
        H -->|"是 (Anthropic)"| I["AnthropicAdapter.chat_completion()<br/>httpx → Anthropic /v1/messages"]
        H -->|"否 (OpenAI 等)"| J["原有逻辑不变<br/>urllib → OpenAI /chat/completions"]
    end

    F --> H
    G --> H
    I --> K["返回 OpenAI 兼容格式 dict"]
    J --> K
    K --> L["统一解析 → LLMResponse"]

    style B fill:#e1f5fe
    style F fill:#fff3e0
    style I fill:#fff3e0
    style G fill:#e8f5e9
    style J fill:#e8f5e9
    style L fill:#f3e5f5

绿色 = 原有逻辑（未修改），橙色 = 新增 Anthropic 路径，紫色 = 共享的统一出口。

3. 核心设计：适配器模式 Copy Chapter

classDiagram
    class LLMClient {
        -LLMConfig config
        -AnthropicAdapter _anthropic
        +chat(messages, ...) LLMResponse
        +preflight() tuple
        -_call_with_retry(model, ...) LLMResponse
        -_raw_call(model, ...) LLMResponse
    }

    class AnthropicAdapter {
        -str base_url
        -str api_key
        -int timeout_sec
        +chat_completion(model, messages, ...) dict
    }

    class LLMResponse {
        +str content
        +str model
        +int prompt_tokens
        +int completion_tokens
    }

    LLMClient "1" *-- "0..1" AnthropicAdapter : _anthropic
    LLMClient ..> LLMResponse : returns
    AnthropicAdapter ..> LLMResponse : "返回 OpenAI 兼容 dict\n由 LLMClient 统一解析"

    note for AnthropicAdapter "仅当 provider=='anthropic' 时实例化\n其他 provider 时 _anthropic = None"

关键设计决策：

• AnthropicAdapter 是 LLMClient 的一个 可选内部组件，不是独立的客户端类
• 适配器返回 OpenAI 兼容格式的 dict，由 _raw_call() 的统一出口解析为 LLMResponse
• 当 _anthropic is None 时，_raw_call() 走 完全不变的原有 OpenAI 路径

4. 调用流程详解 Copy Chapter

以下时序图展示了两种 provider 各自的完整调用链路：

OpenAI / OpenRouter / DeepSeek（原有流程，零改动） Copy Section

sequenceDiagram
    participant Caller as 调用方
    participant Client as LLMClient
    participant Raw as _raw_call()
    participant API as OpenAI API

    Caller->>Client: chat(messages)
    Client->>Client: _call_with_retry(model, ...)
    Client->>Raw: _raw_call(model, ...)
    Note over Raw: self._anthropic is None<br/>→ 走 else 分支 (原有逻辑)
    Raw->>API: urllib POST /chat/completions
    API-->>Raw: {"choices": [...], "usage": {...}}
    Raw-->>Client: LLMResponse
    Client-->>Caller: LLMResponse

Anthropic（新增流程） Copy Section

sequenceDiagram
    participant Caller as 调用方
    participant Client as LLMClient
    participant Raw as _raw_call()
    participant Adapter as AnthropicAdapter
    participant API as Anthropic API

    Caller->>Client: chat(messages)
    Client->>Client: _call_with_retry(model, ...)
    Client->>Raw: _raw_call(model, ...)
    Note over Raw: self._anthropic 存在<br/>→ 走 if 分支
    Raw->>Adapter: chat_completion(model, messages, ...)
    Note over Adapter: 1. 提取 system 消息<br/>2. 构建 Anthropic 请求体<br/>3. httpx POST /v1/messages
    Adapter->>API: httpx POST /v1/messages
    API-->>Adapter: {"content": [...], "usage": {...}}
    Note over Adapter: 转换为 OpenAI 兼容格式
    Adapter-->>Raw: {"choices": [...], "usage": {...}}
    Note over Raw: 统一解析（与 OpenAI 路径完全相同）
    Raw-->>Client: LLMResponse
    Client-->>Caller: LLMResponse

5. 对现有 Provider 零影响的保证 Copy Chapter

graph LR
    subgraph "provider != 'anthropic' 时的代码路径"
        A["from_rc_config()"] --> B["PROVIDER_PRESETS 填充 base_url ✅"]
        B --> C["LLMClient.__init__()"]
        C --> D["self._anthropic = None"]
        D --> E["_raw_call()"]
        E --> F{"self._anthropic?"}
        F -->|"None → False"| G["else 分支<br/>原有 OpenAI 逻辑<br/>（代码未修改）"]
    end

    style G fill:#e8f5e9,stroke:#4caf50,stroke-width:3px
    style F fill:#fff9c4

零影响的 5 重保证：

PROVIDER_PRESETS 对照表 Copy Section

graph TD
    subgraph "PROVIDER_PRESETS（base_url 自动填充）"
        P1["openai → https://api.openai.com/v1"]
        P2["openrouter → https://openrouter.ai/api/v1"]
        P3["deepseek → https://api.deepseek.com/v1"]
        P4["anthropic → https://api.anthropic.com"]
        P5["openai-compatible → 用户自定义 base_url"]
    end

    P1 --> |"不变 ✅"| OK1[" "]
    P2 --> |"不变 ✅"| OK2[" "]
    P3 --> |"不变 ✅"| OK3[" "]
    P4 --> |"新增"| OK4[" "]
    P5 --> |"不变 ✅"| OK5[" "]

    style P1 fill:#e8f5e9
    style P2 fill:#e8f5e9
    style P3 fill:#e8f5e9
    style P4 fill:#fff3e0
    style P5 fill:#e8f5e9

6. 变更文件清单 Copy Chapter

7. 异常处理与重试机制 Copy Chapter

Anthropic 适配器内部将 httpx 异常 转换为 urllib 标准异常，确保上层重试逻辑无需修改：

graph TD
    subgraph "AnthropicAdapter 内部"
        A["httpx.HTTPStatusError<br/>(4xx/5xx)"] -->|转换| B["urllib.error.HTTPError<br/>(保留 status_code)"]
        C["httpx.ConnectError<br/>httpx.TimeoutException"] -->|转换| D["urllib.error.URLError"]
    end

    subgraph "_call_with_retry() — 不变"
        B --> E{"status code?"}
        E -->|"429/500/502/503/504"| F["指数退避重试 ✅"]
        E -->|"400"| G["立即抛出（Bad Request）"]
        E -->|"403 + model forbidden"| H["跳到下一个 fallback model"]
        D --> I["重试直到耗尽 ✅"]
    end

    style A fill:#fff3e0
    style C fill:#fff3e0
    style B fill:#e8f5e9
    style D fill:#e8f5e9

这意味着 Anthropic 路径享有与 OpenAI 路径 完全相同的重试策略：指数退避 + jitter + model fallback chain。

8. 配置示例 Copy Chapter

使用 Anthropic（新增） Copy Section

llm:
  provider: anthropic
  # base_url 可省略，自动使用 https://api.anthropic.com
  api_key_env: ANTHROPIC_API_KEY
  primary_model: claude-sonnet-4-20250514
  fallback_models:
    - claude-haiku-4-5-20251001

使用 OpenAI（不变） Copy Section

llm:
  provider: openai
  # base_url 可省略，自动使用 https://api.openai.com/v1
  api_key_env: OPENAI_API_KEY
  primary_model: gpt-4o
  fallback_models:
    - gpt-4.1
    - gpt-4o-mini

使用 OpenRouter（不变） Copy Section

llm:
  provider: openrouter
  api_key_env: OPENROUTER_API_KEY
  primary_model: anthropic/claude-sonnet-4-20250514

9. 新增依赖 Copy Chapter

不使用 Anthropic provider 的用户 无需安装 httpx，pip install researchclaw 的行为完全不变。

总结: 本次改动通过适配器模式在 _raw_call() 内部添加了一条 Anthropic 专用路径。
当 provider 不是 "anthropic" 时，self._anthropic 为 None，代码执行路径与改动前 完全一致，
不触及任何新增代码，不引入任何新依赖。

CODE REVIEW 2026 07 03 (`docs/CODE_REVIEW_2026-07-03.md`) Copy Section

AutoResearchClaw 全仓代码审查报告

日期: 2026-07-03
范围: researchclaw/ 全部 396 个 Python 文件（约 80k 行），8 个并行审查线程覆盖 pipeline 核心、23 个 stage 实现、agent/修复循环、LLM 适配层、experiment 沙箱、config/CLI、模板/文献验证、基础设施。
基线: 测试套件 2831 passed, 49 skipped（全绿）；compileall 通过；ruff 227 项（多为未用 import）。下述问题全部处于测试盲区。

核心结论 Copy Chapter

项目最大的系统性风险是：多个以"反造假 / 反幻觉"为卖点的防线，在最需要生效的场景下自我关闭或被绕过。防线本身写了，但边界条件、降级路径、schema 对齐上有缺陷，导致"配置了却没生效"或"失败了却报成功"。这与仓库近期的 hard-guards-against-fabrication、silent-fallback-audit 方向直接相悖。

三条主线问题：

1. 反造假防线被击穿（P0 群）——引用验证、论文数字校验、实验失败硬闸都有绕过路径。
2. 版本目录选择错误（反复出现的 P1）——回滚后诊断/修复/论文写作系统性读到归档的旧快照。_helpers.py 已有正确实现，但至少 9 处各自用 sorted(glob, reverse=True) 重写且语义相反。
3. 静默降级——大量 except Exception: pass/logger.debug 把功能失效藏起来，包括 LLM 未接通、审批被跳过、数据源全空。

P0（严重：数据伪造 / 安全 / 核心功能失效） Copy Chapter

P1（高：崩溃 / 逻辑错误 / 安全） Copy Chapter

反造假与引用验证 Copy Section

• literature/verify.py:794 — L1 arXiv 校验是死代码：OpenAlex 查无结果返回确定性 HALLUCINATED（非 None），永不回落到 arXiv API。OpenAlex 尚未收录的新预印本被误判为幻觉并从正文删除。
• literature/verify.py:379 — 真 DOI + 假题目（相似度<0.5）只判 SUSPICIOUS，而 stage-23 用 include_suspicious=True 保留。元数据从不比对。
• literature/verify.py:97 — 网络全挂/5 分钟超时 → 全部 SKIPPED → integrity_score 分母 total-skipped 为 0 返回 1.0 满分。单次无重试。
• pipeline/stage_impls/_review_publish.py:2798（BUG-26 回退）— 验证剔除 >50% 条目就整体还原原始 bib，即在幻觉最严重时把 HALLUCINATED 条目放回，且正文引用已被删 → bib 与正文不一致。

版本目录选择（同一根因，多处） Copy Section

• pipeline/runner.py:224,235,253,268 — 诊断读 sorted(glob("stage-14*"), reverse=True) 取到 stage-14_vN 旧快照。首次 REFINE 后诊断/修复全基于过期数据。
• 同族问题：_analysis.py:869,1222、_paper_writing.py:1398,1950,1988、_review_publish.py:1589,2264、_execution.py:851。建议统一为 find_latest_stage_artifact()，一次消灭 BUG-58/178/207/222/DA8-16 全系列。

控制流 / 门禁 / 回滚 Copy Section

• pipeline/executor.py:769 — GATE 阶段即使 FAILED 也被无条件改写成 BLOCKED_APPROVAL，失败被吞。
• pipeline/runner.py:845 — BLOCKED_APPROVAL 仅在 stop_on_gate=True 时中断；execute_iterative_pipeline 从不传该参数 → 未批准的质量门禁被跳过继续导出论文。
• pipeline/runner.py:762 — PIVOT/REFINE 递归调用 execute_pipeline 漏传 to_stage，--to-stage 17 触发 REFINE 后无视上限跑到 Stage 23。
• pipeline/runner.py:660 — 回滚时不回退 checkpoint；递归重跑期间崩溃 → resume 从错误阶段起、读被改名的旧目录。
• pipeline/executor.py:641 — Ollama 无 api_key（其 preset 无 key 且本不需要）→ llm=None 无任何日志 → 23 阶段全部静默降级为模板兜底，产出无 LLM 参与的"论文"。而 validate_config 明确豁免 ollama 需要 key，两处矛盾。

数据伪造 / 静默 fallback（stage 层） Copy Section

• _code_generation.py:776,1298 — 代码生成失败时合成噪声 1/(1+‖x‖²) 冠以真实指标名；对齐检查解析失败默认 aligned=True 放行 → 合成数据绕过零指标硬闸流向论文。
• _execution.py:269 — collider_agent 失败仍返回 DONE，绕过 stage 12 的 fabrication 硬闸（硬闸只保护 sandbox/docker 模式）。
• _paper_writing.py:241 — 精炼"最优"选择硬编码 maximize 方向；minimize（loss/RMSE）下选出最差迭代注入论文提示词。
• _execution.py:1072/_analysis.py:1173/experiment_diagnosis.py:572 — 饱和/退化/近随机检测假设指标在 [0,1] 或百分制；百分制 accuracy 恒触发"饱和"，0.92 小数 accuracy 被误诊为"接近随机"。

确定性崩溃 Copy Section

• _paper_writing.py:2293 — re.search(draft_text, re.DOTALL) 参数错位（pattern 未用、flag 当字符串），PaperCoWriter 章节提取 100% 抛异常被吞，section 永远为空。
• opencode_bridge.py:583/code_agent.py:567 — 把库文件改名为 main.py，from main import X 导入自身 → 必然 ImportError。

修复循环 Copy Section

• experiment_repair.py:373 + experiment_diagnosis.py:709 — repairable/repair_possible 计算了但从不检查，循环终止条件失效；_assess_repairability 要求 3 种不同缺陷，同一 crash 每轮复现永不触发 → 烧满 3 周期。
• opencode_bridge.py:477 — 超时只杀直接子进程，OpenCode 的 Node 孙进程成孤儿。
• experiment_diagnosis.py:214 — 2 段 key 场景 actual_seeds 恒 1 → 永达不到 FULL_PAPER，修复即使成功也返回 success=False。
• agents/figure_agent（renderer/critic/orchestrator）— figure_id 清洗不一致 → 数值校验被跳过、失败图从重试集剔除、空转耗尽 max_iterations。

LLM 适配层 Copy Section

• llm/client.py:333 — 可重试 HTTP 错误耗尽重试后 raise RuntimeError（无 from e），preflight 依赖 e.__cause__ 的 401/403/429 分类全部失效，速率限制误报"All models failed"。
• llm/acp_client.py:100 — ACP 路径丢弃 json_mode/max_tokens，同一 stage 在 OpenAI/Anthropic 下有 JSON 强制、ACP 下没有，下游解析成功率不一致。

配置 / CLI Copy Section

• config.py:1182 — collider_agent.extra_args 默认 --dangerously-bypass-permissions（非法 CLI 参数），与 dataclass 默认及其他两个解析器的 --dangerously-skip-permissions 不一致 → HEP Stage 12 CLI 报错失败。
• config.py:920 等约 20 处 — 顶层字段对 YAML null 裸用 int()/float() → int(None) TypeError，validate_config 不拦截（experiment 段有 _safe_int 但其余段没用）。
• cli.py:1285 等 5 处 — serve/dashboard/project/overleaf/trends 的 --config 默认硬编码 config.yaml，而 init 生成 config.arc.yaml → 官方流程走完后这些命令报找不到配置。

安全（server / web / hitl） Copy Section

• server/middleware/auth.py:40 — BaseHTTPMiddleware 对非 http scope 直接放行 → 所有 WebSocket 端点绕过 token 鉴权。
• web/crawler.py:210/pdf_extractor.py:144/search.py:204 — SSRF 校验只查初始 URL，urlopen 自动跟随 3xx 重定向不复检 → 302 到 169.254.169.254/127.0.0.1 读内网。
• server/app.py:49 — CORS 默认 ("*",) + allow_credentials=True + auth_token 默认空 → 任意站点携凭证跨域调 /api/*。
• overleaf/sync.py:42 — Overleaf git URL 含认证 token 明文写日志和异常。
• overleaf/sync.py:142 — 以 stderr 含 "conflict" 决定吞非零退出码 → pull 冲突被静默，随后把带冲突标记的 .tex 推到 Overleaf。
• hitl/adapters/mcp_adapter.py:229 — hitl_view_output 的 filename 无消毒 → 路径穿越读任意文件（ws_adapter 有防护，此处没有）。
• metaclaw_bridge/prm_gate.py:191 — 质量门平票时 statistics.mode 取"最先出现"，顺序来自线程完成顺序 → 门禁 pass/fail 非确定。

LaTeX / 编译 Copy Section

• templates/converter.py:1804 — _escape_latex 正序还原保护块，嵌套时输出残留 \x00PROT0\x00 空字节 → pdflatex 崩溃（_convert_inline 已逆序修过，此处漏改）。已复现。
• templates/converter.py:198 — _fix_tabular_amp 无差别把单元格内合法 \& 反转义成 & → "Extra alignment tab" 编译错误（R&D、A&B 消融名）。
• templates/compiler.py:283 — "Missing $ inserted" 自动修复把全文档 $x_i$ 破坏成 $x\_i$，编译"成功"但所有下标公式错。
• report.py:154 — 读 total_references/verified_count 等键，而写入方 schema 是 {"summary": {"total", "verified"}} → 运行报告引用验证恒显示 "0/0 N/A"（同错复制在 hitl/quality_predictor.py、summarizer.py）。

P2（中：健壮性 / 正确性 / 资源） Copy Chapter

（节选，完整清单见各模块）

• experiment/code_agent.py:450 — proc.returncode or -1 把成功码 0 变成 -1。
• experiment/code_agent.py:436 — Windows 上 os.killpg 抛 AttributeError（docker_sandbox 有 win32 保护，此处没有）。
• experiment/validator.py:807 — auto_fix_unbound_locals 只看函数直接子级赋值，for/with/try 内赋值 + if 分支赋值的变量被误插 var=None 覆盖循环算好的值，自动应用改错正确代码。
• experiment/validator.py:67 — 安全扫描遗漏 pathlib.Path.unlink/write_text、open(p,'w')、别名 import os as o、getattr(os,'system')。
• experiment/docker_sandbox.py:407 — setup_only/pip_only 不加 --network none，依赖容器内 iptables，无 root 时网络全程可用。
• 三个 *_agent_sandbox.py — _install_skills 把技能复制进共享 ~/.claude/skills 并对同名先 rmtree → 破坏用户全局技能，并发 race。
• pipeline/_helpers.py:657 — _extract_multi_file_blocks 缺 main.py 时把第一个文件改名为 main.py，其余文件 import model ImportError。
• pipeline/_helpers.py:966 — _primary_metric 缺失指标返回 0.0，minimize 方向下失败 run 以 0.0"战胜"所有真实 run；不过滤 NaN。
• utils/thinking_tags.py:36 — 未闭合 `` 正则 .* 从该处删到文末；[PLAN] 大写时守卫过但替换不命中。
• memory/embeddings.py:73 — API 失败回退 TF-IDF 致 1536 与 256 维向量混存，检索静默退化为按时间排序。
• hitl/cost_guard.py:52 — 阈值去重是实例级但每 stage 新建实例 → 预算过半后每步重复暂停。
• assessor/scorer.py:107/trends/daily_digest.py:92 — LLM 未按格式回复时静默编造固定分。
• 多处非原子整文件覆写（memory/store、assessor/comparator、collaboration/repository、project/idea_pool、hitl/file_wait）— 并发或 SIGKILL 中途丢数据/截断。

架构 / 质量改进 Copy Chapter

高优先级重构 Copy Section

1. 版本目录选择统一 — 抽 find_latest_stage_artifact(run_dir, pattern)，语义"当前 > 最高版本号"。消灭 9 处重复 + BUG 全系列。
2. 状态机死代码 — stages.py 的 TRANSITION_MAP/TransitionOutcome/GATE_ROLLBACK 定义完整但只被 advance(...START) 仪式性调用一次，真实门禁/回滚在 runner/executor ad-hoc 重写且已漂移。要么驱动它、要么删。
3. LaTeX 转义碎片化 — 至少 4 份互不一致的转义实现，"先全局转义、再按环境反转义"是 \& 表格 bug 的根因。抽单一 latex_escape(text, context=...)，生成时按上下文转义，删掉所有事后反转义 pass。
4. 子进程调用统一封装 — run_subprocess(cmd, timeout, kill_process_group=True)，统一 start_new_session+killpg、bytes/str、returncode 归一化。消灭孤儿进程 + returncode + Windows 三类 bug。
5. provider 适配接口 — 定义显式 adapter 契约（能力声明 supports_json/max_tokens/temperature + 规范化错误类型），消除散落的 startswith 前缀判断（_NEW_PARAM_MODELS/_NO_TEMPERATURE_MODELS/_no_response_format 三张列表互不同步）。

巨型文件拆分 Copy Section

• _review_publish.py（2880 行）、_paper_writing.py（2308 行）、cli.py（2295，22 分支手工 if/elif 分发）、_helpers.py（1837，杂物抽屉）、config.py（1673，默认值双份维护是 bug 之源）、_code_generation.py（1531，单函数 1300 行串 8 环节）。

死代码 / 半成品模块（建议删除或标注 experimental） Copy Section

• servers/ 整包（dispatcher/slurm/ssh/cloud，slurm 提交命令有 shell 语法错误，生产走 experiment/ssh_sandbox.py）。
• copilot/（455 行，被 hitl 取代）、collaboration/（469 行，被 hitl/collaboration 取代）。
• mcp/ 整包内核空心（stub run_id、literature/review 恒返回占位，但对外宣称能力）。
• 配置有节但从未接线：assessor/、knowledge/graph/、memory/ 大部（runner 接线 API 对不上从未运行）。
• hitl 近半模块（ws_adapter/escalation/learning/quality_predictor/branching/notify/hooks）仅测试喂养；hitl.hooks 配置字段根本不解析。
• 零调用函数：domains.detector.detect_domain_async、knowledge.base.generate_weekly_report、wizard.validator、voice.synthesizer、project.scheduler 等。

横切建议 Copy Section

• atomic_write_json（temp + os.replace）+ 文件锁 — 统一所有磁盘 JSON 读写。
• 静默吞异常审计 — 把 except Exception: pass|debug 改为至少 logger.warning(exc_info=True)，尤其在标榜 anti-fabrication 的审批/评分/记忆/验证路径上；pipeline_summary 增加 silent_degradations: [] 字段留痕。
• example yaml 同步 CI — config.py 大量字段 example 未覆盖；加测试保证 example 可被 from_dict 加载 + 每个 key 映射到 dataclass 字段。

最该先修的清单（投入产出比排序） Copy Chapter

1. literature/verify.py:128 双引号 BibTeX 解析（P0，反造假核心，~5 行）
2. paper_verifier.py:63 \% 掩码（P0，反造假核心，1 行负向后顾）
3. hitl/session.py:199 硬编码 auto-approve（P0，审批语义，1 行）
4. dashboard/collector.py + trends/feeds.py schema/import 对齐（P0，整个仪表盘和 trends 恢复）
5. config.py:1182 extra_args 默认值（P1，HEP 直接失败，1 词）
6. cli.py --config 默认统一走 resolve_config_path（P1，官方流程可用性）
7. 版本目录选择统一 helper（P1，消灭一整个 BUG 系列）
8. experiment_diagnosis.py:572 + _execution.py:1072 指标刻度（P1，误诊正常模型）

DOMAIN INTEGRATION GUIDE (`docs/DOMAIN_INTEGRATION_GUIDE.md`) Copy Section

Domain Integration Guide

Audience: domain experts (chemistry, neuroscience, biology, materials, …) who already have a curated set of prompts and want to plug their domain into AutoResearchClaw end-to-end.
Working example throughout: the existing hep_ph integration (ColliderAgent + JHEP).

1. Elevator Summary Copy Chapter

AutoResearchClaw runs a fixed 23-stage research pipeline (topic init → literature → hypothesis → experiment design → code generation → execution → analysis → paper draft → review → revision → export). The pipeline runner, gates, evaluators, LLM dispatch, and the experiment-config plumbing are domain-agnostic. To integrate a new domain you do not modify any of that. You add a small plug-in surface consisting of (at minimum) a profile YAML and a detector keyword tuple, and (at most) a new prompt bank, an adapter class, an experiment-mode sandbox, and a LaTeX template. The selected domain id flows through PromptManager(domain=...), get_adapter(...), and (optionally) create_sandbox(config.mode == "_agent"). Every other stage handler reads the same generic API and never needs to know your domain exists.

2. Architecture (5 Layers) Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

The narrow interface is intentional. Stages 0–23 of the pipeline runner stay generic; the only stage code that knows your domain exists is the prompt manager (which returns a RenderedPrompt) and — if you add Layer 5 — the sandbox factory.

3. The 7-File Checklist Copy Chapter

When adding a new domain, every place that may need touching, in order:

For the simplest possible new domain (e.g. plain Python analysis), files 1, 2, 3, 7 are enough. The full HEP integration uses all 11.

4. Profile YAML Skeleton Copy Chapter

Modeled on researchclaw/domains/profiles/hep_ph.yaml. Every field carries a comment naming where it is consumed.

/* Detailed source-code truncated for AI context efficiency. */

Tip — narrative belongs in the prompt bank, not the YAML. After the Phase-B refactor (see researchclaw/prompts/hep.py:1-23), per-stage prose moved out of the YAML and into a dedicated bank module. Only code_generation_hints is left in YAML because it feeds the blueprint context.

5. Prompt Adapter Skeleton Copy Chapter

Inherit from PromptAdapter (defined at researchclaw/domains/prompt_adapter.py:52). Each method returns a PromptBlocks dataclass (prompt_adapter.py:26-49); empty fields fall back to defaults.

/* Detailed source-code truncated for AI context efficiency. */

How the `PromptBlocks` fields map to rendered prompts Copy Section

Real-world examples to crib from:

• researchclaw/domains/adapters/biology.py — full GenericPromptAdapter-style overlay (recommended starting point for bio/chem/neuro).
• researchclaw/domains/adapters/hep_ph.py — minimal adapter that returns empty blocks because all narrative lives in the prompt bank prompts/hep.py.

6. Prompt Bank Skeleton (optional — file 4) Copy Chapter

If your domain's per-stage prose deviates substantially from ML defaults (the HEP-ph case), create a dedicated bank module. The contract:

1. Module exposes STAGES: dict[str, dict[str, Any]] whose keys exactly match those in researchclaw/prompts/ml.py. The parity test tests/test_prompt_bank_parity.py will fail if you add or drop a stage.
2. Each stage value is {"system": str, "user": str, "json_mode": bool, "max_tokens": int} (the latter two are optional; defaults False / None).
3. The user template uses {placeholder} substitution (the regex in prompts/manager.py:39-51 is r"\{(\w+)\}"). The set of placeholders for each stage must match the corresponding ML stage so the call sites in the pipeline (which pass the same kwargs regardless of domain) work unchanged.
4. Optionally export DEBATE_ROLES_HYPOTHESIS and DEBATE_ROLES_ANALYSIS — dicts of {role_name: {"system": ..., "user": ...}} used by the multi-agent debate at the hypothesis/analysis stages. ML uses innovator/pragmatist/contrarian; HEP-ph uses theorist/phenomenologist/experimentalist (prompts/hep.py:34-192).

The full canonical stage list (from prompts/hep.py):

topic_init, problem_decompose, search_strategy, literature_collect,
literature_screen, knowledge_extract, synthesis, hypothesis_gen,
experiment_design, code_generation, resource_planning, result_analysis,
research_decision, paper_outline, paper_draft, peer_review,
paper_revision, quality_gate, knowledge_archive, export_publish

Example stage entry — hypothesis_gen from prompts/hep.py:437-488:

STAGES["hypothesis_gen"] = {
    "system": (
        "You formulate testable HEP-phenomenology hypotheses that address "
        "gaps NOT covered by existing experimental results. Every "
        "hypothesis must be:\n"
        "1. NOVEL: Not replicating a published recast or an existing "
        "collaboration exclusion.\n"
        "..."
    ),
    "user": (
        "Generate at least 2 falsifiable HEP-ph hypotheses from the "
        "synthesis below.\n"
        "For each hypothesis provide:\n"
        "- **Hypothesis statement**: A clear claim in physics language, "
        "  naming the BSM model / operator and the observable.\n"
        "..."
        "{domain_context}"
        "Synthesis:\n{synthesis}"
    ),
}

The two placeholders {domain_context} and {synthesis} are exactly the kwargs the hypothesis stage handler passes — so the same handler works for both prompts/ml.py and prompts/hep.py.

Wiring the bank into the manager Copy Section

After creating researchclaw/prompts/my_domain.py, two single-line edits:

researchclaw/prompts/manager.py:31

SUPPORTED_DOMAINS = ("ml", "hep_ph", "my_domain")

researchclaw/prompts/manager.py:74-92 (_load_bank)

def _load_bank(domain: str) -> tuple[...]:
    if domain == "hep_ph":
        from researchclaw.prompts import hep as _bank
    elif domain == "my_domain":
        from researchclaw.prompts import my_domain as _bank
    else:
        from researchclaw.prompts import ml as _bank
    ...

Anything not in SUPPORTED_DOMAINS falls back to the ML bank — see line 119: self._domain = domain if domain in SUPPORTED_DOMAINS else "ml". So if you forget to register, your domain silently uses ML prose.

7. Detector Keyword Rule Copy Chapter

Auto-routing happens via a flat list of (phrases, domain_id) tuples scanned top-to-bottom in researchclaw/domains/detector.py:_KEYWORD_RULES (lines 245–351). The first rule whose keyword list intersects the topic text wins.

Rule format — one line per domain, most-specific-first:

(["dark matter", "wimp", "direct detection", "dark photon",
  "axion", "neutralino", "bsm", "beyond standard model",
  "effective field theory", "relic density", "annihilation cross section",
  "hep-ph", "hep-ex", "madgraph5", "feynrules", "delphes", "pythia8",
  "collider phenomenology", "monojet", "mono-x", "missing et",
  "simplified model", "mediator mass", "portal interaction",
  "spin-independent", "spin-dependent", "xenon1t", "pandax", "lz experiment",
  "exclusion contour", "atlas dark matter", "cms dark matter"],
 "hep_ph"),

Ordering rule (most-specific-first). Place narrower domains before broader ones. The HEP-ph rule sits at lines 283–292 of detector.py, before the generic physics rules at lines 298–307, so a topic about "dark matter direct detection" hits hep_ph rather than being swallowed by the broader physics_* block. Similarly the neuroscience rules (lines 264–276) precede the ML catch-all (lines 279–281) so "spiking neural" routes to neuroscience_computational instead of ML.

When you add your domain, ask: which already-listed rule could accidentally swallow my topic? Place your tuple above that rule.

8. External-Agent Integration (the ColliderAgent pattern) Copy Chapter

When your domain pipeline isn't a single Python script but a multi-tool toolchain — ColliderAgent runs Lagrangian → FeynRules → UFO → MadGraph5 → Delphes → MadAnalysis5 — wrap it in an experiment mode. The plug-in surface is exactly five edits:

Step 1 — Register the mode Copy Section

researchclaw/config.py:98-106

EXPERIMENT_MODES = {
    "simulated",
    "sandbox",
    "docker",
    "ssh_remote",
    "colab_drive",
    "agentic",
    "collider_agent",     # ← existing example
    "my_domain_agent",    # ← your addition
}

Step 2 — Define the config dataclass Copy Section

Mirror ColliderAgentConfig at config.py:296-333:

@dataclass(frozen=True)
class MyDomainAgentConfig:
    """Configuration for my-domain external-agent experiment mode."""

    # Path to your toolchain repo (used to install skills/agents)
    my_domain_agent_dir: str = "/path/to/MyDomainAgent"
    working_dir: str = "my_domain_workspace"
    timeout_sec: int = 3600
    claude_binary: str = ""                        # auto-detect if empty
    extra_args: tuple[str, ...] = ("--dangerously-skip-permissions",)
    install_skills: bool = True                    # copy skills → ~/.claude
    max_turns: int = 100
    # Add cloud creds, GPU flags, etc. as needed
    incremental: bool = False

Step 3 — Wire it into `ExperimentConfig` Copy Section

researchclaw/config.py:475 — append a field next to collider_agent:

@dataclass(frozen=True)
class ExperimentConfig:
    ...
    collider_agent: ColliderAgentConfig = field(default_factory=ColliderAgentConfig)
    my_domain_agent: MyDomainAgentConfig = field(default_factory=MyDomainAgentConfig)   # ← add
    ...

Step 4 — Add the parser Copy Section

researchclaw/config.py:1094-1110 — mirror _parse_collider_agent_config:

def _parse_my_domain_agent_config(data: dict[str, Any]) -> MyDomainAgentConfig:
    if not data:
        return MyDomainAgentConfig()
    extra_raw = data.get("extra_args", ("--dangerously-skip-permissions",))
    if isinstance(extra_raw, str):
        extra_raw = [extra_raw]
    return MyDomainAgentConfig(
        my_domain_agent_dir=data.get("my_domain_agent_dir", "/path/to/MyDomainAgent"),
        working_dir=data.get("working_dir", "my_domain_workspace"),
        timeout_sec=_safe_int(data.get("timeout_sec"), 3600),
        claude_binary=data.get("claude_binary", ""),
        extra_args=tuple(extra_raw),
        install_skills=bool(data.get("install_skills", True)),
        max_turns=_safe_int(data.get("max_turns"), 100),
    )

Then call it from _parse_experiment_config (around line 1179):

my_domain_agent=_parse_my_domain_agent_config(data.get("my_domain_agent") or {}),

Step 5 — Create the sandbox class Copy Section

researchclaw/experiment/my_domain_agent_sandbox.py — mirror collider_agent_sandbox.py (≈656 lines). The minimum viable shape:

/* Detailed source-code truncated for AI context efficiency. */

The two design rules to copy from ColliderAgentSandbox:

1. Existing keys win for "soft" fields — the agent's own results.json is authoritative for things like metrics and structured_results; the sandbox only fills in source, artifacts, status. (collider_agent_sandbox.py:626-655)
2. returncode, elapsed_sec, timed_out are sandbox-authoritative — always overwritten regardless of what the agent wrote.

Step 6 — Add the factory dispatch Copy Section

researchclaw/experiment/factory.py:85-89 — a dispatch case parallel to collider_agent:

if config.mode == "my_domain_agent":
    from researchclaw.experiment.my_domain_agent_sandbox import MyDomainAgentSandbox
    return MyDomainAgentSandbox(config.my_domain_agent, workdir)

Step 7 — Set the preference in your profile YAML Copy Section

preferred_experiment_mode: my_domain_agent

my_domain_agent:
  timeout_sec: 3600
  max_turns: 100
  install_skills: true
  extra_args:
    - "--dangerously-skip-permissions"

That's the entire Layer 5 surface. The pipeline runner doesn't change.

Step 8 — Mandate a canonical `results.json` in the agent prompt Copy Section

This is non-optional for bench scoring. Agent-based pipelines are atomic: the agent runs end-to-end inside one Claude Code session and exits. The downstream pipeline (stage 14 RESULT_ANALYSIS, stage 15 RESEARCH_DECISION, the bench rubric judge) only reads what's on disk afterwards. If the agent's scientific numbers don't reach a known-location structured file, the rubric scores all-null and the bench is meaningless.

In your _prepare_workspace (Step 5), append a MANDATORY CANONICAL OUTPUT footer to the prompt that instructs the agent to write results.json at the workspace root with this fixed schema:

{
  "primary_metric": <number>,
  "metric_key": "<string>",
  "metrics": { "<domain_key_1>": <number>, "<domain_key_2>": <number>, ... },
  "hypotheses": {
    "h1": {"supported": true|false, "value": <number>, "details": "..."},
    "h2": {"supported": true|false, "details": "..."},
    "h3": {"supported": true|false, "details": "..."}
  },
  "summary": "human-readable narrative",
  "structured_results": {"artifacts": {"figures": [...], "data": [...]}}
}

See biology_agent_sandbox.py:_prepare_workspace and collider_agent_sandbox.py:_prepare_workspace for the exact instruction text — copy it verbatim.

In _build_metrics, read this file via a static _read_agent_results(workspace) helper and merge metrics.* into the SandboxResult.metrics dict, plus convert hypotheses..supported flags into hypothesis__supported 0/1 metrics. This makes the agent's scientific numbers visible to stage 14 and the rubric. See biology_agent_sandbox.py:374-470 for the full pattern.

Crucial guard: the sandbox itself writes a meta stub to results.json (returncode, elapsed_sec, artifacts). _read_agent_results must skip that stub by requiring at least one of metrics, primary_metric, hypotheses, structured_results to be present, otherwise it picks up its own stub and forwards garbage. The fallback chain (analysis/summary.json, analysis/flux_analysis_summary.json) lets the agent use older conventions without breaking.

Step 9 — Implement `run_project()` (SandboxProtocol parity) Copy Section

The pipeline's stage-14 repair loop calls sandbox.run_project(project_dir) to re-execute. Without this method, repair cycles fail silently with 'XYZAgentSandbox' object has no attribute 'run_project'. For agent-based sandboxes the implementation is trivial — a single Claude Code session IS the project — so dispatch to run() after reading the existing plan markdown:

def run_project(self, project_dir, *, entry_point="main.py",
                timeout_sec=300, args=None, env_overrides=None):
    del entry_point, args, env_overrides  # SandboxProtocol parity only
    for cand in (project_dir / "REPAIR_PROMPT.md",
                 project_dir / _PROMPT_FILENAME,
                 self.workdir / _PROMPT_FILENAME):
        if cand.is_file():
            return self.run(cand.read_text(encoding="utf-8"),
                            timeout_sec=timeout_sec)
    return SandboxResult(returncode=-1, stdout="",
                         stderr="no plan found", elapsed_sec=0.0,
                         metrics={}, timed_out=False)

Step 10 — Skip stage 13 + stage-14 repair for your mode Copy Section

For agent-based modes, the python-code refinement loop in stage 13 ITERATIVE_REFINE and the stage-14 repair cycles are dead code: they iterate on python files the agent never executed, then re-spawn the agent atomically anyway. Two one-line edits skip them cleanly:

• researchclaw/pipeline/stage_impls/_execution.py:519 — extend the existing if config.experiment.mode == "collider_agent" guard at the top of _execute_iterative_refine to also include "my_domain_agent".
• researchclaw/pipeline/runner.py:670 — extend the gate above _run_experiment_diagnosis / _run_experiment_repair so it skips when config.experiment.mode in ("collider_agent", "biology_agent", "my_domain_agent").

After these edits the pipeline reduces to: stage 12 (agent runs, writes results.json) → stage 13 (no-op, copies artifacts forward) → stage 14 (reads results.json, builds summary) → stage 15 (proceed-or-reject decision based on the summary). No abstract code refinement.

Step 11 — Declare requirements + plug into the LLM gate Copy Section

For agent modes the pipeline replaces the python-style numeric-threshold repair with an LLM-driven proceed/rerun gate at stage 15 RESEARCH_DECISION. Each manifest declares:

requirements:
  - id: req_<short_name>
    type: numeric | discussion | artifact   # advisory; LLM uses freely
    description: "natural-language statement of what must be true post-run"
    must_pass: true                          # true → unmet ⇒ rerun once

Mechanics:

1. experiments/arc_bench/scripts/prepare_run.py:write_requirements() copies the list to run_dir/stage-09/requirements.json and stashes the full manifest under run_dir/stage-07/topic_manifest.json for fallback lookup.
2. At stage 15, researchclaw.pipeline.stage_impls._analysis._agent_requirements_decision() fires (only when experiment.mode in ("collider_agent", "biology_agent")):
   • reads requirements.json
   • reads the most recent experiment_summary.json and the agent's canonical results.json (with the same fallback chain as the sandbox: analysis/summary.json, analysis/flux_analysis_summary.json, output/data/results.json)
   • calls researchclaw.pipeline.requirements_judge.judge_requirements() — LLM produces {verdict: proceed|reject|partial, per_requirement: [...], delta_feedback}
   • normalizes verdict from per_requirement.met (defends against LLM envelope inconsistency)
3. On reject AND retry budget remains (default 1 retry): writes REPAIR_PROMPT.md to the stage-12 sandbox workspace listing the unmet must_pass items, sets decision = "refine". Runner-side override at runner.py:718 redirects refine → EXPERIMENT_RUN for agent modes (not the python-refine ITERATIVE_REFINE), so the agent re-runs atomically. The sandbox's _prepare_workspace() consumes REPAIR_PROMPT.md (deletes it) and prepends it as a FOLLOWUP DELTA section ahead of the original plan.
4. On reject with retry exhausted, proceed, or partial: sets decision = "proceed". The requirements_unmet flag (when present) flows into requirements_verdict.json at run root and downstream stages can surface caveats.

To raise the retry budget, change _REQUIREMENTS_MAX_RETRIES (default 1) in _analysis.py. To gate ML modes the same way, drop the experiment.mode in ("collider_agent", "biology_agent") guard at the top of _execute_research_decision.

Tight requirements work best — keep the must_pass set to 2-5 items that the agent can unambiguously satisfy or fail. Use must_pass=false for nice-to-haves (mechanistic discussion, seed documentation) so the LLM can flag them without forcing a rerun.

Step 12 — Paper-quality meta-rubric (applies to ALL topics) Copy Section

Per-topic rubrics in config/<domain>/rubrics/.json grade the science.
A separate file — experiments/arc_bench/config/_meta_paper_quality.json —
grades the paper output uniformly across every topic. You do NOT need to
write a separate paper-quality rubric for your domain: the same 19 leaves
(paper-content / code-orchestration / visual-layout / content-accuracy) apply
to ML, physics, biology, and any future domain.

The meta-rubric is graded manually via scripts/judge_paper_manual.sh,
which launches a vision-equipped Claude Code session against the run's
deliverable directory. The bench pipeline does NOT auto-invoke this — paper
quality is too expensive (~$0.5 + 10 min per run) and too subtle (figure
inspection, code review) to bake into every CI cycle.

Your domain only needs to make sure its deliverables are present for the
manual grader to find:

• paper_final.md (or paper_revised.md, or paper_draft.md) under any
  stage-22/, stage-19/, stage-17/, or deliverables/
• A charts/ directory (PNG / PDF) under stage-22/ or deliverables/
• A code/ or experiment_final/ directory with your domain's source

These are produced by the standard pipeline stages 16-22, so no extra wiring
is required.

Step 13 — Place the agent repo under `external/agents/` with attribution Copy Section

Don't reference absolute paths like /home//MyDomainAgent in the default config. Instead:

mkdir -p external/agents
ln -s /path/to/MyDomainAgent external/agents/MyDomainAgent

Then in MyDomainAgentConfig:

my_domain_agent_dir: str = "external/agents/MyDomainAgent"

(Resolved relative to the repo root, which is the cwd when researchclaw runs.) Add an entry to external/agents/README.md crediting the upstream — for ColliderAgent the upstream is https://github.com/HET-AGI/ColliderAgent. The bench's per-run README must mention which external agent produced the results so reviewers can attribute correctly.

9. Validation Steps Copy Chapter

Run these in order. Each command prints success/failure for one layer.

/* Detailed source-code truncated for AI context efficiency. */

If step 5 fails with "extra stage in my_domain" or "missing placeholder {X} in stage Y", fix the bank module — those are the precise contract violations the parity test catches.

10. Worked Example: `hep_ph` (ColliderAgent) Copy Chapter

How the seven layers fit together for the existing HEP integration.

End-to-end flow when a user runs python -m researchclaw run --profile hep_ph --topic "dark photon mediator dark matter":

1. deploy.py reads profiles/hep_ph.yaml → fills experiment.mode = "collider_agent", export.target_conference = "jhep", time budget 7200 s, etc.
2. PromptManager(domain="hep_ph") loads prompts/hep.py STAGES.
3. Pipeline runs stages 0–10. Hypothesis generation uses the theorist/phenomenologist/experimentalist debate roles. Code generation stage's blueprint context is enriched with typical_file_structure and code_generation_hints from the YAML via HEPPhPromptAdapter.get_blueprint_context().
4. Stage 12 (experiment execution) calls create_sandbox(config) → factory dispatches to ColliderAgentSandbox → writes the assembled physics plan to collider_plan.md, installs skills, invokes Claude Code, collects artifacts back into metrics.
5. Stage 13 result analysis uses the model_builder/phenomenologist/experimentalist debate roles.
6. Stage 22 export reads HEPPhPromptAdapter.get_export_publish_blocks() → selects the JHEP template → renders the paper using jheppub.cls.

The 23-stage runner code is unchanged from the ML pipeline.

11. What You Do NOT Need to Touch Copy Chapter

The plug-in surface is intentionally narrow. None of the following ever needs domain-specific edits:

• The pipeline runner (researchclaw/pipeline/runner.py) — it iterates stages by name and calls pm.for_stage(name, **vars).
• Stage handlers (researchclaw/pipeline/stages/*.py) — they request a RenderedPrompt from the manager and pass the same kwarg set regardless of domain.
• LLM dispatch (researchclaw/llm/*.py) — model selection, retries, token accounting.
• Gates and judges (researchclaw/pipeline/gates/*.py, researchclaw/judge/*) — they evaluate outputs against generic structural and quality rubrics.
• Knowledge base writer (researchclaw/kb/*.py) — markdown/Obsidian backends are domain-agnostic.
• Evaluators / scoreboards (researchclaw/evaluator/*).
• Experiment auto-repair (researchclaw/experiment/repair*.py).
• Code-generation agent core (researchclaw/code_agent/*) — it consumes the blueprint context the adapter produced.
• The CLI (researchclaw/__main__.py, researchclaw/cli/*).

If you find yourself editing any of these to make a new domain work, stop — that's a sign the plug-in surface needs widening (or you're doing too much). The five layers above are the contract.

Quick reference: minimum viable new domain Copy Section

1. researchclaw/domains/profiles/<id>.yaml         — write the YAML
2. researchclaw/domains/adapters/<id>.py           — copy biology.py, edit
3. researchclaw/domains/adapters/__init__.py       — import + __all__
   researchclaw/domains/prompt_adapter.py          — add to _build_adapter_registry
4. researchclaw/domains/detector.py:_KEYWORD_RULES — append your tuple
5. pytest tests/test_prompt_bank_parity.py         — must pass (no-op
                                                      unless you added a bank)
6. python -m researchclaw run --profile <id> ...   — smoke test

That's the whole thing. The HEP integration adds layers 5/6 (external agent + JHEP template) on top of the same skeleton.

HITL GUIDE (`docs/HITL_GUIDE.md`) Copy Section

Human-in-the-Loop Co-Pilot Guide

AutoResearchClaw v0.4.0 transforms the pipeline from purely autonomous to a human-AI collaborative research engine. This guide covers everything you need to know.

Table of Contents Copy Chapter

1. Why Co-Pilot?
2. Quick Start
3. Intervention Modes
4. The Co-Pilot Workflow
5. CLI Commands
6. Stage-by-Stage Intervention Guide
7. Workshops
8. Detached Operation
9. Safety & Guardrails
10. Intelligence Layer
11. Pipeline Branching
12. Adapters (CLI / WebSocket / MCP)
13. Configuration Reference
14. FAQ

1. Why Co-Pilot? Copy Chapter

Fully autonomous research pipelines produce papers fast, but testing reveals consistent quality gaps:

The HITL Co-Pilot system solves this by letting you intervene exactly where your expertise matters most, while the AI handles the heavy lifting everywhere else.

The result: papers that combine AI speed with human judgment.

2. Quick Start Copy Chapter

Option A: Co-Pilot Mode (Recommended) Copy Section

researchclaw run --topic "Your research idea" --mode co-pilot

The pipeline will run automatically and pause at key decision points for your input. At each pause, you'll see an interactive prompt with available actions.

Option B: Express Mode (Minimal Interruption) Copy Section

researchclaw run --topic "Your research idea" --mode express

Only pauses at 3 critical gates: hypothesis approval (Stage 8), experiment design (Stage 9), and final quality check (Stage 20).

Option C: Full Auto (Original Behavior) Copy Section

researchclaw run --topic "Your research idea" --auto-approve

No human intervention. Identical to pre-v0.4.0 behavior.

3. Intervention Modes Copy Chapter

How to Choose Copy Section

• First time using the pipeline? Start with step-by-step to understand each stage.
• Publishing a real paper? Use co-pilot for the best quality.
• Running overnight? Use gate-only or express — fewer interruptions.
• Batch processing many topics? Use full-auto.

4. The Co-Pilot Workflow Copy Chapter

When the pipeline pauses, you'll see an interactive panel:

──────────────────────────────────────────────────────────
  HITL | Stage 08: HYPOTHESIS_GEN
  Post-stage review
──────────────────────────────────────────────────────────

  Stage 8 (HYPOTHESIS_GEN) — done

  Hypotheses generated. This is a CRITICAL decision point —
  review each hypothesis for novelty, feasibility, and significance.

  Outputs:
    hypotheses.md (1,247 bytes)
      → ## Hypothesis 1: Quantum gate noise as structured regularization
    novelty_report.json (892 bytes)

  Novelty score: 0.72 (moderate)

  Available actions:
    [a] Approve and continue
    [r] Reject and rollback
    [e] Edit stage output
    [c] Start collaborative chat
    [i] Inject guidance / direction
    [s] Skip this stage
    [q] Abort pipeline
    [v] View full stage output

Action >

Available Actions at Every Pause Copy Section

5. CLI Commands Copy Chapter

Starting a Run Copy Section

# Co-Pilot mode
researchclaw run --topic "Quantum noise as neural network regularization" --mode co-pilot

# With explicit config
researchclaw run --config config.arc.yaml --topic "..." --mode co-pilot

# Resume a previous run in co-pilot mode
researchclaw run --config config.arc.yaml --resume --mode co-pilot

Detached Interaction Copy Section

These commands let you interact with a paused pipeline from a separate terminal:

# Check status
researchclaw status artifacts/rc-2026-0328-abc123

# Attach interactively (full TUI)
researchclaw attach artifacts/rc-2026-0328-abc123

# Quick approve (non-interactive)
researchclaw approve artifacts/rc-2026-0328-abc123 --message "Looks good"

# Quick reject
researchclaw reject artifacts/rc-2026-0328-abc123 --reason "Missing ResNet baseline"

# Inject guidance for a specific stage
researchclaw guide artifacts/rc-2026-0328-abc123 --stage 9 --message "Add Dropout as baseline"

6. Stage-by-Stage Intervention Guide Copy Chapter

Where Your Input Matters Most Copy Section

Guidance Injection Copy Section

You can inject guidance for any stage at any time, even before it runs:

researchclaw guide artifacts/rc-xxx --stage 17 --message "Emphasize the theoretical contribution in the Introduction. Keep the Method section concise."

Guidance is automatically included in the LLM's context when that stage executes.

7. Workshops Copy Chapter

Workshops are specialized collaboration tools for the most critical stages.

Idea Workshop (Stage 7-8) Copy Section

When you enter collaboration mode at Stage 8, the Idea Workshop activates:

You > c  (start collaboration)

AI > I generated 3 candidate hypotheses. Here's my evaluation:
     1. "Quantum gate noise as structured regularization" — Novelty: 8/10, Feasibility: 6/10
     2. "Entanglement-based feature selection" — Novelty: 7/10, Feasibility: 4/10
     3. "Quantum sampling for data augmentation" — Novelty: 5/10, Feasibility: 8/10

     Which direction interests you most?

You > Hypothesis 1 is the most promising, but we need to be more specific.
     The noise should be modeled as a stochastic regularizer, and we need
     to compare against Dropout, Label Smoothing, and MixUp.

AI > Updated hypothesis:
     "We theoretically characterize quantum gate noise as a structured
     stochastic regularizer and empirically demonstrate it outperforms
     Dropout, Label Smoothing, and MixUp on small-sample classification."

     Baselines updated: + Dropout, + Label Smoothing, + MixUp, + CutMix

     Shall I proceed with this direction?

You > Yes, approve.

The workshop automatically:

• Saves your refined hypothesis to hypotheses.md
• Records the conversation in hitl/chat_stage_08.jsonl
• Persists candidate evaluations in hitl/idea_workshop.json

Baseline Navigator (Stage 9) Copy Section

The Baseline Navigator helps you build a rigorous experiment design:

AI > Here are the suggested baselines:
     [AI] ResNet-50 (standard image classification baseline)
     [AI] ViT-B/16 (transformer baseline)
     [AI] Dropout (regularization baseline)

     Experiment Design Checklist:
     [+] Baselines: 3
     [ ] Benchmarks: CIFAR-10, CIFAR-100
     [ ] Metrics: accuracy, F1

You > Add Label Smoothing and MixUp as baselines. Also add STL-10.

AI > Updated. Current checklist:
     [+] Baselines: 5 (ResNet-50, ViT-B/16, Dropout, Label Smoothing, MixUp)
     [+] Benchmarks: 3 (CIFAR-10, CIFAR-100, STL-10)
     [+] Metrics: accuracy, F1

     Review questions:
     [ ] Are all standard baselines for this domain included? ✓
     [ ] Is there at least one ablation planned? — suggest: "noise magnitude sweep"

Paper Co-Writer (Stage 16-17) Copy Section

The Paper Co-Writer supports three workflows:

1. AI-first (default): AI writes the draft, you edit and refine
2. Human-first: You write key paragraphs, AI expands and polishes
3. Interleaved: You alternate — you write the Method, AI writes Related Work

AI > Paper draft completed (5,200 words, 7 sections).
     Which sections would you like to review or co-edit?

You > The Introduction is too generic. Let me rewrite the first paragraph.

AI > Opening your editor... (saves backup to hitl/snapshots/)

     [Editor opens with Introduction section]

You > [Saves edited file]

AI > Your edits look great. I'll polish the transitions and ensure
     the notation is consistent with the Method section.

     Updated Introduction: 420 words → 380 words (tighter, more specific).
     Change summary: +3 added, -5 deleted, ~8 changed, 22 unchanged

8. Detached Operation Copy Chapter

Research runs can take hours. You don't need to sit and watch.

How It Works Copy Section

1. Pipeline pauses → writes hitl/waiting.json
2. Pipeline enters file-polling mode (checks every 2 seconds for response.json)
3. You respond whenever you're ready via attach, approve, or web dashboard
4. Pipeline picks up your response and resumes

Scenario: Overnight Run Copy Section

# Start the run at 6 PM
researchclaw run --topic "..." --mode co-pilot &

# Pipeline runs Stages 1-7, pauses at Stage 8...
# You go home

# Next morning, check status
researchclaw status artifacts/rc-2026-xxx
# Output: "WAITING for input at Stage 8 — HYPOTHESIS_GEN (since 18:42)"

# Review and approve
researchclaw attach artifacts/rc-2026-xxx
# Interactive review → approve → pipeline resumes

Timeout Behavior Copy Section

By default, the pipeline waits 24 hours for a response. You can configure this:

hitl:
  timeouts:
    default_human_timeout_sec: 86400   # 24h (default)
    auto_proceed_on_timeout: false     # true = auto-approve after timeout

9. Safety & Guardrails Copy Chapter

Cost Budget Copy Section

Set a spending limit to prevent runaway API costs:

hitl:
  cost_budget_usd: 50.0   # Pipeline pauses at 50%, 80%, and 100% of budget

When a threshold is breached, the pipeline pauses with a cost summary:

Cost budget alert: Cost: $42.50 / $50.00 [████████████████░░░░] 85%

Claim Verification Copy Section

The Claim Verifier automatically checks AI-generated text against your collected literature:

• Citation claims: Are cited papers in your shortlist? Or fabricated?
• Numerical claims: Do reported numbers match actual experiment data?
• Factual claims: Are "it has been shown that..." statements grounded?

Unverified claims are flagged in the review summary, letting you decide what to keep.

SHA256 Artifact Checksums Copy Section

Every stage output gets a SHA256 manifest (manifest.json) for reproducibility. If an artifact is modified outside the pipeline, verification will detect it.

Escalation Policy Copy Section

For team/production use, configure tiered notification escalation:

hitl:
  escalation:
    levels:
      - delay_sec: 0       # Immediate terminal notification
        channel: terminal
      - delay_sec: 1800    # After 30 min → Slack
        channel: slack
        message: "Pipeline needs attention"
      - delay_sec: 7200    # After 2h → email
        channel: email
      - delay_sec: 86400   # After 24h → auto-abort
        channel: terminal
        auto_action: abort

Extensible Hooks Copy Section

Run custom scripts before/after any stage:

# Create a hook script
cat > artifacts/rc-xxx/hooks/post_stage_10.sh << 'EOF'
#!/bin/sh
echo "Running linter on generated code..."
cd $RC_RUN_DIR/stage-10/experiment && python -m py_compile main.py
EOF
chmod +x artifacts/rc-xxx/hooks/post_stage_10.sh

Hooks receive environment variables: RC_STAGE_NUM, RC_STAGE_NAME, RC_RUN_DIR, RC_HOOK_NAME.

10. Intelligence Layer Copy Chapter

SmartPause Copy Section

SmartPause goes beyond fixed gate stages. It dynamically decides whether to pause based on:

• Quality score (from PRM or heuristics): Low quality → pause for review
• Stage criticality: High-impact stages (hypotheses, experiment design) have lower thresholds
• Historical rejection rate: Stages you frequently reject get paused more often
• Confidence: When the AI is uncertain, it asks for help

You don't need to configure SmartPause — it works automatically in co-pilot mode.

Intervention Learning (ALHF) Copy Section

Every time you approve, reject, or edit, the system learns:

• Stages you always approve → future runs auto-approve them
• Stages you frequently reject → future runs pause more aggressively
• Your edit patterns → inform SmartPause thresholds

After 5+ runs, the system adapts to your review style.

Quality Predictor Copy Section

At any pause point, the system estimates the final paper quality based on current artifacts:

• Literature coverage (number and diversity of papers)
• Hypothesis specificity and falsifiability
• Experiment design completeness (baselines, ablations, metrics)
• Result strength (improvement over baselines)
• Draft quality (length, structure, section coverage)
• Citation integrity

Risk factors are highlighted so you know where to focus your attention.

11. Pipeline Branching Copy Chapter

When you're unsure which research direction to pursue, branch the pipeline:

# At Stage 8, you see 3 promising hypotheses
Action > b  (branch)

# Fork to explore Hypothesis A
researchclaw branch create --run-dir artifacts/rc-xxx --name "quantum-noise" --stage 8

# Fork to explore Hypothesis B
researchclaw branch create --run-dir artifacts/rc-xxx --name "entanglement" --stage 8

Each branch gets its own copy of the pipeline state. Run them independently, then compare:

# Compare branches at Stage 14 (after experiments)
researchclaw branch compare --run-dir artifacts/rc-xxx --stage 14

Branch Comparison — Stage 14: RESULT_ANALYSIS

  main:
    artifacts: 3, quality: 0.72
    → Best accuracy: 78.3%

  quantum-noise:
    artifacts: 3, quality: 0.85
    → Best accuracy: 82.1%

  entanglement:
    artifacts: 2, quality: 0.61
    → Best accuracy: 74.5%

Merge the winner:

researchclaw branch merge --run-dir artifacts/rc-xxx --branch "quantum-noise" --from-stage 9

12. Adapters Copy Chapter

The HITL system supports three interaction channels:

CLI Adapter (Default) Copy Section

Terminal-based interaction with ANSI colors, $EDITOR integration, and multi-line input. Works over SSH.

WebSocket Adapter Copy Section

For the web dashboard. Provides real-time updates via WebSocket:

Browser → WebSocket → ws_adapter.py → waiting.json / response.json → Pipeline

Message types: get_status, approve, reject, edit, inject_guidance, chat_message.

MCP Adapter Copy Section

External AI agents (Claude, OpenClaw) can interact with the HITL system via MCP tool calls:

• hitl_get_status — Check if the pipeline is waiting
• hitl_approve_stage — Approve the current gate
• hitl_reject_stage — Reject with reason
• hitl_inject_guidance — Provide direction
• hitl_view_output — Read stage artifacts

This enables agent-in-the-loop workflows where another AI system reviews and approves the pipeline's work.

13. Configuration Reference Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

Environment Variables Copy Section

14. FAQ Copy Chapter

Does HITL slow down the pipeline? Copy Section

Only at the stages where you choose to intervene. In co-pilot mode, ~15 of 23 stages run automatically. Typical human time is 30-60 minutes per run, compared to 2-4 hours of autonomous execution.

Can I switch modes mid-run? Copy Section

Not currently, but you can resume a paused run with a different mode:

researchclaw run --resume --output artifacts/rc-xxx --mode step-by-step

What if I'm not sure what to do at a pause? Copy Section

Press v to view the full output, then c to chat with the AI about it. The AI can explain what it did and why, and suggest what to focus on.

Does HITL work with ACP/OpenClaw? Copy Section

Yes. The MCP adapter exposes HITL tools that any ACP-compatible agent can call. OpenClaw can automatically review and approve gates.

What data does HITL store? Copy Section

Everything goes in {run_dir}/hitl/:

• session.json — Session state
• interventions.jsonl — All interventions (append log)
• chat_stage_NN.jsonl — Chat histories
• snapshots/ — File backups before edits
• guidance/ — Injected guidance per stage
• notifications.jsonl — Notification log

Is it backward compatible? Copy Section

Yes. Without hitl.enabled: true or --mode, the pipeline behaves identically to v0.3.x. The --auto-approve flag still works and takes precedence over HITL settings.

README AR (`docs/README_AR.md`) Copy Section

**شارك فكرة. احصل على ورقة بحثية. ذاتي، تعاوني ومتطور ذاتياً.**

| | 🏆 معرض الأوراق المُولّدة
8 أوراق في 8 مجالات — الرياضيات، الإحصاء، الأحياء، الحوسبة، NLP، RL، الرؤية الحاسوبية، المتانة — مُولّدة بشكل مستقل تماماً أو بتوجيه مساعد الطيار Human-in-the-Loop.

|
| --- | --- |

🧪 نبحث عن مختبرين! جرّب خط الأنابيب بفكرتك البحثية الخاصة — من أي مجال — وأخبرنا برأيك. ملاحظاتك تشكّل الإصدار القادم مباشرة. → Testing Guide | → 中文测试指南 | → 日本語テストガイド

🔥 News Copy Chapter

• [05/19/2026] v0.5.0 — وكلاء تجارب متعددة المجالات + ARC-Bench — تحديثان رئيسيان. (1) وكلاء تنفيذ متخصصون حسب المجال: أصبحت مرحلة التجارب (المراحل 10–13) توجّه المهام إلى وكلاء متخصصين حسب التخصص بدلاً من بيئة ML الافتراضية فقط — فيزياء الطاقة العالية (ColliderAgent: FeynRules، MadGraph5، Delphes عبر سحابة Magnus)، والأحياء (نمذجة الأيض على مستوى الجينوم باستخدام COBRApy)، والإحصاء (وكيل دراسات المحاكاة)، مع منفّذ Docker عام للكيمياء/المواد. يختار المسار التنفيذي المنفّذ المناسب تلقائيًا حسب مجال البحث. (2) ARC-Bench: معيار مرجعي مفتوح للبحث الذاتي يضم 55 موضوعًا يغطي ML (25)، وفيزياء الطاقة العالية (10)، والكم (10)، والأحياء (7)، والإحصاء (3)، مع بيان (manifest) ومقياس تقييم (rubric) لكل موضوع (experiments/arc_bench/، ومتاح أيضًا على 🤗 Hugging Face). → دليل تكامل المجالات
• [04/01/2026] v0.4.0 — نظام مساعد الطيار Human-in-the-Loop — لم يعد AutoResearchClaw مستقلاً بالكامل فحسب. نظام HITL الجديد يضيف 6 أوضاع تدخل (full-auto، gate-only، checkpoint، step-by-step، co-pilot، custom)، وسياسات لكل مرحلة، وتعاون عميق بين الإنسان والذكاء الاصطناعي. يتضمن: ورشة الأفكار لتطوير الفرضيات التعاوني، متصفح خطوط الأساس لمراجعة تصميم التجارب، الكاتب المشارك للورقة للصياغة التعاونية، SmartPause (تدخل ديناميكي مدفوع بالثقة)، تعلّم التدخل ALHF، التحقق من الادعاءات لمكافحة الهلوسة، حواجز ميزانية التكلفة، تفريع خط الأنابيب لاستكشاف فرضيات متوازية، وأوامر CLI (attach/status/approve/reject/guide). → دليل HITL الكامل
• [03/30/2026] تحميل مرن للمهارات — يدعم AutoResearchClaw الآن تحميل مهارات مفتوحة المصدر ومخصصة من أي تخصص لتعزيز تجربتك البحثية. 20 مهارة مُحمّلة مسبقاً متضمنة كمراجع جاهزة للاستخدام، تغطي الكتابة العلمية وتصميم التجارب والكيمياء والأحياء والمزيد — بما في ذلك مهارة A-Evolve للتطور الذكي ساهم بها المجتمع. حمّل مهاراتك عبر researchclaw skills install أو ضع SKILL.md في .claude/skills/. انظر مكتبة المهارات.
• [03/22/2026] v0.3.2 — دعم متعدد المنصات + استقرار كبير — يعمل AutoResearchClaw الآن مع أي وكيل متوافق مع ACP (Claude Code، Codex CLI، Copilot CLI، Gemini CLI، Kimi CLI) ويدعم منصات المراسلة (Discord، Telegram، Lark، WeChat) عبر جسر OpenClaw. واجهة خلفية جديدة لتوليد الكود عبر CLI-agent تفوّض المرحلتين 10 و13 لوكلاء CLI خارجيين مع التحكم في الميزانية وإدارة المهلة الزمنية. يتضمن نظام مكافحة التلفيق (VerifiedRegistry + حلقة تشخيص وإصلاح التجارب)، 100+ إصلاح أخطاء، إعادة هيكلة modular executor، كشف تلقائي لـ --resume، تعزيز إعادة محاولات LLM، وإصلاحات المجتمع.

الإصدارات السابقة

• [03/18/2026] v0.3.1 — OpenCode Beast Mode + Community Contributions — New "Beast Mode" routes complex code generation to OpenCode with automatic complexity scoring and graceful fallback. Added Novita AI provider support, thread-safety hardening, improved LLM output parsing robustness, and 20+ bug fixes from community PRs and internal audit.
• [03/17/2026] v0.3.0 — MetaClaw Integration — AutoResearchClaw now supports MetaClaw cross-run learning: pipeline failures → structured lessons → reusable skills, injected into all 23 stages. +18.3% robustness in controlled experiments. Opt-in (metaclaw_bridge.enabled: true), fully backward-compatible. See Integration Guide.
• [03/16/2026] v0.2.0 — Three multi-agent subsystems (CodeAgent, BenchmarkAgent, FigureAgent), hardened Docker sandbox with network-policy-aware execution, 4-round paper quality audit (AI-slop detection, 7-dim review scoring, NeurIPS checklist), and 15+ bug fixes from production runs.
• [03/15/2026] v0.1.0 — We release AutoResearchClaw: a fully autonomous 23-stage research pipeline that turns a single research idea into a conference-ready paper. No human intervention required.

⚡ أمر واحد. ورقة واحدة. Copy Chapter

# مستقل تماماً — بدون تدخل بشري
pip install -e . && researchclaw setup && researchclaw init && researchclaw run --topic "Your research idea here" --auto-approve

# وضع مساعد الطيار — تعاون مع الذكاء الاصطناعي في نقاط القرار الرئيسية
researchclaw run --topic "Your research idea here" --mode co-pilot

🤔 ما هذا؟ Copy Chapter

أنت تفكر. AutoResearchClaw يكتب. أنت توجّه القرارات الرئيسية.

أعطِ موضوعاً بحثياً — احصل على ورقة أكاديمية كاملة مع أدبيات حقيقية من OpenAlex و Semantic Scholar و arXiv، وتجارب في بيئة معزولة واعية بالعتاد (كشف تلقائي لـ GPU/MPS/CPU)، وتحليل إحصائي، ومراجعة أقران متعددة الوكلاء، و LaTeX جاهز للمؤتمرات يستهدف NeurIPS/ICML/ICLR. شغّله بشكل مستقل تماماً، أو استخدم وضع مساعد الطيار لتوجيه الذكاء الاصطناعي في نقاط القرار الحاسمة — اختر اتجاهات البحث، راجع تصاميم التجارب، وشارك في كتابة الورقة. بدون مراجع مُلفّقة.

يعمل خط الأنابيب من البداية إلى النهاية — بشكل مستقل تماماً أو بتعاون human-in-the-loop. عندما تفشل التجارب، يصلح نفسه. عندما لا تصمد الفرضيات، يغيّر المسار. عندما تكون الاستشهادات مُلفّقة، يزيلها. عندما تريد التوجيه، يتوقف ويستمع.

🌍 شغّله من أي مكان. AutoResearchClaw ليس مقيّدًا بمنصة واحدة. استخدمه مستقلاً عبر CLI، أو وصّله بـ OpenClaw، أو ادمجه مع أي وكيل متوافق مع ACP — 🤖 Claude Code، 💻 Codex CLI، 🐙 Copilot CLI، ♊ Gemini CLI، 🌙 Kimi CLI، وغيرها. بفضل جسر الرسائل في OpenClaw، يمكنك إطلاق بحث كامل من 💬 Discord، ✈️ Telegram، 🐦 Lark (飞书)، 💚 WeChat، أو أي منصة يستخدمها فريقك بالفعل. موضوع واحد كمُدخل، ورقة بحثية كمُخرج — بغض النظر عن المكان الذي تكتب منه.

🚀 البداية السريعة Copy Chapter

# 1. استنساخ وتثبيت
git clone https://github.com/aiming-lab/AutoResearchClaw.git
cd AutoResearchClaw
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. الإعداد (تفاعلي — يثبّت OpenCode beast mode، يتحقق من Docker/LaTeX)
researchclaw setup

# 3. التهيئة
researchclaw init          # تفاعلي: اختر مزوّد LLM، ينشئ config.arc.yaml
# أو يدوياً: cp config.researchclaw.example.yaml config.arc.yaml

# 4. التشغيل
export OPENAI_API_KEY="sk-..."
researchclaw run --config config.arc.yaml --topic "Your research idea" --auto-approve

المخرجات → artifacts/rc-YYYYMMDD-HHMMSS-<hash>/deliverables/ — LaTeX و BibTeX وكود التجارب والرسوم البيانية جاهزة للترجمة.

📝 الحد الأدنى من التهيئة المطلوبة

project:
  name: "my-research"

research:
  topic: "Your research topic here"

llm:
  base_url: "https://api.openai.com/v1"
  api_key_env: "OPENAI_API_KEY"
  primary_model: "gpt-4o"
  fallback_models: ["gpt-4o-mini"]

experiment:
  mode: "sandbox"
  sandbox:
    python_path: ".venv/bin/python"

🧠 ما الذي يميّزه Copy Chapter

🦞 تكامل OpenClaw Copy Chapter

🚀 الاستخدام مع OpenClaw (موصى به) Copy Section

إذا كنت تستخدم OpenClaw بالفعل كمساعد ذكاء اصطناعي:

1️⃣  شارك رابط مستودع GitHub مع OpenClaw
2️⃣  OpenClaw يقرأ تلقائياً RESEARCHCLAW_AGENTS.md → يفهم خط الأنابيب
3️⃣  قل: "ابحث عن [موضوعك]"
4️⃣  تم — OpenClaw يستنسخ، يثبّت، يهيّئ، يشغّل، ويعيد النتائج

هذا كل شيء. يتعامل OpenClaw مع git clone، pip install، إعداد التهيئة، وتنفيذ خط الأنابيب تلقائياً. أنت فقط تتحدث.

💡 ماذا يحدث خلف الكواليس

1. يقرأ OpenClaw ملف RESEARCHCLAW_AGENTS.md → يتعلم دور منسّق البحث
2. يقرأ OpenClaw ملف README.md → يفهم التثبيت وبنية خط الأنابيب
3. يقرأ OpenClaw ملف config.researchclaw.example.yaml → config.yaml
4. يسأل عن مفتاح API لنموذج اللغة (أو يستخدم متغير البيئة)
5. يشغّل pip install -e . + researchclaw run --topic "..." --auto-approve
6. يعيد الورقة و LaTeX والتجارب والاستشهادات

🔌 جسر OpenClaw (متقدم) Copy Section

للتكامل الأعمق، يتضمن AutoResearchClaw نظام محوّلات جسر مع 6 إمكانيات اختيارية:

# config.arc.yaml
openclaw_bridge:
  use_cron: true              # ⏰ عمليات تشغيل بحث مجدولة
  use_message: true           # 💬 إشعارات التقدم (Discord/Slack/Telegram)
  use_memory: true            # 🧠 استمرارية المعرفة عبر الجلسات
  use_sessions_spawn: true    # 🔀 إطلاق جلسات فرعية متوازية للمراحل المتزامنة
  use_web_fetch: true         # 🌐 بحث ويب مباشر أثناء مراجعة الأدبيات
  use_browser: false          # 🖥️ جمع الأوراق عبر المتصفح

كل علامة تفعّل بروتوكول محوّل مُحدد النوع. عندما يوفر OpenClaw هذه الإمكانيات، تستهلكها المحوّلات بدون تغييرات في الكود. راجع integration-guide.md للتفاصيل الكاملة.

ACP (Agent Client Protocol) Copy Section

يمكن لـ AutoResearchClaw استخدام أي وكيل برمجة متوافق مع ACP كواجهة خلفية لنموذج اللغة — بدون الحاجة لمفاتيح API. يتواصل الوكيل عبر acpx، ويحافظ على جلسة واحدة مستمرة عبر جميع مراحل خط الأنابيب الـ 23.

# config.yaml — مثال ACP
llm:
  provider: "acp"
  acp:
    agent: "claude"   # أي أمر CLI لوكيل متوافق مع ACP
    cwd: "."          # دليل العمل للوكيل
  # لا حاجة لـ base_url أو api_key — الوكيل يدير مصادقته بنفسه.

# فقط شغّل — الوكيل يستخدم بيانات اعتماده الخاصة
researchclaw run --config config.yaml --topic "Your research idea" --auto-approve

🛠️ طرق أخرى للتشغيل Copy Section

🔬 خط الأنابيب: 23 مرحلة، 8 أطوار Copy Chapter

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    ← متعدد الوكلاء
  4. LITERATURE_COLLECT  ← API حقيقي  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    ← فحص الصلة

مراحل البوابات (5، 9، 20) تتوقف للحصول على موافقة بشرية أو موافقة تلقائية مع --auto-approve. عند الرفض، يعود خط الأنابيب للخلف.

وضع مساعد الطيار (--mode co-pilot): تعاون عميق بين الإنسان والذكاء الاصطناعي في المراحل 7-8 (ورشة الأفكار)، المرحلة 9 (متصفح خطوط الأساس)، والمراحل 16-17 (الكاتب المشارك للورقة). المراحل الأخرى تُنفّذ تلقائياً مع مراقبة SmartPause.

حلقات القرار: يمكن للمرحلة 15 تفعيل REFINE (→ المرحلة 13) أو PIVOT (→ المرحلة 8)، مع إصدار تلقائي للمخرجات.

📋 ماذا يفعل كل طور

✨ الميزات الرئيسية Copy Chapter

🧑‍✈️ مساعد الطيار Human-in-the-Loop Copy Chapter

يقدّم AutoResearchClaw v0.4.0 نظام Human-in-the-Loop (HITL) متكاملاً يحوّل خط الأنابيب من مستقل بالكامل إلى محرك بحث تعاوني بين الإنسان والذكاء الاصطناعي. اختر مستوى مشاركتك:

أوضاع التدخل Copy Section

سير عمل مساعد الطيار Copy Section

You: researchclaw run --topic "Quantum noise as neural network regularization" --mode co-pilot

خط الأنابيب يشغّل المراحل 1-7 تلقائياً...

  ┌─────────────────────────────────────────────────────────────┐
  │  HITL | المرحلة 08: HYPOTHESIS_GEN                            │
  │  مراجعة ما بعد المرحلة                                        │
  │                                                             │
  │  الفرضيات المذكورة: 3                                        │
  │  درجة الجدّة: 0.72 (متوسطة)                                   │
  │                                                             │
  │  [a] موافقة  [r] رفض  [e] تعديل  [c] تعاون                   │
  │  [i] حقن توجيه  [v] عرض المخرجات  [q] إلغاء                  │
  └─────────────────────────────────────────────────────────────┘

You: c  (بدء محادثة تعاونية)
You: الفرضية 3 مثيرة لكنها تحتاج Dropout/Label Smoothing كخطوط أساس
AI:  تم التحديث — أُضيف Dropout، Label Smoothing، MixUp، CutMix كخطوط أساس...
You: approve

خط الأنابيب يستمر بفرضيتك المُحسّنة...

أوامر CLI Copy Section

# البدء بوضع HITL
researchclaw run --topic "..." --mode co-pilot

# الاتصال بخط أنابيب متوقف (من طرفية أخرى)
researchclaw attach artifacts/rc-2026-xxx

# التحقق من حالة خط الأنابيب و HITL
researchclaw status artifacts/rc-2026-xxx

# الموافقة/الرفض من طرفية أخرى أو سكريبت
researchclaw approve artifacts/rc-2026-xxx --message "LGTM"
researchclaw reject artifacts/rc-2026-xxx --reason "Missing key baseline"

# حقن توجيه لمرحلة (حتى قبل تشغيلها)
researchclaw guide artifacts/rc-2026-xxx --stage 9 --message "Use ResNet-50 as primary baseline"

القدرات الرئيسية Copy Section

التهيئة Copy Section

# config.arc.yaml
hitl:
  enabled: true
  mode: co-pilot                     # full-auto | gate-only | checkpoint | co-pilot | custom
  cost_budget_usd: 50.0              # توقف عند تجاوز التكلفة للميزانية (0 = بلا حد)

  notifications:
    on_pause: true
    on_quality_drop: true
    channels: ["terminal"]            # terminal | slack | webhook

  timeouts:
    default_human_timeout_sec: 86400  # 24 ساعة انتظار افتراضي
    auto_proceed_on_timeout: false

  collaboration:
    max_chat_turns: 50
    save_chat_history: true

  # سياسات مخصصة لكل مرحلة (اختياري، لوضع 'custom')
  stage_policies:
    8: { require_approval: true, enable_collaboration: true }
    9: { require_approval: true, allow_edit_output: true }

التوافق العكسي Copy Section

• الافتراضي: مُعطّل. بدون hitl.enabled: true أو --mode، يعمل خط الأنابيب تماماً كما كان.
• --auto-approve لا يزال يعمل. يتجاوز وضع HITL.
• جميع الاختبارات الـ 2,699 الحالية تنجح مع وجود كود HITL.

🧠 تكامل MetaClaw Copy Chapter

AutoResearchClaw + MetaClaw = خط أنابيب يتعلم من كل تشغيل.

يضيف MetaClaw نقل المعرفة عبر التشغيلات إلى AutoResearchClaw. عند التفعيل، يلتقط خط الأنابيب تلقائياً الدروس من الإخفاقات والتحذيرات، ويحوّلها إلى مهارات قابلة لإعادة الاستخدام، ويحقنها في جميع مراحل خط الأنابيب الـ 23 في التشغيلات اللاحقة — بحيث لا تتكرر نفس الأخطاء أبداً.

كيف يعمل Copy Section

Run N ينفّذ → الإخفاقات/التحذيرات تُلتقط كـ Lessons
                      ↓
          MetaClaw Lesson → تحويل إلى Skill
                      ↓
          ملفات arc-* Skill تُخزّن في ~/.metaclaw/skills/
                      ↓
Run N+1 → build_overlay() يحقن المهارات في كل أمر LLM
                      ↓
          LLM يتجنب المزالق المعروفة → جودة أعلى، محاولات أقل

الإعداد السريع Copy Section

# 1. تثبيت MetaClaw (إذا لم يكن مُثبّتاً)
pip install metaclaw

# 2. التفعيل في التهيئة

# config.arc.yaml
metaclaw_bridge:
  enabled: true
  proxy_url: "http://localhost:30000"        # وكيل MetaClaw (اختياري)
  skills_dir: "~/.metaclaw/skills"          # أين تُخزّن المهارات
  fallback_url: "https://api.openai.com/v1" # بديل LLM مباشر
  fallback_api_key: ""                      # مفتاح API لعنوان البديل
  lesson_to_skill:
    enabled: true
    min_severity: "warning"                 # تحويل التحذيرات + الأخطاء
    max_skills_per_run: 3

# 3. شغّل كالمعتاد — MetaClaw يعمل بشفافية
researchclaw run --config config.arc.yaml --topic "Your idea" --auto-approve

بعد كل تشغيل، تحقق من ~/.metaclaw/skills/arc-*/SKILL.md لمشاهدة المهارات التي تعلّمها خط أنابيبك.

نتائج التجارب Copy Section

في تجارب A/B مُحكمة (نفس الموضوع، نفس LLM، نفس التهيئة):

درجة المتانة المركّبة هي متوسط مرجّح لمعدل إكمال المراحل (40%) وتقليل المحاولات (30%) وكفاءة دورات REFINE (30%).

التوافق العكسي Copy Section

• الافتراضي: مُعطّل. إذا كان metaclaw_bridge غائباً أو enabled: false، يعمل خط الأنابيب تماماً كما كان.
• بدون تبعيات جديدة. MetaClaw اختياري — خط الأنابيب الأساسي يعمل بدونه.
• جميع الاختبارات الـ 2,699 الحالية تنجح مع وجود كود التكامل.

🧩 مكتبة المهارات Copy Chapter

يدعم AutoResearchClaw الآن تحميل مهارات مفتوحة المصدر ومخصصة لتعزيز تجربتك البحثية. نوفر أيضاً 20 مهارة مُدمجة مُحمّلة مسبقاً (الكتابة العلمية، البحث في الأدبيات، الكيمياء، الأحياء، والمزيد) كمراجع جاهزة للاستخدام، توفر درجة عالية من المرونة فوراً. عطّل أي مهارة بإضافة enabled: false إلى بيانات YAML الوصفية.

نماذج من المهارات المُدمجة:

شاهد جميع المهارات الـ 20 باستخدام researchclaw skills list.

تحميل مهاراتك الخاصة Copy Section

# الخيار 1: تثبيت مهارة (تبقى عبر المشاريع)
researchclaw skills install /path/to/my-skill/

# الخيار 2: ضع SKILL.md في المشروع
mkdir -p .claude/skills/my-custom-skill
# ثم أنشئ SKILL.md مع بيانات YAML وصفية (name، description، trigger-keywords، applicable-stages)

# الخيار 3: هيّئ مجلدات مهارات مشتركة في config.arc.yaml
# skills:
#   custom_dirs:
#     - /path/to/team-shared-skills

استخدام المهارات Copy Section

تُحمّل المهارات وتُحقن في أوامر LLM تلقائياً — لا حاجة لتفعيل يدوي. استخدم CLI للفحص:

researchclaw skills list               # عرض جميع المهارات المُحمّلة مع المصادر
researchclaw skills validate ./my-skill # التحقق من تنسيق SKILL.md

تصفح مهارات المجتمع: K-Dense-AI/claude-scientific-skills (150+ مهارة علمية عبر تخصصات متعددة).

⚙️ مرجع التهيئة Copy Chapter

انقر لتوسيع مرجع التهيئة الكامل

/* Detailed source-code truncated for AI context efficiency. */

🙏 شكر وتقدير Copy Chapter

مستوحى من:

• 🔬 AI Scientist (Sakana AI) — رائد البحث الآلي
• 🧠 AutoResearch (Andrej Karpathy) — أتمتة البحث من البداية إلى النهاية
• 🌐 FARS (Analemma) — نظام بحث مؤتمت بالكامل

📄 الرخصة Copy Chapter

MIT — راجع LICENSE للتفاصيل.

📌 الاستشهاد Copy Chapter

إذا وجدت AutoResearchClaw مفيداً، يرجى الاستشهاد:

@misc{liu2026autoresearchclawselfreinforcingautonomousresearch,
      title={AutoResearchClaw: Self-Reinforcing Autonomous Research with Human-AI Collaboration},
      author={Jiaqi Liu and Shi Qiu and Mairui Li and Bingzhou Li and Haonian Ji and Siwei Han and Xinyu Ye and Peng Xia and Zihan Dong and Congyu Zhang and Letian Zhang and Guiming Chen and Haoqin Tu and Xinyu Yang and Lu Feng and Xujiang Zhao and Haifeng Chen and Jiawei Zhou and Xiao Wang and Weitong Zhang and Hongtu Zhu and Yun Li and Jieru Mei and Hongliang Fei and Jiaheng Zhang and Linjie Li and Linjun Zhang and Yuyin Zhou and Sheng Wang and Caiming Xiong and James Zou and Zeyu Zheng and Cihang Xie and Mingyu Ding and Huaxiu Yao},
      year={2026},
      eprint={2605.20025},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2605.20025},
}

README CN (`docs/README_CN.md`) Copy Section

**聊一个想法。出一篇论文。全自动、协作 & 自演化。**

| | 🏆 生成论文展示
8 篇论文覆盖 8 个领域 — 数学、统计、生物、计算、NLP、RL、视觉、鲁棒性 — 完全自主生成，或通过人机协作的 Co-Pilot 引导。

|
| --- | --- |

🧪 我们正在寻找测试者！ 用你自己的研究想法试试这个流水线 — 任何领域 — 然后 告诉我们你的反馈。你的反馈将直接影响下一个版本。 → Testing Guide | → 中文测试指南 | → 日本語テストガイド

🔥 News Copy Chapter

• [05/19/2026] v0.5.0 — 多领域实验智能体 + ARC-Bench — 两大更新。(1) 领域专家执行智能体： 实验阶段（第 10–13 阶段）不再局限于默认的 ML 沙箱，而是按学科路由到专业智能体——高能物理（ColliderAgent：拉格朗日量 → FeynRules → MadGraph5 → Delphes，经 Magnus 云）、生物学（COBRApy 全基因组代谢建模）与统计学（模拟研究智能体），并由通用 Docker 执行器覆盖化学/材料。流水线会根据研究领域自动选择执行器。(2) ARC-Bench： 一个 55 个主题的开放式自主研究基准，覆盖 ML（25）、高能物理（10）、量子（10）、生物（7）、统计（3），每个主题都附带清单（manifest）与评分量规（rubric），位于 experiments/arc_bench/，并已发布到 🤗 Hugging Face。→ 领域集成指南
• [04/01/2026] v0.4.0 — 人机协作 Co-Pilot 系统 — AutoResearchClaw 不再是纯自动化工具。新增 HITL 系统支持 6 种干预模式（full-auto、gate-only、checkpoint、step-by-step、co-pilot、custom），支持逐阶段策略配置与深度人机协作。包括：Idea Workshop（假设共创）、Baseline Navigator（实验设计审核）、Paper Co-Writer（协作撰写论文）、SmartPause（基于置信度的动态暂停）、ALHF 干预学习、反幻觉声明验证、成本预算护栏、流水线分支并行探索假设，以及 CLI 命令（attach/status/approve/reject/guide）。→ 完整 HITL 指南
• [03/30/2026] 灵活技能加载 — AutoResearchClaw 现已支持从任何学科加载开源和自定义技能。内置 20 个预加载技能作为即用参考，覆盖科学写作、实验设计、化学、生物等领域，包括社区贡献的 A-Evolve 自进化技能。通过 researchclaw skills install 加载或将 SKILL.md 放入 .claude/skills/。参见技能库。
• [03/22/2026] v0.3.2 — 跨平台支持 + 重大稳定性更新 — AutoResearchClaw 现已支持任何 ACP 兼容的 AI 代理后端（Claude Code、Codex CLI、Copilot CLI、Gemini CLI、Kimi CLI），并通过 OpenClaw 桥接支持消息平台（Discord、Telegram、飞书、微信）。新增 CLI-agent 代码生成后端，将 Stage 10 和 13 委托给外部 CLI agent，支持预算控制和超时管理。同时包含反数据捏造系统（VerifiedRegistry + 实验诊断与修复循环），100+ 个 bug 修复，模块化 executor 重构，--resume 自动检测，LLM 重试加固，以及社区反馈修复。

早期版本

• [03/18/2026] v0.3.1 — OpenCode Beast Mode + Community Contributions — New "Beast Mode" routes complex code generation to OpenCode with automatic complexity scoring and graceful fallback. Added Novita AI provider support, thread-safety hardening, improved LLM output parsing robustness, and 20+ bug fixes from community PRs and internal audit.
• [03/17/2026] v0.3.0 — MetaClaw Integration — AutoResearchClaw now supports MetaClaw cross-run learning: pipeline failures → structured lessons → reusable skills, injected into all 23 stages. +18.3% robustness in controlled experiments. Opt-in (metaclaw_bridge.enabled: true), fully backward-compatible. See Integration Guide.
• [03/16/2026] v0.2.0 — Three multi-agent subsystems (CodeAgent, BenchmarkAgent, FigureAgent), hardened Docker sandbox with network-policy-aware execution, 4-round paper quality audit (AI-slop detection, 7-dim review scoring, NeurIPS checklist), and 15+ bug fixes from production runs.
• [03/15/2026] v0.1.0 — We release AutoResearchClaw: a fully autonomous 23-stage research pipeline that turns a single research idea into a conference-ready paper. No human intervention required.

⚡ 一行命令。一篇论文。 Copy Chapter

# 完全自动 — 无需人工干预
pip install -e . && researchclaw setup && researchclaw init && researchclaw run --topic "Your research idea here" --auto-approve

# Co-Pilot 模式 — 在关键决策点与 AI 协作
researchclaw run --topic "Your research idea here" --mode co-pilot

🤔 这是什么？ Copy Chapter

你有一个灵感，AutoResearchClaw 把它写出来。你来引导关键决策。

输入一个研究主题——获得一篇完整的学术论文，包含来自 OpenAlex、Semantic Scholar 和 arXiv 的真实文献，硬件感知沙箱实验（自动检测 GPU/MPS/CPU），统计分析，多 Agent 同行评审，以及面向 NeurIPS/ICML/ICLR 的顶会级 LaTeX。完全自主运行，或使用 Co-Pilot 模式在关键决策点引导 AI——选择研究方向、审核实验设计、协作撰写论文。不会出现幻觉引用。

流水线端到端运行 — 完全自动或人机协作。实验失败时自动修复。假设不成立时自主转向。引用是假的？自动删除。你想介入？它会暂停等候。

🌍 随处可用。 AutoResearchClaw 不绑定任何单一平台。你可以通过 CLI 独立运行，接入 OpenClaw，或对接任何 ACP 兼容的 AI 代理 —— 🤖 Claude Code、💻 Codex CLI、🐙 Copilot CLI、♊ Gemini CLI、🌙 Kimi CLI，应有尽有。而且，借助 OpenClaw 的消息桥接能力，你还可以从 💬 Discord、✈️ Telegram、🐦 飞书、💚 微信，或任何你团队日常使用的平台发起一次完整的研究。输入一个课题，输出一篇论文 —— 无论你在哪里输入。

🚀 快速开始 Copy Chapter

# 1. 克隆 & 安装
git clone https://github.com/aiming-lab/AutoResearchClaw.git
cd AutoResearchClaw
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. 初始化（交互式 — 安装 OpenCode Beast Mode，检查 Docker/LaTeX）
researchclaw setup

# 3. 配置
researchclaw init          # 交互式：选择 LLM 提供商，创建 config.arc.yaml
# 或手动：cp config.researchclaw.example.yaml config.arc.yaml

# 4. 运行
export OPENAI_API_KEY="sk-..."
researchclaw run --config config.arc.yaml --topic "Your research idea" --auto-approve

输出 → artifacts/rc-YYYYMMDD-HHMMSS-<hash>/deliverables/ — 可编译的 LaTeX、BibTeX、实验代码、图表。

📝 最小必要配置

project:
  name: "my-research"

research:
  topic: "Your research topic here"

llm:
  base_url: "https://api.openai.com/v1"
  api_key_env: "OPENAI_API_KEY"
  primary_model: "gpt-4o"
  fallback_models: ["gpt-4o-mini"]

experiment:
  mode: "sandbox"
  sandbox:
    python_path: ".venv/bin/python"

🧠 有什么不同 Copy Chapter

🦞 OpenClaw 集成 Copy Chapter

🚀 通过 OpenClaw 使用（推荐） Copy Section

如果你已经在使用 OpenClaw 作为 AI 助手：

1️⃣  把 GitHub 仓库地址分享给 OpenClaw
2️⃣  OpenClaw 自动读取 RESEARCHCLAW_AGENTS.md → 理解流水线
3️⃣  对它说："帮我研究 [你的主题]"
4️⃣  完成 — OpenClaw 自动克隆、安装、配置、运行，然后返回结果

就这么简单。 OpenClaw 自动处理 git clone、pip install、配置和流水线执行。你只需聊天。

💡 底层发生了什么

1. OpenClaw 读取 RESEARCHCLAW_AGENTS.md → 学习研究编排器角色
2. OpenClaw 读取 README.md → 理解安装方式和流水线结构
3. OpenClaw 复制 config.researchclaw.example.yaml → config.yaml
4. 向你询问 LLM API Key（或使用环境变量）
5. 运行 pip install -e . + researchclaw run --topic "..." --auto-approve
6. 返回论文、LaTeX、实验结果和引用

🔌 OpenClaw Bridge（高级功能） Copy Section

AutoResearchClaw 内置了 Bridge 适配器系统，提供 6 个可选集成能力：

# config.arc.yaml
openclaw_bridge:
  use_cron: true              # ⏰ 定时研究任务
  use_message: true           # 💬 进度通知（Discord/Slack/Telegram）
  use_memory: true            # 🧠 跨会话知识持久化
  use_sessions_spawn: true    # 🔀 为并行阶段派生子会话
  use_web_fetch: true         # 🌐 文献检索中的实时网络搜索
  use_browser: false          # 🖥️ 基于浏览器的论文采集

每个标志激活一个类型化适配器协议。当 OpenClaw 提供对应能力时，适配器无需改代码即可消费。详见 integration-guide.md。

ACP (Agent Client Protocol) Copy Section

AutoResearchClaw 可以使用任何 ACP 兼容的编码 Agent 作为其 LLM 后端——无需 API 密钥。Agent 通过 acpx 通信，在全部 23 个流水线阶段中维持单个持久会话。

# config.yaml — ACP 示例
llm:
  provider: "acp"
  acp:
    agent: "claude"   # 任何 ACP 兼容的 Agent CLI 命令
    cwd: "."          # Agent 的工作目录
  # 无需 base_url 或 api_key — Agent 自行处理认证。

# 直接运行 — Agent 使用自己的凭据
researchclaw run --config config.yaml --topic "Your research idea" --auto-approve

🛠️ 其他运行方式 Copy Section

🔬 流水线：23 个阶段，8 个阶段组 Copy Chapter

阶段组 A：研究定义                阶段组 E：实验执行
  1. TOPIC_INIT                    12. EXPERIMENT_RUN
  2. PROBLEM_DECOMPOSE             13. ITERATIVE_REFINE  ← 自修复

阶段组 B：文献发现                阶段组 F：分析与决策
  3. SEARCH_STRATEGY               14. RESULT_ANALYSIS    ← 多Agent
  4. LITERATURE_COLLECT ← 真实API  15. RESEARCH_DECISION  ← PIVOT/REFINE
  5. LITERATURE_SCREEN  [门控]
  6. KNOWLEDGE_EXTRACT             阶段组 G：论文撰写
                                   16. PAPER_OUTLINE
阶段组 C：知识综合                 17. PAPER_DRAFT
  7. SYNTHESIS                     18. PEER_REVIEW        ← 证据审查
  8. HYPOTHESIS_GEN   ← 辩论      19. PAPER_REVISION

阶段组 D：实验设计                阶段组 H：终稿
  9. EXPERIMENT_DESIGN  [门控]     20. QUALITY_GATE     [门控]
 10. CODE_GENERATION               21. KNOWLEDGE_ARCHIVE
 11. RESOURCE_PLANNING             22. EXPORT_PUBLISH    ← LaTeX
                                   23. CITATION_VERIFY   ← 相关性审查

门控阶段（5、9、20）可暂停等待人工审批，也可用 --auto-approve 自动通过。拒绝后流水线回滚。

Co-Pilot 模式（--mode co-pilot）：在阶段 7-8（Idea Workshop）、阶段 9（Baseline Navigator）和阶段 16-17（Paper Co-Writer）进行深度人机协作。其他阶段自动执行，SmartPause 持续监控。

决策循环：第 15 阶段可触发 REFINE（→ 第 13 阶段）或 PIVOT（→ 第 8 阶段），自动版本化之前的产物。

📋 各阶段组职责

✨ 核心功能 Copy Chapter

🧑‍✈️ 人机协作 Co-Pilot Copy Chapter

AutoResearchClaw v0.4.0 引入了完整的人机协作（HITL）系统，将流水线从纯自动化转变为人机协作的研究引擎。选择你的参与程度：

干预模式 Copy Section

Co-Pilot 工作流 Copy Section

You: researchclaw run --topic "量子噪声作为神经网络正则化" --mode co-pilot

流水线自动运行阶段 1-7...

  ┌─────────────────────────────────────────────────────────────┐
  │  HITL | Stage 08: HYPOTHESIS_GEN                            │
  │  阶段后审查                                                  │
  │                                                             │
  │  提及的假设数: 3                                              │
  │  新颖性得分: 0.72（中等）                                      │
  │                                                             │
  │  [a] 通过  [r] 拒绝  [e] 编辑  [c] 协作                      │
  │  [i] 注入引导  [v] 查看输出  [q] 中止                          │
  └─────────────────────────────────────────────────────────────┘

You: c  (开始协作对话)
You: 假设 3 很有趣，但需要 Dropout/Label Smoothing 作为基线
AI:  已更新——添加了 Dropout、Label Smoothing、MixUp、CutMix 作为基线...
You: approve

流水线继续运行你优化后的假设...

CLI 命令 Copy Section

# 以 HITL 模式启动
researchclaw run --topic "..." --mode co-pilot

# 附加到暂停的流水线（从另一个终端）
researchclaw attach artifacts/rc-2026-xxx

# 检查流水线和 HITL 状态
researchclaw status artifacts/rc-2026-xxx

# 从另一个终端或脚本审批/拒绝
researchclaw approve artifacts/rc-2026-xxx --message "LGTM"
researchclaw reject artifacts/rc-2026-xxx --reason "缺少关键基线"

# 为某个阶段注入引导（甚至在它运行之前）
researchclaw guide artifacts/rc-2026-xxx --stage 9 --message "使用 ResNet-50 作为主要基线"

核心能力 Copy Section

配置 Copy Section

# config.arc.yaml
hitl:
  enabled: true
  mode: co-pilot                     # full-auto | gate-only | checkpoint | co-pilot | custom
  cost_budget_usd: 50.0              # 超出预算时暂停（0 = 无限制）

  notifications:
    on_pause: true
    on_quality_drop: true
    channels: ["terminal"]            # terminal | slack | webhook

  timeouts:
    default_human_timeout_sec: 86400  # 默认等待 24 小时
    auto_proceed_on_timeout: false

  collaboration:
    max_chat_turns: 50
    save_chat_history: true

  # 逐阶段自定义策略（可选，用于 'custom' 模式）
  stage_policies:
    8: { require_approval: true, enable_collaboration: true }
    9: { require_approval: true, allow_edit_output: true }

向后兼容性 Copy Section

• 默认：关闭。 不设置 hitl.enabled: true 或 --mode 时，流水线行为与之前完全一致。
• --auto-approve 仍然有效。 它会覆盖 HITL 模式。
• 所有 2,699 项现有测试通过（包含 HITL 代码）。

🧠 MetaClaw 集成 Copy Chapter

AutoResearchClaw + MetaClaw = 一个能从每次运行中学习的流水线。

MetaClaw 为 AutoResearchClaw 添加了跨运行知识迁移。启用后，流水线会自动从失败和警告中提取教训，将其转化为可复用的技能，并在后续运行中注入到全部 23 个阶段——让同样的错误不再重犯。

工作原理 Copy Section

运行 N 执行 → 失败/警告被捕获为 Lessons
                      ↓
          MetaClaw Lesson → Skill 转换
                      ↓
          arc-* Skill 文件存储在 ~/.metaclaw/skills/
                      ↓
运行 N+1 → build_overlay() 将技能注入每个 LLM 提示
                      ↓
          LLM 规避已知陷阱 → 更高质量，更少重试

快速配置 Copy Section

# 1. 安装 MetaClaw（如未安装）
pip install metaclaw

# 2. 在配置中启用

# config.arc.yaml
metaclaw_bridge:
  enabled: true
  proxy_url: "http://localhost:30000"        # MetaClaw 代理（可选）
  skills_dir: "~/.metaclaw/skills"          # 技能存储位置
  fallback_url: "https://api.openai.com/v1" # 直连 LLM 回退
  fallback_api_key: ""                      # 回退 URL 的 API key
  lesson_to_skill:
    enabled: true
    min_severity: "warning"                 # 转换 warning + error
    max_skills_per_run: 3

# 3. 照常运行 — MetaClaw 透明运作
researchclaw run --config config.arc.yaml --topic "Your idea" --auto-approve

每次运行后，查看 ~/.metaclaw/skills/arc-*/SKILL.md 以了解流水线学到了哪些技能。

实验结果 Copy Section

在对照 A/B 实验中（相同主题、相同 LLM、相同配置）：

综合鲁棒性得分是阶段完成率（40%）、重试减少（30%）和 Refine 循环效率（30%）的加权平均。

向后兼容性 Copy Section

• 默认：关闭。 如果 metaclaw_bridge 不存在或 enabled: false，流水线行为与之前完全一致。
• 无新依赖。 MetaClaw 是可选的——核心流水线无需它即可运行。
• 所有 2,699 项现有测试通过（包含集成代码）。

🧩 技能库 Copy Chapter

AutoResearchClaw 现已支持加载开源和自定义技能，进一步增强你的研究体验。同时内置 20 个预加载技能（科学写作、文献搜索、化学、生物等）作为即用参考，开箱即用的灵活性极高。通过在技能的 frontmatter 中添加 enabled: false 可禁用任何技能。

内置技能示例：

使用 researchclaw skills list 查看全部 20 个技能。

加载自定义技能 Copy Section

# 方式 1：安装技能（跨项目持久化）
researchclaw skills install /path/to/my-skill/

# 方式 2：将 SKILL.md 放入项目中
mkdir -p .claude/skills/my-custom-skill
# 然后创建一个带有 YAML frontmatter 的 SKILL.md（name、description、trigger-keywords、applicable-stages）

# 方式 3：在 config.arc.yaml 中配置共享技能目录
# skills:
#   custom_dirs:
#     - /path/to/team-shared-skills

使用技能 Copy Section

技能会自动加载并注入到 LLM 提示中——无需手动激活。使用 CLI 进行检查：

researchclaw skills list               # 显示所有已加载的技能及来源
researchclaw skills validate ./my-skill # 检查 SKILL.md 格式

浏览社区技能：K-Dense-AI/claude-scientific-skills（150+ 个跨学科的科学技能）。

⚙️ 配置参考 Copy Chapter

点击展开完整配置参考

/* Detailed source-code truncated for AI context efficiency. */

🙏 致谢 Copy Chapter

灵感来源：

• 🔬 AI Scientist（Sakana AI）— 自动化研究先驱
• 🧠 AutoResearch（Andrej Karpathy）— 端到端研究自动化
• 🌐 FARS（Analemma）— 全自动研究系统

📄 许可证 Copy Chapter

MIT — 详见 LICENSE。

📌 引用 Copy Chapter

如果你觉得 AutoResearchClaw 有用，请引用：

@misc{liu2026autoresearchclawselfreinforcingautonomousresearch,
      title={AutoResearchClaw: Self-Reinforcing Autonomous Research with Human-AI Collaboration},
      author={Jiaqi Liu and Shi Qiu and Mairui Li and Bingzhou Li and Haonian Ji and Siwei Han and Xinyu Ye and Peng Xia and Zihan Dong and Congyu Zhang and Letian Zhang and Guiming Chen and Haoqin Tu and Xinyu Yang and Lu Feng and Xujiang Zhao and Haifeng Chen and Jiawei Zhou and Xiao Wang and Weitong Zhang and Hongtu Zhu and Yun Li and Jieru Mei and Hongliang Fei and Jiaheng Zhang and Linjie Li and Linjun Zhang and Yuyin Zhou and Sheng Wang and Caiming Xiong and James Zou and Zeyu Zheng and Cihang Xie and Mingyu Ding and Huaxiu Yao},
      year={2026},
      eprint={2605.20025},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2605.20025},
}

README DE (`docs/README_DE.md`) Copy Section

**Idee besprechen. Paper erhalten. Autonom, Kollaborativ & Selbstevolvierend.**

| | 🏆 Showcase generierter Paper
8 Paper aus 8 Disziplinen — Mathematik, Statistik, Biologie, Informatik, NLP, RL, Vision, Robustheit — vollstaendig autonom generiert oder mit Human-in-the-Loop Co-Pilot-Fuehrung.

|
| --- | --- |

🧪 Wir suchen Tester! Teste die Pipeline mit deiner eigenen Forschungsidee — aus jedem Fachgebiet — und sag uns, was du denkst. Dein Feedback beeinflusst direkt die naechste Version. → Testing Guide | → 中文测试指南 | → 日本語テストガイド

🔥 News Copy Chapter

• [05/19/2026] v0.5.0 — Multi-Domain-Experimentagenten + ARC-Bench — Zwei wesentliche Updates. (1) Domaenenspezifische Ausfuehrungsagenten: Die Experimentphase (Stufen 10–13) leitet nun ueber die Standard-ML-Sandbox hinaus an Fachagenten weiter — Hochenergiephysik (ColliderAgent: FeynRules → MadGraph5 → Delphes ueber die Magnus-Cloud), Biologie (COBRApy-Stoffwechselmodellierung im Genommassstab) und Statistik (Simulationsstudien-Agent), mit einem generischen Docker-Executor fuer Chemie/Materialien. Die Pipeline waehlt den passenden Executor automatisch anhand der Forschungsdomaene. (2) ARC-Bench: ein offener Benchmark fuer autonome Forschung mit 55 Themen, der ML (25), Hochenergiephysik (10), Quanten (10), Biologie (7) und Statistik (3) abdeckt — jedes Thema mit Manifest und Bewertungsrubrik (experiments/arc_bench/, jetzt auch auf 🤗 Hugging Face). → Leitfaden zur Domaenenintegration
• [04/01/2026] v0.4.0 — Human-in-the-Loop Co-Pilot-System — AutoResearchClaw ist nicht mehr rein autonom. Das neue HITL-System fuegt 6 Interventionsmodi hinzu (full-auto, gate-only, checkpoint, step-by-step, co-pilot, custom), stufenspezifische Richtlinien und tiefe Mensch-KI-Kollaboration. Enthalten: Ideen-Workshop zur gemeinsamen Hypothesenerstellung, Baseline-Navigator zur Ueberpruefung des Experimentdesigns, Paper-Co-Writer fuer kollaboratives Verfassen, SmartPause (konfidenzgesteuerte dynamische Intervention), ALHF-Interventionslernen, Anti-Halluzinations-Behauptungsverifikation, Kostenbudget-Leitplanken, Pipeline-Verzweigung fuer parallele Hypothesenerkundung und CLI-Befehle (attach/status/approve/reject/guide). → Vollstaendige HITL-Anleitung
• [03/30/2026] Flexibles Skill-Laden — AutoResearchClaw unterstuetzt jetzt das Laden von Open-Source- und benutzerdefinierten Skills aus jeder Disziplin, um Ihr Forschungserlebnis weiter zu verbessern. 20 vorinstallierte Skills sind als sofort einsetzbare Referenzen enthalten, die wissenschaftliches Schreiben, Experimentdesign, Chemie, Biologie und mehr abdecken — einschliesslich eines A-Evolve Agentic-Evolution-Skills, der von der Community beigesteuert wurde. Laden Sie eigene ueber researchclaw skills install oder legen Sie eine SKILL.md in .claude/skills/ ab. Siehe Skills-Bibliothek.
• [03/22/2026] v0.3.2 — Plattformuebergreifende Unterstuetzung + grosse Stabilitaet — AutoResearchClaw laeuft jetzt mit jedem ACP-kompatiblen Agenten-Backend (Claude Code, Codex CLI, Copilot CLI, Gemini CLI, Kimi CLI) und unterstuetzt Messaging-Plattformen (Discord, Telegram, Lark, WeChat) ueber die OpenClaw-Bruecke. Neues CLI-Agent-Code-Generierungs-Backend delegiert Stages 10 und 13 an externe CLI-Agenten mit Budgetkontrolle und Timeout-Management. Enthaelt Anti-Fabrication-System (VerifiedRegistry + Experiment-Diagnose- und Reparaturschleife), 100+ Bugfixes, modulares Executor-Refactoring, --resume Auto-Erkennung, LLM-Retry-Haertung und Community-Fixes.

Frühere Versionen

• [03/18/2026] v0.3.1 — OpenCode Beast Mode + Community Contributions — New "Beast Mode" routes complex code generation to OpenCode with automatic complexity scoring and graceful fallback. Added Novita AI provider support, thread-safety hardening, improved LLM output parsing robustness, and 20+ bug fixes from community PRs and internal audit.
• [03/17/2026] v0.3.0 — MetaClaw Integration — AutoResearchClaw now supports MetaClaw cross-run learning: pipeline failures → structured lessons → reusable skills, injected into all 23 stages. +18.3% robustness in controlled experiments. Opt-in (metaclaw_bridge.enabled: true), fully backward-compatible. See Integration Guide.
• [03/16/2026] v0.2.0 — Three multi-agent subsystems (CodeAgent, BenchmarkAgent, FigureAgent), hardened Docker sandbox with network-policy-aware execution, 4-round paper quality audit (AI-slop detection, 7-dim review scoring, NeurIPS checklist), and 15+ bug fixes from production runs.
• [03/15/2026] v0.1.0 — We release AutoResearchClaw: a fully autonomous 23-stage research pipeline that turns a single research idea into a conference-ready paper. No human intervention required.

⚡ Ein Befehl. Ein Paper. Copy Chapter

# Vollstaendig autonom — kein menschliches Eingreifen
pip install -e . && researchclaw setup && researchclaw init && researchclaw run --topic "Your research idea here" --auto-approve

# Co-Pilot-Modus — an wichtigen Entscheidungspunkten mit KI zusammenarbeiten
researchclaw run --topic "Your research idea here" --mode co-pilot

🤔 Was ist das? Copy Chapter

Du denkst es. AutoResearchClaw schreibt es. Du triffst die wichtigen Entscheidungen.

Gib ein Forschungsthema ein — erhalte ein vollstaendiges wissenschaftliches Paper mit echter Literatur von OpenAlex, Semantic Scholar und arXiv, hardwarebewussten Sandbox-Experimenten (automatische GPU/MPS/CPU-Erkennung), statistischer Analyse, Multi-Agenten-Peer-Review und konferenzfertigem LaTeX fuer NeurIPS/ICML/ICLR. Fuehre es vollstaendig autonom aus, oder verwende den Co-Pilot-Modus, um die KI an kritischen Entscheidungspunkten zu lenken — waehle Forschungsrichtungen, pruefe Experimentdesigns und verfasse das Paper gemeinsam. Keine halluzinierten Referenzen.

Die Pipeline laeuft End-to-End — vollstaendig autonom oder mit Human-in-the-Loop-Kollaboration. Wenn Experimente fehlschlagen, repariert sie sich selbst. Wenn Hypothesen nicht bestaetigt werden, schwenkt sie um. Wenn Zitationen gefaelscht sind, entfernt sie diese. Wenn du steuern moechtest, pausiert sie und hoert zu.

🌍 Ueberall ausfuehrbar. AutoResearchClaw ist nicht an eine einzelne Plattform gebunden. Nutzen Sie es eigenstaendig ueber die CLI, verbinden Sie es mit OpenClaw, oder integrieren Sie es mit jedem ACP-kompatiblen AI-Agenten — 🤖 Claude Code, 💻 Codex CLI, 🐙 Copilot CLI, ♊ Gemini CLI, 🌙 Kimi CLI und mehr. Dank der Messaging-Bruecke von OpenClaw koennen Sie eine komplette Forschung von 💬 Discord, ✈️ Telegram, 🐦 Lark (飞书), 💚 WeChat oder jeder anderen Plattform starten, die Ihr Team bereits nutzt. Ein Thema rein, ein Paper raus — egal wo Sie tippen.

🚀 Schnellstart Copy Chapter

# 1. Klonen & installieren
git clone https://github.com/aiming-lab/AutoResearchClaw.git
cd AutoResearchClaw
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. Setup (interaktiv — installiert OpenCode Beast Mode, prueft Docker/LaTeX)
researchclaw setup

# 3. Konfigurieren
researchclaw init          # Interaktiv: LLM-Anbieter waehlen, erstellt config.arc.yaml
# Oder manuell: cp config.researchclaw.example.yaml config.arc.yaml

# 4. Ausfuehren
export OPENAI_API_KEY="sk-..."
researchclaw run --config config.arc.yaml --topic "Your research idea" --auto-approve

Ausgabe → artifacts/rc-YYYYMMDD-HHMMSS-<hash>/deliverables/ — kompilierfertiges LaTeX, BibTeX, Experimentcode, Diagramme.

📝 Minimale erforderliche Konfiguration

project:
  name: "my-research"

research:
  topic: "Your research topic here"

llm:
  base_url: "https://api.openai.com/v1"
  api_key_env: "OPENAI_API_KEY"
  primary_model: "gpt-4o"
  fallback_models: ["gpt-4o-mini"]

experiment:
  mode: "sandbox"
  sandbox:
    python_path: ".venv/bin/python"

🧠 Was macht es anders Copy Chapter

🦞 OpenClaw-Integration Copy Chapter

🚀 Verwendung mit OpenClaw (empfohlen) Copy Section

Wenn du bereits OpenClaw als KI-Assistenten nutzt:

1️⃣  Teile die GitHub-Repo-URL mit OpenClaw
2️⃣  OpenClaw liest automatisch RESEARCHCLAW_AGENTS.md → versteht die Pipeline
3️⃣  Sage: "Research [dein Thema]"
4️⃣  Fertig — OpenClaw klont, installiert, konfiguriert, fuehrt aus und liefert Ergebnisse

Das war's. OpenClaw uebernimmt git clone, pip install, Konfiguration und Pipeline-Ausfuehrung automatisch. Du chattest einfach.

💡 Was unter der Haube passiert

1. OpenClaw liest RESEARCHCLAW_AGENTS.md → lernt die Forschungs-Orchestrator-Rolle
2. OpenClaw liest README.md → versteht Installation und Pipeline-Struktur
3. OpenClaw kopiert config.researchclaw.example.yaml → config.yaml
4. Fragt nach deinem LLM-API-Schluessel (oder verwendet deine Umgebungsvariable)
5. Fuehrt pip install -e . + researchclaw run --topic "..." --auto-approve aus
6. Liefert Paper, LaTeX, Experimente und Zitationen zurueck

🔌 OpenClaw Bridge (Fortgeschritten) Copy Section

Fuer tiefere Integration enthaelt AutoResearchClaw ein Bridge-Adapter-System mit 6 optionalen Faehigkeiten:

# config.arc.yaml
openclaw_bridge:
  use_cron: true              # ⏰ Geplante Forschungsdurchlaeufe
  use_message: true           # 💬 Fortschrittsbenachrichtigungen (Discord/Slack/Telegram)
  use_memory: true            # 🧠 Sitzungsuebergreifende Wissenspersistenz
  use_sessions_spawn: true    # 🔀 Parallele Sub-Sessions fuer gleichzeitige Stufen
  use_web_fetch: true         # 🌐 Live-Websuche waehrend der Literaturrecherche
  use_browser: false          # 🖥️ Browserbasierte Paper-Sammlung

Jedes Flag aktiviert ein typisiertes Adapter-Protokoll. Wenn OpenClaw diese Faehigkeiten bereitstellt, nutzen die Adapter sie ohne Codeaenderungen. Siehe integration-guide.md fuer vollstaendige Details.

ACP (Agent Client Protocol) Copy Section

AutoResearchClaw kann jeden ACP-kompatiblen Coding-Agenten als LLM-Backend verwenden — keine API-Schluessel erforderlich. Der Agent kommuniziert ueber acpx und haelt eine einzige persistente Sitzung ueber alle 23 Pipeline-Stufen aufrecht.

# config.yaml — ACP-Beispiel
llm:
  provider: "acp"
  acp:
    agent: "claude"   # Jeder ACP-kompatible Agent-CLI-Befehl
    cwd: "."          # Arbeitsverzeichnis fuer den Agenten
  # Kein base_url oder api_key noetig — der Agent verwaltet seine eigene Authentifizierung.

# Einfach ausfuehren — der Agent verwendet seine eigenen Anmeldedaten
researchclaw run --config config.yaml --topic "Your research idea" --auto-approve

🛠️ Weitere Ausfuehrungsmoeglichkeiten Copy Section

🔬 Pipeline: 23 Stufen, 8 Phasen Copy Chapter

Phase A: Forschungsplanung            Phase E: Experimentausfuehrung
  1. TOPIC_INIT                          12. EXPERIMENT_RUN
  2. PROBLEM_DECOMPOSE                   13. ITERATIVE_REFINE  ← Selbstheilung

Phase B: Literaturrecherche            Phase F: Analyse & Entscheidung
  3. SEARCH_STRATEGY                     14. RESULT_ANALYSIS    ← Multi-Agent
  4. LITERATURE_COLLECT  ← echte API     15. RESEARCH_DECISION  ← PIVOT/REFINE
  5. LITERATURE_SCREEN   [Gate]
  6. KNOWLEDGE_EXTRACT                   Phase G: Papiererstellung
                                         16. PAPER_OUTLINE
Phase C: Wissenssynthese                 17. PAPER_DRAFT
  7. SYNTHESIS                           18. PEER_REVIEW        ← Evidenzpruefung
  8. HYPOTHESIS_GEN    ← Debatte         19. PAPER_REVISION

Phase D: Experimentdesign             Phase H: Finalisierung
  9. EXPERIMENT_DESIGN   [Gate]          20. QUALITY_GATE      [Gate]
 10. CODE_GENERATION                     21. KNOWLEDGE_ARCHIVE
 11. RESOURCE_PLANNING                   22. EXPORT_PUBLISH     ← LaTeX
                                         23. CITATION_VERIFY    ← Relevanzpruefung

Gate-Stufen (5, 9, 20) pausieren fuer menschliche Genehmigung oder werden mit --auto-approve automatisch genehmigt. Bei Ablehnung wird die Pipeline zurueckgesetzt.

Co-Pilot-Modus (--mode co-pilot): Tiefe Mensch-KI-Kollaboration in den Stufen 7-8 (Ideen-Workshop), Stufe 9 (Baseline-Navigator) und Stufen 16-17 (Paper-Co-Writer). Andere Stufen laufen automatisch mit SmartPause-Ueberwachung.

Entscheidungsschleifen: Stufe 15 kann REFINE (→ Stufe 13) oder PIVOT (→ Stufe 8) ausloesen, mit automatischer Artefakt-Versionierung.

📋 Was jede Phase bewirkt

✨ Hauptfunktionen Copy Chapter

🧑‍✈️ Human-in-the-Loop Co-Pilot Copy Chapter

AutoResearchClaw v0.4.0 fuehrt ein vollstaendiges Human-in-the-Loop (HITL)-System ein, das die Pipeline von rein autonom zu einer kollaborativen Mensch-KI-Forschungsmaschine transformiert. Waehle dein Beteiligungsniveau:

Interventionsmodi Copy Section

Co-Pilot-Workflow Copy Section

Du: researchclaw run --topic "Quantenrauschen als neuronales Netzwerk-Regularisierung" --mode co-pilot

Pipeline fuehrt Stufen 1-7 automatisch aus...

  ┌─────────────────────────────────────────────────────────────┐
  │  HITL | Stufe 08: HYPOTHESIS_GEN                            │
  │  Post-Stage-Pruefung                                        │
  │                                                             │
  │  Erwaehnte Hypothesen: 3                                    │
  │  Neuheitswert: 0.72 (moderat)                               │
  │                                                             │
  │  [a] Genehmigen  [r] Ablehnen  [e] Bearbeiten  [c] Kollaborieren │
  │  [i] Anleitung einfuegen  [v] Ausgabe anzeigen  [q] Abbrechen    │
  └─────────────────────────────────────────────────────────────┘

Du: c  (kollaborativen Chat starten)
Du: Hypothese 3 ist interessant, braucht aber Dropout/Label Smoothing als Baselines
KI:  Aktualisiert — Dropout, Label Smoothing, MixUp, CutMix als Baselines hinzugefuegt...
Du: genehmigen

Pipeline setzt mit deiner verfeinerten Hypothese fort...

CLI-Befehle Copy Section

# Mit HITL-Modus starten
researchclaw run --topic "..." --mode co-pilot

# An eine pausierte Pipeline anhaengen (von einem anderen Terminal)
researchclaw attach artifacts/rc-2026-xxx

# Pipeline- und HITL-Status pruefen
researchclaw status artifacts/rc-2026-xxx

# Von einem anderen Terminal oder Skript genehmigen/ablehnen
researchclaw approve artifacts/rc-2026-xxx --message "Sieht gut aus"
researchclaw reject artifacts/rc-2026-xxx --reason "Wichtige Baseline fehlt"

# Anleitung fuer eine Stufe einfuegen (auch bevor sie laeuft)
researchclaw guide artifacts/rc-2026-xxx --stage 9 --message "ResNet-50 als primaere Baseline verwenden"

Hauptfaehigkeiten Copy Section

Konfiguration Copy Section

# config.arc.yaml
hitl:
  enabled: true
  mode: co-pilot                     # full-auto | gate-only | checkpoint | co-pilot | custom
  cost_budget_usd: 50.0              # Pausieren wenn Kosten das Budget ueberschreiten (0 = kein Limit)

  notifications:
    on_pause: true
    on_quality_drop: true
    channels: ["terminal"]            # terminal | slack | webhook

  timeouts:
    default_human_timeout_sec: 86400  # 24h Standard-Wartezeit
    auto_proceed_on_timeout: false

  collaboration:
    max_chat_turns: 50
    save_chat_history: true

  # Stufenspezifische benutzerdefinierte Richtlinien (optional, fuer 'custom'-Modus)
  stage_policies:
    8: { require_approval: true, enable_collaboration: true }
    9: { require_approval: true, allow_edit_output: true }

Abwaertskompatibilitaet Copy Section

• Standard: AUS. Ohne hitl.enabled: true oder --mode verhaelt sich die Pipeline exakt wie zuvor.
• --auto-approve funktioniert weiterhin. Es ueberschreibt den HITL-Modus.
• Alle 2.699 bestehenden Tests bestehen mit vorhandenem HITL-Code.

🧠 MetaClaw-Integration Copy Chapter

AutoResearchClaw + MetaClaw = Eine Pipeline, die aus jedem Durchlauf lernt.

MetaClaw fuegt durchlaufuebergreifenden Wissenstransfer zu AutoResearchClaw hinzu. Wenn aktiviert, erfasst die Pipeline automatisch Erkenntnisse aus Fehlern und Warnungen, konvertiert sie in wiederverwendbare Skills und injiziert diese Skills in alle 23 Pipeline-Stufen bei nachfolgenden Durchlaeufen — damit dieselben Fehler nie wiederholt werden.

Funktionsweise Copy Section

Durchlauf N wird ausgefuehrt → Fehler/Warnungen als Lektionen erfasst
                      ↓
          MetaClaw Lektion → Skill-Konvertierung
                      ↓
          arc-* Skill-Dateien in ~/.metaclaw/skills/ gespeichert
                      ↓
Durchlauf N+1 → build_overlay() injiziert Skills in jeden LLM-Prompt
                      ↓
          LLM vermeidet bekannte Fallstricke → hoehere Qualitaet, weniger Wiederholungen

Schnelleinrichtung Copy Section

# 1. MetaClaw installieren (falls nicht vorhanden)
pip install metaclaw

# 2. In der Konfiguration aktivieren

# config.arc.yaml
metaclaw_bridge:
  enabled: true
  proxy_url: "http://localhost:30000"        # MetaClaw-Proxy (optional)
  skills_dir: "~/.metaclaw/skills"          # Wo Skills gespeichert werden
  fallback_url: "https://api.openai.com/v1" # Direkter LLM-Fallback
  fallback_api_key: ""                      # API-Schluessel fuer Fallback-URL
  lesson_to_skill:
    enabled: true
    min_severity: "warning"                 # Warnungen + Fehler konvertieren
    max_skills_per_run: 3

# 3. Wie gewohnt ausfuehren — MetaClaw arbeitet transparent
researchclaw run --config config.arc.yaml --topic "Your idea" --auto-approve

Nach jedem Durchlauf kannst du ~/.metaclaw/skills/arc-*/SKILL.md pruefen, um die erlernten Skills deiner Pipeline zu sehen.

Experimentergebnisse Copy Section

In kontrollierten A/B-Experimenten (gleiches Thema, gleiches LLM, gleiche Konfiguration):

Der Komposit-Robustheitswert ist ein gewichteter Durchschnitt aus Stufenabschlussrate (40%), Wiederholungsreduktion (30%) und REFINE-Zykluseffizienz (30%).

Abwaertskompatibilitaet Copy Section

• Standard: AUS. Wenn metaclaw_bridge fehlt oder enabled: false, verhaelt sich die Pipeline exakt wie zuvor.
• Keine neuen Abhaengigkeiten. MetaClaw ist optional — die Kern-Pipeline funktioniert ohne.
• Alle 2.699 bestehenden Tests bestehen mit dem Integrationscode.

🧩 Skills-Bibliothek Copy Chapter

AutoResearchClaw unterstuetzt jetzt das Laden von Open-Source- und benutzerdefinierten Skills, um Ihr Forschungserlebnis weiter zu verbessern. Wir liefern ausserdem 20 vorinstallierte integrierte Skills (wissenschaftliches Schreiben, Literatursuche, Chemie, Biologie und mehr) als sofort einsetzbare Referenzen mit, die von Anfang an ein hohes Mass an Flexibilitaet bieten. Deaktivieren Sie einen Skill, indem Sie enabled: false in seinen Frontmatter einfuegen.

Beispiele fuer integrierte Skills:

Alle 20 Skills anzeigen mit researchclaw skills list.

Eigene Skills laden Copy Section

# Option 1: Skill installieren (projektuebergreifend persistent)
researchclaw skills install /path/to/my-skill/

# Option 2: SKILL.md ins Projekt legen
mkdir -p .claude/skills/my-custom-skill
# Dann eine SKILL.md mit YAML-Frontmatter erstellen (name, description, trigger-keywords, applicable-stages)

# Option 3: Gemeinsame Skill-Verzeichnisse in config.arc.yaml konfigurieren
# skills:
#   custom_dirs:
#     - /path/to/team-shared-skills

Skills verwenden Copy Section

Skills werden automatisch geladen und in LLM-Prompts injiziert — keine manuelle Aktivierung noetig. Verwenden Sie die CLI zur Inspektion:

researchclaw skills list               # Alle geladenen Skills mit Quellen anzeigen
researchclaw skills validate ./my-skill # SKILL.md-Format pruefen

Community-Skills durchsuchen: K-Dense-AI/claude-scientific-skills (150+ wissenschaftliche Skills aus mehreren Disziplinen).

⚙️ Konfigurationsreferenz Copy Chapter

Klicken zum Aufklappen der vollstaendigen Konfigurationsreferenz

/* Detailed source-code truncated for AI context efficiency. */

🙏 Danksagungen Copy Chapter

Inspiriert von:

• 🔬 AI Scientist (Sakana AI) — Pionier der automatisierten Forschung
• 🧠 AutoResearch (Andrej Karpathy) — End-to-End-Forschungsautomatisierung
• 🌐 FARS (Analemma) — Fully Automated Research System

📄 Lizenz Copy Chapter

MIT — siehe LICENSE fuer Details.

📌 Zitation Copy Chapter

Wenn du AutoResearchClaw nuetzlich findest, zitiere bitte:

@misc{liu2026autoresearchclawselfreinforcingautonomousresearch,
      title={AutoResearchClaw: Self-Reinforcing Autonomous Research with Human-AI Collaboration},
      author={Jiaqi Liu and Shi Qiu and Mairui Li and Bingzhou Li and Haonian Ji and Siwei Han and Xinyu Ye and Peng Xia and Zihan Dong and Congyu Zhang and Letian Zhang and Guiming Chen and Haoqin Tu and Xinyu Yang and Lu Feng and Xujiang Zhao and Haifeng Chen and Jiawei Zhou and Xiao Wang and Weitong Zhang and Hongtu Zhu and Yun Li and Jieru Mei and Hongliang Fei and Jiaheng Zhang and Linjie Li and Linjun Zhang and Yuyin Zhou and Sheng Wang and Caiming Xiong and James Zou and Zeyu Zheng and Cihang Xie and Mingyu Ding and Huaxiu Yao},
      year={2026},
      eprint={2605.20025},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2605.20025},
}

README ES (`docs/README_ES.md`) Copy Section

**Comparte una idea. Obten un articulo. Autonomo, Colaborativo & Auto-evolutivo.**

| | 🏆 Galeria de articulos generados
8 articulos en 8 dominios — matematicas, estadistica, biologia, computacion, NLP, RL, vision, robustez — generados de forma completamente autonoma o con guia de co-piloto Human-in-the-Loop.

|
| --- | --- |

🧪 Buscamos testers! Prueba el pipeline con tu propia idea de investigacion — de cualquier campo — y cuentanos que piensas. Tu feedback da forma directamente a la proxima version. → Testing Guide | → 中文测试指南 | → 日本語テストガイド

🔥 News Copy Chapter

• [05/19/2026] v0.5.0 — Agentes de experimentacion multidominio + ARC-Bench — Dos actualizaciones principales. (1) Agentes de ejecucion especializados por dominio: la etapa de experimentos (etapas 10–13) ahora va mas alla del sandbox de ML por defecto y enruta a agentes especializados por campo — fisica de altas energias (ColliderAgent: FeynRules → MadGraph5 → Delphes via la nube Magnus), biologia (modelado metabolico a escala genomica con COBRApy) y estadistica (agente de estudios de simulacion), con un ejecutor Docker generico para quimica/materiales. El pipeline selecciona automaticamente el ejecutor adecuado segun el dominio. (2) ARC-Bench: un benchmark de investigacion autonoma abierta de 55 temas que cubre ML (25), fisica de altas energias (10), cuantica (10), biologia (7) y estadistica (3), cada uno con un manifiesto y una rubrica de evaluacion (experiments/arc_bench/, y también en 🤗 Hugging Face). → Guia de integracion de dominios
• [04/01/2026] v0.4.0 — Sistema Co-Piloto Human-in-the-Loop — AutoResearchClaw ya no es puramente autonomo. El nuevo sistema HITL agrega 6 modos de intervencion (full-auto, gate-only, checkpoint, step-by-step, co-pilot, custom), politicas por etapa y colaboracion profunda humano-IA. Incluye: Taller de Ideas para co-creacion de hipotesis, Navegador de Baselines para revision del diseno experimental, Co-Escritor de Articulos para redaccion colaborativa, SmartPause (intervencion dinamica basada en confianza), aprendizaje de intervencion ALHF, verificacion de afirmaciones anti-alucinacion, guardias de presupuesto, ramificacion del pipeline para exploracion paralela de hipotesis, y comandos CLI (attach/status/approve/reject/guide). → Guia HITL completa
• [03/30/2026] Carga Flexible de Habilidades — AutoResearchClaw ahora soporta la carga de habilidades de codigo abierto y personalizadas de cualquier disciplina para mejorar aun mas tu experiencia de investigacion. Se incluyen 20 habilidades precargadas como referencias listas para usar, cubriendo redaccion cientifica, diseno experimental, quimica, biologia y mas — incluyendo una habilidad de evolucion agente A-Evolve contribuida por la comunidad. Carga las tuyas via researchclaw skills install o coloca un SKILL.md en .claude/skills/. Ver Biblioteca de Habilidades.
• [03/22/2026] v0.3.2 — Soporte multiplataforma + estabilidad mayor — AutoResearchClaw ahora funciona con cualquier agente compatible con ACP (Claude Code, Codex CLI, Copilot CLI, Gemini CLI, Kimi CLI) y soporta plataformas de mensajeria (Discord, Telegram, Lark, WeChat) via el puente OpenClaw. Nuevo backend de generacion de codigo CLI-agent que delega las Stages 10 y 13 a agentes CLI externos con control de presupuesto y gestion de timeouts. Incluye sistema anti-fabricacion (VerifiedRegistry + bucle de diagnostico y reparacion), 100+ correcciones de bugs, refactorizacion modular del executor, auto-deteccion de --resume, endurecimiento de reintentos LLM y correcciones de la comunidad.

Versiones anteriores

• [03/18/2026] v0.3.1 — OpenCode Beast Mode + Community Contributions — New "Beast Mode" routes complex code generation to OpenCode with automatic complexity scoring and graceful fallback. Added Novita AI provider support, thread-safety hardening, improved LLM output parsing robustness, and 20+ bug fixes from community PRs and internal audit.
• [03/17/2026] v0.3.0 — MetaClaw Integration — AutoResearchClaw now supports MetaClaw cross-run learning: pipeline failures → structured lessons → reusable skills, injected into all 23 stages. +18.3% robustness in controlled experiments. Opt-in (metaclaw_bridge.enabled: true), fully backward-compatible. See Integration Guide.
• [03/16/2026] v0.2.0 — Three multi-agent subsystems (CodeAgent, BenchmarkAgent, FigureAgent), hardened Docker sandbox with network-policy-aware execution, 4-round paper quality audit (AI-slop detection, 7-dim review scoring, NeurIPS checklist), and 15+ bug fixes from production runs.
• [03/15/2026] v0.1.0 — We release AutoResearchClaw: a fully autonomous 23-stage research pipeline that turns a single research idea into a conference-ready paper. No human intervention required.

⚡ Un comando. Un articulo. Copy Chapter

# Totalmente autonomo — sin intervencion humana
pip install -e . && researchclaw setup && researchclaw init && researchclaw run --topic "Your research idea here" --auto-approve

# Modo Co-Piloto — colabora con la IA en puntos de decision clave
researchclaw run --topic "Your research idea here" --mode co-pilot

🤔 Que es esto? Copy Chapter

Tu lo piensas. AutoResearchClaw lo escribe. Tu guias las decisiones clave.

Proporciona un tema de investigacion — recibe un articulo academico completo con literatura real de OpenAlex, Semantic Scholar y arXiv, experimentos en sandbox adaptados al hardware (deteccion automatica GPU/MPS/CPU), analisis estadistico, revision multi-agentes, y LaTeX listo para conferencia orientado a NeurIPS/ICML/ICLR. Ejecutalo completamente autonomo, o usa el modo Co-Piloto para guiar a la IA en puntos de decision criticos — elige direcciones de investigacion, revisa disenos experimentales y co-escribe el articulo. Sin referencias alucinadas.

El pipeline se ejecuta de principio a fin — completamente autonomo o con colaboracion human-in-the-loop. Cuando los experimentos fallan, se auto-repara. Cuando las hipotesis no se sostienen, pivotea. Cuando las citas son falsas, las elimina. Cuando quieres dirigir, se pausa y escucha.

🌍 Ejecutalo en cualquier lugar. AutoResearchClaw no esta atado a una sola plataforma. Usalo de forma independiente por CLI, conectalo a OpenClaw, o integralo con cualquier agente compatible con ACP — 🤖 Claude Code, 💻 Codex CLI, 🐙 Copilot CLI, ♊ Gemini CLI, 🌙 Kimi CLI, y mas. Gracias al puente de mensajeria de OpenClaw, puedes iniciar una investigacion completa desde 💬 Discord, ✈️ Telegram, 🐦 Lark (飞书), 💚 WeChat, o cualquier plataforma que tu equipo ya utilice. Un tema de entrada, un paper de salida — sin importar donde lo escribas.

🚀 Inicio rapido Copy Chapter

# 1. Clonar e instalar
git clone https://github.com/aiming-lab/AutoResearchClaw.git
cd AutoResearchClaw
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. Setup (interactivo — instala OpenCode beast mode, verifica Docker/LaTeX)
researchclaw setup

# 3. Configurar
researchclaw init          # Interactivo: elegir proveedor LLM, crea config.arc.yaml
# O manualmente: cp config.researchclaw.example.yaml config.arc.yaml

# 4. Ejecutar
export OPENAI_API_KEY="sk-..."
researchclaw run --config config.arc.yaml --topic "Your research idea" --auto-approve

Salida → artifacts/rc-YYYYMMDD-HHMMSS-<hash>/deliverables/ — LaTeX listo para compilar, BibTeX, codigo experimental, graficos.

📝 Configuracion minima requerida

project:
  name: "my-research"

research:
  topic: "Your research topic here"

llm:
  base_url: "https://api.openai.com/v1"
  api_key_env: "OPENAI_API_KEY"
  primary_model: "gpt-4o"
  fallback_models: ["gpt-4o-mini"]

experiment:
  mode: "sandbox"
  sandbox:
    python_path: ".venv/bin/python"

🧠 Que lo hace diferente Copy Chapter

🦞 Integracion con OpenClaw Copy Chapter

🚀 Uso con OpenClaw (Recomendado) Copy Section

Si ya usas OpenClaw como tu asistente de IA:

1️⃣  Comparte la URL del repositorio de GitHub con OpenClaw
2️⃣  OpenClaw lee automaticamente RESEARCHCLAW_AGENTS.md → comprende el pipeline
3️⃣  Di: "Research [tu tema]"
4️⃣  Listo — OpenClaw clona, instala, configura, ejecuta y devuelve los resultados

Eso es todo. OpenClaw se encarga de git clone, pip install, configuracion y ejecucion del pipeline automaticamente. Tu solo chateas.

💡 Que sucede internamente

1. OpenClaw lee RESEARCHCLAW_AGENTS.md → aprende el rol de orquestador de investigacion
2. OpenClaw lee README.md → comprende la instalacion y la estructura del pipeline
3. OpenClaw copia config.researchclaw.example.yaml → config.yaml
4. Solicita tu clave API del LLM (o usa tu variable de entorno)
5. Ejecuta pip install -e . + researchclaw run --topic "..." --auto-approve
6. Devuelve el articulo, LaTeX, experimentos y citas

🔌 Bridge de OpenClaw (Avanzado) Copy Section

Para una integracion mas profunda, AutoResearchClaw incluye un sistema de adaptadores bridge con 6 capacidades opcionales:

# config.arc.yaml
openclaw_bridge:
  use_cron: true              # ⏰ Ejecuciones de investigacion programadas
  use_message: true           # 💬 Notificaciones de progreso (Discord/Slack/Telegram)
  use_memory: true            # 🧠 Persistencia de conocimiento entre sesiones
  use_sessions_spawn: true    # 🔀 Generar sub-sesiones paralelas para etapas concurrentes
  use_web_fetch: true         # 🌐 Busqueda web en vivo durante la revision de literatura
  use_browser: false          # 🖥️ Recopilacion de articulos basada en navegador

Cada flag activa un protocolo de adaptador tipado. Cuando OpenClaw proporciona estas capacidades, los adaptadores las consumen sin cambios en el codigo. Consulta integration-guide.md para mas detalles.

ACP (Agent Client Protocol) Copy Section

AutoResearchClaw puede usar cualquier agente de programacion compatible con ACP como backend LLM — sin necesidad de claves API. El agente se comunica via acpx, manteniendo una sola sesion persistente a traves de las 23 etapas del pipeline.

# config.yaml — ejemplo ACP
llm:
  provider: "acp"
  acp:
    agent: "claude"   # Cualquier comando CLI de agente compatible con ACP
    cwd: "."          # Directorio de trabajo para el agente
  # No se necesita base_url ni api_key — el agente gestiona su propia autenticacion.

# Solo ejecuta — el agente usa sus propias credenciales
researchclaw run --config config.yaml --topic "Your research idea" --auto-approve

🛠️ Otras formas de ejecucion Copy Section

🔬 Pipeline: 23 etapas, 8 fases Copy Chapter

Fase A: Alcance de investigacion     Fase E: Ejecucion de experimentos
  1. TOPIC_INIT                        12. EXPERIMENT_RUN
  2. PROBLEM_DECOMPOSE                 13. ITERATIVE_REFINE  ← auto-reparacion

Fase B: Descubrimiento de literatura Fase F: Analisis y decision
  3. SEARCH_STRATEGY                   14. RESULT_ANALYSIS    ← multi-agente
  4. LITERATURE_COLLECT  ← API real    15. RESEARCH_DECISION  ← PIVOT/REFINE
  5. LITERATURE_SCREEN   [compuerta]
  6. KNOWLEDGE_EXTRACT                 Fase G: Redaccion del articulo
                                       16. PAPER_OUTLINE
Fase C: Sintesis de conocimiento       17. PAPER_DRAFT
  7. SYNTHESIS                         18. PEER_REVIEW        ← verif. evidencia
  8. HYPOTHESIS_GEN    ← debate        19. PAPER_REVISION

Fase D: Diseno experimental          Fase H: Finalizacion
  9. EXPERIMENT_DESIGN   [compuerta]   20. QUALITY_GATE      [compuerta]
 10. CODE_GENERATION                   21. KNOWLEDGE_ARCHIVE
 11. RESOURCE_PLANNING                 22. EXPORT_PUBLISH     ← LaTeX
                                       23. CITATION_VERIFY    ← verif. relevancia

Las etapas con compuerta (5, 9, 20) se pausan para aprobacion humana o se auto-aprueban con --auto-approve. Al rechazar, el pipeline retrocede.

Modo Co-Piloto (--mode co-pilot): Colaboracion profunda humano-IA en las Etapas 7-8 (Taller de Ideas), Etapa 9 (Navegador de Baselines) y Etapas 16-17 (Co-Escritor de Articulos). Las demas etapas se auto-ejecutan con monitoreo SmartPause.

Bucles de decision: La etapa 15 puede activar REFINE (→ Etapa 13) o PIVOT (→ Etapa 8), con versionado automatico de artefactos.

📋 Que hace cada fase

✨ Caracteristicas principales Copy Chapter

🧑‍✈️ Co-Piloto Human-in-the-Loop Copy Chapter

AutoResearchClaw v0.4.0 introduce un sistema completo Human-in-the-Loop (HITL) que transforma el pipeline de puramente autonomo a un motor de investigacion colaborativo humano-IA. Elige tu nivel de participacion:

Modos de intervencion Copy Section

Flujo de trabajo Co-Piloto Copy Section

Tu: researchclaw run --topic "Ruido cuantico como regularizacion de redes neuronales" --mode co-pilot

El pipeline ejecuta las Etapas 1-7 automaticamente...

  ┌─────────────────────────────────────────────────────────────┐
  │  HITL | Etapa 08: HYPOTHESIS_GEN                            │
  │  Revision post-etapa                                        │
  │                                                             │
  │  Hipotesis mencionadas: 3                                   │
  │  Puntuacion de novedad: 0.72 (moderada)                     │
  │                                                             │
  │  [a] Aprobar  [r] Rechazar  [e] Editar  [c] Colaborar      │
  │  [i] Inyectar guia  [v] Ver salida  [q] Abortar            │
  └─────────────────────────────────────────────────────────────┘

Tu: c  (iniciar chat colaborativo)
Tu: La Hipotesis 3 es interesante pero necesita Dropout/Label Smoothing como baselines
IA:  Actualizado — se agregaron Dropout, Label Smoothing, MixUp, CutMix como baselines...
Tu: aprobar

El pipeline continua con tu hipotesis refinada...

Comandos CLI Copy Section

# Iniciar con modo HITL
researchclaw run --topic "..." --mode co-pilot

# Conectarse a un pipeline pausado (desde otra terminal)
researchclaw attach artifacts/rc-2026-xxx

# Verificar el estado del pipeline y HITL
researchclaw status artifacts/rc-2026-xxx

# Aprobar/rechazar desde otra terminal o script
researchclaw approve artifacts/rc-2026-xxx --message "LGTM"
researchclaw reject artifacts/rc-2026-xxx --reason "Falta baseline clave"

# Inyectar guia para una etapa (incluso antes de que se ejecute)
researchclaw guide artifacts/rc-2026-xxx --stage 9 --message "Usar ResNet-50 como baseline principal"

Capacidades clave Copy Section

Configuracion Copy Section

# config.arc.yaml
hitl:
  enabled: true
  mode: co-pilot                     # full-auto | gate-only | checkpoint | co-pilot | custom
  cost_budget_usd: 50.0              # Pausar cuando el costo exceda el presupuesto (0 = sin limite)

  notifications:
    on_pause: true
    on_quality_drop: true
    channels: ["terminal"]            # terminal | slack | webhook

  timeouts:
    default_human_timeout_sec: 86400  # 24h de espera por defecto
    auto_proceed_on_timeout: false

  collaboration:
    max_chat_turns: 50
    save_chat_history: true

  # Politicas personalizadas por etapa (opcional, para modo 'custom')
  stage_policies:
    8: { require_approval: true, enable_collaboration: true }
    9: { require_approval: true, allow_edit_output: true }

Retrocompatibilidad Copy Section

• Por defecto: DESACTIVADO. Sin hitl.enabled: true o --mode, el pipeline se comporta exactamente como antes.
• --auto-approve sigue funcionando. Anula el modo HITL.
• Los 2,699 tests existentes pasan con el codigo HITL presente.

🧠 Integracion MetaClaw Copy Chapter

AutoResearchClaw + MetaClaw = Un pipeline que aprende de cada ejecucion.

MetaClaw agrega transferencia de conocimiento entre ejecuciones a AutoResearchClaw. Cuando esta habilitado, el pipeline captura automaticamente lecciones de fallos y advertencias, las convierte en habilidades reutilizables, e inyecta esas habilidades en las 23 etapas del pipeline en ejecuciones posteriores — para que los mismos errores nunca se repitan.

Como funciona Copy Section

Ejecucion N se ejecuta → fallos/advertencias capturados como Lecciones
                      ↓
          MetaClaw Leccion → conversion a Habilidad
                      ↓
          Archivos de habilidades arc-* almacenados en ~/.metaclaw/skills/
                      ↓
Ejecucion N+1 → build_overlay() inyecta habilidades en cada prompt LLM
                      ↓
          El LLM evita trampas conocidas → mayor calidad, menos reintentos

Configuracion rapida Copy Section

# 1. Instalar MetaClaw (si no esta instalado)
pip install metaclaw

# 2. Habilitar en tu configuracion

# config.arc.yaml
metaclaw_bridge:
  enabled: true
  proxy_url: "http://localhost:30000"        # Proxy MetaClaw (opcional)
  skills_dir: "~/.metaclaw/skills"          # Donde se almacenan las habilidades
  fallback_url: "https://api.openai.com/v1" # Fallback directo al LLM
  fallback_api_key: ""                      # Clave API para la URL de fallback
  lesson_to_skill:
    enabled: true
    min_severity: "warning"                 # Convertir advertencias + errores
    max_skills_per_run: 3

# 3. Ejecuta como siempre — MetaClaw funciona de forma transparente
researchclaw run --config config.arc.yaml --topic "Your idea" --auto-approve

Despues de cada ejecucion, revisa ~/.metaclaw/skills/arc-*/SKILL.md para ver las habilidades que tu pipeline ha aprendido.

Resultados experimentales Copy Section

En experimentos controlados A/B (mismo tema, mismo LLM, misma configuracion):

La puntuacion de robustez compuesta es un promedio ponderado de la tasa de completacion de etapas (40%), reduccion de reintentos (30%) y eficiencia de ciclos REFINE (30%).

Retrocompatibilidad Copy Section

• Por defecto: DESACTIVADO. Si metaclaw_bridge esta ausente o enabled: false, el pipeline se comporta exactamente como antes.
• Sin nuevas dependencias. MetaClaw es opcional — el pipeline base funciona sin el.
• Los 2,699 tests existentes pasan con el codigo de integracion presente.

🧩 Biblioteca de Habilidades Copy Chapter

AutoResearchClaw ahora soporta la carga de habilidades de codigo abierto y personalizadas para mejorar aun mas tu experiencia de investigacion. Tambien incluimos 20 habilidades integradas precargadas (redaccion cientifica, busqueda de literatura, quimica, biologia y mas) como referencias listas para usar, ofreciendo un alto grado de flexibilidad desde el primer momento. Desactiva cualquier habilidad agregando enabled: false a su frontmatter.

Habilidades integradas de ejemplo:

Ver las 20 habilidades con researchclaw skills list.

Carga tus propias habilidades Copy Section

# Opcion 1: Instalar una habilidad (persiste entre proyectos)
researchclaw skills install /path/to/my-skill/

# Opcion 2: Coloca un SKILL.md en el proyecto
mkdir -p .claude/skills/my-custom-skill
# Luego crea un SKILL.md con frontmatter YAML (name, description, trigger-keywords, applicable-stages)

# Opcion 3: Configura directorios de habilidades compartidos en config.arc.yaml
# skills:
#   custom_dirs:
#     - /path/to/team-shared-skills

Uso de habilidades Copy Section

Las habilidades se cargan e inyectan en los prompts del LLM automaticamente — no se necesita activacion manual. Usa el CLI para inspeccionar:

researchclaw skills list               # Muestra todas las habilidades cargadas con sus fuentes
researchclaw skills validate ./my-skill # Verifica el formato de SKILL.md

Explora habilidades de la comunidad: K-Dense-AI/claude-scientific-skills (150+ habilidades cientificas en multiples disciplinas).

⚙️ Referencia de configuracion Copy Chapter

Haz clic para expandir la referencia completa de configuracion

/* Detailed source-code truncated for AI context efficiency. */

🙏 Agradecimientos Copy Chapter

Inspirado por:

• 🔬 AI Scientist (Sakana AI) — Pionero en investigacion automatizada
• 🧠 AutoResearch (Andrej Karpathy) — Automatizacion de investigacion de principio a fin
• 🌐 FARS (Analemma) — Sistema de investigacion completamente automatizado

📄 Licencia Copy Chapter

MIT — consulta LICENSE para mas detalles.

📌 Citacion Copy Chapter

Si encuentras AutoResearchClaw util, por favor cita:

@misc{liu2026autoresearchclawselfreinforcingautonomousresearch,
      title={AutoResearchClaw: Self-Reinforcing Autonomous Research with Human-AI Collaboration},
      author={Jiaqi Liu and Shi Qiu and Mairui Li and Bingzhou Li and Haonian Ji and Siwei Han and Xinyu Ye and Peng Xia and Zihan Dong and Congyu Zhang and Letian Zhang and Guiming Chen and Haoqin Tu and Xinyu Yang and Lu Feng and Xujiang Zhao and Haifeng Chen and Jiawei Zhou and Xiao Wang and Weitong Zhang and Hongtu Zhu and Yun Li and Jieru Mei and Hongliang Fei and Jiaheng Zhang and Linjie Li and Linjun Zhang and Yuyin Zhou and Sheng Wang and Caiming Xiong and James Zou and Zeyu Zheng and Cihang Xie and Mingyu Ding and Huaxiu Yao},
      year={2026},
      eprint={2605.20025},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2605.20025},
}

README FR (`docs/README_FR.md`) Copy Section

**Discutez une idee. Obtenez un article. Autonome, Collaboratif & Auto-evolutif.**

| | 🏆 Vitrine des articles generes
8 articles couvrant 8 domaines — mathematiques, statistiques, biologie, informatique, NLP, RL, vision, robustesse — generes de maniere entierement autonome ou avec guidage co-pilote Human-in-the-Loop.

|
| --- | --- |

🧪 Nous recherchons des testeurs ! Essayez le pipeline avec votre propre idee de recherche — dans n'importe quel domaine — et dites-nous ce que vous en pensez. Vos retours faconnent directement la prochaine version. → Testing Guide | → 中文测试指南 | → 日本語テストガイド

🔥 News Copy Chapter

• [05/19/2026] v0.5.0 — Agents d'experience multi-domaines + ARC-Bench — Deux mises a jour majeures. (1) Agents d'execution specialises par domaine : l'etape d'experience (etapes 10 a 13) ne se limite plus au bac a sable ML par defaut et s'oriente vers des agents specialises selon le domaine — physique des hautes energies (ColliderAgent : FeynRules → MadGraph5 → Delphes via le cloud Magnus), biologie (modelisation metabolique a l'echelle du genome avec COBRApy) et statistiques (agent d'etudes de simulation), avec un executeur Docker generique pour la chimie/les materiaux. Le pipeline selectionne automatiquement le bon executeur selon le domaine. (2) ARC-Bench : un benchmark de recherche autonome ouvert de 55 sujets couvrant ML (25), physique des hautes energies (10), quantique (10), biologie (7) et statistiques (3), chacun fourni avec un manifeste et une grille de notation (experiments/arc_bench/, et aussi sur 🤗 Hugging Face). → Guide d'integration des domaines
• [04/01/2026] v0.4.0 — Systeme Co-Pilote Human-in-the-Loop — AutoResearchClaw n'est plus purement autonome. Le nouveau systeme HITL ajoute 6 modes d'intervention (full-auto, gate-only, checkpoint, step-by-step, co-pilot, custom), des politiques par etape, et une collaboration profonde humain-IA. Inclut : Atelier d'Idees pour la co-creation d'hypotheses, Navigateur de References pour la revue de conception experimentale, Co-Redacteur d'Article pour la redaction collaborative, SmartPause (intervention dynamique guidee par la confiance), apprentissage d'intervention ALHF, verification anti-hallucination des affirmations, garde-fous de budget, ramification du pipeline pour l'exploration parallele d'hypotheses, et commandes CLI (attach/status/approve/reject/guide). → Guide HITL complet
• [03/30/2026] Chargement flexible de competences — AutoResearchClaw supporte desormais le chargement de competences open-source et personnalisees depuis n'importe quelle discipline pour enrichir votre experience de recherche. 20 competences pre-chargees sont incluses comme references pretes a l'emploi, couvrant la redaction scientifique, la conception experimentale, la chimie, la biologie, et plus encore — incluant une competence d'evolution agentique A-Evolve contribuee par la communaute. Chargez les votres via researchclaw skills install ou deposez un SKILL.md dans .claude/skills/. Voir Bibliotheque de competences.
• [03/22/2026] v0.3.2 — Support multiplateforme + stabilite majeure — AutoResearchClaw fonctionne desormais avec tout agent compatible ACP (Claude Code, Codex CLI, Copilot CLI, Gemini CLI, Kimi CLI) et supporte les plateformes de messagerie (Discord, Telegram, Lark, WeChat) via le pont OpenClaw. Nouveau backend de generation de code CLI-agent qui delegue les Stages 10 et 13 a des agents CLI externes avec controle de budget et gestion des timeouts. Inclut le systeme anti-fabrication (VerifiedRegistry + boucle diagnostic/reparation), 100+ corrections de bugs, refactoring modulaire de l'executor, auto-detection --resume, renforcement des retries LLM, et corrections communautaires.

Versions antérieures

• [03/18/2026] v0.3.1 — OpenCode Beast Mode + Community Contributions — New "Beast Mode" routes complex code generation to OpenCode with automatic complexity scoring and graceful fallback. Added Novita AI provider support, thread-safety hardening, improved LLM output parsing robustness, and 20+ bug fixes from community PRs and internal audit.
• [03/17/2026] v0.3.0 — MetaClaw Integration — AutoResearchClaw now supports MetaClaw cross-run learning: pipeline failures → structured lessons → reusable skills, injected into all 23 stages. +18.3% robustness in controlled experiments. Opt-in (metaclaw_bridge.enabled: true), fully backward-compatible. See Integration Guide.
• [03/16/2026] v0.2.0 — Three multi-agent subsystems (CodeAgent, BenchmarkAgent, FigureAgent), hardened Docker sandbox with network-policy-aware execution, 4-round paper quality audit (AI-slop detection, 7-dim review scoring, NeurIPS checklist), and 15+ bug fixes from production runs.
• [03/15/2026] v0.1.0 — We release AutoResearchClaw: a fully autonomous 23-stage research pipeline that turns a single research idea into a conference-ready paper. No human intervention required.

⚡ Une commande. Un article. Copy Chapter

# Entierement autonome — aucune intervention humaine
pip install -e . && researchclaw setup && researchclaw init && researchclaw run --topic "Your research idea here" --auto-approve

# Mode Co-Pilote — collaborez avec l'IA aux points de decision cles
researchclaw run --topic "Your research idea here" --mode co-pilot

🤔 De quoi s'agit-il ? Copy Chapter

Vous y pensez. AutoResearchClaw l'ecrit. Vous guidez les decisions cles.

Donnez un sujet de recherche — recevez un article academique complet avec de la vraie litterature provenant d'OpenAlex, Semantic Scholar et arXiv, des experiences en sandbox adaptees au materiel (detection automatique GPU/MPS/CPU), une analyse statistique, une relecture multi-agents, et du LaTeX pret pour les conferences ciblant NeurIPS/ICML/ICLR. Executez-le en mode entierement autonome, ou utilisez le mode Co-Pilote pour guider l'IA aux points de decision critiques — choisissez les directions de recherche, revisez les conceptions experimentales, et co-redigez l'article. Aucune reference hallucinee.

Le pipeline s'execute de bout en bout — entierement autonome ou avec collaboration human-in-the-loop. Quand les experiences echouent, il s'auto-repare. Quand les hypotheses ne tiennent pas, il pivote. Quand les citations sont fausses, il les supprime. Quand vous voulez intervenir, il se met en pause et ecoute.

🌍 Utilisable partout. AutoResearchClaw n'est pas verrouille sur une seule plateforme. Utilisez-le en CLI autonome, connectez-le a OpenClaw, ou integrez-le avec n'importe quel agent compatible ACP — 🤖 Claude Code, 💻 Codex CLI, 🐙 Copilot CLI, ♊ Gemini CLI, 🌙 Kimi CLI, et bien d'autres. Grace au pont de messagerie d'OpenClaw, vous pouvez lancer une recherche complete depuis 💬 Discord, ✈️ Telegram, 🐦 Lark (飞书), 💚 WeChat, ou la plateforme que votre equipe utilise deja. Un sujet en entree, un article en sortie — peu importe d'ou vous l'envoyez.

🚀 Demarrage rapide Copy Chapter

# 1. Cloner & installer
git clone https://github.com/aiming-lab/AutoResearchClaw.git
cd AutoResearchClaw
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. Setup (interactif — installe OpenCode beast mode, verifie Docker/LaTeX)
researchclaw setup

# 3. Configurer
researchclaw init          # Interactif : choisir le fournisseur LLM, cree config.arc.yaml
# Ou manuellement : cp config.researchclaw.example.yaml config.arc.yaml

# 4. Executer
export OPENAI_API_KEY="sk-..."
researchclaw run --config config.arc.yaml --topic "Your research idea" --auto-approve

Sortie → artifacts/rc-YYYYMMDD-HHMMSS-<hash>/deliverables/ — LaTeX pret a compiler, BibTeX, code d'experience, graphiques.

📝 Configuration minimale requise

project:
  name: "my-research"

research:
  topic: "Your research topic here"

llm:
  base_url: "https://api.openai.com/v1"
  api_key_env: "OPENAI_API_KEY"
  primary_model: "gpt-4o"
  fallback_models: ["gpt-4o-mini"]

experiment:
  mode: "sandbox"
  sandbox:
    python_path: ".venv/bin/python"

🧠 Ce qui le distingue Copy Chapter

🦞 Integration OpenClaw Copy Chapter

🚀 Utilisation avec OpenClaw (recommande) Copy Section

Si vous utilisez deja OpenClaw comme assistant IA :

1️⃣  Partagez l'URL du depot GitHub avec OpenClaw
2️⃣  OpenClaw lit automatiquement RESEARCHCLAW_AGENTS.md → comprend le pipeline
3️⃣  Dites : "Research [votre sujet]"
4️⃣  C'est fait — OpenClaw clone, installe, configure, execute et renvoie les resultats

C'est tout. OpenClaw gere git clone, pip install, la configuration et l'execution du pipeline automatiquement. Vous n'avez qu'a discuter.

💡 Ce qui se passe en coulisses

1. OpenClaw lit RESEARCHCLAW_AGENTS.md → apprend le role d'orchestrateur de recherche
2. OpenClaw lit README.md → comprend l'installation et la structure du pipeline
3. OpenClaw copie config.researchclaw.example.yaml → config.yaml
4. Demande votre cle API LLM (ou utilise votre variable d'environnement)
5. Execute pip install -e . + researchclaw run --topic "..." --auto-approve
6. Renvoie l'article, le LaTeX, les experiences et les citations

🔌 Pont OpenClaw (avance) Copy Section

Pour une integration plus poussee, AutoResearchClaw inclut un systeme d'adaptateurs pont avec 6 fonctionnalites optionnelles :

# config.arc.yaml
openclaw_bridge:
  use_cron: true              # ⏰ Executions de recherche planifiees
  use_message: true           # 💬 Notifications de progression (Discord/Slack/Telegram)
  use_memory: true            # 🧠 Persistance des connaissances inter-sessions
  use_sessions_spawn: true    # 🔀 Lancement de sous-sessions paralleles pour les etapes concurrentes
  use_web_fetch: true         # 🌐 Recherche web en direct pendant la revue de litterature
  use_browser: false          # 🖥️ Collecte d'articles via navigateur

Chaque option active un protocole d'adaptateur type. Quand OpenClaw fournit ces fonctionnalites, les adaptateurs les consomment sans modification de code. Voir integration-guide.md pour tous les details.

ACP (Agent Client Protocol) Copy Section

AutoResearchClaw peut utiliser n'importe quel agent de codage compatible ACP comme backend LLM — sans cle API requise. L'agent communique via acpx, en maintenant une session persistante unique a travers les 23 etapes du pipeline.

# config.yaml — exemple ACP
llm:
  provider: "acp"
  acp:
    agent: "claude"   # N'importe quel agent CLI compatible ACP
    cwd: "."          # Repertoire de travail pour l'agent
  # Pas besoin de base_url ou api_key — l'agent gere sa propre authentification.

# Executez simplement — l'agent utilise ses propres identifiants
researchclaw run --config config.yaml --topic "Your research idea" --auto-approve

🛠️ Autres methodes d'execution Copy Section

🔬 Pipeline : 23 etapes, 8 phases Copy Chapter

Phase A : Cadrage de la recherche     Phase E : Execution des experiences
  1. TOPIC_INIT                         12. EXPERIMENT_RUN
  2. PROBLEM_DECOMPOSE                  13. ITERATIVE_REFINE  ← auto-reparation

Phase B : Decouverte de litterature   Phase F : Analyse et decision
  3. SEARCH_STRATEGY                    14. RESULT_ANALYSIS    ← multi-agents
  4. LITERATURE_COLLECT  ← API reelle   15. RESEARCH_DECISION  ← PIVOT/REFINE
  5. LITERATURE_SCREEN   [porte]
  6. KNOWLEDGE_EXTRACT                  Phase G : Redaction de l'article
                                        16. PAPER_OUTLINE
Phase C : Synthese des connaissances    17. PAPER_DRAFT
  7. SYNTHESIS                          18. PEER_REVIEW        ← verif. preuves
  8. HYPOTHESIS_GEN    ← debat          19. PAPER_REVISION

Phase D : Conception experimentale    Phase H : Finalisation
  9. EXPERIMENT_DESIGN   [porte]        20. QUALITY_GATE      [porte]
 10. CODE_GENERATION                    21. KNOWLEDGE_ARCHIVE
 11. RESOURCE_PLANNING                  22. EXPORT_PUBLISH     ← LaTeX
                                        23. CITATION_VERIFY    ← verif. pertinence

Etapes de validation (5, 9, 20) : pause pour approbation humaine ou approbation automatique avec --auto-approve. En cas de rejet, le pipeline revient en arriere.

Mode Co-Pilote (--mode co-pilot) : Collaboration profonde humain-IA aux etapes 7-8 (Atelier d'Idees), etape 9 (Navigateur de References), et etapes 16-17 (Co-Redacteur d'Article). Les autres etapes s'executent automatiquement avec surveillance SmartPause.

Boucles de decision : l'etape 15 peut declencher REFINE (→ etape 13) ou PIVOT (→ etape 8), avec versionnement automatique des artefacts.

📋 Ce que fait chaque phase

✨ Fonctionnalites cles Copy Chapter

🧑‍✈️ Co-Pilote Human-in-the-Loop Copy Chapter

AutoResearchClaw v0.4.0 introduit un systeme complet Human-in-the-Loop (HITL) qui transforme le pipeline d'un mode purement autonome en un moteur de recherche collaboratif humain-IA. Choisissez votre niveau d'implication :

Modes d'intervention Copy Section

Flux de travail Co-Pilote Copy Section

You: researchclaw run --topic "Quantum noise as neural network regularization" --mode co-pilot

Le pipeline execute les etapes 1-7 automatiquement...

  ┌─────────────────────────────────────────────────────────────┐
  │  HITL | Stage 08: HYPOTHESIS_GEN                            │
  │  Revue post-etape                                           │
  │                                                             │
  │  Hypotheses mentionnees : 3                                 │
  │  Score de nouveaute : 0.72 (modere)                         │
  │                                                             │
  │  [a] Approuver  [r] Rejeter  [e] Editer  [c] Collaborer    │
  │  [i] Injecter un guidage  [v] Voir la sortie  [q] Annuler  │
  └─────────────────────────────────────────────────────────────┘

You: c  (demarrer un chat collaboratif)
You: L'hypothese 3 est interessante mais il faut Dropout/Label Smoothing comme references
AI:  Mis a jour — ajout de Dropout, Label Smoothing, MixUp, CutMix comme references...
You: approve

Le pipeline continue avec votre hypothese affinee...

Commandes CLI Copy Section

# Demarrer en mode HITL
researchclaw run --topic "..." --mode co-pilot

# S'attacher a un pipeline en pause (depuis un autre terminal)
researchclaw attach artifacts/rc-2026-xxx

# Verifier l'etat du pipeline et du HITL
researchclaw status artifacts/rc-2026-xxx

# Approuver/rejeter depuis un autre terminal ou script
researchclaw approve artifacts/rc-2026-xxx --message "LGTM"
researchclaw reject artifacts/rc-2026-xxx --reason "Reference cle manquante"

# Injecter un guidage pour une etape (meme avant son execution)
researchclaw guide artifacts/rc-2026-xxx --stage 9 --message "Utiliser ResNet-50 comme reference principale"

Capacites cles Copy Section

Configuration Copy Section

# config.arc.yaml
hitl:
  enabled: true
  mode: co-pilot                     # full-auto | gate-only | checkpoint | co-pilot | custom
  cost_budget_usd: 50.0              # Pause quand le cout depasse le budget (0 = pas de limite)

  notifications:
    on_pause: true
    on_quality_drop: true
    channels: ["terminal"]            # terminal | slack | webhook

  timeouts:
    default_human_timeout_sec: 86400  # 24h d'attente par defaut
    auto_proceed_on_timeout: false

  collaboration:
    max_chat_turns: 50
    save_chat_history: true

  # Politiques personnalisees par etape (optionnel, pour le mode 'custom')
  stage_policies:
    8: { require_approval: true, enable_collaboration: true }
    9: { require_approval: true, allow_edit_output: true }

Retrocompatibilite Copy Section

• Par defaut : DESACTIVE. Sans hitl.enabled: true ou --mode, le pipeline se comporte exactement comme avant.
• --auto-approve fonctionne toujours. Il prend le pas sur le mode HITL.
• Les 2 699 tests existants passent avec le code HITL present.

🧠 Integration MetaClaw Copy Chapter

AutoResearchClaw + MetaClaw = Un pipeline qui apprend de chaque execution.

MetaClaw ajoute le transfert de connaissances inter-executions a AutoResearchClaw. Lorsqu'il est active, le pipeline capture automatiquement les lecons des echecs et avertissements, les convertit en competences reutilisables, et injecte ces competences dans les 23 etapes du pipeline lors des executions suivantes — pour ne jamais repeter les memes erreurs.

Fonctionnement Copy Section

Execution N s'execute → echecs/avertissements captures comme Lecons
                      ↓
          MetaClaw Lecon → conversion en Competence
                      ↓
          Fichiers de competences arc-* stockes dans ~/.metaclaw/skills/
                      ↓
Execution N+1 → build_overlay() injecte les competences dans chaque prompt LLM
                      ↓
          Le LLM evite les pieges connus → meilleure qualite, moins de tentatives

Configuration rapide Copy Section

# 1. Installer MetaClaw (si ce n'est pas deja fait)
pip install metaclaw

# 2. Activer dans votre configuration

# config.arc.yaml
metaclaw_bridge:
  enabled: true
  proxy_url: "http://localhost:30000"        # Proxy MetaClaw (optionnel)
  skills_dir: "~/.metaclaw/skills"          # Ou les competences sont stockees
  fallback_url: "https://api.openai.com/v1" # Repli direct vers le LLM
  fallback_api_key: ""                      # Cle API pour l'URL de repli
  lesson_to_skill:
    enabled: true
    min_severity: "warning"                 # Convertir avertissements + erreurs
    max_skills_per_run: 3

# 3. Executez comme d'habitude — MetaClaw fonctionne de maniere transparente
researchclaw run --config config.arc.yaml --topic "Your idea" --auto-approve

Apres chaque execution, verifiez ~/.metaclaw/skills/arc-*/SKILL.md pour voir les competences que votre pipeline a apprises.

Resultats experimentaux Copy Section

Dans des experiences controlees A/B (meme sujet, meme LLM, meme configuration) :

Le score de robustesse composite est une moyenne ponderee du taux de completion des etapes (40%), de la reduction des tentatives (30%) et de l'efficacite des cycles REFINE (30%).

Retrocompatibilite Copy Section

• Par defaut : DESACTIVE. Si metaclaw_bridge est absent ou enabled: false, le pipeline se comporte exactement comme avant.
• Aucune nouvelle dependance. MetaClaw est optionnel — le pipeline de base fonctionne sans.
• Les 2 699 tests existants passent avec le code d'integration present.

🧩 Bibliotheque de competences Copy Chapter

AutoResearchClaw supporte desormais le chargement de competences open-source et personnalisees pour enrichir votre experience de recherche. Nous livrons egalement 20 competences integrees pre-chargees (redaction scientifique, recherche documentaire, chimie, biologie, et plus) comme references pretes a l'emploi, offrant un haut degre de flexibilite des l'installation. Desactivez n'importe quelle competence en ajoutant enabled: false a son frontmatter.

Exemples de competences integrees :