文档

这份文档覆盖 ARK 从安装到进阶配置的完整流程，包括文献调研、实验设计与执行、论文写作和迭代审稿。

安装

克隆仓库并以可编辑模式安装 ARK：

git clone https://github.com/kaust-ark/ARK.git
cd ARK
pip install -e .

如需研究阶段功能（Deep Research 集成），请安装 research 扩展：

pip install -e ".[research]"

前置要求

• Python 3.9+
• 至少一个 AI 后端，装好并登录：
  • Claude Code CLI (claude) — 推荐
  • Gemini CLI (gemini)
  • Codex CLI (codex)
• LaTeX 工具链（可选）— pdflatex、bibtex，编译 PDF 用
• PyYAML — 装 ARK 时自动装好

快速开始

建个项目，填标题和想法，剩下的交给 ARK：

# 创建新项目（交互式向导）
ark new my-project

# 运行完整 Pipeline
ark run my-project

# 随时查看进度
ark status my-project

ark new 向导将询问：

1. 论文标题 — 例如 "Efficient Cache-Aware Matrix Multiplication on Modern CPUs"
2. 研究想法 — 描述核心贡献和方法的段落
3. 目标会议 — NeurIPS、ICML、ICLR、ACL、IEEE 等
4. 代码目录 — 实验代码所在位置
5. 模型后端 — Claude、Gemini 或 Codex

也可以从已有 PDF 提案直接起步：

ark new my-project --from-pdf proposal.pdf

ark new

交互式向导，创建研究项目。

ark new <project-name> [options]

会在 ARK/projects/<project-name>/ 下生成：

• config.yaml — 项目配置
• hooks.py — 自定义研究/图表生成逻辑
• agents/ — 各 Agent 的 prompt 文件

ark run

启动自主研究 Pipeline。

ark run <project-name> [options]

也可以直接调 orchestrator，控制更细：

# 指定模型和迭代限制的论文模式
python -m ark.orchestrator --project my-project --mode paper --model claude --max-iterations 20

# 带天数限制的研究模式
python -m ark.orchestrator --project my-project --mode research --model claude --max-days 3

# 后台执行并记录日志
nohup python -m ark.orchestrator --project my-project --mode paper --model claude \
  > auto_research/logs/orchestrator.log 2>&1 &

ark status

查看项目当前进度。

ark status <project-name>

显示：当前迭代、审稿分数、阶段、费用明细和最近的 Agent 动作。

ark monitor

实时监控 Pipeline — 流式输出 Agent 日志和状态变化。

ark monitor <project-name>

ark update

向 Pipeline 发送运行中指令，不停机就能调方向。

ark update <project-name>

# 示例指令：
# "重点关注相关工作部分"
# "添加与 TransformerFAM 的比较"
# "增大图 3 的字体大小"

ark stop

优雅停止运行中的 Pipeline。状态自动 checkpoint，随时恢复。

ark stop <project-name>

ark delete

删除项目及全部配置。

ark delete <project-name>

项目配置

每个项目有一个 config.yaml，Pipeline 的一切都在这控制：

# ARK/projects/my-project/config.yaml
code_dir: /home/user/my-research        # 实验代码所在目录
venue: NeurIPS                           # 目标会议
venue_format: neurips                    # LaTeX 模板格式
venue_pages: 9                           # 正文页数限制

title: "My Paper Title"
model: claude                            # AI 后端 (claude/gemini/codex)

# 目录结构
latex_dir: paper                         # LaTeX 源文件目录（相对于 code_dir）
figures_dir: paper/figures               # 生成的图表
scripts_dir: code                        # 实验脚本

# 图表生成
create_figures_script: code/create_paper_figures.py

# 质量阈值 — 当审稿分数达到此值时停止
paper_accept_threshold: 8

# 目标锚点 — 让 Agent 在迭代中不跑偏
goal_anchor: |
  ## Goal Anchor
  **Paper Title**: My Paper Title
  **Target Venue**: NeurIPS 2025
  **Core Contributions**:
  1. First contribution...
  2. Second contribution...

# 计算设置（可选）
use_slurm: false
slurm_job_prefix: EXP_
conda_env: my-env

# Telegram 通知（可选）
telegram_bot_token: "YOUR_BOT_TOKEN"
telegram_chat_id: "YOUR_CHAT_ID"

会议模板

内置 11+ 会议的精确 LaTeX 排版预设，图表和表格开箱就能对齐：

Agent Prompt

每个 Agent 在 projects/<name>/agents/ 下都有一个 .prompt 文件，改它就能调 Agent 行为：

自定义钩子

每个项目可以定义 hooks.py 注入自定义逻辑：

# ARK/projects/my-project/hooks.py

def pre_experiment(config, state):
    """在每次实验运行前调用。"""
    pass

def post_experiment(config, state, results):
    """实验完成后调用。在此处理结果。"""
    pass

def create_figures(config, state):
    """自定义图表生成逻辑。"""
    pass

阶段一：研究

用 Deep Research 收集背景知识：

