← Pi Agents

包:交付一个智能体

一个 Pi 包如何把一个扩展连同它的技能、提示词和主题作为一个可安装单元携带,以及哪些依赖绝不应该被打包。

你有一个扩展。它注册了一个工具、一条 /guard 命令、一个针对它自己的会话条目的渲染器,以及一个告诉模型何时使用该工具的技能。一位同事想要它。你把你的 .pi 文件夹打了个 zip 发过去,然后它坏了:他们的 guard 包是同一批依赖的另一个副本,他们的技能路径对着他们自己的项目解析,而条目渲染器从不触发,因为自定义条目类型对不上。

本章讲的是让这个智能体变得可交付。一个 Pi 包不是扩展外面的一层包装——它是你写下的一切的分发单元。

什么是包

出自 packages.md:“Pi 包把扩展、技能、提示词模板和主题作为一个单元安装和分发。当一样定制应当通过 npm 或 git 共享时,或者当若干个资源属于一体时,就使用包。”

第二个分句是人们会漏掉的那个。单个扩展文件不需要包。当你需要两个资源一起到达,因为其中一个引用另一个时,你才需要包。一个指示模型调用你的工具的技能是最清楚的例子:没有技能,工具没用;没有工具,技能会误触发。

一个包是"一个普通目录或 npm 包"。这是刻意放松的。它可以暴露约定俗成的资源目录,在 package.json 的 pi 键下声明显式路径,并携带自己的运行时依赖。

最简单的包

把资源丢进约定目录,Pi 就会发现它们。不需要清单。

pi-guard/
├── package.json
├── extensions/
│   └── guard.ts
├── skills/
│   └── guarded-edit/
│       ├── SKILL.md
│       └── references/
│           └── policy.md
├── prompts/
│   └── review-change.md
└── themes/
    └── guard-dark.json

“没有 pi 清单,Pi 会从那些目录中发现 TypeScript 和 JavaScript 扩展、技能目录、Markdown 提示词和 JSON 主题。”

如果你想让它有资格进入 Pi 包展示馆,加上这个关键字:

{
  "name": "pi-guard",
  "version": "0.3.0",
  "keywords": ["pi-package"],
  "pi": {
    "image": "https://example.com/pi-guard.png",
    "video": "https://example.com/pi-guard-demo.mp4"
  }
}

pi-package 关键字就是让一个 npm 包在展示馆中可被发现的东西。可选的 pi.image 和 pi.video 字段会在那里添加预览。

一个包声明其资源的两种方式

这是在约定与显式清单之间的选择,值得刻意地选,而不是顺着默认。

    flowchart TD
  P["一个包目录或 npm 包"] --> Q{"package.json 是否声明了<br/>`pi` 键?"}
  Q -->|"否"| CONV["约定式发现<br/>pi 找到 extensions/、skills/、prompts/、themes/"]
  Q -->|"是"| EXPLICIT["清单是权威的<br/>extensions、skills、prompts、themes,<br/>以及可选的 mcpServers"]
  CONV --> LOAD["资源在发现时注册"]
  EXPLICIT --> LOAD
  EXPLICIT --> GATE{"需要过滤器吗?<br/>settings 对象形式"}
  GATE -->|是| NARROW["只有匹配的资源加载"]
  GATE -->|否| LOAD
  

没有清单时,发现靠的是约定目录名。有了清单,清单就是权威的——而就在那一刻,一个没有被列出的资源会停止加载,这正是这个功能有用的那一半。

一旦你的资源不是并列的,约定目录就是错误的形状。当资源住在别处或需要过滤时,使用显式形式:

{
  "name": "pi-guard",
  "version": "0.3.0",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./src/extension.ts"],
    "skills": ["./resources/skills"],
    "prompts": ["./resources/prompts/*.md"],
    "themes": ["./resources/themes/*.json"]
  }
}

