Genarrative/CONTEXT.md

# Genarrative Domain Context

Genarrative 是一个 AI 原生互动内容与小游戏平台，当前上下文记录团队在玩法、作品、运行态和平台闭环中使用的领域语言。

## 平台创作工具

**表单/图片输入创作工作台**:
新增玩法默认采用的创作工具模式，用户通过结构化表单、图片槽位和配置控件提交创作输入，链路覆盖入口、工作台、生成页、结果页、试玩、发布和运行态闭环。
_Avoid_: 默认对话式 Agent 工作台、默认轻输入 Agent 工作台、复制既有玩法工作台

**单图资产编辑**:
角色形象、UI 背景、容器、封面、分享图等单张图资产的统一输入与重生成方式，统一通过 `CreativeImageInputPanel` 表达上传、AI 重绘、参考图、历史图和删除确认。
_Avoid_: 在玩法页面内手写上传、参考图、重绘、预览、删除确认

**图片画布工程**:
独立 `/editor` 中可保存、恢复和继续编辑的图片画布工作状态，包含画布视图、图层布局和资源引用；用于多图对比、生成结果衍生和画布级编辑，不替代玩法页面内的单图资产编辑。
_Avoid_: 玩法结果页单图槽位、发布态作品、只存在前端内存里的临时画布

**项目开发画布**:
GameAgent 独立客户端中某个本地游戏项目的开发工作区概念，用于承载项目名、路径、首条需求、附件导入结果、最近 run 状态，以及后续真正的项目开发画布与 Agent 协作界面；当前首页改造阶段先落占位页。它属于 AI 游戏创作本地项目域，不等同于 `/editor` 的图片画布工程。
_Avoid_: `/editor` 图片画布工程、画布资源 / 图层布局、启动器 / 主窗口切换概念、只用于首页输入的临时草稿

**画布Agent对话**:
图片画布工程右侧的对话式编辑器工具，用户通过自然语言调度画布已有的图片类生成与编辑能力（生成图片、生成角色形象、生成图标素材、生成 UI 设计图、基于附件的图片修改），并可附加画布素材或素材库图片作为参考；对话归属单个图片画布工程，可保存历史、新开会话和软删会话。属于画布域工具，不承接玩法创作、不产出玩法作品或模板，与「表单/图片输入创作工作台」的 Avoid 边界不冲突。
_Avoid_: 对话式玩法创作工作台、绕过模型定价收口的生成入口、把对话消息当作画布布局真相、复用拼图专用 creative-agent 内存会话

**画布Agent会话记录**:
画布Agent对话的持久化形态：SpacetimeDB 表只存会话元数据（会话 ID、所属工程、属主、标题、软删标记、聊天记录 OSS 对象引用、时间戳），完整消息内容以会话粒度 JSON 对象存 OSS，追加消息即整体重写对象。
_Avoid_: api-server 内存会话、消息全文入 SpacetimeDB 表、对话混入工程布局快照、每条消息一个 OSS 对象

**画布Agent对话附件**:
画布Agent对话消息携带的图片参考，统一为画布资源 / 素材库对象引用（resourceId / assetId + 可选 objectKey），单条消息上限 9 张；上传图片若从对话入口进入，必须复用素材库 / 画布资源登记链路，在上传格未落地前只从已有画布资源和账号素材库选择，不存在只属于对话的第三种图。
_Avoid_: 对话私有图片副本、内嵌 base64 附件、音视频附件

**画布资源**:
图片画布工程中可被一个或多个图层引用的图片资源记录，保存 OSS 对象引用、上传 / 生成来源、提示词、模型、任务和尺寸等资源元数据；同一资源可以在工程布局中出现多次。
_Avoid_: 图层位置、前端 hover / selected 状态、直接内嵌图片二进制

**图层布局**:
图片画布工程中描述资源实例如何摆放的画布结构，包含 resourceId、位置、尺寸、缩放、层级和选中所需的稳定图层 ID；布局属于工程快照，不属于画布资源本身。
_Avoid_: 把同一资源的全局元数据和某一次摆放坐标混在同一条资源记录里

**生成资源**:
由图片生成或图片修改流程产生的画布资源，必须记录来源资源、提示词、实际提示词、模型、provider、任务 ID 和生成时间；本期 `/editor` 的生成修改先允许 mock 生成资源，但仍按生成资源元数据形状保存。
_Avoid_: 无来源的静态素材、只显示在 UI 但不落工程资源记录的生成结果

**图片模型历史值与使用端解析**:
图片资源中已持久化的 `gpt-image-2` 是历史业务事实，读回时保持原值；新任务使用业务模型值 `gpt-image-2.5`。当用户基于历史资源再次发起生成或编辑任务时，服务端只在新任务的使用端把历史值解析为当前业务模型，不改写历史资源。provider route 属于服务端执行与审计边界，前端不接收、不持久化、不展示，也不据此分支。
_Avoid_: 读取数据库时改写历史模型值、把 provider route 暴露为前端模型选项或公开 DTO

