DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

Buir5 /

Buir5/dsh-tg-voice

Topic repository only

TG给D.H发语音。光速识别 超迅捷识别。秒回。你懂的。一般情况下只支持打字。Telegram voice -> local sherpa-onnx transcript for DeepSeek Harness (dsh-im patch, no cloud ASR)

★ 0 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@18b2d726

dsh-tg-voice

给 DeepSeek Harness 的 Telegram 渠道加上「语音转文字」:在 TG 里发一段语音,Agent 收到的是文字,而不是 [语音消息]。 全本地运行,不要 API Key,不联网推理,音频不出本机。

中文 | English

🧭 收有想法的兄弟 · 你也可以的。年入百万级。

如果你也想把技术变成能收钱的手艺,而不是收藏夹里吃灰的教程—— 我把我这些年接活、交付、踩坑的全套流程,写成了一份说明。 👉 收徒说明(知乎)

另外,我做了一个给独立开发者/小团队用的资源位:AI891 · 1888 终身,一次买断,不续费。 地址:https://ai891.com


它解决什么问题

DSH 的 IM 插件(@xmanrui/dsh-im)给飞书做了语音交互:ffmpeg 转码、DashScope 转写、TTS 回语音。但 Telegram 渠道没有这一层——message.voice 只会被归一化成一句 [语音消息],模型拿到的是三个字,不是你说的话。

这个仓库补的就是这一层:

场景 打补丁前 打补丁后
TG 发「给我重庆的天气」 Agent 收到 [语音消息],回「你想问什么?」 Agent 收到 给我重庆的天气,直接查天气
语音里的指令 识别不了 /new、/model 等命令 转写成文字后走正常命令流水线
群聊 @bot 语音 同上,只能当附件 转写后正常进上下文
隐私 若接云 ASR,音频要出网 全程本机,ffmpeg + sherpa-onnx
成本 云 ASR 按分钟计费 0 元,只吃 CPU

工作原理

Telegram 客户端
   │  按住说话,上传 ogg/opus
   ▼
Telegram Bot API  getUpdates
   │  message.voice.file_id
   ▼
dsh-im telegram-runtime.mjs
   │  ① downloadFile(file_id)  → Buffer(ogg)
   │  ② 写临时文件 %TEMP%\tgvoice_<ts>.ogg
   │  ③ powershell -File stt.ps1 -Path <ogg>
   ▼
stt.ps1
   │  ffmpeg -i in.ogg -ar 16000 -ac 1 -c:a pcm_s16le out.wav
   │  sherpa-onnx-offline --zipformer-ctc-model model.int8.onnx --tokens tokens.txt --num-threads 2 out.wav
   ▼
stdout 一行 JSON → 取 .text
   │
   ▼
message.content = "给我重庆的天气"
message.files = []
message.plainText = true
   │
   ▼
正常文字流水线:命令识别 → 会话 → 模型调用 → 回复

三个关键设计:

  1. 在 normalizeTelegramUpdate 之后立刻改 message.content,早于 captureGroupHistory 和 bridge.accept,所以群聊历史、上下文、命令解析拿到的都是文字。
  2. message.files = [] + message.plainText = true:原始语音不再作为附件往下传,避免桥接层重复下载、重复上传、把 ogg 塞进模型上下文。
  3. 失败只降级,不阻断:转写抛错时记一条 warn,content 保持 [语音消息],消息照常进入流水线。

为什么是 sherpa-onnx,而不是 Whisper / 云 API

方案 依赖 冷启动 中文短句准确率 隐私 成本
sherpa-onnx + Zipformer-CTC int8(本仓库) 一个 exe + 63 MB 模型 约 20 s(每次进程重载模型) 好,专有名词偶尔错 全本地 0
whisper.cpp large-v3-turbo 1.6 GB 模型 + GPU 更佳 1-3 s(服务常驻) 很好 全本地 0
云 ASR(DashScope / OpenAI) 网络 + Key 0.5-2 s 很好 音频出网 按分钟

选它的理由:零依赖、单文件、CPU 能跑、模型只有 63 MB,适合「一台常开的小主机 + 偶尔发语音」的场景。如果你一天几十条语音,建议换成常驻 whisper-server,见 docs/performance.md。

快速开始

0. 前置

  • Windows 10/11
  • 已安装 DeepSeek Harness,且装了 @xmanrui/dsh-im,Telegram 机器人能正常收发文字
  • Node.js 18+(DSH 自带运行时即可)
  • ffmpeg(winget install Gyan.FFmpeg,或放到 PATH)
  • PowerShell 5.1(系统自带)

1. 克隆

git clone https://github.com/Buir5/dsh-tg-voice.git
cd dsh-tg-voice

