pp-instacart

Instacart - Printing Press CLI

前置条件：安装 CLI

此技能依赖 instacart-pp-cli 二进制文件。**调用此技能中的任何命令前，必须先确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install instacart --cli-only
   

2. 验证：instacart-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent／运行时的 $PATH 中。

如果 npx 安装失败（例如没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/commerce/instacart/cmd/instacart-pp-cli@latest

如果安装后 --version 报告“command not found”，则运行时无法在 $PATH 中找到二进制文件目录。验证成功前，请勿继续运行技能命令。

何时使用此 CLI

当用户想要执行以下操作时，可以使用此 CLI：

• 通过自然语言将商品添加到 Instacart 购物车（“把柠檬雪葩加到 QFC 的购物车”）
• 添加之前买过的商品（“把我常买的牛奶加到 Safeway 的购物车”）
• 显示、搜索或比较不同零售商的当前购物车
• 列出或搜索自己的 Instacart 订单历史
• 通过脚本、cron 作业或 Agent 循环运行 Instacart 流程

如果用户想要实际结账，请勿使用此 CLI。此 CLI 会将商品添加到购物车；结账仍需在 Instacart 应用或 Web 界面中完成。

独特功能

优先使用历史记录的 add

add 会先检查本地购买历史；如果在目标零售商处找到可信匹配项，就会完全跳过由三次调用组成的实时 GraphQL 流程。这样，“添加我常买的柠檬雪葩棒”的处理时间就会从约 1.2 秒降至约 200 毫秒，并且会匹配到正确的 SKU（也就是你实际购买的商品），而不是当天实时搜索排名最高的商品。

可信度规则：

• 在该零售商的本地 purchased_items 中匹配到 FTS5 结果
• 购买时间在最近 365 天内
• 上次购买时有库存

如果任何条件不满足，就会回退到今天的实时搜索行为。传入 --no-history 可强制使用实时搜索。

每次成功的 add（无论是通过历史记录还是实时搜索解析）都会将结果写回 purchased_items，让历史数据持续丰富，无需完整重新同步。

一条命令回填历史记录

输入“回填我的 Instacart 订单”（或类似说法，参见“参数解析”）会启动由 Chrome-MCP 驱动的流程。该流程会遍历用户已登录的 Instacart 标签页，将订单历史提取为 JSONL，并导入本地数据库。完成回填后，add 会根据真实购买历史解析商品，而不是依赖实时搜索猜测。

主要方式：Chrome MCP。备用方式：手动将三个 JS 文件粘贴到 DevTools 中。

完整操作步骤见下文的“回填流程”。更多详情请参阅参考文档：

• docs/backfill-walkthrough.md — Chrome MCP 流程
• docs/backfill-devtools-fallback.md — 手动 DevTools 流程

history list / history search / history stats 可查看已加载的历史记录。

Instacart 没有提供规范的订单历史 GraphQL 操作，因此旧版 history sync 命令无法使用。原因请参阅 docs/solutions/best-practices/instacart-orders-no-clean-graphql-op.md。

自然语言 add

通过 Instacart 自有的三步 GraphQL 调用链（ShopCollectionScoped -> Autosuggestions -> Items），从自由文本解析商品，并触发 UpdateCartItemsMutation。无需浏览器自动化。

当 Instacart 因 notFoundBasketProduct 拒绝候选商品时（自动建议偶尔会显示无法添加到当前购物车所在商店的商品），add 会自动重试最多 3 个排名靠前的候选商品，之后才放弃。在 --json 输出中，重试成功时会设置 retry_count > 0，并包含列出被拒绝商品 ID 的 attempts 数组。通过优先使用历史记录的解析方式遇到同样的错误时，add 会转而进行实时搜索，并报告 resolved_via: "history->live"。

多零售商 carts

carts list 会一次显示所有零售商的活跃购物车。适用于需要在添加商品前确认商品所在位置的 Agent。

命令参考

身份验证：

