Skill

env-check

Universal environment checker. Detects missing tools, services, and configurations BEFORE starting any work phase. Always asks user before installing anything. Used by Designer (Stitch), FE, and BE agents. Modules: A = Stitch MCP (Designer), B = Backend env (BE), C = Frontend env (FE).

Popularity

Parent stars

Parent forks

Invocation

How this skill is triggered — by the user, by Claude, or both

Slash command

/claude-harness:env-check

User invocable

Model invocable

Inline context

Default effort

Context Preview

The summary Claude sees in its skill listing — used to decide when to auto-load this skill

**检测先行，询问再装，用户决定。**

SKILL.md

654 lines · ~3.7k tokens

Stats

LanguageJavaScript

Parent stars4

Parent forks1

MaintenanceExcellent

Last CommitApr 10, 2026

Actions

View Source View Plugin View on GitHub View README

Stats

Actions

环境检测与引导配置

核心原则

检测先行，询问再装，用户决定。

任何工具或服务缺失时：

检测 → 确认是否缺失
询问 → 告诉用户缺什么，问是否需要配置
引导 → 如果用户同意，提供具体安装命令并执行
验证 → 安装后验证是否成功
继续 → 验证通过后继续工作流

永远不在没有明确用户同意的情况下自动安装任何东西。

模块索引

模块	调用方	说明	跳转
模块 A	Designer	Stitch MCP 检测与配置	→ [模块 A]
模块 B	BE Agent	后端环境检测（DB / Redis / 依赖）	→ [模块 B]
模块 C	FE Agent	前端环境检测（依赖 / 设计稿 / API 客户端）	→ [模块 C]

使用方式：加载本 SKILL.md 后，只执行与调用方对应的模块，其他模块跳过。

任何工具或服务缺失时：

检测 → 确认是否缺失
询问 → 告诉用户缺什么，问是否需要配置
引导 → 如果用户同意，提供具体安装命令并执行
验证 → 安装后验证是否成功
继续 → 验证通过后继续工作流

永远不在没有明确用户同意的情况下自动安装任何东西。

模块 A：Stitch MCP 检测

由 Designer Agent 在 /generate-stitch-designs 前调用。

检测逻辑

# 检测 Stitch MCP 是否已配置
check_stitch_mcp() {
  # 方法 1：检查 claude mcp list 输出
  if claude mcp list 2>/dev/null | grep -qi "stitch"; then
    echo "CONFIGURED"
    return 0
  fi

  # 方法 2：检查 .mcp.json 配置文件
  if [ -f ".mcp.json" ] && grep -qi "stitch" .mcp.json 2>/dev/null; then
    echo "CONFIGURED"
    return 0
  fi

  # 方法 3：检查全局配置
  if [ -f "$HOME/.claude/mcp.json" ] && grep -qi "stitch" "$HOME/.claude/mcp.json" 2>/dev/null; then
    echo "CONFIGURED"
    return 0
  fi

  echo "NOT_CONFIGURED"
  return 1
}

询问流程

当检测到 NOT_CONFIGURED 时，停止并向用户展示以下内容：

## ⚙️ 需要你的决定：Stitch MCP 未配置

Stitch 是 Google 的 AI UI 设计工具，可以生成真实的 HTML 设计稿。
当前 Stitch MCP 未配置，有以下三个选择：

---

**选项 1：现在配置（推荐）**
   使用 API Key 方式，约 2 分钟，之后自动生成设计稿

   步骤：
   a. 前往 https://stitch.withgoogle.com → Settings → API Keys
   b. 复制 API Key
   c. 告诉我 API Key，我来完成配置

**选项 2：使用第三方代理（解决 OAuth bug）**
   需要 gcloud CLI 已安装，约 3 分钟

   命令：npx @_davideast/stitch-mcp init

**选项 3：跳过 Stitch，输出提示词文件**
   生成 design/stitch-prompts.md，你可以之后手动粘贴到 stitch.withgoogle.com
   设计阶段继续进行，但没有真实 HTML 设计稿

---

请回复：1、2、3 或直接粘贴你的 API Key

配置执行（用户选择 1 后）

