Skip to main content

游戏数值工具系统设计

独立数值工具保留确定性计算和输入隔离。旧 Run Action、Worker Profile、岗位编排、终态信封和运行手册退役，不继续通过 run_id 执行。当前服务接线必须由 owning 项目单独配置，不能从包存在推断自动执行就绪。

数值数据模型​

game.numeric-model.v1 是工具间唯一计算合同：

  • 参数：稳定 ID、数值、单位、可调性、上下界、来源定位；
  • 公式：表达式、显式输入、输出 ID 和单位；
  • 指标与硬约束：目标区间及 minimum/maximum/equal 规则；
  • 经济流与容量：资源、source/sink、周期、流入/流出与容量；
  • 成长与概率：离散成长点、成本、权重、价值和保底阈值；
  • 来源：内容寻址 source_ref，模型自身再生成 model_ref。

表达式引擎不执行 JavaScript。它只支持数字、已声明标识符、算术/比较/逻辑运算和受限函数 min/max/abs/floor/ceil/round/pow/log/exp/if。除零、非有限结果、未知标识符和依赖循环均为显式错误。

状态、并发与生命周期​

  • source/model store 是进程内、内容寻址、不可枚举的有界 LRU；最多保留 128 项。
  • 相同内容复用相同 ref；ref 无更新操作，因此不存在并发覆盖。
  • DSH 重启后 ref 失效。调用方必须从权威来源重新扫描和编译，不能将 ref 当长期存储。
  • 单个场景有明确 horizon；候选最多 50 个，来源大小、单元格、行列数和 JSON 深度均有上限。
  • 工具异常返回结构化失败，不修改输入模型，也不产生外部副作用。

Wire-level 合同​

能力工具统一返回：

{
  "schema_version": "game.numeric-tool-result.v1",
  "tool": "game_numeric_scenario_run",
  "ok": true
}

失败时 ok=false，并携带 {error:{code,message}}；业务字段只在成功结果中出现。所有工具参数必须是 JSON 可表达值，拒绝 NaN、Infinity、负零、函数、二进制和路径。source_ref、model_ref 与 change_set_hash 分别采用 source:<64 hex>、model:<64 hex>、sha256:<64 hex>。

Schema 关键不变量​

  • source_ref 绑定规范化来源内容；相同内容必须得到相同哈希。
  • model_ref 只为 ready 模型创建；incomplete 结果的引用为 null。
  • formula 的 inputs 必须与表达式标识符精确一致；未知标识符、循环和不可计算结果阻断模型。
  • candidate 只能覆盖存在、可调且在上下界内的参数；不可行候选不进入 Pareto 前沿。
  • change set 只列真实变化，且每项必须有 source_locator。调用方保持外层哈希与内嵌哈希一致。

安全与 NFR​

  • 来源上限 2 MB、20,000 单元格、10,000 行、256 列、JSON 深度 32；候选最多 50 个。
  • 内容存储最多 128 项，进程重启自然失效；不提供枚举接口，避免跨任务浏览暂存数据。
  • 表、Sheet、单元格地址和候选 ID 必须唯一，避免“取第一个”造成静默歧义。
  • 计算是确定性的；month 固定为 30 天。需要日历月语义时必须由上游显式展开，不能隐式猜测。
  • 所有外部修改通过 fresh-base/MR；无任意 shell；外部 CI 是唯一验证权威。

错误收敛​

  • 来源或映射错误：模型 incomplete，不创建可调用 model_ref。
  • 计算错误：场景/审计保留实体 ID 和错误原因，不转成零。
  • 约束失败：候选标记不可行；变更集生成被拒绝。
  • 引用过期：返回 ref unknown/expired，调用方重新从权威来源编译。

来源与外部写入​

固定 DSP manifest 的 ADP-DEV-API-DSP-0001 提供能力工具源码位置。GitLab MR、配置表写入及 Symphony 委托由各自 owner 管理；数值包不承担自动调度或提交。

历史 Action 的 source、schema 与测试保留归档资产，但不可恢复成备用路径。错误必须保持结构化和可解释，不以默认零值或模型自述代替证据。

Last updated on by source2728