1. 以论文标题和研究想法作为输入
2. 进行全面的文献调研
3. 识别相关工作、空白和定位
4. 输出结构化的研究摘要到 auto_research/state/

阶段二：开发

完成实验设计与执行：

1. Planner 根据研究摘要定实验方案
2. Experimenter 写脚本、提交运行（Slurm / 本地 / 云端）
3. Researcher 分析结果，找出还差什么
4. Writer 用 LaTeX 写初稿

阶段三：审稿（核心循环）

这是 ARK 的核心。每轮迭代：

1. 编译 — LaTeX → PDF，生成页面截图供视觉审查
2. 审稿 — Reviewer 打分（1-10）并写详细反馈
3. 规划 + 执行 — Planner 拆任务，Writer / Experimenter / Researcher 干活
4. 可视化 — 修图表、重新编译、验证改动

什么时候停：

• 审稿分数达到 paper_accept_threshold（默认 8）
• 跑满最大迭代次数
• 你手动 ark stop

达到目标分数后，ARK 会再执行一轮收尾迭代处理遗留问题，再输出最终 PDF。

记忆系统

ARK 跨迭代追踪进展，防止死循环和停滞：

# 存储在 auto_research/state/memory.yaml
scores: [5.0, 5.5, 6.0, 6.2, 6.5, 7.0, 7.2]
best_score: 7.2
stagnation_count: 0

分数跟踪

保留最近 20 轮审稿分数历史，用于衡量进展和触发干预。

停滞检测

分数连续多轮不涨，ARK 会：

1. 给 Planner 标记停滞状态
2. 触发 Meta-debugger 做系统级诊断
3. 通过 Telegram 通知你（如已配置），请求人工介入

问题重复跟踪

记录每个问题在审稿中反复出现的次数。修了还不行？ARK 会封掉无效策略，换条路走。

目标锚点

每次 Agent 调用都带上目标锚点 — 项目核心目标的固定描述，防止 Agent 跑偏。

Telegram 集成

ARK 通过 Telegram 推送实时通知，也能接收运行中指令：

设置

# 交互式设置
ark setup-bot

# 或手动添加到 config.yaml：
telegram_bot_token: "YOUR_BOT_TOKEN"
telegram_chat_id: "YOUR_CHAT_ID"

功能

• 迭代通知 — 每轮审稿后推送分数
• PDF 推送 — 随时拿当前论文 PDF
• 运行中指令 — 发消息就能调 Agent 方向
• 停滞警报 — 进展停了自动通知你
• 主动确认 — Agent 要做大动作前先问你

Slurm / HPC

ARK 支持在 Slurm 管理的 HPC 集群上运行实验：

# config.yaml
use_slurm: true
slurm_job_prefix: EXP_       # 作业名前缀
conda_env: my-env             # 要激活的 Conda 环境

开启 use_slurm: true 后，Experimenter Agent 会：

1. 生成带有适当资源请求的 Slurm 批处理脚本
2. 通过 sbatch 提交作业
3. 使用 squeue 监控作业状态
4. 在作业完成后收集结果

没 Slurm？实验直接在本地或任意可 SSH 的服务器上跑。

多模型支持

支持三种 AI 后端，在 config.yaml 或 CLI 里切换：

# 为特定运行切换模型
python -m ark.orchestrator --project my-project --model gemini

状态管理

所有运行时状态在 <code_dir>/auto_research/ 下：

auto_research/
├── state/
│   ├── paper_state.yaml      # 当前论文元数据
│   ├── action_plan.yaml      # 规划师的当前行动计划
│   ├── latest_review.md      # 最新审稿输出
│   ├── memory.yaml           # 分数历史、停滞跟踪
│   ├── checkpoint.yaml       # 恢复检查点
│   └── findings.yaml         # 累积的研究发现
└── logs/
    └── *.log                  # 每轮迭代的 Agent 日志

检查点与恢复

ARK 每轮迭代后自动存档。中断了？再跑一次 ark run 就从上次断点继续。

从头再来

想从零开始？清掉状态文件：

rm -f auto_research/state/checkpoint.yaml \
      auto_research/state/paper_state.yaml \
      auto_research/state/action_plan.yaml \
      auto_research/state/latest_review.md \
      auto_research/state/memory.yaml

故障排除

LaTeX 编译失败

确保已安装 pdflatex 和 bibtex。在 Ubuntu 上：

sudo apt install texlive-full

Agent 超时或失败

看 auto_research/logs/ 下的日志。常见原因：

• Claude Code CLI 没登录 — 跑一次 claude 完成认证
• 速率限制 — ARK 有内置重试和退避
• 上下文太长 — 试试精简目标锚点

分数卡住

审稿分数不涨？

1. 看 auto_research/state/latest_review.md 里的具体问题
2. 通过 ark update 或 Telegram 发针对性指令
3. 调整 projects/<name>/agents/ 里的 Agent Prompt

Pipeline 跑不起来

• 确认 config.yaml 里的路径是绝对路径且存在
• 确认模型 CLI 装好了：which claude
• 跑 ark status <project> 看诊断输出