spideymooon/McOracle

它解决的问题

人们通常希望从生活问题中得到有趣、新颖的答案，但 AI 聊天机器人往往容易编造内容——如果你接着要求食物推荐，它们可能会虚构菜单项目或价格。McOracle 通过将趣味部分（随机神谕）与事实部分（真实的麦当劳中国数据）分离来解决这个问题。它会给你随机抽取一条中文风格的神谕谚语，然后使用麦当劳中国官方 MCP（模型上下文协议）查询真实的附近门店、实际可售菜单项目和已验证价格。它从不编造产品、价格或门店。它还会拒绝下单，直到你明确确认，即使确认后也只创建订单——不会自动支付。

工作原理

McOracle 被构建为一个“技能”（WorkBuddy 助手的打包能力）。流程如下：

1. 提问 — 你可以问任何问题，比如“我今天该辞职吗？”
2. 抽取神谕 — 一个 Python 脚本（draw-oracle.py）使用 secrets 模块从本地库（oracle-library.json）中选取 104 条原创中文神谕谚语之一。抽取结果锁定到状态文件中，因此相同的谚语会用于解读、推荐和卡片，直到你明确要求重新抽取。
3. 获取真实推荐 — 如果你需要，系统会调用麦当劳中国官方 MCP 工具（query-nearby-stores、query-meals、calculate-price）查找附近门店，并显示真实的、经过价格验证的“今日必点”项目。价格以分为单位，并且始终显示为已验证，如果未确认则标记为“价格未验证”。
4. 生成运势卡片 — 一个 Python 脚本（generate-card.py）渲染固定 1200×1600 的 PNG，采用深红和金色塔罗风格模板。食物图片在可用时来自官方产品图片 URL；如果不可用，则使用回退概念插图（明确标注）或带有错误代码的降级卡片——它从不假装成功。
5. 可选下单 — 只有在你明确说“确认订单”（或类似表述）后，系统才会重新检查价格，调用 create-order MCP 工具，并返回带有官方支付链接的真实订单号。创建订单不是支付；系统从不自动支付。

如果你只需要神谕，流程在步骤 2 停止——你永远不会被迫分享位置或调用 MCP 工具。

适用人群

这个项目面向：

• 希望从随意问题中得到有趣、快速“运势”答案的人，并希望获得一张视觉吸引人的卡片可以分享。
• WorkBuddy 桌面助手的用户，他们想尝试一个以安全、不编造的方式集成真实商业 API（麦当劳中国 MCP）的技能。
• 参加麦当劳中国开发者挑战赛的开发者，他们需要一个具有真实 MCP 集成、安全控制和测试的技能的参考实现。

它不是预测工具，也不是专业建议的替代品。神谕仅供娱乐。

亮点

• 真正的随机性 — 神谕抽取使用 Python 的 secrets 模块进行真正的随机选择，而不是模型即兴发挥。
• 始终验证价格 — 每个推荐项目都来自真实的 MCP 查询；如果价格无法验证，卡片和对话会显示“价格未验证”，而不是编造数字。
• 严格的下单安全 — 在用户明确确认之前不会创建订单，任何项目、门店或价格的更改都会使之前的确认失效。系统从不自动支付，也从不假装成功。
• 离线可用的视觉 — 运势卡片使用 Pillow 以编程方式渲染；不需要图像生成 API 或密钥。模板永远不会失败，缺失的产品图片会诚实地降级（退出代码 2，ok=false）。
• 24/24 测试通过 — 三个测试套件覆盖神谕随机性/锁定、卡片生成和降级，以及下单安全状态转换（仅模拟，无真实订单）。
• 清晰的限制文档 — 完整的订单到支付流程未经过端到端验证；配送和优惠券流程在 README 中标记为未验证。