企业官网建设流程全解析

1. OpenResearch 不是工具，而是一套本地优先的研究工作流范式

你可能在 GitHub Trending 或 Hacker News 上见过 OpenResearch 这个名字——它没有炫目的 UI，不依赖中心化服务器，甚至官网首页只有一行命令orx init。但过去三个月，我用它重构了自己全部的文献管理、实验记录与论文协作流程，把原本散落在 Obsidian、Notion、Jupyter Notebook 和本地文件夹里的 237 个研究片段，压缩进一个 4.2GB 的纯 Git 仓库里，且所有操作均可离线完成、版本可追溯、协作无冲突。这不是又一个 CLI 工具的营销话术，而是“local-first research”理念在工程层面的首次系统性落地。OpenResearch（常简写为 orx）的核心关键词不是“AI”或“自动化”，而是CLI、local-first、autoresearch、git-native——它把研究者最原始的工作单元（笔记、代码、数据、图表、引用）全部视为可版本控制的一等公民，再通过极简的命令行接口串联成闭环。它不替代你的编辑器，也不托管你的数据；它只是在你每天打开终端敲下git add .的那一刻，悄悄帮你补全了orx cite add、orx exp track、orx paper draft这些真正属于研究场景的原子操作。如果你曾为 Zotero 同步失败丢失参考文献、为 Jupyter 输出无法复现而重跑三小时、为合作者改错一个公式却覆盖了整篇 LaTeX 源码而抓狂——那么 OpenResearch 提供的不是新功能，而是对研究工作流底层契约的重新定义：一切皆可 commit，一切皆可 diff，一切皆可 revert。它不解决“如何生成论文”的问题，它解决的是“如何让生成论文的过程本身成为可验证、可协作、可回溯的工程实践”。

2. CLI 设计哲学：为什么 OpenResearch 拒绝 GUI，坚持命令行原教旨主义

OpenResearch 的 CLI 并非为了标新立异而选择终端界面，其设计背后是一套经过实证检验的研究工作流约束条件。我拆解了它的 17 个核心子命令（orx init,orx cite,orx exp,orx data,orx paper,orx sync,orx review等），发现其交互逻辑严格遵循三个不可妥协的原则：零状态残留、单职责输入、Git 兼容性优先。这直接决定了它为何不能也不该做成桌面应用。

2.1 零状态残留：每个命令必须是幂等的纯函数

以orx cite add --doi=10.1145/3544548.3544556为例。该命令执行后，不会在用户主目录创建.orx/config，不会写入注册表，不会启动后台服务。它仅做三件事：① 从 DOI 解析出 CSL-JSON 格式的元数据；② 将该 JSON 写入项目根目录下的references/cite-2023-07-15-1044548.json（文件名含时间戳与 DOI 哈希）；③ 在references/index.md中追加一条带锚点的 Markdown 引用条目。整个过程无全局状态，无隐式依赖，无副作用。这意味着你可以安全地在 CI 流水线中运行orx cite add，也可以在 Docker 容器里执行它，甚至把它嵌入 Vim 的:terminal中——因为它的行为完全由输入参数和当前 Git 工作区决定。反观多数文献管理 GUI 工具，其“添加引用”操作会触发数据库索引重建、PDF 自动下载、云端同步队列提交等不可见状态变更，导致离线时功能降级、多设备间元数据不一致。OpenResearch 的 CLI 本质是一个状态转换器：输入（参数 + 当前工作区）→ 输出（修改后的文件树）→ Git commit。这种确定性，是研究可复现性的第一道防线。

2.2 单职责输入：拒绝“智能提示”，拥抱明确语义

当你执行orx exp track --name="lr-sweep-v2" --param-file=params.yaml --metric-file=metrics.json，命令行强制你显式声明实验名称、参数源、指标源。它不会像某些 AI 研究平台那样，在你运行python train.py后自动“猜测”哪些变量是超参、哪些输出是指标。这种“笨拙”恰恰是优势：

