Pi 包

Pi 可以帮你创建 Pi 包（package）。请它打包你的扩展（extension）、技能（skill）、提示词模板（prompt template）或主题（theme）。

安装与管理

安全警告： Pi 包拥有完整系统访问权限。扩展可以执行任意代码，技能可以指示模型执行任何操作，包括运行可执行文件。安装第三方包前请审查其源码。

pi install npm:@foo/[email protected]
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo  # raw URLs work too
pi install /absolute/path/to/package
pi install ./relative/path/to/package

pi remove npm:@foo/bar
pi list                     # show installed packages from settings
pi update                   # update pi only
pi update --all             # update pi, update packages, and reconcile pinned git refs
pi update --extensions      # update packages and reconcile pinned git refs only
pi update --models          # refresh model catalogs only
pi update --self            # update pi only
pi update --self --force    # reinstall pi even if current
pi update npm:@foo/bar      # update one package
pi update --extension npm:@foo/bar

这些命令管理 Pi 包，pi update 还可以更新 Pi CLI 本身的安装。要卸载 Pi 本身，参见快速开始。

默认情况下，install 和 remove 写入用户设置（~/.pi/agent/settings.json）。使用 -l 可改为写入项目设置（.pi/settings.json）。项目设置可以与团队成员共享，项目受信任后，Pi 会在启动时自动安装任何缺失的包。

若想试用某个包而不安装它，可使用 --extension 或 -e。这会安装到临时目录，仅对当前运行生效：

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

包来源

Pi 在设置和 pi install 中接受三种来源类型。

npm

npm:@scope/[email protected]
npm:pkg

带版本号的说明符会被锁定，包更新（pi update --extensions、pi update --all）时跳过。
用户安装位于 ~/.pi/agent/npm/。
项目安装位于 .pi/npm/。
在 settings.json 中设置 npmCommand，可将 npm 包查找和安装操作固定到特定的包装命令，如 mise 或 asdf。

示例：

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

git

git:github.com/user/repo@v1
git:[email protected]:user/repo@v1
https://github.com/user/repo@v1
ssh://[email protected]/user/repo@v1

不加 git: 前缀时，只接受带协议的 URL（https://、http://、ssh://、git://）。
加 git: 前缀时，接受简写格式，包括 github.com/user/repo 和 [email protected]:user/repo。
HTTPS 和 SSH URL 均受支持。
SSH URL 会自动使用你配置的 SSH 密钥（遵循 ~/.ssh/config）。
对于非交互式运行（例如 CI），可设置 GIT_TERMINAL_PROMPT=0 禁用凭据提示，并设置 GIT_SSH_COMMAND（例如 ssh -o BatchMode=yes -o ConnectTimeout=5）以快速失败。
引用（ref）是固定的标签或提交。pi update --extensions 和 pi update --all 不会将它们移到更新的引用，但会把已有的克隆对齐到配置的引用。
使用 pi install git:host/user/repo@new-ref 可更新设置，并将现有包移动到新的固定引用。
克隆到 ~/.pi/agent/git/<host>/<path>（全局）或 .pi/git/<host>/<path>（项目）。
当对齐操作改变检出内容时，Pi 会重置并清理克隆，然后如果存在 package.json 则运行 npm install。

SSH 示例：

# git@host:path shorthand (requires git: prefix)
pi install git:[email protected]:user/repo

# ssh:// protocol format
pi install ssh://[email protected]/user/repo

# With version ref
pi install git:[email protected]:user/[email protected]

本地路径

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

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

创建 Pi 包

在 package.json 中添加 pi 清单，或使用约定目录。为便于发现，请包含 pi-package 关键字。

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

路径相对于包根目录。数组支持 glob 模式和 !排除项。

画廊元数据

包画廊会展示标记为 pi-package 的包。添加 video 或 image 字段可显示预览：

{
  "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 优先。

包结构

约定目录

如果不存在 pi 清单，Pi 会从以下目录自动发现资源：

extensions/ 加载 .ts 和 .js 文件
skills/ 递归查找 SKILL.md 文件夹，并将顶层 .md 文件作为技能加载
prompts/ 加载 .md 文件
themes/ 加载 .json 文件

依赖

第三方运行时依赖应放在 package.json 的 dependencies 中。不注册扩展、技能、提示词模板或主题的依赖也应放在 dependencies 中。Pi 从 npm 或 git 安装包时会运行 npm install，因此这些依赖会自动安装。

Pi 为扩展和技能捆绑了核心包。如果导入其中任何包，请将它们列为 peerDependencies，版本范围用 "*"，且不要捆绑它们：@earendil-works/pi-ai、@earendil-works/pi-agent-core、@earendil-works/pi-coding-agent、@earendil-works/pi-tui、typebox。

其他 Pi 包必须捆绑进你的 tarball。将它们加入 dependencies 和 bundledDependencies，然后通过 node_modules/ 路径引用其资源。Pi 以独立的模块根加载包，因此分开安装不会冲突或共享模块。

示例：

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

包过滤

在设置中使用对象形式来过滤包的加载内容：

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

+path 和 -path 是相对于包根目录的精确路径。

省略某个键即加载该类型的全部内容。
使用 [] 表示不加载该类型的任何内容。
!pattern 排除匹配项。
+path 强制包含某个精确路径。
-path 强制排除某个精确路径。
过滤条件叠加在清单之上，只会收窄已经允许加载的内容。

启用和禁用资源

使用 pi config 启用或禁用已安装包和本地目录中的扩展、技能、提示词模板和主题。pi config 从全局设置（~/.pi/agent/settings.json）开始；按 Tab 可在全局与项目本地模式之间切换。使用 pi config -l 可从项目覆盖（.pi/settings.json）开始，继承的全局资源会置灰显示。

作用域与去重

包可以同时出现在全局和项目设置中。如果同一个包在两处都出现，项目条目优先，除非项目条目标记为 autoload: false，此时它作为全局条目的增量覆盖应用。标识由以下内容决定：

npm：包名
git：不带引用的仓库 URL
本地：解析后的绝对路径