foliko 2.0.4 → 2.0.6

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
 /**

package/skills/python/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: python-plugin-dev
-description: Python 插件开发指南。当用户说"创建 Python 插件"、"用 Python 写插件"时立即调用此 skill。注意：只适合python 开发插件
+description: Python 插件开发指南。当用户说"创建 Python 插件"、"用 Python 写插件"时立即调用此 skill。注意：只适合 python 开发插件
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ---
 
@@ -8,44 +8,40 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 
 ## ext_call 调用方式
 
-通过 `ext_call` 工具调用 Python 插件：
+每个 Python 插件自动注册为独立扩展 `python:<插件名>`，通过 `ext_call` + `ext_skill` 统一调用：
 
 ```javascript
+// 1. 先查询参数
+ext_skill({ plugin: "python:<插件名>" })
+
+// 2. 用结构化对象参数调用
 ext_call({
-  plugin: "插件名",    // 插件名称（必须）
-  tool: "工具名",      // 工具名称（必须）
-  args: {...}          // 工具参数（必须）
+  plugin: "python:<插件名>",   // 格式：python:<插件名>
+  tool: "<工具名>",              // 纯工具名（不带插件名前缀）
+  args: { /* Zod 结构化参数 */ }
 });
 ```
 
-**注意**：插件下的工具调用时，`tool` 参数格式为：
-
-- 如果工具名是 `query_data`，插件名是 `test_nested_plugin`
-- 调用时：`plugin: "python"`, `tool: "test_nested_plugin_query_data"`
-- 即：自动将 `插件名_工具名` 合并为 `tool` 参数
-
 **示例**：
 
 ```javascript
-// 插件名: test-plugin, 工具名: hello
+// 插件名: my-plugin, 工具名: hello
 ext_call({
-  plugin: 'python',
-  tool: 'test-plugin_hello',
+  plugin: 'python:my-plugin',
+  tool: 'hello',
   args: { name: 'Foliko' },
 });
 
 // 插件名: test_nested_plugin, 工具名: query_data
 ext_call({
-  plugin: 'python',
-  tool: 'test_nested_plugin_query_data',
+  plugin: 'python:test_nested_plugin',
+  tool: 'query_data',
   args: { filter: { name: 'Alice' } },
 });
 ```
 
 ## 概述
 
-## 概述
-
 Python 插件允许用 Python 语言开发工具，插件代码运行在 Python 环境中，可以调用所有 Python 库。
 
 ## 插件存放位置
@@ -105,11 +101,12 @@ def calc(params):
     return {"success": True, "result": result}
 ```
 
-**重要**：`tools` 字段定义了插件提供的所有工具。框架会自动：
+**重要**：`TOOLS` 字段定义了插件提供的所有工具。框架会自动：
 
-1. 将这些工具注册到 ExtensionExecutor
-2. 附加到系统提示词【Extensions 扩展工具】部分
-3. 可通过 `ext_call` 调用
+1. 把插件注册为 `python:<插件名>` 扩展
+2. 每个工具作为该扩展下的 tool（tool 名为原始名，不带前缀）
+3. 附加到系统提示词【Extensions 扩展工具】部分
+4. 可通过 `ext_call({ plugin: "python:<插件名>", tool: "<工具名>", args: {...} })` 调用
 
 ## 工具函数规范
 
@@ -135,13 +132,13 @@ def calc(params):
 
 ## 使用方式
 
-通过 `ext_call` 调用：
+通过 `ext_call` 调用（`python:<插件名>` 是固定格式）：
 
 ```javascript
 ext_call({
-  plugin: 'python', // 插件名称
-  tool: 'my-plugin_hello', // 工具名称
-  args: { name: 'Foliko' }, // 工具参数
+  plugin: 'python:my-plugin',     // python:<插件名>
+  tool: 'hello',                   // 纯工具名（不带插件名前缀）
+  args: { name: 'Foliko' },        // 工具参数
 });
 ```
 
@@ -149,7 +146,7 @@ ext_call({
 
 ## 嵌套参数支持
 
-`ext_call` 的 `args` 参数支持多层嵌套结构，可以传递复杂的数据对象：
+`ext_call` 的 `args` 参数支持多层嵌套结构，可以传递复杂的数据对象。
 
 ### 支持的参数类型
 
@@ -167,15 +164,15 @@ ext_call({
 ```javascript
 // 简单参数
 ext_call({
-  plugin: 'python',
-  tool: 'my-plugin_query',
+  plugin: 'python:my-plugin',
+  tool: 'query',
   args: { table: 'users' },
 });
 
 // 嵌套 filter
 ext_call({
-  plugin: 'python',
-  tool: 'my-plugin_query_data',
+  plugin: 'python:my-plugin',
+  tool: 'query_data',
   args: {
     filter: {
       name: 'Alice',
@@ -191,8 +188,8 @@ ext_call({
 
 // 带 options 的复杂查询
 ext_call({
-  plugin: 'python',
-  tool: 'my-plugin_query_data',
+  plugin: 'python:my-plugin',
+  tool: 'query_data',
   args: {
     filter: { status: 'active' },
     options: {
@@ -226,10 +223,9 @@ def query_data(params):
 
 ### 注意事项
 
-1. **参数名简写**：`ext_call` 会将 `my-plugin_tool` 自动简写为 `my-plugin_xxx`
-2. **嵌套深度**：支持任意深度的嵌套对象
-3. **空值处理**：使用 `.get()` 方法并提供默认值，避免 KeyError
-4. **数组对象**：支持数组和嵌套对象的任意组合
+1. **嵌套深度**：支持任意深度的嵌套对象
+2. **空值处理**：使用 `.get()` 方法并提供默认值，避免 KeyError
+3. **数组对象**：支持数组和嵌套对象的任意组合
 
 ## 示例：天气查询插件
 
@@ -274,6 +270,16 @@ def get_weather(params):
         return {"success": False, "error": str(e)}
 ```
 
+调用方式：
+
+```javascript
+ext_call({
+  plugin: 'python:weather',       // python:<插件名>
+  tool: 'get_weather',             // 纯工具名
+  args: { city: '上海' },
+});
+```
+
 ## 示例：文件处理插件
 
 ```python
@@ -330,6 +336,16 @@ def write_file(params):
         return {"success": False, "error": str(e)}
 ```
 
+调用方式：
+
+```javascript
+ext_call({
+  plugin: 'python:file_processor',
+  tool: 'read_file',
+  args: { path: '/tmp/test.txt' },
+});
+```
+
 ## 注意事项
 
 1. **文件格式** - 必须是单个 `.py` 文件
@@ -338,12 +354,14 @@ def write_file(params):
 4. **工具函数名** - 必须与 TOOLS 中定义的 name 一致
 5. **异常处理** - 所有可能出错的地方都要 try-except
 6. **编码** - 文件使用 UTF-8 编码
+7. **命名空间** - 扩展名格式为 `python:<PLUGIN.name>`，工具名是 `TOOLS[].name`（不带前缀）
 
 ## 开发流程
 
 1. **编写插件代码** - 在 `.foliko/plugins/` 下创建 `.py` 文件
-2. **自动加载** - 框架启动时自动注册工具
-3. **调试** - 查看返回的 `success` 和 `error` 信息
+2. **自动加载** - 框架启动时自动注册到 `python:<插件名>` 扩展
+3. **测试** - 在聊天中用 `/<插件名>:<工具名>` 测试，或让 LLM 用 `ext_call` 调用
+4. **调试** - 查看返回的 `success` 和 `error` 信息
 
 ## 常用 Python 库