assist/docs/FEISHU_LONGCONN.md

# 飞书长连接模式使用指南

> ✅ **已验证可用** - 2026-02-11
>
> 本文档介绍如何使用飞书官方 SDK 的长连接模式，无需公网域名即可接入飞书机器人。

## 🎯 什么是长连接模式？

飞书官方 SDK 提供了**事件订阅 2.0（长连接模式）**，相比传统的 webhook 模式有以下优势：

| 特性 | Webhook 模式（旧） | 长连接模式（新）✅ |
|------|-------------------|-------------------|
| 公网域名 | ✅ 必需 | ❌ 不需要 |
| SSL 证书 | ✅ 必需 | ❌ 不需要 |
| 回调配置 | ✅ 需要配置 | ❌ 不需要 |
| 内网部署 | ❌ 不支持 | ✅ 支持 |
| 实时性 | 中等（HTTP 轮询） | ✅ 高（WebSocket） |
| 稳定性 | 中等 | ✅ 高（自动重连） |

---

## 📦 安装步骤

### 1. 安装依赖

```bash
cd /Users/macos/Desktop/tsp-assist/assist
pip install -r requirements.txt
```

**核心依赖：**
- `lark-oapi==1.3.5` - 飞书官方 Python SDK

### 2. 配置环境变量

编辑 `.env` 文件：

```bash
# 飞书配置（必需）
FEISHU_APP_ID=cli_xxxxxxxxxxxxx       # 你的飞书应用 ID
FEISHU_APP_SECRET=xxxxxxxxxxxxx        # 你的飞书应用密钥

# 数据库配置
DATABASE_URL=sqlite:///./data/tsp_assistant.db

# LLM 配置
LLM_PROVIDER=qwen
LLM_API_KEY=sk-xxxxxxxxxxxxx
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL=qwen-plus-latest
```

### 3. 初始化数据库

```bash
python init_database.py
```

### 4. 在飞书开放平台配置应用权限

