PI-Desktop 插件权限网关Host 如何管控第三方代码的 5 层能力边界【免费下载链接】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 编码工具装插件最怕的是第三方代码失控。PI-Desktop 的插件权限网关Permission Gateway就是为了解决这个问题每个插件都跑在独立进程里所有 API 调用必须穿过允许清单 权限断言 审计日志三道关卡。本文带你从新手视角看懂这套机制的 5 层设计以及它如何把第三方代码关进笼子。为什么 AI 编码 Agent 需要插件权限网关PI-Desktop 是一个本地优先Local-first的 AI 编码 Agent 桌面应用架构为 Electron Rust host-core pi Agent Harness。它的插件系统允许用户安装命令、面板、Agent 工具、技能等扩展但插件代码本质上是不可信的。按设计文档的说法如果直接加载插件脚本插件代码可能拖垮或侵入宿主。因此 PI-Desktop 从第一天就确立了原则默认拒绝权限显式授权才可用default-deny permissions with explicit grants。这条决策记录在 docs/adr/0005-user-installable-plugin-system.md 中。能力边界的第一层进程隔离插件主进程运行在一个独立进程中通过 RPC 访问 Host API而不是直接拿到宿主对象。每个插件都有独立的宿主进程入口在 apps/desktop/electron/main/plugin-host-process.mjs以utilityProcess.fork方式启动插件进程只获得一个最小化环境宿主的环境变量和 Provider API Key 根本到不了插件代码插件崩溃被完全包含挂起调用以PLUGIN_CRASHED拒绝贡献点自动注销面板关闭界面弹通知——宿主应用不会跟着死这条隔离决策的完整论证见 docs/adr/0008-plugin-runtime-isolation-target.md。能力边界的第二层Host API 允许清单插件进程里甚至没有require宿主模块的能力。所有pi.*调用都以 RPC 形式到达 apps/desktop/electron/main/plugin-runtime.ts先查HOST_API_ALLOWLIST不在清单里的接口根本不存在。这份允许清单覆盖了界面ui.openPanel、文件fs.readText、fs.glob、网络net.fetch、剪贴板clipboard.readText、浏览器控制browser.cdp等几十个接口——插件能做什么只取决于这张白名单。能力边界的第三层默认拒绝的权限断言白名单只是能不能调权限断言决定你这个插件调了没有。每次调用前都会执行assertPermissionthis.assertPermission(loaded, agent.tool.register);插件的权限来自其manifest.json中的声明。以示例插件 examples/plugins/hello/manifest.json 为例插件声明了什么贡献commands、agentTools、面板Host 就据此推导能力徽章。如果插件没有持有对应权限assertPermission会抛出PERMISSION_DENIED错误并写入审计日志errorCode: PERMISSION_DENIED——见 plugin-runtime.ts。能力徽章和权限列表在 Rust 侧由 crates/host-core/src/plugins/permissions.rs 从 manifest 推导最终在插件页面以徽章形式展示给用户。能力边界的第四层风险分级与审批卡片当 Agent 要执行高危操作时Host 的权限管理器会弹出审批卡片。核心逻辑在 crates/host-core/src/permissions.rs工具类型风险等级处理方式Read/Glob/Grep低自动放行Write/Edit/Bash高需用户确认plugin_*工具按 manifest 声明未声明者默认中风险注意一个细节插件工具的风险声明如果缺失或格式错误不会被视为低风险而是落到中风险——审批路径保留这防止了声明缺失反而更安全的反直觉漏洞。审批卡片有120 秒超时PERMISSION_TIMEOUT_MS超时自动拒绝用户的三种决定允许一次 / 会话内允许 / 拒绝通过PermissionDecision枚举传递。此外审批请求的参数预览会被截断到 2000 字符避免一个大文件内容卡住界面。能力边界的第五层文件系统作用域与可展示性权限不只是运行时检查还要让用户看得见manifest 的fs字段声明每个模式能触碰哪些文件Host 强制执行注册表也会保存它插件页面据此展示你授予了什么crates/host-core/src/plugins/model.rs插件更新时Host 会计算权限差异permission_diff并展示新增权限用户更新前就知道这个版本多要了什么插件来源记录信任层级verified/community/unknown并随安装保留即使目录源消失也能看到用户当时接受了什么新手如何验证这套机制不用读源码也能快速体验权限网关安装 examples/plugins/hello 示例插件观察插件页面展示的能力徽章commands、tools、panel 等在会话中让 Agent 触发文件写入观察审批卡片的出现与 120 秒倒计时把插件的manifest.json里某个权限删掉再调用对应 API——会得到PERMISSION_DENIED审计日志里有一条失败记录小结权限网关的设计哲学PI-Desktop 的插件权限网关可以概括为一句话进程隔离兜底白名单划界断言守门风险分级全程可审计。它不追求绝对沙箱文档坦承插件进程内的原生require仍是已知边界而是用多层低成本检查把第三方代码的能力边界压缩到 manifest 声明的范围内——这正是本地 AI 编码 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），仅供参考
PI-Desktop 插件权限网关Host 如何管控第三方代码的 5 层能力边界【免费下载链接】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 编码工具装插件最怕的是第三方代码失控。PI-Desktop 的插件权限网关Permission Gateway就是为了解决这个问题每个插件都跑在独立进程里所有 API 调用必须穿过允许清单 权限断言 审计日志三道关卡。本文带你从新手视角看懂这套机制的 5 层设计以及它如何把第三方代码关进笼子。为什么 AI 编码 Agent 需要插件权限网关PI-Desktop 是一个本地优先Local-first的 AI 编码 Agent 桌面应用架构为 Electron Rust host-core pi Agent Harness。它的插件系统允许用户安装命令、面板、Agent 工具、技能等扩展但插件代码本质上是不可信的。按设计文档的说法如果直接加载插件脚本插件代码可能拖垮或侵入宿主。因此 PI-Desktop 从第一天就确立了原则默认拒绝权限显式授权才可用default-deny permissions with explicit grants。这条决策记录在 docs/adr/0005-user-installable-plugin-system.md 中。能力边界的第一层进程隔离插件主进程运行在一个独立进程中通过 RPC 访问 Host API而不是直接拿到宿主对象。每个插件都有独立的宿主进程入口在 apps/desktop/electron/main/plugin-host-process.mjs以utilityProcess.fork方式启动插件进程只获得一个最小化环境宿主的环境变量和 Provider API Key 根本到不了插件代码插件崩溃被完全包含挂起调用以PLUGIN_CRASHED拒绝贡献点自动注销面板关闭界面弹通知——宿主应用不会跟着死这条隔离决策的完整论证见 docs/adr/0008-plugin-runtime-isolation-target.md。能力边界的第二层Host API 允许清单插件进程里甚至没有require宿主模块的能力。所有pi.*调用都以 RPC 形式到达 apps/desktop/electron/main/plugin-runtime.ts先查HOST_API_ALLOWLIST不在清单里的接口根本不存在。这份允许清单覆盖了界面ui.openPanel、文件fs.readText、fs.glob、网络net.fetch、剪贴板clipboard.readText、浏览器控制browser.cdp等几十个接口——插件能做什么只取决于这张白名单。能力边界的第三层默认拒绝的权限断言白名单只是能不能调权限断言决定你这个插件调了没有。每次调用前都会执行assertPermissionthis.assertPermission(loaded, agent.tool.register);插件的权限来自其manifest.json中的声明。以示例插件 examples/plugins/hello/manifest.json 为例插件声明了什么贡献commands、agentTools、面板Host 就据此推导能力徽章。如果插件没有持有对应权限assertPermission会抛出PERMISSION_DENIED错误并写入审计日志errorCode: PERMISSION_DENIED——见 plugin-runtime.ts。能力徽章和权限列表在 Rust 侧由 crates/host-core/src/plugins/permissions.rs 从 manifest 推导最终在插件页面以徽章形式展示给用户。能力边界的第四层风险分级与审批卡片当 Agent 要执行高危操作时Host 的权限管理器会弹出审批卡片。核心逻辑在 crates/host-core/src/permissions.rs工具类型风险等级处理方式Read/Glob/Grep低自动放行Write/Edit/Bash高需用户确认plugin_*工具按 manifest 声明未声明者默认中风险注意一个细节插件工具的风险声明如果缺失或格式错误不会被视为低风险而是落到中风险——审批路径保留这防止了声明缺失反而更安全的反直觉漏洞。审批卡片有120 秒超时PERMISSION_TIMEOUT_MS超时自动拒绝用户的三种决定允许一次 / 会话内允许 / 拒绝通过PermissionDecision枚举传递。此外审批请求的参数预览会被截断到 2000 字符避免一个大文件内容卡住界面。能力边界的第五层文件系统作用域与可展示性权限不只是运行时检查还要让用户看得见manifest 的fs字段声明每个模式能触碰哪些文件Host 强制执行注册表也会保存它插件页面据此展示你授予了什么crates/host-core/src/plugins/model.rs插件更新时Host 会计算权限差异permission_diff并展示新增权限用户更新前就知道这个版本多要了什么插件来源记录信任层级verified/community/unknown并随安装保留即使目录源消失也能看到用户当时接受了什么新手如何验证这套机制不用读源码也能快速体验权限网关安装 examples/plugins/hello 示例插件观察插件页面展示的能力徽章commands、tools、panel 等在会话中让 Agent 触发文件写入观察审批卡片的出现与 120 秒倒计时把插件的manifest.json里某个权限删掉再调用对应 API——会得到PERMISSION_DENIED审计日志里有一条失败记录小结权限网关的设计哲学PI-Desktop 的插件权限网关可以概括为一句话进程隔离兜底白名单划界断言守门风险分级全程可审计。它不追求绝对沙箱文档坦承插件进程内的原生require仍是已知边界而是用多层低成本检查把第三方代码的能力边界压缩到 manifest 声明的范围内——这正是本地 AI 编码 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），仅供参考
