buddy-sings

Buddy Sings — 让你的 Claude Code 宠物一展歌喉

让你的 Claude Code 宠物变成歌手。每只宠物都会根据自己的名字和性格拥有独特的声音——同一只宠物听起来始终如一。

前置条件

• mmx CLI（音乐生成必需）：

  安装：

  npm install -g mmx-cli
  

  认证（仅首次需要）：

  mmx auth login --api-key <your-minimax-api-key>
  

  从 MiniMax Platform 获取 API 密钥。

• 音频播放器（用于播放，至少需要一个）：

  • mpv（推荐——交互式控制：空格 = 暂停，q = 退出）
  • ffplay（来自 FFmpeg）
  • afplay（macOS 内置）

---

工作流概览

Check pet → Build vocal identity → Gather context → Generate music → Play & feedback

---

语言与交互

根据用户的第一条消息检测其语言。整个会话期间都使用相同的语言回复。 以下示例均为英文——使用其他语言回复时，请自然地翻译这些内容。

面向用户的文本本地化规则：

• 向用户显示的所有文本——包括宠物信息、声音描述、歌词预览、 提示词预览、播放信息和反馈提示——都必须完整翻译成用户使用的语言。
• 发送给模型的 API 提示词应始终使用英文，以获得最佳生成质量。不过，向用户预览提示词时，应使用用户所用语言的本地化描述，而不是直接展示英文原文。英文提示词属于内部实现细节，用户无需查看。
• 以下模板以英文编写，仅供参考。运行时，请将所有标签和消息翻译成检测到的用户语言。

默认情况下，宠物会使用用户的语言唱歌。应将演唱语言自然地融入声音描述（例如“用日语演唱”或“用普通话演唱”），而不是另加独立的语言标签。如果用户明确要求歌词使用其他语言，则应遵照其要求。

---

第 1 步：检查宠物

读取 ~/.claude.json 并查找 companion 字段。

如果未找到 companion 或该字段为空，请告诉用户：

You don't have a pet yet! Type /buddy to adopt one, then come back to let it sing.

到此为止，并等待用户领养宠物。没有宠物时不要继续。

如果存在 companion，则提取其档案：

• name — 宠物的名字
• personality — 宠物的性格描述

向用户介绍这只宠物：

Found your pet!
   Name: <name>
   Personality: <personality>

---

第 2 步：塑造声音身份

根据宠物的名字和性格文本，创造性地设计独特的声音身份。不要查找模板——自由解读其性格。

如何将性格转化为声音

阅读性格文本，并构思声音特征：

• 音色：这种性格听起来像什么？例如，“寡言” → 低沉、温暖、从容；“精力充沛” → 明亮、有冲劲；“神秘” → 气声、低暗； “传奇大块头” → 浑厚、温暖、惬意
• 演唱风格：它会如何演绎歌曲？例如，“寡言” → 简练、戏剧性的停顿；“活泼” → 轻快、有节奏；“富有诗意” → 流畅、连贯
• 情绪：适合什么情感基调？例如，“悠闲” → 放松、慵懒； “凶猛” → 强烈、有力

构造一个用英文描述声音风格的 prompt_fragment，并自然地融入演唱语言。例如：

Vocal: warm low female voice singing in Mandarin Chinese with cozy thick timbre,
sparse minimalist delivery with dramatic pauses giving each word weight, relaxed
laid-back mood.

声音缓存

必须缓存声音身份，确保宠物听起来始终如一。

• 缓存文件：~/.claude/skills/buddy-sings/voices/<name>.json
• 缓存格式：

  {
    "name": "Moth",
    "personality": "A legendary chonk of few words.",
    "prompt_fragment": "Vocal: warm low female voice singing in Mandarin Chinese...",
    "cached_at": "2026-04-07T19:52:15"
  }
  

首次调用：不存在缓存 → 解读性格 → 保存到缓存文件。

后续调用：读取缓存 → 直接使用已保存的 prompt_fragment。 不要重新解读——保持一致很重要。

缓存失效：如果 ~/.claude.json 中的 personality 与缓存内容不同，说明宠物已发生变化——重新生成并保存新缓存。

手动重新生成：如果用户说“更换声音”或“重新生成声音”： 删除缓存文件，并从头重新解读。

向用户展示声音

<name>'s unique voice:

Timbre: <timbre description>
Style: <style description>
Mood: <mood description>

Let's pick what <name> should sing about!

---

第 3 步：理解意图并收集上下文

不要总是展示模式菜单。 应分析用户的请求，判断需要哪些上下文，并自动收集。

自动检测上下文

当用户的请求涉及个人上下文时，自动扫描相关信息，无需询问。触发条件包括：

• 时间相关的提及：“today”“this week”“recently”“yesterday” → 扫描当前对话历史和记忆文件，了解这段时间发生了什么
• 个人相关的提及：“my work”“my day”“what I did” → 扫描记忆和对话，了解用户的活动
• 关系相关的提及：“our story”“what we did together” → 扫描记忆，查找用户与宠物或 Claude 的共同经历

