Pi Agent 源码级教程
F08

打包分发 —— package.json 里的 pi 清单

2,176 字 · 含 44 行代码 · 约 15 分钟

F05 到 F07 写的都是「你自己机器上的东西」。一旦想让同事用上, 问题就换了:文件放哪、依赖怎么带、别人装上之后能不能跑。

Pi 的答案很省事——一个普通的 npm 包或 git 仓库, 在 package.json 里加一个 pi 键。

三个问题:

  1. 不写 pi 清单行不行?写了又有什么不同?
  2. @earendil-works/pi-tui 这类宿主包,为什么必须是 peerDependencies?
  3. 同一个包被两个人装了,谁的名字赢?

一、两种包:约定目录 与 显式清单

最简单的包就是四个约定目录(packages.md:48-59):

text
my-pi-package/├── package.json├── extensions/     ← .ts / .js├── skills/         ← 含 SKILL.md 的目录├── prompts/        ← .md└── themes/         ← .json

不用写任何清单,Pi 会去这四个目录里扫。扫描规则写在 core/package-manager.ts:235-240 的 FILE_PATTERNS 里—— 就四个正则,extensions 收 .ts|.js,themes 收 .json,其余两个收 .md。

资源放别处、或者需要过滤时,才写显式清单(packages.md:63-74):

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

这里有个容易误判的细节:hasManifestResourceFields(package-manager.ts:686-688) 判断「是不是显式清单」的标准是四个资源键里有没有至少一个。 所以只写 pi.changelogPath、pi.image 这类纯元数据的包, 仍然走目录自动发现(:684-685)。它不会因为有了 pi 键就变成「什么都不加载」。

keywords: ["pi-package"] 决定的是另一件事:让 npm 上的包能进入 Pi 包画廊 的检索(packages.md:78)。 不加也能装,只是别人搜不到。


二、pi install 的四种来源

来源 例子 行为
npm npm:@example/pi-tools@1.0.0 装进 Pi 自己的 npm 目录
git git:github.com/example/pi-tools@v1 克隆并跟随指定 ref
URL https://github.com/example/pi-tools 当作 git 源处理
本地 ./pi-tools 按解析后的路径加载,不复制

命令表在 cli.md:262-267:

动作 命令
装 pi install <source>
看已装 pi list
卸 pi remove <source>(pi uninstall 是别名)
更新全部扩展 pi update --extensions

写进哪个文件决定生效范围:默认写 ~/.pi/agent/settings.json, 加 --local(-l)写项目 .pi/settings.json(packages.md:21)。 后者只在项目受信任后才会被读——又一次回到 F01 那道闸门。

不想写进配置、只想试一次,用 -e(packages.md:25-31):

powershell
pi -e npm:@example/pi-tools

-e 的包缓存在 ~/.pi/agent/tmp/extensions/,每次启动和 /reload 都会核对。 锁定到精确版本的不会被检查(@1.2.3 就是 @1.2.3), 范围版本则会跟着 registry 走。离线时用缓存,这条由 PI_OFFLINE 控制 (package-manager.ts:63-67,只认 1 / true / yes)。


三、依赖:哪些要带,哪些绝对不能带

这是打包最容易翻车的地方。packages.md:100-116 讲得很重,拆成三条:

带什么。 扩展 import 的运行时包放进 dependencies。 官方例子 with-deps/package.json 只依赖一个 ms, index.ts:9 一行 import ms from "ms" 就是全部用法。

不带什么。 五个宿主包永远由 Pi 提供:

text
@earendil-works/pi-ai@earendil-works/pi-agent-core@earendil-works/pi-coding-agent@earendil-works/pi-tuitypebox

它们在 peerDependencies 里用 "*" 声明,且不进 dependencies。 原因不是洁癖:packages.md:114 说,多一份物理副本会绕过 Pi 的模块映射, 造出重复的类和注册表——表现出来就是「同一个 Type 不认同一个 Type」, 或者扩展被初始化两次。Pi 检测到这种清单会直接给一条扩展警告。

顺带一提,安装时 Pi 会关掉自动装 peer (--config.strict-peer-dependencies=false,package-manager.ts:1942), 所以 peer 声明只能是「声明」,不能指望它被装下来。

彼此依赖的 Pi 包。 一个 Pi 包依赖另一个 Pi 包时, 被依赖的那个必须打进 tarball,并通过 node_modules 下的资源路径引用 (packages.md:114)。而且两个包各自的模块根是隔离的, 不要指望共享同一个依赖实例(:116)。


四、装不上的时候 Pi 不会死

这条设计值得单独一节。packages.md:19:配置好的包在启动时安装失败 (比如 registry 连不上),Pi 会警告、跳过这个包的资源、继续运行, 下次启动或 /reload 再试。

但 pi install 和 pi update --extensions 是另一回事: 它们会报错并以非零码退出。

于是同一个故障在两种入口下有相反的表现,写 CI 脚本时要分清: 交互启动的「跳过」不能当成「装好了」,得自己补一条 pi list 或看 warnings。


五、装进项目里不信任,等于没装

项目包在信任决议之后才安装和加载(packages.md:23)。理由很硬: 包含扩展代码,还可能带一个让模型去执行程序的 skill。

实际会被拒的门(package-manager.ts:203-221 的 resourcePrecedenceRank):

优先级 来源
0 项目 + 设置条目
1 项目 + 自动发现
2 用户 + 设置条目
3 用户 + 自动发现
4 包内资源
5 内置扩展

数字越小越优先,重名时先出现的赢。 所以判定顺序是「项目设置 > 项目目录 > 用户设置 > 用户目录 > 包 > 内置」。 你在 .pi/settings.json 里点名的文件,一定能压过某个包里同名的东西。


