OpenLearnV2 插件开发指南与规范

核心原则

在线文档是权威来源，本地缓存加速读取，规则约束保证代码正确性。
skill 自带三份文档的本地快照（references/），每次使用前通过索引页探活。缓存未过期则直接用本地，发现远端更新才重新拉取——将月消耗从 ~100K token 降至 ~22K token。

工作流程

第一步：探活 + 缓存命中或增量更新

1a. 探活（每次必做，~200 token）

webfetch 索引页，同时提取两个版本信号：

https://openlearn-next-v2.readthedocs.io/zh-cn/latest/

1. 页面标题中的构建版本：OpenLearnV2 x.y.z 文档
2. 页脚的最近更新日期：最后更新：YYYY-MM-DD (vX.Y.Z)

> 页脚日期可能滞后于实际构建版本（曾出现页脚标 v0.3.14、实际构建已是 0.3.16）。两个信号任一变化都视为有更新。

1b. 比对缓存

读取 references/.cache-meta.json 中的 lastUpdated 字段：

• 日期相同 → 缓存命中，直接使用 references/ 目录下的本地快照（0 额外 token）
• 日期更新 → 远端有更新，告知用户"文档已更新（旧: X, 新: Y）"，然后重新拉取全量文档，更新 references 文件和 .cache-meta.json
• 首次使用（无缓存） → 直接使用 references/ 本地快照

1c. 缓存未命中时按需拉取

如果缓存不存在或已过期，按以下优先级拉取：

> 全部为多页汇编或单页快照，具体来源 URL 见 .cache-meta.json 与各文件末尾的「来源」节。

拉取后更新 references/ 和 .cache-meta.json。

第二步：需求讨论与预检查

获取最新文档后，与开发者进行结构化讨论，逐项确认：

1. 插件用途：面向教师还是学生？解决什么问题？
2. 核心功能：列举 1-5 个核心功能点
3. 插件类型（三选一）：
   - server-only：纯后端（AI 工具 + 命令 + 事件，无 UI）
   - full-stack：全栈（后端逻辑 + React 前端）
   - frontend-only：纯前端（仅 UI 面板或课堂工具）
4. UI 扩展点（full-stack / frontend-only 时确认）：
   - teacher.tab — 教师侧边栏标签页（管理页）
   - teacher.dashboard.widget — 白板可拖拽卡片（课堂交互，需匹配 teacherWidgetId）
   - teacher.panel — 教师独立全宽面板（v0.1.9+）
   - student.view — 学生端全屏视图
   - student.fullscreen — 学生全屏视图/考试模式（v0.1.9+）
   - classroom.tool — 课堂工具架按钮
   - global.setting — 全局设置页扩展（v0.1.9+）
   - anchor:<区域>:<锚点id> — 在宿主原生按钮/元素前后插入（v0.2.6+，如 anchor:whiteboard-toolbar:rollcall）
   - nav.user_menu — 顶部 Header 用户菜单扩展
5. 权限需求 (Capabilities)：显式核对需申请的权限列表（见后文权限全集字典）
6. AI 能力与 Action 关联：是否需要 AI Agent 调用？（必须注册 Action 且描述清晰）
7. 数据库需求：需要哪些表？是否需要版本迁移？
8. 目标版本：声明在 manifest.engines.openlearn 中的宿主版本兼容范围，推荐 >=0.2.5（不是 SDK 版本）

第三步：生成代码与编码规范

方案确认后，根据插件类型选择对应模板生成代码。

1. 模板对照

将 {{placeholder}} 替换为用户确认的参数：
- {{pluginId}} → 如 @teacher-li/class-polls
- {{pluginName}} → 显示名称
- {{description}} → 功能描述
- {{author}} → 作者名
- {{commandPrefix}} → 命令前缀（如 classpolls）
- {{toolId}} / {{toolName}} → classroomTools 配置
- {{tabId}} → 前端 tab ID

2. 关键编码规范与防御规则 (Mandatory Guardrails)

