Amazon Search Skill
Search Amazon for products matching a keyword query and return structured JSON results.
Prerequisites
Install Bun runtime:
CODEBLOCK0
Install skill dependencies:
CODEBLOCK1
Install Playwright browsers (required for Amazon search):
CODEBLOCK2
Cookie
This skill uses Playwright to search Amazon directly in a headless browser. No manual cookie management is required.
Playwright Prerequisites
Install npm dependencies and Playwright browsers:
CODEBLOCK3
Inputs
| Parameter | Type | Description |
|---|
| INLINECODE0 | string | Search keywords (e.g. "t-shirt") |
| INLINECODE2 |
string | Optional proxy URL. Can be set as argument value or via
--proxy flag /
T2P_PROXY env var. Supports HTTP/HTTPS and SOCKS5 proxies. |
|
price_min | number | Optional minimum price filter. Mapped to Amazon
low-price. |
|
price_max | number | Optional maximum price filter. Mapped to Amazon
high-price. |
|
--pages | number | Max number of pages to fetch (default: 1). Each page has ~20-60 results. |
|
--num-products | number | Max number of products to fetch. Stops when limit is reached, even if more pages available. |
|
--incremental | flag | Only output new results that haven't been cached before. |
|
--clear-cache | flag | Clear cache for this keyword before searching. |
|
--output | string | Custom output directory for results (default:
results/). |
|
--download | flag | Download product images after search using
@t2p/image-cache. |
Output Format
Returns a JSON object containing search metadata and an array of Amazon product objects.
Results are automatically saved to results/<keyword>_<timestamp>_<count>.json.
CODEBLOCK4
Item Fields
| Field | Type | Description |
|---|
| INLINECODE18 | string | Amazon ASIN (Amazon Standard Identification Number) |
| INLINECODE19 |
string | Unique identifier from Amazon's data attributes |
|
original_image_url | string | Product image URL (highest resolution from srcset) |
|
title | string | Product title |
|
item_page | string | Full URL to the product page |
|
rating | number | Average rating (1-5) |
|
review_count | number | Number of reviews |
|
price | string | Price as displayed on Amazon (includes currency) |
|
description | string | Product description (may be same as title if no separate description) |
Execution
Use the script at scripts/amazon_search.ts.
All TypeScript files must be run with Bun:
CODEBLOCK5
Configuration Tool
Use scripts/configure.ts to generate environment variable commands and manage cache:
CODEBLOCK6
Usage Notes
- - Runtime: All TypeScript files must be run with INLINECODE29
- Search Method: Uses Playwright to search Amazon directly in a headless browser (no manual cookie management needed)
- Proxy Support: Proxy is read from
T2P_PROXY environment variable (or --proxy CLI flag). Supports both HTTP/HTTPS and SOCKS5 proxies (e.g., socks5://127.0.0.1:1080). - Cache & Deduplication: Search results are cached to
resultscache/<sanitizedQuery>_cache.md. Each line is an ASIN/uuid used for deduplication. - Incremental Mode: Use
--incremental to output only items not present in the cache. - Clear Cache: Use
--clear-cache to delete this keyword cache before searching, or use scripts/configure.ts clearcache. - Custom Output: Use
--output=/path/to/dir to save results to a custom directory. - Download Images: Use
--download to automatically download product images using @t2p/image-cache after search completes.
Example
All commands use
bun run:
CODEBLOCK7
Error Handling
| Situation | What to do |
|---|
| HTTP 4xx/5xx / Search blocked | Amazon may be rate-limiting; try again later with a different proxy, or wait before retrying |
| Parse errors / empty results |
Page layout may have changed; try different keywords, pages, or filters |
| Playwright launch errors | Ensure Playwright browsers are installed:
cd scripts && npx playwright install chromium |
Amazon 搜索技能
根据关键词查询搜索亚马逊商品，并返回结构化的 JSON 结果。
前提条件
安装 Bun 运行时：
bash
curl -fsSL https://bun.sh/install | bash
安装技能依赖：
bash
cd skills/amazon-search
bun install
安装 Playwright 浏览器（亚马逊搜索所需）：
bash
cd skills/amazon-search/scripts
npm install
npx playwright install chromium
Cookie
本技能使用 Playwright 在无头浏览器中直接搜索亚马逊，无需手动管理 Cookie。
Playwright 前提条件
安装 npm 依赖和 Playwright 浏览器：
bash
cd skills/amazon-search/scripts
npm install
npx playwright install chromium
输入参数
| 参数 | 类型 | 描述 |
|---|
| keyword | string | 搜索关键词（例如 t-shirt） |
| proxy |
string | 可选代理 URL。可通过参数值、--proxy 标志或 T2P_PROXY 环境变量设置。支持 HTTP/HTTPS 和 SOCKS5 代理。 |
| price_min | number | 可选最低价格筛选。映射到亚马逊的 low-price。 |
| price_max | number | 可选最高价格筛选。映射到亚马逊的 high-price。 |
| --pages | number | 最大抓取页数（默认：1）。每页约 20-60 个结果。 |
| --num-products | number | 最大抓取商品数量。达到限制后停止，即使还有更多页面。 |
| --incremental | 标志 | 仅输出之前未缓存的新结果。 |
| --clear-cache | 标志 | 搜索前清除该关键词的缓存。 |
| --output | string | 自定义结果输出目录（默认：results/）。 |
| --download | 标志 | 搜索后使用 @t2p/image-cache 下载商品图片。 |
输出格式
返回一个包含搜索元数据和亚马逊商品对象数组的 JSON 对象。
结果会自动保存到 results/.json。
json
{
keyword: shirt,
timestamp: 2026-04-06T12:34:56.789Z,
count: 10,
items: [
{
id_: B09TPN9NJ6,
uuid: 418e2c7d-ccaa-4ca3-9d1b-6b4f3bd406b0,
originalimageurl: https://m.media-amazon.com/images/I/91YprRrDB4L.ACUL960FMwebpQL65_.jpg,
title: Amazon Essentials Mens Slim-Fit Crewneck T-Shirts, Short Sleeve,
item_page: https://www.amazon.com/dp/B09TPN9NJ6,
rating: 4.4,
review_count: 1787,
price: $19.99,
description: Amazon Essentials Mens Slim-Fit Crewneck T-Shirts, Short Sleeve
}
]
}
商品字段
| 字段 | 类型 | 描述 |
|---|
| id_ | string | 亚马逊 ASIN（亚马逊标准识别号） |
| uuid |
string | 来自亚马逊数据属性的唯一标识符 |
| original
imageurl | string | 商品图片 URL（来自 srcset 的最高分辨率） |
| title | string | 商品标题 |
| item_page | string | 商品页面的完整 URL |
| rating | number | 平均评分（1-5） |
| review_count | number | 评论数量 |
| price | string | 亚马逊上显示的价格（含货币符号） |
| description | string | 商品描述（若无单独描述，可能与标题相同） |
执行
使用 scripts/amazon_search.ts 脚本。
所有 TypeScript 文件必须使用 Bun 运行：
bash
简单搜索
bun run scripts/amazon_search.ts shirt
配置工具
使用 scripts/configure.ts 生成环境变量命令和管理缓存：
bash
生成代理设置命令（复制并运行输出）
bun run scripts/configure.ts proxy http://127.0.0.1:7890
列出缓存文件
bun run scripts/configure.ts listcache
清除特定关键词的缓存
bun run scripts/configure.ts clearcache shirt
清除所有缓存
bun run scripts/configure.ts clearcache --all
使用说明
- - 运行时：所有 TypeScript 文件必须使用 bun run 运行
- 搜索方式：使用 Playwright 在无头浏览器中直接搜索亚马逊（无需手动管理 Cookie）
- 代理支持：代理从 T2PPROXY 环境变量（或 --proxy CLI 标志）读取。支持 HTTP/HTTPS 和 SOCKS5 代理（例如 socks5://127.0.0.1:1080）。
- 缓存与去重：搜索结果缓存到 resultscache/cache.md。每行是一个用于去重的 ASIN/uuid。
- 增量模式：使用 --incremental 仅输出缓存中不存在的商品。
- 清除缓存：使用 --clear-cache 在搜索前删除该关键词的缓存，或使用 scripts/configure.ts clearcache。
- 自定义输出：使用 --output=/path/to/dir 将结果保存到自定义目录。
- 下载图片：使用 --download 在搜索完成后自动使用 @t2p/image-cache 下载商品图片。
示例
所有命令均使用 bun run：
bash
简单搜索
bun run scripts/amazon_search.ts t-shirt
增量搜索 - 仅输出缓存中不存在的新结果
bun run scripts/amazon_search.ts t-shirt --incremental
搜索前清除缓存
bun run scripts/amazon_search.ts t-shirt --clear-cache --incremental
使用代理
bun run scripts/amazon_search.ts t-shirt --incremental --proxy http://127.0.0.1:10809
多页搜索（抓取 2 页，约 40-120 个结果）
bun run scripts/amazon_search.ts t-shirt --pages=2
多页 + 增量（仅所有页面中的新商品）
bun run scripts/amazon_search.ts t-shirt --pages=2 --incremental
限制特定数量的商品（达到限制后提前停止）
bun run scripts/amazon_search.ts t-shirt --pages=5 --num-products=50
指定自定义输出目录
bun run scripts/amazon_search.ts t-shirt --output=/path/to/custom/results
搜索后下载图片
bun run scripts/amazon_search.ts t-shirt --download
组合：搜索并下载，自定义输出
bun run scripts/amazon_search.ts t-shirt --download --output=/path/to/results
错误处理
| 情况 | 处理方法 |
|---|
| HTTP 4xx/5xx / 搜索被阻止 | 亚马逊可能正在限流；稍后使用不同代理重试，或等待后重试 |
| 解析错误 / 结果为空 |
页面布局可能已更改；尝试不同关键词、页面或筛选条件 |
| Playwright 启动错误 | 确保已安装 Playwright 浏览器：cd scripts && npx playwright install chromium |
