foliko 2.0.5 → 2.0.6

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 库
 

package/skills/skill-guide/SKILL.md

@@ -176,13 +176,17 @@ module.exports = [
 
 ### ext_call 调用格式
 
-当需要通过 AI 调用 skill 命令时，使用 `ext_call` 工具：
+每个 skill 自动注册为 `skill:<技能名>` 扩展，通过 `ext_call` + `ext_skill` 统一调用。
 
 ```javascript
+// 1. 先查询命令参数
+ext_skill({ plugin: "skill:<技能名>" })
+
+// 2. 用命令行字符串调用
 ext_call({
-  plugin: "skill",
-  tool: "<skillname>:<commandname>",
-  args: { command: "<命令行>" }
+  plugin: "skill:<技能名>",
+  tool: "<commandname>",
+  args: { command: "-n Alice -l en" }
 });
 ```
 
@@ -190,31 +194,31 @@ ext_call({
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
-| `plugin` | string | 固定为 `"skill"` |
-| `tool` | string | 格式为 `<技能名>:<命令名>`，如 `test-skill:greet` |
-| `args.command` | string | 命令行参数字符串 |
+| `plugin` | string | 固定为 `"skill:<技能名>"`，如 `skill:test-skill` |
+| `tool` | string | 命令名（不带技能前缀），如 `greet` |
+| `args` | object | 固定为 `{ command: "命令行字符串" }` |
 
 **示例：**
 
 ```javascript
-// 调用 test-skill 的 greet 命令，无参数
+// 调用 test-skill 的 greet 命令
 ext_call({
-  plugin: "skill",
-  tool: "test-skill:greet",
-  args: { command: "" }
+  plugin: "skill:test-skill",
+  tool: "greet",
+  args: { command: "-n Alice" }
 });
 
-// 调用 test-skill 的 greet 命令，带参数
+// 调用 test-skill 的 greet 命令，带可选 lang
 ext_call({
-  plugin: "skill",
-  tool: "test-skill:greet",
-  args: { command: "Alice" }
+  plugin: "skill:test-skill",
+  tool: "greet",
+  args: { command: "-n Alice -l en" }
 });
 
 // 调用 test-skill 的 echo 命令
 ext_call({
-  plugin: "skill",
-  tool: "test-skill:echo",
+  plugin: "skill:test-skill",
+  tool: "echo",
   args: { command: "Hello World" }
 });
 ```
@@ -383,13 +387,17 @@ module.exports = [
 
 ### ext_call 调用格式
 
-当需要通过 AI 调用 skill 命令时，使用 `ext_call` 工具：
+每个 skill 自动注册为 `skill:<技能名>` 扩展，通过 `ext_call` + `ext_skill` 统一调用。
 
 ```javascript
+// 1. 先查询命令参数
+ext_skill({ plugin: "skill:<技能名>" })
+
+// 2. 用命令行字符串调用
 ext_call({
-  plugin: "skill",
-  tool: "<skillname>:<commandname>",
-  args: { command: "<命令行>" }
+  plugin: "skill:<技能名>",
+  tool: "<commandname>",
+  args: { command: "-n Alice -l en" }
 });
 ```
 
@@ -397,31 +405,31 @@ ext_call({
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
-| `plugin` | string | 固定为 `"skill"` |
-| `tool` | string | 格式为 `<技能名>:<命令名>`，如 `test-skill:greet` |
-| `args.command` | string | 命令行参数字符串 |
+| `plugin` | string | 固定为 `"skill:<技能名>"`，如 `skill:test-skill` |
+| `tool` | string | 命令名（不带技能前缀），如 `greet` |
+| `args` | object | 固定为 `{ command: "命令行字符串" }` |
 
 **示例：**
 
 ```javascript
-// 调用 test-skill 的 greet 命令，无参数
+// 调用 test-skill 的 greet 命令
 ext_call({
-  plugin: "skill",
-  tool: "test-skill:greet",
-  args: { command: "" }
+  plugin: "skill:test-skill",
+  tool: "greet",
+  args: { command: "-n Alice" }
 });
 
-// 调用 test-skill 的 greet 命令，带参数
+// 调用 test-skill 的 greet 命令，带可选 lang
 ext_call({
-  plugin: "skill",
-  tool: "test-skill:greet",
-  args: { command: "Alice" }
+  plugin: "skill:test-skill",
+  tool: "greet",
+  args: { command: "-n Alice -l en" }
 });
 
 // 调用 test-skill 的 echo 命令
 ext_call({
-  plugin: "skill",
-  tool: "test-skill:echo",
+  plugin: "skill:test-skill",
+  tool: "echo",
   args: { command: "Hello World" }
 });
 ```

package/skills/workflows/SKILL.md

@@ -144,6 +144,18 @@ allowed-tools: execute_workflow,workflow_reload
 | `args`           | object | 否   | 工具参数           |
 | `outputVariable` | string | 否   | 结果保存到的变量名 |
 
+**重要：`args` vs `params` 字段**：
+
+工作流引擎使用 `args` 字段传递工具参数，不是 `params`：
+
+```json
+// ✅ 正确
+{ "type": "tool", "tool": "fetch", "args": { "url": "https://..." } }
+
+// ❌ 错误
+{ "type": "tool", "tool": "fetch", "params": { "url": "https://..." } }
+```
+
 **args 中支持变量引用**：
 
 使用 `{{variableName}}` 语法引用 context.variables 中的变量：
@@ -199,9 +211,61 @@ allowed-tools: execute_workflow,workflow_reload
 
 **自动 JSON 解析**：如果字段值是 JSON 字符串，会自动解析为对象后再提取嵌套字段。
 
-### 3. loop - 循环步骤
+### 3. 调用扩展工具（ext_call）
+
+使用 `ext_call` 工具调用插件扩展的命令（如 skill 插件的命令）：
+
+```json
+{
+  "type": "tool",
+  "name": "调用视频创作命令",
+  "tool": "ext_call",
+  "args": {
+    "plugin": "skill:creator",
+    "tool": "creator",
+    "args": {
+      "aspectRatio": "16:9",
+      "title": true,
+      "voice": "female-shaonv-jingpin"
+    }
+  },
+  "outputVariable": "videoId"
+}
+```
+
+**参数说明**：
+
+| 字段    | 类型   | 必填 | 说明                    |
+| ------- | ------ | ---- | ----------------------- |
+| `plugin` | string | 是   | 扩展名（格式：`skill:<技能名>` / `mcp:<server>` / `python:<插件名>`） |
+| `tool`  | string | 是   | 工具名（不带扩展名前缀） |
+| `args`  | object | 是   | Zod 结构化参数（无需拼装命令字符串） |
+
+**调用 skill 命令示例**：
+
+```json
+{
+  "type": "tool",
+  "name": "创建项目",
+  "tool": "ext_call",
+  "args": {
+    "plugin": "skill:creator",
+    "tool": "creator",
+    "args": {
+      "aspectRatio": "16:9",
+      "title": true,
+      "voice": "female-shaonv-jingpin",
+      "audio": true
+    }
+  }
+}
+```
+
+### 4. loop - 循环步骤
+
+支持两种循环模式：
 
-重复执行一组步骤：
+**模式一：固定次数循环**
 
 ```json
 {
@@ -216,7 +280,63 @@ allowed-tools: execute_workflow,workflow_reload
 - `maxIterations`: 最大迭代次数
 - `loopVariable`: 循环计数器变量名（从 0 开始）
 
-### 4. condition - 条件分支
+**模式二：数组迭代循环（over）**
+
+```json
+{
+  "type": "loop",
+  "name": "处理幻灯片",
+  "over": "input.slides",
+  "as": "slide",
+  "index": "slideIndex",
+  "maxIterations": 10,
+  "steps": [
+    {
+      "type": "tool",
+      "tool": "ext_call",
+      "args": {
+        "plugin": "skill:creator",
+        "tool": "addSlide",
+        "args": {
+          "videoId": "{{videoId}}",
+          "slideIndex": "{{slideIndex}}",
+          "bgColor": "{{slide.bgColor}}"
+        }
+      }
+    }
+  ]
+}
+```
+
+- `over`: 要迭代的数组路径（如 `input.slides`、`slide.cards`）
+- `as`: 每个元素的变量名（如 `slide`）
+- `index`: 索引变量名（如 `slideIndex`，从 0 开始）
+- `maxIterations`: 最大迭代次数（可选，默认为数组长度）
+
+**嵌套循环示例**：
+
+```json
+{
+  "type": "loop",
+  "over": "input.slides",
+  "as": "slide",
+  "index": "slideIndex",
+  "steps": [
+    {
+      "name": "处理数据卡片",
+      "type": "loop",
+      "over": "slide.cards",
+      "as": "card",
+      "index": "cardIndex",
+      "steps": [
+        { "type": "tool", "tool": "addCard", "args": { ... } }
+      ]
+    }
+  ]
+}
+```
+
+### 5. condition - 条件分支
 
 根据条件选择执行分支：
 
@@ -239,7 +359,7 @@ allowed-tools: execute_workflow,workflow_reload
 }
 ```
 
-### 5. switch - 开关分支
+### 6. switch - 开关分支
 
 根据值匹配执行对应分支（类似编程语言的 switch-case）：
 
@@ -260,7 +380,7 @@ allowed-tools: execute_workflow,workflow_reload
 - `branches`: 分支数组，匹配第一个 `case` 等于 `value` 的分支
 - `default`: 默认分支（可选）
 
-### 6. try - 异常捕获
+### 7. try - 异常捕获
 
 尝试执行，失败时执行 catch 分支：
 
@@ -284,7 +404,7 @@ allowed-tools: execute_workflow,workflow_reload
 - `try`: 尝试执行的步骤
 - `catch`: 捕获异常后执行的步骤
 
-### 7. parallel - 并行执行
+### 8. parallel - 并行执行
 
 多个步骤同时并行执行：
 
@@ -302,7 +422,7 @@ allowed-tools: execute_workflow,workflow_reload
 
 返回数组形式的执行结果。
 
-### 8. workflow - 嵌套工作流
+### 9. workflow - 嵌套工作流
 
 在一个工作流中调用另一个工作流：
 
@@ -322,7 +442,7 @@ allowed-tools: execute_workflow,workflow_reload
 
 子工作流的输出会合并到父工作流的上下文变量中。
 
-### 9. delay - 延时步骤
+### 10. delay - 延时步骤
 
 等待指定毫秒数：
 
@@ -334,7 +454,7 @@ allowed-tools: execute_workflow,workflow_reload
 }
 ```
 
-### 10. sequential - 顺序步骤
+### 11. sequential - 顺序步骤
 
 将多个步骤组合为顺序执行（可嵌套使用）：
 
@@ -644,3 +764,98 @@ allowed-tools: execute_workflow,workflow_reload
   "default": { "steps": [{ "type": "tool", "tool": "notification_send", "args": {"message": "未知状态"} }] }
 }
 ```
+
+### 示例：ext_call + loop 调用 skill 命令处理列表
+
+**调用 skill 插件命令的正确方式**：
+
+```json
+{
+  "name": "process-videos",
+  "description": "使用 ext_call 调用 skill 命令处理多个视频",
+  "input": {
+    "videos": ["video1.mp4", "video2.mp4", "video3.mp4"]
+  },
+  "steps": [
+    {
+      "type": "script",
+      "name": "初始化",
+      "outputVariable": "videoList",
+      "script": "return context.input.videos || [];"
+    },
+    {
+      "type": "loop",
+      "name": "处理每个视频",
+      "maxIterations": 10,
+      "loopVariable": "i",
+      "steps": [
+        {
+          "type": "condition",
+          "name": "检查是否还有视频",
+          "branches": [
+            {
+              "name": "有视频",
+              "condition": "context.variables.i < context.variables.videoList.length",
+              "steps": [
+                {
+                  "type": "script",
+                  "name": "获取当前视频",
+                  "outputVariable": "currentVideo",
+                  "script": "return context.variables.videoList[context.variables.i];"
+                },
+                {
+                  "type": "tool",
+                  "name": "处理视频",
+                  "tool": "ext_call",
+                  "args": {
+                    "plugin": "skill:creator",
+                    "tool": "addClip",
+                    "args": {
+                      "videoId": "{{videoId}}",
+                      "video": "{{currentVideo}}"
+                    }
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+**关键点**：
+
+1. **使用 `type: "tool"` + `tool: "ext_call"`** 调用扩展命令
+2. **嵌套的 `args` 对象** 包含 `plugin`、`tool`、`args`
+3. **loop 使用 `maxIterations`** 控制最大循环次数
+4. **条件判断使用 `condition`** 字段
+
+### 常见错误
+
+```json
+// ❌ 错误 - 使用 action: "ext_call"（不支持的类型）
+{
+  "name": "createProject",
+  "action": "ext_call",
+  "params": {
+    "plugin": "skill:creator",
+    "tool": "creator",
+    "args": { "aspectRatio": "16:9" }
+  }
+}
+
+// ✅ 正确 - 使用 type: "tool" + tool: "ext_call"
+{
+  "name": "createProject",
+  "type": "tool",
+  "tool": "ext_call",
+  "args": {
+    "plugin": "skill:creator",
+    "tool": "creator",
+    "args": { "aspectRatio": "16:9" }
+  }
+}
+```