内容
# `ssc` — ShoppingScraper 命令行工具
> **价格爬取命令行工具**，适用于 Amazon、Google Shopping、Bol.com 和 Coolblue。从终端爬取价格、优惠、购买框获胜者、变体和评论 — 或将其作为原生 MCP 工具连接到 Claude Desktop / Cursor / Claude Code。
[](https://www.npmjs.com/package/@shoppingscraper/cli)
[](https://github.com/ShoppingResult/shoppingscraper-cli/actions/workflows/ci.yml)
[](./LICENSE)
**🌐 网站：** [shoppingscraper.com](https://shoppingscraper.com) · **🔑 获取 API 密钥：** [app.shoppingscraper.com](https://app.shoppingscraper.com) · **📖 API 文档：** [apiguide](https://app.shoppingscraper.com/apiguide)
适用于 [ShoppingScraper API](https://app.shoppingscraper.com/apiguide) 的代理友好型命令行工具，由 [shoppingscraper.com](https://shoppingscraper.com) 提供。每个命令都具有稳定的 JSON 封套，支持 MCP 服务器模式，可用于 Claude Desktop / Cursor / Code，并附带 `SKILL.md` 文件，以便任何 LLM 都能无需模式包装而使用。
## 为什么
您是一个 AI 代理（或正在构建一个的开发人员），并且需要来自 Google Shopping、Amazon、Bol.com 或 Coolblue 的**产品数据 — 价格、优惠、购买框获胜者、变体、评论**。目前，您正在直接调用原始 HTTP API，并编写相同的重试/错误/信用跟踪代码。`ssc` 就是这种代码的粘合剂，存在于一个二进制文件中，具有稳定的接口。
用例：
- **价格监控命令行工具** — 从 cron / GitHub Actions / 您的 CI 中分发数千个 EAN。
- **电子商务爬取** — 将 EAN 匹配到市场 SKU，拉取每个优惠，监控购买框。
- **AI 代理** — 通过内置的 MCP 服务器为 Claude/Cursor 提供实时的市场数据。
- **批量价格爬取** — `ssc batch` 从 stdin 读取 EAN，流式传输 NDJSON 封套。
## 安装
```bash
# 运行而无需安装
npx -y @shoppingscraper/cli credits
# 全局安装
npm install -g @shoppingscraper/cli
# 或通过 Homebrew（发布后）
brew install ShoppingResult/tap/ssc
```
## 快速入门
```bash
# 1. 设置您的 API 密钥（在 https://app.shoppingscraper.com 获取）
export SSC_API_KEY="<your-key>"
# 2. 验证
ssc credits
# → {"_v":1,"ok":true,"command":"credits","result":{...},"meta":{...}}
# 3. 获取某个市场上的 EAN 的优惠
ssc offers --site amazon.de --ean 0190198001281
# 4. 人性化输出
ssc buybox --site bol.com --ean 0190198001281 --pretty
# 5. 管道友好：仅获取结果负载
ssc info --site shopping.google.nl --ean 0190198001281 | jq '.result'
# 6. 批量：从文件中获取 500 个 EAN，信用额度上限为 500
ssc batch offers --input eans.txt --site amazon.de --max-spend-credits 500
```
## 命令
| 命令 | 功能 | 信用额度 |
|---|---|---|
| `ssc credits` | 显示剩余信用额度 + 计划信息 | 0 |
| `ssc history` | 该密钥的近期 API 调用 | 0 |
| `ssc offers --site --ean` | EAN 的所有卖家优惠 | 1 |
| `ssc info --site --ean` | 产品标题、品牌、图片、规格 | 1 |
| `ssc buybox --site --ean` | 当前购买框获胜者 + 价格 | 1 |
| `ssc match --site --ean [--deepsearch]` | EAN → 市场 SKU/URL | 1 / 4 |
| `ssc search --country --keyword` | Google Shopping 搜索 | 1 |
| `ssc page --url` | 任意产品 URL 的结构化数据 | 1 |
| `ssc variants --site --sku` | Google Shopping SKU 的变体 ⚠ | 6 |
| `ssc reviews --site --sku` | 评论 + 评分分布 | 1 |
| `ssc batch <cmd> --input` | 分发命令（NDJSON 输出） | n × 成本 |
| `ssc tools [--json-schema]` | 列出每个命令（用于代理自省） | 0 |
| `ssc mcp serve` | 标准输入/输出上的 MCP 服务器 | 0 |
⚠ = 高成本，获取 `requiresConfirmation: true` 在 MCP 工具注释中。
## 批量 / 流式处理
每个爬取命令都接受 `--input <file|->`。每行读取一个 EAN/SKU，分发时配置并发（默认为 5），每个请求抖动 200–800ms，流式传输 NDJSON 封套。以 `#` 开头的行是注释。
```bash
# 从文件
ssc offers --input eans.txt --site amazon.de --max-spend-credits 500
# 从标准输入
cat eans.txt | ssc info --site bol.com --input - --max-spend-credits 100
# `ssc batch` 是带有强制上限的语法糖
ssc batch buybox --input eans.txt --site amazon.de --max-spend-credits 200
```
`ssc batch` **需要** `--max-spend-credits N` — 没有默认值。这是故意的：代理绕过此标志是 MCP 驱动的工作流可能犯下的最高风险错误。
## 输出格式
每个命令都在标准输出上发出稳定的 JSON 封套（批量/流式处理的单行）：
```json
{
"_v": 1,
"ok": true,
"command": "offers",
"result": { /* 端点有效载荷 */ },
"error": null,
"meta": {
"credits_remaining": 12483,
"duration_ms": 412,
"request_id": "ssc_01a2b3c4d5e6f708"
}
}
```
失败时：`ok: false`，`result: null`，`error.code` 是以下之一：`AUTH_MISSING | AUTH_INVALID | RATE_LIMITED | UPSTREAM_ERROR | NETWORK_ERROR | SPEND_CAP_EXCEEDED | NOT_FOUND | INVALID_RESPONSE | USER_ERROR`。
退出代码：
- `0` 成功 · `1` 用户错误 · `2` 认证 · `3` 速率限制 · `4` 上游 · `5` 网络 · `6` 支出上限。
传递 `--pretty` 以获得人性化的视图；传递 `--quiet` 以抑制标准输出（仅退出代码重要）。
## 认证
解析顺序：
1. `--api-key <key>` 标志（避免 — 记录在 shell 历史中）
2. `SSC_API_KEY` 环境变量（推荐）
3. `~/.config/ssc/config.json` 包含 `{"api_key": "..."}` （模式 0600 推荐）
命令行工具将密钥作为查询字符串参数（`?api_key=...`）发送，以匹配已部署的 ShoppingScraper API 合同。所有 URL 在日志、错误封套或 `meta.request_id` 出现之前都会被遮蔽。
## MCP — 模型上下文协议
```bash
ssc mcp serve
```
作为标准输入/输出的 MCP 服务器运行，公开每个命令作为工具（`ssc_offers`、`ssc_info`、`ssc_buybox`，...）。工具输入模式是从命令行工具使用的相同 zod 模式自动导出的，因此代理和人类看到的是相同的接口。
### Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"shoppingscraper": {
"command": "npx",
"args": ["-y", "@shoppingscraper/cli", "mcp", "serve"],
"env": { "SSC_API_KEY": "<your-key>" }
}
}
}
```
### Cursor / Claude Code
相同的形状 — 将任何 MCP 兼容的主机指向 `npx -y @shoppingscraper/cli mcp serve`，并在环境中设置 `SSC_API_KEY`。
### 工具注释
高成本工具（`ssc_variants`、`ssc_match` 带有 `--deepsearch`，任何批量）带有 `requiresConfirmation: true`。**此注释是建议性的** — 行为良好的主机在调用前提示；恶意或无头客户端忽略它。真正的支出上限是 `--max-spend-credits` 和 ShoppingScraper API 计划的服务器端上限。
## 支出上限防御
三层，按强度顺序：
1. **服务器端（最强）** — ShoppingScraper API 强制执行 `max_credits_per_call` 和每个密钥的每日上限。返回带有 `credits_required` 的 HTTP 402。无法被任何东西绕过。
2. **客户端强制** — `ssc batch` 在没有 `--max-spend-credits N` 的情况下拒绝运行。
3. **客户端建议** — 每个命令的全局 `--max-spend-credits` （默认为 100）；每个工具的软上限；MCP `requiresConfirmation` 注释。
要为高级用户工作流禁用客户端上限：
```bash
ssc batch offers --input eans.txt --site amazon.de --max-spend-credits none
```
## 程序化使用
```ts
import { HttpClient, endpoints, resolveConfig } from "@shoppingscraper/cli";
const cfg = resolveConfig();
const client = new HttpClient({
apiKey: cfg.apiKey,
baseUrl: cfg.baseUrl,
appBaseUrl: cfg.appBaseUrl,
timeoutMs: 30_000,
retries: 2,
});
const r = await endpoints.offers(client, { site: "amazon.de", ean: "0190198001281" });
console.log(r.creditsRemaining, r.data);
await client.close();
```
## 开发
```bash
npm install
npm run typecheck
npm test
npm run build
node dist/cli.js --help
```
## 安全
参见 [SECURITY.md](./SECURITY.md)。发现漏洞？请发送电子邮件至 security@shoppingscraper.com。请勿公开发布问题。
## 关于 ShoppingScraper
`ssc` 由 **[ShoppingScraper](https://shoppingscraper.com)** 构建和维护 — 面向 Amazon、Google Shopping、Bol.com、Coolblue 和 30 多个其他市场的电子商务价格爬取 API。精确到 EAN，实时，专为 AI 代理构建。
- 🌐 网站： **[shoppingscraper.com](https://shoppingscraper.com)**
- 🔑 获取 API 密钥： **[app.shoppingscraper.com](https://app.shoppingscraper.com)**
- 📖 API 文档： **[app.shoppingscraper.com/apiguide](https://app.shoppingscraper.com/apiguide)**
- 📨 联系方式： hello@shoppingscraper.com
## 许可证
MIT — © [ShoppingScraper](https://shoppingscraper.com)
