@glodon-aiot/agent-cli-sdk/README.md

aiot agent client js sdk

# @glodon-aiot/agent-cli-sdk

AIoT Agent 客户端 JavaScript SDK，提供与 AIoT 平台交互的能力，支持会话管理和消息处理。

## 安装

```bash
yarn add @glodon-aiot/agent-cli-sdk
# 或
npm install @glodon-aiot/agent-cli-sdk
```

## 核心概念

### BotClient
主客户端类，负责与 AIoT 平台建立连接和管理会话。

### Session
会话类，分为两种类型：
- `AgentSession`: 代理会话
- `DialogSession`: 对话会话

## 基本使用

### 初始化客户端

```javascript
import BotClient from '@glodon-aiot/agent-cli-sdk';

const token = 'your-aiot-token'; // AIoT 平台令牌
const config = {
  apiRoot: 'https://api.example.com' // AIoT API 根地址
};

const client = new BotClient(token, config);

// 监听客户端就绪事件
client.addEventListener('ready', () => {
  console.log('Client is ready');
});
```

### 会话管理

```javascript
// 获取会话列表
const sessions = await client.getSessions();

// 创建新会话
const newSession = await client.loadSession('', {
  name: 'New Session'
});

// 激活会话
client.activeSession = newSession.id;
```

### 发送消息

```javascript
const session = await client.loadSession('session-id');

// 发送文本消息
await session.send({
  text: 'Hello, world!'
}, {
  stream: true // 启用流式响应
});

// 监听消息事件
session.addEventListener('message:new', (message) => {
  console.log('New message:', message);
});
```

## 事件系统

### BotClient 事件
- `ready`: 客户端准备就绪
- `application:loaded`: 应用信息加载完成

### Session 事件
- `message:new`: 收到新消息
- `message:updated`: 消息更新
- `history:loaded`: 历史消息加载完成
- `data:updated`: 会话数据更新

## 高级功能

### 流式消息处理

```javascript
session.addEventListener('message:content', (content) => {
  // 处理流式消息内容
  console.log('Stream content:', content);
});

await session.send({
  text: 'Streaming question'
}, {
  stream: true
});
```

### 会话配置

```javascript
// 设置会话知识库
await session.setKnowledges([{id: 'knowledge-1'}]);

// 设置提示变量
await session.setPromptVariables([
  {key: 'var1', value: 'value1'}
]);

// 设置网络访问
await session.setNetOpen(true);
```

## 开发指南

### 依赖安装

`yarn install`

### 运行示例

`yarn start`

### 贡献代码

1. 切换到 master 分支: `git switch master`
2. 拉取最新代码: `git pull` 
3. 创建新分支: `git switch -c feature/xxx`
4. 提交代码: 
   ```bash
   git add .
   git commit -m "feat: your feature"
   git push
   ```
5. 创建 PR 合并到 develop 分支

### 代码提交规范

遵循 Conventional Commits 规范：
- `feat`: 新功能
- `fix`: bug 修复
- `docs`: 文档更新
- `style`: 代码样式
- `refactor`: 代码重构
- `test`: 测试相关
- `chore`: 构建/工具变更

示例：
```
git commit -m "feat: add new session API"
git commit -m "fix: message streaming issue"