Genarrative/docs/technical

技术方案

这一组文档偏技术选型、实现路线和外部产品形态拆解。

文档列表

• SPACETIMEDB_TABLE_CATALOG.md：持续维护当前 SpacetimeDB 表目录，按领域说明每张表的作用、字段结构、索引和常用 spacetime sql 查询模板。

• FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md：记录网站启动后首次加载约三分钟的前端根因，收口 RouteImageReadyGate 首屏图片门控和 Vite dev server 无关文件监听范围。

• RPG_WORK_DELETE_SPACETIMEDB_PROCEDURE_EXPORT_FIX_2026-04-25.md：记录 RPG 作品删除时报 No such procedure 的根因，补齐 delete_custom_world_agent_session 在有效 SpacetimeDB 模块入口中的导出，并要求发布后核验 Maincloud schema。

• CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md：冻结当前后端唯一落地口径，明确新功能以 server-rs + Axum + SpacetimeDB 为准，旧 server-node / Express / PostgreSQL 与 Go 方向只允许作为迁移参考。

• RPG_DRAFT_GENERATION_CONTINUE_AND_ETA_FIX_2026-04-25.md：记录世界草稿生成失败/中断后进度不再误到 100%、主按钮改为“继续生成草稿”并复用已保存底稿续跑，以及按阶段耗时模型估算预计等待时间的修复口径。

• RUNTIME_NPC_CHAT_LLM_MIGRATION_2026-04-25.md：冻结运行时 NPC 聊天从 Rust 确定性兜底迁到 platform-llm 的边界，要求旧 Node 聊天提示词原样迁移，覆盖回复、建议、好感变化与限轮收束。

• API_SERVER_DEV_STACK_COLD_BUILD_TIMEOUT_FIX_2026-04-25.md：记录 npm run dev:rust 在 Windows 冷编译/链接阶段误把 api-server /healthz 等待判定为超时并杀掉 cargo run 的根因，以及将 SpacetimeDB 与 api-server 等待窗口拆分的脚本口径。

• API_ERROR_DETAILS_MESSAGE_DISPLAY_FIX_2026-04-25.md：记录统一 API envelope 错误展示优先读取 error.details.message 的修复口径，避免 Big Fish 发布校验等业务错误只显示通用“请求参数不合法”。

• CHARACTER_VISUAL_IP_MODERATION_FALLBACK_FIX_2026-04-25.md：记录角色主形象遇到 DashScope IPInfringementSuspect 时自动改用原创安全 prompt 兜底重试的修复口径，并保留供应商原始错误便于排查。

• CREATION_AGENT_IMMEDIATE_WAITING_DOTS_FIX_2026-04-25.md：记录创作 Agent 用户发送消息后立刻展示三点等待动画的前端展示条件，避免首个 SSE token 到达前聊天区无反馈。

• CREATION_AGENT_DOCUMENT_INPUT_UPLOAD_2026-04-25.md：冻结 Agent 创作页上传文本类文档并解析为输入框内容的前后端边界、接口、支持范围和验收标准。

• CREATION_HUB_LOGOUT_PRIVATE_CACHE_FIX_2026-04-25.md：记录退出登录后创作中心仍显示上一账号作品的前端缓存根因，并冻结退出时立即收回鉴权上下文、清空三类私有作品货架缓存的修复口径。

• CREATION_AGENT_CLIENT_AND_FLOW_CONTROLLER_REUSE_2026-04-25.md：冻结三类作品创作 Agent client 通用工厂与平台轻量流程 controller 的复用边界，明确本轮只收口 HTTP/SSE 骨架和大鱼/拼图会话流程，不合并 RPG 自动保存主链。

• BACKEND_CREATION_AGENT_LLM_TURN_COMMONIZATION_2026-04-25.md：冻结后端创作 Agent LLM turn 公共化边界，收口模型可用性检查、流式 JSON 回复抽取、最终 JSON 解析与中文错误映射，玩法 schema 和写回逻辑继续留在各自模块。

• CREATION_WORK_SHELF_UNIFICATION_2026-04-25.md：冻结创作中心作品货架统一视图模型，先在前端归一 RPG、大鱼、拼图 works 的展示字段、筛选状态和卡片动作语义，不新增后端聚合接口。

• PUZZLE_BIG_FISH_DRAFT_PROGRESS_AND_ASSET_CHAIN_2026-04-25.md：冻结拼图与大鱼吃小鱼点击生成草稿后进入独立进度页，并一次性生成草稿、图片与动作资产的前端编排边界。

• BIG_FISH_DIRECTION_TOUCH_CONTROL_2026-04-24.md：记录大鱼吃小鱼从固定摇杆改为屏幕首触点方向控制，并要求本地直达局在未操作时保持对象运动。

• RUST_WORKSPACE_DEFAULT_BUILD_SCOPE_FIX_2026-04-25.md：记录 server-rs 无参数 cargo build 链接 spacetime-module 失败的根因，并冻结默认只构建原生 api-server、模块产物继续走 spacetime build 的命令边界。

• BIG_FISH_DIRECT_ROUTE_PLAYGROUND_2026-04-24.md：记录 /big-fish 大鱼吃小鱼玩法直达入口，明确复用现有 BigFishRuntimeShell 和本地占位运行态的调试边界。

• PUZZLE_DIRECT_ROUTE_PLAYGROUND_2026-04-24.md：记录 /puzzle 拼图玩法直达入口，明确复用现有 PuzzleRuntimeShell 和本地占位图运行态的调试边界。

