学术写作工作台：Zotero+Pandoc+Git构建可复现研究流程

看到 Imbad0202 / academic-research-skills 这个仓库名时，很多人第一反应是去收藏一批“学术工具清单”或“读论文方法论”。但只停留在收藏阶段，资料很快就会变成一份永远不会再打开的书签。真正的学术研究技能，在计算机和工程相关领域里，是一套可执行、可复现、可排查的工程能力：文献管理是否成体系，论文笔记是否支撑后续写作，实验能否换一台机器重跑，草稿改了几十版之后还能不能定位关键差异。

这篇文章不写励志方法论，而是把文献管理、论文笔记、写作流水线、实验复现和版本管理串成一条完整流程。你会看到一个最小可运行的学术写作工作台：从 Zotero 导出 BibTeX，用 Markdown 写正文，用 Pandoc 生成带引用的 PDF 或 Word 文档，再用 Git 管理每一版修改，最后把代码和依赖整理成可复现的实验仓库。这套流程既适合研究生从零搭建自己的研究环境，也适合已经写过论文但一直被参考文献格式、编译报错和复现问题反复打断的人。

1. 先把“学术研究技能”定义成工程问题

1.1 为什么只收藏工具网址没有用

学术研究技能不是“会推荐几个软件”，而是能够在压力场景下稳定输出研究产物。真正的压力场景包括：导师三天后要看综述初稿、投稿系统要求指定参考文献格式、评审人要求提供实验脚本和数据处理过程、换一台电脑后发现之前的实验环境再也装不回来。

这些场景有一个共同特征：它们不是靠灵感解决的，而是靠流程和工具链解决的。文献没有清洗干净的元数据，写作时引用就会失效；笔记只有大段摘抄，写作时依然要重新打开 PDF；实验脚本只保存在个人目录，无法让别人一键运行；论文草稿用“最终版2_new_v3.docx”管理，你永远无法回答“上一版和这一版到底改了什么”。

把这些问题看成工程问题，解决方案就清晰很多。核心不是某个软件，而是一套工作台：每条文献有稳定 ID，每篇笔记有结构化模板，每个写作文件可以编译验证，每个实验有环境和种子记录，每次修改都在版本历史中留下痕迹。

1.2 从文献到论文的完整处理流程

整个研究生命周期可以拆成五个环节，每个环节都对应一类可训练的技能：

学习阶段可以使用最小配置：Zotero 只负责存 PDF，Pandoc 只负责转格式，Git 只用来每天提交一次。这样做的目的是尽早跑通链路，而不是一开始就引入复杂的自动化。

生产阶段则要增加约束：参考文献库必须导出到受控的.bib文件，代码目录必须包含requirements.txt，论文提交前必须从干净环境编译一次，原始数据不进入 Git，实验关键参数写入 README。后面章节会分别展开这些约束。

注意：工具不是越多越好。先把 Zotero、Pandoc、Git 这三件基础工具用到能自动反应，再逐步加入笔记软件、Docker、持续集成。

2. 文献管理：让每一篇 PDF 都有稳定的“身份证”

2.1 Zotero 作为本地文献库

Zotero 是文献管理环节最常用的开源工具，免费、跨平台，可以用浏览器插件从论文页面一键抓取元数据和 PDF。相比“下载 PDF 后按文件夹堆放”，Zotero 的核心价值在于每一条文献的元数据可以持续修正，并且可以通过插件导出成标准格式。

使用 Zotero 时有一个容易忽视的动作：导入 PDF 后，必须检查作者、标题、年份、期刊卷期、DOI 是否正确。机器抓取的元数据并不总是可靠，如果引用阶段发现作者名里的花括号写错，再回到库里去改已经晚了。建议把文献元数据错乱当作数据质量问题来对待，每篇重要文献入库时顺手核对一次。

