把扩展、技能和提示词作为一个 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.