spideymooon/McOracle

选用指南

AI 根据 README 整理 · 2026/10/14 20:01:28

使用方式

作为 WorkBuddy Skill 使用，也可独立运行脚本。

查看 README 依据

- 图像生成能力：**正式出卡不需要**（模板为程序化绘制） ```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 为准）： | 工具 | 用途 | 状态 | |---|---|---|

部署要求

需要 Python 3.9+ 和 Pillow；可选配置麦当劳中国 MCP 和 WorkBuddy 桌面版。

查看 README 依据

│ └── 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`）

已知限制

完整下单支付流程未闭环验证，麦乐送和优惠券链路未实测；神谕仅供娱乐，不构成决策依据。

查看 README 依据

- 命运卡 1200×1600 PNG 真实生成（正式模板 + 官方商品图合成）； - 餐品素材缺失时的降级路径（不静默失败）； - 订单安全状态机（Mock）。 ### ⚠️ 未完成端到端验证 / 未实测 - **完整「下单 → 支付 → 状态回查」流程尚未作为闭环验证**：`create-order` 的 Schema 已核实，接口已在真实会话中实测调用并返回订单（状态「待支付」），但**支付环节未执行、`query-order` 状态回查未验证**，因此本项目**不声明端到端下单 / 支付流程已通过验证**。 - 麦乐送（外送）链路（`delivery-query-stores`、地址、运费）未实测。 - 优惠券领取与核销路径未完整实测。 - 官方商品图无法覆盖时的概念插画实际观感（降级路径与测试已覆盖）。 ### 已知限制 - 到店自取与得来速走 `orderType=1`，外送走 `orderType=2`（需配送地址），两类参数不可混用； - 价格单位为「分」，展示前需 ÷100，且具有时效性； - Skill 自动加载与注册元数据依赖 WorkBuddy 版本，请按本地版本要求核对（见下）。 --- ## 安全、隐私、品牌与免责声明 ### 安全与隐私

不是。神谕仅供娱乐与启发，不构成任何现实决策依据。涉及辞职、投资、健康、法律等重大事项时，会附加「请结合现实条件独立判断」的提醒。 **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）： | 测试 | 项数 | 结果 | 覆盖要点 | |---|---|---|---|