作者便利接口

用聊天命令接收玩家请求，用玩家句柄准备动作，再通过 Operations 提交和读取结果。下面的入口均包含在当前工具包中，完整参数见API 目录。

按任务选择入口

任务	入口	使用方式
注册中文命令、别名和参数范围	ctx.chat.command(...)	在 on_event 中显式调用 ctx.chat.dispatch(event)。
分发多类事件、等待玩家回复	ctx.events、ctx.chat_waiters	显式分发或喂入事件，处理完成后确认事件。
提交动作并等待结果	ctx.operations.execute(intent)	提交一次，返回原始终态回执。
执行命令、解析回应	ctx.commands.execute(...)、result(receipt)	查看状态、成功数和逐条服务器消息。
绑定玩家、准备常用动作	await ctx.player(...)、ctx.player_actions	从缓存名册解析身份，准备意图后显式提交。

这些 helper 可以在普通 Python 模块中组合，显式接收 ctx 并返回原始意图，无需增加新的 Host 动作。标题加声音、typed 字段解释以及可选 provider 的用法见用 Python 组合能力。

命令查询、常加载区和机器人控制分别使用 ctx.command_queries、ctx.tickingareas、ctx.control；机器人状态读取使用 await ctx.robot()。所有便利方法沿用对应操作的权限和回执，详见命令、移动与机器人。

中文命令与帮助信息

@ctx.chat.command(
    "帮助", aliases=("help",), description="查看插件用法",
    usage="!帮助 [主题]", min_args=0, max_args=1,
)
async def help_command(command):
    ctx.log.info("命令=%s，调用名=%s", command.name, command.invoked_as)
    await command.event.ack()

放在 on_start 内注册，再从 on_event 显式分发。name 返回规范命令名，invoked_as 保留实际输入的别名。list_commands() 返回注册顺序的帮助元数据；get_command(name) 接受规范名或别名；unregister(name) 一并移除别名。

元数据不会自动发送帮助文字。参数数目不匹配抛 ChatArgumentError，其中 command.usage 可用于显示用法；由插件决定回复与 ACK。完整事件处理结构见聊天命令路由。

玩家句柄与动作

async def prepare_reward(ctx, player_uuid, business_key, fixed_deadline):
    player = await ctx.player(uuid=player_uuid)
    return player.give(
        "minecraft:apple", count=1,
        idempotency_key=business_key, deadline=fixed_deadline,
    )

ctx.player 需要 permissions.players: ["list"]；give 需要 framework.command.execute。返回的 PlayerHandle 保存 name/uuid/xuid/session，提供 notify/title/subtitle/actionbar/position/score/set_score/add_score/reset_score/give。这些方法只准备意图或通知计划；对事件奖励，把意图加入事件事务，保存后查询其动作回执。

需要传送、效果、标签、音效等动作时使用 ctx.player_actions。句柄是一次身份快照，await player.refresh() 可重新核对原身份；身份变化抛 PlayerIdentityChanged，不会悄悄绑定另一个玩家。服务器命令执行时仍按姓名选择，详细约束见玩家。

一次提交与结果解析

async def run_list(ctx, business_key, fixed_deadline):
    receipt = await ctx.commands.execute(
        "list", idempotency_key=business_key, deadline=fixed_deadline,
    )
    result = ctx.commands.result(receipt)
    return {"state": result.state, "success": result.is_success,
            "messages": result.message_texts}

使用 framework.command.execute 权限。result() 只解析现有回执，不查询 Host；is_success 要求成功终态、服务器确认、正成功数、没有失败消息和部分效果。需要在发送前持久化时，先 prepare 并保存意图，再调用 ctx.operations.execute(intent)。事件中的业务状态与动作登记使用事务。

execute 不自动重试，超时或取消也不撤销动作。保留原意图、固定期限和操作 ID；unknown 按错误与恢复核对。

单次延迟任务

async def remind():
    ctx.log.info("延迟回调已执行")

ctx.later(5, remind, name="remind")

ctx.later(seconds, callback, *, name=None) 在非负有限秒数后调用一次无参数异步函数。它与 spawn/every 一样由 Worker 管理，停止或重载会取消并等待任务退出；跨重启的提醒应另行保存业务状态。回调异常会使插件失败，取消等待不会撤销已经提交的游戏动作。见生命周期。