PaperOrchestra workspace输入输出契约详解:从inputs到final/paper.pdf全流程图解
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 是什么:五智能体自动写论文管线
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/:
4.1 Step 1:Outline → outline.json
Outline Agent 只花 1 次 LLM 调用,把四件套压缩成结构化 outline.json,内含三个计划块:
plotting_plan:每张图的figure_id、plot_type(plot/diagram)、数据源、aspect_ratiointro_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 的产物是"数据 → 图"契约的直接体现,这张能力覆盖热力图完全由表格数据驱动生成:
4.3 Step 4:Section Writing → drafts/paper.tex
这是整条管线最"惊艳"的一步:单次多模态 LLM 调用同时接收 outline、idea、实验日志、已写好的 Intro/RelWork、refs.bib 指南和 figures/ 里的真实图片文件,一次性完成:
- 从实验日志提取数字,构建 booktabs 表格(数值逐字复制,不得改写)
- 撰写 Abstract / Method / Experiments / Conclusion
- 将生成的图片拼入正文(
\includegraphics+\ref),caption 取自captions.json - 保留 Step 3 写好的 Intro + Related Work 原文
下图即 Step 4 拼入正文的架构图(其"绘图蓝图"早在 Step 1 的 plotting_plan 中就已定义):
写完即过四道确定性门禁:孤儿引用检查(每个 \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 是最终交付物。只要记住这张地图,你就能精准定位管线卡在哪一步、该补哪个文件。



