亚马逊店铺 AI 助手 · 使用指南

这份指南写给不熟悉代码的运营、广告投放和产品团队——你只需要告诉 AI 你想查什么，它会自动调用工具帮你拿到数据。

🔍 它能做什么？

简单来说，它是一套亚马逊店铺数据查询工具集，覆盖两个业务板块：

所有数据都来自本地数据库（历史数据），不走亚马逊实时接口，查询速度快且不消耗 API 配额。

🚀 快速上手

关于你的权限 Token

每位用户都会获得一个专属权限 Token，它决定了你能访问哪些亚马逊账号和站点。Token 的分配由管理员完成，你不需要手动管理。

当你向 AI 提问时，它会自动用你的 Token 查询可用账号列表，然后替你调用对应的工具。你只需要用自然语言描述需求即可，不需要传任何账号 ID 或站点 ID。

第一次使用？先看看你有哪些账号权限

直接告诉 AI：

"帮我列出我能用的亚马逊账号"

AI 会调用 list_ad_accounts 工具，返回你有权限访问的账号名称、国家站点和可用数据范围。当你不确定"我有没有美站权限"、"我管着哪些店铺"时，随时可以问。

通用规则

• 日期格式：统一用 YYYY-MM-DD，例如 2026-10-01
• 多值过滤：可以一次指定多个值（多个 SKU、多个订单状态、多个日期），满足任一即返回
• 时间范围：订单查询最多 365 天，广告查询取决于数据库覆盖情况
• 指定账号/站点：用名称或国家告诉 AI，比如"美站"、"日本站"、"店铺 A"，AI 会自动匹配

🏷️ 一键复制的提问示例

新手直接复制下面的例子丢给 AI 就能跑起来！

🛒 店铺业务

📊 广告数据

🔧 进阶玩法：一次问多个维度

🛒 店铺业务数据工具

工具速查表

1. list_ad_accounts — 查看可用账号

你只需要说：

"我有哪些账号可以用？" / "列出我能访问的店铺"

AI 返回你权限范围内的所有账号，包括名称、国家/站点。这是一个"查询权限"的工具，AI 在调用其他工具前也会自动先调它来确认你能用哪些账号。

2. get_order_list — 历史订单查询

能回答的问题：

• 最近一周我在美站卖了多少单？
• 上个月某个 SKU 的订单明细是什么？
• 帮我查订单号 114-1234567-1234567 的详细信息
• 10 月 1 日到 10 月 15 日已发货但未付款的订单

你需要提供的：

可选的过滤条件（说给 AI 听即可）：

常用订单状态：

• Shipped — 已发货
• Unshipped — 待发货
• Pending — 待处理
• Canceled — 已取消
• InvoiceUnconfirmed — 发票未确认

返回内容：每笔订单的主信息（订单号、状态、金额、日期）、商品明细（SKU/ASIN/数量/价格/品牌型号）、买家联系方式（邮箱/收件人/地址/物流）。

3. get_inventory_list — FBA 库存快照查询

能回答的问题：

• 今天我的 SKU-001 在 FBA 仓库还有多少可售库存？
• 帮我对比 10 月 15 日和 10 月 29 日的库存变化
• 列出美站全部 SKU 当前的库存情况

你需要提供的：

关于库存快照日期：

库存不是每天都存。系统保留：

• 近 30 天的每日快照（完整）
• 更早的历史快照：每月 15 日 和每月最后一天

所以查询时用这些日期能命中数据；如果一个没有快照的日期，会返回空。

返回的关键字段：

4. get_refund_list — FBA 退货查询

能回答的问题：

• 上个月美站有哪些 FBA 退货？退货原因是什么？
• 某个 SKU 最近的退货情况？
• 10 月份已完成跟进的退货有多少笔？

你需要提供的：

可选过滤：

退货跟进状态码：

• 1 — 未跟进
• 2 — 未到期
• 3 — 已到期
• 4 — 已完成

返回内容：订单号、SKU/ASIN、退货数量、退货原因、客户评论、退货仓库、退货处理结果（SELLABLE/UNSELLABLE）、自动关联的品牌型号等商品属性。

