Pi Agent拡張入門

Extensions(拡張)はPi Agentで最も強力なカスタマイズ方法です——TypeScriptでカスタムツール、コマンド、イベントリスナーを作成できます。


Extensionとは

ExtensionはTypeScriptモジュールであり、以下のことができます。

機能説明典型的な用途
登録カスタムツールAIに呼び出し可能な新機能を追加内部システムの照会、データベースの読み書き、サードパーティAPIのラップ
登録カスタムコマンドユーザーが /コマンド名 で呼び出しよく使うプロンプトをラップし、ワンクリックで定型フローを実行
監視ライフサイクルイベントAIの作業の各段階にロジックを挿入危険なコマンドのインターセプト、コンテキストの注入、監査ログの記録
登録キーボードショートカットターミナルUIでキーをバインドパネルのクイック切り替え、頻繁に行う操作のトリガー
表示カスタムUIターミナルにインタラクティブUIをレンダリングプログレスバー、リスト、確認ダイアログなどのコンポーネント

最初のExtension:Hello World

次の拡張は、イベント監視、ツール登録、コマンド登録の3つの機能を一度にデモンストレーションします。

実例

// ファイルパス:~/.pi/agent/extensions/my-extension.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  // セッション起動時にトリガー
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("私の拡張がロードされました!", "info");
  });

  // 危険なコマンドをインターセプト
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash"
        && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("危険な操作!", "rm -rfを実行しますか?");
      if (!ok) return { block: true, reason: "ユーザーがブロック" };
    }
  });

  // カスタムツールを登録
  pi.registerTool({
    name: "greet",
    label: "挨拶",
    description: "指定した人に挨拶する",
    parameters: Type.Object({
      name: Type.String({ description: "挨拶する相手の名前" }),
    }),
    async execute(toolCallId, params) {
      return {
        content: [{ type: "text", text:`こんにちは、${params.name}!` }],
        details: {},
      };
    },
  });

  // カスタムコマンドを登録
  pi.registerCommand("hello", {
    description: "世界に挨拶",
    handler: async (args, ctx) => {
      ctx.ui.notify(`こんにちは ${args || "世界"}!`, "info");
    },
  });
}

13行目のイベント判定は最もシンプルなevent.toolName書き方を使用しています。型ガードを使ってeventを具体的なイベント型に絞り込むこともできます。『イベントシステム』の章を参照してください。

pi -e パラメータでPi Agentを起動すると、この拡張をロードしてテストできます:

$ pi -e ~/.pi/agent/extensions/my-extension.ts
Loading extension: /Users/サンプル/.pi/agent/extensions/my-extension.ts
my-extension 加载成功(1 个工具、1 个命令)
我的扩展已加载!

最後の行はsession_startイベント内のctx.ui.notifyが表示した通知で、拡張が有効になっていることを示しています。


拡張の読み込み場所

Pi Agentは固定のいくつかのディレクトリで拡張を自動的に検出します。パスを明示的に指定することもできます。

場所適用範囲説明
~/.pi/agent/extensions/*.tsグローバルすべてのプロジェクトに有効、自動検出
~/.pi/agent/extensions/*/index.tsグローバルサブディレクトリにindex.tsを含む拡張
.pi/extensions/*.tsプロジェクト現在のプロジェクトのみ、プロジェクト信頼が必要
.pi/extensions/*/index.tsプロジェクトプロジェクトのサブディレクトリ拡張

コマンドライン引数の他に、settings.jsonのextensionsフィールドにパスの配列を記述することもできます。ディレクトリパスは拡張ディレクトリのルールに従って展開されます。

実例

{
  "extensions": [
    "/Users/サンプル/.pi/agent/extensions/quick-notify.ts",
    "/Users/サンプル/.pi/agent/extensions/team-tools"
  ]
}

最初の要素は単一ファイル拡張、2番目はディレクトリ拡張です。実際に使用する際は自分の拡張の場所に置き換えてください。


