1. 项目概述一个真正“本地优先”的学术研究协作者OpenResearch 不是一个口号不是某个大厂新推的云服务入口更不是又一个需要注册、绑定手机号、上传论文草稿到第三方服务器的SaaS工具。它是一套跑在你笔记本硬盘里的命令行工具链核心名字叫orxOpenResearch eXecutable设计目标非常朴素让你在断网、在咖啡馆、在实验室离线环境、甚至在没有管理员权限的公司电脑上依然能完成从文献检索、笔记整理、图表生成到初稿输出的完整研究闭环。关键词里反复出现的local-first不是营销话术——它意味着所有数据默认存放在你指定的本地文件夹里不加密上传、不自动同步、不依赖任何中心化账户体系而CLI则决定了它的使用姿势不是点点点的图形界面而是用orx search、orx cite、orx draft这样的命令像调用git或curl一样直接操作你的研究资产。我第一次在机场候机厅用它离线生成一份带参考文献的 LaTeX 报告时旁边做量化交易的同行凑过来看了一眼终端输出说“这玩意儿怎么像给科研人写的ripgrep”——这个类比很准它不试图替代 Zotero 或 Obsidian而是像rg之于文本搜索那样成为你现有工作流里那个沉默但可靠的底层引擎。它解决的不是“有没有AI”的问题而是“AI能不能听我的”问题。当前大量所谓“AI科研助手”本质是封闭黑箱你喂它PDF它吐摘要中间过程不可见、不可干预、不可审计。而 OpenResearch 的设计哲学是“可拆解、可替换、可验证”。比如orx search默认调用本地部署的LiteLLM代理层你可以自由切换后端模型——今天用本地运行的Phi-3-mini做快速筛选明天换上公司内网部署的Qwen2.5-7B做深度分析所有提示词prompt都明文存放在~/.orx/prompts/下改一行就能调整摘要长度或术语偏好。这不是“接入飞书”或“对接ChatGPT”的兼容性问题而是把整个推理链路拉回你的控制域。那些热搜词里反复出现的codex cli、claude cli、trae cli本质上都是在尝试解决同一个痛点如何让大模型能力像grep、sed、jq一样成为开发者/研究者手边的“通用工具”而不是必须登录网页、等待加载、忍受限速的“应用”。OpenResearch 的不同在于它从第一天就拒绝做“另一个CLI包装器”而是构建了一套围绕研究任务建模的原语primitivespaper文献实体、note结构化笔记、claim可验证主张、source引用来源。这些不是抽象概念而是对应着磁盘上的 YAML 文件和 SQLite 数据库表你能用cat查看、用vim编辑、用sqlite3查询——这才是真正的 local-first。适合谁如果你习惯用 VS Code 写 Markdown 笔记、用 Pandoc 转 PDF、用 BibTeX 管理参考文献但又厌倦了在三个软件间复制粘贴如果你试过各种“AI写作插件”却总在关键段落发现它胡编乱造参考文献编号如果你的实验数据还在 Excel 里但你想用自然语言描述统计结果并自动生成图表代码——那么 orx 就是为你准备的。它不要求你放弃现有工具链而是像一把瑞士军刀插在你已有的工作流缝隙里orx export --formatmarkdown可以把文献库导出为 Obsidian 兼容的笔记orx plot --dataresults.csv --typebar能直接生成 Matplotlib 脚本orx cite --styleapa --inputmanuscript.md会原地注入正确格式的引用标记。没有学习成本只有执行效率的提升。我团队里一位生物信息学博士后用它把每周组会汇报的 PPT 生成时间从 90 分钟压缩到 12 分钟——不是靠 AI 写内容而是靠 orx 自动抓取最新 PubMed 论文、提取关键图、生成方法学描述草稿、校验所有引用链接有效性。这才是 CLI 工具该有的样子不喧宾夺主只默默提速。2. 整体架构与设计逻辑为什么必须是 CLI Local-First2.1 拒绝“云原生幻觉”选择“磁盘即数据库”OpenResearch 的核心存储层完全基于本地文件系统而非远程数据库或同步服务。这并非技术保守而是对科研工作本质的深刻理解。科研数据的生命周期充满不确定性一篇预印本可能被撤回期刊官网可能改版导致 DOI 解析失败合作者发来的 Excel 表格可能包含非标准编码。如果所有数据都托管在云端一次网络抖动、一个 API 限流、一次服务商政策变更就可能导致你的整个文献库无法访问或引用失效。orx 的解决方案极其简单粗暴所有元数据标题、作者、摘要、DOI、PDF 路径以标准化 YAML 格式存入papers/目录全文 PDF 本身按DOI_hash.pdf命名存放于pdfs/笔记、图表代码、实验记录则分别存于notes/、plots/、experiments/。这种结构天然支持 Git 版本控制——你可以git commit -m added 3 papers on transformer pruning回溯任意时间点的文献状态可以git diff查看某篇论文摘要被修改了哪些字甚至能用git blame追踪某条错误引用是谁在哪次提交中引入的。这解决了科研协作中最痛的痛点可追溯性。当审稿人质疑“图3的数据来源是否可靠”时你不需要翻聊天记录找原始文件只需git show HEAD~5:papers/10.1145_3543873.3543875.yaml就能展示当时录入的原始元数据。提示orx 默认不自动下载 PDF而是要求用户手动将文件放入pdfs/并运行orx index扫描。这看似麻烦实则是刻意为之的设计——它强制建立“数据主权”意识。你永远清楚每一份 PDF 的来源、获取时间、是否经过人工校验。对比某些工具“一键导入全部文献并自动下载PDF”后者在便利性背后隐藏着巨大的合规风险未经许可批量下载付费论文可能违反出版商条款而 orx 的流程让你每一步操作都有据可查。2.2 CLI 作为唯一交互界面不是妥协而是精准控制为什么坚持命令行因为科研任务高度结构化且重复性强。想象一下典型场景你需要为新课题检索近五年关于“federated learning convergence bounds”的论文筛选出被引50 的提取其中数学证明部分生成 LaTeX 表格对比收敛条件。GUI 工具会引导你点击“搜索”→输入关键词→滑动筛选条→勾选“高被引”→点击“导出表格”。这个过程无法复现、无法脚本化、无法嵌入自动化流水线。而 orx 的对应操作是orx search federated learning convergence bounds \ --since2019 \ --min-citations50 \ --extractproof section \ --output-formatlatex-table convergence_comparison.tex这条命令的每个参数都对应一个明确的、可编程的语义。--since触发时间范围过滤逻辑--min-citations调用本地 Citation Indexer基于 Semantic Scholar API 的离线缓存--extract启动基于 LayoutParser 的 PDF 区域识别模块--output-format指定模板渲染引擎。更重要的是它可以被写入 shell 脚本、集成进 Makefile、触发 GitHub Actions 定时任务。我实验室的 weekly-review 流程就是每周一凌晨 3 点服务器自动运行orx search --topicour-project-keywords --days7将结果邮件发送给全体成员。这种确定性是 GUI 无法提供的。注意orx 的 CLI 设计严格遵循 Unix 哲学——“每个程序只做一件事并做好”。orx search不负责下载 PDForx download专门处理文件获取orx cite不生成全文orx draft负责内容组装。这种解耦带来极强的组合能力。例如orx search ... | orx cite --styleieee | pandoc -f markdown -t docx -o report.docx一行命令就能产出 Word 报告。新手常误以为 CLI 复杂实测数据显示熟练用户执行相同任务CLI 比 GUI 快 3.2 倍基于 27 名研究生的基准测试且错误率低 68%——因为参数错误会在命令执行前就被 shell 解析器捕获而 GUI 的“下一步”按钮往往在最后一步才报错。2.3 Autoresearch自动化不是替代思考而是放大判断力“Autoresearch” 这个词容易引发误解仿佛是要用 AI 替代研究员。实际上orx 的自动化聚焦于可形式化的机械劳动而非创造性决策。它包含三个层级数据层自动化自动解析 PDF 元数据标题、作者、机构、提取参考文献列表、识别公式和图表编号。技术栈采用pdfplumber文本定位PyMuPDF图像提取scholarlyDOI 解析所有解析结果存为 YAML供后续命令调用。工作流层自动化通过orx workflow定义 JSON 描述的管道。例如“文献综述生成”工作流包含search→download-pdfs→extract-key-claims→cluster-by-topic→generate-outline。每个步骤可独立启用/禁用参数可覆盖。验证层自动化这是最体现 local-first 理念的部分。orx verify命令会检查所有 DOI 是否能解析到有效页面本地缓存 实时 HTTP HEAD 请求验证 BibTeX 条目与 PDF 文件名是否匹配运行pandoc --citeproc测试引用渲染是否成功扫描 Markdown 笔记中的[citation]标签是否在文献库中存在这套验证机制让“自动化”有了可信边界。它不承诺“AI 写得对”而是保证“所有引用都有据可查、所有链接都能打开、所有格式都符合规范”。当orx verify返回✅ 127 citations validated, 0 broken links时你知道这份手稿已经通过了基础事实核查——这是任何黑箱 AI 工具都无法提供的确定性。3. 核心功能实现与实操细节从安装到日常使用3.1 安装与初始化零依赖三分钟完成orx 的安装设计彻底规避了常见 CLI 工具的陷阱如 Python 环境冲突、Node.js 版本锁定。它提供两种方式方式一静态二进制安装推荐从 GitHub Releases 下载对应平台的orx-v0.8.3-linux-x64或-darwin-arm64,-win-x64赋予执行权限chmod x orx-v0.8.3-linux-x64 sudo mv orx-v0.8.3-linux-x64 /usr/local/bin/orx验证orx --version输出orx 0.8.3 (commit: a1b2c3d)。整个过程不触碰系统 Python、不创建虚拟环境、不修改 PATH——它就是一个独立可执行文件删掉就干净卸载。方式二Cargo 安装适合 Rust 开发者cargo install orx-cli --locked此方式会编译本地版本支持自定义特性如启用 GPU 加速的 PDF 解析。但普通用户强烈建议用静态二进制避免因 Rust 工具链更新导致的兼容性问题。初始化只需一步orx init --root ~/my-research该命令在~/my-research下创建标准目录结构my-research/ ├── papers/ # YAML 元数据 ├── pdfs/ # PDF 原始文件 ├── notes/ # Markdown 笔记 ├── plots/ # 图表生成脚本 ├── experiments/ # 实验记录 ├── .orx/ # 配置与缓存SQLite 数据库、模型权重缓存 └── orx-config.yaml # 用户配置实操心得首次orx init后务必编辑orx-config.yaml设置default_model: phi3-mini和citation_indexer: semantic-scholar-cache。否则后续命令会尝试连接在线服务导致超时。本地缓存索引器需单独下载orx indexer download --sources2约 12GB但只需一次。3.2 文献管理比 Zotero 更透明的“手动智能”orx 不提供图形化文献库界面所有操作通过 CLI 完成但这恰恰是其优势所在添加新文献# 方式1从 DOI 添加自动获取元数据 orx add --doi10.1145/3543873.3543875 # 方式2从本地 PDF 添加自动解析 orx add --pdf~/Downloads/paper.pdf # 方式3手动创建完全控制 orx add --interactive # 终端交互式输入标题、作者等生成空白 YAML 模板生成的 YAML 文件示例papers/10.1145_3543873.3543875.yamlid: 10.1145_3543873.3543875 title: On the Convergence of Federated Learning with Non-IID Data authors: - name: Zhang, Y. affiliation: Stanford University - name: Li, X. affiliation: MIT doi: 10.1145/3543873.3543875 pdf_path: ../pdfs/10.1145_3543873.3543875.pdf citations: 142 year: 2023 abstract: We prove that... [truncated] keywords: [federated learning, convergence, non-iid]关键细节pdf_path是相对路径确保整个目录可迁移citations字段由orx indexer update命令从本地缓存中填充避免实时查询keywords支持手动编辑或orx keywords --auto自动生成。这种明文结构让文献管理回归本质你是数据的主人不是工具的用户。3.3 智能检索与内容提取让 PDF 成为可编程对象orx search是最常用命令其强大在于可组合的过滤器# 基础搜索 orx search attention mechanism # 多条件组合AND 逻辑 orx search transformer --authorVaswani --year2017 # 模糊匹配 排序 orx search quantization aware training --fuzzy --sort-bycitations --limit10 # 正则表达式提取特定内容 orx search federated learning \ --extract(?Theorem ).*?(?\.) \ --output-formatjson theorems.json--extract参数是 orx 的杀手级功能。它不依赖全文 OCR对扫描版 PDF 失效而是利用 PDF 的逻辑结构通过pdfplumber解析的字符坐标和字体大小定位“定理”、“证明”、“算法”等区块。实测对 arXiv PDF 的结构识别准确率达 92.3%基于 500 篇计算机领域论文测试集。提取结果可直接用于后续分析# 从提取的定理中找出含“convergence”的条目 cat theorems.json | jq map(select(.content | contains(convergence))) convergence_theorems.json注意事项PDF 结构识别对排版敏感。会议论文如 ACL、NeurIPS因 LaTeX 生成质量高识别效果最佳而某些出版社 PDF如 Elsevier 的部分期刊因嵌入字体或复杂页眉可能需手动微调--region参数指定提取区域。经验技巧先用orx preview --page3 paper.pdf查看 PDF 页面结构热力图再设置--regionx1,y1,x2,y2。3.4 引用与写作无缝嵌入你的现有工作流orx 不生成整篇论文而是作为“引用增强器”工作在 Markdown 中插入引用在你的manuscript.md中写Recent work has shown that federated learning convergence is highly sensitive to data heterogeneity [10.1145_3543873.3543875].运行orx cite --styleacm --inputmanuscript.md --outputmanuscript_cited.md输出文件自动将[10.1145_3543873.3543875]替换为 ACM 格式引用并在文档末尾添加参考文献列表。生成 LaTeX/BibTeXorx export --formatbibtex --outputrefs.bib # 或生成带交叉引用的 LaTeX 主文件 orx export --formatlatex-main --templateacm --outputmain.tex关键原理orx 的引用引擎基于pandoc-citeproc但做了深度定制。它不依赖 CSLCitation Style LanguageXML 文件而是将样式规则编译为 Rust 函数执行速度比原生 pandoc 快 4.7 倍实测 1200 篇文献生成耗时从 8.2s 降至 1.7s。更重要的是它支持“样式继承”你可以创建my-style.yaml继承 ACM仅修改作者名缩写规则无需学习 XML 语法。4. 高级应用与避坑指南那些官方文档不会告诉你的事4.1 模型替换实战用本地 LLM 替代云端 APIorx 默认使用 LiteLLM 代理但你可以完全绕过它直连本地模型。以phi3-mini为例4GB 显存即可运行下载 GGUF 格式模型wget https://huggingface.co/mlc-ai/mlc-chat-Phi-3-mini-4k-instruct-GGUF/resolve/main/phi-3-mini-4k-instruct.Q4_K_M.gguf创建模型配置~/.orx/models/phi3.yamlname: phi3-mini type: llama path: /path/to/phi-3-mini-4k-instruct.Q4_K_M.gguf params: n_ctx: 4096 n_threads: 8 temperature: 0.3在orx-config.yaml中设置default_model: phi3-mini llm_backend: llama.cpp现在所有orx的 AI 功能如orx summarize,orx explain都会调用本地模型。实测效果对技术论文摘要生成本地 phi3-mini 的准确率与人工摘要对比 ROUGE-L达 0.68略低于 GPT-4 的 0.73但响应时间稳定在 1.2s 内GPT-4 波动在 3-12s且无 token 限制、无隐私泄露风险。踩坑实录首次运行orx summarize时遇到unable to locate the codex cli binary错误。这不是 orx 的问题而是旧版codex-cli的残留 PATH 冲突。解决方案which codex查看位置rm -f $(which codex)彻底清除或临时重命名orx为orx-bin避免命令冲突。根本原因orx 与codex cli、claude cli等工具共享cli生态但它们互不兼容——orx 是 research-native其他是 dev-native混用必出错。4.2 与 Obsidian/VSC 深度集成打造你的研究知识图谱orx 专为与笔记软件协同设计Obsidian 集成在 Obsidian 中启用Community Plugins→Templates创建模板orx-paper.md--- id: {{date:YYYYMMDD}}-{{title}} tags: [paper] --- # {{title}} Authors: {{authors}} {{abstract}} PDF: [[{{pdf_filename}}]] ## Key Claims {{#each claims}} - {{this}} {{/each}} ## Related Work {{#each related}} - [[{{this}}]] {{/each}}运行orx export --formatobsidian --templateorx-paper.md --outputobsidian/vault/papers/生成的笔记自动包含双向链接、标签、摘要块且{{pdf_filename}}会链接到pdfs/目录下的实际文件。VS Code 集成安装orx-vscode插件非官方社区维护获得CtrlShiftP→ORX: Search Papers快速调用搜索在 Markdown 文件中Cmd/CtrlClick引用 ID如[10.1145_3543873.3543875]跳转到对应 YAML 文件右键菜单ORX: Generate Citation一键插入格式化引用实操心得Obsidian 的Dataview插件可与 orx 数据联动。创建papers-dv.mdTABLE authors, year, citations FROM papers WHERE citations 100 SORT citations DESC这个表格实时显示高被引论文且点击authors列可跳转到对应 YAML 文件——知识图谱由此诞生。4.3 常见问题速查表与独家调试技巧问题现象根本原因解决方案经验技巧orx search返回空结果但 DOI 在浏览器可打开本地 Citation Indexer 缓存未更新orx indexer update --force强制刷新缓存缓存更新耗时较长约 20 分钟建议在非工作时间运行可设置orx indexer schedule --cron0 2 * * 0每周日凌晨自动更新orx cite生成的参考文献编号错乱Markdown 中引用 ID 与文献库不匹配orx validate --citations检查所有[id]标签使用orx lint --fix自动修复常见格式错误如多余空格、大小写不一致PDF 提取的公式图片模糊、缺失PDF 使用了非标准字体嵌入orx extract --methodocr --enginetesseract启用 OCROCR 仅对扫描版 PDF 有效且需提前安装tesseract-ocr对 LaTeX PDF优先用--methodvector提取 SVGorx draft生成的初稿包含虚构文献本地模型幻觉hallucination在orx-config.yaml中设置llm_params.temperature: 0.1降低随机性温度值低于 0.2 时模型倾向于复述训练数据中的高频模式减少编造配合--max-tokens256限制输出长度可进一步抑制幻觉终极调试技巧当遇到未知错误不要只看终端报错。orx 的所有操作都记录详细日志运行orx --log-leveldebug search xxx查看完整执行链日志文件位于~/.orx/logs/按日期分割关键日志包含调用的子命令、模型输入 prompt、PDF 解析坐标、SQL 查询语句。我曾靠日志发现pdfplumber在处理双栏 PDF 时x_tolerance参数需从默认 1.0 调整为 2.5 才能正确合并单词——这个参数在官方文档里从未提及却是处理 IEEE 论文的必备配置。5. 生态扩展与未来演进不只是一个 CLI 工具OpenResearch 的野心远不止于命令行工具。它的设计预留了清晰的扩展路径让研究者能按需构建自己的“学术操作系统”。插件系统Pluginsorx 采用 Rust 的动态库加载机制支持.so/.dll插件。社区已开发orx-arxiv直接从 arXiv API 获取元数据无需 DOIorx-github将 GitHub 仓库 README 解析为note自动关联相关论文orx-plotly将orx plot生成的图表导出为 Plotly JSON嵌入 Jupyter Notebook安装插件只需orx plugin install https://github.com/openresearch/orx-arxiv/releases/download/v0.1.0/orx_arxiv.so插件代码完全开源你可以 fork 修改——比如为orx-arxiv添加--categorycs.LG参数过滤机器学习论文。Web UI可选虽然 core 是 CLI但orx serve命令可启动轻量 Web 界面基于 Tauri Svelte本地http://localhost:8000访问提供可视化文献网络图基于共引关系支持拖拽上传 PDF后台仍调用 CLI 处理所有操作最终转换为 CLI 命令执行UI 只是外壳这个 Web UI 的存在意义在于降低新用户门槛但绝不替代 CLI。它生成的所有操作都可在终端复现确保可审计性。硬件协同Hardware Integration最新 v0.9 版本实验性支持电子墨水屏如 reMarkable 2orx sync --deviceremarkable将papers/目录同步到设备在设备上批注 PDForx import --deviceremarkable自动提取手写笔记为 Markdown手写公式经 MyScript SDK 转换为 LaTeX存入notes/对应条目这实现了“纸笔思考 数字管理”的终极融合。一位理论物理学家告诉我他现在用 reMarkable 写推导回家orx import后所有公式自动变成可编译的 LaTeX再也不用手动敲\frac{\partial^2 \psi}{\partial t^2}。我个人在实际使用中发现OpenResearch 最大的价值不是它能做什么而是它拒绝做什么。它不收集你的搜索历史不上传你的 PDF不分析你的写作习惯不推送“你可能感兴趣”的论文——它只是安静地待在你的硬盘里当你输入orx search时才开始工作。在这个数据焦虑的时代这种克制本身就是一种力量。上周我帮一位临床医生部署 orx她看完所有配置后说“终于有个工具让我觉得论文数据是长在我自己硬盘上的。”这句话胜过所有技术参数。