PROJECT AKASHA

一个基于 telethon 构建的模块化 Telegram UserBot。集成了 Gemini LLM 用于上下文感知自动化，Edge-TTS 用于本地化语音合成，以及自定义媒体栈。

安装 · 系统核心 · 模块手册 · 故障排除

## 𓏵 概述 **Project Akasha** 解决了“愚蠢”自动回复的问题。与静态 Userbot 不同，它使用 **Neural engine**（Google Gemini）生成真正符合对话上下文的响应，模仿你的打字风格。 它包括用于阿姆哈拉语/英语语音笔记的 **TTS Wrapper**，用于节省 RAM 的 **Two-Stage Music Downloader**，以及各种管理工具。代码库结构便于在本地机器或云实例（Heroku/Railway）上部署。 ## ➜ 项目结构 确保你的目录与此树状图匹配。Bot 依赖相对路径来加载字体和进行数据库持久化。 ``` . ├── .env # API keys & configuration ├── config.py # settings loader ├── main.py # event loope entry point ├── requirements.txt # python dependencies ├── docker-compose.yml ├── Dockerfile # docker container configuration ├── Procfile # cloud deployment instructions ├── setup.sh # linux VPS automated setup ├── LICENSE # Legal Usage Permissions ├── core │ └── database.py # JSON/Mongo handler └── plugins ├── admin_tools.py # group management ├── ai.py # LLM & vision Logic ├── creative.py # pillow-based image manipulation ├── master_voice.py # edge-TTS & FFmpeg filters ├── music.py # yt-dlp audio wrapper ├── security.py # TTL capture └── system.py # auto-reply logic ``` ## ⚙ 安装 按照以下步骤进行部署。我们使用 **环境变量** 来防止凭据泄露。

1. 环境先决条件

必需：**Python 3.9+** 和 **FFmpeg**（用于音频转换）。 **Ubuntu/Debian:** ``` sudo apt update && sudo apt install python3 python3-pip ffmpeg -y ``` **Windows:** 1. 从 python.org 安装 Python。 2. 安装 FFmpeg 并将其添加到系统 PATH 中。

2. 安装依赖

``` pip install -r requirements.txt ```

3. 配置 (.env)

在根目录下创建一个 `.env` 文件。复制下方的结构。 **注意：** Bot 支持 API Key 轮换以绕过免费层速率限制。你可以使用单一列表（`GEMINI_KEYS`）或单独的变量（`GEMINI_KEY1`...）。 ``` # ---telegram core--- # 从 my.telegram.org 获取 API_ID=123456 API_HASH=your_api_hash SESSION=1BVts... # telethon session # --- AI engine --- # 方法 1：单个列表 # 使用逗号 (,) 分隔键 GEMINI_KEYS=AIzaSy1...,AIzaSy2...,AIzaSy3... # 方法 2：独立变量 GEMINI_KEY1=AIzaSyD... GEMINI_KEY2=AIzaSyF... GEMINI_API_KEY=AIzaSy... # fallback # --- database --- # 留空以使用本地 JSON MONGO_URL= ```

4. 执行

``` python main.py ``` *启动时触发 `Config.check_integrity()` 以验证 Key。*

