---

name: inspirai-deploy description: "智慧部署工具 - 自動檢測部署策略，預檢查、釋出、監控一體化。支援 K8s/Helm、Docker Compose、Vercel、Fly.io。Triggers: '部署', 'deploy', '釋出', '上線', '預檢查', '部署監控', 'helm upgrade', 'docker compose up'." version: 1.0.0 license: MIT

---

inspirai-deploy - 智慧部署工具

自動檢測部署策略，執行預檢查、釋出、監控的一體化部署工具。支援 K8s/Helm、Docker Compose、Vercel、Fly.io。

Init

初始化部署配置

自動檢測專案結構，生成 .deploy.yaml 配置檔案。

使用方式

/deploy init                     # 自動檢測並生成配置
/deploy init --strategy k8s      # 指定策略

執行步驟

Step 1: 檢測專案結構

echo "[INFO] 檢測專案結構..."

# 檢測部署策略
DETECTED_STRATEGIES=""

[ -d "helm" ] && DETECTED_STRATEGIES="$DETECTED_STRATEGIES k8s"
[ -f "docker-compose.yml" ] && DETECTED_STRATEGIES="$DETECTED_STRATEGIES compose"
[ -f "docker-compose.prod.yml" ] && DETECTED_STRATEGIES="$DETECTED_STRATEGIES compose"
[ -f "vercel.json" ] && DETECTED_STRATEGIES="$DETECTED_STRATEGIES vercel"
[ -f "fly.toml" ] && DETECTED_STRATEGIES="$DETECTED_STRATEGIES fly"
[ -f "Dockerfile" ] && DETECTED_STRATEGIES="$DETECTED_STRATEGIES docker-ssh"

echo "[INFO] 檢測到策略: $DETECTED_STRATEGIES"

Step 2: 收集資訊

使用 AskUserQuestion 確認或補充資訊：

1. 策略選擇 — 如果檢測到多個，讓使用者選擇
2. 專案名稱 — 從 package.json / go.mod / 目錄名推斷
3. 環境列表 — 從 helm/environments 或詢問使用者

Step 3: 策略專屬資訊收集

K8s： - 從 justfile/Makefile 提取 registry 資訊 - 從 helm/ 目錄發現 chart 和 values - 從 .service-tags.json 或 services/ 發現元件 - 從 helm/environments/ 發現環境配置

Compose： - 解析 docker-compose.yml 中的 services - 檢測遠端部署目標（如有）

Vercel/Fly： - 從 vercel.json / fly.toml 讀取專案配置

Step 4: 生成 .deploy.yaml

K8s 模板：

strategy: k8s

project:
  name: {project_name}
  description: {description}

registry:
  domain: {registry_domain}
  namespace: {registry_namespace}
  overrides:
    prd: {vpc_registry}

components:
  - name: {component}
    path: services/{component}
    image: {project}-{component}

environments:
  dev:
    cluster: {cluster}
    namespace: {namespace}
    context: {context}
  prd:
    cluster: {cluster}
    namespace: {namespace}
    context: {context}

commands:
  build: "{build_cmd}"
  push: "{push_cmd}"
  deploy: "{deploy_cmd}"
  config: "{config_cmd}"

helm:
  chart_path: helm/{chart}
  release_name: {release}

monitor:
  interval: 5
  timeout: 600
  failure_threshold: 3

Compose 模板：

strategy: compose

project:
  name: {project_name}

compose:
  file: docker-compose.prod.yml
  # 遠端部署（可選）
  host: {user}@{server}
  path: /opt/{project_name}

environments:
  dev:
    file: docker-compose.yml
  prd:
    file: docker-compose.prod.yml

commands:
  deploy: "docker compose -f {file} up -d"
  logs: "docker compose -f {file} logs -f"

monitor:
  interval: 5
  timeout: 120

Vercel 模板：

strategy: vercel

project:
  name: {project_name}

environments:
  preview:
    auto: true
  prd:
    branch: main
    prod: true

commands:
  deploy: "vercel --prod"
  preview: "vercel"

Step 5: 確認配置

顯示生成的配置檔案，詢問使用者確認或修改。

輸出

• 在專案根目錄生成 .deploy.yaml
• 建議將 .deploy.yaml 加入版本控制（不含敏感資訊時）

注意事項

• 如果 .deploy.yaml 已存在，詢問是否覆蓋
• 敏感資訊（credentials、tokens）不寫入配置檔案
• 配置檔案中使用佔位符的命令模板，實際值從環境變數讀取

  小蔥技能7w4.net有更新，你可以訪問看下。

Check

部署預檢查

執行部署前的預檢查，確保所有條件就緒。

安全原則

只檢查、只報告，不修改任何檔案。 發現問題後提供修復建議，由使用者決定是否執行。

使用方式

