Hongdou for Obsidian 使用说明

Hongdou for Obsidian 用来在 Obsidian 中搜索红豆文献、插入可点击的文献标题、建立阅读笔记，以及导入红豆笔记和 PDF 文字批注。

适用版本：Hongdou for Obsidian 0.3.22 + Hongdou Obsidian Bridge 0.1.12。 当前为桌面预览版；截图来自 macOS、Obsidian 1.13.7，不适用于手机和平板。

第一次使用请先完成第 1 节。已经安装并连接后，可直接从第 2 节按命令名称查找说明。

• 1. 安装并连接红豆
• 2. 七个常用命令一览
• 3. 插入红豆文献链接
• 4. 创建文献阅读笔记
• 5. 在红豆中打开文献
• 6. 打开红豆文献附件
• 7. 导入红豆笔记与批注材料
• 8. 更新当前阅读笔记的红豆材料
• 9. 检查红豆连接
• 10. 可选：让红豆显示 Obsidian 引用
• 11. 设置与高级维护
• 12. 更新、停用与故障排查

插件生成文献跳转链接和阅读整理内容，不会自动生成论文引用编号或参考文献表。Obsidian 正文也不会自动改写红豆原生笔记。

1. 安装并连接红豆

安装两端插件

1. 在红豆打开 设置 → 引用 → 文档编辑软件 → Obsidian插件。
2. 点击 安装红豆端插件。显示 Hongdou Obsidian Bridge 0.1.12 且“已是最新版本”时无需重复安装。
3. 先用 Obsidian 打开过每个准备联动的笔记库，再回红豆点击 安装到所有 Obsidian 笔记库。已安装旧版时按钮会显示 更新所有 Obsidian 笔记库。
4. 在每个笔记库打开 Obsidian 设置 → 第三方插件，启用 Hongdou for Obsidian，确认版本为 0.3.22。更新后重新加载 Obsidian，或停用再启用一次插件。

红豆分别显示两端安装状态，并统一安装、更新或卸载全部可用笔记库。

多个名称表示 Obsidian 登记了多个笔记库，并不是电脑上装了多个 Obsidian。插件文件要写入每个笔记库，启用状态也由各笔记库分别管理。

红豆未找到目标笔记库时，先用 Obsidian 打开它，再在安装窗口点击 重新检测笔记库。自定义配置目录无法自动识别时，可展开 其他安装方式，另存 ZIP 插件包并按界面说明安装。

本套插件不需要 Zotero Link、Zotero Bridge 或 Better BibTeX。

连接红豆文献库

1. 启动红豆，确认当前账号和资料库正确。
2. 在红豆 设置 → 高级 中保持 允许此计算机上的其他应用程序与红豆智能文献管理通讯 开启。
3. 在 Obsidian 打开 设置 → Hongdou for Obsidian。
4. 在顶部 联动状态 查看连接结果，并在 默认文献库 选择搜索范围。
5. 显示未连接时，确认 红豆原生地址 为 http://127.0.0.1:18500，点击 检查红豆连接。更换账号或资料实例后，再点击 连接并使用此资料库。

“已连接红豆，…个文献库可用”表示读取连接成功。

保持默认 18500 地址即可。无需开启 Zotero 兼容模式，也无需配置 MCP；插件使用 hongdou:// 打开红豆，因此红豆与 Zotero 可以同时运行。

2. 七个常用命令一览

打开 Obsidian 笔记后，按 Command + P（Windows 为 Ctrl + P），输入“Hongdou”即可看到日常命令。

前三项覆盖大多数日常操作。“创建文献阅读笔记”建立独立阅读工作区；“插入红豆文献链接”只把引用放到当前写作位置。

3. 插入红豆文献链接

适用场景：正在编辑普通 Obsidian 笔记，需要在当前段落引用红豆文献。这通常是使用频率最高的命令。

1. 打开 Markdown 笔记，切到编辑视图或实时预览，把光标放到插入位置。阅读视图中不会显示此命令。
2. 执行 插入红豆文献链接。
3. 按标题、作者或年份搜索。点击结果可以多选，每次最多 20 篇；键盘可用 ↑ / ↓ 选择，Shift + Enter 切换选中。
4. 点击 插入所选文献（数量）。单篇也可直接按 Enter 插入。

插入结果：

• 文献标题出现在当前光标位置，不创建新文件。
• 实时预览和阅读视图只显示标题；点击标题直接在红豆中定位文献。
• 完整 hongdou:// 地址仅在源码视图中保留。
• 设置中的 引用显示文字 可改成“作者与年份”或自定义模板，只影响以后插入的链接。

