feat: 添加状态缓存管理 GitHub Action，支持多种操作模式（获取、设置、删除），实现缓存过期控制，优化状态管理逻辑，更新文档以反映新功能和使用示例。

cache-state/examples/deployment-state.yml

@@ -0,0 +1,200 @@
+# 部署状态管理示例
+# 演示如何在部署工作流中使用状态缓存来跟踪部署进度和状态
+
+name: Cache State - 部署状态管理
+
+on:
+  push:
+    branches: [main, develop]
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: '部署环境'
+        required: true
+        default: 'staging'
+        type: choice
+        options:
+          - staging
+          - production
+      force_deploy:
+        description: '强制部署（忽略上次部署状态）'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  check-deployment-state:
+    runs-on: ubuntu-latest
+    outputs:
+      should-deploy: ${{ steps.deploy-decision.outputs.should-deploy }}
+      last-deployed-sha: ${{ steps.last-deploy.outputs.state-value }}
+      environment: ${{ steps.env-state.outputs.state-value }}
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 获取环境配置
+        id: env-state
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'target-environment-${{ github.ref_name }}'
+          state-value: ${{ github.event.inputs.environment || 'staging' }}
+          default-value: 'staging'
+          cache-prefix: 'deploy-env'
+
+      - name: 检查上次部署的SHA
+        id: last-deploy
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'last-deployed-sha-${{ steps.env-state.outputs.state-value }}'
+          default-value: 'none'
+          action: 'get'
+
+      - name: 检查部署状态
+        id: deploy-status
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'deploy-status-${{ steps.env-state.outputs.state-value }}'
+          default-value: 'idle'
+          action: 'get'
+
+      - name: 决定是否需要部署
+        id: deploy-decision
+        run: |
+          FORCE_DEPLOY="${{ github.event.inputs.force_deploy }}"
+          LAST_SHA="${{ steps.last-deploy.outputs.state-value }}"
+          CURRENT_SHA="${{ github.sha }}"
+          DEPLOY_STATUS="${{ steps.deploy-status.outputs.state-value }}"
+          
+          echo "🔍 部署决策分析:"
+          echo "  - 强制部署: ${FORCE_DEPLOY}"
+          echo "  - 上次部署SHA: ${LAST_SHA}"
+          echo "  - 当前SHA: ${CURRENT_SHA}"
+          echo "  - 部署状态: ${DEPLOY_STATUS}"
+          
+          if [[ "${FORCE_DEPLOY}" == "true" ]]; then
+            echo "✅ 强制部署模式，将执行部署"
+            echo "should-deploy=true" >> $GITHUB_OUTPUT
+          elif [[ "${DEPLOY_STATUS}" == "deploying" ]]; then
+            echo "⚠️ 检测到正在进行的部署，跳过"
+            echo "should-deploy=false" >> $GITHUB_OUTPUT
+          elif [[ "${LAST_SHA}" != "${CURRENT_SHA}" || "${LAST_SHA}" == "none" ]]; then
+            echo "✅ 检测到新的变更，需要部署"
+            echo "should-deploy=true" >> $GITHUB_OUTPUT
+          else
+            echo "ℹ️ 没有新的变更，跳过部署"
+            echo "should-deploy=false" >> $GITHUB_OUTPUT
+          fi
+
+  deploy:
+    needs: check-deployment-state
+    if: needs.check-deployment-state.outputs.should-deploy == 'true'
+    runs-on: ubuntu-latest
+    environment: ${{ needs.check-deployment-state.outputs.environment }}
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 标记部署开始
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'deploy-status-${{ needs.check-deployment-state.outputs.environment }}'
+          state-value: 'deploying'
+          action: 'set'
+
+      - name: 记录部署开始时间
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'deploy-start-time-${{ needs.check-deployment-state.outputs.environment }}'
+          state-value: ${{ github.run_started_at }}
+          action: 'set'
+
+      - name: 模拟部署过程
+        run: |
+          echo "🚀 开始部署到 ${{ needs.check-deployment-state.outputs.environment }} 环境..."
+          echo "📦 部署版本: ${{ github.sha }}"
+          
+          # 模拟部署步骤
+          for i in {1..5}; do
+            echo "  步骤 ${i}/5: 部署进行中..."
+            sleep 2
+          done
+          
+          echo "✅ 部署完成!"
+
+      - name: 记录成功部署的SHA
+        if: success()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'last-deployed-sha-${{ needs.check-deployment-state.outputs.environment }}'
+          state-value: ${{ github.sha }}
+          action: 'set'
+
+      - name: 标记部署成功
+        if: success()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'deploy-status-${{ needs.check-deployment-state.outputs.environment }}'
+          state-value: 'success'
+          action: 'set'
+
+      - name: 记录部署完成时间
+        if: success()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'deploy-end-time-${{ needs.check-deployment-state.outputs.environment }}'
+          state-value: ${{ github.event.head_commit.timestamp }}
+          action: 'set'
+
+      - name: 标记部署失败
+        if: failure()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'deploy-status-${{ needs.check-deployment-state.outputs.environment }}'
+          state-value: 'failed'
+          action: 'set'
+
+      - name: 记录失败信息
+        if: failure()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'deploy-error-${{ needs.check-deployment-state.outputs.environment }}'
+          state-value: 'Deployment failed at ${{ github.event.head_commit.timestamp }}'
+          action: 'set'
+
+  post-deploy:
+    needs: [check-deployment-state, deploy]
+    if: always() && needs.check-deployment-state.outputs.should-deploy == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: 获取最终部署状态
+        id: final-status
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'deploy-status-${{ needs.check-deployment-state.outputs.environment }}'
+          default-value: 'unknown'
+          action: 'get'
+
+      - name: 部署状态总结
+        run: |
+          echo "📊 部署状态总结:"
+          echo "  - 环境: ${{ needs.check-deployment-state.outputs.environment }}"
+          echo "  - 最终状态: ${{ steps.final-status.outputs.state-value }}"
+          echo "  - 部署SHA: ${{ github.sha }}"
+          
+          if [[ "${{ steps.final-status.outputs.state-value }}" == "success" ]]; then
+            echo "🎉 部署成功完成!"
+          elif [[ "${{ steps.final-status.outputs.state-value }}" == "failed" ]]; then
+            echo "❌ 部署失败，请检查日志"
+          else
+            echo "⚠️ 部署状态未知"
+          fi
+
+      # 清理部署锁定状态（如果需要）
+      - name: 清理部署锁定
+        if: always()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'deploy-status-${{ needs.check-deployment-state.outputs.environment }}'
+          state-value: 'idle'
+          action: 'set'