1. Manifest 1:1 映射约束：manifest.classroomTools 中声明的所有 commandType，必须在 activate() 中通过 ctx.services.commandBus.registerHandler() 注册对应的 Handler！
2. React 导入与 JSX 模式：frontend.tsx 第一行推荐显式导入 React (import React from 'react';)。在经典模式下（"jsx": "react"，≤0.3.14 唯一可用）省略会直接报 ReferenceError: React is not defined；0.3.15+ 启用自动 JSX 运行时时可不显式导入，但必须把 react / react-dom / react-dom/client / react/jsx-runtime 全部标记为 external。
3. classroom.tool 挂载规范（防挤压/防遮挡）：
   - 槽位组件必须保持为单纯的图标按钮（尺寸与画笔/点名按钮对齐）。
   - 展开的控制面板、全屏弹窗或遮罩，必须通过 ReactDOM.createPortal(..., document.body) 挂载到 document.body，绝对禁止在工具栏 DOM 内直接扩展大尺寸面板。
4. 前后端 Socket.IO + EventBus 实时同步架构：
   - 后端发：Handler 变更数据后，发布 EventBus 事件 (prefix.action_done)，并通过 Socket.IO 服务向前端频道/房间广播。
   - 前端收：前端在 useEffect / 组件挂载时监听 Socket 事件，收到更新后触发 state 刷新。
5. 全生命周期清理 SOP (Resource Cleanup SOP)：
   - 在 deactivate() 函数中，必须显式取消订阅 EventBus (subscription.unsubscribe())、清除所有 setInterval/setTimeout 定时器、注销监听器、以及调用 processManager 停止后台进程。
6. 数据库表命名与操作：使用 ctx.db.ensureTable() + ctx.db.table()，绝不手动拼接 SQL 表名。
7. Node.js 原生模块避坑：用 crypto.randomUUID() 代替 import { randomUUID } from 'crypto'；文件读写必须使用系统提供的 VFS API，不可直接引入 fs / path。

3. Manifest 关键字段（v0.3.x）

• engines.openlearn：填宿主版本兼容范围（推荐 >=0.2.5）；SDK 版本随平台 release 同步、勿写死。
• 按目标版本可用的新字段：api.routes（配合 ctx.http 注册 REST 路由，0.3.11+）、provides（对外暴露服务，供其他插件 requires）、optional、pluginDependencies、contributes（声明式贡献点，仅供管理后台枚举）、updateSource（热更新源）、deploy、configuration.showInDashboard。
• 完整字段与 Zod 校验规则见 references/scaffold.md「Manifest 字段全表」与 references/plugin-development-tutorial.md §3.1。

第四步：构建与脚本化预检

代码生成后，指导开发者或自动化执行构建：

cd <plugin-directory>
npm install
npx @openlearn/plugin-sdk build

构建产物预检清单 (Pre-flight Inspection)

• [ ] React 显式导入检查：grep 'import React from "react"' dist/frontend.js 或检查 Bundle 头部包含 React 全局/模块引用。
• [ ] 三件套映射检查：manifest.json 中所有的 classroomTools[].commandType 均已在 src/index.ts 注册了 registerHandler。
• [ ] 裸导入非法引用检查：执行 grep -E '^import .+ from "[^@\./]' dist/index.js 应无输出。
• [ ] JSX 模式检查：目标为 ≤0.3.14 时，构建产物中不得出现 react/jsx-runtime 引用；0.3.15+ 允许自动模式，但仍需确认 react/jsx-runtime 已标记 external（版本口径不一，稳妥做法是直接标记 external）。
• [ ] Worker 兼容检查：若插件声明 worker 模式，确认未使用 ctx.config / ctx.provide()，eventBus 用 subscribe/unsubscribe，commandBus.execute 手动加了前缀（详见速查字典 §5）。
• [ ] 生命周期清理检查：deactivate() 中包含了定时器与 EventBus 监听器的取消注册代码。

第五步：安装与验证

提醒开发者在 OpenLearn 管理后台上传 dist/<plugin-name>.zip：

1. 管理后台 → 系统设置 → 插件中心 → 上传插件
2. 激活插件：检查服务日志输出带 [Plugin:<id>] 前缀
3. UI 工具验证：若声明了 classroomTools，进入课堂白板，验证工具栏图标正常显示且无布局挤压
4. AI 工具测试：发送自然语言命令测试 AI Agent 是否能够正确识别并触发 Actions

第六步：故障归因（插件侧 vs 系统侧）

当开发者报告「插件报错 / 不工作」时，先归因，再动手。不要立刻改代码，也不要立刻断言是平台问题。完整方法见 references/troubleshooting.md，此处为速用版。

