From dafa8f6b064b233d75a6a1969ea22ee421deac66 Mon Sep 17 00:00:00 2001 From: ROOG Date: Sun, 14 Dec 2025 22:01:59 +0800 Subject: [PATCH] =?UTF-8?q?main:=20=E8=B0=83=E6=95=B4=20README=EF=BC=8C?= =?UTF-8?q?=E6=8F=8F=E8=BF=B0=E9=A1=B9=E7=9B=AE=E6=9E=B6=E6=9E=84=E4=B8=8E?= =?UTF-8?q?=E5=BF=AB=E9=80=9F=E5=90=AF=E5=8A=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 重新组织 README，详细说明愿景与运行目标 - 增加系统架构概览，包括存储、鉴权与实时功能介绍 - 提供快速启动指南，包括服务构建和迁移步骤 - 列出 API 功能，并说明状态与门禁规则 - 补充开发验证示例与后续演进方向 --- README.md | 123 ++++++++++++++++++++++++------------------------------ 1 file changed, 54 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index c206947..ed1571d 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,65 @@ -

Laravel Logo

+# Agent Runtime Server (ARS) · Laravel + Octane + Docker -

-Build Status -Total Downloads -Latest Stable Version -License -

+> 自建可部署的 Agent Runtime Server。愿景：兼容大部分 Agent 模型、随时在 Web 终端输入指令/查看日志、断开后任务继续执行，重新连入能续上会话。 +> +> “输入 prompt 就能离开工位，路上/手机继续 approve 和观察”。 -## Local Development (Docker + FrankenPHP Octane) +## 🎯 愿景与思路（摘录） +- 兼容多数 Agent 模型，提供可观测的运行日志。 +- Web 终端可随时输入/查看；断线不中断，重连可续。 +- 面向开源生态，避免被单一厂商闭锁；先做最小实现，再逐步拆分组件。 -Everything runs in containers; no PHP/Composer is required on the host. +## 🏗️ 当前架构概览 +- **运行**：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` 渠道。 -1. Build the FrankenPHP image (installs PHP extensions, Composer, git): `docker compose build` -2. Start the stack (app + PostgreSQL + Redis): `docker compose up -d app pgsql redis` -3. Tail app logs: `docker compose logs -f app` -4. Run framework commands: `docker compose exec app php artisan migrate` -5. Stop and clean up: `docker compose down` (add `-v` to drop databases/Redis data) +## 🚀 快速启动 +```bash +# 构建并启动 +docker compose build +docker compose up -d app pgsql redis -Notes: -- `docker/app/entrypoint.sh` will run `composer install`, copy `.env` if missing, generate `APP_KEY`, and boot Octane with `--watch`. -- Config sets `OCTANE_SERVER=frankenphp` by default (see `.env` and `config/octane.php`). -- PostgreSQL service: host `pgsql`, port `5432`, database `ars_backend`, user `ars`, password `secret` (see `.env.example`). -- Redis service: host `redis`, port `6379`, default no password, client `phpredis`. -- API 默认使用 JWT：`AUTH_GUARD=api`，会话驱动为 `array`（无状态）。首次运行如需重置密钥：`docker compose run --rm --entrypoint=php app artisan jwt:secret --force`。 -- API 说明文档：`docs/user/user-api.md`（中文）；OpenAPI/Swagger 规范：`docs/user/user-openapi.yaml`（可导入 Swagger UI / Postman）。 -- ChatSession 接口文档：`docs/ChatSession/chat-session-api.md`；OpenAPI：`docs/ChatSession/chat-session-openapi.yaml`。 -- CORS：通过全局中间件开启，允许域名由环境变量 `CORS_ALLOWED_ORIGINS` 配置（默认 `http://localhost:5173`，多域名用逗号分隔）。 -- 项目沟通与自然语言默认使用中文。 +# 首次迁移（仅需一次） +docker compose exec app php artisan migrate -## About Laravel +# 运行 Feature 测试 +docker compose exec app php artisan test --testsuite=Feature +``` -Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as: +## 🔑 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。 -- [Simple, fast routing engine](https://laravel.com/docs/routing). -- [Powerful dependency injection container](https://laravel.com/docs/container). -- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage. -- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent). -- Database agnostic [schema migrations](https://laravel.com/docs/migrations). -- [Robust background job processing](https://laravel.com/docs/queues). -- [Real-time event broadcasting](https://laravel.com/docs/broadcasting). +详细字段/示例：`docs/ChatSession/chat-session-api.md`，OpenAPI：`docs/ChatSession/chat-session-openapi.yaml`。用户管理/鉴权文档：`docs/User/user-api.md`。 -Laravel is accessible, powerful, and provides tools required for large, robust applications. +## 🔒 状态与门禁规则 +- `OPEN`：正常追加。 +- `LOCKED`：拒绝 `role=USER && type=user.prompt`。 +- `CLOSED`：拒绝追加，例外 `role=SYSTEM && type in [run.status, error]`。 +- 幂等：同一 session + dedupe_key 返回已有消息（同 message_id/seq）。 -## Learning Laravel +## 🔌 开发/验证 +- 迁移：`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" +``` -Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. You can also check out [Laravel Learn](https://laravel.com/learn), where you will be guided through building a modern Laravel application. - -If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library. - -## Laravel Sponsors - -We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com). - -### Premium Partners - -- **[Vehikl](https://vehikl.com)** -- **[Tighten Co.](https://tighten.co)** -- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)** -- **[64 Robots](https://64robots.com)** -- **[Curotec](https://www.curotec.com/services/technologies/laravel)** -- **[DevSquad](https://devsquad.com/hire-laravel-developers)** -- **[Redberry](https://redberry.international/laravel-development)** -- **[Active Logic](https://activelogic.com)** - -## Contributing - -Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions). - -## Code of Conduct - -In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct). - -## Security Vulnerabilities - -If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed. - -## License - -The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). +## 📌 后续演进（规划） +- Agent Loop/Tools/Policy Engine/Context Store 解耦与插件化。 +- 更丰富的前端控制台：日志流、工具审批、移动端友好。 +- 兼容多家模型/工具 SDK，保持开放生态。