# @cloudbase/aiagent-framework

云开发 AI 智能体开发框架

使用示例：

```ts
import { TcbEventFunction } from '@cloudbase/functions-typings'
import { BotRunner, BotCore, IBot } from '@cloudbase/aiagent-framework'

class MyBot extends BotCore implements IBot {
  // 按接口约定实现对应的方法即可
}

export const main: TcbEventFunction<unknown> = function (event, context) {
  return BotRunner.run(event, context, new MyBot(context))
}
```

## API 说明

目前 `@cloudbase/aiagent-framework` 提供了 `IBot` 抽象接口 和 `BotCore` 基类，提供了开发 `云开发AI智能体` 所需的基本接口定义以基础方法。

基于这两个 `IBot & BotCore` 可以更简单方便的实现 `云开发 AI 智能体` 的开发，并部署到 `云函数2.0` 上。

使用方法：

```ts
class MyBot extends BotCore implements IBot {}
```

`MyBot` 类继承了 `BotCore` 类，并实现 `IBot` 定义的接口，即可实现 `云开发 AI 智能体`。

### `interface IBot` 抽象接口

该抽象类定义了云开发 AI 智能体的基本接口，开发者需要对其进行实现。可以通过继承 [`BotCore`](#class-botcore-基类) 获取基本能力，更加便捷地实现 `Ibot` 接口。

接口实际是对 [AI Agent](https://docs.cloudbase.net/http-api/ai-bot/ai-agent-%E6%8E%A5%E5%85%A5) 中定义的 API的实现。

| `HTTP API`                                        | `IBot Method Name`        | `Description` |
|---------------------------------------------------|-----------------------------------|-------------------------|
| `POST /v1/aibot/bots/:botId/send-message`         | `sendMessage`                     | 进行 Agent 问答对话       |
| `GET  /v1/aibot/bots/:botId/records`              | `getChatRecords`                  | 查询 Agent 历史对话信息    |
| `POST /v1/aibot/bots/:botId/recommend-questions`  | `getRecommendQuestions`           | 获取推荐问题              |
| `POST /v1/aibot/bots/:botId/feedback`             | `sendFeedback`                    | 提交用户反馈              |
| `GET  /v1/aibot/bots/:botId/feedback`             | `getFeedback`                     | 查询用户反馈              |

### `class BotCore` 基类

该类定义了以下属性：

* `BotCore#context`    - 云函数上下文
* `BotCore#botId`      - 云开发 `BotId`
* `BotCore#botTag`     - 云开发 `BotTag`
* `BotCore#sseSender`  - 调用 `BotCore#sseSender.send` 方法可以向客户端回复 `Server-Sent Events` 消息
* `BotCore#chatRecord` - 对话记录云开发数据模型

该类还定义了以下方法：

* **`createUserRecord({ record })`** - 创建用户聊天记录
  * `record`: 必须包含 `content`（消息内容）和 `reply`（回复的 record_id）
  * 返回完整的用户聊天记录对象（包含自动生成的 record_id 等字段）

* **`createBotRecord({ record })`** - 创建 Agent 聊天记录
  * `record`: 必须包含 `record_id`（记录ID）
  * 返回包含基础字段的 Agent 聊天记录对象

* **`createRecordPair({ userContent })`** - 创建 用户-Agent 聊天记录对
  * `userContent`: 用户消息内容
  * 返回包含：
    * `userRecord`: 用户聊天记录对象
    * `botRecord`: Agent 聊天记录对象
    * `updateBotRecord(content)`: 异步更新 Agent 聊天记录内容的方法

* **`getChatRecords(params)`** - 获取聊天记录（IBot 接口默认实现）
  * 参数包含分页和排序参数
  * 返回格式化后的聊天记录列表和总数

* **`getHistoryMessages(option?)`** - 获取整理后的历史消息
  * `option.size`: 获取的消息数量（默认20）
  * `option.removeLastUser`: 是否移除最后一条用户消息（默认true）
  * 返回经过整理的聊天记录，保证：
    1. 以用户消息开头
    2. 用户和Agent消息交替出现
    3. 默认以Agent消息结尾（当 removeLastUser 为 true 时）
    4. 无空内容的消息