Genarrative/server-rs/crates/module-ai/README.md

module-ai 模块说明

日期：2026-04-21

1. package 职责

module-ai 是 AI 编排模块 crate，当前已经落地首版领域基座，负责：

1. 统一 AI 任务类型、任务状态、阶段状态与任务快照
2. 统一流式文本片段、阶段输出、结果引用与最终结果聚合
3. 为 api-server 与后续 platform-llm 接线提供稳定的模块领域服务接口
4. 为 spacetime-module 映射 ai_task / ai_task_stage / ai_text_chunk / ai_result_reference 提供稳定类型基础

2. 当前阶段说明

当前提交已完成：

1. module-ai 的 Cargo.toml
2. DDD 分层文件与内部子模块：
   • src/domain.rs
   • src/domain/types.rs
   • src/domain/stages.rs
   • src/domain/ids.rs
   • src/commands.rs
   • src/commands/inputs.rs
   • src/commands/validation.rs
   • src/application.rs
   • src/application/service.rs
   • src/application/store.rs
   • src/application/result.rs
   • src/events.rs
   • src/errors.rs
3. 首版核心类型：
   • AiTaskKind
   • AiTaskStatus
   • AiTaskStageKind
   • AiTaskSnapshot
   • AiTextChunkSnapshot
   • AiResultReferenceSnapshot
4. 默认阶段蓝图与 ID 前缀
5. InMemoryAiTaskStore
6. AiTaskService
7. 面向 SpacetimeDB 的输入类型与 ID helper：
   • AiTaskStartInput
   • AiTaskStageStartInput
   • AiTextChunkAppendInput
   • AiResultReferenceInput
   • AiTaskFinishInput
   • AiTaskCancelInput
   • AiTaskFailureInput
8. src/tests.rs 中的基础单元测试

首版详细设计见：

1. ../../../docs/technical/M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md
2. ../../../docs/technical/M4_MODULE_AI_SPACETIMEDB_BASELINE_2026-04-21.md
3. ../../../docs/technical/M4_MODULE_AI_AXUM_FACADE_DESIGN_2026-04-22.md
4. ../../../docs/technical/SERVER_RS_DDD_WP_AI_TASK_DOMAIN_REFACTOR_2026-04-29.md
5. ../../../docs/technical/SERVER_RS_DDD_WP_AI_INTERNAL_MODULE_SPLIT_2026-04-29.md

3. 当前仍未进入的范围

当前刻意未进入：

1. 真实供应商 SDK 与模型请求
2. SSE 协议输出
3. 任务订阅 projection 与清理调度
4. 业务模块自己的 prompt 组装实现

这些后续分别由：

1. platform-llm
2. api-server
3. spacetime-module + spacetime-client
4. module-story / module-npc / module-custom-world / module-quest / module-runtime-item

继续接入。

4. 边界约束

1. module-ai 只负责生成型流程的模块级编排领域模型与最小服务，不直接承接供应商 HTTP 适配。
2. 真实模型接入通过 platform-llm 完成，任务真相状态最终应下沉到 spacetime-module。
3. api-server 负责 REST / SSE 对外协议，module-ai 不返回 HTTP DTO。