**图片 provider 显式路由**:
api-server 在任务入口按业务语义显式选择具体 provider model name（生成或编辑），并把同一具体名传给图片平台适配器和后台定价解析；图片平台适配器不从参考图数量或前端字段猜测任务。具体 provider model name 只存在于服务端调用、定价配置和审计边界。
后台管理 Web/API 是明确例外，可以查看和编辑两个具体定价 key；主站普通前端与公开定价 API 不接收这些 key。
_Avoid_: 让图片适配器隐式猜路由、让主站前端携带 provider model name

**业务模型**:
面向任务与产品契约的稳定模型值；当前 GPT 图片新任务的业务模型是 `gpt-image-2.5`。业务模型不等同于 provider 的具体计费/请求 model，也不暴露 provider 凭证或 endpoint。
_Avoid_: 把 provider concrete model 当作前端业务选项、用业务模型值直接推断 provider 凭证

**具体模型**:
服务端发送请求和定价使用的 concrete model name。GPT Image 2.5 生成与编辑分别是 `gpt-image-2.5-flare-c` 和 `gpt-image-2.5-sunburst-c`；nanobanana 仍使用 `gemini-3.1-flash-image-preview`。具体模型只在服务端执行、定价和审计边界出现。
_Avoid_: 把具体模型写入普通前端 DTO、让未知字符串自动选择 provider

**provider client**:
按具体模型选出的外部图片 provider 连接配置，包含 provider identity、base URL 和 API key；VectorEngine 与 Tiantoken client 共享图片协议执行器，不复制请求/响应业务逻辑。两套 required client 在 api-server 启动时构造。
_Avoid_: 在首次请求时才创建 client、在 provider client 中复制尺寸/重试/审计逻辑、跨 provider credential fallback

**历史模型值**:
已持久化的 `gpt-image-2` 或 `gpt-image-2-c` 字符串，只作为历史事实原样读取和审计；基于历史资源提交新任务时，在使用端解析为当前 GPT Image 2.5 业务任务，不回写历史记录，也不把旧值作为现役 provider route。
_Avoid_: 数据库批量改写历史值、把历史值重新路由到 VectorEngine、把兼容解析扩散到普通前端

**GPT Image 2.5 新生成展示名**:
`GPT Image 2.5` 是新生成任务的产品展示名；历史资源与既有编辑上下文不因新模型上线而改写展示语义。
_Avoid_: 把新生成展示名扩散到历史记录、历史生成器或旧编辑上下文

**系列素材图集生成**:
一组同类素材的统一批量生成方式，采用批量规划、sheet 生图、后端切图、透明化、OSS 持久化和局部重生成的通用流水线。
_Avoid_: 为每个玩法单独发明素材流水线、把系列素材建模成任一玩法专属 DTO

## Language

### Puzzle Clear

**拼消消**:
基于拼图交换 / 拖拽手感的新玩法模板，玩家移动 1x1 卡牌碎片，把同一复合图案组拼成完整矩形后消除，并由顶部对应纵列补牌继续游玩。
_Avoid_: 拼图整图过关、三消槽位玩法、前端本地裁决

**复合图案组**:
拼消消中可被消除的一幅小图，由 `1x2`、`1x3`、`2x2` 或 `2x3` 的 1x1 卡牌碎片组成；只有组内碎片按正确相对位置拼成完整矩形后才消除。
_Avoid_: 单张卡牌、整关大图、任意相邻同色块

**1x1 卡牌碎片**:
复合图案组被服务端切成的最小可移动单位，带有所属组、形状、组内坐标和图片资产。
_Avoid_: 前端临时裁图、无所属图案的普通方块

**半锁定拼接组**:
非 2 格复合图案组中已经局部完成的拼接状态，可作为整体拖动；玩家用外部单格撞入组内某格时只交换该格，其余部分保留并退回半完成状态。
_Avoid_: 永久锁死、补牌打散、完整消除

**顶部卡牌准备区**:
拼消消棋盘上方按纵列排列的背面卡牌队列；某列产生空位时，准备区对应列的卡牌从顶部下落补齐。
_Avoid_: 全局随机发牌槽、底部三消槽

**防死局发牌**:
拼消消开局和每次补牌后由后端保证至少存在一步可拼接；补牌时至少有一张新掉落卡能与场上剩余某张卡对应。
_Avoid_: 前端提示代替可解性、完全随机补牌

### Wooden Fish

