# Leeway：基于YAML决策树的AI Agent工作流框架，平衡确定性与灵活性

> 一款创新的AI Agent框架，通过YAML定义决策树工作流，由人类控制流程结构，AI在节点内灵活执行，实现了确定性状态机与LLM灵活性的完美结合。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-09T23:12:02.000Z
- 最近活动: 2026-04-09T23:18:32.920Z
- 热度: 157.9
- 关键词: AI Agent, 工作流框架, YAML决策树, MCP协议, 任务调度, 人机协作, 自动化工作流
- 页面链接: https://www.zingnex.cn/forum/thread/leeway-yamlai-agent
- Canonical: https://www.zingnex.cn/forum/thread/leeway-yamlai-agent
- Markdown 来源: ingested_event

---

在AI Agent领域，开发者长期面临一个两难选择：完全由AI自主控制的Agent虽然灵活，但行为难以预测；而传统的工作流工具虽然确定性高，却缺乏AI的智能适应能力。**Leeway** 是一款创新性的开源AI Agent框架，它通过独特的YAML决策树设计，巧妙地平衡了确定性与灵活性，为构建可预测且智能的自动化工作流提供了全新方案。

## 核心理念：人类定义流程，AI执行节点

Leeway的设计哲学可以用一句话概括：**人类用YAML定义工作流图结构，AI在每个节点内灵活推理执行，通过确定性信号触发状态转移**。这种架构既保证了整体流程的可预测性，又保留了AI在局部任务中的智能适应能力。

与传统Agent工具对比，Leeway的优势显而易见：

| 维度 | AI自主Agent | 传统工作流工具 | Leeway |
|------|------------|--------------|--------|
| 流程控制者 | AI自主决定 | 人类预设脚本 | **人类定义YAML决策树** |
| 执行方式 | AI全程自主 | 刚性脚本执行 | **AI在节点内灵活执行** |
| 可预测性 | 低，可能偏离预期 | 高，但缺乏灵活性 | **高，确定性状态转移** |
| 灵活性 | 高，但不可控 | 低，锁定在设计中 | **高，AI在边界内推理** |

这种设计特别适合需要严格合规、审计追踪或人机协作的场景，如代码审查、安全审计、文档生成等。

## 技术架构与核心特性

### YAML决策树工作流引擎

Leeway的工作流采用YAML格式定义，支持五种核心模式：

**线性流程**：无条件顺序执行，适合简单任务链
```yaml
scan:
  prompt: "扫描项目结构"
  tools: [glob, bash]
  edges:
    - target: assess
      when: { always: true }
```

**分支决策**：基于AI信号的条件分支，支持复杂业务逻辑
```yaml
assess:
  prompt: "发出'well_documented'、'needs_investigation'或'trivial'信号"
  edges:
    - target: deep_dive
      when: { signal: needs_investigation }
    - target: summarize
      when: { signal: well_documented }
```

**循环迭代**：支持回边到自身或前置节点，实现迭代式处理

**并行分支**：条件触发的并发执行，所有分支完成后统一汇聚
```yaml
review:
  parallel:
    branches:
      quality:
        when: { always: true }
        prompt: "审查代码质量"
      security:
        when: { signal: security_risk }
        prompt: "安全审计"
        requires_approval: true
```

**终止节点**：无出边的叶节点，标志工作流结束

### 21+内置工具集

Leeway提供丰富的工具生态，覆盖常见开发场景：

**文件操作**：bash、read_file、write_file、edit_file、glob、grep等核心文件操作

**网络访问**：web_fetch网页抓取、web_search搜索引擎集成

**交互能力**：ask_user_question用户提问、skill按需加载知识技能

**任务管理**：task_create、task_list、task_get、task_stop后台任务生命周期管理

**调度系统**：cron_create、cron_list、cron_delete、cron_toggle定时任务管理

**Agent协作**：agent子Agent派生、remote_trigger远程触发器

**持久记忆**：memory_read、memory_write跨会话知识存储

**MCP集成**：动态注册MCP服务器工具，扩展外部能力

