openmaic/docs/architecture-3-tier.md

麦洛学习三端架构：learner desktop / ops / server

事实基线：2026-08-15

当前物理形态仍是一份 OpenMAIC Next.js 应用，通过部署角色封住大型课程运营能力； learner desktop、ops、server 尚未拆成三个独立应用。本文区分“已经实现的能力边界” 与“后续机械拆分”，不把目标态写成已上线事实。

1. 核心结论

1. learner desktop 保留原 OpenMAIC 单课件生成、编辑与互动课堂，不是纯静态播放器。
2. 大型课程只由 ops 制作：主 Agent 先给出全局框架与每模块 generationPrompt，人工确认后， 才按顺序复用原单课件生成管线。
3. 发布不复制或重写课堂内核。server 把持久化 classroom 冻结为完整 bundle； learner 严格验证课程清单、版本、哈希与 bundle 完整性后，仍进入原 Stage。
4. 原课堂的 Agent、ChatArea/Roundtable、Scene/Action、HTML 互动、Quiz、PBL、白板、 讲解音频和媒体都是受保护能力，不在本次三端改造中另造简化版。
5. 大型课程 manifest 的模块身份是 coursewareId + coursewareVersion + contentHash。 单独重发某模块不会改变已经发布的课程版本。
6. 当前 courseware、bundle、course framework、course manifest 都是文件仓库， 发布只是单进程内的补偿事务，没有跨进程隔离性，只适合单写 Node.js 实例。 Postgres 事务与私有对象存储仍是公网生产上线前的硬前置。

2. 当前形态与能力矩阵

部署角色取值为 all、ops、server、learner。生产环境未配置角色时默认 learner， 开发和测试环境未配置时默认 all。角色边界目前主要保护 manage_courses， 并不等同于已经完成物理路由裁剪。

