foliko 2.0.4 → 2.0.6

package/docs/usage.md

@@ -166,32 +166,67 @@ skills/              → 子目录内有 SKILL.md → 加载为 skill
 
 ### 命令注册
 
-如果 skill 目录下有 `index.js`，导出命令数组即可注册为可调用的 slash 命令：
+如果 skill 目录下有 `index.js`，导出命令数组即可注册为可调用的扩展。**每个 skill 自动注册为 `skill:<skillname>` 扩展**，命令是扩展下的 tool。
 
 ```js
-module.exports = [
-  {
-    name: 'greet',
-    description: '打招呼',
-    options: [
-      { flags: '-n, --name <value>', description: '姓名' }
-    ],
-    execute: async (parsedArgs, ctx) => {
-      return `Hello, ${parsedArgs.name || 'World'}!`
-    }
-  }
-]
+// index.js
+module.exports = {
+  commands: [
+    {
+      name: 'greet',
+      description: '打招呼',
+      options: [
+        { flags: '-n, --name <name>', description: '姓名', required: true },
+        { flags: '-l, --lang <lang>', description: '语言', defaultValue: 'zh' },
+        { flags: '-s, --shout', description: '是否大声喊' },
+      ],
+      execute: async (args) => {
+        // args 是 commander.js 解析后的对象，无需自己解析命令字符串
+        const name = args.name || 'World';
+        const lang = args.lang || 'zh';
+        const shout = !!args.shout;
+        return `Hello, ${name}!` + (shout ? '!!!' : '');
+      },
+    },
+  ],
+};
 ```
 
-命令通过 `ext_call({ plugin: "skill", tool: "skill-name:command-name", args: { command: "..." } })` 调用。
+#### 调用方式
+
+```js
+// 1. 查询参数
+ext_skill({ plugin: "skill:<skillname>" })
+
+// 2. 调用（传命令行字符串）
+ext_call({
+  plugin: "skill:<skillname>",
+  tool: "greet",
+  args: { command: "-n Claude -l en --shout" },
+})
+```
+
+#### 参数传递
+
+Skill 命令参数通过 `args: { command: "..." }` 传递命令行字符串，由 Commander.js 解析后传给 handler：
+
+| flags | 解析后 args 字段 |
+|---|---|
+| `-n, --name <name>` | `args.name` |
+| `-l, --lang <lang>` | `args.lang` |
+| `-s, --shout` | `args.shout` |
 
 ### 相关工具
 
-- `skill_load({ skill: "name" })` — 获取技能内容
+- `skill_load({ skill: "name" })` — 获取技能内容（SKILL.md + 命令参考）
 - `skill_reload` — 重载所有技能
 - `skill_load_reference({ skill, reference })` — 加载技能的参考文档
 - `skill_list_scripts` / `skill_load_script` — 技能脚本管理
 
