前言¶

在 DSH 里做智能体时，常见做法是让用户描述一首歌，或把歌词贴进对话。文本模型本身听不到文件：没有 BPM、能量走势、调性或母带动态，回答很容易变成泛泛的乐评话术。把整段音频丢给云端多模态 API 可以补这一块，但涉及费用、网络，以及「音频是否出本机」的顾虑。

下面介绍维护者 ALittleLov 的实验插件 dsh-soundcheck（GitHub：ALittleLov/dsh-soundcheck，社区目录标识 alittlelov/dsh-soundcheck）。它在用户机器上跑 Python 分析引擎，把本地音频拆成结构、速度、调性、动态、声源等可核对的数据，默认输出一段人可读的「判断」，再交给 DSH 里的文本模型续写问答。设计目标在仓库 README 里写得很直白：让文本大模型能回答关于音乐的问题，不是 DAW 参数推荐器，也不是播放器；分析过程声明为不联网，音频不出本机。

这是什么¶

• 名称：dsh-soundcheck（manifest 中 id 为 dsh-soundcheck.local）
• 维护者：ALittleLov
• 分类：社区目录归入「模型推理」一类——本质是本地特征提取 + 工具调用，把信号变成模型可消费的文本或 JSON
• 当前版本：0.6.8（package.json / dsh-plugin.json 一致；SkillHub 目录页标注可安装且为今日更新）
• 许可证：MIT
• 平台：package.json 中 os 仅声明 win32；引擎脚本路径默认使用 venv\Scripts\python.exe，与 Windows 开发环境一致

插件在 DSH 侧注册 四个工具 与 两个斜杠命令（以当前 lib/index.js 为准；早期开发说明里仍写「三个工具」，以代码为准）。

安装策略：分析时不会偷偷装依赖。引擎缺失时工具返回 ENGINE_NOT_INSTALLED，需要用户执行 /audio-install，或明确让助手调用 audio_provision。v0.6.8 Release 说明默认安装体量约 570 MB（含 Beat This 节拍模型等）；开发 README 中曾写约 470 MB，以当前发版说明为准。

核心功能与输出形态¶

引擎主脚本为包内 engine/analyze.py（分发 zip 中含插件代码 + 引擎 + YAMNet 等，Python 依赖由安装步骤单独下载）。README 中给出的能力表与项目定位可以概括为：

默认可靠或可用

• 结构 / 能量走势（16 秒块 RMS）
• BPM（含倍频校验；检测器锁在倍频时仍可能出错）
• 调性（Krumhansl 模板 + 候选与歧义处理）
• 响度 / 削波
• 片段分析（audio_section）
• 声源标签（YAMNet，部分可用；情绪/风格类标签已剔除）
• 适用性自评 [FIT]（在 --detail 与 JSON 中，用于判断哪些结论可信）

默认文本输出（先结论、后数字）：

[SCOPE] 仅片段分析时出现
[判断]  时长、速度层级、调性、母带、结构重心等
[依据]  峰值、RMS、起音、调性、拍速等数字
[可信]  beat / 调性 / 根音 适用性分数 (0–1)
[听不到] 测不到的内容会明确写出

需要完整测量明细时，使用工具参数 detail: true 或命令行 --detail，会得到 [FIT]、[META]、[BPM]、[KEY]、[DYN]、[FORM]、[CHORD]、[SEG]、[SRC] 等块。

刻意不做的事：README 明确不写死流派判断（流派靠听，不靠测）；也给不出 Gemini 式「马头琴、蒙古语」的自然语言画面——项目结论是把能测的合成判断，测不到的写进 [听不到]。

性能参考（开发 README，2026-10-19）：约 4 分钟 MP3 整首分析约 11 秒（优化前约 66 秒）。

可选能力（引擎 CLI，不一定每次经插件暴露）：--stems / --stems 6s 分轨与人声占比；--asr 歌词听写候选（v0.6.8 对零可信段有降级稿策略）。这些组件体积与耗时 README 中有单独说明。

安装与启用¶

