@glodon-aiot/bot-client-ui 0.0.0-snapshot-20250729081352

package/README.md

@@ -0,0 +1,403 @@
+# 安装依赖
+
+## 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# 《认证说明》/cwyipHfE1wRR7nhN#post-v1-resourceToken) |          |
+| apiUrl                                             | string                       | 否   | `https://copilot.glodon.com/api/cvforce` | 拼接规则：`${origin}/api/cvforce`，其中`origin`是部署服务的源地址。                                                                                                                              | 3.0.8    |
+| getContainer                                       | () => Element                | 否   | () => document.body                      | 容器元素获取方法，默认在 document.body 中渲染                                                                                                                                                    |          |
+| mode                                               | 'float' \| 'inlay'           | 否   | 'float'                                  | 悬浮按钮模式，或者嵌入模式                                                                                                                                                                       |          |
+| header                                             | Element \| string \| boolean | 否   | 应用名称                                 | 应用名称                                                                                                                                                                                         |          |
+| footer                                             | Element \| string \| boolean | 否   |                                          |                                                                                                                                                                                                  |          |
+| sider                                              | boolean                      | 否   |                                          | inlay 模式可用。<br/>是否展示左侧会话列表                                                                                                                                                        |          |
+| icon                                               | string                       | 否   |                                          | 影响greeting和triggerButton的icon                                                                                                                                                                |          |
+| size                                               | SizeConfig                   | 否   | {width: 450}                             | float 模式下：窗体大小                                                                                                                                                                           |          |
+| open                                               | boolean                      | 否   | false                                    | float 模式下：默认打开状态                                                                                                                                                                       |          |
+| triggerButton                                      | TriggerButtonConfig          | 否   | {visible: true}                          | triggerButton 设置                                                                                                                                                                               |          |
+| features                                           | Feature                      | 否   | FEATURE_DEFAULT                          | 功能配置                                                                                                                                                                                         |          |
+| debug                                              | boolean                      | 否   | false                                    | 1. 控制 log 输出。<br/>2. promptValues 变为非必填项；<br/>3. Agent 类型应用下，控制是否开启，debug 模式，由于收到权限限制，可能会配置失败。                                                      |          |
+| eventListeners<font style="color:#1DC0C9;"></font> | EventListeners               |      |                                          | 事件监听器配置                                                                                                                                                                                   |          |
+| errorHandlers                                      | ErrorHandlers                | 否   | -                                        | errorHandlers.token 是 token 验证失败后的处理器;<br/>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; // 推荐问题
+  };
+  // 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[] };
+}
+```
+
+## 事件与错误处理
+
+```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)
+        );
+      }
+    },
+  },
+});
+```