d6e977a5ac
按 tier2 图说目标做缺口分析(8族逐元素比对),补齐 0号 spike 为过门收窄掉、 但图说明确要求的「核心引擎待补」项。全部加性/observe-only:金标冒烟仍 ACCEPT (九门9/9+富游戏三门3/3,门一道没放松),真依赖下全链 import+自测+一款真 M3 跑验证通过。 G族(n≥30 runbook 执行基建): - worker/config.py: build_model_openai 便宜档 client(deepseek 经 new-api OpenAI 兼容路,与 M3 Anthropic 路并存) - worker/run_record.py: G4 采集字段表 → 可序列化 RunRecord(含退路树分流键 fail_system) - worker/fallback_tree.py: 退路树五出口判定器(Q1–Q4 数字触发线,★阈值常量区待校准) - batch_run.py / aggregate.py: model×variant×n 批跑(断点续跑/失败隔离)+ 矩阵聚合三图喂判定器 H族(观测/成本接线,把孤儿件缝进 run 主链): - observability/newapi_pricing.py: 活读 new-api /api/pricing 倍率(取不到回落显式参数+告警) - middleware.py: Tier2TraceMiddleware 挂 writer agent 最外层洋葱,ReAct 全事件旁路 ingest - agent_loop/studio.py 收口: records→cost_for_run 折¥;真跑实测 cost_rmb=1.29(newapi-live)、trace 647事件 dropped=0 - contracts/trace/: additive trace 事件契约位(忠实 trace.py 落 sink 形状) D族(L3 视觉软检接线,observe-only): - agent_loop/studio.py: 收口调一次 M3 多模态(真截图+真玩取证→fun映射0-100),只写 verdict.L3,绝不参与 decision - 真跑实测 L3 score=25 准确指出空心表现层;decision=fix 仍由 L1硬门/熔断裁、与 L3 无关(防 Goodhart 成立) 留后(不投机抢建):工作室 Agent Team/第二装载落库/控制面/Agent Service 等按 plan 决策②⑤ gate 到 B门后; n≥30 等统计相是「跑」非「写」(批跑底座已就位);A-model 4插件复用待合并对账;4处图说 spec-drift 待 doc 线回写。 详见 tier2/HANDOFF.md「图说对账补全」节。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
contracts/trace/ —— tier2 统一 trace 事件契约(additive 立位)
这一目录登记 tier2 富游戏自治生成线的统一 trace 事件契约。它是契约组的新一类 additive 立位:只新增、不改动也不破坏任何现有契约(events / game-package / tier2-verdict 等),随 0号 spike 或控制面 phase-1 才真接代码。当前状态是「建」——设计已出、schema 已立,tier2 这条线本身整体待 spike 验证。
这是什么
tier2-trace-event.schema.json 定义一条 trace 记录的形状。一条记录 = 一次生成轨迹里的一步,由公共核心五字段(traceId / step / cost / verdict / timestamp)加一个 tier2 私有的 ext 扩展段构成。核心五字段是两条生成线(tier2 ReAct 多轮、SAA 16 节点廉价线)都必须老老实实填上的对称子集;ext 是 tier2 这一轨各写各的不对称段,塞它独有的 ReAct 三段——推理、动作、观察。
这份契约约束的是数据口径,不是采集机制。两条线各按各的框架采集轨迹,但写进同一张表时字段同名同义。要让两条异构线共用一张表,靠的不是强求字段对齐,而是「接口对称、内容不对称」:核心子集对称,扩展段各写各的、没有的字段绝不编造。这才是消灭 split-brain 的真口径。
谁产
产出方是 tier2/gen-worker/observability/trace.py 里的 TraceAdapter。它订阅 AgentScope 2.0.2 官方的 typed Event System(ReAct agent 经 reply_stream() 吐的 AgentEvent 流),把每个事件经纯函数 to_trace_step 映射成这份契约规定的形状。tier2 这条线只「订阅 + 映射」,不「埋点 + 采集」——事件流是框架现成件,源码已逐条核过,不必自造。schema 里每个字段的口径都忠实映射 adapter 已实现的产出:adapter 没产的字段一概不写进契约;代码注释里标为可选、当前还没实填的字段(如 cost.tokens.cached、cost.cost_rmb),在 schema 的 description 里注明了它们各自的填充时机。
SAA 那一轨的扩展段由 Java 线另一个 adapter 产,字段与本契约的 ext 不同名也不要求对齐,各写各的——本契约只管 tier2 这一轨。
谁消费(后续)
消费链路按 H 族图说 H2 是「Event System → TracingMiddleware → OpenTelemetry span → AgentScope Studio」。trace 记录最终落进已部署的 MySQL 加对象存储,不上重型可观测中间件;观测要早建,是为了 spike 调试和成本对账当下就用得上,而不是要先铺一套独立基建。traceId 贯穿整条生成任务链路,既是反查键,也是成本关联键——它对接 tier2-verdict.schema.json 的 evidence.traceId,让一次验收终判能反查到它对应的全过程轨迹。成本侧由 cost.py 读 new-api 的 logs.quota 权威口径,按 traceId 关联后把人民币金额 best-effort 回填进 cost.cost_rmb(trace 阶段只记 token,不携金额估算)。
与 H 族图说的对应
设计权威是 docs/architecture/架构/生成引擎/tier2细节图说-H-观测与成本.md。
- 公共核心五字段 = 图 H1 的对称子集。
ext的三段(reasoning/action/observation)= 图 H1/H2 讲的 tier2 ReAct 三段扩展段,逐段对到图 H2 摊开的七类强类型事件:TextBlock*与ThinkingBlock*映射进reasoning,ToolCall*映射进action,ToolResult*映射进observation。- 图 H2 的另外两类事件——
ModelCallStart/ModelCallEnd与ReplyStart/ReplyEnd——在代码里不单独成段:ModelCallEnd带的 token 用量落进cost.tokens(供 H3 成本台账抓取),其余关键字段(模型名、回复边界、reply_id、agent 名)落进ext.raw。这一点是代码实现与图说「七类事件」措辞的精确对应,schema 的顶层 description 与各$defs段里都注明了。
写失败时的策略遵循 H1/H2 的 best-effort 铁律:轨迹写失败默认不阻塞主生成流程,但落一条告警——不让一次落库抖动把整局已经跑出来的生成废掉,也不让它无声丢失。这条策略在 adapter 代码里实现(ingest / _emit_to_sink 全包 try、只告警不抛),不在 schema 的约束范围内,但读契约时该一并知道。