# GEO 平台新增 Agent 实现计划

**Status:** Draft
**Type:** feat
**Created:** 2026-05-28
**Updated:** 2026-05-28

## Summary

为 GEO 平台新增 4 个专业 Agent，构建完整的监测-分析-优化闭环：

1. **MonitorAgent** — 效果追踪：定期检测内容发布后的引用变化
2. **SchemaAdvisor** — Schema优化：根据诊断结果推荐具体的 Schema 标记方案
3. **CompetitorAnalyzer** — 竞品分析：深度分析竞品内容策略、引用模式
4. **TrendAgent** — 趋势洞察：分析行业 AI 搜索趋势、热点话题

---

## Problem Frame

当前 GEO 平台已有 4 个 Agent（CitationDetector、ContentGenerator、DeAIAgent、GEOOptimizer），覆盖检测→生成→去AI化→优化链路。但缺少：

- **效果追踪**：内容发布后无法自动追踪引用变化
- **Schema 优化**：诊断发现 Schema 问题但没有 Agent 提供具体方案
- **竞品深度分析**：仅做引用检测，缺乏策略层面的竞品分析
- **趋势洞察**：无法感知行业 AI 搜索趋势和热点话题

这 4 个 Agent 的缺失导致 GEO 平台只能发现问题，无法主动建议行动方向。

---

## Scope Boundaries

### In Scope
- 4 个新 Agent 的完整实现
- Agent 注册和调度集成
- 相应的数据模型和 API
- 前端展示（可选，取决于 API 完备性）

### Out of Scope
- 不实现前端页面（只提供 API，供现有页面调用）
- 不实现自动执行闭环（内容发布后的自动追踪需要分发系统配合）
- TrendAgent 的第三方数据源集成（仅使用现有 AI 引擎返回的引用数据）

---

## Key Technical Decisions

### KTD-1: MonitorAgent 触发方式

**Decision:** 采用「定时任务 + 手动触发」双模式

**Rationale:** 自动追踪需要内容分发系统配合，目前分发系统仅支持手动发布。定时任务模式可覆盖已有内容的手动追踪需求。手动触发作为 API 入口，可被前端页面直接调用。

**Alternatives considered:**
- 仅定时任务：无法满足用户即时查询需求
- 仅手动触发：无法实现自动化效果追踪

### KTD-2: SchemaAdvisor 生成策略

**Decision:** 采用「规则模板 + LLM 增强」混合模式

**Rationale:** Schema 标记有明确的规范（JSON-LD 格式），规则模板可覆盖 80% 常见场景。LLM 用于生成描述性内容（如 FAQ 的 questions/answers）和处理边界情况。

**Alternatives considered:**
- 纯规则：无法处理动态内容场景
- 纯 LLM：Schema 格式要求严格，纯 LLM 生成可能不合规

### KTD-3: CompetitorAnalyzer 数据来源

**Decision:** 复用现有 CitationDetector 的检测数据

**Rationale:** 竞品分析依赖品牌和竞品的引用数据，现有 CitationDetector 已实现全量检测能力。新 Agent 只需在检测结果基础上做策略分析，避免重复建设。

**Alternatives considered:**
- 独立检测通道：增加 API 调用成本和数据冗余
- 仅分析历史数据：无法获取最新竞品动态

### KTD-4: TrendAgent 趋势识别

**Decision:** 基于「品牌领域关键词 + AI 引擎引用模式」识别趋势

**Rationale:** TrendAgent 的定位是「GEO 趋势洞察」而非「通用舆情分析」。通过分析品牌核心关键词在 AI 引擎中的引用模式变化，可以识别用户关注度趋势，无需引入外部数据源。

**Alternatives considered:**
- 接入第三方舆情 API：成本高、数据不精准
- 基于社交媒体趋势：与 GEO 关联度低

---

## High-Level Technical Design

### 4 Agent 在现有架构中的位置

