1

docs/technical/AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md

@@ -115,3 +115,24 @@
 2. 该失败只代表登录方式配置探测失败，不代表登录功能不可用，因此不把 `读取登录方式失败` 写入登录弹窗错误条。
 3. 登录弹窗仍展示密码登录表单，玩家可继续登录后进入创作链路。
 4. 本地仍需要启动 `api-server`，否则后续 `POST /api/auth/entry` 等真实登录请求无法完成。
+
+## 9. 2026-05-07 本地短信入口恢复记录
+
+如果登录弹窗里短信登录页签“像是被删了”，先不要改前端表单，优先检查本地登录方式探测结果：
+
+1. 仓库根目录 `.env.local` 里必须显式保留 `SMS_AUTH_ENABLED=true`。
+2. 本地启动请优先使用 `npm run api-server`、`npm run dev:rust` 或 `npm run dev`，这些脚本会按“shell 环境优先、`.env.local` 覆盖 `.env`”合并配置。
+3. 若 `GET /api/auth/login-options` 只返回 `["password"]`，说明短信入口没有被服务端配置打开，前端只是按 contract 正常降级。
+4. 当 `SMS_AUTH_ENABLED=true` 生效时，`GET /api/auth/login-options` 至少应返回 `["phone", "password"]`，短信登录页签才会重新出现。
+
+## 10. 2026-05-07 前端代理端口错配修复记录
+
+如果 Rust API 直连返回 `["phone", "password"]`，但从前端域名请求 `GET /api/auth/login-options` 返回 `500`，短信页签同样会消失。此时不是登录 UI 被删除，而是 `AuthGate` 按第 5.3 节降级成 `["password"]`。
+
+本地排查顺序固定为：
+
+1. 先请求 `http://127.0.0.1:3000/api/auth/login-options`，确认前端代理是否成功返回 JSON。
+2. 再请求当前 Rust API 目标，例如 `http://127.0.0.1:3100/api/auth/login-options` 或 `http://127.0.0.1:8082/api/auth/login-options`。
+3. 若直连 API 成功而 3000 返回 `500`，检查 `RUST_SERVER_TARGET`、`GENARRATIVE_API_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET` 是否指向仍在监听的 API 端口。
+4. `npm run dev` / `npm run dev:rust` 完整栈默认由脚本计算 API 端口；加载 `.env.local` 给后端使用后，脚本必须重新固定 `RUST_SERVER_TARGET`，避免 `.env.local` 中的旧代理目标覆盖本次启动的实际 API 端口。
+5. `npm run dev:web` 只启动前端，不会自动拉起 Rust API；如果单独使用它，必须同时确认其打印的 backend target 已有 `api-server` 正在监听。

docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md

@@ -2,17 +2,18 @@
 
 ## 背景
 
-创作中心顶部“新建作品”入口和平台创作类型弹层都依赖同一组玩法模板。此前入口开放状态、隐藏状态和中文文案集中写在 `src/components/platform-entry/platformEntryCreationTypes.ts` 与入口组件中，后续切换玩法开放节奏时容易出现多个入口不一致。
+创作中心的模板 Tab、平台创作类型弹层和旧“新建作品”卡片配置都依赖同一组玩法模板。此前入口开放状态、隐藏状态和中文文案集中写在 `src/components/platform-entry/platformEntryCreationTypes.ts` 与入口组件中，后续切换玩法开放节奏时容易出现多个入口不一致。
 
 ## 落地规则
 
 1. 新建作品入口配置统一放在 `src/config/newWorkEntryConfig.ts`。
-2. `visible` 控制玩法是否展示在新建作品入口和创作类型弹层中。
+2. `visible` 控制玩法是否展示在创作 Tab 模板入口、新建作品入口和创作类型弹层中。
 3. `open` 控制玩法是否允许点击创建；`open: false` 时入口保持展示但禁用。
 4. `title`、`subtitle`、`badge` 控制玩法卡片文案。
-5. `startCard` 控制创作中心顶部新建作品模块的标题、辅助文案和移动端角标文案。
+5. `startCard` 控制旧创作中心顶部新建作品模块的标题、辅助文案和移动端角标文案；当前创作 Tab 首屏标题固定在 `PlatformEntryFlowShellImpl.tsx`，不再由 `startCard` 控制。
 6. `typeModal` 控制平台创作类型弹层标题和描述。
 7. 入口排序仍遵循“可创建玩法在前，未开放玩法在后”；同组内部沿用配置顺序。
+8. `creative-agent` 可以继续保留运行链路，但默认 `visible: false`，不出现在创作 Tab 模板入口。
 
 ## 当前状态
 
@@ -20,16 +21,19 @@
 | --- | --- | --- | --- |
 | 角色扮演 | 否 | 是 | 暂时从创作端入口下线，既有链路与作品能力保留 |
 | 大鱼吃小鱼 | 否 | 是 | 功能仍保留，不在新建作品入口展示 |
