diff --git a/.agents/skills/staging-ops.md b/.agents/skills/staging-ops.md index 64e2b844..4f347283 100644 --- a/.agents/skills/staging-ops.md +++ b/.agents/skills/staging-ops.md @@ -40,6 +40,10 @@ > **教训速记（区分两个隔离用法）**:同样起 `:48090` 隔离实例——「重部署安全变体」目标是**最终要切 live**（验全过 → 停老起新）;「`-D` 注入真验 flag」目标是**永不切 live**（只验 flag 行为,验完即停,主干字节不变）。混用会误把"只想验 flag"做成了"切 live"。 +> **后端接 staging 前环境检查:代理劫持防护（创始人 2026-06-22 历史回收判定捡回·边际登记）**。staging 机若装了 mihomo 之类代理客户端(占 7890/9090),Java 进程连内网 MySQL/Redis 可能被代理拦截,表现为莫名其妙的连接失败。接线前先把内网网段 `100.64.0.0/10` 加进 `no_proxy`/JVM `nonProxyHosts`,放行内网中间件连接。(与生成域 new-api 出网调模型的 no_proxy 是两个场景:那条放行出网,这条放行内网。) + +> **边际登记(创始人 2026-06-22 历史回收判定,真部署时补,不在此展开)**:① **快检部署落点**(运维 033)——`deploy/smoke-test.sh` 等就绪快检在哪台机怎么跑,真部署时在本配方 §5 补;② **观测数据保留期**(运维 034)——trace/metrics 存多久、和 `security-and-reliability.md` §6 的日志保留期(ERROR/WARN 90 天、INFO 30 天)、磁盘水位告警(运维 021)、¥500/月监控预算(运维 027)一起对账,观测栈真上线时定;③ **staging 数据脱敏子集归属**(运维 006)——真上线后 staging 要不要用生产数据脱敏子集来验(暴露真实数据分布下的 bug),是运维-合规交叉约束,**待定**(现状 staging 是 seed 假数据,可幂等重建)。 + ## 4. 构建/测试门（红线） - **`vue-tsc --noEmit` 是假门禁**，前端验证一律 `npm run build`。 diff --git a/docs/architecture/产品/README.md b/docs/architecture/产品/README.md index d0d23b8b..8813e241 100644 --- a/docs/architecture/产品/README.md +++ b/docs/architecture/产品/README.md @@ -69,18 +69,18 @@ flowchart TB - **编号** `P-{域}-{序号}`:例如 `P-CRT-01` 表示"自定义创作"域的第 1 条需求。域用三字母缩写(MAT 素材、TPL 模板、CRT 创作……)。 - **端**:这条功能服务谁——**创作者**、**玩家**、**经营**(创作者查看自己作品的数据)、**运营**(平台管理员)、**B端**(企业客户)、或**通用**。 -- **优先级**:**P0** = MVP 阶段必须验收的功能(全部 155 条里有 **55 条 P0**);**P1 / P2** = 后续迭代。 +- **优先级**:**P0** = MVP 阶段必须验收的功能(全部 158 条里有 **55 条 P0**);**P1 / P2** = 后续迭代。另有一档 **P0-lite**(创作者基础播放数据 P-OPS-01),是供给侧留存断点的轻量必做,独立于 55 P0 头号口径。 - **来源**:**demo** = 早期原型演示里出现过;**v2.0** = 延续既有能力;**G#** = demo 暴露出的缺口编号。 --- -## 4. MVP 的边界:155 选 55 +## 4. MVP 的边界:158 选 55 -完整产品有 **155 条需求**,分布在 19 个域。MVP 阶段不全做,而是聚焦其中 **55 条 P0**——它们刚好串起一条"种子用户可试用的全链路":创建 → 生成 → 预览 → 发布 → 信息流 → 游玩 → 互动 → 广告 → 收益。 +完整产品有 **158 条需求**(2026-06-22 历史回收补登 3 条入口/账号面后,从 155 升到 158),分布在 19 个域。MVP 阶段不全做,而是聚焦其中 **55 条 P0**——它们刚好串起一条"种子用户可试用的全链路":创建 → 生成 → 预览 → 发布 → 信息流 → 游玩 → 互动 → 广告 → 收益。 ```mermaid flowchart LR - P155["155 条产品需求
(完整产品)"] --> P55["55 条 P0
(MVP 验收口径)"] + P158["158 条产品需求
(完整产品)"] --> P55["55 条 P0
(MVP 验收口径)"] P55 --> LOOP["覆盖全链路闭环
create → play → earn"] ``` @@ -92,7 +92,7 @@ flowchart LR | 文档 | 回答什么 | |---|---| -| [需求清单](需求清单.md) | 完整的 155 条产品需求,按 19 个域逐条列出 | +| [需求清单](需求清单.md) | 完整的 158 条产品需求,按 19 个域逐条列出 | | [需求模块映射](需求模块映射.md) | 每条产品需求由哪些技术模块实现(连接[架构域](../架构/README.md)) | | [护城河话术](护城河话术.md) | 对外融资沟通时,产品与商业层面的统一口径 | diff --git a/docs/architecture/产品/商业定位.md b/docs/architecture/产品/商业定位.md index cb4aab69..38dae599 100644 --- a/docs/architecture/产品/商业定位.md +++ b/docs/architecture/产品/商业定位.md @@ -35,10 +35,16 @@ quadrantChart | 竞品 | 强 | 空白 | 绘境AI 如何避开 | |---|---|---|---| -| 极逸 SOON(融资近 1 亿) | 自研三引擎 + 产业大模型 | 无流量、无变现闭环 | 不自研引擎,用开源组合;钱花在流量和变现上 | +| 极逸 SOON(融资近 1 亿【据竞品自述/单源·待核】) | 自研三引擎 + 产业大模型【无外部佐证·待核】 | 无流量、无变现闭环 | 不自研引擎,用开源组合;钱花在流量和变现上 | | TapTap 制造(上市公司) | 有流量 | 封闭、不能多渠道、分成低 | 开放多渠道、创作者拿 80% 分成 | | FunloomAI(估值 2 亿) | 有付费验证 | 品类窄、无流量 | 多模板多品类、自建游戏流 | +> 上表的竞品融资/估值数字一律标注【待核】(创始人 2026-06-22 历史回收判定捡回):外部核查只把"极逸 SOON 融资近 1 亿"核到"超千万"量级,"自研三引擎"查不到外部佐证,FunloomAI 的"百度云合作"也查无信源。这些数字目前都是据竞品自述或单一来源,进融资材料前必须降级为"据竞品自述/单源,待核",或补上可引用的信源——一个未经核实的竞品数字被尽调交叉核验时打脸,会让对方默认你其余所有陈述都注水。 + +> **这块地不是无人区:自有 feed 形态早有现任者**(创始人 2026-06-22 历史回收判定捡回)。休闲游戏信息流这种形态,摸摸鱼、233 乐园、4399、微信小游戏中心早就占着,所以绘境的差异化不能押在"自有 feed 形态"本身——光有一个游戏信息流并不构成壁垒。真正的差异在 AI 供给侧的成本结构(用 agent 闭环把生成与质检全自动化、产能成本远低于人工堆量)加上 IP 锁风保真,以及把"做得出 → 有人玩 → 赚到钱"接成一条闭环。把这条讲清楚,内部判定和对外叙事才不会两张皮:对外不能让人以为 feed 是我们发明的无人区。 + +> **TapTap 制造是同形态最大现实威胁,窗口正因它收窄**(创始人 2026-06-22 历史回收判定捡回)。上表把 TapTap 当"有流量但封闭"轻轻带过,低估了它:TapTap 制造已确证 2026-01-31 上线,做的是自然语言生成加 TapTap 渠道、免费,这是离绘境形态最近的现实威胁。窗口期判断(§6 的 6-12 个月)之所以紧迫,很大一部分压力就来自它——它证明"AI 生成小游戏 + 自有渠道"这条路有人在认真跑,绘境的领先不是时间无限的。它的相对弱点仍是封闭、不能多渠道、分成低,这正是绘境用开放多渠道加 80% 创作者分成去切的缝。 + **结论:绘境不追求技术深度第一,追求生态完整度第一。技术够用即可,生态无法复制。** --- @@ -56,6 +62,8 @@ quadrantChart > 真正归我们独家的,不是 IP(IP 非独家,只是冷启动燃料),而是**创作者沉淀在平台上、搬不走的生态资产**。详细对外口径见[护城河话术](护城河话术.md)。 +**IP 获取路径有关键人风险,需建可复制的 BD 打法(创始人 2026-06-22 历史回收判定捡回)。** 现有 IP(以王蓝莓为锚点)的授权是非独家、数年期、带分成、靠人脉拿到的。这两个属性各有代价:非独家意味着 IP 在供给侧零防御力——同一个 IP 竞品也能去签;靠人脉拿到意味着获取路径不可规模化,是一次性的、且有关键人风险(拿 IP 的关系断了,这条供给就断了)。这直接决定了 IP 对绘境到底是"一块样板"还是"一台引擎":如果 IP 获取始终停在人脉单点,它只能是冷启动样板;要让它升级成可持续的内容供给引擎,必须把"可复制的 IP BD 打法"列成一个战略待办——一套不依赖某个关键人、能批量谈下腰尾部 IP 的标准化获取流程。这条待办目前没有归属,需要尽早立起来。 + **平台方下场的风险与应对(创始人 2026-06-21 定调)。** 有一个绕不开的真实风险:如果微信、抖音这类上游平台自己上线"IP 授权 + 一句话生成",绘境的位置还在不在?诚实的判断是——平台方会做通用、做规模,但不会为腰尾部 IP 做精细保真,也不会替创作者把"做得出 → 有人玩 → 赚到钱"这条闭环一段段踩实。我们的应对不是去比平台的流量,而是往产品深处扎,扎两个平台方为了通用化不愿意做的方向:一是**深化游戏引擎的使用**——tier2 自治富游戏引擎让生成的游戏从超休闲单局走到合成、经营、挂机这类有系统深度的品类(见[架构域生成引擎子树](../架构/生成引擎/自治富游戏引擎.md));二是**深化创作能力**——把对话式创作加差量修改的完整闭环做扎实,让创作者改得动、也养得熟一个能长期运营的游戏项目。引擎深度和创作深度都是平台方为通用化不愿做的脏活,也正是创作者真正搬不走的那层资产。 --- @@ -80,6 +88,16 @@ flowchart TB > 主轴一句话:单人 + AI agent 体系的资本效率(已实证)→ B端/IP 现金线供血 → 用窗口期把供给侧成本优势滚成内容资产与数据飞轮(未来式,诚实标注)。 +### 4.1 三个仍悬着的战略缺口与待办(创始人 2026-06-22 历史回收判定捡回) + +变现叙事的供给侧讲得扎实,但有三块战略级的缺口/待办此前散在审计里没沉淀进来,这里补登,免得它们因为"不是工程任务"而在文档里失踪。 + +**玩家侧获客通路与预算,目前是零字的战略空白。** 现行叙事把供给侧(创作者激励、新人任务)铺得不错,但飞轮要转,需求侧——玩家——同样要冷启动:玩家从哪来、单个玩家获客成本多少、"10 万创作者"这个目标是怎么从玩家规模推导出来的,全部文档里至今没有答案。投资人版只给了两个变现数字,玩家侧获客通路与预算一字未写。这不是细节,是飞轮需求侧的地基,需要补出一套玩家获客的通路假设和预算口径。它和冷启动内容供给(种子游戏)是同一件事的两面:一个回答"玩家从哪来",一个回答"玩家进来看见什么"。 + +**"先把单位经济测准、再谈规模"应抬成战略级优先级。** 每款游戏的真实单位经济(LLM 成本、审核成本、广告产值)目前躺在工程待办里(变现域 W4 的按游戏粒度成本/收益埋点,见[变现与单位经济](../运营/变现与单位经济.md)§6),但它没有上升为一条战略判断。在拿到每款游戏真实的成本/收益数据之前,任何关于规模化能否回本的结论都是建在假设数上的。所以这件事不只是一个埋点待办,而是"规模化决策的前置闸门"——把单位经济测准之前,不轻易对外锁回本模型、不基于假设数做扩张承诺。这条优先级判断要明确摆在战略层,而不只是埋在工程清单里。 + +**对外融资口径与团队口径,待创始人锁一个对外单值。** 历史材料里出现过三版互斥的融资额(BP 改造版 200-1000 万 / 生态引擎 BP 3000-5000 万 / 路演稿 3000 万占 15%),团队表述也自相矛盾(对外"全职 5 人"与三位创始人"现任他司"并存)。这属于对外叙事一致性,审计明确要求创始人定一个对外单值。[护城河话术](护城河话术.md)给了诚实口径模板,但"融资额/团队表述到底锁哪个单值"这个待拍板项是否已闭合,从现行档看不出。**这是一条待办:具体单值由创始人定**,定下后回填到本节和护城河话术,确保所有对外材料口径一致。 + --- ## 5. demo 与产品的定位边界(避免拿原型当建设度) @@ -107,4 +125,29 @@ timeline --- +## 7. 增长与冷启动战略(创始人 2026-06-22 历史回收判定捡回) + +§4 的飞轮讲的是"飞轮转起来之后怎么放大",但漏了"飞轮怎么从零启动那一下"和"启动之后靠什么持续放大"。这两件事此前散在计划档里没沉淀,补在这里。 + +**开张要先有种子内容,feed 不能空着开张。** 飞轮转起来的前提是 feed 里先有一批种子内容垫底——计划档把"约 10 款种子游戏 + 首批约 10 个 demo 题材"列为飞轮启动的硬前置。道理很直接:玩家进来如果看见的是空流,既没有可玩的东西留住他,平台也无从采集任何行为数据,飞轮的第一圈根本起不来。所以开张前必须备好一份种子游戏清单(每款带模板、封面、试玩目标、埋点、审核状态),把它当成开张那天的内容底盘。这不是一个工程量问题,而是一条冷启动的内容供给约束——它和§4.1 讲的玩家获客(玩家从哪来)是一件事的两面:一个回答"玩家进来看见什么",一个回答"玩家从哪来",缺一边飞轮都启动不了。 + +**靠可运营的主题活动机制持续放大内容供给与广告库存。** 飞轮启动之后,放大它的手段是把活动运营做成产品能力:节日主题、题材挑战、模板赛道榜单、收益榜这类可运营的主题活动机制,能周期性地激发创作者多产内容、拉动玩家参与。它对变现的意义是直接的——更多内容供给意味着更多游戏可曝光,玩家参与度上来意味着更多广告库存可卖,两头都喂着流量闭环。Doc A 的 GRW 域已有"创作挑战赛"(P-GRW-02)、"创作大赛"(P-INC-05)这些散点,但"主题活动作为放大内容供给和广告库存的增长引擎"这个战略定位要立起来,而不只是当成几个孤立功能——它是冷启动后期把飞轮从能转推到转得快的关键运营手段。 + +## 8. 验收北极星:这半年算不算没白干(创始人 2026-06-22 历史回收判定捡回) + +判断这半年没白干,看的不是结构骨架建了多少,而是四件事成立没有:**有人要用、能合规上线、能采到数据、能产生收入。** 这句话是整个产品战略的北极星定义,比任何模块清单都上位,也和"结构骨架≠真实可验收""产品视角非技术视角"一脉相承——一个模块能启动不等于有人愿意用它、不等于它能合规上线、不等于它在采有用的数据、更不等于它在赚钱。把战略落到能周度跟踪的判据,就是下面这组 CEO 周看指标,创始人每周只盯这 6 个: + +| 北极星维度 | CEO 周看指标 | +|---|---| +| 能做得出(生成质量) | 生成可接受率 | +| 能玩得动(运行可靠) | 单局加载成功率 | +| 有人要用(玩家侧) | 玩家完玩率 + 次日留存 | +| 内容在转(供给侧) | 每款游戏的事件量 | +| 能合规上线(外部闸门) | 外部合规闸门状态(ICP/备案/资质进度) | +| 能赚到钱(变现) | 首个真实收入或付费意向 | + +这组指标卡是活的:具体阈值和口径随阶段调,但"创始人每周只看这 6 个"的纪律不变。它把"6 个月不后悔"从一句口号变成可核对的判据,避免方向在大量结构性工作里跑偏。指标的数据来源与看板落点在[运营域](../运营/README.md)与各模块遥测,本节只承载战略层的北极星定义与指标清单。 + +--- + > **配套**:对外怎么说见[护城河话术](护城河话术.md);成本/资本效率与单位经济见[运营域](../运营/变现与单位经济.md);技术架构如何支撑这套商业逻辑见[架构域](../架构/README.md)。 diff --git a/docs/architecture/产品/护城河话术.md b/docs/architecture/产品/护城河话术.md index e07dfc5b..cecc7f7d 100644 --- a/docs/architecture/产品/护城河话术.md +++ b/docs/architecture/产品/护城河话术.md @@ -78,6 +78,18 @@ flowchart LR - 不说"独家 IP" → 说"IP 是点火燃料,生态才是资产"。 - 不说"飞轮已成型" → 说"窗口期内点燃,钱就是用来点火的"。 +### A5. IP 叙事的诚信边界与对外红线(创始人 2026-06-22 历史回收判定捡回) + +IP 这条线讲得好能加分,讲过头会击穿信任。叙事边界、正向资产口径、法律红线、竞品数字纪律这四条得一次框死,对外讲 IP 时照此口径。 + +**主攻腰尾部 / 表情包型 IP,别讲"顶流独家"。** 在资本碾压下绘境拿不到顶流 IP 的独家授权,所以 IP 护城河的主攻层必须诚实定位在腰尾部、表情包型 IP 的规模化(已有锚点:王蓝莓)。对外讲"我们要做正版 IP 规模化"时,要自己先把战场框死在腰尾部——一旦被问"那你怎么拿顶流",如果之前暗示过顶流,叙事就崩。腰尾部不是退而求其次的说辞,而是和资本效率打法一致的选择:腰尾部 IP 议价低、可批量,正好用低成本供给侧的优势去规模化。 + +**IP 故事最该主打的正面资产是"IP 库 + IP 方信任 + 历史保真口碑",不是锁风技术。** 技术层面的东西(锁风算法、画风 LoRA)竞品都能做,讲它只能停在"我们也有",立不住壁垒。真正会随时间增厚、竞品追不上的,是签约 IP 库越攒越多、IP 方因为历史保真做得好而越来越信任你、市场对"在绘境上做的 IP 游戏不会崩人设"形成口碑——这是资产壁垒和合规壁垒的具象。所以 IP 叙事别只停在"锁风不是高深算法、价值在合规流程"这个否定式口径(那是版本 B 给 CTO 的诚实底牌),正面对投资人要把"IP 库 + 信任 + 口碑 = 真资产层"这一面讲出来,这才是 IP 故事里最有说服力的部分。 + +**🔴 法律红线:对外演示一律用自有吉祥物,不得直接用现有热门 IP 的原名原形象。** 玩法机制可以借鉴(机制不受著作权保护),但《王蓝莓的小卖部》这类现有热门 IP 的名称、美术、角色形象,在对外演示(投资人路演、公开 demo)里必须换成平台自有的吉祥物系——直接用"王蓝莓"原名原形象演示是侵权风险。这条恰好和"做平台自有吉祥物系"的方向一致:既规避法律风险,又顺势把自有 IP 立起来。合规侧的对应约束见[合规闸门](../运营/合规闸门.md)。 + +**竞品融资/估值数字对外一律标"待核"。** "极逸 SOON 融资近 1 亿"外部只核到"超千万","自研三引擎"无外部佐证;A2/A3 里引用这些数字时,口径要按"据竞品自述/单源,待核"讲,别当成实锤——尽调桌上一个未核实的竞品数字被交叉核验打脸,会连累你其余所有陈述的可信度。这条与[商业定位](商业定位.md)§2 的竞品数字纪律同源。 + --- ## 版本 B — 技术尽调面 diff --git a/docs/architecture/产品/需求清单.md b/docs/architecture/产品/需求清单.md index 039a9220..8da4bb42 100644 --- a/docs/architecture/产品/需求清单.md +++ b/docs/architecture/产品/需求清单.md @@ -56,6 +56,8 @@ flowchart TB | P-TPL-04 | 收藏模板 | 创作者 | P2 | demo | | P-TPL-05 | 购买商用模板(模板市场) | 创作者 | P1 | demo/v2.0 | +> P-TPL-01(浏览玩法模板)/ P-TPL-03(应用模板到草稿)维持 P0,产品形态定调为"玩法模板中心"(创始人 2026-06-22 历史回收判定捡回,定调玩法模板中心形态)。这里要分清两个被废弃术语纠偏后的概念:废掉的是"游戏模板"——填参即得整局的旧 4 套代码模板;**保留并待建的"玩法模板"是品类框架**(经营/剧情/解谜/TRPG/非遗等),它的作用是给创作者一个浏览品类、选中后引导 AI 往这个品类方向生成的入口,而不是一段填参就跑的成品代码。所以 P-TPL-01/03 验收的是"能浏览玩法模板库、选中后把品类框架带进创作流引导生成",落点是一个玩法模板中心,不是把旧填参模板复活。它在 MVP 内是有效 P0,但优先级排在"生成可靠"之后。 + > 上表的玩法模板面向超休闲档。经营、合成、挂机这类多系统的 premium 品类框架不在这条线上,而是由第二条生成轨——tier2 自治富游戏轨——承载;它面向价值更高、产量更低的场景,与超休闲廉价线解耦并存。这一轨目前是待 0 号 spike 验证的假设、未落代码,因此不在 MVP 的 P0 范围内,也不在这份清单里单列正式 P-id;它的设计见[自治富游戏引擎](../架构/生成引擎/自治富游戏引擎.md)。 ### 域 3　自定义创作（CRT） @@ -76,6 +78,14 @@ flowchart TB | P-CRT-13 | 生成超时后台通知 | 创作者 | P0 | v2.0 | | P-CRT-14 | 模板参数可调编辑(速度/敌数/时长/胜负) | 创作者 | P1 | v2.0 | | P-CRT-15 | 游戏流专属版本一键适配(竖屏/短时长/3秒钩子) | 创作者 | P2 | v2.0 | +| P-CRT-16 | 对话式创作"代码目录"标签(查看生成产物的文件结构) | 创作者 | P1 | demo | +| P-CRT-17 | 创作模式双标签切换(自定义创作 / 授权 IP 创作) | 创作者 | P1 | demo | + +> P-CRT-16 / P-CRT-17 是补登的(创始人 2026-06-22 历史回收判定捡回,源自 demo 审计「表述缺口」):这两条是 demo 里真实存在、但清单此前没列成行的**入口/切换面**。P-CRT-16 是智能体对话式创作(本体见 P-CRT-05)界面里的"代码目录"标签,让创作者能看生成产物的文件结构——它依附于对话流本体,不是独立功能,补行只为让读清单的人对得上 demo。P-CRT-17 是创作入口处"自定义创作 / 授权 IP 创作"两种模式的标签切换面,它跨在自定义创作(本域)和授权 IP 创作(域 4 LIC)两条线之间,是进入两条创作路径的入口开关。两者功能本体多已被既有 P-id 覆盖,补的是入口表述,优先级取 P1。 + +> **P-CRT-02 的验收口径(创始人 2026-06-22 历史回收判定捡回,实质重定义):** 六类资产(图元/角色/特效/场景/界面/音乐)的"模块化生成",落地形态是**每一类资产各挂一个独立的 AI 生成 workflow**(dify 之类的工作流编排,逐类调对应模型出对应资产),而不是要求创作者在工作坊里逐类手工生成、再拼装成一局游戏。当前生成主线是"一句话直出 + 附件装配"(见 P-CRT-01 / P-CRT-04),用户不必逐类操作六个资产模块;P-CRT-02 描述的是底层把资产按六类拆开、各走一条生成链的能力组织方式,验收按"六类资产各有独立生成通路、可被主线编排调用"来认,不按"工作坊里六模块逐一手工生成"来认。具体的 workflow 编排设计在[架构域](../架构/README.md)。 + +> **P-CRT-03 / P-CRT-06 / P-CRT-07(图生文生角色 / 角色骨骼拆件多动作编辑 / 导出角色动作包)= premium 远期方向(创始人 2026-06-22 历史回收判定捡回):** 这三项合起来是一整套"角色 rig 编辑器"范式——把角色拆成骨骼件、编辑多套动作、导出动作包。它和现行生成主线(agent 直出 + mmx 出静态素材)不在同一条轨上:主线产出的是静态美术资产,rig 编辑器要的是可绑定可驱动的骨骼动画件,产能与复杂度都高一档。裁定是**保留为 premium 远期产品方向、不在 MVP 范围**,优先级维持 P1/P2 不动,但定性为远期方向而非近期待建,避免被误读成 MVP 要交付一个角色骨骼编辑器。 ### 域 4　授权 IP 创作（LIC） | ID | 需求 | 端 | 优先级 | 来源 | @@ -90,12 +100,14 @@ flowchart TB ### 域 5　发布分发（PUB） | ID | 需求 | 端 | 优先级 | 来源 | |---|---|---|---|---| -| P-PUB-01 | 一键多渠道发布(自有必选 + 抖音/微信/快手/TapTap) | 创作者 | P0 | demo/G6 | +| P-PUB-01 | 一键多渠道发布(自有必选 + 抖音/微信/快手/TapTap) | 创作者 | P1 | demo/G6 | | P-PUB-02 | 查看外部渠道开通状态(待开通/申请中/已上线) | 创作者 | P1 | demo/G6 | | P-PUB-03 | 发布前检查(锁风+性能+版权通过才可发布) | 创作者 | P0 | demo/G2 | | P-PUB-04 | 保存发布配置 | 创作者 | P2 | demo | | P-PUB-05 | 多渠道合规简介自动改写 | 创作者+运营 | P1 | v2.0 | +> P-PUB-01 的优先级按渠道拆开看(创始人 2026-06-22 历史回收判定捡回,源自三向审计「出」):**发布到自有端这一条单渠道路径仍是 P0**——它是 MVP 闭环里"发布"那一环的落点,创作者做完游戏必须能在自有端上线、进信息流。**外部多渠道(抖音/微信/快手/TapTap)整体降到 P1**,因为外部渠道受 ICP 备案、平台进件这些日历闸门阻塞,MVP 期内不可能真正打通,把它挂在 P0 等于在验收集里留一条注定做不完的硬指标。所以 P-PUB-01 的行级优先级记 P1(整条"一键多渠道"以外部渠道为主体),但"自有单渠道发布"这一子能力的验收口径仍按 P0 守。 + --- ## 玩家侧 @@ -129,6 +141,8 @@ flowchart TB | P-FED-15 | 低端设备低画质模式 | 玩家 | P1 | v2.0 | | P-FED-16 | 弱网/离线游玩兜底 | 玩家 | P1 | v2.0 | +> 信息流的玩家态度只保留**点赞(P-FED-03)+ 收藏(P-FED-04)**两态,确认不做 demo 里多出来的"最喜欢"星标(创始人 2026-06-22 历史回收判定捡回,确认删除)。"最喜欢"在语义上独立于点赞和收藏,是 demo 阶段冗余出来的第三种态,既加重玩家心智又和收藏功能重叠,清单不引入这一行。 + ### 域 12　社区互动（SOC） | ID | 需求 | 端 | 优先级 | 来源 | |---|---|---|---|---| @@ -193,7 +207,7 @@ flowchart TB ### 域 8　创作者数据经营（OPS） | ID | 需求 | 端 | 优先级 | 来源 | |---|---|---|---|---| -| P-OPS-01 | 创作者数据看板(留存/完玩/广告转化/素材复用) | 经营 | P1 | demo/v2.0 | +| P-OPS-01 | 创作者数据看板(留存/完玩/广告转化/素材复用) | 经营 | P0-lite | demo/v2.0 | | P-OPS-02 | 七日留存与播放趋势 | 经营 | P1 | demo/v2.0 | | P-OPS-03 | AI 内容诊断(短板定位 + 建议) | 经营 | P1 | demo/v2.0 | | P-OPS-04 | 一键迭代优化 / 生成改版任务 | 经营 | P1 | demo | @@ -272,6 +286,8 @@ flowchart TB | P-BIZ-13 | 政务科普小游戏 | 运营 | P2 | v2.0 | | P-BIZ-14 | 资质代办(软著/渠道上架/ICP文网文) | 运营 | P1/P2 | v2.0 | +> P-BIZ-02 / P-BIZ-03 / P-BIZ-04 维持 P0,但 demo 里那套高调呈现的"32 个分场景模板库 / 15 分钟自动出案 / 可交互 demo 自动生成"是**愿景示意,不是产品承诺**(创始人 2026-06-22 历史回收判定捡回)。当前 B 端真实建设度只有轻量需求表单加人工报价,离"32 模板 / 15min 自动出案"差距很大。所以这三条 P0 的验收口径要按"B 端能选模板预览、看到定制进度、完成试玩验收签署"这个最小可用面来认,不要把"32/15min 自动"那套数字当成必须达成的验收指标——它是对外展示的能力愿景,具体模板数量与出案时长不作承诺,B 端客户与创作者的预期管理都依此口径。 + ### 域 18　运营管理（OPN，admin） | ID | 需求 | 端 | 优先级 | 来源 | |---|---|---|---|---| @@ -293,11 +309,16 @@ flowchart TB | P-ACC-03 | 适龄分级提示展示 | 通用 | P0 | v2.0 | | P-ACC-04 | 创作者审核申诉 | 创作者 | P1 | v2.0 | | P-ACC-05 | 帮助中心 / 退出登录 | 通用 | P2 | demo | +| P-ACC-06 | 登录 / 注册(账号体系入口) | 通用 | P0 | demo | + +> P-ACC-06 是补登的(创始人 2026-06-22 历史回收判定捡回,源自三向审计 Doc A 判定):账号体系是 P0,鉴权波已实现,但登录/注册作为一条用户可感知的产品功能,此前在清单里没有独立 P-id——只有"账号信息/隐私政策/适龄提示/申诉"这些账号相关行,登录注册本身缺位,读清单的人对不上 demo 里真实存在的登录注册面。补这一行让 55 P0 验收契约自洽:登录/注册是其余账号能力的前置入口,验收按"能完成注册与登录、拿到账号态"来认。 --- ## 计数与说明 -共 **155 项产品需求**,分 19 个产品域,其中 **55 项 P0**(MVP 验收口径)。 +共 **158 项产品需求**,分 19 个产品域,其中 **55 项 P0**(MVP 验收口径)。 > 每项需求由哪些技术功能(T-id)实现、首要负责模块是谁——见[需求模块映射](需求模块映射.md)。 + +> **2026-06-22 历史回收判定带来的口径调整(创始人 2026-06-22 历史回收判定捡回):** 本轮补登了 3 条此前缺位的产品需求行,总数从 155 升到 158——P-ACC-06(登录/注册)、P-CRT-16(对话式创作代码目录标签)、P-CRT-17(创作模式双标签切换),都是 demo 里真实存在却没列成行的功能/入口面。**P0 总数仍维持 55**:新增的 P-ACC-06 计入 P0(账号体系前置),同时 P-PUB-01(一键多渠道发布)按"外部多渠道受日历闸门阻塞"从 P0 降到 P1,一进一出抵平,所以 MVP 验收口径的 55 P0 头号锚不变。另外 P-OPS-01(创作者数据看板)从 P1 升为 **P0-lite**——这是审计为"创作者发布后看不到数据=供给侧留存断点"开的一档轻量必做,它是独立于 55 P0 的子档(只要求最基础的播放数,不是完整看板),不计进 55 的头号口径。各行优先级变更的来由,见对应产品域表下的注记。 diff --git a/docs/architecture/前端/README.md b/docs/architecture/前端/README.md index 8439d2ed..9422d2dd 100644 --- a/docs/architecture/前端/README.md +++ b/docs/architecture/前端/README.md @@ -218,7 +218,78 @@ token 还承担一个长期使命:**做跨端的单一事实源**(single source --- -## 9. 关键指针 +## 9. 前端域承载范围:近期待补的前端落点 + +前面几节讲的是设计体系本身、以及 studio 相对 demo 的能力盘点。但前端域要承载的不止设计体系——有一批能力,后端、契约、运维、架构域都已经把"里子"做出来或定下来了,缺的只是前端这层"面子":页面、入口、按钮、展示。这一节把这些**归属在前端域、近期要补的落点**钉清楚,按时间窗分组。它只立"该谁承载、什么时候补"这件事,不在这里写逐页 UI 的详细设计——具体到组件与交互的 file 级设计,留给实现时在活代码里落。这一整节都来自创始人 2026-06-22 历史回收判定的捡回,逐条对应[历史回收清单](../_recall/前端-历史设计点.md)里同名的设计点。 + +### 9.1 前端域引用承载:把活在别域的前端约束引一份过来 + +前端的体验是很多跨域约束的最终执行点,但这些约束的权威定义常常活在架构域、运维域或代码里,前端域却看不到它们。这容易让人误以为"前端没有性能/观测责任",其实前端正是这些指标的兑现处。下面这几条不在前端域重新定义(避免一份事实两处写、口径漂移),只引用一句、点明它们的前端责任,让读前端档的人知道这些线压在前端身上。 + +**体验 SLO 的前端责任。** 信息流首屏 P75 < 3 秒、点卡到可玩 S2 常态 ≤ 2 秒(全新设备首次 ≤ 3.5 秒)这套体验承诺,权威定义在架构域 [`../架构/生成引擎/引擎与运行时.md`](../架构/生成引擎/引擎与运行时.md)(SLO 地板那节)。它对前端的含义是:首帧绘制、加载态反馈、预热时机这些都是前端的执行点——manifest 随 feed 清单先行下发后,前端要能在 300ms 量级先用它把游戏的主题底色和标题画出来,消除加载等待感,而不是干等游戏字节到齐才出画面。自适应质量分档(首次会话探测设备能力、低端机自动降画质)也有前端/宿主的探测与降级开关这一半。这些都不在前端档展开设计,只记一句:**前端是这套体验 SLO 的兑现处,设计与验收时要把它当成前端的首要约束,而不是别人家的指标。** + +**feed 容器调度的前端责任。** 信息流的核心手势(上滑切下一款)、三容器预加载策略(销毁当前 + 激活预加载好的下一个、N±1 只预取字节不实例化)、以及 manifest 随 feed 清单下发省一次往返,这套运行时调度的"how"归架构域生成引擎子树。但**前端 feed 列表如何维护这三态容器、何时按滚动方向触发上/下预取、切换动画怎么做**,是前端实现问题。这里只钉归属:feed 的滑动手势承载与容器生命周期调度归前端域,装载与渲染的底层机制见架构域,别让它悬空成"两边都以为对方在管"。 + +**前端可观测性的承载。** 页面在真实用户浏览器里加载多慢、报了什么 JS 错、首屏耗时实测对齐 P75 < 3s——这种前端可观测性,和现有那条"业务遥测(性能/游玩/会话)落 `game_telemetry_event`"的业务数据回路是两回事。它的承载方案是运维域观测体系里那条 **OTel Web SDK**(给 `game-studio` / `game-admin` 接入,采页面性能 / JS 错误 / 前端 trace),权威定义见 [`../运维/观测体系.md`](../运维/观测体系.md)。现状标的是"可选、后期",前端域只引这一句、认下这个承载点:**前端的页面级性能与错误观测走 OTel Web SDK,不在前端另造一套采集。** + +### 9.2 admin(game-admin)第一期承载:审核台四页 + 权限双层 + +现行前端档对 admin 几乎只说了"沿用 Element Plus 默认、品牌色对齐"。但随着内容审核后端落地,admin 侧有一组页面要进**第一期**(跟审核台后端同期建),它们归 game-admin 前端承载: + +- **审核队列页**:待审内容列表,支持按状态/举报率/积压时长筛选,是运营每天的工作入口。 +- **审核详情页**:单条内容的试玩预览 + 生成轨迹 + 就绪分 + 举报详情,供运营做判断。 +- **审核处置页**:通过 / 拒绝 / 下架 / 加精选 / 限曝光这套决策操作,以及拒绝反馈与重提交流转。 +- **锁风配置页**:内容安全策略(关键词、阈值、风控开关)的配置界面。 + +权限口径定**双层**:前端给这几页的操作入口挂 `v-hasPermi` 权限指令做按钮级显隐,后端再用 `@PreAuthorize` 兜底做真正的访问控制。这一条要和 admin 侧的历史现状对齐看——现存的 wanxiang 页是"零 `v-hasPermi`、全靠后端 `@PreAuthorize` 兜底",原因是前端挂权限点要求 `system_menu` 的权限种子已到位,否则超管以外的角色按钮会全隐。所以审核台这几页挂 `v-hasPermi` 的前提是先把对应的权限点种子配好;种子没到位前,先靠后端兜底这一层守住安全边界,不能因为前端没挂权限点就当成不设防。**前端的权限指令是体验层(让没权限的人看不到按钮),不是安全边界——安全边界永远在后端。** + +> contract-first(待落地):审核台四页要挂 `v-hasPermi`,前置是 `system_menu` 里这几个审核操作的权限点种子(菜单/按钮权限编码)要先补一批 Flyway 种子数据;锁风配置页若要落配置项,涉及的配置存储与读写接口要先在后端定。这两项都标"待落地",当前 admin 还没有这套审核台页面。 + +### 9.3 admin 观测三入口:近期承载 + +观测体系正式稿(运维域)里定了 admin 要开一个进观测大盘的入口。落到 admin 前端,是三个近期要补的承载点: + +- **观测大图入口**:在 admin 里挂一个进 Grafana / 夜莺大盘的入口,运营/管理员从后台直接看系统健康与生成指标,而不是各自记一串 Grafana 地址。 +- **SSO 免登**:嵌入的观测大盘要和 admin 的登录态打通,做到免二次登录(涉及 Grafana 的 `X-Frame-Options` 放行与 SSO 对接,这两项是待处理的接入工作)。 +- **告警概览**:在 admin 里给一个告警的概览视图,把当前活跃告警聚合展示,不必跳到夜莺才看得到。 + +这三个归 admin 前端承载,但它们的数据与嵌入方式依赖运维域观测栈先就绪(见 [`../运维/观测体系.md`](../运维/观测体系.md) 的 admin 观测入口那节)。`X-Frame-Options` / SSO 这两个嵌入前置没解决前,这三个入口落不实,所以排"近期"而非"第一期"。 + +### 9.4 C 端 studio 近期承载:钱包页 / 溯源条 / AIGC 标识 / 互动真接 + +C 端这一摊,后端大多已是现行真相,缺的是前端这层面子,逐条钉清归属与时间窗: + +**创作者收益钱包页(近期)。** 后端钱包链路已经真跑——`game_trade_account`(收益账户,守 `balance + frozen + total_withdraw = total_income` 不变式)、`game_trade_income`(分账入账,区分广告/打赏)、`game_trade_withdraw`(提现,状态机 + 幂等)都在(见 [`../后端/数据模型.md`](../后端/数据模型.md) 的 trade 子图)。前端要补的是创作者看得见的钱包页:查余额、看收益明细(按日/周/月、按广告/素材/商单各渠道分)、发起提现。这是把已经跑通的后端能力接出一个用户入口,避免它成为没有前端的孤儿能力。"满 5 元才能提现"这类预期管理的文案也落在这一页(对应变现侧的提现门槛口径)。 + +**同款溯源条 + 创作者中心同款聚合卡(随数据飞轮阶段一一起落)。** 数据飞轮的溯源链设计(见 [`../架构/生成引擎/数据飞轮.md`](../架构/生成引擎/数据飞轮.md) §3.1)已经把前端这两个出口点写进了阶段一范围:试玩页读 `game_lineage_edge`,有 active 血缘边时展示"改编自 [原作标题] · @[原作者]"的**溯源条**(点击跳回原作,父被删时降级为不可跳转的灰态);原作者在**创作者中心**能看到"我的 [作品] 被 N 人做了同款"的**同款聚合卡**(走去重聚合 API)。这两个展示点是溯源链对用户可见的唯一出口,没有它们血缘就是库里的孤儿数据。它们归前端域承载,跟着数据飞轮阶段一(溯源链 + 同款创作)一起落,不早于、不晚于那条飞轮。 + +**AIGC 显式标识的前端展示(法定 P0,跟渠道线起步落)。** AI 生成内容的显式标识是法定要求(生成式 AI 服务的合规义务),它在前端的承载是把"AI 生成"这个标识展示在内容的每个对外触点——信息流卡片、游戏详情、分享落地页都要带上。这条归前端域,优先级对齐法定 P0,跟渠道线起步一起落(渠道发行场景对 AIGC 标识的合规要求最硬)。 + +**feed 互动按钮真接 community / social(排期真接)。** 现行 feed 的部分互动按钮还是 mock。后端 community / social 模块已建成并接入单体(见 [`../后端/README.md`](../后端/README.md) 的 13 模块现状),`game_feed_interact_log` 已有点赞/收藏/分享/举报四种互动埋点。前端要做的是把 feed 的互动按钮从 mock 真接到 community / social 的真实端点。这条捡回、排期真接,不再让互动停在 mock。 + +> contract-first(待落地):feed 互动按钮真接 community / social,前置是核对 community / social 已暴露的互动端点与 `game_feed_interact_log` 的埋点契约是否齐备(点赞/收藏/分享/举报四种已有,评论/关注若要进 feed 需另核后端端点与契约)。评论(P-SOC-01)、关注当前在 Doc A 标 P1,真接范围以已建端点为准,缺口标"待落地"。 + +### 9.5 青少年模式与分级展示(合规放量前补) + +青少年模式的内容过滤 + 适龄分级提示展示,归前端域承载,时间窗是**合规放量前**——它不是 v2.0 远期能力,而是正式放量(面向更大用户盘)前必须补上的合规前端。落到前端是两件事:青少年模式下对不适龄内容做过滤(feed/详情不展示),以及适龄分级标识的展示(对应 Doc A 的 `P-ACC-03 适龄分级提示展示`)。这条钉一个清晰的时间锚:**合规放量前必补,别拖到放量之后才想起来。** + +### 9.6 SDK 与移动端适配:补齐的前端能力 + +**Debug 调试插件补进 SDK 插件库。** 现行 SDK 插件库(运行时手册里的 Ad / Pay / Social / Storage 四插件,见 [`../../../.agents/skills/runtime-and-multichannel.md`](../../../.agents/skills/runtime-and-multichannel.md))漏了一个历史上规划过的 **Debug 插件**。它是开发模式下的调试面板:实时 FPS 曲线、SDK 事件流日志、GameConfig 运行时状态查看、从生成到运行的全链路 `trace_id` 展示、网络请求拦截、一键性能快照。它既是创作者调试自己游戏的工具,也是平台排查生成质量的利器。这条捡回,补进 SDK 插件库,作为一个仅开发模式加载、不进生产首屏的插件。 + +> contract-first(待落地):Debug 插件要进 SDK 插件库,涉及 SDK 契约(`contracts/sdk/`)新增一个 `debug` 插件声明 + GameConfig 里按需声明该插件的开关(仅开发模式加载),宿主据 manifest 决定是否注入该插件 chunk。当前 SDK 契约只声明了 Ad / Pay / Social / Storage 四插件,Debug 标"待落地"。 + +**移动端基本适配集。** 现行前端档把响应式大方向定了(移动沉浸/桌面居中放大),但移动端的几条具体适配约束是空白,捡回补成一个"移动端基本适配集",归前端域:① **安全区适配**——竖屏沉浸式 feed 在真机上必然遇到刘海、底部手势条,要用 `safe-area-inset` 留出安全区;② **软键盘处理**——创作页的一句话输入框、评论输入框在移动端软键盘弹起时会顶布局,要做遮挡处理;③ **横屏游戏在竖屏 feed 的呈现**——生成的游戏可能是横屏体验,塞进竖屏卡片时要给旋转提示或自适应方案,而不是直接挤变形;④ **触觉反馈**——游戏关键节点、互动反馈用 `navigator.vibrate` 做轻量震动,提体感。这四条都是消费级移动 Web 的基本盘,作为一个适配集一并补,file 级细节留实现。 + +### 9.7 B 端 demo 取包:owner-agnostic 取包端点(卡 B 端现金线) + +这是一条被历史评审标为高风险、卡 B 端现金线命脉的真实契约缺口:运营为客户代建的 biz demo,owner 是运营不是客户,客户走 `preview` 取包会被 owner 校验拦下,走 `play` 又要求游戏已正式发布(`status=1`)——于是客户根本没有一个能取到这个 demo 包的端点,B 端"给客户看 demo"这个闭环不可达。前端域要承载的是这个取包入口,但它依赖后端先补一个 **owner-agnostic 的取包判定端点**(或把 demo 走正式发布流绕开 owner 校验)。这条钉清:**B 端 demo 试玩的取包归前端承载,但前提是后端先把这个取包端点的契约缺口补上,否则前端有入口也取不到包。** + +> contract-first(待落地):biz demo 的客户试玩取包,前置是 runtime 侧补一个 owner-agnostic 的取包端点(不做 owner 校验、也不要求 `status=1` 的受控取包路径,带 biz demo 的合法性判定),涉及 runtime 模块的 API 契约新增。当前 runtime 只有 `preview`(owner 校验)/ `play`(`status=1`)两条路,owner-agnostic 取包标"待落地"。 + +--- + +## 10. 关键指针 需要更深的细节时,回到这些权威源: diff --git a/docs/architecture/后端/数据模型.md b/docs/architecture/后端/数据模型.md index 2ce52d6f..93b71f6a 100644 --- a/docs/architecture/后端/数据模型.md +++ b/docs/architecture/后端/数据模型.md @@ -296,3 +296,59 @@ admin 和运营侧的用户是另一套人,走 Huijing 原生的 `system_users`, 本页是数据结构 SoT 的"总图"层,只画表和表怎么连。表的逐列细节以迁移头注为准,完成度以 [MVP进度总账](../../mvp/MVP进度总账.md) §2 为准,模块边界以 [13模块.md](../架构/13模块.md) 为准,工程落地以 [后端 README](README.md) 为准。 迁移只增不改。新增表或列时,回这里补对应的节点和说明 —— 主表进第 1 章主干图、明细进第 2 章对应链路子图、所有表进第 3 章清单,并锚点到新迁移。 + +--- + +## 7. 待落地的数据契约缺口(contract-first 清单) + +下面这几条都是设计已经讲清、但库里还没改的硬缺口或待建表。它们的共同点是改动横跨契约文件、Flyway 迁移和 `-api` 镜像,属于 contract-first 动作而非顺手加一列,所以集中登记成待落地清单,别因为这里写了就当已建。本节内容均为**创始人 2026-06-22 历史回收判定捡回**。 + +### 7.1 `game_trade_income` 缺 `game_id`:按游戏算钱的连接键断在这里 + +入账流水现在只有 `source` / `source_ref` / `gross_amount` / `share_rate` / `net_amount`,能顺着 `source_ref` 串到广告单或打赏单,却串不到具体哪款游戏。结果是两件事同时被卡:一是按游戏粒度算单位经济(哪款游戏赚了多少、成本回不回得来),二是收益回流语料需要的 join 键(把"线上赚了多少钱"这个结果标签接到某款游戏的源工件上,见 [生成引擎/数据飞轮.md](../架构/生成引擎/数据飞轮.md) §3.3)。`game_ad_revenue` 这一侧本来就带 `game_id`(它靠 game_id 反查创作者),缺口只在 trade 这一段没把它透传下来、也没落列。 + +补法是一条四步链,缺一即断:广告台账查询接口 `AdRevenueApi.getUnsettledRevenue` 返回的 `AdRevenueRespDTO` 先加上 `gameId` 字段;trade 的 `SettlementJob` 拿到后透传进 `IncomeService.recordIncome`,写入新增的 `game_id` 列;打赏线的 `recordIncome` 同样把打赏单所属游戏的 gameId 带进来。这条链在变现侧的工程口径(W4 ③④、防重计数硬约束、为什么否决"往 telemetry 加列")已写在 [运营/变现与单位经济.md](../运营/变现与单位经济.md) §6 待办首条,本页只补它在数据模型侧的列与镜像清单,两处一并维护、别让缺口口径漂移。 + +contract-first 待落地: +- 契约 `contracts/api-schemas/ad.yaml` —— `AdRevenueRespDTO`(`getUnsettledRevenue` 的 itemType)加 `gameId: Long`,语义"产生这笔收入的游戏 ID,供 trade 落 game_trade_income.game_id 做按游戏归因"。 +- 契约 `contracts/api-schemas/trade.yaml` —— `IncomeRespVO` 加 `gameId`;`recordIncome` 的入参说明补 gameId 透传。 +- Flyway 新迁移(版本号按落地时仓内最新顺延,现仓已到 V25)—— `game_trade_income` `ADD COLUMN game_id BIGINT NULL`(nullable,对存量行无影响、向后兼容),加普通索引 `idx_game_id` 供按游戏聚合。 +- Java 镜像 —— `IncomeDO` 加 `gameId` 字段、`IncomeRespVO` 加 `gameId`、`recordIncome` 签名带 gameId 透传;`AdRevenueRespDTO` 同步加。 +- 注意分账幂等键 `uk_source(source, source_ref, tenant_id)` 不动:game_id 是归因维度、不进幂等键。 + +### 7.2 `game_telemetry_game_stat` 缺留存字段:先定口径再加聚合列 + +聚合表现在只有 play / end / complete / duration / like / favorite 这几个量,拿不出"次留 / N 日留存"。这同样卡着收益回流语料(没有留存标签就训不出"什么样的游戏留得住人")和未来推荐排序里的 freshness / 留存信号。它和 §7.1 同源但落点不同:§7.1 缺的是 trade 侧的连接键,这条缺的是 telemetry 侧的留存口径。 + +这条不是单纯加列,得**先定义留存口径再加聚合字段**——留存按设备(anonId)还是按登录用户算、次留的窗口怎么切(自然日还是 24 小时滚动)、回访事件以哪个埋点为准,这些定下来之前不要急着 ALTER。口径定了之后,聚合字段才好确定是落"次留人数 / 分母人数"两列由读侧算率,还是直接物化一个留存率。 + +contract-first 待落地: +- 先产出留存口径定义(归到遥测域,可在本页或观测体系档补一段口径说明),作为加列的前置。 +- 契约 `contracts/events.schema.json` —— 若现有埋点不足以判定回访,可能要新增或明确一个回访事件;先核对 `game_play_start` 能否承载,能则不新增事件。 +- Flyway 新迁移 —— `game_telemetry_game_stat` 按定好的口径 `ADD COLUMN`(如 `retained_uv` / 留存分母,均 nullable)。 +- Java 镜像 —— 聚合 Service 补留存计算、`game_telemetry_game_stat` 对应 DO 加字段。 + +### 7.3 锁风三档裁决落点:MVP 写 `details` JSON,不改表 + +锁风三档(标准 / 严格 / 人工复核)的裁决要能回答"这条内容为什么走了严格档",落点是现有的 `game_compliance_gate_result` 台账。但 `GateResultDO` 现在只有 `id` / `game_id` / `version_id` / `verdict` / `rating` / `details` / `trace_id`,没有 `lock_strength` 或 `ip_id` 列。MVP 阶段的取舍是**写进已有的 `details` JSON 列**——`details` 本来就存各原子明细数组 `[{atom,verdict,reason}]`,给它再加 `lockStrength` 和 `ipId` 两个键即可,不改表、不加迁移,溯源时从 JSON 里读。这条选 JSON 而非升列的理由是:MVP 还没有"按档位聚合审核量做报表"的需求,软扩字段够用且零迁移成本。完整设计在 [运营/审核台运营.md](../运营/审核台运营.md) §3.3,本页只登记它在数据模型侧的落点结论。 + +只有在确有按档位做报表(需要 SQL `WHERE lock_strength=…` / `GROUP BY`)的需求时,才 contract-first 升列:`game_compliance_gate_result` `ADD COLUMN lock_strength VARCHAR / ip_id BIGINT`(均 nullable、向后兼容),`GateResultDO` 加两字段,Mapper 不动(MyBatis-Plus 自动映射)。升列迁移的版本号要和 §7.4 的信用台账迁移错开,别撞同一个版本号。 + +### 7.4 创作者信用:独立扣分台账,不在等级表加列 + +创作者信用要把单次违规处置转成对人的长期约束(信用低 → 审核自动拉严档 + feed 基线曝光降低)。它的宿主候选是 community 的等级引擎 `game_community_level`,但那张表只有 `level` / `published_count` / `last_milestone`,没有 `credit_score`,`CommunityNotifyApi` 也没有扣分端点。创始人 2026-06-22 定的落点是**独立扣分台账,而不是在等级表上加一个 `credit_score` 列**——每次扣分记一条流水(谁、因为哪次处置、扣多少、什么时候),信用分由台账聚合得出。选台账而非加列,是为了让信用变化可追溯、可审计、可对账,也便于将来做误伤申诉时逐条回放;一个汇总列做不到这些。 + +contract-first 待落地: +- 新建 Flyway 迁移建表 `game_community_credit_ledger`(继承 TenantBaseDO 拿 6 审计列),关键字段:`creator_user_id`(归属)、`delta`(本次扣分,负值)、`reason_type`(对应哪类处置:降权 / 下架 / 封禁)、`source_ref`(关联的处置单 / ban id)、`biz_no`(幂等键)、`trace_id`(对账)。当前信用分 = 该创作者全部 delta 之和(或物化一个汇总,但权威源是台账)。 +- 契约 `contracts/api-schemas/community.yaml` —— `CommunityNotifyApi` 现有 4 方法(generate-done / review-result / income-changed / project-published),为它加第 5 个扣分端点 `deduct-credit`,**带幂等键 `bizNo`**(同 community 既有 `(userId,type,bizRef)` 去重范式),供 compliance 在处置时同进程 @Primary 调用。 +- 跨模块依赖 —— compliance-server 调 community 的 `-api` 扣分,扣分失败不回滚处置主操作(扣分是处置的附带副作用),走幂等补偿。 +- 注意迁移版本号与 §7.3 锁风升列(若升)错开。 +- 完整设计与误伤治理在 [运营/审核台运营.md](../运营/审核台运营.md) §3.5,本页只登记数据落点。 + +### 7.5 封号级联:数据语义上的两条断链 + +封一个创作者账号现在只写 `game_user_ban` 台账,既不置 `game_player.status=DISABLE`,也不遍历下架其全部已发布游戏,而创作准入的 `validateCreator` 又不查 ban 表。结果是封了号拦不住本人继续创作、其旧内容仍在 feed 里跑——一个真实的越权 / 绕管缺陷。这条横跨鉴权域(准入)和合规域(处置),两边都容易以为对方管而都漏。数据侧要补两条断链:封号时同步把 `game_player.status` 置 `DISABLE`(走 passport `-api`,复用既有禁用态判定)、按 `creator_id` 查其全部已发布游戏批量走 `offlineRank` 下架。准入侧的 `validateCreator` 改法详见 [鉴权与权限.md](鉴权与权限.md) §5,本页只标这条级联在数据上动了 `game_player.status` 与 feed 出流两处状态,不新建表。 + +### 7.6 绘豆:平台类积分体系的立位(待单独设计) + +历史上 D3 业务决策里有一套积分体系 `point_rate=10`(1 元 = 10 积分,打赏走积分计入创作者收益)。这套旧口径**不照搬**——创始人 2026-06-22 提出新设计「绘豆」,是平台侧的类积分体系,取代旧 `point_rate=10` 的定价口径。绘豆的具体形态(用途是打赏 / 生成额度 / 会员权益、与档位和订阅漏斗怎么挂、单价怎么定、要不要落独立账本表与幂等扣减)目前**待单独设计**,这里只占一个位:trade 现有的 TIP(打赏)入账入口是真的,但"积分 / 绘豆"这层产品形态尚未落库,设计成形前不要在 trade 或别处提前建绘豆相关的表或枚举。绘豆与预算即产品(档位决定生成级别与额度)、订阅漏斗一脉,设计时一并考虑。 diff --git a/docs/architecture/后端/鉴权与权限.md b/docs/architecture/后端/鉴权与权限.md index 40b4c6ee..b5fa551a 100644 --- a/docs/architecture/后端/鉴权与权限.md +++ b/docs/architecture/后端/鉴权与权限.md @@ -77,6 +77,8 @@ C 端虽创作者与玩家同型,但"能不能创作"由一道白名单卡住, `PlayerApiImpl` 用 `@Primary` 本地 bean(单体同进程直调,拆微服务后换 Feign),被上游 `@Transactional` 方法包着调用,校验失败整体回滚(`PlayerApiImpl.java:24-38`)。除发布外,直发生成等创作写入口同样前置 `validateCreator`——前端守卫挡不住直连 API,所以这道白名单必须在后端。白名单的置位由 B 端运营操作:`AdminPassportPlayer` 的 `PUT /passport/player/set-creator`,权限位 `@PreAuthorize('system:passport-player:update')`(`AdminPassportPlayerController.java:34-38`)。 +这道白名单有一处和合规域接缝上的断链要补:封一个创作者账号时,准入链现在拦不住他继续创作(创始人 2026-06-22 历史回收判定捡回)。`validateCreator` 今天只查 `game_player.status` 和 `creator_flag`,**不查 `game_user_ban` 表**;而合规侧封禁账号时(`UserBanServiceImpl.createBan`)只写 `game_user_ban` 台账,**既不置 `game_player.status=DISABLE`、也不遍历下架该创作者全部已发布游戏**。两个事实叠在一起,封号后他的 `game_player` 仍是启用态、`validateCreator` 照样放行,旧内容也照样在 feed 里跑——这是个真实的越权 / 绕管缺陷,一头在鉴权(准入)、一头在合规(处置),容易被两域都当成对方的事而漏掉。要补的两条断链:其一是封号时同步把 `game_player.status` 置 `DISABLE`(走 passport 的 `-api`,复用现有禁用态判定;这样 `validateCreator` 的现有 status 检查就能拦住),作为更小改动优先,或退一步让 `validateCreator` 在判定时多查一次生效中的 ban 记录;其二是按 `creatorId` 查其全部已发布游戏、逐个走 `offlineRank` / `unlistIfPublished` 批量下架。两条都要定义解封时的状态恢复、封 / 解封的幂等(重复操作不出错)、审计留痕;下架是封禁的附带副作用,部分失败不回滚封禁主操作。这条级联在数据侧的落点见 [数据模型.md](数据模型.md) §7.5,处置侧完整设计见 [运营/审核台运营.md](../运营/审核台运营.md) §3.5。 + ## 6. 匿名与登录态的准入矩阵 平台的端点按准入要求分四档。匿名读端点用 `@PermitAll` 由框架扫描注解自动转成免登 URL 列表;其余端点落到 `anyRequest().authenticated()` 的兜底,未登录即 401(`HuijingWebSecurityConfigurerAdapter.java:128-219`)。这张表是查"某个端点该走哪档"的速查: @@ -110,6 +112,8 @@ flowchart LR mock 后门是 staging 现状、生产必须关死的红线。`mock-enable=true` 时,token 以 `mockSecret`(默认 `test`)开头即直造登录态(`test1` → userId=1),注释明写"线上环境一定要关闭";staging 与 local 当前都是 `mock-enable=true`(`TokenAuthenticationFilter.java`)。它与 §5 的 `validateCreator` 查无行放行是配套的内测豁免——批量跑零中断靠它,但生产上线前必须连同 sms-mock 一起关闭。 +短信发码端点的滥用防护是切真实短信渠道前的硬安全前置,现在缺(创始人 2026-06-22 历史回收判定捡回)。发验证码端点 `POST /app-api/passport/send-sms-code` 按 §6 必然免登(`@PermitAll`),这就让它天然暴露在短信轰炸这个经典攻击面下:有人拿一个号或一批号高频打这个端点,既骚扰用户、又烧掉真实短信通道的钱。现状是只有按手机号的频控,按 IP / 设备的限制还是上游 TODO、staging 的图形验证码也关着,而且 `game-module-*` 的 pom 至今没引限频组件(protection starter)。切真实短信渠道前必须补三件:按 IP / 设备维度限频(单 IP、单设备每分钟 / 每天的发码次数封顶)、图形验证码开关(高频或可疑时强制过 captcha 再发码)、引入限频组件作为落地手段。这道防护必须在后端——前端的发码冷却挡不住直连 API 的脚本。现在没切真实短信、仍走 sms-mock,所以它不是 staging 阻塞项,但它和"mock 后门生产关死"是同一时机的硬前置:开真实短信的那一刻,这套防护必须已经在位。 + | 维度 | 已建(鉴权波收口) | 蓝图 / 待办 | |---|---|---| | 认证 | OAuth2 token + userType 强绑定 + mock 后门(staging) | mock 后门生产关死 | @@ -117,6 +121,7 @@ mock 后门是 staging 现状、生产必须关死的红线。`mock-enable=true` | C 端授权 | Service 层归属隔离 + 创作白名单 | —— | | 网关 | 软转发(剥伪造头 / 注入可信头) | 网关路径级鉴权(微服务拆分后) | | 数据权限 | 公开读手动 `eq` 裁剪 | `DataPermission` 扩展到业务表 | +| 发码防护 | 按手机号频控 | 切真实短信前补:IP / 设备限频 + 图形验证码 + 引限频组件(创始人 2026-06-22 捡回) | --- diff --git a/docs/architecture/架构/契约总览.md b/docs/architecture/架构/契约总览.md index 7a1fb326..8c5215bd 100644 --- a/docs/architecture/架构/契约总览.md +++ b/docs/architecture/架构/契约总览.md @@ -100,6 +100,8 @@ flowchart LR 这是一个待决策位,不在本档自裁:要么补一道真门 —— 在 wave-close 或 pre-commit 加一步 `contracts/db-schemas` ↔ migration 的 `cmp`,漂移即红线拦截;要么干脆裁定执行副本为唯一源、把 `contracts/db-schemas` 降为只读快照或删掉,消除"声称授权源却滞后"的矛盾。无论哪条,先得让 README §41 的口径和代码实情对上。 +更重的两套机器化契约手段是**远期待引、MVP 不引**(创始人 2026-06-22 历史回收判定:不捡,记远期待引)。一是服务间的 Pact 消费者驱动契约测试,二是事件的 Schema Registry。MVP 阶段不上它们,靠现有的人工纪律(改契约先改 `contracts/`)加 CI diff、加 events 的枚举守门人就够;真正把它们引进来的时机是微服务拆分、事件消费方变多、人工纪律开始压不住漂移的时候。登记在此是为了不让"现在没有机器门"被误读成"以后也不该有"——它们是有意推迟的升级路径,不是缺口。 + ## 版本与兼容铁律 规则正文在 [`contracts/README.md` §2](../../../contracts/README.md),不在此重抄,只列锚点:API 走 URL Path 版本,新增字段不算 breaking、删除或重命名要升版本、旧版本保留 ≥ 3 个月;事件每条带 `schema_version`,新增字段给默认值、老消费者忽略未知字段、不兼容变更用新事件名并行消费;DB 迁移已合入的禁改,回滚写新补偿迁移。跨模块对齐的三条硬约束在 [§2.1](../../../contracts/README.md):两个 `qualityScore` 不同量纲不可互相回灌(aigc 0-1 生成质量分 vs telemetry/feed 0-100 运营质量分)、`package_url` 权威写者=runtime、`play_count` 权威源=telemetry `game_play_start` 事件聚合。 diff --git a/docs/architecture/架构/生成引擎/OpenGame对照.md b/docs/architecture/架构/生成引擎/OpenGame对照.md index d3ba8843..dc8d2c05 100644 --- a/docs/architecture/架构/生成引擎/OpenGame对照.md +++ b/docs/architecture/架构/生成引擎/OpenGame对照.md @@ -371,6 +371,23 @@ flowchart TB **OpenGame 的命令式自主主循环、重型 PTY 沙箱、@google/genai 的 MCP 适配层**,都是 Node/TS 生态产物,且与我们 SAA 图的控制流范式正交。主循环用 SAA 图替代;PTY 沙箱如果将来需要,Java 侧得用 ProcessBuilder/pty4j 自建等价物(工作量不小,但 MVP 阶段我们的 build 节点未必需要这么重);MCP 走 SAA v1.1.2.2 自带的 MCP 支持,别试图移植那套 JS 适配。 +### 3.5 我们的 Phase 0–4 落地路线:从对照分析到带消融杠杆的执行序列(创始人 2026-06-22 历史回收判定捡回) + +上面 §3.1–§3.4 把"OpenGame 哪些设计值得抄、怎么落进 SAA 节点"按价值分了四类,那是**对照分析**。2026-06-22 把另一份决策记录(`docs/plans/2026-06-20-关闭九门判定-全面参考OpenGame-决策与Phase0-4.md`,创始人当天拍板、当天把 gamedef 做到 91.7%)的 Phase 路线回收进来,补的是分析之外的另一半——**一条有编号、有消融杠杆量化、有达标 flip 条件的执行序列**。两份口径不同:对照档回答"抄什么",这条路线回答"按什么顺序抄、每步能抬多少、抬到什么程度就切默认"。 + +这条路线的**起跑线**,是验收口径的一次收窄,得先讲清,否则后面的 Phase 没有立足点:生成环的硬门已从"九门全过"收窄成"只认五道客观健康门 A–E"(A_boot/B_uncaught/C_frame/D_render/E_live),G_input/H_progress/I_control 三道 driver 依赖门降为不否决生成的参考门,F_wiring 移出客观硬门、改由 VLM 看截图判其"真用引擎/有特效"的语义。这一收窄是 gamedef 从 all-9 口径下约 50% 做到 **91.7%** 的直接原因之一(细节见 [验收门-W-G1 §2.4](验收门-W-G1.md))。把九门里"靠 driver 才判得了"的那几道暂时摘出生成环的否决权之后,Phase 路线要补的就是"用别的、更对的东西把那几道门的语义重新接回来"——这正是下面几个 Phase 的主线。 + +各 Phase 与它们各自的消融杠杆(数字是 06-20 当天实测的 Build-Health 增量贡献): + +- **Phase 2 · 模板-First + hook,杠杆最大(约 +10.1 BH)。** 给每个 archetype 预建一套**已验证过的 gamedef 骨架**,再让便宜模型在骨架上做 hook 覆写,而不是从零发明结构。这与 §3.1 那条"GDD 契约 + template_api 是最高价值缺口"是同一件事的执行版——预建骨架就是"填空靶子",hook 清单就是约束便宜模型不编造 API 的那份 `template_api`。它单点贡献最大,所以排在最前。 +- **Phase 3 · 活调试协议 / 离线 linter(约 +6.9)。** 把生成中反复踩的坑沉淀进一个**版本化的匹配库**,在真玩之前先跑一道静态门把已知错挡掉、并回灌修复。这就是 §3.2 那条 Debug Skill 的落地——(签名,原因,修复)三元组加分组阈值升格,签名匹配纯算法零 LLM。它排第二,因为有了 Phase 2 的骨架打底,剩下的错才收敛到"可被 linter 模式化捕获"的程度。 +- **模板族复用(约 +5.8)。** 对应 §3.2 的 Template Skill:把完成过的项目按物理三元组泛化成可复用的家族骨架,命中即复用整个家族。它的增量来自"同品类第二款起不必重走 Phase 2 的从头预建"。 +- **Phase 4 · build-health + VLM 验证替换 driver 判定,并定 flip 达标条件。** 这一步把起跑线收窄时摘出去的 driver 门语义**正式接回来**——但不是接回 driver,而是接回"客观 build-health + VLM 看截图"两条:能不能跑用客观门 A–E 判,好不好看 / 是不是要的那个游戏用 VLM 判(对应 §3.3"player 软门做厚"和论文三轴里的 Visual Usability / Intent Alignment)。配套自修复封顶 **T=3**(同一道门最多自动修三次),达标后才 flip 成默认。 + +**flip 达标条件(这是 Phase 路线区别于纯分析的关键)**:gamedef 路在统一口径下成功率真达 80% 门,才把它切成默认产线、二分收敛退役旧 factory 路、并把"失败即拦截"的门翻开。在此之前,新口径与新 Phase 全部默认旁路、只观测、可用 `-Dsaa.gen.gateMode=all9` 回退对比,绝不一上来就改放行行为。这条 flip 门与生成引擎 README §6 那道 cutover 里程碑、与 SAA编排 §7 的 batch 治理层退役条件是同一道闸的不同视角,落地时挂同一个 80% 达标判据,不各立一套。 + +> 口径归属:这条 Phase 路线与起跑线的口径收窄,蒸馏权威源在 `.agents/skills/saa-graph-orchestration.md` §3.5 与上述决策 plan;"统一的 to-do、阶段序列、cutover 门"仍以[生成主线架构演进路线](../../../agent-specs/生成主线架构演进路线.md)为单一 SoT。本节把消融杠杆量化(+10.1/+6.9/+5.8)与 flip 达标条件回填进对照档,是因为这几个数字决定了"先抄哪一层最划算",而它们此前只躺在那份决策记录里、没进现行架构档。 + --- ## 4. 收口结论 diff --git a/docs/architecture/架构/生成引擎/README.md b/docs/architecture/架构/生成引擎/README.md index eb192a3d..8ea921bb 100644 --- a/docs/architecture/架构/生成引擎/README.md +++ b/docs/architecture/架构/生成引擎/README.md @@ -22,6 +22,8 @@ 把这三点合起来,可以用一句话概括整台机器的定位:**LLM 在这里扮演的是"游戏工作室"的角色**——它替代的是一个真实游戏工作室原本要做的策划、写码、配资产的活,而不是充当一个一次性出活的黑盒。这个"LLM as 工作室"的定位是整条线的灵魂,§3 会专门展开。 +把第三个支点再往前推一步,可以立一条贯穿全线的**工程纲领:harness 是这个项目的工程护城河,不是一次性的测试脚本(创始人 2026-06-22 历史回收判定捡回)。** 这条判断的分量在于它决定了工程投入往哪里沉淀。一次具体的生成——某个创作者那句话变成的那款游戏——是**消耗品**:它产出后,真正留下来、能复利的不是那一款游戏本身,而是把它造出来、验出来的那套生成运行环境。所以 harness 应当被当作一份**可版本化、可观测、可回放、可扩展**的核心资产来建设:可版本化,意味着它的判定口径、阈值、负例语料都进 Git、能 diff、能回滚;可观测,意味着每一次生成的全过程(走了哪些门、花了多少、为什么挂)都落进轨迹账本;可回放,意味着拿同一份输入能重跑出同一个结果、复现一次失败;可扩展,意味着加一道新门、接一个新品类的真玩 driver 不必重写底座。它决定的是整条线的成功率、成本和交付稳定性这三件最要紧的事——把工程力气压在 harness 上,而不是去优化某一次单独的生成,正是这条线"越做越快"的复利来源。这也解释了为什么"九门 harness 禁止重写、是子进程复用的既有资产"这条铁律不只是怕改坏,更是因为它是要被长期养厚的资产,不是用完即弃的脚手架。 + 这台机器当前的真实状态需要诚实说清:**结构正确、控制流确定、底层验收很硬的流水线已经建成并合入主干;但生成质量尚未稳定达到 80% 这道门,而且一部分本该可替换的"策略"被焊死进了不该重编译的"机制"代码里。** 换句话说,骨架立住了,接下来要解决的是"质量"和"策略外置"两件事——这正是 §4–§6 演进路线要回答的。 还要钉死一条比技术债更根本的**范式定性**(出处:同目录[设计合理性裁决](设计合理性裁决.md),2026-06-20 对抗审查,status 待创始人拍板):这套"便宜模型 + 受限 schema + 九门验收"是一条**为超休闲轻游戏(Tier0:打砖块 / 合成 / 挂机 / 答题 / 网格点选)量身打造的可靠产线,而不是一个通用生成范式**。它最大的风险不在工程层,而在被当成通用范式去对标 demo 里的 **Marvel 平台动作 / KOF 格斗**那一档富交互游戏——那一档这套范式**结构性地够不着**(运行时没有承载那层复杂度的形状),不是补个分支能解决的,必须显式把愿景分层、复杂品类另开一轨。下文 §3/§5 把这台机器框成"护城河的关键路径""值钱的东西我们还没有",成立的前提正是把它锚在 Tier0 这档;读时务必带着这条天花板,别把它读成"再补几层就能通吃所有品类"。 @@ -269,6 +271,8 @@ prompt 同源这一步一举两得:既根除了那处 P0 级 split-brain,又坐 - **Template Skill 按 gameDefinition 重写,且入库前过九门质量门。** 抄它的范式,但实现整体重写(它的物理信号正则和 hook 命名死绑了 Phaser)。**更关键的是:原版入库前没有任何回验门,带病的骨架会直接沉进库;我们必须给它加一道"入库前过九门或可构建校验"的质量门**——这恰恰是我们相对它的强项,把我们最硬的东西用在它最弱的地方。另要预警原版一个硬缺口:这套进化只有单调累积、没有遗忘 / 淘汰 / 冲突消解,也没有向量检索,家族一多会退化;等品类规模上来,我们可能需要补一层真正的检索。 - **资产线接 mmx。** asset 节点接 mmx-cli 替代那套重流水线,降级部分照多级回退思路兜底。顺带把它的确定性 bitmask 贴图(纯算法、与模型无关,用确定性算法绕开模型的空间推理)直接搬进来——这是 OpenGame 一个聪明的工程判断,几乎零成本可得。 +建 Debug Skill 与 Template Skill 这两套经验库时,有一条容易被忽略、但想得很深的设计约束要先立住:**经验要绑契约、不绑引擎,否则一次换引擎就会把攒了很久的经验库抹平(创始人 2026-06-22 历史回收判定捡回)。** 我们的引擎本就是"模板携带的可换实现选项"(Tier1 现在是 LittleJS,将来可能换),如果每条经验都和某个引擎的具体写法死绑,那换引擎那天经验库就归零、白攒。正确的做法是把每条 Debug / Template 经验**强制拆成两层**:一层是 **invariant(不变量)层**——失败类别(failureClass)、品类原型(archetype)、物理画像、契约级的事前预校验(proactive check),这些与具体引擎无关,换引擎 100% 继承;另一层是 **`engineBinding`(引擎绑定)层**——具体的修复 patch、骨架代码、引擎特定的检查,这些换引擎时需要 re-derive(重新推导)。这样切引擎的迁移路径就清楚了:invariant 层 100% 继承、绑定层按新引擎 re-seed(重新播种),再过一道**契约无关的黄金集 parity 门**——拿一组与引擎无关的黄金用例在新旧引擎上各跑一遍、比对通过率,**达标才切默认**。这条约束此前在 OpenGame 对照里讲 Debug/Template Skill 时完全没带,但它和"引擎是可换实现选项"这条原则同根,落地经验库时必须先按这个两层结构设计,事后再拆代价极大。 + ### 6.3 两处交汇点:必须合并,不能各列一遍 线 A 和线 B 有两处在解同一个问题,必须合成一项实现: @@ -303,6 +307,14 @@ flowchart LR **关键路径是一条线:阶段 2(prompt 同源解 split-brain)→ 阶段 4(质量信号可信)→ 阶段 5(cutover)。** 阶段 0 / 1 / 3 可并行。按价值排,最该立刻动手的三件依次是:**先补 template_api 与 GDD 契约(B1,一切约束的靶子)、再把 Debug Skill 落成 diagnose / repair + checkpoint、然后把 Template Skill 按 gameDefinition 重写并加九门质量门。** +### 6.5 两条远期方案的补记(创始人 2026-06-22 历史回收判定捡回) + +有两条早期讨论过、被列为"次要"后没进现行档的方案,这里各记一笔,免得它们被彻底丢掉、将来又从头讨论一遍。两条都是远期项,现在不排期。 + +**best-of-N 多候选并行(抬成功率的一条直接杠杆,但有硬前置和两条警示)。** 思路是同一 brief 同时跑 K 个候选、取过门质量最高的那一个交付——在 60% 实测基线下,这是抬成功率最朴素有效的办法之一。但它落不了,卡点不在算法而在架构:**它的硬前置是先解掉"整图串行"约束**(`SaaGraphDispatcher` 单线程 + `Semaphore(1)` 包住整条 `graph.invoke()`、build/play 子进程用固定端口,详见 [SAA编排 §整图串行约束](SAA编排.md))——整图串行下 K 个候选只能排队跑,墙钟退化成 K 倍,并行优势荡然无存。即便将来解了串行、真要上 best-of-N,还有两条评审给过的警示要先认:一是 **K 个候选高度相关**(同一便宜模型、同一 brief),挑最优带来的成功率上界压在约 **94%** 以下,不是"K 越大越接近 100%";二是**成本必须对账**——K 路并行是 K 倍的 LLM 开销,墙钟约 K×3.5–16min,这笔账要落进成本台账算清,别糊里糊涂烧钱。所以 best-of-N 是"先解 037 串行、再谈、且上之前先认清上界与成本"的远期项。 + +**实例级引擎复用(信息流场景的冷启动优化)。** 当前每跑一款游戏都要重新初始化引擎、重建 WebGL 上下文;在信息流这种"一款接一款连续玩"的场景里,如果能让一个常驻 runner 跨游戏**复用同一个引擎实例**,省掉反复的 init 和上下文重建,对冷启动体感收益很大。它没现在做,有两个原因:一是它被明确标为"等 S2 主考实测把它逼出来再上(2.x)"的有意延后项;二是它受候选引擎的 **destroy 卫生**制约——引擎能不能干净地销毁、不漏内存,直接决定实例能不能安全复用,而这恰恰是 LittleJS 选型时的一个考量因素(Phaser 的 destroy 泄漏 issue #2138/#5456 当年正是它落选因素之一)。记这一笔,是因为它是一条想清楚了、但有意压后的性能路径,别在做冷启动优化时把"复用实例"这个选项忘掉、也别忘了它对 destroy 卫生的依赖。 + --- ## 7. 我们刻意不做的 @@ -328,6 +340,8 @@ flowchart LR > **一条重要的模板哲学拍板(2026-06-12)**:**模板 = 引擎能力插件**(碰撞 / 粒子 / 物理 / 手感等,LittleJS 二次开发件),**不含玩法 / 美术 / 关卡 / UI——这四者是 agent 生成域**。玩法模板层被废除(它是同质化的根源)。所以"玩法模板"在本项目语义里 = 品类引导框架,影响生成 prompt 与脚手架,**不是一个可执行的游戏壳**。 +上面那张表的"预算档"一栏是**工程门**(成本和时延的硬上限),但同一个预算还有一层**产品面**,要补上、别只当工程数字看(创始人 2026-06-22 历史回收判定捡回):**预算即产品——绘豆与会员档决定创作者能用到哪一级生成、有多少额度,而且这个预算要对用户透明。** 创作者看到的不是"L1/L2/L3"这种内部分级,而是"我这个档位能造什么样的游戏、还剩多少次"。这一层把生成级别直接接到了两条收入线上:更高的生成级别(L2 扩玩法、L3 全栈)是订阅会员的付费墙,绘豆额度是用量计费的入口——创作者梯度在这里就是一条订阅转化漏斗(与同域那条"用生成级别做付费墙"是一脉)。配套还要把**第一笔收益的激活路径**讲给创作者:从"生成一款游戏 → 发布进信息流 → 拿到第一笔广告分成"这条链路要有明确引导,因为创作者留存的第一道坎就是"我造的东西到底能不能赚到钱"。这条产品面此前在生成引擎档没落点,而它恰恰是订阅与广告两条收入线的创作侧入口,值得记一笔。预算的具体数值(绘豆定价、各档额度、付费墙怎么卡)以变现战略档为准,本节只钉死"预算是产品、级别即付费墙、要引导第一笔收益"这条口径。 + 支撑这套体系的是**第 9 契约组**(生成工厂契约包,9a~9g):9a 模板协议(能力插件清单)、9b 作业与状态、9c 评估与就绪评分、9d 全链 trace、9e 代码补丁、9f 资产血缘、9g 收益归因。配套还有一个**生成控制平面**(配额 / 计费 / 背压 / 取消 / 幂等 / 补偿 / 防刷 / 降级——没有控制面的 agentic 系统会同时烧钱、压垮环境、放大滥用),以及一套**双轨灰度矩阵**(工厂路径按品类 × 人群灰度,黄金评估集通过率 ≥ 80% 且灰度 7 天错误率达标才切默认,跌幅 > 5pp 或破红线自动切回)。L2 起代码不可信,有一套七层信任边界(补丁面白名单、依赖锁定、静态安全门、构建隔离、运行取证、发布隔离、代码补丁契约)——细节都在源档,不在此展开。这里的"生成控制平面 / 双轨灰度矩阵"是蓝图级骨架;它的现行四组件设计(配置注册表、观测 / 审计仓、D12 运行治理门、管理面 UI,两条生成线共用)在同目录 [agentic 集成架构](agentic集成架构.md),以该档为现行口径。 --- diff --git a/docs/architecture/架构/生成引擎/SAA编排.md b/docs/architecture/架构/生成引擎/SAA编排.md index 2d0b63da..820eccdc 100644 --- a/docs/architecture/架构/生成引擎/SAA编排.md +++ b/docs/architecture/架构/生成引擎/SAA编排.md @@ -109,6 +109,8 @@ flowchart TD **engineBundle 是什么?** 它是最终的打包产物:build 节点把 gameDefinition(声明式的游戏描述)和 LittleJS(绘境AI 选用的 Tier-1 游戏引擎,详见[引擎与运行时](引擎与运行时.md))装配在一起,产出一个可以直接在浏览器里运行的 bundle。 +**render 节点的输入端不止"一句话"——还有确认目标和六类素材(创始人 2026-06-22 历史回收判定捡回)。** 图的入口画的是 render"解析创作意图 → PromptContext",这里要把它的输入端讲全,否则会让人以为生成永远只凭一句话起步。真实的创作输入有两条额外通道,都在 render 这一层被解析进 PromptContext,再随图往下流:**一是智能确认目标**——系统先分析创作者那句话,清晰的直接直通生成,模糊的才弹一张确认卡问清楚,确认结果以一个显式的 `confirmedGoal` 随上下文携带(不留隐藏共享态),而不是每次都打断、也不是永远不确认;**二是六类素材驱动(assetContext)**——创作者上传或选用的图元 / 角色 / 特效 / 场景 / 界面 / 音乐六类素材,透传进生成上下文(图片走多模态、音乐与脚本作结构化上下文),让生成有据可依而不是只凭文字臆测。这两条通道在编排里的落点就是 render→generate 这一段的 state(`PromptContext` 加素材引用),它们的完整交互设计(`/studio/analyze` 出 `{parsedGoal, needsConfirm, clarifyQuestions[]}` 的口径、六类素材契约、以及创作期数据回灌)以 [固定游戏架构 §对话式生成闭环](固定游戏架构.md) 为现行 SoT;本档只钉死它们"在 render 节点入图"这一编排接点,不重复展开。 + **为什么 MySQL/Redis 之外还画了一组虚线框?** 那是 future-state(未来态)的中间件——Nacos(服务注册/配置中心)、RocketMQ(消息队列)、Sentinel(流控熔断)。它们是 SAA / Spring Cloud Alibaba 框架自带的能力,但**基建按"消费者驱动"分期上线**:MVP 阶段只用已部署的 MySQL + Redis(Phase 1 零新基建);只有当真正出现第一个需要它们的消费者(例如 Tier-3 自治开发组,且 MVP 闭环已上线)时,才把这套控制面铺上去,绝不预先铺设。 --- @@ -223,6 +225,19 @@ SAA worker 的出口只代表这款游戏达到了"机制可玩"水准(过了九 代码落地有两个核心文件:`SaaStudioGraph.java`(唯一的节点布线源)和 `SaaGraphDispatcher.java`。 +### 整图串行约束:当前一次只能跑一条生成图(创始人 2026-06-22 历史回收判定捡回) + +有一条架构现状约束必须显式记下,否则后人提"并行抬成功率 / 抬吞吐"方案时会重新发现它、白绕一圈:**当前整条生成图是串行的,一次只能跑一款游戏。** 成因有两处叠加——`SaaGraphDispatcher` 是单线程的,并且用一个 `Semaphore(1)` 把整条 `graph.invoke()` 包住,同时图里 build / play 两步调的子进程(esbuild 构建在 4320、CDP 真玩在 9222)用的是**固定端口**。`Semaphore(1)` 保证任一时刻只有一条图在跑,正是为了让这两个固定端口不被并发任务抢占冲突。 + +这条约束的影响面比它看起来宽:它不只卡某一个功能,而是**任何"同时跑多条生成图"的方案的共同前置**。两个具体后果—— + +- **best-of-N 落不了**(同一 brief 跑 K 个候选挑最优交付):K 个候选要并行才有意义,但整图串行下它们只能一个接一个排队跑,墙钟成本退化成 K 倍、失去并行优势。所以 best-of-N 在现行档里只作远期方案记一笔(见 [生成引擎 README §6 / 待补](README.md)),它的硬前置就是先解掉这里的端口绑定。 +- **单局墙钟长这件事也与它同根**:走高质量路(M3 thinking-on 异步产线)时单局可达数十分钟,这是异步产线可接受的代价、但它和整图串行叠加,意味着"排队效应"会被进一步放大——前一款没跑完,后一款连起跑都排不上。 + +要解这条约束,真正要动的是"把固定端口换成每任务动态分配的端口池 + 放开 `Semaphore` 的并发度",这是一项独立的架构改造,不在 MVP 范围;在它落地之前,任何并行方案都先别排期。 + +> 口径归属:`Semaphore(1)` 串行守端口这条坑的逐键旁证在 `.agents/skills/saa-graph-orchestration.md`;本节把它从"实现坑"提升为一条"架构现状约束"记进架构档,因为它是 best-of-N 与一切并行生成方案落不了的共同根因,值得在提方案之前就被看见。同口径在 [agentic 集成架构](agentic集成架构.md) 也有一句对应的登记。 + --- ## 7. 与旧 agent-loop-v1 编排器的边界 diff --git a/docs/architecture/架构/生成引擎/agentic集成架构.md b/docs/architecture/架构/生成引擎/agentic集成架构.md index 6dc958f2..f792dff8 100644 --- a/docs/architecture/架构/生成引擎/agentic集成架构.md +++ b/docs/architecture/架构/生成引擎/agentic集成架构.md @@ -35,6 +35,22 @@ flowchart TB 仓里已经有一份《生成主线架构演进路线》(下称线A),它是配置外置那层地基的分期主计划:把 prompt 做成两端同源、解决 split-brain(同一份 prompt 被 Java 和 Python 各存一份会漂移),是它的阶段2;把模型名外置成 models.yaml 加跨语言一致性校验,是它的阶段3。配置外置那层地基,本设计不另立分期,只认领并引用线A。控制面真正的净增量收窄到几件:配置审计日志、管理面 UI、把两条线的轨迹收成一份统一契约、把配置注册表从 prompt 推广到 skill / tool / mcp、热加载机制选型。 +## Agent 框架可替换:反锁死原则(创始人 2026-06-22 历史回收判定捡回) + +控制面对外只暴露"读配置、写轨迹、过治理门"三件事,这背后还有一条更根本的架构原则,得显式立住:**平台不绑死在任何单一 agent 框架上。** 当下生产线是 SAA-only(决策 HJ-AGI-002),这是经双评审与源码核验后选定的实现;但"选了 SAA"不等于"被 SAA 锁死"。AgentScope / LangGraph / AutoGen 这些框架可以被借鉴、组合、在不同轨上分别采用(比如 long-term 的 tier2 premium 轨就走 AgentScope),平台真正固化、不随框架走的,是协议层那几件东西——把它们钉牢,框架就被压到"只租用不拥有"的位置,换框架时业务不被连根拔起。 + +固化在协议层、与框架解耦的是这五件: + +1. **任务协议**——生成任务怎么提交、怎么回调,边界就是 job/callback 契约 #6 暴露的 `GenerationDispatcher` 接口(见 [SAA编排 §4 不变量五](SAA编排.md));换框架只换 dispatcher 实现,调用方一行不改。 +2. **状态模型**——一次生成的状态怎么表达、怎么续跑(checkpoint 的语义),是平台自己的口径,不是某个框架的私有结构。 +3. **工具接口**——agent 能调哪些工具、工具的入参出参长什么样,以契约定义,不绑某框架的工具注册机制。 +4. **验收门禁**——"完成"由确定性九门裁定、禁止 LLM 自评,这条是平台铁律(同 §4 不变量二),无论底下换成哪个框架,出题与被考不同源这条都不让步。 +5. **遥测事件**——每次生成发生了什么,落进统一 trace 契约(`contracts/trace/`,公共核心子集对称、扩展段各写各的),采集机制可以两条线各按各的框架来,但数据口径是平台的,不随框架漂移。 + +这条原则不是空谈"将来好换",它有具体落点:它正是 long-term 要不要把某条轨从 SAA 切到 AgentScope 时的**判据**——只要那五件仍稳稳钉在协议层,切换就只是换一个被治理的执行后端,而不是推倒重来。反过来,如果哪天发现某个框架的私有结构悄悄渗进了上面五件中的任何一件(比如轨迹格式被某框架的 span 结构绑死、任务协议泄漏了框架的内部状态),那就是锁死的开始,要立刻在协议层把它隔离回去。这也解释了本档为什么反复强调"管理面只渲染运行时自报的拓扑、绝不另持一份拓扑模型"——那同样是反锁死:管理面里硬编码的框架拓扑,换框架时就是阻力。 + +**一条配套的架构现状约束登记(037,与 [SAA编排 §整图串行约束](SAA编排.md) 同口径)**:SAA 这条线当前整图串行——`SaaGraphDispatcher` 单线程 + `Semaphore(1)` 包住整条 `graph.invoke()`、build/play 子进程用固定端口(4320 构建 / 9222 真玩),一次只能跑一款。它是 best-of-N 与任何并行生成方案落不了的共同根因;要解得先把固定端口换成每任务动态分配的端口池、再放开并发度。控制面将来若要给生成线排"并行抬吞吐"的能力,这条端口绑定是硬前置,提方案前先看见它。逐键旁证见 SAA编排,这里只登记一句,避免后人在治理层重新发现。 + ## tier2 接入面:官方 Agent Service + Agent Team 在讲控制面四个组件怎么接 tier2 之前,得先说清 tier2 这条线的接入面长什么样 —— 它不是我们自造的,是 AgentScope 2.0.3 的官方 service 层,源码逐条核过(`agentscope/app/`)。这层既是 cloud 调 tier2 的入口(控制面在这之上加治理),也是 tier2 内部多 agent 协作的底座(管理面对它的拓扑做可视化)。把它讲清,控制面/管理面才不会去重复造轮子。 diff --git a/docs/architecture/架构/生成引擎/固定游戏架构.md b/docs/architecture/架构/生成引擎/固定游戏架构.md index cd1c091e..19a380a9 100644 --- a/docs/architecture/架构/生成引擎/固定游戏架构.md +++ b/docs/architecture/架构/生成引擎/固定游戏架构.md @@ -136,6 +136,18 @@ flowchart LR > **演进路线(接法 A / 接法 B):** 当前 16 节点是**接法 A**——裸图确定性编排,由九门判定"做完了没"(已建七成、是躯干)。**接法 B** 是让 generate/repair 长成一个 **ReactAgent 自治工具循环**(把"写源、构建、跑九门、读错误、改配置和资产"都做成它能自己调用的工具)。九门兜底化解了"自治"与"铁律"的张力——**自治在门内、裁决在门外**。策略是先用 A 稳住地基,再用 B 增量演进,避免返工。 +### 4.5 对话式生成闭环:输入端不止一句话,还有确认目标、六类素材与创作期回灌(创始人 2026-06-22 历史回收判定捡回) + +前面几节把镜头对在"工作室怎么把输入造成游戏"上,把输入默认成了"一句话"。但创始人口径里的"真创作能力"是两半——"一句话快"只是其中一半,另一半是"确认目标准、有素材依据、能据试玩反馈越调越准"。这后一半此前散在几份 review 里、生成引擎档没有落点,这里把它作为现行 SoT 立住。它由三个互相咬合的机制构成,共同把生成从"一次猜"变成"一段对话"。 + +**一是对话式生成 + 智能确认目标。** 让便宜小模型从一句话直接开造,风险在于模糊的需求会被它各自脑补、跑偏。但反过来"每次都弹一堆问题让用户确认"又会把"一句话快"这个卖点毁掉。正确的折中是让系统先判一判:创作者那句话清晰、信息够,就直接直通生成;只有当它**模糊**、缺了关键决策点时,才弹一张确认卡问清楚。落地接口是 `/studio/analyze`,它产出 `{parsedGoal, needsConfirm, clarifyQuestions[]}`——`parsedGoal` 是系统对这句话的结构化理解,`needsConfirm` 标记要不要追问,`clarifyQuestions[]` 是模糊时要问的那几个问题。确认的结果以一个**显式的 `confirmedGoal`** 随上下文往下携带,而不是塞进某个隐藏的共享态里偷偷影响后续——这条"无隐藏共享态"很重要,它让"这一轮到底按什么目标生成的"始终可追溯。这套 analyze→(可选)确认→生成,在编排里的入图接点是 render 节点(见 [SAA编排 §2](SAA编排.md) render 输入端那段),`confirmedGoal` 随 `PromptContext` 流进 design / generate。 + +**二是六类素材驱动生成(assetContext)。** "素材驱动创作"是产品侧明确的卖点:创作者不止能打一句话,还能上传或选用图元 / 角色 / 特效 / 场景 / 界面 / 音乐**六类素材**,让生成有真实素材作依据,而不是只凭文字臆测。这里要分清一个极易混的边界——本档 §5 契约⑤讲的 `assets[]` / `assetSpec` 是**生成产物侧**的六类资产规格(generate 出来的、要装进 GamePackage 的),而这里说的 assetContext 是**生成输入侧**的六类素材透传(用户带进来、喂给模型作上下文的)。两者品类枚举同名(sprite/character/effect/scene/ui/music)但方向相反:一个是"用户给的料",一个是"工作室产的活"。透传时图片类走多模态通道(让视觉模型看见),音乐与脚本类作结构化上下文(进 prompt)。这条输入通道同样在 render 节点入图,随上下文驱动 design 与 generate;它和上面 020 那条"每类资产一个生成 workflow"是两件事——020 是"怎么产六类资产",这里是"怎么吃用户带来的六类素材",别合并。 + +**三是创作期数据回灌。** 数据回灌有两个闭环,极易只记住一个。一个是**发布后**的:游戏上线后,据玩家遥测与反馈,工作室回到项目继续演进(对应 §1 那张图的下游、以及 README 范式里的 maintain 步)——这一半生成引擎档已经讲了。另一个是**创作期**的,此前没落点:创作者在发布前**自己试玩**这款半成品时,会暴露出流失点(玩到哪里就不想玩了)、难度卡点(卡在哪一关过不去)。把这些信号**结构化地喂回对话调整**,让下一轮生成或修改据此校准——这就把"改"也变成了有数据依据的对话,而不是创作者凭感觉描述"太难了"。它和发布后那条是两条不同的闭环:一条用真实玩家数据驱动长期运营演进,一条用创作者自己的试玩数据驱动当下这次创作的收敛。三者合起来,对话式生成才真正成"闭环"——确认目标定准了起点,素材喂厚了依据,试玩回灌让每一轮调整都更准。 + +> **contract-first 落地清单(待落地,勿当已建)**:上述三个机制大多仍是设计、尚未在生成引擎子树成 code SoT,落地前要先把契约面定清——① `/studio/analyze` 的请求/响应契约(`{parsedGoal, needsConfirm, clarifyQuestions[]}` + `confirmedGoal` 的回传),进 API schema;② SAA state key 增 `confirmedGoal` / `assetContext`(输入侧素材引用),严格 additive,与 §5 契约④口径一致;③ 输入侧素材透传若需落库,核对是否复用 `game_material`(P-MAT 素材中心)而非新表;④ 创作期回灌的信号结构(流失点 / 卡点的字段)与它喂回 design/generate 的接点,以及它与发布后遥测回灌的去重边界。这些都标"待落地",别写成现成。 + --- ## 5. 八个契约:两条开发线的唯一事实源 diff --git a/docs/architecture/架构/生成引擎/验收门-W-G1.md b/docs/architecture/架构/生成引擎/验收门-W-G1.md index c6efbe8a..018fc47f 100644 --- a/docs/architecture/架构/生成引擎/验收门-W-G1.md +++ b/docs/architecture/架构/生成引擎/验收门-W-G1.md @@ -70,7 +70,7 @@ flowchart TD 这三组门的取舍理由,可以浓缩成三条核心决策: 1. **D12 和 GP9 为什么必须硬阻塞?** 因为这两件事不做,后果都不可逆。后台的生成 worker 是**全局串行**的(一次只处理一个任务),不做控制平面,单个用户的并发请求就能把它压垮,所有人都生成不了;不做合规先行,违规内容会直接生成出来进入玩家信息流,这是法务红线,一旦发生无法回收。 -2. **那 3 道落库门为什么第一版只观测、不拦截?** 因为底层那套"九门 harness"(在真实浏览器里跑游戏、用九道确定性检查判定能不能玩的测试夹具)已经是挡住坏游戏的**硬地板**了。这三道落库门是更上一层的质量观测,第一版若一上来就生效拦截,反而会**误杀好游戏**——所以先只记录数据,等积累够了再考虑收紧。 +2. **那 3 道落库门为什么第一版只观测、不拦截?** 因为底层那套"九门 harness"(在真实浏览器里跑游戏、用九道确定性检查判定能不能玩的测试夹具)已经是挡住坏游戏的**硬地板**了。这三道落库门是更上一层的质量观测,第一版若一上来就生效拦截,反而会**误杀好游戏**——所以先只记录数据,等积累够了再考虑收紧。(这里"九门硬地板"说的是**开闸放行**那一侧:一款游戏要进信息流,仍按完整九门要求。但**生成环在迭代生成时怎么消费九门裁决**已于 2026-06-20 收窄成"只认五道客观健康门 A–E",两套口径别混——详见 §2.4。) 3. **真实计费为什么不在这一批?** 见 §1.2。 ### 1.2 真实计费扣退为什么被拆出去(随 M4) @@ -148,6 +148,22 @@ flowchart TD - **回滚**:整个控制平面挂在 `aigc.control-plane.enabled` 这个功能开关(feature-flag)后面,**默认关闭 = 现行逻辑逐字不变**(全部门加 GP9 都旁路)。 - **契约与数据迁移**:合规负例语料放在契约目录 `contracts/prompts/eval/safety.prompt-check/{inputs,labels}.jsonl`,共 **10 条负例,覆盖 10 类合规红线类目**;数据库迁移 `V15.0.0__aigc_task_add_level.sql` 给任务表加 `level` 列,只增不改(additive)、默认值 1,存量数据回填为 L1。 +### 2.4 生成环消费九门的口径:硬门收窄成客观健康门 A–E(创始人 2026-06-22 历史回收判定捡回) + +前面几节把九门 harness 讲成一道统一的"硬地板",这个说法在"开闸放行"这个语境里仍然成立——一款游戏要进信息流,确实要先过这套真玩检测。但要把一件 2026-06-20 拍下的口径变化讲清楚,否则架构档会和现行真相脱节:**生成环(SAA 管线)在迭代生成时怎么"消费"九门的裁决,已经从"九门全过才算成功"收窄成了"只认五道客观健康门 A–E"。** 这是 gamedef 生成质量从 all-9 口径下的约 50% 真正做到 91.7% 的直接原因之一(另一半来自走 Anthropic 原生 thinking 分离协议)。 + +先把九道门按"判什么"分成两类。一类是**客观健康门**,它们不依赖 driver(driver 指真玩脚本里那段"知道这款游戏该点哪、该划哪"的操作逻辑)就能判定,纯看运行时本身健不健康:A_boot(能不能起来)、B_uncaught(有没有未捕获异常)、C_frame(跑不跑帧)、D_render(画面有没有真渲染)、E_live(进程活不活着)。另一类是**driver 依赖门**:G_input(响不响应输入)、H_progress(机制有没有进展)、I_control(可控性),这三道必须有一段能真玩这款游戏的 driver 才判得了;而 F_wiring(游戏事件有没有真触发 `rt.fx` 之类特效)同样依赖游戏被真玩起来,没有 driver 必挂。 + +收窄后的口径是: + +- **生成环的硬门只认 A–E 五道客观健康门**。便宜模型新生成一款游戏、还没有为它写专属 driver 时,G/H/I 三道 driver 依赖门**不再否决生成、也不进救场回喂**——它们降为"参考门",失败只记录、不把这一轮判死,免得因为缺一段 driver 就把一款其实健康的游戏空跑八轮救场烧掉。 +- **F_wiring 移出客观硬门**。"有没有真用引擎、有没有真特效"这层语义,改由 VLM 看截图来判(对应 README/OpenGame对照里那条"player 软门做厚"),不再让一道必然挂的事件触发门去卡生成。 +- **九门 harness 本身一行不改**:它照常跑、照常把九门逐门结果写进 `verdict.json`,门的判定逻辑动都不动。变的只是"生成环如何读这份 verdict"。这条边界很关键——动的是消费侧策略,不是裁判本身,所以"开闸放行"那一侧仍可以按完整九门来要求。两套口径用 `-Dsaa.gen.gateMode=all9` 双轨可回退:默认走收窄后的客观门模式,加这个参数就退回旧的"九门全过"模式做对比。 + +这个收窄背后还藏着一条**必须记住的实现约束(030)**,它是客观门解耦能不能真正生效的前提。`SaaGenNodes.playNode` 判 pass 时,如果前置条件写成 `rc==0`(rc = 真玩脚本 `play.cdp.cjs` 的退出码),问题就来了:这个退出码本身是**九门聚合**的——只要任意一道门(含 driver 门)挂了,脚本就 exit 1。于是一旦某道 driver 门失败让 rc=1,它会**反向否决**掉"只认客观门 A–E"的解耦,让收窄形同虚设——2026-06-20 当天就是这个 bug 让 Phase 1 空转、白烧了 302K token。修法是在客观门模式下把判据改成 `pass = (rc==0 || rc==1) && objectiveGatesPass(verdict)`:不再拿聚合退出码当门,而是直接读 `verdict.json` 里 A–E 五道门的结果。谁要在生成环里重写 verdict 消费逻辑,这条耦合坑必须先避开,否则解耦白做。 + +> 口径归属:这次收窄和那条 rc 耦合坑已蒸馏进 `.agents/skills/saa-graph-orchestration.md` §3.5;决策与 Phase 路线记在 `docs/plans/2026-06-20-关闭九门判定-全面参考OpenGame-决策与Phase0-4.md`。本节把它回填进架构档,是为了让"九门统一硬地板"这个旧讲法对齐到"开闸侧仍要完整九门、生成环只认客观门 A–E"的现行真相,避免后人据旧讲法去重写生成环又踩一遍 rc 坑。OpenGame对照档里那条 Phase 0–4 落地路线([OpenGame对照 §3.5](OpenGame对照.md))承接的正是这条收窄之后"往哪走"。 + --- ## 3. 组B:三道落库门(9d trace + D11 就绪评分 + D9 反同质化) diff --git a/docs/architecture/运维/README.md b/docs/architecture/运维/README.md index 6e992fcc..14c586be 100644 --- a/docs/architecture/运维/README.md +++ b/docs/architecture/运维/README.md @@ -124,3 +124,41 @@ flowchart TB > ⚠️ **blast radius(我作为工程师的提示)**:上 k8s 是**部署架构的大变更**——当前是单体 staging(mini-desktop 容器),迁 k8s 会改动 [staging-ops](../../../.agents/skills/staging-ops.md) 整套部署链与四机分工,影响面远大于其余三件观测工作。建议把"k8s 迁移"**单独立一个设计 / 实施项**,与观测埋点解耦推进,别让观测大盘被 k8s 迁移阻塞(观测栈本身在单体 staging 上也能先跑起来)。 **下一步**:由我出正式设计稿(观测体系 + k8s 迁移建议分两份);采集埋点、栈搭建、集群迁移的代码执行归 Mac。 + +--- + +## 5. 平台后台 job 调度面的运维归属(创始人 2026-06-22 历史回收判定捡回) + +上面 §1.1 说"常驻定时任务落在 6c6g",但那指的是 agent 编排的 cron——和平台业务自己的那批后台 job 不是一回事,后者一直没有运维落点,这一节把它补上。 + +平台现在有一整批后台批处理 job,它们的业务逻辑各档讲清楚了,但"跑在哪台机、卡了谁发现"作为一个整体是空白的:变现链路有三个带 `@TenantJob` 的结算/补偿 job(`tradeSettlementJob` 日结算、`WithdrawPayoutCompensateJob` 打款补偿、`RewardPayoutJob` 打赏发放,业务面见[运营域 变现端到端](../运营/变现端到端.md)),telemetry 有一个把埋点事件日聚合成质量分的 job(见[后端域 数据模型 §2.3](../后端/数据模型.md)),数据飞轮规划了一个把三源 join 出来落档的离线归档 job(见[数据飞轮 §3.3](../架构/生成引擎/数据飞轮.md))。再加上上面观测体系 §3.7 新增的 new-api 网关健康巡检,后台 job 已经成批,却没有一处回答"这些 job 由谁调度、跑在哪、失败谁知道"。 + +这些业务 job 跑在 yudao 自带的 XXL-Job 调度框架上(`@TenantJob` 是 huijing 对 XXL-Job 任务的多租户封装),它和 agent 编排 cron 是两套东西,所以运维归属要单独定:**executor 注册与 job 实际运行落在 staging 机(mini-desktop)的后端进程内**——这批 job 是后端单体的一部分,跟着 `huijing-server` 起,不另开机器;**XXL-Job admin 调度控制台**作为查看调度记录、手动触发、看失败重试的入口,部署落点与访问端点按内网铁律登记进 [`docs/内网凭据与端点.md`](../../内网凭据与端点.md);**job 的失败告警接进观测栈的夜莺**,与 §3.4 那张 P0–P3 表统一——结算 job 失败意味着创作者拿不到钱、归档 job 卡住意味着语料断供、网关巡检冻结阀拉起意味着生成命脉告急,这几类按其业务影响归入对应告警级别,而不是让它们静默失败到第二天才被人发现。 + +这条覆盖现有(三个 trade job + telemetry 聚合)和新增(飞轮归档 job + 网关健康巡检)的全部后台 job,是把第一轮只点了"三个结算 job 运维面空白"的盲区,扩成"全平台 job 调度面归属"统一定调。 + +> **待落地的运维落点(现在没有)**:① XXL-Job admin 控制台在 staging 机上的部署与端点登记(进内网凭据档);② executor 注册健康(executor 掉线会让所有 job 静默不跑)纳入观测——给 XXL-Job 的调度成功率/executor 在线数打指标推 Prometheus;③ 每个 job 的失败/超时夜莺告警规则。落地前,"结算 job 跑没跑、归档 job 卡没卡"只能靠人主动去 XXL-Job 控制台翻,没有告警兜底。 + +--- + +## 6. Feature Flag 生命周期纪律:上线稳定后强制清理(创始人 2026-06-22 历史回收判定捡回) + +现行代码里 feature-flag 用得很密——W-G1 开闸的 `aigc.control-plane.enabled`、生成产线切换的 `saaSourceMode`、九门的 `GATE_ALL9`,以及观测体系新增的埋点开关、网关批跑冻结阀,都是"默认关、验稳了再 flip"的灰度开关。这套用法本身是对的(新能力先关着上线、隔离验证过再放量,见 [staging-ops §3](../../../.agents/skills/staging-ops.md) 的 `-D` 注入真验 flag 配方),但它有个一直没人管的后半段:**flag flip 到稳态之后,该不该清、什么时候清,没有任何纪律约束**。结果是默认关的开关只增不减,攒成一堆没人敢动的死代码——每个 flag 都对应一段"开了走这条、关了走那条"的分支逻辑,flag 永久留着,这些分支就永久背在身上,以后改这块代码的人得先搞清每个开关的死活才敢动。 + +纪律定为:**一个 feature-flag 一旦 flip 到目标态并稳定运行一段时间(参照原蓝图口径约 2 周),就必须把开关连同它另一侧的废弃分支一起删掉,让代码只剩下胜出的那条路**,不留"理论上还能切回去"的死开关。判断一个 flag 是不是该清,看它是不是已经完成了使命:控制平面验稳了、产线模式定了、九门固化了,这些 flag 的存在意义(灰度过渡)就消失了,该退役。需要长期保留的运行时可调参数(比如阈值、限额这类要随运营调整的)不算这一类——那是配置,不是过渡开关,二者要分清:**过渡开关有明确的"用完即弃"终点,运行时参数没有**。 + +这条之所以要写进运维域而不只是口头约定,是因为它是个会随时间累积的技术债红线:每次波次收口都可能新增几个默认关的 flag,没有强制清理纪律,死开关的数量只会单调上涨。波次收口时(见 [`.agents/skills/wave-close-checklist.md`](../../../.agents/skills/wave-close-checklist.md))应顺带盘一次"本波或更早 flip 过的 flag 有没有到清理点",把到点的开关清掉,避免攒到无人敢碰。 + +> **注**:现行 flag 全靠 `-D`/yaml + 重部署生效,没有 admin 后台热改能力(那要等 Nacos 作为配置中心上线才解锁,future-state)。所以现在清 flag = 改代码删分支 + 重部署,不是后台点一下;这反而更要求"用完即清",否则每个死开关都是一段永久编译进 jar 的废逻辑。 + +--- + +## 7. 上线前数据可靠性前置清单(创始人 2026-06-22 历史回收判定捡回) + +§1.4 把可用性硬指标定在 ≥99.5%,但可用性达标的另一半——数据不丢——现行档一直没有一处汇总。内网 staging 阶段用的是隔离容器 + seed 假数据、库可重建,丢了不心疼,所以这一摊一直没人接;可真上线后,数据保护是和可用性并列的硬约束,而且其中有一类资产丢了不可再生:创作者生成的游戏包和素材。游戏包不像缓存能重算,丢了就是创作者的作品没了。所以在真上生产之前,要有一份明确的数据可靠性清单逐项落地,而不是上线了才临时补。 + +清单覆盖四件,都是"上线前必须就位、内网 staging 阶段可暂缓"的生产约束:**一是 MySQL 高可用**——生产库走主从复制,主库故障从库能顶上,而不是单点;**二是备份频率与保留**——每日全量备份打底、binlog 增量兜到分钟级,明确备份留多久;**三是 OSS(对象存储)容灾**——游戏包和素材所在的对象存储做跨区域复制,异地留一份,防单区域故障把不可再生的创作者作品一锅端,这一条尤其要紧,因为它护的是丢了无法重算的资产;**四是恢复演练**——备份不是存了就算数,要定期真跑一次"从备份恢复"演练,确认备份真能恢复、恢复要多久(对应 SLO 里支付 43 分钟/月、游戏流 3.6 小时/月的 error budget,恢复时长直接吃这个预算)。前三件是"有没有备份/有没有冗余",第四件是"备份到底能不能用",缺第四件前三件都是纸面承诺。 + +这份清单的定位是运维域的"上线前数据保护门",和 §1.3 的冒烟门(部署后跑没跑得起来)、§4 的观测体系(线上跑得住不住)互补:冒烟门管"这次部署对不对",观测管"线上健不健康",这份清单管"数据丢不丢、丢了能不能恢复"。三者合起来才撑得住 ≥99.5% 可用性 + 数据不丢这两条硬约束。 + +> **现状与待落地**:内网 staging 阶段四件均未落地(隔离容器单实例、无主从、无跨区复制、无恢复演练),这是有意降级——staging 数据可丢,不值得为它建主从。**这份清单是"真上生产前必须逐项落地"的前置门,不是已建项**;上生产前要把它从 staging 现状逐条抬到生产标准。其中 MySQL 主从、每日全量+binlog 在 [`security-and-reliability.md`](../../../.agents/rules/security-and-reliability.md) §5.2 留过一行口径,OSS 跨区域复制此前整棵树没有落点,这一节是它的家。 diff --git a/docs/architecture/运维/观测体系.md b/docs/architecture/运维/观测体系.md index 90359c33..29349808 100644 --- a/docs/architecture/运维/观测体系.md +++ b/docs/architecture/运维/观测体系.md @@ -212,6 +212,18 @@ flowchart LR **和可用性目标的关系 = 观测是 ≥99.5% 的度量与举证手段。** 现在 ≥99.5% 是个目标数字,但没有任何东西在持续度量它、没有 error budget 在被消耗和记录。观测体系把它落地:用 health 探测的成功率算游戏流 API 的实际可用性,对着 `security-and-reliability.md` §5.1 那张 SLO 表(游戏流 99.5%/月 error budget 3.6 小时、AI 生成 99%/7.2 小时、支付 99.9%/43 分钟)做 burn rate 看板和告警。这样"达没达标"从一句承诺变成一张有数据、有 error budget 余量的看板,创始人随时能看见这个月还剩多少容错预算。 +### 3.7 LLM 网关(new-api)健康巡检:盯生成命脉本身,而不是盯调它的那次请求(创始人 2026-06-22 历史回收判定捡回) + +上面 §3.2 埋的 `gen_task_total`/`gen_duration_seconds` 这套指标,盯的是"业务侧调 new-api 这次调用快不快、成没成";它们看不见的是网关本身的健康——new-api 背后挂着多条上游通道,每条对应不同供应商的 key,一条通道的 key 失效或被供应商封了,落到业务侧只表现为"生成成功率掉了",但那已经是结果坏了之后。把网关自身的健康单拎出来盯,是因为它是整个平台的命脉:网关一旦多条通道批量失效,所有生成全停,而不是某一类游戏生成不了。这不是假想的风险——2026-06 真发生过二厂系通道整批作废,当时只能靠人去翻日志才发现生成为什么集体失败。 + +要盯的是三件,它们和生成成功率告警是互补的前后两层。**第一件是多通道健康巡检**:周期性地对 new-api 配置的每条上游通道做一次最小探活(一个极小的 chat completion 请求,只问通道还通不通、不在意内容),把每条通道的"通/不通、延迟"打成指标,这样看板上能直接看见"现在还有几条通道活着",而不是等业务调用失败了反推。**第二件是 key 激活状态监控**:盯每个 key 的有效性与额度,new-api admin 接口能查出 key 的启用状态和已用额度,key 被禁用或额度耗尽时要在它影响生成之前就告警。**第三件是批跑冻结阀**:当健康巡检判定可用通道掉到某个下限(比如只剩一条、或全废),要能自动把后台批量生成(W-G1 竞标批跑、夜间批生成这类高并发消耗 key 的任务)冻结住,避免在通道已经半废的情况下继续猛打、把仅存的通道也打爆,同时给前台单次生成留一条降级到单通道运行的活路。冻结阀拉起后告警必达,由人确认通道恢复后再解冻。 + +这三件的告警分层接进 §3.4 夜莺那张表:**单条通道失效、key 额度告警**属于"结果还没坏、但前哨亮了"的前置预警(归 P2 一档,先在群里通知去补通道/换 key);**可用通道全废、批跑冻结阀拉起**属于命脉级,生成即将或已经全停(归 P1,等同生成成功率<70% 的紧急级,短信+群叫人)。次序很清楚:通道健康巡检在前(结果坏之前的前哨),生成成功率<70% 告警在后(结果已经坏了),两层都要,缺前哨就只能等生成集体失败了才知道网关出了事。 + +> **巡检的部署落点**:网关健康巡检是一个轻量周期任务(每条通道探活 + 查 key 状态),它的运维归属并入下面 README §5 讲的"平台后台 job 调度面"——和结算 job、telemetry 聚合 job 一样,作为一个定时 job 跑在 staging 机上,失败/冻结阀触发的告警接进夜莺。探活产出的通道健康、key 额度指标推给 Prometheus,在 Grafana 上和生成成功率画在同一块大盘,让"网关背后还活着几条通道"和"生成成功率"并排可见。 + +> **contract-first(待落地,现在没有)**:① **巡检 job**:新建一个 new-api 网关健康巡检 job(周期探活每条通道 + 查 key 激活/额度),在后台 job 调度面注册;它读 new-api 的 channel/key 管理接口(端点与 admin token 按内网铁律取自 [`docs/内网凭据与端点.md`](../../内网凭据与端点.md))。② **新增指标**:`llm_channel_up{channel}`(每条通道通/不通)、`llm_channel_latency_ms{channel}`(探活延迟)、`llm_key_quota_remaining{key}`(key 剩余额度)——三者都是纯应用内新增的 Micrometer/OTel 指标,不动契约 yaml/DB。③ **冻结阀开关**:批跑侧需要一个可被巡检 job 置位的"生成批跑冻结"标志(一个 feature-flag 形态的开关,通道全废时置位、人工确认恢复后清),批跑任务启动前先读它;具体落成配置项还是控制平面状态待落地时定。这三件落地前,网关健康在看板上是空的,通道批量失效仍只能靠人翻日志发现。 + --- ## 4. 分期落地 diff --git a/docs/architecture/运营/变现与单位经济.md b/docs/architecture/运营/变现与单位经济.md index dbfaca83..5d3f23bc 100644 --- a/docs/architecture/运营/变现与单位经济.md +++ b/docs/architecture/运营/变现与单位经济.md @@ -121,6 +121,8 @@ flowchart LR eCPM 取三档做敏感性扫描:**悲观 15 / 基准 30 / 乐观 60 元/千次**(激励视频口径)。注意这是用来摸边界的扫描,**不是收入预测**——外部核查只拿到从业者给的 20-80 区间,低置信。 +这里必须钉一个口径地雷,否则跨页引用会得出自相矛盾的结论(创始人 2026-06-22 历史回收判定捡回):**绘境AI 内部存在两套不同口径的 eCPM,差约一个数量级,对照前必须先对齐。** 本页和敏感性模型用的是"激励视频每次曝光"口径的 eCPM 15/30/60;而另一份《全成本收益测算 v2》用的是"完整观看单价"口径——单价 ¥0.4/0.75/1.2,折算成激励位 eCPM 约 200/562.5/1080。两者算的不是同一个量:前者按每次广告曝光摊,后者按每次完整观看摊,完整观看率远低于曝光数,所以折算下来差了约一个数量级。任何人拿全成本 v2 的回本月份去对照本页的"1.33 万 DAU 回本",如果没先对齐这两套口径,会得出矛盾结论却不自知。所以引用 eCPM 数字时务必标清是哪套口径,跨两份模型对照前先做口径换算,别把曝光口径的 30 和完整观看口径折算的 562.5 当成同一回事。 + 这个模型最重要的一句话,也是它对战略的真正贡献: > **自有端 IAA 是"万级 DAU 才回本"的规模游戏。** 在基准档(eCPM 30、人均 3 次展示/日)下,覆盖 ¥4,300/月基建成本需要约 **1.33 万 DAU**(日活用户)。种子期只有百级 DAU 时,月留存只有几十元量级。 @@ -129,6 +131,14 @@ eCPM 取三档做敏感性扫描:**悲观 15 / 基准 30 / 乐观 60 元/千次* 关于"满 5 元提现"对创作者的可达性:头部款可达(eCPM 30 时需单款约 12 次激励展示/日),长尾款不可达。因此**对创作者宣传"能赚钱"时,必须用头部款的口径,不能做普遍性承诺**——这是审计 R3 连带的诚信红线。 +这条诚信红线不能只活在经济模型档里,要落到创作者引导/激励的文案层(创始人 2026-06-22 历史回收判定捡回)。"满 5 元提现"对长尾款长期不可达,如果产品在创作者引导、激励页、收益预期这些文案里暗示"做了就能提现赚钱",那就是一笔面向用户的潜在诚信债——种子期绝大多数创作者的广告收益接近零,提现门槛长期够不着,落差会反噬留存和口碑。所以面向创作者的收益预期管理要做实:文案讲收益时用头部款口径、不做普遍性承诺,把"收益取决于作品表现、长尾款可能长期达不到提现门槛"这层预期诚实地前置给创作者,而不是只在内部经济模型档里写一句诚信红线、对外却用"能赚钱"做钩子。 + +上面 eCPM 三档摸的是"单位收入"的边界,但回本快慢的头号变量并不是 eCPM(创始人 2026-06-22 历史回收判定捡回)。《全成本收益测算 v2》的九宫格敏感性给出一个更要命的结论:**回本月份对月增速的敏感度,高于对 eCPM 的敏感度——月增速才是回本的头号杠杆。** 在零投流假设下取月增速 15%/25%/35% 三档扫描,同一个 eCPM 基准档里,月增速从 15% 升到 35%,回本月份近乎减半(基准列从 24 个月缩到 12 个月)。而这个最主导回本的变量,恰恰是当前**最没把握、完全未经验证**的一个——它建立在"零付费投流也能撑住这个月增速"的强假设上,而"不花钱买量能不能持续拉到这么高的自然增长"还没有任何实测数据支撑。 + +这条直接关系到对外讲回本周期时的诚实度:拿乐观月增(35%)算出来的"一年回本"和拿悲观月增(15%)算出来的"近三年回本",差着一整个融资窗口,而决定走哪条路的恰恰是这个最不确定的变量。所以**对外讲回本周期时必须连带声明这个头号假设**——讲任何回本月份,都要同时说清"这个结论的头号假设是零投流下的月增速、属低置信、待 W4 拉新埋点实测验证",不能拿乐观月增算出的回本数字单独抛出去给人一个过于乐观的预期。这条和下面 §4.3"拿到真实账单前不对外锁价"、以及创作者收益文案的诚信红线是一组对外口径纪律:凡是对外抛数字,都要把它背后最不确定的那个假设一并交代清楚。 + +还有一条成功率的对外口径要钉清,避免对外讲"生成成功率"时虚高或自相矛盾(创始人 2026-06-22 历史回收判定捡回):**绘境AI 有两个不同的成功率指标,对应两件不同的事,对外口径统一前要做双指标声明。** 一个是**王蓝莓窄域 ≥90%**——单 IP × 单点玩法(1 个 IP 配 2 种玩法)打透的可行性验证门,衡量的是"单点能不能做到极致";另一个是**生成工厂宽域 ≥80%**——海量 UGC 任意题材的平台能力门(对应 W-G1 开闸验收的 ≥80% 现行口径),衡量的是"广域随机生成能不能稳"。这两个数不能混为一谈:窄域是收窄了输入空间打深的成绩,宽域是放开输入空间求稳的成绩,窄域天然比宽域高。对外讲成功率时若不区分,要么拿 90% 的窄域数去冒充平台普遍能力(虚高),要么把两个口径混着引用导致自相矛盾。所以引用成功率务必标清是窄域单点验证(≥90%)还是宽域平台能力(≥80%)。 + ### 4.3 三个假设值的红线 成本侧涉及三个还没拿到真实账单、暂时占位的假设值。创始人 2026-06-11 已采纳一条红线:**在拿到真实账单前,这三个值一律标注【假设·待测】,不作为预测口径,不对外锁价。** @@ -139,6 +149,16 @@ eCPM 取三档做敏感性扫描:**悲观 15 / 基准 30 / 乐观 60 元/千次* | `QUOTA_PER_UNIT` | 500000 | new-api 额度单位换算(每 USD) | | `USD_CNY` | 7.2 | 美元兑人民币汇率 | +这条红线不能只管内部成本测算,要一路延伸到对外材料(创始人 2026-06-22 历史回收判定捡回)。这三个假设值真实化依赖创始人提供 new-api 网关的真实账单口径(关联 A1 闸门里的 LLM 实名充值闸门),在账单到手前它们只是占位值。这意味着任何由它们推导出来的单款成本、毛利、回本测算,**对外都不能当成锁定的数字承诺**——无论是护城河话术、对外收益叙事还是融资材料,凡引用单款成本或单位经济结论,都要带上"基于待测假设值、未拿到真实账单前不锁价"这层声明,与 §4.2 那条"对外讲回本要连带声明头号假设"是同一条对外口径纪律。把这条对内的成本待办和对外的承诺纪律挂钩,是为了堵住一个真实的口子:内部档老老实实标了【假设·待测】,对外材料却把同一个数字抄成确定的成本承诺——这种落差一旦被尽调戳穿,伤的是可信度。 + +### 4.4 生成分级即订阅转化漏斗,第一笔收益激活即留存钩子(创始人 2026-06-22 历史回收判定捡回) + +订阅这条收入线的核心产品逻辑,是把"生成能力的分级"直接做成"免费到付费的转化漏斗"。三级生成(L1/L2/L3)对应小白、进阶、专业三类创作者:小白用免费的 L1 体验把游戏做出来,进阶和专业能力(更高的生成级别、更大的额度、premium 品类)放在订阅后解锁。这个梯度本身就是付费墙——复杂能力不打扰小白(他们不需要、也不会因为看到锁而流失),想要更强能力的人自然撞上订阅入口。所以生成分级不只是产品功能的分层,它是订阅收入的转化机制设计:用"生成级别和额度"做付费墙,比单独立一个会员页更顺,因为创作者是在真实创作受限的那一刻遇到升级点的。它和创作者等级体系(Doc A 的 P-INC-02)、会员订阅(P-PAY-02)是同一套逻辑的两端——等级是身份、订阅是权益、生成分级是把两者挂钩的那道闸。 + +与之配套的是"第一笔收益激活路径"这个留存钩子。要把创作者留存从"工具使用"升级成"收益驱动",光让他生成出一个游戏不够,必须有一条显式的产品引导,把他从"生成一个游戏"一路推到"发布、进信息流、拿到第一笔广告收益"。第一笔收益是创作者从"试用一次就走"转成"为了收益留下"的关键拐点——他亲眼看到自己做的东西真的赚到了哪怕几毛钱,留存逻辑就从工具好不好用变成了这里能不能持续赚。这条激活路径要做成明确的 onboarding 设计(和 Doc A 的新人任务 P-INC-01 衔接),而不是把发布和收益当成创作者自己会去摸索的功能。 + +> **战略优先级提醒(对接 012):** 上面这套订阅漏斗的回报、以及任何关于"靠订阅/广告规模化回本"的判断,都依赖每款游戏真实的单位经济数据(见 §6 的 W4 按游戏粒度成本/收益埋点)。在单位经济测准之前,订阅漏斗的转化假设、第一笔收益的金额预期都还是假设值——"先把单位经济测准、再谈规模"这条战略优先级判断的完整论述在[商业定位](../产品/商业定位.md)§4.1,本页只承载它在变现侧的落点。 + --- ## 5. 资金一致性红线(执行时必守) @@ -197,6 +217,18 @@ eCPM 取三档做敏感性扫描:**悲观 15 / 基准 30 / 乐观 60 元/千次* > 这里的 **SAA**(Spring AI Alibaba)是后端进程内的 AI 编排框架,用它的 StateGraph 编排生成流程,无需额外部署独立的编排服务,所以不占新增机器成本。 +**这张 ¥4,300/月 的表算的是"跑 demo 的账",不是"真实经营的账"——真实上线要补一批它漏掉的成本(创始人 2026-06-22 历史回收判定捡回)。** 三向审计早就点名这张表系统性低估了真实经营成本。漏掉的有两类。第一类是**直接漏算的运营开销**,真实经营时都会发生、却没进表: + +- **GPU 算力**——图片/音乐这类素材生成的 GPU 开销。现在 ComfyUI 未部署、零数据,所以表里是空的;一旦素材生成真跑起来,这是真正可能咬人的一项(§3 已点名)。 +- **审核 API**——阿里云内容安全是按调用量收费的,成本随产能线性涨。这张表压根没算它,而[审核台运营](审核台运营.md)§5.2 已明确"放量前要把审核 API 成本单列进成本台账",否则单位经济测算偏乐观。 +- **WAF 高防**——Web 应用防火墙 + DDoS 高防(阿里云/Cloudflare),技术决策版明确写了是"上线前"必须接的安全防护成本,尤其开公网前。 +- **短信验证码**——表里"其他"那 ¥200 含了短信,但只是个占位估值;真切到真实短信渠道、有了限频防护与真实发送量后,要按实际量重核(防短信轰炸的滥用成本另见[变现端到端]资金红线一脉)。 +- **支付通道费**——广告分成提现、内购收单都有第三方通道费率,这部分在表里完全没体现。 + +第二类是**全成本测算 v2 里有意排除、但规模化时要补回的成本**:税费、渠道 T+N 结算账期带来的资金占用成本、对账差与坏账。这三项模型保守起见没纳入是对的,但"它们是被有意排除、规模化与融资测算时要单列补回"这层边界声明不能丢——渠道结算有 T+N 账期会占用现金流,广告分成有对账差和坏账风险,真实经营里都会咬人。少了这句声明,容易让人误以为成本已经算全了。 + +这张表适合讲"种子期跑 demo 要花多少";对外做融资或单位经济测算时,必须把上面这两类成本补进去重算,否则真实上线成本被系统性低估。 + ### 7.3 团队与 Runway MVP 阶段 **5 人核心团队**(2 后端 + 1 前端 + 1 AI/生成 + 1 产品运营),年人力成本约 150-214 万。以种子轮 3000 万计算,**Runway(资金可支撑的时长)为 18-24 个月**。团队的演进路径是: diff --git a/docs/architecture/运营/变现端到端.md b/docs/architecture/运营/变现端到端.md index 6d88bad6..4eed7179 100644 --- a/docs/architecture/运营/变现端到端.md +++ b/docs/architecture/运营/变现端到端.md @@ -252,6 +252,12 @@ flowchart TB | 打款终态 | `game_trade_withdraw` | CAS | 回调/补偿 1→2 或 1→4 | | admin 赋订阅 | `game_trade_subscription_grant` | `uk_biz_no` | `renewByCas` 续期 | +**资金渠道切换要双人复核 + 配置审计(操作红线 · 待落地)。**(创始人 2026-06-22 历史回收判定捡回)上面四条红线管的是代码逻辑——钱在哪个事务、哪个 CAS、哪条边界上动;这一条管的是**人去改配置的那个动作本身**,是流程规矩不是代码规则。变现链上有两个"切真"的开关:广告 provider 从 `MockAdProvider` 切到真实联盟(`CsjAdProvider`/`GdtAdProvider`)、打款 channel 从 `MockPayoutClient` 切到真实微信/支付宝(Nacos `trade.payout-channel` 设为 `wxpay`)。这两个开关一翻,系统就开始动真钱——配置填错的后果是直接的资损:渠道选错或密钥配错,可能让本该 fail-fast 的打款变成"以为切了真渠道、其实在发 mock 假钱",或者把真实联盟的回调对到错的归因上。 + +资金渠道是整条变现链风险最高的开关,绝不能允许单人改一行配置就切真。要钉死两条操作约束:① **双人复核**——切换 provider/payout-channel 的配置变更必须经第二人复核确认后才生效,不允许单人直接改 Nacos/配置中心就上线;② **配置审计**——每一次渠道切换都要留下"谁、什么时候、把哪个开关从什么改成什么"的审计记录,可追溯、可回查。这条和[变现与单位经济](变现与单位经济.md)§4.3"拿到真实账单前不对外锁价"是一类纪律——都是真钱面前的操作护栏,约束的是人的操作而非系统的逻辑。 + +它落地依赖配置变更的管控面,不是改业务码:双人复核挂在配置中心(Nacos)或运维变更流程的审批环节上,配置审计取配置中心自带的变更历史或单独记一条运维操作台账。**待落地**——当前 §8 标"打款执行=mock 桩",这两个切真开关都还没真正翻过,但红线要在切真之前就立好,别等手滑改错配置酿成资损才补。 + --- ## 7. 对账锚点链 diff --git a/docs/architecture/运营/审核台运营.md b/docs/architecture/运营/审核台运营.md index 35fdc8a5..33075e44 100644 --- a/docs/architecture/运营/审核台运营.md +++ b/docs/architecture/运营/审核台运营.md @@ -119,6 +119,18 @@ flowchart TB - review 的处理要扩。今天 `GateVerdict` 只是返回 verdict,没有"转人审后挂起、等人审回来再定"的环节。要补一个**人审挂起态**:聚合裁决为 review 时,不立即放行也不立即拦截,而是**建一条人审工单**(§3.4)、把 project 的发布卡在"待人审"上,人审终裁回来再驱动后续。 - 阿里云调用是外部 API,必须按工程铁律处理超时/失败/重试:阿里云超时或报错时**降级到 review(转人审),绝不降级到 pass**——内容安全的降级口径只能往严格走,放行型降级等于把没审过的内容当审过了放出去。这条和变现侧"打款降级要 fail-fast"是同一个道理:涉及安全和钱的降级,方向永远朝保守。 +### 3.2.1 事中召回:举报率超阈值把已上线内容拎回人审(创始人 2026-06-22 历史回收判定捡回) + +上面那条三段瀑布管的是"内容上架前先审一遍",§3.5 的举报降权管的是"判定违规之后怎么处置"。这两者之间漏了一环:内容已经过审上线、在 feed 里正常跑,但它后来变坏了,或者一开始就擦着边没被机审拦住,玩家开始大量举报——这种情况下没有任何机制把它重新拎回审核。审核台只画了"事前审"和"事后处置"两端,中间"内容在线上由信号触发重审"这一环是空的。补上它,审核闭环才从"只防得住新内容"变成"也防得住上线后才变坏、才被举报的内容"。 + +触发信号取**举报率**,定义为 `report_rate = 举报数 / 曝光数`,是一个负向质量信号——分母用曝光而非绝对举报数,是为了不让高曝光的热门内容仅因为基数大就被误判,也不让冷门内容靠几次举报就轻易翻车。当一条内容的举报率在统计窗口内冲过阈值,系统自动给它建一条人审工单,把它**反向召回**到 §3.4 的人审队列,由人来定它该继续跑、降权还是下架。这条路径和上架前送审方向相反:一个是上线前主动送审拦截,一个是上线后被舆情反向召回;但它们汇入的是同一个人审队列、走同一套审核工单状态机,人审终裁同样是最高权威。 + +它接的是两个已有的点。一头接 feed 的举报埋点——举报本身是 feed/community 侧已有的玩家互动信号,事中召回要做的是把这个信号按曝光归一成举报率、并设一个可配阈值的监测;另一头接 §3.4 的人审队列,召回产出的工单和机审 review 产出的工单同构,只是 `触发原因` 标成"举报率超阈值"、证据里带上当前举报率和窗口内的举报样本。这样事中召回不另起一套人审基础设施,复用审核工单这一条主干。 + +阈值的高低和窗口长短是运营旋钮,要随真实举报分布调:定太低会把正常内容频繁拎回人审、加重人力;定太高则起不到事中拦截的作用,坏内容在被召回前已经伤害了一批玩家。这和快检阈值一样是运营常态、不是一次性调好的参数,落点是锁风档位配置那一类策略配置(§3.7)。 + +**contract-first 清单(待落地)**:① 监测口径——举报率的计算依赖"举报数"和"曝光数"两个量,举报数在 community/feed 的互动埋点里、曝光数在 feed 的出流统计或 telemetry 里,要先确认这两个量能按 `gameId` 聚合取到(若现有埋点不足,需补一个按游戏聚合举报数/曝光数的只读查询,别新建写接缝);② 触发器——新增一个周期扫描的 job(或挂在现有 feed/compliance 的定时任务上),扫超阈值的内容、调 §3.4 的建工单入口,工单 `触发原因` 枚举加一个"举报率超阈值"值;③ 阈值配置——`report_rate` 阈值和统计窗口作为可配项落 admin 策略配置(复用 §3.7 锁风档位配置页那套策略表,不单建一张表),权限位沿用 `compliance:lock-policy:config`;④ 幂等——同一条内容在一个窗口内只召回一次,别让它每轮扫描都重复建工单(以 `gameId + 窗口` 为幂等键)。这一环放在第一期人审队列建成之后接,因为它依赖人审工单这条主干先在。 + ### 3.3 锁风三档与 IP 库怎么绑 锁风门(Gate)裁决的是"这条内容的风格/版权/内容安全过不过",而**锁风三档**调的是"用多严的力度去裁"。同一条内容,标准档可能放行、严格档可能转人审、人工复核档直接送人。这三档不是写死的,是个**按内容的 IP 归属和类型动态选出来的策略**。 @@ -308,8 +320,9 @@ flowchart TB - 审核工单台账 + 轻量状态机 + admin 审核队列/详情/处置页。把"机审 review → 建工单 → 人审认领裁决 → 回写驱动"主干打通。 - 违规处置联动:下架走 feed 现有的 `FeedApi.offlineRank`(现成);封禁联动补两块断链——封账号时置 `game_player.status=DISABLE`(让 `validateCreator` 拦得住)+ 按 creatorId 批量下架其全部已发布内容。**feed 自动降权与创作者信用模型也放第一期(创始人 2026-06-22 定)**:新建 feed 降权 `-api` 让 compliance 自动降权、建简单信用扣分台账(只记不连带),两者都 contract-first 补新跨模块写入口 / 新表(见 §3.5)。 - 锁风三档用过渡的 `lock_strength_policy` 配置表起步(admin 可配),先按题材黑名单 + 手配 IP 映射选档。 +- 事中召回(§3.2.1,创始人 2026-06-22 历史回收判定捡回)接在人审队列建成之后:把举报率按曝光归一成负向信号、设可配阈值,超阈值的已上线内容自动建工单反向召回到人审队列。复用审核工单主干,不另起人审基础设施。 -这一期做完,自有端邀请制内测就有了一套能日常运转的内容安全运营——机审挡大面、人审兜疑难、违规真下架真拦创作。 +这一期做完,自有端邀请制内测就有了一套能日常运转的内容安全运营——机审挡大面、人审兜疑难、违规真下架真拦创作,且上线后变坏/被举报的内容也能被举报率信号拎回重审。 **第二期 · 阿里云兜底接入(放量前的合规刚需)。** 依赖"接真实公开流量"这个时点(渠道线③临近):把第一期留的阿里云接缝接通,灰带样本真送阿里云、按工程铁律处理超时/失败/降级(降级朝 review 走)。同时补内容溯源——AIGC 显式标识在各发行面带上,审核记录留存机制成文(喂合规闸门 #8 材料)。 diff --git a/docs/architecture/运营/渠道发行.md b/docs/architecture/运营/渠道发行.md index 8bb0df92..666e8bb2 100644 --- a/docs/architecture/运营/渠道发行.md +++ b/docs/architecture/运营/渠道发行.md @@ -144,6 +144,10 @@ flowchart LR 广告这条线,接口是 `showRewarded(slotId)`(展示一支激励视频广告,`slotId` 是广告位逻辑标识),它会映射到平台原生的 `wx/tt.createRewardedVideoAd`,把逻辑广告位 `slotId` 翻译成平台的 `adUnitId`;此外增补 `showBanner / hideBanner` 管理横幅广告。这里有一条不容造假的红线:**`rewarded=true`(用户完整看完广告应得奖励)只认平台返回的"完整观看"回调**;如果走兜底发奖,必须标记 `reward_fallback=true`,绝不能把兜底奖励伪装成真实广告收益。 +还有一条运行时体验红线,和上面计费侧的口径是两码事:**广告在玩家端加载失败时,必须跳过广告、让游戏继续,绝不能因为广告问题把游戏卡死**(创始人 2026-06-22 历史回收判定捡回)。[变现端到端](变现端到端.md)§2.1 讲的是**后端计费侧**的降级口径——广告联盟没注册时降级到 mock 可接受,代价只是少算些收入;这条讲的是**玩家正在玩的运行时侧**——广告 SDK 拉不出来(`load-fail`)、超时(`timeout`)、无填充(`no-fill`)是常态而非异常,SDK 适配层遇到这些必须静默吞掉、把控制权还给游戏循环,玩家该玩玩、该结算的奖励按兜底发(`reward_fallback=true` 计入),绝不能让一支拉不出来的广告把整局游戏阻塞在等待态。对一个靠广告吃饭的 IAA 平台,广告偶发失败把游戏卡死,对留存的伤害远比少算一笔收入严重——广告体验直接是留存生命线。这条红线跨在变现与前端运行时的交界上,两侧各以为对方会守、结果都漏了,所以在渠道线的广告接口这里钉死:`showRewarded` / `showBanner` 的实现契约里,所有加载失败路径都不得向上抛出阻断游戏的异常。 + +这条红线和 §8.1 P1 真机门里的 **G4 广告五路径**(success / close-before-complete / load-fail / timeout / no-fill)是同一件事的验收面——G4 要求 `load-fail`/`timeout`/`no-fill` 三种失败情况都被正确处理,而"正确处理"的判据正是这里定的"跳过广告、游戏继续",不是把失败当致命错误。 + 遥测(telemetry,即埋点数据采集)方面,渠道专属字段作为 **9g 转正候选** 补入——与上面 §5.1 的 9c 同属"渠道线转正后才落库"的命名,现行遥测事件仍是契约 **#5**(`events.schema.json`,这些渠道字段尚未并入)。要补的字段是:`channel`、`channelAppId`、`adUnitId`、`logicalSlotId`、`packageVersion`、`configHash`、`requestId`、`ad_event_type`、`platform_callback`、`settlement_batch`。性能监测的"七锚点"在渠道版里展开为一串时序埋点:`t_launch → t_runner_boot → t_canvas_ready → t_sdk_ready → t_config_loaded → t_first_paint → t_input_bound → t_game_start`,用来精确度量从启动到游戏可玩的每一段耗时。 ---