openmaic/docs/handover.md

麦洛学习项目交接

交接基线：2026-08-15

项目根：/Users/inmanw/项目/麦洛学习

代码：/Users/inmanw/项目/麦洛学习/OpenMAIC

文档：/Users/inmanw/项目/麦洛学习/docs

1. 一句话现状

三端能力边界、大型连续课程生成、完整 classroom 冻结发布和精确版本学习链路已经落地； 当前仍是一份 OpenMAIC Next.js 16.1.2 应用与文件仓库，learner desktop / ops / server 尚未物理拆分，发布层尚未迁到 Postgres/对象存储，learner 身份与资源 owner 也尚未完成。这两项都是公网生产上线前的硬前置。

2. 接手前必须知道的本机事实

项目	当前事实
OpenMAIC 版本	package version 0.3.2
Next.js	16.1.2
版本管理	OpenMAIC 当前不是 Git worktree，没有可依赖的 commit/diff/rollback
环境文件	.env.local 当前存在；不要输出、分享或提交其中内容
.env	当前不存在
代码与文档位置	文档在 OpenMAIC 同级的 docs，不在代码目录内
存储	课程发布主链路仍使用 data 下的文件仓库
写入拓扑	只能单 Node.js 写实例

在建立 Git 基线前，任何后续改动都应小批次、保留触及文件清单，并先备份 data 与 .env.local。

3. 产品与能力矩阵

能力	learner desktop	ops	server
普通文本单课件后台生成	是	同构代码仍可用	当前承载 job/API
材料/Interactive/职教前台生成	是	同构代码仍可用	提供生成 API
原单课件编辑与 Stage	是	模块审阅	否
大型课程主 Agent	否	是	当前同进程运行
框架人工确认、模块重试	否	是	否
classroom 冻结与课程发布	否	冻结并发起	整批事务接收与发布
courseware / manifest 读服务	消费	发布	主责
大课目录与精确模块学习	是	验收	提供数据
Agent/Chat/白板/PBL/音频	原样保留	审阅时原样保留	供数据/模型端点

当前部署角色为 all、ops、server、learner。生产默认 learner，开发/测试默认 all。 大型课程运营能力由 role + ACCESS_CODE 会话保护；浏览器不再持有发布 token。 server 角色已是无头服务：所有页面以及运营/API 家族返回 404，但这不等于 其他 API 已有 learner 身份和资源级授权。当前已额外隐藏 provider 验证、 MP4 export、开发态 persistence、usage、全局 job 列表和未鉴权媒体代理； 原 Chat/Quiz/PBL/TTS 与单课件生成等待正式 learner capability，不得直接删除。 全局 job 列表的 HEAD 与 GET 同样隐藏，内部整课发布在尾斜杠形式下也仍是 POST-only。ops 远程发布成功后会用当前 publication receipt 保护 source classroom， 发布和 job/source 删除还有同进程互斥。这不包含被重生清除的历史回执，也不是 跨副本锁；多实例生产化时必须改为持久发布历史和数据库事务/分布式锁。

ACCESS_CODE 会话默认 TTL 为 7 天，cookie Max-Age 与服务端验证同步；登录只接受 同源 application/json，实际请求体最大 8 KiB，且有进程内失败限流。所有 cookie 授权的 ops 写请求还会校验同源 Origin。 反向代理部署要配置 OPS_PUBLIC_ORIGIN 作为 canonical origin；该校验不信任 X-Forwarded-Host。

4. 不可跨越的保护边界

本项目的原则是：不改原课堂内核，只改外围编排、权限、发布、目录和存储。

受保护范围：

• 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 发布模块仍走 /learn → /classroom → 原 Stage。
2. learner 外层没有第二套 AssistantPanel；原 ChatArea/Roundtable 是唯一课堂问答入口。
3. frozen bundle 带完整 Agent persona/voice、Stage/Scene 白板、四类 Scene、Action、 HTML、Quiz、PBL、媒体和 speech 音频。
4. 大课模块仍复用原单课件 agent，没有第二套内容生成器。
5. 拆分工作不得以修复无关 Chat 断言为理由修改 protected core。

5. 已实现主链路

5.1 learner desktop 单课件双路径

app/page.tsx 的当前分流：

