以下人物、公司与数字均为教学假设,不构成对任何真实产品的评价。字段数量、取值范围与校验规则均为产品教学设定值。
《潮汐消消》每个版本要上两百多关。策划在表格里填步数、掉落率、难度标签,程序把表格导出成配置,客户端和服务端各读一份。过去这套流程靠口头约定维持:掉落率写 0.3 表示 30%,步数写 20 表示 20 步,NPC 写「潮汐」表示引用潮汐这个角色。
引入 Agent 生成配置之后,口头约定失效了。模型不知道「0.3」是概率还是三分之三,也不知道「潮汐」是角色名还是关卡名。它按字面理解生成内容,错误不会在导出时报出来,只会在玩家打到第 187 关时暴露。
这一节解决一件事:把策划表格变成机器能校验、能拒绝、能版本化的规格。只有先有规格,Agent 才有稳定的输入与输出边界。
表格的三处缺口
策划表格不是规格,它少了三样东西:
| 缺口 | 表格里的写法 | 规格里的写法 | 不补的后果 |
|---|---|---|---|
| 类型 | 掉落率 0.3 | float,范围 0–1 | 0.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」,事后才能回答「这批配置是按哪套规则生成的」。
编译闸门:不合格的表不进运行时
表格到配置之间要有一道编译闸门,顺序固定:
- 检查规格本身可执行。 数值字段有上下界,枚举有取值,引用有目标表。
- 逐行校验。 缺字段、类型错、越界、枚举外取值、引用不存在,全部收集。
- 有错就整体拒绝。 不返回半成品,也不跳过错误行。
- 无错才产出配置。 同时产出规格版本与内容指纹。
第三步是关键。允许「跳过错误行」看起来宽容,实际会让配置悄悄少几关,线上表现为进度卡住。整体拒绝会迫使问题在导出阶段解决。
闸门还要对 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 美术与音频的批处理一致性 。
常见错误与边界
- 把表格当规格。 类型与范围靠口头约定,Agent 一读就错,错误在上线后才暴露。
- 版本号取文件名。
final与final2哪个新说不清,事后无法还原生成依据。 - 校验只报数量。 「有 3 个错误」不告诉策划改哪里,沟通成本比校验本身还高。
- 跳过错误行继续导出。 配置悄悄少几关,线上表现为进度卡住,比直接失败更难查。
- 对 Agent 放宽校验。 模型生成的内容绕过闸门,等于把最需要约束的来源放到了约束之外。
- 人审重复机器检查。 把时间花在字段是否合法上,真正的异常组合反而没人看。
规格解决的是「配置对不对」。配置之外还有美术与音频,它们的批量生成面对的是另一种一致性问题:单张都合格,放在一起不像一套。
下一节从一批 40 张的素材开始,说明色差、响度与抽检怎么变成可执行的判据。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。