类型定义 (ai-blueking)

本文档列出 @blueking/ai-blueking 包中的核心类型定义。

AIBluekingProps

AIBlueking 组件的 Props 类型。

typescript

interface AIBluekingProps {
  // 基础配置
  /** API 服务地址 */
  url?: string;
  /** 组件标题 */
  title?: string;
  /** 渲染模式：chat(默认)、share(分享)、test(测试) */
  renderMode?: RenderMode;
  /** 请求配置 */
  requestOptions?: MaybeRefOrGetter<IRequestOptions>;
  /** 自定义 CSS 类名 */
  extCls?: string;
  /** 输入框占位文本 */
  placeholder?: string;
  /** 欢迎语 */
  helloText?: string;
  /** 预设提示词列表 */
  prompts?: string[];
  /** 资源列表（输入 @ 触发） */
  resources?: IAiSlashMenuItem[];

  // 功能开关
  /** 是否启用选中文本弹窗（AiSelection） */
  enablePopup?: boolean;
  /** 是否可拖拽 */
  draggable?: boolean;
  /** 是否启用会话管理 */
  enableChatSession?: boolean;
  /** 是否隐藏头部 */
  hideHeader?: boolean;
  /** 是否隐藏悬浮球 */
  hideNimbus?: boolean;
  /** 是否隐藏默认触发器 */
  hideDefaultTrigger?: boolean;
  /** 是否禁用输入 */
  disabledInput?: boolean;

  // 容器配置
  /** 渲染目标（CSS 选择器） */
  teleportTo?: string;
  /** 默认宽度 */
  defaultWidth?: number;
  /** 默认高度 */
  defaultHeight?: number;
  /** 默认左侧位置 */
  defaultLeft?: number;
  /** 默认顶部位置 */
  defaultTop?: number;
  /** 最大宽度 */
  maxWidth?: number | string;
  /** 最小化时的内边距 */
  miniPadding?: number;
  /** 默认聊天输入框位置 */
  defaultChatInputPosition?: 'bottom' | undefined;

  // Nimbus 配置
  /** 悬浮球大小 */
  nimbusSize?: 'large' | 'normal' | 'small';
  /** 是否默认最小化 */
  defaultMinimize?: boolean;

  // Popup 配置
  /** 快捷操作列表 */
  shortcuts?: IShortcut[];
  /** 快捷操作显示数量限制 */
  shortcutLimit?: number;
  /** 快捷操作过滤函数 */
  shortcutFilter?: (shortcut: IShortcut, selectedText: string) => boolean;

  // 会话配置
  /** 初始会话编码 */
  initialSessionCode?: string;
  /** 是否自动切换到初始会话 */
  autoSwitchToInitialSession?: boolean;
  /** 挂载时是否加载最近会话 */
  loadRecentSessionOnMount?: boolean;

  // Header 图标控制
  /** 是否显示历史记录图标 */
  showHistoryIcon?: boolean;
  /** 是否显示新建会话图标 */
  showNewChatIcon?: boolean;
  /** 是否显示压缩图标 */
  showCompressionIcon?: boolean;
  /** 是否显示更多图标 */
  showMoreIcon?: boolean;
  /** 下拉菜单配置 */
  dropdownMenuConfig?: DropdownMenuConfig;

  // 高级配置
  /** Nimbus 点击前钩子函数，返回 false 阻止默认 showPanel 行为 */
  beforeNimbusClick?: () => boolean | Promise<boolean | void> | void;
  /** ResizeLayout 配置（执行情况侧面板拖拽） */
  resizeProps?: {
    disabled?: boolean;
    initialDivide?: number | string;
    max?: number;
    min?: number;
  };

  /** 自定义侧栏内容区渲染（≥ v2.1.4-beta.7，透传内层 ChatBot） */
  getSideRenderComponent?: GetSideRenderComponent;
  /** 自定义侧栏 Tab 标签渲染（≥ v2.1.4-beta.7） */
  getSideTabRenderComponent?: GetSideTabRenderComponent;
  /** 侧栏自定义 Tab 切换时拉取详情（≥ v2.1.4-beta.7） */
  onCustomTabChange?: OnCustomTabChange;
}

