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

cache-state/examples/basic-usage.yml

@@ -0,0 +1,77 @@
+# 基础使用示例
+# 演示如何使用 cache-state action 进行基本的状态管理
+
+name: Cache State - 基础使用示例
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: '要设置的版本号'
+        required: false
+        default: 'v1.0.0'
+
+jobs:
+  demo-basic-usage:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 获取或设置应用版本
+        id: app-version
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'application-version'
+          state-value: ${{ github.event.inputs.version }}
+          default-value: 'v0.1.0'
+          action: 'get-or-set'
+
+      - name: 显示版本信息
+        run: |
+          echo "🏷️ 应用版本: ${{ steps.app-version.outputs.state-value }}"
+          echo "💾 缓存命中: ${{ steps.app-version.outputs.cache-hit }}"
+          echo "🔄 使用默认值: ${{ steps.app-version.outputs.used-default }}"
+          echo "🔑 缓存键: ${{ steps.app-version.outputs.cache-key }}"
+
+      - name: 基于版本信息的条件操作
+        run: |
+          if [[ "${{ steps.app-version.outputs.used-default }}" == "true" ]]; then
+            echo "⚠️ 使用了默认版本，可能是首次运行"
+            echo "执行初始化操作..."
+          else
+            echo "✅ 使用了已有版本或新设置的版本"
+            echo "执行常规操作..."
+          fi
+
+      - name: 记录构建状态
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'last-build-status'
+          state-value: 'success'
+          action: 'set'
+
+      - name: 获取构建历史
+        id: build-history
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'build-count'
+          state-value: '1'
+          default-value: '0'
+          action: 'get-or-set'
+
+      - name: 更新构建计数
+        run: |
+          CURRENT_COUNT=${{ steps.build-history.outputs.state-value }}
+          NEW_COUNT=$((CURRENT_COUNT + 1))
+          echo "当前构建次数: ${CURRENT_COUNT}"
+          echo "新的构建次数: ${NEW_COUNT}"
+
+      - name: 保存新的构建计数
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'build-count'
+          state-value: ${{ env.NEW_COUNT }}
+          action: 'set'
+        env:
+          NEW_COUNT: ${{ steps.build-history.outputs.state-value == '0' && '1' || format('{0}', steps.build-history.outputs.state-value + 1) }}

cache-state/examples/delete-demo.yml

