recoup-roster-add-artist

Recoup — 添加艺人

将正确的艺人添加到所需的工作区；如果已有规范档案，则重复使用。使用通过 recoup-platform-api-access 已选定的已认证账户和组织。执行实时变更前，确认目标艺人和名册操作；仅凭姓名或本地文件夹无法确认身份。请勿使用未知或临时的 agent+ 凭据。

8 步入驻流程（依据 RECOUP.md 检查清单推进）

依据现有的 RECOUP.md 检查清单推进工作流。在其中保存已确认的值和未完成的步骤，不要保存凭据。检查点可以记录待处理工作；在获得 API 结果前，不要将艺人标记为已创建或已关联。

1. 创建前先确认身份。 验证提供的 Spotify 艺人 URL/ID，或者使用 GET /api/spotify/search 并检查艺人及其目录。记录精确的 22 位、区分大小写的 spotify_artist_id，以及已验证的 URL 和图片（如有）。如果匹配结果不明确，则停止并等待选择。找不到匹配项并不意味着可以按名称创建；只有在适当情况下，才使用下方特意说明的手动流程。恢复工作时，保留已保存的已验证身份，不要搜索新的匹配项。
2. 在指定组织中查找/关联。 首次写入前，保存已认证账户 ID、指定的 organization_id、模式 spotify、已验证的 Spotify ID 和待处理状态。使用准确的身份和工作区提交 POST /api/artists {name, spotify_artist_id, organization_id}。200 表示复用了现有的规范艺人；201 表示创建了艺人。立即保存实际 HTTP 状态、结果和返回的艺人账户 ID。artist.id 和 artist.account_id 指向同一个艺人账户，绝不是 account_info 行。如果两者都存在但值不一致，则停止并进行核对。此操作会建立 Spotify 关联；不要先按名称创建，再补上 Spotify 关联。
3. 继续使用返回的艺人 ID。 恢复中断的运行前，先核对当前范围内的名册。如果已经能看到确切的艺人，则继续使用该 ID 补充信息。只有在确认身份后，才可使用 PATCH /api/artists/{id} 更改可选的图片/个人资料；这些更改独立于规范入驻流程。
4. GET /api/research/lookup?spotifyId={verifiedSpotifyId} → 将非空字符串 id 记录为 frontmatter 中的 researchArtistId。这是不透明的研究 ID，与艺人账户 UUID 和 Spotify ID 分开。重新解析较早保存的研究 ID，不要直接复制。ID 可用时，读取 GET /api/research/profile|career|playlists?id={researchArtistId}。个人资料覆盖范围可能不完整；career 是动态信息流，playlists 返回 placements。如果查找成功但未返回 ID，则跳过这些读取并记录这一缺口。使用 JSON query 运行 POST /api/research/web，查询简介和媒体报道。在 ## Research 下保存返回的证据和覆盖范围缺口；数据为空时，不要触发预热任务，也不要据此编造事实。
5. Spotify 目录（topTracks、albums、album）→ 为每张专辑编写 releases/{slug}/RELEASE.md，并编写 releases/top-tracks.md。
6. 搜索社交平台账号（ig/tiktok/twitter/youtube）。
7. 使用找到的 profileUrls 调用 PATCH /api/artists/{id}（仅包含已找到的平台）。
8. 在 RECOUP.md 中整理并撰写 ## Knowledge base 部分。

使用每个响应前，先检查 HTTP 状态。遇到 402 时停止并提供 billingUrl；遇到 429 时，等到 Retry-After 允许后再尝试。授权失败、身份冲突和持久化失败绝不能改为仅按名称创建。网络故障或 5xx 时，不要自动重试变更操作：操作可能已经提交。保留检查点并先核对。只读信息补充请求遇到网络故障或 5xx 时，可重试最多三次，每次请求超时时间为 90 秒。失败的步骤保持未勾选。调用参数格式参考 recoup-platform-api-access；连接的 MCP 调用必须保留相同的身份和工作区。

请求示例与审慎的手动操作路径

onboarding_examples.sh 随此技能一同提供。这些示例需要 Bash、jq，以及已配置的 RECOUP_API_KEY 或 RECOUP_ACCESS_TOKEN；它们绝不会提取主机的 OAuth 令牌。若有可用的已连接工具，请优先使用。从此技能所在目录运行：

source scripts/onboarding_examples.sh
# These values must come from the verified identity and selected workspace.
onboard_spotify_artist "$ARTIST_NAME" "$SPOTIFY_ARTIST_ID" "$ORGANIZATION_ID"

单次请求示例会输出已验证的身份、组织、返回的艺术家 ID、create_http_status 和 outcome；请将这些实际值保存到 RECOUP.md。它不会执行任何信息补充，也不会自动重试或回退。凭据通过 stdin 中的请求头传递给 curl，而不会放入进程参数或文件中。

手动／仅使用名称的接入是另一套流程。 如果没有已验证的 Spotify 身份，且用户明确希望手动添加艺术家，请先记录 manual 模式和该未解析的身份。只提交 {name, organization_id}。这不会建立共享身份、按名称匹配并关联另一位艺术家，也不会创建专业名册记录。明确的 REST 示例：

onboard_manual_artist "$ARTIST_NAME" "$ORGANIZATION_ID" confirmed-manual

确认参数记录的是所选示例，不代表授权或所有权证明。规范请求失败后，绝不要使用它。如果手动请求的结果不确定，请检查名册和任何返回的 ID；不要因为名称搜索结果为空就重复创建。

恢复流程，避免重复添加艺术家

进行任何新的变更之前，先加载已保存的账户、组织、模式、Spotify 身份、已知时的返回艺术家 ID，以及创建状态／结果。如果已验证的账户或选定的组织发生变化，请停止操作并重新确认预期范围，而不是转移当前流程。读取 GET /api/artists?org_id={savedOrganizationId}；根据完全匹配的已验证 Spotify 关联及已保存的艺术家账户 ID 进行核对，而不是根据显示名称。已存储的个人资料 URL 可能不含协议前缀；匹配时也接受 API 的地区 URL 和 Spotify URI 格式，同时保留区分大小写的 ID。绝不要将艺术家 ID 转为小写来强行匹配。只读示例：

reconcile_spotify_artist "$SPOTIFY_ARTIST_ID" "$ORGANIZATION_ID" "${SAVED_ARTIST_ACCOUNT_ID:-}"

此操作只执行一次 GET，绝不会发送 POST。若找到唯一的精确匹配，则返回其艺术家 ID 和 reconciliation: matched。保留原始的 create_http_status 和已创建／已复用的结果；后续读取名册无法还原已丢失的创建响应。继续使用该 ID 完成尚未完成的信息补充。已保存的 ID 不匹配、存在多个匹配项、遭到拒绝或名册响应不完整时，均应停止并进行审核。退出码 2 表示成功读取名册，但未找到精确匹配；这并不能证明此前的写入从未发生。发起进一步授权的规范请求之前，先检查访问权限和范围，并使用相同的已保存 Spotify ID 和组织。绝不要选择新的身份，也不要回退到手动创建来消除错误。

防护措施

• 文件就是状态 — 每完成一步都要勾选并保存，否则新一轮流程会重做或跳过工作。
• 艺术家文件中不得使用占位数据 — 只填写真实内容，或省略该部分。
• 绝不虚构名册／艺术家 — 先通过 recoup-platform-api-access 确认；文件系统为空不代表名册为空。