5. get_reimbursement_list — 理赔查询

能回答的问题：

• 10 月份美站批准了多少笔理赔？总共赔了多少钱？
• 某个 SKU 有哪些理赔记录？
• 最近已完成跟进的理赔 Case

你需要提供的：时间范围。

可选过滤：SKU、ASIN、跟进状态（1未跟进/2未到期/3已到期/4已完成）。

返回的关键字段：

6. get_replace_list — 换货查询

能回答的问题：

• 10 月份美站有多少笔换货？
• 原始订单号 111-222-333 的换货情况？
• 某个 SKU 作为换货原因（Reason Code）的统计？

你需要提供的：时间范围。

可选过滤：SKU、ASIN、跟进状态（1未跟进/2未到期/3已到期/4已完成）。

返回的关键字段：

7. get_rma_return_list — RMA 退货授权查询

能回答的问题：

• 10 月份美站有多少 RMA 退货授权？
• 哪些 RMA 状态是"待处理"的需要跟进？
• 某个 SKU 的 A-to-Z 索赔情况？
• Prime 订单的退货统计？

你需要提供的：时间范围。

可选过滤：SKU、ASIN、状态码。

⚠️ RMA 的状态码含义和其他售后工具不同：

返回的关键字段：

📊 广告数据工具

工具速查表

所有广告查询工具都自动使用你的权限 Token 匹配对应广告账号，你只需告诉 AI 你要查什么内容、什么时间范围、哪个站点即可。

广告类型说明（你可以直接说，也可以不说——不说就查全部）：

4. get_campaign_performance — 活动级整体表现

能回答：

• 最近一个月哪些活动烧钱最多？
• 美站十月份各活动的 ACOS 是多少？
• 按花费排序，Top 10 的活动有哪些？

你需要提供：时间范围、站点（可选）。其他条件（广告类型、返回条数）不说也行，AI 用默认值。

返回指标：曝光、点击、花费、销售额、订单数、CTR、CPC、CPA、ACOS、ROAS。

5. get_performance_trend — 按天趋势

能回答：

• 上周三 ACOS 突然升高是为什么？
• 最近 7 天销售额的走势如何？
• 某个活动最近一个月每天的花费变化

6. get_ad_group_performance — 广告组表现

能回答：

• 某个活动下哪个广告组效果最好？
• 按广告组看十月份的花费和 ACOS

7. get_keyword_performance — SP 关键词表现

能回答：

• 哪些关键词 ACOS 过高需要降价？
• 哪些长尾词转化好可以加价？
• Top 20 花费关键词的表现

💡 仅适用于 SP（商品推广）。如果你想查品牌推广或展示推广的"关键词"，用"定向表现"工具。

返回内容：关键词文本、匹配类型（广泛/短语/精确）、竞价、1/7/14/30 天的归因销售额和订单。

8. get_targeting_performance — 定向表现

能回答：

• 我定向的那些 ASIN 竞品哪个效果最好？
• 品牌推广的品类定向表现如何？

三种广告类型的定向形式：

• 商品推广：关键词定向（广泛匹配、短语匹配、精确匹配、竞品 ASIN）
• 品牌推广：商品定向、品类定向、品牌定向
• 展示推广：商品定向、受众定向

9. get_search_term_performance — 搜索词表现

能回答：

• 客户实际搜了哪些词找到我的产品？
• 哪些搜索词只带来点击没带来转化？
• 帮我找新的关键词机会

💡 用来找新关键词（高转化低竞争）和否定词（高点击零转化）。

10. get_ad_performance — 广告/创意表现

能回答：

• 同一个活动里哪个 ASIN/创意烧钱最多、ACOS 最差？
• 不同主图创意的 ACOS 对比

11. get_purchased_product_performance — 成交商品表现

能回答：

• 客户点击我的广告后最终买了什么？
• 有没有"买了别家的"（Other ASIN）？
• 我投 A 商品但客户最终买了 B 商品，那 B 是什么？

💡 这个报表没有花费/点击数据，主要看"谁被转化了"——用来发现交叉销售机会。

