@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.10

package/skills/meritdata-platform-2nd-dev-check/scripts/check-platform.sh

@@ -0,0 +1,212 @@
+#!/bin/bash
+# =============================================================================
+# 检查基础设施：MySQL / Redis / Nacos / 平台服务
+# 通用化：从环境变量读取所有项目特定配置
+# =============================================================================
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+# 加载环境变量（从项目根 .env 或 ~/.bashrc）
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+
+# 第 1 步：自动从 Nacos 导出目录加载真实配置
+if [ -f "$SCRIPT_DIR/load-config.sh" ]; then
+    source "$SCRIPT_DIR/load-config.sh"
+fi
+
+# 第 2 步：加载项目根 .env
+if [ -f "$PROJECT_ROOT/.env" ]; then
+    source "$PROJECT_ROOT/.env"
+fi
+
+PASS=0
+FAIL=0
+WARN=0
+
+print_result() {
+    local status=$1
+    local name=$2
+    local detail=$3
+    case $status in
+        PASS) echo -e "${GREEN}✅${NC} $name: $detail"; PASS=$((PASS+1));;
+        FAIL) echo -e "${RED}❌${NC} $name: $detail"; FAIL=$((FAIL+1));;
+        WARN) echo -e "${YELLOW}⚠️${NC} $name: $detail"; WARN=$((WARN+1));;
+    esac
+}
+
+# 必需环境变量检查
+check_env() {
+    local var_name=$1
+    if [ -z "${!var_name}" ]; then
+        print_result FAIL "环境变量 $var_name" "未设置"
+        return 1
+    fi
+    return 0
+}
+
+echo -e "${BLUE}=== 0. 环境变量检查 ===${NC}"
+for v in MYSQL_HOST MYSQL_PORT MYSQL_USER MYSQL_PASSWORD \
+         REDIS_HOST REDIS_PORT REDIS_PASSWORD \
+         NACOS_HOST NACOS_PORT NACOS_USER NACOS_PASSWORD \
+         APP_NAME APP_PORT; do
+    if ! check_env "$v"; then
+        echo "请设置环境变量后重试："
+        echo "  export $v=<value>"
+        exit 1
+    fi
+done
+print_result PASS "环境变量" "13 个都已设置"
+
+echo ""
+echo -e "${BLUE}=== 1. MySQL 检查 ===${NC}"
+if mysql -h "$MYSQL_HOST" -P "$MYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASSWORD" -e "SELECT 1;" >/dev/null 2>&1; then
+    VERSION=$(mysql -h "$MYSQL_HOST" -P "$MYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASSWORD" -e "SELECT VERSION();" -s 2>/dev/null | tail -1)
+    print_result PASS "MySQL" "可连接，版本 $VERSION"
+
+    # 检查 cloud 库
+    if mysql -h "$MYSQL_HOST" -P "$MYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASSWORD" -e "USE cloud; SHOW TABLES;" >/dev/null 2>&1; then
+        TABLE_COUNT=$(mysql -h "$MYSQL_HOST" -P "$MYSQL_PORT" -u "$MYSQL_USER" -p"$MYSQL_PASSWORD" -e "SELECT COUNT(*) FROM information_schema.TABLES WHERE TABLE_SCHEMA='cloud';" -s 2>/dev/null | tail -1)
+        if [ "$TABLE_COUNT" -ge 130 ]; then
+            print_result PASS "cloud 库" "存在，$TABLE_COUNT 张表"
+        else
+            print_result WARN "cloud 库" "存在但表数较少($TABLE_COUNT < 130)"
+        fi
+    else
+        print_result FAIL "cloud 库" "不存在"
+    fi
+else
+    print_result FAIL "MySQL" "$MYSQL_HOST:$MYSQL_PORT 不可达"
+fi
+
+echo ""
+echo -e "${BLUE}=== 2. Redis 检查 ===${NC}"
+# 测试 Redis 端口（兼容无 redis-cli 的环境）
+if (timeout 3 bash -c "echo -e 'PING\r\nQUIT\r\n' >/dev/tcp/$REDIS_HOST/$REDIS_PORT" 2>/dev/null) || \
+   (timeout 3 redis-cli -h "$REDIS_HOST" -p "$REDIS_PORT" -a "$REDIS_PASSWORD" PING 2>/dev/null) || \
+   (python3 -c "import socket; s=socket.socket(); s.settimeout(2); s.connect(('$REDIS_HOST',$REDIS_PORT)); print('OK')" 2>/dev/null) || \
+   (powershell.exe -Command "Test-NetConnection -ComputerName $REDIS_HOST -Port $REDIS_PORT -InformationLevel Quiet" 2>/dev/null | grep -q "True"); then
+    print_result PASS "Redis 端口" "$REDIS_HOST:$REDIS_PORT 可达"
+
+    # 尝试用 redis-cli 获取版本（如果可用）
+    if command -v redis-cli >/dev/null 2>&1; then
+        VERSION=$(redis-cli -h "$REDIS_HOST" -p "$REDIS_PORT" -a "$REDIS_PASSWORD" INFO server 2>&1 | grep "redis_version" | cut -d: -f2 | tr -d '\r')
+        DBSIZE=$(redis-cli -h "$REDIS_HOST" -p "$REDIS_PORT" -a "$REDIS_PASSWORD" DBSIZE 2>&1 | tr -d '\r')
+        print_result PASS "Redis 详情" "$VERSION，DBSIZE=$DBSIZE"
+
+        CACHE_HIT=$(redis-cli -h "$REDIS_HOST" -p "$REDIS_PORT" -a "$REDIS_PASSWORD" KEYS "CACHE_SESSION_LIST_KEY" 2>&1 | head -1)
+        if [ -n "$CACHE_HIT" ]; then
+            print_result PASS "CACHE_SESSION_LIST_KEY" "存在"
+        else
+            print_result WARN "CACHE_SESSION_LIST_KEY" "不存在（可能首次启动）"
+        fi
+    else
+        print_result WARN "Redis" "端口可达，但 redis-cli 不在 PATH（无法查版本）"
+    fi
+else
+    print_result FAIL "Redis" "$REDIS_HOST:$REDIS_PORT 不可达"
+fi
+
+echo ""
+echo -e "${BLUE}=== 3. Nacos 检查 ===${NC}"
+# 测试 Nacos 认证（用 GET /v1/auth/users）
+if curl -sS -u "$NACOS_USER:$NACOS_PASSWORD" "http://$NACOS_HOST:$NACOS_PORT/nacos/v1/auth/users?pageNo=1&pageSize=1" >/dev/null 2>&1; then
+    print_result PASS "Nacos" "$NACOS_HOST:$NACOS_PORT 可达，$NACOS_USER 认证通过"
+else
+    # 试 admin 凭据
+    if curl -sS -u "$NACOS_USER:$NACOS_PASSWORD" "http://$NACOS_HOST:$NACOS_PORT/nacos/" -w "%{http_code}" --max-time 3 -o /dev/null 2>&1 | grep -qE "200|404"; then
+        print_result WARN "Nacos" "$NACOS_HOST:$NACOS_PORT 可达但凭据 $NACOS_USER 需调整"
+    else
+        print_result FAIL "Nacos" "$NACOS_HOST:$NACOS_PORT 不可达"
+    fi
+fi
+
+# 检查 6 份 common 配置（通用清单）
+if curl -sS -u "$NACOS_USER:$NACOS_PASSWORD" "http://$NACOS_HOST:$NACOS_PORT/nacos/v1/auth/users?pageNo=1&pageSize=1" >/dev/null 2>&1; then
+    COMMON_CONFIGS=(
+        "common.properties"
+        "common-cache.properties"
+        "common-server.properties"
+        "common-cloud-system-cas.properties"
+        "common-cloud-system-manage.properties"
+        "common-datasource.properties"
+    )
+
+    # 修复 2026-07-27：原 API 路径 nacos/v3/console/cs/config 在 Nacos 2.x 返回 403
+    # 改用 v1 API（兼容性更好），并增加本地 Nacos 导出目录副本 fallback
+    # 当 Nacos 不可达或凭据异常时，能从本地副本验证（适用于离线开发环境）
+    NACOS_EXPORT_DIR="$PROJECT_ROOT/Nacos 导出目录/DEFAULT_GROUP"
+
+    for cfg in "${COMMON_CONFIGS[@]}"; do
+        # 优先尝试 Nacos v1 API
+        RESP=$(curl -sS -u "$NACOS_USER:$NACOS_PASSWORD" \
+            "http://$NACOS_HOST:$NACOS_PORT/nacos/v1/cs/config?dataId=${cfg}&group=DEFAULT_GROUP" 2>&1)
+        if echo "$RESP" | grep -q "\"dataId\":\"${cfg}\""; then
+            print_result PASS "${cfg}" "存在（Nacos v1 API）"
+        elif [ -f "$NACOS_EXPORT_DIR/${cfg}" ]; then
+            # Nacos 不可达或返 403，fallback 到本地副本
+            print_result PASS "${cfg}" "存在（本地副本 $NACOS_EXPORT_DIR/${cfg}）"
+        else
+            print_result FAIL "${cfg}" "Nacos 和本地副本都不存在"
+        fi
+    done
+
+    # 本工程专属配置
+    APP_CONFIG="common-${APP_NAME}.properties"
+    RESP=$(curl -sS -u "$NACOS_USER:$NACOS_PASSWORD" \
+        "http://$NACOS_HOST:$NACOS_PORT/nacos/v1/cs/config?dataId=${APP_CONFIG}&group=DEFAULT_GROUP" 2>&1)
+    if echo "$RESP" | grep -q "\"dataId\":\"${APP_CONFIG}\""; then
+        print_result PASS "${APP_CONFIG}" "存在（Nacos v1 API）"
+    elif [ -f "$NACOS_EXPORT_DIR/${APP_CONFIG}" ]; then
+        print_result PASS "${APP_CONFIG}" "存在（本地副本）"
+    else
+        print_result WARN "${APP_CONFIG}" "缺失（业务开发时创建）"
+    fi
+fi
+
+echo ""
+echo -e "${BLUE}=== 4. 平台服务检查 ===${NC}"
+# 4 个平台服务的常见端口（按美林 6.x 标准部署）
+declare -A SERVICES=(
+    ["cloud-system-gateway"]="8081"
+    ["cloud-system-manage"]="8085"
+    ["cloud-system-bpm-engine"]="8089"
+    ["cloud-system-job"]="8086"
+)
+
+for svc in "${!SERVICES[@]}"; do
+    port="${SERVICES[$svc]}"
+    # 检查 Nacos 注册
+    REGISTERED=$(curl -sS -u "$NACOS_USER:$NACOS_PASSWORD" "http://$NACOS_HOST:$NACOS_PORT/nacos/v1/ns/instance/list?serviceName=${svc}" 2>&1)
+    if echo "$REGISTERED" | grep -q '"ip"'; then
+        COUNT=$(echo "$REGISTERED" | grep -o '"ip"' | wc -l)
+        print_result PASS "${svc}" "Nacos 已注册，$COUNT 个实例（端口 $port）"
+    elif echo "$REGISTERED" | grep -q "403\|Forbidden"; then
+        print_result WARN "${svc}" "Nacos 凭据 403（仅检查端口）"
+    else
+        print_result FAIL "${svc}" "未在 Nacos 注册"
+    fi
+
+    # 检查端口可达
+    if curl -sSI "http://localhost:${port}/" -w "%{http_code}" --max-time 3 -o /dev/null 2>&1 | grep -qE "200|302|404|401"; then
+        print_result PASS "${svc} 端口" "${port} 可达"
+    else
+        print_result WARN "${svc} 端口" "${port} 不可达"
+    fi
+done
+
+echo ""
+echo -e "${BLUE}=== 总结 ===${NC}"
+echo -e "通过: ${GREEN}$PASS${NC}"
+echo -e "警告: ${YELLOW}$WARN${NC}"
+echo -e "失败: ${RED}$FAIL${NC}"
+
+if [ $FAIL -gt 0 ]; then
+    exit 1
+fi
+exit 0

