feat(flow): 实时全链路流程可视化 P1——trace→graph_update→前端全链路流程页(design/19)

后端: trace/graph.go(RunGraph 图构建器,kind/status 映射,父子优先连线,脱敏白名单+截断);
       loop/flow.go(FlowPublisher 按会话增量发布 ws.graph_update,仅主人web会话); loop span
       start/finish 折入图; run.go StartRound/EndRound; wire.go 组装+注入.
前端: Flow.tsx(全链路流程页:FlowGraphView+会话/节点/开始/耗时卡片+状态计数+节点点开日志);
       FlowGraph 组件加 onNodeClick; types/wsParse 扩展; router/sections/AdminApp 注册 flow;
       api-client.md §3.5 graph_update 契约.
验证: 后端 build/vet/test 全绿+flow_test.go 集成(span→graph→ws.graph_update主干); 前端 build 绿.
红线: 单二进制零新依赖; 工具参数/结果脱敏; 仅主人web会话; 身份靠actor元数据; 只读不虚构.
P2(并行子代理分支/泳道/节点实时日志)后置.

internal/runtime/loop/flow.go

@@ -0,0 +1,143 @@
+package loop
+
+import (
+	"sync"
+	"time"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/trace"
+)
+
+// graphUpdateSubject is the bus subject the FlowPublisher publishes each round's
+// live flow graph on. The gateway hub subscribes to ws.> and relays it as the
+// WS event type graph_update (design/19 §1).
+const graphUpdateSubject = "ws.graph_update"
+
+// allowedSessions is the predicate signature used to gate which sessions publish
+// flow graphs (the owner's web sessions), so IM/stranger/sub-agent turns never
+// leak into the admin panel. A nil predicate allows every session.
+type allowedSessions func(sessionID string) bool
+
+// FlowPublisher accumulates a per-session flow graph from the loop's trace spans
+// and publishes ws.graph_update as each span starts/finishes, giving the frontend
+// a realtime input→think→tool→output graph (design/19 §1). It is nil-tolerant
+// (a nil publisher is a no-op) and safe for concurrent use; session graphs are
+// serialized under one mutex because parallel tool spans finish concurrently.
+type FlowPublisher struct {
+	mu     sync.Mutex
+	publish func(subject string, payload any)
+	allow  allowedSessions
+	graphs map[string]*trace.RunGraph
+	rounds map[string]int
+}
+
+// NewFlowPublisher builds a FlowPublisher. publish, when non-nil, is called with
+// graphUpdateSubject and a *trace.FlowGraph snapshot on every span transition.
+// allow, when non-nil, gates which session ids are published (returning false
+// drops the session entirely). Both may be nil (a nil publish is a no-op).
+func NewFlowPublisher(publish func(subject string, payload any), allow func(sessionID string) bool) *FlowPublisher {
+	return &FlowPublisher{
+		publish: publish,
+		allow:   allow,
+		graphs:  make(map[string]*trace.RunGraph),
+		rounds:  make(map[string]int),
+	}
+}
+
+// StartRound begins a fresh graph for sessionID, seeding an input node from the
+// user text and publishing the initial frame. It resets the session's previous
+// round, so each user turn is its own graph.
+func (p *FlowPublisher) StartRound(sessionID, inputText string) {
+	if sessionID == "" || !p.allowed(sessionID) {
+		return
+	}
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	round := p.rounds[sessionID] + 1
+	g := trace.NewRunGraph(sessionID)
+	g.Start(round, time.Now())
+	g.SeedInput(inputText)
+	p.graphs[sessionID] = g
+	p.rounds[sessionID] = round
+	p.publishLocked(g)
+}
+
+// EndRound finalizes the round by seeding an output node from the reply and
+// publishing the final frame. It keeps the graph around so a client that misses
+// the final frame can replay the last snapshot on refresh.
+func (p *FlowPublisher) EndRound(sessionID, outputText string) {
+	if sessionID == "" || !p.allowed(sessionID) {
+		return
+	}
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	g := p.graphs[sessionID]
+	if g == nil {
+		return
+	}
+	g.SeedOutput(outputText)
+	p.publishLocked(g)
+}
+
+// SpanStarted records a running placeholder node for a span that just began.
+// State-transition spans are omitted by the graph builder.
+func (p *FlowPublisher) SpanStarted(sessionID string, sp *trace.Span) {
+	if sp == nil || sessionID == "" || !p.allowed(sessionID) {
+		return
+	}
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	g := p.graphs[sessionID]
+	if g == nil {
+		return
+	}
+	if g.AddSpanStart(sp.ID, sp.Name, sp.Kind, sp.ParentID, sp.StartedAt) {
+		p.publishLocked(g)
+	}
+}
+
+// SpanFinished folds a just-finished span into the session graph as a final node
+// (status done/error) and publishes. It must be called after the span's Finish.
+func (p *FlowPublisher) SpanFinished(sessionID string, sp *trace.Span) {
+	if sp == nil || sessionID == "" || !p.allowed(sessionID) {
+		return
+	}
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	g := p.graphs[sessionID]
+	if g == nil {
+		return
+	}
+	g.AddSpan(sp.Snapshot())
+	p.publishLocked(g)
+}
+
+// publishLocked publishes a snapshot of g. Callers must hold p.mu.
+func (p *FlowPublisher) publishLocked(g *trace.RunGraph) {
+	if p.publish == nil {
+		return
+	}
+	p.publish(graphUpdateSubject, g.Snapshot())
+}
+
+// allowed reports whether a session's graphs should be published.
+func (p *FlowPublisher) allowed(sessionID string) bool {
+	if p.allow == nil {
+		return true
+	}
+	return p.allow(sessionID)
+}
+
+// lastUserText returns the text of the newest user message in messages, used to
+// label the round's input node. It returns "" when no user text is present.
+func lastUserText(messages []model.Message) string {
+	for i := len(messages) - 1; i >= 0; i-- {
+		if messages[i].Role != model.RoleUser {
+			continue
+		}
+		if t := messageText(messages[i]); t != "" {
+			return t
+		}
+	}
+	return ""
+}

