Pi Packages

pi 可以帮助您创建 pi 包。要求它捆绑您的扩展、技能、prompt templates或主题。

Pi 打包捆绑扩展、技能、prompt templates 和主题，以便您可以通过 npm 或 git 共享它们。包可以在 pi 键下的 package.json 中声明资源，或者使用常规目录。

• Install and Manage
• Package Sources
• Creating a Pi Package
• Package Structure
• Dependencies
• Package Filtering
• Enable and Disable Resources
• Scope and Deduplication

安全性： Pi 软件包以完全系统访问权限运行。 Extensions执行任意代码，技能可以指示模型执行任何操作，包括运行可执行文件。在安装第三方软件包之前检查源代码。

pi install npm:@foo/bar@1.0.0
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 本身，请参阅 Quickstart。

默认情况下，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:@scope/pkg@1.2.3
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: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 URL 均受支持。
• SSH URL 自动使用您配置的 SSH 键（尊重 ~/.ssh/config）。
• 对于非交互式运行（例如 CI），您可以设置 GIT_TERMINAL_PROMPT=0 以禁用凭据提示，并设置 GIT_SSH_COMMAND（例如 ssh -o BatchMode=yes -o ConnectTimeout=5）以快速失败。
• 参考文献是固定标签或提交。 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:git@github.com:user/repo

# ssh:// protocol format
pi install ssh://git@github.com/user/repo

# With version ref
pi install git:git@github.com:user/repo@v1.0.0

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

本地路径指向磁盘上的文件或目录，并且无需复制即可添加到设置中。相对路径根据它们出现的设置文件进行解析。如果路径是文件，它将作为单个扩展名加载。如果是目录，pi使用包规则加载资源。

将 pi 清单添加到 package.json 或使用常规目录。包含 pi-package 关键字以提高可发现性。

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

路径是相对于包根的。数组支持 glob 模式和 !exclusions。

package gallery 显示标有 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"
  }
}

• 视频：仅限 MP4。在桌面上，悬停时自动播放。单击将打开全屏播放器。
• 图像：PNG、JPEG、GIF 或 WebP。显示为静态预览。

如果两者均设置，则视频优先。

如果不存在 pi 清单，pi 会自动从这些目录中发现资源：

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

第三方运行时依赖项属于 package.json 中的 dependencies。不注册扩展、技能、prompt templates或主题的依赖项也属于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 启用或禁用已安装软件包和本地目录中的扩展、技能、prompt templates 和主题。 pi config 在全局设置中启动（~/.pi/agent/settings.json）；按 T​​ab 键可在全局模式和项目本地模式之间切换。使用 pi config -l 在项目覆盖 (.pi/settings.json) 中启动，继承的全局资源变暗。

包可以出现在全局和项目设置中。如果相同的包出现在两者中，则项目条目获胜，除非项目条目具有 autoload: false，在这种情况下，它将作为全局条目的增量应用。身份由以下因素决定：

• npm：包名
• git：不带引用的存储库 URL
• local：解析的绝对路径