12. get_placement_performance — 投放位置表现

能回答：

• 首页顶部广告位的 ACOS 和商品页广告位比起来怎么样？
• 搜索结果首页 vs 其他位置的花费分布

三种位置：

13. get_ad_structure — 广告结构快照

能回答：

• 当前我有多少个活动在跑？预算是多少？
• 出价策略是什么？广告组和定向都配了啥？
• 盘点一下我账户里的广告结构

💡 这个工具返回的是配置快照（活动/广告组/定向/创意的当前状态），不是历史数据。

包含的内容：活动列表、广告组列表、投放 ASIN/SKU、定向表达式、品牌推广创意（标题/品牌/落地页）。

💡 常见问题

Q：AI 没有调用工具，反而让我传文件怎么办？

这说明你的 MCP 连接没生效——AI 看不到可用的工具列表，所以以为你要让它做"普通的文件数据分析"。

典型的错误回复长这样：

"我先看了一下当前工作区，里面没有任何广告数据文件。要分析 Amazon SP 广告并给出调整建议，我需要你提供 8 月份的实际投放数据……麻烦你确认一下手头有哪种报表，然后把它发给我（直接拖文件进来即可）"

看到这种回复，不要传文件——直接按下面的清单排查。

排查清单（按优先级从上往下查）

1️⃣ 先确认：AI 到底能不能看到工具？

在聊天窗口直接问 AI：

"你现在有哪些可用的 MCP 工具？把工具名列表给我看"

✅ 正常情况：AI 应该能列出 list_ad_accounts、get_order_list、get_inventory_list、get_campaign_performance、get_refund_list 等十几个工具名。

❌ 如果 AI 说"没有 MCP 工具"、"我只擅长文本对话"、或者只列出了它自己内置的通用能力 → 继续看第 2 条。

2️⃣ 检查 MCP 客户端配置有没有写对

3️⃣ 检查 Token 是不是有效

• 是不是复制了整行（包括空格或引号）？
• 是不是过期了？后台重新生成一个试试
• 是不是Bearer 前缀重复了？（有些客户端自动加，你又手动加了一遍）

快速验证：在浏览器或终端里直接请求一下服务器：

curl -X POST http://你的服务器地址/mcp/amazon-shop \
  -H "Authorization: Bearer 你的Token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

返回里如果有 "tools": [{"name": "list_ad_accounts", ...}, ...] 说明服务器和 Token 都没问题，那问题就在客户端配置。

4️⃣ 重启客户端再试

有时候 MCP 配置改了但客户端没重新加载——关掉客户端、重新打开、或者在设置面板里点一下"重新连接 / Reload"。

排查 OK 之后，这样提问效果更好

工具能正常调用时，用自然语言说清楚你要什么就行，比如：

通用提问公式：[站点/账号] + [时间范围] + [你要看的指标/维度]

AI 会自动选对应的工具去查，不需要你知道工具名。

Q：多账号/多站点怎么办？

直接用名称或国家告诉 AI。比如"美站"、"日本站"、"店铺 A"。AI 会自动匹配你的权限 Token 下对应的账号。如果你同时有多个权限，AI 会按你说的名称筛选。

Q：为什么查询返回空？

1. 日期格式：有没有写成 2026-10-01 而不是 2026/10/01？
2. 库存快照日期：库存不是每天都存，只能查近 30 天每天 + 历史每月 15 日和月底
3. 权限范围：你查的账号/站点是否在你的权限 Token 范围内？可以先调 list_ad_accounts 确认
4. 数据还没入库：数据库里可能还没有最新日期的数据

Q：订单查询时间范围太长怎么办？

单次最多 365 天。如果要查两年的，拆成两次说（"查 2025 年全年"和"查 2026 年至今"）。

Q：返回的广告数据里活动名称不对？

系统会自动用数据库里的最新活动名称覆盖报表中的历史名称，所以你看到的是活动当前的名字。

Q：SBV（视频品牌推广）数据在哪里？

不用你手动区分。系统自动把 SB 和 SBV 拆开，返回里会分别有两个部分。

