---
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` 类型           |