学习环境的快速做法是直接使用网页剪藏插件，遇到论文就一键保存。生产环境则建议为每个课题建立独立分类，并定期把分类导出到课题目录下的.bib文件，避免依赖云服务或单一数据库。

2.2 用 Better BibTeX 生成稳定引用键

Zotero 自带的 BibTeX 导出功能可以工作，但生成的引用键往往不稳定，例如zhang2024toward这类键可能因为字段修改而变长或变动。如果论文正文里已经写了[@zhang2024]，文献库里稍微调整标题，导出后 key 变成zhang2024towardreproducibleresearchskil，所有引用就全部失效。

推荐安装 Better BibTeX 插件。它能让你自定义引用键规则，并且在导出.bib时提供“保持引用键不变化”的能力。安装流程并不复杂：

1. 在 Zotero 官网或插件仓库下载 Better BibTeX 的.xpi文件。
2. 打开 Zotero：工具 -> 插件 -> 右上角齿轮 -> Install Plugin From File。
3. 选择.xpi文件，确认安装后重启 Zotero。
4. 在 编辑 -> 首选项目录 中找到 Better BibTeX，设置引用键格式。

一个简单但可靠的 key 格式是“作者小写 + 年份”：

[auth:lower][year]

以作者 Chen、2023 年为例，生成结果是chen2023。如果同作者同年有多篇文献，插件会自动追加字母，形成chen2023a、chen2023b。这种 key 易于记忆，写在 Markdown 正文里也不会显得杂乱。

2.3 导出 .bib 并保持与正文一致

Better BibTeX 安装完成后，在 Zotero 中对某条文献或整个分类点右键，选择“Export Library”或“Export Collection”，导出格式选择 Better BibTeX，就能得到.bib文件。

导出内容大致如下，示例条目并不代表真实论文，仅用于展示字段结构：

@article{chen2023, title = {A Practical Pipeline for Reproducible Academic Writing}, author = {Chen, Wei and Li, Xin}, journal = {Journal of Research Practice}, year = {2023}, volume = {8}, number = {2}, pages = {100--115}, doi = {10.xxxx/example} }

这个.bib文件是整个写作流水线的数据源。后续 Pandoc 生成参考文献列表时读取它，Zotero 只是编辑界面的入口。导出文件建议提交到 Git，记录成随论文版本一起变化的历史。需要特别注意的是：修改 Zotero 里的文献后要重新导出.bib，否则正文引用的 key 虽然存在，但最终参考文献里的标题、作者、年份可能是旧版本。

3. 论文笔记：不要摘抄，要建立“问题-方法-结论”结构

3.1 用 Markdown 模板记录每一篇论文

读完一篇论文之后，如果笔记只是一段摘要或几段高亮，写作时几乎无法直接使用。更好的做法是在阅读时就建立一个固定模板，强迫自己回答几个问题：“这篇论文解决什么问题”“核心方法是什么”“实验如何证明效果”“对我自己的课题有什么启发”“有哪些可能存在的问题”。

下面是一个可以直接复制到本地笔记目录的模板：

# Paper note: <论文短标题> - Cite key: @<citekey> - Read date: YYYY-MM-DD - Related: [[另一篇笔记文件名]] ## 1. 论文在解决什么问题 ## 2. 核心方法是什么 ## 3. 实验和评价方式 ## 4. 结论是什么 ## 5. 与我课题的关系 ## 6. 可能的局限与可扩展点

模板不是格式负担，而是降低写作启动成本。看到Cite key这一行时，阅读者会意识到这条笔记必须和文献库中的条目建立关联。看实验章节时，不只是记录准确率，还要记录数据集划分方式、是否设置随机种子、是否报告多次运行方差。

3.2 用链接把笔记组织成知识网络

单篇笔记做得再完整，如果彼此之间没有链接，下一篇论文读完之后仍然难以形成体系。推荐的做法是使用支持 Wiki 链接的 Markdown 编辑器，比如 Obsidian、VS Code 加 Foam 插件等，在Related字段里记录与当前论文相关的其他笔记。

