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

- 添加流式文本推送，支持 `message.delta` 消息类型 - 优化 Run 主流程，增加工具调用与流式数据发布逻辑 - 更新 `phpunit.xml` 环境变量，支持 Agent 配置项 - 扩展文档，完善工具调用与消息类型说明
2025-12-22 17:51:56 +08:00
parent 59d4831f00
commit 663e15395b
5 changed files with 766 additions and 143 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,14 +36,24 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `message_id` (UUID, 主键): 消息唯一标识
 - `session_id`: 所属会话ID
 - `role`: 消息角色 (USER/AGENT/TOOL/SYSTEM)
- `type`: 消息类型 (user.prompt/agent.message/run.status等)
+- `type`: 消息类型 (user.prompt/agent.message/message.delta/tool.call/tool.result/run.status/error等)
 - `content`: 消息内容 (text)
- `payload`: 附加数据 (jsonb)
+- `payload`: 附加数据 (jsonb)，包含 run_id、tool_call_id、error_type 等元数据
 - `seq`: 会话内序号 (单调递增)
 - `reply_to`: 回复的消息ID
 - `dedupe_key`: 幂等去重键
 - **约束**: `unique(session_id, seq)` 和 `unique(session_id, dedupe_key)`

+#### 消息类型完整列表
+- `user.prompt` (USER): 用户提示
+- `agent.message` (AGENT): Agent 完整回复
+- `message.delta` (AGENT): 流式文本增量
+- `tool.call` (AGENT): 工具调用请求
+- `tool.result` (TOOL): 工具执行结果
+- `run.status` (SYSTEM): Run 状态（RUNNING/DONE/FAILED/CANCELED）
+- `error` (SYSTEM): 错误信息
+- `run.cancel.request` (USER): 取消请求
+
 ### 会话状态与门禁规则

 - **OPEN**: 正常追加所有消息
@@ -58,12 +68,48 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 3. 检查会话是否已有 RUNNING 状态的 run（单会话单任务限制）
 4. 创建 `run.status=RUNNING` 消息并派发 `AgentRunJob`
 5. `RunLoop` 执行 Agent 调用流程：
-   - `ContextBuilder` 构建上下文
-   - `AgentProviderInterface` 调用 Agent（当前为 DummyAgentProvider）
-   - `CancelChecker` 检查取消信号
-   - `OutputSink` 写入 agent.message
+   - `ContextBuilder` 构建上下文（加载最近 20 条相关消息）
+   - `AgentProviderInterface::stream()` 流式调用 Agent
+   - 消费 `Generator<ProviderEvent>` 流：
+     - `MessageDelta`: 流式文本，写入 `message.delta` 消息
+     - `ToolCall`: 工具调用，累积后写入 `tool.call` 并分发 `ToolRunJob`
+     - `Done`: 流结束，写入最终 `agent.message` + `DONE` 状态
+     - `Error`: 错误，写入 `error` + `FAILED` 状态
+   - `CancelChecker` 定期检查取消信号
+   - 工具调用完成后，等待 `tool.result`，继续下一轮 Provider 调用
+   - `OutputSink` 统一写入消息，保证幂等性
 6. 完成后写入 `run.status=DONE/FAILED/CANCELED`

+**Provider 选择逻辑**（在 `AppServiceProvider` 中绑定）：
+- `HttpAgentProvider` 会检查 `AGENT_OPENAI_API_KEY` 环境变量
+- 若配置了 OpenAI Key，则使用 `OpenAiChatCompletionsAdapter`
+- 否则回退到 `DummyAgentProvider`（返回模拟响应）
+
+### 工具系统架构
+
+项目支持 Agent 调用工具（Tools），采用子 Run 模式：
+
+- **Tool** (`app/Services/Tool/Tool.php`): 工具接口，定义 name、description、parameters、execute 方法
+- **ToolRegistry** (`app/Services/Tool/ToolRegistry.php`): 管理已注册工具，生成 OpenAI 兼容工具声明
+- **ToolExecutor** (`app/Services/Tool/ToolExecutor.php`): 执行工具，处理超时和结果截断
+- **ToolRunDispatcher** (`app/Services/Tool/ToolRunDispatcher.php`): 为每个工具调用创建子 run 并投递 `ToolRunJob`
+- **ToolRunJob** (`app/Jobs/ToolRunJob.php`): 队列任务，执行工具并写入 `tool.result` 消息
+
+工具调用流程：
+1. Agent 返回 ToolCall 事件
+2. RunLoop 累积工具调用，写入 `tool.call` 消息
+3. ToolRunDispatcher 为每个工具创建子 run（`run.status=RUNNING`）
+4. ToolRunJob 执行工具，写入 `tool.result` 消息
+5. RunLoop 轮询等待所有 `tool.result`（支持超时）
+6. 收集工具结果后，继续下一轮 Provider 调用
+
+配置项（`config/agent.php`）：
+- `agent.tools.max_calls_per_run`: 单 run 最多工具调用次数（默认 1）
+- `agent.tools.wait_timeout_ms`: 等待工具结果超时（默认 15000ms）
+- `agent.tools.wait_poll_interval_ms`: 轮询间隔（默认 200ms）
+- `agent.tools.timeout_seconds`: 工具执行超时（默认 15s）
+- `agent.tools.result_max_bytes`: 结果最大字节数（默认 4096）
+
 ### 实时消息推送 (SSE)

 - **端点**: `GET /api/sessions/{id}/sse?after_seq=123`
