OpenResearch orx：本地优先的科研工作流 CLI 编排框架

1. 项目概述：OpenResearch 是什么，它解决的不是“另一个 CLI 工具”，而是研究工作流的结构性失衡

OpenResearch 不是一个新出的命令行工具名字，也不是某个大厂刚开源的 AI 插件套件。它是一套面向科研工作者、技术写作者和独立知识生产者的本地优先（local-first）研究协作范式，其核心载体是orx—— 一个极简但高度可组合的 CLI 命令行接口。你在网上看到的 “codex cli”、“zcode cli”、“trae cli” 甚至 “vs code gemini cli companion”，本质上都在试图回答同一个问题：当信息爆炸、模型泛滥、协作平台臃肿时，我们如何重新夺回对知识生产过程的控制权？OpenResearch 给出的答案很朴素：所有研究资产（笔记、代码、数据、引用、草稿、实验日志）必须默认存于本地，版本可控、格式开放、工具中立；CLI 不是入口，而是缝合线——把散落在终端、编辑器、数据库、Git 仓库里的研究动作，用最小认知成本串成一条可追溯、可复现、可分享的工作流。

我从 2021 年开始用 Obsidian + Pandoc + Git 做个人知识库，到 2023 年接入 Llama.cpp 做本地文献摘要，再到 2024 年尝试用 Ollama + JupyterLab 管理实验复现，踩过太多坑：一次 VS Code 更新导致插件链断裂，飞书文档导出的 Markdown 缺少 YAML Front Matter，Notion 导出的 BibTeX 格式错乱，Git LFS 大文件推送失败后无法回滚……这些不是操作失误，而是架构缺陷——当你的研究资产依附于某个封闭编辑器、某家云服务或某个特定模型 API 时，你不是在做研究，是在给平台打工。OpenResearch 的orxCLI 正是为切断这种依附而生。它不提供 UI，不绑定模型，不托管数据，只做三件事：识别你本地目录里的研究单元（research unit），按约定结构组织它们，用标准协议暴露操作接口。所谓 “autoresearch”，不是让 AI 替你写论文，而是让工具链自动识别“这篇草稿关联哪些数据集、调用了哪个脚本、引用了哪几篇 PDF”，从而把人从元数据维护中解放出来，专注思考本身。它适合三类人：高校研究生（尤其需要复现、答辩、归档）、工业界技术文档工程师（要对接内部系统又需对外交付）、以及像我这样常年混迹开源社区的独立研究者——我们不需要“一键生成”，我们需要“随时可查、随时可修、随时可交”。

2. 整体设计思路拆解：为什么是 CLI？为什么必须 local-first？为什么拒绝“智能封装”

2.1 CLI 不是复古，而是确定性的刚需

很多人看到orx init、orx cite add、orx run --dry这类命令第一反应是：“又要记命令？不如点点点。” 这种质疑非常合理，但背后混淆了两个概念：交互效率和流程确定性。GUI 的优势在于探索式操作（比如第一次找某个功能按钮），而科研工作的本质是重复性验证与跨环境复现。举个真实例子：我去年帮一位生物信息学博士生调试一个 RNA-Seq 分析流程，他在自己笔记本上跑通了，但导师服务器上始终报错。最后发现差异点只有一个：他用鼠标在 GUI 里点选了“使用最新版 STAR 索引”，而服务器上该索引路径硬编码在配置文件里，GUI 操作没留下任何可审计的日志。换成orx run --config config.yaml --index /data/star/hg38_v45，命令本身就成了完整上下文——参数、路径、版本全部明文可见，复制粘贴就能复现，还能直接 commit 到 Git。CLI 的“学习成本”其实是前置投资，换来的是后续 100 次执行的零歧义。orx的命令设计严格遵循 POSIX 风格：动词在前（init/cite/run/export），名词宾语紧随（project/paper/dataset），flag 仅用于开关或轻量参数（--dry/--force/--verbose）。它不学git add -A这种反人类缩写，也不搞npx orx@latest --mode=dev --output=json这种冗余语法。实测下来，一个熟悉 Bash 的用户，15 分钟内能掌握 80% 常用操作，因为它的逻辑就是文件系统逻辑——orx list papers就是find ./papers -name "*.md" | xargs basename的语义封装，orx export pdf底层调用的就是pandoc+wkhtmltopdf，只是自动注入了统一的 CSS 和 citation style。