这里有三条规则比例子本身更重要:

  • “路径相对于包根目录。”
  • “数组接受 glob 模式和排除项。”
  • “当穿过 glob 的遍历不会发现它们时,直接列出以点开头或经符号链接到达的资源根。”

第三条规则会抓住人。一个走进以点开头的目录、或只经符号链接到达的 glob,什么也找不到——所以你显式地点名路径,而不是指望模式展开。

那条会搞坏构建的依赖规则

这是一个值得在发布前就先学会的错误。Pi 为你的扩展和技能代码提供五个包:

  • @earendil-works/pi-ai
  • @earendil-works/pi-agent-core
  • @earendil-works/pi-coding-agent
  • @earendil-works/pi-tui
  • typebox

把它们声明为 peer dependencies,范围用 "*"。不要打包它们。

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

文档里说出这个原因时没有留余地:“一份物理副本可能绕过 Pi 在编译后 ESM 中的扩展模块映射,造成重复的类、注册表和初始化工作。Pi 在检测到这种清单配置时会报告一个扩展警告。”

一个类的两份副本不是体积问题。它是类型认同问题:一次 isinstance 检查失败,一次注册表查找落空,初始化跑了两遍。清单看起来正确,而行为是不连贯的。

Pi “对托管的 npm 包以及用 npm、pnpm 或 Bun 安装的 git 包,抑制自动的 peer 安装。” 本地包则"不被安装也不被修改,所以其依赖树仍然是包作者的责任。" 如果你 pi install ./pi-guard,那里的 node_modules 归你管。

1.0.1 中一次依赖解析的变更,改变了这其中有多少是你的问题。npm-shrinkwrap.json 从已发布的包里被移除了,于是"npm 安装不再锁定传递依赖,库的使用者现在可以覆盖它们。" Pi 自己的快速上手现在明确对照两条路径:pi.dev 安装器"锁定全部依赖",而从 npm 安装"不锁定传递依赖。"

对任何在包里交付许可关卡的人来说,那是值得读两遍的句子。上面那五个 peer 依赖仍然是你的责任,而且仍然不能被打包,独立模块根的那条规则也仍然成立。变的是你的包拉进来的其他一切:在 npm 之下,它在安装时解析并可能漂移,在托管安装器之下它是固定的。所以诚实的交付建议比"你的依赖树是你的问题"更窄——它是:无论走哪条路,你的树都是你的问题,但在 npm 之下它还是未锁定的,这是一种与重复的类不同的风险。第 42 章的权限阶梯讲的是前者;这是同一门学科里无聊的那一半,供应链的那一半。

这也解释了同一个发布版里一次行为变化:全局 npm 安装上的 pi update 现在会建议迁移到托管安装,而这恰恰是因为那才是会锁定的路径。如果你部署的是 Pi 本身,那条建议是关于你的可复现性,而不是关于 Pi。

还有一条隔离规则:“已安装的包以独立的模块根加载。不要指望两个包共享一个依赖实例,或一个包解析另一个包未声明的依赖。” 如果包 B 需要包 A 的类型,声明它们——不要假设解析会成功。

安装与版本管理

pi install npm:@example/pi-tools@1.0.0
pi install git:github.com/example/pi-tools@v1
pi install ./local-package
来源 行为
npm 安装在 Pi npm 目录下
git 克隆并对齐到选定的 ref
URL 当作 git 来源处理
本地 从解析出的路径加载,不复制

带版本的 npm 规格是被锁定的,而"git 标签和提交也被锁定;包更新会对齐检出,但不会移动一个已配置的 ref。" 所以 pi update --extensions 不会悄无声息地把你的团队挪到一个新标签上。这正是包里含着许可关卡时你想要的那个属性。

“一个文件路径加载一个扩展。一个目录遵循普通的包发现规则。” 这种不对称会抓住那些传入 ~/.pi/agent/extensions/guard.ts 并指望顺带得到那些技能的人。

在定下来之前,为一次调用试一个包:

pi -e npm:@example/pi-tools

