pp-amazon-orders

Amazon Orders — Printing Press CLI

前置条件：安装 CLI

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

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

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

2. 验证：amazon-orders-pp-cli --version
3. 确保报告的安装目录已添加到将调用此技能的 Agent/运行时的 $PATH 中。

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

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

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

何时使用此 CLI

当 Agent 需要综合查看用户的 Amazon 订单历史时，请使用 amazon-orders-pp-cli，例如追踪多个订单、检测定期购买、汇总支出，或通过 FTS5 搜索“我什么时候订购的那条 USB-C 线”。本地 SQLite 存储让跨订单问题能够即时得到解答，无需再次访问 Amazon，也不会因为完整 HTML 页面而消耗上下文。

何时不使用此 CLI

对于需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或更改远程状态的请求，请勿启用此 CLI。此 CLI 仅提供用于检查、导出、同步和分析的只读命令。

独特功能

这些功能在任何其他用于此 API 的工具中都不可用。

持续累积的本地状态

• where-is-my-stuff — 在一个视图中显示所有运输中的 Amazon 包裹及其当前状态和预计送达时间。

  当 Agent 需要跨多个订单回答“我的包裹今天会到吗”时，这个工具可以一次性给出结果。

  amazon-orders-pp-cli where-is-my-stuff --json --select orderId,status,etaDate,carrier
  

• delivery-slips — 实际送达日期比原始预计日期晚超过 N 天的订单。

  无需手动逐一查看所有订单，即可发现不可靠的承运商和卖家。

  amazon-orders-pp-cli delivery-slips --days 3 --since 2025-01-01 --json
  

• spend — 按月、年、类别、卖家或付款方式细分支出。

  让 Agent 能够一次性回答预算、费用报告和趋势分析相关问题。

  amazon-orders-pp-cli spend --by month --year 2025 --json
  

• top-items — 按购买频率或总支出统计最常订购的商品，并按 ASIN 汇总全部历史记录。

  帮助 Agent 判断用户实际会消耗哪些商品，而非只买过一次的商品。

  amazon-orders-pp-cli top-items --by total-spend --limit 20 --json
  

• subscribe-and-save — 根据订单历史推断定期购买（同一 ASIN 按固定周期订购）。

  找出可实际加入 S&S 的商品，并检测用户可能未意识到的事实订阅。

  amazon-orders-pp-cli subscribe-and-save --min-occurrences 3 --json
  

• arriving-soon — 显示未来 N 天内送达的包裹，并按预计送达时间排序。

  让 Agent 能够根据即将送达的包裹安排计划（例如：“我的路由器会在周五会议前送到吗？”）。

  amazon-orders-pp-cli arriving-soon --days 7 --json
  

• late — 已超过原始预计送达日期的在途包裹。

  无需手动检查，承运商延误一发生就能立即发现。

  amazon-orders-pp-cli late --json
  

面向 Agent 的基础功能

• find — 使用 FTS5 搜索订单、商品、卖家和追踪备注。

  直接回答“我什么时候订购的那个东西”，无需翻阅多年的订单历史。

  amazon-orders-pp-cli find 'usb-c cable' --json --select orderId,placedDate,total
  

发现信号

此 CLI 根据浏览器观察到的流量上下文生成。

• 捕获覆盖范围：共 6 条网络记录，其中捕获 6 条 API 记录
• 协议：html_cookie（85% 置信度）

命令参考

gift_cards — 礼品卡余额和活动记录。

• amazon-orders-pp-cli gift_cards — 当前礼品卡余额及活动记录：金额、类型（充值/使用/退款）、日期、关联订单 ID。

orders — 买家端订单历史列表和每个订单的详情页。

• amazon-orders-pp-cli orders get — 单个订单的完整详情：商品、ASIN、价格、配送、付款方式、收货地址、总额。
• amazon-orders-pp-cli orders invoice — 订单的可打印发票（HTML），适用于 VAT/费用核对。
• amazon-orders-pp-cli orders list — 获取一页订单历史记录。使用 timeFilter（year-2026、last30days、months-3）和 startIndex 分页。

shipments — 每个包裹的追踪详情。

• amazon-orders-pp-cli shipments — 单个配送的追踪详情：承运商、追踪号码、状态、预计送达时间、送达确认。

transactions — 所有订单、定期服务和 Prime 的扣款与退款。

• amazon-orders-pp-cli transactions — 交易列表的第一页，按日期分组。每行包含付款方式、卡号后 4 位、带正负号的金额，以及（当...

手写命令

