第14章 - 证据画像与徽章

// packages/game-kit/src/save.ts
/** 运行时只产出草稿；id/profileId/at 由外壳补齐后成为 EvidenceEvent */
export interface EvidenceDraft {
  phase: EvidencePhase;
  variantId: string;
  tool?: ToolId;
  action: string;
  artifact?: ArtifactSummary;
  outcome?: 'info' | 'pass' | 'fail';
  failureClass?: string;
  metrics?: Record<string, number>;
  scaffold?: Scaffold;
}

export interface EvidenceEvent extends EvidenceDraft {
  v: 1;
  id: string;
  at: number;
  profileId: string;
  levelId: LevelId;
  revision?: number;
}

export const EVIDENCE_PHASES = [
  'observe', 'hypothesize', 'construct', 'run', 'result', 'revise', 'generalize', 'argue',
] as const;

// packages/templates/src/pattern/runtime.ts（节选）
function emit(draft: Omit<import('@mmf/game-kit').EvidenceDraft, 'variantId'>): void {
  opts.onEvidence?.({ ...draft, variantId: 'base' });
}

// apps/site/src/views/WorkshopView.vue（节选）
function scheduleEvidenceFlush(): void {
  if (disposed || evidenceTimer !== null) return;
  evidenceTimer = window.setTimeout(() => {
    evidenceTimer = null;
    void flushEvidence();
  }, 2000);
}

// packages/evidence/src/index.ts（节选）
/** 空聚合：6 件工具的计数全部归零，便于 UI 直接读 byTool[tool]。 */
export function emptyAggregate(): EvidenceAggregate {
  const byTool = {} as Record<ToolId, number>;
  for (const tool of TOOL_IDS) byTool[tool] = 0;
  return {
    total: 0,
    byLevel: {},
    byTool,
    byPhase: {},
    byFailure: {},
    lastAggregatedAt: 0,
  };
}

export function aggregate(events: EvidenceEvent[]): EvidenceAggregate {
  const result = emptyAggregate();
  const byPhase: Partial<Record<EvidencePhase, number>> = {};
  for (const event of events) {
    if (event === null || typeof event !== 'object') continue;
    result.total += 1;
    // 分别累计 byLevel / byTool / byPhase / byFailure，并取最大 at 作为 lastAggregatedAt
  }
  result.byPhase = byPhase;
  return result;
}

// packages/evidence/src/types.ts（节选）
export interface DimensionSignal {
  id: string;
  label: string;
  value: number;
  sample: number;
  band: 0 | 1 | 2 | 3;
}

export interface DimensionView {
  id: EvidenceDimensionId; // 'structure' | 'rule' | 'model' | 'boundary'
  label: string;
  band: 0 | 1 | 2 | 3;
  summary: string;
  signals: DimensionSignal[];
}

export interface EvidenceProfile {
  version: 1;
  dimensions: DimensionView[];
  recommendations: Recommendation[];
  toolUses: { tool: ToolId; count: number }[];
  eventCount: number;
}

// packages/evidence/src/profile.ts（节选）
const DIMENSION_TEXT: Record<EvidenceDimensionId, readonly [string, string, string, string]> = {
  structure: [
    '还没有留下观察记录，先在关卡里多看、多试，再动手也不迟。',
    '你会先观察再动手。',
    '你会先观察再动手，也能把结构主线走通。',
    '你会先观察再动手，也能把规则用到转过方向的地图上。',
  ],
  // rule / model / boundary 同构
};

// packages/evidence/src/profile.ts（节选）
const structureBand: Band = anyTransfer ? 3 : completedStructure > 0 ? 2 : observed.size > 0 ? 1 : 0;
const ruleBand: Band = ruleVariantLevels > 0
  ? 3
  : completedRule > 0 && revisedCount > 0
    ? 2
    : completedRule > 0
      ? 1
      : 0;
const modelBand: Band = multiVariantModel > 0 ? 3 : completedModel > 0 ? 2 : knobProbeEvents > 0 ? 1 : 0;
const boundaryBand: Band = counterexamplePasses > 0 && anyTransfer
  ? 3
  : counterexamplePasses > 0
    ? 2
    : paymentCompleted
      ? 1
      : 0;

// packages/evidence/src/profile.ts（节选）
// rule 模板不再有迁移门（旋转是刚体变换，恒真，见 docs/12 遗留项 1），
// 所以"带迁移印章的规则关"永远是 0。这里换成规则线真正可观测的信号：
// 在多张地图上跑通过程序的关卡数（变体通行证里出现过的规则关）。

