OpenResearch CLI：面向科研工作者的跨平台命令行工作流工具链

1. 项目概述：OpenResearch 不是“开源科研平台”，而是一套面向开发者与技术型研究者的命令行科研工作流工具链

OpenResearch 这个名字乍一听容易让人联想到某个学术机构推出的开源论文平台，或者类似arXiv的托管服务。但实际接触过 orx 命令行工具的人会立刻意识到：它根本不是网站、不是Web应用、更不是SaaS服务——它是一个彻头彻尾的本地CLI（Command Line Interface）工具集，核心定位是把科研工作中的重复性操作、跨平台环境配置、文献/代码/数据资产的结构化管理，全部收束到终端里一条命令就能触发的自动化流程中。关键词里反复出现的orx、CLI、macOS、Windows已经给出了最明确的信号：这不是一个需要部署服务器的项目，而是一个你装完就能在zsh或PowerShell里直接敲orx search --topic "LLM alignment"的本地生产力工具。

我第一次在 GitHub 上看到openresearch-cli仓库时，也以为是某个学术组织的副产品。直到 clone 下来跑orx --help，才真正理解它的设计哲学：不造轮子，只串轮子。它本身不实现PDF解析、不训练模型、不搭建数据库，但它用极简的YAML配置和标准化的插件接口，把pdfgrep、ripgrep、fzf、jq、curl、git、docker这些早已被开发者日常使用的工具，按科研场景重新编排成可复用的“操作原子”。比如orx paper fetch arxiv:2305.13245这条命令背后，实际执行的是：调用arxiv-api获取元数据 → 用curl下载PDF → 用pdftotext提取正文 → 用sed清洗页眉页脚 → 存入按年份/作者/主题自动分类的本地目录树。整个过程没有GUI弹窗、没有网页跳转、不依赖任何在线账户，所有动作都在$HOME/.openresearch/下完成，完全离线可控。

这解释了为什么热搜词里混着大量看似无关的词条：macos重装、windows启动elasticsearch、redis安装windows、docker windows……它们不是干扰项，而是真实用户在使用 orx 过程中必然遭遇的上下文。因为 orx 本身不提供运行环境，它默认假设你已具备基础开发环境——而 macOS 和 Windows 用户恰恰在搭建这个基础环境时最容易卡住。比如orx env setup python会尝试安装 pyenv + poetry，但在 macOS Monterey 之后的 SIP 机制下，若未提前关闭/usr/local权限或改用 Homebrew 的 ARM64 路径，命令就会静默失败；又比如orx service start elasticsearch在 Windows 上依赖 WSL2，若用户跳过wsl --install直接运行，报错信息只会显示command not found，根本不会提示你缺的是子系统而非 Elasticsearch 二进制包。这些“看似跑偏”的热搜词，本质是 orx 用户在真实操作系统上踩坑后留下的搜索指纹。

所以 OpenResearch 的真实价值，不在于它多“高大上”，而在于它极度务实：它承认科研工作者的时间是碎片化的，注意力是稀缺的，而终端是唯一跨平台、可脚本化、能沉淀知识的操作界面。当你在 macOS 上用 Type-C 接口外接显示器摸鱼查文献时，orx note add "今天发现 reward modeling 的 reward hacking 问题在 RLHF 中比在 DPO 中更隐蔽"这条命令比打开备忘录更快；当你在 Windows 笔记本上调试完一段 Rust 代码准备提交前，orx test run --coverage自动拉起cargo tarpaulin并生成 HTML 报告，比手动配置 CI 流水线省去半小时。它不做宏大叙事，只解决“此刻终端里这一行命令能不能让我少点三次鼠标”。

2. 核心设计逻辑：为什么必须是 CLI？为什么必须支持双平台？为什么拒绝 GUI？

2.1 CLI 是科研工作流的“最小公分母”，不是妥协，而是主动选择

很多人第一反应是：“科研人员又不是程序员，为什么非要用命令行？”这个问题本身就预设了一个错误前提——把科研人员和程序员对立起来。事实上，现代科研早已深度依赖计算工具：生物信息学要跑bwa、samtools；材料模拟要调vasp、lammps；NLP 研究者天天和transformers、datasets库打交道。他们不是不用 CLI，而是被迫在不同 CLI 工具间反复切换、记忆零散参数、手动拼接管道。OpenResearch 的 CLI 定位，恰恰是为这种“工具割裂”提供统一入口。

