# Smith：Ruby生态中的工作流优先多智能体编排框架

> Smith是一个面向Ruby开发者的工作流优先多智能体编排库，基于RubyLLM构建。它提供显式状态机、预算控制、工具策略、持久化钩子等特性，将AI代理从"提示工程"提升为可运维的应用系统。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-03-30T23:44:59.000Z
- 最近活动: 2026-03-30T23:52:50.076Z
- 热度: 141.9
- 关键词: Smith, Ruby, 多智能体编排, 工作流, RubyLLM, 状态机, AI代理, 生产级AI
- 页面链接: https://www.zingnex.cn/forum/thread/smith-ruby
- Canonical: https://www.zingnex.cn/forum/thread/smith-ruby
- Markdown 来源: ingested_event

---

# Smith：Ruby生态中的工作流优先多智能体编排框架

## 引言：从提示工程到系统工程的跃迁

在AI应用开发的早期阶段，开发者们专注于"提示工程"——如何通过精心设计的自然语言指令来引导大语言模型的行为。然而，随着AI代理（Agent）系统的复杂度不断提升，单纯的提示工程已经无法满足生产环境的需求。

Smith正是为解决这一问题而生。它是一个面向Ruby生态的工作流优先多智能体编排框架，基于RubyLLM构建。与那些将编排逻辑隐藏在提示词中的方案不同，Smith将工作流作为一等公民，提供了显式状态机、预算控制、工具策略、持久化钩子等生产级特性。

## 命名背后的深意

Smith这个名字来源于《黑客帝国》中的特工史密斯（Agent Smith）。这个命名并非随意为之，而是蕴含了深刻的系统设计理念：

- **控制（Control）**：对代理行为的精确掌控
- **执行（Enforcement）**：策略和约束的强制执行
- **复制（Replication）**：代理能力的可复用和扩展
- **传播（Propagation）**：任务在系统中的流转和分发
- **协调（Coordination）**：多代理之间的协作机制
- **遏制压力（Containment Pressure）**：对代理行为的边界约束

正如电影中的史密斯特工随着自主性增强而变得更加难以约束，真实的代理软件系统也面临着类似的挑战：多角色参与、重复委托、范围扩展，以及一旦系统产生实际后果就变得重要的故障模式。Smith框架正是为这一层面而构建的。

## 核心设计理念

### 显式而非隐式

传统的代理演示往往在需要以下能力时显得力不从心：

- 显式控制流而非"提示告诉模型该做什么"
- 可重复的错误行为（便于调试）
- 工具授权和护栏机制
- 预算和截止时间强制执行
- 并行扇出与受控的会计统计
- 嵌套工作流和可复用的子流程
- 评估器-优化器（evaluator-optimizer）和编排器-工作者（orchestrator-worker）循环
- 工作流边界处的持久化和恢复
- 大型输出的产物管理
- 追踪和最优的Token/成本核算

Smith通过将编排逻辑从提示词中抽离出来，用Ruby代码显式表达，解决了这些问题。

### 工作流优先架构

Smith的核心抽象是工作流（Workflow）。一个Smith工作流包含：

- **命名状态（Named States）**：明确定义工作流可能处于的状态
- **命名转换（Named Transitions）**：状态之间的合法转移
- **预算（Budgets）**：Token和成本的预算控制
- **护栏（Guardrails）**：安全约束和策略执行
- **工具策略（Tool Policy）**：工具使用的授权和控制
- **持久化钩子（Persistence Hooks）**：状态保存和恢复机制
- **产物（Artifacts）**：大型输出的管理
- **追踪（Tracing）**：执行过程的可观测性

## 技术架构与核心组件

### Context（上下文）

Context是Smith中管理持久化状态的核心组件。它定义了哪些数据需要在步骤之间保持，以及如何将这些数据注入到后续的状态中：

```ruby
class ReplyContext < Smith::Context
  persist :user_message

  inject_state do |persisted|
    "User message: #{persisted[:user_message]}"
  end
end
```

