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

VitePress 功能指南生成

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

用途

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

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

调用方式

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

示例：

/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 格式

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

文档结构

1. 概述：功能的简介和用途
2. 核心概念：关键概念和术语解释
3. 基本用法：最简单的使用方式
4. 高级用法：复杂场景和配置
5. 最佳实践：推荐的使用方式
6. 常见问题：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

前置条件

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 - 初始版本，支持功能指南生成