Zum Hauptinhalt springen

​
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

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-TypBytePayload
START0JSON mit sessionId und request-Text
DELTA1Textfragment aus dem LLM
DONE2Leer
ERROR3Fehlermeldungs-String
TOOL_STATUS4Name des aktuell aufgerufenen Tools
TOOL_STATUS_CLEAR5Leer (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 VerhaltenWert
Tool-Call-Limitbereich1 bis 20
Standardwert Tool-Call-Limit16
Tool-Call-Limit Standardzustanddeaktiviert
Ask-user max Optionen5
Ask-user Timeout60 Sekunden
Failed-Request Retry-Token TTL30 Minuten
Rate-Limit Retry-Anzahl2 Retries
Rate-Limit Retry-Backoff1500ms * retry_index
History max Eintraege fuer Buchaufbau300
Overlay-Eingabeleiste max Laenge600 Zeichen
Asset-Kategorien5

​
Sicherheitsmodell

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