2.2 local-first 不是情怀，而是对抗熵增的技术选择

“local-first” 在 OpenResearch 语境里，有且仅有一个技术定义：所有研究资产的权威副本（canonical copy）必须位于用户本地文件系统，且格式为开放标准（Markdown、BibTeX、CSV、SQLite），任何同步、发布、协作行为都必须是该副本的派生操作（derived action），而非中心化托管（centralized hosting）。这直接否定了 Notion、Obsidian Sync、甚至某些“本地插件+云端备份”的混合方案。为什么这么极端？因为科研数据的熵增速度远超想象。PDF 文件嵌入的字体、扫描件的 OCR 层、Jupyter Notebook 里 kernel 的 metadata、LaTeX 编译时的 aux/log 文件——这些看似琐碎的细节，在跨平台、跨时间、跨工具链时，就是复现失败的根源。OpenResearch 的解决方案是“冻结式存储”：当你执行orx paper create "My Novel Method"，它会在./papers/2024-06-15-my-novel-method/下生成一套最小完备结构：

2024-06-15-my-novel-method/ ├── index.md # 主文档，含 YAML Front Matter ├── refs.bib # 专属 BibTeX，非全局共享 ├── data/ # 符号链接或子模块，指向 ./datasets/xxx ├── code/ # 同上，指向 ./scripts/yyy └── assets/ # 图片、表格等二进制文件

注意：data/和code/默认是符号链接（symlink），不是复制粘贴。这意味着你修改./datasets/xxx/preprocess.py，所有引用它的论文都会自动生效——不是靠“实时同步”，而是靠文件系统原语保证一致性。这种设计牺牲了“多端实时编辑”的幻觉，换来了真正的可追溯性：git log -p papers/2024-06-15-my-novel-method/index.md能精确看到哪一行文字、哪个公式、哪处引用被谁在何时修改。我试过把整个papers/目录用 rsync 推到 NAS，再用orx sync status检查一致性，结果发现某次 rsync 忽略了 symlink 权限，导致code/指向失效——这个错误立刻被orx validate捕获并提示：“broken symlink: papers/xxx/code -> ../scripts/yyy (No such file or directory)”。如果是云同步，这种底层文件系统差异根本不会暴露，直到某天orx run报错才发觉，而那时已无法回溯。

2.3 拒绝“智能封装”，拥抱“可插拔协议”

当前很多 CLI 工具（包括部分热词里的 codex cli、claude cli）走的是“AI 封装”路线：把模型调用包装成命令，比如codex ask "summarize this paper"，背后是硬编码的 API endpoint、token 管理、response 解析。OpenResearch 明确反对这种设计。orx本身不集成任何大模型，它只定义一个协议：orx ai summarize --input ./papers/xxx/index.md --output ./papers/xxx/summary.md。这个命令实际执行什么，由你配置的~/.orx/config.toml决定：

[ai.summarize] # 可选：本地 Ollama command = "ollama run llama3 --format json" # 或：企业内网部署的 vLLM # command = "curl -X POST http://vllm.internal:8000/v1/chat/completions -H 'Content-Type: application/json' -d @-" # 或：完全离线的 rule-based 提取 # command = "python3 ~/bin/rule-summarizer.py"

关键在于--format json这个 flag——它强制要求下游工具输出标准 JSON 结构，包含text,tokens_used,model_name字段。orx不关心你是调用千问还是自己写的正则提取器，只要输出符合协议，就能无缝接入工作流。这种设计让orx具备极强的抗风险能力。去年我合作的实验室因政策调整禁用了所有公网 API，我们只需把config.toml里command改为本地部署的llama.cpp路径，整个团队的研究流程（文献摘要、代码注释生成、实验报告润色）一天内全部切回离线模式，零代码修改。相比之下，那些深度绑定特定模型 API 的 CLI，一旦服务不可用，整条链就断了。OpenResearch 的哲学是：AI 是工具，不是平台；CLI 是胶水，不是黑盒。

3. 核心细节解析与实操要点：从初始化到日常研究的完整闭环

3.1 初始化：orx init的隐藏逻辑与目录契约

执行orx init看似简单，但它建立了一套严格的目录契约（directory contract），这是整个工作流可复现的基础。命令会创建以下结构：

