arxiv-paper-writer

ML/AI 综述论文工作流（IEEEtran 模板）

适用场景

• 面向 arXiv 的 ML/AI 综述论文（正文约 6-10 页；不含参考文献）
• 使用 LaTeX + BibTeX 工作流，并验证引用
• 验证或修复现有 LaTeX 项目中的引用

不适用场景

• 新颖的实验研究论文（此工作流适用于综述）
• 非学术文档

输入

• 主题描述（必需）
• 限制条件：投稿 venue、页数限制、作者/所属机构（可选）
• 用于验证引用的现有项目路径（可选）

输出

• main.tex（LaTeX 源文件）
• ref.bib（已验证的 BibTeX 条目）
• IEEEtran.cls
• plan/<timestamp>-<slug>.md、issues/<timestamp>-<slug>.csv
• 图表；main.pdf
• notes/research-snapshot.md（Gate 0 研究快照）
• notes/literature-notes.md（可选的逐条引用笔记）
• notes/arxiv-registry.sqlite3（arXiv 元数据/BibTeX 缓存）

约定：从此技能文件夹（其中包含 scripts/）运行 python3 scripts/...；<paper_dir> 是论文/项目根目录（包含 main.tex、ref.bib、plan/、issues/、notes/）。诸如 plan/... 的路径均位于 <paper_dir> 下。论文创建在 --out <workspace_dir> 指定的位置（你的工作目录，绝不放在此技能文件夹内）；两个引导阶段都传入相同的 --out（如使用了 --name，也传入相同的 --name）。对于 arXiv 检索、元数据和 BibTeX，请使用 scripts/arxiv_registry.py（不要临时使用 curl/wget）。

---

分阶段工作流

提示：使用前运行 python3 scripts/<script>.py --help。 仅在某个步骤明确要求时才打开参考文件。

不可妥协的规则

1. 在计划获批且 issues CSV 文件存在之前，不得在 main.tex 中撰写正文。
2. 首批交付内容：研究快照 + 大纲 + 澄清问题 + 计划草案。
3. 所有新论文都必须使用计划和 issues 跟踪；不得选择跳过。
4. Issues CSV 是执行约定；针对每个 issue 更新 Status 和 Verified_Citations，并在范围扩大时添加/拆分/插入 issue 行（不得进行未跟踪的工作）。
5. 模板固定：使用 IEEEtran 双栏布局（assets/template/IEEEtran.cls）。 将双栏宽度视为布局约束（需要时使用双栏浮动体）。

Gate 0：研究快照 + 计划草案

1. 确认限制条件（投稿 venue、页数限制、作者信息区块、日期范围）。
2. 将主题转化为搜索关键词，并进行初步检索： 10-20 篇关键论文（参见 references/research-workflow.md）。完成第 4 步（<paper_dir> 创建后）后，使用 arxiv_registry.py search 缓存 arXiv 检索结果，并将快照保存到 notes/research-snapshot.md。
3. 提出 2-4 个与主题相符的候选标题。
4. 搭建项目文件夹并起草计划：

   python3 scripts/bootstrap_ieee_review_paper.py --stage kickoff --topic "<topic>" --out <workspace_dir>
   

   此操作会从 assets/template/ 复制 LaTeX 模板；计划和 issues 文件由 assets/ 中的模板生成。 初始化 arXiv 注册表（仅需一次）：python3 scripts/arxiv_registry.py --project-dir <paper_dir> init。
5. 在 main.tex 中创建框架骨架 （章节标题 + 每节 2-4 个要点 + 种子引用；不得写正文）。
6. 更新计划文件，使其反映框架、拟定标题以及章节/小节计划。
7. 尽早编译：python3 scripts/compile_paper.py --project-dir <paper_dir> 修复所有 Overfull \hbox 警告（参见下文的版面规范）。
8. 向用户返回：
   • 拟定大纲（5-8 节，每节 2-4 个要点）
   • 按章节安排的可视化内容（5 项以上，参见 references/visual-templates.md）
   • 澄清问题
9. 暂停，等待用户批准。

Gate 1：创建 Issues CSV（获批后）

1. 检查计划中的启动 Gate：- [x] User confirmed scope + outline in chat。
2. 创建 Issues CSV（如果 Gate 未勾选，脚本会拒绝执行）：

   python3 scripts/bootstrap_ieee_review_paper.py --stage issues --topic "<topic>" --out <workspace_dir> --with-literature-notes
   

3. 验证：

   python3 scripts/validate_paper_issues.py <paper_dir>/issues/<timestamp>-<slug>.csv
   

4. 如果启用了文献笔记，请保留简短摘要和（可选）摘要片段，避免重复检索。
5. 计划可能会调整；按需添加、拆分或插入 Issues，编辑后重新验证，并持续推进，直到所有 Issues（包括新插入的 Issues）都变为 DONE 或 SKIP（条件允许时，在同一次运行中完成）。