```
┌──────────────────────────────────────────────────────────────────┐
│                    Agent Framework (Dispatcher)                  │
└──────────────────────────────────────────────────────────────────┘
                              │
      ┌───────────┬───────────┼───────────┬───────────┐
      ▼           ▼           ▼           ▼           ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│Citation  │ │Monitor   │ │Schema    │ │Competitor│ │Trend     │
│Detector  │ │Agent 🆕  │ │Advisor 🆕│ │Analyzer 🆕│ │Agent 🆕  │
│          │ │          │ │          │ │          │ │          │
│引用检测   │ │效果追踪   │ │Schema    │ │竞品策略   │ │趋势洞察   ││
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
     │            │            │            │            │
     ▼            ▼            ▼            ▼            ▼
 CitationRecord  MonitoringRecord  SchemaSuggestion  CompetitorInsight  TrendInsight
     │            │            │            │            │
     ▼            ▼            ▼            ▼            ▼
  ScoringService  GeoPlanGenerator  DiagnosisReport  StrategyPage   Dashboard
```

### MonitorAgent 数据流

```
内容发布 → 记录监测任务 → 定时执行检测 → 对比基线数据 → 生成变化报告 → 更新评分
                                    │
                            ┌───────┴───────┐
                            │ 变化类型判断   │
                            ├───────────────┤
                            │ + 引用量增加   │ → 正面反馈
                            │ - 引用量下降   │ → 告警 + 建议
                            │ = 无变化       │ → 持续观察
                            └───────────────┘
```

### SchemaAdvisor 建议生成

```
诊断数据 → 识别 Schema 缺失维度 → 匹配模板 → 生成 JSON-LD → LLM 填充内容 → 验证格式
                                                              │
                                                      ┌───────┴───────┐
                                                      │  格式验证通过  │ → 返回建议
                                                      │  格式验证失败  │ → 回退到规则
                                                      └───────────────┘
```

---

## Implementation Units

### U1. MonitorAgent — 效果追踪 Agent

**Goal:** 实现内容发布后引用变化的自动追踪和对比分析

**Requirements:** R1（效果追踪）

**Files:**
- `app/agent_framework/agents/monitor_agent.py` (新增)
- `app/models/monitoring.py` (新增)
- `app/schemas/monitoring.py` (新增)
- `app/services/monitoring/monitor_service.py` (新增)
- `app/api/monitoring.py` (新增)
- `tests/test_monitor_agent.py` (新增)

**Approach:**
1. 数据模型：`MonitoringRecord` 记录监测任务，`ContentBaseline` 存储发布时的基线数据
2. Agent 逻辑：接收监测任务 → 提取关键词和平台 → 调用 CitationService 检测 → 对比基线 → 生成变化报告
3. 变化判断：基于引用量、情感倾向、引用排名三个维度计算变化幅度
4. API：提供创建监测任务、查询监测历史、获取变化报告的端点

**Test scenarios:**
- Happy path: 内容发布后创建监测任务，定时检测对比基线，生成正面/负面/无变化报告
- Edge case: 基线数据为空时，使用首次检测作为基线
- Error path: 检测服务不可用时，记录失败状态并重试
- Integration: 监测任务触发时，通过 Dispatcher 正确分发给 MonitorAgent

---

### U2. SchemaAdvisor — Schema 优化建议 Agent

**Goal:** 根据诊断结果生成具体的 Schema 标记方案

**Requirements:** R2（Schema 优化）

**Files:**
- `app/agent_framework/agents/schema_advisor.py` (新增)
- `app/models/schema_suggestion.py` (新增)
- `app/schemas/schema_suggestion.py` (新增)
- `app/services/schema/schema_advisor_service.py` (新增)
- `app/api/schema_advisor.py` (新增)
- `tests/test_schema_advisor.py` (新增)

**Approach:**
1. 诊断数据输入：接收 GEO 诊断结果，识别 Schema 缺失维度
2. 模板匹配：5 种 Schema 类型 × 3 种场景 = 15 个预定义模板
   - Organization: 品牌主页
   - Product: 产品详情页
   - FAQPage: 常见问题页
   - Article: 博客/新闻页
   - LocalBusiness: 本地商户页