# 用户提供 API Key 后执行
configure_stitch_api_key() {
  local api_key="$1"

  # 添加到 Claude Code
  claude mcp add stitch \
    --transport http \
    "https://stitch.googleapis.com/mcp" \
    --header "X-Goog-Api-Key: $api_key" \
    -s user

  # 验证配置
  if claude mcp list 2>/dev/null | grep -qi "stitch"; then
    echo "✅ Stitch MCP 配置成功"
    return 0
  else
    echo "❌ 配置失败，请检查 API Key 是否正确"
    return 1
  fi
}

配置执行（用户选择 2 后）

configure_stitch_proxy() {
  # 检查 npm/npx 是否可用
  if ! command -v npx &>/dev/null; then
    echo "❌ 需要先安装 Node.js 和 npm"
    return 1
  fi

  npx @_davideast/stitch-mcp init

  if [ $? -eq 0 ]; then
    echo "✅ Stitch MCP 代理配置成功"
  else
    echo "❌ 配置失败，请查看上方错误信息"
    return 1
  fi
}

模块 B：BE 开发环境检测

由 BE Agent 在开始实现之前调用。

检测清单

check_be_environment() {
  local issues=()
  local warnings=()

  # 1. 运行时检测
  echo "检测运行时..."
  if command -v bun &>/dev/null; then
    BUN_VERSION=$(bun --version)
    echo "  ✅ Bun $BUN_VERSION"
  elif command -v node &>/dev/null; then
    NODE_VERSION=$(node --version)
    echo "  ⚠️  Node.js $NODE_VERSION（推荐 Bun，但 Node 可用）"
    warnings+=("运行时：建议安装 Bun 以获得更好性能")
  else
    echo "  ❌ Bun/Node.js 未安装"
    issues+=("MISSING_RUNTIME:需要 Bun 或 Node.js")
  fi

  # 2. 数据库检测
  echo "检测数据库..."
  DB_URL="${DATABASE_URL:-}"

  if [ -z "$DB_URL" ]; then
    # 检查 .env 文件
    if [ -f ".env" ] && grep -q "DATABASE_URL" .env; then
      DB_URL=$(grep "DATABASE_URL" .env | cut -d= -f2-)
    elif [ -f ".env.local" ] && grep -q "DATABASE_URL" .env.local; then
      DB_URL=$(grep "DATABASE_URL" .env.local | cut -d= -f2-)
    fi
  fi

  if [ -z "$DB_URL" ]; then
    echo "  ❌ DATABASE_URL 未配置"
    issues+=("MISSING_DATABASE_URL:数据库连接未配置")
  else
    # 尝试连接（如果是 PostgreSQL）
    if echo "$DB_URL" | grep -q "postgresql\|postgres"; then
      if command -v psql &>/dev/null; then
        if psql "$DB_URL" -c "SELECT 1" &>/dev/null 2>&1; then
          echo "  ✅ PostgreSQL 可连接"
        else
          echo "  ❌ PostgreSQL 配置了但无法连接"
          issues+=("DB_CONNECTION_FAILED:数据库无法连接，请检查连接字符串和服务状态")
        fi
      else
        echo "  ⚠️  DATABASE_URL 已配置，但无法验证连接（psql 未安装）"
        warnings+=("建议安装 psql 以验证数据库连接")
      fi
    fi
  fi

  # 3. Redis 检测（如果 arch-decision.md 提到需要）
  if [ -f "docs/arch-decision.md" ] && grep -qi "redis\|bullmq\|upstash" docs/arch-decision.md; then
    echo "检测 Redis..."
    REDIS_URL="${REDIS_URL:-}"
    if [ -z "$REDIS_URL" ]; then
      if [ -f ".env" ] && grep -q "REDIS_URL" .env; then
        REDIS_URL=$(grep "REDIS_URL" .env | cut -d= -f2-)
      fi
    fi

    if [ -z "$REDIS_URL" ]; then
      echo "  ❌ REDIS_URL 未配置（架构要求 Redis）"
      issues+=("MISSING_REDIS_URL:架构需要 Redis，但 REDIS_URL 未配置")
    else
      echo "  ✅ REDIS_URL 已配置"
    fi
  fi

  # 4. .env 文件检测
  echo "检测环境变量..."
  if [ ! -f ".env" ] && [ ! -f ".env.local" ]; then
    echo "  ❌ 未找到 .env 文件"
    issues+=("MISSING_ENV_FILE:.env 文件不存在")
  elif [ -f ".env.example" ]; then
    # 检查 .env.example 中的必填项是否都配置了
    MISSING_VARS=()
    while IFS= read -r line; do
      # 跳过注释和空行
      [[ "$line" =~ ^#.*$ || -z "$line" ]] && continue
      VAR_NAME=$(echo "$line" | cut -d= -f1)
      # 检查变量是否在 .env 中有值
      if [ -f ".env" ]; then
        VAR_VALUE=$(grep "^${VAR_NAME}=" .env | cut -d= -f2-)
        if [ -z "$VAR_VALUE" ]; then
          MISSING_VARS+=("$VAR_NAME")
        fi
      fi
    done < .env.example

    if [ ${#MISSING_VARS[@]} -gt 0 ]; then
      echo "  ⚠️  以下变量未配置：${MISSING_VARS[*]}"
      warnings+=("ENV_VARS_MISSING:${MISSING_VARS[*]}")
    else
      echo "  ✅ 环境变量完整"
    fi
  fi

  # 5. 依赖安装检测
  echo "检测依赖..."
  # 支持 monorepo（apps/server） + 单仓库（根目录 / server/）
  BE_PKG=$(find . -maxdepth 3 -name "package.json" \
    \( -path "*/apps/server/package.json" -o -path "*/server/package.json" -o -path "*/backend/package.json" -o -path "./server/package.json" -o -path "./backend/package.json" \) \
    -not -path "*/node_modules/*" 2>/dev/null | head -1)
  if [ -n "$BE_PKG" ]; then
    BE_DIR=$(dirname "$BE_PKG")
    if [ ! -d "${BE_DIR}/node_modules" ]; then
      echo "  ❌ 后端依赖未安装（${BE_DIR}/）"
      issues+=("DEPS_NOT_INSTALLED:${BE_DIR}/node_modules 不存在")
    else
      echo "  ✅ 后端依赖已安装（${BE_DIR}/）"
    fi
  else
    echo "  ⚠️  未检测到后端 package.json（单仓库或无独立后端）"
  fi

  # 汇总结果
  echo ""
  echo "检测完成"
  echo "❌ 阻塞问题：${#issues[@]} 个"
  echo "⚠️  建议修复：${#warnings[@]} 个"

  # 返回问题列表（供询问流程使用）
  printf '%s\n' "${issues[@]}"
}

BE 环境询问模板

当检测到问题时，停止并向用户展示：

## ⚙️ 需要你的决定：开发环境有 {N} 个问题

在开始实现之前，发现以下环境问题：

---

{如果 MISSING_RUNTIME}
**问题 1：未找到 Bun / Node.js**
Bun 是推荐的运行时（比 Node.js 快 3-4x）

选项：
  A) 安装 Bun（推荐）：curl -fsSL https://bun.sh/install | bash
  B) 使用系统已有的 Node.js（如果有的话）
  C) 告诉我你希望用什么运行时

{如果 MISSING_DATABASE_URL}
**问题 {N}：数据库未配置**
架构决策要求 PostgreSQL 16+

选项：
  A) 本地 Docker 快速启动（推荐开发环境）：
     docker run -d --name postgres \
       -e POSTGRES_PASSWORD=devpassword \
       -e POSTGRES_DB=myapp \
       -p 5432:5432 postgres:16
     DATABASE_URL=postgresql://postgres:devpassword@localhost:5432/myapp

  B) 使用云数据库（Neon/Supabase）：告诉我你的连接字符串
  C) 跳过数据库，先实现不需要 DB 的部分

