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

M4 module-ai SpacetimeDB 基座记录（2026-04-21）

更新时间：2026-04-21

0. 文档目标

本文件只记录一件事：

把 module-ai 从“只有领域模型和内存态服务”推进到“SpacetimeDB 侧已有最小 AI 任务真相表与 procedure 骨架”的真实落地结果。

本轮只做最小可编译基座，不扩到真实模型请求、SSE 输出或前端订阅联调。

---

1. 本轮落地范围

本轮只落实下面 5 件事：

1. 在 server-rs/crates/module-ai/ 中补齐面向 SpacetimeDB 接线的输入类型。
2. 在 server-rs/crates/spacetime-module/ 中新增 ai_task / ai_task_stage / ai_text_chunk / ai_result_reference 四张 private 表。
3. 在 spacetime-module 中新增 AI 任务的最小 reducer / procedure。
4. 把 module-ai 的领域快照与 SpacetimeDB 行结构之间的转换 helper 固定下来。
5. 补充 crate README 与技术索引，明确当前 AI 真相源边界。

---

2. 新增的真实工程落点

2.1 module-ai

1. server-rs/crates/module-ai/src/lib.rs
   • 补充 AiTaskStartInput
   • 补充 AiTaskStageStartInput
   • 补充 AiTextChunkAppendInput
   • 补充 AiResultReferenceInput
   • 补充 AiTaskFinishInput
   • 补充 AiTaskCancelInput
   • 补充 AiTaskFailureInput
   • 补充 AI_TASK_STAGE_ID_PREFIX
   • 补充 AiTaskStageKind::as_str()
   • 补充 generate_ai_task_stage_id()

2.2 spacetime-module

1. server-rs/crates/spacetime-module/src/lib.rs
   • 新增 ai_task
   • 新增 ai_task_stage
   • 新增 ai_text_chunk
   • 新增 ai_result_reference
   • 新增 create_ai_task
   • 新增 create_ai_task_and_return
   • 新增 start_ai_task
   • 新增 start_ai_task_stage
   • 新增 append_ai_text_chunk_and_return
   • 新增 complete_ai_stage_and_return
   • 新增 attach_ai_result_reference_and_return
   • 新增 complete_ai_task_and_return
   • 新增 fail_ai_task_and_return
   • 新增 cancel_ai_task_and_return

---

3. 当前冻结的数据口径

3.1 ai_task

当前首版字段冻结为：

1. task_id
2. task_kind
3. owner_user_id
4. request_label
5. source_module
6. source_entity_id
7. request_payload_json
8. status
9. failure_message
10. latest_text_output
11. latest_structured_payload_json
12. version
13. created_at
14. started_at
15. completed_at
16. updated_at

当前策略：

1. ai_task 只保留任务级聚合字段，不在单行内嵌套 Vec<stage>。
2. 阶段、增量文本、结果引用全部拆到独立表，避免后续更新整行大对象。
3. version 继续沿用 module-ai 的任务快照版本语义。

3.2 ai_task_stage

当前首版字段冻结为：

1. task_stage_id
2. task_id
3. stage_kind
4. label
5. detail
6. order
7. status
8. text_output
9. structured_payload_json
10. warning_messages
11. started_at
12. completed_at

当前策略：

1. 一条 stage 一行。
2. task_stage_id 使用 generate_ai_task_stage_id(task_id, stage_kind)，保持同任务内幂等。
3. 当前不单独存“阶段版本”，统一归任务版本递增。

3.3 ai_text_chunk

当前首版字段冻结为：

1. text_chunk_row_id
2. chunk_id
3. task_id
4. stage_kind
5. sequence
6. delta_text
7. created_at

当前策略：

1. chunk_id 保留领域侧 ID 语义。
2. 表级主键使用 text_chunk_row_id，避免 generate_ai_text_chunk_id(seed, sequence) 在不同任务之间碰撞。
3. 流式文本聚合结果仍写回 ai_task_stage.text_output 和 ai_task.latest_text_output。

3.4 ai_result_reference

当前首版字段冻结为：

1. result_reference_row_id
2. result_ref_id
3. task_id
4. reference_kind
5. reference_id
6. label
7. created_at

当前策略：

1. result_ref_id 保留领域侧 ID 语义。
2. 表级主键使用 result_reference_row_id，避免只按时间种子生成的领域 ID 在并发情况下直接作为主键带来碰撞风险。

---

4. 当前 reducer / procedure 口径

4.1 create_ai_task

当前负责：

1. 校验 AiTaskCreateInput
2. 拒绝重复 task_id
3. 写入 ai_task
4. 按蓝图写入 ai_task_stage

4.2 start_ai_task

当前负责：

1. 校验目标任务存在
2. 把 ai_task.status 从 Pending 推进到 Running
3. 填充 started_at

4.3 start_ai_task_stage

当前负责：

1. 校验目标任务与目标阶段存在
2. 推进任务为 Running
3. 推进对应 stage 为 Running

4.4 append_ai_text_chunk_and_return

当前负责：

1. 校验任务与阶段存在
2. 追加 ai_text_chunk
3. 按 task_id + stage_kind + sequence 聚合文本
4. 回写 ai_task_stage.text_output
5. 回写 ai_task.latest_text_output

4.5 complete_ai_stage_and_return

当前负责：

1. 更新 stage 状态、阶段输出、warning 列表
2. 回写 ai_task.latest_text_output
3. 回写 ai_task.latest_structured_payload_json
4. 递增任务版本

4.6 attach_ai_result_reference_and_return

当前负责：

1. 追加 ai_result_reference
2. 更新任务 updated_at
3. 递增任务版本

4.7 complete_ai_task_and_return

当前负责：

1. 推进任务为 Completed
2. 填充 completed_at

4.8 fail_ai_task_and_return

当前负责：

1. 推进任务为 Failed
2. 写入 failure_message
3. 填充 completed_at

4.9 cancel_ai_task_and_return

当前负责：

1. 推进任务为 Cancelled
2. 填充 completed_at

---

5. 当前刻意未做

本轮明确没有扩到以下范围：

1. 还没有做 AI 任务公开订阅表。
2. 还没有做 api-server 的 AI facade 路由。
3. 还没有做 platform-llm 真实流式回调接线。
4. 还没有做 story / custom-world / quest / runtime-item 对 AI 任务的自动建链。
5. 还没有做清理旧任务、旧 chunk 的 schedule reducer。

也就是说，本轮只是把 AI 任务真相表和最小写入口立起来，不宣称已经完成 AI runtime 主链迁移。

---

6. 当前边界判断

当前仍保持以下职责划分：

1. module-ai
   • 负责领域模型、校验、快照结构与最小内存服务。
2. spacetime-module
   • 负责任务真相表、事务性持久化与 procedure 聚合返回。
3. platform-llm
   • 后续负责真实模型调用、超时、重试、供应商错误。
4. api-server
   • 后续负责 HTTP / SSE / 鉴权与外部 contract。

---

7. 下一步建议

按当前节奏，后续应继续按下面顺序推进：

1. 先把 platform-llm 的文本网关正式接到 append_ai_text_chunk_and_return / complete_ai_stage_and_return。
2. 再给 api-server 增加 AI 任务 facade，把 HTTP/SSE 对外 contract 冻结下来。
3. 再把 story、custom-world、quest、runtime-item 各自的 AI 编排入口切到 module-ai + spacetime-module。
4. 最后再根据订阅需求评估是否补 public projection 表或事件表。