robbin/grokbot-local-agent

Bot PC上のPi Agentを呼び出す

Pi はBot PCにインストールされたコマンドラインコーディングエージェントです。デフォルトモデルは DeepSeek Flash、思考レベルは high で、ファイルの読み書き、コマンドの実行、Web検索が可能です。詳細なインストールと設定はリポジトリ内の docs/setup-guide.md を参照してください。スクリプトは ~/tools/pi-call/（リポジトリの bin/ ディレクトリ）に配置されています。

使用量ポリシー

Bot自身のモデル使用量には制限がありますが、Pi はユーザー自身のモデルアカウント（デフォルトは DeepSeek）を使用するため、使用量はBotとは別に計算されます。そのため、重いタスクはデフォルトでPiに委譲し、Botはスケジューリングと最終確認のみを行います。

Pi に委譲するタスク：

• バッチファイル処理：ファイルの一括変更、データ整理、フォーマット変換。
• コーディング：スクリプト、ツール、テスト、デバッグ。
• 長文調査とWeb検索。
• 長文初稿：ドキュメント、レポート、記事の初版。
• ユーザーが明示的にPiに依頼する場合、第二意見を求める場合、または同一テーマでの比較を要求する場合。

Bot自身が行うタスク：

• 短い対話や1〜2ステップで回答できる質問。
• コネクタ操作（Gmail、X、GitHubなど）。Piはこれらのコネクタを持ちません。
• 送信、公開、プッシュ、デプロイ前の確認、およびユーザーへのレポート。

方法：

• 指示は簡潔に：目標、入力場所、出力ファイル、完了基準を数行で明確に記述します。元のテキストの長い部分をプロンプトに貼り付けず、Piにファイルを直接読ませます。
• 結果は直接ファイルに保存：プロンプト内で出力パスを指定し、Piにファイルを書き込ませます。Botは確認後、そのファイルをそのまま納品し、自分で書き直しません。修正が必要な場合は、同じセッションでPiに修正させます。
• 重要な結論を確実に定着させる：タスクから得られた重要な結論、決定、データは、Botが能動的に記憶や関連ドキュメントに書き込み、Piのセッション内にのみ残さないようにします。

手順

1. 作業ディレクトリを決定する：タスクの完了に必要なディレクトリのみをPiに渡します（リポジトリまたは /tmp/<タスク>）。/ やホームディレクトリ全体は渡さないでください。
2. セッション名を付ける：簡潔な英語のkebab-caseで、タスクごとに一意の名前を付けます（例：news-i18n）。同じタスクの修正には同じ名前を使用します。最初からやり直したい場合は新しい名前を使用します。
3. 出力場所を決める：適切な場所がない場合は /tmp/pi-out/<セッション名>/ を使用します。保存または同期が必要な成果物は、本来あるべき場所（対応するリポジトリ、ドキュメント、ノートのディレクトリ）に直接書き込みます。
4. プロンプトを書く：簡潔かつ完全に、目標、制約、出力ファイルパス、完了基準を記述し、最後にどのファイルを書き込んだかと一言の結論を報告させます。Piはチャット履歴を見ることができないため、必要な背景は1〜2文で説明し、長い資料はファイルパスで指定します。
5. 呼び出す。1〜2分以上かかるタスクは常に pi-task を使用します。これによりタスクIDが発行され、状態と進行状況が記録され、結果がファイルに保存されます。

   ~/tools/pi-call/pi-task run <作業ディレクトリ> "<プロンプト>" --session <セッション名> --owner <あなたのエージェントID> [--timeout 秒] [--no-write] [--no-web]
   

   --owner は必須です：これによりタスクを発行したBotが識別され、完了通知が適切なBotに届き、pending/ack による異なるBot間のタスク取得競合や誤ったackを防止します。指定しなくてもタスクは実行されますが（owner は null になり、stderr に警告が出力されます）、通知が返ってこなくなります。（環境変数 PI_TASK_OWNER でデフォルト値を指定することもできますが、明示的に渡す方が確実です。）自身のエージェントIDは自身のプロファイルパス（例：/home/box/agent-data/agents/<your-agent-id>/profile.json）にあります。 Shellツールのバックグラウンド実行機能を使用します（ブロッキングしません）。nohup、&、setsid は使用しないでください。出力の最初の行は TASK <タスクID> です。終了時にステータスと result.md のパスが出力されます。終了コード：0 成功、1 失敗、124 タイムアウト、130 キャンセル。 その他のサブコマンド：status <ID>（ステータス、owner、所要時間、最新のイベント）、log <ID> [-n 30]、list [--all] [--owner <id>|none]、cancel <ID>、pending [--owner <id>|none]（終了したがまだ報告されていないタスク）、ack <ID> [--owner <id>|none]（報告済みとしてマーク。ownerが一致しない場合は拒否、終了コード1）。 タスクデータは ~/.pi/tasks/<タスクID>/ に保存されます：status.json、events.jsonl、result.md、prompt-<n>.txt。Bot PCが再起動された場合、実行中のタスクは interrupted とマークされ、ユーザーに再実行するかどうか尋ねます。 完了通知： 環境変数 PI_NOTIFY_URL と PI_NOTIFY_SECRET が設定されている場合（Bot PCの環境変数として保存され、ファイルには書き込まれません）、pi-task はタスク完了時にこのWebhookに {source, id, owner, state, exit_code} を送信します（タスクの内容は含みません）。これを受信したルーチンタスクは、起動後に pending --owner <自分のid> を実行し、確認、報告、ack --owner <自分のid> を実行します。ownerが自分のタスクのみを処理します。他のBotのタスクは確認もackもせず、SendToAgent（priority true）でownerのBotに転送します。ルーチンタスク環境からメッセージを送信できない場合は、Bot本体に転送を依頼します。ownerなしのタスクはユーザーに通知するだけで、ackはしません。他のBotから転送され、ownerが自分のタスクは、自分で確認、報告し、ack します。設定がない場合は自動的にスキップされ、送信結果は events.jsonl の notify イベントに記録されます。PI_NOTIFY_OFF=1 を設定すると一時的に無効にできます。 セーフティネット報告： 完了通知が届かない可能性があります。そのため、起動時（ユーザーからのメッセージ、ルーチンタスクなど）にPiに委譲したタスクがある場合は、最初に pi-task pending --owner <自分のid> を実行し、自分のタスクのみを確認して、終了したが未報告のタスクを確認・納品し、その後 ack <ID> --owner <自分のid> を実行します。自分のタスクのみをackし、他の人のタスクは発行元のBotに任せます。 数十秒で完了する短いQ&Aは、フォアグラウンドで直接呼び出すこともできます。

   ~/tools/pi-call/pi-run <作業ディレクトリ> "<プロンプト>" --session <セッション名> [--timeout 秒]
   

   読み取り専用またはモデルを変更する必要がある場合は、低レベルスクリプトを使用します。

   ~/tools/pi-call/pi-call.mjs <作業ディレクトリ> deepseek/deepseek-flash "<プロンプト>" --thinking high [--allow-write] [--no-web] [--session <セッション名>] [--timeout 秒]
   

   pi-run と pi-call.mjs：標準出力にはPiの最後の応答のみが含まれます。デフォルトのタイムアウトは300秒です。終了コード：0 成功、1 エラー、124 タイムアウト、127 piが見つかりません。 権限：pi-task run および pi-run はデフォルトですべてのツール（読み取り、検索、コマンド実行、ファイル書き込み、Web検索）へのアクセスを許可します。pi-call.mjs は --allow-write なしの場合、読み取り専用ツールのみを使用できます。
