智能体管理后台前端开发设计文档智能体管理后台前端开发设计文档文档版本：v0.2-draft 创建日期：2026-04-

智能体管理后台前端开发设计文档

文档版本：v0.2
创建日期：2026-04-13
更新日期：2026-04-15
文档类型：前端页面协作文档
文档状态：评审稿
权限前提：仅超管可见、仅超管可用

1. 文档说明

1.1 文档目标

本文档用于对齐智能体管理后台的页面设计和前后端协作方式，重点说明以下内容：

给产品说明页面的业务逻辑、用户操作流程和关键交互方式
给前端说明页面的组件拆分、关键业务字段和组件通信方式
给后端说明页面需要的能力以及前端期望的数据返回结构

本文档不约束后端接口地址、请求方式和具体入参设计。

1.2 阅读指引

产品重点关注：第 2 章、第 3 章中的页面说明和交互流程
前端重点关注：第 3 章中的组件拆分、关键业务字段设计、组件通信设计
后端重点关注：第 3 章中的后端接口能力需求、期望返回数据格式，以及第 4 章的公共字段说明

1.3 组件拆分说明

本模块的组件拆分不按原型结构机械拆分，而是优先根据业务职责和复杂度决定。

原则如下：

具有独立业务职责、字段较多、交互较复杂、后续可能复用的区域，建议拆分为独立组件
仅用于简单确认、简单录入、简单展示的浮层、弹窗、下拉菜单，不强制拆分为独立组件
页面级请求编排、保存提交、发布下线等主流程动作，统一由页面组件负责
子组件优先承担独立业务区域的渲染和局部交互，不承担页面主流程编排

2. 模块整体说明

2.1 模块目标

智能体管理后台面向超管，提供智能体从创建、配置、调试、发布到运行查看的完整管理入口。

模块主要支持以下能力：

查看和管理智能体列表
配置智能体基础信息、Prompt、知识和工具
调试智能体效果

3. 页面设计

3.1 智能体首页

智能体首页对应路由建议为：

3.1.1 页面说明

智能体首页是智能体管理后台的默认入口页，面向超管使用。

该页面主要解决三件事：

让用户快速看到当前智能体整体情况
让用户快速筛选和找到某个智能体
让用户直接在首页完成新建、发布、下线、删除、权限设置等高频操作

3.1.2 页面交互流程

页面区域

首页由 4 个主要区域组成：

区域	说明
标题区	展示页面标题和副标题，用于说明当前页面是“智能体管理”首页
统计区	展示总数量、已发布、草稿、已下线四个指标
工具栏	提供新建、应用筛选、关键字搜索、状态筛选、刷新等操作
卡片区	展示智能体卡片列表，并提供卡片点击和更多操作菜单

用户操作流程

用户动作	页面行为	结果反馈
进入页面	自动加载统计数据、应用筛选项、卡片列表	页面展示首页内容
点击“新建智能体”	打开新建流程	用户填写基础信息后创建智能体
选择应用筛选	按所选应用重新查询列表	卡片区刷新
输入关键字搜索	按关键字重新查询列表	卡片区刷新
选择状态筛选	按状态重新查询列表	卡片区刷新
点击刷新	按当前条件重新加载统计和列表	页面数据更新
点击卡片	进入该智能体配置页	页面跳转
点击“更多操作”	打开卡片操作菜单	用户可继续执行权限设置、编辑、预览、发布、下线、删除
点击“权限设置”	打开权限配置流程	用户可修改可见/可用范围
点击“发布”	执行校验	成功后刷新首页数据
点击“下线”	弹出二次确认	成功后刷新首页数据
点击“删除”	弹出二次确认	成功后刷新首页数据并移除该卡片

卡片更多操作规则

卡片状态	可执行操作
DRAFT（草稿）	权限设置、编辑、预览、发布、删除
PUBLISHED（已发布）	权限设置、编辑、预览、下线
OFFLINE（已下线）	权限设置、编辑、预览、删除

页面反馈规则

动作	是否需要确认	成功反馈	后续处理
新建智能体	否	提示创建成功	刷新统计和列表
发布	否	提示发布成功	刷新统计和列表，保留当前筛选条件
下线	是	提示下线成功	刷新统计和列表，保留当前筛选条件
删除	是	提示删除成功	刷新统计和列表
权限设置保存	否	提示保存成功	结束当前权限配置流程

3.1.3 前端组件拆分

首页建议按“页面组件 + 独立业务区域组件”拆分。

组件名	主要职责
AgentHomePage.vue	管理页面状态、加载首页数据、处理页面动作
AgentHomeToolbar.vue	承载筛选、搜索、新建、刷新等工具栏业务
AgentHomeCardList.vue	渲染卡片列表和卡片动作

3.1.4 关键业务字段设计

首页筛选字段

AgentHomeFilterValue

字段名	类型	说明
applicationId	string	应用筛选值，空值表示全部
keyword	string	搜索关键字，可匹配名称、ID、描述
publishStatus	'DRAFT' \| 'PUBLISHED' \| 'OFFLINE' \| ''	状态筛选值

统计字段

AgentOverviewStats

字段名	类型	说明
totalCount	number	总数量
publishedCount	number	已发布数量
draftCount	number	草稿数量
offlineCount	number	已下线数量

卡片字段

AgentCardSummary

字段名	类型	说明
id	string	智能体主键 ID
agentId	string	智能体编号，用于展示
agentName	string	智能体名称
publishStatus	'DRAFT' \| 'PUBLISHED' \| 'OFFLINE'	发布状态
publishStatusText	string	状态展示文案
description	string	智能体描述
applicationId	string	所属应用 ID
applicationName	string	所属应用名称
iconUrl	string	图标地址
updatedAt	string	最后更新时间

权限选择结果字段

PermissionSelectedItem

字段名	类型	说明
id	string	对象 ID
name	string	对象名称
type	string	对象类型，如用户、部门、角色

3.1.5 组件通信设计

AgentHomeToolbar.vue

props

字段名	类型	说明
applicationOptions	SelectOption[]	应用筛选项
statusOptions	SelectOption[]	状态筛选项
modelValue	AgentHomeFilterValue	当前筛选值

emits

事件名	参数	说明
update:modelValue	AgentHomeFilterValue	筛选条件变更
search	AgentHomeFilterValue	点击查询或回车搜索
create	-	点击新建智能体
refresh	-	点击刷新

AgentHomeCardList.vue

props

字段名	类型	说明
list	AgentCardSummary[]	卡片列表数据

emits

事件名	参数	说明
cardClick	AgentCardSummary	点击卡片
actionClick	{ actionKey, agentCard }	点击卡片更多操作

actionClick 参数字段

字段名	类型	说明
actionKey	'permissionSetting' \| 'edit' \| 'preview' \| 'publish' \| 'delete' \| 'offline'	动作标识
agentCard	AgentCardSummary	当前卡片数据

3.1.6 后端接口能力需求

能力名称	使用场景	用途说明
查询首页统计	页面初始化、点击刷新后	获取首页右上角四个统计值
查询应用筛选项	页面初始化	获取应用下拉选项
查询智能体列表	页面初始化、筛选、搜索、刷新	获取首页卡片列表
创建智能体	点击新建并提交后	创建一个新的草稿智能体
查询智能体详情	点击卡片进入详情页前或进入后	获取智能体详情数据
发布智能体	点击发布确认后	将草稿状态改为已发布
下线智能体	点击下线确认后	将已发布状态改为已下线
删除智能体	点击删除确认后	删除当前智能体
查询权限配置	打开权限配置流程时	获取当前已配置的权限范围
保存权限配置	点击权限设置保存后	保存当前权限配置结果

3.1.7 期望返回数据格式

首页统计数据

{
  "totalCount": 12,
  "publishedCount": 6,
  "draftCount": 4,
  "offlineCount": 2
}

应用筛选项数据

[
  {
    "label": "CRM 应用",
    "value": "app001"
  },
  {
    "label": "流程应用",
    "value": "app002"
  }
]

智能体卡片列表数据

[
  {
    "id": "1",
    "agentId": "9527",
    "agentName": "营销助手",
    "publishStatus": "PUBLISHED",
    "publishStatusText": "已发布",
    "description": "用于活动咨询与问题解答",
    "applicationId": "app001",
    "applicationName": "CRM 应用",
    "iconUrl": "",
    "updatedAt": "2026-04-13 10:30:00"
  }
]

创建智能体结果

{
  "id": "2"
}

权限配置回显数据

[
  {
    "id": "u001",
    "name": "张三",
    "type": "user"
  },
  {
    "id": "d001",
    "name": "研发部",
    "type": "department"
  }
]

动作结果

{
  "success": true
}

3.2 智能体配置页

3.2.1 页面说明

智能体配置页用于承载单个智能体的基础信息和各类配置入口，是单个智能体的主编辑页。

页面核心任务：

展示当前智能体的基础信息和状态
作为 Prompt、知识、工具等配置页面的统一入口
承接预览、返回、发布调试等主流程动作

3.2.2 页面交互流程

建议页面由“顶部信息区 + 左侧导航区 + 右侧配置区”构成。

关键交互包括：

进入页面后加载当前智能体详情
点击左侧导航切换不同配置区域
在当前配置区域编辑并保存

详细内容在子页面章节展开。

3.2.3 前端组件拆分

顶部信息区和左侧导航区业务较轻，建议不单独拆分组件，统一由页面组件承接。

组件名	主要职责
AgentEditorPage.vue	承接页面级编排、详情加载、路由切换；包含顶部信息区与左侧导航区；渲染右侧面板容器
AgentBasicInfoPanel.vue	主要信息面板：名称、所属应用、描述、智能体 Prompt；独立保存
AgentModelPanel.vue	大模型配置面板；独立保存
AgentDialogEnhancePanel.vue	对话增强配置面板；独立保存
AgentKnowledgeBasePanel.vue	知识库配置面板；独立保存
AgentBusinessKnowledgePanel.vue	业务知识配置面板；独立保存
AgentSubAgentsPanel.vue	子智能体配置面板；独立保存
AgentSkillPanel.vue	技能配置面板；独立保存
AgentPermissionPanel.vue	权限配置面板；独立保存
AgentApiAccessPanel.vue	访问 API 配置面板；独立保存
AgentAutomationPanel.vue	自动化配置面板；独立保存

路由组织建议使用嵌套路由：detail/:id 为页面壳路由，右侧面板为子路由（如 basic / model / dialog-enhance / knowledge-base / knowledge-biz / sub-agents / skills / permission / api-access / automation），默认进入 basic。

3.2.4 关键业务字段设计

AgentBaseDetail

字段名	类型	说明
agentId	string	智能体编号
agentName	string	智能体名称
publishStatus	'DRAFT' \| 'PUBLISHED' \| 'OFFLINE'	当前发布状态

3.3 主要信息（基础信息）

3.3.1 页面说明

主要信息面板用于维护单个智能体的核心可编辑信息。

字段规则：

可编辑：智能体名称、描述、智能体 Prompt
只读：所属应用（永远不可改，使用只读输入框展示 applicationName）

面板内提供独立“保存”按钮，仅保存本面板可编辑字段。

3.3.2 页面交互流程

进入面板后，调用查询智能体基础信息接口回填表单
用户编辑名称/描述/Prompt
点击保存：
- 校验通过后调用“保存主要信息”接口
- 成功提示，并调用 refreshAgentBaseDetail() 刷新顶部信息区展示（如名称、状态等）
- 失败提示，保留当前输入内容

