第06章 - 内容数据模型与双语JSON

// packages/content/src/summaries.ts（节选）
/**
 * 摘要表：只静态加载已发布关卡，随 SHIPPED_LEVEL_IDS 增补。
 * 运行时不跑 zod（构建期由 content:check 校验），否则 zod 会进首屏。
 *
 * 键类型是 ShippedLevelId 而不是 string：少登记一关 typecheck 就报，
 * 不用等到运行时才由下面的 throw 兜底。
 */
const RAW: Record<ShippedLevelId, unknown> = {
  'k-structure-pattern-path': kPatternPath,
  'k-data-tally': kDataTally,
  // …共 20 条
};

export const LEVEL_SUMMARIES: readonly LevelSummary[] = SHIPPED_LEVEL_IDS.map((id) => {
  const summary = RAW[id] as LevelSummary | undefined;
  if (!summary) throw new Error('缺少关卡摘要：' + id);
  if (summary.id !== id) throw new Error('关卡摘要 id 不一致：' + id);
  return summary;
});

// packages/content/src/loadLevel.ts（节选）
/**
 * 详情走动态 import：Vite 会把每个 <id>.level.json 切成独立 chunk。
 * 运行时不做 zod 校验（构建期 content:check 负责）；只做 id 一致性断言。
 */
const LOADERS: Record<ShippedLevelId, () => Promise<unknown>> = {
  'k-structure-pattern-path': () => import('./details/k-structure-pattern-path.level.json'),
  'k-data-tally': () => import('./details/k-data-tally.level.json'),
  // …共 20 条
};

export async function loadLevel(
  id: ShippedLevelId,
  _locale: Locale = 'zh-CN',
): Promise<LevelDetail | null> {
  const summary = getLevelSummary(id);
  if (!summary) return null;
  const loader = LOADERS[id];
  if (!loader) return null;
  const raw = (await loader()) as { default?: unknown } | unknown;
  const detail = (raw && typeof raw === 'object' && 'default' in raw ? raw.default : raw) as LevelDetail | null;
  // 动态 import 正常不会给 null；真给了也要报清楚的错，而不是 TypeError: cannot read 'id' of null。
  if (!detail) throw new Error('关卡详情为空：' + id);
  if (detail.id !== id) throw new Error('关卡详情 id 不一致：' + id);
  return detail;
}

// packages/content/src/schema.ts（节选）
/**
 * strict()：未知字段直接报错而不是被静默剥掉——内容 JSON 里写错字段名
 * （例如 "thinking_target"）时，静默剥掉会变成"字段没生效但校验通过"。
 */
export const LevelSummarySchema = z.object({
  id: z.enum(LEVEL_IDS),
  title: z.string().min(1).max(24),
  titleEn: z.string().min(1).max(48).optional(),
  emoji: z.string().min(1).max(8),
  color: hexColor.optional(),
  band: z.enum(BANDS),
  thread: z.enum(THREADS),
  template: z.enum(TEMPLATE_IDS),
  tools: z.array(z.enum(TOOL_IDS)).min(1),
  estimatedMinutes: z.number().int().min(3).max(15),
  thinkingTarget: z.string().min(1).max(40),
  thinkingTargetEn: z.string().min(1).max(120).optional(),
  difficulty: z.object({
    structure: z.number().int().min(1).max(5),
    representation: z.number().int().min(1).max(5),
    constraint: z.number().int().min(1).max(5),
    transfer: z.number().int().min(1).max(5),
  }).strict(),
  unlock: z.object({ after: z.array(z.enum(LEVEL_IDS)).default([]) }).strict().optional(),
}).strict();

// packages/content/src/schema.ts（节选）
export const LevelDetailSchema = z.object({
  id: z.enum(LEVEL_IDS),
  title: z.string().min(1).max(24),
  // …中英六字段
  tools: z.array(ToolSpecSchema).min(1),
  requiredToolArtifacts: z.array(z.string().min(1)).min(1),
  levelScript: z.unknown(),
  evidencePlan: z.array(EvidenceCheckpointSchema).min(2),
  solutions: z.array(LevelSolutionSchema).min(2),
  negativeSamples: z.array(NegativeSampleSchema).min(3),
  variants: z.array(LevelVariantSchema).min(2),
  feedback: z.record(z.string(), FeedbackCopySchema),
  badges: z.array(z.enum(BADGE_IDS)).default([]),
  manualAudit: z.object({
    reviewed: z.boolean(),
    reviewer: z.string().min(1),
    reviewedAt: z.string().min(1),
    notesKey: z.string().optional(),
  }).strict().optional(),
}).strict();

