pp-ebay

eBay — Printing Press 命令行工具

前置条件：安装命令行工具

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

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

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

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

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

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

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

独特功能

这些功能无法通过此 API 的其他工具使用。

发现与分析

• auctions — 按出价数量和结束时间范围筛选正在进行的拍卖（例如“至少有 3 次出价且在接下来一小时内结束的 Steph Curry 卡片”）。自 Finding API 于 2025 年 2 月停用后，eBay 网站已无法回答此类查询。

  找到出价最后一刻确实会影响价格的竞争窗口。

  ebay-pp-cli auctions "Steph Curry rookie" --has-bids --ending-within 1h --json --select item_id,price,bids,time_left
  

• comp — 计算任意商品过去 90 天的平均成交价，并进行智能匹配、成色标准化、异常值修剪和百分位分布分析。

  评估出价价格（或判断是否值得一试）时，需要了解近期成交价的真实分布，而不是单一的参考价格。修剪可处理异常值；去重可处理标题变体。

  ebay-pp-cli comp "Cooper Flagg /50 Topps Chrome" --trim --json --select mean,median,sample_size
  

• comp 异常值修剪 — 对已售同类商品结果使用 1.5x IQR 修剪异常值。提供买家可据以判断的真实价格区间，以及标准差和四分位数。

  帮助了解普通买家实际支付的价格，而非创纪录的成交价或清仓甩卖的异常价格。

  ebay-pp-cli comp "Rolex Submariner 116610LN" --trim --json --select p25,median,p75,std_dev
  

• comp --dedupe-variants — 将近似重复的已售商品合并，每个指纹（基于词元集合，不区分顺序）保留一个示例。

  不去重时，如果同一张卡片被同一卖家发布 5 次，成交价分布就会偏向该卖家。

  ebay-pp-cli comp "Cooper Flagg /50" --dedupe-variants
  

• listings — 按拍卖/一口价、成色和价格区间筛选正在售的商品。

  ebay-pp-cli listings --nkw "PSA Mariners Griffey" --lh-bin 1 --udlo 10 --udhi 30
  

适用场景

• 用户询问“这张卡片 / 这块手表 / 这件商品卖了多少钱” → ebay-pp-cli comp "<title>" --trim
• 用户询问“查找即将结束且已有出价的拍卖” → ebay-pp-cli auctions "<query>" --has-bids --ending-within 1h
• 用户询问“查找价格低于 $X 的……一口价商品” → ebay-pp-cli listings --nkw "<query>" --lh-bin 1 --udhi <max>
• 用户询问“关注此商品”/“显示我的关注列表” → ebay-pp-cli watch list
• 用户要求以编程方式出价 → 说明此限制（eBay 在 /bfl/placebid 上对身份验证进行升级）；引导用户在浏览器中出价。不要代替用户运行 bid 或 snipe。

不适用场景

此命令行工具不适用于：

• 出价。bid/snipe/bid-group 仍处于实验阶段，无法端到端完成。请引导用户在浏览器中出价。
• 以卖家身份发布商品（请直接使用 eBay Sell API / Seller Hub）。
• 订单履行或生成运输标签。
• 卖家的批量库存管理。

已知限制

• 出价（bid、snipe、bid-group）无法端到端完成，因为 eBay 会对仅使用 Cookie 的会话在 /bfl/placebid 上进行身份验证升级。这些命令在默认的 --help 中隐藏，调用时会打印警告。用户应在浏览器中出价。
• 速率限制：持续抓取会触发 eBay 403 错误。恢复方法：运行 ebay-pp-cli auth refresh 并降低请求频率。
• 占位命令：关注列表写入、已保存搜索的 CRUD、Feed 和 Offer Hunter 均作为“尚未实现”的占位命令发布。

HTTP 传输

此命令行工具对面向浏览器的端点使用兼容 Chrome 的 HTTP 传输。执行常规 API 调用不需要常驻的浏览器进程。

发现信号

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

