foliko 2.0.12 → 2.0.13

package/.claude/settings.local.json

@@ -239,7 +239,9 @@
       "Bash(npm start *)",
       "Bash(xxd)",
       "Bash(python fix_ext2.py)",
-      "Bash(npx vitest *)"
+      "Bash(npx vitest *)",
+      "Bash(ls node_modules | wc -l && ls -d node_modules/@* 2>/dev/null | head -5)",
+      "Bash(node -e \"console.log\\(require.resolve\\('croner'\\)\\)\")"
     ]
   }
 }

package/CLAUDE.md

@@ -147,7 +147,7 @@ Provider selection via `config.provider` and AI settings in `.foliko/ai.json`.
 5. **Per-Session Message Storage**: `AgentChatHandler` uses `_sessionMessageStores` Map for Per-Session 消息隔离
 6. **Unified Extension Call**: 扩展工具（普通扩展 / `mcp:<server>` / `skill:<name>`）通过 `ext_skill` + `ext_call` 统一调度
    - `ext_skill({ plugin })` 查询参数 → `ext_call({ plugin, tool, args })` 调用
-   - 普通扩展/MCP/Python：`args` 是结构化对象；Skill 命令：`args: { command: "..." }` 命令行字符串
+   - 扩展调用：`args` 是结构化对象，参数名对应工具定义的字段（camelCase）
 
 ### Built-in Plugins
 

package/README.md

@@ -391,9 +391,9 @@ allowed-tools: tool1,tool2
 > **统一扩展调用模式**：
 > - 普通扩展：`ext_call({ plugin: "<name>", tool: "<tool>", args: {...} })`
 > - MCP 服务器：`ext_call({ plugin: "mcp:<servername>", tool: "<tool>", args: {...} })`
-> - Skill 命令：`ext_call({ plugin: "skill:<skillname>", tool: "<command>", args: { command: "..." } })`
+> - Skill 命令：`ext_call({ plugin: "skill:<skillname>", tool: "<command>", args: { name: "...", lang: "..." } })`
 > - 调用前先 `ext_skill({ plugin: "<name>" })` 查看参数结构
-> - 普通扩展/MCP/Python：`args` 是结构化对象；Skill 命令：`args: { command: "..." }`
+> - 扩展调用：`args` 是结构化对象，参数名对应工具定义的字段（camelCase）
 
 ### 子 Agent 管理工具
 

package/docs/extensions.md