链接的意义在于：一篇笔记可以继承另一个问题的上下文。当你在写综述时，不需要重新阅读全部 PDF，只需要打开某个关键词范围内的笔记，顺着链接逐层追溯。笔记不是 PDF 的替代品，而是 PDF 的索引和压缩结果。

目录结构保持简单即可：

research-notes/ ├── README.md ├── 2024-literature/ │ ├── 2024-chen2023.md │ ├── 2024-wang2022.md └── ideas/ ├── 综述写作计划.md └── 实验扩展方向.md

3.3 定期把笔记整理成写作素材

每周或每完成一个小主题后，建议新建一份主题综述.md，把相关笔记链接复制进来，并按照逻辑顺序排列。例如整理“可复现实验”主题时，可以把关于随机种子、环境锁定、数据版本的三条笔记放在同一个文件里。这个文件最终会成为论文 Related Work 或方法章节的素材。

不要等到开始写论文才整理素材，因为那时阅读记忆已经淡了，重新翻 PDF 的成本很高。阅读完毕后花五分钟更新笔记，比写作时花两小时重新回溯原文高效得多。

4. 写作流水线：用 Markdown 写正文，让 Pandoc 处理格式

4.1 为什么用纯文本写作

论文最终通常要提交为 Word 或 PDF，但写作过程不一定直接使用 Word。Word 的问题不在于不好用，而在于版本差异、样式漂移和参考文献插件形成的隐式依赖。不同电脑打开同一个 docx，格式可能不同；期刊模板升级后，旧文档要手工迁移。

纯文本写作则可以让内容和格式分离。Markdown 负责内容结构，CSL 文件负责参考文献风格，Pandoc 负责把两者组装成最终文档。改稿时只看 Markdown diff，完成后再统一编译成投稿格式，最大程度减少“改内容时碰坏格式”的问题。

4.2 安装 Pandoc 和 PDF 编译环境

Pandoc 是文档转换工具，安装方式随操作系统不同而不同：

如果目标是生成带中文的 PDF，还需要安装 XeLaTeX 和一套中文字体。在 Ubuntu 上可以安装：

sudo apt install -y texlive-xetex fonts-noto-cjk

在学习环境里，不想折腾 LaTeX 也可以先生成 Word 文档，这样不需要额外安装 LaTeX 工具链：

pandoc manuscript.md --citeproc --bibliography=refs.bib --csl=ieee.csl -o manuscript.docx

4.3 最小可编译的写作示例

创建一个原文manuscript.md，内容先写两行，验证引用功能是否跑通：

--- title: "学术写作工作台示例" author: "Imbad0202" lang: zh-CN --- # 引言 学术研究技能需要从文献、笔记和实验三个角度分别建设 [@chen2023]。

再准备一份refs.bib，内容可以是第二节导出的条目。为了让 Pandoc 生成参考文献列表，需要指定一种参考文献风格，即 CSL 文件。IEEE 风格的 CSL 可以从已维护的样式仓库下载，也可以先从自带的简单样式开始。

执行下面的命令，生成 PDF：

pandoc manuscript.md \ --citeproc \ --bibliography=refs.bib \ --csl=ieee.csl \ --pdf-engine=xelatex \ -V CJKmainfont="Noto Sans CJK SC" \ -o manuscript.pdf

命令里的--citeproc表示启用参考文献处理，--bibliography指向.bib文件，--csl指定引用格式，--pdf-engine=xelatex负责处理中文，-V CJKmainfont指定正文字体。执行成功后会看到 PDF 中[@chen2023]被替换为类似[1]的编号，文末出现参考文献列表。

如果暂时不需要 PDF，可以删掉--pdf-engine和-V参数，直接生成同名的docx或html。重点是先把“正文 + 文献库 + 样式”这条链路跑通，再优化排版细节。

4.4 把编译相关文件放进独立模板目录