• 普通纯文本需求 → POST /api/generate-classroom → 持久化后台 job；
• 有材料，或 Interactive/职教开关打开 → lib/generation/foreground-session.ts 保存文件引用和 generationSession → 原 /generation-preview。

后台路径可以关闭页面后从 /tasks 查看；前台路径保留浏览器拥有的材料与原互动/职教生成。

5.2 大型课程

POST /api/courses
  → 主 Agent CourseFramework
  → framework_ready
  → 人工确认
  → 模块按序复用 classroom job
  → outputDigest / continuityInputRefs
  → 全部成功

主 Agent 输出 targetAudience、courseGoals、continuityContract，以及每模块 generationPrompt、输入/输出知识边界和 excludedTopics。任一模块失败会暂停后续模块； 修复后按顺序续跑。

所有大课模块固定 Interactive Mode 与 TTS。若没有生成的非空 HTML interactive Scene， 在 persistClassroom 前失败。

5.3 发布

validate CourseRecord snapshot
  → persisted classroom 转完整 frozen bundle
  → 每模块暂存 unpublished 精确版本
  → 再验证来源未变化
  → 本批切 published
  → schemaVersion=2 manifest

发布保留完整课堂，并拒绝缺 Agent、音频、媒体、HTML、连续性或发生 digest 漂移的模块。 每个 manifest module 固定 coursewareId + coursewareVersion + contentHash。 发布校验还使用 sourceRevisionHash 锁定完整持久化 classroom；ops 只在 server 返回 的 id/version/contentHash 逐项一致后保存带 sourceRevisionHash 的 publication receipt。

独立部署时，ops 把 metadata 与全部模块 ZIP 作为一个 multipart 请求发往 /api/internal/course-publish，server 只接受 COURSEWARE_PUBLISH_TOKEN Bearer。模块在 schema-v2 manifest exact pin 提交前不会进入公共 catalog/detail/download。未配置远程 origin 时的同源 fallback 复用同一内容幂等与可见性规则。

contentHash v2 忽略 manifest.json.exportedAt，使相同内容的远程/本地重试返回既有 manifest；无 contentHashVersion 的真正历史包仍按 v1 原始字节哈希验证。

5.4 学习

manifest 精确 pin
  → registry 精确版本
  → bundle 内外 id/version/hash/completeness 校验
  → 物化 Agent/音频/媒体/document
  → hash 隔离的本地 stage id
  → 原 Stage

发布文档不带 outlines，所以课堂页不会触发场景/媒体恢复生成。进入原 Stage 后，原课堂 教师/助教、动态评分和 PBL 运行时仍可按原设计调用模型。

6. 关键代码地图

角色与鉴权

路径	作用
lib/config/deployment-role.ts	角色解析、生产 fail closed、manage_courses
lib/server/ops-access.ts	ops role + ACCESS_CODE cookie route guard
middleware.ts	运营页面/API 第一层边界
app/api/coursewares/route.ts	ops 会话或 server Bearer 的双发布入口
e2e/tests/deployment-role-boundary.spec.ts	learner 隐藏/拒绝运营能力

单课件双路径

路径	作用
app/page.tsx	普通后台与材料/Interactive/职教前台分流
lib/generation/foreground-session.ts	文件持久化与原 preview session 适配
app/generation-preview	原前台生成
app/api/generate-classroom	后台 job
lib/server/classroom-generation.ts	原单课件服务端生成管线与 HTML 门

主 Agent 与连续性

路径	作用
lib/course-framework/types.ts	CourseFramework、generationPrompt、digest/ref 契约
lib/prompts/templates/course-framework/system.md	主 Agent prompt
lib/course-framework/generate-framework.ts	严格解析、校验与重试
lib/course-framework/compat.ts	旧 CourseRecord 读取兼容
lib/course-framework/runner.ts	人工确认后的顺序单课件复用
lib/course-framework/module-digest.ts	实际产出摘要与 semanticHash
lib/course-framework/publish-validation.ts	digest、连续性、HTML 发布门
lib/course-framework/store.ts	文件记录、原子更新、读时自愈

冻结与版本

路径	作用
lib/server/classroom-courseware-publish.ts	persisted classroom → 完整 frozen bundle
lib/bundle/packager.ts	bundle 组装、完整性和内容 hash
lib/bundle/serialize.ts	Stage/Agent/Scene/Action portable manifest
lib/courseware-repo	append-only 课件版本与 bundle bytes
lib/course-manifest-repo	schema v2 课程清单历史
app/api/courses/{id}/publish	暂存、二次校验、提交、失败补偿