@@ -45,8 +45,7 @@ ext_call({
 
 | 扩展类型 | args 格式 |
 |---|---|
-| 普通扩展 / MCP / Python | `args: {...}` 结构化对象 |
-| Skill 命令 | `args: { command: "..." }` 命令行字符串 |
+| 普通扩展 / MCP / Python / Skill | `args: {...}` 结构化对象，参数名对应工具定义的字段（camelCase） |
 
 ## 3. MCP 服务器自动注册
 
@@ -118,11 +117,11 @@ module.exports = {
 ext_call({
   plugin: 'skill:my-skill',
   tool: 'greet',
-  args: { command: "-n Claude -l en -s" }
+  args: { name: "Claude", lang: "en", shout: true }
 })
 ```
 
-**args 传 `command` 字符串**，commander.js 解析后 handler 收到 `{ name: 'Claude', lang: 'en', shout: true }`。
+**args 直接传结构化对象**，handler 收到 `{ name: 'Claude', lang: 'en', shout: true }`。
 
 ## 5. Plugin 基类：`this.skill` accessor
 

package/docs/migration.md

@@ -84,15 +84,15 @@ Skill 命令通过 `skill:<name>` 命名空间调用：
 ext_call({
   plugin: "skill:my-skill",  // skill:<name>
   tool: "cmd",               // 命令名（不是 <skill>:<cmd>）
-  args: { command: "-n x -v" }
+  args: { name: "x", verbose: true }
 })
 ```
 
 **要点**：
 - 每个 skill 是独立扩展 `skill:<name>`
 - 命令是该扩展下的 tool
-- `args: { command: "..." }` 传命令行字符串
-- Commander.js 解析后传给 handler
+- `args` 直接传结构化对象，参数名对应 `options` 中定义的字段（camelCase）
+- 不再需要命令行字符串解析
 
 #### 3. ext_skill 返回内容
 

package/docs/usage.md

@@ -198,17 +198,17 @@ module.exports = {
 // 1. 查询参数
 ext_skill({ plugin: "skill:<skillname>" })
 
-// 2. 调用（传命令行字符串）
+// 2. 调用（传结构化参数）
 ext_call({
   plugin: "skill:<skillname>",
   tool: "greet",
-  args: { command: "-n Claude -l en --shout" },
+  args: { name: "Claude", lang: "en", shout: true },
 })
 ```
 
 #### 参数传递
 
-Skill 命令参数通过 `args: { command: "..." }` 传递命令行字符串，由 Commander.js 解析后传给 handler：
+Skill 命令参数直接通过 `args` 对象传递，无需解析命令行字符串：
 
 | flags | 解析后 args 字段 |
 |---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foliko",
-  "version": "2.0.12",
+  "version": "2.0.13",
   "description": "简约的插件化 Agent 框架",
   "main": "src/index.js",
   "type": "commonjs",

package/plugins/core/scheduler/index.js

@@ -340,6 +340,7 @@ class SchedulerPlugin extends Plugin {
       }),
     });
 
+    log.info(` [start] Scheduler 插件启动，当前时间: ${new Date().toISOString()} timezone=${this.config.timezone}`);
     this._loadPersistedTasks();
     return this;
   }
@@ -432,7 +433,11 @@ class SchedulerPlugin extends Plugin {
           // once：startAt 限定未来触发
           task.scheduleHandle = new Cron(runAt, this._cronOptions(task), () => this._onFire(task));
         }
+        // 打印下次执行时间便于调试
+        const nextRun = task.scheduleHandle.nextRun();
+        log.info(` [_createTask] 创建任务成功: ${task.name} cron="${cron || ''}" 下次执行: ${nextRun ? nextRun.toISOString() : 'once-立即?'} timezone=${task.timezone}`);
       } catch (err) {
+        log.error(` [_createTask] 创建调度失败: ${err.message}`);
         return { success: false, error: `调度创建失败: ${err.message}` };
       }
 
@@ -465,30 +470,39 @@ class SchedulerPlugin extends Plugin {
   }
 
   _cronOptions(task) {
-    return {
+    const opts = {
       timezone: this.config.timezone,
       protect: true, // 防重叠：上一次还没跑完，跳过本次
       catch: true,   // catch-up：进程恢复后补触发错过的触发
       name: `scheduler:${task.id}`,
       unref: true,   // 不阻止进程退出
     };
+    log.debug(` [_cronOptions] task=${task.name} cron=${task.cronExpression || 'once'} timezone=${opts.timezone}`);
+    return opts;
   }
 
   // ============================================================
   // 触发回调
   // ============================================================
   async _onFire(task) {
-    if (!task.enabled) return;
+    log.info(` [_onFire] >>> 任务触发: ${task.name} (id=${task.id}) cron=${task.cronExpression || 'once'} timezone=${task.timezone}`);
+
+    if (!task.enabled) {
+      log.warn(` [_onFire] 任务 ${task.name} 已禁用，跳过`);
+      return;
+    }
     if (task.running) {
       // 理论上 protect:true 已经处理过；这里再保险一次
-      log.warn(` 任务 ${task.name} 仍在执行中，跳过本次触发`);
+      log.warn(` [_onFire] 任务 ${task.name} 仍在执行中，跳过本次触发`);
       return;
     }
     task.running = true;
     task.lastRun = new Date();
     task.runCount++;
+    log.info(` [_onFire] 开始执行任务: ${task.name} (第${task.runCount}次)`);
     try {
       await this._executeTask(task);
+      log.info(` [_onFire] <<< 任务执行完成: ${task.name}`);
     } finally {
       task.running = false;
     }
@@ -890,12 +904,20 @@ class SchedulerPlugin extends Plugin {
   // ============================================================
   _loadPersistedTasks() {
     const savedTasks = this._taskStore.loadTasks();
-    if (!savedTasks || savedTasks.length === 0) return;
+    log.info(` [_loadPersistedTasks] 开始加载任务，当前时间: ${new Date().toISOString()}`);
+    if (!savedTasks || savedTasks.length === 0) {
+      log.info(` [_loadPersistedTasks] 没有已保存的任务`);
+      return;
+    }
+    log.info(` [_loadPersistedTasks] 从磁盘加载了 ${savedTasks.length} 个任务`);
     const now = Date.now();
 
     for (const saved of savedTasks) {
       // 已完成的 once 任务不再恢复
-      if (saved.type === 'once' && (saved.runCount || 0) > 0) continue;
+      if (saved.type === 'once' && (saved.runCount || 0) > 0) {
+        log.debug(` [_loadPersistedTasks] 跳过已完成的 once 任务: ${saved.name}`);
+        continue;
+      }
 
       const task = {
         ...saved,
@@ -910,19 +932,25 @@ class SchedulerPlugin extends Plugin {
       try {
         if (task.type === 'cron' && task.enabled && task.cronExpression) {
           task.scheduleHandle = new Cron(task.cronExpression, this._cronOptions(task), () => this._onFire(task));
+          const nextRun = task.scheduleHandle.nextRun();
+          log.info(` [_loadPersistedTasks] 恢复 cron 任务: ${task.name} cron="${task.cronExpression}" 下次执行: ${nextRun ? nextRun.toISOString() : 'N/A'}`);
           this._tasks.set(task.id, task);
         } else if (task.type === 'once' && task.enabled) {
-          if (!task.runAt) continue;
+          if (!task.runAt) {
+            log.warn(` [_loadPersistedTasks] 跳过没有 runAt 的 once 任务: ${task.name}`);
+            continue;
+          }
           const fireAt = task.runAt.getTime();
           if (fireAt <= now) {
             // 已过期：超过 grace period 就丢弃
             if (now - fireAt > ONCE_EXPIRY_GRACE_MS) {
-              log.warn(` 丢弃过期任务 ${task.name}（已过期 ${Math.round((now - fireAt) / 1000)}s，超出 24h 容忍期）`);
+              log.warn(` [_loadPersistedTasks] 丢弃过期任务 ${task.name}（已过期 ${Math.round((now - fireAt) / 1000)}s，超出 24h 容忍期）`);
               continue;
             }
             // B4/B5 修复：catchup 也用 croner 调度过去时间，croner 会立即触发；
             // stop() 能真正取消，update 走 stop()+new Cron() 不会双触发
             // protect:false 是因为"补触发"不应被 startup 期间的并发阻塞
+            log.info(` [_loadPersistedTasks] 恢复过期的 once 任务（立即触发）: ${task.name} 原定执行: ${task.runAt.toISOString()}`);
             task.scheduleHandle = new Cron(task.runAt, {
               ...this._cronOptions(task),
               protect: false,
@@ -930,15 +958,18 @@ class SchedulerPlugin extends Plugin {
             this._tasks.set(task.id, task);
           } else {
             // 未来触发
+            log.info(` [_loadPersistedTasks] 恢复 future once 任务: ${task.name} 执行时间: ${task.runAt.toISOString()}`);
             task.scheduleHandle = new Cron(task.runAt, this._cronOptions(task), () => this._onFire(task));
             this._tasks.set(task.id, task);
           }
+        } else {
+          log.debug(` [_loadPersistedTasks] 跳过任务: ${task.name} type=${task.type} enabled=${task.enabled}`);
         }
       } catch (err) {
-        log.error(` 恢复任务失败: ${task.name}`, err.message);
+        log.error(` [_loadPersistedTasks] 恢复任务失败: ${task.name}`, err.message);
       }
     }
-    log.info(` 已恢复 ${this._tasks.size} 个定时任务`);
+    log.info(` [_loadPersistedTasks] 完成，共恢复 ${this._tasks.size} 个定时任务`);
   }
 
   // ============================================================

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

@@ -263,6 +263,59 @@ function buildSchemaFromType(type, desc, defaultValue) {
   return schema;
 }
 
+/**
+ * 从 options 构建 JSON Schema（供 AI SDK 直接使用，不走 Zod）
+ * 用于替换旧的 CLI 字符串模式，让 LLM 能用结构化参数调用
+ *
+ * type 可选值：'string' | 'number' | 'boolean' | 'array' | 'object'
+ * （对应 JS 原生类型 String, Boolean, Number, Array, Object）
+ */
+function buildInputSchemaFromOptions(options) {
+  if (!Array.isArray(options) || options.length === 0) {
+    return { type: 'object', properties: {}, required: [] };
+  }
+
+  const properties = {};
+  const required = [];
+
+  for (const opt of options) {
+    const name = extractOptionName(opt.flags);
+    if (!name) continue;
+
+    const hasValue = optionHasValue(opt.flags);
+    const isRequired = opt.required === true && hasValue;
+    const desc = opt.description || '';
+    const defaultVal = opt.defaultValue;
+
+    let jsonType = 'string';
+    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';
+    } else {
+      jsonType = hasValue ? 'string' : 'boolean';
+    }
+
+    const prop = { type: jsonType, description: desc };
+    if (defaultVal !== undefined && defaultVal !== null) {
+      prop.default = defaultVal;
+    }
+    properties[name] = prop;
+    if (isRequired) required.push(name);
+  }
+
+  return { type: 'object', properties, required };
+}
+
 /**
  * 生成等效的 JSON schema（用于 _rawSchema，让 ext_skill 渲染更清晰）
  */
@@ -329,6 +382,50 @@ function buildExampleFromOptions(options) {
   return parts.join(' ');
 }
 
+/**
+ * 解析命令行参数字符串为结构化对象（供 messaging 插件 backward compatible 使用）
+ * 支持：--name value, -n value, --flag, -f
+ * @param {string} str - 参数字符串
+ * @param {Array} options - 选项定义数组
+ * @returns {Object} 解析后的参数对象
+ */
+function parseCommandArgs(str, options) {
+  if (typeof str !== 'string' || !str.trim()) return {};
+  const result = {};
+  const tokens = parseShellArgs(str);
+  let i = 0;
+  while (i < tokens.length) {
+    const token = tokens[i];
+    const optMatch = token.match(/^(-[a-zA-Z]|-{1,2}[a-zA-Z][a-zA-Z0-9-]*)$/);
+    if (optMatch) {
+      const optKey = optMatch[1];
+      const opt = options.find(o => {
+        const flags = o.flags || '';
+        return flags.includes(optKey) || flags.includes(optKey.replace(/^--?/, '--'));
+      });
+      if (opt) {
+        const name = extractOptionName(opt.flags);
+        const hasValue = optionHasValue(opt.flags);
+        if (hasValue && i + 1 < tokens.length) {
+          const next = tokens[i + 1];
+          if (!next.match(/^-/)) {
+            result[name] = next;
+            i += 2;
+            continue;
+          }
+        } else if (!hasValue) {
+          result[name] = true;
+          i += 1;
+          continue;
+        }
+      }
+    }
+    i += 1;
+  }
+  if (i < tokens.length) result._ = tokens.slice(i);
+  return result;
+}
+
 /**
  * Skill 类
  */
@@ -356,6 +453,17 @@ class Skill {
     return [];
   }
 
+  /**
+   * 简单命令行字符串解析器（backward compatible，供 messaging 插件使用）
+   * 支持：--name value, -n value, --flag, -f, positional args
+   * @param {string} str - 参数字符串
+   * @param {Array} options - 选项定义数组
+   * @returns {Object} 解析后的参数对象
+   */
+  _parseCommandString(str, options) {
+    return parseCommandArgs(str, options);
+  }
+
   /**
    * 注册 skill 的命令到 extension 系统
    * 异步版本：用动态 import() 替代 require()，支持 ESM 包
@@ -415,87 +523,13 @@ class Skill {
         // 命令名格式: {skill_name}:{cmd_name}
         const fullName = `${skillName}:${cmd.name}`;
 
-        // 获取参数解析器（优先使用 argumentParser，否则用 options 构建）
-        let argumentParser = cmd.argumentParser;
-        if (!argumentParser && Array.isArray(cmd.options) && cmd.options.length > 0) {
-          argumentParser = (rawArgs) => {
-            try {
-              const program = new Command();
-              program.exitOverride(); // 不自动退出
-              program.configureOutput({ writeErr: () => {} }); // 隐藏错误输出
-              for (const opt of cmd.options) {
-                program.option(opt.flags, opt.description, opt.defaultValue);
-              }
-              program.arguments('[args...]');
-              program.parse(['node', 'cmd', ...parseShellArgs(rawArgs)]);
-              return { ...program.opts(), args: program.args };
-            } catch (err) {
-              log.warn(`[SkillManager] Command parse error: ${err.message}`);
-              // Commander 解析失败时，用简单方式从 rawArgs 提取选项值
-              const result = {};
-              const tokens = parseShellArgs(rawArgs);
-              let i = 0;
-              while (i < tokens.length) {
-                const token = tokens[i];
-                // 匹配选项（-x 或 --xxx）
-                const optMatch = token.match(/^(-[a-zA-Z]|-{1,2}[a-zA-Z][a-zA-Z0-9-]*)$/);
-                if (optMatch) {
-                  const optKey = optMatch[1];
-                  // 找对应的 option
-                  const opt = cmd.options.find(o => {
-                    const flags = o.flags || '';
-                    return flags.includes(optKey) || flags.includes(optKey.replace(/^--?/, '--'));
-                  });
-                  if (opt) {
-                    const name = extractOptionName(opt.flags);
-                    // 判断是否有值（下一个 token 不是选项）
-                    const hasValue = /<[^>]+>/.test(opt.flags);
-                    if (hasValue && i + 1 < tokens.length) {
-                      const next = tokens[i + 1];
-                      if (!next.match(/^-/)) {
-                        result[name] = next;
-                        i += 2;
-                        continue;
-                      } else {
-                        // 下个 token 是另一个选项，但当前选项需要值，用默认值
-                        result[name] = opt.defaultValue ?? undefined;
-                        i += 1;
-                        continue;
-                      }
-                    } else if (!hasValue) {
-                      result[name] = true;
-                      i += 1;
-                      continue;
-                    } else if (hasValue && i + 1 >= tokens.length) {
-                      // 当前选项需要值但没有更多 token，用默认值
-                      result[name] = opt.defaultValue ?? undefined;
-                      i += 1;
-                      continue;
-                    }
-                  }
-                }
-                i += 1;
-              }
-              // 剩余的 token 当 args
-              result.args = tokens.slice(i);
-              return result;
-            }
-          };
-        }
-
-        // 直接使用 command 字符串的 schema，describe 说明命令行格式
-        const exampleArgs = cmd.options && cmd.options.length > 0
-          ? buildExampleFromOptions(cmd.options)
-          : '';
+        // 新模式：结构化参数 schema，让 LLM 直接用 JSON 对象调用
         const toolDef = {
           name: cmd.name,
           description: cmd.description || 'Skill command',
-          inputSchema: z.object({
-            command: z.string().optional().describe(exampleArgs || '命令行字符串，如：-n value1 -v'),
-          }),
+          // 直接用 JSON Schema，不走 Zod（让 LLM 看到清晰的结构化参数）
+          inputSchema: buildInputSchemaFromOptions(cmd.options),
           _options: cmd.options || null,
-          // 把原始 options 数组也保存下来，便于 ext_skill 显示
-          _rawSchema: buildRawJsonSchema(cmd.options),
           execute: async (toolArgs, framework) => {
             const ctx = {
               sessionId: framework?._currentSessionId || 'unknown',
@@ -503,13 +537,13 @@ class Skill {
               framework: framework,
               cwd: framework?.getCwd?.() ?? process.cwd(),
             };
-            // 直接使用 command 字符串
-            const commandString = toolArgs?.command || '';
-            let parsedArgs = commandString;
-            if (typeof argumentParser === 'function') {
-              parsedArgs = argumentParser(commandString);
+            // backward compatible：如果 args.command 是字符串（messaging 插件传来），
+            // 用 options 做简单解析；否则直接传递结构化参数（AI SDK / ext_call 传来）
+            let args = toolArgs || {};
+            if (typeof args.command === 'string' && Array.isArray(cmd.options) && cmd.options.length > 0) {
+              args = parseCommandArgs(args.command, cmd.options);
             }
-            return await handler(parsedArgs, ctx);
+            return await handler(args, ctx);
           },
         };
 
@@ -1283,72 +1317,12 @@ class SkillManagerPlugin extends Plugin {
 
         const fullName = `${name}:${cmd.name}`;
 
-        // 获取参数解析器
-        let argumentParser = cmd.argumentParser;
-        if (!argumentParser && Array.isArray(cmd.options) && cmd.options.length > 0) {
-          argumentParser = (rawArgs) => {
-            try {
-              const program = new Command();
-              program.exitOverride();
-              program.configureOutput({ writeErr: () => {} });
-              for (const opt of cmd.options) {
-                program.option(opt.flags, opt.description, opt.defaultValue);
-              }
-              program.arguments('[args...]');
-              program.parse(['node', 'cmd', ...parseShellArgs(rawArgs)]);
-              return { ...program.opts(), args: program.args };
-            } catch (err) {
-              log.warn(`[SkillManager] Command parse error: ${err.message}`);
-              // Commander 解析失败时，用简单方式从 rawArgs 提取选项值
-              const result = {};
-              const tokens = parseShellArgs(rawArgs);
-              let i = 0;
-              while (i < tokens.length) {
-                const token = tokens[i];
-                const optMatch = token.match(/^(-[a-zA-Z]|-{1,2}[a-zA-Z][a-zA-Z0-9-]*)$/);
-                if (optMatch) {
-                  const optKey = optMatch[1];
-                  const opt = cmd.options.find(o => {
-                    const flags = o.flags || '';
-                    return flags.includes(optKey) || flags.includes(optKey.replace(/^--?/, '--'));
-                  });
-                  if (opt) {
-                    const name = extractOptionName(opt.flags);
-                    const hasValue = /<[^>]+>/.test(opt.flags);
-                    if (hasValue && i + 1 < tokens.length) {
-                      const next = tokens[i + 1];
-                      if (!next.match(/^-/)) {
-                        result[name] = next;
-                        i += 2;
-                        continue;
-                      }
-                    } else if (!hasValue) {
-                      result[name] = true;
-                      i += 1;
-                      continue;
-                    }
-                  }
-                }
-                i += 1;
-              }
-              result.args = tokens.slice(i);
-              return result;
-            }
-          };
-        }
-
-        // 转为 Zod schema（统一风格）
-        const exampleArgs2 = cmd.options && cmd.options.length > 0
-          ? buildExampleFromOptions(cmd.options)
-          : '';
+        // 新模式：结构化参数 schema
         const toolDef = {
-          name: cmd.name,  // 只用命令名
+          name: cmd.name,
           description: cmd.description || 'Skill command',
-          inputSchema: z.object({
-            command: z.string().optional().describe(exampleArgs2 || '命令行字符串'),
-          }),
+          inputSchema: buildInputSchemaFromOptions(cmd.options),
           _options: cmd.options || null,
-          _rawSchema: buildRawJsonSchema(cmd.options),
           execute: async (toolArgs, framework) => {
             const ctx = {
               sessionId: framework?._currentSessionId || 'unknown',
@@ -1356,12 +1330,12 @@ class SkillManagerPlugin extends Plugin {
               framework: framework,
               cwd: framework?.getCwd?.() ?? process.cwd(),
             };
-            const commandString = toolArgs?.command || '';
-            let parsedArgs = commandString;
-            if (typeof argumentParser === 'function') {
-              parsedArgs = argumentParser(commandString);
+            // backward compatible：如果 args.command 是字符串，解析为结构化对象
+            let args = toolArgs || {};
+            if (typeof args.command === 'string' && Array.isArray(cmd.options) && cmd.options.length > 0) {
+              args = parseCommandArgs(args.command, cmd.options);
             }
-            return await handler(parsedArgs, ctx);
+            return await handler(args, ctx);
           },
         };
 

package/plugins/executors/extension/prompt-builder.js

@@ -345,14 +345,41 @@ class ExtensionPromptBuilder {
   _formatSchema(schema, rawSchema) {
     // 优先用 zodSchemaToMarkdown（MCP/普通扩展都走这条路径）
     try {
-      const md = zodSchemaToMarkdown(schema);
-      if (md && !/Zod\w+/.test(md)) return md;
+      // Zod 实例有 _def.typeName，纯 JSON Schema 没有
+      if (schema && schema._def && schema._def.typeName) {
+        const md = zodSchemaToMarkdown(schema);
+        if (md && !/Zod\w+/.test(md)) return md;
+      }
     } catch { /* fall through */ }
     try {
-      return zodSchemaToTable(schema) || '无';
-    } catch {
-      return '无';
+      const table = zodSchemaToTable(schema);
+      if (table) return table;
+    } catch { /* fall through */ }
+
+    // 兜底：纯 JSON Schema（{type,properties,required}）
+    if (schema && schema.properties) {
+      return this._jsonSchemaToMarkdown(schema);
+    }
+
+    return '无';
+  }
+
+  /**
+   * 将纯 JSON Schema 对象格式化为 Markdown 表格
+   */
+  _jsonSchemaToMarkdown(schema) {
+    const { properties = {}, required = [] } = schema;
+    if (Object.keys(properties).length === 0) return '无';
+
+    const lines = ['| 参数 | 类型 | 必填 | 默认 | 描述 |', '|------|------|------|------|------|'];
+    for (const [name, prop] of Object.entries(properties)) {
+      const type = prop.type || 'any';
+      const desc = prop.description || '';
+      const isRequired = required.includes(name);
+      const def = prop.default !== undefined ? String(prop.default) : '';
+      lines.push(`| \`${name}\` | ${type} | ${isRequired ? '✅' : '❌'} | ${def} | ${desc} |`);
     }
+    return lines.join('\n');
   }
 }
 