**敲木鱼**:
轻量点击型互动玩法，玩家在单次运行中点击非功能区敲击中央物品，触发敲击音效、敲击动画、随机飘字和本次运行内的词条计数。
_Avoid_: 长期功德账本、排行榜玩法、全局账户累计

**敲击物图案**:
敲木鱼作品中被玩家点击敲击的单张物品图案；默认模板使用内置透明 PNG `/wooden-fish/default-hit-object.png`，用户自定义关键词或上传图时再使用 image2 生成最终资产，上传图只作为 image2 参考。
_Avoid_: 直接把上传图作为运行态素材、系列素材图集

**敲木鱼背景环境图**:
敲木鱼作品中的竖屏 9:16 背景资产；由后端在敲击物图案生成后，以新敲击物图案作为主题和画风参考，再结合用户原始题材关键词或参考图主题调用 image2 生成。背景只适配敲击物主题和画风，不包含敲击物本体或木槌互动物品。
_Avoid_: 把背景当封面图、在背景里重复绘制敲击物、让前端临时拼背景

**敲击音效**:
敲木鱼作品中每次有效敲击播放的短音频资产，可由描述生成、文件上传或麦克风录制产生，最终统一写回作品的敲击音效资产槽位。
_Avoid_: 背景音乐、长音频轨道、运行态实时录音

**飘字**:
每次有效敲击后从作品配置中等概率抽取词条，并在敲击物上方以“词条+1”短暂漂浮显示的文本；配置里只保存幸运、健康、财富、姻缘、幸福、事业、成功、功德等词条名本身。
_Avoid_: 带权重奖励、账户属性、可结算货币

**单次 run 计数**:
敲木鱼运行态只在当前 run 内累计总敲击次数和已出现飘字词条计数，run 结束后作为摘要保存，不形成账号级长期账本。
_Avoid_: 用户永久功德值、跨作品累计值、排行榜积分

### Bark Battle

**汪汪声浪大作战**:
浏览器 2D 声控对战玩法，玩家通过麦克风响度触发声浪并推动能量条。
_Avoid_: 狗叫识别游戏、声纹识别玩法

**有效声浪触发**:
玩家麦克风采样点的归一化响度在冷却结束后达到或超过有效阈值时产生的一次计分输入。
_Avoid_: 有效叫声持续时长、狗叫识别结果、等待回落后的叫声

**有效阈值**:
用于判定麦克风采样是否产生有效声浪触发的响度门槛。
_Avoid_: 狗叫识别阈值、语义识别阈值

**声浪冷却**:
两次有效声浪触发之间必须满足的最小时间间隔。
_Avoid_: 叫声持续时长、回落等待时间

**能量条**:
表示玩家与对手当前声浪优势的连续对抗刻度。
_Avoid_: 血条、分数条

**单局结果**:
一局 Bark Battle 结束后形成的胜负、平局和派生统计摘要。
_Avoid_: 原始音频记录、语音内容

**Bark Battle 平台作品闭环**:
Bark Battle 从创作配置、发布作品、正式运行态到单局结果记录和作品统计的完整平台流程。
_Avoid_: 孤立 demo、只做表现深化

**轻创作配置作品**:
创作者只配置展示与难度预设字段、但不能直接配置公平性敏感规则的 Bark Battle 作品。
_Avoid_: 完整规则编辑器、固定官方关卡

**难度预设**:
Bark Battle 作品中用于选择 AI 对手行为强度的发布态配置值。
_Avoid_: 阈值配置、分数公式配置

**排行榜分榜**:
排行榜按作品、难度预设和规则集版本拆分后的独立排名空间，只收录后端裁决为玩家胜利的单局结果。
_Avoid_: 全难度混排、跨规则版本混排、失败刷分榜

**后端裁决结果**:
后端根据 start run 记录和 finish 派生指标校验后生成的正式单局结果。
_Avoid_: 前端最终分数、客户端胜负裁决

**派生指标**:
前端从本地 runtime 汇总出的不可还原原始音频的单局统计值。
_Avoid_: 原始音频、可还原语音内容

**作品统计投影**:
按作品聚合的 Bark Battle 游玩开始、完成结果、反作弊标记和最佳/平均表现摘要。
_Avoid_: 只从排行榜反推、原始音频分析、留存分析

**个人历史成绩**:
玩家本人可查看的 Bark Battle 最近完成记录和个人最佳摘要。
_Avoid_: 公开失败记录、完整无限历史、好友对比

**正式作品入口闭环**:
Bark Battle 作品从创作入口、作品详情、广场/作品卡片、我的作品到正式 runtime 路由的可发现、可进入流程。
_Avoid_: 内部试玩入口、独立活动专区

**轻配置编辑流程**:
Bark Battle 创作者用单页轻配置表单和预览卡片完成草稿保存与发布的创作流程。
_Avoid_: 多步骤向导、完整规则编辑器、拖拽编辑器

