前言¶
在 DeepSeek Harness（DSH）里做智能体或长会话开发时，语音往往只停在「说一句、识别一次」：转写出现在聊天里，录音留在临时目录，回头写交付文档时既找不到原话对应的几秒，也没法把波形和文本一起放进仓库。
社区里已有 TTS、单次 ASR、语音输入等插件，但少有把口述当成可归档资料的完整链路。下面介绍维护者 dingchenhui0618-arch 发布的 dsh-voice-memo（分类：记忆）：在会话视图增加「口述」Tab，按住说话或导入 WAV，经本机识别后在工作区生成 audio.wav、waveform.png、memo.md 与 meta.json，供回听、引用和写入文档。
这是什么¶
dsh-voice-memo 是 DSH 的口述归档插件。录完每一段都会落在当前会话工作区（默认 voice-memos/<id>/），而不是只在聊天里闪一下的转写结果。识别默认走本机 speechToText 或你配置的本地命令；引擎未配好时会如实标「未转写」，不伪造文本。
- 仓库：dingchenhui0618-arch/dsh-voice-memo
- 社区目录：skillhub 插件页
- 许可证：MIT（README 与 package.json 一致）
- package.json 版本：0.1.0
核心功能¶
面板：录音与归档¶
「口述」Tab 主要做四件事：
- 按住「按住说话」录音，松开结束；录音时显示电平和秒数。也可「导入 WAV」。
- 浏览器侧用 Web Audio 解码、混成单声道、重采样到 16 kHz、编码成 PCM16 WAV，再 POST 给 Host（Host 不需要自带音频解码器）。
- Host 调用本地识别引擎，生成
audio.wav、waveform.png、memo.md、meta.json。 - 列表里可点波形定位、回听音频、逐条复制分段引用、一键复制笔记路径。
归档目录结构¶
经过上面的步骤，每条口述落在工作区如下结构（outputDir 可配置，默认相对路径 voice-memos）：
<当前会话工作区>/voice-memos/
20261020-104532-ab12/
audio.wav 16 kHz 单声道 PCM16
waveform.png 960×220 透明背景波形 + 时间刻度
memo.md frontmatter + 元信息表 + 带锚点分段 + 引用块
meta.json 面板与工具共用的机器可读记录
分段带时间戳与 #seg-N 锚点，例如：
<a id="seg-1"></a>
### 00:00.0–00:02.4
先讲结论：这个方案今天可以落地。
可直接粘贴进交付文档的引用块格式见仓库 README 示例。
与常见做法的差异¶
| 常见做法 | 本插件 |
|---|---|
| 转写只在聊天里 | 落盘 wav + 波形 + markdown + meta |
| 无时间戳 | 分段 00:01.2–00:03.4 与 #seg-N |
| 依赖云端 ASR | 默认本机引擎；失败只影响 status，不编假文 |
| 波形需 ffmpeg / matplotlib | 纯 JS 写 PNG（node:zlib + CRC32） |
| 仅面板可见 | Agent 工具与面板共用同一套归档 |
Agent 工具¶
| 工具 | 作用 |
|---|---|
voice_memo_save |
将 WAV（路径或 base64）归档为口述笔记，返回路径与引用行 |
voice_memo_list |
列出工作区归档：时间、时长、段数、状态、笔记路径 |
voice_memo_read |
读取一条笔记的 markdown、分段与引用行 |
典型流程：用户说「把这个录音整理成笔记」时调 voice_memo_save；写文档时调 voice_memo_read 取带时间戳的引用。
识别引擎（配置摘要）¶
插件在 profile 的插件 Config 中注册为 dsh-voice-memo。asr.mode 支持 auto、harness、command、off：
- harness：DSH
speechToText；整段录音会按静音切窗再逐窗转写。桌面 profile 未加载实验性语音输入插件时不可用，面板会提示未配置引擎。 - command：本地命令；约定最后一个参数为 16 kHz 单声道 WAV，stdout 输出 JSON（含
segments数组）。仓库提供workers/transcribe_faster_whisper.py参考实现，需自行安装faster-whisper。 - auto：有 harness 用 harness，否则 command，都没有则明确报未配置。
- off：只归档音频与波形，笔记标「未转写」。
单条录音上限、音频大小上限等见下方配置块。
安装与启用¶
从 GitHub 安装（仓库已包含构建好的 lib/，无需本地 build）：
dsh plugin --profile <profile> add github:dingchenhui0618-arch/dsh-voice-memo
本地开发可 link（路径按你本机修改）：
dsh plugin --profile <profile> add link:D:\Projects\dsh-voice-memo
安装后重载 DSH，会话视图会出现「口述」Tab。
可选配置示例（摘自 README）：
dsh-voice-memo:
outputDir: voice-memos
language: zh
maxDurationSec: 600
maxAudioBytes: 20971520
asr:
mode: auto
command: null
providerId: null
timeoutSec: 120
使用 faster-whisper 时，可参考 README 在虚拟环境中安装依赖，并在 command 中指向 transcribe_faster_whisper.py 与 Python 解释器路径。
典型用法¶
- 启动带 web 客户端的 profile，确认 ASR 已按上节配置（或先用
off只归档音频与波形）。 - 打开会话，进入「口述」Tab，按住说话录一段，或「导入 WAV」走与真实截图相同的解码 → 重采样 → 上传链路。
- 在列表中回听、点分段复制引用，或将
memo.md路径贴进 README / 交付文档。 - 若由 Agent 处理录音，在会话中说明 WAV 路径或让 Agent 调用
voice_memo_save/voice_memo_read。
HTTP API 前缀为 /dsh-voice-memo（GET /api/state、POST /api/save 等），供面板与 Host 通信；日常使用以 Tab 与三个工具为主即可。
适用场景与注意¶
适合谁：需要把会议口述、现场说明、口头结论留在项目仓库里，且希望引用能指回具体秒数、附带波形图证据的 DSH 用户；也希望 Agent 能列出、读取同一份归档的开发者。
权限与安全：插件以当前 DSH 进程权限运行，会读写工作区下的 voice-memos/（或你配置的 outputDir），并可能执行你配置的 asr.command。安装前请阅读源码与 MIT 许可证，自行评估是否纳入团队规范。社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。
已知边界（README「已知边界」）：麦克风 getUserMedia 需真人授权，无头环境无法端到端自动化；harness 路径在维护者环境中以单测为主，command + faster-whisper 有真实归档验证；波形为振幅包络，非频谱分析。口述笔记是否提交 Git 由你决定。
结尾¶
dsh-voice-memo 补的是「口述 → 时间戳分段 → 波形 PNG → 仓库内 markdown」这一整条链路，并与 Agent 工具共用归档。若要查看简介与分类（记忆），可打开 skillhub 目录页；安装与配置细节以 GitHub 仓库 README 为准。
