diff --git a/docs/architecture/架构/生成引擎/agentic运行时架构图说.md b/docs/architecture/架构/生成引擎/agentic运行时架构图说.md index 651433c5..06e058eb 100644 --- a/docs/architecture/架构/生成引擎/agentic运行时架构图说.md +++ b/docs/architecture/架构/生成引擎/agentic运行时架构图说.md @@ -11,10 +11,15 @@ - **映射设计档**：本图说只把《[自治富游戏引擎](自治富游戏引擎.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 族后续补）： +- **细节族图说（本图说之下的放大层）**：本篇是整轨的「看图入口」（9 张总览图）；要看某一面的逐项细节，下钻这八份按族拆的细节图说（全八族已建，共 32 张细图，均为本总览的逐项放大、deepen 不 duplicate）： + - [A 族 · 运行时形态](tier2细节图说-A-运行时形态.md)——Agent Service 与 session 三路径、Agent 非常驻 + AgentState、Workspace 双轴注入、Middleware 洋葱。 - [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 插件复用。 + - [F 族 · 源项目契约与装载](tier2细节图说-F-源项目契约与装载.md)——源项目契约七要素四组、第二装载分支、finish 工具共用 schema。 + - [G 族 · 0号 spike runbook](tier2细节图说-G-spike-runbook.md)——建设五步 + 生死门、mini-肥鹅靶子、模型矩阵 + 跑序、过门阈值 + 采集字段、两段实施 + 退路树。 + - [B 族 · 控制面与管理面](tier2细节图说-B-控制面与管理面.md)——控制面四组件、反锁死五协议、预算三层强制、管理面三 phase。 + - [H 族 · 观测与成本](tier2细节图说-H-观测与成本.md)——trace 统一契约、观测管道（Event→OTel→Studio）、成本台账。 ## 1. 全图通用图例 diff --git a/docs/architecture/架构/生成引擎/assets/t2-A-01-AgentService与session三路.svg b/docs/architecture/架构/生成引擎/assets/t2-A-01-AgentService与session三路.svg new file mode 100644 index 00000000..f5946c23 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-A-01-AgentService与session三路.svg @@ -0,0 +1,160 @@ + + + + + + + + + + + + 图 A1 · Agent Service 与 session 三路径（族 A） + cloud 怎么接 tier2:经官方 Agent Service(create_app 的 FastAPI,REST + SSE)→ tier2 不自造 API。八 router · MessageBus 底座 · session 三加载路。 + + + + 整图状态 = 建:tier2 整轨待 0号 spike 验证、尚未落代码;但官方 Agent Service 源码已核(agentscope/app/),它现成、不用自造。 + 实线 = 现行已落 / 框架现成件(官方 Agent Service · MessageBus · D12);虚线(stroke-dasharray 6 4)= tier2 专属待建机制(tier2 自身的 agent / session 接线)。 + + + + + game-cloud + 现行 + REST POST /sessions 建会话 + → SSE 收事件流 + + + + 官方 Agent Service · AgentScope 2.0.3 + 现成 + = create_app 拉起的 FastAPI(REST + SSE);tier2 不自造 API,接官方的。 + 天生多租户 + durable session:会话状态 AgentState 落库可恢复(配 StorageBase 落 Redis)。 + Agent 实例非常驻 —— 每次 run 现组装、跑完即弃,状态全落在可持久化的 AgentState 里。 + + + + tier2 自治富游戏轨 + 待建 + 单写 ReAct agent + 在 service 之上自治造游戏 + + + + + + + 八个 router(源码 agentscope/app/_router/ 逐条核过 · 框架现成件) + + + + + /sessions + 会话 + + + /chat + 对话 + + + /schedule + cron 式定时触发 + + + /credential + 托管模型密钥 + + + /workspace + 执行环境 + + + /model + 模型 + + + /tts_model + 语音模型 + + + agent 管理 + agent 管理面 + + + 底座 = MessageBus(Redis 实现 · 撑分布式协作 · 源码 app/message_bus/ 核过) + + + Redis Stream + 事件 replay 日志(append / read / trim) + 晚到的订阅者可回放、不丢中间过程 + + + pub/sub + 唤醒广播(idle wake-up / live fan-out) + worker 干完异步通知 leader,不必轮询 + + + 分布式锁 + acquire_lock + 同一会话同一时刻只被一个进程跑 + + + 取消信令 + session_publish_cancel + task_publish_cancel + + + + SSE 可恢复:断线靠 MessageBus 的 replay 日志补发,不丢中间过程 —— 兜住外部服务 / 异步任务的超时 · 失败 · 断线。 + cloud 接 tier2 的真实姿势 = REST POST /sessions 建 durable 会话 → SSE 收事件流;掉线后重连,从 replay 日志续读、不必从头重跑。 + + + session 三加载路径(对应「游戏=长生命周期项目」三种入场 · 汇到同一 Agent 装配点 · 只是初始 state / workdir 不同) + + + + ① 续接之前会话 + 待建 + 取历史 resume,往下接着跑 + 初始 state 源: + SessionRecord.state + 取回历史工作记忆 + 轮次,接着 reason + + + + ② 加载已有工程 + 待建 + 指向已存在游戏目录,迭代它 + 初始 workdir 源: + Workspace.workdir + 进迭代模式(改源不改包 · 重新构建) + + + + ③ 新建 + 待建 + 从模板铺一套工程骨架起手 + 初始 workdir 源: + 阶段 2 模板初始化工具 + 铺出空骨架,再交单写 agent 写代码 + + + + + + + + + + + 同一 Agent 装配点(只是初始 state / workdir 不同) + + + 映射：agentic集成架构.md §tier2 接入面（八 router / MessageBus / session 三路）· tier2实现详设.md §运行时形态：两阶段、service 化与 session 三路径 ·（放大总览图 1 系统全景 / 图 2 调用时序）· 源码 agentscope/app/ 已核 ｜ 状态：现（官方 Agent Service 现成件）/ 建（tier2 接线待 spike）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-A-02-Agent非常驻与AgentState.svg b/docs/architecture/架构/生成引擎/assets/t2-A-02-Agent非常驻与AgentState.svg new file mode 100644 index 00000000..c4d72b0e --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-A-02-Agent非常驻与AgentState.svg @@ -0,0 +1,155 @@ + + + + + + + + + + + + 图 A2 · Agent 非常驻 + AgentState + checkpoint（族 A） + Agent 是无状态 ReAct 引擎、实例非常驻——每 run 现组装、跑完即弃；所有状态落在可持久化的 AgentState，checkpoint 即存取这份 state。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；但 AgentState / StorageBase 的结构与字段已按 AgentScope 2.0.3 源码逐条核过。 + 实线 = 现行已落（官方 AgentScope 2.0.3 现成件：AgentState 模型 / StorageBase / RedisStorage）；虚线（stroke-dasharray 6 4）= tier2 专属待建机制（非常驻装配、每轮 checkpoint 落 Redis、resume 续跑）。 + + + + 生产维度 + 可靠 + 数据 + + + + Agent · 无状态 ReAct 引擎 + 待建 + （引擎本体 = 官方 AgentScope 2.0.3） + + 实例非常驻 = 不是长跑进程 + 每次 run：现组装 → 跑完即弃，不留活对象。 + 构造时持有 model / toolkit / middlewares / state。 + + + + 现组装 + 注入初始 state + + 跑 ReAct 多轮 + cur_iter 自增 + + 跑完即弃 + 对象销毁 + + + + 关键推论：状态不在内存里活着 + 既然没有常驻进程可序列化，所有"还要用"的 + 东西都得外置到可持久化的 AgentState 里 → + 这直接决定了 checkpoint 怎么做（看右侧）。 + + + + 状态全落入 + + + + AgentState · pydantic 模型 + 2.0.3 现成 + agentscope/state/_state.py + + + + context + 工作记忆 · 未压缩对话上下文（喂进 LLM） + list[Msg] + + + cur_iter + 当前轮次 · ReAct 循环走到第几轮 + int + + + tasks_context + 任务清单 / TODO · 拆解后的子任务表 + TaskContext + + + + goal/进度 = 输入（brief / play_spec / GDD）为目标 ＋ tasks_context 逐项 TaskCreate/Update 追踪（像 todo list）。 + + + + 存取这份 + + + + checkpoint + 待建 + + 不是序列化一个活对象 + Agent 非常驻 → 没有活进程可存； + checkpoint = 存 / 取这份 AgentState。 + + + + 2.0.3 现成 + StorageBase + 配 StorageBase 抽象 · RedisStorage 落 Redis + + + + 每轮 checkpoint + cur_iter 每自增一轮即落一次 state。 + + + 可靠 + 半轮副作用须幂等无脏（长程一致性采集字段） + + + + 这点直接决定 tier2 怎么做断点续跑：resume = 取回 AgentState 历史往下跑（对应官方 Agent Service 的 session 加载路径①） + + + + 取回历史 state + SessionRecord.state + 从 StorageBase 读回上次的 AgentState + + + 现组装 Agent + 把取回的 state 作为初始 state 注入， + 非常驻引擎据此重建工作记忆与 cur_iter。 + + + resume 往下跑 + 从 cur_iter 续接 ReAct 循环， + 不从头重跑，已完成的 TODO 不重做。 + + + + + + + session 三加载路径 + ① 续接会话（本图主线 · resume state） + ② 加载已有工程（workdir 指向目录） + ③ 新建（模板初始化工具铺骨架） + + + + 本图 = detail 层逐项放大（放大总览图 3 运行时内部 / 图 8 类图） + 总览图 3 把 Agent 与 Workspace 的整体结构画在一处；本图只取"非常驻 + AgentState + checkpoint"这一面逐字段放大：列出 AgentState 三个核心字段、checkpoint 的"存 state 非存活对象"机理、 + 每轮落盘与半轮幂等两条硬约束，以及 resume 续跑落到 SessionRecord.state 与 cur_iter 续接的具体链路——这些总览图 3/8 未展开。Agent↔Workspace 两轴注入见总览图 3，本图不重画。 + + + 映射：docs/architecture/架构/生成引擎/tier2实现详设.md §运行时形态（Agent 非常驻 + AgentState + checkpoint）· agentic集成架构.md §tier2 接入面（durable session / SessionRecord.state）· agentic运行时架构图说.md 图3 运行时内部 + 图8 类图（放大）· AgentScope 2.0.3 源码 state/_state.py + app/storage（已核）｜ 状态：现（AgentState/StorageBase=官方现成）/ 建（tier2 非常驻装配 + 每轮 checkpoint + resume）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-A-03-Workspace双轴注入.svg b/docs/architecture/架构/生成引擎/assets/t2-A-03-Workspace双轴注入.svg new file mode 100644 index 00000000..a9b647be --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-A-03-Workspace双轴注入.svg @@ -0,0 +1,139 @@ + + + + + + + + + + + + 图 A3 · Workspace 双轴注入（族 A） + 纠误解：Workspace 是执行环境、沿两轴注入 Agent；Agent 持有 Workspace 引用、不嵌在它里面。放大总览图 3（运行时内部）+ 图 8（类图 WorkspaceBase）。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；双轴注入结构本身（AgentScope 2.0.3 源码已逐条核过）可信。 + 实线 = 官方 AgentScope 2.0.3 现成件（Agent / Workspace / Toolkit / get_toolkit / offloader / 三实现，直接用）；虚线（stroke-dasharray 6 4）= tier2 专属待建（注入工具集 / 沙箱底座选型）。 + + + + Agent · 无状态 ReAct 引擎 + 官方现成 + 构造参数持有(非嵌套): + + model（M3 AnthropicChatModel） + + toolkit（← 轴①注入） + + offloader（← 轴②，= Workspace） + + middlewares / state（AgentState） + 每 run 现组装、跑完即弃（非常驻）； + 状态全在可持久化 AgentState。 + 持有引用，不被 Workspace 包住。 + 源:agent/_agent.py:104 offloader 参数 + + + + 轴① 资源注入 + Workspace → get_toolkit → Toolkit + + 注入 agent 能调的工具集 + + + 轴② offloader + Workspace 本身作 offloader + + 上下文 / 工具结果卸载挂在 Agent 上 + + + + Workspace · 执行环境（environment 真实载体） + 官方现成 + 源:workspace/_base.py:36 WorkspaceBase（add_skill / add_mcp / list_skills / list_mcps） + + + + Toolkit（轴① 产物 → 注入 Agent） + get_toolkit 把下面汇成 Agent 能调的工具集: + workspace 内建工具 ＋ list_skills() ＋ list_mcps() + 源:app/_service/_toolkit.py:27 get_toolkit / :180 skills_or_loaders ＋ mcps + + + 真正「跑在 Workspace 里」的: + + MCP 进程（add_mcp / list_mcps） + + skills（SKILL.md，add_skill / list_skills） + + 文件（workdir 多文件源工程） + — 不是 Agent 本体；Agent 只持引用。 + + + WorkspaceBase 三实现（沙箱隔离不同强度） + + LocalWorkspace + 本地进程 · 隔离最弱 · 最快 + workspace/_local_workspace.py + + DockerWorkspace + 容器隔离 · 中等强度 + workspace/_docker/... + + E2BWorkspace + 远端沙箱 · 隔离最强 + workspace/_e2b/... + + + + tier2 沙箱底座选型（D5 · spike 前置阻断） + 待建 + spike 开跑前必须先出结论，否则探针矩阵跑不起来。 + 确定性硬门要的「真浏览器低层探针」是否够用 = 承重前提，先验: + + 候选 A:agentscope-runtime BrowserSandbox + page.evaluate / navigate / screenshot / 输入注入 + 逐项可用 → 直接用它跑探针矩阵（当前全仓零引用） + + 候选 B:自建薄沙箱 ＋ 复用现有 CDP + 回落到复用现行 play.cdp.cjs 的运行 / 截图 / 证据骨架 + （探针硬编码 LittleJS，须为 Phaser 重写） + + + + 隔离强度梯度（按需选） + Local ＜ Docker ＜ E2B + spike 期就近用 Local / Docker 起手（最快、好调试）; + E2B 远端强隔离对齐更长期的多租户 / premium 层， + 不是 spike 期投入项。 + 三实现都是官方现成抽象，tier2 只是在其上挂工具与资源。 + + + + 生产维度 + 可观测 + 安全 + 伸缩 + 可观测:工具调用 / 卸载经 + Workspace 统一面，易埋点 trace。 + 安全:沙箱隔离 = 写码 / 真跑 + 的信任边界（强度按层选）。 + 伸缩:E2B 远端撑多租户。 + + + + 一句话:Workspace 注入 Agent，不是 Agent 嵌进 Workspace + 误读 = 「Agent 跑在 environment 里、environment 包着 Agent」。实情 = Agent 是无状态 ReAct 引擎，构造时把 Workspace 沿两轴接进来:轴① 经 get_toolkit 把工具 / MCP / skills 汇成 Toolkit、轴② 把 Workspace 本身当 offloader 挂上。 + 所以「跑在 Workspace 里」的是 MCP 进程 / skills / 文件，不是 Agent 本体——Agent 只持一个引用，每 run 现组装、跑完即弃。 + tier2 不凭空自建 environment 数据面:在官方 Workspace 抽象上挂 tier2 要的工具与资源即可;沙箱底座（Local/Docker/E2B 与 D5 选型）解决「在哪跑、隔离多强」。 + + + 映射：docs/architecture/架构/生成引擎/agentic运行时架构图说.md 图3（运行时内部·双轴注入）＋ 图8（类图 WorkspaceBase）· tier2实现详设.md §运行时形态 · tier2四层工程架构.md §3（environment 层·载体=Workspace·D5 沙箱底座待验）· agentscope 2.0.3 源码（_agent.py：104 offloader / _toolkit.py：27 get_toolkit / workspace/_base.py：36 三实现）｜ 状态：现（官方 AgentScope 现成件）/ 建（tier2 注入工具集 ＋ D5 沙箱底座选型）/ 缓（E2B 远端强隔离=更长期层）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-A-04-Middleware洋葱.svg b/docs/architecture/架构/生成引擎/assets/t2-A-04-Middleware洋葱.svg new file mode 100644 index 00000000..8e9df121 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-A-04-Middleware洋葱.svg @@ -0,0 +1,116 @@ + + + + + + + + + 图 A4 · Middleware 洋葱（横切关注点挂载点）（族 A） + AgentScope 2.0.3 的 MiddlewareBase 在 Agent 执行的若干钩子上层层拦截（洋葱式）；tier2 把成本刹车 / 硬熔断 / 可观测统一挂在这套洋葱上，不另起机制、不散落进业务逻辑。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；洋葱 hook 机制（MiddlewareBase 5 钩子，AgentScope 2.0.3 源码已核）可信。 + 实线 = 承袭现行已落（官方 ReplyBudgetControlMiddleware 软刹 / 官方 TracingMiddleware 观测 / D12 治理门）；虚线（stroke-dasharray 6 4）= tier2 专属待建（硬熔断三件做成 MiddlewareBase 子类）。 + + + 洋葱拦截点 · MiddlewareBase 的 4 个 onion 钩子（外→内,各裹住 Agent 执行的一层） + + + + on_reply + 一轮回复边界（最外环 · 整次 reply 进出） + + + + on_reasoning + 推理 / 模型调用阶段（推理前后） + + + + on_acting + 单次工具执行（仅裹 toolkit.call_tool 这层 I/O） + + + + on_model_call + 最内环：拦截裸模型 API 调用 + 可读 ModelCallEndEvent 的 token 用量 + （event.input_tokens / output_tokens） + 成本台账与 trace 都从这里取 token —— 钱算在这一环。 + 钩子用 next_handler() 前后包裹,故称「洋葱」。 + + + + 第 5 个钩子 · on_system_prompt（transformer 管线,非 onion） + 不前后包裹,而是顺序变换 system prompt 串:多个 middleware 串成管线,各拿上一个的输出。 + （4 onion + 1 transformer 共 5 个挂载点,MiddlewareBase 源码 _base.py 逐条核过；未实现的钩子运行时自动跳过。） + + + 挂在洋葱上的三类横切关注点（现成 vs 自建,一眼区分） + + + + ① 官方 ReplyBudgetControlMiddleware · 预算软刹 + 成本 + 现成·实线 + 挂 on_reply + on_reasoning;AgentScope 2.0.3 自带,直接用。 + on_reply 里按 ModelCallEndEvent 累计加权 token → 越阈值后, + on_reasoning 里注入收尾提示 + 强制 tool_choice=none 让它收尾。 + 只数 token、不换算金额、更不硬拒 —— 刹不住一个已经在烧钱的失控循环（见 B3）。 + + + + ② 自建硬熔断（fail-closed）· 各做成 MiddlewareBase 子类 + 成本 + 可靠 + 待建·虚线 + 同挂洋葱,不另起机制;官方软刹刹不住时由它硬切。 + + + TimeoutMiddleware + 超时 → 硬杀本次生成 + + StuckDetectMiddleware + 卡死 / 无进展 → 硬杀 + + 预算硬闸（¥ 台账） + token×单价＞硬上限→抛错 + 硬闸订阅 ModelCallEndEvent 取 token,乘 new-api 单价换算 ¥ 累进台账,越硬上限即 fail-closed 终止本次（不只注入提示）。 + 建成前 tier2 不规模化跑、只在严格时间盒实验里跑（见 C3 / B3）。 + + + + ③ 官方 TracingMiddleware · 可观测 + 可观测 + 现成·实线 + 挂 on_reply / on_model_call / on_acting;AgentScope 2.0.3 自带。 + 把 typed Event 流（ThinkingBlock / ToolCall / ModelCallStart/End …）转成 OpenTelemetry span。 + 直接调真 OTel SDK → 汇进 AgentScope Studio 可视化;tier2 再加一层 adapter 映射进统一 trace 契约（见 H2）。 + tier2 写轨迹不必自己埋点 —— 复用这条官方 Event→OTel 管道。 + + + + 洋葱 = tier2 横切关注点的统一挂载点 + 成本（软刹 / ¥ 硬闸）· 超时 · 卡死 · 观测 全挂同一套洋葱, + 不散落进业务逻辑、不另立机制 —— 这是 2.0.3 给的扩展点。 + 三层成本强制:worker 本地预测先闸 → D12 网关配额二闸 → 任务 deadline 三闸。 + + + + 与 D12 运行治理门的分工（D12 已有件 · 实线复用） + 洋葱在 agent 进程内（per-run 成本 / 超时 / 卡死 / 观测）;D12 在生成任务入口前（配额 / 并发 / 背压 / 降级）。 + D12 同口径自建一个预算 Middleware,挂 on_model_call,订阅 ModelCallEndEvent,正是 D12 那道「花到上限就拒绝执行」的 agent 内落点。 + D12 现只覆盖 SAA;tier2 接入的入口 / 预算扣减 / 并发释放 / 失败补偿待补（D12 边界,见集成架构 §D12）。 + + + 映射：docs/architecture/架构/生成引擎/agentic集成架构.md §D12 运行治理门（on_model_call / ModelCallEndEvent 软刹缺口与自建硬熔断）· tier2实现详设.md §建设五步第三步「成本强制」· agentscope 2.0.3 源码 middleware/_base.py（4 onion + 1 transformer 钩子）· _budget.py（软刹机制）· _tracing/_trace.py（Event→OTel）｜ 状态：建（tier2 待建·洋葱 hook 2.0.3 已核;软刹 / trace 官方现成,硬熔断自建）｜ 设计变动须同步本图 + （放大总览图 8 关键类图的 MiddlewareBase 一支:ReplyBudgetControlMiddleware 现成,TimeoutMiddleware / StuckDetectMiddleware 自建 —— 本图把它们各自挂哪个钩子、做什么逐项展开,不重画类图。） + diff --git a/docs/architecture/架构/生成引擎/assets/t2-B-01-控制面四组件.svg b/docs/architecture/架构/生成引擎/assets/t2-B-01-控制面四组件.svg new file mode 100644 index 00000000..190e9403 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-B-01-控制面四组件.svg @@ -0,0 +1,149 @@ + + + + + + + + + + + + 图 B1 · 控制面四组件（族 B） + tier2 与现行 SAA 廉价线共用的治理层：让两条生成线被配置、观测、审计、在入口拦住。内核 = 配置即数据 · 全链可观测，不从零造 Dify。 + + + + 整图状态 = 现 ＋ 建·接：D12 与 Prompt Registry 部分已落（现）；配置审计 / skill-tool-mcp 推广 / tier2 接入 待建（建·接）。 + 实线框 = 现行已落或已有件复用；虚线框（stroke-dasharray 6 4）= 待建净增量或 tier2 待接。控制面从属于线A、只做净增量；tier2 整轨待 0号 spike 验证。 + + + 可观测 + 安全 + 数据 + + + 两条生成线 + + + + SAA · Tier0/1 廉价线 + 现行 + 16 节点静态 StateGraph + 读配置 / 写轨迹 / 过 D12 已接 + + + + tier2 · 自治富游戏 + 待建 + 单写 ReAct（AgentScope 2.0.3） + 读配置/写轨迹已设计 · 过门待接 + + + + 控制面 / 管理面 —— 对两条线暴露同一套契约：读配置 ＋ 写轨迹 ＋ 过门（接口对称 · 内容不对称） + + + + ① 配置注册表 · 唯一事实源 + 数据 + 现 部分 + prompt · model · skill · tool · mcp + 凡「改就得发版」的都搬进版本化、可回滚注册表。 + 现状：Prompt Registry 是构建期快照（非热加载）、有 STUB 缺口。 + + + 推广到 skill / tool / mcp = 净增量（待建）。 + 硬纪律：推广前先补一致性 CI（条目有文件 · 硬编码 id 已登记 · STUB 补正或标不可上线）。 + + + + ② 观测 / 审计仓 · 唯一事实源 + 可观测 + 数据 + 运行轨迹：每步推理 · 工具 · LLM IO · 门裁 · 成本 + 统一 contracts/trace/：公共核心子集对称、扩展段各写各的。 + + + 配置审计：谁 · 何时 · 改哪条配置 · 前后 diff（全新建）。 + 分类落地：prompt / models 走 GitOps（建 PR）；运营开关走 DB 直写 infra_config。 + 价值：任一次生成可反查「当时用了哪几条配置的哪个版本」。 + + + + ③ D12 运行治理门 · 已有件复用 + 安全 + 现行 + 配额 · 并发 · 背压 · 降级（焊在生成入口前） + 已存在的件，本设计只复用不改；默认关闭、零行为变更进主干。 + 现只覆盖 SAA；记账是骨架（门结构 ＋ 配置键）、非真计费。 + + + tier2 待接（虚线）：入口 · 预算扣减 · 并发释放 · 失败补偿要补。 + 硬熔断 ＋ ¥ 台账自建（订阅 ModelCallEnd 折¥，越上限 fail-closed），官方仅软刹。 + + + + ④ 管理面 UI · 注册表＋观测仓的视图与编辑器 + 可观测 + 配置是真相、UI 是视图；不造 Dify 式拖拽建图器。三 phase（见 B4）： + + + phase-1 + 配置管理＋可观测 + + phase-2 + 限定范围图编辑 + + phase-3 + 完整建图 远期不投 + 铁律：拓扑只渲染运行时自报结构，管理面侧绝不另持一份拓扑模型。 + phase-1 含纯只读切片：看各角色当前模型 · 回放全轨迹 · 按 quota 对账成本。 + + + + + 读配置（实线·已接） + + + 写轨迹（实线·已接） + + + 过 D12（实线·已接） + + + + tier2 读配置：待接（虚线） + + + tier2 写轨迹：待接（虚线） + + + tier2 过 D12：待接（虚线） + + + + 接口对称、内容不对称 —— 一份管理面管两条异构线的成立条件 + 读配置：两条线都按「id ＋ 版本」从注册表加载（接口同），但 SAA 读 16 节点参数、tier2 读 ReAct 工具集与轮数预算（内容异）。 + 写轨迹：都按统一 trace 契约写，公共核心子集对称、扩展段各写各的（SAA 放阶段/修复轮/门裁，tier2 放推理/动作/观察）。 + 过治理门：都先过 D12，现只覆盖 SAA、tier2 待接。注意：tier2 的 eval/灰度门尚不存在 —— 其配置改动当前只有「下次生效＋轨迹留痕」两层保护、无 eval 拦截。 + 反锁死：控制面对外只暴露读配置/写轨迹/过门三件，平台不绑死任何单一 agent 框架（固化在协议层的是任务/状态/工具/门禁/遥测五件）。 + + + + 元素级状态读法 + 实线框 = 现行已落 / 已有件复用：SAA 廉价线（读配置·写轨迹·过 D12 已接）、D12 治理门、Prompt Registry（构建期快照那部分）。 + 虚线框 = 待建净增量 / tier2 待接：配置审计日志（全新建）、注册表推广到 skill/tool/mcp、统一 trace 契约新立位、tier2 读配置/写轨迹/过门。 + 远期紫（phase-3 完整可视化建图）= 远期不投：要等真有多编排 / 多 agent 团队需求、且「拓扑配置化」深坑被填后才上。 + + 存储复用已部署的 MySQL ＋ 对象存储，不新起重型可观测中间件（链路追踪那套是 future-state，等真有第一个消费者再上）。 + + + 映射：docs/architecture/架构/生成引擎/agentic集成架构.md §为什么要这一层（顶部 mermaid）＋ §四个组件 ｜ 状态：现（D12 / Prompt Registry 部分已落）＋ 接 / 建（配置审计 · skill-tool-mcp 推广 · tier2 接入待建）/ 缓（phase-3 远期）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-B-02-反锁死五协议.svg b/docs/architecture/架构/生成引擎/assets/t2-B-02-反锁死五协议.svg new file mode 100644 index 00000000..d12161e7 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-B-02-反锁死五协议.svg @@ -0,0 +1,135 @@ + + + + + + + + + 图 B2 · 反锁死五协议（框架可替换 · 族 B） + 平台不绑死任何单一 agent 框架：选了 SAA ≠ 被 SAA 锁死。固化在协议层的五件与框架解耦，框架被压到「只租用不拥有」。 + + + + 整图状态 = 建：本图立的是一条根本架构原则（协议层固化、框架解耦）；五件中 job/callback 契约 #6 已存在，其余随 tier2 / 控制面分期落地。 + 实线 = 现行已落（GenerationDispatcher 接口 #6 / D12 已有件 / 九门廉价线已建 / new-api 出口）；虚线（stroke-dasharray 6 4）= tier2 专属或随分期待建（统一 trace 契约 / 工具接口契约 / tier2 接 D12）；远期紫 = AgentScope premium 轨等远期不投。 + + + + 当下生产线 SAA-only（HJ-AGI-002，经双评审 + 源码核验选定的实现） + 「选了 SAA」不等于「被 SAA 锁死」——框架可借鉴 / 组合 / 分轨采用（long-term tier2 premium 轨走 AgentScope）。 + 把协议层那几件钉牢，框架就被压到「只租用不拥有」的位置，换框架时业务不被连根拔起。 + + + + long-term premium 轨 + 远期不投 + tier2 premium 走 AgentScope + + + + 协议层归属 + 数据口径 + 五件 = 平台固化,不随框架走 + + + 固化在协议层、与框架解耦的五件（框架私有结构禁渗入） + + + + ① 任务协议 + 现 + 生成怎么提交 / 回调 + 边界 = job/callback 契约 #6 + GenerationDispatcher + 接口暴露 + + 换框架只换 dispatcher 实现， + 调用方一行不改。 + + + + ② 状态模型 + 建 + 状态怎么表达 / 续跑 + checkpoint 的语义 + 是平台自己的口径， + 不是某框架的私有结构。 + + 一次生成的续跑语义由平台 + 定义，不随框架漂移。 + + + + ③ 工具接口 + 建 + agent 能调哪些工具 + 入参 / 出参以契约定义， + 不绑某框架的 + 工具注册机制。 + + 工具集 = 契约，框架只是 + 把契约接进它的注册器。 + + + + ④ 验收门禁 + 现 + 平台铁律 + 「完成」由确定性九门裁定 + 禁 LLM 自评（同不变量二） + 无论底下换哪个框架， + 出题与被考不同源不让步。 + + 防 Goodhart：把度量当目标 + 优化，度量即失效。 + + + + ⑤ 遥测事件 + 建 + 可观测 + 落进统一 trace 契约 + contracts/trace/ + 公共核心子集对称、 + 扩展段各写各的。 + + 采集机制各框架来， + 数据口径是平台的。 + + + + 判据 · 正向：切轨 = 换一个被治理的执行后端 + long-term 把某轨从 SAA 切到 AgentScope 时—— + 只要这五件仍稳稳钉在协议层， + 切换就只是换一个被治理的执行后端，不是推倒重来。 + + SAA（裸 StateGraph） ⇄ AgentScope（自治 ReAct）：业务侧调用方契约不变（不变量五）。 + 两套异构范式靠「协议层对称、执行后端可换」共存。 + + + + 判据 · 反向：框架私有结构渗进五件 = 锁死开始 + 若某框架私有结构悄悄渗进上面五件中任何一件—— + 例：轨迹格式被某框架的 span 结构绑死、 + 或任务协议泄漏了框架的内部状态。 + + → 那就是锁死的开始，要立刻在协议层把它隔离回去。 + 同理:管理面只渲染运行时自报拓扑、绝不另持一份拓扑模型（硬编码框架拓扑 = 换框架阻力）。 + + + + 框架被压到「只租用不拥有」 · 协议层固化 · 执行后端可换 + 五件钉牢的是平台真正固化、不随框架走的东西；框架（SAA / AgentScope / LangGraph / AutoGen）只在五件契约的约束下被借鉴 / 组合 / 分轨采用。 + 这条原则不是空谈「将来好换」，它有具体落点：它正是 long-term 要不要把某条轨从 SAA 切到 AgentScope 时的判据。 + 现行已落锚点（实线）：契约 #6 GenerationDispatcher 接口已存在；九门由廉价线已建（验收门禁）；D12 入口治理为已有件；模型出口统一收口 new-api 计费平面。 + 待建锚点（虚线）：状态模型 / 工具接口的契约化、统一 trace 契约（contracts/trace/ 当前未立位）、tier2 接 D12，随 0号 spike 与控制面分期落地。 + + + 映射：docs/architecture/架构/生成引擎/agentic集成架构.md §「Agent 框架可替换：反锁死原则」· SAA编排.md §1 决策锚点 / §4 不变量五（GenerationDispatcher 契约 #6） ｜ 状态：建（原则·协议层固化;契约 #6 已存在,余随分期落地）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-B-03-预算三层强制.svg b/docs/architecture/架构/生成引擎/assets/t2-B-03-预算三层强制.svg new file mode 100644 index 00000000..6ca3d085 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-B-03-预算三层强制.svg @@ -0,0 +1,117 @@ + + + + + + + + + + + + 图 B3 · 预算三层强制（软刹 vs 硬熔断） + 引擎那道「花到上限就拒绝执行」的预算闸:官方 ReplyBudgetControlMiddleware 只软刹、刹不住烧钱循环 → 自建硬熔断 fail-closed ＋ 三层强制。深挖 C3 四熔断里的预算这一道。 + + + + 整图状态 = 现（官方软刹现成）＋ 建（硬熔断 ＋ 三层强制自建待落）。tier2 整轨待 0号 spike 验证、尚未落代码。 + 实线 = 现行已落（官方 AgentScope 2.0.3 ReplyBudgetControlMiddleware / D12 运行治理门 / new-api 计费平面）；虚线（stroke-dasharray 6 4）= tier2 专属待建机制（预算 Middleware 硬熔断 / 三层强制闸）。 + 徽章:成本（#16a34a）＝预算核算面 · 安全（#dc2626）＝fail-closed 截断面。 + + + 官方给了什么 vs 缺什么 ——— 同一个中间件洋葱里两种处置力度 + + + + 官方软刹 · ReplyBudgetControlMiddleware + 现成 + AgentScope 2.0.3 自带 + 机制:累计加权 token 到阈值后 — + ① 往 Agent 上下文注入一句提示（「别再调工具、收尾」）; + ② 把下一步 tool_choice 强制成 none，逼它结束。 + 边界:只数 token、不换算金额、不会硬拒。 + + + 对失控成本不够: + tier2 自治多轮一次失控循环能烧掉数美元;软刹只「提醒别再调工具」, + 刹不住一个已经在烧钱的循环 —— 提示不等于截断。 + + + + 自建硬熔断 · 预算 Middleware（fail-closed） + 待建 + 现成载体 = Middleware 洋葱 + 机制:订阅 ModelCallEndEvent（带每次模型调用 token 用量） + ① token × new-api 单价 → 换算成 ¥ 累进台账; + ② 一旦越硬上限 → 直接抛错 fail-closed、终止本次生成; + ③ 不是只注入提示 —— 是强制截断已在烧钱的循环。 + + + 越上限 → fail-closed 抛错 → 终止本局 + 挂在 on_model_call 钩子拦截;¥ 金额台账 ＋ 硬拒， + 是官方软刹做不到的两件,故必须自建。 + + + + 软刹「提醒」 + 硬熔断「截断」—— 一个数 token 提醒,一个折¥硬拒,两者叠在同一洋葱里。 + + + 三层强制 ——— 成本不靠单点,三道闸纵向叠;任一道先到上限即拦 + + + + ① worker 本地预测闸 + 待建 + 成本 + worker 本地的 token / 成本预测 + 先闸:动手前先估这一步要花多少, + 越本局预算就不发起调用 —— 最便宜的 + 一道,在调模型之前就拦下。 + （位置:tier2 worker 进程内） + + + + ② 网关配额闸 · D12 + 已有 + 成本 + D12 运行治理门(已存在件,只复用) + 配额 · 并发 · 背压 · 降级 · 记账骨架, + 焊在生成任务入口前;现仅覆盖 SAA。 + tier2 接入面（入口 / 预算扣减 / 并发释放 / + 失败补偿）＋ 记账从骨架变真计费 = 待补。 + + + + ③ 任务 deadline 闸 + 待建 + 成本 + 本次生成的墙钟 deadline + 三闸:超过时间盒即停, + 兜住「token 没烧穿但卡在长循环里」 + 这种纯耗时的失控, + 与 token / ¥ 上限互补。 + + + + + + + + 取价不可达时的策略（必须选边、不能既要又要） + token × new-api 单价折 ¥ 这一步,若取价通路不可达 —— 要么直接失败（保守、宁停不超支）,要么降级到纯 token 上限（不折¥、只按 token 硬顶兜底）。落地时显式定一条,不留模糊。 + + + + 铁律 · 强制预算建成前,tier2 不规模化跑 + 这套三层强制预算落地之前,tier2 只在严格时间盒的实验里跑,绝不规模化 —— 自治多轮不强制就会烧钱,软刹刹不住。 + （C3「四道熔断」是总览,本图只深挖其中预算这一道 ＋ D12 网关配额;spike 阶段成本熔断可先只挂官方软刹,硬熔断与三层强制到建设期补全。） + + + 映射：docs/architecture/架构/生成引擎/agentic集成架构.md §D12 运行治理门（官方软刹 vs 自建硬熔断 ＋ 三层强制）· tier2实现详设.md §建设五步 第三步 成本强制 ｜ 状态：现（官方 ReplyBudgetControlMiddleware ＋ D12 已有）/ 建（硬熔断 ＋ 三层强制自建待落）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-B-04-管理面三phase.svg b/docs/architecture/架构/生成引擎/assets/t2-B-04-管理面三phase.svg new file mode 100644 index 00000000..eb617a03 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-B-04-管理面三phase.svg @@ -0,0 +1,133 @@ + + + + + + + + + + + + 图 B4 · 管理面三 phase + 接口对称内容不对称（族 B） + 管理面 UI = 注册表与观测仓的视图与编辑器，不是真相本身（配置才是真相）。创始人最在意的「Dify 式可视化管 agent 平台」那半边。 + + + + 整图状态分档：phase-1 可立即做（接，依赖最少）/ phase-2（缓）/ phase-3 远期不投（future，远期紫）。 + 实线 = 现行已落（D12 已有件 / infra_config 热改通路 / new-api quota）；虚线（stroke-dasharray 6 4）= 待建净增量（trace 契约 / 配置审计 / UI 各档）。 + 远期紫块 = 明确「现在不投」的能力（phase-3 拖拽改拓扑），等真有多编排需求且「拓扑配置化」深坑被填了才上。 + + + + 生产维度 + 可观测 + 数据 + 可观测＝先兑现的切片 + + + + 设计选择先定：不从零造 Dify 式建图器，让配置成为真相、UI 只做配置＋轨迹的视图与编辑器 + ① 已拍板维持现有 SAA / AgentScope、不迁可视化平台；② 裸图节点是 Java 代码、ReAct 工具也是代码 — 真相在代码和配置里，拖拽生成代码是另一套不可靠范式； + ③ 别过度工程的纪律。但「配置是真相、UI 是视图」不等于「第一期什么都不做」— 管理面按三档落，且诚实命名（下排）。 + + + + + phase-1 · 配置管理 ＋ 运行可观测 + 可立即做 + 接 + 诚实命名：这期还没真图编辑，不叫「可视化编排」。 + + + + 只读「看得见」切片 · 不依赖线A任何一步 · 立即兑现 + · 看各角色当前用什么模型 + · 回放任意一次生成的全轨迹 + · 按 new-api 的 quota 口径对账成本 + + + + 其上加：配置编辑（改注册表条目） + UI 改 prompt / 换模型 / 调阈值 → 落 Git ＋ 审计日志，非热生效。 + + + + phase-2 · 限定范围图编辑 + 缓 + 配置编辑 UI 完整化 ＋ 限定范围的图编辑。 + 把图编辑排进来： + · 节点启停 / 边开关 + · 节点的模型 / 工具绑定 + · 配置版本 diff + · 按轨迹回放 + + 「限定范围」= 只编辑节点参数和启停 + 渲染的拓扑来自运行时自报，不让用户拖拽新增节点改结构。 + + + + phase-3 · 完整可视化建图 + 远期不投 + 拖拽改拓扑 / 可视化编 agent flow / 跨编排复用。 + 两个前置条件齐了才上： + · 真有多编排、多 agent 团队的需求； + · 「拓扑配置化」那个深坑（运行时 + 　重建图）被填了。 + + 这是给我们自己运维用的拓扑可视化 + 不是给 C 端创作者编 workflow 的产品能力（后者另登记一条 + 未来需求，tier2 自身靠 loop＋task/goal＋Team 调度即可，不靠 DAG）。 + + + + + + + + 贯穿约束 ① 只渲染运行时自报的拓扑（反锁死） + 管理面对拓扑只渲染框架运行时自报的结构 + 数据源 = 运行时轨迹实际走到哪个节点；绝不在管理面这侧另持一份拓扑模型。 + SAA = 静态 StateGraph；tier2 ReAct = 无静态图。两套异构范式要用同一管理面呈现， + 只能靠「渲染运行时自报」这个共同口径。 + 也是反锁死：换框架时，管理面里硬编码的拓扑模型反而会成为阻力 → 拓扑结构配置化推迟。 + + + + 贯穿约束 ② 接口对称、内容不对称 + 「一份管理面管两条异构线」能成立的条件：接口层对称、内容层不对称。 + + + + 读配置 + 接口：按 id＋版本加载 + SAA 读 16 节点参数； + tier2 读 ReAct 工具集＋轮数预算 + + + 写轨迹 + 接口：按统一契约写 + 公共核心子集对称； + 扩展段各写各的（JSON 列） + + + 过治理门 + 接口：都先过 D12 + SAA 已覆盖（实）； + tier2 入口待补（虚） + + + + 要写明的现实 · 不是设计缺陷，是 tier2 成熟度的现状 + 配置安全门要分清：tier2 的 eval / 灰度门是 tier2 实验的产物、现在不存在。 + 所以「配置改动要过 eval 门」对 tier2 现在是空头支票 — eval 门建成前，tier2 配置改动只有「下次任务生效 ＋ 轨迹留痕」两层保护，没有 eval 门拦截。 + 写明这点，否则会让人以为 tier2 配置改动有它实际没有的安全网。（SAA 廉价线则已落 D12 ＋ Git CI 校验，保护更全。） + + + 映射：docs/architecture/架构/生成引擎/agentic集成架构.md §管理面 UI ＋ §接口对称内容不对称 ＋ §关于 workflow 编排（放大总览图 5 的管理面/配置维度）｜ 状态：接（phase-1）/ 缓（phase-2）/ future 不投（phase-3）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-F-01-源项目契约七要素.svg b/docs/architecture/架构/生成引擎/assets/t2-F-01-源项目契约七要素.svg new file mode 100644 index 00000000..ce661e4b --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-F-01-源项目契约七要素.svg @@ -0,0 +1,115 @@ + + + + + + 图 F1 · 源项目契约七要素四组(族 F) + tier2 立项要补的第一件工程:给真 Phaser 引擎工程新写一套源项目契约,钉七样、分四组,与 Tier0/1 廉价线的 ECS-lite 装载契约解耦并存。 + + + + 整图状态 = 建:tier2 整轨待 0号 spike 验证、尚未落代码;这套源项目契约本身也未落,编为契约组新一类(additive)。 + 虚线(stroke-dasharray 6 4)= tier2 专属待建机制(七要素全是新写);实线 = 现行已落件(下方蓝条那条现行装载路);红线 = 不许碰的硬边界;徽标:紫「待建」= 此件尚未落代码,灰「数据」= 该要素沿用现行 GamePackage manifest + sha256 落库取回这条路。 + + + + 现行(实线):Tier0/1 一款游戏 = 库里一条 GamePackage —— 代码打成 engineBundle 内嵌 manifest JSON(带整包 sha256),feed 下发 → 挂 window.__GameBundle → bootGameHost 在沙箱 canvas 跑起、每帧回调 update / render。 + tier2 产物也走「存进库、按需取来跑」这条路,但形态不同:不是声明式数据壳 + 固定运行时,而是多源文件 + 构建脚本 + 依赖的真 Phaser 工程,要先 esbuild 构建出 bundle 才能玩 —— 故下面七要素另立一套契约。 + + + + + 【身份】辨清是哪种产物 + + + ① 源项目类型标记 + 待建 + 让装载侧一眼分清 + 是 ECS-lite 数据壳 + 还是 tier2 引擎工程, + 走对应的装载分支。 + 两条装载路不通用、 + 解耦并存,类型标记 + 是分流的第一道闸。 + + 分流目标:Phaser 引擎 + 工程 → esbuild 构建分支 + + + + 【工程骨架】有哪些文件 · 从哪起手 + + + ② 文件树 manifest + 待建 + 记下有哪些文件、 + 各自什么角色:入口 / 场景 / + 资产 / 配置。装载、寻址都按它走。 + + + ③ 入口文件 + 待建 + 标出 build 从哪个 + 文件起手。 + 构建链的源头锚点。 + + + + 【构建可复现】同一款永远构得出来 + + + ④ 构建 profile + 待建 + 固定这一款用什么 + 命令、什么 esbuild 配置打包。 + 构建步骤随款冻结,不漂。 + + + ⑤ 依赖锁 + 待建 + 钉死引擎和插件版本。 + 免得上游一升级, + 历史游戏就构建不出来。 + + + + 【落库取回】算指纹 · 存 / 取重建 + + + ⑥ 内容哈希 + 待建 + 数据 + 给整个工程算一个指纹。 + 做缓存命中(同指纹跳过重建) + + 完整性校验。 + + + ⑦ 落库与寻址 API + 待建 + 数据 + 定义工程怎么存进 + MySQL + 对象存储, + 怎么按 id 取回来重建。 + + + + 建议:finish 工具的参数 schema 与这套源项目契约共用同一份定义(待建) + tier2 的 agent 自治跑完那一刻,经一个 finish 工具(AgentScope 里以 Tool 工具函数为载体的收尾接线)把结构化游戏定义吐出来。 + 让 agent 调 finish 交付的形状 = 落库取回时认的那个形状;两边各写各的迟早对不上(改了契约忘改工具、或反过来),共用一份从源头杜绝漂移。 + + + + 红线 · 这套契约是 tier2 自己的,绝不碰 Tier0/1 廉价线在生产上跑着的 ECS-lite 装载契约 + 命名上另立一份独立 schema、编为契约组新一类 —— 绝不扩在现有 contracts/agent-loop/source-project.schema.json 上。 + 那份现有同名 schema 是 Tier0/1 ECS-lite 数据壳的契约;共用一份会把本该解耦的两条线又焊一起,还可能污染在产线。两条装载路解耦并存,tier2 这边怎么改都不许回归现有产线。 + 接上产品基座:游戏是长生命周期的结构化源项目,改源不改包、重新构建 —— 真·多文件 Phaser 工程本身就是一个可维护的源项目。 + + + 映射：docs/architecture/架构/生成引擎/tier2实现详设.md §第一批工程定义：源项目契约(七要素四组 / finish 工具共用 / 命名边界)· (放大总览图 7 产物与契约)docs/architecture/架构/生成引擎/agentic运行时架构图说.md ｜ 状态：建(tier2 待建·契约组新一类 additive;承袭现行 GamePackage 落库取回这条路 = 实线)｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-F-02-第二装载分支.svg b/docs/architecture/架构/生成引擎/assets/t2-F-02-第二装载分支.svg new file mode 100644 index 00000000..ca7275b8 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-F-02-第二装载分支.svg @@ -0,0 +1,135 @@ + + + + + + + + + + + + 图 F2 · 第二装载分支（Phaser 工程 vs ECS-lite 数据壳） + 游戏怎么进浏览器：两条「存进库、按需取来跑」的装载路，由源项目类型标记分流——现行数据壳一条、tier2 引擎工程一条，解耦并存。 + + + + 整图状态 = 现 + 建：现行 ECS-lite 装载（engineBundle 内嵌 manifest / __GameBundle / bootGameHost）已落在生产 = 实线；tier2 真 Phaser 工程的第二装载分支待 0号 spike 验证、尚未落代码 = 虚线。 + 实线（实心框）= 现行已落；虚线框（stroke-dasharray 6 4）= tier2 专属新机制（源项目契约 / esbuild 构建 / 第二装载路）。两条装载路不通用、tier2 怎么改都不许回归现有产线。 + + + + 源项目类型标记（见 F1）→ 装载侧一眼分流 + 每款游戏都不是仓库里的源码，而是一份存进库的数据；装载侧读它那条记录的源项目类型标记，决定走哪条装载路。 + 两条路解耦并存：ECS-lite 数据壳走现行分支（声明式数据壳 + 固定运行时）；tier2 引擎工程走第二装载分支（真 Phaser 多源工程，须先构建）。 + + 类型标记 + data：现行已落 + phaser：待建 + + + + 类型 = data + + 类型 = phaser + + + + 现行装载路 · ECS-lite 数据壳 + 现 + 声明式数据壳 + 代码打成 engineBundle，内嵌在 GamePackage 的 manifest JSON 里（整包带 sha256）。每款游戏 = 库里一条 GamePackage，不是仓库里一份源码。 + + + + ① 存库：engineBundle 内嵌 manifest JSON + 代码打成 bundle 文本，作 GamePackage additive 字段嵌进 DB-manifest（CSP 不放外域），整包带 sha256。 + + + ② 取回：feed 点开 → 后端下发 manifest + 玩家在 feed 点开某款，后端把这份 manifest 下发到浏览器。 + + + ③ 挂载：取出 engineBundle 挂 window.__GameBundle + iframe 内联 script 暴露全局 __GameBundle，不引外域。 + + + ④ 启动：bootGameHost 在沙箱 canvas 上跑 + 通用宿主泛化装载，固定运行时（引擎掌帧、受控面经 ctx.getEngine 注入）。 + + + ⑤ 跑：每帧回调游戏 update / render + 引擎是唯一掌帧源；绘制面唯一 = 引擎 mainContext，游戏不自起 RAF。 + + 特征：不构建、即取即跑——bundle 已是产物。固定运行时一套，所有数据壳共用。 + 这条是 Tier0/1 廉价线在生产上跑着的装载契约（已落，Runner v2 P1/P2 实证）。 + 红线：tier2 的第二装载分支绝不碰它——两条线解耦并存，不许回归现有产线。 + + + + + + + + + + tier2 装载路 · 真 Phaser 引擎工程 + 待建 + 真多文件源工程 + 同样「存进库、按需取来跑」，但形态不同：不是数据壳 + 固定运行时，而是一个真 Phaser 工程，要先 esbuild 构建出 bundle 才能玩。 + + + + 工程形态 = 多源文件 + 构建脚本 + 依赖 + 入口 / 场景 / 资产 / 配置 多个源文件，一份构建脚本，一套依赖锁——是个可维护的源项目， + 不是声明式数据壳。改源不改包、重新构建。 + + + + tier2 立项新写的源项目契约（七样 · 四组 · 见 F1） + 身份：源项目类型标记（让装载侧分流，就是顶上那个 phaser 标记）。 + 骨架：文件树 manifest（哪些文件 / 各自角色）+ 入口文件（build 从哪起手）。 + 构建可复现：构建 profile（命令 + esbuild 配置）+ 依赖锁（钉死引擎与插件版本）。 + 落库取回：内容哈希（缓存命中 + 完整性）+ 落库 / 寻址 API（MySQL + 对象存储）。 + 另立独立 schema、不扩在 ECS-lite 那份 source-project.schema.json 上——共用会把两条线又焊一起。 + + + + 构建步（现行没有） + 取回源工程 → esbuild 按构建 + profile 打包 → 产出可玩 bundle + + + 而后同样存库 / 取来跑 + 落库取回走自己那套寻址 API； + 沙箱里跑构建产物，固定运行时不复用。 + + + + finish 工具交付的形状建议与这套源项目契约共用同一份定义——agent 吐出的形状 = 落库取回认的形状，源头杜绝漂移。 + 接上产品基座：游戏 = 长生命周期结构化源项目，真·多文件 Phaser 工程本身就是可维护的源项目。 + + + + + + + + 两条路对照一句话 + 现行：bundle 即产物、即取即跑、固定运行时、一款一条 GamePackage、sha256 整包校验。 + tier2：源工程入库、取回须先 esbuild 构建、独立源项目契约寻址、内容哈希做缓存与完整性。 + + 可靠 + 数据 + 伸缩·并存 + 红线 + 可靠 = sha256 / 内容哈希完整性校验 + + + 映射：docs/architecture/架构/生成引擎/tier2实现详设.md §第一批工程定义：源项目契约（现行 engineBundle 装载 + tier2 第二装载路）· （放大总览图 7 产物与契约）· 项目记忆 runner-v2-p1-loading-contract（__GameBundle / bootGameHost / engineBundle 内嵌 manifest 已落实证）｜ 状态：现（ECS-lite 装载已落）+ 建（tier2 Phaser 第二装载分支待建）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-F-03-finish共用schema.svg b/docs/architecture/架构/生成引擎/assets/t2-F-03-finish共用schema.svg new file mode 100644 index 00000000..846cddf3 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-F-03-finish共用schema.svg @@ -0,0 +1,146 @@ + + + + + + + + + + + + 图 F3 · finish 工具 ↔ 源项目契约共用 schema（族 F） + 防漂移的一处源头设计：agent 调 finish 交付的形状 = 落库取回时认的那个形状，两边共用同一份定义。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；finish 工具与「共用一份 schema」均为 tier2 立项要补的新机制。 + 实线 = 现行已落（「存进库、按 id 取回来跑」这条装载范式 + MySQL 底座 + bootGameHost 沙箱）；虚线（stroke-dasharray 6 4）= tier2 专属待建机制（finish 工具 / 共用 schema / 源项目契约 / 引擎工程的 OSS 落库与寻址）。 + + + + 核心约定 · 共用同一份 schema + 待建 + finish 工具的参数 schema，与源项目契约（F1 那七要素）共用同一份定义 —— 不是各写一份、靠人盯着保持一致。 + + + + finish 工具 · 参数 schema + AgentScope 里以 Tool 工具函数为载体的收尾接线; + agent 自治跑完那一刻,调它把结构化游戏定义吐出来。 + 「交付的形状」 + + + ＝ + 同一份 + + + + 源项目契约（F1 · 七要素） + tier2 自己另立的一份独立 schema(编为契约组新一类); + 绝不碰 Tier0/1 在产线跑的 ECS-lite 装载契约。 + 「落库取回认的形状」 + + + + 为什么共用 · 从源头杜绝交付↔落库漂移 + 两边各写各的迟早对不上 —— 改了契约忘改工具、或反过来 —— 一旦错位,agent 交付的形状落不进库、取回时认不出。 + 共用一份从源头消除这种漂移:契约即工具签名,改一处两处一起改,不存在「两份 schema 不一致」这个失败面。 + + + 链路（横向）· agent 收敛 → finish 交付 → 落库 → 下次取回重建 + + + + ① agent ReAct 收敛 + 待建 + 单写 agent 在 Agent 内 + ReAct 多轮自治,过三层 + 校验收敛到产出。 + + + + ② 调 finish 工具 + 待建 + 收尾接线（Tool 工具函数）; + 参数 = 源项目契约形状 + （七要素 / 四组,见下条带）。 + + + + ③ 结构化游戏定义 + 待建 + 一个真 Phaser 引擎工程 + （多源文件 + 构建脚本 + + 依赖,非声明式数据壳）。 + + + + ④ 落库 + 待建 + 按 F1 落库 / 寻址 API, + 工程存进 MySQL + OSS + （内容哈希做完整性校验）。 + + + + ⑤ 按 id 取回重建 + 待建 + 下次按 id 取回工程, + 重建后玩 / 改源不改包; + 认的就是 finish 交付的形状。 + + + + + + + + + 源项目契约（F1）钉死的七样东西 · 分四组（finish 参数 schema 与之共用这一份定义） + + + + 身份 + 待建 + ① 源项目类型标记 + 让装载侧一眼分清: + ECS-lite 数据壳 还是 + tier2 引擎工程,走对分支。 + + + + 工程骨架 + 待建 + ② 文件树 manifest + 记有哪些文件、各自角色 + （入口 / 场景 / 资产 / 配置）。 + ③ 入口文件　build 从哪起手 + + + + 构建可复现 + 待建 + ④ 构建 profile + 固定命令 / esbuild 配置打包。 + ⑤ 依赖锁 + 钉死引擎 + 插件版本,防上游升级断构建。 + + + + 落库取回 + 待建 + ⑥ 内容哈希 + 给整个工程算指纹,做缓存命中 + 完整性校验。 + ⑦ 落库与寻址 API + 定义工程怎么存进 MySQL + 对象存储、怎么按 id 取回重建（即链路④⑤的依据）。 + + + 映射：docs/architecture/架构/生成引擎/tier2实现详设.md §第一批工程定义：源项目契约（finish 工具共用 schema 那段 / 七要素四组 / 落库取回链路）｜ 状态：建（finish 与契约共用一份 schema · tier2 待 0号 spike）｜ 设计变动须同步本图 + 放大《agentic 运行时架构图说》图 7「产物与契约」：图 7 给五要素扁平链,本图逐项展开七要素四组 + finish 工具 + 共用 schema 防漂移机制 + 交付→落库→取回链路（deepen 不 duplicate）。 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-G-01-建设五步与spike门.svg b/docs/architecture/架构/生成引擎/assets/t2-G-01-建设五步与spike门.svg new file mode 100644 index 00000000..80cb3239 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-G-01-建设五步与spike门.svg @@ -0,0 +1,140 @@ + + + + + + + + + + + + + + + 图 G1 · 建设五步 ＋ 0号 spike 生死门（族 G） + 五步纵向走，第三步之前插一道便宜的 spike 门。贯穿原则：最深的赌注（便宜模型能否自治写出那 56% 表现层）要在最便宜的时候验。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；故 tier2 专属新机制（spike 门、五步路径、隐藏硬工作）一律画虚线。 + 实线 = 承袭现行已落（AgentScope 2.0.3 官方件 / SAA 廉价线 / L1 九门 / W-CH-α 渠道路）；虚线（stroke-dasharray 6 4）= 待建；远期紫 = 远期不投核心循环（Cocos）。 + + + 建设主干（纵向五步 · spike 门插在第二步与第三步之间） + + + + 第一步 · 建 + 搭 AgentScope、完成集成 + agent ＋ 循环的运行时底座（统一 Agent 类 · max_iters 放开为 Agent 内 ReAct 多轮）。从 L2 studio 编排演进，非 L1 裸 openai 主线；tier2 独立锁 2.0.3、fork 起步。 + + + + 第二步 · 建 + 配置外置做实 + prompt / 编排 / 模型全部输入可配、不发版可改（声明式为主 ＋ 脚本逃生口），并挂上可回溯轨迹。实现归线 A 阶段 2-3 —— 本档引用、不重排。 + + + + 0号 spike · 生死门 + 便宜模型能否自治写出那 56% 表现层? + 最小 AgentScope ＋ 硬编码配置即可先验 —— 不必等第一二步全做完。 + 最深、最没证过的风险，在把全引擎生态铺开前先便宜地证一遍；不过即按退路树走（见右侧 G5），绝不滑成无限调参。 + + + + 第三步 · 建 + 以 Phaser 为范例搭生成引擎 + spike 证成后开建，边搭边反哺第一二步。表面搭引擎，底下藏五块必须显式排进去的硬工作（见下「隐藏硬工作 · 第三步」）。 + + + + 第四步 · 建 + Phaser 自治生成一款过人审 + 对标肥鹅美食街，过确定性地板 ＋ 人工终审；产物是可回头改和扩的 Phaser 源工程（改源不改包）。藏三块硬工作(见下「隐藏硬工作 · 第四步」)。 + + + + 第五步 · 建 + 完善 Cocos 生态 ＋ 推进 Phaser 渠道 adapter + Cocos 是另一条轴（编辑器 / 人在环 / 3D / 渠道导出），放在 Phaser 证成之后、不进自治循环。渠道 adapter 走 W-CH-α 已实证到 P0 的「轻 H5 ＋ 自研 adapter」路。 + + + + + + + + + + 过（go）→ 第三步 + + + + 不过（no-go）→ 退路树 + + + + + 隐藏硬工作 · 第三步（不补就埋雷 · 必须显式排进去） + ① 验收地板 —— L1 确定性门泛化到 Phaser ＋ 为经营品类补确定性 driver ＋ 跨表语义门。 + ② Goodhart 安全 —— agent 自产取证 driver 过平台白名单 ＋ 独立评审；写者不能写判自己游戏的卷子。 + ③ 成本强制 —— 官方 ReplyBudgetControlMiddleware 软刹 ＋ 自建硬熔断（超时/卡死/硬杀，MiddlewareBase 子类）。 + ④ 源项目契约 —— 文件树 manifest / 构建 profile / 依赖锁 / 落库寻址，这步真接上。 + ⑤ 可观测早建 —— 官方 TracingMiddleware 把每步推理/动作/观察吐成 typed event 流进 Studio ＋ 成本台账。 + 现状均 best-effort；规模化前必须落地。可观测是复利中台唯一该在这个阶段建的部分。 + + + + 隐藏硬工作 · 第四步（把「人审」做实，不是创始人亲玩一票） + ① 终审判据 —— 把「好玩」拆成可复核的几条、压个人品味方差。 + ② 终审吞吐模型 —— 否则 premium 量一上来，人审变瓶颈或橡皮图章。 + ③ player panel 减负 —— 判明显劣化信号（可达性 / 空内容这些确定性可逼近的）给人门减负。 + 承接：终审地板 = 第三步「验收地板」泛化的 L1；终审吞吐与 panel 都是为「人审不成瓶颈」服务。 + 产物 = 可维护、可回头改和扩的 Phaser 源工程（改源不改包），非生成完就完的一次性产物。 + + + + 补齐 + + 补齐 + + + + 退路树 · no-go 时按三条数字触发线分流（放大见 G5） + 看矩阵级 过门率 ＋ fail_system 分布，按下列触发线走，绝不滑成无限调参。 + + + v4-pro 仍 ＜40% ∧ 失败集中表现层 → 退向更模板化（更多预制表现模板、少 LLM 写） + + + 某系统装不出 ∧ 其余能过 → 补骨架再试（判骨架/driver 缺口，非范式问题） + + + 便宜档全线 ＜20% ∧ 强模型基线能过 → 便宜模型天花板（换贵模型重估经济 / 整轨缓行） + + 既非全线崩、也非天花板 → 留观：据具体数微调前置物再跑。门阈值标 ★ 需创始人 ＋ 实测校准。 + + + + 本图相关生产维度 + 质量 + spike = 在最便宜时验最深质量赌注（56% 表现层能否自治写出） + 成本 + 第三步「成本强制」软刹 ＋ 硬熔断；退路含 ★ ¥3/款 上限触发线 + 可观测 + 第三步「可观测早建」TracingMiddleware ＋ 成本台账，spike 调试当下就要 + 安全 + Goodhart 安全：自产 driver 过白名单 ＋ 独立评审，写者不判自己的卷 + + + 映射：docs/architecture/架构/生成引擎/tier2实现详设.md §建设五步与 0号 spike 生死门（含 mermaid）＋ §退路树（放大见 G5）＋ §三层校验（L1）｜ 状态：建（tier2 待建 · 五步 ＋ spike 生死门）｜ 设计变动须同步本图 + 承接《agentic 运行时架构图说》（看图入口）的「建设/spike」一面逐项放大：deepen 不 duplicate —— 总览给系统全景与对象结构，本图给五步顺序、spike 插点、隐藏硬工作与退路触发线的细节。 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-G-02-mini肥鹅靶子.svg b/docs/architecture/架构/生成引擎/assets/t2-G-02-mini肥鹅靶子.svg new file mode 100644 index 00000000..96ab253a --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-G-02-mini肥鹅靶子.svg @@ -0,0 +1,163 @@ + + + + + + + + + + + + 图 G2 · mini-肥鹅 靶子规格（族 G） + 0号 spike 对照组的确切靶子：砍到能证、又保住三本质难点（多系统耦合 / 重 UI 表现层 / 数值经济闭环）的最小经营游戏。结构参照 wanglanmei-ref 但更小。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；本图是 spike 对照组「人工预建骨架 + 人工预建 driver」的施工规格。 + 虚线（stroke-dasharray 6 4）= tier2 待建的 spike 靶子工程；红线 = 胜负 latch 终态。三系统的数据表与耦合点都按本图预建为平台代码。 + + + 质量 + 数据 + 可靠 + 成本 + + + + + 合成系统 + 重 UI 表现层主承载 + 3×3 棋盘 · 点两个相同物品合成上一级 + 承载棋盘格渲染 / 点击命中 / 合成动画（那 56% 表现层的主要承载） + + + mergeChains: [{ from, to, cost }, ...] + 6 条链 · 覆盖 12 物品 · 产出进资源库存 + + + + + + + + + + + 3×3 棋盘 + 点两个同物品 + → 合成上一级 + + + + 资源系统 + 读写交汇点 + 2 种货币：金币 + 食材库存（其余两系统的读写交汇） + 合成消耗食材 · 订单产出金币 · 解锁花金币 — 都读写这张表 + + + state = { coins, ingredients: { [id]: number } } + 一张极小的表 · 开局 coins=20 + + + addCoins(n) + + consumeIngredient(id) + 金币门控：攒够金币解锁第 4 / 5 摊位、更高合成链（读金币、改可玩范围） + 跨表可达性约束在此交汇 — 三系统不是孤岛，资源表是耦合枢纽。 + + + + 订单系统 + 数值经济驱动 + 面板列 3~5 个顾客订单 · 要物品给金币 + 每个订单有 patience；耐心耗尽即订单流失 + + + orders: [{ id, requires, reward, patience }] + 5 个模板 · requires 须能被合成产出满足（跨表可达） + + + requires + reward 金币 + patience ▼ + 完成订单： + 扣物品 + addCoins + 流失：耐心归零 + + + + + 合成产出进库存 + consumeIngredient 扣食材 + + + + 完成订单扣物品 + addCoins 加金币 + + + + 金币门控解锁 + 第 4/5 摊位 + 更高链 + + + + 合成产出须满足订单 requires（跨表可达性 — 本 spike 的核心考点） + + + 胜负条件 · 两条路径都要能被 harness 真输入驱动跑到终态并 latch + + + + 赢 = 金币达 100（开局 20 攒上去） + 正循环路径：合成 → 凑齐订单物品 → 交单收金币 → coins 涨 + driver 真输入序列：点合成格 → 凑齐订单物品 → 交单 → 看金币涨，反复直到 coins ≥ 100。 + latch: win 终态(不可逆) + harness 轮询读到 latch 即判赢，确定性可验。 + + + + 输 = 连续 3 个订单流失 + 破产路径：只合成不交单 / 经济崩盘 → 订单耐心连续耗尽 + driver 真输入序列：让 3 个订单 patience 连续归零（不交单），触发连续流失计数。 + latch: lose 终态(不可逆) + harness 轮询读到 latch 即判输，确定性可验。 + + + + + 内容量：足够证数据驱动，又不至让 spike 本身变重 + + + 12 + 物品 + + 6 + 合成链 + + 5 + 订单模板 + + 2 + 货币（金币 + 食材） + 数据表留空给 LLM 填值，骨架（三系统 + 耦合点）按本图预建为平台代码、先天过 boot。 + D3 富游戏门（跨表联动 / 经济 / latch）是在这靶子上加的；本图是靶子本身的施工规格，不是验收门定义。 + + + + 相对 wanglanmei-ref 的砍法（更小、保本质） + 参照：game-runtime/games/wanglanmei-ref + （12 文件约 180KB 多系统经营游戏，赢输双路径已证） + 砍掉：任务弹窗 · 背包深度 · 上百物品 + 保留：三个联动系统 + 确切耦合点（spike 考点） + + + 映射：docs/architecture/架构/生成引擎/tier2实现详设.md §靶子游戏 mini-肥鹅（含三系统耦合 mermaid）· §过门判据（latch / 胜负阈值）· §前置物清单（人工预建骨架 + driver）｜ 状态：建（tier2 待建·spike 靶子施工图）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-G-03-模型矩阵与跑序.svg b/docs/architecture/架构/生成引擎/assets/t2-G-03-模型矩阵与跑序.svg new file mode 100644 index 00000000..5e4fdf82 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-G-03-模型矩阵与跑序.svg @@ -0,0 +1,170 @@ + + + + + + + + + + + + 图 G3 · 模型矩阵 + 跑序（族 G） + spike 跑哪几档模型、每档跑多少样本、按什么顺序跑：先 M3 证路通不通，再便宜档比成本守不守得住。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；本图是 spike 的模型矩阵与跑序规格，照它跑。 + 实线 = 现行已落（new-api 出口 / mini-desktop 构建+e2e 门 / deepseek 两档已是廉价线在产模型）；虚线（stroke-dasharray 6 4）= tier2 spike 待建（自治多轮接法 / M3 原生接法 / 自治产物判定）。 + + + + 本图相关生产维度： + 成本 + 质量 + 可观测 + 成本 = 便宜档比单款¥；质量 = 过门率/收敛步数；可观测 = 每档 n≥30 真跑、采集字段可对账（产出三张图喂 go/no-go）。 + + + ① 模型矩阵 — 三个产出数（过门率 / 成本 / 收敛步数）都要有归属对象，「60% 是哪个模型的 60%」才答得上来 + + + + 角色档 + + 模型 + + 说明 + + 样本量 / 进成本评估? + + + + 主力便宜档 + 现行 + 实线 = 在产模型 + + deepseek-v4-flash + Tier0/1 廉价线打底模型 + tier2 自治的主力候选 + + 现行 Tier0/1 打底模型，tier2 自治的主力候选。 + spike 真正要回答的「便宜到什么程度还守得住」就是看它 —— 把模型降到主力便宜档， + 过门率与单款成本各掉多少。 + + n ≥ 30 真跑 + 进成本评估 + 承「别拿单次当基线」硬教训 + + + + 强便宜档 + 现行 + 实线 = 现行救场档 + + deepseek-v4-pro + 现行救场档 + 「贵一档便宜模型」 + + 现行救场档，测「贵一档便宜模型」是否显著抬过门率。 + 退路树第一条触发线直接读它：最强便宜档 v4-pro 过门率仍 ＜ 40%、且失败集中表现层， + 判 56% 自治承重太重 → 退向更模板化。 + + n ≥ 30 真跑 + 进成本评估 + 退路树「最强便宜档」锚点 + + + + 中等 agentic 档 + 先证路 + 这批最能打 + 虚线 = 原生接法待建 + （见 C2 放大） + + MiniMax-M3 + 能力比 Sonnet 略强、接得通 + 接法：官方 AnthropicChatModel + → new-api /v1/messages + + 这批最能打，先用它证路（见下「跑序」）。 + 接法走官方 AnthropicChatModel + AnthropicChatFormatter（构造不传 formatter 即自动配对）， + AnthropicCredential.base_url 指向 new-api 的 Anthropic 端点（/v1/messages）， + 吃原生 Anthropic 协议 + agentic 工具循环；接法逐项见 C2，本图不重画。 + + n ≥ 30 真跑 + 进成本评估 + 但先单独证路那一步 + 是亲玩判定、不是统计 + + + + 强模型基线 + 上限基线 + 远期不押 · 仅作天花板 + + Opus / Fable + 最贵档、只验路通不通 + 不是 tier2 量产模型 + + 只跑 1~2 款作「路通不通」的上限基线。 + 退路树第三条读它：便宜档全线 ＜ 20%、而强基线 Opus/Fable 能过 → 判便宜模型天花板， + 换更贵模型重估经济性（撞 ¥3/款 上限就缓行）或整轨缓行。 + + n = 2~3 + 不进成本评估 + 只判上限、不算单价 + + + ② 样本量与题面 — 5 个一句话变体 × 每档每变体 6 次 = 凑够 n≥30；跑在 mini-desktop（权威构建 + e2e 门 + x86 同构） + + + 题面：5 个一句话变体（经营品类） + 美食 + 水果 + 咖啡 + 面包 + 糖水店 + 每变体每档跑 6 次 → 5 × 6 = 30，凑够 n≥30；每个便宜/中等档都铺满这张 5×6。 + 强基线 Opus/Fable 不铺满，n=2~3 即可（只验上限）。 + + + 跑在 mini-desktop + 现行 + 权威构建机（实线 = 已有） + 权威构建 + e2e 门 + x86 同构 + + 禁本机 6c6g 跑 chrome（exit 144 / OOM 红线）。 + + + + 承袭硬教训 + 质量 + 「先跑 n≥30 真基线、 + 别拿单次当基线」—— + 单次跑数不可作过门率依据。 + + + ③ 跑序（创始人 2026-06-21 定）— 不一上来把整张矩阵 × n≥30 全铺开 + + + + 先 · M3 证路 — 证「这条路走不走得通」 + M3 全流程自治产一款 mini-肥鹅，创始人亲玩判有没有「肥鹅味」（软门·人锚）；走不通就别在更便宜模型上空耗。 + + + + + + + 证通再 · v4-flash / v4-pro 各跑一轮 n≥30 比成本 — 证「便宜到什么程度还守得住」 + 看把模型降到主力便宜档，过门率与单款成本各掉多少；Opus/Fable 仍只作路通不通上限基线、不进成本评估。 + + + 映射：docs/architecture/架构/生成引擎/tier2实现详设.md §模型矩阵与样本量（模型矩阵表 + 跑序 2026-06-21）· M3 接法逐项见 C2（放大）· 项目记忆 m3-agentic-anthropic-protocol ｜ 状态：现（deepseek 两档/mini-desktop 已有）/ 建（tier2 spike 矩阵）/ 缓（Opus·Fable 仅基线）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-G-04-过门阈值与采集字段.svg b/docs/architecture/架构/生成引擎/assets/t2-G-04-过门阈值与采集字段.svg new file mode 100644 index 00000000..1604f4e5 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-G-04-过门阈值与采集字段.svg @@ -0,0 +1,139 @@ + + + + + + + + + 图 G4 · 过门阈值 + 采集字段（族 G） + 0号 spike 的 go/no-go 怎么判：5 维过门判据（数字阈值）+ run 级采集字段 → 汇成矩阵级三张图当直接输入。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；阈值标 ★ 的是建议值（需创始人和实测校准），其余承袭现行线硬约束。 + 虚线（stroke-dasharray 6 4）= tier2 待建机制（spike 阈值 / 采集字段 / 三张汇总图）；实线 = 承袭现行已落口径（factory 60% / cutover 80% / L1≤¥0.15·L2≤¥5 / new-api quota·cost.py）。 ★ = 建议值待校准。 + + + + 本图相关生产维度： + 质量 + 数据 + 成本 + 质量 = 过门率/收敛/长程一致性；数据 = run 级采集字段是 go/no-go 的可对比底料；成本 = ¥/成功款（new-api quota 折¥）。 + + + A · 过门判据与精确阈值（5 维 · 全绿才 go） + + + + ① 过门率 + 质量 + ★ ≥ 50% 起评 · ≥ 70% 算强信号 + 判据 = L1 确定性门 ＋ 三联动门 ＋ 经济门全绿 ＋ latch 终态。 + 来源：对照现行 factory 路 60% / cutover 门 80%（实线承袭）；tier2 富游戏更难， + spike 阶段先看是否显著大于 0、能否随模型档升。 + + + + ② 单款成本 + 成本 + ★ ≤ ¥3 / 成功款 + 来源：现行 L1 ≤ ¥0.15、L2 ≤ ¥5（实线承袭）； + tier2 premium 取 L2 偏下的 ¥3，留自治多轮的空间， + 撞 ¥3/款 上限即触发退路树「换更贵模型重估经济性 / 缓行」。 + + + + ③ 收敛步数 + 质量 + ≤ max_iters（★ 单系统 ≤ 8 轮 · 整局 ≤ 40 轮） + 来源：防靠运气擦边；超 max_iters 即判不收敛。 + 对照第一步 AgentScope 2.0.3 ReActConfig.max_iters 默认 20；tier2 自治放开。 + + + + ④ 长程一致性 + 数据 + 12+ 文件工程过程无丢失、半轮幂等无脏 + 判据 = 12+ 文件工程过程中无 checkpoint 丢失、 + 半轮副作用幂等无脏。来源：采集字段直接读（见右侧 B 区长程三字段）。 + + + + ⑤ 人锚 · 软门，不可替代 + 创始人试玩判一句「是不是个有肥鹅味的可玩雏形」 — 软门、不可被任何确定性指标替代，但单它也不构成 go。 + 前四维是数字硬门（全绿才 go），第五维是人锚软门：四维过了人锚却没味，仍按退路树「退向更模板化」等分流，不强行放行。 + + + B · run 级采集字段（每款一行 · 取处明确，无定义则跑完拿不到可对比数） + + + + 标识 + 数据 + run_id / model + stage（1 或 2） + brief_variant + 5 题面变体 × 模型档定位每行 + + + + 过门 · pass / repairs + 质量 + pass + = L1 ＋ 三联动门 ＋ 经济门 ＋ latch 全绿 + （确定性 · 取 verdict.pass） + repairs + = 自治循环轮数（取 studio attempt 计数） + + + + 失败定位 · fail_stage / system + 质量 + fail_stage + extract / validate / build / seven_gate / + 三联动门 / 经济门（承 studio stage_fail） + fail_system + resource / merge / order / 表现层（经营品类特有） + + + + 成本 · cost / tokens / wall + 成本 + cost_rmb / tokens_by_model + per-model token 折¥ + （取 new-api quota 口径 · cost.py） + wall_s + 墙钟（单款端到端耗时） + + + + 长程一致性 + 数据 + file_count / total_loc + （产物工程文件数、总行数） + ctx_compressed / checkpoint_recovered / idempotency_clean + 是否触发上下文压缩 / checkpoint 恢复是否无损 / 半轮副作用是否幂等无脏 — 直接喂判据④。 + + + + 自产 driver 安全 + 仅第二段 + driver_authored / driver_rejected_by_review / driver_edits + 自产 driver 数 / 被独立 adversarial 评审打回比例 / driver 修改次数 + （Goodhart 安全：防它用改 driver 逃避卡死探测 — 第一段不采、driver 是人预建的）。 + + + + 汇总到矩阵级（每模型档）→ go/no-go 直接输入：① 过门率 = pass 款数 / n ② ¥/成功款 = Σcost / pass 款数 ③ 收敛中位数 ④ fail_system 分布 — 对照 A 区阈值与退路树触发线判。 + + + 映射：docs/architecture/架构/生成引擎/tier2实现详设.md §过门判据与精确阈值 ＋ §采集指标字段表（汇总三张图见同档退路树触发线）｜ 状态：建（tier2 待建 · spike 阈值 ＋ 采集字段；★ 需创始人和实测校准）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-G-05-两段实施与退路树.svg b/docs/architecture/架构/生成引擎/assets/t2-G-05-两段实施与退路树.svg new file mode 100644 index 00000000..2f02aa25 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-G-05-两段实施与退路树.svg @@ -0,0 +1,238 @@ + + + + + + + + + + + + 图 G5 · 两段实施 + 退路树（族 G） + 0号 spike 怎么跑：变量隔离的两段（纯模型变量 → 开放自产 driver）+ 两段间 gate 铁律 + 据数字触发线分流的退路树。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；本图是「怎么验、崩了往哪退」的可执行 runbook。 + 虚线（stroke-dasharray 6 4）= tier2 专属待建机制（两段实施、自产 driver 三层隔离、退路分流）；实线 = 现行已落件（L1 确定性门 / new-api 计费 / studio.py 躯干 / harness 四件套）。 + 徽章：质量 = spike 证「便宜模型能否自治写出那 56% 表现层」这个最深赌注；安全 = 第二段 Goodhart 防线（自产 driver 三层隔离）；成本 = ¥3/款 成本闸。 + + + 质量 + 安全 + 成本 + 可观测 + + + 两段实施 · 变量隔离（每段：固定什么 / 跑什么 / 测什么） + + + + 第一段 · 纯模型变量 + driver 是人预建的、不让 agent 碰 —— 只测「填差异」这一个变量 + + + + 预建（人投入 · Opus 或人写 · 实线＝靠现行件） + 固定人工骨架：mini-肥鹅 经营骨架工程（三系统 + 耦合点，先天过 boot） + + 人工 driver（点合成 / 凑单 / 交单 的确定性序列，预建、冻结） + + 数据表 schema（12 物品 / 6 链 / 5 订单，留空给 LLM 填）+ 共用资产池占位图 + + + + 跑（便宜模型自治填那 56% · 待建） + 便宜模型在骨架上 填数据表 + 写表现层（场景渲染 / 事件接线 / 特色规则） + Agent 内 ReAct 多轮（max_iters 放开，非 studio 现行 max_iters=1 + 外层 repair）： + 写源 → build → headless 快检 → L1 门 → 读 verdict → 改 + spike 最小版 = 最小 AgentScope + 硬编码配置；不上 service / Agent Team / 配置外置。 + + + + 采集 + 第一段 gate + 采集（run 级）：pass / repairs / ¥ / wall / fail_system / 长程一致性 + gate ＝ 过门率 / 成本 / 收敛 是否达阈值（★≥50% 起评 · ★≤¥3/款 · ≤max_iters） + + + + + + + + 第二段 · 开放自产 driver + 第一段证通才进 —— 测自治上限 + Goodhart 安全（自产 driver 三层隔离） + + + + 放开：让 agent 自产 / 扩 harness driver · 走三层隔离（见 D4） + + + ① agent 提议 driver + 写者提交取证脚本， + 但不许直接当判据。 + + ② 平台编译 + 按 schema / 白名单 + 编译，越界即拒。 + + ③ 独立 adversarial 评审 + 查是否覆盖真实玩家 + 路径、是否读作弊字段。 + 三层隔离要点：写者不能写判自己游戏的那张卷子（防 Goodhart）。 + + + + + + + 跑 + 采集（额外两列） + driver_rejected_by_review（被独立评审打回比例）· driver_edits（防它改 driver 逃避卡死探测） + + + + 第二段 gate ＝ 自产 driver 不降过门可信度（独立评审通过率高） + ＋ 自治不烧穿成本闸（不超 ¥3/款） + + + + + + + + 过 + + + + 两段间 gate 铁律（卡得很清） + ① 第一段崩（纯模型变量就崩）→ 直接进退路树、不开第二段 —— 连固定 driver 都填不出来，放开让 agent 自产 driver 的开放自治只会更糟。 + ② 第一段过、第二段挂在 driver 安全 → 判 Goodhart 防线「设计」问题（不是模型问题）—— 模型能写出来，是隔离防线没拦住作弊，回去补防线、不是怪模型。 + + + + 崩 → 进退路树 + + + 退路树 · 据矩阵级「过门率 + fail_system 分布」三条数字触发线纵向分流（绝不滑成无限调参） + + + + + + + START + spike 跑完，看矩阵级 + 过门率 + fail_system 分布 + + + + + Q1：v4-pro 过门率仍 ＜ 40%？ + 最强便宜档（强便宜档 deepseek-v4-pro） + + + + Q2：失败集中在表现层？ + （render / 事件接线） + + + + Q3：某系统装不出、其余能过？ + （如合成棋盘命中几何反复错） + + + + + 是（＜40%） + + 否 + + + + + + + GO · 过门率达阈值 → 转第三步以 Phaser 铺引擎 + Q1 否（≥40%，达阈值）：最深赌注证成，进建设五步的第三步、边搭引擎边反哺。 + 人锚仍须过：创始人试玩判一句「是不是个有肥鹅味的可玩雏形」。 + + + + R1 · 退向更模板化 + 触发：v4-pro ＜40% 且失败集中表现层 → 判 56% 自治承重太重。 + 动作：更多预制表现模板、少 LLM 写。 + + + + R2 · 补骨架再试 + 触发：某系统装不出、其余系统能过 → 判骨架 / driver 缺口，不是范式问题。 + 动作：补该系统的骨架 / driver 缺口后再跑。 + + + + Q4：便宜档全线＜20% + 而强基线 Opus/Fable + 能过？ + + + + R3 · 便宜模型天花板 + 换更贵模型重估经济性 + （撞 ¥3/款 缓行），或整轨缓行。 + + + + KEEP · 留观 + 既非全线崩、也非天花板 + → 据具体数微调前置物再跑。 + + + + + + + 否（≥40%） + + + + + + 是，集中表现层 + + + + 是 + + + + + 否（其余系统也过不了 / 不集中） + + + + + + + + + + + 是 + + + + + 否 + + + 铁律：五条出口（GO / R1 / R2 / R3 / KEEP）都是「据数字裁定一步」—— 退路树真能被触发、不悬空，KEEP 也只许据具体数微调一轮，绝不滑成无限调参。 + + + 映射：docs/architecture/架构/生成引擎/tier2实现详设.md §两段实施步骤（含 mermaid）+ §退路树（含 mermaid）· §过门判据与精确阈值 · §采集指标字段表（fail_system / driver 安全列）｜ 状态：建（tier2 待 0号 spike 验证）｜ 设计变动须同步本图 + deepen 不 duplicate：两段实施与退路树承接《agentic 运行时架构图说》的 spike 判据，本图把两段 gate 铁律与退路三条数字触发线逐项放大（总览未展开）；自产 driver 三层隔离详见 D4。 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-H-01-trace统一契约.svg b/docs/architecture/架构/生成引擎/assets/t2-H-01-trace统一契约.svg new file mode 100644 index 00000000..04754a47 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-H-01-trace统一契约.svg @@ -0,0 +1,127 @@ + + + + + + + + + + + + 图 H1 · trace 统一契约（族 H） + 两条生成线的轨迹收成同一张表：一个对称的公共核心子集 + 各轨一个不对称的 JSON 扩展列；落成 contracts/trace/ 的 additive 契约，写不进去时 best-effort 不阻塞。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码；contracts/trace/ 这一位当前还没建（随 spike 或控制面 phase-1 落地时再新立、别当现成）。 + 实线 = 现行已落（SAA 廉价线节点裁决已在跑 / contracts 契约组已存在 / D12 治理门已有件）；虚线（stroke-dasharray 6 4）= tier2 专属待建机制 + contracts/trace 待立位。 + + + 可观测 + 数据 + + + + 消灭 split-brain 的真口径 = 诚实镜像，不是强求对齐 + 每条派发路诚实镜像它真有的字段、没有的绝不编造。tier2 的 ReAct「想-做-看」与 SAA 16 节点的阶段裁决本就不同构 —— 强求字段对齐是错的。 + 正确解：同一张表 = 一个对称的公共核心子集 + 各轨一个不对称的 JSON 扩展段；接口层对称、内容层不对称，这才是「一份契约管两条异构线」的成立条件。 + + + 统一表结构（放大总览图 7：图 7 只点了 tier2 扩展段，这里把对称核心 5 字段 + 两轨扩展段逐项展开） + + + + + + + 公共核心子集 · 对称 + 两条线都必有的最小集 · 字段同名同义 + + traceId一次生成的轨迹主键 + + step第几步 / 第几节点 + + cost这一步的成本（new-api quota 折¥） + + verdict这一步 / 这道门的裁决 + + timestamp发生时刻 + + + + SAA 扩展段 · JSON 列 + 廉价线已落 + 16 节点阶段裁决形态 + + 阶段 （当前跑到 16 节点里的哪个阶段） + + 修复轮次 （外层 repair 循环第几轮） + + 门裁 （现行确定性九门各门的判定） + 采集机制：SAA Java 线按它自己的节点裁决埋点。 + + + + tier2 扩展段 · JSON 列 + 待建 + ReAct「想-做-看」形态 + + 推理 （这一步「想」了什么 · ThinkingBlock） + + 动作 （调了哪个工具 · ToolCall） + + 观察 （工具回了什么 · ToolResult） + 采集机制：订阅 AgentScope typed Event System，无须自己埋点。 + + + 同一张表 + 各写各的 + + + + + SAA adapter（Java 线） + 承现行 + 按 16 节点的阶段裁决埋点， + 经 adapter 映射进同一份契约。 + 采集机制按自己框架来，数据口径走平台契约。 + + + + tier2 adapter（Python 线） + 待建 + Event System → TracingMiddleware → OTel + 官方管道汇进 Studio，再加一层 adapter 把事件 + 按「公共核心子集 + 扩展段」映射进统一表。 + + + + contracts/trace/ + additive 待立 + 契约组新一类 additive 立位 · 含四样： + · 字段定义　　　· schema 版本 + · 敏感字段脱敏规则　· 两条线 adapter 怎么映射 + + + + + + 两条线机制各异、契约一致 —— adapter 各自把轨迹按统一表写进 contracts/trace/ + + + + 写不进去时的策略 = best-effort 不阻塞，但计入告警（要选边、不能既要又要） + 轨迹写失败时默认 best-effort —— 不阻塞主生成流程，但落一条告警。不能让一次落库抖动把整局生成废掉。 + 这是「接口对称、内容不对称」在可观测面的落点：契约是数据口径不是采集机制，采集两条线各按各的框架来，数据口径不随框架漂移。 + 价值：任何一次生成都能反查「它当时用的哪几条配置的哪个版本」—— 才能回答「那批游戏质量掉了，是不是上周改的那条 prompt 干的」。 + + + 映射：docs/architecture/架构/生成引擎/tier2实现详设.md §统一 trace 契约的实现接点 · agentic集成架构.md §观测/审计仓（运行轨迹）+§接口对称内容不对称 · （放大总览图 7）agentic运行时架构图说.md 图7 trace 契约 ｜ 状态：建（tier2 待建 · contracts/trace additive 待立；SAA 廉价线节点裁决已落）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-H-02-观测管道.svg b/docs/architecture/架构/生成引擎/assets/t2-H-02-观测管道.svg new file mode 100644 index 00000000..761066fd --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-H-02-观测管道.svg @@ -0,0 +1,177 @@ + + + + + + + + + + + + 图 H2 · tier2 观测管道（Event System → OTel → Studio） + tier2 不自造埋点：订阅官方 typed Event System，走 TracingMiddleware → OTel 官方管道，再加一层 adapter 映射进 contracts/trace 统一表。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证、尚未落代码。Event System / TracingMiddleware / OTel / Studio 是 AgentScope 2.0.3 官方现成件（源码已核），adapter 为自建。 + 实线 = 官方现成件 / SAA 廉价线已落 / 已有件；虚线（stroke-dasharray 6 4）= tier2 专属待建机制（订阅事件流、adapter、统一 trace 契约位）。 + + + + 可观测 + + + tier2 写轨迹的官方管道（横向链路） + + + + Agent Event System + 官方 typed + ReAct agent 每跑一步 + 吐一套强类型事件流。 + 不必自己埋点—— + 框架自带完整事件系统。 + agentscope/event/_event.py + + + + TracingMiddleware + 官方 + 中间件直接调真 OTel SDK： + start_as_current_span + 把事件转成 span， + 挂 attributes / status。 + middleware/_tracing/_trace.py + + + + OpenTelemetry span + 标准 + 标准链路追踪 span： + agent / llm / tool 三类 + span_name，OK / ERROR 状态。 + 真 OTel SDK（非 mock）， + 可对接标准后端。 + + + + AgentScope Studio + 官方 + 可视化每次生成： + 逐步推理 / 工具调用 / + 模型用量 / 一轮回复边界。 + 开箱即用， + 不必自造前端。 + + + + + + 订阅 + 转 span + 汇入 + + + + 一句话 + tier2 写轨迹 + = 订阅事件 + + 官方 OTel 管道 + + 一层 adapter。 + 不自造埋点， + 不自造前端。 + + + 事件流逐类（强类型 · 源码 agentscope/event/_event.py 逐条核过） + + + + + TextBlock* + 文本块 + Start/Delta/End + + + + ThinkingBlock* + 思考块 + Start/Delta/End + + + + ToolCall* + 工具调用 + Start/Delta/End + + + + ToolResult* + 工具结果 + Start/...Delta/End + + + + ModelCallStart / End + 模型调用边界 + End 带 token 用量（input/output_tokens） + + + + ReplyStart / End + 一轮回复边界 + 圈住一步 reason→act→observe + + + adapter 层：两条线机制各异、契约一致（接口对称、内容不对称） + + + + tier2 adapter + 待建 + 订阅上面的 Event System，把事件按 + 公共核心子集 + 扩展段映射进统一表。 + 扩展段（tier2 独有）：推理 · 动作 · 观察 + 机制 = 订阅 typed 事件流（非节点裁决埋点）。 + + + + SAA adapter（Java 线） + 廉价线已落 + SAA 按它自己的 16 节点裁决埋点， + 走同一份契约的 adapter。 + 扩展段（SAA 独有）：阶段 · 修复轮次 · 门裁 + 机制 = 节点裁决埋点（非订阅事件流）。 + + + + contracts/trace 统一表 + 契约位待建 + 公共核心子集（两线对称）： + traceId · step · cost · verdict · timestamp + 扩展段：各写各的（JSON 扩展列） + 同一张表，第 9 类 additive 契约位（尚未建） + + + + + + + + tier2 订阅 + + + + trace 契约是数据口径、不是采集机制 —— 采集两条线各按各的框架来 + 写不进去时的策略要选边：默认 best-effort 不阻塞主流程（轨迹写失败 → 计入告警、生成继续），而非阻塞生成。契约位含字段定义 · schema 版本 · 脱敏规则 · 两线 adapter 映射。 + 消灭 split-brain 的真口径 = 每条派发路诚实镜像它真有的字段、没有的绝不编造，不是强求两线字段对齐。tier2 不必埋点（订阅 Event System），SAA 按节点裁决埋点 —— 机制各异、契约一致。 + 价值：任何一次生成都能反查「它当时用的哪几条配置的哪个版本」，才能回答「那批游戏质量掉了，是不是上周改的那条 prompt 干的」。存储复用已部署 MySQL + 对象存储，不上重型可观测中间件。 + + + 映射：docs/architecture/架构/生成引擎/agentic集成架构.md §观测/审计仓（Event System → TracingMiddleware → OTel → Studio）· agentic运行时架构图说.md §6 术语映射（可观测 = Event System，放大总览图 6）· 源码 agentscope/event/_event.py + middleware/_tracing/_trace.py ｜ 状态：建（tier2 待建 · Event System / TracingMiddleware 官方现成，adapter + contracts/trace 自建）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/assets/t2-H-03-成本台账.svg b/docs/architecture/架构/生成引擎/assets/t2-H-03-成本台账.svg new file mode 100644 index 00000000..c9adac98 --- /dev/null +++ b/docs/architecture/架构/生成引擎/assets/t2-H-03-成本台账.svg @@ -0,0 +1,105 @@ + + + + + + + + + 图 H3 · 成本台账（RecordingChatModel → new-api quota）（族 H） + tier2 成本怎么对账到每款：补一个 RecordingChatModel(AnthropicChatModel) 变体抓 token → new-api quota 权威口径折¥ → 采集字段 cost_rmb / tokens_by_model（每款一行）。 + + + + 整图状态 = 建：tier2 整轨待 0号 spike 验证；其中 RecordingChatModel(Anthropic) 变体待补——现有成本记录只覆盖 OpenAI 路，不补则 A 门 M3 成本抓不到。 + 实线 = 现行已落（new-api 计费平面 / quota 权威口径 / cost.py 读 logs.quota）；虚线（stroke-dasharray 6 4）= tier2 专属待建机制（RecordingChatModel 变体、M3 Anthropic 路成本采集）。 + + + + 生产维度 + 成本 + 数据 + 成本 = 不是估的，是从 new-api quota 权威口径折出来的 per 款¥；数据 = cost_rmb / tokens_by_model 落 run 级采集字段、每款一行（见 G4）。 + + + 接点 · 成本台账要补一个 RecordingChatModel(AnthropicChatModel) 变体 + + + RecordingChatModel(AnthropicChatModel) + 待补 + tier2 专属新机制 + 包住模型调用、抓每次 token 用量（per-model）。 + M3 走 AnthropicChatModel（见 C2），所以要补一个 Anthropic 路的 + 录制变体；现有成本记录只覆盖 OpenAI 路。 + 不补的代价 ↓ + + + + 红线 · 不补则 A 门（spike）的 M3 成本抓不到 + 现有的成本记录只覆盖 OpenAI 路——M3 走 Anthropic 原生端点（/v1/messages）。 + A 门 = M3 先证路那一段（先用 M3 证路，再用便宜档比成本）。M3 这档的 token 用量 + 若没有对应的录制变体包住调用，就采不到，¥/成功款 这个数对 M3 直接缺。 + 便宜档（deepseek-v4-flash / v4-pro）走各自端点，由现有 OpenAI 路的记录覆盖； + 缺的就是 Anthropic 这一路——补上才能让全矩阵成本可对比。 + + + 折算链路 · token（per-model）→ new-api quota 折¥ → 采集字段 + + + + ① 抓 token + 待补 + RecordingChatModel 包住每次模型调用 + 逐次记 token 用量，按模型分列 + tokens_by_model（per-model） + + + + ② new-api quota 折¥ + 现行 + 权威成本源（已落） + new-api 的 quota 口径折人民币 + cost.py 读 new-api logs.quota + （每次调用 quota = 真实倍率成本，权威） + + + + ③ 落采集字段 + 数据 + run 级 · 每款一行（见 G4） + cost_rmb / tokens_by_model + 汇到矩阵级：¥/成功款 = Σcost / pass 款数 + → go/no-go 三张图的成本输入 + + + + + token + ¥ + + + + 计费平面 · 模型统一从 new-api 出口走，不论走哪条端点，计量都收口到 new-api quota 一个计费平面（成本可对账） + M3 走 Anthropic 原生端点（/v1/messages）、便宜档（deepseek-v4-flash / v4-pro）走各自端点；协议 / SDK 不锁死，每档走它各自最优端点。 + + + + M3 → Anthropic 端点（/v1/messages） + + v4-flash / v4-pro → 各自端点 + + new-api quota 计费平面 + all roads 收口到一个口径，per-model 折¥ + + + 计量收口（quota） + 一句话：成本不是估的，是从 new-api quota 权威口径折出来的 per 款¥；凭据见 docs/内网凭据与端点.md（NEWAPI_KEY / 端点 / 机器）。 + + + 映射：tier2/HANDOFF.md §接着做（U7 成本取证：RecordingChatModel(AnthropicChatModel) 变体）· docs/architecture/架构/生成引擎/tier2实现详设.md §采集指标字段表（cost_rmb / tokens_by_model）· 项目记忆 newapi-billing-plane-integration（quota 权威成本源 · cost.py 读 logs.quota）· 接法见 C2 底带 / 采集字段落处见 G4 ｜ 状态：建（RecordingChatModel(Anthropic) 变体待补）/ 现（new-api quota 计费平面已落）｜ 设计变动须同步本图 + diff --git a/docs/architecture/架构/生成引擎/tier2细节图说-A-运行时形态.md b/docs/architecture/架构/生成引擎/tier2细节图说-A-运行时形态.md new file mode 100644 index 00000000..2b5c12a8 --- /dev/null +++ b/docs/architecture/架构/生成引擎/tier2细节图说-A-运行时形态.md @@ -0,0 +1,93 @@ +--- +date: 2026-06-23 +topic: tier2 细节图说 · A 族——运行时形态(Agent Service / 非常驻 + AgentState / Workspace 双轴 / Middleware 洋葱) +status: 设计中(tier2 待 spike) · 每图映射源档见该图脚注 / frontmatter 记 hash 作防漂移门 +映射源档: + - { doc: "docs/architecture/架构/生成引擎/tier2实现详设.md", hash: "d5efe45f" } + - { doc: "docs/architecture/架构/生成引擎/agentic集成架构.md", hash: "1b3e375a" } + - { doc: "docs/architecture/架构/生成引擎/agentic运行时架构图说.md", hash: "32adda95" } + - { doc: "docs/architecture/架构/生成引擎/tier2四层工程架构.md", hash: "d5efe45f" } +--- + +# tier2 细节图说 · A 族 —— 运行时形态 + +> 本篇是绘境AI 架构图集 **生成引擎子树** 下的 tier2 细节图说,只覆盖 **A 族(运行时形态)** 四张图。生成引擎主干、tier2 总览、自治富游戏验收各有自己的图说;这里专门把「tier2 这条富游戏自治线跑起来到底长什么样」这件事画清楚——cloud 怎么接进去、agent 实例怎么活、执行环境怎么挂上来、横切关注点挂在哪。 + +--- + +## 0 阅读约定与同步纪律 + +A 族讲的是 tier2 富游戏自治生成线的运行时骨架——从 cloud 怎么经官方 Agent Service 接进来,到 agent 实例非常驻、状态全外置到 AgentState,再到 Workspace 沿两轴注入 agent,最后到成本与观测怎么统一挂在 middleware 洋葱上。这四件事是同一条运行轨的四个切面:图 A1 画接入面(cloud 怎么进、session 三条路怎么汇),图 A2 画 agent 的生命周期与断点续跑(非常驻怎么靠 AgentState + checkpoint 落实),图 A3 纠一个最容易踩的误解(Workspace 不是包着 agent、而是注入 agent),图 A4 画横切关注点的统一挂载点(成本刹车 / 硬熔断 / 观测挂在哪)。 + +这四张图映射四份属主设计档加 AgentScope 2.0.3 源码。运行时形态的总口径出自《tier2 实现详设》的「运行时形态:两阶段、service 化与 session 三路径」一节,接入面的逐 router 与 MessageBus 细节出自《agentic 集成架构》的「tier2 接入面」与「D12 运行治理门」两节,所有结构性事实——八个 router、AgentState 三字段、WorkspaceBase 三实现、MiddlewareBase 五钩子——都按 AgentScope 2.0.3 源码逐条核过(`agentscope/app/`、`state/_state.py`、`workspace/`、`middleware/`)。frontmatter 记了这四份的当前 commit hash,作为防漂移门——其中任一份动了运行时口径,本图说与对应 SVG 必须同步改。 + +整条 tier2 富游戏线现在 **整体待建**:0号 spike 还没跑,引擎没搭,代码一行没落。所以读 A 族时,「待建」是默认状态,绝不能因为图画得齐整就误以为运行时已经搭起来了。但「待建」不等于「全凭空想」——A 族里有一大块是 AgentScope 2.0.3 已经提供的现成件:官方 Agent Service(`create_app` 拉起的 FastAPI)、MessageBus(Redis 实现)、AgentState 模型与 StorageBase、WorkspaceBase 三实现、官方两个 middleware(预算软刹与 tracing),这些都现成、不用自造,图里用实线画。tier2 自己要做的是把这些现成件接成一条富游戏自治线:接官方 service、做非常驻装配与每轮 checkpoint、在官方 Workspace 抽象上挂 tier2 要的工具与资源、把硬熔断三件做成 MiddlewareBase 子类——这部分用虚线画。看图时记住这条对照:**实线 = 现行已落 / AgentScope 2.0.3 官方现成件,可以直接信;虚线(stroke-dasharray 6 4)= tier2 专属、待 0号 spike 验证后才落代码的接线。** 个别图上还有远期紫,标的是「设计已出但排在更长期层级」的元素(如 E2B 远端强隔离),不是 spike 期的投入项。 + +A 族是《agentic 运行时架构图说》的放大层,不是它的替代。那份总览图说里的图 1(系统全景)、图 2(调用时序)、图 3(运行时内部)、图 5(编排配置)、图 8(关键类图)给的是整体结构,A 族只把「运行时形态」这一面逐字段放大——总览图 3 把 Agent 与 Workspace 的整体结构画在一处,A 族则把非常驻装配、AgentState 三字段、双轴注入的两条轴、middleware 五钩子各自挂什么,一项一项展开。凡总览图已画清的整体结构,A 族不重画,只在脚注里指回去。这是 deepen 而非 duplicate:总览看轮廓,A 族看施工。 + +## 1 全图通用图例 + +A 族四张图共用一套视觉语言,先在这里讲清,后面每张图不再重复。 + +**线型承担状态语义。** 实线框 / 实线箭头 = 现行已落或 AgentScope 2.0.3 官方现成件(官方 Agent Service、MessageBus、AgentState、StorageBase、WorkspaceBase 三实现、官方 ReplyBudgetControlMiddleware 与 TracingMiddleware、D12 运行治理门),这些可以直接复用、不用自造。虚线框 / 虚线箭头(`stroke-dasharray 6 4`)= tier2 专属待建机制(非常驻装配、每轮 checkpoint 落 Redis、session 三路接线、注入工具集、D5 沙箱底座选型、硬熔断三件子类),还要写还要验。远期紫(紫框 / 紫底)= 设计已出但排在更长期层级的元素,典型是 E2B 远端强隔离对齐的多租户 / premium 层,不是 spike 期投入项。 + +**徽章标的是这块内容服务哪个生产维度。** 绿色的 **可靠**(断点续跑不丢、半轮副作用幂等)、**成本**(压住自治多轮的烧钱)、蓝色的 **可观测**(每步推理 / 工具调用可对账)、灰色的 **数据**(状态可持久化落库)、红色的 **安全**(沙箱隔离 = 写码真跑的信任边界)、紫色的 **伸缩**(远端沙箱撑多租户)。这些维度落到 A 族的具体接点上:可靠落在 SSE 可恢复与 resume 续跑,成本落在 middleware 洋葱的预算软刹与硬熔断,可观测落在 Workspace 统一面与官方 Event→OTel 管道,数据落在 AgentState→StorageBase 落库,安全落在 Workspace 三实现的隔离强度梯度。 + +**状态码四个,贯穿生成引擎子树。** **现** = 现行已建在跑或 AgentScope 2.0.3 官方现成;**接** = 设计已出、代码待接线;**建** = tier2 立项后要新建、当前待 spike;**缓** = 收窄后缓做 / 更长期层级。A 族绝大多数 tier2 自有元素是「建」,官方现成件是「现」,E2B 远端强隔离这类更长期项是「缓」。 + +## 2 图集 + +### 图 A1 · Agent Service 与 session 三路径 + +![图 A1 Agent Service 与 session 三路径](assets/t2-A-01-AgentService与session三路.svg) + +cloud 这边要调 tier2 生成一款富游戏,第一个要回答的问题是「接口在哪、长什么样」。这张图给的答案是:tier2 不自造这层 API,直接用 AgentScope 2.0.3 的官方 Agent Service。它是 `create_app` 拉起的一个 FastAPI 应用,对外是 REST 加 SSE,天生多租户、天生 durable session,源码在 `agentscope/app/` 里逐条核过。图中央那条横向三段链路就是 cloud 接 tier2 的真实姿势——game-cloud 经 REST `POST /sessions` 建一个会话,再经 SSE 收事件流;tier2 的单写 ReAct agent 跑在这层 service 之上。这么接的理由很直接:一个现成、已经把多租户和可恢复会话都做好的 service 摆在那里,自己重写一遍既慢又容易漏,不如直接用官方的,把力气省下来花在富游戏怎么造上。 + +图中段那排八个 router 和底下那行 MessageBus,是把「这层现成到什么程度」摆出来给人看清。八个 router——`/sessions`、`/chat`、`/schedule`、`/credential`、`/workspace`、`/model`、`/tts_model`、外加 agent 管理面——覆盖了一条生成线要用到的会话、对话、定时触发、模型密钥托管、执行环境、模型选择这一整套,全是框架现成件。底座是 MessageBus 的 Redis 实现,它撑起四样分布式协作能力:Redis Stream 做事件 replay 日志(晚到的订阅者能回放、不丢中间过程),pub/sub 做唤醒广播(worker 干完异步通知 leader、不必轮询),分布式锁保证同一会话同一时刻只被一个进程跑,取消信令支持中途叫停。这套底座直接决定了那条绿色的「SSE 可恢复」要点带能成立——cloud 收事件流时掉了线,重连后从 replay 日志续读、不必从头重跑,这正好兜住了「外部服务 / 异步任务要考虑超时、失败、断线」这条可靠性要求。一次富游戏生成可能跑很久,断线重连不丢进度是必须的,而这件事官方已经给了。 + +图底那三个并排的 session 加载路径,是这张图最该让人看出的设计取舍。tier2 把「游戏 = 长生命周期软件项目」这条基座裁定落到了运行时入口上:一款游戏不是一次性产物,所以进场方式不止「从零新建」一种。路径①是续接之前的会话,从 `SessionRecord.state` 取回历史工作记忆与轮次,接着往下 reason;路径②是加载一份已有游戏工程,把 `Workspace.workdir` 指向那个已存在的目录,进迭代模式(改源不改包、重新构建);路径③才是新建,由阶段 2 的模板初始化工具铺一套空骨架,再交单写 agent 写代码。关键在于这三条路最终汇到同一个 Agent 装配点——它们不是三套独立流程,只是初始 state / workdir 不同。把三种入场收敛到同一个装配点,而不是为每种入场各写一条链路,是这张图背后的简化决策。要注意的边界:整条 tier2 轨待 spike,这三条加载路本身都是 tier2 待建(虚线),而它们脚下的官方 Agent Service 与 MessageBus 是现成实线——接线待建,底座现成,这条虚实之分是读这张图时最该先盯住的一层。 + +### 图 A2 · Agent 非常驻 + AgentState + checkpoint + +![图 A2 Agent 非常驻 + AgentState + checkpoint](assets/t2-A-02-Agent非常驻与AgentState.svg) + +这张图回答「tier2 的 agent 实例到底怎么活、断了怎么续」。结论先放在最前面:agent 是一个无状态的 ReAct 引擎,实例非常驻——它不是一个长跑的进程,而是每次 run 现组装、跑完即弃,不留活对象。图左侧那条「现组装 → 跑 ReAct 多轮 → 跑完即弃」的生命周期三态画的就是这件事:构造时持有 model / toolkit / middlewares / state,跑若干轮 ReAct(`cur_iter` 自增),跑完对象就销毁了。这不是一个随意的实现选择,而是 AgentScope 2.0.3 service 化的天然形态——service 要多租户、要能横向起多个进程处理不同会话,就不能让 agent 在某个进程的内存里长期活着。 + +图左下角那条「关键推论」是整张图的逻辑枢纽:既然没有常驻进程可以序列化,所有「下一轮还要用」的东西就都得外置到一份可持久化的状态里。这就引出图中段那个实线框的 AgentState——它是 AgentScope 2.0.3 自带的 pydantic 模型(源码 `agentscope/state/_state.py`),三个核心字段把一次生成的全部活记忆装了进去:`context` 是工作记忆,即喂进 LLM 的未压缩对话上下文;`cur_iter` 是当前轮次,记 ReAct 循环走到了第几轮;`tasks_context` 是任务清单,即拆解后的子任务表。图里那条蓝色说明带点出了 goal 和进度是怎么追踪的——目标来自输入(brief / play_spec / GDD),进度靠 `tasks_context` 逐项 TaskCreate / TaskUpdate 追踪,像一张会随生成推进不断勾选的 todo list。AgentState 是官方现成的(实线),tier2 直接用它装状态,不自己另造一套状态模型。 + +图右侧那个虚线框的 checkpoint,是这张图最该破除的一个直觉误解:checkpoint 不是去序列化一个活对象。直觉上「保存进度」像是把正在跑的 agent 冻起来存盘,但 agent 非常驻、根本没有活进程可存——checkpoint 在 tier2 里的真实含义是存 / 取那份 AgentState。它配 AgentScope 2.0.3 现成的 StorageBase 抽象、用 RedisStorage 落 Redis(StorageBase 实线现成,每轮 checkpoint 这件 tier2 接线虚线待建)。两条硬约束写在右下角:一是每轮 checkpoint,`cur_iter` 每自增一轮就落一次 state,粒度细到能从任意一轮断点续上;二是半轮副作用须幂等无脏,因为续跑可能在一轮的中间断掉重来,如果半轮里那些副作用不幂等,重跑就会脏数据,所以这是一条要在长程一致性里专门采集字段去验的可靠性约束。 + +图底那条蓝带把「非常驻 + AgentState」这条机理直接接到了实用价值上:它决定了 tier2 怎么做断点续跑。resume 不是什么特殊机制,就是图 A1 里 session 路径①的具体落实——从 StorageBase 读回上次的 AgentState,把它作为初始 state 注入新组装的非常驻引擎,引擎据此重建工作记忆与 `cur_iter`,然后从那一轮续接 ReAct 循环往下跑,已经完成的 TODO 不重做。一句话:非常驻不是缺陷,而是把「断点续跑」从难题变成了「读回 state 再装配」这件平常事。本图是总览图 3(运行时内部)和图 8(类图)的逐字段放大——总览把 Agent 与 Workspace 的整体结构画在一处,本图只取非常驻、AgentState 三字段、checkpoint 存 state 非存活对象这一面展开,Agent 与 Workspace 的双轴关系见图 A3,本图不重画。 + +### 图 A3 · Workspace 双轴注入 + +![图 A3 Workspace 双轴注入](assets/t2-A-03-Workspace双轴注入.svg) + +这张图存在的唯一目的是纠一个会带歪整个 tier2 设计的误解:很多人第一眼会把 Workspace 理解成「一个 environment,agent 跑在它里面、被它包着」,照这个理解去设计,数据面和注入关系全会接反。实情正相反——Workspace 是执行环境,它沿两条轴注入 agent;agent 持有 Workspace 的引用,不嵌在它里面。图的布局本身就在说这件事:左边是 agent 本体(无状态 ReAct 引擎,官方现成),右边是 Workspace(执行环境的真实载体,官方现成),中间两条箭头都是从 Workspace 指向 agent——注入的方向是 Workspace → Agent,不是 Agent 进 Workspace。 + +两条轴是这张图的主干。轴①是资源注入:Workspace 经 `get_toolkit` 把它内建的工具、加上 `list_skills()` 列出的 skills、加上 `list_mcps()` 列出的 MCP,汇成一个 Toolkit,注入到 agent 的构造参数里,成为 agent 能调用的工具集(源码 `app/_service/_toolkit.py:27`)。轴②是 offloader:Workspace 本身被当作 offloader 挂在 agent 上,agent 的上下文与工具结果卸载就挂到这个引用上(源码 `agent/_agent.py:104` 的 offloader 参数)。看清这两条轴,就能回答「那到底什么东西是『跑在 Workspace 里』的」——是 MCP 进程、是 skills(SKILL.md)、是 workdir 里那套多文件源工程,这些才真正在 Workspace 里运行;agent 本体不在里面,它只持一个引用,每 run 现组装、跑完即弃。这个区分不是咬文嚼字:它决定了 tier2 该把工具和资源挂到哪、该在哪埋观测点、隔离边界画在哪条线上。 + +图右下那排 WorkspaceBase 三实现,是这套抽象给 tier2 的隔离强度梯度。LocalWorkspace 跑本地进程,隔离最弱、最快;DockerWorkspace 用容器隔离,中等强度;E2BWorkspace 是远端沙箱,隔离最强。三者都是官方现成抽象,tier2 只是在其上挂自己要的工具与资源,不凭空自建一个 environment 数据面。图里把 spike 期的取舍标得很清楚:spike 就近用 Local / Docker 起手(最快、好调试),E2B 那种远端强隔离对齐的是更长期的多租户 / premium 层,用远期紫画、不是 spike 期投入项。 + +图左下角那个虚线框是这张图里唯一一处真正卡住 spike 的待裁项——D5 沙箱底座选型,标着「spike 前置阻断」。它要先回答一个承重前提:确定性硬门要的「真浏览器低层探针」(page.evaluate、navigate、screenshot、输入注入)在选定的沙箱上够不够用。候选 A 是 agentscope-runtime 的 BrowserSandbox,如果它把这些能力逐项暴露够了,就直接用它跑探针矩阵(当前全仓零引用,要先验);候选 B 是回落到自建薄沙箱加复用现行的 `play.cdp.cjs` 运行 / 截图 / 证据骨架(但那套探针硬编码了 LittleJS,要为 Phaser 重写)。这道结论必须在 spike 探针矩阵开跑前出来——出不来,矩阵根本跑不起来,所以它是属主标记的前置阻断项。图底那条蓝带把整张图收口成一句话:Workspace 注入 agent,不是 agent 嵌进 Workspace;tier2 不凭空自建 environment 数据面,在官方 Workspace 抽象上挂工具与资源即可,而「在哪跑、隔离多强」由沙箱底座(Local / Docker / E2B 与 D5 选型)解决。本图放大的是总览图 3 的双轴注入和图 8 的 WorkspaceBase 类图,不重画类图本身。 + +### 图 A4 · Middleware 洋葱 + +![图 A4 Middleware 洋葱(横切关注点挂载点)](assets/t2-A-04-Middleware洋葱.svg) + +让 agent 自治生成游戏,光有 agent 和执行环境还不够——还得能在它跑的过程中刹住烧钱、超时硬切、把每一步都记下来,而且这些横切的事不能散落进业务逻辑里各写各的。这张图回答的就是这些横切关注点统一挂在哪。答案是 AgentScope 2.0.3 的 MiddlewareBase 洋葱:它在 agent 执行的若干钩子上层层拦截,每一层用 `next_handler()` 把下一层包在中间,外层裹内层,所以叫洋葱。tier2 把成本刹车、硬熔断、可观测全挂在这套洋葱上,不另起机制、不散落进业务代码——这是框架给的扩展点,直接用。 + +图左侧那组同心环画的是四个 onion 钩子,从外到内各裹住 agent 执行的一层。最外环 `on_reply` 是一整次回复的进出边界;往里 `on_reasoning` 裹推理 / 模型调用阶段;再往里 `on_acting` 只裹单次工具执行那层 I/O(`toolkit.call_tool`);最内环 `on_model_call` 拦截裸模型 API 调用——这一环是钱算在哪的地方,因为它能读到 `ModelCallEndEvent` 带的 token 用量(`input_tokens` / `output_tokens`),成本台账和 trace 的 token 都从这一环取。洋葱框外下方那个单独的框是第五个钩子 `on_system_prompt`,它和前四个不同,不是前后包裹,而是顺序变换——多个 middleware 串成一条管线,各拿上一个的输出去改 system prompt 串,所以它是 transformer 而非 onion。四个 onion 加一个 transformer 共五个挂载点,按源码 `_base.py` 逐条核过,未实现的钩子运行时自动跳过。看懂这五个钩子各裹哪一层,才能回答「某个横切关注点该挂哪个钩子」。 + +图右侧那三类挂在洋葱上的东西,是这张图最该让人一眼分清的现成与自建之别。第一类是官方 ReplyBudgetControlMiddleware,做预算软刹(实线现成):它挂 `on_reply` 加 `on_reasoning`,在 `on_reply` 里按 ModelCallEndEvent 累计加权 token,越阈值后在 `on_reasoning` 里注入收尾提示、并强制 `tool_choice=none` 让它收尾。但要看清它的天花板——它只数 token、不换算金额、更不硬拒,刹不住一个已经在烧钱的失控循环。第二类正是为补这个缺口而设的自建硬熔断(虚线待建):TimeoutMiddleware(超时硬杀本次生成)、StuckDetectMiddleware(卡死 / 无进展硬杀)、预算硬闸(token 乘 new-api 单价换算成 ¥ 累进台账,越硬上限即 fail-closed 抛错终止,不只注入提示)。它们同挂这套洋葱、不另起机制,官方软刹刹不住时由它们硬切;在这套硬熔断建成前,tier2 不规模化跑、只在严格时间盒的实验里跑。第三类是官方 TracingMiddleware,做可观测(实线现成):它把 typed Event 流(ThinkingBlock / ToolCall / ModelCallStart / End 等)转成 OpenTelemetry span 汇进 AgentScope Studio,tier2 写轨迹不必自己埋点,复用这条官方 Event→OTel 管道、再加一层 adapter 映射进统一 trace 契约即可。 + +图底那条与 D12 运行治理门的分工带,讲清了「洋葱」和「门」各管哪一段,避免把两者混成一回事或重复造。洋葱在 agent 进程内,管 per-run 的成本 / 超时 / 卡死 / 观测;D12 在生成任务入口前,管配额 / 并发 / 背压 / 降级——一个在进程里逐轮拦,一个在入口处先闸,层次不同。两者之间有一个清晰的衔接点:D12 那道「花到上限就拒绝执行」的预算闸,在 agent 内的落点正是同口径自建一个预算 Middleware、挂 `on_model_call`、订阅 ModelCallEndEvent。这就构成了图底那句三层成本强制——worker 本地预测先闸、D12 网关配额二闸、任务 deadline 三闸。要记一条现行边界:D12 现在只覆盖 SAA,tier2 接入的入口、预算扣减、并发释放、失败补偿还待补,这是 D12 的已知边界。本图放大的是总览图 8 关键类图里 MiddlewareBase 那一支——把 ReplyBudgetControlMiddleware(现成)、TimeoutMiddleware / StuckDetectMiddleware(自建)各自挂哪个钩子、做什么逐项展开,不重画类图。 + +## 3 图清单与状态表 + +| # | 图名 | 形式 | 状态 | 覆盖内容 | +|---|---|---|---|---| +| A1 | Agent Service 与 session 三路径 | SVG · 横向链路 + router 网格 + 三路汇聚 | 现(官方 Agent Service / MessageBus = 现成)/ 建(tier2 接线待 spike) | cloud 经 REST POST /sessions 建会话 + SSE 收流;八个 router;MessageBus 四能力(Redis Stream replay / pub-sub / 分布式锁 / 取消信令);SSE 可恢复;session 三加载路(续接 / 加载已有工程 / 新建)汇到同一 Agent 装配点 | +| A2 | Agent 非常驻 + AgentState + checkpoint | SVG · 三段结构 + resume 链路带 | 现(AgentState / StorageBase = 官方现成)/ 建(tier2 非常驻装配 + 每轮 checkpoint + resume) | agent 非常驻三态生命周期;AgentState 三字段(context / cur_iter / tasks_context)+ goal/进度追踪;checkpoint = 存 state 非存活对象、配 StorageBase 落 Redis;每轮 checkpoint 与半轮幂等两条硬约束;resume = 取回 state 装配续跑(对应 session 路径①) | +| A3 | Workspace 双轴注入 | SVG · 左右双轴 + 三实现 + D5 二分 | 现(Agent / Workspace / Toolkit / 三实现 = 官方现成)/ 建(tier2 注入工具集 + D5 沙箱底座)/ 缓(E2B 远端强隔离 = 更长期层) | 纠误解:Workspace 注入 agent、非嵌套;轴① get_toolkit 汇 Toolkit、轴② Workspace 作 offloader;真跑在 Workspace 里的是 MCP / skills / 文件;WorkspaceBase 三实现隔离强度梯度;D5 沙箱底座 spike 前置阻断(BrowserSandbox vs 回落 CDP) | +| A4 | Middleware 洋葱 | SVG · 同心环 + 右侧三类 + D12 分工 | 建(tier2 洋葱挂载待 spike;软刹 / trace 官方现成,硬熔断自建) | MiddlewareBase 4 onion 钩子(on_reply / on_reasoning / on_acting / on_model_call)+ 1 transformer(on_system_prompt);挂洋葱三类(官方预算软刹 / 自建硬熔断三件 / 官方 TracingMiddleware);三层成本强制;与 D12 运行治理门的进程内 vs 入口前分工 | diff --git a/docs/architecture/架构/生成引擎/tier2细节图说-B-控制面与管理面.md b/docs/architecture/架构/生成引擎/tier2细节图说-B-控制面与管理面.md new file mode 100644 index 00000000..22854664 --- /dev/null +++ b/docs/architecture/架构/生成引擎/tier2细节图说-B-控制面与管理面.md @@ -0,0 +1,97 @@ +--- +date: 2026-06-23 +topic: tier2 细节图说 · B 族——控制面与管理面(生成引擎子树·tier2) +status: 设计中(tier2 待 spike) · 每图映射源档见该图脚注 / frontmatter 记 hash 作防漂移门 +映射源档: + - path: docs/architecture/架构/生成引擎/agentic集成架构.md + hash: 1b3e375a + - path: docs/architecture/架构/生成引擎/SAA编排.md + hash: 1b3e375a +--- + +# tier2 细节图说 · B 族 —— 控制面与管理面 + +> 本篇是绘境AI 架构图集 **生成引擎子树** 下的 tier2 细节图说,只覆盖 **B 族(控制面四组件、反锁死五协议、预算三层强制、管理面三 phase)** 四张图。它是 [agentic 运行时架构图说](agentic运行时架构图说.md) 里「治理层」那一格的放大层——运行时图说把控制面当成一个盒子带过,这里把盒子拆开,逐组件、逐协议讲清它怎么同时管住两条异构生成线。 + +--- + +## 0 阅读约定与同步纪律 + +B 族讲的是平台拿什么治理两条生成线——SAA 廉价线(Tier0/1)和 tier2 自治富游戏线。治理这件事被拆成四个面:配置怎么管(配置注册表)、运行过程怎么看怎么审(观测/审计仓)、入口怎么拦(D12 与预算闸)、人怎么操作(管理面 UI)。四张图分别从四个角度切这同一层:B1 是四个组件的全貌加它们对两条线暴露的同一套契约,B2 是支撑「一份治理管两条异构线」的根本原则——反锁死五协议,B3 把四个组件里最容易被忽视的预算闸单独深挖(官方软刹刹不住烧钱循环、要自建硬熔断),B4 把管理面 UI 这一个组件展开成三 phase 的演进路线。 + +四张图映射两份属主设计档。控制面四组件、反锁死原则、预算闸、管理面三 phase、接口对称内容不对称,这五块的口径全部出自《agentic 集成架构:控制面与管理面》;反锁死五协议里的任务协议这一件,其精确边界(job/callback 契约 #6 暴露的 `GenerationDispatcher` 接口)出自《SAA 编排》第 4 节六条不变量的第五条与整图串行约束那节。frontmatter 记了这两份的当前 commit hash,作为防漂移门——其中任一份动了治理口径,本图说与对应 SVG 必须同步改。 + +B 族的状态分布比 D 族复杂,因为控制面不是 tier2 的专属物,它从属于「生成主线架构演进路线」(档内称线A),只在线A 之上做净增量,并且同时服务 SAA 和 tier2 两条线。所以同一张图里会并存三种成熟度:SAA 廉价线那部分(读配置、写轨迹、过 D12)是现行已落,D12 治理门和 Prompt Registry 的构建期快照部分是已有件复用,配置审计日志 / 注册表推广到 skill-tool-mcp / 统一 trace 契约 / tier2 整条接入则是待建。tier2 整轨本身待 0号 spike 验证、尚未落代码,这个前提对 B 族同样成立。 + +看图时认线型和颜色:实线框 = 现行已落或已有件复用;虚线框(短划线)= 待建净增量,或 tier2 待接;远期紫 = 明确「现在不投」的能力(典型是管理面 phase-3 的完整可视化建图),要等真有多编排 / 多 agent 团队需求、且某个深坑被填后才上。 + +## 1 全图通用图例 + +B 族用一套统一的徽章、线型和状态码,先在这里讲清,后面每张图不再重复。 + +**生产维度徽章**标的是一道能力服务哪个非功能维度:蓝色 **可观测**(看得见运行过程)、红色 **安全**(入口拦截 / fail-closed 截断)、灰色 **数据**(唯一事实源、数据口径)、绿色 **成本**(预算核算面)。一个组件可以同时挂多个徽章——比如观测/审计仓既是可观测面也是数据事实源。 + +**线型**承担状态语义。实线框 = 现行已落或已有件复用,实线箭头 = 现行已接的转移 / 关系;虚线框(短划线)= 待建净增量或 tier2 待接,虚线箭头 = 待建的流程或待接线。**远期紫块** = 明确登记「现在不投」的远期能力。 + +**状态码**四档,贯穿整个生成引擎子树:**现** = 现行已建在跑;**接** = 设计已出、代码待接线(或他分支已落、待合并对账);**建** = tier2 立项后要新建、当前待 spike;**缓/future** = 收窄后缓做或远期不投。B 族里 SAA 三件事和 D12 是「现」,Prompt Registry 构建期快照部分是「现 部分」,配置审计 / trace 契约 / skill-tool-mcp 推广 / tier2 接入是「建」,管理面 phase-2 是「缓」、phase-3 是「future」。 + +## 2 图集 + +### 图 B1 · 控制面四组件 + +![图 B1 控制面四组件](assets/t2-B-01-控制面四组件.svg) + +让 agent 自治生成游戏这件事本身不够,平台还得能改 prompt 不发版、看见每次生成到底干了什么、查出谁改了哪条配置、在入口拦住失控的生成。控制面就是干这几件事的那一层,它同时管两条生成线。这张图把控制面的四个组件并排铺开,核心要让人看出一件事:四个组件对两条线暴露的是**同一套契约**——读配置、写轨迹、过门,生成线只管照契约办事,不感知管理面长什么样。 + +第一个组件是**配置注册表**,它是配置的唯一事实源,直接回应创始人那句「改 prompt、模型、skill、mcp 还要重新部署」。内核是把凡是现在「要改就得发版」的东西,都搬进一个版本化、可回滚的注册表。这里的现行真相要说清:今天的 Prompt Registry 不是「现成可热加载」的地基,它是构建期被 maven 插件复制进 classpath 的快照,改 prompt 等于改 `contracts/` 原文件、升版本号、过四道闸,下次构建部署才带新版——是 Git 版本化加构建期注入,不是运行时热加载,而且注册表里还有标着 STUB 占位的条目和一批硬编码加载、未必登记的模板路径。所以图里给它标的是「现 部分」,并且把「推广到 skill / tool / mcp」框成虚线净增量,旁边压着一条硬纪律:推广前先补一道一致性 CI(每条条目都有对应文件、每个硬编码 id 都登记、STUB 补正或标为不可上线)。这条纪律是有出处的——同目录的对抗审查给过一个对症范例:某个运行时能力本要四处人手同步,正确解法不是上重型注册表,而是加一道一致性测试逼你改齐。别在裂的地基上盖更大的注册表,是这个组件最该守住的设计取舍。 + +第二个组件是**观测 / 审计仓**,它回答两个独立问题,对应两条留痕线。一条是运行轨迹——每步推理、每次工具调用、每次 LLM 输入输出、每道门裁决、每次成本,落进统一的 `contracts/trace/` 契约。另一条是配置审计日志——谁、什么时候、改了哪条配置、前后 diff,这条线现在完全没有,是全新建的。把这两条线钉一起的价值很具体:任何一次生成都能反查它当时用的哪几条配置的哪个版本,才能回答「那批游戏质量掉了,是不是上周改的那条 prompt 干的」。配置审计还带一个要选边的分类决策(图里画出来了):prompt / models 这类版本化资产走 GitOps(改配置 = 建 PR,审计天然、可回滚),运营开关类(降级、配额数值)走 DB 直写 `infra_config`(即时生效、复用现成通路)。 + +第三个组件是 **D12 运行治理门**,它把配额、并发、背压、降级、记账骨架焊在生成任务入口前。它是已经存在的件,本设计只复用不改、默认关闭、零行为变更进主干。它有两点边界图里点明了:现在只覆盖 SAA,tier2 接进来的入口、预算扣减、并发释放、失败补偿还要补;它的记账是骨架不是真计费。这道门接上引擎那道「花到上限就拒绝执行」的预算闸,那是 B3 单独深挖的事。 + +第四个组件是**管理面 UI**,它是注册表和观测仓的视图与编辑器,不是真相本身——配置才是真相。它按三 phase 落,是 B4 单独展开的事,这里只在图里留一个三 phase 带做指引。 + +四个组件下方那条绿带,讲的是这套设计能成立的真正条件:接口对称、内容不对称。两条线都按「id 加版本」从注册表读配置(接口同),但 SAA 读 16 个节点的参数、tier2 读 ReAct 的工具集和轮数预算(内容异);两条线都按统一 trace 契约写轨迹,公共核心子集对称、扩展段各写各的;两条线都先过 D12,只是现在只覆盖 SAA。这条对称/不对称的边界,是「一份管理面管两条异构线」能成立的根。还有一处现实图里写明了,不写会误导人:tier2 的 eval / 灰度门现在不存在,所以它的配置改动当前只有「下次生效加轨迹留痕」两层保护、没有 eval 拦截——这不是设计缺陷,是 tier2 成熟度的现状。 + +### 图 B2 · 反锁死五协议(框架可替换) + +![图 B2 反锁死五协议](assets/t2-B-02-反锁死五协议.svg) + +当下生产线是 SAA-only(决策 HJ-AGI-002,经双评审与源码核验后选定),但选了 SAA 不等于被 SAA 锁死。这张图立的是一条比四个组件更根本的架构原则:平台不绑死在任何单一 agent 框架上。AgentScope / LangGraph / AutoGen 这些框架可以被借鉴、组合、在不同轨上分别采用(long-term 的 tier2 premium 轨就走 AgentScope),平台真正固化、不随框架走的,是协议层那五件东西——把它们钉牢,框架就被压到「只租用不拥有」的位置,换框架时业务不被连根拔起。 + +固化在协议层、与框架解耦的是五件。**任务协议**是生成任务怎么提交、怎么回调,边界就是 job/callback 契约 #6 暴露的 `GenerationDispatcher` 接口,这件是现行已落的实线锚点——换框架只换 dispatcher 实现,调用方一行不改。**状态模型**是一次生成的状态怎么表达、怎么续跑,checkpoint 的语义是平台自己的口径,不是某框架的私有结构。**工具接口**是 agent 能调哪些工具、入参出参长什么样,以契约定义,不绑某框架的工具注册机制。**验收门禁**是「完成」由确定性九门裁定、禁止 LLM 自评,这条是平台铁律(防 Goodhart:把度量当目标去优化,度量即失效),无论底下换哪个框架,出题与被考不同源这条都不让步——它也是现行已落的实线锚点(九门由廉价线已建)。**遥测事件**落进统一 trace 契约,公共核心子集对称、扩展段各写各的,采集机制各框架来、数据口径是平台的。这五件里,任务协议和验收门禁是「现」,状态模型、工具接口、遥测事件是「建」,随 0号 spike 与控制面分期落地。 + +这张图最该让人记住的不是这五件本身,而是它给出的**正反两个判据**,图中间两条带画的就是这个。正向判据:long-term 要不要把某条轨从 SAA 切到 AgentScope,就看这五件是不是仍稳稳钉在协议层——是,切换就只是换一个被治理的执行后端,不是推倒重来;SAA(裸 StateGraph)和 AgentScope(自治 ReAct)这两套异构范式,正是靠「协议层对称、执行后端可换」才能共存。反向判据:如果哪天发现某个框架的私有结构悄悄渗进了这五件中的任何一件(比如轨迹格式被某框架的 span 结构绑死、任务协议泄漏了框架的内部状态),那就是锁死的开始,要立刻在协议层把它隔离回去。这也解释了为什么整个治理层反复强调「管理面只渲染运行时自报的拓扑、绝不另持一份拓扑模型」——那同样是反锁死,管理面里硬编码的框架拓扑,换框架时就是阻力。这条原则不是空谈「将来好换」,它有具体落点,就是上面那条切轨判据。 + +### 图 B3 · 预算三层强制(软刹 vs 硬熔断) + +![图 B3 预算三层强制](assets/t2-B-03-预算三层强制.svg) + +引擎设计里那道「花到上限就拒绝执行」的预算闸,现在不是现成能力,这张图把它单独深挖。要先看清官方给了什么、缺什么,图上半部分就是这个对照。AgentScope 2.0.3 自带 `ReplyBudgetControlMiddleware`,但它只做软刹——累计加权 token 到阈值后,往 Agent 上下文注入一句提示(别再调工具、收尾)、并把下一步的 `tool_choice` 强制成 `none` 让它结束,它只数 token、不换算金额、更不会硬拒。这对失控成本不够:tier2 自治多轮 ReAct 一次失控循环能烧掉数美元,软刹只是「提醒它别再调工具」,刹不住一个已经在烧钱的循环——提示不等于截断。 + +所以硬熔断和金额台账都得自建,而且自建有现成载体——同样是 AgentScope 的中间件洋葱。图右半部分画的是这个自建件:在 `on_model_call` 这类钩子上拦截,订阅 `ModelCallEndEvent`(源码已确认这事件带每次模型调用的 token 用量),把 token 乘上 new-api 的单价换算成金额累进台账,一旦越过硬上限就直接抛错 fail-closed、终止本次生成,而不是像官方那样只注入提示。金额台账加硬拒这两件,正是官方软刹做不到、故必须自建的。软刹和硬熔断这两种处置力度叠在同一个中间件洋葱里——一个数 token 提醒,一个折金额硬拒。 + +图下半部分是三层强制,讲的是成本不靠单点,三道闸纵向叠、任一道先到上限即拦。第一道是 worker 本地预测闸:动手前先估这一步要花多少,越本局预算就不发起调用,是最便宜的一道,在调模型之前就拦下,位置在 tier2 worker 进程内。第二道是网关配额闸,就是 D12 那道已有件,配额 / 并发 / 背压 / 降级 / 记账骨架焊在入口前,现仅覆盖 SAA,tier2 接入面和「记账从骨架变真计费」是待补的。第三道是任务 deadline 闸:超过墙钟时间盒即停,兜住「token 没烧穿但卡在长循环里」这种纯耗时的失控,和 token / 金额上限互补。这三道之间还有一个要选边、不能既要又要的决策图里写明了:token 折金额这一步若取价通路不可达,要么直接失败(保守、宁停不超支),要么降级到纯 token 上限兜底,落地时显式定一条、不留模糊。 + +图底那条红铁律是整张图的落点:这套三层强制预算落地之前,tier2 只在严格时间盒的实验里跑,绝不规模化——自治多轮不强制就会烧钱,软刹刹不住。需要留意一处分期边界:这道预算闸只是 C 族「四道熔断」总览里的其中一道,本图只深挖预算这一道加 D12 网关配额;spike 阶段成本熔断可以先只挂官方软刹,硬熔断与三层强制到建设期再补全。 + +### 图 B4 · 管理面三 phase + 接口对称内容不对称 + +![图 B4 管理面三 phase](assets/t2-B-04-管理面三phase.svg) + +管理面 UI 是注册表和观测仓的视图与编辑器,不是真相本身——这是创始人最在意的那半边,「Dify 式可视化 agent 平台管理」:改 prompt / 模型 / skill / tool / mcp 不发版、可视化、可追踪、可审计、不要死代码。这张图先把一个设计选择定下来(顶部那条蓝带),再把管理面按三 phase 铺开。 + +设计选择是:不从零造一个 Dify 式可视化建图器,而让配置成为真相、UI 只做配置加轨迹的视图与编辑器。三个理由图里列了:前期平台调研已拍板「维持现有 SAA / AgentScope、不迁可视化平台」;裸图的节点是 Java 代码、ReAct 的工具也是代码,真相在代码和配置里,靠 UI 拖拽生成代码是另一套不可靠的范式;还有那条别过度工程的纪律。但「配置是真相、UI 是视图」不等于「第一期什么都不做、把可视化全推远期」——管理面按三档落,而且诚实命名。 + +phase-1 叫「配置管理加运行可观测」,不叫「可视化编排」,因为这期还没有真的图编辑,叫编排名不副实。这一档最该被看见的是它含一个**纯只读、不依赖线A 任何一步、立即就能兑现**的切片:看各角色当前用什么模型、回放任意一次生成的全轨迹、按 new-api 的 quota 口径对账成本。这三件事现在就能做,是立刻能给创始人看见的最小兑现,图里把它画成实线、挂可观测徽章,正是这个意思。其上再加配置编辑(虚线、待建):在 UI 改 prompt / 换模型 / 调阈值,改的是注册表条目,改完落 Git 加审计日志,不是直接热生效。phase-2 是「限定范围图编辑」(缓),把节点启停、边开关、模型 / 工具绑定、配置版本 diff、按轨迹回放排进来;「限定范围」指它只编辑节点参数和启停,渲染的拓扑来自运行时自报,不让用户拖拽新增节点改结构。phase-3 是「完整可视化建图」(远期紫、不投),拖拽改拓扑要等两个前置条件齐了才上:真有多编排 / 多 agent 团队的需求,而且「拓扑配置化」那个深坑(运行时重建图)被填了。图里特地点明,phase-3 这个拓扑可视化是给我们自己运维用的,不是给 C 端创作者编 workflow 的产品能力——后者另登记一条未来需求,tier2 自身靠 loop 加 task/goal 加 Team 调度即可,不靠 DAG。 + +图下半部分是两条贯穿管理面的约束。左边那条是「只渲染运行时自报的拓扑」——数据源是运行时轨迹实际走到哪个节点,绝不在管理面这侧另持一份拓扑模型。这条约束的根在于 SAA 是静态 StateGraph、tier2 的 ReAct 没有静态图,两套异构范式要用同一个管理面呈现,只能靠「渲染运行时自报」这个共同口径;它同时也是反锁死(换框架时,管理面里硬编码的拓扑模型反而成阻力),和 B2 那条原则是一回事。右边那条把「接口对称、内容不对称」逐件拆给了三行:读配置(接口按 id 加版本加载,内容 SAA 读 16 节点参数、tier2 读 ReAct 工具集加轮数预算)、写轨迹(接口按统一契约写,公共核心子集对称、扩展段各写各的 JSON 列)、过治理门(都先过 D12,SAA 已覆盖、tier2 入口待补)。图底那条红带写明了那处不写会误导人的现实:tier2 的 eval / 灰度门是 tier2 实验的产物、现在不存在,所以「配置改动要过 eval 门」对 tier2 现在是空头支票——eval 门建成前,tier2 配置改动只有「下次任务生效加轨迹留痕」两层保护,没有 eval 门拦截;SAA 廉价线则已落 D12 加 Git CI 校验,保护更全。 + +## 3 图清单与状态表 + +| # | 图名 | 形式 | 状态 | 覆盖内容 | +|---|---|---|---|---| +| B1 | 控制面四组件 | SVG · 两线 lane + 四组件容器 + 契约带 | 现(D12 / Prompt Registry 部分已落)+ 建·接(配置审计 · skill-tool-mcp 推广 · tier2 接入待建) | 配置注册表(唯一事实源 · 现 STUB 缺口)/ 观测审计仓(运行轨迹 + 配置审计 GitOps vs DB 直写)/ D12 治理门(已有件复用)/ 管理面 UI(三 phase 指引);接口对称内容不对称;tier2 无 eval 门现状 | +| B2 | 反锁死五协议(框架可替换) | SVG · 五协议卡片 + 正反判据带 | 建(原则 · 协议层固化;契约 #6 已存在,余随分期落地) | 任务协议 / 状态模型 / 工具接口 / 验收门禁 / 遥测事件五件与框架解耦;切轨 = 换被治理后端(正判据)/ 私有结构渗入 = 锁死开始(反判据);框架被压到「只租用不拥有」 | +| B3 | 预算三层强制(软刹 vs 硬熔断) | SVG · 两框对照 + 三闸纵向 | 现(官方软刹 + D12 已有)/ 建(硬熔断 + 三层强制自建待落) | 官方 ReplyBudgetControlMiddleware 软刹(只数 token、不折金额、不硬拒)vs 自建预算 Middleware 硬熔断(订阅 ModelCallEnd 折金额、越上限 fail-closed);三层强制(worker 本地预测 / D12 网关配额 / 任务 deadline);取价不可达策略;强制建成前 tier2 不规模化 | +| B4 | 管理面三 phase + 接口对称内容不对称 | SVG · 三 phase 横向 + 两贯穿约束 | 接(phase-1)/ 缓(phase-2)/ future 不投(phase-3) | 不造 Dify 建图器的设计选择;phase-1 配置管理加可观测(含纯只读立即兑现切片)/ phase-2 限定范围图编辑 / phase-3 完整建图远期不投;只渲染运行时自报拓扑;接口对称内容不对称三件;tier2 无 eval 门现状 | diff --git a/docs/architecture/架构/生成引擎/tier2细节图说-F-源项目契约与装载.md b/docs/architecture/架构/生成引擎/tier2细节图说-F-源项目契约与装载.md new file mode 100644 index 00000000..73153b69 --- /dev/null +++ b/docs/architecture/架构/生成引擎/tier2细节图说-F-源项目契约与装载.md @@ -0,0 +1,84 @@ +--- +date: 2026-06-23 +topic: tier2 细节图说 · F 族——源项目契约与第二装载分支(生成引擎子树·tier2) +status: 设计中(tier2 待 spike) · 每图映射源档见该图脚注 / frontmatter 记 hash 作防漂移门 +映射源档: + - path: docs/architecture/架构/生成引擎/tier2实现详设.md + hash: d5efe45f + - path: docs/architecture/架构/生成引擎/agentic运行时架构图说.md + hash: 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 · 源项目契约七要素四组 + +![图 F1 源项目契约七要素四组](assets/t2-F-01-源项目契约七要素.svg) + +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 · 第二装载分支 + +![图 F2 第二装载分支](assets/t2-F-02-第二装载分支.svg) + +游戏怎么进浏览器,在 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 + +![图 F3 finish 工具与源项目契约共用 schema](assets/t2-F-03-finish共用schema.svg) + +这张图讲的是一处从一开始就要对齐、不然日后必漂的源头设计: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。 diff --git a/docs/architecture/架构/生成引擎/tier2细节图说-G-spike-runbook.md b/docs/architecture/架构/生成引擎/tier2细节图说-G-spike-runbook.md new file mode 100644 index 00000000..90203545 --- /dev/null +++ b/docs/architecture/架构/生成引擎/tier2细节图说-G-spike-runbook.md @@ -0,0 +1,100 @@ +--- +date: 2026-06-23 +topic: tier2 细节图说 · G 族——0号 spike runbook(建设五步 / 靶子 / 模型矩阵 / 过门 / 退路)(生成引擎子树·tier2) +status: 设计中(tier2 待 spike) · 每图映射源档见该图脚注 / frontmatter 记 hash 作防漂移门 +映射源档: + - path: docs/architecture/架构/生成引擎/tier2实现详设.md + hash: d5efe45f + - path: docs/architecture/架构/生成引擎/自治富游戏引擎.md + hash: 4858e6cf +--- + +# tier2 细节图说 · G 族 —— 0号 spike runbook + +> 本篇是绘境AI 架构图集 **生成引擎子树** 下的 tier2 细节图说,只覆盖 **G 族(0号 spike 的可执行 runbook)** 五张图。生成引擎主干、tier2 总览、agentic 运行时各有自己的图说;这里专门把「tier2 整轨值不值得投、怎么便宜地先验一次」这件事画清楚。 + +--- + +## 0 阅读约定与同步纪律 + +G 族画的是 0号 spike 这一道生死门——tier2 富游戏自治生成线最深的赌注在被铺开成一整套引擎生态之前,先用一个最小、可丢弃的 spike 把它便宜地验一遍。整条线押的那一半是:便宜或中等模型的自治 agent,在经营骨架、玩法模板、资产池、RAG、L1 确定性门兜底这套约束下,能不能稳定写出占一款经营富游戏 56% 的表现层并过确定性门。已经证到的只是产物形态——王蓝莓那款 12 文件、180KB 的多系统经营游戏真做出来过、过了真输入 harness,Phaser 这条路能过确定性门也有 2026-06-11 的五门证据;但这两次都是最贵的模型加重人工编排做到的,不是便宜模型自治。架构论证替代不了实测,所以要跑这个 spike。 + +五张图映射两份属主设计档。建设五步与 spike 插点、隐藏硬工作出自《tier2 实现详设》的「建设五步与 0号 spike 生死门」一节;靶子游戏的施工规格出自同档「靶子游戏 mini-肥鹅」一节;模型矩阵、样本量与跑序出自「模型矩阵与样本量」一节;过门阈值与采集字段出自「过门判据与精确阈值」「采集指标字段表」两节;两段实施与退路树出自「两段实施步骤」「退路树」两节。56% 这个占比数、约束自治(O2)范式、最深赌注的来龙去脉出自《自治富游戏引擎》的「三层拆分」与「现在证到哪,赌注在哪」两节。frontmatter 记了这两份的当前 commit hash 作为防漂移门——其中任一份动了 spike 口径、靶子规格、阈值或退路触发线,本图说与对应 SVG 必须同步改。 + +整条 tier2 富游戏线现在 **整体待建**:0号 spike 还没跑,AgentScope 底座没搭,引擎没建,代码一行没落。所以 G 族里几乎所有元素都是设计已出、尚未落地的状态(虚线),包括 spike 门本身、五步建设路径、两段实施、退路分流、阈值与采集字段。有承袭、不全是新建的部分用实线画,但要分清承袭的是什么:deepseek 两档便宜模型是现行 Tier0/1 廉价线在产的模型、mini-desktop 是已有的权威构建与 e2e 门机、L1 确定性门(九门)和 new-api 计费平面是现行已落的底座、W-CH-α 渠道路已实证到 P0——这些是真承袭,用实线。spike 要在它们之上新做的全是虚线。另有一档颜色单列:**远期紫**标的是 Cocos 这条不进自治循环、放到 Phaser 证成之后才铺的另一条轴,它远期不押核心赌注。看图时记住:**实线 = 承袭现行已落;虚线(短划线)= tier2 专属待 spike 验证后才落代码的新机制;远期紫 = 远期不投核心循环。** + +G 族是《[agentic 运行时架构图说](agentic运行时架构图说.md)》的放大层。那份总览给的是整轨的生命周期、对象结构与系统全景,其中「建设 / spike 判据」只点到为止;G 族把那一面逐项放大——五步的先后、spike 插在哪、隐藏硬工作有哪些、靶子砍成什么样、跑哪几档模型、过门的数字阈值、采集哪些字段、崩了往哪条退路走。deepen 不 duplicate:总览负责让人建立全局轮廓,G 族负责让一个工程师能照着把 spike 跑起来、据数字裁 go/no-go。 + +## 1 全图通用图例 + +G 族用一套统一的徽章和线型,先在这里讲清,后面每张图不再重复。 + +**状态码**四个,贯穿生成引擎子树:**现** = 现行已建在跑;**接** = 设计已出、代码待接线;**建** = tier2 立项后要新建、当前待 spike;**缓** = 收窄后缓做。G 族绝大多数元素是「建」,deepseek 两档 / mini-desktop / L1 九门 / new-api 计费是「现」,Cocos 生态与 Phaser 渠道 adapter 是「缓」。 + +**线型**承担状态语义,与状态码对齐。实线框 / 实线箭头 = 承袭现行已落(deepseek 两档在产模型、mini-desktop 权威构建机、L1 九门、new-api quota 折¥、W-CH-α 渠道路);虚线框 / 虚线箭头(短划线 6 4)= tier2 专属待建(spike 门、五步路径、两段实施、退路分流、阈值与采集字段);**远期紫**实线 = 远期不投核心循环的 Cocos 轴与作为天花板基线的强模型档。go/no-go 的分流用绿(过 / go)和红(不过 / no-go)两色箭头区分。 + +**生产维度徽章**标的是某个元素服务哪个目标:**质量**(绿)= spike 验「便宜模型能否自治写出那 56% 表现层」这个最深赌注、过门率与收敛步数;**成本**(绿)= 单款¥与 ¥3/款 成本闸;**安全**(红)= 第二段 Goodhart 防线(自产 driver 三层隔离,写者不判自己的卷);**可观测**(蓝)= 第三步要早建的 TracingMiddleware 与成本台账、spike 调试当下就要;**数据**(灰)= run 级采集字段是 go/no-go 的可对比底料。 + +阈值上还有一个记号要先讲清:凡标 **★** 的数字是建议值、需创始人和实测校准(如 ¥3/款 premium 预算、50%/70% 过门率门、单系统 8 轮 / 整局 40 轮的收敛上限);不带 ★ 的是承袭现行线的硬约束(factory 路 60% / cutover 门 80% / L1≤¥0.15 / L2≤¥5 / new-api quota 折¥口径)。 + +## 2 图集 + +### 图 G1 · 建设五步 + 0号 spike 生死门 + +![图 G1 建设五步与 0号 spike 生死门](assets/t2-G-01-建设五步与spike门.svg) + +tier2 的建设按创始人给的五步纵向走,真正的设计取舍是在第二步和第三步之间硬插一道便宜的 spike 门。原来的自然顺序是先把 AgentScope 底座搭好、再以 Phaser 搭出一整套生成引擎(大投入),最后才让它自治生成一款肥鹅级游戏过人审——可那一刻才第一次验「便宜模型到底写不写得出富游戏」,而这恰恰是整轨最深、最没证过的风险。把这个验证推迟到引擎都搭漂亮之后,等于把最贵的赌注押在最后揭晓。spike 门就是把这个顺序倒过来:最深的赌注要在最便宜的时候验。它不必等第一二步全做完——一个最小的 AgentScope 加一坨硬编码配置就能先验,过了(go)才进第三步铺引擎,不过(no-go)直接走退路树,绝不滑成无限调参。这张图让人一眼看出的就是这个插点的位置和它背后的逻辑:先证赌注、再投生态。 + +这张图第二个该让人看清的,是「搭引擎」和「过人审」这两步表面之下藏着的硬工作。第三步表面是以 Phaser 为范例搭生成引擎,底下藏着五块不补就埋雷、必须显式排进去的工作:把现行 L1 确定性门泛化到 Phaser 并为经营品类补 driver 和跨表语义门(验收地板),自产取证 driver 必须过平台白名单加独立评审(Goodhart 安全),官方软刹叠自建硬熔断防自治多轮烧钱(成本强制),真 Phaser 工程的源项目契约这步真接上,以及用官方 TracingMiddleware 把每步推理动作观察吐成 typed event 流进 Studio 加成本台账(可观测早建)。这五块现状都还只是 best-effort,规模化前必须落地;其中可观测是复利中台里唯一该在这个阶段就建的部分,因为 spike 调试和对账当下就用得上。第四步表面是自治生成一款过人审的游戏,藏着的是把「人审」做实而不是创始人亲玩一票:要把「好玩」拆成可复核的几条来压个人品味方差(终审判据),要有一个终审吞吐模型免得 premium 量一上来人审变瓶颈或橡皮图章,还要让 player panel 去判可达性和空内容这类确定性可逼近的明显劣化信号给人门减负。把这两步的隐藏工作单独画出来,是为了不让它们在「搭引擎」「过人审」这种轻描淡写的步骤名底下被漏掉。 + +第五步把 Cocos 放在 Phaser 证成之后是有意为之,这是这张图唯一的远期紫:Cocos 是另一条正交的轴(编辑器、人在环,服务 3D、复杂场景、渠道导出),它进不了无人值守的自治循环,不该和 Phaser 并级、更不该在核心赌注证成前就铺。渠道 adapter 走仓内 W-CH-α 已实证到 P0 的「轻 H5 引擎加自研 adapter」路,待补的是 P1 真机门,卡在创始人三件套那道日历闸门上,不是技术阻断。最该据这张图 review 的设计缝在 spike 门那一格的阈值:它标了 ★,意味着 go/no-go 的判线本身还需要创始人和实测校准——门焊得太松会放进一个其实不该投的赌注,焊得太紧会把一个本可成立的范式误杀,这条线怎么定,是这张图把决定权显式交还给创始人的地方。 + +### 图 G2 · mini-肥鹅 靶子规格 + +![图 G2 mini-肥鹅 靶子规格](assets/t2-G-02-mini肥鹅靶子.svg) + +spike 的第一段是个对照实验,对照组是「人工预建骨架加人工预建 driver」——要预建,就得先有一个确切的靶子游戏。这张图把这个靶子钉死成 mini-肥鹅:一个砍到能证、又保住三个本质难点的最小经营游戏。三个本质难点是多系统耦合、重 UI 表现层、数值经济闭环,它们正是现有廉价线做不出富游戏的原因,也正是 spike 要考的东西。砍法是相对仓内 wanglanmei-ref(那款 12 文件约 180KB、赢输双路径已证的多系统经营游戏)做减法:砍掉任务弹窗、背包深度、上百物品,但一根不少地保留三个联动系统和它们之间的确切耦合点。砍内容量是为了让 spike 本身别变重,保耦合点是因为耦合点才是考题——如果砍到三个系统互不相干,这个 spike 就白跑了,因为它考的就是 agent 能不能把系统正确接起来。 + +图中央把资源系统画成读写交汇点,是这张图最该让人看懂的结构。三个系统不是三座孤岛:合成系统(3×3 棋盘,点两个相同物品合成上一级,6 条合成链覆盖 12 个物品)的产出进资源库存、消耗时调资源系统扣食材;订单系统(面板列 3~5 个带耐心的顾客订单,要物品给金币)完成订单时调资源系统扣物品加金币、耐心耗尽即流失;资源系统反过来用金币门控解锁第 4、5 摊位和更高合成链。所有读写都汇到资源系统那张极小的状态表上,它是耦合枢纽。图上方那条横跨的弧线标的是这个 spike 真正的核心考点——跨表可达性:订单的 requires 必须能被合成系统产出的物品满足,这是一次从 mergeChains 静态推到 orders 的检查,如果 agent 填的数据表里有订单要的物品根本合不出来,这游戏就是死局。把这条考点单独用一条跨越全图的弧画出来,是因为它最容易被忽略、又最能区分「三个系统摆在一起」和「三个系统真接上了」。 + +图下半部分把胜负条件画成两条都必须能被 harness 真输入驱动跑到终态并 latch 的路径,这是 spike 能确定性验收的前提。赢是金币从开局 20 经「合成→凑齐订单物品→交单→收金币」的正循环攒到 100,输是连续 3 个订单流失(只合成不交单或经济崩盘)。关键约束是这两条路都得能被 driver 的真输入序列驱动到终态、再 latch 成不可逆的终局——能在数据表里算出来和能被真玩到是两回事,latch 成可轮询的终态则是因为游戏没有 emit 通道、宿主只能轮询去读,这条承接的是现行宿主装载已经验过的约束。内容量定在 12 物品、6 链、5 订单模板、2 种货币,数据表留空给 LLM 填、骨架按三系统加耦合点预建为平台代码先天过 boot。要分清这张图的边界:它是靶子本身的施工规格(对照组预建什么),不是验收门的定义——加在这靶子上的三联动门、经济门、latch 门是 D 族的事,这里只画这把「卷子」长什么样,不画怎么判卷。 + +### 图 G3 · 模型矩阵 + 跑序 + +![图 G3 模型矩阵与跑序](assets/t2-G-03-模型矩阵与跑序.svg) + +「便宜模型」是个集合不是一个值,这张图最该让人记住的就是这件事:过门率、成本、收敛步数这三个产出数必须各有归属对象,否则「60% 是哪个模型的 60%」根本答不上来。所以 spike 不是笼统地拿「便宜模型」跑,而是跑一张点名到具体模型的矩阵——主力便宜档 deepseek-v4-flash(现行 Tier0/1 打底模型、tier2 自治的主力候选,spike 真正要回答的「便宜到什么程度还守得住」就是看它),强便宜档 deepseek-v4-pro(现行救场档,测贵一档便宜模型是否显著抬过门率,退路树第一条触发线直接读它),中等 agentic 档 MiniMax-M3(这批最能打,先用它证路),强模型基线 Opus/Fable(只跑 1~2 款作路通不通的上限基线、不进成本评估)。前两档是现行在产模型(实线),后两档里 M3 的原生接法和自治产物判定待建(虚线),Opus/Fable 是远期不押的天花板基线(紫)。 + +样本量这一格承接的是一条踩过的硬教训——别拿单次跑数当基线。每个便宜或中等档都要跑 n≥30 真跑才算数:题面用 5 个一句话变体(美食、水果、咖啡、面包、糖水店),每变体每档跑 6 次,5×6 凑够 30;强基线 Opus/Fable 不铺满,n=2~3 即可,因为它只验上限不算单价。这张图把跑在哪也画死了:mini-desktop——权威构建加 e2e 门加 x86 同构,禁本机 6c6g 跑 chrome(exit 144 / OOM 红线)。这条不是随手提的运维细节,而是 spike 数据可信的前提:在非同构机器上跑出来的过门率,作不得正式依据。 + +跑序那一块是创始人 2026-06-21 定的,它的设计取舍是「别一上来把整张矩阵 × n≥30 全铺开」。先用 M3 证路:让它全流程自治产一款 mini-肥鹅,创始人亲玩判有没有「肥鹅味」——这一步是软门、是人锚,证的是「便宜模型自治这条路到底走不走得通」,而且它是亲玩判定不是统计,所以 M3 这一步先单独走、不先铺 n≥30。路走不通,就别在更便宜的模型上空耗。证通之后再用 v4-flash 和 v4-pro 各跑一轮 n≥30 比成本,看把模型降到主力便宜档、过门率和单款成本各掉多少——这一步证的是「便宜到什么程度还守得住」。这个先证路再比成本的顺序,把最贵的失败(在便宜模型上空耗到发现路根本不通)挡在了最前面。M3 的具体接法(走官方 AnthropicChatModel 对 new-api 的 /v1/messages 端点、吃原生 Anthropic 协议加 agentic 工具循环)在 C 族放大,这张图不重画,只标它走原生接法、待建。 + +### 图 G4 · 过门阈值 + 采集字段 + +![图 G4 过门阈值与采集字段](assets/t2-G-04-过门阈值与采集字段.svg) + +没有数字阈值,go/no-go 必然滑成「再调一轮」,退路树也跟着悬空。这张图把过门判据钉成五维带精确阈值的硬门加一道软门,左半部分就是这五维。前四维是数字硬门、全绿才 go:过门率(L1 确定性门加三联动门加经济门全绿加 latch,★≥50% 起评、≥70% 算强信号,对照现行 factory 路 60% / cutover 门 80% 而 tier2 富游戏更难,spike 阶段先看是否显著大于 0、能否随模型档升),单款成本(★≤¥3/成功款,取现行 L2≤¥5 偏下、留自治多轮的空间,撞上限即触发退路),收敛步数(≤max_iters,★ 单系统 8 轮 / 整局 40 轮,防靠运气擦边、超即判不收敛),长程一致性(12+ 文件工程过程无 checkpoint 丢失、半轮副作用幂等无脏)。第五维是人锚软门——创始人试玩判一句「是不是个有肥鹅味的可玩雏形」,它不可被任何确定性指标替代,但单它也不构成 go:四维过了人锚却没味,仍按退路树分流,不强行放行。这张图最该让人看清的就是这种「数字硬门加人锚软门」的双重结构——既不让冷冰冰的指标全权裁定一款游戏好不好,也不让一票主观品味绕过客观地板。 + +右半部分是 run 级采集字段,每款一行。这一块存在的理由很硬:没有字段定义,跑完拿不到可对比的数。字段按用途分组——标识(run_id / model / stage / brief_variant),过门核心(pass 取 verdict.pass、repairs 取 studio 的 attempt 计数即自治循环轮数),失败定位(fail_stage 落在 extract / validate / build / seven_gate / 三联动门 / 经济门哪一段、fail_system 落在 resource / merge / order / 表现层哪个系统),成本与墙钟(cost_rmb 与 tokens_by_model 取 new-api quota 口径经 cost.py 折¥、wall_s 端到端耗时),长程一致性三字段(file_count / total_loc 加 ctx_compressed / checkpoint_recovered / idempotency_clean,直接喂判据④)。fail_system 这一列是经营品类特有的、也是退路树分流的关键依据——它能区分「整轨范式不行」和「某个系统的骨架缺口」,这两者的退路完全不同。 + +图里有一个字段块特意标了「仅第二段」,这是这张图埋的一条设计线。自产 driver 安全三字段(driver_authored / driver_rejected_by_review / driver_edits)只在第二段开放自产 driver 时采,第一段不采——因为第一段的 driver 是人预建的、不让 agent 碰,根本不存在「写者判自己卷子」的风险。这条字段块对应的是 Goodhart 防线:防 agent 用改 driver 来逃避卡死探测、防它把判卷的 driver 写成只读不暴露真实力的字段。底部那条汇总带把这些 run 级字段卷成矩阵级三张图(过门率 = pass 款数 / n、¥/成功款 = Σcost / pass 款数、收敛中位数、fail_system 分布),它们就是 go/no-go 的直接输入,对照左半的阈值和退路树触发线判。最该 review 的缝同样是那些 ★ 阈值——50%/70% 的过门率门和 ¥3/款 的成本闸都是建议值,需要创始人和实测校准,这张图把它们标出来而不是假装它们已经定死,正是为了不让一个还没校准的数字悄悄变成生死线。 + +### 图 G5 · 两段实施 + 退路树 + +![图 G5 两段实施与退路树](assets/t2-G-05-两段实施与退路树.svg) + +这张图是 spike「怎么验、崩了往哪退」的可执行 runbook,核心设计是变量隔离的两段。第一段是纯模型变量:driver 是人预建的、冻结的,不让 agent 碰,只测「填差异」这一个变量。它先预建(人投入,Opus 或人写,靠现行件)——固定的 mini-肥鹅 经营骨架工程(三系统加耦合点、先天过 boot)、人工 driver(点合成 / 凑单 / 交单的确定性序列)、数据表 schema(留空给 LLM 填)、共用资产池占位图;再跑(便宜模型自治填那 56%)——便宜模型在骨架上填数据表加写表现层,跑的是 Agent 内 ReAct 多轮(max_iters 放开,不是 studio 现行那种 max_iters=1 加外层 repair 的形态),循环是「写源→build→headless 快检→L1 门→读 verdict→改」,spike 最小版直接最小 AgentScope 加硬编码配置、不上 service 也不上 Agent Team 和配置外置;最后采集加第一段 gate(过门率 / 成本 / 收敛是否达阈值)。把 driver 冻死在第一段,是为了让这一段的结果干净——过门率高低只反映模型填得好不好,不掺杂 driver 写得好不好。 + +第一段证通才进第二段开放自产 driver,这一段测自治上限加 Goodhart 安全,整段待建。它放开让 agent 自产或扩 harness 的 driver,但必须走三层隔离:agent 提议 driver(写者提交取证脚本但不许直接当判据),平台按 schema 和白名单编译(越界即拒),独立 adversarial 评审(一个不向着被评对象、专找漏洞的评审,查它是否覆盖真实玩家路径、是否读了作弊字段),三层全过才入验收。这三层隔离的要点就是图底那条红线铁律——写者不能写判自己游戏的那张卷子。两段之间的 gate 卡得很清,这是这张图第二个该让人看清的逻辑:第一段崩(纯模型变量就崩)直接进退路树、不开第二段,因为连固定 driver 都填不出来,放开让 agent 自产 driver 的开放自治只会更糟;第一段过、第二段挂在 driver 安全,判的是 Goodhart 防线的设计问题而不是模型问题——模型能写出来,是隔离防线没拦住作弊,该回去补防线、不该怪模型。把「模型问题」和「防线问题」用这道 gate 分开,是为了不让一次作弊翻车被误读成范式失败。 + +退路树是这张图的下半部分,它存在的全部意义是让 no-go 之后有确定的去处、绝不滑成无限调参。据矩阵级的过门率加 fail_system 分布,按三条数字触发线纵向分流出五个出口:Q1 问最强便宜档 v4-pro 是否仍<40%,否(≥40%、达阈值)就 GO 转第三步铺引擎(人锚仍须过);是,再问 Q2 失败是否集中表现层,是就 R1 退向更模板化(判 56% 自治承重太重,改成更多预制表现模板、少 LLM 写);否则问 Q3 是否某系统装不出而其余能过,是就 R2 补骨架再试(判骨架 / driver 缺口、不是范式问题);否则问 Q4 是否便宜档全线<20%而强基线 Opus/Fable 能过,是就 R3 判便宜模型天花板(换更贵模型重估经济性、撞 ¥3/款 缓行,或整轨缓行),否则 KEEP 留观(既非全线崩也非天花板,据具体数微调前置物再跑)。这五个出口每一个都是「据数字裁定一步」,退路树真能被触发、不悬空,连 KEEP 都只许据具体数微调一轮,这正是「绝不滑成无限调参」这条铁律在图上的落地。自产 driver 三层隔离的更细展开在 D 族(D4),这张图只画到三层的形状,不重画。 + +## 3 图清单与状态表 + +| # | 图名 | 形式 | 状态 | 覆盖内容 | +|---|---|---|---|---| +| G1 | 建设五步 + 0号 spike 生死门 | SVG · 纵向五步 + 旁路框 | 建(tier2 待建 · 五步 + spike 生死门)/ 缓(Cocos 轴 = 远期紫) | 五步纵列(搭 AgentScope / 配置外置 / 搭 Phaser 引擎 / 自治过人审 / Cocos 加渠道 adapter);spike 插在二三步间、过 go / 不过 no-go;第三步五块隐藏硬工作(验收地板 / Goodhart 安全 / 成本强制 / 源项目契约 / 可观测早建)+ 第四步三块(终审判据 / 终审吞吐 / player panel 减负) | +| G2 | mini-肥鹅 靶子规格 | SVG · 三系统拓扑 + 胜负 latch | 建(tier2 待建 · spike 靶子施工图) | 合成 / 资源 / 订单三系统的数据表与确切耦合点(资源 = 读写交汇、跨表可达性 = 核心考点);赢(金币达 100)与输(连续 3 单流失)双路径 latch;内容量 12 物品 / 6 链 / 5 订单 / 2 货币;相对 wanglanmei-ref 的砍法 | +| G3 | 模型矩阵 + 跑序 | SVG · 矩阵表 + 跑序流程 | 现(deepseek 两档 / mini-desktop 已有)/ 建(tier2 spike 矩阵)/ 缓(Opus·Fable 仅基线) | 四角色档(v4-flash 主力 / v4-pro 强便宜 / M3 中等 agentic / Opus·Fable 上限基线)各自模型与样本量;5 题面变体 ×6 = n≥30、跑在 mini-desktop;跑序(先 M3 证路 → 便宜档比成本,2026-06-21 创始人定) | +| G4 | 过门阈值 + 采集字段 | SVG · 五维判据 + 字段分组 | 建(tier2 待建 · spike 阈值 + 采集字段;★ 需创始人和实测校准) | 五维过门(过门率 ★≥50%/70% / 单款成本 ★≤¥3 / 收敛步数 ★8·40 轮 / 长程一致性 / 人锚软门);run 级采集字段(标识 / pass·repairs / fail_stage·fail_system / cost·tokens·wall / 长程三字段 / 自产 driver 安全仅第二段);汇成矩阵级三张图当 go/no-go 直接输入 | +| G5 | 两段实施 + 退路树 | SVG · 两段泳道 + 退路决策树 | 建(tier2 待 0号 spike 验证) | 第一段纯模型变量(预建 / 跑 / 采集 gate,driver 冻结)、第二段开放自产 driver(三层隔离 + 两项采集);两段间 gate 铁律(第一段崩不开第二段、第二段挂 driver 判防线问题);退路树五出口(GO / R1 退模板化 / R2 补骨架 / R3 天花板 / KEEP 留观)据三条数字触发线分流 | diff --git a/docs/architecture/架构/生成引擎/tier2细节图说-H-观测与成本.md b/docs/architecture/架构/生成引擎/tier2细节图说-H-观测与成本.md new file mode 100644 index 00000000..32d28e73 --- /dev/null +++ b/docs/architecture/架构/生成引擎/tier2细节图说-H-观测与成本.md @@ -0,0 +1,90 @@ +--- +date: 2026-06-23 +topic: tier2 细节图说 · H 族——观测与成本(生成引擎子树·tier2) +status: 设计中(tier2 待 spike) · 每图映射源档见该图脚注 / frontmatter 记 hash 作防漂移门 +映射源档: + - path: docs/architecture/架构/生成引擎/tier2实现详设.md + hash: d5efe45f + - path: docs/architecture/架构/生成引擎/agentic集成架构.md + hash: 1b3e375a + - path: tier2/HANDOFF.md + hash: ccb00bb9 + - path: docs/architecture/架构/生成引擎/agentic运行时架构图说.md + hash: 32adda95 +--- + +# tier2 细节图说 · H 族 —— 观测与成本 + +> 本篇是绘境AI 架构图集 **生成引擎子树** 下的 tier2 细节图说,只覆盖 **H 族(观测与成本)** 三张图。生成引擎主干、tier2 总览、agentic 运行时各有自己的图说;这里专门把「一次生成到底干了什么、花了多少钱、这些数据怎么收成一份口径」这件事画清楚。 + +--- + +## 0 阅读约定与同步纪律 + +H 族讲的是 tier2 富游戏自治生成线怎么被看见、怎么被算账。让 agent 自治写游戏只是第一步,平台还得能反查每一次生成的全过程,还得能把每一款的成本对到一笔权威账上。三张图分管三件事:统一 trace 契约怎么让两条异构的生成线写进同一张表(H1)、tier2 这条线靠 AgentScope 官方管道怎么把轨迹吐出来(H2)、成本怎么从 token 折算成每款的人民币并收口到 new-api 一个计费平面(H3)。 + +这三张图映射四份源档。统一 trace 契约的实现接点出自《tier2 实现详设》的「统一 trace 契约的实现接点」节,它讲 tier2 这一侧怎么把 ReAct 三段填进契约。契约的完整治理口径——为什么消灭 split-brain 是「诚实镜像各自字段」而不是「强求对齐」、接口对称内容不对称怎么成立、观测管道的官方件链路、D12 预算闸缺什么——出自《agentic 集成架构》的「观测/审计仓」与「D12 运行治理门」两节。采集指标的字段定义(`cost_rmb` / `tokens_by_model`)出自《tier2 实现详设》的「采集指标字段表」。成本取证那条要补 `RecordingChatModel(AnthropicChatModel)` 变体的接点出自 `tier2/HANDOFF.md` 的「U7 成本取证」。frontmatter 记了这四份的当前 commit hash,作为防漂移门——其中任一份动了观测或成本的口径,本图说与对应 SVG 必须同步改。 + +整条 tier2 富游戏线现在 **整体待建**:0号 spike 还没跑,引擎没搭,代码一行没落。所以 H 族里凡是 tier2 专属的机制——统一 trace 契约的 `contracts/trace/` 立位、tier2 这条线的 adapter、Anthropic 路的录制变体——都是设计已出、尚未落地的状态,用虚线画。但这三张图都不是纯虚的,各有一段实打实的现行底座撑着。可观测面的官方件(Event System、TracingMiddleware、OTel、Studio)是 AgentScope 2.0.3 的现成件,源码已逐条核过,tier2 直接订阅、不必自造,这部分用实线画,表的是「官方现成、直接可用」。成本面的 new-api quota 计费平面是早已部署在跑的权威成本源,`cost.py` 读 `logs.quota` 折人民币是仓内 `newapi-billing-plane-integration` 已落的能力,这部分也用实线,表的是「现行已落」。SAA 廉价线那条 Java 线的节点裁决埋点同样是现行已跑的。看图时记住这条对照:**实线 = 现行已落或官方现成件(SAA 节点裁决埋点 / AgentScope 官方观测管道 / new-api quota 计费平面);虚线(短划线)= tier2 专属、待 0号 spike 验证后才落代码的新机制。** 个别图上还有一抹远期紫,标的是 `contracts/trace/` 这一类还没建的 additive 契约立位——它不是已有件、也不只是 tier2 私有,而是随 spike 或控制面 phase-1 才新立的契约位,别当现成。 + +本族是 [agentic运行时架构图说](agentic运行时架构图说.md) 的放大层,deepen 不 duplicate。运行时图说的图 7「产物与契约」只点了 trace 契约的两段结构(公共核心子集 + tier2 扩展段),它的术语映射节(图 6)只把「可观测 = Event System → TracingMiddleware → Studio」点了一行。H 族把这两点逐项展开:H1 把对称核心五字段加两轨扩展段逐项摊开、画出 adapter 双轨怎么汇进契约;H2 把官方观测管道的四节点链路加七类强类型事件逐个画清;H3 把运行时图说没细讲的成本折算链路独立成图。要看 tier2 整轨的全貌从运行时图说进,要看观测与成本这一面的细节看这里。 + +## 1 全图通用图例 + +H 族用一套统一的徽章和线型,先在这里讲清,后面每张图不再重复。 + +**生产维度徽章**标的是这块东西服务于哪个非功能目标:蓝色 **可观测** = 让一次生成的全过程能被看见、被反查;绿色 **成本** = 让每款的花费能被算准、被对账;灰色 **数据** = 落进采集字段的那些列。H 族主要落在可观测和成本这两维上。 + +**状态徽章**标的是单块组件的成熟度,跟整图状态条配合读:绿色 **现行 / 已落 / 廉价线已落 / 承现行** = 这块东西现在就在跑(new-api quota 平面、SAA 节点裁决埋点、`cost.py` 读 quota);蓝色 **官方 / 官方 typed / 标准** = AgentScope 2.0.3 或 OpenTelemetry 的现成件,直接订阅即用;紫色 **待建 / 待补 / 待立 / 契约位待建 / additive 待立** = tier2 专属、尚未落代码的新机制或新契约位。 + +**线型**承担状态语义。实线框 = 现行已落或官方现成件,虚线框(短划线 `stroke-dasharray 6 4`)= tier2 专属待建。实线箭头 = 现行已有的链路或官方件之间的转移,虚线箭头 = tier2 待建的订阅 / 映射流程。 + +**状态码**四个,贯穿生成引擎子树:**现** = 现行已建在跑;**接** = 设计已出、代码待接线;**建** = tier2 立项后要新建、当前待 spike;**future / 远期** = 更长期才铺、不在本期。H 族里 new-api quota 平面与 cost.py 是「现」,AgentScope 官方观测管道是官方现成(可直接接,记「接」),`contracts/trace/` 立位与两条 tier2 adapter 与 Anthropic 录制变体都是「建」。 + +## 2 图集 + +### 图 H1 · trace 统一契约 + +![图 H1 trace 统一契约](assets/t2-H-01-trace统一契约.svg) + +两条生成线长得不一样,却要把轨迹写进同一张表,这件事一旦做错就会变成两套谁也对不上的日志。这张图要让人看清的,是「一份契约管两条异构线」凭什么能成立——它不靠强求两条线长成一个样,而靠一个对称的公共核心子集加各轨一个不对称的 JSON 扩展段。 + +先得把一个常见的错判扭过来。把轨迹收成一份,直觉上像是要消灭 split-brain,而消灭 split-brain 听起来就该是「让两条线的字段对齐」。这是错的。tier2 这条线是 ReAct 的「想一步、做一个动作、看一次结果」,SAA 廉价线是 16 个节点的阶段裁决,两者本就不同构——强求它们字段对齐,等于逼一条线编造它根本没有的字段。图顶那条红带说的就是这个真口径:**消灭 split-brain = 每条派发路诚实镜像它真有的字段、没有的绝不编造,不是强求对齐。** 正确解是把同一张表切成两部分:一个对称的公共核心子集,加各轨自己的不对称扩展段——接口层对称、内容层不对称,这才是一份契约管两条线的成立条件。 + +表结构这块是本图的核心,也是对运行时图说图 7 的放大。图 7 只点了一句「公共核心子集 + tier2 扩展段」,这里把五个对称字段逐项摆出:`traceId`(一次生成的轨迹主键)、`step`(第几步 / 第几节点)、`cost`(这一步折成人民币的成本)、`verdict`(这一步或这道门的裁决)、`timestamp`(发生时刻)——两条线都必须老老实实填上这五样,字段同名同义。扩展段则各写各的:SAA 那一列(实线,因为它在廉价线上已落)塞它的阶段、修复轮次、门裁;tier2 那一列(虚线待建)塞它独有的推理、动作、观察。两列虽然同在一张表里,内容互不编造、互不要求对齐。 + +两条线的采集机制差别很大,但这恰恰是设计成立的地方,不是缺陷。图中间那两个 adapter 框画的就是这件事:SAA adapter(Java 线、实线承现行)按 16 节点的阶段裁决埋点,经 adapter 映射进契约;tier2 adapter(Python 线、虚线待建)走 `Event System → TracingMiddleware → OTel` 这条官方管道汇进 Studio,再加一层 adapter 把事件按「公共核心子集 + 扩展段」映射进表。**trace 契约约束的是数据口径,不是采集机制**——采集两条线各按各的框架来,数据口径不随框架漂移。 + +这份契约的落处是 `contracts/trace/`,作为契约组的新一类 additive 立位(图右下那个远期紫框),内容含四样:字段定义、schema 版本、敏感字段脱敏规则、两条线 adapter 怎么映射。要特别说清的现行边界是:**这一位当前还没建**——它随 spike 或控制面 phase-1 落地时再新立,现在别把它当现成件引用。最后是写失败时的策略,图底那条黄带把它钉成一个必须选边、不能既要又要的决策:轨迹写失败时默认 **best-effort 不阻塞主生成流程,但落一条告警**。理由很直接——不能让一次落库抖动把整局已经跑出来的生成废掉,但也不能让它无声丢失,所以计入告警。这套观测真正的价值,是任何一次生成都能反查「它当时用的哪几条配置的哪个版本」,这样才回答得了「那批游戏质量掉了,是不是上周改的那条 prompt 干的」这种问题。 + +### 图 H2 · tier2 观测管道(Event System → OTel → Studio) + +![图 H2 tier2 观测管道](assets/t2-H-02-观测管道.svg) + +H1 给了 tier2 adapter 走官方管道这一句结论,这张图把那条管道逐节点展开,要破除的误解是「tier2 写轨迹得自己埋点」。事实正相反:AgentScope 2.0.3 本身带一套完整的 typed Event System,tier2 只订阅、不自造,再走官方的 TracingMiddleware → OTel 管道汇进 Studio,最后才加一层自建 adapter 映射进统一契约。 + +横向那条主链路是四个官方现成件接成的(图里全用实线、蓝色官方徽章,源码已核)。第一节 **Agent Event System**:ReAct agent 每跑一步就吐出一套强类型事件流,框架自带,不必自己埋点(源码 `agentscope/event/_event.py`)。第二节 **TracingMiddleware**:这个中间件直接调真 OTel SDK 的 `start_as_current_span`,把事件转成 span、挂上 attributes 和 status(源码 `middleware/_tracing/_trace.py`)。第三节 **OpenTelemetry span**:标准链路追踪 span,分 agent / llm / tool 三类 span_name,带 OK / ERROR 状态——这是真 OTel SDK 而非 mock,所以可以对接任何标准后端。第四节 **AgentScope Studio**:开箱即用的可视化,逐步呈现推理、工具调用、模型用量、一轮回复的边界,不必自造前端。一句话:tier2 写轨迹 = 订阅事件 + 官方 OTel 管道 + 一层 adapter。 + +中段把 Event System 吐的事件流逐类摊开,这是源码 `agentscope/event/_event.py` 逐条核过的七类。`TextBlock*` / `ThinkingBlock*` / `ToolCall*` 三类各带 Start / Delta / End 三相,分别对应文本、思考、工具调用;`ToolResult*` 是工具结果;`ModelCallStart / End` 圈住一次模型调用,而且 End 那一下带 token 用量(input / output_tokens)——这一条对 H3 的成本台账是关键,token 就是从这里抓;`ReplyStart / End` 圈住一轮回复,正好框住一步完整的 reason → act → observe。把这七类事件画清,是为了让人看出 tier2 的 ReAct 三段扩展段(推理 / 动作 / 观察)在事件流里都有现成对应——所以 tier2 adapter 的活只是「订阅 + 映射」,不是「埋点 + 采集」。 + +底部那段 adapter 层把两条线的对照画完整,正是「接口对称、内容不对称」在可观测面的落点。tier2 adapter(虚线待建)订阅上面的 Event System,机制是 **订阅 typed 事件流**;SAA adapter(实线、廉价线已落)按它自己的 16 节点裁决埋点,机制是 **节点裁决埋点**——两条机制各异,却写进中间同一张 `contracts/trace` 统一表(那个契约位仍是待建的紫框)。图底蓝带重申两件现行边界:写失败默认 best-effort 不阻塞、计入告警;存储复用已部署的 MySQL 加对象存储,不上重型可观测中间件——观测要早建是为了 spike 调试和对账当下就用得上,但不等于要为它铺一套独立基建。 + +### 图 H3 · 成本台账(RecordingChatModel → new-api quota) + +![图 H3 成本台账](assets/t2-H-03-成本台账.svg) + +成本对账这件事,绘境的口径一直很硬:成本不是估的,是从 new-api 的 quota 权威口径折出来的每款人民币。这张图要讲清的,是 tier2 接进这套口径时缺了一块、不补就会让 spike 的关键一档算不出账——M3 那一档走的是 Anthropic 原生端点,现有的成本记录只覆盖 OpenAI 路,抓不到它。 + +缺口在图左上和右边那个红框里讲得最直白。M3 是 spike 里 A 门那一段用来「先证路」的模型(先用 M3 证明这条自治路走得通,再用便宜档比成本),它走 `AnthropicChatModel`、用 Anthropic 原生端点 `/v1/messages`。但现有的成本记录只覆盖 OpenAI 路——便宜档(deepseek-v4-flash / v4-pro)走各自端点,由现有 OpenAI 路的记录覆盖,唯独 Anthropic 这一路没有对应的录制件包住调用。后果是确定的:M3 这档的 token 用量采不到,`¥/成功款` 这个数对 M3 直接缺,全矩阵成本没法对比。所以接点很明确——补一个 `RecordingChatModel(AnthropicChatModel)` 变体(图左上虚线待补框),它包住模型调用、抓每次的 per-model token 用量,把 Anthropic 这一路补齐。 + +折算链路是三步,横向铺开(图中段)。第一步 **抓 token**(待补):`RecordingChatModel` 包住每次模型调用,逐次记 token、按模型分列成 `tokens_by_model`。第二步 **new-api quota 折¥**(现行已落、绿框):用 new-api 的 quota 口径折人民币,`cost.py` 读 new-api 的 `logs.quota`——每次调用的 quota 就是真实倍率成本,这是权威源,不是按公开单价估的。第三步 **落采集字段**(数据):`cost_rmb` 和 `tokens_by_model` 落 run 级、每款一行(字段定义对到 G 族 G4 的采集字段表),再汇到矩阵级算出 `¥/成功款 = Σcost / pass 款数`,这个数直接喂给 spike 的 go/no-go 三张图。token → ¥ → 采集字段,一条链就把每款的成本钉到了权威账上。 + +底部那条计费平面带讲的是这套口径能成立的根本原因:**模型统一从 new-api 出口走,不论走哪条端点,计量都收口到 new-api quota 一个计费平面。** M3 走 Anthropic 端点、便宜档走各自端点,协议和 SDK 不锁死、每档走它各自最优的端点,但所有路最终都收口到 quota 这一个口径上 per-model 折¥。这是「协议自由 + 计费收口」的设计:上层任各档自由选最划算的接法,下层用一个统一的权威口径把成本拢回来对账。要查 NEWAPI_KEY、端点和机器,去 `docs/内网凭据与端点.md`——那是内网凭据的单一事实源。 + +## 3 图清单与状态表 + +| # | 图名 | 形式 | 状态 | 覆盖内容 | +|---|---|---|---|---| +| H1 | trace 统一契约 | SVG · 表结构 + adapter 双轨 | 建(tier2 待建 · contracts/trace additive 待立;SAA 廉价线节点裁决已落) | 消灭 split-brain 的真口径(诚实镜像非强求对齐);公共核心子集五字段(traceId/step/cost/verdict/timestamp)对称 + SAA / tier2 两轨 JSON 扩展段不对称;SAA adapter(实)+ tier2 adapter(虚)汇进 contracts/trace;best-effort 写失败计入告警 | +| H2 | tier2 观测管道(Event System → OTel → Studio) | SVG · 横向链路 + 事件流逐类 | 接(官方现成件可直接接)/ 建(tier2 adapter + contracts/trace 自建待建) | 官方四节点管道(Event System → TracingMiddleware → OTel span → Studio);七类强类型事件(TextBlock/ThinkingBlock/ToolCall/ToolResult/ModelCallStart-End 带 token/ReplyStart-End);两线 adapter 机制各异契约一致;best-effort 策略 + 复用 MySQL/对象存储不上重型中间件 | +| H3 | 成本台账(RecordingChatModel → new-api quota) | SVG · 折算链路 + 计费平面 | 现(new-api quota 平面 / cost.py 读 quota 已落)/ 建(RecordingChatModel(Anthropic) 变体待补) | 红线缺口(不补 Anthropic 录制变体则 A 门 M3 成本抓不到);折算链路 token → new-api quota 折¥ → 采集字段(cost_rmb / tokens_by_model);计费平面收口(M3 Anthropic 端点 / 便宜档各自端点 all roads 收口到 new-api quota 一个口径) |