{如果 MISSING_REDIS_URL}
**问题 {N}：Redis 未配置**
架构决策要求 Redis（用于 BullMQ 队列/缓存）

选项：
  A) 本地 Docker 启动：
     docker run -d --name redis -p 6379:6379 redis:7
     REDIS_URL=redis://localhost:6379

  B) 使用 Upstash（免费云 Redis）：https://upstash.com
  C) 跳过 Redis 相关功能，先实现其他部分

{如果 DEPS_NOT_INSTALLED}
**问题 {N}：依赖未安装**
需要运行 bun install / npm install

选项：
  A) 现在自动安装（推荐）
  B) 我手动安装后告诉你

---

请回复每个问题选择的选项（如：1-A, 2-B, 3-A）
或直接说"全部自动处理"让我帮你完成所有配置

BE 自动处理逻辑

# 如果用户说"全部自动处理"或指定了选项

# 安装 Bun（如果选 A）
install_bun() {
  echo "正在安装 Bun..."
  curl -fsSL https://bun.sh/install | bash
  export PATH="$HOME/.bun/bin:$PATH"
  bun --version && echo "✅ Bun 安装成功" || echo "❌ 安装失败"
}

# 启动本地 PostgreSQL（如果选 A）
start_local_postgres() {
  if ! command -v docker &>/dev/null; then
    echo "❌ Docker 未安装，请先安装 Docker Desktop"
    echo "   下载：https://www.docker.com/products/docker-desktop"
    return 1
  fi

  docker run -d --name postgres-dev \
    -e POSTGRES_PASSWORD=devpassword \
    -e POSTGRES_DB=myapp_dev \
    -p 5432:5432 \
    postgres:16-alpine \
    2>/dev/null || docker start postgres-dev 2>/dev/null

  sleep 3  # 等待启动

  # 写入 .env
  if ! grep -q "DATABASE_URL" .env 2>/dev/null; then
    echo 'DATABASE_URL=postgresql://postgres:devpassword@localhost:5432/myapp_dev' >> .env
    echo "✅ DATABASE_URL 已写入 .env"
  fi

  # 运行 migration
  if [ -n "$BE_DIR" ] && [ -f "${BE_DIR}/package.json" ]; then
    cd "$BE_DIR"
    bun run db:push 2>/dev/null || \
    bun run drizzle-kit push 2>/dev/null || \
    echo "⚠️  请手动运行数据库迁移"
    cd ../..
  fi
}