说明：切换左侧菜单不做未保存拦截，未保存即视为放弃当前面板修改。

3.3.3 前端组件拆分

组件名	主要职责
AgentBasicInfoPanel.vue	渲染主要信息表单与保存按钮；管理本面板数据加载、校验与提交

3.3.4 关键业务字段设计

AgentMainInfo

字段名	类型	说明
agentName	string	智能体名称
applicationName	string	所属应用名称（只读输入框展示）
description	string	描述
prompt	string	智能体 Prompt

AgentMainInfoSavePayload

字段名	类型	说明
id	string	智能体主键 ID
agentName	string	智能体名称
description	string	描述
prompt	string	智能体 Prompt

3.3.6 后端接口能力需求

能力名称	使用场景	用途说明
查询主要信息	初始化	回填主要信息表单字段
保存主要信息	点击保存	仅保存可编辑字段

3.3.7 期望返回数据格式

保存主要信息

{
  "success": true
}

3.4 大模型

3.4.1 页面说明

大模型面板用于管理“智能体已绑定的大模型”列表，支持：

从“已有模型库”选择并添加到智能体（不能在此模块创建模型）
添加时配置温度（temperature），添加成功后在列表生成一条新数据
列表内支持：配置温度、启用/停用、删除、筛选/搜索/刷新

3.4.2 页面交互流程

进入面板

请求“智能体已绑定模型列表”，并按默认条件展示（搜索为空、类型=全部、状态=全部）

筛选/搜索/刷新

输入关键词（模型名称模糊匹配）、选择类型（全部/对话模型/嵌入模型）、选择状态（全部/启用/停用）后重新请求列表
点击刷新：按当前条件重新请求列表

添加大模型（单弹框，Popover 配温度，不套娃）

点击“+ 添加大模型”打开弹框
弹框请求“可选模型库列表”，支持关键词搜索
每条模型右侧有“添加”按钮，点击后在按钮旁打开“温度 Popover”
在 Popover 内输入温度（默认 0.2）并点“确定”：
- 调用“添加模型到智能体”接口（携带 agentId + modelId + temperature）
- 成功：该条在弹框内变为“已添加”（禁用添加）；同时主列表新增一条数据（刷新列表或本地插入）
- 失败：Popover 保持打开并提示错误，保留用户输入

列表内配置温度（Popover，同一交互范式复用）

点击某条卡片的“配置”，在“配置”旁打开温度 Popover，回填当前温度
点击“确定”：
- 调用“更新温度”接口（携带 agentModelId(关联记录id) + temperature）
- 成功：Popover 关闭，卡片温度展示更新
- 失败：Popover 保持打开并提示错误，保留输入

启用/停用

切换开关调用“更新启用状态”接口；成功后更新该条状态（允许乐观更新，失败则回滚）

删除

点击删除二次确认；确认后调用删除接口；成功后移除该条并刷新/本地删除

Popover 行为约束（避免误触与错位）：

只允许同时打开一个温度 Popover（打开新的会关闭旧的）
Popover 不因点击空白处自动关闭，只能通过“取消/确定/关闭按钮”关闭
列表或弹框内容发生滚动时，强制关闭 Popover（避免浮层定位错位）
Popover 打开/提交中，禁用该条的其他操作（删除、开关、再次配置/添加）

3.4.3 前端组件拆分

组件名	主要职责
AgentModelPanel.vue	面板唯一业务组件：工具栏、列表、添加弹框、接口调用、状态管理
ModelTemperaturePopover.vue	可复用温度配置 Popover（新增与列表配置复用，也可供外部模型列表复用）

说明：

除温度 Popover 需要跨模块复用外，其余 UI 片段（卡片/弹框列表项）不单独拆组件，保持模块简单
ModelTemperaturePopover.vue 为通用组件，只负责温度编辑与确认动作，不直接调用接口

3.4.4 关键业务字段设计

ModelType

'CHAT'：对话模型
'EMBEDDING'：嵌入模型

ModelStatus

'ENABLED'：启用
'DISABLED'：停用

ModelCatalogItem（模型库项）

字段名	类型	说明
modelId	string	模型库ID
modelName	string	模型名称
modelType	ModelType	模型类型
providerName	string	提供商
capabilities	string[]	能力标签（弹框列表展示）
description	string	简介

AgentModelItem（智能体绑定模型项）

字段名	类型	说明
id	string	关联记录ID（智能体-模型绑定ID）
agentId	string	智能体ID
modelId	string	模型库ID
modelName	string	模型名称
modelType	ModelType	模型类型
providerName	string	提供商
temperature	number	温度（0~2，步进0.1）
status	ModelStatus	启用状态

温度校验规则（前后端一致）：

0 <= temperature <= 2
步进 0.1（UI 约束），后端按 number 接收

3.4.5 组件通信设计

AgentModelPanel.vue 获取 agentId（建议来自路由或页面壳 props）
ModelTemperaturePopover.vue 作为通用组件，通过 props/emits 与宿主通信，不依赖 provide/inject

ModelTemperaturePopover.vue 组件 API（供复用）

Props：
- open: boolean（或 v-model:open）
- value: number（当前温度，用于回填）
- min?: number = 0, max?: number = 2, step?: number = 0.1
- loading?: boolean（确定按钮 loading）
- disabled?: boolean（禁用输入与按钮）
- title?: string = "温度"（表单标题）
Emits：
- update:open(boolean)
- confirm(number)（点击确定）
- cancel()（点击取消）
Slots：
- reference（触发器插槽：宿主提供“添加/配置”按钮）

行为要求（组件内部实现约束）：

采用手动控制显示（manual open），不自动因点击外部关闭
宿主在滚动事件时统一关闭 open=false

3.4.6 后端接口能力需求

能力名称	使用场景	用途说明
查询智能体模型列表	进入面板、筛选/搜索、刷新	返回 `AgentModelItem[]`
查询模型库列表	打开添加弹框、搜索	返回 `ModelCatalogItem[]`
添加模型到智能体	添加 Popover 确定	创建绑定记录并返回新记录ID（或 success）
更新模型温度	列表配置 Popover 确定	更新绑定记录温度
更新模型启用状态	切换开关	启用/停用绑定记录
删除智能体模型	删除确认	删除绑定记录

3.4.7 期望返回数据格式

查询智能体模型列表

[
  {
    "id": "am001",
    "agentId": "1",
    "modelId": "m001",
    "modelName": "MiniMax-M2.5",
    "modelType": "CHAT",
    "providerName": "MiniMax",
    "temperature": 0.2,
    "status": "ENABLED"
  }
]

查询模型库列表

[
  {
    "modelId": "m001",
    "modelName": "MiniMax-M2.5",
    "modelType": "CHAT",
    "providerName": "MiniMax",
    "capabilities": ["图片输入"],
    "description": "..."
  }
]

变更类接口（添加/更新/启用/删除）

{ "success": true }

3.5 对话增强

3.5.1 页面说明

对话增强用于增强智能体会话体验，包含三种配置模式：

开场白：配置进入会话时展示的引导文案
预设问题：配置推荐问题列表，支持增删改、启停、筛选、自动推荐开关
自定义Prompt：配置增强 Prompt 规则，支持增删改、启停、批量操作、查看基础 Prompt

三类能力按 Tab 切换，互相独立保存，不做跨 Tab 联动校验。

3.5.2 页面交互流程

A. Tab 切换

顶部切换：开场白 / 预设问题 / 自定义Prompt
切换到某个 Tab 时，仅查询当前 Tab 数据，不预加载其他 Tab
未保存草稿不做离开拦截，切换即放弃当前未保存输入

B. 开场白

进入 Tab 后查询当前开场白内容
编辑文本后点击保存，调用“保存开场白配置”
字数限制 <= 500，展示字数计数

C. 预设问题

进入 Tab 后查询预设问题列表和“自动推荐问题”开关状态
支持关键词搜索、角色筛选、状态筛选
点击“添加问题”或“编辑”时，在 PresetQuestionManager.vue 内打开弹窗
弹窗字段：问题、角色、优先级、状态
支持单条启停、删除
“自动推荐问题”开关单独保存，不和问题表单合并提交

D. 自定义Prompt

进入 Tab 后查询自定义 Prompt 配置列表
支持“添加优化配置”“查看智能体Prompt”
点击“添加优化配置”或“编辑”时，在 CustomPromptManager.vue 内打开弹窗
弹窗字段：配置名称、配置描述、优化提示词内容、优先级、状态
列表支持单条启停、编辑、删除
支持多选后批量启用、批量禁用、批量删除
“智能体Prompt”在 AgentDialogEnhancePanel.vue 内用统一弹层只读展示，不在此处编辑

3.5.3 前端组件拆分

组件名	主要职责
AgentDialogEnhancePanel.vue	对话增强主模块：Tab 切换、开场白配置、当前子模块装配、基础 Prompt 查看弹层
PresetQuestionManager.vue	预设问题通用子模块：工具栏、列表、筛选、自动推荐开关（可选）、内置新增/编辑弹窗
CustomPromptManager.vue	自定义Prompt子模块：批量操作栏、卡片列表、内置新增/编辑弹窗

3.5.4 关键业务字段设计

DialogEnhanceTabKey

'GREETING'：开场白
'PRESET_QUESTION'：预设问题
'CUSTOM_PROMPT'：自定义Prompt

GreetingConfig

字段名	类型	说明
greetingText	string	开场白内容，<= 500

PresetQuestionItem

字段名	类型	说明
id	string	预设问题记录ID
question	string	问题内容
roleId	string	角色ID
roleName	string	角色名称
priority	number	优先级，数字越小越靠前
status	'ENABLED' \| 'DISABLED'	启用状态
creatorName	string	创建人
createdAt	string	创建时间
updaterName	string	最后修改人
updatedAt	string	最后修改时间

PresetQuestionForm

字段名	类型	说明
question	string	问题内容，必填，<= 500
roleId	string	角色ID，可选
priority	number	优先级，必填，正整数
status	'ENABLED' \| 'DISABLED'	状态

PresetQuestionRecommendConfig

字段名	类型	说明
autoRecommendEnabled	boolean	是否自动推荐预设问题

PresetQuestionManagerScene

'dialog-enhance'：对话增强场景
'sub-agent'：子智能体场景

CustomPromptItem

字段名	类型	说明
id	string	自定义Prompt记录ID
configName	string	配置名称
configDesc	string	配置描述，<= 500
promptContent	string	优化提示词内容，<= 20000
priority	number	优先级，数字越小越靠前
status	'ENABLED' \| 'DISABLED'	启用状态

CustomPromptForm

字段名	类型	说明
configName	string	配置名称，必填
configDesc	string	配置描述，可选
promptContent	string	优化提示词内容，必填
priority	number	优先级，必填，正整数
status	'ENABLED' \| 'DISABLED'	状态

3.5.5 组件通信设计

AgentDialogEnhancePanel.vue 通过 props 接收 agentId。

AgentDialogEnhancePanel.vue 内部直接管理：

当前 TabKey
开场白表单与保存
“智能体Prompt”查看弹层开关与只读内容加载

PresetQuestionManager.vue 内部自管：

列表查询参数
自动推荐开关
新增/编辑弹窗状态
单条增删改启停

PresetQuestionManager.vue 对外输入口径：

agentId
scene
showAutoRecommend
subAgentId?

说明：

当 scene='dialog-enhance' 时，组件作用于 3.5 对话增强，并显示“自动推荐问题”开关。
当 scene='sub-agent' 时，组件作用于 3.8 子智能体预设问题配置，不显示“自动推荐问题”开关。
组件内部根据 scene 切换接口作用域，而不仅仅是切换显隐。

