6ef0b5d75e
以 2026-07-03《生成引擎实现与图说一致性对账》§5 八条 + 重推演 Δ6/Δ9① + 预算两段式裁决为据,把掉队约两周的运行时图说追回现实,写前逐条重核工作树代码。 图说本体(主对象): - 配置口径反转:ADR-4/A13/§5.2/§5.8/对标表/五列/§二补④ 从「Langfuse 式热取 + GitOps 四闸」改为「yudao 配置中心版本化(MySQL 版本行)⊕ Nacos 下发 ⊕ AgentScope per-POST 热重载」,阶段〇+一① 已代码落地;Langfuse 式退历史备选、原表保留作决策留痕。 - §4.2 收敛环:前瞻「go(留观微调)」改为真跑 conditional 结论,补 agent 层 win-balance 瓶颈(约 1-2/5 thrash)、网关无强档记 conditional no-go、F-1 反馈补厚已落。 - §4.1 便宜档:补运行时载体已 Python 化(cheap-worker 双入口 CLI+Service、复用 tier2 worker 包;Node 拆两半:gen.mjs 退对照、tools.mjs/serve-and-play.sh/play.cdp.cjs 九门执行层 shell-out 仍活);「十一插件」核正为十二(8 基元+4 编排)。 - §5.3 续修:回同续修原语迁入 on_reasoning 的 RepairMiddleware(单 POST 内 finish 点 续修=生产主路,外层 resume 为本地 runner 并存 fallback);预算两段式(软停线 ¥10/¥50 + 硬地板 ×1.5=¥15/¥75、与轮数/墙钟任一先到即停),§5.2/§5.7 同步。 - §5.1 checkpoint 降准(每外层 resume 落本地 JSON;Redis durable 已编码未真跑);服务壳 已编码真跑未验证、阶段一 Agent Team 已提前落地默认开启。 - §5.4 删 DockerWorkspace 前置阻断句(06-28 已裁 in-process);A2.5 表行改现·部分; 补引质量 canonical(D11 权重管辖已移交、四层塔与三层校验共用 L1-L3 但异轴防混)。 - §一 Δ6：第一原则改述为「接缝按变更频率设」(模型月换>品类周扩>引擎季增>框架可能永不换; 协议脊柱与 judge 独立两资产保留;框架适配验证明确为远期非投入项)。 - §三 Δ9①：A8–A13 加「单实现期不冻、第二消费者出现才抬升」注记(不删行);C5/C6 判分 闭环两契约入表(PlaySpec 考卷/VerdictFeedback 判卷反馈,已立 schema+校验器、生产接线 在途,指 contracts/play-loop/)。 - A11(工单第 10 条)复核:图说 §六已是完整 A11 章节，无需重复补——系对账/工单误判。 配套一处:contracts/trace/README.md 廉价线口径 SAA→cheap-worker(便宜档已 Python 化复用 tier2 TraceAdapter/schema,saa-trace-event schema 保留作 SAA 远期轨立位)。 代码触点一处:tier2 agent_loop/studio.py 头注释纠正（「不再外层 repair」与同文件外层 resume 相左）。 收尾:两份配置设计档 sot-impact「收口时回写」翻「已回写」；plan① §11 TODO ⑤⑥ 勾状态。 docs-gate 七检全绿；studio.py 语法校验通过。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
45 lines
6.0 KiB
Markdown
45 lines
6.0 KiB
Markdown
# contracts/trace/ —— tier2 统一 trace 事件契约(additive 立位)
|
|
|
|
这一目录登记 tier2 富游戏自治生成线的统一 trace 事件契约。它是契约组的新一类 additive 立位:只新增、不改动也不破坏任何现有契约(events / game-package / tier2-verdict 等),随 0号 spike 或控制面 phase-1 才真接代码。当前状态是「建」——设计已出、schema 已立,tier2 这条线本身整体待 spike 验证。
|
|
|
|
> **廉价线口径更新(2026-07-03)**:本目录 schema 设计时,"廉价线"指 SAA 的 16 节点 Java 编排。2026-06-26 起便宜档核心已整条 Python 化(cheap-worker,复用 tier2 的 `TraceAdapter` 与 `tier2-trace-event.schema.json`),所以**当前生产的便宜档 trace 走 tier2 那份 schema、不是 `saa-trace-event.schema.json`**。SAA 16 节点那条线已按生成运行时图说 §一降为最低优先级的远期适配目标;`saa-trace-event.schema.json` 与下文对它的描述保留作那条远期轨的立位、不删——等 SAA 真适配进来时它就是现成的 adapter 契约。下文凡以"SAA 16 节点廉价线"指代廉价线处,当前现实读作"cheap-worker Python 线、复用 tier2 schema"。
|
|
|
|
## 这是什么
|
|
|
|
`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,不携金额估算)。
|
|
|
|
## 两份 schema 的关系
|
|
|
|
本目录维护两份 trace schema,对应两条异构生成线:
|
|
|
|
| schema 文件 | 对应生成线 | 特有扩展段 |
|
|
|---|---|---|
|
|
| `tier2-trace-event.schema.json` | tier2 富游戏自治线(Python / AgentScope ReAct) | `ext`:reasoning / action / observation 三段(ReAct 推理→动作→观察) |
|
|
| `saa-trace-event.schema.json` | SAA 16 节点廉价生成线(Java / Spring AI Alibaba) | `ext`:nodeIndex / nodeName / nodeStatus(节点位置与执行状态) |
|
|
|
|
核心五字段(`traceId` / `step` / `cost` / `verdict` / `timestamp`)在两份 schema 里**完全同名同义**——这是 H1「接口对称」子集,让两条线写进同一张 trace 表时无需 join 也能按 `traceId` 对账。`ext` 扩展段各写各的、字段不要求对齐(H1「内容不对称」):tier2 的推理/动作/观察三段 SAA 轨不存在,SAA 的节点编号/名称/状态 tier2 轨也不存在,**没有的字段绝不编造**。
|
|
|
|
谁消费哪份:目前 tier2 侧 adapter(`tier2/gen-worker/observability/trace.py` 的 `TraceAdapter`)已产出并落盘(`JsonlFileSink` 写进 `_tier2-gen/<game_id>/trace.jsonl`);SAA 侧 adapter 在 Java 后端待产线接线(控制面 phase-1)。
|
|
|
|
## 与 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 的约束范围内,但读契约时该一并知道。
|