技术细节

​

请求生命周期

1. 你运行 /mclawd ...、/mineclawd prompt ...，或在覆盖层输入栏提交请求。
2. MineClawd 校验 provider 配置和 OP 权限。
3. MineClawd 加载或创建当前激活的 Session 状态。
4. MineClawd 向 OpenAI 兼容端点或 Vertex 端点发送流式请求。
5. 流增量通过 AGENT_STREAM_EVENT 通道实时发送到客户端。覆盖层会用闪烁光标渲染每个增量。
6. 模型响应可触发工具调用。工具结果会回注到模型循环。
7. 最终 assistant 输出会渲染到聊天（和覆盖层），并保存 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
• 资产追踪：
  • list-assets
  • upsert-asset-record
  • remove-asset-record
• 网页搜索（需要 Tavily API key）：
  • search
• 模组信息：
  • 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 位小写 token。
• 命令 token 格式是 <id>-<title-slug>。
• Session 文件会分别保存 OpenAI 与 Vertex 历史。
• 每个拥有者的 active.json 存储当前激活 Session 指针。
• 首轮成功后，系统会用 summarize model 生成 Session 标题。

​

LLM 传输细节

• OpenAI 兼容请求路径：<endpoint>/chat/completions
• Vertex 请求路径：<endpoint>/<model>:generateContent?key=<api_key>
• 两条路径都使用 60 秒请求超时。
• 两条路径都支持函数式工具调用。
• 两条路径都支持流式。流增量会通过 AGENT_STREAM_EVENT 网络通道转发给客户端。

​

流式架构

​

动态占位符内部机制

• 容量：30 个物品槽、30 个方块槽、30 个流体槽。
• 固定 id 包括：
  • mineclawd:dynamic_item_001
  • mineclawd:dynamic_block_001
  • mineclawd:dynamic_fluid_001
• 状态同步使用 sync_dynamic_content 网络负载。
• 状态持久化使用世界 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

​

资产追踪内部机制

• 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 — 创建该资产的 Session
• createdAt、updatedAt — 时间戳

​

限制和计时器

​

安全模型

• 所有命令路径都受 OP 权限门控。
• KubeJS 执行是真实服务器执行，不是模拟。
• API key 必须按密钥处理。
• 仅在可信环境中使用。