思源桥：把思源笔记接入你的 AI 助手

让 AI 安全地阅读、搜索和修改你的思源笔记。

安装思源桥之后，你可以在 Codex、Claude Code、Hermes、WorkBuddy 等 AI Agent 中直接处理自己的知识库。你只需要说清楚想找什么、想读什么、想怎么改，剩下的文档定位、长文读取、块结构处理和写入检查都由思源桥完成。

它主要服务于文档和知识库场景：写长文、整理资料、修改表格、管理文档树，以及处理文档之间的引用关系。数据库、闪卡和块样式等功能目前不在支持范围内。

你可以把这些事情交给 AI

• “找出我过去关于拖延和注意力的笔记，整理一下反复出现的观点并写一篇汇总文档，要求引用原文档中的具体段落。”
• “把我的课程笔记整理成一份适合期末复习的知识框架并引用来源。”
• “读一下这篇报告，把里面的架构图和截图也讲给我听。”
• “这篇文章第三节有些混乱，保留原意，重新调整段落顺序。”
• “修改旅行计划表里的日期，再增加一列预算。”
• “把电脑里的照片和行程文件插入这篇旅行记录对应的位置。”
• “把本地 Markdown 文档导入为新笔记，或把其中一段内容插入现有笔记。”
• “新建一个项目笔记本，把这些PDF资料整理为文档放进去并重新分类。”

AI 可以按关键词搜索整个知识库，也可以浏览笔记本和文档目录。SQL 搜索按原查询顺序返回前 20 条可见命中：正文块完整展示，文档展示前 20 个正文展示块；隐藏内容不返回、不计数。图片只保留地址，嵌入 SQL 不展开；上游截断时会提示使用 LIMIT/OFFSET 继续查询，不自动补查。遇到长文时，它会先看到文章大纲，再按完整段落分段阅读，不会把内容从一句话中间截断。需要修改时，它能定位到具体段落，完成单段改写、连续多段重组、前后插入、整段删除和文末追加。

表格可以按行列修改单元格，也可以增加或删除一行、一列。图片和普通文件可以上传到思源资源目录，本地文件夹则会作为链接插入文档。本地 Markdown 文件可以直接导入为新文档，也可以把其中内容插入到现有文档的某个位置；文件里的本地图片、附件和文件夹引用会一并导入，网络图片保持原地址。笔记本和文档也可以由 AI 创建；已有文档可以改名、移动、复制、导出或删除。

在插件设置中开启「读文档时默认返回图片」后，AI 读取文档时会把其中的截图、图表随文字一起返回，按原文顺序穿插；单次读取的图片总量不超过 9 MB，放不下的图片会说明原因并保留文件路径或原地址，供 AI 单独读取。确有需要时，你确认后 AI 也可以无视该限制一次性返回全部图片。该开关默认关闭。重要提示：如果你使用的模型不支持图片输入，开启后调用此工具时可能会报错。但我还没实际验证过，现在DeepSeek、GLM等大部分（之前不能看图的）模型都已经支持多模态。如果遇到报错请提issue或者社区反馈。

思源的块引用也在处理范围内。你可以查询“这篇文档引用了哪些块”，也可以查询“哪些块引用了这篇文档”。两种查询都覆盖文档及其内部所有块，并递归汇总子文档的引用次数。AI 修改或删除内容时，思源桥也会检查这些操作是否会让已有引用失效。文档里用 {{SELECT ...}} 嵌入的查询结果也会被读取：思源桥先确认每个目标可见，再读取正文，并以引用块展示来源路径；隐藏目标不出现、不计数，没有可见目标时只说“查无此块”。

修改笔记时，思源桥会做什么保护

AI 的优势是快，但一次错误操作也可能影响很多内容。思源桥把确认、快照、引用检测和隐私权限放进了实际操作流程。

创建、编辑、移动、复制或删除内容之前，必须由用户明确同意。正式写入前，思源桥会先创建思源工作空间快照。结果不符合预期时，可以进入思源的数据仓库手动恢复。思源桥不会替用户自动回滚，避免恢复操作覆盖后续产生的正常修改。

删除文档、重写已有内容或合并多个段落时，原来的文档 ID 和块 ID 可能消失。如果这些内容仍被其他笔记引用，思源桥会默认停止操作，并列出允许展示的引用来源。只有用户看过影响并明确允许后，AI 才能继续破坏这些引用。同一篇文档也可以随时主动检查引用，不需要等到删除时才发现。

隐私规则由用户在思源中直接维护。笔记本或文档可以设置为读写、只读或隐藏，权限会沿文档树继承。隐藏内容不会出现在列表、搜索、阅读和操作结果里；只读内容可以参与查询和整理，但不能被修改。隐私规则文档本身对 AI 隔离，AI 无法读取或修改。

关闭笔记本只代表暂时不用，不代表隐藏。搜索和读取时，思源桥会临时打开需要访问的关闭笔记本，完成后再恢复原来的关闭状态。如果某些内容不希望 AI 接触，应当在隐私规则中设置为隐藏。

安装和开始使用

使用思源桥需要桌面版思源笔记和 Python 3.11 或更高版本。

1. 在思源集市搜索“思源桥”并安装插件。
2. 打开插件设置，在 MCP 配置页面保存当前工作空间 Token。
3. 复制插件生成的 MCP 配置，发送给你的 AI Agent，让它按照所在平台的格式完成注册。
4. 重启 AI Agent，然后说：“帮我找一下笔记里的某个主题。”

两台电脑的思源目录不同时，需要分别打开插件设置，复制各自电脑生成的配置。

