一套完整的 AI 辅助学术写作管道：从 Zotero 文献库出发，经过 Obsidian Canvas 结构化笔记，
到 Gemini CLI 分阶段提取证据，最终生成事实驱动、可核查的 Related Work 段落。
公开版核心是 batch.py（Zotero → Canvas）；下游 RW 写作流水线以一篇真实 ToCHI 投稿
实践（2026.03）为案例呈现，参见 GitHub 仓库。
初稿 Related Work 最常见的问题是"引用堆积"——一句话后面跟 5–7 个引用，没有实质内容。 审稿人无法判断这些论文发现了什么、为什么被引用。
Gaze interaction has been studied extensively for selection tasks \cite{A, B, C, D, E, F, G}. Various approaches have been proposed to address the Midas Touch problem \cite{H, I, J, K}.
→ 两句话引了 11 篇论文，但读者不知道任何一篇的具体发现
Dwell-based selection remains a primary solution, with 600ms identified as the optimal duration to balance efficiency and workload \cite{niu2020}. For small targets, discrete magnification achieves 88% accuracy compared to only 28% for standard dwell \cite{skovsgaard2011}.
→ 每句话 = 一个具体事实 + 一个引用，论证清晰可追溯
💡 核心思路
不要让 AI 直接写 RW（会编造或泛化）。让 AI 做结构化提取， 输出 JSON，人工检查后再写作。所有中间产物保存，修改方向时不需要重跑。 Canvas 笔记库是结构化的知识来源——可以直接针对它提问，找出具体证据。
从 Zotero 文献库到最终 LaTeX 段落，整条管道分为 7 个阶段、4 种 AI Agent。
点击任意阶段查看详细说明、代码示例和真实输出数据。
batch.py从 Zotero 数据库读取指定 Collection 的所有论文，用 pdfplumber 提取 PDF 全文并编号每行， 然后调用 Gemini CLI 生成结构化的 Obsidian Canvas 知识鸟瞰图。 每个 Canvas 包含：文献元数据、研究背景、核心方案、实验设计、结论等节点，以及带页码的 Zotero 深链接。
bash # 批量生成 Canvas 文件 venv/bin/python batch.py -m gemini-3-flash-preview -w 5 # 可选：只处理特定 attachment keys venv/bin/python batch.py --keys TEPVVD2P ABC12345 # Dry run：列出所有论文，不实际生成 venv/bin/python batch.py -n
python — 核心调用模式 # Gemini CLI 调用模式（所有脚本统一） result = subprocess.run( ["gemini", "-m", model, "-p", prompt], capture_output=True, text=True, timeout=360 ) # prompt 里包含完整的 PDF 文本 + 元数据 + Canvas 格式要求 raw = result.stdout.strip() # 清理 markdown fence if raw.startswith("```"): raw = re.sub(r"^```\w*\n?", "", raw) raw = re.sub(r"\n?```$", "", raw) canvas = json.loads(raw)
classify.py读取每个 Canvas 文件的关键节点内容（元数据 + 结论 + 核心方案）， 结合论文的 RW 小节定义，让 Gemini 判断每篇文献属于哪个小节。 输出结构化的分类结果和 Markdown 表格。
screen.py
区分哪些论文有"展开讲"的价值（有具体数字/对比/结论 → featured），
哪些只需要 \cite{} 提及（→ brief）。
每个小节有定制化的筛选标准。
| S1 | 有没有量化的确认延迟/错误率/成功率？ |
| S2 | 有没有比较第二通道 vs. 纯注视的 RT/SR？ |
| S3 | 有没有量化不同足部动作的疲劳/精度差异？ |
| S4 | 具体测了什么场景？关键结果数字是什么？ |
extract.py对 featured 论文精确提取 1–2 句可直接引用的事实句。 每篇提取：具体技术 → 核心量化发现 → 局限性 → 可放入 RW 的英文句子。 这三要素决定 RW 段落的论证强度。
⚠️ 经验：如果 Canvas 节点文本太长（>8000 tokens）， 直接传给 Flash 会有截断风险，建议只传"实验"和"结论"节点。
write_rw.py用 evidence 文件驱动 Gemini 写出 Sidenmark 风格的段落草稿。 每句话 = 一个具体事实 + 一个引用，不堆积。每段有论点驱动的开头句。
rw_sentence（可直接用或改写）\cite{} 分组提及）草稿 S1 节选（真实输出）：
LaTeX Dwell-based selection remains a primary solution, with 600ms identified as the optimal duration to balance efficiency and workload \cite{niu2020Improving}. For small targets, discrete magnification achieves 88% accuracy compared to only 28% for standard dwell \cite{skovsgaard2011Evaluating}, while the Bubble Gaze Cursor reduces selection errors by 54.0% using area cursors and kinematic triggering \cite{choi2020Bubble}.
integrate_rw.py以 draft 为素材、LaTeX 骨架为框架，用 Gemini Pro 做最终 rewrite。 Flash 在整合写作质量上明显偏弱——这一步必须用 Pro。
\cite{A, B, C, D} 形式的句子，用具体事实句替换Gap Statement 分布策略：
| §2.1 | 过渡连接 — "...the design principle on which [Paper] is founded." |
| §2.2 | 定位连接 — "[Paper] exploits this property by dedicating [channel] to..." |
| §2.3 | 完整 gap + 贡献 — "Two questions remain... Our work addresses both gaps." |
CodeX exec核查 RW 中所有带数字的陈述是否与 Canvas 原始记录一致。 CodeX 擅长"读文件 + 判断"类任务，逐文件读取 Canvas 并交叉比对。 每次运行约 5–10 分钟。
bash # CodeX 调用示例 /Applications/Codex.app/Contents/Resources/codex exec " Task: Verify factual claims in §2.1 of rw_integrated_21.tex. For each claim with a number, find the source Canvas file, read it, check if the number/fact matches. Output markdown table: claim | status (✅/⚠️/❌) | source | notes. Canvas dir: ./canvas-out/ Output: verification_report.md "
真实核查结果（节选）：
| Claim | Status | Notes |
|---|---|---|
600ms optimal dwell — niu2020 |
✅ | Canvas 明确推荐 600ms |
88% accuracy vs 28% — skovsgaard2011 |
✅ | 数字完全匹配 |
5.30 wpm text entry — scottmackenzie2011 |
⚠️ | Canvas 记录 4.37 wpm 平均、4.58 wpm 最优，需修正 |
54.0% error reduction — choi2020 |
⚠️ | 54.0% 归因于 lens condition，非 Bubble Gaze Cursor 整体 |
98.6% trigger success — ya2024magilock |
✅ | 两个数字完全匹配 |
整条管道依赖的外部工具和它们的角色分工。
文献管理 + citekey 映射。SQLite 数据库提供论文元数据，BetterBibTeX 提供稳定的 citekey。
zotero://open-pdf/library/items/{key}?page=N
结构化文献笔记。每篇论文一个 .canvas 文件，包含元数据、研究背景、核心方案、实验、结论节点。标准 JSON 格式（nodes + edges）。
AI 引擎，通过 subprocess 调用，非 API。Flash 用于 Stage 1–5（速度快），Pro 用于 Stage 6（整合写作质量更高）。
gemini -m model -p "prompt"
OpenAI 的 CodeX 执行器，擅长"读文件 + 判断"类任务。用于 Stage 7 事实核查——逐文件读取 Canvas 并比对 RW 中的数字。
| 阶段 | 模型 | 原因 |
|---|---|---|
| Canvas 生成 / 分类 / 筛选 / 提取 / 草稿 | gemini-3-flash-preview |
速度快、结构化 JSON 输出稳定 |
| LaTeX 整合 | gemini-2.5-pro |
整合写作质量 Flash 明显偏弱 |
| 事实核查 | CodeX 默认模型 | 逐文件阅读 + 判断，非生成型任务 |
完成后的 Related Work 应满足以下标准（点击可打勾）：
整条管道设计为可复用。以下是移植到新论文时需要调整的 6 个点。
修改 classify.py 中的 RW_SECTIONS 定义，按新论文的 RW 小节重新定义 S1–S4（或更多）。
重跑 classify.py 生成新的 classify_result.json。
修改 screen.py 中的 SECTION_CRITERIA，
根据新论文的核心论点定制每个小节的筛选问题（什么信息值得"展开讲"）。
修改 extract.py 中每个 section 的提取问题。
围绕新论文"要说明什么 gap"来设计，每小节 3 个问题。
在 integrate_rw.py 中替换为新论文当前的 LaTeX RW 文本。
保留段落结构和 gap statement 的位置。
修改 integrate_rw.py 中的连接语指令——
改为新论文的名字和贡献方向，使每小节末尾正确导向本文。
修改每个脚本顶部的配置块：ZOTERO_DB、ZOTERO_STORAGE、
COLLECTION_NAME、OUTPUT_DIR、CITEKEY_MAP。
project structure zotero-canvas-batch/ ├── batch.py # 核心：PDF → Canvas（公开版主入口） ├── rename_patch.py # Canvas 重命名 + 补丁 citekey ├── SKILL.md # Agent / Claude Code 调用接口契约 ├── README.md # 项目说明 ├── .env.example # 环境变量模板 └── examples/ └── rw-pipeline/ # 参考实现（非通用，作模板） ├── classify.py # Stage 2: 文献分类 ├── screen.py # Stage 3: featured / brief 筛选 ├── extract.py # Stage 4: 证据提取 ├── write_rw.py # Stage 5: RW 段落草稿 └── README.md # 如何把这套模板替换成你自己的 RW 大纲
说明：教程页中演示的 Stage 6 (integrate_rw.py，LaTeX 整合) 和
Stage 7（CodeX 事实核查）是 Gaze2Foot 投稿实践中的额外环节，
因为高度论文专属，公开仓不再随附；可按 §复用 部分自行重建。