用途
openmaic-classroom 用于将 WeKnora 知识库中的内容转换为 OpenMAIC 互动课程。根据技能说明，它面向以下场景：把文档做成课件、基于检索结果生成课程、为知识点创建互动课堂、将知识库内容转为教学材料，以及批量生成课程或基于概念图生成微课堂。
支持的输入源
技能定义了四种输入源：
- 纯需求生成：用户直接描述教学主题，无需额外文档，直接使用该描述作为 requirement。
- RAG 检索结果：先通过 knowledge_search 检索相关知识，再用 scripts/rag-to-requirement.py 将 chunks 转换为结构化 requirement。
- PDF 文件：用户提供 PDF 路径，提取文本后构建 requirement，并将解析结果填入 pdfContent。
- 概念图遍历批量生成：遍历知识图谱中的所有 concept 页面，用 scripts/concept-to-requirement.py 将 concept 及关联 entity 转换为 requirement，每个 concept 生成一个 micro-classroom。
主要能力
技能说明列出的核心能力包括：RAG → 课程、PDF → 课程、文档块 → 课程集，以及概念图遍历 → 批量微课堂。生成请求支持的字段有 requirement（必填）、pdfContent、language（默认 zh-CN）、enableWebSearch、enableImageGeneration、enableVideoGeneration、enableTTS、agentMode。是否可启用网络搜索、配图、视频和语音等可选功能，需先查询服务端的 /api/health 接口返回的 capabilities，仅当对应项为 true 时才可设为 true。
使用方式
创建课程前需先确认使用模式。托管模式使用 https://open.maic.chat，认证方式为 Authorization: Bearer <access-code>，需要以 sk- 开头的访问码；本地模式由用户自行部署，无认证，需用户提供本地地址。由于 WeKnora 运行在 Docker 容器内，本地地址中的 127.0.0.1 和 localhost 会被替换为 host.docker.internal。调用前需通过 GET <BASE_URL>/api/health 验证服务可用。
API 调用必须通过 WeKnora 注册的 mcp_api_requester MCP 工具完成，工具名称格式为 mcp_{service_name}_{tool_name}。技能明确不提供 curl 命令作为降级方案；若该 MCP 工具未配置或不可用，需引导用户先从 https://github.com/yryuu/mcp-api-requester 下载代码并部署，再在 WeKnora 中注册。
生成流程为：确定输入源后构建 requirement，通过 MCP 工具向 /api/generate-classroom 发送 POST 请求，返回 jobId 和 pollUrl。提交后只查询一次状态；若为 queued 或 running，需停止轮询并告知用户课程正在生成，预计 2 至 10 分钟；用户再次询问进度时再查询一次。仅在状态为 succeeded 或 failed 时继续处理。成功后返回 classroomId 与课程 URL：<BASE_URL>/classroom/<classroomId>。
批量场景下，多文档可分别生成 requirement 并顺序调用生成 API，汇总返回所有课堂 URL。概念图批量生成时，使用 wiki_search 列出 concept 页面，用 wiki_read_page 获取详情与关联 entity（entity 只取 title 与 summary），再顺序调用 API（concurrency=1，不可并行），并生成 manifest JSON 记录 generated、failed、pending 状态，以便失败时从断点继续。
适用场景与限制
根据技能说明，脚本在 Docker 沙箱中执行，沙箱默认禁用网络访问。单次生成任务预计 2 至 10 分钟。托管模式每天最多 10 次生成配额，独立于 Web UI 配额。常见错误包括连接失败、401（访问码无效）、403（每日配额用尽，次日零点重置）、500（服务器错误）以及 Provider 配置错误。若同一 job 仍在运行，不应重复提交新生成请求。