核心定位
galdr 是一款面向 AI 代理的音乐感知 CLI 工具，其独特价值在于将音频转换为时间有序的听众状态轨迹（attention、pattern、pulse、pressure、texture、harmony、melody、overtones、silence/re-entry），而非传统的频谱或情感标签。
核心用法
主要工作流
1. YouTube 分析: galdr fetch <url> --analyze 自动提取音频+元数据，生成结构化 slug
2. 本地文件分析: galdr listen <file> --name <slug> 直接处理本地音频
3. Prompt 组装: galdr assemble <slug> --template arc --mode full 生成可输入其他 AI 的完整提示
关键模式选择
| 模式 | 用途 |
|------|------|
| `full` | 指标+歌词+背景+视频帧（默认） |
| `lyrics` | 指标+歌词 |
| `context` | 指标+背景信息 |
| `blind` | 纯结构指标（无文化语境） |
核心数据输出
*_stream.json: 逐秒感知状态流（首要证据）*_perception.json: 综合感知摘要PERCEPTION-MODEL.md: 感知模型文档- 可选: harmony/melody/overtone 专项流、视频帧提取
显著优点
1. 时间粒度精细: 秒级轨迹而非整曲标签，捕捉 pattern break、silence/re-entry 等微观结构
2. 感知模型独特: 将声学特征转化为听众身体状态（pressure、breathe、attention），桥接技术分析与主观体验
3. AI 原生设计: 输出专为 AI 消费优化，支持直接组装为 Claude/LLM 提示
4. 元数据自动化: YouTube 下载、歌词获取、Wikipedia 背景、视频帧提取一站式完成
5. 可验证性: galdr doctor 诊断工具链健康，update-deps 维护 yt-dlp 等依赖
潜在局限与风险
1. 依赖外部工具链: 需 yt-dlp、ffmpeg、JavaScript 运行时，YouTube 下载可能因平台变更失效
2. 无原创音频分析: 依赖 yt-dlp 提取音频，本地处理仍需外部编码器
3. 歌词准确性: 自动抓取的歌词可能有误，需 --censor 等后处理
4. 感知模型的主观性: "pressure""breath"等指标虽结构化，但仍为特定理论框架，非普适音乐认知
5. 黑箱风险: 核心分析逻辑（stream.json 生成）未开源说明具体算法
适合人群
- AI 音乐分析开发者: 需要结构化音乐数据训练或提示工程
- 音乐评论家/写作者: 生成基于微观时间结构的聆听体验文本
- 比较音乐学者:
galdr compare支持跨曲目结构对比 - AI agent 构建者: 通过 Python subprocess 模式集成到自动化工作流
常规风险
- 版权合规: YouTube 下载需遵守平台 ToS 和当地版权法
- 数据隐私: 上传至外部模型的提示可能包含歌词等受版权保护内容
- 过度解读风险: 文档明确警告"不要从结构过度声称情感确定性"
- 依赖失效: yt-dlp 与 YouTube 的持续对抗可能导致功能突然中断
使用建议
优先采用 blind 模式进行纯结构分析，避免文化语境污染；关键分析前运行 galdr doctor 验证工具链；生成提示后人工审核再发送至外部模型端点。