foliko 2.0.4 → 2.0.6

package/skills/workflows/workflow-troubleshooting/SKILL.md

@@ -1,391 +1,331 @@
 ---
 name: workflow-troubleshooting
-description: 工作流故障排除与修复指南。当工作流执行失败、fetch 工具不可用、模板变量问题时调用此技能。
-allowed-tools: python-executor, shell, read_file, write_file, execute_workflow, fetch
+description: 工作流故障排除与修复指南。当工作流执行失败、工具调用失败、模板变量问题时调用此技能。
+allowed-tools: python-executor, shell, read_file, write_file, execute_workflow, workflow_reload
 ---
 
 # 工作流故障排除指南
 
 ## 常见问题与解决方案
 
-### 1. fetch 工具可用 ✅
+### 1. Unknown step type 错误
 
-**好消息**: 工作流引擎**支持** `fetch` 工具！可以直接在 steps 中使用：
+**原因**：使用了不支持的步骤类型，如 `action: "ext_call"`
 
-```yaml
-steps:
-  - type: tool
-    name: fetch
-    params:
-      url: 'https://news.baidu.com'
-      timeout: 10000
-    output: 'baidu_news'
-```
+**解决方案**：使用 `type: "tool"` + `tool: "ext_call"` 调用扩展工具
 
-**优势**:
+```json
+// ❌ 错误
+{ "action": "ext_call", "params": { ... } }
 
-- 原生支持，无需额外 sandbox 配置
-- 语法简洁
-- 自动处理超时和错误
+// ✅ 正确
+{
+  "type": "tool",
+  "tool": "ext_call",
+  "args": {
+    "plugin": "skill",
+    "tool": "creator:creator",
+    "args": { "command": "-r 16:9" }
+  }
+}
+```
 
-### 2. 多个 fetch 步骤串联
+### 2. 工具参数问题：args vs params
 
-**已验证可用**:
+**原因**：工作流引擎使用 `args` 字段传递工具参数，不是 `params`
 
-```yaml
-steps:
-  - type: tool
-    name: fetch
-    params:
-      url: 'https://news.baidu.com'
-    output: 'baidu_news'
+**解决方案**：
 
-  - type: tool
-    name: fetch
-    params:
-      url: 'https://feeds.bbci.co.uk/news/world/rss.xml'
-    output: 'bbc_news'
+```json
+// ❌ 错误
+{ "type": "tool", "tool": "fetch", "params": { "url": "https://..." } }
 
-  - type: tool
-    name: fetch
-    params:
-      url: 'https://www.reddit.com/r/popular/hot.json?limit=20'
-    output: 'reddit_news'
+// ✅ 正确
+{ "type": "tool", "tool": "fetch", "args": { "url": "https://..." } }
 ```
 
-### 3. Python 脚本获取结果
-
-**正确方式**: Python 脚本返回 JSON 格式字符串
+### 3. loop 循环语法错误
 
-```python
-import json
-import requests
+**正确语法**：
 
-result = {"news": ["标题1", "标题2"]}
-print(json.dumps(result))  # 输出 JSON 字符串
+**固定次数循环**：
+```json
+{
+  "type": "loop",
+  "maxIterations": 10,
+  "loopVariable": "i",
+  "steps": [...]
+}
 ```
 
