Suno Claw

基于 Suno AI 的多轮迭代创作流程，生成符合 Suno 标准的高质量带歌词或纯音乐作品。

Security Scan

The skill appears to implement the claimed Suno/kie.ai music-generation workflow, but there are packaging and documentation inconsistencies (notably a required API key not declared in the registry metadata, and an optional callback URL that could be misused) and missing runtime dependency declarations — review before installing.

Purpose & Capability

The code and SKILL.md match the described Suno/kie.ai music-generation purpose: scripts call https://api.kie.ai and the prompts/scripts implement the multi-agent workflow. However the registry metadata lists no required environment variables while SKILL.md and the scripts require KIEAI_API_KEY — this mismatch is a packaging/documentation problem and could hide surprises during runtime.

Instruction Scope

Runtime instructions are narrowly scoped to collecting creative input, running child agents, packaging prompts, calling the kie.ai API, and storing local memory files. The only external network calls are to the documented API. Two points to note: (1) the skill supports an optional CALLBACK_URL which, if set to an external third-party, could cause generated content or notifications to be sent outside your environment (the docs warn about this); (2) prompts reference using web_search / sessions_spawn — these rely on other platform capabilities (browser/web access or subagent runtimes) not bundled here.

Install Mechanism

No install spec or remote download is present; this is an instruction-and-scripts-only skill. The code files are included in the skill bundle (Python scripts) and there are no opaque external installers or downloads in the manifest.

Credentials

The only credential the skill needs at runtime is the kie.ai API key (KIEAI_API_KEY), which is appropriate for the declared functionality. But the skill bundle/registry did not declare this required env var in metadata (registry shows none), creating an incoherence and an operational surprise. CALLBACK_URL is optional but can direct callbacks to arbitrary endpoints — set only to internal/trusted endpoints or leave unset. No other unrelated secrets are requested.

Persistence & Privilege

The skill writes and reads memory files under its own directory (memory/history.json and memory/patterns.log) and documents retention/rotation rules. It does not request always:true or system-wide configuration changes and does not modify other skills' configs. This level of persistence is expected for a personalization workflow.

What to consider before installing

This skill is largely what it says (a Suno/kie.ai music-generation workflow), but take the following precautions before installing: - Expect to provide a KIEAI_API_KEY: SKILL.md and the scripts require this env var, but the registry metadata omitted it. Confirm the platform will supply this secret and that the developer updates the manifest. - Do not set CALLBACK_URL to an unknown third-party endpoint. If you want callbacks, use an internal/trusted endpoint or leave CALLBACK_URL empty (the scripts default to polling rather than sending callbacks). - Ensure your OpenClaw environment provides Python and the requests library (the included scripts call requests) or run the scripts in a sandboxed environment. - Be aware the skill stores user-generated lyrics and preference signals locally at suno-claw/memory/ (history.json and patterns.log). If you want to remove stored data, delete that directory. - The docs contain minor inconsistencies (e.g., generator.md mentions a default example callback URL, while the script only sends a callback if CALLBACK_URL is non-empty). Ask the author to clarify and to update the registry metadata to list required env vars and any runtime dependencies before you proceed. If you need to be extra cautious, review the included Python scripts (they are short and call only the advertised kie.ai endpoints) and test the skill in an isolated environment first.

SKILL.md — suno-claw

来源: https://github.com/jasonzhang-zzx/suno-claw
作者: jasonzhang-zzx
许可证: MIT

概述

一个基于 Suno AI（kie.ai API）的多代理创意工作流技能。模拟艺术创作的发散与收敛过程，通过迭代式信息解析与生成，逐步产出符合 Suno 输入标准的高质量歌曲。

核心流程： 灵感输入 → 信息收集 → 双轨解析（歌词/音乐性）× 3轮发散 → 封包为 Suno prompt → 渐进生成 → 试听反馈 → 记忆存档

流式输出规则

每个步骤开始和结束时，主代理须输出状态描述，让用户感知 Pipeline 进度：

步骤	开始时	结束时
Step 1 收集	🎯 正在解析您的创意...	✨ 创意解析完成
Step 2 Agent A	✍️ 词作者正在工作...	✍️ 词作者完成（第X轮）
Step 2 Agent B	🎸 编曲师正在工作...	🎸 编曲师完成（第X轮）
Step 3 封包	📦 正在封装提示词...	📦 封装完成
Step 4 生成	🎵 Suno(kieAI) 正在创作...	🎵 创作完成
Step 5 存档	💾 正在保存您的偏好...	💾 已存档

用户对生成结果评分/评价后，触发记忆存档环节。

---

目录结构

suno-claw/
├── SKILL.md                      # 本文件
├── workflow.md                   # 工作流详细说明
├── memory-system.md              # 记忆系统设计
├── prompts/
│   ├── collector.md              # 信息收集代理说明
│   ├── agent-a.md                # Agent A（歌词）子代理完整 Prompt（含角色+JSON Schema+格式规则）
│   ├── agent-b.md                # Agent B（音乐性）子代理完整 Prompt（含角色+JSON Schema+格式规则）
│   ├── executor-main.md          # 主代理执行器（Pipeline 总指挥，含调度逻辑）
│   ├── packager.md               # Suno 封包代理（JSON Schema + 校验规则）
│   └── generator.md               # kie.ai API 调用指南
├── scripts/
│   └── suno_generate.py          # kie.ai Suno API Python 调用脚本
└── memory/
    ├── history.json              # 交互历史（JSON，热数据）
    └── patterns.log              # 压缩模式日志（长期记忆）

