《AI Agent 游戏产品开发》9.1 从策划表格到可执行规格

策划表格要变成可执行规格,必须补上类型、范围、引用与版本四件事。本节以消消关卡表为例,说明五种字段类型各自校验什么、为什么行号与原因要一起返回、版本号为什么取字段定义指纹而不是文件名,以及 Agent 生成配置前必须先过的编译闸门,并说明人审只看哪三件事。

以下人物、公司与数字均为教学假设,不构成对任何真实产品的评价。字段数量、取值范围与校验规则均为产品教学设定值。

《潮汐消消》每个版本要上两百多关。策划在表格里填步数、掉落率、难度标签,程序把表格导出成配置,客户端和服务端各读一份。过去这套流程靠口头约定维持:掉落率写 0.3 表示 30%,步数写 20 表示 20 步,NPC 写「潮汐」表示引用潮汐这个角色。

引入 Agent 生成配置之后,口头约定失效了。模型不知道「0.3」是概率还是三分之三,也不知道「潮汐」是角色名还是关卡名。它按字面理解生成内容,错误不会在导出时报出来,只会在玩家打到第 187 关时暴露。

这一节解决一件事:把策划表格变成机器能校验、能拒绝、能版本化的规格。只有先有规格,Agent 才有稳定的输入与输出边界。

表格的三处缺口

策划表格不是规格,它少了三样东西:

缺口表格里的写法规格里的写法不补的后果
类型掉落率 0.3float,范围 0–10.3 被当成 30 条,或反过来
范围步数 20 左右int,10–40生成了 0 步或 9999 步的关卡
引用NPC:潮汐ref 指向 npc.id引用了不存在的角色,运行时空指针

三处缺口对应三类事故:类型错导致数值离谱,范围错导致玩家卡死或秒过,引用错导致内容加载失败。三类都发生在线上,而不是导出时。

表格的另一个隐蔽问题是它没有版本。文件名从 level_v3.xlsx 改成 level_v3_final.xlsx,没人知道改了什么。Agent 读到哪一版、依据哪一版生成,事后无法还原。

五种字段类型够用

游戏配置的字段看似五花八门,落到校验层只有五种:

类型典型字段校验内容
int步数、关卡号、掉落数量必须是整数,且在上下界内
float掉落率、暴击倍率、时长必须是有限浮点数,且在上下界内
bool是否限时、是否显示提示必须是布尔值
enum难度、关卡类型、奖励档位必须来自固定取值集合
ref关卡引用的 NPC、道具、章节必须能在目标表中找到

五种类型不是理论分类,而是校验动作的最小集合。每多一种类型,就多一条校验分支和一套测试;五种覆盖了绝大多数配置,剩下的用组合表达。

类型之外还要有「必填」标记。必填字段缺失时不能给默认值,因为默认值会掩盖策划漏填。可选字段缺失是合法的,校验应放行。

校验要带行号与原因

「这张表有 3 个错误」是一句无用的话。策划需要知道第几行、哪个字段、错在哪:

row 42 field dropRate: above:1
row 43 field npc: type:ref
row 44 field moves: missing

三要素缺一不可。没有行号,策划要自己找;没有字段名,找到行也不知道看哪列;没有原因,知道哪列也不知道怎么改。

原因要写成机器可读的短标签,而不是自然语言长句。短标签便于聚合统计:一周内 above 出现 40 次,说明范围设置与策划预期不符,而不是某个人填错。

原因也要能被人读懂。type:ref 对策划不够友好,导出工具可以在展示层翻译成「NPC 不存在」,但底层保留短标签。展示层可以换,校验层不换。

版本号取字段定义,不取文件名

规格的版本号有两种算法:取文件名,或取内容指纹。

取文件名的问题是它可以随便改。level_v3.xlsx 与 level_v3_final.xlsx 可能内容完全相同,也可能差了一个范围;版本号无法回答「这两版能不能互相替代」。

取内容指纹则只看字段定义:字段名、类型、是否必填、范围、枚举取值、引用表。字段顺序变化不算变更,因为校验行为没变;改一个范围就算新版本,因为校验行为变了。

