Pi Package 是一种分发单元，可以把扩展（Extensions）、技能（Skills）、提示模板和主题组合在一起。它解决的是“怎样把一组 Pi 资源安装、共享和更新”，而不是定义新的 Agent Loop。一个 Package 可以只包含其中一种资源，也可以同时包含多种资源。
Package 包含什么
Package 通常通过清单声明要提供的资源。安装后，Pi 会按配置发现其中的扩展、技能、提示模板或主题。扩展能够注册工具和事件处理；技能提供按需加载的说明与资源；提示模板提供可复用的输入；主题改变终端界面外观。选择 Package 前，应先判断自己需要的是执行能力、工作说明、输入模板还是界面资源。
官方 Packages 文档说明了包结构、资源字段和加载规则；各类资源本身的职责可结合扩展文档理解。
安装来源
Pi 可以从 npm、Git 仓库或本地路径安装 Package。来源决定了版本标识和更新方式，也影响可复现性。
pi install npm:@example/pi-tools@1.0.0
pi install git:github.com/example/pi-tools
pi install ./local-pi-package
固定 npm 版本或 Git 引用有助于团队复现环境。直接跟随可变分支或未固定版本更适合试用，但以后得到的内容可能发生变化。
全局安装与项目安装
默认安装作用于当前用户的全局 Pi 配置。使用 -l 可把 Package 记录到项目的 .pi/settings.json：
pi install npm:@example/pi-tools@1.0.0
pi install -l npm:@example/pi-tools@1.0.0
全局安装适合个人在多个项目复用；项目安装适合团队共享依赖。项目配置进入版本库后，其他成员打开项目时可以得到一致的资源声明。Pi 只会在项目被信任后加载项目资源和处理缺少的 Package，因此“配置文件中存在”不等于“已经加载并可执行”。
临时试用
不希望立即写入安装配置时，可以用 -e 临时加载一个 Package：
pi -e npm:@example/pi-tools
这种方式适合评估扩展、复现问题或比较版本。进程结束后，不应把这次临时加载当作项目的固定依赖。试用结果满意后，再选择全局安装或项目安装。
查看、移除与更新
常用管理入口包括：
pi list
pi config
pi remove npm:@example/pi-tools
pi update --extensions
pi update --models
pi update --all
pi list 用于查看已经声明的 Package；pi config 提供交互式资源管理；pi remove 移除安装记录。更新命令需要区分 Pi 自身、扩展资源和模型目录：pi update 更新 Pi，--extensions 更新扩展相关 Package，--models 更新模型信息，--all 执行完整更新。实际支持的选项应以当前版本的 pi --help 和官方文档为准。
对于要求稳定复现的项目，应固定 Package 版本，并在升级后重新运行关键任务或测试，而不是把“更新完成”直接视为“行为兼容”。
筛选 Package 中的资源
一个 Package 可能提供多个扩展、技能、模板或主题。设置中的 Package 项可以使用对象形式，只启用所需资源。这样能够减少不必要的工具和提示进入运行环境，也有助于定位冲突。
排查时应分别确认：
- Package 是否出现在安装配置中；
- Package 内容是否已下载或可访问；
- 目标资源是否被筛选规则启用；
- 当前进程是否重新加载了配置；
- 工具或技能是否真正被本次任务调用。
“安装成功”“资源已加载”和“能力已被调用”是三个不同状态。
安全与维护边界
Package 中的扩展代码与 Pi 进程具有相同的系统权限。安装来源、版本和代码都应视为需要审核的依赖；项目受信任并不等于 Package 本身可信。正式使用前应确认来源，阅读清单和扩展代码，并在最小权限环境中验证。
删除 Package 也不一定撤销它此前对文件或外部系统造成的变化。安全边界和项目资源加载规则见官方安全文档。
一个可复现的团队流程
团队可以把固定版本的 Package 写入项目配置，提交 .pi/settings.json，并在项目说明中记录其用途。新成员进入项目后先确认项目来源，再允许安装和加载；随后用 pi list 检查声明，用一个最小任务确认目标工具或技能出现，最后运行项目测试验证结果。这样可以把依赖声明、资源加载和业务验收分开记录。