Genarrative/server-rs/crates/platform-llm

platform-llm 平台适配 crate

日期：2026-04-21

1. crate 职责

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

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

2. 当前首版边界

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

1. 对外抽象固定为 LlmRunRequest / LlmRunResponse，不再保留旧 LlmTextRequest / LlmTextResponse 类型。
2. 支持 OpenAiChat 和 OpenAiResponses 两类 API kind 的 JSON 请求与 SSE 增量响应。
3. 支持 Anthropic API kind 的最小文本 Messages 请求、非流式响应与 SSE 文本增量解析；Anthropic URL 默认在 base URL 后拼 /v1/messages，如果 base URL 已以 /v1 结尾则只拼 /messages。
4. 当前 run 抽象只收敛通用文本结果、finish reason、response id 和 usage；上下文管理、后台执行、provider 原生工具等高级能力后续再按 capability 显式扩展，不把 Responses 语义硬编码进业务层。
5. 支持按 provider 打标签，但不把业务 prompt、SSE 转发和模块状态写回本 crate。
6. DashScope 当前只通过“调用方显式提供兼容文本网关 base url”的方式接入，不复用图像 API。
7. 角色动画、图片、视频、资产轮询仍留在后续 platform-llm / platform-oss / 业务模块任务里另行实现。

3. 核心导出

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

1. LlmProvider
2. LlmConfig
3. LlmMessageRole
4. LlmMessage
5. LlmRunRequest
6. LlmApiKind
7. LlmStreamDelta
8. LlmRunResponse
9. LlmTokenUsage
10. LlmClient
11. 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，不能复制一份私有实现。