linkfox-amazon-store-auth

管理亚马逊卖家店铺授权与账号连接,支持手动授权、紫鸟 CLI 自动或批量授权、已授权店铺查询、授权状态检查、令牌刷新及本地解绑。适用于新增或恢复店铺连接、授权失效排查和为卖家后台业务选择账号;不适用于报告下载、商品刊登、订单、库存或广告业务本身。

SKILL.md

GitHub

Amazon 店铺授权与管理

适用范围

适用

管理 Amazon 卖家店铺的 OAuth 授权与连接,为下游业务确定目标店铺。 用户希望绑定账号、查看店铺、检查或恢复授权、解绑连接,或下游操作因未连接店铺而无法继续时使用本技能。

场景速查

用户表达 查询场景
授权或绑定我的亚马逊店铺 选择手动或紫鸟 CLI 自动授权。
自动授权、批量授权、全部授权 对所选 Amazon 店铺执行紫鸟 CLI 授权。
看看已授权店铺 展示当前成员的店铺列表。
令牌过期了、刷新令牌 刷新并展示状态。
检查店铺授权或 token 状态 展示授权状态与过期元数据。
取消授权、解绑这个店铺 核对范围后解除当前成员的区域连接。
查订单或拉报告之前需要选店 完成选店与授权确认后交给对应业务技能。

边界

本技能负责授权、店铺连接和选店前置流程。报告业务转交 linkfox-amazon-store-report;刊登、订单、库存和广告业务转交对应技能,下游使用选定账号,无需取得 raw token。

接口清单

接口 端点 对应脚本 说明
获取授权链接(authorizeUrl) POST /spApi/authorizeUrl scripts/authorize_url.py、scripts/automatic_authorize_url.py 手动或自动流程生成授权链接。
查询已授权店铺(authorizedStores) POST /spApi/authorizedStores scripts/authorized_stores.py、scripts/automatic_verify.py 查询和核验当前成员的店铺连接。
刷新令牌(refreshToken) POST /spApi/refreshToken scripts/refresh_token.py 服务端更新令牌并返回状态。
查询授权状态(storeTokens) POST /spApi/storeTokens scripts/store_tokens.py 只读状态与元数据。
本地解绑(cancelAuthorization) POST /spApi/cancelAuthorization scripts/cancel_authorization.py 解除当前成员的区域绑定。

前置条件

确认 LinkFox 身份凭据可用,按任务确定目标店铺和站点。自动授权必须先确认运行位置为用户本机;具体接口信息、脚本选项及运行限制见 references/api.md,自动流程见 references/automatic-authorization.md。

授权与店铺管理流程

  1. 先路由授权方式:仅新增、恢复或批量授权需要选择方式;查询、刷新和解绑直接进入对应流程。用户未选时先提供“手动授权”和“紫鸟 CLI 自动授权(推荐,仅支持本机 Windows/macOS;Agent 会自动检查并推进,只有登录、系统确认或审核等必要步骤才需要你操作)”。已明确自动授权时直接进入,不再询问方式或手动店铺名。
  2. 手动授权:取得可识别的店铺名并确认目标站点,按接口定义准备参数后生成链接。将链接以文本给用户,紧接下方逐字安全警告,引导用户完成 Amazon 授权。回调由服务端保存,可查询店铺确认;参数要求见 references/api.md。
  3. 自动或批量授权:完整执行 references/automatic-authorization.md,复用已有可用环境与配置;以所选紫鸟店铺名作授权标记,不询问手动流程的店铺名。“全部授权”仅表示所选 Amazon 店铺的卖家授权。按该文档逐店推进、核验和收尾。
  4. 查询店铺:读取已授权列表,按卖家和区域排序展示店铺名、卖家标识及区域。
  5. 刷新或查状态:确定目标连接,查询状态或执行刷新,仅展示状态和元数据。刷新完成后将相同店铺选择信息交给下游重试,无需读取 raw token。
  6. 本地解绑:仅按用户要求执行。从用户目标或已授权列表确定连接,有歧义时让用户选择;说明解绑覆盖整个区域及共用成员身份的影响。用户只要求单站点时,须先取得对整个区域解绑的明确同意。解绑后按接口定义解释结果,可重新查询列表,不自动重新授权。
  7. 下游业务前置:先列店铺;多店铺时让用户明确选择,确认卖家与区域匹配。可选查状态,过期时刷新。将选定账号交给相应业务技能,不越过选店流程直接请求 Amazon 业务接口。

