Skip to content

README.md

Latest commit

 

History

History
151 lines (111 loc) · 10.9 KB

README.md

File metadata and controls

151 lines (111 loc) · 10.9 KB
Raw

CourseForge · 离线网页课件编辑器（原型）

把传统 PPT 课件升级为「PPT 基础层 + AI 互动层」的网页课件，全程离线、零安装、零服务器。 本目录是可运行的 MVP 原型，配合本地 WorkBuddy 即可生成互动 H5。

一、结论：采用「独立离线编辑器 + WorkBuddy 联动」（方案 B）

你与 doubao 讨论的两个方案本质都是「PPT + 网页互动融合」，区别只在职责切分：

  • 方案 A（WorkBuddy 内置 PPT 技能）——耦合重、版本难管控、AI 不可控风险高，不推荐。
  • 方案 B（独立离线编辑器 + WorkBuddy 联动）——PPT 解析/编辑/排版集中在编辑器，WorkBuddy 只做「生成互动 HTML 素材」单一职责。✅ 主推。

本原型即方案 B 的可运行实现。

我补充的 6 个工程要点（你们讨论里没充分展开，但决定成败）

# 要点 本原型的做法
1 PPT 导入到底转成什么 浏览器端渲染库（pptxjs）脆弱且依赖多。生产级应把每页栅格化为图片作为「底层基础层」，保真、离线、可控。原型用 pptxjs 尽力而为 + 示例课件兜底，架构已支持 image/html 两种基础层。
2 AI 内容的隔离（最关键） 互动 iframe 默认 sandbox="allow-scripts allow-forms allow-popups allow-modals"（不带 allow-same-origin），AI 生成的 H5 无法触碰课件主体。确需摄像头/麦克风时，可在组件属性里按需开启「摄像头 / 麦克风 / 允许同源」——开启后追加 allow-same-origin 与 allow="camera; microphone"。出错一键清空即可，不污染基础层。
3 真·单文件离线 当下是「index.html + libs/」文件夹，双击即可离线运行；用 build_singlefile.js 把依赖内联，得到真正的单 HTML 文件用于统一分发。
4 本地通信协议 编辑器与 WorkBuddy 通过本地 WebSocket（仅 127.0.0.1）通信，WorkBuddy 只回传 HTML 片段，不持有完整课件。协议见第四节。
5 工程 vs 导出分离 「保存工程」= JSON（图片以 dataURL 内联），便于二次编辑；「导出课件包」= 单 HTML（互动以 iframe srcdoc 内联），便于离线分发播放。两者职责不同。
6 管控与升级 编辑工具是固定文件统一下发，老师无法改内核；迭代只换一个 HTML 文件，不用逐个升级 WorkBuddy 客户端。

二、架构与数据流

老师 PPT (.pptx) ──┐
                    ├─► [离线编辑器 index.html] ── 解析/编辑/排版/分层
示例/空白 ──────────┘        │  ├─ 底层基础层（PPT 转图片/HTML，固定、不受 AI 影响）
                            │  └─ 上层互动层（HTML 交互容器，可增删改、可清空重生成）
                            │
                  一键唤起 ──┴─► [本地 WorkBuddy] ── WebSocket(127.0.0.1) ──► 回传互动 HTML
                            │
                  保存工程 ──┤──► .cfc.json（可二次编辑）
                  导出课件 ──┴──► 离线课件.html（单文件，断网可播，U盘/微信分发）

分层解耦的核心价值：PPT 基础内容与 AI 互动组件完全分层。AI 出错 = 删掉一个互动框，课件主体毫发无损。

三、使用流程（老师视角，零学习成本）

  1. 用 WPS/Office 正常做 PPT，保存本地。
  2. 双击打开 index.html（或单文件版）。
  3. 「📚 模板库」选一套现成课件（已含「超能AI工坊·第04单元 点亮创意表达」等预制模板，部分预填了可运行互动）；或用「导入PPT」把你的 PPT 转成底层基础页；也可点「✨ 示例课件」快速体验。
  4. 在需要互动的页面，顶部点「🌐 HTML交互容器」添加框，拖动/缩放定位。
  5. 选中互动框 → 右侧「调用 WorkBuddy 生成」→ 输入需求 → 生成后自动回填；或直接「插入内置组件」（答题/投票/拖拽，离线即用）；也可「📂 手动导入本地 HTML」。
    • 未连接 WorkBuddy 时，内置 Mock 生成器 会按关键词返回可用的答题/投票/拖拽小游戏，便于先体验。
  6. 「🗂 备份」随时给当前可编辑源文件存版本（localStorage 快照，可回滚），并支持「导出全部备份(.cfbak)」统一存档/迁移；「💾 保存工程」导出单 JSON 留底便于二次编辑。
  7. 「🚀 导出课件包」得到可离线播放的单 HTML（断网可播、U盘/微信分发）。授课时打开即用、可全屏投屏。

快捷键：Delete 删除选中；Ctrl+←/→ 切换页面；互动框双击可临时开启/关闭互动（方便在编辑时操作 H5）。

四、与 WorkBuddy 的通信协议（本地 WebSocket）

  • 端口：默认 ws://127.0.0.1:7788（编辑器「连接」按钮可改）。
  • 全双工，单连接多请求，用 requestId 关联。

编辑器 → WorkBuddy（请求）

{
  "type": "generate",
  "requestId": 1,
  "prompt": "做一个浮力知识点的选择题小测验，3道题",
  "theme": { "primary": "#2563eb", "bodyFont": "Microsoft YaHei" },
  "size": { "w": 340, "h": 200 }
}

WorkBuddy → 编辑器（进度 / 结果 / 错误）

