| name | linkfox-amazon-store-auth |
| description | 亚马逊店铺授权与管理技能，提供完整的授权流程、令牌刷新、已授权店铺查询以及授权状态查询能力。获取授权链接时店铺名 sellerName 为必填，用于区分已授权店铺。当用户提到亚马逊店铺授权、绑定亚马逊店铺、刷新令牌、查询店铺授权状态、管理授权店铺、Amazon seller authorization, bind Amazon seller account, refresh access token, query store token status, manage authorized stores时触发此技能。只要其需求涉及亚马逊卖家账号授权、令牌生命周期管理或店铺列表查询，也应触发此技能。 |
Amazon 店铺授权与管理
本 skill 负责 亚马逊卖家店铺的 OAuth 授权、已授权店铺列表、授权状态查询与令牌刷新，是拉取报告、查询库存、同步订单等所有下游操作的前置依赖。下游业务经 developerProxy 传入 sellerId+region 即可，无需先取 raw token。
📌 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（授权状态，非 raw token 下发）
POST /spApi/storeTokens 返回状态与元数据（具体字段以网关为准），供确认授权是否有效、何时过期。不要将响应当作下游 developerProxy 的 token 来源。
| Field | Type | Description |
|---|
| status | string | 授权/令牌状态（如有效、过期、缺失） |
| authRecordId | integer | 授权记录 ID（如有） |
| expiresIn | integer | 距 accessToken 过期的秒数（如有） |
| tokenExpiresAt | string | 绝对过期时间（如有） |
| message | string | 补充说明 |
| errcode / errmsg | integer / string | 网关错误（失败时） |
兼容说明：旧版网关可能仍返回 accessToken/refreshToken；Agent 不应优先读取或传递给下游。下游应使用 sellerId+region 调 developerProxy。
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 进入上下文。
解决认证和积分问题
发生以下异常情况时，采用 references/onboarding.md 引导解决问题：
异常情况
- 未配置API Key：环境变量未配置
LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
- 响应401或402状态码
- 响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。
Usage Scenarios
Scenario 1: Authorize New Store
User request：「我要授权我的亚马逊北美站点」
Steps：
- 询问店铺名
sellerName（若用户未提供）。/spApi/authorizeUrl 要求 sellerName 为非空字符串；向用户说明这只是在 LinkFox 里识别店铺的标签，建议与 Seller Central 后台名字保持一致。
- 调用
/spApi/authorizeUrl，传入 region 与 sellerName
- 把返回的
authorizeUrl 给用户，让其在浏览器中打开
- 用户在 Amazon 完成授权 → Amazon 回调系统 → 系统自动保存授权
- 可选：调用
/spApi/authorizedStores 确认授权成功
Scenario 2: View Authorized Stores
User request：「列一下我已授权的亚马逊店铺」
Steps：
- 调用
/spApi/authorizedStores
- 展示店铺列表（sellerName / sellerId / region）
- 按 sellerId、region 排序
Scenario 3: Refresh Expired Token
User request：「我店铺的令牌过期了，帮我刷新」
Steps：
- 调用
/spApi/refreshToken，传入 sellerId（可选 region）
- 返回刷新状态与元数据（如
status、message、expiresIn）；服务端更新令牌
- 下游可直接重试
developerProxy（传入相同 sellerId+region），无需读取 raw token
Scenario 4: Query Store Token Status
User request：「查一下北美站点 A123 店铺的授权/令牌状态」
Steps：
- 调用
/spApi/storeTokens，传入 sellerId 与 region
- 向用户展示状态字段（
status、expiresIn、tokenExpiresAt、message 等）
- 不要把响应当作下游 proxy 的 token；业务调用直接带
sellerId+region
Scenario 5: Prepare Account Selector for Any Store Operation (Standard Preparation Workflow)
当用户提出任何涉及卖家后台数据的请求（拉报告、查库存、看订单等），本 skill 负责前置的「选店 → 确认授权」，具体业务由相应的下游 skill 接手。
Steps：
- 列出已授权店铺：调用
/spApi/authorizedStores
- 让用户选择店铺：如果有多家店铺，请用户明确选哪一家，确定
sellerId 与 region
- （可选）调用
/spApi/storeTokens 仅作状态确认（过期则先 refreshToken）
- 把
sellerId+region 交给下游 skill（例如 linkfox-amazon-store-report），由下游直接调 developerProxy
Why this workflow is critical：
- 用户可能同时授权了多家不同区域的店铺
- 每家店铺的令牌与权限彼此独立
- 必须使用与店铺匹配的
sellerId+region，跳过「选店」会导致歧义和错误
Display Rules
- 先有店铺名再生成授权链接：若用户未提供
sellerName，必须先问，不允许带空值调用 /spApi/authorizeUrl。
- 只呈现数据：展示授权结果、店铺列表、令牌信息即可，不做业务建议。
- 安全意识：响应若含 legacy token 字段，不要明文展示；优先呈现
status / 过期时间等元数据。
- 清晰引导：返回授权链接时，明确告知用户在浏览器中打开并完成授权。
- 错误说明：授权失败时，基于错误码解释原因并给出建议。
- 成功确认：授权完成后与用户确认，可选择展示该店铺基本信息。
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 店铺授权状态" / "Check store token status" | 查询授权状态（storeTokens） |
| "绑定我的亚马逊账号" / "Connect my Amazon seller account" | 新店铺授权 |
Not applicable — 超出本 skill 的业务：
- 拉取亚马逊报告 → 请使用
linkfox-amazon-store-report
- 产品 listing 管理、订单处理、库存管理、广告投放 → 由其他 skill 负责
Boundary judgment：
- 本 skill 只负责「授权 + 管店铺 + 令牌刷新/状态查询 + 为下游准备
sellerId+region 选店信息」。
- 不要为下游
developerProxy 调用 storeTokens 取 raw accessToken（除非兼容极旧客户端且用户明确要求）。
- 当用户要做具体卖家后台业务（如拉报告）时：
- 本 skill 执行 Scenario 5 的标准前置流程（选店）
- 随后切换到对应下游 skill，直接
developerProxy + sellerId+region
- 不要直接越过本 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 Token Status | /spApi/storeTokens | 查询某店铺授权/令牌状态（非下游 token 来源） | ✅ Yes |
详细请求参数、响应结构、错误码，见 references/api.md。完整授权流程图，见 references/authorization-flow.md。快速上手示例，见 references/quick-start.md。
积分消耗规则
不消耗积分。
Feedback：
当出现以下任一情况时，自动通过 Feedback API 上报反馈：
- 本 skill 描述的功能与实际行为不符
- skill 的结果与用户意图不符
- 用户表达了对本 skill 的不满或赞赏
- 任何你认为可以改进的点
按 references/api.md 中的规范调用 Feedback API，不要打断用户的主流程。
For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.
