# ApiDispatcher

**Repository Path**: TaBuE/api-dispatcher

## Basic Information

- **Project Name**: ApiDispatcher
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-06
- **Last Updated**: 2026-05-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# API Dispatcher

基于 Java 21 + Spring Boot + MyBatis 的 AI API 转发与多模型编排服务端。

当前仓库已完成的基础能力：

1. Maven Spring Boot 工程骨架。
2. 本地 `local` profile 使用 H2 启动验证，`prod` profile 预留 MySQL 配置。
3. 虚拟线程、共享 HttpClient、统一返回体、统一异常处理、TraceId 过滤器。
4. 模型配置、agent profile、skill、tool、MCP 配置的基础 CRUD 接口。
5. run 创建接口、run 详情接口、SSE 事件回放接口。
6. 基线建表 SQL。
7. Vue 3 管理前端工程。
8. 对外兼容 OpenAI 和 Ollama 的 harness 接入层。

## 技术栈

1. Java 21 语义目标。
2. Spring Boot 3.5。
3. Spring MVC。
4. MyBatis。
5. HikariCP。
6. H2 本地验证。
7. MySQL 生产配置。

## 本地启动

```bash
mvn spring-boot:run
```

默认使用 `local` profile，并自动执行 [db/20260506_000001_baseline.sql](db/20260506_000001_baseline.sql) 初始化 H2 内存库。

健康检查：

```bash
curl http://127.0.0.1:8080/actuator/health
```

## 前端启动

```bash
cd frontend
npm install
npm run dev
```

前端默认使用 Vite 代理把 `/api` 和 `/actuator` 转发到 `http://127.0.0.1:8080`。
如果你需要改成直连后端，可以设置 `VITE_API_BASE_URL`。

## 关键接口

1. `POST /api/models`
2. `GET /api/models`
3. `POST /api/agent-profiles`
4. `POST /api/skills`
5. `POST /api/tools`
6. `POST /api/mcp-servers`
7. `POST /api/runs`
8. `GET /api/runs/{runId}`
9. `GET /api/runs/{runId}/stream`
10. `POST /api/runs/{runId}/tool-results`

## 对外 Harness 接入

OpenAI 兼容接入：

```bash
curl http://127.0.0.1:8080/v1/models

curl http://127.0.0.1:8080/v1/chat/completions \
	-H 'Content-Type: application/json' \
	-d '{
		"model": "assistant-primary",
		"messages": [{"role": "user", "content": "你好"}],
		"stream": false
	}'
```

Ollama 兼容接入：

```bash
curl http://127.0.0.1:8080/api/tags

curl http://127.0.0.1:8080/api/chat \
	-H 'Content-Type: application/json' \
	-d '{
		"model": "assistant-primary",
		"messages": [{"role": "user", "content": "你好"}],
		"stream": false
	}'
```

说明：

1. 对外暴露的模型名使用后台配置里的 `modelRef`。
2. 服务端会把 `modelRef` 映射到真实上游模型 ID，再转发到已配置的 openai-compatible provider。
3. OpenAI 兼容入口基址是 `http://host:port/v1`。
4. Ollama 兼容入口基址是 `http://host:port`，主要接口是 `/api/tags`、`/api/show`、`/api/chat`、`/api/generate`、`/api/version`。
5. `GET /api/version` 现在返回标准 Ollama 语义版本号，便于外部客户端做版本探测。
6. 兼容层额外提供 `GET /api/ps`，返回当前可用模型的运行态列表形状。

## 运行约束

1. 不使用 Flyway。
2. 数据库结构变更统一走项目内 SQL 脚本。
3. IO 转发优先使用虚拟线程和共享 HttpClient。
4. provider 调用优先流式透传到下游 SSE。

## 文档

1. 设计文档：[docs/ai-api-dispatcher-design.md](docs/ai-api-dispatcher-design.md)
2. SQL 执行说明：[docs/database-sql-execution.md](docs/database-sql-execution.md)
3. 部署说明：[docs/deploy.md](docs/deploy.md)
4. opencode 联调说明：[docs/opencode-integration.md](docs/opencode-integration.md)