Pi Agent パッケージ管理
Pi Packages(パッケージ) を使用すると、Extensions、Skills、プロンプトテンプレート、テーマをパッケージ化し、npm または git で配布・インストールできます。
パッケージ管理コマンド
すべてのパッケージ操作は pi コマンドで完結し、settings.json を手動で編集する必要はありません。
| コマンド | 機能 | 例 |
|---|---|---|
| pi install <source> | パッケージをインストールする。-l パラメータでプロジェクトレベルとしてインストール | pi install npm:@サンプル/pi-todo-kit |
| pi remove <source> | パッケージを削除 | pi remove npm:@サンプル/pi-todo-kit |
| pi uninstall <source> | remove と同じ | pi uninstall npm:@サンプル/pi-todo-kit |
| pi list | インストール済みパッケージの一覧表示 | pi list |
| pi update --all | Pi Agent とすべてのパッケージを更新 | pi update --all |
| pi update --extensions | インストール済みのパッケージのみ更新(Pi Agent 本体は含まない) | pi update --extensions |
| pi update <source> | 指定したパッケージの更新 | pi update npm:@サンプル/pi-todo-kit |
使用例:
# 安装 npm 包 $ pi install npm:@サンプル/pi-todo-kit@1.0.0 # 安装 git 包 $ pi install git:github.com/サンプル/pi-todo-kit@v1 # 安装本地包 $ pi install ./packages/pi-todo-kit $ pi install ~/projects/pi-share-kit # 安装为项目级(写入 .pi/settings.json) $ pi install -l npm:@サンプル/pi-todo-kit # 临时试用包(不安装到配置中) $ pi -e npm:@サンプル/pi-todo-kit $ pi -e git:github.com/サンプル/pi-todo-kit
インストール出力はおおよそ次のようになります(イメージ)。extensions と skills の数はパッケージの pi フィールドによって異なります。
$ pi install npm:@サンプル/pi-todo-kit Resolving @サンプル/pi-todo-kit@1.2.0 Downloading @サンプル/pi-todo-kit (12.4 kB) Running npm install in ~/.pi/agent/npm/@サンプル/pi-todo-kit Installed @サンプル/pi-todo-kit@1.2.0 extensions: 2 skills: 1 prompts: 3 Saved to ~/.pi/agent/settings.json
上記のパッケージ名とバージョンはあくまで例示であり、実際に使用する際はインストールしたいパッケージに置き換えてください。
パッケージソース
Pi Agent は3種類のパッケージソースをサポートしており、インストール動作とキャッシュ位置はそれぞれ異なります。
npm パッケージ
npm は推奨されるパッケージ配布方法です:
pi install npm:@scope/pkg@1.2.3 pi install npm:pkg
バージョン番号付きの npm パッケージはロックされ、pi update では自動的にアップグレードされません。
パッケージのインストール場所:グローバルは~/.pi/agent/npm/、プロジェクトレベルは.pi/npm/。
Git パッケージ
HTTPS および SSH プロトコルをサポート:
# HTTPS pi install https://github.com/user/repo@v1 # SSH(git@host:path 需要 git: 前缀) pi install git:git@github.com:user/repo@v1 # SSH 协议 pi install ssh://git@github.com/user/repo@v1
Git パッケージの ref はロックされ、pi update では新しい ref に自動的に移動しません。
クローン場所:グローバルは~/.pi/agent/git/、プロジェクトレベルは.pi/git/。
ローカルパス
ローカルファイルシステムのパスを指し、ファイルはコピーされません:
pi install /Users/サンプル/.pi/agent/packages/my-kit pi install ./packages/my-kit
Pi パッケージの作成
package.json にpiフィールドを追加:
例
"name": "@サンプル/pi-todo-kit",
"keywords": ["pi-package"],
"pi": {
"extensions": ["./extensions"],
"skills": ["./skills"],
"prompts": ["./prompts"],
"themes": ["./themes"],
"video": "https://example.com/demo.mp4",
"image": "https://example.com/screenshot.png"
}
}
もしpiフィールドがない場合、Pi Agent は規約に従ったディレクトリから自動的にリソースを検出します:
| 規約ディレクトリ | 読み込む内容 |
|---|---|
| extensions/ | その中の .ts および .js ファイルを読み込む |
| skills/ | SKILL.md を含むフォルダを再帰的に検索し、同時にトップレベルの .md ファイルを独立した Skill として読み込む |
| prompts/ | その中の .md テンプレートファイルを読み込む |
| themes/ | その中の .json テーマファイルを読み込む |
追加pi-packageキーワードでパッケージをPi Agent パッケージギャラリーに表示できます。
video フィールドと image フィールドは、ギャラリーでプレビューを表示するために使用します。
パッケージのフィルタリング
パッケージをインストールする際に、どのリソースを読み込むかを正確に制御でき、一度にすべてのコンテンツを取り込むことを避けられます。
以下の packages 配列は~/.pi/agent/settings.json(グローバルに有効)または.pi/settings.json(現在のプロジェクトのみ有効)に書き込みます。
pi install -l でインストールしたパッケージはプロジェクトの .pi/settings.json に書き込まれ、どちらの方法も最終的には同じ設定に反映されます。
配列エントリは2つの記法をサポートしています:文字列形式はそのパッケージの全リソースを読み込み、オブジェクト形式はリソースタイプごとにフィルタリングします。
例
"packages": [
"npm:simple-pkg",
{
"source": "npm:@サンプル/pi-todo-kit",
"extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
"skills": ["skills/brave-search"],
"prompts": [],
"themes": ["+themes/legacy.json"]
}
]
}
公式ドキュメントでは、skills フィルタはパッケージ内パスによる記法とスキル名による記法の両方がありますが、実際にはインストールしたパッケージの説明に従ってください。
フィルタリングルールは次のとおりです:
| 構文 | 意味 | 例 |
|---|---|---|
| 特定のキーを省略 | そのタイプのすべてのリソースを読み込む | skills キーを書かない = すべての Skill を読み込む |
| [] に設定 | そのタイプのリソースを一切読み込まない | "prompts": [] |
| !pattern | 一致するリソースを除外 | "!extensions/legacy.ts" |
| +path | 指定パスを強制的に含める | "+themes/legacy.json" |
| -path | 指定パスを強制的に除外 | "-skills/internal" |
依存関係の管理
Pi Agent はインストール済みの各 npm/git パッケージに対してnpm installを実行し、依存関係を自動的にインストールします。
パッケージに同梱されるローカル依存関係はbundledDependenciesを使用してパッケージ化できます。
以下のコアパッケージは Pi Agent 自身が提供するもので、peerDependenciesとしてリストし、パッケージ内に重複して含めないでください:
| パッケージ名 | 説明 |
|---|---|
| @earendil-works/pi-ai | AI ツールと型 |
| @earendil-works/pi-agent-core | エージェントコア |
| @earendil-works/pi-coding-agent | Pi Agent メインパッケージ |
| @earendil-works/pi-tui | TUI コンポーネント |
| typebox | パラメータ Schema 定義 |
pi config でのリソース管理
を使用してpi configインストール済みパッケージの拡張機能、Skills、テンプレート、テーマを対話形式で有効または無効にします:
# 编辑全局配置 $ pi config # 编辑项目配置 $ pi config -l
Tab キーでグローバルモードとプロジェクトモードを切り替えます。
スコープと重複排除
同じパッケージをグローバル設定とプロジェクト設定の両方に同時に含めることができます。
プロジェクトエントリが存在する場合、グローバルエントリよりも優先されます。
例外として、プロジェクトエントリがautoload: falseに設定されている場合、全体を上書きせず、グローバルエントリに増分として重ね合わせます。
パッケージの同一性は以下の方法で決定され、Pi Agent はこれに基づいて2つの設定が同じパッケージを指しているかどうかを判断します:
| ソース | 識別子 |
|---|---|
| npm パッケージ | パッケージ名(例:@サンプル/pi-todo-kit) |
| git パッケージ | リポジトリ URL(ref を含まない) |
| ローカルパス | 解決後の絶対パス |