main: 扩展 Agent Run 调度与队列功能

- 增加 Agent Run MVP-0，包括 RunDispatcher 和 AgentRunJob
- 优化队列配置，支持 Redis 队列驱动，添加 Horizon 容器
- 更新 Docker 配置，细化角色分工，新增 Horizon 配置
- 增加测试任务 `TestJob`，扩展队列使用示例
- 更新 OpenAPI 规范，添加 Agent Run 相关接口及示例
- 编写文档，详细描述 Agent Run 流程与 MVP-0 功能
- 优化相关服务与文档，支持队列与异步运行

app/Services/Agent/AgentProviderInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace App\Services\Agent;
+
+interface AgentProviderInterface
+{
+    /**
+     * @param array<string, mixed> $context
+     * @param array<string, mixed> $options
+     */
+    public function generate(array $context, array $options = []): string;
+}

app/Services/Agent/DummyAgentProvider.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Services\Agent;
+
+class DummyAgentProvider implements AgentProviderInterface
+{
+    /**
+     * @param array<string, mixed> $context
+     * @param array<string, mixed> $options
+     */
+    public function generate(array $context, array $options = []): string
+    {
+        $messages = $context['messages'] ?? [];
+        $lastUser = null;
+        foreach (array_reverse($messages) as $msg) {
+            if (($msg['role'] ?? '') === 'USER' && ($msg['type'] ?? '') === 'user.prompt') {
+                $lastUser = $msg['content'] ?? null;
+                break;
+            }
+        }
+
+        $summary = $lastUser ? mb_substr($lastUser, 0, 80) : 'no user prompt';
+
+        return sprintf('MVP reply: based on last user input -> %s', $summary);
+    }
+}

app/Services/Agent/HttpAgentProvider.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace App\Services\Agent;
+
+use Illuminate\Support\Facades\Http;
+
+class HttpAgentProvider implements AgentProviderInterface
+{
+    protected string $endpoint;
+
+    public function __construct(?string $endpoint = null)
+    {
+        $this->endpoint = $endpoint ?? config('services.agent_provider.endpoint', '');
+    }
+
+    /**
+     * @param array<string, mixed> $context
+     * @param array<string, mixed> $options
+     */
+    public function generate(array $context, array $options = []): string
+    {
+        if (empty($this->endpoint)) {
+            // placeholder to avoid accidental outbound calls when未配置
+            return (new DummyAgentProvider())->generate($context, $options);
+        }
+
+        $payload = [
+            'context' => $context,
+            'options' => $options,
+        ];
+
+        $response = Http::post($this->endpoint, $payload);
+
+        if (! $response->successful()) {
+            throw new \RuntimeException('Agent provider failed: '.$response->body());
+        }
+
+        $data = $response->json();
+
+        return is_string($data) ? $data : ($data['content'] ?? '');
+    }
+}

app/Services/CancelChecker.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\Message;
+
+class CancelChecker
+{
+    public function isCanceled(string $sessionId, string $runId): bool
+    {
+        return Message::query()
+            ->where('session_id', $sessionId)
+            ->where('type', 'run.cancel.request')
+            ->whereIn('role', [Message::ROLE_USER, Message::ROLE_SYSTEM])
+            ->where('payload->run_id', $runId)
+            ->exists();
+    }
+}

