协议扩展与表单

当前版本提供玩家能力、实体属性、时间天气、游戏规则和配方目录接口，也提供 Python 协议模型的构造、编解码、观察与发送。先选领域接口；需要直接处理协议字段时再使用协议与数据包。

查询能力与授权

ctx.packets.catalog() 与 describe(packet_id) 返回包的 direction、protocol、support、requirements 等描述。当前协议模型覆盖 protocol 860 / 1.21.120。observable 表示适配器提供观察入口；读取和发送仍分别检查实际授权、当前连接及包 ID。

玩家能力、实体与环境

需求	入口	结果
读取或请求玩家能力	ctx.player_abilities.observe/request	读取 UpdateAbilities 缓存，或按有效引用提交能力请求。
读取实体属性	ctx.actors.observe、actor.observed	读取已观察的 metadata、effects、equipment、attributes。
读取时间、天气与规则	ctx.environment.observe、environment.observed	读取当前连接的环境快照和后续变化。

这些同步方法先返回意图，再通过 ctx.operations.execute(intent) 执行。玩家能力操作为 framework.player.abilities.observe/request；请求还需要 packet_send_ids: [185]、当前有效引用和写入权限。request 接受 permission_level=0..3 与 requested_permissions=0..255；引用必须来自真实观察。请求回执中的 dispatched 表示已经分发，能力值从后续观察中读取。

环境读取需要 framework.environment.observe：

async def read_environment(ctx, read_key, fixed_deadline):
    intent = ctx.environment.observe(
        idempotency_key=read_key, deadline=fixed_deadline,
    )
    return await ctx.operations.execute(intent)

成功回执中的环境快照包括 connection_id/epoch/revision，以及时间、维度、天气和游戏规则。字段带 known/value/source/revision；先检查 known 再使用 value，未知时的 false 或 0 只是占位值。after 可传之前的环境游标检查连续性，不会回放历史或刷新服务器。

actor.observed 与 environment.observed 订阅需要原生 gameEvents 来源，以及 event:actor.observed、event:environment.observed 授权。订阅权限与操作权限分别授予。连接或 epoch 变化后重新建立状态；缺口可以与部分已知字段同时存在。具体实体字段见实体，事件处理见事件。

配方目录与材料缺口

ctx.recipes 从当前连接收到的 CraftingData 读取配方：

入口	操作	用途
catalog(...)	framework.recipes.catalog	分页读取目录。
by_output(output, ...)	framework.recipes.by_output	按物品 ID 查询候选配方。
material_gaps(reference, crafts=1, ...)	framework.recipes.material_gaps	用配方引用与自身库存计算材料缺口。

async def find_recipes(ctx, output, read_key, fixed_deadline):
    intent = ctx.recipes.by_output(
        output, limit=20, idempotency_key=read_key, deadline=fixed_deadline,
    )
    return await ctx.operations.execute(intent)

目录每页 limit=1..100，默认 20；从第二页开始同时传首份结果的 connection_id/revision/registry_hash。配方引用包含这些字段和 recipe_id，只能用于对应连接与目录版本。recipe_id 不是合成操作的 recipe_network_id。

读取目录不会制作物品或刷新库存。库存未知或不完整时保留未知材料数。实际合成还需要解锁条件、工作站和服务端接受；当前 framework.craft.once 提供单次 2×2 合成，目录中也可出现其他类型的配方。

表单与 NPC 能做什么

Python 协议模型包含原生表单相关包，可按字段构造、编解码、观察和提交。按目标服务器的表单协议处理请求 ID、响应字段与取消状态；框架没有额外的表单会话管理或 Forms/NPC 专用回复助手。

ModalFormResponse（包 ID 101）也支持 lossless 包体编码。调用预览时使用 context="offline"、format="lossless"、packet_type="modal_form_response"；Optional 的缺席与已存在的 JSON null、false、0 会分别保留。ID 101 的 original_json 形式会被拒绝。

协议发送使用 framework.packet.send_protocol 和逐包授权，收到的动作回执保留服务器交互结果的实际状态。实体名称或 NPC 名称信息可通过实体观察读取；名称记录不包含表单会话。聊天菜单可直接组合聊天命令与文本通知。

处理读取与发送结果

缓存读取先检查连接、revision、字段已知标记及缺口。发送保存原意图与操作 ID，检查终态回执；unknown 或等待超时时按错误与结果核对处理，不更换幂等键自动重放。