✦ Cleo
具有web界面、真实工具和内存的个人AI助手。
内置谷歌Gemini 2.5 Flash·Python·MCP·Flask
______________________________________________________________________
Cleo是一个在浏览器中本地运行的个人AI助手。与简单的聊天机器人不同，Cleo实际上可以 做事：读写文件、搜索网络、查询数据库以及获取天气和时间等实时数据——所有这些都由自定义MCP（模型上下文协议）服务器和Google Gemini提供支持。
______________________________________________________________________
✨ 特性
- 🌐 网络界面 --干净的深色主题UI，可在任何浏览器中运行
- 🔍 网络搜索 -实时搜索DuckDuckGo，不需要API密钥
- 📁 文件系统 --读取、写入、列出和删除沙盒文件夹中的文件
- 🗄️ SQLite数据库 --用自然语言管理笔记、任务和联系人
- 🌤️ 实时天气 -通过Open-Meteo实时预测（免费，无API密钥）
- 🕐 日期及时间 --支持时区的日期时间查询
- 🔁 对话记忆 --记住整个会话的上下文
- ⚡ 重试逻辑 --通过指数回退处理Gemini速率限制
______________________________________________________________________
🏗️ 建筑
┌──────────────────┐ HTTP ┌──────────────────┐ stdio (JSON-RPC) ┌──────────────────┐
│ │ ──────────────────► │ │ ────────────────────────────► │ │
│ Browser │ │ Flask + Gemini │ │ MCP Server │
│ (index.html) │ ◄────────────────── │ (app.py) │ ◄────────────────────────────│ (server.py) │
│ │ │ │ │ │
└──────────────────┘ └──────────────────┘ └──────────────────┘它是如何工作的，一步一步：
- 用户在浏览器中键入消息
- 浏览器通过以下方式将其发送到Flask
POST /api/chat请求 - Flask将完整的对话历史记录和工具定义传递给Gemini 2.5 Flash
- 双子座决定是调用一个或多个工具，还是直接回复
- 如果需要工具，Flask将MCP服务器作为子进程生成，并通过stdio上的JSON-RPC进行通信
- MCP服务器执行实际操作（文件I/O、SQL查询、HTTP请求等）并返回结果
- 结果会反馈给双子座，双子座会继续推理，直到得到最终答案
- 最终响应将返回浏览器并显示
这 代理循环 允许Cleo在一次循环中链接多个工具调用——例如，搜索网络，然后将结果保存到文件中。
______________________________________________________________________
🛠️ MCP工具
MCP服务器公开了4类11个工具：
📁 文件系统
| 工具 | 说明 |
|---|---|
read_file | 读取文件内容 |
write_file | 创建或覆盖文件（支持追加模式） |
list_files | 列出助手沙盒文件夹中的所有文件 |
delete_file | 删除文件 |
所有文件都存储在 ~/assistant_files/ --与系统的其他部分隔离。🔍 网络
| 工具 | 说明 |
|---|---|
web_search | 搜索DuckDuckGo-不需要API密钥 |
fetch_url | 从任何公共URL获取和提取文本 |
🗄️ 数据库（SQLite）
| 工具 | 说明 |
|---|---|
db_query | 快跑 SELECT 查询 |
db_execute | 快跑 INSERT, UPDATE, DELETE |
db_schema | 检查当前表结构 |
首次运行时会自动创建三个表：
| 表 | 字段 |
|---|---|
notes | id、标题、内容、创建at、更新at |
tasks | id、标题、描述、状态、due_date、created_at |
contacts | id、姓名、电子邮件、电话、笔记、created_at |
🌐 外部API
| 工具 | 说明 |
|---|---|
get_weather | 实时天气+3天预报 开放天气 |
get_datetime | 当前日期、时间和星期几，支持时区 |
______________________________________________________________________
🚀 设置和运行
先决条件
- Python 3.10+ 是必需的。请检查：
python --version如果你在macOS上，需要升级：
brew install python@3.12
python3.12 -m venv .venv
source .venv/bin/activate- 紫外线 （可选但推荐）--从安装 星光sh/uv:
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux
# or: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows- A. Gemini API密钥 --免费在 aistudio.google.com → 获取API密钥
步骤1——克隆仓库
git clone https://github.com/matteodr99/cleo-ai.git
cd cleo-ai步骤2——创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate # macOS / Linux
# .venv\Scripts\activate # Windows步骤3——安装依赖项
使用 紫外线 （推荐-快速和确定性）：
uv sync或者使用pip：
pip install -e .步骤4-设置API密钥
export GEMINI_API_KEY="your-key-here"或者创建一个 .env 项目根目录中的文件（永远不要提交此文件）：
GEMINI_API_KEY=your-key-here第五步——跑步
python app.py然后打开 http://localhost:5001 在您的浏览器中。
______________________________________________________________________
💬 示例提示
"What time is it in Tokyo?"
"What's the weather like in Milan this week?"
"Search the web for the latest news on AI agents"
"Create a file called 'ideas.txt' and write down 5 startup ideas"
"Add a task: review the project proposal by Friday"
"Show me all my pending tasks"
"Add a contact: Luca Bianchi, luca@email.com, +39 333 1234567"
"Search for the price of NVIDIA stock and save it to a file"______________________________________________________________________
📁 项目结构
cleo-ai/
├── app.py # Flask backend — Gemini agentic loop
├── pyproject.toml # Project metadata & dependencies (PEP 517)
├── requirements.txt # Python dependencies (alternative)
├── pytest.ini # Pytest configuration
├── README.md
├── .gitignore
├── mcp_server/
│ ├── __init__.py
│ └── server.py # MCP Server — all tool implementations
├── static/
│ ├── index.html # Frontend — dark theme chat UI
│ ├── logo.svg
│ └── favicon.ico
└── tests/
├── conftest.py
├── test_api.py
├── test_gemini_loop.py
└── test_mcp_tools.py______________________________________________________________________
🔧 添加新工具
- 定义它 --向添加条目
list_tools()在mcp_server/server.py - 实施它 --在中处理工具名称
call_tool()在同一个文件中 - 注册它 --将定义添加到
TOOL_DEFINITIONS在app.py
就是这样。双子座会在相关的时候自动开始使用新工具。
______________________________________________________________________
⚙️ 配置
| 设置 | 位置 | 默认值 |
|---|---|---|
| AI模型 | app.py → model= | gemini-2.5-flash |
| 系统提示/个性 | app.py → SYSTEM_PROMPT | 友好的意大利助理 |
| 港口 | app.py → app.run(port=) | 5001 |
| 文件存储路径 | mcp_server/server.py → FILES_DIR | ~/assistant_files/ |
| 对话历史长度 | app.py → messages[-20:] | 最后20条消息 |
______________________________________________________________________
🗺️ 路线图
- \[\]支持多个命名会话/对话
- \[\]日历集成（谷歌日历）
- \[\]电子邮件阅读和起草（Gmail）
- \[\]语音输入支持
- \[\]将对话导出为Markdown或PDF
- \[\]Docker支持，易于部署
- \[\]支持其他AI模型（OpenAI、Anthropic）
______________________________________________________________________
🤝 贡献
欢迎投稿！请打开问题或提交拉取请求。
______________________________________________________________________
📝 许可证
保留所有权利——有关详细信息，请参阅许可证文件。
______________________________________________________________________
Built by Matteo — powered by Google Gemini