CustomPromptManager.vue 内部自管：

列表数据与选中态
批量操作
新增/编辑弹窗状态
单条增删改启停

父组件不接管子模块内部 CRUD，只负责 Tab 级别切换与轻量级页面状态。

3.5.6 后端接口能力需求

能力名称	使用场景	用途说明
查询开场白配置	进入开场白 Tab	获取当前开场白内容
保存开场白配置	点击保存开场白	保存开场白文本
查询预设问题列表	进入预设问题 Tab、筛选/刷新	获取预设问题列表
新增预设问题	添加问题确认	创建一条预设问题记录
更新预设问题	编辑问题确认	更新预设问题
更新预设问题状态	切换单条启停	启用/停用单条预设问题
删除预设问题	点击删除确认	删除单条预设问题
查询角色选项	进入预设问题 Tab/打开弹窗	获取角色选项
查询自动推荐状态	进入预设问题 Tab	获取自动推荐开关状态
保存自动推荐状态	切换自动推荐开关	更新自动推荐开关
查询自定义Prompt列表	进入自定义Prompt Tab	获取增强 Prompt 配置列表
新增自定义Prompt	添加优化配置确认	创建一条增强 Prompt 配置
更新自定义Prompt	编辑优化配置确认	更新增强 Prompt 配置
更新自定义Prompt状态	切换单条启停	启用/停用单条配置
批量更新自定义Prompt状态	批量启用/禁用	批量修改选中记录状态
批量删除自定义Prompt	批量删除确认	批量删除选中记录
删除自定义Prompt	单条删除确认	删除单条配置
查询智能体Prompt全文	点击“智能体Prompt”	获取基础 Prompt 全文用于只读查看

3.5.7 期望返回数据格式

查询开场白配置

{
  "greetingText": "您好，我可以帮助您查询合同台账、付款与统计信息。"
}

查询预设问题列表

[
  {
    "id": "pq001",
    "question": "今年的合同总额有多少？",
    "roleId": "role001",
    "roleName": "班子成员",
    "priority": 1,
    "status": "ENABLED",
    "creatorName": "合同管理员",
    "createdAt": "2026-04-01 13:52:15",
    "updaterName": "合同管理员",
    "updatedAt": "2026-04-01 13:52:15"
  }
]

查询自定义Prompt列表

[
  {
    "id": "cp001",
    "configName": "合同金额",
    "configDesc": "这是一个增强prompt的配置",
    "promptContent": "1. 查询的合同金额需要精确到小数点后两位。",
    "priority": 1,
    "status": "ENABLED"
  }
]

查询智能体Prompt全文

{
  "promptContent": "- Role: 产品经理兼数据驱动型业务策略专家..."
}

变更类接口

{
  "success": true
}

3.6 知识库

3.6.1 页面说明

知识库用于维护当前智能体可召回的知识数据，支持三类知识：

文档（文件上传）
问答对（Q&A）
常见问题（FAQ）

模块能力包括：

列表查询、分页、按创建时间倒序展示
单条新增、编辑、删除
召回开关即时生效
同步知识到向量库
导出问答对/常见问题
Excel 批量导入问答对/常见问题

说明：

分块策略 是知识入库与向量化的配置项，在列表中以标签展示。
向量化状态 仅用于状态展示，不在本版作为查询条件。
是否召回 是业务开关，切换即保存。

3.6.2 页面交互流程

A. 列表查询

进入面板后查询知识列表，默认按创建时间倒序，支持分页。
查询区包含：
- 快速查询：按知识标题搜索，支持清空
- 知识类型：文档（文件上传）/问答对（Q&A）/常见问题（FAQ），支持清空
- 是否召回：召回/不召回，支持清空
切换查询条件后重新请求列表。

B. 列表区

表格列：序号 / 标题 / 类型 / 分块策略 / 向量化状态 / 创建时间 / 是否召回 / 操作
分块策略 以标签展示。
向量化状态 固定展示 待处理 / 处理中 / 已完成 / 失败，并以颜色区分。
是否召回 使用开关，切换后立即调用接口保存，并提示“召回成功 / 取消召回成功”。
编辑：打开“编辑知识”弹窗。
删除：二次确认“确认要删除该知识吗？”，确认后执行删除。

C. 添加/编辑知识

点击“添加知识”打开弹窗，默认选中 文档（文件上传）。
同一弹窗支持新增和编辑；编辑时回填当前记录。
不同知识类型渲染不同字段：
- 文档（文件上传）
  - 知识类型（必填）
  - 知识标题（必填，<= 50）
  - 分块策略（必填，仅文档显示）
  - 上传文件（新增时必填；编辑时可选，若重新上传则覆盖原文件）
- 问答对（Q&A）
  - 知识类型（必填）
  - 知识标题（必填，<= 50）
  - 问题（必填，<= 50）
  - 答案（必填，<= 800）
- 常见问题（FAQ）
  - 字段与 Q&A 相同
文档类型下分块策略默认 递归分块；其余类型默认按 Token 分块 入库，不在弹窗中展示分块策略选择。
分块策略切换时显示对应说明文案：
- Token 分块
- 递归分块
- 句子分块
- 段落分块
- 语义分块
保存成功后关闭弹窗并刷新列表。

D. 批量导入

点击“导入知识”打开“批量导入”弹窗，两步流程：
1. 上传 Excel
2. 导入数据
上传阶段支持拖拽/点击上传，文件限制：
- 仅支持 xls/xlsx
- 大小 <= 10MB
弹窗内展示导入说明：
- 支持下载标准模板
- 默认导入新增数据；若 Excel 中带有导出数据里的 id，则按 id 更新
- 仅支持导入 问答对（Q&A） 和 常见问题（FAQ）
导入完成后展示结果：成功条数、失败条数；若存在失败数据，支持“下载错误报告”。

E. 同步到向量库

点击“同步到向量库”后，对当前智能体知识库执行同步。
同步成功后刷新列表中向量化状态。

F. 导出知识

点击“导出知识”先提示：“仅支持导出问答对和常见问题，确认导出当前列表的知识吗？”
确认后导出当前查询结果中知识类型为 Q&A / FAQ 的记录。
导出数据中包含 id，便于后续再次导入时更新。

3.6.3 前端组件拆分

组件名	主要职责
AgentKnowledgeBasePanel.vue	知识库主模块：查询区、列表、分页、召回开关、同步/导出操作、弹窗编排
KnowledgeEditDialog.vue	新增/编辑知识弹窗：三类知识动态表单、字段校验、文件上传、保存提交
KnowledgeBatchImportDialog.vue	通用批量导入弹窗：两步导入流程、模板下载、上传校验、导入结果与错误报告下载

拆分说明：

AgentKnowledgeBasePanel.vue 必须独立承接列表型业务，不能把查询、分页、召回、同步、导出都塞进弹窗组件。
KnowledgeEditDialog.vue 单独拆出是有必要的，因为它承载“多知识类型动态表单 + 文件上传 + 分块策略说明”的复杂状态。
KnowledgeBatchImportDialog.vue 单独拆出是有必要的，因为它是一个独立两步流程，并由 3.6 知识库 与 3.7 业务知识 共用。
不再继续细拆表格行组件或分块策略说明组件，当前复杂度不值得。

3.6.4 关键业务字段设计

KnowledgeType

'DOCUMENT'：文档（文件上传）
'QA'：问答对（Q&A）
'FAQ'：常见问题（FAQ）

ChunkStrategy

'TOKEN'：Token 分块
'RECURSIVE'：递归分块
'SENTENCE'：句子分块
'PARAGRAPH'：段落分块
'SEMANTIC'：语义分块

VectorizationStatus

'PENDING'：待处理
'PROCESSING'：处理中
'COMPLETED'：已完成
'FAILED'：失败

KnowledgeItem

字段名	类型	说明
id	string	知识记录ID
title	string	知识标题
knowledgeType	KnowledgeType	知识类型
chunkStrategy	ChunkStrategy	分块策略
vectorizationStatus	VectorizationStatus	向量化状态
recallEnabled	boolean	是否召回
createdAt	string	创建时间

DocumentKnowledgeForm

字段名	类型	说明
title	string	知识标题，必填，<= 50
knowledgeType	'DOCUMENT'	知识类型
chunkStrategy	ChunkStrategy	分块策略，必填
file	File	上传文件，新增必填

QaKnowledgeForm

字段名	类型	说明
title	string	知识标题，必填，<= 50
knowledgeType	'QA' \| 'FAQ'	知识类型
question	string	问题，必填，<= 50
answer	string	答案，必填，<= 800

KnowledgeImportResult

字段名	类型	说明
successCount	number	成功条数
failCount	number	失败条数
errorReportUrl	string	错误报告下载地址，失败数大于 0 时返回

KnowledgeBatchImportScene

'knowledge-base'：知识库导入
'business-knowledge'：业务知识导入

3.6.5 组件通信设计

AgentKnowledgeBasePanel.vue 通过 props 接收 agentId，不使用 provide/inject。

KnowledgeEditDialog.vue 通过 props 接收：

open
mode（create/edit）
initialData
agentId

KnowledgeEditDialog.vue 通过 emits 返回：

confirm(formData)
cancel()
update:open(boolean)

KnowledgeBatchImportDialog.vue 通过 props 接收：

open
agentId
scene
descriptionItems

KnowledgeBatchImportDialog.vue 通过 emits 返回：

success()（导入完成后通知主模块刷新列表）
cancel()
update:open(boolean)

主模块职责边界：

AgentKnowledgeBasePanel.vue 负责查询条件、列表数据、分页、操作入口和刷新。
两个弹窗组件各自闭环管理内部表单与步骤状态。
主模块不接管弹窗内部字段状态，只监听成功回调后刷新列表。
KnowledgeBatchImportDialog.vue 内部根据 scene 决定调用哪组导入相关接口。

3.6.6 后端接口能力需求

能力名称	使用场景	用途说明
查询知识列表	进入面板、筛选、分页、刷新	返回当前智能体知识列表
查询单条知识详情	打开编辑弹窗	获取单条知识详情用于回填
新增知识	添加知识确认	创建一条知识记录
更新知识	编辑知识确认	更新一条知识记录
删除知识	删除确认	删除单条知识
更新知识召回状态	切换召回开关	更新单条知识是否召回
同步知识到向量库	点击“同步到向量库”	将当前智能体知识同步到向量库
导出知识	点击“导出知识”确认	导出当前查询结果中 Q&A/FAQ 记录
下载导入模板	打开导入弹窗	下载标准 Excel 模板
批量导入知识	导入弹窗第二步确认	导入或按 id 更新 Q&A/FAQ 记录
下载导入错误报告	导入存在失败数据时	下载失败明细报告

接口约定：

查询知识列表 支持分页参数与查询参数：keyword / knowledgeType / recallEnabled。
新增/更新知识 根据 knowledgeType 接收不同 payload。
批量导入知识 仅接收 Q&A/FAQ 数据，不支持文档类型。
导出知识 返回文件流或下载地址均可，但需保证导出的数据包含 id。

3.6.7 期望返回数据格式

查询知识列表

{
  "list": [
    {
      "id": "kb001",
      "title": "合同管理流程指引",
      "knowledgeType": "DOCUMENT",
      "chunkStrategy": "TOKEN",
      "vectorizationStatus": "COMPLETED",
      "recallEnabled": true,
      "createdAt": "2026-04-01 12:22:36"
    }
  ],
  "total": 4,
  "pageNum": 1,
  "pageSize": 20
}

