refactor(scripts): 重构脚本以使用共享模块配置

- 将模块配置提取到共享的 module-config.sh 文件中
- 在 batch-generate.sh 中使用 get_source_dir 和 is_valid_module 函数
- 更新可用模块列表显示为动态获取
- 在 generate-examples.sh 中添加命名空间参数和详细的示例生成指南
- 优化 update-vitepress-nav.sh 中的用户界面和添加重复检查
- 修改 validate-all.sh 中的代码块验证以避免中断流程
- 改进 validate-frontmatter.sh 中的 frontmatter 检测逻辑
- 将 find 命令结果存储为数组以提高处理准确性

.claude/skills/_shared/module-config.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# 共享的模块配置
+# 用于统一管理 GFramework 项目的模块映射关系
+
+# 根据模块名获取源代码目录
+get_source_dir() {
+    local MODULE="$1"
+    case "$MODULE" in
+        Core)
+            echo "GFramework.Core"
+            ;;
+        Game)
+            echo "GFramework.Game"
+            ;;
+        Godot)
+            echo "GFramework.Godot"
+            ;;
+        SourceGenerators)
+            echo "GFramework.SourceGenerators"
+            ;;
+        *)
+            echo ""
+            return 1
+            ;;
+    esac
+}
+
+# 根据模块名获取文档输出目录
+get_docs_dir() {
+    local MODULE="$1"
+    case "$MODULE" in
+        Core)
+            echo "docs/zh-CN/api-reference/core"
+            ;;
+        Game)
+            echo "docs/zh-CN/api-reference/game"
+            ;;
+        Godot)
+            echo "docs/zh-CN/api-reference/godot"
+            ;;
+        SourceGenerators)
+            echo "docs/zh-CN/api-reference/source-generators"
+            ;;
+        *)
+            echo ""
+            return 1
+            ;;
+    esac
+}
+
+# 根据命名空间推断模块名
+infer_module_from_namespace() {
+    local NAMESPACE="$1"
+    if [[ "$NAMESPACE" == GFramework.Core* ]]; then
+        echo "Core"
+    elif [[ "$NAMESPACE" == GFramework.Game* ]]; then
+        echo "Game"
+    elif [[ "$NAMESPACE" == GFramework.Godot* ]]; then
+        echo "Godot"
+    elif [[ "$NAMESPACE" == GFramework.SourceGenerators* ]]; then
+        echo "SourceGenerators"
+    else
+        echo ""
+        return 1
+    fi
+}
+
+# 获取所有可用模块列表
+get_all_modules() {
+    echo "Core Game Godot SourceGenerators"
+}
+
+# 验证模块名是否有效
+is_valid_module() {
+    local MODULE="$1"
+    case "$MODULE" in
+        Core|Game|Godot|SourceGenerators)
+            return 0
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+}

.claude/skills/_shared/scripts/generate-examples.sh

@@ -1,33 +1,109 @@
 #!/bin/bash
 # 生成代码示例辅助脚本
-# 用法: generate-examples.sh <类型> <类名>
+# 用法: generate-examples.sh <类型> <类名> [命名空间]
 
 set -e
 
 TYPE="$1"  # class/interface/enum
 CLASS_NAME="$2"
+NAMESPACE="$3"
 
 if [ -z "$TYPE" ] || [ -z "$CLASS_NAME" ]; then
-    echo "用法: $0 <类型> <类名>"
+    echo "用法: $0 <类型> <类名> [命名空间]"
     echo "类型: class, interface, enum"
     exit 1
 fi
 
-echo "生成 $CLASS_NAME 的示例代码..."
+echo "=========================================="
+echo "代码示例生成指南"
+echo "=========================================="
 echo "类型: $TYPE"
+echo "类名: $CLASS_NAME"
+if [ -n "$NAMESPACE" ]; then
+    echo "命名空间: $NAMESPACE"
+fi
+echo ""
 
-# 注意: 此脚本仅输出提示信息
+# 根据类型提供示例生成指南
-# 实际的示例代码生成由 AI 根据 API 签名和现有教程风格完成
-
 case "$TYPE" in
     class)
