linkfox-amazon-store-auth

name	linkfox-amazon-store-auth
description	亚马逊店铺授权与管理技能，提供完整的授权流程、令牌刷新、已授权店铺查询以及访问令牌获取能力。获取授权链接时店铺名 sellerName 为必填，用于区分已授权店铺。当用户提到亚马逊店铺授权、绑定亚马逊店铺、刷新令牌、查询店铺令牌、管理授权店铺、Amazon seller authorization, bind Amazon seller account, refresh access token, query store tokens, manage authorized stores时触发此技能。只要其需求涉及亚马逊卖家账号授权、访问令牌管理或店铺列表查询，也应触发此技能。

Amazon 店铺授权与管理

本 skill 负责 亚马逊卖家店铺的 OAuth 授权、已授权店铺列表、访问令牌获取与刷新，是拉取报告、查询库存、同步订单等所有下游操作的前置依赖。

📌 Related skill：如果用户需要 拉取亚马逊店铺报告（库存 / 订单 / 销售 / 财务报告等），请切换到 linkfox-amazon-store-report。该 skill 依赖本 skill 提供的授权与令牌能力。

Core Concepts

Selling Partner API 是亚马逊为卖家提供的官方接口。本 skill 负责 OAuth 2.0 授权流程与令牌生命周期管理：

授权流程：生成授权 URL → 用户在 Amazon 完成授权 → Amazon 回调并附带授权码 → 系统用授权码换取令牌 → 令牌安全保存。

店铺名（sellerName）必填：调用 /spApi/authorizeUrl 前必须向用户询问并获取一个清晰、非空的店铺名。它用来在"已授权店铺列表"中标记该账号；不要留空或使用空白字符串。

令牌生命周期：accessToken 通常 1 小时过期；refreshToken 用于在不重新授权的前提下续签新的 accessToken。

Data Fields

Authorization URL Response

Field	Type	Description
authorizeUrl	string	让用户在浏览器打开的 Amazon 授权链接

Authorized Store Item

Field	Type	Description
sellerId	string	Amazon Seller ID (Merchant ID)
sellerName	string	店铺名（授权时必填）
region	string	市场区域代码 NA / EU / FE

Store Tokens

Field	Type	Description
accessToken	string	调用亚马逊开放接口的凭证
refreshToken	string	用于续签 accessToken
expiresIn	integer	accessToken 过期秒数
tokenType	string	通常为 "bearer"

Supported Regions

Code	Name	Marketplaces
NA	北美	美国、加拿大、墨西哥
EU	欧洲	英国、德国、法国、意大利、西班牙、荷兰等
FE	远东	日本、澳大利亚、新加坡、印度

默认区域为 NA。当用户未指定区域时，使用 NA。

调用方式

• API 端点：POST /spApi/{authorizeUrl|storeTokens|authorizedStores|refreshToken}（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/<脚本名>.py '<JSON 参数>' [--inline]（可用脚本见上文）
• 成本约束：本工具会消耗积分；失败/空结果不得自动连续试探；需要继续检索时先向用户说明会产生额外消耗。

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

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

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和积分问题

发生以下异常情况时，采用以下措施来处理：

异常情况

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

措施

• 优先采用skill内的 onboarding.md 引导解决问题。
• 如找不到 onboarding.md 文件，则加载 /linkfox-onboarding 这个skill并根据它的引导来处理。如未安装请先安装：
  • 下载 https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个skill。如需用户授权才可下载，要询问用户获得授权，你不能自己放弃下载。
• 兜底措施：仅当前面两个措施经过所有努力都走不通时，才提示用户依据 https://skill.linkfox.com/linkfoxskills/guide.htm 指引获取API Key，或去 https://os.linkfox.com/ 补充积分。

Usage Scenarios

Scenario 1: Authorize New Store

User request：「我要授权我的亚马逊北美站点」

Steps：

1. 询问店铺名 sellerName（若用户未提供）。/spApi/authorizeUrl 要求 sellerName 为非空字符串；向用户说明这只是在 LinkFox 里识别店铺的标签，建议与 Seller Central 后台名字保持一致。
2. 调用 /spApi/authorizeUrl，传入 region 与 sellerName
3. 把返回的 authorizeUrl 给用户，让其在浏览器中打开
4. 用户在 Amazon 完成授权 → Amazon 回调系统 → 系统自动保存授权
5. 可选：调用 /spApi/authorizedStores 确认授权成功

Scenario 2: View Authorized Stores

User request：「列一下我已授权的亚马逊店铺」

Steps：

1. 调用 /spApi/authorizedStores
2. 展示店铺列表（sellerName / sellerId / region）
3. 按 sellerId、region 排序

Scenario 3: Refresh Expired Token