• amazon-orders-pp-cli sync — 将订单历史同步到本地 SQLite 存储。增量同步请使用 --since 90d，重新遍历全部内容请使用 --full。
• amazon-orders-pp-cli orders list — 列出订单，使用 --time-filter（year-YYYY、last30days、months-3）和 --start-index 分页。
• amazon-orders-pp-cli orders get <order-id> — 显示单个订单的完整详情（商品、配送、付款、总额）。
• amazon-orders-pp-cli orders invoice <order-id> — 打印单个订单的发票。
• amazon-orders-pp-cli shipments --order-id <id> — 查看单个订单配送的追踪详情。
• amazon-orders-pp-cli track <order-id> — 查看单个订单的实时追踪信息：承运商、追踪号码、状态、预计送达时间。
• amazon-orders-pp-cli where-is-my-stuff — 在一个视图中显示所有运输中的配送及其当前状态和预计送达时间。
• amazon-orders-pp-cli arriving-soon --days 7 — 查看未来 N 天内送达的配送，按预计送达时间排序。
• amazon-orders-pp-cli late — 查看已超过预计送达日期的配送。
• amazon-orders-pp-cli delivery-slips --days 3 --since 2025-01-01 — 查看实际送达时间比原预计时间晚了超过 N 天的订单。（需要同步历史记录。）
• amazon-orders-pp-cli spend --by month --year 2026 — 按月份、年份、收货地址或状态汇总支出。
• amazon-orders-pp-cli top-items --by count --limit 20 — 查看历史订单中订购次数最多的商品/ASIN。
• amazon-orders-pp-cli returns — 查看已退回的商品，并关联订单 <-> 交易。（需要同步历史记录。）
• amazon-orders-pp-cli subscribe-and-save --min-occurrences 3 — 事实上的订阅检测器。（需要同步历史记录。）
• amazon-orders-pp-cli carriers --rank — 按承运商查看准时送达率。（需要同步历史记录。）
• amazon-orders-pp-cli find '<query>' — 在订单、商品、ASIN 和卖家中进行全文搜索。
• amazon-orders-pp-cli transactions — 查看扣款与退款（交易页面解析器）。
• amazon-orders-pp-cli gift-cards — 查看礼品卡余额和活动记录。

新鲜度约定

此 CLI 仅对已注册的、由存储支持的读取命令路径提供有限的新鲜度保障。在 --data-source auto 模式下，这些路径会检查 sync_state，并可能在读取本地数据前执行有限刷新。--data-source local 不会刷新。--data-source live 会读取 API，且不会修改本地存储。设置 AMAZON_ORDERS_NO_AUTO_REFRESH=1 可跳过新鲜度钩子，但不会改变数据源选择。

涵盖的路径：

• amazon-orders-pp-cli orders
• amazon-orders-pp-cli orders get
• amazon-orders-pp-cli orders invoice
• amazon-orders-pp-cli orders list
• amazon-orders-pp-cli transactions

当 JSON 输出使用生成的来源信息封装时，新鲜度元数据会显示在 meta.freshness。请将其视为该命令路径的当前缓存新鲜度，而非完整历史回填或特定 API 数据增强的保证。

查找合适的命令

当你知道要做什么，但不确定该用哪个命令时，可以直接询问 CLI：

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

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

示例

我正在等的东西都到哪儿了？

amazon-orders-pp-cli where-is-my-stuff --json --select orderId,status,etaDate,carrier

列出所有尚未完成的货件及其当前状态和预计送达时间——汇总查看所有在途 Amazon 订单。

我今年花了多少钱？

amazon-orders-pp-cli spend --by month --year 2026 --json

从本地存储汇总每月的 Amazon 支出；不调用实时接口，亚秒级完成。

找到我买过某件东西的那笔订单

amazon-orders-pp-cli find 'usb-c hub' --json --select orderId,placedDate,total,items.title

使用 FTS5 搜索订单和商品；通过带点号的 --select 提取 Agent 所需的字段。

哪些商品正在运送、我已被收费但还没收到？

amazon-orders-pp-cli late --json

显示预计送达时间已过的在途货件，方便 Agent 标记承运商延误。

我实际都买了些什么？

amazon-orders-pp-cli top-items --by total-spend --limit 20 --json

按总支出汇总历史上购买的所有 ASIN——找出经常购买的商品。

身份验证设置

Amazon 不提供买家 API。CLI 会通过 auth login --chrome 从已登录的 Chrome / Firefox / Safari / Brave 会话导入 Cookie。这些 Cookie 会保存在本地、自动刷新，并用于后续所有数据获取——无需 API 密钥、OAuth，也无需在运行时常驻浏览器。

对于非美国站点，请在登录时传入站点域名。印度站点示例：

amazon-orders-pp-cli auth login --chrome --domain amazon.in

你也可以在运行 auth login --chrome 前设置 AMAZON_ORDERS_BASE_URL=https://www.amazon.in。

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

使用 1Password 设置无头 Agent（不经过 LLM 的完整流程）

对于无头主机（CI、开发容器、远程 Agent），如果无法运行 auth login --chrome，请在一台已登录的机器上捕获一次会话，将其存入 1Password（或其他密钥管理器），然后注入无头主机。Cookie 值绝不会进入 LLM 的上下文窗口，因为字节通过 op → stdin → CLI 流转，不会经过 LLM 可读取的 Shell 变量。

存入一次（在已登录的机器上）：

