docs: 添加中文文档
This commit is contained in:
@@ -0,0 +1,354 @@
|
||||
# @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)
|
||||
Reference in New Issue
Block a user