> ## 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 校验 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`

## 存储布局

```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 位小写 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` 网络通道转发给客户端。

## 流式架构

流事件使用 `AGENT_STREAM_EVENT` 通道，包含请求 ID、事件类型字节和负载字符串。

| 事件类型                | 字节  | 负载                                 |
| ------------------- | --- | ---------------------------------- |
| `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` 会把请求 ID 记入 `CANCELLED_REQUEST_IDS`，并取消正在进行的 HTTP 连接。

## 动态占位符内部机制

* 容量：`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 定义以下数据包标识符：

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

## 资产追踪内部机制

资产记录按拥有者存储在 `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` -- 创建该资产的 Session
* `createdAt`、`updatedAt` -- 时间戳

系统提示包含资产追踪附录，因此 LLM 会通过 `upsert-asset-record` 工具调用自动编目其创建内容。

## 限制和计时器

| 设置或行为            | 值                      |
| ---------------- | ---------------------- |
| 工具调用上限范围         | `1` 到 `20`             |
| 工具调用上限默认值        | `16`                   |
| 工具调用上限默认状态       | disabled               |
| ask-user 最大选项数   | `5`                    |
| ask-user 超时时间    | `60` 秒                 |
| 失败请求重试 token TTL | `30` 分钟                |
| 限流重试次数           | `2` 次                  |
| 限流重试退避           | `1500ms * retry_index` |
| 历史书构建的最大历史条数     | `300`                  |
| 覆盖层输入栏最大长度       | `600` 字符               |
| 资产类别数            | `5`                    |

## 安全模型

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