foliko 2.0.4 → 2.0.6

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" }
+  }
+}
+```