GFramework/.claude/skills

VitePress 文档生成 Skills 系统

为 GFramework 项目提供自动化的 VitePress 文档生成能力。

概述

这是一套专门为 GFramework 项目设计的文档生成 skills，能够根据 C# 源代码自动生成高质量的 VitePress 文档。系统采用模块化设计，每个 skill 专注于特定的文档生成任务。

可用 Skills

1. vitepress-api-doc - API 文档生成

为单个 C# 文件生成 API 参考文档。

用途：

• 类、接口、枚举的 API 文档
• 方法、属性、事件的详细说明
• 基于 XML 注释生成文档

调用方式：

/vitepress-api-doc <C# 文件路径>

示例：

/vitepress-api-doc GFramework.Core/architecture/Architecture.cs

输出位置：docs/zh-CN/api-reference/<模块>/<文件名>.md

详细文档

---

2. vitepress-guide - 功能指南生成

生成功能模块的使用指南文档。

用途：

• 核心功能模块的使用说明
• 设计模式和架构概念
• 最佳实践和常见问题

调用方式：

/vitepress-guide <主题> <目标模块>

示例：

/vitepress-guide "事件系统" Core
/vitepress-guide "IoC 容器" Core

输出位置：docs/zh-CN/<模块>/<主题>.md

详细文档

---

3. vitepress-tutorial - 分步教程生成

生成分步教程文档，适合初学者学习。

用途：

• 框架入门教程
• 功能实现教程
• 问题解决方案

调用方式：

/vitepress-tutorial <教程主题>

示例：

/vitepress-tutorial "创建第一个 System"
/vitepress-tutorial "使用事件系统"

输出位置：docs/zh-CN/tutorials/<主题>.md

详细文档

---

4. vitepress-batch-api - 批量 API 文档生成

为整个模块批量生成 API 文档。

用途：

• 初始化模块文档
• 更新整个模块的文档
• 快速生成大量文档

调用方式：

/vitepress-batch-api <模块名>

示例：

/vitepress-batch-api Core
/vitepress-batch-api Godot

输出位置：docs/zh-CN/api-reference/<模块>/

详细文档

---

5. vitepress-validate - 文档验证

验证文档的质量和规范性。

用途：

• Frontmatter 格式验证
• 内部链接有效性检查
• 代码块语法验证
• 标点符号规范检查

调用方式：

/vitepress-validate <文件或目录路径>

示例：

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

详细文档

---

快速开始

1. 生成单个 API 文档

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

2. 批量生成模块文档

# 为整个 Core 模块生成文档
/vitepress-batch-api Core

3. 生成功能指南

# 生成事件系统使用指南
/vitepress-guide "事件系统" Core

4. 生成教程

# 生成创建 Model 的教程
/vitepress-tutorial "创建第一个 Model"

5. 验证文档

# 验证生成的文档
/vitepress-validate docs/zh-CN/api-reference/core/

工作流程

典型工作流程

graph TD
    A[开始] --> B{文档类型?}
    B -->|API 文档| C[/vitepress-api-doc]
    B -->|功能指南| D[/vitepress-guide]
    B -->|教程| E[/vitepress-tutorial]
    C --> F[/vitepress-validate]
    D --> F
    E --> F
    F --> G{验证通过?}
    G -->|是| H[完成]
    G -->|否| I[修复问题]
    I --> F

推荐流程

1. 初始化模块文档

   /vitepress-batch-api Core
   

2. 生成功能指南

   /vitepress-guide "IoC 容器" Core
   /vitepress-guide "事件系统" Core
   

3. 生成教程

   /vitepress-tutorial "创建第一个 Model"
   /vitepress-tutorial "使用命令系统"
   

4. 验证所有文档

   /vitepress-validate docs/zh-CN/
   

目录结构

.claude/skills/
├── README.md                          # 本文件
├── _shared/                           # 共享资源
│   └── scripts/                       # 共享脚本
│       ├── update-vitepress-nav.sh    # 更新导航配置
│       ├── parse-csharp-xml.sh        # 解析 XML 注释
│       └── generate-examples.sh       # 生成代码示例
│
├── vitepress-api-doc/                 # API 文档生成
│   ├── SKILL.md                       # Skill 说明
│   ├── template.md                    # 文档模板
│   └── examples/                      # 示例文档
│       ├── class-example.md
│       ├── interface-example.md
│       └── enum-example.md
│
├── vitepress-guide/                   # 功能指南生成
│   ├── SKILL.md
│   ├── template.md
│   └── examples/
│       └── guide-example.md
│
├── vitepress-tutorial/                # 教程生成
│   ├── SKILL.md
│   ├── template.md
│   └── examples/
│       └── tutorial-example.md
│
├── vitepress-batch-api/               # 批量 API 文档生成
│   ├── SKILL.md
│   └── scripts/
│       └── batch-generate.sh
│
└── vitepress-validate/                # 文档验证
    ├── SKILL.md
    └── scripts/
        ├── validate-frontmatter.sh
        ├── validate-links.sh
        ├── validate-code-blocks.sh
        └── validate-all.sh