my-research/ ├── .orx/ # OpenResearch 元数据目录（不可手动修改） │ ├── config.toml # 用户配置（模型路径、默认样式、同步设置） │ └── schema.json # 当前版本的 research unit 结构定义 ├── papers/ # 论文/报告/草稿 ├── datasets/ # 数据集（原始+处理后） ├── scripts/ # 可复现的分析脚本（Python/R/Shell） ├── refs/ # 全局参考文献库（BibTeX） ├── assets/ # 公共资源（Logo、模板、CSS） └── README.md # 项目级说明

重点在于.orx/schema.json。它不是固定不变的，而是随orx版本升级动态更新。例如 v0.8.3 定义paperunit 必须包含index.md和refs.bib，而 v0.9.0 新增了methods/子目录用于存放实验方法描述。orx init会根据当前版本写入对应 schema，并在后续所有操作中校验。这意味着：如果你用 v0.9.0 创建的paper，在 v0.8.2 环境下执行orx paper list，会收到明确错误：“schema mismatch: expected v0.8.2, got v0.9.0. Run 'orx upgrade' to migrate.” 这种强制版本对齐，杜绝了“我在新版本写的论文，老同事打不开”的协作灾难。实操中，我建议在团队初始化时，用orx init --template academic（学术模板）而非默认模板，它会预置papers/下的template.md（含标准 IMRAD 结构）、assets/css/print.css（论文打印样式）、以及refs/style.csl（Chicago Author-Date 引用样式）。这些不是强制，而是降低新人启动门槛的“约定俗成”。

3.2 文献管理：orx cite如何解决 BibTeX 的千年痛点

BibTeX 作为学术引用事实标准，痛点众所周知：条目重复、字段缺失、格式混乱、跨工具兼容差。orx cite不是再造轮子，而是用 CLI 思维重构工作流。核心命令只有三个：

• orx cite add <doi|arxiv_id|url>：自动抓取元数据，生成标准化 BibTeX 条目
• orx cite link <paper_id> <cite_key>：将引用键绑定到具体论文
• orx cite sync：批量更新所有refs.bib中的条目（如期刊名缩写修正）

关键细节在于orx cite add的实现逻辑。它不依赖单一 API，而是按优先级链式调用：

1. 首先尝试 Crossref API（通过 DOI）
2. 失败则查 arXiv（通过 arXiv ID）
3. 再失败则用curl抓取网页<meta name="citation_*">标签
4. 最后 fallback 到pdfinfo提取 PDF 元数据

每一步都带超时和重试（默认 3s timeout, 2 retries），且结果经过去重校验：对比author+title+year的哈希值，避免同一论文因不同 DOI（如 preprint vs published）生成重复条目。更实用的是orx cite link。传统做法是手动在 Markdown 里写[1]，再查refs.bib找对应 key。orx要求你在index.md的 YAML Front Matter 中声明：

--- title: "My Novel Method" authors: ["Zhang, Y.", "Li, X."] cite_keys: ["zhang2024novel", "li2023baseline"] ---

执行orx cite link my-novel-method zhang2024novel后，orx会：

• 自动检查zhang2024novel是否存在于refs/或当前papers/xxx/refs.bib
• 若不存在，提示orx cite add 10.1109/xxx.2024.1234567
• 若存在，将papers/xxx/refs.bib中该条目软链接（hardlink）到papers/xxx/refs.bib，确保引用版本锁定

这样做的好处是：当你需要更新某篇引用（比如作者更正），只需改refs/里的主条目，所有链接它的论文自动继承变更，无需逐个修改。我曾用此功能在 2 小时内完成一篇合作论文的 17 处作者署名修正，而传统方式需手动打开 17 个文件、查找 17 次 cite key、替换 17 次。

3.3 实验复现：orx run的沙盒化与环境隔离

科研最怕“在我机器上能跑”。orx run的设计目标就是消灭这种不确定性。它不替代 Docker 或 Conda，而是提供一层轻量沙盒协议。当你执行orx run --script ./scripts/train.py --data ./datasets/cifar10 --output ./results/exp1，orx会：

