Pi Agent のコマンドとショートカットキー登録

拡張機能を使ってカスタムコマンド、キーボードショートカット、CLI フラグを登録し、Pi Agent を自分のワークフローに合わせてカスタマイズできます。


カスタムコマンドの登録

使い方pi.registerCommand()ユーザーが / で呼び出せるコマンドを登録します。

以下の拡張機能は、基本コマンドと引数の自動補完付きコマンドの両方を示しています:

例

// 文件路径:~/.pi/agent/extensions/stats-command.ts

// 基础命令
pi.registerCommand("stats", {
  description: "現在のセッションの統計情報を表示", // 必須、/ 自動補完リストに表示されます
  handler: async (args, ctx) => {
    const count = ctx.sessionManager.getEntries().length;
    ctx.ui.notify(`共 ${count}条消息`, "info");
  }
});

// パラメータ付き自動補完のコマンド
pi.registerCommand("deploy", {
  description: "部署到指定环境",
  // パラメータの自動補完を定義します。prefix はユーザーが既に入力したパラメータのプレフィックスです。
  getArgumentCompletions: (prefix) => {
    const envs = ["dev", "staging", "prod"];
    const items = envs
      .filter(e => e.startsWith(prefix))
      .map(e => ({ value: e, label: e }));
    return items.length > 0 ? items : null; // 无匹配时返回 null
  },
  handler: async (args, ctx) => {
    if (!args) {
      ctx.ui.notify("用法: /deploy <环境名>", "warning");
      return;
    }
    ctx.ui.notify(`$にデプロイ中{args}环境...`, "info");
  },
});

保存後、/reload を実行して拡張機能を読み込むと、編集エリアに /stats と入力することで効果を確認できます:

/stats
共 42 条消息

複数の拡張機能が同名のコマンドを登録した場合、Pi Agent はすべての登録を保持し、読み込み順に数字のサフィックスを追加します。例:/review:1 や /review:2。

これにより、拡張機能間の命名の競合を回避できます。


拡張機能から能動的にメッセージを送信する

コマンドやイベントに受動的に応答するだけでなく、拡張機能は能動的に会話を駆動することもできます。

pi.sendMessage(message, deliverAs?)カスタムメッセージの注入に使用し、pi.sendUserMessage(text, deliverAs?)ユーザー入力をシミュレートします。

deliverAs には3つの値があります:steer はデフォルト値で、メッセージを現在のターンに挿入します。followUp はこのターン終了後に追加します。nextTurn は新しいターンを開始します(sendMessage のみ対応)。

sendUserMessage は常に1ターンの応答をトリガーします。AI にとっては実際のユーザー発言であるためです。

ストリーミング出力中にこれらの2つのメソッドを呼び出す場合は、明示的に deliverAs を指定する必要があります。指定しないとエラーが発生します。

例

// 文件路径:~/.pi/agent/extensions/follow-up.ts
// 以下片段位于扩展工厂函数体内

// 模拟用户补充要求:等当前所有工具执行完再追加
pi.sendUserMessage("部署完成后请顺手检查生产环境日志", {
  deliverAs: "followUp",
});

// 只往上下文里塞参考信息,不模拟用户发言
pi.sendMessage({
  customType: "deploy-context",
  content: "現在のデプロイ目標は production です",
  display: true,
}, {
  deliverAs: "steer", // 默认值,插入当前轮
});

sendMessage は triggerTurn: true にも対応しており、agent がアイドル状態のときに LLM 応答を即座に1回トリガーします。

両者の選択基準は簡単です:AI に実際に返答させたい場合は sendUserMessage を使い、参考情報を提供したいだけの場合は sendMessage を使います。


コマンドコンテキスト(ExtensionCommandContext)

コマンドの handler が受け取るのはExtensionCommandContext、これは ExtensionContext を継承しています。

通常のコンテキストに加えて、次のメソッドを追加で提供します:

メソッド説明
ctx.getSystemPromptOptions()システムプロンプトの構築に使う基本入力を読み取ります(contextFiles、skills など)。コマンドコンテキストでのみ利用可能です。
ctx.waitForIdle()AI が完全にアイドル状態になるまで待機します(リトライ、圧縮、フォローアップメッセージの完了を含む)。
ctx.newSession(options)新しいセッションを作成します。親セッションと初期化ロジックを指定できます。
ctx.fork(entryId, options)指定したエントリから新しいセッションをフォークします。
ctx.navigateTree(targetId, options)セッションツリー内の指定位置に移動します。
ctx.switchSession(sessionPath, options)別のセッションファイルに切り替えます。
ctx.reload()/reload と同じホットリロードフローを実行します。

以下のコマンドは、現在のプロジェクトのすべてのセッションを選択リストとして表示し、選択すると直接そのセッションに切り替えます:

例

// 文件路径:~/.pi/agent/extensions/switch-session.ts
import { SessionManager } from "@earendil-works/pi-coding-agent";

pi.registerCommand("switch", {
  description: "切换到另一个会话",
  handler: async (args, ctx) => {
    // 現在のプロジェクトのすべてのセッションを一覧表示
    const sessions = await SessionManager.list(ctx.cwd);
    if (sessions.length === 0) {
      ctx.ui.notify(利用可能なセッションがありません, "warning");
      return;
    }

    // 弹出选择列表
    const choice = await ctx.ui.select(
      "切り替えるセッションを選択:",
      sessions.map(s => s.file),
    );

    if (choice) {
      // 選択中のセッションに切り替える
      await ctx.switchSession(choice, {
        withSession: async (ctx) => {
          ctx.ui.notify("已切换会话", "info");
        },
      });
    }
  },
});
/switch
┌ 选择要切换的会话:
│ > ~/.pi/agent/sessions/my-project/abc123.jsonl
│   ~/.pi/agent/sessions/my-project/def456.jsonl
└
已切换会话

セッション置換の注意事項:withSession コールバック内の ctx は完全に新しいコンテキストです。

古い pi オブジェクトやコマンドコールバックでキャプチャした ctx を使用しないでください。セッション置換後は無効な状態になります。


ショートカットキーの登録

使い方pi.registerShortcut()カスタムキーボードショートカットを登録します。

以下では「Plan モードに切り替え」を、まだ組み込みで使用されていないキーの組み合わせにバインドします:

例

// 文件路径:~/.pi/agent/extensions/plan-shortcut.ts

pi.registerShortcut("ctrl+shift+g", {
  description: "切换 Plan 模式",
  handler: async (ctx) => {
    ctx.ui.notify("已切换 Plan 模式!", "info");
  },
});

起動後、キーの組み合わせを押すとトリガーされます:

已切换 Plan 模式!

キーの組み合わせを選ぶ前に、デフォルトのショートカットキー表を確認して、組み込みのバインドを上書きしないようにしてください。

例えば ctrl+shift+p は「次のモデルに切り替え」で使用済みのため、同じ組み合わせを登録すると、2つの動作がキーを取り合うことになります。

ショートカットキーの形式は修飾キー+キーです。例:ctrl+shift+g、alt+x など。


CLI フラグの登録

使い方pi.registerFlag()pi コマンドにカスタム CLI 引数を追加します。

以下の例では、AI にまず計画を立てさせてから実行させるための --plan ブールフラグを登録します:

例

// 文件路径:~/.pi/agent/extensions/plan-flag.ts

pi.registerFlag("plan", {
  description: "以 Plan 模式启动",
  type: "boolean",
  default: false,
});

// 拡張コード内でフラグ値を確認する
// 注意:pi.getFlag() 要等到命令行参数解析完成后才有值,
// したがって、判断は拡張モジュールのトップレベルに書くのではなく、イベントコールバックに入れることをお勧めします。
// モジュールのトップレベル評価は拡張機能のロード段階で行われるため、この時点で読み取られる値は常にデフォルトの false です。
pi.on("before_agent_start", async (event, ctx) => {
  if (!pi.getFlag("plan")) return; // 未启用 --plan 则不做任何修改
  return {
    systemPrompt: event.systemPrompt
      + "\n\nPlan Mode:先提出计划,经用户确认后再执行。",
  };
});

使用法:

$ pi --plan "帮我实现用户认证功能"

拡張機能間の通信

使い方pi.events拡張機能間でイベントを共有します。

送信側は誰がリッスンしているかを知る必要はなく、リッスン側もイベントがどこから来たかを知る必要はありません:

例

// 文件路径:~/.pi/agent/extensions/deploy-events.ts

// 扩展 A:发送事件
pi.events.emit("deploy:completed", {
  env: "production",
  timestamp: Date.now(),
});

// 拡張 B:イベントの監視(通常は別の拡張ファイルに書かれます)
pi.events.on("deploy:completed", (data) => {
  console.log(`部署完成:${data.env}`);
});

登録済みコマンドの取得

使い方pi.getCommands()現在のセッションで利用可能なすべてのコマンドを取得します。

以下の例では、拡張機能によって登録されたすべてのコマンドを一覧表示する /my-commands コマンドを登録します:

例

// 文件路径:~/.pi/agent/extensions/list-commands.ts

pi.registerCommand("my-commands", {
  description: "拡張機能が登録したすべてのコマンドを一覧表示",
  handler: async (args, ctx) => {
    const commands = pi.getCommands();

    // 按来源分类
    const extCommands = commands.filter(
      c => c.source === "extension"
    );
    const templates = commands.filter(
      c => c.source === "prompt"
    );
    const skills = commands.filter(
      c => c.source === "skill"
    );

    // 結果を表示して、計算するだけで出力しないことを避けます
    ctx.ui.notify(
`扩展命令 ${extCommands.length}个:`
        + extCommands.map(c => "/" + c.name).join("、"),
      "info"
    );
    console.table(commands);
  },
});
/my-commands
扩展命令 2 个:/stats、/deploy

各コマンドエントリには次のフィールドが含まれます:

フィールド型説明
namestringコマンド名。編集エリアで /name の形式で呼び出します。
descriptionstringコマンドの説明。自動補完リストに表示されます。
sourcestringソースタイプ:extension、prompt、skill など。
sourceInfoobject詳細なソースメタデータ。例えば、それを登録した拡張機能のパス。

動的ツール管理

実行時にツールの有効化と無効化を管理します。

典型的な用途は、書き込み操作ツールを一時的にオフにして、AI を1つのタスク内で読み取り専用にすることです:

例

// ファイルパス:~/.pi/agent/extensions/manage-tools.ts

// 現在有効なツールのリストを取得
const active = pi.getActiveTools();
// 例:["read", "bash", "edit", "write"]

// 登録済みのすべてのツールのメタデータを取得
const all = pi.getAllTools();

// 組み込みツールをフィルタリング
const builtinTools = all.filter(
  t => t.sourceInfo.source === "builtin"
);

// 拡張機能が登録したツールをフィルタリング
const extTools = all.filter(
  t => t.sourceInfo.source !== "builtin"
    && t.sourceInfo.source !== "sdk"
);

// カスタムツールを動的に有効化(既存ツールを保持)
pi.setActiveTools([...new Set([...active, "my_tool"])]);

// 読み取り専用モードに切り替え:読み取り系ツールのみを保持し、
// bash / edit / write を含めない。この状態では AI はコマンドを実行したりファイルを変更したりできない
pi.setActiveTools(["read", "grep", "find", "ls"]);

ここの setActiveTools はコマンドラインの--tools / --exclude-toolsパラメータと同じツールセットに対して作用します。

CLI パラメータは起動時の初期セットを決定し、setActiveTools は実行時に動的に調整します。両者は組み合わせて使用できます。

setActiveTools に渡す変更は増分的(additive)である必要があります。同じ呼び出し内で現在アクティブなツールを削除すると、遅延読み込みの最適化が失われます。

さらに、promptSnippet または promptGuidelines を持つツールをアクティブにするとシステムプロンプトが再構築され、モデルが遅延読み込みをサポートしている場合でも、キャッシュされたプロンプトプレフィックスが無効になる可能性があります。

その他の拡張機能