Genarrative/server-rs/crates/module-custom-world/README.md

module-custom-world 独立模块 package 说明

日期：2026-04-21

1. package 职责

module-custom-world 是自定义世界与 agent 模块 package，后续负责：

1. custom_world_profile、custom_world_session 等世界状态模型
2. custom_world_agent_session、消息、操作、草稿卡等 agent 状态模型
3. 传统问答流、library、gallery、agent 会话的模块级编排
4. 与 apps/api-server 的 custom world 兼容接口与 SSE 对接
5. 与 apps/spacetime-module 的 custom world 表、reducer、view 聚合对接

2. 当前阶段说明

当前阶段已经不再是单纯目录占位，而是先把 M5 首批 custom world / agent 类型契约与字段校验固定下来，避免 spacetime-module 在缺少领域边界的情况下直接堆表。

当前已落地：

1. 真实 Cargo.toml crate scaffold
2. CustomWorldPublicationStatus、CustomWorldThemeMode、CustomWorldGenerationMode
3. CustomWorldSessionStatus、RpgAgentStage
4. RpgAgentMessageRole、RpgAgentMessageKind
5. RpgAgentOperationType、RpgAgentOperationStatus
6. RpgAgentDraftCardKind、RpgAgentDraftCardStatus
7. CustomWorldRoleAssetStatus
8. 首批表字段校验函数与最小单测
9. published profile compile 输入输出 contract
10. publish_world 串联输入输出 contract

当前 crate 仍然只承接：

1. 共享枚举与类型口径
2. 字段校验与字符串归一化
3. published profile compile 的最小编译摘要 contract
4. 后续 spacetime-module 聚合表时需要复用的领域边界

当前阶段明确不提前进入：

1. 旧问答流 reducer 编排
2. RPG 创作 Agent 编排
3. publish gate blocker 规则迁移
4. 资产绑定与图片生成副作用

当前设计依据：

1. ../../../docs/technical/SPACETIMEDB_CUSTOM_WORLD_AGENT_STAGE1_TABLE_DESIGN_2026-04-21.md
2. ../../../backend-rewrite-tasklist/04_M5_CUSTOM_WORLD_AND_AGENT.md
3. ../../../docs/technical/SPACETIMEDB_CUSTOM_WORLD_PUBLISHED_PROFILE_COMPILE_STAGE3_DESIGN_2026-04-21.md
4. ../../../docs/technical/SPACETIMEDB_CUSTOM_WORLD_PUBLISH_WORLD_STAGE4_DESIGN_2026-04-21.md

后续与本 package 直接相关的任务包括：

1. 设计 custom_world_profile、custom_world_session
2. 设计 custom_world_agent_session、消息、操作、卡片相关表
3. 对齐 traditional custom world、library、gallery、agent 兼容链路
4. 接入世界编译、场景图、封面图与角色资产的模块级编排

3. 边界约束

1. module-custom-world 负责世界状态真相、agent 状态与模块级编排，不把整个会话重新塞回单大 JSON 体。
2. 外部 LLM、图片生成、OSS 写入等副作用通过平台适配和应用层完成，状态最终回写到 spacetime-module 聚合的状态模型中。
3. 前端兼容 REST 与 SSE 由 api-server 暴露，但自定义世界主链状态不能再次分散到本地 session store 或前端临时状态中。
4. custom_world_asset_link 本轮不冻结，等待 asset_object / asset_entity_binding / M6 assets 的槽位规则稳定后再接。