PaperOrchestra workspace输入输出契约详解:从inputs到final/paper.pdf全流程图解

原创2026-11-02 20:26:19508 阅读

PaperOrchestra workspace输入输出契约详解:从inputs到final/paper.pdf全流程图解

PaperOrchestra 是一款可插拔的自动化 AI 论文写作框架:它让 Claude Code、Cursor、Cline 等任意 coding agent 扮演"乐队指挥",把 workspace/inputs/ 下的 idea、实验日志、LaTeX 模板一路加工成可投稿的 final/paper.pdf。本文详解 PaperOrchestra 的 workspace 输入输出契约(I/O Contract)——每一步读取什么、产出什么、哪些文件必须存在、最终 PDF 如何被"晋升"到 final 目录,带你完整看懂这条从 inputs 到 final/paper.pdf 的文件流转链路。

PaperOrchestra 多智能体自动写论文框架(Google 论文首页预览)

一、PaperOrchestra 是什么:五智能体自动写论文管线

PaperOrchestra 是 Google 论文(arXiv:2604.05018)的工程化实现:一套 skills 技能包 + 确定性脚本,把"写论文"拆成 5 个可独立执行的智能体步骤:

步骤 智能体 职责 LLM 调用
Step 1 outline-agent 输入四件套 → 结构化大纲 outline.json 1 次
Step 2 plotting-agent 按大纲生成全部图表 + caption ~20–30 次
Step 3 literature-review-agent 检索/核验文献,写 Intro + Related Work ~20–30 次
Step 4 section-writing-agent 一次多模态调用写完正文、表格、插图 1 次
Step 5 content-refinement-agent 模拟同行评审,迭代润色 ≤3 轮 ~5–7 次

💡 核心设计:无 API Key、无 LLM SDK。所有需要推理的工作交给宿主 coding agent 自己完成;仓库里的 Python 脚本只做 schema 校验、Levenshtein 匹配、引用门禁等确定性工作。全流程约 60–70 次 LLM 调用、40 分钟左右产出一篇完整论文。

二、workspace 目录结构:一张图看懂输入输出契约

PaperOrchestra 的全部约定都写在 skills/paper-orchestra/references/io-contract.md 中。workspace 布局是整条管线的"总地图":

workspace/
├── inputs/                 # ← 用户提供的输入(契约起点)
│   ├── idea.md             #     I — 研究想法(Sparse 或 Dense 变体)
│   ├── experimental_log.md #    E — 实验日志:设置、原始数据、观察
│   ├── template.tex        #     T — 目标会议的 LaTeX 模板
│   ├── conference_guidelines.md # G — 页数、格式、截止日期
│   └── figures/            #     F — 可选:已有图(PNG/PDF)
├── outline.json            # ← Step 1 输出:绘图计划 + 文献计划 + 章节计划
├── figures/                # ← Step 2 输出:生成的图 + captions.json
├── refs.bib                # ← Step 3 输出:核验过的 BibTeX
├── citation_pool.json      # ← Step 3 输出:Semantic Scholar 元数据
├── drafts/
│   ├── intro_relwork.tex   # ← Step 3 输出:Intro + Related Work
│   └── paper.tex           # ← Step 4 输出:完整初稿
├── refinement/             # ← Step 5 工作目录:worklog.json + iter1~3/
├── final/                  # ★ 最终交付物
│   ├── paper.tex
│   └── paper.pdf
└── provenance.json         # 输入/输出哈希,用于复现

📁 一句话总结契约:inputs/ 是"因",final/ 是"果",中间每一个目录对应一个智能体的产物,文件与路径固定不变,agent 才能可靠地接力。

三、inputs 输入契约:四件套的填写规范

四个必需文件(论文中记作 I、E、T、G)各有一条硬性规范:

文件 关键契约
idea.md (I) 必须含 4 节:Problem Statement / Core Hypothesis / Proposed Methodology / Expected Contribution;支持 Sparse(无公式概念笔记)与 Dense(保留公式)两种变体
experimental_log.md (E) 严格三段式:Setup → Raw Numeric Data(markdown 表格)→ Qualitative Observations;禁止出现 "Table 1 / Fig. 5" 之类的图号引用;数字必须 100% 准确——它们是 Step 5 幻觉检查的 ground truth
template.tex (T) 带空 \section{...} 占位符的会议模板;Section Writing Agent 会原地填充正文、逐字保留导言区
conference_guidelines.md (G) 页数上限、必备章节、单双栏格式、截止日期(后者会变成文献检索的 cutoff_date)

✅ 仓库自带两个可直接对照的输入样例:最小玩具案例 examples/minimal/inputs/(9 页限制、含 cutoff 日期),以及一个跑通 22 页真实白皮书的完整案例 examples/agentic-security-report/inputs/。

四、五步流水线:每步读取什么、产出什么

下图就是 Step 2(Plotting Agent)的真实产物示例——它不依赖任何外部素材,完全从 experimental_log.md 的表格数据自动渲染出 300 DPI 论文级图表,并写入 workspace/figures/:

PaperOrchestra workspace/figures 产物示例:由 experimental_log.md 数据自动生成的市场增长图

4.1 Step 1:Outline → outline.json

Outline Agent 只花 1 次 LLM 调用,把四件套压缩成结构化 outline.json,内含三个计划块:

  • plotting_plan:每张图的 figure_id、plot_type(plot/diagram)、数据源、aspect_ratio
  • intro_related_work_plan:文献检索方向 + 相关工作聚类
  • section_plan:正文章节骨架

