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-api.md

@@ -1,4 +1,4 @@
-# ChatSession & Message API（MVP-1）
+# ChatSession & Message API（MVP-1 + Agent Run MVP-0）
 
 基地址：`http://localhost:8000/api`（FrankenPHP 容器 8000 端口）  
 认证方式：JWT，`Authorization: Bearer {token}`  
@@ -7,6 +7,7 @@
 ## 变更记录
 - 2025-02-14：新增 ChatSession 创建、消息追加、增量查询接口；支持状态门禁与 dedupe 幂等。
 - 2025-02-14：MVP-1.1 增加会话列表、会话更新（重命名/状态变更），列表附带最后一条消息摘要。
+- 2025-02-15：Agent Run MVP-0 —— RunDispatcher + AgentRunJob + DummyProvider；自动在 user.prompt 后触发一次 Run，落地 run.status / agent.message。
 
 ## 领域模型
 - `ChatSession`：`session_id`(UUID)、`session_name`、`status`(`OPEN`/`LOCKED`/`CLOSED`)、`last_seq`
@@ -19,23 +20,26 @@
 ### 创建会话
 - `POST /sessions`
 - 请求体字段  
+
   | 字段 | 必填 | 类型 | 说明 |
   | --- | --- | --- | --- |
   | session_name | 否 | string(≤255) | 会话名称 |
 - 响应 201（JSON）  
-  | 字段 | 类型 | 说明 |
-  | --- | --- | --- |
-  | session_id | uuid | 主键 |
-  | session_name | string|null | 会话名 |
-  | status | enum | `OPEN|LOCKED|CLOSED` |
-  | last_seq | int | 当前最大 seq |
-  | last_message_id | uuid|null | 最后一条消息 |
-  | created_at, updated_at | datetime | 时间戳 |
+
+     | 字段 | 类型 | 说明 |
+      | --- | --- | --- |
+      | session_id | uuid | 主键 |
+      | session_name | string|null | 会话名 |
+      | status | enum | `OPEN|LOCKED|CLOSED` |
+      | last_seq | int | 当前最大 seq |
+      | last_message_id | uuid|null | 最后一条消息 |
+      | created_at, updated_at | datetime | 时间戳 |
 - 错误：401 未授权
 
 ### 追加消息
 - `POST /sessions/{session_id}/messages`
 - 请求体字段  
+
   | 字段 | 必填 | 类型 | 说明 |
   | --- | --- | --- | --- |
   | role | 是 | enum | `USER|AGENT|TOOL|SYSTEM` |
@@ -52,6 +56,7 @@
 ### 按序增量查询
 - `GET /sessions/{session_id}/messages?after_seq=0&limit=50`
 - 查询参数  
+
   | 参数 | 默认 | 类型 | 说明 |
   | --- | --- | --- | --- |
   | after_seq | 0 | int | 仅返回 seq 大于该值 |
@@ -62,6 +67,7 @@
 ### 会话列表
 - `GET /sessions?page=1&per_page=15&status=OPEN&q=keyword`
 - 查询参数  
+  
   | 参数 | 默认 | 类型 | 说明 |
   | --- | --- | --- | --- |
   | page | 1 | int | 分页页码 |
@@ -69,6 +75,7 @@
   | status | - | enum | 过滤 `OPEN|LOCKED|CLOSED` |
   | q | - | string | ILIKE 模糊匹配 session_name |
 - 响应 200：分页结构（`data/links/meta`），`data` 每项字段：  
+  
   | 字段 | 类型 | 说明 |
   | --- | --- | --- |
   | session_id | uuid | 会话主键 |
@@ -86,7 +93,8 @@
 
 ### 会话更新
 - `PATCH /sessions/{session_id}`
-- 请求体（至少一项，否则 422）  
+ 请求体（至少一项，否则 422）  
+ 
   | 字段 | 必填 | 类型 | 说明 |
   | --- | --- | --- | --- |
   | session_name | 否 | string 1..255 | 自动 trim |
