feat: updat AI rules and support windsurf

.github/copilot-instructions.md

@@ -14,6 +14,72 @@
 - 可复用片段/模块：常见于 `docs/**/_*.mdx`（不要改动其对外接口/导入路径）
 - 模板参考：`docs/template/`
 
+## 项目目录结构约束（配件除外）
+
+- 目标：为每个产品/型号在 `docs/` 下保持一致、清晰的目录结构，便于维护、侧栏配置与 i18n 同步（参照 `docs/cubie/a7z`）。
+- 建议顶层结构（示例，来自 `a7z`）：
+
+```text
+.
+├── app-dev
+│   ├── mediapipe-dev
+│   ├── npu-dev
+│   ├── ollama-dev
+│   ├── opencv-dev
+│   ├── README.md
+│   ├── ros-dev
+│   ├── virtual-env
+│   └── vscode-remote-ssh.md
+├── download.md
+├── faq.md
+├── getting-started
+│   ├── install-system
+│   ├── quickly-start.md
+│   └── README.md
+├── hardware-use
+│   ├── ante.md
+│   ├── fan.md
+│   ├── hardware-info.md
+│   ├── microhdmi.md
+│   ├── microsd.md
+│   ├── mipi-csi.md
+│   ├── pcie-fpc.md
+│   ├── pin-gpio.md
+│   ├── README.md
+│   ├── type-c.md
+│   └── uboot.md
+├── low-level-dev
+│   ├── build-system
+│   └── README.md
+├── other-system
+│   ├── android
+│   └── README.md
+├── README.md
+└── system-config
+    ├── app-usage.md
+    ├── audio-usage.md
+    ├── auto-login.md
+    ├── blue-usage.md
+    ├── no-display.md
+    ├── README.md
+    ├── rsetup.md
+    ├── ssh-remote.md
+    ├── system-update.md
+    ├── uart-debug.md
+    ├── vnc-remote.md
+    └── wifi-usage.md
+```
+
+- 规则摘要：
+  - 每个型号目录须包含 `README.md` 作为入口（不要使用 `index.md`）。
+  - 常见子目录建议包括：`getting-started/`（含 `install-system/`）、`hardware-use/`、`system-config/`、`app-dev/`、`low-level-dev/`、`other-system/`。
+  - 每个子目录应包含 `README.md`（目录首页）。
+  - 文件/目录命名必须使用 **小写 + 连字符**（例如 `quickly-start.md`）。
+  - 安装相关目录统一使用 `install-system`（代替 `install-os`）。
+  - 侧栏顺序通过 `sidebar_position` 控制，避免使用 `0`，并在目录内按逻辑顺序编号（例如 `README:1, getting-started:2, hardware-use:3`）。
+  - 所有变更在 `docs/` 发生后需评估是否同步到 `i18n/en/...`，镜像结构以英文树为准并调整图片路径（英文图像路径在 HTML 标签中使用 `/en/img/...`）。
+  - 避免过深嵌套，保持每个产品树在 2-3 层内清晰可读。
+
 ## 写作与链接约定
 
 - 文档入口优先用 `README.md`（不要新建 `index.md`）
@@ -40,3 +106,56 @@
 - 优先遵循现有格式化/校验工具的输出，不要引入新的格式/规则
 - 提交前检查中英文文档是否同步：改动 `docs/` 时评估是否需要同步到 `i18n/en/docusaurus-plugin-content-docs/current/`（并确保英文树不含中文）
 - 如果遇到 CI 失败，先根据 pre-commit 报错定位对应文件再修复
