Hướng dẫn McOracle – lời sấm nhà Mc: Từ lời sấm ngẫu nhiên đến gợi ý thực đơn thực tế và đặt hàng an toàn

McOracle là gì

McOracle (Lời thần McDonald's) là một trải nghiệm thần oracle AI thuần Skill. Người dùng có thể đặt bất kỳ câu hỏi nào; hệ thống sử dụng mô-đun secrets của Python để chọn ngẫu nhiên thực sự một câu trả lời từ 104 lời sấm tiếng Trung nguyên bản, sau đó kết hợp MCP chính thức của McDonald's Trung Quốc để tra cứu cửa hàng thực tế, thực đơn đang bán và giá, rồi tạo ra một «Sách Khải Huyền McDonald's» cùng thẻ vận mệnh.

Nguyên tắc cốt lõi của dự án là: lời sấm có thể ngẫu nhiên, nhưng sản phẩm và giá nhất định phải có thật. Lời sấm lấy từ dữ liệu cố định trong kho lưu trữ, không do mô hình tự sáng tác trong lúc chạy; món ăn, cửa hàng và giá chỉ sử dụng dữ liệu do MCP trả về; khi chưa xác minh giá, hệ thống hiển thị «Giá chưa được xác minh». Trước khi người dùng xác nhận rõ ràng, hệ thống sẽ không tạo đơn hàng; việc tạo đơn hàng cũng không đồng nghĩa với thanh toán thành công.

Quy trình hoạt động đầy đủ

Quy trình tiêu chuẩn của McOracle gồm năm giai đoạn:

1. Người dùng đặt câu hỏi hoặc trực tiếp yêu cầu lời sấm McDonald's.
2. scripts/draw-oracle.py chọn ngẫu nhiên thực sự một lời sấm từ references/oracle-library.json và khóa kết quả của lượt này.
3. Nếu người dùng cần gợi ý món ăn, Skill sử dụng MCP để tra cứu các cửa hàng lân cận, thực đơn đang bán và thông tin chi tiết món ăn.
4. Sử dụng calculate-price để xác minh giá, sau đó dùng scripts/generate-card.py tạo thẻ vận mệnh PNG kích thước 1200×1600.
5. Chỉ sau khi người dùng trả lời rõ ràng «Xác nhận đặt hàng», hệ thống mới kiểm tra lại thông tin đơn và gọi create-order. Sau đó người dùng vẫn phải tự thanh toán qua cổng chính thức.

Nếu người dùng chỉ muốn rút một lời sấm, quy trình sẽ kết thúc ở giai đoạn đầu tiên; hệ thống không bắt buộc yêu cầu vị trí và cũng không gọi MCP.

Mô-đun cốt lõi và cấu trúc dự án

Dự án chủ yếu gồm các mô-đun sau:

• Oracle Engine: draw-oracle.py và thư viện lời sấm phụ trách việc chọn ngẫu nhiên, khóa kết quả và kiểm soát việc rút lại.
• Recommendation Engine: recommendation-rules.md ánh xạ các nhãn lời sấm sang hướng gợi ý món ăn, đồng thời đưa ra đề xuất dựa trên thực đơn thực tế và ngân sách.
• MCP Adapter: SKILL.md và MCP_INTEGRATION.md mô tả thứ tự gọi công cụ, quy tắc tham số và cách xử lý ngoại lệ.
• Card Generator: generate-card.py sử dụng Pillow để lập trình bố cục mẫu màu đỏ rượu vang ánh vàng và ghép ảnh sản phẩm chính thức.
• Order Safety Controller: validate-order.py sử dụng máy trạng thái để kiểm soát quy trình xác nhận, ngăn việc đặt hàng khi chưa được xác nhận.
• Skill Orchestrator: SKILL.md định nghĩa điều kiện kích hoạt, quy trình thực thi, định dạng đầu ra và yêu cầu an toàn.

Thư viện lời sấm gồm 104 nội dung nguyên bản, bao phủ tám nhóm lớn: khẳng định, phủ định, chờ đợi, hành động, đảo chiều, may mắn, hài hước và độc quyền McDonald's. Mỗi lời sấm gồm số hiệu, nội dung, phân loại, nhãn, diễn giải, gợi ý hành động, nhãn đề xuất và chủ đề hình ảnh.

Cài đặt phụ thuộc Python

Dự án yêu cầu Python 3.9 trở lên. Môi trường phát triển sử dụng Python 3.13. Thẻ vận mệnh chính thức được dàn trang bằng Pillow, vì vậy cần cài đặt Pillow; bản thân các tập lệnh rút lời sấm và an toàn đơn hàng không phụ thuộc vào API tạo ảnh.

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

Nếu chạy trên macOS hoặc Linux, hãy xác nhận hệ thống có phông chữ hỗ trợ hiển thị tiếng Trung. Tập lệnh sẽ chọn phông chữ khả dụng theo danh sách ứng viên. Việc tạo thẻ chính thức không cần cấu hình Image Generation API Key.

Cài đặt dưới dạng WorkBuddy Skill

1. Lấy dự án và cài đặt các phụ thuộc.
2. Sao chép toàn bộ thư mục McOracle/ vào thư mục Skill cấp người dùng ~/.workbuddy/skills/McOracle/, hoặc sao chép vào {workspace}/.workbuddy/skills/McOracle/ của workspace hiện tại.
3. Bật MCP McDonald's Trung Quốc trong trình kết nối của WorkBuddy.
4. Mở cuộc trò chuyện và dùng các cụm từ như «Lời sấm McDonald's», «Rút một quẻ», «Lời sấm hôm nay» để kích hoạt Skill.

Bạn cũng có thể đặt câu hỏi thông thường, chẳng hạn «Tôi có nên nghỉ việc không?». Nếu muốn thực hiện toàn bộ quy trình, có thể nói «Tôi muốn vận mệnh McDonald's đầy đủ hôm nay». Các phiên bản WorkBuddy khác nhau có thể có yêu cầu khác nhau về metadata đăng ký Skill; hãy bổ sung cấu hình tương ứng theo phiên bản cục bộ.

Cấu hình MCP chính thức của McDonald's Trung Quốc

Trước khi sử dụng cửa hàng, thực đơn và giá thực tế để đề xuất, hãy tìm hiểu cách đăng ký Token trong hướng dẫn sử dụng MCP chính thức, sau đó điền cấu hình trong «Trình kết nối» → «Trình kết nối tùy chỉnh» → «Cấu hình MCP» của WorkBuddy.

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

Hãy thay YOUR_MCP_TOKEN bằng Token của bạn và không commit Token vào kho lưu trữ. Các công cụ chính của dự án gồm now-time-info, query-nearby-stores, query-meals, query-meal-detail và calculate-price. Công cụ đặt hàng create-order chỉ được gọi sau khi người dùng xác nhận rõ ràng.

Sử dụng lần đầu: Rút lời sấm

Thực thi lệnh sau tại thư mục gốc của dự án để rút một lời sấm cho câu hỏi cụ thể:

python scripts/draw-oracle.py --question 'Hôm nay ăn gì?'

Kết quả rút sẽ được ghi vào scripts/_oracle_state.json và được khóa trong lượt hiện tại. Nhờ đó, phần diễn giải, đề xuất và thẻ vận mệnh tiếp theo đều tham chiếu cùng một lời sấm, không vô tình thay đổi do đọc nhiều lần.

Xem kết quả hiện đang bị khóa hoặc yêu cầu rút lại:

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

Chỉ sử dụng --redraw khi người dùng yêu cầu rút lại rõ ràng. Hệ thống sẽ không tự thay lời sấm khi tạo phần diễn giải hoặc thẻ vận mệnh.

Tạo thẻ vận mệnh

Thẻ vận mệnh sử dụng mẫu hình ảnh màu đỏ rượu vang ánh vàng cố định và không phụ thuộc vào dịch vụ tạo ảnh. Nền gồm chuyển sắc đỏ rượu vang đậm, khung viền đôi màu vàng, vòng tròn phát sáng ở trung tâm và các họa tiết ngôi sao; văn bản được dàn trang bằng Pillow để tránh lỗi hoặc tràn khi hiển thị tiếng Trung, số hiệu và giá.

Khi MCP trả về ảnh sản phẩm chính thức và giá đã được xác minh qua calculate-price, có thể tạo thẻ chính thức như sau:

python scripts/generate-card.py \
  --oracle-id 'NO.021' \
  --answer 'Đừng đưa ra quyết định vào đêm khuya.' \
  --interpretation 'Bạn lúc một giờ sáng và bạn lúc mười giờ sáng không phải là cùng một người.' \
  --item-name 'Combo burger đùi gà nướng ba món' \
  --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

Kích thước đầu ra chính thức là PNG 1200×1600. Chỉ được sử dụng --price-verified khi giá thực sự đã được MCP xác minh; không được coi giá trong ví dụ là giá theo thời gian thực.

Chiến lược hạ cấp素材 hình ảnh

Hình ảnh món ăn được xử lý theo thứ tự ưu tiên sau:

1. Ưu tiên sử dụng ảnh sản phẩm chính thức do query-meals hoặc query-meal-detail trả về.
2. Nếu không có ảnh chính thức, có thể dùng --item-image để chỉ định tranh minh họa ý tưởng riêng và ghi rõ đó là tranh minh họa ý tưởng.
3. Nếu không có tài nguyên bên ngoài, tập lệnh sử dụng tranh minh họa lập trình tích hợp sẵn về hamburger, khoai tây chiên và Coca-Cola.
4. Khi tất cả tài nguyên đều không khả dụng, xuất thẻ hạ cấp «Thiếu素材 hình ảnh món ăn», đồng thời báo lỗi bằng mã thoát 2 và JSON ok=false.

Dự án không dùng vòng tròn rỗng để giả làm món ăn, cũng không gắn nhãn ảnh chụp chính thức cho tranh minh họa ý tưởng.

Hoàn tất một trải nghiệm đầy đủ trong cuộc trò chuyện

Một cuộc trò chuyện điển hình có thể diễn ra như sau:

Bạn: Lời sấm McDonald's, hôm nay có thích hợp để nghỉ việc không?
McOracle: Rút lời sấm, trả về nội dung, diễn giải, gợi ý hành động và nhắc nhở các vấn đề quan trọng, đồng thời có thể đề xuất món nhất định phải gọi hôm nay.

Bạn: Chuẩn bị đặt hàng
McOracle: Hiển thị bản tóm tắt đơn hàng gồm cửa hàng, phương thức nhận hàng, sản phẩm và giá để bạn xác nhận.

Bạn: Xác nhận đặt hàng
McOracle: Kiểm tra lại giá, gọi create-order và trả về mã đơn hàng thực cùng cổng thanh toán chính thức.

«Xem thử», «Gợi ý một chút» và «Chuẩn bị đặt hàng» đều không phải xác nhận cuối cùng. Chỉ sau khi người dùng trả lời rõ ràng «Xác nhận đặt hàng», quy trình đơn hàng mới được tiếp tục.

Cơ chế an toàn đơn hàng

Bộ điều khiển an toàn đơn hàng sẽ kiểm tra trạng thái đơn hàng và các tham số quan trọng. Chỉ cần cửa hàng, sản phẩm, số lượng, giá hoặc phương thức nhận hàng thay đổi, xác nhận trước đó sẽ mất hiệu lực; hệ thống phải hiển thị lại bản tóm tắt và yêu cầu xác nhận.

Dự án không tự động thanh toán, cũng không giả mạo mã đơn hàng hoặc thông báo đặt hàng thành công. Sau khi tạo đơn, đơn vẫn ở trạng thái chờ thanh toán bên ngoài quy trình thanh toán chính thức; người dùng cần tự hoàn tất thanh toán qua trang chính thức. Nhận tại cửa hàng và McDrive sử dụng orderType=1; giao hàng sử dụng orderType=2 và cần địa chỉ giao hàng. Hai loại tham số này không được dùng lẫn.

Chạy độc lập bản trình diễn an toàn đơn hàng

Tập lệnh đơn hàng cung cấp bản trình diễn Mock thuần logic và không tạo đơn hàng thật:

python scripts/validate-order.py demo

Bản trình diễn này phù hợp để kiểm tra quy tắc xác nhận trước khi kết nối MCP thật, bao gồm không được đặt hàng khi chưa xác nhận, cách diễn đạt mơ hồ không được tính là xác nhận, thay đổi tham số đơn hàng sẽ làm mất hiệu lực xác nhận, và tạo đơn hàng không đồng nghĩa với thanh toán thành công.

Chạy kiểm thử

Dự án gồm ba nhóm kiểm thử, lần lượt bao phủ logic lời sấm, việc tạo thẻ vận mệnh và máy trạng thái an toàn đơn hàng:

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

Kết quả hiện tại được ghi trong README là cả 24 mục đều đạt. Kiểm thử lời sấm xác minh 104 mục dữ liệu, số hiệu duy nhất, tám nhóm phân loại, tính ngẫu nhiên và trạng thái khóa; kiểm thử thẻ vận mệnh xác minh PNG thực, kích thước, chế độ hạ cấp khi thiếu素材, nhánh giá chưa xác minh và bố cục văn bản dài; kiểm thử đơn hàng dùng Mock để xác minh chuyển đổi trạng thái an toàn, không gọi MCP thật và không tạo đơn hàng.

Gợi ý sử dụng nâng cao

Phân biệt lời sấm giải trí với quyết định thực tế

Lời sấm chỉ dùng cho giải trí và gợi mở, không phải dự đoán tương lai và không thể thay thế phán đoán thực tế. Với các vấn đề liên quan đến nghỉ việc, đầu tư, sức khỏe, pháp luật hoặc tài chính, hãy xem xét các điều kiện khách quan và tham khảo chuyên gia.

Luôn phân biệt giá đã xác minh với giá ví dụ

Đơn vị giá MCP trả về là «cent», cần chia cho 100 trước khi hiển thị và giá có tính thời điểm. Nếu chưa hoàn tất xác minh theo thời gian thực, phải hiển thị «Giá chưa được xác minh»; không dùng giá ví dụ thay cho giá theo thời gian thực trên thẻ hoặc trong cuộc trò chuyện.

Quản lý thông tin xác thực và quyền riêng tư

Token và API Key chỉ được đọc thông qua cấu hình trình kết nối hoặc biến môi trường, không được ghi vào mã nguồn hoặc commit vào kho lưu trữ. Dự án không nên lưu thông tin riêng tư, Cookie, mã đơn hàng hoặc thông tin xác thực cá nhân của người dùng. Khi gửi Issue hoặc Pull Request, cũng không được đưa vào các thông tin nhạy cảm này.

Hiểu rõ giới hạn năng lực hiện tại

Việc tra cứu cửa hàng, tra cứu thực đơn, xem chi tiết món ăn, tính giá, tải ảnh chính thức và tạo thẻ vận mệnh đã có ghi nhận kiểm chứng thực tế. Tuy nhiên, vòng khép kín «đặt hàng—thanh toán—kiểm tra lại trạng thái» hoàn chỉnh, quy trình McDelivery cùng quy trình nhận và sử dụng phiếu ưu đãi vẫn còn những phần chưa được kiểm thử đầy đủ; vì vậy không được mô tả chúng là đã được xác minh thành công từ đầu đến cuối.

Lời kết

McOracle kết hợp dữ liệu tiên tri cố định, việc rút ngẫu nhiên thực sự, thực đơn chính thức theo thời gian thực qua MCP và dàn trang hình ảnh bằng chương trình để tạo thành một WorkBuddy Skill thú vị. Bạn có thể chỉ sử dụng tập lệnh tiên tri trước, hoặc cấu hình MCP để nhận thêm đề xuất về cửa hàng, món ăn và giá cả. Khi sử dụng thực tế, hãy luôn ghi nhớ ba nguyên tắc: lời tiên tri chỉ nhằm mục đích giải trí, giá phải được xác minh theo thời gian thực và tuyệt đối không tạo đơn hàng trước khi người dùng xác nhận rõ ràng.

Số phận có thể ngẫu nhiên, nhưng giá cả phải chân thực.