openmaic/docs/large-course-mode.md

大型课程模式：主 Agent、顺序复用单课件、冻结发布

事实基线：2026-08-15

当前主链路已经实现：主 Agent 框架 → 人工确认 → 顺序复用原单课件生成 → 实际产出连续性 → Interactive HTML 门禁 → classroom 冻结 → manifest 精确 pin → learner 严格验证 → 原 Stage。三端物理拆分与数据库/对象存储替换仍是后续工作。

1. 与单课件模式的关系

大型课程不是第二套课堂生成器。它只增加课程级编排：

大型课程
  = 主 Agent 生成课程框架
  + 每个模块复用原单课件 agent
  + 课程级连续性与发布门禁

每个模块最终仍是一份普通 OpenMAIC classroom，拥有原四类 Scene、Action、Agent、 HTML 互动、Quiz、PBL、白板、媒体和讲解音频。learner 也仍进入原 Stage。

learner desktop 的单课件模式继续存在，并有两条入口：

• 普通纯文本需求走 POST /api/generate-classroom 后台任务；
• 有课程材料或开启 Interactive/职教模式时，保存 generationSession 后进入原 /generation-preview 前台流程。

只有大型课程的创建、框架重生成、确认、模块重试和课程发布属于 ops。

2. 主 Agent 产物

CourseFramework 是人工确认前的课程级契约，包含：

字段	含义
courseTitle / summary	整课标题与说明
languageDirective	所有模块一致的教学语言和术语处理
targetAudience	稳定学习者画像
courseGoals	3–8 个可观察整课目标
continuityContract.terminology	跨模块统一术语
continuityContract.teachingStyle	稳定讲解、示例和互动风格
continuityContract.difficultyProgression	难度递进
continuityContract.assessmentStrategy	形成性检查与综合考核连续性
modules	4–15 个有序完整教学单元

每个 CourseModuleSpec 不再只有标题和说明，还必须包含：

字段	用途
generationPrompt	主 Agent 写给原单课件 agent 的可独立执行 brief
learningObjectives	本模块可观察目标
prerequisites	前置模块/知识
incomingKnowledge	本模块可假定的输入知识
outgoingKnowledge	必须交给后续模块的输出知识
excludedTopics	由其他模块负责、此处不得深度重复的主题
estimatedMinutes	模块预计时长

新的 AI 输出经过严格校验；JSON 解析或契约失败时最多再试一次。旧 CourseRecord 在读取时 由 compat 层确定性补齐 generationPrompt、课程目标和连续性默认值，便于审阅和重跑； 这不会降低新 AI 输出的校验，也不会让旧记录自动通过发布门禁。

3. 两阶段与人工确认

3.1 框架阶段

POST /api/courses
  → 保存 CourseRecord(status=queued)
  → 可选联网研究
  → resolveModel(stage=course-framework)
  → generateCourseFramework
  → 严格校验
  → 保存 framework + pending modules
  → status=framework_ready

到 framework_ready 为止不会生成任何模块。运营必须在 /courses/{courseId} 审阅：

• 学习者、整课目标与语言；
• 术语、教学风格、难度和考核策略；
• 每模块 generationPrompt 与知识边界；
• 模块顺序、目标、时长和前置关系。

确认后才调用 POST /api/courses/{id}/start。不满意可调用 POST /api/courses/{id}/framework/regenerate；该操作会重置模块状态后重跑框架。

3.2 模块阶段

每个模块通过 buildModuleRequirement 合成完整输入：

整课标题、简介、目标学习者、整课目标
+ languageDirective
+ continuityContract
+ 当前模块 generationPrompt
+ objectives / prerequisites
+ incoming / outgoing / excluded knowledge
+ 所有前序模块的实际 outputDigest
+ 原始整课需求

随后调用同一套：

createClassroomGenerationJob
  → runClassroomGenerationJob
  → generateClassroom
  → outlines
  → Scene content / actions
  → media
  → TTS
  → 原子 persistClassroom

当前顺序语义：

