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-paper论文orx-reports报告输出位置工作树working tree根目录的paper.texartifacts 目录按主题/交付物组织子目录渲染方式.tex就地编译PDF 写在源文件旁边Markdown/CSV/PDF 等产物直接成为项目 artifact引用约定file pathfigs/loss_curve.pdf /仓库相对无artifacts/前缀file pathartifacts/topic/figures/….pdf /这条边界在 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[margin1in]{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 环境与宏包依赖对照文档强调每个环境都需要定义它的宏包——这是草稿编译失败最常见的原因而且是致命失败而非外观问题使用需要theorem、lemma、proofamsthm以及为每个环境写一个\newtheoremlstlistinglistingsalign、equation*、\textamsmath\toprule、\midrulebooktabs\includegraphicsgraphicx\url、\hrefhyperref\citet、\citepnatbib普通\cite则不需要原则只有两条只加载你实际用到的宏包绝不发明一个没有定义的宏。五、引擎选择用魔法注释声明而不是靠猜论文默认以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 programpdflatex、% !TeX program XeLaTeX等变体以及指令埋在第 16 行之后应被忽略的边界情况。Program枚举Pdf/Xe/Lua把引擎名与 latexmk 标志对应起来-pdf/-xelatex/-lualatex与 Overleaf 的引擎命名一致。5.2 驱动器的优先级latexmk → 直接驱动 → tectonicsrc/local/latex.rs 的choose_driver()按以下顺序挑选编译驱动器latexmk当latexmk与文档所需引擎二进制都可用时优先——它自动选引擎、跑 biber/bibtex、重复多遍直到引用收敛这正是 Overleaf 的行为因此注释里写目标是 Overleaf parity直接驱动引擎没有 latexmk 时直接调用pdflatex/xelatex/lualatex由 OpenResearch 自己编排文献工具与重复遍数tectonic只剩 tectonic 时使用它但会在结果中明确备注——因为 tectonic 本质是 XeTeX无法忠实处理声明为 LuaLaTeX 的文档见served_by_tectonic()与Compilation.note字段。每个驱动器的编译参数都经过安全性设计latexmk-norc禁止执行 checkout 里可能存在的.latexmkrc、-interactionnonstopmode非交互避免文档卡在?提示符、-no-shell-escapeAgent 编写的源文件一律关闭 shell escape直接驱动同样-interactionnonstopmode、-no-shell-escapetectonic--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-directoryx.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 pathfigs/loss_curve.pdf /仓库相对、无artifacts/前缀引用同时坚持按最终印刷尺寸制图 仍然写width\linewidth的双保险——尺寸正确时\linewidth缩放系数为 1.0 不改变任何东西但若会场的栏宽与假设不符它依然能自适应。width\linewidth唯一救不了的是按错误尺寸制出的图15 英寸画布被缩进 5.5 英寸栏宽缩放 0.35 后 11pt 刻度标签只剩 4pt这是真实论文图表不可读的头号原因。八、参考文献单遍编译的内联 thebibliographyorx-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则在中间插入文献工具调用并把总遍数提升为 3BIBLIOGRAPHY_PASSES错误判定以 TeX 日志为准TeX 用!开头行标记每个错误reports_errors()扫描这个信号而非退出码——因为continue-on-errors会让 tectonic 对部分排版的文档也返回 0PDF 原子落盘write_pdf_beside()先写临时文件再 rename读者永远不会看到写了一半的 PDF若目标 PDF 是符号链接则拒绝覆盖防仓库外逃超时保护单遍预算PASS_TIMEOUT 120s超时后杀进程组kill_process_tree用进程组 SIGKILL因为 latexmk 的引擎是孙子进程日志尾部固定保留 8KBLOG_TAIL_BYTES以便诊断。10.2 编译失败日志第一行!就是诊断没有可用的近似预览兜底不能编译的文档就是什么也没有。失败构建不是记一笔就继续的外观问题——它决定用户是拥有一篇论文还是两手空空。因此构建失败时TeX 日志就是诊断读第一个以!开头的行——它点名了问题与源文件行号修复源码重新构建绝不把不能编译的文档交还给用户。10.3 机器上没有 LaTeX明说并指向 Overleaf如果机器没有 LaTeX 引擎要直说而不是假装文件已完工并指向文件头部的Overleaf 按钮。该按钮打开一个面板可把论文作为新项目上传到 Overleaf若用户的套餐包含 Git 集成则与已有 Overleaf 项目保持同步。源码侧对没有工具链也给出了引导路径install_hint()首推 Tectonic单一自包含二进制自动拉取文档所需宏包但只跑 XeTeX并明确标注这一限制需要全引擎全宏包时安装 TeX LivemacOS 为 MacTeX。install_command()目前只在 macOS 提供可粘贴命令brew install tectonic——只对已验证可用的平台提供粘贴命令因为给终端粘贴一条错误的命令比不给更糟。十一、Overleaf 面板的双向同步纪律当 Overleaf 面板的标签页打开时已关联的论文双向同步合著者的编辑可能在你的回合之间落入.tex。因此有两条硬性纪律改文件前先读文件而不是凭我上次写的内容重写——对方可能已经改了绝不手工裁决面板报告为两侧都有改动的文件——面板会询问用户保留哪个副本那是用户的决定不是 Agent 的。十二、从实验到论文的完整工作流实战串联把各模块串起来orx-paper在真实项目中的完整链路是项目初始化orx up启动项目导入或创建 Git 仓库为论文场景用orx paper id配合orx-lit-review找到作者或社区实现并克隆见 orx-create运行实验取证运行命令统一设置一次orx project edit localProjectId --run-command command运行后所有数字经orx logs读取orx-evidence文献检索orx discover检索候选orx paper精读 3–5 篇最关键的来源保证每一条引用都有真实依据orx-lit-review制图先读orx-figures用其共享样式模块orx_figstyle.py位于 agent-skills/orx-figures/assets/orx_figstyle.py按最终印刷尺寸产出矢量图写进figs/写作检查.orx/latex-templates/→ 建paper.tex→ 套模板或默认导言 → 写正文、图表、内联thebibliography编译与交付保存触发编译PDF 落在源文件旁失败则读日志首行!修复无引擎则指向 Overleaf 面板最后按 evidence-and-links 契约在聊天中给出可点击链接。十三、关键要点速查输出位置.tex放工作树paper.tex或topic.texPDF 就地生成报告才进 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/20 1:40:24 · 阅读 1.2k 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-paper论文orx-reports报告输出位置工作树working tree根目录的paper.texartifacts 目录按主题/交付物组织子目录渲染方式.tex就地编译PDF 写在源文件旁边Markdown/CSV/PDF 等产物直接成为项目 artifact引用约定file pathfigs/loss_curve.pdf /仓库相对无artifacts/前缀file pathartifacts/topic/figures/….pdf /这条边界在 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[margin1in]{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 环境与宏包依赖对照文档强调每个环境都需要定义它的宏包——这是草稿编译失败最常见的原因而且是致命失败而非外观问题使用需要theorem、lemma、proofamsthm以及为每个环境写一个\newtheoremlstlistinglistingsalign、equation*、\textamsmath\toprule、\midrulebooktabs\includegraphicsgraphicx\url、\hrefhyperref\citet、\citepnatbib普通\cite则不需要原则只有两条只加载你实际用到的宏包绝不发明一个没有定义的宏。五、引擎选择用魔法注释声明而不是靠猜论文默认以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 programpdflatex、% !TeX program XeLaTeX等变体以及指令埋在第 16 行之后应被忽略的边界情况。Program枚举Pdf/Xe/Lua把引擎名与 latexmk 标志对应起来-pdf/-xelatex/-lualatex与 Overleaf 的引擎命名一致。5.2 驱动器的优先级latexmk → 直接驱动 → tectonicsrc/local/latex.rs 的choose_driver()按以下顺序挑选编译驱动器latexmk当latexmk与文档所需引擎二进制都可用时优先——它自动选引擎、跑 biber/bibtex、重复多遍直到引用收敛这正是 Overleaf 的行为因此注释里写目标是 Overleaf parity直接驱动引擎没有 latexmk 时直接调用pdflatex/xelatex/lualatex由 OpenResearch 自己编排文献工具与重复遍数tectonic只剩 tectonic 时使用它但会在结果中明确备注——因为 tectonic 本质是 XeTeX无法忠实处理声明为 LuaLaTeX 的文档见served_by_tectonic()与Compilation.note字段。每个驱动器的编译参数都经过安全性设计latexmk-norc禁止执行 checkout 里可能存在的.latexmkrc、-interactionnonstopmode非交互避免文档卡在?提示符、-no-shell-escapeAgent 编写的源文件一律关闭 shell escape直接驱动同样-interactionnonstopmode、-no-shell-escapetectonic--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-directoryx.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 pathfigs/loss_curve.pdf /仓库相对、无artifacts/前缀引用同时坚持按最终印刷尺寸制图 仍然写width\linewidth的双保险——尺寸正确时\linewidth缩放系数为 1.0 不改变任何东西但若会场的栏宽与假设不符它依然能自适应。width\linewidth唯一救不了的是按错误尺寸制出的图15 英寸画布被缩进 5.5 英寸栏宽缩放 0.35 后 11pt 刻度标签只剩 4pt这是真实论文图表不可读的头号原因。八、参考文献单遍编译的内联 thebibliographyorx-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则在中间插入文献工具调用并把总遍数提升为 3BIBLIOGRAPHY_PASSES错误判定以 TeX 日志为准TeX 用!开头行标记每个错误reports_errors()扫描这个信号而非退出码——因为continue-on-errors会让 tectonic 对部分排版的文档也返回 0PDF 原子落盘write_pdf_beside()先写临时文件再 rename读者永远不会看到写了一半的 PDF若目标 PDF 是符号链接则拒绝覆盖防仓库外逃超时保护单遍预算PASS_TIMEOUT 120s超时后杀进程组kill_process_tree用进程组 SIGKILL因为 latexmk 的引擎是孙子进程日志尾部固定保留 8KBLOG_TAIL_BYTES以便诊断。10.2 编译失败日志第一行!就是诊断没有可用的近似预览兜底不能编译的文档就是什么也没有。失败构建不是记一笔就继续的外观问题——它决定用户是拥有一篇论文还是两手空空。因此构建失败时TeX 日志就是诊断读第一个以!开头的行——它点名了问题与源文件行号修复源码重新构建绝不把不能编译的文档交还给用户。10.3 机器上没有 LaTeX明说并指向 Overleaf如果机器没有 LaTeX 引擎要直说而不是假装文件已完工并指向文件头部的Overleaf 按钮。该按钮打开一个面板可把论文作为新项目上传到 Overleaf若用户的套餐包含 Git 集成则与已有 Overleaf 项目保持同步。源码侧对没有工具链也给出了引导路径install_hint()首推 Tectonic单一自包含二进制自动拉取文档所需宏包但只跑 XeTeX并明确标注这一限制需要全引擎全宏包时安装 TeX LivemacOS 为 MacTeX。install_command()目前只在 macOS 提供可粘贴命令brew install tectonic——只对已验证可用的平台提供粘贴命令因为给终端粘贴一条错误的命令比不给更糟。十一、Overleaf 面板的双向同步纪律当 Overleaf 面板的标签页打开时已关联的论文双向同步合著者的编辑可能在你的回合之间落入.tex。因此有两条硬性纪律改文件前先读文件而不是凭我上次写的内容重写——对方可能已经改了绝不手工裁决面板报告为两侧都有改动的文件——面板会询问用户保留哪个副本那是用户的决定不是 Agent 的。十二、从实验到论文的完整工作流实战串联把各模块串起来orx-paper在真实项目中的完整链路是项目初始化orx up启动项目导入或创建 Git 仓库为论文场景用orx paper id配合orx-lit-review找到作者或社区实现并克隆见 orx-create运行实验取证运行命令统一设置一次orx project edit localProjectId --run-command command运行后所有数字经orx logs读取orx-evidence文献检索orx discover检索候选orx paper精读 3–5 篇最关键的来源保证每一条引用都有真实依据orx-lit-review制图先读orx-figures用其共享样式模块orx_figstyle.py位于 agent-skills/orx-figures/assets/orx_figstyle.py按最终印刷尺寸产出矢量图写进figs/写作检查.orx/latex-templates/→ 建paper.tex→ 套模板或默认导言 → 写正文、图表、内联thebibliography编译与交付保存触发编译PDF 落在源文件旁失败则读日志首行!修复无引擎则指向 Overleaf 面板最后按 evidence-and-links 契约在聊天中给出可点击链接。十三、关键要点速查输出位置.tex放工作树paper.tex或topic.texPDF 就地生成报告才进 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考