---

执行层架构

主代理（executor-main.md 驱动）
    │
    ├── Step 1: 收集 + IS_INSTRUMENTAL 判断
    │       ↓
    ├── Step 2: sessions_spawn 并行调度子代理
    │       ├─ Agent A (agent-a.md) ──→ JSON 歌词结果
    │       └─ Agent B (agent-b.md) ──→ JSON 音乐性结果
    │           ↓ × 3轮（relevance: 1.0 → 0.7 → 0.5）
    ├── Step 3: 封包（packager）→ Suno Prompt × 3
    │       ↓
    ├── Step 4: 渐进生成
    │       ├─ python scripts/suno_generate.py --style_tags ... --lyrics ... --title ...
    │       ├─ 返回音频 URL + 歌词
    │       └─ 展示给用户 → 等待确认 → 下一轮
    │       ↓
    └── Step 5: 用户"喜欢" → 写入 history.json + patterns.log

---

核心概念

1. 相关性衰减（Relevance Decay）

轮次	Relevance	含义
第1轮	1.0	严格围绕原始创意，精准提炼
第2轮	0.7	适度延伸，引入关联元素，参考 HISTORY_SIGNAL
第3轮	0.5	高度发散，探索远距联想，HISTORY_SIGNAL 参考价值最大

• RELEVANCE_LEVEL = 本轮输出相对于 INFO_COLLECTION_TABLE 的相关性强度
• HISTORY_SIGNAL = 来自 patterns.log 的历史偏好参考材料，子代理自行判断如何使用（不是约束指令）

2. IS_INSTRUMENTAL 双分支

IS_INSTRUMENTAL	唤醒的子代理
false（有歌词）	Agent A（歌词）+ Agent B（音乐性）并行
true（纯音乐）	仅 Agent B（音乐性）

3. 渐进生成（用户确认制）

每步生成后先展示试听，用户确认后再跑下一步，有效节约 API 用量。

4. 记忆系统

• 热数据（history.json）：完整交互快照，最近 50 条
• 长期记忆（patterns.log）：成功标签模式压缩存档，无限积累
• 调用新任务时：从 patterns.log 读取偏好，注入 Agent A/B 第2、3轮

---

触发条件

用户说"制作一首..."、"创作一首歌..."、"做一首...风格的歌"、"生成纯音乐"时触发。

---

输入

用户原始创意（字符串），例如：

• "制作一首 Kill This Love 风格的歌曲"
• "做一首西海岸 chill rap"
• "生成一段放松的钢琴纯音乐"

---

输出（每轮生成后）

1. 歌名
2. 试听链接（Suno 音频 URL）
3. 完整歌词（含结构标签，仅 IS_INSTRUMENTAL=false 时）
4. 核心风格描述（≤2句）

---

环境变量

必需环境变量：

变量	必填	说明
KIEAI_API_KEY	✅	kie.ai API 密钥（https://kie.ai/api-key 获取）

可选环境变量：

变量	必填	默认值	说明
CALLBACK_URL	❌	空（不传）	生成完成后的回调地址；若为空字符串则不传给 API，推荐使用内部可信端点

安全说明

• SSL 验证: 始终启用，不可禁用
• CALLBACK_URL 建议: 使用内部可控的回调服务，或留空（由 kie.ai 轮询）
• 避免: 设为未知第三方地址，以免生成内容被意外泄露

记忆文件 Retention

文件	路径	保留策略
history.json	memory/history.json	最近 50 条交互，超出后自动截断（仅保留最新）
patterns.log	memory/patterns.log	聚合偏好模式；单文件上限 1MB，超出后轮转（保留最新）

隐私提示：以上文件包含你的歌词、风格偏好、生成记录。如需清理，删除对应文件即可。

---

质量门控

检查点	标准	失败处理
Agent A JSON 解析	纯 JSON，无 markdown 块	重试，最多3次
Agent A 格式校验	含 [Verse]+[Chorus]，无歌手名	重试当前轮次
Agent B JSON 解析	纯 JSON，无 markdown 块	重试，最多3次
Agent B 格式校验	style_tags ≤ 115字符，无歌手名，≥3个乐器	重试当前轮次
封包校验	style ≤ 115字符，title ≤ 80字符	自动修正
API 失败	返回错误 JSON	自动以更低相关性重试

---

主代理执行参考（executor-main.md）

当运行本技能时，主代理按照 prompts/executor-main.md 中的指引执行：

1. sessions_spawn 并行调度 Agent A + Agent B
2. 每轮 JSON Schema 校验（含歌手名检测正则）
3. 校验失败时反馈错误给子代理，要求重做
4. python scripts/suno_generate.py 调用 kie.ai API
5. 渐进展示 + 用户确认后继续

---

相关技能

• clawhub install suno — Suno API 基础封装（参考 aimusicapi.ai）
• clawhub install browser — 浏览器自动化备用方案