---
name: workflow
description: 工作流引擎 - 定义和执行结构化工作流，支持顺序、条件分支、循环、延迟、工具调用等步骤类型
allowed-tools: execute_workflow,reloadWorkflows
---

# Workflow 工作流

工作流引擎用于定义和执行结构化的工作流程，支持多种步骤类型，可以组合使用实现复杂逻辑。

## 快速开始

### 创建工作流文件

工作流定义文件放在 `.agent/workflows/` 目录下，支持 `.json` 和 `.js` 格式：

```json
{
  "name": "example-workflow",
  "description": "示例工作流",
  "steps": [
    { "type": "script", "name": "步骤1", "script": "return 'Hello';" },
    { "type": "tool", "name": "发送通知", "tool": "notification_send", "args": { "title": "标题", "message": "内容" } }
  ]
}
```

### 执行工作流

```javascript
// 通过 execute_workflow 工具执行
await execute_workflow({
  workflow: "get-ip-notify"  // 工作流名称（自动从 .agent/workflows/ 加载）
})

// 或直接传入工作流定义
await execute_workflow({
  workflow: {
    steps: [
      { "type": "script", "name": "Hello", "script": "return 'Hello World';" }
    ]
  }
})
```

### 重要注意事项

1. **script 必须用 return 返回值**：`script` 是函数体，不是表达式
2. **JSON 中不能使用多行字符串**：所有 script 内容写成单行，用分号分隔
3. **JSON 中不能有注释**：注释会导致 JSON 解析失败

## 步骤类型

### 1. script - 脚本步骤

执行 JavaScript 代码，**必须用 return 返回值**：

```json
{
  "type": "script",
  "name": "计算",
  "outputVariable": "result",
  "script": "var a=10; var b=20; context.variables.sum=a+b; return a+b;"
}
```

**正确写法**：
```json
{ "script": "return context.variables.value + 1;" }
```

**错误写法**（缺少 return）：
```json
{ "script": "context.variables.value + 1;" }
```

**JSON 中 script 只能写单行**，不能换行。如果逻辑复杂，建议拆成多个 script 步骤。

**script 中的可用对象**：
- `context.input` - 工作流输入参数
- `context.variables` - 工作流变量（可读写），存储在 outputVariable 中的值
- `context.lastResult` - 上一步骤的返回值
- `context.variables.loopIndex` - 循环中的当前索引

### 2. tool - 工具调用步骤

在工作流中调用框架注册的工具：

```json
{
  "type": "tool",
  "name": "发送通知",
  "tool": "notification_send",
  "args": {
    "title": "标题",
    "message": "内容"
  },
  "outputVariable": "result"
}
```

**参数说明**：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `tool` | string | 是 | 工具名称 |
| `args` | object | 否 | 工具参数 |
| `outputVariable` | string | 否 | 结果保存到的变量名，可通过 `context.variables.xxx` 访问 |

**args 中支持变量引用**：

使用 `{{variableName}}` 语法引用 context.variables 中的变量：

```json
{
  "type": "tool",
  "name": "发送通知",
  "tool": "notification_send",
  "args": {
    "title": "IP 信息",
    "message": "当前公网IP: {{currentIp}}"
  }
}
```

变量引用规则：
- `{{currentIp}}` → 从 context.variables.currentIp 获取
- `{{emailResult.success}}` → 支持嵌套属性访问

**完整示例 - 获取IP并发送通知**：

```json
{
  "name": "get-ip-notify",
  "description": "获取本机IP并发送通知",
  "steps": [
    {
      "type": "tool",
      "name": "获取IP信息",
      "tool": "fetch",
      "args": {
        "url": "https://api.ipify.org?format=json",
        "proxy": true
      },
      "outputVariable": "ipResult"
    },
    {
      "type": "script",
      "name": "提取IP",
      "outputVariable": "currentIp",
      "script": "var r=context.variables.ipResult; return (r&&r.success&&r.body)?(typeof r.body==='object'?r.body.ip:r.body.trim()):'获取失败';"
    },
    {
      "type": "tool",
      "name": "发送通知",
      "tool": "notification_send",
      "args": {
        "title": "IP 信息",
        "message": "当前公网IP: {{currentIp}}"
      }
    }
  ]
}
```

