DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

liuda1999 /

liuda1999/dsh-voice-mode-headless

Topic repository only

把闲置设备变成「只靠说话」的常驻智能体 · Turn an idle machine into a voice-only agent box — no screen, no keyboard. With gratitude to qishuilalala/dsh-voice-mode

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

让一台吃灰的旧设备,变成「动动嘴就能干活」的智能体盒子

Turn an idle machine into a voice-only agent box. No screen. No keyboard. Just power, network, a microphone — and your voice.

License: MIT Release: v1.0.0 DSH: dsh-plugin

简体中文 · 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 那一套),宿主端压根没有采集代码。可我们这台机器连浏览器都不开,所以只能自己补上「宿主端采集 + 桥接」这一截。模型、音色表、模型下载脚本还是上游给的,其余这一截是我们自己搭的。


一次对话是怎么判定的

说白了就是「什么时候算你在说话、什么时候算你说完了」:

  1. 安静的时候识别器根本不启动,空闲时 CPU 几乎为 0;太轻的动静(RMS 低于 0.006)和 300 毫秒以下的短响都不算一句话;
  2. 一有声音就开始收,还往前多留 300 毫秒,免得句首那个字被吞掉;识别结果只有标点或干脆是空的,直接丢掉;
  3. 连续安静 2 秒,就当你这句话说完了;
  4. 唤醒词必须在句首:两字词的第二个字要准,第一个字容许同音 —— 说「飞鱼」能唤醒,说「买条鱼」不会;
  5. 唤醒词优先级最高:只喊名字,立刻停掉正在念的音频、回一句「我在」,但不会杀掉正在跑的任务;接下来 20 秒不用再叫它;
  6. 紧接着说「停」「算了」「别做了」这类不超过 12 字的短句,才真正终止任务,回一句「好的,停了」;
  7. 其它指令:它闲着就立刻做,忙着就排队,手头这轮完了接着处理;
  8. 朗读期间只有喊唤醒词能打断,回声、咳嗽、噪声都不会把答复截断。

每天一个新会话,别攒成一锅粥

方案基线里会话是固定一个不更换;这个项目按运维补充改成按天轮转,免得上下文越攒越长:

每天第一次开口,自动开一个当天的新会话;当天后面再说什么都接着这个会话聊;过了零点再开口,又换一个新的。 昨天的还在,想翻随时能翻。

这件事是宿主侧自动做的,你不用管,它也不会在回答里跟你汇报「我给你新建了个会话」——那种话念出来纯属废话。真想立刻清空上下文,手动开一段新会话也行,会丢掉当前上下文。


装之前要准备啥

  • 一台 macOS 12+ 的机器,装好 Node 24(用 nvm 管比较省事),dsh 命令行能用,已经有个 web profile;
  • 一个能出声的麦克风;
  • 一次性的图形登录能力——就为了第一次点一下「允许使用麦克风」,后台进程自己是弹不出这个框的;
  • 网:npm 得能连上;huggingface.co 有时候连不通,得准备 hf-mirror.com 兜底。

提醒一句:采集 App 重新编译会改掉签名哈希,麦克风授权就得重新点一次。所以装完就别再动那个二进制了。


怎么装

九步,别急,一步一步来。完整的命令、配置文件内容和踩坑说明都在 references/语音模式说明.md 的第 10 节,这里只给个路线图:

  1. 把语音插件装进 web profile(dsh plugin --profile web add dsh-voice-mode);
  2. 下载并校验模型 —— 这一步有坑:下载脚本按默认分支抓,运行时却按固定版本号校验,得按固定 revision 把 4 个文件补齐,最后 32/32 全过;
  3. 建一个专门的语音工作区,写好语音规则 AGENTS.md;
  4. 编译采集 App、签名、手动点一次麦克风授权;
  5. 放好桥接程序,先跑一次 headless 拿到会话 id;
  6. 配好 DSH:web profile 的语音开关、headless 的默认模型、云端密钥;
  7. 装两个用户级 LaunchAgent(采集、桥接),带崩溃自动拉起;
  8. 开系统自动登录,让重启后不用有人去点登录;
  9. 验收。

两个特别容易栽的地方:注册工作区记录时五个字段必须写全(少个 updatedAt,侧栏会话列表会整个空白);别把采集改成系统级 LaunchDaemon,麦克风授权只在用户登录会话里有效,硬改只会拿到 auth_status=2 被拒。

文档里所有路径都用占位符写着(~、<VOICE_DIR>、<VOICE_WS>、<DSH_HOME>、<MODELS>、<UID>),没有写死任何一台机器的绝对路径和账号。装的时候按自己机器的实际情况换成真值就行。


装完怎么知道它真活了

  1. 采集和桥接两个进程都在;
  2. 采集日志里 frames 一直涨、peak 不是 0;
  3. 桥接日志每 4 秒有一行电平;
  4. 喊「肥鱼」→ 听见「我在」→ 说个任务 → 它正常回答;
  5. 同一天里 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 反馈,就是对作者最好的支持。
  • 🫶 我们这点补充,不敢掠美,也不配比。凡是有价值的地方,都是上游做得好;凡是不好用、不周到、写岔了的地方,那都是我们自己加的,跟上游一点关系都没有,欢迎直接在我们这边提。

再一次,郑重谢谢作者,谢谢这个优秀的项目。能站在它的肩膀上做一点点延伸,是我们的运气。🙏

—/ 5

No ratings yet

Manifest verification required

Commit 4e719b5d7484

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