chorned/heb-mcp.skill

heb-mcp.skill (TikTok-2-HEB) 代理技能

管理实时的H-E-B杂货购物车，从购买历史中解析首选家庭产品，剪辑优惠券，并将烹饪视频URL转换为经过家庭规模调整和储藏室审计的H-E-B杂货购物车，并提供确定性的缺货替换。

---

🎯 触发条件

在以下情况下激活此技能：

1. 用户要求搜索H-E-B、查看购物车、切换首选商店或配送方式（路边取货 vs. 配送）、剪辑优惠券，或添加/移除H-E-B商品（例如 "在我的H-E-B购物车中加入全脂牛奶和黄油玉米饼"）。
2. 授权用户分享来自 TikTok (tiktok.com, vm.tiktok.com)、Instagram Reels (instagram.com/reel/) 或 YouTube Shorts (youtube.com/shorts/) 的烹饪或食谱URL。
3. 用户要求转换、调整规模或为食谱视频订购食材（例如 "从H-E-B下订单这个食谱的食材"、"把这个TikTok晚餐放入我的购物车"）。
4. 用户回复现有的杂货审核线程，进行分阶段后的调整（例如 "加入酱油"、"将普通三文鱼换成野生红鲑"、"将此替换设为永久"）。
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，并在用户请求时帮助切换其活跃商店或在路边取货和送货上门之间切换）。
   • 家庭人数： 询问用户为多少成人和儿童做饭（更新 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登录信息或会话cookie。
3. 反缓存污染不变量：
   • 缺货替换（第2/3/4级）必须严格保持临时性，仅针对该特定购物车订单。
   • 除非用户明确命令："将该替换设为永久" 或 "始终使用此品牌"，否则绝不要覆盖 cache/recipes/<slug>.yaml 中的 primary_sku。
4. 儿童友好型烹饪分离：
   • 当 kid_friendly_split 启用时，将辣味成分（sriracha、chili flakes、cayenne、jalapeños）与主锅分离。保持主锅口味温和，先盛出儿童份量，最后再为成人份量调味。
   • 添加提示，将蛋白质和窒息危险物切成1/2英寸的立方块。
5. 自动令牌刷新（鼓励每日Cronjob）：
   • 尽管H-E-B的短期会话访问令牌 (sat) 每30分钟轮换一次，heb_graphql.py 会按需使用长期会话令牌 (sst) 自动刷新它。
   • 在初始设置或提取/刷新会话期间，主动鼓励用户允许您设置一个自动化的24小时cronjob，以保持其底层H-E-B会话和反机器人令牌 (reese84) 在后台得到验证，这样他们就不必在每次购物前手动重新登录。

---

🛠️ 逐步执行工作流程

步骤 1: 飞行前缓存查找

在执行媒体提取或API调用之前，检查视频是否已被解析并缓存：

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

• 命中： 加载缓存的食谱YAML。直接进入步骤 4（购物车分阶段），使用缓存的 primary_sku 定义。
• 未命中： 继续执行步骤 2（媒体提取）。

步骤 2: 零认证多模态媒体提取

运行3遍提取管道：

python scripts/extract_recipe_media.py "<VIDEO_URL>"

1. 第1遍： 捕获视频标题、描述、上传者和自动字幕。
2. 第2遍： 清理字幕提示、移除时间戳、去重滚动字幕重复。
3. 第3遍： 如果转录内容稀疏（少于3个烹饪计量标记），则自动提取音频流或关键帧。

步骤 3: 食谱解析、家庭规模调整与储藏室审计

1. 家庭规模调整： 使用 HouseholdScaler 将食材数量从原始份量（例如4份）调整为目标份量（2名成人+1名儿童默认 2.5 份）。
2. 储藏室去重： 使用 PantryComparator 对照 config/pantry_staples.json 检查食材。将匹配项（盐、胡椒、食用油、酱油、大蒜粉）移至 pantry_staples_skipped。
3. 儿童准备提示： 如果检测到辣味成分或完整蛋白质，生成儿童友好型改编。

步骤 4: H-E-B目录匹配与5级后备级联

对于 ingredients_to_buy 中的每种食材（或用户的临时请求），使用 scripts/heb_client.py 对照本地H-E-B商店目录进行匹配：

