Kroger/QFC API Skill

概述

用于搜索 Kroger/QFC 商品、管理购物车、查询自提可用性以及创建自提订单的 Skill。 使用官方 Kroger API。QFC 连锁店 chain ID：213。

配置

1. 在 developer.kroger.com 注册账号并创建应用。
2. 添加重定向 URI，例如：http://localhost
3. 所需权限范围（Scopes）：product.compact locations.read fulfillment.readwrite orders.pickup.create
4. 编辑 state.json 文件，添加以下字段：client_id、client_secret、chain_id: "213"
5. OAuth 流程：
   • python3 scripts/client.py --state state.json oauth-url
   • 访问输出的 URL，登录并授权。
   • 从重定向地址中复制授权码（例如：http://localhost?code=ABC123）
   • python3 scripts/client.py --state state.json oauth-exchange ABC123

用法（通过 exec 调用）

请在 workspace 根目录下执行：

搜索商品

python3 kroger-api.skill/scripts/client.py search "milk" --chain-id 213 --limit 5

输出：JSON 格式商品列表，包含字段如 id（UPC）、attributes.description、attributes.brand 等。

查找门店

python3 kroger-api.skill/scripts/client.py locations 98101 --chain-id 213

输出：门店信息列表，包含字段如 id、attributes.address.addressLine1 等。

购物车（本地）

python3 kroger-api.skill/scripts/client.py cart-add 0001111101001 2  # UPC 数量
python3 kroger-api.skill/scripts/client.py cart-get
python3 kroger-api.skill/scripts/client.py cart-clear

查询自提可用性

python3 kroger-api.skill/scripts/client.py availability LOC123 --items '[{"upc":"UPC","quantity":1}]'

创建订单

python3 kroger-api.skill/scripts/client.py order-create LOC123 "2026-02-14T10:00:00Z" --items '[{"upc":"UPC","quantity":1}]'

杂货清单集成

创建 grocery-list.txt 文件：

milk
bread
eggs

python3 kroger-api.skill/scripts/client.py grocery --zip 98101

输出匹配的商品及附近门店列表。Agent 工作流示例：对每个商品执行搜索 → 选取 UPC（例如取首个结果）→ 加入购物车 → 查询可用性 → 创建订单。

Agent 工作流示例

1. 用户：“将牛奶和鸡蛋加入 Kroger 购物车”
2. 搜索 “milk”，选取 UPC1，执行 cart-add
3. 搜索 “eggs”，选取 UPC2，执行 cart-add
4. 用户：“查找 98101 附近的 QFC 门店” → 执行 locations
5. 执行 location-set LOC 设置当前门店
6. cart-get 获取当前购物车商品
7. availability 查询可选时间段并选定时段
8. 调用 order-create 并传入选定的时间段。

状态管理

state.json：保存访问令牌、本地购物车内容、location_id 等状态信息。

注意事项

• 所有接口均基于 Kroger API 文档实现，请以 developer.kroger.com/reference 中的最新文档为准。
• UPC 来源于商品响应中的 products.id 字段。
• 自提时间需为 ISO 8601 格式的 UTC 时间。
• 错误处理：请检查 API 响应体内容。
• 访问令牌支持自动刷新。

打包路径为：kroger-api.skill/