+### 程序化注册（不依赖文件）
+
+可在 Plugin 中用 `this.skill.register(...)` 程序化创建技能，详见 [Plugin 基类的 skill accessor](#技能注册skillregister)。
+
 ## Workflows
 
 ### 结构化工作流
@@ -330,25 +365,67 @@ class MyPlugin extends Plugin {
     this.system = false
   }
 
-  install(framework) {
-    // 注册工具、监听事件
-    framework.registerTool({
+  onStart(framework) {
+    // 1. 注册 AI SDK 直调工具
+    this.tool.register({
       name: 'my_tool',
       description: 'My tool',
-      inputSchema: z.object({ ... }),
-      execute: async (args) => { ... }
+      inputSchema: framework.z.object({
+        param: framework.z.string().describe('参数')
+      }),
+      execute: async (args) => { /* ... */ }
+    })
+
+    // 2. 注册扩展工具（通过 ext_call 调用）
+    this.extension.register({
+      name: 'my_ext',
+      description: 'Extension tool',
+      inputSchema: framework.z.object({ /* ... */ }),
+      execute: async (args) => { /* ... */ }
     })
+
+    // 3. 注册工作流
+    this.workflow.register('my-workflow', {
+      name: 'my-workflow',
+      steps: [/* ... */]
+    })
+
+    // 4. 注册子代理
+    this.agent.register({
+      name: 'helper',
+      role: '助手',
+      description: '辅助处理',
+      tools: {}
+    })
+
+    // 5. 注册 prompt part
+    this.prompt.register('my-rules', () => 'Rules content', {
+      scope: 'global',
+      priority: 50
+    })
+
+    // 6. 注册程序化 Skill（自动成为 skill:<name> 扩展）
+    this.skill.register('my-skill', '# My Skill\n\n...', {
+      description: 'My skill description'
+    }, {
+      commands: [{
+        name: 'do',
+        description: '...',
+        options: [{ flags: '-n, --name <name>', required: true }],
+        execute: async (args) => ({ success: true })
+      }]
+    })
+
     framework.on('some:event', handler)
-    return this
   }
 
-  start(framework) {
-    // 初始化逻辑，start() 可能会被调用多次
-    return this
+  onStop() {
+    // 清理资源（工具/扩展/工作流/子代理/prompt/skill 基类自动处理）
   }
 
   reload(framework) {
-    // 热重载
+    // 声明式 prompts 自动清理/注册
+    // tool/extension/workflow/agent/prompt/skill 基类自动重新注册
   }
 
   async onCwdChanged(oldCwd, newCwd, framework) {
@@ -364,22 +441,37 @@ class MyPlugin extends Plugin {
 module.exports = MyPlugin
 ```
 
+#### 插件基类的 6 个 accessor 一览
+
+| Accessor | 方法 | 用途 |
+|---|---|---|
+| `this.tool` | `register`/`remove`/`execute` | AI SDK 直接调用的工具 |
+| `this.extension` | `register`/`remove`/`execute` | 扩展工具（通过 ext_call） |
+| `this.workflow` | `register`/`remove`/`execute` | 工作流 |
+| `this.agent` | `register`/`remove`/`get` | 子代理 |
+| `this.prompt` | `register`/`remove` | 提示词 part |
+| **`this.skill`** | `register`/`remove`/`get`/`has`/`list`/`details`/`listOwned`/`execute` | 技能（自动注册为 `skill:<name>` 扩展） |
+
 ### 生命周期
 
 ```
-install() → load() → [start() + 注册工具]
+install() → load() → [start() → onStart() + 注册工具]
                 ↓
          startAll() → [start() 再次调用]
                 ↓
-         reload() → 热重载
+         reload() → 清理 + onStart()
+                ↓
+         disable() → stop() → onStop()
+                ↓
+         enable() → start() → onStart()
                 ↓
-         uninstall() → 卸载清理
+         uninstall() → 清理 + 移除工具
 ```
 
 **注意**：`start()` 会被调用两次（`load()` 和 `startAll()`），插件需通过 `_loaded` 标志或幂等设计来防止重复初始化。
 
 ### 放置位置
 
-- 项目级：`plugins/<name>/index.js`
+- 项目级：`.foliko/plugins/<name>/index.js`
 - 全局：`~/.foliko/plugins/<name>.js` 或 `~/.foliko/plugins/<name>/index.js`
-- 通过 `pluginLinks` 指定任意路径
+- 内置：`plugins/<name>/index.js`

package/package.json

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

package/plugins/core/audit/index.js

@@ -23,7 +23,7 @@ class AuditPlugin extends Plugin {
     this.config = {
       maxLogs: config.maxLogs || 1000,
       retentionDays: config.retentionDays || 30,
-      logDir: config.logDir || path.join(os.homedir(), '.vb-agent', 'logs', 'audit')
+      logDir: config.logDir || path.join(os.homedir(), '.foliko', 'logs', 'audit')
     }
 
     this._framework = null

package/plugins/core/default/bootstrap.js

@@ -40,15 +40,36 @@ async function loadCustomPlugins(framework, agentConfig) {
         delete require.cache[require.resolve(resolved.path)];
         const mod = require(resolved.path);
         let pluginClass = mod.default || mod;
+
+        // 如果默认导出不是 Plugin 子类，查找模块中的 Plugin 子类
         if (typeof pluginClass === 'function' && !(pluginClass.prototype instanceof Plugin)) {
           const keys = Object.keys(mod).filter(k => mod[k] && mod[k].prototype instanceof Plugin);
           if (keys.length > 0) pluginClass = mod[keys[0]];
         }
+
+        // 如果 pluginClass 是对象（模块直接导出对象而非类），查找其中的 Plugin 子类
+        if (typeof pluginClass !== 'function' && pluginClass.prototype === undefined) {
+          const keys = Object.keys(mod).filter(k => mod[k] && mod[k].prototype instanceof Plugin);
+          if (keys.length > 0) pluginClass = mod[keys[0]];
+        }
+
+        // 检查 pluginClass 是否是 Plugin 实例
+        if (pluginClass instanceof Plugin) {
+          pluginClass = pluginClass.constructor;
+        }
+
         let resolvedName = pluginName;
         if (typeof pluginClass === 'function' && pluginClass.prototype instanceof Plugin) {
           resolvedName = new pluginClass().name || pluginName;
         }
         if (framework.pluginManager.has(resolvedName) && framework.pluginManager.get(resolvedName)?._started) continue;
+
+        // 跳过无法识别的模块（不是 Plugin 类也不是 Plugin 实例）
+        if (typeof pluginClass !== 'function' && !(pluginClass instanceof Plugin)) {
+          log.debug(`Skipping ${pluginName}: not a Plugin class or instance`);
+          continue;
+        }
+
         const pluginConfig = agentConfig[resolvedName] || {};
         let instance;
         if (typeof pluginClass === 'function') {
@@ -56,10 +77,21 @@ async function loadCustomPlugins(framework, agentConfig) {
             // 类式：new PluginClass()
             instance = new pluginClass(pluginConfig);
           } else {
-            // function(foliko) 格式：直接调用，传入 framework
-            pluginClass(framework);
-            // function(foliko) 不需要 return，插件内部自己注册
-            instance = null; // 不再作为插件实例加载
+            // function(Plugin) 或 function(foliko) 格式：尝试调用
+            try {
+              // 优先尝试 function(Plugin) 格式
+              const Result = pluginClass(Plugin);
+              if (Result && Result.prototype instanceof Plugin) {
+                instance = new Result(pluginConfig);
+              } else {
+                // function(foliko) 格式：传入 framework
+                pluginClass(framework);
+                instance = null;
+              }
+            } catch (err) {
+              log.error(`Failed to call plugin factory ${pluginName}:`, err.message);
+              continue;
+            }
           }
         } else {
           instance = pluginClass;
@@ -127,21 +159,6 @@ async function bootstrapDefaults(framework, config = {}) {
     }));
   }
 
-  // 1.5 Main Agent
-  if (!framework._mainAgent) {
-    const { Agent } = require('../../../src/agent/main');
-    const aiPlugin = framework.pluginManager.get('ai');
-    framework._mainAgent = framework.createAgent({
-      name: 'MainAgent',
-      systemPrompt: '你是一个智能助手。当用户提出问题或任务时，你会主动分析需求，选择合适的工具来获取信息或执行操作。你善于将复杂任务拆解为多个步骤，通过工具协作完成。',
-      model: aiConfig.model || 'deepseek-chat',
-      provider: aiConfig.provider || 'deepseek',
-      apiKey: aiPlugin ? aiPlugin.config.apiKey : (aiConfig.apiKey || envApiKey),
-      baseURL: aiConfig.baseURL,
-    });
-    framework._agents.push(framework._mainAgent);
-  }
-
   // 1.875 Extension executor (needed by skill-manager for slash commands)
   if (shouldLoad('extension-executor')) {
     const ExtensionExecutorPlugin = require('../../executors/extension');
@@ -230,6 +247,35 @@ async function bootstrapDefaults(framework, config = {}) {
   // 统一启动所有插件
   await framework.pluginManager.startAll();
 
+  // 等待 skill-manager 完成首次异步加载 (`_loadAllSkills` 包含动态 import ESM 的 index.js)
+  // 否则 MainAgent 首次 _buildSystemPrompt() 会错过 skill 命令
+  const skillManagerEntry = framework.pluginManager.get('skill-manager');
+  if (skillManagerEntry && typeof skillManagerEntry._loadReady?.then === 'function') {
+    try {
+      await skillManagerEntry._loadReady;
+    } catch (_) { /* 加载失败已在 skill-manager 内 log */ }
+  }
+
+  // ============= Main Agent (在所有 plugins 加载并 start 之后) =============
+  // 修复: 必须放到所有 plugins 加载并 start 之后再创建,并且 await skill-manager 的
+  // _loadReady。
+  // 原顺序下 MainAgent.constructor 会立即 _buildSystemPrompt(),此时 extension-executor
+  // 和 skill-manager 还没注册工具到 prompt registry,导致系统提示词里看不到 skill 命令
+  // —— 之前用户必须 reload 一次才看到就是这个 race。
+  if (!framework._mainAgent) {
+    const { Agent } = require('../../../src/agent/main');
+    const aiPlugin = framework.pluginManager.get('ai');
+    framework._mainAgent = framework.createAgent({
+      name: 'MainAgent',
+      systemPrompt: '你是一个智能助手。当用户提出问题或任务时,你会主动分析需求,选择合适的工具来获取信息或执行操作。你善于将复杂任务拆解为多个步骤,通过工具协作完成。',
+      model: aiConfig.model || 'deepseek-chat',
+      provider: aiConfig.provider || 'deepseek',
+      apiKey: aiPlugin ? aiPlugin.config.apiKey : (aiConfig.apiKey || envApiKey),
+      baseURL: aiConfig.baseURL,
+    });
+    framework._agents.push(framework._mainAgent);
+  }
+
   // 退出 bootstrap 模式
   framework.pluginManager.setBootstrapping(false);
 }

package/plugins/core/python-loader/index.js

@@ -53,15 +53,14 @@ class PythonPluginLoader extends Plugin {
     }
 
     let desc = '## 【Python 插件】\n\n'
-    desc += 'Python 插件工具通过 `ext_call` 调用：\n\n'
+    desc += '每个 Python 插件自动注册为 `python:<插件名>` 扩展，通过 `ext_skill` + `ext_call` 统一调用：\n\n'
 
     for (const [name, plugin] of this._pythonPlugins) {
-      desc += `### ${plugin.info.name}\n`
+      desc += `### python:${plugin.info.name}\n`
       desc += `${plugin.info.description || ''}\n\n`
       if (plugin.info.tools && Array.isArray(plugin.info.tools)) {
         for (const tool of plugin.info.tools) {
-          const fullName = `${name}_${tool.name}`
-          desc += `- **${fullName}**: ${tool.description || '无描述'}\n`
+          desc += `- **${tool.name}**: ${tool.description || '无描述'}\n`
           // 使用 zodSchemaToMarkdown 生成参数描述
           const params = tool.params || {}
           if (Object.keys(params).length > 0) {
@@ -82,7 +81,9 @@ class PythonPluginLoader extends Plugin {
     }
 
     desc += '**调用格式:**\n'
-    desc += '```\next_call({ plugin: "python", tool: "插件名_工具名", args: {...} })\n'
+    desc += '```\n'
+    desc += '// 1. 查询参数\next_skill({ plugin: "python:<插件名>" })\n'
+    desc += '// 2. 调用\next_call({ plugin: "python:<插件名>", tool: "<工具名>", args: {...} })\n'
     desc += '```\n'
     return desc.trim()
   }
@@ -151,7 +152,7 @@ class PythonPluginLoader extends Plugin {
           // 注册插件的每个工具
           if (pluginInfo.tools && Array.isArray(pluginInfo.tools)) {
             for (const tool of pluginInfo.tools) {
-              this._registerPythonTool(pluginName, tool)
+              this._registerPythonTool(pluginName, tool, pluginInfo);
             }
           }
         }
@@ -160,22 +161,32 @@ class PythonPluginLoader extends Plugin {
       }
     }
 
+    // 所有 Python 插件注册完毕后，强制失效 prompt 缓存，让 LLM 看到新的扩展
+    this._extensionExecutor?._invalidatePromptCaches?.(this._framework);
+
     //log.info(` Total Python plugins: ${this._pythonPlugins.size}`)
   }
 
   /**
-   * 注册 Python 插件的工具
-   * 工具名格式：插件名_工具名（如 stock_get_price）
-   * 直接注册到 ExtensionExecutor，使用 ext_call({ plugin: "python", tool: "插件名_工具名", args: {...} }) 调用
+   * 注册 Python 插件的单个工具到 ExtensionExecutor
+   *
+   * 每个 Python 插件注册为独立扩展 `python:<插件名>`，工具名是原始名（不带前缀）。
+   * LLM 通过以下方式调用：
+   *   1. 查询参数：ext_skill({ plugin: "python:<插件名>" })
+   *   2. 调用：ext_call({ plugin: "python:<插件名>", tool: "<工具名>", args: {...} })
+   *
+   * @param {string} pluginName Python 插件名（PLUGIN.name，例如 'stock'）
+   * @param {Object} tool 工具定义对象
+   * @param {string} tool.name 工具名（PLUGIN.TOOLS[].name，例如 'get_price'）
+   * @param {string} [tool.description] 工具描述（用于提示词）
+   * @param {Object} [tool.params] 工具参数定义（key → 类型占位符或 JSON Schema）
+   * @param {Object} [pluginMeta] 插件元信息（含 description），用于丰富扩展描述
    */
-  _registerPythonTool(pluginName, tool) {
+  _registerPythonTool(pluginName, tool, pluginMeta = null) {
     if (!tool.name) return
 
-    // 格式：pluginname_toolname
-    const fullToolName = `${pluginName}_${tool.name}`
-
     const toolDef = {
-      name: fullToolName,
+      name: tool.name,  // 工具原始名（如 get_price），不带 pluginName_ 前缀
       description: tool.description || `${pluginName} 的 ${tool.name} 工具`,
       inputSchema: this._parseToolParams(tool.params || {}),
       execute: async (args) => {
@@ -183,26 +194,33 @@ class PythonPluginLoader extends Plugin {
       }
     }
 
+    // 每个 Python 插件注册为独立扩展 `python:<pluginName>`
+    // 优先用 PLUGIN.description，fallback 到默认描述
+    const extName = `python:${pluginName}`;
+    const extDescription = pluginMeta?.description
+      ? pluginMeta.description
+      : `Python 插件 ${pluginName}`;
+    const pluginInfo = {
+      name: extName,
+      description: extDescription,
+      version: pluginMeta?.version || '1.0.0',
+    };
+
     try {
-      // 直接注册到 ExtensionExecutor（如果可用）
       if (this._extensionExecutor) {
-        this._extensionExecutor.registerTool(
-          'python',  // 插件名，用于 ext_call 的 plugin 参数
-          { name: 'python', description: 'Python 插件工具', version: '1.0.0' },
-          toolDef
-        )
+        this._extensionExecutor.registerTool(extName, pluginInfo, toolDef);
       } else {
-        // 回退到基类的 registerTool
+        // 回退到基类的 registerTool（带 pluginName 前缀以避免冲突）
         this.registerTool({
-          name: fullToolName,
-          description: `[${pluginName}] ${tool.description || ''}`,
+          name: `${pluginName}_${tool.name}`,
+          description: tool.description || `${pluginName} 的 ${tool.name} 工具`,
           pluginName: pluginName,
           inputSchema: this._parseToolParams(tool.params || {}),
           execute: toolDef.execute
-        })
+        });
       }
     } catch (err) {
-      log.error(` Failed to register tool ${fullToolName}:`, err.message)
+      log.error(` Failed to register tool ${tool.name} for ${extName}:`, err.message)
     }
   }
 

package/plugins/core/skill-manager/PROMPT.md

@@ -0,0 +1,6 @@
+## 可用技能
+
+> 命令详情（参数、调用方式）请查看上方【Extensions】扩展插件段落。
+> 详细使用指南用 `skill_load("技能名")` 加载。
+
+{{skills}}