pi 可以帮你创建 pi packages。你可以让它把你的扩展、Skill、提示词模板或主题打包起来。

Pi Packages（包）

Pi packages 会把扩展、Skill、提示词模板和主题组合起来，方便你通过 npm 或 git 共享。Package 可以在 package.json 的 pi 键下声明资源，也可以使用约定目录。

目录

• 安装与管理
• Package 来源
• 创建 Pi Package
• Package 结构
• 依赖
• Package 过滤
• 启用与禁用资源
• 作用域与去重

安装与管理

安全提示： Pi packages 以完整的系统权限运行。扩展可以执行任意代码，Skill 也可以指示模型执行任意操作，包括运行可执行文件。在安装第三方 packages 之前，请先检查源码。

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 --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 packages，pi update 还可以更新 pi CLI 的安装。要卸载 pi 本身，请参见 快速开始。

默认情况下，install 和 remove 会写入用户设置（~/.pi/agent/settings.json）。如果想改写到项目设置（.pi/settings.json），请使用 -l。项目设置可以和团队共享；在项目被信任后，pi 会在启动时自动安装缺失的 packages。

如果你想在不安装的情况下试用某个 package，可以使用 --extension 或 -e。这会把它安装到临时目录，只对当前运行有效：

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

Package 来源

Pi 在设置和 pi install 中支持三种来源类型。

npm

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

• 带版本的 spec 会被固定，并在 package 更新（pi update --extensions、pi update --all）时跳过。
• 用户安装会放在 ~/.pi/agent/npm/ 下。
• 项目安装会放在 .pi/npm/ 下。
• 在 settings.json 中设置 npmCommand，可以把 npm package 的查找和安装操作固定到某个特定的封装命令，例如 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 key，并遵循 ~/.ssh/config。
• 对于非交互式运行（例如 CI），你可以设置 GIT_TERMINAL_PROMPT=0 来禁用凭据提示，再设置 GIT_SSH_COMMAND（例如 ssh -o BatchMode=yes -o ConnectTimeout=5）让它尽快失败。
• ref 可以是已固定的 tag 或 commit。pi update --extensions 和 pi update --all 不会把它们移动到更新的 ref，但会把已有 clone 对齐到配置的 ref。
• 使用 pi install git:host/user/repo@new-ref 可以更新设置，并把已有 package 切换到新的固定 ref。
• 全局安装会克隆到 ~/.pi/agent/git/<host>/<path>，项目安装会克隆到 .pi/git/<host>/<path>。
• 当对齐导致检出结果发生变化时，pi 会重置并清理 clone，然后在存在 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]

Local Paths

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

本地路径指向磁盘上的文件或目录，添加到设置时不会复制。相对路径会以它们所在的设置文件为基准解析。如果路径是文件，就会作为单个 extension 加载。如果路径是目录，pi 会按 package 规则加载资源。

创建 Pi Package

向 package.json 添加 pi 清单，或者使用约定目录。请包含 pi-package 关键字，方便被发现。

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

路径都是相对于 package root 的。数组支持 glob 模式和 !exclusions。

Gallery Metadata

package gallery 会展示带有 pi-package 标签的 packages。添加 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。

Package 结构

约定目录

如果没有 pi 清单，pi 会从这些目录自动发现资源：

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

依赖

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

Pi 已经为扩展和 Skill 打包了核心 Package。如果你 import 了其中任何一个，请把它们列入 peerDependencies，并使用 "*" 范围，而且不要把它们打包进去：@earendil-works/pi-ai、@earendil-works/pi-agent-core、@earendil-works/pi-coding-agent、@earendil-works/pi-tui、typebox。

其他 pi packages 必须打包进你的 tarball。把它们加入 dependencies 和 bundledDependencies，然后通过 node_modules/ 路径引用它们的资源。Pi 会为 packages 使用彼此独立的模块根目录，所以不同安装不会冲突，也不会共享模块。

示例：

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

---

Package 过滤

使用 settings 里的对象形式，筛选 Package 会加载哪些内容：

{
  "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 都是相对于 Package 根目录的精确路径。

• 省略某个 key，就会加载该类型的全部内容。
• 使用 [] 表示不加载该类型的任何内容。
• !pattern 用来排除匹配项。
• +path 用来强制包含某个精确路径。
• -path 用来强制排除某个精确路径。
• 过滤规则是在 manifest 之上叠加的。它们只会进一步收窄已经允许的内容。

启用和禁用资源

使用 pi config 可以启用或禁用已安装 Package 和本地目录中的 extension、Skill、prompt template 和 theme。它同时适用于全局（~/.pi/agent）和项目（.pi/）作用域。

作用域与去重

Package 可以同时出现在全局和项目设置中。如果同一个 Package 两边都存在，项目条目会生效。身份的判定方式如下：

• npm: package name
• git: 不包含 ref 的 repository URL
• local: 解析后的绝对路径