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

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

tests/Feature/AgentRunTest.php

@@ -4,6 +4,9 @@ namespace Tests\Feature;
 
 use App\Jobs\AgentRunJob;
 use App\Models\Message;
+use App\Services\Agent\AgentProviderInterface;
+use App\Services\Agent\ProviderException;
+use App\Services\CancelChecker;
 use App\Services\ChatService;
 use App\Services\RunDispatcher;
 use App\Services\RunLoop;
@@ -39,7 +42,8 @@ class AgentRunTest extends TestCase
         // simulate worker execution
         (new AgentRunJob($session->session_id, $runId))->handle(
             app(RunLoop::class),
-            app(OutputSink::class)
+            app(OutputSink::class),
+            app(CancelChecker::class)
         );
 
         $messages = Message::query()
@@ -52,6 +56,36 @@ class AgentRunTest extends TestCase
         $this->assertTrue($messages->contains(fn ($m) => $m->type === 'run.status' && ($m->payload['status'] ?? null) === 'DONE'));
     }
 
+    public function test_dispatch_is_idempotent_for_same_trigger(): void
+    {
+        Queue::fake();
+        $service = app(ChatService::class);
+        $dispatcher = app(RunDispatcher::class);
+
+        $session = $service->createSession('Idempotent Run');
+        $prompt = $service->appendMessage([
+            'session_id' => $session->session_id,
+            'role' => Message::ROLE_USER,
+            'type' => 'user.prompt',
+            'content' => 'please run once',
+        ]);
+
+        $firstRunId = $dispatcher->dispatchForPrompt($session->session_id, $prompt->message_id);
+        $secondRunId = $dispatcher->dispatchForPrompt($session->session_id, $prompt->message_id);
+
+        $this->assertSame($firstRunId, $secondRunId);
+
+        Queue::assertPushed(AgentRunJob::class, 1);
+
+        $statusMessages = Message::query()
+            ->where('session_id', $session->session_id)
+            ->where('type', 'run.status')
+            ->whereRaw("payload->>'trigger_message_id' = ?", [$prompt->message_id])
+            ->get();
+
+        $this->assertCount(1, $statusMessages);
+    }
+
     public function test_second_prompt_dispatches_new_run_after_first_completes(): void
     {
         Queue::fake();
@@ -70,7 +104,8 @@ class AgentRunTest extends TestCase
 
         (new AgentRunJob($session->session_id, $firstRunId))->handle(
             app(RunLoop::class),
-            app(OutputSink::class)
+            app(OutputSink::class),
+            app(CancelChecker::class)
         );
 
         $secondPrompt = $service->appendMessage([
@@ -90,6 +125,51 @@ class AgentRunTest extends TestCase
         });
     }
 
+    public function test_repeated_job_does_not_duplicate_agent_message(): void
+    {
+        Queue::fake();
+        $service = app(ChatService::class);
+        $dispatcher = app(RunDispatcher::class);
+
+        $session = $service->createSession('Retry Session');
+        $prompt = $service->appendMessage([
+            'session_id' => $session->session_id,
+            'role' => Message::ROLE_USER,
+            'type' => 'user.prompt',
+            'content' => 'retry run',
+        ]);
+
+        $runId = $dispatcher->dispatchForPrompt($session->session_id, $prompt->message_id);
+
+        (new AgentRunJob($session->session_id, $runId))->handle(
+            app(RunLoop::class),
+            app(OutputSink::class),
+            app(CancelChecker::class)
+        );
+
+        (new AgentRunJob($session->session_id, $runId))->handle(
+            app(RunLoop::class),
+            app(OutputSink::class),
+            app(CancelChecker::class)
+        );
+
+        $agentMessages = Message::query()
+            ->where('session_id', $session->session_id)
+            ->where('type', 'agent.message')
+            ->whereRaw("payload->>'run_id' = ?", [$runId])
+            ->get();
+
+        $doneStatuses = Message::query()
+            ->where('session_id', $session->session_id)
+            ->where('type', 'run.status')
+            ->whereRaw("payload->>'run_id' = ?", [$runId])
+            ->whereRaw("payload->>'status' = ?", ['DONE'])
+            ->get();
+
+        $this->assertCount(1, $agentMessages);
+        $this->assertCount(1, $doneStatuses);
+    }
+
     public function test_cancel_prevents_agent_reply_and_marks_canceled(): void
     {
         Queue::fake();
@@ -123,4 +203,59 @@ class AgentRunTest extends TestCase
         $this->assertFalse($messages->contains(fn ($m) => $m->type === 'agent.message' && ($m->payload['run_id'] ?? null) === $runId));
         $this->assertTrue($messages->contains(fn ($m) => $m->type === 'run.status' && ($m->payload['status'] ?? null) === 'CANCELED'));
     }
+
+    public function test_provider_exception_writes_error_and_failed_status(): void
+    {
+        Queue::fake();
+        $this->app->bind(AgentProviderInterface::class, function () {
+            return new class implements AgentProviderInterface {
+                public function generate(array $context, array $options = []): string
+                {
+                    throw new ProviderException('HTTP_ERROR', 'provider failed', true, 500, 'boom');
+                }
+            };
+        });
+
+        $service = app(ChatService::class);
+        $dispatcher = app(RunDispatcher::class);
+
+        $session = $service->createSession('Provider Failure');
+        $prompt = $service->appendMessage([
+            'session_id' => $session->session_id,
+            'role' => Message::ROLE_USER,
+            'type' => 'user.prompt',
+            'content' => 'trigger failure',
+        ]);
+
+        $runId = $dispatcher->dispatchForPrompt($session->session_id, $prompt->message_id);
+
+        try {
+            (new AgentRunJob($session->session_id, $runId))->handle(
+                app(RunLoop::class),
+                app(OutputSink::class),
+                app(CancelChecker::class)
+            );
+            $this->fail('Expected provider exception');
+        } catch (ProviderException $exception) {
+            $this->assertSame('HTTP_ERROR', $exception->errorCode);
+        }
+
+        $messages = Message::query()
+            ->where('session_id', $session->session_id)
+            ->get();
+
+        $this->assertTrue($messages->contains(function ($m) use ($runId) {
+            return $m->type === 'run.status'
+                && ($m->payload['status'] ?? null) === 'FAILED'
+                && ($m->payload['run_id'] ?? null) === $runId;
+        }));
+
+        $this->assertTrue($messages->contains(function ($m) use ($runId) {
+            return $m->type === 'error'
+                && $m->content === 'HTTP_ERROR'
+                && ($m->payload['run_id'] ?? null) === $runId
+                && ($m->payload['retryable'] ?? null) === true
+                && ($m->payload['http_status'] ?? null) === 500;
+        }));
+    }
 }