17 Pi 包

17.1 Pi 包概述

Pi 包（Package）是将扩展、Skills、Prompt 模板和主题打包分发的机制。通过 npm 或 git 分享，让团队和社区可以复用你的定制。

一个 Pi 包可以包含：

扩展（TypeScript/JavaScript 文件）
Skills（SKILL.md 目录）
Prompt 模板（.md 文件）
主题（.json 文件）

17.2 安装和管理

17.2.1 基本命令

# 安装包
pi install npm:@foo/bar@1.0.0
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo
pi install /absolute/path/to/package
pi install ./relative/path/to/package

# 移除包
pi remove npm:@foo/bar

# 列出已安装的包
pi list

# 更新
pi update              # 仅更新 pi 本身
pi update --all        # 更新 pi + 包 + 对齐 git refs
pi update --extensions # 更新包 + 对齐 git refs
pi update --models     # 仅刷新模型目录
pi update --self       # 仅更新 pi
pi update --self --force  # 强制重装 pi

# 更新单个包
pi update npm:@foo/bar
pi update --extension npm:@foo/bar

17.2.2 安装位置

默认安装到用户级设置（~/.pi/agent/settings.json）。使用 -l 标志安装到项目级设置（.pi/settings.json）：

pi install -l npm:@foo/bar  # 项目级安装

Tip

项目级安装适合团队共享。团队成员克隆仓库后，Pi 会在项目受信任时自动安装缺失的包。

17.2.3 临时使用

不安装到 settings，仅本次运行使用：

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

Warning

安全提示：Pi 包拥有完整的系统访问权限。扩展执行任意代码，Skills 可以指示模型执行任何操作。安装第三方包前请审查源代码。

17.3 包源类型

Pi 支持三种包来源：

17.3.1 npm

npm:@scope/pkg@1.2.3
npm:pkg

有版本号的 spec 会被固定，包更新操作（pi update --extensions）会跳过
用户安装到 ~/.pi/agent/npm/
项目安装到 .pi/npm/

自定义 npm 命令（如使用 mise 或 asdf）：

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

17.3.2 git

git:github.com/user/repo@v1
git:git@github.com:user/repo@v1
https://github.com/user/repo@v1
ssh://git@github.com/user/repo@v1

不带 git: 前缀时，仅接受协议 URL（https://、http://、ssh://、git://）
带 git: 前缀时，支持简写格式（github.com/user/repo、git@github.com:user/repo）
同时支持 HTTPS 和 SSH
SSH 自动使用你配置的 SSH 密钥（遵循 ~/.ssh/config）

SSH 示例：

# git@host:path 简写（需要 git: 前缀）
pi install git:git@github.com:user/repo

# ssh:// 协议格式
pi install ssh://git@github.com/user/repo

# 带版本 ref
pi install git:git@github.com:user/repo@v1.0.0

Ref 固定规则：

Ref 是固定的 tag 或 commit
pi update --extensions 和 pi update --all 不会移动到更新的 ref
但会对齐已有克隆到配置的 ref
使用 pi install git:host/user/repo@new-ref 更新 settings 并移动到新的固定 ref

克隆位置：~/.pi/agent/git/<host>/<path>（全局）或 .pi/git/<host>/<path>（项目级）。

非交互式环境（CI）：

export GIT_TERMINAL_PROMPT=0
export GIT_SSH_COMMAND="ssh -o BatchMode=yes -o ConnectTimeout=5"

17.3.3 本地路径

/absolute/path/to/package
./relative/path/to/package

本地路径指向磁盘上的文件或目录，添加到 settings 时不复制文件。相对路径相对于其所在的 settings 文件解析。如果路径是文件，作为单个扩展加载；如果是目录，使用包规则加载资源。

17.4 创建 Pi 包

17.4.1 package.json 配置

在 package.json 中添加 pi 字段：

{
  "name": "my-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

路径相对于包根目录
数组支持 glob 模式和 !exclusions
添加 pi-package 关键字可在 Pi 包画廊中被发现

17.4.2 Gallery 元数据

在包画廊中展示包预览：

{
  "name": "my-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "video": "https://example.com/demo.mp4",
    "image": "https://example.com/screenshot.png"
  }
}

字段	说明
`video`	MP4 格式。桌面端鼠标悬停时自动播放，点击打开全屏播放器
`image`	PNG、JPEG、GIF 或 WebP。静态预览图

如果同时设置了两者，video 优先。

17.5 包结构

17.5.1 约定目录

如果没有 pi 清单，Pi 会从以下约定目录自动发现资源：

目录	加载规则
`extensions/`	加载 `.ts` 和 `.js` 文件
`skills/`	递归查找包含 `SKILL.md` 的文件夹，加载顶层 `.md` 作为 Skill
`prompts/`	加载 `.md` 文件
`themes/`	加载 `.json` 文件

17.5.2 目录结构示例

my-package/
├── package.json
├── extensions/
│   ├── index.ts
│   └── helpers.ts
├── skills/
│   ├── search/
│   │   └── SKILL.md
│   └── translate/
│       └── SKILL.md
├── prompts/
│   ├── review.md
│   └── deploy.md
├── themes/
│   └── neon.json
└── README.md

17.6 依赖管理

17.6.1 第三方运行时依赖

放在 dependencies 中。Pi 安装包时会运行 npm install，自动安装依赖。

17.6.2 Pi 核心包

如果导入了 Pi 核心包，将它们放在 peerDependencies 中，范围设为 "*"，不要打包：

{
  "peerDependencies": {
    "@earendil-works/pi-ai": "*",
    "@earendil-works/pi-agent-core": "*",
    "@earendil-works/pi-coding-agent": "*",
    "@earendil-works/pi-tui": "*",
    "typebox": "*"
  }
}

17.6.3 依赖其他 Pi 包

其他 Pi 包必须打包到你的 tarball 中：

{
  "dependencies": {
    "shitty-extensions": "^1.0.1"
  },
  "bundledDependencies": ["shitty-extensions"],
  "pi": {
    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
    "skills": ["skills", "node_modules/shitty-extensions/skills"]
  }
}

Note

Pi 以独立的模块根加载每个包，因此不同的安装不会冲突或共享模块。

17.7 包过滤

使用 settings 中的对象形式过滤包加载的资源：

{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:my-package",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"],
      "themes": ["+themes/legacy.json"]
    }
  ]
}

过滤规则：

语法	说明
`glob 模式`	匹配文件路径（如 `extensions/*.ts`）
`!pattern`	排除匹配的文件
`+path`	强制包含精确路径
`-path`	强制排除精确路径
省略 key	加载该类型的全部
`[]`	加载该类型的零个

过滤在清单之上叠加，只能缩小范围，不能扩大。

17.8 启用和禁用资源

使用 pi config 命令启用或禁用已安装包中的扩展、Skills、Prompt 模板和主题：

pi config           # 全局模式（~/.pi/agent/settings.json）
pi config -l        # 项目覆盖模式（.pi/settings.json）

在 pi config 界面中：

按 Tab 切换全局和项目模式
项目模式下继承的全局资源会暗显
可以覆盖启用/禁用状态

17.9 作用域和去重

包可以同时出现在全局和项目设置中。当同一个包同时出现在两处时：

项目条目优先（除非项目条目有 autoload: false）
autoload: false 的项目条目作为全局条目的增量应用

身份判定规则：

来源	身份键
npm	包名
git	不含 ref 的仓库 URL
本地路径	解析后的绝对路径

Tip

利用去重机制，可以在全局安装一个包的稳定版本，同时在特定项目中覆盖为开发版本，实现灵活的版本管理。