# platform-llm 平台适配 crate

日期：`2026-04-21`

## 1. crate 职责

`platform-llm` 是 Rust 工作区里的大模型平台适配 crate，当前首版已经落地以下能力：

1. 统一 Ark / DashScope / 其他 OpenAI 兼容网关的文本模型配置结构
2. 统一 `/chat/completions` 文本请求、非流式响应与 SSE 流式增量解析
3. 统一超时、连接失败、上游错误、空响应与重试策略
4. 为后续 `module-ai`、`module-story`、`module-npc`、`module-custom-world` 提供可直接复用的基础 client

## 2. 当前首版边界

当前实现只覆盖“文本 chat completion”主链，不提前混入媒体生成和业务编排：

1. 支持 OpenAI 兼容格式的 JSON 请求与 SSE 增量响应
2. 支持按 provider 打标签，但不把业务 prompt、SSE 转发和模块状态写回本 crate
3. `DashScope` 当前只通过“调用方显式提供兼容文本网关 base url”的方式接入，不复用图像 API
4. 角色动画、图片、视频、资产轮询仍留在后续 `platform-llm` / `platform-oss` / 业务模块任务里另行实现

## 3. 核心导出

首版对外导出以下公共类型：

1. `LlmProvider`
2. `LlmConfig`
3. `LlmMessageRole`
4. `LlmMessage`
5. `LlmTextRequest`
6. `LlmStreamDelta`
7. `LlmTextResponse`
8. `LlmTokenUsage`
9. `LlmClient`
10. `LlmError`

## 4. 设计文档

详细约束与接口说明见：

- [../../../docs/technical/PLATFORM_LLM_TEXT_GATEWAY_DESIGN_2026-04-21.md](../../../docs/technical/PLATFORM_LLM_TEXT_GATEWAY_DESIGN_2026-04-21.md)

## 5. 边界约束

1. `platform-llm` 只承接模型平台适配，不承接业务模块状态真相与业务规则。
2. 业务模块只能依赖这里的统一 client / DTO / 错误模型，不能再把上游请求细节散落回各 crate。
3. `api-server` 后续如果需要做 REST/SSE façade，只允许在协议层调用 `platform-llm`，不能复制一份私有实现。