内容
# Elly（后端）
本仓库是 **开源后端**，用于 Elly —— 一个自我托管、LLM 增强的笔记本 + 日记 + 日历 + 习惯伴侣，旨在围绕多动症（ADHD）大脑的实际工作方式而设计，而非通用的生产力应用假设。
**本仓库仅包含领域逻辑、MCP 服务器和 REST API —— 这里没有捆绑的 Web UI。** 它本身是完全可用的（通过 REST API 或作为 OpenCode/Claude Desktop 的 MCP 服务器），并且它是完整产品（仪表盘 PWA + 一键安装程序，适用于 macOS/Windows/Linux）的开源基础。
## 为什么选择这个后端
- **真正本地优先。** SQLite 存储在您自己的磁盘上，无需账户，无需云同步。 它建立的唯一网络连接是 LLM API 调用本身（可选 - 通过 Ollama 指向一个完全本地的模型）以及（如果您启用它）用于远程访问的 Telegram 服务器。
- **安全被视为头等功能，而非事后补充。** 本地访问令牌控制每个路由，请求受到速率限制和验证，您的日记/聊天/记忆内容在静止时加密，并且完整的安全威胁模型被记录在 [`SECURITY.md`](./SECURITY.md) 中 - 包括尚未保护的内容，而不仅仅是已经保护的内容。
- **LLM 可以真正行动，而不仅仅是聊天。** 与对话式使用和直接 API/领域调用的工具调用完全对等 - 创建/重新安排事件，将模糊的任务分解为微小的具体步骤，记录习惯，记住偏好以供日后使用。破坏性操作（删除笔记、任务、事件或习惯）始终需要明确确认。
- **围绕多动症（ADHD）实际工作方式构建，而非通用生产力智慧：** 宽容的连续记录（错过一天不会将进度重置为零），微小步骤的任务分解，具体外部时间而非模糊的提醒，并且没有任何羞耻感的文案 - 参见 [`CONTRIBUTING.md`](./CONTRIBUTING.md) 的设计原则。
- **通过 Telegram 进行远程访问，而非通过向网络暴露任何内容。** 记录习惯或脑暴任务从您的手机，即使您的机器正在睡眠 - 消息队列会在下次启动时处理。
**许可证：** [AGPL-3.0](./LICENSE) - 免费自我托管、运行和修改；如果您将修改后的版本作为公共网络服务运行，则必须向用户提供修改后的源代码。 参见 [`CONTRIBUTING.md`](./CONTRIBUTING.md) 以了解如何帮助构建它。
## 它是如何构建的
- **数据：** SQLite，默认存储在 macOS 上的 `~/Library/Application Support/Elly/elly.db`（可通过 `ELLY_DATA_DIR` 配置）- 故意 *不* 存储在云同步文件夹中，因为实时 SQLite 文件在同步时可能会损坏。 日记/笔记本内容、记住的事实和聊天历史在静止时加密（字段级别，通过 `cryptography` 的 Fernet - 参见 `SECURITY.md` 以了解确切的覆盖范围和为什么不使用整个数据库的 SQLCipher）。
- **领域层** (`server/src/elly_server/domain/`): 业务逻辑的单一事实来源（笔记/日记、日历、任务、习惯、洞察、记忆、预算）。 MCP 服务器、REST API 和 Telegram 机器人都调用这些相同的函数，因此它们永远不会出现不同步的情况。
- **MCP 服务器** (`server/src/elly_server/mcp_server/`): 将领域层公开为 MCP 工具/资源/提示，供 OpenCode/Claude Desktop 使用。
- **REST API** (`server/src/elly_server/api/`): 领域函数的 FastAPI 层。 除健康检查和一次性令牌验证外，每个路由都需要本地访问令牌 - 参见 `SECURITY.md`。
- **Telegram 机器人** (`server/src/elly_server/telegram_bot/`): 可选 - 通过 `ELLY_TELEGRAM_BOT_TOKEN`（或 REST API）配置机器人令牌，自动生成和管理为 `elly-api` 的子进程。 与单个聊天配对，通过一次性代码 - 绝不会使用硬编码的聊天 ID。 相同的领域层，相同的聊天/LLM 工具调用循环。
- **仅有的网络连接是 LLM API 调用本身**（如果您通过 Ollama 运行完全本地的模型，则可选）**和（仅当您启用它时）Telegram 服务器**用于远程访问机器人。 所有其他内容都在 `127.0.0.1` 上运行。
## 运行它
```sh
cd server
cp .env.example .env # 如果您想要基于云的聊天，请填写 OPENAI_API_KEY
uv sync
uv run elly-mcp # 标准输入输出 MCP 服务器，供 OpenCode/Claude Desktop 使用
uv run elly-api # REST API 在 http://127.0.0.1:8765 上
```
`elly-api` 在第一次运行时的终端中打印本地访问令牌 - 除健康检查和一次性令牌检查外的每个路由都需要它（参见 `SECURITY.md` 了解原因）。 从那里，您可以选择 LLM 提供商 - 云（OpenAI，需要上述 API 密钥）或通过 [Ollama](https://ollama.com) 的完全本地模型（零数据离开您的机器）- 通过 REST API 的设置端点。
`elly-mcp` 直接与 OpenCode/Claude Desktop 配合使用 - 将您的 MCP 客户端配置的 `command`/`cwd` 指向此代码库，`elly` 工具将自动在对话中可用。
尝试以下提示：
- “记录我喝了水” / “我的喝水记录怎么样？”
- “记录我花了 12 美元吃午饭” / “这个月我花了多少钱买杂货？”
- “开始我的早晨计划”（使用 `morning_planning` MCP 提示）
参见 `server/README.md` 以获取完整的源代码布局和环境变量覆盖。
## 测试
```sh
cd server && uv run pytest
cd server && uv run ruff check src/
```
每次推送后在 CI 上运行（`.github/workflows/ci.yml`）。
## 数据模型
`Note`（笔记本 + 日记，统一）· `Event`（日历）· `Task`（+ AI 分解为子任务）· `Habit` / `HabitLog`（宽容的连续记录 - 错过一天不会将进度重置为零）· `BudgetEntry`（收入/支出，一次性或定期）· `Memory`（记住的事实/目标/偏好）· `AppSettings`（LLM 提供商选择，货币，加密的 Telegram 机器人令牌）· `TelegramLink` / `InboundTelegramMessage`（配对 + 离线消息持久性）。
## 想要完整的应用程序吗？
本仓库仅是后端。 完整的产品 - 仪表盘 PWA，应用内聊天和一键安装程序，适用于 macOS/Windows/Linux - 建立在此相同的开源基础上，并单独分发。
## 贡献
欢迎提交错误报告，功能想法和 PR - 参见 [`CONTRIBUTING.md`](./CONTRIBUTING.md) 以了解项目组织方式以及在打开 PR 之前需要了解的内容。 请同时阅读 [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)。 发现安全问题？ 参见 [`SECURITY.md`](./SECURITY.md) 以了解如何私下报告它。
