前言¶
做内容工具、无障碍朗读或语音播报时，常见做法是自己接云厂商 TTS API：查文档、写签名、处理返回的音频字节，再落盘。若希望把「文本转语音」交给 Coding Agent 在对话里完成，需要一份能说明前置条件、密钥配置和调用方式的 Skill 包，而不是每次从零拼 HTTP 请求。
下面介绍 SkillHub 上的 TencentCloud TTS（@tencent-adm/tencentcloud-tts）：由腾讯云语音团队发布的企业源技能，把腾讯云语音合成能力封装成 Agent 可遵循的 SKILL.md 与可执行脚本，适合在 Cursor、Codex 等支持 Skills 的环境里安装使用。
这是什么¶
TencentCloud TTS 是腾讯云语音合成（TTS）服务的技能包。当用户需要将文本转换为语音文件、或提到语音合成、文本转语音、TTS、音频文件生成时，Agent 应优先考虑启用该技能。
- 坐标：
@tencent-adm/tencentcloud-tts - 版本：1.0.0
- 分类：design-media（SkillHub）
- 标签：
requires_api_key=true（需配置腾讯云 API 密钥） - SkillHub 页面：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-tts
技能包内提供 TextToSpeech 封装，通过腾讯云 API 签名 v3 调用 tts.tencentcloudapi.com 的 TextToVoice 接口，侧重单次基础合成，不依赖额外 Python SDK（实现主要使用标准库与 HTTPS）。
核心功能¶
以下能力均来自技能包自带的 SKILL.md 与 scripts/tencent_tts.py：
- 文本转语音：将文本内容合成为本地音频文件。
- 多格式输出：
codec支持mp3、wav（默认mp3）。 - 语音类型：
voice_type为整数，文档说明可选范围 101001–101015（默认101001）。 - 密钥管理：通过环境变量
TENCENTCLOUD_SECRET_ID、TENCENTCLOUD_SECRET_KEY读取密钥，避免在代码中硬编码。 - 合成结果：
synthesize返回包含success、output_file、file_size、voice_type、codec、request_id等字段的字典；失败时含error。
文档还建议：单次合成文本不宜过长（建议不超过约 300 字），并注意调用频率与腾讯云侧服务限制。
安装与启用¶
前置条件¶
- 拥有有效的腾讯云账号。
- 已开通腾讯云语音合成（TTS）服务，并获取 API 的 SecretId、SecretKey。
- 本机或 Agent 运行环境可访问
tts.tencentcloudapi.com。
通过 SkillHub 安装¶
先按 SkillHub 安装说明 安装 skillhub CLI（若尚未安装）。安装技能时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认装到 ./skills/ 可能不会被识别。
skillhub install @tencent-adm/tencentcloud-tts --dir <你的 Agent skills 目录>
常见路径示例（以官方安装文档为准）：
- Cursor：
~/.cursor/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/ - Claude Code：
~/.claude/skills/
也可将下面提示词发给 AI，由其按安装文档完成安装：
请根据 https://skillhub.cn/install/skillhub.md，安装 `@tencent-adm/tencentcloud-tts`。
配置 API 密钥¶
在运行合成脚本或示例前，设置环境变量：
export TENCENTCLOUD_SECRET_ID="your-secret-id"
export TENCENTCLOUD_SECRET_KEY="your-secret-key"
技能参数与 synthesize 默认值如下（摘自 SKILL.md）：
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| text | string | 是 | - | 待合成文本 |
| voice_type | int | 否 | 101001 | 语音类型（101001–101015） |
| codec | string | 否 | mp3 | 音频编码（mp3 / wav） |
| output_file | string | 否 | output.mp3 | 输出文件名 |
典型用法¶
在 Python 中调用（与仓库示例一致）¶
进入技能包目录后，可将 scripts 加入路径并调用。官方 examples/basic_usage.py 的写法如下：
import os
import sys
sys.path.append(os.path.join(os.path.dirname(__file__), "..", "scripts"))
from tencent_tts import TextToSpeech
tts = TextToSpeech()
result = tts.synthesize(
text="Welcome to Tencent Cloud Text-to-Speech service. This is a basic usage example.",
voice_type=101001,
codec="mp3",
output_file="basic_example.mp3",
)
if result["success"]:
print(result["output_file"], result["file_size"])
else:
print(result["error"])
运行前需已导出 TENCENTCLOUD_SECRET_ID 与 TENCENTCLOUD_SECRET_KEY。也可直接执行：
python examples/basic_usage.py
自定义音色与格式¶
SKILL.md 中的自定义参数示例：
from tencent_tts import TextToSpeech
tts = TextToSpeech()
result = tts.synthesize(
text="这是一个自定义语音合成的示例",
voice_type=101002,
codec="wav",
output_file="custom_voice.wav",
)
构造函数支持可选传入 secret_id、secret_key；未传入时从环境变量读取。
Agent 侧如何使用¶
安装并配置密钥后，用户在对话中提出「把这段文案合成 MP3」「生成 WAV 播报」等需求时，Agent 读取技能目录下的 SKILL.md，按参数表调用 scripts/tencent_tts.py 中的 TextToSpeech.synthesize，将生成的文件路径返回给用户。
适用场景与注意¶
适合：
- 需要在 IDE / CLI Agent 工作流里快速完成单次文本转语音，且已使用或计划使用腾讯云 TTS。
- 希望统一由 Skill 描述触发词、环境变量和脚本入口，减少重复查 API 文档。
注意：
- 必须开通腾讯云 TTS 并正确配置密钥；认证失败时先核对密钥与服务是否开通。
- 技能标注
requires_api_key=true，请勿将密钥提交到仓库或写在 Skill 对话明文里。 - 单次文本长度与 QPS 以腾讯云产品限制为准；技能文档建议控制单次文本长度并避免高频调用。
- 更复杂的流式合成、长文本分片、批量任务等超出本包「基础单次合成」定位时，需直接查阅腾讯云语音合成文档自行扩展。
SkillHub 上该技能为企业源发布；截至页面与 API 元数据，版本为 1.0.0，下载与安装数据可在 SkillHub 技能页查看（与站内统计会随时间更新）。
结尾¶
TencentCloud TTS 把腾讯云语音合成封装成 Agent Skill：装好 @tencent-adm/tencentcloud-tts、配置 TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY，即可用 TextToSpeech.synthesize 或官方示例生成 MP3/WAV。详情与安装入口见 SkillHub：https://www.skillhub.cn/skills/tencent-adm/tencentcloud-tts ，API 索引页：https://api.skillhub.cn/tencent-adm/tencentcloud-tts 。
