基于 LangGraph 的 Telegram AI 助手，支持长期记忆、网络搜索、深度研究和多用户权限管理。
- AI 对话 - 基于 OpenAI 兼容 API，支持上下文记忆
- Supervisor 架构 - 采用 LangGraph Supervisor 模式，智能调度工具调用
- 深度思考/研究 - 支持异步深度研究和分析任务，自动生成研究报告
- 长期记忆 - 使用向量数据库存储用户偏好和重要信息
- 网络搜索 - 集成 Tavily Search，获取实时信息
- 网页抓取 - 抓取并解析网页内容
- 定时任务/提醒 - 支持自然语言创建定时提醒，系统重启后自动恢复
- 多时区支持 - 基于用户位置自动识别时区，支持跨时区任务调度
- 权限管理 - 超管、群管、白名单三级权限体系
- 群组支持 - 支持私聊和群组，群组需 @ 或回复触发
- aiogram - Telegram Bot 框架
- LangGraph - Agent 编排
- deepagents - 深度思考/研究 Agent
- PostgreSQL - 对话历史和权限存储
- APScheduler - 定时任务调度
- Tavily - 网络搜索（可选）
- geopy + timezonefinder - 时区识别
- Jinja2 - 模板引擎
- Python >= 3.11
- PostgreSQL >= 14
- uv 包管理器（推荐）
# 克隆项目
git clone https://github.com/itsmorninghao/TelePal.git
cd TelePal
# 安装依赖
uv sync- 在 Telegram 中搜索 @BotFather 并打开对话
- 发送
/newbot命令 - 按提示输入机器人名称（显示名）和用户名（以
_bot结尾） - 创建成功后会收到 Bot Token，格式如
123456789:ABCdefGHIjklMNOpqrsTUVwxyz
# 复制配置文件
cp .env.example .env
# 编辑配置
vim .env必填配置项：
TELEGRAM_BOT_TOKEN- 上一步获取的 Bot TokenPOSTGRES_*- 数据库连接信息OPENAI_API_KEY/OPENAI_BASE_URL/OPENAI_MODEL- LLM 配置EMBEDDING_*- 嵌入模型配置（用于长期记忆）INITIAL_SUPER_ADMINS- 初始超管的 Telegram User ID
可选配置：
TAVILY_API_KEY- 启用网络搜索功能
使用 Docker Compose 一键部署所有服务（包括 PostgreSQL 和 Ollama）：
# 进入 docker 目录
cd docker
# 启动所有服务
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止服务
docker-compose down如果 PostgreSQL 和 Ollama 服务已经通过其他方式部署，可以单独启动应用服务（默认使用 host 网络模式）：
# 进入 docker 目录
cd docker
# 使用 docker-compose.app.yml 单独启动应用
docker-compose -f docker-compose.app.yml up -d
# 查看日志
docker-compose -f docker-compose.app.yml logs -f
# 停止服务
docker-compose -f docker-compose.app.yml down注意：默认使用 host 网络模式，应用可以通过 localhost 访问主机上的服务。如果需要连接到 Docker 网络中的服务，请参考 docker/README.md 中的配置说明。
详细说明请参考 docker/README.md。
如果不想使用 Docker，可以在本地直接运行应用：
# 使用启动脚本
./bot.sh start
# 查看状态
./bot.sh status
# 查看日志
./bot.sh logs
# 停止
./bot.sh stop或直接运行：
uv run python main.py| 命令 | 说明 |
|---|---|
/group_authorize <chat_id> |
授权群组 |
/group_revoke <chat_id> |
撤销群组授权 |
/group_list |
查看已授权群组 |
/permission_set <user_id> <role> |
设置用户权限 |
| 命令 | 说明 |
|---|---|
/whitelist_add <user_id> [type] [chat_id] |
添加白名单 |
/whitelist_remove <user_id> [type] [chat_id] |
移除白名单 |
/whitelist_list [type] [chat_id] |
查看白名单 |
| 命令 | 说明 |
|---|---|
/memory_list [user_id] [query] |
查看长期记忆（超管可指定用户） |
/memory_delete [user_id] <key> |
删除记忆（超管可指定用户） |
/set_location |
设置位置信息以获取时区（仅私聊） |
/help |
显示可用命令列表（根据身份动态显示） |
省略部分文件，只保留了核心目录结构展示
TelePal/
├── main.py # 入口
├── bot.sh # 启动脚本
├── .env.example # 配置模板
├── src/
│ ├── agent/ # LangGraph Agent
│ │ ├── graph.py # Graph 定义
│ │ ├── state.py # 状态定义
│ │ ├── graphs/ # Graph 实现
│ │ │ ├── supervisor.py # Supervisor 主图
│ │ │ └── deep_think.py # 深度思考图
│ │ ├── prompts/ # 系统提示词模板
│ │ └── tools/ # Agent 工具
│ ├── auth/ # 权限系统
│ │ ├── models.py # 领域模型（dataclass）
│ │ └── service.py # 权限检查服务
│ ├── bot/ # Telegram Bot
│ ├── database/ # 数据库模块
│ │ ├── engine.py # SQLAlchemy 异步引擎
│ │ ├── langgraph_pool.py # LangGraph 连接池
│ │ ├── models.py # ORM 模型
│ │ ├── init_db.py # 数据库初始化
│ │ ├── langgraph/ # LangGraph 存储
│ │ └── repositories/ # 数据访问层
│ └── utils/
│ ├── logger.py
│ ├── settings.py
│ └── langchain_utils.py
├── data/ # 数据目录
├── docs/ # 文档目录
├── docker/ # Docker 配置
│ ├── docker-compose.yml
│ ├── docker-compose.app.yml
│ ├── Dockerfile
│ ├── init-db.sql
│ └── README.md
└── logs/ # 日志目录
- 让模型能够感知时间,兼容多时区
- 基于自然语言的生成/执行定时任务
- 采用 supervisor 的架构形式
- 深度思考/研究功能（异步任务）
- 在群聊中能够识别出不同的人,而不是把所有人当成同一个人
- 可能会做多会话管理,正在考虑是否需要这样的功能
- 可能会考虑对 SQLite 的支持以简化部署
MIT