foliko 2.0.5 → 2.0.6

package/skills/foliko/SKILL.md

@@ -341,28 +341,69 @@ module.exports = MyPlugin;
 
 ## 生命周期
 
-| 方法                   | 调用时机   | 必须实现 |
-| ---------------------- | ---------- | -------- |
-| `install(framework)`   | 插件安装时 | ✅       |
-| `start(framework)`     | 插件启动时 | 推荐     |
-| `reload(framework)`    | 热重载时   | 可选     |
-| `uninstall(framework)` | 卸载时     | 推荐     |
+| 方法 | 调用时机 | 必须实现 | 说明 |
+|------|----------|----------|------|
+| `install(framework)` | 插件安装时 | ✅ | 初始化，获取 framework |
+| `onStart(framework)` | start/enable/reload 时 | 推荐 | 注册工具、扩展、子代理 |
+| `onStop()` | disable 时 | 可选 | 清理资源 |
+| `reload(framework)` | 热重载时 | 可选 | prompts 自动清理/注册 |
+| `uninstall(framework)` | 卸载时 | 推荐 | 清理资源 |
+
+### onStart / onStop（推荐方式）
+
+**推荐使用 `onStart` 注册工具和扩展**，基类自动处理生命周期：
+
+```javascript
+class MyPlugin extends Plugin {
+  name = 'my-plugin';
+  version = '1.0.0';
+  description = '我的工具插件';
+
+  onStart(framework) {
+    // 注册 AI SDK 工具（直接调用）
+    this.tool.register({
+      name: 'hello',
+      description: '打招呼',
+      inputSchema: framework.z.object({
+        name: framework.z.string().describe('姓名')
+      }),
+      execute: async (args) => ({ message: `Hello, ${args.name}!` }),
+    });
+
+    // 注册扩展工具（通过 ext_call 调用）
+    this.extension.register({
+      name: 'greet',
+      description: '打招呼扩展',
+      inputSchema: framework.z.object({
+        name: framework.z.string()
+      }),
+      execute: async (args) => ({ message: `Hi, ${args.name}!` }),
+    });
+  }
+}
+```
+
+### 生命周期自动管理
+
+| 操作 | 效果 |
+|------|------|
+| `disable` | 自动移除工具/扩展（保留注册记录） |
+| `enable` | 自动重新注册工具/扩展 |
+| `reload` | 移除后重新注册 |
+| `uninstall` | 移除并清空注册记录 |
 
 ---
 
 ## 注册工具
 
-### 最新方式：定义在 `this.tools = {}`
+### 方式1：`this.tools = {}`（ExtensionExecutor 自动扫描）
 
-插件将工具定义在 `this.tools = {}` 中，ExtensionExecutor 会自动扫描并注册到系统提示词：
+插件将工具定义在 `this.tools = {}` 中，ExtensionExecutor 会自动扫描并注册：
 
 ```javascript
 class MyPlugin extends Plugin {
-  constructor(config = {}) {
-    super();
-    this.name = 'my-plugin';
-    this.description = '我的工具插件';
-  }
+  name = 'my-plugin';
+  description = '我的工具插件';
 
   tools = {
     my_tool: {
@@ -378,37 +419,125 @@ class MyPlugin extends Plugin {
 }
 ```
 
-### 方式2：使用 `this.registerTool()`
+### 方式2：`this.tool.register()`（推荐）
 
-支持两种调用格式：
+在 `onStart` 中使用，支持完整的生命周期管理：
 
 ```javascript
-install(framework) {
-  const { z } = require('zod');
-
-  // 方式1：分开传 name 和 def
-  this.registerTool('my_tool', {
+onStart(framework) {
+  this.tool.register({
+    name: 'my_tool',
     description: '我的工具',
-    inputSchema: z.object({
-      param: z.string().describe('参数描述')
+    inputSchema: framework.z.object({
+      param: framework.z.string().describe('参数描述')
     }),
     execute: async (args) => {
       return { success: true, result: args.param };
     }
   });
+}
+```
 
