refactor(openmaic-classroom): 规范文档并强化mcp-api-requester调用要求

- 重新排版和规范技能说明文档,提升可读性
- 明确强调必须使用WeKnora的mcp-api-requester MCP工具调用OpenMAIC API
- 取消curl命令降级方案,改为引导用户部署mcp-api-requester服务
- 增强本地模式Base URL处理,替换localhost和127.0.0.1为host.docker.internal
- 完善错误处理和任务状态查询流程说明
- 更新API参考文档,统一接口描述和响应格式
- 细化多文档生成课程集的调用和错误引导逻辑
- 提示单次生成任务时间及托管模式配额限制
This commit is contained in:
bingxiang.cheng
2026-04-17 22:11:24 +08:00
committed by lyingbug
parent fff89d3abb
commit 8f671817a3
4 changed files with 20 additions and 23 deletions
@@ -17,8 +17,7 @@ description: 将 RAG 检索结果或文档块转换为 OpenMAIC 互动课程。
> **通过 WeKnora 注册的 mcp-api-requester MCP 工具,你可以直接调用 OpenMAIC API**(HTTP POST/GET 请求)。
> 该工具在 WeKnora agent 中注册为 `mcp_{service_name}_{tool_name}` 格式(如 `mcp_mcp_api_requester_make_request`)。
> 不再需要向用户提供 curl 命令——直接在后台调用 API 并交付结果。
> 如果 MCP 工具未配置或不可用,则降级为展示 curl 命令让用户手动执行。
> **必须**使用该 MCP 工具调用 API。如果 MCP 工具未配置或不可用,引导用户先部署 mcp-api-requester,不提供 curl 命令。
> **⚠️ MCP 可用性检查(每次读取此文件后必须执行):**
> 在开始工作前,检查可用的 MCP 工具列表中是否存在名称包含 `mcp_api_requester` 的工具。
@@ -32,13 +31,22 @@ OpenMAIC 有两种使用模式,**根据用户场景选择**:
| 模式 | Base URL | 认证方式 | 适用场景 |
|------|----------|----------|----------|
| 托管模式(推荐快速使用) | `https://open.maic.chat` | `Authorization: Bearer <access-code>` | 用户有 open.maic.chat 访问码,无需本地部署 |
| 本地模式 | `http://host.docker.internal:3000`(WeKnora 在容器内)或 `http://localhost:3000`(本地直接运行) | 无认证(本地自部署) | 用户自行部署了 OpenMAIC 实例 |
| 本地模式 | 用户提供(见本地模式 Base URL 处理) | 无认证(本地自部署) | 用户自行部署了 OpenMAIC 实例 |
**判断规则**:
- 用户提到"在线服务"、"open.maic.chat"、"访问码" → 使用托管模式
- 用户提到"本地部署"、"自建" → 使用本地模式
- 用户未明确说明时,优先询问用户使用哪个模式
**本地模式 Base URL 处理**:
1. 用户选择本地模式后,必须询问用户:"请输入你的 OpenMAIC 本地部署地址(例如 `http://localhost:3000` 或 `http://192.168.1.100:3000`)"
2. 收到用户提供的地址后,进行如下处理:
- 将地址中的 `127.0.0.1` 替换为 `host.docker.internal`
- 将地址中的 `localhost` 替换为 `host.docker.internal`
- 其他地址保持不变
> ⚠️ WeKnora 运行在 Docker 容器内,`localhost` 和 `127.0.0.1` 指向容器自身,无法访问宿主机服务。必须使用 `host.docker.internal` 作为容器访问宿主机的桥接地址。
## 前置条件
| 配置项 | 说明 |
@@ -121,14 +129,14 @@ execute_skill_script(
- 在你可用的 MCP 工具中,找到用于 HTTP 请求的工具
- 工具名称格式为 `mcp_{service_name}_{tool_name}`(如 `mcp_mcp_api_requester_make_request`)
- 通过工具描述(description)识别:寻找包含 "HTTP request"、"API"、"GET/POST" 等关键词的工具
- 如果找不到 HTTP 请求类 MCP 工具,则降级为 curl 方案
- 如果找不到 HTTP 请求类 MCP 工具,则引导用户部署 mcp-api-requester(见 MCP 可用性检查)
**第二步:确定 Base URL 和认证 Header**
| 模式 | Base URL | 认证 Header |
|------|----------|-------------|
| 托管模式 | `https://open.maic.chat` | `Authorization: Bearer <access-code>` |
| 本地模式 | `http://host.docker.internal:3000` 或 `http://localhost:3000` | 无 |
| 本地模式 | 用户提供的地址(已将 `localhost`/`127.0.0.1` 替换为 `host.docker.internal`) | 无 |
**第三步:Feature Detection(发送可选功能前)**
@@ -183,22 +191,11 @@ execute_skill_script(
}
```
**降级方式**:如果 MCP 工具不可用,向用户展示 curl 命令:
**MCP 工具不可用的处理**:
**托管模式**:
```bash
curl -X POST https://open.maic.chat/api/generate-classroom \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access-code>" \
-d '{"requirement": "..."}'
```
告知用户:
**本地模式**:
```bash
curl -X POST <BASE_URL>/api/generate-classroom \
-H "Content-Type: application/json" \
-d '{"requirement": "..."}'
```
> 未检测到 `mcp_api_requester` MCP 服务。请先从 https://github.com/yryuu/mcp-api-requester 下载代码并部署,然后在 WeKnora 中注册该 MCP 服务。
### Phase 4: 查询任务进度
@@ -252,7 +249,7 @@ Classroom URL:
| 401 | 访问码无效(托管模式) | 告知用户到 open.maic.chat 检查或重新生成访问码 |
| 403 | 每日配额用尽(托管模式) | 告知每日 10 次限制,次日零点重置 |
| 500 | 服务器错误 | 建议稍后重试或切换到本地模式 |
| Provider 配置错误 | 模型/Provider/认证问题 | 引导用户检查 `.env.local` 或 `server-providers.yml` |
| Provider 配置错误 | 模型/Provider/认证问题 | 引导用户检查 配置或联系管理员 |
## 多文档 → 课程集
@@ -261,15 +258,15 @@ Classroom URL:
1. 收集所有文档内容
2. 为每个文档/主题分别生成 requirement
3. 通过 MCP 工具依次调用生成 API(不可并行,避免配额冲突)
4. 如果 MCP 工具不可用,依次提供对应的 curl 命令
4. 如果 MCP 工具不可用,告知用户先部署 mcp-api-requester(见 MCP 可用性检查)
5. 汇总返回所有 Classroom URL
## 注意事项
- 脚本在 Docker 沙箱中执行,**沙箱默认禁用网络访问**
- **通过 WeKnora MCP 工具,你可以直接调用 OpenMAIC API**——不再需要用户提供 curl 命令
- **必须通过 WeKnora MCP 工具调用 OpenMAIC API**——不提供 curl 命令作为降级方案
- MCP 工具名称格式为 `mcp_{service_name}_{tool_name}`,根据描述识别 HTTP 请求工具
- 如果 MCP 工具未启用或不可用,降级为展示 curl 命令让用户手动执行
- 如果 MCP 工具未启用或不可用,告知用户先从 https://github.com/yryuu/mcp-api-requester 下载代码并部署,然后在 WeKnora 中注册该 MCP 服务
- 单次生成任务预计 2-10 分钟,取决于内容复杂度和可选功能
- 托管模式(open.maic.chat)每天最多 10 次生成配额,独立于 Web UI 配额
- 如果用户在同一个 job 仍在运行时要求生成新课程,不要重复提交——先检查已有 job 状态