Pi Packages：把 Agent 能力打包复用

如果你已经开始用 Pi Agent，迟早会遇到一个问题：

同一套 skills、prompt templates、themes、extensions，能不能别在每个项目里重复配？

Pi Packages 解决的就是这件事。它把 Pi 的扩展能力打成一个可安装、可更新、可分享的包，让个人工具链和团队 Agent 工作流都更容易复用。

先说结论（建议收藏）

Pi Packages 可以打包 extensions、skills、prompt templates、themes。
包可以来自 npm、Git URL、GitHub URL，也可以来自本地路径。
pi install 默认写入用户配置；加 -l 可以写入项目配置，方便团队共享。
第三方 Pi Packages 权限很高，安装前必须审源码，尤其是 extensions 和 skills。

为什么 Pi 需要 Packages

Pi 的核心很小，但可扩展点很多。

你可以写扩展，补工具能力；可以写 skill，把一套固定任务流程交给 Agent；可以写 prompt template，复用常见提示词；也可以写 theme，调整终端体验。

问题是，这些能力一旦变多，就不适合散落在各个项目里。

Pi Packages 的价值就是把这些资源统一封装起来：

flowchart LR
    A[Extension] --> P[Pi Package]
    B[Skill] --> P
    C[Prompt Template] --> P
    D[Theme] --> P
    P --> E[npm / git / local path]
    E --> F[pi install]

关键点 1：安装来源很灵活

官方文档列出的安装方式覆盖了几种常见场景。

如果包已经发布到 npm，可以这样装：

1
pi install npm:@foo/bar@1.0.0

如果是 Git 仓库，可以指定 GitHub 仓库和版本：

1
pi install git:github.com/user/repo@v1

也可以直接安装 GitHub URL：

1
pi install https://github.com/user/repo

开发调试阶段，本地路径也支持：

1
2
pi install ./relative/path/to/package
pi install /absolute/path/to/package

这意味着 Pi Packages 不只适合公开分发，也适合团队内部沉淀一套私有 Agent 能力包。

关键点 2：用户级和项目级要分清

pi install 和 pi remove 默认写入用户配置：

1
~/.pi/agent/settings.json

这适合个人长期使用的包，比如自己的常用 skills、主题、私人工具扩展。

如果希望一个项目里的所有人都自动获得同一组包，可以加 -l 写入项目配置：

1
pi install -l npm:@foo/bar

项目配置会写到：

1
.pi/settings.json

官方文档说明，项目 settings 可以和团队共享，Pi 启动时会自动安装缺失的包。

这个设计很适合团队把“项目专属 Agent 能力”版本化：例如代码审查 skill、发布检查 prompt、内部 CLI extension。

关键点 3：也可以临时试用

有些包只是想试一下，不一定要写进配置。

这时可以用 --extension 或 -e：

1
2
pi -e npm:@foo/bar
pi -e git:github.com/user/repo

它会把包安装到临时目录，只在当前运行中生效。

这个姿势适合做两件事：

试用第三方包，看是否真的适合自己的工作流；
调试还没准备正式安装的内部包。

关键点 4：更新和删除也走 Pi 命令

Pi Packages 的管理命令和 Pi CLI 本身不是一回事。

常用命令可以记这几个：

1
2
3
4
5
pi list
pi remove npm:@foo/bar
pi update
pi update --extensions
pi update npm:@foo/bar

其中 pi update 会更新 Pi、更新 packages，并处理 pinned git refs；pi update --extensions 只更新 packages 并处理 pinned git refs；pi update --self 才是只更新 Pi 自身。

如果你只是想管理 Pi Packages，不要把它和卸载 Pi CLI 混在一起。

关键点 5：安全边界一定要看

这是最容易被忽略的一点。

文档明确说明：Pi packages 拥有完整系统访问权限。Extensions 可以执行任意代码，skills 也可以指示模型执行任意动作，包括运行可执行文件。

所以第三方包不能当普通配置文件看。

更稳妥的使用方式是：

安装前看源码，尤其是 extension 入口和 skill 内容；
能固定版本就固定版本，不要随意追最新；
团队共享前先做 review；
先用 -e 临时试跑，再决定是否写入配置；
对来源不明的包保持默认不信任。

Pi Packages 提升的是复用效率，但它同时扩大了 Agent 的执行面。

可用步骤清单

先确认包来源：npm、Git 仓库，还是本地。
先用 pi -e <package> 临时试用，观察是否符合预期。
检查源码和包内声明的 resources。
个人长期使用：执行 pi install <package>。
团队项目共享：执行 pi install -l <package>，并把 .pi/settings.json 纳入代码审查。

定期用 pi list 查看已安装包，用 pi update --extensions 更新 packages。

最后总结

Pi Packages 是 Pi Agent 从“个人终端工具”走向“可复用 Agent 工程体系”的关键能力。

它把 extensions、skills、prompt templates、themes 放进同一个分发模型里，让能力可以安装、更新、共享和版本化。

但也因为它能带来真实执行能力，安装第三方包前必须把安全审查当成默认动作。

Mate（发布信息）

建议标题（20字以内）

Pi Packages 入门
Agent 能力打包复用
Pi 扩展包怎么用

正文描述（用于发布）

Pi Packages 可以把 Pi Agent 的 extensions、skills、prompt templates 和 themes 打包复用。适合想沉淀个人工具链、团队 Agent 工作流的人，但安装第三方包前一定要审源码。

参考资料

Pi Packages 官方文档

话题标签

#AI编程 #Agent #PiAgent #开发工具 #工程效率 #命令行