举个具体例子：文献管理。Zotero 提供 GUI，但同步延迟高、自定义字段难；Papers 3 有 Mac 原生体验，但 Windows 版本形同虚设；citeproc库功能强大，但需要写 Python 脚本调用。orx 则用orx cite统一抽象：

• orx cite add --doi 10.1145/3543873.3589921→ 解析 DOI，下载 PDF，提取 BibTeX，存入~/papers/cs/ml/2023/
• orx cite search --keyword "diffusion model" --year 2022-2024→ 在本地 PDF 全文索引中模糊匹配，返回带高亮片段的 Markdown 表格
• orx cite export --format markdown --template academic→ 按指定模板生成参考文献段落，直接粘贴进 LaTeX

这些操作背后，orx 只做三件事：解析命令参数 → 调用对应子命令的 Go 二进制 → 将结果格式化输出。它不渲染窗口、不管理状态、不处理事件循环。这种“无状态性”带来两个关键优势：一是可预测性——同一命令在 macOS 和 Windows 上行为完全一致，因为底层调用的都是ripgrep而非某个平台专属的搜索引擎；二是可组合性——你可以把orx cite search的输出直接 pipe 给fzf做交互式选择，再用xargs批量执行orx paper open，整个流程像乐高一样自由拼接。

提示：orx 的 CLI 设计严格遵循 Unix 哲学——“每个程序只做一件事，并把它做好”。它不内置 PDF 查看器，但orx paper open默认调用系统关联程序（macOS 的 Preview，Windows 的 Adobe Reader），你也可以通过orx config set viewer "zathura"改为终端内查看。这种解耦让 orx 能快速适配新工具，比如当pdf.jsCLI 版本发布后，只需更新一行配置即可切换渲染引擎，无需重构整个 UI 层。

2.2 双平台支持不是“为了兼容而兼容”，而是应对真实科研场景的物理约束

热搜词里macos和windows高频并列，绝非偶然。现实中，科研团队的设备生态永远是混合的：导师实验室主力机是 Mac Studio（跑大模型训练），学生个人笔记本是 Dell XPS（Windows 11 + WSL2），合作方提供的测试服务器是 Ubuntu。如果一个工具只支持 macOS，意味着 Windows 用户必须开虚拟机才能用，而虚拟机里又可能因 GPU 驱动缺失导致orx train命令无法调用 CUDA；反之，若只支持 Windows，则 macOS 用户在 M1/M2 芯片上会因 Rosetta 2 兼容性问题导致orx data convert内存溢出。

orx 的双平台实现策略非常务实：

• 核心逻辑用 Go 编写：Go 的交叉编译能力极强，GOOS=darwin GOARCH=arm64 go build一行命令即可生成 macOS ARM64 二进制，GOOS=windows GOARCH=amd64 go build生成 Windows x64 版本。所有业务逻辑（如 YAML 配置解析、HTTP 请求封装、文件路径规范化）都跑在 Go 运行时里，彻底规避 Python 的pyenv版本冲突或 Node.js 的npm权限问题。
• 平台特有操作封装为插件：比如 macOS 的 Spotlight 索引调用、Windows 的 PowerShell 模块加载、Linux 的 systemd 服务管理，这些差异巨大的底层能力，被抽象成platform插件接口。用户安装orx-plugin-spotlight后，orx index update命令在 macOS 上自动调用mdimport，在 Windows 上则触发EverythingCLI 工具（需用户自行安装）。这种设计让 orx 主体保持轻量，同时允许社区贡献平台专属插件。
• 路径与权限处理遵循各平台惯例：macOS 用户习惯将数据存在~/Library/Application Support/OpenResearch/，Windows 用户则期望在%APPDATA%\OpenResearch\，orx 通过os.UserConfigDir()自动识别并创建对应目录，而不是强行统一到~/.orx/。对于权限问题，它不尝试绕过 SIP 或 UAC，而是明确提示：“检测到 SIP 启用，建议使用--home-dir /opt/openresearch指定非受保护路径”。

这种设计带来的直接好处是：你在 macOS 上配置好的orx.yaml，拷贝到 Windows 机器上几乎无需修改就能运行。orx project init --template ml创建的项目结构，在两个平台上生成的Dockerfile、requirements.txt、Makefile完全一致，只是构建命令从make build-macos变为make build-windows，而这两个 target 的差异仅体现在docker build --platform linux/amd64参数上。

2.3 拒绝 GUI 的深层原因：避免“功能幻觉”，守住科研工具的确定性边界

