WeKnora deployment source with the reviewed wiki identity, summary and recovery fixes

skills/preloaded/openmaic-classroom/references/api-reference.md

@@ -0,0 +1,297 @@
+# OpenMAIC API Reference
+
+OpenMAIC 服务 API 接口规范。所有 API 基础路径为 `{base_url}/api`，默认 `http://localhost:3000/api`。
+
+## 认证机制
+
+- 如果 OpenMAIC 未设置 `ACCESS_CODE` 环境变量：所有接口开放
+- 如果设置了 `ACCESS_CODE`：需先通过 `/api/access-code/verify` 获取 cookie
+- `/api/health` 始终无需认证
+
+### 获取认证 Cookie
+
+```
+POST {base_url}/api/access-code/verify
+Content-Type: application/json
+
+{ "code": "<ACCESS_CODE>" }
+```
+
+成功返回 `{ "success": true, "valid": true }` 并设置 `openmaic_access` cookie（7 天有效）。
+
+## 标准响应格式
+
+**成功**:
+```json
+{ "success": true, ...additionalFields }
+```
+
+**错误**:
+```json
+{ "success": false, "errorCode": "<Code>", "error": "<message>", "details?": "<detail>" }
+```
+
+---
+
+## 核心端点
+
+### 1. 健康检查
+
+```
+GET {base_url}/api/health
+```
+
+响应：
+```json
+{
+  "success": true,
+  "status": "ok",
+  "version": "0.1.0",
+  "capabilities": {
+    "webSearch": true,
+    "imageGeneration": false,
+    "videoGeneration": false,
+    "tts": true
+  }
+}
+```
+
+> `capabilities` 用于功能检测，只在返回此字段时才启用对应的可选功能。
+
+---
+
+### 2. 生成课程（异步任务）
+
+#### 2a. 创建生成任务
+
+```
+POST {base_url}/api/generate-classroom
+Content-Type: application/json
+```
+
+请求体：
+```json
+{
+  "requirement": "教学主题描述",
+  "pdfContent": { "text": "PDF文本内容", "images": [] },
+  "enableWebSearch": false,
+  "enableImageGeneration": false,
+  "enableVideoGeneration": false,
+  "enableTTS": false,
+  "agentMode": "default"
+}
+```
+
+成功响应 (202):
+```json
+{
+  "success": true,
+  "jobId": "abc123xyz",
+  "status": "queued",
+  "step": "queued",
+  "message": "Classroom generation job queued",
+  "pollUrl": "{base_url}/api/generate-classroom/abc123xyz",
+  "pollIntervalMs": 5000
+}
+```
+
+错误：
+- `400`: `requirement` 字段缺失
+- `500`: 内部错误
+
+#### 2b. 轮询任务状态
+
+```
+GET {pollUrl}
+```
+
+响应：
+```json
+{
+  "success": true,
+  "jobId": "abc123xyz",
+  "status": "running",
+  "step": "generating_outlines",
+  "progress": 35,
+  "message": "Generating scene outlines...",
+  "pollUrl": "...",
+  "pollIntervalMs": 5000,
+  "scenesGenerated": 2,
+  "totalScenes": 6,
+  "result": null,
+  "error": null,
+  "done": false
+}
+```
+
+最终成功响应：
+```json
+{
+  "success": true,
+  "status": "succeeded",
+  "result": {
+    "classroomId": "Uyh82Y32ZK",
+    "url": "{base_url}/classroom/Uyh82Y32ZK",
+    "scenesCount": 6
+  },
+  "done": true
+}
+```
+
+最终失败响应：
+```json
+{
+  "success": true,
+  "status": "failed",
+  "error": "具体错误信息",
+  "done": true
+}
+```
+
+---
+
+### 3. 解析 PDF
+
+```
+POST {base_url}/api/parse-pdf
+Content-Type: multipart/form-data
+```
+
+表单字段：
+- `pdf`（文件，必填）: PDF 文件
+- `providerId`（可选）: PDF 提供商，默认 `"unpdf"`
+- `apiKey`（可选）: 提供商 API Key
+- `baseUrl`（可选）: 提供商基础 URL
+
+响应：
+```json
+{
+  "success": true,
+  "data": {
+    "text": "提取的文本内容",
+    "images": [],
+    "metadata": {
+      "pageCount": 10,
+      "fileName": "document.pdf",
+      "fileSize": 1024000
+    }
+  }
+}
+```
+
+---
+
+### 4. 课程存储
+
+#### 4a. 获取课程
+
+```
+GET {base_url}/api/classroom?id=<classroomId>
+```
+
+#### 4b. 持久化课程
+
+```
+POST {base_url}/api/classroom
+Content-Type: application/json
+
+{ "stage": {...}, "scenes": [...] }
+```
+
+---
+
+### 5. Web 搜索
+
+```
+POST {base_url}/api/web-search
+Content-Type: application/json
+
+{ "query": "搜索关键词", "pdfText": "PDF上下文", "apiKey": "Tavily Key" }
+```
+
+---
+
+### 6. 验证 LLM 连接
+
+```
+POST {base_url}/api/verify-model
+Content-Type: application/json
+
+{ "model": "openai:gpt-4o", "apiKey": "...", "baseUrl": "..." }
+```
+
+---
+
+## 生成管线（逐步调用）
+
+如果需要更细粒度的控制，可以使用以下逐步生成端点代替 `/api/generate-classroom`：
+
+### A. 生成场景大纲（SSE 流）
+
+```
+POST {base_url}/api/generate/scene-outlines-stream
+```
+
+请求体：
+```json
+{
+  "requirements": { "requirement": "主题", "userNickname": "用户昵称" },
+  "pdfText": "PDF文本",
+  "pdfImages": [],
+  "researchContext": "网络搜索结果",
+  "agents": []
+}
+```
+
+Headers:
+- `x-image-generation-enabled`: `"true"` 或 `"false"`
+- `x-video-generation-enabled`: `"true"` 或 `"false"`
+
+SSE 事件类型：`languageDirective`、`outline`、`done`、`error`、`retry`
+
+### B. 生成场景内容
+
+```
+POST {base_url}/api/generate/scene-content
+Content-Type: application/json
+
+{
+  "outline": {...},
+  "allOutlines": [...],
+  "stageId": "stage-1",
+  "pdfImages": [],
+  "agents": [],
+  "languageDirective": "使用简体中文"
+}
+```
+
+### C. 生成场景动作
+
+```
+POST {base_url}/api/generate/scene-actions
+Content-Type: application/json
+
+{
+  "outline": {...},
+  "allOutlines": [...],
+  "content": {...},
+  "stageId": "stage-1",
+  "agents": [],
+  "languageDirective": "使用简体中文"
+}
+```
+
+### D. 生成 Agent 画像
+
+```
+POST {base_url}/api/generate/agent-profiles
+Content-Type: application/json
+
+{
+  "stageInfo": { "name": "入门阶段", "description": "..." },
+  "sceneOutlines": [{ "title": "...", "description": "..." }],
+  "languageDirective": "使用简体中文",
+  "availableAvatars": [],
+  "avatarDescriptions": []
+}
+```