每个工具都具备Pydantic输入验证、自描述JSON Schema、权限集成和钩子支持。

### 技能系统：渐进式知识披露

Leeway的技能系统采用**文件夹化组织**，每个技能包含主说明文件SKILL.md和可选的references/详细参考资料：

```
.leeway/skills/
  code-review/
    SKILL.md              # 主说明（优先加载）
    references/
      checklist.md        # 详细清单（按需加载）
```

这种渐进式披露机制确保Agent首先获取核心指令，仅在需要时才加载详细参考资料，有效管理上下文窗口。项目内置三个示例技能：编码标准检查、代码质量审查、安全漏洞审计。

### 生命周期钩子

钩子系统支持在工具执行前后触发自定义逻辑，可在settings.json全局配置、工作流global_hooks级别或节点/分支级别定义：

```yaml
global_hooks:
  - type: command
    match: { event: workflow_start }
    command: "echo '工作流启动' >> /tmp/hooks.log"
```

支持命令钩子（执行shell命令）和HTTP钩子（发送POST请求），适用于日志记录、通知、审计和外部系统集成。

### MCP协议支持

Leeway原生支持Model Context Protocol（MCP），可连接外部MCP服务器扩展工具能力：

```json
{
  "mcp_servers": [
    {
      "name": "my-server",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@my/mcp-server"]
    }
  ]
}
```

MCP工具自动注册为`mcp_<server>_<tool>`格式，可在工作流节点工具列表中使用。

### 权限与安全机制

Leeway提供多级安全控制：

**执行模式**：默认模式（写入/执行前询问）、全自动模式（沙箱环境）、计划模式（只读预览）

**路径规则**：细粒度的路径级权限控制

**命令黑名单**：禁止危险命令如`rm -rf /`

**人机协作**：并行分支支持`requires_approval: true`配置，关键操作需人工确认

## 调度与Cron系统

Leeway内置独立的Cron调度守护进程，支持多种调度类型：

- **Cron表达式**：如`*/5 * * * *`每5分钟执行
- **间隔调度**：如`300`秒间隔执行
- **单次定时**：指定时间点执行一次

支持shell命令、工作流执行和Webhook调用三种动作类型，满足定时报告生成、定期健康检查、定时数据同步等场景需求。

## 使用场景与价值

**代码审查自动化**：定义包含质量检查、安全审计、测试运行的并行审查流程，AI自动扫描代码并生成结构化报告。

**文档生成工作流**：从代码分析到架构图生成再到文档撰写的端到端自动化。

**DevOps运维剧本**：将复杂的故障排查流程编码为决策树，AI按步骤执行诊断命令并汇总结果。

**合规性检查**：确保每次执行都遵循预定义的检查清单，满足审计要求。

**多Agent协作**：通过子Agent派生实现任务分解，主Agent协调多个专业Agent并行工作。

## 项目质量与成熟度

Leeway展现了优秀的工程实践：

- **测试覆盖**：190个测试用例全部通过，涵盖技能、任务、钩子、Cron、MCP、工作流引擎等核心模块
- **类型安全**：基于Python 3.10+和Pydantic的严格类型检查
- **现代UI**：基于React Ink的终端交互界面，支持实时工作流进度可视化
- **多模型支持**：兼容Anthropic Claude和OpenAI兼容API

## 快速上手

```bash
# 克隆安装
git clone https://github.com/hardness1020/Leeway.git
cd Leeway
uv sync --extra dev

# 配置API密钥
export ANTHROPIC_API_KEY=sk-...

# 启动交互模式
uv run leeway

# 运行示例工作流
> /code-health start
```

## 总结

Leeway为AI Agent领域带来了一种务实而优雅的设计范式：不是让AI完全自主，也不是完全限制AI，而是在人类定义的安全边界内赋予AI适当的灵活性。这种"有约束的智能"特别适合企业级应用场景，在确保可预测性和可审计性的同时，充分发挥大语言模型的推理能力。对于需要构建可靠AI自动化系统的开发者而言，Leeway是一个值得深入研究和采用的开源框架。