1. 同一课程只允许一个活动 run，整课、框架和单模块重试互斥。
2. 模块按 index 串行，不并发。
3. 成功模块保存 classroomId、generationPromptSnapshot、outputDigest 和 continuityInputRefs。
4. 任一模块失败会停止后续模块，避免在缺失前序实际产出的情况下继续生成。
5. 单模块重试成功后，可从后续未成功模块继续按序生成。
6. 已成功模块不会被整课 resume 无条件重做。
7. 取消会中止当前 run，并协作式取消当前 classroom job；已成功模块保留。

旧文档中的“模块失败后继续下一个”已经不符合当前实现，不应恢复。

4. 实际产出连续性

4.1 outputDigest

每个成功 classroom 会生成确定性、有限大小的 CourseModuleOutputDigest：

• classroomId、createdAt、stage title/description/language；
• sceneCount 与 slide/quiz/interactive/pbl 分类计数；
• 每个 Scene 的标题、顺序、类型和有界关键内容；
• coveredConcepts、assessments、interactiveExperiences；
• 由实际语义内容计算的 sha256 semanticHash；
• digestVersion=2 的 sourceRevisionHash，对完整持久化 classroom JSON 做规范化 哈希，不会漏掉仅发生在 HTML 脚本、样式、布局或媒体的漂移。

digest 从已经持久化的 classroom 读取，而不是从主 Agent 的计划或 job 日志推测。 它忽略学习者 messages、submissions、evaluations 等运行态。

4.2 continuityInputRefs

生成模块 N 前，runner 必须确认所有 index 小于 N 的模块：

• status=succeeded；
• classroom 可读取；
• 具有 outputDigest，缺失时可从旧成功课堂补建；
• 按顺序形成 moduleIndex + classroomId + semanticHash 引用。

这些引用既注入后续生成 requirement，也持久化到模块记录。发布时会从当前 classroom 重新计算 digest，并逐项核对每个后续模块引用的正是当前前序实际输出。

因此：

• 前序模块重新生成后 semanticHash 变化，旧后续模块会被判 CONTINUITY_STALE；
• 缺少历史引用的旧下游模块会被判 CONTINUITY_UNVERIFIED；
• 必须从最早漂移位置开始顺序重生成，不能手工改 hash。

5. Interactive Mode 与 HTML 门禁

大型课程模块固定：

• interactiveMode=true；
• enableTTS=true。

后台 generateClassroom 不另写 Interactive prompt，而是通过 lib/server/classroom-outline-mode.ts 复用原 INTERACTIVE_OUTLINES 模板，并传入 同一 teacher persona、PDF、研究和媒体开关。

有两层门禁：

1. 生成门：Interactive Mode 在 persistClassroom 前要求至少一个 interactive Scene 且 content.html 非空；否则整个 job 失败且不落半成品。
2. 发布门：重新检查每个模块仍有非空 HTML；packager 要求 HTML 资产严格内联， 远端引用、无法冻结资产或空 HTML 均拒绝。

这保证了大课模块不是只打了 Interactive 标志却实际退化为纯幻灯片。

6. 发布门禁与原课堂保真

POST /api/courses/{id}/publish 必须通过：

• ops 角色 + ACCESS_CODE 会话；
• COURSEWARE_PUBLISH_TOKEN 已配置；
• 当前课程没有生成 run；
• framework 与 runtime module 数量/顺序一致；
• 所有模块 status=succeeded 且 classroom 可读取；
• 当前 digest 与模块保存的 semanticHash 一致；
• 当前完整 classroom 与模块保存的 sourceRevisionHash 一致；
• continuityInputRefs 精确；
• 每模块有生成的 Interactive HTML。

6.1 classroom → frozen bundle

lib/server/classroom-courseware-publish.ts 从持久化 classroom 直接冻结：

内容	冻结行为
Stage	标题、说明、语言、style、Interactive/Task mode、初始白板
Agent	id 映射、name、role、persona、avatar、priority、voiceConfig、voiceDesign
Scene	slide、quiz、interactive、pbl 原内容
Action	speech、discussion 和原教学动作
白板	Stage 与 Scene whiteboards，含其媒体
HTML	严格内联并拒绝残留远端资产
媒体	本地或 SSRF 安全远端字节转为包内稳定 ref
音频	speech 必须改写为包内 audioRef；不得同时保留 audioUrl
PBL	发布设计模板，不携带运营/学习者运行态

