spideymooon / McOracle

# McOracle · 麦门神谕
> **不要问 AI，问薯条。**
McOracle 是一个**纯 Skill 形态**的 AI 神谕体验：向它提出任何问题，它会从 104 条原创神谕中**真随机**抽取一条答案，包装成一份「麦门启示录」，再通过**麦当劳中国官方 MCP** 查询真实门店、可售菜单与价格，推荐「今日必点」，并生成一张酒红金色的神秘命运卡。用户明确确认后，可继续进入订单流程。
 示例卡：神谕 NO.021「别在深夜做决定。」· 今日必点 板烧鸡腿堡三件套 · ¥34.50（经 MCP 实时核实）· 1200×1600 PNG 
**命运可以随机，价格必须真实。**
- 神谕从原创库真随机抽取，不由模型即兴编造；
- 商品、价格、门店全部来自真实 MCP 返回，绝不编造；
- 价格未经核实只显示「价格未核实」；
- **用户明确确认前，绝不创建订单；创建订单 ≠ 支付成功。**
---
## 目录
- 项目演示
- 核心功能与架构
- 项目目录结构
- 环境要求与依赖安装
- 安装为 WorkBuddy Skill
- 麦当劳中国 MCP 配置
- 图片生成与本地模板回退
- 使用示例
- 常见问题
- 测试
- 能力现状：已验证 / 未验证 / 已知限制
- 安全、隐私、品牌与免责声明
- 许可证与贡献
---
## 项目演示
McOracle 的完整链路：**提问 → 抽取神谕 → 查询真实菜单 → 核实价格 → 生成命运卡 → （用户确认后）下单**。
 [code] 
只问神谕、不想要推荐时，流程到 ① 即止，**不会**强迫提供位置或调用 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）**。
---
## 项目目录结构
 [code] 
---
## 环境要求与依赖安装
- **Python** 3.9+（开发环境使用 3.13）
- **Pillow**（仅命运卡生成需要）
- 可选：**WorkBuddy 桌面版** + 麦当劳中国官方 MCP（`mcd-mcp`）
- 图像生成能力：**正式出卡不需要**（模板为程序化绘制）
 [code] 
Mac / Linux 中文字体请确保系统存在（开发环境使用 Windows 的微软雅黑 / 楷体等）。脚本会自动按候选列表选择可用中文字体。
---
## 安装为 WorkBuddy Skill
1. **获取代码**
 [code] 
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】中填入：
 [code]