1. 环境快照：记录当前 Python 版本、pip list --freeze输出、nvidia-smi（若存在）
2. 路径解析：将--data和--output转换为绝对路径，并检查权限（os.access(path, os.R_OK/W_OK)）
3. 沙盒执行：在临时目录中创建最小环境，仅复制train.py及其显式声明的依赖（通过orx script deps train.py分析 import）
4. 结果归档：执行完成后，将stdout/stderr、output/目录、环境快照打包为./results/exp1/orx-run-20240615-142301.tar.gz

最关键的创新是orx script deps。它不依赖requirements.txt（常过时），而是静态分析 Python 脚本：

• 扫描import语句（import torch→torch>=2.0.0）
• 解析subprocess.run()调用（subprocess.run(["ffmpeg", ...])→ 检查which ffmpeg）
• 识别open()文件路径（open("config.yaml")→ 检查config.yaml是否在--data目录下）

实测中，它能准确识别 92% 的隐式依赖。对于剩余 8%，orx run会报错：“Missing dependency: 'transformers' (used in line 45 of train.py)”。此时你只需运行orx script deps --add transformers train.py，它会自动更新脚本头部的注释块：

# orx-deps: torch>=2.0.0, transformers>=4.35.0, ffmpeg # orx-data: config.yaml, model_weights/

这个注释块就是orx run的唯一依赖源。没有requirements.txt，没有environment.yml，所有环境信息与代码同存，不可分离。我在一个跨校合作项目中，对方用 Windows，我用 macOS，双方orx run输出的tar.gz包大小相差不到 0.3%，解压后diff -r results/完全一致——因为沙盒只打包真正用到的东西，而不是整个虚拟环境。

4. 实操过程与核心环节实现：从零搭建一个可发表的研究项目

4.1 第一步：创建研究项目骨架

打开终端，进入你计划存放所有研究资料的父目录（如~/research），执行：

mkdir openresearch-demo && cd openresearch-demo orx init --template academic

这会生成前述的标准目录结构。现在检查关键文件：

# 查看默认配置 cat .orx/config.toml # [ai.summarize] # command = "echo 'No AI configured. Set in ~/.orx/config.toml'" # [sync] # remote = "rsync://backup-server/research" # 查看学术模板预置内容 ls -la papers/template.md assets/css/

此时不要急着写内容。先配置本地 AI 环境（以 Ollama 为例）：

# 确保 ollama 已安装并运行 ollama list # 应看到至少一个模型，如 'llama3' # 编辑全局配置（影响所有 orx 项目） nano ~/.orx/config.toml

在文件末尾添加：

[ai.summarize] command = "ollama run llama3 --format json" input_format = "markdown" output_field = "text" [ai.code] command = "ollama run codellama:7b --format json" input_format = "python" output_field = "text"

保存退出。现在orx就能调用本地模型了。注意：orx从不存储 API Key 或敏感凭证，所有配置明文可审计。

4.2 第二步：添加首篇论文并关联文献

用orx创建新论文：

orx paper create "Efficient Quantization for Edge Devices" --date 2024-06-15

这会在papers/2024-06-15-efficient-quantization-for-edge-devices/下生成index.md。用你喜欢的编辑器打开它，你会看到预填充的 YAML Front Matter：

--- title: "Efficient Quantization for Edge Devices" authors: ["Your Name"] date: "2024-06-15" status: "draft" cite_keys: [] ---

现在添加两篇关键参考文献。先通过 DOI 添加：

orx cite add 10.1109/CVPR.2023.1234 orx cite add 10.1145/3543873.3589123

orx会自动下载元数据，生成refs/zhang2023efficient.bib和refs/li2024practical.bib。然后将它们链接到当前论文：

orx cite link 2024-06-15-efficient-quantization-for-edge-devices zhang2023efficient orx cite link 2024-06-15-efficient-quantization-for-edge-devices li2024practical

回到index.md，编辑 YAML 部分：

cite_keys: ["zhang2023efficient", "li2024practical"]

保存。现在执行orx paper preview，它会：

• 用 Pandoc 渲染index.md为 HTML
• 自动注入refs.bib中的条目（按 Chicago 样式）
• 在浏览器中打开预览页

你能在页面底部看到自动生成的参考文献列表，且点击条目可跳转到refs/中的原始 BibTeX 文件——这就是orx的“可追溯”设计：引用不是字符串，而是文件系统中的硬链接。

4.3 第三步：关联数据与代码，构建可复现实验