internal/runtime/loop/flow_test.go

@@ -0,0 +1,118 @@
+package loop
+
+import (
+	"context"
+	"sync"
+	"testing"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/trace"
+)
+
+// TestRun_PublishesFlowGraph_Trunk wires a FlowPublisher with a capturing publish
+// function and a live tracer, runs one tool round and asserts ws.graph_update was
+// published with the input→llm→tool→output trunk (design/19 §1 P1).
+func TestRun_PublishesFlowGraph_Trunk(t *testing.T) {
+	var mu sync.Mutex
+	var seen []*trace.FlowGraph
+	flow := NewFlowPublisher(func(subject string, payload any) {
+		if subject != graphUpdateSubject {
+			return
+		}
+		if g, ok := payload.(*trace.FlowGraph); ok {
+			mu.Lock()
+			seen = append(seen, g)
+			mu.Unlock()
+		}
+	}, func(string) bool { return true })
+
+	call := `{"tool_calls":[{"name":"echo","args":{"q":"hi"}}]}`
+	ad := &mockAdapter{chat: []mgResp{
+		{resp: model.Response{Content: call}},
+		{resp: model.Response{Content: "Echoed!"}},
+	}}
+	td := dispatcherWith(t, &mockTool{name: "echo", result: "hi"})
+	a := newTestAgent(t, ad, td)
+	l := New(Options{Agent: a, MaxRounds: 8, Flow: flow, Tracer: trace.New(nil)})
+
+	res, err := l.Run(context.Background(), "web", []model.Message{model.TextMessage(model.RoleUser, "echo this")})
+	if err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if res.Text != "Echoed!" {
+		t.Fatalf("Text = %q, want Echoed!", res.Text)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+	if len(seen) == 0 {
+		t.Fatal("no ws.graph_update published")
+	}
+	last := seen[len(seen)-1]
+	if last.SessionID != "web" {
+		t.Fatalf("SessionID = %q, want web", last.SessionID)
+	}
+
+	kinds := make(map[string]string)
+	for _, n := range last.Nodes {
+		kinds[n.ID] = n.Kind
+	}
+	nodeKind := map[string]bool{"input": false, "llm": false, "tool": false, "output": false}
+	inputID, outputID := "", ""
+	for _, n := range last.Nodes {
+		if n.Kind == "input" {
+			inputID = n.ID
+		}
+		if n.Kind == "output" {
+			outputID = n.ID
+		}
+		if _, ok := nodeKind[n.Kind]; ok {
+			nodeKind[n.Kind] = true
+		}
+	}
+	for _, want := range []string{"input", "llm", "tool", "output"} {
+		if !nodeKind[want] {
+			t.Fatalf("trunk incomplete: no %q node; nodes=%+v", want, last.Nodes)
+		}
+	}
+
+	// Walk the chain from the input node; it must reach output through llm/tool.
+	chain := []string{}
+	cur := inputID
+	for cur != "" {
+		chain = append(chain, kinds[cur])
+		if cur == outputID {
+			break
+		}
+		cur = nextNode(last, cur)
+	}
+	hasLLM, hasTool := false, false
+	for _, k := range chain {
+		if k == "llm" {
+			hasLLM = true
+		}
+		if k == "tool" {
+			hasTool = true
+		}
+	}
+	if chain[len(chain)-1] != "output" || !hasLLM || !hasTool {
+		t.Fatalf("trunk chain broken: %v", chain)
+	}
+	// The final frame should show the tool completed (done), not still running.
+	for _, n := range last.Nodes {
+		if n.Kind == "tool" && n.Status != trace.FlowStatusDone {
+			t.Fatalf("tool status = %q, want done", n.Status)
+		}
+	}
+}
+
+// nextNode returns the node that cur points to, or "" when cur has no outgoing
+// edge (the terminal output node). A linear chain has at most one successor.
+func nextNode(g *trace.FlowGraph, cur string) string {
+	for _, e := range g.Edges {
+		if e.From == cur {
+			return e.To
+		}
+	}
+	return ""
+}

internal/runtime/loop/loop.go

@@ -90,6 +90,7 @@ type Loop struct {
 	extractor       memory.Extractor
 	checkpoint      checkpointStore
 	tracer          *trace.Tracer
+	flow            *FlowPublisher
 	guards          *guardrail.Pipeline
 	personaID       string
 	timeLocation    *time.Location
@@ -141,6 +142,7 @@ func New(opts Options) *Loop {
 		extractor:        opts.Extractor,
 		checkpoint:       opts.Checkpoint,
 		tracer:           opts.Tracer,
+		flow:             opts.Flow,
 		guards:           opts.Guards,
 		personaID:        opts.PersonaID,
 		timeLocation:     timeLocation,

internal/runtime/loop/options.go

@@ -60,6 +60,10 @@ type Options struct {
 	Checkpoint checkpointStore
 	// Tracer emits a structured span for every step, LLM call and tool call.
 	Tracer *trace.Tracer
+	// Flow, when non-nil, accumulates the run's trace spans into a per-session
+	// flow graph and publishes ws.graph_update on each span transition (design/19
+	// §1). Nil disables the realtime flow visualization.
+	Flow *FlowPublisher
 	// Guards validates request/response payloads on the streaming path, where
 	// RunStep is bypassed. On the non-streaming path the agent runs its own
 	// guardrails inside RunStep.

internal/runtime/loop/run.go

@@ -49,6 +49,10 @@ func (l *Loop) Run(ctx context.Context, sessionID string, messages []model.Messa
 	msgs = l.resolveImages(ctx, msgs)
 	toolState := &toolLoopState{prevFP: make(map[string]bool)}
 	res := &Result{}
+	if l.flow != nil {
+		l.flow.StartRound(sessionID, lastUserText(msgs))
+		defer func() { l.flow.EndRound(sessionID, res.Text) }()
+	}
 	for step := startStep; step <= l.maxRounds; step++ {
 		if err := ctx.Err(); err != nil {
 			return nil, fmt.Errorf("loop: run: step %d: %w", step, err)

internal/runtime/loop/trace.go

@@ -8,20 +8,36 @@ import (
 
 // span starts a named span of the given kind when a Tracer is configured, else
 // returns a nil no-op span. The returned context carries the span as the current
-// one so nested spans chain as children.
+// one so nested spans chain as children. When a FlowPublisher is configured the
+// span's session (threaded via ctx) is stamped as a prop and a running placeholder
+// node is published immediately, so the flow graph shows work in flight.
 func (l *Loop) span(ctx context.Context, name string, kind trace.SpanKind) (context.Context, *trace.Span) {
 	if l.tracer == nil {
 		return ctx, nil
 	}
-	return l.tracer.StartSpan(ctx, name, kind)
+	sctx, sp := l.tracer.StartSpan(ctx, name, kind)
+	if sid := loopSession(ctx); sid != "" {
+		_ = sp.SetProp("session", sid)
+		if l.flow != nil {
+			l.flow.SpanStarted(sid, sp)
+		}
+	}
+	return sctx, sp
 }
 
-// finishSpan closes a span with the given status, ignoring a nil span.
+// finishSpan closes a span with the given status, ignoring a nil span. After the
+// span closes (immutable) the finished record is folded into the flow graph and
+// published, flipping the node to its final status.
 func (l *Loop) finishSpan(sp *trace.Span, status trace.SpanStatus) {
 	if sp == nil {
 		return
 	}
 	sp.Finish(status)
+	if l.flow != nil {
+		if sid, ok := sp.Props["session"].(string); ok && sid != "" {
+			l.flow.SpanFinished(sid, sp)
+		}
+	}
 }
 
 // spanProp attaches a structured property to a span, ignoring a nil span and any