fix(trace): 让 graph_update 的分支根节点 props.persona 真的前送(白名单漏登记)
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
CI / Frontend (tsc + vite build) (push) Has been cancelled

审计(DevDocs/audit/11-trace-observability.md 发现 #1):scheduler 用
span.SetProp("persona", sub.PersonaID) 设了这个 prop,api-client v0.47 也已把它写进
对外承诺,但 trace/graph.go 的 safePropKeys 白名单不含 "persona",而 safeSpanProps
只遍历白名单 ⇒ 该键在到达客户端前被静默丢弃(实测:整个 props 键都消失)。

修法:把 "persona" 加进 safePropKeys,并在同处写清它为什么可以前送 ——
① 它必然是注册表校验过的角色 id(scheduler.checkPersona 未知 id 一律 ErrUnknownPersona
拒绝整批派发);② 它本来就随 GET /personas 与 message_persisted.personaId 对外可见;
③ 值仍过 redactValue → RedactText(凭据形状清洗 + 80 rune 截断)。

测试:新增 trace/graph_persona_test.go(真 Tracer → 真 SetProp → 真 Snapshot,两条断言:
有 persona / 不指定角色时键不出现 = 钉住 v0.47 的"纯增量")+ 网关 flow_update_ws_test.go
追加 TestFlowGraphUpdateRelaysPersonaProp(真 bus Publish → 真 WS 帧 → 断言帧内节点
props.persona=="yuki")。

验证:go build/vet 绿;trace + gateway 包测试绿;全树 go test ./... = 58 包 ok / 0 FAIL;
linux/amd64 + darwin/arm64 交叉编译绿;gofmt -l 干净;三文件 471/57/370 行、最长函数 64 行。
变异验证:把 persona 从白名单摘掉 → 两条断言分别 FAIL(trace 层 props 为空;
WS 帧里 span-sub 节点的 props 键整个消失),还原后复绿。

遗留(登记):前端尚未消费该键(flow 节点未显示"以谁的身份替班")。
This commit is contained in:
AskaEth committed 2026-10-04 10:37:22 +08:00
1 parent 074ffc4ebf
commit 4bf1f7cac6
3 files changed
+155 -1

No files matched your search

@@ -187,6 +187,95 @@ func assertGraphMeta(t *testing.T, raw []byte) {
}
}
// TestFlowGraphUpdateRelaysPersonaProp 端到端钉住 v0.47 契约的后半段:
// 图构建器放行的 `props.persona`(子代理分支根节点上的目标角色 id)
// 经真实 bus 中继后,客户端收到的 graph_update 帧里仍然看得到它。
// 只在 trace 包断言白名单或快照不足以证明「客户端真的收得到」——
// 中继链路上任何一环重塑载荷都会让该键丢失,所以这条从生产者
// 快照一路查到下行 WS 帧。
func TestFlowGraphUpdateRelaysPersonaProp(t *testing.T) {
env := newEnv(t, nil, false)
tok := env.token(t, auth.RoleOwner)
wsURL := "ws" + strings.TrimPrefix(env.ts.URL, "http") + "/ws/chat?token=" + tok
conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil)
if err != nil {
t.Fatalf("dial: %v", err)
}
defer conn.Close()
_ = conn.SetReadDeadline(time.Now().Add(3 * time.Second))
// 与 TestFlowGraphUpdateRelayedToWS 相同:先往返一次 mode_switch,
// 保证连接在发布前已注册。
if err := conn.WriteJSON(wsInbound{Type: "mode_switch", Data: json.RawMessage(`{"mode":"chat"}`)}); err != nil {
t.Fatalf("write mode_switch: %v", err)
}
if got := readWS(t, conn); got.Type != "mode_switch" {
t.Fatalf("first frame type = %q, want mode_switch", got.Type)
}
if err := env.bus.Publish(context.Background(), "ws.graph_update", samplePersonaSnapshot()); err != nil {
t.Fatalf("publish graph: %v", err)
}
raw := readRawWS(t, conn)
var frame struct {
Type string `json:"type"`
Data struct {
Nodes []struct {
ID string `json:"id"`
Props map[string]any `json:"props"`
} `json:"nodes"`
} `json:"data"`
}
if err := json.Unmarshal(raw, &frame); err != nil {
t.Fatalf("decode frame %s: %v", raw, err)
}
if frame.Type != "graph_update" {
t.Fatalf("frame type = %q, want graph_update (frame=%s)", frame.Type, raw)
}
for _, n := range frame.Data.Nodes {
if n.ID != personaBranchNodeID {
continue
}
if got, _ := n.Props["persona"].(string); got != personaBranchRole {
t.Fatalf("线上帧里分支根 props.persona = %q, want %q (frame=%s)", got, personaBranchRole, raw)
}
return
}
t.Fatalf("线上帧里找不到分支根节点 %q: %s", personaBranchNodeID, raw)
}
// personaBranchNodeID / personaBranchRole 是下面 fixture 里分支根
// 的节点 id 与它所扮演的角色 id,供上面的断言引用。
const (
personaBranchNodeID = "span-sub"
personaBranchRole = "yuki"
)
// samplePersonaSnapshot 构建一张带子代理分支的真实生产者侧快照:
// 分支根节点经 AddSpan 折叠(因此走 safeSpanProps 白名单,与生产路径
// 同一道过滤),persona 值就是 orchestration/scheduler.go 会设进
// span prop 的目标角色 id。
func samplePersonaSnapshot() *trace.FlowGraph {
base := time.Date(2026, 10, 3, 21, 0, 0, 0, time.UTC)
g := trace.NewRunGraph("web")
g.Start(1, base)
g.SeedInput("帮我查一下天气")
g.AddSpan(trace.SpanRecord{
ID: personaBranchNodeID,
ParentID: "input",
Name: "subagent.sub-1",
Kind: trace.SpanKindSubagent,
Status: trace.SpanStatusOK,
StartedAt: base.Add(time.Millisecond),
EndedAt: base.Add(9 * time.Millisecond),
Props: map[string]any{"persona": personaBranchRole},
})
g.SeedOutput("今天晴,26 度。")
return g.Snapshot()
}
// sampleFlowSnapshot 构建真实的生产者侧快照(trace.RunGraph,与
// loop 的 FlowPublisher 发布的类型相同),其每个可选线上字段
// 都被填充,使上面的键集断言有意义。