---
name: qiwei-voice
description: 管理企微语音转写与本人声音克隆。用于接收、解码和转写企微语音，初始化本人参考录音，通过云端 IndexTTS2 生成受控客服语气，并在人工确认后发送原生企微语音消息。
---

# 企微语音

## 使用边界

执行以下能力：

- 下载、保存、解码和转写企微语音；
- 保存当前企微账号的本人参考录音；
- 调用云端 IndexTTS2 生成 WAV；
- 将 WAV 编码为 24kHz 单声道 SILK；
- 上传媒体并发送原生企微语音。

禁止克隆未明确授权的第三方声音。调用真实发送工具前，先向用户确认接收人、文本和语气。

## 数据存储

- 转写运行：`outputs/voice/<date>/<time>-transcribe/`
- 声音档案：`outputs/voice/profiles/<account-key>/reference.wav`
- 克隆运行：`outputs/voice/<date>/<time>-clone/`

不同企微账号使用独立声音档案。声音注销时删除当前账号档案。

## 转写流程

调用 `qiwei_transcribe_voice`，传入 `voiceUrl`、`filePath` 或 `base64Audio`。Silk 文件先解码，再按配置调用 fmode-listen。`voiceUrl` 只接受公网 HTTPS 地址，最多重定向 3 次、30 秒超时且音频最大 20MB；本机和内网地址会被拒绝。

## 声音克隆流程

1. 调用 `qiwei_voice_profile_status` 检查配置。
2. 调用 `qiwei_enroll_voice` 保存 5～30 秒本人录音。
3. 确认接收人、文本和语气。
4. 调用 `qiwei_send_cloned_voice`，同时传入 `confirmed=true`，生成并真实发送。发送成功后可在工作台消息流中回放该语音；不提供单独试听，避免额外合成费用。

从 Dashboard 的待审核草稿发送语音时，传入当前 `draftId`。仅在企微确认发送成功后，将该草稿结算为 `sent` 并关联语音消息；不要保留可再次批准发送的 pending 草稿。

工作台「转文字」直接展示合成时已保存的原文。不要为已发送的克隆语音再次调用 ASR，也不要因此产生额外模型费用。

`tone` 默认使用 `auto`。只使用以下受控语气：

- `natural`：普通说明；
- `friendly`：欢迎、感谢、成功和好消息；
- `apology`：投诉、道歉和服务失误；
- `empathetic`：遗憾、安慰和关怀；
- `reminder`：截止、到期和时间提醒。

保持 `use_random=false`。自动判断不明确时回退 `natural`。不要开放愤怒、厌恶、恐惧或强烈悲伤。

## 上传策略

声音合成通过 Fmode `/api/voice/indextts2`，并复用技能包的 Fmode Token。只通过 Fmode `/api/qiwei/doFileApi` 上传本地 SILK；上传失败时直接报错，不使用公网 URL 回源。语音发送请求发生网络结果不确定时不自动重试，避免重复发送。

## 配置与依赖

- `QIWEI_VOICE_ENDPOINT`：默认 `https://server.fmode.cn/api/voice/indextts2`；
- Fmode 鉴权：自动复用 `QIWEI_AUTH_TOKEN`、`FMODE_API_KEY` 或当前 Fmode Studio 的 NewAPI Token；
- 语音合成按 Fmode 服务端计费规则扣除 Token 额度；
- `@binsee/wx-voice`：SILK 编解码；
- `@ffmpeg-installer/ffmpeg`、`@ffprobe-installer/ffprobe`：音频标准化和校验。

## MCP 工具

- `qiwei_transcribe_voice`
- `qiwei_voice_profile_status`
- `qiwei_enroll_voice`
- `qiwei_send_cloned_voice`