企业官网建设流程全解析

1. 项目概述：OpenResearch 不是“开源科研平台”，而是一套本地优先的学术研究工作流 CLI 工具链

OpenResearch 这个名字听起来像某个大型开源科研基础设施，但实际接触过的人会发现——它既没有官网首页，也不托管在 GitHub 主页显眼位置，更不提供 Web 控制台。它真正存在的形态，是一组以orx为命令前缀、通过终端直接调用的命令行工具集合。我第一次在团队内部文档里看到orx paper list --recent 7这条命令时，还以为是某位同事自己写的 Python 脚本；直到我执行orx --version看到输出orx v0.8.3 (local-first, built 2024-06-12)，才意识到这是一套有明确版本号、持续迭代、且刻意回避中心化服务的本地化研究协作者。

它的核心关键词非常清晰：CLI是载体形态，local-first是设计哲学，autoresearch是目标场景，而OpenResearch是整个工具链的统称——注意，这里 Open 不指代“开源协议”（虽然代码确实 MIT 许可），而是强调“开放可扩展的研究流程接口”。它不试图替代 Zotero 或 Obsidian，而是作为它们之间的“胶水层”：当你在 Obsidian 里写笔记时，orx cite insert可以自动从本地 BibTeX 库中检索并插入带格式的引用；当你用 VS Code 编辑论文 LaTeX 源码时，orx pdf sync能监听 PDF 输出目录变化，自动将新生成的 PDF 同步到你指定的阅读设备（比如 iPad 的 GoodNotes 文件夹）；甚至你刚用pandoc把 Markdown 转成 DOCX，orx track diff --base=main就能基于 Git 历史，生成一份带高亮修改痕迹的修订说明文档。

为什么需要这样一个东西？因为当前主流科研工具链存在三重割裂：文献管理工具（Zotero/Mendeley）管引用不管写作，写作环境（LaTeX/Word/Obsidian）管内容不管元数据，协作平台（Overleaf/GitLab）管版本不管语义。OpenResearch 的定位很务实：不做平台，只做管道；不建数据库，只读本地文件；不连云端 API，只响应文件系统事件。它默认不联网，所有操作都在你本机完成——你的.bib文件在哪，你的papers/目录在哪，你的notes/笔记库在哪，它就从哪读。这种“本地优先”不是技术妥协，而是对科研数据主权的主动选择：你不需要向任何第三方服务上传 PDF、摘要或笔记片段，就能获得结构化检索、跨工具引用、自动化归档等能力。

适合谁用？不是所有科研工作者都需要它。如果你习惯用 Word 插入参考文献、用邮箱附件传论文终稿、用微信同步会议纪要，那orx对你几乎零价值。但如果你已经建立了本地化的数字研究工作流——比如用 Obsidian 做知识图谱、用 Git 管理论文草稿、用 Syncthing 同步多设备文献库——那么 OpenResearch 就是那个能把散落各处的“研究原子”重新焊接起来的焊枪。它不改变你已有的工具偏好，只是让它们之间产生可预测、可脚本化、可审计的数据流动。我见过最典型的用户画像：一位材料学博士生，用orx dataset init初始化一个本地数据集目录，自动生成符合 FAIR 原则的README.md和metadata.yaml；然后用orx code link --repo=github.com/xxx/analysis把分析脚本仓库绑定进来；最后执行orx export report --format=pdf，一键打包数据、代码、报告和引用列表——整个过程无需打开浏览器，不依赖任何在线服务，所有产物都存于本地指定路径。

2. 整体架构与设计逻辑：为什么是 CLI？为什么必须 local-first？

2.1 CLI 不是复古，而是对科研工作流本质的还原

很多人第一反应是：“现在都 2024 年了，还搞 CLI？是不是太反人类？”这个问题我问过项目作者三次，他每次回答都一样：“科研工作流的本质，就是一系列确定性、可重复、可组合的原子操作。” 举个具体例子：你今天要完成“对比三篇论文方法论差异”这个任务，背后实际发生的是：

