configure

用途

本技能用于为当前平台设置或更新 spotify-ads-api 插件的本地配置文件，完成 Spotify Ads API 的凭证配置，包括身份认证、广告账户绑定和执行偏好设置。

主要能力

OAuth 2.0 授权码 + PKCE（S256）模式（默认）：使用属于用户团队的客户端 ID 进行授权，该 ID 决定客户端级归因、配额和限流隔离。插件不提供全局客户端 ID，不应使用替代品。
直接令牌模式（token）：适用于已签发的 bearer 令牌（遗留模式）。
设置文件管理：按平台选择活动设置文件，并支持在托管工作区写入受限时进行待处理令牌文件的最终化安装。
广告账户发现与选择：通过 API 请求包装脚本列出业务与广告账户，展示名称、ID 与状态，并在唯一账户时自动选择，否则提示用户提供。
账户验证：对选定的广告账户执行验证请求。

使用方式

选择活动设置文件

Codex：.codex/spotify-ads-api.local.md
Claude：.claude/spotify-ads-api.local.md
Antigravity：.agents/spotify-ads-api.local.md

读取该文件（如存在）；若不存在，可读取另一平台的设置文件作为默认值，但不得覆盖该平台的设置文件。

OAuth 模式

前置条件：团队管理员已创建或选择 Spotify Developer 应用、启用 Ads API、完成相应授权步骤，并准确注册 http://127.0.0.1:8080/callback。需要 Python 3.8+ 或 uv 可用。

解析团队所属的客户端 ID：优先使用命令参数；否则若本地设置含 client_id，可提议复用而不静默替换；若无或不复用，则提示输入。

提示 auto_execute（默认 false）。运行助手脚本：

PLUGIN_ROOT="${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$PWD}}"
python3 "${PLUGIN_ROOT}/skills/configure/scripts/oauth-flow.py" \
  --client-id "<team_client_id>" \
  --settings-file "<active_settings_file>" \
  --auto-execute "<true_or_false>"

若 python3 不可用，改用：

PLUGIN_ROOT="${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-$PWD}}"
uv run "${PLUGIN_ROOT}/skills/configure/scripts/oauth-flow.py" \
  --client-id "<team_client_id>" \
  --settings-file "<active_settings_file>" \
  --auto-execute "<true_or_false>"

助手会先打印授权 URL，再尝试打开浏览器。若自动打开失败，提示用户将 URL 复制到浏览器，同时回环监听继续等待。不要在 shell 中重建 PKCE 流程或让用户粘贴重定向 URL（verifier 为临时值，仅保留在助手内存中）。

若既无 Python 3 也无 uv，配置无法进行。直接令牌模式同样依赖该安全设置助手，并非无需运行时的回退方案。

确认助手的非敏感 stdout 回执：

{"settings_file":"<active_settings_file>","auth_flow":"authorization_code_pkce"}

助手将 access_token、refresh_token、token_expires_at、client_id、auth_flow 通过原子化 mode-0600 创建直接写入设置文件，不打印令牌，无需后续 chmod。stderr 诊断信息应单独保留。

若托管工作区拒绝写入设置，助手以退出码 5 返回安全路径：

{"settings_file":"<active_settings_file>","pending_token_file":"<private_mode_0600_file>","requires_settings_write":true}

不要读取或打印待处理文件。请求所需的工作区权限，然后运行最终化命令：

python3 "${PLUGIN_ROOT}/skills/configure/scripts/settings_file.py" oauth-result \
  --settings-file "<active_settings_file>" \
  --pending-token-file "<pending_token_file>"

成功后写入器原子化安装设置文件并删除待处理令牌文件。若放弃配置，告知用户后删除该特定待处理文件（其中含有效的 OAuth 令牌）。

定义请求包装，然后发现并选择广告账户：

PLUGIN_ROOT="${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}"
api() { "$PLUGIN_ROOT/scripts/api-request.sh" configure "$@"; }