package/skills/meritdata-platform-2nd-dev-check/scripts/load-config.sh

@@ -0,0 +1,189 @@
+#!/bin/bash
+# =============================================================================
+# 自动从项目内 Nacos 导出目录（默认 Nacos 导出目录/DEFAULT_GROUP/，可自定义）读取真实配置
+# 优先级：用户 export 的环境变量 > Nacos 导出目录中的值 > 报错
+# =============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+# 默认 Nacos 导出目录（可通过环境变量 NACOS_EXPORT_DIR 自定义）
+NACOS_EXPORT_DIR="${NACOS_EXPORT_DIR:-$PROJECT_ROOT/Nacos 导出目录/DEFAULT_GROUP}"
+
+# 加载项目根 .env（如果存在，优先级最高）
+if [ -f "$PROJECT_ROOT/.env" ]; then
+    source "$PROJECT_ROOT/.env"
+fi
+
+# 读取 Nacos 导出目录文件的辅助函数（自动处理不存在的 key）
+read_nacos_prop() {
+    local file=$1
+    local key=$2
+    # 关闭 set -e 让 grep 无匹配时返回空而不是失败
+    set +e
+    local val=$(grep -E "^${key}\s*=" "$NACOS_EXPORT_DIR/$file" 2>/dev/null | \
+        head -1 | \
+        sed -E "s/^${key}\s*=\s*//" | \
+        sed -E 's/\s*$//' | \
+        sed -E 's/\\([\\$])/\1/g')
+    set -e
+    echo "$val"
+}
+
+# 解析 JDBC URL：jdbc:mysql://host:port/database?params
+parse_jdbc_url() {
+    local url=$1
+    # 提取主机
+    local host=$(echo "$url" | sed -E 's|^jdbc:[a-z]+://([^:]+):.*|\1|')
+    # 提取端口
+    local port=$(echo "$url" | sed -E 's|^jdbc:[a-z]+://[^:]+:([0-9]+).*|\1|')
+    # 提取数据库名
+    local db=$(echo "$url" | sed -E 's|^jdbc:[a-z]+://[^:]+:[0-9]+/([^?]+).*|\1|')
+
+    # 设置（仅当用户未设置）
+    [ -z "$MYSQL_HOST" ] && [ -n "$host" ] && export MYSQL_HOST="$host" || true
+    [ -z "$MYSQL_PORT" ] && [ -n "$port" ] && export MYSQL_PORT="$port" || true
+    [ -z "$MYSQL_DATABASE" ] && [ -n "$db" ] && export MYSQL_DATABASE="$db" || true
+}
+
+# 解析 Redis serve-hosts：localhost:6380
+parse_redis_hosts() {
+    local hosts=$1
+    # 取第一个 host:port
+    local first=$(echo "$hosts" | cut -d',' -f1)
+    local host=$(echo "$first" | cut -d':' -f1)
+    local port=$(echo "$first" | cut -d':' -f2)
+
+    [ -z "$REDIS_HOST" ] && [ -n "$host" ] && export REDIS_HOST="$host" || true
+    [ -z "$REDIS_PORT" ] && [ -n "$port" ] && export REDIS_PORT="$port" || true
+}
+
+# 从 common-datasource.properties 读取
+echo "=== 读取 common-datasource.properties ==="
+if [ -f "$NACOS_EXPORT_DIR/common-datasource.properties" ]; then
+    # 数据源类型
+    PLATFORM=$(read_nacos_prop "common-datasource.properties" "spring.jpa.database-platform")
+    [ -z "$MYSQL_PLATFORM" ] && [ -n "$PLATFORM" ] && export MYSQL_PLATFORM="$PLATFORM" || true
+
+    # JDBC URL（解析主机/端口/数据库）
+    JDBC_URL=$(read_nacos_prop "common-datasource.properties" "spring.datasource.url")
+    if [ -n "$JDBC_URL" ]; then
+        parse_jdbc_url "$JDBC_URL"
+        [ -z "$MYSQL_URL" ] && export MYSQL_URL="$JDBC_URL" || true
+    fi
+
+    # 用户名/密码（仅当用户未设置）
+    DB_USER=$(read_nacos_prop "common-datasource.properties" "spring.datasource.username")
+    [ -z "$MYSQL_USER" ] && [ -n "$DB_USER" ] && export MYSQL_USER="$DB_USER" || true
+
+    DB_PASS=$(read_nacos_prop "common-datasource.properties" "spring.datasource.password")
+    [ -z "$MYSQL_PASSWORD" ] && [ -n "$DB_PASS" ] && export MYSQL_PASSWORD="$DB_PASS" || true
+
+    # driver-class-name（用于判断数据库类型）
+    DRIVER=$(read_nacos_prop "common-datasource.properties" "spring.datasource.driver-class-name")
+    [ -z "$DB_DRIVER" ] && [ -n "$DRIVER" ] && export DB_DRIVER="$DRIVER" || true
+
+    echo "✅ 数据源：$MYSQL_HOST:$MYSQL_PORT/$MYSQL_DATABASE（$MYSQL_USER）"
+    echo "   平台：$MYSQL_PLATFORM"
+    echo "   Driver：$DB_DRIVER"
+else
+    echo "⚠️ common-datasource.properties 不存在（跳过）"
+fi
+
+# 从 common-cache.properties 读取
+echo ""
+echo "=== 读取 common-cache.properties ==="
+if [ -f "$NACOS_EXPORT_DIR/common-cache.properties" ]; then
+    # 多种可能的 Redis key
+    REDIS_HOSTS=$(read_nacos_prop "common-cache.properties" "meritdata.cloud.cache.serve-hosts")
+    REDIS_HOSTS_SPRING=$(read_nacos_prop "common-cache.properties" "spring.data.redis.host")
+
+    # 优先用 meritdata.cloud.cache.* 配置
+    if [ -n "$REDIS_HOSTS" ]; then
+        parse_redis_hosts "$REDIS_HOSTS"
+        # 密码
+        REDIS_PASS=$(read_nacos_prop "common-cache.properties" "meritdata.cloud.cache.serve-password")
+        [ -z "$REDIS_PASSWORD" ] && [ -n "$REDIS_PASS" ] && export REDIS_PASSWORD="$REDIS_PASS" || true
+        echo "✅ Redis（meritdata 配置）：$REDIS_HOST:$REDIS_PORT"
+    elif [ -n "$REDIS_HOSTS_SPRING" ]; then
+        [ -z "$REDIS_HOST" ] && export REDIS_HOST="$REDIS_HOSTS_SPRING" || true
+        REDIS_PORT_SPRING=$(read_nacos_prop "common-cache.properties" "spring.data.redis.port")
+        [ -z "$REDIS_PORT" ] && [ -n "$REDIS_PORT_SPRING" ] && export REDIS_PORT="$REDIS_PORT_SPRING" || true
+        REDIS_PASS_SPRING=$(read_nacos_prop "common-cache.properties" "spring.data.redis.password")
+        [ -z "$REDIS_PASSWORD" ] && [ -n "$REDIS_PASS_SPRING" ] && export REDIS_PASSWORD="$REDIS_PASS_SPRING" || true
+        echo "✅ Redis（spring.data 配置）：$REDIS_HOST:$REDIS_PORT"
+    fi
+    echo "   密码：${REDIS_PASSWORD:+***已设置***}"
+else
+    echo "⚠️ common-cache.properties 不存在（跳过）"
+fi
+
+# 从 common.properties 读取 Nacos 地址和 CLOUD_HOME
+echo ""
+echo "=== 读取 common.properties ==="
+if [ -f "$NACOS_EXPORT_DIR/common.properties" ]; then
+    # meritdata.cloud.server.ip（备用）
+    SERVER_IP=$(read_nacos_prop "common.properties" "meritdata.cloud.server.ip")
+    # meritdata.cloud.web-server-gateway（备用）
+
+    # nacos-addr（如果有）
+    NACOS_ADDR=$(read_nacos_prop "common.properties" "meritdata.cloud.nacos-addr")
+    if [ -n "$NACOS_ADDR" ] && [ -z "$NACOS_HOST:$NACOS_PORT" ]; then
+        export NACOS_HOST=$(echo "$NACOS_ADDR" | cut -d':' -f1)
+        export NACOS_PORT=$(echo "$NACOS_ADDR" | cut -d':' -f2)
+        echo "✅ Nacos：$NACOS_HOST:$NACOS_PORT（来自 common.properties）"
+    fi
+
+    # platform-version
+    PLAT_VER=$(read_nacos_prop "common.properties" "meritdata.cloud.platform-version")
+    [ -z "$PLATFORM_VERSION" ] && [ -n "$PLAT_VER" ] && export PLATFORM_VERSION="$PLAT_VER" || true
+    echo "   Platform version: $PLATFORM_VERSION"
+fi
+
+# 从 common-cloud-system-manage.properties 读取 Nacos 凭据（fallback）
+echo ""
+echo "=== 读取 common-cloud-system-manage.properties（Nacos 凭据 fallback）==="
+if [ -f "$NACOS_EXPORT_DIR/common-cloud-system-manage.properties" ]; then
+    # nacos 用户名
+    NACOS_USER_CFG=$(read_nacos_prop "common-cloud-system-manage.properties" "spring.cloud.nacos.username")
+    [ -z "$NACOS_USER" ] && [ -n "$NACOS_USER_CFG" ] && export NACOS_USER="$NACOS_USER_CFG" || true
+
+    # nacos 密码
+    NACOS_PASS_CFG=$(read_nacos_prop "common-cloud-system-manage.properties" "spring.cloud.nacos.password")
+    [ -z "$NACOS_PASSWORD" ] && [ -n "$NACOS_PASS_CFG" ] && export NACOS_PASSWORD="$NACOS_PASS_CFG" || true
+
+    # nacos 地址
+    NACOS_ADDR_CFG=$(read_nacos_prop "common-cloud-system-manage.properties" "spring.cloud.nacos.discovery.server-addr")
+    if [ -n "$NACOS_ADDR_CFG" ] && [ -z "${NACOS_HOST}${NACOS_PORT}" ]; then
+        export NACOS_HOST=$(echo "$NACOS_ADDR_CFG" | cut -d':' -f1)
+        export NACOS_PORT=$(echo "$NACOS_ADDR_CFG" | cut -d':' -f2)
+    fi
+
+    echo "   Nacos：$NACOS_USER@$NACOS_HOST:$NACOS_PORT"
+fi
+
+# 从本工程的 common-${APP_NAME}.properties 读取 app port（fallback）
+if [ -n "$APP_NAME" ]; then
+    APP_CONFIG="$NACOS_EXPORT_DIR/common-${APP_NAME}.properties"
+    if [ -f "$APP_CONFIG" ]; then
+        echo ""
+        echo "=== 读取 common-${APP_NAME}.properties ==="
+        APP_PORT_CFG=$(read_nacos_prop "common-${APP_NAME}.properties" "server.port")
+        [ -z "$APP_PORT" ] && [ -n "$APP_PORT_CFG" ] && export APP_PORT="$APP_PORT_CFG" || true
+        echo "   Server port: $APP_PORT"
+    fi
+fi
+
+# 输出汇总
+echo ""
+echo "=== 当前生效的环境变量 ==="
+for v in APP_NAME APP_PORT MAVEN_SETTINGS MERIT_HOME \
+         MYSQL_HOST MYSQL_PORT MYSQL_USER MYSQL_PASSWORD MYSQL_DATABASE \
+         REDIS_HOST REDIS_PORT REDIS_PASSWORD \
+         NACOS_HOST NACOS_PORT NACOS_USER NACOS_PASSWORD \
+         PLATFORM_VERSION FRONTEND_PAGES; do
+    if [ -n "${!v}" ]; then
+        echo "  ✅ $v=${!v}"
+    else
+        echo "  ❌ $v (未设置)"
+    fi
+done

