pp-shopping

购物 — Printing Press CLI

前提条件：安装 CLI

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

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

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

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

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接 Go 安装（需要 Go 1.26.6 或更高版本）。此方式会安装到 $GOPATH/bin（默认是 $HOME/go/bin），因此请将该目录添加到 $PATH：

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

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

Shopping 封装了 LemmeBuyIt 聚合零售 API（涵盖 70 多家零售商的 1.15 亿多种商品），并添加了其他工具不具备的本地 SQLite 层。index 会同步商品和价格历史；compare 会查找同一标识符对应商品的最低价零售商；deals 会跨商店执行折扣、价格、评分和库存的复合查询；arbitrage 会按 Amazon FBA 转售利润率排序；price-drops 会显示每周降价商品，leaderboard 会按折扣区间排序。原生支持 Agent 的 --json/--select、离线搜索和带类型的退出码。

何时使用此 CLI

当 Agent 需要快速解答跨零售商的零售商品相关问题时，可使用 Shopping：查找 UPC 对应的最低价零售商、筛选折扣或价格达到门槛且有库存的最佳优惠、按每周降价幅度排序，或评估 Amazon FBA 转售利润率。先同步一次，再对本地商店执行多次复合查询时，它的效果最佳。

不适用场景

请勿将此 CLI 用于：

• 下单、加入购物车或结账——它是只读数据 API。
• 非零售数据，或单个零售商自己的订单管理 API。
• 实时价格查询——基于商店数据的查询反映的是上次 index 同步时的数据，而不是货架上的实时价格。

独特能力

以下能力是此 API 的其他工具所不具备的。

可累积的本地状态

• index — 将一个或多个零售商的商品（以及可选的价格历史）拉取到快速的本地 SQLite 商店，以便其他所有查询都能即时离线运行。

  先从这里开始：compare/deals/arbitrage/分析命令都会读取 index 填充的数据。

  shopping-pp-cli index --retailer walmart --retailer target --on-sale --limit 500
  

• watch status — 固定关注的商品；每次刷新索引后，查看它们的价格变化、变化幅度，以及哪些商品达到目标价格。

  适用于跟踪精心挑选的商品自上次观察以来的变化，而不是重新抓取数据并逐一查看价格。

  shopping-pp-cli watch status --json
  

跨零售商智能分析

• compare — 查看已同步的零售商中，哪个以最低价出售完全相同的商品（按 UPC/EAN/GTIN/ASIN 识别），并按价格排序，显示价差。

  只需一次调用即可回答“哪里卖得最便宜”，而不必逐一查询 N 家零售商。

  shopping-pp-cli compare 012345678905 --lookup-type upc --in-stock --json
  

• deals — 在所有受跟踪的零售商中，用一个排序列表筛选出同时满足多项条件的优惠，例如大幅折扣、低于价格上限、评价良好且有库存。

  当 Agent 需要筛选值得用户关注的最佳优惠，而非获取原始商品列表时，选择此命令。

  shopping-pp-cli deals --min-discount 30 --max-price 100 --min-rating 4 --in-stock --sort discount --json
  

盈利能力

• arbitrage — 按在 Amazon 转售后扣除平台推荐费和 FBA 费用的净收益，对已同步商品排序，并按投资回报率和购买价格筛选。

  用于从清仓商品中筛选出真正达到转售投资回报率门槛的商品。

  shopping-pp-cli arbitrage --retailer walmart --min-roi 30 --max-buy-price 50 --in-stock --json
  

时间序列分析

• price-drops — 按美元跌幅和百分比跌幅，列出所有已同步产品中，过去一周（或 N 周）跌幅最大的产品。

  用它抢先发现最新降价，而不必手动重新获取每款产品的历史记录。

  shopping-pp-cli price-drops --weeks 1 --min-drop-pct 15 --limit 25 --json
  

• leaderboard — 根据平均折扣、促销数量或平均价格，查看已同步数据中哪些零售商和品类的折扣持续最深。

  找优惠时，用它决定先查看哪个零售商或品类。

  shopping-pp-cli leaderboard --by avg-discount --limit 15 --json
  

命令参考

amazon — 管理 amazon

• shopping-pp-cli amazon <asin> — 返回适用于图表的特定 ASIN Amazon 侧每周时间序列数据，可直接访问 amazon_price_history

retailers — 与零售商及其产品相关的操作。

• shopping-pp-cli retailers — 获取经身份验证的 API 密钥有权访问的零售商列表。

status — API 健康状况和状态检查。

• shopping-pp-cli status — 提供 API 服务当前运行状态，包括数据库连接情况。

查找合适的命令

知道想做什么，但不确定该用哪个命令时，可直接向 CLI 提问：