app/Services/ContextBuilder.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\Message;
+use Illuminate\Support\Collection;
+
+class ContextBuilder
+{
+    public function __construct(private readonly int $limit = 20)
+    {
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function build(string $sessionId, string $runId): array
+    {
+        $messages = $this->loadRecentMessages($sessionId);
+
+        return [
+            'run_id' => $runId,
+            'session_id' => $sessionId,
+            'system_prompt' => 'You are an agent inside ARS. Respond concisely in plain text.',
+            'messages' => $messages->map(function (Message $message) {
+                return [
+                    'message_id' => $message->message_id,
+                    'role' => $message->role,
+                    'type' => $message->type,
+                    'content' => $message->content,
+                    'seq' => $message->seq,
+                ];
+            })->values()->all(),
+        ];
+    }
+
+    private function loadRecentMessages(string $sessionId): Collection
+    {
+        return Message::query()
+            ->where('session_id', $sessionId)
+            ->whereIn('role', [Message::ROLE_USER, Message::ROLE_AGENT])
+            ->whereIn('type', ['user.prompt', 'agent.message'])
+            ->orderByDesc('seq')
+            ->limit($this->limit)
+            ->get()
+            ->sortBy('seq')
+            ->values();
+    }
+}

app/Services/OutputSink.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\Message;
+
+class OutputSink
+{
+    public function __construct(private readonly ChatService $chatService)
+    {
+    }
+
+    /**
+     * @param array<string, mixed> $meta
+     */
+    public function appendAgentMessage(string $sessionId, string $runId, string $content, array $meta = []): Message
+    {
+        return $this->chatService->appendMessage([
+            'session_id' => $sessionId,
+            'role' => Message::ROLE_AGENT,
+            'type' => 'agent.message',
+            'content' => $content,
+            'payload' => array_merge($meta, ['run_id' => $runId]),
+        ]);
+    }
+
+    /**
+     * @param array<string, mixed> $meta
+     */
+    public function appendRunStatus(string $sessionId, string $runId, string $status, array $meta = []): Message
+    {
+        $dedupeKey = $meta['dedupe_key'] ?? null;
+        unset($meta['dedupe_key']);
+
+        return $this->chatService->appendMessage([
+            'session_id' => $sessionId,
+            'role' => Message::ROLE_SYSTEM,
+            'type' => 'run.status',
+            'payload' => array_merge($meta, [
+                'run_id' => $runId,
+                'status' => $status,
+            ]),
+            'dedupe_key' => $dedupeKey,
+        ]);
+    }
+
+    /**
+     * @param array<string, mixed> $meta
+     */
+    public function appendError(string $sessionId, string $runId, string $code, string $message, array $meta = []): Message
+    {
+        return $this->chatService->appendMessage([
+            'session_id' => $sessionId,
+            'role' => Message::ROLE_SYSTEM,
+            'type' => 'error',
+            'content' => $code,
+            'payload' => array_merge($meta, [
+                'run_id' => $runId,
+                'message' => $message,
+            ]),
+        ]);
+    }
+}

app/Services/RunDispatcher.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace App\Services;
+
+use App\Jobs\AgentRunJob;
+use App\Models\Message;
+use Illuminate\Database\Eloquent\ModelNotFoundException;
+use Illuminate\Support\Str;
+
+class RunDispatcher
+{
+    public function __construct(
+        private readonly ChatService $chatService,
+        private readonly OutputSink $outputSink,
+    ) {
+    }
+
+    /**
+     * @throws ModelNotFoundException
+     */
+    public function dispatchForPrompt(string $sessionId, string $triggerMessageId): string
+    {
+        $triggerMessage = $this->chatService->getMessage($sessionId, $triggerMessageId);
+        if (! $triggerMessage) {
+            throw (new ModelNotFoundException())->setModel(Message::class, [$triggerMessageId]);
+        }
+
+        $existingForTrigger = Message::query()
+            ->where('session_id', $sessionId)
+            ->where('type', 'run.status')
+            ->where('payload->trigger_message_id', $triggerMessageId)
+            ->orderByDesc('seq')
+            ->first();
+
+        if ($existingForTrigger && ($existingForTrigger->payload['run_id'] ?? null)) {
+            return $existingForTrigger->payload['run_id'];
+        }
+
+        $latestStatus = Message::query()
+            ->where('session_id', $sessionId)
+            ->where('type', 'run.status')
+            ->orderByDesc('seq')
+            ->first();
+
+        if ($latestStatus && ($latestStatus->payload['status'] ?? null) === 'RUNNING' && ($latestStatus->payload['run_id'] ?? null)) {
+            return $latestStatus->payload['run_id'];
+        }
+
+        $runId = (string) Str::uuid();
+
+        $this->outputSink->appendRunStatus($sessionId, $runId, 'RUNNING', [
+            'trigger_message_id' => $triggerMessageId,
+            'dedupe_key' => 'run:trigger:'.$triggerMessageId,
+        ]);
+
+        dispatch(new AgentRunJob($sessionId, $runId));
+
+        return $runId;
+    }
+}

app/Services/RunLoop.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace App\Services;
+
+use App\Services\Agent\AgentProviderInterface;
+use App\Services\Agent\DummyAgentProvider;
+
+class RunLoop
+{
+    public function __construct(
+        private readonly ContextBuilder $contextBuilder,
+        private readonly AgentProviderInterface $provider,
+        private readonly OutputSink $outputSink,
+        private readonly CancelChecker $cancelChecker,
+    ) {
+    }
+
+    public function run(string $sessionId, string $runId): void
+    {
+        if ($this->cancelChecker->isCanceled($sessionId, $runId)) {
+            $this->outputSink->appendRunStatus($sessionId, $runId, 'CANCELED', [
+                'dedupe_key' => "run:{$runId}:status:CANCELED",
+            ]);
+            return;
+        }
+
+        $context = $this->contextBuilder->build($sessionId, $runId);
+
+        if ($this->cancelChecker->isCanceled($sessionId, $runId)) {
+            $this->outputSink->appendRunStatus($sessionId, $runId, 'CANCELED', [
+                'dedupe_key' => "run:{$runId}:status:CANCELED",
+            ]);
+            return;
+        }
+
+        $reply = $this->provider->generate($context);
+
+        if ($this->cancelChecker->isCanceled($sessionId, $runId)) {
+            $this->outputSink->appendRunStatus($sessionId, $runId, 'CANCELED', [
+                'dedupe_key' => "run:{$runId}:status:CANCELED",
+            ]);
+            return;
+        }
+
+        $this->outputSink->appendAgentMessage($sessionId, $runId, $reply, [
+            'provider' => $this->provider instanceof DummyAgentProvider ? 'dummy' : get_class($this->provider),
+        ]);
+        $this->outputSink->appendRunStatus($sessionId, $runId, 'DONE', [
+            'dedupe_key' => "run:{$runId}:status:DONE",
+        ]);
+    }
+}