简介

本文件面向开发者，系统化梳理 DouPHP 智能聊天机器人的核心架构与实现要点，覆盖对话管理、会话控制、消息处理、配额与订阅、知识库匹配、流式输出等关键能力。重点解析前台 ChatService 与 SessionService 的职责边界与协作方式，说明如何基于现有接口接入不同 AI 模型、自定义对话流程与扩展功能，并提供性能优化、并发处理与错误重试的最佳实践。

项目结构

聊天功能采用分层设计：API 控制器负责路由与参数校验；前台服务层封装页面数据与对话编排；核心服务层提供会话持久化、配额校验、知识匹配与运行器；后台模块提供会话管理与运营视图。

graph TB
subgraph "API层"
Ctl["ChatController"]
end
subgraph "前台服务层"
FCS["Front ChatService"]
FSS["Front SessionService"]
end
subgraph "核心服务层"
Runner["ChatRunner"]
Store["SessionStore"]
Quota["QuotaService"]
KM["KnowledgeMatcher"]
end
subgraph "数据层"
DB["chat_session / chat_message"]
end
subgraph "后台管理"
AdminSess["Admin SessionService"]
AdminModels["Admin Models"]
end
Ctl --> FCS
Ctl --> FSS
FSS --> Runner
FSS --> Store
FSS --> Quota
FCS --> Quota
FCS --> Runner
Runner --> Store
Store --> DB
AdminSess --> AdminModels

核心组件

• API 控制器：统一暴露聊天相关端点，包括应用列表、默认应用页、应用详情、新建会话、会话列表、消息增量拉取、配额校验与流式对话。
• 前台 ChatService：负责页面数据组装（应用中心、应用对话页、套餐页、我的订阅、历史会话），以及可用模型列表与配额状态格式化。
• 前台 SessionService：负责会话生命周期（创建、查询）、消息增量拉取、配额校验与流式对话编排。
• 核心 SessionStore：会话与消息的持久化、归属校验、统计更新与关闭操作。
• 核心 KnowledgeMatcher：基于关键词、标题、标准问题的知识库召回与上下文构建。
• 后台 SessionService 与模型：提供会话列表筛选、详情查看、关闭与会话删除（连带消息）。

架构总览

聊天系统以“控制器→服务→核心服务→存储”的分层架构组织，通过统一的 JSON 响应与 SSE 流式协议对接前端与小程序。

sequenceDiagram
participant Client as "客户端"
participant API as "ChatController"
participant Svc as "SessionService"
participant Run as "ChatRunner"
participant Sto as "SessionStore"
participant Q as "QuotaService"
Client->>API : POST /chat/stream {prompt, session_sn, model_id}
API->>Svc : runStream(userId, post, ip, ua)
Svc->>Svc : 校验 prompt / 会话状态 / 应用可见性
Svc->>Q : 配额校验(免费应用按日限额/付费应用扣减订阅)
Q-->>Svc : 校验结果
Svc->>Run : resolveTurnConfig(chat, session, model_id)
Run-->>Svc : 配置(模型/提供商/密钥)
Svc->>Run : runStreamTurn(...)
Run->>Sto : appendMessage(用户消息)
Run-->>Client : SSE 文本片段(流式)
Run->>Sto : appendMessage(AI回复+用量统计)

详细组件分析

前台 ChatService：页面数据与配额展示

• 职责：构建应用中心、默认应用对话页、指定应用对话页、套餐页、我的订阅与历史会话的数据；格式化配额状态供模板渲染。
• 关键点：
  • 免费应用不要求订阅，走每日限额；付费应用无有效订阅时返回 no_subscription=true。
  • 可用模型由 AiGateway 根据应用配置的 model_ids 返回。
  • 配额状态包含 tokens/requests 的使用量、限额与剩余量的格式化字段。

前台 SessionService：会话与流式对话编排

