技術詳細

​

リクエストのライフサイクル

1. /mclawd ...、/mineclawd prompt ... を実行するか、オーバーレイ入力バーでリクエストを送信します。
2. MineClawd がプロバイダー設定と OP 権限を検証します。
3. MineClawd がアクティブ Session 状態を読み込むか新規作成します。
4. MineClawd が OpenAI 互換または Vertex エンドポイントへストリーミングリクエストを送信します。
5. ストリーム差分は AGENT_STREAM_EVENT チャネル経由でクライアントへリアルタイム送信されます。オーバーレイは点滅カーソル付きで各差分を描画します。
6. モデル応答はツール呼び出しを発生させる場合があります。ツール結果はモデルループへ返されます。
7. 最終アシスタント出力がチャット（およびオーバーレイ）に表示され、Session 履歴が保存されます。

​

実行時ツールファミリー

• コマンドとスクリプト実行:
  • execute-command
  • apply-instant-server-script
• 永続スクリプトファイル:
  • list-server-scripts
  • read-server-script
  • write-server-script
  • delete-server-script
  • reload-game
  • sync-command-tree
• 確認質問:
  • ask-user-question
• assets 追跡:
  • list-assets
  • upsert-asset-record
  • remove-asset-record
• Web 検索（Tavily API キーが必要）:
  • search
• Mod 情報:
  • list_mods
  • list_commands
  • fetch_modrinth
  • fetch_url
• 動的プレースホルダー（有効時のみ）:
  • list-dynamic-content
  • register-dynamic-item
  • register-dynamic-block
  • register-dynamic-fluid
  • update-dynamic-item
  • update-dynamic-block
  • update-dynamic-fluid
  • unregister-dynamic-content

​

保存レイアウト

gameDir/
  config/
    mineclawd.json5
  mineclawd/
    player-settings.json
    sessions/
      <owner>/
        active.json
        <id>.json
    assets/
      <owner>.json
    souls/
      default.md
      yuki.md
      <custom>.md
      .active/
        <owner>.txt
  kubejs/
    server_scripts/
      mineclawd/
        ...

​

Session 内部仕様

• Session ID は 4 文字の小文字トークンです。
• コマンドトークン形式は <id>-<title-slug> です。
• Session ファイルは OpenAI と Vertex の履歴を別々に保持します。
• owner ごとのアクティブ Session ポインターは active.json に保存されます。
• Session タイトルは、最初の成功ラウンド後に summarize モデルで生成されます。

​

LLM 転送詳細

• OpenAI 互換リクエストパス: <endpoint>/chat/completions
• Vertex リクエストパス: <endpoint>/<model>:generateContent?key=<api_key>
• 両パスともリクエストタイムアウトは 60 秒です。
• 両パスとも function-style のツール呼び出しをサポートします。
• 両パスともストリーミングをサポートします。ストリーム差分は AGENT_STREAM_EVENT ネットワークチャネルでクライアントに転送されます。

​

ストリーミングアーキテクチャ

​

動的プレースホルダー内部仕様

• 容量: item スロット 30、block スロット 30、fluid スロット 30。
• 固定 ID 例:
  • mineclawd:dynamic_item_001
  • mineclawd:dynamic_block_001
  • mineclawd:dynamic_fluid_001
• 状態同期は sync_dynamic_content ネットワーク payload を使います。
• 状態永続化は world PersistentState ID mineclawd_dynamic_content を使います。
• AUTO モードは、クライアント実行時に実行時プレースホルダーを有効化し、専用サーバーでは無効化します。

​

ネットワークチャネル

• mineclawd:client_ready
• mineclawd:client_gui_pref
• mineclawd:open_config
• mineclawd:sync_broadcast_target
• mineclawd:sync_assistive_touch
• mineclawd:sync_dynamic_content
• mineclawd:open_question
• mineclawd:question_response
• mineclawd:open_sessions
• mineclawd:open_assets
• mineclawd:open_history_book
• mineclawd:agent_stream_event

​

assets 追跡内部仕様

• id — 一意識別子
• category — ENTITIES、ITEMS_BLOCKS_FLUIDS、SPECIAL_ITEMS、COMMANDS、GAME_MECHANICS のいずれか
• name、summary、scriptPath、details
• カテゴリ固有フィールド: contentId、specialItemId、specialItemNbt、command、entityUuid、entityDimension、entityX、entityY、entityZ
• sessionId — その asset を作成した Session
• createdAt、updatedAt — タイムスタンプ

​

制限とタイマー

​

セキュリティモデル

• すべてのコマンド経路は OP 権限で保護されています。
• KubeJS 実行はシミュレーションではなく、実サーバー実行です。
• API キーは秘密情報として扱う必要があります。
• 信頼できる環境でのみ利用してください。