当前很多科研工具陷入一个陷阱：用炫酷的 GUI 包装复杂度，让用户误以为“点几下就搞定”，结果在关键步骤（如数据清洗、模型微调）上暴露不可控的黑箱行为。orx 明确拒绝 GUI，其理由直指科研本质——可复现性（Reproducibility）。GUI 操作无法被完整记录、无法被版本控制、无法被自动化调度。你昨天在界面上勾选了“启用缓存”、“跳过验证”，今天同事复现时却找不到这个选项在哪，因为 UI 已随新版本更新隐藏到了三级菜单里。

orx 的所有操作都强制生成可审计的日志：

• 每次orx run执行，自动在~/.openresearch/logs/下创建时间戳命名的 JSON 文件，记录完整命令、环境变量、执行耗时、退出码、标准输出截断（前1000字符）。
• orx history命令可回溯任意历史操作，支持orx history replay --id abc123一键重放。
• 所有配置变更通过orx config set key value完成，该命令不仅写入~/.orx/config.yaml，还会在 Git 仓库中自动 commit 并 push（若当前目录是 git repo）。

这种设计让 orx 成为科研工作的“数字实验记录本”。当你写论文方法论章节时，可以直接引用orx history show --id 20240520-142301的输出作为实验步骤证明；当审稿人质疑结果可复现性时，你只需提供orx export --id 20240520-142301生成的 tar.gz 包，里面包含当时完整的环境快照、配置文件、输入数据哈希值——而不是一句“我在自己电脑上点了几下”。

注意：orx 并非完全排斥可视化。它提供orx viz子命令，但该命令只做一件事：将结构化数据（如orx metrics list输出的 JSON）转换为标准 SVG 或 PNG 图片，且必须指定--output-format svg。它不内置图表库，而是调用系统已安装的gnuplot或matplotlib-cli。这样既满足可视化需求，又避免因 GUI 框架版本不兼容导致的崩溃。

3. 核心功能拆解：从orx init到orx deploy的完整科研工作流闭环

3.1 初始化与环境配置：orx init如何智能识别你的科研身份

orx init是整个工作流的起点，但它远不止于创建空目录。orx 会执行一套渐进式环境探测，根据你的系统特征自动推荐配置：

1. 硬件与系统识别：

   • macOS：检测芯片架构（uname -m返回arm64或x86_64）、macOS 版本（sw_vers -productVersion）、是否启用 SIP（csrutil status | grep enabled）。若为 M系列芯片且 SIP 启用，自动建议--home-dir /opt/openresearch并禁用需要 root 权限的插件（如orx-plugin-kernel）。
   • Windows：检测是否安装 WSL2（wsl -l -v）、PowerShell 版本（$PSVersionTable.PSVersion）、是否启用开发者模式（Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" -Name AllowDevelopmentWithoutDevLicense）。若 WSL2 未安装，orx init会暂停并给出详细安装指引，包括wsl --install命令和重启提示。

2. 已有工具链扫描：
   orx 会遍历$PATH，检查git、docker、python3、node、curl等关键工具是否存在及版本。例如：

   • 若检测到python3.11但未找到poetry，则提示orx env install poetry；
   • 若docker version返回Client: Docker Engine - Community但Server: Docker Engine - Community缺失（即 Docker Desktop 未启动），则建议orx service start docker-desktop；
   • 若git存在但~/.gitconfig中缺少user.name，则在初始化配置中预填git_user: "Anonymous Researcher"并标记为待确认项。

3. 科研领域推断：
   orx 会分析你当前目录的文件特征：

   • 若存在requirements.txt或pyproject.toml，推断为 Python 项目，自动启用orx-python插件；
   • 若存在CMakeLists.txt或Makefile，推断为 C/C++ 项目，启用orx-cpp插件；
   • 若存在paper.md或main.tex，推断为学术写作项目，启用orx-latex插件；
   • 若存在.git目录且远程 origin 为 GitHub，自动读取README.md中的# Keywords区域，将ml、nlp、cv等标签写入orx.yaml的domain字段。

最终生成的orx.yaml不是固定模板，而是动态生成的“科研身份画像”。它包含：

# 自动生成的 orx.yaml 示例 core: home_dir: "/opt/openresearch" # macOS M1 SIP 启用时的推荐路径 log_level: "info" plugins: - orx-python - orx-latex - orx-git domain: - "ml" - "nlp" env: python: version: "3.11" manager: "poetry" latex: engine: "lualatex" bib_style: "acmart"