首次调用 Ads API v3 前，阅读并遵循 $PLUGIN_ROOT/skills/api-reference/references/live-openapi.md。

api GET "businesses"

对每个选定的业务：

api GET "businesses/<business_id>/ad_accounts"

展示账户名称、ID 与状态。仅当所有业务中恰好只有一个账户时才自动选择。若发现失败或无账户，提示输入广告账户 ID。

原子化更新 ad_account_id（不打印令牌）：

python3 "${PLUGIN_ROOT}/skills/configure/scripts/settings_file.py" update-account \
  --settings-file "<active_settings_file>" \
  --ad-account-id "<selected_ad_account_id>"

验证选定的账户：

api GET "ad_accounts/<ad_account_id>"

从旧版 OAuth 设置成功迁移后，告知 macOS 用户旧版 spotify-ads-api-client-secret Keychain 项目已不再使用，可移除，但不要自动删除（旧版已安装插件可能仍需要）。

直接令牌模式（token）

用于已签发 bearer 令牌的遗留模式。不要要求用户在 slash 命令中包含令牌或粘贴到聊天中。

警告：直接令牌通常约一小时过期，且不能自动刷新。

提示 auto_execute（默认 false）。要求用户在终端运行以下命令，以便助手通过直接附加到该终端的无回显提示收集令牌。不要通过智能体 Bash 工具执行此命令（其安全提示需要用户的控制终端）。写入器将 auth_flow 设为 "direct_token"，并让 refresh_token、token_expires_at、client_id 留空。

python3 "<absolute_plugin_root>/skills/configure/scripts/settings_file.py" direct-token \
  --settings-file "<absolute_active_settings_file>" \
  --prompt \
  --auto-execute "<true_or_false>"

呈现命令前先解析两个绝对路径。若 python3 不可用，用 uv run 替代。等待用户确认助手返回无令牌的设置文件回执后再继续。

之后使用相同的 businesses → ad accounts 发现流程，或在发现失败时请求账户 ID，然后更新 ad_account_id，并验证所选账户。

设置文件格式

---
access_token: "<token>"
refresh_token: "<refresh_token>"
token_expires_at: "<ISO 8601 timestamp>"
client_id: "<team_client_id>"
auth_flow: "authorization_code_pkce"
ad_account_id: "<uuid>"
environment: "production"
auto_execute: false
---

# Spotify Ads API Settings

Local configuration for the spotify-ads-api plugin.
Do not commit this file to version control.

直接令牌模式将 auth_flow 设为 "direct_token"，并让 refresh_token、token_expires_at、client_id 留空。

验证结果

200：配置已保存并验证成功。
401/403：令牌可能无效、过期，或对账户未授权。
404：所选广告账户 ID 可能有误。
其他错误：报告状态与响应错误，不暴露令牌。

安全与迁移

设置文件通过 .codex/*.local.md、.claude/*.local.md、.agents/*.local.md 被 gitignore。
访问与刷新令牌保留在活动本地设置文件中。客户端 ID 是刷新所需的公开应用元数据。
PKCE verifier 与 state 以加密方式生成，verifier 从不打印或持久化。
OAuth 令牌直接写入安全创建的设置文件，从不输出到助手 stdout。
永不请求、读取、存储、记录或传输应用密钥。
永不显示完整的访问或刷新令牌；仅在必要时显示短后缀。
缺少 auth_flow 的现有 OAuth 配置可能使用未过期的访问令牌，但无法刷新。运行一次 OAuth 配置以替换为 PKCE 签发的令牌。

适用场景与限制

适用于需要为 Spotify Ads API 插件完成本地鉴权、团队客户端 ID 绑定、广告账户发现与验证的场景。限制：需要 Python 3.8+ 或 uv；OAuth 模式要求团队管理员预先完成 Spotify Developer 应用与 Ads API 授权并准确注册回环回调 URI；直接令牌模式约一小时过期且无法自动刷新。