三条铁律

1. 堆栈归属：顶层帧在 dist/index.js、dist/frontend.js → 插件侧；在 packages/core/...、src/plugin-host/...、node_modules/@openlearn/... → 系统 / SDK 侧。
2. 对照实验：官方脚手架原始产物、或 ≤50 行最小复现插件（仅 manifest + 空 activate）能否稳定复现——能复现的才是系统侧。
3. 先核版本：系统版本 / 插件 engines.openlearn / 所用 API 的最低版本。大量「系统 bug」其实是插件用了未来版本 API 或声明了不兼容 engines。

判为「系统侧」的 4 个必要条件（缺一即只能给「待定」）

1. 官方脚手架原始产物或最小复现插件稳定复现；
2. 具体版本号、复现步骤、完整堆栈（不截断）齐全；
3. 报错点位于宿主 / 内核 / SDK / 文档承诺范围内，而非插件自身代码或构建配置；
4. 已排除：版本不匹配、产物未重新构建、浏览器缓存、热重载未生效、权限未审批、插件间冲突。

结论与动作

必给的简要汇总（≤10 行）

【故障归因】<插件侧 / 系统侧 / 插件间冲突 / 环境与配置 / 待定>
现象：<一句话>
关键证据：
  1. <堆栈归属 / 版本核对 / 对照实验>
判定依据：<为什么是这一类，而非另一类>
建议动作：<修复方式 或 已生成 bug 报告：<路径>>

> 生成报告前务必确认已包含：具体版本号、完整堆栈、最小复现插件。缺这三项的报告通常会被系统作者以「信息不足」退回。

知识库与速查字典 (Reference Dictionaries)

1. 内核 Service Token & 接口方法速查

在 ctx.services 或通过 ctx.resolve(Token) 获取的核心服务列表及 API 方法签名：

2. Capabilities 权限全集字典

声明在 manifest.capabilitiesProposed 中的标准权限格式为 {resource}:{action}。常见权限分类如下：

3. UI 扩展槽位 Context & Props 全景表

前端扩展槽位组件被 Host 渲染时传递的 props 以及适用的挂载场景：

> 版本口径提示：上表部分槽位在官方文档中带「v3.2 / v5.2」等旧标签，但自平台 v0.2.3 起宿主 API 版本已与发行版本统一。具体可用性与 props 以 references/plugin-development-tutorial.md §6.4 与 references/architecture.md §8 为准。 锚点渲染是命令式的（ctx.ui.registerExtensionPoint），manifest.contributes 中的声明仅供管理后台枚举。

4. 前端共享依赖 (HostSharedDeps) 白名单

宿主通过 window.HostSharedDeps 全局提供以下共享运行时，切勿重复打入插件 bundle（构建时全部标记为 external）：

• JSX 模式：平台 0.3.15+ 已内置 react/jsx-runtime 映射，经典模式（"jsx": "react"）与自动模式（"jsx": "react-jsx"）均可；≤0.3.14 只能用经典模式，否则报 Failed to resolve module specifier "react/jsx-runtime"。
  > 口径提示：tutorial §6.7 与 architecture 均记为 0.3.15+，Release Notes v0.3.16 将白名单由 4 扩充至 6。不同来源口径不一，归因时以 Release Notes 为准，写代码时按“稳妥优先”处理。
  > 稳妥做法：无论目标版本，都把 react/jsx-runtime 一并标记为 external，并优先用经典模式 + 显式 import React。
• @openlearn/plugin-sdk 也由宿主提供，不必打包。
• 必须自行打包（宿主不共享）：socket.io-client、zustand、motion、react-konva/konva、react-markdown、xlsx、jspdf 等。

5. Worker 与 Inline 模式 API 差异（必读）

插件可能在 execution_mode: 'worker' 下运行，此时部分 API 不可用或方法名不同。写代码和排查故障时都要先确认执行模式：

> 插件违反上表属于插件侧问题；已按上表适配仍失败，才可能是系统侧。完整归因流程见 references/troubleshooting.md。

调试 SOP 与故障排查指南 (Troubleshooting SOP)

> 本表是「症状 → 直接处理」的速查。若需判定责任方（插件侧还是系统侧）并产出 bug 报告，请先走第六步，并阅读 references/troubleshooting.md。

资源文件说明

在线文档地址