linkfox-amazon-alexa-search

Amazon Alexa Shopping Assistant

此技能可调用 Amazon 商店中的 Alexa 购物助手：提出自然语言问题，即可获得答案、精选商品列表（含 ASIN 和链接），以及 Alexa 愿意继续回答的一组后续问题。每次调用仅支持一个提示词。对于多轮对话，Agent 必须总结先前的上下文，并将其与新问题拼接后，在新调用中发送。

核心概念

1. 每次调用仅限单轮对话：prompts 是一个数组，但仅支持 1 个元素。每次 API 调用会向 Alexa 发送一个问题，并返回一个答案。请勿传入多个元素。
2. 不同调用之间不会保留上下文：每次调用都会开启一个全新的 Alexa 会话。若要提出后续问题，Agent 必须总结先前的答案（关键推荐、ASIN、相关上下文），并将其与新问题拼接，作为新调用中的 prompts[0]。
3. 可选页面上下文（url）：只有在希望对话围绕特定页面展开时，才传入 Amazon 页面 URL（例如分类页面、搜索结果页面或商品详情页面）。请勿传入类似 https://www.amazon.com/ 的普通商城首页 URL，因为它无法提供有用的上下文。没有特定页面可作为对话锚点时，请完全省略 url。
4. 两种输出格式：
   • markdown（默认）——一份易读的 Markdown 报告，包含问题、Alexa 的回答、推荐商品组和后续问题。
   • json——data 下的结构化数组，每个条目包含 prompt、content、products（分组推荐）、followUpQuestions 和 screenshot。

resultsNum 是 Alexa 实际回答的对话轮数；如果为 0，则表示 Alexa 未针对输入生成可用回复。

参数

参数	类型	必填	描述	默认值
prompts	string[]	是	对话提示词。每次调用仅允许 1 个元素。若要提出后续问题，请发起新调用，并将上下文摘要与新问题作为 prompts[0]。	-
format	string	否	响应格式：markdown 返回易读报告；json 返回结构化数组。	markdown
url	string	否	用于锚定对话的特定 Amazon 页面 URL（分类、搜索结果或商品详情）。没有特定页面时请省略；请勿传入类似 https://www.amazon.com/ 的普通首页 URL。	-

响应字段

字段	类型	描述
stdout	string	当 format=markdown 时返回 Markdown 报告，包含每轮的问题、Alexa 的回答、推荐商品组和后续问题
data	array	当 format=json 时返回结构化对话轮次。每个条目包含 prompt、content、products[]、followUpQuestions[]、screenshot
resultsNum	integer	已回答的轮数（0 = Alexa 未响应）
code / errcode	string / integer	成功时为 200；非 200 表示业务错误
msg / errmsg	string	成功时为 ok；否则为错误说明
costTime	integer	API 延迟时间，单位为毫秒
costToken	integer	消耗的 Token 数量（仅成功时计费）
taskId	string	用于追踪的上游任务标识符
type	string	渲染提示：Markdown 对应 stdoutWorkbenches，JSON 对应 json

结构化的 data[*] 格式（format=json）

字段	类型	描述
prompt	string	本轮发送的问题或后续问题
content	string	Alexa 的自然语言回答
products[].title	string	分组标题（例如“热门推荐”“最适合跑步”）
products[].items[].asin	string	商品 ASIN
products[].items[].title	string	商品标题
products[].items[].url	string	商品详情页 URL
products[].items[].cover	string	商品封面图片 URL
products[].items[].price	string	当前价格字符串（含货币单位）
products[].items[].originalPrice	string	标价／删除线价格
products[].items[].score	string	星级评分
products[].items[].ratingsCount	string	评论数
products[].items[].describe	string	商品简介
followUpQuestions	string[]	Alexa 提供的后续问题
screenshot	string	本轮截图 URL

调用方式

• API 端点：POST /amazon/alexaSearch（完整参数／响应／错误码见 references/api.md）
• Python 脚本：python scripts/amazon_alexa_search.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话中，同一参数组合默认只调用一次，脚本带有 24h 本地缓存。失败或结果为空时，不得自动更换关键词、翻页或更改邮编连续试探；需要继续检索时，先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-alexa-search-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 中即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写时则报错）
• 响应体 ≤ 8 KB：落盘后将完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后，stdout 只输出摘要（顶层字段、total／costToken 等常见计数、最大列表字段的长度及前 3 条样本）
• 加上 --inline 强制将全部内容打印到 stdout（同时落盘）

读取数据的建议：先查看摘要，判断信息是否足够；需要具体字段时，优先使用 jq或ConvertFrom-Json 从保存的 json 文件中按需提取，避免将整份 JSON 加载到上下文中。

解决认证和算力问题

发生以下异常情况时，使用 references/onboarding.md 引导用户解决问题：

异常情况

• 未配置 API Key：未配置环境变量 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应状态码为 401 或 402
• 响应提示算力或余额不足：消息包含“算力余额不足／计费不足／余额不足／quota exceeded／insufficient balance／套餐到期／需充值／请充值”，或类似含义的内容。

如何构建查询

1. 在 prompts[0] 中优先说明用户意图——包括市场提示（“在 Amazon US 上”）、使用场景和任何硬性约束（预算、关键特性）。Alexa 会重点考虑问题开头的内容。
2. 每次调用只问一个问题——prompts 只接受 1 个元素。不要传入多个元素。
3. 提出后续问题时，先总结再提问——用户希望继续对话时，Agent 必须：(a) 总结 Alexa 上次回答的要点（回答摘要、推荐的 ASIN 和相关上下文）；(b) 将摘要与新问题合并；(c) 在新的 API 调用中将其作为 prompts[0] 发送。Alexa 不会记住之前的调用。
4. 仅在有具体页面时使用 url 作为依据——用户根据某个页面进行判断时，传入分类页、搜索结果页或商品详情页 URL。一般性问题不要传入 url；不要传入 https://www.amazon.com/ 之类的纯主页 URL。
5. 有意选择 format——向用户展示精心排版的回答时，markdown 最合适；下游代码需要以编程方式提取 ASIN、价格或后续问题时，json 更合适。

