PaperOrchestra：基于多智能体管道的自动化AI论文写作技能包实践

1. 项目概述：一个为AI编码代理设计的自动化论文写作技能包

如果你是一名AI研究员、数据科学家，或者任何需要频繁撰写学术论文的从业者，你肯定对“写论文”这件事又爱又恨。爱的是研究成果得以呈现，恨的是从零散的实验日志、混乱的图表和浩如烟海的参考文献中，整理出一篇结构严谨、格式规范的LaTeX论文，这个过程极其耗时且繁琐。更不用说，当你同时使用Claude Code、Cursor、Antigravity等多个AI编码助手进行探索性研究时，相关的对话、代码和结果分散在各个角落，事后整理更是噩梦。

现在，想象一下，有一个工具能将这个“噩梦”流程自动化。它不是一个独立的、需要你学习新API的复杂系统，而是一套“技能包”（Skill Pack）。你可以把它安装到你正在使用的任何AI编码代理（如Claude Code、Cursor）中，然后直接告诉你的AI助手：“帮我把这个项目里的所有实验整理成一篇会议论文。” 接下来，从文献综述、图表绘制、章节撰写到内容润色，整个流程将由一个多智能体管道自动协调完成，最终输出一份提交就绪的LaTeX文档。这就是PaperOrchestra项目要解决的问题。

PaperOrchestra 并非一个全新的、需要独立部署的AI写作工具。它的核心创新在于其“可插拔”的设计理念。它基于一篇名为《PaperOrchestra: A Multi-Agent Framework for Automated AI Research Paper Writing》的arXiv论文（2026年）中提出的五智能体管道，并将论文附录F中公开的完整提示词（Prompt）、JSON模式、停止规则和验证流程，打包成了一组你的“宿主”AI代理可以直接理解和执行的技能文件。

这意味着什么？意味着零API密钥，零SDK依赖，零嵌入式LLM调用。整个技能包只包含指令文档和确定性的辅助脚本（如JSON验证、模糊匹配、BibTeX格式化）。所有需要“思考”的部分——LLM推理、网络搜索、语义理解——都委托给你已经信任且正在使用的那个AI编码代理来完成。你不需要为PaperOrchestra单独付费或配置模型，它只是极大地扩展了你现有AI助手的能力边界，让它从一个代码编写者，升级为一个能统筹论文写作全流程的“研究助理”。

2. 核心架构与设计哲学拆解

2.1 从论文到可执行技能：一种务实的技术转化

PaperOrchestra 项目的本质，是将学术研究中的“框架”进行了一次极其务实的工程化落地。原论文提出了一个在基准测试上显著优于单智能体和树搜索基线的方法，但其价值如果只停留在论文里，对大多数研究者而言仍是遥不可及的。该项目团队做了一件非常“极客”的事情：他们把论文附录F里长达数十页的、详尽的提示词和流程说明，直接变成了可运行的代码和指令。

这种转化包含几个关键层次：

1. 模块化封装：将论文中定义的五个核心智能体（提纲、绘图、文献综述、章节写作、内容精炼）以及一个协调者、一个基准测试工具，分别封装成独立的“技能”文件夹。每个技能都是一个自包含的单元。
2. 职责分离：项目严格遵循“宿主代理负责智能，技能包负责流程”的原则。SKILL.md文件是给AI看的“超级详细的岗位说明书”，而scripts/目录下的Python脚本则处理所有确定性的、规则性的工作，比如验证JSON格式、计算字符串相似度、检查LaTeX语法。这种分离保证了系统的透明度和可控性。
3. 无状态设计：技能包本身不保存任何会话状态或记忆。所有中间状态和最终输出都保存在用户指定的workspace目录中。这使得流程可以随时中断、检查和继续，也方便进行版本控制。

这种设计哲学带来的最大好处是兼容性与灵活性。因为不绑定任何特定的LLM API，所以任何能够读取文件、执行命令、进行网络搜索的“编码代理”都可以成为它的宿主。这打破了工具链的垄断，让研究者可以自由选择自己最顺手的主工具。