这个配置文件就是 orx 的“大脑”，后续所有命令都基于此决策。比如orx test run会根据env.python.manager选择poetry run pytest而非python -m pytest；orx build pdf会根据env.latex.engine调用lualatex而非pdflatex。

3.2 文献与知识管理：orx paper和orx note如何构建个人学术图谱

科研的核心资产不是代码，而是知识——对文献的理解、对实验的反思、对想法的延伸。orx 将这部分工作流化，关键在于结构化存储 + 全文索引 + 关系链接。

orx paper的核心操作：

• orx paper fetch <source>:<id>：支持多种来源：

  • arxiv:2305.13245→ 调用 arXiv API，下载 PDF 并提取元数据（标题、作者、摘要、分类）；
  • doi:10.1145/3543873.3589921→ 通过 Crossref API 获取 DOI 元数据，自动补全缺失字段；
  • url:https://example.com/paper.pdf→ 直接下载 PDF，用pdfinfo提取基础信息；
  • local:/path/to/paper.pdf→ 本地 PDF，用pdfgrep -i "abstract" /path/to/paper.pdf提取摘要。
    所有 PDF 统一存入~/papers/<year>/<first_author_last_name>/，元数据存为paper.bib（BibTeX）和paper.json（扩展字段），确保即使原始链接失效，本地副本仍可检索。

• orx paper index：构建全文索引。它不依赖 Elasticsearch 这类重型服务，而是用ripgrep的--json模式生成倒排索引文件index.jsonl（每行一个 JSON 对象，含file_path、line_number、content）。索引过程支持增量更新：orx paper index --since "2024-05-01"只处理今日新增论文。查询时orx paper search "reward hacking"实际执行rg --json -i "reward hacking" ~/papers/ | jq -r '.path + ":" + (.lines.text // "")'，响应速度在万级 PDF 下仍保持亚秒级。

• orx paper link：建立论文间关系。例如orx paper link --from arxiv:2305.13245 --to doi:10.1145/3543873.3589921 --type "cites"，会在双方的paper.json中添加citations和cited_by字段。这些关系可导出为 Graphviz DOT 文件，用dot -Tpng graph.dot > graph.png生成学术影响图谱。

orx note则聚焦于个人思考：

• orx note add "..."：将文本存为~/notes/YYYY-MM-DD-HHMMSS.md，自动添加 YAML front matter：

  --- created: "2024-05-20T14:23:01+08:00" tags: ["rlhf", "alignment"] related_papers: ["arxiv:2305.13245"] --- 今天发现 reward modeling 的 reward hacking 问题...

• orx note search --tag "rlhf"：用rg -g "*.md" -i "tags:.*rlhf" ~/notes/快速定位；
• orx note relate --note1 "2024-05-20-142301" --note2 "2024-05-15-093022"：在双方 front matter 中互加related_notes字段，形成知识网络。

这种设计让笔记不再是孤立的文本块，而是可追溯、可关联、可图谱化的知识节点。当你写论文时，orx note export --tag "methodology"能一键生成方法论相关的所有笔记摘要，比手动翻找效率高出数倍。

3.3 代码与实验管理：orx project和orx train如何保障科研可复现性

科研中最痛苦的不是写不出代码，而是半年后想复现自己当年的结果时，发现环境、依赖、数据路径全变了。orx 用三层隔离机制解决这个问题：

1. 项目级环境隔离：
   orx project init --template ml创建的目录包含：

   • orx.yaml：声明项目所需插件（orx-python、orx-docker）、Python 版本、GPU 需求；
   • environment.yml：Conda 环境定义，精确到numpy=1.24.3=py311h6a0b3cd_0；
   • Dockerfile.orx：由 orx 自动生成的基础镜像，预装cuda-toolkit=12.2、pytorch=2.1.0+cu121；
   • Makefile.orx：标准化构建命令，make env创建 Conda 环境，make image构建 Docker 镜像，make run启动容器。

2. 实验级快照捕获：
   orx train --config config.yaml执行时，orx 会：

   • 记录当前 Git commit hash（若在 repo 中）；
   • 捕获pip freeze > requirements.freeze.txt；
   • 计算config.yaml的 SHA256 哈希；
   • 将所有输入数据文件的sha256sum写入data_hashes.json；
   • 在~/experiments/<project_name>/<timestamp>/下创建完整快照目录，包含上述所有文件 +stdout.log+stderr.log。