六、主题:看起来能随便放,其实不能

主题是本篇最少写、但最容易做错的一个资源类型。三个硬约束:

  • 文件名必须等于 name。 themes.md:68:只有 <agent-dir>/themes/<name>.json 会被热更新,别的来源改动要 /reload。
  • name 不能是 system,不能含 /。 前者是保留名(:22), 后者被用于 "light/dark" 这种双主题格式(:48)。
  • 主题对象是严格的。 themes.md:81:只接受文档里的顶层字段和色彩键, 自定义颜色放在 vars 下;在 colors 里加自定义键会被拒绝。

一个最小文件长这样(字段含义见 themes.md:72-79):

json
{  "name": "my-theme",  "appearance": "dark",  "vars": { "brand": "okhsl(250 60% 55%)" },  "colors": { "accent": "brand", "text": "" }}

色彩六种写法里两种最有用:okhsl(...) 保色相和饱和度可比, "" 表示「用终端自己的默认色」。后者是做 system 类主题的关键—— 不写死颜色,交给终端。

userMessageBg 是核心色:export 段不写时,HTML 导出的页面和卡片背景 都是从它推出来的(:130)。


七、包的选取粒度

packages.md:120-143 的对象写法,能把一个包「只装一半」:

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

四种语义要背下来:

写法 含义
不写这个键 全要
[] 一个都不要
!glob 从匹配里排除
+path / -path 精确加 / 精确减

关键限制在最后一句:过滤只能在包自己声明过的范围内收窄, 不能凭空放出一个包没提供的资源(packages.md:143)。

同一个包同时出现在用户和项目设置里时,项目条目默认替换用户条目; 只有 autoload: false 时,项目条目才变成「在用户包基础上的过滤增量」(:149)。 这个区别决定了你关一个扩展时,是「项目里关掉」还是「项目里换个配置」。


八、变更日志:只有加载扩展的包才有

packages.md:80-98 有个不对称的规则:

  • 更新后,下次干净启动会读包里的 CHANGELOG.md, 把比上次见到的新版本显示在 "Extension Updates" 下;
  • 只提供 skills / prompts / themes 的包不显示变更日志。

版本标题要和 Pi 自己的格式一致(## [1.2.0] 或 ## 1.2.0 - 2026-01-01), 匹配的是 package.json 的 version 字段。 所以 git 源只有在 version 涨了才会看到日志——只改 commit 不升版本,等于静默更新。

pi.changelogPath 可以改路径,设成 "" 关掉。 resolvePackageChangelogPath(package-manager.ts:697-713)还会检查 这个路径必须落在包根内,否则当没配。


九、自己动手验证

实验 1:把 todo.ts 变成一个能装的包。

text
my-todo/├── package.json└── extensions/    └── todo.ts

package.json 里只写 name 和 keywords: ["pi-package"],不写 pi 清单。 然后:

powershell
pi install ./my-todopi list

pi list 应该能看到它。这一步验证了「约定目录不写清单也能用」。

实验 2:故意把宿主包写进 dependencies。

在 my-todo/package.json 里加 "dependencies": { "@earendil-works/pi-tui": "^1.4.0" },重装。 Pi 会报一条扩展警告——packages.md:114 说的就是它。 看完记得删掉:这不是能忽略的提示,真装上会出现重复类。

实验 3:看优先级怎么决定同名谁赢。

放一个 .pi/extensions/todo.ts(项目自动发现),同时装上面那个包。 两边都注册 todo 工具名。这时项目那份赢(优先级 1 对 4), 而且这份生效需要项目受信任——pi --approve 和不加参数各跑一次对比。

改一处试试

在一个主题文件里把 accent 改成 "",/reload,观察强调色变成终端自己的颜色。 再把它改成 "oklch(62% 0.1 200)",同样是冷色但亮度由主题控制。 两个值都是合法写法,差别在于「谁说了算」。


十、工程暗坑

坑一:把宿主包 dependencies 了。 编译得过,跑起来可能出现重复注册、类型不认、扩展加载两次。 五个宿主包一律 peerDependencies: "*"。

坑二:以为 pi install 失败等于 Pi 起不来。 启动时会跳过并继续跑,pi install 才会非零退出。CI 里别只看退出码。

坑三:git 包不升 version。 更新了代码但变更日志不出现,用户以为没更新。改代码就升版本。

坑四:主题文件名和 name 不一致。 能加载,但热更新不生效,每次都要 /reload 才发现改动。

坑五:在 colors 里加自定义键。 严格模式会拒掉整份主题。自定义颜色一律放 vars,colors 里只写角色名。

坑六:以为项目里的 packages 一定覆盖用户设置。 默认是替换,但配了 autoload: false 就变成增量过滤—— 想彻底替换,别加这个字段。


十一、本章源码索引

文件 行数 本章用到的位置
packages/coding-agent/src/core/package-manager.ts 2,907 资源扫描、优先级、变更日志路径
packages/coding-agent/examples/extensions/with-deps/package.json 23 带依赖的最小包清单
packages/coding-agent/examples/extensions/with-deps/index.ts 33 用第三方依赖注册工具
packages/coding-agent/docs/packages.md 153 源格式、依赖规则、选取粒度全表
packages/coding-agent/docs/themes.md 138 主题字段、色彩写法、热更新条件
packages/coding-agent/docs/cli.md 343 包命令与别名

十二、下一章

包是「给别人用」。下一章回到「给自己用」: 同一套东西,Pi 提供了五种接口——交互 TUI、-p 一次性、 --mode json 流式、--mode rpc 进程协议、以及 SDK 直接嵌进 Node 程序。 F09 会把五个入口的实际输出摆在一起对比,说清什么时候该用哪个。