main: 增强 Agent Run 逻辑与消息处理

- 添加流式文本推送，支持 `message.delta` 消息类型
- 优化 Run 主流程，增加工具调用与流式数据发布逻辑
- 更新 `phpunit.xml` 环境变量，支持 Agent 配置项
- 扩展文档，完善工具调用与消息类型说明

app/Services/OutputSink.php

@@ -30,13 +30,18 @@ class OutputSink
     }
 
     /**
+     * 追加 Agent 流式文本增量（仅用于 SSE 推送，不落库）。
+     *
+     * message.delta 消息只用于实时流式推送，不需要持久化到数据库。
+     * 最终的完整回复会通过 appendAgentMessage() 落库。
+     *
      * @param array<string, mixed> $meta
      */
-    public function appendAgentDelta(string $sessionId, string $runId, string $content, int $deltaIndex, array $meta = []): Message
+    public function appendAgentDelta(string $sessionId, string $runId, string $content, int $deltaIndex, array $meta = []): void
     {
-        $dedupeKey = "run:{$runId}:agent:delta:{$deltaIndex}";
-
-        return $this->chatService->appendMessage([
+        // 1. 创建临时 Message 对象（不保存到数据库）
+        $message = new Message([
+            'message_id' => (string) \Illuminate\Support\Str::uuid(),
             'session_id' => $sessionId,
             'role' => Message::ROLE_AGENT,
             'type' => 'message.delta',
@@ -45,8 +50,45 @@ class OutputSink
                 'run_id' => $runId,
                 'delta_index' => $deltaIndex,
             ]),
-            'dedupe_key' => $dedupeKey,
-        ], $wasDeduped);
+            'dedupe_key' => "run:{$runId}:agent:delta:{$deltaIndex}",
+            'seq' => 0, // delta 消息不需要真实的 seq
+            'created_at' => now(),
+        ]);
+
+        // 2. 仅发布 Redis 事件，供 SSE 实时推送
+        $this->publishDeltaMessage($message);
+    }
+
+    /**
+     * 发布 delta 消息到 Redis（仅用于 SSE 推送）。
+     *
+     * 此方法不保存消息到数据库，只发布事件供 SSE 客户端接收。
+     */
+    private function publishDeltaMessage(Message $message): void
+    {
+        $root = \Illuminate\Support\Facades\Redis::getFacadeRoot();
+        $isMocked = $root instanceof \Mockery\MockInterface;
+
+        // 如果 Redis 不可用（测试环境），直接返回
+        if (!class_exists(\Redis::class) && !$isMocked) {
+            return;
+        }
+
+        $channel = "session:{$message->session_id}:messages";
+
+        try {
+            \Illuminate\Support\Facades\Redis::publish(
+                $channel,
+                json_encode($message->toArray(), JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_IGNORE)
+            );
+        } catch (\Throwable $e) {
+            logger()->warning('Redis publish failed for delta message', [
+                'session_id' => $message->session_id,
+                'run_id' => $message->payload['run_id'] ?? null,
+                'delta_index' => $message->payload['delta_index'] ?? null,
+                'error' => $e->getMessage(),
+            ]);
+        }
     }
 
     /**