### 3. condition - 条件分支

根据条件选择执行分支：

```json
{
  "type": "condition",
  "name": "判断",
  "branches": [
    {
      "name": "大于10",
      "condition": "context.variables.value > 10",
      "steps": [
        { "type": "script", "name": "处理大数", "script": "context.variables.status='big'; return true;" }
      ]
    },
    {
      "name": "小于等于10",
      "condition": "context.variables.value <= 10",
      "steps": [
        { "type": "script", "name": "处理小数", "script": "context.variables.status='small'; return true;" }
      ]
    }
  ]
}
```

**condition 中的 condition 写法**：
- 比较运算符：`>`、`<`、`>=`、`<=`、`===`、`!==`
- 逻辑运算符：`&&`、`||`、`!`
- 必须返回 boolean 值

### 4. loop - 循环步骤

重复执行一组步骤：

```json
{
  "type": "loop",
  "name": "循环3次",
  "maxIterations": 3,
  "loopVariable": "i",
  "until": "context.variables.i >= 2",
  "steps": [
    { "type": "script", "name": "迭代", "script": "context.variables.count=context.variables.i+1; return context.variables.i;" }
  ]
}
```

### 5. delay - 延迟步骤

等待指定时间：

```json
{
  "type": "delay",
  "name": "等待1秒",
  "delayMs": 1000
}
```

### 6. sequential - 顺序步骤

将多个步骤组合为顺序执行（可嵌套使用）：

```json
{
  "type": "sequential",
  "name": "顺序执行",
  "steps": [
    { "type": "script", "name": "步骤1", "script": "return 1;" },
    { "type": "script", "name": "步骤2", "script": "return 2;" }
  ]
}
```

## sessionId 传递

工作流执行时会自动获取当前 sessionId，所有 tool 调用都会使用该 sessionId。

**调用流程**：
1. `execute_workflow` 从执行上下文获取 sessionId
2. sessionId 存入 `context.variables._sessionId`
3. ToolStep 执行工具时使用该 sessionId

**这确保了通知会发送到当前会话**。

## 工具

### execute_workflow

执行指定的工作流。

```javascript
// 按名称执行（从 .agent/workflows/ 加载）
await execute_workflow({
  workflow: "get-ip-notify"
})

// 传入工作流定义
await execute_workflow({
  workflow: {
    steps: [
      { "type": "script", "script": "return 'test';" }
    ]
  }
})

// 带输入参数
await execute_workflow({
  workflow: "my-workflow",
  input: { key: "value" }
})
```

### reloadWorkflows

重载所有工作流（当添加或修改工作流后调用）。

```javascript
await reloadWorkflows()
```

## 最佳实践

1. **script 必须 return**：`script` 是函数体，必须用 return 返回值
2. **JSON 中 script 单行写**：用分号分隔多个语句，不要换行
3. **拆分复杂逻辑**：复杂的 script 拆成多个简单步骤
4. **使用 outputVariable**：需要跨步骤使用的值，存入 context.variables
5. **条件判断加 else**：condition 分支要有兜底处理
6. **合理设置循环次数**：loop 的 maxIterations 不要过大

**错误示例**：
```json
// ❌ 错误 - script 没有 return
{ "type": "script", "script": "context.variables.count + 1;" }

// ❌ 错误 - JSON 多行字符串
{
  "script": "
    const a = 10;
    return a + 1;
  "
}

// ❌ 错误 - JSON 中有注释
{
  "script": "return 1; // 这是注释"
}
```

**正确示例**：
```json
// ✅ 正确
{ "type": "script", "outputVariable": "count", "script": "return (context.variables.count||0) + 1;" }

// ✅ 正确 - 复杂逻辑拆成多步
{ "type": "script", "script": "context.variables.a=10; context.variables.b=20; return context.variables.a+context.variables.b;" }
```
