federicodeponte/opendraft · 上手攻略

  • 仓库：federicodeponte/opendraft
  • 链接：https://github.com/federicodeponte/opendraft
  • 分类：agent / 学术写作与文献综述
  • 作者：spark
  • 更新：2026-11-04

版本说明：本文基于 2026-11-04 抓取的 README（master 分支）、docs/PIPELINE.md、docs/citation-verification.md、docs/opendraft-vs-storm.md。文中下载量与引用数据均为 README 自述数字（截至 2026 年 11 月），未独立核验；PyPI 版本号本文未锁定（⚠️ 待核，见文末）。

一、这是什么

OpenDraft 是 MIT 许可的开源 agent 系统，输入一个主题，输出带已核验引用的学术论文、文献综述或论文章节。README 自述定位为「Jenni 和 ThesisAI 的开源替代品」——区别在于不需要订阅闭源 SaaS，而是用你自己的模型 key。

核心技术特征是引用的两段式验证，作者明确把「能证明什么」和「不能证明什么」分开写：

  1. 文献是否存在：默认只保留在 Crossref、OpenAlex、Semantic Scholar 三者中至少两家持有其 DOI 的来源，单来源直接丢弃并记日志。
  2. 文献是否支撑所引论断：CitationClaimVerifier 逐条判断来源与论断的关系，返回 RELEVANT / IRRELEVANT / UNCERTAIN。

作者强调第一段只证明「这篇工作存在且被索引」，不证明它支持挂在它身上的那句话。这种自我设限在同类项目里少见。

二、解决什么问题

学术写作自动化的核心痛点从来不是「生成得像不像论文」，而是「引用是不是真的」。传统 LLM 写作工具的通病是引用幻觉——DOI 格式正确、作者名合理、期刊也存在，唯独这篇论文压根没说过你引它说的那句话。OpenDraft 针对的是：

  • 引用幻觉：用多库交叉确认把「不存在的文献」挡在门外。
  • 凑数引用：论点与文献错配由 claim verifier 单独抓。
  • 长文结构崩坏：19 个专职 agent 分 6 阶段流水线，避免一段话写到底。
  • 格式转换：直接导出 PDF / Word / LaTeX。

三、快速安装

要求 Python 3.10+ 与一个模型 key（Gemini 默认，Claude 与 OpenAI 也支持）。

pip install opendraft
opendraft setup              # 交互式录入你的 Gemini API key
opendraft "Remote work and team productivity"

从源码装：

git clone https://github.com/federicodeponte/opendraft.git
cd opendraft
pip install -e ./engine
cp .env.example engine/.env   # 填入你的 key
opendraft "Your topic"

环境变量（README 表格 + .env.example）：

变量 必需 用途
GOOGLE_API_KEY 是（其一） Gemini，默认 provider
ANTHROPIC_API_KEY / OPENAI_API_KEY 可选 配合 AI_PROVIDER=claude 或 openai
ENABLE_SEMANTIC_SCHOLAR 可选 被 Semantic Scholar 限流时设为 false

成本：README 自述「约 $0.35 到 $3 每份草稿」，费用只来自你自己的模型 provider。README 说其余设置都在 .env.example 里。

四、核心用法

4.1 命令行

opendraft                                    # 交互模式
opendraft "Topic" --level phd --lang de      # 级别：research_paper / bachelor / master / phd；语言
opendraft "Topic" --expose                   # 只出提纲与来源，更快
opendraft revise ./output "make the intro longer"   # 修改已有草稿
opendraft tldr paper.pdf                     # 任意论文的 5 条要点摘要

--expose 很实用：先看提纲与检索到的来源，确认选题没跑偏再让引擎写全文，省 token。

4.2 作为 agent skill 使用

在 Claude、ChatGPT 等会读 skill 的 agent 里使用：

npx skills add federicodeponte/opendraft --skill autonomous-research

然后对 agent 说「Write a paper on 」。重要说明：skill 位于 skills/autonomous-research/，跑在你自己的 agent 里，并不调用这个 Python engine——skill 路径是提示词与流程的复用，不是引擎的调用。

4.3 流水线结构（19 agents / 6 阶段）

docs/PIPELINE.md 的完整架构：

