@botlearn-course/courseware-bridge

BotLearn sandboxed courseware iframe 与宿主之间的共享 V1 contract、运行时校验和注入 SDK。

平台或工具链安装：

pnpm add @botlearn-course/courseware-bridge

课件作者怎么接入

课程 HTML 不需要安装依赖。平台渲染 iframe 时会自动注入 SDK；作者应优先使用声明式属性：

<button type="button" data-botlearn-practice-action="open">
  回到练习场预览
</button>

<button type="button" data-botlearn-content-action="learning.advance">
  进入下一节
</button>

只有声明式 DOM 无法表达的复杂交互，才调用注入的受限 API：

await window.botlearnCoursewareBridge.ready()
if (window.botlearnCoursewareBridge.supports('learning.advance')) {
  await window.botlearnCoursewareBridge.request('learning.advance', {})
}

不得在课程 HTML 中直接调用 parent.postMessage，也不得手写 wire envelope。提交审核、发布和 后台“校验课程定义”都会执行相同的发布前检查。

平台开发者看哪里

• protocol-v1.json：跨语言机器可读 contract，也是 Python 发布校验器的 parity fixture。
• src/protocol.ts：TypeScript 类型、envelope 与 payload 校验。
• src/runtime-script.ts：注入 iframe 的 SDK 构建器。
• docs/specs/courseware-bridge-protocol.md：完整语义、消息矩阵、安全和兼容策略。

修改 contract 后必须同时更新 fixture、TypeScript 校验、Python 发布校验及其测试。