插件首次启用时，思源桥会在当前工作空间创建一个笔记本（名称是“思源桥”）。里面保存思源桥 MCP 会用到的用户个性化要求、工作空间索引、使用指南和隐私规则。安装或更新后会随插件重新加载自动维护，不需要打开设置页，也不需要先调用 AI 工具。所有文档都可以像普通思源文档一样查看、编辑。

你可以在“用户个性化要求”里告诉 AI：回答应该多简洁、写入前需要怎样确认、哪些笔记本更重要，以及整理文章时应遵循什么习惯。这些要求保存在思源里，会跟随工作空间同步。

思源桥默认在正文左侧显示实时块序号，AI看到的块序号与你看到的一致，方便 AI 与你交流定位具体段落。文档结构变化后会自动重算。

当前不支持

• 手机端：思源桥通过本地 Python 程序运行，目前只适用于桌面端。
• 数据库编辑：数据库可以读取为普通表格，暂不支持修改。
• 闪卡、标签和块样式等功能。
• 删除整个笔记本：目前只能创建笔记本；删除操作只针对文档及其子文档。

常见问题

• 是否支持多个思源工作空间？ 支持。将插件安装到主要使用的工作空间，再在插件设置中手动添加其他工作空间的 Token。用户个性化要求、工作空间索引和隐私规则分别保存在各自的工作空间中，切换后会自动使用对应内容。

  每次只能启动一个思源工作空间。切换时，先打开目标工作空间并关闭其他工作空间，再关闭并重新启动目标工作空间。思源默认让第一个启动的工作空间使用固定端口，后续工作空间使用随机端口，思源桥无法稳定探测随机端口。因此不需要在每个工作空间中分别注册一套相同的 MCP，否则 AI 会看到重复工具。

• 提示思源未启动怎么办？ 先打开思源桌面端，并确认当前工作空间正确。MCP 注册完成后，即使思源暂时没有启动，AI Agent 仍然能够发现思源桥；真正读取或修改笔记时，工具会明确提示先打开思源。

  如果思源已经启动但仍然报错，可以重启 AI Agent。某些 Agent 在网络代理或 VPN 状态变化后，可能会丢失已经注册的 MCP 连接。

• 配置完成后，AI 仍然看不到工具怎么办？ 确认已经把插件生成的 MCP 配置复制到正确的 AI 客户端，并在配置后重启客户端。不同 AI Agent 使用的 MCP 注册格式略有差异，插件当前生成的是 Claude Code 格式；也可以把配置交给 AI，让它转换成所在平台需要的格式。

• 两台电脑都装了思源怎么同步？ 插件本身可以跟随思源的工作空间同步，但 MCP 配置中的启动脚本必须使用当前电脑的绝对路径。请在每台电脑上分别打开插件设置，复制该电脑重新生成的 MCP 配置。

• 用户体验改进计划是什么？ 用户体验改进计划用来匿名搜集思源桥的调用成功率，以寻找工具设计不够合理的地方。默认关闭。开启后只记录版本号、工具名称、执行耗时、调用是否成功和错误类型，不上传笔记正文、搜索内容或对话记录，不会收集具体的笔记信息或AI聊天记录。匿名统计结果可以在公开看板查看。

  

• 修改后内容消失、产生冲突或导致思源崩溃怎么办？ 常见原因是两台电脑同时打开同一个思源工作空间，并且都开启了自动云同步。建议将同步方式设置为手动同步，或者只在启动和关闭时同步。需要时，也可以让 AI 在完成修改后调用一次思源内置同步。

• 为什么修改或写入前没有生成新的快照？ 自动云同步也会生成快照。在同步进行时，思源可能判断当前数据没有新变化，从而跳过思源桥请求创建的快照。建议将自动同步改为手动同步，或只在启动和关闭时同步。

• AI 写入的 #标签# 变成了普通文字怎么办？ 思源是否把成对 #标签# 解析成标签由编辑器设置决定。请打开思源「设置 → 编辑器 → Markdown 行级语法」，开启「#foo#」（标签语法）。开启后 AI 写入的 #标签# 会成为可点击的真标签并进入标签面板；关闭时，包括思源原生接口在内的所有 Markdown 写入都不会解析标签，落成普通文字。

• 快照会不断膨胀吗？ 思源内置了快照清理机制，通常每天保留两个，并在 180 天后删除。但自动清理需要云同步触发。如果使用纯本地工作空间且没有开启云同步，建议定期进入“设置 → 数据仓库 → 清理”手动清理。

• 思源桥可以怎样管理文档？ 可以创建笔记本和文档，也可以改名、移动、复制、导出或删除文档。改名、复制和导出只针对当前文档；移动和删除会作用于整棵文档子树，也就是当前文档及其所有子文档。当前不提供删除整个笔记本的功能。

• 怎样查看文档的正向引用和反向引用？ 告诉 AI“这篇文档引用了哪些块”，对应 siyuan_operate(action="check_forward_references")，按目标文档展示被引用块；问“哪些块引用了这篇文档”，对应 action="check_backward_references"，按来源文档展示引用块。两者都计入本篇内部引用，子文档递归汇总次数。默认各展示 10 篇可见对端/子文档，可用 limit="none" 查看全部，展示限制不影响关系总数。隐藏对端只计关系次数，不暴露路径、ID、内容或文档数。

• 删除或重写会不会破坏块引用？ 会让现有文档 ID 或块 ID 消失的操作，都会先检查这些内容是否仍被其他笔记引用。存在引用时，思源桥会默认拒绝操作，并展示允许查看的引用来源。只有用户了解影响并明确同意后，AI 才能继续破坏这些引用。

交流与反馈

遇到问题或有新的想法，可以直接告诉 AI“提交反馈”，也可以前往 GitHub 提交 issue。

更多介绍和分享请见社区讨论贴：链滴

如果思源桥对你有帮助，欢迎打赏支持！

---

Apache-2.0 License