Merge pull request #231 from opentiny/lhs/docs-i18n-skill

chore: add docs-i18n skill

Author: rhlin

.agents/skills/docs-i18n/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: docs-i18n
+description: >-
+  Sync GenUI SDK docs between Chinese and English when adding, editing, renaming,
+  or deleting documentation under docs/. Use when the user modifies docs/src/,
+  docs/demos/, docs/demos/en/, zh-theme.ts, en-theme.ts, or asks to update
+  English docs, i18n docs, or mirror Chinese documentation changes.
+---
+
+# GenUI SDK 文档国际化
+
+完整约定见仓库根目录 `docs/I18N.md`。修改中文文档时（共享 demo、仅改图片等例外除外），**必须同步**英文镜像与导航配置。
+
+## 目录映射
+
+| 类型 | 中文 | 英文 |
+|------|------|------|
+| Markdown | `docs/src/<path>.md` | `docs/src/en/<path>.md` |
+| Demo | `docs/demos/<path>.vue` | `docs/demos/en/<path>.vue` |
+| 图片 | `docs/src/public/`（共用，无需复制） | 同上 |
+| 中文导航 | `docs/.vitepress/config/zh-theme.ts` | — |
+| 英文导航 | — | `docs/.vitepress/config/en-theme.ts` |
+
+**路径规则**：
+
+- 文档：`docs/src/examples/chat/foo.md` → `docs/src/en/examples/chat/foo.md`（在 `src/` 后插入 `en/`）
+- Demo：`docs/demos/chat/foo.vue` → `docs/demos/en/chat/foo.vue`（在 `demos/` 后插入 `en/`，文件名相同）
+
+## 工作流程
+
+根据用户操作选择对应流程，完成后执行「验证清单」。
+
+### 新增文档
+
+1. 编写中文 `docs/src/<path>.md`
+2. 有交互示例时：
+   - 中文：`docs/demos/<name>.vue`
+   - 含中文 UI/文案时：`docs/demos/en/<name>.vue`（翻译 UI 文案、alert、Schema label 等；代码注释可翻译或保留）
+   - 纯英文、无文本、或 i18n 演示类 demo → 共用中文版，不建 `demos/en/` 镜像
+3. 图片放入 `docs/src/public/`（中英文共用）
+4. 在 `zh-theme.ts` 对应 sidebar 添加条目：
+   ```ts
+   { text: '中文标题', link: '/examples/chat/my-feature' },
+   ```
+5. 创建并翻译 `docs/src/en/<path>.md`
+6. 在 `en-theme.ts` 对应 sidebar 添加条目（链接带 `/en` 前缀）：
+   ```ts
+   { text: 'English Title', link: '/en/examples/chat/my-feature' },
+   ```
+7. 本地预览：`cd docs && pnpm dev`
+
+### 修改文档
+
+| 变更类型 | 同步动作 |
+|----------|----------|
+| 改正文 / 标题 / 代码块 | 更新 `docs/src/en/` 下对应文件（翻译变更部分） |
+| 改 demo 引用或逻辑 | 同步 `docs/demos/` 与 `docs/demos/en/` 中对应 `.vue`（如有） |
+| 改 sidebar 文案或顺序 | 同步更新 `zh-theme.ts` 与 `en-theme.ts` 对应条目 |
+| 仅改图片 | 无需动英文 md（public 共用） |
+
+### 重命名 / 移动
+
+1. 移动中文 md → 同步移动 `docs/src/en/` 下镜像文件
+2. 移动 demo → 同步移动 `docs/demos/en/` 下镜像文件（如存在）
+3. 更新 `zh-theme.ts` 与 `en-theme.ts` 中所有相关 `link`
+4. 检查文档内相对路径引用是否仍有效
+
+### 删除文档
+
+1. 删除 `docs/src/<path>.md`
+2. 删除 `docs/src/en/<path>.md`
+3. 删除关联 demo（`docs/demos/` 与 `docs/demos/en/` 下对应文件）
+4. 从 `zh-theme.ts` 与 `en-theme.ts` 移除对应 sidebar 条目
+
+## 英文文档编写规则
+
+### 路径调整（从中文复制时必改）
+
+英文 md 比中文多一层 `en/`，`<demo>` 与图片的相对路径需**多加一层 `../`**，并将 demo 路径指向 `demos/en/`：
+
+```markdown
+<!-- 中文 docs/src/examples/chat/foo.md -->
+<demo vue="../../../demos/chat/foo.vue" />
+
+<!-- 英文 docs/src/en/examples/chat/foo.md -->
+<demo vue="../../../../demos/en/chat/foo.vue" />
+```
+
+- 文档内互相引用：相对路径写法与中文相同
+- sidebar / nav 的 `link`：英文必须带 `/en` 前缀（如 `/en/guide/quick-start`）
+
+### 翻译原则
+
+- 翻译自然、技术准确的英文，勿逐字机翻
+- 保留 API 名称、组件名、包名、文件名、路径（如 `@opentiny/genui-sdk-vue`、`GenuiChat`）
+- 代码块：仅翻译注释与字符串字面量；结构、导入、类型与中文一致
+- 标题层级、章节顺序、代码块行高亮（如 `{12-19}`）与中文版对齐
+
+### Demo 需翻译的内容
+
+| 类型 | 示例 | 处理 |
+|------|------|------|
+| UI 文案 | `<button>新建会话</button>` | 译成英文 |
+| 代码注释 | `// 获取会话对象` | 翻译或保留 |
+| Schema 内容 | `label: '姓名'` | 译成英文 |
+| alert 消息 | `alert('复制成功')` | 译成英文 |
+
+### 无需国际化的 Demo
+
+以下 demo 无需创建 `demos/en/` 镜像，直接共用中文版：
+
+- 纯英文内容的 demo
+- 国际化示例 demo（如 `i18n.vue`，本身演示 i18n 功能）
+- 无文本内容的 demo
+
+## 导航配置对照
+
+两个 theme 文件结构镜像，修改时成对维护：
+
+- `zh-theme.ts`：`nav` / `sidebar` 的 `link` 无 `/en` 前缀
+- `en-theme.ts`：相同路径结构，`link` 以 `/en` 开头；`text` 为英文
+
+sidebar 按路径前缀分组（`/guide/`、`/components/`、`/examples/`、`/schema/`、`/advanced/`），新增条目放入与中文版相同的分组与层级。
+
+## 验证清单
+
+完成同步后逐项确认：
+
+```markdown
+- [ ] docs/src/en/ 下存在对应的翻译文件，路径正确
+- [ ] zh-theme.ts 与 en-theme.ts 均有对应 sidebar 条目且 link 正确
+- [ ] zh-theme.ts 与 en-theme.ts 顶层 nav 映射一致，英文 link 带 /en 前缀
+- [ ] 英文 md 中 <demo> 路径多一层 ../，且指向 demos/en/ 下对应文件（如需）
+- [ ] demo 含中文内容时已在 docs/demos/en/ 提供镜像
+- [ ] 删除场景下无残留英文文件、demo、sidebar 条目
+- [ ] 可选：cd docs && pnpm dev 本地预览中英文页面
+```
+
+## 快速定位镜像文件
+
+```text
+中文：docs/src/examples/chat/history.md
+英文：docs/src/en/examples/chat/history.md
+
+中文 demo：docs/demos/chat/history.vue
+英文 demo：docs/demos/en/chat/history.vue
+```