Q：一个权限 Token 可以给多个人用吗？

不建议。每个 Token 绑定一个具体用户的账号权限范围。如果你需要给新同事开通权限，请联系管理员分配。

如何连接 MCP 客户端（WorkBuddy / Trae / VS Code 等）

如果你是技术同事，需要把这套工具接入自己的 MCP 客户端（WorkBuddy、Trae、VS Code MCP、Claude Desktop 等），按以下步骤配置即可。

前置条件：获取 API Token

所有 MCP 端点都需要 Bearer Token 鉴权。找开发拿一个就行，然后在客户端配置里直接粘贴（不需要手动加 Bearer 前缀——客户端会自动补上）。

MCP Server 端点

当前有三个 HTTP 端点（均为 POST JSON-RPC）：

以下配置示例均以 http://你的服务器地址 作为 Base URL，请替换为实际部署地址。

WorkBuddy 配置

WorkBuddy 的 MCP 配置文件位于设置中的 MCP Servers 面板，格式如下：

{
  "mcpServers": {
    "amazon-shop": {
      "type": "http",
      "url": "http://你的服务器地址/mcp/amazon-shop",
      "headers": {
        "Authorization": "Bearer 你的Token"
      }
    }
  }
}

如果你想用完整服务器地址把三个端点都配上（后两个目前没有工具，可以先不配）：

{
  "mcpServers": {
    "amazon-shop": {
      "type": "http",
      "url": "http://你的服务器地址/mcp/amazon-shop",
      "headers": {
        "Authorization": "Bearer 你的Token"
      }
    },
    "amazon-ads-api": {
      "type": "http",
      "url": "http://你的服务器地址/mcp/amazon-ads-api",
      "headers": {
        "Authorization": "Bearer 你的Token"
      }
    },
    "amazon-sp-api": {
      "type": "http",
      "url": "http://你的服务器地址/mcp/amazon-sp-api",
      "headers": {
        "Authorization": "Bearer 你的Token"
      }
    }
  }
}

保存后 WorkBuddy 会自动连接，成功后在工具列表里能看到 list_ad_accounts、get_order_list、get_inventory_list 以及 10 个广告查询工具。

Trae / VS Code 配置

Trae 和 VS Code MCP 扩展同样支持 HTTP transport。在项目根目录的 .trae/mcp.json（Trae）或 VS Code 设置中添加：

Trae（.trae/mcp.json）：

{
  "servers": {
    "amazon-shop": {
      "type": "http",
      "url": "http://你的服务器地址/mcp/amazon-shop",
      "headers": {
        "Authorization": "Bearer 你的Token"
      }
    }
  }
}

VS Code MCP（settings.json）：

{
  "mcp.servers": {
    "amazon-shop": {
      "type": "http",
      "url": "http://你的服务器地址/mcp/amazon-shop",
      "headers": {
        "Authorization": "Bearer 你的Token"
      }
    }
  }
}

Claude Desktop / 其他兼容 MCP 客户端

Claude Desktop 的配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json，Windows: %APPDATA%/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "amazon-shop": {
      "url": "http://你的服务器地址/mcp/amazon-shop",
      "headers": {
        "Authorization": "Bearer 你的Token"
      }
    }
  }
}

💡 通用规则：任何支持 HTTP transport 的 MCP 客户端，核心都是提供三个字段——url（端点）、Authorization header（Bearer Token）。

本地 stdio 模式（仅开发调试用）

如果你想在本地不经过 HTTP 直接调试（不需要 Token），项目也注册了 stdio 模式的 Server，通过 Laravel 命令启动：

# 启动指定 Server（会进入阻塞的 stdio 循环，handle 值见 routes/ai.php）
php artisan mcp:start amazon-shop

# 也可以用 MCP Inspector 调试（浏览器打开交互式调试界面）
php artisan mcp:inspector

然后在客户端里把 type 改成 stdio，配置 command 和 args 即可。stdio 模式不做权限校验，仅限内网开发使用。

常见连接问题

广告报表中的派生指标

所有广告报表都会自动帮你算好这些指标，不用你自己算：