跳到主要内容
AI教程

McOracle 麦门神谕教程：从随机神谕到真实菜单推荐与安全下单

本文将介绍 McOracle 的工作原理、Python 环境安装、WorkBuddy Skill 配置、麦当劳中国 MCP 接入、命运卡生成、脚本使用、测试与订单安全机制。

AI我搜编辑部阅读约 11 分钟
McOracle 麦门神谕教程：从随机神谕到真实菜单推荐与安全下单

McOracle 是什么

McOracle（麦门神谕）是一个纯 Skill 形态的 AI 神谕体验。用户可以提出任意问题，系统从 104 条原创中文神谕中使用 Python secrets 模块真随机抽取一条答案，再结合麦当劳中国官方 MCP 查询真实门店、可售菜单和价格，生成一份「麦门启示录」与命运卡。

项目的核心原则是：神谕可以随机，商品和价格必须真实。神谕来自仓库中的固定数据，不由模型临时编造；餐品、门店和价格只使用 MCP 返回的数据；价格未核实时显示「价格未核实」。在用户明确确认前，系统不会创建订单，创建订单也不等于支付成功。

完整工作流程

McOracle 的标准链路包括五个阶段：

  1. 用户提出问题，或直接请求麦门神谕。
  2. scripts/draw-oracle.py 从 references/oracle-library.json 中真随机抽取神谕，并将本轮结果锁定。
  3. 如果用户需要餐品推荐，Skill 通过 MCP 查询附近门店、可售菜单和餐品详情。
  4. 通过 calculate-price 核实价格，再使用 scripts/generate-card.py 生成 1200×1600 PNG 命运卡。
  5. 只有用户明确回复「确认下单」后，系统才会复核订单信息并调用 create-order。之后仍需用户通过官方入口自行支付。

如果用户只想抽取神谕，流程会在第一阶段结束，不会强制索取位置，也不会调用 MCP。

核心模块与项目结构

项目主要由以下模块组成：

  • Oracle Engine：draw-oracle.py 与神谕库负责随机抽取、结果锁定和重抽控制。
  • Recommendation Engine：recommendation-rules.md 将神谕标签映射为餐品方向，并结合真实菜单与预算给出推荐。
  • MCP Adapter：SKILL.md 与 MCP_INTEGRATION.md 描述工具调用顺序、参数规则和异常处理。
  • Card Generator：generate-card.py 使用 Pillow 程序化绘制酒红金模板，并合成官方商品图。
  • Order Safety Controller：validate-order.py 通过状态机控制确认流程，防止未确认下单。
  • Skill Orchestrator：SKILL.md 定义触发条件、执行流程、输出格式和安全要求。

神谕库包含 104 条原创内容，覆盖肯定型、否定型、等待型、行动型、反转型、好运型、幽默型和麦门专属型八大分类。每条神谕包含编号、正文、分类、标签、解读、行动提示、推荐标签和视觉主题。

安装 Python 依赖

项目要求 Python 3.9 或更高版本。开发环境使用 Python 3.13。正式命运卡由 Pillow 程序排版，因此需要安装 Pillow；神谕抽取和订单安全脚本本身不依赖图像生成 API。

git clone <your-repo-url> McOracle
cd McOracle
pip install Pillow

如果在 macOS 或 Linux 上运行，请确认系统中存在可显示中文的字体。脚本会按照候选列表选择可用字体。正式出卡不需要配置图像生成 API Key。

安装为 WorkBuddy Skill

  1. 获取项目并安装依赖。
  2. 将整个 McOracle/ 目录复制到用户级 Skill 目录 ~/.workbuddy/skills/McOracle/，或复制到当前工作区的 {workspace}/.workbuddy/skills/McOracle/。
  3. 在 WorkBuddy 的连接器中启用麦当劳中国 MCP。
  4. 打开对话，使用「麦门神谕」「抽一签」「今日神谕」等表达触发 Skill。

也可以直接提出普通问题，例如「我该不该辞职？」。如果希望执行完整链路，可以说「我想要完整的今日麦门命运」。不同 WorkBuddy 版本对 Skill 注册元数据的要求可能不同，应根据本地版本补充相应配置。

配置麦当劳中国官方 MCP

使用真实门店、菜单和价格推荐前，需要从官方 MCP 使用指南了解申请 Token 的方式，并在 WorkBuddy 的「连接器」→「自定义连接器」→「配置 MCP」中填写配置。

