pp-amazon-seller

Amazon Seller — Printing Press CLI

前提条件：安装 CLI

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

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

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

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

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

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

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

命令参考

catalog — 读取 Catalog Items API 商品数据。

• amazon-seller-pp-cli catalog get — 按 ASIN 获取一项目录商品。
• amazon-seller-pp-cli catalog search — 搜索目录商品。提供 marketplaceIds，以及一种有效的搜索模式，例如 keywords 或 identifiers，后接...

fba-inventory — 查看 Fulfillment by Amazon 库存摘要。

• amazon-seller-pp-cli fba-inventory — 列出 FBA 库存摘要。对于北美市场的市场级库存，请传入 granularityType=Marketplace，...

listings — 读取卖家 SKU 的 Listings Items API 数据。

• amazon-seller-pp-cli listings get — 按卖家 ID 和 SKU 获取一项商品刊登。
• amazon-seller-pp-cli listings search — 搜索某卖家的商品刊登。

orders — 搜索和查看 Orders API v2026-01-01 订单记录。

• amazon-seller-pp-cli orders get — 获取一笔 Orders API v2026-01-01 订单。
• amazon-seller-pp-cli orders search — 搜索订单。必须且只能提供 createdAfter 或 lastUpdatedAfter 中的一个；组合无效时，Amazon 会返回 400 错误。

reports — 创建报告、轮询报告状态并查看报告文档元数据。

• amazon-seller-pp-cli reports create — 创建报告请求。对于 JSON 请求体，优先使用 --stdin，以确保 marketplaceIds 保持为 JSON 数组，且 reportOptions...
• amazon-seller-pp-cli reports document — 获取报告文档元数据和预签名下载 URL。此命令不会下载或打开文档。
• amazon-seller-pp-cli reports get — 按报告 ID 获取一份报告。这是用于手动轮询报告处理状态的端点。
• amazon-seller-pp-cli reports list — 列出报告。如果设置了 nextToken，Amazon 要求它必须是唯一的查询参数；请勿同时传入其他筛选条件，...

inbound-plans — 创建和管理 Fulfillment Inbound v2024-03-20 入库计划。

• amazon-seller-pp-cli inbound-plans create --marketplace-id ATVPDKIKX0DER --source-address address.json --items items.csv --name "June FBA" — 根据 CSV/JSON 输入预览 createInboundPlan 请求正文。**写入命令：**传入 --yes 以发送，传入 --dry-run 以呈现 HTTP 请求，传入 --wait 以轮询返回的操作。
• amazon-seller-pp-cli inbound-plans create --stdin — 从标准输入读取 Amazon 的准确 createInboundPlan JSON 请求正文。**写入命令：**传入 --yes 以发送。
• amazon-seller-pp-cli inbound-plans status --operation-id <operationId> --wait — 轮询 getInboundOperationStatus，查看异步 Fulfillment Inbound POST/PUT 操作的状态。
• amazon-seller-pp-cli inbound-plans get <inboundPlanId> — 获取一个入库计划。
• amazon-seller-pp-cli inbound-plans list --status ACTIVE --page-size 10 — 列出入库计划。
• amazon-seller-pp-cli inbound-plans cancel <inboundPlanId> --yes — 取消入库计划。**写入命令：**除非设置了 --dry-run，否则必须传入 --yes。
• amazon-seller-pp-cli inbound-plans packing generate --inbound-plan-id <id> — 生成装箱选项。**写入命令：**使用 --dry-run 预览请求。
• amazon-seller-pp-cli inbound-plans packing list --inbound-plan-id <id> — 列出装箱选项。
• amazon-seller-pp-cli inbound-plans packing confirm --inbound-plan-id <id> --option-id <packingOptionId> --yes — 确认装箱选项。**写入命令：**除非设置了 --dry-run，否则必须传入 --yes。
• amazon-seller-pp-cli inbound-plans packing set --inbound-plan-id <id> --body cartons.json --yes — 设置箱级装箱信息。**写入命令：**除非设置了 --dry-run，否则必须传入 --yes。
• amazon-seller-pp-cli inbound-plans placement generate --inbound-plan-id <id> --body placement.json — 生成入库地点选项，可选提供 customPlacement JSON。**写入命令：**提供正文时，传入 --yes 以发送而非预览。
• amazon-seller-pp-cli inbound-plans placement list --inbound-plan-id <id> — 列出入库地点选项。
• amazon-seller-pp-cli inbound-plans placement confirm --inbound-plan-id <id> --option-id <placementOptionId> --yes — 确认入库地点选项。**写入命令：**除非设置了 --dry-run，否则必须传入 --yes。
• amazon-seller-pp-cli inbound-plans transportation generate --inbound-plan-id <id> --body transportation.json — 根据入库地点/货件 JSON 生成运输选项。**写入命令：**提供正文时，传入 --yes 以发送而非预览。
• amazon-seller-pp-cli inbound-plans transportation list --inbound-plan-id <id> --placement-option-id <placementOptionId> — 列出运输选项。
• amazon-seller-pp-cli inbound-plans transportation confirm --inbound-plan-id <id> --body selections.json --yes — 确认运输选择。**写入命令：**除非设置了 --dry-run，否则必须传入 --yes。