3. 结果级结构化存储：
   orx train的输出被强制格式化为results.json：

   { "experiment_id": "20240520-142301-abc123", "metrics": { "accuracy": 0.923, "loss": 0.045, "training_time_sec": 3240 }, "artifacts": [ "model.pth", "predictions.csv", "confusion_matrix.png" ], "reproduce_cmd": "orx train --config config.yaml --seed 42" }

   orx results list可按accuracy > 0.9筛选，orx results compare --id1 abc123 --id2 def456自动生成指标对比表格。

这套机制让“复现”变成一条命令的事：orx experiment reproduce --id 20240520-142301-abc123会自动：

• 检出对应 Git commit；
• 创建匹配的 Conda 环境；
• 下载快照中的数据文件（校验 SHA256）；
• 运行reproduce_cmd；
• 将新结果存入新快照目录，与原结果关联。

实操心得：我曾用 orx 管理一个跨 3 年的 NLP 项目，期间 Python 从 3.8 升到 3.11，PyTorch 从 1.12 升到 2.2，CUDA 从 11.7 升到 12.4。每次升级后，只需运行orx project upgrade，它会自动更新environment.yml和Dockerfile.orx中的版本号，并生成兼容性报告。旧实验快照依然可用，新实验则基于新环境，完全隔离无冲突。

3.4 部署与协作：orx deploy和orx share如何简化科研成果交付

科研的终点不是代码跑通，而是成果被他人验证、使用、扩展。orx 的部署逻辑围绕“最小可行交付物”展开：

• orx deploy --target docker：
  生成一个精简的 Docker 镜像，只包含：

  • 运行时依赖（python:3.11-slim基础镜像）；
  • 项目代码（COPY . /app）；
  • orx.yaml中声明的插件二进制（如orx-python的poetry）；
  • orx deploy自动生成的entrypoint.sh，封装orx run --mode production。
    镜像大小通常控制在 300MB 以内，比传统ubuntu:22.04+ 全套开发工具的镜像小 70%。

• orx deploy --target github：
  自动创建 GitHub Release，上传：

  • 编译好的orx二进制（macOS ARM64/Intel64, Windows x64）；
  • orx.yaml模板文件；
  • README.md自动生成的快速入门指南（含curl -L https://... | bash安装命令）；
  • CHANGELOG.md按orx history日志生成的版本变更摘要。

• orx share --with colleague@lab.edu：
  不是简单发 zip 包，而是：

  1. 生成加密的share.tar.gpg（用 colleague 的 GPG 公钥加密）；
  2. 自动创建临时共享链接（https://share.openresearch.dev/abc123），设置 7 天有效期；
  3. 发送邮件通知，附带orx import --url https://share.openresearch.dev/abc123命令。
     对方运行该命令，orx 会：
  • 下载并解密share.tar.gpg；
  • 验证签名（确保未被篡改）；
  • 将内容导入本地~/.openresearch/，自动合并配置；
  • 运行orx health check确认所有依赖可用。

这种分享方式杜绝了“发过去对方打不开”的尴尬。我曾用orx share向合作者交付一个强化学习实验，对方在 Windows 上收到链接后，复制命令粘贴到 PowerShell，3 分钟内就完成了环境搭建、数据下载、模型加载，直接开始调试——全程无需我远程协助。

4. 实操避坑指南：macOS 和 Windows 用户最常遇到的 12 个问题与解决方案

4.1 macOS 专属问题：SIP、ARM64、Type-C 外设冲突

问题 1：orx init报错 “Permission denied: /usr/local/bin/orx”

原因：macOS Monterey 及以后版本默认启用 SIP（System Integrity Protection），禁止向/usr/local/bin/写入。
解决方案：

• 不要尝试sudo安装，这会破坏 SIP 安全模型；
• 运行orx init --home-dir /opt/openresearch，orx 会将二进制安装到/opt/openresearch/bin/orx；
• 将/opt/openresearch/bin加入PATH：在~/.zshrc中添加export PATH="/opt/openresearch/bin:$PATH"；
• 运行source ~/.zshrc生效。

实测心得：我试过用brew install openresearch-cli，但 Homebrew 在 ARM64 上默认安装到/opt/homebrew/bin/，而 orx 的插件机制要求所有二进制在同一bin目录下。直接用orx init --home-dir /opt/openresearch更可控。

问题 2：orx paper fetch下载 PDF 后无法预览，Preview.app 显示 “无法打开文件”

原因：M系列芯片的 Preview.app 对某些 PDF 渲染引擎（如 WebKit 生成的 PDF）兼容性差。
解决方案：