• FRONTEND_INDEPENDENT_PAGE_ROUTES_2026-04-25.md：记录平台入口、RPG 创作、拼图创作和大鱼吃小鱼创作各页面的独立前端路径，以及与 /puzzle、/big-fish 调试直达入口的边界。

• PUZZLE_AGENT_ACTION_RESPONSE_SESSION_2026-04-25.md：记录拼图 Agent actions 回包直接携带最新 session，避免选图后额外拉取完整会话大包的接口收口规则。

• CREATION_AGENT_PUBLISH_GATE_NORMALIZE_WRITEBACK_FIX_2026-04-24.md：记录结果页 profile 归一化回写丢失顶层 worldHook / playerPremise 导致 publish gate 继续误报结构 blocker 的根因，并冻结前端归一化保留发布字段的修复口径。

• CUSTOM_WORLD_RESULT_ENTITY_GENERATION_FIX_2026-04-24.md：记录世界结果页在 Agent 草稿模式下新增场景、新增 NPC 生成成功但结果页字段不可用的根因，并冻结 api-server 生成归一化层补齐 profile 字段的修复口径。

• ADMIN_CONSOLE_SERVICE_DESIGN_2026-04-23.md：冻结 Rust api-server 内后台管理服务首版方案，明确管理员用户名密码登录、管理员 JWT 鉴权、数据库概览、受控 API 调试台与同源管理页面的落地边界。

• SPACETIME_MODULE_LIB_RS_SPLIT_EXECUTION_2026-04-23.md：冻结 server-rs/crates/spacetime-module/src/lib.rs 的模块地图、二级落位点与迁移顺序，要求后续 SpacetimeDB 主工程改动按对应模块落位，不再继续堆回单大文件。

• CUSTOM_WORLD_DRAFT_FOUNDATION_API_SERVER_LLM_MIGRATION_2026-04-23.md：冻结 draft_foundation 从 SpacetimeDB 内部规则编译迁到 api-server + platform-llm 的边界，明确草稿必须由 api-server 真实调 LLM 生成，SpacetimeDB 只负责落库。

• CUSTOM_WORLD_AGENT_LLM_REPLY_RESTORE_2026-04-22.md：恢复 Custom World Agent 聊天必须走大模型推理的 Rust 落地方案，冻结 submit/finalize 两阶段职责、旧 Node 提示词原样搬运、SSE 流式回复与 session 回写边界。

• PUZZLE_AGENT_LLM_REPLY_INTEGRATION_2026-04-23.md：冻结拼图 Agent 聊天接入真实 LLM 的最小 Rust 落地方案，明确 submit 只写 user message、api-server 承接推理、SSE 流式回放与 finalize 回写 session 真相的边界。

• UNIFIED_CREATION_DRAFT_SESSION_RESTORE_2026-04-23.md：冻结创作中心全草稿恢复 Agent 会话的统一口径，覆盖 RPG、Big Fish、Puzzle 三类草稿的会话索引、结果页分流和 Big Fish works 最小投影边界。

• PUZZLE_DRAFT_SESSION_RESTORE_2026-04-23.md：冻结拼图结果页草稿进入创作中心后的恢复口径，明确 draft 作品投影、sourceSessionId 反查 Agent session、编译时同步落草稿卡与发布复用同一作品记录。

• RUST_LOCAL_DEV_SPACETIMEDB_PUBLISH_GUARD_AND_AGENT_LLM_FAILURE_POLICY_2026-04-23.md：冻结 Rust 本地联调启动前必须 publish/generate 最新 spacetime-module 的守卫，以及 Custom World Agent 在 LLM 失败时禁止写固定 assistant 回复的 finalize 与 HTTP/SSE 错误策略。

• CREATION_AGENT_CHAT_SCROLL_FOLLOW_POLICY_FIX_2026-04-23.md：记录统一创作聊天工作区从“每次更新都强制滚到底”改为“仅在用户仍停留在底部附近时跟随”的滚动策略修复，避免流式回复持续抢走阅读位置。

• CREATION_AGENT_STREAMING_MESSAGE_STABILITY_FIX_2026-04-23.md：记录创作 Agent 聊天流式文本、玩家乐观消息、最终 session 回写和草稿切换的展示稳定性修复，避免乱码、闪消、插队和旧草稿闪烁。

• CREATION_AGENT_SESSION_SYNC_RENDER_LOOP_FIX_2026-04-23.md：记录 RPG 创作 Agent 工作区打开后重复 GET /agent/sessions/:sessionId 的前端渲染环根因，以及通过稳定 enterCreateTab 依赖收紧 session 同步 effect 的修复口径。

• CREATION_AGENT_PUBLISH_GATE_SCHEMA_ALIGNMENT_FIX_2026-04-23.md：记录发布阻断项仍按旧 worldHook / playerPremise / sceneChapters schema 校验的问题，以及将 Rust publish gate 对齐到 anchorContent / creatorIntent / sceneChapterBlueprints 当前主链结构的修复口径。

• CREATION_HUB_CARD_ACTIONS_2026-04-22.md：冻结创作中心作品卡“体验 / 删除”入口的最小落地语义，明确 RPG 已发布作品软删除、卡片直达运行时，以及暂不扩草稿 / 拼图删除契约。

• CREATION_CATEGORY_OPENING_TIMEOUT_GUARD_FIX_2026-04-22.md：记录创作中心点击类别后长时间停留在“正在开启”的根因与修复口径，收口前端创建会话启动超时、中文错误提示以及 Big Fish / 拼图代理上游超时兜底。

• JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md：冻结 Jenkins 构建 / 部署 / 构建并部署 三条流水线的职责、版本号传递、上游触发门禁、本地目录部署脚本与 /home/ubuntu/Genarrative-deploy/ 覆盖策略。

• JENKINS_DEPLOY_ENV_BOM_FIX_2026-04-25.md：记录 Jenkins 部署时 .env.local 首行 UTF-8 BOM 导致 start.sh 加载失败的根因，并冻结发布包构建、部署脚本和启动脚本的环境文件净化规则。

• RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md：冻结 Rust 本地一键联调脚本与 Ubuntu 发布包构建脚本的执行口径，覆盖 npm run dev:rust、npm run build:rust:ubuntu、Vite release、Linux api-server、SpacetimeDB wasm、启动停止脚本、默认 scp 上传和安全清库开关。

• RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md：记录当前 Rust api-server 已挂载的 101 条 Axum 路由，并补充管理后台入口与管理接口索引，按 auth、assets、runtime、custom world、story、generated path 等挂载面归类，用于对照 Node 能力基线与切流 smoke 清单。

• BACKEND_REWRITE_CROSS_CUTTING_GOVERNANCE_2026-04-22.md：冻结后端重写收口阶段的横向治理规则，覆盖 TypeScript contract 到 Rust DTO 映射、SpacetimeDB schema 演进、大对象 / workflow cache 存储边界和文档维护门禁。

• PLATFORM_LLM_TEXT_GATEWAY_DESIGN_2026-04-21.md：platform-llm 文本模型网关首版设计，冻结 OpenAI 兼容 /chat/completions、SSE 增量解析、错误模型与重试边界。

• API_SERVER_PLATFORM_LLM_PROXY_DESIGN_2026-04-21.md：api-server 接入 platform-llm 的最小代理设计，冻结 /api/llm/chat/completions 的配置、状态注入与首版非流式兼容边界。

• PHONE_SMS_LOGIN_STAGE_A_IMPLEMENTATION_2026-04-21.md：冻结手机号验证码登录第一阶段的真实落地边界，明确游客兜底默认关闭、公开请求不污染登录态，以及 smoke 必须覆盖短信登录主链。

• AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md：/api/auth/login-options 首版设计，冻结登录方式列表 contract、配置开关来源与返回顺序。

• AUTH_ME_QUERY_DESIGN_2026-04-21.md：/api/auth/me 首版查询设计，冻结 Bearer JWT 衔接、user + availableLoginMethods 返回 contract，以及用户不存在时的 401 语义。

• AUTH_LOGOUT_ALL_DESIGN_2026-04-21.md：/api/auth/logout-all 全端登出设计，冻结全部 refresh session 吊销、token_version 递增、清 cookie 语义与 Rust 首版接口边界。

• AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md：/api/auth/sessions 会话列表设计，冻结当前设备识别、多端登录字段映射、clientLabel 兼容策略与 Rust 首版接口边界。

• PHONE_AUTH_AXUM_MINIMAL_FLOW_DESIGN_2026-04-21.md：手机号验证码登录最小闭环设计，冻结 mock 验证码规则、send-code / phone/login contract 与 crate 边界。

• PHONE_AUTH_AXUM_RATE_LIMIT_AND_FAILURE_DESIGN_2026-04-21.md：手机号验证码冷却与失败次数限制设计，冻结同手机号同场景发送冷却、错误次数耗尽、429 与 Retry-After contract。

• PHONE_AUTH_AXUM_REAL_SMS_PROVIDER_DESIGN_2026-04-22.md：冻结 Rust api-server + module-auth + platform-auth 接入真实阿里云短信 provider 的 crate 边界、发送与校验职责、配置项和错误语义。

• PHONE_SMS_ALIYUN_RESPONSE_FIELD_MAPPING_FIX_2026-04-23.md：记录 Rust platform-auth 把阿里云 PascalCase 响应字段误判成空值的问题根因，并冻结字段映射修复与回归标准。

• PHONE_SMS_SEND_CODE_OBSERVABILITY_FIX_2026-04-23.md：冻结手机号验证码发送链路的日志补强口径，确保 api-server、module-auth、platform-auth 能直接暴露发送前后与错误分类关键字段。

• PHONE_SMS_DELIVERY_OBSERVABILITY_AND_RECEIPT_DESIGN_2026-04-22.md：冻结短信平台受理成功与最终送达状态的区分方式、追踪字段、送达回执接口和前端提示文案边界。

• PHONE_SMS_REAL_PROVIDER_MANUAL_VERIFICATION_RUNBOOK_2026-04-23.md：冻结验证清单第一项“真实短信验证码链路”的本地启动、前端操作、日志观察点、通过标准与失败排查步骤。

• ASSET_EXTERNAL_GENERATION_MANUAL_VERIFICATION_RUNBOOK_2026-04-23.md：冻结验证清单第四项“图片、视频、动作真实外部生成”的人工联调口径，明确哪些入口已接真实外部图片服务、哪些入口仍是 Stage 1 占位链，以及前端点击路径、日志观察点和通过标准。

• M6_CHARACTER_VISUAL_ASSET_EXTERNAL_GENERATION_STAGE2_2026-04-23.md：冻结角色主形象从 Stage 1 SVG 占位草稿切到 DashScope 真实出图的 Stage 2 口径，覆盖模型、参考图解析、去底处理、OSS 草稿存储和失败策略。

• M6_CHARACTER_ANIMATION_ASSET_EXTERNAL_GENERATION_STAGE2_2026-04-23.md：冻结角色动作从 Stage 1 占位视频切到真实 Ark/DashScope 生成的 Stage 2 口径，优先明确 image-to-video 主链、Ark 固定参数、媒体上传与错误回退规则。

