From d4ad3262df0b3816ba02b2ebf6d13e6753cbd851 Mon Sep 17 00:00:00 2001 From: WJZ_P <110795301+WJZ-P@users.noreply.github.com> Date: Mon, 23 Mar 2026 12:59:41 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- SKILL.md | 13 ++++++++++--- src/mcp-server.js | 20 +++++++++++++++----- 2 files changed, 25 insertions(+), 8 deletions(-) diff --git a/SKILL.md b/SKILL.md index 33f2127..f97c9df 100644 --- a/SKILL.md +++ b/SKILL.md @@ -17,9 +17,16 @@ description: 通过 Gemini 官网（gemini.google.com）执行生图、对话等 > 浏览器 Daemon 未运行时 MCP 工具会自动拉起，无需任何手动操作。 -## 📡 进度同步 +## 📡 进度同步 & 长耗时工具规则 -MCP 工具调用（尤其是生图、等待回复等）可能耗时较长。**每隔 15 秒必须主动向用户发送一条进度消息**，告知当前操作状态（如"正在等待 Gemini 生成图片…"、"图片仍在加载中，已等待 30 秒…"），避免用户长时间挂起收不到任何反馈。 +MCP 工具调用（尤其是生图、等待回复等）可能耗时较长（60~180 秒）。必须遵守以下规则： + +- **本 Skill 所有 MCP 工具均为同步阻塞调用**，会等到最终结果才返回。不存在"中间状态"需要轮询。 +- 调用长耗时工具时，`timeoutMs` 必须设为 ≥180000（3 分钟），避免传输层提前超时截断。 +- **禁止在未收到工具最终返回前结束对话**或向用户报告"还在运行"/"工具超时"。 +- 每隔 15~30 秒向用户发送一条进度消息（如"正在等待 Gemini 生成图片…已等待 30 秒…"），保持反馈。 +- 拿到最终结果后**立即**回传产物（文件路径）或报告错误，不得遗漏。 +- 若 `fullSize` 模式失败，可降级重试 `fullSize=false`（预览图模式更稳定）。 ## 触发关键词 @@ -48,7 +55,7 @@ MCP 工具调用（尤其是生图、等待回复等）可能耗时较长。** | 工具名 | 说明 | 入参 | |--------|------|------| -| `gemini_generate_image` | 完整生图流程：新建会话→发prompt→等待→提取图片→保存本地（耗时约 60~120 秒） | `prompt`，`newSession`（默认false），`referenceImages`（参考图路径数组），`fullSize`（默认false，true则下载高清原图），`timeout`（默认180000ms） | +| `gemini_generate_image` | 完整生图流程：新建会话→发prompt→等待→提取图片→保存本地（耗时约 60~120 秒） | `prompt`，`newSession`（默认false），`referenceImages`（参考图路径数组），`fullSize`（默认true，高清原图；false则预览图），`timeout`（默认120000ms） | **会话管理：** diff --git a/src/mcp-server.js b/src/mcp-server.js index 4aa11dd..f636c6e 100644 --- a/src/mcp-server.js +++ b/src/mcp-server.js @@ -35,11 +35,17 @@ const server = new McpServer({ server.registerTool( "gemini_generate_image", { - description: "调用后台的 Gemini 浏览器会话生成高质量图片。注意：生图过程较慢（通常 60~120 秒），请耐心等待", + description: `调用后台的 Gemini 浏览器会话生成高质量图片。 + +【重要：长耗时工具】 +- 本工具为同步阻塞调用，内部会等待 Gemini 生成完毕后才返回最终结果（成功/失败+文件路径）。 +- 典型耗时 60~120 秒，复杂图片可能更久。调用时 timeoutMs 务必设为 ≥120000（2分钟）。 +- 禁止在未收到本工具最终返回前结束对话或向用户报告"还在运行"。 +- 必须等到拿到最终成功/失败结果后，再向用户回传产物（文件路径）或报告错误。`, inputSchema: { - prompt: z.string().describe("图片的详细描述词"), + prompt: z.string().describe("图片的详细描述词。提示：描述越详细越好，包含风格、构图、色调等关键词能显著提升生成质量"), newSession: z.boolean().default(false).describe( - "是否新建会话。true= 开启全新对话; false = 复用当前已有的 Gemini 会话页" + "是否新建会话。true= 开启全新对话（推荐生成全新图片时使用）; false= 复用当前会话（适合基于上下文迭代修改）" ), referenceImages: z.array(z.string()).default([]).describe( "参考图片的本地文件路径数组，例如 [\"/path/to/ref1.png\", \"/path/to/ref2.jpg\"]。图片会在发送 prompt 前上传到 Gemini 输入框" @@ -238,7 +244,9 @@ server.registerTool( server.registerTool( "gemini_send_message", { - description: "向 Gemini 发送文本消息并等待回答完成（不提取图片，纯文本交互）", + description: `向 Gemini 发送文本消息并等待回答完成（不提取图片，纯文本交互）。 + +【长耗时工具】同步阻塞等待 Gemini 回复完毕才返回。典型耗时 10~60 秒，必须等到最终结果再回传用户。`, inputSchema: { message: z.string().describe("要发送给 Gemini 的文本内容"), timeout: z.number().default(120000).describe("等待回答完成的超时时间（毫秒），默认 120000"), @@ -373,7 +381,9 @@ server.registerTool( server.registerTool( "gemini_download_full_size_image", { - description: "下载完整尺寸的图片（高清大图）。默认下载最新一张，也可通过 index 指定第几张（从0开始，从旧到新排列）", + description: `下载完整尺寸的图片（高清大图）。默认下载最新一张，也可通过 index 指定第几张（从0开始，从旧到新排列）。 + +【长耗时工具】需要 hover 触发工具栏 + CDP 拦截下载，典型耗时 10~30 秒。必须等到最终结果。`, inputSchema: { index: z.number().int().min(0).optional().describe( "图片索引，从0开始，按从旧到新排列。不传则下载最新一张"