@@ -118,6 +126,7 @@
 - `GET /sessions/{session_id}/sse?after_seq=123`
 - 头部：`Accept: text/event-stream`，可带 `Last-Event-ID`（优先于 query）用于断线续传。
 - 查询参数  
+  
   | 参数 | 默认 | 类型 | 说明 |
   | --- | --- | --- | --- |
   | after_seq | 0 | int | backlog 起始 seq（若有 Last-Event-ID 则覆盖） |
@@ -135,6 +144,38 @@
 - 心跳：周期输出 `: ping` 保活（生产环境）。
 - 错误：401 未授权；404 session 不存在。
 
+## Agent Run MVP-0（RunDispatcher + AgentRunJob）
+### 流程概述
+1. 用户追加 `role=USER && type=user.prompt` 后，Controller 自动调用 `RunDispatcher->dispatchForPrompt`。
+2. 并发保护：同会话只允许一个 RUNNING；同一个 `trigger_message_id` 幂等复用已有 `run_id`。
+3. 立即写入 `run.status`（SYSTEM/run.status，payload `{run_id,status:'RUNNING',trigger_message_id}`，dedupe_key=`run:trigger:{message_id}`）。
+4. 推送 `AgentRunJob(session_id, run_id)` 到队列（测试环境 QUEUE=sync 会同步执行）。
+5. RunLoop（使用 DummyAgentProvider）：
+   - Cancel 检查：存在 `run.cancel.request`(payload.run_id) 则写入 `run.status=CANCELED`，不产出 agent.message。
+   - ContextBuilder：提取最近 20 条 USER/AGENT 消息（type in user.prompt/agent.message），seq 升序提供给 Provider。
+   - Provider 返回一次性文本回复。
+   - OutputSink 依次写入：`agent.message`（payload 含 run_id, provider）、`run.status=DONE`（dedupe_key=`run:{run_id}:status:DONE`）。
+6. 异常：AgentRunJob 捕获异常后写入 `error` + `run.status=FAILED`（dedupe）。
+
+### Run 相关消息类型（落库即真相源）
+| type | role | payload 关键字段 | 说明 |
+| --- | --- | --- | --- |
+| run.status | SYSTEM | run_id, status(RUNNING/DONE/CANCELED/FAILED), trigger_message_id?, error? | Run 生命周期事件，CLOSED 状态下允许写入 |
+| agent.message | AGENT | run_id, provider | Provider 的一次性回复 |
+| run.cancel.request | USER/SYSTEM | run_id | CancelChecker 依据该事件判断是否中止 |
+| error | SYSTEM | run_id, message | 任务异常时落库 |
+
+### 触发 Run（调试入口）
+- `POST /sessions/{session_id}/runs`
+- 请求体字段  
+  
+  | 字段 | 必填 | 类型 | 说明 |
+  | --- | --- | --- | --- |
+  | trigger_message_id | 是 | uuid | 通常为 `user.prompt` 消息 ID |
+- 行为：同 `trigger_message_id` 幂等；若已有 RUNNING 则复用其 run_id。
+- 响应 201：`{ run_id }`
+- 错误：401 未授权；404 session 不存在或 trigger_message 不属于该 session。
+
 ## cURL 示例
 ```bash
 # 创建会话
@@ -163,4 +204,9 @@ curl -s http://localhost:8000/api/sessions/$SESSION_ID/messages/{message_id} \
 curl -N http://localhost:8000/api/sessions/$SESSION_ID/sse?after_seq=10 \
   -H "Authorization: Bearer $TOKEN" \
   -H "Accept: text/event-stream"
+
+# 手动触发 Run（调试用，实际 user.prompt 会自动触发）
+curl -s -X POST http://localhost:8000/api/sessions/$SESSION_ID/runs \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"trigger_message_id":"'$MESSAGE_ID'"}'
 ```