# 服务模块 (server)

本模块提供了一个基于 HTTP 的 RESTful API 和 Server-Sent Events (SSE) 流接口，允许通过网络远程管理和与 Claw 会话进行交互。

## 概览

`server` 模块将 `runtime` 的核心功能封装为 Web 服务，其主要职责包括：
- **会话管理**：提供创建、列出和获取会话详情的端点。
- **消息分发**：接收用户消息并将其路由到相应的会话实例。
- **实时流推送**：通过 SSE 接口实时推送会话事件（如 AI 响应消息、状态快照）。
- **状态维护**：在内存中管理多个活跃会话的生命周期。

## 关键特性

- **RESTful API**：使用 `axum` 框架实现，遵循现代 Web 服务标准。
- **事件流 (SSE)**：支持 `text/event-stream`，允许客户端实时订阅会话更新。
- **并发处理**：利用 `tokio` 和 `broadcast` 频道，支持多个客户端同时监听同一会话的事件。
- **快照机制**：在建立连接时发送当前会话的完整快照，确保客户端能够同步历史状态。

## 实现逻辑

### 核心接口 (API Routes)

- `POST /sessions`: 创建一个新的对话会话。
- `GET /sessions`: 列出所有活跃会话的简要信息。
- `GET /sessions/{id}`: 获取指定会话的完整详细信息。
- `POST /sessions/{id}/message`: 向指定会话发送一条新消息。
- `GET /sessions/{id}/events`: 建立 SSE 连接，订阅该会话的实时事件流。

### 核心结构

- **`AppState`**: 存储全局状态，包括 `SessionStore` (由 `RwLock` 保护的哈希表) 和会话 ID 分配器。
- **`Session`**: 封装了 `runtime::Session` 实例，并包含一个用于广播事件的 `broadcast::Sender`。
- **`SessionEvent`**: 定义了流中传输的事件类型，包括 `Snapshot` (快照) 和 `Message` (新消息)。

### 工作流程

1. 启动服务并初始化 `AppState`。
2. 客户端通过 `POST /sessions` 开启一个新会话。
3. 客户端连接 `GET /sessions/{id}/events` 以监听响应。
4. 客户端通过 `POST /sessions/{id}/message` 发送 Prompt。
5. 服务端将消息存入 `runtime::Session`，并触发广播。SSE 流将该消息及后续的 AI 响应实时推送回客户端。

## 使用示例 (内部)

```rust
use server::{app, AppState};
use axum::Router;

// 创建应用路由
let state = AppState::new();
let router = app(state);

// 启动服务（示例）
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
axum::serve(listener, router).await.unwrap();
```