Genarrative/docs/README.md

文档总览

docs/ 现在按主题拆成了 6 类；旧后端路线文档开始聚合和删除，后续实现以 Rust / SpacetimeDB 当前基线为准。

快速入口

• 经验沉淀：项目开发经验、UI 交接、历史实现经验。
• 审计与复盘：工程审查、文本/乱码审计、专项落地审计。
• 系统设计：玩法、关系、物品与对话设计。
• 技术方案：动画、服务端、外部产品形态拆解。
• 规划与优先级：当前阶段的迭代排序与落地优先级；创作流程统一总计划见 【玩法创作】创作流程统一总计划-2026-05-30.md。
• 参考目录：脚本/Function 速查入口。 重点补充：RPG 创作与运行时脚本职责地图见 RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md。
• 埋点查询：埋点原始事件与聚合投影的本地 SQL 查询。
• 运营查询：任务、领奖、钱包对账等后台核查查询。
• PRD：产品需求与阶段计划；参考 MOKU / 幕间类 AI 文游的陶泥儿 text-game 模板口径见 AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md，视觉小说模板 TXT 玩法平台化接入口径见 AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md，创意互动内容 Agent Phase 1 的 LangChain-Rust PoC、拼图闭环和并行任务拆分见 CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md，幸存者类模板闭环见 AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md，后台管理独立前端工程见 ADMIN_WEB_CONSOLE_PRD_2026-04-30.md，新增 RPG 开场动画方案见 AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md，新增抓大鹅 Match3D 玩法方案见 AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md，方洞挑战创作、发布与试玩闭环见 AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md，跳一跳俯视角玩法模板 PRD 见 【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md。

拼图生成页步骤真进度、步骤内假进度和精简展示口径见 【玩法创作】拼图生成页进度口径-2026-05-23.md。

从文字需求生成高一致性美术素材流程抽象出的发明专利交底稿见 【专利交底】一种极低成本快速生成高质量2D小游戏高一致性美术素材的解决方案-2026-05-25.md。

微信小程序虚拟支付接入、wechat_mp_virtual 渠道、wx.requestVirtualPayment 承接页和后端签名配置见 【技术方案】微信虚拟支付接入-2026-05-26.md。

生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md，该文档也是当前生产 Jenkinsfile 的唯一入口。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md 与 JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md；后台管理独立前端工程技术方案见 ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md。

SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md。

创作 Agent 问答流式失败时保留已显示回复、并透出更具体上游错误的契约见 CREATION_AGENT_STREAM_FAILURE_RETENTION_FIX_2026-05-05.md。

maincloud 相关脚本、环境变量、测试名和文档要求已统一判定为历史残留，后续禁止新增、运行或引用；当前后端 smoke 使用 npm run dev:api-server 与 /healthz，详细规则见 MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md。

基于 LangChain-Rust，以“感知—思考—记忆—行动—反思—协作”闭环完成图文创意理解、拼图模板选择、积分范围确认、拼图草稿字段填充、立即试玩和自然语言修订草稿字段的 Agent 方案见 CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md。

创意互动内容 Agent Phase 1 的产品边界、实现细节、SpacetimeDB 落点、前端接入和可并行任务拆分见 CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md。

视觉小说模板接入以 AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md 为最新口径：只吸收外部 TXT 玩法的模板创作与运行经验，禁止迁入外部平台功能，并删除回放。

AI 文字游戏模板接入以 AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md 为最新口径：只吸收 MOKU / 幕间类 AI 文游的剧本游乐场、自由行动、AI GM、记忆和模拟器强反馈经验，禁止迁入外部社区、支付、榜单、私有存档或回放。

前端 Server-Sent Events 客户端传输层收口到 src/services/sseStream.ts，事件边界、UTF-8 flush、JSON 解析跳过和提前取消约定见 【前端架构】SSE客户端传输层收口约定-2026-06-03.md。