• M6_CHARACTER_ANIMATION_BACKEND_FRAME_EXTRACTION_AND_PUBLISH_STAGE3_2026-04-23.md：冻结角色动作正式发布链从“前端抽帧回传”继续迁到“后端抽帧、去绿幕、上传 OSS、落库绑定”的 Stage 3 口径，明确 ffmpeg/ffprobe 依赖、contract 扩展与兼容策略。

• WECHAT_LOGIN_AXUM_IMPLEMENTATION_DESIGN_2026-04-21.md：Rust api-server 微信登录实现设计，冻结微信 provider 接入、系统 JWT 签发边界、wechat/start / wechat/callback / wechat/bind-phone 闭环，以及与后续 SpacetimeDB claims 透传的关系。

• WECHAT_LOGIN_REAL_INTEGRATION_RUNBOOK_2026-04-21.md：微信登录从本地 mock 到真实微信开放平台联调的执行手册，覆盖环境变量、回调域名、代理头要求、验证步骤与常见失败排查。

• PASSWORD_ENTRY_FLOW_DESIGN_2026-04-21.md：密码登录与自动建号落地设计，冻结 /api/auth/entry、幂等兼容策略、模块边界以及与 JWT / refresh cookie 的衔接方式。

• MULTI_DEVICE_SESSION_IDENTITY_DESIGN_2026-04-21.md：多端登录会话身份模型设计，冻结浏览器、小程序、微信内 H5 的客户端身份字段、请求头约定与展示名派生规则。

• PLATFORM_AUTH_REFRESH_COOKIE_ADAPTER_DESIGN_2026-04-21.md：platform-auth refresh cookie 适配设计，冻结 cookie 配置结构、读取规则与 api-server 最小读取链路。

• PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md：platform-auth 首版 JWT 适配设计，冻结 JwtConfig、claims 结构、HS256 签发/校验、api-server Bearer 中间件与内部验收路由边界。

• OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md：面向 Axum、platform-auth 与 SpacetimeDB 身份透传的 OIDC 风格 JWT claims 设计，冻结 iss/sub/sid/provider/roles 等关键字段。

• RUST_SHARED_LOGGING_CRATE_DESIGN_2026-04-21.md：Rust 工作区统一日志模块 shared-logging 的职责边界、API、输出风格与 api-server 迁移规则。

