# IM Client - Agent 即时通讯客户端

**Agent 的通信客户端工具**，管理消息历史、联系人、消息收发。

## 概述

IM Client 是每个 Agent 的通信客户端，负责：

- **消息收发**：与 IM Server 通信，发送和接收消息
- **消息历史**：存储该 Agent 的所有对话消息历史
- **联系人管理**：管理该 Agent 的联系人列表
- **消息队列**：管理待处理的消息（特别是数字员工型 Agent）

## 核心功能

- **连接 IM Server**：建立和维护与 IM Server 的连接
- **发送消息**：发送消息给指定联系人（Agent 或用户）
- **接收消息**：接收来自其他主体的消息
- **消息历史存储**：本地存储消息历史（在 Workspace 内）
- **联系人管理**：维护联系人列表和信息

## 存储位置

IM Client 的数据存储在 Agent 的 Workspace 内：

```
~/.gateway/workspaces/{workspace_id}/
├── im_client/
│   ├── config.json              # IM Client 配置
│   ├── contacts.json            # 联系人列表
│   ├── conversations/           # 对话历史
│   │   ├── {conversation_id}.jsonl
│   │   └── ...
│   └── queue/                   # 消息队列（数字员工型）
│       └── pending.json
```

## 架构

```
┌─────────────────────────────────────────────────────────┐
│                    IM Client                             │
│                                                          │
│  ┌────────────────────────────────────────────────────┐ │
│  │ Connection Manager（连接管理）                      │ │
│  │ - 连接 IM Server                                    │ │
│  │ - 心跳保活                                          │ │
│  │ - 断线重连                                          │ │
│  └────────────────────────────────────────────────────┘ │
│                                                          │
│  ┌────────────────────────────────────────────────────┐ │
│  │ Message Handler（消息处理）                         │ │
│  │ - 发送消息                                          │ │
│  │ - 接收消息                                          │ │
│  │ - 消息确认                                          │ │
│  └────────────────────────────────────────────────────┘ │
│                                                          │
│  ┌────────────────────────────────────────────────────┐ │
│  │ Storage Manager（存储管理）                         │ │
│  │ - 消息历史存储                                      │ │
│  │ - 联系人管理                                        │ │
│  │ - 消息队列管理                                      │ │
│  └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
                         ↑
                         │ IM Protocol
                         │
                    ┌────▼────┐
                    │IM Server│
                    └─────────┘
```

## 目录结构

```
im-client/
├── core/                          # 核心功能
│   ├── connection.py              # 连接管理
│   ├── message_handler.py         # 消息处理
│   └── storage.py                 # 存储管理
│
├── api/                           # Python API
│   └── client.py                  # IMClient 类
│
└── docs/                          # 文档
    ├── architecture.md            # 架构设计
    ├── api.md                     # API 文档
    └── storage.md                 # 存储格式文档
```

## 快速开始

### 创建 IM Client 实例

```python
from im_client.api.client import IMClient

# 创建 IM Client
client = IMClient(
    workspace_path="~/.gateway/workspaces/user_001",
    im_server_url="http://im-server:8080",
    agent_id="agent_001"
)

# 连接 IM Server
client.connect()
```

### 发送消息

```python
# 发送消息给指定联系人
client.send_message(
    to="agent_002",
    text="你好，我需要你的帮助"
)
```

### 接收消息

```python
# 注册消息处理回调
def on_message(message):
    print(f"收到消息：{message['text']}")
    print(f"来自：{message['from']}")

client.on_message(on_message)

# 或者主动查询消息队列（数字员工型）
messages = client.get_pending_messages()
for msg in messages:
    print(msg)
```

### 查询消息历史

```python
# 查询与指定联系人的对话历史
messages = client.get_conversation_history(
    contact_id="agent_002",
    limit=50
)

for msg in messages:
    print(f"{msg['from']}: {msg['text']}")
```

### 管理联系人

```python
# 添加联系人
client.add_contact(
    contact_id="agent_002",
    name="助理 Agent",
    description="负责数据分析的助理"
)

# 查询联系人列表
contacts = client.list_contacts()
for contact in contacts:
    print(f"{contact['name']}: {contact['description']}")
```

## 文档

### 核心文档

- [架构设计](./docs/architecture.md)：IM Client 架构和核心模块
- [API 文档](./docs/api.md)：Python API 参考
- [存储格式](./docs/storage.md)：消息历史和联系人的存储格式

## 开发状态

### 待设计 📋

- 架构设计
- API 设计
- 存储格式设计
- IM 协议实现

### 待实现 📋

- 核心代码实现
- Python API 实现
- 存储管理实现

## 相关项目

- [IM Server](../im-server/README.md)：IM 通信服务器
- [Gateway](../gateway/README.md)：Agent 管理系统
- [Agent Core](../agent/README.md)：Agent 核心框架