# @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)