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（首行  自校验） ### 工具链（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>
2026-06-06 05:30:39 +08:00 · 2026-05-05 00:26:33 +08:00
parent 1c107a9344
commit 1f7c8b9673
59 changed files with 10533 additions and 2014 deletions
--- a/docs/I18N.md
+++ b/docs/I18N.md
@@ -0,0 +1,175 @@
+# Skills 多语言（i18n）作者指南
+
+DesireCore 市场支持多语言展示与多语言 SKILL.md 正文。本指南面向 skill 作者与 maintainer，说明如何编写、提交、维护多语言 skill。
+
+## 总则
+
+- **作者只需要写一种语言**（推荐写中文 `zh-CN`）。CI 会自动调模型翻译为其余 `manifest.json#supportedLocales` 中声明的语言。**默认 backend 是 [GitHub Models](https://docs.github.com/en/github-models)**（`openai/gpt-5-mini`），使用 repo 内置 `GITHUB_TOKEN`，无需额外 secret；可选切到 Anthropic Claude（见下文 CI 流水线一节）。
+- **目录名 == `name` 字段**：spec 强制约束（agentskills.io）。目录名是 ASCII slug；显示名（中/英/其他）安放在 `metadata.i18n.<locale>.name`。
+- **默认语言**：`en-US`。Fallback 链：`requested locale → source_locale → default_locale`。市场仓库 schemaVersion 1.1+ 必填 `metadata.i18n` 块，无顶层 legacy 字段兜底。
+- **禁止占位**：不要直接编辑 `metadata.i18n.<locale>.source_hash` 与 `translated_at`，这些字段由 `translate.py` 维护。
+
+---
+
+## 文件结构
+
+```
+skills/<your-skill>/
+├── SKILL.md                  # 顶层 frontmatter + 默认语言 (en-US) body
+├── SKILL.zh-CN.md            # 中文 body（作者源语言）
+├── SKILL.<locale>.md         # 其他语言 body（CI 生成）
+├── references/               # 可选：扩展文档
+└── scripts/                  # 可选：可执行脚本
+```
+
+只有 `SKILL.md` 有 frontmatter，其余 `SKILL.<locale>.md` 仅含 body，并在首行写 `<!-- locale: <locale> -->`。
+
+---
+
+## Frontmatter Schema
+
+```yaml
+---
+name: your-skill                    # 必须 == 父目录名（ASCII slug）
+description: >-                     # 单字段，Claude 检索用；建议含中英触发词
+  Use this skill when the user wants to ... 用户提到 ...、...、...
+license: MIT
+version: 1.0.0
+metadata:
+  author: your-org
+  updated_at: '2026-05-03'
+  i18n:
+    default_locale: en-US           # fallback 终点
+    source_locale: zh-CN            # 你写的源语言
+    locales: [zh-CN, en-US]         # 已提供的 locale
+    zh-CN:
+      name: 你的技能名
+      short_desc: 一句话描述
+      description: 较长的中文描述（可选）
+      body: ./SKILL.zh-CN.md
+      source_hash: sha256:xxxxxxxx  # CI 维护
+      translated_by: human          # human 或 ai:<model-id>
+    en-US:
+      name: Your Skill Name
+      short_desc: One-line description
+      description: Longer English description
+      body: ./SKILL.md              # 默认语言 = 根 SKILL.md
+      source_hash: sha256:xxxxxxxx
+      translated_by: ai:claude-sonnet-4-6
+      translated_at: '2026-05-03'
+market:
+  icon: <svg>...</svg>
+  category: productivity
+  channel: latest
+  maintainer:
+    name: DesireCore Official
+    verified: true
+---
+```
+
+完整 JSON Schema：[`scripts/i18n/schema/skill-frontmatter.schema.json`](../scripts/i18n/schema/skill-frontmatter.schema.json)
+
+---
+
+## 提交流程
+
+### 新建 skill（首次贡献）
+
+1. 在 `skills/<your-slug>/` 下新建目录与 `SKILL.md`。
+2. 编写中文 frontmatter + 中文 body：
+   - `name: <your-slug>`（ASCII）
+   - `metadata.i18n.{default_locale: en-US, source_locale: zh-CN, locales: [zh-CN]}`
+   - `metadata.i18n.zh-CN.{name, short_desc, description}`
+   - `metadata.i18n.zh-CN.body: ./SKILL.zh-CN.md`
+   - 中文正文写在 `SKILL.zh-CN.md`，首行 `<!-- locale: zh-CN -->`
+   - 根 `SKILL.md` body 留作翻译占位符（CI 会替换）
+3. 本地校验：`uv run scripts/i18n/validate-i18n.py skills/<your-slug>`
+4. 开 PR。CI 会自动追加一个 commit，把 en-US 翻译填入根 `SKILL.md` 与 `metadata.i18n.en-US`。
+5. **审 CI 翻译**：检查英文术语、Markdown 结构。若需修改，编辑后把 `metadata.i18n.en-US.translated_by` 改为 `human`，CI 不会再覆盖。
+
+### CI 翻译流水线（GitHub Actions）
+
+CI 用 [GitHub Models inference API](https://docs.github.com/en/github-models) 调模型。Workflow `.github/workflows/i18n-translate.yml`：
+
+- **触发**：PR 改动 `skills/**/SKILL.zh-CN.md` 或 `manifest.json`/`categories.json`；或 `workflow_dispatch` 手动触发。
+- **认证**：用 repository 的 `GITHUB_TOKEN`（无需额外 secret），workflow 声明 `permissions: models: read`。
+- **默认模型**：`openai/gpt-5-mini`（catalog 中性价比款 GPT-5；想要旗舰精度切到 `openai/gpt-5`。GitHub Models 当前**未上架** Anthropic Claude，仅 OpenAI / DeepSeek / Meta / xAI / Microsoft 系列）。
+- **切换模型**：repository → Settings → Variables → `TRANSLATE_MODEL`，取值参考 [GitHub Models marketplace](https://github.com/marketplace?type=models) 的 `publisher/model-name` 格式。
+- **切到 Anthropic Claude**：在 repo 加 secret `ANTHROPIC_API_KEY`，再加 variable `TRANSLATE_BACKEND=anthropic`、`TRANSLATE_MODEL=claude-sonnet-4-6`。
+
+提交回仓库的方式：`desirecore-bot` 在同 PR 追加 commit `chore(i18n): auto-translate skills [skip ci]`，并在 PR 留 review comment 提示人工核对。
+
+### 修改已有 skill
+
+1. 修改源语言 body（`SKILL.zh-CN.md`）或 `metadata.i18n.zh-CN.{name,short_desc,description}`。
+2. 不要手动改 `source_hash`。
+3. 开 PR。CI 检测 hash 变化，重新翻译目标 locale 并追加 commit。
+4. 若某个 locale 的 `translated_by: human`，CI 会跳过该 locale 并在 PR 留 review 提示「目标语已脱钩，请确认」，由你手工同步。
+
+---
+
+## 本地工具
+
+```bash
+# 校验 i18n 状态
+uv run scripts/i18n/validate-i18n.py
+uv run scripts/i18n/validate-i18n.py skills/web-access
+
+# 一次性把旧格式 SKILL.md 迁移到 i18n 格式（旧 skill 已迁完，新 skill 一般不需要）
+uv run scripts/i18n/migrate.py --apply skills/<your-slug>
+
+# 仅检查哪些 locale 缺翻译（不调 API）
+uv run scripts/i18n/translate.py --check
+
+# 本地翻译：默认走 GitHub Models（需 fine-grained PAT，启用 Models: Read 权限）
+GITHUB_TOKEN=ghp_... uv run scripts/i18n/translate.py skills/<your-slug>
+
+# 切到 Anthropic Claude（需 sk-ant-...）
+TRANSLATE_BACKEND=anthropic ANTHROPIC_API_KEY=sk-ant-... \
+  uv run scripts/i18n/translate.py skills/<your-slug>
+
+# 选择特定模型（默认 GitHub: openai/gpt-5-mini；Anthropic: claude-sonnet-4-6）
+TRANSLATE_MODEL=openai/gpt-5 GITHUB_TOKEN=... \
+  uv run scripts/i18n/translate.py skills/<your-slug>
+```
+
+---
+
+## 术语表
+
+`scripts/i18n/glossary.json` 是翻译的事实来源。提交新 skill 时，如果引入了领域专有名词（例如 "审批流"、"工单"），请在 PR 中追加术语映射。
+
+不要在术语表里加：
+- 已经在 `do_not_translate` 列表里的品牌/技术词
+- 译文与字面意义无差别的通用词
+
+---
+
+## 常见问题
+
+**Q：为什么顶层 `description` 还混着中英文？**
+因为 Claude 只用单字段 `description` 在 100+ skills 中匹配 user query。混合触发词是 Anthropic 官方在 [skill 最佳实践](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) 里认可的写法。各 locale 的纯净版本走 `metadata.i18n.<locale>.description`，市场 UI 读这里。
+
+**Q：CI 翻译质量不达预期怎么办？**
+1. 在 `glossary.json` 里加更具体的术语映射。
+2. 直接手工编辑目标 locale 的 body 与 frontmatter，并把 `translated_by` 改为 `human`，CI 不会再覆盖。
+3. 若是普遍问题，到 repo Settings → Variables 改 `TRANSLATE_MODEL`（默认 `openai/gpt-5-mini`，可选 `openai/gpt-5`、`openai/gpt-5-nano`、`openai/gpt-4.1`、`meta/llama-3.3-70b-instruct` 等），或切到 `TRANSLATE_BACKEND=anthropic` 用 Claude。
+
+**Q：能否禁用某个 locale 的自动翻译？**
+可以。在 `manifest.json#supportedLocales` 中删除该 locale；或在 skill 级别保留 `metadata.i18n.locales` 不含它（CI 不会主动新增）。
+
+**Q：references/ 里的文档需要翻译吗？**
+当前不强制。未来扩展时使用 `references/<file>.<locale>.md` 兄弟文件命名，与 SKILL body 一致。
+
+---
+
+## 相关文件
+
+- 规范：[agentskills.io/specification](https://agentskills.io/specification)
+- 最佳实践：[Anthropic Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+- 术语表：`scripts/i18n/glossary.json`
+- JSON Schema：`scripts/i18n/schema/skill-frontmatter.schema.json`
+- 校验：`scripts/i18n/validate-i18n.py`
+- 翻译：`scripts/i18n/translate.py`
+- 迁移：`scripts/i18n/migrate.py`
+- CI workflows：`.github/workflows/i18n-{validate,translate}.yml`