_
有用的 JEV API 集成是围绕大型游戏系统的小型决策服务。游戏拥有权威世界，将其转化为紧凑状态，并创建现在合法的行为。 JEV 评估该有界问题；执行者验证答案并执行操作.
Game State -> Legal Actions -> Typed Question -> JEV -> Validate -> Execute or Fallback游戏状态 -> 可执行动作 -> Typed Question -> JEV -> Validate -> Execute or Fallback
1。设计紧凑
{ agentId: 'guard-07', healthRatio: 0.42, visibleThreats: 1, ammo: 3, stateVersion: 1842 }{ agentId: 'guard-07', healthRatio: 0.42, visibleThreats: 1, ammo: 3, stateVersion: 1842 }
2。定义 每个候选者都需要一个稳定的名称、显式参数、先决条件和执行所有者。例如：_takeCover(coverId)_、_attack(targetId)_，或holdPosition(locationId)。从权威国家建立清单；不要要求 JEV 发明 ID、路线、能力或参数。3。选择原语当应该选择一名候选人时使用Choice，当候选人需要排名时使用Score，当问题是一个门（例如是否放弃目标）时使用有界是或否判断。使用与问题匹配的最小原语.4。调用并验证
const result = await jev.decide({ state, legalActions, question: 'Protect the relay' }); const current = buildLegalActions(world, npc); if (!current.some(action => sameAction(action, result))) return 兜底策略(); return executor.run(result);
确切的 SDK 方法可能会有所不同。不变量不会：比较状态版本、重新验证参数以及拒绝不再合法的结果。当请求正在处理时，响应可能会变得过时。
5。处理信心
const result = await jev.decide({ state, legalActions, question: 'Protect the relay' }); const current = buildLegalActions(world, npc); if (!current.some(action => sameAction(action, result))) return fallback(); return executor.run(result);6。设置节奏和
调用有意义的事件或有限的战术计时器，而不是每个渲染帧。给每个请求一个期限。超时时，保持安全操作或使用特定于角色的 兜底策略，例如隐蔽、保持位置、跟随或编写行为树。除非明确取消和订购，否则限制每位代理人在飞行中做出一项决定。
7。测试合约
记录预计状态、可执行动作、响应、延迟、状态版本、验证结果、执行结果和 兜底策略 原因。重播生命值低、没有弹药、多重威胁、目标丢失、行动中断和服务失败。分别测量决策质量、延迟、无效结果率和 兜底策略 率。
设计请求合约
生产请求应携带模式版本、代理身份、状态版本、允许的状态投影、可执行动作、决策原语、目标、截止日期和相关 ID。保持目标简短而稳定。对代码和数据施加严格约束，而不是依赖一段指令。
{ schemaVersion: 'npc-decision-v1', agentId, stateVersion, state, legalActions, primitive: 'choice', deadlineMs, requestId }
设计响应合约
响应应标识所选候选者或 Score、观察到的状态版本、可用的置信度或概率以及提供者状态。将解释视为可选遥测，而不是执行字段。执行者应该能够在不解析散文的情况下验证操作。
{ schemaVersion: 'npc-decision-v1', agentId, stateVersion, state, legalActions, primitive: 'choice', deadlineMs, requestId }条件操作 超时忽略响应并使用特定于角色的 无效schema记录合约错误并失败已关闭陈旧版本放弃或重新验证当前操作设置提供商失败跳闸短暂退避并继续本地重复失败禁用代理和表面的远程决策遥测_
重播和可观察性
_保留足够的信息来重现决策：预计状态、可执行动作、问题架构、模型响应、时间戳、状态版本、验证结果、执行的命令、结果和 兜底策略 原因。编辑玩家数据和秘密。重播工具可让设计人员将新的提示或提供程序与相同的场景进行比较，而无需加载整个游戏。
| API 应停止的位置 | API 应该返回一个决定，而不是改变世界。将库存写入、损坏、移动权限和多人游戏状态更改保留在游戏服务器或引擎后面。此边界使重试更安全，并防止重复的请求两次应用游戏效果。 |
|---|---|
| 有关完整的 NPC 流程，请参阅 JEV 教程 | 。对于动作空间设计，请阅读 |
| JEV 。对于 Unity，请继续JEV Unity 教程 | . |
| Stale version | Discard or revalidate against the current action set |
| Provider failure | Trip a short backoff and continue locally |
| Repeated failure | Disable remote decisions for the agent and surface telemetry |
Replay and observability
Persist enough information to reproduce a decision: projected state, legal actions, question schema, model response, timestamps, state versions, validation result, executed command, outcome, and 兜底策略 reason. Redact player data and secrets. A replay harness lets designers compare a new prompt or provider against the same scenarios without loading the entire game.
Where the API should stop
The API should return a decision, not mutate the world. Keep inventory writes, damage, movement authority, and multiplayer state changes behind the game server or engine. This boundary makes retries safer and prevents a duplicated request from applying a gameplay effect twice.
For a full NPC flow, see JEV tutorial. For action-space design, read JEV legal actions. For Unity, continue to JEV Unity tutorial.
