前言¶
做亚马逊选品、竞品监控或卖家分析时，常见做法是手工翻站点、拼爬虫，或自己对照 OpenAPI 文档写请求。接口多、参数杂，Agent 还容易凭记忆拼错路径。下面介绍社区 Skill keyapi-amazon：它把业务意图映射到场景卡片，以 KeyAPI 官方文档 为契约，通过本地脚本发起 REST 调用，而不是用网页浏览代替 API 结果。
这是什么¶
keyapi-amazon（坐标 @user_2e47cd26/keyapi-amazone-commerce，当前版本 1.1.2）是 SkillHub 上的社区 Skill，分类为 business-ops，由发布者 user_2e47cd26 维护。Skill 的定位是：借助 KeyAPI REST API 与实时官方文档，探索和分析亚马逊市场数据。
官方简介涵盖的能力包括：商品搜索、类目浏览、商品详情、畅销榜、促销与 Deal、卖家情报、达人橱窗、评论与报价，以及 ASIN/GTIN 互转。SkillHub 页面标注 requires_api_key=true，即需要配置 KeyAPI 的 Bearer Token（环境变量 KEYAPI_TOKEN）。
核心功能¶
以下能力均来自 Skill 说明与 references/scenarios.md 中的场景划分，具体路径与参数以 KeyAPI 当前文档为准。
商品与类目
- 关键词或 ASIN 搜索，支持类目、价格、品牌、Prime、评分等过滤
- 类目列表、按类目拉商品、Best Seller 等多榜单类型
- 批量商品详情（文档说明单次最多 10 个 ASIN）
促销与报价
- Deal 发现、按 Deal ID 拉商品、促销码详情
- 多 ASIN 报价（成色、配送等过滤）
评论信号
- 分页评论、高赞评论摘要、按 review ID 取详情
卖家情报
- 卖家档案、在售商品、卖家反馈，并可结合报价做竞争力对比
达人橱窗
- Influencer 档案、帖子列表、List 类型帖子下的 featured 商品
标识符
- ASIN 转 GTIN（文档说明支持 24 个亚马逊站点）
执行方式
Skill 自带三个 Node 脚本：configure-keyapi-auth.mjs（鉴权）、search-keyapi-docs.mjs（查文档）、keyapi-api.mjs（发请求）。成功响应以 KeyAPI 信封为准：code = 0 表示成功。
安装与启用¶
安装 SkillHub CLI¶
若尚未安装，可先检查版本：
command -v skillhub && skillhub --version
未安装时可按 SkillHub 安装文档执行完整安装：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安装 keyapi-amazon¶
安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认装到 ./skills/ 可能不会被识别。常见路径示例：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
安装命令：
skillhub install @user_2e47cd26/keyapi-amazone-commerce --dir ~/.cursor/skills/
也可让 Agent 按 SkillHub 安装说明 完成安装。安装后通常需要重启或刷新 Agent 以加载 Skill。
配置 KeyAPI 鉴权¶
API 基址为 https://api.keyapi.ai，请求头为 Authorization: Bearer $KEYAPI_TOKEN。Token 可在 KeyAPI Dashboard 获取；说明见 Bearer 认证文档。
在 Skill 目录下（与 SKILL.md 同级）建议按以下顺序操作：
node scripts/configure-keyapi-auth.mjs --status
若 authStatus 为 unavailable，执行交互式配置：
node scripts/configure-keyapi-auth.mjs
非交互方式（仅在本地私有 shell 中使用）：
node scripts/configure-keyapi-auth.mjs --token "your_keyapi_token"
Skill 要求凭证仅存本地环境，不要在对话中回显 KEYAPI_TOKEN。
运行脚本需要本机已安装 Node.js。
典型用法¶
Agent 按 Skill 约定的工作流：先对齐业务目标 → 选场景 → 用文档解析当前 endpoint → 再调用 API。你在对话里可以用自然语言描述目标，例如「美国站关键词搜索蓝牙耳机，按评论数排序取前 20」或「给定 ASIN 列表拉详情和 Buy Box 报价」。
1. 解析当前文档（发请求前）
在 Skill 目录执行：
node scripts/search-keyapi-docs.mjs --query "product search" --resolve
查询词应来自推断出的 API 概念，而不是生硬翻译用户原话。
2. 调用 GET 类接口
将 --path 换成上一步文档中的 /v1/amazon/... 路径：
node scripts/keyapi-api.mjs --path /v1/amazon/... --query-param example=value
3. 大响应或需要完整字段时
node scripts/keyapi-api.mjs --path /v1/amazon/... --query-param example=value --output-file response.json
完整业务数据在 helper 结果的 data.data 中；大响应默认可能只预览 stdout。
4. POST 请求
node scripts/keyapi-api.mjs --path /v1/amazon/... --method POST --body '{"example":"value"}'
若主机 Agent 无法执行脚本，Skill 允许改用同一文档约定的 method、path、header 与 body，通过宿主环境的 HTTP 客户端发起请求。
适用场景与注意¶
适合谁
- 运营、选品、竞品分析需要在对话里反复查亚马逊结构化数据，且已有或愿意申请 KeyAPI 账号的团队
- 希望 Agent 跟官方 OpenAPI 同步、减少「记错路径」的集成场景
限制与注意
- 依赖 KeyAPI 计费与配额；重复相同参数会再次计费（脚本说明 live 请求无本地缓存）
- 官方文档与 Skill 冲突时，以
https://docs.keyapi.ai/llms.txt及链接页面为准 - 不得用亚马逊网页抓取替代 API 结果；无 Token 时应暂停 live 调用并走配置流程，而不是退回到未授权浏览
- SkillHub 统计（以页面抓取为准）：评分 100000，下载 580，安装 3；标签 requires_api_key=true
结尾¶
keyapi-amazon 把亚马逊相关的自然语言需求收敛成「场景 + 实时文档 + 本地脚本调用」的固定流程，适合在 Cursor、Claude Code 等支持 Skills 的环境里做市场数据查询与分析。安装与详情见 SkillHub：
- https://www.skillhub.cn/skills/user_2e47cd26/keyapi-amazone-commerce
- https://api.skillhub.cn/user_2e47cd26/keyapi-amazone-commerce