packager 以 requireAgentRoster、requireInteractiveHtml、 strictInteractiveAssets、requireComplete 全部开启运行；任何缺失都 fail closed。

6.2 原子可见性

课程发布流程：

1. 先验证 CourseRecord 快照；
2. ops 为每个 classroom 生成完整 placeholder-version ZIP，server 在课程锁内运行原发布门禁、 分配真实 version 并冻结为 unpublished；
3. 所有模块完成后再次验证来源快照未变化；
4. 把本批模块精确版本切为 published；大课 registry 私有 courseId/moduleIndex 让公共读 API 在 manifest exact pin 出现前继续隐藏这些版本；
5. 写入下一 CourseManifest version；
6. 若 manifest 未提交，补偿把本批 staged 版本退回 unpublished。

旧 published 版本不可变且不受本批失败影响。幂等命中会读取 exact 存储 ZIP 并复用完整 publish gate；丢失或篡改对象不会被当作成功。contentHash v2 明确忽略 manifest.json 的 exportedAt，因此远程和本地 fallback 对相同内容重复发布均返回 既有 manifest。无 contentHashVersion 的历史包仍用 v1 原始字节哈希验证，且只有 精确 registry 身份和重算 v1 hash 均通过才允许 learner 兼容加载。

ops 在 server 返回的模块 id/version/contentHash 与本地冻结包逐项匹配后才保存 publication receipt，并在其中固定 sourceRevisionHash。课程详情重读当前 classroom 后再验证该回执；任何完整源修改都会 fail closed。

当前锁和回退只是单进程内的补偿事务，没有跨进程隔离性或崩溃一致性； 文件仓库只允许单写实例。

7. CourseManifest v2 与 legacy

新 manifest 是 append-only 历史记录：

CourseManifestRecord
  schemaVersion = 2
  courseId
  version
  modules[]
    index
    title
    description
    coursewareId
    coursewareVersion
    contentHash

模块单独重发只会产生新的 courseware version；已提交 manifest v1 继续指向旧精确版本。 只有重新发布课程，新的 manifest v2 才会选择新的模块版本。

旧 singleton 文件仍可读取，并会在下一次成功发布时升级成 history envelope：

• 旧记录本身原样保留；
• 新记录使用旧最高 version + 1；
• 新记录必须是 schemaVersion=2 且 pin 完整。

learner API 对旧无 pin 记录返回 409。安全策略是运营重发，不是把当前 latest 伪造成旧 pin。 如发布校验发现旧课程缺 digest、连续性、HTML 或音频，从最早失败模块开始顺序重生成。

8. learner 严格加载并进入原 Stage

大型课程页面读取指定或 latest manifest version。点击模块时把以下值全部传入：

• coursewareId；
• coursewareVersion；
• contentHash；
• courseId、courseVersion、module index 作为返回导航。

loadLearnerCourseware 的检查顺序：

1. version 与 expectedContentHash 必须成对出现且格式合法；
2. registry 必须返回同一 coursewareId、精确 version 与合法 hash；
3. registry hash 必须等于 manifest pin；
4. 下载 bundle；
5. bundle 内 coursewareId 必须一致；
6. bundle 声明 hash、registry hash 与重新计算 hash 必须三者一致；
7. completeness.complete 必须为 true；
8. Agent、音频和媒体全部物化后，才原子写入 document。

缓存 stage id 包含 id、version 和完整 hash，所以不同版本或相同版本的异常不同内容不会 共用缓存。失败时回滚文档、媒体、音频和资产池。

物化文档不带 outlines，随后跳转：

/classroom/{learn_id_v_version_hash}?learner=1

课堂页仍渲染原 Stage；learner 参数只控制返回课程导航，不选择另一套播放器或助教。

9. 学习进度的当前边界

课程目录的 started/completed 标记当前保存在 localStorage，key 包含 courseId、 course manifest version 和 module index：

milo.course.{courseId}.v{courseVersion}.module.{index}.{kind}

它是单设备目录标记，不是服务端真实课堂进度。原课堂内部进度/作答仍走现有 runtime store； 启用 NEXT_PUBLIC_PERSISTENCE=1 时可走 HTTP backend。未来应从逐模块 runtime 记录聚合 课程进度，而不是让目录提前物化全部 bundle。