-### 4. webhook 类型步骤
-
-**警告**: `webhook` 类型需要 HTTP 服务支持，否则会失败。
-
-- 如需接收外部数据，使用 `web_register_webhook` 注册路由
-- 测试时改用 `tool` + `fetch` 组合
-
-### 5. 变量传递问题
-
-- **原因**: sandbox 环境无法访问主环境变量
-- **解决方案**:
-  - 使用上下文变量 `$.context.xxx`
-  - 或直接在脚本中硬编码（测试用）
-
-## 调试技巧
-
-1. **先单独测试每个步骤** - 用简单输入验证
-2. **检查工作流定义语法** - YAML/JSON 格式正确性
-3. **使用简单输入测试变量传递**
-4. **fetch 失败时**: 加 `timeout` 参数，加 `proxy: true` 重试
-
-## 成功案例
-
-### 真实新闻聚合工作流
-
-```yaml
-name: 'news-fetcher'
-steps:
-  - type: 'context'
-    key: 'current_time'
-    value: '$.time.current'
-
-  - type: 'tool'
-    name: 'fetch'
-    params:
-      url: 'https://news.baidu.com'
-      timeout: 15000
-    output: 'baidu_news'
-
-  - type: 'tool'
-    name: 'fetch'
-    params:
-      url: 'https://feeds.bbci.co.uk/news/world/rss.xml'
-      timeout: 15000
-    output: 'bbc_news'
-
-  - type: 'tool'
-    name: 'fetch'
-    params:
-      url: 'https://www.reddit.com/r/popular/hot.json?limit=20'
-      timeout: 15000
-    output: 'reddit_news'
-
-  - type: 'python'
-    script: |
-      import json
-      # 处理新闻数据...
-      result = {"status": "success", "sources": ["baidu", "bbc", "reddit"]}
-      print(json.dumps(result))
+**数组迭代循环（over）**：
+```json
+{
+  "type": "loop",
+  "over": "input.slides",
+  "as": "slide",
+  "index": "slideIndex",
+  "maxIterations": 10,
+  "steps": [...]
+}
 ```
 
-### 网络不稳定时加代理
+- `over`: 要迭代的数组路径
+- `as`: 每个元素的变量名
+- `index`: 索引变量名（从 0 开始）
 
-```yaml
-- type: 'tool'
-  name: 'fetch'
-  params:
-    url: 'https://feeds.bbci.co.uk/news/world/rss.xml'
-    timeout: 15000
-    proxy: true # 失败时自动启用
-  output: 'bbc_news'
-```
-
-## 复杂工作流步骤类型测试 ✅
+- `maxIterations`: 最大迭代次数（必填）
+- `loopVariable`: 循环计数器变量名（默认 `loopIndex`）
+- `steps`: 循环执行的步骤数组
 
-以下步骤类型已通过完整测试验证：
+### 4. condition 条件语法错误
 
-### 1. parallel (并行执行) ✅
+**原因**：使用了不存在的字段如 `if`、`then`
 
-多个任务同时执行，提高效率：
+**正确语法**：
 
 ```json
 {
-  "type": "parallel",
-  "steps": [
-    { "type": "tool", "name": "get_time", "output": "current_time" },
-    {
-      "type": "tool",
-      "name": "storage_set",
-      "params": { "key": "test", "value": "ok" },
-      "output": "storage_result"
-    },
+  "type": "condition",
+  "branches": [
     {
-      "type": "tool",
-      "name": "fetch",
-      "params": { "url": "https://news.baidu.com" },
-      "output": "news"
+      "name": "条件1",
+      "condition": "context.variables.value > 10",
+      "steps": [...]
     }
-  ]
+  ],
+  "defaultBranch": {
+    "steps": [...]
+  }
 }
 ```
 
-### 2. condition (条件分支) ✅
+- `condition`: JavaScript 表达式字符串
+- `branches`: 条件分支数组
+- `defaultBranch`: 默认分支（可选）
+
+### 5. switch 分支语法错误
 
-支持 if/else 逻辑判断：
+**正确语法**：
 
 ```json
 {
-  "type": "condition",
-  "if": { "key": "$.context.storage_result", "equals": "success" },
-  "then": [
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "成功", "message": "条件成立" }
-    }
+  "type": "switch",
+  "value": "{{status}}",
+  "branches": [
+    { "case": "success", "steps": [...] },
+    { "case": "error", "steps": [...] }
   ],
