gs-ai-assistant

gs-ai-assistant 是从 main 主分支迁出的 AI 助手能力工程。

它负责沉淀并发布 AI 助手相关能力，包括助手入口、会话管理、指令库、模型选择、消息编排，以及 SQL / Table / Chart 等结构化结果展示。后续通过 npm 包形式提供给 main、gs-eant-comp、gs-flow-engine 以及其他宿主工程使用。

定位

main 原本包含较多基础能力和业务能力。为了让 main 更干净，也让其他工程可以按需复用，AI 助手能力被拆分到独立 npm 包中维护。

gs-ai-assistant 主要负责：

• AI 助手悬浮入口
• AI 对话弹窗
• 新对话、最近会话和本地会话缓存
• AI 指令库
• 能力类型选择（聊天 / SQL / 表格 / 图表）
• 在线 / 本地模型选择
• 普通消息、Thinking、错误消息展示
• SQL 预览和 SQL 执行结果展示
• 表格结果展示
• 基础图表结果展示
• AI 智能中心页面

不建议在本包中长期维护具体业务页面。业务页面、业务容器、流程引擎和系统基础壳能力，应由对应宿主或独立包维护。

技术栈

• Vue 3
• Vite
• Ant Design Vue 4
• Bootstrap 5
• Vuex 4
• Vue Router 4
• Vue Request
• AntV G2
• gs-eant-comp

安装

npm install gs-ai-assistant

样式需要在宿主工程中引入：

import 'gs-ai-assistant/dist/gs-ai-assistant.css'

使用方式

全量注册

import { createApp } from 'vue'
import GsAiAssistant from 'gs-ai-assistant'
import 'gs-ai-assistant/dist/gs-ai-assistant.css'

const app = createApp(App)

app.use(GsAiAssistant)

全量注册会注册 AiAssistantTool、AiAssistantModal 和 AiCenter。

按需引入

import { AiAssistantTool } from 'gs-ai-assistant'

按需引入适合宿主只需要把 AI 助手挂到自己的工具区或布局中的场景。

注册到 gs-eant-comp 全局工具区

import { registerGlobalTool } from 'gs-eant-comp'
import { AiAssistantTool } from 'gs-ai-assistant'
import 'gs-ai-assistant/dist/gs-ai-assistant.css'

registerGlobalTool({
  key: 'ai-assistant',
  component: AiAssistantTool,
  order: 20,
})

主要导出

| 导出 | 说明 | | --- | --- | | AiAssistantTool | AI 助手悬浮入口，负责展示入口按钮并打开助手弹窗 | | AiAssistantModal | AI 助手弹窗主体，负责布局、共享状态和本地会话缓存 | | AiCenter | AI 智能中心页面，用于承载 AI 任务、结果和配置入口 |

当前对外主要使用 AiAssistantTool。AiAssistantModal 保留导出主要用于调试、宿主定制和兼容；AiCenter 用于宿主把 AI 智能中心作为页面路由接入。

AI 配置

AI 助手配置统一从宿主的 store.state.app.aiAssistantConfig 读取。

基础示例：

{
  enabled: true,
  title: 'AI 小助手',
  chatUrl: '/chat',
  welcomeMessage: '开始一个新的 AI 对话',
  defaultModelSource: 'online',
  defaultModel: 'MiniMax-M2.7',
  models: [
    { label: 'MiniMax-M2.7', value: 'MiniMax-M2.7', source: 'online' },
    { label: 'qwen2.5:7b', value: 'qwen2.5:7b', source: 'local' }
  ],
  instructions: [
    {
      label: '系统问答',
      items: [
        {
          title: '系统能力介绍',
          description: '快速了解当前系统能力',
          actionType: 'chat',
          prompt: '请介绍当前系统的主要能力。'
        }
      ]
    }
  ]
}

配置说明：

| 字段 | 说明 | | --- | --- | | enabled | 是否展示 AI 助手入口 | | title | AI 助手弹窗标题 | | chatUrl | AI 对话接口地址 | | welcomeMessage | 空会话欢迎文案 | | defaultModelSource | 默认模型来源，通常为 online 或 local | | defaultModel | 默认模型名称 | | models | 模型下拉列表 | | instructions | AI 指令库配置 |

请求协议

发送消息时，请求体结构如下：

{
  message,
  session_id,
  action_type,
  model_source,
  model
}

字段说明：