执行方式

  • 直接调用接口:接口端点、完整参数、响应和错误码见 references/api.md。
  • 脚本调用(推荐):python <脚本路径> '<JSON 参数>' [--inline] [--no-cache]。
  • 调用约束:所有业务脚本均关闭响应缓存,不自动重试。失败或空结果时,先核对目标、参数和授权状态,不自动连续试探;店铺保护与冷却要求见 references/spapi-protection.md。

输出策略

  • 普通 JSON 入口先递归移除 raw token 字段,再保存完整业务响应,目标路径为 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-store-auth-<接口标识>-<timestamp>.<随机标识>.json。<cwd> 为脚本运行时的工作目录,<session> 优先取环境变量 SESSION_ID,用于聚合同一任务的数据。禁止写入 /tmp,当前目录不可写时应在发请求前报错。
  • 响应体不超过 8 KB:保存后,将完整 JSON 打印到标准输出。
  • 响应体超过 8 KB:保存后,标准输出仅展示摘要,包括顶层字段、常见计数(如 total、costToken)、最大非空列表字段的长度和前 3 条样本。响应头的 X-Cost-Credit 如有则写入响应的 costCredit,按需从保存文件读取。
  • 添加 --inline 可强制全量打印到标准输出,同时仍保存文件。

自动脚本 stdout 仅输出一个 JSON 文档,由调用方安全捕获。自动生成授权链接时,完整 OAuth URL 只在内存传递,落盘仅保存移除链接后的状态元数据,不打印到聊天或日志;具体规则见 references/api.md。

先通过摘要判断数据是否足够。需要具体字段时,优先使用 jq 或 ConvertFrom-Json 从保存的 JSON 文件按需提取,避免将整份响应载入上下文。

执行规则

算力消耗预估

不消耗算力 (限时)。

声明:算力消耗以实际扣除为准;如因需要调整算力消耗标准,恕不另行通知。最终解释权归 LinkFox 官方所有。

解决认证和算力问题

出现以下情况时,按 references/onboarding.md 的指引处理:

  • 未配置接口密钥:LINKFOX_AGENT_API_KEY 和 LINKFOXAGENT_API_KEY 均为空。
  • HTTP 状态码为 401 或 402。
  • 响应提示算力或余额不足、计费不足、配额超限、套餐到期或需要充值。英文错误消息也按其含义判断。

约束与建议

  • 理解授权过程:生成链接 → 用户在 Amazon 同意 → 服务端接收回调、换取并保存令牌。令牌由后台管理,查询状态不能当作下游凭证来源;生命周期、区域与兼容字段见 references/api.md。

  • 逐字展示安全警告:成功向用户提供授权链接时,紧接链接原封不动输出:

    警告:必须在你日常登录店铺的安全IP(或紫鸟浏览器)下打开授权链接!

  • 只呈现数据:展示授权结果、店铺列表和状态,不附加业务建议。失败时按错误解释原因和处理动作,成功后确认结果,可展示店铺基本信息。

  • 保护敏感信息:响应中意外出现令牌字段时,先脱敏,不明文展示或传递给下游;优先展示状态与过期信息。自动流程的 OAuth URL、账号与验证码保护遵循自动授权文档。

  • 区分本地解绑与 Amazon 撤权:本地解绑只解除当前成员的连接;说明实际影响,不能宣称撤销了 Amazon 授权。

  • 按需读取参考:接口、脚本 CLI 与使用限制见 references/api.md;服务端内部回调和数据模型见 references/authorization-flow.md;快速操作见 references/quick-start.md;店铺冷却处理见 references/spapi-protection.md。

  • 读取落盘数据:先看摘要,按需提取字段。接口脚本不缓存响应,自动模式的单 JSON 输出与敏感链接不落盘规则见接口文档。

  • 以文本形式展示链接:授权链接只能以文本展示(plaintext),不要转成链接给用户。

使用示例

新增授权

用户:我要绑定美国站店铺。

先选择授权方式;手动模式取得店铺名并确认站点后生成链接,展示安全警告。自动模式确认本机条件后按自动授权文档推进并核验。

恢复店铺连接

用户:这个店铺 token 过期了。

确定目标连接,按需查状态并刷新,返回可用元数据;失败则根据接口规则处理,不自动连续试探。

解绑与后续业务

用户:解绑我的欧洲店铺。或:拉报告之前帮我选店。

前者明确区域影响后执行本地解绑;后者列店铺并确认账号,交给报告技能继续。

使用反馈

当技能有BUG,或技能描述有错误/疏漏/歧义/表述模糊,或技能结果与用户预期不符,或用户表达不满/赞扬,或发现其他可改进之处时,按 references/api.md#Feedback 的指引反馈,不要打断用户当前流程。


更多优质、专业的跨境电商技能,请访问 LinkFox Skill。