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

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

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

---

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

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

---

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

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

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

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

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

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

工作流采用简洁的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时优雅结束工作流

---