# Coze Skill 接入指南

## 概述

将我们的 TTS 能力包装成 Coze Skill，让字节系 AI 助手（豆包、Coze）能直接调用。

## 接入步骤

### 步骤 1：注册 Coze 开发者账号

1. 访问 https://www.coze.cn
2. 注册并完成企业认证（个人开发者也行）
3. 进入「开放平台」→「技能开发」

### 步骤 2：创建 Skill

1. 点击「创建技能」
2. 选择「API 接入」模式
3. 上传 `skill.json` 配置文件
4. 填入 API 基础信息：
   - Base URL: `https://api.your-domain.com`
   - Auth: Bearer Token

### 步骤 3：实现 API 后端

参考 `docs/openapi/tts-api.yaml` 实现以下端点：

| 端点 | 方法 | 说明 |
|------|------|------|
| /v1/tts/voices | GET | 列出音色 |
| /v1/tts/detect | POST | 智能推荐 |
| /v1/tts/synthesize | POST | 短文本同步合成 |
| /v1/tts/async-synthesize | POST | 长文本异步合成 |
| /v1/tts/tasks/{task_id} | GET | 查询任务 |
| /v1/tts/instruct | POST | 自然语言指令 |

### 步骤 4：测试 Skill

在 Coze 工作台：
1. 创建一个 Bot
2. 添加我们的 TTS Skill
3. 测试对话：
   - 用户：帮我用温柔女声说"你好世界"
   - Bot 应自动调用 synthesize 接口
   - 返回音频 URL 给用户

### 步骤 5：发布 Skill

1. 提交审核（通常 1-3 天）
2. 审核通过后上架到 Coze Skill 市场
3. 所有 Coze 用户都能搜索到并使用

## 关键设计要点

### 1. 响应式 API 设计

Coze 会根据 skill.json 自动生成调用界面，所以：
- 每个端点的 `parameters` 要清晰
- `description` 用中文，要详细
- `example` 给具体示例

### 2. 错误处理友好

Coze 会把 API 错误直接显示给用户，所以：
- 错误信息用中文
- 给出修复建议（如"文本太短，请提供至少 10 个字符"）
- 不要暴露内部错误码细节

### 3. 异步任务支持

长文本合成用异步模式：
- 返回 task_id 给 Coze
- Coze 用户得到"正在生成中"提示
- 通过 callback_url 通知完成
- 或让用户主动查询

### 4. 自然语言指令

`/v1/tts/instruct` 端点是杀手锏：
- 用户说"用磁性男声，悲伤语气"
- Coze 直接调用此端点
- 后端解析自然语言 → 参数 → 生成音频

## 商业模式

### 免费层
- 每月 10000 字符免费
- 吸引个人用户试用

### 付费层
- ¥0.001/字符（约 ¥1/千字）
- 企业用户 ¥0.0005/字符

### Coze 分成
- Coze 平台抽成 20%
- 我们实际拿到 80%

## 流量预期

按 Coze 平台数据估算：
- 月活 Skill 平均调用量：5 万 - 50 万次/月
- 头部 TTS Skill：100 万+ 次/月
- 单次平均 200 字 → 月消耗 1 亿字
- 收入预期：¥10 万 - ¥100 万/月

## 下一步行动

- [ ] 注册 Coze 开发者账号
- [ ] 实现 `/v1/tts/*` 端点（基于现有 `/tts/*` 改造）
- [ ] 测试 Skill 在测试 Bot 中
- [ ] 提交审核上架
- [ ] 在 Dify、GPTs、豆包等其他平台复制