Pi 包

Pi 包将扩展、技能、提示模板和主题打包在一起，使您能够通过 npm 或 git 共享它们。包可以在 package.json 的 pi 键下声明资源，或使用约定目录。

目录

• 安装和管理
• 包源
• 创建 Pi 包
• 包结构
• 依赖
• 包过滤
• 启用和禁用资源
• 范围和去重

安装和管理

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

pi install npm:@foo/bar@1.0.0
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo  # raw 网址也可以
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 引用
pi update --extensions      # 仅更新包并协调固定的 git 引用
pi update --models          # 仅刷新模型目录
pi update --self            # 仅更新 pi
pi update --self --force    # 即使已安装也重新安装 pi
pi update npm:@foo/bar      # 更新一个包
pi update --extension npm:@foo/bar

这些命令管理 Pi 包，而不是 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/pkg@1.2.3
npm:pkg

• 带版本号的规格会被固定，包更新（pi update、pi update --extensions）会跳过它们。
• 用户安装的包位于 ~/.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:git@github.com:user/repo@v1
https://github.com/user/repo@v1
ssh://git@github.com/user/repo@v1

• 不带 git: 前缀时，仅接受协议网址（https://、http://、ssh://、git://）。
• 带 git: 前缀时，接受简写格式，包括 github.com/user/repo 和 git@github.com:user/repo。
• 同时支持 HTTPS 和 SSH 网址。
• SSH 网址自动使用您配置的 SSH 密钥（遵循 ~/.ssh/config）。
• 对于非交互式运行（例如 CI），可以设置 GIT_TERMINAL_PROMPT=0 禁用凭据提示，并设置 GIT_SSH_COMMAND（例如 ssh -o BatchMode=yes -o ConnectTimeout=5）快速失败。
• 引用被固定为标签或提交。pi update 和 pi update --extensions 不会将它们移动到更新的引用，但会协调现有的克隆到配置的引用。
• 使用 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 简写（需要 git: 前缀）
pi install git:git@github.com:user/repo

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

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

本地路径

/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 模式和 !exclusions。

画廊元数据

包画廊 显示标记为 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。作为静态预览显示。

如果两者都设置了，视频优先。

包结构

约定目录

如果没有 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
• 本地：解析后的绝对路径