OpenHanako CosyVoice QQ Voice Assistant

基于 Link-Start/openhanako_liliMozi（fork 自 liliMozi/openhanako）与阿里云百炼 CosyVoice 实现的 QQ 原生语音助手插件。

它让 HanaAgent 调用阿里云 CosyVoice 和用户自己的复刻音色，通过 QQ Bridge 直接发送原生语音条，而不是普通音频附件。本项目同时保留了清晰的插件结构，方便其他开发者修改模型适配、音色配置、语气生成和回复策略，搭配成适合自己 Agent 的语音方案。

功能

• 从 voice_id 自动识别绑定的 CosyVoice 模型。
• 根据最近对话和本次文本，自动生成自然的情绪、节奏、停顿和语速指令。
• 单条语音严格限制为最多 25 个字符。
• QQ Bridge 中以原生语音条发送，而不是普通文件附件。
• 动态语气分析失败时自动回退，不影响语音合成。

项目关系

• Agent 平台：Link-Start/openhanako_liliMozi
• 上游项目：liliMozi/openhanako
• 语音服务：阿里云百炼 CosyVoice

本仓库是社区插件项目，并非 OpenHanako 或阿里云官方项目。

要求

• HanaAgent 0.310.1 或更高版本。
• 阿里云百炼华北 2（北京）地域 API Key。
• CosyVoice 复刻音色 voice_id。
• 已接通 HanaAgent 内置 QQ Bridge，或其他支持原生音频的 Bridge。

安装

1. 下载 Release 中的 zip。
2. 打开 HanaAgent 的“设置 -> 插件”。
3. 将 zip 拖入安装区并启用插件。
4. 在插件配置中填写：
   • 阿里云百炼 API Key
   • 复刻音色 ID

模型、语言、语速、音调、音量、动态语气分析和 25 字限制均由插件自动填写默认值。插件会从 voice_id 前缀自动选择创建音色时绑定的模型，用户不需要手写模型名称。

支持自动识别：

• cosyvoice-v3.5-plus
• cosyvoice-v3.5-flash
• cosyvoice-v3-plus
• cosyvoice-v3-flash

API Key 也可以通过启动 HanaAgent 前设置环境变量提供：

$env:DASHSCOPE_API_KEY="your-api-key"

使用

对 Agent 说：

用语音回答我

或：

用开心一点的声音说：我回来啦

Agent 将调用 hana-cosyvoice-tts_speak。请在安装并启用插件后重启 HanaAgent，再建立新的 QQ Bridge 会话。安装前已经存在的旧会话可能保留旧工具列表；遇到这种情况，请在 HanaAgent 中重新建立 Bridge 会话或绑定，不要只依赖聊天命令刷新。

自动语气

每次合成前，插件会读取最近几条对话，并调用 HanaAgent 已配置的实用文本模型生成一条简洁的表演指导。它会根据语义自由决定整体基调、情绪转折、停顿和语速，不使用固定模板。

自动分析会产生一次额外的文本模型调用。分析失败或超时后，插件会使用默认语气继续合成。

cosyvoice-v3-plus 的复刻音色不支持自由指令控制，因此插件会自动跳过动态语气，其余支持的模型正常使用。模型必须与创建音色时的 target_model 一致。参见阿里云声音复刻 API。

隐私

• 仓库和 Release 包不包含任何 API Key、voice_id、HanaAgent 配置或生成音频。
• API Key 存储在 HanaAgent 的插件配置目录中，并被设置页隐藏显示。
• 对话上下文仅发送给用户在 HanaAgent 中配置的实用文本模型。
• 待朗读文本和动态语气指令会发送给阿里云百炼 CosyVoice API。

开发

插件没有构建步骤。源码结构：

hana-cosyvoice-tts/
├── manifest.json
├── tools/
│   └── speak.js
└── skills/
    └── voice-reply/
        └── SKILL.md

运行本地模拟测试：

node --test

测试会模拟阿里云响应，不会调用真实 API，也不会产生费用。

将整个目录压缩为 zip 即可安装。zip 根目录必须直接包含 manifest.json。

二次开发

开发者可以直接修改以下位置，组合成自己的语音助手：

• manifest.json：调整插件名称、默认语速、音量、语言和 25 字限制等配置。
• tools/speak.js：接入其他 TTS 模型、修改模型识别规则、请求参数和音频处理流程。
• skills/voice-reply/SKILL.md：改变 Agent 在什么场景发送语音，以及如何压缩和组织回复。
• INSTRUCTION_SYSTEM_PROMPT：定制根据上下文生成情绪、停顿和语速提示词的方式。

请勿将 API Key、私人 voice_id、聊天记录或生成音频提交到公开仓库。

License

Apache-2.0