GFramework/.claude/skills/vitepress-validate/SKILL.md

VitePress 文档验证

验证 VitePress 文档的质量和规范性，确保文档符合项目标准。

用途

此 skill 用于验证 Markdown 文档的格式和内容，包括：

• Frontmatter 格式正确性
• 内部链接有效性
• 代码块语法标记
• 标题层级结构
• 中文标点符号规范
• 泛型符号转义

调用方式

# 验证单个文件
/vitepress-validate <文件路径>

# 验证整个目录
/vitepress-validate <目录路径>

# 验证所有文档
/vitepress-validate docs/zh-CN/

示例：

/vitepress-validate docs/zh-CN/api-reference/core/architecture.md
/vitepress-validate docs/zh-CN/core/

验证项

1. Frontmatter 验证

检查项：

• YAML 语法正确性
• 必需字段存在（title、description）
• 字段值类型正确
• outline 字段值有效（deep、[2,3] 等）

示例：

---
title: Architecture  # 必需
description: 架构基类说明  # 必需
outline: deep  # 可选，但值必须有效
---

2. 内部链接验证

检查项：

• 相对路径链接指向的文件存在
• 绝对路径链接格式正确
• 锚点链接对应的标题存在
• 没有损坏的链接

有效链接格式：

• [文本](./file.md) - 相对路径
• [文本](/zh-CN/core/architecture) - 绝对路径
• [文本](#标题) - 锚点链接
• [文本](./file.md#标题) - 组合链接

3. 代码块验证

检查项：

• 代码块有语法标记（csharp、bash 等）
• C# 代码块使用 csharp 标记（不是 cs 或 c#）
• 代码块正确闭合
• 没有未闭合的反引号

正确格式：

\`\`\`csharp
public class Example { }
\`\`\`

错误格式：

\`\`\`cs  // 应该使用 csharp
public class Example { }
\`\`\`

4. 标题层级验证

检查项：

• 标题层级不跳级（不能从 # 直接跳到 ###）
• 每个文档只有一个一级标题（#）
• 标题层级递增合理

正确示例：

# 一级标题
## 二级标题
### 三级标题
## 另一个二级标题

错误示例：

# 一级标题
### 三级标题  ❌ 跳过了二级标题

5. 中文标点符号验证

检查项：

• 中文句子使用全角标点（，。！？）
• 英文句子使用半角标点（,.!?）
• 代码和技术术语周围使用半角符号
• 括号使用规范

规范示例：

• "这是一个示例。" ✓（中文全角句号）
• "This is an example." ✓（英文半角句号）
• "Architecture 类提供了..." ✓（代码周围半角）

6. 泛型符号验证

检查项：

• 泛型符号正确转义（<T> → <T>）
• 仅在代码块外转义
• 代码块内保持原样

正确示例：

`List<T>` 是一个泛型类。

\`\`\`csharp
List<T> items = new List<T>();  // 代码块内不转义
\`\`\`

验证脚本

validate-frontmatter.sh

验证 Frontmatter 格式。

用法：

.claude/skills/vitepress-validate/scripts/validate-frontmatter.sh <文件路径>

validate-links.sh

验证内部链接有效性。

用法：

.claude/skills/vitepress-validate/scripts/validate-links.sh <文件路径>

validate-code-blocks.sh

验证代码块语法。

用法：

.claude/skills/vitepress-validate/scripts/validate-code-blocks.sh <文件路径>

validate-all.sh

执行所有验证。

用法：

.claude/skills/vitepress-validate/scripts/validate-all.sh <文件或目录路径>

输出格式

验证通过

✓ docs/zh-CN/core/architecture.md
  - Frontmatter: 通过
  - 内部链接: 通过
  - 代码块: 通过
  - 标题层级: 通过
  - 标点符号: 通过
  - 泛型符号: 通过

验证失败

✗ docs/zh-CN/core/architecture.md
  - Frontmatter: 失败
    × 缺少必需字段: description
  - 内部链接: 失败
    × 损坏的链接: ./missing-file.md (第 45 行)
  - 代码块: 警告
    ⚠ 使用了 'cs' 标记，建议使用 'csharp' (第 78 行)
  - 标题层级: 通过
  - 标点符号: 警告
    ⚠ 中文句子使用了半角句号 (第 102 行)
  - 泛型符号: 失败
    × 未转义的泛型符号: List<T> (第 120 行)

修复建议

验证失败时，skill 会提供具体的修复建议：

示例：

修复建议:
1. 在 Frontmatter 中添加 description 字段
2. 修复或删除损坏的链接: ./missing-file.md
3. 将代码块标记从 'cs' 改为 'csharp'
4. 将第 102 行的半角句号改为全角句号
5. 将第 120 行的 List<T> 改为 List&lt;T&gt;

配置选项

严格模式

启用严格模式时，警告也会导致验证失败。

/vitepress-validate --strict docs/zh-CN/

忽略特定检查

# 忽略标点符号检查
/vitepress-validate --ignore-punctuation docs/zh-CN/

# 忽略多个检查
/vitepress-validate --ignore-punctuation --ignore-generics docs/zh-CN/

集成到工作流

生成后自动验证

# 1. 生成 API 文档
/vitepress-api-doc GFramework.Core/architecture/Architecture.cs

# 2. 自动验证生成的文档
/vitepress-validate docs/zh-CN/api-reference/core/architecture.md

批量验证

# 验证所有 API 文档
/vitepress-validate docs/zh-CN/api-reference/

# 验证所有文档
/vitepress-validate docs/zh-CN/

退出代码

• 0 - 所有验证通过
• 1 - 存在错误
• 2 - 仅存在警告（非严格模式下仍返回 0）

相关 Skills

• /vitepress-api-doc - 生成 API 文档后自动验证
• /vitepress-guide - 生成指南文档后自动验证
• /vitepress-tutorial - 生成教程文档后自动验证

最佳实践

1. 生成后立即验证：每次生成文档后立即运行验证
2. 定期批量验证：定期验证所有文档，确保一致性
3. 修复所有错误：不要忽略验证错误，及时修复
4. 关注警告：警告虽不致命，但应该重视并修复
5. 使用严格模式：在 CI/CD 中使用严格模式确保质量

故障排除

问题：误报泛型符号错误

解决方案：确保泛型符号在代码块外正确转义，代码块内保持原样

问题：中文标点符号检查过于严格

解决方案：使用 --ignore-punctuation 选项，或手动调整规则

问题：链接验证失败但文件确实存在

解决方案：检查文件路径大小写，确保路径完全匹配

版本历史

• v1.0.0 - 初始版本，支持 6 项基本验证