生成协议草案

1. 文档目的

本文档用于定义课程工厂的正式生成协议，作为三条正式主线共用的契约层。

当前基线已从旧版 GenerationInput 升级为：

• GenerationInputV2

2. 协议设计原则

1. 以课程主骨架为中心
2. 以三条正式主线共享为前提
3. 显式区分输入、阶段产物、任务、结果
4. 支持 P0 先打通正向主链

3. 输入协议

interface GenerationInputV2 {
  requestId?: string;
  subject: string;
  schoolStage: string;
  gradeLevel?: string;
  requirement: string;
  learningSessionMode:
    | "forward_design"
    | "diagnostic_remediation"
    | "capability_reverse_design";
  courseStrategy: CourseStrategyInput;
  lessonIntent: LessonIntentInput;
  assemblyMode:
    | "chapter_based"
    | "knowledge_based"
    | "capability_based"
    | "mixed";
  chapter?: string;
  sourceMaterials?: SourceMaterialRef[];
  curriculumStandard?: CurriculumStandardRef;
  learnerProfile?: LearnerProfile;
  learnerStateSnapshot?: LearnerStateSnapshot;
  diagnosticContext?: DiagnosticContextInput;
  remediationPreference?: RemediationPreferenceInput;
  selectedKnowledgePoints?: string[];
  targetProblemSet?: ProblemSampleInput[];
  targetCapability?: CapabilityGoalInput;
  generationOptions?: GenerationOptions;
  subjectOptions?: SubjectOptions;
  providerOptions?: ProviderOptions;
  locale?: string;
}

3.1 关键字段说明

3.2 当前组合规则

forward_design

建议至少具备：

• chapter 或等价教材章节输入
• sourceMaterials 中至少一种材料

diagnostic_remediation

建议至少具备：

• learnerStateSnapshot
• diagnosticContext

capability_reverse_design

建议至少具备其一：

• targetProblemSet
• targetCapability

4. 阶段产物协议

4.1 StagePlan

interface StagePlan {
  id: string;
  subject: string;
  title: string;
  learningSessionMode: GenerationInputV2["learningSessionMode"];
  courseStrategy: CourseStrategyInput;
  lessonIntent: LessonIntentInput;
  assemblyMode: GenerationInputV2["assemblyMode"];
  stageObjectives: string[];
  unitOrder: string[];
  warnings?: GenerationWarning[];
}

4.2 UnitPlan

interface UnitPlan {
  id: string;
  title: string;
  order: number;
  unitType:
    | "chapter_unit"
    | "review_unit"
    | "remediation_unit"
    | "capability_unit";
  assemblyMode: GenerationInputV2["assemblyMode"];
  knowledgePointIds?: string[];
  teachingObjectives: string[];
  sceneOrder: string[];
  practicePlanId?: string;
  metadata?: Record<string, unknown>;
}

4.3 ScenePlan

interface ScenePlan {
  id: string;
  unitId: string;
  order: number;
  type: "slide" | "quiz" | "interactive" | "pbl";
  scenePattern:
    | "concept_explanation"
    | "worked_example"
    | "quiz_check"
    | "review_feedback"
    | "reinforcement_block"
    | "summary_transfer";
  title: string;
  goal?: string;
  contentHints?: Record<string, unknown>;
}

4.4 PracticePlan

interface PracticePlanContract {
  id: string;
  stageId?: string;
  unitId: string;
  trainingBlocks: PracticeBlock[];
  assessmentFocus?: string[];
  commonMistakeFocus?: string[];
  masteryCheckpoints?: MasteryCheckpoint[];
  feedbackLoop?: FeedbackLoopSummary;
}

4.5 StageArtifact

interface StageArtifact {
  stage: StageContract;
  units: UnitContract[];
  scenes: SceneContract[];
  practicePlans: PracticePlanContract[];
  projections?: ProjectionRef[];
  assetRefs?: AssetRef[];
  protocolVersion: string;
}

5. 主线特有协议

5.1 诊断补救

interface GapProfileContract {
  id: string;
  gapTypes: string[];
  gapTraits: string[];
  evidenceSources: EvidenceSource[];
  decisionHints?: RemediationDecisionHint[];
}

interface RemediationCoursePlanContract {
  id: string;
  gapProfileId: string;
  remediationMode: "rollback" | "recompose" | "hybrid";
  targetKnowledgePoints: string[];
  backfillUnits?: string[];
  bridgeUnits?: string[];
  exitCriteria: string[];
}

5.2 能力专题

interface ProblemSolvingPatternContract {
  identity: {
    id: string;
    subject: string;
    name: string;
    patternType: string;
  };
  applicability: {
    applicableProblemTypes: string[];
    entrySignals: string[];
  };
  cognitiveKernel: {
    requiredKnowledgeChains: string[];
    reasoningSteps: ReasoningStep[];
    commonMistakes: string[];
    successCriteria: string[];
  };
  trainingHints: {
    variantAxes: string[];
    assessmentFocus: string[];
  };
}

interface CapabilityUnitContract {
  id: string;
  title: string;
  patternRefs: string[];
  knowledgeChainRefs?: string[];
  targetCapability: string;
  coverageScope: Record<string, unknown>;
  errorFocus?: string[];
  masteryCheckpointPlan?: MasteryCheckpoint[];
}

6. 任务协议

interface GenerationJob {
  jobId: string;
  status: "pending" | "running" | "succeeded" | "failed" | "cancelled";
  step: GenerationJobStep;
  progress: number;
  input: GenerationInputV2;
  result?: GenerationJobResult;
  error?: JobError;
  createdAt: number;
  updatedAt: number;
}

type GenerationJobStep =
  | "initializing"
  | "understanding_input"
  | "routing_entry"
  | "planning_stage"
  | "planning_units"
  | "planning_scenes"
  | "planning_practice"
  | "assembling_stage_artifact"
  | "persisting"
  | "completed";

7. 错误与警告协议

interface JobError {
  code: string;
  message: string;
  failedStep?: GenerationJobStep;
  retryable?: boolean;
  metadata?: Record<string, unknown>;
}

interface GenerationWarning {
  code: string;
  message: string;
  step?: GenerationJobStep;
  metadata?: Record<string, unknown>;
}

8. P0 最小实现面

当前 P0 只要求协议先稳定支持：

• forward_design
• curriculum_aligned
• chapter_based

P0 可以先不正式落地：

• GapProfileContract
• RemediationCoursePlanContract
• ProblemSolvingPatternContract
• CapabilityUnitContract

但这些对象必须在协议层预留正式位置，避免后续再换协议代际。

9. 结论

当前正式生成协议已经升级为：

• 以 GenerationInputV2 为入口
• 以 StagePlan / UnitPlan / ScenePlan / PracticePlan / StageArtifact 为主产物
• 以三条正式主线共享为前提

后续实现不应再以旧版 GenerationInput + SceneOutline + ActionPlan 作为唯一中心结构。