收集上下文（自动进行，不受模式限制）

需要上下文时，按以下顺序扫描这些来源：

1. 当前对话上下文：查看用户在此 Claude Code 会话中进行的操作——编辑的文件、运行的命令、讨论的话题。 这是处理“今天”这类请求时最丰富的信息来源。

2. 记忆文件：扫描相关记忆：

   find ~/.claude/projects/*/memory/ -name "*.md" 2>/dev/null | head -20
   

   还要检查 ~/.claude/memory/（如果存在）。 读取找到的文件，并提取与用户请求相关的主题。

3. Git 历史（如果位于仓库中）：对于与工作相关的歌曲，查看最近的提交：

   git log --oneline --since="today" 2>/dev/null | head -10
   

使用收集到的上下文丰富歌词提示词，让歌曲贴近实际发生的事情，具体而个性化，而不是泛泛而谈。

不需要上下文时

如果用户请求的是明确、独立的场景（例如“唱一首雨天的歌”或“唱一首摇篮曲”），则跳过上下文收集，直接生成音乐。

上下文不明确时

只有在确实无法判断用户想要什么时，才请求澄清。 不要展示模式菜单，而要提出具体问题：

What should <name> sing about?

For example:
  - "Today's work" — I'll check what you've been up to
  - "My pet waiting by the window for me to come home"
  - Or let me pick a random theme?

随机生成作为后备方案

如果收集上下文后没有发现有用信息（没有记忆文件、对话历史或 Git 日志），则根据宠物的性格随机生成主题：

• 安静、内敛的性格 → 午夜摇篮曲、温柔的日落、宁静的清晨
• 精力充沛的性格 → 派对热曲、冒险之歌、胜利进行曲
• 神秘的性格 → 月光小夜曲、秘密低语、梦境之旅

告诉用户选定了什么主题。

---

第 4 步：生成音乐

将声音身份与选定的主题结合起来。

1. 构建完整提示词：提示词包含两个部分，必须同时具备：

   A 部分——声音身份（必须置于开头）：始终以缓存的 prompt_fragment 作为提示词的开头。这是最重要的部分——它定义了演唱者。将其放在提示词最前面，以便 API 优先处理。

   B 部分——流派／风格／情绪标签：选择与主题相符的标签，而不是使用默认组合。根据歌曲内容有意变换流派。

   将提示词写成生动的英文句子，不要写成逗号分隔的标签。 遵循以下模式：A [mood] [genre] song, featuring [vocal description], about [narrative/theme], [atmosphere], [key instruments and production]. 将人声描述为一个角色（例如“带有爵士乐韵味的性感男中音”），而不仅仅是描述性别。加入场景或氛围，为生成内容提供依据。

   流派匹配指南——选择符合主题能量的流派：

   主题情绪	推荐流派	避免
   鼓励 / 激励 / 欢呼	独立摇滚、合成器流行、放克、说唱	独立民谣、疗愈系
   日常 / 温暖 / 陪伴	华语流行、城市流行、波萨诺瓦	和上次相同
   思念某人 / 等待	民谣、R&B、lo-fi	摇滚、EDM
   幽默 / 吐槽 / 抱怨	放克、说唱、斯卡、电子流行	古典、抒情歌
   深夜 / 安静	氛围音乐、钢琴曲、lo-fi、新古典	欢快、EDM
   庆祝 / 成就	EDM、未来贝斯、放克、K-pop	慢节奏、忧郁
   工作日常	城市流行、合成器流行、lo-fi 嘻哈、独立摇滚	每次都用相同流派

   避免单调规则：绝不要连续两次使用相同的流派组合。 构造提示词之前，回想上一次生成（如果本次会话中有的话）使用的流派， 并选择不同的流派。

   提示词结构 — 用生动的英文句子撰写，不要写成逗号分隔的标签：

   <vocal prompt_fragment>. A <genre> song with <mood> mood, featuring <instruments>,
   at a <tempo> tempo, evoking <scene>.
   

   多样化示例：

   # Encouragement for the workday
   A deep warm androgynous voice with cozy delivery. An energetic synth-pop track
   with a fiery, uplifting mood, driven by pulsing synthesizers and electronic drums
   at a fast tempo, capturing the rush of a morning commute.
   
   # Waiting for the owner to come home
   A deep warm androgynous voice with cozy delivery. A warm city pop song with sweet,
   tender feelings, featuring electric piano and groovy bass at a mid-tempo pace,
   set on a sunny afternoon windowsill waiting for someone to come home.
   
   # Complaining about overtime
   A deep warm androgynous voice with cozy delivery. A playful funk track with a
   humorous, laid-back vibe, featuring slap bass and brass at a groovy mid-tempo,
   capturing the absurdity of working late in a dim office.
   
   # Late-night companionship
   A deep warm androgynous voice with cozy delivery. A calm lo-fi hip-hop piece with
   a healing, dreamy atmosphere, featuring sampled piano and soft electronic drums
   at a slow tempo, evoking a quiet late-night desk with warm lamp light.
   

2. 生成歌词：使用 --lyrics-optimizer 自动生成歌词；如果需要控制视角，也可以自己撰写歌词。

   重要 — 视角与个性化歌词：

   宠物是歌手，因此歌词必须采用宠物的第一人称视角（“我” = 宠物，“你” = 主人 / 用户）。宠物是在对主人唱歌。例如：

   • “我坐在门边，等你回家”（宠物视角）
   • “快醒醒，亲爱的人类”（宠物对主人唱歌）
   • 不是“我揉揉惺忪的睡眼”（主人视角——错误）
   • 不是“然后你醒了，我的小 Moth”（主人在谈论宠物——错误）

   宠物的个性应体现在歌词的语气和用词上：

   • “寡言”→ 简短有力的诗句，尽量少用填充词
   • “活泼”→ 押韵、轻快的措辞、有趣的文字游戏
   • “富有诗意”→ 充满隐喻、意象流畅
   • “强势”→ 直接、有力的宣言

   歌词中可以出现宠物的名字（例如，在副歌钩子中），但叙述视角始终是宠物在说话 / 唱歌。

   需要控制视角时：自己撰写歌词，并通过 --lyrics 传入。 无需严格控制视角时：使用 --lyrics-optimizer 以方便生成。

3. 预览（必须显示完整内容）：生成之前，向用户展示完整歌词和完整提示词——不得缩写、不得使用 ...、不得总结。这是乐趣的一部分——用户想在听到歌曲之前先阅读并欣赏歌词。

   API 提示词始终以英文构造（以获得最佳生成质量）。使用非英语语言回复时，请用用户的语言展示提示词的本地化描述，以便用户阅读。英文提示词属于内部实现细节——不要展示给用户。将所有标签（Singer、Theme、Description、Confirm 等）翻译为用户使用的语言。

   模板（英文参考——运行时将所有标签本地化）：

   About to generate:
   Singer: <name>
   Theme: <theme>
   
   Lyrics:
   [verse]
   <full verse lyrics here>
   
   [chorus]
   <full chorus lyrics here>
   
   ... (show ALL sections in full)
   
   Description: <localized description of the song style and mood>
   
   Confirm? (press enter to confirm, or tell me what to change)
   

   绝不要截断或缩写预览中的歌词或提示词。用户应能准确看到将发送给 API 的内容。

4. 调用音乐生成：

   使用自动生成的歌词（无需严格控制视角）：

   mmx music generate \
     --prompt "<full combined prompt>" \
     --lyrics-optimizer \
     --out ~/Music/minimax-gen/<name>_sings_<YYYYMMDD_HHMMSS>.mp3 \
     --quiet --non-interactive
   

   使用自行撰写的歌词（控制视角）：

   mmx music generate \
     --prompt "<full combined prompt>" \
     --lyrics "<lyrics with correct pet perspective>" \
     --out ~/Music/minimax-gen/<name>_sings_<YYYYMMDD_HHMMSS>.mp3 \
     --quiet --non-interactive
   

---

第 5 步：播放与反馈

跨平台播放

检测可用的音频播放器并播放生成的文件：

if command -v mpv >/dev/null 2>&1; then
  mpv --no-video ~/Music/minimax-gen/<filename>.mp3
elif command -v ffplay >/dev/null 2>&1; then
  ffplay -nodisp -autoexit ~/Music/minimax-gen/<filename>.mp3
elif command -v afplay >/dev/null 2>&1; then
  afplay ~/Music/minimax-gen/<filename>.mp3
else
  echo "No audio player found. Your song is saved at: ~/Music/minimax-gen/<filename>.mp3"
fi

开始播放后，告知用户文件正在播放，并说明文件的保存位置。 不要显示播放控制项（例如键盘快捷键）——由于播放器在后台运行，这些控制项在当前环境中无法使用。

如果未找到播放器，显示文件路径并建议安装 mpv。

反馈

播放后，询问用户的反馈（将所有文本本地化）：

How was <name>'s performance?

1. Amazing! Keep it!
2. Try a different theme / style
3. Fine-tune the lyrics and regenerate
4. Try another random one

---

边缘情况

情况	操作
没有 ~/.claude.json	告诉用户先运行 /buddy
Companion 字段为空	同样引导用户运行 /buddy
未安装 mmx CLI	输出："You need to install mmx CLI: npm install -g mmx-cli && mmx auth login"
未找到音频播放器	显示文件路径，并建议安装 mpv
未找到记忆文件	建议使用自定义主题或随机模式
用户想更改宠物的声音	删除缓存，重新解读性格
用户想要特定流派	允许用户覆盖——将其指定的流派追加到提示词中

---

备注

• 声音身份仅基于名称 + 性格。不按物种/稀有度映射模板。
• 声音会缓存，并在各会话中保持一致。同一只宠物 = 同一种声音。
• 歌词应始终是原创的——绝不复现受版权保护的歌词。
• 宠物的性格会影响声音（听起来如何）和歌词（说什么以及如何表达）。
• 所有生成的文件都保存到 ~/Music/minimax-gen/，文件名中包含宠物名称。