> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baimoqilin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 技術詳細

> MineClawd のアーキテクチャ、保存形式、制限値、実行時内部仕様。

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

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`

## 保存レイアウト

```text theme={null}
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` ネットワークチャネルでクライアントに転送されます。

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

ストリームイベントは `AGENT_STREAM_EVENT` チャネルで送信され、内容は request ID、event type byte、payload string です。

| Event type          | Byte | Payload                              |
| ------------------- | ---- | ------------------------------------ |
| `START`             | `0`  | `sessionId` と `request` テキストを含む JSON |
| `DELTA`             | `1`  | LLM からのテキスト断片                        |
| `DONE`              | `2`  | 空                                    |
| `ERROR`             | `3`  | エラーメッセージ文字列                          |
| `TOOL_STATUS`       | `4`  | 現在呼び出し中のツール名                         |
| `TOOL_STATUS_CLEAR` | `5`  | 空（ツール状態インジケーターをクリア）                  |

オーバーレイはこれらイベントを受信し、差分を段階的に描画します。`DONE` または `ERROR` が到着するまで、最新テキストに点滅カーソルが追従します。生成中は `TOOL_STATUS` イベントが、MineClawd が呼び出しているツール名をアニメーション付きで表示します。`TOOL_STATUS_CLEAR` 到着時に表示が消えます。

アクティブリクエストはサーバー側の `ACTIVE_REQUESTS` と `ACTIVE_NETWORK_REQUESTS` マップで追跡されます。`/mineclawd stop` は request ID を `CANCELLED_REQUEST_IDS` に記録し、進行中 HTTP 接続を中断します。

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

* 容量: 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 は次の packet identifier を定義します。

* `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 追跡内部仕様

asset レコードは owner ごとに `mineclawd/assets/<owner>.json` に保存されます。各レコードには次が含まれます。

* `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` -- タイムスタンプ

システムプロンプトには asset 追跡付録が含まれるため、LLM は `upsert-asset-record` ツール呼び出しを通じて作成物を自動登録します。

## 制限とタイマー

| Setting or behavior                | Value                  |
| ---------------------------------- | ---------------------- |
| Tool call limit range              | `1` to `20`            |
| Default tool call limit value      | `16`                   |
| Tool call limit default state      | disabled               |
| Ask-user max options               | `5`                    |
| Ask-user timeout                   | `60` seconds           |
| Failed-request retry token TTL     | `30` minutes           |
| Rate-limit retry count             | `2` retries            |
| Rate-limit retry backoff           | `1500ms * retry_index` |
| History max entries for book build | `300`                  |
| Overlay input bar max length       | `600` characters       |
| Asset categories                   | `5`                    |

## セキュリティモデル

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