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