@@ -71,26 +117,41 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
  1. 先从数据库补发历史消息（seq > after_seq）
  2. 订阅 Redis 频道 `session:{id}:messages` 监听新消息
  3. 支持 `Last-Event-ID` 自动续传
+  4. 检测 seq gap 自动回补
+  5. 15 秒心跳保活
 - **事件格式**: SSE event id 为消息 seq

 ### 服务层架构

- **ChatService**: 会话和消息的核心业务逻辑
+- **ChatService** (`app/Services/ChatService.php`): 会话和消息的核心业务逻辑
  - 使用行锁 (`lockForUpdate`) + 事务保证消息 seq 单调递增
  - 通过 `dedupe_key` 实现幂等性
  - 消息追加后发布 Redis 事件用于 SSE 推送
+  - 提供 `appendMessage()`、`listMessagesBySeq()`、`updateSession()` 等方法

- **RunDispatcher**: Agent Run 调度器
+- **RunDispatcher** (`app/Services/RunDispatcher.php`): Agent Run 调度器
  - 检查 trigger_message_id 幂等性
  - 确保同会话只有一个 RUNNING 状态的 run

- **RunLoop**: Agent 执行循环
-  - 协调 ContextBuilder、AgentProvider、OutputSink、CancelChecker
+- **RunLoop** (`app/Services/RunLoop.php`): Agent 执行循环
+  - 协调 ContextBuilder、AgentProvider、OutputSink、CancelChecker、ToolRunDispatcher
+  - 处理工具调用上限（`max_calls_per_run`）
+  - 达到上限后强制 `tool_choice=none` 防止再次触发

- **OutputSink**: 统一的消息写入接口
+- **OutputSink** (`app/Services/OutputSink.php`): 统一的消息写入接口
  - `appendAgentMessage()`: 写入 agent 回复
+  - `appendAgentDelta()`: 写入流式文本增量
  - `appendRunStatus()`: 写入 run 状态
  - `appendError()`: 写入错误信息
+  - `appendToolCall()`: 写入工具调用
+  - `appendToolResult()`: 写入工具结果
+
+- **ContextBuilder** (`app/Services/ContextBuilder.php`): 构建 Agent 上下文
+  - 加载最近 20 条相关消息（USER/AGENT/TOOL 角色）
+  - 按 seq 排序并转换为 AgentContext
+
+- **CancelChecker** (`app/Services/CancelChecker.php`): 检查 run 是否被取消
+  - 查询 `type='run.cancel.request'` 消息

 ## 常用开发命令

@@ -162,6 +223,27 @@ docker compose exec app vendor/bin/pint --test
 docker compose exec app vendor/bin/pint --dirty
 ```

+### 本地开发（不使用 Docker）
+
+如果你想在本地直接运行（需要 PHP 8.2+、PostgreSQL、Redis）：
+
+```bash
+# 安装依赖
+composer install
+
+# 启动 Octane 开发服务器
+php artisan octane:start --host=0.0.0.0 --port=8000
+
+# 启动队列 worker
+php artisan queue:work
+
+# 或启动 Horizon
+php artisan horizon
+
+# 查看实时日志
+php artisan pail
+```
+
 ### 队列与任务

 ```bash
@@ -254,6 +336,91 @@ docker compose exec app php artisan make:test ChatServiceTest --unit --phpunit
 - `GET /api/sessions/{session_id}/sse`: SSE 实时消息流
 - `POST /api/sessions/{session_id}/runs`: 手动触发 Agent Run