能力	learner desktop	ops	server	当前事实
普通文本生成单课件	主入口	同构应用内仍可用	承载当前后台 job	POST /api/generate-classroom
材料、Interactive、职教单课件	主入口	同构应用内仍可用	提供生成 API	经 generationSession 进入原 /generation-preview
单课件编辑、播放	是	用于审阅模块	否	均复用原 /classroom/{id} 与 Stage
原课堂 Agent/讨论/白板/PBL/音频	是	审阅时是	提供模型和数据 API	没有 learner 专用简化内核
创建、重生成、确认大型课程	否	是	否	/courses 与 /api/courses/** 受角色和会话保护
主 Agent 课程框架	否	是	运行时当前仍同进程	stage 为 course-framework
classroom 转 frozen bundle	否	发起并审阅	接收整批冻结 ZIP 并事务发布	lib/server/classroom-courseware-publish.ts + /api/internal/course-publish
courseware 注册、精确版本下载	只读	写入	主责	/api/coursewares/**
course manifest 读取	只读	发布	主责	/api/learn/courses/**
学习大型课程	是	可验收	提供静态清单与 bundle	/learn/course/{id} → /learn/{coursewareId} → Stage
发布凭据	无	ACCESS_CODE 会话；跨实例使用服务端 token	校验 Bearer token	浏览器不再读取发布 token

已实现的安全边界

• OPENMAIC_DEPLOYMENT_ROLE 和 NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE 共同决定服务端能力与 客户端入口显示；公开变量只承载非敏感角色名。
• 生产 ops 必须配置 ACCESS_CODE。middleware 保护运营路径， 每个 /api/courses/** route 还会再次执行 requireOpsAccess，校验 HMAC cookie。
• ACCESS_CODE 会话带签发时间和 TTL，默认 7 天；cookie Max-Age 与 TTL 一致， 中间件与 Node route 都会拒绝过期或未来时间的 token。登录只接受同源 application/json，实际请求体上限 8 KiB，失败尝试受有界进程内限流。
• 用 cookie 授权的 ops 写请求还必须通过 Origin 同源校验。反向代理部署应配置 OPS_PUBLIC_ORIGIN 作为 canonical origin；该校验不信任 X-Forwarded-Host。
• 同源 ops 发布课件时使用已认证会话；独立 server 接收 POST /api/coursewares 时才校验 COURSEWARE_PUBLISH_TOKEN Bearer token。
• COURSEWARE_PUBLISH_TOKEN 是服务端变量。旧的 NEXT_PUBLIC_COURSEWARE_PUBLISH_TOKEN 不再是配置项，也不得重新引入浏览器。
• learner 角色隐藏大型课程入口，直接访问运营 API 返回 403，访问运营页面会回到首页。
• server 角色是无头数据/API 服务：所有页面返回 404，且不暴露 /api/courses/、/api/ops/ 和 /api/access-code/**；未鉴权的媒体代理、provider 验证、视频导出、开发态 persistence、usage 与全局 job 列表也会 404。 内部整课发布仍只认 Bearer token。
• server 对全局 job 列表同时拒绝 GET/HEAD，并在规范化尾斜杠后对内部发布 执行 POST-only 方法边界。
• 远程发布后，ops 以当前 publication receipt 补足本地 registry 的 source 反查； 发布与 job/source 删除共用单进程互斥并在冲突时返回 409。该回执不是历史索引， 重生后旧 source 的永久保留和多副本互斥仍是后续持久化契约。
• SSRF 边界已拦截 RFC6598 100.64.0.0/10（含阿里云 metadata 地址）； 专用 server 不暴露 /api/proxy-media。若未来在公网 learner/all 重新开放， 必须先实现 DNS 解析 pin 和逐跳 redirect 复核。

尚未实现的隔离

• 三种角色仍从同一 Next.js 构建产物启动，生成、课堂和多数 API 文件仍共处一个进程。
• deployment role 已对明确非课堂必需端点做部分 deny，但它仍不是完整 learner identity/capability allowlist。
• learner desktop、ops、server 的独立域名和独立包尚未机械拆出；ops → server 的整批 frozen bundle + schema-v2 manifest 提交接口已封装为 server-only HTTP 契约。
• 因 NEXT_PUBLIC_* 在构建期内联，严格的 ops/learner UI 隔离应分别构建。
• learner 用户身份、classroom/job 的 owner、资源级授权与课程权益尚未实现。 因此不得把当前匿名访问原 Chat、生成、TTS、搜索或其他高成本 API 描述为已安全开放；公网部署必须先完成身份、owner、授权和额度设计。

3. 受保护课堂内核

本改造的边界是“外围编排、权限、冻结发布、目录和存储”，不是重写课堂。以下代码和契约 应视为受保护基线：

• components/stage.tsx
• components/edit/PlaybackChromeRoot.tsx
• components/chat/**
• components/roundtable/**
• components/scene-renderers/**
• lib/playback/**
• lib/chat/**
• lib/action/**
• lib/whiteboard/**
• lib/pbl/**
• 原 Stage / Scene / Action DSL 与 /classroom/{id} 播放链路

必须保持的运行时不变式：

1. learner 打开的模块仍是 /classroom → Stage → PlaybackChromeRoot → SceneRenderer。
2. Stage 内原 ChatArea/Roundtable 是唯一课堂问答入口；learner 外层不再挂第二套 AssistantPanel。
3. 冻结包保留完整 Agent roster、persona、priority、voiceConfig、voiceDesign， 以及 discussion/multiAgent 引用。
4. Stage 初始白板、场景白板、四类 Scene、教学 Action、Quiz、PBL 设计模板、 HTML iframe、媒体和 speech 音频均随包保存。
5. 静态目录与 bundle 下载是零 LLM 热路径；进入原课堂后，原教师/助教、动态评分和 PBL 教学运行时仍可按原设计调用模型。不得再把 learner 描述为“整个学习过程零 LLM”。

4. 生成数据流

4.1 learner desktop 单课件双路径

首页需求
  ├─ 纯文本普通模式
  │    └─ POST /api/generate-classroom
  │         └─ 持久化 classroom job
  │              └─ 原 generateClassroom 管线
  │                   └─ 原子写入 classroom
  └─ 有材料，或开启 Interactive Mode / 职教模式
       └─ 文件写入浏览器 document store
            └─ sessionStorage.generationSession
                 └─ /generation-preview
                      └─ 原前台单课件生成管线

分流条件位于 app/page.tsx：

• courseMaterials 非空、interactiveMode 为 true 或 vocationalTestMode 为 true 时走前台；
• 其他普通需求走可关闭页面的后台 job；
• 前台适配器只保存浏览器拥有的文件并恢复原生成会话，不复制场景生成逻辑。

4.2 ops 大型课程生成

POST /api/courses
  → 主 Agent 生成 CourseFramework
  → status = framework_ready
  → 运营人工审查和确认
  → POST /api/courses/{id}/start
  → 模块 1 调用原 classroom job
  → outputDigest + semanticHash
  → 模块 2 注入模块 1 的实际产出与 continuityInputRefs
  → 按序继续，直到全部成功

主 Agent 的框架契约包括：

• targetAudience、courseGoals、languageDirective；
• terminology、teachingStyle、difficultyProgression、assessmentStrategy；
• 每模块 generationPrompt、learningObjectives、incomingKnowledge、 outgoingKnowledge、excludedTopics、prerequisites 和 estimatedMinutes。

第二层生成具有以下约束：

• 每个模块都复用 createClassroomGenerationJob + runClassroomGenerationJob；
• 同一课程同一时刻只有一个 framework、整课或单模块 run；
• generationPromptSnapshot 保存实际使用的主 Agent 提示词；
• outputDigest 从持久化 classroom 的四类 Scene 与 Action 中确定性提取， semanticHash 标识有界语义产出；digest v2 同时保存 sourceRevisionHash，对完整 持久化 classroom JSON 做规范化哈希，覆盖 HTML 脚本、样式、布局和媒体等变化；
• 后续模块使用前序实际 outputDigest，而不是只相信原计划；
• 任一模块失败即暂停后续模块，修复或重试成功后才顺序续跑；
• 大课模块强制 interactiveMode=true、enableTTS=true；
• Interactive Mode 若没有至少一个非空 HTML 的 interactive Scene，会在原子持久化前失败。

5. 发布数据流

独立部署时，ops 在本地冻结完全部模块后，用一个 multipart 请求把 metadata 与全部 ZIP 发往固定的 /api/internal/course-publish。server 只接受 server-only COURSEWARE_PUBLISH_TOKEN Bearer 认证；公开 bundle URL 由 COURSEWARE_PUBLIC_BASE_URL 派生，不使用请求 Host。未配置远程 origin 时的同源 fallback 走同一批量发布契约。

已完成 CourseRecord
  → validateCoursePublishSnapshot
     - 模块顺序、成功状态、classroom 可读
     - outputDigest 语义哈希与 sourceRevisionHash 都未漂移
     - continuityInputRefs 精确匹配前序实际输出
     - 每模块至少一个非空互动 HTML
  → 每个 persisted classroom 冻结为 unpublished courseware
     - Agent/persona/voice
     - Stage/Scene whiteboards
     - Scene/Action/Quiz/PBL
     - 内联 HTML 与媒体
     - speech audioRef 指向包内音频
  → 再次校验整个来源快照未变化
  → 本批精确模块版本切为 published
  → 提交 schemaVersion=2 的 CourseManifest

classroom → frozen bundle 的服务端适配器会：

• 把本地媒体或经过 SSRF 检查的远端媒体转成内容稳定引用；
• 拒绝 blob URL、未解析生成占位符、空媒体、缺失讲解音频和外链互动资产；
• 把 PBL 学习者运行态剥离，只发布可重复开始的设计模板；
• 把 speech 的 audioId/audioUrl 改写成 bundle 内 audioRef；
• 要求可携带且至少有 teacher 的 Agent roster；
• 用确定性 SHA-256 内容哈希登记不可变版本。

发布期间模块先以 unpublished 暂存。每条大课 registry record 私有记录 courseId/moduleIndex； 即使状态已 promotion 为 published，公共 catalog/detail/download 仍要求某个已提交 schema-v2 manifest 精确 pin 该 id/version/hash。因此 manifest 前不存在 learner 可见窗口。若来源二次 校验或 manifest 提交失败，本批版本回到 unpublished，旧的已发布版本不受影响。当前这是 单进程事务式补偿与可见性门禁，不是数据库事务。

幂等判断不只比较 latest manifest 与 incoming contentHash，还会读取对应存储对象并复用完整 单课件发布门禁检查内部 id/version/hash、重算 hash、complete 与 portable 资源。文件缺失或 bundle.json 被篡改时不会返回幂等成功。contentHash v2 明确忽略 manifest.json 中的 exportedAt，所以远程和同源 fallback 对相同源重复发布都返回同一 manifest；无 contentHashVersion 标记的历史包仍按 v1 原始字节哈希验证， learner 仅对能通过精确 registry 和 v1 哈希校验的真正旧包启用兼容路径。 当前没有隐式“强制新版本”语义。

ops 只在 server 回执的模块 id/version/contentHash 与本地冻结包逐项一致后 写入 publication receipt。回执还固定每模块 sourceRevisionHash；查询发布状态时会 重读当前 classroom 并比较该哈希，源课堂任何完整修改都使回执 fail closed。

6. 学习数据流与精确版本

GET /api/learn/courses/{courseId}?version={manifestVersion}
  → 只接受 schemaVersion=2 且每模块有 id + version + hash
  → /learn/{coursewareId}?version={v}&hash={h}
  → 查询 registry 的精确版本
  → 核对 registry id/version/hash
  → 下载 bundle
  → 核对 bundle 内 id、声明 hash、重新计算 hash、complete=true
  → 物化 Agent/音频/媒体/课堂文档
  → 本地 stage id = learn_{id}_v{version}_{hash}
  → /classroom/{stageId}?learner=1
  → 原 Stage

物化后的发布课堂没有 outlines，因此课堂页不会恢复场景或媒体生成；若物化中途失败， 文档、音频、媒体和资产池会补偿回滚。独立单课件入口可以先解析 latest，但缓存身份同样 包含最终解析出的 version 与 contentHash；大型课程入口始终使用 manifest 精确 pin。

7. legacy manifest 重发策略

旧 singleton manifest 可以只读并在仓库中保留，但它没有可靠的模块版本和内容哈希：

• learner API 对 schemaVersion 非 2 或任一模块缺少 pin 的记录返回 409；
• 禁止把“当前 latest”回填成“历史上当时使用的版本”，因为无法证明它是原始事实；
• 运营端应从原 CourseRecord 重新执行发布校验并重发课程；
• 如旧模块没有 continuityInputRefs、outputDigest、互动 HTML 或持久化音频， 从最早不满足门禁的模块开始顺序重生成，再发布；
• 新发布生成下一 manifest 版本并精确 pin 每个模块；旧版本继续保留用于审计， 但仍不可供 learner 打开。

8. 当前存储与扩展边界

数据	当前实现	当前限制	目标替换
classroom	data/classrooms + 本地 media/audio	本机文件	数据库元数据 + 对象存储
classroom jobs	data/classroom-jobs + 内存 runner	重启中断，靠记录自愈后续跑	持久队列/worker
CourseRecord	data/course-frameworks	进程内锁	Postgres 行锁/事务
courseware metadata	data/coursewares 历史 JSON	进程内版本锁	Postgres 唯一键 (id, version)
frozen bundle bytes	data/courseware-bundles	本地文件	对象存储 put-if-absent + manifest exact-pin 后 CDN
CourseManifest	data/course-manifests 历史 JSON	进程内版本锁	Postgres 唯一键 (course_id, version)
learner 物化缓存	浏览器 document store / IndexedDB	单设备	可保留缓存，进度另走用户存储

文件写入使用临时文件 + rename/link，并有进程内 mutex；它只能防同一 Node.js 进程并发。 多个 server 实例、多个容器或共享卷不能依靠这些 Map 锁分配唯一版本，因此当前服务端必须 单实例写入。失败时的 unpublished 回退是应用层补偿，并不提供数据库事务的 隔离性或崩溃一致性。DATABASE_URL 和 ASSET_S3_BUCKET 已服务于通用 document/runtime/asset 持久化抽象，但尚未替换 courseware/manifest/bundle 这组仓库，不能据此宣称发布层已上 Postgres/S3；数据库事务、唯一约束和私有对象存储是扩容或公网上线前的硬前置。

9. 后续机械拆分顺序

1. 先冻结契约和测试：bundle、manifest v2、CourseRecord、protected Stage 回归保持不变。
2. 抽共享契约包：仅移动纯类型、哈希、序列化和 import 适配器，不改 Scene/Action 语义。
3. 先拆 server：搬 courseware/manifest repo、下载与只读 API；复用已有内部整批提交接口， 让现有 ops 通过 HTTP 适配器调用。
4. 把文件 repo 替换为 Postgres + 对象存储后，再允许 server 多实例。
5. 再拆 learner desktop：整体搬首页双路径、generation-preview、tasks、learn、classroom 以及受保护课堂依赖；只改 import 和 API base URL，不复制 Stage。
6. 最后拆 ops：搬 courses UI、course-framework runner、发布校验与 classroom 冻结发起端； 审阅仍复用同一受保护课堂包。
7. 最后删除 all 兼容角色和同源直写分支，启用按应用路由 allowlist。

详细执行与回滚门槛见 deployment-3-tier.md。

10. 验收边界与已知 Chat 基线漂移

三端改造相关的广泛受保护课堂回归曾执行 130 个文件、1,294 个测试： 128 个文件、1,291 个测试通过。稳定复现的 3 个失败位于既有 Pi Chat director 契约：

1. tests/lib/chat/pi/prompts.test.ts： keeps concept and mechanism questions teacher-led before student reactions
2. tests/lib/chat/pi/route-cue-user.test.ts： hands successful web evidence to one child and clears it before later delegations
3. tests/lib/chat/pi/route-cue-user.test.ts： does not leak consumed web evidence after the selected child fails

第一项是当前 prompt 的 teacher + user 规则与旧 assistant fallback 断言漂移；后两项是 route fixture 对 URL 出现在 child prompt 字符串中的旧断言，与当前 evidence attachment 路径漂移。本轮大型课程、冻结发布和三端文档未修改 lib/chat/** 或 /api/chat/pi。 这些失败只作为受保护基线记录，不应在本改造中修改 Chat 内核来“顺手修绿”。