foliko 2.0.21 → 2.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foliko",
-  "version": "2.0.21",
+  "version": "2.0.22",
   "description": "简约的插件化 Agent 框架",
   "main": "src/index.js",
   "type": "commonjs",
@@ -61,6 +61,7 @@
     "@chnak/weixin-bot": "^1.2.9",
     "@chnak/zod-to-markdown": "1.0.7",
     "@earendil-works/pi-tui": "^0.75.3",
+    "@frsource/frs-replace": "^5.1.117",
     "@hono/node-server": "^1.19.11",
     "@larksuiteoapi/node-sdk": "^1.59.0",
     "@modelcontextprotocol/sdk": "^1.27.1",

package/plugins/core/skill-manager/index.js

@@ -272,12 +272,11 @@ function buildSchemaFromType(type, desc, defaultValue) {
  */
 function buildInputSchemaFromOptions(options) {
   if (!Array.isArray(options) || options.length === 0) {
-    return { type: 'object', properties: {}, required: [] };
+    // 返回 zod schema（即使是空的也返回），确保 _doExecute 走校验路径
+    return require('zod').z.object({}).passthrough();
   }
 
-  const properties = {};
-  const required = [];
-
+  const shape = {};
   for (const opt of options) {
     const name = extractOptionName(opt.flags);
     if (!name) continue;
@@ -287,33 +286,45 @@ function buildInputSchemaFromOptions(options) {
     const desc = opt.description || '';
     const defaultVal = opt.defaultValue;
 
-    let jsonType = 'string';
+    // ★ 关键修复：返回 zod schema（不是纯 JSON Schema），
+    //   这样 _doExecute 里的 toolDef.inputSchema.safeParse 才会真的执行校验。
+    //   之前返回 JSON Schema 对象没有 .safeParse 方法，校验被完全跳过。
+    //   导致 LLM 传 args:{} 不会报错，直接到达工具 → args.id undefined。
+    const z = require('zod').z;
+    let zodField;
     if (opt.schema && typeof opt.schema.parse === 'function') {
-      // 从 Zod 实例猜测类型
-      const s = opt.schema;
-      if (s._def.typeName === 'ZodNumber' || s._def.typeName === 'ZodInt') jsonType = 'number';
-      else if (s._def.typeName === 'ZodBoolean') jsonType = 'boolean';
-      else if (s._def.typeName === 'ZodArray') jsonType = 'array';
-      else if (s._def.typeName === 'ZodObject' || s._def.typeName === 'ZodRecord') jsonType = 'object';
-    } else if (opt.type) {
-      const L = opt.type.toLowerCase();
-      if (L === 'number' || L === 'int' || L === 'integer') jsonType = 'number';
-      else if (L === 'boolean' || L === 'bool') jsonType = 'boolean';
-      else if (L === 'array') jsonType = 'array';
-      else if (L === 'object') jsonType = 'object';
+      zodField = opt.schema;
     } else {
-      jsonType = hasValue ? 'string' : 'boolean';
+      const type = (opt.type || (hasValue ? 'string' : 'boolean')).toLowerCase();
+      if (type === 'number' || type === 'int' || type === 'integer') {
+        zodField = z.number();
+      } else if (type === 'boolean' || type === 'bool') {
+        zodField = z.boolean();
+      } else if (type === 'array') {
+        zodField = z.array(z.any());
+      } else if (type === 'object') {
+        zodField = z.object({}).passthrough();
+      } else {
+        zodField = z.string();
+      }
     }
 
-    const prop = { type: jsonType, description: desc };
+    if (!isRequired) {
+      zodField = zodField.optional();
+    }
     if (defaultVal !== undefined && defaultVal !== null) {
-      prop.default = defaultVal;
+      zodField = zodField.default(defaultVal);
     }
-    properties[name] = prop;
-    if (isRequired) required.push(name);
+    // 描述里加 (必填) 标记，方便 LLM 看到
+    zodField = zodField.describe(desc + (isRequired ? '（必填）' : ''));
+
+    shape[name] = zodField;
   }
 
-  return { type: 'object', properties, required };
+  if (Object.keys(shape).length === 0) {
+    return require('zod').z.object({}).passthrough();
+  }
+  return require('zod').z.object(shape).passthrough();
 }
 
 /**

package/plugins/core/sub-agent/index.js

@@ -26,6 +26,16 @@ class SubAgentPlugin extends Plugin {
     this.llmConfig = config.llmConfig || null
     this.hidden = config.hidden || false  // 隐藏子Agent，不在指令系统中显示
 
+    // ★ 新增：frontmatter 之外的配置
+    // systemPrompt: 来自 markdown body（自动提取）
+    // skills: 来自 frontmatter 的 `skills: a, b, c` 字段，技能名数组
+    this.systemPrompt = config.systemPrompt || ''
+    this.skills = Array.isArray(config.skills)
+      ? config.skills
+      : (typeof config.skills === 'string'
+          ? config.skills.split(',').map(s => s.trim()).filter(Boolean)
+          : [])
+
     this.config = {}
 
     this._framework = null
@@ -266,6 +276,24 @@ class SubAgentPlugin extends Plugin {
   }
 
   _getFullSystemPrompt() {
+    // ★ 优先用 markdown body 提取的 systemPrompt（来自 _parseMarkdownConfig）
+    // 然后叠加 skills 列表（自动从 skill-manager 查询命令并注入）
+    const base = this._buildBaseSystemPrompt();
+    const skillsSection = this._buildSkillsSection();
+    if (skillsSection) {
+      return base + '\n\n' + skillsSection;
+    }
+    return base;
+  }
+
+  _buildBaseSystemPrompt() {
+    // 1) 显式配置的 systemPrompt 优先
+    if (this.systemPrompt && this.systemPrompt.trim()) {
+      // 已经是 markdown body（含 "你是..." 这类角色定义）
+      const header = `# ${this.name}\n\n${this.description || ''}`.trim();
+      return `${header}\n\n${this.systemPrompt.trim()}`;
+    }
+    // 2) 回退到 subAgentConfigManager
     const configManager = this._framework._subAgentConfigManager;
     if (configManager) {
       const config = configManager.get(this.name);
@@ -273,10 +301,43 @@ class SubAgentPlugin extends Plugin {
         return config.getSystemPrompt();
       }
     }
-
+    // 3) 最后回退到 _buildSystemPrompt（旧逻辑）
     return this._buildSystemPrompt();
   }
 
+  /**
+   * 根据 this.skills 列表，从 skill-manager 查询每个 skill 的命令，
+   * 生成 "## 可用技能" section 注入 systemPrompt
+   * @private
+   */
+  _buildSkillsSection() {
+    if (!this.skills || this.skills.length === 0) return '';
+    const extExecutor = this._framework?.pluginManager?.get('extension-executor');
+    if (!extExecutor) return '';
+
+    const lines = ['## 🛠️ 可用技能', ''];
+    let hasContent = false;
+    for (const skillName of this.skills) {
+      // 通过 ext_call 拿 skill 下的所有 tool
+      const tools = extExecutor.getExtensionTools(`skill:${skillName}`) || [];
+      if (tools.length === 0) {
+        lines.push(`### ${skillName}`);
+        lines.push('(该技能尚未注册或无可用命令)');
+        lines.push('');
+        continue;
+      }
+      hasContent = true;
+      lines.push(`### ${skillName}`);
+      lines.push('通过 ext_call 调用，格式：`ext_call({plugin: "skill:' + skillName + '", tool: "<命令>", args: {...}})`');
+      lines.push('');
+      for (const tool of tools) {
+        lines.push(`- **${tool.name}**: ${tool.description || '(无描述)'}`);
+      }
+      lines.push('');
+    }
+    return hasContent ? lines.join('\n') : '';
+  }
+
   _updateAgentSystemPrompt() {
     if (!this._agent) return;
     const systemPrompt = this._getFullSystemPrompt();
@@ -545,27 +606,55 @@ class SubAgentManagerPlugin extends Plugin {
   _parseMarkdownConfig(filePath, defaultName) {
     const content = fs.readFileSync(filePath, 'utf-8')
 
-    const jsonMatch = content.match(/```(?:json)?\s*\n([\s\S]*?)\n\s*```/)
-    if (jsonMatch) {
-      try {
-        return JSON.parse(jsonMatch[1].trim())
-      } catch (err) {
-      }
-    }
-
+    // ★ 修复：优先解析 frontmatter（如果文件以 --- 开头）
+    // 之前的 bug：先匹配第一个 ```json 代码块，导致 body 里的示例 JSON 被当作 config。
+    // 例：news-pipeline-agent.md 里有示例 ```json { "news_list": [...] } ```，
+    //     这个示例被当成 config 解析，结果没有 name 字段，注册失败。
+    let config = null
     const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/)
     if (frontmatterMatch) {
       const frontmatterContent = frontmatterMatch[1]
       const parsed = this._parseYamlLike(frontmatterContent)
       if (parsed && parsed.name) {
-        return { name: parsed.name || defaultName, ...parsed }
+        config = { name: parsed.name || defaultName, ...parsed }
       }
+      // frontmatter 存在但没有 name，回退到 body JSON 块
     }
 
-    const config = { name: defaultName }
-    const yamlMatch = content.match(/^(name|role|description|parentTools|tools):\s*(.+)$/m)
-    if (yamlMatch) {
-      config[yamlMatch[1]] = yamlMatch[2].trim()
+    // 回退：找第一个 JSON 代码块作为 config（仅当无 frontmatter 时）
+    if (!config) {
+      const jsonMatch = content.match(/```(?:json)?\s*\n([\s\S]*?)\n\s*```/)
+      if (jsonMatch) {
+        try {
+          const parsed = JSON.parse(jsonMatch[1].trim())
+          if (parsed && parsed.name) {
+            config = parsed
+          }
+          // JSON 块没有 name 字段 → 视为示例代码，跳过
+        } catch (err) {
+          // 解析失败也跳过
+        }
+      }
+    }
+
+    // 最后回退：尝试匹配文件首行 key: value（不带 m flag，避免匹配 body 中间的内容）
+    if (!config) {
+      config = { name: defaultName }
+      const yamlMatch = content.match(/^(name|role|description|parentTools|tools):\s*(.+)$/)
+      if (yamlMatch) {
+        config[yamlMatch[1]] = yamlMatch[2].trim()
+      }
+    }
+
+    // ★ 新增：提取 markdown body 作为 systemPrompt
+    // 移除 frontmatter 后剩下的内容（去掉首个 # 标题和首尾空白）
+    let body = content
+    if (frontmatterMatch) {
+      body = content.slice(frontmatterMatch[0].length)
+    }
+    body = body.replace(/^\s*#\s+[^\n]*\n+/, '').trim()
+    if (body && body.length > 20) {
+      config.systemPrompt = body
     }
 
     return config

package/plugins/executors/extension/extension-registry.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { z } = require('zod');
+
 /**
  * ExtensionRegistry - 扩展注册表
  * 管理扩展插件及其工具的增删改查
@@ -39,7 +41,7 @@ class ExtensionRegistry {
     const toolEntry = {
       name: toolDef.name,
       description: toolDef.description || '',
-      inputSchema: toolDef.inputSchema,
+      inputSchema: toolDef.inputSchema || ExtensionRegistry._buildSchemaFromOptions(toolDef.options),
       execute: toolDef.execute,
     };
     if (toolDef._options) {
@@ -58,6 +60,75 @@ class ExtensionRegistry {
     return true;
   }
 
+  /**
+   * ★ 关键：legacy `options` 格式（CLI flags 风格）自动转 zod schema
+   * 场景：video-creator 等 skill 还在用 `options: [{flags, description, required, ...}]`
+   *       之前 framework 收不到 inputSchema，参数校验被完全跳过 → LLM 传 args:{} 不会报错
+   *       导致 LLM 反复陷入"我传了 id 但工具说 id undefined"的死循环
+   *
+   * @param {Array} options legacy 格式数组
+   * @returns {Object|null} zod object schema 或 null（无 options 时）
+   */
+  static _buildSchemaFromOptions(options) {
+    if (!Array.isArray(options) || options.length === 0) return null;
+    const shape = {};
+    for (const opt of options) {
+      // 解析 flags 找参数名：'-i, --id <value>' → 'id'
+      const flagName = ExtensionRegistry._parseFlagName(opt.flags);
+      if (!flagName) continue;
+
+      // 构造 zod 字段
+      let zodField;
+      const type = (opt.type || 'string').toLowerCase();
+      const isRequired = opt.required === true;
+
+      if (type === 'number') {
+        zodField = z.number();
+        if (opt.defaultValue !== undefined) zodField = zodField.default(opt.defaultValue);
+        if (!isRequired) zodField = zodField.optional();
+      } else if (type === 'boolean') {
+        zodField = z.boolean();
+        if (opt.defaultValue !== undefined) zodField = zodField.default(opt.defaultValue);
+        if (!isRequired) zodField = zodField.optional();
+      } else {
+        // 字符串
+        zodField = z.string();
+        if (opt.defaultValue !== undefined && opt.defaultValue !== '') {
+          zodField = zodField.default(String(opt.defaultValue));
+        }
+        if (!isRequired) {
+          zodField = zodField.optional();
+        }
+      }
+
+      // 加 description（LLM 看得到）
+      const desc = opt.description || flagName;
+      zodField = zodField.describe(desc + (isRequired ? '（必填）' : ''));
+
+      shape[flagName] = zodField;
+    }
+    if (Object.keys(shape).length === 0) return null;
+    return z.object(shape);
+  }
+
+  /**
+   * 从 flags 字符串提取参数名
+   * 格式：'-i, --id <value>' → 'id'
+   *       '--name <value>' → 'name'
+   *       '-x, --transition [value]' → 'transition'
+   *       '-f, --flag'（无 value）→ 'flag'
+   */
+  static _parseFlagName(flags) {
+    if (typeof flags !== 'string') return null;
+    // 匹配短或长 flag：-x 或 --xxx
+    const match = flags.match(/--([a-zA-Z][\w-]*)/);
+    if (match) return match[1].replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    // 短 flag: -x
+    const short = flags.match(/(?:^|\s)-([a-zA-Z])(?:\s|,|$)/);
+    if (short) return short[1];
+    return null;
+  }
+
   /**
    * 注销扩展工具
    * @returns {boolean} 是否真正移除了扩展

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);