world_snapshot/README.md

world_snapshot 模块

世界状态快照模块（W-03）：聚合世界（world）、场景（scene）、实体（entity）当前状态生成 快照，支持快照查询与恢复，恢复时联动 world 表状态（经 world 模块 set_world_mode 契约）。

功能

• 世界快照表 world_snapshot 的 CRUD（create/get/list/update/delete）
• create_snapshot：聚合 world/scene/entity 当前状态写入 snapshot_json
• restore_snapshot：读取并校验快照 JSON，标记已恢复，联动 world 状态
• 下拉接口：世界列表、快照类型、快照状态

数据表

• world_snapshot（models/world_snapshot.json 四段式）
• 编码字典：snapshot_type（full/incremental）、snapshot_status（active/restored/invalid）

目录结构

world_snapshot/
├── world_snapshot/        # Python 包（init.py 实现 + __init__.py 导出）
├── wwwroot/               # index.ui / menu.ui / api/*.dspy
├── models/                # world_snapshot.json 表定义
├── json/                  # world_snapshot.json CRUD 定义
├── init/                  # data.json 编码字典种子
├── scripts/               # load_path.py RBAC 注册
├── skill/SKILL.md         # 模块技能文档
├── pyproject.toml
├── build.sh               # 四步安装（xls2ddl → ddl → crud ui → symlink）
└── README.md

集成

• 通过 load_world_snapshot() 挂载到宿主应用（from world_snapshot.init import load_world_snapshot）
• 库名经 ServerEnv().get_module_dbname('world_snapshot') 获取，禁止硬编码
• 构建：bash build.sh（安装 xls2ddl、生成 DDL、生成 CRUD UI、链接 wwwroot）