3. LLM 增强：使用 LLM 生成 FAQ 的 questions/answers、Product 描述等自然语言内容
4. 格式验证：使用 JSON-LD 解析器验证生成结果的语法正确性
5. 优先级排序：基于诊断得分和实施难度排序建议

**Test scenarios:**
- Happy path: 诊断发现 FAQPage 缺失，生成完整的 FAQPage JSON-LD
- Edge case: LLM 生成内容格式错误，回退到规则模板
- Error path: 模板不存在时，返回"暂不支持该场景"的友好提示
- Format validation: 生成的 JSON-LD 通过 schema.org 验证

---

### U3. CompetitorAnalyzer — 竞品策略分析 Agent

**Goal:** 在引用检测数据基础上，深度分析竞品的内容策略和引用模式

**Requirements:** R3（竞品分析）

**Files:**
- `app/agent_framework/agents/competitor_analyzer.py` (新增)
- `app/models/competitor_insight.py` (新增)
- `app/schemas/competitor_insight.py` (新增)
- `app/services/competitor/competitor_analyzer_service.py` (新增)
- `app/api/competitor_analysis.py` (新增)
- `tests/test_competitor_analyzer.py` (新增)

**Approach:**
1. 数据聚合：聚合品牌和所有竞品的引用检测数据
2. 维度分析：
   - 引用量对比：品牌 vs 竞品在各平台的引用次数
   - 引用质量对比：正面/中性/负面引用比例
   - 引用场景分析：竞品在哪些查询词下被引用
   - 内容策略推断：竞品引用内容的类型（产品介绍/评测/新闻等）
3. Gap 识别：对比发现品牌在哪些维度落后于竞品
4. 机会发现：竞品未被引用的场景，即品牌的潜在机会
5. 策略建议：基于分析结果生成"缩小差距"和"差异化竞争"两类建议

**Test scenarios:**
- Happy path: 品牌 vs 3个竞品，生成完整的竞品分析报告
- Edge case: 竞品数据不足（少于5次引用），标记为"数据不足"并说明
- Error path: 竞品数据获取失败，生成部分报告并提示缺失数据
- Content strategy: 识别竞品的内容类型分布，给出差异化建议

---

### U4. TrendAgent — 趋势洞察 Agent

**Goal:** 分析品牌领域关键词在 AI 引擎中的引用模式变化，识别趋势

**Requirements:** R4（趋势洞察）

**Files:**
- `app/agent_framework/agents/trend_agent.py` (新增)
- `app/models/trend_insight.py` (新增)
- `app/schemas/trend_insight.py` (新增)
- `app/services/trend/trend_analyzer_service.py` (新增)
- `app/api/trends.py` (新增)
- `tests/test_trend_agent.py` (新增)

**Approach:**
1. 时间序列分析：聚合品牌关键词在过去 N 天的引用数据（按天/周粒度）
2. 趋势识别算法：
   - 上升趋势：引用量环比增长 > 20%
   - 下降趋势：引用量环比下降 > 20%
   - 平稳趋势：变化率在 ±20% 以内
3. 热点发现：引用量突增的关键词/话题
4. 平台差异：同一趋势在不同 AI 引擎的差异表现
5. 原因推断：结合情感分析推断趋势变化的可能原因（正面事件/负面事件/行业热点）

**Test scenarios:**
- Happy path: 分析过去30天数据，识别3个上升趋势、2个下降趋势、5个热点话题
- Edge case: 数据不足30天，使用可用数据进行趋势分析并注明
- Error path: 引用数据获取失败，返回"趋势分析需要至少7天数据"提示
- Platform comparison: 识别同一趋势在文心 vs Kimi 的差异

---

### U5. Agent 注册和调度集成

**Goal:** 将 4 个新 Agent 注册到 Agent Framework，支持 Dispatcher 统一调度

**Requirements:** 所有 R1-R4

**Dependencies:** U1, U2, U3, U4

**Files:**
- `app/agent_framework/registry.py` (修改)
- `app/agent_framework/protocol.py` (修改)

**Approach:**
1. 在 `protocol.py` 中定义 4 种新任务类型：
   - `monitor_track` — 效果追踪
   - `schema_advise` — Schema 建议
   - `competitor_analyze` — 竞品分析
   - `trend_insight` — 趋势洞察