INPUT: Topic + Academic Level + Citation Style + Language
  │
  ├─ PHASE 1 RESEARCH      Scout + Deep Research → Scribe → Signal
  │                        找 50+ 篇论文 / 逐篇摘要 / 找缺口与趋势
  ├─ PHASE 2 STRUCTURE     Architect → Formatter（APA/IEEE 风格）
  ├─ PHASE 2.5 CITATION MANAGEMENT（确定性，无 LLM）
  │                        去重 → 抓标题 → 抓元数据 → 生成 {cite_XXX} ID
  ├─ PHASE 3 COMPOSE       Crafter 被调用 6-7 次，逐节写
  │                        Intro / 2.1 Lit Review / 2.2 Methods /
  │                        2.3 Results / 2.4 Discussion / 3 Conclusion / 4 Appendices
  ├─ PHASE 3.5 QA          Thread（跨节连贯、矛盾、引用） + Narrator（语气、时态、对冲）
  │                        ← 咨询性报告，不阻断
  ├─ PHASE 4 COMPILE       组装 → Citation Compiler（{cite_001} → "(Smith et al., 2023)"）
  │                        → Abstract Generator → 后处理（修表、去重复附录、
  │                          清理 AI 语言、标题本地化）
  └─ PHASE 5 EXPORT（无 LLM）Markdown → PDF（Pandoc + LaTeX）/ DOCX（Pandoc）
OUTPUT: paper.pdf + paper.docx

13 个 agent 在自动化流水线中实际被调用，另 6 个（Skeptic、Verifier、Referee、Citation Verifier、Voice、Entropy、Polish、Enhancer 中的一部分）有 prompt 文件但当前不在自动流水线里调用，是为 Cursor/Claude Code 人工迭代流程准备的。

一个容易被忽略的设计：Phase 2.5、3.5 与 Phase 5 完全不用 LLM。去重、占位符替换、格式导出是确定性代码——这正是「引用编译」这类环节不该交给模型的原因。每个小节写作时收到提纲 + citation_summary + 之前已写的小节，这让跨节连贯有上下文基础，也让 Thread agent 的跨节矛盾检查有意义。

4.4 引用发现与确认（两阶段）

CitationResearcher 分两阶段：

STAGE 1 — DISCOVERY（任一来源命中即可进入候选）

Crossref / OpenAlex / Semantic Scholar  （学术主题，并行查询）
        ↓ 若无结果
Serper / Gemini Grounded Search         （URL 结果，通常无 DOI）
        ↓ 若全部失败
LLM Fallback                             （默认禁用；产出标记 llm_unverified）

QueryRouter 智能路由：已知条目查询（DOI、精确标题）→ 先查 Crossref；宽泛主题 → 先查 Semantic Scholar；近期/冷门主题 → 先走 Gemini Grounded / Serper。

STAGE 2 — CONFIRMATION（默认 3 选 2）

对每个带 DOI 的候选，直接按 DOI 逐库查询：

  • ≥ min_confirming_sources 持有 → 保留，标记 multi_source_confirmed
  • 恰好一家持有 → 丢弃，标记 single_source
  • 完全没有 DOI（网络结果）→ 默认丢弃，除非 allow_unconfirmed_web_sources=True，保留则标记 web_search_unconfirmed

四个相关设置（来自 docs/citation-verification.md）：

设置 默认 效果
require_multi_source True 丢弃低于 min_confirming_sources 库的引用
min_confirming_sources 2 三库中至少几家必须持有该 DOI
allow_unconfirmed_web_sources False 保留无 DOI 的网络搜索结果
enable_llm_fallback False 全部查询失败时允许 LLM 断言引用

4.5 论断级验证

CitationClaimVerifier 返回 RELEVANT / IRRELEVANT / UNCERTAIN。注意执行时机：在引用阶段（Phase 2.5）运行时草稿文本尚不存在，因此只能针对「论文主题」验证。句子级验证需要草稿，通过 run_citation_claim_verification() 调用。

环境变量 默认 效果
ENABLE_CLAIM_VERIFICATION true 是否运行论断级验证
CLAIM_VERIFICATION_DROP_IRRELEVANT true 移除不相关引用而非仅报告
CLAIM_VERIFICATION_MIN_CONFIDENCE 0.7 触发移除所需的置信度

报告写到研究目录的 citation_claim_verification.md 与 .json。作者特别说明：引擎拒绝把参考文献清空。

4.6 字数与引用量目标

级别 总字数 最少引用 深研来源数 章节数
Research Paper 3,000-5,000 10 20 3-4
Bachelor 10,000-15,000 15 40 5-7
Master 25,000-30,000 25 50 7-10
PhD 50,000-80,000 50 100 10-15

配置在 engine/draft_generator.py 的 get_word_count_targets()。

4.7 导出

PDF 走 Pandoc + LaTeX，DOCX 走 Pandoc——Pandoc（PDF 另需 LaTeX 工具链）需自行安装，这是安装环节最容易漏掉的一步。README 说可导出 PDF、Word 与 LaTeX，耗时「通常 10 到 20 分钟」。

