智能体系统中的Controller/Worker架构设计与实践

markdown复制## 1. 项目概述：Controller/Worker模式在智能体系统中的工程化实践

这个项目展示了一个典型的企业级智能体系统实现方案。不同于常见的单体式AI应用，我们采用Controller/Worker架构将复杂任务分解为可独立管理的子模块。这种设计源于我在多个AI项目落地过程中积累的深刻教训——当系统需要同时处理SQL查询、文档检索和结果合成时，传统的端到端模型调用方式很快就会变得难以维护和审计。

### 1.1 核心需求解析

现代企业知识管理通常面临三类典型问题：
1. **结构化数据查询**：如"新加坡办公室有多少员工"这类可通过数据库直接回答的事实性问题
2. **非结构化文档检索**：如"安全策略中的最小权限原则是什么"这类需要从文档中提取的规则性问题
3. **混合型问题**：如"列出所有P0工单并说明对应的升级流程"这类需要同时结合数据和文档的复合问题

传统做法是直接将问题抛给大语言模型处理，但这会带来三个严重问题：
- 无法确保模型始终选择正确的信息源
- 缺乏对敏感操作（如数据库查询）的安全控制
- 出现问题难以追踪故障点

### 1.2 架构设计理念

我们的解决方案基于以下核心原则：
- **职责分离**：路由决策、SQL执行、文档检索、结果合成分别由不同Worker处理
- **显式控制流**：Controller明确控制执行流程，而非依赖模型的隐式推理
- **结构化中间产物**：各阶段产出标准化数据结构，便于追踪和审计
- **安全边界**：关键操作（如SQL执行）有严格的校验机制

## 2. 核心组件实现细节

### 2.1 系统分层架构

#### 控制层（Controller）
作为系统大脑，Controller不处理具体业务逻辑，而是负责：
- 初始化执行上下文（Trace ID、问题解析）
- 按顺序调用Worker（路由→取证→合成）
- 收集和持久化执行轨迹
- 处理异常情况和空结果回退

典型代码结构：
```python
def handle(question_text):
    # 初始化上下文
    ctx = TaskContext(question=question_text)
    
    # 阶段1：路由决策
    route_result = route