---
sidebar_position: 1
---

# IM 通道集成指南

IM 通道集成允许您将 Wegent 智能体连接到即时通讯平台，让用户可以在熟悉的聊天工具中直接与 AI 智能体对话。

---

## 📋 目录

- [概述](#-概述)
- [架构说明](#-架构说明)
- [使用说明](#-使用说明)
- [管理功能](#-管理功能)
- [用户映射机制](#-用户映射机制)
- [平台集成指南](#-平台集成指南)
- [常见问题](#-常见问题)
- [相关资源](#-相关资源)

---

## 🎯 概述

### 什么是 IM 通道集成？

IM 通道集成将 Wegent 智能体连接到即时通讯平台，让用户无需访问 Wegent 网页界面，即可在日常使用的聊天软件中直接与 AI 智能体对话。

### 核心价值

| 价值 | 描述 |
|------|------|
| **熟悉的环境** | 在您每天使用的聊天工具中使用 AI 智能体 |
| **实时响应** | 通过 AI 卡片技术获得流式 AI 响应 |
| **多轮对话** | 在多条消息之间保持上下文连贯 |
| **团队协作** | 与整个组织共享 AI 能力 |

### 支持的平台

| 平台 | 状态 | 功能 |
|------|------|------|
| **钉钉** | ✅ 已支持 | 流模式、AI 卡片流式响应、多轮对话 |
| **飞书** | 🔜 规划中 | 即将推出 |
| **企业微信** | 🔜 规划中 | 即将推出 |

---

## 🏗 架构说明

### 消息流转

下图展示了消息在 IM 集成系统中的流转过程：

```mermaid
sequenceDiagram
    participant User as 用户 (IM 平台)
    participant IM as IM 平台
    participant Backend as Wegent 后端
    participant Agent as AI 智能体

    User->>IM: 发送消息
    IM->>Backend: Stream API 回调
    Backend->>Backend: 解析用户身份
    Backend->>Backend: 创建/获取任务
    Backend->>Agent: 触发 AI 响应

    loop 流式响应
        Agent->>Backend: 生成内容片段
        Backend->>IM: 更新 AI 卡片
        IM->>User: 显示流式内容
    end

    Agent->>Backend: 完成响应
    Backend->>IM: 完成 AI 卡片
    IM->>User: 显示最终响应
```

### 关键组件

```mermaid
graph TB
    subgraph "IM 集成层"
        CM[通道管理器]
        CP[通道提供者]
        MH[消息处理器]
        RE[响应发射器]
    end

    subgraph "核心服务"
        TS[任务服务]
        US[用户服务]
        AS[智能体服务]
    end

    subgraph "外部平台"
        DT[钉钉 API]
        FS[飞书 API]
    end

    CM --> CP
    CP --> MH
    MH --> RE

    MH --> TS
    MH --> US
    TS --> AS

    CP <--> DT
    CP <--> FS

    style CM fill:#14B8A6,color:#fff
    style CP fill:#14B8A6,color:#fff
```

| 组件 | 用途 |
|------|------|
| **通道管理器 (Channel Manager)** | 管理所有 IM 通道连接的生命周期 |
| **通道提供者 (Channel Provider)** | 平台特定的连接处理器（钉钉、飞书等） |
| **消息处理器 (Message Handler)** | 处理传入消息并路由到智能体 |
| **响应发射器 (Response Emitter)** | 将 AI 响应发送回 IM 平台（同步或流式） |

---

## 💬 使用说明

### 基本对话

像在任何聊天中一样向机器人发送消息：

```
用户：你能帮我做什么？
机器人：我是由 Wegent 驱动的 AI 助手。我可以帮助您...
```

### 多轮对话

机器人在同一聊天会话中保持对话上下文：

```
用户：我正在开发一个 React 项目
机器人：很好！我很乐意帮助您的 React 项目...

用户：如何优化性能？
机器人：对于您的 React 项目，这里有一些性能优化建议...
```

### 开始新对话

要清除上下文并重新开始，使用 `/new` 命令：

```
用户：/new
机器人：已开始新对话。有什么可以帮助您的？
```

### AI 卡片流式响应

启用 AI 卡片流式响应后，您将看到响应实时出现：

1. 机器人显示"思考中..."指示器
2. 响应文本逐步流式显示
3. 最终响应以格式化形式呈现

---

## ⚙️ 管理功能

### 通道状态监控

在管理面板中查看通道健康状态：

| 状态 | 指示器 | 描述 |
|------|--------|------|
| **已连接** | 🟢 绿色 | 通道活跃并正在接收消息 |
| **已断开** | 🔴 红色 | 通道离线或遇到错误 |
| **已禁用** | ⚪ 灰色 | 通道被手动禁用 |

### 通道操作

| 操作 | 描述 |
|------|------|
| **启用/禁用** | 在不删除配置的情况下切换通道状态 |
| **重启** | 重新连接到 IM 平台（网络问题后有用） |
| **编辑** | 修改通道设置（密钥留空保持现有值） |
| **删除** | 移除通道配置 |

### 更新配置

编辑通道时：

- **敏感字段**（Client Secret）以 `***` 显示
- **留空**敏感字段以保留现有值
- 输入新值以更新凭证

### 监控指标

每个通道可用的指标：

- **运行时长**：通道已连接的时间
- **最近错误**：最近的错误消息（如有）
- **连接时间**：通道最后连接的时间

---

## 👥 用户映射机制

### 自动用户创建

当 IM 平台用户首次与机器人交互时：

1. 系统尝试查找现有的 Wegent 用户
2. 如果未找到，自动创建新用户账号
3. 用户与其 IM 平台身份关联

**默认用户创建：**
- **用户名**：IM 平台用户 ID
- **邮箱**：`{user_id}@im-platform.com`
- **认证来源**：对应的 IM 平台名称

### 企业用户映射

对于拥有现有用户目录（ERP、LDAP）的组织，可以配置自定义用户映射器：

```mermaid
flowchart LR
    IM[IM 平台用户] --> UM[用户映射器]
    UM --> |自定义映射| ERP[ERP/LDAP 查询]
    UM --> |默认| AC[自动创建]
    ERP --> WU[Wegent 用户]
    AC --> WU
```

请联系您的系统管理员配置企业用户映射。

---

## 🔗 平台集成指南

以下平台有详细的集成配置指南：

| 平台 | 链接 |
|------|------|
| **钉钉** | [钉钉集成配置指南](./dingtalk-integration.md) |

---

## ❓ 常见问题

### 连接问题

#### 通道显示"已断开"

**可能原因：**
1. Client ID 或 Client Secret 无效
2. 网络连接问题
3. IM 平台 API 服务中断

**解决方案：**
1. 在开放平台验证凭证
2. 检查 Wegent 服务器的网络连接
3. 尝试重启通道
4. 检查 IM 平台服务状态

#### 消息未被接收

**可能原因：**
1. IM 平台中未启用 Stream 模式
2. 机器人权限未配置
3. Wegent 中通道未启用

**解决方案：**
1. 验证 IM 应用设置中已启用 Stream 模式
2. 检查所有必需权限已授予
3. 确保通道已启用（开关已打开）

### 响应问题

#### 机器人无响应

**可能原因：**
1. 默认智能体未配置
2. 智能体未分配模型
3. 速率限制

**解决方案：**
1. 验证通道已选择默认智能体
2. 确保智能体有可用的模型配置
3. 检查通道状态中的速率限制错误

#### 响应缓慢或不完整

**可能原因：**
1. AI 卡片流式传输问题
2. 网络延迟
3. 响应内容过大

**解决方案：**
1. 尝试临时禁用 AI 卡片流式传输
2. 检查网络连接
3. 系统会在流式传输失败时回退到同步模式

### 用户问题

#### 用户未被识别

**可能原因：**
1. 用户映射配置问题
2. IM 平台用户信息不可访问

**解决方案：**
1. 检查 IM 应用中的用户权限
2. 验证用户映射配置
3. 联系管理员配置企业用户映射

---

## 🔗 相关资源

### 文档
- [核心概念](../../concepts/core-concepts.md) - 了解 Wegent 的架构
- [智能体设置](../settings/agent-settings.md) - 为 IM 通道配置智能体
- [配置模型](../settings/configuring-models.md) - 设置 AI 模型
- [钉钉集成配置](./dingtalk-integration.md) - 钉钉详细的配置步骤

### 外部资源
- [钉钉开放平台文档](https://open.dingtalk.com/document/)
- [钉钉 Stream 模式指南](https://open.dingtalk.com/document/orgapp/receive-message)

---

## 💬 获取帮助

需要帮助？

- 📖 查看 [常见问题](../../faq.md)
- 🐛 提交 [GitHub Issue](https://github.com/wecode-ai/wegent/issues)
- 💬 加入社区讨论

---

<p align="center">将您的 AI 智能体连接到 IM 平台，赋能您的团队！ 🚀</p>
