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

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

docs/ChatSession/chat-session-openapi.yaml

@@ -1,15 +1,19 @@
 openapi: 3.0.3
 info:
   title: ChatSession & Message API
-  version: 1.0.0
+  version: 1.1.0
   description: |
-    ChatSession & Message MVP-1，支持会话创建、消息追加、增量查询。自然语言：中文。
+    ChatSession & Message API（含 Archive/GetMessage/SSE 与 Run 调度）。自然语言：中文。
 servers:
   - url: http://localhost:8000/api
     description: 本地开发（FrankenPHP / Docker）
 tags:
   - name: ChatSession
-    description: 会话管理与消息
+    description: 会话管理
+  - name: Message
+    description: 消息追加与查询
+  - name: Run
+    description: Agent Run 调度
 paths:
   /sessions:
     post:
@@ -77,9 +81,92 @@ paths:
                     $ref: '#/components/schemas/PaginationMeta'
         "401":
           description: 未授权
-  /sessions/{session_id}/messages:
+  /sessions/{session_id}:
+    get:
+      tags: [ChatSession]
+      summary: 获取会话详情
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: path
+          name: session_id
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "200":
+          description: 会话详情
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChatSession'
+        "401":
+          description: 未授权
+        "404":
+          description: 未找到
+    patch:
+      tags: [ChatSession]
+      summary: 更新会话（重命名/状态）
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: path
+          name: session_id
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateSessionRequest'
+      responses:
+        "200":
+          description: 更新成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChatSession'
+        "403":
+          description: 状态门禁禁止
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        "422":
+          description: 校验失败
+        "401":
+          description: 未授权
+  /sessions/{session_id}/archive:
     post:
       tags: [ChatSession]
+      summary: 归档会话（设为 CLOSED，幂等）
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: path
+          name: session_id
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "200":
+          description: 归档成功（或已归档）
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChatSession'
+        "401":
+          description: 未授权
+        "404":
+          description: 未找到
+  /sessions/{session_id}/messages:
+    post:
+      tags: [Message]
       summary: 追加消息（含幂等与状态门禁）
       security:
         - bearerAuth: []
@@ -111,126 +198,8 @@ paths:
                 $ref: '#/components/schemas/Error'
         "401":
           description: 未授权
-  /sessions/{session_id}/messages/{message_id}:
     get:
-      tags: [ChatSession]
-      summary: 获取单条消息（校验 session_id）
-      security:
-        - bearerAuth: []
-      parameters:
-        - in: path
-          name: session_id
-          required: true
-          schema:
-            type: string
-            format: uuid
-        - in: path
-          name: message_id
-          required: true
-          schema:
-            type: string
-            format: uuid
-      responses:
-        "200":
-          description: 消息详情
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/MessageResource'
-        "401":
-          description: 未授权
-        "404":
-          description: 未找到或不属于该会话
-  /sessions/{session_id}/archive:
-    post:
-      tags: [ChatSession]
-      summary: 归档会话（设为 CLOSED，幂等）
-      security:
-        - bearerAuth: []
-      parameters:
-        - in: path
-          name: session_id
-          required: true
-          schema:
-            type: string
-            format: uuid
-      responses:
-        "200":
-          description: 归档成功（或已归档）
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ChatSession'
-        "401":
-          description: 未授权
-        "404":
-          description: 未找到
-  /sessions/{session_id}/sse:
-    get:
-      tags: [ChatSession]
-      summary: SSE 增量推送（backlog + Redis 实时）
-      security:
-        - bearerAuth: []
-      parameters:
-        - in: path
-          name: session_id
-          required: true
-          schema:
-            type: string
-            format: uuid
-        - in: query
-          name: after_seq
-          schema:
-            type: integer
-            default: 0
-          description: backlog 起始 seq（若有 Last-Event-ID 以其为准）
-        - in: query
-          name: limit
-          schema:
-            type: integer
-            default: 200
-            maximum: 500
-      responses:
-        "200":
-          description: text/event-stream SSE 流
-          content:
-            text/event-stream:
-              schema:
-                type: string
-                example: |
-                  id: 1
-                  event: message
-                  data: {"message_id":"...","seq":1}
-        "401":
-          description: 未授权
-        "404":
-          description: 未找到
-  /sessions/{session_id}:
-    get:
-      tags: [ChatSession]
-      summary: 获取会话详情
-      security:
-        - bearerAuth: []
-      parameters:
-        - in: path
-          name: session_id
-          required: true
-          schema:
-            type: string
-            format: uuid
-      responses:
-        "200":
-          description: 会话详情
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ChatSession'
-        "401":
-          description: 未授权
-        "404":
-          description: 未找到
-    get:
-      tags: [ChatSession]
+      tags: [Message]
       summary: 按 seq 增量查询消息
       security:
         - bearerAuth: []
@@ -268,10 +237,80 @@ paths:
                       $ref: '#/components/schemas/MessageResource'
         "401":
           description: 未授权
-  /sessions/{session_id}:
-    patch:
-      tags: [ChatSession]
-      summary: 更新会话（重命名/状态）
+  /sessions/{session_id}/messages/{message_id}:
+    get:
+      tags: [Message]
+      summary: 获取单条消息（校验 session_id）
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: path
+          name: session_id
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - in: path
+          name: message_id
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "200":
+          description: 消息详情
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResource'
+        "401":
+          description: 未授权
+        "404":
+          description: 未找到或不属于该会话
+  /sessions/{session_id}/sse:
+    get:
+      tags: [Message]
+      summary: SSE 增量推送（backlog + Redis 实时）
+      security:
+        - bearerAuth: []
+      parameters:
+        - in: path
+          name: session_id
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - in: query
+          name: after_seq
+          schema:
+            type: integer
+            default: 0
+          description: backlog 起始 seq（若有 Last-Event-ID 以其为准）
+        - in: query
+          name: limit
+          schema:
+            type: integer
+            default: 200
+            maximum: 500
+      responses:
+        "200":
+          description: text/event-stream SSE 流
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                example: |
+                  id: 1
+                  event: message
+                  data: {"message_id":"...","seq":1}
+        "401":
+          description: 未授权
+        "404":
+          description: 未找到
+  /sessions/{session_id}/runs:
+    post:
+      tags: [Run]
+      summary: 触发一次 Agent Run（按 trigger_message_id 幂等）
       security:
         - bearerAuth: []
       parameters:
@@ -286,24 +325,22 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/UpdateSessionRequest'
+              $ref: '#/components/schemas/DispatchRunRequest'
       responses:
-        "200":
-          description: 更新成功
+        "201":
+          description: 已触发（或复用进行中的 RUNNING）
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ChatSession'
-        "403":
-          description: 状态门禁禁止
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-        "422":
-          description: 校验失败
+                type: object
+                properties:
+                  run_id:
+                    type: string
+                    format: uuid
         "401":
           description: 未授权
+        "404":
+          description: session 或 trigger_message 不存在
 components:
   securitySchemes:
     bearerAuth:
@@ -363,6 +400,13 @@ components:
         status:
           type: string
           enum: [OPEN, LOCKED, CLOSED]
+    DispatchRunRequest:
+      type: object
+      required: [trigger_message_id]
+      properties:
+        trigger_message_id:
+          type: string
+          format: uuid
     AppendMessageRequest:
       type: object
       required: [role, type]