输出必须通过 skills/outline-agent/scripts/validate_outline.py 的 JSON Schema 校验(schema 见 skills/outline-agent/references/outline_schema.json),校验失败则整条管线立即中止——因为所有下游 agent 都依赖这份大纲。

4.2 Step 2 ∥ Step 3:并行双分支

outline.json 一产出,两条互不依赖的分支立即并行:

  • 分支 A(Plotting):按 plotting_plan 逐图渲染 → figures/<figure_id>.png + figures/captions.json(caption 为纯文本,无 "Figure N:" 前缀,由 Step 4 拼入 \caption{})
  • 分支 B(Lit Review):并行发现候选文献 → Semantic Scholar 逐条核验(Levenshtein 相似度 > 70、日期 cutoff、按 paperId 去重)→ 产出 refs.bib + citation_pool.json + drafts/intro_relwork.tex,且引用整合率 ≥90%

⚠️ 若宿主不支持并行,先跑 Step 3——它的耗时下限被 Semantic Scholar 的 1 QPS 限速锁死(详见 skills/paper-orchestra/references/pipeline.md)。

Step 2 的产物是"数据 → 图"契约的直接体现,这张能力覆盖热力图完全由表格数据驱动生成:

PaperOrchestra plotting agent 从实验日志表格数据自动生成的能力覆盖热力图

4.3 Step 4:Section Writing → drafts/paper.tex

这是整条管线最"惊艳"的一步:单次多模态 LLM 调用同时接收 outline、idea、实验日志、已写好的 Intro/RelWork、refs.bib 指南和 figures/ 里的真实图片文件,一次性完成:

  1. 从实验日志提取数字,构建 booktabs 表格(数值逐字复制,不得改写)
  2. 撰写 Abstract / Method / Experiments / Conclusion
  3. 将生成的图片拼入正文(\includegraphics + \ref),caption 取自 captions.json
  4. 保留 Step 3 写好的 Intro + Related Work 原文

下图即 Step 4 拼入正文的架构图(其"绘图蓝图"早在 Step 1 的 plotting_plan 中就已定义):

PaperOrchestra 生成的系统架构图,由 Step 4 Section Writing Agent 拼入 paper.tex 正文

写完即过四道确定性门禁:孤儿引用检查(每个 \cite{KEY} 必须存在于 refs.bib)、LaTeX 括号/环境 sanity、防泄漏 grep、数字声明证据门禁(claim-evidence gate)。任一硬门禁失败,必须修复后才允许进入 Step 5。

五、final/paper.pdf 如何产生:Step 5 评审循环与晋升规则

drafts/paper.tex 还不算终点。Content Refinement Agent 进入 ≤3 轮"模拟同行评审"循环:打分 → 针对弱点修改 → 重新打分 → 按 halt 规则决定 accept 或回滚:

ACCEPT  若  new > prev
ACCEPT  若  new == prev 且 子轴净变化 >= 0
REVERT  其他情况(回滚到上一轮快照)
  • 每轮在 refinement/iter<N>/ 留下真实文件快照(paper.tex / paper.pdf / review.json / score.json),全程记录在 refinement/worklog.json
  • 触发任一 halt 条件(达到轮数上限 / 总分下降 / 平分但子轴净负 / 无新弱点)即终止
  • 终止时评分最高的快照被"晋升"复制为 final/paper.tex,再用 latexmk -pdf 编译出 final/paper.pdf
  • 最后写入 provenance.json:输入文件、outline、refs、图、最终 tex/pdf 的 SHA-256 哈希,保证整条链路可复现

规则细节见 skills/content-refinement-agent/references/halt-rules.md。真实案例中该循环把评分从 71.85 一路提升到 77.70,甚至额外新增了一张图——润色 agent 不只是改文字。

六、快速上手:从零跑通 inputs → final/paper.pdf 全流程

# 1. 克隆并安装(仅确定性脚本依赖)
git clone https://gitcode.com/gh_mirrors/pa/PaperOrchestra
cd PaperOrchestra
pip install -r requirements.txt

# 2. 搭建 workspace 骨架
python skills/paper-orchestra/scripts/init_workspace.py --out workspace/

# 3. 把你的四件套放入 workspace/inputs/,然后校验
python skills/paper-orchestra/scripts/validate_inputs.py --workspace workspace/

# 4. 对你的 coding agent 说:
#    "Run the paper-orchestra pipeline on ./workspace"

🚀 跑完后,workspace/final/paper.pdf 就是可投稿的成品。想先验证脚本链路而不消耗 LLM 调用,可直接参考 examples/minimal/README.md 里的 smoke test 流程。

七、关键文件路径速查

想了解什么 看这里
完整 I/O 契约(输入 schema + 中间产物 schema) skills/paper-orchestra/references/io-contract.md
编排器执行顺序与门禁 skills/paper-orchestra/SKILL.md
管线数据流图 + 并行规则 docs/architecture.md
逐步流水线与 halt 规则 skills/paper-orchestra/references/pipeline.md
最小可运行输入样例 examples/minimal/inputs/
跑通后的预期 workspace 目录树 examples/minimal/expected-workspace-tree/README.md
22 页真实白皮书的完整执行记录 examples/agentic-security-report/README.md
设计决策与论文原文页码对照 docs/paper-fidelity.md

📌 总结:PaperOrchestra 的输入输出契约本质是一份"文件系统级 API"——inputs/ 四件套是入参,outline.json、figures/、refs.bib、drafts/paper.tex 是过程返回值,final/paper.pdf + provenance.json 是最终交付物。只要记住这张地图,你就能精准定位管线卡在哪一步、该补哪个文件。

登录后查看全文
PaperOrchestra