2.2 七技能协同：解析自动化论文流水线

整个PaperOrchestra流程由七个技能协同完成，它们共同构成了一条从原始材料到成稿的自动化流水线。理解每个技能的角色，有助于我们在使用时进行监控和干预。

paper-orchestra(协调者)这是整个流程的“总指挥”。它不直接进行内容创作，而是负责读取用户输入（研究想法、实验日志），然后按顺序调用和协调其他六个技能的工作。它会检查每个步骤的产出是否符合预设的“关卡”（gate），比如文献综述的引用覆盖率是否达到90%，才会放行进入下一阶段。你可以把它理解为一个自动化的工作流引擎。

outline-agent(提纲智能体)流程的第一步。它接收一个“稀疏想法”（Sparse Idea，即一段简要的研究描述）和实验日志，然后生成一个结构化的论文提纲JSON。这个提纲非常详细，不仅包括章节标题，还会规划好每个部分需要绘制哪些图（Plotting Plan）、需要回顾哪些文献（Lit Review Plan）、每个章节的核心论点是什么。这是后续所有工作的蓝图。

plotting-agent(绘图智能体) &literature-review-agent(文献综述智能体)这是流程中并行执行的两个核心环节，也是耗时最长的部分。

• 绘图智能体：根据提纲中的“绘图计划”，负责生成论文中的所有图表。它优先尝试集成更强大的PaperBanana工具（如果已配置），该工具能基于真实论文案例进行检索、规划、风格化，生成出版质量的示意图。如果未配置，则回退到使用matplotlib生成基础图表。它还会为每张图生成准确的标题和说明文字。
• 文献综述智能体：根据“文献回顾计划”，进行网络搜索，寻找相关论文。它使用Semantic ScholarAPI（支持无密钥的公共端点，但有速率限制）来验证找到的文献元数据（标题、作者、年份）的准确性，并使用Levenshtein距离进行模糊匹配（相似度>70%才采纳）。其核心产出是论文的“引言”和“相关工作”章节草稿，并要求达到至少90%的引用集成度（即提出的观点都有文献支撑）。

section-writing-agent(章节写作智能体)在前两步完成后，这个智能体进行一次“多模态”调用（尽管当前主要处理文本），基于提纲、已生成的图表、文献综述草稿和完整的实验日志，一次性撰写论文剩余的核心章节（如方法、实验、结果分析、讨论等）。它还会从实验日志中提取数据，构建结果表格，并将生成的图表插入到合适的位置。

content-refinement-agent(内容精炼智能体)扮演“模拟同行评审”的角色。它对初稿进行多轮润色，检查逻辑一致性、表述清晰度、与实验数据的吻合度等。关键在于，它遵循论文中定义的严格“停止规则”（Halt Rules），例如，如果修改无法在特定评估维度上提升分数，则回滚修改。这防止了智能体为了“优化”而引入事实错误或偏离原意。

paper-writing-bench&paper-autoraters(基准与自动评分器)这两个是辅助性技能。paper-writing-bench用于从一篇已完成的论文“反向工程”出原始的“稀疏想法”和“实验日志”，主要用于构建测试用例。paper-autoraters则是运行论文中定义的自动评分器，用于客观评估生成论文的质量，如“引用F1分数”、“文献综述质量六轴评估”等。在常规写作流程中，用户一般不会直接调用它们。

注意：这个多智能体管道并非魔法。它的高质量产出严重依赖于两点：1. 输入的研究想法和实验日志本身的质量和清晰度；2. 宿主AI代理（如Claude-3.5-Sonnet, GPT-4）本身的推理与写作能力。技能包提供的是经过验证的最佳流程和提示，但“厨师”（宿主AI）的功底同样重要。

3. 前置准备：聚合分散的研究记录

