前言¶
在开发基于 DeepSeek Harness 的智能体时，处理音乐理论领域常会遇到非确定性的错误：例如音名拼写错误（将 G# 大三和弦误写为 G# C D#）、频率计算偏差、升降号处理混乱等。dsh-musictheory 是一个针对 DeepSeek Harness 的确定性音乐理论工具包，它采用零运行时依赖的纯 12-TET（十二平均律）算术，旨在为模型推理提供精确、可靠的数学计算支持。
核心能力¶
该插件提供以下核心功能：
- 音名解析与频率/MIDI 转换：支持解析
C#4、Bb3等音名，输出 MIDI 编号、八度、音级以及精确的 12-TET 频率，并列举所有常规同音异名拼写。 - 和弦构建：支持 26 种和弦质量（如
maj、min、dim、sus2、sus4、7、maj7、m7b5、dim7、aug7、7sus4、add9、madd9、maj9、9、m9、11、m11、13、maj13、6/9等）的正确拼写。 - 音阶生成：支持 17 种音阶类型（如
major、natural_minor、harmonic_minor、melodic_minor、dorian、phrygian、lydian、mixolydian、locrian、major_pentatonic、minor_pentatonic、blues、whole_tone、chromatic等）的正确拼写。 - 音程构建与识别：支持 34 个标准音程名称的构建与识别，并处理同音异名问题。
- 音阶和声化：对 7 音音阶进行和声化处理，输出调内三和弦与七和弦（带罗马数字标记）。
- 拼写感知移调：支持对 1-16 个音符进行任意音程的移调，且拼写严格遵循字母与升降号规则。
- 和弦识别：支持识别 2-8 个音符构成的和弦，包含转位识别（如
Cmaj/E），并能处理同音异名情况（如C6与Am7/C同时存在）。
安装¶
安装此插件需要使用 DeepSeek Harness 的插件命令。
dsh plugin --profile <profile-name> add github:TYEclipse/dsh-musictheory
典型用法¶
以下是该插件的主要命令示例：
音名与频率信息
note_info note="C#4"
输出：MIDI 61, octave 4, pitch class 1, 277.18 Hz, also: Db4
频率转音名
freq_to_note frequencyHz=442
输出：A4 (MIDI 69), +7.85 cents
构建和弦
chord_build root="G#" quality="maj"
输出：G#maj: G#4 B#4 D#5
生成音阶
scale_generate root="C" type="blues"
输出：C4 Eb4 F4 Gb4 G4 Bb4
移调
transpose notes=["Bb3","G3","D4"] interval="M2"
输出：C4 A3 E4
和弦识别
chord_identify notes=["C4","E4","G4","A4"]
输出：C6, then “other readings: Am7/C”
特性与设计¶
- 零运行时依赖：纯数学计算，无网络请求、Shell 调用或文件系统访问。
- 确定性计算：相同输入总是产生相同输出，不依赖大模型的随机性。
- 可配置标准音高：支持通过
config.a4Hz调整标准音高频率（例如巴洛克 415Hz、威尔第 432Hz、现代 442Hz）。 - 输入验证：对非法的音名、频率或未知和弦质量返回结构化错误。
- 许可证：MIT 许可证。
生态背景¶
DeepSeek Harness 的核心理念是「一切皆插件」。dsh-musictheory 是社区贡献的插件之一，旨在通过标准化工具增强 DSH 的能力边界。该插件由维护者 TYEclipse 开发，可在社区目录中查询更多信息。
总结¶
dsh-musictheory 解决了音乐理论计算中常见的拼写错误和不确定性问题。对于需要处理音高、和弦、音阶和频率转换的智能体应用，它提供了基于纯数学的确定性解决方案。该插件当前版本为 0.3.0，安装简便且无外部依赖。
