Detalles técnicos

​

Ciclo de vida de solicitudes

1. Ejecutas /mclawd ..., /mineclawd prompt ... o escribes una solicitud en la barra de entrada de la superposición.
2. MineClawd valida la configuración del proveedor y el acceso OP.
3. MineClawd carga o crea el estado de Session activa.
4. MineClawd envía una solicitud en streaming al endpoint compatible con OpenAI o Vertex.
5. Los deltas de streaming se envían al cliente en tiempo real por el canal AGENT_STREAM_EVENT. La superposición renderiza cada delta con cursor parpadeante.
6. Las respuestas del modelo pueden activar llamadas de herramientas. Los resultados de las herramientas se vuelven a inyectar en el ciclo del modelo.
7. La salida final del asistente se muestra en chat (y en la superposición) y se guarda el historial de Session.

​

Familias de herramientas de runtime

• Ejecución de comandos y scripts:
  • execute-command
  • apply-instant-server-script
• Archivos de script persistentes:
  • list-server-scripts
  • read-server-script
  • write-server-script
  • delete-server-script
  • reload-game
  • sync-command-tree
• Aclaración:
  • ask-user-question
• Seguimiento de assets:
  • list-assets
  • upsert-asset-record
  • remove-asset-record
• Búsqueda web (requiere Tavily API key):
  • search
• Información de mods:
  • list_mods
  • list_commands
  • fetch_modrinth
  • fetch_url
• Placeholders dinámicos (solo cuando están habilitados):
  • list-dynamic-content
  • register-dynamic-item
  • register-dynamic-block
  • register-dynamic-fluid
  • update-dynamic-item
  • update-dynamic-block
  • update-dynamic-fluid
  • unregister-dynamic-content

​

Estructura de almacenamiento

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

​

Internals de Session

• El id de Session es un token de 4 caracteres en minúsculas.
• El formato del token de comando es <id>-<title-slug>.
• El archivo de Session guarda historiales de OpenAI y Vertex por separado.
• El puntero de Session activa se guarda en active.json por propietario.
• El título de Session se genera después de la primera ronda exitosa con el modelo de resumen.

​

Detalles de transporte LLM

• Ruta de solicitud compatible con OpenAI: <endpoint>/chat/completions
• Ruta de solicitud Vertex: <endpoint>/<model>:generateContent?key=<api_key>
• Ambas rutas usan timeout de solicitud de 60 segundos.
• Ambas rutas soportan llamadas de herramientas tipo función.
• Ambas rutas soportan streaming. Los deltas se reenvían al cliente por el canal de red AGENT_STREAM_EVENT.

​

Arquitectura de streaming

​

Internals de placeholders dinámicos

• Capacidad: 30 slots de item, 30 slots de block, 30 slots de fluid.
• IDs fijos incluyen:
  • mineclawd:dynamic_item_001
  • mineclawd:dynamic_block_001
  • mineclawd:dynamic_fluid_001
• La sincronización de estado usa payload de red sync_dynamic_content.
• La persistencia de estado usa PersistentState del mundo con id mineclawd_dynamic_content.
• El modo AUTO habilita placeholders de runtime en cliente y los deshabilita en servidores dedicados.

​

Canales de red

• 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

​

Internals de seguimiento de assets

• id — identificador único
• category — una de ENTITIES, ITEMS_BLOCKS_FLUIDS, SPECIAL_ITEMS, COMMANDS, GAME_MECHANICS
• name, summary, scriptPath, details
• Campos por categoría: contentId, specialItemId, specialItemNbt, command, entityUuid, entityDimension, entityX, entityY, entityZ
• sessionId — la Session que creó el asset
• createdAt, updatedAt — marcas de tiempo

​

Límites y temporizadores

​

Modelo de seguridad

• Todas las rutas de comando están protegidas por OP.
• La ejecución de KubeJS es ejecución real de servidor, no simulación.
• Las API keys deben tratarse como secretos.
• Usa solo entornos de confianza.