如何打造第一个 PI-Desktop 插件从骨架到 .piplug 包的完整指南【免费下载链接】PI-DesktopLocal-first AI coding agent desktop: Electron Rust host core pi Agent Harness user-installable plugins项目地址: https://gitcode.com/GitHub_Trending/pid/PI-Desktop本文是一份 PI-Desktop 插件开发教程从空文件夹开始创建插件骨架看懂 manifest、main、面板页三个核心文件的分工跑通热重载调试循环最后用 check 与 pack 命令打包出可直接安装的 .piplug 插件包。第一关把骨架跑起来最省事的入口在应用里。打开Plugins页面点标题栏溢出菜单里的New plugin from template选panel-basic模板再挑一个空文件夹——脚手架会拒绝非空目录防止覆盖你已有的项目。写完之后PI-Desktop 直接把这个文件夹作为开发插件加载无需重启。内置四个模板按需选择模板初始内容权限panel-basic命令 HTML 面板ui.panelagent-tool-basicAgent 可调用的 echo 工具agent.tool.registerskill-pack一份技能文档agent.prompt.injectfull-demo命令、面板、工具、技能、设置上述功能对应的权限集合想批量构建就用仓库 CLI如果你的插件要走脚本化流程可以 clone 仓库后用 plugin-devkit 的pi-plugin命令生成需要 Node.js ≥ 22.19、pnpm ≥ 10git clone https://gitcode.com/GitHub_Trending/pid/PI-Desktop cd PI-Desktop pnpm install pnpm --filter pi-desktop/plugin-devkit... build pnpm pi-plugin init panel-basic ../my-first-plugin \ --id local.my-first-plugin --name My First Plugin生成后在 PI-Desktop 的 Plugins 页面选Load development plugin指到../my-first-plugin即可。ID 命名约定私有插件用local.前缀要发布的插件用反向域名如com.example.workspace-summary。ID 必须保持稳定——设置、数据、授权、更新和包名都以它为键。做到这一步你已经拥有一个被应用加载、能执行行为的插件文件夹调试循环随时可以开始。第二关看穿三个文件的分工PI-Desktop 插件的运行时只有两句话入口代码跑在专用 Node 进程里主机注入全局pi对象pi.commands.register、pi.agent.registerTool都挂在它下面。面板跑在沙箱窗口里——一种只跑界面的隔离窗口里面没有 Node只能通过window.pluginBridge跟插件进程通信。所有跨边界的调用都要过权限网关你在 manifest 里声明的每一项permissions都要由用户在安装时显式授权没声明或没授权的调用一律被拒。manifest.json一张登记表热重载调试开发文件夹被加载后会被自动监视保存后 300ms 防抖即触发热重载流程是 unload → validate → load。即使改出语法错误把插件卸载了监视器也不会停保存修复后的文件就能恢复。注意面板内的临时状态不会被保留。逐项验证改动是否生效命令按Cmd/CtrlK或Cmd/CtrlShiftP打开全局搜索输入标题执行面板从命令或插件列表行打开确认窗口正常显示Agent 工具切到 Agent 模式让智能体调用你贡献的工具技能提出匹配description的任务看它是否被选中。出问题时打开Settings → Info → Logs按插件 ID 搜索即可定位。主机 API 失败会抛出带code的ErrorPERMISSION_DENIED、NOT_FOUND、TIMEOUT等捕获并打印 code 是个好习惯。⚠️ 开发中新增权限不会经热重载生效PI-Desktop 会停下重载要求你重新选择该文件夹让你审阅新增的授权。移除权限则可以即时生效。 想要一份功能齐全的参考实现直接读 examples/plugins/hello/它的 manifest.json 同时贡献了命令、面板、Agent 工具、技能、主题、常驻服务与消息总线main.js 演示了完整的注册流程。做到这一步你手里不只是一个能跑的骨架而是能解释每个文件职责、能自己查日志排错的插件。第三关校验、打包装上自己的产物先跑 check 再 pack在仓库根目录执行pnpm pi-plugin check ../my-first-plugin pnpm pi-plugin pack ../my-first-plugincheck使用与安装时完全相同的规则校验 manifest、引用文件、权限、路径包含性、符号链接、包大小与文件数输出阻断性错误和非阻断性警告。警告别跳过尤其是未使用的高风险权限这一类pack产出dist/local.my-first-plugin-0.1.0.piplug并打印包体的SHA-256值。.piplug 包格式有硬性约束约束要求根目录必须直接包含manifest.json归档格式仅存储store不压缩的 ZIP通用zip的默认压缩方式会被安装器拒绝排除项.git、node_modules、dist拒绝符号链接上限最多 2000 个文件、50 MiB⚠️ 分发包必须是可直接执行的 JS/HTML/CSS 与静态资源。PI-Desktop 加载插件时不会替你npm install也不会编译 TypeScript——用了就请先自行打包编译好。 会话里也可以让智能体代劳PluginCheck各模式可用PluginScaffold与PluginPack是 Agent 模式工具。装上 .piplug 走完最后一程开发验收和用户安装是两条不同路径这一步验证的就是用户拿到的那份产物Plugins 页面 → 溢出菜单 →Install plugin package选择刚生成的.piplug文件审阅权限列表并确认安装重复第二关的逐项验证命令、面板、工具、技能禁用再启用一次确认清理与启动行为卸载确认所有贡献彻底消失。做到这一步你交付的不再是一个文件夹而是一个别人双击就能装上、随时能卸载干净的 .piplug 包。卡住了常见报错速查症状可能原因解决方式manifest.json is missing选错了目录层级选择直接包含manifest.json的那一层目录面板打不开缺少ui.panel路径或权限两处都声明新增授权需重新加载文件夹工具不出现agentTools、registerTool、权限三者不一致三处对齐为同名确认处于 Agent 模式安装包被拒绝用普通 ZIP 工具压缩过必须用pi-plugin pack重新打包保存后PERMISSION_DENIEDmanifest 扩大了权限重新选择开发文件夹审阅新增授权参考资料与下一步完整开发指南docs/plugin-development.md英文docs/zh-CN/plugin-development.md中文插件系统规范docs/spec/07-plugins/Manifest 字段规范docs/spec/07-plugins/02-plugin-manifest-schema.md插件权限矩阵docs/spec/07-plugins/13-plugin-permissions-matrix.md打包规范docs/spec/07-plugins/06-plugin-packaging.md可运行的参考插件examples/plugins/hello/下一步建议给插件加一个 Agent 工具加一份技能体验用户说一句话、智能体调用你的代码的完整闭环。发布前记得把 ID 换成反向域名、按语义化版本递增version并在干净的应用状态下把安装验收再走一遍。【免费下载链接】PI-DesktopLocal-first AI coding agent desktop: Electron Rust host core pi Agent Harness user-installable plugins项目地址: https://gitcode.com/GitHub_Trending/pid/PI-Desktop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考