/deploy check <env> [components...] [options]

選項:
  --image-only         僅檢查映象
  --config-only        僅檢查配置
  --connectivity-only  僅檢查連通性
  --strategy <type>    指定策略

執行步驟

Step 1: 檢測策略並載入配置

同 Run 部分的 Step 1。

Step 2: 通用檢查

所有策略都執行的檢查：

echo "[INFO] ========== 通用預檢查 =========="

# 1. 環境變數檢查
echo "[CHECK] 環境變數..."
# 檢查 .env / .env.{env} 是否存在必需變數

# 2. Git 狀態檢查
echo "[CHECK] Git 狀態..."
UNCOMMITTED=$(git status --porcelain | wc -l | tr -d ' ')
if [ "$UNCOMMITTED" -gt 0 ]; then
    echo "[WARN] 有 $UNCOMMITTED 個未提交的變更"
fi

# 3. 分支檢查（生產環境）
if [ "$ENV" = "prd" ]; then
    BRANCH=$(git rev-parse --abbrev-ref HEAD)
    if [ "$BRANCH" != "main" ] && [ "$BRANCH" != "master" ]; then
        echo "[WARN] 當前分支 $BRANCH 不是主分支"
    fi
fi

Step 3: 策略專屬檢查

K8s 策略：

echo "[INFO] ========== K8s 預檢查 =========="

# 1. 映象推送檢查
echo "[CHECK] 映象推送狀態..."
for comp in $COMPONENTS; do
    tag=$(get_version_tag "$comp" "$ENV")
    image="$REGISTRY/$NAMESPACE/${comp}:${tag}"
    if docker manifest inspect "$image" &>/dev/null; then
        echo "  ✓ $comp: $tag"
    else
        echo "  ✗ $comp: $tag (未推送)"
        FAILED=true
    fi
done

# 2. 配置同步檢查
echo "[CHECK] 配置同步..."
# 渲染本地 Helm values vs 叢集 ConfigMap/Secret
# 對比 data 欄位差異

# 3. 叢集連通性
echo "[CHECK] 叢集連通性..."
kubectl cluster-info $KUBECTL_ARGS &>/dev/null || echo "[ERROR] 無法連線叢集"

# 4. Namespace 存在性
kubectl get namespace "$NAMESPACE" $KUBECTL_ARGS &>/dev/null || echo "[ERROR] Namespace $NAMESPACE 不存在"

Compose 策略：

echo "[INFO] ========== Compose 預檢查 =========="

# 1. 映象構建檢查
echo "[CHECK] 映象構建..."
docker compose config --quiet || echo "[ERROR] compose 配置無效"

# 2. 目標主機連通性（遠端部署時）
if [ -n "$DEPLOY_HOST" ]; then
    echo "[CHECK] 遠端主機連通性..."
    ssh -o ConnectTimeout=5 "$DEPLOY_HOST" "echo ok" || echo "[ERROR] 無法連線 $DEPLOY_HOST"
fi

# 3. 磁碟空間
echo "[CHECK] 磁碟空間..."
docker system df

Vercel/Fly 策略：

echo "[INFO] ========== 平臺預檢查 =========="

# 1. CLI 登入狀態
echo "[CHECK] 登入狀態..."
vercel whoami || fly auth whoami || echo "[ERROR] 未登入"

# 2. 專案連結
echo "[CHECK] 專案連結..."
# 檢查是否已 link 到遠端專案

Step 4: 輸出報告

========== 預檢查報告 ==========

環境: uat
策略: k8s
元件: core, ops, admin

通用檢查:
  ✓ 環境變數完整
  ✓ Git 狀態乾淨
  ✓ 分支: main

策略檢查:
  ✓ 映象: core (v1.2.3)
  ✗ 映象: ops (v1.2.3) - 未推送
  ✓ 配置同步
  ✓ 叢集連通

結果: 1 項失敗
建議: 執行 `just push uat COMPONENTS="ops"` 推送映象後重試

注意事項

• 檢查過程完全只讀，不修改任何檔案或叢集狀態
• 失敗項提供具體的修復命令建議
• 可單獨執行用於 CI/CD pipeline 的 gate check

Run

執行部署

自動檢測部署策略，執行完整的 check → deploy → monitor 流程。

安全原則

嚴禁修改應用邏輯程式碼。 本 skill 只操作部署相關檔案（配置、Dockerfile、Helm、compose 等）。

如果部署過程中發現問題源於應用邏輯： 1. 立即停止部署 2. 報告問題詳情（錯誤日誌、堆疊資訊） 3. 建議轉交專業技能處理（如 /wxm:dev、程式碼修復等） 4. 設定檢查點，修復後可從當前步驟恢復部署

使用方式

/deploy run <env> [components...] [options]

