让一台吃灰的旧设备,变成「动动嘴就能干活」的智能体盒子
Turn an idle machine into a voice-only agent box. No screen. No keyboard. Just power, network, a microphone — and your voice.
简体中文 · English · 语言切换 / Switch
说人话就是:给它通上电、连上网、开个麦克风,之后显示器、鼠标、键盘全都不用接。你站旁边说句话,它就把活干了,干完还把结果念给你听。
⭐ 先别急着往下翻,麻烦先去给上游点个 Star: qishuilalala/dsh-voice-mode。没有那个项目,这个仓库连一行字都写不出来。文末有我们认认真真写的致谢,是真的感谢,不是客套。
一句话讲明白
一台吃灰的旧 Mac 或小主机,接上网、开个麦克风,就变成不用看屏幕的智能体。
说一句「肥鱼,看看昨晚的日志有没有报错」,它自己去查,再用语音把结论念回来:「下午三点有一条超时,别的都正常。」想核对细节,在手机或另一台电脑上打开 Web 页面翻会话记录;让它去局域网另一台机器取个文件、发个汇报,也是一句话的事。
不说话时它安安静静,一开口就开始干活。 没有显示器,没有鼠标键盘,也不用每次开机点一遍登录和授权 —— 这个仓库装的就是这套能力。
先说个特别容易误会的事
这不是一个「用的时候打开一下」的小工具,也不是每次都要重新调用一遍的技能。
它是装一次、就长期住在这台机器里的能力。 装好之后,开机自己起来,崩了被人拉起来,重启也不用你重新登录、重新点授权。你要做的只有「说话」,别的都是它在后台自己转。
所以这份仓库里放的是一份「怎么把它装上去、装完怎么管」的完整说明,外加一个给 WorkBuddy 用的 SKILL 包。它不是让你每次聊天都拿出来用一下的快捷指令,而是给一台设备「装上一张嘴和一副耳朵」的施工手册。
装好之后,你手上只需要什么
| 需要 | 不需要 |
|---|---|
| 电 | 显示器 |
| 网 | 鼠标、键盘 |
| 一个能用的麦克风 | 浏览器界面 |
| 一张嘴 | 每次开机手动登录、手动点授权 |
麦克风授权这事儿只用在第一次装的时候人工点一次「允许」,之后再也不用管。系统会自动登录,两个后台小服务自己起来,全链路就活了。
它能帮你做什么
随便举几个,别被限制住:
- 问点什么、查点什么,让它自己调工具跑完,只把结论念出来;
- 让它盯着某台机器的状态,有异常主动汇报;
- 让它在局域网里跑去别的设备上取文件、传文件、拿结果回来;
- 让它整理资料、算数、写点东西,然后读给你听;
- 你在另一台电脑上通过远程 / Web UI 翻它的会话记录,检查它到底干得对不对;
- 夜里想起个事,走过去说一句就行,不用开灯找键盘。
关键不是「能语音聊天」——能聊天的东西多了去了。关键是这台机器不需要屏幕,你也不需要坐在它面前,它还能真的动手干活、真的把结果交出来。
跟手机上的语音助手有啥不一样
| 常见语音助手 | 这台盒子 | |
|---|---|---|
| 得有块屏幕吗 | 基本得有 | 完全不用 |
| 回答怎么给你 | 显示 / 念一句 | 逐句念出来,长答案也念 |
| 它说话时你能插嘴吗 | 多数得等 | 喊唤醒词立刻停播;回声、咳嗽不会截断 |
| 会真的去操作别的机器吗 | 看生态 | 会,工具、命令、网络都在它的工作区里 |
| 干完的痕迹在哪 | 多数看完就没了 | 会话存着,Web UI 随时翻 |
| 识别要不要额外 API Key | 常常要 | 本地识别,不用为「听」再花钱 |
还有个细节挺重要:它有个固定的语音工作区,回答会被强制压成口语短句——不念 markdown、不念表格、不念代码块,也不把命令原样读给你听。因为用户根本看不见屏幕,念那些东西纯属折磨人。
大概是怎么跑起来的
别被名词吓到,其实就是一条流水线,一环接一环:
你说话
│
▼
一个很小很小的采集 App(就负责听)
│ 把声音压成 16kHz 的单声道数字流
▼
一根管道 FIFO(可以理解成「传声筒」)
│
▼
桥接程序 bridge.mjs(真正干活的大脑中枢)
├─ 先判断有没有声音,没声音就啥也不干,不白烧 CPU
├─ 一边听一边出字(流式识别)
├─ 你说完了,再校一遍字、补上标点(定稿识别)
├─ 看看有没有叫「肥鱼」
├─ 把指令丢给 headless 会话,让智能体去执行
├─ 把答复切成一句一句,用本地音色合成语音
└─ 喇叭放出来,配上三声小提示音
│
▼
会话存进文件,同时登记到「语音对话」工作区
这里有个坑得提前说清楚:上游那个插件原本是在浏览器里录音的(getUserMedia 那一套),宿主端压根没有采集代码。可我们这台机器连浏览器都不开,所以只能自己补上「宿主端采集 + 桥接」这一截。模型、音色表、模型下载脚本还是上游给的,其余这一截是我们自己搭的。
一次对话是怎么判定的
说白了就是「什么时候算你在说话、什么时候算你说完了」:
- 安静的时候识别器根本不启动,空闲时 CPU 几乎为 0;太轻的动静(RMS 低于 0.006)和 300 毫秒以下的短响都不算一句话;
- 一有声音就开始收,还往前多留 300 毫秒,免得句首那个字被吞掉;识别结果只有标点或干脆是空的,直接丢掉;
- 连续安静 2 秒,就当你这句话说完了;
- 唤醒词必须在句首:两字词的第二个字要准,第一个字容许同音 —— 说「飞鱼」能唤醒,说「买条鱼」不会;
- 唤醒词优先级最高:只喊名字,立刻停掉正在念的音频、回一句「我在」,但不会杀掉正在跑的任务;接下来 20 秒不用再叫它;
- 紧接着说「停」「算了」「别做了」这类不超过 12 字的短句,才真正终止任务,回一句「好的,停了」;
- 其它指令:它闲着就立刻做,忙着就排队,手头这轮完了接着处理;
- 朗读期间只有喊唤醒词能打断,回声、咳嗽、噪声都不会把答复截断。
每天一个新会话,别攒成一锅粥
方案基线里会话是固定一个不更换;这个项目按运维补充改成按天轮转,免得上下文越攒越长:
每天第一次开口,自动开一个当天的新会话;当天后面再说什么都接着这个会话聊;过了零点再开口,又换一个新的。 昨天的还在,想翻随时能翻。
这件事是宿主侧自动做的,你不用管,它也不会在回答里跟你汇报「我给你新建了个会话」——那种话念出来纯属废话。真想立刻清空上下文,手动开一段新会话也行,会丢掉当前上下文。
装之前要准备啥
- 一台 macOS 12+ 的机器,装好 Node 24(用 nvm 管比较省事),
dsh命令行能用,已经有个webprofile; - 一个能出声的麦克风;
- 一次性的图形登录能力——就为了第一次点一下「允许使用麦克风」,后台进程自己是弹不出这个框的;
- 网:npm 得能连上;
huggingface.co有时候连不通,得准备hf-mirror.com兜底。
提醒一句:采集 App 重新编译会改掉签名哈希,麦克风授权就得重新点一次。所以装完就别再动那个二进制了。
怎么装
九步,别急,一步一步来。完整的命令、配置文件内容和踩坑说明都在 references/语音模式说明.md 的第 10 节,这里只给个路线图:
- 把语音插件装进
webprofile(dsh plugin --profile web add dsh-voice-mode); - 下载并校验模型 —— 这一步有坑:下载脚本按默认分支抓,运行时却按固定版本号校验,得按固定 revision 把 4 个文件补齐,最后 32/32 全过;
- 建一个专门的语音工作区,写好语音规则
AGENTS.md; - 编译采集 App、签名、手动点一次麦克风授权;
- 放好桥接程序,先跑一次 headless 拿到会话 id;
- 配好 DSH:web profile 的语音开关、headless 的默认模型、云端密钥;
- 装两个用户级 LaunchAgent(采集、桥接),带崩溃自动拉起;
- 开系统自动登录,让重启后不用有人去点登录;
- 验收。
两个特别容易栽的地方:注册工作区记录时五个字段必须写全(少个 updatedAt,侧栏会话列表会整个空白);别把采集改成系统级 LaunchDaemon,麦克风授权只在用户登录会话里有效,硬改只会拿到 auth_status=2 被拒。
文档里所有路径都用占位符写着(~、<VOICE_DIR>、<VOICE_WS>、<DSH_HOME>、<MODELS>、<UID>),没有写死任何一台机器的绝对路径和账号。装的时候按自己机器的实际情况换成真值就行。
装完怎么知道它真活了
- 采集和桥接两个进程都在;
- 采集日志里
frames一直涨、peak不是 0; - 桥接日志每 4 秒有一行电平;
- 喊「肥鱼」→ 听见「我在」→ 说个任务 → 它正常回答;
- 同一天里
session-id.txt前后不变,跨天第一次对话会换成新的。
日常想调点什么
| 想改 | 动哪儿 |
|---|---|
| 换个唤醒词 | VOICE_WAKE |
| 觉得它抢话、老打断 | 调大 VOICE_SILENCE_MS(现在 2 秒) |
| 说话声音太轻 / 环境太吵容易误触发 | 调 VOICE_RMS(现在 0.006) |
| 念得太快 | VOICE_SPEED(现在 0.9) |
| 换个音色 | voice.txt 写预设名,重启桥接;可选 suyingxue / gunian / fushiyu / bingjiao / bazong |
| 答案太啰嗦 | 改语音工作区的 AGENTS.md |
| 换线上 / 本地模型 | headless profile 的 agent-default-model,下一轮就生效,不用重启 |
| 立刻开新会话 | printf '' > <VOICE_DIR>/session-id.txt |
具体命令在参考文档第 7 节,参数表在第 5.1 节。
出问题了先看这儿
| 现象 | 八成是 | 怎么办 |
|---|---|---|
| 完全没反应,日志里连语音段都没有 | 采集停了(设备睡了、音频路由切了) | 采集 App 自检重试、强制绑定默认输入设备;看门狗 3 秒无音频块才重启,10 秒内不重复;急就手动 kickstart |
| 音量峰值一直低得离谱 | 麦克风选错了,或输入音量是 0 | 查系统默认输入设备 |
| 喊名字没反应 | 识别跑偏、没在句首,或者不在 20 秒免唤醒窗口里 | 已有定稿纠错;确认唤醒词在句首,必要时换三个字以上的词 |
| 话没说完就被执行 | 中间停顿太久 | 已经放宽到 2 秒,还不够就再调大 |
日志一直 session locked, retry |
你在 Web 界面开着这个会话,占了写锁 | 把那个页面关掉;它每 5 秒重试,不会乱换会话 |
| 侧栏看不到新会话 | 宿主只在启动时读会话列表 | 刷新页面或重启 Web 服务 |
| 念得含糊 | 合成音质 / 语速 | 语速已降到 0.9,也可以换个音色 |
完整排查表在参考文档第 8 节。
目前还做不到的事(不藏着)
- Web 界面不是实时的,会话列表得刷新或重启服务才更新;
- 在界面里打开语音会话会加写锁,跟语音写入打架(它会一直重试,不换会话);
- 单轮朗读超过 800 字会被悄悄截断,会话记录不受影响;
- 想打断它念答案,必须喊唤醒词;随便说句话、咳嗽或回声都不会截断朗读;
- 蓝牙耳机在播放时麦克风可能被系统切走,打断会失灵;
- 换模型没有运行时开关,得改 profile 配置;
- 冷启动依赖系统自动登录,登录密码改了要重新设一次;
- 早期试做留下的隔离目录、备份文件、查看页脚本,可以清掉。
这个仓库里都有啥
.
├── README.md ← 简体中文主版,说人话版
├── README.en.md ← English edition
├── README.bilingual.md ← 语言切换页 / Language switcher
├── SKILL.md ← WorkBuddy 技能入口(触发条件 + 章节导航 + 硬约束)
├── references/
│ └── 语音模式说明.md ← 完整方案原文:架构、参数、命令、九步部署、排障、变更记录
├── community/ ← DSH 社区收录状态、登记表材料与标签复查
│ ├── README.md
│ └── dsh-plugin-radar.md
├── CONTRIBUTING.md ← 怎么参与、哪些不能改
├── CODE_OF_CONDUCT.md ← 行为准则
├── SECURITY.md ← 部署涉及的安全事项
├── NOTICE.md ← 上游版权归属与致谢
├── LICENSE ← MIT
└── .github/
├── ISSUE_TEMPLATE/ ← 问题 / 建议模板
└── pull_request_template.md
想当成 WorkBuddy 技能用:把 SKILL.md 和 references/ 一起放进 ~/.workbuddy/skills/dsh-voice-mode-headless/,或者下载发布包解压到那儿。之后跟智能体提「把闲置设备改成语音盒子」「无浏览器语音链路怎么装」「肥鱼没反应」之类的话,它就会自己去翻参考文档的对应章节。
只想自己照着装:直接读 references/语音模式说明.md 第 10 节就够了,那份文档本来就是不依赖任何工具也能照做的施工手册。
完全开源,也进了 DSH 社区
先把话说清楚:这个仓库完全公开、完全开源。公开仓库、MIT 许可,随便看、随便用、随便改、随便分发,没有功能阉割,也没有「开源但保留某些权利」的附加条款。上游版权单独写在 NOTICE.md 里,不把别人的功劳算到自己头上。
开源项目该有的东西也补齐了:贡献指南、行为准则、安全说明、Issue 和 PR 模板。有意见直接开 issue,别客气。
DSH 社区这边:
- 仓库已经加上生态官方发现标签
dsh-plugin,dsh-plugin.org、dshmarketplace.dev、DSH Plugin Radar 等社区目录靠它做常规扫描,会自动发现并收录; - 也按 DSH Plugin Radar 登记表 的 🎓 技能 分区准备好了登记条目,收录进度和待办写在
community/README.md; - 精选插件库的主目录要求「可安装插件 + 真实插件代码 + 仓库满 1 天」,本仓库是文档型项目,按规矩不冒充插件去投主目录,只走技能 / 相关项目通道。
先说清楚:这不是一个 DSH 插件
社区里插件很多,身份得说明白,免得有人照着 dsh plugin add 装半天装不上:
- 本仓库是文档 + WorkBuddy 技能(
SKILL.md+references/语音模式说明.md),没有package.json、没有dsh.bundle、没有apply(ctx),也没有cordis.patch.yml; - 所以不能用
dsh plugin add安装本仓库。上面「怎么装」第 1 步那条dsh plugin --profile web add dsh-voice-mode装的是上游插件,是这条部署链路要用的依赖,跟本仓库不是一回事; - 想用这个仓库,要么把
SKILL.md和references/放进 WorkBuddy 的技能目录,要么直接照着 README 给设备装一套; - 在 DSH 社区目录里,它该归到「技能 / 文档 / 相关项目」,不是「可安装插件」。我们也是这么登记的。
跟 DeepSeek AI 官方没有隶属关系,也不是官方项目。
跟上游到底是什么关系
上游 qishuilalala/dsh-voice-mode 是个很完整的 DSH 全双工语音插件:边说边出字、按句朗读带字幕、开口即打断、可选唤醒词,识别在本地跑,不用额外 API Key。它原本是给浏览器界面用的。
我们这套是给连浏览器都不开的无显示器设备用的,所以:
- 用到上游的:模型下载脚本
scripts/prefetch.mjs、识别与合成模型、音色表、设置页; - 我们自己补的:宿主端麦克风采集 App、FIFO 音频管道、
bridge.mjs桥接、唤醒词与会话调度、LaunchAgent 自启、headless 会话接入、按天轮转会话。
换句话说,上游把最难的那部分(模型、识别、合成、音色)造好了,我们只是在它旁边接了一根线,让一台没屏幕的机器也能用上。这份关系在参考文档第 3 节和第 13 节也写得很清楚。
几个常被问到的问题
Q:一定要 Mac 吗? A:这套文档目前是按 macOS 写的(LaunchAgent、自动登录、麦克风授权、afplay 都是 macOS 的东西)。Windows / Linux 上可以拿来理解思路,命令别照抄。
Q:一定要联网吗?
A:识别是本地的,但推理模型目前走线上,密钥放在 <DSH_HOME>/.credentials.yaml。想全本地就把 headless 的默认模型换成本地 provider,下一轮生效。
Q:为什么非要系统自动登录? A:因为麦克风授权只在用户登录会话里有效。不自动登录,重启后没人点登录,那两个后台服务就起不来。代价是登录密码会以系统 kcpassword 保存、登录窗口被跳过,改密码后要重新设一次自动登录。
Q:这个仓库能用 dsh plugin add 装吗?
A:不能,它是文档和 WorkBuddy 技能,不是 DSH 插件。装的是上游 dsh-voice-mode,本仓库照着读或放进技能目录就行。详细见上面「先说清楚:这不是一个 DSH 插件」。
Q:这算不算另起炉灶重写了上游? A:完全不算,也担不起。模型、音色、识别合成全靠上游,我们只是补了「没有浏览器时谁来听、谁来传」这一截。
许可
本仓库的文档与技能说明采用 MIT,见 LICENSE——可以自由使用、修改、分发。上游项目同样是 MIT,其代码、模型与音色资源的版权归原作者 @qishuilalala 及各自权利人所有;本仓库不主张对上游代码的任何权利,也没有复制上游源码,只按公开文档和 npm 包做了引用与说明,完整归属见 NOTICE.md。
贡献指南、行为准则、安全说明、Issue / PR 模板都在仓库里,欢迎来提意见;DSH 社区的收录状态见 community/README.md。
🙇 写在最后:认认真真地,向上游鞠一躬
先把话说得明明白白:这个仓库能存在,几乎全部功劳都属于 qishuilalala/dsh-voice-mode 和它的作者 @qishuilalala。我们真的只是站在人家肩膀上,往前挪了半步。
说句掏心窝子的话:把语音识别、定稿纠错、流式出字、按句合成、打断、唤醒词、音色、模型下载和校验这些活儿做扎实,还要一轮一轮修到两百多项测试全绿,那是真功夫,是熬出来的。我们做的事情说破了天,也就是在旁边写了个采集小 App、架了根管道、写了个桥接把话递进去——没有上游把地基浇好,我们连第一句话都识别不出来,这份文档一页都写不出来。
所以:
- 🙏 向 @qishuilalala 致以最诚挚、最热烈的感谢和敬意! 谢谢您把这个项目开源出来,谢谢您把那么多坑一个个填平,谢谢您让后来的人有机会在它上面接着折腾。
- ⭐ 如果这个小仓库对您有一点用,请先把 Star 点给上游:https://github.com/qishuilalala/dsh-voice-mode。那是它应得的。
- 📦 也欢迎顺手看看上游的 npm 包、Releases,遇到问题去 Issues 反馈,就是对作者最好的支持。
- 🫶 我们这点补充,不敢掠美,也不配比。凡是有价值的地方,都是上游做得好;凡是不好用、不周到、写岔了的地方,那都是我们自己加的,跟上游一点关系都没有,欢迎直接在我们这边提。
再一次,郑重谢谢作者,谢谢这个优秀的项目。能站在它的肩膀上做一点点延伸,是我们的运气。🙏
No comments yet. Be the first to write one.