Phase 2：逐个 Issue 的写作循环

针对 CSV 中的每个写作 Issue：

• 如果某个 Issue 的规模膨胀（新增图表、新小节、新基准测试集或大量 QA 修正），请先拆分或插入新的 Issue 行（例如，W6a、Q5），再继续；重新运行 python3 scripts/validate_paper_issues.py <issues.csv>；持续推进，直到所有 Issues 都变为 DONE/SKIP。

1. 研究：每个章节专属的论文 8-12 篇。
2. 写作：引用之间最多只能有 3 个句子；段落节奏应有变化 （参见 references/writing-style.md）。 关于章节的意图和结构，请使用 references/template-usage.md。
3. 可视化：根据内容触发条件选择可视化形式（参见 references/visual-templates.md）。 优先使用单栏尺寸；仅在必要时使用跨双栏布局（参见“布局规范”）。 对外部来源的图表内容加以引用。
4. 验证：通过网络搜索并打开来源页面（如有 PDF，也要打开）后，再添加到 ref.bib。 对于 arXiv 条目，使用 python3 scripts/arxiv_registry.py --project-dir <paper_dir> export-bibtex <arxiv_id> --out-bib <paper_dir>/ref.bib 追加 BibTeX。
5. 更新：将 Issue 标记为 DONE，并填写 Verified_Citations 数量。
6. 每次有实质性更改后都要编译；标记为 DONE 前修复 Overfull \hbox。

Phase 2.5：节奏润色

所有写作 Issues 都标记为 DONE 后，使用 latex-rhythm-refiner 技能逐节润色行文。调整句子和段落的长度，删去填充语，同时保留所有引用。

Phase 3：QA Gate

1. 运行内部 QA 检查清单（参见 references/quality-report.md）。
2. 编译；确保 main.log 中没有 Overfull \hbox 警告。
3. 交付 main.tex、ref.bib、图表和 main.pdf。

---

现有论文工作流（不重新搭建）

如果论文文件夹已存在，请勿重新运行脚手架：

# Create plan
python3 scripts/create_paper_plan.py --topic "<topic>" --stage plan --output-dir <paper_dir>
# STOP for approval, then check kickoff gate box
# Create issues (use timestamp/slug from plan filename/frontmatter)
python3 scripts/create_paper_plan.py --topic "<topic>" --stage issues --timestamp "<TS>" --slug "<slug>" --output-dir <paper_dir> --with-literature-notes

引用验证变体

1. 将提供的路径视为 LaTeX 项目根目录。
2. 按照 references/citation-workflow.md 执行。
3. 如果条目需要修复，请使用 references/bibtex-guide.md 了解 BibTeX 规则。
4. 如有要求，交付验证报告和修正后的 ref.bib。

---

成功标准

编译：python3 scripts/compile_paper.py --project-dir <paper_dir>（退出码为 0，且没有“Citation undefined”警告）。使用 --report-page-counts 获取正文页数。

质量指标：

• 正文 6-10 页（不包括参考文献）
• 总引用数 60-80 条（每节至少 8 条）
• 引用验证率 100%
• 近 3 年的引用占比 70% 以上
• 至少 5 种可视化类型
• 所有 Issues 均为 DONE 或 SKIP

---

安全与防护措施

• 绝不捏造引用或结果；如果缺少证据，请添加 TODO 并询问用户。
• 将引用添加到 ref.bib 前，必须通过网络搜索和来源页面（如有 PDF，也要查看）验证每一条引用。
• 大型文献检索前，请先确认。
• 未经确认，不得覆盖用户文件。
• Issues CSV 是执行约定；只有满足标准后才能标记为 DONE。
• 除非用户提出要求，否则不要创建投稿材料包。

布局规范

标记 Issues 为 DONE 前，请修复 Overfull \hbox 警告：

• 图表：从 figure + \columnwidth 开始；必要时改用 figure* + \textwidth
• 表格：优先使用 p{...} 列宽或 \tabcolsep，而非 \resizebox
• 公式：使用 split、multline、aligned 或 IEEEeqnarray 进行换行

---

问题 CSV 架构

阶段	问题
调研	Rx：发现、搭建框架、可视化规划
写作	Wx：每个章节均需包含目标引文和可视化内容
润色	RFx：应用 latex-rhythm-refiner 技能（所有 Wx 均标记为 DONE 后）
QA	Qx：引文验证、QA 检查清单、编译、最终审查

状态：TODO → DOING → DONE，或标记为 SKIP，并在 Notes 中说明原因。架构由 validate_paper_issues.py 验证。

Verified_Citations = 将问题标记为 DONE 时，该问题所属章节中已验证的唯一引文键数量（非写作类问题为 0）。