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

2026-09-22 16:19:06 +08:00
commit f7fc992f57
3929 changed files with 1006607 additions and 0 deletions
@@ -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": []
+}
+```
@@ -0,0 +1,195 @@
+# 需求构建指南
+
+将 WeKnora RAG 检索结果转换为 OpenMAIC 课程生成所需的 `requirement` 格式。
+
+## 核心原则
+
+OpenMAIC 的 `requirement` 字段需要是**结构化的教学需求描述**，而不是原始文档片段。构建时需考虑：
+
+1. **教学主题**: 明确要教什么
+2. **目标受众**: 面向谁教学（如：初学者、专业人士、学生等）
+3. **教学深度**: 入门级、中级、高级
+4. **内容范围**: 基于哪些知识源构建
+
+## 转换模板
+
+### 模板 1: 纯需求（无检索结果）
+
+用户直接描述需求时，直接使用用户描述作为 requirement：
+
+```
+用户: "帮我创建一个关于量子力学的入门课程"
+→ requirement: "Create an introductory classroom on quantum mechanics for beginners"
+```
+
+### 模板 2: 基于 RAG 检索结果
+
+```
+步骤：
+1. 使用 knowledge_search 检索相关知识
+2. 从检索结果中提取：
+   - 核心主题/概念
+   - 关键知识点
+   - 文档来源信息
+3. 构建结构化 requirement
+```
+
+构建格式：
+```
+基于以下知识内容，创建一个面向[目标受众]的[深度级别]课程：
+
+核心主题：[从检索结果提取的主要概念]
+关键知识点：
+- [知识点1]
+- [知识点2]
+- ...
+内容来源：[文档名称列表]
+```
+
+### 模板 3: 基于单个文档
+
+```
+基于文档《[文档名称]》的内容，创建一个面向[目标受众]的课程，
+重点讲解以下方面：
+- [用户指定的重点1]
+- [用户指定的重点2]
+```
+
+### 模板 4: 基于多个文档/知识块
+
+```
+综合以下文档内容，创建一个系统的课程：
+
+文档1《[名称1]》: [简要内容摘要]
+文档2《[名称2]》: [简要内容摘要]
+文档3《[名称3]》: [简要内容摘要]
+
+要求：
+- 教学深度：[级别]
+- 目标受众：[描述]
+- 重点覆盖：[关键主题列表]
+```
+
+### 模板 5: 基于概念图遍历（Concept Graph）
+
+当从知识图谱 concept 页面及其关联 entity 生成微课堂时使用此模板。由 `scripts/concept-to-requirement.py` 自动生成。
+
+**输入结构**：
+```json
+{
+  "concept": { "slug": "concept/rag", "title": "RAG 检索增强生成", "summary": "...", "content": "..." },
+  "entities": [
+    { "slug": "entity/vector-db", "title": "向量数据库", "summary": "...", "link_type": "outlink" },
+    { "slug": "entity/embedding", "title": "Embedding 模型", "summary": "...", "link_type": "bidirectional" }
+  ],
+  "language": "zh-CN",
+  "depth": "intermediate",
+  "audience": "相关领域的学习者"
+}
+```
+
+**输出 requirement 结构**：
+```
+基于知识图谱概念「[concept.title]」，为[audience]创建一个[depth]微课堂（micro-classroom）。
+
+教学锚点：[concept.summary]
+
+学习目标：
+  - 理解[concept.summary 中的关键句]
+
+核心知识点：
+  - [从 concept.content 解析的定义/机制]
+
+关联实体（实践环节）：
+  - 案例：[entity.title]：[entity.summary]
+  - 工具：[entity.title]：[entity.summary]
+  - 应用场景：[entity.title]：[entity.summary]
+  - 前置知识：[entity.title]
+
+实践任务：
+  - 通过 [entity.title] 实践 [concept.title] 的应用
+
+常见误区检查：
+  - [从 concept.content 解析的误区]
+
+评估提示：
+  - 请解释 [concept.title] 的核心定义
+
+请使用中文生成课程内容。
+```
+
+**entity 分类排序规则**（纯文本操作，无 LLM/embedding）：
+- link_type 权重：bidirectional (+3) > outlink (+2) > inlink (+1)
+- title token overlap：concept title 分词后与 entity title 的交集数 (+1 per hit, cap +2)
+- summary keyword hit：concept summary 关键词在 entity summary 中出现 (+1 per hit, cap +2)
+- slug token hit：concept slug token 在 entity slug 中出现 (+1)
+- summary 为空扣分 (-2)
+- 取 top 3-5 entities，分为 Examples / Tools / Application Scenarios / Prerequisites
+
+**概念内容解析逻辑**：
+- 优先解析 markdown 结构：标题列表（定义段、机制段、案例段、误区段）
+- fallback 到前 N 字
+
+## 示例
+
+### 示例 1: 技术文档 → 课程
+
+```
+检索结果：
+- 文档: "Kubernetes 部署指南.pdf"
+- 关键内容: Pod 管理、Service 配置、Ingress 路由、存储卷
+
+构建的 requirement：
+"基于 Kubernetes 部署指南，创建一个面向 DevOps 工程师的中级课程。
+重点涵盖：Pod 生命周期管理、Service 和 Ingress 网络配置、持久化存储卷管理。
+课程应包含实践操作环节。"
+```
+
+### 示例 2: 产品手册 → 入门课程
+
+```
+检索结果：
+- 文档: "产品使用手册 v2.0.pdf"
+- 关键内容: 产品概述、快速开始、核心功能、常见问题
+
+构建的 requirement：
+"基于产品使用手册 v2.0，为新用户创建一个入门课程。
+帮助用户快速了解产品核心功能，掌握基本操作方法，
+并能够独立完成常见任务。课程语言为中文。"
+```
+
+### 示例 3: 研究论文 → 高级课程
+
+```
+检索结果：
+- 文档: "Transformer 架构研究综述.pdf"
+- 关键内容: Attention 机制、位置编码、多头注意力、训练技巧
+
+构建的 requirement：
+"基于 Transformer 架构研究综述，为具有深度学习基础的研究人员
+创建高级课程。深入讲解 Attention 机制的数学原理、位置编码的
+各种变体、多头注意力的设计动机，以及训练大模型时的实践技巧。"
+```
+
+## 可选功能配置建议
+
+在构建 request 时，根据用户需求推荐可选功能：
+
+| 场景 | 推荐功能 |
+|------|----------|
+| 技术培训 | `enableWebSearch: true`（补充最新技术动态） |
+| 产品介绍 | `enableImageGeneration: true`（生成产品截图/界面图） |
+| 市场营销 | `enableImageGeneration: true, enableVideoGeneration: true` |
+| 语言教学 | `enableTTS: true`（语音朗读） |
+| 学术研究 | 默认配置即可（不需要多媒体） |
+
+## 多文档处理
+
+当需要将多个独立文档分别生成课程时：
+
+1. 为每个文档单独构建 requirement
+2. 依次调用生成 API（不可并行）
+3. 每完成一个即返回 URL，继续下一个
+4. 最终汇总所有 Classroom URL
+
+> 注意：OpenMAIC 托管模式每天最多 10 次生成配额，本地模式取决于 LLM Provider 配额。