AIBluekingExpose

AIBlueking 组件暴露的方法。

typescript

interface AIBluekingExpose {
  // 面板控制（await 后在 sessionList 就绪后 resolve；loadRecentSessionOnMount 时含当前会话初始化）
  show: (sessionCode?: string, options?: { isTemporary?: boolean }) => Promise<void>;
  hide: () => void;
  handleShow: (sessionCode?: string) => Promise<void>;
  handleClose: () => void;

  // 消息操作
  sendMessage: (message: string) => Promise<void>;
  stopGeneration: () => void;
  setCiteText: (text: string) => void;
  focusInput: () => void;

  // 快捷方式操作
  /** 选择快捷指令并显示表单，不会自动提交 */
  selectShortcut: (shortcut: IShortcut, selectedText?: string) => void;
  /** 直接发送快捷指令（跳过表单） */
  sendShortcut: (shortcut: IShortcut, selectedText?: string) => Promise<void>;

  // 会话管理
  addNewSession: (options?: CreateSessionOptions) => Promise<void>;
  switchToSession: (sessionCode: string) => Promise<void>;
  updateSessionName: (sessionCode: string, newName: string) => Promise<void>;

  // 容器控制
  updatePosition: (x: number, y: number) => void;
  updateSize: (w: number, h: number) => void;
  updatePositionAndSize: (x: number, y: number, w: number, h: number) => void;

  // 其他
  /** 获取 chatHelper 实例，用于访问 agent/session/message 等底层模块 */
  getChatHelper: () => IChatHelper | null;
}

AIBluekingEmits

AIBlueking 组件的事件类型。

typescript

interface AIBluekingEmits {
  // 面板事件
  (e: 'show'): void;
  (e: 'close'): void;

  // 拖拽事件
  (e: 'dragging', position: PositionAndSize): void;
  (e: 'resizing', position: PositionAndSize): void;
  (e: 'drag-stop', position: PositionAndSize): void;
  (e: 'resize-stop', position: PositionAndSize): void;

  // 消息事件
  (e: 'send-message', message: string): void;
  (e: 'receive-start'): void;
  (e: 'receive-text'): void;
  (e: 'receive-end'): void;
  (e: 'stop'): void;

  // 快捷方式事件
  (e: 'shortcut-click', data: { shortcut: IShortcut; source: 'main' | 'popup' }): void;

  // 会话事件
  (e: 'session-initialized', data: { openingRemark: string; predefinedQuestions: string[] }): void;
  (e: 'new-chat'): void;
  (e: 'new-chat-created', session: { sessionCode: string; sessionName?: string; createdAt?: string }): void;
  (e: 'history-click', event: Event): void;
  (e: 'auto-generate-name'): void;
  (e: 'help-click'): void;
  (e: 'rename', newName: string): void;
  (e: 'share'): void;

  // 消息选择事件
  (e: 'transfer-messages', data: { messageIds: string[] }): void;
  (e: 'share-messages', data: { messageIds: string[] }): void;

  // 错误事件
  (e: 'sdk-error', data: { apiName: string; code: number; data: unknown; message: string }): void;
}

ChatBotProps

ChatBot 组件的 Props 类型。

typescript

interface ChatBotProps {
  // 基础配置
  /** API 服务地址（独立模式） */
  url?: string;
  /** ChatHelper 实例（集成模式，优先级高于 url） */
  chatHelper?: IChatHelper;
  /** 请求配置（仅独立模式有效） */
  requestOptions?: MaybeRefOrGetter<IRequestOptions>;

  // 会话配置
  /** 是否自动加载 */
  autoLoad?: boolean;
  /** 会话编码 */
  sessionCode?: string;

  // 快捷方式与资源
  /** 快捷方式列表 */
  shortcuts?: IShortcut[];
  /** 资源列表（输入 @ 触发） */
  resources?: IAiSlashMenuItem[];
  /** 预设提示词列表 */
  prompts?: string[];