package/skills/meritdata-platform-2nd-dev-check/scripts/run-all.sh

@@ -0,0 +1,168 @@
+#!/bin/bash
+# =============================================================================
+# 一键全套检查：调用所有 5 个分类检查，输出汇总报告
+# 通用化：自动从 Nacos 导出目录/DEFAULT_GROUP/ 读取真实配置
+# =============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+
+# 第 1 步：自动从 Nacos 导出目录加载真实配置
+# （用户 export 的环境变量优先级最高，会覆盖自动加载的值）
+if [ -f "$SCRIPT_DIR/load-config.sh" ]; then
+    echo "=== 自动加载 Nacos 导出目录配置 ==="
+    source "$SCRIPT_DIR/load-config.sh"
+    echo ""
+fi
+
+# 第 1.5 步：检测 --check-env-only 旗标（2026-08-12 新增）
+# 用于 Claude Code skill 启动时预检，输出 JSON 后退出（exit 0）
+if [ "${1:-}" = "--check-env-only" ]; then
+    REQUIRED_VARS=("APP_NAME" "APP_PORT" "MAVEN_SETTINGS" "MERIT_HOME" \
+                   "MYSQL_HOST" "MYSQL_PORT" \
+                   "NACOS_HOST" "NACOS_PORT" \
+                   "PLATFORM_VERSION" "FRONTEND_PAGES")
+    CRITICAL_VARS=("APP_NAME" "MAVEN_SETTINGS" "MERIT_HOME" "FRONTEND_PAGES")
+
+    MISSING_ARR=()
+    CRITICAL_MISSING_ARR=()
+    CURRENT_LINES=()
+
+    for v in "${REQUIRED_VARS[@]}"; do
+        val="${!v}"
+        if [ -z "$val" ]; then
+            MISSING_ARR+=("$v")
+            # critical 区分
+            for cv in "${CRITICAL_VARS[@]}"; do
+                if [ "$v" = "$cv" ]; then
+                    CRITICAL_MISSING_ARR+=("$v")
+                    break
+                fi
+            done
+            CURRENT_LINES+=("    \"$v\": \"\"")
+        else
+            # JSON 转义：backslash + 双引号
+            esc=$(printf '%s' "$val" | sed 's/\\/\\\\/g; s/"/\\"/g')
+            CURRENT_LINES+=("    \"$v\": \"$esc\"")
+        fi
+    done
+
+    # 用 printf 拼接 missing 数组（避免双引号转义陷阱）
+    MISSING_STR=$(printf '"%s",' "${MISSING_ARR[@]}")
+    MISSING_STR="[${MISSING_STR%,}]"
+    [ "${#MISSING_ARR[@]}" -eq 0 ] && MISSING_STR="[]"
+
+    CRIT_STR=$(printf '"%s",' "${CRITICAL_MISSING_ARR[@]}")
+    CRIT_STR="[${CRIT_STR%,}]"
+    [ "${#CRITICAL_MISSING_ARR[@]}" -eq 0 ] && CRIT_STR="[]"
+
+    # current 字段：每行一个 var
+    CURRENT_BLOCK=$(printf '%s,\n' "${CURRENT_LINES[@]}")
+    CURRENT_BLOCK="${CURRENT_BLOCK%,}"
+
+    echo "{"
+    echo "  \"missing\": $MISSING_STR,"
+    echo "  \"critical_missing\": $CRIT_STR,"
+    echo "  \"current\": {"
+    echo "$CURRENT_BLOCK"
+    echo "  }"
+    echo "}"
+    exit 0
+fi
+
+# 第 2 步：检查必需的最小环境变量
+MISSING=0
+echo "=== 必需环境变量检查 ==="
+for v in APP_NAME APP_PORT MAVEN_SETTINGS MERIT_HOME \
+         MYSQL_HOST MYSQL_PORT \
+         NACOS_HOST NACOS_PORT \
+         PLATFORM_VERSION FRONTEND_PAGES; do
+    if [ -z "${!v}" ]; then
+        echo "  ❌ $v 未设置"
+        MISSING=$((MISSING+1))
+    else
+        echo "  ✅ $v=${!v}"
+    fi
+done
+
+if [ $MISSING -gt 0 ]; then
+    echo ""
+    echo "❌ 缺少 $MISSING 个环境变量，无法继续"
+    echo ""
+    echo "💡 提示：本 skill 在 Claude Code 中会自动通过 AskUserQuestion 补齐缺失变量"
+    echo "   bash 直跑用户请通过以下两种方式之一配置："
+    echo "  1. 项目根创建 .env 文件（推荐）"
+    echo "  2. export 手动设置环境变量"
+    echo ""
+    echo "最小必需配置："
+    cat <<EOF
+export APP_NAME=your-app-name             # 必填：你的 Spring Boot 应用名
+export APP_PORT=18080                       # 必填：你的服务端口（避开 8080/8081/8085）
+export MAVEN_SETTINGS="<你的 settings.xml 绝对路径>"
+export MERIT_HOME="<美林平台环境根目录，含 key/ 证书>"
+export MYSQL_HOST=localhost                  # 可被 Nacos 导出目录自动覆盖
+export MYSQL_PORT=3337                       # 可被 Nacos 导出目录自动覆盖
+export NACOS_HOST=localhost
+export NACOS_PORT=8850
+export PLATFORM_VERSION=6.13.2
+export FRONTEND_PAGES=page1,page2,page3
+EOF
+    echo ""
+    echo "MYSQL_USER/MYSQL_PASSWORD/REDIS_*/NACOS_USER/NACOS_PASSWORD 等"
+    echo "会自动从 Nacos 导出目录/DEFAULT_GROUP/ 读取，无需手填"
+    exit 1
+fi
+
+echo ""
+echo "✅ 所有必需环境变量已就绪"
+echo ""
+
+run_check() {
+    local name=$1
+    local script=$2
+    echo ""
+    echo "=========================================="
+    echo "  $name"
+    echo "=========================================="
+    if [ -f "$script" ]; then
+        # 修复 2026-07-27：原写法 `if bash "$script"; then` 在 Windows Git Bash 下
+        # 会导致子脚本的 stdout 被截断、退出码被误判（所有子检查都报"失败"）。
+        # 改为显式捕获退出码 + 临时文件缓冲输出，再统一展示。
+        # 注意：不能用 `local tmp_log=$(mktemp)` 形式，Windows Git Bash 下会失败。
+        # 改用 $$（进程 PID）作后缀，确保唯一性且无 subshell 问题。
+        tmp_log="/tmp/merit_check_$$_$RANDOM.log"
+        bash "$script" > "$tmp_log" 2>&1
+        exit_code=$?
+        cat "$tmp_log"
+        rm -f "$tmp_log"
+        if [ $exit_code -eq 0 ]; then
+            echo ""
+            echo "✅ $name 检查完成（exit 0）"
+        else
+            echo ""
+            echo "❌ $name 检查失败（exit $exit_code）"
+        fi
+    else
+        echo "❌ 脚本缺失: $script"
+    fi
+}
+
+# 执行 6 个分类检查
+run_check "1️⃣ 基础设施 (MySQL/Redis/Nacos/平台服务)" "$SCRIPT_DIR/check-platform.sh"
+run_check "2️⃣ 后端工程 (pom.xml/Java/编译)" "$SCRIPT_DIR/check-backend.sh"
+run_check "3️⃣ 前端工程 (npm/页面/构建)" "$SCRIPT_DIR/check-frontend.sh"
+run_check "4️⃣ 数据库 (cloud 库表)" "$SCRIPT_DIR/check-database.sh"
+run_check "5️⃣ 代码规范 (包路径/命名/审计字段)" "$SCRIPT_DIR/check-conventions.sh"
+run_check "6️⃣ 关键库版本一致性 (pom vs apps/common-lib)" "$SCRIPT_DIR/check-lib-version.sh"
+
+echo ""
+echo "=========================================="
+echo "  全套检查完成"
+echo "=========================================="
+echo ""
+echo "📋 报告归档建议: $SKILL_DIR/<用户配置的报告输出目录>/"
+echo "📖 详细检查清单: $SKILL_DIR/references/checklist.md"
+echo "🔧 修复指南: $SKILL_DIR/references/fix-guide.md"
+echo ""
+echo "🚨 如有 FAIL 项，请参考 fix-guide.md 进行修复"