这种设计使得工作流可以在任意点暂停、持久化，并在之后从精确的状态恢复。

### Agent（代理）

Smith的Agent是对RubyLLM的封装，但增加了注册机制和指令模板：

```ruby
class ReplyAgent < Smith::Agent
  register_as :reply_agent
  model "gpt-4.1-nano"

  instructions do |_context|
    "Write a concise, professional reply."
  end
end
```

代理可以被多个工作流复用，其指令可以根据上下文动态生成。

### Workflow（工作流）

Workflow是Smith的核心抽象，它使用状态机模式定义执行流程：

```ruby
class ReplyWorkflow < Smith::Workflow
  context_manager ReplyContext
  initial_state :idle
  state :done
  state :failed

  transition :reply, from: :idle, to: :done do
    execute :reply_agent
    on_failure :fail
  end
end
```

这种声明式的设计使得工作流的结构一目了然，同时也便于静态分析和验证。

## Smith的能力边界

### Smith是什么

- 一个用于工作流优先代理编排的Ruby库
- 基于RubyLLM构建，而非替代品
- 进程内执行，由宿主应用控制
- 适用于需要显式状态和显式控制的应用级编排

### Smith不是什么

- 不是托管运行时（hosted runtime）
- 不是持久化工作流引擎本身
- 不是任务队列
- 不是计费级成本系统
- 不能替代应用的持久化、重试或部署平台

宿主应用仍然需要负责：
- 持久化实现
- 任务执行
- 主机/进程级别的重试
- 租户隔离策略
- 提供商凭证和配置

## 可构建的系统模式

基于当前的能力，Smith支持构建以下类型的系统：

1. **单代理护栏系统**：在工作流边界后保护单个受控代理
2. **顺序多步流程**：明确的步骤链和状态转换
3. **分类器路由**：基于内容的智能路由
4. **有界并行扇出**：受控的并行执行
5. **嵌套工作流**：通过子流程实现复用
6. **生成器/评估器循环**：迭代优化模式
7. **编排器/工作者系统**：主从协作模式
8. **产物引用工作流**：将大型输出存储为产物引用
9. **可恢复流程**：使用`to_state` / `.from_state`实现断点续传

## 实际价值：一分钟理解Smith的转变

### 没有Smith时的典型应用

```ruby
# 一个提示字符串
# 一个LLM调用
# 围绕响应的临时分支
# 不清晰的错误处理
# 没有工作流状态
```

### 使用Smith后的同等工作

```ruby
result = ReplyWorkflow.new(
  context: { user_message: "I was charged twice for the same invoice." }
).run!

result.state
# => :done

result.output
# => 最终的助手输出

result.steps
# => [{ transition: :reply, from: :idle, to: :done, output: ... }]
```

这种转变立即带来了：
- 显式的工作流状态
- 显式的成功和失败路由
- 可检查的步骤日志
- 添加预算、工具、护栏、追踪、持久化和产物的清晰扩展点

## 项目现状与展望

Smith目前处于活跃开发阶段，尚未发布到RubyGems。开发者可以通过本地路径或Git源引入：

```ruby
gem "smith", path: "../smith"
# 或
gem "smith", git: "ssh://git@your-git-host/your-org/smith.git"
```

项目提供了完整的验证工具链：

```bash
smith doctor              # 离线验证
smith doctor --live       # 包含真实提供商调用
smith doctor --durability # 包含持久化往返测试
smith install             # 生成配置文件
```

对于Rails应用，还提供了专门的Rake任务和生成器。

## 结语

Smith代表了AI应用开发从"演示"走向"生产"的必然趋势。它不提供魔法般的"自动代理"，而是提供了一套严谨的工程框架，让开发者能够以可预测、可调试、可运维的方式构建复杂的AI系统。

在Python生态中，我们有LangGraph、CrewAI等多代理框架；而在Ruby世界，Smith正在填补这一空白。对于那些已经在Ruby生态中深耕的团队来说，Smith提供了一个无需切换技术栈就能构建生产级AI系统的选择。