review-docs

审查文档

全面审查文档，针对 Docus/Nuxt Content 优化，同时兼容任何 Markdown 文档。

工作流概览

此技能执行 5 步审查流程：

1. 检测项目类型 - 判断是 Docus/Nuxt Content 项目还是通用 Markdown 文档
2. 分析结构 - 梳理文档组织方式、语言区域和章节
3. 技术验证 - 检查 frontmatter、MDC 语法（如适用）和文件命名
4. 内容质量审查 - 评估清晰度、SEO、结构和国际化
5. 生成报告 - 提供分类明确、可执行的建议

优先级

• 关键 - 阻碍部署或导致错误（缺少 frontmatter、MDC 语法无效）
• 重要 - 对用户体验/SEO 产生显著影响（元数据质量差、使用被动语态、标题不清晰）
• 可选优化 - 润色和优化建议（添加提示框、改进示例）

预期结果

此技能仅生成详细报告。审查完成后，如有需要，会提供修复已发现问题的选项。

---

第 1 步：检测项目类型

目标： 判断这是 Docus/Nuxt Content 项目还是通用 Markdown 文档。

检测指标

检查 Docus/Nuxt Content：

1. package.json 依赖项：

   • "docus" - Docus 主题
   • "@nuxt/content" - Nuxt Content 模块
   • "@nuxtjs/mdc" - MDC 支持

2. 配置文件：

   • nuxt.config.ts 或 nuxt.config.js 中包含 @nuxt/content 模块
   • content.config.ts - 内容集合配置

3. 内容结构：

   • content/ 或 docs/content/ 目录
   • 子目录中的 .navigation.yml 文件
   • Markdown 文件中的 MDC 语法（::component-name）

4. 项目结构：

   • 带编号的目录（1.getting-started/、2.guide/）
   • 含有 navigation、seo 字段的 frontmatter

项目类型分类

类型 A：Docus/Nuxt Content 项目

• 应用所有 Docus 专属验证
• 检查 MDC 组件语法（必须使用 u- 前缀）
• Nuxt Content frontmatter 结构
• 导航文件（.navigation.yml）
• 完整技术验证

类型 B：通用 Markdown 文档

• 仅执行基础 Markdown 验证
• 通用 frontmatter（title、description、date、author）
• 标准 Markdown 语法
• 关注内容质量（SEO、清晰度、结构）
• 不执行 Docus 专属技术检查

检测结果

检测后，在报告中注明：

Project Type: [Docus/Nuxt Content | Generic Markdown]
Validation Mode: [Full (Docus-specific) | Basic (Markdown-only)]

根据检测到的类型调整验证步骤：

• 类型 A（Docus）： 执行所有步骤并进行完整验证
• 类型 B（通用）： 跳过 Docus 专属检查，关注内容质量

---

第 2 步：分析文档结构

定位内容目录

查找文档内容目录：

• 检查 docs/content/（最常见）
• 检查 content/（根目录）
• 检查 app/content/（替代位置）

检测语言区域

通过检查子目录识别语言结构：

单语言（没有语言区域子目录）：

content/
├── index.md
├── 1.getting-started/
└── 2.guide/

多语言（包含语言区域子目录）：

content/
├── en/
│   ├── index.md
│   ├── 1.getting-started/
│   └── 2.guide/
└── fr/
    ├── index.md
    ├── 1.getting-started/
    └── 2.guide/

检测逻辑：

• 如果直接子目录名称是 2 个字母的代码（en、fr、es、de 等），则为多语言
• 如果直接子目录以数字开头（1.getting-started），则为单语言

列出文档章节

识别每个语言区域中的所有编号目录：

• 1.getting-started/
• 2.guide/ 或 2.concepts/
• 3.api/ 或 3.essentials/
• 4.advanced/ 或 4.ai/

对于每个章节，记录：

• 章节名称
• 是否存在 .navigation.yml 文件
• 页面数量（统计 .md 文件）
• 页面文件名

验证核心文件

检查所需文件：

• 每个语言区域的根目录中都存在 index.md
• 每个章节目录中都有 .navigation.yml
• 带编号的文件遵循命名模式（1.introduction.md、2.installation.md）

创建结构映射

在报告中记录结构：

Project: [project-name]
Locales: [en, fr] (or "Single language")
Sections:
  - 1.getting-started: 5 pages, .navigation.yml ✅
  - 2.guide: 8 pages, .navigation.yml ✅
  - 3.api: 3 pages, .navigation.yml ❌ (missing)

---

第 3 步：技术验证

根据第 1 步检测到的项目类型调整验证方式。

对于 Docus/Nuxt Content 项目（Type A）

使用 references/technical-checks.md 执行全面的技术验证：

验证内容：

