zizi cc71dbbaf5 docs(tier2): 扩展五族细图——A 运行时×4 / F 源项目契约×3 / G spike runbook×5 / B 控制管理面×4 / H 观测成本×3 + 五族图说

19 张新图经 draw→对抗验证→族汇编 workflow(43 个 opus 子代理)产出,每张是总览(agentic运行时架构图说.md 图1-8)的逐项放大(deepen 不 duplicate):
- A: Agent Service+session三路 / Agent非常驻+AgentState / Workspace双轴 / Middleware洋葱
- F: 源项目契约七要素 / 第二装载分支 / finish共用schema
- G: 建设五步+spike门 / mini-肥鹅靶子 / 模型矩阵+跑序 / 过门阈值+采集字段 / 两段+退路树
- B: 控制面四组件 / 反锁死五协议 / 预算三层强制 / 管理面三phase
- H: trace统一契约 / 观测管道 / 成本台账

对抗验证逮修真问题:F3 落库/取回画成现行→改虚线待建、G2 56%张冠李戴、B1 tier2箭头几何错位、B2 伪造「伸缩」徽章删、H1 门裁九门/三层校验错配。主会话复验补逮 6 张脚注半角冒号(verify 脚本盲区)。
全 32 张复验 界内/良构/脚注/ok;5 族图说带防漂移 hash + 人读散文(零 AI 味)。8 族接进看图入口。tier2 全集=32 图+8 族图说。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-23 10:36:57 +00:00

15 KiB

Raw Blame History

date, topic, status, 映射源档

date topic status 映射源档

2026-06-23

tier2 细节图说 · F 族——源项目契约与第二装载分支(生成引擎子树·tier2)

设计中(tier2 待 spike) · 每图映射源档见该图脚注 / frontmatter 记 hash 作防漂移门

path	hash
docs/architecture/架构/生成引擎/tier2实现详设.md	`d5efe45f`

path	hash
docs/architecture/架构/生成引擎/agentic运行时架构图说.md	`32adda95`

tier2 细节图说 · F 族 —— 源项目契约与第二装载分支

本篇是绘境AI 架构图集 生成引擎子树 下的 tier2 细节图说,只覆盖 F 族(源项目契约与装载) 三张图。生成引擎主干、tier2 总览、agentic 运行时各有自己的图说;这里专门把「tier2 那个真 Phaser 工程怎么定义、怎么进浏览器、怎么和 agent 收尾接线对齐」这件事画清楚。

0 阅读约定与同步纪律

F 族讲的是 tier2 富游戏自治生成线在"产物形态"这一面要补的工程地基——给真 Phaser 引擎工程新写的一套源项目契约(钉七样、分四组),这套工程怎么经第二条装载路进浏览器,以及 agent 自治跑完时收尾的 finish 工具为什么要和这套契约共用同一份 schema。三张图共映射两份属主设计档:契约的七要素四组、命名边界、finish 共用 schema 这三段口径全部出自《tier2 实现详设》开头的「第一批工程定义:源项目契约」;第二装载分支与现行 ECS-lite 装载的对照、以及"放大图 7"这层关系出自《agentic 运行时架构图说》的图 7「产物与契约」。frontmatter 记了这两份的当前 commit hash 作防漂移门——任一份动了产物形态或契约口径,本图说与对应 SVG 必须同步改。

整条 tier2 富游戏线现在 整体待建:0号 spike 还没跑,引擎没搭,这套源项目契约一行代码没落。所以 F 族里几乎所有元素都是设计已出、尚未落地的状态(状态码"建"),绝不能因为图画得齐整就误以为契约已经写好。三张图里唯一是现行已落的对照锚,是 Tier0/1 廉价线那条 ECS-lite 数据壳装载路——它在生产上跑着(Runner v2 P1/P2 实证),用实线画;tier2 要新写的第二装载分支、源项目契约、finish 工具,全用虚线画。看图时记住这条对照:实线 = 现行已落(ECS-lite 装载、MySQL 底座、bootGameHost 沙箱这条已验过的装载范式);虚线 = tier2 专属、待 0号 spike 验证后才落代码的新机制。 紫色徽标和紫色卡片底色统一表示"待建"。

