354 lines
7.0 KiB
Markdown
354 lines
7.0 KiB
Markdown
# @ai-assistant/server
|
||
|
||
AI Terminal Assistant 的 HTTP/WebSocket 服务器 - 提供 REST API、WebSocket 和 SSE 端点。
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
pnpm add @ai-assistant/server
|
||
```
|
||
|
||
## 🌟 功能特性
|
||
|
||
- **REST API** - 会话和工具的完整 CRUD 操作
|
||
- **WebSocket** - 实时双向通信
|
||
- **服务器推送事件** - 流式状态更新
|
||
- **身份验证** - 非本地访问的令牌认证
|
||
- **会话管理** - 持久化会话处理
|
||
- **CORS 支持** - 可配置的跨域访问
|
||
- **基于 Hono 构建** - 轻量级、快速的 Web 框架
|
||
- **Bun 运行时** - 原生 WebSocket 和高性能
|
||
|
||
## 🏗️ 架构
|
||
|
||
```
|
||
src/
|
||
├── index.ts # 使用 Hono 的主服务器设置
|
||
├── routes/
|
||
│ ├── sessions.ts # 会话管理端点
|
||
│ ├── tools.ts # 工具执行端点
|
||
│ ├── config.ts # 配置端点
|
||
│ └── health.ts # 健康检查端点
|
||
├── ws.ts # WebSocket 处理器
|
||
├── sse.ts # 服务器推送事件处理器
|
||
├── agent/
|
||
│ ├── adapter.ts # 核心代理适配器
|
||
│ └── session.ts # 会话管理
|
||
├── auth/
|
||
│ ├── token.ts # 令牌生成/验证
|
||
│ └── middleware.ts # 认证中间件
|
||
├── middleware/
|
||
│ ├── cors.ts # CORS 配置
|
||
│ ├── error.ts # 错误处理
|
||
│ └── logging.ts # 请求日志
|
||
└── types/
|
||
└── index.ts # TypeScript 定义
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 基本服务器设置
|
||
|
||
```typescript
|
||
import { createServer } from '@ai-assistant/server';
|
||
|
||
const server = createServer({
|
||
port: 3000,
|
||
host: 'localhost',
|
||
apiKey: process.env.ANTHROPIC_API_KEY
|
||
});
|
||
|
||
await server.start();
|
||
console.log('服务器运行在 http://localhost:3000');
|
||
```
|
||
|
||
### 独立使用
|
||
|
||
```bash
|
||
# 开发模式（热重载）
|
||
pnpm start:dev
|
||
|
||
# 生产模式
|
||
pnpm start
|
||
|
||
# 自定义配置
|
||
ANTHROPIC_API_KEY=sk-ant-xxx SERVER_PORT=8080 pnpm start
|
||
```
|
||
|
||
## 📡 API 端点
|
||
|
||
### REST API
|
||
|
||
#### 会话管理
|
||
```typescript
|
||
// 创建会话
|
||
POST /api/sessions
|
||
响应: { id: string, status: 'idle' | 'busy', createdAt: string }
|
||
|
||
// 获取会话
|
||
GET /api/sessions/:id
|
||
响应: { id: string, status: string, messages: Message[] }
|
||
|
||
// 列出会话
|
||
GET /api/sessions
|
||
响应: Session[]
|
||
|
||
// 删除会话
|
||
DELETE /api/sessions/:id
|
||
响应: { success: boolean }
|
||
```
|
||
|
||
#### 工具
|
||
```typescript
|
||
// 列出可用工具
|
||
GET /api/tools
|
||
响应: Tool[]
|
||
|
||
// 执行工具
|
||
POST /api/tools/:name/execute
|
||
请求体: { params: any, sessionId?: string }
|
||
响应: { result: any }
|
||
```
|
||
|
||
#### 配置
|
||
```typescript
|
||
// 获取配置
|
||
GET /api/config
|
||
响应: { model: string, maxTokens: number, ... }
|
||
|
||
// 更新配置
|
||
PUT /api/config
|
||
请求体: { model?: string, maxTokens?: number, ... }
|
||
响应: { success: boolean, config: Config }
|
||
```
|
||
|
||
### WebSocket 协议
|
||
|
||
```typescript
|
||
// 连接
|
||
ws://localhost:3000/api/ws/:sessionId
|
||
|
||
// 客户端 → 服务器消息
|
||
{
|
||
type: 'message',
|
||
payload: {
|
||
content: string,
|
||
attachments?: Attachment[]
|
||
}
|
||
}
|
||
|
||
// 服务器 → 客户端消息
|
||
{
|
||
type: 'chunk' | 'done' | 'error' | 'status',
|
||
payload: {
|
||
content?: string, // chunk 类型时
|
||
response?: Message, // done 类型时
|
||
error?: string, // error 类型时
|
||
status?: string // status 类型时
|
||
}
|
||
}
|
||
```
|
||
|
||
### 服务器推送事件
|
||
|
||
```typescript
|
||
// 连接以获取状态更新
|
||
GET /api/sse/:sessionId
|
||
Accept: text/event-stream
|
||
|
||
// 事件格式
|
||
event: status
|
||
data: { "status": "processing", "progress": 0.5 }
|
||
|
||
event: complete
|
||
data: { "result": "任务完成" }
|
||
```
|
||
|
||
## 🔧 配置
|
||
|
||
### 环境变量
|
||
|
||
```env
|
||
# 必需
|
||
ANTHROPIC_API_KEY=sk-ant-xxxxx
|
||
|
||
# 可选
|
||
SERVER_PORT=3000
|
||
SERVER_HOST=localhost
|
||
SERVER_CORS_ORIGIN=http://localhost:5173
|
||
SERVER_AUTH_ENABLED=auto
|
||
SERVER_LOG_LEVEL=info
|
||
AI_MODEL=claude-sonnet-4-20250514
|
||
AI_MAX_TOKENS=4096
|
||
```
|
||
|
||
### 程序化配置
|
||
|
||
```typescript
|
||
interface ServerConfig {
|
||
port?: number; // 服务器端口（默认：3000）
|
||
host?: string; // 服务器主机（默认：localhost）
|
||
apiKey: string; // Anthropic API 密钥
|
||
cors?: {
|
||
origin: string | string[];
|
||
credentials?: boolean;
|
||
};
|
||
auth?: {
|
||
enabled: boolean | 'auto'; // auto 为非本地访问自动启用
|
||
tokenSecret?: string;
|
||
};
|
||
agent?: {
|
||
model?: string;
|
||
maxTokens?: number;
|
||
temperature?: number;
|
||
};
|
||
logging?: {
|
||
level: 'debug' | 'info' | 'warn' | 'error';
|
||
};
|
||
}
|
||
```
|
||
|
||
## 🔐 身份验证
|
||
|
||
当从非本地地址访问时，服务器会自动启用令牌认证：
|
||
|
||
```typescript
|
||
// 生成令牌
|
||
POST /api/auth/token
|
||
请求体: { password?: string }
|
||
响应: { token: string, expiresIn: number }
|
||
|
||
// 在请求中使用令牌
|
||
Authorization: Bearer <token>
|
||
|
||
// 或在 WebSocket 中
|
||
ws://server/api/ws/:sessionId?token=<token>
|
||
```
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 运行测试
|
||
pnpm test
|
||
|
||
# 运行覆盖率测试
|
||
pnpm test:coverage
|
||
|
||
# 端到端测试
|
||
pnpm test:e2e
|
||
```
|
||
|
||
### 测试示例
|
||
|
||
```typescript
|
||
import { testClient } from '@ai-assistant/server/test';
|
||
|
||
describe('服务器 API', () => {
|
||
const client = testClient({ port: 3001 });
|
||
|
||
beforeAll(() => client.start());
|
||
afterAll(() => client.stop());
|
||
|
||
test('创建会话', async () => {
|
||
const session = await client.post('/api/sessions');
|
||
expect(session.id).toBeDefined();
|
||
expect(session.status).toBe('idle');
|
||
});
|
||
|
||
test('WebSocket 对话', async () => {
|
||
const ws = client.ws('/api/ws/test-session');
|
||
|
||
ws.send({ type: 'message', payload: { content: '你好' } });
|
||
|
||
const response = await ws.waitFor('done');
|
||
expect(response.payload.response).toBeDefined();
|
||
});
|
||
});
|
||
```
|
||
|
||
## 🔌 集成示例
|
||
|
||
### 与 Express 集成
|
||
|
||
```typescript
|
||
import express from 'express';
|
||
import { createMiddleware } from '@ai-assistant/server';
|
||
|
||
const app = express();
|
||
app.use('/ai', createMiddleware({
|
||
apiKey: process.env.ANTHROPIC_API_KEY
|
||
}));
|
||
|
||
app.listen(3000);
|
||
```
|
||
|
||
### 与 Next.js 集成
|
||
|
||
```typescript
|
||
// app/api/ai/[...path]/route.ts
|
||
import { handleRequest } from '@ai-assistant/server/next';
|
||
|
||
export const { GET, POST, PUT, DELETE } = handleRequest({
|
||
apiKey: process.env.ANTHROPIC_API_KEY
|
||
});
|
||
```
|
||
|
||
## 📊 监控
|
||
|
||
### 健康检查
|
||
|
||
```bash
|
||
curl http://localhost:3000/api/health
|
||
# 响应: { status: 'healthy', uptime: 123456, sessions: 5 }
|
||
```
|
||
|
||
### 指标端点
|
||
|
||
```bash
|
||
curl http://localhost:3000/api/metrics
|
||
# 响应: Prometheus 格式的指标
|
||
```
|
||
|
||
## 🚀 部署
|
||
|
||
### Docker
|
||
|
||
```dockerfile
|
||
FROM oven/bun:1.0
|
||
WORKDIR /app
|
||
COPY package*.json ./
|
||
RUN bun install
|
||
COPY . .
|
||
EXPOSE 3000
|
||
CMD ["bun", "run", "start"]
|
||
```
|
||
|
||
### PM2
|
||
|
||
```json
|
||
{
|
||
"apps": [{
|
||
"name": "ai-server",
|
||
"script": "bun",
|
||
"args": "run start",
|
||
"env": {
|
||
"SERVER_PORT": 3000,
|
||
"ANTHROPIC_API_KEY": "sk-ant-xxx"
|
||
}
|
||
}]
|
||
}
|
||
```
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎贡献！请遵循主仓库中的贡献指南。
|
||
|
||
## 📄 许可证
|
||
|
||
MIT 许可证 - 查看 [LICENSE](../../LICENSE) 了解详情。
|
||
|
||
## 🔗 链接
|
||
|
||
- [主仓库](https://github.com/username/ai-terminal-assistant)
|
||
- [API 文档](https://docs.example.com/server)
|
||
- [OpenAPI 规范](https://api.example.com/openapi.json) |