Pi Agent拡張入門
Extensions(拡張)はPi Agentで最も強力なカスタマイズ方法です——TypeScriptでカスタムツール、コマンド、イベントリスナーを作成できます。
Extensionとは
ExtensionはTypeScriptモジュールであり、以下のことができます。
| 機能 | 説明 | 典型的な用途 |
|---|---|---|
| 登録カスタムツール | AIに呼び出し可能な新機能を追加 | 内部システムの照会、データベースの読み書き、サードパーティAPIのラップ |
| 登録カスタムコマンド | ユーザーが /コマンド名 で呼び出し | よく使うプロンプトをラップし、ワンクリックで定型フローを実行 |
| 監視ライフサイクルイベント | AIの作業の各段階にロジックを挿入 | 危険なコマンドのインターセプト、コンテキストの注入、監査ログの記録 |
| 登録キーボードショートカット | ターミナルUIでキーをバインド | パネルのクイック切り替え、頻繁に行う操作のトリガー |
| 表示カスタムUI | ターミナルにインタラクティブUIをレンダリング | プログレスバー、リスト、確認ダイアログなどのコンポーネント |
最初のExtension:Hello World
次の拡張は、イベント監視、ツール登録、コマンド登録の3つの機能を一度にデモンストレーションします。
実例
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-ai | AIツール(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つのルートは拡張と同じイベントモデルを共有しています。どちらを選ぶかは、独立したプロセスが必要かどうかによります。
その他の拡張