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 --allPi 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種類のパッケージソースをサポートしており、インストール動作とキャッシュ位置はそれぞれ異なります。

Pi 包从 npm、git、本地路径三种来源安装到本地目录并自动发现资源的流程

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-aiAI ツールと型
@earendil-works/pi-agent-coreエージェントコア
@earendil-works/pi-coding-agentPi Agent メインパッケージ
@earendil-works/pi-tuiTUI コンポーネント
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 を含まない)
ローカルパス解決後の絶対パス
その他の拡張機能