管理就是你会料到的那几条命令:pi list、pi remove <source>、pi update --extensions,以及用于启用和禁用单个已发现资源的 pi config。

过滤加载的内容

settings 中的对象形式会收窄一个包加载哪些资源:

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

按资源类型:省略该属性即加载包允许的一切,用 [] 表示一个都不要,用 !pattern 排除匹配项,用 +path 包含某一个确切路径,用 -path 排除某一个确切路径。

限制性的那句话是这样的:“过滤器收窄包清单。它们不会暴露包自己没有声明的资源。” 过滤器能让你的包对某人更小。它不能让包更大。如果你的守卫需要 legacy 扩展才安全,你不能既交付安全性又把那份依赖过滤掉。

作用域与身份

“同一个包可以出现在个人设置和项目设置中。一个项目条目通常替换个人条目。有了 autoload: false,项目条目转而充当对个人包的过滤式增量。” 所以一个想要不同版本的项目得到的是替换,而一个想要个人安装但禁用一个文件的项目得到的是增量。

身份是阻止重复加载的东西:“Pi 按包名识别 npm 包,按不含 ref 的仓库 URL 识别 git 包,按解析出的绝对路径识别本地包。” git:github.com/example/pi-tools@v1 和 git:github.com/example/pi-tools@v2 是同一个包,所以你得到一个实例,不是两个。

当你的包遇到另一个宿主

以上一切假定是 Pi 加载这个包。越来越不会只有这样一件事加载它。

一个针对 Pi API 编写的扩展是一个看起来可移植的对象:它导入 @earendil-works/pi-coding-agent,调用 registerTool,渲染一个组件。一旦 Pi CLI 以外的某个东西加载它——一个编辑器集成、一个桌面应用、一个 CI 包装层——你就进入了 Pi 自己的文档没有覆盖的地带,因为从 Pi 的角度看,那件事根本没有发生。

这值得预先规划,因为失败模式不是你会猜到的那些。

子集问题

一个不同的宿主几乎肯定不实现整个 API。它可能实现十几个成员,把其余的桩掉。有意思的问题是,当你的扩展碰到一个被桩掉的成员时会发生什么。

好的行为是那个起初看起来过于宽松的:

不受支持的成员仍然存在于对象上
调用其中一个什么也不做,并返回一个中性的值
它从不抛出
宿主为每个扩展的每个成员发出一条诊断

回头读一遍,你就看见它买到了什么。一个碰巧碰到不受支持成员的扩展仍然工作。一个从没听说过某个新上游 API 的宿主是降级,而不是崩溃。而作者会知道,因为有一条诊断——但这次运行不会死。

另一种做法是抛出,而抛出就是你将一个部分兼容的扩展变成一次失败会话的方式。第 30 章讲恢复;这是它的第一个案例。

其推论对作为包作者的你不舒服:在一个桩掉了某个成员的宿主上,你的功能静默地缺席。 扩展加载了,命令出现了,工具列出来了,而什么也没发生。没有错误。你的诊断负担从"它会崩吗"转移到"那个人怎么发现它什么也没做",这意味着扩展应当暴露自己的不可用状态,而不是假定它运行过了。

锁定你承诺的那个面

如果一个宿主实现一个子集,那个子集就是一份契约,必须像契约一样被锁定。一个自动跟随已安装包版本的宿主,会把它实现的扩展面报告成"刚好是最新发布版实现的那个"——这意味着一次上游发布可能悄悄加进一个你的关卡没有处理的成员。

站得住的做法是描述你实际实现的那个面,给它命名,并刻意地变更它:

实现   一个具体的、已枚举的成员集合
冻结   把描述出来的那个面固化成它自己的具名版本
评审   显式地变更它,并配一个测试

第 16 章和第 17 章都说,在依赖某个形状之前,先检查导出的类型声明。这是同一门纪律,只是从另一侧看:宿主在声明一份契约,而一个没有版本的契约不算契约。