为了让每篇论文的目录清晰，建议把可变文件和工具依赖分开：

manuscripts/ └── 2026-survey/ ├── manuscript.md ├── refs.bib ├── csl/ │ └── ieee.csl └── output/ ├── manuscript.pdf └── manuscript.docx

manuscript.md和refs.bib是核心源文件，提交到 Git。output/是编译产物，可以通过.gitignore忽略。这样合作者或未来的你看到项目时，不会被一墙 PDF 文档干扰。

5. 可复现实验：让研究结果经得起重跑

5.1 用 venv 和 requirements.txt 锁定 Python 环境

实验能跑通和实验可以被别人跑通是两回事。最常见的问题是代码在本机使用了一组依赖版本，半年后换机器执行时报错，却无法定位是哪个库发生变化。

为每个实验创建独立虚拟环境，并把依赖导出为requirements.txt，是最低成本的可复现手段。创建命令如下：

python -m venv .venv source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1 pip install numpy pandas scikit-learn pip freeze > requirements.txt

之后任何人在新环境里执行：

python -m venv .venv source .venv/bin/activate pip install -r requirements.txt

就能安装与开发时一致的依赖版本。pip freeze会记录精确版本号，例如numpy==1.26.4，而不是numpy>=1.26。这种“锁定模型”适合学习阶段和单机复现。如果实验涉及系统级依赖、GPU 驱动或复杂服务，再考虑 Docker 镜像方式，但不要一开始就引入 Docker，先让项目具备最基础的三件套：虚拟环境、依赖清单、启动说明。

5.2 建立实验项目的标准目录

一个符合可复现原则的实验目录至少要区分原始数据、脚本、结果和日志，不要让所有文件都堆在一个根目录里。推荐目录如下：

experiment-project/ ├── README.md ├── requirements.txt ├── data/ │ ├── raw/ │ └── processed/ ├── scripts/ │ ├── train.py │ ├── evaluate.py │ └── preprocessing.py ├── notebooks/ │ └── analysis.ipynb ├── results/ │ └── 2026-02-01_run/ └── logs/

data/raw/存放原始数据，不经过代码修改；data/processed/存放预处理后的结果；results/按运行时间归档每次实验。README 要写清楚从原始数据到结果文件的执行顺序，例如：

# 实验运行说明 1. 创建虚拟环境：python -m venv .venv 2. 安装依赖：pip install -r requirements.txt 3. 运行预处理：python scripts/preprocessing.py 4. 训练模型：python scripts/train.py --seed 42 5. 评估结果：python scripts/evaluate.py --checkpoint results/2026-02-01_run/model.pt

5.3 固定随机种子并记录实验参数

机器学习类实验即使代码相同，多次运行结果也可能不同。差异来自随机初始化、数据加载顺序、并行计算顺序等。可复现实验需要把随机种子作为代码参数，并把种子值记录在实验日志里。

下面是一个最小种子管理示例：

import random import numpy as np def set_seed(seed: int = 42) -> None: random.seed(seed) np.random.seed(seed) try: import torch torch.manual_seed(seed) if torch.cuda.is_available(): torch.cuda.manual_seed_all(seed) except ImportError: pass if __name__ == "__main__": set_seed(42)

需要注意，设置随机种子并不能保证所有框架完全确定，GPU 上部分算子仍然存在非确定性。因此除固定种子外，最好在同一环境内重复运行多次并记录均值和方差，而不是只报告单次结果。

注意：可复现不等于“每次结果完全相同”，而是“在相同代码、相同依赖、相同数据条件下，结果保持一致并在合理范围内波动”。

6. 版本管理：论文草稿和实验代码一样值得提交

6.1 用 Git 追踪论文的每一版

论文写作中最怕的不是没内容，而是改到一半发现之前的方案更合理。如果只用文件名区分版本，“论文终版”最终会变成十几个文件，而且无法知道两个文件之间具体改了什么。

把论文目录初始化为 Git 仓库，可以在每次修改后提交一次：