设计原则

1. 单一职责

每个 skill 专注于一个特定任务：

• vitepress-api-doc - 单文件 API 文档
• vitepress-guide - 功能指南
• vitepress-tutorial - 分步教程
• vitepress-batch-api - 批量生成
• vitepress-validate - 质量验证

2. 模块化设计

• 共享脚本放在 _shared/scripts/
• 每个 skill 独立维护
• 可以单独使用或组合使用

3. 基于源代码

• 仅使用 XML 注释，不添加 AI 补充
• 保持文档与代码同步
• 代码示例由 AI 自动生成

4. 质量保证

• 所有生成的文档都应通过验证
• 遵循 VitePress 规范
• 保持一致的文档风格

文档规范

Frontmatter 格式

---
title: 文档标题
description: 简短描述（1-2 句话）
outline: deep  # 可选
---

代码块标记

• C# 代码使用 csharp
• Bash 脚本使用 bash
• JSON 使用 json
• YAML 使用 yaml

泛型符号转义

在正文中使用 HTML 实体：

• List<T> → List<T>
• 代码块内保持原样

中文标点符号

• 中文句子使用全角标点：，。！？
• 英文句子使用半角标点：,.!?
• 代码周围使用半角符号

共享脚本

update-vitepress-nav.sh

更新 VitePress 侧边栏导航配置。

用法：

.claude/skills/_shared/scripts/update-vitepress-nav.sh <文件路径> <标题>

parse-csharp-xml.sh

解析 C# XML 文档注释。

用法：

.claude/skills/_shared/scripts/parse-csharp-xml.sh <C# 文件路径>

generate-examples.sh

生成代码示例。

用法：

.claude/skills/_shared/scripts/generate-examples.sh <类型名> <命名空间>

最佳实践

1. 文档生成顺序

1. 先生成 API 文档（基础）
2. 再生成功能指南（概念）
3. 最后生成教程（实践）

2. 保持文档同步

• 修改代码后及时更新文档
• 使用单文件生成更新特定文档
• 定期批量验证所有文档

3. 质量控制

• 生成后立即验证
• 修复所有错误和警告
• 确保链接有效

4. 版本控制

• 将生成的文档提交到 Git
• 在 PR 中包含文档更新
• 保持文档与代码版本一致

故障排除

问题：生成的文档缺少内容

原因：源代码缺少 XML 注释

解决方案：

1. 在源代码中添加 XML 注释
2. 重新生成文档

问题：验证失败

原因：文档格式不符合规范

解决方案：

1. 查看验证错误信息
2. 根据提示修复问题
3. 重新验证

问题：链接损坏

原因：文件路径错误或文件不存在

解决方案：

1. 检查链接的目标文件是否存在
2. 修正文件路径
3. 重新验证

问题：批量生成速度慢

原因：文件数量多

解决方案：

1. 使用 --parallel 选项（如果支持）
2. 分批生成
3. 仅生成修改的文件

扩展开发

添加新 Skill

1. 在 .claude/skills/ 下创建新目录
2. 创建 SKILL.md 说明文档
3. 创建必要的模板和脚本
4. 在本 README 中添加说明

修改现有 Skill

1. 更新 SKILL.md 文档
2. 修改模板或脚本
3. 更新示例文档
4. 测试修改后的功能

贡献指南

报告问题

在 GitHub Issues 中报告问题，包含：

• 使用的 skill 名称
• 输入参数
• 预期结果
• 实际结果
• 错误信息

提交改进

1. Fork 项目
2. 创建功能分支
3. 提交修改
4. 创建 Pull Request

版本历史

• v1.0.0 (2025-01-XX) - 初始版本
  • 5 个核心 skills
  • 3 个共享脚本
  • 完整的文档和示例

许可证

与 GFramework 项目保持一致。

联系方式

如有问题或建议，请通过以下方式联系：

• GitHub Issues
• 项目讨论区

---

注意：本 skills 系统专为 GFramework 项目设计，使用前请确保了解项目结构和文档规范。