1. Frontmatter 结构 - 必需字段：title、description。可选字段：navigation、seo、links
2. MDC 组件语法 - 所有 Nuxt UI 组件都必须带有 u- 前缀（::u-page-hero、:::u-button）
3. 代码块标签 - 所有表示文件的代码块都需要描述性标签（```vue [App.vue]、```ts [config.ts]）
4. 代码语言一致性 - 代码示例应与项目的语言栈一致（例如，项目使用 TypeScript 时，应使用 TypeScript；Vue <script setup> 中应使用 lang="ts"）
5. 包管理器覆盖范围 - ::code-group 安装代码块必须涵盖项目／生态系统支持的所有包管理器
6. 代码预览 - 对可视化呈现的示例（表格、列表、渲染后的 Markdown 等）使用 ::code-preview
7. 代码组范围 - 仅组合等效的替代方案（例如，包管理器、框架变体），不要混合无关步骤（例如，安装命令和配置文件）
8. 文件命名 - 使用编号目录／文件、kebab-case；每个分区都应包含 .navigation.yml
9. 隐藏页面 - 对应当作为路由存在但不显示在侧边栏中的页面，使用 navigation: false

常见严重错误：

• 缺少 u- 前缀：::page-hero → 应为 ::u-page-hero
• 缺少必需的 frontmatter：title、description
• .navigation.yml 结构无效
• 缺少分区 index.md，导致分区根 URL 返回 404

完整的验证规则、示例和错误模式，请参阅 references/technical-checks.md。

对于通用 Markdown 项目（Type B）

简化验证 - 跳过 Docus 专属检查：

基本 Frontmatter 验证：

• 检查常见字段：title、description、date、author、tags
• 无严格要求，仅作为建议
• 如果完全缺少 frontmatter，则标记出来

标准 Markdown 语法：

• 验证基本 Markdown 语法（标题、列表、链接、代码块）
• 检查内部链接是否失效
• 确认图片路径存在

跳过：

• MDC 组件语法（不适用）
• Nuxt Content frontmatter 结构
• .navigation.yml 文件
• Docus 专属约定

关注：

• 内容质量（下一步）
• SEO 优化
• 清晰度和可读性
• 整体结构

---

第 4 步：内容质量审查

此步骤适用于所有项目类型（包括 Docus 和通用 Markdown）。

从四个维度评估内容质量。详细检查清单请参阅参考文件。

清晰度审查

使用 references/clarity-checks.md 检查：

• 语态和语气： 使用主动语态、现在时和第二人称
• 句子结构： 目标为 15-20 个词，避免冗长表达
• 段落结构： 每段 2-5 句；标题之间控制在 200-400 个词
• 行动导向的标题： 指南页面的标题（H1）和小标题（H2/H3）使用动作动词（Nuxt 模式）
  • 示例：“创建你的第一个模块”“配置你的应用”“构建插件”
  • 例外：入门指南（名词）、API（函数名称）、概念（描述性标题）
• 术语： 命名一致，并定义技术术语
• 代码示例： 完整、可直接复制粘贴、贴近实际，并带有文件标签

SEO 审查

使用 references/seo-checks.md 检查：

• 标题： 50-60 个字符，包含关键词且独一无二
• 描述： 120-160 个字符，有吸引力且独一无二
• 标题层级： 单个 H1，层级合理（H1→H2→H3），描述清晰
• URL： 使用 kebab-case，描述清晰且稳定
• 链接： 锚文本具有描述性，并包含“后续步骤”章节
• 内容长度： 落地页 300 个词以上，指南 400 个词以上，每个章节 200-400 个词
• 图片： 包含替代文本和颜色模式变体

结构审查

使用 references/structure-checks.md 检查：

• **层级：**最多 3 层，逻辑递进
• **组织：**每个章节包含 2-15 个页面，存在 .navigation.yml，并使用合适的图标
• **流程：**逻辑递进，包含“后续步骤”链接，不存在孤立页面
• **落地页：**主视觉、功能、快速入门
• **一致性：**各页面结构相似

i18n 审查（适用于多语言项目）

使用 references/i18n-checks.md 检查：

• **结构平行：**不同语言版本的目录、文件和页面数量相同
• **翻译完整性：**内容长度相近（±30%），标题相同
• **导航：**图标相同，标题已翻译
• **语言区域特定检查：**无语言混杂，内部链接正确，注释已翻译

---

步骤 5：生成报告

使用 assets/report-template.md 创建全面的审查报告。

根据项目类型调整报告：

• **Docus/Nuxt Content：**包含所有部分（技术、SEO、清晰度、结构、i18n）
• **通用 Markdown：**重点关注内容质量（SEO、清晰度、结构），省略 Docus 特有的技术问题

报告结构

# Documentation Review Report

**Generated:** [current date and time]
**Project:** [project name from package.json or directory]
**Reviewed:** [X] pages across [Y] sections in [locales]

---

## Executive Summary