| 字段 | 说明 | | --- | --- | | message | 用户输入内容 | | session_id | 当前前端会话 ID | | action_type | 当前能力类型 | | model_source | 模型来源，通常为 online 或 local | | model | 当前选择的模型名称 |

当前支持的 action_type：

| 类型 | 说明 | | --- | --- | | chat | 普通对话 | | sql | SQL 生成、解释或执行 | | table | 表格结果 | | chart | 图表结果 |

返回协议

AI 助手优先按 steps 渲染结构化消息；如果没有 steps，则使用普通 reply。

基础示例：

{
  reply: '普通回复内容',
  steps: [
    {
      type: 'ai',
      content: 'AI 回复内容',
      thinking: '可选 Thinking 内容'
    }
  ],
  usage: {
    prompt_eval_count: 128,
    context_limit: 8192,
    context_usage_ratio: 0.15,
    eval_count: 64
  },
  debug: {
    history_message_count: 4
  }
}

当前支持的 step.type：

| 类型 | 说明 | | --- | --- | | ai | 普通 AI 回复 | | thinking | 思考过程 | | thought | 思考过程，兼容类型 | | reasoning | 思考过程，兼容类型 | | sql_preview | SQL 预览 | | sql_result | SQL 执行结果 | | table_result | 表格结果 | | chart_result | 图表结果 | | error | 错误消息 |

table_result 示例

{
  type: 'table_result',
  title: '签到统计',
  summary: '共返回 3 条记录',
  sql: 'select name, count from checkin_summary',
  columns: ['name', 'count'],
  rows: [
    { name: '张三', count: 12 },
    { name: '李四', count: 8 }
  ]
}

chart_result 示例

{
  type: 'chart_result',
  title: '签到趋势',
  summary: '近 7 天签到趋势',
  sql: 'select day, count from checkin_daily',
  chart_type: 'line',
  x_field: 'day',
  y_fields: ['count'],
  data: [
    { day: '周一', count: 12 },
    { day: '周二', count: 18 }
  ]
}

chart_result 当前使用 AntV G2 做基础图表展示，支持基础柱状、折线、面积图，并保留原始 JSON 数据展示作为兜底。

组件目录结构

src/components
└── AiAssistant
    ├── index.js
    ├── AiAssistantTool.vue
    ├── AiAssistantModal.vue
    ├── AiCenter.vue
    ├── chat
    │   ├── AiChatInput.vue
    │   └── AiChatMessages.vue
    ├── instruction
    │   └── AiInstructionLibrary.vue
    ├── results
    │   ├── AiChartResultMessage.vue
    │   └── AiTableResultMessage.vue
    └── sidebar
        └── AiAssistantSidebar.vue

目录职责：

• AiAssistant/index.js：AI 助手模块入口，统一导出对外组件。
• AiAssistantTool.vue：AI 助手入口，负责悬浮按钮、拖拽和打开弹窗。
• AiAssistantModal.vue：AI 助手弹窗主体，负责布局、共享状态和 localStorage 会话恢复。
• AiCenter.vue：AI 智能中心页面，用于展示 AI 任务、结果预览和接入配置入口。
• chat：消息输入、消息展示、请求发送和消息编排。
• instruction：指令库分类、指令卡片和 prompt 回填。
• results：结构化结果展示，包括表格和图表。
• sidebar：新对话、指令库入口、最近会话和删除会话。

会话机制

当前会话由前端本地维护：

• 点击“新对话”只进入草稿视图，不立即创建会话。
• 发送第一条消息时创建 session。
• 最近会话保存在浏览器 localStorage 中。
• 会话缓存按助手标题隔离，避免多个宿主系统共用同一份缓存。
• 删除当前会话后回到新对话视图。

后续如果后端提供会话能力，可以继续接入新建会话、查询会话、删除会话和更新标题等接口。

开发命令

npm run dev
npm run build
npm run test

发布说明

构建产物输出到 dist，包入口由 package.json 中的 main 和 module 指向：

{
  "main": "dist/gs-ai-assistant.umd.cjs",
  "module": "dist/gs-ai-assistant.js"
}

发布前建议至少执行：

npm run build

维护原则

• 本包优先维护 AI 助手入口、会话、指令、模型、消息和结构化结果展示能力。
• 宿主业务页面不应长期沉淀在本包中。
• 系统基础壳、布局、全局工具区和基础组件能力应通过 gs-eant-comp 接入。
• 流程引擎相关能力应通过 gs-flow-engine 接入。
• 对外导出保持稳定，内部目录可以按职责继续收敛。