内容
# McOracle · 麦门神谕
> **不要问 AI，问薯条。**
McOracle 是一个**纯 Skill 形态**的 AI 神谕体验：向它提出任何问题，它会从 104 条原创神谕中**真随机**抽取一条答案，包装成一份「麦门启示录」，再通过**麦当劳中国官方 MCP** 查询真实门店、可售菜单与价格，推荐「今日必点」，并生成一张酒红金色的神秘命运卡。用户明确确认后，可继续进入订单流程。
<sub>示例卡：神谕 NO.021「别在深夜做决定。」· 今日必点 板烧鸡腿堡三件套 · ¥34.50（经 MCP 实时核实）· 1200×1600 PNG</sub>
**命运可以随机，价格必须真实。**
- 神谕从原创库真随机抽取，不由模型即兴编造；
- 商品、价格、门店全部来自真实 MCP 返回，绝不编造；
- 价格未经核实只显示「价格未核实」；
- **用户明确确认前，绝不创建订单；创建订单 ≠ 支付成功。**
---
## 目录
- [项目演示](#项目演示)
- [核心功能与架构](#核心功能与架构)
- [项目目录结构](#项目目录结构)
- [环境要求与依赖安装](#环境要求与依赖安装)
- [安装为 WorkBuddy Skill](#安装为-workbuddy-skill)
- [麦当劳中国 MCP 配置](#麦当劳中国-mcp-配置)
- [图片生成与本地模板回退](#图片生成与本地模板回退)
- [使用示例](#使用示例)
- [常见问题](#常见问题)
- [测试](#测试)
- [能力现状：已验证 / 未验证 / 已知限制](#能力现状已验证--未验证--已知限制)
- [安全、隐私、品牌与免责声明](#安全隐私品牌与免责声明)
- [许可证与贡献](#许可证与贡献)
---
## 项目演示
McOracle 的完整链路：**提问 → 抽取神谕 → 查询真实菜单 → 核实价格 → 生成命运卡 → （用户确认后）下单**。
```
用户：「今天适合辞职吗？」
│
▼ ① 真随机抽取（scripts/draw-oracle.py，secrets 模块）
神谕 NO.021「别在深夜做决定。」
+ 趣味解读「凌晨一点的你和上午十点的你，不是同一个人。」
+ 行动提示 + 重大事项提醒
│
▼ ② 查询真实门店与菜单（MCP：query-nearby-stores / query-meals）
麦当劳深圳松岗沙江路餐厅 · 100+ 可售 SKU
│
▼ ③ 核实价格（MCP：calculate-price，单位：分）
今日必点：板烧鸡腿堡三件套 —— ¥34.50（MCP 实时核实，无优惠）
│
▼ ④ 生成命运卡（scripts/generate-card.py，固定酒红金模板 + 官方商品图）
examples/oracle-card-NO021-official.png（1200×1600）
│
▼ ⑤ 用户明确「确认下单」→ 复核价格 → create-order → 官方支付入口
```
只问神谕、不想要推荐时，流程到 ① 即止，**不会**强迫提供位置或调用 MCP。
---
## 核心功能与架构
| 模块 | 文件 | 职责 |
|---|---|---|
| **Oracle Engine** | `scripts/draw-oracle.py` + `references/oracle-library.json` | 104 条原创神谕真随机抽取、本轮锁定、重抽控制（`--question` / `--redraw` / `--peek`） |
| **Recommendation Engine** | `references/recommendation-rules.md` | 神谕标签 → 餐品方向映射，结合真实菜单与预算给出首选 + 备选 |
| **MCP Adapter** | `SKILL.md` + `MCP_INTEGRATION.md` | 调用麦当劳中国官方 MCP 查询门店、菜单、详情、价格与订单 |
| **Card Generator** | `scripts/generate-card.py` | 固定酒红金模板 + 官方商品图合成 + Pillow 程序排版，输出 1200×1600 PNG |
| **Order Safety Controller** | `scripts/validate-order.py` | 订单状态机与确认铁律，参数变化使确认失效 |
| **Skill Orchestrator** | `SKILL.md` | 定义触发条件、执行顺序、工具规则、异常处理与输出格式 |
### 神谕库
- **104 条原创中文神谕**，覆盖 8 大分类：
| 分类 | 键 | 条数 |
|---|---|---|
| 肯定型 | `affirmative` | 11 |
| 否定型 | `negative` | 12 |
| 等待型 | `waiting` | 13 |
| 行动型 | `action` | 13 |
| 反转型 | `reversal` | 12 |
| 好运型 | `lucky` | 13 |
| 幽默型 | `humor` | 13 |
| 麦门专属型 | `mcm` | 17 |
- 每条包含：`id` / `answer` / `category` / `tags` / `interpretation` / `action_hint` / `recommendation_tags` / `visual_theme`。
- 抽取使用 Python `secrets` 模块真随机，抽取结果锁定到 `_oracle_state.json`，同一轮的解释、卡片、推荐引用**同一条**神谕；只有用户要求重抽才会更换。
- 文案为本项目原创，不照搬任何受版权保护的《答案之书》内容。
### 命运卡（正式视觉）
固定「简洁神秘」风格，每次神谕**只输出一张**：
- 深酒红渐变背景 + 金色双层边框 + 中央发光圆环 + 少量金色星点星芒；
- 圆环中央为**真实餐品主体**（优先官方商品图，严禁用空圆环冒充）；
- 顶部 `McORACLE` / `麦门神谕`，中部神谕编号 + 大字号神谕正文 + 解读；
- 底部「今日必点」商品名 + 经核实价格（或「价格未核实」）+ 标语「命运可以随机，价格必须真实。」
- **全程程序排版**，中文、编号、价格准确不溢出、不依赖图像模型绘字；
- 输出尺寸 **1200×1600（3:4）**。
---
## 项目目录结构
```
McOracle/
├── SKILL.md # Skill 编排主文档（触发条件/执行流程/工具规则/异常处理）
├── README.md # 本文件
├── MCP_INTEGRATION.md # MCP 集成说明与实测记录
├── references/ # 规则与数据
│ ├── oracle-library.json # 104 条原创神谕（唯一数据源）
│ ├── oracle-rules.md
│ ├── recommendation-rules.md
│ ├── image-design.md
│ └── order-safety.md
├── assets/
│ ├── oracle-card-template.svg # 正式卡模板的矢量参考
│ └── products/ # MCP 官方商品图缓存（运行时自动生成）
├── scripts/
│ ├── draw-oracle.py # 神谕抽取 + 状态锁定
│ ├── generate-card.py # 命运卡合成与排版
│ └── validate-order.py # 订单安全状态机（纯逻辑）
├── tests/
│ ├── test-oracle.py # 神谕库 / 随机性 / 状态锁定
│ ├── test-card.py # 命运卡真实生成与降级路径
│ └── test-order-safety.py # 订单安全铁律（Mock，绝不真实下单）
└── examples/
├── oracle-card-NO021-official.png # 正式模板示例（README 首图）
├── oracle-card-NO013-official.png # 正式模板示例
├── oracle-demo.md # 一次完整神谕交互记录
└── order-flow-demo.md # 下单安全流程演示
```
---
## 环境要求与依赖安装
- **Python** 3.9+（开发环境使用 3.13）
- **Pillow**（仅命运卡生成需要）
- 可选：**WorkBuddy 桌面版** + 麦当劳中国官方 MCP（`mcd-mcp`）
- 图像生成能力：**正式出卡不需要**（模板为程序化绘制）
```bash
pip install Pillow
```
Mac / Linux 中文字体请确保系统存在（开发环境使用 Windows 的微软雅黑 / 楷体等）。脚本会自动按候选列表选择可用中文字体。
---
## 安装为 WorkBuddy Skill
1. **获取代码**
```bash
git clone <your-repo-url> McOracle
cd McOracle
pip install Pillow
```
2. **放入 Skill 目录**（二选一）
- 用户级（对本机所有项目生效）：复制 `McOracle/` 到 `~/.workbuddy/skills/McOracle/`
- 项目级（仅当前工作区）：复制到 `{workspace}/.workbuddy/skills/McOracle/`
3. **配置麦当劳中国 MCP**（见下一节），并在 WorkBuddy 连接器中**启用**。
4. **在对话中触发**
- 「麦门神谕」「抽一签」「今日神谕」「再抽一签」
- 「我该不该辞职？」（任意问题，神谕式回答）
- 「我想要完整的今日麦门命运」（神谕 + 真实推荐 + 命运卡）
- 流程中说「准备下单」→（我展示订单摘要）→ 你回复「确认下单」
> 说明：脚本可独立运行，不依赖 Skill 加载（见「使用示例」）。SKILL.md 已按官方赛事要求命名；若你的 WorkBuddy 版本要求 Skill 注册元数据，请按本地版本要求补齐（详见「能力现状」）。
---
## 麦当劳中国 MCP 配置
MCP 由赛事官方提供，需先在官方控制台申请 Token（参见
[官方 MCP 使用指南](https://github.com/M-China/mcd-mcp-server)）。在 WorkBuddy 的
【连接器】→【自定义连接器】→【配置 MCP】中填入：
```json
{
"mcpServers": {
"mcd-mcp": {
"type": "streamablehttp",
"url": "https://mcp.mcd.cn",
"headers": {
"Authorization": "Bearer YOUR_MCP_TOKEN"
}
}
}
}
```
> ⚠️ 请将 `YOUR_MCP_TOKEN` 替换为你自己的 Token，并妥善保管，**不要提交到仓库**。
本项目调用的工具（名称与参数以实际 Schema 为准）：
| 工具 | 用途 | 状态 |
|---|---|---|
| `now-time-info` | 服务端时间 / 时段判断 | ✅ 已实测 |
| `query-nearby-stores` | 到店 / 得来速门店查询 | ✅ 已实测 |
| `query-meals` | 门店真实可售菜单（含官方商品图 URL） | ✅ 已实测 |
| `query-meal-detail` | 餐品组成与规格 / 特调 | ✅ 已实测 |
| `calculate-price` | 价格 / 优惠 / 总价核实（单位：**分**） | ✅ 已实测 |
| `create-order` | 创建订单（**仅用户明确确认后**） | Schema 已核实；端到端支付流程见下文说明 |
| `query-order` | 订单状态查询 | Schema 已核实，未实测 |
| `query-my-coupons` / `query-store-coupons` | 优惠券 | Schema 已核实，未实测 |
| `delivery-*`（麦乐送） | 外送链路 | 流程已设计，未实测 |
详见 [MCP_INTEGRATION.md](MCP_INTEGRATION.md)。
---
## 图片生成与本地模板回退
正式视觉为**固定程序化模板**，不依赖任何图像生成 API：
1. **模板背景**：`generate-card.py` 内置绘制（深酒红渐变 + 金色双层边框 + 中央发光圆环 + 星点星芒），风格永远一致，且**永远不会失败**。
2. **餐品主体**：按优先级解析——
- **官方商品图（首选，零成本）**：`query-meals` / `query-meal-detail` 返回的 `image` 字段（`menu-img.mcd.cn`），传 `--item-image-url`，脚本自动下载、验证并缓存；
- **独立概念插画**：无官方图时用 `--item-image`，卡片如实标注「概念插画」，**不冒充官方实拍**；
- **程序概念插画（兜底）**：脚本内置绘制汉堡 + 薯条 + 可乐，**绝不用空圆环冒充餐品**；
- **全部不可用**：输出「餐品视觉素材缺失」降级卡，**退出码 2、JSON `ok=false`**，如实报告，绝不谎报成功。
3. **预览模式**：`--preview --background <AI背景图>` 仅用于风格对比实验，非正式输出。
---
## 使用示例
### 脚本独立运行
```bash
# 抽取神谕（结果锁定到 scripts/_oracle_state.json）
python scripts/draw-oracle.py --question "今天吃什么？"
# 查看当前锁定神谕 / 重新抽取
python scripts/draw-oracle.py --peek
python scripts/draw-oracle.py --redraw
```
```bash
# 生成命运卡（正式输出：固定模板 + 官方商品图）
# --price-verified 仅在价格经 calculate-price 核实后使用
python scripts/generate-card.py \
--oracle-id "NO.021" \
--answer "别在深夜做决定。" \
--interpretation "凌晨一点的你和上午十点的你，不是同一个人。" \
--item-name "板烧鸡腿堡三件套" --item-price 34.5 --price-verified \
--item-image-url "https://menu-img.mcd.cn/.../MS_9900005462_320.png" \
--out examples/oracle-card-NO021-official.png
```
```bash
# 订单安全控制器演示（纯逻辑 Mock，不创建真实订单）
python scripts/validate-order.py demo
```
### 在对话中使用
```
你：麦门神谕，今天适合辞职吗？
McOracle：（真随机抽中 NO.021）别在深夜做决定。 + 解读 + 行动提示 + 重大事项提醒
今日必点：板烧鸡腿堡三件套 ¥34.50（MCP 实时核实） + 命运卡 PNG
你：准备下单
McOracle：展示订单草稿摘要（门店 / 取餐方式 / 商品 / 价格）→ 请你确认门店与取餐方式
（此时不会创建任何订单）
你：确认下单
McOracle：复核价格 → create-order → 返回真实订单号与官方支付入口
（提醒：创建订单 ≠ 支付成功，不会自动支付）
```
---
## 常见问题
**Q：它会自己下单扣钱吗？**
不会。只有你明确回复「确认下单」后才会调用下单工具；「看看」「推荐一下」「准备下单」都不算确认。创建订单后仍需你在官方页面自行支付，**不会自动支付**。
**Q：价格和麦当劳 App 不一样？**
以门店**实时**查询结果为准；卡片与对话会标注核实时间。未核实的价格一律显示「价格未核实」，绝不显示示例价冒充实时价。
**Q：神谕是预测未来吗？**
不是。神谕仅供娱乐与启发，不构成任何现实决策依据。涉及辞职、投资、健康、法律等重大事项时，会附加「请结合现实条件独立判断」的提醒。
**Q：没有配置 MCP 还能用吗？**
能。神谕与（无商品版）命运卡可正常使用；商品推荐会降级并如实标注「价格未核实」，不会编造餐品。
**Q：需要图像生成 API Key 吗？**
不需要。正式出卡为程序排版；即使配置了图像 API，Key 也只从环境变量读取，绝不写入仓库。
**Q：中文会乱码或溢出吗？**
不会。命运卡所有文字由 Pillow 程序排版，自动换行 / 自动缩字号；价格使用含 `¥` 字形的字体。
---
## 测试
```bash
python tests/test-oracle.py # 神谕库 / 随机性 / 状态锁定（Mock）
python tests/test-card.py # 命运卡真实生成与降级路径（本地真实图片）
python tests/test-order-safety.py # 订单安全状态机（Mock，绝不真实下单）
```
**当前实际结果：24 / 24 全部通过**（三套退出码均为 0）：
| 测试 | 项数 | 结果 | 覆盖要点 |
|---|---|---|---|
| `test-oracle.py` | 6 | ✅ | 加载 104 条、编号唯一、8 分类齐全、200 次抽取随机性、状态锁定与重抽控制 |
| `test-card.py` | 9 | ✅ | 正式模板默认出卡、1200×1600、餐品进入圆环（像素级校验）、单卡输出、预览需显式开关、素材缺失降级（`ok=false` 退出码 2）、未核实价格分支、动态内容非硬编码、超长文本不溢出 |
| `test-order-safety.py` | 9 | ✅ | 未确认不得下单、「看看/推荐一下/准备下单/先不/算了」均不算确认、价格与商品变化使确认失效、无真实订单号不得标记下单成功、创建订单 ≠ 支付成功、非法状态转移被拒 |
> 说明：`test-oracle.py` 与 `test-order-safety.py` 为**纯逻辑（Mock）测试**，不调用任何 MCP 工具、不创建真实订单；`test-card.py` 在本地产出真实 PNG 用于校验（不依赖网络）。
---
## 能力现状：已验证 / 未验证 / 已知限制
### ✅ 已真实验证（真实 MCP 调用 + 真实文件产出）
- 门店查询、真实菜单、餐品详情与特调、价格计算（含优惠与取餐方式）；
- 官方商品图 URL 可真实下载并验证（`menu-img.mcd.cn`，HTTP 200）；
- 命运卡 1200×1600 PNG 真实生成（正式模板 + 官方商品图合成）；
- 餐品素材缺失时的降级路径（不静默失败）；
- 订单安全状态机（Mock）。
### ⚠️ 未完成端到端验证 / 未实测
- **完整「下单 → 支付 → 状态回查」流程尚未作为闭环验证**：`create-order` 的 Schema 已核实，接口已在真实会话中实测调用并返回订单（状态「待支付」），但**支付环节未执行、`query-order` 状态回查未验证**，因此本项目**不声明端到端下单 / 支付流程已通过验证**。
- 麦乐送（外送）链路（`delivery-query-stores`、地址、运费）未实测。
- 优惠券领取与核销路径未完整实测。
- 官方商品图无法覆盖时的概念插画实际观感（降级路径与测试已覆盖）。
### 已知限制
- 到店自取与得来速走 `orderType=1`，外送走 `orderType=2`（需配送地址），两类参数不可混用；
- 价格单位为「分」，展示前需 ÷100，且具有时效性；
- Skill 自动加载与注册元数据依赖 WorkBuddy 版本，请按本地版本要求核对（见下）。
---
## 安全、隐私、品牌与免责声明
### 安全与隐私
- 未确认绝不创建订单；商品 / 数量 / 门店 / 价格 / 取餐方式任一变化都会使旧确认失效，必须重新展示摘要并再次确认；
- 不自动支付；不伪造订单号或下单成功消息；异常如实反馈；
- 不编造商品、价格、优惠、库存、门店；无实时数据时标注「价格未核实」；
- 不收集、不存储用户隐私；仓库内不含 Token、Cookie、订单号或个人凭据；
- Token / API Key 仅通过环境变量或连接器配置读取，绝不写入源码或仓库。
### 品牌与免责声明
- 本项目为**麦当劳中国开发者创新挑战赛**参赛作品，**非麦当劳官方产品**，与麦当劳官方无隶属关系，不暗示任何官方背书；
- 「麦当劳」「McDonald's」及相关商标、商品图片归其各自权利人所有；本项目仅通过**官方 MCP 接口**调用其服务；
- 餐品、价格、供应状态以麦当劳官方渠道**实时结果**为准；
- **神谕内容为娱乐与启发用途，不构成任何预测、建议或决策依据**；涉及重大人生、医疗、法律、财务决策请咨询专业人士。
---
## 许可证与贡献
- 本项目仅用于学习与技术演示。神谕文案为本项目原创。
- 使用本项目即表示你同意自行遵守麦当劳《MCP 服务规则》与《使用条款》，并自行申请与管理 MCP Token。
- Issue / PR 欢迎，但请勿在提交内容中包含 Token、订单号或个人敏感信息。
### 参赛文件清单（依据官方赛事要求）
| 文件 | 说明 | 状态 |
|---|---|---|
| `README.md` | 项目介绍、安装、示例、目标用户 | ✅ 本文件 |
| `CONTEST_DECLARATION.md` | 参赛声明（官方原件，**文件名与内容均不可改动**） | ⚠️ **缺失，需从官方仓库原样获取** |
| `MCP_INTEGRATION.md` | 实际使用的 MCP Server / Tool / 调用流程 / 业务价值 | ✅ 已提供 |
| 源代码 | 项目主体 | ✅ 已提供 |
| `workbuddy.md` | WorkBuddy 开发对话上下文（参加 WorkBuddy 专项奖励时必交） | ⚠️ 未提供（可选） |
> `CONTEST_DECLARATION.md` 必须从官方仓库原样复制，不得自行改写：
> <https://github.com/M-China/mcd-developer-innovation-challenge/blob/main/CONTEST_DECLARATION.md>
连接信息
猜你喜欢
暂无推荐服务器