前言¶
做內容工具、無障礙朗讀或語音播報時，常見做法是自己接雲廠商 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 。