**Phase 2 实施顺序**:
Bark Battle 平台作品闭环按契约与领域规则、后端存储/API、最小前端纵切、投影体验、收口验证的顺序推进。
_Avoid_: mock 先行堆积、前后端各自发散、先做排行榜 UI

## Relationships

- 一个 **汪汪声浪大作战** 单局包含多个 **有效声浪触发**。
- 每个 **有效声浪触发** 必须达到 **有效阈值** 并满足 **声浪冷却**。
- **有效声浪触发** 推动 **能量条**。
- **能量条** 在倒计时结束时产生一个 **单局结果**。
- **单局结果** 可以被后端记录为派生摘要，但不包含原始麦克风音频。
- **Bark Battle 平台作品闭环** 包含发布态作品配置、**正式作品入口闭环**、run start / finish、个人历史成绩、**作品统计投影** 和最小排行榜。
- Phase 2 的 Bark Battle 作品是 **轻创作配置作品**，通过 **轻配置编辑流程** 创建；配置范围限制为标题、描述、主题/背景预设、狗狗皮肤预设和排行榜开关，其中 **难度预设** 只影响 AI 对手行为。
- **排行榜分榜** 由 `workId + difficultyPreset + rulesetVersion` 唯一确定，只收录 `serverResult = player_win` 的单局结果。
- **单局结果** 的正式胜负、分数与排行榜成绩来自 **后端裁决结果**；前端只提交 **派生指标**，客户端结果仅用于 debug/对账。
- **作品统计投影** 计入成功 start run 的 playStartCount、后端接受 finish 的 finishCount、胜/平/负、flagged、leaderboard 以及最佳/平均能量表现。
- **个人历史成绩** 由最近记录列表和个人最佳摘要组成，只允许本人查看；排行榜只公开入榜胜利成绩。
- **正式作品入口闭环** 必须覆盖创作入口、作品详情 CTA、广场/作品卡片、我的作品/个人作品架、稳定作品 ID runtime 路由和 `work_play_start` 埋点。
- **Phase 2 实施顺序** 固定为：契约与领域规则 → SpacetimeDB 表/reducer 与 api-server BFF → 最小前端纵切 → 投影与列表体验 → 收口验证。

## Example dialogue

> **Dev:** “第二阶段排行榜要按玩家狗叫持续时间排序吗？”
> **Domain expert:** “不按持续时间；Bark Battle 的计分输入是有效声浪触发，排行榜只能基于触发次数、峰值、能量条结果等派生摘要。”

## Flagged ambiguities

- “有效叫声”曾同时指代持续时长合规的声音片段和瞬时响度触发；已解析为 **有效声浪触发**，不再要求 `minBarkDurationMs` / `maxBarkDurationMs`，也不等待响度回落。
- “第二阶段”曾可能指玩法表现深化或平台接入；已解析为 **Bark Battle 平台作品闭环**，优先补正式 play type、作品配置、发布、正式 runtime、结果持久化、历史成绩、作品统计和最小排行榜。
- “创作者可配置作品”曾可能指完整规则编辑器；已解析为 **轻创作配置作品**，Phase 2 不允许创作者直接配置单局时长、有效阈值、声浪冷却、AI 细粒度参数、分数公式或反作弊阈值。
- “难度预设”曾可能影响阈值、冷却或计分；已解析为只影响 AI 对手行为，排行榜按 `workId + difficultyPreset + rulesetVersion` 分榜。
- “单局结果”曾可能由前端直接决定；已解析为必须由 **后端裁决结果** 决定，前端只提交触发次数、音量、能量、连击、时长等 **派生指标**。
- “排行榜成绩”曾可能收录胜/平/负或按触发次数排序；已解析为只收录玩家胜利局，并以 `finalEnergy` 优先、`triggerCount` / `maxVolume` / 标准局时长接近度 / `finishedAt` 作为后续排序因子。
- “作品统计”曾可能只从排行榜反推；已解析为独立 **作品统计投影**，失败、平局和 flagged finish 都可进入统计，但 rejected finish 不进入完成统计。
- “个人历史成绩”曾可能指完整无限历史或公开记录；已解析为仅本人可见的最近记录列表 + 个人最佳摘要，不公开失败、平局或 flagged 历史。
- “入口闭环”曾可能只指内部 demo 或单个详情 CTA；已解析为 **正式作品入口闭环**，不新增独立专区或活动页。
- “创作编辑”曾可能指多步骤向导或完整编辑器；已解析为 **轻配置编辑流程**，使用单页表单 + 预览卡片完成保存草稿、发布和发布后跳转作品详情。
- “实施顺序”曾可能按 UI 或功能并行发散；已解析为契约/领域规则先行，再做后端存储/API，随后打通最小前端纵切，最后补投影体验与收口验证。