  // 界面配置
  /** 欢迎语 */
  helloText?: string;
  /** 输入框占位文本 */
  placeholder?: string;
  /** 渲染模式：chat(默认)、share(分享)、test(测试) */
  renderMode?: RenderMode;
  /** 高度 */
  height?: number | string;
  /** 最大宽度 */
  maxWidth?: number | string;
  /** 自定义 CSS 类名 */
  extCls?: string;
  /** 执行情况侧面板位置 */
  placement?: 'left' | 'right';

  // 分享与选择
  /** 是否启用消息选择 */
  enableSelection?: boolean;
  /** 分享操作是否加载中 */
  shareLoading?: boolean;

  // 高级配置
  /** MessageTools 的 tippy 弹窗配置 */
  messageToolsTippyOptions?: MessageToolsTippyOptions;
  /** ResizeLayout 配置（执行情况侧面板拖拽） */
  resizeProps?: {
    disabled?: boolean;
    initialDivide?: number | string;
    max?: number;
    min?: number;
  };

  /** 自定义侧栏内容区渲染（≥ v2.1.4-beta.7，透传 ChatContainer） */
  getSideRenderComponent?: GetSideRenderComponent;
  /** 自定义侧栏 Tab 标签渲染（≥ v2.1.4-beta.7） */
  getSideTabRenderComponent?: GetSideTabRenderComponent;
  /** 侧栏自定义 Tab 切换时拉取详情（≥ v2.1.4-beta.7） */
  onCustomTabChange?: OnCustomTabChange;
}

GetSideRenderComponent

自定义侧栏内容区渲染函数（≥ v2.1.4-beta.7）。

typescript

import type { h, VNode } from 'vue';

type GetSideRenderComponent = (
  createElement: typeof h,
  props?: Record<string, unknown>,
) => VNode | undefined;

props 为当前选中 Tab 的 data.props（Flow 场景常为 snake_case）
返回 VNode：作为侧栏内容根组件
返回 undefined：使用 addCustomTab 注册的 data.component

GetSideTabRenderComponent

自定义侧栏 Tab 标签渲染函数（≥ v2.1.4-beta.7）。

typescript

import type { CustomTab } from '@blueking/chat-x';
import type { h, VNode } from 'vue';

type GetSideTabRenderComponent = (
  createElement: typeof h,
  tab: CustomTab<Record<string, unknown>>,
  events: { removeCustomTab: (tabName: string) => void },
) => VNode | undefined;

OnCustomTabChange

侧栏自定义 Tab 切换时的数据拉取（≥ v2.1.4-beta.7）。

typescript

import type { CustomBkFlowTab } from '@blueking/chat-x';

type OnCustomTabChange = (tab: CustomBkFlowTab) => Promise<unknown>;

ChatBot 未传入时，对 Flow 节点 Tab 默认调用 chatHelper.message.getFlowAgentTaskNodeInfo(task_id, node_id)。

ChatBotExpose

ChatBot 组件暴露的方法和属性。

typescript

interface ChatBotExpose {
  // 消息操作
  sendMessage: (message: string) => Promise<void>;
  stopGeneration: () => void;
  setCiteText: (text: string) => void;
  focusInput: () => void;

  // 快捷方式操作
  /** 选择快捷指令并显示表单 */
  selectShortcut: (shortcut: IShortcut, selectedText?: string) => void;
  /** 直接发送快捷指令（跳过表单） */
  sendShortcut: (shortcut: IShortcut, selectedText?: string) => Promise<void>;

  // 会话操作
  switchSession: (sessionCode: string) => Promise<void>;

  // 分享操作
  /** 进入分享选择模式 */
  enterShareMode: () => void;
  /** 退出分享选择模式 */
  exitShareMode: () => void;

  // 其他
  /** 获取 chatHelper 实例 */
  getChatHelper: () => IChatHelper | null;
  /** 当前消息列表（响应式） */
  messages: ComputedRef<Message[]>;
  /** 当前会话（响应式） */
  currentSession: Ref<ISession | null>;
  /** 是否正在生成（响应式） */
  isGenerating: Ref<boolean>;
}

