Pi パッケージ · Pi 日本語ドキュメント

Pi パッケージは、拡張機能、スキル、プロンプトテンプレート、テーマを1つの単位としてインストールし、配布します。カスタマイズを npm または git 経由で共有する場合や、複数のリソースをまとめる場合にパッケージを使用します。

パッケージは通常のディレクトリまたは npm パッケージです。規約に従ったリソースディレクトリを公開し、package.json の pi キーで明示的なパスを宣言し、独自のランタイム依存関係を含めることができます。

パッケージのインストールと管理#

npm、git、またはローカルパスからインストールします。

bash

pi install npm:@example/pi-tools@1.0.0
pi install git:github.com/example/pi-tools@v1
pi install ./local-package

pi list は設定済みのパッケージを表示します。パッケージを削除するには pi remove <source>、パッケージのインストール状態を整合させるには pi update --extensions を使用します。すべてのパッケージコマンドとオプションについては、コマンドラインを参照してください。

個人用のインストールは ~/.pi/agent/settings.json に書き込まれます。--local または -l を追加すると、パッケージ宣言が .pi/settings.json に書き込まれます。Pi は、プロジェクトが信頼された後にのみ、そのファイルから宣言を読み取ります。

プロジェクトのパッケージは、プロジェクトの信頼状態が確定した後にのみインストールされ、読み込まれます。パッケージは拡張機能のコードを実行でき、モデルにプログラムの実行を指示するスキルを含めることもできます。サードパーティ製パッケージをインストールする前に、そのソースを確認してください。プロジェクトを信頼する前に、プロジェクトのパッケージ宣言を確認してください。

設定に追加せず、1回の呼び出しだけでパッケージを試すには、--extension または -e を使用します。

bash

pi -e npm:@example/pi-tools

ソースの選択#

ソース	例	動作
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`	コピーせず、解決済みのパスから読み込まれます

バージョンを指定した npm 仕様は固定されます。git のタグとコミットも固定されます。パッケージを更新するとチェックアウトの状態は整合されますが、設定済みの ref は移動しません。

相対ローカルパスは、それを含む設定ファイルを基準に解決されます。ファイルパスを指定すると、1つの拡張機能が読み込まれます。ディレクトリを指定すると、通常のパッケージ検出ルールが適用されます。

パッケージの作成#

最も単純なパッケージでは、規約に従ったディレクトリを使用します。

text

my-pi-package/
├── package.json
├── extensions/
├── skills/
├── prompts/
└── themes/

pi マニフェストがない場合、Pi はそれらのディレクトリから TypeScript および JavaScript の拡張機能、スキルディレクトリ、Markdown プロンプト、JSON テーマを検出します。

リソースが別の場所にある場合や、フィルタリングが必要な場合は、明示的なマニフェストを使用します。

json

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

パスはパッケージルートからの相対パスです。配列では glob パターンと除外指定を使用できます。glob による走査では検出されない、ドットで始まるリソースルートやシンボリックリンクされたリソースルートは、直接指定してください。

pi-package キーワードを指定すると、npm パッケージが Pi パッケージギャラリーで検出される対象になります。任意の pi.image および pi.video フィールドを指定すると、ギャラリーにプレビューが追加されます。

依存関係の宣言#

拡張機能がインポートするランタイムパッケージは、dependencies に含めます。Pi は npm または git ソースをインストールするときに、パッケージの依存関係をインストールします。

Pi は、次のパッケージを拡張機能とスキルに提供します。

@earendil-works/pi-ai
@earendil-works/pi-agent-core
@earendil-works/pi-coding-agent
@earendil-works/pi-tui
typebox

上記のホスト提供パッケージは、"*" の範囲指定を使用して peerDependencies に宣言し、バンドルしないでください。Pi は、管理対象の npm パッケージ、および npm、pnpm、Bun のいずれかでインストールされた git パッケージについて、peer 依存関係の自動インストールを抑止します。ローカルパッケージはインストールも変更もされないため、その依存関係ツリーは引き続きパッケージ作成者の責任です。

ホスト提供パッケージを dependencies に含めないでください。物理的なコピーがあると、コンパイル済み ESM における Pi の拡張機能モジュールマッピングが迂回され、クラスやレジストリが重複し、初期化処理も重複する可能性があります。このマニフェスト設定を検出すると、Pi は拡張機能に関する警告を報告します。依存関係として使用するほかの Pi パッケージは、公開する tarball に含め、その node_modules リソースパスを介して参照する必要があります。

インストールされたパッケージは、個別のモジュールルートで読み込まれます。2つのパッケージが1つの依存関係インスタンスを共有することや、あるパッケージが別のパッケージの未宣言の依存関係を解決することを前提にしないでください。

パッケージリソースの選択#

設定でオブジェクト形式を使用すると、パッケージから読み込むリソースを絞り込めます。

json

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

各リソースタイプについて、次のように指定します。

プロパティを省略すると、パッケージで許可されているすべてのリソースが読み込まれます。
[] を使用すると、そのタイプのリソースは何も読み込まれません。
!pattern を使用すると、glob に一致するものが除外されます。
+path を使用すると、許可されているパスを完全一致で1つ含められます。
-path を使用すると、完全一致するパスを1つ除外できます。

フィルターは、パッケージマニフェストの対象を絞り込みます。パッケージ自体が宣言していないリソースを公開することはありません。

検出されたリソースと Pi の組み込み拡張機能を有効または無効にするには、pi config を実行します。個人用設定から開始します。Tab キーを押すとスコープが切り替わります。プロジェクトのオーバーライドから開始するには、pi config --local を実行します。

スコープと識別情報の理解#

同じパッケージを個人用設定とプロジェクト設定の両方に含めることができます。通常、プロジェクトのエントリは個人用のエントリを置き換えます。autoload: false を指定すると、プロジェクトのエントリは代わりに、個人用パッケージに対する差分フィルターとして機能します。

Pi は、npm パッケージをパッケージ名、git パッケージを ref を除いたリポジトリ URL、ローカルパッケージを解決済みの絶対パスで識別します。これにより、同等の宣言を介して同じパッケージが二重に読み込まれることを防ぎます。

各リソースをパッケージ化する前に設計するには、拡張機能、スキル、プロンプトテンプレート、テーマを参照してください。