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:
committed by
lyingbug
parent
fff89d3abb
commit
8f671817a3
@@ -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 状态
|
||||
Reference in New Issue
Block a user