Extensionのファイル構造

Extensionは単一の.tsファイルでも、エントリーファイルを含むディレクトリでも構いません。

単一ファイル拡張

最もシンプルな形式で、小規模な拡張に適しています:

~/.pi/agent/extensions/
└── my-extension.ts

ディレクトリ拡張(index.tsを含む)

複数ファイルの拡張に適しています:

~/.pi/agent/extensions/
└── my-extension/
    ├── index.ts        # 入口文件(导出默认函数)
    ├── tools.ts        # 辅助模块
    └── utils.ts        # 工具函数

依存関係のある拡張

npmパッケージを必要とする大規模な拡張に適しています:

~/.pi/agent/extensions/
└── my-extension/
    ├── package.json    # 声明依赖和入口
    ├── node_modules/   # npm install 后生成
    └── src/
        └── index.ts

拡張はあなたのシステム権限で実行され、任意のコードを実行できます。

信頼できるソースからの拡張のみインストールしてください。


拡張の読み込みメカニズム

拡張はjitiで読み込まれ、TypeScriptコードはコンパイル不要で直接実行できます。

ファクトリー関数がPromiseを返す場合、Pi Agentは起動プロセスを続行する前にその完了を待ちます。

つまり、拡張の初期化時に非同期操作(リモート設定の取得など)を行うことができます。


利用可能なImportパッケージ

これらのパッケージはPi Agentに組み込みで提供されており、拡張内で直接importできます。

パッケージ名用途
@earendil-works/pi-coding-agent拡張タイプ(ExtensionAPI、ExtensionContext、各種イベントタイプ)
typeboxツールパラメータのSchema定義
@earendil-works/pi-aiAIツール(Google互換の列挙型に使用されるStringEnumなど)
@earendil-works/pi-tuiカスタムレンダリング用のTUIコンポーネント

これらの組み込みコアパッケージはPi自身が提供するため、peerDependenciesに列挙するだけでよく、拡張にバンドルしないでください。

独自のランタイム依存関係はpackage.jsonのdependenciesフィールドに記述する必要があります。

Piは拡張パッケージをインストールする際、デフォルトで本番インストール(npm install --omit=dev)を実行するため、devDependenciesは実行時には利用できません。

他のnpmパッケージも使用できます——拡張ディレクトリにpackage.jsonを追加してnpm installを実行するだけです。


開発のヒント

これらの経験則は、特に読み込み方法の選択において、遠回りを避けるのに役立ちます。

方法理由
拡張を~/.pi/agent/extensions/ディレクトリに置く/reloadによるホットリロードをサポートし、変更後にセッションを再起動する必要がない
pi -e ./path.ts一時的なテストのみに使用長期的に使用する場合は拡張を ~/.pi/agent/extensions/ ディレクトリに置き、Pi Agentに自動検出させる
拡張ファクトリー関数でバックグラウンドリソースを起動しないプロセス、ソケット、ファイルリスナー、タイマーなどはsession_startイベントで起動する
session_shutdownイベントでセッションレベルのリソースをクリーンアップするセッション切り替え後にハンドルとリスナーが残るのを防ぐ

さらなる統合

拡張の作成に加えて、公式では2つのプログラミング統合ルートが提供されています。

NodeまたはTypeScriptプロジェクトは直接@earendil-works/pi-coding-agentがエクスポートするSDKを使用できます:createAgentSessionでセッションを作成し、subscribeでイベントを購読し、promptでメッセージを送信します。

この方法はPiと同じプロセスで実行され、型定義が完全です。

言語をまたいだ呼び出しやプロセス分離が必要な場合は、pi --mode rpcを使用し、JSONLプロトコルでPiプロセスと通信します。

2つのルートは拡張と同じイベントモデルを共有しています。どちらを選ぶかは、独立したプロセスが必要かどうかによります。

その他の拡張