-        echo "提示: 为类生成示例，包括实例化、方法调用、属性访问"
+        echo "## 类示例生成建议"
+        echo ""
+        echo "1. 基本用法示例:"
+        echo "   - 实例化对象"
+        echo "   - 调用主要方法"
+        echo "   - 访问公共属性"
+        echo ""
+        echo "2. 常见场景示例:"
+        echo "   - 实际应用案例"
+        echo "   - 与其他组件的集成"
+        echo ""
+        echo "3. 高级用法示例（如适用）:"
+        echo "   - 复杂配置"
+        echo "   - 扩展和自定义"
+        echo ""
+        echo "示例模板:"
+        echo '```csharp'
+        echo "// 创建实例"
+        echo "var instance = new $CLASS_NAME();"
+        echo ""
+        echo "// 使用主要功能"
+        echo "instance.MainMethod();"
+        echo '```'
         ;;
     interface)
-        echo "提示: 为接口生成示例，包括实现类和使用方式"
+        echo "## 接口示例生成建议"
+        echo ""
+        echo "1. 实现接口:"
+        echo "   - 展示如何实现该接口"
+        echo "   - 实现所有必需成员"
+        echo ""
+        echo "2. 使用接口:"
+        echo "   - 通过接口类型使用实例"
+        echo "   - 依赖注入场景"
+        echo ""
+        echo "示例模板:"
+        echo '```csharp'
+        echo "// 实现接口"
+        echo "public class My$CLASS_NAME : $CLASS_NAME"
+        echo "{"
+        echo "    // 实现成员"
+        echo "}"
+        echo ""
+        echo "// 使用接口"
+        echo "$CLASS_NAME instance = new My$CLASS_NAME();"
+        echo '```'
         ;;
     enum)
-        echo "提示: 为枚举生成示例，包括值比较和 switch 语句"
+        echo "## 枚举示例生成建议"
+        echo ""
+        echo "1. 基本用法:"
+        echo "   - 枚举值赋值"
+        echo "   - 值比较"
+        echo ""
+        echo "2. Switch 语句:"
+        echo "   - 根据枚举值执行不同逻辑"
+        echo ""
+        echo "3. 枚举转换:"
+        echo "   - 字符串转枚举"
+        echo "   - 枚举转整数"
+        echo ""
+        echo "示例模板:"
+        echo '```csharp'
+        echo "// 使用枚举值"
+        echo "var value = $CLASS_NAME.SomeValue;"
+        echo ""
+        echo "// Switch 语句"
+        echo "switch (value)"
+        echo "{"
+        echo "    case $CLASS_NAME.Value1:"
+        echo "        // 处理逻辑"
+        echo "        break;"
+        echo "    case $CLASS_NAME.Value2:"
+        echo "        // 处理逻辑"
+        echo "        break;"
+        echo "}"
+        echo '```'
         ;;
     *)
         echo "错误: 不支持的类型: $TYPE"
@@ -35,4 +111,11 @@ case "$TYPE" in
         ;;
 esac
 
+echo ""
+echo "注意事项:"
+echo "- 使用项目的命名约定"
+echo "- 包含必要的 using 语句"
+echo "- 确保示例代码可以编译运行"
+echo "- 参考现有教程的代码风格"
+
 exit 0

.claude/skills/_shared/scripts/update-vitepress-nav.sh

@@ -10,7 +10,7 @@ CONFIG_FILE="docs/.vitepress/config.mts"
 
 if [ -z "$DOC_PATH" ] || [ -z "$DOC_TITLE" ]; then
     echo "用法: $0 <文档路径> <文档标题>"
-    echo "示例: $0 /zh-CN/api-reference/core/architecture.md Architecture"
+    echo "示例: $0 /zh-CN/api-reference/core/architecture Architecture"
     exit 1
 fi
 
@@ -27,16 +27,31 @@ if [ -z "$MODULE" ]; then
     exit 1
 fi
 
-echo "正在更新 VitePress 配置..."
+echo "=========================================="
-echo "  模块: $MODULE"
+echo "VitePress 导航配置更新"
-echo "  路径: $DOC_PATH"
+echo "=========================================="
-echo "  标题: $DOC_TITLE"
+echo "模块: $MODULE"
+echo "路径: $DOC_PATH"
+echo "标题: $DOC_TITLE"
+echo ""
 
-# 注意: 此脚本仅输出提示信息
+# 检查配置文件中是否已存在该路径
-# 实际的配置更新由 AI 直接编辑 config.mts 文件完成
+if grep -q "link: '$DOC_PATH'" "$CONFIG_FILE"; then
-# 因为 TypeScript 配置文件的复杂性，使用脚本解析和修改容易出错
+    echo "✓ 该文档已存在于导航配置中"
+    exit 0
+fi
 
