第三练 BOT

项目详细说明

基于飞书（Lark）的智能聊天机器人，集成大语言模型（LLM）能力，提供多轮对话、文档问答、图像理解、日程管理等功能。

功能特性

• 智能对话：基于 LangChain 的多轮对话，支持上下文理解
• 工具调用：集成网络搜索、文档问答、图像理解、日程管理等工具
• RAG 文档问答：基于 LangGraph 的智能文档检索，自动选择直接处理或向量检索
• 群聊监控：智能判断何时主动介入群聊对话，无需 @机器人
• 视觉理解：使用 VLM 理解图像内容
• 日程管理：创建飞书日历事件
• 新闻收集：定时收集新闻并发送到群聊

技术栈

• Python >= 3.12
• 包管理器: uv
• LLM 框架: LangChain + LangGraph
• 大模型: 阿里云 DashScope (通义千问)
• 飞书 SDK: lark-oapi
• 向量存储: FAISS
• 缓存: Redis
• 搜索: Tavily

快速开始

环境要求

• Python 3.12+
• Redis 7.0+
• 飞书应用凭证
• DashScope API Key

安装

1. 克隆项目

git clone <repository-url>
cd chat-agent

2. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，填写必要的配置

3. 安装依赖

# 使用 uv（推荐）
uv sync

# 或使用 pip
pip install -e .

运行

本地开发

uv run main.py

Docker 部署

docker-compose up -d

配置说明

必需的环境变量

变量名	说明
APP_ID	飞书应用 ID
APP_SECRET	飞书应用密钥
DASHSCOPE_API_KEY	阿里云 DashScope API 密钥
TAVILY_API_KEY	Tavily 搜索 API 密钥
REDIS_HOST	Redis 主机地址
REDIS_PORT	Redis 端口
REDIS_PASSWORD	Redis 密码

飞书应用配置

1. 在飞书开放平台创建企业自建应用
2. 开启机器人能力，获取 APP_ID 和 APP_SECRET
3. 配置事件订阅：
   • 订阅方式：长连接（WebSocket）
   • 订阅事件：接收消息 (im.message.receive_v1)
4. 申请权限：
   • im:chat:readonly
   • im:message:send
   • im:message.group_msg
   • calendar:calendar:write
   • calendar:calendar.event:write
   • contact:user.department:readonly
5. 发布应用到企业

项目结构

chat-agent/
├── main.py                 # 项目入口
├── pyproject.toml          # 项目配置
├── docker-compose.yml      # Docker 编排
├── app/                    # 核心应用代码
│   ├── server.py           # Flask OAuth 服务
│   ├── agents/             # Agent 模块
│   │   ├── main_agent.py   # 主 Agent
│   │   ├── monitor.py      # 群聊监控
│   │   ├── rag_workflow.py # RAG 工作流
│   │   └── vlm.py          # 视觉语言模型
│   ├── bot/                # 飞书机器人模块
│   │   ├── client.py       # 飞书 API 客户端
│   │   ├── auth.py         # Token 认证
│   │   ├── messages/       # 消息处理
│   │   └── calendar/       # 日程管理
│   └── tools/              # 外部工具
├── storage/                # 文档存储
└── docs/                   # 文档

使用指南

与机器人对话

• 私聊：直接发送消息给机器人
• 群聊：@机器人 或 让机器人自动介入对话

支持的指令

指令	说明
/rag <问题>	基于上传的文档进行问答
/news	获取最新新闻
直接发送图片	自动使用 VLM 分析图像内容

文档问答

将 PDF 或图片文件放入 storage/ 目录，机器人会自动加载并建立向量索引。

开发

运行测试

uv run pytest

代码规范

# 格式化
uv run ruff format .

# 检查
uv run ruff check .

架构说明

Agent 架构

用户消息
    ↓
消息回调 (callback.py)
    ↓
群聊监控 (monitor.py) ← 判断是否主动回复
    ↓
主 Agent (main_agent.py)
    ↓
工具路由 → 搜索 / RAG / VLM / 日程

RAG 工作流

使用 LangGraph 实现智能路由：

• 短文档：直接由 LLM 处理
• 长文档：使用 Embedding 检索相关片段

相关链接

• LangChain 文档
• LangGraph 文档
• 飞书开放平台
• DashScope 文档

License

MIT