• instacart auth login - 从 Chrome 提取会话 Cookie
• instacart auth status - 显示当前会话状态
• instacart auth logout - 清除已保存的 Cookie
• instacart auth paste - 手动粘贴 Cookie JSON（适用于较新版本 macOS Chrome 的备用方式）
• instacart auth import-file <path> - 从 browser-use 导出的 JSON 文件加载 Cookie

购物车操作：

• instacart add <retailer> <query...> - 通过自然语言添加商品
• instacart add <retailer> <query...> --no-history - 跳过优先使用历史记录的解析器
• instacart add --item-id <id> <retailer> - 通过精确的 Instacart 商品 ID 添加商品
• instacart cart show <retailer> - 显示某零售商当前购物车的内容
• instacart cart remove <item-id> <retailer> - 从购物车中移除商品
• instacart carts list - 列出所有零售商的活跃购物车

发现：

• instacart search <query> --store <retailer> - 在某零售商处搜索商品
• instacart retailers list - 列出你所在地址可用的零售商
• instacart retailers show <slug> - 在本地缓存某个零售商

购买历史：

• instacart history import <path> - 将 JSONL 订单转储文件加载到本地数据库（推荐方式）
• instacart history import - --json - 从标准输入读取，输出 JSON 供 Agent 工作流使用
• instacart history import <path> --dry-run - 预览数量，不写入数据
• instacart history list - 按购买次数和近期程度列出购买最多的商品
• instacart history list --store <retailer> --limit 20 - 筛选并分页
• instacart history search <query> - 对购买历史进行 FTS 搜索
• instacart history search <query> --store <retailer> - 按范围进行 FTS 搜索
• instacart history stats - 显示数量和各零售商的状态

维护：

• instacart doctor - 健康检查：配置、存储、操作、历史记录、会话、实时 ping
• instacart capture - 刷新 GraphQL 操作哈希缓存
• instacart capture --remote - 从社区注册表合并最新哈希
• instacart ops list - 显示操作哈希缓存状态

使用示例

首次设置

instacart auth login                # extract cookies from Chrome
instacart doctor                    # verify auth + live ping
instacart capture                   # seed built-in op hashes

然后回填历史记录（可选，但建议执行；可启用优先使用历史记录的 add）：

告诉 Agent：“回填我的 instacart 订单”

该技能会处理其余步骤。请参阅下方的“回填流程”一节。

添加常买的商品

instacart add safeway "oat milk"    # resolves via local history if you have bought it before

查看输出中的 via history。如果看到 via live，说明 FTS 匹配未通过置信度检查；运行 instacart history search "oat milk" --store safeway，查看历史记录中的实际内容。

强制进行新的实时搜索

instacart add safeway "oat milk" --no-history --dry-run --json

调试时可以使用 --dry-run --json——输出中包含 resolved_via，可据此查看将采用哪条路径。

根据近期历史记录补充日常所需商品

instacart history list --store safeway --limit 20 --json | jq -r '.[].name' \
  | while read item; do instacart add safeway "$item" --yes --json; done

身份验证设置

需要在 Chrome 中登录 Instacart。CLI 会通过 kooky 提取 Cookie（我们不会处理凭据）。如果 Chrome 已锁定，或者你使用的系统无法让 kooky 读取 Cookie：

instacart auth paste         # paste the full cookie JSON manually
instacart auth import-file <path>

会话保存在 ~/.config/instacart/session.json（0600）。

位置设置

Instacart 的 GraphQL API 要求每次查询零售商时都提供位置信息（latitude/longitude 或 address_id）。如果缺少这些信息，search、add 和 cart show 会在 ShopCollectionScoped 引导步骤失败。

auth login 后的步骤会从你的默认 Instacart 地址自动填充 address_id、postal_code、latitude 和 longitude。如果未能成功，Agent 应改用以下方法之一：