查询单条知识详情（编辑回填）

{
  "id": "kb002",
  "title": "合同常见问题一",
  "knowledgeType": "FAQ",
  "question": "今年总共有多少合同？",
  "answer": "今年共签订 128 份合同。"
}

批量导入结果

{
  "successCount": 500,
  "failCount": 1,
  "errorReportUrl": "/api/knowledge/import/error-report/20260401.xlsx"
}

变更类接口

{
  "success": true
}

3.7 业务知识

3.7.1 页面说明

业务知识用于维护智能体在特定业务域下的术语解释与同义表达，帮助模型识别用户问题中的业务名词并提升召回准确度。

模块能力包括：

列表查询、分页、按创建时间倒序展示
单条新增、编辑、删除
召回开关即时生效
同步业务知识到向量库
导出业务知识
Excel 批量导入业务知识

说明：

每条业务知识由 业务名词 + 同义词 + 描述 构成。
向量化状态 仅用于状态展示，不作为本版查询条件。
是否召回 是业务开关，切换即保存。
与 3.6 知识库 相比，业务知识没有“知识类型”和“分块策略”字段。

3.7.2 页面交互流程

A. 列表查询

进入面板后查询业务知识列表，默认按创建时间倒序，支持分页。
查询区包含：
- 快速查询：按业务名词搜索，支持清空
- 全部状态：按 召回/不召回 筛选，支持清空
切换查询条件后重新请求列表。

B. 列表区

表格列：序号 / 业务名词 / 同义词 / 描述 / 向量化状态 / 是否召回 / 创建时间 / 操作
同义词 直接展示逗号分隔后的文本结果。
描述 在列表中按文本展示，超长时按单元格省略/换行策略处理。
向量化状态 固定展示 待处理 / 处理中 / 已完成 / 失败，并以颜色区分。
是否召回 使用开关，切换后立即调用接口保存，并提示“召回成功 / 取消召回成功”。
编辑：打开“编辑业务知识”弹窗。
删除：二次确认“确认要删除该业务知识吗？”，确认后执行删除。

C. 添加/编辑业务知识

点击“添加知识”打开弹窗。
同一弹窗支持新增和编辑；编辑时回填当前记录。
弹窗字段：
- 业务名词：单行文本，必填
- 描述：多行文本，必填，<= 500
- 同义词：多行文本，必填，<= 100；多个同义词用英文逗号分隔
保存成功后关闭弹窗并刷新列表。

D. 批量导入

点击“导入知识”打开“批量导入”弹窗，两步流程与 3.6 完全一致：
1. 上传 Excel
2. 导入数据
上传阶段支持拖拽/点击上传，文件限制：
- 仅支持 xls/xlsx
- 大小 <= 10MB
弹窗内展示导入说明：
- 支持下载标准模板
- 默认导入新增数据；若 Excel 中带有导出数据里的 id，则按 id 更新
- 模板字段为：id（可选）/ 业务名词 / 同义词 / 描述
导入完成后展示结果：成功条数、失败条数；若存在失败数据，支持“下载错误报告”。

E. 同步到向量库

点击“同步到向量库”后，对当前智能体业务知识执行同步。
同步成功后刷新列表中向量化状态。

F. 导出知识

点击“导出知识”先提示：“确认导出当前列表的业务知识吗？”
确认后导出当前查询结果中的业务知识记录。
导出数据中包含 id，便于后续再次导入时更新。

3.7.3 前端组件拆分

组件名	主要职责
AgentBusinessKnowledgePanel.vue	业务知识主模块：查询区、列表、分页、召回开关、同步/导出操作、弹窗编排
BusinessKnowledgeEditDialog.vue	新增/编辑业务知识弹窗：字段校验、同义词输入规范、保存提交
KnowledgeBatchImportDialog.vue	通用批量导入弹窗：两步导入流程、模板下载、上传校验、导入结果与错误报告下载

拆分说明：

AgentBusinessKnowledgePanel.vue 承接列表型业务，与 3.6 的主模块职责一致。
BusinessKnowledgeEditDialog.vue 单独拆出是有必要的，因为它承载表单校验、编辑回填、同义词输入规则。
KnowledgeBatchImportDialog.vue 为 3.6 与 3.7 共用的通用导入弹窗，不再重复设计业务知识专属导入组件。
不再继续细拆列表行组件，当前复杂度不值得。

3.7.4 关键业务字段设计

VectorizationStatus

'PENDING'：待处理
'PROCESSING'：处理中
'COMPLETED'：已完成
'FAILED'：失败

BusinessKnowledgeItem

字段名	类型	说明
id	string	业务知识记录ID
term	string	业务名词
synonyms	string[]	同义词列表
description	string	描述
vectorizationStatus	VectorizationStatus	向量化状态
recallEnabled	boolean	是否召回
createdAt	string	创建时间

BusinessKnowledgeForm

字段名	类型	说明
term	string	业务名词，必填，<= 50
description	string	描述，必填，<= 500
synonymsText	string	同义词原始输入文本，必填，<= 100，多个同义词用英文逗号分隔

BusinessKnowledgeImportResult

字段名	类型	说明
successCount	number	成功条数
failCount	number	失败条数
errorReportUrl	string	错误报告下载地址，失败数大于 0 时返回

3.7.5 组件通信设计

AgentBusinessKnowledgePanel.vue 通过 props 接收 agentId，不使用 provide/inject。

BusinessKnowledgeEditDialog.vue 通过 props 接收：

open
mode（create/edit）
initialData
agentId

BusinessKnowledgeEditDialog.vue 通过 emits 返回：

confirm(formData)
cancel()
update:open(boolean)

KnowledgeBatchImportDialog.vue 通过 props 接收：

open
agentId
scene
descriptionItems

KnowledgeBatchImportDialog.vue 通过 emits 返回：

success()（导入完成后通知主模块刷新列表）
cancel()
update:open(boolean)

主模块职责边界：

AgentBusinessKnowledgePanel.vue 负责查询条件、列表数据、分页、操作入口和刷新。
两个弹窗组件各自闭环管理内部表单与步骤状态。
主模块不接管弹窗内部字段状态，只监听成功回调后刷新列表。
KnowledgeBatchImportDialog.vue 内部根据 scene 决定调用哪组导入相关接口。

3.7.6 后端接口能力需求

能力名称	使用场景	用途说明
查询业务知识列表	进入面板、筛选、分页、刷新	返回当前智能体业务知识列表
查询单条业务知识详情	打开编辑弹窗	获取单条业务知识详情用于回填
新增业务知识	添加业务知识确认	创建一条业务知识记录
更新业务知识	编辑业务知识确认	更新一条业务知识记录
删除业务知识	删除确认	删除单条业务知识
更新业务知识召回状态	切换召回开关	更新单条业务知识是否召回
同步业务知识到向量库	点击“同步到向量库”	将当前智能体业务知识同步到向量库
导出业务知识	点击“导出知识”确认	导出当前查询结果中的业务知识记录
下载导入模板	打开导入弹窗	下载标准 Excel 模板
批量导入业务知识	导入弹窗第二步确认	导入或按 id 更新业务知识记录
下载导入错误报告	导入存在失败数据时	下载失败明细报告

接口约定：

查询业务知识列表 支持分页参数与查询参数：keyword / recallEnabled。
新增/更新业务知识 的核心字段为 term / synonyms / description，其中 synonyms 建议后端按数组接收。
批量导入业务知识 的模板字段与导出字段保持一致，包含 id / 业务名词 / 同义词 / 描述。
导出业务知识 返回文件流或下载地址均可，但需保证导出的数据包含 id。

3.7.7 期望返回数据格式

查询业务知识列表

{
  "list": [
    {
      "id": "bk001",
      "term": "合同编号",
      "synonyms": ["合同编码", "合同号"],
      "description": "合同双方或一方为便于识别、管理、查询及分类归档等目的，依据特定规则和方法为该合同所赋予的唯一编号。",
      "vectorizationStatus": "COMPLETED",
      "recallEnabled": true,
      "createdAt": "2026-04-01 12:22:36"
    }
  ],
  "total": 4,
  "pageNum": 1,
  "pageSize": 20
}

查询单条业务知识详情（编辑回填）

{
  "id": "bk002",
  "term": "合同金额",
  "synonyms": ["合同总价", "合同价款", "合同额"],
  "description": "指在合同中明确约定的，双方当事人就某项交易或服务所涉及的货币总额。"
}

批量导入结果

{
  "successCount": 500,
  "failCount": 1,
  "errorReportUrl": "/api/business-knowledge/import/error-report/20260401.xlsx"
}

变更类接口

{
  "success": true
}

3.8 子智能体

3.8.1 页面说明

子智能体模块用于为当前智能体挂载和配置多个“系统内置子智能体”。每个子智能体卡片代表一个可选能力单元，例如应用搭建助手、智能填报助手、数据分析助手。

模块能力包括：

查询当前可配置的子智能体卡片列表
卡片级启用/禁用
打开子智能体详情抽屉
在抽屉内按页签分别维护子智能体配置：
- 开场白配置
- 数据源配置
- 语义模型配置
- 预设问题配置

说明：

卡片页只负责“选择和启停子智能体”，不承载复杂表单。
子智能体抽屉顶部基础信息（名称、标签、状态、类型、描述）为只读展示。
抽屉内各页签独立保存，不存在“整个抽屉统一保存”的提交动作。

3.8.2 页面交互流程

A. 卡片列表

进入面板后查询子智能体卡片列表。
卡片展示：图标、名称、标签、类型、描述、维护人、更新时间、启用开关。
切换卡片开关时，立即调用“更新子智能体启用状态”接口。
点击卡片主体时，打开对应子智能体详情抽屉；无论当前启用或禁用，都允许查看配置。

B. 子智能体详情抽屉

打开抽屉后，先查询子智能体基础信息，用于回填顶部只读字段。
抽屉顶部展示：
- 智能体名称
- 标签
- 状态
- 类型
- 描述
下方按页签切换配置：
- 开场白配置
- 数据源配置
- 语义模型配置
- 预设问题配置
切换页签时，仅查询当前页签数据，不预加载其他页签。
关闭抽屉不做未保存拦截；页签内局部草稿关闭即丢弃。

C. 开场白配置

进入页签后查询当前子智能体开场白。
文本区域支持输入开场白内容，字数限制 <= 500。
点击保存后调用“保存子智能体开场白配置”接口。

D. 数据源配置

进入页签后查询已绑定数据源列表。
列表列：序号 / 数据源名称 / 数据源类型 / 连接地址 / 连接状态 / 状态 / 创建时间 / 操作
操作包括：
- 测试连接
- 选择数据表
- 配置表关系
- 移除
顶部按钮：
- + 添加数据源
- 同步到向量库
“添加数据源”弹窗包含两个子页签：
- 选择已有数据源
- 添加新数据源
选择已有数据源：
- 以表格列出系统已有数据源
- 单选后点击“添加选中数据源”完成绑定
- 支持在弹窗内对已有数据源做编辑/删除
添加新数据源：
- 表单字段：数据源名称、数据源类型、主机地址、端口号、数据库名、JDBC 地址、用户名、密码、描述
- 提交后创建并绑定到当前子智能体
测试连接 单条执行，结果更新连接状态。
选择数据表 打开选择数据表弹窗，维护该数据源在当前子智能体下可用的数据表。
配置表关系 打开表关系配置弹窗，维护跨表关联关系。
状态 开关表示该数据源绑定是否启用，切换即保存。
同步到向量库 对当前子智能体下的数据源配置执行同步。

