diff --git a/docs/architecture/架构/生成引擎/agentic运行时架构图说.md b/docs/architecture/架构/生成引擎/agentic运行时架构图说.md index f495cb6e..651433c5 100644 --- a/docs/architecture/架构/生成引擎/agentic运行时架构图说.md +++ b/docs/architecture/架构/生成引擎/agentic运行时架构图说.md @@ -11,6 +11,10 @@ - **映射设计档**：本图说只把《[自治富游戏引擎](自治富游戏引擎.md)》《[tier2 四层工程架构](tier2四层工程架构.md)》《[tier2 实现详设](tier2实现详设.md)》《[agentic 集成架构](agentic集成架构.md)》画出来。机制以 **agentscope 2.0.3 源码实证**为准（`/root/oss/agentscope`，逐条核过）。 - **同步纪律**：设计一变动，本图说与对应 svg 必须同步更新（已并入 wave 收口清单）。 - **产物**：svg 入仓（GitHub/编辑器渲染矢量），png 在 mini-desktop 转。 +- **细节族图说（本图说之下的放大层）**：本篇是整轨的「看图入口」（9 张总览图）；要看某一面的逐项细节，下钻这几份按族拆的细节图说（核心三族已建，A/B/F/G/H 族后续补）： + - [C 族 · 单写 ReAct 循环](tier2细节图说-C-单写ReAct循环.md)——ReAct 一轮 / 多轮自治、M3 Anthropic 原生接法、四道熔断 + 预算闸、承 amodel-gen 范式。 + - [D 族 · 三层校验与九门](tier2细节图说-D-三层校验与九门.md)——三层校验全景、九门逐门、富游戏专属门、advisory 分级 + Goodhart 隔离、CDP 探针 Phaser 重写。 + - [E 族 · 能力面（skills 与 prompt）](tier2细节图说-E-能力面skills与prompt.md)——toolkit 九工具、引擎能力包五件套、prompt 两阶段角色、A-model 4 插件复用。 ## 1. 全图通用图例 diff --git a/docs/architecture/架构/生成引擎/assets/t2-C-01-单写ReAct循环.svg b/docs/architecture/架构/生成引擎/assets/t2-C-01-单写ReAct循环.svg new file mode 100644 index 00000000..7eeb4f78 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-C-01-单写ReAct循环.svg @@ -0,0 +1,184 @@ + + + + + + + + + + + + + + + + + + 图 C1 · 单写 ReAct 循环（族 C） + 一个单写者 ReAct agent 在三层校验门内自治造富游戏：想一步 → 调一个工具 → 看结果 → 再想。tier2 演进自 WG1 studio.py，待 0号 spike 验证。 + + + + 整图状态 = 建（tier2 整轨待 0号 spike 验证、尚未落代码）。 + 实线 = 承袭现行已落（九门 harness · A-model driven 感知）；虚线（stroke-dasharray 6 4）= tier2 专属新机制，待建；红线 = 四道熔断。 + + + 质量 + 可靠 + 成本 + 可观测 + + + + 对比：WG1 廉价线 vs tier2 + tier2 复用 studio.py 的多角色 prompt 与 + 生成域躯干，但把多轮自治从外层搬进内部。 + + + + WG1 廉价线（现行 · L1 生产主线） + ReActConfig(max_iters=1) 单轮调用 + + 外层 for attempt in range(max_repairs) + 的 repair 重试循环 + + + 单轮调用：生成一次 + + + + 外层喂错 → 重跑（repair） + + + + + 为压便宜档单价：L1 生产主线 + 明确不引 AgentScope（框架 token 膨胀） + + + + tier2 富游戏线（待建 · fork 起步） + max_iters 放开（2.0.3 默认 20） + 把多轮自治从外层 repair 循环 + 搬进 Agent 内部 ReAct 循环 + + + Agent 内 ReAct：reason→act + + + + observe→再 reason（多轮） + + + + 无状态 Agent（统一 Agent 类） + reasoning-acting 循环内建驱动 + 独立锁 AgentScope 2.0.3 · 独立演进 + + + ReAct 一轮（想一步 · 调一个工具 · 看结果） + + + + reason + 想下一步 + + + act + 调一个工具 + + + observe + 看结果 + + + + + act + 每轮观测后回 reason，不是一次把答案写完 + 回 reason + + + + + 自治内循环 · 关在一圈验收门内迭代（三层校验：L1 硬约束焊死） + + + + + 读文档 / 资产 + 引擎文档 · 资产池 + + + 写源文件 + 填数据表 · 写表现层 + + + build + esbuild 构建 + + + headless 快检 + 无头预筛 + + + + + + + + 九门（L1）· 真浏览器真玩 + 确定性判定 · 绝不让 LLM 自评（承袭现行 · 实线） + + + + + + 读 verdict + 过 / 未过 + + + + + 改 + 据 verdict 改源 + + + 未过 + + 回到写源 + + + + 过 → finish + 产出富游戏（真 Phaser 源工程） + 12 文件级多系统 · 改源不改包 + 质量 + + 过 → 跳出内循环 + + + + 四道熔断 · 任一触发即停 + ① 步数硬顶（每系统构建-修复步数） + ② 预算闸（网关 · 现非强制硬闸） + ③ 卡死探测（语义层） + ④ 双层超时 + 收敛步数 ≤ max_iters：单系统 ≤ 8 轮、 + 整局 ≤ 40 轮；超 max_iters 即判不收敛。 + + + 任一触发即停 + + + + 铁律 · 单写者：只一个 agent 持整个工程的全局视图，不并行拆给多 agent + 经营游戏多系统共享同一套状态与约定，拆并行几乎必不一致。一手教训：曾把「造 Flappy Bird」拆给并行子 agent，背景跑成了马里奥。 + 「单写者」专指阶段 2 写代码环节（阶段 1 工作室设计仍用 Agent Team 星形多 agent 发散）；旁配只读探路 agent + 一道独立评审。 + + 映射：自治富游戏引擎.md §「谁在写：单写者 ReAct + 四道熔断」 · tier2实现详设.md §「运行时形态」第二阶段 + §「建设五步」第一步 ｜ 状态：建（tier2 待建，演进自 WG1 studio.py）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-C-02-M3原生接法.svg b/docs/architecture/架构/生成引擎/assets/t2-C-02-M3原生接法.svg new file mode 100644 index 00000000..47a25f75 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-C-02-M3原生接法.svg @@ -0,0 +1,111 @@ + + + + + + + + + 图 C2 · M3 Anthropic 原生接法（族 C） + tier2 中等 agentic 档 MiniMax-M3 怎么接：官方 AnthropicChatModel → new-api 的 /v1/messages → 原生 thinking 分离 + agentic 工具循环。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；接法本身（官方 AnthropicChatModel，AgentScope 2.0.3 源码已核）可信。 + 实线 = 现行已落（new-api 计费平面 / NEWAPI_KEY 出口）；虚线（stroke-dasharray 6 4）= tier2 专属待建机制（M3 原生接法、thinking 分离、工具循环）。 + + + + + tier2 agent + 待建 + 单写 ReAct agent + （AgentScope 2.0.3） + + + + AnthropicChatModel + 待建 + AgentScope 2.0.3 官方模型类 + 构造不传 formatter → 自动配对 + AnthropicChatFormatter + + + + AnthropicCredential + 待建 + .base_url + → new-api 的 Anthropic 端点 + （/v1/messages） + + + + MiniMax-M3 + 中等 agentic 档 + 这批最能打 + 先用它证路 + + + + + + + + + 生产维度 + 成本 + 统一从 new-api 出口 + 计费，单一计费平面 + + + 「用对 M3」三个要点 + + + + ① 走 Anthropic 原生协议 + 工具循环 + 原生 Anthropic 协议（/v1/messages） + + agentic 工具循环（ReAct 多轮） + 不是 OpenAI 式单次 JSON 填空： + agent 调工具 写源 / build / 跑门 / 读 verdict / 改， + 在循环里自治多轮收敛。 + + + + ② thinking 分离 + thinking_enable / thinking_budget + 硬约束：max_tokens ＞ thinking_budget + budget 缺省取 max_tokens 的一半。 + 若 budget ≥ max_tokens：2.0.3 自动把 + max_tokens 抬到 budget+1024 — 别依赖兜底，显式设对。 + + + + ③ 完整 response / 历史保留 + 每轮把完整 response 回传入历史 + thinking / text / tool_use 所有块都保留， + 不剥、不丢、不只抠 JSON。 + 这样 Interleaved Thinking 才不失效， + M3 才发挥得出最佳 agentic 性能。 + + + + 红线 · 旧用法是 60% 失败的最深根因（用法错，不是模型天花板） + 错用法 = 关 thinking ＋ 单次 JSON 填空 ＋ 救场从头重生成。 + 把 agentic + 交错思维的 M3 当一次性填空机用、剥掉 thinking、历史不留、失败就从头重来 — 三连违反官方铁律，是 60% 失败最深主因（非模型天花板）。 + 另一处误读：max_tokens 是「输出上限」、不是 512K 的上下文窗 — 输出可抬到 ＜128K 给 thinking ＋ 答案，输入窗 512K 不受它限。 + + + + 模型统一从 new-api 出口走 · 协议 / SDK 不锁死 · all roads 收口到一个计费平面 + 出口 = new-api（baseUrl ＋ NEWAPI_KEY，凭据见 docs/内网凭据与端点.md）；协议 / SDK 不锁死，每档走它各自最优端点。 + M3 这档之所以走 Anthropic 原生端点，是因为「用对它」要的就是原生 thinking ＋ agentic 工具循环；便宜档（deepseek-v4-flash / v4-pro）照旧各自端点。 + 不论走哪条端点，计量都收口到 new-api 的 quota 口径（per-model 折¥）— 一个计费平面，成本可对账。 + + + 映射：docs/architecture/架构/生成引擎/tier2实现详设.md §模型矩阵与样本量（M3 行接法说明）· 项目记忆 m3-agentic-anthropic-protocol（Anthropic 原生 thinking ＋ 工具循环）｜ 状态：建（M3 接法走官方 AnthropicChatModel，AgentScope 2.0.3 已核）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-C-03-四道熔断.svg b/docs/architecture/架构/生成引擎/assets/t2-C-03-四道熔断.svg new file mode 100644 index 00000000..beeac9e9 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-C-03-四道熔断.svg @@ -0,0 +1,84 @@ + + + + + + 图 C3 · 四道熔断 ＋ 预算闸（族 C） + agent 在三层校验门内可任意迭代，但被四道熔断关着，任一道先触发即停。官方软刹现成、自建硬熔断待落。 + + + + 整图状态 = 建：tier2 待 0 号 spike 验证、尚未落代码。实线 = 现行已落或官方现成；虚线（stroke-dasharray）= tier2 待建。 + 预算闸用官方 ReplyBudgetControlMiddleware（现成软刹，画实线）；三道硬熔断 ＋ 强制硬闸为 tier2 自建（待落，画虚线）。spike 阶段可先只挂官方软刹。 + + + + 单写者 ReAct agent 在三层校验门（L1/L2/L3）内反复迭代造富游戏；四道熔断是关住自治多轮的笼子，任一道先触发即停止本局生成。 + 四道 = ① 步数硬顶 · ② 预算闸 · ③ 卡死探测 · ④ 双层超时。中心赌注未证，必须靠熔断防它在 56% 表现层上烧钱发散。 + + + + + ① 步数硬顶 · 防靠运气擦边 + 每系统 build-修复步数上限；整局 ≤ max_iters + 建议★ 单系统 ≤ 8 轮、整局 ≤ 40 轮；超 max_iters 即判不收敛 + 走 AgentScope ReActConfig.max_iters（2.0.3 默认 20，tier2 放开） + 防模型靠多轮反复试错把门擦边混过，而非真收敛 + 可靠 + 成本 + 建·待落 + + + + ② 预算闸 · 官方软刹 + 官方 ReplyBudgetControlMiddleware，按预算优雅收尾 + 在 on_reasoning / on_reply 钩子里收尾——是软刹，不强杀 + 现成中间件（实线）；但现还只是 best-effort、非强制硬闸 + 规模化前必须落地强制硬闸（见下方警示带） + 成本 + 官方现成 + best-effort 非硬闸 + + + + + ③ 卡死探测 · 语义层 + 检测 agent 原地打转、无实质进展 + 语义层判定（非单纯计步），防它换汤不换药空转 + 第二段还要防它改 driver 逃避卡死探测（Goodhart） + 自建：做成 MiddlewareBase 子类，挂进中间件洋葱 + 可靠 + 成本 + 建·待落 + + + + ④ 双层超时 + 两层墙钟上限：单步超时 ＋ 整局超时 + 单步钉死一次工具调用 / 一轮推理，整局钉死本局总时长 + 兜住单步挂起与整局拖死两种失控 + 自建：做成 MiddlewareBase 子类，挂进中间件洋葱 + 可靠 + 成本 + 建·待落 + + + + 机制：官方软刹 ＋ 自建硬熔断叠在中间件洋葱里 + 官方 ReplyBudgetControlMiddleware（预算软刹，现成）＋ 自建硬熔断（超时 / 卡死 / 硬杀，各做成 MiddlewareBase 子类）一层层套进 ReAct 循环。 + 任一道熔断先触发即停本局：软刹优雅收尾、硬熔断强制截断。spike 阶段先只挂官方软刹，三道硬熔断到建设期补全。 + + + + 警示 · 预算闸现还不是强制硬闸（待建） + 官方软刹只在钩子里按预算优雅收尾，是 best-effort，不强制截断；自治多轮一旦不强制，会在 56% 表现层上烧钱发散。 + 强制硬闸的完整口径归《agentic 集成架构》那份；规模化（premium 量起来）前必须落地，否则成本不可控。 + + spike 阶段退路：可先只挂官方 ReplyBudgetControlMiddleware 软刹跑通验证，强制硬闸 ＋ 三道自建硬熔断到建设期再补——不阻塞 spike。 + + 映射：自治富游戏引擎.md §「谁在写：单写者 ReAct ＋ 四道熔断」（K 节点）· tier2实现详设.md §「建设五步」第三步成本强制 ＋ §「前置物清单」 ｜ 状态：建（软刹官方现成 / 硬熔断 ＋ 强制硬闸自建待落、现 best-effort）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-C-04-多轮范式承amodel.svg b/docs/architecture/架构/生成引擎/assets/t2-C-04-多轮范式承amodel.svg new file mode 100644 index 00000000..038db4b2 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-C-04-多轮范式承amodel.svg @@ -0,0 +1,110 @@ + + + + + + + + + + + + 图 C4 · 多轮自治范式（承 amodel-gen） + 从「单轮 + 外层 repair」演进到「Agent 内多轮 ReAct」——tier2 复用 amodel-gen 三件范式，是 fork 演进、不是返工。 + + + + 整图状态 = 建（范式承 A-model 已落 / tier2 fork 演进、待 0号 spike）。 + 实线 = 现行已落（wg1 studio.py 单轮 + repair · amodel-gen 多轮 JS harness，均 working reference）；虚线 = tier2 专属、待建（Python·AgentScope 2.0.3 多轮自治造 Phaser 富游戏）。 + 质量 + + + 三态演进带（左 → 右） + + + + ① wg1 / studio.py + 现行已落（实线） + LittleJS 廉价线 · Python 种子 + ReActConfig(max_iters=1) 单轮调用 + + 外层 for attempt in range(max_repairs) + 靠外层喂错重跑（repair 重试） + 单写 · 单轮 · 为压便宜档单价采的形态 + studio.py:159 单轮 / :266 外层 repair 循环 + + + + ② amodel-gen / gen.mjs + working ref（实线） + A-model 在 LittleJS 上 · JS harness + 多轮 ReAct done 门已在 M3 上跑通 + check / build 循环内快反馈 + 历史压缩（长程上下文不爆） + 5 工具沙箱 · 仍在 LittleJS / game-runtime + JS 参照系（不照搬）· feat/mac-amodel-foundation + + + + ③ tier2 · Phaser 富游戏 + tier2 待建（虚线） + Python · AgentScope 2.0.3 多轮自治 + 放开 max_iters → Agent 内 ReAct 多轮 + reason → act 写源 → 读 verdict → 再 reason + 种子仍是 studio.py（Python） + 造 Phaser 多系统富游戏（肥鹅美食街档） + 整轨待 0号 spike 验证 · 尚未落代码 + + + + 参照系 + + fork 演进 + + + amodel-gen 三件可复用范式（tier2 U2 / U7 复用 · 实线=范式已落，虚线框=tier2 复用为待建） + + + + done 门 + agent 自判完成才收 + 多轮 ReAct 不靠外层固定轮数， + 由 agent reason 自己判「够了」才终止。 + + tier2 复用 → U2 多轮 ReAct（finish 工具收尾吐 src/） + + + + check / build 快反馈 + 每轮先跑便宜检查再决定 + 循环内先做便宜的 check / build， + 拿快反馈喂下一轮，不等重门才纠错。 + + tier2 复用 → U7 闭环：写源 → build → headless 快检 → L1 门 + + + + 历史压缩 + 长程上下文不爆 + 多文件富游戏迭代轮数多、上下文长， + 压缩历史让长程多轮不撑爆窗口。 + + tier2 复用 → U7 长程一致性（12+ 文件无 checkpoint 丢失） + + + + 边界说明 · fork 演进而非返工（创始人 2026-06-23 裁：两线分立、不收敛） + 复用躯干：tier2 复用 studio 那套多角色 prompt 与生成域（design / code / fix）的躯干，把「多轮」从外层 repair 循环搬进 Agent 内部 ReAct（max_iters 放开）。 + 接法 A（七成已建）是接法 B（ReAct 自治）的躯干 evolve——是 fork 起步、独立演进、运行期零依赖现有 worker，不是推倒重来。 + 种子归属：种子仍是 studio.py（Python · 框架接缝 6 符号在 2.0.3 兼容、版本钉级别）；amodel-gen 只作 working reference（JS · 参照循环范式，不照搬）。 + 重写面（≠平移）：validate / run / prompt / roles 是 LittleJS 专属，按 Phaser 重写、工作量约等于 net-new——别被「6 符号兼容」误导成「整个 U2 是平移」。 + + tier2 待建（虚线）：amodel-gen 合并 dev/2.0.0 后，循环范式以合并后版本为参照系重取；多轮 ReAct / Workspace / Service 是 net-new 的真功夫（Phase B）。 + 边界从旧「能力档（声明式 vs 自治）」精确为「引擎 / 表现层复杂度档」：A-model 吃 LittleJS 轻量档，tier2 吃 Phaser 重表现富游戏档。 + + 映射：docs/plans/2026-06-22-003-feat-tier2-富游戏自治生成线-plan.md §与 A-model 分支的关系 · tier2/HANDOFF.md §与 A-model 分支的协调 · tier2实现详设.md §建设五步(第一步) · wg1/gen-worker/worker/agent_loop/studio.py:159/:266 ｜ 状态：建 ｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-D-03-富游戏专属门.svg b/docs/architecture/架构/生成引擎/assets/t2-D-03-富游戏专属门.svg new file mode 100644 index 00000000..8670cfe7 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-D-03-富游戏专属门.svg @@ -0,0 +1,113 @@ + + + + + + + + + 图 D3 · 富游戏专属确定性门（族 D） + 九门是超休闲单局的机制地板；富游戏的本质难点是多系统接线，故 tier2 在九门之上补三道确定性门（全为 tier2 待建）。 + + + + 整图状态 = 建（tier2 待建 · 经营品类专属确定性门）：整轨待 0号 spike 验证、尚未落代码。 + 实线 = 承袭现行已落（九门 harness / A-model 已建）；虚线 = tier2 专属新机制（三联动门 / 经济门 / latch 门 · 待建）。 + + + + 现行九门 = 「超休闲单局」的机制地板（实线，已落 · 见 D2）；它确定性地判「能不能玩」，但不查跨系统接线。 + 富游戏（mini-肥鹅级）是多个系统耦合，光过九门不够 —— 还要确定性地证「三系统真接上了」「经济双路径真能跑到终态」「终态真落定」，故补下面三门。 + + + + + ① 三联动门 · 跨系统接线 + 测：合成 / 资源 / 订单三系统真耦合，非三孤岛 + 判据（确定性·静态+真玩）： + • 订单 requires 须被合成系统产出物品满足 + （跨表可达性 · 静态查 mergeChains→orders） + • 合成链是 DAG 且无环（mergeChains 拓扑） + • 完成订单调资源系统 addCoins + • 合成消耗调资源系统 consumeIngredient + L1 + 硬 + tier2待建 + assertAfterPlay：订单引物品可达、 + 合成 DAG 无环 + + + + ② 经济门 · 双路径到终态 + 测：数值经济闭环 —— 既可盈利又可破产 + 判据（harness 真输入驱动跑到终态）： + • 可盈利：金币从开局 20 攒到 100 = 赢 + （经「合成→交单→收金币」正循环） + • 可破产：连续 3 个订单流失 = 输 + （只合成不交单 / 经济崩盘） + • 两条路径都要能被 harness 真输入 + 驱动跑到终态（不是只在数据表里能算） + L1 + 硬 + tier2待建 + assertAfterPlay：经济可盈利可破产 + + + + ③ latch 门 · 终态落定 + 测：赢 / 输落定不回弹，宿主能读到终局 + 判据（承现行宿主装载约束）： + • 终态 latch：赢 / 输一旦落定不回弹 + • 宿主轮询 latch，不靠游戏 emit + （游戏无 emit 通道） + → 生成约束 latch 终态 + 宿主轮询 + （约束写者把终态焊成可轮询 latch） + L1 + 硬 + tier2待建 + 承 A-model「observe→enforce」范式（见 D2 脚带） + + + + 现行九门（实线 · 已落） + A_boot / B_uncaught / C_frame / D_render / + E_live / F_wiring / G_input / H_progress / I_control + + ＋ + + + tier2 三道专属门（虚线 · 待建） + ① 三联动门（跨表可达 + DAG） + ② 经济门（盈利 / 破产双路径） ③ latch 门 + + ＝ + + + tier2 的 L1 机制地板 + 九门（超休闲地板）＋ 三门（富游戏接线地板） + 共同构成 · 全绿 = 富游戏机制地板通过 + + + + + + + 靶子 = mini-肥鹅（spike 对照组的确切施工图） + 3×3 合成棋盘 · 资源系统（金币 + 食材库存 {coins, ingredients}）· 3~5 个顾客订单（含 patience）。 + 内容量：12 个物品 / 6 条合成链（mergeChains）/ 5 个订单模板（orders）/ 2 种货币 —— 砍到能证、又保住多系统耦合 + 重 UI 表现层 + 数值经济闭环三个本质难点。 + + assertAfterPlay 规格（前置物清单 · tier2 待建）：① 订单引物品可达（合成产出能满足全部订单 requires）； + ② 合成 DAG 无环（mergeChains 拓扑无环）；③ 经济可盈利可破产（金币 20→100 赢路径、连续 3 单流失输路径，两路径 harness 真输入驱动可达终态并 latch）。 + 复用 game-e2e-cdp-harness 四件套证据（render→截图时序→驱动→verdict）；driver 按「点合成格→凑齐订单物品→交单→看金币涨」确定性序列预建。 + + + 质量 + 可靠 + 数据 + + 映射：tier2实现详设.md §靶子游戏-mini-肥鹅 / §过门判据与精确阈值 / §前置物清单 ｜ 状态：建（tier2 待建 · 经营品类专属确定性门）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-D-04-advisory分级与Goodhart隔离.svg b/docs/architecture/架构/生成引擎/assets/t2-D-04-advisory分级与Goodhart隔离.svg new file mode 100644 index 00000000..13a2c660 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-D-04-advisory分级与Goodhart隔离.svg @@ -0,0 +1,122 @@ + + + + + + + + + + + + 图 D4 · driven 感知 advisory 分级 + Goodhart 隔离 + 上：driver 缺位→两门降 advisory（承 A-model 已建·实线）。下：agent 自产 driver 走三层隔离防 Goodhart（tier2 第二段·待建·虚线）。 + + + + 整图状态：现（advisory 分级 = A-model 已落）+ 建（自产 driver 隔离 = tier2 第二段，待 0号 spike）。 + 实线/实心 = 现行已落（九门 harness · A-model）；虚线框（stroke-dasharray 6 4）= tier2 专属新机制、待建。徽章：质量 / 安全 / 可观测。 + 质量 + 安全 + 可观测 + + + 上半 · driven 感知 advisory 分级（承 A-model · 创始人 B 裁 2026-06-22 · 现行已落 = 实线） + + + + 态 ①　spec 无 driver / 无 inputs + driven = (spec.driver 存在) 或 (spec.inputs 非空) → false + 游戏未被驱动 → 无法公平评判可玩性 → 降 advisory + + + 硬门 = 7（计入 pass·致命） + A_boot · B_uncaught · C_frame · D_render · F_wiring · G_input · I_control + + + advisory = 2（仍跑 · 仍报告 · 不计入 pass） + E_live（活动 hash）· H_progress（机制进展 + latch 终态） + + + + 态 ②　spec 有 driver / 有 inputs + driven = true（design 产 driver，或 spec 给 inputs 序列） + 游戏被驱动 → 可公平评判 → 9 门全部恢复致命 + + 硬门 = 9（E_live / H_progress 自动恢复致命，无需改代码） + A_boot · B_uncaught · C_frame · D_render · E_live + F_wiring · G_input · H_progress · I_control + factory / gamedef 本就带 driver → 不受影响，始终 9 门致命。 + + + + driver 到位 + 恢复致命 + + driver 缺位 + 降 advisory + + + + 一句话：driver 缺位 → advisory，driver 到位 → 恢复致命。tier2 修 latch 与经营门的 observe → enforce 复用此范式（先观测、driver 到位再卡死）。 + + + 下半 · 自产 driver 的 Goodhart 三层隔离（tier2 第二段「开放自产 driver」· 待 0号 spike · 待建 = 虚线） + + + + agent 提议 / 扩 driver + 放开第二段：让自治 agent + 自产或扩 harness driver + （测自治上限） + 待建 + + + + ① 平台编译 + 按 schema 和白名单编译 + 只许声明式合法形态过编译； + 非白名单 / 越界字段直接拒。 + 安全 + + + + ② 独立 adversarial 评审 + 不向着被评对象 · 专找漏洞 + 查：是否覆盖真实玩家路径？ + 查：是否读作弊字段（避真考验）？ + 安全 + 质量 + + + + ③ 通过才用 + 三层全过 → 该 driver 才入验收 + 任一层不过 → 退回 agent 重提， + 驳回计入「被打回比例」指标。 + 质量 + + + + + + + + + 铁律 · 写者不能写判自己游戏的那张卷子 + Goodhart = 优化代理指标反而偏离真目标。agent 既造游戏又造判它的 driver，会把 driver 写成只盖走过的路、只读不暴露真实力的字段 → 假绿。 + 隔离手段：编译 + 独立评审把「写卷人」与「判卷人」拆开，自产 driver 不得降低过门可信度（第二段 gate）。 + + + + 采集（数据维度·第二段专属）： + 数据 + driver_rejected_by_review = 自产 driver 被独立评审打回的比例　·　driver_edits = driver 修改次数（防它靠反复改 driver 逃避卡死探测）。 + + + 映射：game-runtime/games/_wg1-gen/_shared/play.cdp.cjs（advisory 分级 L1077-1085·A-model 分支）· 生成引擎/tier2实现详设.md §两段实施步骤 第二段 + §建设五步 第三步 Goodhart 安全 ｜ 状态：现（advisory=A-model 已落）/ 建（自产 driver 三层隔离=tier2 第二段待建）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-D-05-CDP探针Phaser重写.svg b/docs/architecture/架构/生成引擎/assets/t2-D-05-CDP探针Phaser重写.svg new file mode 100644 index 00000000..c501b789 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-D-05-CDP探针Phaser重写.svg @@ -0,0 +1,118 @@ + + + + + + + + + + + + 图 D5 · CDP 探针 Phaser 重写 + 沙箱底座 + 九门探针机制不变(真浏览器真玩 + 确定性判定),但引擎钩子是 LittleJS 专属——tier2 要为 Phaser 重写。这是「重写适配层」,不是参数化一键切换。 + + + + 整图状态 = 建(tier2 待建·待 0号 spike 验证)。实线 = 现行已落(九门 harness / A-model 已建的 LittleJS 探针)；虚线框 = tier2 专属新机制(Phaser 重写 + 沙箱底座 spike,尚未落代码)。 + 右侧 Phaser 钩子全画虚线;实线 LittleJS 钩子 → 虚线 Phaser 钩子的「重写映射」用虚线箭头,逐条须各自重写,不是一个参数切过去。 + + 可观测 + 质量 + 可靠 + + + 引擎钩子重写映射(LittleJS 现行 → Phaser 待建) + 每行一条钩子:左 = 探针现在硬编码的 LittleJS 取法(实线·已落) → 右 = tier2 要为 Phaser 重写的等价钩子(虚线·待建)。 + + + + 现行 · LittleJS 钩子(play.cdp.cjs 硬编码 · 实线) + + tier2 · Phaser 等价钩子(待重写 · 虚线) + + + + ① 引擎 / canvas 选择器 + #game-engine + 用于像素回读 / 触摸坐标映射(captureImageData·mapToClient) + + ① Phaser canvas 选择器(待定) + Phaser 实例挂载的 canvas 节点 + Phaser 自挂 canvas、id 不同 → 选择器与坐标映射要按 Phaser 视口重写 + + + + ② 帧源(掌帧 / 推进 / 对照) + window.__engine.snapshot().frame + C 门帧 delta / G 门对照实例推进到同帧号 都读它 + + ② Phaser 帧计数源(待定) + Phaser 的帧 / 时钟计数 + Phaser 帧驱动机制不同 → 取一个单调递增的帧计数替代 __engine.frame + + + + ③ boot 信号(装载就绪) + __gameHostEngineInitFired + A 门 waitBoot 轮询(配 __genBooted)判引擎接管完成 + + ③ Phaser boot 信号(待定) + Phaser scene create 完成信号 + Phaser boot 序列独立 → 另置一个「引擎已起、可真玩」的就绪标志 + + + + ④ 输入注入 + 状态读取 + tap / key 注入 · __gameState 读取 + G 门输入改状态 / H 门 assertAfterPlay 经 _forensicsView 导出 + + ④ Phaser 输入 + 可观测 state(待定) + Phaser 输入接口 + 富游戏 state 导出 + 输入投递路径与可测性接口按 Phaser 重接;富游戏 state 走经营门约定 + + + + 重写 + + 重写 + + 重写 + + 重写 + + + + 沙箱底座小验证(spike 前置阻断 · plan U3) + 可观测 + 可靠 + 先做小验证:agentscope-runtime BrowserSandbox 是否暴露足够的 + page.evaluate / CDP(navigate / screenshot / 输入注入 逐项可用)? + + + 够 → 用 BrowserSandbox + 直接用其暴露的 page.evaluate / + CDP 跑探针矩阵 + + 不够 → 回落复用 play.cdp.cjs 路 + 自建薄沙箱 + 复用现有 CDP 驱动 + + Phaser driver 重写 + + + + 第一版克制:只参数化钩子,能力包接口不抽满 + 只参数化九门 harness 的引擎钩子(canvas 选择器、帧计数源), + 把 Phaser 的 rag 和脚手架硬编码进 worker。 + + 通用能力包接口(skill / mcp / tool / rag / 脚手架)暂不建满。 + 理由:只有 Phaser 一个真实现,接口形状会被它反向决定。等第二个引擎 + (Pixi)落地、有两个实现做依据,再抽真正的能力包接口。 + + + 阻断关系:沙箱底座结论须在 U7 生成迭代开跑前出来——这道结论不出,U7 的生成迭代跑不起来(spike 前置阻断项,见 plan U3 / Risks)。 + 映射：game-runtime/games/_wg1-gen/_shared/play.cdp.cjs · docs/plans/2026-06-22-003-…-plan.md U3 · tier2实现详设.md §前置物清单 · 自治富游戏引擎.md §引擎是能力包 ｜ 状态：建(tier2 Phaser 重写探针 + 沙箱底座 spike,待 0号 spike 验证)｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-E-02-引擎能力包manifest.svg b/docs/architecture/架构/生成引擎/assets/t2-E-02-引擎能力包manifest.svg new file mode 100644 index 00000000..56d60b96 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-E-02-引擎能力包manifest.svg @@ -0,0 +1,98 @@ + + + + + + 图 E2 · 引擎能力包 manifest（五件套） + 引擎不是固定底座，而是动态加载的能力包：每个引擎 = 一套给 agent 用的 {skill · tool · mcp · rag · 脚手架}。换引擎 = 换一套加载的工具集，不是架构重写。 + + + + 整图状态 = 建（第一版 Phaser 硬编码进 worker，通用能力包接口待第二引擎落地再抽）。tier2 整轨待 0号 spike 验证、尚未落代码。 + 五件套实线卡 = 概念定义（说明每件是什么，非建成断言）；虚线框 = tier2 专属新机制（待建）；底部绿条 = 承袭现行已落（九门 harness 钩子 / A-model）。 + + + + 核心论点:引擎在这套架构里不是「一次选定、所有游戏都长在上面的固定底座」，而是「动态加载的能力包」。 + 每个引擎对应一套五件套；换引擎对 agent 就是换一套加载的工具集，不是架构重写——这正合 agent「我有哪些工具能调」的工作方式。 + 首批引擎 = Phaser / Pixi（见 E-01 toolkit · 引擎选型见生成引擎域）；Phaser 有真实现，Pixi 当前留桩。 + + + + + skill · 可复用操作 playbook + 质量 + 给 agent 的可复用操作 playbook + 这一引擎下「如何做某一类事」的固化步骤 + 边界：引擎相关；换引擎换一套 + 作用：把对的写法沉淀，少让模型现场摸索 + + + + tool · toolkit 工具 + agent 在 ReAct 循环里能调的 toolkit + 即 E-01 那 9 个工具（写源 / 构建 / 跑门…） + 边界:工具的引擎实现（esbuild profile / harness 钩子）按引擎重写 + 作用：ReAct「想一步 · 调一个工具 · 看结果」的工具面 + + + + mcp · 模型上下文协议接入 + 经 MCP 把这一引擎的能力接给 agent + 模型上下文协议（Model Context Protocol） + 边界:引擎相关；与 tool 并列、由能力包一并装载 + 作用：标准化地把引擎侧能力暴露成可调接口 + + + + + rag · 引擎文档 + 范例检索 + 质量 + 引擎文档 + 范例的检索增强 + 补训练数据密度——模型见这引擎代码越多写得越对 + 边界：每引擎一套文档 / 范例语料 + 作用：自治循环里少漂、少编 API + + + + 脚手架 · 模板初始化骨架 + 模板初始化铺的工程骨架 + 阶段 2 起手 template-init 铺一套工程骨架（见 E-01） + 边界:骨架 = 平台预建那 25%（经营骨架·三系统+耦合点） + 作用:给单写 agent 一个先天过 boot 的起手点 + + + + 换引擎 = 换一套加载的工具集 + Phaser 能力包 ⇄ Pixi 能力包 + 对 agent 只是换掉「我有哪些工具能调」的那一组 + 不是架构重写，不动两阶段角色与三层校验主干 + Phaser 真实现 · Pixi 留桩（首批两引擎） + + + + 克制警示（tier2 待建 · 虚线）：第一版不把五件套建满 + 一上来就建满（skill / tool / mcp / rag / 脚手架），而只有 Phaser 一个真实现、Pixi 留桩——接口形状会被那唯一实现反向决定，接第二个引擎多半得改。 + 真正的能力包接口，等第二个引擎（Pixi）落地、有两个实现做依据，再抽。不为一个实现先建抽象。 + + + + 实验阶段最小项 ①（虚线·待建） + 把九门 harness 的引擎钩子参数化: + canvas 选择器 / 帧计数源（钩子机制承袭现行九门，实线）。 + + + 实验阶段最小项 ②（虚线·待建） + 把 Phaser 的 rag 和脚手架硬编码进 worker: + 不抽通用接口，先把这一个引擎跑通再说。 + + + + 承袭现行已落（实线）:九门 harness 的钩子机制本身、A-model 的 driver 感知分级——这些是现行 LittleJS 廉价线已建、tier2 复用其哲学而非新造。 + + 映射:自治富游戏引擎.md §引擎是能力包不是底座 · tier2实现详设.md §运行时形态 · 见 E-01 toolkit ｜ 状态:建（第一版 Phaser 硬编码 · 通用接口待第二引擎）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-E-03-prompt两阶段角色.svg b/docs/architecture/架构/生成引擎/assets/t2-E-03-prompt两阶段角色.svg new file mode 100644 index 00000000..cd679192 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-E-03-prompt两阶段角色.svg @@ -0,0 +1,130 @@ + + + + + + + + + + + + + + 图 E3 · prompt 两阶段角色（族 E） + 阶段 1 工作室设计用 Agent Team 多 agent 发散 + 专业分工；阶段 2 收敛到单写实现防并行写冲突。内部拓扑照 AgentScope 2.0.3 真 API 画。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码，故 tier2 专属新机制一律画虚线（待建）；承袭现行已落的（九门 harness / A-model）画实线。 + 虚线框 + 「建」小标 = tier2 待建；实线框 = 现行已落。Agent Team 与单写 ReAct 的内部拓扑均照 AgentScope 2.0.3 源码实证（/root/oss/agentscope 逐条核过）。 + + 质量 + 伸缩·多agent + 数据·只读探 + + + + 阶段 1 · 工作室设计（Agent Team 星形） + 建 + 只读+对话 + leader 分析拆解用户意图 → 经 AgentCreate 拉起设计 worker 发散 → 经 TeamSay 把各路结论汇回 leader 收敛成设计结论。 + + + + leader + 分析拆解意图 · 收敛结论 + 星形拓扑唯一协调中心 + + + + + 玩法设计 worker + + 关卡设计 worker + + 数值设计 worker + + + UI设计 worker + + 音乐设计 worker + + + 特效设计 worker + + 资产设计 worker + + + + + + + + + + TeamSay 汇回 + + + worker 用 PermissionMode.EXPLORE 只读已有工程代码 + 工程内设计文档（迭代已有游戏时），并与用户跨 session 多轮对话，不写代码。 + + + + 拓扑铁律 · leader-worker 星形 + worker 只拿到 TeamSay —— 只能把结果报回 leader。 + 禁止 worker 之间互评 / 互相喊话，所有协调都过 leader 这个中心。 + + 2.0.3 删掉了进程内的 MsgHub / pipeline。 + 进程内多 agent 协作那套没有了，只剩部署态的 Agent Team（TeamCreate / AgentCreate / TeamSay）。 + 禁 worker 互喊话 + 只剩部署态 Agent Team + 工作室建在这套 Agent Team 上，不去找已不存在的 MsgHub。多 agent 边界照 2.0.3 源码核过，免照旧版资料踩坑。 + + + + 阶段 2 · 单写实现 + 建 + 单写防冲突 + 收敛到单写：单个 Agent 跑 ReAct 多轮写代码，防多系统共享状态被并行写写崩。 + + + + 模板初始化工具铺骨架 + 新建路径起手 + + 写工程内设计文档 + 阶段 1 各设计 agent 结论落档 + + 单写 agent 写代码 + 单个 Agent · ReAct 多轮 + + + 三层校验 + L1 硬约束 / L2 设计符合 / L3 效果 + + 产出 + 真 Phaser 源工程 + + + + + + + + + + 设计结论交接 + + + + prompt 生成域承 studio.py 多角色（design / code / fix）—— tier2 复用其多角色 prompt 与生成域躯干，fork 起步、独立演进。 + 「单写者」专指阶段 2 写代码环节，不是整轨只一个 agent：阶段 1 设计用多 agent 要发散 + 专业分工，阶段 2 实现收敛到单写要防并行写冲突。 + 承袭实线 = 九门 harness / A-model（现行已落，见 D2）；tier2 专属新机制（Agent Team 星形 / 单写 ReAct 多轮）= 虚线待建，待 0号 spike 验证。 + + 映射：tier2实现详设.md §「运行时形态：两阶段、service 化与 session 三路径」 · 自治富游戏引擎.md §「换一种生成方式」+§「谁在写：单写者 ReAct」 ｜ 状态：建（阶段1 Agent Team / 阶段2 单写，2.0.3 API 已核）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-E-04-Amodel插件复用.svg b/docs/architecture/架构/生成引擎/assets/t2-E-04-Amodel插件复用.svg new file mode 100644 index 00000000..a777329b --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-E-04-Amodel插件复用.svg @@ -0,0 +1,111 @@ + + + + + + 图 E4 · A-model 4 插件复用（族 E） + A-model（Tier1 廉价线 agentic 优化）造的资产 tier2 接住、别重新发明。两线分立：A-model 吃 LittleJS 轻量经营档，tier2 吃 Phaser 重表现富游戏档。 + + + + 整图状态：接（复用 A-model 已落资产 · 合并后对账）。实线框 = A-model 现行已落（承袭即用）；虚线框 = tier2 专属新机制（待 0 号 spike 验证、尚未落代码）。 + 两线分立(创始人 2026-06-23 裁)：边界 = 引擎 / 表现层复杂度档,非能力档。A-model = LittleJS 轻量自治(单局 + 轻量经营/合成);tier2 = Phaser 重表现富游戏(肥鹅美食街档)。 + + + 数据 + 质量 + 成本 + 数据 = 复用引擎无关契约/命名;质量 = 渲染 impl 按 Phaser 重做不降级;成本 = 不重新发明、省 Mac 重复造轮子。 + + + + 论点:A-model 的 api.d.ts 是引擎无关、零语义的契约——tier2 Phaser 能力面直接复用契约 / 命名,仅渲染 impl 按 Phaser 重做(impl 绑 Canvas、跨不了引擎)。 + 源:plan「与 A-model 分支的关系」§54 · HANDOFF「与 A-model 分支的协调」§30。游戏运行时路径 game-runtime/src/plugins/<插件>/api.d.ts。 + + + ① 四插件契约复用(渲染按 Phaser 重做) + + + + scene-fsm + 场景状态机 + 引擎无关零语义契约 + 复用：api.d.ts 契约 / 命名 + 契约复用 + 渲染按 Phaser 重做 + + + + hud-ui + HUD 界面 + 引擎无关零语义契约 + 复用：api.d.ts 契约 / 命名 + 契约复用 + 渲染按 Phaser 重做 + + + + session-score + 局内计分 + 引擎无关零语义契约 + 复用：api.d.ts 契约 / 命名 + 契约复用 + 渲染按 Phaser 重做 + + + + timer-scheduler + 定时调度 + 引擎无关零语义契约 + 复用：api.d.ts 契约 / 命名 + 契约复用 + 渲染按 Phaser 重做 + + + + sim-business · 经营配方 + 经营 / 合成的系统骨架——tier2 复用其配方(非渲染件,是数值/系统结构配方)。源:.agents/skills/agentic-amodel-generation.md（3 层边界 + sim-business 配方）。 + 配方复用 + Phaser 数值落地 + + + ② 九门基线 — 承袭 A-model 改过的 play.cdp.cjs(现行已落 · 实线) + + A-model 改了 play.cdp.cjs:SAA-mode __GameBundle 信封 + driven 感知 advisory 分级 + _forensicsView。 + 「driver 缺位 → advisory,driver 到位 → 恢复致命」分级范式。 + 复用 driver 感知分级范式 + tier2 U3/U6: + fork 源与行号锚点 钉到 A-model 合并后版本 重取; + 分级范式复用到 tier2 修 latch 与经营门 observe→enforce。 + + + + + tier2 专属新机制(待建 · 虚线):探针为 Phaser 重写 + tier2 待建 + #game-engine 选择器 / __engine.frame 帧源 / boot 信号 全换; + 沙箱底座(BrowserSandbox vs 复用现有 CDP)= spike 前置阻断验证。 + 承袭分级范式(实线哲学),探针实现按 Phaser 重写(虚线待建)—— + 同 D2:复用「真玩判定 + 零自评」哲学、为 Phaser 重写探针。 + + + ③ 源项目契约 — A-model 升 oneOf(1.0/2.0),tier2 仍另立独立 schema + + A-model:source-project.schema.json 升 oneOf(1.0 / 2.0 = 真多文件 JS)。 + 2.0 绑死 __GameBundle + 九门 + ECS-lite 装载路(LittleJS keystone 契约)。 + 现行已落(实线·承袭) + + + tier2:另立独立 schema、不加 3.0 进同一 oneOf(理由见 plan KTD7 / U9)。 + Phaser 工件装载序列不同(第二装载分支)——避免把 Phaser 差异焊进 LittleJS keystone 契约。 + tier2 待建 + + + 注脚:A-model 合并 dev/2.0.0 后,接缝(play.cdp.cjs / source-project.schema.json)会刷新——实现 tier2 时以合并后版本为准对账(plan §61 · HANDOFF §35)。 + + 映射:plan「与 A-model 分支的关系」§54/§56/§57/§61 · tier2/HANDOFF.md「与 A-model 分支的协调」§30/§32/§33/§35 ｜ 状态:接(复用 A-model 资产,合并后对账)｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/tier2细节图说-C-单写ReAct循环.md b/docs/architecture/架构/生成引擎/tier2细节图说-C-单写ReAct循环.md new file mode 100644 index 00000000..a055c07d --- /dev/null +++ b/docs/architecture/架构/生成引擎/tier2细节图说-C-单写ReAct循环.md @@ -0,0 +1,91 @@ +--- +date: 2026-06-23 +topic: tier2 细节图说 · C 族——单写 ReAct 循环 / M3 原生接法 / 四道熔断 / 多轮范式承 amodel +status: 设计中（tier2 待 0号 spike 验证、尚未落代码） +映射源档: + - { doc: "docs/architecture/架构/生成引擎/自治富游戏引擎.md", hash: "4858e6cf" } + - { doc: "docs/architecture/架构/生成引擎/tier2实现详设.md", hash: "d5efe45f" } + - { doc: "docs/plans/2026-06-22-003-feat-tier2-富游戏自治生成线-plan.md", hash: "ccb00bb9" } + - { doc: "tier2/HANDOFF.md", hash: "ccb00bb9" } +--- + +# tier2 细节图说 · C 族 — 谁在写富游戏 + +C 族四张图围着一个问题转：tier2 要造现有廉价线做不出来的多系统富游戏，那么到底是谁在写、用什么模型写、写的时候被什么关着、这套写法又是从哪条已经跑通的路演进来的。图 C1 画清写者的形态——一个单写者 ReAct agent 在三层校验门内自治迭代；图 C2 画清这个 agent 怎么把中等档的 MiniMax-M3 接对；图 C3 画清自治多轮被四道熔断关在笼子里；图 C4 把这套写法回溯到它的两个 working reference，说明它是 fork 演进而非推倒重来。 + +整个 C 族对应的是一条尚未落代码的设计轨。tier2 的中心赌注——便宜或中等模型的自治 agent 能不能稳定写出富游戏里那一大块表现层——要靠一个叫 0号 spike 的最小验证来证伪或证成，过了这道生死门才进建设。所以读这四张图时，要把它们当成「计划怎么干」的施工图，而不是「已经在跑」的现状图。 + +## 0 阅读约定与同步纪律 + +C 族把生成引擎子树里三份设计档画成图：写者形态与四道熔断出自《自治富游戏引擎》的「谁在写：单写者 ReAct + 四道熔断」一节；运行时形态、建设五步、模型矩阵出自《tier2 实现详设》；与 A-model 分支的复用边界出自 tier2 富游戏自治生成线的实现计划与 `tier2/HANDOFF.md`。frontmatter 记了这四份的当前 commit hash 作为防漂移门——设计一变动，本图说与对应 SVG 必须同步更新，hash 对不上就说明图已落后于源档。 + +四张图整体状态都是「建」：tier2 整轨待 0号 spike 验证、尚未落代码。但「待建」不等于「全凭空想」。这套写法承袭了两条已经在跑的真实参照系——现行 WG1 廉价线的 `studio.py`（单轮调用加外层重试）和 A-model 分支的 `amodel-gen/gen.mjs`（在 M3 上已跑通的多轮 ReAct）——所以图里凡是承袭这两条已落机制的部分画实线，tier2 专属、要新写的部分画虚线。这条虚实之分贯穿全族，是读图时最该先盯住的一层：实线 = 现行已落或官方现成、可以直接信；虚线 = tier2 待建、还要写还要验。状态码就四个——现（现行已落）、接（待接线）、建（待建）、缓（收窄后缓做），C 族绝大多数元素是「建」。 + +## 1 全图通用图例 + +四张图共用一套视觉语言。**实线箭头/实线框**表示承袭现行已落的机制：九门 harness、new-api 计费平面、`studio.py` 单轮形态、`amodel-gen` 多轮范式都属此类，它们是已经跑过的 working reference。**虚线箭头/虚线框**（`stroke-dasharray 6 4`）表示 tier2 专属的待建新机制：Agent 内多轮 ReAct、M3 原生接法、thinking 分离、三道自建硬熔断、Phaser 富游戏产物，都还没落代码。**红线**专用于四道熔断——任一道先触发即停本局生成。 + +徽章标的是这块内容服务哪个生产维度：绿色的**质量**（造出真能玩的富游戏）、**可靠**（稳定收敛不靠运气擦边）、**成本**（压住自治多轮的烧钱）、蓝色的**可观测**（每步推理动作观察可对账）。状态徽章里，紫底的「待建」「tier2 待建」标 tier2 自己要写的部分，深灰底的「现行已落」「working ref」标可直接复用的参照系，橙底的「best-effort 非硬闸」标一处已知没焊死的设计缝。 + +## 2 图集 + +### 图 C1 · 单写 ReAct 循环〔SVG·建〕 + +![图 C1 单写 ReAct 循环](assets/t2-C-01-单写ReAct循环.svg) + +这张图回答「谁在写富游戏、以什么节奏写」。写者是一个单写者 ReAct agent。ReAct 指 agent「想一步、调一个工具、看结果、再想下一步」的循环——图中央那个 reason→act→observe 的三角就是这个节奏，它的反面是「一次把整个游戏的答案写完」。富游戏工程跨十几个源文件、多个系统互相接线，一次写完几乎不可能对，所以必须让 agent 每观测一次就回头重想，在循环里把游戏逼出来。 + +图左侧的两态并列是这张图最该让人看出的东西：tier2 和现行 WG1 廉价线的真正差别，不在 prompt、不在生成域，而在「多轮自治放在哪一层」。WG1 现行用的是 `ReActConfig(max_iters=1)` 的单轮调用，加一个外层 `for attempt in range(max_repairs)` 的重试循环——生成一次，外层把错误喂回去重跑一次，单写、单轮。它故意这么做，是为了压住便宜档的单价：L1 生产主线明确不引 AgentScope，因为框架本身的 token 膨胀会吃掉便宜档那点利润空间。tier2 则把 `max_iters` 放开（AgentScope 2.0.3 默认 20），把「多轮」从外层 repair 循环搬进 Agent 内部的 ReAct 循环——同一套多角色 prompt 和生成域躯干复用，但自治的位置变了。这就是为什么左下角那块 tier2 态画虚线、还标着「独立锁 AgentScope 2.0.3、独立演进」：它从 WG1 fork 起步，但锁自己的框架版本、独立往前走，不强求两条线跟同一份 AgentScope。 + +中下那个虚线笼子是另一处要点——agent 的自治不是放任。它被关在一圈验收门里迭代：读引擎文档和资产 → 写源文件 → esbuild 构建 → headless 无头快检 → 九门 L1 真浏览器真玩 → 读 verdict → 没过就改、改完回到写源。这里有一条画成实线的关键节点：九门 L1 那一格。一款游戏算不算过关，不靠模型自己说，靠在真浏览器里真玩一遍——这套确定性判定继承自现行九门，铁律是绝不让 LLM 给自己打分。LLM 一旦进验收当裁判，会学会把游戏优化成「让裁判说好」而不是「真的好」，门就废了。所以图里九门那一格是实线（承袭现行已落），而它前后的写源、改、快检都是虚线（tier2 内循环待建）——确定性的判定承袭旧机制，自治的写法是新的。 + +右上角那个红框是四道熔断，任一触发即停：步数硬顶、预算闸、卡死探测、双层超时。其中预算闸现在还不是强制硬闸——这是一处已知设计缝，详见图 C3。 + +底部那条铁律带讲清「单写者」这三个字的边界，很容易误读。单写者只指阶段 2 写代码这一环：只有一个 agent 持有整个工程的全局视图，它一个人写，不并行拆给多个 agent。坚持这点是因为经营游戏的多个系统共享同一套状态和约定，拆给并行 agent 几乎必然不一致——一手教训是曾经把「造一个 Flappy Bird」拆给并行子 agent，结果背景跑成了马里奥。但阶段 1 的工作室设计仍然用 Agent Team 星形多 agent 去发散（玩法、关卡、数值、UI、音乐、特效各路 worker），收敛成设计结论后才进阶段 2 的单写。设计要发散和专业分工用多 agent，实现要防写冲突收敛到单写——所以「单写」专指写代码那一段，不是说整轨只有一个 agent。 + +### 图 C2 · M3 Anthropic 原生接法〔SVG·建〕 + +![图 C2 M3 Anthropic 原生接法](assets/t2-C-02-M3原生接法.svg) + +这张图回答「中等 agentic 档的 MiniMax-M3 怎么接进 tier2 的 agent」。主链路从左到右一条线：tier2 agent → AnthropicChatModel → AnthropicCredential.base_url → MiniMax-M3。读这条链要抓两个事实。一是接法本身可信——它走 AgentScope 2.0.3 的官方模型类 AnthropicChatModel，构造时不传 formatter 就会自动配对一个 AnthropicChatFormatter，无需手接，这套已经逐条核过 2.0.3 源码。二是出口统一——AnthropicCredential 的 base_url 指向 new-api 的 Anthropic 端点（即 `/v1/messages`），模型计费统一从 new-api 这一个平面走。链路上的箭头里，agent 到模型那几跳画虚线（tier2 待建），但 new-api 计费出口画实线（现行已落）。 + +中间三个要点框讲「用对 M3」要满足的三件事，它们合起来定义了 M3 的正确用法。其一，走 Anthropic 原生协议加 agentic 工具循环——不是 OpenAI 式的单次 JSON 填空，而是让 agent 在循环里调工具写源、build、跑门、读 verdict、改，多轮自治收敛。其二，thinking 分离：开 `thinking_enable` / `thinking_budget` 拿到推理与答案分离，这里有一条硬约束——max_tokens 必须严格大于 thinking_budget，budget 缺省取 max_tokens 的一半；如果把 budget 设得不小于 max_tokens，2.0.3 会自动把 max_tokens 抬到 budget+1024，但别依赖这个兜底，显式设对。其三，完整 response 和历史保留：每轮把 thinking / text / tool_use 所有块原样回传入历史，不剥、不丢、不只抠 JSON——这样 M3 的交错思维（Interleaved Thinking）才不失效，才发挥得出最佳 agentic 性能。 + +图中间那条红框是这张图的命门，也是为什么它值得单独画一张：旧用法是 60% 失败的最深根因，而且是用法错、不是模型天花板。错用法等于三连违反——关掉 thinking、单次 JSON 填空、失败就从头重生成。把一个 agentic 加交错思维的模型当成一次性填空机来用，等于把它最强的那部分能力全关掉了。这处误读还连着另一处：max_tokens 是「输出上限」、不是 512K 的上下文窗——输出可以抬到小于 128K 给 thinking 加答案用，输入窗 512K 不受它限。 + +底部那条绿带收口一个设计原则：模型统一从 new-api 出口走，但协议和 SDK 不锁死，每档走它各自最优端点。M3 之所以特意走 Anthropic 原生端点，是因为「用对它」要的就是原生 thinking 加 agentic 工具循环；便宜档（deepseek-v4-flash / v4-pro）照旧各自端点。不论走哪条端点，计量都收口到 new-api 的 quota 口径，折算成每款多少钱——一个计费平面，成本可对账。这是「all roads 收口到一个计费平面」的具体含义：端点可以多样，账只有一本。 + +### 图 C3 · 四道熔断 + 预算闸〔SVG·建〕 + +![图 C3 四道熔断 + 预算闸](assets/t2-C-03-四道熔断.svg) + +这张图回答「自治多轮会不会失控、靠什么关住」。agent 在三层校验门内可以任意迭代，但被四道熔断关在笼子里，任一道先触发即停本局生成。四道分别是：步数硬顶、预算闸、卡死探测、双层超时。读这张图最该看出的，是它们的来源和成熟度并不一致——这正是图里实线虚线混用的原因。 + +步数硬顶防的是「靠运气擦边」。它给每系统的构建-修复定上限、给整局定 max_iters（建议单系统不超过 8 轮、整局不超过 40 轮，超 max_iters 即判不收敛），走的是 AgentScope 的 `ReActConfig.max_iters`。它要防的不是慢，而是模型靠多轮反复试错把门擦边混过去——擦边过门和真收敛是两回事，没有步数顶就分不开。这道是 tier2 自建、待落，画虚线。 + +预算闸是四道里唯一画实线的——它用官方的 ReplyBudgetControlMiddleware，是现成中间件，在 on_reasoning / on_reply 钩子里按预算优雅收尾。但这恰恰是这张图最该被 review 的设计缝：它是软刹，不是强杀，现在还只是 best-effort，不强制截断。图里专门给它配了橙底「best-effort 非硬闸」徽章，又在底部拉了一整条警示带说清后果——自治多轮一旦不强制，会在那 56% 的表现层上烧钱发散。强制硬闸的完整口径归《agentic 集成架构》那份，规模化（premium 量起来）之前必须落地，否则成本不可控。这条缝在 spike 阶段可以容忍：先只挂官方软刹把路跑通，三道自建硬熔断加强制硬闸到建设期再补，不阻塞 spike。 + +卡死探测和双层超时都是 tier2 自建、待落（虚线）。卡死探测在语义层判 agent 是不是原地打转、无实质进展，而不是单纯计步——单纯计步拦不住「换汤不换药」的空转。它还要防一种更刁的逃避：agent 改 driver 来绕过卡死探测，这是 Goodhart 问题的一个具体形态（优化代理指标反而偏离真目标）。双层超时是两层墙钟上限——单步钉死一次工具调用或一轮推理，整局钉死本局总时长，兜住单步挂起和整局拖死两种失控。 + +机制上，这四道不是散落各处，而是叠在 AgentScope 的中间件洋葱里：官方软刹加三道自建硬熔断（各做成 MiddlewareBase 子类）一层层套进 ReAct 循环，软刹优雅收尾、硬熔断强制截断。底部那条退路带把 spike 阶段的可行起点钉死——先只挂官方 ReplyBudgetControlMiddleware 软刹跑通验证就够了，强制硬闸和三道自建硬熔断到建设期再补，不让一道还没建的硬熔断挡住最该先证的那个赌注。 + +### 图 C4 · 多轮自治范式（承 amodel-gen）〔SVG·建〕 + +![图 C4 多轮自治范式 承 amodel-gen](assets/t2-C-04-多轮范式承amodel.svg) + +这张图回答「tier2 这套多轮自治写法是凭空发明的吗」——不是，它是从两条已经跑通的真实参照系演进来的。图上方那条三态演进带从左到右画清这条血脉：① WG1 的 `studio.py` 是现行已落的单轮加外层 repair 形态（实线）；② A-model 分支的 `amodel-gen/gen.mjs` 是已经在 M3 上跑通的多轮 ReAct（实线，working reference）；③ tier2 是要在 Phaser 上造富游戏的多轮自治（虚线，待建）。①到②标「参照系」、②到③标「fork 演进」——tier2 是 fork 起步、独立演进，不是返工。 + +中间那三块是 amodel-gen 留给 tier2 的三件可复用范式，每件都配了一个紫色虚线小条，标明 tier2 在哪个工作单元复用它。done 门——agent 自己 reason 判「够了」才终止，不靠外层固定轮数，tier2 在 U2 复用为多轮 ReAct（finish 工具收尾吐出 src/ 源工程）。check/build 快反馈——每轮先跑便宜的检查再决定下一步，拿快反馈喂下一轮而不是等重门才纠错，tier2 在 U7 复用为「写源 → build → headless 快检 → L1 门」的闭环。历史压缩——多文件富游戏迭代轮数多、上下文长，压缩历史让长程多轮不撑爆窗口，tier2 在 U7 复用为长程一致性（12 个以上文件的工程过程中无 checkpoint 丢失）。 + +图底那条蓝带是这张图最该读透的部分，它讲清一处极易被误导的边界——「fork 演进」不等于「整轨是平移」。tier2 复用 studio 那套多角色 prompt 和生成域躯干，把「多轮」从外层 repair 搬进 Agent 内部 ReAct，这层确实是 fork 加版本钉级别的轻活：种子 `studio.py` 用到的 AgentScope 框架接缝（6 个符号）在 2.0.3 全兼容，零签名改。但别被「6 符号兼容」误导——studio.py 拖着的 `validate.py` / `run.py` / `prompt.py` / `roles.py` 是 LittleJS 专属，按 Phaser 重写、工作量约等于全新写（net-new）。最典型的是 validate 的硬规则：它对 LittleJS 要求「禁 import、单 export default 工厂」，这套规则对 Phaser 多文件源工程完全反转。所以真正的功夫不在框架接缝，而在这些重写面加 net-new 的多轮 ReAct / Workspace / Service（Phase B）。 + +这条边界还连着一处口径的精确化（创始人 2026-06-23 裁）：两线分立、不收敛。旧的边界叫「能力档（声明式 vs 自治）」，但 A-model 分支已经让廉价线也走向自治写真 JS，所以旧口径过时了。新口径是「引擎 / 表现层复杂度档」——A-model 吃 LittleJS 轻量经营档，tier2 吃 Phaser 重表现富游戏档。两条线各吃各的市场、各跑各的运行时，运行期零依赖。amodel-gen 合并 dev/2.0.0 之后，tier2 的循环范式以合并后版本为参照系重取，种子仍是 Python 的 `studio.py`，amodel-gen 只作 JS 参照、不照搬。 + +## 3 图清单与状态表 + +| # | 图名 | 形式 | 状态 | 覆盖内容 | +|---|---|---|---|---| +| C1 | 单写 ReAct 循环 | SVG | 建（演进自 WG1 studio.py） | reason→act→observe 三角；WG1 单轮+repair vs tier2 内多轮两态并列；验收门笼子（读文档→写源→build→快检→九门 L1→verdict→改）；九门实线承袭、自治内循环虚线待建；单写者只指阶段 2、阶段 1 仍多 agent；底部四道熔断红框引子 | +| C2 | M3 Anthropic 原生接法 | SVG | 建（接法走官方 AnthropicChatModel，2.0.3 已核） | 主链路 agent→AnthropicChatModel→base_url 指 new-api→MiniMax-M3；用对 M3 三要点（原生协议+工具循环 / thinking 分离 / 完整 response 保留）；红框警示旧用法=60% 失败最深根因；new-api 统一计费平面、协议不锁死 | +| C3 | 四道熔断 + 预算闸 | SVG | 建（软刹官方现成、三道硬熔断+强制硬闸自建待落） | 四道熔断（步数硬顶 / 预算闸 / 卡死探测 / 双层超时）；预算闸=官方软刹实线 best-effort、非强制硬闸（设计缝）；卡死探测防 Goodhart；中间件洋葱叠加机制；spike 阶段先只挂官方软刹的退路 | +| C4 | 多轮自治范式（承 amodel-gen） | SVG | 建（范式承 A-model 已落、tier2 fork 演进待建） | 三态演进带（studio.py 单轮 → amodel-gen 多轮 → tier2 Phaser 富游戏）；三件可复用范式（done 门 / check-build 快反馈 / 历史压缩）映射 U2/U7；fork 演进≠平移（6 符号兼容是版本钉、validate/run/prompt/roles 是 net-new 重写）；两线分立不收敛、边界精确为引擎/表现层复杂度档 | diff --git a/docs/architecture/架构/生成引擎/tier2细节图说-D-三层校验与九门.md b/docs/architecture/架构/生成引擎/tier2细节图说-D-三层校验与九门.md new file mode 100644 index 00000000..79dd4fab --- /dev/null +++ b/docs/architecture/架构/生成引擎/tier2细节图说-D-三层校验与九门.md @@ -0,0 +1,100 @@ +--- +date: 2026-06-23 +topic: tier2 细节图说 · D 族——三层校验与九门(生成引擎子树·tier2) +status: 设计中(tier2 待 spike) · 每图映射源档见该图脚注 / frontmatter 记 hash 作防漂移门 +映射源档: + - path: docs/architecture/架构/生成引擎/tier2实现详设.md + hash: d5efe45f + - path: docs/architecture/架构/生成引擎/自治富游戏引擎.md + hash: 4858e6cf + - path: docs/architecture/架构/生成引擎/tier2四层工程架构.md + hash: d5efe45f + - path: game-runtime/games/_wg1-gen/_shared/play.cdp.cjs + hash: 9d463f08 + - path: docs/plans/2026-06-22-003-feat-tier2-富游戏自治生成线-plan.md + hash: ccb00bb9 +--- + +# tier2 细节图说 · D 族 —— 三层校验与九门 + +> 本篇是绘境AI 架构图集 **生成引擎子树** 下的 tier2 细节图说,只覆盖 **D 族(三层校验与九门验收)** 五张图。生成引擎主干、tier2 总览、agentic 运行时各有自己的图说;这里专门把「一款生成出来的富游戏算不算过关」这件事画清楚。 + +--- + +## 0 阅读约定与同步纪律 + +D 族讲的是 tier2 富游戏自治生成线的验收骨架——从最顶层的三层校验框架,一路下到现行九门、富游戏专属新门、advisory 分级机制,再到把这套门从 LittleJS 搬到 Phaser 要付的工程代价。五张图映射四份属主设计档加一份探针源码:三层校验的口径出自《tier2 实现详设》和《自治富游戏引擎》(后者已升到三层口径),九门的精确判据和阈值出自《tier2 实现详设》的「过门判据」与「靶子 mini-肥鹅」两节,advisory 分级的真实落地证据出自现行九门探针 `play.cdp.cjs`,Phaser 重写与沙箱底座的工程序列出自 `2026-06-22-003` 计划的 U3/U6。frontmatter 记了这五份的当前 commit hash,作为防漂移门——其中任一份动了验收口径,本图说与对应 SVG 必须同步改。 + +整条 tier2 富游戏线现在 **整体待建**:0号 spike 还没跑,引擎没搭,门没重写,代码一行没落。所以 D 族里几乎所有「新机制」都是设计已出、尚未落地的状态,绝不能因为图画得齐整就误以为已经建好。有承袭、不全是新建的部分,用实线画,但这里要把两层承袭分清,别一概当「主干现行」。现行九门 harness 在 LittleJS 廉价线上判了大量游戏,是真跑了很久的底座,这部分确是主干现行。它内置的「driven 感知 advisory 分级」却要单独说清出处:这是 A-model 分支(`feat/mac-amodel-foundation`)近期给九门加的增强,在那条分支上已实现,但尚未合并到 dev/2.0.0 主干——本仓 docs/tier2-plan 的 `play.cdp.cjs`(frontmatter 记的 9d463f08)还是用各门 SKIP 标志达成同义降级,字面 advisory 块要等 A-model 合并后才进主干。图里 advisory 用实线,表的是「它已被实现」(A-model 线),不是「已在主干」;严格按状态码,从主干看它是「接」(待合并对账),tier2 实现时以 A-model 合并后的版本为准。tier2 自己要做的全是把这套哲学搬到 Phaser、再在九门之上补富游戏专属的几道门,这部分用虚线画。看图时记住这条对照:**实线 = 已实现(主干现行的九门,或 A-model 分支已落待合并的 advisory);虚线 = tier2 专属、待 0号 spike 验证后才落代码的新机制。** + +## 1 全图通用图例 + +D 族用一套统一的徽章和线型,先在这里讲清,后面每张图不再重复。 + +**层级徽章**标的是一道门落在三层校验的哪一层:绿色 **L1** = 硬约束层(编译 / 启动 / 运行错误,必须解决、循环);蓝色 **L2** = 设计符合层(玩法 / 关卡 / UI vs 设计,尽量解决);橙色 **L3** = 效果层(美观 / 好不好玩,只评分、绝不阻塞)。**处置徽章**标的是这道门怎么处置:红色 **硬** = 硬门(不过即拒发),橙色 **无 driver 降 advisory** = 条件门(被驱动时致命、没被驱动时只报告)。另有几个生产维度徽章在个别图上点到:**质量**(绿)、**可靠**(绿)、**安全**(红)、**可观测**(蓝)、**数据**(灰)。 + +**线型**承担状态语义。实线框 = 现行已落,虚线框(短划线)= tier2 专属待建。实线箭头 = 现行已有的转移 / 关系,虚线箭头 = tier2 待建的流程或重写映射。 + +**状态码**四个,贯穿生成引擎子树:**现** = 现行已建在跑;**接** = 设计已出、代码待接线;**建** = tier2 立项后要新建、当前待 spike;**缓** = 收窄后缓做。D 族绝大多数元素是「建」,九门 harness 与 advisory 分级是「现」。 + +## 2 图集 + +### 图 D1 · 三层校验全景 + +![图 D1 三层校验全景](assets/t2-D-01-三层校验全景.svg) + +一款生成出来的富游戏算不算过关,在 tier2 里不是一个笼统的「过了九门就行」,而是按创始人定的三层校验来判,三层各管一档、处置力度截然不同。这张图把三层并排铺开,关键在于让人一眼看出它们的处置差异,而不是把它们当成同一种门的三个名字。 + +最底下的 L1 是硬约束层,管的是编译、启动、运行错误这类客观事实——游戏 boot 不起来、跑着跑着抛异常、画面是死的,这些都是真问题,**必须解决,而且循环逼到解决为止**。判它的全是确定性信号:构建日志、浏览器 console、CDP 错误捕获、九门探针,机器说了算,零 LLM 参与判定。绘境现行那套「在真浏览器里真玩一遍判能不能玩」的九门,绝大多数落在这一层。中间的 L2 是设计符合层,管的是玩法和关卡实现得对不对、UI 有没有缺组件、品类约定有没有违反,处置是「尽量解决」而非死循环,靠的是确定性的设计符合度信号(九门里的机制进展 H_progress 就落这层)。L2 的拒发权不是天生就有,而是 observe → enforce ——先只观测、积累信号,等这道门在真实数据上证明自己判得准,才赋予它拒发权。最上面的 L3 是效果层,管特效、美观、好不好玩,处置是 **只评分、绝不解决、绝不阻塞拒发**,工具是 M3 多模态视觉软检(看截图打分),产出只进质量趋势、告警、给人工终审减负。 + +为什么 L3 死活不让它当门,是这张图最该让人记住的设计取舍,底部那条铁律带说的就是这件事。两个极端都不能取:把确定性门扩到能自动判「好不好玩」,会得到一堆能被刷的代理指标——同一套机制门下,精心做的打砖块和「摆三块砖点一下就赢」的退化品都能全绿,门就废了;反过来纯靠 LLM 当玩家裁判判好玩,又踩了 Goodhart 红线(优化代理指标反而偏离真目标),因为模型一旦进验收当裁判,会学会把游戏优化成「让裁判说好」而不是「真的好」。所以效果只评分、不当门,好不好玩最终归人工终审。还有一条迭代原则同样要紧:**初期只焊死 L1,L2/L3 渐进做,绝不让效果问题阻塞真问题**——一款刚生成的富游戏,先把「能不能运行」这件硬事判死,美不美观是后话;用户也可以经 HITL 主动要求继续解决任意层。整套三层在 tier2 里都还是待建状态,spike 初期只焊 L1。 + +### 图 D2 · 九门逐门 + +![图 D2 九门逐门](assets/t2-D-02-九门逐门.svg) + +L1 那层「确定性归机器」的主体就是九门。这张图把九道门逐道拆开,每道门讲四件事:测什么、用什么探针手段、落 L1 还是 L2、是硬门还是条件门。读这张图的正确方式是把它当成 L1 的施工细节——D1 给的是三层的处置哲学,D2 给的是这套哲学在最底层具体怎么落成九个可机器执行的检查。 + +九门覆盖的是一款游戏从「能不能起来」到「玩起来正不正常」的完整链条。A_boot 判游戏能不能 boot 起来(navigate 后轮询 boot 信号);B_uncaught 判运行期有没有未捕获异常(console 加 CDP 错误监听);C_frame 判帧在不在推进、有没有卡死(前后两次取帧号差大于零);D_render 判画面有没有真实内容(截图回读亮像素阈值);E_live 判画面在不在变、是不是静止帧(对多帧取 FNV hash 去重);F_wiring 判逻辑是真调引擎还是空桩(查引擎 API 的调用前缀有没有出现);G_input 判注入输入后状态有没有变化(注入 input 再读 gameState 前后对比);H_progress 判核心机制有没有真进展(driver 驱动加玩后断言,含 latch 终态);I_control 判控制响应跟不跟手(输入到反应的时序在阈值内)。九门里只有 H_progress 落 L2(它判的是机制实现 vs 设计,属设计符合),其余八门都落 L1;E_live 和 H_progress 还带一个「无 driver 降 advisory」的条件标记,这正是下面 D4 要展开的分级机制。九门全绿等于机制地板通过、可发。 + +这套九门为什么对 tier2 重要,在于它把「做完了」这件事钉死在客观证据上,绝不让 LLM 给自己打分——这是防 Goodhart 的机制地板。但要看清一条现行与远期的边界:**现在这九门是为 LittleJS 廉价线建的,所有探针钩子都硬编码了 LittleJS 专属取法**(`#game-engine` 选择器、`window.__engine.snapshot().frame` 帧源、`__gameHostEngineInitFired` boot 信号)。tier2 复用的是「真玩判定加零自评」这套哲学,不是这套代码——探针要为 Phaser 整个重写,并且在九门之上再补富游戏专属的几道门(跨表联动、经济、latch,见 D3)。图底那条脚带把这件事点明:这是「重写适配层、不是参数化一键切」,而沙箱底座选型(直接复用现有 CDP,还是用 agentscope-runtime 的 BrowserSandbox)是 spike 开跑前必须先出结论的前置阻断项。 + +### 图 D3 · 富游戏专属确定性门 + +![图 D3 富游戏专属确定性门](assets/t2-D-03-富游戏专属门.svg) + +九门是为「超休闲单局」量身定的机制地板——它确定性地判一款单场景小游戏能不能玩,但它不查跨系统接线。富游戏的本质难点恰恰在跨系统:像 mini-肥鹅 这样的经营游戏是合成、资源、订单三个系统耦合在一起,光过九门远远不够,还得确定性地证明「三个系统真接上了」「经济的盈利和破产两条路都真能跑到终态」「赢输的终态真落定」。这张图就是在九门之上补的三道富游戏专属门,整图全是 tier2 待建(虚线),待 0号 spike 验证后才落代码。 + +第一道是 **三联动门**,管跨系统接线,要证三个系统是真耦合而非三座孤岛。它的判据是确定性的、静态加真玩混合:订单的 requires 必须能被合成系统产出的物品满足(这是一次跨表可达性检查,静态地从 mergeChains 推到 orders),合成链必须是有向无环图(对 mergeChains 做拓扑检查、不许成环),完成订单时必须真调资源系统的 addCoins,合成消耗时必须真调资源系统的 consumeIngredient。第二道是 **经济门**,管数值经济闭环——一个真正的经营游戏既要能赢也要能输,所以这道门要 harness 用真输入把两条路都驱动到终态:可盈利的路径是金币从开局 20 经「合成→交单→收金币」的正循环攒到 100 判赢,可破产的路径是连续三个订单流失(只合成不交单或经济崩盘)判输。关键约束是这两条路都得能被 harness 的真输入驱动跑到终态,不能只是「在数据表里能算出来」——能算和能玩到是两回事。第三道是 **latch 门**,管终态落定:赢或输一旦落定就不能回弹,而且宿主要能读到终局。这道门承接现行宿主装载那条已经验过的约束——游戏没有 emit 通道,所以终态必须焊成一个可轮询的 latch,由宿主轮询去读,而不是靠游戏主动 emit。 + +这三道门和九门的关系,图中间那条「九门(实) + 三门(虚) = tier2 的 L1 机制地板」的式子讲得最清楚:九门是超休闲地板,三门是富游戏接线地板,两者合起来全绿,才算富游戏的机制地板通过。底部那条带把这三道门钉到了一个确切的靶子上——mini-肥鹅。它是 spike 对照组的施工图:3×3 合成棋盘加资源系统(金币加食材库存)加 3~5 个带耐心的顾客订单,内容量定在 12 个物品、6 条合成链、5 个订单模板、2 种货币,砍到能证、又保住多系统耦合 / 重 UI 表现层 / 数值经济闭环这三个本质难点。这三道门的 assertAfterPlay 规格就是照这个靶子写的,driver 也按「点合成格→凑齐订单物品→交单→看金币涨」的确定性序列预建,产出复用 game-e2e-cdp-harness 的四件套证据(render→截图时序→驱动→verdict)。 + +### 图 D4 · driven 感知 advisory 分级 + Goodhart 隔离 + +![图 D4 driven 感知 advisory 分级与 Goodhart 隔离](assets/t2-D-04-advisory分级与Goodhart隔离.svg) + +九门里有两道门——E_live(画面在变)和 H_progress(机制有进展)——只有在游戏真被人驱动起来的前提下才判得公平。一款游戏如果根本没人给它输入,画面本来就该是静的、机制本来就没进展,这时候硬判它 E_live / H_progress 不过,是冤枉它。这张图的上半部分画的就是解决这个冤案的机制:**driven 感知 advisory 分级**,它承接 A-model 分支、创始人 2026-06-22 裁定,在那条分支上已实现(实线表其已落)。按 §0 那条 branch 说明,它还没合并到主干——从 dev/2.0.0 看是「接」(待合并对账),tier2 以 A-model 合并后的版本为准。 + +机制是一个两态的判断:当 spec 既没有 driver 也没有非空 inputs 时,driven 为 false——游戏没被驱动,无法公平评判可玩性,于是 E_live 和 H_progress 降为 advisory(仍然跑、仍然报告,但不计入 pass),硬门只剩七道(A/B/C/D/F/G/I);一旦 spec 给了 driver 或给了 inputs 序列,driven 变 true,这两道门自动恢复致命、九门全部计入 pass,而且不用改一行代码。一句话概括就是「driver 缺位则降 advisory,driver 到位则恢复致命」。这个范式对 tier2 不只是搬过来用——tier2 修 latch 门和经营门时复用的正是它:先 observe(只观测、积累信号),等 driver 到位、判据证准了再 enforce(卡死)。把「先观测后卡死」做成可控的状态转移,而不是一上来就硬卡,是这套分级真正的价值。 + +图的下半部分是 tier2 的第二段「开放自产 driver」,整段待建(虚线),它要解决一个比上半部分更危险的问题。第一段 spike 的 driver 是人预建的,纯测模型变量;第二段要放开,让自治 agent 自己产或扩 harness 的 driver,以测它的自治上限。但这里埋着一颗 Goodhart 雷,就是图底那条红线铁律说的:**写者不能写判自己游戏的那张卷子**。agent 既造游戏又造判它的 driver,会自然而然地把 driver 写成只盖它走过的路、只读不暴露真实力的字段,然后全绿——假绿。隔离手段是把「写卷人」和「判卷人」拆开,走三层:agent 提议 driver 后,平台先按 schema 和白名单编译(只许声明式合法形态过,非白名单或越界字段直接拒),再交独立 adversarial 评审(一个不向着被评对象、专找漏洞的评审,查它是否覆盖真实玩家路径、是否读了作弊字段以避开真考验),三层全过这个 driver 才入验收,任一层不过就退回 agent 重提。为了让这道隔离可观测,第二段还专门采集两个指标:自产 driver 被独立评审打回的比例、driver 被修改的次数(防它靠反复改 driver 来逃避卡死探测)。 + +### 图 D5 · CDP 探针 Phaser 重写 + 沙箱底座 + +![图 D5 CDP 探针 Phaser 重写与沙箱底座](assets/t2-D-05-CDP探针Phaser重写.svg) + +九门的探针机制(真浏览器真玩加确定性判定)在 tier2 里不变,但它的引擎钩子全是 LittleJS 专属的,要为 Phaser 重写。这张图最该破除的一个误解是「换引擎只要改个参数」——它不是。整图待建(虚线),核心是一张「引擎钩子重写映射」表,左边是探针现在硬编码的 LittleJS 取法(实线、已落),右边是 tier2 要为 Phaser 重写的等价钩子(虚线、待建),每一行都要各自重写,中间那条虚线箭头标的就是「重写」而不是「切换」。 + +要重写的钩子有四条。第一条是 canvas 选择器:现行用 `#game-engine` 做像素回读和触摸坐标映射,Phaser 自己挂 canvas、id 不同,选择器和坐标映射都得按 Phaser 视口重写。第二条是帧源:现行 C 门读帧 delta、G 门把对照实例推进到同帧号,都读 `window.__engine.snapshot().frame`,Phaser 的帧驱动机制不同,得另找一个单调递增的帧计数替代它。第三条是 boot 信号:现行 A 门轮询 `__gameHostEngineInitFired` 判引擎接管完成,Phaser 的 boot 序列独立(scene create 完成),得另置一个「引擎已起、可真玩」的就绪标志。第四条是输入注入加状态读取:现行 tap/key 注入加 `__gameState` 读取(经 _forensicsView 导出)支撑 G 门和 H 门,Phaser 的输入投递路径和可测性接口要重接,而富游戏的 state 还要走经营门那套约定导出。这四条逐条重写,不是一个参数切过去——这是这张图反复强调的判断。 + +图底两个框讲的是这件事的两个边界。左下角的沙箱底座框是一道 **spike 前置阻断验证**:先做个小验证,看 agentscope-runtime 的 BrowserSandbox 暴露的 page.evaluate / CDP 能力够不够(navigate / screenshot / 输入注入逐项可用),够就直接用它跑探针矩阵,不够就回落到自建薄沙箱加复用现有 `play.cdp.cjs` 的路。这道结论必须在 U7 生成迭代开跑前出来——出不来,整个 spike 跑不起来,所以它是属主标记的前置阻断项。右下角的「第一版克制」框讲的是另一种纪律:第一版只参数化九门 harness 的引擎钩子(canvas 选择器、帧计数源),把 Phaser 的 RAG 和脚手架硬编码进 worker,通用能力包接口(skill / mcp / tool / rag / 脚手架)暂不建满。理由很实在——现在只有 Phaser 一个真实现,接口形状会被它一个人反向决定,等第二个引擎(Pixi)落地、有两个实现做依据,再抽真正的能力包接口才不会白抽。这是一个有意的「先别抽象」决策,不是没做完。 + +## 3 图清单与状态表 + +| # | 图名 | 形式 | 状态 | 覆盖内容 | +|---|---|---|---|---| +| D1 | 三层校验全景 | SVG · 分层卡片 | 建(tier2 待建 · 初期只焊 L1) | L1 硬约束 / L2 设计符合 / L3 效果三层的内容、处置、工具包、谁判;三条铁律(机器判确定性、L3 只评分防 Goodhart、初期只焊 L1) | +| D2 | 九门逐门 | SVG · 九宫格 | 现(九门=LittleJS 现行)/ 建(tier2 Phaser 重写探针) | A_boot/B_uncaught/C_frame/D_render/E_live/F_wiring/G_input/H_progress/I_control 逐门的测什么 / 探针 / 落 L1 还是 L2 / 硬门 or advisory | +| D3 | 富游戏专属确定性门 | SVG · 三门卡片 + 关系式 | 建(tier2 待建 · 经营品类专属) | 三联动门(跨表可达 + DAG 无环) / 经济门(盈利破产双路径到终态) / latch 门(终态落定不回弹);九门 + 三门 = tier2 L1 机制地板;靶子 mini-肥鹅 与 assertAfterPlay 规格 | +| D4 | driven 感知 advisory 分级 + Goodhart 隔离 | SVG · 状态机 + 流程 | 接(advisory 分级=A-model 分支已落·待合并 dev/2.0.0)/ 建(自产 driver 三层隔离=第二段待建) | 上:无 driver 两门降 advisory、有 driver 恢复致命的两态转移(observe→enforce 范式源);下:自产 driver 走编译 / 独立 adversarial 评审 / 通过才用的三层隔离防 Goodhart + 两项采集指标 | +| D5 | CDP 探针 Phaser 重写 + 沙箱底座 | SVG · 重写映射表 + 二分 | 建(tier2 Phaser 重写探针 + 沙箱底座 spike) | 四条引擎钩子(canvas 选择器 / 帧源 / boot 信号 / 输入加 state)的 LittleJS→Phaser 重写映射;沙箱底座 spike 前置阻断(BrowserSandbox vs 回落 CDP);第一版克制(只参数化钩子、不抽满能力包接口) | diff --git a/docs/architecture/架构/生成引擎/tier2细节图说-E-能力面skills与prompt.md b/docs/architecture/架构/生成引擎/tier2细节图说-E-能力面skills与prompt.md new file mode 100644 index 00000000..aac113ba --- /dev/null +++ b/docs/architecture/架构/生成引擎/tier2细节图说-E-能力面skills与prompt.md @@ -0,0 +1,110 @@ +--- +date: 2026-06-23 +topic: tier2 细节图说 · E 族——能力面（skills 清单 / 引擎能力包 / prompt 两阶段角色 / A-model 插件复用） +status: 设计中（tier2 待 spike）· 每图映射源档见脚注 · 通用读法见本篇 §0/§1 +映射源档: + - docs/architecture/架构/生成引擎/tier2实现详设.md @ d5efe45f + - docs/architecture/架构/生成引擎/自治富游戏引擎.md @ 4858e6cf + - docs/plans/2026-06-22-003-feat-tier2-富游戏自治生成线-plan.md @ ccb00bb9 + - tier2/HANDOFF.md @ ccb00bb9 +--- + +# tier2 细节图说 · E 族 · 能力面：skills 与 prompt + +> 🚧 设计中 · tier2 是待 0号 spike 验证的假设,尚未落代码;过了 spike 才进建设。 +> 本族四张图回答同一个层面的问题:**单写 agent 手里握着什么、引擎以什么形态交给它、谁在哪个阶段写、上一条廉价线已经造好的资产怎么接住。** 整轨的生命周期与对象结构画在《[agentic 运行时架构图说](agentic运行时架构图说.md)》,本族只放大其中的能力面。 + +--- + +## 0 阅读约定与同步纪律 + +E 族映射四份源档:tier2 实现详设的 §「运行时形态:两阶段、service 化与 session 三路径」和 §「前置物清单」,自治富游戏引擎的 §「引擎是能力包,不是底座」和 §「换一种生成方式」,实现计划的 §「与 A-model 分支的关系」,以及 tier2/HANDOFF.md 的 §「与 A-model 分支的协调」。frontmatter 里记了这四份的当前 commit hash,作为防漂移的对账锚——设计一变动,本图说与对应 SVG 必须连同 hash 一起同步更新。 + +整族都还没落代码,所以"状态"这一维度贯穿每张图,绝不能把待建的东西画成已建。tier2 的整条轨待 0号 spike 验证才决定要不要正式投入,因此本族凡是 tier2 专属的新机制一律画虚线、标"建";凡是承袭现行廉价线已经跑着的东西(九门 harness 的钩子机制、A-model 改过的探针分级范式、A-model 已造的插件契约)画实线、标"现"或"接"。看图时先认线型再读内容:实线 = 有真实现可承袭,虚线 = 还要照这份设计去建。 + +E 族里只有图 E4 涉及第三种状态。它讲的是 tier2 怎么接住 Mac 那条 A-model 分支已经造好的资产,所以整图基调是"接"——既不是 tier2 从零新建,也不是现行产线已落,而是把一份在飞分支的产出对账过来复用。这个区别在图里用底色和线型分开标。 + +## 1 全图通用图例 + +**状态码**(贯穿全族,决定线型):**现** = 现行廉价线已落、tier2 直接承袭(实线);**接** = 复用 A-model 已造资产、合并后对账(实线框 + 接的底色);**建** = tier2 专属新机制、待 spike 后落代码(虚线框 + "建"小标);**缓** = 排在更后、本族未出现。 + +**工具角色徽章**(图 E1 用):**核心环**(`#2563eb`)= ReAct 写-构-验主回路上的工具;**取证**(`#b45309`)= 只喂软检与人审、绝不进硬门判定;**起手收尾**(`#16a34a`)= 一次 session 的开头铺骨架、结尾吐源工程。 + +**五件套维度徽章**(图 E2 用):**质量**(`#15803d`)标在 skill 与 rag 上,因为这两件直接抬高模型写对的概率。 + +**两阶段维度徽章**(图 E3 用):**伸缩·多 agent**(`#7c3aed`)= 阶段 1 工作室靠多个设计 agent 发散;**数据·只读探**(`#475569`)= 设计 worker 只读不写;**质量·单写防冲突**(`#15803d`)= 阶段 2 收敛到单写。 + +**复用维度徽章**(图 E4 用):**数据**(`#475569`)= 复用引擎无关的契约与命名;**质量**(`#15803d`)= 渲染实现按 Phaser 重做、不降级;**成本**(`#16a34a`)= 不重新发明、省掉 Mac 那边重复造轮子的工时。 + +实线箭头(承袭现行)与虚线箭头(待建机制)在图 E3 的拓扑连线里也用同一套语义。 + +## 2 图集 + +### 图 E1 · 单写 agent 的 toolkit(阶段 2 · skill 清单) + +![图 E1 单写 agent 的 toolkit skill 清单](assets/t2-E-01-skills清单.svg) + +这张图把阶段 2 单写 agent 的工具箱摊开,逐个交代每个工具的目的、边界、产出。看它要先抓住一个形态:这不是一条流水线,而是九个工具围成的一圈自治内循环——写源文件、构建、跑一道便宜快检、跑真玩门、读门的裁决、据裁决再改,绕回写源,直到收敛或熔断触发为止。agent 不按固定顺序走完九步,而是每一轮"想一步、调一个工具、看结果",由它自己决定下一个调谁。所以这九个工具是 ReAct 循环的工具面,不是阶段图。 + +工具按角色分三类,这层分类才是设计要点。核心环的六个(写源、构建、快检、跑门、读裁决，以及作为收尾的 finish)是主回路上真正驱动迭代的;取证类的截图和查资产是喂给软检与人工的辅助;起手收尾类的模板初始化和 finish 各管一次 session 的开头和结尾。把截图单独划成取证、不让它进 L1 判定,是一条故意设的边界:一旦让模型看截图来给自己的游戏打分、又拿这个分当过关依据,模型会很快学会把游戏优化成"在截图里好看"而不是"真的能玩"。验收要靠 run-gates 在真浏览器里真玩一遍、机器确定性地判,截图只能用来给人减负和 debug。 + +九个工具里 write-source 是整轨最深的赌注所在。它写的是那 56% 的表现层——逐像素手画的场景和 UI、点击命中、这款游戏独有的规则,既压不成数据表也压不成骨架,只能 LLM 现写,也最容易崩。其余八个工具大半是在给这一件兜底:build 把源工程打成可玩 bundle,headless 在跑全套真玩门之前先做一道便宜快筛、能早断就别浪费一整轮真玩,run-gates 才上确定性的九门加三联动门加经济门加 latch,read-verdict 把裁决喂回循环让 agent 知道该改哪。 + +脚带那三条边界铁律是这张图最该让人记住的设计约束。第一条单写独占——整个工程只允许一个 agent 写、绝不并行拆,因为经营游戏的多个系统共享同一套状态,拆给并行 agent 几乎必然写出互相矛盾的结果(一手教训是曾经把"造 Flappy Bird"拆并行,背景跑成了马里奥)。第二条 finish 与源项目契约共用一份 schema——agent 交付时吐出来的形状,必须就是落库取回时认的那个形状,两边各写各的迟早对不上。第三条验收零自评,就是前面说的那条防 Goodhart 红线。 + +图底那条虚线点明本族最大的待建项:这九个工具现在只是概念清单,它们的 Phaser 实现(esbuild 构建 profile、Phaser harness 的钩子)都还没写。第一版打算先把 Phaser 硬编码进 worker,等第二个引擎落地、有两个实现做依据,再去抽通用的能力包接口——这正是图 E2 要讲的克制。 + +*(图源:tier2实现详设.md §运行时形态 / §前置物清单 · 自治富游戏引擎.md §引擎是能力包 · plan U2/U5)* + +### 图 E2 · 引擎能力包 manifest(五件套) + +![图 E2 引擎能力包 manifest 五件套](assets/t2-E-02-引擎能力包manifest.svg) + +这张图回答一个容易想偏的问题:引擎在 tier2 里到底是什么。直觉会把引擎当成"一次选定、所有游戏都长在上面的固定底座",像现行廉价线选了 LittleJS 那样。tier2 故意不这么做。在这套架构里引擎是动态加载的能力包:每个引擎对应一套给 agent 用的五件套——skill、tool、mcp、rag,外加一份起手脚手架。换引擎,对 agent 来说就是换掉"我手里有哪些工具能调"的那一组,不是架构重写。这个设计的好处是它顺着 agent 的工作方式来——agent 本来就是按"我能调什么工具"来干活的,把引擎做成一套工具集,换引擎的代价就被压到了换工具集而非重写主干。 + +五件套各管一面。skill 是这一引擎下"如何做某一类事"的固化 playbook,把对的写法沉淀下来、少让模型现场摸索;tool 就是图 E1 那九个工具,它们的引擎实现按引擎重写;mcp 经模型上下文协议把引擎侧能力标准化地暴露成可调接口;rag 是引擎文档加范例的检索增强,补模型训练数据里这个引擎的密度——模型见这个引擎的代码越多,自治循环里就越少漂、越少编不存在的 API;脚手架就是模板初始化铺的那套工程骨架,等于平台预建的那 25%,给单写 agent 一个先天能过 boot 的起手点。skill 和 rag 标了质量徽章,因为这两件直接决定模型写得对不对。 + +图里那个紫色块"换引擎 = 换一套加载的工具集"是核心论点的落点:Phaser 能力包和 Pixi 能力包对 agent 只是两套不同的工具集,切换它不动两阶段角色、也不动三层校验主干。首批两个引擎里 Phaser 有真实现,Pixi 当前留桩。 + +这张图整体状态是"建",而且它最该让人看清的是那个克制警示——第一版不把五件套建满。如果一上来就把 skill、tool、mcp、rag、脚手架五件全建成抽象接口,而实际只有 Phaser 一个真实现、Pixi 只是个桩,那接口的形状会被 Phaser 这唯一的实现反向决定,等真去接第二个引擎时多半得改。真正的能力包接口要等第二个引擎落地、有两个实现做依据再抽,不为一个实现先建抽象。所以实验阶段只做两件最小的:把九门 harness 的引擎钩子(canvas 选择器、帧计数源)参数化,把 Phaser 的 rag 和脚手架硬编码进 worker,先把这一个引擎跑通。 + +图底那条绿条标出承袭现行已落的实线部分:九门 harness 的钩子机制本身、A-model 那套 driver 感知分级,都是现行 LittleJS 廉价线已经建好的,tier2 复用它们的哲学、为 Phaser 重写实现,而不是从零新造。 + +*(图源:自治富游戏引擎.md §引擎是能力包不是底座 · tier2实现详设.md §运行时形态)* + +### 图 E3 · prompt 两阶段角色 + +![图 E3 prompt 两阶段角色](assets/t2-E-03-prompt两阶段角色.svg) + +这张图回答"谁在哪个阶段写",并破除一个常见误读:tier2 不是只有一个 agent。它分两阶段,两阶段的 agent 形态故意相反。阶段 1 是工作室设计,用 Agent Team 星形多 agent:一个 leader 分析并拆解用户意图,经 AgentCreate 拉起玩法、关卡、数值、UI、音乐、特效、资产等设计 worker 去发散,再经 TeamSay 把各路结论汇回 leader 收敛成一份设计结论。这一阶段只读加对话——设计 worker 用 PermissionMode.EXPLORE 只读已有工程代码和工程内的设计文档(迭代已有游戏时会用到),并能与用户跨 session 多轮对话,但不写代码。阶段 2 才是单写实现:模板初始化工具铺骨架,把阶段 1 每个设计 agent 的结论写成工程内文档,然后单写 agent 跑 ReAct 多轮写代码,过三层校验,产出一个真 Phaser 源工程。 + +为什么设计用多 agent、实现用单写,这是两阶段角色最该讲清的道理。设计阶段要的是发散和专业分工,多个 worker 各管一个方面、把可能性铺开,leader 再收敛,这时候多 agent 是优势。实现阶段恰恰相反:经营游戏的多个系统共享同一套状态和约定,如果拆给并行 agent 同时写,几乎必然写出互相不一致的结果,所以实现必须收敛到单写、由一个 agent 持有整个工程的全局视图。图里那个红框拓扑铁律点出了星形的硬约束——worker 只拿到 TeamSay、只能把结果报回 leader,禁止 worker 之间互评或互相喊话,所有协调都过 leader 这个唯一的中心。 + +红框里还钉了一条容易踩坑的事实:AgentScope 2.0.3 删掉了进程内的 MsgHub 和 pipeline 编排,进程内多 agent 协作那套已经没有了,留下的只有部署态的 Agent Team(TeamCreate / AgentCreate / TeamSay)。工作室必须建在这套 Agent Team 上,而不是去找一个已经不存在的 MsgHub。图里阶段 1 和阶段 2 的内部拓扑都是照 2.0.3 源码逐条核过画的(`/root/oss/agentscope`),就是为了免得照旧版资料把架构画错。 + +底部那条蓝带补一句血缘:prompt 生成域承袭现行 studio.py 的多角色 prompt(design / code / fix),tier2 复用它的多角色 prompt 和生成域躯干,是 fork 起步、独立演进,不是照搬。整图的 tier2 专属机制(Agent Team 星形、单写 ReAct 多轮)都画虚线待建,承袭现行的(九门 harness、A-model)画实线。 + +*(图源:tier2实现详设.md §运行时形态:两阶段、service 化与 session 三路径 · 自治富游戏引擎.md §换一种生成方式 + §谁在写:单写者 ReAct)* + +### 图 E4 · A-model 4 插件复用 + +![图 E4 A-model 4 插件复用](assets/t2-E-04-Amodel插件复用.svg) + +这张图讲 tier2 怎么接住 Mac 那条 A-model 分支已经造好的资产,别重新发明。先要理清两线的关系。A-model 是 Mac 在做的 Tier1 廉价线 agentic 优化,它把廉价线从"声明式数据壳"推进到了"便宜模型自治写真 JS",所以两线的边界不再是过去那个"声明式 vs 自治"的能力档,而是创始人 2026-06-23 重定的引擎/表现层复杂度档:A-model 吃 LittleJS 轻量经营档,tier2 吃 Phaser 重表现富游戏档(肥鹅美食街那一档)。两线分立、不收敛,但 A-model 已经造好的几样东西 tier2 该接住,省掉重复造轮子。 + +复用的逻辑落在一条论点上:A-model 的 api.d.ts 是引擎无关、零语义的契约,跨得了引擎;而渲染实现绑死在 Canvas 上、跨不了引擎。所以图里那四个插件(scene-fsm 场景状态机、hud-ui 界面、session-score 局内计分、timer-scheduler 定时调度)tier2 都复用它们的契约和命名,只把渲染实现按 Phaser 重做。这就是每张插件卡上那两个徽章的含义——契约复用是数据维度的承袭,渲染按 Phaser 重做是质量维度不降级。横在下面的 sim-business 经营配方卡同理,它是经营和合成的系统骨架配方(数值与系统结构,不是渲染件),tier2 复用配方、用 Phaser 落地数值。 + +图里还有两块讲接缝怎么对账。九门基线那块:A-model 改过 play.cdp.cjs,加了 SAA-mode 的 __GameBundle 信封、driven 感知的 advisory 分级("driver 缺位就降为只提示、driver 到位就恢复致命")、还有取证用的 _forensicsView。tier2 在 U3/U6 复用它那套分级范式来修 latch 与经营门的 observe→enforce,但 fork 的源和行号锚点要钉到 A-model 合并进 dev/2.0.0 之后的版本重取,而探针本身要为 Phaser 重写——#game-engine 选择器、__engine.frame 帧源、boot 信号全换,这部分是虚线待建。源项目契约那块:A-model 把 source-project.schema.json 升成了 oneOf(1.0/2.0),但它的 2.0 绑死了 __GameBundle 加九门加 ECS-lite 那条 LittleJS 装载路;tier2 的 Phaser 工件走的是另一条装载序列(第二装载分支),所以另立一份独立 schema、不把 3.0 变体加进同一个 oneOf——这是为了避免把 Phaser 的差异焊进 LittleJS 的 keystone 契约。 + +整图基调是"接":实线框是 A-model 现行已落、承袭即用,虚线框是 tier2 专属待建。最该记住的一条在脚注里——A-model 是 Mac 在飞的分支、还没并进 dev/2.0.0,合并之后这两个接缝(play.cdp.cjs、source-project.schema.json)会刷新,所以实现 tier2 时要以合并后的版本为准对账,别拿当前在飞版本去钉行号。 + +*(图源:plan §与 A-model 分支的关系 · tier2/HANDOFF.md §与 A-model 分支的协调)* + +## 3 图清单与状态表 + +| # | 图名 | 形式 | 状态 | 覆盖内容 | +|---|---|---|---|---| +| E1 | 单写 agent 的 toolkit(阶段 2 · skill 清单) | SVG | 建(演进自 wg1 studio.py) | 九个工具的目的/边界/产出 · 三类角色(核心环 / 取证 / 起手收尾) · 自治内循环形态 · 三条工具边界铁律(单写独占 / finish 共用 schema / 验收零自评) | +| E2 | 引擎能力包 manifest(五件套) | SVG | 建(第一版 Phaser 硬编码 · 通用接口待第二引擎) | 引擎=动态加载的能力包而非固定底座 · skill/tool/mcp/rag/脚手架五件套各管一面 · 换引擎=换工具集非架构重写 · 克制警示(不为一个实现先建抽象) | +| E3 | prompt 两阶段角色 | SVG | 建(阶段 1 Agent Team / 阶段 2 单写 · 2.0.3 API 已核) | 阶段 1 工作室 Agent Team 星形(多 agent 发散+专业分工·只读+对话) · 阶段 2 单写 ReAct(防并行写冲突) · leader-worker 拓扑铁律 · 2.0.3 删 MsgHub 只剩部署态 Agent Team | +| E4 | A-model 4 插件复用 | SVG | 接(复用 A-model 资产 · 合并后对账) | 两线边界(引擎/表现层复杂度档) · 四插件契约复用+渲染按 Phaser 重做 · sim-business 配方复用 · 九门基线 driver 感知分级范式复用 · 源项目契约维持独立 schema |