从零写一个思源笔记插件：6步完成你的第一个Petals

从零写一个思源笔记插件：6步完成你的第一个Petals

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan

思源笔记插件能让你给编辑器加菜单、改数据视图、接上 AI 服务。这篇教程带你走完一整条开发任务线：先把本地开发环境跑起来，再看懂内核加载插件的机制，然后接上核心 API 完成调试，最后把成品打包发到集市。跟着做完，你手里会有一个能跑、能装、能分发的插件。

先想清楚你要做什么

动手前，给任务定一个明确的边界。思源笔记插件能覆盖的范围包括：往界面里塞自定义组件、调用大模型做 AI 能力、扩展数据同步渠道，或者定制导出格式。选其中一类做小，比一上来就想做全家桶更容易跑通。

目标定了，下一步是把代码拉到本地，看看它怎么组织。

把开发环境跑起来

在终端里克隆仓库：

git clone https://gitcode.com/GitHub_Trending/si/siyuan

拿到代码后进入app目录安装前端依赖：

pnpm install

这一条命令把 TypeScript 前端的全部包拉齐。前端源码在src/下，编译入口是 webpack。接着启动开发编译：

pnpm run dev

这行命令跑的是webpack --mode development，会把src/编译进stage/目录并持续监听你的改动，改了文件立刻生效，不用手动重启。如果要在桌面端整体验证，再执行pnpm run start拉起 Electron 本地实例。

环境能转了，接下来回答一个更底层的问题：内核到底怎么认识一个插件。

内核怎么识别并加载一个插件

思源笔记内部把扩展统称为 Petal，插件只是其中一种类型。内核扫描工作区的data/plugins目录，按目录名逐个读取plugin.json，这就是每个插件的门面文件：名字、版本、前端入口都写在里面。插件注册入口 定义了各类型扩展的落盘路径和清单文件名，Petals 加载接口 则负责在前端请求时返回可用列表并处理启用、停用开关。

加载之后，插件在 内核插件运行时 里会经历一套完整状态：ready → loading → running → stopping → stopped，出问题时停在 error。这个状态机是你后面排障的坐标，看到卡在哪一态，基本就能定位是哪一步出的问题。

插件和内核之间靠什么通信

插件写 JavaScript/TypeScript，内核是 Go 程序，两边不共享内存，全靠显式通道。内核给插件开了两条 RPC 通道：HTTP 和 WebSocket，对应 插件 RPC 网关 里的pluginJsonRpcHttp和pluginJsonRpcWebSocket两个入口，插件在前端注册方法、内核按名调用。

反过来，插件要读笔记数据、改设置，也是走同一套 JSON-RPC 请求内核。所有可调用的方法签名汇总在 API 文档 里，按功能域分章，写代码前先查它比自己翻源码快得多。还有一个容易被忽略的点：内核的 MCP 工具模块 允许插件把自己的能力注册成 MCP 工具，也就是说你的插件可以被 AI 智能体当作工具来调用，这是接入 AI 场景的正规姿势。

本地调试怎么验

开发模式下验证分三步。第一步看前端：pnpm run dev的热编译会把报错直接打印在终端，控制台里再确认页面加载的 bundle 是最新的。第二步看日志：内核插件运行时内置了独立的日志流，插件里打的日志和内核日志分开显示，不会混在一起。第三步看状态：按上一节的状态机检查插件是否走到了 running，没走到的话，九成是plugin.json的入口路径写错了或者前端报错没加载成功。

调试的目标是让每次改动的反馈链路足够短——改一行、热编译、刷新、看到结果。链路短了，后面的功能迭代才不会拖成泥潭。

打包与分发

功能稳定后，把插件目录压缩成一个 zip 包，里面包含plugin.json、前端代码和kernel.js（如果用了内核侧逻辑）。分发有两条路：一条是用户上传，把 zip 放进自己工作区的data/plugins解压即用；另一条是提交到思源笔记的 Bazaar 集市，经过打包规范校验后供所有人一键安装，安装逻辑同样走前面提到的 集市安装流程。版本发布后记得同步更新plugin.json里的版本号，这样老用户在设置里能看到更新提示。

到这里，从目标到分发的完整链路就闭环了：仓库在本地、热编译在转、RPC 通道已打通、调试反馈短、成品能进集市。剩下唯一要回答的问题是你自己选的那个功能点——回到开头，挑一个最小的需求，先让plugin.json跑起来。

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan