## 项目概述

Odysseus 是一个自托管的 AI 工作空间，集成了聊天、智能体、研究、文档、邮件、笔记、日历和本地模型工作流。它旨在提供一个全面的、可本地部署的 AI 助手平台，用户可以在其中管理日常任务和知识。项目使用 Python 编写，采用 AGPL-3.0 许可证。

## 核心功能

- **聊天与智能体**：支持本地/API 模型、工具、MCP、文件、Shell、技能和记忆。
- **Cookbook**：提供硬件感知的模型推荐、下载和服务。
- **深度研究**：多步骤网络研究，包括来源阅读和报告生成。
- **对比**：盲测并排模型测试和综合。
- **文档**：以写作为先的编辑器，支持 AI 编辑、建议、Markdown、HTML、CSV 和语法高亮。
- **邮件**：IMAP/SMTP 收件箱，支持分类、标签、摘要、提醒和回复草稿。
- **笔记、任务和日历**：提醒、待办事项、定时智能体任务和 CalDAV 同步。
- **其他**：图库/图像编辑器、主题、上传、网络搜索、预设、会话和双因素认证。

## 适用与不适用场景

**适用场景：**

- 希望完全掌控数据和 AI 工作流的个人或团队。
- 需要集成聊天、文档、邮件、日历等多种功能的统一工作空间。
- 希望使用本地模型或私有 API 进行 AI 任务。
- 需要深度研究和文档处理能力的用户。

**不适用场景：**

- 需要托管式、零维护解决方案的用户。
- 对 Microsoft Outlook/Office 365 邮件有强依赖的用户（当前不支持 OAuth）。
- 需要大规模多用户协作和复杂权限管理的企业环境。
- 希望快速部署且不熟悉 Docker 或 Python 环境的用户。

## 技术架构与依赖

- **后端**：Python 3.11+，FastAPI 框架。
- **前端**：静态 HTML/CSS/JavaScript，模块化设计。
- **数据库**：SQLite（默认），支持 PostgreSQL 等通过 `DATABASE_URL` 配置。
- **向量存储**：ChromaDB（用于记忆和 RAG）。
- **搜索**：SearXNG（元搜索）。
- **通知**：ntfy（自托管推送通知）。
- **模型服务**：支持 Ollama、vLLM、SGLang、llama.cpp 等。
- **部署**：Docker Compose 推荐，也支持原生安装（Linux/macOS/Windows）。

## 安装与快速开始

### Docker（推荐）

```bash
git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build
```

打开 `http://localhost:7000`，首次登录密码在 `docker compose logs odysseus` 中。

### 原生安装（Linux/macOS）

```bash
git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python setup.py
python -m uvicorn app:app --host 127.0.0.1 --port 7000
```

### Windows

使用 `launch-windows.ps1` 脚本或手动安装。

## 典型使用方法

- **配置模型**：在设置中添加 OpenAI 兼容端点或本地模型服务器（如 Ollama）。
- **创建智能体**：使用内置工具（文件、Shell、搜索）和技能。
- **深度研究**：启动多步骤研究任务，生成报告。
- **文档处理**：使用 AI 编辑、建议和格式转换。
- **邮件管理**：连接 IMAP/SMTP 账户，自动分类和摘要。
- **日历同步**：通过 CalDAV 同步日历和任务。

## 配置与部署要点

- **环境变量**：通过 `.env` 文件配置端口、认证、数据库等。
- **安全**：保持 `AUTH_ENABLED=true`，使用 HTTPS 反向代理，不暴露原始服务端口。
- **备份**：使用 `scripts/odysseus-backup` 工具备份 `data/` 目录。
- **GPU 支持**：Docker 需要配置 NVIDIA/AMD GPU 覆盖层。
- **HTTPS**：使用 mkcert 生成证书，配置反向代理。

## 限制、风险与许可证

- **限制**：不支持 Microsoft Outlook/Office 365 OAuth；Windows 原生安装未充分测试；Docker 中 ChromaDB 数据不在 `data/` 目录内，需单独备份。
- **风险**：自托管包含强大工具（Shell、文件访问），需严格管理认证和权限；备份包含敏感数据，需安全存储。
- **许可证**：AGPL-3.0-or-later。

## 官方链接

- GitHub 仓库：https://github.com/odysseus-dev/odysseus
- 设置指南：docs/setup.md
- 贡献指南：CONTRIBUTING.md
- 路线图：ROADMAP.md

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、CONTRIBUTING.md、docs/setup.md、docs/backup-restore.md、docs/email-outlook.md、docs/agent-migration.md、docs/attachments.md、docs/security-ci.md、docs/pr-blocker-audit.md。
- 分析时间：2026-05-12（基于仓库内容推断，实际分析时间未提供）。