语音校验 songjongdevsecops/dsh-escutar

dsh-escutar

一条语音笔记有两份记录：音频和转写文本。转写文本出错时（语言不对、有噪声、混进了别的笔记的文字），错误会悄悄进入对话。这个插件在 EmbeddingGemma 共享的 768 维空间里，测量转写文本离音频有多远；即使转写文本不可信，也能按语义搜索音频。

它从不重新转写，从不删除，也从不改写转写文本：只读取、测量、提醒。音频始终留在你的机器上。

安装

支持 Linux、macOS 和 Windows。打开终端（Windows 上用 PowerShell 即可），运行：

1. pnpm — the harness manages profile plugins with it
npm install -g pnpm

2. add the plugin to your web profile
npx @deepseek-ai/dsh plugin --profile web add github:songjongdevsecops/dsh-escutar

3. restart the harness: the bundle layer is read at boot
stop dsh web (Ctrl+C) and start it again
npx @deepseek-ai/dsh web

如果 dsh 是全局安装的，第 2 步改成 dsh plugin --profile web add github:songjongdevsecops/dsh-escutar。

包中声明了 dsh.bundle.patch，所以 dsh plugin add 还会把插件条目追加到配置档的 bundle 列表。这一条就是唯一的启用方式，每次启动都会生效。安装不需要再配置别的。

更新与卸载

update: re-run the add command above (it resolves the repository again), then restart
npx @deepseek-ai/dsh plugin --profile web remove dsh-escutar # then restart

要求

- Node.js ^22.19.0 || >=24.0.0（与 DeepSeek Harness 支持的版本范围相同）。
- pnpm 在 PATH 上 —— harness 用它管理配置档插件。
- DeepSeek Harness 本体。
- EmbeddingGemma 命令行，能以可执行文件方式调用。插件会调用 parecido <text> --simetrico 和 buscar <query> --indice <collection> --n <n>。用 DSH_ESCUTAR_GEMMA_BIN 环境变量或 gemma 配置项指定它。如果找不到这个可执行文件，第一次测量会返回错误，并在错误里点名该变量；harness 其余部分不受影响。
- 语音语料：每条笔记一个音频文件和一个转写文本，共用同一个 id（001.ogg + 001.md），可以并排放，也可以分到 audio/ 和 texto/ 两个目录。

插件本身没有原生依赖，也没有构建步骤：纯 ESM，只用 Node 内置模块。

用法

| 谁 | 怎么用 | 得到什么 |
| 智能体 | conferir_transcricao 工具 | 检查一条笔记（id），或按语义搜索音频（consulta） |
| 你 | /escutar 命令 | 转写文本可疑的近期笔记 |
| 智能体 | agent/pre-step 钩子 | 近期笔记可疑时，在对话末尾给一条简短提醒；没有可疑项就不追加，因此不消耗 token |

conferir_transcricao { "id": "001" } # is this note trustworthy?
conferir_transcricao { "consulta": "what did I say about backup" } # 搜索音频
/escutar # 最近的可疑笔记

判定结果

判定结果是音频向量与转写向量之间的余弦值：

| 判定 | 条件 |
| suspeita | 余弦 < 0.78 − 0.03 |
| incerta | 落在阈值周围 0.03 的区间内 |
| confiavel | 余弦 > 0.78 + 0.03 |
| sem-medida | 没有数值（命令行失败、缓存损坏） |

落在阈值边缘的笔记会特意报成 incerta：它既不算告警，也不算通过。

配置

每个键都有默认值，所以配置写错也不会弄坏插件。
在你的配置档补丁里按 id 覆盖对应行（~/.dsh/profiles/web/cordis.patch.yml；Windows 上是 %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml）。补丁会替换该行的整份配置，所以想保留的键都要重新写一遍：

- id: escutar
config:
corpus: '/path/to/voice-corpus'
cache: '/path/to/discordancia.json'
gemma: '/path/to/embeddinggemma'
limiar: 0.78
banda: 0.03
maxAvisos: 2
colecaoAudio: 'escutar-audio-gemma-v1'
tempoLimiteMs: 120000

| 键 | 默认值 | 含义 |
| workspace | 包目录 | corpus 和 cache 默认值的基准目录 |
| corpus | <workspace>/corpus | 存放音频/转写配对的文件夹 |
| cache | <workspace>/estado/discordancia.json | /escutar 和钩子读取的缓存 |
| gemma | DSH_ESCUTAR_GEMMA_BIN，然后是 ~/.local/bin/embeddinggemma（Windows 上是 embeddinggemma.exe） | EmbeddingGemma 命令行 |
| limiar | 0.78 | 余弦低于此值时，转写视为可疑 |
| banda | 0.03 | 阈值周围的不确定区间 |
| maxAvisos | 2 | 钩子最多追加的行数；0 表示关闭 |
| colecaoAudio | escutar-audio-gemma-v1 | consulta 使用的索引名 |
| tempoLimiteMs | 120000 | 单次命令行调用的超时 |

配置里没设 gemma 时，会使用 DSH_ESCUTAR_GEMMA_BIN 变量。包里不带任何与具体机器相关的路径。

索引与缓存

插件读取两份产物，不负责构建它们：

1. 音频索引（colecaoAudio，默认 escutar-audio-gemma-v1）——只有带 consulta 的 conferir_transcricao 需要它。用 EmbeddingGemma 命令行构建：

embeddinggemma indexar /path/to/corpus/audio \
--nome escutar-audio-gemma-v1 --ext ogg,opus,mp3,wav,m4a

音频编码器大致只读每个文件的前 30 秒。如果你需要把长笔记切成窗口，请在建立索引前先切好。

2. 不一致缓存（cache）——/escutar 和钩子需要它。它是由你的索引流水线写出的 JSON 文件：

{
"gerado_em": "2026-10-13T12:00:00+00:00",
"notas":
{
"id": "001",
"cosseno": 0.84,
"transcricao": "first 200 characters of the transcript",
mtime 和 mtime_texto 是测量余弦相似度时音频和转写文本的修改时间。工具每次读取都会检查这两个时间：缓存里没有它们，或者它们比磁盘上的文件旧，就不会把缓存当作当前结果——而是当场重新测量。钩子只对 mtime 在最近 48 小时内的笔记发出警告。

没有索引或缓存时，带 id 的 conferir_transcricao 仍然可用：它会实时测量这一对文件（加载模型约 11 秒，每条笔记再加几秒）。/escutar 和钩子保持沉默，并说明缺少什么。

验证

重启后，导出配置档配置，查找对应行： sh
npx @deepseek-ai/dsh --profile web --dump-config
text

== dsh-escutar

- id: escutar
name: dsh-escutar

然后让智能体用 {"id": "001"} 调用 conferir_transcricao（缓存存在时也可以运行 /escutar）。实时测量会返回余弦值、判定结果，以及从缓存读取的转写文本。

从源码检出运行测试套件： sh
npm test

测试套件覆盖判定区间、命令行输出解析器、缓存新鲜度检查、命令、钩子，以及缺少二进制文件时的报错。它使用 shell 桩，因此可在 Linux 和 macOS 上运行；安装插件不依赖它。

限制

- 音频编码器只读取约 30 秒。 长笔记靠一个窗口判定，而不是整段录音。
- 看似合理但错误的转写可能通过。 把同一个主题上的一个词换成另一个词，可能不会让余弦值降到阈值以下。这个信号能抓住明显错误：语言不对、噪声、来自另一条笔记的文本。
- 它不评判内容。 它只说明音频和文本是否在同一语义空间里谈论同一件事。

许可证

[MIT