E. 语义模型配置

进入页签后查询语义模型列表。
列表列：序号 / 表名 / 数据库字段名 / 业务名称 / 同义词 / 数据类型 / 状态 / 创建时间 / 操作
顶部按钮：
- + 添加语义模型
- 批量导入
- 同步到向量库
“添加语义模型”弹窗字段：
- 表名
- 数据库字段名
- 业务名称
- 同义词
- 业务描述
- 字段注释
- 数据类型
列表支持单条 编辑 / 删除 / 状态开关。
批量导入弹窗支持两种模式：
- JSON 导入
- Excel 导入
JSON 导入：
- 输入 JSON 内容
- 支持“加载模板”“验证 JSON”
Excel 导入：
- 文件上传
- 支持下载标准模板
两种导入模式都走两步流程：录入/上传 -> 导入结果。
导入完成后展示成功/失败统计；存在失败时支持下载错误报告。
同步到向量库 对当前子智能体语义模型配置执行同步。

F. 预设问题配置

进入页签后复用 PresetQuestionManager.vue 查询当前子智能体预设问题列表。
组件传参为：
- scene='sub-agent'
- showAutoRecommend=false
- agentId
- subAgentId
支持：
- 问题搜索
- 角色筛选
- 状态筛选
- 单条新增
- 编辑
- 删除
- 状态开关即时保存
不展示“自动推荐问题”开关。

3.8.3 前端组件拆分

组件名	主要职责
AgentSubAgentPanel.vue	子智能体主模块：卡片列表、启用开关、抽屉开关、当前选中子智能体管理
SubAgentConfigDrawer.vue	子智能体详情抽屉：顶部只读信息、页签切换、各页签子模块装配
SubAgentDataSourceManager.vue	数据源配置子模块：列表、测试连接、选择数据表、配置表关系、添加数据源弹窗编排
SubAgentDataSourceDialog.vue	添加数据源弹窗：选择已有数据源 / 添加新数据源两种模式
SubAgentSemanticModelManager.vue	语义模型配置子模块：列表、单条增删改、状态切换、同步、批量导入编排
SemanticModelEditDialog.vue	语义模型新增/编辑弹窗
SemanticModelBatchImportDialog.vue	语义模型批量导入弹窗：JSON/Excel 双模式、两步导入流程
PresetQuestionManager.vue	预设问题通用子模块：在 `sub-agent` 场景下复用，不新增子智能体专属预设问题组件

拆分原则：

AgentSubAgentPanel.vue 和 SubAgentConfigDrawer.vue 必须拆开：一个负责卡片层，一个负责抽屉层。
开场白配置 业务较轻，直接内聚在 SubAgentConfigDrawer.vue 内，不单独拆组件。
数据源配置 和 语义模型配置 复杂度都明显高于普通表单，必须独立成 manager 组件。
预设问题配置 复用 PresetQuestionManager.vue，通过 scene 和 showAutoRecommend 控制场景差异。
选择数据表 和 配置表关系 当前原型未给出内部交互细节，本次先作为 SubAgentDataSourceManager.vue 内部弹层能力描述，不继续拆命名独立组件。

3.8.4 关键业务字段设计

SubAgentCardItem

字段名	类型	说明
id	string	子智能体记录ID
subAgentName	string	子智能体名称
tagName	string	标签名称
agentTypeText	string	类型展示文案，如“系统内置”
description	string	描述
maintainerName	string	维护人
updatedAt	string	更新时间
enabled	boolean	是否启用

SubAgentDetail

字段名	类型	说明
id	string	子智能体记录ID
subAgentName	string	子智能体名称
tagName	string	标签
statusText	string	状态展示文案
agentTypeText	string	类型展示文案
description	string	描述

SubAgentDataSourceItem

字段名	类型	说明
id	string	子智能体数据源绑定ID
dataSourceName	string	数据源名称
dataSourceType	string	数据源类型
jdbcUrl	string	连接地址
connectionStatus	'SUCCESS' \| 'FAILED'	连接状态
enabled	boolean	状态开关
createdAt	string	创建时间

ExistingDataSourceItem

字段名	类型	说明
id	string	系统数据源ID
dataSourceName	string	数据源名称
dataSourceType	string	数据库类型
host	string	主机地址
port	string	端口号
databaseName	string	数据库名
description	string	描述

CreateDataSourceForm

字段名	类型	说明
dataSourceName	string	数据源名称，必填
dataSourceType	string	数据源类型，必填
host	string	主机地址，必填
port	string	端口号，必填
databaseName	string	数据库名，必填
jdbcUrl	string	JDBC 地址，选填；不填则自动生成
username	string	用户名，必填
password	string	密码，必填
description	string	描述，选填

SemanticModelItem

字段名	类型	说明
id	string	语义模型记录ID
tableName	string	表名
columnName	string	数据库字段名
businessName	string	业务名称
synonyms	string[]	同义词列表
dataType	string	数据类型
enabled	boolean	状态开关
createdAt	string	创建时间

SemanticModelForm

字段名	类型	说明
tableName	string	表名，必填
columnName	string	数据库字段名，必填
businessName	string	业务名称，必填
synonymsText	string	同义词输入文本，多个同义词用英文逗号分隔
businessDesc	string	业务描述，选填
fieldComment	string	字段注释，选填
dataType	string	数据类型，必填

SubAgentPresetQuestionItem

字段名	类型	说明
id	string	预设问题记录ID
question	string	问题内容
roleId	string	角色ID
roleName	string	角色名称
priority	number	优先级
status	'ENABLED' \| 'DISABLED'	状态
creatorName	string	创建人
createdAt	string	创建时间
updaterName	string	最后修改人
updatedAt	string	最后修改时间

3.8.5 组件通信设计

AgentSubAgentPanel.vue 通过 props 接收 agentId，不使用 provide/inject。

AgentSubAgentPanel.vue 负责：

查询卡片列表
切换子智能体启用状态
打开/关闭详情抽屉
传递当前选中 subAgentId 给抽屉组件

SubAgentConfigDrawer.vue 通过 props 接收：

open
agentId
subAgentId

SubAgentConfigDrawer.vue 内部管理：

子智能体详情只读数据
当前页签
开场白查询与保存
各页签子模块装配

SubAgentDataSourceManager.vue、SubAgentSemanticModelManager.vue 都通过 props 接收：

agentId
subAgentId

PresetQuestionManager.vue 在 3.8 中通过 props 接收：

agentId
subAgentId
scene='sub-agent'
showAutoRecommend=false

各 manager 组件内部自管列表、筛选、弹窗状态和单条增删改操作，父抽屉不接管子模块内部 CRUD。

SubAgentDataSourceDialog.vue、SemanticModelEditDialog.vue、SemanticModelBatchImportDialog.vue 都采用 props/emits 方式，与各自 manager 通信。

3.8.6 后端接口能力需求

能力名称	使用场景	用途说明
查询子智能体卡片列表	进入面板、刷新	获取当前智能体下可配置的子智能体卡片列表
更新子智能体启用状态	切换卡片开关	更新某个子智能体是否启用
查询子智能体详情	打开详情抽屉	获取抽屉顶部只读基础信息
查询子智能体开场白配置	进入开场白页签	获取当前开场白内容
保存子智能体开场白配置	点击保存	保存开场白内容
查询子智能体数据源列表	进入数据源配置页签	获取已绑定数据源列表
查询已有数据源列表	打开“选择已有数据源”	获取系统已有数据源列表
新增并绑定数据源	添加新数据源确认	创建数据源并绑定到当前子智能体
绑定已有数据源	选择已有数据源确认	将系统已有数据源绑定到当前子智能体
更新子智能体数据源状态	切换数据源状态开关	启用/禁用单条数据源绑定
测试数据源连接	点击测试连接	测试当前数据源连接状态
查询数据表列表	点击选择数据表	获取当前数据源可用的数据表列表
保存数据表选择结果	选择数据表确认	保存当前子智能体下可用数据表
查询表关系配置	打开配置表关系	获取表关系配置详情
保存表关系配置	配置表关系确认	保存表关系
移除子智能体数据源	点击移除	删除数据源绑定
同步子智能体数据源到向量库	点击同步到向量库	同步数据源配置到向量库
查询语义模型列表	进入语义模型配置页签	获取语义模型列表
新增语义模型	添加语义模型确认	创建语义模型记录
更新语义模型	编辑语义模型确认	更新语义模型记录
更新语义模型状态	切换状态开关	启用/禁用单条语义模型
删除语义模型	点击删除	删除单条语义模型
批量导入语义模型	批量导入确认	支持 JSON/Excel 两种导入方式
下载语义模型 Excel 模板	Excel 导入模式	下载标准模板
下载语义模型错误报告	批量导入存在失败时	下载失败报告
同步语义模型到向量库	点击同步到向量库	同步语义模型配置到向量库
查询子智能体预设问题列表	进入预设问题页签	获取预设问题列表
查询角色选项	打开预设问题弹窗/角色筛选	获取角色选项
新增子智能体预设问题	添加问题确认	创建一条预设问题
更新子智能体预设问题	编辑问题确认	更新预设问题
更新子智能体预设问题状态	切换状态开关	启用/禁用单条预设问题
删除子智能体预设问题	点击删除	删除单条预设问题

接口约定：

所有抽屉内配置接口都必须带 agentId + subAgentId 作为作用域。
语义模型批量导入支持 JSON 和 Excel 两种模式，返回统一导入结果结构。
数据源“选择已有 / 新增并绑定”是两套接口，不建议混为一个接口。
测试连接、同步到向量库 都是即时操作，不参与统一保存。

3.8.7 期望返回数据格式

查询子智能体卡片列表

[
  {
    "id": "sa001",
    "subAgentName": "数据分析助手",
    "tagName": "数据分析大师",
    "agentTypeText": "系统内置",
    "description": "专门处理数据分析的智能体。",
    "maintainerName": "admin",
    "updatedAt": "2025-01-01 00:17:59",
    "enabled": false
  }
]

查询子智能体详情

{
  "id": "sa001",
  "subAgentName": "数据分析助手",
  "tagName": "数据分析大师",
  "statusText": "禁用",
  "agentTypeText": "系统内置",
  "description": "专门处理数据分析的智能体。"
}

查询子智能体数据源列表

[
  {
    "id": "dsb001",
    "dataSourceName": "管理信息化数据库",
    "dataSourceType": "mysql",
    "jdbcUrl": "jdbc:mysql://192.10.51.139:3306/...",
    "connectionStatus": "SUCCESS",
    "enabled": true,
    "createdAt": "2026-04-01 12:22:36"
  }
]

查询语义模型列表

[
  {
    "id": "sm001",
    "tableName": "mt20008864999710",
    "columnName": "fieldTextInput27848",
    "businessName": "合同编号",
    "synonyms": ["合同号", "合同编码"],
    "dataType": "varchar(50)",
    "enabled": true,
    "createdAt": "2026-04-01 12:22:36"
  }
]

查询子智能体预设问题列表

[
  {
    "id": "spq001",
    "question": "今年的合同总额有多少？",
    "roleId": "role001",
    "roleName": "班子成员,副总工程师",
    "priority": 1,
    "status": "ENABLED",
    "creatorName": "合同管理员",
    "createdAt": "2026-04-01 13:52:15",
    "updaterName": "合同管理员",
    "updatedAt": "2026-04-01 13:52:15"
  }
]

