# GEO 平台 - AI Agent 框架设计

## 概述

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

本文档定义 Agent 框架的整体架构、核心组件和通信机制。

## Agent 列表

### CitationDetector（引用检测 Agent）

| 属性 | 说明 |
|------|------|
| **职责** | 解析 AI 平台响应，识别其中是否包含品牌引用 |
| **输入** | AI 平台原始响应文本、品牌名称列表、竞品名称列表 |
| **输出** | 引用检测结果（引用/未引用/竞品引用）、引用片段、置信度评分 |
| **核心能力** | 自然语言理解、实体识别、引用关系判定 |
| **触发方式** | 查询任务完成后自动触发 |
| **优先级** | P0 |

**处理流程**：
```
接收响应文本 ──▶ 文本预处理 ──▶ 品牌实体识别 ──▶ 引用关系判定
                                              │
                                              ▼
                                    竞品引用检测 ──▶ 置信度评估
                                              │
                                              ▼
                                    结果格式化 ──▶ 上报结果
```

**引用类型判定**：
| 类型 | 判定标准 | 置信度权重 |
|------|----------|------------|
| `direct_quote` | 品牌名被直接提及并作为信息来源 | 高 |
| `indirect_reference` | 品牌信息被提及但未明确标注来源 | 中 |
| `no_reference` | 品牌完全未被提及 | 确定 |
| `competitor_reference` | 竞品被引用而品牌未被引用 | 高 |

### ContentGenerator（内容生成 Agent）

| 属性 | 说明 |
|------|------|
| **职责** | 根据策略和规则生成 GEO 优化的内容资产 |
| **输入** | 内容主题、规则库配置、品牌素材、参考数据 |
| **输出** | GEO 优化内容（文章/问答/指南等）、内容元数据 |
| **核心能力** | 创意写作、SEO/GEO 优化、多风格适配 |
| **触发方式** | 用户手动触发或按排期自动触发 |
| **优先级** | P0 |

**处理流程**：
```
接收生成任务 ──▶ 需求分析 ──▶ 素材收集 ──▶ 大纲生成
                                          │
                                          ▼
                                    内容撰写 ──▶ GEO 优化处理
                                          │
                                          ▼
                                    自检校验 ──▶ 输出结果
```

**内容类型支持**：
| 类型 | 说明 | 适用场景 |
|------|------|----------|
| `article` | 长篇文章（800-2000 字） | 深度行业内容 |
| `qa` | 问答对 | 常见品牌问题 |
| `guide` | 操作指南 | 产品使用场景 |
| `comparison` | 对比分析 | 竞品对抗 |
| `data_report` | 数据报告 | 行业研究 |

### RuleChecker（规则检查 Agent）

| 属性 | 说明 |
|------|------|
| **职责** | 检查内容是否符合规则库中的约束条件 |
| **输入** | 待检查内容、规则库配置 |
| **输出** | 检查结果（通过/不通过）、问题列表、改进建议 |
| **核心能力** | 规则引擎、内容质量评估、语义分析 |
| **触发方式** | ContentGenerator 生成后自动触发，或手动触发 |
| **优先级** | P0 |

**检查维度**：
| 维度 | 说明 | 示例规则 |
|------|------|----------|
| `keyword_coverage` | 关键词覆盖度 | 必须包含核心关键词 |
| `readability` | 可读性评分 | Flesch 阅读 ease 分数 |
| `tone_consistency` | 语气一致性 | 保持专业、客观语气 |
| `length_compliance` | 长度合规 | 符合目标平台偏好长度 |
| `fact_accuracy` | 事实准确性 | 品牌信息准确无误 |
| `geo_optimization` | GEO 优化度 | 符合 GEO 最佳实践 |

### CompetitorAnalyzer（竞品分析 Agent）

| 属性 | 说明 |
|------|------|
| **职责** | 分析竞品的 GEO 表现和策略 |
| **输入** | 竞品名称、查询结果、引用数据 |
| **输出** | 竞品分析报告、SWOT 分析、策略建议 |
| **核心能力** | 竞品数据对比、模式识别、策略推断 |
| **触发方式** | 诊断分析流程中自动触发 |
| **优先级** | P1 |