本族是《agentic 运行时架构图说》图 7 的放大层。图 7 把 tier2 源项目契约画成一条扁平的五要素链(类型标记 → 文件树 manifest 加入口 → 构建 profile 加依赖锁 → 内容哈希 → 落库寻址),只到"有这几样"的粒度;F 族把这条链逐项展开成七要素四组,补上第二装载分支的完整步序,再补上图 7 没画的 finish 共用 schema 防漂移机制。是 deepen,不是 duplicate——同一套设计,图 7 给总览扁平链,F 族给逐项施工图。

1 全图通用图例

F 族用一套统一的徽章和线型,先在这里讲清,后面每张图不再重复。

状态徽章标的是某件东西落在生命周期的哪个阶段:紫色待建 = 此件尚未落代码,是 tier2 立项要补的新机制;绿色现 = 现行已建在跑(只有 ECS-lite 那条对照锚带它);灰色数据 = 这一要素沿用现行 GamePackage 那套"存进 MySQL 加对象存储、带 sha256 落库取回"的数据范式,不是凭空新造存取面。少数图上还点到几个生产维度徽章:可靠(绿,指 sha256 / 内容哈希这类完整性校验)、伸缩·并存(紫,指两条装载路解耦并存可各自演进)。

线型承担状态语义。实线框 = 现行已落(只有 ECS-lite 装载路与 MySQL 底座);虚线框(短划线 stroke-dasharray 6 4)= tier2 专属待建机制(源项目契约、esbuild 构建、第二装载路、finish 工具)。实线箭头 = 现行已有的流程或关系,虚线箭头 = tier2 待建的流程或映射。红线(红框)是不许碰的硬边界:tier2 的契约与装载路绝不回归 Tier0/1 在产线跑着的那套。

状态码四个,贯穿生成引擎子树:现 = 现行已建在跑;接 = 设计已出、代码待接线;建 = tier2 立项后要新建、当前待 spike;缓 = 收窄后缓做。future 用远期紫表示更长期、当前不排的项;F 族里没有用到 future 项,全族集中在"现"(ECS-lite 对照锚)与"建"(tier2 七要素 / 第二装载 / finish)两档。

2 图集

图 F1 · 源项目契约七要素四组

tier2 立项要补的第一件工程,是给真 Phaser 引擎工程新写一套源项目契约。这张图把这套契约要钉死的七样东西按职责分成四组铺开,关键是让人看清:这七样不是随手列的字段清单,而是覆盖了一个真工程从"是什么"到"怎么构建出来、怎么存回来"的完整链条,缺一样这条链就断在某处。

先要弄明白为什么非得新写一套契约。现行 Tier0/1 廉价线上,一款游戏就是库里一条 GamePackage——代码打成 engineBundle 内嵌在 manifest JSON 里(整包带 sha256),feed 下发后挂上 window.__GameBundle、由 bootGameHost 在沙箱 canvas 里跑起来,每帧回调 update / render。tier2 的产物也走"存进库、按需取来跑"这条路,但形态根本不同:它不是声明式数据壳加固定运行时,而是一个真 Phaser 工程——多个源文件、一份构建脚本、一套依赖,要先 esbuild 构建出 bundle 才能玩。形态不同,认它的契约就必须另写。

四组七要素是这样落的。第一组身份只有一样——源项目类型标记,它的作用是让装载侧一眼分得清这是 ECS-lite 数据壳还是 tier2 引擎工程、走对应的装载分支,是两条装载路分流的第一道闸(F2 整张图就建在这道闸上)。第二组工程骨架两样:文件树 manifest 记下有哪些文件、各自什么角色(入口、场景、资产、配置),入口文件标出 build 从哪个文件起手——装载和寻址都按它们走,入口文件还是整条构建链的源头锚点。第三组构建可复现两样,要保证同一款游戏永远构得出来:构建 profile 固定这一款用什么命令、什么 esbuild 配置打包,把构建步骤随款冻结不漂;依赖锁钉死引擎和插件的版本,免得上游一升级历史游戏就构建不出来——这一条直接服务于"游戏是长生命周期项目"这个产品基座,一款两年前生成的游戏今天还得能原样构建出来。第四组落库取回两样:内容哈希给整个工程算一个指纹,既做缓存命中(同指纹直接跳过重建)又做完整性校验;落库与寻址 API 定义工程怎么存进 MySQL 加对象存储、怎么按 id 取回来重建。落库取回这一组带"数据"徽标,因为它沿用的正是现行 GamePackage 那套落库取回的数据范式,不是另起炉灶。

