foliko 2.0.21 → 2.0.23

package/plugins/executors/extension/index.js

@@ -219,28 +219,35 @@ class ExtensionExecutorPlugin extends Plugin {
       description:
         '【⚡ 执行扩展工具】调用某个扩展插件的具体工具。\n' +
         '\n' +
-        '**必传参数**：\n' +
+        '**三个参数都必须传**（即使 args 是空对象也要写成 `args: {}`）：\n' +
         '- `plugin`：插件名（命名空间支持 4 种：普通插件名 `email` / MCP 服务器 `mcp:<server>` / Skill `skill:<name>` / Python 插件 `python:<plugin>`）\n' +
         '- `tool`：工具名（来自 ext_list 或 ext_skill 输出）\n' +
-        '- `args`：参数对象（每个工具的必填项见 ext_skill 输出）\n' +
+        '- `args`：**参数对象**。绝大多数工具都需要参数（id、name、path 等），传 `args: {}` 会导致"参数缺失"错误\n' +
         '\n' +
-        '**推荐使用顺序**：`ext_list` 查看所有可用插件 → `ext_skill` 查看参数细节 → `ext_call` 执行\n' +
+        '**🚨 重要工作流**：\n' +
+        '1. 先调 `ext_list` 找到工具名\n' +
+        '2. **必须先调 `ext_skill({plugin: "..."})` 拿到该工具的完整参数 schema**（必填项、类型）\n' +
+        '3. 按 schema 填好 `args` 再调 `ext_call`\n' +
         '\n' +
-        '**调用示例**：\n' +
+        '**调用示例**（多参数必填）：\n' +
         '```js\n' +
         'ext_call({\n' +
-        '  plugin: "mcp:designmd",\n' +
-        '  tool: "search_design_kits",\n' +
-        '  args: { query: "modern" }\n' +
+        '  plugin: "skill:video-creator",\n' +
+        '  tool: "addCover",\n' +
+        '  args: { id: "abc123", title: "视频标题", subtitle: "副标题", duration: 3, background: "#0a0e27" }\n' +
         '})\n' +
         '```\n' +
         '\n' +
         '**返回值**：`{success: true, data: <工具返回的数据>}` 或 `{success: false, error: "<错误信息>"}`\n' +
-        '**注意**：调用前必须先调 ext_skill 确认参数格式和必填项，否则可能因参数缺失失败',
+        '\n' +
+        '**常见错误**：\n' +
+        '- `参数缺失：...` → 你传了 `args: {}`，但工具需要参数。先调 `ext_skill` 查必填字段\n' +
+        '- `视频项目不存在: undefined` → `args.id` 没传，参考 ext_skill 输出的 `id` 必填项\n',
       inputSchema: z.object({
         plugin: z.string().describe('插件名称（如 email, gate-trading, mcp:designmd, skill:my-skill, python:stock）'),
         tool: z.string().describe('工具名称（来自 ext_list 输出）'),
-        args: z.record(z.any()).optional().describe('工具参数（对象格式，详见 ext_skill 输出）'),
+        // ★ 关键：保持 optional 让 LLM 调用简单，但 description 强调必填
+        args: z.record(z.any()).optional().describe('⚠️ 必填！工具参数对象。必须先调 ext_skill({plugin: "..."}) 查必填项，然后传完整对象'),
       }),
       execute: async (args) => {
         const { plugin, tool, args: toolArgs = {} } = args;
@@ -358,6 +365,10 @@ class ExtensionExecutorPlugin extends Plugin {
     if (toolDef.inputSchema && typeof toolDef.inputSchema.safeParse === 'function') {
       const parsed = toolDef.inputSchema.safeParse(toolArgs);
       if (!parsed.success) {
+        // ★ 优化：如果 args 是空对象且 schema 有必填项，给 LLM 更明确的提示
+        if (toolArgs && typeof toolArgs === 'object' && Object.keys(toolArgs).length === 0) {
+          return this._emptyArgsError(plugin, tool, toolArgs, toolDef, parsed.error);
+        }
         return this._paramValidationError(plugin, tool, parsed.error);
       }
     }
@@ -432,6 +443,54 @@ class ExtensionExecutorPlugin extends Plugin {
     };
   }
 
+  /**
+   * 专门处理 args={} 的情况 —— LLM 经常忘记传 args
+   * 给一个非常具体的错误，让 LLM 自我纠正
+   * @private
+   */
+  _emptyArgsError(plugin, tool, toolArgs, toolDef, zodError) {
+    // 尝试从 toolDef 的 inputSchema 提取必填字段
+    let requiredFields = [];
+    try {
+      const schemaShape = toolDef.inputSchema?.shape || toolDef.inputSchema?._def?.schema?.shape;
+      if (schemaShape) {
+        for (const [key, value] of Object.entries(schemaShape)) {
+          // zod 字段上 isOptional() 返回 false 表示必填
+          if (value && typeof value.isOptional === 'function' && !value.isOptional()) {
+            requiredFields.push(key);
+          }
+        }
+      }
+    } catch { /* ignore */ }
+
+    const requiredHint = requiredFields.length > 0
+      ? `\n  必填字段：${requiredFields.join(', ')}`
+      : '';
+
+    // 直接从 issues 中提取 path 作为必填字段
+    if (requiredFields.length === 0 && zodError?.issues) {
+      const paths = new Set();
+      for (const iss of zodError.issues) {
+        if (iss.path && iss.path.length > 0) paths.add(iss.path[0]);
+      }
+      if (paths.size > 0) {
+        requiredFields = Array.from(paths);
+      }
+    }
+
+    const finalHint = requiredFields.length > 0
+      ? `\n  必填字段：${requiredFields.join(', ')}`
+      : '';
+
+    return {
+      success: false,
+      error: `参数缺失：'${plugin}:${tool}' 调用时 args 为空对象 {}。该工具需要参数。`,
+      receivedArgs: toolArgs,
+      hint: `请使用 ext_skill({ plugin: "${plugin}" }) 查看 "${tool}" 工具的完整参数说明（包括必填字段）。${finalHint}`,
+      action: 'call_ext_skill_first',
+    };
+  }
+
   /** 执行时错误 */
   _executionError(plugin, tool, err) {
     const message = (err && err.message) || String(err);