范围变化必须换版本,原因是它直接改变什么数据能通过。把步数上限从 40 放宽到 60,原本被拒绝的配置会开始通过,这是一次行为变更,不是一次排版调整。

版本号还要能写进生成记录。Agent 生成一批配置时,记录「使用规格版本 a1b2c3d4」,事后才能回答「这批配置是按哪套规则生成的」。

编译闸门:不合格的表不进运行时

表格到配置之间要有一道编译闸门,顺序固定:

  1. 检查规格本身可执行。 数值字段有上下界,枚举有取值,引用有目标表。
  2. 逐行校验。 缺字段、类型错、越界、枚举外取值、引用不存在,全部收集。
  3. 有错就整体拒绝。 不返回半成品,也不跳过错误行。
  4. 无错才产出配置。 同时产出规格版本与内容指纹。

第三步是关键。允许「跳过错误行」看起来宽容,实际会让配置悄悄少几关,线上表现为进度卡住。整体拒绝会迫使问题在导出阶段解决。

闸门还要对 Agent 生成的内容一视同仁。模型生成的配置与人工填的表走同一条校验路径,不因为来源是模型就放宽标准。

把规格写成可运行校验

下面的实现把字段定义、单行校验、整表校验、可执行判定、版本指纹与编译闸门写成纯函数。

// file: src/pipeline/spec.ts
// tier: L1
// verify: node --test test/pipeline/spec.test.ts

// 策划表格变成可执行规格:先有类型与范围,才有校验与版本。
// 表格里一句「数值合理」无法执行,规格里一行 min/max 可以。

export type FieldType = "int" | "float" | "bool" | "enum" | "ref";

export type FieldSpec = {
  readonly key: string;
  readonly type: FieldType;
  readonly required: boolean;
  readonly min?: number;
  readonly max?: number;
  readonly values?: readonly string[];
  readonly refTable?: string;
};

export type TableSpec = {
  readonly table: string;
  readonly fields: readonly FieldSpec[];
};

export type Row = Readonly<Record<string, string | number | boolean | null>>;

export type Issue = {
  readonly row: number;
  readonly field: string;
  readonly reason: string;
};

export type Refs = Readonly<Record<string, ReadonlySet<string>>>;

function typeOk(field: FieldSpec, value: unknown, refs: Refs): boolean {
  switch (field.type) {
    case "int":
      return typeof value === "number" && Number.isInteger(value);
    case "float":
      return typeof value === "number" && Number.isFinite(value);
    case "bool":
      return typeof value === "boolean";
    case "enum":
      return typeof value === "string" && (field.values ?? []).includes(value);
    default:
      return (
        typeof value === "string" &&
        field.refTable !== undefined &&
        (refs[field.refTable]?.has(value) ?? false)
      );
  }
}

// 一行一行校验:缺字段、类型不符、越界、枚举外取值、引用找不到,各给一条原因。
export function checkRow(
  spec: TableSpec,
  row: Row,
  rowIndex = 0,
  refs: Refs = {},
): Issue[] {
  const issues: Issue[] = [];
  for (const field of spec.fields) {
    const value = row[field.key];
    const empty = value === undefined || value === null || value === "";
    if (empty) {
      if (field.required) {
        issues.push({ row: rowIndex, field: field.key, reason: "missing" });
      }
      continue;
    }
    if (!typeOk(field, value, refs)) {
      issues.push({ row: rowIndex, field: field.key, reason: `type:${field.type}` });
      continue;
    }
    if ((field.type === "int" || field.type === "float") && typeof value === "number") {
      if (field.min !== undefined && value < field.min) {
        issues.push({ row: rowIndex, field: field.key, reason: `below:${field.min}` });
      }
      if (field.max !== undefined && value > field.max) {
        issues.push({ row: rowIndex, field: field.key, reason: `above:${field.max}` });
      }
    }
  }
  return issues;
}

