后端重写提交

server-rs/crates/platform-llm/README.md

@@ -1,28 +1,48 @@
-# platform-llm 平台适配 package 占位说明
+# platform-llm 平台适配 crate
 
-日期：`2026-04-20`
+日期：`2026-04-21`
 
-## 1. package 职责
+## 1. crate 职责
 
-`platform-llm` 是大模型平台适配 package，后续负责：
+`platform-llm` 是 Rust 工作区里的大模型平台适配 crate，当前首版已经落地以下能力：
 
-1. DashScope、Ark 与其他模型供应商适配
-2. 统一模型调用、流式输出、重试、超时与日志策略
-3. 供 `module-ai`、`module-story`、`module-npc`、`module-custom-world` 等模块复用的模型基础设施能力
+1. 统一 Ark / DashScope / 其他 OpenAI 兼容网关的文本模型配置结构
+2. 统一 `/chat/completions` 文本请求、非流式响应与 SSE 流式增量解析
+3. 统一超时、连接失败、上游错误、空响应与重试策略
+4. 为后续 `module-ai`、`module-story`、`module-npc`、`module-custom-world` 提供可直接复用的基础 client
 
-## 2. 当前阶段说明
+## 2. 当前首版边界
 
-当前提交仅完成目录占位，不提前进入具体模型 SDK、流式调用与供应商切换实现。
+当前实现只覆盖“文本 chat completion”主链，不提前混入媒体生成和业务编排：
 
-后续与本 package 直接相关的任务包括：
+1. 支持 OpenAI 兼容格式的 JSON 请求与 SSE 增量响应
+2. 支持按 provider 打标签，但不把业务 prompt、SSE 转发和模块状态写回放进本 crate
+3. `DashScope` 当前只通过“调用方显式提供兼容文本网关 base url”的方式接入，不复用图像 API
+4. 角色动画、图片、视频、资产轮询仍留在后续 `platform-llm` / `platform-oss` / 业务模块任务里另行实现
 
-1. 落地统一模型请求与响应适配
-2. 落地流式文本输出与阶段事件适配
-3. 落地重试、超时、错误与日志策略
-4. 设计多供应商切换与能力分层
+## 3. 核心导出
 
-## 3. 边界约束
+首版对外导出以下公共类型：
 
-1. `platform-llm` 只承接模型平台适配，不承接业务模块的状态真相与业务规则。
-2. 生成型状态与结果引用最终由业务模块和 `apps/spacetime-module` 管理，前端接口由 `apps/api-server` 暴露。
-3. 不允许把供应商 SDK、流式细节和重试策略重新散落到多个业务模块里各自实现。
+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`，不能复制一份私有实现。