Pi Agent 包管理
Pi Packages(包) 允许你将 Extensions、Skills、提示词模板和主题打包，通过 npm 或 git 进行分发和安装。
包管理命令
| 命令 | 功能 |
|---|---|
| pi install <source> | 安装包，-l 参数安装为项目级 |
| pi remove <source> | 移除包 |
| pi uninstall <source> | 同 remove |
| pi list | 列出已安装的包 |
| pi update --all | 更新 Pi Agent 和所有包 |
| pi update --extensions | 仅更新包 |
| pi update <source> | 更新指定包 |
使用示例：
# 安装 npm 包 $ pi install npm:@foo/bar@1.0.0 # 安装 git 包 $ pi install git:github.com/user/repo@v1 # 安装本地包 $ pi install ./relative/path/to/package # 安装为项目级（写入 .pi/settings.json） $ pi install -l npm:@foo/bar # 临时试用包（不安装到配置中） $ pi -e npm:@foo/bar $ pi -e git:github.com/user/repo
包来源
npm 包
npm 是推荐的包分发方式：
pi install npm:@scope/pkg@1.2.3 pi install npm:pkg
带版本号的 npm 包会被锁定，pi update 不会自动升级它们。
包安装位置：全局在 ~/.pi/agent/npm/，项目级在 .pi/npm/。
Git 包
支持 HTTPS 和 SSH 协议：
# HTTPS pi install https://github.com/user/repo@v1 # SSH（git@host:path 需要 git: 前缀） pi install git:git@github.com:user/repo@v1 # SSH 协议 pi install ssh://git@github.com/user/repo@v1
Git 包的 ref 会被锁定，pi update 不会自动移动到新 ref。
克隆位置：全局在 ~/.pi/agent/git/，项目级在 .pi/git/。
本地路径
指向本地文件系统路径，不会复制文件：
pi install /absolute/path/to/package pi install ./relative/path/to/package
创建 Pi 包
在 package.json 中添加 pi 字段：
实例
{
"name": "my-package",
"keywords": ["pi-package"],
"pi": {
"extensions": ["./extensions"],
"skills": ["./skills"],
"prompts": ["./prompts"],
"themes": ["./themes"],
"video": "https://example.com/demo.mp4",
"image": "https://example.com/screenshot.png"
}
}
"name": "my-package",
"keywords": ["pi-package"],
"pi": {
"extensions": ["./extensions"],
"skills": ["./skills"],
"prompts": ["./prompts"],
"themes": ["./themes"],
"video": "https://example.com/demo.mp4",
"image": "https://example.com/screenshot.png"
}
}
如果没有 pi 字段，Pi Agent 会自动从约定的目录中发现资源：
- extensions/ - 加载 .ts 和 .js 文件
- skills/ - 递归查找 SKILL.md 文件夹
- prompts/ - 加载 .md 文件
- themes/ - 加载 .json 文件
添加 pi-package 关键词可以让你的包出现在 Pi Agent 包画廊 中。video 和 image 字段用于在画廊中展示预览。
包过滤
安装包时可以精确控制加载哪些资源：
实例
{
"packages": [
"npm:simple-pkg",
{
"source": "npm:my-package",
"extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
"skills": ["skills/brave-search"],
"prompts": [],
"themes": ["+themes/legacy.json"]
}
]
}
"packages": [
"npm:simple-pkg",
{
"source": "npm:my-package",
"extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
"skills": ["skills/brave-search"],
"prompts": [],
"themes": ["+themes/legacy.json"]
}
]
}
过滤规则：
- 省略某个键 = 加载该类型的所有资源
- 设为 [] = 不加载该类型的任何资源
- !pattern = 排除匹配的资源
- +path = 强制包含指定路径
- -path = 强制排除指定路径
依赖管理
Pi Agent 会为每个已安装的 npm/git 包执行 npm install，自动安装依赖。
以下核心包由 Pi Agent 自身提供，应列为 peerDependencies，不要在包中重复打包：
| 包名 | 说明 |
|---|---|
| @earendil-works/pi-ai | AI 工具和类型 |
| @earendil-works/pi-agent-core | 代理核心 |
| @earendil-works/pi-coding-agent | Pi Agent 主包 |
| @earendil-works/pi-tui | TUI 组件 |
| typebox | 参数 Schema 定义 |
pi config 管理资源
使用 pi config 交互式地启用或禁用已安装包的扩展、Skills、模板和主题：
# 编辑全局配置 $ pi config # 编辑项目配置 $ pi config -l
Tab 键在全局和项目模式之间切换。
作用域与去重
同一个包可以同时出现在全局和项目配置中。如果项目条目存在，它优先于全局条目。
包的身份由以下方式确定：
- npm 包：包名
- git 包：仓库 URL（不含 ref）
- 本地路径：解析后的绝对路径