# 核心功能

<cite>
**本文档引用的文件**
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/api/auth.py](file://backend/app/api/auth.py)
- [backend/app/api/queries.py](file://backend/app/api/queries.py)
- [backend/app/api/citations.py](file://backend/app/api/citations.py)
- [backend/app/api/reports.py](file://backend/app/api/reports.py)
- [backend/app/api/lifecycle.py](file://backend/app/api/lifecycle.py)
- [backend/app/api/knowledge.py](file://backend/app/api/knowledge.py)
- [backend/app/services/auth.py](file://backend/app/services/auth.py)
- [backend/app/services/query.py](file://backend/app/services/query.py)
- [backend/app/services/citation.py](file://backend/app/services/citation.py)
- [backend/app/services/analytics/tracker.py](file://backend/app/services/analytics/tracker.py)
- [backend/app/services/analytics/insights.py](file://backend/app/services/analytics/insights.py)
- [backend/app/services/knowledge/rag_service.py](file://backend/app/services/knowledge/rag_service.py)
- [backend/app/agent_framework/agents/__init__.py](file://backend/app/agent_framework/agents/__init__.py)
- [backend/app/agent_framework/agents/citation_detector.py](file://backend/app/agent_framework/agents/citation_detector.py)
- [backend/app/agent_framework/agents/content_generator_agent.py](file://backend/app/agent_framework/agents/content_generator_agent.py)
- [backend/app/agent_framework/agents/deai_agent.py](file://backend/app/agent_framework/agents/deai_agent.py)
- [backend/app/agent_framework/agents/geo_optimizer_agent.py](file://backend/app/agent_framework/agents/geo_optimizer_agent.py)
- [backend/app/agent_framework/pipeline/engine.py](file://backend/app/agent_framework/pipeline/engine.py)
- [backend/app/agent_framework/pipeline/loader.py](file://backend/app/agent_framework/pipeline/loader.py)
- [backend/app/agent_framework/dispatcher.py](file://backend/app/agent_framework/dispatcher.py)
- [backend/app/models/query.py](file://backend/app/models/query.py)
- [backend/app/models/citation_record.py](file://backend/app/models/citation_record.py)
- [backend/app/models/lifecycle.py](file://backend/app/models/lifecycle.py)
- [backend/app/models/knowledge.py](file://backend/app/models/knowledge.py)
- [backend/alembic/versions/d4f6g8h0ab23_add_geo_lifecycle_tables.py](file://backend/alembic/versions/d4f6g8h0ab23_add_geo_lifecycle_tables.py)
- [backend/workers/scheduler.py](file://backend/workers/scheduler.py)
- [backend/workers/citation_engine.py](file://backend/workers/citation_engine.py)
- [backend/workers/platforms/base.py](file://backend/workers/platforms/base.py)
- [frontend/app/(dashboard)/dashboard/page.tsx](file://frontend/app/(dashboard)/dashboard/page.tsx)
- [frontend/app/(dashboard)/dashboard/admin/page.tsx](file://frontend/app/(dashboard)/dashboard/admin/page.tsx)
- [frontend/app/(dashboard)/dashboard/agents/page.tsx](file://frontend/app/(dashboard)/dashboard/agents/page.tsx)
- [frontend/app/(dashboard)/dashboard/analytics/page.tsx](file://frontend/app/(dashboard)/dashboard/analytics/page.tsx)
- [frontend/app/(dashboard)/dashboard/lifecycle/page.tsx](file://frontend/app/(dashboard)/dashboard/lifecycle/page.tsx)
- [frontend/app/(dashboard)/dashboard/knowledge/page.tsx](file://frontend/app/(dashboard)/dashboard/knowledge/page.tsx)
- [frontend/components/charts/trend-chart.tsx](file://frontend/components/charts/trend-chart.tsx)
- [frontend/lib/api/lifecycle.ts](file://frontend/lib/api/lifecycle.ts)
</cite>

## 更新摘要
**变更内容**
- 新增AI代理框架模块，包含引用检测、内容生成、去AI化、GEO优化等智能代理
- 新增业务生命周期管理系统，支持品牌项目全生命周期管理
- 新增分析监控系统，提供发布追踪、效果分析和智能洞察生成功能
- 新增知识库服务模块，支持RAG检索、文档管理和知识库CRUD操作
- 扩展前端界面，新增代理管理、分析监控、生命周期管理和知识库管理页面

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件为 GEO 平台的核心功能概览，聚焦以下关键能力：
- 用户认证与权限管理：基于邮箱/密码注册登录、JWT 访问令牌签发与校验、会话保护接口。
- 智能查询任务管理：查询词创建、更新、删除、分页查询；按日/周/月频率自动调度；手动触发即时查询。
- 品牌引用检测引擎：多阶段匹配（精确/别名/模糊）、置信度评分、竞争品牌识别、上下文片段抽取。
- 多AI平台数据集成：抽象适配器模式对接不同大模型平台，统一查询与结果处理。
- AI代理框架：基于Pipeline的多代理协作系统，支持引用检测、内容生成、去AI化、GEO优化等智能任务编排。
- 业务生命周期管理：品牌项目全生命周期管理，包含5个阶段的项目推进和状态跟踪。
- 分析监控系统：发布效果追踪、内容表现分析、智能洞察生成和性能监控。
- 知识库服务：RAG检索、文档管理、知识库CRUD操作和搜索日志记录。
- 数据分析与可视化：统计指标（总查询/引用次数、引用率、平均位置）、平台对比、30 天趋势折线图。
- 报告导出：CSV 导出引用记录，便于离线分析与归档。

这些功能围绕"查询—检测—智能代理—生命周期—分析监控—知识库—统计—可视—导出"的完整生态展开，既满足管理员对系统运行与任务调度的掌控，也服务于研究人员对品牌监测与趋势分析的需求。

## 项目结构
后端采用 FastAPI + SQLAlchemy 异步 ORM，按领域划分 API、服务、模型与工作器；前端使用 Next.js + React，通过自定义 API 客户端与后端交互；数据库为 PostgreSQL。

```mermaid
graph TB
subgraph "后端"
A["FastAPI 应用<br/>app/main.py"]
B["API 层<br/>auth/queries/citations/reports/lifecycle/knowledge"]
C["服务层<br/>auth/query/citation/analytics/knowledge"]
D["模型层<br/>Query/CitationRecord/Lifecycle/Knowledge"]
E["工作器<br/>Scheduler/CitationEngine/Platforms"]
F["AI代理框架<br/>Agents/Pipeline/Dispatcher"]
G["分析监控<br/>Tracker/Insights"]
H["知识库服务<br/>RAGService/Chunker/Embedder"]
end
subgraph "前端"
I["仪表盘页面<br/>dashboard/page.tsx"]
J["管理员页面<br/>admin/page.tsx"]
K["代理管理页面<br/>agents/page.tsx"]
L["分析监控页面<br/>analytics/page.tsx"]
M["生命周期页面<br/>lifecycle/page.tsx"]
N["知识库页面<br/>knowledge/page.tsx"]
O["趋势图表组件<br/>trend-chart.tsx"]
end
A --> B
B --> C
C --> D
C --> E
C --> F
C --> G
C --> H
I --> O
I --> B
J --> B
K --> F
L --> G
M --> D
N --> H
```

**图表来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [backend/app/api/reports.py:1-47](file://backend/app/api/reports.py#L1-L47)
- [backend/app/api/lifecycle.py:1-297](file://backend/app/api/lifecycle.py#L1-L297)
- [backend/app/api/knowledge.py:1-502](file://backend/app/api/knowledge.py#L1-L502)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/services/citation.py:1-269](file://backend/app/services/citation.py#L1-L269)
- [backend/app/services/analytics/tracker.py:1-230](file://backend/app/services/analytics/tracker.py#L1-L230)
- [backend/app/services/analytics/insights.py:1-313](file://backend/app/services/analytics/insights.py#L1-L313)
- [backend/app/services/knowledge/rag_service.py:1-43](file://backend/app/services/knowledge/rag_service.py#L1-L43)
- [backend/app/agent_framework/agents/__init__.py:1-14](file://backend/app/agent_framework/agents/__init__.py#L1-L14)
- [backend/app/agent_framework/pipeline/engine.py:1-536](file://backend/app/agent_framework/pipeline/engine.py#L1-L536)
- [backend/app/agent_framework/dispatcher.py:1-367](file://backend/app/agent_framework/dispatcher.py#L1-L367)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/citation_record.py:1-42](file://backend/app/models/citation_record.py#L1-L42)
- [backend/app/models/lifecycle.py:1-91](file://backend/app/models/lifecycle.py#L1-L91)
- [backend/app/models/knowledge.py:1-43](file://backend/app/models/knowledge.py#L1-L43)
- [backend/workers/scheduler.py:1-95](file://backend/workers/scheduler.py#L1-L95)
- [backend/workers/citation_engine.py:1-309](file://backend/workers/citation_engine.py#L1-L309)
- [frontend/app/(dashboard)/dashboard/page.tsx:1-156](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L156)
- [frontend/app/(dashboard)/dashboard/admin/page.tsx:1-200](file://frontend/app/(dashboard)/dashboard/admin/page.tsx#L1-L200)
- [frontend/app/(dashboard)/dashboard/agents/page.tsx:1-200](file://frontend/app/(dashboard)/dashboard/agents/page.tsx#L1-L200)
- [frontend/app/(dashboard)/dashboard/analytics/page.tsx:1-200](file://frontend/app/(dashboard)/dashboard/analytics/page.tsx#L1-L200)
- [frontend/app/(dashboard)/dashboard/lifecycle/page.tsx:1-200](file://frontend/app/(dashboard)/dashboard/lifecycle/page.tsx#L1-L200)
- [frontend/app/(dashboard)/dashboard/knowledge/page.tsx:1-200](file://frontend/app/(dashboard)/dashboard/knowledge/page.tsx#L1-L200)
- [frontend/components/charts/trend-chart.tsx:1-60](file://frontend/components/charts/trend-chart.tsx#L1-L60)

**章节来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)

## 核心组件
- 认证与权限
  - 注册/登录：邮箱唯一性校验、密码哈希、JWT 签发；当前用户信息读取。
  - 权限边界：所有业务接口均通过当前用户上下文进行资源归属校验（查询、引用、统计、导出、生命周期、知识库）。
- 查询任务管理
  - 查询 CRUD：分页列表、创建、读取、更新、删除；创建时校验用户配额上限；更新时可重算下次执行时间。
  - 自动调度：每小时扫描到期查询，自动触发引用检测；手动触发即时查询。
- 引用检测引擎
  - 多阶段匹配：精确命中 → 别名命中 → 模糊相似度阈值；返回是否引用、置信度、位置、上下文。
  - 竞争品牌：基于预设行业品牌库识别竞品。
  - 结果持久化：生成引用记录，包含平台、是否引用、位置、文本、竞品集合、原始响应。
- 多 AI 平台集成
  - 适配器基类定义统一接口；内置"文心""Kimi"适配器；未来可扩展更多平台。
- AI代理框架
  - 代理实现：引用检测代理、内容生成代理、去AI化代理、GEO优化代理。
  - Pipeline编排：基于YAML的多阶段任务编排，支持变量解析、依赖管理、条件执行。
  - 任务分发：Redis队列驱动的任务分发器，支持任务状态跟踪和重试机制。
- 业务生命周期管理
  - 项目管理：品牌基建、内容生产、AI适配优化、权威信号构建、持续运维5个阶段。
  - 状态跟踪：项目进度、阶段状态、完成率统计和时间轴事件记录。
  - 快速启动：一键创建项目并初始化5个阶段。
- 分析监控系统
  - 发布追踪：内容发布记录、效果指标快照和平台分布统计。
  - 性能分析：内容表现排行、单篇内容深度分析和历史趋势追踪。
  - 智能洞察：基于LLM的自动化洞察生成和优化建议。
- 知识库服务
  - RAG检索：文档分块、向量化嵌入和混合检索。
  - 文档管理：URL抓取、文本上传和分块预览。
  - 知识库CRUD：多租户知识库管理和搜索日志记录。
- 数据分析与可视化
  - 统计聚合：总查询/引用数、引用率、平均位置、按平台汇总、30 天趋势。
  - 前端展示：仪表盘卡片与趋势折线图组件。
- 报告导出
  - 支持 CSV 下载，包含日期、平台、是否引用、引用位置、引用文本、竞品品牌等字段。

**章节来源**
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [backend/app/services/citation.py:1-269](file://backend/app/services/citation.py#L1-L269)
- [backend/app/workers/citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/agent_framework/agents/__init__.py:1-14](file://backend/app/agent_framework/agents/__init__.py#L1-L14)
- [backend/app/agent_framework/pipeline/engine.py:1-536](file://backend/app/agent_framework/pipeline/engine.py#L1-L536)
- [backend/app/agent_framework/dispatcher.py:1-367](file://backend/app/agent_framework/dispatcher.py#L1-L367)
- [backend/app/api/lifecycle.py:1-297](file://backend/app/api/lifecycle.py#L1-L297)
- [backend/app/models/lifecycle.py:1-91](file://backend/app/models/lifecycle.py#L1-L91)
- [backend/app/services/analytics/tracker.py:1-230](file://backend/app/services/analytics/tracker.py#L1-L230)
- [backend/app/services/analytics/insights.py:1-313](file://backend/app/services/analytics/insights.py#L1-L313)
- [backend/app/api/knowledge.py:1-502](file://backend/app/api/knowledge.py#L1-L502)
- [backend/app/services/knowledge/rag_service.py:1-43](file://backend/app/services/knowledge/rag_service.py#L1-L43)
- [frontend/app/(dashboard)/dashboard/page.tsx:1-156](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L156)
- [frontend/components/charts/trend-chart.tsx:1-60](file://frontend/components/charts/trend-chart.tsx#L1-L60)
- [backend/app/api/reports.py:1-47](file://backend/app/api/reports.py#L1-L47)

## 架构总览
下图展示从用户请求到数据落库与可视化的整体流程，以及定时调度、智能代理编排、生命周期管理和分析监控的协同机制。

```mermaid
sequenceDiagram
participant U as "用户"
participant FE as "前端"
participant API as "后端API"
participant S as "服务层"
participant DB as "数据库"
participant W as "工作器"
participant CE as "引用检测引擎"
participant P as "AI平台适配器"
participant AG as "AI代理框架"
participant PL as "Pipeline引擎"
U->>FE : 登录/访问各功能页面
FE->>API : 获取统计/查询/引用/导出/生命周期/知识库
API->>S : 参数校验与业务处理
S->>DB : 读写查询/引用/任务/项目/知识库
Note over S,DB : 权限校验：仅允许访问本人资源
API->>W : 触发/查询任务
W->>CE : 执行查询
CE->>P : 平台查询
P-->>CE : 原始响应
CE->>S : 写入引用记录
S->>DB : 持久化
S->>AG : 分发代理任务
AG->>PL : 执行Pipeline编排
PL->>AG : 代理执行结果
S->>DB : 更新代理状态
DB-->>S : 成功
S-->>API : 结果
API-->>FE : 响应数据/流式下载
```

**图表来源**
- [backend/app/main.py:13-21](file://backend/app/main.py#L13-L21)
- [backend/app/api/citations.py:59-77](file://backend/app/api/citations.py#L59-L77)
- [backend/app/workers/scheduler.py:51-84](file://backend/workers/scheduler.py#L51-L84)
- [backend/app/workers/citation_engine.py:159-234](file://backend/workers/citation_engine.py#L159-L234)
- [backend/app/services/citation.py:204-234](file://backend/app/services/citation.py#L204-L234)
- [backend/app/agent_framework/dispatcher.py:54-117](file://backend/app/agent_framework/dispatcher.py#L54-L117)
- [backend/app/agent_framework/pipeline/engine.py:51-176](file://backend/app/agent_framework/pipeline/engine.py#L51-L176)

## 详细组件分析

### 用户认证与权限管理
- 功能要点
  - 注册：邮箱唯一性检查、密码加密存储、返回用户信息。
  - 登录：邮箱+密码验证、签发 JWT（含过期时间），返回用户与令牌。
  - 当前用户：受保护路由读取当前用户上下文。
- 关键价值
  - 保障数据隔离：所有业务接口均以当前用户为准进行资源归属校验。
  - 易于扩展：JWT 可用于跨域与第三方集成。
- 典型流程
  - 注册 → 登录 → 携带令牌访问受保护接口 → 获取/创建查询 → 触发查询 → 查看统计/导出报告。

```mermaid
sequenceDiagram
participant U as "用户"
participant API as "认证API"
participant S as "认证服务"
participant DB as "数据库"
U->>API : POST /api/v1/auth/register
API->>S : 注册逻辑
S->>DB : 检查邮箱/保存用户
DB-->>S : 成功
S-->>API : 用户对象
U->>API : POST /api/v1/auth/login
API->>S : 验证邮箱/密码
S->>DB : 查询用户
DB-->>S : 用户信息
S-->>API : JWT令牌
API-->>U : {access_token,user}
```

**图表来源**
- [backend/app/api/auth.py:13-37](file://backend/app/api/auth.py#L13-L37)
- [backend/app/services/auth.py:37-69](file://backend/app/services/auth.py#L37-L69)

**章节来源**
- [backend/app/api/auth.py:1-43](file://backend/app/api/auth.py#L1-L43)
- [backend/app/services/auth.py:1-69](file://backend/app/services/auth.py#L1-L69)

### 智能查询任务管理
- 功能要点
  - 查询 CRUD：分页列表、创建（校验配额与频率）、读取、更新（频率变更时重算下次执行时间）、删除。
  - 自动调度：每小时扫描到期查询，调用引用检测引擎执行；更新查询最近与下次执行时间。
  - 即时查询：手动触发，为每个配置平台创建任务并入队。
- 核心价值
  - 减少人工干预：按计划自动抓取与检测，提升研究效率。
  - 灵活控制：支持日/周/月频率与手动触发，兼顾实时性与成本。
- 典型场景
  - 研究员创建查询（关键词、目标品牌、平台、频率），系统按时自动执行；也可随时"立即执行"。

```mermaid
flowchart TD
Start(["创建查询"]) --> CheckLimit["检查用户配额"]
CheckLimit --> |未超限| CalcNext["按频率计算下次执行时间"]
CheckLimit --> |超限| Deny["拒绝创建"]
CalcNext --> SaveQ["保存查询"]
SaveQ --> Schedule["等待调度器扫描"]
Schedule --> Due{"到期？"}
Due --> |否| Wait["继续等待"]
Due --> |是| Trigger["触发引用检测"]
Trigger --> UpdateTime["更新最近/下次执行时间"]
UpdateTime --> Done(["完成一轮周期"])
```

**图表来源**
- [backend/app/services/query.py:45-81](file://backend/app/services/query.py#L45-L81)
- [backend/app/workers/scheduler.py:51-84](file://backend/workers/scheduler.py#L51-L84)
- [backend/app/workers/citation_engine.py:291-300](file://backend/app/workers/citation_engine.py#L291-L300)

**章节来源**
- [backend/app/api/queries.py:1-86](file://backend/app/api/queries.py#L1-L86)
- [backend/app/services/query.py:1-130](file://backend/app/services/query.py#L1-L130)
- [backend/app/workers/scheduler.py:1-95](file://backend/workers/scheduler.py#L1-L95)

### 品牌引用检测引擎
- 功能要点
  - 品牌匹配器：精确命中（置信度1.0）→ 别名命中（置信度0.9）→ 模糊相似度（阈值0.4）；返回是否引用、置信度、位置、上下文。
  - 竞争品牌检测：基于预设行业品牌库识别其他品牌。
  - 结果持久化：记录平台、是否引用、位置、文本、竞品、原始响应。
- 核心价值
  - 置信度评分：帮助判断引用可靠性；模糊匹配提供兜底发现。
  - 上下文定位：快速定位品牌在原文中的首次出现段落，便于人工复核。
- 典型场景
  - 文本中提及"XX品牌"，匹配器判定为"别名命中"，置信度0.9，并返回首次出现段落片段。

```mermaid
classDiagram
class CitationEngine {
+execute_query(query, db) CitationRecord[]
+execute_single_platform(keyword, platform, target_brand, aliases) dict
}
class BrandMatcher {
+match(text) dict
}
class CompetitorDetector {
+detect(text, target_brand) str[]
}
class BasePlatformAdapter {
<<abstract>>
+query(keyword) str
}
CitationEngine --> BrandMatcher : "使用"
CitationEngine --> CompetitorDetector : "使用"
CitationEngine --> BasePlatformAdapter : "委托查询"
```

**图表来源**
- [backend/app/workers/citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)

**章节来源**
- [backend/app/workers/citation_engine.py:19-120](file://backend/app/workers/citation_engine.py#L19-L120)
- [backend/app/workers/citation_engine.py:122-146](file://backend/app/workers/citation_engine.py#L122-L146)
- [backend/app/workers/citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)

### 多 AI 平台数据集成
- 功能要点
  - 适配器基类定义统一接口（平台名、URL、查询方法）。
  - 内置"文心""Kimi"适配器；引擎按查询配置的平台列表逐一执行。
- 核心价值
  - 解耦平台差异：统一调用入口，便于扩展更多平台。
  - 可观测性：每个平台独立任务状态（pending/running/success/failed）。
- 典型场景
  - 查询配置包含"wenxin,kimi"，引擎为两者分别创建任务并行执行，最终汇总结果。

```mermaid
sequenceDiagram
participant CE as "CitationEngine"
participant Q as "Query"
participant T as "QueryTask"
participant A as "平台适配器"
CE->>Q : 读取平台列表
loop 遍历平台
CE->>T : 获取/创建任务
CE->>A : 调用 query(keyword)
A-->>CE : 返回原始响应
CE->>CE : 品牌匹配/竞品检测
CE->>T : 更新任务状态
end
```

**图表来源**
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
- [backend/app/workers/platforms/base.py:10-17](file://backend/app/workers/platforms/base.py#L10-L17)

**章节来源**
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/citation_engine.py:151-157](file://backend/app/workers/citation_engine.py#L151-L157)

### AI代理框架
- 功能要点
  - 代理实现：CitationDetectorAgent、ContentGeneratorAgent、DeAIAgent、GEOOptimizerAgent。
  - Pipeline编排：支持变量解析、依赖管理、条件执行、重试机制。
  - 任务分发：Redis队列驱动，支持任务状态跟踪、进度上报和回调机制。
- 核心价值
  - 智能化编排：将复杂的多步骤任务分解为可组合的代理单元。
  - 可扩展性：新的代理类型可通过简单接口接入框架。
  - 可观测性：完整的任务生命周期跟踪和性能监控。
- 典型场景
  - 内容生产Pipeline：主题选择 → 文章生成 → 去AI化 → GEO优化 → 发布。

```mermaid
classDiagram
class BaseAgent {
<<abstract>>
+execute(task) TaskResult
+report_progress(task_id, progress, message)
+get_capabilities() AgentCapability
}
class CitationDetectorAgent {
+execute_full_detect(task) dict
+execute_single_detect(task) dict
}
class ContentGeneratorAgent {
+_generate_topics(task) dict
+_generate_article(task) dict
}
class DeAIAgent {
+_process(task) dict
}
class GEOOptimizerAgent {
+_optimize(task) dict
}
class PipelineEngine {
+execute(pipeline, context) PipelineResult
+_execute_stage(stage, ctx, stages_ctx) StageResult
}
class TaskDispatcher {
+dispatch(task, org_id, user_id) str
+get_task_status(task_id) dict
+handle_result(result)
}
BaseAgent <|-- CitationDetectorAgent
BaseAgent <|-- ContentGeneratorAgent
BaseAgent <|-- DeAIAgent
BaseAgent <|-- GEOOptimizerAgent
PipelineEngine --> BaseAgent : "编排执行"
TaskDispatcher --> BaseAgent : "任务分发"
```

**图表来源**
- [backend/app/agent_framework/agents/citation_detector.py:24-218](file://backend/app/agent_framework/agents/citation_detector.py#L24-L218)
- [backend/app/agent_framework/agents/content_generator_agent.py:23-299](file://backend/app/agent_framework/agents/content_generator_agent.py#L23-L299)
- [backend/app/agent_framework/agents/deai_agent.py:21-156](file://backend/app/agent_framework/agents/deai_agent.py#L21-L156)
- [backend/app/agent_framework/agents/geo_optimizer_agent.py:23-198](file://backend/app/agent_framework/agents/geo_optimizer_agent.py#L23-L198)
- [backend/app/agent_framework/pipeline/engine.py:31-536](file://backend/app/agent_framework/pipeline/engine.py#L31-L536)
- [backend/app/agent_framework/dispatcher.py:32-367](file://backend/app/agent_framework/dispatcher.py#L32-L367)

**章节来源**
- [backend/app/agent_framework/agents/__init__.py:1-14](file://backend/app/agent_framework/agents/__init__.py#L1-L14)
- [backend/app/agent_framework/agents/citation_detector.py:1-218](file://backend/app/agent_framework/agents/citation_detector.py#L1-L218)
- [backend/app/agent_framework/agents/content_generator_agent.py:1-299](file://backend/app/agent_framework/agents/content_generator_agent.py#L1-L299)
- [backend/app/agent_framework/agents/deai_agent.py:1-156](file://backend/app/agent_framework/agents/deai_agent.py#L1-L156)
- [backend/app/agent_framework/agents/geo_optimizer_agent.py:1-198](file://backend/app/agent_framework/agents/geo_optimizer_agent.py#L1-L198)
- [backend/app/agent_framework/pipeline/engine.py:1-536](file://backend/app/agent_framework/pipeline/engine.py#L1-L536)
- [backend/app/agent_framework/dispatcher.py:1-367](file://backend/app/agent_framework/dispatcher.py#L1-L367)

### 业务生命周期管理
- 功能要点
  - 项目创建：快速启动功能，自动生成5个阶段的项目。
  - 阶段管理：品牌基建、内容生产、AI适配优化、权威信号构建、持续运维。
  - 状态跟踪：项目进度、阶段状态、完成率统计和时间轴事件记录。
  - 统计分析：组织级别的项目统计和阶段分布。
- 核心价值
  - 全生命周期视角：从品牌建设到持续运营的完整流程管理。
  - 可视化跟踪：阶段进度卡片和时间轴展示项目进展。
  - 数据驱动决策：基于统计数据的项目管理和资源配置。
- 典型场景
  - 管理员创建品牌项目 → 各阶段负责人推进 → 实时查看进度 → 生成项目报告。

```mermaid
sequenceDiagram
participant Admin as "管理员"
participant API as "生命周期API"
participant S as "生命周期服务"
participant DB as "数据库"
Admin->>API : POST /api/v1/lifecycle/projects/quick-start
API->>S : 创建项目和5个阶段
S->>DB : 插入LifecycleProject和ProjectStage
DB-->>S : 成功
S-->>API : 返回项目详情
API-->>Admin : 项目创建成功
Admin->>API : GET /api/v1/lifecycle/projects/{id}/timeline
API->>S : 获取时间轴事件
S->>DB : 查询项目和阶段
DB-->>S : 事件列表
S-->>API : 时间轴数据
API-->>Admin : 渲染时间轴
```

**图表来源**
- [backend/app/api/lifecycle.py:190-230](file://backend/app/api/lifecycle.py#L190-L230)
- [backend/app/api/lifecycle.py:138-187](file://backend/app/api/lifecycle.py#L138-L187)
- [backend/app/models/lifecycle.py:12-91](file://backend/app/models/lifecycle.py#L12-L91)

**章节来源**
- [backend/app/api/lifecycle.py:1-297](file://backend/app/api/lifecycle.py#L1-L297)
- [backend/app/models/lifecycle.py:1-91](file://backend/app/models/lifecycle.py#L1-L91)
- [frontend/lib/api/lifecycle.ts:53-95](file://frontend/lib/api/lifecycle.ts#L53-L95)

### 分析监控系统
- 功能要点
  - 发布追踪：记录内容发布事件、更新效果指标和生成快照。
  - 性能分析：内容表现排行、单篇内容深度分析和历史趋势。
  - 智能洞察：基于LLM的自动化洞察生成，包含趋势、异常、机会和建议。
  - 统计概览：组织级别的发布统计、平台分布和互动率分析。
- 核心价值
  - 数据驱动优化：基于真实效果数据的自动化洞察和建议。
  - 全面监控：从发布到效果的全流程数据追踪。
  - 智能辅助：AI驱动的分析和优化建议，提升内容质量。
- 典型场景
  - 内容发布后自动记录效果 → 定期生成洞察报告 → 基于建议优化内容策略。

```mermaid
sequenceDiagram
participant CMS as "内容管理系统"
participant API as "分析API"
participant S as "分析服务"
participant DB as "数据库"
CMS->>API : POST /api/v1/analytics/publish
API->>S : 记录发布事件
S->>DB : 插入PublishRecord
DB-->>S : 成功
S->>DB : 插入ContentMetrics快照
CMS->>API : GET /api/v1/analytics/insights
API->>S : 生成洞察
S->>S : 调用LLM分析数据
S->>DB : 插入OptimizationInsight
DB-->>S : 成功
S-->>API : 返回洞察结果
API-->>CMS : 洞察报告
```

**图表来源**
- [backend/app/services/analytics/tracker.py:16-51](file://backend/app/services/analytics/tracker.py#L16-L51)
- [backend/app/services/analytics/insights.py:40-103](file://backend/app/services/analytics/insights.py#L40-L103)
- [backend/app/services/analytics/tracker.py:53-128](file://backend/app/services/analytics/tracker.py#L53-L128)

**章节来源**
- [backend/app/services/analytics/tracker.py:1-230](file://backend/app/services/analytics/tracker.py#L1-L230)
- [backend/app/services/analytics/insights.py:1-313](file://backend/app/services/analytics/insights.py#L1-L313)

### 知识库服务
- 功能要点
  - RAG检索：文档分块、向量化嵌入和混合检索，支持多知识库查询。
  - 文档管理：支持URL抓取和文本上传，自动计算内容哈希和分块数量。
  - 知识库CRUD：多租户知识库管理，支持文档级联删除和统计更新。
  - 搜索日志：记录搜索查询、结果数量和延迟时间。
- 核心价值
  - 智能检索：基于向量和关键词的混合检索，提升相关性。
  - 知识管理：结构化的知识库管理和版本控制。
  - 效率提升：自动化的文档处理和检索，减少人工维护成本。
- 典型场景
  - 研究员上传行业报告 → 系统自动分块嵌入 → 搜索相关知识 → 生成内容。

```mermaid
sequenceDiagram
participant User as "用户"
participant API as "知识库API"
participant S as "RAG服务"
participant DB as "数据库"
User->>API : POST /api/v1/knowledge/bases/{kb_id}/documents
API->>S : 上传文档
S->>DB : 插入KnowledgeDocument
S->>S : 分块 → 向量化 → 存储
S->>DB : 插入KnowledgeChunk
DB-->>S : 成功
S-->>API : 返回文档详情
API-->>User : 上传完成
User->>API : POST /api/v1/knowledge/search
API->>S : 执行RAG检索
S->>DB : 查询向量相似度
DB-->>S : 相关文档
S-->>API : 返回检索结果
API-->>User : 检索结果
```

**图表来源**
- [backend/app/api/knowledge.py:217-293](file://backend/app/api/knowledge.py#L217-L293)
- [backend/app/api/knowledge.py:424-501](file://backend/app/api/knowledge.py#L424-L501)
- [backend/app/services/knowledge/rag_service.py:33-43](file://backend/app/services/knowledge/rag_service.py#L33-L43)

**章节来源**
- [backend/app/api/knowledge.py:1-502](file://backend/app/api/knowledge.py#L1-L502)
- [backend/app/services/knowledge/rag_service.py:1-43](file://backend/app/services/knowledge/rag_service.py#L1-L43)
- [backend/app/models/knowledge.py:1-43](file://backend/app/models/knowledge.py#L1-L43)

### 数据分析与可视化
- 功能要点
  - 统计接口：总查询/引用数、引用率、平均位置、按平台汇总、30 天趋势（按自然周聚合）。
  - 前端仪表盘：卡片展示核心指标；趋势折线图展示过去 30 天每周引用次数。
- 核心价值
  - 快速洞察：总览指标帮助评估监测效果与变化趋势。
  - 易用性：图表直观呈现，降低阅读成本。
- 典型场景
  - 研究人员查看"过去30天引用趋势"，发现某周显著上升，结合上下文进一步分析。

```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "统计API"
participant S as "统计服务"
participant DB as "数据库"
FE->>API : GET /api/v1/citations/stats
API->>S : 统计聚合
S->>DB : 聚合查询/分组统计
DB-->>S : 结果集
S-->>API : {total,rate,avg,by_platform,trend}
API-->>FE : 返回JSON
FE->>FE : 渲染卡片与趋势图
```

**图表来源**
- [frontend/app/(dashboard)/dashboard/page.tsx:20-155](file://frontend/app/(dashboard)/dashboard/page.tsx#L20-L155)
- [frontend/components/charts/trend-chart.tsx:22-59](file://frontend/components/charts/trend-chart.tsx#L22-L59)
- [backend/app/api/citations.py:49-56](file://backend/app/api/citations.py#L49-L56)
- [backend/app/services/citation.py:76-201](file://backend/app/services/citation.py#L76-L201)

**章节来源**
- [frontend/app/(dashboard)/dashboard/page.tsx:1-156](file://frontend/app/(dashboard)/dashboard/page.tsx#L1-L156)
- [frontend/components/charts/trend-chart.tsx:1-60](file://frontend/components/charts/trend-chart.tsx#L1-L60)
- [backend/app/api/citations.py:1-78](file://backend/app/api/citations.py#L1-L78)
- [backend/app/services/citation.py:1-269](file://backend/app/services/citation.py#L1-L269)

### 报告导出
- 功能要点
  - 支持 CSV 导出指定查询的所有引用记录，包含日期、平台、是否引用、引用位置、引用文本、竞品品牌。
  - 流式响应，避免大文件内存压力。
- 核心价值
  - 离线分析：便于导入 Excel/BI 工具做深度分析。
  - 合规归档：结构化导出满足审计与存档需求。
- 典型场景
  - 研究员导出某周的全部引用记录，用于撰写专题报告。

```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "导出API"
participant S as "导出服务"
participant DB as "数据库"
FE->>API : GET /api/v1/reports/export/csv?query_id=...
API->>S : 导出CSV
S->>DB : 查询引用记录
DB-->>S : 记录集
S-->>API : CSV字符串
API-->>FE : 流式响应(Attachment)
```

**图表来源**
- [backend/app/api/reports.py:16-46](file://backend/app/api/reports.py#L16-L46)
- [backend/app/services/citation.py:237-268](file://backend/app/services/citation.py#L237-L268)

**章节来源**
- [backend/app/api/reports.py:1-47](file://backend/app/api/reports.py#L1-L47)
- [backend/app/services/citation.py:237-268](file://backend/app/services/citation.py#L237-L268)

## 依赖分析
- 组件耦合
  - API 层仅负责参数解析与鉴权，业务逻辑集中在服务层，降低控制器复杂度。
  - 引擎与平台适配器通过抽象接口解耦，便于替换与扩展。
  - 调度器与引擎通过 ORM 与任务表协作，避免直接耦合业务数据。
  - AI代理框架通过任务分发器与代理实现松耦合。
  - 生命周期管理与项目阶段通过外键关联，确保数据一致性。
- 外部依赖
  - FastAPI/SQLAlchemy：Web 框架与 ORM。
  - APScheduler：异步定时任务调度。
  - Recharts：前端图表渲染。
  - Redis：异步任务队列和缓存。
  - LLM提供商：OpenAI、DeepSeek等大模型服务。
- 潜在风险
  - 平台适配器异常需隔离，避免影响其他平台任务。
  - 大量并发查询可能带来数据库与外部平台压力，建议限流与重试策略。
  - AI代理任务的LLM调用可能存在成本控制和速率限制问题。

```mermaid
graph LR
API["API层"] --> SVC["服务层"]
SVC --> MODEL["模型层"]
SVC --> WORKER["工作器"]
SVC --> AGENT["AI代理框架"]
SVC --> ANALYTICS["分析监控"]
SVC --> KNOWLEDGE["知识库服务"]
WORKER --> ADAPTER["平台适配器"]
AGENT --> DISPATCHER["任务分发器"]
ANALYTICS --> LLM["LLM提供商"]
KNOWLEDGE --> VECTOR["向量数据库"]
FE["前端"] --> API
```

**图表来源**
- [backend/app/main.py:38-42](file://backend/app/main.py#L38-L42)
- [backend/app/workers/citation_engine.py:151-157](file://backend/app/workers/citation_engine.py#L151-L157)
- [backend/app/agent_framework/dispatcher.py:35-46](file://backend/app/agent_framework/dispatcher.py#L35-L46)

**章节来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/workers/citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [backend/app/agent_framework/dispatcher.py:1-367](file://backend/app/agent_framework/dispatcher.py#L1-L367)

## 性能考虑
- 数据库
  - 查询索引：查询与引用记录表均建立常用过滤字段索引，减少扫描开销。
  - 分页与聚合：统计接口使用分组与聚合，避免一次性拉取全量数据。
  - 连接池：合理配置数据库连接池大小，避免连接争用。
- 引擎与平台
  - 并行执行：同一查询的不同平台可并行处理，缩短总耗时。
  - 错误隔离：单平台失败不影响其他平台，保证整体可用性。
  - 缓存策略：对频繁查询的结果进行缓存，减少重复计算。
- 前端
  - 图表懒加载与响应式容器，提升大屏体验。
  - 导出采用流式响应，避免内存峰值。
  - 代理状态轮询优化，避免过度请求。
- AI代理框架
  - 任务队列：Redis队列支持高并发任务处理。
  - 超时控制：为LLM调用设置合理的超时时间。
  - 重试机制：失败任务自动重试，支持指数退避。
- 知识库服务
  - 向量索引：优化向量相似度查询性能。
  - 分块策略：合理设置分块大小，平衡精度与性能。
  - 批量处理：批量插入和更新操作，减少数据库往返。

## 故障排查指南
- 认证问题
  - 注册失败：邮箱已被注册；检查重复提交或换用其他邮箱。
  - 登录失败：邮箱或密码错误；确认凭据正确与网络可达。
- 查询任务
  - 创建被拒：超出配额；联系管理员提升限额或清理历史查询。
  - 无法执行：查询状态非"active"或未配置平台；检查状态与平台列表。
  - 即时查询无响应：平台适配器异常或网络超时；查看任务状态与错误信息。
- AI代理框架
  - 代理任务失败：检查代理配置、LLM提供商连接和任务输入参数。
  - Pipeline执行错误：验证YAML语法、依赖关系和变量引用。
  - 任务超时：调整超时设置或优化LLM调用参数。
- 生命周期管理
  - 项目创建失败：检查组织权限和品牌名称唯一性。
  - 阶段推进异常：确认阶段状态和前置条件满足。
  - 统计数据缺失：验证项目数据完整性和时间范围设置。
- 分析监控
  - 发布记录丢失：检查发布事件记录和数据库连接。
  - 洞察生成失败：确认LLM提供商可用性和API密钥配置。
  - 性能数据异常：验证指标计算逻辑和数据完整性。
- 知识库服务
  - 文档上传失败：检查文件大小限制和内容格式。
  - 检索结果不准确：验证向量嵌入质量和检索参数设置。
  - 搜索日志缺失：确认日志记录和数据库写入权限。
- 统计与导出
  - 统计为空：可能因筛选条件导致无数据；尝试放宽时间范围或移除查询筛选。
  - 导出失败：查询不存在或无权限；确认 query_id 与登录态。
- 调度器
  - 未触发：检查调度器是否启动、时区设置、下次执行时间是否已到达。

**章节来源**
- [backend/app/services/auth.py:37-69](file://backend/app/services/auth.py#L37-L69)
- [backend/app/services/query.py:45-81](file://backend/app/services/query.py#L45-L81)
- [backend/app/services/citation.py:204-234](file://backend/app/services/citation.py#L204-L234)
- [backend/app/api/reports.py:16-46](file://backend/app/api/reports.py#L16-L46)
- [backend/app/workers/scheduler.py:30-40](file://backend/app/workers/scheduler.py#L30-L40)
- [backend/app/agent_framework/dispatcher.py:118-154](file://backend/app/agent_framework/dispatcher.py#L118-L154)
- [backend/app/api/lifecycle.py:190-230](file://backend/app/api/lifecycle.py#L190-L230)
- [backend/app/services/analytics/tracker.py:16-51](file://backend/app/services/analytics/tracker.py#L16-L51)
- [backend/app/api/knowledge.py:217-293](file://backend/app/api/knowledge.py#L217-L293)

## 结论
GEO 平台以"查询—检测—智能代理—生命周期—分析监控—知识库—统计—可视—导出"为主线，构建了从自动化采集到深度分析的完整链路。通过严格的权限控制、可扩展的平台适配器、稳健的定时调度、智能化的AI代理编排、全生命周期的项目管理和全面的分析监控体系，既能满足管理员对系统运行的掌控，也能为研究人员提供高效、可靠的品牌监测工具。新增的AI代理框架、业务生命周期管理、分析监控系统和知识库服务等核心功能模块，进一步增强了平台的智能化水平和业务服务能力。建议后续在代理任务的成本控制、生命周期管理的自动化程度、分析洞察的准确性以及知识库的规模扩展等方面持续优化，以提升整体用户体验和平台价值。

## 附录
- 典型使用流程（管理员）
  - 新建用户/分配配额 → 配置平台密钥 → 监控调度器运行 → 查看任务状态与错误日志 → 调整频率策略 → 管理代理任务 → 监控分析数据 → 维护知识库内容。
- 典型使用流程（研究人员）
  - 登录 → 创建查询（关键词/目标品牌/平台/频率） → 查看仪表盘趋势 → 导出报告 → 使用知识库检索相关信息 → 生成内容并进行优化 → 发布内容并跟踪效果。
- 典型使用流程（项目经理）
  - 登录 → 快速启动品牌项目 → 分配各阶段任务 → 跟踪项目进度 → 查看阶段报告 → 管理团队成员 → 生成项目总结。
- 关键接口路径参考
  - 认证：POST /api/v1/auth/register, POST /api/v1/auth/login, GET /api/v1/auth/me
  - 查询：GET/POST/GET/PATCH/DELETE /api/v1/queries
  - 引用：GET /api/v1/citations, GET /api/v1/citations/stats, POST /api/v1/queries/{query_id}/run-now
  - 报告：GET /api/v1/reports/export/csv
  - 生命周期：POST /api/v1/lifecycle/projects/quick-start, GET /api/v1/lifecycle/projects/{id}/timeline
  - 知识库：POST /api/v1/knowledge/bases, POST /api/v1/knowledge/bases/{kb_id}/documents, POST /api/v1/knowledge/search
  - 分析监控：POST /api/v1/analytics/publish, GET /api/v1/analytics/insights
  - AI代理：POST /api/v1/agents/{agent_name}/{task_type}