用途
ACE-Step 音乐生成技能用于通过 ACE-Step V1.5 API 进行音乐创作，覆盖文本生音乐、歌词生成、音频续写、音频重绘（repainting）与翻唱（cover）等场景。该技能要求始终通过 scripts/acestep.sh 脚本调用，不直接请求 API 端点。
主要能力
- 文本生音乐（Caption 模式）：通过 -c 指定音乐描述、-l 提供完整歌词，可设置时长、BPM、调性（key-scale）、拍号（time-sig）等参数。
- 纯器乐生成：直接以描述文本生成。
- 快速探索：使用 -d 或 random 的简单/随机模式获取灵感或进行器乐探索。
- 翻唱与音频重绘：基于源音频文件生成新风格/新歌词的翻唱，或修改音频中指定区间（--repaint-start / --repaint-end）。
- 歌曲创作辅助：配合 acestep-songwriting 技能进行歌词写作、caption 创建以及时长/BPM/调性选择。
- 简单 MV 制作：配合 acestep-songwriting、acestep-lyrics-transcription、acestep-simplemv 技能渲染带波形可视化与同步歌词的音乐视频；可选 acestep-thumbnail 技能通过 Gemini API 生成封面或背景图。
- 歌词转录与缩略图生成可作为独立任务并行执行以节省时间。
使用方式
使用前需切换到技能目录（例如 {project_root}/{.claude 或 .codex}/skills/acestep/），然后用脚本命令操作：
- 检查服务健康： ./scripts/acestep.sh health
- 带歌词生成（推荐）： ./scripts/acestep.sh generate -c "pop, female vocal, piano" -l "[Verse] Your lyrics here..." --duration 120 --language zh
- 纯器乐生成： ./scripts/acestep.sh generate "Jazz with saxophone"
- 快速探索： ./scripts/acestep.sh generate -d "A cheerful song about spring" ./scripts/acestep.sh random
- 翻唱： ./scripts/acestep.sh cover song.mp3 -c "Rock cover style" -l "[Verse] Lyrics..." --duration 120 --bpm 128
- 音频重绘： ./scripts/acestep.sh generate --src-audio song.mp3 --task-type repaint -c "Pop" --repaint-start 30 --repaint-end 60
- 其他命令： ./scripts/acestep.sh status <job_id> ./scripts/acestep.sh models
提供歌词时（-l 参数）必须传入全部歌词内容，不得截断、删减或只传部分，否则会导致歌曲不完整或不连贯。
配置项遵循优先级：命令行参数 > config.json 默认值。仅 config --set 命令会永久修改 config.json。默认配置文件（scripts/config.json）包含 api_url、api_key、api_mode，以及 generation 下的 thinking、use_format、use_cot_caption、use_cot_language、batch_size、audio_format、vocal_language 等字段。
API 模式支持两种：
- completion（默认）：使用 /v1/chat/completions，兼容 OpenRouter，同步请求，音频以 base64 内联返回并自动解码保存；无需轮询，但 inference_steps、infer_method、shift 不可配置，--no-wait 与 status 命令不适用，需 model 字段（未指定时从 /v1/models 自动检测）。
- native：使用 /release_task + /query_result，异步轮询模式，支持所有参数。
切换模式示例： ./scripts/acestep.sh config --set api_mode completion ./scripts/acestep.sh config --set api_mode native
官方云 API 配置（https://api.acemusic.ai）： ./scripts/acestep.sh config --set api_url "https://api.acemusic.ai" ./scripts/acestep.sh config --set api_key "your-key" ./scripts/acestep.sh config --set api_mode completion 官方云 API 当前可通过 acemusic.ai 免费获取密钥。本地服务（默认 http://127.0.0.1:8001）无需配置。自定义远程服务可更新 scripts/config.json 或使用 config --set 指定 api_url 与 api_key。
首次使用前需检查 API 密钥与 URL 状态： config --check-key config --get api_url 当 api_url 为官方云 API 且 api_key 为空时必须停止并引导用户配置密钥。检查密钥配置使用 config --check-key（仅报告是否已配置），不要使用 config --get api_key 或直接读取 config.json，以免暴露密钥；config --list 会自动掩码。
依赖方面，脚本需要 curl 与 jq；若 jq 未安装脚本会尝试自动安装，失败时可按平台手动安装（Windows: choco install jq 或从 https://jqlang.github.io/jq/download/ 下载；macOS: brew install jq；Linux: sudo apt-get install jq 或 sudo dnf install jq）。
输出文件与结果结构
生成后脚本自动将结果保存到项目根目录的 acestep_output 文件夹（与 .claude 同级），包含 <job_id>.json（完整任务结果）与 <job_id>_1.mp3、<job_id>_2.mp3 等音频文件（batch_size > 1 时有多个）。JSON 结果包含 prompt、lyrics（实际合成所用内容，可能经 LM 增强）、metas.prompt、metas.lyrics（原始输入）、metas.bpm、metas.keyscale、metas.duration、generation_info、seed_value、lm_model、dit_model 等字段。当启用 LM 增强（use_format=true）时，最终合成内容可能与输入不同，需解析 JSON 并读取顶层 lyrics 字段而非 metas.lyrics。
适用场景与限制
适用于需要借助 ACE-Step API 生成带人声歌曲、器乐、翻唱、局部重绘音频，以及制作带同步歌词的简单 MV 的场景。使用前提是 ACE-Step API 服务处于运行状态；若健康检查失败，需确认是否已安装 ACE-Step，未运行可借助 acestep-docs 技能启动，未安装则通过 acestep-docs 引导安装。云 API 使用时大音频文件可能被 Cloudflare 拒绝，必要时先用 ffmpeg 压缩（例如 ffmpeg -i input.mp3 -b:a 64k -ar 24000 -ac 1 compressed.mp3）。MV 制作需额外安装 acestep-songwriting、acestep-lyrics-transcription、acestep-simplemv 技能，可选用 acestep-thumbnail 生成背景图。其他具体收费、平台兼容性或性能指标暂未提供。