shopping-pp-cli which "<capability in your own words>"

which 会根据自然语言功能查询，从此 CLI 精选的功能索引中匹配最合适的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示没有足够可靠的匹配项，此时可改用 --help 或缩小查询范围。

使用示例

查找某 UPC 的最低价零售商

shopping-pp-cli compare 012345678905 --lookup-type upc --in-stock --json --select results.retailer_id,results.current_price

跨零售商比较仅保留 Agent 执行操作所需的两个字段。

最划算的有货优惠

shopping-pp-cli deals --min-discount 40 --max-price 75 --in-stock --sort discount --limit 20 --json

在已同步商店中，按折扣对折扣、价格和库存查询结果进行复合排序。

FBA 套利候选清单

shopping-pp-cli arbitrage --retailer walmart --min-roi 30 --max-buy-price 50 --json --select results.product_name,results.roi,results.net_margin

按 ROI 为转售候选项排序，仅选取决策所需字段。

本周跌幅最大的商品

shopping-pp-cli price-drops --weeks 1 --min-drop-pct 20 --limit 25 --json

对所有已同步产品进行每周时间序列差值排序。

身份验证设置

使用单个 LemmeBuyIt API 密钥进行身份验证，该密钥会作为 X-API-Key 标头随每个请求发送（设置 SHOPPING_API_KEY，或运行 shopping-pp-cli auth set-token <key>）。免费密钥可访问 /shopping/ 产品界面；付费密钥还可解锁完整产品搜索、每周价格历史、Amazon ASIN 历史，以及为 arbitrage 提供支持的 Amazon 盈利能力数据。请访问 https://www.lemmebuyit.com/developer 获取密钥。

运行 shopping-pp-cli doctor 验证设置。

Agent 模式

在任意命令后添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 支持管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 支持筛选 — --select 保留字段子集。点分路径可深入嵌套结构；数组则逐元素遍历。对于输出冗长的 API，这对控制上下文大小至关重要：

  shopping-pp-cli retailers --agent --select id,name,status
  

• 支持预览 — --dry-run 显示请求但不发送

• 支持离线使用 — 如果本地 SQLite 存储可用，同步和搜索命令可使用该存储

• 非交互式 — 不会发出提示，所有输入均通过标志传入

• 只读 — 不要使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他会修改数据的请求

响应封装

从本地存储或 API 读取数据的命令会将输出封装在来源信息中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

从 .results 解析数据，并通过 .meta.source 判断数据来自实时 API 还是本地存储。只有当 stdout 连接到终端，且未设置机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将便于人类阅读的 N results (live) 摘要输出到 stderr；通过管道传输的内容、Agent 使用的内容以及显式指定格式的运行都只会在 stdout 输出纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有什么不对劲时，请记录下来：

shopping-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
shopping-pp-cli feedback --stdin < notes.txt
shopping-pp-cli feedback list --json --limit 10

条目会存储在本地的 ~/.local/share/shopping-pp-cli/feedback.jsonl 中。除非设置了 SHOPPING_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 SHOPPING_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认行为是仅存储在本地。

记录让你感到意外的事情，而不是提交错误报告。简短、具体、一行即可：这些细节会不断累积。

输出交付

每个命令都接受 --deliver <sink>。输出除了写入标准输出（stdout）外，也会发送到指定的目标；也可以只发送到该目标，因此 Agent 无需手动管道即可路由命令结果。支持三种目标：

目标	效果
stdout	默认；仅写入标准输出
file:<path>	以原子方式将输出写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到 URL（传入 --compact 时使用 application/json 或 application/x-ndjson）

不支持的协议会被拒绝，并返回一条结构化错误，指出支持的目标。Webhook 请求失败时会返回非零状态，并在标准错误输出中记录 URL 和 HTTP 状态。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。如果定时运行的 Agent 每次都使用相同配置调用同一命令，就可以使用配置——这就是 HeyGen 的 “Beacon” 模式。

shopping-pp-cli profile save briefing --json
shopping-pp-cli --profile briefing retailers
shopping-pp-cli profile list --json
shopping-pp-cli profile show briefing
shopping-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便可进行自省的 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数不正确）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求过于频繁（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 shopping-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他情况 → 直接使用（将其作为 CLI 命令执行，并加上 --agent）

安装 MCP 服务

1. 安装 MCP 服务：

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

2. 注册到 Claude Code：

   claude mcp add shopping-pp-mcp -- shopping-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which shopping-pp-cli 如果未找到，请提供安装选项（参见本技能顶部的先决条件）。
2. 根据用户查询，从上文的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   shopping-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，请查看子命令帮助：shopping-pp-cli <command> --help。