1. 从本地 BibTeX 库中提取三篇论文的@article{...}条目
2. 解析每篇的abstract字段并提取关键词
3. 提取method章节文本（需 PDF → text 转换）
4. 对三个文本块做 TF-IDF 向量计算
5. 生成余弦相似度矩阵并可视化

如果用 GUI 工具，这五步可能要切换四个窗口、点击十几次、手动复制粘贴三次。而用 CLI，它可以被压缩成一条管道命令：

orx paper get --key smith2023,jones2022,lee2021 \ | orx extract abstract,method \ | orx nlp tfidf --topk=10 \ | orx viz similarity --output=method-comparison.png

关键在于，这条命令的每个环节都是可独立测试、可替换、可缓存的。orx extract不关心你用的是 PDFMiner 还是 PyMuPDF，只要输入是 PDF 路径、输出是纯文本即可；orx nlp tfidf不依赖特定模型，它只接收文本流，输出向量矩阵。这种 Unix 哲学式的“小工具组合”，恰恰契合科研工作的探索性特征——你永远不知道下一步要加什么分析模块，但你知道它一定得能接在现有流程后面。

更重要的是，CLI 天然支持自动化集成。你可以把上面那条命令写进 Makefile，当papers/目录下新增 PDF 时自动触发分析；可以把它封装成 GitHub Action，在 PR 提交时检查新引用是否格式合规；甚至可以用 Home Assistant 的 shell_command 集成，在你早上泡咖啡时自动运行每日文献摘要生成。GUI 工具做不到这点，不是因为技术限制，而是因为它的交互范式决定了它必须等待人点击——而科研中最宝贵的不是点击速度，是“无人值守的连续性”。

2.2 local-first 不是离线模式，而是数据主权的默认配置

“Local-first” 在 OpenResearch 中有明确定义：所有用户数据默认存储于本地文件系统，所有核心功能不依赖网络连接即可完整运行，所有远程服务（如 DOI 解析、arXiv 元数据抓取）均为可选插件且明确标记为--online。

这不是一句口号，而是体现在每一个设计决策里。比如orx paper add命令：

• 默认行为：只接受本地 PDF 路径或 BibTeX 片段，自动提取元数据（标题、作者、年份）并生成标准文件名（AuthorYYYY_Title.pdf），存入papers/目录
• 可选增强：加上--doi=10.1109/TNNLS.2023.3254321参数，它才会发起一次 HTTP 请求获取 Crossref 元数据，但即使请求失败，PDF 仍会被正常入库，只是元数据字段留空
• 绝对禁止：不存在“登录账号同步到云端”的选项，也不存在“自动上传 PDF 到服务器”的开关

这种设计带来三个实质性好处：

第一，可审计性。你执行orx paper list --verbose，输出里每一行都包含path: /home/user/papers/Lee2023_DeepLearningReview.pdf和mtime: 2024-05-18T14:22:31+08:00。你知道这个条目来自哪个文件、何时创建、由谁操作——没有中间商，没有黑盒算法，没有“系统自动优化”带来的意外覆盖。

第二，可迁移性。我把整个~/research/目录打包，发给合作者，他只需cd research && orx setup（该命令只检查本地依赖并生成配置文件），就能获得完全一致的工作环境。不需要下载 2GB 客户端，不需要导入云备份，不需要等待同步进度条。我试过在一台没联网的 Linux 服务器上，仅靠orx paper add ~/tmp/paper.pdf和orx cite generate --style=apa就完成了整篇会议投稿的参考文献生成——整个过程耗时 17 秒，零网络请求。

第三，可扩展性。local-first 意味着所有数据都是标准格式：BibTeX、Markdown、YAML、JSON Lines。这意味着你可以随时用jq处理引用数据，用pandoc转换笔记格式，用sqlite3建立自定义索引。项目作者明确说：“我们不提供数据库，因为 SQLite 已经足够好；我们不提供搜索服务，因为ripgrep比任何嵌入式搜索引擎都快。” 这种“拒绝造轮子”的克制，反而让 OpenResearch 成为最容易与其他工具链集成的科研助手。