使用 CSV 输入商品时，请使用以下列：msku,quantity,prepOwner,labelOwner,expiration,manufacturingLotCode。对于美国商城 ATVPDKIKX0DER，如果 prepOwner=AMAZON 或 labelOwner=AMAZON，CLI 会发出警告，因为 Amazon 表示，自 2026 年 1 月 1 日起，美国 FBA 的商品预处理和商品标签服务将不再提供。

profitability — 根据 Amazon 报告计算预估 SKU 盈利能力。

• amazon-seller-pp-cli profitability sku-pnl --marketplace-id ATVPDKIKX0DER --days 30 — 估算每个 SKU 的收入、费用、仓储成本、利润率和利润。

• amazon-seller-pp-cli profitability fee-breakdown --marketplace-id ATVPDKIKX0DER — 显示预估推荐费、FBA 费用、成交费和总费用的明细百分比。

• amazon-seller-pp-cli profitability settlement-reconciliation --marketplace-id ATVPDKIKX0DER --days 90 — 将订单收入与已完成的结算行进行比较，并标记差异。

• amazon-seller-pp-cli profitability reimbursements --marketplace-id ATVPDKIKX0DER --days 90 — 按 SKU 和原因汇总赔偿款。 inventory-intel — 计算 FBA 库存健康度、补货、库龄和配送建议。

• amazon-seller-pp-cli inventory-intel health-score --marketplace-id ATVPDKIKX0DER — 评估各 SKU 的库存健康度。

• amazon-seller-pp-cli inventory-intel restock --marketplace-id ATVPDKIKX0DER --lead-time-days 14 — 估算缺货时间和补货数量。

• amazon-seller-pp-cli inventory-intel stranded --marketplace-id ATVPDKIKX0DER — 找出滞留库存记录并给出建议操作。

• amazon-seller-pp-cli inventory-intel aging --marketplace-id ATVPDKIKX0DER --warn-days 150 — 预测长期仓储费风险。

• amazon-seller-pp-cli inventory-intel fba-vs-fbm --marketplace-id ATVPDKIKX0DER --estimated-shipping-cost 5 — 比较 FBA 与 FBM 的预估单件利润。

sales-intel — 计算销售、流量、转化率、销量趋势和退货分析数据。

• amazon-seller-pp-cli sales-intel dashboard --marketplace-id ATVPDKIKX0DER --days 30 --group-by date — 汇总销售与流量报告指标。
• amazon-seller-pp-cli sales-intel velocity --marketplace-id ATVPDKIKX0DER --days 60 — 检测 SKU 销量趋势和异常。
• amazon-seller-pp-cli sales-intel returns --marketplace-id ATVPDKIKX0DER --days 30 — 分析退货率、原因和客户评论。
• amazon-seller-pp-cli sales-intel conversion-funnel --marketplace-id ATVPDKIKX0DER --days 30 — 诊断流量、购物车赢得率和转化瓶颈。

brand-analytics — 计算品牌注册搜索词和购物篮洞察。

• amazon-seller-pp-cli brand-analytics search-terms --marketplace-id ATVPDKIKX0DER --period WEEK — 显示受跟踪 ASIN 出现在点击量最高位置的搜索词。
• amazon-seller-pp-cli brand-analytics market-basket --marketplace-id ATVPDKIKX0DER --period WEEK — 显示经常与您的 ASIN 一同购买的商品。