// packages/evidence/src/badges.ts（节选）
const OBSERVE_TARGET = 2;
const TRANSFER_TARGET = 2;

/** 完成关卡即授予的徽章：徽章 id → 关卡 id。 */
const LEVEL_BADGES: Partial<Record<BadgeId, LevelId>> = {
  'pattern-spotter': 'k-structure-pattern-path',
  'rule-designer': 'g13-algorithm-route',
  builder: 'g46-algorithm-payment',
  modeler: 'g79-modeling-dispatch',
  experimenter: 'g1012-modeling-winrate',
};

// packages/evidence/src/badges.ts（节选）
const view: BadgeView = {
  id,
  earned: Boolean(award) || progress.current >= progress.target,
  title: localizedTitle,
  criteria: levelTitle
    ? (locale === 'en' ? 'Complete "' + levelTitle + '"' : '完成「' + levelTitle + '」')
    : localizedCriteria,
  progress,
};

// packages/progress/src/manager.ts（节选）
const events = await this.evidence.recent(MAX_EVIDENCE_EVENTS);
const views = evaluateBadges(this.current, events, LEVEL_SUMMARIES);
const badges = { ...this.current.badges };
const newly: BadgeId[] = [];
// recent() 按时间倒序（最新在前）：引用取最新的 20 条，而非窗口里最旧的 20 条。
const evidenceRefs = events.slice(0, 20).map((event) => event.id);
for (const view of views) {
  if (!view.earned || badges[view.id]) continue;
  badges[view.id] = { awardedAt: now, evidenceRefs };
  newly.push(view.id);
}

// packages/evidence/src/index.ts（节选）
export { localizeDimensions, localizeReport, localizeTrail } from './localize';

// packages/progress/src/manager.ts（节选）
async recordEvidence(levelId: LevelId, drafts: EvidenceDraft[]): Promise<void> {
  if (!isKnownLevelId(levelId) || !Array.isArray(drafts) || drafts.length === 0) return;
  const at = this.clock();
  const batch = this.revisionBatches.get(levelId) ?? 0;
  const events: EvidenceEvent[] = [];
  for (const draft of drafts) {
    const event = toEvidenceEvent(draft, {
      id: this.nextEvidenceId(at),
      at,
      levelId,
      revision: batch,
    });
    if (event) events.push(event);
  }
  // 整批草稿都坏时不占 revision，也不写空数组。
  if (events.length === 0) return;
  this.revisionBatches.set(levelId, batch + 1);
  await this.evidence.append(events);
}

// packages/progress/src/manager.ts（节选）
/** 证据事件单条序列化上限（docs/02 §8.4：≤ 1.5 KB）。 */
const MAX_EVENT_BYTES = 1536;
/** 单条事件的 metrics 键数上限（docs/02 §8.4）。 */
const MAX_METRICS_KEYS = 8;

/** 兜底裁剪：先丢可选字段（metrics → artifact → failureClass），最后才截 action。 */
function fitEventSize(event: EvidenceEvent): EvidenceEvent {
  if (eventBytes(event) <= MAX_EVENT_BYTES) return event;
  delete event.metrics;
  if (eventBytes(event) <= MAX_EVENT_BYTES) return event;
  delete event.artifact;
  if (eventBytes(event) <= MAX_EVENT_BYTES) return event;
  delete event.failureClass;
  if (eventBytes(event) <= MAX_EVENT_BYTES) return event;
  event.action = truncateChars(event.action, 40);
  return event;
}

// apps/site/src/components/BadgeGrid.vue（节选）
/**
 * 徽章数据里没有图案字段（证据层只管"授没授"），
 * 贴纸图案属于外壳的视觉决定，所以放在这里而不是 @mmf/evidence。
 */
const STICKER_EMOJI: Record<BadgeId, string> = {
  observer: '👀',
  'pattern-spotter': '🧩',
  'rule-designer': '📜',
  builder: '🧱',
  modeler: '⚙️',
  experimenter: '🔬',
  'boundary-explorer': '🧭',
  reviser: '🔁',
  transferer: '🌈',
};

/** 已获得的贴纸微微歪一点，像真的贴上去的；灰度虚线的是还没收集到的空位。 */
const STICKER_TILT = ['-rotate-1', 'rotate-1', 'rotate-2', '-rotate-2', 'rotate-1', '-rotate-1'];

// apps/site/src/views/BadgesView.vue（节选）
const ringStyle = computed(() => ({
  background: 'conic-gradient(var(--color-teal) ' + percent.value + '%, var(--color-grid) 0)',
}));