# 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](../../../docs/technical/M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md)
2. [../../../docs/technical/M4_MODULE_AI_SPACETIMEDB_BASELINE_2026-04-21.md](../../../docs/technical/M4_MODULE_AI_SPACETIMEDB_BASELINE_2026-04-21.md)
3. [../../../docs/technical/M4_MODULE_AI_AXUM_FACADE_DESIGN_2026-04-22.md](../../../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](../../../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](../../../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。