GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity
Files
793d82cccd80fea373e86ae1a205a54b5df55c5e
Genarrative/.hermes/shared-memory/decision-log.md
kdletters 86fc382413
Some checks failed
CI / verify (push) Has been cancelled
Details
feat: add shared runtime input device layer
2026-05-10 17:50:00 +08:00

34 KiB
Raw Blame History

决策记录

用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。

记录格式

## YYYY-MM-DD 决策标题

- 背景：为什么需要这个决策
- 决策：最终决定是什么
- 影响范围：涉及哪些模块/文档/流程
- 验证方式：如何确认决策仍有效
- 关联文档：相关 PRD、技术文档、提交或 Issue

2026-05-10 运行态输入设备抽象层全项目通用化

  • 背景：拼图运行态接入 mocap 后，鼠标/触控和 mocap 各自维护输入逻辑会导致合并大块、拖拽语义和取消会话行为不一致；后续其他玩法也需要复用体感、摇杆、键盘等设备输入。
  • 决策：前端运行态输入统一通过 src/services/input-devices/ 承接，设备适配层只输出 press / move / release / tap / drop 等通用语义和通用坐标；玩法组件自己解释目标对象、落点和业务动作，输入层不得写拼图等玩法专用规则。
  • 影响范围：拼图运行态鼠标/触控/mocap 输入、后续运行态设备接入、运行态输入技术文档与相关前端回归测试。
  • 验证方式：执行 npm run test -- src\services\input-devices\runtimeDragInputController.test.ts、npm run test -- src\components\puzzle-runtime\PuzzleRuntimeShell.test.tsx、npm run typecheck 和编码检查。
  • 关联文档：docs/technical/RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md、docs/technical/PUZZLE_RUNTIME_FRONTEND_LOGIC_REHOME_2026-05-02.md。

2026-05-09 GPT-image-2 图片生成统一迁移到 VectorEngine

  • 背景：仓库内 RPG、拼图、方洞和本地模板脚本的 GPT-image-2 生图此前依赖 APIMart 图片网关；团队要求参考 VectorEngine Apifox api-448710071，后续不再使用 APIMart 执行 GPT-image-2 图片生成。
  • 决策：所有 GPT-image-2 生图请求统一走 VectorEngine POST /v1/images/generations，基础配置读取 VECTOR_ENGINE_BASE_URL / VECTOR_ENGINE_API_KEY / VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS，上游模型使用 gpt-image-2-all，请求体不再携带 official_fallback，参考图字段改为 image。APIMart 只保留给创意 Agent 的 gpt-5 Responses 文本/多模态链路。
  • 影响范围：api-server 共享图片 helper、拼图图片生成、角色主图、RPG 场景图、开局 CG 故事板、方洞视觉资产、生产环境示例、gpt-image-2 本地 skill 和相关技术文档。
  • 验证方式：执行 npm run check:encoding、cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml、cargo test -p api-server puzzle --manifest-path server-rs/Cargo.toml、cargo test -p api-server custom_world_ai --manifest-path server-rs/Cargo.toml、cargo test -p api-server character_visual --manifest-path server-rs/Cargo.toml，并用 npm run api-server + /healthz 做后端 smoke。
  • 关联文档：docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md、docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md。

2026-05-08 Hyper3D Rodin Gen-2 只通过后端安全代理接入

  • 背景：需要接入 Hyper3D Rodin Gen-2 的文生 3D 模型与图生 3D 模型，但供应商 API Key 不能进入前端、文档或 Git；本次只是外部副作用代理，不需要新增平台真相表。
  • 决策：Hyper3D 统一走 api-server 的 /api/assets/hyper3d/* 鉴权路由，配置只读取 HYPER3D_BASE_URL / HYPER3D_API_KEY / HYPER3D_MODEL_REQUEST_TIMEOUT_MS 及兼容 RODIN_* 变量；生成提交、状态查询和下载列表都由后端代理。首版不写 SpacetimeDB、不确认 asset_object，下载链接后续由调用方决定是否进入 OSS 资产链。
  • 影响范围：api-server 外部服务配置、Hyper3D route、shared-contracts / TS contract、前端 service、生产环境示例和外部服务环境变量文档。
  • 验证方式：执行 cargo test -p api-server hyper3d --manifest-path server-rs/Cargo.toml、cargo test -p shared-contracts hyper3d --manifest-path server-rs/Cargo.toml、cargo check -p api-server --manifest-path server-rs/Cargo.toml、npm run typecheck 和编码检查；真实 API smoke 只在本地私密环境配置 key 后手动执行。
  • 关联文档：docs/technical/HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md、docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md。

2026-05-08 APIMart 接口统一携带 official_fallback

2026-05-09 追认：本决策中的图片生成部分已被“GPT-image-2 图片生成统一迁移到 VectorEngine”覆盖；当前只保留 APIMart gpt-5 Responses 文本/多模态链路继续显式携带 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 等依赖时容易漂移。
  • 决策：server-rs/Cargo.toml 的 [workspace.dependencies] 统一维护第三方依赖版本和 workspace 内部 crate path；成员 crate 默认使用 { workspace = true }，只保留自身 feature、optional 或 target-specific 差异；不再新增 sha1，OSS 与阿里云 OpenAPI 签名统一走 sha2::Sha256 对应的 V4/V3 口径。
  • 影响范围：server-rs/Cargo.toml、所有 server-rs/crates/*/Cargo.toml、platform-oss、platform-auth、后续新增 Rust crate 或新增 Rust 依赖的开发流程。
  • 验证方式：修改 Cargo 配置后先执行 cargo metadata --manifest-path server-rs\Cargo.toml --format-version 1 --no-deps，再按影响范围执行 cargo check、DDD 边界检查和编码检查。
  • 关联文档：docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md。

