@glodon-aiot/bot-client-ui 0.0.0-20251106104234

package/README.md

@@ -0,0 +1,432 @@
+# 安装依赖
+
+## npm
+
+`npm install @glodon-aiot/bot-client-ui`
+
+## yarn
+
+`yarn add @glodon-aiot/bot-client-ui`
+
+## 从 cdn 引入 cjs 文件
+
+一些项目无法处理 esm，请使用以下方式引入依赖。BotClientUI 将被注册在 window 对象上。
+`<script src="https://cv-cdn.obs.cn-north-4.myhuaweicloud.com/glodon/libs/bot-client-ui/3.3.0/bot-client-ui.umd.cjs"></script>`
+
+# 快速开始
+
+## 初始化
+
+```javascript
+import BotClientUI from '@glodon-aiot/bot-client-ui';
+
+new BotClientUI({
+  token: 'aiot_resource_token_goes_here',
+  getContainer: () => document.getElementById('client-ui'),
+  errorHandlers: {
+    token: (error) => {
+      console.error(error);
+    },
+  },
+});
+```
+
+## 在线预览：
+
+- 对话型应用 Demo [https://code.juejin.cn/pen/7494170871938940966](https://code.juejin.cn/pen/7494170871938940966)
+- Agent Demo [https://code.juejin.cn/pen/7372449505322467363](https://code.juejin.cn/pen/7372449505322467363)
+
+# BotClientUI 构造配置
+
+## 通用配置
+
+| 名称           | 类型                          | 必填    | 默认值                                   | 说明                                                                                                                                                                | 适用应用类型               | 支持版本   |
+| -------------- | ----------------------------- | ------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ---------- | ---------- | --- |
+| token          | string                        | 是      | -                                        | aiot 行业 AI 平台的 AI 应用的 resource token。详情查看[认证说明](https://glodon-cv-help.yuque.com/lzh2bp/eszzb5/evk1gvh3pqaexe74?singleDoc#%20《认证说明》)。       | 全部                       |            |
+| apiUrl         | string                        | 否      | `https://copilot.glodon.com/api/cvforce` | 拼接规则：`${origin}/api/cvforce`，其中`origin`是部署服务的源地址。                                                                                                 | 全部                       | 3.0.8      |
+| getContainer   | () => Element                 | 否      | () => document.body                      | 容器元素获取方法，默认在 document.body 中渲染                                                                                                                       | 全部                       |            |
+| sessionId      | string                        | 否      | -                                        | 默认加载的会话 ID                                                                                                                                                   | Agent/对话                 |            |
+| mode           | 'float'                       | 'inlay' | 否                                       | 'float'                                                                                                                                                             | 悬浮按钮模式，或者嵌入模式 | Agent/对话 |            |
+| header         | Element                       | string  | boolean                                  | 否                                                                                                                                                                  | 应用名称                   | 应用名称   | Agent/对话 |     |
+| footer         | Element                       | string  | boolean                                  | 否                                                                                                                                                                  |                            |            | Agent/对话 |     |
+| sider          | boolean                       | 否      |                                          | inlay 模式可用。 是否展示左侧会话列表                                                                                                                               | Agent/对话                 |            |
+| icon           | string                        | 否      |                                          | 影响 greeting 和 triggerButton 的 icon                                                                                                                              | Agent/对话                 | 3.3.1      |
+| size           | [SizeConfig](#GbxmJ)          | 否      | {width: 450}                             | float 模式下：窗体大小                                                                                                                                              | 全部                       |            |
+| open           | boolean                       | 否      | false                                    | float 模式下：默认打开状态                                                                                                                                          | Agent/对话                 |            |
+| triggerButton  | [TriggerButtonConfig](#djhoc) | 否      | {visible: true}                          | triggerButton 设置                                                                                                                                                  | Agent/对话                 |            |
+| features       | [Features](#uIpxC)            | 否      | FEATURE_DEFAULT                          | 功能配置                                                                                                                                                            | Agent/对话                 |            |
+| debug          | boolean                       | 否      | false                                    | 打开 debug 模式时：<br/>1. 控制 log 输出。 2. promptValues 变为非必填项； 3. Agent 类型应用下，控制 ws 连接是否开启，debug 模式，由于收到权限限制，可能会配置失败。 | Agent/对话                 |            |
+| eventListeners | [EventListeners](#IhvdK)      |         |                                          | 事件监听器配置                                                                                                                                                      | Agent/对话                 |            |
+| errorHandlers  | [ErrorHandlers](#VTONU)       | 否      | -                                        | errorHandlers.token 是 token 验证失败后的处理器; errorHandlers.promptValues 非 debug 模式下，检测空值                                                               | 全部                       |            |
+
+## 只适用于 Agent 应用的配置
+
+| 名称    | 类型          | 必填 | 默认值 | 说明                                                                                                              |
+| ------- | ------------- | ---- | ------ | ----------------------------------------------------------------------------------------------------------------- |
+| plugins | PluginsConfig | 否   | -      | Agent 应用适用。<br/>插件列表，`pluginCode`与`functionCode`要与平台中注册的插件标识和 API 名称保持一致            |
+| mcp     | McpConfig     | 否   | -      | Agent 应用适用。<br/>这里注册的 MCP 作用到每个会话中。<br/>如果希望特定会话才可注册 MCP，则在会话加载后动态注册。 |
+
+# BotClientUI 实例 API
+
+| 名称           | 类型                                         | 说明               |
+| -------------- | -------------------------------------------- | ------------------ |
+| reload         | `() => void`                                 |                    |
+| activeSession  | `Session`                                    | 当前活跃的会话信息 |
+| input          | `(message:string) => void`                   | 填充输入框内容     |
+| getMessageList | `(sessionId?: string) => Promise<Message[]>` | 获取历史对话列表   |
+
+# 类型定义
+
+## 基础类型
+
+```typescript
+interface SizeConfig {
+  width?: number | string;
+  height?: number | string;
+  maxWidth?: number | string;
+  maxHeight?: number | string;
+  minWidth?: number | string;
+  minHeight?: number | string;
+}
+
+interface TriggerButtonConfig {
+  style: string;
+  visible: boolean;
+}
+
+interface SessionInfo {
+  id: string;
+  name: string;
+}
+
+interface Message {
+  messageId: string;
+  content: string;
+  role: ChatMessageRole;
+  sessionId: string;
+  reference: IReference[];
+  searchReference: ISearchRefernce[];
+  messageTime: string;
+}
+
+enum ChatMessageRole {
+  Robot = 1,
+  User = 2,
+  System = 3,
+}
+
+interface IReference {
+  text: string;
+  docId: string;
+  fileId: string;
+  fileName: string;
+  knowledgeId: string;
+  knowledgeName: string;
+  score: number;
+  nickname: string;
+  knowledgeSourceName: string;
+}
+
+interface ISearchRefernce {
+  link: string;
+  title: string;
+  snippet: string;
+}
+
+interface SessionPrompt {
+  id?: string;
+  key: string;
+  name?: string;
+  value: string;
+  status?: PromptStatus;
+}
+
+interface Knowledge {
+  id: string;
+}
+```
+
+## 功能配置
+
+```typescript
+interface Feature {
+  // 问候
+  greeting?:
+    | boolean
+    | {
+        icon?: string;
+        text?: string; // 问候语
+        questions?: boolean; // 推荐问题
+        layoutBreakpoints?: number[]; // 布局断点数组
+      };
+  // toolbar中的"会话历史记录"
+  sessionList?: boolean;
+  // toolbar中的"新会话"
+  newSession?: boolean; // dialog only
+  // toolbar中的"上传文件"
+  fileUpload?: boolean; // dialog only
+  // toolbar中的"上传图片"
+  imageUpload?: boolean; // agent only
+  // 问题气泡
+  userMessageBox?: {
+    // dialog only
+    copy?: boolean;
+    editAgain?: boolean;
+  };
+  // 回答气泡
+  botMessageBox?: {
+    // dialog only
+    // 参考列表前置
+    referenceFirst?: boolean;
+    // 参考列表元素设置
+    reference?: {
+      // 是否可查看参考源文件
+      file?: boolean;
+      // 是否展开参考内容
+      itemExpanded?: boolean;
+    };
+    // 是否展示相关问题
+    relatedQuesions: boolean;
+    // 回答气泡底部设置
+    footer: {
+      items: {
+        componentName: 'AnswerAgain' | 'Copy' | 'Comments';
+        position: 'left' | 'right';
+      }[];
+    };
+  };
+  prompts?: boolean;
+  // toolbar中的网络访问
+  connectNetwork?:
+    | boolean
+    | { visible: boolean; default?: boolean; disabled?: boolean };
+  // 参考知识库设置
+  knowledges?:
+    | boolean
+    | { visible: boolean; default: Knowledge[]; disabled?: boolean };
+  // 用户指令变量设置
+  promptVariables?: boolean | { visible: boolean; default: SessionPrompt[] };
+  // 支持自定义问答内容markdown的超链接元素的点击事件
+  markdown?: {
+    componentProps?: {
+      a?: {
+        onClick?: (e: { nativeEvent: PointerEvent }) => void;
+      };
+    };
+  };
+}
+```
+
+## 事件与错误处理
+
+```typescript
+interface EventListeners {
+  comment: (payload: {
+    applicationId: string;
+    sessionId: string;
+    comment: Comment;
+  }) => void;
+  sessionload: (payload: {
+    applicationId: string;
+    sessionId: string;
+    session: SessionInfo;
+    sessionInstance: Session;
+  }) => void;
+  message: (payload: {
+    applicationId: string;
+    sessionId: string;
+    message: Message;
+  }) => void;
+  beforemessagesend: (payload: {
+    applicationId: string;
+    sessionId: string;
+    message: Message;
+  }) => boolean | Partil<Message> | Promise<boolean | Partil<Message>>;
+}
+
+interface ErrorHandlers {
+  token: (error: any) => void;
+  promptValues?: (error: any, values: { key: string; value: string }[]) => void;
+}
+```
+
+## Agent 应用配置
+
+### 插件配置
+
+```typescript
+interface PluginsConfig {
+  [pluginCode: string]: {
+    [functionCode: string]: Function;
+  };
+}
+
+interface McpServer {
+  type: 'sse';
+  url: string;
+  headers?: Record<string, string>;
+}
+
+interface McpConfig {
+  mcpServers: {
+    [key: string]: McpServer;
+  };
+}
+```
+
+### MCP 配置
+
+```typescript
+interface McpServer {
+  type: 'sse';
+  url: string;
+  headers?: Record<string, string>;
+}
+
+interface McpConfig {
+  mcpServers: {
+    [key: string]: McpServer;
+  };
+}
+```
+
+# Agent 类型应用的特别说明
+
+## 客户端插件使用
+
+由于该类型应用一般被当作某个软件的助手使用，需要主体软件在浏览器上注册一些方法，作为与浏览器交互的桥梁。
+
+例如，有客户端`Plugin A`，注册插件如下代码。
+
+其中，`pluginACode`是插件标识，可以在[行业 AI 平台](https://copilot.glodon.com/)的【插件管理 - 插件详情】中获得，不支持自定义。`functionCode`对应的是`API名称`，可自定义。
+
+```javascript
+window.pluginACode = {
+  functionCode1: (params, cb) => {
+    console.log(
+      `模拟pluginA function1 执行\n执行入参\n${JSON.stringify(arguments)}`
+    );
+    setTimeout(() => {
+      console.log(`模拟pluginA function1 执行完成`);
+      cb({
+        code: 0,
+        message: 'function1运行成功',
+        data: {
+          a: 'a',
+          b: 2,
+        },
+      });
+    }, 5000);
+  },
+  functionCode2: (params, cb) => {
+    console.log(
+      `模拟pluginA function2 执行\n执行入参\n${JSON.stringify(arguments)}`
+    );
+    setTimeout(() => {
+      console.log(`模拟pluginA function2 执行完成`);
+      cb({
+        code: 0,
+        message: 'function2运行成功',
+        data: {
+          a: 'a',
+          b: 2,
+        },
+      });
+    }, 10000);
+  },
+};
+```
+
+创建 Agent 应用 UI 的时候，配置`plugins`属性。完整代码如下：
+
+```javascript
+import BotClientUI from '@glodon-aiot/bot-client-ui';
+
+new BotClientUI({
+  token: 'aiot_resource_token_goes_here',
+  getContainer: () => document.getElementById('agent-ui'),
+  mode: 'inlay',
+  plugins: {
+    pluginACode: window.pluginACode,
+  },
+  errorHandlers: {
+    token: (error) => {
+      console.error(error);
+    },
+  },
+});
+```
+
+## MCP 注册
+
+MCP Server 信息可以在[行业 AI 平台](https://copilot.glodon.com/)的【MCP 管理 - MCP 详情】中获得。
+
+### 全局作用的 MCP 注册
+
+全局作用的 MCP 注册的完整代码如下：
+
+```javascript
+import BotClientUI from '@glodon-aiot/bot-client-ui';
+
+new BotClientUI({
+  token: 'aiot_resource_token_goes_here',
+  getContainer: () => document.getElementById('agent-ui'),
+  mode: 'inlay',
+  mcp: {
+    mcpServers: {
+      mcpServer_ID: {
+        type: 'sse',
+        url: 'https://copilot.glodon.com/proxy/XXXX/mcp/XXXX/mcp-mcpServer_ID/XXXX/sse',
+      },
+    },
+  },
+  errorHandlers: {
+    token: (error) => {
+      console.error(error);
+    },
+  },
+});
+```
+
+### 为当前会话注册 MCP
+
+为当前会话注册 MCP 的完整代码如下：
+
+```javascript
+import BotClientUI from '@glodon-aiot/bot-client-ui';
+
+const botClientUI = new BotClientUI({
+  token: 'aiot_resource_token_goes_here',
+  getContainer: () => document.getElementById('agent-ui'),
+  mode: 'inlay',
+  errorHandlers: {
+    token: (error) => {
+      console.error(error);
+    },
+  },
+  eventListeners: {
+    sessionload: ({ sessionInstance }) => {
+      if (sessionInstance) {
+        // MCP注册方法
+        const addMCP = () => {
+          sessionInstance.addMcpServer({
+            mcpServers: {
+              mcpServer_ID: {
+                type: 'sse',
+                url: 'https://copilot.glodon.com/proxy/XXXX/mcp/XXXX/mcp-mcpServer_ID/XXXX/sse',
+              },
+            },
+          });
+        };
+
+        // 只能在ready事件发生后才可以注册MCP
+        sessionInstance.addEventListener('ready', addMCP);
+        // session不活跃之后移除事件监听
+        sessionInstance.addEventListener('inactivated', () =>
+          sessionInstance.removeEventListener('ready', addMCP)
+        );
+      }
+    },
+  },
+});
+```