Genarrative/server-rs/crates/platform-llm

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. 设计文档

当前文档入口

当前长期工程口径已融合到：

1. ../../../docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
2. ../../../docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
3. ../../../docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

旧阶段设计文档不再作为实现依据。

5. 边界约束

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