前言¶

在 DeepSeek Harness（DSH）里写提示词或长草稿时，键盘输入往往跟不上思路。Harness 侧存在若干实验性语音相关包，依赖链和部署方式并不轻。若你已经在本机跑好了 Whisper（例如 faster-whisper 网关），更希望「浏览器点麦克风 → 本机转写 → 文字进编写区」，且不走云 API、不让插件替你下载模型，pinion05/dsh-local-wispr（Local Wispr）就是按这条路径设计的 DSH 插件。下面介绍它的定位、数据流、安装与配置。

这是什么¶

dsh-local-wispr（npm 包名 @local/dsh-local-wispr，当前资料版本 2.0.1）由维护者 pinion05 发布，归类为模型推理相关能力。一句话：在 Harness Web GUI 的 composer 上增加独立语音输入按钮，在浏览器里录音，经 DSH 宿主机同源路由转发到本机 Whisper HTTP 网关做转写，再把文本插入当前草稿。不使用 Harness 自带的实验性语音栈（dsh-experimental-*speech*、ui-voice-input），也不依赖浏览器 Speech API，不由插件拉取模型。

许可证：MIT。兼容 DeepSeek Harness 0.2.x（engines.dsh: >=0.2.0-rc.1 <0.3.0-0），面向 web 配置文件。

核心功能与行为¶

交互流程¶

1. 在 composer 工具行点击麦克风 → 浏览器立即开始录音（红色脉冲与计时；最长 240 秒自动停止；按 Escape 可取消）。
2. 点击停止（■） → 将录音 blob 以 POST 提交到 DSH Web 服务器上的同源路径 /local-wispr/transcribe。
3. 插件宿主机侧在 trust-fence 校验后，把音频代理到本机 Whisper 网关（示例：POST /api/transcribe?lang=ko）。
4. 返回的转写文本通过 InputActions.insertText() 写入草稿：优先插在开始录音时记录的插入点；若其间草稿已变则退回到当前插入点；若插入被拒绝则静默放弃。不会自动发送消息。

架构要点¶

浏览器 (Harness Web UI)
│  MediaRecorder（webm/ogg/mp4）
▼
POST /local-wispr/transcribe     ← DSH 同源路由
▼
Whisper 网关（例：127.0.0.1:8813）
│  POST /api/transcribe?lang=
▼  faster-whisper large-v3-turbo（资料示例为 int8、CPU）
{ text, seconds, elapsed }  →  编写区

• 宿主机（index.js）：注册 /local-wispr/transcribe、/local-wispr/health，向网关反向代理；浏览器不直连网关端口，避免 CORS，网关可只监听 loopback。
• 客户端（client.js）：在 conversation.input.right 插槽渲染麦克风；状态机为 idle → recording → transcribing → idle/error；处理权限拒绝、静音、超时等。

README 中 STT 徽章指向 Whisper large-v3-turbo（faster-whisper）；实际推理由你自建的网关决定，插件只约定 HTTP 接口形状。

环境与依赖¶

安装与启用¶

先将插件包放到本机目录（从 GitHub 仓库 获取源码或发布物后解压/拷贝均可，资料未规定单一获取方式）。再在 Harness 中安装 bundle：

• 图形界面：Plugins → Install bundle，填入该目录路径。
• CLI（web profile）：

dsh plugin --profile web add <插件目录路径>

安装成功后配置中会出现一行 local-wispr，composer 工具行出现麦克风按钮。

注意：插件在当前 DSH 进程权限下运行；安装前请自行阅读仓库源码与 MIT 许可证，确认网关地址与网络暴露范围符合你的安全策略。

配置（可选）¶

在 profile patch 中修改 local-wispr 行的 config，例如：

- insert:
    - id: local-wispr
      name: '@local/dsh-local-wispr'
      config:
        endpoint: http://127.0.0.1:8813   # Whisper 网关基址
        lang: ko                            # 转写语言提示，可用 "auto"
        timeoutMs: 240000                   # 单次转写超时
        maxBodyBytes: 31457280              # 录音 body 上限（30MB）

默认 endpoint 与 README 示例网关端口一致；若你改用 GPU 或其他 Whisper 服务，只需保证接口契约不变并改 endpoint / lang。

典型用法¶

1. 确认本机 Whisper 网关已启动且 GET /health 正常（README 故障表示例：systemctl --user start pi-voice-board）。
2. 用 localhost 或 HTTPS 打开 Harness Web，进入带 composer 的对话页。
3. 光标停在要插入文字的位置，点麦克风说话，点停止等待转写。
4. 检查草稿中是否出现转写文本；再按需编辑或发送（插件不会代你点发送）。

CPU 上 faster-whisper 的 RTF 在资料中约为 1（30 秒录音可能需约 30 秒以上转写）；换 GPU 网关可缩短等待。

故障排查（摘自 README）¶

适用场景与边界¶

适合：已在同一台机器（或 tailnet 内可信节点）部署 Whisper 网关、希望语音只走本地、又要与 Harness composer 草稿编辑流程绑定的开发者。

不适合：没有 HTTP 网关、只想用浏览器内置听写、或需要插件内置模型下载的一站式方案——这些不在本插件设计范围内。

插件目录与说明亦见于社区目录（与 DeepSeek / 幻方无官方从属）：skillhub.cn 插件页。源码与文档：github.com/pinion05/dsh-local-wispr。