ChatBotEmits

ChatBot 组件的事件类型。

typescript

interface ChatBotEmits {
  'send-message': [message: string];
  'receive-start': [];
  'receive-text': [];
  'receive-end': [];
  'stop': [];
  'error': [error: Error];
  'session-switched': [session: ISession | null];
  'shortcut-click': [data: { shortcut: IShortcut; source: 'main' | 'popup' }];
  'agent-info-loaded': [chatHelper: IChatHelper];
  'feedback': [tool: IToolBtn, message: Message, reasonList: string[], otherReason: string];
  'confirm-share': [messages: Message[]];
  'cancel-share': [];
  'request-share': [];
  'execution-panel-change': [isCollapse: boolean];
}

IShortcut

快捷指令类型，扩展自 IAgentCommand。

typescript

interface IShortcut extends IAgentCommand {
  /** 用于强制重新渲染组件的唯一键值 */
  bindKey?: string;
  /** 是否启用自动回填（划词选择的内容会自动回填到 fill_back_component_key 指定的字段） */
  enable_fill_back?: boolean;
  /** 自动回填的目标字段 key */
  fill_back_component_key?: string;
  /** 是否隐藏底部按钮区域，默认为 false */
  hideFooter?: boolean;
  /** 指令模式：simple 简单模式（无 header/footer），advanced 高级模式（默认） */
  mode?: 'advanced' | 'simple';
  /** 自定义 icon 渲染函数 */
  iconRender?: (h: (type: any, props?: any, children?: any) => any) => VNode;
}

IShortcutComponent

快捷指令组件类型，扩展自 IAgentCommandComponent。

typescript

interface IShortcutComponent extends IAgentCommandComponent {
  /** 组件模式：simple 无 label，advanced 有 label */
  mode?: 'advanced' | 'simple';
  /** 选中的文本内容 */
  selectedText?: null | string;
  /** 当前输入模块是否显示发送按钮，默认为 false */
  showSendButton?: boolean;
}

IRequestOptions

请求配置类型。headers / data 使用 MaybeRequestValue（来自 @blueking/chat-helper），支持普通对象、零参函数、ref、computed；组件 props 上整体可为 MaybeRefOrGetter<IRequestOptions>。

typescript

import type { MaybeRequestValue, RequestData, RequestHeaders } from '@blueking/chat-helper';
import type { MaybeRefOrGetter } from 'vue';

interface IRequestOptions {
  headers?: MaybeRequestValue<RequestHeaders>;
  data?: MaybeRequestValue<RequestData>;
}

// AIBlueking / ChatBot / useChatBootstrap
type RequestOptionsProp = MaybeRefOrGetter<IRequestOptions>;

data 在 chat-helper 层按 HTTP 方法合并：POST/PUT/PATCH/DELETE → body；GET/HEAD/OPTIONS → query。

用法示例

typescript

import { computed, ref } from 'vue';

// 静态配置
const requestOptions: IRequestOptions = {
  headers: { 'X-Custom-Token': 'abc123' },
  data: { appCode: 'my-app' },
};

// 函数：每次请求前求值
const requestOptionsFn: IRequestOptions = {
  headers: () => ({ Authorization: `Bearer ${getToken()}` }),
  data: () => ({ timestamp: Date.now() }),
};

// ref / computed（推荐用于登录态、租户切换）
const token = ref('a');
const requestOptionsReactive = computed<IRequestOptions>(() => ({
  headers: { Authorization: `Bearer ${token.value}` },
  data: { app_id: 'my-app' },
}));

详见自定义请求。

DropdownMenuConfig

下拉菜单配置类型。

typescript

interface DropdownMenuConfig {
  /** 是否显示自动生成名称选项 */
  showAutoGenerate?: boolean;
  /** 是否显示重命名选项 */
  showRename?: boolean;
  /** 是否显示分享选项 */
  showShare?: boolean;
}

IAgentInfoData

Agent 信息数据类型。

typescript

