从零写一个思源笔记插件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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考