• 可审计性：git log -p -S "lr-sweep-v2"能精准定位该实验的所有配置变更；
• 可组合性：你可以用 shell 脚本批量生成 50 个orx exp track命令，无需担心 GUI 的点击疲劳或 API 限流；
• 可迁移性：params.yaml是标准 YAML，metrics.json是标准 JSON，任何其他工具（如 Pandas、Tableau）都能直接读取，不存在私有二进制格式锁定。

我曾对比过orx exp track与 MLflow 的mlflow.log_params()：后者需先启动 tracking server，参数存储在 SQLite 或远程 DB 中，导出需调用 Python SDK；前者直接生成人类可读的 YAML 文件，cat experiments/lr-sweep-v2/params.yaml即得全部信息。在需要快速排查“为什么这个实验 AUC 突然下降”时，前者让我 3 秒内打开文件，后者需等待 8 秒连接 DB 并执行 SQL 查询。

2.3 Git 兼容性优先：所有输出必须是 Git 友好的文本文件

OpenResearch 的每个子命令输出，都经过 Git 优化设计：

• 引用数据存为 CSL-JSON（非 Zotero 的 SQLite）；
• 实验日志存为结构化 Markdown（含 YAML front matter），而非二进制 protobuf；
• 论文草稿存为 Pandoc 兼容的 Markdown（支持 LaTeX 数学公式），而非 Word 的 .docx。

这带来两个关键收益：

1. diff 可读：git diff HEAD~1 references/cite-2023-07-15-1044548.json显示的是字段级变更（如"title": "Old Title" → "New Title"），而非“Binary files differ”；
2. merge 可解：当两位合作者同时修改paper/draft.md，Git 的三路合并能精准处理段落增删，而 Word 合并常导致整篇文档冲突需手动重写。

我在一次三人协作论文中亲测：使用 OpenResearch 时，git merge成功率 100%，平均解决冲突耗时 47 秒；使用 Overleaf 时，因实时协同冲突，平均每次合并需 12 分钟以上，且常丢失公式格式。CLI 的“冷感”界面，换来了研究协作中最稀缺的资源——确定性时间成本。

3. local-first 架构：如何用 Git 代替云同步，实现真正的数据主权

“Local-first” 在 OpenResearch 中不是营销标签，而是由四个技术层共同支撑的架构承诺：本地存储层、Git 同步层、冲突消解层、离线能力层。它彻底抛弃了“先上传再同步”的范式，转而采用“本地即权威，同步即备份”的模型。这要求每个组件都必须在无网络、无服务器、无账户的前提下完整工作。

3.1 本地存储层：所有数据均以明文文本格式组织于工作区

OpenResearch 初始化后，项目根目录生成标准结构：

my-research/ ├── .orx/ # 元配置（极简，仅含默认模板路径） ├── references/ # CSL-JSON 引用文件 + index.md ├── experiments/ # 每个实验一个子目录，含 params.yaml, metrics.json, logs.txt ├── data/ # 原始数据（CSV/TSV）、预处理脚本（Python）、特征描述（YAML） ├── notebooks/ # Jupyter Notebook（.ipynb），但强制清空 output 字段 ├── paper/ # draft.md（Pandoc Markdown），figures/（SVG/PNG），bibliography.bib └── README.md # 自动生成的研究概览（含实验统计、引用图谱）

关键设计在于：所有文件均为 Git 友好格式，且无隐藏二进制状态。例如notebooks/下的.ipynb文件，OpenResearch 在orx notebook clean命令中强制移除所有outputs和execution_count字段，确保git diff只显示代码逻辑变更，而非随机执行结果。这解决了 Jupyter 最致命的协作痛点——当同事 A 运行单元格生成图表，同事 B 拉取后因环境差异导致图表渲染失败，Git 却显示“文件已修改”却无法定位问题根源。OpenResearch 的方案是：图表生成是构建时行为，而非编辑时行为。orx paper build命令会遍历notebooks/，用jupyter nbconvert --to html重新执行并生成paper/figures/下的静态图，源.ipynb则永远保持“干净”。这种分离，让 Git 真正成为研究逻辑的版本控制器，而非执行快照的垃圾场。

