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一款 Local-first AI coding agent 桌面应用中开发或安装插件那么manifest.json是你必须读懂的第一份文件。本文带你完整解析 PI-Desktop 插件清单Manifest的全部字段以及它的分发格式.piplug包——从必填项、UI 声明、能力贡献contributes、权限permissions到文件/网络沙箱策略一篇讲透。读完本文你将能够看懂任意 PI-Desktop 插件的manifest.json知道每个字段对应什么能力、需要什么权限理解.piplug包的内部结构与安装校验规则核心参考文档02-plugin-manifest-schema.md字段权威定义与 06-plugin-packaging.md打包规范。一分钟认识 .piplug 包格式.piplug是 PI-Desktop 的产品级插件分发扩展名本质是一个zip 压缩包根目录必须包含manifest.json见 ADR 0007。典型结构如下demo.hello-0.1.0.piplug └─ (zip) ├─ manifest.json ← 插件清单根目录必须存在 ├─ main.js ← 插件运行时入口 ├─ renderer/ ← 面板 HTML/CSS ├─ skills/ ← Agent 技能文档 ├─ themes/ ← 主题 CSS └─ checksums.json ← 可选的包内校验清单选择 zip 的原因很务实跨平台、实现简单、方便做校验和/签名、开发者可以解压后本地审查。包内硬性约束 约束规则根目录必须包含manifest.json路径禁止绝对路径软链接、禁止../路径穿越压缩方式必须是store不压缩模式普通 zip 工具生成的包会被安装器拒绝大小解压后默认上限 50 MB可配置文件数默认上限 2000 个可配置 开发阶段无需打包——直接选择包含manifest.json的目录加载为开发插件即可。打包请用官方工具pi-plugin pack它会输出id-version.piplug并打印 SHA-256。必填字段身份四件套 入口manifest 的 Schema 版本当前为1。以下五个字段缺一不可host-core 校验源码见 manifest.rs字段要求说明schemaVersion必须是1未来升到 2 需要迁移器过高的主版本会被拒绝id必填反向域名风格如com.example.todo发布插件建议用稳定 id设置、数据、授权、更新全部以它为键name必填展示名称作者语言version必填语义化版本semver如0.1.0main必填运行时入口相对路径指向可直接加载的 js/html/css宿主不会替你做npm install或编译 TypeScript可选字段从描述到国际化基本信息区description一句话描述author字符串或{ name, url, email }对象homepage/repository项目地址icon图标相对路径engines.piDesktop宿主版本范围如0.1.0enabledByDefault内置插件首次注册默认开关省略即默认启用i18n让插件说用户语言 name/description是展示文案可通过顶层i18n块按语言声明。en和zh-CN是契约语言所有中文 Shell 语言读zh-CN其余语言读en缺失时逐字段回退到作者原文。{ name: 小清新待办, i18n: { en: { name: Todo List, description: A calm todo list }, zh-CN: { name: 小清新待办, description: 轻盈的待办清单, safetyNotes: 只写自己的数据 } } }解析发生在宿主侧按settings.language或 OS 语言注册表里始终保存作者原文切语言不重写数据库。ui 块面板与浮动小组件{ ui: { panel: renderer/index.html, width: 480, height: 360, resizable: true, title: { en: My Panel, zh-CN: 我的面板 } } }panel指向沙箱、上下文隔离的 Electron 窗口无 Node 集成只暴露window.pluginBridge宿主预留 46px 透明拖拽带不要在内容区再补 46px 顶部内边距想要悬浮球式透明无边框窗口声明ui: { shape: widget }最小支持 120×120alwaysOnTop可置顶contributes 块插件能贡献什么 这是 manifest 的核心——声明插件向宿主注入的能力。每种能力都有对应的权限要求缺失即校验失败skills除外能力用途所需权限commands全局搜索中的命令—agentToolsAgent 可调用的工具含risk等级与 JSON Schemaagent.tool.registerskills按需注入的提示词文档字符串路径或元数据覆盖对象agent.prompt.inject缺失则跳过views停靠在工作面板的界面本地化 titleicon为宿主图标 tokenui.viewthemes设计令牌覆盖 CSSbase为 light/dark最多 8 个单文件 256 KiBui.themesettings设置项string/number/boolean/select/json/shortcut—mcpServersstdio 或 http 的 MCP 服务器mcp.server.local/mcp.server.remoteservices宿主监管的常驻服务background.servicebus插件间消息总线publish 具体主题 / subscribe 通配模式bus.publish/bus.subscribeproviders声明模型供应商行最多 8 个每个 1..64 个模型provider.registerglobalShortcuts全局快捷键最多 8 条command 必须已声明keyboard.globalShortcut完整字段类型定义见 02-plugin-manifest-schema.md。两个值得注意的细节MCP 的env/headers支持{ setting: key }语法读取插件自身设置宿主环境变量永不透传contributes.providers的oauth暂不支持声明即校验失败完整示例仓库自带一个全家桶示例插件覆盖命令、面板、工具、技能、主题、服务、总线、设置examples/plugins/hello/manifest.json。更精简的 Agent 工具插件可看 examples/plugins/roundtable/manifest.json。permissions 与沙箱策略permissions32 项封闭枚举permissions是能否碰的总闸。未知权限值 校验失败。按风险分三档低ui.panel、ui.view、ui.theme、notify中clipboard.read/write、fs.read、background.service、bus.publish/subscribe、keyboard.globalShortcut等高fs.write、fs.delete、agent.tool.register、agent.prompt.inject、net.fetch、mcp.server.local/remote、net.websocket、desktop.control等完整矩阵见 13-plugin-permissions-matrix.md。fs能碰哪些文件 权限回答能否碰文件fs回答碰哪些{ permissions: [fs.read, fs.write, fs.delete], fs: { read: { root: workspace, scope: [**/*] }, write: { root: workspace, scope: [docs/**, *.md] }, delete: { own: true, scope: [dist/**] } } }不写fs块 零常驻可达每次访问都弹运行时确认——不声明就不给写/删除禁止整树模式**、**/*等只有读可以声明全树root: userSelected走用户选目录授权句柄仅存内存随进程销毁.env*、SSH 凭据、*.pem、.git/**无论怎么声明都拒绝net出站白名单 { net: { domains: [api.example.com, *.githubusercontent.com] } }这份白名单约束所有宿主管理的出站路径——pi.net.fetch、面板自身的fetch/img/script加载、远程 HTTP MCP、WebSocket。条目只能是裸主机名无协议/端口/路径裸*被拒省略或写坏 完全无出站。校验规则速查 ✅安装前宿主执行严格校验常见雷区路径字段一律相对路径禁止绝对路径和..main/ui.panel/ skills /views[].entry指向的文件必须存在贡献 idthemes、mcpServers、services、views须匹配[a-zA-Z][a-zA-Z0-9_-]{0,63}且列表内唯一能力缺对应权限直接失败如agentTools必须配agent.tool.registerfs.mode必须配同名权限net.domains必须是裸主机名activationEvents支持onStartup、onCommand:*当前 MVP 实现校验器与打包器共用同一套规则——用pi-plugin check就能在本地预演安装结果。开发 → 打包 → 安装全流程 选择目录/包 → 校验包安全性 → 解压到临时区 → 校验 manifest 文件 → 权限审查 UI → 移入 installed/id → 写注册表 → 可选自动启用同 id 新版本 升级旧版自动备份到cache/backup/id/version失败则清理临时区不留半成品目录发布前清单稳定反向域名 id → 升 semver → 声明engines.piDesktop→pi-plugin check清零错误 →pi-plugin pack→ 干净状态安装测试 → 记录 SHA-256更多开发细节热重载、日志、排错表见 plugin-development.md安全模型背景见 04-plugin-security.md。总结概念一句话manifest.json插件的身份证 能力声明书根目录必须有.piplugstore 模式 zip50MB / 2000 文件上限禁止穿越与软链contributes插件给宿主注入什么几乎每项都绑权限permissionsfsnet三道沙箱能不能碰 → 碰哪些文件 → 出站到哪校验能力缺权限即失败不声明沙箱范围即零权限读懂这五个字段簇你就掌握了 PI-Desktop 插件生态的语言。动手试试用应用内New plugin from template生成panel-basic模板对照本文逐字段检查生成的 manifest.json——这比看十篇文档都快。【免费下载链接】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），仅供参考