使用示例

1. 单轮购物问题

{
  "prompts": ["best wireless earbuds for running on Amazon US under $100"]
}

2. 后续问题（Agent 总结先前上下文并重新提问）

首次调用：

{
  "prompts": ["best electric kettle on Amazon US"]
}

第二次调用（Agent 总结上次回答并附上后续问题）：

{
  "prompts": ["Previously Alexa recommended: 1) Cosori Electric Kettle (B07T1KY5TZ, $35.99, 4.7★), 2) Mueller Ultra Kettle (B09KC7D3HR, $29.97, 4.5★). Now compare these two on noise level and boil time."]
}

3. 以分类页为依据的问题

{
  "prompts": ["What are the most popular picks on this page?"],
  "url": "https://www.amazon.com/s?k=electric+kettle"
}

4. 用于下游提取的结构化输出

{
  "prompts": ["best gift ideas for a 10-year-old who likes science"],
  "format": "json"
}

展示规则

1. 当 format=markdown 时，直接渲染 Markdown：stdout 已按轮次标题、产品卡片和后续问题进行结构化处理 — 保留该结构。
2. 展示推荐的 ASIN，方便用户点击查看；显示 title、price、score/ratingsCount 和产品 URL。
3. 展示 Alexa 返回的后续问题 — 用户可以选取这些问题继续探索。用户选取其中一个时，先总结当前答案，再在新的调用中将所选后续问题用作 prompts[0]。
4. 不要将请求转到数据分析沙盒：答案正文是对话式的，推荐产品采用嵌套分组，而不是适合 SQL 式聚合的扁平表格数据集。
5. 标示空结果：如果 resultsNum 为 0 或 data 为空，请告知用户 Alexa 未生成可用答复，并建议改写问题或使用 url 指定页面。
6. 说明时效性：结果反映 Alexa 在调用时给出的实时答复；用户询问时间相关信息时，请说明这一点。
7. 处理业务错误：如果 code / errcode 不为 200，请显示 msg / errmsg，并建议使用更简单的问题重试。

重要限制

• 由 Alexa 驱动，结果并非确定：相同的问题在不同调用中可能得到不同答案 — Alexa 的回复会随时间、流量和上下文而变化。
• 调用之间不保留记忆：每次工具调用都是一个全新的 Alexa 会话；Agent 必须总结之前的上下文，并将其融入新问题。
• 每次调用只能有一个提示词：prompts 只接受 1 个元素。对于后续问题，Agent 必须将上下文总结与新问题合并为一个 prompts[0]，然后发起新的调用。
• 商城覆盖范围：基于 Amazon 的商城 Alexa 体验（主要是 amazon.com）；是否支持美国以外的商城取决于 Alexa 的推广情况。
• 输出内容组合：主要价值是对话式答复和精选的少量产品；这不能替代覆盖整个搜索引擎结果页（SERP）的产品提取。

用户表达与场景速查

适用 — 在 Amazon 上进行自然语言对话式购物：

用户表达	场景
"用 Alexa 帮我推荐...", "亚马逊 Alexa 问下..."	直接向 Alexa 提问
"在亚马逊上聊聊给我推荐 ...", "对话式选品"	对话式探索
"顺便再追问一下 / 接着问 ..."	后续提问（Agent 总结之前的结果，并在新的调用中重新提问）
"在这个页面 / 这个分类下推荐...", "基于这个页面再问一下"	基于页面的对话（使用 url）
"best XX for YY under $Z on Amazon"	目标 + 限制条件 + 预算问答
"对比 Alexa 给的前两个推荐"	对比 Alexa 回复中的前两个推荐
"Alexa 还能继续问什么 / 给我一些追问思路"	展示后续问题

不适用 — 建议转到其他工具：

• 获取某个关键词的完整 SERP，包括排名、广告标记等（使用商城搜索模拟技能）。
• 历史搜索词分析或搜索量趋势（使用 ABA 数据探索器）。
• 已知 ASIN 的详细产品信息 / A+ 内容 / 要点（使用 Amazon 产品详情技能）。
• 评论级别的情感分析（使用 Amazon 评论技能）。
• 基于图片发现相似产品（使用图片搜索技能）。
• 对扁平产品列表进行汇总统计（此处没有结构化表格）。

边界判断：当用户想要进行对话 — “询问 Amazon、获取推荐，然后继续追问” — 此技能适用。如果用户需要原始搜索结果行、结构化分析数据或特定 ASIN 的数据，则应转到相应的专用技能。

算力消耗规则

按动态规则计费：消耗算力 = 对话轮次 × 12.6。

重要：本技能的服务按倍数动态计算，可能一次性消耗大量算力，必须提醒用户，由用户决定是否继续。

反馈：

出现以下任一情况时，自动通过 Feedback API 检测并报告反馈：

1. 本技能描述的功能或用途与实际行为不符
2. 本技能的结果与用户意图不符
3. 用户对本技能表示不满或称赞
4. 你认为任何方面可以改进

请按照 references/api.md 中的说明调用反馈 API。不要打断用户的流程。

---

如需获取更多优质、专业的跨境电商技能，请访问 LinkFox Skills。