> ## 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.

# Technische Details

> Architektur, Speicher, Limits und Laufzeit-Interna fuer MineClawd.

## Request-Lebenszyklus

1. Du fuehrst `/mclawd ...`, `/mineclawd prompt ...` aus oder tippst eine Anfrage in die Overlay-Eingabeleiste.
2. MineClawd prueft Provider-Konfiguration und OP-Zugriff.
3. MineClawd laedt oder erstellt den aktiven session-Zustand.
4. MineClawd sendet eine Streaming-Anfrage an den OpenAI-kompatiblen oder Vertex-Endpunkt.
5. Stream-Deltas werden ueber den Kanal `AGENT_STREAM_EVENT` in Echtzeit an den Client gesendet. Das Overlay rendert jedes Delta mit blinkendem Cursor.
6. Modellantworten koennen Tool-Aufrufe ausloesen. Tool-Ergebnisse werden in die Modell-Loop zurueckgefuehrt.
7. Die finale Assistant-Ausgabe wird im Chat (und Overlay) angezeigt und der Session-Verlauf wird gespeichert.

## Runtime-Toolfamilien

* Befehls- und Skriptausfuehrung:
  * `execute-command`
  * `apply-instant-server-script`
* Persistente Skriptdateien:
  * `list-server-scripts`
  * `read-server-script`
  * `write-server-script`
  * `delete-server-script`
  * `reload-game`
  * `sync-command-tree`
* Rueckfragen:
  * `ask-user-question`
* Asset-Tracking:
  * `list-assets`
  * `upsert-asset-record`
  * `remove-asset-record`
* Websuche (erfordert Tavily API-Key):
  * `search`
* Mod-Informationen:
  * `list_mods`
  * `list_commands`
  * `fetch_modrinth`
  * `fetch_url`
* Dynamische Placeholder (nur wenn aktiviert):
  * `list-dynamic-content`
  * `register-dynamic-item`
  * `register-dynamic-block`
  * `register-dynamic-fluid`
  * `update-dynamic-item`
  * `update-dynamic-block`
  * `update-dynamic-fluid`
  * `unregister-dynamic-content`

## Speicherlayout

```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-Interna

* Session-ID ist ein 4-stelliger Kleinbuchstaben-Token.
* Befehls-Token-Format ist `<id>-<title-slug>`.
* Session-Dateien speichern OpenAI- und Vertex-Verlaeufe getrennt.
* Der aktive Session-Zeiger wird pro owner in `active.json` gespeichert.
* Der Session-Titel wird nach der ersten erfolgreichen Runde mit dem summarize-Modell erzeugt.

## LLM-Transportdetails

* OpenAI-kompatibler Request-Pfad: `<endpoint>/chat/completions`
* Vertex-Request-Pfad: `<endpoint>/<model>:generateContent?key=<api_key>`
* Beide Pfade verwenden 60 Sekunden Request-Timeout.
* Beide Pfade unterstuetzen function-style Tool-Calling.
* Beide Pfade unterstuetzen Streaming. Stream-Deltas werden ueber den Netzwerkkanal `AGENT_STREAM_EVENT` an den Client weitergeleitet.

## Streaming-Architektur

Stream-Events verwenden den Kanal `AGENT_STREAM_EVENT` mit Request-ID, Event-Typ-Byte und Payload-String.

| Event-Typ           | Byte | Payload                                 |
| ------------------- | ---- | --------------------------------------- |
| `START`             | `0`  | JSON mit `sessionId` und `request`-Text |
| `DELTA`             | `1`  | Textfragment aus dem LLM                |
| `DONE`              | `2`  | Leer                                    |
| `ERROR`             | `3`  | Fehlermeldungs-String                   |
| `TOOL_STATUS`       | `4`  | Name des aktuell aufgerufenen Tools     |
| `TOOL_STATUS_CLEAR` | `5`  | Leer (loescht den Tool-Statusindikator) |

Das Overlay empfaengt diese Events und rendert Deltas inkrementell. Ein blinkender Cursor folgt dem neuesten Text, bis `DONE` oder `ERROR` eintrifft. Waehrend der Generierung zeigen `TOOL_STATUS`-Events einen animierten Indikator, welches Tool MineClawd gerade aufruft. Der Indikator wird bei `TOOL_STATUS_CLEAR` entfernt.

Aktive Requests werden serverseitig in `ACTIVE_REQUESTS`- und `ACTIVE_NETWORK_REQUESTS`-Maps verfolgt. Der Befehl `/mineclawd stop` markiert die Request-ID in `CANCELLED_REQUEST_IDS` und bricht laufende HTTP-Verbindungen ab.

## Dynamic Placeholder-Interna

* Kapazitaet: `30` Item-Slots, `30` Block-Slots, `30` Fluid-Slots.
* Feste IDs:
  * `mineclawd:dynamic_item_001`
  * `mineclawd:dynamic_block_001`
  * `mineclawd:dynamic_fluid_001`
* State-Sync verwendet `sync_dynamic_content` als Netzwerk-Payload.
* State-Persistenz verwendet die Welt-`PersistentState`-ID `mineclawd_dynamic_content`.
* `AUTO` aktiviert Runtime-Placeholder in Client-Runtimes und deaktiviert sie auf dedizierten Servern.

## Netzwerkkanaele

MineClawd definiert diese 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`

## Asset-Tracking-Interna

Asset-Eintraege werden pro owner in `mineclawd/assets/<owner>.json` gespeichert. Jeder Eintrag enthaelt:

* `id` - eindeutiger Identifier
* `category` - eine von `ENTITIES`, `ITEMS_BLOCKS_FLUIDS`, `SPECIAL_ITEMS`, `COMMANDS`, `GAME_MECHANICS`
* `name`, `summary`, `scriptPath`, `details`
* Kategorie-spezifische Felder: `contentId`, `specialItemId`, `specialItemNbt`, `command`, `entityUuid`, `entityDimension`, `entityX`, `entityY`, `entityZ`
* `sessionId` - die Session, die das Asset erstellt hat
* `createdAt`, `updatedAt` - Zeitstempel

Das Systemprompt enthaelt einen Asset-Tracking-Anhang, damit das LLM Kreationen automatisch ueber `upsert-asset-record`-Tool-Aufrufe katalogisiert.

## Limits und Timer

| Einstellung oder Verhalten            | Wert                   |
| ------------------------------------- | ---------------------- |
| Tool-Call-Limitbereich                | `1` bis `20`           |
| Standardwert Tool-Call-Limit          | `16`                   |
| Tool-Call-Limit Standardzustand       | deaktiviert            |
| Ask-user max Optionen                 | `5`                    |
| Ask-user Timeout                      | `60` Sekunden          |
| Failed-Request Retry-Token TTL        | `30` Minuten           |
| Rate-Limit Retry-Anzahl               | `2` Retries            |
| Rate-Limit Retry-Backoff              | `1500ms * retry_index` |
| History max Eintraege fuer Buchaufbau | `300`                  |
| Overlay-Eingabeleiste max Laenge      | `600` Zeichen          |
| Asset-Kategorien                      | `5`                    |

## Sicherheitsmodell

* Jeder Befehlspfad ist OP-geschuetzt.
* KubeJS-Ausfuehrung ist echte Serverausfuehrung, keine Simulation.
* API-Keys muessen als Geheimnisse behandelt werden.
* Nutze nur vertrauenswuerdige Umgebungen.