foliko 2.0.2 → 2.0.3

package/skills/{workflow-troubleshooting → workflows/workflow-troubleshooting}/SKILL.md

@@ -1,391 +1,391 @@
----
-name: workflow-troubleshooting
-description: 工作流故障排除与修复指南。当工作流执行失败、fetch 工具不可用、模板变量问题时调用此技能。
-allowed-tools: python-executor, shell, read_file, write_file, execute_workflow, fetch
----
-
-# 工作流故障排除指南
-
-## 常见问题与解决方案
-
-### 1. fetch 工具可用 ✅
-
-**好消息**: 工作流引擎**支持** `fetch` 工具！可以直接在 steps 中使用：
-
-```yaml
-steps:
-  - type: tool
-    name: fetch
-    params:
-      url: 'https://news.baidu.com'
-      timeout: 10000
-    output: 'baidu_news'
-```
-
-**优势**:
-
-- 原生支持，无需额外 sandbox 配置
-- 语法简洁
-- 自动处理超时和错误
-
-### 2. 多个 fetch 步骤串联
-
-**已验证可用**:
-
-```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'
-
-  - type: tool
-    name: fetch
-    params:
-      url: 'https://www.reddit.com/r/popular/hot.json?limit=20'
-    output: 'reddit_news'
-```
-
-### 3. Python 脚本获取结果
-
-**正确方式**: Python 脚本返回 JSON 格式字符串
-
-```python
-import json
-import requests
-
-result = {"news": ["标题1", "标题2"]}
-print(json.dumps(result))  # 输出 JSON 字符串
-```
-
-### 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))
-```
-
-### 网络不稳定时加代理
-
-```yaml
-- type: 'tool'
-  name: 'fetch'
-  params:
-    url: 'https://feeds.bbci.co.uk/news/world/rss.xml'
-    timeout: 15000
-    proxy: true # 失败时自动启用
-  output: 'bbc_news'
-```
-
-## 复杂工作流步骤类型测试 ✅
-
-以下步骤类型已通过完整测试验证：
-
-### 1. parallel (并行执行) ✅
-
-多个任务同时执行，提高效率：
-
-```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": "tool",
-      "name": "fetch",
-      "params": { "url": "https://news.baidu.com" },
-      "output": "news"
-    }
-  ]
-}
-```
-
-### 2. condition (条件分支) ✅
-
-支持 if/else 逻辑判断：
-
-```json
-{
-  "type": "condition",
-  "if": { "key": "$.context.storage_result", "equals": "success" },
-  "then": [
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "成功", "message": "条件成立" }
-    }
-  ],
-  "else": [
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "失败", "message": "条件不成立" }
-    }
-  ]
-}
-```
-
-**支持的操作符**：`equals`, `not_equals`, `contains`, `greater_than`, `less_than`, `exists`, `not_exists`
-
-### 3. loop (循环执行) ✅
-
-支持指定次数的循环：
-
-```json
-{
-  "type": "loop",
-  "count": 3,
-  "steps": [
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "循环", "message": "第 {{index}} 次" }
-    }
-  ]
-}
-```
-
-### 4. switch (多分支) ✅
-
-类似 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": "默认" } }]
-}
-```
-
-### 5. try-catch (错误处理) ✅
-
-捕获步骤执行中的错误，防止中断：
-
-```json
-{
-  "type": "try",
-  "steps": [{ "type": "tool", "name": "email_unread_count" }],
-  "catch": [
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "捕获错误", "message": "邮件服务超时，使用备用方案" }
-    }
-  ]
-}
-```
-
-### 6. delay (延迟执行) ✅
-
-在步骤之间添加延迟：
-
-```json
-{
-  "type": "delay",
-  "ms": 500
-}
-```
-
-### 7. nested workflow (嵌套工作流) ✅
-
-在主工作流中调用子工作流：
-
-```json
-{
-  "type": "workflow",
-  "name": "workflow_file-backup",
-  "input": {}
-}
-```
-
-### 8. context (上下文变量) ✅
-
-在步骤间传递数据：
-
-```json
-{
-  "type": "context",
-  "key": "workflow_status",
-  "value": "completed"
-}
-```
-
-## 复杂工作流完整示例
-
-```json
-{
-  "name": "complex-workflow-demo",
-  "input": {},
-  "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": "condition",
-      "if": { "key": "$.context.storage", "exists": true },
-      "then": [
-        {
-          "type": "tool",
-          "name": "notification_send",
-          "params": { "title": "开始", "message": "工作流启动" }
-        }
-      ]
-    },
-    { "type": "delay", "ms": 300 },
-    {
-      "type": "loop",
-      "count": 2,
-      "steps": [
-        {
-          "type": "tool",
-          "name": "notification_send",
-          "params": { "title": "循环", "message": "第 {{index}} 次" }
-        }
-      ]
-    },
-    {
-      "type": "switch",
-      "value": "$.context.storage",
-      "cases": [
-        {
-          "value": "started",
-          "steps": [
-            {
-              "type": "tool",
-              "name": "notification_send",
-              "params": { "title": "状态", "message": "已开始" }
-            }
-          ]
-        }
-      ],
-      "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": "workflow", "name": "workflow_file-backup", "input": {} },
-    {
-      "type": "tool",
-      "name": "notification_send",
-      "params": { "title": "完成", "message": "复杂工作流执行成功" }
-    }
-  ]
-}
-```
-
-## 关键结论
-
-| 场景         | 推荐方案                     |
-| ------------ | ---------------------------- |
-| 获取网络数据 | ✅ `fetch` 工具              |
-| 本地脚本处理 | ✅ `python` 类型 + JSON 输出 |
-| 接收外部请求 | `webhook` 类型（需服务运行） |
-| 串行任务     | ✅ 多个 `tool`/`python` 步骤 |
-| 并行任务     | ✅ `parallel` 类型           |
-| 条件分支     | ✅ `condition` 类型          |
-| 循环执行     | ✅ `loop` 类型               |
-| 多分支选择   | ✅ `switch` 类型             |
-| 错误处理     | ✅ `try-catch` 类型          |
-| 延迟等待     | ✅ `delay` 类型              |
-| 子工作流调用 | ✅ `workflow` 类型           |
+---
+name: workflow-troubleshooting
+description: 工作流故障排除与修复指南。当工作流执行失败、fetch 工具不可用、模板变量问题时调用此技能。
+allowed-tools: python-executor, shell, read_file, write_file, execute_workflow, fetch
+---
+
+# 工作流故障排除指南
+
+## 常见问题与解决方案
+
+### 1. fetch 工具可用 ✅
+
+**好消息**: 工作流引擎**支持** `fetch` 工具！可以直接在 steps 中使用：
+
+```yaml
+steps:
+  - type: tool
+    name: fetch
+    params:
+      url: 'https://news.baidu.com'
+      timeout: 10000
+    output: 'baidu_news'
+```
+
+**优势**:
+
+- 原生支持，无需额外 sandbox 配置
+- 语法简洁
+- 自动处理超时和错误
+
+### 2. 多个 fetch 步骤串联
+
+**已验证可用**:
+
+```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'
+
+  - type: tool
+    name: fetch
+    params:
+      url: 'https://www.reddit.com/r/popular/hot.json?limit=20'
+    output: 'reddit_news'
+```
+
+### 3. Python 脚本获取结果
+
+**正确方式**: Python 脚本返回 JSON 格式字符串
+
+```python
+import json
+import requests
+
+result = {"news": ["标题1", "标题2"]}
+print(json.dumps(result))  # 输出 JSON 字符串
+```
+
+### 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))
+```
+
+### 网络不稳定时加代理
+
+```yaml
+- type: 'tool'
+  name: 'fetch'
+  params:
+    url: 'https://feeds.bbci.co.uk/news/world/rss.xml'
+    timeout: 15000
+    proxy: true # 失败时自动启用
+  output: 'bbc_news'
+```
+
+## 复杂工作流步骤类型测试 ✅
+
+以下步骤类型已通过完整测试验证：
+
+### 1. parallel (并行执行) ✅
+
+多个任务同时执行，提高效率：
+
+```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": "tool",
+      "name": "fetch",
+      "params": { "url": "https://news.baidu.com" },
+      "output": "news"
+    }
+  ]
+}
+```
+
+### 2. condition (条件分支) ✅
+
+支持 if/else 逻辑判断：
+
+```json
+{
+  "type": "condition",
+  "if": { "key": "$.context.storage_result", "equals": "success" },
+  "then": [
+    {
+      "type": "tool",
+      "name": "notification_send",
+      "params": { "title": "成功", "message": "条件成立" }
+    }
+  ],
+  "else": [
+    {
+      "type": "tool",
+      "name": "notification_send",
+      "params": { "title": "失败", "message": "条件不成立" }
+    }
+  ]
+}
+```
+
+**支持的操作符**：`equals`, `not_equals`, `contains`, `greater_than`, `less_than`, `exists`, `not_exists`
+
+### 3. loop (循环执行) ✅
+
+支持指定次数的循环：
+
+```json
+{
+  "type": "loop",
+  "count": 3,
+  "steps": [
+    {
+      "type": "tool",
+      "name": "notification_send",
+      "params": { "title": "循环", "message": "第 {{index}} 次" }
+    }
+  ]
+}
+```
+
+### 4. switch (多分支) ✅
+
+类似 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": "默认" } }]
+}
+```
+
+### 5. try-catch (错误处理) ✅
+
+捕获步骤执行中的错误，防止中断：
+
+```json
+{
+  "type": "try",
+  "steps": [{ "type": "tool", "name": "email_unread_count" }],
+  "catch": [
+    {
+      "type": "tool",
+      "name": "notification_send",
+      "params": { "title": "捕获错误", "message": "邮件服务超时，使用备用方案" }
+    }
+  ]
+}
+```
+
+### 6. delay (延迟执行) ✅
+
+在步骤之间添加延迟：
+
+```json
+{
+  "type": "delay",
+  "ms": 500
+}
+```
+
+### 7. nested workflow (嵌套工作流) ✅
+
+在主工作流中调用子工作流：
+
+```json
+{
+  "type": "workflow",
+  "name": "workflow_file-backup",
+  "input": {}
+}
+```
+
+### 8. context (上下文变量) ✅
+
+在步骤间传递数据：
+
+```json
+{
+  "type": "context",
+  "key": "workflow_status",
+  "value": "completed"
+}
+```
+
+## 复杂工作流完整示例
+
+```json
+{
+  "name": "complex-workflow-demo",
+  "input": {},
+  "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": "condition",
+      "if": { "key": "$.context.storage", "exists": true },
+      "then": [
+        {
+          "type": "tool",
+          "name": "notification_send",
+          "params": { "title": "开始", "message": "工作流启动" }
+        }
+      ]
+    },
+    { "type": "delay", "ms": 300 },
+    {
+      "type": "loop",
+      "count": 2,
+      "steps": [
+        {
+          "type": "tool",
+          "name": "notification_send",
+          "params": { "title": "循环", "message": "第 {{index}} 次" }
+        }
+      ]
+    },
+    {
+      "type": "switch",
+      "value": "$.context.storage",
+      "cases": [
+        {
+          "value": "started",
+          "steps": [
+            {
+              "type": "tool",
+              "name": "notification_send",
+              "params": { "title": "状态", "message": "已开始" }
+            }
+          ]
+        }
+      ],
+      "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": "workflow", "name": "workflow_file-backup", "input": {} },
+    {
+      "type": "tool",
+      "name": "notification_send",
+      "params": { "title": "完成", "message": "复杂工作流执行成功" }
+    }
+  ]
+}
+```
+
+## 关键结论
+
+| 场景         | 推荐方案                     |
+| ------------ | ---------------------------- |
+| 获取网络数据 | ✅ `fetch` 工具              |
+| 本地脚本处理 | ✅ `python` 类型 + JSON 输出 |
+| 接收外部请求 | `webhook` 类型（需服务运行） |
+| 串行任务     | ✅ 多个 `tool`/`python` 步骤 |
+| 并行任务     | ✅ `parallel` 类型           |
+| 条件分支     | ✅ `condition` 类型          |
+| 循环执行     | ✅ `loop` 类型               |
+| 多分支选择   | ✅ `switch` 类型             |
+| 错误处理     | ✅ `try-catch` 类型          |
+| 延迟等待     | ✅ `delay` 类型              |
+| 子工作流调用 | ✅ `workflow` 类型           |