## ☁︎ 云部署 对于 Render、Railway 或 Heroku，跳过 `.env` 文件。直接将这些变量注入到面板的 **环境设置** 中： * `API_ID` * `API_HASH` * `SESSION` * `GEMINI_KEYS`（在此粘贴你所有的 Key，用逗号分隔。例如：`Key1,Key2,Key3`）。 ## 𖡎 系统核心 由 `plugins/system.py` 管理。处理“离开状态”逻辑。 ### Auto-Pilot (`.auto`) 控制回复引擎。 | 命令 | 逻辑 | | :--- | :--- | | `.auto ai` | **神经模式：** 从最近 5 条消息中获取上下文，并通过 Gemini 生成响应。 | | `.auto static` | **静态模式：** 用预设字符串回复（例如，“Busy”）。 | | `.auto off` | **直通：** 禁用所有自动化。 | | `.auto [text]` | 更新静态模式变量。 | ### 上下文模式 (`.mode`) 向 AI 注入特定的系统提示词以改变语气。 * `sleep` - 简短、困倦的回复。 * `work` - 专业、简洁。 * `gaming` - 轻蔑/简短。 * `default` - 标准对话风格。 ### 延迟模拟 为了防止 Bot 检测： 1. **阅读延迟：** 标记为已读前随机休眠 `1-3s`。 2. **打字：** 计算 `len(response) * 0.1s` 以模拟人类打字速度。 ## ⊞ 模块手册 ### 1. 管理工具 (`plugins/admin_tools.py`) 标准群组管理。 * **Whois:** `.whois @user`。生成用户资料卡（ID、DC、Scam 状态、Bio）。 * **翻译器:** `Text //lang_code`。用翻译替换消息（例如，`Hey //am` -> `ሰላም`）。 * **管理:** * `.purge`: 递归删除消息。 * `.ban / .mute`: 标准用户限制。 * `.zombies`: 扫描已删除的帐户并清理它们以修正成员计数。 ### 2. TTS 引擎 (`plugins/master_voice.py`) **Microsoft Edge TTS** 的直接封装。支持用于音高/速率控制的 SSML 标签。 **命令:** `.say [text] [flags]` * **自动检测:** 根据文字脚本在 `Mekdes`（阿姆哈拉语）和 `Jenny`（英语）之间切换。 **标志 (FFmpeg Filters):** | 标志 | 应用的滤镜 | | :--- | :--- | | `.f / .m` | 强制女/男模型。 | | `.echo` | `aecho` 滤镜（大厅效果）。 | | `.radio` | 高通/低通滤波器链。 | | `.demon` | 音高偏移 `-400Hz`。 | | `.kid` | 音高偏移 `+400Hz`。 | *快捷方式:* `.whisper` 应用 `.slow` + 低音量。 ### 3. 图像工具 (`plugins/creative.py`) 基于 Pillow 的图像处理。 * **Meme 生成:** `.meme [Top];[Bottom]`。 * *逻辑:* 如果文本脚本需要，自动获取 `NotoSansEthiopic-Bold` 或 `NotoSansArabic`。在本地缓存字体。 * **贴纸 Kang:** `.kang`。将媒体转换为 `512px` WebP 并追加到你的贴纸包。 * *限制:* 跳过 >5MB 的文件以防止 VPS 上的内存泄漏。 ### 4. 音乐加载器 (`plugins/music.py`) 使用 `yt-dlp` 进行 SoundCloud/YouTube 提取。 **工作流程:** 1. **搜索:** `.song [Query]`。仅获取元数据。将结果缓存在 RAM（`SEARCH_STATE`）中。 2. **选择:** 回复 `1 到 5`。 3. **处理:** 下载 -> 转换为 **MP3 192kbps** (FFmpeg) -> 写入 id3 标签 -> 上传。 ### 5. AI & 视觉 (`plugins/ai.py`) * **生成式:** `.ai [prompt]`。使用轮换的 API Key 池。 * **视觉:** 回复图片并附带 `.ai explain`。将图片下载到内存缓冲区 -> 发送给 Gemini Vision API。 * **图片搜索:** `.img` 或 `.imgs`（图库）。抓取 DuckDuckGo 的图片。 ### 6. 安全模块 (`plugins/security.py`) #### **TTL Capture (防阅后即焚)** **状态:** 默认 `disabled`。 * **功能:** 钩入 `MessageMedia` 事件。如果 `ttl_period > 0`： 1. 将媒体下载到临时文件。 2. 转发到“Saved Messages”。 3. 附加“ꗃ vault capture”标签。 #### **虚假终端** * `.hack @user`: 重复编辑消息以模拟终端入侵。纯属恶作剧。 ## 🔧 故障排除 **1. FFmpeg 错误:** `FileNotFoundError`: 确保 Ffmpeg 位于你的系统 PATH 中或通过 `apt` 安装。 **2. API Key 限制:** 如果 `.ai` 失败，请检查你的 Gemini Key 是否有效。Bot 会自动轮换，但如果全部耗尽，它将返回错误。 **3. 依赖问题:** 强制重装: `pip install --force-reinstall -r requirements.txt`。

基于 MIT License 授权。

Project Akasha v1.0
为未知目的而构建 ☕︎。

标签：DLL 劫持, Edge-TTS, Gemini, Heroku, IM 工具, Python, Telegram UserBot, Telethon, TTS, 上下文感知, 人工智能, 大语言模型, 媒体管理, 拟人化, 无后门, 用户模式Hook绕过, 社交工程, 社交自动化, 网络调试, 自动化, 自动回复, 语音合成, 请求拦截, 逆向工具, 隐私