2026-05-08 资料页反馈提交必须走 Rust 后端与 SpacetimeDB

  • 背景：/profile/feedback 首版页面曾只做前端成功态，无法沉淀到用户账号和数据库，也容易与主站平台主题脱节。
  • 决策：反馈提交统一走鉴权 HTTP 路由 POST /api/profile/feedback，由 api-server 取当前 access token 用户，调用 spacetime-client facade，再通过 spacetime-module procedure 写入私有表 profile_feedback_submission；前端只负责输入采集、Data URL 预览和提交元数据，不再保存 File[] 作为外部契约。
  • 影响范围：src/components/platform-entry/PlatformFeedbackView.tsx、src/services/rpg-entry/rpgProfileClient.ts、packages/shared/src/contracts/runtime.ts、server-rs/crates/shared-contracts、api-server、module-runtime、spacetime-client、spacetime-module、表目录与 bindings。
  • 验证方式：前端定向测试应覆盖 Data URL 预览与 /api/profile/feedback 请求体；后端变更需同步 migration.rs、SPACETIMEDB_TABLE_CATALOG.md 和生成绑定；API smoke 使用 npm run api-server 和 /healthz。
  • 关联文档：docs/prd/PROFILE_FEEDBACK_ENTRY_PRD_2026-05-08.md、docs/technical/PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md。

2026-05-06 Maincloud 历史残留引用禁止再使用

  • 背景：项目已经全面移除 Maincloud 运行口径，但历史脚本、测试名和文档仍可能让后续开发误用 api-server:maincloud 或 GENARRATIVE_SPACETIME_MAINCLOUD_*。
  • 决策：maincloud / Maincloud / MAINCLOUD 相关代码、脚本、测试、环境变量、命令和文档要求全部视为历史残留，后续禁止新增、运行或引用；后端 API smoke 统一使用 npm run api-server 并检查 /healthz。
  • 影响范围：AGENTS.md、docs/technical/、.hermes/shared-memory/、后端启动脚本、测试支撑和所有后续工程文档。
  • 验证方式：新增或修改后端相关文档时，检查不得要求 api-server:maincloud 或 GENARRATIVE_SPACETIME_MAINCLOUD_*；触碰历史残留时同步删除或改名。
  • 关联文档：docs/technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md、docs/technical/SPACETIMEDB_CLOUD_CONFIG_REMOVAL_2026-05-02.md。

2026-05-05 新手引导首版复用拼图本地运行时

  • 背景：首次打开产品的新用户需要先体验输入想法、生成拼图、通关、登录保存、回到首页的闭环，但首版不应引入新的持久化表或独立玩法运行时。
  • 决策：未登录首次访问由前端 localStorage 标记触发；生成入口走公开 BFF POST /api/runtime/puzzle/onboarding/generate 生成 1 关临时拼图；登录后保存走鉴权 BFF POST /api/runtime/puzzle/onboarding/save，由服务端创建当前用户拼图 agent session 并更新其草稿作品 profile；游玩阶段复用现有本地拼图运行时。
  • 影响范围：平台入口首屏、新手引导 PRD、拼图 BFF、拼图作品契约与前端 puzzle runtime。
  • 验证方式：未登录首次访问应展示新手引导；生成后只进入 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，并需要独立拉取仓库、修改代码、本地测试；团队希望形成共享的长期项目记忆。
  • 决策：不共享个人 ~/.hermes，先在 Genarrative 仓库内使用 .hermes/ 保存可 Git 同步的团队共享记忆、计划和未来 skills。
  • 影响范围：AGENTS.md、.hermes/README.md、.hermes/shared-memory/。
  • 验证方式：任一开发者拉取仓库后，在项目根目录启动 Hermes，均可读取同一套 .hermes/shared-memory/ 文件。
  • 关联文档：.hermes/README.md、.hermes/shared-memory/team-conventions.md。