• 职责：新建会话、会话列表、消息增量拉取、配额校验、流式对话。
• 关键点：
  • 新建会话需解析目标应用并获取 turn 配置（模型/提供商/密钥），失败则抛出不可用配置错误。
  • 会话归属校验：通过 session_sn 查找并按 user_id 校验所有权。
  • 配额分支：免费应用按 free_limit_type/free_limit_value 进行日限额校验；付费应用走订阅配额检查与扣减。
  • 流式对话：调用 ChatRunner 执行 runStreamTurn，过程中记录用户与AI消息及用量统计。

flowchart TD
Start(["进入 runStream"]) --> CheckPrompt["校验 prompt 非空"]
CheckPrompt --> |为空| ErrParam["抛出无效参数错误"]
CheckPrompt --> LoadSession["按 session_sn 加载会话并校验归属"]
LoadSession --> CheckClosed{"会话已关闭?"}
CheckClosed --> |是| ErrClosed["抛出业务规则违反(422)"]
CheckClosed --> |否| LoadChat["加载应用并校验启用/公开"]
LoadChat --> AuthCheck{"是否登录"}
AuthCheck --> |否| ErrAuth["抛出未登录(401)"]
AuthCheck --> IsFree{"是否免费应用"}
IsFree --> |是| FreeQuota["按免费应用日限额校验"]
IsFree --> |否| SubQuota["按订阅配额校验"]
FreeQuota --> Config["resolveTurnConfig"]
SubQuota --> Config
Config --> Run["runStreamTurn 执行流式对话"]
Run --> End(["结束"])

核心 SessionStore：会话与消息持久化

• 职责：创建会话、按 session_sn 查找、归属校验、会话列表、消息增量读取、追加消息并更新会话统计、关闭会话。
• 关键点：
  • 生成全局唯一 session_sn，避免冲突。
  • 追加消息时同步更新 message_count、total_tokens、last_active_at、updated_at。
  • 支持 after_id 增量轮询，减少带宽与数据库压力。

classDiagram
class SessionStore {
+create(chatId, userId, modelId, providerId, keyId, title, ip, userAgent) array|null
+findBySn(sessionSn) array|null
+owns(session, userId) bool
+listForOwner(chatId, userId, limit) array
+messages(sessionId, limit, afterId) array
+appendMessage(sessionId, role, content, extra) int
+close(sessionId) void
}

知识库匹配 KnowledgeMatcher：意图识别与上下文注入

• 职责：按触发关键词、标题、标准问题召回知识条目，并将命中条目拼接为 system 上下文段落，供客服场景优先依据回答。
• 关键点：
  • 支持限定分类范围检索。
  • 命中后自动增加 hit_count 用于效果评估。
  • 回退策略：无关键词命中时尝试标题/标准问题整词包含匹配。

flowchart TD
In(["输入 question, categoryIds, limit"]) --> Query["查询启用且符合条件的知识条目"]
Query --> Loop{"逐条判断是否命中"}
Loop --> |命中| Collect["收集命中条目"]
Loop --> |未命中| Next["下一条"]
Collect --> IncHit["批量增加 hit_count"]
Next --> Loop
IncHit --> BuildCtx["构建 system 上下文段落"]
BuildCtx --> Out(["返回 hits 或上下文字符串"])

后台会话管理：运营视角

• 职责：会话列表筛选分页（应用/状态/会员/关键字）、会话详情（消息流+元信息）、关闭会话、删除会话（连带消息）、批量操作。
• 关键点：
  • 使用 ChatSession 模型的 scope 方法组合筛选条件。
  • 消息读取通过 SessionStore 的 messages 方法限制数量，保障性能。
  • 删除前二次确认，审计日志记录。

依赖关系分析

• 控制器依赖前台服务：ChatController 依赖 ChatService 与 SessionService 完成页面数据与对话编排。
• 前台服务依赖核心服务：SessionService 依赖 ChatRunner、SessionStore、QuotaService；ChatService 依赖 AiGateway、QuotaService。
• 数据存储：SessionStore 直接操作 chat_session 与 chat_message 表；后台模型提供筛选与排序能力。
• 外部集成：AiGateway 提供可用模型列表；QuotaService 负责配额与订阅逻辑；KnowledgeMatcher 提供知识库匹配。

