前言¶
在開發基於 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，安裝簡便且無外部依賴。
