Pi Packages

pi 可以協助你建立 Pi 套件。請它打包你的擴充、技能、Prompt Templates 或主題。

Pi 套件會打包擴充、技能、Prompt Templates 和主題，以便透過 npm 或 git 共享。套件可以在 package.json 的 pi 鍵下宣告資源，也可以使用慣例目錄。

• 安裝和管理
• 套件來源
• 建立 Pi 套件
• 套件結構
• 相依性
• 套件過濾
• 啟用和停用資源
• 範圍與去重

安全性： Pi 套件會以完整系統存取權限執行。Extensions 可執行任意程式碼，技能可指示模型執行任何操作，包括執行可執行檔。安裝第三方套件前請先檢查原始碼。

pi install npm:@foo/bar@1.0.0
pi install git:github.com/user/repo@v1
pi install https://github.com/user/repo  # raw URLs work too
pi install /absolute/path/to/package
pi install ./relative/path/to/package

pi remove npm:@foo/bar
pi list                     # show installed packages from settings
pi update                   # update pi only
pi update --all             # update pi, update packages, and reconcile pinned git refs
pi update --extensions      # update packages and reconcile pinned git refs only
pi update --models          # refresh model catalogs only
pi update --self            # update pi only
pi update --self --force    # reinstall pi even if current
pi update npm:@foo/bar      # update one package
pi update --extension npm:@foo/bar

這些指令管理 Pi 套件，pi update 可以更新 Pi CLI 安裝。要解除安裝 Pi 本身，請參閱 Quickstart。

預設情況下，install 和 remove 寫入使用者設定 (~/.pi/agent/settings.json)。請使用 -l 寫入專案設定 (.pi/settings.json)。專案設定可以與你的團隊共享，並且在專案受信任後，pi 會在啟動時自動安裝任何缺少的套件。

要試用某個套件而不安裝它，請使用 --extension 或 -e。這會安裝到僅供目前執行使用的暫存目錄：

pi -e npm:@foo/bar
pi -e git:github.com/user/repo

Pi 在設定和 pi install 中接受三種源類型。

npm:@scope/pkg@1.2.3
npm:pkg

• 帶版本號的 spec 會被固定，並在 package 更新時跳過（pi update --extensions、pi update --all）。
• 使用者安裝位於 ~/.pi/agent/npm/ 下。
• 專案安裝位於 .pi/npm/ 下。
• 將 settings.json 中的 npmCommand 設定為將 npm package 尋找和安裝操作固定到特定的包裝器指令，例如 mise 或 asdf。

範例：

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

git:github.com/user/repo@v1
git:git@github.com:user/repo@v1
https://github.com/user/repo@v1
ssh://git@github.com/user/repo@v1

• 如果沒有 git: 前綴，則僅接受協議 URL（https://、http://、ssh://、git://）。
• 使用 git: 前綴，接受簡寫格式，包括 github.com/user/repo 和 git@github.com:user/repo。
• HTTPS 和 SSH URL 均受支援。
• SSH URL 自動使用你設定的 SSH 鍵（尊重 ~/.ssh/config）。
• 對於非互動式執行（例如 CI），你可以設定 GIT_TERMINAL_PROMPT=0 以停用憑證提示，並設定 GIT_SSH_COMMAND（例如 ssh -o BatchMode=yes -o ConnectTimeout=5）以快速失敗。
• Git ref 是固定的標籤或 commit。pi update --extensions 和 pi update --all 不會將其移至較新的 ref，但會將既有 clone 對齊至設定的 ref。
• 使用 pi install git:host/user/repo@new-ref 更新設定，並將既有套件移至新的固定 ref。
• 會 clone 到 ~/.pi/agent/git/<host>/<path>（全域）或 .pi/git/<host>/<path>（專案）。
• 當對齊作業變更 checkout 時，pi 會重設並清理 clone，然後在 package.json 存在時執行 npm install。

SSH 範例：