**分析维度**：
| 维度 | 说明 |
|------|------|
| `citation_share` | 竞品引用份额占比 |
| `platform_presence` | 各平台出现频率 |
| `content_pattern` | 竞品被引用的内容模式 |
| `strength_weakness` | 竞品的优劣势分析 |
| `strategy_inference` | 推测竞品的 GEO 策略 |

### PerformanceTracker（性能追踪 Agent）

| 属性 | 说明 |
|------|------|
| **职责** | 持续追踪品牌 GEO 表现，计算 KPI，检测异常 |
| **输入** | 历史引用数据、当前查询结果、KPI 配置 |
| **输出** | KPI 计算结果、趋势分析、异常告警、优化建议 |
| **核心能力** | 时间序列分析、趋势预测、异常检测 |
| **触发方式** | 按设定周期自动执行 |
| **优先级** | P1 |

**追踪指标**：
| 指标 | 计算方式 | 更新频率 |
|------|----------|----------|
| `citation_rate` | 被引用查询数 / 总查询数 | 每日 |
| `avg_confidence` | 引用记录置信度平均值 | 每次查询 |
| `platform_coverage` | 已覆盖平台数 / 目标平台数 | 每周 |
| `ranking_position` | 品牌在引用中的平均排名 | 每周 |
| `competitor_gap` | 品牌引用率 - 竞品平均引用率 | 每周 |

## 通信协议

### Agent 间通信模型

GEO 平台 Agent 之间采用 **基于 Redis 消息队列的异步通信协议**。

```
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  Agent A    │◀────▶│   Redis     │◀────▶│  Agent B    │
│ (Producer)  │      │   Queue     │      │ (Consumer)  │
└─────────────┘      └──────┬──────┘      └─────────────┘
                            │
                     ┌──────▼──────┐
                     │  Registry   │
                     │ (Hash Map)  │
                     └─────────────┘
```

### 消息格式规范

```python
class AgentMessage:
    """Agent 间通信消息标准格式"""
    
    message_id: str          # UUID，消息唯一标识
    timestamp: datetime      # ISO 8601 格式时间戳
    sender: str              # 发送方 Agent 名称
    recipient: str           # 接收方 Agent 名称，或 "broadcast"
    message_type: str        # 消息类型
    correlation_id: str      # 关联 ID，用于追踪请求-响应链路
    reply_to: str            # 回复目标 Agent
    payload: dict            # 消息负载数据
    ttl: int                 # 消息存活时间（秒），默认 300
```

**消息类型（message_type）**：
| 类型 | 说明 | 使用场景 |
|------|------|----------|
| `task_request` | 任务请求 | Agent A 请求 Agent B 执行任务 |
| `task_result` | 任务结果 | Agent B 返回任务执行结果 |
| `status_update` | 状态更新 | Agent 上报自身状态变化 |
| `heartbeat` | 心跳 | Agent 定期发送健康信号 |
| `config_update` | 配置更新 | 通知 Agent 配置变更 |
| `error_report` | 错误报告 | Agent 报告执行错误 |

### 消息负载（payload）规范

```python
class TaskPayload:
    """任务请求/结果负载"""
    
    task_id: str             # 任务唯一标识
    task_type: str           # 任务类型
    parameters: dict         # 任务参数
    data: dict               # 输入/输出数据
    priority: int            # 优先级 1-10，默认 5
    deadline: datetime       # 截止时间（可选）
    retry_count: int         # 已重试次数
    max_retries: int         # 最大重试次数
```

### 通信模式

#### 1. 点对点模式（Point-to-Point）

```
Agent A ──task_request──▶ Queue ──▶ Agent B
Agent A ◀──task_result─── Queue ◀── Agent B
```

- 每个 Agent 有专属的输入队列
- 任务按轮询方式分配
- 适用于明确的任务分配场景

#### 2. 发布/订阅模式（Pub/Sub）

```
Agent A ──config_update──▶ Topic
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
        Agent B         Agent C         Agent D
```

