# streamctx — MCP 2.1 流式上下文引擎

> 把 Anthropic MCP 2.1「实时流式上下文更新」从协议概念，落地为一套可运行、可部署、可嵌入的增量上下文交付引擎。

[![Python](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![CI](https://img.shields.io/badge/CI-GitHub%20Actions-blue.svg)](.github/workflows/ci.yml)

## 一句话

MCP 2.1 引入了**流式上下文更新**：AI 助手通过增量事件接收上下文变化，而无需每次全量重载，从而把长会话的上下文加载延迟降低最高 75%、显著节省 Token。`streamctx` 是这一能力的**开源、零重型依赖**实现——一套「服务端 + SDK + 传输 + 预算 + 可观测」完整的增量上下文引擎。

## 为什么需要它

传统 MCP 的上下文是「全量快照」模型：每次上下文变化，客户端都要重新拉取整份上下文。上下文一大，这就是灾难：

- **延迟高**：每轮都全量传输，网络往返成本与上下文体积成正比
- **Token 浪费**：大量未变化的内容被反复重传
- **无法流式**：无法在长会话中边用边更新

`streamctx` 用「增量 diff + 版本向量 + 断点续传」解决上述问题：只推送变化的部分，客户端按 seq 应用，落后太多时自动降级为全量快照。

## 特性

- ✅ **增量 diff**：行级 LCS 最小化差异，只推送变化部分
- ✅ **版本向量 + Lamport 时钟**：多会话因果一致、断点续传锚点
- ✅ **三种传输**：进程内（零依赖）/ SSE（stdlib）/ WebSocket（可选）
- ✅ **Token 预算与加权 LRU 驱逐**：控制上下文体积
- ✅ **快照/增量自适应降级**：落后超过阈值自动切全量快照
- ✅ **断线重连 + 断点续传**：指数退避 + checkpoint 恢复
- ✅ **主题订阅**：精确 topic + glob 模式路由
- ✅ **可观测**：指标 / 追踪 / 健康检查
- ✅ **插件系统**：去重 / 计数 / 审计
- ✅ **零核心依赖**：`pip install streamctx` 即可跑通全部核心功能
- ✅ **FastAPI / stdlib 双控制面** + CLI + Docker/K8s/Helm/CI

## 快速开始

```bash
# 安装（核心零依赖）
pip install -e .

# 自检
python -m streamctx doctor

# 端到端演示（零依赖）
python examples/demo_basic.py

# 启动 SSE 服务
python -m streamctx serve --config config/config.yaml
```

## 架构

```
                ┌─────────────────────────────────────────────┐
  写入源        │            StreamContextEngine               │
 (LLM/文档) ──▶ │  ContextManager ── DeltaEngine ── Budget    │
                │       │              │            │          │
                │  SessionManager   Subscription  Metrics     │
                └───────┼──────────────┼───────────────────────┘
                        │ 事件流（snapshot / delta / ack）      │
        ┌───────────────┼──────────────┼───────────────┐
        ▼               ▼              ▼               ▼
   in-process        SSE            WebSocket       (FastAPI)
        │
        ▼
  StreamClient（本地视图 + seq 确认 + 断点续传）
```

模块总览见 [docs/architecture.md](docs/architecture.md)。

## 目录结构

```
streamctx/
├── streamctx/            # 核心包
│   ├── engine.py         # 引擎门面
│   ├── context.py        # 上下文状态与管理
│   ├── delta_engine.py   # 增量引擎
│   ├── diff.py           # 行级 LCS diff
│   ├── patch.py          # 增量应用
│   ├── tokenizer.py      # Token 估算
│   ├── budget.py         # Token 预算与驱逐
│   ├── session.py        # 会话
│   ├── subscription.py   # 主题订阅
│   ├── protocol.py       # 协议序列化
│   ├── transport/        # 进程内 / SSE / WebSocket
│   ├── server/           # stdlib SSE / FastAPI
│   ├── client/           # 客户端 SDK
│   ├── adapters/         # mock / openai / anthropic / ollama
│   ├── backends/         # 内存 / redis
│   ├── observability/    # 指标 / 追踪 / 健康
│   ├── plugins/          # 插件
│   ├── utils/            # 配置 / 日志
│   └── cli/              # 命令行
├── examples/             # 演示脚本
├── tests/                # 单元测试
├── benchmarks/           # 基准
├── docs/                 # 文档
├── model_cards/          # 设计决策卡
├── deploy/               # K8s / Helm
├── Dockerfile / docker-compose.yml
└── .github/workflows/    # CI / Release
```

## 配置

复制 `config/config.example.yaml` 为 `config/config.yaml`，按需修改：

```yaml
actor: "server"
session_ttl: 300.0        # 会话 TTL（秒）
max_tokens: 4096          # 上下文最大 token
soft_ratio: 0.9           # 软上限比例
evict_on_exceed: true     # 超限是否驱逐
snapshot_ratio: 0.5       # 变化超过该比例降级为快照
history_limit: 500        # 版本历史上限
server:
  host: "127.0.0.1"
  port: 9000
```

## 更多

- 详细项目介绍：见 [INTRO.md](INTRO.md)
- 协议设计：见 [docs/protocol.md](docs/protocol.md)
- 快速上手：见 [docs/quickstart.md](docs/quickstart.md)
- API 参考：见 [docs/api-reference.md](docs/api-reference.md)

## License

MIT License，详见 [LICENSE](LICENSE)。