-  "else": [
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "失败", "message": "条件不成立" }
-    }
-  ]
+  "default": { "steps": [...] }
 }
 ```
 
-**支持的操作符**：`equals`, `not_equals`, `contains`, `greater_than`, `less_than`, `exists`, `not_exists`
+- `value`: 要匹配的值，支持 `{{variable}}` 引用
+- `branches`: 分支数组，匹配 `case` 等于 `value` 的分支
+- `default`: 默认分支
 
-### 3. loop (循环执行) ✅
+### 6. try-catch 语法错误
 
-支持指定次数的循环：
+**正确语法**：
 
 ```json
 {
-  "type": "loop",
-  "count": 3,
-  "steps": [
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "循环", "message": "第 {{index}} 次" }
-    }
-  ]
+  "type": "try",
+  "try": {
+    "steps": [
+      { "type": "tool", "tool": "可能失败的工具", "args": {} }
+    ]
+  },
+  "catch": {
+    "steps": [...]
+  }
 }
 ```
 
-### 4. switch (多分支) ✅
+### 7. parallel 并行执行语法
 
-类似 switch-case 的多条件分支：
+**正确语法**：
 
 ```json
 {
-  "type": "switch",
-  "value": "$.context.status",
-  "cases": [
-    {
-      "value": "success",
-      "steps": [{ "type": "tool", "name": "notification_send", "params": { "title": "成功" } }]
-    },
-    {
-      "value": "error",
-      "steps": [{ "type": "tool", "name": "notification_send", "params": { "title": "错误" } }]
-    }
-  ],
-  "default": [{ "type": "tool", "name": "notification_send", "params": { "title": "默认" } }]
+  "type": "parallel",
+  "steps": [
+    { "type": "tool", "tool": "task1", "args": {} },
+    { "type": "tool", "tool": "task2", "args": {} }
+  ]
 }
 ```
 
-### 5. try-catch (错误处理) ✅
+## 调试技巧
+
+### 1. 先单独测试每个步骤
 
-捕获步骤执行中的错误，防止中断：
+创建简单的单步骤工作流验证工具是否可用：
 
 ```json
 {
-  "type": "try",
-  "steps": [{ "type": "tool", "name": "email_unread_count" }],
-  "catch": [
+  "name": "test-tool",
+  "steps": [
     {
       "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "捕获错误", "message": "邮件服务超时，使用备用方案" }
+      "name": "测试",
+      "tool": "notification_send",
+      "args": { "message": "测试消息" }
     }
   ]
 }
 ```
 
-### 6. delay (延迟执行) ✅
-
-在步骤之间添加延迟：
+### 2. 使用 script 步骤调试变量
 
 ```json
 {
-  "type": "delay",
-  "ms": 500
+  "type": "script",
+  "name": "调试变量",
+  "outputVariable": "debug",
+  "script": "return JSON.stringify(context.variables, null, 2);"
 }
 ```
 
-### 7. nested workflow (嵌套工作流) ✅
-
-在主工作流中调用子工作流：
+### 3. 检查工具是否存在
 
-```json
-{
-  "type": "workflow",
-  "name": "workflow_file-backup",
-  "input": {}
-}
-```
+使用 `workflow_list` 工具查看所有已注册的工作流工具。
 
-### 8. context (上下文变量) ✅
+### 4. 变量引用格式
 
-在步骤间传递数据：
+| 格式 | 说明 |
+| ---- | ---- |
+| `{{result}}` | 上一步完整结果 |
+| `{{result.field}}` | 从结果提取字段 |
+| `{{lastResult}}` | result 的别名 |
+| `{{variables.x}}` | 显式引用 variables |
+| `{{input.x}}` | 引用工作流输入 |
+| `${stepId.output}` | 引用指定步骤输出（兼容旧格式） |
 
-```json
-{
-  "type": "context",
-  "key": "workflow_status",
-  "value": "completed"
-}
-```
+## 完整工作流示例
 
-## 复杂工作流完整示例
+### 示例：使用 ext_call 调用 skill 命令
 
 ```json
 {
-  "name": "complex-workflow-demo",
-  "input": {},
+  "name": "video-creator",
+  "description": "视频创作工作流示例",
+  "input": {
+    "title": "测试视频",
+    "slides": ["slide1", "slide2"]
+  },
   "steps": [
     {
-      "type": "parallel",
-      "steps": [
-        { "type": "tool", "name": "get_time", "output": "time" },
-        {
-          "type": "tool",
-          "name": "storage_set",
-          "params": { "key": "status", "value": "started" },
-          "output": "storage"
-        },
-        { "type": "tool", "name": "storage_list", "output": "namespaces" }
-      ]
+      "type": "tool",
+      "name": "创建项目",
+      "tool": "ext_call",
+      "args": {
+        "plugin": "skill",
+        "tool": "creator:creator",
+        "args": {
+          "command": "-r 16:9 -t true -v female-shaonv-jingpin"
+        }
+      },
+      "outputVariable": "videoId"
     },
     {
-      "type": "condition",
-      "if": { "key": "$.context.storage", "exists": true },
-      "then": [
-        {
-          "type": "tool",
-          "name": "notification_send",
-          "params": { "title": "开始", "message": "工作流启动" }
+      "type": "tool",
+      "name": "添加片头",
+      "tool": "ext_call",
+      "args": {
+        "plugin": "skill",
+        "tool": "creator:addCover",
+        "args": {
+          "command": "-i {{videoId}} -t '{{input.title}}'"
         }
-      ]
+      }
     },
-    { "type": "delay", "ms": 300 },
     {
       "type": "loop",
-      "count": 2,
+      "name": "添加幻灯片",
+      "maxIterations": 10,
+      "loopVariable": "i",
       "steps": [
         {
-          "type": "tool",
-          "name": "notification_send",
-          "params": { "title": "循环", "message": "第 {{index}} 次" }
-        }
-      ]
-    },
-    {
-      "type": "switch",
-      "value": "$.context.storage",
-      "cases": [
-        {
-          "value": "started",
-          "steps": [
+          "type": "condition",
+          "name": "检查是否还有幻灯片",
+          "branches": [
             {
-              "type": "tool",
-              "name": "notification_send",
-              "params": { "title": "状态", "message": "已开始" }
+              "name": "有幻灯片",
+              "condition": "context.variables.i < context.input.slides.length",
+              "steps": [
+                {
+                  "type": "tool",
+                  "name": "添加幻灯片",
+                  "tool": "ext_call",
+                  "args": {
+                    "plugin": "skill",
+                    "tool": "creator:addSlide",
+                    "args": {
+                      "command": "-i {{videoId}} -n {{i}}"
+                    }
+                  }
+                }
+              ]
             }
           ]
         }
-      ],
-      "default": [
-        {
-          "type": "tool",
-          "name": "notification_send",
-          "params": { "title": "状态", "message": "默认状态" }
-        }
       ]
     },
     {
-      "type": "try",
-      "steps": [{ "type": "tool", "name": "email_unread_count" }],
-      "catch": [
-        {
-          "type": "tool",
-          "name": "notification_send",
-          "params": { "title": "错误处理", "message": "捕获异常完成" }
+      "type": "tool",
+      "name": "渲染视频",
+      "tool": "ext_call",
+      "args": {
+        "plugin": "skill",
+        "tool": "creator:render",
+        "args": {
+          "command": "-i {{videoId}} -o output.mp4"
         }
-      ]
+      }
+    }
+  ]
+}
+```
+
+## 快速修复清单
+
+| 问题 | 修复 |
+| ---- | ---- |
+| `Unknown step type: ext_call` | 改用 `type: "tool"` + `tool: "ext_call"` |
+| 工具参数不传递 | 将 `params` 改为 `args` |
+| loop 不执行 | 检查 `maxIterations` 和 `steps` 字段 |
+| condition 不生效 | 使用 `condition` 字段，不是 `if` |
+| switch 不匹配 | 确保有 `default` 分支兜底 |
+| 变量引用失败 | 使用 `{{result}}` 而非 `${result}` |
+
+## 成功案例
+
+### 视频创作工作流（已验证）
+
+```json
+{
+  "name": "hot-news-video",
+  "steps": [
+    {
+      "type": "tool",
+      "tool": "ext_call",
+      "args": {
+        "plugin": "skill",
+        "tool": "creator:creator",
+        "args": { "command": "-r 16:9 -t true -v female-shaonv-jingpin" }
+      },
+      "outputVariable": "videoId"
     },
-    { "type": "workflow", "name": "workflow_file-backup", "input": {} },
     {
       "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "完成", "message": "复杂工作流执行成功" }
+      "tool": "ext_call",
+      "args": {
+        "plugin": "skill",
+        "tool": "creator:addCover",
+        "args": { "command": "-i {{videoId}} -t '{{input.title}}'" }
+      }
     }
   ]
 }
 ```
-
-## 关键结论
-
-| 场景         | 推荐方案                     |
-| ------------ | ---------------------------- |
-| 获取网络数据 | ✅ `fetch` 工具              |
-| 本地脚本处理 | ✅ `python` 类型 + JSON 输出 |
-| 接收外部请求 | `webhook` 类型（需服务运行） |
-| 串行任务     | ✅ 多个 `tool`/`python` 步骤 |
-| 并行任务     | ✅ `parallel` 类型           |
-| 条件分支     | ✅ `condition` 类型          |
-| 循环执行     | ✅ `loop` 类型               |
-| 多分支选择   | ✅ `switch` 类型             |
-| 错误处理     | ✅ `try-catch` 类型          |
-| 延迟等待     | ✅ `delay` 类型              |
-| 子工作流调用 | ✅ `workflow` 类型           |