-| 拼图 | 是 | 是 | 点击后进入拼图 Agent 共创工作台 |
+| 拼图 | 是 | 是 | 创作 Tab 默认选中并内嵌展示拼图创作表单，提交后进入拼图草稿生成 |
 | 抓大鹅 | 否 | 是 | 暂时从创作端入口下线，既有链路与作品能力保留 |
 | 方洞挑战 | 是 | 是 | 点击后进入方洞挑战 Agent 共创工作台，支持草稿、结果页、发布、试玩、作品架与广场 |
 | AIRP | 是 | 否 | 保留入口，显示敬请期待 |
-| 视觉小说 | 是 | 否 | 保留入口，显示敬请期待 |
+| 视觉小说 | 是 | 是 | 点击后进入视觉小说创作工作台 |
+| 智能创作 | 否 | 是 | 入口隐藏，既有 `creative-agent` 链路保留 |
 
 ## 验收
 
-1. 修改 `src/config/newWorkEntryConfig.ts` 后，创作中心顶部卡带和平台创作类型弹层应同步变化。
+1. 修改 `src/config/newWorkEntryConfig.ts` 后，创作 Tab 模板入口、创作中心顶部卡带和平台创作类型弹层应同步变化。
 2. 隐藏玩法不触发入口预加载，也不出现在新建作品入口中。
 3. 未开放玩法点击态保持禁用，不应进入鉴权或创建会话链路。
 4. 已开放玩法点击后必须进入对应创建链路；若用户未登录，先走登录保护。
-5. 方洞挑战作品发布后应生成 `SH-` 作品号，并能从作品架、广场详情和试玩 runtime 回到同一作品详情。
+5. 创作 Tab 首屏应显示“10分钟创作一个精品互动玩法”，并默认展示拼图创作表单。
+6. 智能创作入口隐藏后，不应出现“Hi, 朋友”“问一问百梦”或“一句话生成闪应用”等旧首页入口。
+7. 方洞挑战作品发布后应生成 `SH-` 作品号，并能从作品架、广场详情和试玩 runtime 回到同一作品详情。

docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md

@@ -408,7 +408,7 @@ WASM_SOURCE="${CARGO_TARGET_DIR}/wasm32-unknown-unknown/release/spacetime_module
 并发与清理规则：
 
 - 同一个 Rust 构建 Job 建议使用 `disableConcurrentBuilds()`，避免同一组件的多个 release 构建同时写入同一最终产物路径。
-- 如果 Linux agent 未安装 `sccache`，应先运行 `Genarrative-Server-Provision` 补齐缓存工具；Rust 构建流水线仍必须自动取消 `RUSTC_WRAPPER`，回退到直接使用 `rustc`，不能因为缺少可选缓存工具阻断真实构建。
+- 如果 Linux/Windows agent 未安装 `sccache`，或 `sccache --version` 无法实际执行，应先补齐缓存工具；Rust 构建流水线仍必须自动取消 `RUSTC_WRAPPER`，回退到直接使用 `rustc`，不能因为缺少可选缓存工具阻断真实构建。
 - 生产发布流水线只能消费 `build/<version>/` 或 Jenkins 归档产物，不允许从共享 `cargo-target` 目录直接发布。
 - `SCCACHE_CACHE_SIZE` 必须设置上限，避免编译缓存无限增长。
 - 对 `/var/cache/genarrative-build/*/cargo-target` 或数据盘对应目录配置定期清理，建议保留最近 14 到 30 天。

docs/technical/PUZZLE_TEMPLATE_FORM_AND_GPT_IMAGE_SKILL_2026-05-03.md

@@ -2,44 +2,53 @@
 
 ## 背景
 
-拼图创作入口已经从对话式 Agent 收口为填表式表单。本次改版目标是让“点击拼图创作”后的表单更接近图像创作工具的单屏体验：先选创作模板，再补充提示词，最后直接生成首关草稿与首张拼图图。
+拼图创作入口已经从对话式 Agent 收口为填表式表单。本次改版目标是让“点击拼图创作”后的表单更接近图像创作工具的单屏体验：优先上传参考图或填写画面描述，然后直接生成首关草稿与首张拼图图。2026-05-07 起，入口表单删除 Template 模块，模板参考图只保留为历史资产，不再作为表单首屏交互。
 
 ## 落地范围
 
 1. `src/components/puzzle-agent/PuzzleAgentWorkspace.tsx`
-   - 改为顶部标题、模板横滑区、大输入框、底部操作区的布局。
+   - 改为顶部标题、超大参考图上传区、大输入框、底部操作区的布局。
    - 保留参考图上传、模型切换和生成草稿。
+   - 删除 Template 模块与模板卡切换入口。
    - 不再提供输入框底部的 `try` 示例入口。
 2. `src/components/puzzle-agent/puzzleCreationTemplates.ts`
-   - 新增拼图创作模板数据。
-   - 模板来源按社交、热点、职场学习、电商、治愈、营销、儿童教育等场景抽样。
-   - 点击模板后把模板提示词写入画面描述。
+   - 保留历史拼图创作模板数据，当前表单不再消费。
+   - 后续若重新开放模板入口，必须先更新本文档和移动端首屏验收。
 3. `public/puzzle-creation-templates/`