2026-04-25 后端唯一落地口径固定为 Rust / SpacetimeDB

  • 背景：项目经历过 Node/Express/PostgreSQL、Go 试验、Rust/SpacetimeDB 等多条后端路线，旧路线文档容易造成开发歧义。
  • 决策：新功能以后端当前基线为准：HTTP 门面使用 Rust api-server / Axum，业务真相使用 SpacetimeDB，领域和契约在 server-rs 多 crate 分层维护。
  • 影响范围：所有后端、数据真相、运行时状态、创作结果、用户系统、资产、任务、埋点、后台 API 等相关开发。
  • 验证方式：开发前优先阅读 CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md；旧 server-node、Express、PostgreSQL、Go 方向只允许作为迁移参考。
  • 关联文档：docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md、AGENTS.md。

2026-04-28/29 server-rs DDD 分层与契约矩阵冻结

  • 背景：server-rs 模块多、上下文多，需防止领域规则、SpacetimeDB 表、HTTP BFF、前端临时逻辑互相污染。
  • 决策：按 DDD 总纲和 G1 契约/路由矩阵开发：module-* 承载领域，spacetime-module 承载表和事务，spacetime-client 承载 facade，api-server 承载 HTTP/SSE/BFF，platform-* 承载外部副作用，shared-contracts 承载 DTO。
  • 影响范围：server-rs 全部 crate、前端 API client、SpacetimeDB schema、旧接口清理。
  • 验证方式：执行任务前对照 DDD 总纲、并行任务清单、G1 矩阵；提交前运行相关 DDD 边界检查和定向测试。
  • 关联文档：SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md、SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md、SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md。

SpacetimeDB 表结构变更必须显式维护迁移与表目录

  • 背景：SpacetimeDB 的 schema 迁移模型不同于 PostgreSQL，部分变更会触发冲突或拒绝自动迁移。
  • 决策：凡涉及 table、reducer、procedure、row shape 或 binding 变化，必须同步 migration.rs、表目录和生成绑定；涉及 private 表迁移时按 JSON 导入导出和分片导入流程处理。
  • 影响范围：server-rs/crates/spacetime-module、spacetime-client bindings、SPACETIMEDB_TABLE_CATALOG.md、部署/发布脚本。
  • 验证方式：发布前检查 SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md 清单，更新 SPACETIMEDB_TABLE_CATALOG.md，执行生成绑定和相关测试。
  • 关联文档：SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md、SPACETIMEDB_TABLE_CATALOG.md、SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md。

生产部署切换到 systemd + Nginx + 自托管 SpacetimeDB

  • 背景：旧一体化启动脚本和历史 Jenkinsfile 已不再是生产发布唯一入口。
  • 决策：生产部署以 systemd 托管 SpacetimeDB 与 Rust api-server，Nginx 负责站点和代理，生产 Jenkinsfile 按 web/api/stdB module/build/deploy/publish 拆分。
  • 影响范围：部署脚本、服务器目录、维护模式、Jenkins、Nginx、systemd 服务。
  • 验证方式：生产发布、服务器配置、Jenkins Job 重建或回滚时，先看 PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md。
  • 关联文档：PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md。

个人任务与埋点首版边界冻结

  • 背景：“我的”Tab、任务、奖励、钱包和埋点涉及用户、运营、分析多条链路，需要避免范围泛化。
  • 决策：埋点原始事实进入 tracking_event，聚合投影进入 tracking_daily_stat；个人任务配置/进度/领奖/钱包分别进入 profile_task_config、profile_task_progress、profile_task_reward_claim、profile_wallet_ledger；首版个人任务 scope 仅支持 user。
  • 影响范围：用户侧任务中心、后台任务配置、运营查询、埋点查询、钱包流水。
  • 验证方式：非 user scope 的个人任务配置应被 API 和领域构造层拒绝；任务查询与埋点查询分别放在 docs/operations/ 和 docs/tracking/。
  • 关联文档：PROFILE_TASK_AND_TRACKING_SYSTEM_2026-05-03.md、RUNTIME_PROFILE_TASK_SCOPE_2026-05-04.md、ANALYTICS_DATE_DIMENSION_IMPLEMENTATION_2026-05-04.md。
Reference in New Issue View Git Blame Copy Permalink