cc71dbbaf5
19 张新图经 draw→对抗验证→族汇编 workflow(43 个 opus 子代理)产出,每张是总览(agentic运行时架构图说.md 图1-8)的逐项放大(deepen 不 duplicate): - A: Agent Service+session三路 / Agent非常驻+AgentState / Workspace双轴 / Middleware洋葱 - F: 源项目契约七要素 / 第二装载分支 / finish共用schema - G: 建设五步+spike门 / mini-肥鹅靶子 / 模型矩阵+跑序 / 过门阈值+采集字段 / 两段+退路树 - B: 控制面四组件 / 反锁死五协议 / 预算三层强制 / 管理面三phase - H: trace统一契约 / 观测管道 / 成本台账 对抗验证逮修真问题:F3 落库/取回画成现行→改虚线待建、G2 56%张冠李戴、B1 tier2箭头几何错位、B2 伪造「伸缩」徽章删、H1 门裁九门/三层校验错配。主会话复验补逮 6 张脚注半角冒号(verify 脚本盲区)。 全 32 张复验 界内/良构/脚注/ok;5 族图说带防漂移 hash + 人读散文(零 AI 味)。8 族接进看图入口。tier2 全集=32 图+8 族图说。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
16 KiB
date, topic, status, 映射源档
| date | topic | status | 映射源档 | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2026-06-23 | tier2 细节图说 · H 族——观测与成本(生成引擎子树·tier2) | 设计中(tier2 待 spike) · 每图映射源档见该图脚注 / frontmatter 记 hash 作防漂移门 |
|
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运行时架构图说 的放大层,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 统一契约
两条生成线长得不一样,却要把轨迹写进同一张表,这件事一旦做错就会变成两套谁也对不上的日志。这张图要让人看清的,是「一份契约管两条异构线」凭什么能成立——它不靠强求两条线长成一个样,而靠一个对称的公共核心子集加各轨一个不对称的 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)
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)
成本对账这件事,绘境的口径一直很硬:成本不是估的,是从 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 一个口径) |