• instacart config set-address --id <uuid> — 通过缓存的 GetAddressById 操作，根据已知的 Instacart 地址 ID 获取坐标。在 https://www.instacart.com/store/account/your-account 的 URL 或 GraphQL 变量中查找该 ID（DevTools 的 Network 标签页）。
• instacart config set-coords --lat <N> --lon <N> [--postal <zip>] — 直接传入坐标（在 Google Maps 中右键点击 → “这里是什么？”即可获取纬度/经度）。
• instacart config show — 确认当前设置。

如果缺少位置信息，instacart doctor 会显示 location: fail 检查结果，这样驱动 CLI 的 Agent 就能在调用实际命令前检测到此问题。

多个地址（命名配置档案）

config profiles 是建立在单一活动位置配置之上的命名地址库。用户有多个配送地址（家、工作地点、度假屋），并希望切换地址而不必每次都重新运行 config set-address 时，可以使用它。

• instacart config profiles list — 显示已保存的配置档案；活动档案旁会标有 *。
• instacart config profiles add <name> --id <address_id> [--label "..."] [--use] — 根据 Instacart 地址 ID 保存配置档案（使用 GetAddressById 填充坐标）。传入 --use 还可将其设为活动档案。
• instacart config profiles add <name> --lat <N> --lon <N> [--postal <zip>] [--label "..."] — 根据原始坐标保存配置档案，不会发起网络请求。
• instacart config profiles use <name> — 切换活动档案（将其位置信息复制到顶层配置键，因此所有下游调用都会使用该位置）。
• instacart config profiles show <name> — 显示一个配置档案。
• instacart config profiles rm <name> — 删除一个配置档案。如果该档案处于活动状态，则会清除活动档案，现有顶层配置仍会生效。
• instacart config profiles import [--prefix <p>] [--overwrite] [--use <name>] — 从用户的 Instacart 账户获取所有已保存地址（通过 CurrentUserAddresses），并将每个地址保存为配置档案，同时将街道地址转换为适合作为名称的格式。

单次调用覆盖：对任何需要位置信息的命令传入 --profile <name>（例如，instacart --profile work add safeway "cold brew"）。这只会在此次调用中应用命名配置档案，不会更改活动档案。

未定义任何配置档案时，CLI 的行为与之前完全一致——config set-coords / set-address / show 会继续直接控制顶层位置键。

Agent 模式

CLI 默认适用于 Agent。在任何命令上添加 --json 可获取机器可读的输出。--dry-run 会预览 add，而不会触发变更，并显示将会使用哪个解析器（history、live 或 item-id）。

需要了解的 add JSON 信封字段：

• resolved_via：可能为 history、live、history->live（历史记录中的选项被拒绝，实时重试成功）或 item-id。
• retry_count：胜出项之前被拒绝的候选项数量。首次选择即成功时为 0。
• attempts：仅在 retry_count > 0 时出现，是一个包含每个被拒绝候选项 {item_id, name, error_type} 的数组。
• 耗尽时（退出码为 5）：JSON 信封包含 error、retailer、query、attempts，以及 hint，其中指出具体的后续步骤（先运行 search 再运行 add --item-id，或使用 --no-history 重试）。

筛选输出

--select 接受点分隔路径，用于深入访问嵌套响应；数组会逐元素遍历：

instacart-pp-cli <command> --agent --select id,name
instacart-pp-cli <command> --agent --select items.id,items.owner.name

使用此功能可将庞大的有效负载缩减到你实际需要的字段，这对于深度嵌套的 API 响应尤为重要。

响应封装

数据层命令会将输出封装为 {"meta": {...}, "results": <data>}。解析 .results 获取数据，并查看 .meta.source 以确认来源是 live 还是本地数据。只有当 stdout 是 TTY 时，N results (live) 摘要才会输出到 stderr；通过管道传输或由 Agent 使用时，stdout 中只有纯 JSON。

退出代码

代码	含义
0	成功
2	用法错误
3	缺少身份验证或身份验证被拒绝
4	未找到资源
5	API 错误 / 冲突
7	触发速率限制或遇到暂时性网络错误