-   - 存放模板样例图。
-   - 样例图只用于创作模板缩略图，不作为正式拼图作品资产。
-4. `.codex/skills/gpt-image-2-apimart/`
+   - 存放历史模板样例图。
+   - 样例图不作为正式拼图作品资产，当前也不再出现在拼图入口表单。
+4. `public/creation-type-references/`
+   - 存放平台创作入口和玩法类型弹层的参考图。
+   - 每个玩法一个参考图，首版用于视觉识别，不承载规则说明。
+   - 当前创作 Tab 顶部玩法卡带必须直接渲染这些图片，避免参考图只出现在隐藏弹层里。
+5. `.codex/skills/gpt-image-2-apimart/`
    - 封装仓库内 `gpt-image-2` 的 APIMart OpenAI 兼容调用流程。
    - Skill 默认读取本地环境变量，不把密钥写入代码、文档或前端。
 
 ## UI 规则
 
-1. 顶部只展示“创建拼图”和轻量状态标识，不写玩法规则说明。
-2. 模板区横向滚动，移动端优先；每个模板卡包含样例图、短标题和选中态。
-3. 点击模板时：
-   - 立即选中该模板。
-   - 如果输入框为空，直接填入模板提示词。
-   - 如果输入框已有内容，替换为该模板提示词，避免追加后变得冗长。
+1. 顶部主标题展示“想做个什么玩法？”和轻量状态标识，不写玩法规则说明。
+2. 上传拼图图片区优先占据首屏左侧/上方的大块区域，移动端也必须完整露出。
+   - 上传区自身就是图片卡片，不再额外封装为 `platform-subpanel` 模块壳。
+   - 亮色主题下上传卡片必须使用白色或暖浅色卡面，不得显示整块黑色底。
+   - 上传卡片固定为 1:1 正方形，避免拼图主画面在首屏出现非正方形预期。
+   - 上传卡片底部不再叠加文件名 bar；卡片下方只保留 `点击上传拼图图片` 纯文字入口。
+   - 上传卡片上方固定展示 `拼图画面` 标题。
+   - 叠在上传卡片上的 `AI重绘` 和图标必须和卡面保持足够对比，避免浅色主题重映射后不可读。
+3. 画面描述输入框高度约为旧版大输入框的 1/2，避免移动端把上传参考图和提交区挤出首屏。
 4. 输入区保留：
-   - 参考图上传按钮。
+   - 上传拼图图片按钮。
    - 图片模型切换按钮。
 5. 输入区不保留：
    - `try` 文本。
    - 示例 prompt chip。
+   - 画面描述输入框默认提示词或占位示例。
    - 玩法规则说明。
+   - Template 模块和模板卡切换。
 
-## 模板抽样
+## 历史模板抽样
 
-首批模板不追求覆盖图二所有条目，而是选择高频且适合拼图主图的代表项：
+以下模板曾用于表单 Template 模块。2026-05-07 后入口表单不再展示这些模板，列表仅作为历史资产索引：
 
 1. 情侣合照拼图
 2. 家庭纪念拼图
@@ -76,12 +85,45 @@ n = 1
 
 本次 Skill 只封装生成样例图和研发复用流程，不改变正式后端接口、扣费、OSS、SpacetimeDB 写入和发布链路。
 
+## 2026-05-07 AI 重绘与上传直用
+
+拼图入口上传区右上角新增 `AI重绘` 开关，默认打开；未上传拼图图片前不显示开关，上传成功后才显示。
+
+1. `AI重绘=true`
+   - 上传区文案为 `点击上传拼图图片`，上传图作为生图参考图。
+   - 未上传图片时，输入框标题为 `画面描述`。
+   - 已上传图片时，输入框标题为 `画面AI重绘要求（提示词）`。
+   - 展示图片模型切换。
+   - `compile_puzzle_draft` 携带 `aiRedraw: true`，继续走 APIMart 生图与 `PUZZLE_IMAGE_GENERATION_POINTS_COST = 2` 扣费链路。
+   - 生成按钮展示 `消耗2光点`。
+2. `AI重绘=false`
+   - 隐藏画面描述输入框和模型切换。
+   - 必须上传拼图图片，按钮不展示 `消耗2光点`。
+   - `compile_puzzle_draft` 携带 `aiRedraw: false`，后端只编译草稿和生成首关名，不调用 APIMart，不进入光点扣费 wrapper。
+   - 后端把上传图片 Data URL 按拼图资产路径持久化，构造 `sourceType=uploaded` 的候选图并直接选为第一关正式图。
+3. 上传裁剪
+   - 前端读取上传图原始宽高。
+   - 非 1:1 图片必须先弹出正方形裁剪工具，裁剪完成后再进入表单状态和提交 payload。
+   - 裁剪输出仍按参考图体积预算压缩，避免上传图撑爆 JSON body。
+
+契约字段同步：
+
+```ts
+CreatePuzzleAgentSessionRequest.aiRedraw?: boolean
+PuzzleAgentActionRequest.compile_puzzle_draft.aiRedraw?: boolean
+```
+
+Rust 共享契约使用 `ai_redraw: Option<bool>` 并按 camelCase 序列化为 `aiRedraw`。
+
 ## 验收
 