@@ -0,0 +1,263 @@
+# 删除功能演示
+# 展示如何使用 cache-state action 的删除功能
+
+name: Cache State - 删除功能演示
+
+on:
+  workflow_dispatch:
+    inputs:
+      demo_type:
+        description: '演示类型'
+        required: true
+        default: 'basic'
+        type: choice
+        options:
+          - basic
+          - cleanup
+          - conditional
+          - batch
+
+jobs:
+  demo-basic-delete:
+    if: ${{ inputs.demo_type == 'basic' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 设置测试状态
+        id: setup-state
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "demo-delete-test"
+          state-value: "test-value-${{ github.run_id }}"
+          action: "set"
+
+      - name: 验证状态已设置
+        id: verify-set
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "demo-delete-test"
+          default-value: "not-found"
+          action: "get"
+
+      - name: 显示设置结果
+        run: |
+          echo "设置的值: ${{ steps.verify-set.outputs.state-value }}"
+          echo "缓存命中: ${{ steps.verify-set.outputs.cache-hit }}"
+          
+          if [[ "${{ steps.verify-set.outputs.cache-hit }}" == "true" ]]; then
+            echo "✅ 状态设置成功"
+          else
+            echo "❌ 状态设置失败"
+            exit 1
+          fi
+
+      - name: 删除状态
+        id: delete-state
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "demo-delete-test"
+          action: "del"
+
+      - name: 验证删除结果
+        run: |
+          echo "删除操作: ${{ steps.delete-state.outputs.deleted }}"
+          echo "缓存键: ${{ steps.delete-state.outputs.cache-key }}"
+          
+          if [[ "${{ steps.delete-state.outputs.deleted }}" == "true" ]]; then
+            echo "✅ 删除操作执行成功"
+          else
+            echo "❌ 删除操作失败"
+            exit 1
+          fi
+
+      - name: 验证状态已删除
+        id: verify-deleted
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "demo-delete-test"
+          default-value: "fallback-value"
+          action: "get"
+
+      - name: 确认删除效果
+        run: |
+          echo "验证获取的值: ${{ steps.verify-deleted.outputs.state-value }}"
+          echo "缓存命中: ${{ steps.verify-deleted.outputs.cache-hit }}"
+          echo "使用默认值: ${{ steps.verify-deleted.outputs.used-default }}"
+          
+          if [[ "${{ steps.verify-deleted.outputs.cache-hit }}" == "false" && "${{ steps.verify-deleted.outputs.used-default }}" == "true" ]]; then
+            echo "✅ 状态已成功删除，使用默认值"
+          else
+            echo "❌ 状态删除验证失败"
+            exit 1
+          fi
+
+  demo-cleanup-workflow:
+    if: ${{ inputs.demo_type == 'cleanup' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 创建多个测试状态
+        run: |
+          echo "创建多个测试状态用于清理演示..."
+
+      - name: 设置构建状态
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "build-status-${{ github.run_id }}"
+          state-value: "completed"
+          action: "set"
+
+      - name: 设置部署状态
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "deploy-status-${{ github.run_id }}"
+          state-value: "success"
+          action: "set"
+
+      - name: 设置测试状态
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "test-status-${{ github.run_id }}"
+          state-value: "passed"
+          action: "set"
+
+      - name: 模拟工作流结束后的清理
+        run: |
+          echo "🧹 开始清理工作流状态..."
+
+      - name: 清理构建状态
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "build-status-${{ github.run_id }}"
+          action: "del"
+
+      - name: 清理部署状态
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "deploy-status-${{ github.run_id }}"
+          action: "del"
+
+      - name: 清理测试状态
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "test-status-${{ github.run_id }}"
+          action: "del"
+
+      - name: 清理完成
+        run: |
+          echo "✅ 所有状态已清理完成"
+
+  demo-conditional-delete:
+    if: ${{ inputs.demo_type == 'conditional' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 检查现有状态
+        id: check-state
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "conditional-delete-test"
+          default-value: "none"
+          action: "get"
+
+      - name: 显示当前状态
+        run: |
+          echo "当前状态: ${{ steps.check-state.outputs.state-value }}"
+          echo "缓存命中: ${{ steps.check-state.outputs.cache-hit }}"
+
+      - name: 条件性删除 - 如果状态存在
+        if: ${{ steps.check-state.outputs.cache-hit == 'true' }}
+        id: conditional-delete
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "conditional-delete-test"
+          action: "del"
+
+      - name: 条件性设置 - 如果状态不存在
+        if: ${{ steps.check-state.outputs.cache-hit != 'true' }}
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "conditional-delete-test"
+          state-value: "newly-created-${{ github.run_id }}"
+          action: "set"
+
+      - name: 显示操作结果
+        run: |
+          if [[ "${{ steps.check-state.outputs.cache-hit }}" == "true" ]]; then
+            echo "🗑️ 执行了删除操作"
+            echo "删除结果: ${{ steps.conditional-delete.outputs.deleted }}"
+          else
+            echo "🆕 执行了创建操作"
+          fi
+
+  demo-batch-operations:
+    if: ${{ inputs.demo_type == 'batch' }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        operation: [create, delete]
+        state_id: [1, 2, 3]
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 批量创建状态
+        if: ${{ matrix.operation == 'create' }}
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "batch-state-${{ matrix.state_id }}"
+          state-value: "batch-value-${{ matrix.state_id }}-${{ github.run_id }}"
+          action: "set"
+
+      - name: 批量删除状态
+        if: ${{ matrix.operation == 'delete' }}
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "batch-state-${{ matrix.state_id }}"
+          action: "del"
+
+      - name: 显示操作结果
+        run: |
+          echo "操作: ${{ matrix.operation }}"
+          echo "状态ID: ${{ matrix.state_id }}"
+          echo "✅ 批量操作 ${{ matrix.operation }} 完成"
+
+  demo-summary:
+    needs: [demo-basic-delete, demo-cleanup-workflow, demo-conditional-delete, demo-batch-operations]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: 生成演示总结
+        run: |
+          echo "## 🗑️ 删除功能演示总结" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 演示类型: ${{ inputs.demo_type }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          case "${{ inputs.demo_type }}" in
+            "basic")
+              echo "✅ **基础删除演示**: 展示了设置、删除、验证的完整流程" >> $GITHUB_STEP_SUMMARY
+              ;;
+            "cleanup")
+              echo "✅ **清理工作流演示**: 展示了批量清理多个状态的用法" >> $GITHUB_STEP_SUMMARY
+              ;;
+            "conditional")
+              echo "✅ **条件删除演示**: 展示了基于状态存在性的条件操作" >> $GITHUB_STEP_SUMMARY
+              ;;
+            "batch")
+              echo "✅ **批量操作演示**: 展示了并行批量创建和删除状态" >> $GITHUB_STEP_SUMMARY
+              ;;
+          esac
+          
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 核心特性" >> $GITHUB_STEP_SUMMARY
+          echo "- 🗑️ **状态删除**: 通过删除标记实现状态清除" >> $GITHUB_STEP_SUMMARY
+          echo "- 🔄 **即时生效**: 删除后立即生效，后续访问使用默认值" >> $GITHUB_STEP_SUMMARY
+          echo "- 📊 **状态透明**: 通过 \`deleted\` 输出明确告知删除操作" >> $GITHUB_STEP_SUMMARY
+          echo "- 🛡️ **安全可靠**: 基于缓存覆盖机制，不会影响其他状态" >> $GITHUB_STEP_SUMMARY

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'

cache-state/examples/error-handling.yml

@@ -0,0 +1,377 @@
+# 错误处理和恢复示例
+# 演示如何使用状态缓存进行错误处理、状态恢复和重试逻辑
+
+name: Cache State - 错误处理示例
+
+on:
+  workflow_dispatch:
+    inputs:
+      simulate_error:
+        description: '模拟错误类型'
+        required: false
+        default: 'none'
+        type: choice
+        options:
+          - none
+          - network_error
+          - build_failure
+          - deployment_error
+      recovery_mode:
+        description: '恢复模式'
+        required: false
+        default: 'auto'
+        type: choice
+        options:
+          - auto
+          - manual
+          - skip
+
+jobs:
+  initialize-operation:
+    runs-on: ubuntu-latest
+    outputs:
+      operation-id: ${{ steps.operation-setup.outputs.operation-id }}
+      should-continue: ${{ steps.check-previous.outputs.should-continue }}
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 设置操作ID
+        id: operation-setup
+        run: |
+          OPERATION_ID="op-$(date +%s)-${{ github.run_number }}"
+          echo "operation-id=${OPERATION_ID}" >> $GITHUB_OUTPUT
+          echo "🆔 操作ID: ${OPERATION_ID}"
+
+      - name: 检查上次操作状态
+        id: last-operation
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'last-operation-status'
+          default-value: 'none'
+          action: 'get'
+          cache-prefix: 'operation'
+
+      - name: 检查是否有失败的操作需要恢复
+        id: check-previous
+        run: |
+          LAST_STATUS="${{ steps.last-operation.outputs.state-value }}"
+          RECOVERY_MODE="${{ github.event.inputs.recovery_mode }}"
+          
+          echo "🔍 检查上次操作状态: ${LAST_STATUS}"
+          echo "🔧 恢复模式: ${RECOVERY_MODE}"
+          
+          if [[ "${LAST_STATUS}" == "failed" || "${LAST_STATUS}" == "partial" ]]; then
+            echo "⚠️ 检测到失败的操作需要处理"
+            
+            case "${RECOVERY_MODE}" in
+              "auto")
+                echo "🔄 自动恢复模式，将继续操作"
+                echo "should-continue=true" >> $GITHUB_OUTPUT
+                ;;
+              "manual")
+                echo "✋ 手动恢复模式，需要人工干预"
+                echo "should-continue=false" >> $GITHUB_OUTPUT
+                exit 1
+                ;;
+              "skip")
+                echo "⏭️ 跳过恢复，开始新操作"
+                echo "should-continue=true" >> $GITHUB_OUTPUT
+                ;;
+            esac
+          else
+            echo "✅ 没有失败的操作，正常继续"
+            echo "should-continue=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: 记录操作开始
+        if: steps.check-previous.outputs.should-continue == 'true'
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'current-operation-id'
+          state-value: ${{ steps.operation-setup.outputs.operation-id }}
+          action: 'set'
+          cache-prefix: 'operation'
+
+      - name: 记录操作状态为进行中
+        if: steps.check-previous.outputs.should-continue == 'true'
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'last-operation-status'
+          state-value: 'running'
+          action: 'set'
+          cache-prefix: 'operation'
+
+  build-with-retry:
+    needs: initialize-operation
+    if: needs.initialize-operation.outputs.should-continue == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 检查构建重试状态
+        id: retry-status
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'build-retry-count-${{ needs.initialize-operation.outputs.operation-id }}'
+          default-value: '0'
+          action: 'get'
+          cache-prefix: 'retry'
+
+      - name: 准备构建重试
+        id: prepare-retry
+        run: |
+          CURRENT_RETRY=${{ steps.retry-status.outputs.state-value }}
+          MAX_RETRIES=3
+          
+          echo "🔄 当前重试次数: ${CURRENT_RETRY}/${MAX_RETRIES}"
+          
+          if [[ ${CURRENT_RETRY} -ge ${MAX_RETRIES} ]]; then
+            echo "❌ 已达到最大重试次数"
+            echo "can-retry=false" >> $GITHUB_OUTPUT
+            exit 1
+          else
+            echo "✅ 可以继续重试"
+            echo "can-retry=true" >> $GITHUB_OUTPUT
+            echo "next-retry=$((CURRENT_RETRY + 1))" >> $GITHUB_OUTPUT
+          fi
+
+      - name: 模拟构建过程
+        id: build
+        run: |
+          echo "🔨 开始构建过程..."
+          
+          # 根据输入模拟不同类型的错误
+          case "${{ github.event.inputs.simulate_error }}" in
+            "build_failure")
+              echo "❌ 模拟构建失败"
+              exit 1
+              ;;
+            "network_error")
+              echo "🌐 模拟网络错误"
+              sleep 2
+              exit 1
+              ;;
+            *)
+              echo "✅ 构建成功"
+              ;;
+          esac
+
+      - name: 更新重试计数（失败时）
+        if: failure()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'build-retry-count-${{ needs.initialize-operation.outputs.operation-id }}'
+          state-value: ${{ steps.prepare-retry.outputs.next-retry }}
+          action: 'set'
+          cache-prefix: 'retry'
+
+      - name: 记录构建失败状态
+        if: failure()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'build-status-${{ needs.initialize-operation.outputs.operation-id }}'
+          state-value: 'failed'
+          action: 'set'
+          cache-prefix: 'build'
+
+      - name: 记录构建失败时间
+        if: failure()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'build-failure-time-${{ needs.initialize-operation.outputs.operation-id }}'
+          state-value: ${{ github.event.head_commit.timestamp }}
+          action: 'set'
+          cache-prefix: 'build'
+
+      - name: 清理重试计数（成功时）
+        if: success()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'build-retry-count-${{ needs.initialize-operation.outputs.operation-id }}'
+          state-value: ''
+          action: 'set'
+          cache-prefix: 'retry'
+
+      - name: 记录构建成功状态
+        if: success()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'build-status-${{ needs.initialize-operation.outputs.operation-id }}'
+          state-value: 'success'
+          action: 'set'
+          cache-prefix: 'build'
+
+  deploy-with-rollback:
+    needs: [initialize-operation, build-with-retry]
+    if: success()
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 获取上次成功的部署版本
+        id: last-deploy
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'last-successful-deployment'
+          default-value: 'v1.0.0'
+          action: 'get'
+          cache-prefix: 'deploy'
+
+      - name: 备份当前部署状态
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'deployment-backup-${{ needs.initialize-operation.outputs.operation-id }}'
+          state-value: ${{ steps.last-deploy.outputs.state-value }}
+          action: 'set'
+          cache-prefix: 'backup'
+
+      - name: 模拟部署过程
+        id: deploy
+        run: |
+          echo "🚀 开始部署..."
+          echo "📦 部署版本: ${{ github.sha }}"
+          echo "🔙 备份版本: ${{ steps.last-deploy.outputs.state-value }}"
+          
+          # 模拟部署错误
+          if [[ "${{ github.event.inputs.simulate_error }}" == "deployment_error" ]]; then
+            echo "❌ 模拟部署失败"
+            exit 1
+          fi
+          
+          echo "✅ 部署成功"
+
+      - name: 记录部署成功
+        if: success()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'last-successful-deployment'
+          state-value: ${{ github.sha }}
+          action: 'set'
+          cache-prefix: 'deploy'
+
+      - name: 清理备份（成功时）
+        if: success()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'deployment-backup-${{ needs.initialize-operation.outputs.operation-id }}'
+          state-value: ''
+          action: 'set'
+          cache-prefix: 'backup'
+
+      - name: 执行回滚（失败时）
+        if: failure()
+        run: |
+          echo "🔄 部署失败，开始回滚..."
+          ROLLBACK_VERSION="${{ steps.last-deploy.outputs.state-value }}"
+          echo "回滚到版本: ${ROLLBACK_VERSION}"
+          
+          # 这里执行实际的回滚操作
+          echo "✅ 回滚完成"
+
+      - name: 记录回滚状态
+        if: failure()
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'rollback-executed-${{ needs.initialize-operation.outputs.operation-id }}'
+          state-value: 'true'
+          action: 'set'
+          cache-prefix: 'rollback'
+
+  finalize-operation:
+    needs: [initialize-operation, build-with-retry, deploy-with-rollback]
+    if: always() && needs.initialize-operation.outputs.should-continue == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 确定最终操作状态
+        id: final-status
+        run: |
+          BUILD_RESULT="${{ needs.build-with-retry.result }}"
+          DEPLOY_RESULT="${{ needs.deploy-with-rollback.result }}"
+          
+          echo "🔍 构建结果: ${BUILD_RESULT}"
+          echo "🔍 部署结果: ${DEPLOY_RESULT}"
+          
+          if [[ "${BUILD_RESULT}" == "success" && "${DEPLOY_RESULT}" == "success" ]]; then
+            FINAL_STATUS="success"
+          elif [[ "${BUILD_RESULT}" == "failure" ]]; then
+            FINAL_STATUS="build_failed"
+          elif [[ "${DEPLOY_RESULT}" == "failure" ]]; then
+            FINAL_STATUS="deploy_failed"
+          elif [[ "${BUILD_RESULT}" == "success" && "${DEPLOY_RESULT}" == "skipped" ]]; then
+            FINAL_STATUS="partial"
+          else
+            FINAL_STATUS="unknown"
+          fi
+          
+          echo "final-status=${FINAL_STATUS}" >> $GITHUB_OUTPUT
+          echo "🏁 最终状态: ${FINAL_STATUS}"
+
+      - name: 记录最终操作状态
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'last-operation-status'
+          state-value: ${{ steps.final-status.outputs.final-status }}
+          action: 'set'
+          cache-prefix: 'operation'
+
+      - name: 记录操作完成时间
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'last-operation-time'
+          state-value: ${{ github.event.head_commit.timestamp }}
+          action: 'set'
+          cache-prefix: 'operation'
+
+      - name: 生成错误处理报告
+        run: |
+          echo "📋 错误处理和恢复报告"
+          echo "========================"
+          echo "操作ID: ${{ needs.initialize-operation.outputs.operation-id }}"
+          echo "最终状态: ${{ steps.final-status.outputs.final-status }}"
+          echo "模拟错误类型: ${{ github.event.inputs.simulate_error }}"
+          echo "恢复模式: ${{ github.event.inputs.recovery_mode }}"
+          echo ""
+          
+          case "${{ steps.final-status.outputs.final-status }}" in
+            "success")
+              echo "✅ 操作成功完成"
+              ;;
+            "build_failed")
+              echo "❌ 构建失败，请检查构建日志"
+              ;;
+            "deploy_failed")
+              echo "❌ 部署失败，已执行回滚"
+              ;;
+            "partial")
+              echo "⚠️ 部分完成，可能需要手动干预"
+              ;;
+            *)
+              echo "❓ 状态未知，需要进一步调查"
+              ;;
+          esac
+
+  cleanup-expired-states:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 清理过期的重试状态
+        run: |
+          echo "🧹 清理过期的状态信息..."
+          # 这里可以实现清理逻辑
+          # 例如，清理超过一定时间的重试计数、备份等临时状态
+
+      - name: 清理示例 - 重置错误计数
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'error-count-global'
+          state-value: '0'
+          action: 'set'
+          cache-prefix: 'cleanup'