访问 [飞书开放平台](https://open.feishu.cn/app)，为您的应用添加以下权限：

**必需权限：**
- ✅ `im:message` - 获取与发送单聊、群组消息
- ✅ `im:message:send_as_bot` - 以应用的身份发消息
- ✅ `im:chat` - 获取群组信息

**可选权限（用于工单同步）：**
- ✅ `bitable:app` - 查看、评论、编辑和管理多维表格

**注意：** 添加权限后需要重新发布应用版本。

---

## 🚀 启动服务

### 方式 1: 使用启动脚本（推荐）

```bash
python start_feishu_bot.py
```

启动后会看到：

```
================================================================================
🚀 TSP Assistant - 飞书长连接客户端
================================================================================

📋 配置信息:
   - App ID: cli_xxxxxxxxxxxxx
   - 数据库: sqlite:///./data/tsp_assistant.db
   - LLM: qwen/qwen-plus-latest
   - 日志级别: INFO

🔌 启动模式: 事件订阅 2.0（长连接）
✅ 优势:
   - 无需公网域名
   - 无需配置 webhook
   - 自动重连
   - 实时接收消息

💡 提示: 按 Ctrl+C 停止服务
================================================================================

🚀 启动飞书长连接客户端...
   - App ID: cli_xxxxxxxxxxxxx
   - 模式: 事件订阅 2.0（长连接）
   - 无需公网域名和 webhook 配置
✅ 飞书长连接服务初始化成功
```

### 方式 2: 在代码中集成

如果您想将长连接服务集成到现有的 Flask 应用中：

```python
import threading
from src.integrations.feishu_longconn_service import get_feishu_longconn_service

# 在后台线程中启动长连接服务
def start_feishu_in_background():
    service = get_feishu_longconn_service()
    service.start()

# 启动
feishu_thread = threading.Thread(target=start_feishu_in_background, daemon=True)
feishu_thread.start()

# 然后启动 Flask 应用
app.run(...)
```

---

## 🧪 测试

### 1. 在飞书群聊中测试

**场景 1：单个用户对话**

```
用户 A: @TSP助手 车辆无法连接网络怎么办？
机器人: [基于工单知识库的智能回复]

用户 A: 还有其他解决方法吗？
机器人: [基于上下文的多轮对话回复]
```

**场景 2：多用户群聊隔离**

```
群聊 1:
  用户 A: @TSP助手 我的车有问题
  机器人: [针对用户 A 的回复]

  用户 B: @TSP助手 我的车有问题
  机器人: [针对用户 B 的独立回复，不受用户 A 影响]

群聊 2:
  用户 A: @TSP助手 我的车有问题
  机器人: [全新对话，不受群聊 1 影响]
```

### 2. 查看日志

服务运行时会实时输出日志：

```
📨 [Feishu LongConn] 收到消息
   - 消息ID: om_xxxxxxxxxxxxx
   - 群聊ID: oc_xxxxxxxxxxxxx
   - 发送者: ou_xxxxxxxxxxxxx
   - 消息类型: text
   - 原始内容: @TSP助手 车辆无法连接网络
   - 清理后内容: 车辆无法连接网络
🔑 会话用户标识: feishu_oc_xxxxxxxxxxxxx_ou_xxxxxxxxxxxxx
🆕 为用户 ou_xxxxxxxxxxxxx 在群聊 oc_xxxxxxxxxxxxx 创建新会话: session_xxxxxxxxxxxxx
🤖 调用 TSP Assistant 处理消息...
📤 准备发送回复 (长度: 156)
✅ 成功回复消息: om_xxxxxxxxxxxxx
```

---

## 🔧 与旧模式的对比

### 旧模式（Webhook）- 已废弃

**文件：** `src/web/blueprints/feishu_bot.py`

**工作流程：**
```
飞书 → 公网域名 → Webhook → Flask → 处理消息
```

**缺点：**
- ❌ 需要公网域名
- ❌ 需要配置 SSL
- ❌ 内网无法部署
- ❌ 需要在飞书后台配置回调地址

### 新模式（长连接）- 推荐 ✅

**文件：** `src/integrations/feishu_longconn_service.py`

**工作流程：**
```
飞书 ← WebSocket 长连接 ← SDK 客户端 ← 处理消息
```

**优点：**
- ✅ 无需公网域名
- ✅ 无需 SSL 证书
- ✅ 内网可部署
- ✅ 无需配置回调地址
- ✅ 自动重连
- ✅ 更稳定

---

## 📊 架构说明

```
┌─────────────────────────────────────────────────────────────┐
│                      飞书服务器                               │
│                  (open.feishu.cn)                           │
└───────────────────────┬─────────────────────────────────────┘
                        │ WebSocket 长连接
                        │ (事件订阅 2.0)
                        ↓
┌─────────────────────────────────────────────────────────────┐
│          TSP Assistant (内网部署)                             │
│  ┌────────────────────────────────────────────────────┐    │
│  │  feishu_longconn_service.py                        │    │
│  │  - 飞书 SDK 长连接客户端                             │    │
│  │  - 自动接收消息事件                                   │    │
│  │  - 群聊隔离 (feishu_群ID_用户ID)                      │    │
│  └──────────────┬─────────────────────────────────────┘    │
│                 ↓                                           │
│  ┌────────────────────────────────────────────────────┐    │
│  │  RealtimeChatManager                               │    │
│  │  - 会话管理                                          │    │
│  │  - 多轮对话                                          │    │
│  └──────────────┬─────────────────────────────────────┘    │
│                 ↓                                           │
│  ┌────────────────────────────────────────────────────┐    │
│  │  TSP Assistant 智能引擎                             │    │
│  │  - LLM 调用                                         │    │
│  │  - 工单知识库匹配                                    │    │
│  │  - AI 分析和建议                                     │    │
│  └────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
```

---

## ⚙️ 高级配置

### 1. 调整日志级别

编辑 `.env`：

```bash
LOG_LEVEL=DEBUG  # 查看详细日志
LOG_LEVEL=INFO   # 默认（推荐）
LOG_LEVEL=WARNING  # 仅警告和错误
```

### 2. 同时运行 Web 管理后台和长连接服务

**方式 1：使用两个终端**

```bash
# 终端 1 - Web 管理后台
python start_dashboard.py

# 终端 2 - 飞书长连接服务
python start_feishu_bot.py
```

**方式 2：使用进程管理器（推荐生产环境）**

创建 `supervisord.conf`：

```ini
[program:tsp-web]
command=python start_dashboard.py
directory=/Users/macos/Desktop/tsp-assist/assist
autostart=true
autorestart=true

[program:tsp-feishu]
command=python start_feishu_bot.py
directory=/Users/macos/Desktop/tsp-assist/assist
autostart=true
autorestart=true
```

启动：
```bash
supervisord -c supervisord.conf
```

---

## ❓ 常见问题

### Q1: SSL 证书验证失败怎么办？

**错误信息：**
```
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain
```

**解决方案（macOS）：**

1. **运行 Python 证书安装脚本**（推荐）：
```bash
open "/Applications/Python 3.10/Install Certificates.command"
```

或者手动运行：
```bash
/Applications/Python\ 3.10/Install\ Certificates.command
```

2. **升级 certifi 包**：
```bash
python3 -m pip install --upgrade certifi
```

3. **验证修复**：
```bash
python3 -c "import urllib.request; urllib.request.urlopen('https://open.feishu.cn', timeout=5); print('✅ SSL 验证成功')"
```

**解决方案（Linux/Windows）：**
```bash
pip3 install --upgrade certifi
```

### Q2: 启动后没有收到消息？

**检查清单：**
1. ✅ 确认飞书应用权限已配置（`im:message`）
2. ✅ 确认应用已发布最新版本
3. ✅ 确认机器人已添加到群聊
4. ✅ 查看日志是否有连接成功的提示
5. ✅ 确认没有 SSL 证书错误（见 Q1）

### Q3: 提示"权限不足"？

**解决方案：**
1. 登录飞书开放平台
2. 进入应用管理 → 权限管理
3. 添加所需权限
4. 创建新版本并发布
5. 重启长连接服务

### Q4: 如何停止服务？

按 `Ctrl+C` 即可优雅停止。

### Q5: 可以在多台服务器上运行吗？

**不建议**。同一个飞书应用只应运行一个长连接客户端实例，否则会导致消息重复处理。

### Q6: 如何迁移旧的 Webhook 模式？

**建议：**
1. 保留旧代码（`feishu_bot.py`）作为备份
2. 使用新的长连接模式（`start_feishu_bot.py`）
3. 测试无误后，可以移除 webhook 端点

---

## 🎉 总结

现在您的 TSP Assistant 已经支持**飞书官方 SDK 的长连接模式**！

✅ **核心优势：**
- 无需公网域名
- 无需 webhook 配置
- 内网可部署
- 自动重连
- 群聊隔离
- 完整的工单管理和 AI 分析功能

✅ **使用方式：**
```bash
python start_feishu_bot.py
```

就这么简单！🚀