# iConsulting Agent 三层架构设计

## 问题背景

当前 AI 回复存在以下问题：
- 回复过于冗长，没有抓住用户核心需求
- 重复性表达多，效率低
- 缺乏对用户意图的准确理解
- 没有自我评估机制

## 设计目标

作为 Agent，应该做到：
1. **准确理解用户意图** - 基于对话上下文、历史经验判断用户当前需要什么
2. **自我评估** - 判断 AI 是否已经给出用户想要的答案
3. **主动行动** - 如果未达到用户需求，主动调用工具寻找解决方案
4. **简洁高效** - 回答抓住重点，简短有效

## 三层架构

```
┌─────────────────────────────────────────────────────────────┐
│                      用户消息输入                            │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   第一层：意图分类器                         │
│  IntentClassifier                                            │
│  ┌─────────────────────────────────────────────────────────┐│
│  │ • 分析用户意图类型（简单查询/深度咨询/需要行动/闲聊）   ││
│  │ • 确定建议的最大回复长度                                ││
│  │ • 识别是否需要调用工具                                  ││
│  │ • 检测是否为后续问题                                    ││
│  │ • 提取关键实体（签证类型、职业等）                      ││
│  └─────────────────────────────────────────────────────────┘│
│  输出：IntentResult { type, maxResponseLength, needsTools } │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   第二层：ReAct Agent                        │
│  Claude API + Tool Loop                                      │
│  ┌─────────────────────────────────────────────────────────┐│
│  │ 思考 (Thought)                                          ││
│  │   └─► 分析用户真实需求                                  ││
│  │   └─► 评估当前信息是否足够                              ││
│  │   └─► 决定是否需要调用工具                              ││
│  │                                                          ││
│  │ 行动 (Action)                                           ││
│  │   └─► 调用合适的工具获取信息                            ││
│  │   └─► 支持最多10轮工具调用                              ││
│  │                                                          ││
│  │ 观察 (Observation)                                      ││
│  │   └─► 分析工具返回结果                                  ││
│  │   └─► 决定是否需要继续行动                              ││
│  │                                                          ││
│  │ 生成 (Generate)                                         ││
│  │   └─► 根据意图分类结果控制回复长度                      ││
│  │   └─► 聚焦用户核心问题                                  ││
│  └─────────────────────────────────────────────────────────┘│
│  输出：AI 回复文本                                          │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                   第三层：回复质量门控                        │
│  ResponseGate                                                │
│  ┌─────────────────────────────────────────────────────────┐│
│  │ 质量检查：                                              ││
│  │   • 长度检查 - 是否超过建议长度                         ││
│  │   • 相关性检查 - 是否回答了用户问题                     ││
│  │   • 冗余检查 - 是否包含重复/冗余表达                    ││
│  │   • 完整性检查 - 是否包含必要信息                       ││
│  │   • 语气检查 - 是否符合场景要求                         ││
│  │                                                          ││
│  │ 优化处理：                                              ││
│  │   • 裁剪过长回复（在句子边界处裁剪）                    ││
│  │   • 移除冗余表达                                        ││
│  └─────────────────────────────────────────────────────────┘│
│  输出：优化后的最终回复                                     │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                      最终回复输出                            │
└─────────────────────────────────────────────────────────────┘
```

## 第一层：意图分类器 (IntentClassifier)

### 意图类型

| 类型 | 说明 | 建议长度 | 需要工具 |
|------|------|----------|----------|
| `SIMPLE_QUERY` | 简单查询，直接回答 | 300字 | 否 |
| `DEEP_CONSULTATION` | 深度咨询，需要知识库 | 800字 | 是 |
| `ACTION_NEEDED` | 需要执行操作 | 500字 | 是 |
| `CHAT` | 闲聊寒暄 | 100字 | 否 |
| `CLARIFICATION` | 需要追问澄清 | 150字 | 否 |
| `CONFIRMATION` | 确认/否定 | 200字 | 否 |

### 分类规则

1. **关键词匹配** - 快速识别意图模式
2. **上下文分析** - 判断是否为后续问题
3. **实体提取** - 识别签证类型、职业等关键信息
4. **工具推荐** - 根据意图推荐合适的工具

