bot/docs/development-guide.md

ai.bot 開発ガイド

プロジェクト概要

ai.botは、Rust製のBluesky（AT Protocol）ボットです。メンション応答、コマンド実行、OpenAI統合などの機能を提供します。

重要: 2025年6月6日より、パッケージ名とCLI名が統一されました：

• 新CLI名: aibot (推奨)
• 旧CLI名: ai (互換性維持)
• 設定ディレクトリ: ~/.config/syui/ai/bot/ (旧: ~/.config/ai/)

詳細は移行ガイドを参照してください。

アーキテクチャ

主要コンポーネント

1. HTTPクライアント (src/http_client.rs)

   • AT Protocol API呼び出しの統一インターフェース
   • 認証処理の自動化
   • エラーハンドリングの標準化

2. コマンドシステム (src/main.rs)

   • Seahorseを使用したCLIインターフェース
   • 各機能への振り分け

3. AT Protocolモジュール

   • 投稿、フォロー、いいね等の基本機能
   • 認証・セッション管理
   • フィード・通知処理

4. ゲームシステム (src/game/)

   • カードゲーム機能
   • ユーザー管理
   • ゲームデータ処理

5. 外部連携

   • OpenAI API統合 (src/openai.rs)
   • 画像処理機能

開発環境セットアップ

必要なツール

# Rust（最新安定版）
rustup update stable

# Cargo make（タスクランナー）
cargo install cargo-make

# 開発用依存関係は自動インストール

注意: 初回はcargo install cargo-makeでcargo-makeのインストールが必要です。

設定ファイル

~/.config/syui/ai/bot/config.toml  # 基本設定
~/.config/syui/ai/bot/refresh      # リフレッシュトークン  
~/.config/syui/ai/bot/access      # アクセストークン

注意: 旧設定ディレクトリ（~/.config/ai/）も自動的に参照・移行されます。

開発ワークフロー

1. コード変更

# フォーマット
cargo fmt

# コンパイル確認
cargo check

# テスト実行
cargo test

2. 統合ワークフロー

# 全体フロー（フォーマット→ビルド→テスト）
cargo make my-flow

3. 個別テスト

cargo make test-quick      # 素早いテスト
cargo make test-verbose    # 詳細出力テスト

API呼び出しパターン

HttpClientの使用方法

基本的なGETリクエスト

use crate::http_client::HttpClient;

pub async fn get_user_profile(handle: String) -> String {
    let client = HttpClient::new();
    let url = format!("https://bsky.social/xrpc/app.bsky.actor.getProfile?actor={}", handle);
    
    match client.get_with_auth(&url).await {
        Ok(response) => response,
        Err(e) => {
            eprintln!("Error getting profile: {}", e);
            "err".to_string()
        }
    }
}

JSONを送信するPOSTリクエスト

use crate::http_client::HttpClient;
use serde_json::json;

pub async fn create_post(text: String) -> String {
    let client = HttpClient::new();
    let url = "https://bsky.social/xrpc/com.atproto.repo.createRecord";
    
    let payload = json!({
        "repo": "user.handle",
        "collection": "app.bsky.feed.post",
        "record": {
            "text": text,
            "createdAt": chrono::Utc::now().to_rfc3339()
        }
    });
    
    match client.post_json_with_auth(&url, &payload).await {
        Ok(response) => response,
        Err(e) => {
            eprintln!("Error creating post: {}", e);
            "err".to_string()
        }
    }
}

テストの書き方

ユニットテスト

#[cfg(test)]
mod tests {
    use super::*;
    
    #[tokio::test]
    async fn test_http_client_creation() {
        let client = HttpClient::new();
        // テストロジック
    }
    
    #[test]
    fn test_data_parsing() {
        // 同期テスト
    }
}

統合テスト

#[tokio::test]
#[ignore] // 通常は無視、環境変数設定時のみ実行
async fn test_real_api() {
    if std::env::var("RUN_INTEGRATION_TESTS").is_ok() {
        // 実際のAPI呼び出しテスト
    }
}

エラーハンドリングガイドライン

推奨パターン

// Good: 適切なエラーハンドリング
match api_call().await {
    Ok(response) => response,
    Err(e) => {
        eprintln!("Error in operation: {}", e);
        "err".to_string()
    }
}

// Bad: unwrapの使用
api_call().await.unwrap()

エラーレスポンス

• API呼び出し失敗時は"err"文字列を返す
• ログにエラー詳細を出力
• 上位レイヤーでエラー処理を継続

新機能追加の手順

1. AT Protocol関連機能

# 1. モジュールファイルを作成
touch src/new_feature.rs

# 2. main.rsに追加
# pub mod new_feature;

# 3. HttpClientを使用して実装
# 4. テストを追加
# 5. main.rsのコマンドに追加

2. 基本的なテンプレート

use crate::http_client::HttpClient;
use crate::{data_toml, url};
use serde_json::json;

pub async fn new_feature_request(param: String) -> String {
    let client = HttpClient::new();
    let endpoint_url = url(&"endpoint_name");
    
    let payload = json!({
        "param": param
    });
    
    match client.post_json_with_auth(&endpoint_url, &payload).await {
        Ok(response) => response,
        Err(e) => {
            eprintln!("Error in new_feature: {}", e);
            "err".to_string()
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    
    #[tokio::test]
    async fn test_new_feature() {
        // テスト実装
    }
}

デバッグ方法

1. ログ出力

eprintln!("Debug: {}", variable);
println!("Info: {}", message);

2. テスト実行

# 特定のテストのみ
cargo test test_name

# 詳細出力
cargo test -- --nocapture

# 特定モジュール
cargo test module_name

3. HTTPリクエストのデバッグ

HttpClientモジュール内でリクエスト/レスポンスをログ出力することで、API呼び出しの詳細を確認できます。

パフォーマンス考慮事項

HttpClientの再利用

// Good: 一度作成して再利用
let client = HttpClient::new();
for item in items {
    client.get_with_auth(&url).await;
}

// Bad: 毎回新規作成
for item in items {
    let client = HttpClient::new();
    client.get_with_auth(&url).await;
}

非同期処理

• 可能な限り並列処理を活用
• await呼び出しを最小限に
• tokio::joinやfutures::join_allの活用

トラブルシューティング

よくある問題

1. 認証エラー

   • トークンの有効期限切れ
   • 設定ファイルの不備

2. コンパイルエラー

   • 型不整合（特にライフタイム）
   • 未使用のimport

3. 実行時エラー

   • ネットワーク接続問題
   • API仕様変更

解決方法

# 設定確認（新ディレクトリ）
ls -la ~/.config/syui/ai/bot/
# 旧ディレクトリも確認
ls -la ~/.config/ai/

# トークンリフレッシュ
./target/debug/aibot refresh
# または互換性コマンド
./target/debug/ai refresh

# 詳細ログ
RUST_LOG=debug ./target/debug/aibot [command]

コントリビューション

1. コードフォーマット必須: cargo fmt
2. テスト追加必須: 新機能には対応テスト
3. エラーハンドリング必須: .unwrap()の使用禁止
4. ドキュメント更新: 重要な変更は本ドキュメントも更新

関連ドキュメント

• リファクタリングサマリー
• AT Protocol仕様
• Rust公式ドキュメント