OpenResearch 论文写作技能 orx-paper 深度解析：让 Agent 产出可编译的 LaTeX 学术论文

OpenResearch 论文写作技能 orx-paper 深度解析：让 Agent 产出可编译的 LaTeX 学术论文

【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch

本指南系统讲解 OpenResearch 中负责学术论文撰写的 Agent 技能orx-paper：它规定 Agent 必须以真实.tex文件落地论文、在写导言前检查用户上传的模板、使用一份保证能编译的 LaTeX 导言区，并正确选择编译引擎与参考文献方案。读完本文，你将掌握orx-paper从"首次请求建文件"到"编译失败排错"、再到"Overleaf 双向同步"的完整工作流，同时理解其背后的源码级实现（src/local/latex.rs 的引擎调度与 src/commands/paper.rs 的文献读取），能够在实际项目中产出可渲染、可编译、可投稿的论文草稿。

一、技能定位：论文（orx-paper）与报告（orx-reports）的边界

orx-paper（定义于 agent-skills/orx-paper/SKILL.md）是 OpenResearch 面向 Agent 的一组技能模块之一。它的 frontmatter 明确定义了适用场景：

Draft an academic paper or preprint as LaTeX. Use for a paper, preprint, manuscript, arXiv or submission draft, or a section of one; generic reports and result summaries belong toorx-reports.

也就是说，论文、预印本、手稿、arXiv/投稿草稿或其中某个章节，走orx-paper；而通用报告和结果总结，属于 orx-reports。两者最核心的差异是输出位置与生命周期：

这条边界在 orx-figures 中被进一步强调：引用标签必须与目标位置匹配——一个写进工作树却被以artifacts/前缀引用的图片，会在两个根目录里都找不到，用户点击即得 "File not found"。这也是orx-paper第一条纪律的由来：.tex必须放在工作树中就地编译，绝不能放进 artifacts 目录。

二、首次请求就创建文件：拒绝"聊天框大纲"

orx-paper的第一条硬性规则是：

Write the paper as a real.texfile in the working tree. Do not answer a paper request with an outline in chat.

即：不能只给用户一个大纲。论文必须落地为真实的.tex文件：

• 仓库根目录创建paper.tex；当多个论文并存时，使用<topic>.tex命名区分；
• 写入真实内容后，按会话剧本（session playbook）的 evidence-and-links 契约在聊天中给出链接，让用户能直接打开渲染后的文档——聊天里的大纲没有任何可渲染的东西；
• 若用户希望把可复用模板沉淀为 OpenResearch 的公共资产，应加载 orx-customize 技能（对应orx templates add命令）。

三、写导言之前，先检查模板

用户可能已经上传了自己的 LaTeX 模板——会议类（conference class）或实验室预印本风格。动手写任何导言之前必须检查：

ls .orx/latex-templates/

处理规则分三种情况：

• 恰好一个模板→ 直接使用，不要反问（它被上传就是用来用的）；
• 多个模板→ 逐个点名并询问用哪个，除非请求里已经说明；
• 没有模板→ 使用下文第四节给出的默认导言。

选中模板后，把它的类文件和样式文件复制到.tex旁边，让编译器能找到它们，并从模板入口.tex起步而非默认导言：