graph LR
Ctrl["ChatController"] --> FCS["Front ChatService"]
Ctrl --> FSS["Front SessionService"]
FSS --> Runner["ChatRunner"]
FSS --> Store["SessionStore"]
FSS --> Quota["QuotaService"]
FCS --> Quota
FCS --> Runner
Store --> DB["chat_session / chat_message"]
Runner --> Store

性能与并发

• 流式输出：通过 SSE 直出文本片段，降低首屏延迟，提升用户体验；小程序端使用 enableChunked 接收。
• 增量消息：messages 接口支持 after_id 增量拉取，减少重复传输与数据库扫描。
• 分页与限制：会话列表与消息读取均设置合理 limit，避免一次性加载过多数据。
• 配额前置校验：在流式对话前进行配额检查，快速失败，减少无效请求。
• 并发建议：
  • 在高并发场景下，确保数据库连接池与索引优化（如 session_sn、user_id、chat_id、updated_at）。
  • 对长耗时任务（如 AI 调用）建议使用队列与异步处理，避免阻塞请求线程。
  • 结合缓存（如 Redis）缓存热点应用信息与配额状态，降低数据库压力。

故障排查指南

• 未登录访问：当 userId<=0 时，接口返回未登录错误（401）。请检查认证中间件与 token 传递。
• 应用不存在或不可见：应用需启用且公开，否则返回 404。请核查应用状态与 is_public 标志。
• 会话已关闭：关闭后的会话不允许继续对话，返回 422。请引导用户新建会话。
• 配额不足：免费应用日限额或付费应用订阅配额不足时返回 422，并附带配额详情。请检查套餐与使用情况。
• 模型不可用：若 resolveTurnConfig 失败，返回配置不可用错误。请检查应用的模型配置与提供商密钥。
• 消息为空：prompt 为空将返回无效参数错误。请在前端做好输入校验。

结论

DouPHP 智能聊天机器人通过清晰的分层设计与明确的服务职责，实现了从页面数据到流式对话的完整闭环。前台 ChatService 与 SessionService 分别承担页面数据与对话编排，核心 SessionStore 保证会话与消息的一致性与可追溯性，KnowledgeMatcher 提供知识库匹配能力。结合配额与订阅机制，系统既能支撑免费应用的日限额，也能满足付费用户的订阅配额管理。开发者可基于现有接口快速集成不同 AI 模型、扩展对话流程与功能，并通过合理的性能优化与错误处理策略，保障系统的稳定性与用户体验。

附录：集成与扩展示例

• 接入不同 AI 模型：

  • 在应用中配置 model_ids，通过 AiGateway 获取可用模型列表。
  • 新建会话或流式对话时传入 model_id，由 ChatRunner 解析 turn 配置并调用对应提供商。
  • 参考路径：ChatService.php:112-137、SessionService.php:207-223

• 自定义对话流程：

  • 在 ChatRunner 中扩展 turn 逻辑，例如插入系统提示、调用工具函数或执行业务动作。
  • 通过 SessionStore.appendMessage 记录每一步交互与用量统计。
  • 参考路径：SessionStore.php:136-183

• 扩展聊天功能：

  • 新增知识库条目并在 KnowledgeMatcher 中调整匹配策略，提升客服场景准确率。
  • 在后台会话管理中增强筛选维度（如按消息内容关键词），便于运营定位问题。
  • 参考路径：KnowledgeMatcher.php:38-89、SessionService.php（后台）:52-102

• 性能优化与错误重试：

  • 对 AI 调用增加超时与重试机制，避免瞬时抖动导致失败。
  • 使用队列处理耗时任务，释放请求线程。
  • 对高频查询（如应用列表、配额状态）引入缓存层。
  • 参考路径：SessionService.php:166-223