这张图最该让人记住的是底部那条红线:这套契约绝不碰 Tier0/1 在产线跑着的 ECS-lite 装载契约。命名上有个真实的撞名坑——仓里已经有一份 contracts/agent-loop/source-project.schema.json,名字也叫"源项目",但那是 Tier0/1 那条 ECS-lite 数据壳的契约。tier2 这套必须另立一份独立 schema、编为契约组新一类(additive),绝不能图省事扩在那份现有同名 schema 上——共用一份会把本该解耦的两条线又焊一起,改 tier2 时还可能污染在产线跑着的廉价线。两条装载路解耦并存,tier2 这边怎么改都不许回归现有产线。图中段还点出一处与 finish 工具的对齐建议(完整道理见 F3):finish 工具的参数 schema 应当和这套契约共用同一份定义,因为 agent 调 finish 交付的形状就该是落库取回时认的那个形状。

图 F2 · 第二装载分支

游戏怎么进浏览器,在 tier2 立项后变成了两条路而不是一条。这张图把两条"存进库、按需取来跑"的装载路并排画出来,左支是现行 ECS-lite 数据壳(实线、已落在生产),右支是 tier2 真 Phaser 工程的第二装载分支(虚线、待建),顶上一个分流框由源项目类型标记决定走哪条。读这张图的正确方式是盯住两支的差异点——它们前半段(存进库、按需取回)是同一个范式,真正分岔在"取回之后要不要先构建"。

左支是现行装载路,五步连成一条已经验过的流水线。第一步存库:代码打成 bundle 文本,作 GamePackage 的 additive 字段嵌进 DB-manifest(出于 CSP 不放外域),整包带 sha256。第二步取回:玩家在 feed 点开某款,后端把这份 manifest 下发到浏览器。第三步挂载:iframe 内联 script 取出 engineBundle 挂到 window.__GameBundle,不引外域。第四步启动:bootGameHost 在沙箱 canvas 上跑,这是通用宿主泛化装载、一套固定运行时,引擎掌帧、受控面经 ctx.getEngine 注入。第五步跑:引擎是唯一掌帧源、绘制面唯一是引擎 mainContext,每帧回调游戏 update / render,游戏不自起 RAF。这条路的特征是"不构建、即取即跑"——bundle 本身就是产物,而且固定运行时一套、所有数据壳共用。它是 Tier0/1 廉价线在生产上跑着的装载契约,Runner v2 P1/P2 已实证。

右支是 tier2 要补的第二装载分支,前半段一样"存进库、按需取回",但形态不同导致中间多出一段现行根本没有的步骤。tier2 入库的不是一个 bundle,而是一个真 Phaser 工程——多源文件加构建脚本加依赖锁,是个可维护的源项目,改源不改包、重新构建。取回这个源工程之后,必须先按构建 profile 用 esbuild 打包,产出可玩 bundle,然后才轮到落库取回走自己那套寻址 API、在沙箱里跑构建产物。这里有一处明确的设计取舍:右支的固定运行时不复用左支那套——两条装载路不通用、解耦并存,正是为了让它们各自演进时互不牵连(底部"伸缩·并存"徽章标的就是这一点)。右支中段嵌着 F1 那七要素四组,因为这条装载路的每一步都靠那套契约支撑:分流靠类型标记、取回寻址靠落库 API、构建靠 profile 加依赖锁、缓存与完整性靠内容哈希。

两条路对照成一句话就是图底那条带:现行是 bundle 即产物、即取即跑、固定运行时、一款一条 GamePackage、sha256 整包校验;tier2 是源工程入库、取回须先 esbuild 构建、独立源项目契约寻址、内容哈希做缓存与完整性。这张图同样压着 F1 那条红线——tier2 的第二装载分支绝不碰左支那条在产线跑着的 ECS-lite 装载路,tier2 怎么改都不许回归现有产线。

图 F3 · finish 工具 ↔ 源项目契约共用 schema

