OpenMAIC 系统设计文档站
权威基础文档
系统设计文档站 / 权威基础文档

系统架构设计文档

本文档用于从实施级视角说明 OpenMAIC 新一代课程内核的目标架构。

01 静态 HTML 版本 2026年5月26日 15:03

1. 文档目的

本文档用于从实施级视角说明 OpenMAIC 新一代课程内核的目标架构。

本文件以 [15-课程内核重构蓝图（V1）.md](./15-%E8%AF%BE%E7%A8%8B%E5%86%85%E6%A0%B8%E9%87%8D%E6%9E%84%E8%93%9D%E5%9B%BE%EF%BC%88V1%EF%BC%89.md) 和 [16-课程内核重构工程推进路线图（V1）.md](./16-%E8%AF%BE%E7%A8%8B%E5%86%85%E6%A0%B8%E9%87%8D%E6%9E%84%E5%B7%A5%E7%A8%8B%E6%8E%A8%E8%BF%9B%E8%B7%AF%E7%BA%BF%E5%9B%BE%EF%BC%88V1%EF%BC%89.md) 为最高基线。

2. 架构定位

系统本质不是“AI 课堂页面平台”，而是：

  • 课程工厂
  • 教学运行内核

其中：

  • 课程工厂 负责把教材、知识点、诊断证据、能力目标转成稳定课程资产
  • 教学运行内核 负责把课程资产转成课堂过程、训练过程和回挂过程

总体策略固定为：

  • 单引擎、多策略、多投影

第一阶段实现形态固定为：

  • 模块化单体

3. 顶层原则

  1. 课程内核优先于平台外壳
  2. 领域模型优先于页面结构
  3. 生成链与运行链分离
  4. 包级边界优先于框架选型
  5. 基础能力通过 adapter 接入，不写进内核主流程
  6. 先稳定生成课程主干，再逐步增强质量、交互和多模态深度

4. 主骨架

课程主骨架已固定为：

  • Stage -> Unit -> Scene

其中：

  • Stage 表示一门完整课程或一个完整课堂实例
  • Unit 表示面向教学目标的组织块
  • Scene 表示课堂运行的最小教学场景

PracticePlan 已进入课程主干，不再只是课后附属题单。

运行层的 Action 仍然保留，但它属于：

  • Scene 的运行附属对象
  • runtime-engine 的消费对象

而不是课程主骨架本身。

5. 目标架构分层

5.1 核心包

  • packages/domain-model
  • packages/generation-contracts
  • packages/course-kernel
  • packages/runtime-engine
  • packages/subject-enhancers
  • packages/infra-adapters

5.2 应用壳层

  • apps/api
  • apps/web

5.3 分层职责

domain-model

负责稳定领域对象，不承载生成算法和页面实现。

重点包括：

  • Stage / Unit / Scene / PracticePlan
  • KnowledgePoint / CompositeKnowledgeChain
  • ProblemSolvingPattern / CapabilityUnit
  • GapProfile / RemediationCoursePlan
  • CourseStrategy / LessonIntent / AssemblyMode / UnitType

generation-contracts

负责统一三条正式主线的输入输出协议。

重点包括：

  • GenerationInputV2
  • StagePlan / UnitPlan / ScenePlan
  • StageArtifact / Projection
  • 任务状态、阶段日志、错误协议

course-kernel

负责课程装配主流程，是课程工厂的编排中枢。

重点包括：

  • 输入理解与上下文归一化
  • 三条主线入口分流
  • 正向组课
  • 诊断补救反向组课
  • 能力专题反向组课
  • PracticePlan 装配

runtime-engine

负责消费课程资产并驱动课堂运行，不参与组课决策。

重点包括：

  • Scene 切换
  • Action 执行
  • 检查点与小测事件
  • 训练回挂与运行快照

subject-enhancers

负责学科增强注入。

重点包括：

  • 学科表达策略
  • 模式库
  • 图示、题型、讲评和补救建议

infra-adapters

负责接入外部能力。

重点包括：

  • LLM
  • Image / Video
  • TTS / ASR
  • PDF 解析
  • Web Search
  • PostgreSQL / Redis / MinIO

apps/api

负责请求接入、任务编排、持久化和对外暴露。

apps/web

负责老师与学生消费界面，不承载课程协议本体。

6. 包级依赖规则

允许的主方向如下：

Mermaid 流程图
flowchart LR WEB["apps/web"] --> API["apps/api"] API --> GC["packages/generation-contracts"] API --> CK["packages/course-kernel"] API --> RT["packages/runtime-engine"] API --> IA["packages/infra-adapters"] CK --> DM["packages/domain-model"] CK --> GC CK --> SE["packages/subject-enhancers"] CK --> IA RT --> DM RT --> IA SE --> DM IA --> EXT["External Providers / DB / Storage"]
查看结构源码
flowchart LR
    WEB["apps/web"] --> API["apps/api"]
    API --> GC["packages/generation-contracts"]
    API --> CK["packages/course-kernel"]
    API --> RT["packages/runtime-engine"]
    API --> IA["packages/infra-adapters"]
    CK --> DM["packages/domain-model"]
    CK --> GC
    CK --> SE["packages/subject-enhancers"]
    CK --> IA
    RT --> DM
    RT --> IA
    SE --> DM
    IA --> EXT["External Providers / DB / Storage"]

禁止的反向依赖：

  1. domain-model 不得依赖任何应用层或基础设施层
  2. generation-contracts 不得依赖 apps/*
  3. runtime-engine 不得依赖 course-kernel
  4. subject-enhancers 不得改写主骨架协议
  5. apps/web 不得直接依赖 provider SDK

7. 两条主链

7.1 生成链

GenerationInputV2 -> StagePlan -> UnitPlan -> ScenePlan -> PracticePlan -> StageArtifact

7.2 运行链

StageArtifact -> RuntimeSession -> SceneSwitch -> ActionExecution -> CheckpointFeedback -> RuntimeSnapshot

8. 三条正式主线

统一通过 GenerationInputV2.learningSessionMode 区分：

  1. forward_design
  2. diagnostic_remediation
  3. capability_reverse_design

它们共享同一套内核，但采用不同装配策略。

9. 当前阶段的架构优先级

当前工程优先级固定为：

  1. 先稳定 forward_design 主链
  2. 再补 diagnostic_remediation
  3. 再补 capability_reverse_design
  4. 最后抬升课程质量、交互深度和 AI 深覆盖

这意味着当前不是微服务拆分阶段，也不是平台外壳优先阶段。

10. 结论

当前推荐的正式目标架构是：

  • 单仓 monorepo
  • 服务端为权威
  • 模块化单体
  • 课程工厂与教学运行内核分离
  • 课程主骨架稳定为 Stage -> Unit -> Scene

后续无论是否拆服务，都不得破坏这条主线。