artist-workspace

艺术家工作区

每位艺术家都有一个工作区——一个存放上下文、歌曲和参考资料的目录。根目录中的 RECOUP.md 文件将其连接到 Recoupable 平台。

艺术家目录位于沙盒中的 artists/{artist-slug}/。沙盒已限定为单个 Recoupable 组织（其仓库就是该组织），因此艺术家目录位于顶层——没有 orgs/ 目录。

列出沙盒中的内容

当账户询问“我有哪些艺术家”“列出我的艺术家”“我属于哪些组织”或其他关于沙盒内容的清单问题时，遍历文件系统——它是该沙盒的权威信息来源。 不要为此调用 Recoupable API：API 回答的是“此账户在所有范围内有权访问哪些艺术家”，这与沙盒创建时所针对的集合不同（而且通常更多）。

# All artist workspaces in this sandbox
ls -d artists/*/ 2>/dev/null

# Every artist's identity file — read the frontmatter for name/slug/id
find artists -type f -name RECOUP.md 2>/dev/null

每个 RECOUP.md 都有 frontmatter（artistName、artistSlug、artistId）——使用 head 或任何 YAML 解析器读取，以获取规范身份信息。

如果 artists/ 不存在，说明沙盒尚未设置——请引导账户使用 setup-sandbox skill，而不是凭空编造数据。

创建新艺术家

当用户要求创建一位新艺术家（或让其入驻、添加或完成设置）时，请通过一个清单文件来推进工作——不要试图凭记忆执行整个流程。设置过程包含 8 个依次进行的 API 调用，而 Agent 循环在不同轮次之间会丢失状态；清单可以让你顺利恢复进度，并证明哪些步骤确实已执行。

步骤 0：在调用任何 API 之前搭建工作区框架

选择一个 slug，创建目录，并写入初始 RECOUP.md 模板——frontmatter 保存流程中获取的值，正文列出尚未勾选的步骤：

ARTIST_SLUG=$(echo "$ARTIST_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]\+/-/g; s/^-//; s/-$//')
ARTIST_DIR="artists/$ARTIST_SLUG"
mkdir -p "$ARTIST_DIR"

cat > "$ARTIST_DIR/RECOUP.md" <<EOF
---
artistName: $ARTIST_NAME
artistSlug: $ARTIST_SLUG
artistId:
spotifyArtistId:
spotifyProfileUrl:
imageUrl:
cmArtistId:
---

# $ARTIST_NAME

## Setup checklist

- [ ] 1. Create the artist (\`POST /api/artists\`) — capture \`account_id\` → \`artistId\`
- [ ] 2. Find canonical Spotify match (\`GET /api/spotify/search\`) — capture \`id\`, \`external_urls.spotify\`, \`images[0].url\`
- [ ] 3. PATCH artist with image + Spotify profile URL
- [ ] 4. Structured research — \`/research/lookup\` (capture \`cmArtistId\`) → \`/research/profile\` + \`/research/career\` + \`/research/playlists\` + \`/research/web\`. Save responses under \`## Research\` in this file.
- [ ] 5. Pull Spotify catalog → write \`releases/{album-slug}/RELEASE.md\` per album + \`releases/top-tracks.md\` (see Releases section)
- [ ] 6. Web search for additional socials (instagram / tiktok / twitter / youtube)
- [ ] 7. PATCH artist with discovered socials
- [ ] 8. Synthesize knowledge base — append it as \`## Knowledge base\` in this file

## Notes
EOF

文件写入磁盘之前，不要继续执行步骤 1。

步骤 1–8 的完整逐条 curl 操作手册位于 create-artist skill 中，也可在文档网站 https://developers.recoupable.com/skills/create-artist 上找到。在搭建框架时加载该 skill 一次，并按其 8 步流程执行。

每一步完成后：勾选并保存

每完成一步后，都要将两项更改写回 RECOUP.md：

1. 勾选复选框（- [ ] → - [x]），标记刚执行的步骤。
2. 将获取的值写入 frontmatter（artistId:、spotifyArtistId:、spotifyProfileUrl:、imageUrl:、cmArtistId:）。后续步骤会从 frontmatter 读取这些值——绝不要重新推导已保存的内容。较大的数据（研究响应、社交媒体 URL）应放在正文各自的标题小节下，而不是 frontmatter 中。

该文件就是工作流状态。如果某个值没有写入磁盘，下一轮就无法获知它。

恢复未完成的设置

如果 $ARTIST_DIR/RECOUP.md 已存在，不要重新执行已完成的步骤。读取文件，找到第一个未勾选的项目，并使用已获取的 frontmatter 值从那里继续：

# Show the next unchecked step
grep -n '^- \[ \]' "$ARTIST_DIR/RECOUP.md" | head -1

如果所有项目都已勾选，说明艺术家的设置已全部完成——在进行其他操作之前，先向用户确认。

为什么要使用清单

根据文字说明执行冗长且确定性很强的流程，往往会漏掉步骤：Agent 读一遍文档，执行几次调用，然后忘记其余内容。将状态保存在文件中的清单可以避免这种情况——进度在磁盘上一目了然，每个步骤都会产生回写副作用，新一轮可以直接从文件恢复，而不必重新推导已完成的内容。

进入艺术家工作区

开始在艺术家目录中工作时：

1. 阅读 RECOUP.md，确认你位于艺术家工作区，并获取艺术家的姓名、slug 和 ID。
2. 检查现有内容 — 对目录运行 ls，查看其中已有的文件和文件夹。
3. 如果 context/artist.md 存在，则阅读它 — 这是关于艺术家身份的事实来源。你所做的一切都应与之保持一致。
4. 查看这位艺术家近期的 git 历史 — 在仓库根目录运行 git log --oneline -10 -- artists/{artist-slug}/，只显示涉及这位艺术家文件的提交。如果你已位于艺术家目录中，则改用 git log --oneline -10 -- .。在进行自己的更改之前，先阅读提交消息，了解近期的变化。

---

在艺术家目录中工作

内容放在哪里

填充完整的艺术家工作区如下所示。这里的内容都不会预先创建 — 只有在有实际内容时，才会添加相应的文件和目录。

{artist-slug}/
├── RECOUP.md                    # identity — connects workspace to the platform
├── context/
│   ├── artist.md                # who they are, how they present, creative constraints
│   ├── audience.md              # who listens and what resonates
│   └── images/
│       └── face-guide.png       # face reference for visual content generation
├── releases/
│   ├── top-tracks.md            # cross-release Spotify top tracks (snapshot)
│   └── {release-slug}/          # one folder per album / EP / single
│       └── RELEASE.md           # tracklist + Spotify metadata + cover art URL
└── songs/
    └── {song-slug}/
        ├── {song-slug}.mp3
        └── {song-slug}.wav

如果文件或目录尚不存在，请在有内容时创建。如果已经存在，则更新它 — 先阅读现有内容，不要直接覆盖。目录结构应随着工作逐步形成，而不是由脚手架预先搭建。

静态与动态上下文

将艺术家上下文分为两个层次：

静态上下文描述艺术家是谁。它的变化较为缓慢 — 可能跨越数月、发行周期或职业阶段。artist.md 和 audience.md 都属于静态上下文。一位 20 岁的卧室流行钢琴家，明年可能仍然是卧室流行钢琴家，但随着时间推移，她可能会尝试新的音色、改变美学风格，或触达不同的受众。请审慎更新静态上下文，不要随意更改。修改 artist.md，就意味着更改所有工具和 Agent 所依赖的事实来源。

动态上下文描述当下正在发生的事。发行文档、宣传活动调研、策略文档 — 都与特定时间有关。它们会不断补充内容、逐渐过时，也会被下一个周期的内容取代。请将它们视为有时效性的内容。当发行周期结束或调研过时时，应将其归档，而不是让它们堆积在工作目录中。

这种区分很重要，因为读取工作区的 Agent 需要知道：这是关于艺术家的长期事实，还是三个月前的记录？静态上下文应当值得信赖。动态上下文应当保持最新 — 如果已经过时，就应将其移出工作目录。

艺术家上下文（context/artist.md）

这是工作区中最重要的文件。它定义艺术家的身份、品牌、声音、美学和创作限制。其他工具和 Agent 会读取它，以确保内容符合品牌风格。这属于静态上下文 — 只有在艺术家确实发生变化时才更新，不要因为每次宣传活动的调整而更改。

在掌握真实信息后再创建。包含真实数据的不完整档案，胜过充满占位符的完整模板。不要编造你不知道的细节 — 宁可省略相应章节，也不要猜测。

首次创建时，请阅读 references/artist-template.md，了解各章节的结构。查看 references/artist-example.md，了解填写完成后的样子。

受众上下文（context/audience.md）

描述粉丝是谁、哪些内容能引起他们的共鸣，以及他们如何交流。这属于静态上下文 — 受众会随着艺术家的成长逐渐变化，而不是随每次发行改变。

掌握真实的受众数据后再创建。首次创建时，请阅读 references/audience-template.md。

歌曲

歌曲是源材料。它们永久保存在 songs/{song-slug}/ 中。将 mp3 文件命名为歌曲名称 — 下游工具会将文件名用作歌曲标题。

songs/adhd/adhd.mp3           ✓  title becomes "adhd"
songs/adhd/audio.mp3          ✗  title becomes "audio"

发行作品

发行作品存放在 releases/{release-slug}/。每个发行作品对应一个文件夹，根目录下有一份 RELEASE.md——这是贯穿发行作品整个生命周期（公告、发行周、后续维护）的主要发行管理文档。其他所有发行级别的资料（调研、文案、素材、衍生报告）都放在同一文件夹中。

Slug 命名约定——项目标题使用 lowercase-kebab-case，并加上格式后缀：

• 专辑 → releases/{title-slug}/（无后缀——专辑是默认格式）
• EP → releases/{title-slug}-ep/
• 单曲 → releases/{title-slug}-single/
• 合辑 → releases/{title-slug}-compilation/

releases/after-hours/RELEASE.md          # album
releases/adhd-ep/RELEASE.md              # EP
releases/blinding-lights-single/RELEASE.md

RELEASE.md 包含 18 个部分，涵盖项目概况、标识符和元数据、叙事、受众、DSP 策略、营销、社交媒体、公关、视觉素材、实体产品／周边／巡演、团队、预算、KPI 跟踪和链接中心，另有待完成事项表格和文档历史记录。完整的规范模板、共享标签约定（[INTERNAL] / [SHAREABLE] / [OPS]）和状态标记（✅ / ❌ / ⚠️ TBD / N/A），请参阅 references/release-template.md。

文档通过 slug 引用歌曲，不会重复或移动歌曲文件。

Spotify 目录数据存放位置

创建艺人流程的第 5 步（Spotify 目录）会填充此文件夹：

• GET /api/spotify/artist/albums 返回的每张专辑 → 根据 references/release-template.md 初始化 releases/{release-slug}/RELEASE.md。第 5 步会填写可从 Spotify 获取的字段（第 1 节：艺人名称、项目标题、发行日期、格式；第 2.1 节：Spotify URI；第 2.2 节：每首曲目的标题、时长和显式内容标记；第 2.3 节：对本地 songs/ 的交叉引用；第 18 节：封面图片 URL），其他所有内容均保留为 ⚠️ TBD。Spotify 公开响应中不包含 ISRC、UPC、词曲作者／制作人、唱片公司、发行商，以及任何营销／公关／预算部分——这些内容会保持为 TBD，直到用户提供相关信息。完整的字段映射请参阅 references/release-template.md。

• GET /api/spotify/artist/topTracks → releases/top-tracks.md（跨发行作品快照——它们本身并非发行作品，但由于这些都是 Spotify 目录数据，因此存放在此处；将其与发行作品放在一起，能让目录集中管理）。内联结构：

  ---
  title: Top Tracks
  source: spotify
  snapshotDate: {YYYY-MM-DD}
  ---
  
  # Top Tracks
  
  | # | Track | Album | Duration |
  |---|-------|-------|----------|
  | 1 | {name} | {album-slug or external} | {mm:ss} |
  

整理其他文件

将相关文件归类存放。竞品分析、品牌指南和策略文档都属于调研资料——它们应放在同一个目录中，而不是分散在三个目录里。新建目录前，先确认该文件是否适合放在已有目录中。

动态上下文变得过时后——例如发行周期结束、策略文档不再适用——请将其移至归档目录，不要删除，也不要继续放在活动文件所在位置。需要时再创建归档目录，无须提前创建。

数据只存放一处。歌曲放在 songs/，不要复制到发行作品文件夹中。上下文放在 context/，不要重复放进调研文档。如果需要引用其他位置的数据，请按路径引用，不要复制。

命名约定

• 目录和 slug： lowercase-kebab-case
• 歌曲文件： songs/{song-slug}/{song-slug}.mp3

跟踪更改

使用 git 历史记录作为进度日志。艺人目录中的每项更改都应作为一次提交，并附上说明更改内容和原因的提交信息。

艺人目录的良好提交信息示例：

artist: update aesthetic — shifting from bedroom to lo-fi studio (user direction)
songs: add 5 tracks from ADHD EP with lyrics and clips
research: competitive analysis for Q2 release planning
release: update ADHD EP — distributor confirmed as SpaceHeater
context: refine audience — adding Gen Alpha psychographics from fan survey
archive: move pre-release strategy docs from ADHD EP cycle

格式为：{what}: {why}。其中，“what”说明涉及的范围，“why”则向下一个 Agent 说明更改的意图——不仅是发生了什么变化，还要说明为什么变化。对于静态上下文的更改，这一点尤其重要，因为未来的 Agent 需要判断更新是有意演进还是误操作。

不要为每位艺人单独维护进度文件。git 日志才是事实来源。若要了解发生过什么，请查看提交记录。

为什么采用这种结构

艺术家工作区过去会预先创建 10 多个目录，在每个文件夹中放置 README 文件、占位模板、分级记忆系统和每位艺术家各自的配置文件。由于 Agent 无法分辨哪些是真实数据、哪些只是脚手架，其中大部分内容很快就会过时。对于不在场的 Agent 来说，满是 {placeholder} 标记的文件看起来就像真实数据，结果自然会受到影响。

当前的结构刻意保持精简。只有在有真实内容可供存放时，才会创建相应内容。该技能会指导内容应放在哪里，让 Agent 能随着工作开展逐步构建工作区。