---
url: https://www.aiforge.cn/features/ai-assistant.md
---
# AI 助手

基于 `laravel/ai` 集成的后台 AI 助手能力，为管理员提供智能对话和工具调用能力。

## 功能说明

| 功能 | 说明 |
|------|------|
| SSE 流式对话 | 以 Server-Sent Events 实时推送 AI 响应，支持思考过程（reasoning）和文本输出 |
| 工具调用 | AI 可调用内置工具查询数据或执行操作（审计日志查询、验证码查询、系统设置读写、仪表盘统计、地区查询、系统信息、用户管理与站内通知、钱包流水/充值/提现查询与提现审核、财务趋势环比/充值转化漏斗/提现异常扫描、用户增长与留存分析、流失预警名单、意见反馈查询与处理、实名认证查询与审核、公告/Banner/敏感词/评论/协议管理、用户分群同步、任务系统查询、队列失败任务查询与重试、定时任务查询、App 版本查询、字典查询、管理员/角色查询、举报处理、邀请记录查询、附件查询、开放平台账户管理与令牌轮换、知识库语义检索（RAG）、网页抓取等） |
| 知识库（RAG） | 知识库文档经「段落分块 + Embedding 向量化」异步索引后，AI 可通过 `SearchKnowledgeBase` 工具做语义检索，回答平台业务规则、产品说明、操作指南等知识类问题；知识库管理见「AI 知识库」接口章节。检索引擎可配置（`KNOWLEDGE_ENGINE`）：默认 `database` 库内暴力余弦（零外部依赖）；`meilisearch` 将分块向量同步至 Meilisearch（userProvided embedder），检索下沉引擎执行，支撑大规模分块，切换后执行 `php artisan knowledge:sync-index` 迁移存量数据 |
| 工具审批 | 敏感操作（如调整用户余额、VIP 延期、重置密码等）需管理员二次审批后继续执行 |
| 对话历史 | 按会话（Conversation）保存对话记录，支持查看历史会话、删除会话 |
| 权限控制 | 接口入口由 `chat.use` 权限点保护；工具按当前管理员角色权限动态过滤，越权调用在执行层兜底拒绝 |

## 权限控制

AI 助手与后台 RBAC（`spatie/laravel-permission`）深度集成，采用三层防线防止越权：

| 防线 | 位置 | 说明 |
|------|------|------|
| 入口控制 | `ChatController` | `permission:chat.use` 中间件，无权限的管理员无法使用任何 AI 助手接口（返回 403） |
| 工具过滤 | `Assistant::tools()` | 按当前对话管理员的权限点（`canAny`）动态过滤工具列表，无权限的工具不会暴露给模型；无对话参与者时按 deny-by-default 全部过滤 |
| 执行兜底 | 各工具 `handle()` | 工具装配时注入当前管理员，执行前 `authorizeAdmin()` 二次校验，即使模型被诱导发起越权调用也会被拒绝并返回提示文案 |

实现要点：

* 工具实现 `App\Ai\Contracts\RequiresPermission` 契约声明所需权限点（支持字符串或数组，数组任一满足即可）
* 授权能力由 `App\Ai\Tools\Concerns\AuthorizesAdmin` trait 提供（`forAdmin()` 注入 + `authorizeAdmin()` 校验）
* `chat.use` 权限点随 `ai.chat` 菜单同步注册（菜单 saved 事件自动写入 permissions 表，超级管理员角色自动获得）

## 内置 AI 工具

