From 4941ce2452689111ba7bdd951df62b57a1f7c085 Mon Sep 17 00:00:00 2001
From: EchoZenith <60392923+EchoZenith@users.noreply.github.com>
Date: Sun, 25 Jan 2026 20:05:09 +0800
Subject: [PATCH] docs: create README.md

---
 README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6c16802
--- /dev/null
+++ b/README.md
@@ -0,0 +1,91 @@
+# Telegram Contact Bot (TG 客服机器人)
+
+[![Docker](https://img.shields.io/badge/Docker-supported-blue.svg?logo=docker)](https://www.docker.com/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg?logo=python)](https://www.python.org/)
+
+这是一个基于 Python 开发的轻量级 Telegram 机器人，旨在为个人或小团队提供 **“私聊中转”** 服务。它可以作为你的私密客服通道，保护你的个人账号不被外界直接获知。
+
+### 🌟 核心功能
+
+- **双向转发**：用户发给机器人的消息会立即转发给你；你只需回复该转发消息，机器人便会代你回传。
+- **无视隐私限制**：采用 SQLite 数据库记录消息映射关系，即使对方开启了“转发隐私保护”，你依然可以正常回复。
+- **全媒体支持**：支持文字、图片、语音、视频、文件、贴纸等多种消息格式。
+- **Docker 化部署**：支持 Docker Compose，一键运行，环境隔离，极致稳定。
+- **欢迎语自定义**：自动处理 `/start` 命令，向首次访问的用户发送个性化引导。
+
+---
+
+### 🚀 快速开始
+
+#### 1. 准备凭证
+1.  **获取 Bot Token**: 在 Telegram 咨询 [@BotFather](https://t.me/BotFather) 创建机器人并获取 API Token。
+2.  **获取 Admin ID**: 咨询 [@userinfobot](https://t.me/userinfobot) 获取你自己的 User ID（一串数字）。
+
+#### 2. 下载与配置
+克隆本仓库到你的服务器：
+```bash
+git clone [https://github.com/EchoZenith/TelegramContactBot.git](https://github.com/你的用户名/TelegramContactBot.git)
+cd TelegramContactBot/
+```
+复制示例配置文件并填入你的信息：
+```bash
+cp .env.example .env
+nano .env
+```
+在 .env 中填入：
+```bash
+BOT_TOKEN=123456:ABC-DEFG...
+ADMIN_ID=987654321
+```
+
+#### 3. 使用 Docker 部署 (推荐)
+​只需一行命令：
+```bash
+docker-compose up -d --build
+```
+
+#### 🛠️ 手动部署 (非 Docker)
+​如果你希望直接运行 Python 脚本：
+##### 1. 安装依赖：
+```bash
+pip install -r requirements.txt
+```
+##### 2. 设置环境变量：
+- ​Windows (PowerShell): $env:BOT_TOKEN="你的TOKEN"; $env:ADMIN_ID="你的ID"
+- ​Linux/macOS: export BOT_TOKEN="你的TOKEN" ADMIN_ID="你的ID"
+##### 3. 启动机器人：
+```bash
+python bot.py
+```
+
+### 📖 使用说明
+
+1. ​**接收消息**：当有人给机器人发送消息时，你会收到一条由机器人转发的消息。
+2. ​**回复消息**：在 Telegram 中**长按或右键点击**那条转发消息，选择 “**回复** (Reply)”，输入内容并发送。
+3. **注意**：必须使用“**回复**”功能，否则机器人不知道该将消息回传给哪位用户。
+### ​📂 项目结构
+
+```
+├── bot.py                # 核心逻辑代码
+├── Dockerfile            # 容器构建文件
+├── docker-compose.yml    # 编排定义
+├── requirements.txt      # Python 依赖
+├── .env.example          # 环境变量配置模板
+└── data/                 # 数据库挂载目录 (运行后自动创建)
+```
+### ⚠️ 安全与隐私
+
+- ​**Token 保护**：切勿将包含真实 Token 的 .env 文件提交到任何公共仓库。本仓库已默认忽略 .env。
+- ​**数据持久化**：数据库存放在 ./data 目录下，建议定期备份 messages.db。
+
+### ​🎁 鸣谢
+
+​感谢以下项目及技术的支持：
+- ​[python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) - 强大的 Telegram Bot 框架。
+- ​[aiosqlite](https://github.com/omnilib/aiosqlite) - 优秀的异步 SQLite 库。
+- ​[Docker](https://www.docker.com/) - 让部署变得如此简单。
+
+### ​⚖️ 开源协议
+
+​本项目基于 [MIT License](https://github.com/EchoZenith/TelegramContactBot/blob/main/LICENSE) 开源。
\ No newline at end of file