# chat-agent

**Repository Path**: cufel-x/chat-agent

## Basic Information

- **Project Name**: chat-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-19
- **Last Updated**: 2026-02-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 第三练 BOT

[项目详细说明](./docs/explaination.md)

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

## 功能特性

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

## 技术栈

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

## 快速开始

### 环境要求

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

### 安装

1. 克隆项目

```bash
git clone <repository-url>
cd chat-agent
```

2. 配置环境变量

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

3. 安装依赖

```bash
# 使用 uv（推荐）
uv sync

# 或使用 pip
pip install -e .
```

### 运行

**本地开发**

```bash
uv run main.py
```

**Docker 部署**

```bash
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. 在[飞书开放平台](https://open.feishu.cn/)创建企业自建应用
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/` 目录，机器人会自动加载并建立向量索引。

## 开发

### 运行测试

```bash
uv run pytest
```

### 代码规范

```bash
# 格式化
uv run ruff format .

# 检查
uv run ruff check .
```

## 架构说明

### Agent 架构

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

### RAG 工作流

使用 LangGraph 实现智能路由：
- 短文档：直接由 LLM 处理
- 长文档：使用 Embedding 检索相关片段

## 相关链接

- [LangChain 文档](https://python.langchain.com/)
- [LangGraph 文档](https://langchain-ai.github.io/langgraph/)
- [飞书开放平台](https://open.feishu.cn/)
- [DashScope 文档](https://help.aliyun.com/document_detail/2587494.html)

## License

[MIT](LICENSE)