wangxuming/openmaic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
openmaic/OpenMAIC/findings.md
inman 2d04197f3f chore: establish learning module baseline
2026-08-16 14:58:47 +08:00

40 KiB
Raw Permalink Blame History

Findings & Decisions

Requirements

  • 麦洛教育目标形态包含用户桌面端、运营端和后台数据服务。
  • 用户端保留原单课件生成 Agent，并使用运营端发布的大型连续课程。
  • 大型课程制作仅开放给运营端。
  • 主 Agent 围绕课程目标拆解全局框架，并为每个子模块生成提示词；人工确认后串行调用原单课件生成 Agent。
  • 发布后的每个模块完整保留原互动课堂、HTML 代码互动、原教师/助教、多 Agent 讨论、Quiz、PBL、白板和音频。
  • 不新增或重写课堂交互内核；改造集中在编排、权限、发布、目录和服务端外围。

Research Findings

  • 2026-08-16 用户正式确认：平台账号是课程资源、购买权益和跨设备学习记录的永久主体；设备身份只用于持有证明，未登录游客数据必须支持显式迁移到账号。

  • 当前 generation job store 的 updateClassroomGenerationJob 可用任意 patch 覆盖或清空 ownerPrincipalId，create 又始终省略 owner；因此先要把 owner 绑定从普通更新中剥离成单独的 compare-and-set/显式迁移操作。

  • 当前 observe helper 故意只返回 void，无法直接复用作 enforcement。最小安全演进应新增独立的 evaluate/enforce helper，保留 shadow 路径原响应，同时由显式环境模式决定是否 fail closed；不能偷偷把现有 observe 改成返回授权结果。

  • 在真实 session/device-proof provider 未接入前，production resolver 必须继续返回 unavailable；可先让创建路由在解析到 authenticated principal 时原子写 owner，并在 enforcement 模式下对 unavailable/anonymous/legacy-unowned 返回稳定错误，默认仍保持 shadow 兼容。

  • generation job 的 POST/GET-list 目前没有身份测试；list 在非 server 角色会返回全部 job。required enforcement 竖切必须同时处理 create、list、detail、cancel、resume、delete，不能只保护单资源路由而留下全局枚举。

  • 大型课程 runner 直接调用 job store 创建运营内部 job；owner 绑定参数必须保持可选，避免把 ops 编排误当 learner 账号资源。公开 API 创建才从已验证 principal 派生 owner/guest binding。

  • required 模式若先从全局 job 文件中截取 limit=20 再按 owner 过滤，会让活跃多用户场景中的本人任务被其他用户的新任务挤出结果；正确顺序必须是“归属过滤 → 时间排序 → 用户 limit”。文件仓库阶段可在 required 模式读取全集后过滤，未来数据库迁移应下推为带 owner 索引的查询。

  • 持久化 JSON 可能被旧版本或人工操作写成 owner+guest 同时存在；授权分类与迁移都必须将这种双归属视为损坏并 fail closed，不能因为先检查 owner 就忽略 guest。

  • owner 字段除运行时防御外还应从普通 update patch 的 TypeScript 类型中移除；显式迁移函数是唯一允许写归属字段的代码路径。

  • Phase 7 已落 provider-neutral 授权底座：RequestPrincipal 不绑定具体登录供应商，当前生产 resolver 恒为 unavailable 且不读取任何身份 header；纯 owner policy 对 legacy/unknown 给出 indeterminate，对 ops/service 身份不提供隐式越权。

  • generation job 的 detail/cancel/delete/resume 已接 observe-only seam，observer 只返回 void 且隔离同步/异步异常，现有状态码与响应体不依赖授权 decision；ownerPrincipalId 为可选字段，旧 JSON 仍可读取，新任务目前不会伪造 owner。

  • 独立审查未发现 observe-only 竖切阻断问题；未来接真实身份/遥测时必须增加超时或有界异步投递，并在创建资源时原子绑定不可被普通更新清空的 owner。

  • Phase 7 完成全量出站链路分级：proxy-media、Azure Voices、MinerU Cloud 验证已 DNS pin；专用 server 已隐藏 provider verify/probe，但 image/video/TTS/voice/ASR/PDF/extract 及 LLM BYOK 生成入口仍可能把客户端 baseUrl 交给二次解析的 fetch/SDK。

  • 旧 validateUrlForSSRF() 是“先解析校验、后由调用方重新解析连接”，仍有 DNS rebinding TOCTOU；ALLOW_LOCAL_NETWORKS 又同时放开 operator self-hosted 与不可信客户端 URL，必须拆成 server-managed public、operator-private 和 learner-BYOK 三类信任策略。

  • 当前最直接的链式 SSRF 是 provider 返回的二次 URL：MinerU Cloud 的 upload URL/ZIP URL、Qwen TTS 的 audio URL会被直接请求；这些 URL 即使首个 API endpoint 是公网，也必须再次执行 public allowlist/DNS pin/redirect/大小限制。

  • 自托管 model probe/PDF、企业 HTTP proxy 和 AI SDK 流式调用不能直接替换成 GET-only public helper；需要支持任意 method/body/stream 的 secure transport，或由可信 egress proxy 执行目的地址策略。

  • fetchPinnedPublicUrl 已扩展为有界 GET/PUT：只接受静态可测量 body，禁止覆盖 Host/Content-Length/Transfer-Encoding，上传前先做 50 MiB 默认上限，仍以单次 DNS 解析固定 Host/SNI 和连接地址。

  • MinerU 预签名 PUT 与结果 ZIP GET、Qwen TTS 返回音频 GET、AliDoc OSS 图片 GET 均已逐资源重新 pin；不把首个 API Bearer 转发给二次 URL，拒绝重定向并限制请求/响应体。

  • dedicated server 现通过中央 provider access policy 禁止 unmanaged client key/baseUrl；所有统一 LLM/TTS/ASR/PDF/image/video/web-search resolver 只接受运营配置。桌面/all、ops、learner BYOK 和运营配置的 Ollama/private self-hosted 保持原行为；无网络 unpdf 是明确例外。

  • 当前已有两阶段大课骨架：框架生成后停在 framework_ready，人工确认后按顺序创建并运行 classroom generation job。

  • CourseModuleSpec 目前只有标题、说明、目标、前置条件和时长，没有主 Agent 输出的模块级 generationPrompt。

  • runner 仅把说明、目标、前置条件和泛化连续性提示拼成 requirement；没有传递 languageDirective，也不读取前序模块实际产出。

  • 大课模块复用了服务端单课件生成管线，发布后的学习路径最终仍进入原 <Stage>。

  • learner 模式在原 Stage 外额外挂载了自包含 AssistantPanel，形成与原 ChatArea 并行的第二套助教。

  • 大课后台生成没有使用前台 Interactive Mode 的专用 outline prompt，因此可能生成很少或没有 HTML 互动场景。

  • 首页在材料、互动模式或职教模式开启时只 toast 后 return，没有进入仍存在的 /generation-preview。

  • /courses 页面和 /api/courses/** 缺少运营角色服务端鉴权；发布 Token 通过 NEXT_PUBLIC_* 暴露到浏览器。

  • 大型课程 manifest 只保存 coursewareId，没有固定模块版本和 contentHash。

  • 当前目录没有 Git 仓库；已有定向测试曾达到 14 个文件、83 个测试通过，i18n 检查仍有多语言缺失键。

  • middleware.ts 只在配置 ACCESS_CODE 时校验 HMAC cookie；未配置时全部请求放行，且页面请求即使未认证也继续进入前端。

  • 首页 startBackgroundGeneration 在存在课程材料、互动模式或职教模式时于 app/page.tsx:169 仅 toast 后返回；否则 POST /api/generate-classroom。

  • /generation-preview 通过 sessionStorage['generationSession'] 恢复输入，说明首页恢复前台流程必须先写入兼容的 generation session，再导航，不能只做裸 router.push。

  • app/classroom/[id]/page.tsx 先渲染原 <Stage>，随后仅在 learner query 下额外挂载 AssistantPanel；删除该 import/条件挂载即可恢复原课堂助教唯一性，不需触碰 Stage。

  • 首页大型课程入口目前无条件渲染；lib/config/feature-flags.ts 还通过 NEXT_PUBLIC_COURSEWARE_PUBLISH_TOKEN 决定浏览器侧发布能力，课程构建页直接读取并发送该公开变量。

  • 前台生成会话的最小必需结构由 app/generation-preview/types.ts 定义：sessionId、requirements、pdfText、currentStep，并可带 documentSources、图片、outline 与 preview phase。

  • 无材料时可直接写入 requirements.requirement/language/webSearch/interactiveMode/vocationalTestMode 等状态；有材料时必须先用 storeDocumentBlob 持久化每个 Blob，再写入含 storageKey 的有序 documentSources。

  • 现有 home-to-generation 与 full-happy-path E2E 仍断言普通首页提交进入 /generation-preview，但当前产品决定应调整为：普通无材料模式走后台任务，材料/互动/职教模式走前台预览。

  • isCoursewarePublishEnabled() 和 getCoursewarePublishToken() 当前均依赖 NEXT_PUBLIC_COURSEWARE_PUBLISH_TOKEN；课程构建页把它作为 Bearer header 发回同源 API，不能作为运营安全边界。

  • UserRequirements 已原生支持 webSearch、interactiveMode 与 taskEngineMode；职教开关应映射到 taskEngineMode，而不是另造 session 字段。

  • generation-preview 的 active steps 会在 documentSources 存在且 pdfText 为空时自动执行材料解析；storeDocumentBlob(File) 返回 IndexedDB storage key，正好用于首页会话构造。

  • 语言由 useI18n() 提供 locale；UserRequirements 类型本身没有 language 字段，当前生成语言主要由服务端 outline 结果的 languageDirective 决定，因此首页无需为了恢复链路新增未使用的 language 字段。

  • 部署边界现采用双层校验：服务实例角色决定是否具备 manage_courses，ops 生产环境还必须由现有 HMAC ACCESS_CODE cookie 认证；生产未配置角色默认 learner。

  • COURSEWARE_PUBLISH_TOKEN 已收回服务端：同源 ops 发布由角色+ACCESS_CODE 会话授权，独立 server 部署仍用 Bearer Token 接收远端 ops 发布。

  • readCourseRecord 目前直接把 JSON 断言为 CourseRecord，没有 schema migration；新增框架字段必须在读取时规范化，或让所有消费者都安全 fallback，否则旧文件会在 runner 访问新字段时失效。

  • validateCourseFramework 目前只校验标题、语言、摘要和 4–15 个模块；模块索引会重排，时长会夹在 5–60 分钟，但主 Agent 输出没有课程目标、连续性契约、模块生成提示词或知识边界。

  • runFrameworkPhase 手工复制模块记录，只保存标题与说明；应复用 emptyModuleRecord 并保存生成提示词快照，确保之后框架再生成或模型输出变化时有可审计输入。

  • buildModuleRequirement 当前硬编码 15–25 分钟，忽略 estimatedMinutes，也没有拼入 languageDirective；这是 Phase 2 可以在大课编排层修复的明确数据丢失点。

  • Phase 2 已把新模型输出和旧存量分成两条边界：新输出严格要求课程目标、连续性契约、模块提示词和知识边界；旧 JSON 只在 read/list 时确定性规范化，读取不会主动改写磁盘。

  • 运营确认页已改用共享 CourseDetail 类型，并在确认前展示目标学习者、语言、整课目标、四项连续性契约及每模块知识边界/生成提示词。

  • course runner 原先只按 run key 去重，不同 key 的整课生成与单模块重试可以并发；现在 runner 以 courseId 做互斥，所有 start/resume/regenerate 入口也会在调度前检查并立即登记运行。

  • 后台 GenerateClassroomInput 目前没有 interactiveMode，构造的 UserRequirements 也只有 requirement；因此大课 runner 即使复用单课件管线，也只能进入 package 的普通 requirements-to-outlines prompt。

  • 原前台 Interactive Mode 是 app 层 INTERACTIVE_OUTLINES 模板（目标 70% widgets）；package 的 generateSceneOutlinesFromRequirements 负责统一解析/补 id。最小复用方式是在服务端仅替换传给该函数的 outline aiCall prompt，继续复用其解析与后续 content/action/persist 管线。

  • classroom job 成功记录只保存 classroomId 和 scenesCount；runner 可从服务端持久化 classroom JSON 读取四类 Scene 实际内容，生成有界、确定性的 output digest，再把此前成功模块的 digest 注入下一模块 requirement，无需改课堂运行时。

  • Phase 3 已在模块成功后从持久化 classroom 提取四类 Scene 的实际语义证据，保存 semanticHash；后续模块记录 continuityInputRefs 并只在所有前序模块有成功实际产出时继续。

  • 全课程流水线现在遇到模块失败即暂停；失败模块修复后，同一个课程 run 会按顺序继续剩余 pending 模块，避免在知识断层上生成后续课件。

  • 后台 Interactive Mode 复用原 app prompt 模板，只替换 outline AI call，仍走 package 的解析、content、actions 和原子持久化；持久化前强制至少一个 interactive Scene 具有非空 HTML。

  • output digest 会过滤 script/style、data URI 和 learner runtime，并保留所有前序模块的哈希索引；详细 evidence 受 12k 上限约束且优先近期模块。

  • Phase 4 漂移根因是 course manifest 只保存 coursewareId，learner 又查询 latest；正确不可变身份必须是 coursewareId + coursewareVersion + contentHash，传输 URL 只能由该身份派生。

  • 文件型 courseware 与 manifest 原先都允许同版本覆盖或覆盖 latest；现已改成历史记录/append-only，并在单进程发布锁中完成版本分配和保存。多实例仍需要数据库唯一键或跨进程事务作为后续部署约束。

  • 服务端生成的课堂素材位于 data/classrooms/<id>/{media,audio}，Scene 中却保留 /api/classroom-media/... URL；冻结发布必须先把这些 URL 解析成字节和稳定 bundle ref，不能让 learner 依赖运营端源文件。

  • 原序列化同时保存 audioRef 与 audioUrl，而播放器优先 URL；冻结包必须在已有 audioRef 时删除远端 URL，才能真正离线且不漂移。

  • 大课发布要求每条 speech 有持久化音频，因此大型课程生成统一启用 TTS；缺少 provider/字节时允许运营预览，但发布门禁失败并指出缺失资源。

  • Agent persona/voice 与 Stage 初始 whiteboard 原先未完整冻结；它们属于发布数据契约而非课堂运行时逻辑，已在外围序列化/导入和 server publisher 中补齐。

  • “冻结学习包”只禁止 outline/scene/media 的课程生成调用；原 ChatArea/Roundtable、动态评分和 PBL 教学运行时仍可正常调用模型。

  • 受保护核心广泛回归的 3 个失败属于既有 Chat director 契约内部漂移，隔离重跑仍稳定复现：当前 director prompt 明确写“课堂只有 teacher + user”，但旧测试仍期待 assistant/student fallback；web evidence 的源码具备一次性 take/attachment 路径，但这两条 route fixture 没有把 URL带入 child turn。Phase 4 未修改 lib/chat/** 或 /api/chat/pi，因此按用户边界记录而不在本改造中修写 Chat 内核。

  • 现有 Playwright 已覆盖 learner 部署拒绝 ops、首页普通后台任务和互动/材料前台单课件路径，但没有大型课程的真实发布→manifest→精确模块 URL；Phase 5 应优先用无 LLM 的 Vitest/route 集成夹具补这条数据边界，再用少量浏览器 smoke 验证 UI 导航。

  • Playwright 原先在 development 启动服务且未声明部署角色；development 按设计 fallback 为 all，导致 learner 边界用例与其环境互相矛盾。E2E 默认服务现显式固定为 learner；未来 ops 浏览器测试应使用独立 project/server 配置。

  • learner 角色下 / 不保证提前打开 MAIC-Database；classroom-interaction.spec.ts 的旧 seed helper 直接 indexedDB.open() 后在缺表时同步抛错却没有 reject，Promise 因而悬挂到超时。该失败属于 E2E fixture 假设（注释仍写 DB v8，而当前已 v17），可在测试层显式初始化 Dexie/捕获事务创建错误，不需改课堂运行时。

  • 课堂文档的当前权威存储是 BrowserDocumentStore 使用的 maic-documents v1（stages/scenes/outlines）；Quiz、Playback 和 iframe E2E 已按该契约显式 seed。classroom-interaction.spec.ts 仍写入旧 MAIC-Database 的 stageOutlines，应仅在测试夹具中迁移到前者。

  • Phase 5 已有无 LLM 的真实文件仓储集成证据：两模块冻结发布生成 schema v2 精确 pin manifest；中途冻结失败会回滚已暂存模块且 learner 端不可见；manifest v1 在模块独立发布 v2 后仍精确指向 v1。

  • 三端最终边界审计表明：当前闭环仅在“同进程、单副本、共享本地文件库”条件下成立。Docker 未传构建期公开角色；server 尚非无头 allowlist；ops → server 没有跨进程 manifest 事务接口；文件库+内存锁不支持多实例/Vercel。

  • learner 可见 manifest 目前暴露与源 classroom 相同的 coursewareId，而 raw /api/classroom 没有资源权限；多用户共享 server 下 job 列表/读取/取消/删除也没有 owner。这两项属于正式上线前必须建立的资源级边界。

  • 已定位的可独立修复外围漂移还包括：learner /tasks 把 /api/courses 403 与正常 job 绑在同一 Promise.all；首页无 /learn 目录入口；/publish 未纳入 ops gating；上游成功模块重生成不会级联失效下游；浏览器重发的 ZIP 内部 version 可能仍为 1。

  • 合并 Playwright 单 worker 回归已在干净 learner dev server 上 11/11 通过：先前的 iframe 场景标题和 generation redirect 失败不可隔离复现，与并行干扰/残留 server 一致，不应对原 Stage 代码做“修复”。

  • 源 classroom 与公开 module id 可以在外围完整解耦：新发布使用 course_{courseId}_module_{index} 稳定公开 id，registry 私有保存 sourceClassroomId，公开 summary 不返回；learner/server 可用该私有关联拒绝 raw classroom 旁路，同时兼容拦截旧的 shared-id 记录。

  • 源 classroom 反查是授权路径，不能复用“公开列表跳过损坏 JSON”的宽容语义；文件 repo 因此增加了严格 hasPublishedSource 反查，任一 registry 文件损坏时 raw source 请求 fail closed。

  • 浏览器 packager 无法无竞态地预知 next version；可行契约是 server 在 per-courseware lock 内分配版本，仅改写被 content hash 明确排除的 bundle.json.meta.version，再保存 ZIP。learner 必须同时校验 registry、包内 version 和 hash。

  • 上游模块重生成不能仅修目标模块；当前做法是一次原子清空 N..end 的所有尝试/输出字段并将课程置为 generating，随后顺序重建；失败会保留后续 pending，既有 resume 可续跑。

  • NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE 必须在 pnpm build 之前注入；只在容器运行时设置会造成权限与 UI 不一致。Docker 现在对 learner/ops/server 分别构建，并在运行层固定相同角色。

  • learner 冻结课堂的“不再生成”应是路由外层明确策略，而不只依赖 bundle 恰好没有 outlines；现在 learner mode 即使遇到异常缓存也不调 Scene/媒体生成，作者课堂恢复逻辑不变。

  • 跨进程发布的可复用边界已定位：ops 可用 packagePersistedClassroom(..., version: 1) 生成完整 ZIP 模板；server 的 publishCourseware 会在每个 courseware 锁内分配真实版本、重写 bundle.json version 并重验 hash/完整性，因此运输层不应复制这些门禁。

  • 当前大课发布 route 的事务边界全在 ops 进程：本地写 unpublished courseware、二次验证源快照、切 published 再写 manifest。独立部署必须把“metadata + 全部 ZIP”作为一次 server-only 批量请求，并在 server 一个 course 互斥边界内复用 publishCourseware、publishCourse 和 status rollback。

  • 现有 /api/coursewares 只能单 ZIP multipart 上传，已有 COURSEWARE_MAX_UPLOAD_BYTES 单模块上限和 Bearer 校验；大课远程 transport 需在此之上再增加整批 Content-Length/实际 File size 上限，不能仅信任客户头。

  • 文件 repo 可以把本批版本状态补偿为 unpublished，bundle byte store 也支持删除单个版本；当前 manifest repo 是全局实例，为做真实隔离仓库测试，publishCourse 需增加可选 CourseManifestRepo 注入，生产默认仍用原全局 repo。

  • runCoursePublishExclusive 已提供每 course 单进程互斥；server 批量接口可直接复用。它不是跨副本锁，因此文档仍必须保留“多实例上线前迁到数据库事务”限制。

  • 远程发布的安全重试可不新增独立 idempotency 表：server 在 staging 前解析/重算全部 incoming ZIP hash，再将 latest schema-v2 manifest 的课程 metadata 与 module index/id/title/description/hash 精确比较；完全一致时直接返回旧 manifest，超时重发不会产生空转版本。

  • ops 详情当前只查本地 courseware repo 并比较私有 sourceClassroomId；独立 server 下必然误显示“未发布”。最小闭环是在 ops CourseRecord 保存一份精确 publication receipt（manifest version + 每模块 source classroom/digest + id/version/hash），详情仅在 receipt 与当前源身份一致时显示已发布；从任意模块开始重生时清除整课 receipt。

  • ACCESS_CODE 原先的 HMAC 会话没有过期语义、登录限流或 Cookie 写请求的 Origin 检查；现在 Node/Edge 共用同一时效契约（默认 7 天），登录使用有界单进程限流，只在显式信任代理头时按客户 IP 分桶。

  • server 角色不能只是“隐藏运营入口”；它必须是无头服务。当前 middleware 已将全部非 API 页面以直接 404 隐藏，并将 courses/ops/access-code 信任域从 server API 面移除；其余课堂/生成 API 仍等待 owner 契约，不应被误宣称为已完成多用户安全化。

  • 项目已有 capBodyStream，可在 formData() 之前包裹请求 stream，因此整批上传能同时防 Content-Length 谎报和 chunked 无上限缓冲；解析后仍逐模块检查 File.size。

  • internal server 接口不应用 request Host 生成 registry bundleUrl，否则会把 ops 访问的内网 hostname 固化给 learner；生产必须用严格 origin 形式的 COURSEWARE_PUBLIC_BASE_URL。

  • publication receipt 存在时必须 fail closed：若当前 classroom/digest 与 receipt 不符，不能再 fallback 到本地 latest sourceClassroomId；只有完全没有 receipt 的 legacy/shared-FS 记录可用旧查询兼容。

  • 除模块级 invalidateCourseModulesFrom 外，整个框架重生路径会直接将 framework/modules 置空；该原子更新也必须同时清除 publication receipt，避免新框架尚未产生时运营端仍持有旧发布身份。

  • 新冻结包使用 contentHashVersion: 2：哈希规范化时忽略仅表示导出时刻的 manifest.exportedAt，因此相同课堂字节在网络超时后重新打包仍能命中 server 幂等判断；无版本字段的历史包继续按原始 v1 规则验证，避免破坏已发布内容。

  • ops → server 已使用一次 multipart 传输 metadata+全部 ZIP；remote/local 共用同一 commit 内核，同内容重复发布均返回原 manifest，响应丢失不会制造空转版本。

  • 大课模块的 registry 记录私有保留 courseId/moduleIndex/sourceClassroomId；公开 catalog/detail/download 只在 schema-v2 manifest 包含精确 id/version/hash pin 后可见。

  • 发布回执新增全量 canonical classroom sourceRevisionHash，不再仅靠会丢弃 script/style/media/action 细节的语义摘要判断当前性；HTML 脚本单独变化也会使发布状态失效。

  • classroom/courseware 文件库已在路由、facade、record store 和 byte store 多层校验 id/version 与 resolved path；同版本幂等命中前会读回实际 ZIP，核对完整性、内部身份、私有归属和精确字节，缺失/损坏不再返回假成功。

  • OPS_PUBLIC_ORIGIN 是 cookie-authenticated 运营写请求的 canonical Origin；X-Forwarded-Host 即使用于可信 IP 限流，也不再能扩充 CSRF 允许域。

  • server 端其余课堂/单课件 API 仍需要 learner identity/entitlement 契约；不能为了隐藏高成本 API 而直接禁用原 Chat、Quiz、PBL、TTS 或用户端单课件生成。

  • /api/proxy-media 不是原课堂教学运行时必需合约，且存在 DNS-rebinding 窗口；server 角色现已对其直接 404，同时 SSRF IP 分类补齐 RFC6598 100.64.0.0/10（含阿里云 100.100.100.200）。其他用户控制 URL 的服务端 fetch 仍应在正式身份契约阶段统一切换到 pinned-resolution safe fetch。

  • server 无头边界已额外隐藏 provider 探测/验证、MP4 export、开发态 persistence、usage 和无 owner 的全局 job 列表；单课件 POST 与原课堂运行时端点保留，等待 learner capability。

  • generation job DELETE 原先可绕过 raw classroom 读取保护删掉已发布源；现在会先做 fail-closed published-source 反查，命中时 job 与 classroom 都保留。

  • QA/TTS 进程内限流默认不信任 XFF/X-Real-IP，仅在 LEARNER_RATE_LIMIT_TRUST_PROXY_HEADERS=true 且入口覆写头时启用；活跃 key 采用硬上限+共享 overflow bucket，不再无界增长或每次全表 reap。

  • manifest metadata/hash 相同不足以证明一次重试仍可用；幂等返回前必须读取 exact bundle bytes，并复用完整单课件 publish gate 验证内部 id/version/hash、重算 hash、complete 与 portable 资源。对象丢失或只篡改未参与 hash 的 bundle.json 都必须拒绝旧幂等命中并生成新版本。

  • 文件补偿事务不能提供数据库隔离，但大课 record 的私有 courseId/moduleIndex 可以建立最小可见性门禁：catalog、detail、download 只有在任一已提交 schema-v2 manifest 精确 pin 该 id/version/hash 时才公开，因此逐模块 promotion 到 manifest commit 之间不会泄漏给 learner。

  • 同源共享文件 fallback 已复用与远程 server 相同的批量 transaction helper，远近端现在对相同 metadata + 内容都幂等；显式重复点击也是 no-op，当前没有 forceNewVersion 契约。

  • Phase 6 已完成可在单实例文件仓库边界内可靠验证的三端隔离、跨进程发布、冻结内容身份、源 revision 和高风险 server deny；数据库事务、对象存储、共享锁/限流及 learner owner 不是同一层面的“收尾”，已独立迁入生产化阶段。

  • 专用 role=server 已通过 404 隔离 /api/proxy-media 并补齐 100.64.0.0/10，但 learner/all 公网部署仍需要连接级 DNS pin：仅在校验阶段解析域名不足以抵御 fetch 时的二次解析和重定向变址。

  • 身份机制不能替代 SSRF 防护；safe-fetch 可在不决定账号模型的前提下先落地。job/classroom owner、课堂运行时调用额度与单课件生成权益则会改变公开/登录产品体验，必须在身份方案确定后实施。

  • 项目已直接依赖 undici，可通过自定义 dispatcher/连接 lookup 把请求连接绑定到预先验证的 IP，同时保留 URL hostname 供 Host 与 TLS SNI 使用；现有 /api/proxy-media 的逐跳 URL 校验仍使用全局 fetch，尚未绑定到验证结果。

  • 当前依赖中没有 NextAuth/Better Auth/Lucia/Clerk/JWT/Jose 等正式账号或 Session 库，只有 pg 和面向运行时/文档/资产的存储包；现有 PERSISTENCE_DEV_TOKEN + x-learner-key 已在源码中明确标注为开发态、客户端可伪造，不能升级命名后当作 learner 身份。

  • 现成 Postgres document/runtime/asset stores 可以承载学习状态，但没有 users/devices/sessions/entitlements/resource ownership schema；正式身份必须新增独立 auth 数据模型，并由服务端 claim 派生 learner principal，不能继续信任浏览器提交的 learnerKey。

  • learner 身份的推荐终态不是账号 Session 与设备 capability 二选一：账号内部 UUID 是权益、跨设备和找回主体；桌面端用系统浏览器 OAuth 2.1 Authorization Code + PKCE，并用设备密钥/DPoP 证明令牌持有；打开课堂时再签发 5–15 分钟、绑定 coursewareId + version + contentHash 的 runtime grant。

  • RequestPrincipal 应统一承载 user/device/ops/service 四类主体，owner、learnerKey 和配额主体都只能从服务端 claim 派生。job/classroom/render/voice/draft 必须服务端写 owner；跨 owner 查询统一 404，随机 ID 不能代替授权。

  • 课堂 runtime grant 只约束外围 API：Chat/QA/Quiz/PBL/TTS 先校验 exact classroom/courseware 资源、action scope、entitlement 与 quota，再进入现有 handler；不需要修改 Stage、ChatArea/Roundtable、Quiz/PBL 或播放内核。

  • 当前 /api/qa 按 coursewareId 读取 latest，未来必须改为 grant 固定的 version/hash；现有大课 manifest exact pin 不能在动态答疑层被 latest 查询绕过。

  • 身份实施前仍需产品确认：正式发布是否强制登录/保留邀请码游客；桌面技术形态与登录渠道；是否首版多租户；目录/manifest/bundle 是否公开或需 entitlement；离线下载不可撤回的接受度；BYOK 是否开放及是否经过平台；学习进度是否需要跨设备/教师/证书级可信。

  • 无需等待产品选择的安全不变量是：内部 UUID 主体、服务端派生 owner、短期 exact-resource grant、动态高成本 API fail closed、事务配额预留、旧 legacy_unowned 数据不自动认领、原课堂内核保持不变。

  • server 精确路径策略不能只看 GET：Next.js 可从 GET 派生 HEAD，而尾斜杠会绕过 未规范化的精确比较。当前全局 job 列表已同时隐藏 GET/HEAD，内部发布在路径 规范化后仍只允许 POST。Azure voices 列表属于 provider 探测，也不再暴露于专用 server。

  • remote ops 不挂载 server courseware registry，因此已发布 source 保护必须同时查当前 CourseRecord.publication 回执。回执与 registry 反查都是授权路径，损坏时 fail closed。

  • 发布最终复核与 receipt 落盘之间存在 source DELETE TOCTOU；当前用同进程多 source 原子 claim 与单 source delete claim 互斥，冲突返回 409。这与其他内存锁一样不跨副本。

  • 当前 publication receipt 会在重生时清除；旧已发布 source 是否必须永久保留没有 产品契约，本轮不新增历史索引。跨进程提交后本地 receipt 写失败/响应丢失的窗口也只能 由持久 idempotency/outbox 与数据库事务最终消除。

  • courseware record/bundle 之外，course manifest 文件仓库也必须在自身边界校验 id 和 safe positive version，并只解析配置根目录的直接子文件；不能只依赖当前 HTTP 路由的上游校验。

  • 新的 public URL fetch 边界采用“每跳单次 dns.lookup(all) → 任一非 global-unicast 即整跳拒绝 → Undici Agent lookup 只返回已验证集合 → 手动重定向重新建 Agent”的连接级契约；URL hostname 保持不变，因此 Host/TLS SNI 不需要改写为 IP。

  • public media policy 明确忽略全局 ALLOW_LOCAL_NETWORKS，拒绝凭据 URL、IPv4 mapped IPv6、CGNAT/metadata、文档/benchmark/multicast/reserved 与 IPv6 transition/documentation 范围；内部自托管 provider 的例外不能外溢成匿名公网代理。

  • /api/proxy-media 已改为 8 KiB 声明+实际 JSON 流上限、最多 5 次逐跳 pinned redirect、25 MiB transport/读取上限和泛化错误。连接 dispatcher 只在响应体读取/取消后关闭，避免释放过早又不遗留 socket。

  • 远端发布的 ops 进程没有 server 端 courseware registry，因此“是否为已发布 source”的删除保护不能只查本地 registry；现以 current CourseRecord.publication.modules[].sourceClassroomId 作为现有远端回执 fallback，并对损坏回执 fail closed。框架/模块重生成清掉 current receipt 后是否永久保留旧 source，仍是历史审计产品语义，不在本批擅自增加永久索引。

  • 发布从课堂快照、冻结、远端提交到回执落盘期间，与 job DELETE 共享按 source classroomId 的同步 claim；这样删除无法在最后 revalidate 与 receipt 写入之间穿过。该 gate 仍是单 Node 进程语义，多实例要由数据库 CAS/锁取代。

  • 专用 server 对 ownerless 全局 job list 的隐藏必须同时覆盖 GET 与 Next 自动派生的 HEAD；内部 publish 也必须在带尾斜杠时维持“仅 POST”。无客户端调用的 /api/azure-voices 属 provider 探测，已从专用 server 面隐藏。

  • course manifest 文件仓储现在也在自身边界校验 courseId、safe-positive version 与 direct-child 路径，不再只依赖上游 route/transaction；这与 courseware record/ZIP 的多层路径防护一致。

  • outbound 初盘显示剩余风险不是一个入口：provider probe、Azure voices、PDF/ASR/TTS、image/video adapter、文档解析、模型 SDK 和素材下载都有 URL/baseUrl fetch。必须区分客户端 URL 与运营配置的 managed URL；后者可能是私网自托管服务，不能被 public-only policy 静默破坏。

  • Azure voices 与 MinerU Cloud 这类明确公网、单次 GET 且拒绝重定向的路径可直接复用 pinned helper；image/video/voice/AI SDK 涉及 POST、轮询、provider fallback 或 SDK 自己的 fetch 注入，应按 adapter 设计逐批迁移，不能用一次全局替换冒险。

  • /api/provider/probe-models 原本也支持 ALLOW_LOCAL_NETWORKS 下的本地自托管模型。正式方案要么在身份保护后用 operator 精确 host allowlist + pinned connection，要么保持专用 server deny；不应为了 SSRF 修复把桌面自托管能力无提示删除，也不能继续用“允许任意私网”的全局开关。

  • 身份供应商未定不妨碍先建立纯策略，但必须显式区分 anonymous 与 resolver_unavailable：当前没有 learner authenticator，后者不能伪装成游客。ownership 决策只接受服务端 owner/principal/capability，不从 IP、ACCESS_CODE、anon:*、x-learner-key 或 body 推导。

  • observe-only authz seam 只有在接入至少一个真实资源时才有价值；首个选择 generation job，可让旧记录的 owner missing 与未来 owner match/mismatch 被结构化观察，同时保持所有现有 status/body 不变。observer 不能返回 allow，抛错也不得影响请求。

  • 永久权益主体仍需用户确认。推荐以正式账号内部 UUID 为永久 owner，设备 capability 仅作为账号绑定持有证明或可迁移游客身份；具体手机号/邮箱/微信/SSO 供应商可以以后再选。

  • public pinned helper 已最小支持调用方提供认证头，同时拒绝覆盖 Host，保持原 URL hostname 驱动 Host/SNI。Azure voices 与 MinerU Cloud probe 已迁移；它们拒绝重定向，因此订阅 key/Bearer 不会跨 host 转发。

  • 为保留原自托管能力，本批没有把 model probe、PDF self-hosted、AliDocMind SDK 强制切成 public-only；AI SDK 与 image/video adapter 也未动。这些调用点仍需“public pinned / operator exact private allowlist / managed internal”三类明确策略后再迁移。

  • 账号 owner 传递到课堂的最小边界已确认：generateClassroom 的服务端 options 可承载 owner，job runner 从已落盘 job 读取 owner 后传入；不应把 owner 放进客户端可控的 GenerateClassroomInput。

  • 当前 PersistedClassroomData 没有归属字段，/api/classroom 的 POST/GET 也没有资源级授权；发布可见性门仅保护“已发布原始课堂”，不能代替 owner 校验。

  • 课堂归属必须保存在 Stage/Scene 之外的持久化包装中，避免改动原互动课堂 DSL 与播放内核。

  • 课堂重复 POST 是一个隐含的 owner 篡改面：对已存在课堂必须先按旧 owner 授权，并保留旧归属；只有首次持久化才从当前服务端 principal 创建 owner/guest 绑定。

  • 生成课堂必须以已落盘 job 的 owner 为权威来源，不再从长任务结束时的请求上下文推导；当前 runner 已按此传递。

2026-08-16 生成任务恢复故障发现

  • Python 普通课件 job Xjk5UcLtOx 在本次检查时仍可推进到 scene 5/10、已完成 4 个场景；说明当前后端没有持续挂死，用户点击“继续”确实启动了新的生成尝试。
  • 初一英语大型课程 S9V3Mm0AWy 的模块 1 job 在本地时间 12:09 左右开始，最后一次模型使用记录在 12:17:44；当前 Next 进程启动于 12:19:07，之后旧 runner 不再更新该 job，12:43 左右读时被判为 Stale job: process may have restarted during generation。这能证明“进程重启/runner 失联”是本次大课失败的直接机制，但不能单凭现有日志区分崩溃和人工重启。
  • readClassroomGenerationJob 的 stale 判断只比较 updatedAt，并返回内存中的 failed 视图；它不知道当前进程是否仍持有活跃 runner，也没有 heartbeat/lease，因此长模型调用超过 30 分钟时可能误报，进程重启时又只能在下次读取才暴露。
  • runClassroomGenerationJob 的 runningJobs、runningControllers 和大课 runningRuns 都是进程内 Map；磁盘只保存状态和原始输入，不保存 runner 接管 token 或可恢复执行上下文。
  • generateClassroom 的 Stage、outlines 和 generatedScenes 都在内存中；正式 persistClassroom 只在所有场景、媒体/TTS 阶段结束后调用，取消或进程终止不会留下正式 classroom，也没有场景级 checkpoint。
  • 普通 job 的 resume 路由与 runner 注释明确规定“从 persisted input 重新开始”；大型课程 resume 只跳过 succeeded 模块。故障发生在模块 1 时，后续模块尚未成功，用户看到的就是整门大课重跑，而不是框架被重新生成。
  • 课程 reconciliation 把 stale/failed classroom job 变成 module.status = failed 并清空 jobId；随后普通 resume 创建新 job，旧 job 的任何中间产出没有引用入口。这是大课无法复用模块内 checkpoint 的第二个结构性缺口。
  • 恢复协议必须把“逻辑 job、attempt/lease、checkpoint”和“正式课堂可见性”分开：checkpoint 用于恢复，正式 classroom 仍保持完成后原子发布；旧任务没有 checkpoint 时才退化为从头重跑。

Technical Decisions

Decision Rationale
第一批先做权限、入口和 learner 外围收敛 都是 P0 边界问题，可在不碰课堂内核的情况下独立验证
权限同时区分部署能力与请求用户角色 仅隐藏 UI 或仅靠环境变量不足以保护运营 API
平行 AssistantPanel 从课堂外层取消挂载 恢复原 ChatArea/Roundtable 的唯一性，无需修改课堂内核
大课连续性字段采用兼容性 fallback 已有文件型课程记录不能因新增字段失效
新框架字段在边界处规范化，runner 只消费规范化结果 避免把旧数据兼容判断散落到生成管线和 UI
generationPrompt 由主 Agent 生成并在模块记录中保留快照 满足主 Agent 拆解职责，并让每次子课件生成输入可追溯
同一课程同一时间只允许一个生成 run 保证模块顺序和快照语义，避免恢复、整课流水线与单模块重试互相覆盖
新大课 manifest 只接受精确 version/hash pins 防止模块单独重发后旧大课静默切到 latest
legacy 无 pin manifest 要求运营重新发布 历史记录没有保存当时版本，不能把当前 latest 伪装为原始事实
服务端课堂先冻结成自包含 bundle，再提交课程 manifest learner 不依赖运营端媒体 URL，同时仍通过原 import → Stage 链路上课
大课冻结发布强制 TTS、Agent roster 与非空互动 HTML 发布后保证原有语音、教师人格和 HTML 互动能力可重放

Protected Runtime Evidence

  • components/stage.tsx 装配 PlaybackChromeRoot 与 InteractiveIframeHost。
  • components/stage/scene-renderer.tsx 是 slide/quiz/interactive/pbl 的唯一分派器。
  • components/edit/PlaybackChromeRoot.tsx 装配 ActionEngine、PlaybackEngine、Canvas、Roundtable 和 ChatArea。
  • InteractiveIframeHost.tsx、iframe pool 和 widget messaging 维持 HTML iframe 保活及安全契约。
  • lib/bundle/serialize.ts 与 import builder 已保留 scene content、actions、scene whiteboards 和 multiAgent 字段。

Issues Encountered

Issue Resolution
DeepSeek Harness 首次任务未进入工具清单 重启桌面应用后已成功加载并完成只读自检
无 Git 历史，现有定制改动均为未版本化状态 使用计划文件记录范围，限制并行任务触及不同文件，并逐批验证
用户要求停止使用 DeepSeek 算力 后续不再调用 Harness；主线程完成实现与本地验证

Resources

  • 产品与部署文档：../docs/
  • 大课编排：lib/course-framework/
  • 服务端单课件生成：lib/server/classroom-generation.ts
  • 课程运行时入口：app/classroom/[id]/page.tsx
  • 原课堂：components/stage.tsx、components/edit/PlaybackChromeRoot.tsx
  • 发布与学习包：lib/bundle/、lib/course-manifest-repo/