feat: skills i18n 改造(schemaVersion 1.1,零向后兼容) (#1)

* feat: skills i18n 改造 — schemaVersion 1.1,零向后兼容

把 21 个 skills + 1 个 agent + manifest/categories 全量迁移到 schemaVersion 1.1
的 i18n 结构,配套 CI AI 翻译流水线(GitHub Models)与本地工具链。

## 关键变更

### 数据结构(破坏性,schemaVersion 1.0 → 1.1)
- SKILL.md: 顶层 name 改为 ASCII slug(== 目录名,符合 agentskills.io 规范);
  中文显示名/short_desc/description 全部迁入 metadata.i18n.<locale>
- agents/<id>/agent.json: shortDesc/fullDesc/tags/persona.{role,traits} 迁入
  i18n.<locale>;changelog[].changes 改为 { <locale>: string[] } 对象
- categories.json: 每个分类的 label/description 迁入 i18n.<locale>,顶层只剩
  color/icon
- manifest.json: 加 supportedLocales / defaultLocale;顶层 description 迁入
  i18n.<locale>

### Body 文件结构
- 根 SKILL.md = frontmatter + default_locale (en-US) body
- SKILL.<locale>.md = 各 locale 的 markdown body(首行 <!-- locale: xx --> 自校验)

### 工具链(scripts/i18n/)
- glossary.json: zh→en 术语表 + do_not_translate 白名单
- schema/skill-frontmatter.schema.json: i18n frontmatter JSON Schema
- validate-i18n.py: 8 条校验规则(name 合规 / locale 完整性 / hash 一致性等)
- translate.py: GitHub Models / Anthropic 双 backend,sha256 增量翻译
- migrate.py: 一次性迁移脚本(旧格式 → i18n 结构)

### CI(.github/workflows/)
- i18n-validate.yml: PR 触发跑 validate + translate --check
- i18n-translate.yml: PR 触发用 GitHub Models(默认 openai/gpt-5-mini)翻译缺失
  locale,自动追加 commit;可切到 ANTHROPIC_API_KEY 走 Claude

### 文档
- docs/I18N.md: 作者贡献指南(schema 说明 / 提交流程 / 常见问题)
- README.md: 加多语言段落

## 验证

- uv run scripts/i18n/validate-i18n.py: OK,49 文件 0 错误
- uv run scripts/i18n/translate.py --check: 0 stale locale
- 21 skills 标题数 zh-CN == en-US 严格对齐(最大 66=66)
- skills-ref 规范校验:全部通过(顶层 name ASCII slug + description 单字段)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(i18n): 修复 PR #1 review 反馈的 6 项问题

- schema: translated_by 正则放宽为 ^(human|ai:[A-Za-z0-9._:/-]+)$,接受
  'ai:github:openai/gpt-5-mini' 这类 backend:model 形式(CI 翻译输出格式)
- README + docs/I18N.md: 修正"CI 用 Claude API"误导描述,正确说明默认是
  GitHub Models(openai/gpt-5-mini)+ GITHUB_TOKEN,可选切到 Anthropic
- skills/minimax-tts/SKILL.md & SKILL.zh-CN.md: 删除多余的 ``` 闭合,避免
  Markdown 后续渲染错乱
- skills/docx/SKILL.md: 翻译时丢失的 • Unicode escape 示例已恢复,
  与 zh-CN 版本对齐

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-05 00:26:33 +08:00
committed by GitHub
parent 1c107a9344
commit 1f7c8b9673
59 changed files with 10533 additions and 2014 deletions

View File

@@ -0,0 +1,164 @@
<!-- locale: zh-CN -->
# minimax-tts 技能
## 强制规则(违反将导致功能失败)
1. **必须用 HTTPS 访问 agent-service**`https://127.0.0.1:${PORT}``-k` 跳过证书验证
2. **全程使用 Bash curl** — 不要使用 HttpRequest 工具或 Python
## 完整执行流程
### 前置条件
- 用户已在资源管理器-算力中配置 MiniMax Media Provider 并填写 API Key
- agent-service 正在运行
### 语音选择指南
| voice_id | 特点 | 适用场景 |
|----------|------|---------|
| male-qn-qingse | 青涩男声 | 旁白、播客 |
| female-shaonv | 少女女声 | 有声书、对话 |
| female-yujie | 御姐女声 | 专业播报 |
| presenter_male | 主持人男声 | 新闻、正式场合 |
| presenter_female | 主持人女声 | 新闻、正式场合 |
### 生成语音
MiniMax TTS 返回 JSON包含音频 URL 或 hex 数据),`responseType` 使用 `"json"`
```bash
PORT=$(cat ~/.desirecore/agent-service.port)
curl -sk -X POST "https://127.0.0.1:${PORT}/api/media-proxy" \
-H "Content-Type: application/json" \
-d '{
"providerId": "provider-minimax-media-001",
"endpoint": "/t2a_v2",
"body": {
"model": "speech-02-hd",
"text": "要转换为语音的文本内容",
"voice_setting": {
"voice_id": "male-qn-qingse",
"speed": 1.0,
"vol": 1.0,
"pitch": 0
},
"audio_setting": {
"format": "mp3",
"sample_rate": 32000
}
},
"responseType": "json"
}'
```
### 响应处理
MiniMax TTS 返回 JSON根据请求参数可能返回 URL 或 hex 格式:
**URL 格式响应**(推荐,需在 audio_setting 中设置 `"format": "url"`
```json
{
"success": true,
"data": {
"data": {
"audio": {
"audio_url": "https://...",
"status": 1
}
},
"base_resp": { "status_code": 0, "status_msg": "success" }
},
"statusCode": 200
}
```
**Hex 格式响应**(默认):
```json
{
"success": true,
"data": {
"data": {
"audio": {
"data": "hex编码的音频数据...",
"status": 1
}
},
"extra_info": {
"audio_length": 12345,
"audio_sample_rate": 32000,
"audio_size": 67890
}
},
"statusCode": 200
}
```
### 下载并上传到 media-store
音频 URL 有时效限制,必须立即下载并保存到本地 media-store。
**URL 格式**
```bash
PORT=$(cat ~/.desirecore/agent-service.port)
AUDIO_URL="响应中的audio_url"
curl -sL "$AUDIO_URL" -o /tmp/minimax-tts.mp3 && \
curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
-F "file=@/tmp/minimax-tts.mp3;type=audio/mpeg"
```
**Hex 格式**
```bash
PORT=$(cat ~/.desirecore/agent-service.port)
HEX_DATA="响应中的hex数据"
echo -n "$HEX_DATA" | xxd -r -p > /tmp/minimax-tts.mp3 && \
curl -sk -X POST "https://127.0.0.1:${PORT}/api/media/upload" \
-F "file=@/tmp/minimax-tts.mp3;type=audio/mpeg"
```
从 JSON 响应中提取 `mediaId` 字段。
### 展示结果
在回复中使用 dc-media 协议引用(前端会自动识别音频扩展名并渲染播放器):
```
![语音合成结果](dc-media://这里替换为mediaId)
```
### 参数说明
| 参数 | 说明 | 默认值 |
|------|------|--------|
| model | 模型 | "speech-02-hd"(高清)或 "speech-02-turbo"(快速) |
| text | 要转换的文本 | 最大 10000 字符 |
| voice_setting.voice_id | 语音角色 | "male-qn-qingse" |
| voice_setting.speed | 语速 | 1.0 |
| voice_setting.vol | 音量 | 1.0 |
| voice_setting.pitch | 音调 | 0 |
| audio_setting.format | 音频格式 | "mp3" |
| audio_setting.sample_rate | 采样率 | 32000 |
### 特殊语法
MiniMax TTS 支持在文本中插入停顿标记:
- `<#0.5#>` — 停顿 0.5 秒
- `<#2#>` — 停顿 2 秒
- 有效范围0.01 ~ 99.99 秒
示例:`"你好<#1#>欢迎来到 DesireCore"`
### 错误处理
- `success: false` + `statusCode: 400`:文本为空或参数格式错误
- `success: false` + `statusCode: 401`API Key 无效
- `success: false` + `statusCode: 429`:频率限制
- `success: false` + `error: "未找到匹配的供应商"`:未配置 MiniMax Media Provider
### 注意事项
- 文本超过 3000 字符时建议使用流式输出(但代理模式暂不支持流式)
- 返回的 audio_url 有 24 小时时效
- 如果用户未明确要求,默认使用 `speech-02-hd` + `male-qn-qingse` + 1.0 倍速
- 长文本建议分段调用,每段不超过 3000 字符