ai-terminal-assistant/packages/server/README.zh-CN.md

@ai-assistant/server

AI Terminal Assistant 的 HTTP/WebSocket 服务器 - 提供 REST API、WebSocket 和 SSE 端点。

📦 安装

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 定义

🚀 快速开始

基本服务器设置

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');

独立使用

# 开发模式（热重载）
pnpm start:dev

# 生产模式
pnpm start

# 自定义配置
ANTHROPIC_API_KEY=sk-ant-xxx SERVER_PORT=8080 pnpm start

📡 API 端点

REST API

会话管理

// 创建会话
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 }

工具

// 列出可用工具
GET /api/tools
响应: Tool[]

// 执行工具
POST /api/tools/:name/execute
请求体: { params: any, sessionId?: string }
响应: { result: any }

配置

// 获取配置
GET /api/config
响应: { model: string, maxTokens: number, ... }

// 更新配置
PUT /api/config
请求体: { model?: string, maxTokens?: number, ... }
响应: { success: boolean, config: Config }

WebSocket 协议

// 连接
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 类型时
  }
}

服务器推送事件

// 连接以获取状态更新
GET /api/sse/:sessionId
Accept: text/event-stream

// 事件格式
event: status
data: { "status": "processing", "progress": 0.5 }

event: complete
data: { "result": "任务完成" }

🔧 配置

环境变量

# 必需
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

程序化配置

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';
  };
}

🔐 身份验证

当从非本地地址访问时，服务器会自动启用令牌认证：

// 生成令牌
POST /api/auth/token
请求体: { password?: string }
响应: { token: string, expiresIn: number }

// 在请求中使用令牌
Authorization: Bearer <token>

// 或在 WebSocket 中
ws://server/api/ws/:sessionId?token=<token>

🧪 测试

# 运行测试
pnpm test

# 运行覆盖率测试
pnpm test:coverage

# 端到端测试
pnpm test:e2e

测试示例

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 集成

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 集成

// 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
});

📊 监控

健康检查

curl http://localhost:3000/api/health
# 响应: { status: 'healthy', uptime: 123456, sessions: 5 }

指标端点

curl http://localhost:3000/api/metrics
# 响应: Prometheus 格式的指标

🚀 部署

Docker

FROM oven/bun:1.0
WORKDIR /app
COPY package*.json ./
RUN bun install
COPY . .
EXPOSE 3000
CMD ["bun", "run", "start"]

PM2

{
  "apps": [{
    "name": "ai-server",
    "script": "bun",
    "args": "run start",
    "env": {
      "SERVER_PORT": 3000,
      "ANTHROPIC_API_KEY": "sk-ant-xxx"
    }
  }]
}

🤝 贡献

欢迎贡献！请遵循主仓库中的贡献指南。

📄 许可证

MIT 许可证 - 查看 LICENSE 了解详情。

🔗 链接

• 主仓库
• API 文档
• OpenAPI 规范