// 整表校验要把行号带出来,否则策划拿到「有一个字段错了」无法修。
export function checkTable(spec: TableSpec, rows: readonly Row[], refs: Refs = {}): Issue[] {
  const issues: Issue[] = [];
  rows.forEach((row, index) => {
    issues.push(...checkRow(spec, row, index + 1, refs));
  });
  return issues;
}

// 可执行的最低条件:字段有类型,数值有上下界,枚举有取值,引用有目标表。
export function isExecutable(spec: TableSpec): boolean {
  if (spec.fields.length === 0) return false;
  return spec.fields.every((field) => {
    if (field.type === "int" || field.type === "float") {
      return field.min !== undefined && field.max !== undefined;
    }
    if (field.type === "enum") {
      return (field.values ?? []).length > 0;
    }
    if (field.type === "ref") {
      return typeof field.refTable === "string" && field.refTable.length > 0;
    }
    return true;
  });
}

function fnv1a(input: string): string {
  let hash = 0x811c9dc5;
  for (let i = 0; i < input.length; i += 1) {
    hash ^= input.charCodeAt(i);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return hash.toString(16).padStart(8, "0");
}

function canonical(spec: TableSpec): string {
  const fields = [...spec.fields]
    .sort((a, b) => a.key.localeCompare(b.key))
    .map((field) => [
      field.key,
      field.type,
      field.required,
      field.min ?? null,
      field.max ?? null,
      field.values ?? null,
      field.refTable ?? null,
    ]);
  return JSON.stringify({ table: spec.table, fields });
}

// 版本号取字段定义的指纹,不取文件名:改了范围就是新版本,改注释不是。
export function specVersion(spec: TableSpec): string {
  return fnv1a(canonical(spec));
}

export type SpecDiff = {
  readonly added: readonly string[];
  readonly removed: readonly string[];
  readonly retyped: readonly string[];
};

// 字段顺序变化不算变更,增删与改类型才算:否则每次排版都会触发一次评审。
export function diffSpec(before: TableSpec, after: TableSpec): SpecDiff {
  const oldMap = new Map(before.fields.map((field) => [field.key, field]));
  const newMap = new Map(after.fields.map((field) => [field.key, field]));
  const added = [...newMap.keys()].filter((key) => !oldMap.has(key)).sort();
  const removed = [...oldMap.keys()].filter((key) => !newMap.has(key)).sort();
  const retyped = [...newMap.keys()]
    .filter((key) => oldMap.has(key) && oldMap.get(key)!.type !== newMap.get(key)!.type)
    .sort();
  return { added, removed, retyped };
}

export type Compiled = {
  readonly table: string;
  readonly version: string;
  readonly rows: number;
  readonly hash: string;
};

// 编译失败时不返回半成品:一张带错的表进入运行时,比缺一张表更难查。
export function compile(spec: TableSpec, rows: readonly Row[], refs: Refs = {}): Compiled {
  if (!isExecutable(spec)) {
    throw new Error(`spec not executable: ${spec.table}`);
  }
  const issues = checkTable(spec, rows, refs);
  if (issues.length > 0) {
    const first = issues[0];
    throw new Error(
      `invalid row ${first.row} field ${first.field}: ${first.reason} (${issues.length} issues)`,
    );
  }
  return {
    table: spec.table,
    version: specVersion(spec),
    rows: rows.length,
    hash: fnv1a(canonical(spec) + JSON.stringify(rows)),
  };
}

typeOk 把五种类型收在一个 switch 里。引用类型需要外部传入目标表的主键集合,所以校验函数多一个 refs 参数;没有目标表时引用一律不通过,而不是默认放行。

checkRow 先判空再判类型。必填字段为空时报 missing,可选字段为空时直接跳过;空字符串按缺失处理,因为表格里的空单元格导出后通常就是空串。

越界检查只对数值类型生效,并且上下界分开报。below:10 与 above:40 让策划一眼知道是填小了还是填大了。

checkTable 的行号从 1 开始,与表格软件的行号一致。从 0 开始会让策划每次都要加一,增加沟通成本。

isExecutable 是规格自身的体检:数值必须有上下界,枚举必须有取值,引用必须有目标表。缺任何一项,规格就不能编译,因为校验器无法判断什么叫合法。

specVersion 先对字段排序再序列化,所以字段顺序变化不改变指纹。它只包含定义,不包含数据行;数据变化由编译产物的 hash 负责。

diffSpec 只报增、删、改类型三类。范围变化没有单独列出,因为范围已经进入版本指纹;需要看具体差异时对比两个版本的定义即可。

compile 先检查规格可执行,再校验所有行。任何一行有问题就抛错,并在错误信息里带上第一条问题的行号、字段、原因与总问题数。最后返回的 hash 同时覆盖规格与数据,用于回答「这份配置是不是同一份」。

Agent 生成配置,先过同一道闸门

有了规格,Agent 的职责就清楚了:它不负责决定字段是否合法,只负责在合法空间里生成候选。

输入侧,把规格的字段定义转成提示词,明确每个字段的类型、范围与取值。输出侧,要求模型返回结构化数据,而不是自然语言表格。中间侧,用同一套校验函数检查,不通过就退回重生成。

退回重生成要有次数上限。三次仍不合格,说明不是模型的随机波动,而是规格或提示词有问题,应该转人工。无限重试只会把成本花在同一类错误上。

生成记录要保存三样东西:规格版本、模型版本、校验结果。三者合起来才能回答「这批配置为什么长这样」。

人审只看三件事

机器校验通过不代表配置好玩。人审只需要看三件事:

  • 难度曲线。 相邻关卡的步数与掉落率是否形成递进,而不是随机跳动。
  • 引用语义。 NPC 是否存在是一回事,出现在这一关是否合理是另一回事。
  • 异常组合。 每个字段都合法,组合起来可能荒谬,例如 5 步配 1% 掉落率。

三件事都无法用字段级校验表达,所以必须留给人。人审的价值不是重复机器的检查,而是发现「都合法但不对」的组合。

人审意见要回写成规则。同一类组合问题出现三次,就应该变成一条跨字段约束,进入下一版规格,而不是每次靠人看出来。

小结

  • 策划表格缺类型、范围、引用与版本,四者不补,Agent 生成的内容无法校验。
  • 五种字段类型覆盖大多数配置:int、float、bool、enum、ref。
  • 必填字段缺失不能给默认值,默认值会掩盖漏填。
  • 校验结果必须带行号、字段与原因,三者缺一不可。
  • 原因用机器可读短标签,展示层再翻译成人话。
  • 版本号取字段定义指纹,字段顺序不算变更,范围变化算。
  • 编译闸门有错就整体拒绝,不返回半成品,也不跳过错误行。
  • Agent 生成的配置与人工表格走同一条校验路径。
  • 重生成三次仍不合格时转人工,问题多半在规格或提示词。
  • 人审只看难度曲线、引用语义与异常组合,并把重复问题回写成规则。

阅读导航:上一节:8.3 观测与刹车:什么时候关掉涌现 · 下一节:9.2 美术与音频的批处理一致性 。

常见错误与边界

  1. 把表格当规格。 类型与范围靠口头约定,Agent 一读就错,错误在上线后才暴露。
  2. 版本号取文件名。 final 与 final2 哪个新说不清,事后无法还原生成依据。
  3. 校验只报数量。 「有 3 个错误」不告诉策划改哪里,沟通成本比校验本身还高。
  4. 跳过错误行继续导出。 配置悄悄少几关,线上表现为进度卡住,比直接失败更难查。
  5. 对 Agent 放宽校验。 模型生成的内容绕过闸门,等于把最需要约束的来源放到了约束之外。
  6. 人审重复机器检查。 把时间花在字段是否合法上,真正的异常组合反而没人看。

规格解决的是「配置对不对」。配置之外还有美术与音频,它们的批量生成面对的是另一种一致性问题:单张都合格,放在一起不像一套。

下一节从一批 40 张的素材开始,说明色差、响度与抽检怎么变成可执行的判据。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图