• 第0级（首选SKU解析与包装规格缩放）： 匹配 cache/preferred_skus.json（规范键和别名数组），该文件由历史订单和手动锁定填充。自动计算整数包装数量（例如48盎司食谱体积 / 32盎司包装 -> 2包）。如果有货，直接作为第0级分阶段加入。如果缺货，平滑级联到第1级。
• 第1级（精确SKU匹配）： 如果现有食谱主要SKU有货则加入。
• 第2级（品牌层级）： 如果主要SKU缺货，使用 brand_hierarchy（H-E-B → H-E-B Organics → Central Market → Mi Tienda → Hill Country Fare → National Brand）进行替换。
• 第3级（有机↔常规替换）： 如果商店仅有一种有货，将有机替换为常规（反之亦然）。
• 第4级（包装规格调整/人工升级）： 调整数量或将类别清空标记为 ⚠️ 缺货（需要人工呼叫）。

步骤 5: 直接GraphQL购物车分阶段与优惠券剪辑（零慢速UI点击）

通过已认证的GraphQL操作（持久化查询 cartEstimated、cartItemV2、CouponClip，来自 texas-grocery-mcp 的供应商），使用提取的Chrome CDP（127.0.0.1:9222）/ rookiepy 会话令牌，直接分阶段加入商品并剪辑优惠券：

# 1. 提取或刷新实时会话令牌
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] 人类在环结账关卡： 代理严格禁止执行结账、支付或配送/取货时段预订突变。仅允许购物车分阶段和数字优惠券剪辑；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表格，使用简洁的emoji项目符号格式）：

🛒 H-E-B购物车已分阶段：香脆蜂蜜大蒜三文鱼块
已调整为2名成人 + 1名儿童（约2.5份）

👶 儿童准备提示：
• 将1汤匙辣椒酱从主锅釉料中取出。先盛出儿童份量，然后将成人份量与辣椒酱拌匀。
• 将儿童的三文鱼切成1/2英寸的立方块。

✅ 已加入H-E-B购物车（4件商品）：
• 1x H-E-B鲜大西洋三文鱼柳（约1.25磅）— $13.74
• 1x H-E-B纯三叶草蜂蜜（12盎司）— $4.48
• 1x 新鲜青葱（1把）— $0.88
• 1x H-E-B茉莉香米（32盎司）— $2.74

🔄 自动替换（商店缺货）：
• 2x H-E-B西兰花小花（10盎司袋装）— $4.56
  （1磅有机西兰花头缺货；本次订单替换为2x 10盎司袋装）

🎟️ 已剪辑优惠券：
• H-E-B新鲜海鲜盘立减$1.00

🏠 储藏室检查（已跳过 — 回复即可添加）：
• 酱油（3汤匙）、大蒜（4瓣）、玉米淀粉（2汤匙）、芝麻油（1茶匙）

📱 下一步：
如果您想添加储藏室商品（例如"加入酱油"）或更换品牌，请回复。否则，打开My H-E-B应用审核并点击结账！

---

🔄 分阶段后回复命令

当用户回复已分阶段的审核线程时：

1. "添加[储藏室物品]"（例如 "我们没有酱油了，加上它"）：
   • 通过第0级首选SKU引擎解析并加入购物车： python scripts/heb_client.py --stage-sku "soy sauce" --confirm
   • 通过简短回复确认："已将1x H-E-B低钠酱油加入您的购物车。"
2. "将[商品]替换为[偏好]"（例如 "将普通三文鱼换成野生红鲑"）：
   • 从购物车中移除旧SKU，并添加首选SKU。
   • 提示："已为本订单替换为野生红鲑。您是否希望将此替换设为永久，用于此食谱的未来订单？"
3. "将此替换设为永久"：
   • 执行 python scripts/cache_manager.py promote-sku ... 以更新 cache/recipes/<slug>.yaml 中的 primary_sku，并将其锁定在 cache/preferred_skus.json 中，设置 source: "manual_override"。
   • 确认："已更新食谱缓存：Central Market野生红鲑现为此食谱的主要SKU，并已锁定为首选SKU。"
4. "将首选商店切换为[商店]" / "切换为路边取货或配送"：
   • 更新 .env 中的 HEB_STORE_ID 和 config/household.yaml 中的 store，或更新H-E-B会话中的活跃商店/配送模式，并重新验证新商店的商品可用性。