平台入口公开作品身份、跨玩法去重、公开作品流聚合、推荐运行态 kind 判定、推荐 runtime 启动意图、ready 判定和最新排序收口到 src/components/platform-entry/platformPublicGalleryFlow.ts，规则见 【前端架构】平台入口PublicGalleryFlowModule收口计划-2026-06-03.md。

统一作品详情页的玩法 kind、详情打开策略、自有作品动作模式、编辑 / 点赞 / 改造 / 启动意图和公开详情映射收口到 src/components/platform-entry/platformPublicWorkDetailFlow.ts；抓大鹅公开详情映射与启动 / 编辑 Adapter 的素材归一仍归 platformMatch3DRuntimeProfile.ts，规则见 【前端架构】PlatformPublicWorkDetailFlow收口计划-2026-06-03.md。

创作中心作品架打开动作由 CreationWorkShelfItem.actions.open 统一承载，生产 Hub 只接收 CreationWorkShelfItem[] 与 UI 状态，不再接收各玩法 raw items 和回调列阵，规则见 【前端架构】WorkShelfModule收口计划-2026-06-03.md。

作品架删除确认的标题、删除说明、草稿 notice key 和拼图派生稳定 ID 收口到 src/components/platform-entry/platformCreationWorkDeleteFlow.ts，平台壳只保留删除 API、刷新、错误和页面跳转副作用，规则见 【前端架构】CreationWorkDeleteFlow收口计划-2026-06-04.md。

创作入口点击的占位、隐藏模板拦截、未知入口 no-op 与工作台启动目标收口到 src/components/platform-entry/platformCreationLaunchModel.ts，壳层只执行启动前准备、错误提示和受保护动作，规则见 【前端架构】PlatformCreationLaunchModel收口计划-2026-06-04.md。

平台入口公开码搜索的用户 ID、陶泥号、RPG 作品号、各玩法作品号前缀和失败回退顺序收口到 src/components/platform-entry/platformPublicCodeSearchModel.ts，壳层只按计划执行网络读取、详情打开和错误归航副作用，规则见 【前端架构】PlatformPublicCodeSearchModel收口计划-2026-06-04.md。

个人“玩过作品”面板的玩法别名、worldKey 前缀兜底、RPG 公开详情 payload 和大鱼吃小鱼 gallery miss fallback 收口到 src/components/platform-entry/platformPlayedWorkOpenModel.ts，壳层只执行面板关闭、gallery 读取、详情打开和错误提示副作用，规则见 【前端架构】PlatformPlayedWorkOpenModel收口计划-2026-06-04.md。

平台入口生成页进度 tick 的 stage 到生成状态映射、终态判定和视觉小说轻量生成特例收口到 src/components/platform-entry/platformGenerationProgressTickModel.ts，壳层只保留 Date.now()、setInterval 和 cleanup 副作用，规则见 【前端架构】PlatformGenerationProgressTickModel收口计划-2026-06-04.md。

平台壳的拼图 runtime 恢复 work、方洞 session draft 转 profile、跳一跳 pending session、敲木鱼 detail 恢复 session 和敲木鱼 pending session DTO 映射收口到 src/components/platform-entry/platformMiniGameSessionMappingModel.ts，壳层只保留网络、状态、URL 与 stage 副作用，规则见 【前端架构】PlatformMiniGameSessionMappingModel收口计划-2026-06-04.md。

平台小游戏生成状态的恢复、失败 / 完成收尾、展示 rebase、拼图后端进度合并、抓大鹅生成资产旁路进度合并和 ready / generating 判定收口到 src/components/platform-entry/platformMiniGameDraftGenerationStateModel.ts，壳层只保留 API、后台任务、React state、URL 与 stage 副作用，规则见 【前端架构】PlatformMiniGameDraftGenerationStateModel收口计划-2026-06-04.md。

平台小游戏草稿恢复和提交所需的拼图 / 抓大鹅表单 payload、拼图编译 action、pending metadata 与拼图 form-only 草稿判定收口到 src/components/platform-entry/platformMiniGameDraftPayloadModel.ts，壳层只保留 API、Action 执行、background task 与状态副作用，规则见 【前端架构】PlatformMiniGameDraftPayloadModel收口计划-2026-06-04.md。