interface IAgentInfoData {
  /** Agent 名称 */
  agentName?: string;
  /** SaaS URL */
  saasUrl?: string;
  /** 聊天群组配置 */
  chatGroup?: {
    enabled: boolean;
    staff: string[];
    username: string;
  };
  /** 会话设置 */
  conversationSettings?: {
    enableChatSession?: boolean;
    openingRemark?: string;
    predefinedQuestions?: string[];
  };
}

IChatHelper

ChatHelper 实例类型，由 useChatHelper 返回。

typescript

interface IChatHelper {
  /** Agent 模块 - 管理 agent 信息和聊天 */
  agent: IAgentModule;
  /** HTTP 模块 */
  http: unknown;
  /** Message 模块 - 管理消息 */
  message: IMessageModule;
  /** Session 模块 - 管理会话 */
  session: ISessionModule;
}

PositionAndSize

位置和尺寸类型。

typescript

interface PositionAndSize {
  x: number;
  y: number;
  width: number;
  height: number;
}

CreateSessionOptions

创建会话选项类型。

typescript

interface CreateSessionOptions {
  /** 是否为临时会话 */
  isTemporary?: boolean;
  /** 会话名称 */
  name?: string;
  /** 会话编码 */
  sessionCode?: string;
}

BootstrapPhase

启动阶段枚举，表示 useChatBootstrap 的当前初始化阶段。

typescript

enum BootstrapPhase {
  /** 空闲状态 */
  IDLE = 'idle',
  /** 正在加载 Agent 信息 */
  LOADING_AGENT = 'loading-agent',
  /** 正在加载会话 */
  LOADING_SESSION = 'loading-session',
  /** 就绪 */
  READY = 'ready',
  /** 出错 */
  ERROR = 'error',
}

ChatBootstrapOptions

useChatBootstrap 的配置选项。

typescript

interface ChatBootstrapOptions {
  /** chat-helper 实例或创建选项 */
  chatHelper?: IChatHelper | IUseChatHelperOptions;
  /** API 地址前缀 */
  url?: string;
  /** 请求配置 */
  requestOptions?: MaybeRefOrGetter<IRequestOptions>;
  /** 是否自动加载最近会话 */
  autoLoad?: boolean;
  /** 初始会话编码 */
  sessionCode?: string;
}

ChatBootstrapReturn

useChatBootstrap 的返回类型。

typescript

interface ChatBootstrapReturn {
  /** 当前启动阶段 */
  phase: Ref<BootstrapPhase>;
  /** chat-helper 实例 */
  chatHelper: IChatHelper;
  /** 组件管理器 */
  componentManager: ComponentManager;
  /** 聊天业务管理器 */
  chatBizManager: ChatBusinessManager;
  /** 会话业务管理器 */
  sessionBizManager: SessionBusinessManager;
  /** 快捷指令管理器 */
  shortcutManager: ShortcutManager;
  /** UI 状态管理器 */
  uiStateManager: UIStateManager;
  /** 启动函数 */
  bootstrap: () => Promise<void>;
}

类型定义 (ai-blueking) ​

AIBluekingProps ​

AIBluekingExpose ​

AIBluekingEmits ​

ChatBotProps ​

GetSideRenderComponent ​

GetSideTabRenderComponent ​

OnCustomTabChange ​

ChatBotExpose ​

ChatBotEmits ​

IShortcut ​

IShortcutComponent ​

IRequestOptions ​

用法示例 ​

DropdownMenuConfig ​

IAgentInfoData ​

IChatHelper ​

PositionAndSize ​

CreateSessionOptions ​

BootstrapPhase ​

ChatBootstrapOptions ​

ChatBootstrapReturn ​

类型定义 (ai-blueking)

AIBluekingProps

AIBluekingExpose

AIBluekingEmits

ChatBotProps

GetSideRenderComponent

GetSideTabRenderComponent

OnCustomTabChange

ChatBotExpose

ChatBotEmits

IShortcut

IShortcutComponent

IRequestOptions

用法示例

DropdownMenuConfig

IAgentInfoData

IChatHelper

PositionAndSize

CreateSessionOptions

BootstrapPhase

ChatBootstrapOptions

ChatBootstrapReturn