zemanzhang809/dsh-stt-plugin

dsh-stt-plugin

DeepSeek Harness 的语音输入(STT)插件。

在会话输入框工具行(模型选择器与发送按钮一侧)添加麦克风开关,基于浏览器 Web Speech API 把语音实时转写进消息草稿;并在设置弹框中新增「语音输入」页面,可配置识别语言、连续听写与自动发送。识别完全在浏览器端完成,进入会话的只有识别出的文本。

功能特性

- 🎙 输入框麦克风按钮 — 点击开始/停止;识别文本(含中间结果)实时写入草稿。
- ⚙️ 「语音输入」设置页 — 识别语言、连续听写、自动发送;配置通过 DSH 设置服务(ui-stt 命名空间)持久化。
- 📴 自动发送 — 默认关闭;开启后(单次模式)一句话识别结束自动提交消息。
- 🔁 连续听写 — 开启后麦克风持续工作直到再次点击停止,语句持续累加进草稿。
- 🔒 音频不出浏览器 — Host 与模型提供方都不接触音频。
- 🧩 干净的 Cordis 生命周期 — Slot、样式、词典、设置作用域全部挂在 Fiber 上,卸载即清理。

环境要求

| 要求 | 说明 |
| --- | --- |
| DeepSeek Harness | 源码运行(pnpm dsh web)或支持 profile 的部署包 |
| Node.js ≥ 18 / pnpm ≥ 8 | 构建与安装插件所需 |
| 浏览器 | Chrome / Edge ✅ 完整支持 · Safari ⚠️ 部分 · Firefox ❌ 不支持(按钮显示为禁用) |
| 麦克风权限 | 首次点击时浏览器会弹窗询问 |

安装

方式一:从 npm registry 安装(推荐;不需要能访问 GitHub)

把包安装进 profile 的 node_modules,并注册 bundle 层
dsh plugin --profile web add dsh-stt-plugin

启动(或重启)Harness —— web 是 --profile web 的内置别名
dsh web

说明:

- 这是最稳的路径:registry 拉取完全不经过 GitHub,在访问不了 GitHub 的网络下也能装。国内网络建议先把 pnpm 指到 registry 镜像(任意目录执行一次即可):

pnpm config set registry https://registry.npmmirror.com

- 仓库直接提交预构建的 lib/ 产物,且零运行时依赖(schemastery 已打包进产物)——安装本包不运行任何构建脚本、不拉取任何传递依赖,pnpm ≥ 10 的构建脚本审批与"新发布包放行时长"类供应链策略对本包均不适用(构建工具只放在 devDependencies,供插件仓库内开发使用)。
- 需要锁定版本时使用 dsh-stt-plugin@0.1.0。

方式二:从 GitHub 安装(要求能访问 GitHub)

dsh plugin --profile web add github:zemanzhang809/dsh-stt-plugin