# git@host:path shorthand (requires git: prefix)
pi install git:git@github.com:user/repo

# ssh:// protocol format
pi install ssh://git@github.com/user/repo

# With version ref
pi install git:git@github.com:user/repo@v1.0.0

/absolute/path/to/package
./relative/path/to/package

本機路徑指向磁碟上的檔案或目錄，無須複製即可新增到設定中。相對路徑會依其所在的設定檔解析。若路徑是檔案，會作為單一擴充功能載入；若為目錄，pi 會依套件規則載入資源。

將 pi manifest 新增到 package.json，或使用慣例目錄。加入 pi-package 關鍵字以提高可發現性。

{
  "name": "my-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

路徑是相對於套件根目錄。陣列支援 glob 模式與 !exclusions。

package gallery 會顯示標記為 pi-package 的套件。新增 video 或 image 欄位即可顯示預覽：

{
  "name": "my-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "video": "https://example.com/demo.mp4",
    "image": "https://example.com/screenshot.png"
  }
}

• 影片：僅限 MP4。在桌面上，游標懸停時會自動播放；點擊可開啟全螢幕播放器。
• 圖片：PNG、JPEG、GIF 或 WebP。顯示為靜態預覽。

如果兩者都設定，則優先使用影片。

如果不存在 pi 清單，pi 會自動從這些目錄中探索資源：

• extensions/ 載入 .ts 和 .js 檔案
• skills/ 遞迴尋找 SKILL.md 資料夾並載入頂級 .md 檔案作為技能
• prompts/ 載入 .md 檔案
• themes/ 載入 .json 檔案

第三方執行階段相依項屬於 package.json 中的 dependencies。不註冊擴充、技能、Prompt Templates 或主題的相依項也屬於 dependencies。當 pi 從 npm 或 git 安裝套件時，它會執行 npm install，因此這些相依項會自動安裝。

Pi 捆綁擴充和技能的核心包。如果你匯入其中任何一個，請在 peerDependencies 中以 "*" 範圍列出它們，並且不要捆綁它們：@earendil-works/pi-ai、@earendil-works/pi-agent-core、@earendil-works/pi-coding-agent、@earendil-works/pi-tui、typebox。

其他 Pi 套件必須捆綁在你的 tarball 中。將它們新增到 dependencies 和 bundledDependencies，然後透過 node_modules/ 路徑引用其資源。Pi 會以各自獨立的模組根目錄載入套件，因此個別安裝不會衝突或共用模組。

例子：

{
  "dependencies": {
    "shitty-extensions": "^1.0.1"
  },
  "bundledDependencies": ["shitty-extensions"],
  "pi": {
    "extensions": ["extensions", "node_modules/shitty-extensions/extensions"],
    "skills": ["skills", "node_modules/shitty-extensions/skills"]
  }
}

使用設定中的物件形式篩選套件要載入的內容：

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

+path 和 -path 是相對於套件根目錄的精確路徑。

• 省略某個鍵會載入該類型的全部資源。
• 使用 [] 表示不載入該類型的任何資源。
• !pattern 排除比對項。
• +path 強制包含精確路徑。
• -path 強制排除精確路徑。
• 過濾規則疊加在 manifest 之上，只會進一步縮小已允許的範圍。

使用 pi config 啟用或停用已安裝套件和本機目錄中的擴充、技能、Prompt Templates 和主題。 pi config 在全域設定中啟動（~/.pi/agent/settings.json）；按 Tab 鍵可在全域模式和專案本機模式之間切換。使用 pi config -l 在專案覆寫 (.pi/settings.json) 中啟動，繼承的全域資源變暗。

套件可以出現在全域和專案設定中。如果相同的套件出現在兩者中，則專案條目優先，除非專案條目具有 autoload: false；此時會將它作為全域條目的增量套用。身分由以下因素決定：

• npm：套件名稱
• git：不帶引用的儲存庫 URL
• local：解析的絕對路徑