bot-process-control について
bot-process-controlは、Gmail Commanderの運用担当者向けスキルです。Botやダイジェストの稼働場所、状態確認の方法、2つ目のポーラーを起動してはならない理由を説明します。
主な機能
- 01デプロイ済みプロセスの役割を説明
- 02作業前にローカルのポーラーを確認
- 03Telegramの/statusで状態を確認
- 04重複ポーリングを防止
- 05利用可能なTelegramコマンドを掲載
活用シーン
- 01デプロイ済みBotの応答確認
- 02競合するローカルポーラーの起動回避
- 03適切なエスカレーション先の確認
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/bot-process-controlを入力して読み込まれたか確認します。
同梱ファイルreferences/evolution-log.md
詳細
Bot プロセス制御
Gmail Commander ボットとスケジュールされたダイジェストの実行場所、正常に動作しているかの確認方法、ワークステーションで絶対に起動してはならないものについて説明します。
自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある、パラメーターが変わっている、または回避策が必要だった場合は、先送りせず、ただちにこのファイルを修正してください。実際に再現できる問題がある場合にのみ更新してください。
プロセスの実行場所
どちらのプロセスもワークステーションでは実行されません。どちらもプライベートリポジトリからデプロイされた、常時稼働の Mac mini 上にあるプライベートな Restate テナントで実行されます。
| サービス | 役割 |
|---|---|
GmailBot | Telegram の getUpdates チェーン（耐久性があり、自動的に再起動する単一のポーリング）を管理し、各更新をディスパッチします |
GmailBotChat | このプラグインの buildBot() が構築する grammY ボットで各更新を処理します。チャットごとに順序どおりに処理します |
GmailDigest | Telegram へのスケジュール済みメールダイジェストを 1 日に数回送信します（このプラグインとは別の独自の実装です） |
GmailAuth | デプロイ環境のシークレットストアに保管されたリフレッシュトークンから、必要に応じて Gmail アクセストークンを発行します |
起動、停止、再起動、デプロイ、ログの確認、シークレットのローテーション、OAuth の再同意はすべて、そのリポジトリの運用手順書に従って行います。 この公開スキルには、そのリポジトリのホスト名、デプロイコマンド、認証情報のパスを意図的に記載していません。そのリポジトリにアクセスできない場合は、作業を中止して運用担当者に問い合わせてください。
ラップトップの launchd ジョブ com.example.gmail-commander-bot と com.example.gmail-commander-digest は、2026-09-24 に廃止されました。それらの plist、ランチャースクリプト、または env ファイルを再作成しないでください。
必須の事前確認
手順 1：ローカルで何も実行されていないことを確認する（読み取り専用）
echo "=== Local gmail-commander launchd jobs (expected: none) ==="
launchctl list | grep -F gmail-commander || echo "none"
echo ""
echo "=== Local gmail-commander plists (expected: none) ==="
ls ~/Library/LaunchAgents 2>/dev/null | grep -F gmail-commander || echo "none"
echo ""
echo "=== Local standalone bot process (expected: none) ==="
pgrep -fl "gmail-commander/scripts/bot.ts" || echo "none"
いずれかのコマンドで何かが見つかった場合は、自分で読み込み、読み込み解除、または強制終了せず、運用担当者に報告してください。ローカルでポーリングするプロセスが動作していると、テナントと同じボットトークンを取り合うことになります。
手順 2：ユーザー側からデプロイ済みボットを確認する
デプロイへのアクセスが不要な唯一の確認方法は、Telegram のボットとのチャットで /status を送信することです。稼働時間とカウンターを含む応答があれば、GmailBotChat が更新を処理しています。1 分以内に応答がない場合は、ポーリングチェーンまたはテナントが停止しています。運用手順書に従ってエスカレーションしてください。
2 つ目のポーリングプロセスを起動しないでください
scripts/bot.ts には、import.meta.main で保護されたスタンドアロンのロングポーリング main() が残っています。そのため、buildBot() をインポートしてもポーリングは開始されません。本番ボットのトークンを使ってこれを実行しないでください。 Telegram では、1 つのトークンにつき getUpdates を利用できるのは 1 つのコンシューマーだけです。2 つ目を起動すると、Telegram は 409 Conflict を返し、両方のポーリングプロセスが不安定になります。また、テナントはこの競合を検知すると運用担当者にページを送ります。
スタンドアロンのエントリーポイントは、独自のボットトークンを使う、この公開プラグインの他のインストール向けに用意されています。このエントリーポイントは /tmp/gmail-commander-bot.pid に PID ロックを取得し、プラグインの CLAUDE.md に記載された環境変数を読み込みます。このプラグインでは、プロセススーパーバイザー用のテンプレートは提供されなくなりました。
Telegram コマンド
| コマンド | 説明 |
|---|---|
| /inbox | 最近の受信トレイのメールを表示します |
| /search | メールを検索します（Gmail クエリ構文） |
| /read | ID を指定してメールを読みます |
| /compose | 新しいメールを作成します |
| /reply | メールに返信します |
| /abort | 現在の作成／返信操作をキャンセルします |
| /drafts | 下書きメールの一覧を表示します |
| /digest | 直近 N 時間分を今すぐトリアージします（デフォルトは 6 時間） |
| /status | ボットのステータスと統計情報を表示します |
| /help | すべてのコマンドを表示します |
注：
/abortは、進行中の作成または返信セッションをキャンセルします。フローのどの段階でも使用できます。
デプロイでの OAuth エラー
Google がデプロイの更新トークン（invalid_grant）を拒否すると、GmailAuth が担当者に通知します。復旧には、ワークステーションでのブラウザーによる同意とデプロイでのシークレットの更新が必要で、どちらも非公開のランブックに記載されています。ワークステーションでの CLI 独自の invalid_grant 復旧は別のトークンを対象としており、gmail-access で説明しています。
変更後のチェックリスト
- YAML frontmatter が有効（説明にコロンがない）
- トリガーキーワードが最新
- パスパターンでハードコードされたパスではなく $HOME を使用
- launchd テンプレート、ホスト名、認証情報のパスを再導入していない
- プラグインの CLAUDE.md にある
buildBot()の契約がscripts/bot.tsと一致している
実行後の振り返り
このスキルの完了後、タスクを終了する前に振り返ってください。
- 自分の場所を特定する。 — 編集する前に、この SKILL.md の正規パスを確認します。
- 何が失敗したか。 — 原因となった指示を修正します。
- 予想以上にうまくいったことは何か。 — 推奨プラクティスに取り入れます。
- 何が現状とずれていたか。 — 実態と合わなくなったスクリプト、参照先、依存関係を修正します。
- 記録する。 — トリガー、修正、根拠を含む進化ログのエントリーを残します。
先送りしてはいけません。次回の呼び出しでは、ここに残した内容が引き継がれます。