cd manuscripts/2026-survey git init git add manuscript.md refs.bib git commit -m "初始化正文和参考文献数据"

后续每次完成一小节、修完一个引用错误，都提交一次。提交信息尽量说明改动目的，例如“补充方法章节公式推导”“修复实验数据描述不一致”，避免只写“修改”“更新”。

查看修改历史时使用：

git log --oneline git diff HEAD~1 manuscript.md

git diff会精确展示上一版和当前版之间的文本变化，这比肉眼对比 Word 文件可靠得多。论文写作进入投递阶段后，可以使用 tag 标记关键版本：

git tag v1.0-draft git tag v2.0-submitted

6.2 .gitignore 排除编译产物和临时文件

论文仓库中不应提交所有文件。LaTeX 辅助文件、Pandoc 编译输出、系统隐藏文件都应该排除。一个可用的.gitignore示例如下：

.DS_Store *.aux *.bbl *.blg *.log *.out *.fls *.fdb_latexmk output/ .venv/ __pycache__/ .ipynb_checkpoints/

保留原则很清晰：进入 Git 的是可再生成的源文件，即 Markdown、.bib、.csl、脚本配置；不需要进入 Git 的是可以由源文件重新生成的 PDF、Word、辅助缓存文件。如果确实需要交付 PDF，可以单独放到发布分支或通过单独发布渠道传送，不要因为几个 PDF 让仓库体积迅速膨胀。

6.3 分支用于大改动，Tag 用于版本切点

写论文时不一定使用复杂分支策略，但遇到“准备做一次大改，可能回不去”的情况，可以创建分支：

git checkout -b experiment-major-rewrite

需要回到投稿版本时切回原分支并比较差异：

git checkout main git diff main experiment-major-rewrite -- manuscript.md

Git 在这里的作用不是展示 DevOps 技术，而是给论文写作提供“撤销任意一步修改”的安全感。有了这种安全感，你才敢大刀阔斧重构一段论证。

7. 常见问题排查：引用失效、编译报错、复现失败

7.1 Pandoc 生成的 PDF 里引用显示为空

现象是正文中的[@chen2023]没有被替换成编号，而是原样保留或变成[]。排查时优先检查三点。

第一，命令是否包含--citeproc。新版 Pandoc 使用内置 citeproc，老版本可能依赖独立工具，命令缺少这个参数时引用不会被处理。

第二，--bibliography指定的路径是否正确。如果写的是refs.bib，但当前工作目录不是这个文件所在目录，Pandoc 会找不到文献库。

第三，.bib里是否存在对应的 cite key。打开refs.bib，搜索chen2023，如果搜不到，需要回到 Zotero 重新导出。

综合排查路径可以整理为下表：

7.2 中文 PDF 编译为空白或乱码

现象是生成 PDF 后中文文字不显示，或者整个文档报缺少字体。原因通常是默认引擎不支持中文字体，或系统缺少 CJK 字体。解决方案是使用--pdf-engine=xelatex并指定中文字体。Ubuntu 下先确认字体已经安装：

fc-list | grep -i "Noto Sans CJK"

如果命令没有输出，需要安装字体包fonts-noto-cjk，然后重新编译。这个问题不需要靠修改文档内容解决，属于环境配置问题，检查顺序是先确认字体存在，再确认引擎参数。

7.3 换机器后实验无法复现

现象是同一份代码在另一台机器上运行报错或结果明显不一样。最常见原因是requirements.txt未锁定精确版本，其次是代码中存在本机绝对路径。

检查顺序如下：

1. 查看requirements.txt中是否每个包都带==版本号。
2. 查看代码中是否出现/home/username/或C:\\Users\\这类硬编码路径，推荐改成相对路径或使用pathlib。
3. 查看数据是否被当作代码的一部分提交，如果data/raw/没有单独同步，结果自然不同。
4. 查看 README 是否写明了 Python 版本。pip freeze不会记录解释器版本，建议在 README 开头写清楚python=3.11这类约束。