一个宿主绝不能推断什么

这是后果最重的一条规则,而它适用于你,即使你不是宿主:

一个工具名出现在活动工具列表里,不是许可。它是一个声明。

pi.getActiveTools()——以及另一边的 pi.setActiveTools()——描述的是向模型声明的那组工具。它们不是授予清单。一个把被拒绝但已声明的工具当作可用的扩展,终将出错,而那失败是静默的。

如果你的扩展有安全后果,那份许可必须来自一个模型和扩展不能同时写入的来源。第 42 章整章都在讲那道边界;这是同一条规则,只是从可移植包那一侧看到的。

导入不承诺执行

最后一件值得直说的事,因为在 README 里过度承诺很容易:可加载不等于能运行一切。一次导入可能成功,而这个包的某些依赖无法在导入方环境中执行,再怎么细心打理清单也改变不了这一点。所以,你实际上能向读者提供的可移植性契约是三句话:

  1. 这个包声明它的资源和由宿主提供的依赖,并且不打包它们。
  2. 在一个只实现部分扩展 API 的宿主上,它加载并降级,不受支持的成员会自己报告。
  3. 没有新宿主自己的信任决策,其中没有任何东西会加载进那个新宿主。

第三句是让你不惹麻烦的那一句,而它正是第 8 章为项目画出的那道分离。

交付前检查

发布之前,检查五件事。那五个由宿主提供的包的 peer 依赖,dependencies 里没有副本。你的代码引用的每一个资源都声明在 pi 清单里,包括以点开头和经符号链接的根。从一个不属于你的目录里测过 pi -e。读一遍安装后的 settings.json 条目,确认作用域符合你的意图。以及 pi list,确认这个包解析为一个实例。

包"能执行扩展代码,也能包含指示模型运行程序的技能。" 安装前审阅第三方包的源代码,授予项目信任前审阅项目的包声明——包条目是可执行内容的一道关卡,不是一个书签。

第二部分到这里结束。你有工具、扩展、命令、MCP 服务器,以及一个把这一切都交付出去的包。这些没有一个能解决的,是你在任何长任务进行到两小时时撞上的那堵墙:上下文窗口满了,而模型一直在其上推理的那场对话,即将被一段关于它的文字替换。没有任何打包决策能改变那个天花板,因为那个天花板属于模型,而不属于 Pi。

压缩(compaction)是你撞上那堵墙时运行的东西,而它替换掉的,不是大多数人预期的那样。

运行了什么

examples/ch22-packages/ 构建一个真实的包目录,里面有一个提示词模板、一个技能和一个扩展,并拿交付的二进制对着它跑:

  • pi install ./my-pkg 把这个包记录进用户设置,位置相对 settings 文件(../my-pkg),什么都不复制;
  • pi list 显示它,pi remove 把它拿掉,而移除之后它的提示词模板不再展开;
  • 没有清单时,这个包的模板和扩展从约定目录加载,而扩展的工厂运行了一次;
  • pi -e ./my-pkg 为一次调用加载它,什么也不写进设置;
  • 对象形式过滤一个包:prompts: [] 没有加载任何提示词,而扩展仍然加载了;
  • 过滤器只收窄,从不暴露:在一个只声明 ./elsewhere/*.md 的清单里,在过滤器里点名未声明的 prompts/greet.md 不会加载它;
  • 同一个包列了两次只加载一次,因为身份就是解析出的路径;
  • 一个显式清单可以指向包里其他地方的资源,然后替换约定式发现;
  • pi install --local 写进项目的 .pi/settings.json,而项目的包只在项目被批准之后才加载;
  • 依赖规则是被强制的。 一个把 @earendil-works/pi-ai 列在 dependencies 里的包引来了警告"Host-provided extension packages must be declared in peerDependencies with a “*” range, not dependencies",而换成 peerDependencies 的同一个包没有。

未运行:git 和 npm 来源、pi update,以及 autoload: false。