AI 系统
AI 智能体脚本与调用 API
设计回合生命周期、输出写回、后悔与重置的一致状态事务。
AI 系统 · 运行时脚本
AI 回合是异步事务，不是一段随便生成的文本
一次 AI 智能体回合包含输入校验、请求、结构化输出、状态写回、失败恢复，以及后悔/重置。每个阶段必须有明确责任。
# 回合生命周期
输入需求判断
-> 输入前动作（扣费/记录）
-> AI 请求与流式输出
-> 最新输出写入目标字符串
-> 输出后动作（应用结果/特效）
-> 后悔或重置时补偿附加状态
需求脚本只判断。扣费和次数写入放在输入前动作；AI 输出已经写回后，输出后动作再读取结果并推进状态。
# 调用 API
| 方法 | 用途 |
|---|---|
tools.sendAIAgentInput(agent, message) |
给智能体发送自由输入 |
tools.chooseAIAgentOption(agent, choice) |
选择候选项 |
tools.undoAIAgentTurn(agent) |
后悔一回合 |
tools.resetAIAgentSession(agent) |
清空会话 |
tools.requestAIText(prompt, target?) |
单次文本请求 |
tools.requestAIPropertyChanges(prompt, target?) |
单次属性变化请求 |
tools.requestAIObjectChanges(prompt, target?) |
单次对象变化请求 |
旧名 sendAIGameMessage、triggerAIGameChoice、regretAIGame、resetAIGame 仅用于兼容。
# 一次安全的输入
if (tools.session.agentBusy) return;
if (player.getPro("体力") < 1) {
tools.showToast(tools.tr("体力不足"), "warning");
return;
}
tools.session.agentBusy = true;
player.addPro("体力", -1);
try {
await tools.sendAIAgentInput("向导", "继续探索");
} catch (error) {
player.addPro("体力", 1);
tools.showToast(tools.tr("请求失败，体力已返还"), "error");
} finally {
tools.session.agentBusy = false;
}
运行时会对相同请求做队列和去重，但玩法侧仍应提供忙碌状态和补偿规则。
# 输出写回目标
单次 AI API 的 outbindproperty 只能指向：
table_...表格字段；- 开启可写且没有脚本的动态字符串。
不要把 AI 输出直接当作脚本、HTML 模块或 Canvas 模块源码执行。先校验结构，再从动作脚本应用允许的字段。
# 后悔与重置
后悔只会回退智能体会话本身。输入前扣费、外部对象创建、成就或表格日志需要在对应后悔脚本里补偿。重置同理：列出会话外所有附加状态，并保证重复重置不会重复返还。
# 运行时限制
- 离线结算会跳过 AI 异步调用。
- Web/只读环境不能控制本地 AI 智能体。
- 输入受智能体长度限制。
- 智能体正在处理或已有脚本请求时，新请求会拒绝或排队。
- 匿名玩家、积分不足和网络失败都必须有玩家可见反馈。
# 验收清单
- 输入不足、请求成功、超时/失败和重复点击均有确定结果。
- 输出先写目标，再执行依赖输出的后处理。
- 后悔/重置同时处理会话外附加状态。
- AI 输出只作为数据，不作为可信源码。
- 存档刷新后会话相关状态与游戏状态一致。