内容
<p align="center">
<img src="docs/banner.png" alt="我的餐食 — 食谱，AI 餐食规划和智能购物清单" width="820">
</p>
<p align="center">
<a href="https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2FAmantux%2Fmymeal"><img src="https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg" alt="将插件仓库添加到我的 Home Assistant"></a>
<a href="https://my.home-assistant.io/redirect/hacs_repository/?owner=Amantux&repository=mymeal&category=integration"><img src="https://my.home-assistant.io/badges/hacs_repository.svg" alt="通过我的 Home Assistant 将集成添加到 HACS"></a>
</p>
<p align="center">
<sub><b>左侧：</b> 安装插件（运行 myMeal）。 <b>右侧：</b> 安装 HACS 集成（实体，日历，语音）。<br>
大多数人需要 <b>两者</b> — 参见 <a href="#home-assistant">Home Assistant</a>.</sub>
</p>
# 我的餐食
[](https://github.com/Amantux/mymeal/actions/workflows/ha-validate.yml)
[](https://github.com/Amantux/mymeal/actions/workflows/ci.yml)
[](https://hacs.xyz/docs/faq/custom_repositories)
[](https://www.home-assistant.io/addons/)
[](https://www.home-assistant.io/)
[](LICENSE)
**自托管的食谱，AI 餐食规划和智能购物清单 — 内置 Home Assistant 烹饪助手。**
myMeal 是一个注重隐私的自托管厨房伴侣。保留您的食谱集合，让 AI 帮助您规划一周的餐食和烹饪，跟踪您拥有的物品并生成合并的购物清单 — 所有这些都可以独立运行或作为具有语音控制的 Home Assistant 插件运行。
> **状态：** 所有五个里程碑已经交付 — 核心食谱管理，AI 食谱导入 + 可插件提供者，餐食规划，智能购物清单，交谈式烹饪代理，MCP 服务器和 Home Assistant 集成。参见 [更新日志](CHANGELOG.md)。
## 亮点（目标功能集）
- 📖 **食谱管理器** — 结构化的配料和步骤，图片，类别，标签，收藏夹，快速搜索。
- 🤖 **可插件 AI** — Claude，Ollama 或 OpenAI 在一个接口后面。 从 URL 或粘贴的文本导入食谱，询问“我可以用现有的东西烹饪什么”，并生成每周餐食计划。
- 🗓️ **餐食规划** — 一个也支持您日历的每周计划器。
- 🧺 **库存感知** — 连接配套 [Edibl](https://github.com/Amantux/edibl) 应用程序，获取按实际库存排序的建议。 myMeal 本身不存储任何食品；Edibl 拥有库存。
- 🛒 **智能购物清单** — 从您的计划中自动生成，去除重复项并按过道分组。
- 💬 **烹饪代理** — 与帮助您构建和烹饪食谱的助手聊天。
- 🔌 **Home Assistant 原生** — MCP 服务器向 Assist 公开工具，以便您可以询问“今晚吃什么？”并通过语音管理您的清单。
## 架构
```
backend/ Flask API（应用工厂，/api/v1），SQLAlchemy 模型，MCP 服务器
frontend/ Vue 3 + Vite SPA（由后端提供）
custom_components/ Home Assistant（HACS）集成 — 配置流程，传感器，日历，服务，卡片
mymeal/ Home Assistant 插件配置
Dockerfile 多阶段构建（前端 → Python 运行时）
```
后端提供 `/api/v1` 下的 JSON API 和构建的 SPA。默认情况下，身份验证为 JWT，或者在运行 Home Assistant ingress 时禁用（`MYMEAL_DISABLE_AUTH=true`），而 Home Assistant ingress 已经对用户进行了身份验证。
## 运行
### Docker（独立）
```bash
docker compose up --build
# → http://localhost:7850
```
在 `docker-compose.yml` 中设置一个强大的 `MYMEAL_SECRET_KEY`，然后再公开它。
### 本地开发
```bash
# 后端
cd backend
pip install -r requirements.txt
python run.py # http://localhost:7850
# 前端（独立终端，代理 /api 到 :7850）
cd frontend
npm install
npm run dev # http://localhost:5173
```
## Home Assistant
myMeal 提供了 **两个独立的安装路径**。它们是互补的，而不是替代品 — 插件运行应用程序，集成将其作为实体公开。
### 路径 1 — 插件（在 HA 中运行 myMeal）
[](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2FAmantux%2Fmymeal)
单击一次将仓库添加到您的 Home Assistant。然后安装 **myMeal** 并单击 **打开 Web UI**。
<details>
<summary>手动替代</summary>
**设置 → 插件 → 插件商店 → ⋮ → 仓库 → 添加**
```
https://github.com/Amantux/mymeal
```
</details>
**您不会被要求登录。** 已启用 ingress（`ingress: true`，`ingress_port: 7850`），插件默认自带 `disable_auth: true`：Home Assistant 已经在 ingress 层对您进行了身份验证，因此第二次登录将是纯粹的摩擦。前端直接询问后端（`GET /api/v1/misc/auth-mode`）是否需要登录，而不是推断，因此暂时的错误永远不会将您跳转到 HA 内的登录屏幕。MCP 服务器在端口 `7851` 上公开给 Home Assistant MCP 客户端。
> 在 HA **外部** 运行 myMeal？身份验证保持完整 — `disable_auth` 仅在插件中翻转。永远不要在不受信任的网络可访问的任何设备上设置 `MYMEAL_DISABLE_AUTH=true`：它将每个请求绑定到一个本地用户。
### 路径 2 — HACS 集成（实体，日历，语音）
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=Amantux&repository=mymeal&category=integration)
单击一次即可在 HACS 中打开它（需要已安装 HACS）。然后 **下载** → 重启 HA → **设置 → 设备和服务 → 添加集成 → myMeal**。
<details>
<summary>手动替代</summary>
**HACS → ⋮ → 自定义仓库** → 添加 `https://github.com/Amantux/mymeal`，分类为 **集成**，然后下载它。
</details>
如果您安装了插件，它将通过 Supervisor 发现进行广告，集成应该提供配置自身，无需输入 URL 或令牌。
您将获得：
| 类型 | 内容 |
|---|---|
| 传感器 | 今日餐食，购物清单数量 |
| 日历 | 您的餐食计划作为原生 HA 日历实体 |
| 服务 | `add_to_shopping_list`，`plan_week`，`whats_for_dinner` |
| 语音 | Assist 语句 — *"今晚吃什么？"*， *"将牛奶添加到我的购物清单中"* |
| Lovelace | `mymeal-card.js` 仪表盘卡片 |
### 待完成的外部步骤
这些需要在此仓库外部采取行动，并且 **未完成**：
- **品牌图标** — `mymeal` 域名尚未在 [home-assistant/brands](https://github.com/home-assistant/brands) 中注册，因此 HA 显示一个通用图标。需要对该上游仓库的 PR；`brands` 检查在 `ha-validate.yml` 中被显式忽略，而不是静默通过。
- **默认 HACS 列表** — myMeal 作为 *自定义仓库* 安装。包含在默认 HACS 商店中是单独向 HACS 申请的。
## 配置
所有配置均通过 `MYMEAL_` 前缀的环境变量进行：
| 变量 | 默认值 | 目的 |
|---|---|---|
| `MYMEAL_SECRET_KEY` | `change-me…` | JWT 签名密钥（在生产环境中设置） |
| `MYMEAL_DISABLE_AUTH` | `false` | 在受信任的代理 / HA ingress 后面单租户模式 |
| `MYMEAL_ALLOW_REGISTRATION` | `true` | 允许公开注册 |
| `MYMEAL_DATA_DIR` | `./data` | SQLite 数据库 + 上传的图片 |
| `MYMEAL_PORT` | `7850` | HTTP 端口 |
| `MYMEAL_AI_PROVIDER` | _(blank)_ | `claude` \| `ollama` \| `openai`（AI 功能） |
## 开发
```bash
cd backend && ruff check . && pytest -q # 校验 + 测试
cd frontend && npm run build # 类型/构建检查
```
## 许可证
[AGPL-3.0](LICENSE)。（myMeal 是原始的、干净的软件；许可证选择反映了项目所有者的其他自托管工具，可以更改。）
