# United Workforce：无状态工作流引擎的极简之道

> United Workforce (uwf) 是一个基于单步CLI驱动的无状态工作流引擎，采用YAML定义工作流，通过CAS内容寻址存储实现不可变线程链，支持多智能体编排。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-14T01:14:23.000Z
- 最近活动: 2026-06-14T01:22:09.850Z
- 热度: 157.9
- 关键词: workflow engine, stateless, CLI, multi-agent, CAS, YAML, orchestration
- 页面链接: https://www.zingnex.cn/forum/thread/united-workforce
- Canonical: https://www.zingnex.cn/forum/thread/united-workforce
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者**: shazhou-ww
- **来源平台**: GitHub
- **原始标题**: united-workforce
- **原始链接**: https://github.com/shazhou-ww/united-workforce
- **发布时间**: 2026-06-14

---

## 背景：为什么我们需要无状态工作流引擎

在AI智能体(workflow agent)快速发展的今天，大多数工作流引擎都采用了常驻服务(daemon)的架构模式。这些系统需要持续运行的服务器进程、复杂的状态管理、以及难以调试的分布式组件。当开发者试图理解或修改工作流行为时，往往面临着黑盒困境——无法直观地追踪状态变化，也难以在本地环境中复现问题。

United Workforce (uwf) 提出了一种截然不同的设计理念：**完全无状态、单步执行、内容寻址存储(CAS)**。这种架构让工作流引擎变得像普通命令行工具一样简单透明，同时保留了强大的多智能体编排能力。

---

## 核心架构设计

### 单步CLI驱动

与传统的工作流引擎不同，uwf没有常驻进程。每次执行`uwf thread step`命令时，系统会完成一个完整的工作周期：

1. **Moderator评估**: 根据当前状态判断应该路由到哪个角色
2. **智能体执行**: 调用外部智能体CLI生成Markdown输出
3. **提取验证**: 验证输出是否符合角色的JSON Schema定义
4. **状态持久化**: 将结果写入CAS存储，更新线程指针

执行完成后进程立即退出，不占用任何后台资源。这种设计带来了显著的优势：易于调试、可预测的行为、简单的水平扩展。

### 内容寻址存储(CAS)

uwf采用内容寻址存储作为其持久化层，所有数据都存储在`~/.ocas/`目录下：

- **工作流定义**: YAML工作流文件被哈希后存入CAS
- **线程状态**: 每个步骤产生的内容都成为CAS中的一个不可变节点
- **元数据索引**: 使用`~/.ocas/variables.db`存储命名到哈希的映射

这种设计天然支持版本控制、重复数据删除和审计追踪。由于内容通过哈希寻址，相同的输入总是产生相同的存储位置，实现了真正的不可变历史。

### YAML工作流定义

工作流采用简洁的YAML格式定义，包含三个核心部分：

```yaml
version: 1
name: solve-issue
description: Resolve a Gitea/GitHub issue end-to-end.
roles:
  planner:
    goal: "Analyze the issue and create a plan"
  developer:
    goal: "Implement the fix based on the plan"
graph:
  planner:
    ready: developer
  developer:
    done: $END
```

`roles`定义了参与工作流的智能体角色及其目标，`graph`则声明了基于状态的路由规则。这种声明式定义让工作流的意图一目了然。

---

## 多智能体编排机制

### 插件化智能体架构

uwf不绑定特定的AI模型或智能体实现，而是通过标准CLI接口支持多种智能体：

- **uwf-hermes**: 基于Hermes ACP协议的智能体
- **uwf-builtin**: 内置的LLM+工具智能体
- **uwf-claude-code**: Claude Code集成
- **自定义命令**: 任何符合接口规范的CLI程序

智能体通过环境变量接收上下文（如`UWF_EDGE_PROMPT`），输出Markdown格式的响应，实现了真正的解耦。

### 状态路由与协调

Moderator是uwf的核心协调组件，它根据当前线程状态和预定义的路由图决定下一步执行哪个角色。这种设计允许：

- **条件分支**: 基于智能体输出状态选择不同路径
- **循环迭代**: 支持需要多轮处理的复杂任务
- **终止判定**: 当路由到`$END`时优雅结束工作流

---

## 快速上手

安装uwf CLI工具：

```bash
npm install -g @united-workforce/cli
```

配置并运行第一个工作流：

```bash
# 1. 配置提供方、模型和默认智能体
uwf setup

# 2. 从YAML注册工作流
uwf workflow add examples/solve-issue.yaml

# 3. 启动线程（创建头部指针，不执行）
uwf thread start solve-issue -p "Fix the login redirect bug"

# 4. 执行步骤（单步模式）
uwf thread exec <thread-id>
```

使用`-c, --count`参数可以在一次调用中执行多个步骤，而`--agent`参数允许临时覆盖默认智能体。

---

## 技术栈与依赖层次

uwf采用清晰的分层架构，从底层到顶层依次为：

**Layer 0 - Contract层**: protocol包定义共享类型和JSON Schema

**Layer 1 - 基础设施层**: util包提供编码、ID生成、日志、frontmatter解析等通用功能

**Layer 2 - 智能体框架层**: util-agent包提供createAgent工厂、上下文构建器和提取管道

**Layer 3 - 智能体实现层**: 包含hermes、builtin、claude-code三种智能体实现

**Layer 4 - CLI层**: 提供uwf二进制文件，实现线程生命周期、注册表、CAS和setup功能

**应用层**: dashboard提供可视化工作流编辑的Web UI

这种分层确保了关注点分离，底层不依赖高层，便于测试和维护。

---

## 实际意义与应用场景

### 开发工作流自动化

uwf特别适合需要多角色协作的软件开发场景。例如，一个"解决issue"的工作流可以包含：

- **planner角色**: 分析issue描述，制定修复计划
- **developer角色**: 根据计划编写代码
- **reviewer角色**: 审查代码变更
- **tester角色**: 运行测试验证修复

每个角色由不同的智能体或工具担任，通过YAML清晰定义协作流程。

### 可审计的AI工作流

由于所有中间状态都存储在不可变的CAS中，uwf天然支持完整的审计追踪。可以精确重现任意历史执行过程，分析每个决策点的上下文，满足合规要求。

### 本地优先与隐私保护

无服务器架构意味着所有数据默认存储在本地`~/.ocas/`目录，敏感信息不会意外泄露到云端。对于处理私有代码或敏感数据的企业场景，这是重要的安全特性。

---

## 总结与展望

United Workforce代表了一种回归本质的工作流引擎设计思路：通过消除常驻进程、采用内容寻址存储、坚持单步执行模型，它在保持功能完整性的同时大幅降低了系统复杂度。

对于希望将AI智能体集成到现有DevOps流程的团队，uwf提供了一个轻量级、可审计、易于理解的解决方案。其插件化智能体架构确保了与各种AI模型和工具的兼容性，而声明式YAML定义则降低了使用门槛。

随着AI辅助编程的普及，像uwf这样能够桥接人类工作流与机器智能的工具将变得越来越重要。它的设计理念——简单、透明、可控——正是企业级AI应用所需要的坚实基础。