# 扩展与定制

<cite>
**本文档引用的文件**
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/config.py](file://backend/app/config.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/reports.py](file://backend/app/api/reports.py)
- [backend/app/api/citations.py](file://backend/app/api/citations.py)
- [backend/app/api/agents.py](file://backend/app/api/agents.py)
- [backend/app/models/query.py](file://backend/app/models/query.py)
- [backend/app/schemas/query.py](file://backend/app/schemas/query.py)
- [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py)
- [backend/app/workers/platforms/base.py](file://backend/app/workers/platforms/base.py)
- [backend/app/workers/platforms/kimi.py](file://backend/app/workers/platforms/kimi.py)
- [backend/app/workers/platforms/wenxin.py](file://backend/app/workers/platforms/wenxin.py)
- [backend/app/workers/citation_engine.py](file://backend/app/workers/citation_engine.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/database.py](file://backend/app/database.py)
- [backend/app/api/deps.py](file://backend/app/api/deps.py)
- [backend/app/models/user.py](file://backend/app/models/user.py)
- [backend/app/schemas/auth.py](file://backend/app/schemas/auth.py)
- [backend/app/schemas/citation.py](file://backend/app/schemas/citation.py)
- [backend/app/schemas/query.py](file://backend/app/schemas/query.py)
- [backend/requirements.txt](file://backend/requirements.txt)
- [frontend/app/layout.tsx](file://frontend/app/layout.tsx)
- [frontend/components/providers.tsx](file://frontend/components/providers.tsx)
- [frontend/lib/api.ts](file://frontend/lib/api.ts)
- [frontend/lib/api/agents.ts](file://frontend/lib/api/agents.ts)
- [frontend/package.json](file://frontend/package.json)
- [docker-compose.yml](file://docker-compose.yml)
- [backend/Dockerfile](file://backend/Dockerfile)
- [frontend/Dockerfile](file://frontend/Dockerfile)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)
- [backend/app/agent_framework/registry.py](file://backend/app/agent_framework/registry.py)
- [backend/app/agent_framework/config_manager.py](file://backend/app/agent_framework/config_manager.py)
- [backend/app/agent_framework/dispatcher.py](file://backend/app/agent_framework/dispatcher.py)
- [backend/app/agent_framework/protocol.py](file://backend/app/agent_framework/protocol.py)
- [backend/app/agent_framework/pipeline/engine.py](file://backend/app/agent_framework/pipeline/engine.py)
- [backend/app/models/agent.py](file://backend/app/models/agent.py)
- [.env.example](file://.env.example)
</cite>

## 更新摘要
**所做更改**
- 新增了智能体框架扩展指南，包括 Agent 注册中心、配置管理和任务调度
- 扩展了前端 API 封装，新增 agents 模块的完整实现
- 更新了配置定制方法，增加了 LLM 提供商配置和 AI 平台集成
- 完善了第三方集成方案，涵盖智能体系统、Redis 集成和管道编排
- 增加了系统定制化案例研究和实施建议

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

## 简介
本文件面向需要对 GEO 平台进行扩展与定制的工程师与产品团队，系统性阐述后端 API 扩展、前端页面扩展、数据模型扩展、配置定制、第三方集成（AI 平台、数据库、认证）以及智能体框架扩展的最佳实践。文档同时提供可落地的实施建议与案例研究，帮助快速实现业务定制化目标。

**更新** 本次更新重点加强了智能体框架的扩展能力，新增了完整的 Agent 管理、配置热更新、任务调度和管道编排功能。

## 项目结构
GEO 采用前后端分离架构：
- 后端基于 FastAPI，提供 REST API；通过 Alembic 管理数据库迁移；使用 SQLAlchemy ORM 定义模型；APScheduler 实现定时任务；Playwright 支持 AI 平台网页抓取。
- 前端基于 Next.js 14，使用 TypeScript、TailwindCSS、Radix UI 组件库；通过自定义 API 封装层与后端交互；NextAuth v4 提供会话管理。
- **新增** 智能体框架支持，包括 Agent 注册中心、配置管理、任务调度和管道编排。

```mermaid
graph TB
subgraph "前端"
FE_APP["Next.js 应用<br/>路由与页面"]
FE_LIB["API 封装<br/>lib/api.ts"]
FE_LIB_AGENTS["智能体API<br/>lib/api/agents.ts"]
FE_PROV["会话提供者<br/>components/providers.tsx"]
end
subgraph "后端"
BE_MAIN["FastAPI 应用<br/>app/main.py"]
BE_ROUTER_AUTH["认证路由<br/>app/api/auth.py"]
BE_ROUTER_QUERIES["查询路由<br/>app/api/queries.py"]
BE_ROUTER_CITATIONS["引用路由<br/>app/api/citations.py"]
BE_ROUTER_REPORTS["报告路由<br/>app/api/reports.py"]
BE_ROUTER_AGENTS["智能体路由<br/>app/api/agents.py"]
BE_SCHED["调度器<br/>app/workers/scheduler.py"]
BE_PLAT_BASE["平台适配器基类<br/>app/workers/platforms/base.py"]
BE_PLAT_KIMI["Kimi 适配器<br/>app/workers/platforms/kimi.py"]
BE_PLAT_WENXIN["文心一言适配器<br/>app/workers/platforms/wenxin.py"]
BE_DB["数据库与模型<br/>app/database.py + models/*"]
BE_AGENT_REGISTRY["Agent注册中心<br/>agent_framework/registry.py"]
BE_AGENT_CONFIG["配置管理<br/>agent_framework/config_manager.py"]
BE_AGENT_DISPATCH["任务调度<br/>agent_framework/dispatcher.py"]
BE_AGENT_PIPELINE["管道引擎<br/>agent_framework/pipeline/engine.py"]
end
FE_APP --> FE_LIB
FE_LIB --> BE_MAIN
FE_LIB_AGENTS --> BE_ROUTER_AGENTS
BE_MAIN --> BE_ROUTER_AUTH
BE_MAIN --> BE_ROUTER_QUERIES
BE_MAIN --> BE_ROUTER_CITATIONS
BE_MAIN --> BE_ROUTER_REPORTS
BE_MAIN --> BE_ROUTER_AGENTS
BE_MAIN --> BE_SCHED
BE_SCHED --> BE_PLAT_BASE
BE_PLAT_BASE --> BE_PLAT_KIMI
BE_PLAT_BASE --> BE_PLAT_WENXIN
BE_MAIN --> BE_DB
BE_ROUTER_AGENTS --> BE_AGENT_REGISTRY
BE_ROUTER_AGENTS --> BE_AGENT_CONFIG
BE_ROUTER_AGENTS --> BE_AGENT_DISPATCH
BE_AGENT_DISPATCH --> BE_AGENT_PIPELINE
```

**图表来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/lib/api/agents.ts:1-57](file://frontend/lib/api/agents.ts#L1-L57)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
- [backend/app/database.py](file://backend/app/database.py)
- [backend/app/agent_framework/registry.py:1-219](file://backend/app/agent_framework/registry.py#L1-L219)
- [backend/app/agent_framework/config_manager.py:1-191](file://backend/app/agent_framework/config_manager.py#L1-L191)
- [backend/app/agent_framework/dispatcher.py:1-367](file://backend/app/agent_framework/dispatcher.py#L1-L367)
- [backend/app/agent_framework/pipeline/engine.py:1-376](file://backend/app/agent_framework/pipeline/engine.py#L1-L376)

**章节来源**
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [frontend/components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)

## 核心组件
- API 层：认证、查询词、引用数据、报告导出、**新增**智能体管理等模块化路由，统一挂载于主应用。
- 服务层：封装业务逻辑，如用户认证、查询 CRUD、引用处理、**新增**智能体配置管理等。
- 数据层：SQLAlchemy 模型与 Pydantic Schema，定义实体与请求/响应结构，**新增**智能体相关模型。
- 工作器与调度：APScheduler 驱动定时任务，CitationEngine 协调平台适配器执行查询，**新增**智能体任务调度。
- 前端：Next.js 页面与组件，通过 lib/api.ts 统一访问后端接口，**新增**智能体 API 封装。
- **新增** 智能体框架：Agent 注册中心、配置管理、任务调度和管道编排系统。

**章节来源**
- [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](file://backend/app/api/citations.py)
- [backend/app/api/reports.py](file://backend/app/api/reports.py)
- [backend/app/api/agents.py:1-299](file://backend/app/api/agents.py#L1-L299)
- [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/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/schemas/query.py:1-94](file://backend/app/schemas/query.py#L1-L94)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/lib/api/agents.ts:1-57](file://frontend/lib/api/agents.ts#L1-L57)

## 架构总览
下图展示从浏览器到后端 API、数据库与外部 AI 平台的完整链路，包括新增的智能体框架：

```mermaid
sequenceDiagram
participant Browser as "浏览器"
participant Frontend as "前端 Next.js"
participant API as "后端 FastAPI"
participant Svc as "服务层"
participant DB as "数据库"
participant Scheduler as "调度器"
participant Engine as "CitationEngine"
participant Plat as "平台适配器"
participant AgentFramework as "智能体框架"
Browser->>Frontend : 用户操作
Frontend->>API : 发起 HTTP 请求
API->>Svc : 路由分发与校验
svc->>AgentFramework : 智能体管理请求
AgentFramework->>DB : 读写智能体配置
Svc->>DB : 读写数据
DB-->>Svc : 返回结果
Svc-->>API : 业务结果
API-->>Frontend : JSON 响应
Note over Scheduler,Engine : 定时触发查询执行
Scheduler->>Engine : 触发执行
Engine->>Plat : 调用具体平台适配器
Plat-->>Engine : 返回原始响应
Engine->>DB : 写入引用记录
```

**图表来源**
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/lib/api/agents.ts:1-57](file://frontend/lib/api/agents.ts#L1-L57)
- [backend/app/main.py:1-48](file://backend/app/main.py#L1-L48)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
- [backend/app/agent_framework/registry.py:1-219](file://backend/app/agent_framework/registry.py#L1-L219)
- [backend/app/agent_framework/config_manager.py:1-191](file://backend/app/agent_framework/config_manager.py#L1-L191)
- [backend/app/agent_framework/dispatcher.py:1-367](file://backend/app/agent_framework/dispatcher.py#L1-L367)

## 详细组件分析

### 新增 API 接口扩展指南
- 路由扩展步骤
  - 在后端 app/api 下新增模块（如 app/api/new_feature.py），定义 APIRouter 并编写路由函数。
  - 在 app/main.py 中引入并挂载路由，指定前缀与标签。
  - 在 app/services 下新增对应服务函数，封装业务逻辑。
  - 在 app/schemas 下新增请求/响应模型，确保字段校验与默认值。
  - 在 app/models 下新增模型（如需持久化）。
  - 在 app/database.py 中注册模型，并在 alembic 迁移中生成/更新表结构。
- 示例参考路径
  - [认证路由示例:1-43](file://backend/app/api/auth.py#L1-L43)
  - [查询路由示例:1-86](file://backend/app/api/queries.py#L1-L86)
  - [智能体路由示例:1-299](file://backend/app/api/agents.py#L1-L299)
  - [主应用挂载示例:38-42](file://backend/app/main.py#L38-L42)
  - [服务层示例](file://backend/app/services/query.py)
  - [Schema 示例:1-94](file://backend/app/schemas/query.py#L1-L94)
  - [模型示例:1-55](file://backend/app/models/query.py#L1-L55)

```mermaid
flowchart TD
Start(["开始"]) --> CreateRouter["创建路由模块<br/>app/api/new_feature.py"]
CreateRouter --> MountRouter["在 app/main.py 挂载路由"]
MountRouter --> AddService["在 app/services 添加服务函数"]
AddService --> AddSchema["在 app/schemas 添加模型"]
AddSchema --> AddModel["在 app/models 添加模型如需"]
AddModel --> Alembic["生成/更新数据库迁移"]
Alembic --> Test["编写单元测试"]
Test --> End(["完成"])
```

**章节来源**
- [backend/app/main.py:38-42](file://backend/app/main.py#L38-L42)
- [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/agents.py:1-299](file://backend/app/api/agents.py#L1-L299)
- [backend/app/schemas/query.py:1-94](file://backend/app/schemas/query.py#L1-L94)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)

### 前端页面扩展指南
- 页面与布局
  - 在 frontend/app/(dashboard)/(或新的组) 下新增页面目录与 page.tsx。
  - 在 frontend/app/layout.tsx 中组织根布局与 Providers。
  - 在 components/ui 下新增或复用 UI 组件，保持一致的设计语言。
- API 调用
  - 在 frontend/lib/api.ts 中新增方法，遵循现有命名与错误处理模式。
  - **新增** 在 frontend/lib/api/agents.ts 中新增智能体相关 API 方法。
  - 在页面中通过 hooks 或直接调用 api.* 方法获取数据。
- 会话与权限
  - 使用 frontend/components/providers.tsx 包裹应用，确保 NextAuth 会话可用。
  - 在页面中根据用户状态控制渲染与交互。

```mermaid
flowchart TD
NewPage["新增页面<br/>frontend/app/(group)/new/page.tsx"] --> Layout["布局与 Providers<br/>frontend/app/layout.tsx"]
Layout --> UI["UI 组件<br/>frontend/components/ui/*"]
UI --> API["API 封装<br/>frontend/lib/api.ts"]
API --> AgentsAPI["智能体API<br/>frontend/lib/api/agents.ts"]
AgentsAPI --> Backend["后端 API<br/>backend/app/api/*"]
```

**章节来源**
- [frontend/app/layout.tsx:1-37](file://frontend/app/layout.tsx#L1-L37)
- [frontend/components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/lib/api/agents.ts:1-57](file://frontend/lib/api/agents.ts#L1-L57)

### 数据模型扩展指南
- 字段与约束
  - 在 app/models 下新增或修改模型，使用 SQLAlchemy 类型与索引策略。
  - 在 app/schemas 下同步新增/变更 Pydantic 模型，确保序列化与校验。
  - 在 app/api 下更新路由的响应模型。
- 迁移与版本控制
  - 使用 Alembic 生成迁移脚本，维护数据库演进历史。
  - 在生产环境执行迁移，避免破坏性变更。
- 性能与一致性
  - 对高频查询字段建立索引；合理拆分表与外键关系。
  - 通过服务层统一数据访问，避免绕过校验。

```mermaid
erDiagram
QUERIES {
uuid id PK
uuid user_id FK
string keyword
string target_brand
jsonb brand_aliases
jsonb platforms
string frequency
string status
timestamp last_queried_at
timestamp next_query_at
timestamp created_at
timestamp updated_at
}
USERS {
uuid id PK
string email UK
string name
string hashed_password
boolean is_active
timestamp created_at
timestamp updated_at
}
CITATION_RECORDS {
uuid id PK
uuid query_id FK
string platform
text raw_response
timestamp created_at
}
AGENT_REGISTRY {
uuid id PK
string name UK
string agent_type
string status
jsonb capabilities
timestamp last_heartbeat
timestamp created_at
timestamp updated_at
}
AGENT_CONFIGS {
uuid id PK
uuid agent_id FK
string config_key
jsonb config_value
uuid updated_by FK
timestamp updated_at
}
QUERIES ||--o{ CITATION_RECORDS : "包含"
USERS ||--o{ QUERIES : "拥有"
AGENT_REGISTRY ||--o{ AGENT_CONFIGS : "包含"
```

**图表来源**
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/agent.py:1-206](file://backend/app/models/agent.py#L1-L206)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)

**章节来源**
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/models/agent.py:1-206](file://backend/app/models/agent.py#L1-L206)
- [backend/app/schemas/query.py:1-94](file://backend/app/schemas/query.py#L1-L94)
- [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py)

### 配置定制选项
- 环境变量
  - 通过 app/config.py 的 Settings 类集中管理，支持 .env 文件覆盖。
  - 关键配置项包括数据库连接、Redis、JWT 密钥与过期时间、Playwright 浏览器路径、第三方平台密钥等。
  - **新增** LLM 提供商配置，包括默认提供商、模型选择和 API 密钥管理。
- 功能开关与性能参数
  - 平台列表、频率策略、状态枚举在 Schema 中集中校验，便于扩展与限制。
  - 调度周期（每小时）可在 app/workers/scheduler.py 中调整。
  - 前端 NEXT_PUBLIC_API_URL 控制后端域名，lib/api.ts 中统一拼接。
  - **新增** 智能体框架配置，包括 Redis URL 和心跳超时设置。
- 建议
  - 生产环境务必替换默认密钥与数据库密码。
  - 将敏感信息放入 .env 并加入 .gitignore。

**章节来源**
- [backend/app/config.py:1-46](file://backend/app/config.py#L1-L46)
- [backend/app/schemas/query.py:6-8](file://backend/app/schemas/query.py#L6-L8)
- [backend/app/workers/scheduler.py:32-38](file://backend/app/workers/scheduler.py#L32-L38)
- [frontend/lib/api.ts:1](file://frontend/lib/api.ts#L1)
- [.env.example:1-35](file://.env.example#L1-L35)

### 第三方集成扩展指南

#### 新 AI 平台接入
- 适配器开发
  - 继承 app/workers/platforms/base.py，实现 query 与可选的 close。
  - 在 app/workers/platforms 下新增适配器文件，按现有 Kimi/Wenxin 模式实现页面交互与稳定性检测。
- 注册与调度
  - 在 app/schemas/query.py 的 VALID_PLATFORMS 中添加新平台枚举值。
  - 在 CitationEngine 中注册新适配器映射，或通过工厂动态加载。
- 错误与重试
  - 参考现有指数退避与超时处理策略，保证鲁棒性。

```mermaid
classDiagram
class BasePlatformAdapter {
+string platform_name
+string platform_url
+query(keyword) str
+close()
}
class KimiAdapter {
+query(keyword) str
+close()
}
class WenxinAdapter {
+query(keyword) str
+close()
}
BasePlatformAdapter <|-- KimiAdapter
BasePlatformAdapter <|-- WenxinAdapter
```

**图表来源**
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)

**章节来源**
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
- [backend/app/schemas/query.py:6](file://backend/app/schemas/query.py#L6)

#### 新数据库支持
- 当前使用 PostgreSQL + asyncpg，若需更换：
  - 在 app/database.py 中切换引擎与方言。
  - 更新 app/config.py 中 DATABASE_URL。
  - 在 requirements.txt 中替换驱动包。
  - 重新生成/更新 Alembic 迁移以适配新方言。

**章节来源**
- [backend/app/database.py](file://backend/app/database.py)
- [backend/app/config.py:7](file://backend/app/config.py#L7)
- [backend/requirements.txt:5-8](file://backend/requirements.txt#L5-L8)

#### 新认证方式集成
- 当前使用 JWT 令牌与 NextAuth 会话：
  - 后端：app/services/auth.py 生成与校验 JWT。
  - 前端：components/providers.tsx 提供 SessionProvider。
  - 若需 OAuth/SSO：在 NextAuth 配置中新增提供方；后端保持 JWT 令牌发放与校验逻辑不变。
- 注意事项
  - 保持 Authorization 头格式与后端解析一致。
  - 在 app/api/deps.py 中的依赖注入中校验用户身份。

**章节来源**
- [backend/app/services/auth.py](file://backend/app/services/auth.py)
- [frontend/components/providers.tsx:1-9](file://frontend/components/providers.tsx#L1-L9)
- [frontend/lib/api.ts:3-21](file://frontend/lib/api.ts#L3-L21)
- [backend/app/api/deps.py](file://backend/app/api/deps.py)

#### 智能体框架集成
- Agent 注册中心
  - 通过 AgentRegistry 管理 Agent 的注册、发现与状态。
  - 支持心跳检测与自动离线标记。
- 配置管理
  - AgentConfigManager 支持配置的热更新与批量修改。
  - 提供配置历史查询功能。
- 任务调度
  - TaskDispatcher 通过 Redis Queue 实现任务分发。
  - 支持任务取消、状态查询和日志记录。
- 管道编排
  - PipelineEngine 支持 YAML 定义的多阶段任务编排。
  - 实现拓扑排序、变量传递和条件执行。

```mermaid
classDiagram
class AgentRegistry {
+register(capability, endpoint) str
+unregister(agent_name)
+update_heartbeat(agent_name)
+get_agent(agent_name) dict
+list_agents(agent_type, status) list
+get_available_agent(task_type) str
+check_health()
}
class AgentConfigManager {
+get_config(agent_name) dict
+set_config(agent_name, key, value, updated_by)
+bulk_update_config(agent_name, configs, updated_by)
+get_config_history(agent_name, key) list
}
class TaskDispatcher {
+dispatch(task, organization_id, created_by) str
+cancel_task(task_id)
+get_task_status(task_id) dict
+handle_result(result)
+handle_progress(progress)
+retry_failed_tasks(max_retries)
}
class PipelineEngine {
+execute(pipeline, context) PipelineResult
+_topological_sort(stages) list
+dry_run_stage(stage, resolved_inputs) StageResult
}
AgentRegistry <.. TaskDispatcher : "任务分配"
AgentConfigManager <.. TaskDispatcher : "配置管理"
TaskDispatcher <.. PipelineEngine : "任务执行"
```

**图表来源**
- [backend/app/agent_framework/registry.py:1-219](file://backend/app/agent_framework/registry.py#L1-L219)
- [backend/app/agent_framework/config_manager.py:1-191](file://backend/app/agent_framework/config_manager.py#L1-L191)
- [backend/app/agent_framework/dispatcher.py:1-367](file://backend/app/agent_framework/dispatcher.py#L1-L367)
- [backend/app/agent_framework/pipeline/engine.py:1-376](file://backend/app/agent_framework/pipeline/engine.py#L1-L376)

**章节来源**
- [backend/app/agent_framework/registry.py:1-219](file://backend/app/agent_framework/registry.py#L1-L219)
- [backend/app/agent_framework/config_manager.py:1-191](file://backend/app/agent_framework/config_manager.py#L1-L191)
- [backend/app/agent_framework/dispatcher.py:1-367](file://backend/app/agent_framework/dispatcher.py#L1-L367)
- [backend/app/agent_framework/pipeline/engine.py:1-376](file://backend/app/agent_framework/pipeline/engine.py#L1-L376)

### 插件系统使用指南与最佳实践
- 插件化思路
  - 平台适配器采用"插件"式扩展：通过继承基类与工厂/映射注册，实现多平台并行。
  - 调度器与 CitationEngine 作为"核心引擎"，通过适配器接口解耦平台差异。
  - **新增** 智能体框架采用注册中心模式，支持动态 Agent 注册与发现。
- 最佳实践
  - 明确职责边界：路由负责协议与鉴权，服务层负责业务规则，模型负责数据结构。
  - 统一错误处理：前端统一捕获 HTTP 错误并提示；后端抛出明确异常码与消息。
  - 可观测性：为关键流程增加日志与指标，便于定位问题。
  - 安全：严格校验输入、最小权限原则、HTTPS 传输、密钥轮换。
  - **新增** 智能体安全：验证 Agent 能力声明，限制并发执行，监控心跳状态。

**章节来源**
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [frontend/lib/api.ts:16-21](file://frontend/lib/api.ts#L16-L21)
- [backend/app/agent_framework/registry.py:1-219](file://backend/app/agent_framework/registry.py#L1-L219)
- [backend/app/agent_framework/dispatcher.py:1-367](file://backend/app/agent_framework/dispatcher.py#L1-L367)

## 依赖分析
- 后端依赖
  - Web 框架与 ASGI 服务器：FastAPI + Uvicorn
  - 数据库与迁移：SQLAlchemy + Alembic + asyncpg
  - 配置与校验：Pydantic + pydantic-settings + python-dotenv
  - 认证与安全：python-jose + passlib + multipart
  - 任务调度：APScheduler
  - 浏览器自动化：Playwright
  - HTTP 客户端：httpx
  - **新增** 智能体框架：Redis async（aioredis）、SQLAlchemy JSONB
- 前端依赖
  - 框架与 UI：Next.js + Radix UI + TailwindCSS
  - 认证：NextAuth v4
  - 图表：Recharts
  - 开发工具：TypeScript + ESLint + TailwindCSS

```mermaid
graph LR
subgraph "后端依赖"
F["FastAPI"]
S["SQLAlchemy/Alembic"]
P["Pydantic/pydantic-settings"]
J["python-jose/passlib"]
R["Redis/APScheduler"]
PW["Playwright"]
H["httpx/python-dotenv"]
AIO["aioredis/sqlalchemy-jsonb"]
end
subgraph "前端依赖"
N["Next.js"]
NA["NextAuth"]
UI["Radix UI/TailwindCSS"]
RC["Recharts"]
end
```

**图表来源**
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:11-27](file://frontend/package.json#L11-L27)

**章节来源**
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:11-27](file://frontend/package.json#L11-L27)

## 性能考虑
- 数据库
  - 为高频查询字段建立索引；避免 N+1 查询；使用分页参数限制单页规模。
  - **新增** 智能体相关表建立复合索引，优化查询性能。
- API
  - 合理设置分页参数（skip/limit），避免一次性返回大量数据。
  - 对热点接口启用缓存（如 Redis）减少重复计算。
  - **新增** 智能体配置缓存，减少频繁查询数据库。
- 定时任务
  - 调度周期可根据业务需求调整；在高负载时降低频率或增加并发控制。
- 浏览器自动化
  - Playwright 启动成本较高，尽量复用上下文；失败重试与超时控制要合理设置。
- 前端
  - 按需加载页面与组件；减少不必要的 re-render；利用浏览器缓存与静态资源优化。
  - **新增** 智能体状态管理，避免频繁重新获取配置。
- **新增** 智能体框架性能
  - Redis 连接池管理，避免频繁创建连接。
  - 任务队列长度监控，防止内存泄漏。
  - 心跳超时阈值调优，平衡实时性与资源消耗。

## 故障排查指南
- 常见问题定位
  - 后端健康检查：访问 /health 确认服务可用。
  - CORS：确认 app/main.py 中允许的源与方法。
  - 数据库连接：检查 DATABASE_URL 与网络连通性。
  - Playwright：确保已安装浏览器二进制；查看适配器初始化日志。
  - **新增** 智能体框架：检查 Redis 连接状态，验证 Agent 注册与心跳。
- 日志与监控
  - 调度器与平台适配器均输出详细日志，定位失败原因。
  - 前端统一错误处理：lib/api.ts 在请求失败时抛出错误，便于 UI 提示。
  - **新增** 智能体框架日志：监控任务状态变化和配置更新历史。
- 快速恢复
  - 重启后端服务与前端构建；检查 .env 配置是否正确；核对迁移是否执行。
  - **新增** 智能体框架恢复：重启 Redis 服务，重新注册 Agent，检查任务队列。

**章节来源**
- [backend/app/main.py:45-47](file://backend/app/main.py#L45-L47)
- [backend/app/main.py:30-36](file://backend/app/main.py#L30-L36)
- [backend/app/config.py:7](file://backend/app/config.py#L7)
- [backend/app/workers/platforms/kimi.py:23-32](file://backend/app/workers/platforms/kimi.py#L23-L32)
- [frontend/lib/api.ts:16-21](file://frontend/lib/api.ts#L16-L21)

## 结论
GEO 平台提供了清晰的分层架构与可扩展点：路由层、服务层、数据层与工作器层相互解耦，配合配置中心与前端统一 API 封装，能够高效支撑业务扩展。**新增的智能体框架进一步增强了平台的扩展能力**：通过 Agent 注册中心、配置管理、任务调度和管道编排，团队可以快速接入新 AI 平台、扩展前端页面与数据模型，并在生产环境中保持稳定与可观测。通过平台适配器插件化、Schema/模型标准化、调度器与任务队列机制，以及智能体框架的动态扩展能力，团队可以构建更加灵活和强大的 AI 应用平台。

## 附录

### 系统定制化案例研究与实施建议
- 案例一：接入新 AI 平台
  - 步骤：新增适配器类 → 在 Schema 中注册平台枚举 → 在 CitationEngine 中注册映射 → 编写测试 → 部署与灰度。
  - 建议：先在本地模拟页面交互，再逐步对接真实站点；为不同页面结构准备多套选择器策略。
- 案例二：新增查询词字段
  - 步骤：在模型与 Schema 中新增字段 → 生成迁移 → 更新路由与服务层逻辑 → 前端页面与表单适配。
  - 建议：使用默认值与非空约束，确保向后兼容。
- 案例三：前端新增报表页面
  - 步骤：新增页面与路由 → 引入图表组件 → 调用后端报表接口 → 权限控制与数据可视化。
  - 建议：复用现有 UI 组件库，保持设计一致性。
- **新增** 案例四：智能体系统集成
  - 步骤：实现 Agent 能力声明 → 注册到 AgentRegistry → 配置管理 → 任务分发 → 管道编排。
  - 建议：使用心跳机制监控 Agent 状态，实现自动故障转移。
- **新增** 案例五：LLM 提供商扩展
  - 步骤：在配置中添加新提供商 → 实现工厂模式 → 更新默认配置 → 前端配置界面适配。
  - 建议：实现统一的 API 调用抽象，支持多提供商切换。

### 部署与运行要点
- 使用 Docker Compose 启动后端与前端服务，确保端口映射与网络互通。
- 后端 Dockerfile 与 requirements.txt 已配置，注意镜像构建缓存与依赖锁定。
- 前端 Dockerfile 与 Next.js 版本已固定，构建产物由 Next.js 管理。
- **新增** 智能体框架部署：确保 Redis 服务可用，配置正确的 REDIS_URL。
- **新增** 环境配置：使用 .env.example 作为模板，配置所有必要的环境变量。

**章节来源**
- [docker-compose.yml](file://docker-compose.yml)
- [backend/Dockerfile](file://backend/Dockerfile)
- [frontend/Dockerfile](file://frontend/Dockerfile)
- [backend/requirements.txt:1-35](file://backend/requirements.txt#L1-L35)
- [frontend/package.json:11-27](file://frontend/package.json#L11-L27)
- [.env.example:1-35](file://.env.example#L1-L35)