前言¶

在 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})

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 及更早版本未测。

配置要点¶

典型用法¶

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 安装命令接入。

• 目录：https://www.skillhub.cn/plugins/vlln/dsh-listen
• 仓库：https://github.com/vlln/dsh-listen