1. 从零搭建一个叫“OpenResearch”的东西到底在搭什么第一次看到“OpenResearch”这个词很多人脑子里蹦出来的画面是某个开源社区里挂着的一堆论文、数据集和代码仓库。但真到自己动手要做一个叫这个名字的项目时问题就来了它到底是一个工具、一个平台、一套流程还是一种协作方式我最初也卡在这个定义上后来想明白了一件事——名字本身不重要重要的是你打算用它解决什么具体问题。我做的这个 OpenResearch定位很朴素给一个小团队或者个人研究者用的轻量级研究协作底座。它不追求大而全不试图替代任何成熟的商业平台核心目标只有三个第一把研究过程中散落在各处的资料、笔记、代码、数据统一管起来第二让协作的人能快速知道“谁在做什么、做到哪了、结论是什么”第三所有产出物可追溯、可复现。说白了就是让研究这件事从“一个人闷头搞”变成“有结构、有记录、能交接”。为什么我要强调“轻量级”和“小团队”因为我在实际工作中见过太多团队一上来就搞重型平台结果配置成本比研究本身还高最后没人用。OpenResearch 的设计哲学是能用文件夹和文本文件解决的绝不引入数据库能用一条命令跑通的绝不写三行配置。这个原则贯穿了整个搭建过程后面你会看到它在每个技术选型上的体现。这篇文章适合谁看如果你是一个正在做个人项目的研究者、一个三五个人的小团队负责人或者你只是单纯想给自己搭一套“研究外脑”那接下来的内容可以直接抄作业。我会把每一步为什么这么做、踩过什么坑、有哪些替代方案都讲清楚。全文基于我实际搭建和运行三个月的经验不是纸上谈兵。2. 技术选型为什么我放弃了数据库和重型框架2.1 存储层纯文件系统 Git够用且省心OpenResearch 最核心的决策是不引入任何数据库。所有研究资料——笔记、实验记录、数据文件、代码片段——全部以文件形式存放在一个目录树里用 Git 做版本控制。这个选择一开始被团队里的小伙伴质疑“没有数据库怎么检索怎么管理元数据”我的回答是检索用 grep 和 ripgrep元数据用 YAML front matter。具体来说每一条研究记录是一个 Markdown 文件文件头部用 YAML 写元信息--- title: 实验-20240512-模型A与模型B对比 author: 张三 date: 2024-05-12 status: done tags: [对比实验, 模型A, 模型B] related: [实验-20240510-基线复现] ---这样做的好处非常直接第一任何文本编辑器都能打开不依赖特定软件第二Git 天然记录每一次修改谁改了什么一目了然第三迁移成本为零换个电脑直接 clone 就行。我实测下来一个五人团队三个月产生的约 800 个 Markdown 文件用 ripgrep 全文搜索的响应时间在 50 毫秒以内完全满足日常需求。注意文件命名一定要有统一规范。我采用的是“类型-日期-简短描述”的格式比如exp-20240512-ab-comparison.md、note-20240510-paper-reading.md。这样即使不打开文件光看文件名就能大致知道内容也方便脚本批量处理。2.2 协作层Git 工作流 约定式提交协作这块我没有引入任何额外的协作工具就是标准的 Git 工作流。但有一个关键设计每个研究任务对应一个分支分支名就是任务 ID。比如task/exp-20240512-ab-comparison。任务完成后合并到main分支同时打一个 tag。为什么不用 Pull Request 那套因为小团队里 PR 的仪式感太重了。我们的做法是分支推上去之后在团队的即时通讯群里发一条消息附上分支名和一句话说明其他人有空就 review没空就直接合并。流程的目的是让信息流动不是制造审批节点。当然如果某个改动涉及核心结论我们会强制要求至少一个人 review 后才能合并。这里有一个我踩过的坑二进制文件不要直接放进 Git 仓库。早期我们把实验产生的模型文件、数据集直接 commit 进去结果仓库体积两周内从 10MB 涨到了 2GBclone 一次要等好几分钟。后来改成用 Git LFS 管理大文件或者干脆把数据文件放在共享目录里Git 里只存路径和校验和。这个教训很深刻Git 适合管文本不适合管大二进制。2.3 自动化层Makefile Shell 脚本拒绝复杂编排很多团队一提到自动化就想到 Airflow、Prefect 这些编排工具。我的观点是如果你每天要跑的任务不超过 20 个依赖关系不超过三层Makefile 就是最好的编排工具。OpenResearch 里所有重复性操作——生成日报、检查文件命名规范、汇总实验状态——全部用 Makefile 和 Shell 脚本实现。举个例子我们有一个make daily命令它会做三件事扫描过去 24 小时内新增或修改的 Markdown 文件提取其中的status字段生成一份汇总报告输出到reports/daily-YYYYMMDD.md。整个脚本不到 40 行但每天帮团队节省了至少 15 分钟的手动整理时间。daily: find . -name *.md -mtime -1 -exec grep -l status: {} \; | \ while read f; do \ echo ## $$f; \ sed -n /^---$$/,/^---$$/p $$f | grep -E title|status|author; \ echo ; \ done reports/daily-$$(date %Y%m%d).md echo 日报已生成: reports/daily-$$(date %Y%m%d).md这个脚本很糙但够用。工具的价值在于解决问题不在于技术先进。我见过太多团队花两周搭一套漂亮的自动化流水线结果研究本身没推进多少。3. 目录结构设计让信息自己会说话3.1 顶层目录的划分逻辑OpenResearch 的目录结构经过了三版迭代才稳定下来。第一版是按项目分第二版是按时间分最终版是按研究阶段分。为什么因为研究发现团队最常问的问题是“这个实验做到哪一步了”和“上次那个结论的原始数据在哪”。按阶段分能直接回答这两个问题。最终的顶层目录是这样的openresearch/ ├── 00-inbox/ # 临时想法、未分类资料 ├── 10-literature/ # 文献笔记、论文摘要 ├── 20-experiments/ # 实验记录、配置、结果 ├── 30-analysis/ # 分析脚本、图表、结论 ├── 40-writing/ # 论文草稿、报告 ├── 90-archive/ # 已完成或废弃的内容 └── reports/ # 自动生成的汇总报告编号前缀是为了让目录在文件管理器中自然排序同时留出插入空间。比如以后想加一个“数据管理”阶段可以用15-data/。不要用 01、02 这种连续编号否则插入新目录时要么改一堆名字要么忍受乱序。3.2 每个阶段内部的命名约定以20-experiments/为例内部结构是20-experiments/ ├── exp-20240510-baseline/ │ ├── README.md # 实验目的、配置、结论摘要 │ ├── config.yaml # 实验参数 │ ├── run.sh # 复现脚本 │ ├── results/ # 原始结果 │ └── figures/ # 生成的图表 └── exp-20240512-ab-comparison/ └── ...每个实验一个目录目录名就是实验 ID。README.md是必须的而且我要求它必须包含四个部分目的、配置、结果、结论。目的用一句话说清楚为什么要做这个实验配置列出所有非默认参数结果放关键数字或图表链接结论用一两句话总结。这个要求看起来简单但执行起来会发现写不清楚结论的实验往往是因为实验本身设计得就不清楚。提示run.sh必须能在新环境里一键复现。我要求团队里每个人在提交实验时都要在干净目录里跑一遍run.sh确保没有隐藏依赖。这个习惯帮我们避免了很多“在我电脑上能跑”的尴尬。3.3 文献笔记的“三行摘要”规则10-literature/里的每篇文献笔记我强制要求开头写三行摘要这篇文献解决了什么问题、用了什么方法、结论是什么。三行每行不超过 50 字。这个规则来自一个痛苦的经历早期我们写文献笔记动辄上千字结果三个月后回头看自己都找不到重点。三行摘要强迫你在读完之后立刻提炼核心如果写不出三行说明你还没读懂。文献笔记的文件名格式是lit-第一作者姓氏-年份-关键词.md比如lit-zhang-2024-attention.md。这样在目录里一眼就能看到某一年某个作者的工作比按标题命名实用得多。4. 日常运转从“今天做什么”到“这周产出了什么”4.1 每日站会的替代方案异步日报小团队最怕开会。我们试过每天 15 分钟站会结果经常拖到 30 分钟而且有人为了赶会打断深度工作。后来改成异步日报每个人在当天结束前在reports/下建一个以自己名字命名的文件写三件事——今天做了什么、遇到什么问题、明天计划做什么。格式不限但必须写。这个改变带来的效果出乎意料。第一写日报的过程本身就是一次自我梳理很多人写着写着就发现了问题第二日报有记录周复盘时直接翻看即可不用凭记忆第三文字比口头表达更精确很多在站会上说不清楚的技术细节写下来反而清晰了。我自己的日报模板是这样的## 2024-05-12 日报 - 张三 ### 今日完成 - 完成模型A与模型B在数据集C上的对比实验A的F1比B高2.3个点 - 整理了实验配置到 exp-20240512-ab-comparison/config.yaml ### 遇到问题 - 模型B在长文本上推理速度明显下降怀疑是注意力机制的问题明天查文献确认 ### 明日计划 - 阅读 lit-li-2023-longtext.md 并写三行摘要 - 如果确认是注意力问题设计一个消融实验4.2 周复盘的“三个问题”框架每周五下午团队花 30 分钟做一次复盘。复盘不讨论具体技术细节只回答三个问题这周最重要的产出是什么最大的阻塞是什么下周最重要的一件事是什么每个问题每人用一句话回答轮流说不展开讨论。如果某个问题需要深入讨论另约时间。这个框架的好处是强制优先级排序。研究工作中很容易陷入“什么都做了一点但什么都没做完”的状态。三个问题逼着你选出最重要的事而且因为要当众说你会更认真地思考。我印象最深的一次一个成员说“这周最重要的产出是确认了方案X不可行”大家一开始笑了但仔细一想排除一个错误方向本身就是重要产出。4.3 月度归档把“已完成”变成“可检索”每个月最后一天我们会做一次归档操作。所有status: done的实验和笔记从20-experiments/和10-literature/移动到90-archive/下对应的月份目录里。移动之前脚本会自动提取每个文件的元数据生成一个索引文件90-archive/index-202405.md。这个索引文件长这样文件标题作者完成日期标签exp-20240512-ab-comparison模型A与B对比张三2024-05-12对比实验lit-zhang-2024-attention注意力机制综述李四2024-05-10文献有了这个索引找东西就不用翻目录了直接搜索引文件就行。归档不是把东西藏起来而是换一种更高效的方式组织。我强烈建议每个小团队都建立自己的归档索引机制哪怕只是一个 Markdown 表格。5. 踩过的坑与对应的解法5.1 坑一文件命名混乱导致检索失效项目运行到第三周的时候问题爆发了。有人用实验1.md有人用experiment_2024_05_12.md还有人用中文名对比实验-最终版.md。结果就是你知道某个文件存在但就是搜不到。ripgrep 再强大也架不住命名没有规律。解法是制定一份命名规范文档放在仓库根目录的CONTRIBUTING.md里并且写了一个检查脚本make lint在每次提交前运行。脚本会检查所有新增的 Markdown 文件是否符合命名正则不符合就报错并拒绝提交。规范的核心就三条全小写、用连字符分隔、以类型前缀开头。简单但有效。# 检查新增文件命名 git diff --cached --name-only --diff-filterA | grep \.md$ | while read f; do basename$(basename $f) if ! echo $basename | grep -qE ^(exp|lit|note|report)-[0-9]{8}-[a-z0-9-]\.md$; then echo 命名不符合规范: $f exit 1 fi done5.2 坑二元数据字段不统一YAML front matter 刚引入时每个人写的字段都不一样。有人写author有人写authors有人写date有人写created。结果就是自动汇总脚本经常漏掉文件。元数据不统一自动化就是空中楼阁。解法是定义一个最小元数据集只有五个字段是必须的title、author、date、status、tags。其他字段随意但这五个必须存在且格式正确。status只允许四个值todo、doing、done、blocked。这个约束看起来死板但正是这种死板让自动化成为可能。我后来甚至写了一个 VS Code 的 snippet新建 Markdown 文件时自动插入这五个字段的模板进一步降低了执行成本。5.3 坑三Git 冲突处理不当导致工作丢失有一次两个人在同一个实验目录下工作一个人改了README.md的结论部分另一个人改了配置部分合并时产生了冲突。处理冲突的人图省事直接选了“接受当前更改”结果另一个人的修改丢了。虽然 Git 历史里还能找回来但当时确实造成了混乱。解法是按文件类型分工。约定README.md的结论部分由实验负责人写其他人只读配置文件由具体执行人改结果文件只追加不修改。如果确实需要改别人的文件先在群里说一声。技术问题往往要靠流程解决Git 的冲突解决机制再强大也抵不过一个清晰的协作约定。6. 这套东西跑起来之后实际效果怎么样6.1 量化收益时间都省在哪了运行三个月后我粗略统计了一下团队五个人平均每人每周花在“找东西”上的时间从原来的约 3 小时降到了 40 分钟。省下来的时间主要来自三个方面不用反复问“那个文件在哪”检索效率提升、不用重新跑已经跑过的实验复现脚本齐全、不用凭记忆写周报日报和周报自动汇总。另一个意外收益是新人上手时间缩短。以前一个新成员加入至少要两周才能搞清楚项目全貌。现在只要给他仓库地址让他读README.md和最近一个月的reports/两天就能开始干活。因为所有决策的背景、实验的结论、当前的阻塞都写在文件里了。6.2 质性变化研究习惯的转变比数字更重要的是习惯的变化。最明显的一点是大家开始主动写结论了。以前实验做完结果往那一放就完事。现在因为README.md里必须写结论而且结论会被索引和检索大家会更有意识地思考“这个实验到底说明了什么”。这种思考反过来又提升了实验设计的质量。还有一个变化是对“可复现”的重视。因为run.sh是强制要求的而且每周会随机抽一个实验在干净环境里跑一遍验证大家写脚本时会自觉避免硬编码路径、隐藏依赖这些问题。可复现不是一种技术而是一种纪律这套流程就是在培养这种纪律。6.3 什么情况下这套方案会不够用说实话OpenResearch 这套方案有明确的边界。如果你的团队超过 10 个人或者每天产生的文件超过 100 个纯文件系统 ripgrep 的检索方式就会开始吃力。这时候可以考虑引入一个轻量级的全文搜索引擎比如 Meilisearch 或者 Typesense它们都能直接索引 Markdown 文件配置也简单。另一个边界是实时协作。Git 的工作流是异步的如果你需要多人同时编辑同一个文档那还是得用支持实时协同的编辑器。我的建议是研究记录用 Git实时讨论用其他工具两者不要混。我们团队用 Git 管所有正式产出用即时通讯管日常沟通边界清晰互不干扰。7. 如果你也想搭一套从哪开始我的建议是不要一上来就搞全套。先做最小可行版本建一个 Git 仓库定一个目录结构写一份命名规范然后坚持两周。两周之后你会发现哪些规则是必要的哪些是多余的。流程是长出来的不是设计出来的。具体起步步骤就四步第一git init一个空仓库建00-inbox/和20-experiments/两个目录第二写一个最简单的README.md说明目录用途和命名规则第三要求每个人每天往00-inbox/里扔至少一条记录格式不限第四每周五花 15 分钟一起整理00-inbox/把内容归类到对应目录。坚持一个月你会发现自己对“研究管理”这件事的理解完全不一样了。工具是次要的习惯才是核心。我见过用 Notion 管得井井有条的团队也见过用 Git 管得一团糟的团队差别不在工具在于是否真的把“记录和整理”当成了研究工作的一部分。最后分享一个我自己的小技巧在仓库根目录放一个NOW.md文件里面只写一句话——当前最重要的一件事是什么。每次打开仓库先看这个文件避免被各种细节带偏。这个文件每周更新一次内容可以很具体比如“完成模型A在数据集C上的消融实验”也可以很抽象比如“想清楚方案X到底可不可行”。一句话但能救命。