### 代码位置

`packages/services/conversation-service/src/infrastructure/claude/intent-classifier.ts`

## 第二层：ReAct Agent

### ReAct 思维框架

在 System Prompt 中注入 ReAct 思维模式：

```
<thinking_framework>
在回答用户问题时，请遵循以下思维框架：

1. 理解 (Understand)
   - 用户的核心问题是什么？
   - 用户的真实需求是什么？
   - 这是后续问题还是新问题？

2. 评估 (Evaluate)
   - 我当前掌握的信息是否足够？
   - 是否需要调用工具获取更多信息？
   - 之前的对话是否已经回答过类似问题？

3. 行动 (Act)
   - 如果信息不足，调用合适的工具
   - 优先使用：知识库搜索 > 经验召回 > 网络搜索

4. 生成 (Generate)
   - 直接回答核心问题
   - 避免冗余的开场白和结束语
   - 控制回复长度，抓住重点
</thinking_framework>
```

### 工具循环

- 最多支持 10 轮工具调用
- 每轮：思考 → 调用工具 → 观察结果 → 决定下一步
- 当信息足够时停止调用，生成最终回复

### 代码位置

`packages/services/conversation-service/src/infrastructure/claude/prompts/system-prompt.ts`

## 第三层：回复质量门控 (ResponseGate)

### 检查项

| 检查项 | 说明 | 未通过处理 |
|--------|------|------------|
| `length` | 长度是否超标 | 裁剪至建议长度 |
| `relevance` | 是否与问题相关 | 标记警告 |
| `redundancy` | 是否有冗余表达 | 移除冗余 |
| `completeness` | 是否信息完整 | 标记警告 |
| `tone` | 语气是否合适 | 标记警告 |

### 冗余表达清单

```
- "根据我的了解"
- "让我来帮您"
- "非常感谢您的咨询"
- "希望以上信息对您有所帮助"
- "如果您还有其他问题"
- ...
```

### 代码位置

`packages/services/conversation-service/src/infrastructure/claude/response-gate.ts`

## 集成流程

```typescript
// claude-agent.service.ts 伪代码

async sendMessage(message, history) {
  // 第一层：意图分类
  const intent = intentClassifier.classify(message, history);

  // 构建带 ReAct 框架的 System Prompt
  const systemPrompt = buildSystemPrompt({
    ...config,
    intentHint: intent,  // 注入意图信息
  });

  // 第二层：ReAct Agent 处理
  const response = await this.claudeClient.chat({
    systemPrompt,
    messages: history,
    tools: intent.needsTools ? this.getTools() : [],
    maxTokens: this.calculateMaxTokens(intent),
  });

  // 第三层：回复质量门控
  const gateResult = responseGate.check(response, intent, message);

  // 返回优化后的回复
  return gateResult.optimizedResponse || response;
}
```

## 预期效果

### 改进前
```
用户：189签证要多少分？

AI：非常感谢您的咨询！关于澳大利亚189独立技术移民签证，
这是一个非常重要的移民类别。让我来为您详细解答。

首先，189签证是一种打分制签证，需要达到一定的分数才能获邀。
根据目前的政策...（以下省略500字）

希望以上信息对您有所帮助！如果您还有其他问题，欢迎继续咨询。
```

### 改进后
```
用户：189签证要多少分？

AI：189签证需要至少65分才能提交EOI。
目前获邀分数线约为85-95分，具体取决于职业。

主要加分项：年龄、英语、工作经验、学历、州担保等。
```

## 文件清单

| 文件 | 状态 | 说明 |
|------|------|------|
| `intent-classifier.ts` | ✅ 已创建 | 意图分类器 |
| `response-gate.ts` | ✅ 已创建 | 回复质量门控 |
| `system-prompt.ts` | 🔄 待更新 | 加入 ReAct 框架 |
| `claude-agent.service.ts` | 🔄 待更新 | 集成三层架构 |

## 后续优化方向

1. **机器学习分类** - 用训练数据替代规则分类
2. **动态长度调整** - 根据反馈自动调整建议长度
3. **个性化门控** - 根据用户偏好调整检查规则
4. **A/B 测试** - 对比优化前后的用户满意度