参数解析

对于自由形式的自然语言请求：

1. 输入为空、help 或 --help -> 运行 instacart --help
2. 以 install 开头 -> 安装 CLI；以 mcp 结尾 -> 安装 MCP
3. 符合历史回填意图 -> 运行下方的历史回填流程。触发短语包括：“回填我的订单”“回填我的历史记录”“同步我的 Instacart 历史记录”“同步我的 Instacart 订单”“下载我的订单历史记录”“将我的 Instacart 历史记录保存在本地”“导入我之前的订单”“导入我最近的订单”。
4. 其他情况 -> 映射到最合适的子命令；由 Agent 调用时，附带 --json 运行

历史回填流程

当用户表达历史回填意图时，按此流程操作。通过 WebFetch 读取 docs/backfill-walkthrough.md 获取完整步骤；摘要如下。

准备检查：

1. 确认 instacart-pp-cli 在 PATH 中。如果没有，则安装：go install github.com/mvanhorn/printing-press-library/library/commerce/instacart/cmd/instacart-pp-cli@latest。
2. 探测 mcp__claude-in-chrome__tabs_context_mcp。如果该工具不可用，则转到 DevTools 备用流程：获取 docs/backfill-devtools-fallback.md，并引导用户完成操作。然后停止。
3. 运行 instacart-pp-cli history stats --agent。如果订单数 > 0，则这是一次增量补录；恢复状态会自动跳过已导出的订单。

Chrome MCP 循环：

1. 使用 WebFetch 获取以下 3 个 JS 文件（在当前会话中分别缓存）：
   • https://raw.githubusercontent.com/mvanhorn/printing-press-library/main/library/commerce/instacart/docs/dumper.js
   • https://raw.githubusercontent.com/mvanhorn/printing-press-library/main/library/commerce/instacart/docs/extract-one.js
   • https://raw.githubusercontent.com/mvanhorn/printing-press-library/main/library/commerce/instacart/docs/export-jsonl.js
2. 在 https://www.instacart.com/store/account/orders 打开一个标签页或复用现有标签页。如果 dumper 返回 profile_picker: true，请用户在标签页中选择一个档案，然后重新运行。
3. 通过 mcp__claude-in-chrome__javascript_tool 注入 dumper.js。读取 total_ids 和 pending_extract。
4. 对待处理集合中的每个订单 ID，导航到 /store/orders/<id>，然后注入 extract-one.js。每处理 10 个订单，向用户报告一次进度。
5. 当待处理数量变为 0 时，注入 export-jsonl.js。它会将 instacart-orders.jsonl 下载到用户的默认 Downloads 文件夹。
6. 在 Bash 工具中运行 instacart-pp-cli history import ~/Downloads/instacart-orders.jsonl --agent。向用户展示摘要 JSON。
7. 验证：运行 instacart-pp-cli history stats --agent。可进一步进行合理性检查：运行 instacart-pp-cli add <retailer> "<something they've bought>" --dry-run --json；当出现 resolved_via: "history" 时，将其标出。

值得向用户说明的错误情况：

• 每个订单都出现提取器错误 cache_key_missing -> Instacart 更换了网页包。报告观察到的缓存键，并指向 walkthrough 文档中的轮换恢复部分。
• Dumper 报告的 ID 数量少于用户预期 -> 可能是多档案账户；请确认选中的档案包含购买历史记录。
• history import 显示导入 0 个订单 -> JSONL 文件为空（只包含跳过记录）。请使用新标签页重新运行提取器循环。

直接使用

1. 检查是否已安装：which instacart-pp-cli
2. 检查身份验证：instacart doctor
3. 捕获 GraphQL 哈希：instacart capture
4. （可选，但建议）回填历史记录 — 运行上方的回填流程。启用以历史记录优先的 add 解析方式。
5. 如果由 Agent 调用，请使用 --json 运行命令