1

2026-05-01 22:16:01 +08:00
parent 8d46c05129
commit 33dd105630
36 changed files with 1999 additions and 236 deletions
--- a/docs/technical/LLM_MODEL_ROUTING_RPG_AND_CREATION_2026-04-30.md
+++ b/docs/technical/LLM_MODEL_ROUTING_RPG_AND_CREATION_2026-04-30.md
@@ -39,6 +39,8 @@
 - protocol: `/responses`
 - web_search: 开启时映射为 `tools: [{ "type": "web_search", "max_keyword": 3 }]`

+联网搜索是模板创作的增强能力，不是 Agent 对话主链的硬依赖。若上游 Responses SSE 返回 `ToolNotOpen` 或“账号未开通 web search”类错误，`creation_agent_llm_turn` 必须使用同一 system/user prompt 自动降级为无联网搜索重试一次；只有重试仍失败时才向玩法层返回“生成失败”。这样 RPG Agent、大鱼 Agent、拼图 Agent 都能在未开通搜索插件的环境中继续完成基础 JSON turn。
+
 覆盖入口：

 1. `creation_agent_llm_turn.rs`
@@ -74,6 +76,7 @@ Responses 非流式解析优先读取 `output_text`，再兼容 `output[].conten
 1. RPG 运行时 LLM 请求在代码层显式带 `doubao-seed-character-251128`。
 2. 创作模板 LLM 请求在代码层显式带 `deepseek-v3-2-251201` 与 Responses 协议。
 3. `platform-llm` 单测覆盖 Responses 非流式、Responses SSE、Responses web_search tools 请求体。
-4. `cargo test -p platform-llm --manifest-path server-rs/Cargo.toml` 通过。
-5. `cargo test -p api-server creation_agent_llm_turn --manifest-path server-rs/Cargo.toml` 通过。
-6. 修改后按项目约束使用 `npm run api-server:maincloud` 重新启动后端，并执行相应自动测试。
+4. `api-server` 单测覆盖创作 Agent 对 `ToolNotOpen` / 未开通 web search 错误的识别，确保可触发无搜索重试。
+5. `cargo test -p platform-llm --manifest-path server-rs/Cargo.toml` 通过。
+6. `cargo test -p api-server creation_agent_llm_turn --manifest-path server-rs/Cargo.toml` 通过。
+7. 修改后按项目约束使用 `npm run api-server:maincloud` 重新启动后端，并执行相应自动测试。
--- a/docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md
+++ b/docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md
@@ -0,0 +1,33 @@
+# 新建作品入口配置说明 2026-05-01
+
+## 背景
+
+创作中心顶部“新建作品”入口和平台创作类型弹层都依赖同一组玩法模板。此前入口开放状态、隐藏状态和中文文案集中写在 `src/components/platform-entry/platformEntryCreationTypes.ts` 与入口组件中，后续切换玩法开放节奏时容易出现多个入口不一致。
+
+## 落地规则
+
+1. 新建作品入口配置统一放在 `src/config/newWorkEntryConfig.ts`。
+2. `visible` 控制玩法是否展示在新建作品入口和创作类型弹层中。
+3. `open` 控制玩法是否允许点击创建；`open: false` 时入口保持展示但禁用。
+4. `title`、`subtitle`、`badge` 控制玩法卡片文案。
+5. `startCard` 控制创作中心顶部新建作品模块的标题、辅助文案和移动端角标文案。
+6. `typeModal` 控制平台创作类型弹层标题和描述。
+7. 入口排序仍遵循“可创建玩法在前，未开放玩法在后”；同组内部沿用配置顺序。
+
+## 当前状态
+
+| 玩法 | 展示 | 开放 | 说明 |
+| --- | --- | --- | --- |
+| 角色扮演 | 是 | 是 | 点击后进入 RPG Agent 共创工作台 |
+| 大鱼吃小鱼 | 否 | 是 | 功能仍保留，不在新建作品入口展示 |
+| 拼图 | 是 | 是 | 当前唯一可见且可创建入口 |
+| 抓大鹅 | 是 | 否 | 保留入口，显示敬请期待 |
+| AIRP | 是 | 否 | 保留入口，显示敬请期待 |
+| 视觉小说 | 是 | 否 | 保留入口，显示敬请期待 |
+
+## 验收
+
+1. 修改 `src/config/newWorkEntryConfig.ts` 后，创作中心顶部卡带和平台创作类型弹层应同步变化。
+2. 隐藏玩法不触发入口预加载，也不出现在新建作品入口中。
+3. 未开放玩法点击态保持禁用，不应进入鉴权或创建会话链路。
+4. 已开放玩法点击后必须进入对应创建链路；若用户未登录，先走登录保护。
--- a/docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md
+++ b/docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md
@@ -0,0 +1,69 @@
+# 拼图 APIMart 图片模型路由接入 2026-05-01
+
+## 背景
+
+拼图创作已收口为填表式流程，首图生成和结果页关卡重新生成都由 `server-rs/crates/api-server/src/puzzle.rs` 执行外部图片 I/O，再把正式图写入 OSS 与 SpacetimeDB。新的模型选择只影响图片生成上游，不改变 SpacetimeDB 表结构、拼图草稿结构或前端运行时规则。
+
+本轮参考 APIMart 文档：
+
+1. `https://docs.apimart.ai/cn/api-reference/images/gpt-image-2/generation`
+2. `https://docs.apimart.ai/cn/api-reference/images/gemini-3.1-flash/generation`
+
+两条文档均指向 OpenAI 兼容风格的图片生成入口：`POST https://api.apimart.ai/v1/images/generations`，头部使用 `Authorization: Bearer {APIMART_API_KEY}`。请求体至少包含 `model`、`prompt`、`n`、`size`。返回体按 OpenAI images 兼容格式优先读取 `data[].url`，若供应商返回异步任务结构，则继续按 `task_id` / `tasks/{task_id}` 轮询并提取图片 URL。
+
+## 模型选项
+
+拼图图片生成支持三个选项：
+
+| 前端显示 | 请求值 | 上游 |
+| --- | --- | --- |
+| 原模型 | `original` | 继续使用现有 DashScope 文生图 / 图生图链路 |
+| `gpt-image-2` | `gpt-image-2` | APIMart `/v1/images/generations` |
+| `nanobanana2` | `gemini-3.1-flash-image-preview` | APIMart `/v1/images/generations` |
+
+默认值为 `original`。前端只负责展示和传递所选模型，不能把模型路由逻辑、上游请求体拼装或 API Key 暴露到浏览器。
+
+## 前端交互
+
+1. 拼图创作表单的“画面描述”输入框左下角显示当前调用模型。
+2. 拼图结果页关卡详情的“画面描述”输入框左下角同样显示当前调用模型。
+3. 点击模型标识弹出轻量选择菜单，支持 `原模型`、`gpt-image-2`、`nanobanana2` 三项。
+4. 菜单只是模型选择控件，不写入说明性规则文案。
+5. 参考图入口继续在画面描述输入框右下角，模型选择在左下角，两者不得遮挡文本。
+6. 表单创建 session、自动保存表单草稿、首图生成失败重试时都要保留当前模型选择。
+7. 结果页关卡重新生成时将当前模型随 `generate_puzzle_images` action 传给后端。
+
+## 后端路由
+
+1. `CreatePuzzleAgentSessionRequest` 与 `ExecutePuzzleAgentActionRequest` 增加可选 `imageModel` 字段；该字段不进入 SpacetimeDB reducer 输入结构。
+2. `compile_puzzle_draft_with_initial_cover` 与 `generate_puzzle_image_candidates` 增加图片模型参数。
+3. `imageModel` 归一化规则：
+   - 空值、`original` 或未知值统一回落为原 DashScope 链路；
+   - `gpt-image-2` 走 APIMart；
+   - `gemini-3.1-flash-image-preview` 走 APIMart，前端显示名为 `nanobanana2`。
+4. APIMart 文生图和图生图共用 `POST /v1/images/generations`。有参考图时，后端将参考图 Data URL 作为 `image_urls` 数组传入；若上游不接受该字段，错误按上游失败返回，不在前端降级伪造结果。
+5. APIMart 尺寸使用文档要求的比例写法 `1:1`；原 DashScope 继续使用像素写法 `1024*1024`。`gemini-3.1-flash-image-preview` 额外带 `resolution = "1K"`，对齐约 1024px 的拼图正方形素材。
+6. APIMart 生成成功后仍下载远程图片，沿用现有 OSS 私有对象、`asset_object` 和 `asset_entity_binding` 写入流程。
+7. APIMart 错误统一映射为 `502 UPSTREAM_ERROR`，`details.provider = "apimart"`，保留上游状态码、业务 message 和截断后的 raw excerpt。
+
+## 环境变量
+
+新增服务端环境变量：
+
+```text
+APIMART_BASE_URL="https://api.apimart.ai/v1"
+APIMART_API_KEY="YOUR_APIMART_API_KEY"
+APIMART_IMAGE_REQUEST_TIMEOUT_MS=180000
+```
+
+`APIMART_API_KEY` 只能存在于本地或部署环境，不写入 Git 跟踪文件。若选择 APIMart 模型但缺少 key，后端返回服务不可用错误，前端展示现有错误面板。
+
+## 验收
+
+1. 创作表单和关卡详情的画面描述框左下角能切换 `原模型`、`gpt-image-2`、`nanobanana2`。
+2. 点击“生成草稿”时，后端首图生成使用当前表单选择的模型。
+3. 点击“生成画面 / 重新生成画面”时，后端当前关卡图片生成使用关卡详情选择的模型。
+4. 选择 `original` 时，现有 DashScope 请求体、尺寸和错误处理保持兼容。
+5. 选择 APIMart 模型时，请求 `POST {APIMART_BASE_URL}/images/generations`，使用 `Authorization: Bearer {APIMART_API_KEY}`，`model` 等于请求值，`size = 1:1`。
+6. 不改 SpacetimeDB 表结构，因此无需更新 `migration.rs` 或重新生成 bindings。
+7. 后端改动后运行对应 Rust 测试，并按项目约束用 `npm run api-server:maincloud` 重启验证。
--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -5,6 +5,8 @@
 ## 文档列表

 - [PRODUCT_NAMING_BAIMENG_RENAME_2026-05-01.md](./PRODUCT_NAMING_BAIMENG_RENAME_2026-05-01.md)：冻结当前对外中文命名，产品展示名统一为“百梦”，消费单位为“光点”，公开账号标识为“百梦号”，创作侧称谓为“百梦主”。
