chorned/heb-mcp.skill

heb-mcp.skill（TikTok-2-HEB）代理技能

管理即時 H-E-B 購物車、從購買記錄解析偏好的家庭產品、剪取折價券，並將料理影片網址轉換為經過家庭份量調整與 pantry 庫存比對的 H-E-B 購物車，同時提供確定性的缺貨替代方案。

---

🎯 觸發條件

當以下情況發生時啟用此技能：

1. 使用者要求搜尋 H-E-B、檢查購物車、更改偏好門市或配送方式（Curbside 自取 vs. Delivery 送貨）、剪取折價券，或新增/移除 H-E-B 商品（例如："Add whole milk and butter tortillas to my H-E-B cart"）。
2. 已授權的使用者分享來自 TikTok（tiktok.com、vm.tiktok.com）、Instagram Reels（instagram.com/reel/）或 YouTube Shorts（youtube.com/shorts/）的料理或食譜網址。
3. 使用者要求將食譜影片轉換、縮放或訂購雜貨（例如："Order the ingredients for this recipe from H-E-B"、"Put this TikTok dinner into my cart"）。
4. 使用者回覆現有的雜貨審閱討論串，要求在暫存購物車後進行調整（例如："add soy sauce"、"swap regular salmon for wild sockeye"、"make that swap permanent"）。
5. 使用者要求初次設定或配置 heb-mcp.skill（TikTok-2-HEB）。

---

🚀 首次設定（代理主導的入門引導）

當使用者請您設定此專案時，請為他們處理技術步驟，僅詢問簡短且使用白話文的問題：

1. 安裝環境與二進制檔案：

   uv venv --python 3.11 .venv && source .venv/bin/activate && uv pip install -r requirements.txt
   playwright install chromium
   cp -n .env.example .env
   cp -n config/household.example.yaml config/household.yaml
   cp -n config/pantry_staples.example.json config/pantry_staples.json
   

2. 快速詢問使用者設定問題：
   • 偏好 H-E-B 門市與配送方式： 詢問他們在哪間 H-E-B 門市購物（查詢/更新 .env 中的 HEB_STORE_ID 和 config/household.yaml 中的 store，並在任何要求下幫助他們切換作用中門市或在 Curbside Pickup 與 Home Delivery 之間切換）。
   • 家庭人數： 詢問他們為多少成人/小孩做飯（更新 config/household.yaml）。
3. 擷取會話與同步歷史訂單： 請使用者確認已在 Safari 或 Chrome 中登入 heb.com，然後執行：

   python scripts/heb_client.py --harvest
   python scripts/cache_manager.py update-preferred-skus
   python tests/test_skill_setup.py
   

4. 設定自動每日權杖重新整理 cronjob： 強烈鼓勵使用者允許您安裝一個每 24 小時重複執行的 cronjob（0 9 * * * cd <REPO_PATH> && .venv/bin/python scripts/heb_client.py --harvest >/dev/null 2>&1），以確保他們的 H-E-B 會話自動保持活躍。

---

🔒 操作不變原則與安全護欄

1. 強制人工在迴圈的結帳閘道：
   • 代理負責將商品暫存到購物車中並剪取數位折價券。
   • 代理絕不能提交付款、預約送貨/取貨時段或完成訂單結帳。
   • 最終檢視與結帳執行始終由使用者在官方的 My H-E-B 手機應用程式中自行完成。
2. 零驗證提取：
   • 始終呼叫 scripts/extract_recipe_media.py，無需個人 TikTok/Instagram 登入資訊或 session cookie。
3. 防止快取污染不變原則：
   • 缺貨替代方案（層級 2/3/4）必須嚴格保持為僅針對該特定購物車訂單的暫時性調整。
   • 除非使用者明確指令："make that swap permanent" 或 "always use this brand"，否則絕不覆寫 cache/recipes/<slug>.yaml 中的 primary_sku。
4. 兒童友善準備分割：
   • 當啟用 kid_friendly_split 時，將辣椒素/辣味成分（如 sriracha、chili flakes、cayenne、jalapeños）與主煎鍋分開。保持主要菜餚溫和，先盛出兒童份量，最後再為成人份量調味。
   • 加入提醒，將蛋白質和可能造成窒息風險的食物切成 1/2 英寸的塊狀。
5. 自動權杖重新整理（鼓勵每日 Cronjob）：
   • 雖然 H-E-B 的短期 session 存取權杖（sat）每 30 分鐘輪換一次，但 heb_graphql.py 會根據需求使用長期 session 權杖（sst）自動為其重新整理。
   • 在初始設定或擷取/重新整理會話後，主動鼓勵使用者允許您設定一個自動化的每日 cronjob，在背景持續驗證他們的底層 H-E-B 會話與反機器人權杖（reese84），這樣他們就不必在每次購物前手動重新登入。

