1. 我为什么把做研究这件事推翻重做OpenResearch 的由来我的研究项目第一次被人公开说复现不了是在一个技术社群里。对方贴出来的报错日志我盯了十分钟最终承认问题不在他的环境而在我的流程数据存在本地文件夹代码散落着十几个版本关键的超参写在我脑海里文献下载完就躺在默认下载目录里。那一刻我决定把整个研究过程推翻重做代号就叫 OpenResearch。OpenResearch 这个词我一开始误以为是指某个具体的软件平台。后来自己亲手搭过一遍才意识到它更像一套契约一种工作方式把你做研究的全过程——问题怎么提出、文献怎么筛选、代码在哪个环节写岔过、数据怎么清洗、结论怎么得到——尽可能完整地摊开在阳光下。它包含开放获取Open Access但远不止于此。我见过很多研究者和工程师同样陷入能跑就行整理以后再说的循环里。等到真要写技术报告、答辩材料或者博客复盘时才发现大量上下文已经丢失只能凭记忆往回找补。OpenResearch 要解决的正是这种过程黑箱不要求每个人都像发论文那样严谨地走完所有学术步骤但至少要把关键节点的决策和产物留下来让自己、让合作者、让后来关注这个项目的人都能顺着你的路径重新走一遍。这套方法适合谁我觉得至少有三类人一是正在写毕业论文、需要长期追踪文献和实验记录的研究生二是做技术选型、做竞品调研的开发者经常需要把为什么选了 A 而不是 B讲清楚三是内容创作者和独立研究者想把思考过程变成可复用的素材库。哪怕你现阶段做的只是一个小工具的评测按 OpenResearch 的方式留痕过三个月回看价值也远超文档本身。2. OpenResearch 的四层开放从文献到决策再到环境很多人一提开放研究第一反应就是把论文免费放到网上或者把代码 push 到公开仓库。这当然是对的但只是冰山一角。我自己的体会是完整的开放链条至少有四层每一层解决一个不同的问题。2.1 第一层信息源的开放这一层是大多数人已经熟悉的。用 Zotero 管理文献、把 PDF 和元数据同步到云端、把网页快照和笔记链接在一起让任何合作者都能看到你读了什么、引了什么而不是只看到一个让人头晕的参考文献列表。实际操作里有一个容易被忽略的细节不要只收藏 PDF要同时记录你获取它的路径。比如这篇论文是从某个会议的开放论文库下载的那篇技术报告是某公司官网的一个公开 PDF还有一份数据说明书是某个开源项目仓库里的 README。把这些来源写成永远跟着条目走的注释后续核对引用、补授权信息时会省下大量时间。2.2 第二层过程的开放这一层比信息源更难做到因为它反人性。我们从小被训练成展示结果、隐藏过程尤其是那些走弯路的过程。可恰恰是弯路决定了结论的可信度你试了三种方案两种失败你为什么判断它们失败你用了某个阈值这个阈值是拍脑袋定的还是从数据里扫出来的我采用了类似研究日志的机制每次连续工作结束往项目目录里的 research_log.md 追加几条记录内容包括今天做了什么、关键产出是什么、下一个决策点在哪里、此刻的情绪和信心如何。最后一条听起来很奇怪但几个月后回看它最能还原当时的真实判断。过程开放不需要让所有人看你的垃圾草稿只需要让自己和合作者在需要时能翻到。2.3 第三层产物与环境的开放代码、数据、环境配置这是另一个容易翻车的层次。我踩过最典型的坑是代码和图表都留下了但我已经记不清当时用的是什么 Python 版本、哪个依赖包的新版本改了接口。环境本身需要被当作研究产物来管理而不是默认反正都能跑。Docker 在这里特别有用但我不建议每个项目一上来就写一堆镜像。先尝试把依赖锁死Python 项目用 requirements.txt 或 uv.lockNode 项目用 package-lock.json。等确实需要复现比较重的环境时再上 Docker把 Dockerfile 连同构建依赖一起放进仓库。2.4 第四层结果与反馈的开放最后才是成果层面的开放。除了把报告发布到公开平台我更推荐在仓库里留一个反馈渠道GitHub Issues、评论区、邮件列表都行。OpenResearch 的闭环不是论文提交就结束而是让其他人真的去复现你的过程然后告诉你哪里对不上。那些复现不了的 issue 不是指责是最珍贵的校验信号。2.5 各层对应的落地产物开放层次核心问题典型工具关键产物信息源我读了什么从哪读到Zotero、Obsidian、RSS文献库、来源注释、阅读笔记过程我为什么这么做Markdown 日志、决策记录research_log.md、决策说明产物与环境结果能不能重跑Git、Docker、依赖锁文件仓库、镜像、requirements/uv.lock结果与反馈结论能不能被检验GitHub Pages、预印本、博客公开报告、复现说明、issue 讨论这张表不是一次性做完的。我也经历过只做第一层和第四层、中间全空的阶段。但哪怕只是把第二层研究日志补上整个项目的可信度都会明显上一个台阶。3. 搭建 OpenResearch 工作流目录、工具与初始化聊完理念直接上实操。我目前的 OpenResearch 项目统一使用一套目录结构不复杂但足够把上述四层内容各归各位。3.1 一个研究项目的标准目录结构my_research_project/ ├── README.md # 研究一句话介绍、当前状态、如何复现 ├── research_question.md # 研究问题、背景、假设 ├── research_log.md # 按时间追加的研究日志 ├── docs/ │ ├── sources.md # 文献与资料清单每一条带来源链接 │ └── decisions/ # 关键决策记录每条一页 ├── data/ │ ├── raw/ # 原始数据只读不修改 │ └── processed/ # 清洗后的数据生成脚本见 code/ ├── code/ │ ├── analysis/ # 分析脚本、实验脚本 │ ├── run.sh # 一键复现入口 │ └── requirements.txt # 依赖锁文件 ├── results/ │ ├── figures/ # 所有图表 │ └── reports/ # 最终报告 Markdown └── environment/ └── Dockerfile # 需要复杂环境时再补充这套结构有几个设计用意。data/raw 被当作只读目录任何清洗都输出到 processed这样原始数据和中间改动永远不会混淆docs/decisions 单独放是为了让为什么这类信息不被埋在长篇实验记录里run.sh 和 requirements.txt 放在显眼位置是给未来的自己或者陌生人准备的快速通道。3.2 我为什么选这些工具不追求酷追求三年后还能看懂你可能注意到这套目录里没有任何一件需要学习成本很高才能上手的东西。Markdown、Git、Python 脚本、可选 Docker全都是长期稳定的基础工具。我故意不引入太复杂的自动化编排、知识图谱、跨平台研究管理套件。原因很简单研究工具链最大的敌人是弃坑。越复杂的系统越需要持续维护而研究本身已经消耗大量心力一旦工具链需要频繁伺候人就会放弃记录。相反Markdown 文件三十年之后还是纯文本Git 几乎人人会用这套工作流就算你停更半年捡起来也不需要重新学习。选工具时我会问自己一个问题这套东西能不能在我最长的一次停滞后仍然无损恢复能才值得引入。3.3 五分钟初始化一个 OpenResearch 项目不需要什么脚手架直接终端操作。先把目录建好再初始化 Gitmkdir my_research_project cd my_research_project mkdir -p docs/decisions data/raw data/processed code/analysis results/figures results/reports environment touch README.md research_question.md research_log.md docs/sources.md git init git add -A git commit -m chore: init OpenResearch project structure然后往 research_question.md 里写一段话回答四个问题我在研究什么为什么现在研究它我目前知道的答案候选有哪些我打算怎样验证不需要写漂亮写真实想法就行。这一步的价值是把你脑袋里模糊的念头变成可讨论的文本后面的所有工作都会围绕它展开。4. 完整实战一个技术调研项目从问题到公开报告说一次真实的跑通经历。前段时间我想做一个技术选型调研主题是三种轻量级向量数据库在中文技术文档检索上的效果对比。这个项目我全程用 OpenResearch 流程走下来前后用了九天产出的不只是最终报告还有一套可以随时复现的完整路径。4.1 阶段一把模糊问题写成研究问题刚开始我的问题其实是向量数据库哪个好用。这太模糊了。我在 research_question.md 里把它改写成了一句具体的话在中文技术文档检索场景下A、B、C 三种向量数据库在召回准确率和中文长文本处理延迟上是否存在显著差异改写过程本身就是一次决策限定数据规模、限定语言、限定评估维度。我把这些限定写成了研究问题下的两行边界说明明确说本次不做分布式性能测试、不做混合检索比较。这样后续所有工作都有边界可依不会越做越发散。4.2 阶段二文献追踪与概念拆解接下来我没有急着跑实验而是花两天时间做信息整理。在 docs/sources.md 里按官方文档 / 社区评测 / 源码实现三类建立列表每一条都记录来源、发布时间、一句话要点。这里我依赖的阅读工具很朴素普通浏览器加上 Markdown 表格先把每个库的索引方式、默认参数、权量量化策略搞清楚。过程中我发现了几个需要进一步验证的疑点比如中文分词对某些库默认 tokenizer 的影响。这些疑点我直接追加到 research_question.md 的待验证问题清单里没有打断正在进行的阅读流程。这个习惯很小但能保证思路不断线。4.3 阶段三跑实验/采集数据的过程留痕实验阶段是最容易变混乱的。我的做法是每个脚本的输入、输出、时间戳都写在 research_log.md 里每次跑完测试集把结果追加到 results/raw_output.md如果发现某次结果异常不删数据而是在日志里说明今天 14:30 的结果因误用配置已废弃原因是 batch size 不一致。我还会把关键的启动命令原样留在日志里不是我跑了测试这种话而是完整的命令行包括环境变量。这样做的好处是当我在第五天想对比第一天的结果时可以直接照着自己写下的命令重新跑一遍而不需要靠记忆力去猜测当初的配置。4.4 阶段四写报告、留结论、公开仓库九天后我产出了最终报告其中结论部分只写了三页背景、测评方法、结论和局限。报告本身并不长但每个结论背后都指向仓库里可以复现的脚本和原始输出。我把代码和报告一并发到公开仓库并在 README 里写了五步复现说明从 clone 仓库到运行 run.sh全程没有需要手动安装的隐藏依赖。这次发布之后陆续有几个人通过 issue 反馈有说复现成功并补充了新数据的也有指出我选的数据集存在某些明显倾向性的。后者直接促成了我对报告局限部分的改写。反馈反过来变成了研究的一部分这正是第四层开放最有价值的地方。4.5 这个项目最终的增量收益如果只看最终报告九天时间似乎有点长。但后来我给团队做选型汇报时只需要把公开仓库的地址发过去对方就能看到每一步决策的来历各种追问几乎不需要我再解释。三个月后另一个同事要做相似选型直接 fork 了我的仓库换了一套数据就跑出来了。这些东西不能量化成某个 KPI但它们省下的解释成本和沟通成本极高。5. 翻车记录开放研究最容易踩的五个坑没有任何一套流程是在第一次尝试时就顺畅运转的。我把实操中反复踩过的坑整理出来每一条背后都是真实浪费过的时间。5.1 坑一陷入工具折腾忘记研究方向最开始做 OpenResearch 时我极其沉迷于搭建漂亮的知识库结构给每个笔记文件添加一堆 frontmatter、做自动化标签、写 Obsidian 插件式的模板。两周后我发现自己并没有产出任何研究进度全在折腾工具本身。这是最隐蔽的陷阱工具为你服务而不是你为工具服务。我的解决方法是工具冻结期项目进行中使用什么工具写在 README 里期间不允许更换、升级、换模板。想尝试新工作流等下一个项目再说。这个原始但有效的规则帮我砍掉了至少一半的无意义折腾。5.2 坑二把开放等同于无条件公开早期我确实有过一个误区觉得既然做开放研究那就应该把一切都发出去。但后来有一个合作项目涉及未公开的技术细节硬发只会带来风险。我才意识到开放不等于不顾边界OpenResearch 的开放是一层层递进的先开放给自己版本记录再开放给可信任的合作者私有仓库加权限最后才决定哪些部分可以公开。边界要主动画出来而不是默认全开也不是默认全关。5.3 坑三版本库直接装大文件有一次我把一份近 1GB 的实验数据集放进了 Git 仓库结果每次 pull 都变得痛苦一次误操作还会让仓库体积彻底失控。后来我把大文件和数据集的获取方式放进了仓库比如写好 download.sh 脚本和数据源链接原始数据本身用 Git LFS 或专用数据版本工具管理。记住一个原则代码进 Git数据别直接进仓库至少要经过取舍或压缩。5.4 坑四许可证和引用来源没处理好做开放研究不等于可以随意搬运别人成果。我在一篇博文里引用了别人的图表起初只放了链接后来对方读者指出应当明确标注授权协议。从那以后我在 docs/sources.md 里额外增加一列授权状态凡是还没确认的可视结果不允许直接出现在公开报告里。自己的代码和报告也要选好许可证MIT 与否不一样不要随便加上一句保留所有权利然后自己又搞不清规则。5.5 坑五研究日志写成了工作总结研究日志的初期我把它写成了今日已完成1、2、3明日计划4、5、6。这种清单式记录对回忆决策几乎没有帮助。后来我调整成五句话此刻研究还差什么、下一步最不确定的是什么、我当前偏好的答案是什么、有没有哪条证据动摇了我的观点、如果明天不继续哪些记录需要补。日志是写给未来的自己的不是写给领导的周报这两者的信息密度完全不同。6. 让 OpenResearch 长期运转的小习惯有了结构、工具和避坑清单最后决定这套方案能不能持续下去的通常是一些很小的习惯。它们不华丽甚至有点笨拙但确实让我坚持了下来。6.1 从开放给自己开始如果某天你非常忙、非常累那么今天不需要整理任何东西只需要保证一件事下次打开项目时能立刻知道上次进行到哪了。哪怕在 research_log.md 里多写半行话或者只更新一下待验证问题的一条状态都可以。把标准降到开放给自己而不是开放给世界执行阻力会小得多。公开共享是放大器不是起点。6.2 每次会话结束时写五句话我给自己定了一个近乎强制的规定每次连续工作结束时什么都可以不干但那五句话必须写。通常只花两分钟却能避免下一次我是谁、我在哪、我之前在干嘛的迷茫。这个小习惯坚持久了研究日志会自然变成你个人知识资产的一部分。6.3 把 AI 当成关键的讨论对手现在我的研究流程里AI 成了固定角色。我会把 research_question.md 里的内容直接抛给对话式工具让它帮我列出可能的反驳观点、提出遗漏的实验条件甚至检查我写出的复现步骤有没有歧义。但在 OpenResearch 的框架里AI 的产出永远不会被直接当作结论它只能作为讨论记录留在日志里。最终决策、验证和签名都必须是真实的研究者自己完成。我在实际使用中发现这套工作流最大的回报不是论文更好复现或报告更漂亮而是安全性它让你在半年后面对自己的旧项目时依然知道每一步是在什么条件下做出的选择。无论是做毕设、做选型报告还是写一篇深度博客这种可回放的安全感是任何一次性交付都无法替代的。如果你也经常被当时怎么跑的来着困扰不妨从下一个项目开始花五分钟初始化一个这样的目录并告诉自己先开放给自己再慢慢开放给世界。