2. 在 `registry.py` 中注册 4 个 Agent 类
3. 验证 Dispatcher 可正确分发任务到对应 Agent

**Test scenarios:**
- Happy path: Dispatcher 分发 `monitor_track` 任务到 MonitorAgent
- Happy path: Dispatcher 分发 `schema_advise` 任务到 SchemaAdvisor
- Edge case: 未知任务类型返回"Agent not found"错误

---

### U6. 数据库迁移

**Goal:** 创建新 Agent 所需的数据库表

**Dependencies:** U1, U2, U3, U4

**Files:**
- `alembic/versions/xxxx_add_new_agent_tables.py` (新增)

**Approach:**
1. 生成 Alembic 迁移脚本
2. 创建 5 张新表：
   - `monitoring_records` — 监测记录
   - `content_baselines` — 内容基线
   - `schema_suggestions` — Schema 建议
   - `competitor_insights` — 竞品洞察
   - `trend_insights` — 趋势洞察
3. 执行迁移并验证

**Test scenarios:**
- Happy path: 迁移脚本成功执行，5张表创建完成
- Rollback: 执行 downgrade 后，表被正确删除

---

## Open Questions

| # | Question | Resolution |
|---|----------|------------|
| 1 | MonitorAgent 的定时检测间隔是多少？ | 建议默认 24 小时，支持用户配置（1h/6h/24h/7d） |
| 2 | SchemaAdvisor 是否需要验证生成的 Schema 在目标网站上可正常解析？ | 否，验证 JSON-LD 语法即可，网站解析验证超出当前范围 |
| 3 | TrendAgent 历史数据保留多久？ | 建议保留 90 天，超出后归档或删除 |
| 4 | 4 个新 Agent 是否需要独立启动入口（类似 standalone.py）？ | 否，通过 API 触发即可，无独立常驻需求 |

---

## System-Wide Impact

- **数据库**：新增 5 张表，需要 Alembic 迁移
- **API 层**：新增 4 个路由模块（monitoring.py, schema_advisor.py, competitor_analysis.py, trends.py）
- **Agent Framework**：新增 4 种任务类型注册
- **前端**：可选，取决于是否需要页面展示（当前计划仅提供 API）

---

## Deferred to Follow-Up Work

1. **前端监测页面**：MonitorAgent 的效果追踪报告需要页面展示
2. **自动执行闭环**：内容发布后自动创建监测任务（依赖分发系统）
3. **告警集成**：监测到负面变化时自动触发告警通知
4. **定时调度**：TrendAgent 的周期性趋势报告（依赖 APScheduler 集成）

---

## Verification

### 编译验证
```bash
cd geo/backend && python -m py_compile app/agent_framework/agents/monitor_agent.py app/agent_framework/agents/schema_advisor.py app/agent_framework/agents/competitor_analyzer.py app/agent_framework/agents/trend_agent.py
```

### API 验证
```bash
# MonitorAgent
curl -X POST http://localhost:8000/api/v1/monitoring/tasks -H "Authorization: Bearer $TOKEN" -d '{"content_id": "xxx", "brand_id": "yyy"}'

# SchemaAdvisor
curl -X POST http://localhost:8000/api/v1/schema/advise -H "Authorization: Bearer $TOKEN" -d '{"brand_id": "yyy"}'

# CompetitorAnalyzer
curl -X POST http://localhost:8000/api/v1/competitor/analyze -H "Authorization: Bearer $TOKEN" -d '{"brand_id": "yyy"}'

# TrendAgent
curl -X POST http://localhost:8000/api/v1/trends/insight -H "Authorization: Bearer $TOKEN" -d '{"brand_id": "yyy", "days": 30}'
```

### Agent 调度验证
```bash
# 通过 Agent Framework 调度
curl -X POST http://localhost:8000/api/v1/agents/tasks -H "Authorization: Bearer $TOKEN" -d '{
  "agent_type": "monitor",
  "task_type": "monitor_track",
  "params": {"content_id": "xxx", "brand_id": "yyy"}
}'
```