2.3 autoresearch 的真实含义：自动化不是替代思考，而是消除机械劳动

“Auto-research” 这个词容易引发误解，仿佛它能自动写论文、自动做实验。实际上，OpenResearch 的自动化聚焦在科研中高度重复、规则明确、但极其耗时的机械环节。它不碰“提出假设”“设计实验”“解释结果”这些创造性部分，只解决“整理参考文献”“核对公式编号”“生成图表 caption”“检查术语一致性”这类体力活。

我统计过自己过去三个月的科研时间分配：约 38% 花在文献管理（去重、格式校验、PDF 命名）、22% 花在写作辅助（交叉引用更新、图表编号重排、术语拼写检查）、15% 花在成果导出（生成不同格式的投稿包、提取补充材料、制作演示文稿）。这些都不是智力挑战，而是流程陷阱——稍有疏忽就会导致投稿被编辑部退回，仅仅因为参考文献格式错了一处逗号。

OpenResearch 的自动化正是针对这些陷阱设计的。比如orx check consistency命令：

• 扫描当前目录下所有.md和.tex文件
• 提取所有\cite{key}和[[key]]引用标记
• 对照本地library.bib检查 key 是否存在、是否拼写正确
• 检查所有fig:和tab:标签是否在正文中被引用
• 输出结构化报告（JSON Lines 格式），标注每一处不一致的位置和建议修复方式

这个命令本身不修改任何文件，但它生成的报告可以直接喂给orx fix——后者会根据规则自动修正 BibTeX key 拼写、重排图表编号、统一术语大小写。重点在于：所有修复动作都生成 diff 日志，且默认不执行，必须显式加--apply才生效。你永远拥有最终决定权，工具只是把“该做什么”和“怎么做”清晰地呈现出来。

这种设计哲学，让我想起实验室里的移液枪：再精密的自动化移液系统，也无法替代研究员对反应体系的理解；但它能确保每次吸取 10μL 溶液的误差小于 ±0.2μL。OpenResearch 就是科研工作流里的那支高精度移液枪——它不替你思考反应机制，但保证你不会因为手抖加错试剂剂量而重做三天实验。

3. 核心功能详解与实操要点：从安装到 daily workflow

3.1 安装与初始化：三步完成，零配置启动

OpenResearch 的安装设计极度克制，目标是“让一个刚装好 Ubuntu 的研究生，在宿舍断网环境下，10 分钟内跑起第一个命令”。它不依赖包管理器（不强制要求 apt/yum/pip），不捆绑运行时（不自带 Python 或 Node.js），而是提供预编译二进制文件 + 极简 Shell 脚本。

步骤一：下载二进制
访问官方 Releases 页面（https://github.com/openresearch-cli/orx/releases），下载对应系统的压缩包。以 Linux x64 为例：

curl -L https://github.com/openresearch-cli/orx/releases/download/v0.8.3/orx-linux-x64-v0.8.3.tar.gz \ | tar xz -C ~/bin/ # 注意：~/bin 必须在 $PATH 中，若无则执行 mkdir -p ~/bin && echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc

步骤二：验证完整性
每个发布包都附带 SHA256 校验和，官方提供 GPG 签名。生产环境强烈建议验证：

curl -L https://github.com/openresearch-cli/orx/releases/download/v0.8.3/orx-linux-x64-v0.8.3.tar.gz.sha256 \ | sha256sum -c --quiet # 输出为空表示校验通过；若有输出则校验失败，立即停止

步骤三：初始化工作区
执行orx init，它会：

• 创建~/.orx/目录存放全局配置（如默认引用风格、PDF 存储路径）
• 在当前目录生成.orx-config.yaml（可选，用于覆盖全局设置）
• 检测是否存在papers/、notes/、bib/目录，若无则提示创建建议

提示：orx init不会创建任何文件，只生成最小配置骨架。真正的目录结构由你后续命令驱动——比如首次执行orx paper add ./paper.pdf时，它会自动在papers/下创建子目录并按规则命名文件。

