核心用法
Play Music Skill 是一个专为本地音乐播放设计的控制型技能，采用单一入口点架构。用户通过 ./play-music 命令即可完成全部操作，包括播放默认曲目、指定文件播放、暂停/恢复/停止控制、状态查询及服务器管理。技能内置客户端-服务器分离架构，后台 music-server.py 负责实际音频解码与播放控制，前台脚本作为统一交互界面。
使用流程极为简洁：将音乐文件放入 ./music 目录（或通过 MUSIC_DIR 环境变量自定义），安装 pygame 依赖后即可通过命令行操控。服务器采用懒加载设计，播放时自动启动、停止后自动关闭，兼顾响应速度与系统资源占用。
显著优点
架构清晰：单一入口点消除脚本选择困惑，命令白名单机制确保输入安全。客户端-服务器分离使核心播放逻辑与交互层解耦，便于维护与扩展。
控制完备：相比简易播放工具，完整支持 pause/resume/stop 三态控制，满足语音助手场景下的精细化操控需求。pygame 混音器提供跨平台高质量音频输出。
资源友好：服务器非常驻内存，按需启停的设计对边缘设备与长时运行的 AI 助手系统尤为友好。锁文件机制避免多实例冲突。
零网络依赖：纯本地运行，无外部 API 调用、无云端服务依赖，隐私敏感场景下具备天然优势。
潜在缺点与局限性
格式支持受限：依赖 pygame 的音频解码能力，主要覆盖 MP3、OGG、WAV 等常见格式，对 FLAC、AAC、无损压缩格式或流媒体协议（HTTP Live Streaming）缺乏原生支持。
无播放列表管理：当前版本仅支持单首曲目播放，无队列、随机播放、循环模式等高级功能，复杂场景需用户自行编排调用逻辑。
端口硬编码：控制端口固定为 12346，多用户或多实例部署时可能产生冲突，虽提供手动清理命令但缺乏动态端口分配机制。
元数据缺失：无 ID3 标签读取、专辑封面展示、歌词同步等增强功能，纯工具属性定位。
适合的目标群体
- AI 助手开发者：需为 OpenClaw 等框架集成音乐控制能力的场景
- 本地隐私优先用户：拒绝云端音乐服务、追求数据完全本地化的用户
- 自动化脚本编写者：需要将音乐播放纳入工作流或定时任务的效率用户
- 教育/演示场景：需要可控、可中断音频播放的教学或展示环境
使用风险
依赖项风险：pygame 虽为主流库，但跨平台音频驱动兼容性存在差异，Linux 环境可能需额外配置 ALSA/PulseAudio。
并发冲突：固定端口与锁文件机制在容器化或快速重启场景下可能出现状态残留，需手动执行 server-stop 或 pkill 清理。
路径遍历：虽使用 pathlib 进行路径拼接，但若 MUSIC_DIR 被恶意设置为系统敏感目录（如 /etc），配合社会工程学仍可能引发信息泄露，建议配合沙箱使用。