假设你的论文核心是一个量化训练脚本。先创建数据集目录：

mkdir -p datasets/imagenet-lite # （此处放入你的精简 ImageNet 数据，或创建 symbolic link） ln -sf ~/datasets/imagenet-1k datasets/imagenet-lite

再创建脚本：

mkdir -p scripts/quant-train nano scripts/quant-train/train.py

在train.py中写一个极简示例（仅示意结构）：

#!/usr/bin/env python3 """ orx-deps: torch>=2.0.0, torchvision>=0.15.0, numpy>=1.24.0 orx-data: ./datasets/imagenet-lite/train/, ./configs/quant.yaml """ import torch import torchvision import sys import os # 读取配置 config_path = os.path.join(os.path.dirname(__file__), '..', 'configs', 'quant.yaml') # ... 训练逻辑 print(f"Quantization training completed on {torch.__version__}")

注意开头的orx-deps和orx-data注释——这是orx的契约声明。现在创建配置文件：

mkdir -p configs nano configs/quant.yaml

内容示例：

model: "resnet18" quant_bits: 4 batch_size: 128

最后，执行可复现的训练：

orx run \ --script scripts/quant-train/train.py \ --data datasets/imagenet-lite \ --config configs/quant.yaml \ --output results/quant-exp-20240615

orx会：

• 检查orx-deps中的torch是否满足>=2.0.0（否则报错）
• 验证datasets/imagenet-lite是否可读
• 在临时沙盒中执行train.py，并将stdout、results/quant-exp-20240615/、环境快照打包
• 生成results/quant-exp-20240615/orx-run-20240615-164211.tar.gz

这个.tar.gz就是你的“可复现性证书”。任何人拿到它，解压后运行orx run --replay orx-run-20240615-164211.tar.gz，就能在自己机器上 100% 复现相同结果——因为沙盒里包含了所有必要依赖和精确的输入路径。

4.4 第四步：导出与协作：从本地到交付的平滑过渡

当论文初稿完成，需要投稿或分享时，orx export提供多种格式：

# 导出为 PDF（带正确引用） orx export pdf papers/2024-06-15-efficient-quantization-for-edge-devices/ # 导出为交互式 HTML（含代码高亮、图表） orx export html papers/2024-06-15-efficient-quantization-for-edge-devices/ # 导出为 Jupyter Notebook（保留可执行代码块） orx export notebook papers/2024-06-15-efficient-quantization-for-edge-devices/

orx export pdf的底层是 Pandoc + LaTeX，但它做了三处关键增强：

• 自动注入assets/css/print.css样式，确保页眉页脚、章节编号符合期刊要求
• 使用biblatex而非natbib，支持更灵活的引用样式切换
• 将orx run生成的results/目录中的图表（PNG/SVG）自动嵌入 PDF

更重要的是协作交付。orx package命令会创建一个自包含的交付包：

orx package papers/2024-06-15-efficient-quantization-for-edge-devices/ --include-code --include-data

它生成package-20240615-efficient-quantization-for-edge-devices.tar.gz，解压后结构为：

package-20240615-efficient-quantization-for-edge-devices/ ├── paper/ # 渲染后的 PDF + HTML ├── code/ # scripts/quant-train/ 的完整副本 ├── data/ # datasets/imagenet-lite/ 的符号链接（或按需复制） ├── reproducibility/ # orx-run-xxxx.tar.gz 沙盒包 └── README.md # 一键复现指南："tar -xf reproducibility/*.tar.gz && orx run --replay ..."

这个包可以直接发给审稿人、合作者或存档。它不依赖你的本地orx配置，因为README.md里明确写了最低orx版本要求（来自.orx/schema.json），且所有路径都是相对的。我在向 ACL 提交时，用此包替代了传统的“补充材料 ZIP”，审稿人反馈：“第一次不用装环境就能跑通实验，节省了 3 小时调试时间。”

5. 常见问题与排查技巧实录：那些官方文档不会写的实战经验

5.1 问题速查表：高频故障与一招解决

提示：orx所有命令都支持--debugflag，它会输出完整的执行链路、环境变量、调用的子命令及其返回码。这不是日志，而是调试地图——90% 的问题，看--debug输出就能定位到具体哪一行 shell 脚本失败。

5.2 实操心得：三年踩坑总结的 5 条铁律