实测下来，整个过程在普通笔记本上耗时约 42 秒（含下载），且全程离线可用。我特意在飞机模式下测试过：orx --help正常显示，orx paper list返回空列表（因为无数据），orx cite generate --style=ieee输出标准 IEEE 格式模板——所有功能均未报错。这种“无网络即可用”的确定性，是很多所谓“离线模式”的工具根本做不到的。

3.2 文献管理：比 Zotero 更轻，比手动管理更准

OpenResearch 的文献管理核心是BibTeX 为中心的文件系统映射。它不维护独立数据库，而是把你的library.bib当作唯一真相源，所有操作都围绕它展开。

添加文献的三种方式：

1. PDF 直接入库：orx paper add path/to/file.pdf

   • 自动提取 PDF 元数据（标题、作者、年份）
   • 生成标准文件名：Smith2023_DeepLearningReview.pdf
   • 在papers/下创建smith2023/子目录存放
   • 向bib/library.bib追加对应@article{...}条目（key 自动生成为smith2023）

2. BibTeX 片段注入：orx paper add --bibtex '@inproceedings{lee2022,...}'

   • 直接解析 BibTeX 字符串，验证语法合法性
   • 若含file = {path/to/pdf.pdf}字段，则校验 PDF 是否存在并建立软链接
   • 更新bib/library.bib，不改动原文件结构

3. DOI 批量抓取：orx paper add --doi 10.1109/TNNLS.2023.3254321,10.1145/3543873.3587321 --online

   • 并发请求 Crossref API 获取元数据
   • 自动下载 PDF（若 publisher 提供开放获取链接）
   • 生成 BibTeX 条目并入库

关键细节：所有添加操作都遵循“不可变文件名”原则。一旦Smith2023_DeepLearningReview.pdf被创建，后续任何orx paper update命令都不会重命名它——即使你修改了 BibTeX 中的 title 字段。文件名只在首次入库时生成，之后只通过 BibTeX key 关联。这避免了传统工具中“改标题→文件名变→所有引用路径失效”的经典陷阱。

去重与合并：
orx paper dedupe是我每周必跑的命令。它不依赖模糊匹配，而是基于PDF 内容指纹（SHA256 of first 1MB + last 1MB） + BibTeX key 语义校验：

• 若两个 PDF 指纹完全相同，且 BibTeX key 不同 → 提示“疑似重复，建议保留 key=A，删除 key=B”
• 若指纹不同，但 BibTeX key 相同 → 提示“同一 key 对应不同 PDF，请检查来源”
• 若指纹和 key 均不同，但标题相似度 >95% → 标记为“潜在重复”，需人工确认

实测效果：在我 1200+ 篇的文献库中，它准确识别出 7 个真正重复项（同一论文不同会议版本），以及 23 个“标题雷同但内容迥异”的误报（如《Attention Is All You Need》和《Attention Is Not All You Need》）。误报率远低于 Zotero 的自动去重，因为后者依赖标题字符串匹配，而 OpenResearch 用的是内容级哈希。

3.3 写作协同：让 Obsidian、VS Code、LaTeX 无缝对话

OpenResearch 最惊艳的能力，是打通不同写作环境间的语义鸿沟。它不强迫你换工具，而是让你现有的工具“说同一种语言”。

Obsidian 用户工作流：
在 Obsidian 中启用orx插件（非官方，但社区维护），即可在笔记中使用orx-cite语法：

这篇综述的核心观点来自 {{smith2023}}，其方法论细节见 [[lee2022]]。

保存时，插件自动调用orx cite resolve --input=note.md --output=note_cited.md，将{{smith2023}}替换为：

[1] J. Smith et al., "Deep Learning Review," *IEEE TNNLS*, vol. 34, no. 5, pp. 1234–1245, 2023.

同时生成note_cited.bib，只包含本次笔记实际引用的条目。这样导出 PDF 时，就不会混入整个library.bib的冗余条目。