- **Critical Issues:** [count] (must fix - block deployment/cause errors)
- **Important Issues:** [count] (significant impact on UX/SEO)
- **Nice-to-Have:** [count] (polish and optimization recommendations)

**Overall Assessment:** [1-2 sentence summary of documentation quality]

---

## Critical Issues

[List all Critical issues grouped by category]

### Technical: MDC Syntax Errors

#### Missing u- prefix on Nuxt UI components

**File:** `/content/en/1.getting-started/1.introduction.md:15`

**Problem:** Page hero component missing `u-` prefix

**Current:**
\`\`\`markdown
::page-hero
#title
Welcome
::
\`\`\`

**Should Be:**
\`\`\`markdown
::u-page-hero
#title
Welcome
::
\`\`\`

**Impact:** Component will not render, causing build errors

---

### Technical: Missing Frontmatter

[Similar format for each issue]

---

## Important Issues

[List all Important issues grouped by category: SEO, Clarity, Structure]

### SEO: Suboptimal Metadata

[Details with file paths and recommendations]

### Clarity: Passive Voice

[Details with examples and suggested rewrites]

### Structure: Poor Navigation

[Details with organizational recommendations]

---

## Nice-to-Have Suggestions

[List optimization suggestions by category]

### SEO Optimizations
- **[File]**: [Suggestion]

### Clarity Improvements
- **[File]**: Consider adding `::tip` callout for [specific content]

### Structure Enhancements
- **[Section]**: Consider splitting into subsections

---

## Locale-Specific Issues

[Only if multi-language detected]

### French (`/fr/`)
- [Translation issues]

---

## Statistics

### Content Overview

| Section | Pages (en) | Pages (fr) | Avg Words/Page |
|---------|------------|------------|----------------|
| Getting Started | [X] | [X] | ~[XXX] |
| Guide | [X] | [X] | ~[XXX] |

### Issue Breakdown

| Category | Critical | Important | Nice-to-Have | Total |
|----------|----------|-----------|--------------|-------|
| Technical | [X] | [X] | [X] | [X] |
| SEO | [X] | [X] | [X] | [X] |
| Clarity | [X] | [X] | [X] | [X] |
| Structure | [X] | [X] | [X] | [X] |
| i18n | [X] | [X] | [X] | [X] |
| **Total** | **[X]** | **[X]** | **[X]** | **[X]** |

---

## Positive Highlights

[Call out 2-3 things done well]
- Good use of callouts and code examples
- Consistent MDC component usage
- Well-organized section structure

---

## Recommended Action Plan

### Priority 1: Fix Critical Issues (Today)
1. [Specific actionable items]

**Estimated fixes:** [X] files

### Priority 2: Important Issues (This Week)
1. [Specific actionable items]

**Estimated fixes:** [X] files

### Priority 3: Nice-to-Have (Next Sprint)
1. [Specific actionable items]

**Estimated fixes:** [X] files

---

## Next Steps

**Would you like me to:**

1. **Fix all Critical issues** - I can automatically correct MDC syntax and frontmatter issues
2. **Rewrite specific sections** - Point out which pages need clarity improvements, and I'll rewrite them
3. **Optimize SEO metadata** - I can update all titles and descriptions to optimal lengths
4. **Restructure content** - If sections need reorganization, I can help restructure
5. **Complete translations** - If you need i18n content completed

**Or specify what you'd like to focus on first.**

报告生成指南

具体明确：

• 包含确切的文件路径和行号
• 展示当前代码与建议代码
• 说明每个问题为何重要（影响）

提供可执行建议：

• 给出明确的修复说明
• 包含代码示例
• 按影响程度排序

保持平衡：

• 突出优点
• 不要被次要问题淹没
• 聚焦影响较大的改进

生成报告后：

• 如果用户提出请求，愿意协助修复问题
• 随时处理特定类别或文件的问题
• 建议从严重问题开始

---

快速参考

最常见的问题：

• Nuxt UI 组件缺少 u- 前缀（::page-hero → ::u-page-hero）
• SEO 描述过短（需要 120-160 个字符）
• 指令使用被动语态（“可以这样做” → “这样做”）
• 标题过于笼统（“配置” → “配置你的应用”）
• 代码块缺少文件名标签（每个表示文件的代码块都应标注文件名）
• 代码语言与项目技术栈不匹配（例如，TypeScript 项目的 Vue <script setup> 缺少 lang="ts"）
• ::code-group 安装代码块未涵盖完整的软件包管理器（根据生态系统/项目检查）
• 在 ::code-group 中将无关步骤分组（例如，安装命令 + 配置文件）——应拆分为独立代码块
• 缺少 ::code-preview，而渲染预览本可提升内容清晰度（如表格、列表等）
• 章节缺少落地页 → 章节根 URL 返回 404（如有需要，添加带有 navigation: false 的 index.md）

完整检查清单和示例请参阅参考文件。