- 使用 Redis Pub/Sub 频道
- 适用于配置变更、状态广播

#### 3. 工作流模式（Workflow）

```
┌────────────┐    ┌────────────┐    ┌────────────┐
│ QueryTask  │───▶│ Citation   │───▶│ Report     │
│  Completed │    │ Detector   │    │ Generator  │
└────────────┘    └────────────┘    └────────────┘
```

- 基于事件驱动的工作流编排
- 使用 correlation_id 串联整个工作流
- 支持并行和串行执行

## 注册机制

### Agent 注册流程

```
Agent 启动
    │
    ▼
读取配置（能力声明、资源需求、版本信息）
    │
    ▼
连接 Redis
    │
    ▼
向 Registry 注册
    │
    ▼
创建专属输入队列
    │
    ▼
启动心跳定时器
    │
    ▼
开始监听任务
```

### Registry 数据结构

```python
# Redis Hash: agent:registry:{agent_name}
{
    "name": "CitationDetector",
    "version": "1.0.0",
    "capabilities": "[\"citation_detect\", \"entity_recognition\"]",
    "status": "online",           # online / busy / offline
    "queue_name": "agent:citation_detector",
    "registered_at": "2026-01-01T00:00:00Z",
    "last_heartbeat": "2026-01-01T00:01:00Z",
    "current_task": "task_123",   # 当前执行任务 ID，空闲时为 null
    "concurrency": 5,             # 最大并发数
    "load": 0.6                   # 当前负载 0-1
}
```

### 服务发现

```python
# 获取所有在线 Agent
agents = redis.hgetall("agent:registry:*")
online_agents = [a for a in agents if a.status == "online"]

# 按能力筛选 Agent
capable_agents = [a for a in online_agents if "citation_detect" in a.capabilities]

# 选择负载最低的 Agent
selected = min(capable_agents, key=lambda a: a.load)
```

## 任务分发

### 分发策略

| 策略 | 说明 | 适用场景 |
|------|------|----------|
| `round_robin` | 轮询分配 | 同类型 Agent 负载均衡 |
| `least_load` | 最低负载优先 | 不同 Agent 性能差异时 |
| `capability_match` | 能力匹配 | 需要特定能力的任务 |
| `priority_queue` | 优先级队列 | 任务有明确优先级差异 |
| `sticky` | 粘性分配 | 需要上下文连续性的任务 |

### 任务分发流程

```
任务提交
    │
    ▼
解析任务类型 ──▶ 确定所需能力
    │
    ▼
查询 Registry ──▶ 筛选可用 Agent
    │
    ▼
应用分发策略 ──▶ 选择目标 Agent
    │
    ▼
序列化消息 ──▶ 写入目标队列
    │
    ▼
更新任务状态 ──▶ 等待结果
```

### 任务状态机

```
┌──────────┐    提交任务     ┌──────────┐
│  PENDING │───────────────▶│  QUEUED  │
└──────────┘               └─────┬────┘
                                 │ 入队
                                 ▼
                           ┌──────────┐
                    开始执行│ RUNNING  │
                   ┌───────┤          │
                   │       └─────┬────┘
                   │             │
              执行成功         执行失败
                   │             │
                   ▼             ▼
            ┌──────────┐   ┌──────────┐
            │COMPLETED │   │  FAILED  │
            └──────────┘   └─────┬────┘
                                 │
                    重试次数 < 最大重试
                                 │
                                 ▼
                           ┌──────────┐
                           │  RETRY   │
                           └────┬─────┘
                                │ 重新入队
                                └────▶ QUEUED
```

## 状态上报

### 上报内容

每个 Agent 需要定期上报以下状态信息：

| 字段 | 说明 | 上报频率 |
|------|------|----------|
| `status` | 当前状态 | 每次变化 + 心跳 |
| `current_task` | 正在执行的任务 | 每次变化 |
| `load` | 当前负载 0-1 | 心跳时 |
| `queue_depth` | 待处理任务数 | 心跳时 |
| `processed_count` | 已处理任务总数 | 心跳时 |
| `error_count` | 错误次数 | 心跳时 |
| `avg_process_time` | 平均处理时间 | 心跳时 |

