docs: 更新项目文档

2025-12-12 14:28:34 +08:00
parent 2fe1c55997
commit b17649930b
6 changed files with 1894 additions and 128 deletions
@@ -0,0 +1,354 @@
+# @ai-assistant/server
+
+HTTP/WebSocket server for AI Terminal Assistant - provides REST API, WebSocket, and SSE endpoints.
+
+## 📦 Installation
+
+```bash
+pnpm add @ai-assistant/server
+```
+
+## 🌟 Features
+
+- **REST API** - Full CRUD operations for sessions and tools
+- **WebSocket** - Real-time bidirectional communication
+- **Server-Sent Events** - Streaming status updates
+- **Authentication** - Token-based auth for non-localhost
+- **Session Management** - Persistent session handling
+- **CORS Support** - Configurable cross-origin access
+- **Built with Hono** - Lightweight, fast web framework
+- **Bun Runtime** - Native WebSocket and performance
+
+## 🏗️ Architecture
+
+```
+src/
+├── index.ts               # Main server setup with Hono
+├── routes/
+│   ├── sessions.ts        # Session management endpoints
+│   ├── tools.ts           # Tool execution endpoints
+│   ├── config.ts          # Configuration endpoints
+│   └── health.ts          # Health check endpoint
+├── ws.ts                  # WebSocket handler
+├── sse.ts                 # Server-Sent Events handler
+├── agent/
+│   ├── adapter.ts         # Core agent adapter
+│   └── session.ts         # Session management
+├── auth/
+│   ├── token.ts           # Token generation/validation
+│   └── middleware.ts      # Auth middleware
+├── middleware/
+│   ├── cors.ts            # CORS configuration
+│   ├── error.ts           # Error handling
+│   └── logging.ts         # Request logging
+└── types/
+    └── index.ts           # TypeScript definitions
+```
+
+## 🚀 Quick Start
+
+### Basic Server Setup
+
+```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('Server running on http://localhost:3000');
+```
+
+### Standalone Usage
+
+```bash
+# Development mode with hot reload
+pnpm start:dev
+
+# Production mode
+pnpm start
+
+# With custom configuration
+ANTHROPIC_API_KEY=sk-ant-xxx SERVER_PORT=8080 pnpm start
+```
+
+## 📡 API Endpoints
+
+### REST API
+
+#### Sessions
+```typescript
+// Create session
+POST /api/sessions
+Response: { id: string, status: 'idle' | 'busy', createdAt: string }
+
+// Get session
+GET /api/sessions/:id
+Response: { id: string, status: string, messages: Message[] }
+
+// List sessions
+GET /api/sessions
+Response: Session[]
+
+// Delete session
+DELETE /api/sessions/:id
+Response: { success: boolean }
+```
+
+#### Tools
+```typescript
+// List available tools
+GET /api/tools
+Response: Tool[]
+
+// Execute tool
+POST /api/tools/:name/execute
+Body: { params: any, sessionId?: string }
+Response: { result: any }
+```
+
+#### Configuration
+```typescript
+// Get configuration
+GET /api/config
+Response: { model: string, maxTokens: number, ... }
+
+// Update configuration
+PUT /api/config
+Body: { model?: string, maxTokens?: number, ... }
+Response: { success: boolean, config: Config }
+```
+
+### WebSocket Protocol
+
+```typescript
+// Connect
+ws://localhost:3000/api/ws/:sessionId
+
+// Client → Server Messages
+{
+  type: 'message',
+  payload: {
+    content: string,
+    attachments?: Attachment[]
+  }
+}
+
+// Server → Client Messages
+{
+  type: 'chunk' | 'done' | 'error' | 'status',
+  payload: {
+    content?: string,      // For chunk
+    response?: Message,    // For done
+    error?: string,        // For error
+    status?: string        // For status
+  }
+}
+```
+
+### Server-Sent Events
+
+```typescript
+// Connect for status updates
+GET /api/sse/:sessionId
+Accept: text/event-stream
+
+// Event format
+event: status
+data: { "status": "processing", "progress": 0.5 }
+
+event: complete
+data: { "result": "Task completed" }
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+
+```env
+# Required
+ANTHROPIC_API_KEY=sk-ant-xxxxx
+
+# Optional
+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
+```
+
+### Programmatic Configuration
+
+```typescript
+interface ServerConfig {
+  port?: number;              // Server port (default: 3000)
+  host?: string;              // Server host (default: localhost)
+  apiKey: string;             // Anthropic API key
+  cors?: {
+    origin: string | string[];
+    credentials?: boolean;
+  };
+  auth?: {
+    enabled: boolean | 'auto'; // Auto enables for non-localhost
+    tokenSecret?: string;
+  };
+  agent?: {
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+  };
+  logging?: {
+    level: 'debug' | 'info' | 'warn' | 'error';
+  };
+}
+```
+
+## 🔐 Authentication
+
+The server automatically enables token authentication when accessed from non-localhost addresses:
+
+```typescript
+// Generate token
+POST /api/auth/token
+Body: { password?: string }
+Response: { token: string, expiresIn: number }
+
+// Use token in requests
+Authorization: Bearer <token>
+
+// Or in WebSocket
+ws://server/api/ws/:sessionId?token=<token>
+```
+
+## 🧪 Testing
+
+```bash
+# Run tests
+pnpm test
+
+# Run with coverage
+pnpm test:coverage
+
+# E2E tests
+pnpm test:e2e
+```
+
+### Test Examples
+
+```typescript
+import { testClient } from '@ai-assistant/server/test';
+
+describe('Server API', () => {
+  const client = testClient({ port: 3001 });
+
+  beforeAll(() => client.start());
+  afterAll(() => client.stop());
+
+  test('create session', async () => {
+    const session = await client.post('/api/sessions');
+    expect(session.id).toBeDefined();
+    expect(session.status).toBe('idle');
+  });
+
+  test('websocket chat', async () => {
+    const ws = client.ws('/api/ws/test-session');
+
+    ws.send({ type: 'message', payload: { content: 'Hello' } });
+
+    const response = await ws.waitFor('done');
+    expect(response.payload.response).toBeDefined();
+  });
+});
+```
+
+## 🔌 Integration Examples
+
+### With 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);
+```
+
+### With 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
+});
+```
+
+## 📊 Monitoring
+
+### Health Check
+
+```bash
+curl http://localhost:3000/api/health
+# Response: { status: 'healthy', uptime: 123456, sessions: 5 }
+```
+
+### Metrics Endpoint
+
+```bash
+curl http://localhost:3000/api/metrics
+# Response: Prometheus-formatted metrics
+```
+
+## 🚀 Deployment
+
+### 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"
+    }
+  }]
+}
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please follow the contribution guidelines in the main repository.
+
+## 📄 License
+
+MIT License - see [LICENSE](../../LICENSE) for details.
+
+## 🔗 Links
+
+- [Main Repository](https://github.com/username/ai-terminal-assistant)
+- [API Documentation](https://docs.example.com/server)
+- [OpenAPI Spec](https://api.example.com/openapi.json)