foliko 2.0.4 → 2.0.6

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

@@ -130,6 +130,205 @@ class SkillMetadata {
   }
 }
 
+/**
+ * 从 commander.js 的 flags 字符串中提取字段名
+ *   "--video-id <id>"   → "videoId"
+ *   "-v, --video-id <id>" → "videoId"  (优先用长名)
+ *   "--flag"            → "flag"       (布尔)
+ *   "-v"                → "v"          (布尔)
+ */
+function extractOptionName(flags) {
+  if (!flags) return null;
+  // 提取所有 long 选项（--xxx）和 short 选项（-x）
+  const tokens = flags.split(/[,\s]+/).filter(t => t && !t.includes('<'));
+  // 优先选 long 选项（--开头）
+  const longOpt = tokens.find(t => t.startsWith('--'));
+  const target = longOpt || tokens[0];
+  if (!target) return null;
+  // 去掉前导 -，转 camelCase
+  const stripped = target.replace(/^-+/, '');
+  return stripped.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * 判断 option 是否需要值（flags 包含 `<...>`)
+ */
+function optionHasValue(flags) {
+  return /<[^>]+>/.test(flags || '');
+}
+
+/**
+ * 将 cmd.options 数组转换为 Zod 对象 schema
+ *
+ * 支持两种类型声明方式（优先级从高到低）：
+ *   1. schema  — 直接写 Zod 实例，如 { flags: '-n <value>', schema: z.number(), description: '...' }
+ *   2. type    — 字符串类型，如 { flags: '-n <value>', type: 'number', description: '...' }
+ *   3. fallback — 无 schema/type，根据 hasValue 推断（string / boolean）
+ *
+ * type 可选值：'string' | 'number' | 'boolean' | 'array' | 'object'
+ */
+function buildZodSchemaFromOptions(options, commandDescription) {
+  if (!Array.isArray(options) || options.length === 0) {
+    return z.object({}).passthrough();
+  }
+
+  const shape = {};
+  for (const opt of options) {
+    const name = extractOptionName(opt.flags);
+    if (!name) continue;
+
+    const hasValue = optionHasValue(opt.flags);
+    const isRequired = opt.required === true && hasValue;
+    let desc = opt.description || '';
+    if (opt.defaultValue !== undefined && opt.defaultValue !== '') {
+      desc += ` (默认: ${opt.defaultValue})`;
+    }
+
+    let fieldSchema;
+
+    // 优先用 schema（Zod 实例）
+    if (opt.schema && typeof opt.schema.parse === 'function') {
+      fieldSchema = opt.schema.describe(desc);
+      if (opt.defaultValue !== undefined && opt.defaultValue !== null) {
+        fieldSchema = fieldSchema.default(opt.defaultValue);
+      }
+    }
+    // 其次用 type（字符串类型）
+    else if (opt.type) {
+      fieldSchema = buildSchemaFromType(opt.type, desc, opt.defaultValue);
+    }
+    // 默认行为：带 <value> 为 string，否则 boolean
+    else if (hasValue) {
+      fieldSchema = z.string().describe(desc);
+      if (opt.defaultValue !== undefined && opt.defaultValue !== null && opt.defaultValue !== '') {
+        fieldSchema = fieldSchema.default(String(opt.defaultValue));
+      }
+    } else {
+      fieldSchema = z.boolean().describe(desc || '布尔标志');
+    }
+
+    if (!isRequired) {
+      fieldSchema = fieldSchema.optional();
+    }
+    shape[name] = fieldSchema;
+  }
+  return z.object(shape).passthrough();
+}
+
+/**
+ * 根据 type 字符串构建 Zod Schema
+ */
+function buildSchemaFromType(type, desc, defaultValue) {
+  const LOWER = type.toLowerCase();
+  let schema;
+
+  switch (LOWER) {
+    case 'number':
+    case 'int':
+    case 'integer':
+      schema = z.number().describe(desc);
+      if (defaultValue !== undefined && defaultValue !== null) {
+        schema = schema.default(Number(defaultValue));
+      }
+      break;
+    case 'boolean':
+    case 'bool':
+      schema = z.boolean().describe(desc || '布尔标志');
+      if (defaultValue !== undefined && defaultValue !== null) {
+        schema = schema.default(Boolean(defaultValue));
+      }
+      break;
+    case 'array':
+      schema = z.array(z.string()).describe(desc);
+      if (defaultValue !== undefined && defaultValue !== null) {
+        const arr = Array.isArray(defaultValue) ? defaultValue : [defaultValue];
+        schema = schema.default(arr.map(String));
+      }
+      break;
+    case 'object':
+      schema = z.record(z.any()).describe(desc);
+      if (defaultValue !== undefined && defaultValue !== null && typeof defaultValue === 'object') {
+        schema = schema.default(defaultValue);
+      }
+      break;
+    case 'string':
+    default:
+      schema = z.string().describe(desc);
+      if (defaultValue !== undefined && defaultValue !== null && defaultValue !== '') {
+        schema = schema.default(String(defaultValue));
+      }
+      break;
+  }
+
+  return schema;
+}
+
+/**
+ * 生成等效的 JSON schema（用于 _rawSchema，让 ext_skill 渲染更清晰）
+ */
+function buildRawJsonSchema(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 || '';
+
+    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';
+    }
+
+    properties[name] = { type: jsonType, description: desc };
+    if (isRequired) required.push(name);
+  }
+  return { type: 'object', properties, required };
+}
+
+/**
+ * 从 options 构建示例命令行字符串
+ */
+function buildExampleFromOptions(options) {
+  if (!Array.isArray(options) || options.length === 0) return '';
+  const parts = [];
+  for (const opt of options) {
+    const flags = opt.flags || '';
+    // 提取短选项和长选项
+    const tokens = flags.split(/[,\s]+/).filter(t => t && !t.includes('<'));
+    const shortOpt = tokens.find(t => /^-[a-zA-Z]$/.test(t));
+    const longOpt = tokens.find(t => t.startsWith('--'));
+    const flag = shortOpt || longOpt || tokens[0];
+    if (!flag) continue;
+
+    const hasValue = /<[^>]+>/.test(flags);
+    if (hasValue) {
+      const defaultVal = opt.defaultValue !== undefined && opt.defaultValue !== null ? String(opt.defaultValue) : '<value>';
+      parts.push(`${flag} ${defaultVal}`);
+    } else {
+      parts.push(flag);
+    }
+  }
+  return parts.join(' ');
+}
+
 /**
  * Skill 类
  */
