57 lines
1.6 KiB
Markdown
57 lines
1.6 KiB
Markdown
# Session (dsh-session)
|
||
|
||
会话事件流管理。
|
||
|
||
**包名:** `@deepseek-ai/dsh-session`
|
||
**服务名:** `ctx.session`
|
||
|
||
## 概述
|
||
|
||
Session 是 Agent 的对话状态容器。所有模型可见的内容都必须经过 session 事件流记录——这是"model-visible = logged"原则的实现。
|
||
|
||
## SessionSurface
|
||
|
||
会话的外部接口，用于查询当前状态。
|
||
|
||
### surface.messages
|
||
|
||
- **类型:** `Message[]`
|
||
|
||
当前会话的完整消息列表（经过 compaction 处理后的视图）。
|
||
|
||
### surface.events
|
||
|
||
- **类型:** `SessionEvent[]`
|
||
|
||
原始事件流。
|
||
|
||
## SessionEvent
|
||
|
||
会话中所有变更以事件形式记录：
|
||
|
||
```typescript
|
||
type SessionEvent =
|
||
| { type: 'user/message'; content: ContentBlock[] }
|
||
| { type: 'assistant/message'; content: ContentBlock[] }
|
||
| { type: 'tool/call'; name: string; args: unknown; callId: CallId }
|
||
| { type: 'tool/result'; callId: CallId; content: ContentBlock[]; isError?: boolean }
|
||
| { type: 'compact/start'; range: [number, number] }
|
||
| { type: 'compact/end'; summary: string }
|
||
| { type: 'todo/write'; items: TodoItem[] }
|
||
// ... 更多事件类型
|
||
```
|
||
|
||
## 设计原则
|
||
|
||
### Model-visible = Logged
|
||
|
||
任何到达模型请求的内容都必须能从 session log 重建。如果你要引入新的模型可见输入，必须先定义对应的 session event。
|
||
|
||
### 事件是 append-only
|
||
|
||
Session 事件流是只追加的。修改历史（如 compaction）通过新事件（compact/start + compact/end）表达，而不是修改旧事件。
|
||
|
||
### 持久化
|
||
|
||
Session 事件流可以通过 `dsh-session-persistence` 持久化到磁盘（JSONL 或 SQLite），实现跨进程恢复。
|