cache-state/examples/expiry-demo.yml

@@ -0,0 +1,243 @@
+# 过期时间功能演示
+# 展示如何使用 cache-state action 的过期时间功能
+
+name: Cache State - 过期时间演示
+
+on:
+  workflow_dispatch:
+    inputs:
+      demo_type:
+        description: '演示类型'
+        required: true
+        default: 'basic'
+        type: choice
+        options:
+          - basic
+          - session
+          - build-lock
+          - rate-limit
+
+jobs:
+  demo-basic-expiry:
+    if: ${{ inputs.demo_type == 'basic' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 设置短期缓存（5分钟过期）
+        id: short-cache
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "demo-short-cache"
+          state-value: "cached-at-${{ github.run_started_at }}"
+          default-value: "no-cache"
+          expiry-seconds: "300"  # 5分钟
+          action: "get-or-set"
+
+      - name: 显示缓存状态
+        run: |
+          echo "缓存值: ${{ steps.short-cache.outputs.state-value }}"
+          echo "缓存命中: ${{ steps.short-cache.outputs.cache-hit }}"
+          echo "缓存过期: ${{ steps.short-cache.outputs.expired }}"
+          echo "使用默认值: ${{ steps.short-cache.outputs.used-default }}"
+
+      - name: 等待1分钟
+        run: sleep 60
+
+      - name: 再次获取缓存（应该仍然有效）
+        id: check-cache
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "demo-short-cache"
+          default-value: "expired"
+          expiry-seconds: "300"
+          action: "get"
+
+      - name: 验证缓存仍然有效
+        run: |
+          echo "再次获取的值: ${{ steps.check-cache.outputs.state-value }}"
+          echo "缓存命中: ${{ steps.check-cache.outputs.cache-hit }}"
+          
+          if [[ "${{ steps.check-cache.outputs.cache-hit }}" == "true" ]]; then
+            echo "✅ 缓存在1分钟后仍然有效"
+          else
+            echo "❌ 缓存意外失效"
+          fi
+
+  demo-session-management:
+    if: ${{ inputs.demo_type == 'session' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 创建用户会话（1小时过期）
+        id: user-session
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "user-session-${{ github.actor }}"
+          state-value: "session-${{ github.run_id }}"
+          default-value: "no-session"
+          expiry-seconds: "3600"  # 1小时
+          action: "get-or-set"
+
+      - name: 处理会话状态
+        run: |
+          SESSION_VALUE="${{ steps.user-session.outputs.state-value }}"
+          
+          echo "用户: ${{ github.actor }}"
+          echo "会话状态: ${SESSION_VALUE}"
+          echo "缓存命中: ${{ steps.user-session.outputs.cache-hit }}"
+          echo "缓存过期: ${{ steps.user-session.outputs.expired }}"
+          
+          if [[ "${{ steps.user-session.outputs.expired }}" == "true" ]]; then
+            echo "⏰ 会话已过期，创建新会话"
+          elif [[ "${{ steps.user-session.outputs.cache-hit }}" == "true" ]]; then
+            echo "✅ 会话仍然有效，继续使用"
+          else
+            echo "🆕 首次创建会话"
+          fi
+
+      - name: 模拟会话活动
+        run: |
+          echo "执行一些需要会话的操作..."
+          echo "会话ID: ${{ steps.user-session.outputs.state-value }}"
+
+  demo-build-lock:
+    if: ${{ inputs.demo_type == 'build-lock' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 检查构建锁定状态（10分钟过期）
+        id: build-lock
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "build-lock-${{ github.repository }}"
+          state-value: "locked-by-${{ github.run_id }}"
+          default-value: "unlocked"
+          expiry-seconds: "600"  # 10分钟
+          action: "get-or-set"
+
+      - name: 处理构建锁定
+        run: |
+          LOCK_VALUE="${{ steps.build-lock.outputs.state-value }}"
+          
+          echo "构建锁定状态: ${LOCK_VALUE}"
+          echo "缓存命中: ${{ steps.build-lock.outputs.cache-hit }}"
+          echo "缓存过期: ${{ steps.build-lock.outputs.expired }}"
+          
+          if [[ "${LOCK_VALUE}" == "unlocked" ]]; then
+            echo "✅ 没有构建锁定，可以开始构建"
+          elif [[ "${LOCK_VALUE}" == "locked-by-${{ github.run_id }}" ]]; then
+            echo "✅ 当前运行获得了构建锁"
+          elif [[ "${{ steps.build-lock.outputs.expired }}" == "true" ]]; then
+            echo "⏰ 构建锁已过期，获得新锁"
+          else
+            echo "⚠️ 构建被其他运行锁定: ${LOCK_VALUE}"
+            echo "等待锁定过期或手动解锁"
+            exit 1
+          fi
+
+      - name: 模拟构建过程
+        run: |
+          echo "🔨 开始构建..."
+          sleep 30
+          echo "✅ 构建完成"
+
+      - name: 释放构建锁
+        if: always()
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "build-lock-${{ github.repository }}"
+          state-value: "unlocked"
+          expiry-seconds: "600"
+          action: "set"
+
+  demo-rate-limiting:
+    if: ${{ inputs.demo_type == 'rate-limit' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 检查API调用限制（1分钟窗口）
+        id: api-limit
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "api-calls-${{ github.actor }}"
+          state-value: "1"
+          default-value: "0"
+          expiry-seconds: "60"  # 1分钟窗口
+          action: "get-or-set"
+
+      - name: 处理速率限制
+        run: |
+          CALL_COUNT="${{ steps.api-limit.outputs.state-value }}"
+          MAX_CALLS=5
+          
+          echo "当前调用次数: ${CALL_COUNT}/${MAX_CALLS}"
+          echo "缓存命中: ${{ steps.api-limit.outputs.cache-hit }}"
+          echo "缓存过期: ${{ steps.api-limit.outputs.expired }}"
+          
+          if [[ "${{ steps.api-limit.outputs.expired }}" == "true" ]]; then
+            echo "⏰ 速率限制窗口已重置"
+          fi
+          
+          if [[ ${CALL_COUNT} -le ${MAX_CALLS} ]]; then
+            echo "✅ 在速率限制内，可以继续调用"
+          else
+            echo "❌ 超出速率限制，请等待"
+            exit 1
+          fi
+
+      - name: 模拟API调用
+        run: |
+          echo "📡 调用API..."
+          sleep 5
+          echo "✅ API调用成功"
+
+      - name: 更新调用计数
+        if: success()
+        uses: actions/xgj/cache-state@v1
+        with:
+          state-key: "api-calls-${{ github.actor }}"
+          state-value: "${{ steps.api-limit.outputs.state-value + 1 }}"
+          expiry-seconds: "60"
+          action: "set"
+
+  demo-summary:
+    needs: [demo-basic-expiry, demo-session-management, demo-build-lock, demo-rate-limiting]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: 生成演示总结
+        run: |
+          echo "## 🎯 过期时间功能演示总结" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 演示类型: ${{ inputs.demo_type }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          case "${{ inputs.demo_type }}" in
+            "basic")
+              echo "✅ **基础过期演示**: 展示了5分钟过期缓存的基本用法" >> $GITHUB_STEP_SUMMARY
+              ;;
+            "session")
+              echo "✅ **会话管理演示**: 展示了1小时过期的用户会话管理" >> $GITHUB_STEP_SUMMARY
+              ;;
+            "build-lock")
+              echo "✅ **构建锁定演示**: 展示了10分钟过期的构建锁定机制" >> $GITHUB_STEP_SUMMARY
+              ;;
+            "rate-limit")
+              echo "✅ **速率限制演示**: 展示了1分钟窗口的API调用限制" >> $GITHUB_STEP_SUMMARY
+              ;;
+          esac
+          
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 核心特性" >> $GITHUB_STEP_SUMMARY
+          echo "- ⏰ **时间窗口过期**: 基于时间窗口的自动过期机制" >> $GITHUB_STEP_SUMMARY
+          echo "- 🔄 **简单实现**: 不依赖复杂工具，使用基础shell命令" >> $GITHUB_STEP_SUMMARY
+          echo "- 📊 **状态透明**: 清晰显示缓存命中、过期状态" >> $GITHUB_STEP_SUMMARY
+          echo "- 🛡️ **安全可靠**: 利用GitHub Actions缓存的天然特性" >> $GITHUB_STEP_SUMMARY

cache-state/examples/feature-flags.yml

@@ -0,0 +1,326 @@
+# 功能开关状态管理示例
+# 演示如何使用状态缓存来管理功能开关、配置参数等动态配置
+
+name: Cache State - 功能开关管理
+
+on:
+  workflow_dispatch:
+    inputs:
+      feature_name:
+        description: '功能名称'
+        required: true
+        default: 'new-ui'
+      feature_enabled:
+        description: '是否启用功能'
+        required: false
+        default: true
+        type: boolean
+      rollout_percentage:
+        description: '灰度发布百分比 (0-100)'
+        required: false
+        default: '50'
+      environment:
+        description: '目标环境'
+        required: false
+        default: 'staging'
+        type: choice
+        options:
+          - development
+          - staging
+          - production
+
+jobs:
+  manage-feature-flags:
+    runs-on: ubuntu-latest
+    outputs:
+      feature-state: ${{ steps.feature-flag.outputs.state-value }}
+      rollout-config: ${{ steps.rollout.outputs.state-value }}
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 获取或设置功能开关状态
+        id: feature-flag
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'feature-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          state-value: ${{ github.event.inputs.feature_enabled }}
+          default-value: 'false'
+          cache-prefix: 'feature-flags'
+          action: 'get-or-set'
+
+      - name: 管理灰度发布配置
+        id: rollout
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'rollout-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          state-value: ${{ github.event.inputs.rollout_percentage }}
+          default-value: '0'
+          cache-prefix: 'rollout-config'
+          action: 'get-or-set'
+
+      - name: 记录功能开关变更历史
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'feature-history-${{ github.event.inputs.feature_name }}'
+          state-value: '${{ github.event.inputs.environment }}:${{ github.event.inputs.feature_enabled }}:${{ github.run_started_at }}'
+          cache-prefix: 'feature-history'
+          action: 'set'
+
+      - name: 验证功能开关配置
+        run: |
+          FEATURE_ENABLED="${{ steps.feature-flag.outputs.state-value }}"
+          ROLLOUT_PERCENT="${{ steps.rollout.outputs.state-value }}"
+          
+          echo "🎛️ 功能开关配置验证:"
+          echo "  - 功能名称: ${{ github.event.inputs.feature_name }}"
+          echo "  - 环境: ${{ github.event.inputs.environment }}"
+          echo "  - 功能状态: ${FEATURE_ENABLED}"
+          echo "  - 灰度百分比: ${ROLLOUT_PERCENT}%"
+          echo "  - 缓存命中: ${{ steps.feature-flag.outputs.cache-hit }}"
+          
+          # 验证配置合理性
+          if [[ "${FEATURE_ENABLED}" == "true" && "${ROLLOUT_PERCENT}" -gt 0 ]]; then
+            echo "✅ 功能配置有效"
+          elif [[ "${FEATURE_ENABLED}" == "false" ]]; then
+            echo "ℹ️ 功能已禁用"
+          else
+            echo "⚠️ 功能配置可能需要检查"
+          fi
+
+  apply-feature-configuration:
+    needs: manage-feature-flags
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        service: [api, frontend, mobile]
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 获取服务特定的功能配置
+        id: service-config
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'service-config-${{ matrix.service }}-${{ github.event.inputs.environment }}'
+          default-value: '{"features":{},"version":"1.0"}'
+          action: 'get'
+          cache-prefix: 'service-config'
+
+      - name: 应用功能配置到服务
+        run: |
+          SERVICE="${{ matrix.service }}"
+          FEATURE_NAME="${{ github.event.inputs.feature_name }}"
+          FEATURE_ENABLED="${{ needs.manage-feature-flags.outputs.feature-state }}"
+          ROLLOUT_PERCENT="${{ needs.manage-feature-flags.outputs.rollout-config }}"
+          
+          echo "🔧 为 ${SERVICE} 服务应用功能配置:"
+          echo "  - 功能: ${FEATURE_NAME}"
+          echo "  - 状态: ${FEATURE_ENABLED}"
+          echo "  - 灰度: ${ROLLOUT_PERCENT}%"
+          
+          # 模拟配置应用过程
+          case "${SERVICE}" in
+            "api")
+              echo "  📡 API服务配置已更新"
+              ;;
+            "frontend")
+              echo "  🌐 前端服务配置已更新"
+              ;;
+            "mobile")
+              echo "  📱 移动端配置已更新"
+              ;;
+          esac
+
+      - name: 更新服务配置状态
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'service-config-applied-${{ matrix.service }}'
+          state-value: '${{ github.event.inputs.feature_name }}:${{ needs.manage-feature-flags.outputs.feature-state }}'
+          cache-prefix: 'service-status'
+          action: 'set'
+
+  monitor-feature-metrics:
+    needs: [manage-feature-flags, apply-feature-configuration]
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 初始化功能监控指标
+        id: init-metrics
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'metrics-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          default-value: '{"users":0,"errors":0,"performance":100}'
+          action: 'get'
+          cache-prefix: 'feature-metrics'
+
+      - name: 模拟收集功能使用指标
+        run: |
+          echo "📊 收集功能使用指标..."
+          
+          # 模拟指标收集
+          USERS_COUNT=$((RANDOM % 1000 + 100))
+          ERROR_COUNT=$((RANDOM % 10))
+          PERFORMANCE_SCORE=$((RANDOM % 20 + 80))
+          
+          echo "  - 用户数: ${USERS_COUNT}"
+          echo "  - 错误数: ${ERROR_COUNT}"
+          echo "  - 性能分数: ${PERFORMANCE_SCORE}"
+          
+          # 保存到环境变量供后续步骤使用
+          echo "users_count=${USERS_COUNT}" >> $GITHUB_ENV
+          echo "error_count=${ERROR_COUNT}" >> $GITHUB_ENV
+          echo "performance_score=${PERFORMANCE_SCORE}" >> $GITHUB_ENV
+
+      - name: 更新功能监控指标
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'metrics-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          state-value: '{"users":${{ env.users_count }},"errors":${{ env.error_count }},"performance":${{ env.performance_score }}}'
+          cache-prefix: 'feature-metrics'
+          action: 'set'
+
+      - name: 分析指标异常
+        run: |
+          ERROR_COUNT=${{ env.error_count }}
+          PERFORMANCE_SCORE=${{ env.performance_score }}
+          
+          echo "🔍 指标异常分析:"
+          
+          if [[ ${ERROR_COUNT} -gt 5 ]]; then
+            echo "⚠️ 错误率偏高，可能需要回滚功能"
+            echo "alert=high_error_rate" >> $GITHUB_ENV
+          elif [[ ${PERFORMANCE_SCORE} -lt 70 ]]; then
+            echo "⚠️ 性能下降，需要关注"
+            echo "alert=performance_degradation" >> $GITHUB_ENV
+          else
+            echo "✅ 指标正常"
+            echo "alert=none" >> $GITHUB_ENV
+          fi
+
+      - name: 记录异常告警
+        if: env.alert != 'none'
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'alert-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          state-value: '${{ env.alert }}:${{ github.run_started_at }}'
+          cache-prefix: 'alerts'
+          action: 'set'
+
+  feature-rollback-if-needed:
+    needs: [manage-feature-flags, monitor-feature-metrics]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 检查是否需要回滚
+        id: check-rollback
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'alert-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          default-value: 'none'
+          action: 'get'
+          cache-prefix: 'alerts'
+
+      - name: 执行自动回滚
+        if: contains(steps.check-rollback.outputs.state-value, 'high_error_rate')
+        run: |
+          echo "🔄 检测到高错误率，执行自动回滚..."
+          echo "功能: ${{ github.event.inputs.feature_name }}"
+          echo "环境: ${{ github.event.inputs.environment }}"
+
+      - name: 禁用功能开关
+        if: contains(steps.check-rollback.outputs.state-value, 'high_error_rate')
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'feature-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          state-value: 'false'
+          cache-prefix: 'feature-flags'
+          action: 'set'
+
+      - name: 记录回滚操作
+        if: contains(steps.check-rollback.outputs.state-value, 'high_error_rate')
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'rollback-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          state-value: 'auto-rollback:${{ github.run_started_at }}'
+          cache-prefix: 'rollback-history'
+          action: 'set'
+
+  generate-feature-report:
+    needs: [manage-feature-flags, apply-feature-configuration, monitor-feature-metrics, feature-rollback-if-needed]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 收集所有功能状态
+        run: |
+          echo "📋 功能开关管理报告"
+          echo "===================="
+          echo "时间: $(date)"
+          echo "功能: ${{ github.event.inputs.feature_name }}"
+          echo "环境: ${{ github.event.inputs.environment }}"
+          echo ""
+
+      - name: 获取最终功能状态
+        id: final-state
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'feature-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          action: 'get'
+          cache-prefix: 'feature-flags'
+
+      - name: 获取监控指标
+        id: final-metrics
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'metrics-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          action: 'get'
+          cache-prefix: 'feature-metrics'
+
+      - name: 检查回滚历史
+        id: rollback-check
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'rollback-${{ github.event.inputs.feature_name }}-${{ github.event.inputs.environment }}'
+          default-value: 'none'
+          action: 'get'
+          cache-prefix: 'rollback-history'
+
+      - name: 生成最终报告
+        run: |
+          echo "✅ 功能状态管理完成"
+          echo ""
+          echo "📊 最终状态:"
+          echo "  - 功能状态: ${{ steps.final-state.outputs.state-value }}"
+          echo "  - 监控指标: ${{ steps.final-metrics.outputs.state-value }}"
+          echo "  - 回滚历史: ${{ steps.rollback-check.outputs.state-value }}"
+          echo ""
+          echo "🎯 下次运行时，这些状态将被保留并可以继续使用。"
+
+  cleanup-old-feature-states:
+    runs-on: ubuntu-latest
+    if: github.event.inputs.environment == 'development'  # 只在开发环境清理
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 清理过期的功能状态
+        run: |
+          echo "🧹 清理开发环境的过期功能状态..."
+          # 这里可以实现清理逻辑
+          # 例如，清理超过一定时间的开发环境功能开关
+
+      - name: 重置开发环境告警
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'dev-alerts-cleared'
+          state-value: '${{ github.run_started_at }}'
+          cache-prefix: 'cleanup'
+          action: 'set'

cache-state/examples/multi-environment.yml

@@ -0,0 +1,290 @@
+# 多环境状态管理示例
+# 演示如何在多环境部署中使用状态缓存来管理不同环境的配置和状态
+
+name: Cache State - 多环境管理
+
+on:
+  workflow_dispatch:
+    inputs:
+      target_environments:
+        description: '目标环境（逗号分隔）'
+        required: true
+        default: 'dev,staging,production'
+      config_update:
+        description: '是否更新配置'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  setup-environments:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        environment: [dev, staging, production]
+    outputs:
+      environments: ${{ steps.env-list.outputs.environments }}
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 环境特定配置
+        id: env-config
+        run: |
+          case "${{ matrix.environment }}" in
+            "dev")
+              echo "replicas=1" >> $GITHUB_OUTPUT
+              echo "resources=minimal" >> $GITHUB_OUTPUT
+              echo "debug=true" >> $GITHUB_OUTPUT
+              ;;
+            "staging")
+              echo "replicas=2" >> $GITHUB_OUTPUT
+              echo "resources=standard" >> $GITHUB_OUTPUT
+              echo "debug=false" >> $GITHUB_OUTPUT
+              ;;
+            "production")
+              echo "replicas=3" >> $GITHUB_OUTPUT
+              echo "resources=high" >> $GITHUB_OUTPUT
+              echo "debug=false" >> $GITHUB_OUTPUT
+              ;;
+          esac
+
+      - name: 保存环境副本数配置
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'replicas-${{ matrix.environment }}'
+          state-value: ${{ steps.env-config.outputs.replicas }}
+          default-value: '1'
+          cache-prefix: 'env-config'
+
+      - name: 保存环境资源配置
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'resources-${{ matrix.environment }}'
+          state-value: ${{ steps.env-config.outputs.resources }}
+          default-value: 'minimal'
+          cache-prefix: 'env-config'
+
+      - name: 保存调试模式配置
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'debug-${{ matrix.environment }}'
+          state-value: ${{ steps.env-config.outputs.debug }}
+          default-value: 'true'
+          cache-prefix: 'env-config'
+
+      - name: 检查环境健康状态
+        id: health-check
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'health-status-${{ matrix.environment }}'
+          default-value: 'unknown'
+          action: 'get'
+          cache-prefix: 'health'
+
+      - name: 初始化环境健康状态
+        if: steps.health-check.outputs.state-value == 'unknown'
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'health-status-${{ matrix.environment }}'
+          state-value: 'healthy'
+          action: 'set'
+          cache-prefix: 'health'
+
+      - name: 环境配置总结
+        run: |
+          echo "🌍 环境 ${{ matrix.environment }} 配置:"
+          echo "  - 副本数: ${{ steps.env-config.outputs.replicas }}"
+          echo "  - 资源配置: ${{ steps.env-config.outputs.resources }}"
+          echo "  - 调试模式: ${{ steps.env-config.outputs.debug }}"
+          echo "  - 健康状态: ${{ steps.health-check.outputs.state-value }}"
+
+  compare-environments:
+    needs: setup-environments
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 获取开发环境配置
+        id: dev-config
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'replicas-dev'
+          action: 'get'
+          cache-prefix: 'env-config'
+
+      - name: 获取预发布环境配置
+        id: staging-config
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'replicas-staging'
+          action: 'get'
+          cache-prefix: 'env-config'
+
+      - name: 获取生产环境配置
+        id: prod-config
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'replicas-production'
+          action: 'get'
+          cache-prefix: 'env-config'
+
+      - name: 环境配置对比
+        run: |
+          echo "🔍 环境配置对比:"
+          echo "  - 开发环境副本数: ${{ steps.dev-config.outputs.state-value }}"
+          echo "  - 预发布环境副本数: ${{ steps.staging-config.outputs.state-value }}"
+          echo "  - 生产环境副本数: ${{ steps.prod-config.outputs.state-value }}"
+          
+          # 检查配置一致性
+          if [[ "${{ steps.dev-config.outputs.state-value }}" < "${{ steps.staging-config.outputs.state-value }}" ]] && \
+             [[ "${{ steps.staging-config.outputs.state-value }}" < "${{ steps.prod-config.outputs.state-value }}" ]]; then
+            echo "✅ 环境配置递增合理"
+          else
+            echo "⚠️ 环境配置可能需要检查"
+          fi
+
+  environment-health-monitor:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 模拟健康检查 - 开发环境
+        run: |
+          # 模拟健康检查逻辑
+          HEALTH_STATUS="healthy"
+          if [[ $((RANDOM % 10)) -eq 0 ]]; then
+            HEALTH_STATUS="unhealthy"
+          fi
+          echo "dev_health=${HEALTH_STATUS}" >> $GITHUB_ENV
+
+      - name: 更新开发环境健康状态
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'health-status-dev'
+          state-value: ${{ env.dev_health }}
+          action: 'set'
+          cache-prefix: 'health'
+
+      - name: 模拟健康检查 - 预发布环境
+        run: |
+          HEALTH_STATUS="healthy"
+          if [[ $((RANDOM % 15)) -eq 0 ]]; then
+            HEALTH_STATUS="degraded"
+          fi
+          echo "staging_health=${HEALTH_STATUS}" >> $GITHUB_ENV
+
+      - name: 更新预发布环境健康状态
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'health-status-staging'
+          state-value: ${{ env.staging_health }}
+          action: 'set'
+          cache-prefix: 'health'
+
+      - name: 模拟健康检查 - 生产环境
+        run: |
+          HEALTH_STATUS="healthy"
+          if [[ $((RANDOM % 20)) -eq 0 ]]; then
+            HEALTH_STATUS="critical"
+          fi
+          echo "prod_health=${HEALTH_STATUS}" >> $GITHUB_ENV
+
+      - name: 更新生产环境健康状态
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'health-status-production'
+          state-value: ${{ env.prod_health }}
+          action: 'set'
+          cache-prefix: 'health'
+
+  generate-environment-report:
+    needs: [setup-environments, environment-health-monitor]
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 收集所有环境状态
+        id: collect-status
+        run: |
+          echo "🔍 收集环境状态信息..."
+          
+          # 创建状态收集脚本
+          cat > collect_status.sh << 'EOF'
+          #!/bin/bash
+          
+          ENVIRONMENTS=("dev" "staging" "production")
+          
+          echo "| 环境 | 副本数 | 资源配置 | 调试模式 | 健康状态 |"
+          echo "|------|--------|----------|----------|----------|"
+          
+          for env in "${ENVIRONMENTS[@]}"; do
+            echo "| $env | - | - | - | - |"
+          done
+          EOF
+          
+          chmod +x collect_status.sh
+          ./collect_status.sh
+
+      - name: 获取开发环境完整状态
+        id: dev-status
+        run: |
+          echo "=== 开发环境状态 ==="
+
+      - name: 读取开发环境配置
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'replicas-dev'
+          action: 'get'
+          cache-prefix: 'env-config'
+
+      - name: 读取开发环境健康状态
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'health-status-dev'
+          action: 'get'
+          cache-prefix: 'health'
+
+      - name: 获取预发布环境完整状态
+        run: |
+          echo "=== 预发布环境状态 ==="
+
+      - name: 获取生产环境完整状态
+        run: |
+          echo "=== 生产环境状态 ==="
+
+      - name: 生成环境状态报告
+        run: |
+          echo "📊 多环境状态报告 - $(date)"
+          echo "=================================="
+          echo ""
+          echo "本次工作流程已完成以下操作："
+          echo "✅ 环境配置初始化和更新"
+          echo "✅ 健康状态监控"
+          echo "✅ 配置对比分析"
+          echo ""
+          echo "所有环境状态已缓存，可供后续工作流使用。"
+
+  cleanup-old-states:
+    if: github.event.inputs.config_update == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 清理过期的配置状态
+        run: |
+          echo "🧹 清理过期的配置状态..."
+          # 这里可以实现清理逻辑
+          # 例如，设置空值来清理特定的缓存状态
+
+      - name: 重置所有环境的临时状态
+        uses: .actions/xgj/cache-state@v1
+        with:
+          state-key: 'temp-maintenance-mode'
+          state-value: ''
+          action: 'set'
+          cache-prefix: 'maintenance'