export const ToolSpecSchema = z.discriminatedUnion('kind', [
  z.object({
    kind: z.literal('pattern'),
    ...ToolSpecBase,
    config: z.object({
      tokens: z.array(z.string().min(1)).min(2).max(4),
      maxPeriod: z.number().int().min(2).max(6).default(4),
      cells: z.array(z.number().int().min(0)).optional(),
    }),
  }),
  // …rule / construct / knob / probe / counter 各一支
]);

// packages/content/src/index.ts（全文）
/**
 * 外壳侧入口：常量 / 摘要 + 动态详情加载。
 * 刻意不导出 zod schema：zod 是真实副作用，只要主入口引用它就会进首屏。
 * 需要构建期校验的地方走 '@mmf/content/full'。
 */
export * from './ids';
export type { LevelDetail, LevelSummary, ToolSpec } from './schema';
export { LEVEL_SUMMARIES, getLevelSummary, levelSummaries, ensureSummaries } from './summaries';
export { loadLevel } from './loadLevel';
export { localizedDetail, localizedSummary } from './localize';
export type { LocalizedDetail, LocalizedSummary } from './localize';

// packages/content/src/localize.ts（节选）
export function localizedDetail(detail: LevelDetail, locale: Locale): LocalizedDetail {
  if (locale === 'en') {
    return {
      title: detail.titleEn ?? detail.title,
      thinkingTarget: detail.thinkingTargetEn ?? detail.thinkingTarget,
      intro: detail.introEn ?? detail.intro,
      prompt: detail.promptEn ?? detail.prompt,
      done: detail.doneEn ?? detail.done,
      retry: detail.retryEn ?? detail.retry,
    };
  }
  return { title: detail.title, thinkingTarget: detail.thinkingTarget, intro: detail.intro,
    prompt: detail.prompt, done: detail.done, retry: detail.retry };
}

// scripts/content-check.ts（节选）
/** 玩家可见的英文文案字段：这些字段必须存在且零中文残留。 */
const EN_FIELDS = ['titleEn', 'thinkingTargetEn', 'introEn', 'promptEn', 'doneEn', 'retryEn'] as const;

for (const field of EN_FIELDS) {
  const value = data[field];
  if (!value) { fail(id + ' 缺少英文文案 ' + field); continue; }
  if (CJK.test(value)) fail(id + ' 英文文案 ' + field + ' 含中文：' + value);
}
for (const text of EN_FIELDS.map((field) => data[field]).filter((v): v is string => Boolean(v))) {
  // 只拦 CJK 全角标点；弯引号 “” 与 en dash – 是合法英文排版，不算错。
  if (/[，。；：！？（）【】]/.test(text)) fail(id + ' 英文文案含全角标点：' + text);
}

// scripts/content-check.ts（节选）
/**
 * 内容体检：构建期唯一的"内容质量门"。
 * 这里只做**通用**检查——不写死某关的解法数值，避免内容一改脚本就红。
 * 语义检查（解/负例/变体可解性）在 audit-levels.ts，两者共用 templates 的 verifier。
 */

for (const negative of data.negativeSamples) {
  if (negativeIds.has(negative.id)) fail(id + ' 负例 id 重复：' + negative.id);
  negativeIds.add(negative.id);
  const verdict = verifier.validateArtifact(data, baseVariant, negative.artifact);
  if (verdict.passed) fail(id + ' 负例居然通过：' + negative.id);
  else if (verdict.failure?.class !== negative.expectFailure) {
    fail(id + ' 负例失败类不符：' + negative.id + ' 期望 ' + negative.expectFailure + '，实际 ' + verdict.failure?.class);
  }
}

// ---- 反馈覆盖 ----
const reachable = verifier.reachableFailureClasses(data);
const feedbackKeys = new Set(Object.keys(data.feedback));
for (const failure of reachable) {
  if (!feedbackKeys.has(failure)) fail(id + ' 缺少失败类反馈：' + failure);
}

const missingTarget = LEVEL_IDS.filter((id) => !shipped.has(id));
console.log('目标矩阵：' + (LEVEL_IDS.length - missingTarget.length) + '/' + LEVEL_IDS.length + ' 已发布；其余 ' + missingTarget.length + ' 关在后续里程碑' + (requireAll ? '（已要求全量）' : '') + '。');
if (requireAll && missingTarget.length > 0) {
  fail('目标矩阵缺 ' + missingTarget.length + ' 关：' + missingTarget.join('、'));
}