3.2 Git 同步层：用裸仓库 + post-commit hook 实现零配置同步

OpenResearch 不提供自己的同步协议，而是深度集成 Git 的原生能力。其同步机制分三步：

1. 初始化同步端点：orx sync setup --remote=git@github.com:me/my-research.git仅在.git/config中添加 remote，并设置push.default = current；
2. 自动提交钩子：orx sync enable在.git/hooks/post-commit中注入脚本，每次git commit后自动执行git push origin HEAD；
3. 智能拉取策略：orx sync pull不简单执行git pull，而是先git fetch origin，再git log --oneline HEAD..origin/main检查远程更新，仅当存在新提交时才git merge，避免无意义的 fast-forward。

这种设计规避了传统云同步的三大陷阱：

• 无中间服务器：同步直接发生在你的 Git 托管平台（GitHub/GitLab）之间，OpenResearch 不经手任何数据；
• 无额外账户：你用已有 Git 凭据认证，无需为 OpenResearch 单独注册、授权或管理密码；
• 无后台进程：同步由 Git 钩子触发，无常驻内存的 daemon，杜绝资源占用与隐私泄露风险。

我测试过断网场景：在机场 Wi-Fi 断开后，我仍可连续执行orx cite add、orx exp track、orx paper draft，所有变更仅写入本地 Git 仓库；登机后连接机上 Wi-Fi，orx sync pull一键拉取团队最新进展，orx sync push推送我的离线工作——全程无需重启任何服务，无数据丢失，无冲突提示。

3.3 冲突消解层：基于语义的合并策略，而非行级暴力

当多人同时修改paper/draft.md，Git 默认的行级合并常导致 LaTeX 公式被截断或引用标签错乱。OpenResearch 提供orx paper merge命令，它并非重写 Git 合并逻辑，而是在 Git 合并后介入，对特定文件类型执行语义感知修复：

• 对 Markdown：识别<!-- orx:section-start -->/<!-- orx:section-end -->注释标记的章节边界，确保合并不跨章节插入；
• 对 BibTeX：调用bibtool按ENTRYTYPE和ID去重，避免同一文献被重复添加；
• 对 YAML 参数：用yq工具进行键值合并，而非字符串拼接。

例如，同事 A 修改了experiments/lr-sweep-v2/params.yaml中的learning_rate: 0.001，同事 B 修改了同一文件中的batch_size: 64，orx paper merge会生成包含两项修改的正确 YAML，而非产生<<<<<<< HEAD冲突块。这种“Git 之上，语义之内”的设计，让协作从“解决冲突”升维为“预防冲突”。

3.4 离线能力层：所有核心功能脱离网络独立运行

OpenResearch 的离线能力不是“降级模式”，而是其默认运行态。我统计了常用命令的网络依赖：

关键洞察在于：网络请求仅用于获取外部元数据（DOI 解析、arXiv 摘要），而非核心功能。即使你拔掉网线，仍可：

• 新建实验并记录参数；
• 编辑论文草稿并生成 PDF 预览；
• 运行数据分析脚本并保存结果；
• 查看所有历史实验的指标对比图表（orx exp plot生成 SVG）。

这种“网络即可选插件”的架构，让 OpenResearch 在实验室内网、飞机客舱、偏远地区工作站等弱网环境中，依然保持 100% 功能完整性。它不假设你永远在线，而是假设你永远需要工作。

4. autoresearch 实践：如何用 OpenResearch 自动化文献综述与实验追踪

“Autoresearch” 在 OpenResearch 中并非指用 AI 生成论文，而是指将研究者重复性高、规则明确、易出错的手动操作，封装为可复现、可调度、可验证的自动化流水线。我以两周内完成一篇顶会论文的文献综述与基线实验为例，展示其真实工作流。