+## 项目结构
+
+```
+app/
+├── Enums/              # 枚举类（ChatSessionStatus 等）
+├── Exceptions/         # 自定义异常
+├── Http/
+│   ├── Controllers/    # API 控制器
+│   │   ├── ChatSessionController.php       # 会话和消息 API
+│   │   ├── ChatSessionSseController.php    # SSE 实时推送
+│   │   ├── RunController.php               # Agent Run 手动触发
+│   │   ├── AuthController.php              # 用户认证
+│   │   └── UserController.php              # 用户管理
+│   ├── Requests/       # Form Request 验证
+│   └── Resources/      # API 响应格式化
+├── Jobs/               # 队列任务
+│   ├── AgentRunJob.php    # Agent Run 队列任务
+│   └── ToolRunJob.php     # 工具执行队列任务
+├── Models/             # Eloquent 模型
+│   ├── ChatSession.php
+│   ├── Message.php
+│   └── User.php
+├── Providers/          # 服务提供者
+│   └── AppServiceProvider.php   # 绑定 AgentProviderInterface
+└── Services/           # 业务逻辑服务
+    ├── Agent/          # Agent Provider 实现
+    │   ├── OpenAi/     # OpenAI 适配器
+    │   │   ├── OpenAiChatCompletionsAdapter.php
+    │   │   ├── ChatCompletionsRequestBuilder.php
+    │   │   ├── OpenAiApiClient.php
+    │   │   ├── OpenAiStreamParser.php
+    │   │   └── OpenAiEventNormalizer.php
+    │   ├── AgentProviderInterface.php
+    │   ├── AgentContext.php
+    │   ├── ProviderEvent.php
+    │   ├── ProviderEventType.php
+    │   ├── ProviderException.php
+    │   ├── HttpAgentProvider.php
+    │   └── DummyAgentProvider.php
+    ├── Tool/               # 工具系统
+    │   ├── Tool.php                   # 工具接口
+    │   ├── ToolRegistry.php           # 工具注册表
+    │   ├── ToolExecutor.php           # 工具执行器
+    │   ├── ToolRunDispatcher.php      # 工具 Run 分发器
+    │   ├── ToolCall.php               # 工具调用对象
+    │   ├── ToolResult.php             # 工具结果对象
+    │   └── Tools/                     # 具体工具实现
+    │       └── GetTimeTool.php        # 获取时间工具（示例）
+    ├── ChatService.php    # 会话和消息核心服务
+    ├── RunDispatcher.php  # Run 调度器
+    ├── RunLoop.php        # Run 执行循环
+    ├── ContextBuilder.php # 上下文构建器
+    ├── OutputSink.php     # 消息写入器
+    └── CancelChecker.php  # 取消检查器
+
+database/
+├── migrations/
+│   └── 2025_02_14_000003_create_chat_tables.php  # 核心表结构
+└── factories/          # 测试数据工厂
+
+tests/
+├── Feature/
+│   ├── ChatSessionTest.php   # 会话和消息测试
+│   └── AgentRunTest.php      # Agent Run 流程测试
+└── Unit/
+    └── OpenAiAdapterTest.php # OpenAI 适配器单元测试
+
+config/
+├── agent.php          # Agent Provider 和工具配置
+├── auth.php           # JWT 认证配置
+├── queue.php          # 队列配置
+└── horizon.php        # Horizon 队列监控配置
+
+bootstrap/
+├── app.php            # Laravel 12 应用引导（中间件、路由、异常）
+└── providers.php      # 服务提供者注册
+```
+
+**关键设计原则**：
+- 所有 Agent Provider 实现 `AgentProviderInterface::stream()` 接口
+- 使用 `Generator` 模式流式返回 `ProviderEvent`
+- 统一通过 `OutputSink` 写入消息，保证事务性和幂等性
+- 工具系统采用子 Run 模式，每个工具调用创建独立 run
+- 所有异步操作通过队列（AgentRunJob、ToolRunJob）执行
+
 ## 开发注意事项

 ### Laravel 12 新特性
@@ -261,27 +428,80 @@ docker compose exec app php artisan make:test ChatServiceTest --unit --phpunit
 - 中间件、路由、异常处理在 `bootstrap/app.php` 配置
 - 服务提供者在 `bootstrap/providers.php` 注册
 - Commands 自动注册（无需手动注册）
+- JWT 中间件别名在 `bootstrap/app.php` 中配置为 `auth.jwt`

 ### 数据库操作规范