+
+## AI 文档写作约束与提示词
+
+为保证 AI（Copilot / LLM）生成的文档质量与仓库规范一致，请遵守以下约束并优先使用示例提示词进行交互：
+
+### 基本约束（必须遵守）
+
+- 语言与目录对应：`docs/` 下为中文；若要生成英文版本，请同步到 `i18n/en/docusaurus-plugin-content-docs/current/` 并确保英文文件中不包含中文。
+- 文件命名与路径：使用小写 + 连字符（如 `quickly-start.md`），不要使用下划线或空格；新的 section 用 `README.md` 做目录入口。
+- Frontmatter 必须包含至少 `sidebar_position`，建议添加 `slug` 与 `description`；**禁止使用** `sidebar_label`（由侧栏配置控制）。
+- 图片资源：统一使用 `.webp`；在中文文档中引用 `/img/...`，在英文文档中 HTML `<img>` 使用 `/en/img/...`。
+- 链接与引用：内链优先使用相对路径（如 `./install-system/`）；避免硬编码站内绝对 URL。
+- 风格与语气：专业、简洁、客观；步骤使用清晰的标题（例如 `## 使用前提`、`## 安装系统`）。
+- 组件与模板：尽量复用仓库的 `_*.mdx` 组件（勿新增未注册组件）；确保 `Tabs` 组件带 `queryString` 属性。
+- 提交与测试：修改后运行本地 pre-commit / lint；如果更改了 `docs/`，同时评估是否需要更新 `i18n/en/...`。
+
+### AI 生成内容的质量检查（必须执行）
+
+1. 检查 Frontmatter 是否完整且格式正确。
+2. 验证所有内链是否有效（相对路径无错）。
+3. 确认图片存在于 `static/img/`，且格式为 `.webp`。
+4. 英文文件不得出现中文字符；中文文件符合写作风格。
+5. 对含步骤的段落，保证“命令/操作”用动词开头并列出明确步骤。
+
+### 术语约束（必须遵守）
+
+- 单一术语来源：所有术语首选写法应记录并维护在 `.github/terminology.md`（包含：术语、中文写法、英文写法、说明）。提交新术语需同时更新该术语表并在 PR 描述中注明。
+- 产品/商标：产品型号与商标保持原文写法，不随意翻译（例如 `Radxa`、`Rock 5`、芯片型号 `RK3588` 等）；在中文文档首次出现时可在括号中添加简短说明。
+- 专有名词大小写：严格使用官方写法，例如 `U-Boot`、`eMMC`、`UFS`、`NVMe`、`Linux`、`Android`。
+- 单位与数值：单位与数值之间保留空格（如 `8 GB`、`3.5 mm`）；在英文与中文文档中均使用阿拉伯数字表示数值。
+- 术语翻译：对常见技术词（如 `flash` → `刷机/写入镜像`、`bootloader` → `引导加载程序`、`system image` → `系统镜像`）在术语表中给出首选译法并固定。
+- 命名一致性：板卡、接口、引脚、配置项等命名须统一（例如 `GPIO` 引脚命名规则），避免在不同页面使用冲突写法。
+- AI 生成内容：使用 AI 生成文本前，需先读取并遵循 `.github/terminology.md`；AI 提示词中应明确写明“请遵循术语表的写法”，并在生成结果中加入“术语一致性”自检项。
+
+### 执行与校验（建议流程）
+
+- 执行方式：建议通过 Vale 或 textlint 集成术语检查规则（将术语表输出为规则或词典）。如暂未集成，提交人需在 PR 描述中列出已核对的术语项并说明核查结果。
+- 自检清单：在 PR 模板或说明中包含：已核对 Frontmatter / 已按照术语表规范用词 / 英文文件无中文 / 图片路径格式正确。
+- 术语提议流程：新增或修正术语时，更新 `.github/terminology.md` 并在 PR 描述中说明改动缘由；维护者将评审后合并并可同步到 CI 词库。
+
+### 可选改进（建议）
+
+- 为重要页面添加 `description` 和 `tags` 以增强 SEO 与站内检索。
+- 对复杂操作（刷机、底层开发）提供“警告/注意”块 (`:::warning` / `:::tip`) 并配图示例。
+
+### 小提示（Prompt engineering）
+
+- 明确输出格式：要求返回完整文件内容、只返回修改后的片段、或返回 diff（请写明）。
+- 指定约束：例如“保持表格列顺序不变”、“别改行内 HTML”，或“图片路径保持原仓库相对规则”。
+- 要求自检清单：在回复末尾添加“自检清单”并列出上面『质量检查』项的逐项确认。
+
+> 例子 (英文提示词)
+> "Using `docs/cubie/a7z/README.md` as a reference, produce an English `README.md` for a new board `XYZ`: include product overview, specs (table), quick start, install system (MicroSD/eMMC/UFS/NVMe), tips/ warnings. Add frontmatter: `sidebar_position: 1`, `slug: /xyz`, `description`. Ensure English files contain no Chinese. Return the full markdown file and a self-check list confirming frontmatter + local image paths + internal links are valid."

