427 lines
21 KiB
Markdown
427 lines
21 KiB
Markdown
# 麦洛学习三端部署与运维
|
||
|
||
> 事实基线：2026-08-15
|
||
>
|
||
> 当前是一份 Next.js 16.1.2 代码、三种部署角色，不是三个已经拆开的应用。
|
||
> 本手册先说明当前可运行方式，再给出 server → learner desktop → ops 的机械拆分顺序。
|
||
|
||
## 1. 角色解析与真实保护范围
|
||
|
||
| 值 | 用途 | 生产默认 | 大型课程运营能力 |
|
||
|---|---|---|---|
|
||
| learner | learner desktop 公共表面 | 未配置角色时采用 | 无 |
|
||
| ops | 内部运营工作台 | 必须显式配置 | 有，且生产必须配置 ACCESS_CODE |
|
||
| server | 课件/课程清单服务端 | 必须显式配置 | 无；可用 Bearer token 接收课件 |
|
||
| all | 历史单体兼容 | 不建议生产使用 | 有 |
|
||
|
||
解析规则：
|
||
|
||
- 服务端读取 OPENMAIC_DEPLOYMENT_ROLE，未设时才回退公开角色；
|
||
- 客户端入口读取 NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE；
|
||
- 生产未配置或配置非法时 fail closed 为 learner；
|
||
- development/test 未配置时为 all，保留上游单体开发体验；
|
||
- NEXT_PUBLIC_* 是构建期值，ops 与 learner 要做可靠 UI 隔离时应分别构建。
|
||
|
||
当前强制保护的范围：
|
||
|
||
- /courses、/courses/**、/api/courses、/api/courses/** 和 /api/ops/** 需要
|
||
manage_courses；
|
||
- 生产 ops 若没有 ACCESS_CODE 返回 503；
|
||
- 运营 API 除 middleware 外，还逐 route 调用 requireOpsAccess 校验 HMAC cookie；
|
||
- learner 请求运营 API 返回 403，访问运营页面回到首页；
|
||
- server 是无头服务：所有非 API 页面直接返回 404，/api/courses/**、
|
||
/api/ops/** 和 /api/access-code/** 也返回 API 404；provider 探测/验证、
|
||
MP4 export、开发态 persistence、usage、全局 job 列表与 `/api/proxy-media`
|
||
也不在专用 server 公开面；
|
||
- 全局 job 列表的 GET/HEAD 都会返回 404；
|
||
`/api/internal/course-publish` 只允许 POST，尾斜杠不会绕过方法边界；
|
||
- POST /api/coursewares 在 ops 同源部署校验 ACCESS_CODE 会话，在 server 部署校验
|
||
COURSEWARE_PUBLISH_TOKEN Bearer token，在 learner 部署拒绝；
|
||
- 公开 courseware、course manifest 读取仍是服务端的静态数据 API。
|
||
|
||
远程发布成功后，ops 通过当前 `CourseRecord.publication` 回执识别本地未挂载
|
||
registry 的已发布 source classroom，并拒绝覆写或随 job 删除。发布与删除还
|
||
共用同进程 source 互斥，避免在最终复核与回执落盘之间竞态删除。该保护只覆盖
|
||
当前回执且不跨进程；重生清除回执后，旧已发布源是否永久保留尚未定义，
|
||
多实例仍需持久发布历史和分布式锁/事务。
|
||
|
||
重要限制：上述是针对明确非课堂必需端点的部分 deny，不是完整的
|
||
learner identity/capability allowlist；
|
||
物理拆分之前，还应在反向代理层只暴露该角色需要的路由。
|
||
|
||
learner 身份、classroom/job owner、资源级授权、课程权益与成本额度尚未完成。
|
||
无头 server 边界只隐藏页面和运营 API，不代表其他生成、Chat、TTS、搜索等
|
||
高成本 API 已可安全向匿名公网开放。上线前必须先完成身份与授权设计，
|
||
并由网关执行最小 API allowlist。
|
||
|
||
## 2. 三端部署矩阵
|
||
|
||
| 项目 | learner desktop | ops | server |
|
||
|---|---|---|---|
|
||
| 角色 env | learner | ops | server |
|
||
| 面向用户 | 学习者/单课件作者 | 内部运营 | learner 与 ops |
|
||
| 单课件双路径 | 主能力 | 同构代码中仍存在 | 当前承载后台生成与模型 API |
|
||
| 大型课程创建/确认/重试 | 隐藏且拒绝 | 主能力 | 不提供运营 UI |
|
||
| 大课学习 | 主能力 | 验收可用 | 提供 manifest/bundle |
|
||
| 原 Stage | 学习和编辑 | 模块审阅 | 不渲染 |
|
||
| ACCESS_CODE | 可选全站访问码 | 生产必配 | 通常不配，发布走 token |
|
||
| COURSEWARE_PUBLISH_TOKEN | 不配 | 当前课程发布内部必配 | 跨实例发布必配 |
|
||
| LLM/TTS/媒体 provider | 单课件生成与原课堂按需 | 主 Agent、模块生成、TTS、媒体 | 仅其实际承载的模型端点按需 |
|
||
| 文件数据目录 | 可读课程缓存为浏览器数据 | classroom、job、framework | courseware、bundle、manifest |
|
||
| 多实例 | UI 可横向，但生成任务仍受状态约束 | 不可并发写文件 repo | 当前不可并发写文件 repo |
|
||
|
||
learner desktop 不是“无模型 key 的纯静态站”。它保留单课件生成和原课堂教学 Agent：
|
||
当前同构部署可通过 server-configured provider 提供模型；物理 desktop 拆分后可改为调用
|
||
受控 server API。只有目录、manifest 和 bundle 下载属于零 LLM 热路径。
|
||
|
||
## 3. 环境变量
|
||
|
||
### 3.1 角色与鉴权
|
||
|
||
| 变量 | 作用 | learner | ops | server |
|
||
|---|---|---:|---:|---:|
|
||
| OPENMAIC_DEPLOYMENT_ROLE | 服务端角色：all/ops/server/learner | 必配 | 必配 | 必配 |
|
||
| NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE | 同一非敏感角色名，控制 UI affordance | 必配 | 必配 | 可配 |
|
||
| ACCESS_CODE | HMAC 会话口令 | 可选 | 生产必配 | 可选 |
|
||
| ACCESS_CODE_SESSION_TTL_SECONDS | 会话 TTL，默认 604800 秒（7 天） | 按需 | 可配 | 不配 |
|
||
| OPS_PUBLIC_ORIGIN | ops 同源写校验的 canonical origin | 不配 | 反代部署必配 | 不配 |
|
||
| COURSEWARE_PUBLISH_TOKEN | 服务端发布凭据 | 不配 | 当前课程发布必配 | 跨实例接收必配 |
|
||
| COURSE_PUBLISH_SERVER_BASE_URL | 固定的跨进程发布 origin | 不配 | 独立部署必配 | 不配 |
|
||
| COURSEWARE_PUBLIC_BASE_URL | learner 可访问的课件公开 origin | 不配 | 不配 | 生产必配 |
|
||
|
||
不存在受支持的 NEXT_PUBLIC_COURSEWARE_PUBLISH_TOKEN。不要把发布密钥放入浏览器构建。
|
||
|
||
ACCESS_CODE cookie 使用 HMAC 签名并带签发时间，Edge 中间件与 Node route 使用
|
||
同一 TTL 规则，拒绝过期或未来时间 token。POST /api/access-code/verify 只接受
|
||
同源 application/json，对 Content-Length 和实际 chunked stream 都强制 8 KiB 上限，
|
||
并对失败尝试做有界进程内限流。所有使用该 cookie 的 ops 写操作也要通过
|
||
Origin 同源校验。进程内限流不能代替网关级的分布式限流。
|
||
同源校验不信任 X-Forwarded-Host；如果 ops 位于反向代理后，必须把浏览器真实
|
||
origin（例如 https://ops.example.com）配置为 OPS_PUBLIC_ORIGIN。
|
||
|
||
### 3.2 生成与模型
|
||
|
||
| 变量 | 作用 | 备注 |
|
||
|---|---|---|
|
||
| MODEL_ROUTES | 按 stage 路由模型 | 至少按需配置 generate-classroom、course-framework、scene-content、scene-actions |
|
||
| 各 PROVIDER_API_KEY / BASE_URL / MODELS | LLM provider | 以 .env.example 为准 |
|
||
| 各 TTS_* | 讲解音频与原课堂语音 | 大课发布要求每个 speech 有持久化音频 |
|
||
| IMAGE_* / VIDEO_* | 可选媒体生成 | 未生成或无法解析的媒体会在发布时 fail closed |
|
||
| Web search provider 变量 | 可选框架研究/单课件联网 | 未配置时相应生成路径降级 |
|
||
| OPENMAIC_ENABLE_VOCATIONAL | 服务端职教 task-engine 门 | 客户端开关本身不是安全边界 |
|
||
| NEXT_PUBLIC_SHOW_VOCATIONAL_TEST_UI | 显示实验入口 | 仅 UI |
|
||
| NEXT_PUBLIC_PI_CHAT_ENABLED | 原 Pi 课堂 Chat 开关 | 属于受保护课堂能力 |
|
||
| OPENMAIC_ENABLE_PI_WEB_SEARCH | Pi Director 联网门 | 独立于 Pi Chat 开关 |
|
||
|
||
主 Agent 模型示例：
|
||
|
||
MODEL_ROUTES={"course-framework":"openai:gpt-4o-mini","generate-classroom":"openai:gpt-4o"}
|
||
|
||
实际 provider:model 格式应与当前 server provider 配置保持一致，不要照搬旧文档中的
|
||
provider/model 斜杠写法。
|
||
|
||
### 3.3 文件仓库
|
||
|
||
| 变量 | 默认目录 | 角色 |
|
||
|---|---|---|
|
||
| CLASSROOM_DATA_DIR | data/classrooms | learner/ops 当前生成服务 |
|
||
| CLASSROOM_JOBS_DIR | data/classroom-jobs | learner/ops 当前生成服务 |
|
||
| COURSE_FRAMEWORK_DIR | data/course-frameworks | ops |
|
||
| COURSEWARE_DATA_DIR | data/coursewares | server；当前同源发布也直接写 |
|
||
| COURSEWARE_BUNDLE_DIR | data/courseware-bundles | server |
|
||
| COURSE_MANIFEST_DIR | data/course-manifests | server；当前 ops 同进程提交 |
|
||
| COURSEWARE_MAX_UPLOAD_BYTES | 314572800 | server；单模块 ZIP 上限 |
|
||
| COURSE_PUBLISH_MAX_UPLOAD_BYTES | 943718400 | ops/server；整批 multipart 上限 |
|
||
| COURSE_PUBLISH_TIMEOUT_MS | 600000 | ops 调用 server 的超时 |
|
||
| COURSE_PUBLISH_ALLOW_INSECURE_HTTP | false | 仅可在受信私网显式开启 |
|
||
|
||
### 3.4 通用持久化
|
||
|
||
| 变量 | 作用 | 当前边界 |
|
||
|---|---|---|
|
||
| NEXT_PUBLIC_PERSISTENCE=1 | 浏览器改用 HTTP persistence backend | 构建期变量 |
|
||
| NEXT_PUBLIC_PERSISTENCE_TOKEN | 开发共享 token | 不提供用户隔离，不得作为公网生产鉴权 |
|
||
| PERSISTENCE_DEV_TOKEN | 与公开开发 token 配对 | 仅开发 |
|
||
| DATABASE_URL | 通用 document/runtime/asset Postgres backend | 没有替换 courseware/manifest repo |
|
||
| ASSET_S3_BUCKET | 通用 asset 字节存储 | 没有替换 frozen bundle byte store |
|
||
|
||
不要因为配置了 DATABASE_URL 或 ASSET_S3_BUCKET，就把发布仓库描述为已经使用
|
||
Postgres/S3。
|
||
|
||
## 4. 当前启动方式
|
||
|
||
每个角色应使用独立构建目录或独立构建流水线，因为公开角色会在构建时内联。
|
||
|
||
### Docker Compose
|
||
|
||
Dockerfile 把 NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE 声明为 builder ARG/ENV，
|
||
Compose 为 learner、ops、server 分别构建独立镜像上下文，并在运行时固定同值的
|
||
OPENMAIC_DEPLOYMENT_ROLE。不要只在 container 启动时改 NEXT_PUBLIC 角色；那不会重写已经内联的
|
||
浏览器 bundle。
|
||
|
||
# learner：默认端口 3000
|
||
docker compose up --build learner
|
||
|
||
# ops：默认端口 3102，.env.local 必须有 ACCESS_CODE
|
||
docker compose --profile ops up --build ops
|
||
|
||
# server：默认端口 3103
|
||
docker compose --profile server up --build server
|
||
|
||
可分别用 OPENMAIC_LEARNER_PORT、OPENMAIC_OPS_PORT、OPENMAIC_SERVER_PORT 改写宿主机端口。
|
||
`.env.local` 仍负责 provider key、ACCESS_CODE 和 COURSEWARE_PUBLISH_TOKEN；Compose 中的硬编码角色会
|
||
覆盖 env_file 中同名角色，防止服务端权限与客户端入口不一致。learner、ops 和 server 默认使用
|
||
独立数据卷。ops 配置 COURSE_PUBLISH_SERVER_BASE_URL 后使用跨实例整批发布；
|
||
未配置时仅保留历史同进程共享文件库 fallback。
|
||
|
||
### 直接启动 Next.js
|
||
|
||
#### learner desktop 表面
|
||
|
||
OPENMAIC_DEPLOYMENT_ROLE=learner
|
||
NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE=learner
|
||
pnpm build
|
||
pnpm start -p 3101
|
||
|
||
若要使用单课件生成和原课堂模型能力，还需配置相应 provider 与 MODEL_ROUTES。
|
||
若只做发布课程的读取 smoke，可不配置模型，但这不代表完整 learner 产品无需模型。
|
||
|
||
#### ops
|
||
|
||
OPENMAIC_DEPLOYMENT_ROLE=ops
|
||
NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE=ops
|
||
ACCESS_CODE=<strong-secret>
|
||
OPS_PUBLIC_ORIGIN=https://ops.example.com
|
||
COURSEWARE_PUBLISH_TOKEN=<server-only-secret>
|
||
COURSE_PUBLISH_SERVER_BASE_URL=https://course-server.example.com
|
||
pnpm build
|
||
pnpm start -p 3102
|
||
|
||
ops 还需主 Agent、单课件生成、TTS 和媒体 provider，以及可持久化的 classroom、
|
||
job、framework 数据卷。
|
||
|
||
#### server
|
||
|
||
OPENMAIC_DEPLOYMENT_ROLE=server
|
||
NEXT_PUBLIC_OPENMAIC_DEPLOYMENT_ROLE=server
|
||
COURSEWARE_PUBLISH_TOKEN=<same-server-only-secret>
|
||
COURSEWARE_PUBLIC_BASE_URL=https://learn.example.com
|
||
COURSEWARE_DATA_DIR=/srv/openmaic/coursewares
|
||
COURSEWARE_BUNDLE_DIR=/srv/openmaic/courseware-bundles
|
||
COURSE_MANIFEST_DIR=/srv/openmaic/course-manifests
|
||
pnpm build
|
||
pnpm start -p 3103
|
||
|
||
### 跨进程大课发布契约
|
||
|
||
ops 在本地 persisted classroom 上执行完整冻结和二次快照校验，然后向固定路径
|
||
POST /api/internal/course-publish 发送一个 multipart 请求：metadata JSON 加全部模块 ZIP。
|
||
该路由只在 server/all 角色开放，即使 server 环境意外带有 ACCESS_CODE，也只认
|
||
COURSEWARE_PUBLISH_TOKEN Bearer，不认 ops cookie。
|
||
|
||
server 在一个 course 单进程互斥边界内：
|
||
|
||
1. 对全部 incoming ZIP 运行与单课件发布相同的完整门禁；幂等命中前还会读取 exact 已存
|
||
ZIP，复核存在、内部 id/version/hash、重算 hash 与 complete；缺失或篡改会发布新版本，
|
||
不会返回伪成功；
|
||
2. 调用原 publishCourseware 逐模块分配/重写版本并以 unpublished 暂存；
|
||
3. 全部通过后切换 published，再调用原 publishCourse 写 schema-v2 manifest；
|
||
4. 大课 courseware record 私有携带 courseId/moduleIndex；公共 catalog、detail、download
|
||
只有在任一已提交 schema-v2 manifest 包含 exact id/version/hash pin 时才可见，因此
|
||
promote 到 manifest 提交之间以及失败补偿期间均返回 404/不进入列表；
|
||
5. 任一失败将本批状态补偿回 unpublished；
|
||
6. ops 只在回执的 module id/version/hash 与本地 ZIP 逐项一致后写入 publication receipt；
|
||
receipt 还保存每模块的 sourceRevisionHash。查询状态会重读完整 classroom
|
||
并比较该哈希；任意源修改或模块重生都使 receipt 失效。
|
||
|
||
contentHash v2 明确忽略 manifest.json 的 exportedAt。相同 metadata + 课堂内容的
|
||
远程超时重试、重复点击，以及同源共享文件 fallback 都幂等返回既有
|
||
manifest。无 contentHashVersion 的历史包仍使用 v1 原始字节哈希；learner 的旧内部
|
||
version 兼容只对能通过精确 registry 与重算 v1 hash 的真正旧包生效。若要
|
||
强制产生新版本，必须先改变课程内容，当前契约没有 `forceNewVersion` 开关。
|
||
|
||
安全约束：目的地由 server-only COURSE_PUBLISH_SERVER_BASE_URL 固定，不接受浏览器输入；
|
||
URL 禁止凭据/path/query/fragment，fetch 禁止 redirect；非 loopback HTTP 默认拒绝。server 在
|
||
formData 缓冲前对实际 stream 封顶，且解析后再校验每个 File.size。公开 bundleUrl 仅由
|
||
COURSEWARE_PUBLIC_BASE_URL 派生，不使用内网 request Host。失败响应稳定包含 errorCode、phase（request/
|
||
staging/commit/rollback）、可选 moduleIndex 和 details。
|
||
|
||
未配置 COURSE_PUBLISH_SERVER_BASE_URL 时，当前单仓运行仍使用同源共享文件库，但复用同一
|
||
批量事务/幂等/visibility helper；该 fallback 是迁移兼容，不是多实例事务。
|
||
|
||
## 5. 文件仓库为何只能单实例
|
||
|
||
当前正确性依赖以下进程内状态：
|
||
|
||
- courseware publishLocks；
|
||
- CourseRecord courseLocks；
|
||
- CourseManifest manifestLocks；
|
||
- 大课 runningRuns、AbortController 和当前 classroom job 集合；
|
||
- 版本号先读历史、再加一、再写回的 read-modify-write。
|
||
|
||
文件层虽使用原子 rename，bundle 使用 link 实现 create-if-absent，但 Map mutex 只在单进程内
|
||
有效。两个容器可能同时读到相同 nextVersion，或覆盖彼此刚写的 JSON history。
|
||
当前“事务”是失败后把本批记录补偿回 unpublished，不具有数据库事务的跨进程隔离性、
|
||
原子提交或崩溃一致性。
|
||
|
||
当前生产约束：
|
||
|
||
1. courseware、manifest、framework 的写入实例都保持 1；
|
||
2. 不用多副本共享 NFS 来伪装数据库事务；
|
||
3. 发布和生成期间避免滚动重启；
|
||
4. 备份整个版本历史 JSON 与 bundle 目录，并保持二者一致；
|
||
5. classroom/course runner 重启后需要通过记录自愈，再由运营点击继续/重试。
|
||
|
||
这些限制意味着：只要计划公网生产上线或多副本扩容，下述 Postgres 事务、
|
||
唯一约束与私有对象存储就是硬前置，不是可选性能优化。
|
||
|
||
未来多实例的最低实现：
|
||
|
||
- Postgres 表为 courseware_versions 和 course_manifest_versions 建唯一键；
|
||
- 在同一事务内锁定 course/courseware、分配 next version、写 metadata 与状态；
|
||
- bundle 写对象存储，key 包含 id/version/hash，使用 put-if-absent；对象在 manifest commit
|
||
前必须保持私有，CDN/签名 URL 也必须执行等价的 exact-pin visibility gate；
|
||
- manifest 只在全部对象与 metadata 可读后提交；
|
||
- 下载 URL 指向对象存储/CDN；
|
||
- 生成任务进入持久队列，worker 使用租约/幂等键；
|
||
- 失败补偿只改变本批 staged 记录，不覆盖历史已发布版本。
|
||
|
||
## 6. legacy manifest 重发操作
|
||
|
||
识别方式：
|
||
|
||
- GET /api/learn/courses/{id} 返回 409；
|
||
- 错误为 legacy course manifest must be republished；
|
||
- 文件可能是旧 singleton，也可能已经进入 history envelope，但记录本身没有
|
||
schemaVersion=2 或模块缺 version/hash。
|
||
|
||
安全重发流程：
|
||
|
||
1. 保留旧 manifest 文件并备份，不直接编辑旧版本。
|
||
2. 在 ops 打开对应 CourseRecord，确认 framework 和模块 classroom 仍存在。
|
||
3. 运行发布校验；如提示 MODULE_OUTPUT_UNVERIFIED、CONTINUITY_UNVERIFIED、
|
||
CONTINUITY_STALE、INTERACTIVE_HTML_MISSING 或缺音频/媒体，从最早失败模块开始
|
||
按顺序重生成。
|
||
4. 人工审阅修复后的模块，再由 ops 执行“发布课程”。
|
||
5. 新发布会生成下一 manifest 版本，schemaVersion=2，每模块固定
|
||
coursewareId + coursewareVersion + contentHash。
|
||
6. 用精确 manifest version 访问 learner 页进行 smoke。
|
||
7. 旧无 pin 版本保留审计，但继续拒绝 learner；不要把当前 latest 手工写成旧历史 pin。
|
||
|
||
若原 CourseRecord/classroom 已丢失，不能伪造历史身份。应按新课程重新生成、审阅、发布。
|
||
|
||
## 7. 机械拆分顺序与每步门槛
|
||
|
||
### Step 0：冻结基线
|
||
|
||
- 固定 bundle format、manifest schema v2、CourseRecord compat 和 protected core 清单；
|
||
- 保存当前针对性测试结果；
|
||
- 不在拆分 PR 中改变 Chat、Stage、Scene、Action、PBL 或白板语义。
|
||
|
||
回滚门槛：任何 learner bundle 无法进入原 Stage，立即停止拆分。
|
||
|
||
### Step 1：共享契约
|
||
|
||
- 移动 bundle types/hash/serialize、course manifest types、API DTO；
|
||
- 把环境读取留在应用 adapter，纯契约包不读取 process.env；
|
||
- ops、server、learner 同时消费同一版本，禁止复制类型。
|
||
|
||
回滚门槛：同一 fixture 的 contentHash 或 imported document 发生变化。
|
||
|
||
### Step 2：先拆 server
|
||
|
||
- 搬 app/api/coursewares/**、app/api/learn/courses/**、
|
||
lib/courseware-repo、lib/course-manifest-repo 和 bundle byte store；
|
||
- 新增只接受 server token 的 course manifest 提交接口；
|
||
- 现有 ops 先通过 HTTP adapter 调新 server，保留同源 adapter 作为短期回滚；
|
||
- reader 先迁、writer 后迁，确认旧 manifest 409 策略一致。
|
||
|
||
回滚门槛：精确 version/hash 查询、不可变下载头或发布门禁不一致。
|
||
|
||
### Step 3：先完成 DB/对象存储，再扩 server
|
||
|
||
- 文件 repo 双写只用于迁移核对，不作为长期架构；
|
||
- 对比记录数、版本历史、hash 与对象字节；
|
||
- 切读后保留文件只读备份，确认稳定再停双写；
|
||
- 未完成事务和唯一键前保持单实例。
|
||
|
||
### Step 4：再拆 learner desktop
|
||
|
||
- 整体搬 app/page、generation-preview、tasks、learn、classroom 和其依赖；
|
||
- 原 Stage 与 protected core 作为一个共享包/工作区依赖整体复用，不 fork；
|
||
- 只替换 API base URL、鉴权 adapter 与文件路径；
|
||
- 保留首页普通后台与材料/Interactive/职教前台双路径。
|
||
|
||
回滚门槛：出现第二套助教、发布课堂带 outlines、或 learner 不再进入原 Stage。
|
||
|
||
### Step 5：最后拆 ops
|
||
|
||
- 搬 courses UI、course-framework、publish-validation、module-digest 和发布发起端；
|
||
- classroom 生成/审阅仍使用同一单课件 agent 与 protected core；
|
||
- 浏览器只持 ACCESS_CODE 会话，不持 server token；
|
||
- 完成 ops → server 的 bundle 与 manifest transport。
|
||
|
||
### Step 6：收口
|
||
|
||
- 删除 all 的生产支持和同源 repo 直写；
|
||
- 给每个 app 配置显式 route allowlist、独立构建和最小 provider key；
|
||
- 做一次 legacy 重发、并发发布、失败回滚和旧 manifest 固定版本演练。
|
||
|
||
## 8. 验收命令
|
||
|
||
在 /Users/inmanw/项目/麦洛学习/OpenMAIC 执行。
|
||
|
||
### 类型与格式
|
||
|
||
pnpm exec tsc --noEmit
|
||
pnpm exec prettier ../docs/architecture-3-tier.md ../docs/deployment-3-tier.md ../docs/large-course-mode.md ../docs/handover.md --check
|
||
|
||
### 三端、大课、冻结发布定向回归
|
||
|
||
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
|
||
|
||
### learner/ops 浏览器边界
|
||
|
||
pnpm exec playwright test \
|
||
e2e/tests/home-to-generation.spec.ts \
|
||
e2e/tests/deployment-role-boundary.spec.ts \
|
||
--project=chromium
|
||
|
||
Playwright 默认 webServer 已显式固定 learner 角色。若本机已有 3002 端口的旧 dev server，
|
||
先确认它的角色，避免 reuseExistingServer 让边界测试误连 all/ops。
|
||
|
||
### 构建
|
||
|
||
pnpm build
|
||
|
||
### 读路径压测
|
||
|
||
node scripts/load-test-reads.mjs + --base http://localhost:3103 + --courseware <published-id> + --concurrency 20 + --requests 400
|
||
|
||
## 9. 已知受保护 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
|
||
|
||
当前结果为 3 files 中 40 passed / 3 failed；失败正好是：
|
||
|
||
- prompts：keeps concept and mechanism questions teacher-led before student reactions
|
||
- route-cue-user：hands successful web evidence to one child and clears it before later delegations
|
||
- route-cue-user：does not leak consumed web evidence after the selected child fails
|
||
|
||
它们属于既有 protected Chat director 的 prompt/evidence 断言漂移，本次三端改造未触及
|
||
lib/chat/** 或 /api/chat/pi。验收报告应原样记录这 3 项；不要在本改造中修改 Chat
|
||
内核或放宽测试来掩盖它们。
|