# 启动本地 Redis（如果选 A）
start_local_redis() {
  if ! command -v docker &>/dev/null; then
    echo "❌ Docker 未安装"
    return 1
  fi

  docker run -d --name redis-dev \
    -p 6379:6379 \
    redis:7-alpine \
    2>/dev/null || docker start redis-dev 2>/dev/null

  if ! grep -q "REDIS_URL" .env 2>/dev/null; then
    echo 'REDIS_URL=redis://localhost:6379' >> .env
    echo "✅ REDIS_URL 已写入 .env"
  fi
}

# 安装依赖
install_deps() {
  _target_dir="${BE_DIR:-apps/server}"
  cd "$_target_dir"
  echo "正在安装依赖: $_target_dir/"
  if command -v bun &>/dev/null; then
    bun install && echo "✅ 依赖安装成功（bun）"
  else
    npm install && echo "✅ 依赖安装成功（npm）"
  fi
  cd ../..
}

模块 C：FE 开发环境检测

由 FE Agent 在开始实现之前调用。

检测清单

check_fe_environment() {
  local issues=()

  # 1. Node.js / Bun
  echo "检测运行时..."
  if command -v bun &>/dev/null; then
    echo "  ✅ Bun $(bun --version)"
  elif command -v node &>/dev/null; then
    NODE_VER=$(node -e "process.exit(parseInt(process.version.slice(1)) < 18 ? 1 : 0)" 2>/dev/null)
    if [ $? -eq 0 ]; then
      echo "  ✅ Node.js $(node --version)"
    else
      echo "  ❌ Node.js 版本过低（需要 18+）"
      issues+=("NODE_VERSION_LOW:Node.js 版本需要 18 以上")
    fi
  else
    echo "  ❌ Node.js / Bun 未安装"
    issues+=("MISSING_RUNTIME:需要 Node.js 18+ 或 Bun")
  fi

  # 2. FE 依赖
  echo "检测前端依赖..."
  # 支持 monorepo（apps/web）+ 单仓库（根目录 / client/ / frontend/）
  FE_PKG=$(find . -maxdepth 3 -name "package.json" \
    \( -path "*/apps/web/package.json" -o -path "*/client/package.json" -o -path "*/frontend/package.json" \
       -o -path "./package.json" -o -path "./client/package.json" -o -path "./frontend/package.json" \) \
    -not -path "*/node_modules/*" 2>/dev/null | head -1)
  if [ -n "$FE_PKG" ]; then
    FE_DIR=$(dirname "$FE_PKG")
    if [ ! -d "${FE_DIR}/node_modules" ]; then
      echo "  ❌ 前端依赖未安装（${FE_DIR}/）"
      issues+=("FE_DEPS_MISSING:${FE_DIR}/node_modules 不存在")
    else
      echo "  ✅ 前端依赖已安装（${FE_DIR}/）"
    fi
  else
    echo "  ⚠️  未检测到前端 package.json"
  fi

  # 3. 设计稿检测
  echo "检测设计稿..."
  if [ -d "design" ] && [ -f "design/index.html" ]; then
    SCREEN_COUNT=$(find design -name "desktop.html" | wc -l)
    echo "  ✅ 设计稿已就绪（${SCREEN_COUNT} 个页面）"
  elif [ -f "design/stitch-prompts.md" ]; then
    echo "  ⚠️  仅有 Stitch 提示词，无真实设计稿"
    issues+=("NO_DESIGN_SCREENS:design/ 目录只有提示词，建议先配置 Stitch MCP 生成真实设计稿")
  elif [ -f "docs/design-spec.md" ]; then
    echo "  ⚠️  只有文字规范，无设计稿（将基于规范实现）"
  else
    echo "  ❌ 既无设计稿也无设计规范"
    issues+=("NO_DESIGN_AT_ALL:设计阶段产出物缺失，无法开始实现")
  fi

  # 4. 环境变量（NEXT_PUBLIC_* 等）
  echo "检测前端环境变量..."
  NEXT_PUBLIC_MISSING=()
  if [ -f ".env.example" ]; then
    while IFS= read -r line; do
      [[ "$line" =~ ^#.*$ || -z "$line" ]] && continue
      VAR=$(echo "$line" | cut -d= -f1)
      if [[ "$VAR" == NEXT_PUBLIC_* ]]; then
        VAL=$(grep "^${VAR}=" .env 2>/dev/null | cut -d= -f2-)
        [ -z "$VAL" ] && NEXT_PUBLIC_MISSING+=("$VAR")
      fi
    done < .env.example
  fi
  if [ ${#NEXT_PUBLIC_MISSING[@]} -gt 0 ]; then
    echo "  ⚠️  缺少公共环境变量：${NEXT_PUBLIC_MISSING[*]}"
    issues+=("NEXT_PUBLIC_VARS_MISSING:${NEXT_PUBLIC_MISSING[*]}")
  fi

  # 5. API 地址配置
  if [ -f "docs/arch-decision.md" ] && grep -qi "trpc\|api" docs/arch-decision.md; then
    echo "检测 API 连接配置..."
    # 支持 monorepo + 单仓库多种路径模式
    API_CLIENT=$(find . -maxdepth 5 \
      \( -path "*/lib/trpc.ts" -o -path "*/lib/trpc/client.ts" \
         -o -path "*/lib/api.ts" -o -path "*/utils/request.ts" \
         -o -path "*/utils/http.ts" -o -path "*/utils/api.ts" \
         -o -path "*/services/index.ts" -o -path "*/api/index.ts" \
         -o -path "*/src/lib/trpc.ts" -o -path "*/src/utils/request.ts" \
         -o -path "*/src/api.ts" \) \
      -not -path "*/node_modules/*" 2>/dev/null | head -1)
    if [ -n "$API_CLIENT" ]; then
      echo "  ✅ API 客户端已配置（${API_CLIENT}）"
    else
      echo "  ⚠️  API 客户端路径不在预设列表中，手动确认"
      echo "  （单仓库或使用非标准路径的项目跳过此检查）"
    fi
  fi

  printf '%s\n' "${issues[@]}"
}

FE 环境询问模板

## ⚙️ 需要你的决定：前端环境有 {N} 个问题

{如果 FE_DEPS_MISSING}
**问题 {N}：前端依赖未安装**

选项：
  A) 现在自动安装（推荐）
     bun install（或 npm install）
  B) 我手动安装后告诉你

{如果 NO_DESIGN_SCREENS（只有 stitch-prompts.md）}
**问题 {N}：没有真实 HTML 设计稿**
发现 design/stitch-prompts.md，但没有真实的 HTML 设计稿文件。

选项：
  A) 现在配置 Stitch MCP 并生成设计稿（推荐）
     我来引导你完成 Stitch 配置，然后自动生成
  B) 使用 stitch-prompts.md 中的提示词手动生成
     前往 https://stitch.withgoogle.com，粘贴提示词，
     把生成的 HTML 下载后放入 design/{page}/desktop.html
  C) 跳过设计稿，直接基于 docs/design-spec.md 实现
     注意：没有设计稿时视觉对比功能不可用