learner

路径	作用
app/api/learn/courses	课程目录与精确 manifest；legacy 返回 409
app/learn/course/{id}	课程模块列表和精确 pin 导航
lib/bundle/learner-load.ts	严格身份/哈希/完整性校验与回滚
lib/import/import-classroom-core.ts	portable manifest → 原课堂 document
app/learn/{coursewareId}	加载并跳转 classroom
app/classroom/{id}	仍挂原 Stage；learner query 只加返回导航

7. 环境与数据目录

关键角色变量：

• OPENMAIC_DEPLOYMENT_ROLE
• NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE
• ACCESS_CODE
• ACCESS_CODE_SESSION_TTL_SECONDS
• OPS_PUBLIC_ORIGIN
• COURSEWARE_PUBLISH_TOKEN
• COURSE_PUBLISH_SERVER_BASE_URL
• COURSEWARE_PUBLIC_BASE_URL

严禁重新加入 NEXT_PUBLIC_COURSEWARE_PUBLISH_TOKEN。

关键目录变量：

• CLASSROOM_DATA_DIR
• CLASSROOM_JOBS_DIR
• COURSE_FRAMEWORK_DIR
• COURSEWARE_DATA_DIR
• COURSEWARE_BUNDLE_DIR
• COURSE_MANIFEST_DIR
• COURSEWARE_MAX_UPLOAD_BYTES
• COURSE_PUBLISH_MAX_UPLOAD_BYTES
• COURSE_PUBLISH_TIMEOUT_MS

模型按需配置 MODEL_ROUTES 与 provider/TTS/image/video/web-search 变量。 大课至少需要 course-framework 与原 generate-classroom/scene stages 可解析； 发布需要所有 speech 的持久化音频。

通用 NEXT_PUBLIC_PERSISTENCE、DATABASE_URL、ASSET_S3_BUCKET 不等于发布仓库已经迁移。 完整矩阵和示例见 deployment-3-tier.md。

默认数据：

目录	内容
data/classrooms	classroom JSON、本地 media/audio 子目录
data/classroom-jobs	单课件 job
data/course-frameworks	ops CourseRecord
data/coursewares	courseware 版本历史 metadata
data/courseware-bundles	id/version ZIP
data/course-manifests	course manifest 版本历史
data/usage	计量
data/tts-cache	QA/TTS 缓存能力仍在代码中

8. 单实例限制与未来存储

当前 version 分配与 read-modify-write 依赖进程内 Map 锁。临时文件 + rename/link 只能保证 文件操作层面的原子性，不能协调多个 Node.js 进程。发布失败只会由应用层把本批 记录补偿回 unpublished，不具有跨进程隔离性、原子提交或崩溃一致性。现阶段：

• ops/framework writer 单实例；
• server courseware/manifest writer 单实例；
• 生成和发布期间避免滚动重启；
• runner 中断后依赖持久记录自愈，再由运营续跑；
• 备份 metadata history 与 bundle bytes 必须成对。

公网生产上线或多实例前必须完成：

• Postgres 唯一键和事务分配 courseware/manifest version；
• 行锁或 advisory lock 保护每个 course/courseware；
• 对象存储以 id/version/hash 为 key 并 put-if-absent；
• CDN 只分发已被 schema-v2 manifest exact pin 的 immutable bundle；当前文件下载路由已用 同一门禁隐藏 promote→manifest 的中间状态，未来对象存储不能以公开 URL 绕过它；
• 持久任务队列取代内存 runner；
• ops 已可通过内部 HTTP 一次提交 metadata 与全部 bundle；独立部署必须配置 COURSE_PUBLISH_SERVER_BASE_URL，不再直接写 server 文件。

9. legacy manifest 重发

不要手工给旧记录填 current latest。

1. learner API 对旧记录返回 409，这是预期 fail closed。
2. 备份旧 singleton/history 文件。
3. 在 ops 打开原 CourseRecord 并运行发布校验。
4. 若缺 outputDigest、continuityInputRefs、Interactive HTML、音频或媒体，从最早失败模块 开始按顺序重生成。
5. 人工审阅后重发课程。
6. 新 manifest version 使用 schemaVersion=2 并精确 pin；旧版本保留审计但不可学习。
7. 若原 CourseRecord/classroom 已丢失，只能按新课程重新生产，不能伪造历史身份。