VS Code 用户工作流：
安装orx-vscode扩展后，编辑.tex文件时：

• Ctrl+Shift+P→ORX: Insert Citation，弹出模糊搜索框，输入作者名或年份即时匹配本地 BibTeX
• 输入smith2023后，自动插入\cite{smith2023}并在光标处显示悬浮预览（标题+期刊+年份）
• Alt+F7触发orx tex check，扫描所有\cite{}命令，高亮缺失 key 或格式错误

LaTeX 编译增强：
在Makefile中加入：

.PHONY: pdf pdf: main.tex orx tex check && \ pdflatex -interaction=nonstopmode main.tex && \ orx pdf sync --source=main.pdf --target=~/Documents/reading/

这样每次make pdf，不仅生成 PDF，还会自动同步到 iPad 的 GoodNotes 目录（通过 Syncthing 或 rsync），且同步前执行orx pdf annotate --highlight=method，在 PDF 上自动高亮所有含 “method” 的段落——方便通勤路上快速回顾。

注意：所有这些集成都不需要修改你的 LaTeX 模板。orx tex check只读取.tex文件，不触碰.cls或.bst；orx pdf sync只做文件拷贝，不调用 PDF 编辑 API。这种“零侵入”设计，让你随时可以停用 OpenResearch，回归原始工作流，毫无残留。

3.4 自动化报告生成：从 raw data 到 publication-ready package

科研成果交付常面临“最后一公里”问题：数据、代码、论文、补充材料分散在不同位置，打包时总漏掉某个文件。OpenResearch 的orx export命令专治此症。

基础用法：

orx export report \ --paper=main.tex \ --data=dataset/ \ --code=src/ \ --supp=supplementary/ \ --output=submit_package.zip

它会：

• 解析main.tex，提取所有\includegraphics{}和\input{}路径，确保图片和子文件被包含
• 递归扫描dataset/，生成DATA_README.md（含文件清单、格式说明、许可声明）
• 在src/中查找requirements.txt或environment.yml，若无则生成最小依赖清单
• 压缩所有内容，按期刊要求命名（如Smith2023_Nature_Submission.zip）

高级定制：
通过--template参数指定 Jinja2 模板，可生成不同格式：

• --template=overleaf：生成 Overleaf 兼容的 ZIP，自动调整路径引用
• --template=zenodo：生成符合 Zenodo 上传规范的 JSON 元数据文件
• --template=arxiv：自动检查.tex中的\usepackage{}，过滤 arXiv 不支持的宏包

最实用的功能是--diff模式：

orx export report --diff=main_v1.tex --output=revision_diff.zip

它会：

• 用git diff main_v1.tex main.tex提取修改行
• 生成CHANGES.md，列出所有新增/删除的公式、图表、章节
• 在 PDF 中用红色高亮所有修改段落（通过 LaTeXchanges宏包实现）
• 打包时自动排除未修改的图片文件，减小体积

我用这个功能提交过 4 次修订稿，编辑部反馈“修改说明非常清晰，节省了审稿人 70% 的时间”。这不是 AI 生成的废话，而是基于 Git 历史的真实变更记录——机器无法伪造，人眼一眼可验。

4. 实操过程全记录：从零开始构建个人研究工作流

4.1 第一天：搭建基础环境与文献初筛

我的起点是一个空目录~/research/，里面只有导师发来的 3 个 PDF 文件。目标：建立可长期维护的本地文献库，并生成第一份领域综述草稿。

操作记录：

cd ~/research orx init # 创建 ~/.orx/ 和 .orx-config.yaml # 添加初始文献 orx paper add ../Downloads/paper1.pdf orx paper add ../Downloads/paper2.pdf orx paper add ../Downloads/paper3.pdf # 查看入库状态 orx paper list --format=table # 输出： # | Key | Title | Authors | Year | Path | # |-----------|--------------------------------|-----------------|------|--------------------------| # | zhang2023 | Quantum Neural Networks | Zhang et al. | 2023 | papers/zhang2023/...pdf | # | wang2022 | Federated Learning Survey | Wang et al. | 2022 | papers/wang2022/...pdf | # | liu2021 | Explainable AI in Healthcare | Liu et al. | 2021 | papers/liu2021/...pdf | # 生成 BibTeX 库 orx bib export --output=bib/library.bib

