mirror of https://github.com/GeWuYou/GFramework.git synced 2026-03-22 10:34:30 +08:00

GeWuYou bb449259d3 feat(docs): 添加 VitePress 文档生成技能系统

- 新增 .claude/skills 目录及完整的文档生成技能系统
- 添加批量 API 文档生成脚本支持模块化文档创建
- 添加 API 文档、功能指南和教程生成模板与示例
- 添加 C# XML 注释解析和代码示例生成工具
- 添加文档验证和导航更新脚本确保质量
- 更新 .gitignore 配置排除本地设置文件

2026-02-25 09:28:33 +08:00

5.7 KiB

Raw Blame History

VitePress 功能指南生成

生成功能模块的使用指南文档，包括概念说明、用法示例和最佳实践。

用途

此 skill 用于生成结构化的功能指南文档，适用于：

核心功能模块的使用说明
设计模式和架构概念
系统功能的详细介绍
最佳实践和常见问题

调用方式

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

示例：

/vitepress-guide "事件系统" Core
/vitepress-guide "IoC 容器" Core
/vitepress-guide "Godot 节点扩展" Godot

工作流程

收集需求
- 询问用户指南主题
- 确定目标受众（初学者/进阶/专家）
- 了解重点内容（概念/用法/最佳实践）
搜索相关资源
- 搜索相关代码文件
- 查找现有文档
- 识别相关类型和接口
生成指南结构
- 根据 template.md 创建文档框架
- 填充概述和核心概念
- 添加基本用法和高级用法
- 补充最佳实践和常见问题
生成代码示例
- 基本用法示例（最简单的场景）
- 常见场景示例（实际应用）
- 高级用法示例（复杂配置）
确定输出路径
- 保存到 docs/zh-CN/<模块>/
- 文件名使用小写加连字符（如 event-system.md）
更新导航配置
- 在 VitePress 侧边栏中添加新指南

输出规范

Frontmatter 格式

---
title: 指南标题
description: 简短描述（1-2 句话）
---

文档结构

概述：功能的简介和用途
核心概念：关键概念和术语解释
基本用法：最简单的使用方式
高级用法：复杂场景和配置
最佳实践：推荐的使用方式
常见问题：FAQ 和故障排除

章节示例

概述：

## 概述

事件系统提供了一种松耦合的组件间通信机制。通过事件，不同的组件可以在不直接引用彼此的情况下进行交互。

**主要特性**：
- 类型安全的事件
- 自动内存管理
- 支持事件优先级
- 线程安全

核心概念：

## 核心概念

### 事件类型

事件是一个普通的 C# 类，用于携带事件数据：

\`\`\`csharp
public class PlayerDiedEvent
{
    public int PlayerId { get; set; }
    public string Reason { get; set; }
}
\`\`\`

### 事件发送

通过架构发送事件：

\`\`\`csharp
this.SendEvent(new PlayerDiedEvent
{
    PlayerId = 1,
    Reason = "Fall damage"
});
\`\`\`

### 事件监听

注册事件监听器：

\`\`\`csharp
this.RegisterEvent<PlayerDiedEvent>(OnPlayerDied);
\`\`\`

模板变量

{{GUIDE_TITLE}} - 指南标题
{{GUIDE_DESCRIPTION}} - 简短描述
{{OVERVIEW}} - 概述内容
{{CORE_CONCEPTS}} - 核心概念
{{BASIC_USAGE}} - 基本用法
{{ADVANCED_USAGE}} - 高级用法
{{BEST_PRACTICES}} - 最佳实践
{{FAQ}} - 常见问题

示例输出

参考 examples/guide-example.md，该示例基于现有的 IoC 容器文档创建。

内容要求

概述部分

1-2 段简介
列出主要特性（3-5 个）
说明适用场景

核心概念部分

使用三级标题（###）分隔不同概念
每个概念包含简短说明和代码示例
解释关键术语

基本用法部分

提供完整的可运行示例
从最简单的场景开始
逐步增加复杂度
包含必要的 using 语句

高级用法部分

展示复杂场景
说明配置选项
提供性能优化建议

最佳实践部分

使用编号列表
每条实践包含简短说明
提供正反示例（✓ 推荐 / ✗ 不推荐）

常见问题部分

使用问答格式
提供具体的解决方案
包含相关链接

写作风格

语气

友好、专业
使用第二人称（"你"）
避免过于技术化的术语

代码示例

完整且可运行
包含注释说明关键步骤
使用有意义的变量名
遵循项目代码风格

格式

使用 Markdown 标准格式
代码块使用语法高亮
重要内容使用粗体或引用块
适当使用列表和表格

配置选项

目标受众

# 初学者（更多解释，简单示例）
/vitepress-guide "事件系统" Core --audience beginner

# 进阶（平衡解释和示例）
/vitepress-guide "事件系统" Core --audience intermediate

# 专家（简洁说明，复杂示例）
/vitepress-guide "事件系统" Core --audience expert

重点内容

# 侧重概念
/vitepress-guide "事件系统" Core --focus concepts

# 侧重用法
/vitepress-guide "事件系统" Core --focus usage

# 侧重最佳实践
/vitepress-guide "事件系统" Core --focus best-practices

前置条件

了解指南主题的基本概念
能够访问相关代码文件
了解项目的代码风格和术语

最佳实践

先搜索后编写：查看现有文档和代码，保持一致性
使用真实示例：基于项目实际代码创建示例
保持简洁：每个章节聚焦一个主题
提供完整代码：确保示例可以直接运行
添加交叉引用：链接到相关的 API 文档和其他指南

故障排除

问题：不确定指南应该包含哪些内容

解决方案：参考 examples/guide-example.md 和现有的指南文档

问题：代码示例过于复杂

解决方案：将复杂示例拆分为多个简单示例，逐步增加复杂度

问题：概念解释不清晰

解决方案：使用类比、图表或分步说明来辅助解释

版本历史

v1.0.0 - 初始版本，支持功能指南生成

5.7 KiB Raw Blame History Unescape Escape