Example

把扩展、技能和提示词作为一个 Pi 包交付

走一遍安装、过滤和移除的循环,并把由宿主提供的包放在 peerDependencies 里,这样宿主不会警告。

一个 Pi 包是你写下的一切的分发单元:一个扩展连同它的技能、提示词和主题,作为一个目录或 npm 包到来,而不是一个在别人机器上就坏掉的 .pi 文件夹 zip。本章没有独立的代码文件,所以这个页面是一趟带占位名字的命令走查,依据是那个交付二进制测试所断言的内容。

安装、列出、移除

pi install npm:@example/pi-tools@1.0.0              # pinned npm version
pi install git:github.com/example/pi-tools@v1       # cloned, reconciled to the ref
pi install ./local-package                          # loaded from its path; nothing copied
pi list                                             # what resolves, as one instance
pi remove <source>                                  # and its resources stop loading
pi -e npm:@example/pi-tools                         # try one invocation; no settings write
pi install --local ./local-package                  # writes the project's .pi/settings.json

本地安装记录一个相对 settings 文件的路径,什么都不复制;--local 写进项目的 .pi 之下,并且只在项目信任被授予之后才加载。按解析出的路径确定身份——本地包按绝对路径,git 包按不含 ref 的仓库 URL——意味着同一个包列了两次只加载一次。

过滤加载的内容

设置可以按资源类型收窄一个包。[] 表示一个都不要,!pattern 排除,而过滤器绝不会暴露包没有声明的资源:

{
  "packages": [
    {
      "source": "npm:@example/pi-tools",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": ["x"],
      "prompts": []
    }
  ]
}

依赖规则

Pi 为你的扩展代码提供五个包,而它们绝不能被打包——一份物理副本会绕过模块映射,造成重复的类、注册表和初始化。把它们声明为 peer dependencies,范围用 *:

{
  "name": "pi-guard",
  "version": "0.3.0",
  "keywords": ["pi-package"],
  "peerDependencies": { "@earendil-works/pi-coding-agent": "*", "@earendil-works/pi-ai": "*" },
  "dependencies": { "fast-glob": "^3.3.2" },
  "pi": { "extensions": ["./src/extension.ts"] }
}

同样这五个出现在 dependencies 里,会引来下面表格里的警告。

预期结果

命令 / 声明 行为(经交付二进制已观察)
pi install ./my-pkg 把 ../my-pkg 记进用户设置,相对 settings 文件;什么都不复制
pi list / pi remove 显示它;移除它;模板不再展开
无清单 按约定发现 extensions/、skills/、prompts/;扩展的工厂运行了一次
pi -e ./my-pkg 为一次调用加载;什么也不写进设置
"prompts": [] 过滤器 没有提示词加载;扩展仍然加载
同一个包列了两次 只加载一次——身份就是解析出的路径
pi install --local 写进项目的 .pi/settings.json;只在信任被授予后加载
存在于 dependencies 的宿主包 警告;用 peerDependencies "*" 则没有

机制与局限

已观察: packages.test.ts 用一个脚本化的模型,拿交付的 pi 二进制对着一个真实包目录跑,并断言上面那张表。有文档记载: packages.md 锁定带版本的 git ref(更新会对齐检出,但不会移动一个已配置的 ref),并说明"过滤器收窄包清单。它们不会暴露包自己没有声明的资源。"

这个示例不为你运行任何东西,也不展示模型。git 和 npm 来源、pi update,以及 autoload: false 都没有被测试运行。一个包能执行扩展代码并指示模型运行程序,所以安装前审阅第三方源代码——那个条目是可执行内容的一道关卡,不是一个书签。

完整源码与测试 。

Understand this example

Copy this prompt into your AI tool. No code runs here.

Apply this example

Copy this prompt into your AI tool. No code runs here.