修复方式是把发现的问题逐项更正，然后重新执行从虚拟环境创建到结果输出的全流程。

7.4 一个更稳妥的排错顺序

无论遇到哪类问题，建议按下面的顺序排查，避免一开始就怀疑工具链底层实现：

1. 输入是否一致：代码、文件路径、命令行参数是否正确。
2. 依赖是否一致：版本号、环境变量、系统字体是否安装。
3. 源文件是否最新：.bib是不是刚从 Zotero 导出、Markdown 是否保存。
4. 日志是否给出明确线索：Pandoc 报错、Python traceback、Git diff。
5. 工具版本是否匹配：Pandoc 内置 citeproc 与独立 citeproc 的行为差异。

8. 把整套技能沉淀成一个长期可维护的知识仓库

8.1 让仓库结构成为你的研究地图

很多人知道要管理文献、记笔记，但缺少一个总入口。建议仿照开源仓库的组织方式，为自己的研究建立类似下面这样的根目录：

academic-research-skills/ ├── README.md ├── bibliography/ │ └── main.bib ├── literature-notes/ │ ├── 2024-chen2023.md │ └── 2024-wang2022.md ├── manuscripts/ │ └── 2026-survey/ ├── experiment-templates/ │ ├── requirements.txt │ ├── scripts/ │ └── README.md └── checklists/ ├── pre-submission-checklist.md └── experiment-repro-checklist.md

README 是这个仓库的地图，它不需要很长，但必须写清“这个仓库里有什么”“哪份笔记对应哪篇论文”“如何重新生成实验结果”。当你把一套研究项目做成这样的结构后，它本身就是一个可展示、可复用、可持续迭代的作品。

8.2 投稿和归档前的检查清单

论文准备投稿、代码准备开源或实验准备归档时，建议执行下面的清单。这份清单可以直接复制到自己的checklists/目录中。

# 投稿前检查清单 ## 文献和引用 - [ ] Zotero 中重要文献元数据已核对 - [ ] refs.bib 已重新导出并提交 Git - [ ] 正文所有 cite key 均能在 refs.bib 中找到 - [ ] 编译命令包含 --citeproc，参考文献列表正常生成 ## 文档和编译 - [ ] manuscript.md 已在干净目录下重新编译为 PDF - [ ] 中文 PDF 字体显示正常 - [ ] output/ 产物已从 Git 排除，但源文件已提交 ## 实验和代码 - [ ] requirements.txt 中所有依赖带精确版本号 - [ ] Python 版本已写入 README - [ ] 随机种子保存在代码参数中并记录到实验日志 - [ ] data/raw/ 没有提交到 Git，但已有备份说明 - [ ] 从零开始执行 README 中的命令可以跑通全流程 ## 隐私和合规 - [ ] 未公开的数据、内部材料和隐私信息没有进入公开仓库 - [ ] 实验结果没有选择性隐瞒关键失败记录

8.3 下一步可以扩展的工程能力

上面这套流程跑通后，再往上扩展就顺理成章。例如用 Typst 替代 LaTeX 作为排版引擎，用 GitHub Actions 在每次提交后自动编译文档，用 Docker 保存复杂依赖的完整运行环境，用 DVC 管理数据文件版本。这些工具都是在基础流程跑通后才能发挥价值，不适合在论文还没动笔时优先研究。

学术研究技能本质上是一组可以被反复练习的工程习惯。文献管理练的是数据规范性，笔记练的是信息压缩能力，写作流水线练的是格式自动化，实验管理练的是严谨性，Git 练的是版本意识。把每一项都落实到可执行的操作上，你的研究效率提升会非常明显。对于刚进入科研环境的人来说，先从 Zotero 导入十篇文献、用 Markdown 写三篇笔记、运行一次 Pandoc 编译命令开始，是最有效的起步练习。