-echo "提示: 请手动更新 $CONFIG_FILE 中的侧边栏配置"
+echo "提示: 需要在 VitePress 配置中添加新条目"
-echo "或者让 AI 使用 Edit 工具直接修改配置文件"
+echo ""
+echo "建议的配置条目:"
+echo "{ text: '$DOC_TITLE', link: '$DOC_PATH' }"
+echo ""
+echo "请使用以下方式之一更新配置:"
+echo "1. 让 AI 使用 Edit 工具直接修改 $CONFIG_FILE"
+echo "2. 手动编辑配置文件并添加上述条目到对应的 sidebar 部分"
+echo ""
+
+# 输出相关的 sidebar 配置路径
+echo "相关的 sidebar 配置路径: '/zh-CN/$MODULE/'"
 
 exit 0

.claude/skills/vitepress-batch-api/scripts/batch-generate.sh

@@ -4,33 +4,27 @@
 
 set -e
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../../_shared/module-config.sh
+source "$SCRIPT_DIR/../../_shared/module-config.sh"
+
 MODULE="$1"
 
 if [ -z "$MODULE" ]; then
     echo "用法: $0 <模块名>"
-    echo "可用模块: Core, Game, Godot, SourceGenerators"
+    echo "可用模块: $(get_all_modules)"
     exit 1
 fi
 
-# 确定源代码目录
+# 验证模块名
-case "$MODULE" in
+if ! is_valid_module "$MODULE"; then
-    Core)
+    echo "错误: 未知的模块: $MODULE"
-        SOURCE_DIR="GFramework.Core"
+    echo "可用模块: $(get_all_modules)"
-        ;;
+    exit 1
-    Game)
+fi
-        SOURCE_DIR="GFramework.Game"
+
-        ;;
+# 获取源代码目录
-    Godot)
+SOURCE_DIR=$(get_source_dir "$MODULE")
-        SOURCE_DIR="GFramework.Godot"
-        ;;
-    SourceGenerators)
-        SOURCE_DIR="GFramework.SourceGenerators"
-        ;;
-    *)
-        echo "错误: 未知的模块: $MODULE"
-        exit 1
-        ;;
-esac
 
 if [ ! -d "$SOURCE_DIR" ]; then
     echo "错误: 源代码目录不存在: $SOURCE_DIR"
@@ -43,14 +37,14 @@ echo "=========================================="
 echo ""
 
 # 查找所有 C# 文件
-FILES=$(find "$SOURCE_DIR" -name "*.cs" -type f \
+mapfile -t FILES < <(find "$SOURCE_DIR" -name "*.cs" -type f \
     ! -name "*.g.cs" \
     ! -name "*.Designer.cs" \
     ! -name "*Test.cs" \
     ! -name "*.Tests.cs" \
     ! -name "AssemblyInfo.cs")
 
-FILE_COUNT=$(echo "$FILES" | wc -l)
+FILE_COUNT=${#FILES[@]}
 echo "找到 $FILE_COUNT 个文件"
 echo ""
 
@@ -58,7 +52,7 @@ GENERATED=0
 SKIPPED=0
 FAILED=0
 
-for FILE in $FILES; do
+for FILE in "${FILES[@]}"; do
     echo "处理: $FILE"
 
     # 检查是否包含公共类型

.claude/skills/vitepress-validate/scripts/validate-all.sh

@@ -63,7 +63,7 @@ for FILE in "${FILES[@]}"; do
     fi
 
     # 3. 代码块验证
-    OUTPUT=$(bash "$SCRIPT_DIR/validate-code-blocks.sh" "$FILE" 2>&1)
+    OUTPUT=$(bash "$SCRIPT_DIR/validate-code-blocks.sh" "$FILE" 2>&1 || true)
     if echo "$OUTPUT" | grep -q "✗"; then
         FILE_ERRORS=$((FILE_ERRORS + 1))
     fi

.claude/skills/vitepress-validate/scripts/validate-frontmatter.sh

@@ -18,8 +18,8 @@ fi
 
 echo "验证 Frontmatter: $FILE"
 
-# 检查是否有 Frontmatter
+# 检查是否有 Frontmatter（限制在前几行，避免匹配正文中的 '---'）
-if ! grep -q "^---$" "$FILE"; then
+if ! head -n 5 "$FILE" | grep -q "^---$"; then
     echo "✗ 错误: 文件缺少 Frontmatter"
     exit 1
 fi