- 消息追加必须使用 `ChatService::appendMessage()`，不要直接操作 Message 模型
- 会话状态变更必须通过 `ChatService::updateSession()`
- 所有涉及 seq 递增的操作必须在事务 + 行锁中完成
+- **消息追加**：必须使用 `ChatService::appendMessage()`，不要直接操作 Message 模型
+  - 原因：需要行锁 + 事务保证 seq 单调递增，并发布 Redis 事件
+  - 所有 `OutputSink` 方法最终都调用 `ChatService::appendMessage()`
+- **会话状态变更**：必须通过 `ChatService::updateSession()`
+  - 会自动校验 CLOSED 状态不可重新打开
+- **所有涉及 seq 递增的操作**：必须在事务 + 行锁中完成
+
+### Provider 与 Event Stream 开发
+- 实现自定义 Provider 时必须实现 `AgentProviderInterface::stream()` 接口
+- 使用 `Generator` 模式 yield `ProviderEvent` 对象
+- 事件类型：
+  - `ProviderEvent::messageDelta($content)`: 流式文本增量
+  - `ProviderEvent::toolCall($toolCallId, $name, $arguments)`: 工具调用
+  - `ProviderEvent::done($finishReason)`: 流结束
+  - `ProviderEvent::error($errorCode, $message, $retryable)`: 错误
+- 错误处理：抛出 `ProviderException` 包含 errorCode、retryable、httpStatus
+- `RunLoop` 会自动处理重试、取消检查、工具调用分发
+
+### 工具开发规范
+- 创建新工具：继承 `Tool` 抽象类，实现 `name()`、`description()`、`parameters()`、`execute()` 方法
+- 注册工具：在 `AppServiceProvider` 中调用 `ToolRegistry::register($tool)`
+- 工具执行：
+  - `execute()` 方法接收 `array $args`，返回字符串结果
+  - 超时控制：通过 `AGENT_TOOL_TIMEOUT_SECONDS` 配置
+  - 结果截断：超过 `AGENT_TOOL_RESULT_MAX_BYTES` 会自动截断并标记
+- 工具参数：使用 JSON Schema 格式定义，会自动传递给 OpenAI API

 ### 测试规范
- 所有测试使用 PHPUnit（非 Pest）
- Feature 测试必须测试完整的 HTTP 请求流程
- 测试中使用 Factory 创建模型数据
- 修改代码后必须运行相关测试确保通过
+- **框架**：所有测试使用 PHPUnit（非 Pest）
+- **Feature 测试**：必须测试完整的 HTTP 请求流程
+  - 使用 `RefreshDatabase` trait 在测试间刷新数据库
+  - 使用 `Queue::fake()` 模拟队列
+  - 使用 `Redis::shouldReceive()` 模拟 Redis 发布
+- **测试数据**：使用 Factory 创建模型数据
+- **运行测试**：修改代码后必须运行相关测试确保通过
+  ```bash
+  # 运行所有测试
+  docker compose exec app php artisan test
+
+  # 运行特定测试方法
+  docker compose exec app php artisan test --filter=testAppendMessageWithDedupe
+  ```

 ### 队列配置
- 开发环境可使用同步队列：`.env` 中设置 `QUEUE_CONNECTION=sync`
- 生产环境使用 Redis 队列 + Horizon 监控
- `AgentRunJob` 在队列中异步执行
+- **开发环境**：可使用同步队列，`.env` 中设置 `QUEUE_CONNECTION=sync`
+  - 优点：调试方便，错误堆栈清晰
+  - 缺点：阻塞 HTTP 请求
+- **生产环境**：使用 Redis 队列 + Horizon 监控
+  - `AgentRunJob` 和 `ToolRunJob` 在队列中异步执行
+  - Horizon 仪表板：http://localhost:8000/horizon
+- **Job 配置**：通过 `config/agent.php` 控制重试次数、退避时间、超时

 ### 幂等性设计