cp .orx/latex-templates/<name>/*.cls .orx/latex-templates/<name>/*.sty \ .orx/latex-templates/<name>/*.bst . cp .orx/latex-templates/<name>/<entry>.tex paper.tex

然后只填充模板自身的结构：保留它的\documentclass行、包列表和章节骨架，只替换占位内容。会议类编码了投稿审查会用到的页边距、字体与匿名化模式，覆盖它就违背了上传模板的初衷。若模板需要机器上缺失的宏包，应明确说出来，而不是悄悄退回默认导言。

从源码看，模板目录不是临时约定，而是有专门实现支撑：会话目录常量SESSION_DIR_REL = ".orx/latex-templates"定义于 src/local/latex_templates.rs，全局模板则存储在data_dir()/latex-templates/global/<name>/；src/local/opencode.rs 会将该目录注入会话环境。同时，src/local/skills.rs 里嵌入的同名规则再次确认："Check.orx/latex-templates/before writing a preamble"——这说明"先查模板"是写进 Agent 运行时行为的一致约束，而非文档单方面的建议。

四、一份保证能编译的导言区（默认模板）

没有用户模板时，orx-paper提供以下起点，它覆盖了后文所有小节会用到的宏包：

\documentclass[11pt]{article} \usepackage[margin=1in]{geometry} \usepackage{amsmath,amssymb,amsthm} \usepackage{graphicx} \usepackage{booktabs} \usepackage{listings} \usepackage{natbib} \usepackage[hidelinks]{hyperref} \newtheorem{theorem}{Theorem} \newtheorem{lemma}[theorem]{Lemma} \title{...} \author{...} \date{\today} \begin{document} \maketitle ... \end{document}

4.1 环境与宏包依赖对照

文档强调：每个环境都需要定义它的宏包——这是草稿编译失败最常见的原因，而且是致命失败而非外观问题：

原则只有两条：只加载你实际用到的宏包；绝不发明一个没有定义的宏。

五、引擎选择：用魔法注释声明，而不是靠猜

论文默认以pdfLaTeX编译。如果文档需要 XeLaTeX 或 LuaLaTeX——例如fontspec、unicode-math、系统 OpenType 字体——必须在文件第一行声明，否则会被错误的引擎构建并失败：

% !TeX program = lualatex

没有这种需求就不要加这行：pdfLaTeX 是支持最广的引擎，且microtype的字距调整（letter tracking）只在 pdfLaTeX 下生效。

5.1 源码侧：引擎注释是如何被读取的

这一约定在 src/local/latex.rs 中有精确实现。program_from_source()只扫描文件前 16 行（常量PROGRAM_COMMENT_LINES = 16），避免正文深处的文本被误判为头部指令；它同时接受% !TeX program与% !TEX TS-program两种写法（大小写不敏感），因为真实论文里两种都常见，并正确跳过堆叠在引擎行之前的% !TeX root、% !BIB program等指令。

其测试用例（the_program_comment_is_read_in_the_forms_authors_actually_write）覆盖了%% !tex program=pdflatex、% !TeX program = XeLaTeX等变体，以及"指令埋在第 16 行之后应被忽略"的边界情况。Program枚举（Pdf/Xe/Lua）把引擎名与 latexmk 标志对应起来：-pdf/-xelatex/-lualatex，与 Overleaf 的引擎命名一致。

5.2 驱动器的优先级：latexmk → 直接驱动 → tectonic

src/local/latex.rs 的choose_driver()按以下顺序挑选编译驱动器：

1. latexmk：当latexmk与文档所需引擎二进制都可用时优先——它自动选引擎、跑 biber/bibtex、重复多遍直到引用收敛，这正是 Overleaf 的行为，因此注释里写"目标是 Overleaf parity"；
2. 直接驱动引擎：没有 latexmk 时直接调用pdflatex/xelatex/lualatex，由 OpenResearch 自己编排文献工具与重复遍数；
3. tectonic：只剩 tectonic 时使用它，但会在结果中明确备注——因为 tectonic 本质是 XeTeX，无法忠实处理声明为 LuaLaTeX 的文档（见served_by_tectonic()与Compilation.note字段）。

每个驱动器的编译参数都经过安全性设计：

• latexmk：-norc（禁止执行 checkout 里可能存在的.latexmkrc）、-interaction=nonstopmode（非交互，避免文档卡在?提示符）、-no-shell-escape（Agent 编写的源文件一律关闭 shell escape）；
• 直接驱动：同样-interaction=nonstopmode、-no-shell-escape；
• tectonic：--keep-logs与-Z continue-on-errors（否则 microtype 在 XeTeX 下那句 "switching it off" 恢复性错误会被 tectonic 当作致命错误，连 PDF 都不产出）。

源码甚至对"恶意文件名"做了防御：源文件以./前缀传入（./paper.tex），测试a_hostile_file_name_cannot_become_options_or_tex_source验证-output-directory=x.tex、\immediate\write18{sh}.tex这类名字永远不会变成命令行选项或 TeX 源码。

六、正文结构：抽象、小节、交叉引用

orx-paper对正文结构的要求围绕可交叉引用展开：

• 以\begin{abstract}开头，正文使用\section/\subsection；
• 引用到的公式要编号：\begin{equation}\label{eq:loss}并用\eqref{eq:loss}引用；从不引用的公式用带星号的形式；
• 每个浮动体都要加\label，并用Table~\ref{tab:main}这类形式引用，绝不写"the table below"——浮动体会移动，位置描述不可靠。

七、图表：先读 orx-figures，再引用真实存在的文件

论文里的图不是 matplotlib 默认输出就能应付的。orx-paper明确要求：做图之前先读orx-figures模块（agent-skills/orx-figures/SKILL.md）。默认 matplotlib 图直接放进论文会被审稿人点名批评：物理尺寸错误、标题画在标题该在的地方（应该用 caption）、以及文档需要矢量时却用了位图。

图片文件必须真实存在于树中，并按相对.tex的路径引用：

\includegraphics[width=\linewidth]{figs/loss_curve.pdf}

写全扩展名，引用前确认文件存在——缺失的图片会导致构建失败。

orx-figures还补充了图表落位与引用的完整约定：论文图写入.tex旁边的figs/，并在聊天中以<file path="figs/loss_curve.pdf" />（仓库相对、无artifacts/前缀）引用；同时坚持"按最终印刷尺寸制图 + 仍然写width=\linewidth"的双保险——尺寸正确时\linewidth缩放系数为 1.0 不改变任何东西，但若会场的栏宽与假设不符它依然能自适应。width=\linewidth唯一救不了的是按错误尺寸制出的图：15 英寸画布被缩进 5.5 英寸栏宽，缩放 0.35 后 11pt 刻度标签只剩 4pt，这是真实论文图表不可读的头号原因。

八、参考文献：单遍编译的内联 thebibliography

orx-paper的参考文献方案以单遍编译为前提：

\begin{thebibliography}{9} \bibitem[Kaplan et al.(2020)]{kaplan2020} Kaplan et al. Scaling laws for neural language models. 2020. \end{thebibliography}

• 内联thebibliography一次编译即收敛；而\bibliography{refs}配独立.bib需要 biber 往返，在那之前显示为未解析引用；
• [Author(Year)]标签是\citet打印名字的依据——没有它 natbib 就没有名字可用。每个条目都必须给；对于不知道作者是谁的论文，用短标题而不是编造作者名。

8.1 引用命令的选择：\citet vs \citep

按句子的读感选引用命令：

• \citet{kaplan2020}—— 引用是主语：Kaplan et al. (2020) show…
• \citep{kaplan2020}—— 括号附带说明：…is predictable (Kaplan et al., 2020)
• natbib 下普通\cite行为等同\citet，所以GRPO~\cite{x}会输出 "GRPO Shao et al. (2024)"（无括号）——想用作附带说明就写\citep。

8.2 真实文献从哪来：orx-lit-review 工作流

编造的引用比没有引用更糟。找真实参考文献要走 orx-lit-review 工作流：先用orx discover（支持keyword、embedding、openalex、biorxiv四种原语，可加--published-after/--published-before与--prioritize排序控制）检索候选，再用orx paper精读选中的来源。

orx paper的读取能力在 src/commands/paper.rs 有完整实现：detect_source()从 id 形态自动判定来源——biorxiv.org/openalex.org主机提示优先，10.1101/…DOI 归 bioRxiv，其他 DOI 或裸W…id 归 OpenAlex，其余（arXiv id/URL）默认 alphaXiv。其测试特意覆盖了"10 月 arXiv id（如2410.12345、1810.04805）含子串10.但无斜杠，绝不能被误判为 DOI"这类边界；parse_paper_id()则把arxiv.org/abs/…、arxiv.org/pdf/….pdf、alphaxiv.org/overview/…等形态归一化为规范 id。默认返回 alphaXiv 的紧凑结构化报告（约 10KB），报告缺失时自动回退到抽取全文，--full可强制读取原文；用户禁用的文献源在读取时同样生效（ensure_source_enabled）。

九、结果必须来自运行日志，而非记忆

Every number in a results table must come from an actual run.

结果表里的每一个数字都必须来自真实运行——用orx logs读取（见 orx-evidence 技能）。绝不写一个看起来像真实指标的占位符；如果某个数字还没测出来，就在正文里明说。

orx-evidence给出了完整的日志读取命令集：

orx logs <runId> # tail（末尾——通常是你想要的） orx logs <runId> --head # 从头读 orx logs <runId> --bytes 200000 # 提高字节上限（默认 64 KB，最大 1 MB） orx logs <runId> --range 4096:8192 # 精确字节窗口 [start, end)

<runId>来自orx runs <projectId>。日志写到stdout，[source] bytes a–b of N状态行走 stderr。在报告前必须验证：日志能识别变体与生效配置、最终指标和紧凑摘要存在、长运行的轨迹可恢复、返回的字节窗口确实包含支撑输出——截断的输出不等于"没有证据"，要用--head/--bytes/--range读到相关部分为止。

十、文件如何被编译：保存即重编译，PDF 与源文件同步

工作树中的.tex用机器上已有的 LaTeX 工具链编译——tectonic、latexmk 或 pdflatex 皆可——生成的paper.pdf写在源文件旁边。每次保存编辑都会触发重编译，因此 PDF 始终跟随文件。

10.1 源码侧：compile() 的完整旅程

src/local/latex.rs 的compile()展示了完整实现细节：

• 辅助文件进临时目录：ScratchDir用"纳秒时间戳 + PID + 自增计数器"生成唯一临时目录（unique_suffix()），aux 文件全部留在临时目录里，编译结束即清理，绝不污染仓库；同名文件的并发编译也互不干扰；
• 多遍编译编排：latexmk/tectonic 自己跑多遍，直接驱动时由 OpenResearch 编排——第一遍产出.aux，第二遍收敛交叉引用；若第一遍产出了文献工具信号（.bcf→ biber，.aux里的\bibdata→ bibtex），则在中间插入文献工具调用并把总遍数提升为 3（BIBLIOGRAPHY_PASSES）；
• 错误判定以 TeX 日志为准：TeX 用!开头行标记每个错误，reports_errors()扫描这个信号而非退出码——因为continue-on-errors会让 tectonic 对部分排版的文档也返回 0；
• PDF 原子落盘：write_pdf_beside()先写临时文件再 rename，读者永远不会看到写了一半的 PDF；若目标 PDF 是符号链接则拒绝覆盖（防仓库外逃）；
• 超时保护：单遍预算PASS_TIMEOUT = 120s，超时后杀进程组（kill_process_tree用进程组 SIGKILL，因为 latexmk 的引擎是孙子进程），日志尾部固定保留 8KB（LOG_TAIL_BYTES）以便诊断。

10.2 编译失败：日志第一行!就是诊断

没有可用的近似预览兜底：不能编译的文档就是什么也没有。失败构建不是"记一笔就继续"的外观问题——它决定用户是拥有一篇论文还是两手空空。因此：

1. 构建失败时，TeX 日志就是诊断；
2. 读第一个以!开头的行——它点名了问题与源文件行号；
3. 修复源码，重新构建；
4. 绝不把不能编译的文档交还给用户。

10.3 机器上没有 LaTeX：明说，并指向 Overleaf

如果机器没有 LaTeX 引擎，要直说而不是假装文件已完工，并指向文件头部的Overleaf 按钮。该按钮打开一个面板，可把论文作为新项目上传到 Overleaf；若用户的套餐包含 Git 集成，则与已有 Overleaf 项目保持同步。

源码侧对"没有工具链"也给出了引导路径：install_hint()首推 Tectonic（单一自包含二进制，自动拉取文档所需宏包，但只跑 XeTeX），并明确标注这一限制；需要全引擎全宏包时安装 TeX Live（macOS 为 MacTeX）。install_command()目前只在 macOS 提供可粘贴命令brew install tectonic——只对已验证可用的平台提供粘贴命令，因为给终端粘贴一条错误的命令比不给更糟。

十一、Overleaf 面板的双向同步纪律

当 Overleaf 面板的标签页打开时，已关联的论文双向同步：合著者的编辑可能在你的回合之间落入.tex。

因此有两条硬性纪律：

1. 改文件前先读文件，而不是凭"我上次写的内容"重写——对方可能已经改了；
2. 绝不手工裁决面板报告为"两侧都有改动"的文件——面板会询问用户保留哪个副本，那是用户的决定，不是 Agent 的。

十二、从实验到论文的完整工作流（实战串联）

把各模块串起来，orx-paper在真实项目中的完整链路是：

1. 项目初始化：orx up启动项目，导入或创建 Git 仓库；为论文场景，用orx paper <id>配合orx-lit-review找到作者或社区实现并克隆（见 orx-create）；
2. 运行实验取证：运行命令统一设置一次（orx project edit <localProjectId> --run-command '<command>'），运行后所有数字经orx logs读取（orx-evidence）；
3. 文献检索：orx discover检索候选，orx paper精读 3–5 篇最关键的来源，保证每一条引用都有真实依据（orx-lit-review）；
4. 制图：先读orx-figures，用其共享样式模块（orx_figstyle.py，位于 agent-skills/orx-figures/assets/orx_figstyle.py）按最终印刷尺寸产出矢量图，写进figs/；
5. 写作：检查.orx/latex-templates/→ 建paper.tex→ 套模板或默认导言 → 写正文、图表、内联thebibliography；
6. 编译与交付：保存触发编译，PDF 落在源文件旁；失败则读日志首行!修复；无引擎则指向 Overleaf 面板；最后按 evidence-and-links 契约在聊天中给出可点击链接。

十三、关键要点速查

• 输出位置：.tex放工作树（paper.tex或<topic>.tex），PDF 就地生成；报告才进 artifacts 目录（orx-reports）；
• 模板优先：写导言前先ls .orx/latex-templates/，有模板就保留其\documentclass、宏包与章节骨架，只填内容；
• 宏包纪律：每个环境都要有定义它的宏包（amsthm+\newtheorem、listings、amsmath、booktabs、graphicx、hyperref、natbib）；
• 引擎声明：默认 pdfLaTeX；需要 Xe/Lua 时在文件首行写% !TeX program = lualatex；
• 交叉引用：引用到的公式才编号，浮动体必须有\label并用Table~\ref{...}引用；
• 图表：先读 orx-figures；\includegraphics[width=\linewidth]{figs/xxx.pdf}，路径相对.tex，确认文件真实存在；
• 文献：内联thebibliography单遍编译；\citet作主语、\citep作括号附带说明；不编造引用；
• 数字：全部来自orx logs的真实运行，未测就明说；
• 排错：编译失败读 TeX 日志第一个!行；无引擎时明说并指向 Overleaf 按钮；
• 同步：Overleaf 面板打开期间双向同步，改前先读，双向冲突交给用户裁决。

【免费下载链接】OpenResearchTurn your coding agents into research agents项目地址: https://gitcode.com/GitHub_Trending/op/OpenResearch