参考手册Block

方块操作

方块操作工具是 AI 改造世界的核心。通过 5 个工具，AI 可以挖掘、放置、使用方块，以及执行批量区域操作。

工具列表

工具功能参数返回值
mine_block挖掘方块x, y, z, options(可选)挖掘结果
place_block放置方块x, y, z, block_name, facing(可选)放置结果
use_block使用方块x, y, z使用结果
area_operation区域批量操作mode, from, to, block_name(可选), radius(可选)操作结果
collect_block收集掉落物x, y, z, radius(可选)收集结果

工具详解

mine_block — 挖掘方块

挖掘指定坐标的方块，支持精准采集等选项。

{
  "tool": "mine_block",
  "params": { "x": 100, "y": 64, "z": 200 }
}

带精准采集选项：

{
  "tool": "mine_block",
  "params": {
    "x": 100, "y": 64, "z": 200,
    "options": { "silk_touch": true }
  }
}

place_block — 放置方块

在指定坐标放置方块，可指定朝向。

{
  "tool": "place_block",
  "params": { "x": 100, "y": 64, "z": 200, "block_name": "stone" }
}

指定朝向：

{
  "tool": "place_block",
  "params": { "x": 100, "y": 64, "z": 200, "block_name": "stone", "facing": "up" }
}

use_block — 使用方块

与可交互方块进行交互（如拉杆、按钮、门、工作台等）。

{
  "tool": "use_block",
  "params": { "x": 100, "y": 64, "z": 200 }
}

area_operation — 区域批量操作

在指定区域内执行批量操作，支持四种模式：

fill（填充） — 用指定方块填满区域：

{
  "tool": "area_operation",
  "params": {
    "mode": "fill",
    "from": { "x": 10, "y": 64, "z": 10 },
    "to": { "x": 15, "y": 65, "z": 15 },
    "block_name": "stone"
  }
}

clear（清除） — 清除区域内的所有方块：

{
  "tool": "area_operation",
  "params": {
    "mode": "clear",
    "from": { "x": 10, "y": 64, "z": 10 },
    "to": { "x": 15, "y": 65, "z": 15 }
  }
}

break（挖掘） — 挖掘区域内的所有方块并收集掉落：

{
  "tool": "area_operation",
  "params": {
    "mode": "break",
    "from": { "x": 10, "y": 64, "z": 10 },
    "to": { "x": 15, "y": 65, "z": 15 }
  }
}

vein（矿脉） — 使用 BFS 算法扫描并挖掘相连的同类型方块（如矿脉）：

{
  "tool": "area_operation",
  "params": {
    "mode": "vein",
    "from": { "x": 0, "y": 10, "z": 0 },
    "to": { "x": 15, "y": 20, "z": 15 },
    "radius": 5
  }
}

collect_block — 收集掉落物

收集指定位置附近的掉落物物品实体：

{
  "tool": "collect_block",
  "params": { "x": 100, "y": 64, "z": 200, "radius": 5 }
}

典型场景

搭建简易矿洞入口：

1. mine_block(x: 100, y: 65, z: 200) → 挖开门洞
2. place_block(x: 100, y: 64, z: 201, "door") → 放置门
3. place_block(x: 100, y: 65, z: 201, "torch") → 插火把

批量挖掘矿脉：

1. look_around(radius: 16, filter: {blocks: ["iron_ore"]})
   → 发现铁矿脉位置
2. area_operation(mode: "vein", from: {x:80,y:30,z:180}, to: {x:90,y:40,z:190}, radius: 5)
   → 批量挖掘铁矿脉

错误处理

场景错误码说明
方块不可破坏MINE_FAILED目标方块无法被挖掘（如基岩）
背包中无该方块PLACE_FAILED需要先收集目标方块
方块不可交互USE_FAILED目标方块不是可交互方块
区域参数无效AREA_OP_FAILED区域范围或 mode 无效
术语表Entity