批量导入结果

{
  "successCount": 500,
  "failCount": 1,
  "errorReportUrl": "/api/sub-agent/semantic-model/import/error-report/20260401.xlsx"
}

变更类接口

{
  "success": true
}

3.9 技能

3.9.1 页面说明

技能模块用于为当前智能体挂载可执行技能，例如生成 PPT、生成论文等。每个技能代表一个可被智能体调用的独立能力单元。

模块能力包括：

查询当前智能体已挂载技能列表
按技能名称搜索、按启用状态筛选
卡片级启用/禁用
从技能市场添加技能
上传自定义技能并挂载到当前智能体

说明：

主页面只展示“当前已挂载技能”，不展示全量市场技能。
技能市场和上传技能都在“添加技能”弹窗内完成。
技能卡片当前只支持启停，不在本模块提供编辑和删除能力。
上传技能文件格式固定为压缩包，且压缩包内必须包含 SKILL.md 文件。

3.9.2 页面交互流程

A. 技能列表

进入面板后查询当前智能体已挂载技能列表。
页面上方提供：
- + 添加技能
- 按技能名称搜索
- 按状态筛选（全部状态 / 启用 / 禁用）
切换搜索词或状态筛选后重新请求列表。
列表区域以技能卡片形式展示：
- 技能图标
- 技能名称
- 技能描述
- 启用开关
切换卡片开关后，立即调用“更新技能启用状态”接口。

B. 添加技能弹窗

点击“添加技能”打开弹窗。
弹窗分为两个区域：
1. 左上固定入口：上传技能
2. 下方主体区域：技能市场
技能市场支持：
- 按关键字搜索
- 分页查询
- 卡片形式展示技能名称、图标、描述
未添加的市场技能，hover/选中后显示 添加 按钮。
点击 添加 后，立即调用“挂载市场技能到当前智能体”接口；成功后关闭弹窗或刷新市场卡片状态，并同步刷新主页面技能列表。

C. 上传技能

点击弹窗内的“上传技能”入口后，打开“上传技能”表单弹窗。
表单字段：
- 技能名称
- 技能描述
- 上传技能文件
上传文件区支持拖拽或点击上传。
文件校验：
- 仅支持 .zip
- 压缩包内必须包含 SKILL.md
点击确认后：
1. 上传技能包
2. 创建技能记录
3. 自动挂载到当前智能体
成功后关闭上传弹窗，并刷新主页面技能列表。

D. 技能市场分页

技能市场弹窗底部支持分页。
翻页时仅刷新市场数据，不影响已挂载技能列表。
已挂载的技能在市场卡片中应显示“已添加”或禁用 添加 按钮，避免重复挂载。

3.9.3 前端组件拆分

组件名	主要职责
AgentSkillPanel.vue	技能主模块：已挂载技能列表、搜索筛选、启用开关、添加技能入口
SkillSelectDialog.vue	添加技能弹窗：技能市场列表、市场搜索分页、上传技能入口、市场技能挂载
SkillUploadDialog.vue	上传技能弹窗：技能名称/描述/文件上传、压缩包校验、创建并挂载技能

拆分原则：

AgentSkillPanel.vue 承接主页面列表型业务，不应把市场逻辑塞入页面层。
SkillSelectDialog.vue 需要独立，因为它同时管理市场技能搜索、分页和添加行为。
SkillUploadDialog.vue 需要独立，因为它承载文件上传和压缩包校验逻辑，和技能市场是两套交互。
不再继续拆技能卡片组件，当前复杂度不值得。

3.9.4 关键业务字段设计

SkillStatus

'ENABLED'：启用
'DISABLED'：禁用

AgentSkillItem

字段名	类型	说明
id	string	智能体技能挂载记录ID
skillId	string	技能主记录ID
skillName	string	技能名称
skillDesc	string	技能描述
iconUrl	string	技能图标地址
status	SkillStatus	启用状态

SkillMarketItem

字段名	类型	说明
skillId	string	技能主记录ID
skillName	string	技能名称
skillDesc	string	技能描述
iconUrl	string	技能图标地址
alreadyAdded	boolean	是否已挂载到当前智能体

SkillUploadForm

字段名	类型	说明
skillName	string	技能名称，必填，<= 50
skillDesc	string	技能描述，必填，<= 500
skillFile	File	技能压缩包，必填，`.zip` 且内含 `SKILL.md`

3.9.5 组件通信设计

AgentSkillPanel.vue 通过 props 接收 agentId，不使用 provide/inject。
AgentSkillPanel.vue 负责：
- 查询已挂载技能列表
- 管理搜索词与状态筛选
- 切换技能启用状态
- 打开/关闭 SkillSelectDialog.vue
SkillSelectDialog.vue 通过 props 接收：
- open
- agentId
SkillSelectDialog.vue 通过 emits 返回：
- success()（技能添加成功后通知宿主刷新列表）
- cancel()
- update:open(boolean)
SkillSelectDialog.vue 内部管理：
- 市场技能搜索与分页
- 市场技能卡片添加
- 打开/关闭 SkillUploadDialog.vue
SkillUploadDialog.vue 通过 props 接收：
- open
- agentId
SkillUploadDialog.vue 通过 emits 返回：
- success()（上传并挂载成功后通知父弹窗/页面刷新）
- cancel()
- update:open(boolean)

3.9.6 后端接口能力需求

能力名称	使用场景	用途说明
查询智能体技能列表	进入面板、搜索、筛选、刷新	获取当前智能体已挂载技能列表
更新技能启用状态	切换技能卡片开关	启用/禁用单条技能挂载
查询技能市场列表	打开添加技能弹窗、搜索、分页	获取可供添加的市场技能列表
挂载市场技能到智能体	点击市场技能“添加”	将市场技能挂载到当前智能体
上传技能包	上传技能文件	上传 zip 技能包并校验文件结构
创建并挂载自定义技能	上传技能确认	创建技能记录并挂载到当前智能体

接口约定：

查询智能体技能列表 支持查询参数：keyword / status。
查询技能市场列表 支持查询参数：keyword / pageNum / pageSize。
上传技能包 或 创建并挂载自定义技能 需要校验压缩包中存在 SKILL.md。
技能市场技能和自定义上传技能最终都以“挂载记录”形式进入当前智能体技能列表。

3.9.7 期望返回数据格式

查询智能体技能列表

{
  "list": [
    {
      "id": "ask001",
      "skillId": "skill001",
      "skillName": "生成PPT",
      "skillDesc": "PowerPoint 演示文稿创建、编辑和分析技能。",
      "iconUrl": "/assets/skills/ppt.png",
      "status": "ENABLED"
    }
  ],
  "total": 2
}

查询技能市场列表

{
  "list": [
    {
      "skillId": "skill001",
      "skillName": "生成PPT",
      "skillDesc": "PowerPoint 演示文稿创建、编辑和分析技能。",
      "iconUrl": "/assets/skills/ppt.png",
      "alreadyAdded": false
    }
  ],
  "total": 50,
  "pageNum": 1,
  "pageSize": 12
}

上传或创建结果

{
  "success": true
}

3.10 权限

3.10.1 页面说明

权限模块用于配置“哪些成员可以访问当前智能体”。
页面不区分“可见/可用”等多种权限语义，本期仅维护一组授权对象。
页面主体由两部分组成：
- 当前已授权对象展示区
- 选择成员入口
当未选择任何对象时，展示空态选择框；当已有选择结果时，展示已选名称列表，并支持继续打开弹框调整。
页面初始化时直接读取智能体配置中的权限范围字段进行渲染，不单独查询权限详情。

3.10.2 页面交互流程

A. 页面初始化

进入智能体配置页时，读取当前智能体配置中的权限范围字段。
权限面板直接消费该字段，渲染当前已授权列表。
若配置中无权限范围数据，则按空态展示。

B. 选择成员

点击空态选择框或已选区域，打开选人弹框。
选人弹框直接复用当前项目 userpicker 组件。
弹框内 tab 按原型图开放，支持用户、组织架构、群组、角色、快速查询等原型中已有维度。
弹框确认后，将返回的已选结果同步更新到页面当前编辑态。
弹框取消时，不修改页面当前已选结果。

C. 页面内展示与编辑

已选区按 userpicker 既有展示方式回显，仅展示名称。
页面支持删除单个已选对象。
删除操作仅更新当前页面编辑态，不立即调用后端。
当全部删除后，页面恢复为空态选择框。

D. 保存

点击页面级“保存”按钮时，统一提交当前权限配置。
保存成功后提示“保存成功”。
保存失败时保留当前编辑态，允许继续修改后重试。

3.10.3 前端组件拆分

组件名	主要职责
`AgentPermissionPanel.vue`	权限主面板：读取智能体配置中的权限范围、渲染已选区、删除成员、打开选人弹框、输出保存数据
`userpicker` 弹框（复用）	负责授权对象选择，不在本模块重复封装和介绍内部能力

拆分约束：

不新增独立的“权限选人弹框”组件。
不在设计文档中展开介绍 userpicker 内部实现。
权限页只描述本页面如何调用弹框、如何消费返回结果。

3.10.4 关键业务字段设计

AgentPermissionConfig

字段名	类型	说明
`selectedList`	`PermissionSelectedItem[]`	当前已授权对象列表

PermissionSelectedItem

字段名	类型	说明
`id`	string	对象唯一标识
`name`	string	展示名称
`type`	string	对象类型
`parentId`	string[]	层级型对象的父级路径，可选
`isShowClose`	boolean	前端展示时是否允许删除，可选

说明：

字段结构尽量与现有 userpicker 返回结果保持一致。
页面展示时只使用 name。
保存时提交完整授权对象集合，不仅限用户。

3.10.5 组件通信设计

智能体配置页宿主通过 props 传入：
- agentId
- agentConfig
AgentPermissionPanel.vue 负责：
- 从 agentConfig 中提取权限范围
- 维护本地编辑态 selectedList
- 打开/关闭 userpicker 弹框
- 在页面保存时输出最新权限数据
userpicker 弹框输入：
- 当前已选结果
- 原型要求的 tab 配置
- 多选模式
userpicker 弹框输出：
- 用户确认后的完整已选结果列表
页面侧拿到结果后：
- 覆盖当前 selectedList
- 基于现有唯一标识去重
- 重新渲染已选区

3.10.6 后端接口能力需求

能力名称	使用场景	用途说明
查询智能体配置	进入配置页时	返回智能体配置内容，其中包含权限范围字段
保存智能体配置	点击保存	保存当前权限配置及其他配置内容

接口约定：

权限配置作为智能体配置的一部分返回，不再为权限页单独设计查询接口。
保存时沿用智能体配置保存接口，权限字段作为整体配置的一部分提交。
返回和保存结构尽量贴近现有 userpicker 结果结构，减少前端转换成本。

3.10.7 期望返回数据格式

查询智能体配置中的权限片段

{
  "agentId": "agent001",
  "config": {
    "permissionConfig": {
      "selectedList": [
        {
          "id": "u001",
          "name": "二级资产管理员",
          "type": "user"
        },
        {
          "id": "role001",
          "name": "经办人",
          "type": "role"
        }
      ]
    }
  }
}

保存智能体配置中的权限片段

{
  "agentId": "agent001",
  "config": {
    "permissionConfig": {
      "selectedList": [
        {
          "id": "u001",
          "name": "二级资产管理员",
          "type": "user"
        },
        {
          "id": "role001",
          "name": "经办人",
          "type": "role"
        }
      ]
    }
  }
}

