fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/.qoder/repowiki/zh/content/项目概述/核心功能/核心功能.md

795 lines
42 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 核心功能
<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}
Reference in New Issue View Git Blame Copy Permalink