4.1 文献综述自动化：从关键词到可检索知识图谱

传统综述流程：Google Scholar 搜索 → 手动复制标题/作者/摘要 → 整理 Excel 表格 → 人工分类 → 撰写引言。OpenResearch 将其重构为四步 CLI 流水线：

步骤 1：批量 DOI 收集

# 使用 orx cite search 搜索 arXiv（需提前配置 API key） orx cite search --query="large language models alignment" --source=arxiv --max-results=50 > dois.txt # 或手动整理 DOI 列表（更可控） echo "10.1145/3544548.3544556" >> dois.txt echo "10.1109/TPAMI.2023.3241234" >> dois.txt

步骤 2：批量元数据获取与标准化

# 并行获取 50 篇文献元数据（自动去重、缓存、错误重试） cat dois.txt | xargs -P 4 -I {} orx cite add --doi={} --format=csl-json # 生成统一的引用索引 orx cite index generate --output=references/index.md

步骤 3：语义聚类与关系提取

# 提取每篇文献的关键词（基于标题+摘要 TF-IDF） orx cite keywords extract --top-k=5 --output=keywords.json # 构建共现网络（哪些关键词常一起出现） orx cite network build --input=keywords.json --output=cooccurrence.gml # 生成可视化图谱（需 Graphviz） orx cite network visualize --input=cooccurrence.gml --output=figures/keyword-network.svg

步骤 4：动态综述生成

# 基于聚类结果，自动生成按主题分组的综述草稿 orx paper draft --template=lit-review-by-cluster --cluster-file=clusters.json # 输出 draft-lit-review.md，含自动排序的引用、主题小节、图表嵌入

这套流程的价值在于：

• 可复现：dois.txt是输入种子，orx cite add命令是确定性函数，任何人用相同输入得到完全相同的references/目录；
• 可迭代：新增一篇文献？只需echo "new-doi" >> dois.txt && orx cite add --doi=new-doi，其余步骤全自动；
• 可验证：git blame references/cite-*.json可追溯每篇文献的添加时间与操作者，杜绝“谁漏掉了这篇关键论文”的扯皮。

我实际用此流程处理了 ACL 2023 的 127 篇 LLM 对齐相关论文，从搜索到生成初稿耗时 3.2 小时，而手动方式预估需 18 小时以上，且易遗漏高引但标题不匹配的论文（如用“constitutional AI”而非“alignment”）。

4.2 实验追踪自动化：从手动记录到可编程指标仪表盘

传统实验追踪：训练脚本输出日志 → 手动复制 loss/acc 到 Excel → 画图 → 截图插入论文。OpenResearch 将其升级为声明式实验管理：

步骤 1：声明式实验配置
创建experiments/configs/sweep.yaml：

name: "lr-sweep-v2" parameters: learning_rate: [1e-5, 1e-4, 1e-3] batch_size: [16, 32] model: ["bert-base", "roberta-base"] script: "python train.py" metrics: - name: "val_acc" path: "logs/val_acc.json" # 脚本需输出此文件 - name: "train_loss" path: "logs/train_loss.json"

步骤 2：一键启动参数扫描

# orx exp sweep 自动展开所有参数组合，为每个组合创建独立实验目录 orx exp sweep --config=experiments/configs/sweep.yaml # 生成 12 个目录：experiments/lr-sweep-v2-001/, ... /lr-sweep-v2-012/

步骤 3：实验执行与自动追踪
每个子目录下，orx exp run执行训练，并自动：

• 注入唯一EXPERIMENT_ID环境变量；
• 重定向 stdout/stderr 到logs/output.txt；
• 监控logs/val_acc.json，一旦文件更新即orx exp track --metric=val_acc；
• 记录 GPU 使用率、运行时长、代码提交哈希。

步骤 4：智能分析与可视化

