main: 更新 README，增强架构描述与配置说明

- 添加 `messages.payload` 表达式索引，优化查询性能
- 增强 SSE 功能，支持 seq gap 补偿与心跳保活机制
- 更新 Agent Run 逻辑，支持 HttpProvider 幂等去重与取消机制
- 增加 Agent Provider 配置说明，完善环境变量文档

README.md

@@ -11,14 +11,14 @@
 
 ## 🏗️ 当前架构概览
 - **运行**：Docker Compose，FrankenPHP + Laravel Octane。
-- **存储**：PostgreSQL（主存储），Redis（可选，用于 SSE 推送）。
+- **存储**：PostgreSQL（主存储），Redis（可选，用于 SSE 推送）；messages.payload 提供表达式索引以加速 run/cancel 查询。
 - **鉴权**：JWT（无状态），API 路由均在 `/api/*`。
 - **会话/消息模型**：
   - `chat_sessions(session_id UUID, session_name, status OPEN|LOCKED|CLOSED, last_seq, last_message_id, timestamps)`
   - `messages(message_id UUID, session_id, role USER|AGENT|TOOL|SYSTEM, type, content, payload jsonb, seq, reply_to, dedupe_key)`
   - 约束：`unique(session_id, seq)`、`unique(session_id, dedupe_key)`；append 行锁 + 事务，seq 单调递增。
-- **实时**：SSE `/api/sessions/{id}/sse`，backlog 先补历史（按 seq），再监听 Redis `session:{id}:messages` 渠道。
+- **实时**：SSE `/api/sessions/{id}/sse`，backlog 先补历史（按 seq），再监听 Redis `session:{id}:messages` 渠道；发现 seq gap 会回补并提供心跳。
-- **Agent Run 编排（MVP-0）**：user.prompt 后自动触发 RunDispatcher → `run.status=RUNNING` → AgentRunJob（DummyProvider 返回一次性回复）→ `agent.message` + `run.status=DONE/FAILED/CANCELED` 落库；同 trigger_message 幂等、同会话只允许一个 RUNNING。
+- **Agent Run 编排（MVP-0）**：user.prompt 后自动触发 RunDispatcher → `run.status=RUNNING` → AgentRunJob（HttpProvider，未配置 endpoint 时回退 DummyProvider）→ `agent.message` + `run.status=DONE/FAILED/CANCELED` 落库；同 trigger_message 幂等、同会话只允许一个 RUNNING，终态/消息均去重，取消可保证不写 agent.message。
 - **队列监控**：Horizon（本地默认开放 `/horizon`，非 local 环境默认拒绝访问）。
 
 ## 🚀 快速启动
@@ -38,11 +38,22 @@ docker compose exec app php artisan test --testsuite=Feature
 # Horizon：docker compose up -d horizon（需 composer install 安装 laravel/horizon，QUEUE_CONNECTION=redis）
 ```
 
+### Agent Provider 配置（可选）
+`config/agent.php` 读取以下环境变量（默认值已内置）：  
+- `AGENT_PROVIDER_ENDPOINT`  
+- `AGENT_PROVIDER_TIMEOUT`（默认 30）  
+- `AGENT_PROVIDER_CONNECT_TIMEOUT`（默认 5）  
+- `AGENT_PROVIDER_RETRY_TIMES`（默认 1）  
+- `AGENT_PROVIDER_RETRY_BACKOFF_MS`（默认 500）  
+- `AGENT_RUN_JOB_TRIES`（默认 1）  
+- `AGENT_RUN_JOB_BACKOFF`（默认 5）  
+- `AGENT_RUN_JOB_TIMEOUT`（默认 120）
+
 ## 🔑 API 能力一览（MVP-1.1 + Archive/GetMessage/SSE）
 - 会话：`POST /api/sessions`，`GET /api/sessions`（分页/状态/关键词），`GET /api/sessions/{id}`，`PATCH /api/sessions/{id}`（重命名/状态，CLOSED 不可重开），`POST /api/sessions/{id}/archive`（幂等归档→CLOSED）。
 - 消息：`POST /api/sessions/{id}/messages`（幂等 dedupe_key，CLOSED/LOCKED 门禁），`GET /api/sessions/{id}/messages`（after_seq 增量），`GET /api/sessions/{id}/messages/{message_id}`（校验 session_id）。
-- 实时：`GET /api/sessions/{id}/sse?after_seq=123`，SSE 事件 id 为 seq；`Last-Event-ID` 优先于 query。
+- 实时：`GET /api/sessions/{id}/sse?after_seq=123`，SSE 事件 id 为 seq；`Last-Event-ID` 优先于 query；gap 会回补，定期心跳保活。
-- Agent Run：user.prompt 自动触发；或 `POST /api/sessions/{id}/runs {trigger_message_id}` 手动触发，写入 `run.status/agent.message`。
+- Agent Run：user.prompt 自动触发；或 `POST /api/sessions/{id}/runs {trigger_message_id}` 手动触发，写入 `run.status/agent.message`，幂等去重，失败会写 `error`（含 retryable/http_status/provider/latency_ms）。
 
 详细字段/示例：`docs/ChatSession/chat-session-api.md`，OpenAPI：`docs/ChatSession/chat-session-openapi.yaml`。用户管理/鉴权文档：`docs/User/user-api.md`。
 
@@ -50,7 +61,7 @@ docker compose exec app php artisan test --testsuite=Feature
 - `OPEN`：正常追加。
 - `LOCKED`：拒绝 `role=USER && type=user.prompt`。
 - `CLOSED`：拒绝追加，例外 `role=SYSTEM && type in [run.status, error]`。
-- 幂等：同一 session + dedupe_key 返回已有消息（同 message_id/seq）。
+- 幂等：同一 session + dedupe_key 返回已有消息（同 message_id/seq）；run.status 与 agent.message 均通过 dedupe_key 防重复。
 
 ## 🔌 开发/验证
 - 迁移：`docker compose exec app php artisan migrate`