10. 验收结果与命令

已确认结果

检查	结果
首页双路径 Playwright	3 passed
learner 部署边界 Playwright	1 passed
三端角色/ops access 定向单测	通过
主 Agent、连续性、Interactive 回归	通过
冻结发布相关合并回归	10 files / 85 tests 通过
本次文档交接定向回归	18 files / 108 tests 通过
本次 TypeScript 检查	pnpm exec tsc --noEmit，exit 0
本次四文档格式检查	Prettier，exit 0
受保护课堂广泛回归	130 files / 1,294 tests 中 1,291 通过，3 个 Chat 基线漂移
本次隔离 Chat 复现	3 files；40 passed / 3 failed
i18n key check	exit 1；9 个非 zh-CN/en-US locale 各缺 180 个键

定向回归

在 OpenMAIC 目录执行：

pnpm exec vitest run \
  tests/config/deployment-role.test.ts \
  tests/server/ops-access.test.ts \
  tests/generation/foreground-session.test.ts \
  tests/server/classroom-outline-mode.test.ts \
  tests/server/classroom-generation-retry.test.ts \
  tests/course-framework \
  tests/bundle \
  tests/courseware

静态与构建

pnpm exec tsc --noEmit
pnpm build
pnpm exec prettier ../docs/architecture-3-tier.md ../docs/deployment-3-tier.md ../docs/large-course-mode.md ../docs/handover.md --check

浏览器边界

pnpm exec playwright test \
  e2e/tests/home-to-generation.spec.ts \
  e2e/tests/deployment-role-boundary.spec.ts \
  --project=chromium

i18n 已知缺口

pnpm check:i18n-keys

该命令当前预期失败，输出为 ar-SA、es-MX、fr-FR、ja-JP、ko-KR、pt-BR、ru-RU、 vi-VN、zh-TW 各缺 180 个相对 en-US 的键。运行时有 fallback，但发布前应补齐。

11. 已知 3 个受保护 Chat 基线漂移

隔离命令：

pnpm exec vitest run \
  tests/lib/chat/pi/director-tool-wiring.test.ts \
  tests/lib/chat/pi/route-cue-user.test.ts \
  tests/lib/chat/pi/prompts.test.ts

稳定失败：

1. tests/lib/chat/pi/prompts.test.ts
   • keeps concept and mechanism questions teacher-led before student reactions
   • 当前 prompt 明确课堂只有 teacher + user，旧断言仍期待 assistant fallback 文字。
2. tests/lib/chat/pi/route-cue-user.test.ts
   • hands successful web evidence to one child and clears it before later delegations
   • 旧 fixture 断言 URL 必须直接出现在 child prompt 字符串。
3. tests/lib/chat/pi/route-cue-user.test.ts
   • does not leak consumed web evidence after the selected child fails
   • 同属 evidence attachment 与旧 prompt 字符串断言漂移。

大型课程和冻结发布改造未修改 lib/chat/** 或 app/api/chat/pi。按用户确定的保护边界， 这 3 项只记录、隔离复现，不在本改造中修改 Chat 内核、prompt 或断言。

12. 未完成事项

按优先级：

1. 建立 Git 基线并备份 data/.env.local。
2. 完成 learner 用户身份、classroom/job owner、资源级授权、课程权益和成本限额。 在此之前，不得宣称匿名 Chat、生成、TTS、搜索等高成本 API 已安全。
3. 把 courseware/manifest metadata 迁到 Postgres、bundle 迁到私有对象存储，并在 CDN 层保留 manifest exact-pin 可见性门禁。
4. 按 deployment-3-tier.md 的顺序拆 server → learner desktop → ops；内部整批 HTTP adapter 已完成，可直接迁移而不是重新设计。
5. 将大课目录 localStorage 完成标记改为 runtime 进度聚合。
6. 补齐 9 个 locale 的 180 个键。
7. 在真实部署网络上补一条 ops → server → learner smoke；仓内已有两个隔离文件根、mock fetch 的无 LLM 跨进程契约测试。

拆分期间继续坚持：移动边界、替换 adapter、保持契约；不要复制或重写原 Stage/Chat。