Chapter 13 · Pi Packages Ecosystem and Distribution

Chapter goals: Master the structure of pi packages and the pi manifest;会用 npm and git两种方式来分发 extensions/skills/templates/themes; and完整发布 your own package.

13.1 What a Package Is and What Problem It Solves

The extensions we wrote in the previous chapters散落 in ~/.pi/agent/extensions/. Pi packages bundle extensions; skills; prompt templates; and themes into a versioned单元; distributing via npm or git; installing with one pi install command. The官方包画廊 (pi.dev/packages)收录 all npm packages带 pi-package keyword.

Security Reminder

Extensions in packages run任意代码 with your完整系统权限.必须审查源码 before installing third-party packages.

13.2 Install and Manage Commands

# Install (default写入 global ~/.pi/agent/settings.json)
pi install npm:@foo/bar@1.0.0          # npm source (with a version pinned; skipped by update; i.e. "钉死")
pi install git:github.com/user/repo@v1 # git source (pinned to the tag/commit)
pi install https://github.com/user/repo # Protocol URLs also直接支持
pi install /absolute/path/to/package   # Local path (not copied;直接引用)
pi install ./relative/path

#临时试用: install only to a temp dir; effective for this run
pi -e npm:@foo/bar

# Manage
pi list                    # List packages installed in settings
pi remove npm:@foo/bar     # Uninstall
pi update --all            # Update pi + all packages + align git-pinned refs
pi update --extensions     # Only update packages
pi update npm:@foo/bar     # Only update one

Add -l to写入 to project settings (.pi/settings.json) instead of global — project settings can共享 with the repo; every team member's pi auto-installs missing packages after the project is trusted.

🔒 Safer托管 updates (0.84.3+): for installer-managed installs; pi update now采用 "staged; then validated; then atomically activated"流程升级 the selected version —中断 an upgrade does not leave a半成品安装; on failure auto-rollback to the旧版本继续可用.

13.3 Package Structure and the pi Manifest

The最规范 way to create a package is to声明 the pi manifest in package.json:

{
  "name": "my-pi-pack",
  "version": "1.0.0",
  "keywords": ["pi-package"],
  "dependencies": {
    "zod": "^3.0.0"
  },
  "peerDependencies": {
    "@earendil-works/pi-coding-agent": "*",
    "@earendil-works/pi-ai": "*",
    "@earendil-works/pi-tui": "*",
    "typebox": "*"
  },
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"],
    "image": "https://example.com/screenshot.png"
  }
}

Rule要点:

• Paths相对 to the包根; arrays support glob and ! exclusion;
• Omitting the pi manifest走约定目录 auto-discovery: extensions/ (.ts/.js); skills/ (recursively找 SKILL.md); prompts/ (.md); themes/ (.json);
• Add the pi-package keyword to keywords to be收录 by the gallery; video (MP4; auto-play on hover) or image can add preview thumbnails.

Three types of dependencies;别搞混:

Type	Purpose
dependencies	Third-party runtime deps (pi auto-executes npm install when installing packages; production installs with --omit=dev; so devDependencies are不可用 at runtime)
peerDependencies ("*")	pi-built-in core libs (pi-ai / pi-agent-core / pi-coding-agent / pi-tui / typebox); do not bundle
dependencies + bundledDependencies	Other pi packages you依赖 on;必须打进 tarball and reference their resources via the node_modules/ path

13.4 Full Walkthrough: Publishing

Using the test-guard extension from Chapter 11 as an example:

mkdir my-pi-pack && cd my-pi-pack
git init && npm init -y
mkdir extensions
# Put test-guard.ts into extensions/

package.json:

{
  "name": "@yourname/test-guard",
  "version": "1.0.0",
  "description": "Auto-run tests before each turn ends and drive fixes",
  "keywords": ["pi-package"; "pi"; "testing"],
  "license": "MIT",
  "peerDependencies": {
    "@earendil-works/pi-coding-agent": "*"
  },
  "pi": {
    "extensions": ["./extensions"]
  }
}

npm publish --access public          # npm distribution
# Or push to GitHub and distribute via git:
git tag v1.0.0 && git push origin v1.0.0

用户侧安装验证:

pi install npm:@yourname/test-guard   # Or git:github.com/yourname/test-guard@v1.0.0
pi list                               # Confirm installed
pi                                    # After startup verify the /guard command exists

13.5 Filtering; Enabling/Disabling; and Deduplication

After installing; you can精细控制 which resources a package loads — use the object form in settings instead of strings:

{
  "packages": [
    "npm:simple-pkg",
    {
      "source": "npm:my-pi-pack",
      "extensions": ["extensions/*.ts"; "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"],
      "themes": ["+themes/legacy.json"]
    }
  ]
}

• Omitting a key = load that类型全部; [] = load none;
• !pattern exclude; +path force-include; -path force-exclude; filtering only做收窄; cannot exceed the manifest's允许范围.

Without改 the JSON; use the interactive pi config: Tab to切换 between global/project settings;可视化启停 each resource.

When the same package appears in both global and project settings: the project entry wins; if the project entry is autoload: false; it applies as an incremental delta atop the global entry. Identity判定: npm看包名; git看去掉 ref的仓库 URL; local看解析后的绝对路径.

Chapter Summary

• pi install/remove/list/update + -l project-level install + -e临时试用构成包管理闭环;
• The pi manifest declares四类 resources; fall back to约定 directories when omitted;
• Three dependency categories: runtime进 dependencies; pi core libs进 peerDependencies: "*"; nested pi packages必须 bundledDependencies;
• npm ( pi-package keyword进 the gallery) and git (pinned to the tag; update only aligns; does not advance)两种分发;
• Object-form filtering + pi config enable/disable + global/project dedup rules.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Where should a pi package's runtime dependencies be声明?

2. After `pi install git:github.com/user/repo@v1`; executing `pi update --extensions`; what happens to the pinned ref?

3. What is the effect of "extensions": [] in the package filter配置?

4. When the same pi package appears in both global and project settings; what is the默认 behavior?

🛠️ Hands-on Practice

1.合并 the skill from Chapter 9 and the extension from Chapter 11 into a pi package; validate locally with pi install ./my-pi-pack; then pi remove to uninstall. 2. Use filter配置 to let上面的 package only加载 skills; not extensions ("extensions": []); verify效果 with pi list and startup logs. 3. Walk通过 git distribution: fork or create a new repo; push the包 and tag v0.1.0; pi install git:github.com/<you>/repo@v0.1.0 to install; then改 code and tag v0.2.0;体验 "re-install to upgrade"的钉住语义.

After completing; continue to Chapter 14: SDK Programmatic Embedding.