为 Rspress 文档站生成缺失的…

适用于 Rspress Markdown/MDX 文档站需要为新增页面或全站页面补齐 description frontmatter 的场景。

适用场景

解决思路

1. 定位 Rspress 配置文件：搜索 `rspress.config.ts`、`.js`、`.mjs` 或 `.cjs`，可能在项目根目录或 `website/` 等子目录。
2. 读取配置文件并提取 `root` 选项。
3. 判断 `root` 值：可能是普通字符串（`root: 'docs'`）或 JS 表达式（`root: path.join(__dirname, 'docs')`），确定解析后的目录路径。
4. 如果设置了 `root`，相对于配置文件所在目录解析它。
5. 如果没有设置 `root`，默认使用相对于配置文件所在目录的 `docs`。
6. 确认该目录存在；如果配置的 root 和 `docs` 都不存在，检查 `doc` 作为回退。
7. 检查 docs root 是否包含语言子目录（如 `en/`、`zh/`、`ja/`、`ko/` 等两字母代码）。
8. 如果有语言子目录，分别处理每个语言目录，且 description 语言应与内容语言匹配。
9. 如果没有语言子目录，将整个 docs root 视为单语言站点。
10. 在 docs root 下 glob `**/*.md` 和 `**/*.mdx`。
11. 排除 `node_modules`、构建输出（`doc_build`、`.rspress`、`dist`）。
12. 排除 `_meta.json` / `_nav.json`（侧边栏/导航配置，不是文档页面）。
13. 排除 `**/shared/**` 目录（通过 `@import` 引入的可复用片段，不是独立页面）。
14. 对每个文件：读取文件。
15. 对每个文件：检查 frontmatter 中是否已有 `description`；如果存在且非空，跳过。
16. 对每个文件：检查 frontmatter 中的 `pageType`；对于 `home` 页面，从 `hero.text` / `hero.tagline` 字段或功能列表推导 description，而不是从正文内容推导。
17. 对每个文件：按下面的写作指南生成 description。
18. 对每个文件：将 `description` 插入 frontmatter：如果已有 frontmatter 且包含 `title` 字段，插在 `title` 下一行。
19. 对每个文件：如果已有 frontmatter 但不含 `title`，将 `description` 作为第一个字段插入。
20. 对每个文件：如果没有 frontmatter 块，添加一个 frontmatter 块，内容为 `---`、`description: 生成的 description`、`---`。
21. YAML 格式：大多数 description 可以使用裸 YAML 字符串，例如 `description: Step-by-step guide to setting up your first Rspress site`。
22. YAML 格式：如果 description 包含冒号、引号或其他特殊 YAML 字符，用双引号包裹，例如 `description: 'API reference for Rspress configuration: plugins, themes, and build options'`。
23. 批量处理：文件很多时，使用并行 agent 调用同时处理相互独立的文件。
24. 批量处理：按目录分组（例如先 `guide/` 中所有文件，再 `api/` 中所有文件），以保持每个部分的专注和一致性。
25. 批量处理：处理完所有文件后，快速扫描确保没有遗漏——重新 glob 并检查是否仍有文件缺少 `description`。
26. 写作规则：长度 50–160 个字符；少于 50 对搜索引擎太模糊，超过 160 会在摘要中被截断。
27. 写作规则：语言匹配文档内容；中文文档写中文 description，英文文档写英文 description。
28. 写作规则：直接陈述页面覆盖内容；避免以「This document」、「This page」、「Learn about」开头，直接切入实质。
29. 写作规则：具体说明页面涉及的具体技术、API 或概念；例如 `Configure Rspress plugins for search, analytics, and internationalization` 优于 `How to use plugins.`。
30. 写作规则：纯文本，不使用 Markdown 格式语法。
31. 可参考好例子：插件开发指南 -> `Create custom Rspress plugins using the Node.js plugin API and runtime hooks`。
32. 可参考好例子：MDX 组件使用 -> `Import and use React components in MDX documentation files`。
33. 可参考好例子：Rspress 快速开始 -> `从安装到本地预览，搭建 Rspress 文档站点的完整流程`。
34. 可参考好例子：主题配置 -> `自定义 Rspress 主题的导航栏、侧边栏、页脚和暗色模式`。
35. 可参考好例子：首页（`pageType: home`）-> `Rspress documentation framework — fast, MDX-powered static site generator`。
36. 避免坏例子：`About plugins` 太模糊——哪些插件？关于它们什么？
37. 避免坏例子：`This page explains how to configure the Rspress theme` 浪费字符在 `This page explains how to` 上。
38. 避免坏例子：`Learn everything about Rspress!` 是营销空话，没有具体信息。

适用边界 · 注意事项

• 非 Rspress 项目，或没有 Rspress 配置文件时。
• 页面已有非空 `description`，或不是需要独立页面的 Markdown/MDX 文件（如 `_meta.json`、`_nav.json`、`shared` 片段）。
• 无法定位 docs root，且 `docs` 与 `doc` 目录都不存在时。