From 8f671817a3399221f6f89eb913a2705b0c769c96 Mon Sep 17 00:00:00 2001 From: "bingxiang.cheng" Date: Fri, 17 Apr 2026 22:11:24 +0800 Subject: [PATCH] =?UTF-8?q?refactor(openmaic-classroom):=20=E8=A7=84?= =?UTF-8?q?=E8=8C=83=E6=96=87=E6=A1=A3=E5=B9=B6=E5=BC=BA=E5=8C=96mcp-api-r?= =?UTF-8?q?equester=E8=B0=83=E7=94=A8=E8=A6=81=E6=B1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 重新排版和规范技能说明文档,提升可读性 - 明确强调必须使用WeKnora的mcp-api-requester MCP工具调用OpenMAIC API - 取消curl命令降级方案,改为引导用户部署mcp-api-requester服务 - 增强本地模式Base URL处理,替换localhost和127.0.0.1为host.docker.internal - 完善错误处理和任务状态查询流程说明 - 更新API参考文档,统一接口描述和响应格式 - 细化多文档生成课程集的调用和错误引导逻辑 - 提示单次生成任务时间及托管模式配额限制 --- .../openmaic-classroom/SKILL.md | 43 +++++++++---------- .../references/api-reference.md | 0 .../references/requirement-builder.md | 0 .../scripts/rag-to-requirement.py | 0 4 files changed, 20 insertions(+), 23 deletions(-) rename skills/{ => preloaded}/openmaic-classroom/SKILL.md (85%) rename skills/{ => preloaded}/openmaic-classroom/references/api-reference.md (100%) rename skills/{ => preloaded}/openmaic-classroom/references/requirement-builder.md (100%) rename skills/{ => preloaded}/openmaic-classroom/scripts/rag-to-requirement.py (100%) diff --git a/skills/openmaic-classroom/SKILL.md b/skills/preloaded/openmaic-classroom/SKILL.md similarity index 85% rename from skills/openmaic-classroom/SKILL.md rename to skills/preloaded/openmaic-classroom/SKILL.md index c60a7b0e..3acb5dc0 100644 --- a/skills/openmaic-classroom/SKILL.md +++ b/skills/preloaded/openmaic-classroom/SKILL.md @@ -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 ` | 用户有 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 ` | -| 本地模式 | `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 " \ - -d '{"requirement": "..."}' -``` +告知用户: -**本地模式**: -```bash -curl -X POST /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 状态 diff --git a/skills/openmaic-classroom/references/api-reference.md b/skills/preloaded/openmaic-classroom/references/api-reference.md similarity index 100% rename from skills/openmaic-classroom/references/api-reference.md rename to skills/preloaded/openmaic-classroom/references/api-reference.md diff --git a/skills/openmaic-classroom/references/requirement-builder.md b/skills/preloaded/openmaic-classroom/references/requirement-builder.md similarity index 100% rename from skills/openmaic-classroom/references/requirement-builder.md rename to skills/preloaded/openmaic-classroom/references/requirement-builder.md diff --git a/skills/openmaic-classroom/scripts/rag-to-requirement.py b/skills/preloaded/openmaic-classroom/scripts/rag-to-requirement.py similarity index 100% rename from skills/openmaic-classroom/scripts/rag-to-requirement.py rename to skills/preloaded/openmaic-classroom/scripts/rag-to-requirement.py