# `api-server` 接入 `platform-llm` 最小代理设计（2026-04-21）

## 1. 目标

在 `platform-llm` 已落成真实 Rust crate 后，`api-server` 需要尽快拥有一条可正式消费的平台接线面，避免平台层只停留在“可编译但未接入”状态。

本次目标只做最小闭环：

1. 在 `api-server` 配置层补齐 LLM 文本网关环境变量
2. 在 `AppState` 注入 `platform-llm::LlmClient`
3. 提供 `/api/llm/chat/completions` 非流式兼容代理
4. 保持与旧 Node 路由的鉴权位置和基本请求形态一致

## 2. 本次范围

### 2.1 本次实现

1. `AppConfig` 新增 LLM provider / base url / api key / model / timeout / retry 配置
2. `AppState` 初始化 `LlmClient`
3. 新增 `shared-contracts::llm`
4. 新增 `api-server/src/llm.rs`
5. 路由挂载到 `/api/llm/chat/completions`

### 2.2 本次不实现

1. 不实现 SSE 流式透传
2. 不实现通用原样 body 转发
3. 不实现媒体模型路由
4. 不把 `module-ai` 编排接进来

## 3. 兼容口径

保持与旧 Node `POST /api/llm/chat/completions` 一致的基本语义：

1. 需要登录态
2. 接收 `model? + stream + messages[]`
3. 当前 `stream=true` 明确返回 `501`，避免伪装支持
4. 非流式返回统一后的文本结果，而不是原样上游 JSON

## 4. 返回结构

Rust 首版返回：

1. `id`
2. `model`
3. `content`
4. `finishReason`

原因：

1. 当前 Rust 平台层已经把上游 `choices[0].message.content` 归一完成
2. `api-server` 首版先保持稳定、可消费的文本结果接口
3. 真正需要 OpenAI 完全兼容响应体时，再单独补“原样代理模式”

## 5. 验收

1. `api-server` 能在配置合法时成功构建 `AppState`
2. `/api/llm/chat/completions` 能通过测试打到 mock 上游
3. `stream=true` 返回明确错误
4. crate 级 `check/test` 通过

## 6. 环境变量与默认值

`api-server` 首版按以下优先级解析 LLM 配置，保证兼容仓库现有 `.env` 口径：

1. provider：`GENARRATIVE_LLM_PROVIDER` -> `LLM_PROVIDER`
2. base url：`GENARRATIVE_LLM_BASE_URL` -> `LLM_BASE_URL`
3. api key：`GENARRATIVE_LLM_API_KEY` -> `LLM_API_KEY` -> `ARK_API_KEY`
4. model：`GENARRATIVE_LLM_MODEL` -> `LLM_MODEL` -> `VITE_LLM_MODEL`
5. timeout：`GENARRATIVE_LLM_REQUEST_TIMEOUT_MS` -> `LLM_REQUEST_TIMEOUT_MS`
6. max retries：`GENARRATIVE_LLM_MAX_RETRIES` -> `LLM_MAX_RETRIES`
7. retry backoff：`GENARRATIVE_LLM_RETRY_BACKOFF_MS` -> `LLM_RETRY_BACKOFF_MS`

默认值统一对齐 `platform-llm`：

1. provider：`ark`
2. base url：`https://ark.cn-beijing.volces.com/api/v3`
3. model：`doubao-1-5-pro-32k-character-250715`
4. request timeout：`30000`
5. max retries：`1`
6. retry backoff：`500`

补充约束：

1. 如果 `api key` 未配置，`api-server` 允许继续启动，但 `/api/llm/chat/completions` 返回 `503`
2. 如果 provider 字符串非法，回退到默认 `ark`，避免因为环境变量拼写问题阻断开发态服务

## 7. 错误映射

`platform-llm` 到 HTTP 的错误映射固定如下：

1. `InvalidRequest` -> `400 BAD_REQUEST`
2. `InvalidConfig` -> `503 SERVICE_UNAVAILABLE`
3. `Timeout` / `Connectivity` / `Transport` / `Deserialize` / `EmptyResponse` / `StreamUnavailable` -> `502 BAD_GATEWAY`
4. `Upstream(status=429)` -> `429 TOO_MANY_REQUESTS`
5. 其他 `Upstream` -> `502 BAD_GATEWAY`
6. `stream=true` 首版直接返回 `501 NOT_IMPLEMENTED`