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