spideymooon/McOracle

McOracle · 麦门神谕

不要问 AI，问薯条。

McOracle 是一个纯 Skill 形态的 AI 神谕体验：向它提出任何问题，它会从 104 条原创神谕中真随机抽取一条答案，包装成一份「麦门启示录」，再通过麦当劳中国官方 MCP 查询真实门店、可售菜单与价格，推荐「今日必点」，并生成一张酒红金色的神秘命运卡。用户明确确认后，可继续进入订单流程。

_{示例卡：神谕 NO.021「别在深夜做决定。」· 今日必点 板烧鸡腿堡三件套 · ¥34.50（经 MCP 实时核实）· 1200×1600 PNG}

命运可以随机，价格必须真实。

• 神谕从原创库真随机抽取，不由模型即兴编造；
• 商品、价格、门店全部来自真实 MCP 返回，绝不编造；
• 价格未经核实只显示「价格未核实」；
• 用户明确确认前，绝不创建订单；创建订单 ≠ 支付成功。

---

目录

• 项目演示
• 核心功能与架构
• 项目目录结构
• 环境要求与依赖安装
• 安装为 WorkBuddy Skill
• 麦当劳中国 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）
• 图像生成能力：正式出卡不需要（模板为程序化绘制）

pip install Pillow

Mac / Linux 中文字体请确保系统存在（开发环境使用 Windows 的微软雅黑 / 楷体等）。脚本会自动按候选列表选择可用中文字体。

---

安装为 WorkBuddy Skill

1. 获取代码

git clone  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 使用指南）。在 WorkBuddy 的 【连接器】→【自定义连接器】→【配置 MCP】中填入：

{
  "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。

---

图片生成与本地模板回退

正式视觉为固定程序化模板，不依赖任何图像生成 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背景图> 仅用于风格对比实验，非正式输出。

---

使用示例

脚本独立运行

# 抽取神谕（结果锁定到 scripts/_oracle_state.json）
python scripts/draw-oracle.py --question "今天吃什么？"
查看当前锁定神谕 / 重新抽取
python scripts/draw-oracle.py --peek
python scripts/draw-oracle.py --redraw

# 生成命运卡（正式输出：固定模板 + 官方商品图）
--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

# 订单安全控制器演示（纯逻辑 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 程序排版，自动换行 / 自动缩字号；价格使用含 ¥ 字形的字体。

---

测试

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 必须从官方仓库原样复制，不得自行改写：