平台拼图生成完成后刷新恢复的草稿归一化与可恢复完成态判定收口到 src/components/platform-entry/platformPuzzleDraftRecoveryModel.ts，恢复链路只有在首图、关卡画面、UI spritesheet 与关卡背景资产包完整时才抬为 ready，规则见 【前端架构】PlatformPuzzleDraftRecoveryModel收口计划-2026-06-04.md。

后端拼图发布 / 待发布门槛收紧到首图、关卡画面、UI spritesheet 与关卡背景资产包完整，module-puzzle 的 preview blockers 与 api-server 的 session stage 判定保持同一规则，方案见 【后端架构】PuzzlePublishAssetGate收紧计划-2026-06-04.md。

平台入口个人钱包本地 delta、dashboard 乐观更新与服务端快照对账规则收口到 src/components/platform-entry/platformProfileWalletDeltaModel.ts，平台壳只保留 API、ref 与 state 副作用，规则见 【前端架构】PlatformProfileWalletDeltaModel收口计划-2026-06-04.md。

Bark Battle 草稿三图完整性、生成状态归一、发布快照 / 发布回包资产兜底和草稿 / 已发布作品进入 runtime 前的 BarkBattlePublishedConfig 映射收口到 src/components/platform-entry/barkBattleWorkCache.ts，规则见 【前端架构】BarkBattleWorkCache草稿状态收口计划-2026-06-04.md。

平台首页推荐 runtime 的匿名 Runtime Guest Token、已登录 background auth、非 embedded no-op 和拼图 isolated/default auth mode 计划收口到 src/components/platform-entry/platformRecommendRuntimeAuthModel.ts，规则见 【前端架构】PlatformRecommendRuntimeAuthModel收口计划-2026-06-04.md。

平台首页推荐 runtime 自动启动的桌面 / Tab / stage / loading gate、active entry 查找、ready 判定和 clear/start/noop 决策收口到 src/components/platform-entry/platformPublicGalleryFlow.ts，规则见 【前端架构】PlatformRecommendRuntimeAutoStart收口计划-2026-06-04.md。

RPG Agent 结果页发布门禁展示和预览来源 label 收口到 src/components/platform-entry/platformRpgAgentResultPreviewModel.ts，壳层只保留 session/profile 编排和结果页 props 传递，规则见 【前端架构】PlatformRpgAgentResultPreviewModel收口计划-2026-06-04.md。

平台入口创作生成通知、pending 作品架占位、失败覆盖、拼图稳定 ID 和草稿 Tab 未读点收口到 src/components/platform-entry/platformDraftGenerationShelfModel.ts，规则见 【前端架构】DraftGenerationShelfModel收口计划-2026-06-03.md。

平台入口创作恢复 URL 私有 query、初始恢复判定、创作直达恢复目标解析、恢复目标身份匹配、跳一跳 / 敲木鱼恢复阶段落点、拼图 runtime query 与拼图稳定身份互推收口到 src/components/platform-entry/platformCreationUrlStateModel.ts 和 src/components/platform-entry/platformPuzzleIdentityModel.ts，规则见 【前端架构】CreationUrlStateModel收口计划-2026-06-03.md。

平台入口错误 / 完成弹窗的文案归一、来源格式、候选择一、dismiss key 与任务完成文案收口到 src/components/platform-entry/platformDialogStateModel.ts，规则见 【前端架构】PlatformDialogStateModel收口计划-2026-06-03.md。

平台入口受保护数据失效后的 stage 去留判定，以及缺失草稿 / 作品 / run 时的阶段回退，收口到 src/components/platform-entry/platformSelectionStageModel.ts，壳层只执行缓存清空、布尔事实汇总和必要跳转，规则见 【前端架构】PlatformSelectionStageModel收口计划-2026-06-04.md。

