运行时事件协议

1. 文档目的

本文档用于定义教学运行内核的统一事件协议。

2. 协议目标

1. 解耦 UI 与运行内核
2. 解耦运行链与生成任务链
3. 支持回放、诊断和检查点回挂

3. 基础事件结构

interface RuntimeEvent<T = unknown> {
  eventId: string;
  eventType: RuntimeEventType;
  stageId: string;
  unitId?: string;
  sceneId?: string;
  actorId?: string;
  correlationId?: string;
  timestamp: number;
  payload: T;
  metadata?: Record<string, unknown>;
}

4. 顶层事件类型

type RuntimeEventType =
  | "playback.started"
  | "playback.paused"
  | "playback.resumed"
  | "playback.completed"
  | "unit.changed"
  | "scene.changed"
  | "action.started"
  | "action.completed"
  | "checkpoint.triggered"
  | "checkpoint.completed"
  | "quiz.submitted"
  | "quiz.graded"
  | "practice.block.started"
  | "practice.block.completed"
  | "discussion.started"
  | "discussion.ended"
  | "snapshot.saved"
  | "progress.updated"
  | "error.occurred";

5. 关键事件说明

5.1 unit.changed

表示当前运行 Unit 切换。

5.2 scene.changed

表示 Scene 切换，是运行主事件之一。

5.3 checkpoint.triggered

表示掌握检查点被触发。

5.4 practice.block.completed

表示某个训练段完成，可用于回挂进度和补缺判断。

6. 与生成任务事件的边界

运行事件不应承载：

• 生成任务进度
• 任务阶段重试
• 课程装配日志

这些属于：

• GenerationJob
• StageExecutionLog

7. 回挂语义

运行事件需要支持回挂到：

• RuntimeSnapshot
• LearningProgress
• 检查点结果
• 补缺闭环证据

8. 结论

当前运行时事件协议的关键更新是：

• 补入 unitId
• 补入检查点和训练块事件
• 明确与生成任务事件分层

后续实现不得再把生成进度事件和课堂运行事件混成一个层面。