package/plugins/executors/shell/index.js

@@ -45,6 +45,34 @@ class ShellExecutorPlugin extends Plugin {
       execute: async (args) => {
         const cwd = args.cwd || this.config.workingDir
         const timeout = args.timeout || this.config.timeout
+        const command = args.command || ''
+
+        // 检测 /skillname:cmdname args 格式，转到 skill executor
+        if (command.startsWith('/')) {
+          const colonIdx = command.indexOf(':');
+          if (colonIdx > 1) {
+            const skillCmd = command.slice(1); // 去掉前导 /
+            const spaceIdx = command.indexOf(' ');
+            const cmdPart = spaceIdx > 0 ? command.slice(1, spaceIdx) : command.slice(1);
+            const cmdArgs = spaceIdx > 0 ? command.slice(spaceIdx + 1).trim() : '';
+
+            const [skillName, ...rest] = cmdPart.split(':');
+            const cmdName = rest.join(':');
+            if (skillName && cmdName) {
+              const extExecutor = this._framework?.pluginManager?.get('extension-executor');
+              if (extExecutor && typeof extExecutor.executeSkillCommand === 'function') {
+                try {
+                  const result = await extExecutor.executeSkillCommand(`${skillName}:${cmdName}`, cmdArgs);
+                  if (result) {
+                    return { success: true, stdout: result.data || result, stderr: '', command, skillCommand: true };
+                  }
+                } catch (err) {
+                  return { success: false, error: err.message, command, skillCommand: true };
+                }
+              }
+            }
+          }
+        }
 
         return new Promise((resolve) => {
           const startTime = Date.now()

package/skills/skill-guide/SKILL.md

@@ -100,24 +100,24 @@ frontmatter 之后是技能的正文内容，支持 Markdown 格式，包含：
 打招呼命令。
 
 **参数：**
-- `args`（可选）：名字，如 `/my-skill:greet Alice`
+- `name`（可选）：名字，默认 "World"
+- `lang`（可选）：语言，如 "en"，默认 "zh"
 
 **示例：**
 - `/my-skill:greet` → "Hello World"
-- `/my-skill:greet Alice` → "Hello Alice"
+- `/my-skill:greet {"name":"Alice"}` → "Hello Alice"
 
 ### /my-skill:split
 
 切割会话命令。
 
 **参数：**
-- `-t, --tokens <value>`：保留 token 数（默认 4000）
-- `-k, --keep-recent <value>`：保留最近 token（默认 1000）
-- `[args...]`：位置参数
+- `tokens`（可选）：保留 token 数，默认 4000
+- `keepRecent`（可选）：保留最近 token，默认 1000
 
 **示例：**
 - `/my-skill:split` → 使用默认参数
-- `/my-skill:split -t 8000 extra` → tokens=8000，extra 作为位置参数
+- `/my-skill:split {"tokens":8000}` → tokens=8000
 ```
 
 ### index.js 格式
@@ -127,23 +127,26 @@ module.exports = [
   {
     name: 'greet',           // 命令名
     description: '打招呼',   // 命令描述
+    options: [
+      { flags: '-n, --name <value>', description: '名字', defaultValue: 'World' },
+      { flags: '-l, --lang <value>', description: '语言', defaultValue: 'zh' }
+    ],
     execute: async (args, ctx) => {
-      // args: 传入的参数（字符串）
+      // args: 解析后的结构化对象，如 { name: "Alice", lang: "en" }
       // ctx: 上下文对象 { sessionId, agent, framework }
-      return 'Hello ' + (args || 'World');
+      return `Hello ${args.name || 'World'}`;
     }
   },
   {
     name: 'split',
     description: '切割会话',
-    // 简洁方式：定义选项数组，自动使用 Commander.js 解析
     options: [
-      { flags: '-t, --tokens <value>', description: '保留 token 数', defaultValue: '4000' },
-      { flags: '-k, --keep-recent <value>', description: '保留最近 token', defaultValue: '1000' }
+      { flags: '-t, --tokens <value>', type: 'number', description: '保留 token 数', defaultValue: 4000 },
+      { flags: '-k, --keep-recent <value>', type: 'number', description: '保留最近 token', defaultValue: 1000 }
     ],
-    execute: async (parsedArgs, ctx) => {
-      // parsedArgs: { tokens: "4000", keepRecent: "1000", args: [...] }
-      return `Split: tokens=${parsedArgs.tokens}`;
+    execute: async (args, ctx) => {
+      // args: { tokens: 4000, keepRecent: 1000 }
+      return `Split: tokens=${args.tokens}`;
     }
   },
   {
@@ -156,11 +159,12 @@ module.exports = [
 ];
 ```
 
-**参数解析说明：**
+**参数类型说明：**
 
-- 不提供 `options` 时，`args` 是原始参数字符串
-- 提供 `options` 数组时，自动使用 Commander.js 解析，`execute` 收到解析后的对象
-- 对象格式：`{ tokens, keepRecent, args: [...] }`
+- `options[].type`：可选，声明参数类型 (`String` | `Number` | `Boolean` | `Array` | `Object`)，帮助 LLM 理解参数格式
+- 不提供 `options` 时，`args` 是空对象 `{}`
+- 提供 `options` 数组时，`execute` 收到解析后的结构化对象
+- 对象格式：`{ name, lang, tokens, keepRecent, ... }`（camelCase，匹配 flag 名称）
 
 ### 命令调用方式
 
@@ -182,11 +186,11 @@ module.exports = [
 // 1. 先查询命令参数
 ext_skill({ plugin: "skill:<技能名>" })
 
-// 2. 用命令行字符串调用
+// 2. 用结构化参数调用
 ext_call({
   plugin: "skill:<技能名>",
   tool: "<commandname>",
-  args: { command: "-n Alice -l en" }
+  args: { name: "Alice", lang: "en" }
 });
 ```
 
@@ -196,30 +200,30 @@ ext_call({
 |------|------|------|
 | `plugin` | string | 固定为 `"skill:<技能名>"`，如 `skill:test-skill` |
 | `tool` | string | 命令名（不带技能前缀），如 `greet` |
-| `args` | object | 固定为 `{ command: "命令行字符串" }` |
+| `args` | object | 结构化参数对象，字段名对应 `options` 中的参数名（camelCase） |
 
 **示例：**
 
 ```javascript
-// 调用 test-skill 的 greet 命令
+// 调用 test-skill 的 greet 命令（带参数）
 ext_call({
   plugin: "skill:test-skill",
   tool: "greet",
-  args: { command: "-n Alice" }
+  args: { name: "Alice", lang: "en" }
 });
 
-// 调用 test-skill 的 greet 命令，带可选 lang
+// 调用 test-skill 的 greet 命令（使用默认参数）
 ext_call({
   plugin: "skill:test-skill",
   tool: "greet",
-  args: { command: "-n Alice -l en" }
+  args: {}
 });
 
-// 调用 test-skill 的 echo 命令
+// 调用 test-skill 的 split 命令
 ext_call({
   plugin: "skill:test-skill",
-  tool: "echo",
-  args: { command: "Hello World" }
+  tool: "split",
+  args: { tokens: 8000 }
 });
 ```
 
@@ -234,8 +238,23 @@ ext_call({
 
 ```javascript
 module.exports = [
-  { name: 'greet', description: '打招呼', execute: async (args) => 'Hello ' + (args || 'World') },
-  { name: 'echo', description: '回声命令', execute: async (args) => 'Echo: ' + args }
+  {
+    name: 'greet',
+    description: '打招呼',
+    options: [
+      { flags: '-n, --name <value>', description: '名字', defaultValue: 'World' },
+      { flags: '-l, --lang <value>', description: '语言', defaultValue: 'zh' }
+    ],
+    execute: async (args) => `Hello ${args.name || 'World'}`
+  },
+  {
+    name: 'echo',
+    description: '回声命令',
+    options: [
+      { flags: '-t, --text <value>', description: '回显文本', required: true }
+    ],
+    execute: async (args) => 'Echo: ' + args.text
+  }
 ];
 ```
 
@@ -249,21 +268,22 @@ module.exports = [
 打招呼命令。
 
 **参数：**
-- `args`（可选）：名字
+- `name`（可选）：名字，默认 "World"
+- `lang`（可选）：语言，默认 "zh"
 
 **示例：**
 - `/test-skill:greet` → "Hello World"
-- `/test-skill:greet Alice` → "Hello Alice"
+- `/test-skill:greet {"name":"Alice"}` → "Hello Alice"
 
 ### /test-skill:echo
 
 回声命令，将输入原样返回。
 
 **参数：**
-- `args`：要回显的文本
+- `text`（必填）：要回显的文本
 
 **示例：**
-- `/test-skill:echo Hello` → "Echo: Hello"
+- `/test-skill:echo {"text":"Hello"}` → "Echo: Hello"
 ```
 
 ### 自动注册
@@ -338,23 +358,26 @@ module.exports = [
   {
     name: 'greet',           // 命令名
     description: '打招呼',   // 命令描述
+    options: [
+      { flags: '-n, --name <value>', description: '名字', defaultValue: 'World' },
+      { flags: '-l, --lang <value>', description: '语言', defaultValue: 'zh' }
+    ],
     execute: async (args, ctx) => {
-      // args: 传入的参数（字符串）
+      // args: 解析后的结构化对象，如 { name: "Alice", lang: "en" }
       // ctx: 上下文对象 { sessionId, agent, framework }
-      return 'Hello ' + (args || 'World');
+      return `Hello ${args.name || 'World'}`;
     }
   },
   {
     name: 'split',
     description: '切割会话',
-    // 简洁方式：定义选项数组，自动使用 Commander.js 解析
     options: [
-      { flags: '-t, --tokens <value>', description: '保留 token 数', defaultValue: '4000' },
-      { flags: '-k, --keep-recent <value>', description: '保留最近 token', defaultValue: '1000' }
+      { flags: '-t, --tokens <value>', type: 'number', description: '保留 token 数', defaultValue: 4000 },
+      { flags: '-k, --keep-recent <value>', type: 'number', description: '保留最近 token', defaultValue: 1000 }
     ],
-    execute: async (parsedArgs, ctx) => {
-      // parsedArgs: { tokens: "4000", keepRecent: "1000", args: [...] }
-      return `Split: tokens=${parsedArgs.tokens}`;
+    execute: async (args, ctx) => {
+      // args: { tokens: 4000, keepRecent: 1000 }
+      return `Split: tokens=${args.tokens}`;
     }
   },
   {
@@ -367,11 +390,12 @@ module.exports = [
 ];
 ```
 
-**参数解析说明：**
+**参数类型说明：**
 
-- 不提供 `options` 时，`args` 是原始参数字符串
-- 提供 `options` 数组时，自动使用 Commander.js 解析，`execute` 收到解析后的对象
-- 对象格式：`{ tokens, keepRecent, args: [...] }`
+- `options[].type`：可选，声明参数类型 (`String` | `Number` | `Boolean` | `Array` | `Object`)，帮助 LLM 理解参数格式
+- 不提供 `options` 时，`args` 是空对象 `{}`
+- 提供 `options` 数组时，`execute` 收到解析后的结构化对象
+- 对象格式：`{ name, lang, tokens, keepRecent, ... }`（camelCase，匹配 flag 名称）
 
 ### 命令调用方式
 
@@ -393,11 +417,11 @@ module.exports = [
 // 1. 先查询命令参数
 ext_skill({ plugin: "skill:<技能名>" })
 
-// 2. 用命令行字符串调用
+// 2. 用结构化参数调用
 ext_call({
   plugin: "skill:<技能名>",
   tool: "<commandname>",
-  args: { command: "-n Alice -l en" }
+  args: { name: "Alice", lang: "en" }
 });
 ```
 
@@ -407,30 +431,30 @@ ext_call({
 |------|------|------|
 | `plugin` | string | 固定为 `"skill:<技能名>"`，如 `skill:test-skill` |
 | `tool` | string | 命令名（不带技能前缀），如 `greet` |
-| `args` | object | 固定为 `{ command: "命令行字符串" }` |
+| `args` | object | 结构化参数对象，字段名对应 `options` 中的参数名（camelCase） |
 
 **示例：**
 
 ```javascript
-// 调用 test-skill 的 greet 命令
+// 调用 test-skill 的 greet 命令（带参数）
 ext_call({
   plugin: "skill:test-skill",
   tool: "greet",
-  args: { command: "-n Alice" }
+  args: { name: "Alice", lang: "en" }
 });
 
-// 调用 test-skill 的 greet 命令，带可选 lang
+// 调用 test-skill 的 greet 命令（使用默认参数）
 ext_call({
   plugin: "skill:test-skill",
   tool: "greet",
-  args: { command: "-n Alice -l en" }
+  args: {}
 });
 
-// 调用 test-skill 的 echo 命令
+// 调用 test-skill 的 split 命令
 ext_call({
   plugin: "skill:test-skill",
-  tool: "echo",
-  args: { command: "Hello World" }
+  tool: "split",
+  args: { tokens: 8000 }
 });
 ```
 
@@ -445,16 +469,31 @@ ext_call({
 
 ```javascript
 module.exports = [
-  { name: 'greet', description: '打招呼', execute: async (args) => 'Hello ' + (args || 'World') },
-  { name: 'echo', description: '回声命令', execute: async (args) => 'Echo: ' + args }
+  {
+    name: 'greet',
+    description: '打招呼',
+    options: [
+      { flags: '-n, --name <value>', description: '名字', defaultValue: 'World' },
+      { flags: '-l, --lang <value>', description: '语言', defaultValue: 'zh' }
+    ],
+    execute: async (args) => `Hello ${args.name || 'World'}`
+  },
+  {
+    name: 'echo',
+    description: '回声命令',
+    options: [
+      { flags: '-t, --text <value>', description: '回显文本', required: true }
+    ],
+    execute: async (args) => 'Echo: ' + args.text
+  }
 ];
 ```
 
 **使用方法：**
 
 - `/test-skill:greet` → 返回 "Hello World"
-- `/test-skill:greet Alice` → 返回 "Hello Alice"
-- `/test-skill:echo Hello` → 返回 "Echo: Hello"
+- `/test-skill:greet {"name":"Alice"}` → 返回 "Hello Alice"
+- `/test-skill:echo {"text":"Hello"}` → 返回 "Echo: Hello"
 
 ### 自动注册