前言¶
在 DeepSeek Harness（DSH）裏做智能體時，模型上下文通常是文本。用戶發來語音、錄音或附件裏的音頻時，若直接把二進制丟進對話，多數純文本模型既無法「聽」，也難以做可覈查的判斷。常見變通是單獨開 ASR 流水線、或把整段音頻交給多模態 API，再讓 Agent 基於二手摘要推理——證據形態不統一，也很難和本地文件、會話工作目錄對齊。
@vlln/dsh-listen（維護者 vlln，社區分類：模型推理）是 DSH 生態裏的一款插件：通過一個 listen 工具傳入音頻路徑或附件 ID，按需返回轉寫、聲譜圖、電平、頻譜、音高、節奏等結構化證據，由主 Agent 自行組合解讀。它不替模型回答語義問題，也不生成或編輯音頻；定位是「聽」的原子化工具層。插件目錄見 SkillHub，源碼與文檔見 GitHub。DSH 社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
這是什麼¶
一句話：給文本 Agent 裝上耳朵——傳入音頻，返回可選特徵集合與統一 JSON 證據結構。
設計思路是把「聽」拆成可獨立請求的原子操作（轉寫、事件標籤、波形/譜圖、各類 DSP 標量），默認收斂爲單一工具 listen；配置 mode: split 時可拆成四個工具（audio_signal / audio_transcript / audio_events / audio_dsp），便於 Agent 按任務組合調用。
當前包版本爲 0.1.5，許可證 MIT（可選運行時、權重、數據各有其許可）。
核心功能¶
listen 工具與特徵列表¶
調用形態示例：
listen({path:"x.wav", features:["levels","signal_image"], from:0, to:10})
| 參數 | 說明 |
|---|---|
path / attachment_id |
來源，二選一；路徑按會話工作目錄解析 |
features |
必填，無默認值 |
from / to |
源文件秒數，默認 0 / EOF；單次區間 ≤60 秒 |
features 可選值包括：transcript、events、signal_image、levels、energy、spectral_peaks、band_energy、chroma、pitch、pitch_frames、onsets、tempo。附加參數如 spectral_detail（影響 signal_image 的 FFT 長度）、frequency_range_hz、channel_view、dsp_band_hz（band_energy 必填）等，語義見倉庫內設計文檔。
返回給模型的主體爲 JSON：status（complete / partial / failed）、source（格式、採樣率、時長、sha256 等）、coverage、requested_features / available_features / missing_features，以及 evidence 下各特徵塊（含 method、單位、參數；失敗時帶 reason 與錯誤碼）。signal_image 的圖作爲圖片附件隨結果返回，文本 payload 不含圖。
各特徵背後的處理（摘要）¶
- transcript：可選本地 MLX Whisper 或 OpenAI 兼容 ASR API（需配置）。
- events：可選本地 LiteRT / YAMNet 聲音分類（需開啓）。
- signal_image：STFT + mel，輸出功率譜圖 PNG。
- levels：逐聲道 RMS、峯值、DC、過載計數等。
- energy / spectral_peaks / band_energy / chroma / pitch / onsets / tempo：在統一 DSP 管線上分路計算，細節見 README 中的流程圖與
docs/guides/dsp-evidence.md。
基準成績（MMAU）¶
作者在 MMAU-test-mini 1000 題上報告 74.60% 平均正確率（MMAU-v05.15.25 修訂版、文本模型加工具）。分域約爲 sound 72.97、speech 82.58、music 68.26。圖中其他模型行爲引用 MMAU 論文 Test-mini 列的早期端到端音頻模型結果，與當前工具鏈設置不同，對比時需注意設定差異。
安裝與啓用¶
前置：Node 22+、dsh ^0.2.1-rc.5（README 實測 0.2.1-rc.5）、本機安裝 ffmpeg / ffprobe。
官方安裝命令：
dsh plugin --profile web add @vlln/dsh-listen
裝完後重啓 dsh web；在 Plugins 頁填寫同一包名 @vlln/dsh-listen。包聲明瞭 dsh.bundle.patch，add 會自動寫入 profile 的 bundle 列表，無需手寫 insert；若曾手工 insert 舊配置，需先刪除以免衝突。
卸載：
dsh plugin --profile web remove dsh-listen
查看生效配置：
dsh --profile web --dump-config | grep -A6 dsh-listen
兼容性：README 寫明在 dsh 0.2.1-rc.5 + Node 22 + macOS arm64（2026-11-06）實測；engines.dsh: ^0.2.1-rc.5。DSH Desktop、Linux、Windows 及 dsh 0.2.0 及更早版本未測。
配置要點¶
| 設置 | 默認 | 說明 |
|---|---|---|
scratch |
$DSH_HOME/data/dsh-listen/scratch |
解碼與中間文件目錄，調用結束清理 |
mode |
aggregate |
aggregate 僅 listen；split 啓用四個拆分工具 |
localExecution |
true |
沙箱或遠程文件系統無法讀本機路徑時設爲 false |
asrEnabled / asrMode |
false / api |
轉寫：本地 MLX 或 API |
eventsEnabled |
false |
聲音事件標籤 |
allowExternalAudio |
false |
爲 true 且使用 ASR API 時可能外發音頻 |
典型用法¶
1、在會話工作目錄放置或可解析的 x.wav（格式以本機 ffmpeg 支持爲準）。
2、讓 Agent 調用 listen，在 features 中顯式列出所需證據，例如只要電平與譜圖：
listen({path:"x.wav", features:["levels","signal_image"], from:0, to:10})
3、根據返回的 status 與 evidence：標量直接進入推理；signal_image 從附件讀取 PNG 供多模態或人工查看。需要轉寫或環境聲標籤時，先在配置中開啓 asrEnabled / eventsEnabled 並補齊憑據（由宿主憑據服務或環境變量提供，插件不讀取憑據本體）。
4、長文件分段：單次 from/to 區間不超過 60 秒；多聲道高採樣率時有效時長可能更短（總標量樣本上限 23,040,000）。
適用場景與注意¶
適合誰：在 DSH Web / 本地 Harness 裏做需要「聽文件再給結論」的 Agent——質檢聽測、會議片段摘要前的證據抽取、音樂/環境聲的頻域與節奏特徵分析等。希望證據可復現、可進上下文、且與本地路徑/附件 ID 一致時，比純外部 ASR 的一站式黑盒更易編排。
限制：不回答語義問題；不支持音頻生成、播放或編輯；單次最多約 60 秒片段；支持 1–8 聲道，ASR 與 events 分支會混成單聲道。
安全與數據：默認在本機解碼，除配置 ASR API 且 allowExternalAudio 爲真外不外發音頻。證據會進入主 Agent 上下文；主 Agent 使用雲模型時，證據也會發往模型服務。安裝與啓用前，插件以當前 dsh 進程權限運行，應自行審閱 源碼與 MIT 許可，確認 scratch、外發與憑據策略符合環境要求。
結尾¶
dsh-listen 把「聽懂聲音」收斂成 DSH 內可選特徵、統一證據格式的工具調用，方便文本 Agent 在本地音頻與可選 ASR/事件模型之間做組合。若你在搭 DSH 智能體並處理音頻輸入，可從目錄頁瞭解簡介與分類，並按 README 安裝命令接入。
