在红豆中选中文献，就能看到哪些 Obsidian 笔记引用了它，并点击返回笔记。
本文对应：Hongdou Obsidian Bridge 0.1.12 + Hongdou for Obsidian 0.3.19。 请使用配套红豆客户端。截图在 macOS、Obsidian 1.13.7 中实际操作取得；其他平台的完整验证尚未完成。
第一次使用，按下面的 安装 → 配对 → 试用一篇笔记 完成即可。连接管理和排查方法可在需要时再看。
安装两端插件
两个插件分别装在哪里
| 安装位置 | 插件 | 用来做什么 |
|---|---|---|
| 红豆客户端 | Hongdou Obsidian Bridge | 批准连接，显示引用笔记，返回 Obsidian |
| Obsidian 仓库 | Hongdou for Obsidian | 搜索文献、插入链接、创建文献笔记、导入笔记与批注材料、登记引用 |
“仓库”就是 Obsidian 中存放笔记的文件夹。红豆可以把 Obsidian 端插件统一安装到全部可用仓库；安装后仍需在每个仓库中分别启用并完成配对。
两端链接可以互相跳转，笔记正文不会自动双向同步。 从红豆导入的笔记或批注，需要在 Obsidian 中主动导入或预览更新；在 Obsidian 写下的正文不会改写红豆原生笔记。
在红豆安装 Bridge
- 打开红豆 设置 → 引用 → 文档编辑软件。
- 找到 Obsidian插件。首次使用点击 安装红豆端插件；已安装旧版本时按钮会显示 更新红豆端插件；显示版本
0.1.12且“已是最新版本”时无需重复安装。 - 安装或更新成功后，如需核对，可打开 工具 → 插件中心 → 已安装，确认 Hongdou Obsidian Bridge 0.1.12 已启用。列表较长时向下滚动。
红豆会分别显示红豆端和 Obsidian 端的已安装版本；存在旧版时会直接提示可更新到的内置版本。
安装后核对名称、版本和“已启用”状态。图中的“停用”按钮表示插件当前正在启用。
在 Obsidian 安装配套插件
- 先在 Obsidian 中打开过每个准备联动的笔记库，让它们出现在 Obsidian 的笔记库记录中。
- 回到红豆的 设置 → 引用 → 文档编辑软件 → Obsidian插件。首次安装点击 安装到所有 Obsidian 笔记库；存在旧版时点击 更新所有 Obsidian 笔记库。全部是
0.3.19时会显示 重新安装所有 Obsidian 笔记库，日常无需点击。 - 弹窗会列出全部可用笔记库及其安装、启用状态。核对清单后执行安装或更新；该操作会同时处理清单中的全部可用笔记库，不能在这里单独选择一个。
- 完成后，在每个需要联动的仓库中打开 Obsidian 设置 → 第三方插件，启用 Hongdou for Obsidian 0.3.19。如果更新前已经启用，请重新加载 Obsidian，或停用后再启用一次。
弹窗中出现两个或更多名称，表示 Obsidian 登记了多个笔记库，并不是电脑上有多个 Obsidian 应用。
红豆端的安装、更新和卸载会统一处理全部可用笔记库；启用和配对仍以仓库为单位。更新只替换三个程序文件，插件设置、引用队列、目录规则、索引、恢复记录和 Markdown 笔记会保留。卸载同样保留这些数据，只移除插件运行文件及 Obsidian 的启用记录。
如果没有找到目标笔记库，先用 Obsidian 打开它，再展开 其他安装方式 并点击 重新检测笔记库。使用自定义配置目录或仍无法识别时，另存 ZIP 并按《Hongdou for Obsidian 使用说明》中的手动步骤安装。
本套插件不需要 Zotero Link、Zotero Bridge 或 Better BibTeX。
首次配对
让红豆和准备联动的 Obsidian 仓库同时打开。截图使用的是“红豆联动使用示例”仓库；操作时核对你自己的仓库名称与配对码，不要照抄截图中的码。
第 1 步：在红豆允许连接请求
- 打开红豆 设置 → 高级。macOS 可从顶部 Hongdou → 设置 进入，或按
Command + ,。 - 确认上方的 允许此计算机上的其他应用程序与红豆智能文献管理通讯 已勾选。
- 在右侧向下滚动，找到 MCP 下方的“Obsidian 连接”。
- 勾选 允许 Obsidian 发起连接请求。
只需开启“允许 Obsidian 发起连接请求”。MCP 是否开启不影响配对；下方的“兼容 Zotero 外部工具”也无需开启。
本套插件默认使用 18500 和 hongdou://，红豆与 Zotero 可以同时运行，无需更改端口。允许请求不等于自动批准，新的仓库仍需要你确认。
第 2 步：在 Obsidian 连接文献库
- 打开 Obsidian 设置 → Hongdou for Obsidian。侧栏看不到时向下滚动。
- 保持 红豆原生地址 为
http://127.0.0.1:18500。 - 点击 连接并使用此资料库。
- 看到“已连接红豆”后，在 默认文献库 中选择需要使用的库，例如 我的文库。
看到“已连接红豆，…个文献库可用”，表示文献读取连接成功，还需要继续完成下面的配对。
第 3 步：发起请求，在红豆批准
- 在 Obsidian 同一设置页的 配对授权 区域，点击 发起配对。
- 记下界面显示的配对码，回到红豆的 Obsidian 连接。
- 在 待确认请求 中核对仓库名称、文献库和配对码，再点击 查看并允许…。
- 在弹窗中再次核对，点击 允许登记引用。
配对码 5 分钟内有效。这里显示的是本次请求的临时核对码。
红豆和 Obsidian 显示的配对码应一致。仓库识别码属于排障信息，普通配对只需核对仓库名称、文献库和配对码。
确认后只允许这个仓库向所选文献库登记引用，不授予修改红豆文献或笔记正文的权限。
第 4 步：回到 Obsidian 完成配对，开启登记
- 回到 Obsidian 插件设置，点击 检查配对或授权状态。
- 确认显示 配对成功，凭据已保存并通过红豆验证。
- 继续向下滚动，打开 登记红豆笔记的引用关系。这个开关在“引用登记（预览）”区域靠下的位置，不在配对按钮旁边。
打开后，下方会显示引用登记的待发、冲突和待核对数量。第一次还没有文献笔记时，数量为 0 是正常的。
到这里首次设置才完成。以后日常使用不需要反复配对。
配对码过期时，在 Obsidian 点击 清理待配对记录 后重新发起。红豆若显示“已同意，等待插件确认领取凭据”，请回 Obsidian 点击 检查配对或授权状态。
用一篇笔记确认联动成功
- 在 Obsidian 按
Command + P打开命令面板，输入 打开文献笔记，执行 Hongdou for Obsidian 的同名命令。 - 输入文献标题或作者，点击要用的文献即可；也可用上下键高亮后按
Enter。 - Obsidian 会在 红豆文献 文件夹中创建笔记。保持两款应用运行，等待引用登记完成。
- 回到红豆，选中同一篇文献。
- 点击最右侧竖栏中的红紫色 H 图标，定位 Obsidian 引用。也可在右侧文献详情向下滚动找到该区域。
- 看到这篇笔记的条目后，点击 在 Obsidian 中打开，确认返回刚才的笔记。
笔记条目沿用右侧详情栏背景，优先显示标题，并列出仓库、笔记位置、引用次数和同步时间。完整仓库识别码不会占用日常界面。
如果你是在已有普通笔记里插入链接：还需要在 Obsidian 执行 关联已有笔记，按预览完成关联并重新开启登记。单纯插入链接能返回红豆，但不会自动把整篇普通笔记登记到红豆。具体步骤见配套 Obsidian 说明的“让已有笔记也出现在红豆中”。
日常查看引用与返回笔记
- 选中文献，在 Obsidian 引用 查看登记过的笔记。列表会自动检查更新，也可以点击 刷新；记录较多时点击 下一页。
- 点击 在 Obsidian 中打开 返回笔记。红豆会把已校验的目标直接交给系统中的 Obsidian 打开。
- 笔记改名或在仓库内移动后，只要保留关联属性，仍可定位。不要给不同笔记复制相同的
hongdou-document-id。 - 面板显示的是最后一次同步的结果，并不表示 Obsidian 当前在线。红豆提示“已发送到 Obsidian”只代表发出了跳转请求，请以 Obsidian 中实际打开的笔记为准。
面板针对单独选中的文献条目。选中多个条目、附件或独立笔记时，不显示这份文献引用列表。希望父文献显示关联时，请在 Obsidian 插入该文献的链接；附件链接不会自动算作父文献引用。
暂停或撤销连接
在红豆 设置 → 高级 → Obsidian 连接 → 已授权连接 管理仓库授权。
仓库改名后，授权列表仍显示“配对时仓库”；引用条目显示最后同步的名称。仅在排查同名仓库时展开“技术信息”核对完整仓库识别码。
| 你想做什么 | 建议操作 | 之后如何恢复 |
|---|---|---|
| 暂停一个仓库的引用上报 | 在 Obsidian 关闭 登记红豆笔记的引用关系 | 再次开启，已有队列和历史引用保留 |
| 暂停全部配对连接 | 在红豆关闭 允许 Obsidian 发起连接请求 | 重新开启；已有授权保留，待确认请求会被取消 |
| 停用整个红豆联动插件 | 在插件中心停用 Bridge | 重新启用；授权和引用数据保留，面板重新出现 |
| 不再允许某个仓库连接 | 对该连接点击 撤销…，核对后确认 | 需要重新配对；已有笔记及历史引用仍保留 |
如果还能打开原 Obsidian 仓库，也可以在 Obsidian 插件设置中执行 撤销配对连接，同时清理那一端保存的凭据。
撤销授权不会清空历史引用。只想让某一篇笔记不再出现在列表中，请在 Obsidian 使用 管理引用登记 解除它的登记。
遇到问题时
| 现象 | 按这个顺序检查 |
|---|---|
| 高级设置里没有“Obsidian 连接”或只有安装提示 | 插件中心确认 Bridge 已启用、版本正确 → 关闭再打开设置 → 必要时重启红豆 → 核对是否使用配套客户端 |
| Obsidian 连接失败或搜不到文献 | 红豆是否运行 → 本机通讯是否开启 → 地址是否为 http://127.0.0.1:18500 → 是否选择正确文献库 |
| 红豆没有待确认请求 | 开启允许请求 → Obsidian 发起配对 → 过期后清理待配对记录、重新申请 |
| 已批准，但没有引用条目 | Obsidian 检查配对状态 → 开启引用登记 → 普通笔记先“关联已有笔记” → 确认笔记含有该文献链接 |
| 修改后没有立刻更新 | 保持两端运行，在 Obsidian 执行 检查引用登记队列；有待发时等待，冲突或待核对时按提示处理，不要反复配对 |
| 点击回跳没有打开目标 | 检查 Obsidian 是否已安装并可启动 → 对应仓库是否可用 → Obsidian 插件是否启用 → 查看其缺失文件、重复身份等提示 |
| 旧链接打开了 Zotero 或其他应用 | 在 Obsidian 使用 检查旧文献链接，核对目标后迁移为红豆链接；不要只改系统默认打开应用 |
连接失败后可能需要等待约一分钟再自动重试；大量笔记首次登记也需要时间。不要通过删除配置文件或队列文件“重置”。
更新与资料保留
更新前备份红豆资料和 Obsidian 仓库（包括隐藏的 .obsidian 文件夹）。新版客户端提供更新包后，在红豆 设置 → 引用 → 文档编辑软件 → Obsidian插件 点击 更新红豆端插件；然后点击 更新所有 Obsidian 笔记库，在弹窗中核对全部可用笔记库并执行更新。完成后重新加载各仓库，或停用后再启用插件，核对版本。
无需为了更新删除授权或引用数据。红豆只替换 main.js、manifest.json、styles.css，保留仓库中的其他插件配置和数据文件。ZIP 手动更新仍可在安装弹窗的 没有找到仓库？ 中使用。
停用或卸载插件不会删除红豆文献、原生笔记或 Obsidian Markdown 文件，也不代表历史授权已主动撤销。永久停用前，先撤销不再使用的配对。
反馈问题时提供两端应用与插件版本、操作步骤和提示文字即可。不要把配对凭据、完整私人仓库或含个人笔记的备份公开上传。