{
  "mcpServers": {
    "mcd-mcp": {
      "type": "streamablehttp",
      "url": "https://mcp.mcd.cn",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

请将 YOUR_MCP_TOKEN 替换为自己的 Token，并且不要把 Token 提交到仓库。项目涉及的主要工具包括 now-time-info、query-nearby-stores、query-meals、query-meal-detail 和 calculate-price。下单相关的 create-order 只有在用户明确确认后才能调用。

第一次使用：抽取神谕

在项目根目录执行以下命令，可以针对具体问题抽取一条神谕：

python scripts/draw-oracle.py --question '今天吃什么？'

抽取结果会写入 scripts/_oracle_state.json 并在本轮锁定。这样，后续的解读、推荐和命运卡都会引用同一条神谕，不会因为多次读取而意外变化。

查看当前锁定结果或要求重新抽取：

python scripts/draw-oracle.py --peek
python scripts/draw-oracle.py --redraw

--redraw 应只在用户明确要求重抽时使用。系统不会在生成解读或命运卡时自行更换神谕。

生成命运卡

命运卡使用固定的酒红金视觉模板，不依赖图像生成服务。背景包含深酒红渐变、金色双层边框、中央发光圆环和星点装饰；文字由 Pillow 程序排版，以避免中文、编号和价格出现乱码或溢出。

当 MCP 返回官方商品图片并且价格已通过 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

正式输出尺寸为 1200×1600 PNG。--price-verified 只能在价格确实经过 MCP 核实后使用，不能把示例价格当作实时价格。

图片素材的降级策略

商品主体按以下优先级处理：

  1. 优先使用 query-meals 或 query-meal-detail 返回的官方商品图。
  2. 没有官方图时，可以使用 --item-image 指定独立概念插画，并如实标注为概念插画。
  3. 如果外部素材不可用，脚本使用内置的汉堡、薯条和可乐程序插画。
  4. 全部素材都不可用时，输出「餐品视觉素材缺失」降级卡，并以退出码 2 和 JSON ok=false 报告失败。

项目不会用空圆环冒充餐品，也不会把概念插画标成官方实拍。

在对话中完成一次完整体验

典型对话可以这样进行：

你：麦门神谕，今天适合辞职吗？
McOracle：抽取神谕，返回正文、解读、行动提示和重大事项提醒，并可提供今日必点。

你：准备下单
McOracle：展示门店、取餐方式、商品和价格组成的订单摘要，请你确认。

你：确认下单
McOracle：重新核实价格后调用 create-order，并返回真实订单号与官方支付入口。

「看看」「推荐一下」和「准备下单」都不属于最终确认。只有用户明确回复「确认下单」后，订单流程才可以继续。

订单安全机制

订单安全控制器会检查订单状态和关键参数。只要门店、商品、数量、价格或取餐方式发生变化，之前的确认就会失效，系统必须重新展示摘要并要求确认。

项目不会自动支付，也不会伪造订单号或下单成功消息。创建订单后仍处于官方支付流程之外的待支付阶段，用户需要自行通过官方页面完成支付。到店自取和得来速使用 orderType=1，外送使用 orderType=2 并需要配送地址，两类参数不能混用。

独立运行订单安全演示

订单脚本提供纯逻辑 Mock 演示，不会创建真实订单：

python scripts/validate-order.py demo

这个演示适合在接入真实 MCP 前检查确认规则，包括未确认不得下单、模糊表达不算确认、订单参数变化会使确认失效，以及创建订单不等于支付成功。

运行测试

项目包含三组测试，分别覆盖神谕逻辑、命运卡生成和订单安全状态机：

python tests/test-oracle.py
python tests/test-card.py
python tests/test-order-safety.py

README 记录的当前结果是 24 项全部通过。其中神谕测试会验证 104 条数据、编号唯一、八类分类、随机性和状态锁定；命运卡测试会验证真实 PNG、尺寸、素材缺失降级、未核实价格分支以及长文本排版；订单测试使用 Mock 验证安全状态转换，不调用真实 MCP，也不会创建订单。

高级使用建议

区分娱乐神谕和现实决策

神谕只用于娱乐与启发，不是对未来的预测，也不能替代现实判断。涉及辞职、投资、健康、法律或财务的问题，应结合客观条件并咨询专业人士。

始终区分已核实价格与示例价格

MCP 返回的价格单位是「分」，展示前需要除以 100，而且价格具有时效性。没有完成实时核实，就应显示「价格未核实」，不要在卡片或对话中展示示例价格来代替实时价格。

管理凭据与隐私

Token 和 API Key 只能通过连接器配置或环境变量读取，不应写入源码或提交到仓库。项目不应保存用户隐私、Cookie、订单号或个人凭据。提交 Issue 或 Pull Request 时，也不要包含这些敏感信息。

理解当前能力边界

门店查询、菜单查询、餐品详情、价格计算、官方图片下载和命运卡生成已经有实际验证记录。完整的「下单—支付—状态回查」闭环、麦乐送链路以及优惠券领取和核销流程仍存在未完全实测的部分，因此不能把它们描述为已经端到端验证成功。

结语

McOracle 将固定神谕数据、真随机抽取、官方 MCP 实时菜单和程序化图片排版组合成了一套有趣的 WorkBuddy Skill。你可以先只使用神谕脚本，也可以配置 MCP，进一步获得门店、餐品和价格推荐。实际使用时，请牢记三条原则：神谕用于娱乐，价格必须实时核实，用户明确确认前绝不创建订单。

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