3.11 访问API

3.11.1 页面说明

访问API模块用于配置当前智能体对外访问能力的 API Key。
页面不依赖智能体配置中的 accessApiConfig.list，而是通过独立接口查询和维护 API Key 列表。
页面主体由两部分组成：
- 顶部工具区：新增、只看启用、关键字搜索
- 下方列表区：展示 API Key 记录及操作
列表字段按原型展示：
- API Key 名称
- API Key
- 授权范围
- IP 白名单
- 状态
- 创建时间
- 操作
页面核心目标是让超管完成 API Key 的创建、查看、复制和状态管理。

3.11.2 页面交互流程

A. 页面初始化

进入“访问API”面板时，调用“查询访问API列表”接口。
页面默认展示当前智能体下全部 API Key 记录。
列表数据不从智能体配置对象中读取。

B. 工具区筛选

点击 只看启用 后，仅展示状态为启用的 API Key。
在搜索框输入关键字后，按 API Key 名称或 IP 白名单关键字进行搜索。
搜索与“只看启用”条件可叠加。
切换筛选条件后重新请求列表。

C. 新增 API Key

点击 新增 打开新增弹窗。
弹窗字段包括：
- API Key名称：必填，用户输入
- API Key：只读，保存后自动生成
- 授权范围：单选，全部智能体 / 部分智能体
- 部分智能体下拉框：当授权范围为 部分智能体 时显示，支持从全部智能体中多选部分智能体
- IP白名单：可添加多条 IP
API Key 不允许用户手工输入，创建成功后由后端生成。
点击确定后校验必填项，通过后调用“新增 API Key”接口。
成功后关闭弹窗并刷新列表。

D. 列表操作

复制：复制当前 API Key 明文值到剪贴板，并提示“复制成功”。
删除：二次确认后删除当前 API Key，成功后刷新列表。
状态开关：切换启用/停用状态，成功后更新列表状态；失败时回滚开关。
IP 白名单列只展示 已设置 / 未设置，不在列表页展示完整 IP 明细。

E. 空态与分页

当列表为空时展示空态。
列表底部支持分页。
搜索、筛选、新增、删除、启停后保持分页逻辑一致；若删除导致当前页无数据，则回退到上一有效页。

3.11.3 前端组件拆分

组件名	主要职责
`AgentAccessApiPanel.vue`	访问API主面板：列表查询、筛选、搜索、状态切换、复制、删除、打开新增弹窗
`AccessApiCreateDialog.vue`	新增 API Key 弹窗：名称录入、授权范围选择、部分智能体下拉选择、IP 白名单录入、提交创建

拆分原则：

列表页和新增弹窗拆开，避免把表单逻辑塞入主面板。
行内操作较轻，不额外拆表格行组件。
“部分智能体”直接使用弹窗内下拉框，不设计额外组件。

3.11.4 关键业务字段设计

AccessApiItem

字段名	类型	说明
`id`	string	API Key 记录 ID
`name`	string	API Key 名称
`apiKeyMasked`	string	脱敏后的 API Key，用于列表展示
`apiKey`	string	API Key 明文，仅复制或创建成功时返回
`scopeType`	`'ALL' \| 'PARTIAL'`	授权范围类型
`scopeLabel`	string	授权范围展示文案，如“全部智能体”“部分智能体”
`scopeAgentIds`	string[]	当为部分智能体时选中的智能体 ID 列表
`ipWhitelist`	string[]	IP 白名单列表
`ipWhitelistStatus`	`'SET' \| 'UNSET'`	IP 白名单是否已设置
`enabled`	boolean	是否启用
`createTime`	string	创建时间

AccessApiCreateForm

字段名	类型	说明
`name`	string	API Key 名称，必填，建议 <= 50
`scopeType`	`'ALL' \| 'PARTIAL'`	授权范围，必填
`scopeAgentIds`	string[]	授权范围为部分智能体时必填
`ipWhitelist`	string[]	IP 白名单，可为空

AgentOption

字段名	类型	说明
`label`	string	智能体名称
`value`	string	智能体 ID

AccessApiQueryParams

字段名	类型	说明
`keyword`	string	名称/IP 白名单关键字
`enabledOnly`	boolean	是否仅看启用
`pageNum`	number	页码
`pageSize`	number	每页条数

字段约定：

列表默认只展示 apiKeyMasked。
apiKey 明文只在“创建成功返回”或“复制接口返回”时使用。
scopeLabel 可由后端返回，也可由前端根据 scopeType 映射。

3.11.5 组件通信设计

智能体配置页宿主通过 props 传入：
- agentId
AgentAccessApiPanel.vue 负责：
- 管理筛选条件 keyword / enabledOnly / pageNum / pageSize
- 查询列表
- 打开/关闭 AccessApiCreateDialog.vue
- 处理复制、删除、启停
AccessApiCreateDialog.vue 通过 props 接收：
- open
- agentId
AccessApiCreateDialog.vue 通过 emits 返回：
- success()：新增成功后通知父组件刷新列表
- cancel()
- update:open(boolean)
弹窗内部自行维护：
- 授权范围单选值
- “部分智能体”下拉框值
- IP 白名单输入值

3.11.6 后端接口能力需求

能力名称	使用场景	用途说明
查询访问API列表	进入面板、筛选、搜索、翻页	获取当前智能体下的 API Key 列表
新增 API Key	点击新增弹窗确认	创建新 API Key 并生成明文密钥
复制 API Key / 获取明文	点击复制	返回当前记录对应的明文 API Key
更新 API Key 启用状态	切换状态开关	启用或停用单条 API Key
删除 API Key	点击删除	删除单条 API Key
查询全部智能体下拉选项	新增弹窗中选择“部分智能体”时	获取可选智能体列表

接口约定：

访问API列表必须独立维护，不依赖 accessApiConfig。
新增 API Key 成功后建议返回一次明文 apiKey。
列表查询接口默认只返回脱敏 Key，不返回明文。
“查询全部智能体下拉选项”返回适用于下拉框的简单选项结构。
删除、启停接口均按单条记录操作。

3.11.7 期望返回数据格式

查询访问API列表

{
  "list": [
    {
      "id": "key001",
      "name": "提供给合同管理系统数据分析智能体",
      "apiKeyMasked": "****************************abcd",
      "scopeType": "PARTIAL",
      "scopeLabel": "部分智能体",
      "scopeAgentIds": ["agent001", "agent002"],
      "ipWhitelist": ["10.10.1.1", "10.10.1.2"],
      "ipWhitelistStatus": "SET",
      "enabled": true,
      "createTime": "2026-04-07 12:46:23"
    },
    {
      "id": "key002",
      "name": "提供给项目管理系统数据分析智能体",
      "apiKeyMasked": "****************************wxyz",
      "scopeType": "ALL",
      "scopeLabel": "全部智能体",
      "scopeAgentIds": [],
      "ipWhitelist": [],
      "ipWhitelistStatus": "UNSET",
      "enabled": false,
      "createTime": "2026-04-03 12:46:23"
    }
  ],
  "total": 4,
  "pageNum": 1,
  "pageSize": 10
}

查询全部智能体下拉选项

[
  {
    "label": "合同管理小新",
    "value": "agent001"
  },
  {
    "label": "经营管理分析助手",
    "value": "agent002"
  }
]

新增 API Key

{
  "id": "key003",
  "name": "提供给经营管理系统数据分析智能体",
  "apiKey": "sk-agent-xxxxxxxxxxxxxxxx",
  "apiKeyMasked": "************************xxxx",
  "scopeType": "PARTIAL",
  "scopeLabel": "部分智能体",
  "scopeAgentIds": ["agent001", "agent003"],
  "ipWhitelist": ["172.16.10.1"],
  "ipWhitelistStatus": "SET",
  "enabled": true,
  "createTime": "2026-04-16 10:00:00"
}

复制 API Key / 获取明文

{
  "id": "key001",
  "apiKey": "sk-agent-xxxxxxxxxxxxxxxx"
}

更新状态 / 删除结果

{
  "success": true
}

3.12 自动化

3.12.1 页面说明

自动化面板用于为当前智能体配置“定时触发的自动化任务”，使智能体按预设时间和频率主动执行提示词并通过已接入渠道发送提醒消息。
页面按原型分为两部分能力：
- 自动化任务管理：任务列表查询、筛选、启停、编辑、删除、新增
- 推送渠道维护：查看当前可用推送渠道、完成渠道接入配置
自动化任务列表字段按原型展示：
- 任务名称
- 最近更新时间
- 任务描述
- 操作：编辑、删除、启停
页面工具区按原型提供：
- + 添加自动化任务
- 推送渠道
- 关键词搜索
- 类型筛选
- 状态筛选
- 刷新
新增/编辑任务弹窗字段按原型设计：
- 任务名称：必填
- 任务描述：选填
- 提示词：必填，表示 AI 应执行的内容
- 开始时间：必填
- 执行频率：必填，固定枚举
- 提醒方式：必填，开关控制
- 提醒渠道：当提醒方式开启时必选，支持多选
推送渠道维护按本期范围设计为：
- 前端保留 企业微信 / 钉钉 / 飞书 三种提醒渠道
- 本期仅支持 企业微信 完整接入与保存
- 钉钉 / 飞书 仅作为任务配置中的预留渠道枚举，不在“推送渠道维护”内提供接入表单

3.12.2 页面交互流程

A. 页面初始化

进入“自动化”面板时，调用“查询自动化任务列表”接口。
页面默认展示当前智能体下全部自动化任务。
若智能体详情接口未返回渠道接入摘要，则额外调用“查询推送渠道配置列表”接口，用于控制渠道可选状态和“推送渠道”弹窗展示。

B. 工具区筛选

关键词按 任务名称 模糊搜索。
类型筛选用于筛选 执行频率类型，建议枚举：
- ALL：全部类型
- ONCE：仅执行一次
- DAILY：每天
- WEEKLY：每周
- MONTHLY：每月
状态筛选用于筛选任务启用状态，建议枚举：
- ALL：全部状态
- ENABLED：启用
- DISABLED：停用
点击刷新时，按当前筛选条件重新请求列表。

C. 新增自动化任务

点击 + 添加自动化任务 打开任务弹窗。
弹窗标题为 添加自动化任务。
字段交互规则：
- 任务名称：必填，建议长度 1~50
- 任务描述：选填，建议长度 0~500
- 提示词：必填，建议长度 1~20000
- 开始时间：必填，精确到分钟
- 执行频率：必填，使用固定枚举下拉
- 提醒方式：默认开启
- 提醒渠道：当提醒方式开启时至少选择一项；仅允许选择“已完成接入”的渠道；未接入渠道置灰但仍展示
点击确定后：
- 前端先做表单校验
- 通过后调用“新增自动化任务”接口
- 成功后关闭弹窗并刷新列表
- 失败后保留用户输入并提示错误

D. 编辑自动化任务

点击列表项“编辑”打开同一弹窗，标题改为 编辑自动化任务。
弹窗回填当前任务配置。
编辑保存时调用“更新自动化任务”接口。
成功后关闭弹窗并刷新列表。

E. 删除自动化任务

点击“删除”后二次确认。
确认后调用“删除自动化任务”接口。
成功后刷新列表。
若删除导致当前页无数据，则回退到上一有效页；若本期列表不分页，则直接刷新当前列表。

F. 启用/停用自动化任务

