main: 增强 Agent Run 调度可靠性与幂等性

- 默认切换 AgentProvider 为 HttpAgentProvider，增强网络请求的容错和重试机制
- 优化 Run 逻辑，支持多场景去重与并发保护
- 添加 Redis 发布失败的日志记录以提升问题排查效率
- 扩展 OpenAPI 规范，新增 Error 和 Run 状态相关模型
- 增强测试覆盖，验证调度策略和重复请求的幂等性
- 增加数据库索引以优化查询性能
- 更新所有相关文档和配置文件

app/Http/Controllers/ChatSessionSseController.php

@@ -17,6 +17,7 @@ class ChatSessionSseController extends Controller
 
     public function stream(Request $request, string $sessionId): Response|StreamedResponse
     {
+        set_time_limit(360);
         $this->service->getSession($sessionId); // ensure exists
 
         $lastEventId = $request->header('Last-Event-ID');
@@ -44,74 +45,50 @@ class ChatSessionSseController extends Controller
 
         $response = new StreamedResponse(function () use ($sessionId, $afterSeq, $limit) {
             $lastSentSeq = $afterSeq;
+            $lastHeartbeat = microtime(true);
 
             $this->sendBacklog($sessionId, $lastSentSeq, $limit);
+            $this->sendHeartbeat($lastHeartbeat);
 
             try {
                 $redis = Redis::connection()->client();
                 if (method_exists($redis, 'setOption')) {
-                    $redis->setOption(\Redis::OPT_READ_TIMEOUT, 5);
+                    $redis->setOption(\Redis::OPT_READ_TIMEOUT, 360);
                 }
 
                 $channel = "session:{$sessionId}:messages";
-                $lastPing = time();
-                logger()->info('sse open');
-                if (method_exists($redis, 'pubSubLoop')) {
-                    $pubSub = $redis->pubSubLoop();
-                    $pubSub->subscribe($channel);
-
-                    foreach ($pubSub as $message) {
-                        if ($message->kind === 'subscribe') {
-                            continue;
-                        }
-
-                        if (connection_aborted()) {
-                            $pubSub->unsubscribe();
-                            break;
-                        }
-
-                        $payloadId = $message->payload ?? null;
-                        if ($payloadId) {
-                            $msg = $this->service->getMessage($sessionId, $payloadId);
-                            if ($msg && $msg->seq > $lastSentSeq) {
-                                $this->emitMessage($msg);
-                                $lastSentSeq = $msg->seq;
-                            }
-                        }
-
-                        if (time() - $lastPing >= 180) {
-                            logger()->info('ping: sent'.$sessionId);
-                            echo ": ping\n\n";
-                            @ob_flush();
-                            @flush();
-                            $lastPing = time();
-                        }
+                logger('sse open');
+                // Fallback for Redis drivers without pubSubLoop (older phpredis)
+                $redis->subscribe([$channel], function ($redisInstance, $chan, $payload) use (&$lastSentSeq, $sessionId, $limit, &$lastHeartbeat) {
+                    if (connection_aborted()) {
+                        logger('sse aborted');
+                        $redisInstance->unsubscribe([$chan]);
+                        return;
                     }
-                    logger()->info('close: sent'.$sessionId);
-                    unset($pubSub);
-                } else {
-                    // Fallback for Redis drivers without pubSubLoop (older phpredis)
-                    $redis->subscribe([$channel], function ($redisInstance, $chan, $payload) use (&$lastSentSeq, $sessionId) {
-                        if (connection_aborted()) {
-                            $redisInstance->unsubscribe([$chan]);
-                            return;
+
+                    $this->sendHeartbeat($lastHeartbeat);
+
+                    if (! $payload) {
+                        return;
+                    }
+
+                    $msg = $this->service->getMessage($sessionId, $payload);
+                    if ($msg && $msg->seq > $lastSentSeq) {
+                        if ($msg->seq > $lastSentSeq + 1) {
+                            $this->sendBacklog($sessionId, $lastSentSeq, $limit);
                         }
 
-                        if (! $payload) {
-                            return;
-                        }
-
-                        $msg = $this->service->getMessage($sessionId, $payload);
-                        if ($msg && $msg->seq > $lastSentSeq) {
+                        if ($msg->seq > $lastSentSeq) {
                             $this->emitMessage($msg);
                             $lastSentSeq = $msg->seq;
                         }
-                    });
-                }
+                    }
+                });
             } catch (\RedisException $exception) {
                 logger()->warning('SSE redis subscription failed', [
                     'session_id' => $sessionId,
                     'message' => $exception->getMessage(),
+                    'code' => $exception->getCode(),
                 ]);
                 echo ": redis-error\n\n";
                 @ob_flush();
@@ -146,4 +123,16 @@ class ChatSessionSseController extends Controller
             @flush();
         }
     }
+
+    private function sendHeartbeat(float &$lastHeartbeat, int $intervalSeconds = 15): void
+    {
+        if ((microtime(true) - $lastHeartbeat) < $intervalSeconds) {
+            return;
+        }
+
+        echo ": ping\n\n";
+        @ob_flush();
+        @flush();
+        $lastHeartbeat = microtime(true);
+    }
 }