-1. 点击拼图创作后，表单首屏呈现模板横滑区和大输入框。
-2. 点击任一模板后，输入框填入该模板提示词。
-3. 输入框里没有 `try` 示例功能。
-4. 图片模型切换仍可打开并选择 `gpt-image-2` / `nanobanana2`。
-5. 模板样例图文件存在，并能在创作表单缩略图中显示。
-6. gpt-image-2 Skill 校验通过，且脚本 dry-run 能输出计划请求而不泄露密钥。
-7. `npm run check:encoding` 通过。
+1. 点击拼图创作后，表单首屏呈现大参考图区和半高文本输入框。
+2. 输入框里没有 `try` 示例功能。
+3. 图片模型切换仍可打开并选择 `gpt-image-2` / `nanobanana2`。
+4. 历史模板样例图文件可保留，但不出现在拼图入口表单。
+5. 当前创作 Tab 顶部的拼图、方洞挑战、视觉小说和 AIRP 卡片能看到对应 `creation-type-references` 图片。
+6. 默认 `AI重绘` 打开时，无图状态展示 `画面描述` 与 `消耗2光点`；上传图片后输入框标题改为 `画面AI重绘要求（提示词）`。
+7. 关闭 `AI重绘` 后隐藏画面描述输入框，生成按钮不展示 `消耗2光点`，后端直接应用上传图片为第一关图片。
+8. 上传非 1:1 图片时必须先完成正方形裁剪。
+9. gpt-image-2 Skill 校验通过，且脚本 dry-run 能输出计划请求而不泄露密钥。
+10. `npm run check:encoding` 通过。

docs/technical/README.md

@@ -6,6 +6,9 @@
 
 - [RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md](./RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md)：记录 `server-rs` Cargo 依赖集中配置口径，第三方版本和 workspace 内部 crate path 统一维护在根 `server-rs/Cargo.toml`，成员 crate 只保留 feature/optional 差异。
 - [API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md](./API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md)：冻结 api-server 外部服务配置边界，公共服务 URL 可保留代码默认值，非公共模型名和私有网关 URL 统一通过环境变量注入。
+- [CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md](./CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md)：冻结基于 LangChain-Rust 的创意互动内容生成 Agent 技术方案，明确首版只支持拼图模板、必须显式展示模板选择和积分范围，通过拼图模块 Tool/模板协议填充同一份草稿字段，支持单关卡与多关卡图片生成、立即试玩、表单化编辑和 Agent 自然语言修订草稿字段。
+- [VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md](./VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md)：记录视觉小说模板 `VN-03` Prompt / LLM 工具落地，包含创作底稿 Prompt、运行时 GM Prompt、repair Prompt、工具参数 schema、Responses 请求口径和定向验证结果。
+- [VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md](./VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md)：记录视觉小说模板 `VN-13` 实现收口、当前正式入口、表目录、路由、作品 / 运行 / 资产和负向扫描口径。
 - [PROFILE_TASK_AND_TRACKING_SYSTEM_2026-05-03.md](./PROFILE_TASK_AND_TRACKING_SYSTEM_2026-05-03.md)：冻结个人任务与埋点系统首版方案，明确 `tracking_event`、`tracking_daily_stat`、`profile_task_config`、任务进度、领奖记录和光点钱包流水的边界。
 - [SQUARE_HOLE_IMAGE_SLOT_AND_RUNTIME_INTERACTION_FIX_2026-05-06.md](./SQUARE_HOLE_IMAGE_SLOT_AND_RUNTIME_INTERACTION_FIX_2026-05-06.md)：记录方洞挑战结果页图片槽位局部生成、洞口图历史素材、运行态拖拽与点击投放交互的修正口径。
 - [MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md](./MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md)：冻结 Maincloud 历史残留引用禁用策略，明确后续不得新增、运行或引用 `api-server:maincloud`、`GENARRATIVE_SPACETIME_MAINCLOUD_*` 和相关测试/文档口径。
@@ -87,6 +90,7 @@
 - [PUZZLE_IMAGE_AND_FRONTEND_RULES_ALIGNMENT_2026-04-29.md](./PUZZLE_IMAGE_AND_FRONTEND_RULES_ALIGNMENT_2026-04-29.md)：记录拼图生成图片回到 1:1，运行时拖动、交换、合并与拆分由前端即时裁决，以及移动端棋盘贴近屏幕边缘的落地边界。
 - [PUZZLE_FORM_CREATION_FLOW_2026-04-29.md](./PUZZLE_FORM_CREATION_FLOW_2026-04-29.md)：冻结拼图填表式创作入口、初始表单自动保存草稿、生成前退出后的表单恢复，以及草稿编译/首图生成的前后端边界。
 - [PUZZLE_PICTURE_ONLY_CREATION_AND_AI_TAGS_2026-05-03.md](./PUZZLE_PICTURE_ONLY_CREATION_AND_AI_TAGS_2026-05-03.md)：记录拼图入口只填写画面描述、首关名默认作品名、作品描述和标签初始为空、AI 生成 6 个作品标签以及发布前校验的落地规则。