这张图讲的是一处从一开始就要对齐、不然日后必漂的源头设计:agent 调 finish 交付的形状,和落库取回时认的那个形状,必须是同一份 schema。整图待建(虚线),核心约定框居中放大画的就是这个等式——finish 工具的参数 schema 与 F1 那套源项目契约共用同一份定义,而不是各写一份靠人盯着保持一致。

要看懂这处设计,得先弄清 finish 工具是什么。tier2 的 agent 是单写的自治体,在 AgentScope 里以 ReAct 多轮自治运行(reasoning → action → observation 循环,这是 ReAct 的标准范式),过三层校验收敛到产出。它自治跑完那一刻,经一个 finish 工具——AgentScope 里以 Tool 工具函数为载体的收尾接线——把这份结构化游戏定义吐出来。这份结构化游戏定义就是 F1 说的那个真 Phaser 工程:多源文件加构建脚本加依赖,不是声明式数据壳。所以问题来了:agent 经 finish 交付的形状,和落库取回时按 F1 契约认的形状,本来是两个角色在两处定义的东西。

为什么非共用一份不可,红框那条警示讲得最直白:两边各写各的迟早对不上——改了契约忘改工具,或者反过来改了工具忘改契约,一旦错位,agent 交付的形状落不进库、取回时认不出。共用一份从源头消除这种漂移:契约即工具签名,改一处就是两处一起改,根本不存在"两份 schema 不一致"这个失败面。这不是为优雅而优雅,是把一类必然会发生的接缝错位提前焊死。

图下半部分把这件事铺成一条横向链路,让人看清共用 schema 在整条交付链里卡在哪:agent ReAct 收敛 → 调 finish 工具(参数就是源项目契约形状)→ 吐出结构化游戏定义(真 Phaser 工程)→ 按 F1 落库 API 存进 MySQL 加 OSS(内容哈希做完整性)→ 下次按 id 取回重建,认的就是 finish 交付的那个形状。链路末端的"取回重建"和起点的"finish 交付"认的是同一份形状,这条链才闭得上。最底下那条带把 F1 七要素四组逐项重列一遍,点明 finish 的参数 schema 与之共用的就是这一份定义——身份(类型标记)、工程骨架(文件树 manifest 加入口文件)、构建可复现(构建 profile 加依赖锁)、落库取回(内容哈希加落库寻址 API),七样一字不差地既是契约也是 finish 的签名。

3 图清单与状态表

#	图名	形式	状态	覆盖内容
F1	源项目契约七要素四组	SVG · 四组卡片网格	建(tier2 待建 · 契约组新一类 additive)	身份(① 类型标记)/ 工程骨架(② 文件树 manifest、③ 入口文件)/ 构建可复现(④ 构建 profile、⑤ 依赖锁)/ 落库取回(⑥ 内容哈希、⑦ 落库寻址 API);现行 GamePackage 装载对照锚;红线=另立独立 schema 不撞 source-project.schema.json、绝不碰 ECS-lite 产线契约;finish 共用建议
F2	第二装载分支	SVG · 双支对照流水	现(ECS-lite 装载已落)/ 建(tier2 Phaser 第二装载分支待建)	类型标记分流;左支现行五步(存库 engineBundle 内嵌 manifest → feed 下发 → 挂 window.__GameBundle → bootGameHost 启动 → 每帧 update/render);右支 tier2 工程形态加 esbuild 构建步加独立寻址;两条路解耦并存红线;两路对照一句话
F3	finish 工具 ↔ 契约共用 schema	SVG · 等式 + 横向链路 + 七要素条带	建(finish 与契约共用一份 schema · tier2 待 spike)	核心等式(finish 参数 schema = 源项目契约定义);为什么共用(从源头杜绝交付↔落库漂移);横向链路(agent ReAct 收敛 → finish 交付 → 落库 → 下次取回重建);F1 七要素四组逐项条带

放大《agentic 运行时架构图说》图 7「产物与契约」:图 7 给 tier2 源项目契约一条扁平五要素链(类型标记 / 文件树 manifest 加入口 / 构建 profile 加依赖锁 / 内容哈希 / 落库寻址),本族逐项展开为七要素四组(F1),补全第二装载分支完整步序与现行 ECS-lite 装载对照(F2),再补 finish 工具与契约共用 schema 的防漂移机制及交付→落库→取回链路(F3)——deepen 不 duplicate。设计变动须同步本图说与对应 SVG。

15 KiB Raw Blame History