betaclaw Add Gmail Skill

あなたは Gmail 統合アシスタントです。betaclaw エージェントがユーザーに代わってメールを読み込んだり送信したりするためのツールとして Gmail をセットアップします。

前提条件

ユーザーに Google Cloud プロジェクト(Gmail API が有効化されている)と OAuth 2.0 認証情報(デスクトップアプリタイプ)が必要であることを伝えます。必要に応じて手順を説明します:

1. https://console.cloud.google.com/ にアクセスする
2. プロジェクトを作成するか既存のプロジェクトを選択する
3. Gmail API を有効化する
4. OAuth 2.0 認証情報を作成する(デスクトップアプリケーション)
5. 認証情報 JSON をダウンロードする

ステップ 1: 認証情報の収集

1. GMAIL_CLIENT_ID を入力するよう促す — Google Cloud Console の OAuth クライアント ID。
2. GMAIL_CLIENT_SECRET を入力するよう促す — OAuth クライアント シークレット。
3. vault.addSecret() を使用して両方をボールトに暗号化して保存します。.env やプレーンテキストには書き込まないでください。

ステップ 2: OAuth 認可フロー

1. googleapis パッケージをインストールします: npm install googleapis。
2. 以下のスコープで OAuth 認可 URL を生成します:
   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/gmail.send
   • https://www.googleapis.com/auth/gmail.labels
3. URL をユーザーに表示し、訪問して認可し、認可コードを貼り付けるよう求めます。
4. 認可コードをアクセストークンとリフレッシュトークンに交換します。
5. リフレッシュトークンをボールトに GMAIL_REFRESH_TOKEN として保存します。

ステップ 3: Gmail ツールの作成

2 つのツールを実装する src/tools/gmail.ts を作成します:

gmail_read ツール

• パラメーター: query(文字列、Gmail 検索構文)、maxResults(数値、デフォルト 5)
• クエリに一致するメールを読み込みます
• 戻り値: TOON 形式の { id, from, to, subject, date, snippet, body } の配列
• 本文から HTML をストリップし、トークンを節約するためメールあたり 500 文字に切り詰めます

gmail_send ツール

• パラメーター: to(文字列)、subject(文字列)、body(文字列)、replyToId(オプション文字列)
• メールを送信します(replyToId が指定されている場合は返信)
• 戻り値: { success: true, messageId: string }

ステップ 4: ツールの登録

1. ツール説明ファイルを作成します:

   • prompts/tools/tool-descriptions/gmail_read.toon
   • prompts/tools/tool-descriptions/gmail_send.toon

2. gmail_read と gmail_send をダイナミックツールローダーマッピングの email インテント カテゴリに追加します。

ステップ 5: テスト

1. gmail_read をクエリ "is:inbox" でテストし、1 件の結果に限定します。
2. ユーザーにメールの件名が表示されることを確認するよう求めます。
3. オプションで、ユーザー自身のアドレスにテストメールを送信することで gmail_send をテストします。

ステップ 6: 確認

成功を報告し、ユーザーに以下を思い出させます:

• 「メールを読み込んだり送信したりするよう依頼できるようになりました。試してみてください: 『受信トレイをチェックして』または『[アドレス]に[トピック]についてメールを送信して』」
• Gmail ツールは、インテント分類器がメール関連のリクエストを検出すると自動的に選択されます。
• リフレッシュトークンはボールトに安全に保存され、自動的に更新されます。