| 工具分类 | 工具名称 | 说明 | 所需权限 |
|---------|---------|------|---------|
| Apps | ListAppVersions | 查询 App 版本列表 | `app-versions.index` |
| Audit | ListAuditLogs | 查询后台操作日志 | `audit-logs.index` |
| Audit | ListLoginHistories | 查询登录历史 | `login-histories.index` |
| Audit | ListVerificationCodes | 查询验证码记录 | `phone-codes.index` 或 `mail-codes.index`（任一） |
| Content | HandleReport | 处理用户举报（需审批） | `reports.edit` |
| Content | ListComments | 查询用户评论 | `comments.index` |
| Content | ListReports | 查询用户举报 | `reports.index` |
| Content | ModerateComment | 审核评论（需审批） | `comments.edit` |
| Feedbacks | ListFeedbacks | 查询用户意见反馈 | `feedbacks.index` |
| Feedbacks | ReplyFeedback | 处理用户反馈（需审批） | `feedbacks.edit` |
| Knowledge | SearchKnowledgeBase | 知识库语义检索（RAG） | `knowledge-documents.index` |
| Open | ListOpenAccounts | 查询开放平台账户 | `open_accounts.index` |
| Open | RotateOpenAccountToken | 轮换开放平台账户令牌（需审批） | `open_accounts.edit` |
| Open | SetOpenAccountStatus | 启用/冻结开放平台账户（需审批） | `open_accounts.edit` |
| Operation | ListAgreements | 查询用户协议列表 | `agreements.index` |
| Operation | ListAnnouncements | 查询公告列表 | `announcements.index` |
| Operation | ListBanners | 查询 Banner 列表 | `banners.index` |
| Operation | PublishAnnouncement | 发布/归档公告（需审批） | `announcements.edit` |
| Operation | SetBannerStatus | 启用/禁用 Banner（需审批） | `banners.edit` |
| Operation | UpdateAgreement | 更新用户协议（需审批） | `agreements.edit` |
| Queue | ListFailedJobs | 查询队列失败任务 | `horizon.index` |
| Queue | RetryFailedJob | 重试队列失败任务（需审批） | `horizon.index` |
| Segments | CreateUserSegment | 创建用户分群（需审批） | `segments.create` |
| Segments | ListUserSegments | 查询用户分群列表 | `segments.index` |
| Segments | SyncUserSegment | 同步规则分群成员（需审批） | `segments.edit` |
| Settings | GetSetting | 获取系统设置 | `settings.index` |
| Settings | SetSetting | 设置系统配置值（需审批） | `settings.edit` |
| Stats | GetDashboardStats | 获取仪表盘统计数据 | `chat.use` |
| Stats | GetUserGrowthStats | 用户增长/活跃/留存趋势分析 | `users.index` |
| System | AddSensitiveWord | 新增敏感词（需审批） | `sensitive-words.create` |
| System | GetAreas | 查询地区数据 | `areas.index` |
| System | ListAdmins | 查询后台管理员列表 | `admins.index` |
| System | ListAttachments | 查询附件列表 | `attachments.index` |
| System | ListDicts | 查询字典类型与字典数据 | `dicts.index` |
| System | ListRoles | 查询后台角色及权限构成 | `roles.index` |
| System | ListScheduleLogs | 查询定时任务执行日志 | `schedules.index` |
| System | ListSchedules | 查询定时任务定义 | `schedules.index` |
| System | ListSensitiveWords | 查询敏感词库 | `sensitive-words.index` |
| System | SystemInfo | 获取系统信息 | `chat.use` |
| Tasks | ListTaskLogs | 查询任务奖励发放日志 | `task-logs.index` |
| Tasks | ListTasks | 查询任务定义列表 | `tasks.index` |
| Users | GetChurnRiskUsers | 流失风险用户名单（沉默时长 + 历史活跃度规则） | `users.index` |
| Users | GetUser | 获取用户详情 | `users.index` |
| Users | ListIdentityVerifications | 查询实名认证记录 | `identity-verifications.index` |
| Users | ListInviteRecords | 查询用户邀请关系记录 | `invite-records.index` |
| Users | ListUsers | 查询用户列表 | `users.index` |
| Users | AdjustUserBalance | 调整用户积分/金币余额（需审批） | `users.edit` |
| Users | ExtendUserVip | 延长用户VIP（需审批） | `users.edit` |
| Users | GetUserSocials | 获取用户第三方绑定 | `users.index` |
| Users | ResetUserContact | 重置用户联系方式（需审批） | `users.edit` |
| Users | ResetUserPassword | 重置用户密码（需审批） | `users.edit` |
| Users | ReviewIdentityVerification | 审核实名认证（需审批） | `identity-verifications.edit` |
| Users | SendUserNotification | 向用户发送站内通知（需审批） | `users.edit` |
| Users | SetUserStatus | 设置用户状态（需审批） | `users.edit` |
| Wallet | DetectWithdrawAnomalies | 提现异常扫描（大额聚集/短时密集/新注册即提/共享账户/共享 IP） | `wallet.withdraws` |
| Wallet | GetFinanceTrends | 财务趋势按日聚合与环比 | `wallet.index` 或 `wallet.orders` 或 `wallet.withdraws`（任一） |
| Wallet | GetRechargeFunnel | 充值转化漏斗与分渠道成功率 | `wallet.orders` |
| Wallet | ListRecharges | 查询充值订单 | `wallet.orders` |
| Wallet | ListWalletTrades | 查询钱包流水 | `wallet.index` |
| Wallet | ListWithdraws | 查询提现申请 | `wallet.withdraws` |
| Wallet | ReviewWithdraw | 审核提现申请（需审批） | `wallet.withdraws` |
| Web | WebFetch | 网页抓取 | `chat.use` |