listing-intel — 根据报告和本地商品信息审核商品信息缺陷与完整度。

• amazon-seller-pp-cli listing-intel health-audit --marketplace-id ATVPDKIKX0DER — 汇总商品信息缺陷提醒和抑制信号。
• amazon-seller-pp-cli listing-intel catalog-completeness --marketplace-id ATVPDKIKX0DER --seller-id <seller> — 根据本地商品记录评估图片、要点、标题和 A+ 内容的完整度。

account-health — 汇总账户层面的商品信息、库存、退货和赔偿健康状况。

• amazon-seller-pp-cli account-health dashboard --marketplace-id ATVPDKIKX0DER — 生成一个仪表板，汇总被抑制的商品信息、滞留商品数量、退货率、赔偿、缺陷数量和库存等级。

sellers — 验证卖家授权并列出市场参与情况。

• amazon-seller-pp-cli sellers — 列出已授权卖家账户的市场参与情况。

查找合适的命令

如果您知道要做什么，但不知道该用哪个命令，可以直接向 CLI 提问：

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

which 会根据此 CLI 精选的功能索引，将自然语言功能查询匹配到最合适的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可信的匹配项——请改用 --help，或使用更具体的查询。

身份验证设置

在服务提供商控制台中授权您的私有应用，导出 OAuth 客户端 ID、OAuth 客户端密钥和刷新令牌，然后运行 doctor：

export SP_API_LWA_CLIENT_ID="<client-id>"
export SP_API_LWA_CLIENT_SECRET="<client-secret>"
export SP_API_REFRESH_TOKEN="<refresh-token>"
amazon-seller-pp-cli doctor

CLI 会在首次实时使用时将刷新令牌交换为访问令牌，并在本地缓存该访问令牌。

运行 amazon-seller-pp-cli doctor 验证设置。

Agent 模式

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

• 可通过管道传输 — JSON 输出到 stdout，错误输出到 stderr

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

  amazon-seller-pp-cli catalog get <asin> --marketplace-ids ATVPDKIKX0DER --agent --select asin,attributes,summaries
  

• 可预览 — --dry-run 显示请求，但不发送

• 适合离线使用 — 如果本地 SQLite 存储可用，同步／搜索命令可以使用它

• 非交互式 — 绝不提示输入；所有输入都通过标志传入

• 显式重试 — 仅当已存在的创建操作也应视为成功时，才使用 --idempotent

响应封装

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

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

解析 .results 获取数据，并查看 .meta.source 以判断数据来自实时来源还是本地来源。只有当 stdout 连接到终端时，才会向 stderr 打印人类可读的 N results (live) 摘要；通过管道或 Agent 消费时，stdout 只会输出纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

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

条目会本地存储在 ~/.amazon-seller-pp-cli/feedback.jsonl。除非设置了 AMAZON_SELLER_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 AMAZON_SELLER_FEEDBACK_AUTO_SEND=true，否则绝不会发送 POST 请求。默认情况下仅存储在本地。

写下让你感到意外的地方，而不是提交 bug 报告。简短、具体、一行即可：这正是能不断积累价值的内容。

输出交付

每个命令都接受 --deliver <sink>。输出会写入指定的目标位置，同时也会写入 stdout，或取代 stdout 输出，因此 Agent 无需手动通过管道传输，就能路由命令结果。支持三种目标：

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

遇到未知方案时会拒绝执行，并返回列出受支持方案的结构化错误。Webhook 请求失败时会返回非零状态码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

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

amazon-seller-pp-cli profile save briefing --json
amazon-seller-pp-cli --profile briefing sellers marketplaces
amazon-seller-pp-cli profile list --json
amazon-seller-pp-cli profile show briefing
amazon-seller-pp-cli profile delete briefing --yes

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

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	触发速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 amazon-seller-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 请参阅上文的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并附带 --agent）

MCP 服务安装

1. 安装 MCP 服务：

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

2. 在 Claude Code 中注册：

   claude mcp add amazon-seller-pp-mcp -- amazon-seller-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

   amazon-seller-pp-cli <command> [subcommand] [args] --agent
   

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