ROOG
c55534ad20
- 增加 Agent Run MVP-0，包括 RunDispatcher 和 AgentRunJob - 优化队列配置，支持 Redis 队列驱动，添加 Horizon 容器 - 更新 Docker 配置，细化角色分工，新增 Horizon 配置 - 增加测试任务 `TestJob`，扩展队列使用示例 - 更新 OpenAPI 规范，添加 Agent Run 相关接口及示例 - 编写文档，详细描述 Agent Run 流程与 MVP-0 功能 - 优化相关服务与文档，支持队列与异步运行
73 lines
4.3 KiB
Markdown
73 lines
4.3 KiB
Markdown
# Agent Runtime Server (ARS) · Laravel + Octane + Docker
|
||
|
||
> 自建可部署的 Agent Runtime Server。愿景：兼容大部分 Agent 模型、随时在 Web 终端输入指令/查看日志、断开后任务继续执行，重新连入能续上会话。
|
||
>
|
||
> “输入 prompt 就能离开工位，路上/手机继续 approve 和观察”。
|
||
|
||
## 🎯 愿景与思路（摘录）
|
||
- 兼容多数 Agent 模型，提供可观测的运行日志。
|
||
- Web 终端可随时输入/查看；断线不中断，重连可续。
|
||
- 面向开源生态，避免被单一厂商闭锁；先做最小实现，再逐步拆分组件。
|
||
|
||
## 🏗️ 当前架构概览
|
||
- **运行**：Docker Compose，FrankenPHP + Laravel Octane。
|
||
- **存储**：PostgreSQL（主存储），Redis（可选，用于 SSE 推送）。
|
||
- **鉴权**：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` 渠道。
|
||
- **Agent Run 编排（MVP-0）**：user.prompt 后自动触发 RunDispatcher → `run.status=RUNNING` → AgentRunJob（DummyProvider 返回一次性回复）→ `agent.message` + `run.status=DONE/FAILED/CANCELED` 落库；同 trigger_message 幂等、同会话只允许一个 RUNNING。
|
||
- **队列监控**：Horizon（本地默认开放 `/horizon`，非 local 环境默认拒绝访问）。
|
||
|
||
## 🚀 快速启动
|
||
```bash
|
||
# 构建并启动
|
||
docker compose build
|
||
docker compose up -d app horizon pgsql redis
|
||
|
||
# 首次迁移（仅需一次）
|
||
docker compose exec app php artisan migrate
|
||
|
||
# 运行 Feature 测试
|
||
docker compose exec app php artisan test --testsuite=Feature
|
||
|
||
# 队列（AgentRunJob）：开发可用同步队列，或用 Horizon
|
||
# 同步：.env / phpunit.xml 中 QUEUE_CONNECTION=sync
|
||
# Horizon：docker compose up -d horizon（需 composer install 安装 laravel/horizon，QUEUE_CONNECTION=redis）
|
||
```
|
||
|
||
## 🔑 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。
|
||
- Agent Run：user.prompt 自动触发；或 `POST /api/sessions/{id}/runs {trigger_message_id}` 手动触发，写入 `run.status/agent.message`。
|
||
|
||
详细字段/示例：`docs/ChatSession/chat-session-api.md`，OpenAPI：`docs/ChatSession/chat-session-openapi.yaml`。用户管理/鉴权文档：`docs/User/user-api.md`。
|
||
|
||
## 🔒 状态与门禁规则
|
||
- `OPEN`：正常追加。
|
||
- `LOCKED`：拒绝 `role=USER && type=user.prompt`。
|
||
- `CLOSED`：拒绝追加，例外 `role=SYSTEM && type in [run.status, error]`。
|
||
- 幂等：同一 session + dedupe_key 返回已有消息（同 message_id/seq）。
|
||
|
||
## 🔌 开发/验证
|
||
- 迁移：`docker compose exec app php artisan migrate`
|
||
- 测试：`docker compose exec app php artisan test --testsuite=Feature`
|
||
- cURL 示例（需 Bearer TOKEN）：
|
||
```bash
|
||
# 归档
|
||
curl -X POST http://localhost:8000/api/sessions/{sid}/archive -H "Authorization: Bearer $TOKEN"
|
||
# 单条消息
|
||
curl http://localhost:8000/api/sessions/{sid}/messages/{mid} -H "Authorization: Bearer $TOKEN"
|
||
# SSE（断线续传：可带 Last-Event-ID）
|
||
curl -N http://localhost:8000/api/sessions/{sid}/sse?after_seq=0 \
|
||
-H "Authorization: Bearer $TOKEN" -H "Accept: text/event-stream"
|
||
```
|
||
|
||
## 📌 后续演进（规划）
|
||
- Agent Loop/Tools/Policy Engine/Context Store 解耦与插件化。
|
||
- 更丰富的前端控制台：日志流、工具审批、移动端友好。
|
||
- 兼容多家模型/工具 SDK，保持开放生态。
|