### 心跳机制

```python
# 心跳间隔：30 秒
HEARTBEAT_INTERVAL = 30

# 心跳超时判定：90 秒（3 个心跳周期）
HEARTBEAT_TIMEOUT = 90

# 心跳消息格式
heartbeat_message = {
    "message_type": "heartbeat",
    "sender": "CitationDetector",
    "timestamp": "2026-01-01T00:01:00Z",
    "payload": {
        "status": "online",
        "load": 0.4,
        "queue_depth": 2,
        "processed_count": 150,
        "error_count": 3,
        "avg_process_time": 2.5
    }
}
```

### 状态监控

- Registry 定期检查 Agent 心跳超时
- 超时 Agent 自动标记为 `offline`
- 正在执行的任务自动重新分发
- 管理员可通过 Dashboard 查看 Agent 状态

## 配置管理

### 配置层级

| 层级 | 说明 | 优先级 |
|------|------|--------|
| `system_default` | 系统默认配置 | 最低 |
| `tenant_config` | 租户级配置（覆盖默认） | 中 |
| `agent_override` | Agent 本地配置（覆盖租户） | 最高 |

### 配置项

```python
class AgentConfig:
    """Agent 配置项"""
    
    # 通用配置
    max_concurrency: int = 5           # 最大并发数
    task_timeout: int = 300            # 任务超时时间（秒）
    retry_policy: str = "exponential"  # 重试策略
    max_retries: int = 3               # 最大重试次数
    
    # CitationDetector 专用
    confidence_threshold: float = 0.7  # 置信度阈值
    enable_semantic_analysis: bool = True
    
    # ContentGenerator 专用
    default_content_length: int = 1500
    content_styles: List[str] = ["professional", "casual", "technical"]
    
    # RuleChecker 专用
    strict_mode: bool = False
    custom_rules: List[dict] = []
```

### 动态配置更新

```
管理员更新配置
    │
    ▼
写入 Redis 配置存储
    │
    ▼
发布 config_update 消息
    │
    ▼
各 Agent 接收消息
    │
    ▼
Agent 热重载配置（无需重启）
```

## 管理功能需求

### Agent Dashboard

管理员需要通过 Dashboard 监控和管理所有 Agent：

| 功能 | 说明 | 优先级 |
|------|------|--------|
| Agent 列表 | 查看所有已注册 Agent 的状态 | P0 |
| 实时状态看板 | 展示 Agent 在线状态、负载、任务数 | P0 |
| 任务队列监控 | 查看各队列的待处理任务数 | P0 |
| 任务执行日志 | 查看任务执行的详细日志 | P1 |
| 错误告警 | Agent 异常时发送告警通知 | P1 |
| 配置管理 | 在线修改 Agent 配置 | P1 |
| Agent 启停 | 远程启动或停止 Agent | P2 |
| 版本管理 | 查看和升级 Agent 版本 | P2 |
| 性能统计 | 查看 Agent 的性能指标和趋势 | P2 |

### Agent 日志规范

```python
# 日志格式
{
    "timestamp": "2026-01-01T00:00:00Z",
    "level": "INFO",          # DEBUG / INFO / WARNING / ERROR
    "agent": "CitationDetector",
    "task_id": "task_123",
    "message": "开始执行引用检测",
    "metadata": {
        "query_id": "q_456",
        "brand": "ExampleBrand"
    }
}
```

### 错误处理

| 错误类型 | 处理方式 | 告警级别 |
|----------|----------|----------|
| 任务执行失败 | 自动重试，达到最大重试后标记失败 | Warning |
| Agent 心跳超时 | 标记离线，任务重新分发 | Error |
| 队列积压 | 触发弹性扩容或告警 | Warning |
| Agent 崩溃 | 自动重启（配合 supervisor） | Critical |
| 配置错误 | 拒绝加载，保持上次有效配置 | Error |

---

*本文档定义 GEO 平台的 AI Agent 框架设计，各 Agent 的具体实现算法和模型选型在模块指南中详细说明。*