🤖 个人助理电报机器人
一个安全的、人工智能驱动的个人助理，生活在你的Telegram中。具有自主代理大脑，具有持久记忆、自适应调度和主动研究能力。由带有MCP集成的Gemini CLI提供支持。
 
✨ 特性
| 特性 | 描述 |
|---|---|
| 🔒 安全 | 仅响应授权用户ID |
| 🤖 AI驱动 | 连接到Gemini CLI以获得智能响应 |
| 📷 视觉 | 分析通过Telegram发送的图像 |
| 📁 文件访问 | 通过MCP管理指定目录中的文件 |
| 🌐 网页浏览 | 通过Playwright MCP控制浏览器（根据要求将截图发送给Telegram） |
| ☁️ 云存储 | 通过MCP访问谷歌云端硬盘 |
| 📅 日历和电子邮件 | 谷歌日历和Gmail集成 |
| ✅ 任务管理 | 带有自动提醒的清单 |
| ⏰ 定时任务 | 通过自然语言或cron表达式动态调度作业 |
| 🧠 自主代理 | 目标驱动的大脑，持续积压，自适应调度（30分钟-4小时），两阶段分诊→工作周期和自我改善的即时记忆 |
| 📰 新闻文摘 | 每日游戏行业新闻摘要 |
| 🕷️ 网络爬虫 | 使用反机器人旁路技术清除任何URL，由 残次品 |
| 💰 费用跟踪 | 通过Gmail+手动输入自动检测信用卡交易 |
| 🏋️ 运动跟踪器 | 会话式训练记录器——将区域、练习、集合、重复和重量记录到JSON中 |
| 🎤 语音消息 | 通过Groq Whisper实现语音转文本功能——适用于所有功能 |
| 💡 能力清单 | 机器人自我意识——主动提出相关特征 |
| 🔌 模块化自动化 | 易于添加/删除功能 |
🚀 快速开始
先决条件
- Python 3.10+
- Node.js 20+（用于Gemini CLI）
- Gemini CLI已通过身份验证(
npx @google/gemini-cli并遵循设置）
安装
- 安装Python依赖项：
pip install -r requirements.txt- 安装Node.js依赖项（Gemini CLI）：
npm install- 安装Playwright浏览器（用于网页浏览功能）：
npx playwright install chromium- 运行机器人：
python src/main.py配置
- 复制示例文件：
cp .env.example .env
cp config/gemini_settings.example.json config/gemini_settings.json- 编辑
.env自定义：
- TELEGRAM_BOT_TOKEN -来自@BotFather的机器人令牌 - ALLOWED_USER_IDS -以逗号分隔的授权Telegram用户ID列表 - GEMINI_TIMEOUT -Gemini CLI响应超时（默认值：300秒）
MCP服务器
编辑 config/gemini_settings.json 要配置MCP服务器，请执行以下操作：
- 文件系统 -读取/写入所选目录中的文件
- 剧作家 -控制web浏览器
> 注： 需要 @google/gemini-cli v0.29.5+（包含在 package.json).
注： Gemini CLI内置了Google Workspace（日历、Gmail、云端硬盘）集成，无需额外的MCP服务器。
能力清单
编辑 config/capabilities.json 教机器人了解自己的功能。每种能力都有：
- 触发器 --何时建议该功能的上下文提示
- 例子 --AI可以使用的示例建议
这允许机器人主动建议动作（例如。， *“要我为此设置提醒吗？”*)而不是等待明确的命令。
用法
常规命令
/start-欢迎留言/help-显示可用命令/status-检查Gemini CLI状态/security-查看安全配置/persona-重新加载角色配置- 任何文本-使用Gemini CLI聊天
任务命令
/task-添加新任务/task Buy groceries due:tomorrow-添加有截止日期的任务/tasks-列出所有待处理的任务/done-将任务标记为已完成/deltask-删除任务/cleartasks-删除已完成的任务
Cron命令
/cron-显示cron帮助/cron list-列出所有计划作业- `/cron add ""
` -使用显式cron表达式添加作业
/cron delete-删除计划作业/cron pause-暂停作业/cron resume-恢复暂停的作业- 自然语言：“每周一上午9点，查看我的交易流程”自动创建工作
新闻命令
/news-手动触发每日消化
Web抓取命令
/scrape-抓取一页并获取AI摘要/scrape-撕下一页，问一个具体的问题- 先尝试快速HTTP，然后退回到防机器人保护网站的隐形浏览器
支出命令
/expense-添加人工费用（例如。，/expense 250k coffee)/expense-显示今天的支出/expenses-月度支出汇总/expenses week-每周支出汇总/describe-为自动检测到的交易添加描述/delexpense-删除费用- 大华银行的信用卡交易每小时通过Gmail扫描自动检测一次
练习命令
/exercise-开始锻炼/next-完成当前练习，开始下一个练习（显示摘要）/finish-结束训练并保存到JSON/workouts-查看最近的锻炼历史记录- 在会话期间，短信绕过Gemini，直接发送给锻炼处理程序
上下文命令
/context-检查上下文窗口的使用情况/summarize-总结对话历史/clear-清除对话历史记录/clearall-清除历史记录和摘要
自动化
自动化是模块化功能，可以在 config/automations.json:
{
"tasks": {
"enabled": true,
"reminder_check_interval": 60
},
"brain": {
"enabled": true,
"min_cycle_minutes": 30,
"max_cycle_minutes": 240,
"quiet_hours_start": 23.5,
"quiet_hours_end": 7
},
"cron": {
"enabled": true,
"check_interval_seconds": 60,
"quiet_hours_start": 23.5,
"quiet_hours_end": 7
},
"expenses": {
"enabled": true,
"scan_interval_minutes": 60,
"alert_sender_email": "unialerts@uobgroup.com"
},
"exercise": {
"enabled": true,
"data_file": "workouts.json"
}
}可用自动化
- 任务 -带提醒的任务/清单管理
- 大脑 -具有持久积压、自适应调度和事件驱动触发器的自主AI代理
- 定时任务 -动态调度作业（自然语言或cron表达式，通过带MCP的Gemini CLI触发）
- 新闻 -每日游戏新闻摘要与人工智能摘要
- 开支 -通过自动Gmail扫描信用卡提醒进行费用跟踪
- 锻炼 -带有会话记录功能的锻炼/运动跟踪器
自主代理（Brain v3）
大脑自动化是一种自主的目标驱动代理，它：
- 分阶段 --查看其待办事项列表、用户任务、观察结果和对话历史记录，以决定要处理的内容
- 工作阶段 --使用MCP工具执行一步研究/分析，保存笔记并报告结果
- 事件驱动 --用户消息被记录为观察结果，并在下一个周期中进行碰撞
- 任务级 --从读取待处理任务
/task并主动帮助完成最后期限 - 自适应调度 --繁忙时循环30分钟，空闲时循环4小时（可配置）
- 持久状态 --积压、观察和周期信息保存到
agent_state.json - 自我提高记忆力 --Agent将工作周期中的经验教训累积到
agent_learnings.json，注入到未来的提示中。通过Gemini自动合并超过15节课程 - 安全护栏 --无法修改自己的代码库，只能创建独立脚本
添加新的自动化
- 创建文件夹：
src/automations/my_feature/ - 实现类扩展
BaseAutomation - 添加
config/automations.json - 重新启动bot
🐧 在Ubuntu服务器上部署（无头）
初始设置
# Install dependencies
sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-pip python3-venv git curl
# Install Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# Install Gemini CLI globally
sudo npm install -g @google/gemini-cli
# Clone and set up the bot
git clone https://github.com/hansel-7/gemini-friend.git personal_assistant
cd personal_assistant
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Install Playwright system dependencies
playwright install chromium
playwright install-deps
# Configure environment
cp .env.example .env
nano .env # Set GEMINI_CLI_COMMAND=gemini, DATA_DIR, etc.谷歌工作区扩展（无头认证）
在无头服务器上，Google Workspace扩展无法打开OAuth浏览器。使用 无头登录脚本 相反：
# Clone the extension source (includes headless login tool)
cd ~
git clone https://github.com/gemini-cli-extensions/workspace.git workspace-src
cd workspace-src
npm install
# Run headless auth
cd workspace-server
node dist/headless-login.js这打印了一个 谷歌OAuth URL。在任何浏览器（笔记本电脑、手机）中打开它，登录，浏览器显示一个JSON块。将JSON粘贴回终端。
然后将凭据复制到已安装的扩展：
cp ~/workspace-src/gemini-cli-workspace-token.json ~/.gemini/extensions/google-workspace/注： 如果尚未安装扩展，请运行gemini先安装一次，然后用以下命令安装：gemini extensions install https://github.com/gemini-cli-extensions/workspace
作为系统服务运行（24/7）
- 创建服务文件：
sudo nano /etc/systemd/system/personal-assistant.service [Unit]
Description=Personal Assistant Telegram Bot
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=
WorkingDirectory=/home//personal_assistant
ExecStart=/home//personal_assistant/venv/bin/python3 src/main.py
Restart=always
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/home//.npm-global/bin
[Install]
WantedBy=multi-user.target- 启用并启动：
sudo systemctl daemon-reload
sudo systemctl enable personal-assistant
sudo systemctl start personal-assistant- 有用的命令：
sudo systemctl status personal-assistant # Check status
sudo journalctl -u personal-assistant -f # Stream live logs
sudo systemctl restart personal-assistant # Restart after code updates- 更新工作流：
cd ~/personal_assistant && git pull
sudo systemctl restart personal-assistant安全
- 所有处理程序都使用
@authorized_only装饰器 - 未经授权的用户会被默默拒绝
- MCP服务器受到限制
--allowed-mcp-server-names - 文件系统访问限制为
D:\Gemini CLI - 记录到的所有访问尝试
logs/security.log
🏗️ 项目结构
personal_assistant/
├── .env # Your credentials (git-ignored)
├── .env.example # Template for .env
├── requirements.txt # Python dependencies
├── package.json # Node.js dependencies (Gemini CLI)
├── config/
│ ├── settings.py # Configuration loader
│ ├── automations.json # Automation settings
│ ├── capabilities.json # Bot capabilities manifest
│ └── gemini_settings.json # MCP server config
└── src/
├── main.py # Entry point
├── bot/
│ ├── handlers.py # Telegram handlers
│ └── security.py # Authorization
├── gemini/
│ └── cli_wrapper.py # Gemini CLI integration
├── automations/ # Modular automations
│ ├── base.py # Base automation class
│ ├── tasks/ # Task management
│ │ ├── manager.py # Task CRUD
│ │ ├── scheduler.py # Reminders
│ │ └── handlers.py # Commands
│ ├── cron/ # Dynamic scheduled jobs
│ │ ├── manager.py # Job CRUD + JSON persistence
│ │ ├── scheduler.py # Background job runner
│ │ └── handlers.py # /cron commands + NL detection
│ ├── news/ # News scraper & summarizer
│ │ ├── scraper.py
│ │ ├── scheduler.py
│ │ └── summarizer.py
│ ├── expenses/ # Expense tracking
│ │ ├── manager.py # Expense CRUD + JSON storage
│ │ ├── scanner.py # Gmail scanner for CC alerts
│ │ └── handlers.py # Commands + automation class
│ ├── exercise/ # Workout tracker
│ │ ├── manager.py # Workout JSON persistence
│ │ └── handlers.py # Session state + commands
│ └── brain/ # Autonomous AI Agent
│ ├── agent_state.py # Persistent state (backlog, observations)
│ ├── learnings.py # Self-improving prompt memory
│ ├── thinker.py # Two-phase triage + work prompts
│ ├── scheduler.py # Adaptive scheduling (30min–4h)
│ └── handlers.py # Event triggers + TaskManager integration
├── scraper.py # Web scraping (Scrapling)
└── utils/
├── logger.py # Logging
└── conversation.py # Context management📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
- 双子星命令行工具 -为这个机器人提供动力的人工智能骨干
- python电报机器人 -Telegram Bot API包装器
- 残次品 -具有反机器人旁路的自适应网络抓取框架
- MCP（模型上下文协议） -用于工具集成
- 格罗克 -闪电般快速的耳语语音转录