# 平台适配器扩展指南

<cite>
**本文档引用的文件**
- [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/workers/scheduler.py](file://backend/app/workers/scheduler.py)
- [backend/app/models/query.py](file://backend/app/models/query.py)
- [backend/app/config.py](file://backend/app/config.py)
- [frontend/lib/platforms.ts](file://frontend/lib/platforms.ts)
- [frontend/components/charts/platform-chart.tsx](file://frontend/components/charts/platform-chart.tsx)
- [frontend/lib/api.ts](file://frontend/lib/api.ts)
- [tests/test_citation_engine.py](file://tests/test_citation_engine.py)
</cite>

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

## 简介
本指南面向需要为系统新增AI平台适配器的开发者，提供从基类继承、实现必需方法、配置平台参数，到资源管理与性能优化的完整流程。文档同时覆盖两类平台适配策略：基于浏览器自动化（Playwright）的平台与基于API的平台，并给出测试方法、验证标准与常见问题排查建议。

## 项目结构
后端采用分层架构，平台适配器位于 workers/platforms 子目录；引用检测引擎位于 workers 子目录；查询模型与调度器分别位于 models 与 workers 子目录；前端通过 lib 与 components 提供平台映射、图表展示与API封装。

```mermaid
graph TB
subgraph "后端"
CFG["配置<br/>app/config.py"]
SCH["调度器<br/>workers/scheduler.py"]
CE["引用引擎<br/>workers/citation_engine.py"]
BP["适配器基类<br/>workers/platforms/base.py"]
KIMI["Kimi适配器<br/>workers/platforms/kimi.py"]
WENXIN["文心一言适配器<br/>workers/platforms/wenxin.py"]
QRY["查询模型<br/>models/query.py"]
end
subgraph "前端"
PFM["平台映射<br/>lib/platforms.ts"]
API["API封装<br/>lib/api.ts"]
CHART["平台图表<br/>components/charts/platform-chart.tsx"]
end
SCH --> CE
CE --> KIMI
CE --> WENXIN
CE --> QRY
BP -. 继承 .- KIMI
BP -. 继承 .- WENXIN
PFM --> CHART
API --> SCH
```

**图示来源**
- [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/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)

**章节来源**
- [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/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)

## 核心组件
- 适配器基类 BasePlatformAdapter：定义平台名称、平台URL以及抽象方法 query 与可选方法 close。
- 具体适配器 KimiAdapter 与 WenxinAdapter：均继承自基类，实现 query 方法并通过 Playwright 自动化浏览器进行交互。
- 引擎 CitationEngine：负责编排查询、调用适配器、执行品牌匹配与竞争品牌检测、持久化结果。
- 调度器 QueryScheduler：周期性触发查询任务执行。
- 查询模型 Query：承载关键词、目标品牌、别名、平台列表、频率与时间戳等元数据。
- 配置 Settings：集中管理数据库、Redis、JWT、Playwright浏览器路径及第三方API密钥等。

**章节来源**
- [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/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)

## 架构总览
下图展示了从调度器到引擎再到具体适配器的调用链路，以及前端如何消费平台映射与统计数据。

```mermaid
sequenceDiagram
participant S as "调度器<br/>workers/scheduler.py"
participant E as "引擎<br/>workers/citation_engine.py"
participant A as "适配器<br/>Kimi/Wenxin"
participant DB as "数据库<br/>SQLAlchemy"
S->>E : 触发执行查询
E->>DB : 查询待执行的 Query
loop 遍历平台
E->>A : 调用 query(keyword)
A-->>E : 返回原始响应文本
E->>E : 品牌匹配/竞争品牌检测
E->>DB : 写入引用记录与任务状态
end
E-->>S : 返回本次执行结果
```

**图示来源**
- [backend/app/workers/scheduler.py:51-84](file://backend/app/workers/scheduler.py#L51-L84)
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
- [backend/app/workers/platforms/kimi.py:33-48](file://backend/app/workers/platforms/kimi.py#L33-L48)
- [backend/app/workers/platforms/wenxin.py:33-48](file://backend/app/workers/platforms/wenxin.py#L33-L48)

## 详细组件分析

### 基类与继承规范
- 必须实现的方法
  - query(keyword: str) -> str：在指定平台查询关键词并返回原始响应文本。
- 可选方法
  - close()：释放浏览器或网络连接等资源。
- 平台元信息
  - platform_name：平台标识字符串。
  - platform_url：平台主页URL。

```mermaid
classDiagram
class BasePlatformAdapter {
+string platform_name
+string platform_url
+query(keyword) str
+close() void
}
class KimiAdapter {
+platform_name = "kimi"
+platform_url = "https : //kimi.moonshot.cn"
+query(keyword) str
+close() void
}
class WenxinAdapter {
+platform_name = "wenxin"
+platform_url = "https : //yiyan.baidu.com"
+query(keyword) str
+close() void
}
KimiAdapter --|> BasePlatformAdapter
WenxinAdapter --|> BasePlatformAdapter
```

**图示来源**
- [backend/app/workers/platforms/base.py:4-17](file://backend/app/workers/platforms/base.py#L4-L17)
- [backend/app/workers/platforms/kimi.py:11-20](file://backend/app/workers/platforms/kimi.py#L11-L20)
- [backend/app/workers/platforms/wenxin.py:11-20](file://backend/app/workers/platforms/wenxin.py#L11-L20)

**章节来源**
- [backend/app/workers/platforms/base.py:4-17](file://backend/app/workers/platforms/base.py#L4-L17)

### 浏览器驱动型平台适配策略（以Kimi/Wenxin为例）
- 启动与重用浏览器：首次调用时初始化 Playwright 并启动 Chromium 浏览器，避免重复创建。
- 页面交互：导航至平台URL，等待并定位输入框，填充关键词，提交（回车或点击发送按钮）。
- 稳定性检测：持续轮询消息容器，当文本连续多次保持一致时判定回复稳定，返回内容。
- 错误处理：捕获超时与异常，记录日志并抛出可诊断的错误；提供指数退避重试机制。
- 资源管理：在 finally 中确保 page/context 关闭；close()统一释放浏览器与Playwright实例。

```mermaid
flowchart TD
Start(["进入 query"]) --> Ensure["确保浏览器已启动"]
Ensure --> TryDo["_do_query 尝试一次查询"]
TryDo --> Stable["等待回复稳定"]
Stable --> Done["返回原始响应文本"]
TryDo --> |异常| Retry{"重试次数 < 3?"}
Retry --> |是| Backoff["指数退避等待"] --> TryDo
Retry --> |否| Raise["抛出最终异常"]
Done --> Close["关闭 page/context"]
Raise --> Close
Close --> End(["结束"])
```

**图示来源**
- [backend/app/workers/platforms/kimi.py:21-48](file://backend/app/workers/platforms/kimi.py#L21-L48)
- [backend/app/workers/platforms/kimi.py:50-124](file://backend/app/workers/platforms/kimi.py#L50-L124)
- [backend/app/workers/platforms/kimi.py:126-196](file://backend/app/workers/platforms/kimi.py#L126-L196)
- [backend/app/workers/platforms/kimi.py:198-205](file://backend/app/workers/platforms/kimi.py#L198-L205)
- [backend/app/workers/platforms/wenxin.py:21-48](file://backend/app/workers/platforms/wenxin.py#L21-L48)
- [backend/app/workers/platforms/wenxin.py:50-123](file://backend/app/workers/platforms/wenxin.py#L50-L123)
- [backend/app/workers/platforms/wenxin.py:124-195](file://backend/app/workers/platforms/wenxin.py#L124-L195)
- [backend/app/workers/platforms/wenxin.py:197-204](file://backend/app/workers/platforms/wenxin.py#L197-L204)

**章节来源**
- [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)

### API型平台适配策略（扩展指导）
- 继承基类并实现 query：通过HTTP客户端发起请求，解析JSON响应，提取平台返回的文本内容。
- 错误处理：区分网络错误、平台限流/鉴权失败、解析异常等，统一转换为可诊断的异常类型。
- 资源管理：若使用连接池或长连接，实现 close() 以释放连接；否则可为空实现。
- 配置参数：在 Settings 中添加平台API密钥与基础URL，前端与后端分别读取使用。

（本小节为概念性指导，不直接分析具体文件）

### 引擎与品牌检测
- CitationEngine 负责：
  - 初始化各平台适配器实例并注册到平台字典。
  - 针对每个 Query 的平台列表依次执行查询。
  - 使用 BrandMatcher 执行精确/别名/模糊匹配，返回置信度与位置信息。
  - 使用 CompetitorDetector 检测文本中出现的竞争品牌集合。
  - 记录 CitationRecord 并更新 Query 的时间戳与下次查询时间。
- 资源关闭：在 close() 中遍历适配器逐一关闭，避免资源泄漏。

```mermaid
classDiagram
class CitationEngine {
+dict platforms
+BrandMatcher matcher
+CompetitorDetector competitor_detector
+execute_query(query, db) list
+execute_single_platform(keyword, platform, ...) dict
+close() void
}
class BrandMatcher {
+match(text) dict
}
class CompetitorDetector {
+detect(text, target_brand) list
}
CitationEngine --> BrandMatcher : "使用"
CitationEngine --> CompetitorDetector : "使用"
```

**图示来源**
- [backend/app/workers/citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [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:1-309](file://backend/app/workers/citation_engine.py#L1-L309)

### 调度与执行
- QueryScheduler 使用 APScheduler 定时触发检查与执行逻辑，每小时扫描一次到期的查询任务。
- 对每个查询任务，CitationEngine.execute_query 会：
  - 创建或获取 QueryTask 并更新状态为 running。
  - 遍历平台列表执行查询与检测。
  - 记录结果并更新 Query 的 last_queried_at 与 next_query_at。
  - 若失败则记录错误并写入一条 cited=False 的占位记录。
- 关闭时统一调用 engine.close() 释放适配器资源。

```mermaid
sequenceDiagram
participant SCH as "调度器"
participant CE as "引擎"
participant DB as "数据库"
SCH->>CE : check_and_execute_queries()
CE->>DB : 查询 active 且到期的 Query
loop 遍历查询
CE->>DB : 获取/创建 QueryTask
CE->>CE : 执行平台查询与检测
CE->>DB : 写入 CitationRecord 与更新 Query
end
SCH->>CE : shutdown()
CE->>CE : close()
```

**图示来源**
- [backend/app/workers/scheduler.py:30-90](file://backend/app/workers/scheduler.py#L30-L90)
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)

**章节来源**
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)

### 前端集成与展示
- 平台映射：前端 lib/platforms.ts 定义平台键到中文标签的映射，用于UI显示与图表标签。
- 图表组件：components/charts/platform-chart.tsx 接收平台统计数据，渲染引用率柱状图。
- API封装：frontend/lib/api.ts 提供认证、查询、引用与报表导出等接口封装，便于前端调用。

```mermaid
graph LR
PFM["平台映射<br/>lib/platforms.ts"] --> CHART["平台图表<br/>components/charts/platform-chart.tsx"]
API["API封装<br/>lib/api.ts"] --> SCH["调度器<br/>workers/scheduler.py"]
API --> CE["引擎<br/>workers/citation_engine.py"]
```

**图示来源**
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
- [frontend/components/charts/platform-chart.tsx:34-39](file://frontend/components/charts/platform-chart.tsx#L34-L39)
- [frontend/lib/api.ts:23-57](file://frontend/lib/api.ts#L23-L57)

**章节来源**
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)

## 依赖分析
- 组件耦合
  - CitationEngine 与具体适配器松耦合：通过平台字典注册与动态查找，便于扩展新平台。
  - 调度器与引擎解耦：调度器仅负责触发，引擎负责业务逻辑与平台交互。
- 外部依赖
  - Playwright：用于浏览器自动化（Kimi/Wenxin）。
  - SQLAlchemy：用于数据库访问与事务控制。
  - APScheduler：用于定时任务调度。
  - Pydantic Settings：用于配置管理。

```mermaid
graph TB
CE["CitationEngine"] --> KIMI["KimiAdapter"]
CE --> WENXIN["WenxinAdapter"]
CE --> DB["SQLAlchemy"]
SCH["QueryScheduler"] --> CE
CE --> CFG["Settings"]
KIMI --> PW["Playwright"]
WENXIN --> PW
```

**图示来源**
- [backend/app/workers/citation_engine.py:152-155](file://backend/app/workers/citation_engine.py#L152-L155)
- [backend/app/workers/scheduler.py:26-28](file://backend/app/workers/scheduler.py#L26-L28)
- [backend/app/config.py:11-14](file://backend/app/config.py#L11-L14)
- [backend/app/workers/platforms/kimi.py:4-6](file://backend/app/workers/platforms/kimi.py#L4-L6)
- [backend/app/workers/platforms/wenxin.py:4-6](file://backend/app/workers/platforms/wenxin.py#L4-L6)

**章节来源**
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [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)

## 性能考虑
- 浏览器复用：避免每次查询都启动/关闭浏览器，减少冷启动开销。
- 稳定性检测阈值：合理设置“连续稳定”次数与轮询间隔，平衡准确性和延迟。
- 指数退避：在重试时采用指数退避，降低平台压力并提升成功率。
- 数据库批处理：批量写入引用记录与任务状态，减少IO往返。
- 超时与并发：为页面导航、元素等待与响应稳定检测设置合理超时，避免长时间阻塞。
- 缓存与预热：可在进程启动时预热部分资源（如Playwright浏览器），缩短首次查询耗时。

（本节为通用建议，不直接分析具体文件）

## 故障排查指南
- 浏览器相关
  - 现象：启动浏览器失败或找不到输入框。
  - 排查：确认已安装 Playwright 浏览器；检查平台URL可达性；核对页面选择器是否随平台更新而变更。
  - 参考实现：Kimi/Wenxin 适配器在启动失败时抛出明确提示，需按提示执行安装命令。
- 超时与不稳定
  - 现象：页面操作超时或回复未稳定。
  - 排查：适当提高等待超时与稳定检测阈值；检查网络环境与平台负载。
  - 参考实现：适配器内对超时与异常进行捕获并记录日志。
- 品牌匹配
  - 现象：匹配结果不符合预期。
  - 排查：调整别名列表、提高模糊匹配阈值或优化候选词提取逻辑。
  - 参考实现：测试用例覆盖精确、别名、模糊与无匹配场景。
- 调度与状态
  - 现象：查询未按时执行或状态异常。
  - 排查：检查调度器是否启动、数据库连接与时区设置、Query 的 next_query_at 是否正确更新。
- 前端展示
  - 现象：平台图表标签显示异常。
  - 排查：确认前端平台映射与后端平台键一致。

**章节来源**
- [backend/app/workers/platforms/kimi.py:27-31](file://backend/app/workers/platforms/kimi.py#L27-L31)
- [backend/app/workers/platforms/kimi.py:87-88](file://backend/app/workers/platforms/kimi.py#L87-L88)
- [backend/app/workers/platforms/kimi.py:116-118](file://backend/app/workers/platforms/kimi.py#L116-L118)
- [backend/app/workers/platforms/wenxin.py:27-31](file://backend/app/workers/platforms/wenxin.py#L27-L31)
- [backend/app/workers/platforms/wenxin.py:86-87](file://backend/app/workers/platforms/wenxin.py#L86-L87)
- [backend/app/workers/platforms/wenxin.py:114-116](file://backend/app/workers/platforms/wenxin.py#L114-L116)
- [tests/test_citation_engine.py:6-53](file://tests/test_citation_engine.py#L6-L53)
- [backend/app/workers/scheduler.py:30-40](file://backend/app/workers/scheduler.py#L30-L40)
- [backend/app/workers/citation_engine.py:229-232](file://backend/app/workers/citation_engine.py#L229-L232)
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)

## 结论
通过继承 BasePlatformAdapter 并遵循本文提供的实现规范与最佳实践，可以快速、安全地为系统接入新的AI平台。对于浏览器驱动型平台，重点在于稳定的选择器策略与资源管理；对于API型平台，重点在于健壮的错误处理与配置管理。配合引擎的品牌检测能力与调度器的自动化执行，可构建高可用的跨平台引用检测体系。

## 附录

### 新平台接入步骤清单
- 继承基类并实现必需方法
  - 在 workers/platforms 下新建适配器文件，继承 BasePlatformAdapter。
  - 实现 query 与可选的 close。
  - 设置 platform_name 与 platform_url。
- 注册到引擎
  - 在 CitationEngine 的平台字典中注册新适配器实例。
- 配置与密钥
  - 在 Settings 中添加必要的配置项（如API密钥、基础URL）。
- 前端集成
  - 在前端 lib/platforms.ts 中添加平台键与中文标签。
  - 如需展示统计，确保后端返回的数据结构与前端图表组件兼容。
- 测试与验证
  - 编写单元测试覆盖品牌匹配与竞争品牌检测逻辑。
  - 进行端到端测试，验证调度器触发、引擎执行与数据库写入。
- 性能与稳定性
  - 评估并优化超时、重试与稳定检测策略。
  - 监控日志与错误指标，持续改进。

（本节为流程性说明，不直接分析具体文件）