在实际研究过程中，我们往往不是在开始时就规整地写好了idea.md和experimental_log.md。更多的情况是：想法在Claude的对话里，代码片段在Cursor的项目中，运行结果散落在Antigravity的工作日志里。agent-research-aggregator这个可选技能，就是为了解决这个“最后一公里”问题而生的。

3.1 聚合器的工作原理：四阶段数据清洗

这个技能是一个智能的“研究记录考古学家”。它会在你指定的目录（通常是项目根目录或用户主目录）中深度挖掘，寻找主流AI编码代理留下的“遗迹”，并将它们整合成PaperOrchestra所需的格式。

第一阶段：发现 (Discovery)

• 工具：discover_logs.py(确定性脚本)
• 动作：该脚本会扫描--search-roots参数指定的目录，递归查找特定子目录和文件模式，例如：
  • .claude/projects/*/memory/*.md和CLAUDE.md(Claude Code)
  • .cursor/chat/chatHistory.json和.cursorrules(Cursor)
  • .antigravity/workers/*/log.jsonl和output.md(Antigravity)
  • .openclaw/sessions/*/conversation.md(OpenClaw)
• 输出：一份discovered_logs.json文件，仅包含文件路径、大小、修改时间等元数据，不读取内容。脚本会先打印一份摘要供你审阅，确认扫描范围无误后，才会进入下一阶段。这避免了意外读取敏感或无关文件。

第二阶段：提取 (Extraction)

• 工具：LLM (由宿主代理执行)
• 动作：宿主AI代理会读取discovered_logs.json，并按照references/extraction-prompt.md中的详细指令，分批处理这些日志文件。提示词会指导AI从杂乱的对话历史中，识别出“实验设置”、“代码修改”、“运行命令”、“结果输出”、“错误信息”、“研究者的决策和评论”等关键信息，并将其结构化为raw_experiments.json。
• 关键处理：在此过程中，AI会主动剥离可能的个人身份信息（PII），并对所有未被原始日志明确验证的数值结果（例如，AI自己推算的指标）标记为[UNVERIFIED]，确保最终报告的真实性。

第三阶段：合成 (Synthesis)

• 工具：LLM (由宿主代理执行，通常只需一次调用)
• 动作：将第二阶段提取出的、可能重复或碎片化的实验记录，合并成一个连贯的、按时间或主题组织的“研究叙事”。生成synthesis.json。这个步骤非常关键，它能识别出一次探索中的多个分支，或者判断扫描到的日志是否属于多个不相关的项目。如果发现多个独立项目，聚合器会暂停并询问用户，应该聚焦于哪一个。

第四阶段：格式化 (Formatting)

• 工具：format_po_inputs.py(确定性脚本)
• 动作：将synthesis.json转换成两个最终文件：
  1. idea.md: 符合论文中定义的“稀疏想法”格式，简明扼要地描述研究问题、核心方法和预期贡献。
  2. experimental_log.md: 一份结构清晰的实验日志，包含环境配置、每个实验的具体步骤、参数、结果和观察结论，格式参考论文附录D.3。

3.2 实战配置与操作指南

假设你的研究项目存放在~/projects/my_ai_research，并且你混合使用了Claude Code和Cursor。

步骤一：安装与链接技能首先，克隆仓库并安装基础依赖（只是一些Python工具库）。

git clone https://github.com/ar9av/PaperOrchestra.git ~/paper-orchestra cd ~/paper-orchestra pip install -r requirements.txt

然后，将技能链接到你的AI代理的技能目录。以Claude Code为例：

# 创建技能目录（如果不存在） mkdir -p ~/.claude/skills # 链接聚合器技能 ln -sf ~/paper-orchestra/skills/agent-research-aggregator ~/.claude/skills/agent-research-aggregator # 同时链接主流程技能，以备后用 ln -sf ~/paper-orchestra/skills/paper-orchestra ~/.claude/skills/paper-orchestra

对于Cursor、Antigravity等其他代理，你需要查看skills/paper-orchestra/references/host-integration.md找到对应的技能目录路径。

步骤二：启动聚合流程现在，你可以在Claude Code的聊天界面中，直接使用自然语言触发：

“请聚合我在~/projects/my_ai_research目录下的所有AI代理日志，为写论文做准备。”

或者更直接：

“将~/projects/my_ai_research中的实验整理成PaperOrchestra的输入。”

AI代理会识别到这个技能，并开始自动执行上述四阶段流程。你也可以手动分步执行以获得更多控制权：

# 1. 仅执行发现阶段，看看会找到什么 cd ~/projects/my_ai_research python ~/paper-orchestra/skills/agent-research-aggregator/scripts/discover_logs.py \ --search-roots . \ --agents claude,cursor \ --out ./workspace/ara/discovered_logs.json # 查看发现报告 cat ./workspace/ara/discovered_logs.json | python -m json.tool | head -50

步骤三：审查与确认聚合器完成工作后，务必仔细审查workspace/inputs/目录下生成的idea.md和experimental_log.md。这是你纠正AI误解、补充关键信息、确保研究故事主线清晰的最佳时机。你可以手动编辑这两个文件，然后再交给主流程。

实操心得：聚合器的效果很大程度上取决于你平时使用AI代理的习惯。如果能在对话中更结构化地描述实验（例如，明确分隔“目标”、“方法”、“结果”、“结论”），提取和合成的质量会显著提升。建议在重要的实验步骤后，主动让AI助手帮你总结一下，这相当于为未来的“考古”埋下了清晰的标记。

4. 核心写作流程详解与配置

当你的workspace/inputs/目录下准备好了idea.md,experimental_log.md,template.tex（会议LaTeX模板）和conference_guidelines.md（页数、格式要求）后，真正的自动化写作交响曲就可以开始了。

4.1 初始化工作区与输入准备

首先，使用提供的脚本初始化一个标准的工作区结构。这个结构是所有技能共享的“上下文环境”。

python ~/paper-orchestra/skills/paper-orchestra/scripts/init_workspace.py --out ./workspace

这会在当前目录创建workspace文件夹，其内部结构如下：

workspace/ ├── inputs/ │ ├── idea.md # 必须：你的研究想法 │ ├── experimental_log.md # 必须：你的实验日志 │ ├── template.tex # 必须：目标会议/期刊的LaTeX模板 │ ├── conference_guidelines.md # 必须：格式要求（字数、截止日期等） │ └── figures/ # 可选：已有的图片（如照片、示意图） ├── outputs/ # 最终产出目录 │ ├── draft_v1.tex │ ├── draft_v1.pdf │ └── figures/ # 生成的图表会放在这里 ├── intermediate/ # 中间文件（提纲、草稿等） └── logs/ # 运行日志

你需要手动将后四个文件放入inputs/。idea.md和experimental_log.md可以来自聚合器，也可以是你手动编写的。conference_guidelines.md文件很简单，例如：

# Conference: NeurIPS 2025 - Page limit: 8 pages main content, unlimited for references and appendix. - Deadline: May 15, 2025, 23:59 UTC. - Required sections: Abstract, Introduction, Related Work, Method, Experiments, Conclusion. - Blind review: Yes. Do not include author names in the draft.

4.2 运行完整管道与监控

初始化完成后，在你的AI编码代理界面中，只需输入一条指令：

“在./workspace目录上运行 paper-orchestra 管道。”

协调者技能 (paper-orchestra) 会被激活。它会按以下逻辑执行：

1. 检查输入：验证inputs/下的必要文件是否存在且格式大致正确。
2. 调用提纲智能体：生成详细的论文提纲JSON，存入intermediate/outline.json。
3. 并行触发绘图与文献智能体：
   • 绘图智能体读取intermediate/outline.json中的plotting_plan，开始生成图表。它会优先检查是否配置了PAPERBANANA_PATH环境变量。如果配置了，则调用PaperBanana生成高质量示意图；否则，使用matplotlib生成基础图表。所有生成的图表（.png,.pdf）和对应的LaTeX代码块会保存在outputs/figures/和intermediate/plots.json。
   • 文献智能体读取literature_review_plan，开始进行网络搜索和Semantic Scholar验证。搜索到的文献会以BibTeX格式保存在intermediate/citations.bib，而撰写的“引言”和“相关工作”章节草稿则保存在intermediate/litreview_draft.tex。
4. 调用章节写作智能体：等步骤3的两部分都完成后（协调者会检查完成标志），该智能体将提纲、图表、文献草稿、实验日志整合，撰写论文主体部分，产出第一版完整草稿outputs/draft_v1.tex。
5. 调用内容精炼智能体：对draft_v1.tex进行多轮润色。每一轮的修改建议和最终是否接受的决策，都会记录在logs/refinement.log中。最终的精炼稿可能保存为outputs/draft_v2.tex。
6. 最终编译：协调者会尝试使用pdflatex和biber/bibtex编译最终的.tex文件，生成PDF。如果编译失败，它会将错误信息记录在案，并将未编译的.tex和.bib文件交给用户处理。

在整个过程中，你的角色是“监督者”。你可以随时查看intermediate/和logs/目录下的文件，了解进度。例如，查看intermediate/outline.json可以确认AI对你研究的理解是否准确；查看logs/plotting_agent.log可以知道图表生成是否遇到了问题。

4.3 可选集成配置：提升效率与质量

为了让管道运行得更顺畅、产出质量更高，可以考虑以下三个可选的集成配置：

1. Semantic Scholar API 密钥文献综述智能体默认使用Semantic Scholar的公共API端点，但有严格的速率限制（每秒1次请求）。对于需要引用大量文献的论文，这会导致进程频繁等待。

• 获取：前往 Semantic Scholar API 注册获取免费API密钥。
• 配置：只需设置一个环境变量。

  export SEMANTIC_SCHOLAR_API_KEY="your_actual_key_here"

• 验证：运行python skills/literature-review-agent/scripts/s2_search.py --check-key，如果显示Using authenticated API则配置成功。配置后，速率限制会大幅放宽，能显著加快文献检索速度。

2. PaperBanana 图表生成引擎这是原论文中使用的绘图后端，能生成更具“学术感”的示意图。它通过检索真实论文中的图表，学习其风格和构图，来生成新的图表。

• 安装：

  git clone https://github.com/dwzhu-pku/PaperBanana cd PaperBanana pip install -r requirements.txt cp configs/model_config.template.yaml configs/model_config.yaml # 编辑 configs/model_config.yaml，填入你的Google Gemini API Key或OpenRouter API Key

• 配置：设置环境变量指向PaperBanana的安装路径。

  export PAPERBANANA_PATH="/full/path/to/PaperBanana"

• 效果：配置后，绘图智能体在生成概念图、框架图时会自动调用PaperBanana，产出质量远高于简单的matplotlib绘图。对于数据曲线图，它仍然会使用matplotlib以确保精度。

3. Exa 搜索增强如果你的宿主代理没有内置的、高质量的网络搜索功能，或者你想获得更聚焦于学术论文的搜索结果，可以集成Exa搜索。

• 获取：前往 Exa.ai 注册，获取API密钥（有免费额度）。
• 配置：

  export EXA_API_KEY="your_exa_key_here"

• 机制：配置后，文献智能体的exa_search.py脚本会被启用，它专门搜索category: "research paper"的内容，返回的结果更相关，格式也更规整。如果你的宿主代理（如Claude Code）已有很好的搜索功能，则无需此配置。

注意事项：这些集成都是“锦上添花”。没有它们，管道依然可以运行。建议初次使用时先采用默认配置跑通流程，理解每个环节，再根据需求逐步添加集成，以降低调试复杂度。

5. 常见问题、排查技巧与深度优化

即使设计再精良，在实际操作中也会遇到各种问题。以下是我在多次使用和测试中积累的常见问题排查清单和深度优化建议。

5.1 流程执行失败与排查

5.2 输入质量决定输出上限：如何准备优质的idea.md和experimental_log.md

这是整个系统中最关键的一环。垃圾进，垃圾出。你的输入越清晰、越结构化，AI的理解和发挥就越好。

idea.md撰写要点：不要写成冗长的段落。参考论文中的“稀疏想法”格式，力求简洁、结构化。

# Sparse Idea: [你的项目名称] ## Core Problem 当前在[某个领域]中，存在[什么问题]。现有的方法如[方法A]和[方法B]在[某方面]有局限（例如，计算效率低、无法处理长上下文、可解释性差）。 ## Proposed Approach 我们提出[你的方法名称]，其核心是[用一两句话概括创新点]。具体来说，我们通过[技术手段1]和[技术手段2]来实现[目标]。 ## Expected Contribution 1. **性能提升**：在[标准数据集]上，预期比基线方法[方法A]在[指标X]上提升Y%。 2. **效率改进**：我们的方法将时间复杂度从O(n^2)降低到O(n log n)。 3. **新的洞察**：我们发现[某个现象]，这为理解[某个问题]提供了新视角。

experimental_log.md撰写要点：按时间或主题组织，像实验室记录本一样详细。

# Experimental Log: [项目名称] ## Environment Setup - Python 3.9, PyTorch 2.0, CUDA 11.7. - 所有实验在单张NVIDIA A100 (40GB)上运行。 ## Experiment 1: Baseline Reproduction (2024-10-26) **Objective**: 复现对比方法[方法A]在数据集[D]上的结果。 **Procedure**: 1. 克隆官方仓库，安装依赖。 2. 按照README，运行训练命令：`python train.py --dataset D --model A`. 3. 记录最终测试集准确率。 **Results**: 获得准确率75.2%，与论文报告的75.5%基本一致。 **Observations**: 训练过程稳定，但显存占用较高（约32GB）。 ## Experiment 2: Our Method - Ablation on Component X (2024-10-27) **Objective**: 验证我们方法中组件X的必要性。 **Procedure**: 1. 在实验1的代码基础上，移除组件X。 2. 保持其他所有超参数不变，重新训练。 3. 对比完整模型与消融模型的验证集损失曲线和最终准确率。 **Results**: 移除组件X后，准确率下降至70.1%。验证集损失收敛更慢。 **Conclusion**: 组件X对我们的方法有显著正面贡献。

5.3 高级技巧与个性化定制

1. 干预与引导：你不必完全放任自流。在流程执行到intermediate/阶段时，你可以审阅生成的文件。例如，如果你对outline.json中的“相关工作”部分规划不满意，可以直接修改这个JSON文件，然后再让流程继续。协调者技能会以最新的中间文件为准。

2. 利用paper-autoraters进行自我评估：在最终成稿后，你可以手动运行paper-autoraters技能，让它用论文中定义的量化指标给你的生成稿打分。这能给你一个相对客观的质量参考，尤其是对比不同版本草稿时。

# 假设你的最终稿是 outputs/final_paper.tex # 告诉你的AI代理：“对 workspace/outputs/final_paper.tex 运行 paper-autoraters 评分。”

3. 自定义提示词（进阶）：如果你对某个智能体的输出风格有特殊要求（比如希望引言更批判性，或者图表配色符合某个会议主题），你可以直接修改对应技能references/目录下的prompt.md文件。但请注意，这是对原论文方案的直接修改，可能会影响整体流程的协调性。建议先备份原文件，并小范围测试。

4. 处理大型项目：如果你的实验日志非常大（超过10万行），聚合器和后续的LLM调用可能会超时或超出上下文长度。此时，可以：

• 在聚合阶段使用--since参数，只聚合最近一段时间的日志。
• 手动将experimental_log.md拆分成几个核心实验，而非事无巨细地记录所有调试过程。AI更需要的是“故事主线”和“关键证据”。

这个工具链解放了研究者从繁琐的文书工作中，让我们能更专注于研究本身。它不是一个替代思考的“论文生成器”，而是一个强大的“研究表达放大器”。