PI-Desktop 插件开发指南:3 个文件搭出你的第一个 .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-DesktopPI-Desktop 插件开发不需要先啃完全部规范。PI-Desktop 是一款本地优先(Local-first)的 AI 编码智能体桌面应用,插件是它的能力扩展单元:一个插件可以贡献命令、面板、Agent 工具、技能乃至主题。从一个空文件夹起步,写清 3 个文件,经过热重载调试,再跑一遍校验与打包,就能产出一个可安装的.piplug插件包,并按真实用户的流程验收它。PI-Desktop 插件架构:两种运行环境与权限网关整个插件体系只需要记住两句话:入口代码跑在专用 Node 进程里,界面跑在沙箱化的 Electron 窗口里,两者之间的每一次通信都要过主机的权限网关。第一句话的含义:插件入口代码运行在独立的 Node 进程中,主机会注入一个全局pi对象(比如pi.commands.register、pi.agent.registerTool),这是插件进程访问宿主能力的唯一正规渠道。第二句话的含义:面板和视图是隔离的 Electron 页面,没有 Node 集成,拿不到全局pi,只能通过window.pluginBridge与插件进程或主机对话。一个插件可以同时贡献多种能力,按需取用:能力适合场景核心构件命令全局搜索中可执行的显式操作contributes.commandspi.commands.register面板独立的小型 HTML 窗口ui.panel路径 ui.panel权限悬浮挂件透明无边框的圆形球体/小组件ui: { shape: widget }工作面板视图停靠在主窗口右侧的界面contributes.viewsui.view权限Agent 工具让 AI 智能体可调用的函数contributes.agentToolspi.agent.registerTool技能智能体按需加载的指令文档contributes.skillsagent.prompt.inject权限主题设计令牌覆盖contributes.themesui.theme权限MCP 服务器 / 常驻服务 / 消息总线外部工具发现、后台任务、插件间通信对应的contributes声明权限网关是这套架构的安全核心:manifest 里permissions声明的每一项,都要用户在安装时显式授权;凡是没声明或没授权的调用,一律以PERMISSION_DENIED失败。所以声明权限时遵循最小够用原则,多要一项就是多打扰用户一次。最快创建方式:应用内模板,备选仓库 CLI不用手写任何文件:应用内置了模板脚手架,四步就能得到一个可运行的插件文件夹。打开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,适合参与仓库开发或批量构建。需要 Node.js ≥ 22.19 与 pnpm ≥ 10,在仓库根目录执行:git 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选中这个目录即可。 命名约定:私有插件用local.前缀,发布插件用反向域名(如com.example.workspace-summary)。ID 必须保持稳定——设置、数据、授权、更新和包名都以它为键,改 ID 等于换了一个插件。最小插件的三个文件:身份、行为、界面panel-basic生成的是一个最小可运行插件:manifest.jsonmain.jsrenderer/index.html(外加一份 README)。按身份 → 行为 → 界面的视角理解它们,比按文件名记忆更快。身份:manifest.json 回答我是谁、我要什么权限。最小必填字段是schemaVersion、id、name、version、main,其余声明全部围绕贡献与权限展开:{ schemaVersion: 1, id: local.my-first-plugin, name: My First Plugin, version: 0.1.0, main: main.js, ui: { panel: renderer/index.html, width: 480, height: 360 }, contributes: { commands: [{ id: my-first-plugin.open, title: My First Plugin: Open Panel }] }, permissions: [ui.panel], activationEvents: [onCommand:my-first-plugin.open, onStartup] }所有文件路径都相对于插件根目录,且必须留在目录内部。行为:main.js 回答被加载时做什么。入口在onLoad里向主机注册贡献,在onUnload里清理。约 10 行代码就能让插件跑起来:async function onLoad() { await pi.commands.register({ id: my-first-plugin.open, title: My First Plugin: Open Panel, run: async () { await pi.ui.openPanel({ title: My First Plugin }); await pi.ui.showToast(Hello from My First Plugin); }, }); } module.exports { onLoad };主机注入全局pi,调用全部受权限网关把关,所以扩大入口代码的行为通常意味着同步扩大permissions。模块求值加onLoad有 15 秒预算,onUnload有 5 秒且尽力而为——定时器、订阅等要在卸载时尽快释放。界面:renderer/index.html 回答用户看到什么。面板页拿不到全局pi,只有window.pluginBridge,所有跨窗口调用都走它:await window.pluginBridge.invoke(ui.showToast, { message: Hello from the panel, });窗口由主机托管:顶部 46px 是透明拖拽带,右上角叠着主机的三键胶囊,其余可见界面归插件自己画。想看一个五脏俱全的参考实现,仓库自带示例插件 examples/plugins/hello/:它的 manifest 同时贡献了命令、面板、Agent 工具、技能、主题、常驻服务与消息总线,main.js 里能看到完整的注册与卸载流程。免重启的开发循环:热重载机制与逐项验证开发文件夹被加载后会持续被监视(包括跨应用重启),保存即生效,无需手动刷新。具体机制:目录内任何改动在 300ms 防抖后触发一次重载,一次保存爆发只算一次;node_modules、.git、dist、target和编辑器临时文件被忽略。重载走unload → validate → load流程,面板内存不保留。出现语法或 manifest 错误时,损坏版本会被卸载,但监视器保持活跃——保存修复后的文件即可恢复,不用重新加载文件夹。同时最多监视 16 个开发插件。改完代码,按贡献类型逐项验证是否真的生效:命令:按Cmd/CtrlK(或Cmd/CtrlShiftP)打开全局搜索,输入命令标题执行;面板:从命令或插件列表行打开,确认窗口正常显示;Agent 工具:切到 Agent 模式,让智能体实际调用你贡献的工具;技能:提出一个匹配技能description的任务,观察它是否被选中;主题:在 Settings 里选中该插件贡献的主题;常驻服务:在插件行查看服务状态与重启次数。遇到加载、权限、工具、网络类失败,打开Settings → Info → Logs,按插件 ID 搜索即可定位;用户可见的加载与热重载失败还会以 toast 和插件行错误呈现。主机 API 失败会抛出带code的Error(如PERMISSION_DENIED、NOT_FOUND、TIMEOUT),捕获并打印 code 是好习惯,但别把密钥写进日志。打包命令速览:check 校验与 pack 出包开发满意后,在仓库根目录跑两条命令,先校验、再打包:pnpm pi-plugin check ../my-first-plugin pnpm pi-plugin pack ../my-first-plugincheck用的是与安装时完全相同的规则,覆盖 manifest、引用文件、权限、路径包含性、符号链接、包大小与文件数。输出分两级:阻断性error(不修就不能打包)与非阻断性warning——后者不会拦住安装,但声明了却没调用的高风险权限、缺失的agent.prompt.inject等提示值得逐条复查。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——用到了 TypeScript 或第三方库,先在本地打包编译进插件目录,再 check 和 pack。另一个省事的入口:Agent 自身内置了PluginCheck(各模式可用)、PluginScaffold与PluginPack(Agent 模式,仅限当前工作区)工具,可以直接在会话里让智能体帮你跑校验和打包。以用户身份验收:安装、开关、卸载三步最终要验证的是用户实际收到的就是这份产物,流程固定为:安装 → 禁用再启用 → 卸载。打开Plugins页面 → 标题栏溢出菜单 →Install plugin package;选择刚生成的.piplug文件;审阅权限列表并确认安装;重复上一节的逐项验证(命令、面板、工具、技能);禁用再启用一次,确认清理与启动行为正常;卸载,确认所有贡献(命令、面板、视图)全部消失。验收通过后,发布前把 ID 换成反向域名、按语义化版本递增version,并在全新的应用状态下再完整跑一遍安装流程。排错速查表:症状、原因、对策症状可能原因对策manifest.json is missing选错了目录层级指向直接包含manifest.json的那一层目录main entry missingmain指向了未编译的源码先编译/打包,或修正相对路径面板打不开缺少ui.panel路径或ui.panel权限声明面板路径与权限;新授权需重新加载文件夹Agent 工具不出现agentTools、registerTool、agent.tool.register三者不一致三处对齐为同名;确认处于 Agent 模式技能不生效缺agent.prompt.inject或元信息太笼统补权限,把name/description写具体保存后报PERMISSION_DENIEDmanifest 扩大了权限权限扩大不走热重载,重新加载开发文件夹并审阅新授权热重载停了语法/manifest 错误,损坏版本已被卸载监视器仍活跃,保存修复后的文件即恢复安装包被拒绝用普通 ZIP 工具压缩用pi-plugin pack重新打包pluginBridge不可用HTML 在普通浏览器里打开在 PI-Desktop 的面板窗口内测试参考资料完整开发指南:插件开发指南(英文) 中文Manifest 字段规范权限矩阵打包规范开发体验规范插件系统规范索引可运行的参考实现:examples/plugins/hello/下一步建议:给插件加一个 Agent 工具再加一份技能,体验用户说一句话 → 智能体调用你的代码的闭环。【免费下载链接】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），仅供参考