小游戏 runtime client 的路径编码、JSON 请求、runtime guest auth 与 retry 选项收口到 src/services/runtimeRequest.ts，Match3D、SquareHole、Big Fish、Bark Battle、Puzzle 公开 / 推荐运行态请求、Jump Hop / Wooden Fish 正式 run 请求和 Visual Novel 局部 JSON runtime 请求已先迁移，规则见 【前端架构】RuntimeClientFamily收口计划-2026-06-03.md。

抓大鹅 runtime profile 的公开详情转 work、session draft 转 profile、生成背景资产提升和 run/profile/public detail 素材优先级收口到 src/components/platform-entry/platformMatch3DRuntimeProfile.ts，规则见 【前端架构】Match3DRuntimeProfile收口计划-2026-06-03.md。

公开作品分类选项、搜索、跨来源去重、今日筛选、排行排序和时间戳解析收口到 src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts，规则见 【前端架构】PublicGalleryViewModel收口计划-2026-06-03.md。

公开作品的玩法类型 label、公开作者 lookup 与游玩 / 改造 / 点赞等紧凑计数格式收口到 src/components/rpg-entry/rpgEntryWorldPresentation.ts，规则见 【前端架构】PublicWorkPresentation收口计划-2026-06-03.md。

推荐 feed 的公开作品去重、普通内容过滤、active 窗口与上一条 / 下一条回环选择也收口到 src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts，规则见 【前端架构】RecommendFeedViewModel收口计划-2026-06-03.md。

移动端推荐首页 swipe deck 的拖拽阈值、offset clamp、commit 方向、rail class 和分享文案收口到 src/components/rpg-entry/rpgEntryRecommendSwipeDeckModel.ts，规则见 【前端架构】RecommendSwipeDeckModel收口计划-2026-06-03.md。

排行频道的默认 tab、tab 文案、空态文案、排序字段与指标 label/value 收口到 src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts，规则见 【前端架构】RankingViewModel收口计划-2026-06-03.md。

每日任务卡片与任务中心弹窗的任务选择、进度、状态标签和按钮文案收口到 src/components/rpg-entry/rpgEntryProfileTaskViewModel.ts，规则见 【前端架构】ProfileTaskViewModel收口计划-2026-06-03.md。

个人数据卡、钱包 chip 与“玩过”弹窗的计数、时长、作品类型和作品号展示收口到 src/components/rpg-entry/rpgEntryProfileDashboardPresentation.ts，规则见 【前端架构】ProfileDashboardPresentation收口计划-2026-06-03.md。

个人资金展示的账单来源、金额正负号、余额兜底、充值价格、商品主值和会员摘要收口到 src/components/rpg-entry/rpgEntryProfileFundsViewModel.ts，规则见 【前端架构】ProfileFundsViewModel收口计划-2026-06-03.md。

推荐阅读顺序

1. 先看 经验沉淀，快速建立这个项目的开发共识。
2. 再看 工程审查总览 和 文本审计总览，了解当前风险。
3. 需要排期时看 规划与优先级，创作链路相关任务优先看创作流程统一总计划。
4. 需要补方案时进入 系统设计 / 技术方案；涉及后端先看 当前后端实现基线，涉及生产发布链路先看 生产部署计划，涉及 SpacetimeDB 表结构变更时再看 表结构变更约束。
5. 需要对齐目标边界时再进入 PRD。

分类规则

• experience/：偏方法论、交接经验、长期有效的开发结论。
• audits/：偏“现状扫描 / 问题定位 / 是否达标”的审查类文档。
• design/：偏玩法机制、叙事关系、系统结构设计。
• technical/：偏技术选型、实现路线、竞品/产品形态拆解。
• planning/：偏阶段优先级与推进顺序。
• reference/：偏目录、速查、检索辅助。
• tracking/：偏埋点原始事实和聚合投影查询，不放任务进度或钱包对账。
• operations/：偏后台运营核查、对账和排障查询。

文档命名规则

后续新增的 Markdown 文档文件名必须以分类标签开头，格式为 【标签名】中文标题-日期.md。标签用于跨目录检索，不替代上面的目录分类；历史文档不要求批量重命名，除非本次任务明确涉及该文档。