Pi Packages

pi は pi パッケージの作成に役立ちます。拡張機能、スキル、prompt templates、またはテーマをバンドルするよう依頼してください。

Pi パッケージには拡張機能、スキル、prompt templates、テーマがバンドルされているため、npm または git を通じて共有できます。パッケージは、pi キーの下の package.json でリソースを宣言することも、従来のディレクトリを使用することもできます。

• Install and Manage
• Package Sources
• Creating a Pi Package
• Package Structure
• Dependencies
• Package Filtering
• Enable and Disable Resources
• Scope and Deduplication

セキュリティ: 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 は設定で 3 つのソース タイプを受け入れ、pi install は受け入れます。

npm:@scope/pkg@1.2.3
npm:pkg

• バージョン管理された仕様は固定され、パッケージの更新によってスキップされます (pi update --extensions、pi update --all)。
• ユーザーのインストールは ~/.pi/agent/npm/ 未満になります。
• プロジェクトのインストールは .pi/npm/ 未満になります。
• settings.json に npmCommand を設定すると、npm パッケージ検索とインストール操作が 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) を設定してフェイルファストにすることができます。
• Ref は固定されたタグまたはコミットです。 pi update --extensions と pi update --all は、新しい参照に移動しませんが、既存のクローンを構成された参照に調整します。
• pi install git:host/user/repo@new-ref を使用して設定を更新し、既存のパッケージを新しい固定参照に移動します。
• ~/.pi/agent/git/<host>/<path> (グローバル) または .pi/git/<host>/<path> (プロジェクト) にクローンが作成されます。
• 調整によってチェックアウトが変更されると、pi はクローンをリセットしてクリーンアップし、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 マニフェストを package.json に追加するか、従来のディレクトリを使用します。見つけやすくするために、pi-package キーワードを含めます。

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

パスはパッケージのルートからの相対パスです。配列はグロブ パターンと !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 には、拡張機能とスキルのコア パッケージがバンドルされています。これらのいずれかをインポートする場合は、@earendil-works/pi-ai、@earendil-works/pi-agent-core、@earendil-works/pi-coding-agent、@earendil-works/pi-tui、typebox を"*" の範囲でpeerDependencies にリストし、バンドルしないでください。

他の 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 正確なパスを強制的に除外します。
• マニフェストの上にあるフィルターレイヤー。彼らはすでに許可されているものを絞り込みます。

pi config を使用して、インストールされたパッケージおよびローカル ディレクトリの拡張機能、スキル、prompt templates、およびテーマを有効または無効にします。 pi config はグローバル設定 (~/.pi/agent/settings.json) で開始します。 Tab キーを押して、グローバル モードとプロジェクト ローカル モードを切り替えます。 pi config -l を使用して、継承されたグローバル リソースが淡色表示された状態でプロジェクト オーバーライド (.pi/settings.json) を開始します。

パッケージは、グローバル設定とプロジェクト設定の両方に表示できます。同じパッケージが両方に表示される場合、プロジェクト エントリが autoload: false でない限り、プロジェクト エントリが優先されます。その場合、グローバル エントリに対するデルタとして適用されます。アイデンティティは次によって決定されます。

• npm: パッケージ名
• git: 参照のないリポジトリ URL
• ローカル: 解決された絶対パス