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
│
▼
正常文字流水线:命令识别 → 会话 → 模型调用 → 回复
三个关键设计:
- 在
normalizeTelegramUpdate之后立刻改message.content,早于captureGroupHistory和bridge.accept,所以群聊历史、上下文、命令解析拿到的都是文字。 message.files = []+message.plainText = true:原始语音不再作为附件往下传,避免桥接层重复下载、重复上传、把 ogg 塞进模型上下文。- 失败只降级,不阻断:转写抛错时记一条 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
做的事:
- 定位
%USERPROFILE%\.dsh\profiles\desktop\node_modules\@xmanrui\dsh-im\src\channels\telegram\telegram-runtime.mjs - 备份成
telegram-runtime.mjs.bak-tgvoice-<时间戳> - 注入 4 行 import(缺哪行补哪行)
- 在
function telegramMediaFile(message) {前插入两个 helper - 在
await captureGroupHistory(this.#groupHistory, message,前插入语音钩子 node --check校验;失败自动回滚- 把
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 秒,得用常驻服务(见下)。
想更快?
- 常驻 whisper-server:
whisper.cpp的whisper-server.exe+ggml-large-v3-turbo.bin,加载一次常驻,HTTPPOST /inference,热态 0.5-1.5 s(GPU 更快)。把stt.ps1换成 HTTP 调用即可,钩子不用改。 - 提高线程:
-Threads 4(或 8),在 4 核以上机器通常能省 30-50%。 - 异步化:当前钩子在长轮询循环里同步等待,一条语音会阻塞后续 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:
- The hook rewrites
message.contentbeforecaptureGroupHistoryandbridge.accept, so group history, context and command parsing all see plain text. message.files = []andmessage.plainText = truestop the original ogg from being re-downloaded or attached again downstream.- 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.voiceis handled;video_noteandaudiokeep the original attachment behavior. - Language coverage follows the model (zh/en/ja/ko/yue by default).
- Windows-oriented because it spawns
powershell.exe; portstt.ps1to 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
🧭 收有想法的兄弟 · 你也可以的。年入百万级。
如果你也想把技术变成能收钱的手艺,而不是收藏夹里吃灰的教程—— 我把我这些年接活、交付、踩坑的全套流程,写成了一份说明。 👉 收徒说明(知乎)
另外,我做了一个给独立开发者/小团队用的资源位:AI891 · 1888 终身,一次买断,不续费。 地址:https://ai891.com
No comments yet. Be the first to write one.