6. 結果を確認する：Piの応答は単なるPiの主張です。git diff、テストの実行、またはファイルを直接読んで、実際に実行されたことを確認してからユーザーに伝えてください。未確認の結論を事実として伝えないでください。
7. 修正を続ける：pi-task のタスクは pi-task reply <タスクID> "<修正内容>" を使用します（同じセッション、同じディレクトリ、元のタスクのownerを引き継ぎます。タスクがまだ実行中の場合は拒否されます）。pi-run のタスクは同じ --session を指定してもう一度呼び出します。両方のセッションは別々に保存され、相互に引き継ぐことはできません。

ルール

• ユーザー自身のモデル使用量（Web検索はユーザー自身の検索サービスの使用量）を使用します。必要な場合のみ呼び出し、意味のない繰り返しや大量空実行は行いません。
• コードのプッシュ、デプロイ、DNSやオンラインサービスの変更、メッセージやメールの送信、重要なファイルの削除はPiに委譲しません。これらはBot自身が行い、事前にユーザーの同意を得ます。
• Piに ~/.pi/agent/auth.json、シークレットファイル、または環境変数内のキーを読み取らせたり出力させたりしないでください。
• 他人のタスクをackしない：pending/ack は常に --owner <自分のid> を指定します。ownerが一致しない場合は、発行元のBotにタスクを引き渡します。
• ユーザーに見える応答では「PiにXを実行させました」と述べ、何を確認したかを説明します。

トラブルシューティング

• pi: command not found：最初に export PATH=$HOME/.local/bin:$HOME/.node22/bin:$PATH を実行します。
• 利用可能なモデルがないというメッセージ：DeepSeekのログインが無効になっています。ユーザーがデスクトップターミナルで pi を実行し、/login で再ログインする必要があります。Botはユーザーに代わってログインできません。
• タイムアウト：タスクを分割するか、--timeout を増やします。
• エラーまたは結果が正しくない：終了コードと --verbose ログを最初に確認します。タスク自体が間違っている場合は、同じセッションで問題点を指摘してPiにやり直させます（最大1〜2回）。それでも解決しない場合は、Bot自身が引き継ぎ、Piが何をうまくできなかったかをユーザーに伝え、無駄な再実行を繰り返さないようにします。