工作模式适配
约 803 字大约 3 分钟
2026-04-07
IMaidTask 接口中有两个与 AI 聊天相关的方法,让工作模式可以更好地与 AI 的 Function Call 机制协作。
如果你的附属提供了自定义工作模式,建议根据实际情况实现这两个方法。
一、getMaidActionSummary()
@ApiStatus.AvailableSince("1.5.1")
default String getMaidActionSummary() {
return getUid().getPath();
}getMaidActionSummary() 返回一段对当前工作模式的英文摘要说明,用于构建 switch_work_task Tool 的参数描述。
当模型收到可用工作模式列表时,列表中每个模式会附带一行说明:
- mymod:my_task: A short summary describing what this task does and when to use it为什么需要覆写?
默认实现只返回 getUid().getPath()(即 ResourceLocation 的路径部分),例如 my_task。仅靠名称,模型往往无法判断这个任务的实际用途,可能会在不恰当的时机触发。
覆写后,可以明确告诉模型:
- 这个任务做什么
- 什么情况下应该切换到这个任务
- 有哪些前置条件或限制
写法建议
@Override
public String getMaidActionSummary() {
// 用英文,简洁清晰地描述任务用途和触发条件
return """
Mine ores and stone in a designated area.
Requires a pickaxe in main hand.""";
}提示
摘要应该面向模型而不是面向玩家,不需要翻译成中文,也不需要华丽的描述——清晰、准确即可。
二、onFunctionCallSwitch()
@ApiStatus.AvailableSince("1.4.7")
default FunctionCallSwitchResult onFunctionCallSwitch(EntityMaid maid) {
return FunctionCallSwitchResult.OK;
}onFunctionCallSwitch() 在模型通过 switch_work_task Tool 切换到此任务时被触发。
默认实现直接返回 OK,不做任何处理。如果你的任务需要特定的物品或前置条件,可以在这里检查并尝试自动准备。
返回值说明
| 枚举值 | 含义 | 模型收到的结果 |
|---|---|---|
OK | 切换成功,一切就绪 | Switched to task <id> |
NO_CHANGE | 已处于该任务,无需变更 | Already on task <id> |
MISSING_REQUIRED_ITEM | 已切换,但缺少关键物品 | Switched to task <id>, but a required item is missing |
PARTIAL_OK | 切换完成但仅部分满足条件 | Switched to task <id>, but some requirements are missing |
示例:检查主手是否有合适的工具
@Override
public FunctionCallSwitchResult onFunctionCallSwitch(EntityMaid maid) {
// 检查主手是否有镐子
ItemStack mainHand = maid.getMainHandItem();
if (!mainHand.isEmpty() && mainHand.getItem() instanceof PickaxeItem) {
return FunctionCallSwitchResult.OK;
}
// 尝试从背包中找到镐子并装备
for (int i = 0; i < maid.getAvailableSlots(SlotType.HAND).size(); i++) {
ItemStack stack = maid.getItemBySlot(EquipmentSlot.MAINHAND);
// ... 背包搜索逻辑 ...
}
// 找不到合适的工具
return FunctionCallSwitchResult.MISSING_REQUIRED_ITEM;
}注意
onFunctionCallSwitch() 在服务端被调用,执行逻辑时请不要修改客户端状态,也不要做耗时操作。这个钩子是同步的,会直接影响对话回复的延迟。
三、完整示例
下面是一个综合了两个方法的自定义工作模式片段:
public class MiningTask implements IMaidTask {
@Override
public ResourceLocation getUid() {
return new ResourceLocation("mymod", "mining");
}
// ... 其他必要方法 ...
@Override
public String getMaidActionSummary() {
return "Mine ores and stone blocks in a defined area. "
+ "Requires a pickaxe in main hand to work. "
+ "Use this when the user wants the maid to dig or mine.";
}
@Override
public FunctionCallSwitchResult onFunctionCallSwitch(EntityMaid maid) {
ItemStack mainHand = maid.getMainHandItem();
if (isPickaxe(mainHand)) {
return FunctionCallSwitchResult.OK;
}
// 尝试从背包找镐子
boolean found = tryEquipPickaxeFromInventory(maid);
if (found) {
return FunctionCallSwitchResult.OK;
}
return FunctionCallSwitchResult.MISSING_REQUIRED_ITEM;
}
private boolean isPickaxe(ItemStack stack) {
return !stack.isEmpty() && stack.getItem() instanceof PickaxeItem;
}
private boolean tryEquipPickaxeFromInventory(EntityMaid maid) {
// 实现背包搜索逻辑...
return false;
}
}