- 所有可能重复调用的操作都使用 `dedupe_key`
- `RunDispatcher` 通过 `trigger_message_id` 确保不会为同一 prompt 重复创建 run
- SSE 通过 `Last-Event-ID` / `after_seq` 支持断线续传
+- **dedupe_key 机制**：所有可能重复调用的操作都使用 `dedupe_key`
+  - 基于 UNIQUE 约束 `unique(session_id, dedupe_key)` 自动去重
+  - 重复请求返回已有消息（相同 message_id 和 seq）
+- **Run 幂等**：`RunDispatcher` 通过 `trigger_message_id` 的 dedupe_key 确保不会为同一 prompt 重复创建 run
+- **SSE 续传**：通过 `Last-Event-ID` / `after_seq` 支持断线续传
+- **消息幂等模式**：
+  - `run:{runId}:agent:message` - Agent 最终回复
+  - `run:{runId}:agent:delta:{index}` - 流式增量
+  - `run:{runId}:status:{status}` - Run 状态
+  - `run:{runId}:tool:call:{toolCallId}` - 工具调用
+  - `run:{runId}:tool:result:{toolCallId}` - 工具结果
+
+### 性能优化建议
+- **上下文加载**：`ContextBuilder` 只加载最近 20 条消息，可通过配置调整
+- **消息分页**：`listMessagesBySeq()` 使用 `after_seq` + `limit` 增量拉取
+- **索引优化**：`(session_id, seq)` 和 `(session_id, dedupe_key)` 复合索引加速查询
+- **Redis 发布**：消息追加后异步发布，使用 `DB::afterCommit()` 保证顺序
+- **SSE 优化**：backlog 限制 200 条，心跳 15 秒，gap 检测自动回补

 ## 环境变量关键配置

@@ -294,10 +514,14 @@ DB_CONNECTION=pgsql
 DB_HOST=pgsql
 DB_PORT=5432
 DB_DATABASE=ars_backend
+DB_USERNAME=ars
+DB_PASSWORD=secret

 # Redis
+REDIS_CLIENT=phpredis
 REDIS_HOST=redis
 REDIS_PORT=6379
+CACHE_STORE=redis

 # 队列
 QUEUE_CONNECTION=redis  # 或 sync（开发用）
@@ -308,6 +532,57 @@ AUTH_GUARD=api

 # CORS
 CORS_ALLOWED_ORIGINS=http://localhost:5173