{如果 NEXT_PUBLIC_VARS_MISSING}
**问题 {N}：缺少前端公共环境变量**
缺少：{变量名列表}

选项：
  A) 告诉我每个变量的值，我来写入 .env
  B) 我手动编辑 .env 文件
  C) 先跳过，实现不依赖这些变量的部分

---
请回复每个问题的选择，或直接说"帮我处理"

模块 D：通用工具检测

适用于任何 Agent 遇到工具缺失时。

检测函数

check_tool() {
  local tool="$1"
  local install_hint="$2"

  if command -v "$tool" &>/dev/null; then
    echo "✅ $tool 已安装（$(which $tool)）"
    return 0
  else
    echo "❌ $tool 未找到"
    echo ""
    echo "需要安装 $tool 才能继续。"
    echo "$install_hint"
    echo ""
    echo "是否现在安装？（是/否/手动安装后告诉我）"
    return 1
  fi
}

# 使用示例
check_tool "docker" "安装 Docker Desktop：https://www.docker.com/products/docker-desktop"
check_tool "psql" "安装 PostgreSQL 客户端：brew install postgresql 或 apt install postgresql-client"
check_tool "playwright" "安装：bunx playwright install"

询问标准格式

所有环境询问都遵循此格式：

## ⚙️ 缺少 {工具名}