---

🛠️ 逐步執行工作流程

步驟 1：預檢快取查詢

在執行媒體提取或 API 呼叫之前，檢查該影片是否已經被解析並快取：

python scripts/cache_manager.py lookup --query "<VIDEO_URL_OR_ID>"

• 快取命中： 載入快取的食譜 YAML。使用快取的 primary_sku 定義直接進入步驟 4（購物車暫存）。
• 快取未命中： 繼續執行步驟 2（媒體提取）。

步驟 2：零驗證多模態媒體提取

執行 3 通道提取管線：

python scripts/extract_recipe_media.py "<VIDEO_URL>"

1. 通道 1： 擷取影片標題、描述、上傳者與自動字幕。
2. 通道 2： 清理字幕提示、移除時間戳記，並去除重複的滾動式字幕重複內容。
3. 通道 3： 如果轉錄文字內容稀少（少於 3 個烹飪計量詞彙），自動提取音訊流或關鍵影格。

步驟 3：食譜解析、家庭份量縮放與 Pantry 庫存審核

1. 家庭份量縮放： 使用 HouseholdScaler 將食材數量從原始份量（例如 4 人份）縮放至目標份量（預設為 2.5，代表 2 位成人 + 1 位兒童）。
2. Pantry 去重： 使用 PantryComparator 比對食材與 config/pantry_staples.json。將符合的項目（鹽、胡椒、食用油、醬油、蒜粉）移至 pantry_staples_skipped。
3. 兒童準備提醒： 如果偵測到辛辣食材或完整蛋白質，產生兒童友善的調整建議。

步驟 4：H-E-B 商品目錄比對與五層後備級聯

對於 ingredients_to_buy 中的每項食材（或臨時的使用者請求），使用 scripts/heb_client.py 比對當地 H-E-B 門市目錄：

• 層級 0（偏好 SKU 解析與包裝規格縮放）： 比對 cache/preferred_skus.json（標準鍵與別名陣列），該檔案由歷史訂單與手動釘選填充。自動計算整數包裝數量（例如 48 oz 食譜量 / 32 oz 包裝 -> 2 包）。若有庫存，直接以層級 0 暫存。若缺貨，平滑降級至層級 1。
• 層級 1（精確 SKU 比對）： 若現有食譜 primary SKU 有庫存則加入。
• 層級 2（品牌層級）： 若 primary SKU 缺貨，使用 brand_hierarchy（H-E-B → H-E-B Organics → Central Market → Mi Tienda → Hill Country Fare → National Brand）進行替代。
• 層級 3（有機 ↔ 常規互換）： 若門市僅有其中一種庫存，則互換有機與常規品項。
• 層級 4（包裝規格調整 / 人為升級）： 調整數量或將品項類別全面缺貨標記為 ⚠️ OUT OF STOCK (NEEDS HUMAN CALL)。

步驟 5：直接 GraphQL 購物車暫存與折價券剪取（零緩慢 UI 點擊）

透過已驗證的 GraphQL 操作（從 texas-grocery-mcp 購入的持久化查詢 cartEstimated、cartItemV2、CouponClip），使用擷取的 Chrome CDP（127.0.0.1:9222）/ rookiepy session 權杖，直接暫存商品並剪取折價券：

# 1. 擷取或重新整理即時 session 權杖
python scripts/heb_client.py --harvest

# 2. 從歷史訂單與「再次購買」同步偏好 SKU
python scripts/cache_manager.py update-preferred-skus

# 3. 手動將偏好產品固定為偏好 SKU（受到保護，不會被自動同步覆寫）
python scripts/cache_manager.py pin-preferred-sku \
  --ingredient "whole milk" \
  --sku "4122012345" \
  --product "123456" \
  --name "H-E-B Organics Whole Milk" \
  --package-size "1 gal"

# 4. 解析臨時食材或測試包裝規格
python scripts/heb_client.py --resolve-sku "48 oz beef broth"

# 5. 暫存候選商品（需要人工確認 --confirm）
python scripts/heb_client.py --stage-sku "48 oz beef broth" --confirm
# 或直接使用產品 ID：
python scripts/heb_client.py --cart-add <PRODUCT_ID> [--sku <SKU_ID>] [--qty <N>] --confirm

# 6. 檢查目前即時購物車
python scripts/heb_client.py --cart-get