-  // 方式2：直接传对象（name 在对象中）
-  this.registerTool({
-    name: 'another_tool',
-    description: '另一个工具',
-    inputSchema: z.object({}),
+### 方式3：`this.registerTool()`（旧方式）
+
+```javascript
+install(framework) {
+  this.registerTool('my_tool', {
+    description: '我的工具',
+    inputSchema: framework.z.object({
+      param: framework.z.string().describe('参数描述')
+    }),
     execute: async (args) => ({ success: true })
   });
-
   return this;
 }
 ```
 
+### 注册扩展工具
+
+```javascript
+onStart(framework) {
+  this.extension.register({
+    name: 'my_ext_tool',
+    description: '扩展工具',
+    inputSchema: framework.z.object({
+      param: framework.z.string()
+    }),
+    execute: async (args) => ({ success: true })
+  });
+}
+```
+
+---
+
+## 工具/扩展操作
+
+```javascript
+// 注册
+this.tool.register({ name: 'xxx', ... });
+this.extension.register({ name: 'xxx', ... });
+
+// 移除
+this.tool.remove('xxx');
+this.extension.remove('xxx');
+
+// 执行
+const r1 = await this.tool.execute('any-tool', { arg: 'value' });  // 执行任何已注册工具
+const r2 = await this.extension.execute('xxx', { arg: 'value' });  // 执行当前插件的扩展
+const r3 = await this.extension.execute('plugin-name', 'xxx', { arg: 'value' }); // 执行指定插件的扩展
+```
+
+## 工作流操作
+
+```javascript
+// 注册工作流
+this.workflow.register('my-workflow', {
+  name: 'my-workflow',
+  description: '我的工作流',
+  steps: [
+    { type: 'tool', tool: 'hello', args: {} }
+  ]
+});
+
+// 执行工作流
+const result = await this.workflow.execute('my-workflow', { input: 'value' });
+
+// 移除工作流
+this.workflow.remove('my-workflow');
+```
+
+## 子代理操作
+
+```javascript
+// 注册子代理
+this.agent.register({
+  name: 'my-agent',
+  role: '助手',
+  goal: '描述',
+  tools: {},
+  parentTools: ['read_file', 'write_file']
+});
+
+// 获取子代理
+const agent = this.agent.get('my-agent');
+
+// 移除子代理
+this.agent.remove('my-agent');
+```
+
+## Prompt 操作
+
+```javascript
+// 注册 prompt
+this.prompt.register('my-prompt', () => 'Prompt content', {
+  scope: 'global',
+  priority: 50
+});
+
+// 移除 prompt
+this.prompt.remove('my-prompt');
+```
+
 ---
 
 ## 核心规则

package/skills/mcp/SKILL.md

@@ -1,200 +1,159 @@
 ---
 name: mcp-usage
 description: How to use MCP (Model Context Protocol) tools. Available tools, calling patterns, and best practices.
-allowed-tools: mcp_call, mcp_list_servers, mcp_tool_schema, mcp_reload, Read, Write, Edit, Glob, Grep, execute_command
+allowed-tools: ext_skill, ext_call, mcp_reload, mcp_list_servers, mcp_set_enabled, Read, Write, Edit, Glob, Grep, execute_command
 ---
 
 # MCP Usage Guide
 
-> How to use MCP tools in this environment.
+> MCP 工具已统一通过 `ext_call` / `ext_skill` 调用，每个 MCP 服务器自动注册为 `mcp:<servername>` 扩展。
 
 ---
 
-## 1. Available Tools
+## 1. 核心概念
 
-### mcp_list_servers
-
-列出所有已连接的 MCP 服务器及其工具。
+每个 MCP 服务器（如 `designmd`、`fetch`）启动后会自动注册为扩展插件 `mcp:<servername>`。
+其原始工具直接挂在该扩展下，**无需 `mcp_call` 中转**。
 
 ```
-mcp_list_servers()
+mcp:<servername>
+  ├── <tool1>: 描述...
+  ├── <tool2>: 描述...
+  └── <tool3>: 描述...
 ```
 
-返回示例：
+## 2. 调用模式
 
-```json
-{
-  "success": true,
-  "servers": [{ "name": "fetch", "tools": [{ "name": "fetch", "description": "..." }] }]
-}
-```
-
-### mcp_tool_schema
-
-查询工具的完整参数结构，直接返回可复制的调用示例。
+### 2.1 标准三步走（推荐）
 
 ```
-mcp_tool_schema({ server: "服务器名", tool: "工具名" })
+// 1. 查询参数说明
+ext_skill({ plugin: "mcp:<servername>" })
+
+// 2. 根据返回的参数定义调用
+ext_call({
+  plugin: "mcp:<servername>",
+  tool: "<tool_name>",
+  args: { "参数名": "参数值", ... }
+})
 ```
 
-返回示例：
+### 2.2 简单调用（已知参数）
 
-```json
-{
-  "success": true,
-  "result": {
-    "name": "fetch",
-    "description": "Fetches a URL from the internet...",
-    "required": ["url"],
-    "example": "{\"url\": \"https://example.com\"}",
-    "fullExample": "mcp_call({ server: \"fetch\", tool: \"fetch\", args_json: '{\"url\": \"https://...\"}' })"
-  }
-}
+```
+ext_call({
+  plugin: "mcp:designmd",
+  tool: "search_design_kits",
+  args: { query: "dark", limit: 5 }
+})
 ```
 
-### mcp_call
-
-调用 MCP 服务器的工具。
+### 2.3 嵌套参数
 
 ```
-mcp_call({
-  server: "服务器名",
-  tool: "工具名",
-  args_json: '{"参数名": "参数值"}'
+ext_call({
+  plugin: "mcp:designmd",
+  tool: "search_design_kits",
+  args: {
+    query: "minimal",
+    tags: ["dark", "saas"],
+    sort: "trending",
+    limit: 10
+  }
 })
 ```
 
-**重要**：
+---
 
-- `args_json` 必须是有效的 JSON 字符串
-- 必填参数不能为空
-- 如果不知道参数结构，先用 `mcp_tool_schema` 查询
+## 3. 管理工具
 
-### mcp_reload
+### mcp_list_servers
 
-重新加载 MCP 配置。当 `.foliko/mcp_config.json` 修改后使用。
+列出所有 MCP 服务器及其连接状态。
 
 ```
-mcp_reload()
+mcp_list_servers()
 ```
 
----
-
-## 2. Calling Patterns
+### mcp_reload
 
-### 简单参数调用
+重新加载 `.foliko/mcp_config.json` 配置。
 
-```javascript
-// 调用 fetch 工具获取网页
-mcp_call({
-  server: 'fetch',
-  tool: 'fetch',
-  args_json: '{"url": "https://news.baidu.com"}',
-});
 ```
-
-### 多个参数调用
-
-```javascript
-// 调用搜索工具
-mcp_call({
-  server: 'bing-cn-mcp-server',
-  tool: 'bing_search',
-  args_json: '{"query": "关键词", "count": 10}',
-});
+mcp_reload()
 ```
 
-### 复杂参数调用
-
-对于复杂参数（嵌套对象、数组等）：
+### mcp_set_enabled
 
-1. 先查询参数结构：
+动态开启/关闭某个 MCP 服务器（关闭时对应的 `mcp:<server>` 扩展也会注销）。
 
 ```
-mcp_tool_schema({ server: "服务器", tool: "工具" })
+mcp_set_enabled({ server: "designmd", enabled: false })
 ```
 
-2. 根据返回的 `example` 或 `fullExample` 构造调用
-
 ---
 
-## 3. Error Handling
-
-### 参数为空
+## 4. 错误处理
 
-如果忘记传参数，会返回错误：
+### 插件不存在
 
 ```json
-{
-  "success": false,
-  "error": "参数为空！必须提供: url",
-  "hint": "正确格式: {\"url\": \"具体值\"}"
-}
+{ "success": false, "error": "扩展插件 'mcp:foo' 不存在" }
 ```
 
-### 参数格式错误
+→ 先调用 `mcp_list_servers()` 确认服务器名是否正确
 
-如果 JSON 格式不正确：
+### 参数缺失或类型错误
 
-```json
-{
-  "success": false,
-  "error": "args_json 格式错误，不是有效的 JSON"
-}
-```
+→ 调用 `ext_skill({ plugin: "mcp:<server>" })` 查看参数定义
 
-### 服务器不存在
+### 服务器连接失败
 
-```json
-{
-  "success": false,
-  "error": "MCP server 'xxx' not found"
-}
-```
+→ 检查 `.foliko/mcp_config.json` 配置，或调用 `mcp_reload()` 重试
 
 ---
 
-## 4. Configuration
+## 5. 配置
 
 MCP 服务器配置在 `.foliko/mcp_config.json`：
 
 ```json
 {
   "mcpServers": {
-    "服务器名": {
-      "type": "sse",
-      "url": "https://...",
-      "headers": {
-        "Authorization": "Bearer xxx"
-      }
+    "designmd": {
+      "enabled": true,
+      "command": "npx",
+      "args": ["designmd-mcp"],
+      "env": { "DESIGNMD_API_KEY": "xxx" }
     }
   }
 }
 ```
 
-添加或修改配置后，调用 `mcp_reload()` 重载。
+`enabled: false` 的服务器不会自动连接；可通过 `mcp_set_enabled` 动态开启。
 
 ---
 
-## 5. Best Practices
+## 6. Best Practices
 
-- [ ] 不知道参数时，先用 `mcp_tool_schema` 查询
-- [ ] `args_json` 必须是有效的 JSON 字符串（用单引号包裹整个 JSON）
-- [ ] 必填参数必须提供
+- [ ] 不确定参数时先调用 `ext_skill({ plugin: "mcp:<server>" })`
+- [ ] 参数值遵守 JSON 格式（注意引号）
 - [ ] 修改配置后用 `mcp_reload()` 重载
-- [ ] 使用前先 `mcp_list_servers` 查看可用服务器
+- [ ] 调用前可先 `mcp_list_servers()` 确认服务器状态
+- [ ] args 直接传对象，不要序列化成字符串
 
 ---
 
-## 6. Quick Reference
+## 7. Quick Reference
 
-| 场景           | 操作                                                    |
-| -------------- | ------------------------------------------------------- |
-| 查看可用服务器 | `mcp_list_servers()`                                    |
-| 查询参数结构   | `mcp_tool_schema({ server: "x", tool: "y" })`           |
-| 调用工具       | `mcp_call({ server: "x", tool: "y", args_json: '{}' })` |
-| 重载配置       | `mcp_reload()`                                          |
+| 场景           | 操作                                                       |
+| -------------- | ---------------------------------------------------------- |
+| 查看服务器列表 | `mcp_list_servers()`                                       |
+| 查询参数说明   | `ext_skill({ plugin: "mcp:<server>" })`                    |
+| 调用工具       | `ext_call({ plugin: "mcp:<server>", tool: "x", args: {} })` |
+| 重载配置       | `mcp_reload()`                                             |
+| 启停服务器     | `mcp_set_enabled({ server: "x", enabled: true })`          |
 
 ---
 
-> **Tip:** 当工具调用失败时，仔细阅读错误信息，它会告诉你缺少什么参数或格式问题。
+> **Tip:** MCP 工具的 `args` 是普通对象，不需要像旧版那样序列化成 JSON 字符串。

package/skills/plugins/SKILL.md

@@ -15,13 +15,99 @@ Foliko 支持两种插件开发方式：
 | **function(foliko)** | `module.exports = function(foliko) {}` | `.foliko/plugins/*.js` |
 | **类式插件** | `class MyPlugin extends Plugin {}` | `.foliko/plugins/*/index.js` |
 
-推荐使用 **function(foliko)** 方式，更简洁直观。
+**推荐使用类式插件**，支持更完善的生命周期管理（disable/enable 时自动处理工具/扩展）。
 
 ---
 
-## 快速开始
+## 快速开始 - 类式插件（推荐）
 
-创建 `.foliko/plugins/my-plugin.js`：
+创建 `.foliko/plugins/my-plugin/index.js`：
+
+```javascript
+const { Plugin } = require('foliko');
+
+class MyPlugin extends Plugin {
+  name = 'my-plugin';
+  version = '1.0.0';
+  description = '我的插件';
+
+  onStart(framework) {
+    // 注册 AI SDK 工具（直接调用）
+    this.tool.register({
+      name: 'hello',
+      description: '打招呼',
+      inputSchema: framework.z.object({
+        name: framework.z.string().describe('姓名')
+      }),
+      execute: async (args) => ({ message: `Hello, ${args.name}!` }),
+    });
+
+    // 注册扩展工具（通过 ext_call 调用）
+    this.extension.register({
+      name: 'greet',
+      description: '打招呼扩展',
+      inputSchema: framework.z.object({
+        name: framework.z.string()
+      }),
+      execute: async (args) => ({ message: `Hi, ${args.name}!` }),
+    });
+  }
+}
+
+module.exports = MyPlugin;
+```
+
+### 类式插件生命周期
+
+| 方法 | 调用时机 | 用途 |
+|------|----------|------|
+| `onStart(framework)` | start/enable/reload | 注册工具、扩展、子代理 |
+| `onStop()` | disable | 清理资源（工具/扩展基类自动处理） |
+| `onCwdChanged(oldCwd, newCwd, framework)` | 工作目录变更 | 更新资源路径 |
+
+### 工具/扩展自动管理
+
+| 操作 | 效果 |
+|------|------|
+| `disable` | 自动移除工具/扩展（保留注册记录） |
+| `enable` | 自动重新注册工具/扩展 |
+| `reload` | 移除后重新注册 |
+| `uninstall` | 移除并清空注册记录 |
+
+### 手动操作
+
+```javascript
+// 注册
+this.tool.register({ name: 'xxx', ... });
+this.extension.register({ name: 'xxx', ... });
+
+// 移除
+this.tool.remove('xxx');
+this.extension.remove('xxx');
+
+// 执行
+const r1 = await this.tool.execute('any-tool', { arg: 'value' });  // 执行任何已注册工具
+const r2 = await this.extension.execute('xxx', { arg: 'value' });  // 执行当前插件的扩展
+const r3 = await this.extension.execute('plugin-name', 'xxx', { arg: 'value' }); // 执行指定插件的扩展
+
+// 工作流
+this.workflow.register('my-workflow', { name: 'my-workflow', steps: [...] });
+const result = await this.workflow.execute('my-workflow', { input: 'value' });
+this.workflow.remove('my-workflow');
+
+// 子代理
+this.agent.register({ name: 'my-agent', role: '助手', goal: '描述' });
+const agent = this.agent.get('my-agent');
+this.agent.remove('my-agent');
+
+// Prompt
+this.prompt.register('my-prompt', () => 'content', { scope: 'global' });
+this.prompt.remove('my-prompt');
+```
+
+---
+
+## 快速开始 - function(foliko)
 
 ```javascript
 /**