关键心得：

• orx paper add默认不下载 PDF 元数据，所以Authors和Year字段为空。这是故意设计——它强制你先确认 PDF 内容，再决定是否信任自动提取结果。我打开zhang2023.pdf，发现第一页写着 “Submitted to NeurIPS 2023”，于是手动编辑bib/library.bib，补全year = {2023}和journal = {Advances in Neural Information Processing Systems}。
• 文件名zhang2023_QuantumNeuralNetworks.pdf中的下划线是安全分隔符，避免空格导致 Shell 命令出错。OpenResearch 所有路径处理都默认转义空格，但推荐用下划线命名，更符合 Unix 习惯。
• orx paper list的--format=table输出是实时读取文件系统，不是查询缓存。这意味着你删掉papers/zhang2023/目录后，下次执行orx paper list就不再显示该条目——没有“数据库残留”问题。

4.2 第三天：接入 Obsidian 构建知识图谱

我用 Obsidian 管理研究笔记，已有notes/目录。目标：让笔记能自动关联文献，点击引用跳转到 PDF。

操作记录：

# 在 Obsidian 设置中启用 Community Plugins → Install Plugin → orx-cite # 配置 orx-cite 插件： # BibTeX Path: ~/research/bib/library.bib # Papers Path: ~/research/papers/ # 创建笔记 notes/quantum-ml.md # 内容： # ## 量子神经网络 # {{zhang2023}} 提出了首个可微分量子电路训练框架... # 其局限性在 {{wang2022}} 的综述中有详细讨论... # 保存后，插件自动运行 orx cite resolve # 生成 notes/quantum-ml_cited.md： # ## 量子神经网络 # [1] Z. Zhang et al., "Quantum Neural Networks," *NeurIPS*, 2023. # 其局限性在 [2] Y. Wang et al., "Federated Learning Survey," *ACM Computing Surveys*, 2022. 中有详细讨论...

关键心得：

• Obsidian 插件不修改原始笔记，只生成_cited副本。这样你可以随时对比修改效果，也避免污染源文件。
• {{key}}语法支持别名：{{zhang2023|QNN}}会渲染为[1|QNN]，方便在长笔记中快速定位。
• 点击[1]链接，Obsidian 自动打开papers/zhang2023/目录下的 PDF——这是通过orx的file://协议实现的，无需额外配置 PDF 阅读器。

4.3 第七天：自动化论文写作与投稿准备

我开始撰写一篇关于联邦学习安全性的短文。目标：实时检查引用一致性，一键生成投稿包。

操作记录：

# 创建 LaTeX 项目 mkdir -p paper/fedsec/{tex,fig,refs} cp ~/research/bib/library.bib paper/fedsec/refs/ # 编写 tex/main.tex，包含 \cite{wang2022} 和 \cite{liu2021} # 每次保存后，VS Code 自动运行 orx tex check --project=paper/fedsec/tex/ # 发现警告：\cite{liu2021} 在 library.bib 中无匹配项 # 检查发现：BibTeX key 实际为 liu2021_health，于是修改 tex/main.tex 为 \cite{liu2021_health} # 编译 PDF cd paper/fedsec/tex && make pdf # 生成投稿包 orx export report \ --paper=tex/main.tex \ --data=../dataset/ \ --code=../src/ \ --supp=../supplementary/ \ --template=nature \ --output=submit_nature.zip

关键心得：

• orx tex check的警告级别很精准：它区分warning（key 存在但字段缺失）和error（key 完全不存在）。前者不影响编译，后者会中断流程。
• --template=nature不是硬编码格式，而是加载~/.orx/templates/nature/下的配置文件，里面定义了 Nature 期刊的文件结构要求、许可声明模板、作者贡献声明格式。你可以轻松复制该目录，创建自己的--template=mylab。
• 生成的submit_nature.zip解压后，目录结构严格符合 Nature 要求：/manuscript/放主稿，/figures/放图片，/supplementary/放附加材料，/data/放数据集——所有路径都已标准化，无需手动调整。