铁律一：永远用orx init --template开始，绝不手建目录
我见过太多人直接mkdir papers && touch papers/index.md，结果orx paper list找不到——因为缺少.orx/元数据和schema.json。orx init不是仪式，是契约签署。哪怕你只需要一个空目录，也执行orx init --template minimal，它会生成最小合法结构。

铁律二：cite_keys必须在index.mdYAML 中声明，而非正文里写[1]
正文里的[1]是渲染产物，不是数据源。orx的引用管理基于 YAML 键，这样orx cite sync才能批量更新。正文里写[zhang2023efficient]是允许的（Pandoc 支持），但必须确保zhang2023efficient在cite_keys列表中。

铁律三：orx run的--data参数必须是目录，不能是单个文件
这是为了强制路径一致性。你想用config.yaml？把它放在configs/目录下，然后--data configs/。orx会自动解析orx-data注释中的相对路径。如果硬传单个文件，orx会报错：“Data path must be a directory for sandboxing”。

铁律四：orx package前务必git commit -a
orx package会读取 Git HEAD 的 commit hash 并写入README.md。如果没 commit，它会用dirty标记，导致交付包失去可追溯性。我的习惯是：每次orx run成功后，立即git add results/ && git commit -m "Run exp1"，再orx package。

铁律五：.orx/config.toml是你的研究策略文档，不是配置文件
我在config.toml里不仅写ai.summarize.command，还加了注释：

# Research Policy: All AI outputs must be reviewed before citation. # Use 'orx ai summarize' for drafting only; final text written by human. [ai.summarize] command = "ollama run llama3 --format json"

这份文件会被orx package自动包含在交付包中，成为你研究伦理的证明。它比任何论文里的“Methodology”段落都更有说服力。

5.3 进阶技巧：用orx做超出预期的事

技巧一：用orx hook实现自动化质量门禁
orx支持在关键操作前后触发 hook 脚本。在.orx/hooks/pre-paper-create.sh中写：

#!/bin/bash # 检查是否有未提交的更改 if ! git status --porcelain | grep -q '^??'; then echo "ERROR: Uncommitted changes detected. Commit first." exit 1 fi

这样每次orx paper create前，都会强制检查 Git 状态，避免新建论文时遗漏已有修改。

技巧二：orx query做跨项目知识图谱
orx query是一个隐藏的强力命令。执行：

orx query "papers where cite_keys contains 'zhang2023efficient'"

它会扫描所有papers/*/index.md，返回匹配的论文 ID 列表。配合jq，你能构建自己的研究脉络：

orx query "papers where status == 'published'" \| jq '.[].id' \| xargs -I {} orx paper export pdf {}

一键导出所有已发表论文的 PDF。

技巧三：orx sync与 rsync 的深度集成
orx sync本质是rsync的封装，但它理解orx的目录结构。配置~/.orx/config.toml：

[sync] remote = "rsync://backup/research" exclude = ["*.log", "results/*/temp/"]

然后orx sync push会：

• 跳过results/*/temp/目录（加速）
• 保留所有 symlink 的完整性（rsync -aH）
• 生成sync-log-20240615.log记录本次同步的文件数、字节数、耗时

我在 NAS 上部署了一个 cron job，每天凌晨 2 点执行orx sync push，从未丢过一个字节。因为orx的 sync 不是“覆盖”，而是“增量校验”——它先计算本地每个文件的 checksum，再与远程比对，只传输变化的部分。

6. 生态位辨析：OpenResearch 与当前热门 CLI 工具的本质差异

6.1 对比codex cli：不是模型调用器，而是工作流编排器

codex cli的核心价值是“把 GitHub Copilot 的能力带到终端”，它优化的是单次 AI 交互的效率：codex ask "write a regex for email"。OpenResearch 的orx完全不参与模型调用决策，它只规定“当你要 summarize 时，必须输出 JSON，且必须包含text字段”。这意味着：

• 你可以用codex cli作为orx ai summarize的 backend，只需配置command = "codex ask --format json"
• 但你也可以用codex cli单独工作，不受orx约束
• 更重要的是，orx的summarize命令可以被orx run自动触发（如orx run --script analyze.py中调用orx ai summarize --input report.md），形成闭环

codex cli解决“怎么问”，orx解决“问完之后怎么