引數:
  env          目標環境 (dev/test/uat/prd)
  components   要部署的元件列表（預設: 全部）

選項:
  --skip-check         跳過所有預檢查
  --skip-image-check   跳過映象推送檢查
  --skip-config-check  跳過配置同步檢查
  --force              強制部署
  --strategy <type>    指定策略（跳過自動檢測）

執行步驟

Step 1: 檢測部署策略

按優先順序自動檢測：

# 1. 顯式配置
if [ -f ".deploy.yaml" ]; then
    STRATEGY=$(grep "^strategy:" .deploy.yaml | awk '{print $2}')
fi

# 2. 自動檢測
if [ -z "$STRATEGY" ]; then
    if [ -d "helm" ] && command -v kubectl &>/dev/null; then
        STRATEGY="k8s"
    elif [ -f "docker-compose.yml" ] || [ -f "docker-compose.prod.yml" ]; then
        STRATEGY="compose"
    elif [ -f "vercel.json" ]; then
        STRATEGY="vercel"
    elif [ -f "fly.toml" ]; then
        STRATEGY="fly"
    elif [ -f "Dockerfile" ]; then
        STRATEGY="docker-ssh"
    elif [ -f "package.json" ]; then
        STRATEGY="script"
    else
        echo "[ERROR] 無法檢測部署策略，請建立 .deploy.yaml"
        exit 1
    fi
fi

echo "[INFO] 部署策略: $STRATEGY"

Step 2: 預檢查（呼叫 Check）

執行策略對應的預檢查，參見 Check 部分。

如果檢查失敗： - 展示失敗原因 - 提供選項：修復後重試 / 跳過檢查 / 中止

Step 3: 執行部署

根據策略執行部署命令：

K8s 策略：

# 從 .deploy.yaml 或自動發現獲取命令
DEPLOY_CMD=$(get_command "deploy" "$ENV")
# 通常是: just deploy $ENV 或 helm upgrade ...

echo "[INFO] 執行部署: $DEPLOY_CMD"
eval "$DEPLOY_CMD"

Compose 策略：

COMPOSE_FILE="${COMPOSE_FILE:-docker-compose.yml}"
if [ "$ENV" = "prd" ]; then
    COMPOSE_FILE="docker-compose.prod.yml"
fi

docker compose -f "$COMPOSE_FILE" up -d $COMPONENTS

Vercel 策略：

if [ "$ENV" = "prd" ]; then
    vercel --prod
else
    vercel
fi

Fly 策略：

fly deploy --app "$APP_NAME"

Script 策略：

# 從 package.json scripts 中查詢
npm run deploy:$ENV

Step 4: 監控（呼叫 Monitor）

部署命令執行後，自動進入監控模式，參見 Monitor 部分。

Step 5: 問題處理

部署失敗時的處理流程：

檢測到錯誤型別：
├── 配置錯誤（env vars、secrets）
│   → 提示修改部署配置，不觸碰應用程式碼
├── 映象拉取失敗
│   → 檢查 registry 連通性和映象 tag
├── 健康檢查失敗（應用啟動異常）
│   → ⚠️ 可能是邏輯問題
│   → 停止部署，輸出日誌
│   → 建議: "應用啟動失敗，建議檢查應用程式碼後重新部署"
├── 資源不足（OOM、CPU limit）
│   → 提示調整資源配額
└── 未知錯誤
    → 輸出完整日誌，等待使用者指示

嚴格規則：任何涉及修改 .go / .ts / .js / .py 等業務程式碼的操作，必須停止並轉交。

檢查點機制

每個步驟完成後設定檢查點：

checkpoint: strategy_detected → checks_passed → deploy_submitted → monitoring

失敗後恢復：

/deploy run <env> --resume    # 從上次檢查點恢復

示例

/deploy run uat                    # 完整流程部署到 uat
/deploy run prd core ops           # 只部署 core 和 ops 到生產
/deploy run dev --skip-check       # 開發環境跳過檢查
/deploy run uat --strategy compose # 強制使用 compose 策略

Monitor

部署狀態監控

監控進行中的部署狀態，檢測異常並提供診斷資訊。

安全原則

只監控、只報告。 發現應用層錯誤時停止監控，報告問題並建議轉交處理。嚴禁自動修改應用程式碼來"修復"問題。

使用方式

/deploy monitor <env> [options]

選項:
  --timeout <seconds>   超時時間（預設 600）
  --interval <seconds>  輪詢間隔（預設 5）
  --logs                同時顯示 Pod 日誌
  --strategy <type>     指定策略

執行步驟

Step 1: 確定監控目標

根據策略確定要監控的資源：

K8s： Deployment replicas、Pod status、Events Compose： Container status、health checks Vercel/Fly： Deployment status API

Step 2: 輪詢監控

K8s 監控：

