理解 Pi Packages 与结构

什么是 Pi Package

从模块 01 一路配模型、配 provider，你会发现：配置越攒越多，单靠一个人手写太乱。生产级的解法，是把这些能力打包、能分发、能复用。

Pi Package 就是这样一种打包单元：它把扩展（extensions）、技能（skills）、提示词模板（prompt templates）、主题（themes） 捆在一起，让你通过 npm 或 git 分享给别人。

一句话：Pi Package 是把 pi 的能力「分发化」的载体。

---

一个 Pi Package 能装什么

Pi Package 里能装四类资源：

资源	作用	打包在哪
扩展 Extensions	执行任意代码，注册工具/命令/provider	extensions/
技能 Skills	给模型的指令包	skills/
提示词模板 Prompts	/命令 形式的模板	prompts/
主题 Themes	TUI 配色	themes/

每种资源在包里的放置方式，下一节讲 pi 键和目录约定时会展开。

---

先看一个最重要的事实：它运行在你系统上

这是本模块第一课最该建立的安全直觉：

Pi Packages 拥有完整的系统访问权限。扩展执行任意代码，技能可以指示模型做任何事，包括运行可执行文件。

所以官方文档的第一句话就是：安装第三方包前，先看它的源码。 这不是吓唬你，这是生产级工具的第一条纪律。

---

包可以从哪里来

Pi 接受三种包源：

源	写法示例	说明
npm	npm:@scope/pkg@1.2.3	从 npm registry 拉取
git	git:github.com/user/repo@v1	从 git 仓库拉取，可固定 ref
本地路径	/absolute/path 或 ./relative	指向磁盘上的文件或目录

pi install npm:@foo/bar@1.0.0
pi install git:github.com/user/repo@v1
pi install ./relative/path/to/package

本地路径若是文件，当作单个扩展加载；若是目录，就按包规则加载其中的资源。这一点 md-tools 开发期特别好用——本地直接 pi install ./md-tools 就能测。

---

包装到哪里、写进哪个设置

安装分「用户级」和「项目级」：

• 默认写进用户设置 ~/.pi/agent/settings.json
• 加 -l 写进项目设置 .pi/settings.json，可随项目共享

项目设置能被团队共享，而且项目被信任后，pi 启动时会自动装上缺失的包——这跟模块 05 的「项目信任」会碰头。

pi install -l git:github.com/user/repo  # 装进项目设置

---

落地练习：用本地路径装一个包试试

动手体验「装一个 Pi Package」的完整动作：

1. 建一个测试目录 my-pkg/，往里放一个 extensions/ 文件夹，写一个极简扩展 .ts 文件
2. 在另一个目录里运行 pi install ./my-pkg（本地路径即可，先不用发布）
3. 跑 pi list，确认包被列出来，扩展已加载

怎么判断做对了？——pi list 能看到 my-pkg，且包里的扩展确实被加载（比如它注册的工具可用）。

卡住了怎么办？ 扩展没生效？先确认目录结构对不对（资源得放在约定目录里，下一节详讲）。装错位置？看下 pi list 是来自用户设置还是项目设置。

---

常见坑：把 Pi Package 当成普通 npm 库

最大的认知偏差，是把 Pi Package 当成「普通 npm 依赖包」——以为它只是代码，不会影响你系统。

其实它运行在你机器上：扩展是 TypeScript 模块，会以当前用户权限执行。所以它对等的是「你要信任的程序」，不是「编译进项目的一行 import」。看源码再装不是客套话，而是这个生态的安全底线。这一条会贯穿到模块 05 的安全章节。

---

小结

1. Pi Package 打包扩展、技能、提示词模板、主题
2. 通过 npm / git / 本地路径分发
3. 包拥有完整系统访问权限，装第三方包前先看源码
4. 装默认进用户设置，-l 进项目设置
5. 本地路径最方便开发期测试

下一节，写 package.json 的 pi 键和目录约定。