feat(loop,gateway): 事件批 — tool_execution 三事件 + streamId + turn.start/end（裁决 01.4.1/01.4.2/01.4.3/01.4.5/03.4.4/1.12）
执行方案阶段 2 · P2-3（`DevDocs/audit/_plan.md`）。契约 `Docs/api-client.md` → **v0.50**。
- **01.4.1 `tool_execution` 拆三事件**：`model/stream.go` 删旧 `StreamKindToolExecution`，新增
`tool_execution.start/update/end` + `ToolPhaseRunning/Done/Error`（与 design/19 status 同值）；
`StreamEvent` 增 `Tool`/`Phase`；`loop/tools.go` 的 `emitToolExecution` 重写为结构化字段、
**Delta 恒空**（断言锁死），`ID` 复用 provider tool call id（可与 `tool_call.*` 关联）。
⚠️ **诚实边界**：start/end 有真实生产者；`update` 的 wire 映射已实现并单测锁定，但**工具分发器
无中途进度上报源 ⇒ loop 暂不产出 update 帧**（已在 api-client §3.1 如实登记）。
- **03.4.4 phase 驱动图节点状态**：`invokeOne` 用**单一 phase 决策**同时决定 end 帧 phase、
span 的 `phase` prop 与终态；`trace/graph.go` 新增 `FlowStatusForPhase`，`graph_build.go` 的
`AddSpan` 对 tool 节点**优先消费 phase prop**（缺省回落 span 终态 ⇒ 两路不可能矛盾）。
- **01.4.2 `streamId`**：`StreamEvent` 增 `StreamID`；`loop/stream.go` 每次 ChatStream 生成
`stream-<hex>`（crypto/rand，降级时间戳），该流所有帧共享、多步工具轮取新 id；`ws_bridge`
把它并进**模型流帧** `data`（`tool_execution.*`/`turn.*` 不带）。语义区分：`turnId` = 哪轮回答，
`streamId` = 这条流式消息。
- **01.4.3 `turn.start`/`turn.end`**：`loop/run.go` 入口发 start、defer 发 end，**覆盖全部出口**
（最终答案/安全网终止/预算耗尽/步骤错误）；帧**无 data 载荷**；静音的内部 run（backthink/子代理）
不发。顺带把 91 行的 `Run` 拆成 `driveTurn` + `settleAndReturn`（清掉一处既有 >80 行违规）。
- **01.4.5**：仅 `Docs/api-client.md` §3.5 补 `graph_update` 三范围（`web`/`web:<uuid>`/`sess-backthink`），
与 `wire_runtime.go` 的 allow 谓词一致，**零代码变更**。
验证：`go build ./...` 绿；本批四包（loop/model/trace/gateway）vet + 测试绿（含 `-count=1`）；
linux/amd64 + darwin/arm64 交叉编译绿；本批 16 文件 ≤500 行、函数 ≤80 行。
**真 WS 帧断言 8 条**：帧序 `turn.start → message.delta → tool_execution.start →
tool_execution.end → message.delta → turn.end`（+`stream_end`）、turn 边界无载荷且整轮 turnId 一致、
两条模型流 `streamId` 互异、tool 帧 `{tool,phase,id}` 且无 `delta`/`streamId` 键、
`turn.end` 在步骤出错时也发出、内部静音 run 不发边界帧。
**变异验证**：把 `ev.StreamID = streamID` 改为赋空 → 两条断言 FAIL（`streamId` 为空/两流同空），
还原后复绿（直接删行会先被编译期 `declared and not used` 拦截）。
未验证：前端未消费这些帧（本轮未动 `frontend/**`，「前端能渲染」待前端批）；无真实模型端到端。
This commit is contained in:
AskaEth committed
1 parent
afef75f640
commit
6e7ec56f9a
16 files changed
+982
-126
No files matched your search
@@ -23,6 +23,24 @@ const (
|
||||
FlowStatusError = "error"
|
||||
)
|
||||
|
||||
// FlowStatusForPhase 把工具执行的细粒度 phase（design/04 §1.1，
|
||||
// loop 随 tool_execution.end 帧一同记在 tool span 上）映射为流程图
|
||||
// 节点状态：phase 取值与本包状态枚举（design/19 §1 统一枚举）
|
||||
// 同构（running/done/error）。未知 phase 返回空串，调用方回落到
|
||||
// span 终态推导，因此缺 phase 的旧 span 不受影响。
|
||||
func FlowStatusForPhase(phase string) string {
|
||||
switch phase {
|
||||
case FlowStatusRunning:
|
||||
return FlowStatusRunning
|
||||
case FlowStatusDone:
|
||||
return FlowStatusDone
|
||||
case FlowStatusError:
|
||||
return FlowStatusError
|
||||
default:
|
||||
return ""
|
||||
}
|
||||
}
|
||||
|
||||
// FlowNode is one node in a flow graph. Status/SpanKind mirror the frontier.
|
||||
type FlowNode struct {
|
||||
ID string `json:"id"`
|
||||
|
||||
@@ -143,17 +143,26 @@ func (g *RunGraph) addEdge(from, to string) {
|
||||
// AddSpan folds a finished span record into the graph as a node with its final
|
||||
// status. State-transition spans are the step container and are omitted — but
|
||||
// their parent link is remembered so lane resolution can walk through them.
|
||||
// tool 节点的终态优先由其携带的细粒度 phase 驱动（design/04 §1.1 /
|
||||
// design/19 §1：running/done/error），缺失时回落到 span 终态推导，
|
||||
// 因此两套来源对同一节点绝不可能得出不同状态。
|
||||
func (g *RunGraph) AddSpan(rec SpanRecord) {
|
||||
kind := kindForSpan(rec.Kind)
|
||||
if kind == "" {
|
||||
g.rememberParent(rec.ID, rec.ParentID)
|
||||
return
|
||||
}
|
||||
status := statusForFinished(rec.Status)
|
||||
if kind == nodeKindTool {
|
||||
if ph := FlowStatusForPhase(spanPhase(rec)); ph != "" {
|
||||
status = ph
|
||||
}
|
||||
}
|
||||
g.Upsert(NodeSpec{
|
||||
ID: rec.ID,
|
||||
Label: labelForSpan(rec),
|
||||
Kind: kind,
|
||||
Status: statusForFinished(rec.Status),
|
||||
Status: status,
|
||||
StartedAt: rec.StartedAt,
|
||||
EndedAt: rec.EndedAt,
|
||||
Props: safeSpanProps(rec),
|
||||
@@ -162,6 +171,13 @@ func (g *RunGraph) AddSpan(rec SpanRecord) {
|
||||
})
|
||||
}
|
||||
|
||||
// spanPhase 读取 tool span 上记录的执行 phase；缺失或类型不符时返回
|
||||
// 空串（调用方据此回落），不区分「没有」与「读不到」。
|
||||
func spanPhase(rec SpanRecord) string {
|
||||
ph, _ := rec.Props["phase"].(string)
|
||||
return ph
|
||||
}
|
||||
|
||||
// AddSpanStart registers a running placeholder for a span that just began, so a
|
||||
// node appears as "running" before it finishes. State-transition spans are
|
||||
// omitted (their parent link is still remembered for lane resolution), matching
|
||||
|
||||
@@ -0,0 +1,80 @@
|
||||
package trace
|
||||
|
||||
import (
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
// TestFlowStatusForPhase 锁住 phase → 节点状态的映射（design/04 §1.1
|
||||
// 细粒度 phase、design/19 §1 统一枚举）：三个已知 phase 原样通过，
|
||||
// 未知 phase 返回空串让调用方回落到 span 终态推导。
|
||||
func TestFlowStatusForPhase(t *testing.T) {
|
||||
t.Parallel()
|
||||
cases := map[string]string{
|
||||
FlowStatusRunning: FlowStatusRunning,
|
||||
FlowStatusDone: FlowStatusDone,
|
||||
FlowStatusError: FlowStatusError,
|
||||
"started": "",
|
||||
"": "",
|
||||
}
|
||||
for phase, want := range cases {
|
||||
if got := FlowStatusForPhase(phase); got != want {
|
||||
t.Fatalf("FlowStatusForPhase(%q) = %q, want %q", phase, got, want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestAddSpanToolPhaseDrivesStatus 锁住裁决 03.4.4：tool 节点的终态由
|
||||
// span 携带的细粒度 phase 驱动（与 WS 的 tool_execution.end 帧同一
|
||||
// 取值），缺 phase 的 tool span 回落到 span 终态推导，两路绝不矛盾。
|
||||
func TestAddSpanToolPhaseDrivesStatus(t *testing.T) {
|
||||
t.Parallel()
|
||||
now := time.Now()
|
||||
tool := func(id, phase string, status SpanStatus) SpanRecord {
|
||||
rec := SpanRecord{ID: id, Name: "tool.echo", Kind: SpanKindTool,
|
||||
Status: status, StartedAt: now, EndedAt: now}
|
||||
if phase != "" {
|
||||
rec.Props = map[string]any{"phase": phase}
|
||||
}
|
||||
return rec
|
||||
}
|
||||
cases := []struct {
|
||||
name string
|
||||
rec SpanRecord
|
||||
want string
|
||||
}{
|
||||
{"phase done", tool("t1", FlowStatusDone, SpanStatusOK), FlowStatusDone},
|
||||
{"phase error overrides ok status", tool("t2", FlowStatusError, SpanStatusOK), FlowStatusError},
|
||||
{"no phase falls back to span status", tool("t3", "", SpanStatusOK), FlowStatusDone},
|
||||
{"no phase falls back to span error", tool("t4", "", SpanStatusError), FlowStatusError},
|
||||
{"unknown phase falls back to span status", tool("t5", "started", SpanStatusError), FlowStatusError},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
g := NewRunGraph("web")
|
||||
g.Start(1, now)
|
||||
g.AddSpan(tc.rec)
|
||||
if len(g.nodes) != 1 {
|
||||
t.Fatalf("nodes = %d, want 1", len(g.nodes))
|
||||
}
|
||||
if got := g.nodes[tc.rec.ID].Status; got != tc.want {
|
||||
t.Fatalf("tool node status = %q, want %q", got, tc.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestAddSpanNonToolIgnoresPhase 确保 phase 只驱动 tool 节点：其他
|
||||
// kind 的 span 即使带 phase prop（未来不该有），也不改变其
|
||||
// 终态推导路径。
|
||||
func TestAddSpanNonToolIgnoresPhase(t *testing.T) {
|
||||
t.Parallel()
|
||||
now := time.Now()
|
||||
g := NewRunGraph("web")
|
||||
g.Start(1, now)
|
||||
g.AddSpan(SpanRecord{ID: "l1", Name: "llm.call", Kind: SpanKindLLM,
|
||||
Status: SpanStatusOK, StartedAt: now, EndedAt: now, Props: map[string]any{"phase": FlowStatusError}})
|
||||
if got := g.nodes["l1"].Status; got != FlowStatusDone {
|
||||
t.Fatalf("llm node status = %q, want %q (phase must not drive non-tool nodes)", got, FlowStatusDone)
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user