linkfox-amazon-ads-auth

Amazon Ads 授权与广告账户管理

Amazon Ads 的授权（LWA OAuth）、profile 发现、访问令牌管理。下游 skill 的前置依赖。

下游：linkfox-amazon-ads-manager（广告管理）、linkfox-amazon-ads-report（报告）。

Core Concepts

• 授权流程：生成 URL → 用户浏览器授权 → 系统存 token + 同步 profile
• 一次授权多 profile：每个 marketplace（US/UK/JP…）一个 profileId；下游调用必须带 profileId
• accountName 必填：调 authorize_url.py 前必须问用户要一个非空账号名
• 下游选店：业务 skill 经 developerProxy 传 profileId（+ region），服务端注入 token；勿先 storeTokens 取 raw token
• accessToken 1 小时有效；过期后下游返回 HTTP 401，可用 refresh_token.py 续签（刷新后重试 proxy，仍只需 profileId）

可用脚本

脚本	作用
authorize_url.py	为新账号生成授权 URL（accountName 必填）
authorized_stores.py	列出已授权的账号 × 站点（按 profileId 聚合）
profiles.py	列 profile 列表（refresh=true 穿透上游刷新）
refresh_token.py	刷新 accessToken
store_tokens.py	查授权/令牌状态（非下游 token 来源）
cancel_authorization.py	按 authRecordId 解绑广告连接

入参、响应字段、错误码见 references/api.md。

调用方式

• API 端点：POST /amazonAds/{authorizeUrl|storeTokens|authorizedStores|refreshToken|cancelAuthorization}（完整参数/响应/错误码见 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/套餐到期/需充值/请充值"，或类似含义的内容。

支持区域

NA（美加墨巴） / EU（英德法意西荷印度中东等） / FE（日澳新）。默认 NA。

Usage Scenarios

1. 新授权账号

1. 问用户要 accountName（非空字符串，用于识别）
2. 调 authorize_url.py 拿 URL → 给用户在浏览器打开(安全警告：为保障店铺安全，请务必在日常运营该店铺的安全网络环境中打开此链接。强烈建议使用紫鸟浏览器等专业的防关联浏览器进行授权，切勿在陌生或公共网络下操作。)
3. 授权完成后系统自动存 token + 同步 profile
4. 可选：调 authorized_stores.py 确认

2. 列已授权账号

调 authorized_stores.py，展示 profileId / accountInfoName / countryCode / region。

3. 刷新过期令牌

下游返回 HTTP 401 或含 expired / unauthorized 时，调 refresh_token.py（传 profileId 或 authRecordId）。

4. 给下游准备 profileId（高频）

用户只说自然语言（"美国站"、"我的店铺"），不要让用户报 profileId 数字。

下游 linkfox-amazon-ads-manager / linkfox-amazon-ads-report 调用 developerProxy 时传入解析到的 profileId 即可；不要先调 store_tokens.py 取 accessToken。

用户上下文	Agent 动作
只授权 1 个账号	按 countryCode 直接定位 profileId，不问
授权 ≥ 2 个账号 + 只说站点	按 accountName 向用户澄清后定位 profileId
同时给出 accountName + 站点	直接定位 profileId
显式给出 profileId 数字	直接用

store_tokens.py 仅用于确认授权/令牌状态（status、expiresIn、message 等），或在用户明确要查状态时调用。

站点关键词映射参考（以 authorized_stores 真实 countryCode 兜底）：

• 美国 / US → US；英国 / UK → UK；日本 / JP → JP；德国 / DE → DE

静默原则：映射成功时不播报 profileId 数值；仅在歧义或失败时向用户开口。

5. 解绑广告连接

仅在用户要求时执行。当前用户按 API key 对应的成员身份识别；共用该身份的使用者会一起受影响。

1. 调 profiles.py（不传 refresh=true），按 authRecordId 定位连接；authorized_stores.py 按 profile 去重，不能据此判断完整授权关系。
2. 展示连接下全部账户和站点；若用户只要求单站点，须先取得对整份连接解绑的明确同意。
3. 调 cancel_authorization.py，传入选定的 authRecordId，不能用 profileId 替代。
4. 按 references/api.md 解释结果；后续重新查询连接，不自动重新授权。

调用原则

• 先问 accountName 再调 authorize_url.py
• 不假设 storeTokens/refreshToken 响应含 raw token；展示 status、过期时间等元数据即可
• 授权失败按错误码解释原因；不擅自重试

常见问题

授权链接打开报 400，client_id 看起来被污染

