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

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