Neomega

外观

单次合成与单块挖掘 ​

本页说明单次 2×2 合成、打包与挖掘动作。先用配方目录与材料缺口选择配方并检查材料，再按这里的输入范围准备动作。

ctx.crafting 只准备一次 2×2 合成，ctx.digging 只准备一个普通方块的挖掘尝试。二者都返回 OperationIntent：保存意图后通过 Operations 提交、查询或取消；不自动规划材料、寻找工具或移动机器人。

独立类分别为 neomega_runtime.crafting.Crafting(operations) 与 neomega_runtime.digging.BlockDigging(operations)，也可从 neomega_runtime 导入。操作权限为 framework.craft.once、framework.block.dig；清单声明之外还须管理员授权、世界写入门允许、机器人原生连接可用，并通过 Host 对实际发包的权限检查。

原生物品引用 ​

合成输入、输出及挖掘手持均使用这四个字段，大小写不可改：

字段来源与约束
ConnectionIDinventory.observe(0) 的原生 connection_id，不是 Host 会话 ID。
Slot原生槽记录的 slot；合成允许 0..35，挖掘手持仅快捷栏 0..8。
ObservedRevision槽记录的 observed_revision，必须为有效正修订号。
StackNetworkID槽记录的 stack_id；输入必须真实非空，输出要求明确空槽 0。

引用来自同连接的新鲜原生观察，不能从旧式 inventory.read() 缓存、ACK 数量或自己拼出的物品 JSON 推导。合成引用要求观察在 30 秒内；仍应在准备后尽快提交。重新连接或栈发生变化后重新观察。未知槽位不是空槽。

python
# snapshot、row 来自原生主背包观察；业务先验证已知状态及新鲜度。
item_ref = {
    "ConnectionID": snapshot["connection_id"],
    "Slot": row["slot"],
    "ObservedRevision": row["observed_revision"],
    "StackNetworkID": row["stack_id"],
}

一次 2×2 合成 ​

text
ctx.crafting.prepare(*, recipe_network_id, inputs, output, output_count,
                     idempotency_key, deadline) -> OperationIntent

参数全部必传，无默认值。SDK 构建 framework.craft.once 意图，由 Host 和服务端检查具体有效性。

参数要求
recipe_network_id当前连接真实 CraftingData 的配方网络 ID，正整数；不能拿其他连接 ID 或固定示例数字代用。
inputs1..4 个 {item, grid_slot, count}；item 为上面的原生引用，grid_slot: 0..3 为 2×2 行优先位置，count: 1..64。输入源槽互不重复且实际数量足够。
output独立于输入的已知空主背包槽引用。
output_count1..64，来自真实配方输出，不自行猜测。
idempotency_key, deadline本次业务动作的持久唯一标识与带时区的绝对截止时间。

一次只执行一个 recipe、一次合成。当前入口不提供配方发现、材料替代、批量规划、3×3 工作台或熔炉等生产窗口。Host 不凭一个整数证明配方来源；调用方必须先取得真实服务器配方资料，没有资料时应停止准备。

python
# recipe 来自本连接真实 CraftingData；prepared_inputs 与 empty_output_ref
# 均由本连接原生观察构造并通过业务检查，不使用硬编码配方 ID。
intent = ctx.crafting.prepare(
    recipe_network_id=recipe["recipe_network_id"],
    inputs=prepared_inputs,
    output=empty_output_ref,
    output_count=recipe["output_count"],
    idempotency_key=craft_key, deadline=deadline,
)
await save_intent(intent.payload())  # 业务持久化，同时保留配方与前置观察
operation_id = await ctx.operations.submit(intent)
await save_operation_id(operation_id)
receipt = await ctx.operations.wait(operation_id)

执行时打开一次普通背包，发送单条物品栈请求，再有界关窗。开窗引起同物品刷新时可接受新修订号，但完整物品、数量与 NBT 必须保持一致。succeeded/acknowledged 的结果为：

json
{"server_acknowledged": true, "independent_readback": false, "crafts": 1}

ACK 不能证明产物完整 NBT。合成后重新观察原生库存，检查材料减少、目标产物及其属性，再准备下一个动作。不要用 ACK 的数量构造假物品或新引用。

一次普通方块挖掘 ​

text
ctx.digging.prepare(*, position, face, duration_ms, held_item,
                    expected_block, idempotency_key, deadline) -> OperationIntent
参数要求
position三个整数的目标方块坐标；SDK 转成列表。
face方块面编号 0..5。
duration_ms50..10000 毫秒，仅为本次尝试持续时间，不自动计算硬度或保证破坏。
held_item, expected_block新鲜原生快捷栏引用，以及预期完整方块名称，例如 minecraft:stone。
idempotency_key, deadline本次动作的持久唯一标识与带时区绝对截止时间。

支持普通单格石头、圆石、泥土、草方块、常规木板、下界岩、砖块、混凝土、羊毛、玻璃和黑曜石。对应名称包括 stone、cobblestone、dirt、grass / grass_block、planks 及常规六种木板、netherrack、bricks / brick_block、concrete、wool、glass、obsidian；可带 minecraft: 命名空间。带方块实体、第二层非空气、重力、液体、配对和其他特殊方块会被拒绝。

开始前 Host 读回目标，要求距离不超过 6 格、位置 tick 落后不超过 40，并持续核对实际手持引用。结束前复查目标名称和状态，最后通过新的空气读回才能确认完成。它不自动找合适工具、不走近目标，也不保证工具能在指定时间内破坏该方块。

python
intent = ctx.digging.prepare(
    position=target_position, face=1, duration_ms=1000,
    held_item=held_item_ref, expected_block="minecraft:stone",
    idempotency_key=dig_key, deadline=deadline,
)
await save_intent(intent.payload())
operation_id = await ctx.operations.submit(intent)
await save_operation_id(operation_id)
receipt = await ctx.operations.wait(operation_id)

成功为 succeeded/verified，结果为：

json
{"block_air_observed": true, "drops_verified": false}

这个证据只证明目标格被新观察为空气，不证明一定是机器人独自破坏，也不证明掉落数量、归属或已捡入背包。需要掉落结果时另做相应观察。

失败、取消与未知结果 ​

回执原因含义
world_mode_unavailable / not_attached世界写入条件或原生连接不满足。
not_started未进入动作；检查参数、引用、目标及权限条件。
craft_rejected合成被服务端明确拒绝，证据为 acknowledged。
craft_lifecycle_uncertain合成开关窗口生命周期不确定，unknown 且需要恢复。
completion_unproven动作已进入，但错误、取消或读回不足使完成情况无法证明，unknown 且需要恢复。

对已提交动作调用 await ctx.operations.cancel(operation_id) 只能请求取消。挖掘取消和未完成退出会尝试中止；连接变化时不会把旧请求发给新连接。取消回执不等于旧效果已撤回。

保留原意图、key、操作 ID 和前置观察；等待超时、断线或 unknown 后先查原操作，再核对原生库存/方块，不得换 key 自动重试。详见错误与结果核对。这些接口说明的是当前工具包与 Host 合约，具体服务器的配方和挖掘速度仍需在目标环境验证。

Neomega · 使用、开发与参考文档