npm package: @mlt-org/xming-ai
Description: ## 简介
Author: will.li
Latest version: 0.0.1-alpha.8

# 小明 AI Copilot Kit

## 简介

Copilot Kit 为开发者提供易用的 小明 AI 相关能力，可以快速集成在项目当中，并且可以在小明插件中使用

CopilotKit 支持在页面（page）和小明插件（Copilot）中开发引用

> 注意:
>
> 1. 在页面引入时需要申请开发者权限或者设置使用插件用户权限；
> 2. 在插件中使用时需要遵守插件plugin 开发的规范，设置生效网站范围 @match

## 前置

使用 CopilotKit 相关能力前，需要有后端服务

- [小明标准版](https://xmingai.com) 中申请开发者资源
- [开源版本服务](https://github.com/MLT-OSS/samepage) 部署

## 安装

### 使用 npm 安装

```shell
npm install @mlt-org/xming-ai@0.0.1-alpha.8
```

### 使用 cdn 引入

你可以通过以下方式从CDN引入你的SDK：

```html
<script src="https://cdn.jsdelivr.net/npm/@mlt-org/xming-ai@0.0.1-alpha.8/dist/index.umd.js"></script>
```

引入后，你可以通过全局变量 XmingAi 来访问SDK的功能。例如：

```html
<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <title>使用CDN引入SDK示例</title>
    <script src="https://cdn.jsdelivr.net/npm/@mlt-org/xming-ai@0.0.1-alpha.8/dist/index.umd.js"></script>
  </head>
  <body>
    <div id="result"></div>
    <script>
      (async () => {
        // 0. 初始化
        const xmingai = new XmingAi.default();
        xmingai.init({
          appId: 'XXXX-XXXX',
        });

        // 1. 获取或者选择聊天的 bot
        let bot = '100';
        // or
        const bots = await xmingai.getBots();
        bot = bots[0];

        // 2. 设置历史消息 and 需要聊天的消息
        let history = [];
        let message = '15.11 和 15.3哪个数字比较大， 直接给出结果';

        // 3. 设置返回数据的处理函数
        function messageFunctionCall(data) {
          // 根据返回结果做处理
        }

        // 4. 新建会话
        const conv = await xmingai.createConversation({
          history, // 第 2 步设置
          config: {
            bot, // 第 1 步设置
          },
          callback: messageFunctionCall, // 第 3 步设置
        });

        // 5. 开始对话
        await conv.sendMessage(
          message, // 第 2 步设置
          {
            isStream: true,
            callback: messageFunctionCall, // 第 3 步设置
          }
        );
      })();
    </script>
  </body>
</html>
```

## 快速开始

> 定义相关输入

```javascript
// 第1步 设置聊天的 bot
let bot = '100';
// or
const bots = await xmingai.getBots();
bot = bots[0];

// 第2步 设置历史消息
let history = [];

// 第3步 设置会话消息
let message = '15.11 和 15.3哪个数字比较大， 直接给出结果';

// 第4步 设置返回数据的处理函数
function messageFunctionCall(data) {
  // 根据返回结果做处理
}
```

### 携带上下文对话

```javascript
import XmingAi, {Conversation, Language, Role} from '@mlt-org/xming-ai';

// 初始化
const xmingai = new XmingAi();
xmingai.init({
  appId: 'XXXX-XXXX',
});

// 新建会话
const conv = await xmingai.createConversation({
  config: {
    bot, // 第 1 步设置
  },
  history, // 第 2 步设置
  callback: messageFunctionCall, // 第 3 步设置
});

// 对话
await conv.sendMessage(
  message, // 第 4 步设置
  {
    isStream: true,
  }
);
```

### 不携带上下文单次对话

```javascript
import XmingAi, {Conversation, Language, Role} from '@mlt-org/xming-ai';

// 初始化
const xmingai = new XmingAi();
xmingai.init({
  appId: 'XXXX',
});

// 对话
const data = await xmingai.chat(
  {
    bot, // 第 1 步设置
    isStream: true,

  },
  message, // 第 3 步设置
  callback: messageFunctionCall, // 第 4 步设置
);
```

### 插件中注册 Action

```javascript
// ==UserScript==
// @name         小红书发帖
// @namespace    xiaohongshu-publish
// @version      1
// @description  小红书发帖
// @match        https://creator.xiaohongshu.com/publish/publish
// @grant        none
// @status       enabled
// ==/UserScript==

import XmingAi from '@mlt-org/xming-ai';
(() => {
  const xmingai = new XmingAi();
  xmingai.init({
    appId: 'XXXX',
  });
  xmingai.addCopilotAction({
    key: 'xiaohongshu-publish',
    name: '发布帖子',
    bots: [bot], // 第 1 步设置
    callback: messageFunctionCall, // 第 4 步设置
  });
})();
```

## 配置

通过 init 方法进行配置初始化，需要配置

```text
appId: 开发者 id
api: 后端服务地址
webHost: 前端地址
```

## API 文档

### 机器人对象 - Bot

#### getInputParams

- 参数: 无

- 返回值：

  - 使用该机器人的输入参数信息

    | key        | 类型    | 备注                            |
    | ---------- | ------- | ------------------------------- |
    | key        | string  | 传入接口的 key 值               |
    | name       | string  | 该参数的名称                    |
    | type       | enum    | 输入类型：text,image,video,file |
    | isRequired | boolean | 是否必传                        |

### 会话对象 - Conversation

#### sendMessage

发送消息

- 参数：

  | key     | 类型                                            | 备注                   |
  | ------- | ----------------------------------------------- | ---------------------- |
  | message | IReqMessageContent[], IReqMessageContent,string | 发送的消息或者消息数组 |
  | config  | ISendMessageConfig                              | 发送消息的配置         |

  - IReqMessageContent

    | key   | 类型   | 备注                             |
    | ----- | ------ | -------------------------------- |
    | key   | string | Bot.getInputParams 返回的 key 值 |
    | value |        | 输入值                           |

  - ISendMessageConfig

    | key      | 类型                   | 备注                                      |
    | -------- | ---------------------- | ----------------------------------------- |
    | isStream | boolean                | 是否流式返回（流式返回需要配置 callback） |
    | resType  | markdown               | 发返回数据格式                            |
    | language | Auto, Chinese, English | 返回数据语言                              |
    | callback |                        | 流式返回回调函数                          |

- 返回值：
  - Conversation对象

#### getMessages

获取会话所有消息

#### toString

获取最后一条消息的格式文本

### Base API （全局对象）

#### getBots

获取所有机器人列表

#### getBot(botKey)

获取单个机器人详情

- 参数：
  - botKey: 机器人 key
- 返回值：
  - 返回一个 bot 对象，后续可以直接在相关方法中传递，也可以调用机器人相关 API

#### createConversation

新建会话（可携带上下文）

- 参数：

  | key      | 类型           | 备注                                                    |
  | -------- | -------------- | ------------------------------------------------------- |
  | history  | InputMessage[] | 会话的历史对话                                          |
  | config   | IConfig        | 会话相关配置                                            |
  | callback |                | 该会话流式返回时的回调（优先级低于 sendMessage 的设置） |

  - InputMessage

    | key     | 类型                  | 备注             |
    | ------- | --------------------- | ---------------- |
    | role    | user,assistant,system | 该消息的发送角色 |
    | content | IContent[]            | 消息内容数组     |

    - IContent

      | key   | 类型   | 备注     |
      | ----- | ------ | -------- |
      | type  | string | 消息类型 |
      | value |        | 消息内容 |

  - IConfig

    | key      | 类型        | 备注           |
    | -------- | ----------- | -------------- |
    | bot      | Bot, string | 使用的机器人   |
    | language |             | 设置返回的语言 |

- 返回值：
  - Conversation对象

#### chat(config, message, callback)

单轮对话

- 参数：

  | key      | 类型                                             | 备注                   |
  | -------- | ------------------------------------------------ | ---------------------- |
  | message  | IReqMessageContent[], IReqMessageContent, string | 对话输入值             |
  | config   | IConfig                                          | 会话相关配置           |
  | callback |                                                  | 该会话流式返回时的回调 |

- 返回值：
  - Conversation对象

#### templateChat

传递参数对话可用

- 参数：

  | key      | 类型                 | 备注                   |
  | -------- | -------------------- | ---------------------- |
  | message  | IReqMessageContent[] | 对话输入值             |
  | config   | IConfig              | 会话相关配置           |
  | callback |                      | 该会话流式返回时的回调 |

- 返回值：
  - Conversation对象

### Copilot handle API （全局对象）

> 页面开发时需要安装 copilot 才可生效

#### addCopilotAction

copilot 中新建 action

- 参数：

| key      | 类型            | 备注                        |
| -------- | --------------- | --------------------------- |
| key      | string          | action的标识                |
| name     | string          | 展示在 copilot 中的操作名称 |
| bots     | Bot[], string[] | 在 copilot 中生效的 bot     |
| callback |                 | 触发 action 后的回调函数    |

#### openCopilot

打开 copilot 面板

#### continueToChat

继续在平台中聊天（可指定打开的平台，未指定时优先打开 copilot）

- 参数：

| key      | 类型             | 备注           |
| -------- | ---------------- | -------------- |
| conv     | Conversation对象 | 继续聊天的对象 |
| platform | copilot, web     | 需要继续的平台 |

#### chatToCopilot

在 copilot 中继续聊天

- 参数：

| key  | 类型             | 备注           |
| ---- | ---------------- | -------------- |
| conv | Conversation对象 | 继续聊天的对象 |

#### chatToWeb

在 web 网站中继续聊天（需要在 init 时配置 webHost）

- 参数：

| key  | 类型             | 备注           |
| ---- | ---------------- | -------------- |
| conv | Conversation对象 | 继续聊天的对象 |

#### content2Text

数据转换函数