+- [PUZZLE_TEMPLATE_FORM_AND_GPT_IMAGE_SKILL_2026-05-03.md](./PUZZLE_TEMPLATE_FORM_AND_GPT_IMAGE_SKILL_2026-05-03.md)：记录拼图入口模板样例图与 gpt-image-2 Skill 约定，2026-05-07 起表单不再展示 Template 模块，改为大参考图区 + 大输入框的单屏布局。
 - [PUZZLE_LEADERBOARD_FRONTEND_LEVEL_AND_RPG_COMING_SOON_2026-04-30.md](./PUZZLE_LEADERBOARD_FRONTEND_LEVEL_AND_RPG_COMING_SOON_2026-04-30.md)：记录拼图第二关排行榜提交以前端当前关卡为准、不被 SpacetimeDB 旧 run 快照误杀，以及 RPG 创作入口改为敬请期待的落地边界。
 - [PUZZLE_NEXT_LEVEL_AND_SIMILAR_WORK_HANDOFF_2026-04-30.md](./PUZZLE_NEXT_LEVEL_AND_SIMILAR_WORK_HANDOFF_2026-04-30.md)：记录拼图通关后优先同作品下一关、无下一关时按 RPG/build 标签语义相似度返回三个候选作品，并在跨作品时只切换到候选作品第 1 张图、运行时关卡序号继续累进的落地规则。
 - [PUZZLE_FAILURE_EXTENSION_AND_SAVE_ARCHIVE_2026-05-01.md](./PUZZLE_FAILURE_EXTENSION_AND_SAVE_ARCHIVE_2026-05-01.md)：记录拼图失败后重新开始/付费续时，以及进入作品与过关后同步存档页投影的落地规则。