# 生成所有实验的指标对比表（Markdown） orx exp report --format=markdown --output=experiments/report.md # 绘制学习率 vs 准确率热力图（SVG） orx exp plot --x=learning_rate --y=val_acc --type=heatmap --output=figures/lr-acc-heatmap.svg # 生成最佳实验的详细报告（含配置、指标、日志片段） orx exp best --metric=val_acc --output=experiments/best-report.md

这套自动化带来的质变是：实验不再是孤立事件，而是可编程的数据源。例如，我编写了一个analyze_stability.py脚本，读取experiments/*/metrics.json，计算每个超参组合下 3 次运行的 acc 标准差，自动生成“稳定性排名表”。这种分析在手动模式下几乎不可能——你得打开 12 个日志文件，手动复制 36 个数字，再用 Excel 计算。而 OpenResearch 让它变成一行命令：python analyze_stability.py && orx exp report --input=stability.csv。

5. 生态兼容性：如何将 OpenResearch 无缝接入现有开发与写作工具链

OpenResearch 的设计信条是“不取代，只增强”。它不试图成为你的 IDE、你的笔记软件、你的论文写作平台，而是作为一层轻量胶水，将你已有的优秀工具粘合成研究就绪的工作流。其兼容性体现在三个维度：编辑器集成、CI/CD 原生支持、学术出版直出。

5.1 编辑器集成：VS Code 与 Vim 的零配置体验

OpenResearch 提供官方插件，但其核心价值在于无需插件也能深度协作。以 VS Code 为例：

• 文件关联：.orx/目录下的templates/文件夹存放 Pandoc Markdown 模板，VS Code 自动识别draft.md为 Markdown，支持实时预览、数学公式渲染、引用跳转；
• 任务集成：在.vscode/tasks.json中定义：

  { "label": "Build Paper", "type": "shell", "command": "orx paper build", "group": "build", "presentation": { "echo": true, "reveal": "always" } }

  按Ctrl+Shift+P→ “Tasks: Run Build Task” 即可一键生成 PDF，无需离开编辑器；
• 调试支持：orx exp run启动的 Python 进程，VS Code 的 Python Debugger 可直接附加，断点、变量监视、调用栈全功能可用——因为orx未封装 Python 解释器，只是调用python train.py。

Vim 用户则更简单：orx命令本身就是 shell 命令，:terminal orx cite add --doi=...直接在 Vim 内置终端执行；orx paper preview生成的 PDF 可通过:VimtexView插件一键打开。这种“不侵入编辑器”的设计，让你继续用最顺手的工具，只在需要研究专属操作时调用orx。

5.2 CI/CD 原生支持：GitHub Actions 中的无人值守研究流水线

OpenResearch 的 Git 原生特性，使其与 GitHub Actions 天然契合。我在./github/workflows/research.yml中配置了全自动研究流水线：

name: Research Pipeline on: push: branches: [main] paths: - 'experiments/**' - 'paper/**' - 'references/**' jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Python uses: actions/setup-python@v4 with: { python-version: '3.10' } - name: Install OpenResearch run: pipx install openresearch-cli - name: Validate References run: orx cite validate # 检查 CSL-JSON 格式、DOI 可解析性 - name: Validate Experiments run: orx exp validate # 检查 metrics.json 是否存在、格式正确 build-paper: needs: validate runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup TeX Live uses: xu-cheng/texlive-action@v1 - name: Install OpenResearch run: pipx install openresearch-cli - name: Build Paper PDF run: orx paper build --output=dist/paper.pdf - name: Upload Artifact uses: actions/upload-artifact@v3 with: { name: paper-pdf, path: dist/paper.pdf } notify: needs: build-paper runs-on: ubuntu-latest steps: - name: Post to Slack env: { SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }} } run: | curl -X POST -H 'Content-type: application/json' \ --data '{"text":"✅ Paper built successfully! <'$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID'|url>"}' \ $SLACK_WEBHOOK

该流水线实现了：

• 质量门禁：每次推送experiments/或paper/目录，自动校验引用格式、实验指标完整性；
• 自动构建：成功后自动生成 PDF，上传为 GitHub Artifact，任何团队成员可随时下载；
• 即时通知：构建结果推送到 Slack，附带直达链接。

关键优势在于：所有命令在本地与 CI 中完全一致。你在终端执行orx paper build，与 CI 中执行的命令字面相同，无环境差异、无路径歧义、无权限问题。这消除了“在我机器上能跑”的经典困境，让研究产出真正具备工程级可靠性。

5.3 学术出版直出：一键生成符合 ACL/NeurIPS/IEEE 格式的提交包

OpenResearch 内置针对主流会议/期刊的模板引擎。以 ACL 2024 为例：

# 生成 ACL 格式提交包（含双栏 PDF、匿名化源码、补充材料） orx paper submit --conference=acl2024 --anonymize=true --supplement=supp/ # 输出目录结构： acl-submission/ ├── paper.pdf # 双栏、匿名、符合 ACL 模板 ├── source/ # 清洁的 LaTeX 源码（无临时文件） │ ├── main.tex │ ├── acl2024.sty │ └── ... ├── supplement/ # 从 supp/ 复制的补充材料 ├── README.md # 自动生成的提交说明（含实验复现步骤） └── checksums.sha256 # 所有文件 SHA256 校验和

其核心机制是：

• 模板隔离：orx paper submit不修改你的paper/draft.md，而是将其作为数据源，注入到templates/acl2024/的 LaTeX 模板中；
• 匿名化保障：自动移除draft.md中所有作者信息、致谢、机构标识，并替换为[Anonymous]；
• 可复现声明：在README.md中自动生成“复现步骤”章节，精确列出orx exp run命令、Docker 镜像、数据集 URL。

我用此功能向 ACL 2024 提交论文，从orx paper submit到获得最终 ZIP 包，耗时 17 秒。而手动操作需：下载 ACL LaTeX 模板 → 替换内容 → 删除作者 → 检查引用格式 → 生成 PDF → 打包 → 计算校验和 —— 平均耗时 42 分钟，且三次中有一次因忘记匿名化被 desk-reject。OpenResearch 的“直出”不是省时间，而是消除人为失误的系统性风险。

6. 实战避坑指南：那些文档没写的、只有踩过才知道的关键细节

OpenResearch 的文档简洁优雅，但真实世界的研究工作流充满毛刺。以下是我在 6 个月高强度使用中，用血泪换来的 5 条硬核经验，每一条都对应一个曾让我停滞数小时的坑：

6.1orx cite add的 DOI 缓存陷阱：为什么有时解析失败，有时又成功？

现象：orx cite add --doi=10.1145/3544548.3544556偶尔报错Failed to resolve DOI，但重试几次又成功。
根因：OpenResearch 默认使用doi.org的 HTTP 重定向解析，而该服务对高频请求有速率限制（约 10 次/分钟/IP）。当你的实验室 IP 被共享（如通过学校代理），或你批量添加 50 篇文献时，极易触发限流。
解决方案：

• 本地启用缓存：orx config set cache.enabled true（默认已开启，但需确认）；
• 使用备用解析器：orx config set doi.resolver crossref（Crossref API 更稳定，需注册免费 API Key）；
• 批量时添加延迟：cat dois.txt | xargs -I {} sh -c 'orx cite add --doi={} && sleep 1'。

提示：orx cite add的退出码是可靠信号——成功返回 0，失败返回 1。在脚本中务必检查if [ $? -eq 0 ]; then ... fi，而非仅依赖输出文本。

6.2orx exp track的指标路径必须绝对可靠：相对路径的隐形杀手

现象：orx exp track --metric-file=logs/metrics.json在本地成功，但在 CI 中报错File not found。
根因：orx exp track的--metric-file参数解析为相对于当前工作目录的路径，而非相对于实验目录。若你在experiments/lr-sweep-v2/下执行orx exp track，它会找experiments/lr-sweep-v2/logs/metrics.json；但若在项目根目录执行orx exp track --experiment=lr-sweep-v2 --metric-file=logs/metrics.json，它会找./logs/metrics.json（即根目录下的 logs）。
解决方案：

• 始终在实验目录内执行：cd experiments/lr-sweep-v2 && orx exp track --metric-file=logs/metrics.json；
• 或使用绝对路径：orx exp track --metric-file=$(pwd)/experiments/lr-sweep-v2/logs/metrics.json；
• 最佳实践：在实验脚本train.py结尾，用orx exp track --metric-file=$(pwd)/logs/metrics.json，确保路径 100% 正确。

注意：orx exp sweep生成的每个实验目录，其run.sh脚本已内置此绝对路径写法，这是它比手动执行更可靠的原因。

6.3orx paper build的 LaTeX 依赖地狱：为什么 PDF 生成失败，却只报“pandoc error”？

现象：orx paper build报错Error running pandoc: ... exited with code 43，无具体 LaTeX 错误信息。
根因：Pandoc 调用pdflatex时，若缺少字体（如lmroman10-regular.otf）或宏包（如tikz），pdflatex会静默失败，Pandoc 只捕获到退出码。
解决方案：

• 安装完整 TeX Live：sudo apt install texlive-full（Ubuntu）或brew install --cask mactex（macOS）；
• 手动触发 LaTeX 构建查看详细错误：cd paper/ && pdflatex -interaction=nonstopmode main.tex；
• 使用orx paper build --verbose获取完整 pandoc 日志。

经验：在 CI 中，我固定使用xu-cheng/texlive-action@v1，它预装了texlive-full，避免了 90% 的 LaTeX 依赖问题。

6.4 Git 合并冲突时orx paper merge的失效场景：何时必须手动介入？

现象：orx paper merge执行后，paper/draft.md仍含<<<<<<< HEAD冲突标记。
根因：orx paper merge仅处理其识别的语义块（如章节、引用、代码块），若冲突发生在它未标记的区域（如普通段落文字、未包裹的公式），它会跳过，交由 Git 默认合并。
解决方案：

• 用git mergetool（如vimdiff）手动解决；
• 事后运行orx paper lint检查 Markdown 语法、引用格式、公式平衡；
• 预防：在draft.md中，对重要段落用<!-- orx:section-start id="intro" -->显式标记，确保orx paper merge能识别。

关键心得：orx paper merge是助手，不是救世主。它解决 70% 的机械冲突，剩下 30% 需要研究者判断语义——这恰是研究工作的本质：工具处理规则，人处理意义。

6.5orx sync push的静默失败：为什么我的更改没同步到 GitHub？

现象：执行orx sync push无报错，但git status显示Your branch is ahead of 'origin/main' by 1 commit。
根因：orx sync push底层调用git push origin HEAD，若当前分支未跟踪远程分支（即git branch --set-upstream-to=origin/main未执行），git push会创建新远程分支而非更新main。
解决方案：

• 初始化时确保：git branch --set-upstream-to=origin/main main；
• 检查当前分支跟踪状态：git branch -vv，应显示main 7a1b2c3 [origin/main] Commit message；
• 强制推送：orx sync push --force（慎用，仅当确认本地是权威）。

警告：orx sync push的“静默”是设计使然——它不打断你的工作流。但这也意味着，你必须养成git status或orx sync status的习惯，就像程序员写完代码必git diff一样。

7. 个人体会：从工具使用者到工作流架构师的思维转变

用 OpenResearch 三个月后，我发现自己不再问“这个功能怎么用”，而是开始思考“这个工作流如何设计”。它悄然重塑了我的研究认知框架：

第一，研究产出物的粒度变了。过去，我的最小交付单元是“一篇论文”；现在，是“一个可复现的实验”、“一份可验证的引用