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

VitePress 教程生成

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

用途

此 skill 用于生成结构化的分步教程，适用于：

• 框架入门教程
• 功能实现教程
• 最佳实践演示
• 问题解决方案

调用方式

/vitepress-tutorial <教程主题>

示例：

/vitepress-tutorial "创建第一个 System"
/vitepress-tutorial "实现自定义命令"
/vitepress-tutorial "使用事件系统"

工作流程

1. 收集需求

   • 询问用户教程主题
   • 确定学习目标
   • 了解前置知识要求

2. 设计教程步骤

   • 将任务分解为 3-7 个步骤
   • 每步聚焦一个具体任务
   • 确保步骤之间逻辑连贯

3. 生成教程内容

   • 根据 template.md 创建文档框架
   • 为每步编写详细说明和代码
   • 添加完整的可运行代码
   • 说明预期结果

4. 确定输出路径

   • 保存到 docs/zh-CN/tutorials/
   • 文件名使用小写加连字符

5. 更新导航配置

   • 在 VitePress 侧边栏中添加新教程

输出规范

Frontmatter 格式

---
title: 教程标题
description: 简短描述（1 句话说明学习内容）
---

文档结构

1. 学习目标：完成教程后能够掌握的技能
2. 前置条件：需要的前置知识和环境
3. 步骤 1-N：分步说明（3-7 步）
4. 完整代码：汇总所有代码
5. 运行结果：预期输出和效果
6. 下一步：后续学习建议

步骤格式

每个步骤应包含：

• 步骤标题（简短、动词开头）
• 步骤说明（为什么要这样做）
• 代码示例（完整且可运行）
• 代码解释（关键部分的说明）

示例：

## 步骤 1：创建 Model 类

首先，我们需要创建一个 Model 来存储玩家数据。Model 负责管理应用的数据和状态。

\`\`\`csharp
using GFramework.Core.Abstractions.model;
using GFramework.Core.Abstractions.property;

public class PlayerModel : IModel
{
    // 玩家名称（可绑定属性）
    public BindableProperty<string> Name { get; } = new("Player");

    // 玩家生命值
    public BindableProperty<int> Health { get; } = new(100);

    // 玩家金币
    public BindableProperty<int> Gold { get; } = new(0);

    public void Init() { }
}
\`\`\`

**代码说明**：
- `BindableProperty<T>` 是可绑定属性，值变化时会自动通知监听者
- `Init()` 方法在 Model 注册到架构时被调用
- 使用属性初始化器设置默认值

模板变量

• {{TUTORIAL_TITLE}} - 教程标题
• {{TUTORIAL_DESCRIPTION}} - 简短描述
• {{LEARNING_OBJECTIVES}} - 学习目标
• {{PREREQUISITES}} - 前置条件
• {{STEP_N_TITLE}} - 步骤标题
• {{STEP_N_CONTENT}} - 步骤内容
• {{FULL_CODE}} - 完整代码
• {{EXPECTED_OUTPUT}} - 预期输出
• {{NEXT_STEPS}} - 下一步建议

示例输出

参考 examples/tutorial-example.md，该示例基于现有的教程文档创建。

内容要求

学习目标

• 使用列表格式
• 3-5 个具体的学习目标
• 使用"能够..."句式

示例：

## 学习目标

完成本教程后，你将能够：
- 创建自定义的 Model 类
- 在架构中注册 Model
- 从 Controller 中访问 Model
- 使用可绑定属性管理数据

前置条件

• 列出必需的知识
• 说明环境要求
• 提供相关文档链接

示例：

## 前置条件

- 已安装 GFramework.Core NuGet 包
- 了解 C# 基础语法
- 阅读过[架构概览](/zh-CN/getting-started)

步骤内容

• 每步 100-300 字说明
• 包含完整的代码示例
• 解释关键代码的作用
• 使用注释标注重要部分

完整代码

• 汇总所有步骤的代码
• 确保可以直接复制运行
• 包含必要的 using 语句
• 添加文件结构说明

运行结果

• 描述预期的输出
• 如果有界面，提供截图或描述
• 说明如何验证结果正确

下一步

• 推荐 2-3 个后续教程
• 提供相关文档链接
• 建议进阶学习方向

写作风格

语气

• 友好、鼓励性
• 使用第二人称（"你"）
• 避免假设读者已有高级知识

步骤说明

• 使用主动语态
• 步骤标题使用动词开头
• 说明"为什么"而不仅是"怎么做"

代码示例

• 完整且可运行
• 包含详细注释
• 使用有意义的变量名
• 遵循项目代码风格

配置选项

教程难度

# 初学者（更多解释，简单示例）
/vitepress-tutorial "创建第一个 System" --level beginner

# 中级（平衡解释和复杂度）
/vitepress-tutorial "实现自定义命令" --level intermediate

# 高级（简洁说明，复杂示例）
/vitepress-tutorial "架构模块开发" --level advanced

步骤数量

# 指定步骤数量（3-7 步）
/vitepress-tutorial "使用事件系统" --steps 5

前置条件

1. 了解教程主题的基本概念
2. 能够访问相关代码文件
3. 了解目标受众的知识水平

相关 Skills

• /vitepress-api-doc - 生成 API 参考文档
• /vitepress-guide - 生成功能指南
• /vitepress-validate - 验证生成的文档

最佳实践

1. 从简单开始：第一步应该是最简单的操作
2. 逐步增加复杂度：每步在前一步基础上增加新内容
3. 提供完整代码：确保每步的代码都可以运行
4. 解释关键概念：不要假设读者已经了解所有术语
5. 测试教程：确保按照步骤操作能够得到预期结果

故障排除

问题：步骤过多，教程太长

解决方案：将教程拆分为多个小教程，或合并相似的步骤

问题：代码示例不完整

解决方案：在"完整代码"章节提供所有文件的完整代码

问题：读者反馈步骤不清晰

解决方案：增加更多说明，使用截图或图表辅助

版本历史

• v1.0.0 - 初始版本，支持分步教程生成