五、典型适用场景

  • 文献综述初稿：手头 50+ 篇文献要整合成结构化综述，最直接的场景。
  • 学位论文章节：PhD 目标 50,000-80,000 字、50+ 引用，量级匹配。
  • 教学材料起草：--level bachelor 与多语言支持（--lang de）适合非英语场景。
  • 引用错配体检：拿它生成的草稿当参照物，检查自己手写的综述有没有引用错配。
  • 快速文献侦察：--expose 模式只出提纲与来源，成本极低。
  • agent 内嵌：npx skills add 后在自己 agent 里跑，接受「不调用 Python engine」的前提。

六、坑与注意

  1. 现象：三库并非真正独立。 影响：citation-verification.md 明确指出 OpenAlex 和 Semantic Scholar 都摄取 Crossref 的元数据，所以「2 家确认」不等于两份彼此独立的证词——尤其当 Crossref 本身是候选来源时，确认方之一往往就是它自己。做法：把 2/3 当作去重下限而非强证据；关键引用自己再核一遍。
  2. 现象：确认方之一可能被「照单全收」。 影响：文档坦承「两家持有」中，一家可能正是最初返回候选的那个库，引擎对其「以它自己的说法为准而不重新查询」，真正被直接按 DOI 查的只有其余的。做法：需要严格时自己逐库查 DOI；引擎内部用 confirming_sources 与 independently_confirmed_by 区分，但 README 未说明二者如何暴露给用户。
  3. 现象：UNCERTAIN 不是通过。 影响：CitationClaimVerifier 读的是标题与摘要，不是全文；作者原文说「UNCERTAIN means unchecked, not passing」。做法：把输出的 verdict 当作给人审的证据，不要当结论；尤其是具体数字类论断。
  4. 现象：论断级验证在流水线中只对着「主题」跑。 影响：Phase 2.5 时还没有正文，可用的唯一论断是论文主题本身，因此「这句话配这篇文献」的检查在默认流程里并未真正发生，需要草稿存在后调 run_citation_claim_verification()。做法：对最终稿单独跑一次句子级验证。
  5. 现象：严格过滤会让运行失败。 影响：多源确认、严格质量过滤与论断级移除都在缩小文献库，若引用阶段无引用存活，流水线抛 PipelineValidationError。做法：这是「以前能出草稿、现在报错」的根因；应主动放宽检索或显式调 require_multi_source=False，而非随手改配置碰运气。
  6. 现象：README 里引用的引用条数已过时。 影响：文档明确说旧版 README 与 EVALUATION.md 中的引用计数是在多源确认成为默认之前测的、此后未重测，必须当作历史数据看。做法：别拿「它能找出 40+ 篇」当现在的预期；且用 require_multi_source=False 时引用会带 verification_status: not_checked，而不是被标成已确认。
  7. 现象：arXiv 不作为引用库被查询。 影响：arxiv.org 可能作为网络搜索结果出现、Semantic Scholar 也暴露 arXiv ID，但引擎里没有 arXiv API 客户端，纯 arXiv 预印本默认拿不到 2/3 确认，容易被丢。做法：预印本为主的题目需预期更多丢弃，可考虑 allow_unconfirmed_web_sources=True（但会被标记）。
  8. 现象：导出依赖 Pandoc（PDF 另需 LaTeX）。 影响：pip 装完直接跑 opendraft 写稿没问题，但最后一步导出会因缺 Pandoc 失败。做法：先装 Pandoc；PDF 另备 TeX 发行版（如 TeX Live 的最小集合）。
  9. 现象：LLM fallback 存在但默认关闭。 影响：若打开 enable_llm_fallback=True，LLM 会「从训练数据里断言」引用，这类产出全标 llm_unverified，外部没有任何东西检查过它是否存在。做法：保持默认关闭；若为覆盖率打开，成稿后必须逐条人工核查该标记。
  10. 现象：skill 路径不调用 Python 引擎。 影响：npx skills add 装到 agent 里的是 skills/autonomous-research/ 提示词与流程，行为质量取决于你的 agent 与模型，与 CLI 的 19-agent 流水线不是一回事。做法：想要完整引用验证流水线，用 CLI 或 pip install 路径；skill 路径用于「在自己 agent 里复用这套流程」。
  11. 现象：作者自述「草稿不是可直接投稿的成品」。 影响：README FAQ 明说产物是 starting point，需审阅编辑并遵守所在机构对 AI 使用披露的政策。做法：把它当初稿生成器而非投稿机器人；披露政策自己查，别指望工具替你判断。
  12. 现象：QA 阶段是咨询性的、不阻断。 影响：Phase 3.5 的 Thread / Narrator 只产出报告，Crafter 写出的矛盾与语气问题不会自动拦下。做法：成稿后必读 thread_report / narrator_report，别假定引擎已替你把关。