• RUST_SHARED_CONTRACTS_CRATE_STAGE1_DESIGN_2026-04-21.md：把 shared-contracts 从占位目录推进成真实共享协议 crate，冻结统一 envelope、auth/*、runtime/settings、assets/* 与 story-sessions/* 首批公开 DTO 的迁移边界。

• RUST_SHARED_CONTRACTS_CRATE_STAGE4_RESPONSE_DTO_DESIGN_2026-04-21.md：继续把 assets/* 与 story-sessions/* 的成功响应从 handler 内 json! 手拼收口到 shared-contracts，冻结显式响应 DTO 与适配边界。

• RUST_SHARED_KERNEL_CRATE_STAGE1_DESIGN_2026-04-21.md：把 shared-kernel 从目录占位推进到首批真实共享内核，冻结第一阶段只允许上提的基础字符串、ID 与时间处理能力，以及首批接入 crate 范围。

• RUST_SHARED_KERNEL_CRATE_STAGE2_ADOPTION_2026-04-21.md：在不扩公共 API 的前提下，把 shared-kernel 第一阶段已冻结的字符串、UUID 与时间处理能力继续接入 module-runtime、module-story、spacetime-client 与 api-server。

• RUST_SHARED_KERNEL_CRATE_STAGE3_VALUE_NORMALIZATION_2026-04-22.md：继续把 shared-kernel 扩到跨多个纯领域 crate 已稳定重复的字符串列表归一化与前缀种子 ID 拼接能力，明确第三阶段仍不进入 JSON、配置与平台语义处理。

• RUST_SHARED_KERNEL_CRATE_STAGE4_REQUIRED_STRING_ADOPTION_2026-04-22.md：继续把 shared-kernel::normalize_required_string(...) 接入更多纯领域 crate，收口跨模块重复的“trim + 判空 + 映射字段错误”逻辑，同时明确不进入平台与 JSON 语义。

• RUST_SHARED_KERNEL_CRATE_STAGE5_PURE_DOMAIN_FIELD_ADOPTION_2026-04-22.md：继续把 shared-kernel::normalize_required_string(...) 接入 module-runtime 与 module-assets 剩余的纯字段级归一化逻辑，保留 object_key 等模块局部语义不变。

• SPACETIMEDB_WECHAT_AUTH_STATE_TABLE_DESIGN_2026-04-21.md：M2 第七张微信 OAuth 状态表 wechat_auth_state 的字段、过期/消费语义、wechat/start 与 wechat/callback 的单次消费规则，以及多实例下的清理策略。

• SPACETIMEDB_SMS_AUTH_EVENT_TABLE_DESIGN_2026-04-21.md：M2 第六张短信鉴权统计表 sms_auth_event 的事件范围、统计口径、索引与和风控/审计表的协作边界。

• SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md：M2 第五张风控状态表 auth_risk_block 的作用域、活跃态、刷新/解除规则与读取派生约束。

• SPACETIMEDB_AUTH_AUDIT_LOG_TABLE_DESIGN_2026-04-21.md：M2 第四张鉴权审计表 auth_audit_log 的事件范围、追加写规则、索引与对外 DTO 派生约束。

• SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md：M2 第三张会话表 refresh_session 的 cookie/hash 边界、轮换与吊销语义、索引与迁移规则。

• SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md：M2 第二张身份表 auth_identity 的 provider 范围、唯一约束、手机号/微信身份写入规则与迁移策略。

• SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md：M2 第一张身份主表 user_account 的职责边界、字段、唯一约束、状态迁移、旧 users 映射与落地约束。

• SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md：基于旧 Node 后端能力清单，设计用 SpacetimeDB + Axum + 阿里云 OSS 重写后端的目标架构、模块映射、数据分层、迁移顺序与验收标准。

• M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md：冻结 M6 剩余的 STS 与服务端上传 helper 落地口径，明确当前上传主链为服务器上传 OSS，Web 端只负责签名读下载。

• M6_ASSET_METADATA_HASH_VERSION_AND_SPECIALIZED_TABLE_BOUNDARY_2026-04-22.md：冻结 M6 第一批内容 hash、版本、manifest、asset job 与强业务资产表的 Stage 1 边界，明确当前使用 asset_object + asset_entity_binding + OSS manifest + AiTaskService 闭合，不重复新增表。

• M6_LEGACY_GENERATED_PATH_OSS_READ_COMPAT_2026-04-22.md：冻结 M6 旧 /generated-* 路径到 OSS 私有读同源代理的兼容口径，保证旧前端仍能直接消费图片、视频、动作帧与 manifest。

• AXUM_TO_SPACETIMEDB_ASSET_OBJECT_CONFIRM_CALL_DESIGN_2026-04-21.md：冻结 POST /api/assets/objects/confirm 从 Axum 通过 Rust SDK 调用 SpacetimeDB procedure 的最小落地方案，明确本地 server、数据库名、procedure/reducer 分工与 spacetime-client 边界。

• M3_RUNTIME_SETTINGS_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md：冻结 M3 首批 runtime settings 纵向切片的表字段、默认值、procedure、Axum facade、错误 contract 与测试策略。

• SPACETIMEDB_CUSTOM_WORLD_AGENT_SESSION_STAGE6_DESIGN_2026-04-22.md：冻结 M5 Agent session create / snapshot 的最小 SpacetimeDB 与 Axum facade 闭环，明确本轮不迁移 LLM、SSE、卡片更新和完整 action registry。

• SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STAGE7_DESIGN_2026-04-22.md：冻结 M5 Agent message submit / operation query 的 deterministic 最小闭环，明确同步写入 user/assistant 消息、process_message operation 与 session 进度推进规则。

• SPACETIMEDB_CUSTOM_WORLD_AGENT_MESSAGE_STREAM_STAGE8_DESIGN_2026-04-22.md：冻结 M5 Agent /messages/stream 的最小兼容 SSE facade，明确复用 Stage 7 的同步写表逻辑，只输出当前前端真实消费的 reply_delta / session / done / error 事件。

• BIG_FISH_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md：冻结大鱼吃小鱼玩法本轮最小完整落地方案，明确 module-big-fish、SpacetimeDB 表 / procedure、Axum facade、前端接入和运行态规则边界。

• BIG_FISH_ASSET_PLACEHOLDER_PREVIEW_FIX_2026-04-23.md：记录大鱼吃小鱼结果页“状态成功但只看到蓝色底图”的根因，冻结占位图真实写盘、结果页预览渲染与文案收口方案。

• BIG_FISH_FORMAL_IMAGE_GENERATION_2026-04-23.md：冻结 Big Fish 从“占位可见”升级到“模型正式出图”的 Rust 落地方案，明确复用 DashScope + OSS + asset_object 真相链、新的 /generated-big-fish-assets/* 兼容路径，以及 Big Fish 槽位写入语义调整。

• PUZZLE_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md：冻结拼图玩法本轮最小完整落地方案，明确 module-puzzle、SpacetimeDB 表 / procedure、Axum facade、前端接入，以及交换 / 合并 / 拖动 / 拆分 / 下一关推荐边界。

• UNIFIED_CREATION_AGENT_CHAT_FRAMEWORK_2026-04-22.md：冻结所有创作品类 Agent 聊天 UI 与对话进度管理统一框架，明确品类差异只保留锚点映射、提示词/话术和 action。

• RUST_API_SERVER_SSE_INFRASTRUCTURE_DESIGN_2026-04-22.md：冻结 server-rs/crates/api-server 的 SSE 使用口径，明确统一使用 Axum 内建 Sse<Event>，不再保留自定义 sse.rs 模块。

• SPACETIMEDB_CUSTOM_WORLD_LIBRARY_DETAIL_STAGE5_EXTENSION_DESIGN_2026-04-22.md：补齐 M5 Stage 5 遗漏的 owner-only GET /api/runtime/custom-world-library/:profileId 设计，冻结单条 profile detail 的 SpacetimeDB procedure、client facade、404 语义与 Axum 路由扩展方式。

• SPACETIMEDB_CUSTOM_WORLD_WORKS_AND_AGENT_EXTENSION_STAGE9_DESIGN_2026-04-22.md：冻结 M5 剩余主链的 works、card detail、publish gate、supportedActions、action registry 与 AI/OSS 兼容路由边界，作为 Stage 9 到收口阶段的统一落地依据。

• M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md：冻结 M6 第一批 custom world 场景图、封面图、封面上传从本地 public/ 临时落地切到 OSS + asset_object + asset_entity_binding 正式真相链的边界与槽位约定。

• M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md：冻结 M6 第二批 custom world 图片链迁移口径，明确把 scene-image / cover-image 从 Rust SVG 占位切到真实 DashScope 图片生成，并补回 cover-upload 的 cropRect + 16:9 + WebP 压缩。

• M6_CHARACTER_ANIMATION_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md：冻结 M6 第一批角色动作 generate / jobs / publish 接口从旧本地 public/generated-* 真相切到 OSS + asset_object + asset_entity_binding + AI task 的最小闭环与兼容 contract。

• M6_CHARACTER_ANIMATION_IMPORT_AND_TEMPLATE_STAGE1_2026-04-22.md：冻结 M6 第一批角色动作模板查询与参考视频导入从旧 Node 本地草稿写盘切到 Rust OSS 草稿对象的接口 contract、对象键规划与暂不确认 asset_object 的边界。

• M6_CHARACTER_WORKFLOW_CACHE_OSS_STAGE1_2026-04-22.md：冻结 M6 第一批角色资产工作流缓存从旧 Node 本地 workflow-cache.json 切到 Rust OSS JSON 草稿对象的读写 contract、字段归一化与暂不落正式资产表的边界。

• M6_CHARACTER_VISUAL_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md：冻结 M6 第一批角色主形象 generate / jobs / publish 接口从旧本地 public/generated-* 真相切到 OSS + asset_object + asset_entity_binding + AI task 的最小闭环与兼容 contract。

• M7_TEST_DEPLOY_CUTOVER_EXECUTION_PLAN_2026-04-22.md：冻结 M7 联调、回归、部署、观测、Rust 主线灰度、回滚和 spacetime-module 结构收口的可执行方案。

• M3_BROWSE_HISTORY_AXUM_SPACETIMEDB_DESIGN_2026-04-21.md：冻结 M3 第二批 browse history 纵向切片的 user_browse_history 表、双路径 facade、宽松归一化、去重排序规则与测试策略。

• ASSET_ENTITY_BINDING_REDUCER_DESIGN_2026-04-21.md：冻结已确认 asset_object 绑定到业务实体槽位的首版 reducer/procedure、通用 asset_entity_binding 表与 Axum facade。

• REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md：落实工程清理审计第一阶段后的仓库噪音清理范围、忽略规则闭合点与后续约束。

• ENCODING_CHECK_TRANSIENT_WORKSPACE_FIX_2026-04-22.md：冻结编码检查不扫描临时 Cargo / verify 工作区、同时把 Rust 源文件纳入 UTF-8 校验的修复口径。

• CUSTOM_WORLD_DRAFT_GENERATION_FAILURE_ANALYSIS_AND_FIX_2026-04-20.md：世界草稿生成失败后等待页误显示为“卡在编译草稿卡”的根因拆解、主链与增强链路边界，以及本次修复策略。

• CUSTOM_WORLD_AUTO_ASSET_VISIBILITY_FIX_2026-04-20.md：世界草稿里“资产已生成但结果页看不到”的根因拆解，包含角色主形象展示、分幕背景露出和 fallback 资源格式修复。

• CUSTOM_WORLD_PHASE4_COUNT_SEMANTICS_ALIGNMENT_2026-04-20.md：Phase4 新增角色/地点后草稿作品卡数量统计与测试断言的语义对齐说明。

• AGENT_RESULT_PROFILE_SYNC_PHASE1_2026-04-20.md：阶段一保持结果页深度编辑能力不变，同时把结果页完整世界快照同步回 Agent session 主链的方案说明。

• AGENT_RESULT_PROFILE_SYNC_PHASE2_2026-04-20.md：阶段二把平台创作入口统一到聚合作品列表，并收紧 Agent 结果页的新增入口职责边界。

• AGENT_RESULT_PROFILE_SYNC_PHASE3_2026-04-20.md：阶段三继续降级旧 pipeline，让创作中心只认 Agent 草稿与已发布作品，并把 Agent 结果页冻结为预览收口层。

• AGENT_DIALOG_AND_RESULT_REFINEMENT_BOUNDARY_2026-04-21.md：修正 Agent 对话框与结果页职责边界，明确 Agent 只收集八锚点，已有底稿的精修进入结果页完成。

• CURRENT_AGENT_CREATION_FLOW_STAGE4_CLEANUP_CHECK_2026-04-21.md：对照当前优化计划核查四阶段完成度，并明确这轮只允许物理删除旧 custom-world/sessions 世界生成链，不误伤 Agent 主链与已保存作品兼容编辑链。

• CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md：梳理当前创作入口到结果页自动保存再到进入世界的全链前后端脚本地图，并给出文件级重构拆分方案、目标分层与阶段验收标准。

• RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md：梳理当前 RPG 从平台入口、继续游戏、角色选择到营地开场、冒险运行态与 runtime story 后端结算的全链脚本地图，并给出 RPG 专属命名规范、目标分层和可并行执行的工作包。

• RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_A_PROGRESS_2026-04-21.md：记录 RPG 进入游戏与运行时链路工作包 A 已完成的新目录骨架、前后端 façade、按域路由 path 常量与兼容仓储入口。

• RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_B_PROGRESS_2026-04-21.md：记录工作包 B 已完成的前端 RPG 入口壳层真实迁移、rpg-entry 新入口 hooks 收口，以及旧 game-shell / rpg-creation-flow 路径降级为兼容层的状态。

• RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_C_PROGRESS_2026-04-21.md：记录工作包 C 已完成的 rpg-session 主链迁移、snapshot / save archive client 收口、旧 useGame* 降级为兼容 façade，以及定向回归结果。

• RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_D_PROGRESS_2026-04-21.md：记录工作包 D 已完成的前端运行态 shell / stage router / panel router 真实迁移、AdventurePanel section 拆分，以及旧 GameShell* 热点降级为兼容桥的现状。

• RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_F_PROGRESS_2026-04-21.md：记录 RPG 进入游戏与运行时链路工作包 F 已完成的后端 route 真正拆边界、app.ts 新域挂载、旧 runtimeRoutes / storyActionRoutes 兼容降级，以及定向路由回归验证结果。

• RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_E_PROGRESS_2026-04-21.md：记录工作包 E 已完成的前端 runtime story 主链真实迁移、NPC 交互与 gateway/client 收口、旧入口兼容降级，以及定向回归验证结果。

• RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_G_PROGRESS_2026-04-21.md：记录工作包 G 已完成的后端 runtime session / action service 物理迁移、新域原语导出、旧热点兼容降级，以及定向 runtime story 回归验证结果。

• RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_WORK_PACKAGE_H_PROGRESS_2026-04-21.md：记录工作包 H 已完成的 RPG 运行时仓储拆分、shared runtime contract 分文件、旧 story.ts façade 兼容与定向回归结果。

• M4_RPG_RUNTIME_STORY_SPACETIMEDB_BASELINE_2026-04-21.md：记录 server-rs 侧 M4 首轮已落地的 story_session / story_event SpacetimeDB 基座、begin_story_session / continue_story reducer、同步返回快照的 story procedure、spacetime-client facade 与新的 /api/story/sessions* Axum 接口，以及当前尚未兼容旧 runtime story 路由的边界。

• M4_RPG_RUNTIME_STORY_SESSION_STATE_QUERY_DESIGN_2026-04-22.md：冻结 GET /api/story/sessions/:storySessionId/state 这条最小 story state 查询切片，明确当前只返回 storySession + storyEvents，不等价于旧 runtime story state 兼容完成。

• M4_RUNTIME_STORY_COMPAT_STATE_BRIDGE_DESIGN_2026-04-22.md：冻结旧 POST /api/runtime/story/state/resolve 兼容桥的首版边界，明确先补 RuntimeStoryActionResponse DTO 与状态桥，再继续进入 Rust actions/resolve 与正式 snapshot projection。

• M4_RUNTIME_STORY_RS_SPLIT_PLAN_2026-04-22.md：冻结 runtime_story.rs 从超大单文件拆到 compat/ai/presentation/tests/battle/core/game_state/forge/npc_support/*_actions 子模块的收口策略、验证要求与下一阶段纯规则下沉边界。

• M4_MODULE_AI_BASELINE_DESIGN_2026-04-21.md：冻结 module-ai 首版的任务/阶段/流式片段/结果引用领域模型、最小内存服务与后续 platform-llm / api-server / spacetime-module 的边界。

• M4_MODULE_AI_SPACETIMEDB_BASELINE_2026-04-21.md：记录 module-ai 在 spacetime-module 中首轮已落地的 ai_task / ai_task_stage / ai_text_chunk / ai_result_reference 真相表、最小 reducer/procedure 与当前仍未扩到真实模型调用和 Axum facade 的边界。

• M4_MODULE_AI_AXUM_FACADE_DESIGN_2026-04-22.md：冻结 module-ai 从 shared-contracts、spacetime-client 到 api-server 的最小 AI task mutation facade，明确 start 路由当前只返回 202 Accepted。

• M4_RPG_RUNTIME_QUEST_SPACETIMEDB_BASELINE_2026-04-21.md：记录 module-quest 首轮已落地的 quest_record / quest_log 字段模型、accept_quest / apply_quest_signal / acknowledge_quest_completion / turn_in_quest reducer 边界，以及当前刻意未扩到奖励结算和 Axum facade 的范围。

• M4_RUNTIME_ITEM_TREASURE_SPACETIMEDB_BASELINE_2026-04-21.md：记录 module-runtime-item 首轮已落地的 treasure_record 字段模型、奖励快照 contract、resolve_treasure_interaction reducer/procedure 边界，以及当前刻意未扩到 inventory_slot 和 Axum facade 的范围。

• M4_MODULE_COMBAT_SPACETIMEDB_BASELINE_2026-04-21.md：冻结 module-combat 首版 battle_state、resolve_combat_action、fight / spar 收束规则与 spacetime-module 接线边界，明确当前暂不接入 inventory_use 与跨子域奖励联动。

• M4_MODULE_COMBAT_AXUM_FACADE_DESIGN_2026-04-21.md：冻结 module-combat 从 spacetime-module procedure 到 spacetime-client 再到 api-server 的最小同步返回链，明确当前只新增独立 battle facade，不直接兼容旧 runtime story 总入口。

• M4_MODULE_COMBAT_STATE_QUERY_DESIGN_2026-04-22.md：冻结 GET /api/story/battles/:battleStateId 这条最小 battle state 查询切片，明确当前只返回单个 battleState 真相态，不等价于旧 runtime story state 兼容完成。

• M4_RUNTIME_INVENTORY_STATE_QUERY_DESIGN_2026-04-22.md：冻结 GET /api/runtime/sessions/:runtimeSessionId/inventory 这条最小 inventory 查询切片，明确当前只返回 inventory_slot 真相表拆分后的 backpackItems + equipmentItems。

• M4_MODULE_NPC_SPACETIMEDB_BASELINE_2026-04-21.md：记录 server-rs 侧 module-npc 首轮已落地的 npc_state / relation_state / stance_profile 领域 contract、resolve_npc_social_action 规则原语，以及 spacetime-module 的最小 reducer / procedure 接线边界。

• M4_MODULE_NPC_COMBAT_ORCHESTRATION_BASELINE_2026-04-21.md：冻结 npc_fight / npc_spar 在 spacetime-module 聚合层初始化 battle_state 的最小联合 procedure 边界，明确仍不把战斗初始化字段回灌到 module-npc 纯领域 crate。

• M4_MODULE_NPC_BATTLE_AXUM_FACADE_DESIGN_2026-04-22.md：冻结 resolve_npc_battle_interaction_and_return 向上接入 spacetime-client 与 api-server 的最小同步返回链，明确当前只新增独立 POST /api/story/npc/battle facade。

• M4_MODULE_PROGRESSION_SPACETIMEDB_BASELINE_2026-04-21.md：记录 server-rs 侧 module-progression 首轮已落地的 player_progression / chapter_progression 字段模型、成长曲线、章节预算与记账 reducer / procedure 边界，以及当前刻意未扩到完整章节蓝图迁移和 quest/combat 自动联动的范围。

• M4_PROGRESSION_QUEST_COMBAT_INTEGRATION_2026-04-21.md：冻结 turn_in_quest 与 resolve_combat_action(Victory) 到 player_progression / chapter_progression 的最小联动口径，明确 battle 奖励字段、章节账本静默跳过规则与本轮不扩到的范围。

• RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PARALLEL_BATCH_AUDIT_2026-04-21.md：对照执行计划逐项复核第一批与第二批并行工作的真实落地状态，记录本轮确认到的测试合流收口遗漏与文档索引补齐结果。

• RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_PHASE3_CLOSURE_2026-04-21.md：记录 RPG 执行计划第三批收口已完成的前端新域主链接回、后端新仓储接线、shared contract 直连收紧、旧兼容脚本物理删除，以及明确未扩到 UI 和无关历史文档的边界。

• RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_OLD_SCRIPT_REMOVAL_2026-04-21.md：记录 RPG 主链旧 GameShell、useGame*、hooks/story、runtimeRoutes、modules/story/*、contracts/story.ts 脚本的物理删除范围、残留依赖扫描和定向验证结果。

• CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_A_PROGRESS_2026-04-21.md：记录创作链路重构工作包 A 已落地的 RPG 创作域目录骨架、兼容 façade，以及补齐后的共享契约骨架入口。

• CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_E_PROGRESS_2026-04-21.md：记录工作包 E 已完成的后端 Agent 编排拆分、executor 物理迁移、发布链切到 CustomWorldAgentPublishingService、checkpoint 真快照、场景资产 coverage 收口，以及 Phase3/Phase5 定向回归结果。

• CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_H_PROGRESS_2026-04-21.md：记录工作包 H 已完成的共享契约物理拆分、旧命名兼容分文件、统一 fixture，以及 shared contract test / preview compiler / works assembler / works service 回归基建。

• CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_B_PROGRESS_2026-04-21.md：记录工作包 B 已完成的前端平台壳层编排拆分、平台 hooks / coordinator 接入、旧入口兼容保留，以及交互回归验证结果。

• CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_F_PROGRESS_2026-04-21.md：记录工作包 F 已完成的后端 session/store/repository 拆分、works 读模型 service 收口、route/context 直接注入新仓储，以及定向 custom world 回归验证结果。

• CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_D_PROGRESS_2026-04-21.md：记录工作包 D 已完成的前端 custom world client 真正迁出、旧 service 兼容降级，以及平台壳层/结果页测试切换到 rpgCreation 域入口的现状。

• CREATION_FLOW_CHAIN_REFACTOR_WORK_PACKAGE_G_PROGRESS_2026-04-21.md：记录工作包 G 已完成的 runtime profile 目录化、服务端 preview compiler 收口，以及 foundation draft 主生成链与 preview 编译边界的直接拆开。

• CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md#93-工作包-c前端结果页与编辑器拆分：记录工作包 C 已完成的结果页壳层拆分、编辑器目标分发与 mapper 收口、角色资产工坊 section/workflow 拆分，以及仍保留的阶段性 shared 实现边界。

• CREATION_PAGE_MOBILE_UI_FIX_2026-04-21.md：创作页移动端底部 Tab、亮色主题 token 与滚动权责修复记录。

• RPG_FOUNDATION_DRAFT_EIGHT_ANCHOR_SEED_FIX_2026-04-25.md：记录 RPG 创作 Agent session 八锚点进入 foundation draft seed 时被旧字段压缩的根因、修复和后续约束。

• TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md：把外部仓库 TXT 模式完整迁入当前项目的冻结边界、模块映射、分阶段计划与验收清单。

• AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md：AI 生成角色形象与角色动画的技术路线。

• ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md：面向编辑器的阿里云 NPC 形象与动作实验方案，按 4 条生成链路对比。

• PIXELMOTION_TECHNICAL_BREAKDOWN_2026-04-04.md：PixelMotion 产品形态与能力拆解。

• SERVER_DEPLOYMENT_AND_CORS_TECHNICAL_SOLUTION_2026-04-05.md：服务端部署、代理层与 CORS 方案。

• WORLD_DRAFT_FOUNDATION_EDITOR_TARGET_FIX_2026-04-25.md：记录世界草稿“基本设定”独立编辑目标、分号标签化展示与编辑回写边界。

使用建议

• 做实现选型时，优先看这一组。
• 做后端实现前，先看 CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md，再进入具体 Rust / SpacetimeDB 方案。
• 做阶段排期时，把这一组和 docs/planning/、docs/prd/ 一起看，更容易判断先后顺序。