TIMEOUT=${TIMEOUT:-600}
INTERVAL=${INTERVAL:-5}
START_TIME=$(date +%s)

while true; do
    ELAPSED=$(( $(date +%s) - START_TIME ))
    if [ $ELAPSED -gt $TIMEOUT ]; then
        echo "[TIMEOUT] 超過 ${TIMEOUT}s 未完成"
        break
    fi

    echo "[INFO] ===== $(date +%H:%M:%S) (${ELAPSED}s) ====="

    # Deployment 狀態
    kubectl get deployment -n $NAMESPACE -l "$INSTANCE_LABEL" $KUBECTL_ARGS \
        -o custom-columns="NAME:.metadata.name,READY:.status.readyReplicas,DESIRED:.spec.replicas,UP-TO-DATE:.status.updatedReplicas"

    # Pod 狀態
    kubectl get pods -n $NAMESPACE -l "$INSTANCE_LABEL" $KUBECTL_ARGS \
        -o custom-columns="NAME:.metadata.name,STATUS:.status.phase,RESTARTS:.status.containerStatuses[0].restartCount,AGE:.metadata.creationTimestamp"

    # 異常事件
    WARNINGS=$(kubectl get events -n $NAMESPACE $KUBECTL_ARGS \
        --field-selector type=Warning --sort-by='.lastTimestamp' 2>/dev/null | tail -5)
    if [ -n "$WARNINGS" ]; then
        echo ""
        echo "[WARN] 異常事件:"
        echo "$WARNINGS"
    fi

    # 檢查是否全部就緒
    NOT_READY=$(kubectl get deployment -n $NAMESPACE -l "$INSTANCE_LABEL" $KUBECTL_ARGS \
        -o jsonpath='{range .items[*]}{.metadata.name}:{.status.readyReplicas}/{.spec.replicas}{"\n"}{end}' \
        | grep -v -E "^[^:]+:([0-9]+)/\1$" | wc -l | tr -d ' ')

    if [ "$NOT_READY" -eq 0 ]; then
        echo ""
        echo "[SUCCESS] ✓ 所有 Deployment 已就緒"
        break
    fi

    sleep $INTERVAL
done

Compose 監控：

while true; do
    docker compose ps --format "table {{.Name}}\t{{.Status}}\t{{.Health}}"

    # 檢查是否全部 healthy
    UNHEALTHY=$(docker compose ps --format json | jq -r 'select(.Health != "healthy") | .Name')
    if [ -z "$UNHEALTHY" ]; then
        echo "[SUCCESS] ✓ 所有容器 healthy"
        break
    fi

    sleep $INTERVAL
done

Step 3: 異常處理

檢測到的異常型別及處理：

異常	處理方式
ImagePullBackOff	報告映象拉取失敗，檢查 tag 和 registry 許可權
CrashLoopBackOff	⚠️ 停止監控，輸出 Pod 日誌，建議檢查應用程式碼
OOMKilled	報告記憶體不足，建議調整 resource limits
Pending (長時間)	檢查節點資源和排程約束
CreateContainerConfigError	報告配置錯誤，檢查 ConfigMap/Secret

CrashLoopBackOff 特殊處理（應用邏輯問題）：

[ERROR] 檢測到 Pod 持續崩潰 (CrashLoopBackOff)

容器: myapp-core-5f8b9c7d4-x2j9k
重啟次數: 5
最近日誌:
  panic: runtime error: index out of range [3]
  goroutine 1 [running]:
  main.handleRequest(...)
      /app/handlers/user.go:42

⚠️ 這是應用邏輯錯誤，部署監控已停止。
建議:
  1. 檢查 handlers/user.go:42 的陣列越界問題
  2. 修復後重新構建映象
  3. 使用 /deploy run uat core 重新部署

如需回滾到上一版本:
  kubectl rollout undo deployment/myapp-core -n $NAMESPACE

Step 4: 監控結束

成功：

[SUCCESS] 部署完成
  耗時: 45s
  元件: core (1/1), ops (1/1), admin (1/1)
  環境: uat

失敗（非邏輯問題）： 提供具體修復建議（配置、資源、網路）。

失敗（邏輯問題）： 停止監控，輸出診斷資訊，明確建議轉交處理。

注意事項

• 監控期間不執行任何修改操作
• CrashLoopBackOff 等應用錯誤立即停止並報告
• 提供回滾命令供使用者選擇
• 超時後不自動重試，等待使用者指示

這是一款質量不錯的部署工具，支援多種主流部署方式，功能覆蓋全面。它的預檢查和監控機制能幫助使用者在部署前發現問題、部署後追蹤狀態，安全性設計也較為合理。主要優點是省心省力、流程完整；不足之處是個別場景下可能出現誤判或報錯時提示不夠明確。總體來說值得使用，但建議先在小環境驗證再用於生產。