打包分发 —— package.json 里的 pi 清单
F05 到 F07 写的都是「你自己机器上的东西」。一旦想让同事用上, 问题就换了:文件放哪、依赖怎么带、别人装上之后能不能跑。
Pi 的答案很省事——一个普通的 npm 包或 git 仓库,
在 package.json 里加一个 pi 键。
三个问题:
- 不写
pi清单行不行?写了又有什么不同? @earendil-works/pi-tui这类宿主包,为什么必须是peerDependencies?- 同一个包被两个人装了,谁的名字赢?
一、两种包:约定目录 与 显式清单
最简单的包就是四个约定目录(packages.md:48-59):
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):
{ "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):
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 提供:
@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):
{ "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 的对象写法,能把一个包「只装一半」:
{ "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 变成一个能装的包。
my-todo/├── package.json└── extensions/ └── todo.tspackage.json 里只写 name 和 keywords: ["pi-package"],不写 pi 清单。
然后:
pi install ./my-todopi listpi 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 会把五个入口的实际输出摆在一起对比,说清什么时候该用哪个。