2. 装本地识别栈(约 90 MB 下载)

powershell -ExecutionPolicy Bypass -File .\stt\setup-stt.ps1

它会下载:

  • sherpa-onnx-v2.0.0-win-x64-shared-MT-Release-no-tts.tar.bz2(约 25 MB,解压后约 80 MB)
  • sherpa-onnx-zipformer-ctc-zh-int8-2025-07-03.tar.bz2(约 63 MB 模型)

默认落到 %USERPROFILE%\.dsh\im\_stt\:

_stt\
  sherpa\sherpa-onnx-v2.0.0-win-x64-shared-MT-Release-no-tts\
    bin\sherpa-onnx-offline.exe
    lib\...
  sb2\
    model.int8.onnx    62,666,860 B
    tokens.txt         13,366 B

3. 打补丁

powershell -ExecutionPolicy Bypass -File .\install.ps1

做的事:

  1. 定位 %USERPROFILE%\.dsh\profiles\desktop\node_modules\@xmanrui\dsh-im\src\channels\telegram\telegram-runtime.mjs
  2. 备份成 telegram-runtime.mjs.bak-tgvoice-<时间戳>
  3. 注入 4 行 import(缺哪行补哪行)
  4. 在 function telegramMediaFile(message) { 前插入两个 helper
  5. 在 await captureGroupHistory(this.#groupHistory, message, 前插入语音钩子
  6. node --check 校验;失败自动回滚
  7. 把 stt\stt.ps1 复制到 %USERPROFILE%\.dsh\im\stt.ps1

参数:

参数 默认值 说明
-DshImPath %USERPROFILE%\.dsh\profiles\desktop\node_modules\@xmanrui\dsh-im 插件目录
-SttDest %USERPROFILE%\.dsh\im\stt.ps1 转写脚本落点
-NodeExe PATH 里的 node 用于语法校验
-SkipStt 关 不复制 stt.ps1
-DryRun 关 只检查锚点,不写文件

4. 重启 DSH

补丁写在磁盘上的 .mjs 里,必须重启 DeepSeek Harness 才会重新加载模块。

5. 验收

在 Telegram 里给机器人发一条语音,然后看日志:

Get-Content "$env:USERPROFILE\.dsh\im\_tg_in.log" -Tail 6

正常输出:

2026-11-04T03:51:16.784Z voice=YES content="[语音消息]"
2026-11-04T03:51:18.202Z downloaded 10269 bytes +1418ms
2026-11-04T03:51:18.986Z converted +2202ms
2026-11-04T03:51:43.402Z voice stt ok 26618ms chars=7
2026-11-04T03:51:43.403Z done +26619ms

然后在 TG 里应该看到 Agent 按文字内容正常回答。

配置

环境变量 默认值 说明
DSH_TG_STT %USERPROFILE%\.dsh\im\stt.ps1 转写脚本路径;换模型/换语言时指向别的 ps1
DSH_TG_STT_TIMEOUT_MS 300000 单条语音超时;老机器/长语音可调大
DSH_TG_LOG %USERPROFILE%\.dsh\im\_tg_in.log 诊断日志;不想要日志就指向 NUL

改环境变量后要重启 DSH 才生效(Node 进程启动时读取)。

stt.ps1 自己的参数:

参数 默认值 说明
-Path 必填 输入音频,任意 ffmpeg 能解的格式
-Root %USERPROFILE%\.dsh\im\_stt 模型与 sherpa 的根目录
-Threads 2 sherpa 线程数;4 核以上建议 4
-Ffmpeg 自动找 显式指定 ffmpeg.exe

实测数据

原始记录(一条 10,269 B 的 ogg,约 4 秒中文):

阶段 耗时 说明
Bot API 下载 1,418 ms 10,269 B
ffmpeg 转 16 kHz 单声道 WAV 2,202 ms 包含进程启动
sherpa-onnx 识别 26,618 ms 每次调用都重新加载 63 MB 模型,这是大头
合计 26,619 ms 输出:给我重庆的天气(7 字,正确)

结论:这套方案的瓶颈不是识别,是「进程启动 + 模型加载」。日常可用,但要做到 2-3 秒,得用常驻服务(见下)。

想更快?

  1. 常驻 whisper-server:whisper.cpp 的 whisper-server.exe + ggml-large-v3-turbo.bin,加载一次常驻,HTTP POST /inference,热态 0.5-1.5 s(GPU 更快)。把 stt.ps1 换成 HTTP 调用即可,钩子不用改。
  2. 提高线程:-Threads 4(或 8),在 4 核以上机器通常能省 30-50%。
  3. 异步化:当前钩子在长轮询循环里同步等待,一条语音会阻塞后续 update 约 27 秒。语音多的话,把 __dshTranscribeVoice 改成「先回一句『正在听…』,转写完再 bridge.accept」的队列模型。

兼容性与升级

  • 补丁按文本锚点插入,不依赖行号;dsh-im 小版本升级通常仍能命中。
  • 锚点找不到时 install.ps1 会直接报错并不写文件,不会留下半个补丁。
  • node --check 失败会自动回滚到备份。
  • DSH / dsh-im 大版本升级后建议重跑一次 install.ps1:升级会覆盖 telegram-runtime.mjs,补丁随之消失(脚本检测到已打补丁会跳过,检测不到就重新打)。
  • 备份文件 telegram-runtime.mjs.bak-tgvoice-* 不会被自动清理;确认稳定后可以删旧的。

故障排查

现象 原因 处理
日志里没有 voice=YES 补丁没生效 / DSH 没重启 确认文件里有 dsh-tg-voice,重启 DSH
voice stt failed after ...ms stt.ps1 报错 手动跑 powershell -File stt.ps1 -Path test.ogg 看报错
sherpa-onnx-offline.exe not found 没跑 setup-stt.ps1 重新执行 setup,或 -Root 指对目录
ffmpeg.exe not found PATH 里没有 winget install Gyan.FFmpeg 或 -Ffmpeg 指定
识别结果是空字符串 音频太短/纯噪音 钩子会回落成 [语音消息];换一条语音再试
每次都要 20 多秒 模型每次冷加载 正常现象;按上面「想更快」改常驻服务
中文识别成拼音/英文 模型选错(用了英文模型) 用 setup-stt.ps1 默认的 zipformer-ctc-zh-int8
升级 DSH 后失效 文件被覆盖 重跑 install.ps1
node --check 失败 dsh-im 结构变了 看报错行,提 issue 附版本号

更多细节见 docs/troubleshooting.md。

隐私与安全

  • 音频不出本机:下载 → 临时文件 → ffmpeg → sherpa,全程无外网请求(除了 Telegram 本身的 Bot API)。
  • 临时文件在 finally 里删除,异常路径也删。
  • 日志只记字节数、耗时、字符数,不记语音内容。
  • 不需要任何 API Key;仓库里没有任何密钥。
  • 补丁只改一个 .mjs,不动 app.asar、不动系统输入法、不动浏览器。

已知限制

  • 同步阻塞:一条语音会占住长轮询循环约 20-30 秒;这期间新消息会排队。
  • 只处理 message.voice;video_note(圆视频)和 audio(音乐文件)仍按原逻辑当附件。
  • 语言覆盖取决于模型:默认模型覆盖中英日韩粤,方言/口音重时准确率下降。
  • 依赖 powershell.exe 启动子进程;纯 Linux/macOS 需要把 stt.ps1 换成 shell 版本。
  • 模型 63 MB 放在用户目录,不随仓库分发(避免仓库膨胀)。

卸载

powershell -ExecutionPolicy Bypass -File .\uninstall.ps1

会找最新的 telegram-runtime.mjs.bak-tgvoice-* 还原,并打印 marker 是否为 False。重启 DSH 生效。

模型目录 %USERPROFILE%\.dsh\im\_stt 可手动删(约 145 MB)。

目录结构

dsh-tg-voice\
  README.md                 本文件(中英双语)
  LICENSE                   MIT
  install.ps1               打补丁(备份 / 注入 / 语法校验 / 回滚)
  uninstall.ps1             从备份还原
  src\
    imports.txt             需要注入的 4 行 import
    helpers.mjs             注入的 helper 函数(原样)
    hook.mjs                注入的语音钩子(原样,10 空格缩进)
    voice-hook.mjs          上面两块的合体参考版(不参与安装)
  stt\
    setup-stt.ps1           下载 sherpa-onnx + 中文模型
    stt.ps1                 ffmpeg → sherpa 的转写脚本
  docs\
    architecture.md         逐行讲补丁与数据流
    performance.md          实测、调优、常驻服务改造
    troubleshooting.md      报错对照表
    evidence\tg_in.log.sample  真实运行日志

更新日志

v1.0.0(2026-11-05)

  • 首个公开版本:Telegram 语音 → 本地 sherpa-onnx 转写 → 文字进流水线
  • install.ps1 / uninstall.ps1,带备份、锚点校验、node --check、自动回滚
  • setup-stt.ps1 一键下载 sherpa-onnx v2.0.0 + Zipformer-CTC 中文 int8
  • 环境变量 DSH_TG_STT / DSH_TG_STT_TIMEOUT_MS / DSH_TG_LOG
  • 实测 4 秒语音 26.6 秒(冷启动),识别正确

作者

作者 知乎老哥

dsh-tg-voice (English)

dsh-tg-voice adds voice-to-text to the Telegram channel of DeepSeek Harness. Send a voice note in Telegram and the agent receives text instead of the literal [voice message] placeholder. Everything runs locally: ffmpeg + sherpa-onnx, no API key, no cloud ASR, audio never leaves the machine.

Why this exists

@xmanrui/dsh-im ships voice interaction for Feishu (ffmpeg + DashScope ASR + TTS). The Telegram channel does not have that layer: message.voice is normalized to [voice message], so the model sees three words instead of what you said.

This repository adds that layer as a small, reversible patch.

How it works

Telegram voice (ogg/opus)
  -> dsh-im poll loop: downloadFile(file_id)
  -> temp .ogg
  -> stt.ps1: ffmpeg -ar 16000 -ac 1 -c:a pcm_s16le -> .wav
  -> sherpa-onnx-offline --zipformer-ctc-model model.int8.onnx --tokens tokens.txt
  -> stdout JSON -> .text
  -> message.content = text; message.files = []; message.plainText = true
  -> normal text pipeline (commands, sessions, model, reply)

Three design points:

  1. The hook rewrites message.content before captureGroupHistory and bridge.accept, so group history, context and command parsing all see plain text.
  2. message.files = [] and message.plainText = true stop the original ogg from being re-downloaded or attached again downstream.
  3. Failures degrade, never block: the hook logs a warning and the message continues as [voice message].

Install

Requirements: Windows 10/11, a working DeepSeek Harness install with @xmanrui/dsh-im and a Telegram bot that already answers text, Node.js 18+, ffmpeg on PATH, PowerShell 5.1.

git clone https://github.com/Buir5/dsh-tg-voice.git
cd dsh-tg-voice

# 1) local ASR stack (~90 MB download, ~145 MB on disk)
powershell -ExecutionPolicy Bypass -File .\stt\setup-stt.ps1

# 2) patch dsh-im (backup + inject + node --check + auto rollback)
powershell -ExecutionPolicy Bypass -File .\install.ps1

# 3) restart DeepSeek Harness, then send a Telegram voice note

install.ps1 options:

Option Default Meaning
-DshImPath %USERPROFILE%\.dsh\profiles\desktop\node_modules\@xmanrui\dsh-im plugin folder
-SttDest %USERPROFILE%\.dsh\im\stt.ps1 where stt.ps1 is copied
-NodeExe node from PATH used for the syntax check
-SkipStt off do not copy stt.ps1
-DryRun off verify anchors, write nothing

Configuration

Variable Default Meaning
DSH_TG_STT %USERPROFILE%\.dsh\im\stt.ps1 transcription script
DSH_TG_STT_TIMEOUT_MS 300000 per-voice timeout
DSH_TG_LOG %USERPROFILE%\.dsh\im\_tg_in.log diagnostics log

stt.ps1 accepts -Path, -Root, -Threads (default 2) and -Ffmpeg.

Measured

One 10,269-byte ogg, about 4 seconds of Chinese:

Stage Time
Bot API download 1,418 ms
ffmpeg to 16 kHz mono WAV 2,202 ms
sherpa-onnx decode 26,618 ms
total 26,619 ms -> 给我重庆的天气 (correct)

The cost is process start plus reloading the 63 MB model on every call, not the decode itself. For 2-3 second latency, run a resident whisper-server and make stt.ps1 an HTTP client; the hook does not need to change. See docs/performance.md.

Limitations

  • The hook is synchronous inside the long-poll loop: one voice note blocks later updates for roughly 20-30 seconds.
  • Only message.voice is handled; video_note and audio keep the original attachment behavior.
  • Language coverage follows the model (zh/en/ja/ko/yue by default).
  • Windows-oriented because it spawns powershell.exe; port stt.ps1 to a shell script for Linux/macOS.
  • The 63 MB model is downloaded to the user profile, not stored in the repository.

Uninstall

powershell -ExecutionPolicy Bypass -File .\uninstall.ps1

It restores the newest telegram-runtime.mjs.bak-tgvoice-* backup. Restart DeepSeek Harness afterwards. You can delete %USERPROFILE%\.dsh\im\_stt manually (~145 MB).

License

MIT. See LICENSE.

Author

Author: 知乎老哥


🧭 收有想法的兄弟 · 你也可以的。年入百万级。

如果你也想把技术变成能收钱的手艺,而不是收藏夹里吃灰的教程—— 我把我这些年接活、交付、踩坑的全套流程,写成了一份说明。 👉 收徒说明(知乎)

另外,我做了一个给独立开发者/小团队用的资源位:AI891 · 1888 终身,一次买断,不续费。 地址:https://ai891.com

—/ 5

No ratings yet

Manifest verification required

Commit 18b2d7260077

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout