# 工作流开发调试指南

## 快速测试工作流

### 1. 使用 execute_workflow 直接测试

```javascript
execute_workflow({
  workflow: {
    name: 'test-workflow',
    description: '测试工作流',
    steps: [
      {
        id: 'step1',
        type: 'tool',
        tool: 'python-execute',
        args: {
          code: "print('Hello from Python!')",
        },
        outputVariable: 'result',
      },
    ],
  },
});
```

### 2. JSON 格式注意事项

- ✅ 使用双引号包裹字符串
- ✅ 确保 JSON 语法正确
- ❌ 避免在 JSON 中使用未转义的特殊字符
- ❌ 不要在 code 中混用单引号和双引号

### 3. 常见错误

```
Unexpected identifier 'xxx'
```

- 原因：JSON 格式错误，可能是引号或逗号问题
- 解决：检查 JSON 语法

```
Unexpected end of JSON input
```

- 原因：模板字符串 `${}` 在 JSON 中导致解析错误
- 解决：不要在 JSON 中使用模板变量，改用纯 Python 代码

## 工作流重载问题

### 问题

添加新工作流后，`reloadWorkflows` 不会重新加载同名工作流。

### 解决

```bash
# 方法1：使用不同的文件名
news-dashboard-v3.json  # 不会被 v2 覆盖

# 方法2：重启插件
reload_plugins()  # 重载所有插件
```

## Python 执行最佳实践

### 1. 错误处理

```python
try:
    req = urllib.request.Request(url, headers={'User-Agent': 'Mozilla/5.0'})
    with urllib.request.urlopen(req, timeout=10) as resp:
        data = resp.read().decode('utf-8')
    print('SUCCESS')
except Exception as e:
    print(f'ERROR: {e}')
    # fallback 逻辑
```

### 2. 输出格式

```python
# 简单输出
print('Status: OK')
print(f'Count: {len(items)}')

# JSON 输出
import json
print('---JSON_START---')
print(json.dumps(data, ensure_ascii=False))
print('---JSON_END---')
```

### 3. 超时设置

```python
with urllib.request.urlopen(req, timeout=30) as resp:  # 30秒超时
    ...
```

## 工作流步骤类型

| 类型        | 用途            | 示例                                  |
| ----------- | --------------- | ------------------------------------- |
| `tool`      | 调用工具        | `python-execute`, `shell`, `get_time` |
| `script`    | 执行 JavaScript | 数据处理、变量操作                    |
| `condition` | 条件分支        | if/else 逻辑                          |
| `loop`      | 循环执行        | 遍历列表                              |
| `delay`     | 延时等待        | 等待指定时间                          |
| `message`   | 消息通知        | 发送通知                              |
| `think`     | LLM 思考        | 反思/分析                             |

## 工具输出变量

### 正确用法

```json
{
  "id": "step1",
  "type": "tool",
  "tool": "get_time",
  "outputVariable": "current_time"
}
```

### 访问输出

```javascript
// 在 script 步骤中
context.input.current_time

// 在下一个 tool 步骤中
${step1.current_time}
```

## 调试技巧

### 1. 打印中间变量

```python
print('Debug - data:', data)
print('Debug - length:', len(data))
```

### 2. 保存到文件

```python
with open('debug.log', 'w') as f:
    f.write(str(data))
```

### 3. 逐步执行

```javascript
{
  "steps": [
    { "id": "step1", ... },  // 先测试 step1
    { "id": "step2", ... }   // 确认 step1 成功后添加
  ]
}
```

## 性能优化

### 1. 合并步骤

```javascript
// ❌ 多个小步骤
{ "id": "step1", "tool": "python-execute", "code": "a = 1" }
{ "id": "step2", "tool": "python-execute", "code": "b = 2" }

// ✅ 单个大步骤
{ "id": "step1", "tool": "python-execute", "code": "a = 1; b = 2; print(a + b)" }
```

### 2. 减少变量传递

```javascript
// ❌ 多步骤传递
{ "outputVariable": "data1" }
{ "outputVariable": "data2" }

// ✅ 单步骤完成
{ "outputVariable": "final_result" }
```

### 3. 超时设置

```json
{
  "args": {
    "code": "...",
    "timeout": 60000 // 60秒超时
  }
}
```