@@ -183,7 +382,7 @@ class Skill {
 
     const skillInfo = {
       name: skillName,
-      description: this.metadata?.description || `Skill: ${skillName}`,
+      description: this.metadata?.description || '',
       version: this.metadata?.compatibility || '1.0.0',
     };
 
@@ -232,40 +431,71 @@ class Skill {
               return { ...program.opts(), args: program.args };
             } catch (err) {
               log.warn(`[SkillManager] Command parse error: ${err.message}`);
-              return { args: rawArgs };
+              // 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;
             }
           };
         }
 
-        // 构建详细的命令描述，帮助 LLM 正确调用
-        let commandHint = '';
-        if (cmd.options && cmd.options.length > 0) {
-          const optDescs = cmd.options.map(formatOptionForHelp);
-          commandHint = `\n  可用选项:\n  ${optDescs.join('\n  ')}`;
-        }
-
-        // 生成示例命令
-        const exampleCmd = cmd.options && cmd.options.length > 0
-          ? cmd.options.map(o => {
-              const flag = (o.flags || '').split(/[,\s]+/).filter(p => p && !p.includes('<') && !p.includes(','))[0]?.replace(/^-*/, '') || '';
-              const hasValue = (o.flags || '').includes('<');
-              const def = o.defaultValue !== undefined && o.defaultValue !== '' ? String(o.defaultValue) : '';
-              const val = def || '<值>';
-              return hasValue ? `-${flag} ${val}` : `-${flag}`;
-            }).join(' ')
+        // 直接使用 command 字符串的 schema，describe 说明命令行格式
+        const exampleArgs = cmd.options && cmd.options.length > 0
+          ? buildExampleFromOptions(cmd.options)
           : '';
