This commit is contained in:
230
docs/technical/M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md
Normal file
230
docs/technical/M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# `module-ai` 首版基座设计
|
||||
|
||||
日期：`2026-04-21`
|
||||
|
||||
## 1. 文档目标
|
||||
|
||||
本文只冻结一件事：
|
||||
|
||||
**为 `server-rs/crates/module-ai` 建立一套可以直接编码落地的首版领域模型与最小服务边界。**
|
||||
|
||||
本轮不做以下内容：
|
||||
|
||||
1. 不直接接入真实供应商 SDK。
|
||||
2. 不在 `SpacetimeDB` 里提前写完整 `ai_task` 表。
|
||||
3. 不提前改造 `api-server` 的 story/chat/custom world 路由。
|
||||
|
||||
本轮只解决两个问题：
|
||||
|
||||
1. `module-ai` 不能再停留在“目录占位 + README 口号”状态。
|
||||
2. 后续 `api-server`、`platform-llm`、`spacetime-module` 接线时，需要先有稳定的任务、阶段、流式片段、结果引用领域模型可复用。
|
||||
|
||||
## 2. 依据
|
||||
|
||||
本文以以下现有文档和代码为准：
|
||||
|
||||
1. [SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](./SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)
|
||||
2. [CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md](./CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md)
|
||||
3. 历史 Node AI 编排代码仅作为迁移背景，不再作为当前实现依据。
|
||||
|
||||
## 3. 现状问题
|
||||
|
||||
当前 `server-rs/crates/module-ai` 只有 README，占位描述虽然说明了“AI 编排模块”的方向，但还缺失编码级约束：
|
||||
|
||||
1. 没有任务主键、阶段主键、结果引用 ID 的统一前缀。
|
||||
2. 没有 story/chat/custom world/quest/runtime-item 六类任务的共用枚举。
|
||||
3. 没有“排队中/运行中/已完成/失败/已取消”的状态模型。
|
||||
4. 没有“流式片段如何暂存与聚合”的领域对象。
|
||||
5. 没有“结果引用”与“最终文本/结构化结果”的最小抽象。
|
||||
6. 没有可供 `api-server` 直接依赖的最小内存服务。
|
||||
|
||||
如果继续在没有这层基座的前提下直接接 `platform-llm` 或 `api-server`，后续很容易再次把：
|
||||
|
||||
1. 阶段枚举散落在 handler 里，
|
||||
2. 流式文本拼接散落在路由里，
|
||||
3. 结果引用结构散落在 story/custom-world/quest 各模块里。
|
||||
|
||||
## 4. 首版职责冻结
|
||||
|
||||
`module-ai` 首版只负责以下职责：
|
||||
|
||||
1. 定义统一 AI 任务类型、任务状态、阶段状态、任务快照。
|
||||
2. 定义统一流式片段、阶段输出、结果引用、最终结果快照。
|
||||
3. 提供最小编排服务，支持：
|
||||
- 创建任务
|
||||
- 启动任务
|
||||
- 记录阶段开始/完成
|
||||
- 追加流式文本片段
|
||||
- 绑定结果引用
|
||||
- 成功完成 / 失败 / 取消
|
||||
4. 提供一套内存态 store，作为 `api-server` 首轮联调和测试 fallback。
|
||||
|
||||
`module-ai` 首版明确不负责：
|
||||
|
||||
1. 真实 HTTP 请求、重试、超时和供应商切换。
|
||||
2. SSE 协议写回。
|
||||
3. 数据库存储与表结构。
|
||||
4. 业务模块自己的 prompt 组装细节。
|
||||
|
||||
## 5. 任务类型范围
|
||||
|
||||
首版统一冻结以下任务类型：
|
||||
|
||||
1. `StoryGeneration`
|
||||
2. `CharacterChat`
|
||||
3. `NpcChat`
|
||||
4. `CustomWorldGeneration`
|
||||
5. `QuestIntent`
|
||||
6. `RuntimeItemIntent`
|
||||
|
||||
说明：
|
||||
|
||||
1. 这 6 类直接来自当前 Node 后端已经存在的正式运行时 AI 主链。
|
||||
2. 不提前引入媒体类资产生成任务，因为资产生成后续归 `module-assets + platform-oss` 主导。
|
||||
3. 如果后续要增加 `NarrativeRepair`、`ProfileRepair` 这类内部子任务，应作为新枚举值追加，不复用现有值的语义。
|
||||
|
||||
## 6. 阶段模型
|
||||
|
||||
首版阶段固定支持以下通用阶段语义：
|
||||
|
||||
1. `PreparePrompt`
|
||||
2. `RequestModel`
|
||||
3. `RepairResponse`
|
||||
4. `NormalizeResult`
|
||||
5. `PersistResult`
|
||||
|
||||
说明：
|
||||
|
||||
1. 不是每种任务都必须走满 5 个阶段。
|
||||
2. 任务创建时应携带自己的阶段蓝图，按需要裁剪。
|
||||
3. 阶段蓝图是显示给上层 orchestration 的稳定数据，不把“阶段名字符串”重新散落到 handler。
|
||||
|
||||
首版建议默认蓝图：
|
||||
|
||||
| 任务类型 | 默认阶段 |
|
||||
| --- | --- |
|
||||
| `StoryGeneration` | `PreparePrompt` -> `RequestModel` -> `RepairResponse` -> `NormalizeResult` |
|
||||
| `CharacterChat` | `PreparePrompt` -> `RequestModel` -> `NormalizeResult` |
|
||||
| `NpcChat` | `PreparePrompt` -> `RequestModel` -> `NormalizeResult` |
|
||||
| `CustomWorldGeneration` | `PreparePrompt` -> `RequestModel` -> `RepairResponse` -> `NormalizeResult` -> `PersistResult` |
|
||||
| `QuestIntent` | `PreparePrompt` -> `RequestModel` -> `NormalizeResult` |
|
||||
| `RuntimeItemIntent` | `PreparePrompt` -> `RequestModel` -> `NormalizeResult` |
|
||||
|
||||
## 7. 结果模型
|
||||
|
||||
首版结果拆成三层：
|
||||
|
||||
### 7.1 流式片段
|
||||
|
||||
用于记录模型增量输出：
|
||||
|
||||
1. `chunk_id`
|
||||
2. `task_id`
|
||||
3. `stage_kind`
|
||||
4. `sequence`
|
||||
5. `delta_text`
|
||||
6. `created_at_micros`
|
||||
|
||||
这层只负责“增量片段”，不直接宣称是最终结果。
|
||||
|
||||
### 7.2 阶段输出
|
||||
|
||||
用于记录阶段收口后的聚合内容：
|
||||
|
||||
1. `stage_kind`
|
||||
2. `text_output`
|
||||
3. `structured_payload_json`
|
||||
4. `warning_messages`
|
||||
|
||||
### 7.3 结果引用
|
||||
|
||||
用于让 AI 编排结果和其他模块的记录形成稳定绑定：
|
||||
|
||||
1. `result_ref_id`
|
||||
2. `task_id`
|
||||
3. `reference_kind`
|
||||
4. `reference_id`
|
||||
5. `label`
|
||||
|
||||
首版 `reference_kind` 冻结为：
|
||||
|
||||
1. `StorySession`
|
||||
2. `StoryEvent`
|
||||
3. `CustomWorldProfile`
|
||||
4. `QuestRecord`
|
||||
5. `RuntimeItemRecord`
|
||||
6. `AssetObject`
|
||||
|
||||
## 8. 服务边界
|
||||
|
||||
首版 `AiTaskService` 只暴露纯领域操作，不直接暴露供应商能力：
|
||||
|
||||
1. `create_task`
|
||||
2. `start_task`
|
||||
3. `start_stage`
|
||||
4. `append_text_chunk`
|
||||
5. `complete_stage`
|
||||
6. `attach_result_reference`
|
||||
7. `complete_task`
|
||||
8. `fail_task`
|
||||
9. `cancel_task`
|
||||
10. `get_task`
|
||||
|
||||
这层返回的都是领域快照，不返回 HTTP DTO。
|
||||
|
||||
## 9. 与其他 crate 的边界
|
||||
|
||||
### 9.1 与 `platform-llm`
|
||||
|
||||
`platform-llm` 负责：
|
||||
|
||||
1. 真实模型请求
|
||||
2. 流式回调
|
||||
3. 超时 / 重试 / 供应商错误
|
||||
|
||||
`module-ai` 负责：
|
||||
|
||||
1. 把这些外部回调映射为任务快照与阶段快照
|
||||
2. 把供应商响应组织成稳定的模块领域状态
|
||||
|
||||
### 9.2 与 `api-server`
|
||||
|
||||
`api-server` 负责：
|
||||
|
||||
1. HTTP 入参校验
|
||||
2. SSE 输出
|
||||
3. Bearer/Cookie 鉴权
|
||||
4. response envelope
|
||||
|
||||
`module-ai` 不负责 HTTP。
|
||||
|
||||
### 9.3 与 `spacetime-module`
|
||||
|
||||
后续 `spacetime-module` 负责：
|
||||
|
||||
1. 任务真相表
|
||||
2. 阶段表 / 事件表 / 结果引用表
|
||||
3. reducer / procedure
|
||||
|
||||
本轮 `module-ai` 只提供后续可映射到 SpacetimeDB 的稳定领域结构。
|
||||
|
||||
## 10. 首版编码要求
|
||||
|
||||
首版 crate 必须满足：
|
||||
|
||||
1. 提供 `Cargo.toml`
|
||||
2. 提供 `src/lib.rs`
|
||||
3. 默认不依赖 `platform-llm`
|
||||
4. 默认不依赖 `SpacetimeDB`
|
||||
5. 可选提供 `spacetime-types` feature，便于后续映射表结构
|
||||
6. 提供完整中文注释与基础测试
|
||||
|
||||
## 11. 本轮验收口径
|
||||
|
||||
本轮完成后，以下条件同时满足才算 `module-ai` 首版落地：
|
||||
|
||||
1. `server-rs/Cargo.toml` 已把 `module-ai` 纳入 workspace。
|
||||
2. `module-ai` 不再只有 README，而是有真实可编译源码。
|
||||
3. 任务/阶段/结果引用/流式片段领域模型已存在。
|
||||
4. 有最小内存服务可供后续 `api-server` 直接复用。
|
||||
5. 至少有任务创建、流式片段聚合、阶段完成、结果引用绑定、任务失败/取消等测试。
|
||||
Reference in New Issue
Block a user