TMP=$(mktemp -t amazon-orders-session.XXXXXX.json)
chmod 600 "$TMP"
amazon-orders-pp-cli auth export --output "$TMP" --note "captured $(date -u +%FT%TZ) from $(hostname)"
op document create "$TMP" \
  --title 'amazon-orders-session' \
  --vault Agent \
  --tags 'cli-session,amazon-orders,printing-press'
shred -u "$TMP" 2>/dev/null || rm -f "$TMP"

在其他每台机器上注入：

# Long form (separate fetch + import):
op document get 'amazon-orders-session' --vault Agent \
  | amazon-orders-pp-cli auth import --stdin

# Short form via op:// URI (works in direnv, agent configs, K8s init containers):
op read "op://Agent/amazon-orders-session/file" \
  | amazon-orders-pp-cli auth import --stdin

这两种方式都会将 Cookie 数据写入 ~/.config/amazon-orders-pp-cli/config.toml，并完成身份验证。使用以下两项进行验证：

amazon-orders-pp-cli auth status
amazon-orders-pp-cli doctor --agent

auth status 只会确认已配置 Cookie 数据。即使 doctor 仍报告缺少或过期的 browser_session_proof，它也可能显示 Authenticated；在这种情况下，实时命令可能会返回空结果或 null，而不是订单。对于无头环境中的 1Password 导入，请将 doctor 视为端到端验证步骤。

如果 doctor 报告浏览器会话证明已过期或缺失，请从当前已登录的 Chrome 配置文件刷新，然后重新运行 doctor：

python3 -m pip install --user pycookiecheat  # if doctor says cookie_tool not found
export PATH="$PATH:$HOME/go/bin:$(python3 -m site --user-base)/bin"
amazon-orders-pp-cli auth login --chrome --no-input --yes
amazon-orders-pp-cli doctor --agent

如果已从 Chrome 捕获新 Cookie，并希望其他无头 Agent 使用这些 Cookie，请更新 1Password 文档，但不要输出 Cookie 内容：

TMP=$(mktemp "${TMPDIR:-/tmp}/amazon-orders-session.XXXXXX")
chmod 600 "$TMP"
amazon-orders-pp-cli auth export --output "$TMP" --note "captured $(date -u +%FT%TZ) from $(hostname)" &&
  op document edit 'amazon-orders-session' --vault Agent "$TMP"
shred -u "$TMP" 2>/dev/null || rm -f "$TMP"

当 Amazon 轮换 session-id 时刷新（通常每隔几周一次；orders list 返回 401 时表明发生了轮换）：

amazon-orders-pp-cli auth login --chrome           # on the logged-in machine
amazon-orders-pp-cli auth export --output /tmp/s.json
op document edit 'amazon-orders-session' --vault Agent /tmp/s.json
shred -u /tmp/s.json 2>/dev/null || rm -f /tmp/s.json

**替代方案：**任何能将内容通过管道输出到标准输出的密钥管理器都可以采用相同方式。vault kv get、aws secretsmanager get-secret-value --query SecretString --output text、pass show amazon-orders-session、bw get item amazon-orders-session | jq -r .notes 均可串接到 amazon-orders-pp-cli auth import --stdin。

**AMAZON_COOKIES 环境变量方式：**CLI 也会从此环境变量自动导入 Cookie。适用于一次性容器：

export AMAZON_COOKIES="$(op read 'op://Agent/amazon-orders-session/file')"
amazon-orders-pp-cli auth import   # reads $AMAZON_COOKIES, then exits
amazon-orders-pp-cli orders list --json

Agent 模式

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

• 可通过管道传递 — JSON 输出到标准输出，错误输出到标准错误

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

  amazon-orders-pp-cli orders list --agent --select id,name,status
  

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

• 便于离线使用 — 有本地 SQLite 存储时，同步/搜索命令可以使用该存储

• 非交互式 — 绝不提示输入，所有输入均通过标志指定

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

响应封装

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

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

解析 .results 获取数据，并查看 .meta.source 以确定数据来自实时来源还是本地来源。只有在标准输出连接到终端时，才会将人类可读的 N results (live) 摘要输出到标准错误；通过管道传输的使用方或 Agent 会在标准输出中收到纯 JSON。

Agent 反馈

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

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

条目会存储在本地 ~/.amazon-orders-pp-cli/feedback.jsonl。只有在设置了 AMAZON_ORDERS_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 AMAZON_ORDERS_FEEDBACK_AUTO_SEND=true 时，才会通过 POST 提交。默认情况下只存储在本地。

写下让你感到意外的事情，而不是 Bug 报告。简短、具体，写成一行：这才是能不断积累价值的部分。

输出交付

每条命令都接受 --deliver <sink>。除了（或代替）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-orders-pp-cli profile save briefing --json
amazon-orders-pp-cli --profile briefing orders list
amazon-orders-pp-cli profile list --json
amazon-orders-pp-cli profile show briefing
amazon-orders-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

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

2. 注册到 Claude Code：

   claude mcp add amazon-orders-pp-mcp -- amazon-orders-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

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

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