标题本身就是返回红豆的入口，日常阅读时不显示冗长地址或额外图标。

此命令不创建阅读笔记，也不导入红豆笔记或批注。普通笔记只插入链接时，不会自动出现在红豆“Obsidian 引用”中；需要该能力时参见第 10 节。

4. 创建文献阅读笔记

适用场景：准备精读一篇文献，需要一篇长期维护的独立笔记来记录总结、证据和思考。

1. 执行 创建文献阅读笔记。
2. 搜索标题、作者或年份。
3. 点击目标文献，或用 ↑ / ↓ 高亮后按 Enter。此为单文献操作，选中后立即执行。

弹窗明确说明：命令建立独立阅读笔记，不会把内容写进当前笔记。

创建结果：

• 新笔记默认保存在 红豆文献 文件夹，可在设置中修改位置。
• 一级标题使用文献题名；文献概览显示标题、作者、日期、类型、文献库、DOI、标签和红豆跳转，长摘要单独收起。
• 我的阅读笔记预置“一句话总结、核心观点、方法与证据、我的思考”。
• 再次选择同一文献会打开已有阅读笔记，不覆盖内容，也不重复创建。

此命令不改写执行命令前所在的笔记，也不自动混入红豆原生笔记或 PDF 批注。需要这些材料时使用第 7 或第 8 节。

Markdown 中会保存 hongdou- 开头的稳定身份和 <!-- hongdou-metadata… --> 受控区域边界，用于改名、移动、安全更新和回跳。这些内部标记在阅读视图和实时预览中隐藏；源码视图中可见，请勿修改、删除或复制。

5. 在红豆中打开文献

适用场景：只想从 Obsidian 快速找到红豆中的某篇文献，查看条目信息、笔记、标签或相关文献。

1. 执行 在红豆中打开文献。
2. 搜索标题、作者或年份。
3. 点击目标文献，或用 ↑ / ↓ 高亮后按 Enter。

插件通过 hongdou:// 请求红豆定位条目。它不会在当前笔记插入文字，不创建文件，也不修改红豆数据。阅读笔记中直接点击 在红豆中查看文献 可得到相同结果，并且无需重新搜索。

红豆没有自动出现时，先执行第 9 节的连接检查，并确认系统中的 hongdou:// 由红豆处理。

6. 打开红豆文献附件

适用场景：已知主文献，希望从 Obsidian 选择并阅读它的 PDF 或其他附件。

1. 执行 打开红豆文献附件，搜索并选择主文献。
2. 在附件列表查看名称、类型和本地状态。
3. 本地文件可用时点击 打开附件；未下载或属于网页链接时，点击 在红豆中定位，再到红豆下载或检查。

附件打开动作由红豆完成，PDF 会进入红豆阅读器。插件不会把附件复制进 Obsidian，也不会在当前笔记插入附件链接。多个附件需要明确选择，插件不会猜测主附件。

看到“未确认本地文件”时，先在红豆完成下载，再重新打开附件列表。

7. 导入红豆笔记与批注材料

适用场景：把红豆条目下的原生笔记或 PDF 文字批注保存为独立 Obsidian 素材，之后自由整理和链接。

1. 执行 导入红豆笔记与批注材料，搜索并选择主文献。
2. 在材料列表查看子笔记和附件文字批注，可展开 查看 Markdown 预览。
3. 勾选材料，每次最多 20 段。
4. 点击 导入所选材料，完成后可点击 打开：… 查看文件。

导入结果：

• 每段材料保存成独立 Markdown 快照，默认位于 红豆文献/材料。
• 相同来源版本再次导入会复用已有文件，并保留本地修改。
• 来源变化后再次导入会生成新版本快照，旧文件继续保留。
• 读取范围是文献的直接子笔记和附件文字批注，不包括文献库顶层独立笔记。

图片、手写和嵌入资源目前不会导入；复杂排版可能转成可读文字并提示。此命令不改写当前阅读笔记；希望把材料集中到当前阅读笔记时使用下一节。

8. 更新当前阅读笔记的红豆材料

适用场景：正在整理第 4 节创建的阅读笔记，希望把所选红豆笔记或 PDF 文字批注集中放入该笔记，并在来源变化后安全刷新。

此命令只在当前文件是红豆文献阅读笔记时出现。

1. 打开目标阅读笔记，将其所有编辑标签页切到阅读视图，或关闭其他正在编辑该文件的标签页。
2. 执行 更新当前阅读笔记的红豆材料。插件按笔记身份读取对应文献，无需重新搜索。
3. 选择要添加或刷新的材料，点击 预览材料更新。
4. 核对每段材料的“新增、更新、无变化或手工编辑冲突”状态。
5. 点击 保存恢复副本并更新。

