Pi / 06
生态使用：发现、审计与退出策略
为什么这个问题值得关注
Pi 把许多产品能力留给 Extension 和 Package，因此生态不是附属功能，而是实际使用方式的一部分。但“能在市场搜到”“下载量很高”“群里有人推荐”都不能证明一个包安全、兼容或值得长期依赖。
评价生态的关键不是收藏多少链接，而是能否把发现、验证、安装、升级和退出连成一个闭环。
本文的官方事实入口是 Pi 官网、Package 市场 和 官方源码。社区目录只用于发现候选项目，不作为兼容性或安全背书。
把资料入口分成四层
| 层级 | 主要用途 | 可信到什么程度 |
|---|---|---|
| 官方文档 | 安装、配置、Skills、Extensions、Packages、Session、安全 | 当前公开行为说明，仍需与版本对应 |
| 官方源码与测试 | 类型、边界、示例、失败语义 | 最接近实现事实 |
| Package 市场 | 搜索候选包、查看 manifest、版本、依赖和仓库 | 发现入口，不等于审核市场 |
| 中文文档与社区列表 | 快速理解、寻找关键词和历史项目 | 辅助导航，冲突时回到官方事实源 |
这四层不需要扩展成几十个收藏夹。遇到问题时遵循固定顺序：官网定位机制，latest 文档确认用法，源码与测试确认边界，市场和社区目录寻找实现。
awesome 列表已经不能当当前目录
qualisero/awesome-pi-agent 已于 2026-06-03 归档。仓库 README 明确表示内容过时，并被更专门的项目替代。
它仍有两个用途：
- 查找早期生态项目和关键词；
- 观察某类需求曾经有哪些实现方向。
它不适合用来判断：
- 包是否兼容当前
@earendil-works/*命名和 API； - 项目是否仍维护；
- 安装命令是否安全；
- 当前市场里哪个实现更成熟。
旧列表发现的任何项目，都应重新回到仓库、npm 和当前 Pi Package 页面核验。
先从官方示例理解能力边界
在安装社区包前，先阅读 packages/coding-agent/examples/extensions/。官方示例覆盖：
permission-gate.ts：危险 bash 命令确认；protected-paths.ts：阻止写入敏感路径；dirty-repo-guard.ts：工作区脏时阻止 Session 切换；subagent/：通过独立 Pi 进程实现隔离上下文；gondolin/：把内置工具路由到 micro-VM；- 自定义工具、命令、UI、Provider、compaction 与 Session 状态。
这些示例不是开箱即用的企业安全方案，但能回答两个问题：Pi 当前 Extension API 能做什么，以及某个社区包是否只是把官方示例包装了一层。
如果需求只需几十行窄逻辑，自行维护一个小 Extension 可能比引入大型 Package 更容易审计和升级。
Package 市场能提供哪些证据
Pi Package 页面通常可以展示：
- 当前版本、发布时间和许可证；
- Package 类型，例如 extension、skill、prompt、theme；
pimanifest 声明的资源；- npm、源码和问题报告入口；
- 包体积、依赖和下载信息。
这些信息适合第一轮筛选。它们不能证明：
- 源码与 npm tarball 完全一致；
- 依赖没有高风险行为；
- Extension 不访问主目录、网络或环境变量；
- 包升级后仍保持原权限范围；
- 下载量来自真实 Pi 用户。
市场是目录，不是自动信任链。
安装前的十分钟审计
第一步：确认身份与维护状态
检查仓库是否匹配 npm 元数据，最近提交和 release 是否一致，issue 中是否存在兼容性或安全问题。不要只看 star。
npm view pi-mcp-adapter \
name version license repository dist.tarball dependencies --json
第二步：检查实际发布内容
在临时目录下载 tarball，不运行包：
pi_audit_dir=$(mktemp -d)
cd "$pi_audit_dir"
npm pack pi-mcp-adapter --ignore-scripts
tar -tf ./*.tgz | sed -n '1,160p'
重点确认 manifest、入口源码、依赖和 README 是否都包含在发布包内。仓库中存在测试，不代表 npm tarball 发布的是同一份代码。
第三步：搜索高影响行为
解包后检查：
tar -xf ./*.tgz
rg -n 'child_process|exec\(|spawn\(|node:fs|node:net|fetch\(|https?://' package
rg -n 'process\.env|\.ssh|\.aws|\.config|\.pi/agent|keychain|keyring' package
rg -n 'preinstall|install|postinstall|prepare' package/package.json
命中这些字符串不自动表示恶意。它们告诉你权限面在哪里，需要继续读调用路径和默认配置。
第四步：确认失败和退出路径
至少回答：
- 包加载失败时，Pi 是继续运行还是进入半启用状态？
- headless 模式没有 UI 时，审批会放行还是拒绝？
- 禁用或移除后，设置、缓存、凭据和后台进程如何清理？
- 能否固定版本，升级是否有 changelog 和迁移说明？
- 旧版 API 不兼容时，团队是否能快速回退？
分清 Package 内的资源类型
同一个 Package 可以混合多种资源。审计时不要把它当成一个黑盒：
| 资源 | 主要风险 | 核验重点 |
|---|---|---|
| Skill | 诱导模型运行脚本、读取外部资料 | 指令、脚本、相对路径、触发描述 |
| Extension | 同进程任意代码执行 | import、事件 hook、文件、进程、网络、凭据 |
| Prompt Template | 用户触发后进入上下文 | Prompt injection、参数和输出要求 |
| Theme | TUI 渲染变化 | 资源路径和意外代码依赖 |
| MCP config | 拉起子进程或连接远端服务 | 命令、endpoint、认证、工具权限 |
只想使用包内 Skill 时，可以通过 Package filtering 禁用 Extension。最小化启用面比“全部安装后再提醒模型小心”更可靠。
用户级与项目级安装的取舍
# 用户级：影响所有项目
pi install npm:@scope/[email protected]
# 项目级：写入 .pi/settings.json，随仓库共享
pi install npm:@scope/[email protected] -l
# 临时试用：仅当前运行
pi -e npm:@scope/[email protected]
用户级方便，但会扩大影响范围，并让不同项目共享同一 Extension 组合。项目级更容易版本化和复现，却可能在项目被信任后触发缺失包安装。
稳妥流程通常是：先在隔离环境用 -e 试用，确认资源和权限面，再选择项目级固定版本；真正适用于所有仓库的窄工具，才考虑用户级安装。
Skill 的跨 Harness 复用
Pi 可以从共享 .agents/skills/ 发现 Skill，也可以在 settings 中加入其他 Harness 的 Skill 目录：
{
"skills": [
"~/.claude/skills",
"~/.codex/skills"
]
}
可移植的是 SKILL.md 的结构、相对资源和工作流知识，不是完整运行环境。跨宿主时要重新验证：
- 工具名称和参数是否存在；
- project trust 和目录发现顺序是否相同；
- Skill 激活后在 Context 中保留多久；
allowed-tools等字段如何解释；- 附带脚本依赖的运行时是否可用；
- 同名 Skill 冲突时哪个版本获胜。
“能被两个 Harness 发现”只是一项兼容证据，不能推出任务行为一致。
什么时候该 Fork
Package、复制小段代码和 Fork 是三种不同维护承诺：
| 方式 | 适合情况 | 你承担什么 |
|---|---|---|
| 直接依赖 Package | 上游维护活跃、权限面可接受 | 版本固定、升级测试、退出预案 |
| 复制窄 Extension | 逻辑很小、团队只需其中一部分 | 本地代码审查和 API 迁移 |
| Fork 上游 | 长期依赖且必须修改权限、行为或发布节奏 | 合并安全更新、发布、文档和完整回归 |
Fork 不是“一劳永逸地拥有代码”。它把上游维护责任转移给团队。如果没有负责人、升级窗口和差异清单，Fork 往往比固定旧版本更难治理。
建立升级回归而不是追最新
对长期依赖的 Package，维护一组最小行为测试：
- Package 能加载，资源数量和名称符合预期；
- 高风险工具在交互与 headless 模式下都遵守策略；
- Session 恢复后扩展状态正确；
/reload不会重复注册 handler；- 失败的依赖或 Server 不会阻断无关功能；
- 卸载后没有残留进程、配置或凭据引用。
先在临时 Pi agent dir 和测试仓库升级。只有这些证据通过，才更新团队使用的版本。
一份采用记录应该写什么
Package: npm:@scope/[email protected]
Source commit: <reviewed commit>
Purpose: 解决哪个具体问题
Enabled resources: 哪些 Extension / Skill / Prompt
Permissions: 文件、进程、网络、凭据范围
Validation: 运行了哪些成功与失败测试
Owner: 谁负责升级和安全问题
Rollback: 如何固定旧版、禁用和清理状态
Review date: 下次复核时间
这份记录比“推荐插件列表”更有长期价值，因为它把团队的信任判断和退出条件留下来了。
小结
- 官网、latest 文档和官方源码足以覆盖大多数 Pi 机制问题，不需要堆积大量教程入口。
- Package 市场用于发现和初筛，不代表第三方包已经通过官方安全审核。
awesome-pi-agent已归档，只能当历史目录使用。- 采用 Package 前要检查发布内容、权限面、失败行为、版本固定和退出路径。
- Skill 格式可以跨 Harness 复用，但工具、权限、加载顺序和生命周期仍需逐宿主验证。