{ "type": "progress", "requestId": 1, "message": "正在生成…" }
{ "type": "result",   "requestId": 1, "title": "浮力小测验", "html": "<!doctype html>…完整自包含HTML…" }
{ "type": "error",    "requestId": 1, "message": "生成失败：…" }

约束：

  • html 必须是自包含的（内联 CSS/JS，不依赖外部资源），便于 srcdoc 离线加载。
  • WorkBuddy 不接收、不存储课件其它内容，只拿 prompt + 尺寸主题，回传片段。
  • 生成结果是「预览态」：编辑器先展示，老师确认后才回填容器。

workbuddy-bridge.js 是该协议的服务端参考实现（含调用 LLM 的占位），开发者据此把真实 WorkBuddy 接进来。

五、目录结构

course-editor/
├── index.html              # 编辑器主体（双击即用，含模板库/备份/权限/组件插入）
├── CourseForge.standalone.html  # 真正单文件版（依赖已内联，统一分发用）
├── libs/                   # 离线依赖（jquery/d3/jszip/pptxjs 等），已随包提供
├── widgets/                # 内置合规组件（quiz/vote/drag）+ 提示词框架
├── README.md               # 本文档
├── WIDGET_SPEC.md          # 互动组件规范 v0.1（主题/生命周期/通信/权限）
├── build_singlefile.js     # 把依赖内联 → 重新生成 CourseForge.standalone.html
├── workbuddy-bridge.js     # WorkBuddy 侧 WS 服务端参考实现
└── _smoke.cjs              # 自动化冒烟测试（playwright，开发用，可删）

六、构建真正单文件（便于统一分发）

node build_singlefile.js     # 生成 CourseForge.standalone.html（所有 JS/CSS 内联，零外部依赖）

生成的单文件即可像原型要求的那样「统一下发给所有老师，双击即开」。

七、后续迭代建议（按价值排序）

  1. PPT 导入栅格化：用 LibreOffice Headless（--convert-to pdf → pdftoppm）或更轻的本地小工具，把每页转成 PNG 作为基础层，保真度与离线稳定性远超浏览器端 DOM 渲染。
  2. 互动模板市场 / 素材库：把老师生成的优质 H5 沉淀为可复用模板，单独导出/导入（已预留交互层独立配置文件）。
  3. 协同与版本：工程 JSON 天然适合做 Git/网盘版本管理与合并。
  4. 能力边界：摄像头/麦克风等需安全上下文，明确在导出包运行时的权限提示与降级方案。
  5. 可访问性：导出播放器增加键盘导航、字幕、对比度适配。

八、本版新增能力（v0.3）

  • 🏠 示例画廊 + 11 套示例课件：启动即弹出示例画廊，覆盖物理 / 数学 / 语文 / 英语 / 化学 / 生物 / 历史 / 信息技术 / 企业培训 / AI 素养等学科；每套为完整多页课件（封面 + 内容 + 预填互动），点「打开并编辑」即在基础上修改。预览页（GitHub Pages）用户一打开即可看到丰富示例。
  • 🌐 window.CourseForge 编程接口：暴露 getDoc() / loadDoc() / openExample() / examples()，便于 WorkBuddy / 外部脚本编排整本课件（借鉴 bento 的 window.bento 表面），编辑更灵活。

v0.2 能力如下：

  • 📚 模板库：内置「超能AI工坊·第04单元 点亮创意表达」（封面+单元导入+知识讲解<含预填投票互动>+实践任务）、「浮力示例」、「空白课件」三套。点击即载入，老师可在此基础上改基础层、加互动，做成自己的专属模板。
  • 🗂 版本与备份管理：老师本地一键「备份当前」可编辑源文件（存浏览器 localStorage，带备注、可回滚），并支持「导出全部备份(.cfbak)」统一存档/迁移/交备份、「导入备份文件」合并历史版本。解决了"用户本地自己维护、统一备份可编辑源文件"的诉求——编辑器不抢 Git 的活，只在最方便处提供傻瓜式快照与打包。
  • 🌐 组件权限开关：每个互动容器可单独开启「摄像头 / 麦克风 / 允许同源」。默认不限制脚本运行；仅当组件确需摄像头/麦克风时再开，且开启音视频时建议同时开「允许同源」（否则 getUserMedia 在 opaque origin 下会被浏览器拦截）。
  • 🧩 内置组件离线插入：右侧属性面板「插入内置组件」可直接塞入答题/投票/拖拽三类合规 H5，无需联网、无需 WorkBuddy，方便老师立刻看到效果。
  • 🎨 Widget 主题与生命周期注入：编辑器在渲染互动 iframe 时，自动向文档根注入 --cf-* 主题变量（跟随全局统一样式），并在翻到该页时发出 cf:activate；同时接收组件回传的 cf:event / cf:ready / cf:error（详见 WIDGET_SPEC.md）。导出播放器同样内置这套机制。

说明：用户提供的 D:\热门课件\...\模版.pptx 在 Linux 沙箱中无法读取。本版已按「超能AI工坊·第04单元 点亮创意表达」主题独立设计示范模板（基础层为矢量 HTML，互动容器遵循 Widget Spec）。后续你把真实 pptx 上传给我，我会把它作为基础层替换进去，保留已预填的互动层。

九、已知限制（原型阶段）

  • 浏览器端 PPT 导入依赖 pptxjs，部分复杂版式可能偏差；生产请走「栅格化」路线（见上）。
  • 互动 iframe 为安全隔离默认不共享同源；摄像头/麦克风需开通「允许同源」+ 安全上下文（https/localhost 或受支持的本地位点）才能调用，file:// 直接双击打开时浏览器可能仍会限制。
  • Mock 生成器仅用于演示，真实互动由 WorkBuddy 接 LLM 产生。