Genarrative/docs/technical/M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md

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
2. NODE_BACKEND_MODULE_AND_API_INDEX.md
3. EXPRESS_BACKEND_TASK4_AI_ORCHESTRATION_STATUS_2026-04-08.md
4. server-node/src/modules/ai/storyOrchestrator.ts
5. server-node/src/modules/ai/chatOrchestrator.ts
6. server-node/src/modules/ai/customWorldOrchestrator.ts

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. 至少有任务创建、流式片段聚合、阶段完成、结果引用绑定、任务失败/取消等测试。