Mafundisho ya McOracle: kutoka unabii wa nasibu hadi mapendekezo halisi ya menyu na kuagiza kwa usalama

McOracle ni nini

McOracle (Oracle ya McDonald's) ni uzoefu wa AI wa oracle unaotumia Skill pekee. Watumiaji wanaweza kuuliza swali lolote, na mfumo hutumia moduli ya Python secrets kuchagua kwa nasibu ya kweli jibu moja kutoka oracles 104 asili za Kichina, kisha hutumia MCP rasmi ya McDonald's China kutafuta mikahawa halisi, menyu zinazopatikana na bei, na kutengeneza «Ufunuo wa McDonald's» pamoja na kadi ya hatima.

Kanuni kuu ya mradi ni: oracle inaweza kuwa ya nasibu, lakini bidhaa na bei lazima ziwe halisi. Oracle hutoka kwenye data iliyowekwa kwenye hifadhi na haibuniwi kwa muda na modeli; chakula, mikahawa na bei hutumia data inayorejeshwa na MCP pekee; bei ikiwa haijathibitishwa kwa wakati halisi, huonyeshwa «Bei haijathibitishwa». Kabla ya mtumiaji kuthibitisha waziwazi, mfumo hautaunda agizo, na kuunda agizo hakumaanishi kuwa malipo yamekamilika.

Mtiririko kamili wa kazi

Mtiririko wa kawaida wa McOracle una hatua tano:

1. Mtumiaji anauliza swali au anaomba moja kwa moja oracle ya McDonald's.
2. scripts/draw-oracle.py huchagua oracle kwa nasibu ya kweli kutoka references/oracle-library.json, kisha kufunga matokeo ya mzunguko huu.
3. Mtumiaji akihitaji mapendekezo ya chakula, Skill hutumia MCP kutafuta mikahawa ya karibu, menyu zinazopatikana na maelezo ya bidhaa.
4. Bei huthibitishwa kupitia calculate-price, kisha scripts/generate-card.py hutengeneza kadi ya hatima ya PNG yenye ukubwa wa 1200×1600.
5. Ni baada tu ya mtumiaji kujibu waziwazi «Thibitisha agizo» ndipo mfumo hukagua tena maelezo ya agizo na kuita create-order. Baadaye, mtumiaji bado lazima alipe mwenyewe kupitia njia rasmi.

Mtumiaji akitaka tu kuchagua oracle, mtiririko huishia katika hatua ya kwanza; mfumo hautalazimisha kuomba eneo wala kuita MCP.

Moduli kuu na muundo wa mradi

Mradi unaundwa hasa na moduli zifuatazo:

• Oracle Engine: draw-oracle.py na hifadhi ya oracle hushughulikia uchaguzi wa nasibu, kufunga matokeo na udhibiti wa kuchagua tena.
• Recommendation Engine: recommendation-rules.md huunganisha lebo za oracle na aina za chakula, kisha hutoa mapendekezo kwa kuzingatia menyu halisi na bajeti.
• MCP Adapter: SKILL.md na MCP_INTEGRATION.md zinaeleza mpangilio wa miito ya zana, kanuni za vigezo na ushughulikiaji wa hitilafu.
• Card Generator: generate-card.py hutumia Pillow kuchora kwa programu kiolezo cha rangi nyekundu ya divai na dhahabu, kisha huunganisha picha rasmi za bidhaa.
• Order Safety Controller: validate-order.py hutumia mashine ya hali kudhibiti mchakato wa uthibitishaji na kuzuia maagizo yasiyothibitishwa.
• Skill Orchestrator: SKILL.md hufafanua masharti ya kuanzisha, mtiririko wa utekelezaji, muundo wa matokeo na mahitaji ya usalama.

Hifadhi ya oracle ina maudhui 104 asili yanayofunika makundi manane: ya uthibitisho, ya kukataa, ya kusubiri, ya kuchukua hatua, ya mgeuko, ya bahati njema, ya ucheshi na maalumu kwa McDonald's. Kila oracle ina nambari, maandishi, kundi, lebo, tafsiri, kidokezo cha hatua, lebo za mapendekezo na mandhari ya kuona.

Kusakinisha vitegemezi vya Python

Mradi unahitaji Python 3.9 au toleo jipya zaidi. Mazingira ya usanidi hutumia Python 3.13. Kadi rasmi za hatima hupangwa kwa programu ya Pillow, hivyo Pillow lazima isakinishwe; hati za kuchagua oracle na usalama wa agizo zenyewe hazitegemei API ya kutengeneza picha.

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

Ukiendesha kwenye macOS au Linux, hakikisha mfumo una fonti inayoweza kuonyesha Kichina. Hati itachagua fonti inayopatikana kulingana na orodha ya wagombea. Kutengeneza kadi rasmi hakuhitaji kusanidi Image Generation API Key.

Kusakinisha kama WorkBuddy Skill

1. Pata mradi na usakinishe vitegemezi.
2. Copy saraka nzima ya McOracle/ kwenye saraka ya Skill ya mtumiaji ~/.workbuddy/skills/McOracle/, au kwenye {workspace}/.workbuddy/skills/McOracle/ ya nafasi ya sasa ya kazi.
3. Washa MCP ya McDonald's China katika viunganishi vya WorkBuddy.
4. Fungua mazungumzo na utumie maneno kama «Oracle ya McDonald's», «Chagua oracle» au «Oracle ya leo» kuanzisha Skill.

Pia unaweza kuuliza swali la kawaida, kwa mfano «Je, nijiuzulu?» Ili kutekeleza mtiririko kamili, unaweza kusema «Nataka hatima kamili ya McDonald's ya leo». Matoleo tofauti ya WorkBuddy yanaweza kuwa na mahitaji tofauti ya metadata ya usajili wa Skill; ongeza usanidi unaohitajika kulingana na toleo lako la ndani.

Kusanidi MCP rasmi ya McDonald's China

Kabla ya kutumia mikahawa halisi, menyu na bei kwa mapendekezo, soma mwongozo rasmi wa matumizi ya MCP ili kuelewa jinsi ya kuomba Token, kisha jaza usanidi katika «Viunganishi» → «Kiunganishi maalumu» → «Sanidi MCP» cha WorkBuddy.

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

Badilisha YOUR_MCP_TOKEN kwa Token yako mwenyewe, na usiwasilishe Token kwenye hifadhi. Zana kuu zinazohusika katika mradi ni now-time-info, query-nearby-stores, query-meals, query-meal-detail na calculate-price. Zana ya maagizo create-order inaweza kuitwa tu baada ya mtumiaji kuthibitisha waziwazi.

Matumizi ya kwanza: kuchagua oracle

Tekeleza amri ifuatayo kwenye saraka kuu ya mradi ili kuchagua oracle moja kwa swali mahususi:

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

Matokeo ya uchaguzi yataandikwa kwenye scripts/_oracle_state.json na kufungwa kwa mzunguko huu. Kwa njia hii, tafsiri, mapendekezo na kadi ya hatima vitatumia oracle hiyo hiyo na haitabadilika kimakosa kwa sababu ya kusomwa mara nyingi.

Kuangalia matokeo yaliyofungwa au kuomba uchaguzi mpya:

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

--redraw inapaswa kutumiwa tu mtumiaji anapoomba waziwazi uchaguzi mpya. Mfumo hautabadilisha oracle wenyewe wakati wa kutengeneza tafsiri au kadi ya hatima.

Kutengeneza kadi ya hatima

Kadi ya hatima hutumia kiolezo kisichobadilika cha rangi nyekundu ya divai na dhahabu, bila kutegemea huduma ya kutengeneza picha. Mandharinyuma ina mgradiente ya divai iliyokolea, mpaka wa dhahabu wa tabaka mbili, duara linalong'aa katikati na mapambo ya nukta za nyota; maandishi hupangwa na Pillow ili kuzuia Kichina, nambari na bei kuonekana vibaya au kufurika.

MCP ikirejesha picha rasmi ya bidhaa na bei ikiwa imethibitishwa kupitia calculate-price, unaweza kutengeneza kadi rasmi hivi:

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

Ukubwa rasmi wa tokeo ni PNG ya 1200×1600. --price-verified inaweza kutumiwa tu baada ya bei kuthibitishwa na MCP; usichukulie bei ya mfano kuwa bei ya wakati halisi.

Mbinu ya kushusha kiwango kwa nyenzo za picha

Bidhaa kuu hushughulikiwa kwa kipaumbele kifuatacho:

1. Kipaumbele ni kutumia picha rasmi ya bidhaa iliyorejeshwa na query-meals au query-meal-detail.
2. Ikiwa hakuna picha rasmi, unaweza kutumia --item-image kubainisha mchoro huru wa dhana, na uutambue kwa ukweli kuwa ni mchoro wa dhana.
3. Nyenzo za nje zisipopatikana, hati hutumia michoro ya programu iliyojengewa ndani ya hamburger, chipsi na kinywaji.
4. Nyenzo zote zisipopatikana, hutolewa kadi ya kushusha kiwango yenye maandishi «Nyenzo ya kuona ya chakula haipo», huku hitilafu ikiripotiwa kwa msimbo wa kutoka 2 na JSON ok=false.

Mradi hautatumia duara tupu kujifanya chakula, wala hautaweka mchoro wa dhana kama picha rasmi ya bidhaa.

Kukamilisha uzoefu kamili katika mazungumzo

Mazungumzo ya kawaida yanaweza kuwa hivi:

Wewe: Oracle ya McDonald's, je leo ninafaa kuacha kazi?
McOracle: Inachagua oracle, inarudisha maandishi, tafsiri, kidokezo cha hatua na onyo la mambo muhimu, na inaweza kutoa pendekezo la lazima la leo.

Wewe: Niko tayari kuagiza
McOracle: Inaonyesha muhtasari wa agizo wenye mkahawa, njia ya kuchukua, bidhaa na bei, kisha inakuomba uthibitishe.

Wewe: Thibitisha agizo
McOracle: Inakagua tena bei, inaita create-order, na kurudisha nambari halisi ya agizo pamoja na njia rasmi ya malipo.

«Angalia», «Pendekeza» na «Niko tayari kuagiza» si uthibitisho wa mwisho. Mchakato wa agizo unaweza kuendelea tu baada ya mtumiaji kujibu waziwazi «Thibitisha agizo».

Mbinu ya usalama wa maagizo

Kidhibiti cha usalama wa agizo hukagua hali ya agizo na vigezo muhimu. Mkahawa, bidhaa, kiasi, bei au njia ya kuchukua ikibadilika, uthibitisho wa awali huwa batili; mfumo lazima uonyeshe tena muhtasari na uombe uthibitisho.

Mradi haulipi kiotomatiki, wala haughushi nambari ya agizo au ujumbe wa agizo lililofanikiwa. Baada ya kuunda agizo, bado huwa katika hali ya kusubiri malipo nje ya mchakato rasmi wa malipo; mtumiaji anahitaji kukamilisha malipo mwenyewe kupitia ukurasa rasmi. Kuchukua dukani na drive-thru hutumia orderType=1, huku uwasilishaji ukitumia orderType=2 na ukihitaji anwani ya uwasilishaji; aina hizi mbili za vigezo haziwezi kuchanganywa.

Onyesho huru la usalama wa maagizo

Hati ya maagizo hutoa onyesho la Mock la mantiki pekee na haitaunda agizo halisi:

python scripts/validate-order.py demo

Onyesho hili linafaa kukagua kanuni za uthibitisho kabla ya kuunganisha MCP halisi, zikiwemo kutoruhusu kuagiza bila uthibitisho, kutochukulia kauli zisizo wazi kuwa uthibitisho, kubatilisha uthibitisho wakati vigezo vya agizo vinabadilika, na kutambua kuwa kuunda agizo hakumaanishi malipo yamekamilika.

Kuendesha majaribio

Mradi una makundi matatu ya majaribio yanayofunika mantiki ya oracle, utengenezaji wa kadi ya hatima na mashine ya hali ya usalama wa maagizo:

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

README inaonyesha kuwa matokeo ya sasa ni majaribio 24 yote yamefaulu. Majaribio ya oracle huthibitisha data 104, upekee wa nambari, makundi manane, nasibu na kufungwa kwa hali; majaribio ya kadi ya hatima huthibitisha PNG halisi, ukubwa, kushusha kiwango kwa kukosekana kwa nyenzo, tawi la bei ambayo haijathibitishwa na mpangilio wa maandishi marefu; majaribio ya maagizo hutumia Mock kuthibitisha mabadiliko salama ya hali, bila kuita MCP halisi wala kuunda agizo.

Mapendekezo ya matumizi ya hali ya juu

Kutofautisha oracle ya burudani na maamuzi ya maisha halisi

Oracle ni ya burudani na msukumo pekee; si utabiri wa wakati ujao wala haiwezi kuchukua nafasi ya uamuzi wa maisha halisi. Kwa maswali kuhusu kuacha kazi, uwekezaji, afya, sheria au fedha, zingatia hali halisi na wasiliana na mtaalamu.

Kutofautisha kila mara bei iliyothibitishwa na bei ya mfano

Bei inayorejeshwa na MCP hupimwa kwa «fen», hivyo kabla ya kuionyesha lazima igawanywe kwa 100, na bei ina uhalali wa muda. Ikiwa uthibitishaji wa wakati halisi haujakamilika, inapaswa kuonyeshwa «Bei haijathibitishwa»; usionyeshe bei ya mfano kwenye kadi au mazungumzo badala ya bei ya wakati halisi.

Kusimamia vitambulisho na faragha

Token na API Key zinapaswa kusomwa kupitia usanidi wa kiunganishi au vigezo vya mazingira pekee; hazipaswi kuandikwa kwenye msimbo chanzo au kuwasilishwa kwenye hifadhi. Mradi haupaswi kuhifadhi faragha ya mtumiaji, Cookie, nambari ya agizo au vitambulisho vya kibinafsi. Unapowasilisha Issue au Pull Request, usijumuishe taarifa hizi nyeti.

Kuelewa mipaka ya uwezo wa sasa

Utafutaji wa mikahawa, utafutaji wa menyu, maelezo ya chakula, ukokotoaji wa bei, upakuaji wa picha rasmi na utengenezaji wa kadi ya hatima tayari vina rekodi za uthibitishaji wa vitendo. Mzunguko kamili wa «kuagiza—kulipa—kuangalia hali tena», mchakato wa McDelivery, pamoja na kupokea na kutumia kuponi bado una sehemu ambazo hazijajaribiwa kikamilifu; kwa hiyo haviwezi kuelezwa kuwa vimethibitishwa kutoka mwanzo hadi mwisho.

Hitimisho

McOracle imeunganisha data ya unabii iliyowekwa, uteuzi wa kweli wa nasibu, menyu rasmi ya MCP ya wakati halisi na mpangilio wa picha wa kiprogramu kuwa WorkBuddy Skill ya kufurahisha. Unaweza kuanza kwa kutumia hati ya unabii pekee, au kusanidi MCP ili kupata mapendekezo ya maduka, vyakula na bei. Unapotumia mfumo huu, kumbuka kanuni tatu: unabii ni kwa ajili ya burudani, bei lazima zithibitishwe kwa wakati halisi, na usiwahi kuunda agizo kabla ya mtumiaji kuthibitisha wazi.

Hatima inaweza kuwa ya nasibu, lakini bei lazima ziwe halisi.