七、与同类对比

仓库自带 docs/opendraft-vs-storm.md，对照表很实用：

OpenDraft STORM Co-STORM
产出 研究论文、文献综述、论文章节（1 万-2 万字+） 类维基百科条目 条目 + 共享思维导图
驱动方式 全自动：一个主题进，完整草稿出 全自动 协作：用户观察或引导讨论
研究方式 19 个专职 agent 视角引导提问 + 模拟写作者/专家对话 LLM 专家与 moderator 与用户轮次对话
来源 Crossref、OpenAlex、Semantic Scholar 网络检索（You.com、Bing、Serper、Brave、SearXNG、DuckDuckGo、Tavily、Google、Azure）或自有文档 同 STORM
引用校验 DOI 须被 ≥2/3 库持有，逐条记录哪几家确认 指向检索到的网络来源 同 STORM
导出 PDF、Word、LaTeX 文章文本 文章文本
模型 自带 key 的 Gemini / OpenAI / Claude LiteLLM 支持的任意模型 同 STORM
安装 pip install opendraft pip install knowledge-storm 同 STORM
许可 MIT MIT MIT

选择建议（作者原文）：要带学术引用的论文/综述/学位论文草稿 → OpenDraft；要有来自网络的百科式主题概览 → STORM；要交互式探索自己掌舵 → Co-STORM。

再往外看：vs 纯 LLM 手写——差别不在文笔而在引用可验证性；vs Jenni / ThesisAI——卖点是开源 + 自带 key + 引用验证算法写进文档；vs 纯检索工具（Semantic Scholar API + Zotero）——后者保证检索质量但不自动成文，前者自动成文但引用判断带 LLM 成分。

外部背书方面，README 提到自己被两篇工作引用：NIH/NIEHS 的 Talukder 等（2026），Discourse2Draft，Frontiers in Artificial Intelligence，doi:10.3389/frai.2026.1945655；以及 NUS 的 Kong 等（2026），AI for Auto-Research，arXiv:2605.18661。README 还自述下载量「PyPI 20,289 + npm 4,200，截至 2026 年 11 月」。

八、一句话推荐结论

做文献综述或学位论文初稿、且最怕引用被编造或错配的人，值得用 OpenDraft——多源 DOI 确认 + 论断级验证是同类开源项目里少见的工程化尝试，作者也诚实写明了这两道检查「证明不了什么」；但务必把它当初稿生成器：结论自己核，句子级验证单独跑，Pandoc/LaTeX 先装好，arXiv 预印本多的题目预期更多引用被丢。

来源

  • https://github.com/federicodeponte/opendraft（README，2026-11-04 抓取）
  • https://raw.githubusercontent.com/federicodeponte/opendraft/master/docs/PIPELINE.md
  • https://raw.githubusercontent.com/federicodeponte/opendraft/master/docs/citation-verification.md
  • https://raw.githubusercontent.com/federicodeponte/opendraft/master/docs/opendraft-vs-storm.md
  • web_search 命中同仓库 README 页面（另一份缓存快照，措辞略有差异，用于交叉比对）

不确定与待核

  • ⚠️ PyPI / npm 上的确切版本号本文未锁定（README 只给 pip install opendraft）。需要精确版本请查 pypi.org/project/opendraft/。
  • ⚠️ 下载量「PyPI 20,289、npm 4,200，截至 2026 年 11 月」与「$0.35-$3 每份草稿」「10-20 分钟」均为 README 自述，作者未提供独立来源；本次未独立核验。
  • ⚠️ 引用计数类数字（README 的「60 页、40+ 引用」示例、字数目标表）来自 README 与 PIPELINE.md；文档已声明部分旧计数未在多源确认成为默认后重测。
  • ⚠️ docs/MAINTAINER_PUSH_RUNBOOK.md、.env.example 全文、CHANGELOG.md 未抓取，.env.example 中的其余变量名未逐条列出。
  • ⚠️ README 提到 npm 包名 opendraft（npx opendraft）与 PyPI 同名，但本次未在 npm 页面核实其发布时间与版本。
  • ⚠️ web_search 返回的第三方条目「Opendraft / opendraft.io, Los Angeles, SEO 博客工具」与本仓库并非同一实体，已排除，未采信。