DSH 生态是「一切皆插件」；SkillHub 目录 是社区收录站点，与 DeepSeek / 幻方无官方从属关系。该页显示插件可安装，版本 v0.6.8。具体「从目录一键装进当前 profile」的操作以 DSH 客户端与目录页指引为准；仓库开发说明提到维护者本机曾通过 dsh plugin add 装入 desktop profile，但未在已公开 README 中给出完整安装命令行，本文不拼接 dsh plugin add github:... 一类未原文记载的命令。

若走发布包，可从 GitHub Release 下载：

https://github.com/ALittleLov/dsh-soundcheck/releases/download/v0.6.8/dsh-soundcheck-0.6.8.zip

解压后按 DSH 插件加载方式指向包内入口（lib/index.js，见 dsh-plugin.json）。

第二步：装分析引擎（与装插件分开）。在 DSH 对话中执行：

/audio-install

或用工具 audio_provision 代装。装完后用 /audio-status 确认 Python、脚本、模型与 .provisioned 标记。权限声明见 manifest：子进程 dsh-soundcheck.process.spawn、读文件 dsh-soundcheck.fs.read，理由为本地 Python 特征提取且不联网。

安装前建议自行阅读 GitHub 源码 与 MIT 许可证；插件以当前 DSH 进程权限运行，能读取你指定的音频路径并拉起本机 Python。

典型用法¶

在 DSH 里¶

1. 确认 /audio-status 正常；若报 ENGINE_NOT_INSTALLED，先 /audio-install 或 audio_provision。
2. 让助手对本地文件调用 audio_analyze（需要 JSON 或短上下文时传 brief；要仪表盘级明细传 detail: true）。
3. 问「某时刻发生了什么」时，用 audio_section，start / end 支持秒数或 m:ss，且为全曲绝对时间。

插件侧要求设置 PYTHONUTF8=1；中文路径需用引号或硬编码路径，避免经 shell 变量传递导致编码损坏（开发 README 注意事项）。

直接调试引擎（开发 README 用法）¶

在已 provision 的引擎目录下，Windows 示例如下（路径按本机修改）：

export PYTHONUTF8=1

./venv/Scripts/python.exe analyze.py "D:\music\track.flac"

./venv/Scripts/python.exe analyze.py "D:\music\track.flac" --json

./venv/Scripts/python.exe analyze.py "D:\music\track.flac" --brief

./venv/Scripts/python.exe analyze.py "D:\music\track.flac" --start 1:30 --end 2:10

./venv/Scripts/python.exe analyze.py "D:\music\track.flac" --detail

结构化结果可对照仓库中的 out.json / out.brief.json 样例（brief 约 530 B 量级）。

适用场景与注意¶

适合谁

• 已在用 DSH 编排工具调用，希望模型基于本地、可引用的测量讨论曲式、动态、速度、调性，而不是空口描述。
• 能接受 Windows 环境与一次性约 570 MB 引擎安装，且愿意先读 [可信] / [FIT] 再采信结论。

需要知道的边界

• 说不出「音乐内容」层面的乐器、语言、氛围时，输出会写在 [听不到]，这不是临时 bug，而是 README 中的产品结论。
• 和弦仅到根音级；流派不做断定。
• 旧账号 dalekotsvet 仓库已迁移，README 提醒旧下载链接失效，请以 ALittleLov/dsh-soundcheck 为准。
• GitHub 星标数为 0（截至撰稿所用目录线索），不代表质量，只说明曝光仍小；属实验项目，发版节奏在 README 中有「先本地验证、再征得同意后 push」的维护约定。

结尾¶

dsh-soundcheck 把「本地音频 → 结构化证据 → 文本模型」串成一条可复现链路：默认给人读的判断，必要时再展开 JSON 与明细，并标明测不到的部分。若你在 DSH 里做音乐相关的问答或批注工作流，可以从社区目录页或 GitHub Release 装上插件，跑通 /audio-install 后用 audio_analyze / audio_section 试一首本地文件。

• 目录页：https://www.skillhub.cn/plugins/ALittleLov/dsh-soundcheck
• 仓库：https://github.com/ALittleLov/dsh-soundcheck