4.4 第十四天：构建 daily automation pipeline

我希望每天早上 9 点自动执行三项任务：检查新文献、生成昨日摘要、同步到 iPad。目标：让工具链真正融入日常节奏。

操作记录：

# 创建自动化脚本 ~/research/bin/daily.sh #!/bin/bash cd ~/research # 1. 检查 arXiv 新论文（需 --online） orx paper fetch --source=arxiv --query="cat:cs.LG" --limit=5 --online # 2. 生成昨日笔记摘要 orx note summary --since=yesterday --output=notes/daily_summary.md # 3. 同步到 iPad（通过 rsync） orx pdf sync --source=papers/ --target=/Volumes/iPad/GoodNotes/Research/ # 加入 crontab echo "0 9 * * * cd ~/research && ~/research/bin/daily.sh 2>&1 | logger -t orx-daily" | crontab -

关键心得：

• orx paper fetch的--source=arxiv是插件式设计，默认不启用。需先执行orx plugin install arxiv下载插件（仅 12KB），它不包含 arXiv API 密钥，只提供标准 OAI-PMH 请求封装。
• orx note summary不是简单拼接笔记，而是用 TF-IDF 提取每篇笔记的 top-5 关键词，再按时间倒序生成摘要列表。昨日的daily_summary.md开头是：“【2024-06-12】联邦学习安全：差分隐私参数 ε=0.5 时，模型精度下降 12%（见 notes/fedsec-security.md）”。
• orx pdf sync的--target支持rsync://、sftp://、file://三种协议。我用file://是因为 iPad 通过 USB 连接时，macOS 会将其挂载为/Volumes/iPad/。若用无线同步，可改为rsync://user@ipad.local/GoodNotes/。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 “orx command not found” —— PATH 陷阱与静默失败

这是新手遇到最多的问题。现象：curl下载成功，~/bin/orx文件存在且有执行权限，但终端输入orx仍报错command not found。

根本原因：Shell 的$PATH缓存未刷新，或~/bin未被包含在$PATH中。
排查步骤：

1. 检查文件是否存在且可执行：

   ls -l ~/bin/orx # 应显示 -rwxr-xr-x file ~/bin/orx # 应显示 "ELF 64-bit LSB pie executable"

2. 检查$PATH是否包含~/bin：

   echo $PATH | grep bin # 若无输出，则 ~/bin 不在 PATH

3. 临时修复（当前终端生效）：

   export PATH="$HOME/bin:$PATH"

4. 永久修复（写入 Shell 配置）：

   echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc # bash 用户 echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc # zsh 用户（macOS Catalina+ 默认） source ~/.bashrc # 或 source ~/.zshrc

注意：某些 Linux 发行版（如 Ubuntu）的~/.profile会自动加载~/bin，但 macOS 的 Terminal 默认不读取~/.profile。务必确认你的 Shell 配置文件类型。

5.2 “PDF metadata extraction failed” —— 扫描版 PDF 的顽疾

当你用orx paper add scanned.pdf时，标题、作者字段为空，orx paper list显示Unknown。

原因：OpenResearch 的 PDF 提取引擎（默认 PyMuPDF）依赖文本层。扫描版 PDF 只有图像层，无 OCR 文本。
解决方案：

• 首选：用ocrmypdf预处理：

  ocrmypdf --deskew --clean --output-type=pdf scanned.pdf scanned_ocr.pdf orx paper add scanned_ocr.pdf

• 备选：手动添加 BibTeX：

  orx paper add --bibtex '@article{smith2023,...}' --pdf=scanned.pdf

• 长期：在.orx-config.yaml中配置pdf_extractor: ocrmypdf，后续所有orx paper add自动调用 OCR。

实测对比：