症状对照:安装停在 Progress: resolved … 随后报 git ls-remote … Could not connect to server,说明这台机器连不上 github.com——是网络问题,不是插件问题。改用方式一或方式三,或让 git 走代理(git config --global http.proxy http://127.0.0.1:)。

另一种失败形态是 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION,指向一个你从没听过的包(如 style-mod):任何 pnpm add 都会重解析整个 profile,某个其他包的传递依赖刚发布了新版本,触发了 pnpm 默认的 24 小时放行策略。在 profile 的 pnpm-workspace.yaml 里把该包钉回上一个可用版本后重试:

overrides:
style-mod: 4.1.3

说明:

- 如果之前用方式三手工装过,先把它的 insert 行从 profile 的 cordis.patch.yml 里删掉:本方式下包会作为 bundle 层自带该行,重复的 stt 条目会导致组合失败。
- 需要锁定版本时使用 github:zemanzhang809/dsh-stt-plugin#v0.1.0。

方式三:从本地源码安装(开发 / 离线)

1. 准备插件检出
git clone https://github.com/zemanzhang809/dsh-stt-plugin.git
cd dsh-stt-plugin
pnpm install && pnpm build   # lib/ 已随仓库提交;改过 src/ 才需要重新构建

2. 链接进目标 profile 的 node_modules
cd ~/.dsh/profiles/web
pnpm add /绝对路径/dsh-stt-plugin

然后在 profile 的用户 patch 层(cordis.patch.yml)加入插件行——新插件必须用 insert 形式:

- insert:
- id: stt
name: dsh-stt-plugin
- # 已有的按 id 覆盖条目保持原样

profile 为 patchReload: "live" 时保存文件即热重组;否则重启 Harness。

包以 link: 方式链接,后续开发迭代只需:改 src/ → pnpm build → 刷新浏览器(Host 侧改动需要重启实例)。

方式四:验证安装是否生效

组合层检查,无需启动实例;输出中应包含
- id: stt
name: dsh-stt-plugin
dsh --profile web --dump-config

浏览器中:

1. 打开设置弹框 → 左侧导航出现「语音输入」(不依赖会话,是最快的确认信号)。
2. 打开(或新建)一个会话 → 输入框工具行出现麦克风按钮(模型选择器左侧)。

使用

1. 打开一个会话,让输入框进入可用状态。
2. 点击麦克风按钮开始说话。识别文本追加进草稿(草稿与每句话之间以空格拼接,中间结果实时重写)。
3. 再次点击停止。单次模式下若开启自动发送,一句话识别结束即自动提交;否则照常手动发送。

设置项参考

打开 设置 → 语音输入:

| 设置项 | 默认值 | 说明 |
| --- | --- | --- |
| 识别语言 | auto | auto 跟随浏览器语言,或选择 BCP-47 代码(zh-CN、en-US、ja-JP、de-DE、fr-FR、es-ES、ru-RU 等)。 |
| 连续听写 | 关 | 开启后麦克风持续工作,直到再次点击麦克风按钮;语句持续累加进草稿。 |
| 识别完成后自动发送 | 关 | 仅单次模式生效:一句话识别结束后自动提交消息。 |

配置持久化在 DSH 设置存储中,刷新与重启后保持。若该存储当前不可写(组合中没有设置服务,或页面经非环回地址访问),设置页会自动改用本浏览器的本地存储——控件始终可操作,并有提示说明保存位置。

关于按钮位置

输入框工具行提供两个可累加列表(conversation.input.left / conversation.input.right);本插件注册在 conversation.input.right,其条目渲染在工具行右端、模型选择器紧左侧——这是"发送按钮左侧、模型选择器右侧"的最低风险近似位。产品在该间隙内没有可累加的座位,精确占据它需要整体替换常驻输入器(conversation.composer.bar,single 插槽),会同时遮蔽官方 UI 及其声明的全部子插槽,不建议。若上游未来提供更细粒度的座位,只需在 src/client/index.tsx 改一行插槽名即可迁移。

实现原理

插件由两条流程构成:如何被组合进运行中的 Harness,以及听写时的运行时行为。

1. 组合与加载

flowchart TD
A["pnpm dsh webprofile: ~/.dsh/profiles/web"] --> B["组合插件树bundle 层 → 用户 cordis.patch.ymlinsert 行: id stt → dsh-stt-plugin"]
B --> C["Node 进程 —— Host 半边lib/index.js apply()"]
C --> D["inject: ['settings']Fiber 等待设置服务就绪"]
D --> E["ctx.settings.register('ui-stt', schema)language · continuous · autoSend(默认值)"]
B --> F["浏览器 —— boot graph 经模块加载器下发 lib/client.js"]
F --> G["inject: ['slots', 'locale', 'settingsScope']Fiber 保持 PENDING 直到服务提供方挂载"]
G --> H["apply(): 注入样式 + 中英词典+ settingsScope.bind('ui-stt', decode)"]
H --> I["Slot: 麦克风按钮conversation.input.right"]
H --> J["Slot: 语音输入页settings.section"]
E -.->|"settings describe 镜像"| H

Host 与 Client 两个半边从不直接通信:Host 只注册设置命名空间,Client 通过设置作用域(bind + describe 镜像,虚线边)读回配置。语音永不出浏览器——进入会话的只有识别出的文本。

2. 听写运行时

flowchart TD
S["点击麦克风按钮"] --> T{"SpeechRecognition可用?"}
T -- "否(如 Firefox)" --> U["渲染为禁用提示原因"]
T -- "是" --> V["开始识别记录 baseDraft(当前草稿)"]
V --> W{"result 事件"}
W -- "中间结果" --> X["实时重写尾部临时文本"]
W -- "最终结果" --> Y["提交该语句"]
X --> Z["setDraft(join(baseDraft, 已提交, 临时))守卫:仅输入机 phase 'plain' 时写入"]
Y --> Z
Z --> W
W --> EE{"识别结束"}
EE -- "连续听写开" --> FF["250ms 后自动重启沿用同一 baseDraft"]
FF --> W
EE -- "单次模式" --> GG["停止"]
GG --> HH{"自动发送开且已有成句?"}
HH -- "是" --> II["inputActions.submit()"]
HH -- "否" --> JJ["草稿就绪 —— 手动发送"]
V -.->|"权限拒绝 / 网络 / 无麦克风"| KK["显示错误提示清理监听状态"]

第一张图右侧的一切都运行在同一个页面内;setDraft / submit 是会话级 Slot 都会收到的标准输入动作面,插件不操作任何产品 DOM。

项目结构

dsh-stt-plugin/
├── cordis.patch.yml          # 组合层:插入插件行
├── package.json              # dsh.bundle.patch + dsh.client (web) manifest
├── scripts/
│   ├── build.mjs             # esbuild:lib/index.js(Node ESM)+ lib/client.js(浏览器)
│   └── smoke.mjs             # 产物 + 渲染级冒烟测试
├── docs/
│   └── dev-pitfalls.zh-CN.md # 开发实录:踩坑记录与调试手册
└── src/
├── host.ts               # 注册 ui-stt 设置命名空间(Schemastery schema)
├── shared/languages.ts   # Host schema 与 UI 共用的语言列表
└── client/
├── index.tsx         # apply():Slot、样式、词典、设置作用域
├── mic-button.tsx    # Web Speech API + inputActions.setDraft/submit
├── settings-section.tsx  # 「语音输入」设置页
├── speech.ts         # Web Speech API 类型与工具函数
├── locales.ts        # zh / en 词典
└── styles.ts         # 插件样式(引用主题令牌)

- Host 半边 — 只做一件事:ctx.settings.register('ui-stt', …),让浏览器端可以绑定持久化作用域。不接触音频,不发起网络请求。
- Client 半边 — 注册 conversation.input.right(麦克风按钮)与 settings.section(语音输入页)。草稿写入走会话级 Slot 的标准输入动作面(setDraft / submit),不操作任何产品 DOM。
- 构建契约 — lib/client.js 是以 window.__ModuleLoader__.load({ id, factory }) 包裹的经典脚本(DSH 客户端模块协议);react / react/jsx-runtime 保持 external,由外壳模块表提供。

开发

pnpm install
pnpm check   # tsc --noEmit
pnpm build   # 产出 lib/
pnpm test    # 双端产物冒烟测试,含用 react-dom/server 按模拟的
Slot props 真实渲染两个组件

测试套件会在 Node 里按渲染器实际传参的方式真实渲染两个 UI 组件,渲染崩溃会在 CI 中直接暴露,而不是让 UI 静默消失。

更多开发笔记——组合层的坑、本插件依赖的客户端运行时契约、调试手册——见 docs/dev-pitfalls.zh-CN.md。

许可证

MIT