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

# VitePress 功能指南生成

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

## 用途

此 skill 用于生成结构化的功能指南文档，适用于：
- 核心功能模块的使用说明
- 设计模式和架构概念
- 系统功能的详细介绍
- 最佳实践和常见问题

## 调用方式

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

**示例**：
```bash
/vitepress-guide "事件系统" Core
/vitepress-guide "IoC 容器" Core
/vitepress-guide "Godot 节点扩展" Godot
```

## 工作流程

1. **收集需求**
   - 询问用户指南主题
   - 确定目标受众（初学者/进阶/专家）
   - 了解重点内容（概念/用法/最佳实践）

2. **搜索相关资源**
   - 搜索相关代码文件
   - 查找现有文档
   - 识别相关类型和接口

3. **生成指南结构**
   - 根据 `template.md` 创建文档框架
   - 填充概述和核心概念
   - 添加基本用法和高级用法
   - 补充最佳实践和常见问题

4. **生成代码示例**
   - 基本用法示例（最简单的场景）
   - 常见场景示例（实际应用）
   - 高级用法示例（复杂配置）

5. **确定输出路径**
   - 保存到 `docs/zh-CN/<模块>/`
   - 文件名使用小写加连字符（如 `event-system.md`）

6. **更新导航配置**
   - 在 VitePress 侧边栏中添加新指南

## 输出规范

### Frontmatter 格式

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

### 文档结构

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

### 章节示例

**概述**：
```markdown
## 概述

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

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

**核心概念**：
```markdown
## 核心概念

### 事件类型

事件是一个普通的 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 标准格式
- 代码块使用语法高亮
- 重要内容使用粗体或引用块
- 适当使用列表和表格

## 配置选项

### 目标受众

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

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

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

### 重点内容

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

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

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

## 前置条件

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

## 相关 Skills

- `/vitepress-api-doc` - 生成 API 参考文档
- `/vitepress-tutorial` - 生成分步教程
- `/vitepress-validate` - 验证生成的文档

## 最佳实践

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

## 故障排除

### 问题：不确定指南应该包含哪些内容
**解决方案**：参考 `examples/guide-example.md` 和现有的指南文档

### 问题：代码示例过于复杂
**解决方案**：将复杂示例拆分为多个简单示例，逐步增加复杂度

### 问题：概念解释不清晰
**解决方案**：使用类比、图表或分步说明来辅助解释

## 版本历史

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