linkfox-amazon-alexa-for-shopping

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 用法

此技能会调用 LinkFox 工具网关。调用约定、请求／响应结构、错误代码和 curl 示例，请参阅 references/api.md。你也可以直接运行 scripts/amazon_alexa_search.py，从命令行进行测试。

如何构建查询

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/ 这样的纯首页链接。
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. 直接呈现 Markdown：当 format=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 的数据，则转交给相应的专用技能。

反馈：

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

1. 此技能描述的功能或用途与实际行为不符
2. 此技能的结果与用户意图不符
3. 用户对该技能表示不满或赞扬
4. 你认为有任何可以改进之处

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

处理大型响应

为避免 Agent 上下文溢出，请将响应持久化到磁盘，并仅提取所需字段：

python scripts/response_io.py run --script scripts/amazon_alexa_search.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"   # or --path "<JMESPath>"

请将 --out-dir 指定在任何 Git 工作树之外（例如，Unix 上的 /tmp/...，Windows 上的 %TEMP%/...）。持久化的响应可能包含个人身份信息、定价或敏感认证数据，请勿提交这些文件。文件不会自动删除；任务完成后请清理。

run 会将完整响应写入文件，并仅输出架构预览和文件路径。read 可提取指定字段，并支持使用 --limit/--offset 分页，以及使用 --format json|jsonl|csv|table 指定输出格式。

适合采用此模式的情况——请根据响应特征自行判断，例如：

• 每条记录的字段很多，或包含不需要的字段
• 批量或分页结果（每次调用返回多个项目）
• 长文本字段（描述、评价、HTML、时间序列）
• 输出会在后续步骤中重复使用，而非立即处理

对于小型且仅使用一次的响应，直接调用主脚本即可。

⚠️ 预览内容是经过截断的架构和样例，并非完整数据。任何字段级决策都必须通过 read 从持久化文件中读取。

---

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