一次组会上的尴尬让我彻底决定重构自己的研究工作流。当时合作者问我：“你的实验日志里那组对照试验，为什么把学习率设成0.002而不是0.001？”我翻了半个多小时的OneNote、Excel和微信聊天记录，最后只能含糊说一句“应该是试出来的”。这种状态在研究者中太常见了——文献有管理系统，笔记有笔记软件，实验有记录本，但它们之间没有任何通路，研究过程中的上下文被拆得七零八落。我后来花了大约四个月时间，逐步建立了一套名为OpenResearch的研究管理系统，它不是什么商业软件，而是一套以纯文本为核心、以自动化脚本为纽带的开放研究工作流。这套系统解决的核心问题只有一个：让研究过程中的每一个决策、每一次阅读、每一轮实验都有迹可循，并且可以低成本地共享给协作者。适合所有被文献淹没、被实验记录困扰、被协作沟通折磨的研究者参考。
1. 系统化之前的问题：文献堆积、笔记断裂与上下文丢失
1.1 文献管理解决的是“找得到”，不是“想得通”
我见过太多人把大量精力花在文献管理工具的玩出花上，文件夹分得极细、标签打了几百个，但真到写综述的时候依然抓瞎。我自己也有过同样的误区。当时我的Zotero库里有1260多篇文献，按主题分了二十多个子文件夹，做满了高亮和标签，看起来非常规整。但冷静一统计我才发现自己根本没做多少有效的知识转化：点开完整读过的不到300篇，精读并做了结构化笔记的不到80篇，而这80篇里能在三个月后准确复述核心方法细节的，可能只剩下三分之一。
问题出在认知上。文献管理工具的定位是“召回”，它回答的是“这篇文献存在哪个位置”，而不是“这篇文献到底对我正在做的课题意味着什么”。收藏和下载只是研究的最初级动作，真正的价值发生在你读完文献之后，用自己的语言把它的核心问题、方法逻辑、证据链条以及和当前课题的联系重新表达一遍。这个过程没有工具可以代替，只能靠主动加工。而主动加工如果没有一个固定的落点，很容易被忙碌的日常挤掉。所以OpenResearch的第一条设计原则就是：每一种输入，都必须有一个对应的输出位置，且这个位置有明确的格式要求。文献进了Zotero，仅仅是收集层完成；理解层的卡片笔记才是文献真正“内化”发生的地方。
1.2 笔记、实验、沟通三套体系之间的“信息考古”
做研究最消耗精力的事情之一，就是回看自己以前的决策过程。我曾经有三套并行的记录体系：文献在Zotero，思考碎片在OneNote，实验记录在Excel表格，和合作者的讨论则散落在微信和邮件的各个角落。表面上每个数据都有去处，但真正需要把它们组合成一个完整上下文时，我必须像做考古一样把碎片从各个系统里一个个挖出来拼接。
有一件事给我留下的印象很深。我整理一个模型训练日志，代码只有一份最终版本，但训练过程中的学习率做过三次调整，每次调整的原因分别写在微信、邮件和Excel备注里。三个月后我回看这份日志，代码能跑通，但我完全想不起来当时为什么在第二轮把batch size从32改成16，也找不到当时那个损失波动的截图。换句话说，我的记录里只有“做了什么”的结果，没有“为什么这么做”的过程。
这种上下文断裂的代价极其隐蔽，它不会在你当天意识到问题，而是在三个月后写论文、审稿人追问、或者合作者询问时才爆发。OpenResearch要解决的核心问题就是：让研究过程中的“上下文”本身被结构化管理起来。实验日志不仅记录代码和数据，还记录当时的假设、预期、意外现象以及现场判断。笔记不是零散的感想，而是有来源、有日期、有关联的知识卡片。所有这一切都存放在同一个文本仓库里，由Git记录每一次变更，这样任何一次决策过程都保留着可以回溯的时间线。
2. OpenResearch的架构拆解：把研究拆成收集、理解、实验、沉淀四层
2.1 四层分工与工具选型
在搭建OpenResearch之前，我先把研究过程抽象成四个阶段的循环。这个过程很关键，因为如果你不知道每个工具在整体闭环里承担什么角色，就会变成“装了一堆软件，最终还是用原来的方式工作”。
| 层级 | 回答的问题 | 核心载体 | 推荐的工具 |
|---|---|---|---|
| 收集层 | 我看到了什么 | 文献条目、网页快照、灵感 | Zotero + 浏览器扩展 |
| 理解层 | 我读懂了什么 | 卡片笔记、概念图、综述文档 | Markdown + Obsidian |
| 实验层 | 我做了什么、结果如何 | 实验日志、脚本、数据 | Python/Jupyter + Git |
| 沉淀层 | 我可以对外表达什么 | 论文初稿、技术报告、博客 | MkDocs + GitHub Pages |
表格里的分工我非常清楚。收集层管输入，保证任何来源的资料可以在几秒钟内入库；理解层管加工，把原材料转成自己的语言；实验层管验证，把理解落实到设计、试错和数据里；沉淀层管产出，把所有内容变成可以对外沟通的文档。四层之间的数据流动方向是固定的：收集层的文献条目在精读时生成一张理解层卡片，理解层的假设和疑问驱动实验层的设计，实验层的结果反过来修正理解层卡片，最后综合所有层的沉淀生成可用文档。
2.2 为什么底层一定要用纯文本和Git
我最先确定的是底层格式，而且没有经过太多纠结就直接选了纯文本Markdown。很多研究者习惯用Word或OneNote，但经历过几次格式错乱和数据迁移后，我对“格式锁定”非常警惕。
纯文本的核心优势有几个。第一，可读年限长。哪怕十年后所有商业软件都停止维护，纯文本文件还是能被任何文本编辑器打开。第二，不绑定具体工具。我可以在Obsidian里写、在VS Code里改、在手机上查看，随时替换软件而不影响数据。第三，方便程序处理。因为OpenResearch需要大量自动化脚本参与，纯文本是最容易读写的格式。第四，Git友好。Git对比文本文件的粒度比对比二进制格式好得多，每一次修改都能看到真正的差异。
Git是整个系统的第二根支柱。我之前并不理解“研究内容也需要版本管理”，直到有一次我写错了综述里的一个段落，越改越乱，特别想回到两天前的版本但找不到任何历史记录，才意识到版本管理对文本类研究资料同样重要。用上Git之后，每一张卡片、每一份实验日志都有了完整的历史，我不再担心改坏内容，因为任何时候都可以回滚。协作场景下，Git还让参与者的每一次贡献都留下清晰的轨迹，这比“最后发给我的那个版本”靠谱无数倍。
2.3 目录结构与命名规范：把强制秩序注入内容体系
研究过程是高度非结构化的，如果目录和命名规则也随性，那系统迟早会重新变成一团乱麻。我花了不少时间设计了一套目录结构，目的是让任何新内容都能立刻找到属于自己的位置，让检索不再是脑力负担。
openresearch/ ├── 01-collection/ # 收集层：文献元数据、网页存档 │ └── zotero-export/ │ └── library.json ├── 02-cards/ # 理解层：卡片笔记 │ ├── concepts/ # 概念卡片 │ └── papers/ # 文献阅读卡片 ├── 03-experiments/ # 实验层 │ ├── 2024-neurips-repro/ # 单个实验项目 │ │ ├── notes/ │ │ ├── scripts/ │ │ └── results/ │ └── 2025-ssl-continual/ └── 04-notes/ # 沉淀层：阶段性汇总 ├── literature-review/ └── weekly/命名规则是整套系统里最容易被忽视但回报率最高的投入。我的规则不多，但一旦定下就不再随意更改：
- 文献卡片：
[作者姓氏]_[年份]_[标题首词].md，例如vaswani_2017_attention.md - 实验目录：
[年份]-[主题缩写]，例如2024-neurips-repro - 实验日志：
[年月日]_[主题].md，例如20250412_finetune_lr_test.md - 内容版本：采用语义化版本号
v0.1.0，只在重要节点打Tag
命名规范的核心价值是让排序即信息。按文件名排序后，同一主题的文献卡片自然聚在一起，同一实验目录下的日志天然按日期排列。如果你发现自己还需要靠搜索框才能找到两天前刚写的内容，很可能是命名规则出了问题。
3. 从零搭建OpenResearch工作流：环境初始化、文献入库与笔记模板
3.1 初始化一个空仓库：最小动作跑通底层结构
搭建系统不需要等待“万事俱备”。我的建议是第一天只做三件事：建目录、开Git仓库、配置Obsidian工作站。
mkdir openresearch cd openresearch git init mkdir -p 01-collection 02-cards/concepts 02-cards/papers 03-experiments 04-notes echo "# OpenResearch" > README.md git add . git commit -m "chore: init open research workspace"这几行命令看起来简单，但含义很深：从第一秒开始，整个工作区就在版本控制之下。哪怕你什么都不做，这个空仓库也已经是一个可以随时存档和回溯的研究基底。
接着用Obsidian打开这个目录作为Vault。Obsidian本身不存储数据，它只是渲染纯文本Markdown的一层外衣。我一般会把新笔记的默认保存位置设置到02-cards，附件统一存到各实验项目的assets子目录，这样后期维护时不用满仓库寻找图片文件。Obsidian的好处是双链可以让你在卡片之间自由跳转，不过这里提醒一句：不要过度沉迷双链和关系图谱，它们只是辅助，结构化的书写和命名才是核心。
3.2 文献入库：用Better BibTeX把Zotero变成元数据引擎
Zotero我用了很长时间，但真正让它在OpenResearch里发挥关键作用的，是Better BibTeX这个插件。它的作用是给每一条文献生成一个稳定的引用键，也就是Citation Key，并且可以把整个文献库导出为结构化文件，供外部脚本消费。
我在Better BibTeX的设置里把Citation Key格式配置为[auth.lower][year][Verbatim:firstword]，这样一篇论文就会生成类似vaswani2017attention这样的稳定ID。设置完成后，将Zotero文献库导出为一个library.json文件，放在01-collection/zotero-export/目录下。这个文件就是整个研究系统的“元数据中心”。
接下来最关键的一步：写一个Python脚本，监听Zotero导出文件的变化，自动为每一条新文献生成一个空卡片笔记。这也是OpenResearch打通“收集→理解”的第一个自动化节点。
import json, re from pathlib import Path from datetime import date ZOTERO_EXPORT = Path("01-collection/zotero-export/library.json") CARDS_DIR = Path("02-cards/papers") def slug_from_key(key: str) -> str: return re.sub(r"[^a-z0-9]+", "_", key.lower()) def make_card(item: dict) -> None: key = item["citekey"] title = item.get("title", "Untitled") creators = item.get("creators", []) authors = ", ".join(c.get("lastname", "") for c in creators) year = item.get("year", "") fname = f"{slug_from_key(key)}.md" path = CARDS_DIR / fname if path.exists(): return text = f"""--- citekey: {key} title: "{title}" authors: {authors} year: {year} created: {date.today().isoformat()} status: unread --- # {title} ## 核心问题 ## 方法与数据 ## 结果与结论 ## 与我的课题的联系 ## 质疑与延展 """ path.write_text(text, encoding="utf-8") items = json.loads(ZOTERO_EXPORT.read_text(encoding="utf-8")) for it in items: make_card(it)这个脚本最值得注意的点是幂等性：如果卡片文件已存在，就直接跳过。这意味着你可以反复运行，绝不会覆盖已经写过的阅读笔记。每当我往Zotero里加入新文献、重新导出JSON后跑一次脚本，所有新文献就自动获得一张待阅读卡片，一条都不会漏。
3.3 阅读卡片模板设计：模板本身就是在训练思维
很多人觉得模板是束缚，我的体会恰恰相反，模板是在帮你强制建立研究思维的最低标准。我的文献卡片固定五个字段，一个都不允许少：
- 核心问题：这篇文献到底在解决什么问题？写不出来说明你还没读懂。
- 方法与数据：用了什么方法、什么数据，方法为何适配问题。
- 结果与结论：证据强度如何，结论是否被数据充分支撑。
- 与我的课题的联系：这是把文献和自己的工作链接起来的钩子，是整张卡片真正有价值的部分。
- 质疑与延展：保留批判空间，记录当前方法与结论的边界。
下面是我早期整理的一篇经典文献的卡片示例，不必完全照抄，但可以看出每个字段的长度和风格。
--- citekey: vaswani2017attention title: "Attention Is All You Need" authors: Vaswani, Shazeer, Parmar, et al. year: 2017 created: 2024-03-15 status: read --- # Attention Is All You Need ## 核心问题 用纯Attention机制替代RNN/CNN，解决序列建模中难以并行、长程依赖衰减的问题。 ## 方法与数据 - 提出Scaled Dot-Product Attention和Multi-Head Attention - 增加位置编码，去掉循环结构 - 在WMT 2014英德/英法翻译任务上训练 ## 结果与结论 英德达到28.4 BLEU，显著优于当时最优模型；训练成本大幅降低，证明Attention alone足够强大。 ## 与我的课题的联系 我做的长文本表示学习可以借鉴其相对位置编码思路；后续实验可以在Transformer基础上加对比学习目标。 ## 质疑与延展 - 位置编码是绝对式，对超长文本的外推能力有限 - 是否可以结合RoPE做更长上下文的实验？每个字段都在逼我完成一个具体的认知动作：弄清楚问题是什么、拆解方法、评估证据、连接自我、提出异议。一张卡片写完之后，这篇文献就真正属于自己的知识体系了。
4. 从单兵到小组：OpenResearch在多人协作中的落地与约定
4.1 共享仓库的协作约定：按文件粒度分工
研究做到一定程度，单兵作战就不够用了。我和几个合作者开始共享同一个OpenResearch仓库。原以为把Git推到GitHub就完事，结果首批协作就有了不少摩擦。
我们的最终方案是“按文件粒度分工”，这个约定看起来朴实但极其有效：每个成员负责自己的实验目录或综述章节，同一时间段内尽量不修改同一个文件。Git合并冲突大部分都源于多人同时编辑同一文件，这个约定直接从源头消除了冲突。代码类文件统一走Pull Request流程，由第二人Review后合入；文档类文件则允许直接推送，但要求提交信息写清楚“改了什么、为什么改”。
同时我们也意识到，不是每个合作者都愿意学Git命令行。我尝试过教大家用命令行，效果很差。后来换成GitHub Desktop，图形化界面的学习成本低得多，成员只需要学会 commit、push、pull 三个操作就够了。我们还在README里写了一份极简操作SOP，任何人加入项目，十分钟就能上手。
4.2 评审反馈的“文本化”流程：讨论必须留下轨迹
研究者之间最常见的沟通方式是什么？是开会讨论和即时通信。但这种沟通模式有一个硬伤：讨论的细节和结论只存在于聊天记录里，没有沉淀到研究资产中。几个月后回看一段微信语音，才发现当时的讨论已经和现在的方案完全对不上了。
我给团队设计了一个文本化评审模板，放在04-notes/reviews/目录下，每当有人提出意见，就新建一个文件：
## 评审人 ## 针对文档/实验 ## 疑问及原因 ## 修改建议（具体到行/段） ## 优先级：必须改 / 建议改 / 可选这个模板的价值在于迫使评审人把“我觉得有问题”具体化为“哪里有疑问、为什么有疑问、怎么改”。口头讨论经常含糊带过，而一旦要写下来，就得面对自己的逻辑。我们也约定：所有实验结论的验证，必须附上“复现路径”，也就是数据文件位置、脚本位置、参数配置，直接链接到实验日志。之后的评审就不再有“我觉得你结果不对”这种空谈，而是“我按你的复现路径跑了一遍，发现第80行学习率调度器设置与日志描述不符”。
4.3 协作的本质是共享上下文，而不只是共享文件
在协作实践中我越来越确认一个判断：研究协作最难的并不是文件同步，而是上下文共享。对方看你的代码和结果，如果不知道你的假设、约束和临场判断，就只能看到一堆“最终产物”。OpenResearch的价值在于它把研究过程的每一步都变成文本沉淀下来，所有协作者可以通过Git历史回溯一个决策的完整演变过程。这比任何聊天工具都可靠，因为我们不再依赖记忆和口头补充，而是依赖结构化的、可检索的记录。
5. 过去六个月踩过的坑与排查记录，每一条都是真金白银
5.1 坑：Better BibTeX的引用键在文献修订后变了，卡片全部失联
这个坑是我遇到的第一个比较大的事故。当时我对一条Zotero记录补充了作者信息，然后重新导出JSON并跑了卡片脚本，结果发现一批旧卡片的citekey字段和文件名全都对不上了。原因是Better BibTeX的默认引用键是根据条目当前内容实时生成的，一旦条目字段变化，键值就会跟着变。
排查过程比较煎熬。我一开始以为是脚本bug，反复调试了很久，最后才发现是Zotero条目本身变更导致生成规则触发更新。解决方案也简单：在Better BibTeX设置里把引用键生成规则固定下来，并且对所有已有条目执行“Pin”操作，锁定它们的引用键，禁止后续自动变更。
教训是：任何自动化链路都需要一个“不可变ID”，一旦数据被其他系统引用，就绝不能让它随源数据变化而变化。
5.2 坑：非技术协作者对Git的恐惧直接让协作流程停摆
有段时间团队协作者不敢动仓库，理由是“怕弄坏东西”。我一开始觉得Git已经很直观了，却忽视了不是所有人都熟悉命令行和版本概念。结果就是大家绕开Git，用微信传文件，甚至直接拿旧文件覆盖新文件，仓库一度出现内容回溯。
排查之后我调整了策略：前端命令行的使用频率降到最低，引入GitHub Desktop作为统一入口，并且在协作SOP里明确规定“只允许修改自己负责目录下的文件”。每天只做一次同步操作，减少操作频率也就减少了出错概率。这个调整之后，协作效率反而比强制所有人学命令行更高。
工具链必须匹配团队的技术舒适区。流程设计得再漂亮，如果执行成本超出成员的心理阈值，大家就会绕过它，最终一切都回到混乱状态。
5.3 坑：Windows下默认编码导致中文文献卡片乱码
这个坑纯粹是跨平台协作带来的。我在Windows上运行同样的Python脚本时，抛出了UnicodeDecodeError，而macOS上运行却一切正常。排查后才发现是Windows的Python默认编码和文件系统默认编码不一致，读取文件时使用了本地的GBK编码，导致UTF-8内容无法解码。
解决方案是在所有文件读写处强制指定encoding="utf-8"：
path.write_text(text, encoding="utf-8") content = path.read_text(encoding="utf-8")同时在仓库根目录的README.md里明确写入一条约定：整个仓库所有文本文件一律使用UTF-8编码，任何脚本严禁使用系统默认编码读写文件。这个坑让我意识到，跨平台协作时，编码问题不是“小概率事件”，而是必然事件。
5.4 坑：文件名里的时间戳制造虚假版本感
前期的实验日志我习惯用timestamp_topic.md命名，最早的原意是方便排序。但后来我修订文件时会顺手把文件名里的时间改成修订日期，导致同一份日志出现两个“版本”，而每个文件的内容又互相覆盖了一部分。协作者根本分不清哪个是最新的。
真凶其实是我自己对“版本”的理解出了问题：版本信息应该交给Git管理，而不是塞进文件名。我随后把所有文件名的时间戳全部移除，只保留主题性命名，日期全部由Git历史记录。文件名不再承担版本职责，而只承担“这个文件是关于什么的”这一职责。系统重新变得清爽。
6. 越用越顺的长期心得：OpenResearch如何变成真正的研究资产
6.1 让脚本把卡片库“压”成综述初稿
当卡片库积累到两三百张之后，我发现写文献综述开始变得飞快。因为每张卡片已经含有一个固定的结构化信息，我只需要写一个简单的脚本，按主题标签对卡片做分组和排序，然后生成一个按顺序排列的Markdown文档，就得到了一份综述的“初版骨架”。之后在此基础上人工串联逻辑、补充过渡段、修缮表达，效率远高于面对空白页面从零开始。
这段体验让我确信：如果阅读时的每一步都留下了结构化输出，最终的综合表达就会变得轻松自然。
6.2 知道不做什么：这套系统的边界
OpenResearch不是万能库。我用了一两年之后最重要的反思是：要克制“把所有东西都塞进来”的冲动。有一些内容是天然不适合进入纯文本仓库的，比如庞大的二进制数据文件、复杂的可视化图表工程等。我的原则是：仓库里只放“过程与结论的文本化表达”，原始数据和代码放在独立的数据管理系统中，实验层通过路径引用它们，而不是拷贝进入。
模板也要克制。很多刚开始搭建系统的人会陷入“为每类资料都设计模板”的完美主义陷阱。我最终只保留了四类模板：文献卡片、概念卡片、实验日志、周报。这个数量足够应对绝大多数场景，也不会让维护成本失控。
6.3 如果你今天开始，只做这三件事
第一件事：新建一个纯文本目录，执行git init。第二件事：装好Zotero与Better BibTeX，导出library.json。第三件事：选一篇你正在精读的文献，用核心问题、方法与数据、结果与结论、与我的课题的联系、质疑与延展这五个字段写一张卡片。
这三个动作半天就能完成。你不需要一步到位搭建出完整系统，也不需要一开始就用上脚本和自动化。结构会随着你的使用习惯慢慢长出来，关键是先建立起“研究过程值得记录，记录必须结构化”的意识。OpenResearch不是终点，而是一条让研究更加透明、可复现、可持续的长期路径。