10. API

API	用途	权限/性质
POST /api/courses	创建 CourseRecord 并启动框架阶段	ops
GET /api/courses	运营课程列表	ops
GET /api/courses/{id}	框架、模块、job 与发布状态	ops
POST /api/courses/{id}/start	人工确认后启动顺序模块生成	ops
POST /api/courses/{id}/framework/regenerate	重生成框架并重置模块	ops
POST /api/courses/{id}/modules/{index}/regenerate	单模块重试，成功后顺序续跑	ops
POST /api/courses/{id}/resume	根据当前阶段续跑	ops
POST /api/courses/{id}/cancel	取消当前 run/job	ops
POST /api/courses/{id}/publish	校验、冻结全部模块并提交 manifest	ops
GET /api/learn/courses	已发布课程目录	公共静态读
GET /api/learn/courses/{id}?version=N	精确课程清单	公共静态读；legacy 返回 409
GET /api/coursewares/{id}?version=N	精确模块元数据	公共静态读
GET /api/coursewares/{id}/bundles/{version}/download	不可变 bundle	公共静态读

配置 COURSE_PUBLISH_SERVER_BASE_URL 时，课程发布 route 先在 ops 冻结全部模块，再通过 POST /api/internal/course-publish 一次提交 metadata + 全部 ZIP；server 分配真实版本、暂存、 提交 schema-v2 manifest 并在失败时补偿回 unpublished。未配置时保留原同进程 共享文件库 fallback，但复用相同批量事务、幂等与 manifest 可见性门禁。 该整批 multipart 接口只在 server/all 角色开放，使用 server-only COURSEWARE_PUBLISH_TOKEN Bearer 认证。server 生产发布还必须配置 COURSEWARE_PUBLIC_BASE_URL，公开 bundle URL 不从请求 Host 推导。

11. 存储与恢复

数据	目录	恢复行为
CourseRecord	data/course-frameworks	读时兼容旧框架、对 module job 状态自愈
classroom jobs	data/classroom-jobs	runner 重启中断；记录可供重试/续跑
classroom	data/classrooms	outputDigest 与冻结发布的事实源
courseware history	data/coursewares	append-only metadata，状态可 published/unpublished
bundle bytes	data/courseware-bundles	id/version 不可覆盖
manifest history	data/course-manifests	旧 singleton 可读，新发布升级为历史 envelope

所有互斥锁都在 Node.js 进程内。当前只支持单写实例；Postgres 事务、 唯一键、私有对象存储 put-if-absent 和持久任务队列是公网生产上线与多实例前的硬前置。

本模式完成了 ops 大课边界，没有完成 learner 身份、classroom/job owner、资源级 授权或成本额度。原 Chat 和生成/TTS/搜索等高成本 API 不应被当作已可安全 向匿名公网开放；该项等待用户身份、owner、授权、权益和限额设计。

12. 验收

核心定向命令：

pnpm exec vitest run \
  tests/course-framework \
  tests/courseware/server-classroom-publish.test.ts \
  tests/bundle/learner-load.test.ts \
  tests/server/classroom-outline-mode.test.ts \
  tests/server/classroom-generation-retry.test.ts

还应执行：

pnpm exec tsc --noEmit
pnpm exec playwright test e2e/tests/deployment-role-boundary.spec.ts --project=chromium
pnpm build

验收不变式：

1. 框架阶段结束于 framework_ready，确认前没有模块 job。
2. 每模块有 generationPromptSnapshot、outputDigest，后续模块有精确 continuityInputRefs。
3. 失败模块阻断后续生成。
4. 每模块至少有一份生成的非空 HTML 互动 Scene。
5. frozen bundle 包含 teacher roster、白板、Agent voice、媒体和 speech 音频。
6. manifest 精确 pin id/version/hash，旧 manifest version 不随模块重发漂移。
7. learner 拒绝 pin/hash/完整性不一致，并在成功后进入原 Stage。
8. 本改造不修改 protected Chat。已知 3 个 Pi Chat director 基线断言漂移按 handover.md 记录，不作为顺手改 Chat 的理由。