**原因**：{为什么需要这个工具}
**影响**：{如果不装，哪些功能无法进行}

**安装选项**：
  A) 自动安装：{具体命令}
  B) 手动安装：{文档链接或步骤}
  C) 跳过：{跳过后的影响说明}

请回复 A、B 或 C

执行后必须做的事

无论环境检测结果如何，在向用户报告时：

清晰列出 阻塞问题（必须解决才能继续）和警告问题（可以跳过）
给出明确选项，不让用户猜测该怎么做
用户选择后立即执行，执行后打印结果

所有安装记录到 state/agent-log.jsonl：

node scripts/workflow.js log-agent \
  '{"agent":"env-check","action":"install_postgres","status":"OK","note":"docker local"}'

验证安装成功后才继续工作流

接力

环境检测完成后：

全部 ✅ → 返回调用方（env-check 是前置步骤，完成后继续调用者主流程）
有 ❌ → 停止，解决依赖后重跑本检测，通过后才能继续

env-check

Popularity

Invocation

Context Preview

SKILL.md

env-check

Popularity

Invocation

Context Preview

SKILL.md

环境检测与引导配置

核心原则

模块索引

模块 A：Stitch MCP 检测

检测逻辑

询问流程

配置执行（用户选择 1 后）

配置执行（用户选择 2 后）

模块 B：BE 开发环境检测

检测清单

BE 环境询问模板

BE 自动处理逻辑

模块 C：FE 开发环境检测

检测清单

FE 环境询问模板

模块 D：通用工具检测

检测函数

询问标准格式

执行后必须做的事

接力

Similar Skills

环境检测与引导配置

核心原则

模块索引

模块 A：Stitch MCP 检测

检测逻辑

询问流程

配置执行（用户选择 1 后）

配置执行（用户选择 2 后）

模块 B：BE 开发环境检测

检测清单

BE 环境询问模板

BE 自动处理逻辑

模块 C：FE 开发环境检测

检测清单

FE 环境询问模板

模块 D：通用工具检测

检测函数

询问标准格式

执行后必须做的事

接力

Similar Skills