@@ -261,7 +265,7 @@
 - [CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md#93-工作包-c前端结果页与编辑器拆分](./CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md#93-%E5%B7%A5%E4%BD%9C%E5%8C%85-c%E5%89%8D%E7%AB%AF%E7%BB%93%E6%9E%9C%E9%A1%B5%E4%B8%8E%E7%BC%96%E8%BE%91%E5%99%A8%E6%8B%86%E5%88%86)：记录工作包 C 已完成的结果页壳层拆分、编辑器目标分发与 mapper 收口、角色资产工坊 section/workflow 拆分，以及仍保留的阶段性 shared 实现边界。
 - [CREATION_PAGE_MOBILE_UI_FIX_2026-04-21.md](./CREATION_PAGE_MOBILE_UI_FIX_2026-04-21.md)：创作页移动端底部 Tab、亮色主题 token 与滚动权责修复记录。
 - [RPG_FOUNDATION_DRAFT_EIGHT_ANCHOR_SEED_FIX_2026-04-25.md](./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_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md)：把外部仓库 TXT 模式完整迁入当前项目的冻结边界、模块映射、分阶段计划与验收清单。
+- [TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md](./TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md)：旧 TXT 模式迁移方案的历史参考；视觉小说模板最新落地口径以 PRD [`AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`](../prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md) 为准，不再按外部平台工程完整迁入执行。
 - [AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md](./AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md)：AI 生成角色形象与角色动画的技术路线。
 - [ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md](./ALIYUN_NPC_IMAGE_ANIMATION_EXPERIMENT_2026-04-07.md)：面向编辑器的阿里云 NPC 形象与动作实验方案，按 4 条生成链路对比。
 - [PIXELMOTION_TECHNICAL_BREAKDOWN_2026-04-04.md](./PIXELMOTION_TECHNICAL_BREAKDOWN_2026-04-04.md)：PixelMotion 产品形态与能力拆解。

docs/technical/SPACETIMEDB_TABLE_CATALOG.md

@@ -30,6 +30,7 @@ spacetime sql <db> "SELECT * FROM custom_world_gallery_entry"
 | 拼图 | `puzzle_agent_session`, `puzzle_agent_message`, `puzzle_work_profile`, `puzzle_event`, `puzzle_runtime_run`, `puzzle_leaderboard_entry` |
 | 抓大鹅 Match3D | `match3d_agent_session`, `match3d_agent_message`, `match3d_work_profile`, `match3d_runtime_run` |
 | 方洞挑战 | `square_hole_agent_session`, `square_hole_agent_message`, `square_hole_work_profile`, `square_hole_runtime_run` |
+| 视觉小说 | `visual_novel_agent_session`, `visual_novel_agent_message`, `visual_novel_work_profile`, `visual_novel_runtime_run`, `visual_novel_runtime_history_entry`, `visual_novel_runtime_event` |
 | 大鱼吃小鱼 | `big_fish_creation_session`, `big_fish_agent_message`, `big_fish_asset_slot`, `big_fish_event`, `big_fish_runtime_run` |
 | 资产 | `asset_object`, `asset_entity_binding`, `asset_event` |
 | AI 任务 | `ai_task`, `ai_task_stage`, `ai_text_chunk`, `ai_result_reference`, `ai_task_event` |
@@ -717,6 +718,78 @@ SELECT * FROM square_hole_runtime_run WHERE owner_user_id = '<user_id>' ORDER BY
 SELECT * FROM square_hole_runtime_run WHERE profile_id = '<profile_id>';
 ```
 
+## 视觉小说表
+
+> VN-13 复核：当前视觉小说首版只保留本节 6 张表；`visual_novel_runtime_history_entry` 和 `visual_novel_runtime_event` 均不得扩展成回放数据源。维护入口见 [视觉小说模板实现收口与交接说明](./VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md)。
+
+### `visual_novel_agent_session`
+
+- 作用：视觉小说创作 Agent 会话主表，保存创建起点、源资产、当前阶段、底稿 JSON、待执行 action 和发布 profile 指针。
+- 结构：`session_id PK: String`, `owner_user_id: String`, `source_mode: String`, `status: String`, `seed_text: String`, `source_asset_ids_json: String`, `current_turn: u32`, `progress_percent: u32`, `draft_json: String`, `pending_action_json: String`, `last_assistant_reply: String`, `published_profile_id: String`, `created_at: Timestamp`, `updated_at: Timestamp`。
+- 索引：`owner_user_id`。
+
+```sql
+SELECT * FROM visual_novel_agent_session WHERE session_id = '<session_id>';
+SELECT * FROM visual_novel_agent_session WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
+```
+
+### `visual_novel_agent_message`
+
+- 作用：视觉小说创作 Agent 消息流水，保存用户输入和模型回复。
+- 结构：`message_id PK: String`, `session_id: String`, `role: String`, `kind: String`, `text: String`, `created_at: Timestamp`。
+- 索引：`session_id`。
+
+```sql
+SELECT * FROM visual_novel_agent_message WHERE session_id = '<session_id>' ORDER BY created_at ASC;
+```
+
+### `visual_novel_work_profile`
+
+- 作用：视觉小说作品草稿 / 发布 profile 表，保存平台作品摘要字段、源资产引用、完整 `VisualNovelResultDraft` JSON、发布状态和游玩次数。
+- 结构：`profile_id PK: String`, `work_id: String`, `owner_user_id: String`, `source_session_id: String`, `author_display_name: String`, `work_title: String`, `work_description: String`, `tags_json: String`, `cover_image_src: String`, `source_asset_ids_json: String`, `draft_json: String`, `publication_status: String`, `publish_ready: bool`, `play_count: u32`, `created_at: Timestamp`, `updated_at: Timestamp`, `published_at: Option<Timestamp>`。
+- 索引：`owner_user_id`, `publication_status`。
+
+```sql
+SELECT * FROM visual_novel_work_profile WHERE profile_id = '<profile_id>';
+SELECT * FROM visual_novel_work_profile WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
+SELECT * FROM visual_novel_work_profile WHERE publication_status = 'published';
+```
+
+### `visual_novel_runtime_run`
+
+- 作用：视觉小说测试或正式运行态表，保存当前场景、阶段、可见角色、旗标、指标、可选项和运行快照 JSON。
+- 结构：`run_id PK: String`, `owner_user_id: String`, `profile_id: String`, `mode: String`, `status: String`, `current_scene_id: String`, `current_phase_id: String`, `visible_character_ids_json: String`, `flags_json: String`, `metrics_json: String`, `available_choices_json: String`, `text_mode_enabled: bool`, `snapshot_json: String`, `created_at: Timestamp`, `updated_at: Timestamp`。
+- 索引：`owner_user_id`, `profile_id`。
+
+```sql
+SELECT * FROM visual_novel_runtime_run WHERE run_id = '<run_id>';
+SELECT * FROM visual_novel_runtime_run WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
+SELECT * FROM visual_novel_runtime_run WHERE profile_id = '<profile_id>';
+```
+
+### `visual_novel_runtime_history_entry`
+
+- 作用：视觉小说运行时历史表，保存每轮玩家 / 模型 / 系统事实、step JSON 和快照哈希，用于继续体验与历史重生成边界；不是回放表。
+- 结构：`entry_id PK: String`, `run_id: String`, `owner_user_id: String`, `profile_id: String`, `turn_index: u32`, `source: String`, `action_text: String`, `steps_json: String`, `snapshot_before_hash: String`, `snapshot_after_hash: String`, `created_at: Timestamp`。
+- 索引：`run_id`, `owner_user_id`。
+
+```sql
+SELECT * FROM visual_novel_runtime_history_entry WHERE run_id = '<run_id>' ORDER BY turn_index ASC;
+SELECT * FROM visual_novel_runtime_history_entry WHERE owner_user_id = '<user_id>' ORDER BY created_at DESC;
+```
+
+### `visual_novel_runtime_event`
+
+- 作用：视觉小说运行时审计事件表，用于订阅端、BFF 或排障流程感知 run 事实；该表明确不是 replay、分享回放或片段回放数据源。
+- 可见性：`public event`。
+- 结构：`event_id PK: String`, `run_id: String`, `owner_user_id: String`, `profile_id: String`, `event_kind: String`, `client_event_id: String`, `history_entry_id: String`, `payload_json: String`, `occurred_at: Timestamp`。
+- 索引：`run_id`, `owner_user_id`。
+
+```sql
+SELECT * FROM visual_novel_runtime_event WHERE run_id = '<run_id>' ORDER BY occurred_at ASC;
+SELECT * FROM visual_novel_runtime_event WHERE owner_user_id = '<user_id>' ORDER BY occurred_at DESC;
+```
+
 ## 大鱼吃小鱼表
 
 ### `big_fish_creation_session`

docs/technical/TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md

@@ -2,6 +2,8 @@
 
 更新时间：`2026-04-20`
 
+> 2026-05-05 更新口径：本文保留为历史迁移参考。视觉小说模板后续落地以 [`../prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`](../prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md) 为准；冲突时不再迁入外部平台工程、不使用 `server-node` 作为新功能落点、不保留回放，统一接入 Genarrative `server-rs + Axum + SpacetimeDB` 与平台接口。
+
 ## 0. 文档目的
 
 这份执行方案用于指导 `Genarrative` 在**不改动外部 TXT 模式提示词正文、不改动外部 TXT 模式功能需求**的前提下，把下面两个仓库中已经跑通的 TXT 模式创作流程与运行机制完整迁入当前项目：

docs/technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md

@@ -0,0 +1,76 @@
+# 视觉小说模板实现收口与交接说明 2026-05-07
+
+## 1. 范围
+
+本文记录 `AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md` 的 `VN-13` 收口结果，作为视觉小说模板后续维护的一页式入口。
+
+本文只总结当前已经落地且需要长期遵守的实现边界，不再把视觉小说描述成外部 TXT 平台迁移，也不重复旧迁移方案里的临时讨论。
+
+## 2. 当前正式入口
+
+后续维护时优先看这些文档：
+
+1. [AI 原生视觉小说模板 PRD](../prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)
+2. [SpacetimeDB 表说明与查询目录](./SPACETIMEDB_TABLE_CATALOG.md)
+3. [视觉小说 VN-03 Prompt 与 LLM 工具实现说明](./VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md)
+4. [视觉小说 VN-11 负向扫描报告](../audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md)
+5. [视觉小说模板交接与维护经验](../experience/VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md)
+
+旧的 `TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md` 只保留历史参考意义，不再作为实现口径。
+
+## 3. 已收口的实现边界
+
+### 3.1 创作链路
+
+- 创作链统一走 `/api/creation/visual-novel/*`。
+- 入口、工作台、结果页和服务端 prompt 已围绕 `visual-novel` 模板闭环对齐。
+- `VisualNovelResultDraft`、`VisualNovelCreationSessionSnapshot` 等共享契约已经成型。
+
+### 3.2 运行链路
+
+- 运行链统一走 `/api/runtime/visual-novel/*`。
+- 运行时只认 typed step 和快照，不让前端从 `raw_text` 猜业务真相。
+- `visual_novel_runtime_history_entry` 只用于继续体验和历史重生成边界，不是回放表。
+
+### 3.3 数据链路
+
+- SpacetimeDB 首版只保留 6 张视觉小说表。
+- `visual_novel_runtime_event` 是 `public event` 审计事件表，不是 replay 数据源。
+- 表结构变化必须同步 `migration.rs`、`SPACETIMEDB_TABLE_CATALOG.md` 和 Rust bindings。
+
+### 3.4 作品与发布
+
+- 作品架、广场和分享都复用平台现有链路。
+- 公开作品码统一使用 `VN-` 前缀。
+- 发布后要刷新作品架和公开聚合。
+
+### 3.5 资产与登录态
+
+- 文档、封面、背景、角色和音乐都只保留平台资产对象引用。
+- 不保存大 Data URL、不走独立对象存储、不新增视觉小说私有存档系统。
+- 退出登录时要清空视觉小说私有 session、work、run 和错误状态。
+
+## 4. 长期维护规则
+
+1. 看到视觉小说相关改动，先确认是不是契约改动；如果是，先同步 TS / Rust shared contracts。
+2. 看到表结构改动，先同步 `migration.rs` 和表目录，再补 bindings。
+3. 看到资产链路改动，只改平台资产引用，不回退到本地路径或二进制直存。
+4. 看到运行时历史改动，只维护 typed history 和审计事件，不把它改成回放能力。
+5. 看到旧 TXT 文档时，只把它当历史来源，不把其中的平台工程目标重新带回实现。
+
+## 5. 验证口径
+
+收口后建议按下面顺序检查：
+
+```bash
+npm run check:encoding
+npm run check:visual-novel-vn11
+npm run typecheck
+
+cd server-rs
+cargo test -p shared-contracts
+cargo test -p module-visual-novel
+cargo check -p api-server
+```
+
+如果本轮没有改代码，只要编码检查和负向扫描通过，通常就说明 VN-13 的文档收口已经站稳。

docs/technical/VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md

@@ -0,0 +1,111 @@
+# 视觉小说 VN-03 Prompt 与 LLM 工具实现说明
+
+日期：`2026-05-05`
+
+## 1. 范围
+
+本文记录 `AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md` 中 `VN-03` 的工程落地口径。
+
+本次只实现视觉小说模板的 Prompt / LLM 工具层：
+
+1. 创作底稿生成 Prompt，目标输出 `VisualNovelResultDraft`。
+2. 运行时 GM Prompt，目标输出 `VisualNovelRuntimeStep[]`。
+3. 结构化 repair Prompt，用于解析失败后的后端修复。
+4. 创作 action 与图片生成 action 的工具参数 schema。
+5. `platform-llm` Responses 请求构造口径。
+
+本次不保存数据、不新增 HTTP 路由、不写前端 UI、不触碰 SpacetimeDB schema。
+
+## 2. 代码落点
+
+主要实现位于：
+
+1. `server-rs/crates/api-server/src/prompt/visual_novel.rs`
+2. `server-rs/crates/api-server/src/prompt/mod.rs`
+
+为了让当前工作树中已有的 creative-agent / puzzle 并行改动可继续编译，本次还补了两个编译闭口：
+
+1. `server-rs/crates/module-puzzle/Cargo.toml` 增加 `serde_json = "1"`。
+2. `server-rs/crates/platform-agent/src/puzzle_phase1_agent.rs` 给 `MockLangChainRustAgentExecutor` 补 `Debug` 派生。
+
+## 3. Prompt 约束
+
+### 3.1 创作底稿
+
+创作系统 Prompt 明确要求：
+
+1. 只输出一个 JSON 对象。
+2. 内容必须是中文视觉小说底稿。
+3. 补齐世界观、玩家身份、角色、场景、剧情阶段和开场。
+4. 角色必须有可生成立绘的 `appearance`。
+5. 场景必须有可生成背景图的 `description`。
+6. 不输出回放、商城、会员、后台、平台活动、促销、订单或独立账号字段。
+7. 不生成第二套存档、发布、钱包、广场或资产系统。
+
+### 3.2 运行时 GM
+
+运行时系统 Prompt 明确要求：
+
+1. 只输出 `VisualNovelRuntimeStep[]` JSON 数组。
+2. step 数量不超过输入的 `maxAssistantStepCountPerTurn`。
+3. 场景变化必须输出 `scene_change`。
+4. 旁白、对白、转场、选项、flag、metric 分别使用契约内 step 类型。
+5. 前端不得从 `raw_text` 猜业务 step。
+6. 不输出回放、录制、商城、会员、后台、平台活动或独立存档元数据。
+
+### 3.3 Repair
+
+repair Prompt 只负责把坏格式修成目标 JSON：
+
+1. `VisualNovelResultDraft`
+2. `VisualNovelRuntimeStep[]`
+
+repair 仍失败时，由后续 `VN-05` API 接入层返回可重试错误。
+
+## 4. LLM 请求口径
+
+视觉小说创作、运行和 repair 请求统一使用 `platform-llm`：
+
+1. model：`CREATION_TEMPLATE_LLM_MODEL`，当前为 `deepseek-v3-2-251201`。
+2. protocol：`LlmTextProtocol::Responses`。
+3. 创作底稿请求可按 API 配置开启 web search。
+4. 运行时 GM 与 repair 默认不开 web search，避免运行态引入外部噪声。
+
+## 5. 工具参数
+
+本次定义两个工具描述：
+
+1. `visual_novel_apply_creation_action`
+   - 支持 `generate_draft`、`patch_world`、`patch_character`、`patch_scene`、`patch_story_phase`、`compile_work_profile`。
+   - 只写回视觉小说底稿或编译平台 work profile 草稿。
+2. `visual_novel_generate_image_asset`
+   - 支持 `generate_scene_image`、`generate_character_image`。
+   - 输出应接后续平台资产引用，不保存二进制或大 Data URL。
+
+工具 schema 不包含 replay / Replay 字段。
+
+## 6. 验证结果
+
+已执行：
+
+```bash
+cargo test -p shared-contracts visual_novel --manifest-path server-rs/Cargo.toml
+cargo test -p module-puzzle creative_tools --manifest-path server-rs/Cargo.toml
+cargo test -p platform-agent puzzle_phase1_agent --manifest-path server-rs/Cargo.toml
+cargo test -p api-server prompt::visual_novel --manifest-path server-rs/Cargo.toml
+```
+
+结果：全部通过。
+
+## 7. 后续接入点
+
+`VN-05` 接 API Server 时直接复用：
+
+1. `build_visual_novel_creation_llm_request`
+2. `build_visual_novel_runtime_llm_request`
+3. `build_visual_novel_repair_llm_request`
+4. `parse_visual_novel_result_draft_fixture`
+5. `parse_visual_novel_runtime_steps_fixture`
+6. `visual_novel_tool_descriptors`
+
+若后续 `VN-01` 契约发生破坏性变更，必须同步更新本 Prompt 模块的 output contract、fixture 和解析测试。