• 捕获覆盖范围：共 25 条网络记录中的 15 条 API 条目
• 协议：html_scraping（95% 置信度）、rest_json（90% 置信度）
• 身份验证信号：— cookies：cid、s、nonsession、dp1、ebaysid、ds1、ds2、shs、npii
• 生成提示：requires_browser_auth、requires_protected_client、uses_chrome_cookie_import、has_per_request_csrf、has_per_request_fraud_token
• 注意事项：placebid_step_up：eBay 会将 /bfl/placebid/ 重定向到登录页面，因此仅使用 cookie 的会话无法通过此 CLI 完成出价；akamai_active：Akamai 机器人管理器已启用，Surf 必须使用 Chrome TLS 指纹，否则标准库 HTTP 将被拦截；rate_limit：持续抓取会触发 403，需刷新身份验证并降低请求频率

命令参考

deal — eBay Deals 信息流

• ebay-pp-cli deal — 浏览 eBay Deals 信息流

item — 商品详情

• ebay-pp-cli item <itemId> — 根据商品刊登 ID 获取商品详情

listings — 在售商品搜索（抓取 /sch/i.html 的 HTML）

• ebay-pp-cli listings — 按关键词搜索 eBay 在售商品

sold — 已售出／已结束的商品刊登（最近 90 天，抓取 HTML）

• ebay-pp-cli sold — 按关键词搜索已售出的商品刊登（90 天范围）

watch — 关注列表（已通过身份验证，只读）

• ebay-pp-cli watch — 列出用户关注列表中的商品

手写命令

• ebay-pp-cli comp <query> — 已售商品对比分析：统计最近 90 天内符合查询条件的商品的平均售价、分布和趋势线。
• ebay-pp-cli auctions <query> — 按出价数量、结束时间范围和商品状况筛选并搜索在售拍卖。用于查询“有出价且将在一小时内结束”的商品。
• ebay-pp-cli feed <saved-search> — 推送符合已保存搜索条件的新刊登，并为每件商品附加已售商品对比信息。
• ebay-pp-cli history — 查看可配置时间范围内的购买记录（已赢得、未赢得、已付款）。
• ebay-pp-cli saved-search — 本地已保存搜索的增删改查。

隐藏的实验性命令

这些命令存在于二进制文件中，但由于目前无法端到端运行，因此未包含在 --help 中。可按名称使用这些命令（例如 ebay-pp-cli snipe --help）查看详情。

• ebay-pp-cli bid — 出价（实验性；会被 eBay 的升级验证拦截）。
• ebay-pp-cli snipe <itemId> --max <amount> — 狙击出价（实验性；依赖出价流程）。
• ebay-pp-cli bid-group — 协同多件商品的狙击出价组（实验性；依赖狙击出价）。

查找合适的命令

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

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

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

身份验证设置

此 CLI 使用浏览器会话。先在 Chrome 中登录 .ebay.com，然后：

ebay-pp-cli auth login --chrome

需要 cookie 提取工具（通过 pip 安装的 pycookiecheat，或通过 Homebrew 安装的 cookies）。

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

Agent 模式

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

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

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

  ebay-pp-cli deal --agent --select id,name,status
  

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

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

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

响应封装

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

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

从 .results 解析数据，并通过 .meta.source 判断数据来自实时来源还是本地来源。只有当 stdout 连接到终端时，stderr 才会输出便于阅读的 N results (live) 摘要；通过管道传递的内容或 Agent 消费者会在 stdout 上获得纯 JSON。

Agent 反馈

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

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

条目会保存在本地的 ~/.ebay-pp-cli/feedback.jsonl。除非设置了 EBAY_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 EBAY_FEEDBACK_AUTO_SEND=true，否则绝不会发送 POST 请求。默认行为仅保存在本地。

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

输出传递

每个命令都接受 --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”模式。

ebay-pp-cli profile save briefing --json
ebay-pp-cli --profile briefing deal
ebay-pp-cli profile list --json
ebay-pp-cli profile show briefing
ebay-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

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

2. 在 Claude Code 中注册：

   claude mcp add ebay-pp-mcp -- ebay-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

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

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