# AIDelegateServer

**Repository Path**: coder-springxu/aidelegate-server

## Basic Information

- **Project Name**: AIDelegateServer
- **Description**: 模型代理服务
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AIDelegateServer — AI 代理服务

统一接入团队内各本地大模型（llama.cpp / Ollama / vLLM…），对外提供 **MCP 接口** + **OpenAI 兼容 REST API** 双入口；通过 TCP 长连接把分散在各机器上的模型"注册"到代理，按需轮询调度。代理本身**无状态转发，不承载推理**。

![架构](doc/01-overview.md)

## 功能速览

- 🔌 **双向接口**：OpenAI 兼容 `POST /v1/chat/completions`（含 SSE 流式）+ MCP `list_models` / `chat_completion`
- 🌐 **算力联邦**：多台模型机主动连入（NAT/防火墙友好），同名模型自动轮询
- 🔐 **两层静态认证**：调用方 API Key（Bearer）+ 客户端 Token（TCP 握手）
- 📊 **全链路可观测**：request-id 贯穿；结构化日志（耗时 / token / 首 token）

## 快速开始（3 条命令）

```bash
pnpm install
pnpm -r build

# 终端 1：起服务端（北向 8080 + 南向 9100，端口见配置）
AIDP_CONFIG=./server/config.example.yaml node server/dist/index.js
```

```bash
# 终端 2：起一个参考客户端（连代理 → 注册本地模型）
AIDP_CLIENT_CONFIG=./client/client.example.yaml node client/dist/index.js
```

```bash
# 终端 3：调一个 OpenAI 兼容接口
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-ops-demo-1111" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen-7b-chat","messages":[{"role":"user","content":"你好"}]}'
```

> 本地模型机器不必与代理同机；客户端进程常驻对应模型节点即可。

## 配置

| 配置 | 说明 | 参考 |
|------|------|------|
| `server/config.example.yaml` | 服务端：端口、API Key、客户端 Token 表、转发策略 | [doc/06-security-and-config.md](doc/06-security-and-config.md) |
| `client/client.example.yaml` | 客户端：服务端地址、身份、本地模型注册表 | 同上 §3 |

敏感字段（apiKeys / token / 本地模型 apiKey）支持 `${ENV_VAR}` 注入，避免明文入库。

## 常用命令

```bash
pnpm install          # 一次性安装全部 workspace 依赖
pnpm -r build         # 构建 shared / server / client
pnpm test             # 全量单测（shared 帧编解码 · server 注册/轮询 · client 转发）
pnpm lint             # oxlint 静态检查
pnpm dev              # 并行 dev（tsx watch）
```

> 注意：`pnpm test` 遍历全 workspace，`pnpm --filter @aidp/shared test` 等可单独跑某包。

## 故障排查 FAQ

### 1. 连不上 9100（TCP）

- 服务端是否真的在监听听端口：`lsof -iTCP:9100 -sTCP:LISTEN`。
- 客户端 `server.host/port` 是否指向服务端可被客户端访问的地址（内网 IP 而非 127.0.0.1，除非同机）。
- 防火墙是否放行了客户端→代理网段。

### 2. 模型注册了但 `/v1/models` 不出现 / 报「model not found」

- 确认客户端日志出现 `models.registered` 且 `accepted` 含该模型名。
- 服务端 `config.yaml` 的 `clients[].clientId` 与 `client.yaml` 的 `identity.clientId` 必须一致，token 必须一致。
- 模型名不能在客户端注册表里含空格。

### 3. 流式请求卡住 / 首 token 迟迟不来

- 本地模型/转发器是否支持 `stream=true`（本地接口需 OpenAI 兼容 SSE）。
- 中间层代理/反向代理是否缓冲了 SSE（确保 `X-Accel-Buffering: no` / 禁用 buffering）。
- 本地模型是否真的在产流（用 curl 直连本地接口看是否有 `data:`）。

## 架构文档

| 文档 | 内容 |
|------|------|
| [01-overview.md](doc/01-overview.md) | 总览与决策基线 |
| [02-architecture.md](doc/02-architecture.md) | 组件、时序、容错、错误码 |
| [03-tcp-protocol.md](doc/03-tcp-protocol.md) | TCP 帧格式、消息 schema、握手心跳 |
| [04-mcp-interface.md](doc/04-mcp-interface.md) | MCP tool 定义 |
| [05-openai-compatible-api.md](doc/05-openai-compatible-api.md) | OpenAI REST API 规范 |
| [06-security-and-config.md](doc/06-security-and-config.md) | 鉴权与配置 |
| [07-deployment.md](doc/07-deployment.md) | 部署、日志规范、v2 路线 |
| [08-implementation-plan.md](doc/08-implementation-plan.md) | 编码计划与 DoD |