+
+# OpenAI 兼容 API 配置
+AGENT_OPENAI_BASE_URL=https://api.openai.com/v1  # 支持任何 OpenAI 兼容端点
+AGENT_OPENAI_API_KEY=                            # 为空时使用 DummyProvider
+AGENT_OPENAI_ORGANIZATION=                       # 可选
+AGENT_OPENAI_PROJECT=                            # 可选
+AGENT_OPENAI_MODEL=gpt-4o-mini
+AGENT_OPENAI_TEMPERATURE=0.7
+AGENT_OPENAI_TOP_P=1.0
+AGENT_OPENAI_INCLUDE_USAGE=false
+
+# Agent Provider HTTP 配置（重试机制）
+AGENT_PROVIDER_TIMEOUT=30              # HTTP 请求超时（秒）
+AGENT_PROVIDER_CONNECT_TIMEOUT=5       # 连接超时（秒）
+AGENT_PROVIDER_RETRY_TIMES=1           # 建立流前重试次数（仅连接失败/429/5xx 且未产出事件时）
+AGENT_PROVIDER_RETRY_BACKOFF_MS=500    # 重试退避毫秒（指数退避）
+
+# Agent Run Job 配置
+AGENT_RUN_JOB_TRIES=1                  # 队列重试次数
+AGENT_RUN_JOB_BACKOFF=3                # 重试退避秒数
+AGENT_RUN_JOB_TIMEOUT=600              # Job 超时时间（秒）
+
+# 工具系统配置
+AGENT_TOOL_MAX_CALLS_PER_RUN=1         # 单个父 Run 允许的工具调用次数
+AGENT_TOOL_WAIT_TIMEOUT_MS=15000       # 等待 tool.result 的超时时间（毫秒）
+AGENT_TOOL_WAIT_POLL_MS=200            # 等待工具结果轮询间隔（毫秒）
+AGENT_TOOL_TIMEOUT_SECONDS=15          # 单个工具执行超时（秒，超出记为 TIMEOUT）
+AGENT_TOOL_RESULT_MAX_BYTES=4096       # 工具结果最大保存字节数（截断后仍会写入）
+AGENT_TOOL_CHOICE=auto                 # OpenAI tool_choice 选项（auto/required 等）
+AGENT_TOOL_JOB_TRIES=1                 # ToolRunJob 重试次数
+AGENT_TOOL_JOB_BACKOFF=3               # ToolRunJob 重试退避秒数
+AGENT_TOOL_JOB_TIMEOUT=120             # ToolRunJob 超时时间（秒）
+```
+
+## 初始化新环境
+
+```bash
+# 1. 复制环境配置
+cp .env.example .env
+
+# 2. 生成应用密钥
+docker compose exec app php artisan key:generate
+
+# 3. 生成 JWT 密钥
+docker compose exec app php artisan jwt:secret
+
+# 4. 运行迁移
+docker compose exec app php artisan migrate
+
+# 5. （可选）创建测试用户
+docker compose exec app php artisan db:seed
 ```

 ## 相关文档
@@ -315,3 +590,90 @@ CORS_ALLOWED_ORIGINS=http://localhost:5173
 - API 详细文档：`docs/ChatSession/chat-session-api.md`
 - OpenAPI 规范：`docs/ChatSession/chat-session-openapi.yaml`
 - 用户管理文档：`docs/User/user-api.md`
+
+## 常见问题排查
+
+### 队列任务不执行
+- 检查 Horizon 是否运行：`docker compose ps horizon`
+- 查看 Horizon 日志：`docker compose logs -f horizon`
+- 检查 Redis 连接：
+  ```bash
+  docker compose exec app php artisan tinker
+  > Redis::ping()  # 应返回 "PONG"
+  ```
+- 查看失败的任务：`docker compose exec app php artisan queue:failed`
+- 重试失败任务：`docker compose exec app php artisan queue:retry all`
+
+### SSE 连接断开
+- 检查 Nginx/代理是否支持 SSE（需要禁用缓冲）
+- 确认客户端正确处理 `Last-Event-ID` 续传
+- 查看 Redis 发布日志
+- 测试环境下 SSE 会自动回退到仅返回 backlog（无实时推送）
+
+### Agent Run 失败
+- 查看 `messages` 表中 `type=error` 的消息：
+  ```sql
+  SELECT message_id, session_id, content, payload
+  FROM messages
+  WHERE type = 'error'
+  ORDER BY created_at DESC
+  LIMIT 10;
+  ```
+- 检查 `payload.error_type`、`payload.provider`、`payload.retryable`、`payload.details`
+- 检查 Provider 配置：
+  ```bash
+  docker compose exec app php artisan config:show agent
+  ```
+- 查看实时日志：
+  ```bash
+  docker compose exec app php artisan pail
+  # 或查看容器日志
+  docker compose logs -f app
+  ```
+- 测试 OpenAI API Key：
+  ```bash
+  docker compose exec app php artisan tinker
+  > $provider = app(App\Services\Agent\AgentProviderInterface::class);
+  > $context = new App\Services\Agent\AgentContext('test', []);
+  > foreach ($provider->stream($context) as $event) { dump($event); }
+  ```
+
+### 工具调用问题
+- 检查工具是否注册：
+  ```bash
+  docker compose exec app php artisan tinker
+  > $registry = app(App\Services\Tool\ToolRegistry::class);
+  > dump($registry->openAiToolsSpec());
+  ```
+- 查看 tool.call 和 tool.result 消息：
+  ```sql
+  SELECT message_id, type, content, payload
+  FROM messages
+  WHERE session_id = 'xxx' AND type IN ('tool.call', 'tool.result')
+  ORDER BY seq;
+  ```
+- 检查工具调用上限：配置 `AGENT_TOOL_MAX_CALLS_PER_RUN`
+- 工具执行超时：检查 `payload.status` 是否为 `TIMEOUT`
+
+### 数据库迁移问题
+- 确保 PostgreSQL 已启动：`docker compose ps pgsql`
+- 查看迁移状态：`docker compose exec app php artisan migrate:status`
+- 检查数据库连接：
+  ```bash
+  docker compose exec app php artisan tinker
+  > DB::connection()->getPdo()
+  ```
+- 查看数据库日志：`docker compose logs -f pgsql`
+
+### 消息 seq 不连续或重复
+- 检查是否有并发追加消息（应使用行锁 + 事务）
+- 确认所有消息追加都通过 `ChatService::appendMessage()`
+- 查看 unique 约束冲突日志
+
+### 调试技巧
+- **实时日志**：`docker compose exec app php artisan pail`
+- **Telescope**：访问 http://localhost:8000/telescope 查看请求、查询、队列
+- **Tinker REPL**：`docker compose exec app php artisan tinker` 交互式调试
+- **查看配置**：`php artisan config:show agent`
+- **查看路由**：`php artisan route:list`
+- **数据库查询日志**：在 `.env` 中设置 `DB_LOG_QUERIES=true`