---
name: server-design
description: Server 层设计：传输层架构决策、StelloAgent 映射原则、连接态管理模式。存储层见 server-storage，Engine 细节见 engine-design。
---

# Server 层（Service Layer）设计

> 相关 skill：**server-storage**（PG 持久化）、**engine-design**（Engine 内部）、**orchestrator-usage**（StelloAgent API）

---

## 架构分层

```
Transport Layer（Hono REST + ws WebSocket）
  ↓
Space 管理层（SpaceManager · AgentPool）
  ↓
PG Storage Layer（4 个 Storage Adapter）
  ↓
Core（@stello-ai/core — StelloAgent → SessionOrchestrator → Engine）
```

---

## 设计决策

- **WS 用 `ws` 库** — Hono 内置 WS 面向 edge，不适合 Node.js
- **WS 认证用 header** — API key 不暴露在 URL
- **stream 和 message 是独立消息类型** — 客户端显式选择
- **Space 级 WS 连接** — URL 中确定 spaceId，匹配 AgentPool per-space 缓存
- **REST 降级路径** — `/turn` 端点支持无 WS 的非流式对话
- **断连只 detach 不 leave** — runtime 通过 recyclePolicy 自然回收

---

## 连接态管理

ConnectionManager（纯内存，不持久化）：

```
connectionId → { userId, spaceId, sessionId | null }
```

- WS upgrade 时 bind(connId, userId, spaceId)
- session.enter 时 attach
- session.leave / socket close 时 detach
- socket close 时 unbind

---

## AgentPool 默认 fn 注入

AgentPool 支持内置默认 consolidateFn：

- `AgentPoolOptions.llm` 提供最小 LLM 调用接口
- Space 表存 `consolidatePrompt`
- 如果 buildConfig 未提供显式 fn，且 Space 有 prompt 且 llm 可用 → 自动注入默认实现
- buildConfig 提供的显式 fn 始终优先

跨 Session 的 reflection / 全局综合不由 Server 框架承担——服务端只暴露 `StelloAgent` 的 orchestrator-facing 数据 SDK（`listSessionDigests` / `putInsight` 等），应用层基于这些原语自行实现。

---

## createStelloServer 入口

`createStelloServer(options)` 返回 `StelloServer`，内部用 `@hono/node-server` 的 `serve()` 创建 HTTP server，再附着 `ws.WebSocketServer({ noServer: true })`。