+- [NEW_WORK_ENTRY_CONFIG_2026-05-01.md](./NEW_WORK_ENTRY_CONFIG_2026-05-01.md)：记录新建作品入口开放状态、隐藏状态和展示文案统一收口到 `src/config/newWorkEntryConfig.ts` 的配置规则。
+- [PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md](./PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md)：记录拼图图片生成接入 APIMart `gpt-image-2`、`gemini-3.1-flash-image-preview`，以及画面描述框内模型切换与后端路由边界。
 - [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)：冻结 SpacetimeDB 表结构变更约束、自动迁移可接受范围、冲突后的系统行为，以及保留旧数据的增量迁移流程；凡涉及 `spacetime publish`、表字段调整或 `migration.rs` 对齐时优先参考。
 - [SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md](./SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md)：记录本地 standalone 启动时报 `mismatched database identity` 的 root-dir/replica 数据残留根因、备份重建步骤和脚本诊断口径。
 - [LLM_MODEL_ROUTING_RPG_AND_CREATION_2026-04-30.md](./LLM_MODEL_ROUTING_RPG_AND_CREATION_2026-04-30.md)：冻结 RPG 运行时剧情推理使用 `doubao-seed-character-251128` 的 `/chat/completions`，以及所有模板创作大模型推理使用 `deepseek-v3-2-251201` 的 `/responses`。