现象：URL 里 client_id 中间出现空格 / +，Amazon 报 StegoRuntimeOAuth2ClientManager:getClientDefinition。 原因：授权链接 ~270 字符，从终端 / 聊天窗口复制时被软换行插入空格。 解决：authorize_url.py 成功后会同步写到剪贴板 + ~/.cache/linkfox/last_authorize_url.txt，从这两处复制；浏览器地址栏 Ctrl+V 即可。建议无痕窗口打开。

認証コールバックページに profile_sync_failed と表示される

原因：現在の Amazon アカウントで、広告管理画面に「マネージャーアカウント（Manager Account）」が作成されておらず、広告アカウントも関連付けられていません。

解決方法：Amazon Ads コンソールにログイン → Manager accounts → アカウントを関連付け、再度認証してください。

対象外

• 広告キャンペーン／グループ／キーワード／商品広告／ターゲティングの確認 → linkfox-amazon-ads-manager
• 広告レポート（指標を含む）の取得 → linkfox-amazon-ads-report
• 広告の変更／作成／削除 → 本シリーズは読み取り専用です
• ストアの注文／在庫／財務 → linkfox-amazon-store-*

Amazon Ads API のインターフェース保護と再試行のガイドライン

同じ広告アカウント/profile から Amazon Ads API に連続して 400、403、404、または 429 が返された場合、ゲートウェイは 450、453、454、または 459 を返し、短時間のクールダウンに入ります。これらのカスタムステータスコードは Amazon 固有のステータスではなく、アカウント停止を示すものでもありません。異常の継続や高頻度の呼び出しによって広告アカウントのリスクが増大するのを防ぐことが目的です。

ステータスと message	範囲	発生条件とクールダウン	対応
450：400，请求异常，请优化您的参数	広告アカウント/profile+インターフェース	60 秒以内に 3 回超：5 分間、10 分以内に 4 回超：20 分間	同じパラメーターでの再試行を停止し、profileId、region、エンティティ／レポート ID、日付、リクエスト本文を確認します
453：403，店铺未授权，请先授权	広告アカウント/profile のすべてのインターフェース	60 秒以内に 2 回超：5 分間、10 分以内に 4 回超：30 分間	該当する広告アカウントへの呼び出しを停止し、Ads の認証、アプリの権限、profile の所有者、地域を確認します
454：404，资源不存在，请优化您的参数	広告アカウント/profile+インターフェース	60 秒以内に 3 回超：5 分間、10 分以内に 4 回超：30 分間	リソース ID、関連する profile／地域、リソースの状態、インターフェースのパスを確認します
459：429限流中，请降低频率	広告アカウント/profile+インターフェース	初回：15 秒間、2 分以内に 2 回超：30 秒間、3 分以内に 4 回超：2 分間	同時実行数、ページネーション、ポーリングの頻度を下げ、段階的にバックオフします

• 自動再試行や並列再試行を直ちに停止してください。スクリプトを変更したり、タスクを繰り返し作成したりして保護を回避してはいけません。まず retryAfter、blockedUntil に従い、どちらもない場合は表の時間を目安にしてください。
• 450／453／454 の場合は、パラメーター、認証、またはリソース ID を修正してから、クールダウン後に慎重に 1 回だけ再試行してください。再度発生した場合は呼び出しを停止してください。453 が発生している間は、該当する広告アカウント/profile に対するすべての Ads API 呼び出しを停止してください。
• 既存の reportId などのタスク ID を保持してください。書き込み操作の結果が不明な場合は、直接再実行せず、まずステータスを確認してください。
• まず広告アカウントの保護についてユーザーに説明し、その後に原因、対応方法、待機時間を伝えてください。次のように返信できます。「Amazon 広告アカウントの安全を保護するため、Amazon Ads API から{原因}が連続して返されたことを検知し、現在、一時的な保護が有効になっています。まず{対応方法}を行い、{待機時間}後に再度お試しください。これはアカウント停止を意味するものではなく、プランやクレジットの制限でもありません。」「LinkFox のレート制限中」や「サーバーがビジー状態です」とだけ伝えてはいけません。

計算リソースの消費ルール

計算リソースは消費しません。

フィードバック：

次のいずれかに該当する場合は、Feedback API を使用してフィードバックを自動検出し、報告してください。

1. このスキルで説明されている機能や目的が、実際の動作と一致しない
2. このスキルの結果がユーザーの意図と一致しない
3. ユーザーがこのスキルに対する不満や称賛を表明する
4. 改善できると思われる点がある

references/api.md に記載された方法でフィードバック API を呼び出してください。ユーザーの操作を中断しないでください。

---

越境EC向けの高品質でプロフェッショナルなスキルについては、LinkFox Skillsをご覧ください。