# 7. 若商品被替換，從購物車中移除
python scripts/heb_client.py --cart-remove <PRODUCT_ID> [--sku <SKU_ID>] --confirm

# 8. 剪取數位折價券
python scripts/heb_client.py --coupon-clip <COUPON_ID> --confirm

[!IMPORTANT] 人工在迴圈的結帳閘道： AGY 嚴格禁止執行結帳、付款或預約送貨/取貨時段的突變操作。僅限購物車暫存與數位折價券剪取；Carl 始終會在 My H-E-B 手機應用程式中檢視並點擊最終結帳。

⏱️ 建議的背景 Cronjob（每日會話重新整理）

雖然 H-E-B 的短期 sat 權杖每 30 分鐘輪換一次，並透過 sst 在需要時自動重新整理，但請鼓勵使用者設定一個每日 cronjob（macOS/Linux）或預定工作（Windows 上的 schtasks），每 24 小時重新整理並驗證一次會話。主動提議為他們安裝到 crontab 中：

0 9 * * * cd /path/to/heb-mcp.skill && .venv/bin/python scripts/heb_client.py --harvest >/dev/null 2>&1

（若需要 Slack 通知，也可使用 scripts/cron_refresh_heb_auth.py / scripts/cron_refresh_heb_auth.sh。）

步驟 6：食譜快取持久化

將解析後的食譜持久化，確保未來執行能走快速路徑：

python scripts/cache_manager.py save --file <RECIPE_DATA_YAML>

步驟 7：手機審閱摘要（iMessage / Slack）

格式化成適合在手機螢幕上閱讀的審閱摘要（避免 Markdown 表格，使用乾淨的表情符號項目符號格式）：

🛒 H-E-B Cart Staged: Crispy Honey Garlic Salmon Bites
Scaled for 2 Adults + 1 Kid (~2.5 servings)

👶 Kid Prep Note:
• Hold the 1 tbsp sriracha out of the main skillet glaze. Plate the kid's portion first, then toss adult portions with sriracha.
• Cut kid's salmon into 1/2-inch bite-sized cubes.

✅ Added to H-E-B Cart (4 items):
• 1x H-E-B Fresh Atlantic Salmon Fillet (~1.25 lb) — $13.74
• 1x H-E-B Pure Clover Honey (12 oz) — $4.48
• 1x Fresh Green Onions (1 bunch) — $0.88
• 1x H-E-B Jasmine Rice (32 oz) — $2.74

🔄 Auto-Subbed (Out of Stock at Store):
• 2x H-E-B Broccoli Florets (10 oz bag) — $4.56
  (1 lb Organic Crowns were OOS; subbed 2x 10oz bags for this order only)

🎟️ Coupons Clipped:
• $1.00 off H-E-B Fresh Seafood Tray

🏠 Pantry Check (Skipped — reply to add):
• Soy sauce (3 tbsp), Garlic (4 cloves), Cornstarch (2 tbsp), Sesame oil (1 tsp)

📱 Next Step:
Reply if you want to add a pantry item (e.g. "add soy sauce") or swap a brand. Otherwise, open the My H-E-B app to review and tap checkout!

---

🔄 暫存後回覆指令

當使用者回覆暫存的審閱討論串時：

1. "Add [pantry item]"（例如："we are out of soy sauce, add it"）：
   • 透過層級 0 偏好 SKU 引擎解析，並暫存至購物車： python scripts/heb_client.py --stage-sku "soy sauce" --confirm
   • 透過簡短回覆確認："Added 1x H-E-B Reduced Sodium Soy Sauce to your cart."
2. "Swap [item] for [preference]"（例如："swap regular salmon for wild sockeye"）：
   • 從購物車移除舊 SKU，並加入偏好 SKU。
   • 提示："Swapped for wild sockeye for this order. Would you like me to make this swap permanent for future orders of this recipe?"
3. "Make that swap permanent"：
   • 執行 python scripts/cache_manager.py promote-sku ... 以更新 cache/recipes/<slug>.yaml 中的 primary_sku，並將其固定在 cache/preferred_skus.json 中，設定 source: "manual_override"。
   • 確認："Updated recipe cache: Central Market Wild Sockeye is now your primary SKU for this recipe and pinned as your preferred SKU."
4. "Switch preferred store to [Store]" / "Switch to Curbside or Delivery"：
   • 更新 .env 中的 HEB_STORE_ID 和 config/household.yaml 中的 store，或更新 H-E-B 會話中的作用中門市/配送模式，並在新門市重新驗證購物車商品庫存。