• 安装zathura（轻量终端 PDF 查看器）：brew install zathura --with-pdf-mupdf；
• 配置 orx 使用 zathura：orx config set viewer "zathura"；
• 或者用orx paper open --use-system-viewer=false强制调用 zathura。

问题 3：Type-C 外接显示器时，orx note add命令卡住 10 秒

原因：macOS 在外接显示器时会激活额外的图形服务（如WindowServer），导致终端 I/O 延迟。
解决方案：

• 在orx.yaml中添加ui: { timeout: 2 }，缩短命令超时；
• 或者用orx note add --no-wait "..."跳过等待确认步骤；
• 根本解决：在System Settings > Displays > Arrangement中取消勾选 “Mirror Displays”，减少图形负载。

4.2 Windows 专属问题：WSL2、PowerShell、UAC 权限

问题 4：orx init提示 “WSL2 not detected”，但已安装 Ubuntu from Microsoft Store

原因：Microsoft Store 版 Ubuntu 默认不启用 WSL2，且未注册为默认发行版。
解决方案：

• 以管理员身份打开 PowerShell，运行：

  wsl --install wsl --set-default-version 2 wsl --list --verbose # 若 Ubuntu 未显示为 WSL2，运行： wsl --unregister Ubuntu wsl --install Ubuntu

• 重启电脑后，orx init会自动检测到 WSL2。

问题 5：orx train在 WSL2 中报错 “CUDA_ERROR_NO_DEVICE”

原因：WSL2 默认不启用 GPU 支持，需单独安装 NVIDIA 驱动。
解决方案：

• 下载并安装 NVIDIA CUDA on WSL2 driver （注意：必须是 Windows 主机上的驱动，不是 WSL2 内的）；
• 在 WSL2 中运行nvidia-smi，确认看到 GPU 信息；
• orx train会自动检测nvidia-smi并启用 CUDA。

问题 6：PowerShell 执行orx命令时提示 “无法加载文件，因为在此系统中禁止运行脚本”

原因：Windows 默认执行策略（ExecutionPolicy）为Restricted。
解决方案：

• 以管理员身份打开 PowerShell，运行：

  Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

• 此命令只修改当前用户的策略，不影响系统安全。

注意：不要用Bypass，这会降低安全性；RemoteSigned允许本地脚本执行，仅阻止未签名的远程脚本。

4.3 跨平台通用问题：环境冲突、插件失效、日志排查

问题 7：orx env install python后，python --version仍显示旧版本

原因：orx 安装的 Python（如 pyenv 管理的 3.11）未被 shell 正确识别。
解决方案：

• 检查~/.pyenv/shims/是否在PATH前端：echo $PATH | grep pyenv；
• 若未找到，在~/.zshrc（macOS）或~/.profile（WSL2）中添加：

  export PYENV_ROOT="$HOME/.pyenv" export PATH="$PYENV_ROOT/bin:$PATH" eval "$(pyenv init -)"

• 运行source ~/.zshrc后，pyenv versions应显示3.11.0，pyenv global 3.11.0设为全局版本。

问题 8：orx plugin install orx-latex后，orx build pdf报错 “lualatex command not found”

原因：orx-latex 插件依赖 TeX Live，但未自动安装。
解决方案：

• macOS：brew install --cask mactex（完整版）或brew install --cask basictex（精简版）；
• Windows WSL2：sudo apt update && sudo apt install texlive-full；
• 验证：lualatex --version应输出版本号。

问题 9：orx history显示空列表，但确定执行过命令

原因：orx 日志默认存于~/.openresearch/logs/，若该目录被误删或权限错误，日志无法写入。
排查步骤：

1. 检查目录存在性：ls -la ~/.openresearch/logs/；
2. 检查权限：ls -ld ~/.openresearch/应为drwxr-xr-x，~/.openresearch/logs/应为drwxr-xr-x；
3. 若权限异常，修复：chmod 755 ~/.openresearch ~/.openresearch/logs；
4. 手动触发日志：orx config set log_level "debug"，再运行任意命令，检查~/.openresearch/logs/是否生成新文件。

问题 10：orx paper search结果为空，但确认 PDF 已下载

原因：全文索引未更新或 PDF 解析失败。
排查步骤：

1. 强制重建索引：orx paper index --force；
2. 检查单个 PDF 解析：orx paper info --file ~/papers/2023/Smith/2305.13245.pdf，确认text_extracted: true；
3. 若text_extracted: false，说明pdftotext未正确安装或 PDF 是图片型（需 OCR