后端重写提交

server-rs/crates/module-ai/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "module-ai"
+edition.workspace = true
+version.workspace = true
+license.workspace = true
+
+[features]
+default = []
+spacetime-types = ["dep:spacetimedb"]
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+shared-kernel = { path = "../shared-kernel" }
+spacetimedb = { workspace = true, optional = true }

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

@@ -1,29 +1,67 @@
-# module-ai 独立模块 package 占位说明
+# module-ai 模块说明
 
-日期：`2026-04-20`
+日期：`2026-04-21`
 
 ## 1. package 职责
 
-`module-ai` 是 AI 编排模块 package，后续负责：
+`module-ai` 是 AI 编排模块 crate，当前已经落地首版领域基座，负责：
 
-1. 剧情、聊天、自定义世界、运行时物品等生成型流程的模块级编排
-2. prompt 组织、阶段状态、结果引用与模块间协同
-3. 与 `apps/api-server` 的流式输出与兼容接口对接
-4. 与 `apps/spacetime-module` 的任务状态、结果引用聚合对接
+1. 统一 AI 任务类型、任务状态、阶段状态与任务快照
+2. 统一流式文本片段、阶段输出、结果引用与最终结果聚合
+3. 为 `api-server` 与后续 `platform-llm` 接线提供稳定的模块领域服务接口
+4. 为 `spacetime-module` 映射 `ai_task / ai_task_stage / ai_text_chunk / ai_result_reference` 提供稳定类型基础
 
 ## 2. 当前阶段说明
 
-当前提交仅完成目录占位，不提前进入模型调用、流式编排与结果回写实现。
+当前提交已完成：
 
-后续与本 package 直接相关的任务包括：
+1. `module-ai` 的 `Cargo.toml`
+2. 首版核心类型：
+   - `AiTaskKind`
+   - `AiTaskStatus`
+   - `AiTaskStageKind`
+   - `AiTaskSnapshot`
+   - `AiTextChunkSnapshot`
+   - `AiResultReferenceSnapshot`
+3. 默认阶段蓝图与 ID 前缀
+4. `InMemoryAiTaskStore`
+5. `AiTaskService`
+6. 面向 `SpacetimeDB` 的输入类型与 ID helper：
+   - `AiTaskStartInput`
+   - `AiTaskStageStartInput`
+   - `AiTextChunkAppendInput`
+   - `AiResultReferenceInput`
+   - `AiTaskFinishInput`
+   - `AiTaskCancelInput`
+   - `AiTaskFailureInput`
+7. 基础单元测试
 
-1. 设计多模型编排与任务状态抽象
-2. 对齐剧情、聊天、自定义世界等生成链路
-3. 对齐流式输出、阶段事件与兼容响应结构
-4. 接入模块级结果回写与任务引用绑定
+首版详细设计见：
 
-## 3. 边界约束
+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)
 
-1. `module-ai` 负责生成型流程的模块级编排，不把供应商 SDK 直接散落到各业务模块里。
-2. 实际模型接入通过 `packages/platform-llm` 完成，状态与结果引用最终回写到 `apps/spacetime-module` 聚合的状态模型中。
-3. 前端兼容 REST 与 SSE 由 `apps/api-server` 暴露，但 AI 编排过程不能再次退回单个大 orchestrator 的黑盒写法。
+## 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。