我做了一个工具，把思源笔记接入了 AI agent。（前不久还在思源社区发过另一个帖子，但那时候还没有做成思源插件，很多功能设计也不完善，于是重写重发，欢迎讨论）
起因很具体。我做的投资研究资料，大多存在思源笔记里面，做一个结构化的知识库。里面放了几十家公司的各种层面资料，新闻快讯、公司财报、业务梳理、行业分析等。每次想跟 AI 讨论点什么，得先把相关文档找出来，复制粘贴发过去。贴少了 AI 理解不到位，贴多了太麻烦。每次修改之后，下一轮新会话，又得重来一遍。
先花半个下午，写了一个只读工具，能让 AI 读取思源笔记里的文档。连写入权限都没给，觉得不安全，也比较难做。
但刚开始就发现不行。只能读不能写，AI 很难放开手脚干活，效率大打折扣。
于是我准备借鉴点优秀案例。
设计灵感
现在的 AI 在编程上受过大量的强化训练。它天生擅长读代码、写代码这套操作。我在用 Claude Code 做AI编程时感觉很顺手，于是在想，都是文本，能不能让 AI 像操作代码库一样操作我的思源笔记？
从产品设计的角度，我需要顺着用户的习惯和需求设计产品。而我的用户不仅有人，还有 AI。 既然 AI 在编程上受过训练，那我就让它用编程的方式来操作笔记。
我顺着这个思路，去问 AI 编程工具通常是怎么设计的，最后定了 5 个核心工具：list、find、read、edit、create，基本一比一复刻Claude Code。后面又加了 start（借鉴 CLAUDE.md 的注入机制）、refresh（刷新文档树）、doc_manage（文档移动、改名等）。
这并不简单，因为思源笔记内部是按块来组织的，一段文字、一个表格、都是一个块，底层接口是按块进行设计的，每次操作一个块。而AI最熟悉的，是一行一行的纯文本文档。
于是我花了很多心思，去把思源笔记暴露出来的接口改成AI熟悉的样子。
做的时候我也看了 GitHub 上其他封装思源 API 的 MCP 项目。它们的思路通常是"思源能做什么，MCP 就暴露什么"，倾向于大而全的覆盖。但很多功能我从来不用，开发出来对我没意义。加上精力有限，就只挑了核心功能打磨。
后期还发现一个意想不到的优势：因为是本地 Python 程序，没有依赖思源笔记，所以MCP本身的运行和思源笔记完全解绑，不会因为思源笔记没启动或者连不上而报错，收获了用户的"稳定"好评。
安全的逻辑
在AI编程的时候我就发现，AI偶尔会把代码改废，虽然频率不高，但修复起来很麻烦，最好的办法还是git回滚。但编程有git，思源并没有，于是退而求其次，每次编辑前备份快照，需要了再回滚。这样自己用起来也安心：最坏无非是回滚一下。毕竟人类才是最终的用户。
所以我在第一个版本发布之前，就把这块做出来了。
隐私方面，我做了一个三档权限：读写、只读、隐藏。用户填一个笔记本或文档的 ID，标记隐藏，AI 就完全不知道这个文档的存在——搜不到、读不了、改不了。隐私规则文档本身更是被代码硬编码隔离，AI 连它的存在都不知道。也考虑过做一个工具让 AI 帮忙管理隐私，后来砍掉了，因为依赖 AI 自觉是不可靠的。
差点放弃
第一版发出去之后用户不多。下载 Python 程序、解压、注册 MCP 对大多数人来说还是太复杂，GitHub总共只有20来次下载。不过也收到的反馈整体不错，有人说“非常好用！”，还挺开心的。
然后我看到了另一个项目叫 Sisyphus。感觉人家代码写得比我规范，效果也似乎更好。我甚至一度停掉思源桥，去维护Sisyphus。
但 Sisyphus 的 Edit 工具和我的差不多，也是 old text → new text 精确匹配替换。在文本文档里可以，但在思源笔记里经常匹配不到，我不知道是因为什么原因，看起来完全一样的东西就是匹配不上。另外有用户反馈说思源桥用起来稳定，Sisyphus 经常连不上。我给 Sisyphus 提了一些 PR 想解决，但没搞定。想从底层重构一下，又觉得代码架构太复杂，怕搞崩了。加上我心里还是想有一个自己的产品，于是又回来继续优化思源桥。
Edit 工具的迭代
第一版 Edit 完全照搬编程工具的做法：找到 old text，替换为 new text。但在思源里经常匹配失败。因为思源的文档不是按行组织的，是按块。一段文字、一个标题、一张表格都是一个块。块有属性、有ID，而且没有直接跨块操作的接口。此外，文本匹配要求绝对精确，但很多时候 AI 反复尝试几次也匹配不上，我一直不知道问题出在哪里。
第二版我推倒重来。类比文档的行号，把每个块排序，提供块序号和块ID，AI只需要提供块序号和ID即可，不用进行文本精确匹配。如果需要编辑大段文字，只需要标注起止位置的块。同时传入新内容。
这个改动让我意识到一件事：适配比照搬更重要。思源笔记的本质和 Markdown 不一样，不能完全照搬编程工具的做法。思源的块结构是灵魂，我也应该顺应这个设计。
把复杂封装在内部，把简洁暴露给用户
AI看到的只是几个语义清晰的工具接口。但在它内部，每个工具都有一套复杂的转换流程。
以 Edit 工具为例。表面上 AI 调用的接口很简单：选定旧的内容，输入新的内容。但在内部，它要先检测思源是否启动、校验权限、解析块类型、判断是否允许修改，再创建数据快照、最后调用思源 API 把旧内容删掉，写入新的内容。如果只是修改单块，还要保留块的原样式。
start函数也一样。AI看到的只有：从这里开始，像一个开机按钮。但内部，它会获取用户设定的隐私规则、读取用户编写的使用偏好、检查是否有索引地图（如果没有就告诉AI如何做索引）、最后构造一个启动包给AI。在整个工具的外层，还有检测思源是否启动、是否开启遥测等通用流程。
Privacy 规则更是在所有工具底层静默运行——AI 几乎感知不到它的存在（只有启动包会提示，生效了x条隐私规则），但每个请求返回的结果都已经被过滤过。
这个"表面简单、内部复杂"的设计原则贯穿了整个思源桥。让 AI 用得顺手，让人类用得放心。
边做边有新想法
第二版本来想着周末做一天就能搞定。结果周六周日从早干到晚，周日晚上 10 点才提交。
因为一边做一边不断冒出新想法。
用户说需要"只读"权限，我做成了三档权限体系，还理清了父子文档的权限继承关系。
需要改名、移动、删除文档，我加了 doc_manage 工具。
用的时候有经验想分享，但不知道怎么传递，于是做了 feedback 工具，让 AI 替我总结调用经验并反馈。
想针对高频、常错的地方进行优化，但这需要统计数据，所以加了遥测（用户体验改进计划），匿名收集调用数据，哪个工具用得多、哪个出错多、最常见的错误场景是什么，等上线后看看效果。
此外，为了做遥测，我搭了一个 Cloudflare Worker 后端 + 数据库。Cloudflare 默认域名被污染了，又买了一个新域名，顺带把自己的个人网站也盘活了。
最终提交了思源集市的审核。
关于 Obsidian 的插曲
我在重启开发思源桥之前，其实认真想过一个问题：我真的需要自己开发这个工具吗？
如果我把笔记搬到 Obsidian，它底层是 Markdown 文件，AI 天然就能读能写。不需要做什么 MCP 工具。做一个文件夹同步，把OB的仓库在各个设备之间同步，和思源的同步效果也差不多。
所以我下载了 Obsidian，把一部分笔记搬进去，按照我的需求场景配置。折腾了几天。
但 Obsidian 没有思源笔记那么对我友好。我不知道是我不顺手还是什么，就是很多小的摩擦，让我用得不舒服。
而且有一个感受很奇怪：抛弃思源笔记，把所有数据迁到 Obsidian，有一种抛弃家园的失落感。我说不清为什么，也许是因为OB里有太多英文，也许是因为用了一年，笔记都在里面，已经长成了我的一部分。
所以最后我还是回来了，继续建设思源生态。
现在和未来
思源桥现在是一个思源集市插件 + MCP 服务器的组合。用户可以在思源插件市场一键安装，免去打开GitHub、下载压缩包、解压的繁琐过程，然后把配置信息发给AI，就可以在任何支持 MCP 的 AI 工具里接入思源笔记。
上架并不代表完成，目前还有很多想法没实现：
一个 help 功能。当一个工具报错时，报错信息里附带"调用 help 获取技巧"，里面按场景分类给 AI 详细的操作指引。
一个同步功能。因为思源的自动同步会和 AI 的写入操作冲突，我只能用手动同步。AI修改后我得手动关掉软件触发同步，太麻烦。后面会增加同步按钮，让 AI 写完内容后直接触发云端同步，就像改完代码提交 git 那样。
一个公开的遥测看板。因为工具是完全开源的，遥测数据也是匿名的，所以我也想把这些数据公开，在个人网站上建一个页面，展示各工具的调用量、成功率、错误分布、用户反馈，做成完全透明的东西。
编辑和写入工具可以进一步细化，尽可能在操作时保留原有的块属性、块ID，便于其他文档引用。并且在破坏被引用过的块之前，应该有额外的强调和确认。
提示词也可以更加清晰，在编写跨文档的资料整合时，可以更加积极地使用块ID进行引用，让知识库内部的关联更加丰富清晰。
在程序开发上，我准备出一个更清晰的程序架构图，绘制每个工具、每个模块之间的详细流程和关系，便于后期自己和其他开发者维护，对人来说，看图还是要比看markdown文档舒服很多。不过AI写的HTML在绘制复杂流程和关系图上面经常存在问题，可能得自己手绘。
最后
思源桥首先是给自己做的，所以我可以从自己遇到的真实场景出发，决定做什么、不做什么，有时候不做什么和做什么一样重要。也因为它是给自己做的，所以我会尽可能做一个让自己放心、顺手的东西。
做这个MCP，一方面是为了让自己有个顺手的工具可用，另外也是想体验做产品的全流程，AI编程的乐趣之一，就是能将以前想到做不到的东西做出来。这个过程本身，和做出来的成果同样重要。做思源桥这一路，我发现最有意思的不是技术实现，而是在这个过程里不断修正对“产品该长什么样”的判断。四舍五入也算手艺活。
但思源桥也不只是给自己做的，我相信 AI 知识库一定是未来必不可少的配套设施。思源笔记是一个优秀的知识库工具，肯定会有很多人遇到和我类似的情况：想让 AI 接入自己的知识库，但缺少趁手的工具。如果能因为思源桥让更多人把笔记用起来，那就再好不过了。
现在项目已经提交集市了，预计近期能上线，你也可以先来GitHub看看
https://github.com/alone-tree/siyuan-bridge