保护规则：

• 只处理选中材料；未选材料和受控区域外正文保持不变。
• 材料写入 红豆笔记与批注 区域，写入前保存完整恢复副本。
• 材料区域被手工修改时拒绝直接覆盖，可选择 保留原文，另存材料快照。
• Obsidian 中的修改不会反向写回红豆。

也可在文件列表中右键阅读笔记，选择 更新红豆笔记与批注材料。撤回一次插件更新的方法见第 11 节。

9. 检查红豆连接

适用场景：刚启动两款应用、搜索一直加载、提示未连接，或更换红豆账号和资料实例后排查。

执行 检查红豆连接 会检查：

• http://127.0.0.1:18500 是否可访问；
• 红豆是否返回可用文献库；
• 当前默认文献库是否仍存在。

成功时提示“已连接红豆，…个文献库可用”，状态栏显示 红豆：已连接。

连接检查只确认读取服务，不会完成配对或开启引用登记。更换账号或资料实例后，到插件设置重新选择文献库并点击 连接并使用此资料库。

10. 可选：让红豆显示 Obsidian 引用

前面七个命令的搜索、插入、创建、打开附件和读取材料，只需要连接红豆。如果还希望在红豆文献右侧看到引用它的 Obsidian 笔记，并从红豆跳回笔记，需要额外配对和开启引用登记。

1. 在红豆 设置 → 高级 → Obsidian 连接 开启 允许 Obsidian 发起连接请求。
2. 在 Obsidian 设置 → Hongdou for Obsidian → 联动状态 点击 发起配对。
3. 回红豆核对仓库名称、文献库和配对码，点击 查看并允许… → 允许登记引用。
4. 回 Obsidian 点击 检查配对结果，成功后点击 开启引用登记。

配对只授权当前 Obsidian 笔记库向所选红豆文献库登记引用，不授予修改文献或红豆笔记正文的权限。配对码 5 分钟内有效，请使用两端当前显示的号码，不要照抄截图。

哪些笔记会登记：

• 第 4 节创建的阅读笔记已有稳定身份，开启登记后可直接上报。
• 普通笔记只插入链接时不会自动登记整篇笔记。需要在 引用管理 → 关联已有笔记 中预览、备份并确认。
• 代码块、图片、HTML 链接、Wiki 链接、嵌入笔记和动态查询结果不计入引用。

登记完成后，在红豆文献右侧 Obsidian 引用 中可查看笔记并点击 在 Obsidian 中打开。

11. 设置与高级维护

这些入口集中在 设置 → Hongdou for Obsidian → 引用管理 / 高级维护，日常使用通常不需要逐项设置。

阅读笔记维护：

• 红豆修改标题、作者、DOI、摘要或标签：右键阅读笔记选择 更新红豆文献元数据。
• 检查已采用材料的来源和本地修改：右键阅读笔记选择 检查红豆材料来源。
• 撤回材料、元数据或来源删除标记更新：使用高级维护中的相应 恢复…更新 入口。
• 元数据更新不改文件名、自定义属性或“我的阅读笔记”；来源检查本身不修改笔记。
• 更新后又有新编辑时，插件会拒绝整篇恢复覆盖，请对照恢复副本手工取回。

关联、迁移和队列维护：

• 关联已有笔记为普通笔记增加稳定身份，预览和备份后才登记。
• 关联目录规则持续发现目录中的新候选，不会未经确认自动关联。
• 旧文献链接迁移逐条核对 zotero:// 链接，备份后改为红豆链接。
• 管理引用登记、批量核对、清理失效关联用于解除、恢复或修正历史登记。
• 诊断与重建损坏队列、仓库绑定与旧队列仅在界面明确提示队列损坏、连接归属变化或需要解绑时使用。

管理操作通常先暂停登记。保存后按界面提示重新开启，才会向红豆提交。请勿手工删除或修改队列文件。

12. 更新、停用与故障排查

备份整个 Obsidian 笔记库，包括隐藏的 .obsidian 文件夹。在红豆 设置 → 引用 → 文档编辑软件 → Obsidian插件 点击 更新所有 Obsidian 笔记库；红豆只替换程序文件，保留设置、队列、恢复记录和 Markdown。完成后重新加载各笔记库。

暂时停止上报时关闭 登记红豆笔记的引用关系。永久不用时，建议先在原红豆仍可访问时撤销配对，再备份并卸载。停用或卸载不会删除 Markdown、文献链接或红豆中的历史引用。

反馈时提供红豆、Obsidian 和两端插件版本、命令名称及完整提示文字。通常无需提交整个笔记库或私人文献内容。