.github/terminology.md

@@ -0,0 +1,31 @@
+# 术语表（Starter）
+
+本文件作为仓库的唯一术语来源。请在新增或修正术语时同时更新本文件。
+
+| 术语（Key）       |                               中文写法（首选） | 英文写法（首选）                               | 说明                                                                   |
+| ----------------- | ---------------------------------------------: | ---------------------------------------------- | ---------------------------------------------------------------------- |
+| Radxa             |                                          Radxa | Radxa                                          | 公司/品牌名，不翻译。                                                  |
+| ROCK 5 系列       |           ROCK 5 / ROCK 5A / ROCK 5B / ROCK 5C | ROCK5 / ROCK5A / ROCK5B / ROCK5C               | 产品型号，保留官方写法。                                               |
+| ZERO 系列         | ZERO / ZERO+ / ZERO2 / ZERO2+ / ZERO3 / ZERO3+ | ZERO / ZERO+ / ZERO2 / ZERO2+ / ZERO3 / ZERO3+ | 产品型号，保留官方写法。                                               |
+| Cubie 系列        |              Cubie A7A / Cubie A7Z / Cubie A5E | Cubie A7A / Cubie A7Z / Cubie A5E              | 产品型号，保留官方写法。                                               |
+| U-Boot            |                                         U-Boot | U-Boot                                         | 引导加载程序，使用官方写法。                                           |
+| Linux 内核        |                                     Linux 内核 | Linux kernel                                   | 保留 Linux 大写写法，中文中带“内核”说明。                              |
+| eMMC / UFS / NVMe |                              eMMC / UFS / NVMe | eMMC / UFS / NVMe                              | 存储接口名，使用大写缩写。                                             |
+| system image      |                    系统镜像（或 system image） | system image                                   | 镜像文件的正式称呼，中文可并列原文。                                   |
+| flash / 刷机      |                                刷机 / 写入镜像 | flash / write image                            | 建议首选译法为“写入镜像”；用词受上下文影响时可在术语表中注明替代用法。 |
+| bootloader        |                                   引导加载程序 | bootloader                                     | 统一译法为“引导加载程序”。                                             |
+| MicroSD / SD card |                                     MicroSD 卡 | MicroSD / SD card                              | 存储卡命名；写作 `MicroSD 卡` 时保留大小写。                           |
+| GPIO              |                                           GPIO | GPIO                                           | 通用 I/O，首现可扩展为“通用输入输出（GPIO）”。                         |
+| PCIe              |                                           PCIe | PCIe                                           | e 必须是小写 ｜                                                        |
+
+---
+
+## 如何使用与维护
+
+- 提交新术语：在提出新术语的 PR 中更新本文件并说明来源与理由；维护者会审核并决定是否合并。
+- 集成检查：建议将本文件导出为 Vale/textlint 的词典用于自动校验（可向维护者提交 Vale 规则提案）。
+- 示例：若要在中文文档中引用 `U-Boot`，请写为 `U-Boot` 并在首次出现处说明其含义；若引用 `system image`，建议写为 `系统镜像 (system image)`。
+
+---
+
+> 自检清单（术语相关）：已核对术语表 / 文档术语与术语表一致 / 新术语已在本文件登记。

.windsurf/rules/copilot-instructions.md

@@ -0,0 +1 @@
+../../.github/copilot-instructions.md