# AI Agent框架

## 概述

GEO平台的AI Agent框架是系统的核心智能层，采用模块化、可插拔的设计，支持Agent的动态注册、任务分发和状态管理。

## 架构

```
┌─────────────────────────────────────────────────────────────┐
│                     Agent Framework                          │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐    │
│  │  Dispatcher │→│  Registry   │→│  PipelineEngine │    │
│  └─────────────┘  └─────────────┘  └─────────────────┘    │
│                                                              │
│  ┌─────────────────────────────────────────────────┐        │
│  │                    Agents                          │        │
│  ├───────────┬───────────┬───────────┬────────────┤        │
│  │ Citation  │ Content   │ DeAI     │ GEO       │        │
│  │ Detector  │ Generator │ Agent    │ Optimizer │        │
│  └───────────┴───────────┴───────────┴────────────┘        │
└─────────────────────────────────────────────────────────────┘
```

## 核心组件

### Dispatcher (调度器)

负责接收任务请求并分发到合适的Agent。

- 位置：`backend/app/agent_framework/dispatcher.py`
- 职责：任务路由、负载均衡、优先级处理、结果汇总

### Registry (注册中心)

管理所有Agent的注册信息和状态。

- 位置：`backend/app/agent_framework/registry.py`
- 存储：PostgreSQL数据库 (AgentRegistryModel)
- 功能：Agent注册、健康检查、服务发现、心跳更新

### PipelineEngine (编排引擎)

编排多阶段Agent任务链的执行。

- 位置：`backend/app/agent_framework/pipeline/engine.py`
- 职责：DAG执行、变量传递、超时控制、条件执行

## Agent列表

### CitationDetector (引用检测Agent)

| 属性 | 说明 |
|------|------|
| 文件 | `backend/app/agent_framework/agents/citation_detector.py` |
| 职责 | 解析AI平台响应，识别品牌引用情况 |
| 输入 | AI平台原始响应、品牌名称、竞品名称 |
| 输出 | 引用检测结果（引用/未引用/竞品引用） |

**引用类型**：
- `direct_quote` - 品牌名直接提及
- `indirect_reference` - 品牌信息被提及
- `no_reference` - 品牌未被提及
- `competitor_reference` - 竞品被引用

### ContentGenerator (内容生成Agent)

| 属性 | 说明 |
|------|------|
| 文件 | `backend/app/agent_framework/agents/content_generator_agent.py` |
| 职责 | 生成GEO优化的内容资产 |
| 输入 | 内容主题、规则库配置、品牌素材 |
| 输出 | GEO优化内容（文章/问答/指南等） |

**支持内容类型**：
- `article` - 长篇文章（800-2000字）
- `qa` - 问答对
- `guide` - 操作指南
- `comparison` - 对比分析
- `data_report` - 数据报告

### DeAI Agent (去AI化Agent)

| 属性 | 说明 |
|------|------|
| 文件 | `backend/app/agent_framework/agents/deai_agent.py` |
| 职责 | 去除AI生成内容的痕迹 |
| 输入 | AI生成的内容 |
| 输出 | 自然化处理后的内容 |

### GEOOptimizer (GEO优化Agent)

| 属性 | 说明 |
|------|------|
| 文件 | `backend/app/agent_framework/agents/geo_optimizer_agent.py` |
| 职责 | 对内容进行GEO优化 |
| 输入 | 原始内容、关键词策略 |
| 输出 | 优化后的内容 |

### MonitorAgent (效果追踪Agent)

| 属性 | 说明 |
|------|------|
| 文件 | `backend/app/agent_framework/agents/monitor_agent.py` |
| 职责 | 定期检测品牌在AI平台的引用变化，生成变化报告 |
| 输入 | 品牌名称、AI平台列表、检测周期 |
| 输出 | 引用变化报告（新增引用、丢失引用、变化趋势） |

**报告类型**：
- `daily_report` - 每日引用变化快报
- `weekly_report` - 周度引用趋势报告
- `alert` - 异常变化告警（引用大幅下降等）

### SchemaAdvisorAgent (Schema建议Agent)

| 属性 | 说明 |
|------|------|
| 文件 | `backend/app/agent_framework/agents/schema_advisor_agent.py` |
| 职责 | 基于品牌诊断数据生成JSON-LD结构化数据建议 |
| 输入 | 品牌诊断数据、当前Schema配置、行业类型 |
| 输出 | JSON-LD结构化数据建议方案 |

**建议类型**：
- `schema_add` - 新增Schema建议
- `schema_modify` - 现有Schema修改建议
- `schema_validate` - Schema合规性验证结果

### CompetitorAnalyzerAgent (竞品分析Agent)

| 属性 | 说明 |
|------|------|
| 文件 | `backend/app/agent_framework/agents/competitor_analyzer_agent.py` |
| 职责 | 5维度分析竞品（引用量、引用质量、引用场景、内容策略、机会发现） |
| 输入 | 品牌名称、竞品列表、分析维度 |
| 输出 | 竞品分析报告 |

**分析维度**：
- `citation_volume` - 引用量对比
- `citation_quality` - 引用质量评估
- `citation_scenario` - 引用场景分布
- `content_strategy` - 内容策略分析
- `opportunity_discovery` - 机会发现与建议

### TrendAgent (趋势洞察Agent)

| 属性 | 说明 |
|------|------|
| 文件 | `backend/app/agent_framework/agents/trend_agent.py` |
| 职责 | 识别关键词和平台的引用趋势（上升/下降/平稳/热点） |
| 输入 | 关键词列表、AI平台列表、时间范围 |
| 输出 | 趋势分析报告 |

**趋势类型**：
- `rising` - 上升趋势
- `declining` - 下降趋势
- `stable` - 平稳趋势
- `hotspot` - 热点趋势

## 通信协议

基于数据库+Redis Queue的异步通信：

```python
class TaskMessage:
    task_id: str       # UUID
    agent_name: str    # 目标Agent名称
    task_type: str     # 任务类型
    priority: int     # 优先级(0-9)
    input_data: dict  # 输入参数
    callback_url: str  # 回调URL
    created_at: datetime  # 创建时间
    timeout_seconds: int  # 超时时间
```

### 通信流程

```
1. 外部请求 → Dispatcher.dispatch(TaskMessage) → Redis Queue
2. Redis Queue → Agent消费 → 执行任务
3. Agent执行完成 → TaskResult → Dispatcher.handle_result
4. Dispatcher更新数据库 → 触发回调(如有)
```

## 注册机制

Agent启动时向Registry注册：

```python
{
    "name": "CitationDetector",
    "version": "1.0.0",
    "status": "online",  # online/busy/offline
    "endpoint": "http://...",
    "capabilities": {...},
    "last_heartbeat": "2024-01-01T00:00:00Z"
}
```

### 心跳机制

- 心跳超时阈值：90秒
- Registry.check_health() 定期检查并标记超时Agent为OFFLINE

## 任务状态机

```
PENDING → RUNNING → COMPLETED
              ↓
           FAILED → RETRY → RUNNING
              ↓
          CANCELLED
```

## Prompt模板

Agent使用统一的Prompt模板系统：

| 文件 | 说明 |
|------|------|
| `prompts/base_template.py` | 基础模板结构 |
| `prompts/content_generator.py` | 内容生成模板 |
| `prompts/deai_agent.py` | 去AI化模板 |
| `prompts/geo_optimizer.py` | GEO优化模板 |
| `prompts/rule_checker.py` | 规则检查模板 |
| `prompts/topic_selector.py` | 母题选择模板 |