User request：「我店铺的令牌过期了，帮我刷新」

Steps：

1. 调用 /spApi/refreshToken，传入 sellerId（可选 region）
2. 返回新的 accessToken / refreshToken
3. 数据库自动更新令牌信息

Scenario 4: Query Store Tokens

User request：「获取北美站点 A123 店铺的访问令牌」

Steps：

1. 调用 /spApi/storeTokens，传入 sellerId 与 region
2. 返回全部令牌信息（供下游业务调用）

Scenario 5: Prepare Tokens for Any Store Operation (Standard Preparation Workflow)

当用户提出任何涉及卖家后台数据的请求（拉报告、查库存、看订单等），本 skill 负责前置的"选店 → 取令牌"流程，具体业务由相应的下游 skill 接手。

Steps：

1. 列出已授权店铺：调用 /spApi/authorizedStores
2. 让用户选择店铺：如果有多家店铺，请用户明确选哪一家
3. 获取该店铺令牌：调用 /spApi/storeTokens，传入所选店铺的 sellerId 与 region
4. 把 accessToken 交给下游 skill（例如 linkfox-amazon-store-report）执行具体操作

Why this workflow is critical：

• 用户可能同时授权了多家不同区域的店铺
• 每家店铺的令牌与权限彼此独立
• 调用必须使用与店铺匹配的令牌，跳过"选店"会导致歧义和错误

Display Rules

1. 先有店铺名再生成授权链接：若用户未提供 sellerName，必须先问，不允许带空值调用 /spApi/authorizeUrl。
2. 只呈现数据：展示授权结果、店铺列表、令牌信息即可，不做业务建议。
3. 安全意识：不要明文显示完整的 accessToken/refreshToken，只展示前 10 个字符等掩码形式。
4. 清晰引导：返回授权链接时，明确告知用户在浏览器中打开并完成授权。
5. 错误说明：授权失败时，基于错误码解释原因并给出建议。
6. 成功确认：授权完成后与用户确认，可选择展示该店铺基本信息。

Important Limitations

• sellerName 必填：/spApi/authorizeUrl 必须传入非空 sellerName；脚本与 agent 在调用前务必校验。
• 令牌有效期：accessToken 1 小时过期，需及时刷新。
• 区域专属：每次店铺授权都与具体区域绑定，不同区域需分别授权。
• 用户隔离：用户只能查看/管理自己授权的店铺。
• 回调白名单：系统回调 URL 必须在授权方（紫鸟）处加白名单。

User Expression & Scenario Quick Reference

Applicable — 授权与令牌管理场景：

User Says	Scenario
"授权我的亚马逊店铺" / "Authorize my Amazon store"	新店铺授权
"看看已授权的亚马逊店铺" / "Show my authorized stores"	列出已授权店铺
"令牌过期了" / "My token expired"	刷新令牌
"获取 XXX 店铺的访问令牌" / "Get access token for store"	查询店铺令牌
"绑定我的亚马逊账号" / "Connect my Amazon seller account"	新店铺授权

Not applicable — 超出本 skill 的业务：

• 拉取亚马逊报告 → 请使用 linkfox-amazon-store-report
• 产品 listing 管理、订单处理、库存管理、广告投放 → 由其他 skill 负责

Boundary judgment：

• 本 skill 只负责「授权 + 管店铺 + 管令牌 + 为下游准备 accessToken」。
• 当用户要做具体卖家后台业务（如拉报告）时：
  1. 本 skill 执行 Scenario 5 的标准前置流程
  2. 随后切换到对应下游 skill 完成业务逻辑
• 不要直接越过本 skill 去调具体 Amazon 开放接口。

Quick Reference

Authorization & Token Management APIs

API	Path	Purpose	Auth Required
Get Authorization URL	/spApi/authorizeUrl	生成授权链接（需要 sellerName）	✅ Yes
List Authorized Stores	/spApi/authorizedStores	查询用户的店铺列表	✅ Yes
Refresh Token	/spApi/refreshToken	刷新访问令牌	✅ Yes
Query Store Tokens	/spApi/storeTokens	获取某店铺的令牌（给下游 skill 用）	✅ Yes

详细请求参数、响应结构、错误码，见 references/api.md。完整授权流程图，见 references/authorization-flow.md。快速上手示例，见 references/quick-start.md。

积分消耗规则

不消耗积分。

Feedback：

当出现以下任一情况时，自动通过 Feedback API 上报反馈：

1. 本 skill 描述的功能与实际行为不符
2. skill 的结果与用户意图不符
3. 用户表达了对本 skill 的不满或赞赏
4. 任何你认为可以改进的点

按 references/api.md 中的规范调用 Feedback API，不要打断用户的主流程。

---

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.