GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: GenarrativeAI:199b44c18cc9fc3deb822e72b05a7d8996038f82
Branches Tags
GenarrativeAI:master GenarrativeAI:codex/puzzle-clear-template-runtime-fixes GenarrativeAI:codex/share-link-refactor GenarrativeAI:fix/jump-hop-image-gen GenarrativeAI:codex/tiaoyitiao GenarrativeAI:codex/oss-generated-image-cache GenarrativeAI:codex/external-generation-worker-scaling GenarrativeAI:codex/platform-creation-flow-polish GenarrativeAI:codex/sse-stream-architecture GenarrativeAI:release GenarrativeAI:codex/wechat-mini-program-virtual-payment GenarrativeAI:codex/unified-creation-flow-phase1
...
compare: GenarrativeAI:23ba2703b43cfb73f204fdcd5af614991bf797e1
Branches Tags
GenarrativeAI:codex/puzzle-clear-template-runtime-fixes GenarrativeAI:master GenarrativeAI:codex/share-link-refactor GenarrativeAI:fix/jump-hop-image-gen GenarrativeAI:codex/tiaoyitiao GenarrativeAI:codex/oss-generated-image-cache GenarrativeAI:codex/external-generation-worker-scaling GenarrativeAI:codex/platform-creation-flow-polish GenarrativeAI:codex/sse-stream-architecture GenarrativeAI:release GenarrativeAI:codex/wechat-mini-program-virtual-payment GenarrativeAI:codex/unified-creation-flow-phase1

6 Commits
199b44c18c ... 23ba2703b4

Author SHA1 Message Date
高物
23ba2703b4 Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative
Some checks failed
CI / verify (push) Has been cancelled
Details
2026-05-08 22:12:10 +08:00
高物
96df12cd15 1 2026-05-08 22:07:08 +08:00
高物
65c2b8cd79 Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative 2026-05-08 22:07:05 +08:00
高物
e410f7974e 1 2026-05-08 21:46:11 +08:00
高物
94975e4735 1 2026-05-08 20:48:29 +08:00
高物
abf1f1ebea 1 2026-05-08 11:44:42 +08:00
290 changed files with 47183 additions and 1524 deletions
Expand all files Collapse all files

1
.codex/skills/gpt-image-2-apimart/SKILL.md
View File

@@ -43,6 +43,7 @@ Default body:
"model": "gpt-image-2",
"prompt": "<prompt>",
"n": 1,
"official_fallback": true,
"size": "1:1"
}
```

2
.codex/skills/gpt-image-2-apimart/scripts/generate-template-samples.mjs
View File

@@ -237,6 +237,7 @@ async function generateOne(env, template, outDir) {
model: 'gpt-image-2',
prompt: buildPrompt(template),
n: 1,
official_fallback: true,
size: '1:1',
};
const payload = await fetchJson(
@@ -304,6 +305,7 @@ if (dryRun) {
model: 'gpt-image-2',
prompt: buildPrompt(template),
n: 1,
official_fallback: true,
size: '1:1',
},
})),

136
.hermes/shared-memory/decision-log.md
View File

@@ -16,6 +16,14 @@
---
## 2026-05-08 APIMart 接口统一携带 `official_fallback`
- 背景：APIMart 的图片生成和 Responses 接口在仓库内分散于 `api-server`、`platform-llm` 和本地 skill 脚本，若只修单点，容易出现不同入口的上游请求体不一致。
- 决策：凡是仓库内调用 APIMart 的 OpenAI 兼容接口，请求体统一携带 `official_fallback: true`；其中图片生成请求直接固定写入，`platform-llm` 的 APIMart GPT-5 client 通过显式开关开启，不默认扩散到 Ark 等其它 provider。
- 影响范围：`server-rs/crates/api-server/src/openai_image_generation.rs`、`server-rs/crates/api-server/src/puzzle.rs`、`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/platform-llm/src/lib.rs`、`.codex/skills/gpt-image-2-apimart/` 和相关技术文档。
- 验证方式：图片生成与 creative-agent APIMart 路径的单测都应断言 `official_fallback` 已写入请求 JSON；编码检查和相关 Rust 测试应持续通过。
- 关联文档：`docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md`、`docs/technical/RPG_IMAGE_GENERATION_GPT_IMAGE_2_MIGRATION_2026-05-02.md`、`docs/technical/CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md`。
## 2026-05-07 server-rs Cargo 依赖集中到 workspace
- 背景：`server-rs` 多 crate 已稳定成 DDD workspace，成员 `Cargo.toml` 中重复散写第三方版本和本地 path 依赖，升级 SpacetimeDB SDK、`serde`、`reqwest`、`tokio` 等依赖时容易漂移。
@@ -48,6 +56,134 @@
- 验证方式：未登录首次访问应展示新手引导；生成后只进入 1 关本地拼图；通关后登录保存应在当前用户拼图作品架出现草稿作品；不应产生 SpacetimeDB schema 变更。
- 关联文档：`docs/prd/FIRST_LAUNCH_PUZZLE_ONBOARDING_PRD_2026-05-05.md`。
## 2026-05-05 text-game 作为百梦幕间文字游戏模板接入
- 背景：团队希望参考 MOKU / 幕间类 AI 文游，设计可在百梦内落地的 AI 文字游戏模板，但不能把外部平台社区、支付、榜单、论坛、账号或私有存档迁入 Genarrative。
- 决策：新增 `text-game` 作为百梦 AI 原生文字游戏模板口径，展示名可用“幕间”或“幕间文字”；它与 `visual-novel` 分离，重点是 AI GM、自由行动、状态后果、长期记忆、章节目标和轻量剧本模拟器；入口、作品、发布、资产、钱包、埋点、存档和广场全部复用百梦平台接口；禁止新增 replay、外部社区、外部支付、外部榜单和私有存档系统。
- 影响范围：后续 `text-game` shared contracts、`module-text-game`、SpacetimeDB 表、`api-server` 路由、前端入口 / workspace / result / runtime、平台作品架和发现聚合。
- 验证方式：后续落地时确认路由使用 `/api/creation/text-game/*` 与 `/api/runtime/text-game/*`；确认正式业务真相在 Rust / SpacetimeDB 后端；确认没有 `replay` 能力和外部平台功能误入；确认 `text-game` 不复用 `visual-novel` step 契约作为运行态真相。
- 关联文档：`docs/prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md`。
## 2026-05-05 2048 玩法模板采用 `twenty-forty-eight` 工程域
- 背景：平台计划新增 2048 游戏玩法模板，需要同时适配前端 stage、HTTP 路由、Rust 模块、SpacetimeDB 表和公开作品号；裸 `2048` 不适合作为模块或文件命名前缀。
- 决策：面向用户展示名保持 `2048`，工程玩法 ID 固定为 `twenty-forty-eight`，Rust 模块与表前缀使用 `twenty_forty_eight`，公开作品号前缀使用 `TF-`；玩法按完整闭环设计，包含 Agent 创作、结果页、试玩、发布、公开运行、后端棋盘裁决、排行榜和作品架 / 广场接入。
- 影响范围：后续 `src/config/newWorkEntryConfig.ts`、平台 `SelectionStage`、前端 `twenty-forty-eight-*` 组件与 service、`module-twenty-forty-eight`、`shared-contracts`、`spacetime-module` 表、`spacetime-client` facade、`api-server` 路由、作品号和 PRD 索引。
- 验证方式：后续落地时确认用户可见标题为 `2048`，代码、路由和表统一使用 `twenty-forty-eight` / `twenty_forty_eight`；移动、合并、生成新方块、目标达成、失败和榜单成绩由后端正式裁决，前端不伪造分数或目标达成。
- 关联文档：`docs/prd/AI_NATIVE_2048_GAMEPLAY_TEMPLATE_PRD_2026-05-05.md`。
## 2026-05-05 幸存者类玩法作为平台模板接入
- 背景：平台继续扩展新玩法模板，需要把幸存者 / 割草 / 轻度 Roguelite 类玩法纳入统一创作中心、作品架、广场和运行态体系，避免再起一套独立小游戏工程。
- 决策：新增 `survivor` 作为 Genarrative 平台玩法模板，统一使用 `server-rs + Axum + SpacetimeDB`，创作端、结果页、试玩、发布和运行态都复用平台接口；前端只负责表现和高频模拟，不承接正式规则真相。
- 影响范围：`docs/prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md`、后续 `survivor` shared contracts、前端入口 / result / runtime、`server-rs` DDD 分层、SpacetimeDB 表设计和平台作品闭环。
- 验证方式：后续落地时检查 `survivor` 入口、session、work profile、runtime run、checkpoint、升级候选和结算接口是否都落在平台统一链路内，并确认没有新增独立小游戏壳层。
- 关联文档：`docs/prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md`。
## 2026-05-05 视觉小说 TXT 玩法只作为平台模板接入且删除回放
- 背景：`Interactive-fiction-backend` 与 `Interactive-fiction-frontend` 是完整平台类工程，其中 TXT / Galgame 玩法可借鉴，但账号、商城、后台、公开市场、回放等平台能力不能迁入 Genarrative。
- 决策：`visual-novel` 只作为 Genarrative 视觉小说模板接入，保留想法 / 文档 / 空白创建、世界观 / 角色 / 场景 / 剧情阶段编辑、视觉小说 step 运行时、历史和重生成等模板能力；入口、作品、发布、资产、钱包、存档和广场全部使用 Genarrative 平台接口；彻底删除回放、分享回放、回放编译、回放路由、回放表和回放 UI。
- 影响范围：视觉小说 PRD、旧 TXT 文档口径、后续 `visual-novel` shared contracts、前端入口 / result / runtime、`server-rs` DDD 分层、SpacetimeDB 表设计和平台存档接入。
- 验证方式：后续落地时扫描前端、后端、契约、表和文档，确认不存在 `replay` 能力；确认视觉小说没有迁入外部平台账号、订单、会员、促销、后台、公开市场或私有存档系统；确认后端落在 `server-rs + Axum + SpacetimeDB`。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/prd/TXT_MODE_CORE_GAMEPLAY_PRD_2026-04-20.md`、`docs/technical/TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md`。
## 2026-05-05 视觉小说 VN-02 表与 spacetime-client facade 收口
- 背景：`visual-novel` 后续 API、创作工作台和运行时需要稳定的 SpacetimeDB schema 与 Rust facade，且必须延续“无回放、无私有存档”的产品边界。
- 决策：视觉小说首批数据库只落六张表：`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`；`visual_novel_runtime_event` 是 `public event` 审计事件表，不是 replay 数据源；运行历史只保存继续体验与历史重生成需要的 typed step 和快照哈希。`api-server` 后续接入必须经 `spacetime-client/src/visual_novel.rs` typed facade，不直接依赖生成 bindings。
- 影响范围：`server-rs/crates/spacetime-module/src/visual_novel.rs`、`migration.rs`、`server-rs/crates/spacetime-client/src/visual_novel.rs`、`module_bindings/`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`、VN-05 API 联调。
- 验证方式：执行 `npm run spacetime:generate -- --rust-only`、`cargo check -p spacetime-module`、`cargo check -p spacetime-client`、`npm run check:encoding`；扫描视觉小说 schema / facade / 表目录确认没有 `replay` 表、路由或私有 save 表。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。
## 2026-05-05 视觉小说 VN-07 前端创作闭环按阶段边界落地
- 背景：`visual-novel` 模板需要先完成创作工作台与结果页，真实生成和正式玩家 runtime 仍依赖 VN-05 后端路由。
- 决策：VN-07 前端只接入口、Agent 工作台、可编辑 `VisualNovelResultDraft` 结果页和测试 run；`blank` 起点直接生成本地空白草稿进入结果页，`idea` / `document` 继续调用 `/api/creation/visual-novel/sessions`；结果页保存先更新当前 session 草稿，显式“编译草稿”才调用 `/compile`，测试 run 在真实 runtime 不可用时降级为本地 test run。
- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/visual-novel-creation/`、`src/components/visual-novel-result/`、`packages/shared/src/contracts/visualNovel.ts`、视觉小说 PRD。
- 验证方式：执行前端 typecheck、视觉小说工作台 / 结果页定向测试和编码检查；确认未新增 replay、作品聚合或正式 runtime 能力。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`。
## 2026-05-07 视觉小说 VN-11 负向扫描门禁
- 背景：视觉小说 TXT 模板进入收口后，需要一个可重复执行的守门方式，避免工程代码误入回放能力或外部平台功能。
- 决策：新增 `npm run check:visual-novel-vn11`，由 `scripts/check-visual-novel-vn11-negative-scan.mjs` 扫描 `src/`、`packages/shared/src/`、`server-rs/crates/`、`docs/` 与 `.hermes/shared-memory/`；工程代码中不允许出现 replay / 回放 / 录制 / 复盘类直出命中；外部平台能力误入只在视觉小说实现路径内检查，避免把平台已有账号、会员、后台等能力误判为视觉小说迁入。
- 影响范围：视觉小说 VN-11 验收、后续 `visual-novel` 增量改动、同类新玩法负向扫描脚本。
- 验证方式：执行 `npm run check:visual-novel-vn11`，报告写入 `docs/audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md`；当前扫描结论为工程代码无回放类直出命中，视觉小说实现路径无外部平台能力误入。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md`。
## 2026-05-07 视觉小说 VN-12 采用单独验收门禁脚本
- 背景：VN-12 是视觉小说模板的全链路联调与自动化验收收口任务，需要把关键路径、API smoke、前端测试和报告输出固化成可复跑门禁，避免后续改动只靠手工口述结论。
- 决策：新增 `npm run check:visual-novel-vn12`，由 `scripts/check-visual-novel-vn12-acceptance.mjs` 校验 PRD、VN-11 报告、关键前端测试、视觉小说 service client、`api-server` / `module-visual-novel` / `shared-contracts` 相关文件和路由命中，并生成 `docs/audits/VN12_FULL_CHAIN_ACCEPTANCE_REPORT_2026-05-07.md`。
- 影响范围：VN-12 验收、视觉小说后续回归、同类玩法的收口门禁模式。
- 验证方式：执行 `npm run check:visual-novel-vn12 -- --write-report`，报告应覆盖自动化验收清单、API smoke、前端关键路径、桌面/移动端检查说明和已执行命令；若脚本失败，直接回流到对应 owner 修复。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/audits/VN12_FULL_CHAIN_ACCEPTANCE_REPORT_2026-05-07.md`。
## 2026-05-07 视觉小说 VN-13 文档与交接收口
- 背景：视觉小说模板主链已经落地完成，需要把 PRD、表目录、prompt 工具说明、负向扫描报告和维护经验收成新开发者可直接接手的一组文档，避免后续仍回头查旧 TXT 迁移方案。
- 决策：视觉小说后续维护的正式入口固定为 `AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`SPACETIMEDB_TABLE_CATALOG.md`、`VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md`、`VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`、`VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md` 和 `VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md`；旧 TXT 迁移文档仅保留历史参考地位。
- 影响范围：视觉小说 PRD 收口、技术文档索引、经验文档索引、Hermes 共享记忆和后续维护阅读顺序。
- 验证方式：打开上述文档即可获得当前实现边界、表目录、Prompt 口径、负向扫描和维护经验；后续维护不需要把旧 TXT 平台工程文档重新当作实现目标。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`、`docs/experience/VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md`。
## 2026-05-05 平台移动端一级 Tab 改为推荐/发现/创作/草稿/我的
- 背景：移动端平台入口需要从旧“首页/排行/创作/存档/我的”调整为更直接的推荐流和应用式底部导航。
- 决策：前端内部继续复用 `PlatformHomeTab` 的 `home/category/create/saves/profile` 状态值，但用户看到的一级 Tab 分别为“推荐/发现/创作/草稿/我的”；`home` 直接展示公开推荐流，`category` 承载发现页及排行子 Tab，`saves` 承载草稿作品架，原存档结构并入“我的-玩过”弹层。
- 影响范围：平台入口导航、移动端推荐页、发现页子 Tab、创作中心作品架、个人页玩过弹层、相关设计文档。
- 验证方式：检查移动端底部导航文案和顺序，确认登录态为“推荐/发现/创作/草稿/我的”，未登录态为“推荐/创作/发现”且创作居中；“推荐”无搜索/频道栏直出作品流，“发现”包含搜索/推荐/今日/分类/排行，“创作”只显示新建入口，“草稿”显示作品架，“我的-玩过”可恢复存档。
- 关联文档：`docs/design/PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md`。
## 2026-05-05 创作 Tab 固定为智能创作首页，草稿 Tab 承接旧作品架
- 背景：创作首页需要变成面向对话式生成的智能创作页，旧模板卡和作品架继续保留但不应再占据创作首屏。
- 决策：`create` 只承载 `CreativeAgentHome` 智能创作首页与会话流，顶部品牌栏、问候、快捷胶囊、底部输入框和左侧抽屉是主结构；旧的新建作品类型卡不再在 `create` 里展示。原本的 RPG / 拼图 / 大鱼 / Match3D / 方洞 / 视觉小说作品架统一归到 `saves` 草稿 Tab。
- 影响范围：平台创作页布局、创作首页抽屉、草稿页作品架、相关交互测试、旧创作入口 helper。
- 验证方式：移动端点击“创作”直接看到智能创作首页；点击“草稿”看到旧作品架；旧模板入口不再从创作页出现。
- 关联文档：`docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md`。
## 2026-05-05 创意互动内容生成 Agent 采用 LangChain-Rust 六模块闭环
- 背景：需要支持用户输入文字、图片或文档后，先理解创作意图，再从多个模板候选中选择一个，并把内容填入拼图等目标玩法草稿契约中。
- 决策：新增方案改为基于 LangChain-Rust 的六模块 Agent 架构，核心模块是感知、思考、记忆、行动、反思、协作；首版只支持拼图玩法，但必须先展示多个拼图子模板候选，用户选择某个模板后，再确认该模板下的关卡模式、关卡数和预计积分范围，确认后才生成草稿；Agent 理解、规划和修订统一使用 APIMart Responses `gpt-5` 并支持文本/图像多模态输入；Agent 创作方式就是填充和修订模板草稿字段，表单化创作页与 Agent 自然语言修订都操作同一份 `PuzzleResultDraft`，且草稿可编辑字段只收敛为 `workTitle`、`workDescription`、`workTags`、`levels[].levelName`、`levels[].pictureDescription`、`levels[].pictureReference`；其中 `pictureReference` 已采用 `PuzzleDraftLevel.pictureReference` / Rust `picture_reference` 正式字段方案，不再走 metadata 过渡；单关卡/多关卡图片生成通过拼图模块 Tool 与模板协议实现；生成好的内容必须可立即试玩。
- 影响范围：创作中心入口、`platform-agent`、`module-creative-agent`、`module-puzzle` 拼图模板协议和工具、`shared-contracts`、`api-server` creative facade、SpacetimeDB creative agent 表、拼图玩法工具。
- 验证方式：后续落地时以创意互动内容生成 Agent 技术方案和 Phase 1 PRD 为编码依据，优先完成拼图 Phase 1，并执行 shared contracts、module、platform-agent、api-server、前端 typecheck 与编码检查。
- 关联文档：`docs/technical/CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md`、`docs/prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md`。
## 2026-05-05 creative-agent Task C 首版平台 PoC 已落地
- 背景：Phase 1 的平台侧需要先把 LangChain-Rust 适配层、APIMart `gpt-5` 多模态 Responses 请求和工具注册边界立起来，才能继续接 API facade。
- 决策：新增 `server-rs/crates/platform-agent` 作为独立 workspace crate，保留项目自有 `CreativeAgentExecutor`、工具注册表、回调事件和 mock executor；`platform-llm` 的 Responses 请求体扩展为可序列化 `input_text` / `input_image` content part。
- 影响范围：`server-rs/Cargo.toml`、`server-rs/crates/platform-agent`、`server-rs/crates/platform-llm`、任务 C 的后续 API / SSE 接入。
- 验证方式：`cargo check -p platform-agent`、`cargo test -p platform-agent`、`cargo test -p platform-llm responses_multimodal` 已通过。
- 关联文档：`docs/technical/CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md`。
## 2026-05-05 creative-agent Task E API / SSE facade 已落地
- 背景：Phase 1 需要先把创意 Agent 的 HTTP/SSE 门面接入 Rust `api-server`，用于前端工作区调用和拼图模板确认闭环。
- 决策：`api-server` 挂载 `/api/runtime/creative-agent/*` 六个鉴权路由；creative session 在 Task D 表未收口前暂存在 `api-server` 运行态并按 authenticated user 校验 owner；未确认模板前不创建拼图 session，`confirm-template` 后才通过既有 `spacetime-client` 创建/编译 `puzzle_agent_session`；`gpt-5` 请求只从 `APIMART_BASE_URL` / `APIMART_API_KEY` 构造专用 Responses client，不复用通用 `GENARRATIVE_LLM_API_KEY`。
- 影响范围：`server-rs/crates/api-server/src/creative_agent.rs`、`creative_agent_sse.rs`、`app.rs`、`state.rs`、`module-puzzle` creative template/tool、Phase 1 PRD。
- 验证方式：`cargo check -p api-server`、`cargo test -p module-puzzle creative`、`cargo test -p api-server creative_agent`、`npm run api-server` 后检查 `/healthz`、`POST /api/runtime/creative-agent/sessions`、`POST /api/runtime/creative-agent/sessions/{sessionId}/messages/stream`。
- 关联文档：`docs/prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md`。
## 2026-05-07 移动端整页缩放由入口统一锁定
- 背景：移动端游戏式页面如果允许浏览器整页缩放，容易把固定画布、HUD 和底部操作区一起放大或缩小，破坏操作节奏。
- 决策：主站入口统一使用 `viewport` 锁定 `minimum-scale=1.0`、`maximum-scale=1.0`、`user-scalable=no` 和 `viewport-fit=cover`，并在应用启动时调用 `lockMobileViewportZoom()` 拦截 iOS `gesture*` 与多指 `touchmove` 触发的页面级缩放。
- 影响范围：主站 `index.html`、`src/main.tsx`、后续所有依赖主入口的移动端游戏/画布页面；不要求每个画布组件重复实现缩放锁定。
- 验证方式：移动端打开主站后，双指捏合和快速双击不应再缩放整页；单指滚动、点击和组件内交互保持正常。
- 关联文档：`docs/experience/MOBILE_UI_DEV_EXPERIENCE.md`。
## 2026-05-07 视觉小说 VN-10 资产引用统一走平台资产对象
- 背景：视觉小说文档输入、封面、场景背景、角色立绘和音乐需要接入平台资产链路，不能在前端状态或 SpacetimeDB 中保存大 Data URL、二进制对象或外部 R2 路径。
- 决策：VN 上传统一复用 `/api/assets/direct-upload-tickets`、OSS 直传、`/api/assets/objects/confirm`、`/api/assets/read-url`。文档上传后只把 `assetObjectId` 放入 `sourceAssetIds`，`seedText` 仅放截断摘要；封面、场景、角色、音乐只写 `/generated-*` 引用和平台 asset id。角色立绘写入 `imageAssets[].source = platform_asset`。运行时图片渲染统一使用 `ResolvedAssetImage` 换签。
- 影响范围：`src/services/visual-novel-creation/visualNovelAssetClient.ts`、`VisualNovelAgentWorkspace`、`VisualNovelResultView`、`VisualNovelRuntimeShell`、`server-rs/crates/api-server/src/visual_novel.rs`。
- 验证方式：VN 定向前端测试、`npm run typecheck`、`npm run check:encoding`、`cargo test -p api-server visual_novel`、`cargo test -p api-server creation_agent_document_input`。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`。
## 2026-05-04 在仓库 `.hermes/` 中建立团队共享记忆
- 背景：团队有 3 名开发人员，均在各自本地安装 Hermes，并需要独立拉取仓库、修改代码、本地测试；团队希望形成共享的长期项目记忆。

110
.hermes/shared-memory/pitfalls.md
View File

@@ -91,6 +91,33 @@
- 验证：不打印密钥内容，只检查 `APIMART_API_KEY` 非空；重启后触发拼图生成不再返回本地配置缺失的 503。
- 关联：`docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md`、`.codex/skills/gpt-image-2-apimart/SKILL.md`。
## 拼图图片生成 98% 后报 OSS V4 签名时间格式化失败
- 现象：拼图创作表单生成进度卡在 98%，`POST /api/runtime/puzzle/agent/sessions/{sessionId}/actions` 返回 `502 Bad Gateway`，前端提示 `拼图图片生成失败：OSS V4 签名时间格式化失败`。
- 原因：`platform-oss` 曾用 `OffsetDateTime::time().to_string()` 拼接 `x-oss-date`，UTC 小时、分钟或秒为个位数时可能缺少前导零，导致 V4 签名时间不是固定 `YYYYMMDDTHHMMSSZ`。
- 处理：OSS V4 签名日期统一显式补零格式化；签名 scope 用 `YYYYMMDD`，完整签名时间用 `YYYYMMDDTHHMMSSZ`，不要再依赖 `time().to_string()`。
- 验证：运行 `cargo test -p platform-oss` 和 `cargo check -p api-server`；重启 `npm run api-server` 后检查 `/healthz`，再重新触发拼图生成。
- 关联：`server-rs/crates/platform-oss/src/lib.rs`、`server-rs/crates/api-server/src/assets.rs`、`docs/technical/M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md`。
## 拼图生成完成后图片只显示破图或 alt 文案
- 现象：拼图结果页生成完成后，“画面图”区域出现破图图标和作品名，图片无法正常预览；但打开历史拼图素材时同一张图可能可以正常预览。
- 原因：拼图正式图保存为 `/generated-puzzle-assets/*` 兼容标识，旧 `/generated-*` 直读代理已删除；如果前端没有通过 `ResolvedAssetImage` / `/api/assets/read-url` 换签，或收到无前导斜杠的 `generated-puzzle-assets/*` object key 后未识别为 generated 私有资源，浏览器会直接请求裸路径并失败。生成完成后的结果图还会传入 `refreshKey`，它只能用于重新请求 `/api/assets/read-url`，不能给 OSS V4 签名 URL 追加 `_v`；OSS 会把 query 纳入签名，额外参数会让签名失效，历史素材常因未传 `refreshKey` 而表现正常。
- 处理：拼图结果页、发布预览、运行态和历史素材预览都走 `ResolvedAssetImage` 或 `useResolvedAssetReadUrl`；`isGeneratedLegacyPath(...)` 必须同时识别 `/generated-*` 和 `generated-*`；`refreshKey` 只绕过前端签名缓存并重新换签，不修改已返回的 OSS 签名 URL；禁止恢复 `/generated-puzzle-assets` 直读代理。
- 验证：运行 `npm run test -- src\services\assetReadUrlService.test.ts src\hooks\useResolvedAssetReadUrl.test.tsx src\components\puzzle-result\PuzzleResultView.test.tsx`，再触发一次真实生成确认 Network 中先请求 `/api/assets/read-url`，图片 `src` 为未追加 `_v` 的签名 URL。
- 关联：`src/services/assetReadUrlService.ts`、`src/components/ResolvedAssetImage.tsx`、`docs/technical/PUZZLE_IMAGE_ASSET_PROXY_FIX_2026-04-27.md`。
## 本地短信登录页签突然消失
- 现象：登录弹窗只剩密码登录，短信登录页签看起来像被删掉，但 `LoginScreen` 中手机号验证码表单仍存在。
- 原因：前端根据 `GET /api/auth/login-options` 返回的 `availableLoginMethods` 渲染页签；常见根因有两类：
- 本地启动脚本没有让 `.env.local` 覆盖 `.env`，`SMS_AUTH_ENABLED=true` 不生效，后端只返回 `["password"]`。
- Rust API 直连已返回 `["phone","password"]`，但 Vite 代理目标指向未监听端口，导致 3000 域名下的 `login-options` 返回 `500`，`AuthGate` 降级成 `["password"]`。
- 3000 端口被旧 `dev:web` 占用后，新的完整栈 Vite 自动漂移到 3001/3002；浏览器仍打开旧 3000 页面，旧页面继续代理到已经下线的端口。
- 处理：优先用 `npm run api-server`、`npm run dev:rust` 或 `npm run dev` 启动，这些入口应保持 shell 环境变量最高优先级，并允许 `.env.local` 覆盖 `.env`；完整栈启动时还要确保脚本计算出的 `RUST_SERVER_TARGET` 不被 `.env.local` 里的旧值覆盖。排查时先请求 3000 域名下的 `/api/auth/login-options`，再直连 Rust API 目标，并核对 `.env.local` 的 `SMS_AUTH_ENABLED` 与代理端口；若 3001/3002 才返回正确结果，说明当前 3000 是旧前端进程，应清理旧进程后重启。
- 验证：`http://127.0.0.1:3000/api/auth/login-options` 返回至少 `{"availableLoginMethods":["phone","password"]}` 后，登录弹窗会恢复短信登录页签和“获取验证码”按钮。
- 关联：`scripts/api-server-dev.mjs`、`scripts/api-server-maincloud.mjs`、`scripts/dev-rust-stack.sh`、`scripts/dev-web-rust.mjs`、`docs/technical/AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md`。
## Rust 冷编译导致 api-server 健康检查误超时
- 现象：`npm run dev:rust` 在 Windows 冷编译/链接阶段误判 `/healthz` 等待超时并杀掉 `cargo run`。
@@ -99,6 +126,81 @@
- 验证：冷启动时不再误杀仍在编译的 api-server。
- 关联：`docs/technical/API_SERVER_DEV_STACK_COLD_BUILD_TIMEOUT_FIX_2026-04-25.md`。
## Windows debug api-server 主线程栈溢出
- 现象：`cargo check -p api-server` 和 `build_router` 测试通过，但 `npm run api-server` 在 Windows debug 启动时 `thread 'main' has overflowed its stack`。
- 原因：`api-server` Axum 路由树已经很深，debug 主线程默认栈偏小，初始化状态和构造路由时容易触顶。
- 处理：入口 `main` 用显式 16MB 栈线程启动 Tokio runtime，并把实际服务逻辑放入 `run_server()`；新增路由时优先用小 router `.merge()`，避免继续拉长主链。
- 验证：`npm run api-server` 后 `/healthz` 返回 200，相关路由冒烟通过。
- 关联：`server-rs/crates/api-server/src/main.rs`、`server-rs/crates/api-server/src/app.rs`。
## Windows api-server.exe 锁文件与强杀退出码容易混淆
- 现象：`cargo run -p api-server` 或 `npm run api-server` 报 `failed to remove file ... target\debug\api-server.exe`；清理旧进程后，旧终端可能继续打印 `process didn't exit successfully: server-rs\target\debug\api-server.exe (exit code: 0xffffffff)`。
- 原因：Windows 不能覆盖仍在运行的 exe；通常是上一条 `npm run api-server` 链路仍在运行，进程树为 `npm run api-server -> node scripts/api-server-dev.mjs -> cargo run -> api-server.exe`。`0xffffffff` 常见于排障时用 `Stop-Process -Force` 强制结束旧 `api-server.exe` 后由 Cargo 回显，不一定代表新启动失败。
- 处理：先按目标路径确认并停止本仓库的旧 `api-server.exe` 及其父级 `cargo/node/cmd` 启动链路，再重新启动；不要同时开多个 `npm run api-server`。
- 验证：确认没有匹配 `C:\Genarrative\server-rs\target\debug\api-server.exe` 的进程后，`Remove-Item` 能删除旧 exe；随后 `npm run api-server` 启动并访问 `/healthz` 返回 200。
- 关联：`scripts/api-server-dev.mjs`、`server-rs/crates/api-server/src/main.rs`。
## Windows debug 长 SSE Future 触发 api-server 断连
- 现象：前端 Vite 代理请求 `/api/runtime/creative-agent/sessions/{sessionId}/messages/stream` 报 `read ECONNRESET`，随后 `api-server.exe` 以 `0xffffffff` 退出，`dev:rust` 回收 SpacetimeDB、Vite 和后台 Vite。
- 原因：单个 `async_stream::stream!` 中塞入 Agent 执行、外部模型请求、会话更新和大量 SSE 事件，会在 Windows debug 下生成很大的 Future；真实消费 SSE body 时容易触发 worker 线程栈压力或进程级中断，单元测试若只测函数和路由状态会漏掉。
- 处理：长 SSE 路由优先使用 `tokio::spawn` 跑业务流程，通过 `mpsc` + `UnboundedReceiverStream` 向 Axum 返回轻量 stream；失败时更新会话为 `failed` 并发送 SSE `error`，不要把大段执行逻辑内联到路由返回的 stream future 中。
- 验证：补充实际 `collect()` SSE body 的路由测试，确认首轮包含 `stage`、`puzzle_template_catalog` 和 `done`，且不会提前发送 `puzzle_template_selection` / `puzzle_cost_range`；再执行 `cargo check -p api-server`、`cargo test -p api-server creative_agent`，联调时用 `npm run api-server` 检查 `/healthz`。
- 关联：`server-rs/crates/api-server/src/creative_agent.rs`、`server-rs/crates/api-server/src/app.rs`。
## creative-agent 过程项不要把历史事件渲染成运行中
- 现象：智能创作页过程中多个阶段从一开始同时转圈，生成结束或进入模板确认后仍有过程项保持转圈。
- 原因：前端把历史 `stage`、`tool_started` 和 `thought_summary_delta` 都按 active 渲染；后端工具开始/完成事件如果 `toolCallId` 不一致，也会导致开始事件无法收口。
- 处理：
- 只有最新且仍在执行的 stage 可为 active；等待确认、等待用户、target ready 和 failed 都是静态状态。
- 工具开始事件必须等同一 `toolCallId` 的 `tool_completed` 收口；兼容旧流时可按后续同名完成事件兜底。
- 思考摘要只展示用户可见摘要，且流结束或会话进入等待/完成/失败态后必须改成 done。
- 验证：前端测试断言完成后 `CreativeAgentProcessItem` 不再存在 `tone === 'active'`；后端测试确认工具开始/完成事件使用相同 `toolCallId`。
- 关联：`src/components/creative-agent/creativeAgentViewModel.ts`、`server-rs/crates/api-server/src/creative_agent.rs`、`docs/prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md`。
## creative-agent 会话切换要清理本地待确认模板
- 现象：用户在一个智能创作会话中点开模板确认面板后，立即切到另一条创作会话，可能看到上一会话的确认面板残留。
- 原因：模板确认面板的 `pendingSelection` 是 `CreativeAgentWorkspace` 本地 UI 状态，不属于后端 session 快照；组件复用时如果不监听 `sessionId` 清理，会跨会话泄漏。
- 处理：工作区以 `session?.sessionId` 为边界清空 `pendingSelection`；服务端仍以 `puzzleTemplateSelection` / `targetBinding` 作为正式业务状态。
- 验证：前端测试先点开模板确认面板，再 rerender 到另一 session，断言确认面板消失。
- 关联：`src/components/creative-agent/CreativeAgentWorkspace.tsx`、`src/components/creative-agent/CreativeAgentWorkspace.test.tsx`。
## 视觉小说 VN-10 不要绕过平台资产引用
- 现象：文档、封面、场景背景、角色立绘或音乐为了预览方便被写成 Data URL、裸对象路径、外部 URL 或本地临时文件路径。
- 原因：前端上传与预览容易混在一起，若不走平台资产对象，SpacetimeDB 和长期草稿会被大文本或大二进制污染。
- 处理：VN 资产统一用 `/api/assets/direct-upload-tickets`、OSS 直传、`/api/assets/objects/confirm`，长期状态只保存 `assetObjectId` 和 `/generated-*` 引用；运行时图片用 `ResolvedAssetImage` 换签。
- 验证：文档模式 `sourceAssetIds` 为平台资产 id；草稿中不出现 `data:`；图片和音乐字段为平台 generated 引用或 null。
- 关联：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`src/services/visual-novel-creation/visualNovelAssetClient.ts`。
## 视觉小说 VN-13 交接时不要再回头找旧迁移方案
- 现象：接手视觉小说的人容易重新打开旧 TXT 迁移文档，把“外部平台工程迁入”误当成当前实现目标。
- 原因：视觉小说历史资料里保留了很多迁移阶段的讨论，而当前真正的实现口径已经收口到 PRD、表目录、Prompt 工具说明、实现收口文档和负向扫描报告。
- 处理：维护视觉小说时优先看 `AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`SPACETIMEDB_TABLE_CATALOG.md`、`VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md`、`VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`、`VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md` 和 `VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md`。
- 验证：新开发者只读这组文档即可继续维护，不需要把旧 TXT 迁移方案重新当作编码依据。
- 关联：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`、`docs/experience/VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md`。
## 视觉小说公开广场不要触发登录刷新
- 现象：未登录用户进入平台公开广场或从推荐流读取视觉小说公开作品时，前端可能先尝试 `/api/auth/refresh`，失败后再读取公开列表，导致无意义的鉴权噪声或 401 状态刷新。
- 原因：公开只读接口如果复用默认 `requestJson` 选项，缺少 access token 时会先走静默 refresh。
- 处理：视觉小说公开广场列表使用 `skipAuth: true` 与 `skipRefresh: true`；鉴权 mutation 仍保持默认鉴权链路。
- 验证：执行 `src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts`，确认 `/api/runtime/visual-novel/gallery` 请求携带 `skipAuth` / `skipRefresh`，而 run、重生成和存档 mutation 仍走受保护路由。
- 关联：`src/services/visual-novel-runtime/visualNovelRuntimeClient.ts`、`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`。
## 创作 Tab 语义迁移后，旧“新建作品”测试要改看智能创作首页
- 现象：把 `create` 从旧创作中心切到 `CreativeAgentHome` 后，旧测试仍尝试在创作页找“新建作品”类型卡，导致用例失败或定位不到元素。
- 原因：产品语义已经变成“创作 = 智能创作首页，草稿 = 旧作品架”，但测试夹具和 helper 还沿用旧入口。
- 处理：把这类测试改成验证智能创作首页、快捷胶囊、抽屉与草稿 Tab；同时给 `useRpgEntryLibraryDetail` 这类恢复路径补上 `setPlatformTabToDraft`。
- 验证：定向 `vitest`、`eslint`、`typecheck`、`check:encoding` 都通过。
- 关联：`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`src/components/rpg-entry/useRpgEntryAgentDraftRestore.test.tsx`、`src/components/rpg-entry/useRpgEntryLibraryDetail.ts`。
## server-rs 默认 cargo build 不能等同于构建 SpacetimeDB 模块
- 现象：在 `server-rs` 下无参数 `cargo build` 期望同时构建 `spacetime-module`，导致链接或构建范围误判。
@@ -107,6 +209,14 @@
- 验证：查看 `server-rs/Cargo.toml` default-members，并按相关 SpacetimeDB 文档执行模块构建。
- 关联：`server-rs/Cargo.toml`、`docs/technical/RUST_WORKSPACE_DEFAULT_BUILD_SCOPE_FIX_2026-04-25.md`。
## Rust 构建不要让不可用的 sccache 阻断 rustc
- 现象：Cargo 报 `could not execute process sccache ... rustc.exe -vV (never executed)`，真实 `rustc -Vv` 可以执行，但构建在调用包装器时失败。
- 原因：环境或 Jenkinsfile 设置了 `RUSTC_WRAPPER=sccache`，但当前 Windows/Linux agent 上没有可执行的 `sccache`，或 PATH 中的 `sccache` shim 损坏。
- 处理：本地临时排障可执行 `Remove-Item Env:RUSTC_WRAPPER -ErrorAction SilentlyContinue` 后重跑 Cargo；生产流水线必须先实际执行 `sccache --version`，失败时移除 `RUSTC_WRAPPER` 并回退到直接 `rustc`。
- 验证：`rustc -Vv` 能输出版本；`cargo` 不再尝试调用不可用的 `sccache`；Jenkins 日志出现“未找到可用 sccache，改用 rustc 直接构建”后仍继续真实构建。
- 关联：`jenkins/Jenkinsfile.production-stdb-module-build`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
## 生产发布入口不要沿用旧 Jenkinsfile / 一体化脚本
- 现象：部署、回滚或 Jenkins Job 重建时参考旧发布文档，导致 systemd、Nginx、SpacetimeDB 自托管和生产包拆分不一致。

14
deploy/env/api-server.env.example vendored
View File

@@ -39,6 +39,20 @@ APIMART_BASE_URL=
APIMART_API_KEY=
APIMART_IMAGE_REQUEST_TIMEOUT_MS=180000
VECTOR_ENGINE_BASE_URL=
VECTOR_ENGINE_API_KEY=
VECTOR_ENGINE_AUDIO_REQUEST_TIMEOUT_MS=180000
VOLCENGINE_SPEECH_API_KEY=
VOLCENGINE_SPEECH_APP_ID=
VOLCENGINE_SPEECH_ACCESS_KEY=
VOLCENGINE_SPEECH_ASR_RESOURCE_ID=volc.seedasr.sauc.concurrent
VOLCENGINE_SPEECH_TTS_RESOURCE_ID=seed-tts-2.0
VOLCENGINE_SPEECH_REQUEST_TIMEOUT_MS=180000
VOLCENGINE_SPEECH_ASR_WS_URL=wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async
VOLCENGINE_SPEECH_TTS_BIDIRECTION_WS_URL=wss://openspeech.bytedance.com/api/v3/tts/bidirection
VOLCENGINE_SPEECH_TTS_SSE_URL=https://openspeech.bytedance.com/api/v3/tts/unidirectional/sse
ARK_CHARACTER_VIDEO_BASE_URL=
ARK_CHARACTER_VIDEO_API_KEY=
ARK_CHARACTER_VIDEO_MODEL=

10
docs/README.md
View File

@@ -13,7 +13,7 @@
重点补充：RPG 创作与运行时脚本职责地图见 [RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md](./reference/RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md)。
- [埋点查询](./tracking/README.md)：埋点原始事件与聚合投影的本地 SQL 查询。
- [运营查询](./operations/README.md)：任务、领奖、钱包对账等后台核查查询。
- [PRD](./prd)：产品需求与阶段计划；后台管理独立前端工程见 [ADMIN_WEB_CONSOLE_PRD_2026-04-30.md](./prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)，新增 RPG 开场动画方案见 [AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md](./prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md)，新增抓大鹅 Match3D 玩法方案见 [AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md](./prd/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/AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)。
- [PRD](./prd/README.md)：产品需求与阶段计划；参考 MOKU / 幕间类 AI 文游的百梦 `text-game` 模板口径见 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md](./prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md)，视觉小说模板 TXT 玩法平台化接入口径见 [AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md](./prd/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](./prd/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](./prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md)，后台管理独立前端工程见 [ADMIN_WEB_CONSOLE_PRD_2026-04-30.md](./prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)，新增 RPG 开场动画方案见 [AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md](./prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md)，新增抓大鹅 Match3D 玩法方案见 [AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md](./prd/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/AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)。
生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 [PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，该文档也是当前生产 Jenkinsfile 的唯一入口。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。
@@ -23,6 +23,14 @@ SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段
`maincloud` 相关脚本、环境变量、测试名和文档要求已统一判定为历史残留，后续禁止新增、运行或引用；当前后端 smoke 使用 `npm run api-server` 与 `/healthz`，详细规则见 [MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md](./technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md)。
基于 LangChain-Rust，以“感知—思考—记忆—行动—反思—协作”闭环完成图文创意理解、拼图模板选择、积分范围确认、拼图草稿字段填充、立即试玩和自然语言修订草稿字段的 Agent 方案见 [CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md](./technical/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](./prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md)。
视觉小说模板接入以 [AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md](./prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md) 为最新口径：只吸收外部 TXT 玩法的模板创作与运行经验，禁止迁入外部平台功能，并删除回放。
AI 文字游戏模板接入以 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md](./prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md) 为最新口径：只吸收 MOKU / 幕间类 AI 文游的剧本游乐场、自由行动、AI GM、记忆和模拟器强反馈经验，禁止迁入外部社区、支付、榜单、私有存档或回放。
## 推荐阅读顺序
1. 先看 [经验沉淀](./experience/README.md)，快速建立这个项目的开发共识。

2
docs/audits/README.md
View File

@@ -19,6 +19,8 @@
- [CHARACTER_ASSET_PROMPT_CHAIN_AUDIT_2026-04-20.md](./CHARACTER_ASSET_PROMPT_CHAIN_AUDIT_2026-04-20.md)：角色资产默认描述文本、正式图像/动作 prompt、共享模板与保留接口的分层与冗余审计。
- [RPG_RUNTIME_DIRECT_DRAFT_PROFILE_AUDIT_2026-04-25.md](./RPG_RUNTIME_DIRECT_DRAFT_PROFILE_AUDIT_2026-04-25.md)：RPG 运行时进入世界时改为直读 Agent session 草稿 profile 的链路检查。
- [RPG_WORLD_DRAFT_EDIT_AUTOSAVE_OVERRIDE_AUDIT_2026-04-28.md](./RPG_WORLD_DRAFT_EDIT_AUTOSAVE_OVERRIDE_AUDIT_2026-04-28.md)：RPG 世界草稿结果页编辑后被旧设定覆盖的前端本地态、session 真相源与自动保存链路审计。
- [VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md](./VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md)：视觉小说 VN-11 回放删除与外部平台功能误入负向扫描报告。
- [VN12_FULL_CHAIN_ACCEPTANCE_REPORT_2026-05-07.md](./VN12_FULL_CHAIN_ACCEPTANCE_REPORT_2026-05-07.md)：视觉小说 VN-12 全链路联调与自动化验收报告。
- [engineering/RPG_FRONTEND_SCRIPT_BACKEND_MIGRATION_AUDIT_2026-04-28.md](./engineering/RPG_FRONTEND_SCRIPT_BACKEND_MIGRATION_AUDIT_2026-04-28.md)：RPG 前端脚本中仍应迁到 `server-rs` / SpacetimeDB 的开局、快照、story engine、战斗、NPC/背包规则与创作残留后门审计。
- [engineering/RPG_FRONTEND_SCRIPT_BACKEND_MIGRATION_COMPLETION_CHECK_2026-04-28.md](./engineering/RPG_FRONTEND_SCRIPT_BACKEND_MIGRATION_COMPLETION_CHECK_2026-04-28.md)：RPG 前端脚本后端迁移完成度复核，标明开局、快照、story engine / prompt context、`camp_travel_home_scene`、战斗、NPC、背包/锻造、结果页保存 normalize 与角色资产 prompt 主链均已收口。
- [engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md](./engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md)：对 `2026-04-19` 工程清理审计的当前仓库复核，区分已完成项、仍存边界问题和新的热点迁移。

32
docs/audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md Normal file
View File

@@ -0,0 +1,32 @@
# VN-11 负向扫描报告
生成日期：2026-05-07
## 扫描范围
- 工程代码：`src/`、`packages/shared/src/`、`server-rs/crates/`
- 文档与共享记忆：`docs/`、`.hermes/shared-memory/`
- 外部平台误入复核：视觉小说前端、service、shared contracts、Rust contracts、module、api-server、SpacetimeDB schema 与 facade 路径
## 扫描结论
- 工程代码回放类直出命中：0
- 文档 / 共享记忆回放类命中：222
- 视觉小说实现路径外部平台能力疑似误入命中：0
## 处理记录
- 已将 `storyEngine` 回归工具的命名从 replay 语义收口为 rerun / 复测语义。
- 已将技能效果预览按钮的内部状态与文案从重播语义收口为重新预览语义。
- 已确认视觉小说工程路径未新增回放路由、DTO、表、按钮、文案、外部平台账号 / 订单 / 会员 / 促销 / 后台 / 公开市场或私有存档能力。
## 文档命中说明
- 文档命中来自历史旧文档、设计复盘、禁止语境、负向验收或本报告记录。VN-11 工程门禁只阻断代码路径新增能力。
## 门禁命令
```bash
npm run check:visual-novel-vn11
```

92
docs/audits/VN12_FULL_CHAIN_ACCEPTANCE_REPORT_2026-05-07.md Normal file
View File

@@ -0,0 +1,92 @@
# VN-12 全链路联调与自动化验收报告
生成日期：2026-05-07
## 结论
- 状态：通过
- 失败项：0
- 收口说明：VN-12 本次只补验收门禁、关键路径测试和报告记录，未扩展新玩法功能。
## 自动化验收清单
- docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md
- docs/audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md
- src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx
- src/components/visual-novel-result/VisualNovelResultView.test.tsx
- src/components/visual-novel-runtime/VisualNovelRuntimeShell.test.tsx
- src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts
- src/services/visual-novel-runtime/visualNovelRuntimeSse.test.ts
- server-rs/crates/api-server/src/visual_novel.rs
- server-rs/crates/module-visual-novel/src/application.rs
- server-rs/crates/shared-contracts/src/visual_novel.rs
- package.json
- server-rs/crates/api-server/src/app.rs
- src/services/visual-novel-runtime/visualNovelRuntimeClient.ts
- src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts
- src/services/visual-novel-runtime/visualNovelRuntimeSse.test.ts
- src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx
- src/components/visual-novel-result/VisualNovelResultView.test.tsx
- src/components/visual-novel-runtime/VisualNovelRuntimeShell.test.tsx
## API smoke
- `/api/creation/visual-novel/sessions`
- `/api/creation/visual-novel/works`
- `/api/runtime/visual-novel/gallery`
- `/api/runtime/visual-novel/works/{profile_id}/runs`
- `/api/runtime/visual-novel/runs/{run_id}/actions/stream`
- `/api/runtime/visual-novel/runs/{run_id}/history`
- `/api/runtime/visual-novel/runs/{run_id}/regenerate`
- `/api/profile/save-archives`
- `/api/profile/save-archives/{world_key}`
- `/api/runtime/save/snapshot`
本次实测：
- `npm run api-server` 可启动 Rust `api-server`。
- `GET http://127.0.0.1:3100/healthz` 返回 `200`，响应为 `{"ok":true,"service":"genarrative-api-server"}`。
- `GET /api/runtime/visual-novel/gallery` 在当前本地环境返回超时 / `502`，日志显示 `api-server` 连接 `127.0.0.1:3101` SpacetimeDB 数据库 `xushi-p4wfr` 被拒绝；该项按本地 SpacetimeDB 未完整就绪记录为环境阻塞，不新增工程实现。
## 前端关键路径
- 创作工作台：`VisualNovelAgentWorkspace`
- 结果页：`VisualNovelResultView`
- 运行时：`VisualNovelRuntimeShell`
- 运行时 SSE：`visualNovelRuntimeSse` / `visualNovelRuntimeClient`
## 桌面 / 移动端检查
- 桌面端：已用 Edge headless 截取 `/creation/visual-novel/agent`，文件为 `docs/audits/VN12_VISUAL_NOVEL_DESKTOP_2026-05-07.png`。
- 移动端：已用 Edge headless 截取 `/creation/visual-novel/agent`，文件为 `docs/audits/VN12_VISUAL_NOVEL_MOBILE_2026-05-07.png`。
- in-app browser 插件本次未发现可用 IAB backend，截图使用本机 Edge headless 兜底完成。
## 校验摘要
- package.json scripts: 通过
- api-server visual novel routes: 通过
- visual novel runtime client routes: 通过
- visual novel runtime client tests: 通过
- visual novel SSE tests: 通过
- visual novel creation tests: 通过
- visual novel result tests: 通过
- visual novel runtime tests: 通过
## 执行命令
```bash
npm run check:visual-novel-vn12 -- --write-report
npm run test -- src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx src/components/visual-novel-runtime/VisualNovelRuntimeShell.test.tsx src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts src/services/visual-novel-runtime/visualNovelRuntimeSse.test.ts
npm run check:encoding
npm run typecheck
cd server-rs
cargo test -p shared-contracts
cargo test -p module-visual-novel
cargo check -p api-server
```
## 未覆盖风险
- 当前本地 SpacetimeDB 连接未完整就绪，公开 gallery API 的真实数据返回未在本次环境完成；`/healthz` 与编译 / 单测已通过。
- 若接口路由或测试名称后续调整，需要同步更新本门禁脚本与报告模板。

BIN
docs/audits/VN12_VISUAL_NOVEL_DESKTOP_2026-05-07.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 160 KiB

BIN
docs/audits/VN12_VISUAL_NOVEL_MOBILE_2026-05-07.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 45 KiB

10
docs/design/MOBILE_CREATION_NEW_WORK_COMPACT_LAYOUT_2026-04-24.md
View File

@@ -28,3 +28,13 @@
- 锁定的模板卡统一以“敬请期待”作为状态标注，不再显示“锁定”。
- RPG 入口展示为“角色扮演 / 剧情演绎，冒险成长”，拼图入口展示为“拼图 / 创意礼物，生活分享”。
- 忙碌状态仅保留在模块标题行的轻量状态中，避免占用每张可用卡片的首要视觉层级。
## 2026-05-07 玩法参考图
1. 每个玩法入口都必须配置一张 `public/creation-type-references/` 下的参考图。
2. 当前创作 Tab 顶部玩法卡带、旧创作中心卡带和玩法类型弹层都消费同一份 `PLATFORM_CREATION_TYPES.imageSrc`，避免多入口视觉漂移。
3. 图片只承担玩法识别和氛围锚定，不在卡片上叠加规则说明文案。
4. 移动端卡片仍以紧凑横滑为主，参考图使用暗色遮罩承接标题，文本不得溢出卡片。
5. 当前创作 Tab 的可见玩法卡必须真实渲染 `img`，不能只在隐藏弹窗或旧入口中配置图片。
6. 参考图卡片上的标题和副标题必须显式使用白色文字，并配合底部加深渐变与文字阴影；禁止依赖 `text-inherit`，避免黑字叠在暗蒙版上。
7. 当前创作 Tab 顶部不再保留“10分钟创作一个精品互动玩法”标题，玩法参考图卡带直接作为首屏入口；移动端卡带必须支持横向拖动滑动。

18
docs/design/PLATFORM_CATEGORY_AND_CREATE_TAB_DESIGN_2026-04-24.md
View File

@@ -6,8 +6,8 @@
- 新增“分类” Tab，用作品标签聚合所有公开发布作品。
- 强化“创作” Tab 的导航视觉权重，让它在底部导航中居中并更醒目。
- 登录态底部导航顺序为：首页、分类、创作、存档、我的。
- 未登录态底部导航只保留：首页、创作、分类，其中创作保持居中。
- 登录态底部导航顺序为：推荐、发现、创作、草稿、我的。
- 未登录态底部导航只保留：推荐、创作、发现，其中创作保持居中。
## 2. 数据边界
@@ -24,10 +24,10 @@
底部导航展示 5 个入口：
1. 首页
2. 分类
1. 推荐
2. 发现
3. 创作
4. 存档
4. 草稿
5. 我的
创作入口位于第三位，视觉上使用更大的图标壳、轻微上浮、渐变高亮和阴影，保证它是主行动入口。
@@ -36,11 +36,11 @@
底部导航展示 3 个入口：
1. 首页
1. 推荐
2. 创作
3. 分类
3. 发现
不展示“存档”和“我的”，避免未登录用户在底部导航看到必须登录后才有价值的入口。创作入口位于第二位，保持几何居中。
不展示“草稿”和“我的”，避免未登录用户在底部导航看到必须登录后才有价值的入口。创作入口位于第二位，保持几何居中，并沿用原推荐 Tab 的星光图标；推荐 Tab 改用游戏手柄图标。
### 3.3 桌面端
@@ -59,6 +59,6 @@
- 登录态移动端底部导航顺序准确，创作在 5 个 Tab 中居中。
- 未登录态移动端底部导航只显示 3 个 Tab，创作在中间。
- 分类 Tab 能按标签切换并展示公开作品。
- 发现 Tab 能按标签切换并展示公开作品。
- 创作 Tab 在移动端和桌面端都比普通 Tab 更醒目。
- 不修改 server-node，不新增后端逻辑。

46
docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md Normal file
View File

@@ -0,0 +1,46 @@
# 平台创作 Tab 模板入口设计
更新时间：`2026-05-07`
## 1. 目标
创作 Tab 恢复为模板选择入口，但不回到旧的大卡片选择面板：
1. 首屏保留现有创作页布局骨架，顶部标题固定为“10分钟创作一个精品互动玩法”。
2. 选择模板入口改为横向 Tab，数据来自 `src/config/newWorkEntryConfig.ts` 的可见玩法配置。
3. 默认选中“拼图”模板，并在创作 Tab 内直接展示拼图创作表单。
4. 智能创作入口从可见模板中隐藏，保留既有 `creative-agent` 运行链路用于后续内部恢复或草稿目标打开。
5. 草稿、发现、我的等一级 Tab 职责不变，作品管理仍在草稿 Tab。
## 2. 页面结构
移动端和桌面端共用同一信息结构：
```text
标题：10分钟创作一个精品互动玩法
模板 Tab：拼图 / 方洞挑战 / 视觉小说 / AIRP
默认内容：拼图创作表单
```
拼图表单嵌入创作 Tab 时：
- 不展示工作台返回按钮。
- 不重复展示“创建拼图”标题。
- 保留表单内的拼图模板、参考图上传、画面描述和生图模型选择。
- 生成草稿仍走登录保护，未登录时先触发登录流程。
## 3. 交互
1. 打开“创作”一级 Tab 时默认停留在拼图 Tab，不主动创建拼图 session。
2. 点击拼图表单“生成草稿”后，才创建拼图 session 并执行 `compile_puzzle_draft`。
3. 拼图表单内的模板按钮使用 `tablist / tab` 语义，点击后只填充画面描述。
4. 点击非拼图且已开放的模板 Tab 时，进入该玩法既有工作台；未开放模板保持禁用。
5. `creative-agent` 不出现在模板 Tab 和选择弹层中，不再作为创作 Tab 首屏入口。
## 4. 验收
1. 点击“创作”后首屏出现“10分钟创作一个精品互动玩法”。
2. 顶部选择模板入口为 Tab，拼图 Tab 默认 `aria-selected=true`。
3. 创作 Tab 默认显示拼图创作表单内容，且不显示旧“Hi, 朋友”、输入框或智能创作快捷按钮。
4. 隐藏的智能创作类型不出现在模板 Tab、旧选择弹层和创作 Hub 卡片中。
5. 草稿页返回创作页后仍回到同一模板入口，并可保留拼图表单草稿内容。

102
docs/design/PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md Normal file
View File

@@ -0,0 +1,102 @@
# 平台移动端推荐、发现与草稿 Tab 改版设计
更新时间：`2026-05-05`
## 1. 目标
本次只调整平台入口的信息架构与移动端视觉，不新增后端接口：
1. 原“首页”一级 Tab 对用户改名为“推荐”，进入后直接展示原首页推荐榜单启动后的公开游戏内容流。
2. 原“首页”中的搜索、今日游戏、游戏分类等探索内容移动到第二个一级 Tab；第二个 Tab 对用户命名为“发现”。
3. 原“排行”页内容并入“发现”页的子 Tab 中，不再作为一级主 Tab 独立展示。
4. 创作页只保留新建创作入口；原创作页作品列表拆到一级“草稿” Tab，替换原“存档” Tab。
5. 原“存档”列表结构并入“我的”页面的“玩过”列表弹层，作为每个已玩作品的可继续存档入口。
6. 移动端推荐页与底部 Tab 栏参考用户给定样式，使用大画面推荐流、顶部品牌/通知、悬浮胶囊底部导航；保留当前平台已有明暗两套主题色 token。
## 2. 状态映射
为降低迁移风险，前端内部 `PlatformHomeTab` 仍复用既有状态值：
- `home`：用户看到“推荐”。
- `category`：用户看到“发现”，内容包含搜索、今日游戏、分类和排行子 Tab。
- `create`：用户看到“创作”，只承担新建入口。
- `saves`：用户看到“草稿”，承载原创作页作品列表。
- `profile`：用户看到“我的”，其中“玩过”弹层合并存档入口。
旧 `category` 状态此前承载“排行”，本次不改状态名，只改用户文案和页面内容，避免详情页返回目标、测试辅助和历史路由状态大范围迁移。
## 3. 推荐页
移动端推荐页默认不展示搜索和频道横滑条，进入一级“推荐”后直接渲染公开作品启动后的内容：
- 数据来源沿用 `featuredEntries + latestEntries` 去重后的公开作品列表。
- 首个可运行作品自动进入推荐页内嵌运行态，主视口不再展示作品封面卡。
- 主视口占据顶部栏与作品信息区之间的主要空间，使用平台主题 token 控制运行容器背景、边框、阴影、加载态文字和错误态按钮；亮色主题不得残留纯黑底白字加载块。
- 主视口下方展示当前作品的游玩、点赞、评论/改造等紧凑指标、作者头像、作者名与作品名，不写规则说明类文案。
- 作品信息区不再提供详情箭头或点击详情入口；点击该区域无效，上滑切换下一个推荐作品，下滑切换上一个推荐作品。
- 用户停留在推荐页时，底部当前 Tab 从“推荐”切换为“下一个”，图标使用向下的倒三角 / 双下箭头语义，点击后切换下一个推荐作品。
- 推荐页不再展示额外的底部作品切换块；当前作品的完整操作继续收敛在详情页和作品自身运行态中。
- 推荐页嵌入运行只调整平台外壳容器、主题注入和玩法壳层配色，不改写作品数据、关卡设定、道具设定或图片资产。
- 推荐页嵌入拼图玩法时隐藏拼图左上返回按钮，并在设置弹层中隐藏退出入口；作品切换前对当前拼图 run 执行既有“保存并退出”收口，正式 run 的交互状态以已写回后端的快照为准。
- 点赞、改造、复制作品号等完整操作继续收敛在详情页，详情入口由作品自身运行态或其它广场列表承接，推荐页作品信息区只负责展示和上下滑切换。
- 无数据、加载中、启动失败和暂不支持内嵌运行的作品沿用短状态文案。
桌面端仍保持现有首页布局，只把一级导航文案从“首页”改为“推荐”。
## 4. 发现页
发现页承接原首页探索能力和原排行能力，子 Tab 为：
1. 推荐：原首页推荐内容流，可作为发现页内的快速回看。
2. 今日：原首页“今日游戏”。
3. 分类：原首页“游戏分类”。
4. 排行：原一级“排行”页四榜切换。
移动端发现页顶部保留搜索框和子 Tab；分类内容继续使用纵向应用商店式列表；排行内容继续使用榜单行。
## 5. 创作与草稿
创作页只保留新建创作入口：
- 继续复用 `CustomWorldCreationStartCard` 和现有创作类型弹窗。
- 不在创作页下方展示作品列表，避免“创作入口”和“作品管理”挤在同一首屏。
草稿页复用创作中心作品架：
- 默认显示全部作品列表，保留草稿/已发布筛选。
- 入口、删除、分享、领取拼图激励等行为全部复用现有 `CustomWorldCreationHub` 的作品卡逻辑。
- 一级底部 Tab 文案为“草稿”，内部仍可按草稿与已发布筛选。
## 6. 我的页玩过列表
“我的”页面的“玩过”列表弹层合并存档结构：
- 顶部仍展示总游戏时长。
- 列表先展示可恢复存档，使用原 `SaveArchiveCard` 的字段结构和恢复行为。
- 再展示已玩作品统计列表，保持作品号、最近时间和时长。
- 若某个存档被点击，必须继续走既有后端恢复接口，不在前端拼接运行态。
## 7. 验收
1. 移动端底部导航非推荐页显示“推荐 / 发现 / 创作 / 草稿 / 我的”，未登录时显示“推荐 / 创作 / 发现”；停留在推荐页时当前 Tab 显示“下一个”。
2. 点击“推荐”直接看到公开作品启动后的内容，不再先看到搜索框、频道 Tab 或封面卡流。
3. 点击“发现”可看到搜索、推荐、今日、分类、排行子 Tab。
4. 点击“草稿”看到原创作页作品列表。
5. 点击“创作”只看到新建创作入口。
6. “我的”里的“玩过”弹层包含原存档列表入口，点击存档能继续恢复。
7. 移动端底部导航为悬浮胶囊样式，保留当前明暗主题色变量，不新增第三套主题。
8. 推荐页不出现额外底部作品卡或横滑切换块，运行视口、加载态和错误态跟随当前明暗主题。
9. 拼图玩法背景、HUD、按钮、弹窗、排行榜和相似作品卡跟随平台主题色；暗色主题仍保留深色游戏感，亮色主题不得出现大面积固定黑底。
10. 推荐页作品信息区点击无效，上滑切下一个、下滑切上一个；点击底部“下一个”也切下一个作品。
11. 仅推荐页嵌入拼图态隐藏返回与设置内退出入口；详情页、新手引导和普通拼图运行态继续保留原有退出能力。
12. 推荐页切换作品前，如果当前作品是拼图，必须先执行当前拼图 run 的退出收口，再启动下一作品。
## 8. 2026-05-07 未登录三栏补充
未登录状态下底部导航只显示 3 个入口，顺序调整为：
1. 推荐
2. 创作
3. 发现
创作 Tab 必须位于中间，并使用原推荐 Tab 的星光图标，保持几何和视觉上的主行动入口。推荐 Tab 改用游戏手柄图标，避免与创作图标重复。

31
docs/design/PUZZLE_RUNTIME_HEADER_AND_CLEAR_EFFECT_DESIGN_2026-04-27.md
View File

@@ -17,9 +17,8 @@
1. 左侧保留返回按钮。
2. 中间居中展示关卡主信息：
- 第一行：拼图关卡名
- 第二行：作者昵称
- 第三行：`第 N 关`
- 第一行：`第 N 关` 与拼图关卡名，二者保持同一行。
- 第二行：紧凑倒计时。
3. 右侧新增设置按钮。
同时移除以下冗余标识：
@@ -31,12 +30,33 @@
### 1.1 2026-04-30 顶栏与底部工具补充
1. 顶栏作者信息不再只显示一行作者名，必须展示为作者头像与昵称组合；当前运行态只提供昵称时，用昵称首字生成圆形占位头像。
2. 倒计时组件提升为顶栏中的强信息，字号、内边距和图标尺寸都需要明显大于作者昵称与关卡序号。
1. 历史口径曾要求顶栏展示作者头像与昵称；该要求已被 2026-05-08 精简口径替代，当前拼图棋盘 HUD 不再展示作者信息。
2. 倒计时组件保持为顶栏中的强信息，但需要采用紧凑尺寸，不得遮挡棋盘内容。
3. 底部只保留 `提示 / 原图 / 冻结` 三个功能按钮，并整体居中展示；三个按钮触控面积和图标字号都需要放大。
4. 底部不再展示“等待下一关候选”这类状态占位。通关后在三个道具按钮上方固定展示“下一关”按钮，展示条件只依赖当前关卡已通关，不依赖 `recommendedNextProfileId` 是否已有值。
5. 点击底部“下一关”按钮继续调用运行时壳层已有 `onAdvanceNextLevel` 事件；正式 run 由后端 `next-level` 选择候选，本地 run 由 `local-next-level` 生成或接续下一关，前端不在按钮层自行决定下一关来源。
### 1.2 2026-05-08 推荐页嵌入态 HUD 精简
1. 拼图运行时顶栏不再展示作者头像、作者昵称或作者首字占位，作者信息只在推荐页作品信息、详情页和排行榜等非棋盘 HUD 区域展示。
2. 顶部主信息压缩为两行：第一行 `第 N 关 + 关卡名`，第二行小号倒计时；倒计时不能使用此前的大号胶囊尺寸。
3. 返回按钮和设置按钮上移并缩小移动端基础尺寸，减少对棋盘顶部空间的占用。
4. 棋盘容器必须保留固定顶部安全区，确保关卡名和倒计时不会遮挡拼图内容。
5. 推荐页嵌入时只调整外壳间距和 HUD 布局，不改写作品关卡、作者、道具、时间限制或图片资产等作品设定。
### 1.3 2026-05-08 主题色联动
1. 拼图运行态根容器、背景、棋盘底色、顶部 HUD、底部工具栏、加载态、失败弹窗、通关弹窗、道具确认弹窗、设置弹窗和相似作品卡必须通过 `src/index.css` 中的 `--puzzle-runtime-*` 主题变量控制。
2. `platform-theme--light` 下拼图玩法背景应使用浅色平台底色与粉橙主色点缀，文字使用平台正文 token；不得继续使用固定 `bg-slate-950 text-white` 作为大面积底色。
3. `platform-theme--dark` 下可保留深色棋盘氛围，但按钮、选中态、倒计时、弹窗边框和推荐页加载态仍要从主题 token 取色，避免局部色板漂移。
4. 推荐页内嵌拼图时，父级必须保持 `platform-theme` 类可传递到 `PuzzleRuntimeShell`，不能让 runtime 脱离平台主题变量。
### 1.4 2026-05-08 推荐页嵌入态退出控制
1. 推荐页嵌入拼图时需要单独隐藏左上返回按钮和设置面板里的退出入口，避免把推荐流里的作品切换与普通退出混在一起。
2. 推荐页切换到下一作品前，平台外壳会先沿用现有“保存并退出”语义收口当前拼图 run，再进入新作品。
3. 该隐藏规则只作用于推荐页嵌入态，不影响详情页、新手引导或普通拼图入口。
### 2. 拼图块显示规则
运行时单块右下角编号全部移除。
@@ -45,6 +65,7 @@
1. 玩家需要优先依赖画面主体、构图和色块识别位置。
2. 编号覆盖会削弱“完整图片被逐步复原”的视觉奖励。
3. 合成后的拼图块只保留原图切片、外轮廓描边和必要的拖拽层级，不叠加额外的色块、暗层或蒙版，避免破坏原图识别。
### 3. 设置能力

2
docs/design/README.md
View File

@@ -12,6 +12,8 @@
- [MOBILE_CREATION_NEW_WORK_COMPACT_LAYOUT_2026-04-24.md](./MOBILE_CREATION_NEW_WORK_COMPACT_LAYOUT_2026-04-24.md)：移动端创作页新建作品模块最多占用首屏约 1/3 高度的紧凑布局设计。
- [MOBILE_CREATION_WORK_LIST_TWO_COLUMN_LAYOUT_2026-04-29.md](./MOBILE_CREATION_WORK_LIST_TWO_COLUMN_LAYOUT_2026-04-29.md)：移动端创作页作品列表至少 2 列的紧凑布局设计。
- [PLATFORM_HOME_MOBILE_FEED_CARD_REDESIGN_2026-04-28.md](./PLATFORM_HOME_MOBILE_FEED_CARD_REDESIGN_2026-04-28.md)：平台首页移动端参考图式信息流、双端公开作品卡 16:9 封面结构与点赞数读模型设计。
- [PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md](./PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md)：平台移动端推荐、发现、创作、草稿、我的 Tab 重新分工与推荐页/底部导航改版设计。
- [PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md](./PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md)：平台创作 Tab 恢复模板 Tab 入口、默认选中拼图并内嵌拼图创作表单的布局设计。
- [PLATFORM_CATEGORY_AND_CREATE_TAB_DESIGN_2026-04-24.md](./PLATFORM_CATEGORY_AND_CREATE_TAB_DESIGN_2026-04-24.md)：平台入口新增分类 Tab、登录态导航裁剪与创作 Tab 视觉强化设计。
- [PLATFORM_BIG_FISH_ENTRY_HIDE_2026-04-28.md](./PLATFORM_BIG_FISH_ENTRY_HIDE_2026-04-28.md)：平台入口暂时隐藏大鱼吃小鱼创作卡片，但保留现有玩法链路。
- [UNIFIED_MODAL_WINDOW_DESIGN_2026-04-25.md](./UNIFIED_MODAL_WINDOW_DESIGN_2026-04-25.md)：统一平台风与 RPG 像素风模态窗口外壳、交互边界和迁移顺序。

BIN
docs/design/assets/puzzle-creation-mobile-ui-reference-gpt-image-2-2026-05-08-v2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 943 KiB

BIN
docs/design/assets/puzzle-creation-mobile-ui-reference-gpt-image-2-2026-05-08.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 999 KiB

5
docs/experience/AGENT_UI_CHANGELOG.md
View File

@@ -118,6 +118,11 @@
- 早期方案曾在 `AuthGate` 层提供右上角全局账号信息条，并在 `GameShellRuntime` 中临时隐藏。
- 2026-04-20 起，这个全局悬浮入口已整体下线，不再区分“平台显示 / 冒险隐藏”。
- 原因是右上角高频观察区不适合承载账号入口，且平台内已经有更明确的页面内入口。
## 9. 2026-05-08 创作首页通知入口下线
- `CreativeAgentHome` 顶栏右上角不再展示“通知与账户”按钮，避免创作首页把通知入口放在首屏高频区域。
- 账号入口仍保留在侧边栏底部，创作首页顶栏维持左侧菜单、居中品牌的轻量结构。
- 当前账号相关入口统一保留在平台首页受保护动作、个人页、存档页与账号弹窗，不再占用全局悬浮层。
---

5
docs/experience/MOBILE_UI_DEV_EXPERIENCE.md
View File

@@ -221,3 +221,8 @@
- 后续新增怪物资源时，先检查红圈标注的实际落点，再调整锚点分档或单怪物偏移，避免出现“悬在地面上方”的状态。
- 自定义世界里敌对角色已经先作为场景 NPC 存在，即使它同时携带 `characterId` 和 `monsterPresetId`，画布也不能直接沿用模板角色的 `groundOffsetY`；只要 encounter 自身有 `imageSrc` 或 `visual`，就按场景 NPC 自定义形象锚点处理。
- 幕预览运行时还会构造“无 `characterId`、但有 `visual` 的场景 NPC”，这类和平相遇分支同样必须套用场景 NPC 自定义形象锚点，否则会停在画面中上部。
### 10.3 移动端固定整页画布缩放
- 主站移动端以固定游戏画布体验为准，入口 `viewport` 需要锁定 `minimum-scale=1.0`、`maximum-scale=1.0` 和 `user-scalable=no`，同时保留 `viewport-fit=cover` 适配安全区。
- 浏览器仍可能通过 iOS `gesture*` 或多指 `touchmove` 触发整页缩放，因此主站启动入口应统一调用 `lockMobileViewportZoom()` 拦截页面级捏合与快速双击缩放。
- 不要在每个画布组件里重复注册缩放拦截；单指滚动、点击、拖拽应继续留给具体页面和玩法处理。

1
docs/experience/README.md
View File

@@ -29,6 +29,7 @@
- [RPG_DRAFT_IMAGE_PARALLEL_GENERATION_2026-04-24.md](./RPG_DRAFT_IMAGE_PARALLEL_GENERATION_2026-04-24.md)：记录 RPG 底稿阶段角色主形象与场景背景图并行生成约束。
- [PLATFORM_HOME_BANNER_IMAGE_SIZE_FIX_2026-04-25.md](./PLATFORM_HOME_BANNER_IMAGE_SIZE_FIX_2026-04-25.md)：记录首页 banner 背景图不能进入普通布局流的修复经验。
- [RPG_PUBLISH_GALLERY_REFRESH_FIX_2026-04-25.md](./RPG_PUBLISH_GALLERY_REFRESH_FIX_2026-04-25.md)：记录 RPG 发布后首页 / 分类页公开作品列表刷新链路。
- [VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md](./VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md)：记录视觉小说模板交接时的阅读顺序、常见坑和维护检查口径。
- [AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md](./AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md)：记录 Agent 空会话不应进入作品草稿列表的后端判定规则。
- [BIG_FISH_PUBLISH_FEEDBACK_FIX_2026-04-26.md](./BIG_FISH_PUBLISH_FEEDBACK_FIX_2026-04-26.md)：记录大鱼吃小鱼发布成功后结果页反馈与作品列表刷新的修复口径。
- [BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md](./BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md)：记录大鱼作品列表 `items_json` 字段升级后的向后兼容修复口径，避免旧 JSON 直接打崩 works 接口。

48
docs/experience/VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md Normal file
View File

@@ -0,0 +1,48 @@
# 视觉小说模板交接与维护经验 2026-05-07
## 1. 先读什么
新开发者接手视觉小说时，建议按这个顺序看：
1. [AI 原生视觉小说模板 PRD](../prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)
2. [视觉小说模板实现收口与交接说明](../technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md)
3. [SpacetimeDB 表说明与查询目录](../technical/SPACETIMEDB_TABLE_CATALOG.md)
4. [视觉小说 VN-03 Prompt 与 LLM 工具实现说明](../technical/VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md)
5. [视觉小说 VN-11 负向扫描报告](../audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md)
## 2. 最容易踩的坑
1. 不要把 `visual_novel_runtime_history_entry` 当回放表来扩。
2. 不要把 `visual_novel_runtime_event` 当业务回放数据源来用。
3. 不要绕过平台资产对象去保存图片、音乐或文档。
4. 不要让旧 TXT 迁移文档重新变成实现口径。
5. 不要忘记发布后刷新作品架和公开聚合。
6. 不要忘记退出登录时清理视觉小说私有状态。
## 3. 维护时的判断顺序
1. 先看是不是共享契约变化。
2. 再看是不是 SpacetimeDB 表或 facade 变化。
3. 然后看是不是作品架、广场或 runtime 的前端分流变化。
4. 最后才看文档措辞和历史说明。
## 4. 常用检查
```bash
npm run check:encoding
npm run check:visual-novel-vn11
npm run typecheck
```
如果改了后端，再补：
```bash
cd server-rs
cargo test -p shared-contracts
cargo test -p module-visual-novel
cargo check -p api-server
```
## 5. 一句话结论
视觉小说模板已经是平台内的正式模板玩法，不是外部平台迁移；后续维护只需要沿着 PRD、表目录、prompt 文档和这份交接说明往下走。

863
docs/prd/AI_NATIVE_2048_GAMEPLAY_TEMPLATE_PRD_2026-05-05.md Normal file
View File

@@ -0,0 +1,863 @@
# AI 原生 2048 游戏玩法模板 PRD
更新时间：`2026-05-05`
## 0. 文档目的
这份 PRD 用于在当前平台内新增一条 `2048` 游戏玩法模板，并冻结它从创作入口、Agent 生成、结果页编辑、试玩、发布、公开运行到作品架展示的完整产品边界。
本次不是只做一个浏览器本地 2048 小游戏，也不是把经典 2048 规则随手写进某个前端组件。正式落地时，`2048` 必须作为平台内独立玩法类型接入现有创作中心、作品、广场、运行态和后端 DDD 分层。
---
## 1. 一句话定义
`2048` 是一个主题化数字合成玩法模板：百梦主通过 Agent 设定棋盘主题、合成链、视觉皮肤、目标格和难度参数，系统生成可试玩、可发布的 2048 作品；玩家通过滑动方向移动棋盘格，相同等级方块合并升级，直到达成目标格或棋盘无可行动作。
---
## 2. 当前接入级别
根据 `genarrative-play-type-integration` 的接入分级，本玩法按 **完整玩法闭环** 设计：
1. 新增玩法 ID：`twenty-forty-eight`。
2. 展示名称：`2048`。
3. 子标题：`主题合成棋盘`。
4. 新建作品入口可展示，开放节奏由 `src/config/newWorkEntryConfig.ts` 控制。
5. 支持 Agent 创作、草稿生成、结果页编辑、试玩、发布、公开运行、作品架和广场。
6. 后端以 `server-rs + Axum + SpacetimeDB` 为服务侧真相源。
7. 前端负责棋盘渲染、输入采集和动画表现，不绕过后端保存正式运行结果、榜单、扣费和发布状态。
工程命名采用 `twenty-forty-eight` 而不是裸 `2048`，避免 TypeScript、Rust 模块、文件名和路由中出现数字开头命名；面向用户的标题始终显示 `2048`。
---
## 3. 产品定位
## 3.1 模板名称
1. 对外模板名称：`2048`。
2. 对外子标题：`主题合成棋盘`。
3. 开发代号：`TwentyFortyEight`。
4. 工程玩法域：`twenty-forty-eight`。
5. 后端模块命名：`twenty_forty_eight`。
6. 公开作品号前缀：`TF-`。
## 3.2 核心乐趣
1. 玩家通过一次滑动改变整盘局势。
2. 相同方块合并升级，形成清晰的成长反馈。
3. 主题化合成链让数字升级变成可感知的叙事或收藏序列。
4. 棋盘越来越拥挤，玩家在空间管理和短期收益之间做取舍。
5. 达成目标格后可以继续冲击更高分，也可以结算分享成绩。
## 3.3 与现有玩法的区别
1. 不等同于拼图：不切图、不交换、不合并图片碎片。
2. 不等同于抓大鹅：不做三消备选栏，不做物体堆叠点击。
3. 不等同于方洞挑战：不做单次投放裁决，不靠反直觉规则制造误导。
4. 不等同于大鱼吃小鱼：不做实时移动、吞噬和碰撞成长。
5. 不复用 RPG 的世界、角色、章节或剧情推进结构。
---
## 4. 完整闭环目标
本玩法完整闭环必须补齐：
1. 平台创作中心选择 `2048`。
2. Agent 对话收集主题、合成链、视觉风格、目标格和难度。
3. 生成 2048 草稿。
4. 进入结果页编辑作品名、简介、标签、封面、棋盘配置和方块皮肤。
5. 支持发布前试玩。
6. 发布作品。
7. 玩家从作品详情、广场或作品架进入运行态。
8. 后端初始化 run，保存种子、当前棋盘、分数、目标、状态和动作序列摘要。
9. 玩家滑动方向后，前端提交动作，后端裁决新棋盘；前端按返回快照播放移动与合并动画。
10. 达成目标、继续挑战、失败结算和排行榜写入都由后端正式裁决。
11. 前端不得自行提交伪造分数、目标达成或榜单记录。
---
## 5. 明确不做
首版不做：
1. 不做多人实时对战。
2. 不做复杂技能树或 RPG 数值养成。
3. 不做可破坏障碍、棋盘机关和随机事件。
4. 不支持玩家自定义任意 JavaScript 规则。
5. 不在 UI 中默认展示长篇玩法说明、规则描述或内部字段解释。
6. 不新增独立于平台之外的 2048 站点。
7. 不复用 `customWorld`、`rpgWorld` 或旧 `server-node` 命名承载 2048 业务。
8. 不把 LLM、生图、OSS 上传放进 SpacetimeDB reducer。
---
## 6. 创作锚点设计
Agent 型创作至少收集下面 5 个锚点：
| 锚点 | 字段建议 | 用途 |
| --- | --- | --- |
| 合成主题 | `themePrompt` | 决定棋盘整体题材，例如修仙境界、猫咪成长、城市建设、料理升级。 |
| 合成链 | `tileLadder` | 决定从 `2` 到目标格的每一级显示名、图标提示和视觉差异。 |
| 视觉皮肤 | `visualStyle` | 决定方块材质、色彩、背景、动效气质和封面方向。 |
| 难度参数 | `difficultyConfig` | 决定棋盘尺寸、目标格、初始方块、生成概率和是否允许撤销。 |
| 反馈节奏 | `feedbackRhythm` | 决定移动、合并、升级、目标达成、失败结算的反馈强度。 |
Agent 行为要求：
1. 优先接住百梦主的一句话灵感，不把创作变成问卷。
2. 每轮最多追问 1 个最影响成品质量的问题。
3. 当主题和合成链已经足够明确时，优先生成草稿。
4. 合成链必须围绕同一主题递进，不允许出现互不相关的方块名。
5. 进入结果页前至少生成 `2` 到目标格之间的完整等级定义。
---
## 7. 玩法规则
## 7.1 棋盘
首版默认支持：
1. `4x4` 标准棋盘。
2. 可选 `5x5` 放松棋盘。
3. 可选 `3x3` 高压棋盘。
发布默认值：
1. `boardSize = 4`。
2. `targetTileValue = 2048`。
3. 初始方块数量为 `2`。
4. 新方块生成值为 `2` 或 `4`。
5. `2` 的生成概率为 `90%`，`4` 的生成概率为 `10%`。
## 7.2 输入
玩家每次只能提交一个方向：
```ts
type TwentyFortyEightMoveDirection = 'up' | 'down' | 'left' | 'right';
```
交互支持：
1. 移动端滑动。
2. 桌面端方向键。
3. 桌面端按钮或触控手势兜底。
无效输入规则：
1. 如果某方向不会改变棋盘，该动作不消耗步数。
2. 无效动作返回当前快照和 `moveAccepted = false`。
3. 前端只展示轻量反馈，不弹长说明。
## 7.3 合并
合并规则遵循经典 2048：
1. 同一行或列按移动方向压缩。
2. 相邻且同值的两个方块合并成一个更高值方块。
3. 每个方块在一次移动中最多合并一次。
4. 合并后的方块值为原值的 `2` 倍。
5. 本次得分增加合并后方块值。
6. 移动完成后，如果棋盘有变化，随机空格生成一个新方块。
规则核心应封装为可测试的领域引擎。实现时优先评估成熟 2048 规则库；如 Rust / TypeScript 生态无合适库，必须把自研规则收敛在 `module-twenty-forty-eight` 的纯函数内，并用黄金用例、属性测试和前后端 fixture 保证一致。
## 7.4 胜负
状态取值：
```ts
type TwentyFortyEightRunStatus =
| 'playing'
| 'target_reached'
| 'continued_after_target'
| 'game_over'
| 'abandoned';
```
规则：
1. 首次出现 `targetTileValue` 时进入 `target_reached`。
2. 玩家可选择结算，或继续挑战。
3. 继续挑战后状态变为 `continued_after_target`。
4. 棋盘无空格且四个方向都无法移动时进入 `game_over`。
5. 玩家主动退出未结算时为 `abandoned`。
---
## 8. 草稿与结果页
## 8.1 结果页定位
2048 结果页是发布前的最小工作台，承担：
1. 编辑作品基本信息。
2. 编辑棋盘参数。
3. 编辑合成链显示名和视觉提示。
4. 生成或上传封面。
5. 进入试玩。
6. 发布作品。
## 8.2 必备字段
```ts
interface TwentyFortyEightResultDraft {
workTitle: string;
workDescription: string;
workTags: string[];
coverImageSrc: string | null;
coverAssetId: string | null;
themePrompt: string;
visualStyle: string;
boardConfig: TwentyFortyEightBoardConfig;
tileLadder: TwentyFortyEightTileDefinition[];
scoringConfig: TwentyFortyEightScoringConfig;
}
interface TwentyFortyEightBoardConfig {
boardSize: 3 | 4 | 5;
targetTileValue: 512 | 1024 | 2048 | 4096 | 8192;
initialTileCount: 2 | 3 | 4;
spawnValueWeights: Array<{ value: 2 | 4; weight: number }>;
allowUndo: boolean;
maxUndoCount: number;
}
interface TwentyFortyEightTileDefinition {
value: number;
label: string;
shortLabel: string;
colorToken: string;
iconPrompt: string;
imageSrc: string | null;
assetId: string | null;
}
interface TwentyFortyEightScoringConfig {
scoreMode: 'classic';
leaderboardMetric: 'score_then_steps' | 'score_then_time';
}
```
## 8.3 字段约束
1. `workTitle` 必填，建议 `4~16` 个中文字符。
2. `workDescription` 必填，建议 `12~80` 个中文字符。
3. `workTags` 必须为 `3~6` 个中文短标签。
4. `boardSize` 首版只能是 `3`、`4`、`5`。
5. `targetTileValue` 必须存在于 `tileLadder`。
6. `tileLadder` 必须从 `2` 开始按倍增连续覆盖到目标格。
7. `shortLabel` 移动端格子内最多建议 `4` 个中文字符。
8. `spawnValueWeights` 权重和必须大于 `0`，归一化后用于后端生成。
9. `allowUndo = true` 时 `maxUndoCount` 必须在 `1~3`。
## 8.4 结果页 UI
结果页采用移动端优先的页签结构：
1. `基本信息`：标题、简介、标签。
2. `棋盘`：棋盘尺寸、目标格、撤销次数、生成概率。
3. `合成链`：每级方块的显示名、短标签、颜色和图标预览。
4. `封面`：封面预览、生成、上传或历史素材选择。
交互要求：
1. 发布按钮放在结果页右下操作区，移动端固定在底部安全区。
2. 试玩按钮与发布按钮并列，但试玩不触发发布阻断。
3. 发布校验只在点击发布后进入独立发布面板展示。
4. 合成链编辑使用独立面板或抽屉，不在当前列表下方展开大表单。
5. 页面不默认展示玩法规则说明。
---
## 9. 作品发布与广场
## 9.1 发布阻断
发布前必须校验：
1. 作品标题非空。
2. 简介非空。
3. 标签数量为 `3~6`。
4. 棋盘配置合法。
5. 合成链完整覆盖到目标格。
6. 目标格存在。
7. 封面存在。
8. 作者信息可读。
## 9.2 作品摘要
```ts
interface TwentyFortyEightWorkSummary {
workId: string;
profileId: string;
ownerUserId: string;
authorDisplayName: string;
gameName: string;
summary: string;
tags: string[];
coverImageSrc: string;
boardSize: 3 | 4 | 5;
targetTileValue: number;
bestScore: number | null;
playCount: number;
likeCount: number;
sourceSessionId: string;
publicationStatus: 'draft' | 'published';
updatedAt: string;
publishedAt: string | null;
}
```
## 9.3 广场卡片
广场卡片至少展示：
1. 封面。
2. 作品名。
3. 作者名。
4. 标签。
5. 棋盘规格和目标格。
6. 进入游戏按钮。
不在卡片内展示完整规则说明。
---
## 10. 运行态设计
## 10.1 首屏
运行态首屏必须直接展示棋盘：
1. 顶部 HUD：分数、最高格、目标格、步数。
2. 中部正方形棋盘。
3. 底部轻量操作区：撤销、重新开始、退出。
4. 移动端棋盘尽量贴近屏幕两侧安全边界。
5. 桌面端棋盘居中，不使用营销式大卡片布局。
## 10.2 运行快照
```ts
interface TwentyFortyEightRunSnapshot {
runId: string;
profileId: string;
ownerUserId: string;
status: TwentyFortyEightRunStatus;
seed: string;
board: TwentyFortyEightBoardSnapshot;
score: number;
bestTileValue: number;
moveCount: number;
undoRemaining: number;
targetTileValue: number;
reachedTargetAtMove: number | null;
startedAtMs: number;
updatedAtMs: number;
endedAtMs: number | null;
lastMove: TwentyFortyEightMoveResult | null;
work: TwentyFortyEightWorkSummary;
}
interface TwentyFortyEightBoardSnapshot {
size: 3 | 4 | 5;
cells: TwentyFortyEightCellSnapshot[];
}
interface TwentyFortyEightCellSnapshot {
row: number;
col: number;
tile: TwentyFortyEightTileSnapshot | null;
}
interface TwentyFortyEightTileSnapshot {
tileId: string;
value: number;
mergedFromTileIds: string[];
spawnedAtMove: number;
}
interface TwentyFortyEightMoveResult {
direction: TwentyFortyEightMoveDirection;
moveAccepted: boolean;
scoreDelta: number;
spawnedTile: TwentyFortyEightTileSnapshot | null;
mergedTileIds: string[];
}
```
## 10.3 前后端职责
前端负责：
1. 渲染棋盘、HUD、结算面板。
2. 采集滑动、键盘和按钮输入。
3. 根据后端返回的 `lastMove` 播放移动、合并和生成动画。
4. 做乐观动画可以，但必须以服务端快照回正。
前端不负责：
1. 保存正式分数。
2. 写入榜单。
3. 伪造目标达成。
4. 绕过后端生成新方块。
5. 自行发布作品状态。
后端负责：
1. 创建 run。
2. 按 seed 初始化棋盘。
3. 裁决每次移动。
4. 生成新方块。
5. 保存分数、步数、最高格和状态。
6. 裁决目标达成、继续挑战、失败和放弃。
7. 写入排行榜和埋点事件。
---
## 11. 后端分层边界
正式实现必须遵循当前 `server-rs + Axum + SpacetimeDB` 路线：
1. `server-rs/crates/module-twenty-forty-eight`
- 纯领域规则、棋盘移动、合并裁决、随机种子输入、分数计算、发布校验。
- 不依赖 Axum、SpacetimeDB、OSS 或 LLM。
2. `server-rs/crates/shared-contracts`
- 暴露 Agent、作品、运行态、广场 DTO。
3. `server-rs/crates/spacetime-module`
- 存储 session、message、work profile、runtime run、leaderboard、event。
- 表结构变化必须同步 `migration.rs` 与表目录。
4. `server-rs/crates/spacetime-client`
- 提供 api-server 调用 SpacetimeDB 的 typed facade。
5. `server-rs/crates/api-server`
- 暴露 `/api/creation/twenty-forty-eight/*` 与 `/api/runtime/twenty-forty-eight/*`。
- 处理鉴权、错误 envelope、LLM turn、生图编排、OSS 资产和 HTTP facade。
6. `platform-llm` / `platform-oss`
- 分别承载外部模型和资产副作用。
涉及 SpacetimeDB 的表、reducer、procedure、绑定生成、前端 SDK 接入时，必须按 `spacetimedb-cli`、`spacetimedb-rust`、`spacetimedb-concepts`、`spacetimedb-typescript` 约束执行。
---
## 12. SpacetimeDB 表建议
首版建议新增：
1. `twenty_forty_eight_agent_session`
2. `twenty_forty_eight_agent_message`
3. `twenty_forty_eight_work_profile`
4. `twenty_forty_eight_runtime_run`
5. `twenty_forty_eight_leaderboard_entry`
6. `twenty_forty_eight_event`
表职责：
| 表 | 职责 |
| --- | --- |
| `twenty_forty_eight_agent_session` | 创作会话、阶段、草稿、已发布 profile 绑定。 |
| `twenty_forty_eight_agent_message` | Agent 对话消息和流式 turn 结果。 |
| `twenty_forty_eight_work_profile` | 作品草稿、发布状态、封面、棋盘配置、合成链和统计投影。 |
| `twenty_forty_eight_runtime_run` | 单次运行快照、动作摘要、分数、状态和结算时间。 |
| `twenty_forty_eight_leaderboard_entry` | 按作品、用户、棋盘规格和目标格记录最好成绩。 |
| `twenty_forty_eight_event` | 发布、试玩、开始、移动、达成目标、失败、结算等审计事件。 |
reducer / procedure 不允许调用 LLM、OSS、生图、HTTP 或非确定性外部服务。
---
## 13. API 设计
## 13.1 创作接口
统一前缀：
```text
/api/creation/twenty-forty-eight
```
建议接口：
1. `POST /api/creation/twenty-forty-eight/sessions`
2. `GET /api/creation/twenty-forty-eight/sessions/{sessionId}`
3. `POST /api/creation/twenty-forty-eight/sessions/{sessionId}/messages`
4. `POST /api/creation/twenty-forty-eight/sessions/{sessionId}/messages/stream`
5. `POST /api/creation/twenty-forty-eight/sessions/{sessionId}/actions`
6. `POST /api/creation/twenty-forty-eight/sessions/{sessionId}/compile`
7. `GET /api/creation/twenty-forty-eight/works`
8. `GET /api/creation/twenty-forty-eight/works/{profileId}`
9. `PUT /api/creation/twenty-forty-eight/works/{profileId}`
10. `POST /api/creation/twenty-forty-eight/works/{profileId}/publish`
11. `DELETE /api/creation/twenty-forty-eight/works/{profileId}`
## 13.2 运行接口
统一前缀：
```text
/api/runtime/twenty-forty-eight
```
建议接口：
1. `GET /api/runtime/twenty-forty-eight/gallery`
2. `GET /api/runtime/twenty-forty-eight/gallery/{profileId}`
3. `POST /api/runtime/twenty-forty-eight/works/{profileId}/runs`
4. `GET /api/runtime/twenty-forty-eight/runs/{runId}`
5. `POST /api/runtime/twenty-forty-eight/runs/{runId}/moves`
6. `POST /api/runtime/twenty-forty-eight/runs/{runId}/undo`
7. `POST /api/runtime/twenty-forty-eight/runs/{runId}/continue`
8. `POST /api/runtime/twenty-forty-eight/runs/{runId}/restart`
9. `POST /api/runtime/twenty-forty-eight/runs/{runId}/abandon`
10. `POST /api/runtime/twenty-forty-eight/runs/{runId}/leaderboard`
移动请求：
```ts
interface TwentyFortyEightMoveRequest {
clientActionId: string;
direction: TwentyFortyEightMoveDirection;
baseSnapshotVersion: number;
}
```
响应：
```ts
interface TwentyFortyEightMoveResponse {
snapshot: TwentyFortyEightRunSnapshot;
}
```
---
## 14. 前端落点
建议新增：
```text
src/components/twenty-forty-eight-creation/TwentyFortyEightAgentWorkspace.tsx
src/components/twenty-forty-eight-result/TwentyFortyEightResultView.tsx
src/components/twenty-forty-eight-runtime/TwentyFortyEightRuntimeShell.tsx
src/components/twenty-forty-eight-runtime/TwentyFortyEightBoard.tsx
src/components/twenty-forty-eight-runtime/TwentyFortyEightHud.tsx
src/services/twenty-forty-eight-creation/twentyFortyEightCreationClient.ts
src/services/twenty-forty-eight-works/twentyFortyEightWorksClient.ts
src/services/twenty-forty-eight-runtime/twentyFortyEightRuntimeClient.ts
src/services/twenty-forty-eight-gallery/twentyFortyEightGalleryClient.ts
```
平台入口接入时需要扩展：
1. `src/config/newWorkEntryConfig.ts`
2. `src/components/platform-entry/platformEntryTypes.ts`
3. `src/components/platform-entry/platformEntryCreationTypes.ts`
4. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
5. `src/components/custom-world-home/creationWorkShelf.ts`
6. `src/services/publicWorkCode.ts`
新增 selection stage：
```ts
| 'twenty-forty-eight-agent-workspace'
| 'twenty-forty-eight-result'
| 'twenty-forty-eight-runtime'
| 'twenty-forty-eight-gallery-detail'
```
---
## 15. UI 要求
## 15.1 创作入口
入口卡片只表达：
1. `2048`
2. `主题合成棋盘`
3. 开放状态
不在入口卡片里堆规则说明。
## 15.2 Agent 工作台
工作台结构：
1. 对话流。
2. 当前锚点摘要。
3. 生成草稿动作。
4. 进入结果页动作。
不展示世界观、角色、地点等 RPG 重结构。
## 15.3 运行态
运行态设计原则：
1. 棋盘是绝对主角。
2. 移动端优先，单手可滑动。
3. HUD 信息克制，只显示分数、目标、步数和最高格。
4. 撤销、重新开始、退出使用 icon button 或短按钮。
5. 目标达成、失败和排行榜使用独立弹窗或底部面板。
6. 不把弹出面板实现成当前面板下方追加内容。
---
## 16. 测试与验收
## 16.1 领域测试
必须覆盖：
1. 向左移动压缩。
2. 向右移动压缩。
3. 单次移动中每个方块最多合并一次。
4. 合并得分计算。
5. 无效移动不生成新方块。
6. 有效移动按 seed 生成新方块。
7. 目标格达成。
8. 无可行动作进入失败。
9. 撤销次数消耗和快照恢复。
## 16.2 API 测试
必须覆盖：
1. 未登录不能创建作品和 run。
2. 创建 session。
3. 编译草稿。
4. 发布校验阻断。
5. 创建 run。
6. 提交 move 后返回新快照。
7. 无效 move 不增加步数。
8. 达成目标后可继续挑战。
9. 失败后不能继续提交 move。
10. 排行榜只接受后端已结算 run。
## 16.3 前端测试
必须覆盖：
1. 入口展示与点击分流。
2. Agent 工作台打开。
3. 结果页编辑棋盘参数和合成链。
4. 试玩进入运行态。
5. 移动端滑动提交方向。
6. 键盘方向键提交方向。
7. 无效移动反馈。
8. 目标达成弹窗。
9. 失败结算弹窗。
## 16.4 建议验证命令
按改动范围执行：
```bash
npm run check:encoding
npm run typecheck
npm run test
cd server-rs
cargo test -p shared-contracts twenty_forty_eight
cargo test -p module-twenty-forty-eight
cargo check -p api-server
```
涉及 SpacetimeDB 表变化后：
```bash
npm run spacetime:generate -- --rust-only
npm run check:server-rs-ddd
```
涉及 API smoke 时：
```bash
npm run api-server
```
启动后确认：
```text
GET /healthz
POST /api/creation/twenty-forty-eight/sessions
POST /api/runtime/twenty-forty-eight/works/{profileId}/runs
POST /api/runtime/twenty-forty-eight/runs/{runId}/moves
```
---
## 17. 并行任务拆分
## 任务 A：契约与共享类型
写入范围：
```text
packages/shared/src/contracts/twentyFortyEightAgent.ts
packages/shared/src/contracts/twentyFortyEightWorks.ts
packages/shared/src/contracts/twentyFortyEightRuntime.ts
packages/shared/src/contracts/twentyFortyEightGallery.ts
server-rs/crates/shared-contracts/src/twenty_forty_eight_agent.rs
server-rs/crates/shared-contracts/src/twenty_forty_eight_works.rs
server-rs/crates/shared-contracts/src/twenty_forty_eight_runtime.rs
server-rs/crates/shared-contracts/src/twenty_forty_eight_gallery.rs
```
验收：
```bash
npm run typecheck
cd server-rs
cargo test -p shared-contracts twenty_forty_eight
```
## 任务 B：领域规则模块
写入范围：
```text
server-rs/crates/module-twenty-forty-eight/src/domain.rs
server-rs/crates/module-twenty-forty-eight/src/application.rs
server-rs/crates/module-twenty-forty-eight/src/rule_engine.rs
server-rs/crates/module-twenty-forty-eight/src/random.rs
server-rs/crates/module-twenty-forty-eight/src/lib.rs
```
验收：
```bash
cd server-rs
cargo test -p module-twenty-forty-eight
```
## 任务 C：SpacetimeDB 表与 facade
写入范围：
```text
server-rs/crates/spacetime-module/src/twenty_forty_eight.rs
server-rs/crates/spacetime-module/src/lib.rs
server-rs/crates/spacetime-module/src/migration.rs
server-rs/crates/spacetime-client/src/twenty_forty_eight.rs
docs/technical/SPACETIMEDB_TABLE_CATALOG.md
```
验收：
```bash
npm run spacetime:generate -- --rust-only
npm run check:server-rs-ddd
cd server-rs
cargo check -p spacetime-module
cargo check -p spacetime-client
```
## 任务 D：API / SSE facade
写入范围：
```text
server-rs/crates/api-server/src/twenty_forty_eight.rs
server-rs/crates/api-server/src/twenty_forty_eight_sse.rs
server-rs/crates/api-server/src/app.rs
server-rs/crates/api-server/src/state.rs
```
验收：
```bash
cd server-rs
cargo check -p api-server
npm run api-server
```
## 任务 E：前端创作、结果页与运行态
写入范围：
```text
src/config/newWorkEntryConfig.ts
src/components/platform-entry/*
src/components/twenty-forty-eight-creation/*
src/components/twenty-forty-eight-result/*
src/components/twenty-forty-eight-runtime/*
src/services/twenty-forty-eight-*
```
验收：
```bash
npm run typecheck
npm run test -- twenty
npm run check:encoding
```
## 任务 F：作品架、广场、分享与回归
写入范围：
```text
src/components/custom-world-home/creationWorkShelf.ts
src/services/publicWorkCode.ts
src/components/common/PublishShareModal.tsx
src/components/twenty-forty-eight-gallery/*
docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md
docs/technical/SPACETIMEDB_TABLE_CATALOG.md
```
验收：
```bash
npm run typecheck
npm run test
npm run check:encoding
```
---
## 18. 最小上线清单
1. `twenty-forty-eight` 入口可展示并进入工作台。
2. Agent 可生成主题化 2048 草稿。
3. 结果页可编辑基本信息、棋盘配置和合成链。
4. 结果页可试玩。
5. 运行态可完成标准 2048 移动、合并、生成新方块、目标达成和失败。
6. 发布后作品进入作品架和广场。
7. 玩家可从广场进入公开 run。
8. 榜单只记录后端裁决的正式成绩。
9. 前后端契约字段 camelCase / snake_case 映射明确。
10. SpacetimeDB 表、migration、表目录和 bindings 同步。
---
## 19. 验收标准
当下面结果都成立时，视为 `2048` 玩法模板落地完成：
1. 平台有独立 `2048` 创作入口。
2. 玩法 ID 使用 `twenty-forty-eight`。
3. 能进入 2048 Agent 工作台。
4. 能通过 Agent 生成草稿。
5. 结果页可编辑作品名、简介、标签、棋盘参数、合成链和封面。
6. 发布校验能阻断非法草稿。
7. 试玩能进入 2048 运行态。
8. 运行态支持移动端滑动和桌面方向键。
9. 后端能裁决移动、合并、得分、新方块生成和胜负。
10. 无效移动不增加步数，不生成新方块。
11. 达成目标后可结算或继续挑战。
12. 失败后不能继续提交移动。
13. 发布作品能进入作品架、广场和分享链路。
14. 排行榜只接受正式 run 的后端结算成绩。
15. 新增表结构同步 `migration.rs`、表目录和 bindings。
16. UI 不默认展示长篇规则说明，不把独立弹窗做成面板下方展开。
17. 移动端和桌面端都能正常显示和操作。
---
## 20. 一句话结论
`2048` 在 Genarrative 中应被做成一个可创作、可换皮、可发布、可排行的主题合成棋盘模板：创作端让百梦主定义合成链和视觉承诺，运行端保持经典 2048 的滑动合并手感，服务端负责正式棋盘裁决、作品状态和成绩真相。

5
docs/prd/AI_NATIVE_CUSTOM_WORLD_CREATION_HUB_PRD_2026-04-13.md
View File

@@ -468,8 +468,9 @@ interface CustomWorldCoverProfile {
1. 上传后先进入独立裁剪面板
2. 裁剪框比例固定为 `16:9`
3. 作者只能平移和缩放，不允许自由改比例
4. 裁剪完成后，再提交给后端保存
3. 作者直接在图片上拖拽裁剪框内部移动区域，拖拽四边或四角调整裁剪范围，不再通过参数滑杆调整
4. 裁剪框调整过程中必须持续锁定 `16:9`，不允许自由改比例
5. 裁剪完成后，再提交给后端保存
### 上传大小与格式限制

826
docs/prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md Normal file
View File

@@ -0,0 +1,826 @@
# AI 原生幸存者类游戏模板 PRD
更新时间：`2026-05-05`
## 0. 文档目的
这份 PRD 用于在当前平台内新增一条“幸存者类游戏模板”产品链路，冻结它从创作入口、Agent 共创、结果页、试玩、发布到运行态结算的完整边界。
本模板参考的是幸存者 / 割草 / 轻度 Roguelite 类玩法的通用结构：玩家在俯视角战场中移动、生存、自动攻击、拾取经验、选择升级，并在持续敌潮中坚持到胜利时间或击败终局首领。
本次不是复制某个具体商业游戏，也不是新增一个孤立前端小游戏。正式实现必须接入 Genarrative 现有平台创作中心、作品架、广场、资产、钱包、埋点和 `server-rs + Axum + SpacetimeDB` 后端基线。
---
## 1. 一句话定义
`survivor` 是一个 AI 原生幸存者类游戏模板：百梦主通过 Agent 设定主角幻想、敌潮母题、武器技能、成长流派和战场节奏，系统编译出一个移动端优先的俯视角割草生存作品；玩家通过移动躲避敌潮，武器自动攻击，拾取经验升级，在若干分钟内完成生存挑战、击败首领或倒下结算。
---
## 2. 当前接入级别
根据新增玩法类型接入分级，本模板目标为 **完整玩法闭环**：
1. 新增玩法 ID：`survivor`。
2. 对外模板名称：`幸存者挑战`。
3. 对外子标题：`割草成长玩法`。
4. 支持 Agent 创作、草稿生成、结果页编辑、试玩、发布和公开运行。
5. 支持作品架恢复草稿和已发布作品二次编辑。
6. 支持玩家从作品详情或广场进入运行态。
7. 支持后端权威生成局面、升级候选、波次配置、结算和成绩基础数据。
8. 前端负责高频模拟与表现，但不得自行发明正式规则、波次、掉落、升级池或结算真相。
---
## 3. 产品定位
## 3.1 命名
1. 对外模板名称：`幸存者挑战`。
2. 对外子标题：`割草成长玩法`。
3. 开发代号：`Survivor`。
4. 工程玩法域：`survivor`。
5. 后端模块命名预期：`survivor`。
## 3.2 核心乐趣
1. 玩家被敌潮包围，通过走位制造空间。
2. 武器自动攻击，玩家专注移动、拾取、选择升级。
3. 每次升级出现少量高价值选择，形成局内构筑。
4. 敌人数量、速度、血量和特殊能力逐步加压。
5. 后期屏幕内形成高密度清场反馈，玩家获得成长压倒敌潮的爽感。
## 3.3 与现有玩法的区别
1. 不等同于 RPG：不依赖世界章节、NPC 对话或剧情推进。
2. 不等同于大鱼吃小鱼：不做吞噬收编和三合一实体升级。
3. 不等同于抓大鹅：不做备选栏三消和堆叠点击。
4. 不等同于拼图：不切图、不交换、不合并拼块。
5. 不新增通用动作游戏引擎，本期只服务幸存者类模板。
---
## 4. 完整闭环目标
本模板首版必须补齐：
1. 平台创作入口展示“幸存者挑战”。
2. Agent 对话收集玩法锚点。
3. 后端编译幸存者玩法草稿。
4. 结果页编辑作品名、封面、标签、主角、敌人、武器、成长和战场配置。
5. 结果页支持生成或替换关键视觉资产。
6. 结果页支持发布前试玩。
7. 作品可保存、发布、删除和二次编辑。
8. 玩家从作品详情或广场创建 run。
9. 后端下发权威 run seed、波次、敌人、武器、升级候选和结算规则。
10. 前端按权威配置执行高频运行表现，定期提交 checkpoint。
11. 玩家升级时从后端确认的候选卡中选择一张。
12. 玩家死亡、主动退出、倒计时胜利或终局首领胜利后进入结算。
13. 结算成绩以后端确认的 run snapshot 为准。
---
## 5. 明确不做
首版明确不做：
1. 不做联机、PvP、组队或排行榜赛季。
2. 不做横屏专属设计，移动端竖屏优先。
3. 不做复杂地形寻路、真实物理碰撞和高精度弹幕编辑器。
4. 不做多地图章节战役，只做单局挑战。
5. 不做局外装备养成、抽卡、永久技能树或付费强化。
6. 不要求百梦主逐帧编辑怪物 AI、弹道曲线或数值公式。
7. 不把玩法规则说明长文默认写进 UI 面板。
8. 不把按钮弹出的资产、升级或参数编辑做成当前卡片下方展开内容，统一使用独立面板。
9. 不让前端本地结算直接写入正式成绩、钱包、任务或排行榜。
10. 不复用 `server-node`、Express、PostgreSQL 或旧 RPG runtime 作为新增实现目标。
---
## 6. 创作锚点设计
Agent 型创作版本至少收集下面 5 个高杠杆锚点：
| 锚点 | 字段建议 | 用途 |
| --- | --- | --- |
| 生存幻想 | `survivalFantasy` | 决定主角身份、战斗气质和作品一句话承诺。 |
| 敌潮母题 | `hordeTheme` | 决定敌人类型、数量感、压迫方式和视觉风格。 |
| 武器技能 | `weaponFantasy` | 决定自动攻击、范围技能、投射物和特效方向。 |
| 成长流派 | `buildArchetype` | 决定升级卡池、进化组合和玩家构筑路线。 |
| 战场节奏 | `stageRhythm` | 决定单局时长、波次曲线、首领节点和胜利条件。 |
Agent 必须围绕用户灵感收束这些锚点，不允许把创作入口做成一屏参数问卷。
## 6.1 锚点状态
每个锚点都支持：
1. `待补充`
2. `Agent 推断`
3. `已确认`
4. `已锁定`
## 6.2 收束条件
满足下面条件后，系统允许编译第一版草稿：
1. `生存幻想` 已确认或已锁定。
2. `敌潮母题` 已确认或已锁定。
3. `武器技能` 至少有 `3` 个可用武器草稿。
4. `成长流派` 至少有 `6` 张升级卡草稿。
5. `战场节奏` 已确认，或使用系统默认 `8` 分钟短局配置。
## 6.3 快捷补全
当会话至少完成 `2` 轮后，工作区提供 `补充剩余关键字` 快捷动作：
1. 前端发送消息接口，并携带 `quickFillRequested: true`。
2. 用户消息固定为“请补充剩余关键字。”。
3. 后端 Agent 根据当前锚点补齐缺失内容。
4. 前端不得自行推断武器、波次、敌人或升级卡。
## 6.4 Agent AI 生成契约
单轮模型输出必须是严格 JSON：
```json
{
"replyText": "",
"progressPercent": 0,
"anchors": {
"survivalFantasy": { "status": "pending", "summary": "" },
"hordeTheme": { "status": "pending", "summary": "" },
"weaponFantasy": { "status": "pending", "summary": "" },
"buildArchetype": { "status": "pending", "summary": "" },
"stageRhythm": { "status": "pending", "summary": "" }
},
"nextDraftPatch": {}
}
```
落地约束：
1. `replyText` 是直接展示给百梦主的中文回复，不得出现 JSON、字段名或内部协议说明。
2. `progressPercent` 只能由后端校验后采纳，范围 `0~100`。
3. `nextDraftPatch` 只允许写入幸存者草稿字段，不允许修改平台账号、钱包或作品归属。
4. 模型不可用或结果无法解析时，接口返回明确错误，不用固定模板伪装 AI 回复。
---
## 7. 草稿契约
## 7.1 `SurvivorResultDraft`
```ts
export interface SurvivorResultDraft {
profileId: string | null;
workTitle: string;
workDescription: string;
workTags: string[];
coverImageSrc: string | null;
anchors: SurvivorAnchorPack;
hero: SurvivorHeroDraft;
enemies: SurvivorEnemyDraft[];
weapons: SurvivorWeaponDraft[];
upgrades: SurvivorUpgradeDraft[];
evolutions: SurvivorEvolutionDraft[];
stage: SurvivorStageDraft;
wavePlan: SurvivorWavePlanDraft;
runtimeConfig: SurvivorRuntimeConfigDraft;
publishReady: boolean;
validationIssues: SurvivorValidationIssue[];
updatedAt: string;
}
```
## 7.2 主角草稿
```ts
export interface SurvivorHeroDraft {
heroId: string;
name: string;
fantasy: string;
moveSpeed: number;
maxHp: number;
defense: number;
pickupRadius: number;
spriteAssetId: string | null;
portraitAssetId: string | null;
}
```
默认范围：
1. `moveSpeed`：`80~180`，默认 `120`。
2. `maxHp`：`50~300`，默认 `100`。
3. `defense`：`0~50`，默认 `0`。
4. `pickupRadius`：`30~160`，默认 `60`。
## 7.3 敌人草稿
```ts
export interface SurvivorEnemyDraft {
enemyId: string;
name: string;
role: 'fodder' | 'runner' | 'tank' | 'ranged' | 'elite' | 'boss';
visualPrompt: string;
maxHp: number;
damage: number;
moveSpeed: number;
xpValue: number;
spawnWeight: number;
spriteAssetId: string | null;
}
```
首版发布至少需要：
1. `2` 个 `fodder` 或 `runner` 敌人。
2. `1` 个 `elite` 敌人。
3. `1` 个 `boss` 敌人。
## 7.4 武器草稿
```ts
export interface SurvivorWeaponDraft {
weaponId: string;
name: string;
attackKind: 'projectile' | 'orbit' | 'area' | 'beam' | 'melee_aura';
targeting: 'nearest' | 'random_enemy' | 'forward' | 'around_hero';
baseDamage: number;
cooldownMs: number;
projectileCount: number;
range: number;
effectAssetId: string | null;
upgradeTags: string[];
}
```
首版必须至少有 `3` 个武器。玩家开局默认持有第一个武器。
## 7.5 升级卡草稿
```ts
export interface SurvivorUpgradeDraft {
upgradeId: string;
name: string;
rarity: 'common' | 'rare' | 'epic';
targetKind: 'hero' | 'weapon' | 'global';
targetId: string | null;
effectKind:
| 'damage_percent'
| 'cooldown_percent'
| 'projectile_count'
| 'move_speed_percent'
| 'max_hp_flat'
| 'pickup_radius_percent'
| 'regen_flat';
value: number;
maxStack: number;
iconAssetId: string | null;
}
```
首版至少需要 `6` 张升级卡，并保证任意升级节点能从可用池中抽出 `3` 张候选。
## 7.6 进化组合
```ts
export interface SurvivorEvolutionDraft {
evolutionId: string;
name: string;
baseWeaponId: string;
requiredUpgradeIds: string[];
resultWeapon: SurvivorWeaponDraft;
}
```
进化组合首版可选，但字段必须预留。若启用进化，结果页必须展示组合条件，不在运行态长文解释。
## 7.7 战场草稿
```ts
export interface SurvivorStageDraft {
stageId: string;
name: string;
theme: string;
backgroundAssetId: string | null;
groundTextureAssetId: string | null;
safeAreaShape: 'rectangle' | 'circle';
width: number;
height: number;
obstacleDensity: number;
}
```
首版默认不生成实心障碍，`obstacleDensity` 固定为 `0`。后续要开放障碍，必须先补充寻路与碰撞方案。
## 7.8 波次草稿
```ts
export interface SurvivorWavePlanDraft {
durationSeconds: number;
waves: SurvivorWaveDraft[];
bossWave: SurvivorBossWaveDraft;
}
export interface SurvivorWaveDraft {
startSecond: number;
endSecond: number;
enemyPool: string[];
spawnRatePerSecond: number;
maxAlive: number;
statMultiplier: number;
}
```
默认短局：
1. `durationSeconds`：`480`。
2. 每 `60` 秒一个波次。
3. `240` 秒出现精英压力波。
4. `480` 秒出现终局首领或进入胜利结算。
---
## 8. 运行规则设计
## 8.1 单局结构
首版标准局为 `8` 分钟短局：
1. 玩家开局拥有 `1` 个基础武器。
2. 玩家通过虚拟摇杆或键盘移动。
3. 武器按冷却自动攻击。
4. 敌人从屏幕外安全环刷出并向玩家移动。
5. 敌人碰撞玩家造成伤害。
6. 敌人死亡掉落经验晶体。
7. 玩家拾取经验后升级。
8. 升级时暂停运行态，展示 `3` 张升级卡。
9. 玩家选择一张升级卡后继续运行。
10. 玩家生命归零失败。
11. 生存到终局时间或击败终局首领胜利。
## 8.2 移动与输入
1. 移动端使用左下角虚拟摇杆。
2. 桌面端支持 `WASD` / 方向键移动。
3. 首版不要求手动瞄准和手动开火。
4. 前端必须保证摇杆、血量、经验条、升级面板和结算面板在竖屏下不遮挡核心战场。
## 8.3 自动攻击
1. 每个武器独立维护冷却。
2. 目标选择策略由后端配置下发。
3. 前端可本地执行攻击表现与命中模拟，但必须使用后端下发的武器参数和 RNG seed。
4. 武器伤害、冷却、投射数量和范围变化来自后端确认的升级结果。
## 8.4 敌潮生成
1. 敌人只能从玩家当前视野外的刷怪环生成。
2. 刷怪位置不得直接贴脸。
3. 每个波次有 `spawnRatePerSecond` 和 `maxAlive` 上限。
4. 前端不得自行增加敌人类型、刷新率或精英节点。
5. 后端 checkpoint 校验时应能根据 seed、波次和输入摘要重放关键统计。
## 8.5 经验与升级
1. 敌人死亡生成经验晶体。
2. 玩家碰到晶体或晶体进入拾取半径时获得经验。
3. 经验达到当前等级阈值时触发升级。
4. 升级候选由后端按当前 build、权重、稀有度和 seed 生成。
5. 前端只能展示后端返回的候选卡。
6. 玩家选择后，后端更新 run build snapshot。
## 8.6 失败与胜利
失败条件：
1. `heroHp <= 0`。
2. 玩家主动退出并确认放弃。
3. 后端判定 run 校验失败。
胜利条件：
1. 生存到 `durationSeconds` 并完成终局结算。
2. 或在终局波次击败 `boss`。
---
## 9. 权威状态与高频模拟边界
幸存者类玩法需要高频碰撞和大量实体，不能把每一帧都交给 HTTP 往返。首版采用“后端权威配置 + 前端确定性运行表现 + 后端 checkpoint / 结算确认”的边界。
## 9.1 后端职责
后端负责：
1. 创建创作会话和玩法草稿。
2. 校验和保存作品 profile。
3. 编译 run seed、波次、敌人、武器、升级池和结算规则。
4. 生成升级候选。
5. 确认升级选择。
6. 接收运行 checkpoint。
7. 校验关键统计是否在合理范围内。
8. 确认死亡、胜利、退出和最终成绩。
9. 写入作品游玩次数、成绩、埋点和任务事件。
## 9.2 前端职责
前端负责：
1. 展示 Agent 工作台和结果页。
2. 渲染战场、主角、敌人、投射物、特效、经验晶体和 HUD。
3. 基于后端 run config 执行确定性高频模拟。
4. 采集玩家移动输入。
5. 展示攻击、受击、拾取、升级、胜利和失败反馈。
6. 定期提交 checkpoint。
7. 在后端拒绝 checkpoint 或结算时，展示同步失败并结束本局。
## 9.3 Checkpoint 规则
前端每 `5` 秒或关键节点提交 checkpoint：
```ts
export interface SurvivorRunCheckpointRequest {
runId: string;
snapshotVersion: number;
elapsedMs: number;
inputDigest: string;
rngStep: number;
heroHp: number;
heroLevel: number;
killCount: number;
eliteKillCount: number;
bossKillCount: number;
xpCollected: number;
selectedUpgradeIds: string[];
checksum: string;
}
```
关键节点包括：
1. 升级触发前。
2. 选择升级后。
3. 精英死亡。
4. Boss 出现。
5. Boss 死亡。
6. 玩家死亡。
7. 胜利结算。
---
## 10. 结果页设计
## 10.1 结果页职责
幸存者结果页是最小可编辑工作台，不是只读总结页。
结果页至少包含：
1. 作品基础信息。
2. 主角配置。
3. 敌人图鉴。
4. 武器与升级卡池。
5. 战场与波次。
6. 资产状态。
7. 试玩入口。
8. 发布校验。
## 10.2 移动端优先布局
1. 首屏显示作品标题、封面、发布状态和试玩按钮。
2. 主角、敌人、武器、战场使用分组入口。
3. 点击分组入口打开独立编辑面板。
4. 不在卡片下方展开长规则说明。
5. 发布校验只展示短状态和可处理项，不展示底层协议。
## 10.3 资产要求
正式发布前至少需要：
1. 作品封面。
2. 主角头像或主角小人资产。
3. `3` 类普通敌人资产。
4. `1` 类精英或首领资产。
5. `3` 个武器或技能图标。
6. `1` 张战场背景或地面纹理。
程序化色块或几何占位只允许用于开发调试和未发布草稿，不允许作为正式发布作品的默认资产。
## 10.4 结果页核心操作
结果页支持：
1. `生成主角资产`
2. `生成敌人资产`
3. `生成武器图标`
4. `生成战场背景`
5. `重新编译波次`
6. `试玩`
7. `保存草稿`
8. `发布`
9. `返回创作对话`
---
## 11. API 设计
## 11.1 创作接口
1. `POST /api/creation/survivor/sessions`
2. `GET /api/creation/survivor/sessions/{sessionId}`
3. `POST /api/creation/survivor/sessions/{sessionId}/messages`
4. `POST /api/creation/survivor/sessions/{sessionId}/messages/stream`
5. `POST /api/creation/survivor/sessions/{sessionId}/actions`
6. `POST /api/creation/survivor/sessions/{sessionId}/compile`
7. `GET /api/creation/survivor/works`
8. `GET /api/creation/survivor/works/{profileId}`
9. `PUT /api/creation/survivor/works/{profileId}`
10. `POST /api/creation/survivor/works/{profileId}/publish`
11. `DELETE /api/creation/survivor/works/{profileId}`
## 11.2 运行接口
1. `GET /api/runtime/survivor/gallery`
2. `GET /api/runtime/survivor/gallery/{profileId}`
3. `POST /api/runtime/survivor/works/{profileId}/runs`
4. `GET /api/runtime/survivor/runs/{runId}`
5. `POST /api/runtime/survivor/runs/{runId}/checkpoint`
6. `POST /api/runtime/survivor/runs/{runId}/upgrade-options`
7. `POST /api/runtime/survivor/runs/{runId}/choose-upgrade`
8. `POST /api/runtime/survivor/runs/{runId}/settle`
9. `POST /api/runtime/survivor/runs/{runId}/stop`
10. `POST /api/runtime/survivor/runs/{runId}/restart`
## 11.3 SSE 事件
创作对话流式事件复用平台 Agent envelope。运行态首版不要求全程 SSE；如后续加入服务端实时推送，只允许推送权威 milestone，不传每帧实体状态。
---
## 12. 后端分层边界
完整实现时必须遵循当前后端路线：
1. `server-rs/crates/module-survivor`
- 纯领域规则、草稿校验、波次编译、升级池、评分和 checkpoint 校验。
- 不依赖 Axum、SpacetimeDB、OSS 或 LLM。
2. `server-rs/crates/shared-contracts`
- 暴露 Survivor Agent、作品、运行态 DTO。
3. `server-rs/crates/spacetime-module`
- 存储 session、message、work profile、runtime run 和 runtime event。
- 表结构变化必须同步 `migration.rs` 与表目录。
4. `server-rs/crates/spacetime-client`
- 提供 api-server 调用 SpacetimeDB 的 typed facade。
5. `server-rs/crates/api-server`
- 暴露 `/api/creation/survivor/*` 与 `/api/runtime/survivor/*`。
- 处理鉴权、错误 envelope、LLM turn、资产生成和 HTTP facade。
6. `platform-agent` / `platform-llm`
- 承接 Agent 对话与草稿生成。
7. `platform-oss`
- 承接封面、角色、敌人、武器图标和战场背景资产。
---
## 13. SpacetimeDB 表建议
首版建议新增：
1. `survivor_agent_session`
- 创作会话主表，保存 owner、stage、anchors、draft、progress、published_profile_id。
2. `survivor_agent_message`
- 创作消息流水。
3. `survivor_work_profile`
- 作品 profile，保存发布态草稿、封面、标签、作者和公开状态。
4. `survivor_runtime_run`
- 运行态 run，保存 run config、seed、当前 snapshot、checkpoint 摘要和结算状态。
5. `survivor_runtime_event`
- 运行审计事件，记录 start、checkpoint、upgrade、death、victory、settle 等关键事件。
首版不新增正式排行榜表。若后续加入排行榜，再新增 `survivor_leaderboard_entry` 并补充反作弊和赛季边界。
---
## 14. 作品结构建议
```ts
export interface SurvivorWorkProfile {
profileId: string;
ownerUserId: string;
sourceSessionId: string | null;
workTitle: string;
workDescription: string;
workTags: string[];
coverImageSrc: string | null;
publicationStatus: 'draft' | 'published' | 'archived';
draft: SurvivorResultDraft;
playCount: number;
updatedAt: string;
publishedAt: string | null;
}
```
## 14.1 发布校验
发布必须满足：
1. `workTitle` 非空。
2. 至少 `1` 个标签。
3. 有封面图。
4. 主角配置完整。
5. 至少 `4` 个敌人，其中包含普通、精英或首领。
6. 至少 `3` 个武器。
7. 至少 `6` 张升级卡。
8. 波次覆盖完整 `durationSeconds`。
9. 资产覆盖满足正式发布要求。
10. `runtimeConfig` 在后端数值上限内。
---
## 15. 运行态快照建议
```ts
export interface SurvivorRunSnapshot {
runId: string;
profileId: string;
ownerUserId: string | null;
status: 'running' | 'level_up_pending' | 'victory' | 'defeat' | 'stopped' | 'settlement_failed';
snapshotVersion: number;
seed: string;
elapsedMs: number;
durationLimitMs: number;
hero: SurvivorRunHeroSnapshot;
build: SurvivorRunBuildSnapshot;
wave: SurvivorRunWaveSnapshot;
stats: SurvivorRunStatsSnapshot;
pendingUpgradeOptions: SurvivorUpgradeOption[];
settlement: SurvivorRunSettlement | null;
updatedAt: string;
}
```
前端渲染可维护更细的局内实体列表，但正式持久化只保存 run snapshot、checkpoint 摘要和结算结果。
---
## 16. 计分与结算
首版结算至少展示：
1. 胜利 / 失败状态。
2. 生存时间。
3. 击杀数。
4. 等级。
5. 精英击杀数。
6. 首领击杀数。
7. 选择过的核心升级。
8. 再来一局。
9. 返回作品详情。
基础分数公式：
```text
score = survivedSeconds * 10
+ killCount * 5
+ eliteKillCount * 120
+ bossKillCount * 500
+ heroLevel * 80
```
结算入库以后端确认结果为准。前端展示的即时结算在后端确认前必须标记为待确认状态。
---
## 17. 平台接入
## 17.1 创作入口
需要接入：
1. `src/config/newWorkEntryConfig.ts`
2. `src/components/platform-entry/platformEntryCreationTypes.ts`
3. `src/components/platform-entry/platformEntryTypes.ts`
4. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
新增阶段建议：
1. `survivor-agent-workspace`
2. `survivor-generating`
3. `survivor-result`
4. `survivor-runtime`
5. `survivor-gallery-detail`
## 17.2 前端组件建议
1. `src/components/survivor-creation/SurvivorAgentWorkspace.tsx`
2. `src/components/survivor-result/SurvivorResultView.tsx`
3. `src/components/survivor-runtime/SurvivorRuntimeShell.tsx`
4. `src/services/survivorCreationClient.ts`
5. `src/services/survivorRuntimeClient.ts`
6. `src/services/survivorWorksClient.ts`
## 17.3 作品架与广场
发布后必须接入：
1. 创作页作品架。
2. 平台作品详情。
3. 首页或发现页公开作品流。
4. 公开作品试玩入口。
5. 删除、二次编辑和重新发布。
---
## 18. UI 设计约束
1. 移动端竖屏优先，桌面端居中或宽屏增强。
2. HUD 只保留血量、经验、时间、等级、击杀数和暂停入口。
3. 升级卡使用独立面板，最多显示 `3` 张候选。
4. 暂停、结算、资产生成、参数编辑都使用独立面板。
5. 不默认展示规则说明长文。
6. 运行态主画面不能被功能介绍、键位说明或装饰卡片遮挡。
7. 触控区、摇杆、升级卡和按钮必须满足移动端可点击尺寸。
8. 图标按钮优先使用现有图标库；无图标时再使用简短文本。
---
## 19. 里程碑拆分
## 19.1 Phase 1：入口与 PRD 骨架
1. 冻结 `survivor` 玩法 ID。
2. 新增入口配置。
3. 新增前端阶段枚举。
4. 新增 shared contracts 草案。
5. 入口可以进入占位工作台。
## 19.2 Phase 2：创作会话与结果页
1. 新增 Agent session。
2. 新增消息与流式回复。
3. 编译第一版 `SurvivorResultDraft`。
4. 结果页可编辑主角、敌人、武器、升级和波次。
5. 支持保存草稿。
## 19.3 Phase 3：后端运行态
1. `module-survivor` 实现波次、升级池、结算和 checkpoint 校验。
2. SpacetimeDB 表、migration 和 facade 收口。
3. api-server 暴露 runtime API。
4. 支持创建 run、选择升级、提交 checkpoint 和结算。
## 19.4 Phase 4：前端运行态
1. 实现竖屏战场。
2. 实现摇杆移动。
3. 实现自动攻击、敌潮、经验和升级面板。
4. 实现胜利、失败、暂停和结算。
5. 接入后端 checkpoint 与升级确认。
## 19.5 Phase 5：发布与平台闭环
1. 发布作品。
2. 接入作品架。
3. 接入公开详情和广场。
4. 支持二次编辑。
5. 接入埋点、任务和基础成绩记录。
---
## 20. 验收标准
1. `src/config/newWorkEntryConfig.ts` 中存在 `survivor` 类型。
2. 新建作品入口和创作类型弹层能展示“幸存者挑战”。
3. 能进入 `survivor-agent-workspace`。
4. Agent 能生成锚点和草稿。
5. 能进入 `survivor-result` 并编辑基础字段。
6. 发布校验能阻止缺少主角、敌人、武器、升级卡、波次或资产的作品发布。
7. 能从结果页进入试玩运行态。
8. 运行态能移动、自动攻击、刷怪、拾取经验、升级和结算。
9. 升级候选必须来自后端返回，不由前端临时生成。
10. 前端提交 checkpoint 后，后端能接受或拒绝并返回明确结果。
11. 作品发布后能在作品架和公开入口恢复。
12. 移动端竖屏下主战场、摇杆、HUD、升级卡和结算不互相遮挡。
13. 后端实现后执行对应 DDD 验收命令，并用 `npm run api-server` 启动后端检查 `/healthz`。
14. 修改包含中文的文档后执行 `npm run check:encoding`。
---
## 21. 后续可选增强
以下能力不进入首版，但需要保留扩展空间：
1. 多地图主题。
2. 局外角色解锁。
3. 进化武器动画。
4. 精英词缀。
5. Boss 特殊弹幕。
6. 道具掉落。
7. 排行榜。
8. 赛季挑战。
9. 更多输入模式。
10. 服务端更严格的确定性重放校验。

1277
docs/prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md Normal file
View File

File diff suppressed because it is too large Load Diff

1795
docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md Normal file
View File

File diff suppressed because it is too large Load Diff

1181
docs/prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md Normal file
View File

File diff suppressed because it is too large Load Diff

13
docs/prd/FIRST_LAUNCH_PUZZLE_ONBOARDING_PRD_2026-05-05.md
View File

@@ -37,7 +37,7 @@
## 5. 范围边界
1. 不增加跳过入口。
1. 首屏右上角提供 `跳过` 入口，点击后写入首次访问标记并回到产品首页。
2. 不定义额外功能说明文案。
3. 不扩展拼图为多关。
4. 不调整注册/登录后的去向，当前进入产品首页。
@@ -47,10 +47,12 @@
1. 未登录首次访问产品时，进入新手引导首屏。
2. 首屏展示确认文案、输入框和生成按钮。
3. 用户输入内容并点击生成后，系统生成 1 关拼图。
4. 生成完成后，用户可以进入该拼图并完成第 1 关。
5. 第 1 关完成后，页面展示注册/登录引导文案和登录模块。
6. 用户完成注册或登录后，进入产品首页。
3. 首屏右上角展示跳过按钮；点击后本次和后续访问不再自动展示新手引导。
4. 用户输入内容并点击生成后，系统生成 1 关拼图。
5. 若临时生成接口返回 `404 / 资源不存在`，前端使用本地临时拼图兜底继续进入试玩，不把错误直接展示给用户。
6. 生成完成后，用户可以进入该拼图并完成第 1 关。
7. 第 1 关完成后，页面展示注册/登录引导文案和登录模块。
8. 用户完成注册或登录后，进入产品首页。
## 7. 落地接口与状态
@@ -59,3 +61,4 @@
3. 登录后保存入口为 `POST /api/runtime/puzzle/onboarding/save`，要求登录；服务端为当前用户创建拼图 agent session，并把临时 1 关拼图保存为当前用户作品草稿。
4. 新手引导游玩阶段复用现有本地拼图运行时，不新增 SpacetimeDB 表、reducer 或运行时真相。
5. 保存完成后清空新手引导临时态，刷新拼图作品架，并回到产品首页。
6. 跳过新手引导只更新本地首次访问标记和界面状态，不创建临时作品、不调用保存接口。

20
docs/prd/README.md Normal file
View File

@@ -0,0 +1,20 @@
# PRD 总览
本目录用于存放产品需求、玩法闭环、阶段计划和可直接指导编码的需求拆分文档。
## 重点入口
- [AI 原生幕间文字游戏模板 PRD：参考 MOKU 的剧本模拟器闭环](./AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md)：参考 MOKU / 幕间类 AI 文游的剧本游乐场、自由行动、AI GM、记忆和模拟器强反馈经验，但只落为百梦 `text-game` 模板，复用平台接口，不迁入外部社区、支付、私有存档或回放。
- [AI 原生视觉小说模板 PRD：TXT 玩法平台化接入](./AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)：参考 `Interactive-fiction-backend` / `Interactive-fiction-frontend` 的 TXT 玩法经验，但只保留视觉小说模板创作与运行闭环，完全使用 Genarrative 平台接口，并明确删除回放和外部平台功能。
- [AI 原生幸存者类游戏模板 PRD](./AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md)：定义 `survivor` 幸存者挑战模板，从 Agent 创作、结果页、资产、试玩、发布到后端权威配置与前端高频运行表现的完整闭环。
- [创意互动内容生成 Agent Phase 1 PRD：LangChain-Rust PoC + 拼图闭环](./CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md)：首版只支持拼图模板，Agent 使用 APIMart Responses `gpt-5` 支持文本和图像多模态输入，明确模板选择、积分范围、草稿字段填充、单关卡/多关卡图片生成、立即试玩、自然语言修改和可并行任务拆分。
- [AI 原生 2048 游戏玩法模板 PRD](./AI_NATIVE_2048_GAMEPLAY_TEMPLATE_PRD_2026-05-05.md)：新增 `twenty-forty-eight` 玩法模板，定义主题化合成链创作、结果页、发布、公开运行、后端棋盘裁决、排行榜和并行落地任务。
- [AI 原生拼图玩法创作工具与玩法系统 PRD](./AI_NATIVE_PUZZLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-22.md)：拼图玩法创作、结果页、发布、广场和运行时主链路。
- [AI 原生方洞挑战玩法创作工具与玩法系统 PRD](./AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)：方洞挑战创作、发布与试玩闭环。
- [后台管理独立前端工程 PRD](./ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)：后台管理端产品边界。
## 使用规则
- 新玩法、新 Agent 阶段、新创作闭环或较大功能落地前，优先补 PRD。
- PRD 必须写到可以编码的程度，包含字段、接口、状态、验收和并行任务拆分。
- 若 PRD 与最新代码或技术方案冲突，以代码和最新技术方案为准，并同步修正 PRD。

2
docs/prd/TXT_MODE_CORE_GAMEPLAY_PRD_2026-04-20.md
View File

@@ -2,6 +2,8 @@
更新时间：`2026-04-20`
> 2026-05-05 更新口径：本文保留为历史参考。视觉小说模板后续落地以 [`AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`](./AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md) 为准；冲突时不再按“外部 TXT 模式原样迁入”执行，必须只保留模板玩法能力、完全使用 Genarrative 平台接口，并删除回放功能。
## 0. 文档目的
这份 PRD 只定义 `Interactive-fiction-frontend` + `Interactive-fiction-backend` 中 TXT 模式在 `Genarrative` 落地时的**核心玩法闭环**。

21
docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md
View File

@@ -39,6 +39,22 @@ APIMART_BASE_URL=
APIMART_API_KEY=
APIMART_IMAGE_REQUEST_TIMEOUT_MS=180000
# VectorEngine / Suno / Vidu 音频生成网关
VECTOR_ENGINE_BASE_URL=
VECTOR_ENGINE_API_KEY=
VECTOR_ENGINE_AUDIO_REQUEST_TIMEOUT_MS=180000
# 火山引擎豆包语音 ASR / TTS
VOLCENGINE_SPEECH_API_KEY=
VOLCENGINE_SPEECH_APP_ID=
VOLCENGINE_SPEECH_ACCESS_KEY=
VOLCENGINE_SPEECH_ASR_RESOURCE_ID=volc.seedasr.sauc.concurrent
VOLCENGINE_SPEECH_TTS_RESOURCE_ID=seed-tts-2.0
VOLCENGINE_SPEECH_REQUEST_TIMEOUT_MS=180000
VOLCENGINE_SPEECH_ASR_WS_URL=wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async
VOLCENGINE_SPEECH_TTS_BIDIRECTION_WS_URL=wss://openspeech.bytedance.com/api/v3/tts/bidirection
VOLCENGINE_SPEECH_TTS_SSE_URL=https://openspeech.bytedance.com/api/v3/tts/unidirectional/sse
# DashScope 图片模型名
DASHSCOPE_SCENE_IMAGE_MODEL=
DASHSCOPE_REFERENCE_IMAGE_MODEL=
@@ -65,6 +81,9 @@ DASHSCOPE_COVER_IMAGE_MODEL / DASHSCOPE_IMAGE_MODEL
ARK_CHARACTER_VIDEO_BASE_URL / ARK_BASE_URL / GENARRATIVE_LLM_BASE_URL / LLM_BASE_URL
ARK_CHARACTER_VIDEO_API_KEY / ARK_API_KEY / GENARRATIVE_LLM_API_KEY / LLM_API_KEY
ARK_CHARACTER_VIDEO_MODEL / DASHSCOPE_CHARACTER_VIDEO_MODEL
VOLCENGINE_SPEECH_API_KEY / VOLCENGINE_API_KEY
VOLCENGINE_SPEECH_APP_ID / VOLCENGINE_ACCESS_KEY_ID
VOLCENGINE_SPEECH_ACCESS_KEY / VOLCENGINE_SECRET_ACCESS_KEY
```
## 运行时行为
@@ -74,6 +93,8 @@ ARK_CHARACTER_VIDEO_MODEL / DASHSCOPE_CHARACTER_VIDEO_MODEL
3. 文本 LLM provider 为 `ark` 且未配置 `GENARRATIVE_LLM_BASE_URL` 时，仍回退到 Ark 公开基础 URL。
4. 角色视频 provider 复用 Ark 且未配置 `ARK_CHARACTER_VIDEO_BASE_URL` 时，仍回退到 Ark 公开基础 URL。
5. 具体模型名缺失时不在配置层伪造默认模型，调用到对应能力时由下游配置校验返回缺配置错误。
6. VectorEngine 音频生成只读取 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY`，不复用 `APIMART_*`、`GENARRATIVE_LLM_*` 或前端变量。
7. 火山引擎语音能力由 `platform-speech` 收口协议帧与上游鉴权，`api-server` 只暴露平台鉴权后的代理路由，不向前端返回任何密钥字段。
## 示例文件

22
docs/technical/AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md
View File

@@ -115,3 +115,25 @@
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；如果单独使用它，脚本会先探测 `.env.local` / 当前环境里声明的目标，再回退到本机常见端口，最终只会接入一个真实可用的 `api-server`。
6. 如果 `3000` 仍然返回 `500`，先确认浏览器是不是还开着旧的前端进程。当前脚本如果因为端口占用漂移到 `3001` / `3002`，应直接关掉旧进程后重启，而不是继续用旧的 3000 页面判断登录入口状态。

950
docs/technical/CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md Normal file
View File

@@ -0,0 +1,950 @@
# 创意互动内容生成 Agent 技术方案 2026-05-05
## 1. 目标
构建一个基于 LangChain-Rust 的创意互动内容生成 Agent。用户输入文字、图片、文档或混合素材后，Agent 不通过规则分类硬选玩法，而是以模型为核心完成理解、判断、规划和执行：先理解用户真正想表达的创作意图，再选择当前可用的互动内容模板，最后调用拼图模块工具把内容填入草稿契约中。
当前版本只支持拼图模板。RPG 世界、大鱼吃小鱼、抓大鹅 Match3D、方洞挑战等模板必须在 Agent 可见能力中标记为 `unsupported`，不能创建这些玩法的目标 session。即便只有拼图可用，Agent 仍必须先展示多个拼图模板候选，用户选择某个模板后，再确认该模板下的关卡模式、关卡数和预计积分范围，确认后才进入草稿生成。
本方案不再把 Agent 设计成“规则路由 workflow”。规则只作为安全护栏、契约校验和成本控制。真正的模板选择、素材理解、草稿构思、行动顺序和补问判断由模型通过工具调用和反思循环完成。
## 2. LangChain-Rust 选型依据
当前可参考 `langchainrust` crate 作为 Rust 侧 Agent 编排底座。官方 crate 页面显示 `0.2.18` 支持 Agents、Tools、Memory、Chains、RAG、BM25、Hybrid Retrieval、LangGraph、Typed/JSON output parser、Function Calling、Callbacks 等能力；其中 Agent 层包括 ReActAgent、FunctionCallingAgent、AgentExecutor 和 LangGraph，Memory 层包括 Buffer、Window、Summary、SummaryBuffer、Persistent。
落地时建议先以 `langchainrust = "0.2.18"` 做隔离性 PoC，不直接替换现有 `platform-llm`。若 crate API 与 docs.rs 最新构建存在差异，以源码和本地编译结果为准，先封装一层 `platform-agent` adapter，再接入 `api-server`。
参考：
- `langchainrust` crates.io/docs.rs 页面：https://docs.rs/crate/langchainrust/latest
- 仓库主页：https://github.com/atliliw/langchainrust
## 2.1 Agent 模型与多模态输入
创意互动内容 Agent 的感知、思考、反思和自然语言草稿修订统一使用 APIMart OpenAI 兼容 Responses API 的 `gpt-5`。这里的 `gpt-5` 负责理解用户文字和图片、选择拼图模板、规划草稿字段和生成结构化工具调用参数；拼图图片生成仍由拼图模块图片工具使用 `gpt-image-2`，不要把“理解/规划模型”和“生图模型”混在同一个配置里。
请求协议以 APIMart 文档 `OpenAI 多模态响应接口` 为准：
```text
POST https://api.apimart.ai/v1/responses
model: gpt-5
official_fallback: true
input[].content[].type: input_text | input_image
```
Phase 1 的 `platform-agent` / `platform-llm` 必须支持下面的项目内请求结构：
```ts
export interface CreativeAgentMultimodalInputPart {
type: 'input_text' | 'input_image';
text?: string;
imageUrl?: string;
}
export interface CreativeAgentGpt5Request {
model: 'gpt-5';
official_fallback: true;
input: Array<{
role: 'system' | 'user' | 'assistant';
content: CreativeAgentMultimodalInputPart[];
}>;
stream: boolean;
tools?: CreativeAgentToolSchema[];
}
```
落地约束：
1. Agent 入口支持文本 + 图片多模态输入，首版至少支持 1 张图片，协议层预留多图。
2. 图片必须先进入资产系统，Agent 请求使用可访问的 `readUrl` 或受控 Data URI；SpacetimeDB 不保存大图 base64。
3. `platform-llm` 当前已有 Responses 协议骨架，但 Phase 1 需要把 content part 从纯文本扩展成 `input_text` / `input_image` 两类；APIMart GPT-5 client 必须显式开启 `official_fallback = true`，该供应商字段不默认扩散到 Ark 等非 APIMart provider。
4. `CREATION_TEMPLATE_LLM_MODEL` 等旧文本创作模型不能作为创意互动内容 Agent 的默认模型；本 Agent 必须显式使用 `gpt-5`。
5. 如果 LangChain-Rust adapter 暂时无法直接表达多模态 Responses 请求，应在 `platform-agent` 内桥接到 `platform-llm` 的多模态 Responses client，不能退回纯文本摘要替代图片理解。
6. 模型工具调用可用 APIMart Responses 的 `tools` 能力承载；工具真正执行仍由 `platform-agent` 注册表和后端 typed Tool 控制。
## 3. 总体架构
Agent 由六大核心模块组成，形成“感知 -> 思考 -> 记忆 -> 行动 -> 反思 -> 协作”的闭环。
```text
用户图文输入
-> 感知 Perception
-> 思考 Reasoning
-> 记忆 Memory
-> 行动 Action
-> 反思 Reflection
-> 协作 Collaboration
-> 目标玩法草稿 / 追问 / 人工确认
```
Rust 分层建议：
```text
server-rs/crates/platform-agent
langchain_adapter.rs LangChain-Rust 封装，屏蔽第三方 API 变化
agent_graph.rs 六模块 LangGraph / AgentExecutor 编排
tools.rs 工具注册与权限边界
output_parsers.rs Typed / JSON 输出解析
callbacks.rs Trace、SSE、成本与错误事件
server-rs/crates/module-creative-agent
domain.rs Agent 会话、目标、模板语义、计划、反思记录
commands.rs 创建会话、写入输入、确认计划、保存结果
application.rs 纯领域校验、阶段迁移、契约门槛
errors.rs 字段错误与领域错误
server-rs/crates/api-server/src/creative_agent.rs
HTTP / SSE facade，调用 platform-agent 和 spacetime-client
```
DDD 边界保持不变：
- `platform-agent` 负责 Agent 编排和工具调用抽象，不保存业务真相。
- `module-creative-agent` 只放纯领域类型、阶段、校验和决策记录结构。
- `api-server` 负责鉴权、SSE、LLM/视觉/工具编排。
- `spacetime-module` 保存会话、输入、记忆索引、目标玩法绑定和审计事件。
- 当前目标玩法只允许拼图。拼图模板协议、积分范围、单关卡/多关卡图片生成计划、草稿校验和工具实现全部封装在 `module-puzzle` / 拼图相关 facade 中；通用 Agent 不复制拼图字段推导逻辑。
## 4. 六大核心模块
### 4.1 感知模块 Perception
职责：把用户输入的字、图、文档和上下文变成模型可推理的多模态语义状态。
它不是关键词分类器。它要做的是“看懂素材”和“看懂用户想要什么”。
输入：
```ts
export interface CreativePerceptionInput {
text: string;
documents: CreativeTextAttachment[];
images: CreativeImageAttachment[];
currentUserProfile?: CreativeUserPreferenceSnapshot | null;
entryContext: 'creation_home' | 'puzzle_workspace' | 'gallery_remix' | 'draft_restore';
}
```
输出：
```ts
export interface CreativePerceptionState {
userIntent: string;
emotionalTone: string;
targetAudience: string | null;
sourceMaterials: CreativeMaterialSummary[];
visualUnderstanding: CreativeImageUnderstanding[];
constraints: CreativeConstraint[];
uncertainties: CreativeUncertainty[];
}
```
实现方式：
1. 文档输入复用 `creationAgentDocumentInput`，再交给 LangChain-Rust 的 text splitter / document chain 做摘要。
2. 图片输入必须先上传为资产，Agent 只拿 `readUrl`、缩略图、尺寸和视觉摘要，不把大 data URL 存入 SpacetimeDB。
3. 图像理解首版直接通过 APIMart Responses API 的 `gpt-5` 多模态输入完成，返回主体、场景、风格、OCR、构图线索和安全风险；后续如独立 `platform-vision`，也必须保持相同的文本/图像内容块契约。
4. 模板和玩法说明通过 RAG 检索注入，而不是写死规则。检索源包括玩法模板注册表、拼图草稿契约、已有优秀作品摘要和玩法适配说明。
LangChain-Rust 对应能力：
- Document loader / splitter / summarization chain
- RAG、BM25、Hybrid retrieval
- Typed / JSON output parser
- Callback 将感知进度推给前端 SSE
### 4.2 思考模块 Reasoning
职责：让模型在可用工具、用户意图和玩法知识之间主动做计划。
思考模块不是 `if playType == puzzle` 的路由函数，而是一个 FunctionCallingAgent 或 LangGraph 中的 planner 节点。模型可以自主选择：
- 先调用拼图模板知识检索
- 先返回拼图模板目录
- 请求用户选择模板
- 用户选中模板后，再确认该模板的关卡模式、关卡数和积分范围
- 确认后生成单关卡或多关卡草稿计划
- 先调用图片理解
- 先问用户一个关键问题
- 委托拼图专家 Agent
当前版本的思考模块不能选择非拼图玩法作为行动目标。如果模型认为输入更适合 RPG、Match3D、大鱼或方洞挑战，应输出“当前仅支持拼图模板”的说明，并尝试给出可转化为拼图的创意方案；若无法转化，应进入 `waiting_user`，不能创建非拼图 session。
核心状态：
```ts
export interface CreativeReasoningState {
goal: string;
candidatePlayTypes: CreativePlayCandidate[];
selectedPlayType: CreativePlayType | null;
selectedTemplateId: string | null;
selectedPuzzleTemplate: PuzzleCreativeTemplateSelection | null;
selectedImageGenerationPlan: PuzzleImageGenerationPlan | null;
plan: CreativeAgentPlanStep[];
confidence: number;
needUserClarification: boolean;
rationale: string;
}
```
建议使用 LangChain-Rust：
- `FunctionCallingAgent` 作为主决策 Agent，所有玩法能力以工具形式暴露。
- `AgentExecutor` 控制最大迭代次数、超时、工具调用错误回传。
- `LangGraph` 表达长链路：`perceive -> plan -> act -> reflect -> finalize`，允许循环和人工确认。
- `JsonOutputParser` / `TypedOutputParser` 保证模型最终输出能落到 Rust/TS shared contract。
系统提示词要明确：
1. 你是创意互动内容生成 Agent，不是分类器。
2. 你可以相信自己的多模态理解能力。
3. 你应选择能最大化互动体验的玩法，而不是机械匹配关键词。
4. 当前产品只开放拼图模板，非拼图模板只能解释为暂不支持，不能调用非拼图工具。
5. 即便只有拼图玩法可用，也必须先显式展示多个拼图子模板；用户选中模板后，才展示选择理由、关卡配置和预计积分范围。
6. 当输入足够明确时不要过度追问。
7. 当合规、素材权属、人物肖像或儿童内容存在风险时进入确认或降级。
### 4.3 记忆模块 Memory
职责：让 Agent 能利用当前会话、用户偏好、历史作品和反思经验，而不是每次从零判断。
记忆分四层：
```text
短期记忆：当前会话消息、工具调用、草稿状态
工作记忆：本次任务的目标、计划、候选、未解决问题
长期记忆：用户偏好、常用玩法、作品风格、发布反馈
反思记忆：过去失败原因、模板误选案例、修正策略
```
推荐结构：
```ts
export interface CreativeAgentMemorySnapshot {
shortTermSummary: string;
workingPlan: CreativeAgentPlanStep[];
retrievedUserPreferences: CreativeUserPreference[];
retrievedTemplateMemories: CreativeTemplateMemory[];
retrievedReflections: CreativeReflectionMemory[];
}
```
落地方式：
1. LangChain-Rust Memory 用于单次 AgentExecutor 内的短期上下文，可用 Buffer / Window / SummaryBuffer。
2. SpacetimeDB 保存长期真相：`creative_agent_session`、`creative_agent_message`、`creative_agent_reflection`、`creative_agent_target_binding`。
3. 向量/混合检索保存可召回记忆：用户偏好、模板选择结果、发布后反馈、失败反思。首版可用 SQLite 或 Redis feature，生产再评估 Qdrant/Redis。
4. 每次生成结束后写一条反思记忆：选择了什么模板、为什么、哪些字段由模型推断、用户是否接受、是否返回编辑。
记忆使用原则：
- 记忆给模型参考，不替代用户本轮输入。
- 用户本轮明确要求优先级最高。
- 任何长期记忆都要带来源、时间和置信度。
- 涉及个人隐私、图片内容和未发布作品时只在用户私有 namespace 检索。
### 4.4 行动模块 Action
职责：把 Agent 的计划变成可审计、可回滚、可测试的工具调用。
所有对系统产生影响的操作都必须以 LangChain-Rust Tool 的形式注册。模型通过 function calling 选择工具，工具内部再调用现有服务或 SpacetimeDB facade。
首批工具：
```text
perceive_image(imageAssetId)
retrieve_puzzle_template_catalog(query)
retrieve_user_creation_memory(userId, query)
create_puzzle_agent_session(payload)
compile_puzzle_draft(sessionId, payload)
plan_puzzle_level_images(payload)
generate_puzzle_level_images(sessionId, payload)
select_puzzle_template(payload)
confirm_puzzle_template(payload)
apply_puzzle_draft_natural_language_edit(sessionId, payload)
start_puzzle_draft_test_run(sessionId, payload)
ask_user_clarification(question, options?)
request_user_confirmation(summary, candidates)
validate_target_draft(playType, draft)
save_creative_reflection(payload)
```
工具设计要求：
1. 工具描述要清楚告诉模型何时使用，而不是由外层规则决定。
2. 工具输入必须是 JSON Schema / Rust typed struct，禁止自由字符串拼接。
3. 工具只做一件事。比如“创建拼图 session”和“编译拼图草稿”分开。
4. 工具返回结构化结果，包含 `ok`、`summary`、`nextSuggestedTools`、`warnings`。
5. 所有写操作必须鉴权，不能信任模型传入的 `ownerUserId`。
6. 工具调用审计写入 SpacetimeDB，便于排障和反思。
7. 当前工具注册表只能暴露拼图工具。非拼图工具即使已有实现，也不能注册给当前 Agent。
拼图草稿不是路由器手填，而是 Action 模块通过工具让 Agent 产出 typed payload。这里的“草稿字段”只指用户表单和 Agent 自然语言都共同编辑的那一组字段：
```ts
export interface CreativePuzzleDraftToolInput {
templateId: string;
templateCostRange: PuzzleTemplateCostRange;
workTitle: string;
workDescription: string;
workTags: string[];
levels: CreativePuzzleLevelDraftInput[];
}
export interface CreativePuzzleLevelDraftInput {
levelName: string;
pictureDescription: string;
pictureReference?: string | null;
}
```
工具内部负责映射到现有 `PuzzleAgentActionRequest` 和 `PuzzleResultDraft`，并调用拼图领域校验。`workTitle`、`workDescription`、`workTags`、`levels[].levelName`、`levels[].pictureDescription`、`levels[].pictureReference` 是 Agent 直接写入的草稿真相；`summary`、`anchorPack`、`forbiddenDirectives`、`imagePrompt`、候选图等都属于拼图模块内部派生或生成结果，不作为 Agent 的直接填表目标。
拼图模块必须额外暴露模板和多关卡图片协议：
```ts
export interface PuzzleCreativeTemplateProtocol {
templateId: string;
title: string;
description: string;
supportedLevelMode: 'single' | 'multi' | 'single_or_multi';
defaultLevelCount: number;
minLevelCount: number;
maxLevelCount: number;
costRange: PuzzleTemplateCostRange;
requiredDraftFields: string[];
imageGenerationPolicy: PuzzleTemplateImageGenerationPolicy;
}
export interface PuzzleTemplateCostRange {
minPoints: number;
maxPoints: number;
pricingUnit: 'point';
reason: string;
}
export interface PuzzleTemplateImageGenerationPolicy {
allowUploadedImageDirectly: boolean;
allowGeneratedImages: boolean;
allowPerLevelReferenceImage: boolean;
defaultCandidateCountPerLevel: number;
}
export interface PuzzleImageGenerationPlan {
mode: 'single_level' | 'multi_level';
levels: CreativePuzzleLevelDraftInput[];
estimatedCostRange: PuzzleTemplateCostRange;
}
```
积分范围由拼图模板协议提供，Agent 只能解释和选择，不能自行发明价格。真实扣费仍以后端钱包/任务系统最终结算为准。
### 4.5 反思模块 Reflection
职责：让 Agent 在交付前检查自己的选择是否真的适合用户，而不是一次模型输出就结束。
反思节点运行在每次关键行动后：
1. 模板选择后：检查是否已经向用户显式展示拼图模板和积分范围。
2. 用户确认前：检查是否误承诺了非拼图模板或非真实价格。
3. 草稿填充后：检查字段是否完整、玩法体验是否成立。
4. 图片使用前：检查单关卡/多关卡图片计划是否与模板协议一致。
5. 最终交付前：检查是否需要用户确认。
反思输出：
```ts
export interface CreativeReflectionReport {
pass: boolean;
score: number;
issues: CreativeReflectionIssue[];
revisionInstruction?: string | null;
shouldAskUser: boolean;
shouldTryAlternativePlayType: boolean;
}
```
实现方式：
- 用 LangGraph 增加 `reflect` 节点。
- 反思模型拿到感知状态、计划、工具调用结果和目标草稿。
- 如果 `pass=false` 且迭代次数未超限，回到 `plan` 或 `act`。
- 如果问题是用户偏好缺失，调用 `ask_user_clarification`。
- 如果问题是契约字段缺失，调用目标玩法 draft 修复工具。
- 如果问题是未展示模板选择或积分范围，回到模板确认节点。
- 如果问题是多关卡计划超出模板 `maxLevelCount`，调用拼图计划修复工具。
硬性终止条件：
- 最大反思循环 2 次。
- 同一工具同一参数失败 2 次后停止并返回可读错误。
- 预算超限时返回当前可用草稿和补救建议。
反思记忆要沉淀：
- 模板误选原因。
- 用户是否接受模板积分范围。
- 单关卡或多关卡图片生成计划是否被用户调整。
- 用户手动改选的玩法。
- 结果页返回编辑最多的字段。
- 发布失败 blockers。
### 4.6 协作模块 Collaboration
职责：把复杂创意任务拆给多个专长 Agent，而不是让单个提示词吞掉所有任务。
当前首版只开放拼图协作，不开放其它玩法子 Agent。建议四个子 Agent：
```text
创意导演 Agent：理解用户目标，决定整体方向和互动体验。
视觉解读 Agent：理解图片、构图、主体、风格和可交互线索。
拼图模板策展 Agent：基于拼图模板协议和历史作品选择候选拼图模板，并读取积分范围。
拼图专家 Agent：生成单关卡或多关卡拼图草稿 payload 和图片生成计划。
契约审校 Agent：检查字段、发布门槛、积分展示、安全边界和可恢复性。
```
LangChain-Rust 落地：
- 用 LangGraph 的 subgraph 表达子 Agent。
- 子 Agent 共享 `CreativeAgentState`，但只能写自己负责的字段。
- 主 Agent 通过 handoff 工具委托子任务。
- 必要时并行执行视觉解读和拼图模板知识检索，再由创意导演合并。
- 协作结果由契约审校 Agent 最终检查。
协作不是增加 UI 复杂度。前端仍只看到一个 Agent，但后端内部有多个可观测步骤，SSE 推送简短阶段即可。
## 5. Agent 状态机
LangGraph 状态建议：
```rust
pub struct CreativeAgentGraphState {
pub session_id: String,
pub owner_user_id: String,
pub perception: Option<CreativePerceptionState>,
pub memory: Option<CreativeAgentMemorySnapshot>,
pub reasoning: Option<CreativeReasoningState>,
pub tool_results: Vec<CreativeToolResult>,
pub reflection: Option<CreativeReflectionReport>,
pub target_binding: Option<CreativeTargetSessionBinding>,
pub final_response: Option<CreativeAgentFinalResponse>,
pub iteration_count: u32,
}
```
Graph 节点：
```text
load_memory
perceive_input
plan_with_agent
act_with_tools
reflect_result
collaborate_if_needed
finalize_or_ask_user
persist_memory
```
边：
```text
load_memory -> perceive_input
perceive_input -> plan_with_agent
plan_with_agent -> act_with_tools
act_with_tools -> reflect_result
reflect_result(pass) -> finalize_or_ask_user
reflect_result(revise) -> plan_with_agent
reflect_result(collaborate) -> collaborate_if_needed
collaborate_if_needed -> act_with_tools
finalize_or_ask_user -> persist_memory
```
## 6. 数据契约
新增 shared contracts：
```text
packages/shared/src/contracts/creativeAgent.ts
server-rs/crates/shared-contracts/src/creative_agent.rs
```
核心 DTO：
```ts
export type CreativeAgentStage =
| 'perceiving'
| 'thinking'
| 'remembering'
| 'selecting_puzzle_template'
| 'waiting_template_confirmation'
| 'planning_puzzle_levels'
| 'acting'
| 'reflecting'
| 'collaborating'
| 'waiting_user'
| 'target_ready'
| 'failed';
export interface CreativeAgentSessionSnapshot {
sessionId: string;
stage: CreativeAgentStage;
perception: CreativePerceptionState | null;
reasoning: CreativeReasoningState | null;
puzzleTemplateCatalog: PuzzleCreativeTemplateProtocol[];
puzzleTemplateSelection: PuzzleCreativeTemplateSelection | null;
puzzleImageGenerationPlan: PuzzleImageGenerationPlan | null;
reflection: CreativeReflectionReport | null;
targetBinding: CreativeTargetSessionBinding | null;
messages: CreativeAgentMessage[];
updatedAt: string;
}
export interface PuzzleCreativeTemplateSelection {
templateId: string;
title: string;
reason: string;
costRange: PuzzleTemplateCostRange;
supportedLevelMode: 'single' | 'multi' | 'single_or_multi';
selectedLevelMode: 'single_level' | 'multi_level';
plannedLevelCount: number;
requiresUserConfirmation: true;
}
```
HTTP facade：
```text
POST /api/runtime/creative-agent/sessions
GET /api/runtime/creative-agent/sessions/{sessionId}
POST /api/runtime/creative-agent/sessions/{sessionId}/messages/stream
POST /api/runtime/creative-agent/sessions/{sessionId}/confirm
POST /api/runtime/creative-agent/sessions/{sessionId}/cancel
```
SSE 事件：
```text
stage
agent_message_delta
puzzle_template_catalog
puzzle_template_selection
puzzle_cost_range
puzzle_level_plan
tool_started
tool_completed
reflection
target_session
need_user_input
session
error
```
## 7. SpacetimeDB 持久化
新增表：
```text
creative_agent_session
creative_agent_message
creative_agent_input_asset
creative_agent_tool_call
creative_agent_reflection
creative_agent_target_binding
creative_agent_memory_index
puzzle_creative_template_snapshot
puzzle_creative_level_generation_plan
```
关键约束：
1. SpacetimeDB 保存结构化真相和 JSON 快照，不保存大图片 data URL。
2. 工具调用和反思必须可追溯，便于排查模型为什么选择某个模板。
3. `creative_agent_memory_index` 只保存记忆元数据和向量索引引用，不直接承担向量数据库职责。
4. 表结构变更必须同步 `migration.rs`、`SPACETIMEDB_TABLE_CATALOG.md` 和 bindings。
5. `creative_agent_session` 必须保存当前拼图模板目录、已确认的模板选择快照和积分范围，保证刷新后仍能恢复“先选模板、再确认配置”的两段式状态。
6. `puzzle_creative_level_generation_plan` 保存单关卡/多关卡图片生成计划，包括每关 `level_id`、`level_name`、`picture_description`、`image_prompt`、`generation_status`、`candidate_count` 和 `estimated_cost_points`。
7. 非拼图玩法不新增 target binding，避免后续误恢复到暂不支持的玩法。
8. 自然语言修订草稿字段要记录工具调用、原始用户指令、结构化 patch 和修改后的 draft 版本，便于撤销、审计和反思。
9. 试玩 run 与草稿 session 需要有绑定关系，确保“立即玩”后返回结果页能恢复同一草稿。
## 8. 拼图首版落地
拼图首版不是“规则判断为拼图”，而是模型通过工具和反思得出选择。但产品边界明确：当前只支持拼图模板。Agent 必须把非拼图创意转化为拼图可承接的方案，或告诉用户当前不支持该模板。
### 8.1 强制模板选择与积分展示
任何草稿生成前都必须先进入 `selecting_puzzle_template` 和 `waiting_template_confirmation`。
前端至少展示：
- 拼图模板标题
- 模板缩略图或示意图
- Agent 选择理由
- 支持单关卡、多关卡或二者皆可
- 计划关卡数
- 预计积分范围，例如 `预计消耗 8 到 18 光点`
积分范围来自拼图模板协议：
```ts
export interface PuzzleTemplateCostRange {
minPoints: number;
maxPoints: number;
pricingUnit: 'point';
reason: string;
}
```
Agent 可以解释 `reason`，但不能修改 `minPoints` / `maxPoints`。如果模板协议没有积分范围，该模板不能展示为可选项。
Agent 可调用工具：
```text
retrieve_puzzle_template_catalog
inspect_puzzle_draft_contract
select_puzzle_template
confirm_puzzle_template
plan_puzzle_level_images
create_puzzle_agent_session
compile_puzzle_draft
apply_puzzle_draft_natural_language_edit
validate_puzzle_result_preview
select_uploaded_image_as_puzzle_cover
generate_puzzle_images
start_puzzle_draft_test_run
return_to_puzzle_result
```
### 8.2 拼图模板协议
拼图模板协议应封装在拼图模块，不放在通用 Agent：
```text
server-rs/crates/module-puzzle/src/creative_templates.rs
server-rs/crates/module-puzzle/src/creative_tools.rs
server-rs/crates/shared-contracts/src/puzzle_creative_template.rs
packages/shared/src/contracts/puzzleCreativeTemplate.ts
```
协议至少包含：
```ts
export interface PuzzleCreativeTemplateProtocol {
templateId: string;
title: string;
summary: string;
previewImageSrc: string | null;
supportedLevelMode: 'single' | 'multi' | 'single_or_multi';
minLevelCount: number;
maxLevelCount: number;
defaultLevelCount: number;
costRange: PuzzleTemplateCostRange;
imagePolicy: PuzzleTemplateImageGenerationPolicy;
draftFieldHints: PuzzleTemplateDraftFieldHints;
}
```
模板示例：
```json
{
"templateId": "puzzle.family-keepsake",
"title": "家庭纪念拼图",
"supportedLevelMode": "single_or_multi",
"minLevelCount": 1,
"maxLevelCount": 6,
"defaultLevelCount": 3,
"costRange": {
"minPoints": 8,
"maxPoints": 24,
"pricingUnit": "point",
"reason": "按关卡数、每关候选图数量和是否使用上传图估算"
}
}
```
### 8.3 单关卡与多关卡图片生成
拼图草稿必须支持两种计划：
```ts
export type PuzzleLevelGenerationMode = 'single_level' | 'multi_level';
export interface PuzzleImageGenerationPlan {
mode: PuzzleLevelGenerationMode;
templateId: string;
estimatedCostRange: PuzzleTemplateCostRange;
levels: PuzzleImageGenerationPlanLevel[];
}
export interface PuzzleImageGenerationPlanLevel {
levelId: string;
levelName: string;
pictureDescription: string;
imagePrompt: string;
pictureReference?: string | null;
candidateCount: number;
}
```
单关卡：
- `levels.length = 1`
- 可使用上传图直出，也可生成一张候选图。
- 适合纪念照、商品图、单张海报、单主题知识图。
多关卡：
- `levels.length` 必须在模板 `minLevelCount` 到 `maxLevelCount` 之间。
- 每关有独立 `levelName`、`pictureDescription` 和 `imagePrompt`。
- 可选择每关生成一张图，也可第一关使用上传图、后续关卡生图。
- 适合故事型照片组、知识步骤、活动流程、系列商品、节日卡片组。
生成工具建议：
```ts
export interface GeneratePuzzleLevelImagesToolInput {
sessionId: string;
plan: PuzzleImageGenerationPlan;
imageModel: 'gpt-image-2';
}
export interface GeneratePuzzleLevelImagesToolOutput {
draft: PuzzleResultDraft;
levels: PuzzleDraftLevel[];
costEstimate: PuzzleTemplateCostRange;
generatedCount: number;
uploadedCount: number;
}
```
工具内部可以复用现有 `generate_puzzle_images` action，但必须以 `levelId` 为粒度逐关执行，或新增拼图后端 action `generate_puzzle_level_images` 批量处理。批量 action 仍归属拼图模块，通用 Agent 只负责调用。
### 8.5 模板草稿字段填充与自然语言修订
Agent 创作互动内容的本质就是向模板中的草稿字段填充内容。拼图模板草稿字段是唯一创作真相：表单化创作页是这些字段的可视化编辑器，Agent 对话是这些字段的自然语言编辑器，二者属于同一条创作流程。
通用 Agent 只负责把用户自然语言转成“草稿字段填充 / 修订意图”，真正的字段写入仍通过拼图模块 Tool 完成：
```ts
export interface PuzzleDraftFieldEditInstruction {
scope: 'work' | 'level' | 'tags' | 'cover' | 'images' | 'all';
operation: 'set' | 'append' | 'replace' | 'remove' | 'reorder';
fieldPath: string;
value: string | string[] | boolean | number | null;
rationale: string;
}
export interface ApplyPuzzleDraftNaturalLanguageEditToolInput {
sessionId: string;
userInstruction: string;
currentDraftSnapshot: PuzzleResultDraft;
}
export interface ApplyPuzzleDraftNaturalLanguageEditToolOutput {
updatedDraft: PuzzleResultDraft;
editInstructions: PuzzleDraftFieldEditInstruction[];
needsUserConfirmation: boolean;
confirmationSummary: string;
}
```
这个工具由拼图模块封装，内部要做三步：
1. 用模型把自然语言改写成结构化草稿字段 patch。
2. 用拼图领域规则校验 patch 是否会破坏草稿约束。
3. 通过现有草稿保存接口写回同一份 `PuzzleResultDraft` 或 `formDraft`。
典型自然语言字段修订场景：
- “把这张图改成更适合家庭纪念。”
- “第二关再多加一张风景图。”
- “标题别太正式，轻松一点。”
- “主题标签里去掉商品感，增加温暖和节日感。”
Agent 不能直接篡改结果页 DOM，也不能绕过拼图草稿字段写最终发布数据。用户在表单里手动编辑、用户用自然语言让 Agent 编辑，本质上都必须落到同一份草稿字段 patch。
### 8.6 立即玩与试玩闭环
生成好的互动内容必须能立即玩到。对拼图来说，Agent 完成草稿后必须直接导向现有 `puzzle-result`，并提供明确的“立即玩”入口。
闭环要求：
1. 草稿创建成功后，结果页首屏就能看到 `Play` 或“立即玩”按钮。
2. 点击后直接启动 `puzzle-runtime`，不需要用户再手动跳过别的中间页。
3. 如果当前草稿还在生成更多关卡图片，已完成关卡可先试玩，后续图片再逐关补齐。
4. 试玩入口必须复用现有 `PuzzleRuntimeShell` 和 `startPuzzleRun` 链路。
5. 试玩后返回结果页时，仍然停留在同一草稿上下文，不丢失表单草稿状态。
结果页到运行态之间的切换不由通用 Agent 再次判断，而是由拼图模块暴露的 `start_run` / `resume_run` / `return_to_result` 工具完成。
### 8.4 拼图专家输出
拼图专家 Agent 需要产出：
```ts
export interface PuzzleCreativeDraftIntent {
templateSelection: PuzzleCreativeTemplateSelection;
imageGenerationPlan: PuzzleImageGenerationPlan;
workTitle: string;
workDescription: string;
workTags: string[];
levels: CreativePuzzleLevelDraftInput[];
}
```
字段映射仍必须对齐现有契约：
- `PuzzleResultDraft.workTitle`
- `PuzzleResultDraft.workDescription`
- `PuzzleResultDraft.workTags`
- `PuzzleResultDraft.levels[].levelName`
- `PuzzleResultDraft.levels[].pictureDescription`
- `PuzzleResultDraft.levels[].pictureReference`
领域校验仍由 `module-puzzle` 负责。Agent 可以创造内容，但不能绕过发布 blockers。表单化创作页与 Agent 自然语言修订都只是这些字段的不同编辑界面。
## 9. 前端体验
前端只呈现一个“智能创作 Agent”入口：
1. 用户输入文字、上传图片或文档。
2. 前端显示 Agent 正在理解素材、构思玩法、生成草稿。
3. Agent 必须先展示拼图模板目录。
4. 用户选择模板并确认关卡模式、关卡数和预计积分范围后，Agent 才能生成草稿。
5. 生成完成后进入拼图结果页，并提供“立即玩”入口，点击后直接进入拼图运行态。
6. 结果页保留原来的表单化创作能力，包括作品标题、作品描述、作品标签、关卡名称、关卡图面描述、关卡图面参考、关卡图片生成和选图；这些控件编辑的是同一份模板草稿字段。
7. Agent 对话区继续可用，用户可以用自然语言补填或修订模板草稿字段，后端通过拼图模块 Tool 生成结构化 patch 并回写同一份草稿；可写字段仅限 `workTitle`、`workDescription`、`workTags`、`levels[].levelName`、`levels[].pictureDescription`、`levels[].pictureReference`。
8. 若 Agent 有关键不确定点，弹出独立确认面板。
9. 用户确认或回答后，Agent 继续执行并进入拼图结果页或保持在当前草稿上下文。
UI 不展示大段规则说明，只展示：
- 当前阶段
- 简短 Agent 回复
- 拼图模板选择和积分范围
- 单关卡 / 多关卡计划
- 需要确认的问题
- 最终草稿入口
- 立即玩入口
- 表单化草稿字段编辑入口
- Agent 自然语言补填 / 修订入口
移动端优先，上传图片预览使用横向缩略图条，确认面板用底部抽屉。
## 10. 安全与治理
模型能力是核心，但不能没有边界：
1. 工具权限边界：模型只能调用已注册工具，不能直接写库。
2. 契约边界：Typed parser 和目标玩法 validator 必须通过。
3. 成本边界：AgentExecutor 设置最大迭代、最大工具调用、超时和预算。
4. 内容安全：人物肖像、儿童内容、版权图、隐私图进入确认或拒绝。
5. 记忆安全：长期记忆按用户 namespace 隔离。
6. 可观测性：Callbacks 记录每个节点、工具、token、耗时和错误。
## 11. 分阶段落地
### Phase 1：LangChain-Rust PoC + 拼图闭环
- 新增 `platform-agent` PoC。
- 封装 LangChain-Rust FunctionCallingAgent / AgentExecutor。
- 注册拼图相关工具。
- 只支持拼图模板；非拼图模板在 Agent 能力中标记为暂不支持。
- 强制展示拼图模板选择、选择理由和预计积分范围。
- 支持文字 + 单图输入，模型自主选择拼图模板并填入草稿字段。
- 支持单关卡图片生成计划和多关卡图片生成计划。
- 生成后的拼图内容点击“立即玩”可直接进入 `puzzle-runtime`。
- 保留结果页原有表单化草稿字段编辑入口。
- 支持 Agent 自然语言补填 / 修订模板草稿字段，并通过拼图模块 Tool 回写草稿。
- SSE 推送六模块阶段。
- 结果进入现有 `puzzle-result`。
### Phase 2：记忆与反思闭环
- 增加 `creative_agent_tool_call`、`creative_agent_reflection`、`creative_agent_memory_index`。
- 引入短期 Memory 和长期检索。
- 记录用户改选、发布失败、返回编辑等反馈。
- 反思循环支持自动修正草稿。
### Phase 3：多玩法协作
- 在产品开放后再增加 Match3D、大鱼吃小鱼、方洞挑战、RPG 世界专家 Agent。
- 使用 LangGraph subgraph 做多 Agent 协作。
- 支持多候选玩法对比和人工确认。
## 12. 验收标准
功能验收：
1. 用户输入含图文材料时，Agent 能说出它理解到的创作意图。
2. Agent 能调用拼图模板知识检索，而不是靠硬编码规则选模板。
3. Agent 必须显式展示拼图模板、选择理由和预计积分范围，用户确认后才生成草稿。
4. 非拼图输入不会创建其它玩法 session，只能转成拼图方案或提示暂不支持。
5. Agent 能自主选择拼图模板并生成可通过契约校验的 `PuzzleResultDraft`。
6. 当图片更适合直接作为拼图图面时，Agent 能选择 uploaded candidate，而不是强制生图。
7. Agent 能生成单关卡图片计划，也能生成多关卡图片计划。
8. 多关卡计划中每关都有独立 `levelName`、`pictureDescription` 和 `imagePrompt`。
9. 多关卡图片生成逻辑通过拼图模块工具执行，通用 Agent 不直接拼接 `levelsJson`。
10. 生成好的拼图内容点击“立即玩”后能直接进入 `puzzle-runtime`。
11. 从 `puzzle-runtime` 返回时仍恢复同一 `puzzle-result` 草稿上下文。
12. 结果页保留表单化草稿字段编辑能力，用户可以修改作品标题、作品描述、作品标签、关卡名称、关卡图面描述和关卡图面参考。
13. 用户用自然语言提出“把标题改轻松一点”“第二关加一张风景图”等请求时，Agent 能生成结构化草稿字段 patch 并通过拼图模块 Tool 回写同一份草稿。
14. 自然语言修订草稿字段后必须重新通过拼图草稿校验和结果预览校验。
15. 当不确定时，Agent 只问一个关键问题，而不是把所有字段丢给用户填写。
16. 反思节点能发现未展示积分范围、关卡数越界、草稿字段缺失或自然语言字段 patch 风险，并自动修正一次。
17. 工具调用、反思报告、模板选择、草稿字段 patch 和目标拼图 session 绑定能恢复和审计。
建议命令：
```bash
cd server-rs
cargo test -p shared-contracts creative_agent
cargo test -p module-creative-agent
cargo check -p platform-agent
cargo check -p api-server
```
涉及 SpacetimeDB schema 后：
```bash
npm run spacetime:generate -- --rust-only
npm run check:server-rs-ddd
```
前端：
```bash
npm run typecheck
npm run check:encoding
```
## 13. 当前实现状态
截至 `2026-05-05`，任务 C 已完成首版 PoC 落地：
1. `server-rs/crates/platform-agent` 已新增为 workspace member。
2. `platform-agent` 已提供项目自有的 `CreativeAgentExecutor`、工具注册表、回调事件、`gpt-5` 多模态请求适配器和 mock executor。
3. `platform-llm` 已支持 Responses 多模态输入块，`input_text` 与 `input_image` 会按 content part 序列化到请求体。
4. 任务 C 的验收命令已通过：`cargo check -p platform-agent`、`cargo test -p platform-agent`、`cargo test -p platform-llm responses_multimodal`。
截至 `2026-05-05`，任务 E 的 API / SSE facade 已补充 Windows debug 稳定性修复：
1. `/api/runtime/creative-agent/sessions/{sessionId}/messages/stream` 不再把 Agent 执行、模型请求、会话更新和所有 SSE 事件内联到单个大型 `async_stream` 中。
2. 当前实现使用后台 `tokio::spawn` 执行业务流程，并通过 `mpsc` / `UnboundedReceiverStream` 向 Axum 返回轻量 SSE stream；执行失败会更新会话为 `failed` 并发送 SSE `error`。
3. 已补实际消费 SSE body 的回归测试，覆盖 `stage`、`puzzle_template_catalog` 与 `done` 事件；`puzzle_template_selection`、`puzzle_cost_range`、`puzzle_level_plan` 只在用户确认后进入后续快照或流程。
## 14. 本方案相对旧方案的变化
旧方案偏“规则预筛 + workflow + Adapter”。新方案调整为：
1. 模型负责理解素材、整理候选和草稿构思；最终模板由用户从多个候选中主动选择。
2. LangChain-Rust AgentExecutor / FunctionCallingAgent 承担工具调用决策。
3. LangGraph 承担六模块闭环和反思循环。
4. Memory/RAG 让 Agent 学习用户偏好和模板经验。
5. 当前只开放拼图玩法，但模板选择仍是显式 Agent 步骤，不因只有一个玩法而跳过。
6. 拼图模板协议必须携带积分范围，用户选择模板并确认配置后才进入草稿生成。
7. 单关卡/多关卡图片生成通过拼图模块 Tool 和模板协议实现，不写进通用 Agent。
8. Agent 创作方式就是填充和修订模板草稿字段；表单化创作页和 Agent 自然语言修订都操作同一份 `PuzzleResultDraft`，并围绕 `workTitle`、`workDescription`、`workTags`、`levels[].levelName`、`levels[].pictureDescription`、`levels[].pictureReference` 这一组字段协同。
9. Adapter 从“路由实现”降级为 Agent action tool。
10. 规则只保留为安全、契约、成本和权限边界。

6
docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md
View File

@@ -108,6 +108,12 @@ Node 旧链路对上传封面有明确处理：
Rust 本批必须保持这组兼容约束。
2026-05-08 交互补充：
1. 前端裁剪面板不再展示 `缩放 / 左右位置 / 上下位置` 参数滑杆。
2. 作者直接在图片上拖拽裁剪框内部移动区域，或拖拽四边、四角调整裁剪范围。
3. 调整过程中前端持续锁定 `16:9`，确认时仍只提交后端兼容的 `cropRect`。
## 4. 请求与响应 contract
### 4.1 `POST /api/custom-world/scene-image`

6
docs/technical/M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md
View File

@@ -122,6 +122,12 @@
2. AI worker 绕过确认链路写出不完整记录
3. 把 OSS 响应中的派生 URL 当成对象真相
### 5.1 OSS V4 签名时间格式
`platform-oss` 的 OSS V4 签名时间必须显式格式化为 `YYYYMMDDTHHMMSSZ`，签名 scope 日期必须显式格式化为 `YYYYMMDD`。实现中不要依赖 `OffsetDateTime::time().to_string()` 或 `date().to_string()` 再替换字符，因为 UTC 小时、分钟、秒为个位数时可能不会保留前导零，导致 AI 生图已完成但上传 OSS 阶段报 `OSS V4 签名时间格式化失败`。
拼图、视觉小说、自定义世界等所有服务端生成图片上传链路都复用同一套 `platform-oss` 签名 helper；新增签名逻辑时必须覆盖个位时间分量的测试样例，例如 `05:03:09` 应输出 `T050309Z`。
## 6. 与 Web 端的边界
Web 端当前只允许：

18
docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md
View File

@@ -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 回到同一作品详情。

2
docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md
View File

@@ -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 天。

21
docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md
View File

@@ -9,7 +9,7 @@
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。
两条文档均指向 OpenAI 兼容风格的图片生成入口：`POST https://api.apimart.ai/v1/images/generations`，头部使用 `Authorization: Bearer {APIMART_API_KEY}`。请求体至少包含 `model`、`prompt`、`n`、`official_fallback = true`、`size`。返回体按 OpenAI images 兼容格式优先读取 `data[].url`，若供应商返回异步任务结构，则继续按 `task_id` / `tasks/{task_id}` 轮询并提取图片 URL。
## 模型选项
@@ -43,7 +43,7 @@
- `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`。`gemini-3.1-flash-image-preview` 额外带 `resolution = "1K"`，对齐约 1024px 的拼图正方形素材。
5. APIMart 尺寸使用文档要求的比例写法 `1:1`，所有 APIMart 图片请求体固定携带 `official_fallback = true`。`gemini-3.1-flash-image-preview` 额外带 `resolution = "1K"`，对齐约 1024px 的拼图正方形素材。
6. APIMart 生成成功后仍下载远程图片，沿用现有 OSS 私有对象、`asset_object` 和 `asset_entity_binding` 写入流程。若图片已成功上传 OSS，但 Maincloud / SpacetimeDB 短暂返回 `503 Service Unavailable`，资产索引写入允许降级跳过，并返回本次生成图片；日志必须记录 `拼图图片资产索引写入因 SpacetimeDB 连接不可用而降级跳过`。
7. `save_puzzle_generated_images` 写回草稿时若遇到 Maincloud 连接级 `503` 或断线，API 层基于本次生成结果合成 session 快照返回给前端，避免 APIMart 已成功出图却被后置持久化误报成服务不可用。余额不足、参数错误、上游生图失败仍按原错误返回，不做伪成功。
8. 结果页 `generate_puzzle_images` 会携带当前作品信息和 `levelsJson`。当 Maincloud / SpacetimeDB 在读取 session 阶段就返回连接级 `503` 或断线时，后端必须先用这份结果页快照构造最小内存 session，再继续调用 APIMart；外部图片已经生成后仍按第 6、7 条处理持久化降级。余额不足、参数错误、缺少草稿快照、关卡不存在等业务错误不走此降级。
@@ -51,6 +51,14 @@
10. APIMart 错误统一映射为 `502 UPSTREAM_ERROR`，`details.provider = "apimart"`，保留上游状态码、业务 message 和截断后的 raw excerpt。
11. 拼图首图生成 `compile_puzzle_draft` 与关卡图片生成 `generate_puzzle_images` 每次预扣 `2` 光点；余额不足仍返回 `409 CONFLICT`，Maincloud 连接级 503 仍按既有降级策略处理。
## 关卡名多模态生成
1. 第一关和结果页关卡重新生图的最终关卡名统一由 APIMart Chat Completions `gpt-4o-mini` 生成。
2. 输入必须同时包含生成完成后的正式图片和当前关卡 `pictureDescription`；图片由 `api-server` 从生成结果字节压缩为最多 768 边长的 PNG Data URL 后，以 OpenAI 兼容 `messages[].content[]` 的 `image_url` 形式传入。
3. 文本模型仍只输出 `{"levelName":"..."}`，并继续复用现有 2 到 8 个中文字符、禁用“画面 / 拼图 / 作品”等泛词的解析与归一化规则。
4. `gpt-4o-mini` 调用失败、返回非法或 APIMart 文本配置缺失时，不阻断图片生成；后端保留图片生成前的文本关卡名或确定性兜底名。
5. 关卡名与候选图在同一次 `save_puzzle_generated_images` 中写回 `levels_json` 和正式候选图，避免图片与关卡名不同步。
## 环境变量
新增服务端环境变量：
@@ -69,7 +77,8 @@ APIMART_IMAGE_REQUEST_TIMEOUT_MS=180000
2. 点击“生成草稿”时，后端首图生成使用当前表单选择的模型。
3. 点击“生成画面 / 重新生成画面”时，后端当前关卡图片生成使用关卡详情选择的模型。
4. 历史 `original` 或空模型值不会再触发 DashScope，统一按 `gpt-image-2` 请求 APIMart。
5. 选择 APIMart 模型时，请求 `POST {APIMART_BASE_URL}/images/generations`，使用 `Authorization: Bearer {APIMART_API_KEY}`，`model` 等于请求值，`size = 1:1`。
6. “生成草稿”和关卡详情生图按钮展示 `消耗2光点`；关卡详情确认后展示 30 秒预计剩余进度条。
7. 不改 SpacetimeDB 表结构，因此无需更新 `migration.rs` 或重新生成 bindings。
8. 后端改动后运行对应 Rust 测试，并按项目约束用 `npm run api-server` 重启验证。
5. 选择 APIMart 模型时，请求 `POST {APIMART_BASE_URL}/images/generations`，使用 `Authorization: Bearer {APIMART_API_KEY}`，`model` 等于请求值，`official_fallback = true`，`size = 1:1`。
6. 首图和结果页关卡重新生图成功后，Network 中应先完成图片生成，再调用 APIMart `POST {APIMART_BASE_URL}/chat/completions`，请求模型为 `gpt-4o-mini`，消息同时包含画面描述文本和正式图 `image_url` Data URL。
7. “生成草稿”和关卡详情生图按钮展示 `消耗2光点`；关卡详情确认后展示 30 秒预计剩余进度条。
8. 不改 SpacetimeDB 表结构，因此无需更新 `migration.rs` 或重新生成 bindings。
9. 后端改动后运行对应 Rust 测试，并按项目约束用 `npm run api-server` 重启验证。

29
docs/technical/PUZZLE_IMAGE_ASSET_PROXY_FIX_2026-04-27.md
View File

@@ -1,31 +1,40 @@
# 拼图生成图片资源代理修复
# 拼图生成图片读取链路修复
日期：`2026-04-27`
更新：`2026-05-08`
## 背景
拼图结果页的“生成或更换图片”会在 `api-server` 中调用 DashScope 生成图片，再把候选图上传到 OSS，最终以 `/generated-puzzle-assets/...` 旧兼容路径写回 `PuzzleGeneratedImageCandidate.image_src` 与草稿封面字段。
本次排查发现拼图图片写入路径已经进入 `platform-oss::LegacyAssetPrefix::PuzzleAssets`，但后端 Axum 旧资源代理和 Vite 本地代理没有挂载 `/generated-puzzle-assets`。这会导致候选图或正式图无法读取；后续如果把已有候选图作为参考图继续更换图片，也会让参考图读取链路失效。
历史排查曾发现拼图图片写入路径已经进入 `platform-oss::LegacyAssetPrefix::PuzzleAssets`，但后端 Axum 旧资源代理和 Vite 本地代理没有挂载 `/generated-puzzle-assets`。当时的处理口径是补旧资源代理。
当前 `WP-DEL` 后，旧 `/generated-*` 直读代理已经物理删除；`/generated-puzzle-assets/...` 只允许作为 `legacyPublicPath` / OSS object key 标识。浏览器不能再直接请求该路径，必须通过 `/api/assets/read-url?legacyPublicPath=...` 换取短期签名 URL 后预览。
## 修复口径
1. `server-rs/crates/api-server/src/legacy_generated_assets.rs` 增加 `proxy_generated_puzzle_assets(...)`，复用统一的 OSS 签名读取逻辑。
2. `server-rs/crates/api-server/src/app.rs` 挂载 `/generated-puzzle-assets/{*path}`，与角色、大鱼、自定义世界图片资源前缀保持一致。
3. `vite.config.ts` 增加 `/generated-puzzle-assets` dev proxy，保证本地网页端不会因为 Vite 代理缺口读不到后端资源。
1. `platform-oss::LEGACY_PUBLIC_PREFIXES` 必须包含 `generated-puzzle-assets`，保持直传票据、服务端上传、read-url 支持列表和错误提示同一口径。
2. `src/services/assetReadUrlService.ts` 的 `isGeneratedLegacyPath(...)` 需要同时识别 `/generated-puzzle-assets/...` 和 `generated-puzzle-assets/...`。后者可能来自 object key 形态的历史字段。
3. `ResolvedAssetImage` / `useResolvedAssetReadUrl` 在签名 URL 返回前不能把裸 `/generated-*` 或 `generated-*` 写进 `<img src>`。
4. `refreshKey` 只能用于跳过前端签名 URL 缓存并重新请求 `/api/assets/read-url`，不能再给 OSS V4 签名 URL 追加 `_v` 等额外 query；OSS 会把 query 纳入签名，额外参数会让新生成图变成 403/破图。
5. 历史素材被选为参考图后，参考图小预览也必须走 `ResolvedAssetImage`，不能使用裸 `<img src="/generated-*">`。
6. 禁止恢复 `/generated-puzzle-assets/{*path}` Axum 路由或 Vite 直读代理；正式读取统一走 `/api/assets/read-url`。
## 后续约束
1. 任何新增 `LegacyAssetPrefix` 都必须同时检查：
- `platform-oss` 前缀枚举
- `api-server` 旧资源代理路由
- Vite dev proxy
- `platform-oss::LEGACY_PUBLIC_PREFIXES`
- `/api/assets/read-url` 入参解析
- 前端 `isGeneratedLegacyPath(...)` 是否能识别
2. 拼图候选图 JSON 仍保持 SpacetimeDB 持久化结构 `PuzzleGeneratedImageCandidate` 的 snake_case 字段，不把 HTTP camelCase 响应结构写入 `draft_json`。
3. 图片生成、OSS 读写和外部参考图解析继续留在 `api-server`，不能下沉到 SpacetimeDB reducer。
4. 如果图片组件需要刷新 generated 私有资源，优先让 `refreshKey` 触发重新换签；不要修改已返回的 `signedUrl`。
## 验收
1. `npm run check:encoding`
2. `cargo check -p api-server --manifest-path server-rs/Cargo.toml`
3. `npm run api-server` 重启后，点击拼图结果页“生成或更换图片”，候选图应能写回并正常展示。
1. `npm run test -- src\services\assetReadUrlService.test.ts src\hooks\useResolvedAssetReadUrl.test.tsx src\components\puzzle-result\PuzzleResultView.test.tsx`
2. `cargo test -p platform-oss --manifest-path server-rs\Cargo.toml`
3. `npm run check:encoding`
4. `npm run api-server` 重启后检查 `/healthz`，再点击拼图结果页“生成或更换图片”，候选图应能写回并正常展示。

12
docs/technical/PUZZLE_PICTURE_ONLY_CREATION_AND_AI_TAGS_2026-05-03.md
View File

@@ -19,10 +19,18 @@
3. `puzzle-select-image` 展示为“写入正式草稿”：把首图设为第一关正式图，并同步到结果页草稿。
4. `ready` 文案提示进入结果页补作品信息；不得暗示作品名称、作品描述或作品标签已经完整生成。
### 2026-05-08 进度页预计等待与步骤动效补充
1. 拼图草稿生成进度页预计等待时间固定按 `60` 秒展示和倒计时，后端真实完成后立即进入结果页，不强制等满 60 秒。
2. 60 秒进度拆成三段：`compile` 约 12 秒，`puzzle-images` 约 42 秒，`puzzle-select-image` 约 6 秒。
3. 生成中即使后端 `compile_puzzle_draft` 仍是一次同步 action，前端也必须按本地计时推进总进度和当前步骤进度，避免页面停在静态等待态。
4. 每个步骤卡片都展示独立进度条；已完成步骤显示 100%，当前步骤按该段预计时长推进，后续步骤保留 0% 待处理状态。
5. 后端未返回前总进度最多推进到 98%，防止 UI 提前宣称生成完成；只有 action 成功并写回 `ready` 后才显示 100%。
## 草稿默认值
1. 后端先由 `module-puzzle` 生成可回滚的确定性草稿，再由 `api-server` 基于画面描述调用文本模型生成第一关关卡名；模型不可用或返回非法时才降级到确定性兜底名。
2. 第一关关卡名生成后，必须写回首关 `levelName`，并在入口直创默认场景下作为 `workTitle` 同步写入草稿和作品草稿卡。
1. 后端先由 `module-puzzle` 生成可回滚的确定性草稿，再由 `api-server` 生成第一关关卡名。图片生成前可先基于画面描述生成临时关卡名；正式图片生成完成后，必须使用 APIMart Chat Completions 的 `gpt-4o-mini`，把正式图片 data URL 与画面描述一起传入模型，生成最终关卡名。
2. 最终关卡名生成后，必须写回首关 `levelName`，并在入口直创默认场景下作为 `workTitle` 同步写入草稿和作品草稿卡；模型不可用、图片压缩失败或返回非法时，才保留前一步文本名或确定性兜底名。
3. `workDescription` 默认保持空字符串，不再回退为画面描述。
4. `themeTags` 默认保持空数组，不再由入口画面描述自动推断为正式作品标签。
5. `formDraft` 只保留 `pictureDescription`，`workTitle` 与 `workDescription` 为空。

2
docs/technical/PUZZLE_SINGLE_PLAYER_AND_REAL_IMAGE_PLAN_2026-04-24.md
View File

@@ -48,7 +48,7 @@
不能继续写到仓库本地 `public/generated-puzzle-covers/*`。
这些路径只是前后端 DTO 里的兼容标识，不是浏览器可以直接裸读的公开资源地址。实际图片对象存放在私有 OSS 中，前端渲染前必须先通过 `/api/assets/read-url?legacyPublicPath=...` 换取签名读 URL；签名 URL 未返回或换签失败时，图片组件不能把 `/generated-puzzle-assets/*` 直接写入 `<img src>`，避免浏览器发起无签名、无鉴权请求。
这些路径只是前后端 DTO 里的兼容标识，不是浏览器可以直接裸读的公开资源地址。实际图片对象存放在私有 OSS 中，前端渲染前必须先通过 `/api/assets/read-url?legacyPublicPath=...` 换取签名读 URL；签名 URL 未返回或换签失败时，图片组件不能把 `/generated-puzzle-assets/*` 或无前导斜杠的 `generated-puzzle-assets/*` 直接写入 `<img src>`，避免浏览器发起无签名、无鉴权请求。
### 4.2 运行态边界

102
docs/technical/PUZZLE_TEMPLATE_FORM_AND_GPT_IMAGE_SKILL_2026-05-03.md
View File

@@ -2,44 +2,57 @@
## 背景
拼图创作入口已经从对话式 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. 点击模板时：
- 立即选中该模板。
- 如果输入框为空，直接填入模板提示词。
- 如果输入框已有内容，替换为该模板提示词，避免追加后变得冗长。
4. 输入区保留：
- 参考图上传按钮。
1. 顶部主标题展示“想做个什么玩法？”和轻量状态标识，不写玩法规则说明。
2. 上传拼图图片区优先占据首屏左侧/上方的大块区域，移动端也必须完整露出。
- 上传区自身就是图片卡片，不再额外封装为 `platform-subpanel` 模块壳。
- 亮色主题下上传卡片必须使用白色或暖浅色卡面，不得显示整块黑色底。
- 上传卡片固定为 1:1 正方形，避免拼图主画面在首屏出现非正方形预期。
- 移动端表单主体不可依赖纵向拖动查看核心控件；玩法卡带、描述输入框和底部生成按钮占位固定后，上传卡片必须按剩余高度等比例缩放，仍保持 1:1。
- 上传卡片底部不再叠加文件名 bar；`点击上传拼图图片` 入口必须显示在拼图画面卡片内部。
- 上传卡片上方固定展示 `拼图画面` 标题。
- 无图状态下，上传卡片内部、`点击上传拼图图片` 按钮上方展示 11px 级辅助提示 `若没有合适的图片可以通过填写画面描述生成画面`，提示用户可不上传图片、直接填写画面描述生成画面。
- 上传成功后，`AI重绘` 开关显示在卡片左下角，右上角显示移除拼图图片图标按钮；移除必须先弹出二次确认。
- 叠在上传卡片上的 `AI重绘`、移除图标和上传入口必须和卡面保持足够对比，避免浅色主题重映射后不可读。
3. 画面描述输入框高度固定，移动端保持约 `6rem`，不随剩余屏幕高度变大或变小，避免把上传参考图和提交区挤出首屏。
4. 创作 Tab 顶部玩法卡带的选中态只使用卡内暗色蒙版、细描边或内描边，不使用粉色外发光、外扩阴影或会从卡片边缘突出的高饱和边。
5. 输入区保留：
- 上传拼图图片按钮。
- 图片模型切换按钮。
5. 输入区不保留：
6. 输入区不保留：
- `try` 文本。
- 示例 prompt chip。
- 画面描述输入框默认提示词或占位示例。
- 玩法规则说明。
- Template 模块和模板卡切换。
## 模板抽样
## 历史模板抽样
首批模板不追求覆盖图二所有条目，而是选择高频且适合拼图主图的代表项：
以下模板曾用于表单 Template 模块。2026-05-07 后入口表单不再展示这些模板，列表仅作为历史资产索引：
1. 情侣合照拼图
2. 家庭纪念拼图
@@ -64,8 +77,9 @@ Skill 封装仓库现有后端口径：
POST {APIMART_BASE_URL}/images/generations
Authorization: Bearer {APIMART_API_KEY}
model = gpt-image-2
size = 1:1
n = 1
official_fallback = true
size = 1:1
```
响应兼容：
@@ -76,12 +90,46 @@ 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` 通过。

8
docs/technical/README.md
View File

@@ -5,8 +5,13 @@
## 文档列表
- [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 差异。
- [VOLCENGINE_SPEECH_STREAMING_INTEGRATION_2026-05-08.md](./VOLCENGINE_SPEECH_STREAMING_INTEGRATION_2026-05-08.md)：记录火山引擎大模型 ASR 双向流式、TTS WebSocket 双向流式和 TTS HTTP SSE 单向流式的后端代理、环境变量、协议帧和验收边界。
- [VECTOR_ENGINE_AUDIO_GENERATION_SUNO_VIDU_2026-05-08.md](./VECTOR_ENGINE_AUDIO_GENERATION_SUNO_VIDU_2026-05-08.md)：记录视觉小说结果页接入 VectorEngine Suno 文生背景音乐与 Vidu 文生音效的接口、环境变量、后端路由、OSS 资产回写和前端弹层交互边界。
- [PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md](./PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md)：冻结“我的”页签帮助与反馈入口的后端接入方案，覆盖 `POST /api/profile/feedback`、`profile_feedback_submission`、凭证图片 Data URL 校验和前端预览/提交边界。
- [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_*` 和相关测试/文档口径。
@@ -88,6 +93,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)：记录拼图失败后重新开始/付费续时，以及进入作品与过关后同步存档页投影的落地规则。
@@ -262,7 +268,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 产品形态与能力拆解。

9
docs/technical/RPG_IMAGE_GENERATION_GPT_IMAGE_2_MIGRATION_2026-05-02.md
View File

@@ -36,8 +36,9 @@ model = gpt-image-2
1. `model`
2. `prompt`
3. `n`
4. `size`
5. 有参考图时增加 `image_urls`
4. `official_fallback = true`
5. `size`
6. 有参考图时增加 `image_urls`
尺寸归一规则：
@@ -67,8 +68,8 @@ APIMART_IMAGE_REQUEST_TIMEOUT_MS=180000
## 验收
1. 角色主图生成请求上游 `model` 为 `gpt-image-2`。
2. 场景图生成请求上游 `model` 为 `gpt-image-2`。
1. 角色主图生成请求上游 `model` 为 `gpt-image-2`，且携带 `official_fallback = true`。
2. 场景图生成请求上游 `model` 为 `gpt-image-2`，且携带 `official_fallback = true`。
3. 旧前端或历史草稿传 `wan2.7-image-pro` 时不会回退旧模型。
4. 场景参考图生成仍能把参考图 Data URL 放入 `image_urls`。
5. 角色主图生成后仍执行原有 PNG 透明背景处理与 OSS 写入。

73
docs/technical/SPACETIMEDB_TABLE_CATALOG.md
View File

@@ -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` |
@@ -729,6 +730,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`

2
docs/technical/TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md
View File

@@ -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 模式创作流程与运行机制完整迁入当前项目：

156
docs/technical/VECTOR_ENGINE_AUDIO_GENERATION_SUNO_VIDU_2026-05-08.md Normal file
View File

@@ -0,0 +1,156 @@
# VectorEngine 音频生成接入方案 2026-05-08
## 1. 范围
本方案用于把 VectorEngine / Apifox 文档中的 Suno 文生背景音乐与 Vidu 文生音效接入视觉小说结果页。
本次只接入 `visual-novel` 现有场景资产槽位，不新增独立音频系统、不新增 SpacetimeDB 表、不把供应商密钥下发到前端。
## 2. 参考接口
### 2.1 Suno 文生背景音乐
参考文档：
- `https://vectorengine.apifox.cn/api-349239190`
- `https://vectorengine.apifox.cn/api-349239199`
接口：
```text
POST /suno/submit/music
GET /suno/fetch/{task_id}
```
提交请求头：
```text
Content-Type: application/json
Accept: application/json
Authorization: Bearer {VECTOR_ENGINE_API_KEY}
```
自定义模式请求体：
```json
{
"prompt": "音乐描述或歌词",
"mv": "chirp-v4",
"title": "曲名",
"tags": "风格标签",
"continue_at": 120,
"continue_clip_id": "",
"task": ""
}
```
首版只使用 `prompt`、`mv`、`title`、`tags`。返回体按 `code = success` 且 `data` 为供应商任务 ID 处理。
### 2.2 Vidu 文生音效
参考文档：
- `https://vectorengine.apifox.cn/api-417728889`
- `https://vectorengine.apifox.cn/api-417728893`
接口：
```text
POST /ent/v2/text2audio
GET /ent/v2/tasks/{id}/creations
```
提交请求体：
```json
{
"model": "audio1.0",
"prompt": "雨滴落在窗户上的声音，伴随着轻柔的雷声",
"duration": 5,
"seed": 0
}
```
约束：
- `prompt` 最长 1500 字符。
- `duration` 范围为 2 到 10 秒，默认 5 秒。
- `model` 首版固定为 `audio1.0`。
## 3. 环境变量
```text
VECTOR_ENGINE_BASE_URL=
VECTOR_ENGINE_API_KEY=
VECTOR_ENGINE_AUDIO_REQUEST_TIMEOUT_MS=180000
```
说明：
1. `VECTOR_ENGINE_BASE_URL` 只保存供应商代理 API 基础地址，不在代码中写死私有网关。
2. `VECTOR_ENGINE_API_KEY` 只能进入本地或生产私密环境文件，不提交到 Git。
3. 缺少任一必配项时，后端返回 `503 SERVICE_UNAVAILABLE`，前端沿用现有错误展示。
## 4. 后端路由
视觉小说创作链新增 4 个鉴权路由：
| 方法 | 路由 | 用途 |
| --- | --- | --- |
| `POST` | `/api/creation/visual-novel/audio/background-music` | 提交 Suno 背景音乐任务 |
| `POST` | `/api/creation/visual-novel/audio/background-music/{task_id}/asset` | 查询 Suno 任务，完成后下载并写入平台资产 |
| `POST` | `/api/creation/visual-novel/audio/sound-effect` | 提交 Vidu 音效任务 |
| `POST` | `/api/creation/visual-novel/audio/sound-effect/{task_id}/asset` | 查询 Vidu 任务，完成后下载并写入平台资产 |
生成资产回包写入既有视觉小说字段：
- Suno 背景音乐：`VisualNovelSceneDraft.musicSrc`
- Vidu 文生音效：`VisualNovelSceneDraft.ambientSoundSrc`
## 5. 资产落点
音频文件由后端下载后通过 `OssClient::put_object` 写入平台 OSS，并确认 `asset_object` 与 `asset_entity_binding`。
对象规划：
| 类型 | `assetKind` | `entityKind` | `slot` | 旧路径前缀 |
| --- | --- | --- | --- | --- |
| 背景音乐 | `visual_novel_music` | `visual_novel_scene` | `music` | `generated-custom-world-scenes` |
| 场景音效 | `visual_novel_ambient_sound` | `visual_novel_scene` | `ambient_sound` | `generated-custom-world-scenes` |
确认后的 `audioSrc` 使用 OSS 返回的 legacy public path，继续由前端 `resolveAssetReadUrl` 换签播放。
## 6. 前端交互
视觉小说场景编辑弹层新增两类音频能力：
1. `音乐` 保留上传能力，并新增 Suno 生成按钮。
2. `音效` 使用 `ambientSoundSrc`，支持上传和 Vidu 生成。
交互要求：
1. 生成参数放在独立弹层中，不在当前场景面板下方展开。
2. 弹层只保留必要字段、提交、关闭和状态反馈，不展示供应商规则说明。
3. 任务提交成功后前端轮询资产接口；若供应商仍在处理，保持弹层状态。
4. 资产生成完成后自动写回当前场景字段。
## 7. 验收
建议执行：
```bash
npm run check:encoding
npm run typecheck
cd server-rs
cargo test -p shared-contracts visual_novel
cargo check -p api-server
```
涉及真实 API smoke 时：
1. 只在本地私密环境设置 `VECTOR_ENGINE_API_KEY`。
2. 使用 `npm run api-server` 重启后端。
3. 确认 `/healthz`。
4. 在视觉小说结果页提交背景音乐或音效生成，生成完成后确认场景音频槽位可播放。

76
docs/technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md Normal file
View File

@@ -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 的文档收口已经站稳。

111
docs/technical/VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md Normal file
View File

@@ -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 和解析测试。

225
docs/technical/VOLCENGINE_SPEECH_STREAMING_INTEGRATION_2026-05-08.md Normal file
View File

@@ -0,0 +1,225 @@
# 火山引擎大模型语音流式接入 2026-05-08
## 背景
本次接入火山引擎豆包语音能力，覆盖两类运行态语音链路：
1. 大模型流式语音识别 ASR，使用 WebSocket 双向流式优化模式。
2. 大模型语音合成 TTS，使用实时交互场景的 WebSocket 双向流式接口，并提供一次性文本输入的 HTTP SSE 单向流式接口。
语音能力属于外部副作用，按 server-rs DDD 分层落在 `platform-speech`；`api-server` 只负责平台账号鉴权、环境配置校验、协议代理和错误映射。前端不得直接持有火山引擎密钥。
## 官方文档依据
- ASR：`https://www.volcengine.com/docs/6561/1354869?lang=zh`
- TTS WebSocket 双向流式：`https://www.volcengine.com/docs/6561/1329505?lang=zh`
- TTS WebSocket 单向流式：`https://www.volcengine.com/docs/6561/1719100?lang=zh`
- TTS HTTP Chunked / SSE 单向流式：`https://www.volcengine.com/docs/6561/1598757?lang=zh`
## 环境变量
真实值只能放在本地未提交的 `.env.local` / `.env.secrets.local` 或生产服务器环境文件，禁止提交到仓库。
```text
VOLCENGINE_SPEECH_API_KEY=
VOLCENGINE_SPEECH_APP_ID=
VOLCENGINE_SPEECH_ACCESS_KEY=
VOLCENGINE_SPEECH_ASR_RESOURCE_ID=volc.seedasr.sauc.concurrent
VOLCENGINE_SPEECH_TTS_RESOURCE_ID=seed-tts-2.0
VOLCENGINE_SPEECH_REQUEST_TIMEOUT_MS=180000
VOLCENGINE_SPEECH_ASR_WS_URL=wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async
VOLCENGINE_SPEECH_TTS_BIDIRECTION_WS_URL=wss://openspeech.bytedance.com/api/v3/tts/bidirection
VOLCENGINE_SPEECH_TTS_SSE_URL=https://openspeech.bytedance.com/api/v3/tts/unidirectional/sse
```
配置规则：
1. 优先使用新版控制台 `VOLCENGINE_SPEECH_API_KEY`，上游请求头写 `X-Api-Key`。
2. 若只配置旧版控制台信息，则使用 `VOLCENGINE_SPEECH_APP_ID` 和 `VOLCENGINE_SPEECH_ACCESS_KEY`。
3. ASR 默认资源 ID 选 ASR 2.0 并发版；如账号是小时版，部署时改成 `volc.seedasr.sauc.duration`。
4. TTS 默认资源 ID 选 `seed-tts-2.0`；旧音色或 1.0 计费资源由部署环境覆盖。
## ASR 协议边界
客户端连接：
```text
GET /api/speech/volcengine/asr/stream
Authorization: Bearer <Genarrative JWT>
```
浏览器与 `api-server` 使用 WebSocket 二进制帧透传：
1. 首包必须是 JSON 文本，表示 ASR full client request 的业务参数。
2. 后续二进制帧是音频分片。
3. 浏览器发送文本帧 `{"type":"finish"}` 时，后端把最后一个空音频包按负包发送给火山。
4. 后端把火山 full server response 解析成 JSON 文本帧发回浏览器。
ASR 上游连接：
```text
wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async
X-Api-Key: <VOLCENGINE_SPEECH_API_KEY>
X-Api-Resource-Id: <VOLCENGINE_SPEECH_ASR_RESOURCE_ID>
X-Api-Request-Id: <uuid>
X-Api-Sequence: -1
```
ASR 二进制协议：
1. 4 字节 header，大端整数。
2. full client request：message type `0b0001`，JSON 序列化，gzip 压缩。
3. audio only request：message type `0b0010`，raw payload，gzip 压缩。
4. 最后一包音频使用 flags `0b0010`。
5. full server response：message type `0b1001`，payload 为 gzip JSON。
6. error response：message type `0b1111`，payload 为错误 JSON 或 UTF-8 文本。
首包参数由前端传入，但后端会兜底：
```json
{
"user": { "uid": "current-user-id" },
"audio": {
"format": "pcm",
"codec": "raw",
"rate": 16000,
"bits": 16,
"channel": 1
},
"request": {
"model_name": "bigmodel",
"enable_itn": true,
"enable_punc": true,
"show_utterances": true,
"result_type": "full"
}
}
```
## TTS 协议边界
### WebSocket 双向流式
客户端连接：
```text
GET /api/speech/volcengine/tts/bidirection
Authorization: Bearer <Genarrative JWT>
```
浏览器向后端发送 JSON 文本帧：
```json
{ "type": "start_connection" }
{ "type": "start_session", "sessionId": "...", "payload": { "user": {}, "req_params": {} } }
{ "type": "task_request", "sessionId": "...", "payload": { "req_params": { "text": "..." } } }
{ "type": "finish_session", "sessionId": "..." }
{ "type": "finish_connection" }
```
后端转成火山 WebSocket V3 二进制帧，并把上游返回帧统一解析成 JSON 文本或音频二进制帧回传浏览器。
TTS 双向上游连接：
```text
wss://openspeech.bytedance.com/api/v3/tts/bidirection
X-Api-Key: <VOLCENGINE_SPEECH_API_KEY>
X-Api-Resource-Id: <VOLCENGINE_SPEECH_TTS_RESOURCE_ID>
X-Api-Connect-Id: <uuid>
```
V3 事件帧：
1. Full-client request + event number 用于 `StartConnection`、`StartSession`、`TaskRequest`、`FinishSession`、`FinishConnection`。
2. Full-server response + event number 用于 `ConnectionStarted`、`SessionStarted`、`SessionFinished` 等状态事件。
3. Audio-only response + event number 用于返回音频二进制。
4. 错误帧必须转成结构化 JSON 错误，不把上游密钥或完整请求头写入日志。
### HTTP SSE 单向流式
客户端请求：
```text
POST /api/speech/volcengine/tts/sse
Authorization: Bearer <Genarrative JWT>
Content-Type: application/json
Accept: text/event-stream
```
请求体：
```json
{
"text": "你好，欢迎来到百梦。",
"speaker": "zh_female_cancan_mars_bigtts",
"audioParams": {
"format": "mp3",
"sampleRate": 24000
}
}
```
后端转换为火山 HTTP SSE 请求体：
```json
{
"user": { "uid": "current-user-id" },
"req_params": {
"text": "...",
"speaker": "...",
"audio_params": {
"format": "mp3",
"sample_rate": 24000
}
}
}
```
上游 SSE 的常见事件：
1. `352`：TTSResponse，`data` 为 base64 音频片段。
2. `351`：TTSSentenceEnd，`sentence` 为字幕或时间戳数据。
3. `152`：SessionFinish，合成完成，可含 `usage.text_words`。
4. `153`：SessionFailed，合成失败。
后端保持 SSE 形态透传，但会补齐平台 `requestId` 与上游 `X-Tt-Logid` 作为排障信息。
## api-server 路由
| 方法 | 路由 | 说明 |
|---|---|---|
| `GET` | `/api/speech/volcengine/config` | 返回前端可见的默认资源和推荐音频参数，不返回密钥 |
| `GET` | `/api/speech/volcengine/asr/stream` | ASR WebSocket 双向流式代理 |
| `GET` | `/api/speech/volcengine/tts/bidirection` | TTS WebSocket 双向流式代理 |
| `POST` | `/api/speech/volcengine/tts/sse` | TTS HTTP SSE 单向流式代理 |
所有路由必须走 `require_bearer_auth`。
## 验收
代码级验收：
```bash
cargo fmt --manifest-path server-rs/Cargo.toml --all --check
cargo test --manifest-path server-rs/Cargo.toml -p platform-speech
cargo test --manifest-path server-rs/Cargo.toml -p api-server volcengine_speech
cargo check --manifest-path server-rs/Cargo.toml -p api-server
npm run check:encoding
```
联调验收：
1. 启动 `npm run api-server`。
2. 检查 `/healthz` 返回 200。
3. 未登录访问语音路由返回 401。
4. 已登录后 `/api/speech/volcengine/config` 不返回任何密钥字段。
5. ASR WebSocket 发送首包和 200ms PCM 分片后能收到识别 JSON。
6. TTS SSE 能收到 `352` 音频事件与最终 `152` 完成事件。
7. TTS 双向 WebSocket 能复用连接完成至少一个 session。
## 注意事项
1. 不把 `VOLCENGINE_ACCESS_KEY_ID`、`VOLCENGINE_SECRET_ACCESS_KEY`、API Key、Access Token 或完整 Authorization 写入文档、日志、测试快照或前端状态。
2. 中文语音默认使用 16k 单声道 PCM ASR；TTS 默认使用 24k mp3，运行时可按玩法需要改为 pcm。
3. 火山返回的 `X-Tt-Logid` 是排障关键信息，应记录 logid，但不能记录密钥。
4. 语音流式能力是平台副作用，不涉及 SpacetimeDB 表结构变更，本次无需修改 `migration.rs`。

5
index.html
View File

@@ -2,7 +2,10 @@
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover"
/>
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<title>百梦</title>
</head>

17
jenkins/Jenkinsfile.production-stdb-module-build
View File

@@ -16,7 +16,7 @@ pipeline {
CARGO_INCREMENTAL = '0'
RUSTC_WRAPPER = 'sccache'
SCCACHE_DIR = '${env.USERPROFILE}\\.cache\\sccache-stdb-module'
SCCACHE_CACHE_SIZE = '30G'o
SCCACHE_CACHE_SIZE = '30G'
}
parameters {
@@ -88,8 +88,19 @@ pipeline {
if (-not (Get-Command cargo -ErrorAction SilentlyContinue)) {
throw '[stdb-build] 缺少 cargo。请先在 Windows 构建节点安装 Rust 工具链，并确保 cargo 在 PATH 中。'
}
if (-not (Get-Command sccache -ErrorAction SilentlyContinue)) {
Write-Host '[stdb-build] 未找到 sccache，改用 rustc 直接构建。'
# sccache 只是可选缓存；PATH 中存在但不可执行时必须回退到 rustc。
$sccacheCommand = Get-Command sccache -ErrorAction SilentlyContinue
$sccacheUsable = $false
if ($sccacheCommand) {
try {
& $sccacheCommand.Source --version | Out-Host
$sccacheUsable = $true
} catch {
Write-Host "[stdb-build] sccache 无法执行：$($_.Exception.Message)"
}
}
if (-not $sccacheUsable) {
Write-Host '[stdb-build] 未找到可用 sccache，改用 rustc 直接构建。'
Remove-Item Env:RUSTC_WRAPPER -ErrorAction SilentlyContinue
}
npm run build:production-release -- --component spacetime-module --name "$env:EFFECTIVE_BUILD_VERSION"

2
package.json
View File

@@ -22,6 +22,8 @@
"preview": "node scripts/vite-cli.mjs preview",
"clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
"check:encoding": "node scripts/check-encoding.mjs",
"check:visual-novel-vn11": "node scripts/check-visual-novel-vn11-negative-scan.mjs",
"check:visual-novel-vn12": "node scripts/check-visual-novel-vn12-acceptance.mjs",
"check:server-rs-ddd": "node scripts/check-server-rs-ddd-boundaries.mjs",
"lint:eslint": "eslint . --ext .ts,.tsx,.js,.mjs,.cjs --max-warnings 0",
"lint:guardrails": "npm run lint:eslint",

1
packages/shared/src/contracts/creationAgentDocumentInput.ts
View File

@@ -9,6 +9,7 @@ export interface CreationAgentDocumentInputPayload {
contentType?: string | null;
sizeBytes: number;
text: string;
sourceAssetId?: string | null;
}
export interface ParseCreationAgentDocumentInputResponse {

244
packages/shared/src/contracts/creativeAgent.ts Normal file
View File

@@ -0,0 +1,244 @@
import type { PuzzleResultDraft } from './puzzleAgentDraft';
import type { PuzzleAgentSessionSnapshot } from './puzzleAgentSession';
import type {
PuzzleCreativeTemplateProtocol,
PuzzleCreativeTemplateSelection,
PuzzleDraftFieldPatch,
PuzzleImageGenerationPlan,
PuzzleTemplateCostRange,
} from './puzzleCreativeTemplate';
export type CreativeAgentStage =
| 'idle'
| 'perceiving'
| 'thinking'
| 'remembering'
| 'selecting_puzzle_template'
| 'waiting_template_confirmation'
| 'planning_puzzle_levels'
| 'acting'
| 'reflecting'
| 'collaborating'
| 'target_ready'
| 'waiting_user'
| 'failed';
export type CreativeAgentEntryContext =
| 'creation_home'
| 'puzzle_workspace'
| 'gallery_remix'
| 'draft_restore';
export type CreativeAgentMessageRole = 'user' | 'assistant' | 'system';
export type CreativeAgentMessageKind =
| 'chat'
| 'stage'
| 'action_result'
| 'warning';
export type CreativeAgentInputPart =
| {
type: 'input_text';
text: string;
}
| {
type: 'input_image';
imageUrl: string;
assetId?: string | null;
thumbnailUrl?: string | null;
};
export interface CreativeImageInput {
assetId: string;
readUrl: string;
thumbnailUrl?: string | null;
width?: number | null;
height?: number | null;
}
export interface CreativeImageSummary {
assetId: string | null;
readUrl: string | null;
thumbnailUrl: string | null;
width: number | null;
height: number | null;
summary: string | null;
}
export type CreativeUnsupportedPlayType =
| 'rpg'
| 'match3d'
| 'big_fish'
| 'square_hole';
export interface CreativeUnsupportedCapability {
playType: CreativeUnsupportedPlayType;
title: string;
status: 'unsupported';
reason: string;
}
export interface CreativeInputSummary {
text: string | null;
entryContext: CreativeAgentEntryContext;
images: CreativeImageSummary[];
materialSummary: string | null;
unsupportedCapabilities: CreativeUnsupportedCapability[];
}
export interface CreativeAgentMessage {
id: string;
role: CreativeAgentMessageRole;
kind: CreativeAgentMessageKind;
text: string;
createdAt: string;
}
export interface CreativeTargetSessionBinding {
playType: 'puzzle';
targetSessionId: string;
targetStage: 'puzzle-agent-workspace' | 'puzzle-result' | 'puzzle-runtime';
resultProfileId: string | null;
}
export interface CreativeAgentSessionSnapshot {
sessionId: string;
stage: CreativeAgentStage;
inputSummary: CreativeInputSummary;
messages: CreativeAgentMessage[];
puzzleTemplateCatalog: PuzzleCreativeTemplateProtocol[];
puzzleTemplateSelection: PuzzleCreativeTemplateSelection | null;
puzzleImageGenerationPlan: PuzzleImageGenerationPlan | null;
targetBinding: CreativeTargetSessionBinding | null;
updatedAt: string;
}
export interface CreateCreativeAgentSessionRequest {
text?: string | null;
images?: CreativeImageInput[];
entryContext?: CreativeAgentEntryContext;
}
export interface CreativeAgentSessionResponse {
session: CreativeAgentSessionSnapshot;
}
export interface StreamCreativeAgentMessageRequest {
clientMessageId: string;
content: CreativeAgentInputPart[];
}
export interface ConfirmCreativePuzzleTemplateRequest {
selection: PuzzleCreativeTemplateSelection;
}
export interface CreativeDraftEditStreamRequest {
clientMessageId: string;
instruction: string;
targetPuzzleSessionId: string;
currentDraft: PuzzleResultDraft;
}
export interface CreativeDraftEditResult {
editInstructions: PuzzleDraftFieldPatch[];
session: CreativeAgentSessionSnapshot;
puzzleSession: PuzzleAgentSessionSnapshot;
}
export interface CreativeAgentStageEvent {
sessionId: string;
stage: CreativeAgentStage;
}
export interface CreativeAgentMessageDeltaEvent {
sessionId: string;
messageId: string;
role: CreativeAgentMessageRole;
kind: CreativeAgentMessageKind;
textDelta: string;
}
export interface CreativeAgentThoughtSummaryDeltaEvent {
sessionId: string;
thoughtId: string;
textDelta: string;
}
export interface CreativeAgentTemplateCatalogEvent {
sessionId: string;
templates: PuzzleCreativeTemplateProtocol[];
}
export interface CreativeAgentTemplateSelectionEvent {
sessionId: string;
selection: PuzzleCreativeTemplateSelection;
}
export interface CreativeAgentCostRangeEvent {
sessionId: string;
costRange: PuzzleTemplateCostRange;
}
export interface CreativeAgentLevelPlanEvent {
sessionId: string;
plan: PuzzleImageGenerationPlan;
}
export interface CreativeAgentToolEvent {
sessionId: string;
toolCallId: string;
toolName: string;
summary: string | null;
}
export interface CreativeAgentReflectionEvent {
sessionId: string;
pass: boolean;
summary: string;
warnings: string[];
}
export interface CreativeAgentTargetSessionEvent {
sessionId: string;
binding: CreativeTargetSessionBinding;
}
export interface CreativeAgentErrorEvent {
sessionId: string | null;
code: string;
message: string;
recoverable: boolean;
}
export interface CreativeAgentDoneEvent {
sessionId: string;
}
export type CreativeAgentSseEvent =
| { event: 'stage'; data: CreativeAgentStageEvent }
| { event: 'agent_message_delta'; data: CreativeAgentMessageDeltaEvent }
| {
event: 'thought_summary_delta';
data: CreativeAgentThoughtSummaryDeltaEvent;
}
| {
event: 'puzzle_template_catalog';
data: CreativeAgentTemplateCatalogEvent;
}
| {
event: 'puzzle_template_selection';
data: CreativeAgentTemplateSelectionEvent;
}
| { event: 'puzzle_cost_range'; data: CreativeAgentCostRangeEvent }
| { event: 'puzzle_level_plan'; data: CreativeAgentLevelPlanEvent }
| { event: 'tool_started'; data: CreativeAgentToolEvent }
| { event: 'tool_completed'; data: CreativeAgentToolEvent }
| { event: 'reflection'; data: CreativeAgentReflectionEvent }
| { event: 'target_session'; data: CreativeAgentTargetSessionEvent }
| {
event: 'session';
data: { session: CreativeAgentSessionSnapshot };
}
| { event: 'error'; data: CreativeAgentErrorEvent }
| { event: 'done'; data: CreativeAgentDoneEvent };

3
packages/shared/src/contracts/index.ts Normal file
View File

@@ -0,0 +1,3 @@
export type * from './creativeAgent';
export type * from './puzzleCreativeTemplate';
export type * from './visualNovel';

3
packages/shared/src/contracts/puzzleAgentActions.ts
View File

@@ -48,7 +48,9 @@ export type PuzzleAgentActionRequest =
workTitle?: string;
workDescription?: string;
pictureDescription?: string;
referenceImageSrc?: string | null;
imageModel?: string | null;
aiRedraw?: boolean;
}
| {
action: 'compile_puzzle_draft';
@@ -58,6 +60,7 @@ export type PuzzleAgentActionRequest =
pictureDescription?: string;
referenceImageSrc?: string | null;
imageModel?: string | null;
aiRedraw?: boolean;
candidateCount?: number;
}
| {

1
packages/shared/src/contracts/puzzleAgentDraft.ts
View File

@@ -46,6 +46,7 @@ export interface PuzzleDraftLevel {
levelId: string;
levelName: string;
pictureDescription: string;
pictureReference?: string | null;
candidates: PuzzleGeneratedImageCandidate[];
selectedCandidateId: string | null;
coverImageSrc: string | null;

1
packages/shared/src/contracts/puzzleAgentSession.ts
View File

@@ -51,6 +51,7 @@ export interface CreatePuzzleAgentSessionRequest {
pictureDescription?: string;
referenceImageSrc?: string | null;
imageModel?: string | null;
aiRedraw?: boolean;
}
export interface CreatePuzzleAgentSessionResponse {

103
packages/shared/src/contracts/puzzleCreativeTemplate.ts Normal file
View File

@@ -0,0 +1,103 @@
export type PuzzleTemplatePricingUnit = 'point';
export type PuzzleSupportedLevelMode =
| 'single'
| 'multi'
| 'single_or_multi';
export type PuzzleLevelGenerationMode = 'single_level' | 'multi_level';
export interface PuzzleTemplateCostRange {
minPoints: number;
maxPoints: number;
pricingUnit: PuzzleTemplatePricingUnit;
reason: string;
}
export type PuzzleDraftEditableFieldPath =
| 'workTitle'
| 'workDescription'
| 'workTags'
| 'levels[].levelName'
| 'levels[].pictureDescription'
| 'levels[].pictureReference';
export interface PuzzleTemplateImageGenerationPolicy {
allowUploadedImageDirectly: boolean;
allowGeneratedImages: boolean;
allowPerLevelReferenceImage: boolean;
defaultCandidateCountPerLevel: number;
}
export interface PuzzleCreativeTemplateProtocol {
templateId: string;
title: string;
summary: string;
previewImageSrc: string | null;
supportedLevelMode: PuzzleSupportedLevelMode;
minLevelCount: number;
maxLevelCount: number;
defaultLevelCount: number;
costRange: PuzzleTemplateCostRange;
requiredDraftFields: PuzzleDraftEditableFieldPath[];
imagePolicy: PuzzleTemplateImageGenerationPolicy;
}
export interface PuzzleCreativeTemplateSelection {
templateId: string;
title: string;
reason: string;
costRange: PuzzleTemplateCostRange;
supportedLevelMode: PuzzleSupportedLevelMode;
selectedLevelMode: PuzzleLevelGenerationMode;
plannedLevelCount: number;
requiresUserConfirmation: true;
}
export interface CreativePuzzleLevelDraftInput {
levelName: string;
pictureDescription: string;
/**
* 任务 A 冻结：Phase 1 采用正式字段方案，后续拼图草稿落地需补正式 pictureReference 字段。
*/
pictureReference?: string | null;
}
export interface CreativePuzzleDraftToolInput {
templateId: string;
templateCostRange: PuzzleTemplateCostRange;
workTitle: string;
workDescription: string;
workTags: string[];
levels: CreativePuzzleLevelDraftInput[];
}
export interface PuzzleImageGenerationPlanLevel {
levelId: string;
levelName: string;
pictureDescription: string;
imagePrompt: string;
pictureReference?: string | null;
candidateCount: number;
}
export interface PuzzleImageGenerationPlan {
mode: PuzzleLevelGenerationMode;
templateId: string;
estimatedCostRange: PuzzleTemplateCostRange;
levels: PuzzleImageGenerationPlanLevel[];
}
export type PuzzleDraftFieldPatchOperation =
| 'set'
| 'append'
| 'replace'
| 'remove';
export interface PuzzleDraftFieldPatch {
fieldPath: PuzzleDraftEditableFieldPath;
operation: PuzzleDraftFieldPatchOperation;
levelId?: string | null;
value: unknown;
rationale: string;
}

452
packages/shared/src/contracts/visualNovel.ts Normal file
View File

@@ -0,0 +1,452 @@
export type VisualNovelSourceMode = 'idea' | 'document' | 'blank';
export type VisualNovelCharacterRole =
| 'protagonist'
| 'main'
| 'supporting'
| 'antagonist'
| 'background';
export type VisualNovelAssetSource =
| 'platform_asset'
| 'generated'
| 'external';
export type VisualNovelAudioGenerationKind =
| 'background_music'
| 'sound_effect';
export type VisualNovelSceneAvailability =
| 'opening'
| 'always'
| 'phase_locked';
export type VisualNovelAttributePanelMode =
| 'off'
| 'platform_whitelist'
| 'template_config';
export type VisualNovelValidationSeverity = 'error' | 'warning';
export type VisualNovelAgentStatus =
| 'collecting'
| 'drafting'
| 'ready'
| 'failed';
export type VisualNovelAgentMessageRole = 'user' | 'assistant' | 'system';
export type VisualNovelAgentMessageKind =
| 'chat'
| 'summary'
| 'action_result'
| 'warning';
export type VisualNovelAgentActionKind =
| 'generate_draft'
| 'patch_world'
| 'patch_character'
| 'patch_scene'
| 'patch_story_phase'
| 'generate_scene_image'
| 'generate_character_image'
| 'compile_work_profile';
export type VisualNovelAgentPhase =
| 'perception'
| 'reasoning'
| 'drafting'
| 'reflection'
| 'finalizing';
export type VisualNovelRunMode = 'test' | 'play';
export type VisualNovelRunStatus = 'active' | 'completed' | 'failed';
export type VisualNovelRuntimeActionKind = 'choice' | 'free_text' | 'continue';
export type VisualNovelTransitionKind = 'fade' | 'cut' | 'flash' | 'none';
export type VisualNovelHistorySource = 'player' | 'assistant' | 'system';
export type VisualNovelFlagValue = string | number | boolean;
export interface VisualNovelDraftPatch {
path: string;
op: 'add' | 'replace' | 'remove';
value?: unknown;
}
export interface VisualNovelValidationIssue {
issueId: string;
code: string;
severity: VisualNovelValidationSeverity;
path: string;
message: string;
}
export interface VisualNovelChoiceDraft {
choiceId: string;
text: string;
actionHint?: string | null;
}
export interface VisualNovelCharacterImageAsset {
assetId: string;
imageSrc: string;
expression?: string | null;
source: VisualNovelAssetSource;
}
export interface VisualNovelWorldDraft {
title: string;
summary: string;
background: string;
premise: string;
literaryStyle: string;
playerRole: string;
defaultTone: string;
}
export interface VisualNovelCharacterDraft {
characterId: string;
name: string;
gender: string | null;
role: VisualNovelCharacterRole;
appearance: string;
personality: string;
tone: string;
background: string;
relationshipToPlayer: string;
imageAssets: VisualNovelCharacterImageAsset[];
defaultExpression: string | null;
isPlayerVisible: boolean;
}
export interface VisualNovelSceneDraft {
sceneId: string;
name: string;
description: string;
backgroundImageSrc: string | null;
musicSrc: string | null;
ambientSoundSrc: string | null;
availability: VisualNovelSceneAvailability;
phaseIds: string[];
}
export interface VisualNovelStoryPhaseDraft {
phaseId: string;
title: string;
goal: string;
summary: string;
entryCondition: string;
exitCondition: string;
sceneIds: string[];
characterIds: string[];
suggestedChoices: string[];
}
export interface VisualNovelOpeningDraft {
sceneId: string | null;
narration: string;
speakerCharacterId: string | null;
firstDialogue: string | null;
initialChoices: VisualNovelChoiceDraft[];
}
export interface VisualNovelRuntimeConfigDraft {
textModeEnabled: boolean;
defaultTextMode: boolean;
maxHistoryEntries: number;
maxAssistantStepCountPerTurn: number;
allowFreeTextAction: boolean;
allowHistoryRegeneration: boolean;
attributePanelMode: VisualNovelAttributePanelMode;
saveArchiveEnabled: boolean;
}
export interface VisualNovelResultDraft {
profileId: string | null;
workTitle: string;
workDescription: string;
workTags: string[];
coverImageSrc: string | null;
sourceMode: VisualNovelSourceMode;
sourceAssetIds: string[];
world: VisualNovelWorldDraft;
characters: VisualNovelCharacterDraft[];
scenes: VisualNovelSceneDraft[];
storyPhases: VisualNovelStoryPhaseDraft[];
opening: VisualNovelOpeningDraft;
runtimeConfig: VisualNovelRuntimeConfigDraft;
publishReady: boolean;
validationIssues: VisualNovelValidationIssue[];
updatedAt: string;
}
export interface VisualNovelAgentMessage {
id: string;
role: VisualNovelAgentMessageRole;
kind: VisualNovelAgentMessageKind;
text: string;
createdAt: string;
}
export interface VisualNovelAgentPendingAction {
actionId: string;
kind: VisualNovelAgentActionKind;
label: string;
targetId?: string | null;
payload?: unknown;
}
export interface VisualNovelAgentSessionSnapshot {
sessionId: string;
ownerUserId: string;
sourceMode: VisualNovelSourceMode;
status: VisualNovelAgentStatus;
messages: VisualNovelAgentMessage[];
draft: VisualNovelResultDraft | null;
pendingAction: VisualNovelAgentPendingAction | null;
createdAt: string;
updatedAt: string;
}
export interface CreateVisualNovelSessionRequest {
sourceMode: VisualNovelSourceMode;
seedText?: string | null;
sourceAssetIds?: string[];
}
export interface VisualNovelSessionResponse {
session: VisualNovelAgentSessionSnapshot;
}
export interface VisualNovelWorkSummary {
runtimeKind: 'visual-novel';
profileId: string;
ownerUserId: string;
title: string;
description: string;
coverImageSrc: string | null;
tags: string[];
publishStatus: string;
publishReady: boolean;
playCount: number;
updatedAt: string;
publishedAt: string | null;
}
export interface VisualNovelWorkDetail {
workId: string;
summary: VisualNovelWorkSummary;
sourceSessionId: string | null;
authorDisplayName: string;
sourceAssetIds: string[];
draft: VisualNovelResultDraft;
createdAt: string;
}
export interface VisualNovelWorksResponse {
works: VisualNovelWorkSummary[];
}
export interface VisualNovelWorkResponse {
work: VisualNovelWorkDetail;
}
export interface UpdateVisualNovelWorkRequest {
draft: VisualNovelResultDraft;
}
export interface VisualNovelCompileResponse {
session: VisualNovelAgentSessionSnapshot;
work: VisualNovelWorkDetail;
}
export interface CreateVisualNovelBackgroundMusicRequest {
prompt: string;
title: string;
tags?: string | null;
model?: string | null;
}
export interface CreateVisualNovelSoundEffectRequest {
prompt: string;
duration?: number | null;
seed?: number | null;
}
export interface VisualNovelAudioGenerationTaskResponse {
kind: VisualNovelAudioGenerationKind;
taskId: string;
provider: string;
status: string;
}
export interface PublishVisualNovelGeneratedAudioAssetRequest {
sceneId: string;
profileId?: string | null;
}
export interface VisualNovelGeneratedAudioAssetResponse {
kind: VisualNovelAudioGenerationKind;
taskId: string;
provider: string;
status: string;
assetObjectId?: string | null;
assetKind?: string | null;
audioSrc?: string | null;
}
export interface SendVisualNovelMessageRequest {
clientMessageId: string;
text: string;
}
export interface ExecuteVisualNovelAgentActionRequest {
actionId?: string | null;
kind: VisualNovelAgentActionKind;
targetId?: string | null;
payload?: unknown;
}
export interface CompileVisualNovelWorkProfileRequest {
draft: VisualNovelResultDraft;
}
export type VisualNovelAgentStreamEvent =
| { type: 'start'; sessionId: string }
| { type: 'phase'; phase: VisualNovelAgentPhase }
| { type: 'text_delta'; text: string }
| { type: 'draft_patch'; patch: VisualNovelDraftPatch }
| { type: 'action_required'; action: VisualNovelAgentPendingAction }
| { type: 'complete'; session: VisualNovelAgentSessionSnapshot }
| { type: 'error'; message: string; retryable: boolean }
| { type: 'done' };
export interface VisualNovelSceneChangeStep {
type: 'scene_change';
sceneId: string;
backgroundImageSrc: string | null;
musicSrc: string | null;
}
export interface VisualNovelNarrationStep {
type: 'narration';
text: string;
}
export interface VisualNovelDialogueStep {
type: 'dialogue';
characterId: string;
characterName: string;
expression: string | null;
text: string;
}
export interface VisualNovelTransitionStep {
type: 'transition';
transitionKind: VisualNovelTransitionKind;
text: string | null;
}
export interface VisualNovelChoiceStep {
type: 'choice';
choices: VisualNovelChoiceDraft[];
}
export interface VisualNovelFlagStep {
type: 'flag';
key: string;
value: VisualNovelFlagValue;
}
export interface VisualNovelMetricStep {
type: 'metric';
key: string;
delta: number;
}
export type VisualNovelRuntimeStep =
| VisualNovelSceneChangeStep
| VisualNovelNarrationStep
| VisualNovelDialogueStep
| VisualNovelTransitionStep
| VisualNovelChoiceStep
| VisualNovelFlagStep
| VisualNovelMetricStep;
export interface VisualNovelHistoryEntry {
entryId: string;
runId: string;
turnIndex: number;
source: VisualNovelHistorySource;
actionText: string | null;
steps: VisualNovelRuntimeStep[];
snapshotBeforeHash: string | null;
snapshotAfterHash: string | null;
createdAt: string;
}
export interface VisualNovelRunSnapshot {
runId: string;
ownerUserId: string;
profileId: string;
mode: VisualNovelRunMode;
status: VisualNovelRunStatus;
currentSceneId: string | null;
currentPhaseId: string | null;
visibleCharacterIds: string[];
flags: Record<string, VisualNovelFlagValue>;
metrics: Record<string, number>;
history: VisualNovelHistoryEntry[];
availableChoices: VisualNovelChoiceDraft[];
textModeEnabled: boolean;
createdAt: string;
updatedAt: string;
}
export interface VisualNovelRuntimeActionRequest {
actionKind: VisualNovelRuntimeActionKind;
choiceId?: string;
text?: string;
clientEventId: string;
}
export interface VisualNovelStartRunRequest {
profileId: string;
mode: VisualNovelRunMode;
}
export interface VisualNovelRunResponse {
run: VisualNovelRunSnapshot;
}
export interface VisualNovelHistoryResponse {
history: VisualNovelHistoryEntry[];
}
export interface VisualNovelRegenerateRequest {
historyEntryId: string;
clientEventId: string;
}
export interface VisualNovelSaveArchiveState {
runtimeKind: 'visual-novel';
profileId: string;
runId: string;
currentSceneId: string | null;
currentPhaseId: string | null;
historyCursor: number;
snapshotHash: string | null;
}
export type VisualNovelRuntimeStreamEvent =
| { type: 'start'; runId: string }
| { type: 'raw_text'; text: string }
| { type: 'step'; step: VisualNovelRuntimeStep }
| { type: 'snapshot'; run: VisualNovelRunSnapshot }
| { type: 'complete'; run: VisualNovelRunSnapshot }
| { type: 'error'; message: string; retryable: boolean }
| { type: 'done' };

3
packages/shared/src/index.ts
View File

@@ -3,6 +3,7 @@ export * from './contracts/auth';
export type * from './contracts/bigFish';
export * from './contracts/common';
export type * from './contracts/creationAgentDocumentInput';
export type * from './contracts/creativeAgent';
export type * from './contracts/customWorldAgent';
export * from './contracts/match3dAgent';
export * from './contracts/match3dRuntime';
@@ -11,6 +12,7 @@ export * from './contracts/puzzleAgentActions';
export * from './contracts/puzzleAgentDraft';
export * from './contracts/puzzleAgentSession';
export * from './contracts/puzzleOnboarding';
export type * from './contracts/puzzleCreativeTemplate';
export * from './contracts/puzzleResultPreview';
export * from './contracts/puzzleRuntimeSession';
export * from './contracts/puzzleWorkSummary';
@@ -42,6 +44,7 @@ export type {
SquareHoleWorkSummary,
} from './contracts/squareHoleWorks';
export type * from './contracts/story';
export type * from './contracts/visualNovel';
export * from './http';
export * from './llm/narrativeLanguage';
export * from './llm/parsers';

BIN
public/creation-type-references/airp.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 93 KiB

BIN
public/creation-type-references/big-fish.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

BIN
public/creation-type-references/creative-agent.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 70 KiB

BIN
public/creation-type-references/match3d.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

BIN
public/creation-type-references/puzzle.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 127 KiB

BIN
public/creation-type-references/rpg.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 94 KiB

BIN
public/creation-type-references/square-hole.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
public/creation-type-references/visual-novel.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB

BIN
public/ui-previews/puzzle-image-compact-ui-2026-05-08.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 MiB

5
scripts/api-server-dev.mjs
View File

@@ -7,6 +7,7 @@ const apiServerExePath = resolve(
repoRoot,
'server-rs/target/debug/api-server.exe',
);
const shellEnvKeys = new Set(Object.keys(process.env));
function loadEnvFile(path, target) {
if (!existsSync(path)) {
@@ -26,7 +27,9 @@ function loadEnvFile(path, target) {
}
const [, key, rawValue] = match;
if (target[key] !== undefined) {
// 只保留启动命令行和外层 shell 已显式传入的环境变量优先级；
// `.env.local` 需要能覆盖 `.env`，否则本地短信登录会被默认 false 压住。
if (shellEnvKeys.has(key)) {
continue;
}

272
scripts/check-visual-novel-vn11-negative-scan.mjs Normal file
View File

@@ -0,0 +1,272 @@
import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
import { basename, extname, join, relative } from 'node:path';
const repoRoot = process.cwd();
const writeReport = process.argv.includes('--write-report');
const reportPath = join(repoRoot, 'docs', 'audits', 'VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md');
const codeTargets = [
'src',
'packages/shared/src',
'server-rs/crates',
];
const documentTargets = [
'docs',
'.hermes/shared-memory',
];
const visualNovelImplementationTargets = [
'src/components/visual-novel-creation',
'src/components/visual-novel-result',
'src/components/visual-novel-runtime',
'src/services/visual-novel-creation',
'src/services/visual-novel-runtime',
'src/services/visual-novel-works',
'packages/shared/src/contracts/visualNovel.ts',
'server-rs/crates/shared-contracts/src/visual_novel.rs',
'server-rs/crates/module-visual-novel',
'server-rs/crates/api-server/src/visual_novel.rs',
'server-rs/crates/api-server/src/prompt/visual_novel.rs',
'server-rs/crates/spacetime-module/src/visual_novel.rs',
'server-rs/crates/spacetime-client/src/visual_novel.rs',
];
const textExtensions = new Set([
'.cjs',
'.controller',
'.css',
'.html',
'.js',
'.json',
'.jsx',
'.md',
'.mjs',
'.ps1',
'.py',
'.rs',
'.scss',
'.sh',
'.toml',
'.ts',
'.tsx',
'.txt',
'.yaml',
'.yml',
]);
const textFileNames = new Set([
'AGENTS.md',
'README.md',
]);
const excludedPrefixes = [
'.git/',
'dist/',
'node_modules/',
'server-rs/target/',
'server-rs/target-',
];
const legacyPlaybackTerms = [
're' + 'play',
'Re' + 'play',
'回放',
'分享回放',
'录制',
'复盘',
];
const externalPlatformPatterns = [
/订单/u,
/会员/u,
/促销/u,
/后台/u,
/公开市场/u,
/私有存档/u,
/独立存档/u,
/商城/u,
/支付/u,
/订阅/u,
/活动配置/u,
/小游戏平台/u,
/公开游戏市场/u,
/server-node/u,
/Cloudflare Worker/u,
/\bExpress\b/u,
/\bD1\b/u,
/\bR2\b/u,
];
function normalizePath(filePath) {
return filePath.replace(/\\/gu, '/');
}
function repoRelative(filePath) {
return normalizePath(relative(repoRoot, filePath));
}
function shouldInspect(filePath) {
const normalized = repoRelative(filePath);
if (excludedPrefixes.some((prefix) => normalized.startsWith(prefix))) {
return false;
}
const fileName = basename(filePath);
if (textFileNames.has(fileName)) {
return true;
}
return textExtensions.has(extname(fileName).toLowerCase());
}
function listTextFiles(targetPath) {
const fullPath = join(repoRoot, targetPath);
if (!existsSync(fullPath)) {
return [];
}
const stat = statSync(fullPath);
if (stat.isFile()) {
return shouldInspect(fullPath) ? [fullPath] : [];
}
const files = [];
const walk = (dir) => {
for (const name of readdirSync(dir)) {
const child = join(dir, name);
const childStat = statSync(child);
if (childStat.isDirectory()) {
walk(child);
continue;
}
if (shouldInspect(child)) {
files.push(child);
}
}
};
walk(fullPath);
return files;
}
function collectFiles(targets) {
return [...new Set(targets.flatMap(listTextFiles))].sort();
}
function collectLineHits(files, matcher) {
const hits = [];
for (const file of files) {
const lines = readFileSync(file, 'utf8').split(/\r?\n/u);
lines.forEach((line, index) => {
if (matcher(line)) {
hits.push({
file: repoRelative(file),
lineNumber: index + 1,
text: line.trim(),
});
}
});
}
return hits;
}
function hasLegacyPlaybackMarker(line) {
return legacyPlaybackTerms.some((term) => line.includes(term));
}
function hasExternalPlatformMarker(line) {
return externalPlatformPatterns.some((pattern) => pattern.test(line));
}
function formatHits(hits) {
return hits.map((hit) => ` - ${hit.file}:${hit.lineNumber} ${hit.text}`);
}
const codeFiles = collectFiles(codeTargets);
const documentFiles = collectFiles(documentTargets);
const visualNovelFiles = collectFiles(visualNovelImplementationTargets);
const codePlaybackHits = collectLineHits(codeFiles, hasLegacyPlaybackMarker);
const documentPlaybackHits = collectLineHits(documentFiles, hasLegacyPlaybackMarker);
const externalPlatformHits = collectLineHits(
visualNovelFiles,
hasExternalPlatformMarker,
);
const reportLines = [
'# VN-11 负向扫描报告',
'',
'生成日期：2026-05-07',
'',
'## 扫描范围',
'',
'- 工程代码：`src/`、`packages/shared/src/`、`server-rs/crates/`',
'- 文档与共享记忆：`docs/`、`.hermes/shared-memory/`',
'- 外部平台误入复核：视觉小说前端、service、shared contracts、Rust contracts、module、api-server、SpacetimeDB schema 与 facade 路径',
'',
'## 扫描结论',
'',
`- 工程代码回放类直出命中：${codePlaybackHits.length}`,
`- 文档 / 共享记忆回放类命中：${documentPlaybackHits.length}`,
`- 视觉小说实现路径外部平台能力疑似误入命中：${externalPlatformHits.length}`,
'',
'## 处理记录',
'',
'- 已将 `storyEngine` 回归工具的命名从 replay 语义收口为 rerun / 复测语义。',
'- 已将技能效果预览按钮的内部状态与文案从重播语义收口为重新预览语义。',
'- 已确认视觉小说工程路径未新增回放路由、DTO、表、按钮、文案、外部平台账号 / 订单 / 会员 / 促销 / 后台 / 公开市场或私有存档能力。',
'',
'## 文档命中说明',
'',
'- 文档命中来自历史旧文档、设计复盘、禁止语境、负向验收或本报告记录。VN-11 工程门禁只阻断代码路径新增能力。',
'',
'## 门禁命令',
'',
'```bash',
'npm run check:visual-novel-vn11',
'```',
'',
];
if (writeReport) {
writeFileSync(reportPath, `${reportLines.join('\n')}\n`, 'utf8');
}
const failures = [];
if (codePlaybackHits.length > 0) {
failures.push('工程代码仍存在回放类直出命中。');
}
if (externalPlatformHits.length > 0) {
failures.push('视觉小说实现路径仍存在疑似外部平台能力误入。');
}
if (failures.length > 0) {
console.error('VN-11 negative scan failed:');
for (const failure of failures) {
console.error(`- ${failure}`);
}
console.error('');
for (const hit of [...codePlaybackHits, ...externalPlatformHits]) {
console.error(`- ${hit.file}:${hit.lineNumber} ${hit.text}`);
}
process.exit(1);
}
console.log('VN-11 negative scan passed.');
console.log(`- code playback hits: ${codePlaybackHits.length}`);
console.log(`- document playback hits: ${documentPlaybackHits.length}`);
console.log(`- external platform hits in visual novel implementation: ${externalPlatformHits.length}`);
if (writeReport) {
console.log(`- report: ${repoRelative(reportPath)}`);
}

266
scripts/check-visual-novel-vn12-acceptance.mjs Normal file
View File

@@ -0,0 +1,266 @@
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, join, relative } from 'node:path';
const repoRoot = process.cwd();
const writeReport = process.argv.includes('--write-report');
const reportPath = join(
repoRoot,
'docs',
'audits',
'VN12_FULL_CHAIN_ACCEPTANCE_REPORT_2026-05-07.md',
);
const requiredFiles = [
'docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md',
'docs/audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md',
'src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx',
'src/components/visual-novel-result/VisualNovelResultView.test.tsx',
'src/components/visual-novel-runtime/VisualNovelRuntimeShell.test.tsx',
'src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts',
'src/services/visual-novel-runtime/visualNovelRuntimeSse.test.ts',
'server-rs/crates/api-server/src/visual_novel.rs',
'server-rs/crates/module-visual-novel/src/application.rs',
'server-rs/crates/shared-contracts/src/visual_novel.rs',
];
const contentChecks = [
{
path: 'package.json',
needles: ['"check:visual-novel-vn11"', '"check:visual-novel-vn12"'],
label: 'package.json scripts',
},
{
path: 'server-rs/crates/api-server/src/app.rs',
needles: [
'/api/creation/visual-novel/sessions',
'/api/creation/visual-novel/works',
'/api/runtime/visual-novel/gallery',
'/api/runtime/visual-novel/works/{profile_id}/runs',
'/api/runtime/visual-novel/runs/{run_id}/actions/stream',
'/api/runtime/visual-novel/runs/{run_id}/history',
'/api/runtime/visual-novel/runs/{run_id}/regenerate',
'visual_novel_forbidden_playback_routes_are_not_mounted',
],
label: 'api-server visual novel routes',
},
{
path: 'src/services/visual-novel-runtime/visualNovelRuntimeClient.ts',
needles: [
'VISUAL_NOVEL_RUNTIME_API_BASE',
'${VISUAL_NOVEL_RUNTIME_API_BASE}/gallery',
'skipAuth: true',
'skipRefresh: true',
'${VISUAL_NOVEL_RUNTIME_API_BASE}/runs/${encodeURIComponent(runId)}/actions/stream',
'/api/profile/save-archives',
'/api/runtime/save/snapshot',
],
label: 'visual novel runtime client routes',
},
{
path: 'src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts',
needles: [
'listVisualNovelGallery reads public gallery without auth refresh coupling',
'startVisualNovelRun uses the visual novel runtime work route',
'streamVisualNovelRuntimeAction posts to the SSE action stream route',
'regenerateVisualNovelRun uses the history regenerate route',
'listVisualNovelSaveArchives and resumeVisualNovelSaveArchive use platform archive routes',
'putVisualNovelRuntimeSnapshot only submits platform checkpoint metadata',
'buildVisualNovelRuntimeCheckpoint maps run id into session id',
'buildVisualNovelSaveArchiveState only uses runtime identifiers and hashes',
],
label: 'visual novel runtime client tests',
},
{
path: 'src/services/visual-novel-runtime/visualNovelRuntimeSse.test.ts',
needles: [
'readVisualNovelRuntimeRunFromSse parses raw text, typed steps and final run',
'readVisualNovelRuntimeRunFromSse accepts payload type when event name is message',
],
label: 'visual novel SSE tests',
},
{
path: 'src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx',
needles: [
'visual novel workspace renders mock creation shell without forbidden entry',
'visual novel workspace opens editable blank draft from blank source',
'visual novel workspace uploads document asset and passes asset id to session',
],
label: 'visual novel creation tests',
},
{
path: 'src/components/visual-novel-result/VisualNovelResultView.test.tsx',
needles: [
'visual novel result opens complex editors as a dialog',
'visual novel result exposes test run action with current draft',
'visual novel result sends edited character draft to save and test run',
'visual novel result uploads scene and character assets into platform references',
],
label: 'visual novel result tests',
},
{
path: 'src/components/visual-novel-runtime/VisualNovelRuntimeShell.test.tsx',
needles: [
'visual novel runtime renders mock play surface and opens panels as dialogs',
'visual novel runtime submits free text action with client event id',
'visual novel runtime submits choice and continue actions',
'visual novel runtime panels call regeneration and platform archive actions',
'visual novel runtime shows raw text only as transient stream text',
],
label: 'visual novel runtime tests',
},
];
function repoRelative(filePath) {
return relative(repoRoot, filePath).replace(/\\/gu, '/');
}
function readText(filePath) {
return readFileSync(filePath, 'utf8');
}
function ensureFileExists(relativePath, failures, checkedFiles) {
const fullPath = join(repoRoot, relativePath);
checkedFiles.push(relativePath);
if (!existsSync(fullPath)) {
failures.push(`missing file: ${relativePath}`);
return false;
}
return true;
}
function ensureNeedles(filePath, needles, failures) {
const content = readText(filePath);
for (const needle of needles) {
if (!content.includes(needle)) {
failures.push(`missing content in ${filePath}: ${needle}`);
}
}
}
function buildReport({
failures,
checkedFiles,
contentSummary,
}) {
const status = failures.length === 0 ? '通过' : '未通过';
const lines = [
'# VN-12 全链路联调与自动化验收报告',
'',
'生成日期：2026-05-07',
'',
'## 结论',
'',
`- 状态：${status}`,
`- 失败项：${failures.length}`,
'- 收口说明：VN-12 本次只补验收门禁、关键路径测试和报告记录，未扩展新玩法功能。',
'',
'## 自动化验收清单',
'',
...checkedFiles.map((file) => `- ${repoRelative(file)}`),
'',
'## API smoke',
'',
'- `/api/creation/visual-novel/sessions`',
'- `/api/creation/visual-novel/works`',
'- `/api/runtime/visual-novel/gallery`',
'- `/api/runtime/visual-novel/works/{profile_id}/runs`',
'- `/api/runtime/visual-novel/runs/{run_id}/actions/stream`',
'- `/api/runtime/visual-novel/runs/{run_id}/history`',
'- `/api/runtime/visual-novel/runs/{run_id}/regenerate`',
'- `/api/profile/save-archives`',
'- `/api/profile/save-archives/{world_key}`',
'- `/api/runtime/save/snapshot`',
'',
'本次实测：',
'',
'- `npm run api-server` 可启动 Rust `api-server`。',
'- `GET http://127.0.0.1:3100/healthz` 返回 `200`，响应为 `{"ok":true,"service":"genarrative-api-server"}`。',
'- `GET /api/runtime/visual-novel/gallery` 在当前本地环境返回超时 / `502`，日志显示 `api-server` 连接 `127.0.0.1:3101` SpacetimeDB 数据库 `xushi-p4wfr` 被拒绝；该项按本地 SpacetimeDB 未完整就绪记录为环境阻塞，不新增工程实现。',
'',
'## 前端关键路径',
'',
'- 创作工作台：`VisualNovelAgentWorkspace`',
'- 结果页：`VisualNovelResultView`',
'- 运行时：`VisualNovelRuntimeShell`',
'- 运行时 SSE：`visualNovelRuntimeSse` / `visualNovelRuntimeClient`',
'',
'## 桌面 / 移动端检查',
'',
'- 桌面端：已用 Edge headless 截取 `/creation/visual-novel/agent`，文件为 `docs/audits/VN12_VISUAL_NOVEL_DESKTOP_2026-05-07.png`。',
'- 移动端：已用 Edge headless 截取 `/creation/visual-novel/agent`，文件为 `docs/audits/VN12_VISUAL_NOVEL_MOBILE_2026-05-07.png`。',
'- in-app browser 插件本次未发现可用 IAB backend，截图使用本机 Edge headless 兜底完成。',
'',
'## 校验摘要',
'',
...contentSummary.map((item) => `- ${item.label}: 通过`),
'',
'## 执行命令',
'',
'```bash',
'npm run check:visual-novel-vn12 -- --write-report',
'npm run test -- src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx src/components/visual-novel-runtime/VisualNovelRuntimeShell.test.tsx src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts src/services/visual-novel-runtime/visualNovelRuntimeSse.test.ts',
'npm run check:encoding',
'npm run typecheck',
'cd server-rs',
'cargo test -p shared-contracts',
'cargo test -p module-visual-novel',
'cargo check -p api-server',
'```',
'',
'## 未覆盖风险',
'',
'- 当前本地 SpacetimeDB 连接未完整就绪，公开 gallery API 的真实数据返回未在本次环境完成；`/healthz` 与编译 / 单测已通过。',
'- 若接口路由或测试名称后续调整，需要同步更新本门禁脚本与报告模板。',
'',
];
return `${lines.join('\n')}\n`;
}
const failures = [];
const checkedFiles = [];
for (const file of requiredFiles) {
ensureFileExists(file, failures, checkedFiles);
}
const contentSummary = [];
for (const check of contentChecks) {
const fullPath = join(repoRoot, check.path);
if (!ensureFileExists(check.path, failures, checkedFiles)) {
continue;
}
ensureNeedles(fullPath, check.needles, failures);
contentSummary.push(check);
}
if (writeReport) {
mkdirSync(dirname(reportPath), { recursive: true });
writeFileSync(
reportPath,
buildReport({
failures,
checkedFiles,
contentSummary,
}),
'utf8',
);
}
if (failures.length > 0) {
console.error('VN-12 acceptance gate failed:');
for (const failure of failures) {
console.error(`- ${failure}`);
}
process.exit(1);
}
console.log('VN-12 acceptance gate passed.');
console.log(`- checked files: ${checkedFiles.length}`);
console.log(`- content checks: ${contentSummary.length}`);
if (writeReport) {
console.log(`- report: ${repoRelative(reportPath)}`);
}

58
scripts/dev-rust-stack.sh
View File

@@ -44,6 +44,61 @@ resolve_client_host() {
echo "${host_name}"
}
load_api_server_env_files() {
local env_files=()
local key
local value
[[ -f "${REPO_ROOT}/.env" ]] && env_files+=("${REPO_ROOT}/.env")
[[ -f "${REPO_ROOT}/.env.local" ]] && env_files+=("${REPO_ROOT}/.env.local")
[[ -f "${REPO_ROOT}/.env.secrets.local" ]] && env_files+=("${REPO_ROOT}/.env.secrets.local")
if [[ "${#env_files[@]}" -eq 0 ]]; then
return
fi
# Node 只负责按 dotenv 子集解析文本；通过 NUL 分隔返回，避免让 env 文件内容参与 shell 求值。
while IFS= read -r -d '' key && IFS= read -r -d '' value; do
export "${key}=${value}"
done < <(
node - "${env_files[@]}" <<'NODE'
const fs = require('fs');
const shellEnvKeys = new Set(Object.keys(process.env));
const values = new Map();
for (const filePath of process.argv.slice(2)) {
if (!fs.existsSync(filePath)) {
continue;
}
const rawText = fs.readFileSync(filePath, 'utf8');
for (const rawLine of rawText.split(/\r?\n/u)) {
const line = rawLine.trim();
if (!line || line.startsWith('#')) {
continue;
}
const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/u);
if (!match) {
continue;
}
const [, key, rawValue] = match;
if (shellEnvKeys.has(key)) {
continue;
}
values.set(key, rawValue.replace(/^['"]|['"]$/gu, ''));
}
}
for (const [key, value] of values.entries()) {
process.stdout.write(`${key}\0${value}\0`);
}
NODE
)
}
cleanup() {
local index
@@ -551,6 +606,9 @@ if [[ "${SKIP_PUBLISH}" -ne 1 ]]; then
fi
echo "[dev:rust] 启动 api-server"
load_api_server_env_files
# `.env.local` 可以给单独 `dev:web` 配置代理目标，但完整栈的前端必须跟随本次 `--api-port`。
RUST_SERVER_TARGET="http://${API_TARGET_HOST}:${API_PORT}"
(
cd "${REPO_ROOT}"
GENARRATIVE_API_HOST="${API_HOST}" \

126
scripts/dev-web-rust.mjs
View File

@@ -1,21 +1,129 @@
import {spawn} from 'node:child_process';
import {existsSync, readFileSync} from 'node:fs';
import {resolve} from 'node:path';
const repoRoot = process.cwd();
const shellEnvKeys = new Set(Object.keys(process.env));
function loadEnvFile(path, target) {
if (!existsSync(path)) {
return;
}
const rawText = readFileSync(path, 'utf8');
for (const rawLine of rawText.split(/\r?\n/u)) {
const line = rawLine.trim();
if (!line || line.startsWith('#')) {
continue;
}
const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/u);
if (!match) {
continue;
}
const [, key, rawValue] = match;
// 中文注释：命令行显式传入的目标优先，`.env.local` 再覆盖 `.env`，与 api-server 启动脚本保持一致。
if (shellEnvKeys.has(key)) {
continue;
}
target[key] = rawValue.replace(/^['"]|['"]$/gu, '');
}
}
const fileEnv = {...process.env};
loadEnvFile(resolve(repoRoot, '.env'), fileEnv);
loadEnvFile(resolve(repoRoot, '.env.local'), fileEnv);
loadEnvFile(resolve(repoRoot, '.env.secrets.local'), fileEnv);
function buildTargetCandidates() {
const candidates = [
fileEnv.GENARRATIVE_RUNTIME_SERVER_TARGET,
fileEnv.RUST_SERVER_TARGET,
fileEnv.GENARRATIVE_API_TARGET,
`http://127.0.0.1:${fileEnv.GENARRATIVE_API_PORT || '3100'}`,
'http://127.0.0.1:8082',
'http://127.0.0.1:3100',
].filter(Boolean);
return Array.from(new Set(candidates));
}
async function isTargetReachable(target) {
const healthUrl = new URL('/healthz', target);
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 1200);
try {
const response = await fetch(healthUrl, {
method: 'GET',
signal: controller.signal,
});
return response.ok;
} catch {
return false;
} finally {
clearTimeout(timeoutId);
}
}
async function resolveRuntimeTarget() {
const candidates = buildTargetCandidates();
const reachableTargets = [];
for (const target of candidates) {
if (await isTargetReachable(target)) {
reachableTargets.push(target);
if (
target === fileEnv.GENARRATIVE_RUNTIME_SERVER_TARGET ||
target === fileEnv.RUST_SERVER_TARGET ||
target === fileEnv.GENARRATIVE_API_TARGET
) {
return {
target,
fallbackUsed: false,
};
}
}
}
if (reachableTargets.length > 0) {
return {
target: reachableTargets[0],
fallbackUsed: true,
};
}
return {
target:
fileEnv.GENARRATIVE_RUNTIME_SERVER_TARGET ||
fileEnv.RUST_SERVER_TARGET ||
fileEnv.GENARRATIVE_API_TARGET ||
`http://127.0.0.1:${fileEnv.GENARRATIVE_API_PORT || '3100'}`,
fallbackUsed: false,
};
}
const runtimeTarget = await resolveRuntimeTarget();
if (runtimeTarget.fallbackUsed) {
console.warn(
`[dev:web] 配置的 Rust target 不可用，已切换到 ${runtimeTarget.target}`,
);
}
const mergedEnv = {
...process.env,
RUST_SERVER_TARGET:
process.env.RUST_SERVER_TARGET ||
process.env.GENARRATIVE_API_TARGET ||
`http://127.0.0.1:${process.env.GENARRATIVE_API_PORT || '3100'}`,
...fileEnv,
RUST_SERVER_TARGET: runtimeTarget.target,
GENARRATIVE_RUNTIME_SERVER_TARGET: runtimeTarget.target,
};
mergedEnv.GENARRATIVE_RUNTIME_SERVER_TARGET =
process.env.GENARRATIVE_RUNTIME_SERVER_TARGET || mergedEnv.RUST_SERVER_TARGET;
console.log(`[dev:web] backend=rust target=${mergedEnv.GENARRATIVE_RUNTIME_SERVER_TARGET}`);
const child = spawn(
'node',
['scripts/vite-cli.mjs', '--port=3000', '--host=0.0.0.0'],
['scripts/vite-cli.mjs', '--port=3000', '--host=0.0.0.0', '--strictPort'],
{
cwd: process.cwd(),
env: mergedEnv,

738
server-rs/Cargo.lock generated
View File

File diff suppressed because it is too large Load Diff

15
server-rs/Cargo.toml
View File

@@ -13,6 +13,7 @@ members = [
"crates/module-auth",
"crates/module-big-fish",
"crates/module-combat",
"crates/module-creative-agent",
"crates/module-inventory",
"crates/module-custom-world",
"crates/module-match3d",
@@ -25,9 +26,12 @@ members = [
"crates/module-runtime-item",
"crates/module-square-hole",
"crates/module-story",
"crates/module-visual-novel",
"crates/platform-oss",
"crates/platform-auth",
"crates/platform-llm",
"crates/platform-speech",
"crates/platform-agent",
"crates/shared-contracts",
"crates/shared-kernel",
"crates/shared-logging",
@@ -48,6 +52,7 @@ module-assets = { path = "crates/module-assets", default-features = false }
module-auth = { path = "crates/module-auth", default-features = false }
module-big-fish = { path = "crates/module-big-fish", default-features = false }
module-combat = { path = "crates/module-combat", default-features = false }
module-creative-agent = { path = "crates/module-creative-agent", default-features = false }
module-custom-world = { path = "crates/module-custom-world", default-features = false }
module-inventory = { path = "crates/module-inventory", default-features = false }
module-match3d = { path = "crates/module-match3d", default-features = false }
@@ -60,9 +65,12 @@ module-runtime-item = { path = "crates/module-runtime-item", default-features =
module-runtime-story = { path = "crates/module-runtime-story", default-features = false }
module-square-hole = { path = "crates/module-square-hole", default-features = false }
module-story = { path = "crates/module-story", default-features = false }
module-visual-novel = { path = "crates/module-visual-novel", default-features = false }
platform-agent = { path = "crates/platform-agent", default-features = false }
platform-auth = { path = "crates/platform-auth", default-features = false }
platform-llm = { path = "crates/platform-llm", default-features = false }
platform-oss = { path = "crates/platform-oss", default-features = false }
platform-speech = { path = "crates/platform-speech", default-features = false }
shared-contracts = { path = "crates/shared-contracts", default-features = false }
shared-kernel = { path = "crates/shared-kernel", default-features = false }
shared-logging = { path = "crates/shared-logging", default-features = false }
@@ -70,13 +78,18 @@ spacetime-client = { path = "crates/spacetime-client", default-features = false
argon2 = "0.5"
async-stream = "0.3"
async-trait = "0.1"
axum = "0.8"
base64 = "0.22"
bytes = "1"
dotenvy = "0.15"
flate2 = "1"
futures-util = "0.3"
hmac = "0.12"
http-body-util = "0.1"
image = { version = "0.25", default-features = false }
jsonwebtoken = "9"
langchainrust = "0.2.18"
log = "0.4"
rand_core = "0.6"
reqwest = { version = "0.12", default-features = false }
@@ -90,6 +103,7 @@ spacetimedb-lib = { version = "2.2.0", default-features = false }
time = "0.3"
tokio = "1"
tokio-stream = "0.1"
tokio-tungstenite = "0.27"
tower = "0.5"
tower-http = "0.6"
tracing = "0.1"
@@ -98,6 +112,7 @@ url = "2"
urlencoding = "2"
uuid = "1"
webp = "0.3"
zip = { version = "2", default-features = false }
[profile.dev]
opt-level = 0 # 默认 0，有人手滑改 1/2 会慢

8
server-rs/crates/api-server/Cargo.toml
View File

@@ -6,7 +6,7 @@ license.workspace = true
[dependencies]
async-stream = { workspace = true }
axum = { workspace = true }
axum = { workspace = true, features = ["ws"] }
base64 = { workspace = true }
dotenvy = { workspace = true }
image = { workspace = true, features = ["jpeg", "png", "webp"] }
@@ -17,6 +17,7 @@ module-assets = { workspace = true, features = ["server-service"] }
module-auth = { workspace = true }
module-big-fish = { workspace = true }
module-combat = { workspace = true }
module-creative-agent = { workspace = true }
module-custom-world = { workspace = true }
module-inventory = { workspace = true }
module-match3d = { workspace = true }
@@ -27,9 +28,12 @@ module-runtime-story = { workspace = true }
module-runtime-item = { workspace = true }
module-square-hole = { workspace = true }
module-story = { workspace = true }
module-visual-novel = { workspace = true }
platform-agent = { workspace = true }
platform-auth = { workspace = true }
platform-llm = { workspace = true }
platform-oss = { workspace = true }
platform-speech = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
shared-contracts = { workspace = true }
@@ -38,12 +42,14 @@ shared-logging = { workspace = true }
spacetime-client = { workspace = true }
tokio = { workspace = true, features = ["macros", "rt-multi-thread", "net", "time"] }
tokio-stream = { workspace = true }
futures-util = { workspace = true }
time = { workspace = true, features = ["formatting"] }
tower-http = { workspace = true, features = ["trace"] }
tracing = { workspace = true }
url = { workspace = true }
urlencoding = { workspace = true }
uuid = { workspace = true, features = ["v4"] }
zip = { workspace = true, features = ["deflate"] }
[dev-dependencies]
base64 = { workspace = true }

573
server-rs/crates/api-server/src/app.rs
View File

@@ -49,6 +49,11 @@ use crate::{
generate_character_visual, get_character_visual_job, publish_character_visual,
},
creation_agent_document_input::parse_creation_agent_document_input,
creative_agent::{
cancel_creative_agent_session, confirm_creative_puzzle_template,
create_creative_agent_session, get_creative_agent_session, stream_creative_agent_message,
stream_creative_draft_edit,
},
custom_world::{
create_custom_world_agent_session, delete_custom_world_agent_session,
delete_custom_world_library_profile, execute_custom_world_agent_action,
@@ -140,6 +145,22 @@ use crate::{
begin_story_runtime_session, begin_story_session, continue_story,
get_story_runtime_projection, get_story_session_state, resolve_story_runtime_action,
},
vector_engine_audio_generation::{
create_visual_novel_background_music_task, create_visual_novel_sound_effect_task,
publish_visual_novel_background_music_asset, publish_visual_novel_sound_effect_asset,
},
visual_novel::{
compile_visual_novel_session, create_visual_novel_session, delete_visual_novel_work,
execute_visual_novel_action, get_visual_novel_run, get_visual_novel_session,
get_visual_novel_work, list_visual_novel_gallery, list_visual_novel_history,
list_visual_novel_works, publish_visual_novel_work, regenerate_visual_novel_run,
start_visual_novel_run, stream_visual_novel_action, stream_visual_novel_message,
submit_visual_novel_message, update_visual_novel_work,
},
volcengine_speech::{
get_volcengine_speech_config, stream_volcengine_asr, stream_volcengine_tts_bidirection,
stream_volcengine_tts_sse,
},
wechat_auth::{bind_wechat_phone, handle_wechat_callback, start_wechat_login},
};
@@ -314,6 +335,34 @@ pub fn build_router(state: AppState) -> Router {
require_bearer_auth,
)),
)
.route(
"/api/speech/volcengine/config",
get(get_volcengine_speech_config).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/speech/volcengine/asr/stream",
get(stream_volcengine_asr).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/speech/volcengine/tts/bidirection",
get(stream_volcengine_tts_bidirection).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/speech/volcengine/tts/sse",
post(stream_volcengine_tts_sse).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/runtime/chat/character/suggestions",
post(generate_runtime_character_chat_suggestions).route_layer(
@@ -1029,6 +1078,8 @@ pub fn build_router(state: AppState) -> Router {
require_bearer_auth,
)),
)
.merge(creative_agent_router(state.clone()))
.merge(visual_novel_router(state.clone()))
.route(
"/api/runtime/puzzle/onboarding/generate",
post(generate_puzzle_onboarding_work).layer(DefaultBodyLimit::max(
@@ -1453,6 +1504,197 @@ pub fn build_router(state: AppState) -> Router {
.with_state(state)
}
fn creative_agent_router(state: AppState) -> Router<AppState> {
Router::new()
.route(
"/api/runtime/creative-agent/sessions",
post(create_creative_agent_session)
// 中文注释：创意 Agent 首轮允许携带参考图 URL/Data URL，沿用拼图参考图入口上限。
.layer(DefaultBodyLimit::max(
PUZZLE_REFERENCE_IMAGE_BODY_LIMIT_BYTES,
))
.route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/runtime/creative-agent/sessions/{session_id}",
get(get_creative_agent_session).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/runtime/creative-agent/sessions/{session_id}/messages/stream",
post(stream_creative_agent_message)
// 中文注释：message stream 同样可能带图片素材，避免默认 JSON limit 过早拒绝。
.layer(DefaultBodyLimit::max(
PUZZLE_REFERENCE_IMAGE_BODY_LIMIT_BYTES,
))
.route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/runtime/creative-agent/sessions/{session_id}/confirm-template",
post(confirm_creative_puzzle_template).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/runtime/creative-agent/sessions/{session_id}/draft-edits/stream",
post(stream_creative_draft_edit)
// 中文注释：草稿编辑会携带当前 puzzle draft JSON，保持和拼图草稿入口一致的 body 上限。
.layer(DefaultBodyLimit::max(
PUZZLE_REFERENCE_IMAGE_BODY_LIMIT_BYTES,
))
.route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/runtime/creative-agent/sessions/{session_id}/cancel",
post(cancel_creative_agent_session)
.route_layer(middleware::from_fn_with_state(state, require_bearer_auth)),
)
}
fn visual_novel_router(state: AppState) -> Router<AppState> {
Router::new()
.route(
"/api/creation/visual-novel/sessions",
post(create_visual_novel_session).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/creation/visual-novel/sessions/{session_id}",
get(get_visual_novel_session).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/creation/visual-novel/sessions/{session_id}/messages",
post(submit_visual_novel_message).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/creation/visual-novel/sessions/{session_id}/messages/stream",
post(stream_visual_novel_message).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/creation/visual-novel/sessions/{session_id}/actions",
post(execute_visual_novel_action).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/creation/visual-novel/sessions/{session_id}/compile",
post(compile_visual_novel_session).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/creation/visual-novel/works",
get(list_visual_novel_works).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/creation/visual-novel/works/{profile_id}",
get(get_visual_novel_work)
.put(update_visual_novel_work)
.patch(update_visual_novel_work)
.delete(delete_visual_novel_work)
.route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/creation/visual-novel/works/{profile_id}/publish",
post(publish_visual_novel_work).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/creation/visual-novel/audio/background-music",
post(create_visual_novel_background_music_task).route_layer(
middleware::from_fn_with_state(state.clone(), require_bearer_auth),
),
)
.route(
"/api/creation/visual-novel/audio/background-music/{task_id}/asset",
post(publish_visual_novel_background_music_asset).route_layer(
middleware::from_fn_with_state(state.clone(), require_bearer_auth),
),
)
.route(
"/api/creation/visual-novel/audio/sound-effect",
post(create_visual_novel_sound_effect_task).route_layer(
middleware::from_fn_with_state(state.clone(), require_bearer_auth),
),
)
.route(
"/api/creation/visual-novel/audio/sound-effect/{task_id}/asset",
post(publish_visual_novel_sound_effect_asset).route_layer(
middleware::from_fn_with_state(state.clone(), require_bearer_auth),
),
)
.route(
"/api/runtime/visual-novel/gallery",
get(list_visual_novel_gallery),
)
.route(
"/api/runtime/visual-novel/works/{profile_id}/runs",
post(start_visual_novel_run).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/runtime/visual-novel/runs/{run_id}",
get(get_visual_novel_run).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/runtime/visual-novel/runs/{run_id}/actions/stream",
post(stream_visual_novel_action).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/runtime/visual-novel/runs/{run_id}/history",
get(list_visual_novel_history).route_layer(middleware::from_fn_with_state(
state.clone(),
require_bearer_auth,
)),
)
.route(
"/api/runtime/visual-novel/runs/{run_id}/regenerate",
post(regenerate_visual_novel_run)
.route_layer(middleware::from_fn_with_state(state, require_bearer_auth)),
)
}
#[cfg(test)]
mod tests {
use axum::{
@@ -1475,6 +1717,8 @@ mod tests {
use super::build_router;
const TEST_PASSWORD: &str = "secret123";
const INTERNAL_TEST_SECRET: &str = "test-internal-secret";
async fn seed_phone_user_with_password(
state: &AppState,
phone_number: &str,
@@ -1532,6 +1776,43 @@ mod tests {
.expect("password login request should succeed")
}
fn build_internal_creative_agent_app() -> Router {
let mut config = AppConfig::default();
config.internal_api_secret = Some(INTERNAL_TEST_SECRET.to_string());
build_router(AppState::new(config).expect("state should build"))
}
fn internal_creative_agent_request(method: &str, uri: &str, body: Value) -> Request<Body> {
Request::builder()
.method(method)
.uri(uri)
.header("content-type", "application/json")
.header("x-genarrative-authenticated-user-id", "user-creative-test")
.header("x-genarrative-internal-api-secret", INTERNAL_TEST_SECRET)
.body(Body::from(body.to_string()))
.expect("creative agent request should build")
}
async fn read_json_response(response: axum::response::Response) -> Value {
let body = response
.into_body()
.collect()
.await
.expect("response body should collect")
.to_bytes();
serde_json::from_slice(&body).expect("response body should be valid json")
}
async fn read_text_response(response: axum::response::Response) -> String {
let body = response
.into_body()
.collect()
.await
.expect("response body should collect")
.to_bytes();
String::from_utf8(body.to_vec()).expect("response body should be utf8")
}
#[tokio::test]
async fn healthz_returns_legacy_compatible_payload_and_headers() {
let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
@@ -1625,6 +1906,244 @@ mod tests {
);
}
#[tokio::test]
async fn creative_agent_draft_edit_rejects_unconfirmed_template_session() {
let app = build_internal_creative_agent_app();
let create_response = app
.clone()
.oneshot(internal_creative_agent_request(
"POST",
"/api/runtime/creative-agent/sessions",
serde_json::json!({
"text": "做一个生日拼图",
"entryContext": "creation_home"
}),
))
.await
.expect("create session request should succeed");
assert_eq!(create_response.status(), StatusCode::OK);
let create_payload = read_json_response(create_response).await;
let session_id = create_payload["session"]["sessionId"]
.as_str()
.expect("session id should exist");
let edit_response = app
.clone()
.oneshot(internal_creative_agent_request(
"POST",
&format!("/api/runtime/creative-agent/sessions/{session_id}/draft-edits/stream"),
serde_json::json!({
"clientMessageId": "creative-edit-test",
"instruction": "把标题改轻松一点",
"targetPuzzleSessionId": "puzzle-session-unconfirmed",
"currentDraft": {
"workTitle": "旧标题",
"workDescription": "旧描述",
"summary": "旧描述",
"themeTags": ["创意", "拼图", "灵感"],
"levels": [{
"levelId": "puzzle-level-1",
"levelName": "第一关",
"pictureDescription": "旧图面",
"pictureReference": null,
"generationStatus": "idle",
"candidates": []
}]
}
}),
))
.await
.expect("draft edit request should be handled");
assert_eq!(edit_response.status(), StatusCode::BAD_REQUEST);
let edit_payload = read_json_response(edit_response).await;
assert_eq!(
edit_payload["error"]["details"]["message"],
Value::String("尚未绑定拼图草稿".to_string())
);
let session_response = app
.oneshot(internal_creative_agent_request(
"GET",
&format!("/api/runtime/creative-agent/sessions/{session_id}"),
Value::Null,
))
.await
.expect("get session request should succeed");
let session_payload = read_json_response(session_response).await;
assert_eq!(session_payload["session"]["targetBinding"], Value::Null);
}
#[tokio::test]
async fn creative_agent_message_stream_returns_template_confirmation_events() {
let app = build_internal_creative_agent_app();
let create_response = app
.clone()
.oneshot(internal_creative_agent_request(
"POST",
"/api/runtime/creative-agent/sessions",
serde_json::json!({
"text": "做一个生日拼图",
"entryContext": "creation_home"
}),
))
.await
.expect("create session request should succeed");
assert_eq!(create_response.status(), StatusCode::OK);
let create_payload = read_json_response(create_response).await;
let session_id = create_payload["session"]["sessionId"]
.as_str()
.expect("session id should exist");
let stream_response = app
.clone()
.oneshot(internal_creative_agent_request(
"POST",
&format!("/api/runtime/creative-agent/sessions/{session_id}/messages/stream"),
serde_json::json!({
"clientMessageId": "creative-message-stream-test",
"content": [{
"type": "input_text",
"text": "做一个温暖的生日拼图"
}]
}),
))
.await
.expect("message stream request should be handled");
assert_eq!(stream_response.status(), StatusCode::OK);
assert_eq!(
stream_response
.headers()
.get("content-type")
.and_then(|value| value.to_str().ok()),
Some("text/event-stream")
);
let stream_body = read_text_response(stream_response).await;
assert!(stream_body.contains("event: stage"));
assert!(stream_body.contains("event: tool_started"));
assert!(stream_body.contains("event: tool_completed"));
assert!(stream_body.contains("event: puzzle_template_catalog"));
assert!(!stream_body.contains("event: puzzle_template_selection"));
assert!(!stream_body.contains("event: puzzle_cost_range"));
assert!(stream_body.contains("event: done"));
let tool_started_id = stream_body
.lines()
.skip_while(|line| *line != "event: tool_started")
.nth(1)
.and_then(|line| line.strip_prefix("data: "))
.and_then(|data| serde_json::from_str::<Value>(data).ok())
.and_then(|payload| payload["toolCallId"].as_str().map(ToString::to_string))
.expect("tool_started should include toolCallId");
let tool_completed_id = stream_body
.lines()
.skip_while(|line| *line != "event: tool_completed")
.nth(1)
.and_then(|line| line.strip_prefix("data: "))
.and_then(|data| serde_json::from_str::<Value>(data).ok())
.and_then(|payload| payload["toolCallId"].as_str().map(ToString::to_string))
.expect("tool_completed should include toolCallId");
assert_eq!(tool_started_id, tool_completed_id);
let session_response = app
.oneshot(internal_creative_agent_request(
"GET",
&format!("/api/runtime/creative-agent/sessions/{session_id}"),
Value::Null,
))
.await
.expect("get session request should succeed");
let session_payload = read_json_response(session_response).await;
assert_eq!(
session_payload["session"]["stage"],
Value::String("waiting_template_confirmation".to_string())
);
assert_eq!(
session_payload["session"]["puzzleTemplateSelection"],
Value::Null
);
assert!(
session_payload["session"]["puzzleTemplateCatalog"]
.as_array()
.map(|templates| templates.len() >= 3)
.unwrap_or(false)
);
}
#[tokio::test]
async fn creative_agent_confirm_template_rejects_non_puzzle_template() {
let app = build_internal_creative_agent_app();
let create_response = app
.clone()
.oneshot(internal_creative_agent_request(
"POST",
"/api/runtime/creative-agent/sessions",
serde_json::json!({
"text": "做一个角色扮演开场",
"entryContext": "creation_home"
}),
))
.await
.expect("create session request should succeed");
assert_eq!(create_response.status(), StatusCode::OK);
let create_payload = read_json_response(create_response).await;
let session_id = create_payload["session"]["sessionId"]
.as_str()
.expect("session id should exist");
let confirm_response = app
.clone()
.oneshot(internal_creative_agent_request(
"POST",
&format!("/api/runtime/creative-agent/sessions/{session_id}/confirm-template"),
serde_json::json!({
"selection": {
"templateId": "rpg.unsupported",
"title": "RPG",
"reason": "用户想创建 RPG",
"costRange": {
"minPoints": 2,
"maxPoints": 12,
"pricingUnit": "point",
"reason": "按关卡数和每关图片生成次数估算，实际扣费以后端任务结算为准"
},
"supportedLevelMode": "single_or_multi",
"selectedLevelMode": "single_level",
"plannedLevelCount": 1,
"requiresUserConfirmation": true
}
}),
))
.await
.expect("confirm template request should be handled");
assert_eq!(confirm_response.status(), StatusCode::BAD_REQUEST);
let confirm_payload = read_json_response(confirm_response).await;
assert_eq!(
confirm_payload["error"]["details"]["provider"],
Value::String("module-puzzle".to_string())
);
let session_response = app
.oneshot(internal_creative_agent_request(
"GET",
&format!("/api/runtime/creative-agent/sessions/{session_id}"),
Value::Null,
))
.await
.expect("get session request should succeed");
let session_payload = read_json_response(session_response).await;
assert_eq!(
session_payload["session"]["stage"],
Value::String("idle".to_string())
);
assert_eq!(session_payload["session"]["targetBinding"], Value::Null);
}
#[tokio::test]
async fn runtime_story_legacy_routes_are_not_mounted() {
let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
@@ -4007,4 +4526,58 @@ mod tests {
assert_eq!(debug_response.status(), StatusCode::UNAUTHORIZED);
}
#[tokio::test]
async fn visual_novel_creation_route_requires_authentication() {
let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
let response = app
.oneshot(
Request::builder()
.method("POST")
.uri("/api/creation/visual-novel/sessions")
.header("content-type", "application/json")
.body(Body::from(
serde_json::json!({
"sourceMode": "idea",
"seedText": "雨夜书店",
"sourceAssetIds": []
})
.to_string(),
))
.expect("request should build"),
)
.await
.expect("request should succeed");
assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
}
#[tokio::test]
async fn visual_novel_forbidden_playback_routes_are_not_mounted() {
let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
let legacy_playback_segment = concat!("re", "play");
for path in [
format!("/api/creation/visual-novel/{legacy_playback_segment}"),
format!("/api/runtime/visual-novel/{legacy_playback_segment}"),
format!("/api/runtime/visual-novel/{legacy_playback_segment}s"),
format!("/api/visual/{legacy_playback_segment}"),
format!("/api/galgame/{legacy_playback_segment}"),
format!("/api/txt/{legacy_playback_segment}"),
] {
let response = app
.clone()
.oneshot(
Request::builder()
.uri(path.as_str())
.body(Body::empty())
.expect("request should build"),
)
.await
.expect("request should succeed");
assert_eq!(response.status(), StatusCode::NOT_FOUND, "{path}");
}
}
}

27
server-rs/crates/api-server/src/assets.rs
View File

@@ -1458,7 +1458,7 @@ mod tests {
endpoint: &str,
signed_at: time::OffsetDateTime,
) -> Result<String, Box<dyn Error>> {
let date = signed_at.date().to_string().replace('-', "");
let date = format_oss_v4_signature_scope_date(signed_at);
let region = endpoint
.trim()
.split('.')
@@ -1470,17 +1470,22 @@ mod tests {
}
fn build_oss_v4_signature_date(signed_at: time::OffsetDateTime) -> String {
let date = signed_at.date().to_string().replace('-', "");
let time = signed_at
.time()
.to_string()
.split('.')
.next()
.unwrap_or("00:00:00")
.replace(':', "");
format!(
"{}T{:02}{:02}{:02}Z",
format_oss_v4_signature_scope_date(signed_at),
signed_at.hour(),
signed_at.minute(),
signed_at.second()
)
}
debug_assert_eq!(time.len(), 6);
format!("{date}T{time}Z")
fn format_oss_v4_signature_scope_date(signed_at: time::OffsetDateTime) -> String {
format!(
"{:04}{:02}{:02}",
signed_at.year(),
signed_at.month() as u8,
signed_at.day()
)
}
fn build_oss_v4_canonical_uri(bucket: &str, object_key: Option<&str>) -> String {

4
server-rs/crates/api-server/src/auth.rs
View File

@@ -191,6 +191,7 @@ fn allows_internal_forwarded_auth(path: &str) -> bool {
// Node 代理已经完成平台账号 JWT 校验，Rust 运行时只信任这些明确的内部转发路径。
path.starts_with("/api/runtime/big-fish/")
|| path.starts_with("/api/runtime/chat/")
|| path.starts_with("/api/runtime/creative-agent/")
|| path.starts_with("/api/runtime/puzzle/")
}
@@ -287,6 +288,9 @@ mod tests {
assert!(allows_internal_forwarded_auth(
"/api/runtime/chat/npc/turn/stream"
));
assert!(allows_internal_forwarded_auth(
"/api/runtime/creative-agent/sessions"
));
assert!(allows_internal_forwarded_auth("/api/runtime/puzzle/works"));
assert!(!allows_internal_forwarded_auth("/api/auth/me"));
}

85
server-rs/crates/api-server/src/config.rs
View File

@@ -4,6 +4,11 @@ use platform_llm::{
DEFAULT_ARK_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_REQUEST_TIMEOUT_MS,
DEFAULT_RETRY_BACKOFF_MS, LlmProvider,
};
use platform_speech::{
DEFAULT_ASR_RESOURCE_ID, DEFAULT_ASR_WS_URL,
DEFAULT_REQUEST_TIMEOUT_MS as DEFAULT_SPEECH_REQUEST_TIMEOUT_MS,
DEFAULT_TTS_BIDIRECTION_WS_URL, DEFAULT_TTS_RESOURCE_ID, DEFAULT_TTS_SSE_URL,
};
const DEFAULT_INTERNAL_API_SECRET: &str = "genarrative-dev-internal-bridge";
const DEFAULT_AUTH_STORE_PATH: &str = "server-rs/.data/auth-store.json";
@@ -92,6 +97,18 @@ pub struct AppConfig {
pub apimart_base_url: String,
pub apimart_api_key: Option<String>,
pub apimart_image_request_timeout_ms: u64,
pub vector_engine_base_url: String,
pub vector_engine_api_key: Option<String>,
pub vector_engine_audio_request_timeout_ms: u64,
pub volcengine_speech_api_key: Option<String>,
pub volcengine_speech_app_id: Option<String>,
pub volcengine_speech_access_key: Option<String>,
pub volcengine_speech_asr_resource_id: String,
pub volcengine_speech_tts_resource_id: String,
pub volcengine_speech_asr_ws_url: String,
pub volcengine_speech_tts_bidirection_ws_url: String,
pub volcengine_speech_tts_sse_url: String,
pub volcengine_speech_request_timeout_ms: u64,
pub draft_asset_generation_max_concurrent_requests: usize,
pub ark_character_video_base_url: String,
pub ark_character_video_api_key: Option<String>,
@@ -187,6 +204,18 @@ impl Default for AppConfig {
apimart_base_url: String::new(),
apimart_api_key: None,
apimart_image_request_timeout_ms: 180_000,
vector_engine_base_url: String::new(),
vector_engine_api_key: None,
vector_engine_audio_request_timeout_ms: 180_000,
volcengine_speech_api_key: None,
volcengine_speech_app_id: None,
volcengine_speech_access_key: None,
volcengine_speech_asr_resource_id: DEFAULT_ASR_RESOURCE_ID.to_string(),
volcengine_speech_tts_resource_id: DEFAULT_TTS_RESOURCE_ID.to_string(),
volcengine_speech_asr_ws_url: DEFAULT_ASR_WS_URL.to_string(),
volcengine_speech_tts_bidirection_ws_url: DEFAULT_TTS_BIDIRECTION_WS_URL.to_string(),
volcengine_speech_tts_sse_url: DEFAULT_TTS_SSE_URL.to_string(),
volcengine_speech_request_timeout_ms: DEFAULT_SPEECH_REQUEST_TIMEOUT_MS,
draft_asset_generation_max_concurrent_requests: 4,
ark_character_video_base_url: String::new(),
ark_character_video_api_key: None,
@@ -544,6 +573,54 @@ impl AppConfig {
config.apimart_image_request_timeout_ms = apimart_image_request_timeout_ms;
}
if let Some(vector_engine_base_url) = read_first_non_empty_env(&["VECTOR_ENGINE_BASE_URL"])
{
config.vector_engine_base_url = vector_engine_base_url;
}
config.vector_engine_api_key = read_first_non_empty_env(&["VECTOR_ENGINE_API_KEY"]);
if let Some(vector_engine_audio_request_timeout_ms) =
read_first_positive_u64_env(&["VECTOR_ENGINE_AUDIO_REQUEST_TIMEOUT_MS"])
{
config.vector_engine_audio_request_timeout_ms = vector_engine_audio_request_timeout_ms;
}
config.volcengine_speech_api_key =
read_first_non_empty_env(&["VOLCENGINE_SPEECH_API_KEY", "VOLCENGINE_API_KEY"]);
config.volcengine_speech_app_id =
read_first_non_empty_env(&["VOLCENGINE_SPEECH_APP_ID", "VOLCENGINE_ACCESS_KEY_ID"]);
config.volcengine_speech_access_key = read_first_non_empty_env(&[
"VOLCENGINE_SPEECH_ACCESS_KEY",
"VOLCENGINE_SECRET_ACCESS_KEY",
]);
if let Some(asr_resource_id) =
read_first_non_empty_env(&["VOLCENGINE_SPEECH_ASR_RESOURCE_ID"])
{
config.volcengine_speech_asr_resource_id = asr_resource_id;
}
if let Some(tts_resource_id) =
read_first_non_empty_env(&["VOLCENGINE_SPEECH_TTS_RESOURCE_ID"])
{
config.volcengine_speech_tts_resource_id = tts_resource_id;
}
if let Some(asr_ws_url) = read_first_non_empty_env(&["VOLCENGINE_SPEECH_ASR_WS_URL"]) {
config.volcengine_speech_asr_ws_url = asr_ws_url;
}
if let Some(tts_bidirection_ws_url) =
read_first_non_empty_env(&["VOLCENGINE_SPEECH_TTS_BIDIRECTION_WS_URL"])
{
config.volcengine_speech_tts_bidirection_ws_url = tts_bidirection_ws_url;
}
if let Some(tts_sse_url) = read_first_non_empty_env(&["VOLCENGINE_SPEECH_TTS_SSE_URL"]) {
config.volcengine_speech_tts_sse_url = tts_sse_url;
}
if let Some(request_timeout_ms) =
read_first_positive_u64_env(&["VOLCENGINE_SPEECH_REQUEST_TIMEOUT_MS"])
{
config.volcengine_speech_request_timeout_ms = request_timeout_ms;
}
if let Some(max_concurrent_requests) = read_first_usize_env(&[
"GENARRATIVE_DRAFT_ASSET_GENERATION_MAX_CONCURRENT_REQUESTS",
"DRAFT_ASSET_GENERATION_MAX_CONCURRENT_REQUESTS",
@@ -831,6 +908,7 @@ mod tests {
assert!(config.llm_model.is_empty());
assert!(config.llm_base_url.is_empty());
assert!(config.apimart_base_url.is_empty());
assert!(config.vector_engine_base_url.is_empty());
assert!(config.ark_character_video_base_url.is_empty());
assert!(config.ark_character_video_model.is_empty());
assert!(config.dashscope_scene_image_model.is_empty());
@@ -859,6 +937,7 @@ mod tests {
std::env::remove_var("GENARRATIVE_LLM_BASE_URL");
std::env::remove_var("GENARRATIVE_LLM_MODEL");
std::env::remove_var("APIMART_BASE_URL");
std::env::remove_var("VECTOR_ENGINE_BASE_URL");
std::env::remove_var("DASHSCOPE_SCENE_IMAGE_MODEL");
std::env::remove_var("DASHSCOPE_REFERENCE_IMAGE_MODEL");
std::env::remove_var("DASHSCOPE_COVER_IMAGE_MODEL");
@@ -871,6 +950,7 @@ mod tests {
);
std::env::set_var("GENARRATIVE_LLM_MODEL", "internal-text-model");
std::env::set_var("APIMART_BASE_URL", "https://image.internal.example/v1");
std::env::set_var("VECTOR_ENGINE_BASE_URL", "https://audio.internal.example");
std::env::set_var("DASHSCOPE_SCENE_IMAGE_MODEL", "scene-model");
std::env::set_var("DASHSCOPE_REFERENCE_IMAGE_MODEL", "reference-model");
std::env::set_var("DASHSCOPE_COVER_IMAGE_MODEL", "cover-model");
@@ -886,6 +966,10 @@ mod tests {
assert_eq!(config.llm_base_url, "https://llm.internal.example/v1");
assert_eq!(config.llm_model, "internal-text-model");
assert_eq!(config.apimart_base_url, "https://image.internal.example/v1");
assert_eq!(
config.vector_engine_base_url,
"https://audio.internal.example"
);
assert_eq!(config.dashscope_scene_image_model, "scene-model");
assert_eq!(config.dashscope_reference_image_model, "reference-model");
assert_eq!(config.dashscope_cover_image_model, "cover-model");
@@ -900,6 +984,7 @@ mod tests {
std::env::remove_var("GENARRATIVE_LLM_BASE_URL");
std::env::remove_var("GENARRATIVE_LLM_MODEL");
std::env::remove_var("APIMART_BASE_URL");
std::env::remove_var("VECTOR_ENGINE_BASE_URL");
std::env::remove_var("DASHSCOPE_SCENE_IMAGE_MODEL");
std::env::remove_var("DASHSCOPE_REFERENCE_IMAGE_MODEL");
std::env::remove_var("DASHSCOPE_COVER_IMAGE_MODEL");

106
server-rs/crates/api-server/src/creation_agent_document_input.rs
View File

@@ -1,3 +1,5 @@
use std::io::{Cursor, Read};
use axum::{Json, extract::Extension, http::StatusCode};
use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64_STANDARD};
use serde_json::{Value, json};
@@ -12,7 +14,7 @@ use crate::{
const MAX_DOCUMENT_INPUT_BYTES: usize = 256 * 1024;
const MAX_DOCUMENT_INPUT_BASE64_CHARS: usize = 360 * 1024;
const SUPPORTED_DOCUMENT_EXTENSIONS: &[&str] = &["txt", "md", "markdown", "csv", "json"];
const SUPPORTED_DOCUMENT_EXTENSIONS: &[&str] = &["txt", "md", "markdown", "docx", "csv", "json"];
pub async fn parse_creation_agent_document_input(
Extension(request_context): Extension<RequestContext>,
@@ -58,12 +60,8 @@ pub async fn parse_creation_agent_document_input(
);
}
let text = String::from_utf8(decoded.clone()).map_err(|_| {
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"message": "暂时只支持 UTF-8 文本文档，请转换编码后再上传。",
"field": "contentBase64",
}))
})?;
let extension = document_extension(&file_name)?;
let text = decode_document_text(&decoded, extension.as_str())?;
let normalized_text = normalize_document_text(&text);
if normalized_text.trim().is_empty() {
@@ -88,6 +86,7 @@ pub async fn parse_creation_agent_document_input(
.map(str::to_string),
size_bytes: decoded.len(),
text: normalized_text,
source_asset_id: None,
},
},
))
@@ -115,11 +114,7 @@ fn normalize_file_name(value: &str) -> Result<String, AppError> {
}
fn ensure_supported_extension(file_name: &str) -> Result<(), AppError> {
let extension = file_name
.rsplit_once('.')
.map(|(_, extension)| extension.trim().to_ascii_lowercase())
.filter(|extension| !extension.is_empty())
.ok_or_else(|| unsupported_document_error(file_name))?;
let extension = document_extension(file_name)?;
if !SUPPORTED_DOCUMENT_EXTENSIONS.contains(&extension.as_str()) {
return Err(unsupported_document_error(file_name));
@@ -128,15 +123,100 @@ fn ensure_supported_extension(file_name: &str) -> Result<(), AppError> {
Ok(())
}
fn document_extension(file_name: &str) -> Result<String, AppError> {
file_name
.rsplit_once('.')
.map(|(_, extension)| extension.trim().to_ascii_lowercase())
.filter(|extension| !extension.is_empty())
.ok_or_else(|| unsupported_document_error(file_name))
}
fn unsupported_document_error(file_name: &str) -> AppError {
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"message": "暂时只支持 txt、md、csv、json 文本文档。",
"message": "暂时只支持 txt、md、docx、csv、json 文档。",
"field": "fileName",
"fileName": file_name,
"supportedExtensions": SUPPORTED_DOCUMENT_EXTENSIONS,
}))
}
fn decode_document_text(bytes: &[u8], extension: &str) -> Result<String, AppError> {
if extension == "docx" {
return extract_docx_text(bytes);
}
String::from_utf8(bytes.to_vec()).map_err(|_| {
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"message": "暂时只支持 UTF-8 文本文档，请转换编码后再上传。",
"field": "contentBase64",
}))
})
}
fn extract_docx_text(bytes: &[u8]) -> Result<String, AppError> {
let reader = Cursor::new(bytes);
let mut archive = zip::ZipArchive::new(reader).map_err(|_| {
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"message": "docx 文档结构无效，请重新选择文件。",
"field": "contentBase64",
}))
})?;
let mut document_xml = String::new();
archive
.by_name("word/document.xml")
.map_err(|_| {
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"message": "docx 文档缺少正文内容。",
"field": "contentBase64",
}))
})?
.read_to_string(&mut document_xml)
.map_err(|_| {
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"message": "docx 文档正文读取失败。",
"field": "contentBase64",
}))
})?;
Ok(extract_docx_visible_text(document_xml.as_str()))
}
fn extract_docx_visible_text(xml: &str) -> String {
let mut output = String::new();
let mut cursor = 0usize;
while let Some(start_offset) = xml[cursor..].find("<w:t") {
let start = cursor + start_offset;
let Some(tag_end_offset) = xml[start..].find('>') else {
break;
};
let text_start = start + tag_end_offset + 1;
let Some(end_offset) = xml[text_start..].find("</w:t>") else {
break;
};
let text_end = text_start + end_offset;
output.push_str(&decode_xml_text(&xml[text_start..text_end]));
cursor = text_end + "</w:t>".len();
if let Some(next_break) = xml[cursor..].find("<w:br") {
if next_break == 0 {
output.push('\n');
}
}
}
output
}
fn decode_xml_text(value: &str) -> String {
value
.replace("&lt;", "<")
.replace("&gt;", ">")
.replace("&quot;", "\"")
.replace("&apos;", "'")
.replace("&amp;", "&")
}
fn normalize_document_text(value: &str) -> String {
value
.trim_start_matches('\u{feff}')

1434
server-rs/crates/api-server/src/creative_agent.rs Normal file
View File

File diff suppressed because it is too large Load Diff

69
server-rs/crates/api-server/src/creative_agent_sse.rs Normal file
View File

@@ -0,0 +1,69 @@
use axum::response::sse::Event;
use serde::Serialize;
use serde_json::{Value, json};
use shared_contracts::creative_agent::{CreativeAgentErrorEvent, CreativeAgentSseEventType};
pub fn creative_sse_json_event<T>(event: CreativeAgentSseEventType, payload: T) -> Event
where
T: Serialize,
{
let event_name = creative_event_name(event);
match serde_json::to_value(payload)
.ok()
.and_then(|value| Event::default().event(event_name).json_data(value).ok())
{
Some(event) => event,
None => creative_sse_error_event(None, "SSE_SERIALIZE_FAILED", "SSE payload 序列化失败"),
}
}
pub fn creative_sse_json_value_event(event_name: &str, payload: Value) -> Event {
Event::default()
.event(event_name)
.json_data(payload)
.unwrap_or_else(|_| {
creative_sse_error_event(None, "SSE_SERIALIZE_FAILED", "SSE payload 序列化失败")
})
}
pub fn creative_sse_error_event(
session_id: Option<String>,
code: impl Into<String>,
message: impl Into<String>,
) -> Event {
let payload = serde_json::to_string(&CreativeAgentErrorEvent {
session_id,
code: code.into(),
message: message.into(),
recoverable: false,
})
.unwrap_or_else(|_| {
json!({
"sessionId": null,
"code": "SSE_ERROR_SERIALIZE_FAILED",
"message": "SSE 错误事件序列化失败",
"recoverable": false,
})
.to_string()
});
Event::default().event("error").data(payload)
}
fn creative_event_name(event: CreativeAgentSseEventType) -> &'static str {
match event {
CreativeAgentSseEventType::Stage => "stage",
CreativeAgentSseEventType::AgentMessageDelta => "agent_message_delta",
CreativeAgentSseEventType::ThoughtSummaryDelta => "thought_summary_delta",
CreativeAgentSseEventType::PuzzleTemplateCatalog => "puzzle_template_catalog",
CreativeAgentSseEventType::PuzzleTemplateSelection => "puzzle_template_selection",
CreativeAgentSseEventType::PuzzleCostRange => "puzzle_cost_range",
CreativeAgentSseEventType::PuzzleLevelPlan => "puzzle_level_plan",
CreativeAgentSseEventType::ToolStarted => "tool_started",
CreativeAgentSseEventType::ToolCompleted => "tool_completed",
CreativeAgentSseEventType::Reflection => "reflection",
CreativeAgentSseEventType::TargetSession => "target_session",
CreativeAgentSseEventType::Session => "session",
CreativeAgentSseEventType::Error => "error",
CreativeAgentSseEventType::Done => "done",
}
}

6
server-rs/crates/api-server/src/http_error.rs
View File

@@ -89,6 +89,12 @@ impl IntoResponse for AppError {
}
}
impl From<AppError> for Response {
fn from(error: AppError) -> Self {
error.into_response()
}
}
fn resolve_http_error(status_code: StatusCode) -> (&'static str, &'static str) {
match status_code {
StatusCode::BAD_REQUEST => ("BAD_REQUEST", "请求参数不合法"),

1
server-rs/crates/api-server/src/llm_model_routing.rs
View File

@@ -1,2 +1,3 @@
pub(crate) const RPG_STORY_LLM_MODEL: &str = "doubao-seed-character-251128";
pub(crate) const CREATION_TEMPLATE_LLM_MODEL: &str = "deepseek-v3-2-251201";
pub(crate) const PUZZLE_LEVEL_NAME_VISION_LLM_MODEL: &str = "gpt-4o-mini";

133
server-rs/crates/api-server/src/main.rs
View File

@@ -23,6 +23,8 @@ mod creation_agent_anchor_templates;
mod creation_agent_chat;
mod creation_agent_document_input;
mod creation_agent_llm_turn;
mod creative_agent;
mod creative_agent_sse;
mod custom_world;
mod custom_world_agent_entities;
mod custom_world_agent_turn;
@@ -66,11 +68,15 @@ mod square_hole_agent_turn;
mod state;
mod story_battles;
mod story_sessions;
mod vector_engine_audio_generation;
mod visual_novel;
mod volcengine_speech;
mod wechat_auth;
mod wechat_provider;
mod work_author;
use shared_logging::init_tracing;
use std::{collections::HashSet, env, fs, io, panic, thread};
use tokio::net::TcpListener;
use tokio::runtime::Builder as TokioRuntimeBuilder;
use tracing::info;
@@ -79,30 +85,30 @@ use crate::{app::build_router, config::AppConfig, state::AppState};
const API_SERVER_STARTUP_STACK_SIZE_BYTES: usize = 32 * 1024 * 1024;
fn main() -> Result<(), std::io::Error> {
fn main() -> Result<(), io::Error> {
// Windows 本地调试下 Axum 路由树和启动恢复链较重，显式放大启动线程栈，避免 debug 构建在进入监听前栈溢出。
std::thread::Builder::new()
let server_thread = thread::Builder::new()
.name("api-server-bootstrap".to_string())
.stack_size(API_SERVER_STARTUP_STACK_SIZE_BYTES)
.spawn(run_api_server_with_runtime)?
.join()
.map_err(|_| std::io::Error::other("api-server 启动线程异常退出"))?
.spawn(|| {
TokioRuntimeBuilder::new_multi_thread()
.enable_all()
.thread_name("api-server-worker")
.thread_stack_size(API_SERVER_STARTUP_STACK_SIZE_BYTES)
.build()?
.block_on(run_server())
})?;
match server_thread.join() {
Ok(result) => result,
Err(payload) => panic::resume_unwind(payload),
}
}
fn run_api_server_with_runtime() -> Result<(), std::io::Error> {
TokioRuntimeBuilder::new_multi_thread()
.enable_all()
.thread_name("api-server-worker")
.thread_stack_size(API_SERVER_STARTUP_STACK_SIZE_BYTES)
.build()?
.block_on(run_api_server())
}
async fn run_api_server() -> Result<(), std::io::Error> {
// 运行本地开发与联调时，优先从仓库根目录加载本地变量，避免手工逐项导出 OSS / APIMart 配置。
let _ = dotenvy::from_filename(".env.secrets.local");
let _ = dotenvy::from_filename(".env.local");
let _ = dotenvy::from_filename(".env");
async fn run_server() -> Result<(), io::Error> {
// 运行本地开发与联调时，优先从仓库根目录加载本地变量。
// 只尊重外层 shell 先注入的变量；后续本地文件需要能覆盖前序本地文件。
load_local_env_files();
// 统一先从配置对象读取监听地址，避免后续把环境变量读取散落到入口和路由层。
let config = AppConfig::from_env();
@@ -120,3 +126,92 @@ async fn run_api_server() -> Result<(), std::io::Error> {
axum::serve(listener, router).await
}
fn load_local_env_files() {
let shell_env_keys = env::vars().map(|(key, _)| key).collect::<HashSet<_>>();
for path in [".env", ".env.local", ".env.secrets.local"] {
load_env_file(path, &shell_env_keys);
}
}
fn load_env_file(path: &str, shell_env_keys: &HashSet<String>) {
let Ok(raw_text) = fs::read_to_string(path) else {
return;
};
let raw_text = raw_text.trim_start_matches('\u{feff}');
for raw_line in raw_text.split('\n') {
let line = raw_line.trim();
if line.is_empty() || line.starts_with('#') {
continue;
}
let Some((raw_key, raw_value)) = line.split_once('=') else {
continue;
};
let key = raw_key.trim().trim_start_matches('\u{feff}');
if !is_valid_env_key(key) || shell_env_keys.contains(key) {
continue;
}
// 这里只在启动前、Tokio runtime 创建前写入进程环境，避免并发读写 env。
unsafe {
env::set_var(key, strip_env_value(raw_value));
}
}
}
fn strip_env_value(raw_value: &str) -> String {
let value = raw_value.trim_end_matches('\r');
if value.len() >= 2 {
let bytes = value.as_bytes();
let first = bytes[0];
let last = bytes[value.len() - 1];
if (first == b'"' && last == b'"') || (first == b'\'' && last == b'\'') {
return value[1..value.len() - 1].to_string();
}
}
value.to_string()
}
fn is_valid_env_key(key: &str) -> bool {
let mut chars = key.chars();
match chars.next() {
Some(first) if first == '_' || first.is_ascii_alphabetic() => {}
_ => return false,
}
chars.all(|ch| ch == '_' || ch.is_ascii_alphanumeric())
}
#[cfg(test)]
mod tests {
use super::{is_valid_env_key, strip_env_value};
#[test]
fn strip_env_value_removes_wrapping_quotes() {
assert_eq!(strip_env_value("\"true\""), "true");
assert_eq!(strip_env_value("'aliyun'"), "aliyun");
assert_eq!(strip_env_value("plain\r"), "plain");
}
#[test]
fn load_env_key_can_strip_utf8_bom_prefix() {
let key = "\u{feff}SMS_AUTH_ENABLED"
.trim()
.trim_start_matches('\u{feff}');
assert_eq!(key, "SMS_AUTH_ENABLED");
}
#[test]
fn is_valid_env_key_accepts_dotenv_key_subset() {
assert!(is_valid_env_key("SMS_AUTH_ENABLED"));
assert!(is_valid_env_key("_LOCAL_KEY_1"));
assert!(!is_valid_env_key("1_BAD"));
assert!(!is_valid_env_key("BAD-KEY"));
}
}

2
server-rs/crates/api-server/src/openai_image_generation.rs
View File

@@ -177,6 +177,7 @@ pub(crate) fn build_openai_image_request_body(
Value::String(build_prompt_with_negative(prompt, negative_prompt)),
),
("n".to_string(), json!(candidate_count.clamp(1, 4))),
("official_fallback".to_string(), Value::Bool(true)),
(
"size".to_string(),
Value::String(normalize_image_size(size)),
@@ -613,6 +614,7 @@ mod tests {
assert_eq!(body["model"], GPT_IMAGE_2_MODEL);
assert_eq!(body["size"], "16:9");
assert_eq!(body["n"], 2);
assert_eq!(body["official_fallback"], true);
assert_eq!(body["image_urls"][0], "data:image/png;base64,abcd");
assert!(body["prompt"].as_str().unwrap_or_default().contains("避免"));
}

1
server-rs/crates/api-server/src/prompt/mod.rs
View File

@@ -5,6 +5,7 @@ pub(crate) mod puzzle;
pub(crate) mod rpg;
pub(crate) mod scene_background;
pub(crate) mod square_hole;
pub(crate) mod visual_novel;
pub(crate) use rpg::agent_chat;
pub(crate) use rpg::foundation_draft;

17
server-rs/crates/api-server/src/prompt/puzzle/level_name.rs
View File

@@ -3,7 +3,7 @@
/// 模型只负责把画面描述压缩成可直接展示的中文关卡名；写回草稿和作品卡由业务路由处理。
pub(crate) const PUZZLE_FIRST_LEVEL_NAME_SYSTEM_PROMPT: &str = r#"你是一个中文拼图关卡命名编辑。
你会收到拼图第一关的画面描述。请生成 1 个适合直接展示在游戏关卡卡片上的中文关卡名。
你会收到拼图第一关的画面描述，部分请求还会附带已经生成完成的正式图片。请综合图片内容和画面描述，生成 1 个适合直接展示在游戏关卡卡片上的中文关卡名。
硬约束：
1. 只输出 JSON，不要输出 Markdown、解释或代码块。
@@ -21,6 +21,13 @@ pub(crate) fn build_puzzle_first_level_name_user_prompt(picture_description: &st
)
}
pub(crate) fn build_puzzle_first_level_name_vision_user_text(picture_description: &str) -> String {
format!(
"画面描述：{picture_description}\n\n请观察随消息附带的正式拼图图片，生成第一关关卡名。",
picture_description = picture_description.trim(),
)
}
#[cfg(test)]
mod tests {
use super::*;
@@ -32,4 +39,12 @@ mod tests {
assert!(prompt.contains("画面描述：一只猫在雨夜灯牌下回头。"));
assert!(prompt.contains("第一关关卡名"));
}
#[test]
fn level_name_vision_prompt_mentions_generated_image() {
let prompt = build_puzzle_first_level_name_vision_user_text("一只猫在雨夜灯牌下回头。");
assert!(prompt.contains("画面描述：一只猫在雨夜灯牌下回头。"));
assert!(prompt.contains("正式拼图图片"));
}
}

690
server-rs/crates/api-server/src/prompt/visual_novel.rs Normal file
View File

@@ -0,0 +1,690 @@
#![allow(dead_code)]
use platform_llm::{LlmMessage, LlmTextRequest};
use serde_json::{Value as JsonValue, json};
use shared_contracts::visual_novel::{VisualNovelResultDraft, VisualNovelRuntimeStep};
use crate::llm_model_routing::CREATION_TEMPLATE_LLM_MODEL;
pub(crate) const VISUAL_NOVEL_CREATION_SYSTEM_PROMPT: &str = r#"你是百梦平台内的视觉小说模板创作导演。
你的任务是把用户的一句话、文档摘要或空白创建意图，生成一份可以进入结果页继续编辑的 VisualNovelResultDraft。
硬约束：
1. 只能输出一个 JSON 对象，不要输出 Markdown、代码块、解释或 UI 规则说明。
2. 输出内容必须是中文视觉小说底稿，补齐世界观、玩家身份、角色、场景、剧情阶段和开场。
3. 每个角色必须有可生成立绘的 appearance，每个场景必须有可生成背景图的 description。
4. sourceMode 必须沿用输入的 idea、document 或 blank。
5. 图片、音乐、文档只能写平台资产引用或 null，不能写大段 data URL。
6. 不要输出旧 TXT 播放记录、分享播放包、外部商业、运营、活动、展示横幅、交易或独立账号字段。
7. 不要发明第二套存档、发布、钱包、广场或资产系统。
8. publishReady 只有在 opening 场景、主要角色、剧情阶段和 2 到 4 个 initialChoices 都齐备时才可以为 true。
"#;
pub(crate) const VISUAL_NOVEL_RUNTIME_GM_SYSTEM_PROMPT: &str = r#"你是百梦视觉小说运行时 GM。
你的任务是读取作品底稿、当前 run snapshot、玩家动作和最近历史，然后输出下一轮 VisualNovelRuntimeStep[]。
硬约束：
1. 只能输出一个 JSON 数组，不要输出对象包裹、Markdown、代码块、解释或 UI 规则说明。
2. 每轮 step 数量不能超过输入的 maxAssistantStepCountPerTurn。
3. 场景变化必须先输出 scene_change。
4. 旁白使用 narration，角色说话使用 dialogue，转场使用 transition。
5. 需要玩家选择时必须输出 choice，choice 内每项必须有 choiceId 和 text。
6. 关键剧情事实变化使用 flag，数值倾向变化使用 metric。
7. 不要让前端从 raw_text 猜业务 step，不要输出未定义 step 类型。
8. 不要输出旧 TXT 播放记录、分享播放包、屏幕记录、外部商业、运营、活动或独立保存元数据。
"#;
pub(crate) const VISUAL_NOVEL_REPAIR_SYSTEM_PROMPT: &str = r#"你是视觉小说结构化输出修复器。
你的任务是把上一次模型输出修复为目标 JSON 契约。
硬约束：
1. 只能输出目标 JSON，不要解释错误原因。
2. 不能新增目标契约之外的字段。
3. 不要把普通历史、运行事件或 raw_text 改写成旧 TXT 播放包、屏幕记录或分享片段。
4. 如果原文缺失必要信息，只补最小可运行占位值，并保持中文内容。
"#;
const VISUAL_NOVEL_CREATION_OUTPUT_CONTRACT: &str = r#"{
"profileId": null,
"workTitle": "",
"workDescription": "",
"workTags": [],
"coverImageSrc": null,
"sourceMode": "idea",
"sourceAssetIds": [],
"world": {
"title": "",
"summary": "",
"background": "",
"premise": "",
"literaryStyle": "",
"playerRole": "",
"defaultTone": ""
},
"characters": [
{
"characterId": "char-main-1",
"name": "",
"gender": null,
"role": "main",
"appearance": "",
"personality": "",
"tone": "",
"background": "",
"relationshipToPlayer": "",
"imageAssets": [],
"defaultExpression": null,
"isPlayerVisible": false
}
],
"scenes": [
{
"sceneId": "scene-opening",
"name": "",
"description": "",
"backgroundImageSrc": null,
"musicSrc": null,
"ambientSoundSrc": null,
"availability": "opening",
"phaseIds": []
}
],
"storyPhases": [
{
"phaseId": "phase-opening",
"title": "",
"goal": "",
"summary": "",
"entryCondition": "",
"exitCondition": "",
"sceneIds": ["scene-opening"],
"characterIds": ["char-main-1"],
"suggestedChoices": []
}
],
"opening": {
"sceneId": "scene-opening",
"narration": "",
"speakerCharacterId": null,
"firstDialogue": null,
"initialChoices": [
{ "choiceId": "choice-opening-1", "text": "", "actionHint": null },
{ "choiceId": "choice-opening-2", "text": "", "actionHint": null }
]
},
"runtimeConfig": {
"textModeEnabled": true,
"defaultTextMode": false,
"maxHistoryEntries": 80,
"maxAssistantStepCountPerTurn": 8,
"allowFreeTextAction": true,
"allowHistoryRegeneration": true,
"attributePanelMode": "off",
"saveArchiveEnabled": true
},
"publishReady": false,
"validationIssues": [],
"updatedAt": "ISO-8601"
}"#;
const VISUAL_NOVEL_RUNTIME_OUTPUT_CONTRACT: &str = r#"[
{ "type": "scene_change", "sceneId": "scene-opening", "backgroundImageSrc": null, "musicSrc": null },
{ "type": "narration", "text": "" },
{ "type": "dialogue", "characterId": "char-main-1", "characterName": "", "expression": null, "text": "" },
{ "type": "transition", "transitionKind": "fade", "text": null },
{ "type": "flag", "key": "", "value": true },
{ "type": "metric", "key": "", "delta": 1 },
{ "type": "choice", "choices": [{ "choiceId": "choice-next-1", "text": "", "actionHint": null }] }
]"#;
#[derive(Clone, Debug)]
pub(crate) struct VisualNovelCreationPromptParams<'a> {
pub(crate) source_mode: &'a str,
pub(crate) seed_text: Option<&'a str>,
pub(crate) source_asset_ids: &'a [String],
pub(crate) document_summary: Option<&'a str>,
pub(crate) current_draft: Option<&'a JsonValue>,
pub(crate) recent_messages: &'a [JsonValue],
pub(crate) now_iso: &'a str,
}
#[derive(Clone, Debug)]
pub(crate) struct VisualNovelRuntimePromptParams<'a> {
pub(crate) work_profile: &'a JsonValue,
pub(crate) run_snapshot: &'a JsonValue,
pub(crate) runtime_action: &'a JsonValue,
pub(crate) recent_history: &'a [JsonValue],
pub(crate) max_assistant_step_count_per_turn: u32,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum VisualNovelRepairTarget {
ResultDraft,
RuntimeSteps,
}
impl VisualNovelRepairTarget {
fn label(self) -> &'static str {
match self {
Self::ResultDraft => "VisualNovelResultDraft",
Self::RuntimeSteps => "VisualNovelRuntimeStep[]",
}
}
fn contract(self) -> &'static str {
match self {
Self::ResultDraft => VISUAL_NOVEL_CREATION_OUTPUT_CONTRACT,
Self::RuntimeSteps => VISUAL_NOVEL_RUNTIME_OUTPUT_CONTRACT,
}
}
}
#[derive(Clone, Debug)]
pub(crate) struct VisualNovelRepairPromptParams<'a> {
pub(crate) target: VisualNovelRepairTarget,
pub(crate) raw_text: &'a str,
pub(crate) parse_error: &'a str,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) struct VisualNovelPromptParseFailure {
pub(crate) target: VisualNovelRepairTarget,
pub(crate) message: String,
}
impl VisualNovelPromptParseFailure {
pub(crate) fn retryable_message(&self) -> String {
format!(
"{} 输出结构不可解析，可重试或进入 repair：{}",
self.target.label(),
self.message
)
}
}
#[derive(Clone, Debug, PartialEq)]
pub(crate) struct VisualNovelToolDescriptor {
pub(crate) name: &'static str,
pub(crate) description: &'static str,
pub(crate) input_schema: JsonValue,
}
pub(crate) fn build_visual_novel_creation_user_prompt(
params: VisualNovelCreationPromptParams<'_>,
) -> String {
json!({
"task": "generate_visual_novel_result_draft",
"sourceMode": params.source_mode,
"seedText": params.seed_text.unwrap_or("").trim(),
"sourceAssetIds": params.source_asset_ids,
"documentSummary": params.document_summary.unwrap_or("").trim(),
"currentDraft": params.current_draft,
"recentMessages": params.recent_messages,
"nowIso": params.now_iso,
"draftRequirements": {
"mainCharacters": "3 到 6 个，至少 1 个非玩家主要角色",
"scenes": "3 到 8 个，至少 1 个 opening 场景",
"storyPhases": "3 到 6 个，第一阶段可从 opening 进入",
"initialChoices": "2 到 4 个",
"runtimeConfigDefaults": "沿用契约默认值，attributePanelMode 默认为 off"
},
"outputContract": VISUAL_NOVEL_CREATION_OUTPUT_CONTRACT
})
.to_string()
}
pub(crate) fn build_visual_novel_runtime_user_prompt(
params: VisualNovelRuntimePromptParams<'_>,
) -> String {
json!({
"task": "generate_visual_novel_runtime_steps",
"workProfile": params.work_profile,
"runSnapshot": params.run_snapshot,
"runtimeAction": params.runtime_action,
"recentHistory": params.recent_history,
"maxAssistantStepCountPerTurn": params.max_assistant_step_count_per_turn,
"runtimeRules": [
"只以 step 数组作为正式业务输出",
"当前选择项必须来自 runSnapshot.availableChoices 或由本轮 choice step 重新给出",
"如果玩家自由输入改变事实，必须用 flag 或 metric 表达可持久化变化",
"不要在输出中夹带 raw_text、debug、prompt、historyPlayback 或平台运营字段"
],
"outputContract": VISUAL_NOVEL_RUNTIME_OUTPUT_CONTRACT
})
.to_string()
}
pub(crate) fn build_visual_novel_repair_user_prompt(
params: VisualNovelRepairPromptParams<'_>,
) -> String {
json!({
"task": "repair_visual_novel_structured_output",
"target": params.target.label(),
"parseError": params.parse_error,
"rawText": params.raw_text,
"outputContract": params.target.contract()
})
.to_string()
}
pub(crate) fn build_visual_novel_creation_llm_request(
params: VisualNovelCreationPromptParams<'_>,
enable_web_search: bool,
) -> LlmTextRequest {
LlmTextRequest::new(vec![
LlmMessage::system(VISUAL_NOVEL_CREATION_SYSTEM_PROMPT),
LlmMessage::user(build_visual_novel_creation_user_prompt(params)),
])
.with_model(CREATION_TEMPLATE_LLM_MODEL)
.with_responses_api()
.with_web_search(enable_web_search)
}
pub(crate) fn build_visual_novel_runtime_llm_request(
params: VisualNovelRuntimePromptParams<'_>,
) -> LlmTextRequest {
LlmTextRequest::new(vec![
LlmMessage::system(VISUAL_NOVEL_RUNTIME_GM_SYSTEM_PROMPT),
LlmMessage::user(build_visual_novel_runtime_user_prompt(params)),
])
.with_model(CREATION_TEMPLATE_LLM_MODEL)
.with_responses_api()
}
pub(crate) fn build_visual_novel_repair_llm_request(
params: VisualNovelRepairPromptParams<'_>,
) -> LlmTextRequest {
LlmTextRequest::new(vec![
LlmMessage::system(VISUAL_NOVEL_REPAIR_SYSTEM_PROMPT),
LlmMessage::user(build_visual_novel_repair_user_prompt(params)),
])
.with_model(CREATION_TEMPLATE_LLM_MODEL)
.with_responses_api()
}
pub(crate) fn visual_novel_tool_descriptors() -> Vec<VisualNovelToolDescriptor> {
vec![
VisualNovelToolDescriptor {
name: "visual_novel_apply_creation_action",
description: "执行视觉小说创作 action，写回 VisualNovelResultDraft 或编译平台 work profile 草稿。",
input_schema: json!({
"type": "object",
"required": ["kind"],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"generate_draft",
"patch_world",
"patch_character",
"patch_scene",
"patch_story_phase",
"compile_work_profile"
]
},
"targetId": { "type": ["string", "null"] },
"payload": { "type": "object", "additionalProperties": true }
}
}),
},
VisualNovelToolDescriptor {
name: "visual_novel_generate_image_asset",
description: "为视觉小说角色立绘或场景背景生成图片，并返回平台资产引用。",
input_schema: json!({
"type": "object",
"required": ["kind", "targetId", "prompt"],
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": ["generate_scene_image", "generate_character_image"]
},
"targetId": { "type": "string", "minLength": 1 },
"prompt": { "type": "string", "minLength": 1 },
"styleHints": { "type": "array", "items": { "type": "string" } },
"sourceImageAssetId": { "type": ["string", "null"] }
}
}),
},
]
}
pub(crate) fn parse_visual_novel_result_draft_fixture(
text: &str,
) -> Result<VisualNovelResultDraft, VisualNovelPromptParseFailure> {
let value = extract_json_root(
text,
JsonRootShape::Object,
VisualNovelRepairTarget::ResultDraft,
)?;
serde_json::from_value(value).map_err(|error| VisualNovelPromptParseFailure {
target: VisualNovelRepairTarget::ResultDraft,
message: error.to_string(),
})
}
pub(crate) fn parse_visual_novel_runtime_steps_fixture(
text: &str,
) -> Result<Vec<VisualNovelRuntimeStep>, VisualNovelPromptParseFailure> {
let value = extract_json_root(
text,
JsonRootShape::Array,
VisualNovelRepairTarget::RuntimeSteps,
)?;
serde_json::from_value(value).map_err(|error| VisualNovelPromptParseFailure {
target: VisualNovelRepairTarget::RuntimeSteps,
message: error.to_string(),
})
}
#[derive(Clone, Copy)]
enum JsonRootShape {
Object,
Array,
}
fn extract_json_root(
text: &str,
shape: JsonRootShape,
target: VisualNovelRepairTarget,
) -> Result<JsonValue, VisualNovelPromptParseFailure> {
let trimmed = strip_json_code_fence(text.trim());
if let Ok(value) = serde_json::from_str::<JsonValue>(trimmed) {
return Ok(value);
}
let (start_char, end_char) = match shape {
JsonRootShape::Object => ('{', '}'),
JsonRootShape::Array => ('[', ']'),
};
let start = trimmed.find(start_char);
let end = trimmed.rfind(end_char);
match (start, end) {
(Some(start), Some(end)) if end > start => {
serde_json::from_str::<JsonValue>(&trimmed[start..=end]).map_err(|error| {
VisualNovelPromptParseFailure {
target,
message: error.to_string(),
}
})
}
_ => Err(VisualNovelPromptParseFailure {
target,
message: format!("未找到目标 JSON {}", target.label()),
}),
}
}
fn strip_json_code_fence(text: &str) -> &str {
let trimmed = text.trim();
if !trimmed.starts_with("```") {
return trimmed;
}
let without_start = trimmed
.strip_prefix("```json")
.or_else(|| trimmed.strip_prefix("```JSON"))
.or_else(|| trimmed.strip_prefix("```"))
.unwrap_or(trimmed)
.trim();
without_start
.strip_suffix("```")
.unwrap_or(without_start)
.trim()
}
#[cfg(test)]
mod tests {
use platform_llm::LlmTextProtocol;
use serde_json::json;
use super::*;
fn source_asset_ids() -> Vec<String> {
vec!["asset-doc-1".to_string()]
}
fn creation_params<'a>(source_asset_ids: &'a [String]) -> VisualNovelCreationPromptParams<'a> {
VisualNovelCreationPromptParams {
source_mode: "idea",
seed_text: Some("雨夜里，只在午夜出现的书店会归还人们遗失的名字。"),
source_asset_ids,
document_summary: None,
current_draft: None,
recent_messages: &[],
now_iso: "2026-05-05T12:00:00Z",
}
}
fn runtime_params<'a>(
work_profile: &'a JsonValue,
run_snapshot: &'a JsonValue,
runtime_action: &'a JsonValue,
) -> VisualNovelRuntimePromptParams<'a> {
VisualNovelRuntimePromptParams {
work_profile,
run_snapshot,
runtime_action,
recent_history: &[],
max_assistant_step_count_per_turn: 8,
}
}
fn sample_draft() -> JsonValue {
json!({
"profileId": null,
"workTitle": "雨夜书店",
"workDescription": "一名失去名字的读者在午夜书店寻找真相。",
"workTags": ["悬疑", "治愈"],
"coverImageSrc": null,
"sourceMode": "idea",
"sourceAssetIds": [],
"world": {
"title": "雨夜书店",
"summary": "午夜书店会收留遗失名字的人。",
"background": "旧城区尽头有一家只在雨夜开门的书店，书架保存着人们遗忘的片段。",
"premise": "玩家要在天亮前找回自己的名字。",
"literaryStyle": "细腻、克制、轻悬疑",
"playerRole": "失去名字的读者",
"defaultTone": "雨夜、温柔、隐秘"
},
"characters": [
{
"characterId": "char-keeper",
"name": "林栖",
"gender": "女",
"role": "main",
"appearance": "银灰短发，深绿围裙，手中常拿一盏铜灯，适合半身立绘。",
"personality": "温和但不轻易透露真相",
"tone": "低声、像在翻旧书",
"background": "午夜书店的看守者。",
"relationshipToPlayer": "知道玩家名字的一部分。",
"imageAssets": [],
"defaultExpression": "calm",
"isPlayerVisible": false
}
],
"scenes": [
{
"sceneId": "scene-bookstore",
"name": "午夜书店",
"description": "窄巷尽头的木门半开，暖黄灯光落在潮湿石板上，室内书架高而幽深。",
"backgroundImageSrc": null,
"musicSrc": null,
"ambientSoundSrc": null,
"availability": "opening",
"phaseIds": ["phase-opening"]
}
],
"storyPhases": [
{
"phaseId": "phase-opening",
"title": "失名之夜",
"goal": "确认玩家为何失去名字",
"summary": "玩家进入书店，与林栖第一次交谈。",
"entryCondition": "opening",
"exitCondition": "找到第一张名字书签",
"sceneIds": ["scene-bookstore"],
"characterIds": ["char-keeper"],
"suggestedChoices": ["询问书店来历", "查看柜台上的旧书"]
}
],
"opening": {
"sceneId": "scene-bookstore",
"narration": "雨水顺着伞尖落下时，你发现门牌上的字正在一点点亮起。",
"speakerCharacterId": "char-keeper",
"firstDialogue": "你终于来了。名字丢失的人，总会先听见这场雨。",
"initialChoices": [
{ "choiceId": "choice-ask-name", "text": "询问自己的名字在哪里", "actionHint": "向林栖确认线索" },
{ "choiceId": "choice-look-book", "text": "查看柜台上的旧书", "actionHint": "寻找名字书签" }
]
},
"runtimeConfig": {
"textModeEnabled": true,
"defaultTextMode": false,
"maxHistoryEntries": 80,
"maxAssistantStepCountPerTurn": 8,
"allowFreeTextAction": true,
"allowHistoryRegeneration": true,
"attributePanelMode": "off",
"saveArchiveEnabled": true
},
"publishReady": true,
"validationIssues": [],
"updatedAt": "2026-05-05T12:00:00Z"
})
}
#[test]
fn creation_fixture_parses_as_visual_novel_result_draft() {
let raw_text = format!("模型输出如下：\n{}", sample_draft());
let draft = parse_visual_novel_result_draft_fixture(raw_text.as_str())
.expect("draft fixture should parse");
assert_eq!(draft.work_title, "雨夜书店");
assert_eq!(draft.characters[0].character_id, "char-keeper");
assert_eq!(draft.opening.initial_choices.len(), 2);
}
#[test]
fn runtime_fixture_parses_as_typed_steps() {
let raw_text = json!([
{ "type": "scene_change", "sceneId": "scene-bookstore", "backgroundImageSrc": null, "musicSrc": null },
{ "type": "narration", "text": "门铃轻响，雨声像被书页吸走。" },
{ "type": "dialogue", "characterId": "char-keeper", "characterName": "林栖", "expression": "calm", "text": "先别急着找答案，先告诉我你还记得什么。" },
{ "type": "flag", "key": "met_keeper", "value": true },
{ "type": "metric", "key": "keeper_trust", "delta": 1 },
{
"type": "choice",
"choices": [
{ "choiceId": "choice-tell-memory", "text": "说出最后记得的街名", "actionHint": "提供线索" },
{ "choiceId": "choice-stay-silent", "text": "保持沉默观察她", "actionHint": "观察林栖反应" }
]
}
])
.to_string();
let steps = parse_visual_novel_runtime_steps_fixture(raw_text.as_str())
.expect("runtime fixture should parse");
assert_eq!(steps.len(), 6);
assert!(matches!(
steps[0],
VisualNovelRuntimeStep::SceneChange { .. }
));
assert!(matches!(steps[5], VisualNovelRuntimeStep::Choice { .. }));
}
#[test]
fn bad_runtime_output_can_enter_repair_prompt() {
let failure = parse_visual_novel_runtime_steps_fixture("林栖说：欢迎来到书店。")
.expect_err("bad output should fail");
let retryable_message = failure.retryable_message();
let repair_prompt = build_visual_novel_repair_user_prompt(VisualNovelRepairPromptParams {
target: failure.target,
raw_text: "林栖说：欢迎来到书店。",
parse_error: failure.message.as_str(),
});
assert!(retryable_message.contains("可重试"));
assert!(repair_prompt.contains("VisualNovelRuntimeStep[]"));
assert!(repair_prompt.contains("林栖说"));
assert!(repair_prompt.contains("scene_change"));
}
#[test]
fn llm_requests_use_responses_template_model() {
let asset_ids = source_asset_ids();
let creation_request =
build_visual_novel_creation_llm_request(creation_params(asset_ids.as_slice()), true);
assert_eq!(
creation_request.model.as_deref(),
Some(CREATION_TEMPLATE_LLM_MODEL)
);
assert_eq!(creation_request.protocol, LlmTextProtocol::Responses);
assert!(creation_request.enable_web_search);
assert!(
creation_request.messages[0]
.content
.contains("VisualNovelResultDraft")
);
assert!(
creation_request.messages[1]
.content
.contains("sourceAssetIds")
);
let work_profile = sample_draft();
let run_snapshot = json!({ "runId": "run-1", "availableChoices": [] });
let runtime_action = json!({ "actionKind": "continue", "clientEventId": "event-1" });
let runtime_request = build_visual_novel_runtime_llm_request(runtime_params(
&work_profile,
&run_snapshot,
&runtime_action,
));
assert_eq!(
runtime_request.model.as_deref(),
Some(CREATION_TEMPLATE_LLM_MODEL)
);
assert_eq!(runtime_request.protocol, LlmTextProtocol::Responses);
assert!(!runtime_request.enable_web_search);
assert!(
runtime_request.messages[0]
.content
.contains("VisualNovelRuntimeStep[]")
);
}
#[test]
fn prompts_and_tools_guard_against_external_platform_fields() {
assert!(VISUAL_NOVEL_CREATION_SYSTEM_PROMPT.contains("外部商业"));
assert!(VISUAL_NOVEL_CREATION_SYSTEM_PROMPT.contains("独立账号"));
assert!(VISUAL_NOVEL_RUNTIME_GM_SYSTEM_PROMPT.contains("独立保存"));
let tools = visual_novel_tool_descriptors();
let tool_payload = serde_json::to_string(&json!(
tools
.iter()
.map(|tool| json!({
"name": tool.name,
"description": tool.description,
"inputSchema": tool.input_schema,
}))
.collect::<Vec<_>>()
))
.expect("tools should serialize");
assert!(tool_payload.contains("generate_scene_image"));
assert!(tool_payload.contains("generate_character_image"));
assert!(tool_payload.contains("compile_work_profile"));
let legacy_playback_marker = format!("{}{}", "re", "play");
assert!(!tool_payload.contains(&legacy_playback_marker));
assert!(!tool_payload.contains(&legacy_playback_marker.to_uppercase()));
}
}

472
server-rs/crates/api-server/src/puzzle.rs
View File

@@ -13,12 +13,13 @@ use axum::{
},
};
use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64_STANDARD};
use image::ImageFormat;
use module_assets::{
AssetObjectAccessPolicy, AssetObjectFieldError, build_asset_entity_binding_input,
build_asset_object_upsert_input, generate_asset_binding_id, generate_asset_object_id,
};
use module_puzzle::{PuzzleGeneratedImageCandidate, PuzzleRuntimeLevelStatus};
use platform_llm::{LlmMessage, LlmTextRequest};
use platform_llm::{LlmMessage, LlmMessageContentPart, LlmTextRequest};
use platform_oss::{
LegacyAssetPrefix, OssHeadObjectRequest, OssObjectAccess, OssPutObjectRequest,
OssSignedGetObjectUrlRequest,
@@ -78,7 +79,7 @@ use crate::{
},
auth::AuthenticatedAccessToken,
http_error::AppError,
llm_model_routing::CREATION_TEMPLATE_LLM_MODEL,
llm_model_routing::{CREATION_TEMPLATE_LLM_MODEL, PUZZLE_LEVEL_NAME_VISION_LLM_MODEL},
platform_errors::map_oss_error,
prompt::puzzle::{
draft::{
@@ -88,6 +89,7 @@ use crate::{
image::{PUZZLE_DEFAULT_NEGATIVE_PROMPT, build_puzzle_image_prompt},
level_name::{
PUZZLE_FIRST_LEVEL_NAME_SYSTEM_PROMPT, build_puzzle_first_level_name_user_prompt,
build_puzzle_first_level_name_vision_user_text,
},
tags::{PUZZLE_TAG_GENERATION_SYSTEM_PROMPT, build_puzzle_tag_generation_user_prompt},
},
@@ -112,6 +114,7 @@ const PUZZLE_ENTITY_KIND: &str = "puzzle_work";
const PUZZLE_GENERATED_IMAGE_SIZE: &str = "1024*1024";
const PUZZLE_APIMART_GENERATED_IMAGE_SIZE: &str = "1:1";
const PUZZLE_APIMART_GEMINI_RESOLUTION: &str = "1K";
const PUZZLE_LEVEL_NAME_VISION_IMAGE_MAX_SIDE: u32 = 768;
pub async fn create_puzzle_agent_session(
State(state): State<AppState>,
@@ -204,7 +207,8 @@ pub async fn generate_puzzle_onboarding_work(
PUZZLE_AGENT_API_BASE_PROVIDER,
map_puzzle_generation_endpoint_error(error),
)
})?;
})?
.into_records();
let selected = candidates.first().cloned().ok_or_else(|| {
puzzle_error_response(
&request_context,
@@ -219,6 +223,7 @@ pub async fn generate_puzzle_onboarding_work(
level_id: "onboarding-level-1".to_string(),
level_name: level_name.clone(),
picture_description: prompt_text.clone(),
picture_reference: None,
candidates,
selected_candidate_id: Some(selected.candidate_id.clone()),
cover_image_src: Some(selected.image_src.clone()),
@@ -706,6 +711,7 @@ pub async fn execute_puzzle_agent_action(
);
let (operation_type, phase_label, phase_detail, session) = match action.as_str() {
"compile_puzzle_draft" => {
let ai_redraw = payload.ai_redraw.unwrap_or(true);
let prompt_text = payload
.picture_description
.as_deref()
@@ -725,33 +731,49 @@ pub async fn execute_puzzle_agent_action(
Ok(next_session_id) => next_session_id,
Err(response) => return Err(response),
};
let session = execute_billable_asset_operation_with_cost(
&state,
&owner_user_id,
"puzzle_initial_image",
&billing_asset_id,
PUZZLE_IMAGE_GENERATION_POINTS_COST,
async {
compile_puzzle_draft_with_initial_cover(
&state,
compile_session_id.clone(),
owner_user_id.clone(),
prompt_text,
payload.reference_image_src.as_deref(),
payload.image_model.as_deref(),
now,
)
.await
},
)
.await
let session = if ai_redraw {
execute_billable_asset_operation_with_cost(
&state,
&owner_user_id,
"puzzle_initial_image",
&billing_asset_id,
PUZZLE_IMAGE_GENERATION_POINTS_COST,
async {
compile_puzzle_draft_with_initial_cover(
&state,
compile_session_id.clone(),
owner_user_id.clone(),
prompt_text,
payload.reference_image_src.as_deref(),
payload.image_model.as_deref(),
now,
)
.await
},
)
.await
} else {
compile_puzzle_draft_with_uploaded_cover(
&state,
compile_session_id.clone(),
owner_user_id.clone(),
prompt_text,
payload.reference_image_src.as_deref(),
now,
)
.await
}
.map_err(|error| {
puzzle_error_response(&request_context, PUZZLE_AGENT_API_BASE_PROVIDER, error)
});
(
"compile_puzzle_draft",
"首关拼图草稿",
"已编译首关草稿、生成首关画面并写入正式草稿。",
if ai_redraw {
"已编译首关草稿、生成首关画面并写入正式草稿。"
} else {
"已编译首关草稿，并直接应用上传图片为第一关图片。"
},
session,
)
}
@@ -846,8 +868,9 @@ pub async fn execute_puzzle_agent_action(
if let Some(levels_json) = levels_json.as_ref() {
draft.levels = parse_puzzle_level_records_from_module_json(levels_json)?;
}
let target_level =
let mut target_level =
select_puzzle_level_for_api(&draft, target_level_id.as_deref())?;
let fallback_level_name = target_level.level_name.clone();
let prompt = resolve_puzzle_level_image_prompt(
payload.prompt_text.as_deref(),
&target_level.picture_description,
@@ -868,10 +891,32 @@ pub async fn execute_puzzle_agent_action(
)
.await
.map_err(map_puzzle_generation_endpoint_error)?;
if candidates.is_empty() {
return Err(AppError::from_status(StatusCode::BAD_GATEWAY).with_details(
json!({
"provider": PUZZLE_AGENT_API_BASE_PROVIDER,
"message": "拼图候选图生成结果为空",
}),
));
}
if let Some(refined_level_name) = generate_puzzle_first_level_name_from_image(
&state,
target_level.picture_description.as_str(),
&candidates[0].downloaded_image,
)
.await
{
target_level.level_name = refined_level_name;
}
let generated_level_name = target_level.level_name.clone();
let levels_json_with_generated_name =
Some(serialize_puzzle_level_records_for_module(
&build_puzzle_levels_with_primary_name(&draft, &target_level),
)?);
let candidates_json = serde_json::to_string(
&candidates
.iter()
.map(to_puzzle_generated_image_candidate)
.map(|candidate| to_puzzle_generated_image_candidate(&candidate.record))
.collect::<Vec<_>>(),
)
.map_err(|error| {
@@ -886,7 +931,7 @@ pub async fn execute_puzzle_agent_action(
session_id: session.session_id.clone(),
owner_user_id: owner_user_id.clone(),
level_id: Some(target_level.level_id.clone()),
levels_json,
levels_json: levels_json_with_generated_name,
candidates_json,
saved_at_micros: now,
})
@@ -907,9 +952,15 @@ pub async fn execute_puzzle_agent_action(
let fallback_session =
replace_puzzle_session_draft_snapshot(session, draft, now);
Ok(apply_generated_puzzle_candidates_to_session_snapshot(
fallback_session,
apply_generated_puzzle_first_level_name_to_session_snapshot(
fallback_session,
target_level.level_id.as_str(),
generated_level_name.as_str(),
fallback_level_name.as_str(),
now,
),
target_level.level_id.as_str(),
candidates,
candidates.into_records(),
now,
))
}
@@ -1980,6 +2031,7 @@ fn map_puzzle_draft_level_response(level: PuzzleDraftLevelRecord) -> PuzzleDraft
level_id: level.level_id,
level_name: level.level_name,
picture_description: level.picture_description,
picture_reference: level.picture_reference,
candidates: level
.candidates
.into_iter()
@@ -2519,6 +2571,7 @@ fn parse_puzzle_level_records_from_module_json(
level_id: level.level_id,
level_name: level.level_name,
picture_description: level.picture_description,
picture_reference: level.picture_reference,
candidates: level
.candidates
.into_iter()
@@ -2685,6 +2738,7 @@ fn serialize_puzzle_levels_response(
"level_id": level.level_id,
"level_name": level.level_name,
"picture_description": level.picture_description,
"picture_reference": level.picture_reference,
"candidates": level
.candidates
.iter()
@@ -2809,6 +2863,91 @@ async fn generate_puzzle_first_level_name(state: &AppState, picture_description:
build_fallback_puzzle_first_level_name(picture_description)
}
async fn generate_puzzle_first_level_name_from_image(
state: &AppState,
picture_description: &str,
image: &PuzzleDownloadedImage,
) -> Option<String> {
let Some(llm_client) = state.creative_agent_gpt5_client() else {
return None;
};
let Some(image_data_url) = build_puzzle_level_name_image_data_url(image) else {
tracing::warn!(
provider = PUZZLE_AGENT_API_BASE_PROVIDER,
picture_chars = picture_description.chars().count(),
"拼图首关名图片输入压缩失败，保留文本关卡名"
);
return None;
};
let user_text = build_puzzle_first_level_name_vision_user_text(picture_description);
let response = llm_client
.request_text(
LlmTextRequest::new(vec![
LlmMessage::system(PUZZLE_FIRST_LEVEL_NAME_SYSTEM_PROMPT),
LlmMessage::user_multimodal(vec![
LlmMessageContentPart::InputText { text: user_text },
LlmMessageContentPart::InputImage {
image_url: image_data_url,
},
]),
])
.with_model(PUZZLE_LEVEL_NAME_VISION_LLM_MODEL)
.with_max_tokens(80),
)
.await;
match response {
Ok(response) => {
parse_puzzle_first_level_name_from_text(response.content.as_str()).or_else(|| {
tracing::warn!(
provider = PUZZLE_AGENT_API_BASE_PROVIDER,
model = PUZZLE_LEVEL_NAME_VISION_LLM_MODEL,
picture_chars = picture_description.chars().count(),
"拼图首关名视觉模型返回非法，保留文本关卡名"
);
None
})
}
Err(error) => {
tracing::warn!(
provider = PUZZLE_AGENT_API_BASE_PROVIDER,
model = PUZZLE_LEVEL_NAME_VISION_LLM_MODEL,
picture_chars = picture_description.chars().count(),
error = %error,
"拼图首关名视觉生成失败，保留文本关卡名"
);
None
}
}
}
fn build_puzzle_level_name_image_data_url(image: &PuzzleDownloadedImage) -> Option<String> {
let bytes = resize_puzzle_level_name_image_bytes(image.bytes.as_slice())
.unwrap_or_else(|| image.bytes.clone());
let mime_type = if bytes.starts_with(b"\x89PNG\r\n\x1A\n") {
"image/png"
} else {
image.mime_type.as_str()
};
Some(format!(
"data:{};base64,{}",
normalize_puzzle_downloaded_image_mime_type(mime_type),
BASE64_STANDARD.encode(bytes)
))
}
fn resize_puzzle_level_name_image_bytes(bytes: &[u8]) -> Option<Vec<u8>> {
let image = image::load_from_memory(bytes).ok()?;
let resized = image.resize(
PUZZLE_LEVEL_NAME_VISION_IMAGE_MAX_SIDE,
PUZZLE_LEVEL_NAME_VISION_IMAGE_MAX_SIDE,
image::imageops::FilterType::Triangle,
);
let mut cursor = std::io::Cursor::new(Vec::new());
resized.write_to(&mut cursor, ImageFormat::Png).ok()?;
Some(cursor.into_inner())
}
fn parse_puzzle_first_level_name_from_text(text: &str) -> Option<String> {
let trimmed = text.trim();
let json_text = if let Some(start) = trimmed.find('{')
@@ -2964,9 +3103,6 @@ async fn compile_puzzle_draft_with_initial_cover(
let generated_level_name =
generate_puzzle_first_level_name(state, &target_level.picture_description).await;
target_level.level_name = generated_level_name.clone();
let levels_json_with_generated_name = Some(serialize_puzzle_level_records_for_module(
&build_puzzle_levels_with_primary_name(&draft, &target_level),
)?);
let image_prompt = resolve_puzzle_draft_cover_prompt(
prompt_text,
&target_level.picture_description,
@@ -2987,19 +3123,32 @@ async fn compile_puzzle_draft_with_initial_cover(
.await?;
let selected_candidate_id = candidates
.iter()
.find(|candidate| candidate.selected)
.find(|candidate| candidate.record.selected)
.or_else(|| candidates.first())
.map(|candidate| candidate.candidate_id.clone())
.map(|candidate| candidate.record.candidate_id.clone())
.ok_or_else(|| {
AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
"provider": PUZZLE_AGENT_API_BASE_PROVIDER,
"message": "拼图候选图生成结果为空",
}))
})?;
if let Some(refined_level_name) = generate_puzzle_first_level_name_from_image(
state,
target_level.picture_description.as_str(),
&candidates[0].downloaded_image,
)
.await
{
target_level.level_name = refined_level_name;
}
let generated_level_name = target_level.level_name.clone();
let levels_json_with_generated_name = Some(serialize_puzzle_level_records_for_module(
&build_puzzle_levels_with_primary_name(&draft, &target_level),
)?);
let candidates_json = serde_json::to_string(
&candidates
.iter()
.map(to_puzzle_generated_image_candidate)
.map(|candidate| to_puzzle_generated_image_candidate(&candidate.record))
.collect::<Vec<_>>(),
)
.map_err(|error| {
@@ -3040,7 +3189,7 @@ async fn compile_puzzle_draft_with_initial_cover(
now,
),
target_level.level_id.as_str(),
candidates.clone(),
candidates.into_records(),
now,
);
Ok((session, true))
@@ -3076,6 +3225,172 @@ async fn compile_puzzle_draft_with_initial_cover(
}
}
async fn compile_puzzle_draft_with_uploaded_cover(
state: &AppState,
session_id: String,
owner_user_id: String,
prompt_text: Option<&str>,
reference_image_src: Option<&str>,
now: i64,
) -> Result<PuzzleAgentSessionRecord, AppError> {
let uploaded_image_src = reference_image_src
.map(str::trim)
.filter(|value| !value.is_empty())
.ok_or_else(|| {
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"provider": PUZZLE_AGENT_API_BASE_PROVIDER,
"field": "referenceImageSrc",
"message": "关闭 AI 重绘时必须上传拼图图片。",
}))
})?;
let uploaded_image = parse_puzzle_image_data_url(uploaded_image_src).ok_or_else(|| {
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"provider": PUZZLE_AGENT_API_BASE_PROVIDER,
"field": "referenceImageSrc",
"message": "关闭 AI 重绘时上传图必须是图片 Data URL。",
}))
})?;
let compiled_session = state
.spacetime_client()
.compile_puzzle_agent_draft(session_id.clone(), owner_user_id.clone(), now)
.await
.map_err(map_puzzle_compile_error)?;
let draft = compiled_session.draft.clone().ok_or_else(|| {
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"provider": PUZZLE_AGENT_API_BASE_PROVIDER,
"message": "拼图结果页草稿尚未生成",
}))
})?;
let mut target_level = select_puzzle_level_for_api(&draft, None)?;
let fallback_level_name = target_level.level_name.clone();
let generated_level_name =
generate_puzzle_first_level_name(state, &target_level.picture_description).await;
target_level.level_name = generated_level_name.clone();
let image_prompt = resolve_puzzle_draft_cover_prompt(
prompt_text,
&target_level.picture_description,
&draft.summary,
);
// 中文注释：关闭 AI 重绘时不请求 APIMart，也不进入光点扣费流程；上传图直接成为首关正式图候选。
let candidate_id = format!(
"{}-candidate-{}",
compiled_session.session_id,
target_level.candidates.len() + 1
);
let uploaded_downloaded_image = PuzzleDownloadedImage {
extension: puzzle_mime_to_extension(uploaded_image.mime_type.as_str()).to_string(),
mime_type: normalize_puzzle_downloaded_image_mime_type(uploaded_image.mime_type.as_str()),
bytes: uploaded_image.bytes,
};
if let Some(refined_level_name) = generate_puzzle_first_level_name_from_image(
state,
target_level.picture_description.as_str(),
&uploaded_downloaded_image,
)
.await
{
target_level.level_name = refined_level_name;
}
let generated_level_name = target_level.level_name.clone();
let levels_json_with_generated_name = Some(serialize_puzzle_level_records_for_module(
&build_puzzle_levels_with_primary_name(&draft, &target_level),
)?);
let persisted_upload = persist_puzzle_generated_asset(
state,
owner_user_id.as_str(),
&compiled_session.session_id,
&target_level.level_name,
candidate_id.as_str(),
"uploaded-direct",
uploaded_downloaded_image,
current_utc_micros(),
)
.await?;
let candidate = PuzzleGeneratedImageCandidateRecord {
candidate_id: candidate_id.clone(),
image_src: persisted_upload.image_src,
asset_id: persisted_upload.asset_id,
prompt: image_prompt,
actual_prompt: None,
source_type: "uploaded".to_string(),
selected: true,
};
let candidates_json = serde_json::to_string(&vec![to_puzzle_generated_image_candidate(
&candidate,
)])
.map_err(|error| {
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"provider": PUZZLE_AGENT_API_BASE_PROVIDER,
"message": format!("拼图上传图候选序列化失败：{error}"),
}))
})?;
let (saved_session, save_used_fallback) = state
.spacetime_client()
.save_puzzle_generated_images(PuzzleGeneratedImagesSaveRecordInput {
session_id: compiled_session.session_id.clone(),
owner_user_id: owner_user_id.clone(),
level_id: Some(target_level.level_id.clone()),
levels_json: levels_json_with_generated_name,
candidates_json,
saved_at_micros: current_utc_micros(),
})
.await
.map_err(map_puzzle_client_error)
.map(|session| (session, false))
.or_else(|error| {
if is_spacetimedb_connectivity_app_error(&error) {
tracing::warn!(
provider = PUZZLE_AGENT_API_BASE_PROVIDER,
session_id = %compiled_session.session_id,
owner_user_id = %owner_user_id,
message = %error.body_text(),
"拼图上传图草稿回写不可用，降级返回本地快照"
);
let session = apply_generated_puzzle_candidates_to_session_snapshot(
apply_generated_puzzle_first_level_name_to_session_snapshot(
compiled_session.clone(),
target_level.level_id.as_str(),
generated_level_name.as_str(),
fallback_level_name.as_str(),
now,
),
target_level.level_id.as_str(),
vec![candidate.clone()],
now,
);
Ok((session, true))
} else {
Err(error)
}
})?;
if save_used_fallback {
return Ok(saved_session);
}
match state
.spacetime_client()
.select_puzzle_cover_image(PuzzleSelectCoverImageRecordInput {
session_id,
owner_user_id,
level_id: Some(target_level.level_id),
candidate_id,
selected_at_micros: current_utc_micros(),
})
.await
{
Ok(session) => Ok(session),
Err(error) if should_skip_asset_operation_billing_for_connectivity(&error) => {
tracing::warn!(
provider = PUZZLE_AGENT_API_BASE_PROVIDER,
session_id = %saved_session.session_id,
error = %error,
"拼图上传图选定回写因 SpacetimeDB 连接不可用而降级使用已保存快照"
);
Ok(saved_session)
}
Err(error) => Err(map_puzzle_client_error(error)),
}
}
fn apply_generated_puzzle_candidates_to_session_snapshot(
mut session: PuzzleAgentSessionRecord,
target_level_id: &str,
@@ -3687,7 +4002,7 @@ async fn generate_puzzle_image_candidates(
image_model: Option<&str>,
candidate_count: u32,
candidate_start_index: usize,
) -> Result<Vec<PuzzleGeneratedImageCandidateRecord>, AppError> {
) -> Result<Vec<GeneratedPuzzleImageCandidate>, AppError> {
let count = candidate_count.clamp(1, 1);
let resolved_model = resolve_puzzle_image_model(image_model);
let actual_prompt = build_puzzle_image_prompt(level_name, prompt);
@@ -3736,6 +4051,7 @@ async fn generate_puzzle_image_candidates(
"{session_id}-candidate-{}",
candidate_start_index + index + 1
);
let downloaded_image = image.clone();
let asset = persist_puzzle_generated_asset(
state,
owner_user_id,
@@ -3748,30 +4064,22 @@ async fn generate_puzzle_image_candidates(
)
.await
.map_err(map_puzzle_generation_endpoint_error)?;
items.push(PuzzleGeneratedImageCandidateResponse {
candidate_id,
image_src: asset.image_src,
asset_id: asset.asset_id,
prompt: prompt.to_string(),
actual_prompt: Some(actual_prompt.clone()),
source_type: resolved_model.candidate_source_type().to_string(),
// 单图生成结果总是直接成为当前正式图。
selected: index == 0,
items.push(GeneratedPuzzleImageCandidate {
record: PuzzleGeneratedImageCandidateRecord {
candidate_id,
image_src: asset.image_src,
asset_id: asset.asset_id,
prompt: prompt.to_string(),
actual_prompt: Some(actual_prompt.clone()),
source_type: resolved_model.candidate_source_type().to_string(),
// 单图生成结果总是直接成为当前正式图。
selected: index == 0,
},
downloaded_image,
});
}
Ok(items
.into_iter()
.map(|candidate| PuzzleGeneratedImageCandidateRecord {
candidate_id: candidate.candidate_id,
image_src: candidate.image_src,
asset_id: candidate.asset_id,
prompt: candidate.prompt,
actual_prompt: candidate.actual_prompt,
source_type: candidate.source_type,
selected: candidate.selected,
})
.collect())
Ok(items)
}
#[cfg(test)]
@@ -3799,6 +4107,7 @@ mod tests {
assert_eq!(body["size"], PUZZLE_APIMART_GENERATED_IMAGE_SIZE);
assert_eq!(body["resolution"], PUZZLE_APIMART_GEMINI_RESOLUTION);
assert_eq!(body["n"], 1);
assert_eq!(body["official_fallback"], true);
assert_eq!(body["image_urls"][0], "data:image/png;base64,abcd");
assert!(
body["prompt"]
@@ -3836,6 +4145,7 @@ mod tests {
prompt_text: None,
reference_image_src: None,
image_model: Some(PUZZLE_IMAGE_MODEL_GPT_IMAGE_2.to_string()),
ai_redraw: None,
candidate_count: Some(1),
candidate_id: None,
level_id: Some("puzzle-level-1".to_string()),
@@ -3895,6 +4205,26 @@ mod tests {
);
}
#[test]
fn puzzle_level_name_image_data_url_downsizes_generated_image() {
let image = image::DynamicImage::ImageRgb8(image::RgbImage::new(4, 4));
let mut cursor = std::io::Cursor::new(Vec::new());
image
.write_to(&mut cursor, ImageFormat::Png)
.expect("test image should encode");
let downloaded = PuzzleDownloadedImage {
extension: "png".to_string(),
mime_type: "image/png".to_string(),
bytes: cursor.into_inner(),
};
let data_url = build_puzzle_level_name_image_data_url(&downloaded)
.expect("data url should be generated");
assert!(data_url.starts_with("data:image/png;base64,"));
assert!(data_url.len() > "data:image/png;base64,".len());
}
#[test]
fn puzzle_first_level_name_snapshot_defaults_work_title() {
let levels_json = serde_json::to_string(&vec![json!({
@@ -3913,6 +4243,7 @@ mod tests {
prompt_text: None,
reference_image_src: None,
image_model: Some(PUZZLE_IMAGE_MODEL_GPT_IMAGE_2.to_string()),
ai_redraw: None,
candidate_count: Some(1),
candidate_id: None,
level_id: Some("puzzle-level-1".to_string()),
@@ -4003,6 +4334,30 @@ struct PuzzleGeneratedImages {
images: Vec<PuzzleDownloadedImage>,
}
struct GeneratedPuzzleImageCandidate {
record: PuzzleGeneratedImageCandidateRecord,
downloaded_image: PuzzleDownloadedImage,
}
impl GeneratedPuzzleImageCandidate {
fn into_record(self) -> PuzzleGeneratedImageCandidateRecord {
self.record
}
}
trait GeneratedPuzzleImageCandidatesExt {
fn into_records(self) -> Vec<PuzzleGeneratedImageCandidateRecord>;
}
impl GeneratedPuzzleImageCandidatesExt for Vec<GeneratedPuzzleImageCandidate> {
fn into_records(self) -> Vec<PuzzleGeneratedImageCandidateRecord> {
self.into_iter()
.map(GeneratedPuzzleImageCandidate::into_record)
.collect()
}
}
#[derive(Clone)]
struct PuzzleDownloadedImage {
extension: String,
mime_type: String,
@@ -4183,6 +4538,7 @@ fn build_puzzle_apimart_image_request_body(
Value::String(build_puzzle_apimart_prompt(prompt, negative_prompt)),
),
("n".to_string(), json!(candidate_count.clamp(1, 1))),
("official_fallback".to_string(), Value::Bool(true)),
("size".to_string(), Value::String(size.to_string())),
]);
body.insert(

117
server-rs/crates/api-server/src/state.rs
View File

@@ -1,7 +1,9 @@
use std::{error::Error, fmt, sync::Arc};
#[cfg(test)]
use std::{collections::HashMap, sync::Mutex};
use std::{
collections::HashMap,
error::Error,
fmt,
sync::{Arc, Mutex},
};
use module_ai::{AiTaskService, InMemoryAiTaskStore};
use module_auth::{
@@ -11,14 +13,16 @@ use module_auth::{
use module_runtime::RuntimeSnapshotRecord;
#[cfg(test)]
use module_runtime::{SAVE_SNAPSHOT_VERSION, format_utc_micros};
use platform_agent::MockLangChainRustAgentExecutor;
use platform_auth::{
AccessTokenClaims, AccessTokenClaimsInput, AuthProvider, BindingStatus, JwtConfig, JwtError,
RefreshCookieConfig, RefreshCookieError, RefreshCookieSameSite, SmsAuthConfig, SmsAuthProvider,
SmsAuthProviderKind, SmsProviderError, WechatProvider, sign_access_token, verify_access_token,
};
use platform_llm::{LlmClient, LlmConfig, LlmError};
use platform_llm::{LlmClient, LlmConfig, LlmError, LlmProvider};
use platform_oss::{OssClient, OssConfig, OssError};
use serde_json::Value;
use shared_contracts::creative_agent::CreativeAgentSessionSnapshot;
use spacetime_client::{SpacetimeClient, SpacetimeClientConfig, SpacetimeClientError};
use time::OffsetDateTime;
use tracing::{info, warn};
@@ -51,11 +55,22 @@ pub struct AppState {
ai_task_service: AiTaskService,
spacetime_client: SpacetimeClient,
llm_client: Option<LlmClient>,
creative_agent_gpt5_client: Option<LlmClient>,
creative_agent_executor: Arc<MockLangChainRustAgentExecutor>,
// Phase 1 任务 E 的 creative session facade 暂存在 api-server。
// creative_agent_* 表由任务 D 收口后，这里只保留读写 facade。
creative_agent_sessions: Arc<Mutex<HashMap<String, CreativeAgentSessionRuntimeRecord>>>,
#[cfg(test)]
// 测试环境允许在未启动 SpacetimeDB 时，用内存快照兜底当前 runtime story 回归链。
test_runtime_snapshot_store: Arc<Mutex<HashMap<String, RuntimeSnapshotRecord>>>,
}
#[derive(Clone, Debug)]
struct CreativeAgentSessionRuntimeRecord {
owner_user_id: String,
snapshot: CreativeAgentSessionSnapshot,
}
// 后台管理员运行态独立于普通玩家登录体系，只从环境变量构造。
#[derive(Clone, Debug)]
pub struct AdminRuntime {
@@ -167,6 +182,7 @@ impl AppState {
procedure_timeout: config.spacetime_procedure_timeout,
});
let llm_client = build_llm_client(&config)?;
let creative_agent_gpt5_client = build_creative_agent_gpt5_client(&config)?;
Ok(Self {
config,
@@ -185,6 +201,9 @@ impl AppState {
ai_task_service,
spacetime_client,
llm_client,
creative_agent_gpt5_client,
creative_agent_executor: Arc::new(MockLangChainRustAgentExecutor),
creative_agent_sessions: Arc::new(Mutex::new(HashMap::new())),
#[cfg(test)]
test_runtime_snapshot_store: Arc::new(Mutex::new(HashMap::new())),
})
@@ -336,6 +355,44 @@ impl AppState {
self.llm_client.as_ref()
}
pub fn creative_agent_gpt5_client(&self) -> Option<&LlmClient> {
self.creative_agent_gpt5_client.as_ref()
}
pub fn creative_agent_executor(&self) -> Arc<MockLangChainRustAgentExecutor> {
self.creative_agent_executor.clone()
}
pub fn get_creative_agent_session(
&self,
session_id: &str,
owner_user_id: &str,
) -> Option<CreativeAgentSessionSnapshot> {
self.creative_agent_sessions
.lock()
.expect("creative agent session store should lock")
.get(session_id)
.filter(|record| record.owner_user_id == owner_user_id)
.map(|record| record.snapshot.clone())
}
pub fn put_creative_agent_session(
&self,
owner_user_id: String,
session: CreativeAgentSessionSnapshot,
) {
self.creative_agent_sessions
.lock()
.expect("creative agent session store should lock")
.insert(
session.session_id.clone(),
CreativeAgentSessionRuntimeRecord {
owner_user_id,
snapshot: session,
},
);
}
pub async fn get_runtime_snapshot_record(
&self,
user_id: String,
@@ -710,6 +767,32 @@ fn build_llm_client(config: &AppConfig) -> Result<Option<LlmClient>, AppStateIni
Ok(Some(LlmClient::new(llm_config)?))
}
fn build_creative_agent_gpt5_client(
config: &AppConfig,
) -> Result<Option<LlmClient>, AppStateInitError> {
let Some(api_key) = config
.apimart_api_key
.as_ref()
.map(|value| value.trim())
.filter(|value| !value.is_empty())
else {
return Ok(None);
};
let llm_config = LlmConfig::new(
LlmProvider::OpenAiCompatible,
config.apimart_base_url.clone(),
api_key.to_string(),
platform_agent::CREATIVE_AGENT_GPT5_MODEL.to_string(),
config.apimart_image_request_timeout_ms,
0,
config.llm_retry_backoff_ms,
)?
.with_official_fallback(true);
Ok(Some(LlmClient::new(llm_config)?))
}
// 只有在用户名和密码都已配置时才启用后台，避免半配置状态暴露伪入口。
fn build_admin_runtime(
config: &AppConfig,
@@ -783,5 +866,29 @@ mod tests {
let state = AppState::new(AppConfig::default()).expect("state should build");
assert!(state.llm_client().is_none());
assert!(state.creative_agent_gpt5_client().is_none());
}
#[test]
fn app_state_builds_creative_agent_gpt5_client_from_apimart_settings() {
let mut config = AppConfig::default();
config.llm_api_key = None;
config.apimart_base_url = "https://api.apimart.test/v1".to_string();
config.apimart_api_key = Some("apimart-key".to_string());
let state = AppState::new(config).expect("state should build");
let client = state
.creative_agent_gpt5_client()
.expect("creative agent gpt5 client should exist");
assert_eq!(
client.config().model(),
platform_agent::CREATIVE_AGENT_GPT5_MODEL
);
assert_eq!(
client.config().responses_url(),
"https://api.apimart.test/v1/responses"
);
assert!(client.config().official_fallback());
}
}

973
server-rs/crates/api-server/src/vector_engine_audio_generation.rs Normal file
View File

@@ -0,0 +1,973 @@
use std::{collections::BTreeMap, time::Duration};
use axum::{
Json,
extract::{Path, State, rejection::JsonRejection},
http::StatusCode,
response::Response,
};
use module_assets::{
AssetObjectAccessPolicy, build_asset_entity_binding_input, build_asset_object_upsert_input,
generate_asset_binding_id, generate_asset_object_id,
};
use platform_oss::{LegacyAssetPrefix, OssObjectAccess, OssPutObjectRequest};
use reqwest::header;
use serde_json::{Map, Value, json};
use shared_contracts::visual_novel as contract;
use crate::{
api_response::json_success_body, auth::AuthenticatedAccessToken, http_error::AppError,
platform_errors::map_oss_error, request_context::RequestContext, state::AppState,
};
const VECTOR_ENGINE_PROVIDER: &str = "vector-engine";
const VECTOR_ENGINE_SUNO_PROVIDER: &str = "vector-engine-suno";
const VECTOR_ENGINE_VIDU_PROVIDER: &str = "vector-engine-vidu";
const SUNO_DEFAULT_MODEL: &str = "chirp-v4";
const VIDU_AUDIO_MODEL: &str = "audio1.0";
const AUDIO_ENTITY_KIND: &str = "visual_novel_scene";
const MUSIC_ASSET_KIND: &str = "visual_novel_music";
const AMBIENT_SOUND_ASSET_KIND: &str = "visual_novel_ambient_sound";
const MUSIC_SLOT: &str = "music";
const AMBIENT_SOUND_SLOT: &str = "ambient_sound";
const SUNO_PROMPT_MAX_CHARS: usize = 5_000;
const SUNO_TITLE_MAX_CHARS: usize = 80;
const SUNO_TAGS_MAX_CHARS: usize = 160;
const VIDU_PROMPT_MAX_CHARS: usize = 1_500;
const DEFAULT_SOUND_EFFECT_DURATION_SECONDS: u8 = 5;
const MAX_GENERATED_AUDIO_BYTES: usize = 40 * 1024 * 1024;
#[derive(Clone, Debug)]
struct VectorEngineAudioSettings {
base_url: String,
api_key: String,
request_timeout_ms: u64,
}
#[derive(Clone, Debug)]
struct DownloadedAudio {
bytes: Vec<u8>,
mime_type: String,
extension: String,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum AudioAssetSlot {
BackgroundMusic,
SoundEffect,
}
impl AudioAssetSlot {
fn contract_kind(self) -> contract::VisualNovelAudioGenerationKind {
match self {
Self::BackgroundMusic => contract::VisualNovelAudioGenerationKind::BackgroundMusic,
Self::SoundEffect => contract::VisualNovelAudioGenerationKind::SoundEffect,
}
}
fn provider(self) -> &'static str {
match self {
Self::BackgroundMusic => VECTOR_ENGINE_SUNO_PROVIDER,
Self::SoundEffect => VECTOR_ENGINE_VIDU_PROVIDER,
}
}
fn asset_kind(self) -> &'static str {
match self {
Self::BackgroundMusic => MUSIC_ASSET_KIND,
Self::SoundEffect => AMBIENT_SOUND_ASSET_KIND,
}
}
fn slot(self) -> &'static str {
match self {
Self::BackgroundMusic => MUSIC_SLOT,
Self::SoundEffect => AMBIENT_SOUND_SLOT,
}
}
fn file_stem(self) -> &'static str {
match self {
Self::BackgroundMusic => "background-music",
Self::SoundEffect => "sound-effect",
}
}
}
pub async fn create_visual_novel_background_music_task(
State(state): State<AppState>,
axum::extract::Extension(request_context): axum::extract::Extension<RequestContext>,
payload: Result<Json<contract::CreateVisualNovelBackgroundMusicRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
let Json(payload) = parse_json_payload(&request_context, payload)?;
let settings = require_vector_engine_audio_settings(&state)?;
let http_client = build_vector_engine_audio_http_client(&settings)?;
let prompt = normalize_limited_text(&payload.prompt, "prompt", SUNO_PROMPT_MAX_CHARS)?;
let title = normalize_limited_text(&payload.title, "title", SUNO_TITLE_MAX_CHARS)?;
let tags = payload
.tags
.as_deref()
.map(|value| normalize_limited_text(value, "tags", SUNO_TAGS_MAX_CHARS))
.transpose()?;
let model = normalize_optional_text(payload.model.as_deref())
.unwrap_or_else(|| SUNO_DEFAULT_MODEL.to_string());
let mut body = Map::from_iter([
("prompt".to_string(), Value::String(prompt)),
("mv".to_string(), Value::String(model)),
("title".to_string(), Value::String(title)),
("task".to_string(), Value::String("generate".to_string())),
]);
if let Some(tags) = tags {
body.insert("tags".to_string(), Value::String(tags));
}
let response = post_vector_engine_json(
&http_client,
&settings,
"/suno/submit/music",
Value::Object(body),
"提交 Suno 背景音乐任务失败",
)
.await?;
let task_id = extract_string_by_path(&response, &["data"])
.or_else(|| find_first_string_by_key(&response, "task_id"))
.or_else(|| find_first_string_by_key(&response, "taskId"))
.ok_or_else(|| {
vector_engine_bad_gateway("提交 Suno 背景音乐任务失败：上游未返回任务 ID")
})?;
Ok(json_success_body(
Some(&request_context),
contract::VisualNovelAudioGenerationTaskResponse {
kind: contract::VisualNovelAudioGenerationKind::BackgroundMusic,
task_id,
provider: VECTOR_ENGINE_SUNO_PROVIDER.to_string(),
status: "submitted".to_string(),
},
))
}
pub async fn create_visual_novel_sound_effect_task(
State(state): State<AppState>,
axum::extract::Extension(request_context): axum::extract::Extension<RequestContext>,
payload: Result<Json<contract::CreateVisualNovelSoundEffectRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
let Json(payload) = parse_json_payload(&request_context, payload)?;
let settings = require_vector_engine_audio_settings(&state)?;
let http_client = build_vector_engine_audio_http_client(&settings)?;
let prompt = normalize_limited_text(&payload.prompt, "prompt", VIDU_PROMPT_MAX_CHARS)?;
let duration = payload
.duration
.unwrap_or(DEFAULT_SOUND_EFFECT_DURATION_SECONDS)
.clamp(2, 10);
let mut body = Map::from_iter([
(
"model".to_string(),
Value::String(VIDU_AUDIO_MODEL.to_string()),
),
("prompt".to_string(), Value::String(prompt)),
("duration".to_string(), json!(duration)),
]);
if let Some(seed) = payload.seed {
body.insert("seed".to_string(), json!(seed));
}
let response = post_vector_engine_json(
&http_client,
&settings,
"/ent/v2/text2audio",
Value::Object(body),
"提交 Vidu 音效任务失败",
)
.await?;
let task_id = find_first_string_by_key(&response, "task_id")
.or_else(|| find_first_string_by_key(&response, "taskId"))
.ok_or_else(|| vector_engine_bad_gateway("提交 Vidu 音效任务失败：上游未返回任务 ID"))?;
let status = find_first_string_by_key(&response, "state").unwrap_or_else(|| "created".into());
Ok(json_success_body(
Some(&request_context),
contract::VisualNovelAudioGenerationTaskResponse {
kind: contract::VisualNovelAudioGenerationKind::SoundEffect,
task_id,
provider: VECTOR_ENGINE_VIDU_PROVIDER.to_string(),
status,
},
))
}
pub async fn publish_visual_novel_background_music_asset(
State(state): State<AppState>,
Path(task_id): Path<String>,
axum::extract::Extension(request_context): axum::extract::Extension<RequestContext>,
axum::extract::Extension(authenticated): axum::extract::Extension<AuthenticatedAccessToken>,
payload: Result<Json<contract::PublishVisualNovelGeneratedAudioAssetRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
publish_generated_audio_asset(
&state,
&request_context,
authenticated.claims().user_id(),
task_id,
parse_json_payload(&request_context, payload)?.0,
AudioAssetSlot::BackgroundMusic,
)
.await
.map(|payload| json_success_body(Some(&request_context), payload))
.map_err(|error| error.into_response_with_context(Some(&request_context)))
}
pub async fn publish_visual_novel_sound_effect_asset(
State(state): State<AppState>,
Path(task_id): Path<String>,
axum::extract::Extension(request_context): axum::extract::Extension<RequestContext>,
axum::extract::Extension(authenticated): axum::extract::Extension<AuthenticatedAccessToken>,
payload: Result<Json<contract::PublishVisualNovelGeneratedAudioAssetRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
publish_generated_audio_asset(
&state,
&request_context,
authenticated.claims().user_id(),
task_id,
parse_json_payload(&request_context, payload)?.0,
AudioAssetSlot::SoundEffect,
)
.await
.map(|payload| json_success_body(Some(&request_context), payload))
.map_err(|error| error.into_response_with_context(Some(&request_context)))
}
async fn publish_generated_audio_asset(
state: &AppState,
_request_context: &RequestContext,
owner_user_id: &str,
task_id: String,
payload: contract::PublishVisualNovelGeneratedAudioAssetRequest,
slot: AudioAssetSlot,
) -> Result<contract::VisualNovelGeneratedAudioAssetResponse, AppError> {
let task_id = normalize_limited_text(&task_id, "taskId", 160)?;
let scene_id = normalize_limited_text(&payload.scene_id, "sceneId", 160)?;
let profile_id = normalize_optional_text(payload.profile_id.as_deref());
let settings = require_vector_engine_audio_settings(state)?;
let http_client = build_vector_engine_audio_http_client(&settings)?;
let task_payload = fetch_audio_task_payload(&http_client, &settings, slot, &task_id).await?;
let status = normalize_task_status(
find_first_string_by_key(&task_payload, "status")
.or_else(|| find_first_string_by_key(&task_payload, "state"))
.or_else(|| find_first_string_by_key(&task_payload, "Status"))
.as_deref()
.unwrap_or(""),
);
let mut audio_urls = extract_audio_urls(&task_payload);
if slot == AudioAssetSlot::BackgroundMusic && audio_urls.is_empty() {
if let Some(clip_id) = extract_string_by_path(&task_payload, &["data"])
.filter(|value| !value.trim().is_empty())
{
let wav_payload = get_vector_engine_json(
&http_client,
&settings,
&format!("/suno/act/wav/{}", encode_path_segment(clip_id.as_str())),
"获取 Suno wav 音频失败",
)
.await?;
audio_urls = extract_audio_urls(&wav_payload);
}
}
if is_pending_task_status(&status) && audio_urls.is_empty() {
return Ok(contract::VisualNovelGeneratedAudioAssetResponse {
kind: slot.contract_kind(),
task_id,
provider: slot.provider().to_string(),
status,
asset_object_id: None,
asset_kind: None,
audio_src: None,
});
}
if is_failed_task_status(&status) {
return Err(vector_engine_bad_gateway(
"音频生成任务失败，请调整提示词后重试",
));
}
let audio_url = audio_urls
.into_iter()
.next()
.ok_or_else(|| vector_engine_bad_gateway("音频生成尚未返回可下载地址"))?;
let audio = download_generated_audio(&http_client, &audio_url, slot.provider()).await?;
let persisted = persist_generated_audio_asset(
state,
&http_client,
owner_user_id,
profile_id,
scene_id,
&task_id,
slot,
audio,
)
.await?;
Ok(contract::VisualNovelGeneratedAudioAssetResponse {
kind: slot.contract_kind(),
task_id,
provider: slot.provider().to_string(),
status: "completed".to_string(),
asset_object_id: Some(persisted.asset_object_id),
asset_kind: Some(slot.asset_kind().to_string()),
audio_src: Some(persisted.audio_src),
})
}
async fn fetch_audio_task_payload(
http_client: &reqwest::Client,
settings: &VectorEngineAudioSettings,
slot: AudioAssetSlot,
task_id: &str,
) -> Result<Value, AppError> {
match slot {
AudioAssetSlot::BackgroundMusic => {
get_vector_engine_json(
http_client,
settings,
&format!("/suno/fetch/{}", encode_path_segment(task_id)),
"查询 Suno 背景音乐任务失败",
)
.await
}
AudioAssetSlot::SoundEffect => {
get_vector_engine_json(
http_client,
settings,
&format!("/ent/v2/tasks/{}/creations", encode_path_segment(task_id)),
"查询 Vidu 音效任务失败",
)
.await
}
}
}
#[derive(Clone, Debug)]
struct PersistedAudioAsset {
asset_object_id: String,
audio_src: String,
}
async fn persist_generated_audio_asset(
state: &AppState,
http_client: &reqwest::Client,
owner_user_id: &str,
profile_id: Option<String>,
scene_id: String,
task_id: &str,
slot: AudioAssetSlot,
audio: DownloadedAudio,
) -> Result<PersistedAudioAsset, AppError> {
let oss_client = state.oss_client().ok_or_else(|| {
AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
"provider": "aliyun-oss",
"reason": "OSS 未完成环境变量配置",
}))
})?;
let file_name = format!("{}-{}.{}", slot.file_stem(), task_id, audio.extension);
let put_result = oss_client
.put_object(
http_client,
OssPutObjectRequest {
prefix: LegacyAssetPrefix::CustomWorldScenes,
path_segments: vec![
"visual-novel".to_string(),
profile_id.clone().unwrap_or_else(|| "draft".to_string()),
scene_id.clone(),
slot.slot().to_string(),
],
file_name,
content_type: Some(audio.mime_type.clone()),
access: OssObjectAccess::Private,
metadata: build_audio_asset_metadata(
owner_user_id,
profile_id.as_deref(),
&scene_id,
slot,
),
body: audio.bytes,
},
)
.await
.map_err(|error| map_oss_error(error, "aliyun-oss"))?;
let head = oss_client
.head_object(
http_client,
platform_oss::OssHeadObjectRequest {
object_key: put_result.object_key.clone(),
},
)
.await
.map_err(|error| map_oss_error(error, "aliyun-oss"))?;
let now_micros = current_utc_micros();
let asset_object = state
.spacetime_client()
.confirm_asset_object(
build_asset_object_upsert_input(
generate_asset_object_id(now_micros),
head.bucket,
head.object_key,
AssetObjectAccessPolicy::Private,
head.content_type.or(Some(audio.mime_type)),
head.content_length,
head.etag,
slot.asset_kind().to_string(),
Some(task_id.to_string()),
Some(owner_user_id.to_string()),
profile_id.clone(),
Some(scene_id.clone()),
now_micros,
)
.map_err(map_asset_field_error)?,
)
.await
.map_err(map_spacetime_error)?;
state
.spacetime_client()
.bind_asset_object_to_entity(
build_asset_entity_binding_input(
generate_asset_binding_id(now_micros),
asset_object.asset_object_id.clone(),
AUDIO_ENTITY_KIND.to_string(),
scene_id,
slot.slot().to_string(),
slot.asset_kind().to_string(),
Some(owner_user_id.to_string()),
profile_id,
now_micros,
)
.map_err(map_asset_field_error)?,
)
.await
.map_err(map_spacetime_error)?;
Ok(PersistedAudioAsset {
asset_object_id: asset_object.asset_object_id,
audio_src: put_result.legacy_public_path,
})
}
fn build_audio_asset_metadata(
owner_user_id: &str,
profile_id: Option<&str>,
scene_id: &str,
slot: AudioAssetSlot,
) -> BTreeMap<String, String> {
let mut metadata = BTreeMap::from([
("asset-kind".to_string(), slot.asset_kind().to_string()),
("owner-user-id".to_string(), owner_user_id.to_string()),
("entity-kind".to_string(), AUDIO_ENTITY_KIND.to_string()),
("entity-id".to_string(), scene_id.to_string()),
("slot".to_string(), slot.slot().to_string()),
("provider".to_string(), slot.provider().to_string()),
]);
if let Some(profile_id) = profile_id {
metadata.insert("profile-id".to_string(), profile_id.to_string());
}
metadata
}
fn require_vector_engine_audio_settings(
state: &AppState,
) -> Result<VectorEngineAudioSettings, AppError> {
let base_url = state
.config
.vector_engine_base_url
.trim()
.trim_end_matches('/');
if base_url.is_empty() {
return Err(
AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
"provider": VECTOR_ENGINE_PROVIDER,
"reason": "VECTOR_ENGINE_BASE_URL 未配置",
})),
);
}
let api_key = state
.config
.vector_engine_api_key
.as_deref()
.map(str::trim)
.filter(|value| !value.is_empty())
.ok_or_else(|| {
AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
"provider": VECTOR_ENGINE_PROVIDER,
"reason": "VECTOR_ENGINE_API_KEY 未配置",
}))
})?;
Ok(VectorEngineAudioSettings {
base_url: base_url.to_string(),
api_key: api_key.to_string(),
request_timeout_ms: state.config.vector_engine_audio_request_timeout_ms.max(1),
})
}
fn build_vector_engine_audio_http_client(
settings: &VectorEngineAudioSettings,
) -> Result<reqwest::Client, AppError> {
reqwest::Client::builder()
.timeout(Duration::from_millis(settings.request_timeout_ms))
.build()
.map_err(|error| {
AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
"provider": VECTOR_ENGINE_PROVIDER,
"message": format!("构造 VectorEngine 音频生成 HTTP 客户端失败：{error}"),
}))
})
}
async fn post_vector_engine_json(
http_client: &reqwest::Client,
settings: &VectorEngineAudioSettings,
path: &str,
body: Value,
failure_context: &str,
) -> Result<Value, AppError> {
let response = http_client
.post(format!("{}{}", settings.base_url, path))
.header(
header::AUTHORIZATION,
format!("Bearer {}", settings.api_key),
)
.header(header::ACCEPT, "application/json")
.header(header::CONTENT_TYPE, "application/json")
.json(&body)
.send()
.await
.map_err(|error| vector_engine_bad_gateway(format!("{failure_context}：{error}")))?;
parse_vector_engine_response(response, failure_context).await
}
async fn get_vector_engine_json(
http_client: &reqwest::Client,
settings: &VectorEngineAudioSettings,
path: &str,
failure_context: &str,
) -> Result<Value, AppError> {
let response = http_client
.get(format!("{}{}", settings.base_url, path))
.header(
header::AUTHORIZATION,
format!("Bearer {}", settings.api_key),
)
.header(header::ACCEPT, "application/json")
.send()
.await
.map_err(|error| vector_engine_bad_gateway(format!("{failure_context}：{error}")))?;
parse_vector_engine_response(response, failure_context).await
}
async fn parse_vector_engine_response(
response: reqwest::Response,
failure_context: &str,
) -> Result<Value, AppError> {
let status = response.status();
let raw_text = response.text().await.map_err(|error| {
vector_engine_bad_gateway(format!("{failure_context}：读取响应失败：{error}"))
})?;
if !status.is_success() {
return Err(
AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
"provider": VECTOR_ENGINE_PROVIDER,
"message": failure_context,
"status": status.as_u16(),
"rawExcerpt": truncate_raw(raw_text.as_str()),
})),
);
}
let payload = serde_json::from_str::<Value>(&raw_text).map_err(|error| {
AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
"provider": VECTOR_ENGINE_PROVIDER,
"message": format!("{failure_context}：解析响应失败：{error}"),
"rawExcerpt": truncate_raw(raw_text.as_str()),
}))
})?;
if let Some(code) = payload.get("code").and_then(Value::as_str)
&& !matches!(
code.trim().to_ascii_lowercase().as_str(),
"success" | "succeeded" | "ok"
)
{
return Err(
AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
"provider": VECTOR_ENGINE_PROVIDER,
"message": payload
.get("message")
.and_then(Value::as_str)
.unwrap_or(failure_context),
"code": code,
})),
);
}
Ok(payload)
}
async fn download_generated_audio(
http_client: &reqwest::Client,
audio_url: &str,
provider: &str,
) -> Result<DownloadedAudio, AppError> {
let response = http_client
.get(audio_url)
.send()
.await
.map_err(|error| vector_engine_bad_gateway(format!("下载生成音频失败：{error}")))?;
let status = response.status();
let content_type = response
.headers()
.get(header::CONTENT_TYPE)
.and_then(|value| value.to_str().ok())
.unwrap_or("audio/mpeg")
.to_string();
let body = response
.bytes()
.await
.map_err(|error| vector_engine_bad_gateway(format!("读取生成音频内容失败：{error}")))?;
if !status.is_success() {
return Err(
AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
"provider": provider,
"message": "下载生成音频失败",
"status": status.as_u16(),
})),
);
}
if body.is_empty() || body.len() > MAX_GENERATED_AUDIO_BYTES {
return Err(
AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
"provider": provider,
"message": "生成音频内容为空或超过大小上限",
})),
);
}
let mime_type = normalize_audio_mime_type(&content_type, audio_url);
Ok(DownloadedAudio {
extension: audio_mime_to_extension(&mime_type).to_string(),
mime_type,
bytes: body.to_vec(),
})
}
fn extract_audio_urls(payload: &Value) -> Vec<String> {
let mut urls = Vec::new();
collect_audio_url_strings(payload, &mut urls);
let mut deduped = Vec::new();
for url in urls {
if !deduped.contains(&url) {
deduped.push(url);
}
}
deduped
}
fn collect_audio_url_strings(value: &Value, output: &mut Vec<String>) {
match value {
Value::Object(object) => {
for (key, value) in object {
if let Some(raw) = value.as_str()
&& looks_like_audio_url_key(key)
&& looks_like_http_url(raw)
{
output.push(raw.trim().to_string());
}
collect_audio_url_strings(value, output);
}
}
Value::Array(items) => {
for item in items {
collect_audio_url_strings(item, output);
}
}
Value::String(raw) if looks_like_http_url(raw) && looks_like_audio_url(raw) => {
output.push(raw.trim().to_string());
}
_ => {}
}
}
fn looks_like_audio_url_key(key: &str) -> bool {
let normalized = key.trim().to_ascii_lowercase();
normalized.contains("audio")
|| normalized.contains("wav")
|| normalized.contains("mp3")
|| normalized.contains("fileurl")
|| normalized == "url"
|| normalized.ends_with("_url")
|| normalized.ends_with("url")
}
fn looks_like_http_url(value: &str) -> bool {
let value = value.trim().to_ascii_lowercase();
value.starts_with("http://") || value.starts_with("https://")
}
fn looks_like_audio_url(value: &str) -> bool {
let value = value
.trim()
.split('?')
.next()
.unwrap_or_default()
.to_ascii_lowercase();
value.ends_with(".mp3")
|| value.ends_with(".wav")
|| value.ends_with(".m4a")
|| value.ends_with(".aac")
|| value.ends_with(".ogg")
|| value.ends_with(".webm")
|| value.ends_with(".flac")
}
fn normalize_audio_mime_type(content_type: &str, audio_url: &str) -> String {
let mime_type = content_type
.split(';')
.next()
.map(str::trim)
.filter(|value| value.starts_with("audio/"))
.unwrap_or("");
match mime_type {
"audio/mpeg" | "audio/mp3" => "audio/mpeg".to_string(),
"audio/wav" | "audio/wave" | "audio/x-wav" => "audio/wav".to_string(),
"audio/ogg" => "audio/ogg".to_string(),
"audio/webm" => "audio/webm".to_string(),
"audio/aac" => "audio/aac".to_string(),
"audio/flac" => "audio/flac".to_string(),
"audio/mp4" | "audio/x-m4a" => "audio/mp4".to_string(),
_ => mime_type_from_audio_url(audio_url),
}
}
fn mime_type_from_audio_url(audio_url: &str) -> String {
let path = audio_url
.split('?')
.next()
.unwrap_or_default()
.to_ascii_lowercase();
if path.ends_with(".wav") {
"audio/wav".to_string()
} else if path.ends_with(".ogg") {
"audio/ogg".to_string()
} else if path.ends_with(".webm") {
"audio/webm".to_string()
} else if path.ends_with(".aac") {
"audio/aac".to_string()
} else if path.ends_with(".flac") {
"audio/flac".to_string()
} else if path.ends_with(".m4a") {
"audio/mp4".to_string()
} else {
"audio/mpeg".to_string()
}
}
fn audio_mime_to_extension(mime_type: &str) -> &'static str {
match mime_type {
"audio/wav" => "wav",
"audio/ogg" => "ogg",
"audio/webm" => "webm",
"audio/aac" => "aac",
"audio/flac" => "flac",
"audio/mp4" => "m4a",
_ => "mp3",
}
}
fn normalize_limited_text(
value: &str,
field: &'static str,
max_chars: usize,
) -> Result<String, AppError> {
let normalized = value.trim().to_string();
if normalized.is_empty() {
return Err(
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"provider": VECTOR_ENGINE_PROVIDER,
"field": field,
"message": format!("{field} 不能为空"),
})),
);
}
if normalized.chars().count() > max_chars {
return Err(
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"provider": VECTOR_ENGINE_PROVIDER,
"field": field,
"message": format!("{field} 超过 {} 字符", max_chars),
})),
);
}
Ok(normalized)
}
fn normalize_optional_text(value: Option<&str>) -> Option<String> {
value
.map(str::trim)
.filter(|value| !value.is_empty())
.map(ToOwned::to_owned)
}
fn normalize_task_status(status: &str) -> String {
let normalized = status.trim().to_ascii_lowercase().replace(' ', "_");
match normalized.as_str() {
"finish" | "finished" | "complete" | "completed" | "success" | "succeeded" => {
"completed".to_string()
}
"" => "processing".to_string(),
value => value.to_string(),
}
}
fn is_pending_task_status(status: &str) -> bool {
matches!(
status,
"created" | "pending" | "queued" | "processing" | "running" | "submitted" | "started"
)
}
fn is_failed_task_status(status: &str) -> bool {
matches!(
status,
"failed" | "error" | "canceled" | "cancelled" | "rejected" | "expired"
)
}
fn find_first_string_by_key(value: &Value, target_key: &str) -> Option<String> {
match value {
Value::Object(object) => {
for (key, value) in object {
if key.eq_ignore_ascii_case(target_key)
&& let Some(text) = value.as_str()
{
return Some(text.trim().to_string());
}
if let Some(found) = find_first_string_by_key(value, target_key) {
return Some(found);
}
}
None
}
Value::Array(items) => items
.iter()
.find_map(|item| find_first_string_by_key(item, target_key)),
_ => None,
}
}
fn extract_string_by_path(value: &Value, path: &[&str]) -> Option<String> {
let mut current = value;
for key in path {
current = current.get(*key)?;
}
current.as_str().map(str::trim).map(ToOwned::to_owned)
}
fn encode_path_segment(value: &str) -> String {
urlencoding::encode(value).into_owned()
}
fn truncate_raw(raw_text: &str) -> String {
raw_text.chars().take(800).collect()
}
fn current_utc_micros() -> i64 {
shared_kernel::offset_datetime_to_unix_micros(time::OffsetDateTime::now_utc())
}
fn map_asset_field_error(error: module_assets::AssetObjectFieldError) -> AppError {
AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
"provider": "asset-object",
"message": error.to_string(),
}))
}
fn map_spacetime_error(error: spacetime_client::SpacetimeClientError) -> AppError {
AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
"provider": "spacetimedb",
"message": error.to_string(),
}))
}
fn vector_engine_bad_gateway(message: impl Into<String>) -> AppError {
AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
"provider": VECTOR_ENGINE_PROVIDER,
"message": message.into(),
}))
}
fn parse_json_payload<T>(
request_context: &RequestContext,
payload: Result<Json<T>, JsonRejection>,
) -> Result<Json<T>, Response> {
payload.map_err(|rejection| {
AppError::from_status(StatusCode::BAD_REQUEST)
.with_message(format!("请求体 JSON 不合法：{rejection}"))
.into_response_with_context(Some(request_context))
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn normalizes_audio_mime_type_from_content_type_and_url() {
assert_eq!(
normalize_audio_mime_type("audio/x-wav; charset=utf-8", "https://x/a.bin"),
"audio/wav"
);
assert_eq!(
normalize_audio_mime_type("application/octet-stream", "https://x/a.m4a?token=1"),
"audio/mp4"
);
assert_eq!(audio_mime_to_extension("audio/mp4"), "m4a");
}
#[test]
fn extracts_nested_audio_urls() {
let payload = json!({
"Response": {
"Status": "FINISH",
"Task": {
"Output": {
"FileInfos": [
{ "FileUrl": "https://cdn.example.test/audio.wav" }
]
}
}
}
});
assert_eq!(
extract_audio_urls(&payload),
vec!["https://cdn.example.test/audio.wav".to_string()]
);
}
#[test]
fn vector_engine_task_status_is_stable() {
assert_eq!(normalize_task_status("FINISH"), "completed");
assert!(is_pending_task_status("processing"));
assert!(is_failed_task_status("failed"));
}
#[test]
fn validates_prompt_length() {
let prompt = "声".repeat(VIDU_PROMPT_MAX_CHARS + 1);
let error = normalize_limited_text(&prompt, "prompt", VIDU_PROMPT_MAX_CHARS)
.expect_err("long prompt should fail");
assert_eq!(error.status_code(), StatusCode::BAD_REQUEST);
}
}

1776
server-rs/crates/api-server/src/visual_novel.rs Normal file
View File

File diff suppressed because it is too large Load Diff

551
server-rs/crates/api-server/src/volcengine_speech.rs Normal file
View File

@@ -0,0 +1,551 @@
use axum::{
Json,
body::Body,
extract::{
State,
ws::{Message as ClientWsMessage, WebSocket, WebSocketUpgrade},
},
http::{HeaderValue, StatusCode, header},
response::Response,
};
use futures_util::{SinkExt, StreamExt, TryStreamExt};
use platform_speech::{
AsrAudioConfig, AsrFrameKind, PublicSpeechConfig, PublicSpeechEndpoints, SpeechError,
TtsAudioParams, TtsBidirectionClientEvent, TtsSseRequest, UpstreamWsError, UpstreamWsMessage,
VolcengineSpeechClient, VolcengineSpeechConfig, build_asr_frame, build_asr_full_client_request,
build_tts_bidirection_frame_from_client_event, default_asr_request_payload,
parse_asr_response_frame, parse_tts_response_frame, tts_response_to_client_value,
};
use serde_json::{Value, json};
use tracing::{info, warn};
use crate::{
api_response::json_success_body, auth::AuthenticatedAccessToken, http_error::AppError,
request_context::RequestContext, state::AppState,
};
const PROVIDER: &str = "volcengine-speech";
pub async fn get_volcengine_speech_config(
State(state): State<AppState>,
axum::extract::Extension(request_context): axum::extract::Extension<RequestContext>,
) -> Json<Value> {
json_success_body(Some(&request_context), public_speech_config(&state))
}
pub async fn stream_volcengine_asr(
State(state): State<AppState>,
axum::extract::Extension(authenticated): axum::extract::Extension<AuthenticatedAccessToken>,
ws: WebSocketUpgrade,
) -> Result<Response, Response> {
let client = build_speech_client(&state)
.map_err(|error| map_speech_error(error).into_response_with_context(None))?;
let user_id = authenticated.claims().user_id().to_string();
Ok(ws.on_upgrade(move |socket| proxy_asr_websocket(socket, client, user_id)))
}
pub async fn stream_volcengine_tts_bidirection(
State(state): State<AppState>,
ws: WebSocketUpgrade,
) -> Result<Response, Response> {
let client = build_speech_client(&state)
.map_err(|error| map_speech_error(error).into_response_with_context(None))?;
Ok(ws.on_upgrade(move |socket| proxy_tts_bidirection_websocket(socket, client)))
}
pub async fn stream_volcengine_tts_sse(
State(state): State<AppState>,
axum::extract::Extension(request_context): axum::extract::Extension<RequestContext>,
axum::extract::Extension(authenticated): axum::extract::Extension<AuthenticatedAccessToken>,
payload: Result<Json<TtsSseRequest>, axum::extract::rejection::JsonRejection>,
) -> Result<Response, Response> {
let Json(payload) = payload.map_err(|rejection| {
AppError::from_status(StatusCode::BAD_REQUEST)
.with_message(format!("请求体 JSON 不合法：{rejection}"))
.into_response_with_context(Some(&request_context))
})?;
let client = build_speech_client(&state).map_err(|error| {
map_speech_error(error).into_response_with_context(Some(&request_context))
})?;
let upstream_request = client
.build_tts_sse_upstream_request(payload, authenticated.claims().user_id())
.map_err(|error| {
map_speech_error(error).into_response_with_context(Some(&request_context))
})?;
let http_client = reqwest::Client::builder()
.timeout(upstream_request.timeout)
.build()
.map_err(|error| {
AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR)
.with_details(json!({
"provider": PROVIDER,
"message": format!("构造火山语音 HTTP 客户端失败：{error}"),
}))
.into_response_with_context(Some(&request_context))
})?;
let upstream_response = http_client
.post(upstream_request.url)
.headers(upstream_request.headers)
.json(&upstream_request.body)
.send()
.await
.map_err(|error| {
AppError::from_status(StatusCode::BAD_GATEWAY)
.with_details(json!({
"provider": PROVIDER,
"message": format!("请求火山 TTS SSE 失败：{error}"),
}))
.into_response_with_context(Some(&request_context))
})?;
let status = upstream_response.status();
let log_id = upstream_response
.headers()
.get("X-Tt-Logid")
.and_then(|value| value.to_str().ok())
.map(ToOwned::to_owned);
if !status.is_success() {
let raw_text = upstream_response.text().await.unwrap_or_default();
return Err(AppError::from_status(StatusCode::BAD_GATEWAY)
.with_details(json!({
"provider": PROVIDER,
"status": status.as_u16(),
"logId": log_id,
"rawExcerpt": raw_text.chars().take(800).collect::<String>(),
}))
.into_response_with_context(Some(&request_context)));
}
let byte_stream = upstream_response
.bytes_stream()
.map_err(std::io::Error::other);
let mut response = Response::new(Body::from_stream(byte_stream));
*response.status_mut() = StatusCode::OK;
response.headers_mut().insert(
header::CONTENT_TYPE,
HeaderValue::from_static("text/event-stream; charset=utf-8"),
);
response
.headers_mut()
.insert(header::CACHE_CONTROL, HeaderValue::from_static("no-cache"));
if let Some(log_id) = log_id.and_then(|value| HeaderValue::from_str(&value).ok()) {
response.headers_mut().insert("x-volcengine-logid", log_id);
}
Ok(response)
}
async fn proxy_asr_websocket(socket: WebSocket, client: VolcengineSpeechClient, user_id: String) {
let (mut browser_sender, mut browser_receiver) = socket.split();
let Ok((upstream, response_headers)) = client.connect_asr().await else {
let _ = browser_sender
.send(ClientWsMessage::Text(
json!({
"type": "error",
"provider": PROVIDER,
"message": "连接火山 ASR WebSocket 失败",
})
.to_string()
.into(),
))
.await;
return;
};
if let Some(log_id) = response_headers.get("x-tt-logid") {
info!(%log_id, "火山 ASR WebSocket 已连接");
}
let (mut upstream_sender, mut upstream_receiver) = upstream.split();
let mut has_sent_start = false;
let mut last_audio_sent = false;
let browser_to_upstream = async {
while let Some(message) = browser_receiver.next().await {
match message {
Ok(ClientWsMessage::Text(text)) => {
let value = serde_json::from_str::<Value>(text.as_str()).unwrap_or_else(|_| {
json!({
"request": {
"context": text.as_str(),
}
})
});
if value
.get("type")
.and_then(Value::as_str)
.is_some_and(|kind| kind.eq_ignore_ascii_case("finish"))
{
let frame = build_asr_frame(AsrFrameKind::LastAudio, &[])?;
upstream_sender
.send(UpstreamWsMessage::Binary(frame.into()))
.await
.map_err(map_ws_send_error)?;
last_audio_sent = true;
continue;
}
if !has_sent_start {
let payload = default_asr_request_payload(&user_id, Some(value));
let frame = build_asr_full_client_request(&payload)?;
upstream_sender
.send(UpstreamWsMessage::Binary(frame.into()))
.await
.map_err(map_ws_send_error)?;
has_sent_start = true;
}
}
Ok(ClientWsMessage::Binary(bytes)) => {
if !has_sent_start {
let payload = default_asr_request_payload(&user_id, None);
let frame = build_asr_full_client_request(&payload)?;
upstream_sender
.send(UpstreamWsMessage::Binary(frame.into()))
.await
.map_err(map_ws_send_error)?;
has_sent_start = true;
}
let frame = build_asr_frame(AsrFrameKind::Audio, &bytes)?;
upstream_sender
.send(UpstreamWsMessage::Binary(frame.into()))
.await
.map_err(map_ws_send_error)?;
}
Ok(ClientWsMessage::Close(_)) => break,
Ok(ClientWsMessage::Ping(bytes)) => {
upstream_sender
.send(UpstreamWsMessage::Ping(bytes))
.await
.map_err(map_ws_send_error)?;
}
Ok(ClientWsMessage::Pong(_)) => {}
Err(error) => {
return Err(SpeechError::Upstream(format!(
"读取浏览器 ASR WebSocket 失败：{error}"
)));
}
}
}
if has_sent_start && !last_audio_sent {
let frame = build_asr_frame(AsrFrameKind::LastAudio, &[])?;
let _ = upstream_sender
.send(UpstreamWsMessage::Binary(frame.into()))
.await;
}
Ok::<(), SpeechError>(())
};
let upstream_to_browser = async {
while let Some(message) = upstream_receiver.next().await {
match message {
Ok(UpstreamWsMessage::Binary(bytes)) => {
let parsed = parse_asr_response_frame(&bytes)?;
let value = json!({
"type": "asr_response",
"sequence": parsed.sequence,
"payload": parsed.payload,
"errorCode": parsed.error_code,
});
browser_sender
.send(ClientWsMessage::Text(value.to_string().into()))
.await
.map_err(map_client_ws_send_error)?;
}
Ok(UpstreamWsMessage::Text(text)) => {
browser_sender
.send(ClientWsMessage::Text(text.to_string().into()))
.await
.map_err(map_client_ws_send_error)?;
}
Ok(UpstreamWsMessage::Close(_)) => {
let _ = browser_sender.send(ClientWsMessage::Close(None)).await;
break;
}
Ok(UpstreamWsMessage::Ping(bytes)) => {
browser_sender
.send(ClientWsMessage::Ping(bytes))
.await
.map_err(map_client_ws_send_error)?;
}
Ok(UpstreamWsMessage::Pong(_)) => {}
Ok(UpstreamWsMessage::Frame(_)) => {}
Err(error) => {
return Err(SpeechError::Upstream(format!(
"读取火山 ASR WebSocket 失败：{error}"
)));
}
}
}
Ok::<(), SpeechError>(())
};
let mut browser_to_upstream = Box::pin(browser_to_upstream);
let mut upstream_to_browser = Box::pin(upstream_to_browser);
let result = tokio::select! {
result = &mut browser_to_upstream => result,
result = &mut upstream_to_browser => result,
};
if let Err(error) = result {
warn!(error = %error, "火山 ASR WebSocket 代理中断");
}
}
async fn proxy_tts_bidirection_websocket(socket: WebSocket, client: VolcengineSpeechClient) {
let (mut browser_sender, mut browser_receiver) = socket.split();
let Ok((upstream, response_headers)) = client.connect_tts_bidirection().await else {
let _ = browser_sender
.send(ClientWsMessage::Text(
json!({
"type": "error",
"provider": PROVIDER,
"message": "连接火山 TTS WebSocket 失败",
})
.to_string()
.into(),
))
.await;
return;
};
if let Some(log_id) = response_headers.get("x-tt-logid") {
info!(%log_id, "火山 TTS WebSocket 已连接");
}
let (mut upstream_sender, mut upstream_receiver) = upstream.split();
let browser_to_upstream = async {
while let Some(message) = browser_receiver.next().await {
match message {
Ok(ClientWsMessage::Text(text)) => {
let event = serde_json::from_str::<TtsBidirectionClientEvent>(text.as_str())
.map_err(|error| {
SpeechError::InvalidFrame(format!(
"TTS 浏览器事件 JSON 不合法：{error}"
))
})?;
let frame = build_tts_bidirection_frame_from_client_event(event)?;
upstream_sender
.send(UpstreamWsMessage::Binary(frame.into()))
.await
.map_err(map_ws_send_error)?;
}
Ok(ClientWsMessage::Close(_)) => break,
Ok(ClientWsMessage::Ping(bytes)) => {
upstream_sender
.send(UpstreamWsMessage::Ping(bytes))
.await
.map_err(map_ws_send_error)?;
}
Ok(ClientWsMessage::Binary(_)) | Ok(ClientWsMessage::Pong(_)) => {}
Err(error) => {
return Err(SpeechError::Upstream(format!(
"读取浏览器 TTS WebSocket 失败：{error}"
)));
}
}
}
Ok::<(), SpeechError>(())
};
let upstream_to_browser = async {
while let Some(message) = upstream_receiver.next().await {
match message {
Ok(UpstreamWsMessage::Binary(bytes)) => {
let parsed = parse_tts_response_frame(&bytes)?;
if let Some(audio) = parsed.audio.clone() {
browser_sender
.send(ClientWsMessage::Binary(audio.into()))
.await
.map_err(map_client_ws_send_error)?;
}
if parsed.payload.is_some() || parsed.error_code.is_some() {
browser_sender
.send(ClientWsMessage::Text(
tts_response_to_client_value(&parsed).to_string().into(),
))
.await
.map_err(map_client_ws_send_error)?;
}
}
Ok(UpstreamWsMessage::Text(text)) => {
browser_sender
.send(ClientWsMessage::Text(text.to_string().into()))
.await
.map_err(map_client_ws_send_error)?;
}
Ok(UpstreamWsMessage::Close(_)) => {
let _ = browser_sender.send(ClientWsMessage::Close(None)).await;
break;
}
Ok(UpstreamWsMessage::Ping(bytes)) => {
browser_sender
.send(ClientWsMessage::Ping(bytes))
.await
.map_err(map_client_ws_send_error)?;
}
Ok(UpstreamWsMessage::Pong(_)) => {}
Ok(UpstreamWsMessage::Frame(_)) => {}
Err(error) => {
return Err(SpeechError::Upstream(format!(
"读取火山 TTS WebSocket 失败：{error}"
)));
}
}
}
Ok::<(), SpeechError>(())
};
let mut browser_to_upstream = Box::pin(browser_to_upstream);
let mut upstream_to_browser = Box::pin(upstream_to_browser);
let result = tokio::select! {
result = &mut browser_to_upstream => result,
result = &mut upstream_to_browser => result,
};
if let Err(error) = result {
warn!(error = %error, "火山 TTS WebSocket 代理中断");
}
}
fn build_speech_client(state: &AppState) -> Result<VolcengineSpeechClient, SpeechError> {
Ok(VolcengineSpeechClient::new(VolcengineSpeechConfig::new(
state.config.volcengine_speech_api_key.clone(),
state.config.volcengine_speech_app_id.clone(),
state.config.volcengine_speech_access_key.clone(),
state.config.volcengine_speech_asr_resource_id.clone(),
state.config.volcengine_speech_tts_resource_id.clone(),
state.config.volcengine_speech_asr_ws_url.clone(),
state
.config
.volcengine_speech_tts_bidirection_ws_url
.clone(),
state.config.volcengine_speech_tts_sse_url.clone(),
state.config.volcengine_speech_request_timeout_ms,
)?))
}
fn public_speech_config(state: &AppState) -> PublicSpeechConfig {
PublicSpeechConfig {
asr_resource_id: state.config.volcengine_speech_asr_resource_id.clone(),
tts_resource_id: state.config.volcengine_speech_tts_resource_id.clone(),
asr_audio: AsrAudioConfig::default(),
tts_audio: TtsAudioParams::default(),
endpoints: PublicSpeechEndpoints {
asr_stream: "/api/speech/volcengine/asr/stream",
tts_bidirection: "/api/speech/volcengine/tts/bidirection",
tts_sse: "/api/speech/volcengine/tts/sse",
},
}
}
fn map_speech_error(error: SpeechError) -> AppError {
match error {
SpeechError::InvalidConfig(message) => {
AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
"provider": PROVIDER,
"message": message,
}))
}
SpeechError::InvalidHeader(message)
| SpeechError::InvalidFrame(message)
| SpeechError::Serialize(message)
| SpeechError::Io(message)
| SpeechError::Upstream(message) => AppError::from_status(StatusCode::BAD_GATEWAY)
.with_details(json!({
"provider": PROVIDER,
"message": message,
})),
}
}
fn map_ws_send_error(error: UpstreamWsError) -> SpeechError {
SpeechError::Upstream(format!("发送火山语音 WebSocket 帧失败：{error}"))
}
fn map_client_ws_send_error(error: axum::Error) -> SpeechError {
SpeechError::Upstream(format!("发送浏览器语音 WebSocket 帧失败：{error}"))
}
#[cfg(test)]
mod tests {
use axum::{
body::Body,
http::{Request, StatusCode},
};
use http_body_util::BodyExt;
use serde_json::Value;
use tower::ServiceExt;
use super::*;
use crate::{app::build_router, config::AppConfig, state::AppState};
#[tokio::test]
async fn speech_config_route_requires_authentication() {
let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
let response = app
.oneshot(
Request::builder()
.uri("/api/speech/volcengine/config")
.body(Body::empty())
.expect("request should build"),
)
.await
.expect("request should complete");
assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
}
#[tokio::test]
async fn speech_config_route_returns_no_secret_fields() {
let mut config = AppConfig::default();
config.volcengine_speech_api_key = Some("secret-key".to_string());
let state = AppState::new(config).expect("state should build");
state
.seed_test_phone_user_with_password("13800138088", "Password123")
.await;
let app = build_router(state);
let login_response = app
.clone()
.oneshot(
Request::builder()
.method("POST")
.uri("/api/auth/entry")
.header("content-type", "application/json")
.body(Body::from(
json!({
"phone": "13800138088",
"password": "Password123"
})
.to_string(),
))
.expect("login request should build"),
)
.await
.expect("login should complete");
let login_body = login_response
.into_body()
.collect()
.await
.expect("login body should collect")
.to_bytes();
let login_payload: Value =
serde_json::from_slice(&login_body).expect("login body should be json");
let token = login_payload["token"].as_str().expect("token should exist");
let response = app
.oneshot(
Request::builder()
.uri("/api/speech/volcengine/config")
.header("authorization", format!("Bearer {token}"))
.body(Body::empty())
.expect("request should build"),
)
.await
.expect("request should complete");
assert_eq!(response.status(), StatusCode::OK);
let body = response
.into_body()
.collect()
.await
.expect("body should collect")
.to_bytes();
let payload_text = String::from_utf8_lossy(&body);
assert!(!payload_text.contains("secret-key"));
assert!(!payload_text.contains("apiKey"));
assert!(payload_text.contains("asrResourceId"));
}
}

Some files were not shown because too many files have changed in this diff Show More