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-DesktopPI-Desktop 插件开发不需要先通读架构文档。本文面向没给 PI-Desktop 写过插件的读者——它是本地优先Local-first的 AI 编码智能体桌面应用插件是它的扩展方式。这里走一遍最小路径空文件夹起步改三个文件热重载里逐项验证最后打成一个别人能安装的.piplug包。读完你可以独立完成四件事创建插件、读懂并修改 manifest、判断热重载有没有生效、产出带 SHA-256 校验值的安装包。每一步都可复现文中路径均相对仓库根目录。插件到底是什么一个包能同时贡献哪些能力 插件是 PI-Desktop 的能力扩展单元一个包可以同时挂多种能力不必为命令和面板各写一个插件。能力典型用途声明位置命令全局搜索中可直接执行的操作contributes.commandsHTML 面板独立的小窗口ui.panel权限悬浮挂件透明无边框的圆形球体/小组件ui: { shape: widget }工作面板视图停靠主窗口右侧的界面contributes.viewsAgent 工具让 AI 可调用的函数contributes.agentTools技能智能体按需加载的指令文档contributes.skills主题设计令牌覆盖contributes.themesMCP 服务器 / 常驻服务 / 消息总线外部工具发现、后台任务、插件间通信对应contributes声明架构上记两句话就够。第一句插件入口代码跑在一个专用 Node 进程里主机会注入全局pi对象pi.commands.register、pi.agent.registerTool这类调用都在那里发生。第二句面板和视图跑在沙箱化的 Electron 窗口里那里没有 Node唯一与插件进程对话的通道是window.pluginBridge。两条边界上的每一次跨调用都要过主机的权限网关——manifest 里声明的每一条permissions用户安装时都要显式点一次同意。权限的完整对照见权限矩阵。PI-Desktop 插件入门四个模板与两个入口该敲哪条命令最快的路径在应用里完成打开Plugins页 → 标题栏溢出菜单 →New plugin from template选模板再选一个空文件夹——脚手架会拒绝非空目录防止覆盖已有代码。写完文件后该文件夹立刻作为开发插件加载不用重启。参与仓库开发或需要批量产出时走命令行Node.js ≥ 22.19、pnpm ≥ 10克隆仓库仓库地址 https://gitcode.com/GitHub_Trending/pid/PI-Desktop并pnpm install构建 packages/plugin-devkit/ 工具链后执行pnpm pi-plugin init panel-basic ../my-first-plugin --id local.my-first-plugin --name My First Plugin。四个内置模板怎么选一张表定模板生成什么需要权限适合谁panel-basic命令 HTML 面板ui.panel第一个插件推荐从这里开始agent-tool-basicAgent 可调用的 echo 工具agent.tool.register想让智能体调你写的代码skill-pack一份技能文档agent.prompt.inject纯提示词类扩展full-demo命令、面板、工具、技能、设置相应权限集合通读参考实现ID 有一条约定私有插件用local.前缀对外发布用反向域名如com.example.workspace-summary。ID 是设置、数据、授权、更新共用的键定了就别再动。骨架里到底改哪几个文件manifest 必填项与权限声明panel-basic脚手架落盘四个文件manifest.json、main.js、README.md、renderer/index.html真正要懂的是前三个。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: Open Panel }] }, permissions: [ui.panel], activationEvents: [onCommand:my-first-plugin.open, onStartup] }字段全集见manifest 规范。main.js——插件进程入口。导出onLoad/onUnload能力注册都放在onLoad里一个命令注册十几行就能跑async function onLoad() { await pi.commands.register({ id: my-first-plugin.open, title: Open Panel, run: async () { await pi.ui.openPanel({ title: My First Plugin }); await pi.ui.showToast(Hello from My First Plugin); }, }); } module.exports { onLoad };renderer/index.html——面板页面。注意这个窗口里没有全局pi只有window.pluginBridge例如pluginBridge.invoke(ui.showToast, ...)就能弹提示。想看一个把命令、面板、工具、技能、主题、常驻服务、消息总线全声明一遍的参考读仓库里的 examples/plugins/hello/。改动保存后如何确认生效验证节奏与命令在哪输入保存文件后等约 300ms防抖主机自动执行unload → validate → load应用不用重启。写了语法错误时只卸载损坏版本监视器保持活跃——改对再保存即恢复。逐项确认贡献命令按Cmd/CtrlK或Cmd/CtrlShiftP打开全局搜索输入命令标题执行面板从命令或插件列表行打开确认窗口正常渲染Agent 工具切到 Agent 模式让智能体调用你贡献的工具技能提一个命中技能description的任务观察它是否被选中。失败时去Settings → Info → Logs按插件 ID 搜日志。主机 API 失败会抛带code的ErrorPERMISSION_DENIED、NOT_FOUND、TIMEOUT等捕获后把 code 打出来是定位问题的最快路径。怎么把文件夹打成用户能装的 .piplugcheck、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。⚠️ 包内必须放可直接执行的 JS/HTML/CSS 与静态资源PI-Desktop 加载插件时不会替你npm install也不会编译 TypeScript发布前自己打包好。格式约束详见打包规范项目规则根目录必须直接包含manifest.json归档格式仅存储store、不压缩的 ZIP通用压缩 zip 会被安装器拒绝排除项.git、node_modules、dist符号链接一律拒绝上限≤ 2000 个文件、≤ 50 MiB验收按用户视角走一条动线1)Plugins页溢出菜单 →Install plugin package2) 选刚生成的.piplug3) 审阅权限列表并确认安装4) 复验命令、面板、工具、技能5)禁用再启用一次确认清理与启动行为6) 卸载确认贡献全部消失。顺带一提Agent 内置了PluginCheck各模式可用、PluginScaffold与PluginPackAgent 模式工具会话里直接让它替你跑校验和打包也可以。出问题先查这六处症状与处理manifest.json is missing→ 选错了目录层级改选直接包含manifest.json的那一层。面板打不开 →ui.panel路径或ui.panel权限缺失补上新授权后要重新加载开发文件夹。工具不出现 →agentTools、registerTool、权限声明三处名字没对齐同时确认当前处于 Agent 模式。安装包被拒 → 用了普通 zip 工具压缩回到pi-plugin pack重新打包。保存后立刻PERMISSION_DENIED→ manifest 扩大了权限重新加载开发文件夹并审阅新增授权。保存后毫无反应 → 可能正处在 300ms 防抖或损坏版本卸载中看日志确认监视器是否还活着。后续读什么、做什么完整指南docs/plugin-development.md中文docs/zh-CN/plugin-development.md字段与规则manifest 规范、权限矩阵、打包规范动手参考examples/plugins/hello/、packages/plugin-devkit/ 下一步给你的插件加一个 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），仅供参考