聊天角色与工具

概述

在 AI 大模型模块中，聊天角色与工具是让对话从「通用问答」走向「场景化能力」的两个核心配置：

• 聊天角色（Chat Role）：预设一段系统提示词（system_message），并可绑定模型、知识库、工具与 MCP，把大模型「装扮」成某个固定身份或岗位，例如「前端开发专家」「客服小助手」。用户发起对话时选择角色即可获得对应的专业表现。
• 工具（Tool）：对 Function Calling / MCP 工具的注册定义。角色可引用多个工具，从而在对话中具备调用外部能力（查天气、查订单、执行动作等）的潜力。

两者均位于模块 module_ai 的 model 子域下，接口统一以 /ai 为前缀：聊天角色为 /ai/chat-role/*，工具为 /ai/tool/*。

核心概念

角色即「身份模板」

一个聊天角色本质上是一份可复用的对话配置模板。它保存了：

• 身份设定：system_message 决定模型扮演谁、遵循什么规则。
• 能力装配：绑定的模型决定「脑子」，知识库提供「记忆（RAG）」，工具 / MCP 提供「手脚（执行动作）」。
• 可见范围：由 user_id 是否为空决定是「公开角色」还是「我的角色」。

工具是「能力注册表」

工具本身只保存名称与描述这一轻量元信息（ai_tool 表），作为可被角色引用的能力清单。真正的工具调用逻辑（Function Calling、MCP Server 连接）在对话运行时按角色引用的 tool_ids / mcp_client_names 进行装配。

聊天角色管理

角色归属：公开角色与我的角色

聊天角色存在两类归属，由 user_id 字段区分，服务端在查询时强制收窄，客户端不可越权覆盖：

• 公开角色（管理端创建）：user_id 为空，由管理员在后台统一维护，对所有用户可见、可选。
• 我的角色（用户自建）：user_id 指向当前登录用户，仅本人可查看、编辑、删除。

维度	公开角色	我的角色
创建入口	管理端接口 /chat-role/create	用户端接口 /chat-role/create-my
归属	user_id = null	user_id = 当前用户
可见性	全部用户（含分类筛选）	仅本人
典型场景	平台预置「翻译官」「法务顾问」	用户自定义个人助理

角色可绑定的资源

在创建 / 编辑角色时，可为其装配以下资源（均通过编号列表引用）：

• 绑定模型（model_id）：对话默认使用的模型；若未绑定，则回退到默认的 CHAT 类型模型。
• 引用知识库（knowledge_ids）：对话时自动进行 RAG 检索，将相关片段作为上下文注入。
• 引用工具（tool_ids）：预留给 Function Calling 能力装配。
• 引用 MCP（mcp_client_names）：预留给 MCP Client 能力装配，对应 spring.ai.mcp.client 下的配置名。

说明：tool_ids 与 mcp_client_names 已在角色上完成持久化与下发，运行时工具调用的具体装配随框架演进逐步启用；知识库与系统提示词的运行时生效路径已就绪（见下文「与对话的联动」）。

数据模型要点

ai_chat_role 表关键字段：

字段	说明
user_id	归属用户，空表示管理端公开角色
name / avatar / category	名称、头像、分类（用于前端分组展示）
description	角色描述
system_message	角色设定（系统提示词）
model_id	绑定的模型编号
knowledge_ids	引用的知识库编号列表（JSON）
tool_ids	引用的工具编号列表（JSON）
mcp_client_names	引用的 MCP Client 名称列表（JSON）
sort	排序，越小越靠前
status	0-开启，1-关闭

响应模型 AiChatRoleOutSchema 额外返回 model_name（关联模型名称），方便前端直接展示。

管理端接口

权限前缀 ai:chat-role:*，用于后台统一维护公开角色。

方法	路径	说明
GET	/ai/chat-role/page	角色分页
GET	/ai/chat-role/get	角色详情
POST	/ai/chat-role/create	创建角色（user_id 置空，即公开角色）
PUT	/ai/chat-role/update	更新角色
DELETE	/ai/chat-role/delete	删除角色

用户端接口

登录即可访问，服务端强制按当前用户收窄数据范围。

方法	路径	说明
GET	/ai/chat-role/page-my	我的角色分页，支持 publicOnly 仅查公开角色
GET	/ai/chat-role/get-my	我的角色详情
POST	/ai/chat-role/create-my	创建我的角色（强制归属当前用户、启用）
PUT	/ai/chat-role/update-my	更新我的角色
DELETE	/ai/chat-role/delete-my	删除我的角色
GET	/ai/chat-role/category-list	获取启用角色的分类列表（去重排序）

工具管理

工具定位

工具是一份轻量的能力注册表，后台维护一份「可用工具清单」，供角色在编辑时通过下拉选择引用。其本身只记录名称与描述，真正的执行逻辑由对话框架在运行时解析。

管理端接口

权限前缀 ai:tool:*。

方法	路径	说明
GET	/ai/tool/page	工具分页
GET	/ai/tool/get	工具详情
POST	/ai/tool/create	创建工具
PUT	/ai/tool/update	更新工具
DELETE	/ai/tool/delete	删除工具
GET	/ai/tool/simple-list	启用工具的简单列表（仅返回 id/name，供角色表单下拉使用）

AiToolSimpleOutSchema 仅包含 id 与 name，专为前端 ApiSelect 下拉选择设计。

前端使用

管理端页面

路径：AI 管理 → 聊天角色 / 工具。

• 聊天角色 apps/web-ele/src/views/ai/model/chatRole/：基于 Vben 表格（useVbenVxeGrid）实现分页、搜索、新增 / 编辑（modules/form.vue）、删除。表单字段含名称、描述、角色设定、绑定模型、引用知识库、引用工具、引用 MCP、头像、排序与状态。
• 工具 apps/web-ele/src/views/ai/model/tool/：维护工具清单与启停状态，启用项自动进入角色的「引用工具」下拉（/ai/tool/simple-list）。

表单中「引用知识库 / 引用工具 / 引用 MCP / 角色头像」为公共引用字段（useFormRefFields），知识库数据源按场景区分：管理端用全量列表，我的角色用「我的知识库」列表。

用户端：我的角色与公共角色

路径：AI 对话 → 角色抽屉（apps/web-ele/src/views/ai/chat/index/modules/role/）。

对话页通过抽屉展示角色库，分为两个标签页：

• 我的角色：调用 /chat-role/page-my（不带 publicOnly），支持新增（my-create）、编辑、删除与分页加载。
• 公共角色：调用 /chat-role/page-my?publicOnly=true，并按 category-list 提供的分类做筛选。

顶部搜索支持按名称过滤；点击卡片的「使用」会调用 /ai/chat-role/... 创建会话并携带 roleId，随后跳转至对应对话页，立即获得角色设定的对话体验。

与对话的联动

聊天角色在对话中通过 role_id 生效。用户在发起对话时携带角色编号，会话创建时会将角色的 system_message 与 model_id 固化到会话；后续每条消息发送时，运行时按以下顺序解析能力：

核心解析逻辑位于消息服务：

• _resolve_role_system：优先用请求中的 role_id，否则用会话 role_id，取出 system_message 作为系统提示。
• _resolve_knowledge_ids / _resolve_knowledge_context：读取角色 knowledge_ids，对最新用户提问做 RAG 检索，将命中片段拼装为引用上下文；无绑定或检索失败时不阻断对话。

模型与知识库的装配已打通；工具（tool_ids）与 MCP（mcp_client_names）已完成角色侧绑定与下发，运行时调用随框架能力迭代接入。