## 模型提供方（Providers）

AI 能力统一由 `laravel/ai` 驱动，提供方在 `config/ai.php` 配置：

| Provider | 驱动 | 说明 |
|----------|------|------|
| `volc`（默认） | `volc` | 火山方舟，驱动由 `larva/laravel-ai-volc` 包注册，在 OpenAI 兼容协议（chat/completions）基础上扩展了 TTS 语音合成与 Seedance 视频生成能力；覆盖文本对话、Embedding 向量、语音、图像、视频五类模型 |
| `aliyun-image` | `openai` | 阿里百炼图像生成（万相 / qwen-image） |

`volc` provider 的接入点与模型默认值均可通过环境变量覆盖：

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `VOLC_ARK_URL` / `VOLC_ARK_KEY` | `https://ark.cn-beijing.volces.com/api/v3` | 方舟接入点地址与密钥 |
| `VOLC_TEXT_MODEL` | `doubao-seed-2-1-lite-260915` | 文本对话模型 |
| `VOLC_EMBEDDINGS_MODEL` | `doubao-embedding-vision-251215` | 向量模型（知识库 Embedding） |
| `VOLC_EMBEDDINGS_DIMENSIONS` | `2048` | 向量维度（支持传 `dimensions` 降为 1024） |
| `VOLC_AUDIO_MODEL` | `doubao-seed-tts-2.0` | TTS 语音合成模型 |
| `VOLC_AUDIO_VOICE` / `VOLC_AUDIO_MALE_VOICE` | 见 `config/ai.php` | 默认女 / 男音色（SDK 占位音色 `default-female` / `default-male` 分别映射到这两项） |
| `VOLC_AUDIO_FORMAT` / `VOLC_AUDIO_SPEED` | `mp3` / `1.0` | 音频输出格式与语速 |
| `VOLC_IMAGE_MODEL` | `doubao-seedream-5-0-pro-260628` | 图像生成模型（Seedream） |
| `VOLC_IMAGE_WATERMARK` | `false` | 生成图右下角是否添加 AI 生成水印 |
| `VOLC_VIDEO_MODEL` | `doubao-seedance-2-5-260628` | 视频生成模型（Seedance，异步任务：创建任务 → 轮询结果） |

## 内置代理（Agents）

| 代理 | 用途 | 运行配置 |
|------|------|---------|
| `Assistant` | 后台 AI 助手（SSE 流式对话 + 工具调用） | `MaxSteps(12)`、`Temperature(0.3)`、`Timeout(300)` |
| `Finance` | 财务分析对话（财务数据查询、趋势环比、提现风控扫描与解读） | `MaxSteps(12)`、`Temperature(0.1)`、`Timeout(300)` |
| `Copywriter` | 运营文案生成（公告 / Banner，JSON 结构输出） | `Temperature(0.7)`、`Timeout(300)` |
| `ContentReviewer` | 内容审核辅助（评论复核 / 举报初判 / 反馈草拟） | `Temperature(0.2)`、`Timeout(300)` |
| `WechatAssistant` | 公众号智能客服（基于公开知识库问答） | `MaxSteps(4)`、`Temperature(0.4)`、`Timeout(300)` |

> 所有代理统一通过 `#[Timeout(300)]` 设置 300 秒超时，避免多步工具调用或长文本生成被默认超时中断；Banner AI 生图等一次性生成调用同样显式设置 300 秒超时。

## SSE 事件类型

聊天接口通过 `text/event-stream` 逐行推送以下事件类型：

| 事件类型 | 说明 |
|---------|------|
| `text` | 文本增量输出 |
| `reasoning` | 思考过程展示 |
| `tool_call` | 工具调用信息 |
| `tool_approval_required` | 需要人工审批的敏感操作 |
| `error` | 错误信息 |
| `done` | 流结束标记 |

## 聊天请求流转

```
POST /admin/chat → ChatController → AI Agent (laravel/ai) → Tool 调用 → SSE Stream 响应
                                            ↓ (敏感操作)
                                       审批等待 → POST /admin/chat/approve → 继续执行
```

***

> 文档来源：PRD 第 3.4 节