1. 项目概述：OpenResearch 不是“开源科研平台”，而是一套本地优先的学术研究 CLI 工具链
OpenResearch 这个名字听起来像某个大型基金会或学术联盟发起的倡议，但实际在开发者和研究者圈子里，它指的是一套正在快速演进的、以local-first（本地优先）为设计哲学的命令行研究工具集合。它的核心不是托管论文库，也不是搭建协作网站，而是把整个科研工作流——从文献检索、笔记整理、实验记录、代码复现到论文草稿生成——全部拉回到你自己的笔记本电脑上，用终端（Terminal / Command Line）作为主控界面。关键词里反复出现的CLI、orx、autoresearch都指向同一个事实：这不是一个点开即用的图形界面软件，而是一组可组合、可脚本化、可版本控制的命令行程序。
我第一次接触 orx 是在帮一位计算语言学博士生调试环境时。他不用 Zotero 同步云端文献库，也不用 Obsidian 插件自动抓取 PDF 元数据，而是直接在终端里敲orx search "multilingual llm alignment"，几秒后返回结构化 JSON 列表，再用orx fetch --pdf --bibtex一键下载全文和 BibTeX 条目，最后orx note --template litreview自动生成带时间戳和引用链接的 Markdown 笔记。整个过程没有网页跳转、没有账号登录、不依赖任何中心化服务——所有元数据缓存在本地 SQLite 数据库，PDF 存在~/research/papers/下按 DOI 哈希命名，BibTeX 文件由orx自动维护，连.gitignore都预置好了该忽略哪些临时文件。这就是 local-first 的真实手感：你的研究资产，从第一天起就完全在你掌控之中，而不是寄存在某家公司的服务器上。
对刚入门的研究者来说，OpenResearch 的价值在于打破“工具割裂”：文献管理用 Zotero，笔记用 Obsidian，代码用 VS Code，实验日志手写在 Notepad++，论文写作又切回 Word 或 Overleaf。这种频繁切换不仅损耗注意力，更导致关键上下文丢失——你在 Obsidian 里写的某条笔记，可能根本没关联到对应论文的 PDF 或复现代码。而 OpenResearch 的 CLI 设计强制你用统一语义建模所有动作：orx是入口命令，后面跟search/fetch/note/run/track/export等子命令，每个子命令都接受标准化参数（如--project my-llm-study指定工作区），输出结构化数据（JSON/Markdown/TOML），并默认将结果存入本地项目目录树。这意味着你可以用 shell 脚本把一整套流程串起来：orx search ... | jq '.results[0].doi' | xargs orx fetch ... && orx note ... && cd code && make reproduce。这种可编程性，才是它区别于传统科研工具的本质特征。
如果你常被这些场景困扰——文献下载后找不到原始 PDF、笔记里引用的代码仓库已删库、合作者发来的.docx论文修改意见无法追溯到具体段落、实验参数调了十几次却记不清哪次用了什么超参——那么 OpenResearch 提供的不是另一个 GUI 应用，而是一种新的工作范式：把研究当作软件工程来管理。它不承诺“一键解决所有问题”，但确保每一步操作都可审计、可重放、可协作。接下来我会从设计逻辑、核心命令实操、本地数据结构、以及真实踩坑经验四个维度，带你真正用起来。
2. 整体架构与设计逻辑：为什么必须是 CLI + local-first？
OpenResearch 的架构选择不是技术炫技，而是对当前科研工作流痛点的精准回应。我们先拆解两个关键词：CLI和local-first，它们共同构成了整个工具链的底层契约。
2.1 CLI 不是“复古”，而是为了可组合性与可审计性
很多人看到 CLI 就联想到“难用”“学习成本高”，这其实是混淆了“界面复杂度”和“系统复杂度”。GUI 应用把功能藏在多层菜单和弹窗里，用户点击时并不清楚背后执行了什么；而 CLI 的每个命令都是明文可见的操作契约。比如orx fetch --pdf --bibtex doi:10.48550/arXiv.2305.12345这条命令，你一眼就能看出它要做什么（获取 PDF 和 BibTeX）、作用对象是什么（指定 DOI 的论文）、以及关键参数（--pdf和--bibtex）。更重要的是，这条命令可以被：
- 管道传递：
orx search "retrieval-augmented generation" --limit 5 | jq -r '.results[].doi' | xargs -I {} orx fetch --pdf {} - 脚本封装：写成
weekly-review.sh，每周定时运行，自动更新文献库 - 版本控制：把
orx run --script train.py --config config.yaml命令写进Makefile，和代码一起提交 Git - 远程执行：在服务器上运行
orx track --experiment v2 --metric acc=0.87，结果自动同步到本地数据库
这种可组合性直接解决了科研中最常见的“流程黑箱”问题。当你在论文方法部分写“我们使用 HuggingFace Transformers 库进行微调”，读者无法验证你是否真的用了--learning_rate 2e-5还是5e-5；但如果你提供orx run --script train.py --config configs/roberta-base.yaml，别人 clone 仓库后只需一条命令就能复现全部环境和参数。CLI 的本质，是把研究动作从“人脑记忆”转化为“机器可读指令”。
提示：OpenResearch 的 CLI 设计严格遵循 Unix 哲学——“每个程序只做一件事，并做好”。
orx search只负责检索，不处理下载；orx fetch只负责获取资源，不解析内容；orx note只负责生成笔记模板，不管理知识图谱。这种解耦让工具链极其灵活：你可以用curl替代orx fetch，用pandoc替代orx export，只要输入输出格式一致，整个流水线不受影响。
2.2 local-first 不是“拒绝云”，而是重新定义数据主权
“本地优先”常被误解为“完全离线”，实际上 OpenResearch 的 local-first 指的是数据所有权和控制权的默认归属。它不禁止你同步数据到云端，但要求所有同步行为必须是显式、可逆、可审计的。对比传统方案：
| 场景 | Zotero + Web Sync | OpenResearch + orx |
|---|---|---|
| 新增一篇论文 | 在 Zotero 客户端拖入 PDF → 自动上传至 Zotero 服务器 → 其他设备从服务器拉取 | orx fetch --pdf doi:xxx→ PDF 存入~/research/papers/xxx.pdf→git add papers/xxx.pdf && git commit -m "add paper xxx"→ 手动git push origin main |
| 修改笔记 | 在 Obsidian 中编辑 → 插件自动同步到 iCloud/OneDrive | orx note --ref doi:xxx --content "key insight..."→ 生成notes/2024-05-20-doi-xxx.md→git diff查看变更 →git commit |
| 团队协作 | 共享 Zotero 群组库 → 成员编辑冲突需手动合并 | 每人维护独立research/目录 → 通过 Git 分支协作 → 冲突时用git mergetool解决 Markdown 差异 |
关键差异在于：Zotero 的同步是隐式的、中心化的、不可审计的（你不知道服务器上存了什么、何时存的）；而 OpenResearch 的所有操作都在本地文件系统留下明确痕迹，Git 日志就是你的研究审计日志。当某天你需要向期刊证明“实验是在特定 commit 下运行的”，你只需提供git log -n 10和orx track list --since 2024-05-01的输出，而非翻找几个月前的邮件或聊天记录。
2.3 autoresearch：自动化不是替代思考，而是解放认知带宽
autoresearch这个词容易引发误解，以为是要用 AI 自动生成论文。实际上，在 OpenResearch 语境中，它指的是将重复性科研操作自动化，从而让研究者聚焦于真正需要人类判断的部分。比如：
文献筛选自动化：
orx search "LLM safety" --year 2023-2024 | orx filter --min-citations 50 --has-code-repo --not-preprint | orx fetch --pdf --bibtex
这条命令链自动完成：检索近两年论文 → 过滤被引超 50 次、有公开代码、非预印本的论文 → 批量下载。省去人工点开 200 篇论文页面逐个判断的时间。实验记录自动化：
orx run --script train.py --config config.yaml --track--track参数会自动捕获：运行时间、GPU 显存占用、训练 loss 曲线（通过 TensorBoard 日志解析）、最终指标（从train.py输出中提取{"acc": 0.87, "f1": 0.79}），并存入本地 SQLite 数据库。下次你想对比不同超参效果，直接orx track compare --baseline v1 --target v2就能生成对比表格。论文草稿自动化：
orx export --format latex --section methods --include-code
自动从code/目录提取关键函数注释，从notes/目录聚合相关文献见解，生成 LaTeX 方法章节初稿。你不需要它写完整论文，但能帮你避免“知道要写什么却不知从哪下笔”的启动阻力。
这种自动化不是取代研究者的判断力，而是把“机械劳动”从认知循环中剥离。就像程序员不用手写汇编指令，而是用高级语言描述逻辑；研究者也不该把精力耗在手动整理参考文献、复制粘贴实验参数上。OpenResearch 的 autoresearch，本质是给科研工作流装上“自动挡”。
3. 核心命令详解与实操指南：从零开始构建你的本地研究工作站
安装 OpenResearch 并不复杂，但理解其命令体系是高效使用的前提。官方推荐使用pipx安装（避免 Python 环境污染），命令如下：
# 确保 pipx 已安装（macOS/Linux） python3 -m pip install --user pipx python3 -m pipx ensurepath # 安装 orx 主程序 pipx install openresearch-cli # 验证安装 orx --version # 输出类似：orx 0.8.3 (openresearch-cli 0.8.3)Windows 用户需额外安装 Windows Subsystem for Linux (WSL) 并在 WSL 中执行上述命令，因为orx的许多后端依赖（如 PDF 解析、LaTeX 编译）在原生 Windows 上支持有限。这是目前最稳妥的方案，比折腾 Cygwin 或 MSYS2 更可靠。
安装完成后，orx会自动创建默认配置目录~/.orx/，其中包含：
config.toml：全局配置（API 密钥、默认搜索引擎、PDF 存储路径等）db.sqlite：本地元数据数据库（存储文献信息、实验记录、笔记索引）templates/：自定义笔记/报告模板目录
下面我带你实操三个最常用场景：文献管理、实验追踪、笔记生成。每个步骤都附带原理说明和避坑提示。
3.1 文献管理：用 orx search/fetch/note 构建可审计的文献库
步骤 1：配置搜索引擎与 API 密钥
orx search默认使用 Semantic Scholar API，需申请免费 API Key（访问 https://www.semanticscholar.org/product/api，注册后获取）。编辑~/.orx/config.toml：
[search] engine = "semanticscholar" api_key = "your_semantic_scholar_api_key_here" [storage] papers_dir = "~/research/papers" notes_dir = "~/research/notes"注意：不要把 API Key 硬编码在配置文件里！正确做法是使用环境变量：
echo 'export ORX_SEMANTIC_SCHOLAR_API_KEY="your_key"' >> ~/.bashrc source ~/.bashrc这样即使配置文件被误传到 GitHub，密钥也不会泄露。
步骤 2：检索并下载论文
假设你要研究“大模型推理优化”，执行：
# 检索并查看前 3 条结果（JSON 格式，便于后续处理） orx search "large language model inference optimization" --limit 3 --json # 输出示例（简化）： # [ # { # "title": "FlashAttention: Fast and Memory-Efficient Exact Attention", # "doi": "10.48550/arXiv.2205.14135", # "year": 2022, # "citations": 1240, # "pdf_url": "https://arxiv.org/pdf/2205.14135.pdf" # } # ]确认目标论文后，批量下载 PDF 和 BibTeX：
# 下载指定 DOI 的论文（自动校验 PDF 完整性） orx fetch --pdf --bibtex doi:10.48550/arXiv.2205.14135 # orx 会执行： # 1. 创建 ~/research/papers/2205.14135.pdf（SHA256 哈希命名，防重名） # 2. 生成 ~/research/bibliography/flashattention.bib # 3. 在本地数据库中插入记录（含 DOI、标题、作者、年份、本地路径）步骤 3：生成结构化笔记
下载完成后，立即生成笔记模板，避免信息过载：
# 为该论文生成笔记（自动填充 DOI、标题、作者、PDF 路径） orx note --ref doi:10.48550/arXiv.2205.14135 --template litreview # 生成文件：~/research/notes/2024-05-20-flashattention-litreview.md # 内容包含： # --- # ref: doi:10.48550/arXiv.2205.14135 # title: FlashAttention: Fast and Memory-Efficient Exact Attention # authors: Tri Dao et al. # pdf_path: ~/research/papers/2205.14135.pdf # created: 2024-05-20T14:22:33+08:00 # --- # # ## Summary # [在此填写摘要] # # ## Key Insights # - [在此填写核心观点] # - [在此填写技术细节] # # ## Related Work # - [在此填写与其他工作的对比] # # ## Questions & Critiques # - [在此填写质疑与待验证点]这个模板的价值在于：它强制你用结构化方式记录思考，且所有字段（如pdf_path）都指向本地绝对路径，未来用grep -r "FlashAttention" ~/research/notes/就能快速定位所有相关笔记。
3.2 实验追踪：用 orx run/track 管理可复现的实验记录
科研中最痛苦的不是失败，而是成功后无法复现。orx track就是为解决这个问题设计的。
步骤 1：准备可追踪的实验脚本
orx run要求脚本输出结构化 JSON。以 PyTorch 训练脚本为例（train.py）：
# train.py import argparse import json import torch def main(): parser = argparse.ArgumentParser() parser.add_argument("--lr", type=float, default=2e-5) parser.add_argument("--batch_size", type=int, default=16) parser.add_argument("--model", type=str, default="bert-base-uncased") args = parser.parse_args() # 模拟训练过程... acc = 0.87 + (args.lr * 0.01) # 简化逻辑 f1 = 0.79 + (args.batch_size * 0.001) # 关键：输出 JSON 格式结果（orx track 会捕获此 stdout） result = { "metrics": {"acc": round(acc, 4), "f1": round(f1, 4)}, "params": vars(args), "hardware": {"gpu": torch.cuda.get_device_name(0) if torch.cuda.is_available() else "cpu"}, "timestamp": "2024-05-20T14:30:00+08:00" } print(json.dumps(result)) if __name__ == "__main__": main()步骤 2：运行并追踪实验
# 在项目根目录执行（orx 会自动检测当前 git commit） orx run --script train.py --config config.yaml --track \ --experiment "bert-finetune-v1" \ --notes "baseline with default params" # orx 会： # 1. 执行 python train.py --lr 2e-5 --batch_size 16 --model bert-base-uncased # 2. 捕获 stdout 的 JSON 输出 # 3. 记录当前 git commit hash、Python 版本、CUDA 版本 # 4. 将所有信息存入 ~/.orx/db.sqlite 的 experiments 表步骤 3：查询与对比实验
# 查看最近 5 次实验 orx track list --limit 5 # 输出示例： # ID | Experiment | Commit | Acc | F1 | Notes # ------|----------------|----------|-------|-------|----------------------------- # 123 | bert-finetune-v1 | abc1234 | 0.8700 | 0.7900 | baseline with default params # 124 | bert-finetune-v2 | def5678 | 0.8750 | 0.7920 | lr=5e-5, batch_size=32 # 对比两个实验的指标差异 orx track compare --baseline 123 --target 124 --metric acc,f1 # 输出表格： # Metric | Baseline | Target | Δ # -------|----------|--------|------ # acc | 0.8700 | 0.8750 | +0.0050 # f1 | 0.7900 | 0.7920 | +0.0020实操心得：
orx track的威力在于它把“实验”从模糊概念变成数据库记录。当你写论文时，方法部分的超参表格可以直接从orx track list --format csv > methods.csv生成；审稿人问“v2 版本相比 v1 提升了多少”，你只需发一条orx track compare命令截图。这比翻 Jupyter Notebook 或 Excel 表格可靠得多。
3.3 笔记与报告生成：用 orx export 实现内容复用
OpenResearch 的笔记不是孤立文档，而是可被其他命令引用的结构化数据源。orx export就是连接这些数据的枢纽。
步骤 1：为笔记添加语义标签
在notes/2024-05-20-flashattention-litreview.md中，补充 YAML front matter：
--- ref: doi:10.48550/arXiv.2205.14135 title: FlashAttention: Fast and Memory-Efficient Exact Attention tags: ["attention", "optimization", "memory"] ---orx export会扫描tags字段，实现跨笔记聚合。
步骤 2：生成文献综述章节
# 导出所有含 "attention" 标签的笔记，生成 LaTeX 章节 orx export --format latex --section literature --tags attention --include-pdf-links # 输出文件：export/literature.tex # 内容包含： # \section{Literature Review} # \subsection{Attention Mechanisms} # \begin{itemize} # \item \textbf{FlashAttention} (Dao et al., 2022): ... # \href{file:///home/user/research/papers/2205.14135.pdf}{[PDF]} # \end{itemize}步骤 3：生成实验报告 PDF
# 导出指定实验的完整报告（含指标、参数、硬件、相关笔记） orx export --format pdf --experiment 124 --include-notes --include-code # 生成 report-124.pdf，内含： # - 实验元数据（commit, time, hardware） # - 性能指标图表（从 TensorBoard 日志生成） # - 关键代码片段（从 train.py 提取） # - 相关笔记摘要（自动关联 tags 匹配的笔记）这个流程的关键在于：你不再需要手动复制粘贴内容。orx export读取的是本地数据库和文件系统中的结构化数据，确保报告永远与最新状态同步。当导师说“把实验结果更新到论文里”，你只需重新运行orx export，而非逐个修改 Word 文档。
4. 数据结构与本地存储机制：理解你的研究资产如何被组织
OpenResearch 的强大，源于其对本地文件系统的深度尊重。它不创造封闭的数据库格式，而是用标准文件类型（Markdown、JSON、SQLite、PDF）构建一个可被任何工具读取的研究资产层。理解其数据结构，是定制化和故障排查的基础。
4.1 项目目录树：你的研究工作区长什么样？
当你首次运行orx init my-llm-study，它会在当前目录创建标准结构：
my-llm-study/ ├── .orx/ # 项目级配置（覆盖全局配置） │ └── config.toml ├── papers/ # PDF 文件（按 DOI 哈希命名，防重名） │ ├── 2205.14135.pdf │ └── 2305.12345.pdf ├── bibliography/ # BibTeX 文件（按论文标题生成，可手动编辑） │ ├── flashattention.bib │ └── rag-benchmark.bib ├── notes/ # Markdown 笔记（时间戳+DOI 命名，含 YAML front matter） │ ├── 2024-05-20-flashattention-litreview.md │ └── 2024-05-21-rag-benchmark-methods.md ├── code/ # 实验代码（与 Git 仓库绑定） │ ├── train.py │ └── configs/ ├── experiments/ # 实验输出（TensorBoard 日志、模型检查点） │ └── v1/ ├── exports/ # 导出的报告（LaTeX、PDF、CSV） └── README.md # 项目说明（orx init 自动生成）这个结构的设计哲学是：所有内容都应能被 Git 管理，且无需专用工具即可阅读。你可以用 VS Code 打开notes/目录看笔记，用less查看bibliography/中的 BibTeX，用sqlite3 ~/.orx/db.sqlite直接查询数据库。OpenResearch 从不锁死你的数据。
4.2 本地 SQLite 数据库：元数据中枢
~/.orx/db.sqlite是 OpenResearch 的元数据大脑，包含以下核心表：
| 表名 | 作用 | 关键字段 |
|---|---|---|
papers | 论文元数据 | doi,title,authors,year,citations,pdf_path,bibtex_path |
notes | 笔记索引 | note_id,paper_doi,created_at,tags,content_hash |
experiments | 实验记录 | exp_id,git_commit,script_path,params_json,metrics_json,start_time,end_time |
runs | 单次运行快照 | run_id,exp_id,stdout_json,stderr_text,exit_code |
你可以直接用 SQL 查询，例如：
-- 查找所有被引用超过 100 次且有笔记的论文 SELECT p.title, p.citations, n.created_at FROM papers p JOIN notes n ON p.doi = n.paper_doi WHERE p.citations > 100 ORDER BY p.citations DESC;提示：
orx提供orx db query命令封装 SQL，但直接使用sqlite3更灵活。建议在~/.orx/目录下创建queries/子目录存放常用 SQL 脚本，如top-cited.sql。
4.3 配置文件：如何定制你的工作流
~/.orx/config.toml是全局配置，但每个项目可覆盖它。例如，在my-llm-study/.orx/config.toml中：
[search] engine = "arxiv" # 该项目只用 arXiv API，不走 Semantic Scholar [export] latex_template = "custom-report.cls" # 使用项目专属 LaTeX 模板 pdf_engine = "lualatex" # 指定 PDF 编译引擎 [tracking] auto_commit = true # 每次 orx run 后自动 git commit这种层级化配置（全局 → 项目 → 命令行参数）让你既能保持一致性，又能为特定项目灵活调整。
5. 常见问题与排查技巧实录：那些官网不会写的实战经验
在真实使用中，你会遇到各种意料之外的问题。以下是我在帮 12 位研究者部署 OpenResearch 时，高频出现的 5 类问题及解决方案。这些问题往往源于对 CLI 工作流的惯性思维，而非工具本身缺陷。
5.1 “orx search 返回空结果”：API 限频与代理配置
现象：orx search "keyword"无输出，或返回{"error": "rate limit exceeded"}。
原因：Semantic Scholar 免费 API 限制为 100 次/天，且对未设置 User-Agent 的请求更敏感。
解决方案：
- 设置 User-Agent（在
~/.orx/config.toml中）：[search] user_agent = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 ResearchBot/0.1" - 启用代理（如果所在网络访问 Semantic Scholar 不稳定）：
# 设置环境变量（注意：orx 会自动读取） export HTTP_PROXY="http://127.0.0.1:8080" export HTTPS_PROXY="http://127.0.0.1:8080" - 降级到 arXiv 搜索（免费且无限制）：
orx search "keyword" --engine arxiv --max-results 10
实操心得：不要迷信单一 API。我通常配置双引擎：
orx search默认用 Semantic Scholar，当失败时自动 fallback 到 arXiv。这需要写一个 wrapper 脚本，但一次编写，永久受益。
5.2 “orx fetch 下载的 PDF 打不开”：PDF 解析与权限问题
现象：orx fetch --pdf doi:xxx成功，但~/research/papers/xxx.pdf无法用evince或okular打开，提示“文件损坏”。
原因：部分预印本 PDF 由 LaTeX 生成，嵌入了特殊字体或加密，orx的 PDF 下载器（基于requests）可能未正确处理响应头。
解决方案：
- 强制重试并校验：
orx fetch --pdf --retry 3 --verify doi:xxx--verify会用pdfinfo命令检查 PDF 结构完整性。 - 手动下载并导入：
# 手动下载到临时位置 curl -L "https://arxiv.org/pdf/2205.14135.pdf" -o /tmp/manual.pdf # 用 orx 导入（保留元数据） orx import --pdf /tmp/manual.pdf --doi 10.48550/arXiv.2205.14135 - 配置 PDF 修复工具（需安装
qpdf）：# 在 config.toml 中启用自动修复 [storage] auto_fix_pdf = true
5.3 “orx track 无法捕获 GPU 信息”：CUDA 环境隔离
现象：orx run --track生成的实验记录中，hardware.gpu字段为空或显示cpu，尽管nvidia-smi正常显示 GPU。
原因：orx在子进程中执行train.py，而某些 CUDA 环境变量（如LD_LIBRARY_PATH）未被继承。
解决方案：
- 显式导出环境变量：
export LD_LIBRARY_PATH="/usr/local/cuda/lib64:$LD_LIBRARY_PATH" orx run --script train.py --track - 在
train.py中硬编码 GPU 检测（更可靠）：import torch gpu_info = torch.cuda.get_device_name(0) if torch.cuda.is_available() else "N/A" print(json.dumps({"hardware": {"gpu": gpu_info}})) - 使用
orx run的--env参数：orx run --env LD_LIBRARY_PATH="/usr/local/cuda/lib64" --script train.py --track
5.4 “orx export 生成的 LaTeX 编译失败”：模板与宏包缺失
现象：orx export --format latex生成.tex文件，但pdflatex report.tex报错! LaTeX Error: File 'hyperref.sty' not found.。
原因：orx默认使用精简 LaTeX 模板，依赖常见宏包，但你的系统未安装完整 TeX Live。
解决方案：
- 安装完整 TeX Live（Ubuntu/Debian）：
（注意：约 4GB，但一劳永逸）sudo apt update && sudo apt install texlive-full - 指定轻量级引擎（推荐）：
# 使用 tectonic（Rust 编写的现代 LaTeX 引擎，自带宏包） orx export --format pdf --pdf-engine tectonic - 自定义模板：复制
orx默认模板到~/.orx/templates/，在导言区添加\usepackage{hyperref}等缺失宏包。
5.5 “团队协作时 Git 冲突频繁”：Markdown 合并策略优化
现象：多人编辑notes/下的 Markdown 文件，git merge时产生大量冲突，尤其在 YAML front matter 部分。
原因：YAML 的缩进敏感性和多行字符串格式，使 Git 的默认文本合并器失效。
解决方案：
- 配置 Git 合并驱动（在项目根目录
.gitattributes中）：*.md merge=union *.bib merge=unionunion策略会合并所有行，而非尝试智能合并。 - 使用结构化笔记格式：避免在 YAML 中写长文本，改用：
这样 Git 只需合并 Markdown 正文，YAML 部分极少变动。--- ref: doi:xxx tags: ["tag1", "tag2"] --- ## Summary <!-- summary content here --> - 引入 pre-commit hook：安装
pre-commit，添加yamllint检查，确保 YAML 格式统一，减少因格式差异导致的假冲突。
最后分享一个小技巧：我习惯在
notes/目录下创建WIP/子目录存放未完成笔记，正式笔记只放在主目录。这样orx export默认忽略WIP/，避免未成熟想法污染正式报告。这个约定虽简单，却极大提升了团队协作效率。
我在实际使用中发现，OpenResearch 的学习曲线不在命令本身，而在重构你的工作习惯。当你第一次用orx track记录实验，而不是截图发到微信群；当你第一次用orx export生成论文初稿，而不是手动复制粘贴；当你第一次在git log里看到完整的科研轨迹，而不是靠记忆拼凑——那一刻，你才真正体会到 local-first 的力量。它不承诺更快发表，但确保每一步都扎实可溯。