-
         const toolDef = {
-          name: fullName,
-          description: `${cmd.description || 'Skill command'}\n\n**重要**: args.command 是**字符串**，不是对象！\n例: args: { command: "${exampleCmd}" }\n\n${commandHint}`,
+          name: cmd.name,
+          description: cmd.description || 'Skill command',
           inputSchema: z.object({
-            command: z.string().optional().describe(
-              cmd.options && cmd.options.length > 0
-                ? `**字符串**，空格分隔，如: ${cmd.options.map(formatOptionForExample).join(' ')}`
-                : `**字符串**，命令行参数`
-            ),
+            command: z.string().optional().describe(exampleArgs || '命令行字符串，如：-n value1 -v'),
           }),
           _options: cmd.options || null,
+          // 把原始 options 数组也保存下来，便于 ext_skill 显示
+          _rawSchema: buildRawJsonSchema(cmd.options),
           execute: async (toolArgs, framework) => {
             const ctx = {
               sessionId: framework?._currentSessionId || 'unknown',
@@ -273,16 +503,27 @@ class Skill {
               framework: framework,
               cwd: framework?.getCwd?.() ?? process.cwd(),
             };
-            let parsedArgs = toolArgs.command || '';
+            // 直接使用 command 字符串
+            const commandString = toolArgs?.command || '';
+            let parsedArgs = commandString;
             if (typeof argumentParser === 'function') {
-              parsedArgs = argumentParser(toolArgs.command || '');
+              parsedArgs = argumentParser(commandString);
             }
             return await handler(parsedArgs, ctx);
           },
         };
 
-        // 注册到 extension 系统
-        extExecutor.registerTool('skill', skillInfo, toolDef);
+        // 注册到 extension 系统：每个 skill 注册为独立扩展 (skill:<skillname>)
+        const skillExtName = `skill:${skillName}`;
+        // 优先用 SKILL.md frontmatter 的 description，回退到空（提示词会隐藏）
+        const extDescription = skillInfo.description
+          ? skillInfo.description
+          : `Skill ${skillName}`;
+        extExecutor.registerTool(skillExtName, {
+          name: skillExtName,
+          description: extDescription,
+          version: skillInfo.version || '1.0.0',
+        }, toolDef);
 
         // 同时添加到 this.tools，供 extension-executor 的 _scanPluginTools 扫描
         this.tools[fullName] = toolDef;
@@ -298,15 +539,20 @@ class Skill {
 /**
  * SkillManager 插件
  */
+const PROMPT_DIR = __dirname;
+
 class SkillManagerPlugin extends Plugin {
   // 声明式 prompt parts
   prompts = [
     {
       name: 'skills',
-      slot: 'CAPABILITY',
+      file: path.join(PROMPT_DIR, 'PROMPT.md'),
+      scope: 'global',
+      priority: 60,
       description: '可用技能列表',
-      provider: function () {
-        return this._buildSkillsDescription();
+      interpolate: (content) => {
+        const list = this._buildSkillsList();
+        return content.replace('{{skills}}', list || '(暂无技能)');
       },
     },
   ];
@@ -325,6 +571,9 @@ class SkillManagerPlugin extends Plugin {
       : [config.skillsDir || '.foliko/skills', 'skills'];
     this._skills = new Map();
     this._loaded = false;
+    // _loadReady 暴露给外部等待首加载完成(bootstrap 在创建 MainAgent 前 await 它,
+    // 确保系统提示词第一次构建就能看到所有 skill 命令)
+    this._loadReady = Promise.resolve();
     this.tools = {}; // 用于 extension-executor 扫描（由 Skill.registerCommands 填充）
   }
 
@@ -335,7 +584,9 @@ class SkillManagerPlugin extends Plugin {
 
   start(framework) {
     super.start(framework);
-    this._loadAllSkills().catch(err => log.error('_loadAllSkills failed:', err.message));
+    this._loadReady = this._loadAllSkills().catch(err => {
+      log.error('_loadAllSkills failed:', err.message);
+    });
 
     // 注册 skill_load 工具
     framework.registerTool({
@@ -372,7 +623,7 @@ class SkillManagerPlugin extends Plugin {
             }
             cmdLines.push('');
           }
-          cmdLines.push('调用：`ext_call({ plugin: "skill", tool: "' + skillName + ':<命令>", args: { command: "参数" } })`');
+          cmdLines.push('调用：`ext_call({ plugin: "skill:' + skillName + '", tool: "<command>", args: { /* Zod 结构化参数 */ } })`');
           commandDocs = cmdLines.join('\n');
         }
         return {
@@ -490,70 +741,23 @@ class SkillManagerPlugin extends Plugin {
   }
 
   /**
-   * 构建技能描述
+   * 构建技能列表（简版，仅显示技能名 + 描述）
+   * 命令详情在【Extensions】扩展插件段落有完整展示（含 Zod 参数）
+   * 详细使用指南用 skill_load("技能名") 加载
    */
-  _buildSkillsDescription() {
+  _buildSkillsList() {
     const skills = this.getAllSkills();
     if (!skills || skills.length === 0) {
       return '';
     }
 
-    const lines = [
-      '## 可用技能',
-      '命令调用（仅对上方标注了「命令:」的技能有效）：`ext_call({ plugin: "skill", tool: "<技能名>:<命令>", args: { command: "参数" } })`',
-      '',
-    ];
-
-    const extExecutor = this._framework?.pluginManager?.get('extension-executor');
-    const skillCommands = extExecutor?.getSkillCommands?.() || [];
-
-    // 按技能名分组命令（保留完整信息以渲染选项）
-    const toolsBySkill = {};
-    for (const tool of skillCommands) {
-      if (!tool || !tool.name) continue;
-      const parts = tool.name.split(':');
-      if (parts.length < 2) continue;
-      const skillName = parts[0];
-      const cmdName = parts.slice(1).join(':');
-      if (!toolsBySkill[skillName]) toolsBySkill[skillName] = [];
-      toolsBySkill[skillName].push({ name: cmdName, description: tool.description || '', options: tool.options || null });
-    }
-
-    // 一列一技能，命令含选项时显示参数
+    const lines = [];
     for (const skill of skills) {
       const name = skill.metadata?.name || skill.name || 'unknown';
       const descText = skill.metadata?.description || '';
-      if (!descText && !toolsBySkill[name]) continue;
-
-      const parts = [];
-      if (descText) parts.push(descText);
-
-      if (toolsBySkill[name]) {
-        const cmdStrs = toolsBySkill[name].map(cmd => {
-          if (cmd.options && cmd.options.length > 0) {
-            const optStrs = cmd.options.map(o => {
-              // 提取长选项名（--xxx）作为参数名，形如 "--tokens <值>"
-              const flag = o.flags || '';
-              const longOpt = flag.split(/\s+/).filter(f => f.startsWith('--'))[0];
-              const valPart = flag.includes('<') ? flag.match(/<[^>]+>/)?.[0] || '' : '';
-              if (longOpt && valPart) return `${longOpt} ${valPart}`;
-              if (longOpt) return longOpt;
-              return flag.split(/\s+/).filter(f => f && !f.includes('<')).map(f => f.replace(/,$/, ''))[0] || flag;
-            });
-            return `${cmd.name}(${optStrs.join(', ')})`;
-          }
-          return cmd.name;
-        });
-        parts.push(`命令: ${cmdStrs.join(', ')}`);
-      }
-      lines.push(`- **${name}**: ${parts.join(' | ')}`);
+      if (!descText) continue;
+      lines.push(`- **${name}**: ${descText}`);
     }
-
-    lines.push(
-      '',
-      '> **提示**：使用 `skill_load("${skill名}")` 加载技能获取详细使用指南。'
-    );
-
     return lines.join('\n');
   }
 
@@ -631,6 +835,19 @@ class SkillManagerPlugin extends Plugin {
 
     // log.info(` Loaded ${this._skills.size} skills`);
     this._loaded = true;
+
+    // 通知 extension-executor 失效 prompt 缓存,让 AI 看到新注册的 skill 命令
+    // 原因: _loadAllSkills 是异步的(_loadSkill 中 await skill.registerCommands() 会动态 import ESM 包),
+    // 但 framework:ready 在所有 plugin loadPlugin() 之后立即触发,那时 skill 命令可能还没注册。
+    // 不刷缓存的话,首启动后模型看不到这些命令,必须 reload 一次才出现。
+    if (this._framework) {
+      try {
+        const extExec = this._framework.pluginManager?.get('extension-executor');
+        if (extExec && typeof extExec._invalidatePromptCaches === 'function') {
+          extExec._invalidatePromptCaches();
+        }
+      } catch (_) { /* 失效失败不影响 skill 加载 */ }
+    }
   }
 
   /**
@@ -1006,6 +1223,233 @@ class SkillManagerPlugin extends Plugin {
     return this._skills.has(name);
   }
 
+  /**
+   * 获取 skill 详情（结构化信息）
+   */
+  getSkillDetails(name) {
+    const skill = this._skills.get(name);
+    if (!skill) return null;
+    return {
+      name: skill.name,
+      description: skill.metadata?.description || '',
+      content: skill.content || '',
+      path: skill.path || null,
+      metadata: skill.metadata ? {
+        name: skill.metadata.name,
+        description: skill.metadata.description,
+        license: skill.metadata.license,
+        compatibility: skill.metadata.compatibility,
+        allowedTools: skill.metadata.allowedTools,
+      } : null,
+      commands: skill.instance?._commands || [],
+      references: skill.references ? Array.from(skill.references.keys()) : [],
+      scripts: skill.scripts ? Array.from(skill.scripts.keys()) : [],
+      fromPlugin: skill.fromPlugin || false,
+      registered: skill.registered || false,
+    };
+  }
+
+  /**
+   * 注册一个新 skill（程序化注册，不依赖文件）
+   * @param {string} name - 技能名称
+   * @param {string} content - 技能内容（markdown）
+   * @param {Object} [metadata] - 技能元数据
+   * @param {Object} [options] - 选项
+   * @param {Function[]} [options.commands] - 命令定义数组 [{ name, description, options, execute }]
+   * @param {string} [options.path] - 技能路径（用于 references/scripts 解析）
+   * @returns {Object} 注册的 skill 对象
+   */
+  register(name, content, metadata = {}, options = {}) {
+    const skillMetadata = new SkillMetadata({
+      name: name,
+      description: metadata.description || '',
+      license: metadata.license || null,
+      compatibility: metadata.compatibility || null,
+      metadata: metadata.metadata || {},
+      allowedTools: metadata['allowed-tools'] || metadata.allowedTools || [],
+    });
+
+    const skill = new Skill(skillMetadata, content);
+    skill._skillPath = options.path || null;
+    skill.install(this._framework);
+
+    // 注册命令
+    if (Array.isArray(options.commands) && options.commands.length > 0) {
+      for (const cmd of options.commands) {
+        if (!cmd || !cmd.name) continue;
+
+        const handler = typeof cmd.execute === 'function' ? cmd.execute : null;
+        if (!handler) continue;
+
+        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)
+          : '';
+        const toolDef = {
+          name: cmd.name,  // 只用命令名
+          description: cmd.description || 'Skill command',
+          inputSchema: z.object({
+            command: z.string().optional().describe(exampleArgs2 || '命令行字符串'),
+          }),
+          _options: cmd.options || null,
+          _rawSchema: buildRawJsonSchema(cmd.options),
+          execute: async (toolArgs, framework) => {
+            const ctx = {
+              sessionId: framework?._currentSessionId || 'unknown',
+              agent: null,
+              framework: framework,
+              cwd: framework?.getCwd?.() ?? process.cwd(),
+            };
+            const commandString = toolArgs?.command || '';
+            let parsedArgs = commandString;
+            if (typeof argumentParser === 'function') {
+              parsedArgs = argumentParser(commandString);
+            }
+            return await handler(parsedArgs, ctx);
+          },
+        };
+
+        const extExecutor = this._framework?.pluginManager?.get('extension-executor');
+        if (extExecutor) {
+          // 每个 skill 注册为独立扩展 (skill:<name>)
+          // 优先用 skillMetadata.description，回退到占位文本
+          const extDescription = skillMetadata.description
+            ? skillMetadata.description
+            : `Skill ${name}`;
+          extExecutor.registerTool(`skill:${name}`, {
+            name: `skill:${name}`,
+            description: extDescription,
+            version: skillMetadata.compatibility || '1.0.0',
+          }, toolDef);
+        }
+
+        skill.tools[fullName] = toolDef;
+        skill._commands.push(fullName);
+      }
+    }
+
+    // 扫描 references 和 scripts
+    const references = skill._skillPath ? this._scanReferences(skill._skillPath) : new Map();
+    const scripts = skill._skillPath ? this._scanScripts(skill._skillPath) : new Map();
+
+    const skillData = {
+      name: name,
+      metadata: skillMetadata,
+      content: content,
+      instance: skill,
+      path: skill._skillPath,
+      references,
+      scripts,
+      fromPlugin: false,
+      registered: true, // 标记为程序化注册
+    };
+
+    this._skills.set(name, skillData);
+
+    // 更新 SkillManagerPlugin.tools
+    Object.assign(this.tools, skill.tools);
+
+    return skillData;
+  }
+
+  /**
+   * 移除 skill
+   * @param {string} name 技能名称
+   * @returns {boolean} 是否成功移除
+   */
+  remove(name) {
+    if (!this._skills.has(name)) {
+      return false;
+    }
+
+    const skill = this._skills.get(name);
+
+    // 清理命令（从 extension-executor 移除）
+    // 新结构：每个 skill 注册为 `skill:<name>` 扩展，命令是该扩展下的 tool
+    if (skill.instance?._commands) {
+      const extExecutor = this._framework?.pluginManager?.get('extension-executor');
+      if (extExecutor) {
+        const extName = `skill:${name}`;
+        for (const cmdFullName of skill.instance._commands) {
+          // cmdFullName 格式: `<skill>:<command>`，如 'demo-skill:hello'
+          const cmdName = cmdFullName.includes(':') ? cmdFullName.split(':').slice(1).join(':') : cmdFullName;
+          extExecutor._unregisterTool?.(extName, cmdName);
+        }
+        // 如果该扩展下没有工具了，移除整个扩展
+        const ext = extExecutor._registry?.getPlugin?.(extName);
+        if (ext && (!ext.tools || ext.tools.length === 0)) {
+          extExecutor._registry.clearPlugin?.(extName);
+        }
+      }
+    }
+
+    // 从 SkillManagerPlugin.tools 中移除
+    if (skill.instance?.tools) {
+      for (const toolName of Object.keys(skill.instance.tools)) {
+        delete this.tools[toolName];
+      }
+    }
+
+    this._skills.delete(name);
+    return true;
+  }
+
   /**
    * 获取 skill 数量
    */
@@ -1020,9 +1464,10 @@ class SkillManagerPlugin extends Plugin {
     this._framework = framework;
 
     // 清理 extension-executor 中的旧 skill 命令，避免重载后残留
+    // 注意: extExecutor 的 Map 在 _registry._extensions 上,_extensions 自身是 undefined
     const extExecutor = framework.pluginManager?.get('extension-executor');
-    if (extExecutor) {
-      extExecutor._extensions.delete('skill');
+    if (extExecutor?._registry?.clearPlugin) {
+      extExecutor._registry.clearPlugin('skill');
     }
 
     await this._loadAllSkills();
@@ -1034,8 +1479,8 @@ class SkillManagerPlugin extends Plugin {
   async onCwdChanged(oldCwd, newCwd, framework) {
     // 切换工作目录前清理旧 skill 命令
     const extExecutor = framework.pluginManager?.get('extension-executor');
-    if (extExecutor) {
-      extExecutor._extensions.delete('skill');
+    if (extExecutor?._registry?.clearPlugin) {
+      extExecutor._registry.clearPlugin('skill');
     }
   }