# 先选择请求类型

任务	API	结果
生成文本	tools.requestAIText	文本，可写入可写字符串/表格
生成属性变化	tools.requestAIPropertyChanges	受约束的属性变化流程
生成对象变化	tools.requestAIObjectChanges	受约束的对象变化流程
继续多轮会话	tools.sendAIAgentInput	智能体下一回合

不要为了一个固定数值判断调用 AI。普通规则应由脚本确定执行。

# 给 AI 的请求契约

根据玩家最近一次探索记录生成 80 字以内的摘要。
不得补充记录中没有的奖励或角色。
输出纯文本，不要 Markdown；写入可写动态字符串“探索摘要”。
失败时保留旧摘要并显示提示。

提示词应写明输入来源、输出格式、长度、禁止项和目标。不要让模型自己猜写回位置。

# 脚本实现

if (tools.session.summaryBusy) return;
tools.session.summaryBusy = true;

try {
  const text = await tools.requestAIText("总结最近一次探索，80字以内");
  if (typeof text !== "string" || !text.trim()) throw new Error("empty");
  player.setString("探索摘要", text.trim());
  tools.showToast(tools.tr("摘要已更新"), "success");
} catch {
  tools.showToast(tools.tr("生成失败，请稍后重试"), "error");
} finally {
  tools.session.summaryBusy = false;
}

也可以使用第二个参数 outbindproperty 写入目标，但目标必须是表格字段或允许修改且没有脚本的动态字符串。

# 不要重复提交

控件在请求期间应显示忙碌/禁用状态。tools.session 可作为当前运行会话锁；需要刷新后仍防重复时，使用玩家属性记录请求版本或结算标记。

# 属性与对象变化

模型只能在允许的项目状态范围内提出变化。高价值奖励、付费道具、排行和成就仍需脚本或后端做最终校验。AI 输出不能绕过玩家资源条件。

# 验收清单

• 请求类型与任务匹配，没有用 AI 替代固定规则。
• 输入、输出 schema、长度和写回目标明确。
• 重复点击只有一次有效请求。
• 空输出、超时、积分不足和网络失败不会覆盖旧状态。
• AI 返回内容不会作为脚本或可信 HTML 执行。

继续阅读：AI 智能体插件 和 AI 智能体脚本与 API。