列表右侧开关表示任务启用状态。
切换开关时调用“更新自动化任务状态”接口。
允许乐观更新；若失败则回滚开关并提示错误。
关闭任务仅表示暂停调度，不删除任务配置。

G. 推送渠道维护

点击 推送渠道 打开“维护自动化推送渠道”弹窗。
弹窗内展示渠道卡片列表，本期仅企业微信可配置：
- 企业微信：显示接入状态 未接入 / 已接入
点击企业微信卡片，打开“接入企业微信”弹窗。
企业微信接入字段：
- 企业ID：必填
- AgentId：必填
- Secret：必填
点击确定后调用“保存企业微信渠道配置”接口：
- 成功后关闭接入弹窗，刷新渠道状态
- 失败后保留输入并提示错误
已接入状态下再次进入可视为“编辑企业微信配置”；是否回显 Secret 由后端决定，前端默认不强依赖明文回填

H. 空态与可用性约束

当任务列表为空时展示空态。
当未接入任何渠道时：
- 仍允许创建任务
- 若“提醒方式”开启，则渠道区域显示“暂无可用渠道，请先完成推送渠道接入”
- 前端禁止提交
编辑任务时，若历史已选渠道当前变为未接入：
- 保留原值用于展示
- 提交前要求用户重新选择可用渠道
时间选择默认使用当前用户时区。

3.12.3 前端组件拆分

组件名	主要职责
`AgentAutomationPanel.vue`	自动化主面板：列表查询、筛选、搜索、刷新、启停、删除、打开任务弹窗、打开渠道维护弹窗
`AutomationTaskDialog.vue`	新增/编辑自动化任务弹窗：表单回填、校验、提交
`AutomationChannelDialog.vue`	推送渠道维护弹窗：展示渠道卡片、打开具体接入弹窗
`WechatChannelConfigDialog.vue`	企业微信接入弹窗：企业ID、AgentId、Secret 录入与保存

拆分原则：

任务表单与主面板拆开，避免列表页承载复杂表单逻辑。
渠道维护与具体渠道接入弹窗拆开，便于后续扩展钉钉、飞书。
列表单条卡片操作较轻，不额外拆分行组件。

3.12.4 关键业务字段设计

AutomationTaskItem

字段名	类型	说明
`id`	string	自动化任务 ID
`agentId`	string	当前智能体 ID
`taskName`	string	任务名称
`taskDescription`	string	任务描述
`prompt`	string	自动化执行提示词
`startTime`	string	开始时间，格式 `YYYY-MM-DD HH:mm:ss`
`scheduleType`	`'ONCE' \| 'DAILY' \| 'WEEKLY' \| 'MONTHLY'`	执行频率类型
`scheduleLabel`	string	执行频率展示文案
`remindEnabled`	boolean	是否开启提醒方式
`remindChannels`	`AutomationChannelType[]`	已选择的提醒渠道
`status`	`'ENABLED' \| 'DISABLED'`	任务启用状态
`updateTime`	string	最近更新时间

AutomationTaskForm

字段名	类型	说明
`taskName`	string	任务名称，必填，建议 `1~50`
`taskDescription`	string	任务描述，选填，建议 `0~500`
`prompt`	string	提示词，必填，建议 `1~20000`
`startTime`	string	开始时间，必填
`scheduleType`	`'ONCE' \| 'DAILY' \| 'WEEKLY' \| 'MONTHLY'`	执行频率，必填
`remindEnabled`	boolean	是否开启提醒
`remindChannels`	`AutomationChannelType[]`	开启提醒时必填，至少一项

AutomationTaskQueryParams

字段名	类型	说明
`keyword`	string	任务名称关键字
`scheduleType`	string	类型筛选，默认 `ALL`
`status`	string	状态筛选，默认 `ALL`
`pageNum`	number	页码；若本期不分页可不传
`pageSize`	number	每页条数；若本期不分页可不传

AutomationChannelType

'WECOM'：企业微信
'DINGTALK'：钉钉
'LARK'：飞书

AutomationChannelStatus

'CONNECTED'：已接入
'DISCONNECTED'：未接入

AutomationChannelConfigItem

字段名	类型	说明
`channelType`	`AutomationChannelType`	渠道类型
`channelName`	string	渠道名称
`status`	`AutomationChannelStatus`	接入状态
`statusText`	string	状态展示文案
`supported`	boolean	本期是否支持维护
`configSummary`	string	接入说明或摘要

WechatChannelConfigForm

字段名	类型	说明
`corpId`	string	企业ID，必填
`agentId`	string	企业微信应用 AgentId，必填
`secret`	string	企业微信应用 Secret，必填

字段约定：

taskDescription 仅用于列表摘要与弹窗录入，不参与调度逻辑。
scheduleLabel 可由后端返回，也可由前端根据 scheduleType 映射。
remindChannels 仅在 remindEnabled = true 时有意义。
渠道配置按“智能体维度”维护，仅作用于当前智能体。

3.12.5 组件通信设计

智能体配置页宿主通过 props 或 provide/inject 传入：
- agentId
AgentAutomationPanel.vue 负责：
- 管理筛选条件 keyword / scheduleType / status / pageNum / pageSize
- 查询任务列表与渠道接入状态
- 打开/关闭 AutomationTaskDialog.vue
- 打开/关闭 AutomationChannelDialog.vue
- 处理启停、删除、刷新
AutomationTaskDialog.vue 通过 props 接收：
- open
- mode
- agentId
- taskDetail
- availableChannels
AutomationTaskDialog.vue 通过 emits 返回：
- success()
- cancel()
- update:open(boolean)
AutomationChannelDialog.vue 通过 props 接收：
- open
- agentId
- channelList
AutomationChannelDialog.vue 通过 emits 返回：
- refreshChannels()
- update:open(boolean)
WechatChannelConfigDialog.vue 通过 props 接收：
- open
- agentId
- detail
WechatChannelConfigDialog.vue 通过 emits 返回：
- success()
- cancel()
- update:open(boolean)

3.12.6 后端接口能力需求

能力名称	使用场景	用途说明
查询自动化任务列表	进入面板、搜索、筛选、刷新	获取当前智能体下自动化任务列表
查询自动化任务详情	点击编辑	获取单个任务完整配置，用于弹窗回填；若列表已返回完整字段可省略
新增自动化任务	点击新增弹窗确认	创建自动化任务
更新自动化任务	点击编辑弹窗确认	更新单个自动化任务配置
更新自动化任务状态	切换任务启停开关	启用或停用单个自动化任务
删除自动化任务	点击删除确认	删除单个自动化任务
查询推送渠道配置列表	进入面板、打开渠道维护弹窗	获取当前智能体下各渠道接入状态
保存企业微信渠道配置	企业微信接入弹窗点击确定	新增或更新企业微信接入信息

接口约定：

自动化任务与推送渠道配置均按当前 agentId 维度维护。
任务列表建议返回列表展示所需完整字段，编辑时如字段不全再单独查详情。
查询推送渠道配置列表 即使钉钉、飞书本期不支持，也应返回预留渠道状态，便于前端稳定渲染。
保存企业微信渠道配置 支持覆盖更新。
任务保存时后端需校验：
- taskName / prompt / startTime / scheduleType 必填
- remindEnabled = true 时 remindChannels 至少一项
- remindChannels 中的渠道必须为当前智能体已接入渠道
若后端已有统一字典接口，执行频率枚举可由字典下发；否则前端按固定枚举实现。

3.12.7 期望返回数据格式

查询自动化任务列表

{
  "list": [
    {
      "id": "auto001",
      "agentId": "9527",
      "taskName": "提醒超时未签到的人进行签到",
      "taskDescription": "通过对话识别是否要推送什么消息、推给谁、推到哪里。",
      "prompt": "请检查今日未签到人员，并在企业微信中发送提醒。",
      "startTime": "2026-04-03 12:14:52",
      "scheduleType": "ONCE",
      "scheduleLabel": "只执行一次",
      "remindEnabled": true,
      "remindChannels": ["WECOM"],
      "status": "ENABLED",
      "updateTime": "2026-04-03 12:14:52"
    },
    {
      "id": "auto002",
      "agentId": "9527",
      "taskName": "每天下午催办待审批合同",
      "taskDescription": "筛选当天待审批合同并提醒责任人。",
      "prompt": "请整理待审批合同并提醒对应负责人。",
      "startTime": "2026-04-03 18:00:00",
      "scheduleType": "DAILY",
      "scheduleLabel": "每天",
      "remindEnabled": true,
      "remindChannels": ["WECOM", "DINGTALK"],
      "status": "DISABLED",
      "updateTime": "2026-04-15 09:30:00"
    }
  ],
  "total": 2,
  "pageNum": 1,
  "pageSize": 10
}

查询自动化任务详情

{
  "id": "auto001",
  "agentId": "9527",
  "taskName": "提醒超时未签到的人进行签到",
  "taskDescription": "通过对话识别是否要推送什么消息、推给谁、推到哪里。",
  "prompt": "请检查今日未签到人员，并在企业微信中发送提醒。",
  "startTime": "2026-04-03 12:14:52",
  "scheduleType": "ONCE",
  "scheduleLabel": "只执行一次",
  "remindEnabled": true,
  "remindChannels": ["WECOM"],
  "status": "ENABLED",
  "updateTime": "2026-04-03 12:14:52"
}

新增 / 更新自动化任务

{
  "success": true,
  "id": "auto003"
}

更新自动化任务状态 / 删除自动化任务

{
  "success": true
}

查询推送渠道配置列表

[
  {
    "channelType": "WECOM",
    "channelName": "企业微信",
    "status": "CONNECTED",
    "statusText": "已接入",
    "supported": true,
    "configSummary": "接入企业微信以接收自动化消息。"
  },
  {
    "channelType": "DINGTALK",
    "channelName": "钉钉",
    "status": "DISCONNECTED",
    "statusText": "未接入",
    "supported": false,
    "configSummary": "本期仅预留，不支持配置。"
  },
  {
    "channelType": "LARK",
    "channelName": "飞书",
    "status": "DISCONNECTED",
    "statusText": "未接入",
    "supported": false,
    "configSummary": "本期仅预留，不支持配置。"
  }
]

保存企业微信渠道配置

{
  "success": true,
  "channelType": "WECOM",
  "status": "CONNECTED"
}

6. 工时评估

模块	主要工作内容	开发工时（人日）	联调与测试（人日）	小计（人日）
智能体首页	列表页、筛选、卡片操作、新建/发布/下线/删除等交互	1.5	1.0	2.5
智能体配置页框架	顶部信息区、左侧导航、路由容器、发布/预览编排	1.0	0.5	1.5
主要信息	表单回填、保存、顶部信息刷新	0.5	0.5	1.0
大模型	列表、筛选、添加模型、温度配置、启停、删除	1.5	1.0	2.5
对话增强	面板表单、保存、状态回填	0.5	0.5	1.0
知识库	列表绑定、筛选、添加/移除、保存	1.0	1.0	2.0
业务知识	列表绑定、筛选、添加/移除、保存	1.0	0.5	1.5
子智能体	绑定列表、筛选、添加/移除、保存	1.5	1.0	2.5
技能	技能列表、筛选、绑定/解绑、保存	1.0	0.5	1.5
权限	权限选择、可见可用范围设置、保存	0.5	0.5	1.0
访问API	API Key 列表、新增弹窗、复制、删除、启停	1.0	0.5	1.5
自动化	任务列表、筛选、新增/编辑、启停、删除、渠道维护	1.0	0.5	1.5
合计		12.0	8.0	20.0