foliko 1.0.68 → 1.0.69

package/skills/workflow-troubleshooting/SKILL.md

@@ -0,0 +1,314 @@
+---
+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` 类型 |