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/trace/graph.go

@@ -0,0 +1,395 @@
+package trace
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+)
+
+// Flow graph wire types (DevDocs/design/19 §1). The JSON field names are
+// camelCase so the frontend's FlowGraph type and parseGraph read them directly.
+// Node status strings mirror the frontend AgentStatus keys so parseGraph and
+// FlowGraphView pass them through unchanged.
+
+// Node status labels kept as named constants so no bare string appears in the
+// mapping code (project rule §10).
+const (
+	// FlowStatusIdle is a node that has not started.
+	FlowStatusIdle = "idle"
+	// FlowStatusRunning is a node whose span is in flight.
+	FlowStatusRunning = "running"
+	// FlowStatusDone is a successfully completed node.
+	FlowStatusDone = "done"
+	// FlowStatusError is a node whose span finished with an error.
+	FlowStatusError = "error"
+)
+
+// maxSummaryRunes bounds how many runes of a user string / tool result are
+// rendered into a node label or prop summary, so sensitive or long content is
+// collapsed to a safe, dashboard-friendly prefix.
+const maxSummaryRunes = 80
+
+// FlowNode is one node in a flow graph. Status/SpanKind mirror the frontier.
+type FlowNode struct {
+	ID        string         `json:"id"`
+	Label     string         `json:"label"`
+	Kind      string         `json:"kind,omitempty"`
+	Status    string         `json:"status,omitempty"`
+	StartedAt time.Time      `json:"startedAt,omitempty"`
+	EndedAt   time.Time      `json:"endedAt,omitempty"`
+	Props     map[string]any `json:"props,omitempty"`
+	Log       []Event        `json:"log,omitempty"`
+}
+
+// FlowEdge is a directed edge between two nodes.
+type FlowEdge struct {
+	From string `json:"from"`
+	To   string `json:"to"`
+}
+
+// FlowGraph is a live, single-round flow graph published as ws.graph_update.
+type FlowGraph struct {
+	ID        string     `json:"id"`
+	Nodes     []FlowNode `json:"nodes"`
+	Edges     []FlowEdge `json:"edges"`
+	SessionID string     `json:"sessionId,omitempty"`
+	StartedAt time.Time  `json:"startedAt,omitempty"`
+	EndedAt   time.Time  `json:"endedAt,omitempty"`
+}
+
+// NodeSpec is the input to RunGraph.Upsert: the full description of a node plus
+// the parent id used to wire its incoming edge.
+type NodeSpec struct {
+	ID        string
+	Label     string
+	Kind      string
+	Status    string
+	StartedAt time.Time
+	EndedAt   time.Time
+	Props     map[string]any
+	Log       []Event
+	ParentID  string
+}
+
+// RunGraph accumulates the spans of one round into a FlowGraph. It is a pure
+// structure: it knows nothing about the bus, sessions or the loop, so it is
+// unit-testable in isolation. A caller serializes access (see loop.FlowPublisher).
+type RunGraph struct {
+	session   string
+	round     int
+	nodes     map[string]*FlowNode
+	order     []string
+	edges     map[string]bool
+	edgeOrder []FlowEdge
+	last      string
+	started   time.Time
+	ended     time.Time
+}
+
+// NewRunGraph allocates an empty graph for one session round.
+func NewRunGraph(session string) *RunGraph {
+	return &RunGraph{
+		session: session,
+		nodes:   make(map[string]*FlowNode),
+		edges:   make(map[string]bool),
+	}
+}
+
+// Start marks the round began at now and resets the node/edge sets so a reused
+// graph starts fresh for a new round.
+func (g *RunGraph) Start(round int, now time.Time) {
+	g.round = round
+	g.started = now
+	g.ended = time.Time{}
+	g.nodes = make(map[string]*FlowNode)
+	g.order = nil
+	g.edges = make(map[string]bool)
+	g.edgeOrder = nil
+	g.last = ""
+}
+
+// Upsert creates or merges a node and wires its incoming edge. The edge source
+// is the node's ParentID when that parent is already a node, otherwise the most
+// recently added node — so a round assembles as a left-to-right trunk even when
+// the parent container (a state_transition span) is omitted from the graph.
+func (g *RunGraph) Upsert(spec NodeSpec) {
+	if spec.ID == "" {
+		return
+	}
+	if existing := g.nodes[spec.ID]; existing != nil {
+		g.merge(existing, spec)
+		return
+	}
+	n := &FlowNode{
+		ID:        spec.ID,
+		Label:     spec.Label,
+		Kind:      spec.Kind,
+		Status:    spec.Status,
+		StartedAt: spec.StartedAt,
+		EndedAt:   spec.EndedAt,
+	}
+	if spec.Props != nil {
+		n.Props = spec.Props
+	}
+	n.Log = append(n.Log, spec.Log...)
+	g.nodes[spec.ID] = n
+	g.order = append(g.order, spec.ID)
+
+	from := g.last
+	if spec.ParentID != "" {
+		if _, ok := g.nodes[spec.ParentID]; ok {
+			from = spec.ParentID
+		}
+	}
+	if from != "" && from != spec.ID {
+		g.addEdge(from, spec.ID)
+	}
+	g.last = spec.ID
+}
+
+// merge updates an existing node in place (a running placeholder being finalized
+// by its finished span), keeping label/kind and appending props/log.
+func (g *RunGraph) merge(existing *FlowNode, spec NodeSpec) {
+	if spec.Label != "" {
+		existing.Label = spec.Label
+	}
+	if spec.Kind != "" {
+		existing.Kind = spec.Kind
+	}
+	if spec.Status != "" {
+		existing.Status = spec.Status
+	}
+	if !spec.EndedAt.IsZero() {
+		existing.EndedAt = spec.EndedAt
+	}
+	if len(spec.Props) > 0 {
+		if existing.Props == nil {
+			existing.Props = make(map[string]any, len(spec.Props))
+		}
+		for k, v := range spec.Props {
+			existing.Props[k] = v
+		}
+	}
+	existing.Log = append(existing.Log, spec.Log...)
+}
+
+// addEdge records a directed edge once.
+func (g *RunGraph) addEdge(from, to string) {
+	key := from + "\x00" + to
+	if g.edges[key] {
+		return
+	}
+	g.edges[key] = true
+	g.edgeOrder = append(g.edgeOrder, FlowEdge{From: from, To: to})
+}
+
+// SeedInput creates the "input" node for the round. It returns the node id so a
+// caller can reference it.
+func (g *RunGraph) SeedInput(text string) string {
+	g.Upsert(NodeSpec{
+		ID:        "input",
+		Label:     truncate(text, maxSummaryRunes),
+		Kind:      "input",
+		Status:    FlowStatusDone,
+		StartedAt: g.started,
+	})
+	return "input"
+}
+
+// SeedOutput creates the "output" node for the round, wired to the last node so
+// the trunk ends at the answer.
+func (g *RunGraph) SeedOutput(text string) string {
+	g.ended = time.Now()
+	g.Upsert(NodeSpec{
+		ID:        "output",
+		Label:     truncate(text, maxSummaryRunes),
+		Kind:      "output",
+		Status:    FlowStatusDone,
+		StartedAt: g.ended,
+		EndedAt:   g.ended,
+	})
+	return "output"
+}
+
+// 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.
+func (g *RunGraph) AddSpan(rec SpanRecord) {
+	kind := kindForSpan(rec.Kind)
+	if kind == "" {
+		return
+	}
+	g.Upsert(NodeSpec{
+		ID:        rec.ID,
+		Label:     labelForSpan(rec),
+		Kind:      kind,
+		Status:    statusForFinished(rec.Status),
+		StartedAt: rec.StartedAt,
+		EndedAt:   rec.EndedAt,
+		Props:     safeSpanProps(rec),
+		Log:       rec.Events,
+		ParentID:  rec.ParentID,
+	})
+}
+
+// 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, matching AddSpan. It reports whether a node was created.
+func (g *RunGraph) AddSpanStart(id, name string, kind SpanKind, parent string, at time.Time) bool {
+	nodeKind := kindForSpan(kind)
+	if nodeKind == "" {
+		return false
+	}
+	g.Upsert(NodeSpec{
+		ID:        id,
+		Label:     labelForStart(name, kind),
+		Kind:      nodeKind,
+		Status:    FlowStatusRunning,
+		StartedAt: at,
+		ParentID:  parent,
+	})
+	return true
+}
+
+// Snapshot returns a copy of the graph safe to encode and publish.
+func (g *RunGraph) Snapshot() *FlowGraph {
+	nodes := make([]FlowNode, 0, len(g.order))
+	for _, id := range g.order {
+		nodes = append(nodes, *g.nodes[id])
+	}
+	return &FlowGraph{
+		ID:        fmt.Sprintf("%s-%d", g.session, g.round),
+		Nodes:     nodes,
+		Edges:     append([]FlowEdge(nil), g.edgeOrder...),
+		SessionID: g.session,
+		StartedAt: g.started,
+		EndedAt:   g.ended,
+	}
+}
+
+// kindForSpan maps a span kind to a flow node kind. state_transition is the step
+// container and maps to "" so it is never rendered as a node.
+func kindForSpan(k SpanKind) string {
+	switch k {
+	case SpanKindLLM:
+		return "llm"
+	case SpanKindTool:
+		return "tool"
+	case SpanKindSubagent:
+		return "subagent"
+	case SpanKindMemory:
+		return "memory"
+	case SpanKindGuardrail:
+		return "guardrail"
+	case SpanKindOrchestration:
+		return "orchestration"
+	default:
+		return ""
+	}
+}
+
+// labelForSpan renders a node label from a finished span.
+func labelForSpan(rec SpanRecord) string {
+	if kind := kindForSpan(rec.Kind); kind == "tool" {
+		return strings.TrimPrefix(rec.Name, "tool.")
+	}
+	if rec.Kind == SpanKindLLM {
+		return "思考"
+	}
+	if rec.Name != "" {
+		return rec.Name
+	}
+	return string(rec.Kind)
+}
+
+// labelForStart renders a node label from a just-started span.
+func labelForStart(name string, kind SpanKind) string {
+	if kind == SpanKindLLM {
+		return "思考"
+	}
+	if kind == SpanKindTool {
+		return strings.TrimPrefix(name, "tool.")
+	}
+	if name != "" {
+		return name
+	}
+	return string(kind)
+}
+
+// safeSpanProps carries only a whitelist of span props to the frontend, plus a
+// desensitized tool result summary. It never forwards raw arguments or secrets,
+// and truncates string text so long content cannot leak a full sensitive payload.
+func safeSpanProps(rec SpanRecord) map[string]any {
+	var props map[string]any
+	for _, k := range safePropKeys {
+		v, ok := rec.Props[k]
+		if !ok {
+			continue
+		}
+		if props == nil {
+			props = make(map[string]any)
+		}
+		props[k] = redactValue(v)
+	}
+	if rec.Kind == SpanKindTool {
+		if v, ok := rec.Props["result"]; ok {
+			if props == nil {
+				props = make(map[string]any)
+			}
+			props["result_summary"] = truncate(summarize(v), maxSummaryRunes)
+		}
+	}
+	return props
+}
+
+// redactValue shortens string props so a long error/step value cannot leak
+// sensitive content through the dashboard; non-string values pass through.
+func redactValue(v any) any {
+	if s, ok := v.(string); ok {
+		return truncate(s, maxSummaryRunes)
+	}
+	return v
+}
+
+// safePropKeys are the span prop keys forwarded to a node's props.
+var safePropKeys = []string{"stop_reason", "step", "error", "error_kind", "tool"}
+
+// statusForFinished maps a span terminal status to a node status.
+func statusForFinished(s SpanStatus) string {
+	switch s {
+	case SpanStatusError:
+		return FlowStatusError
+	case SpanStatusOK:
+		return FlowStatusDone
+	default:
+		return FlowStatusIdle
+	}
+}
+
+// summarize renders an arbitrary value as a short text string for a prop summary.
+func summarize(v any) string {
+	switch x := v.(type) {
+	case nil:
+		return ""
+	case string:
+		return x
+	default:
+		b, err := json.Marshal(x)
+		if err != nil {
+			return fmt.Sprintf("%v", x)
+		}
+		return string(b)
+	}
+}
+
+// truncate cuts s to at most max runes, appending an ellipsis when it overflows.
+func truncate(s string, max int) string {
+	if max <= 0 {
+		return s
+	}
+	r := []rune(s)
+	if len(r) <= max {
+		return s
+	}
+	return string(r[:max]) + "…"
+}

internal/runtime/trace/graph_test.go

@@ -0,0 +1,161 @@
+package trace
+
+import (
+	"testing"
+	"time"
+)
+
+// spanRec builds a finished SpanRecord with the essential fields for the builder.
+func spanRec(id, parent, name string, kind SpanKind, status SpanStatus, props map[string]any) SpanRecord {
+	now := time.Now()
+	return SpanRecord{
+		ID:        id,
+		ParentID:  parent,
+		Name:      name,
+		Kind:      kind,
+		Status:    status,
+		StartedAt: now.Add(-time.Second),
+		EndedAt:   now,
+		Duration:  time.Second,
+		Props:     props,
+	}
+}
+
+// graphFor builds a graph from the given finished spans plus input/output text.
+func graphFor(spans []SpanRecord, input, output string) *FlowGraph {
+	g := NewRunGraph("web")
+	g.Start(1, time.Now())
+	g.SeedInput(input)
+	for _, s := range spans {
+		g.AddSpan(s)
+	}
+	g.SeedOutput(output)
+	return g.Snapshot()
+}
+
+func nodeByID(g *FlowGraph, id string) FlowNode {
+	for _, n := range g.Nodes {
+		if n.ID == id {
+			return n
+		}
+	}
+	return FlowNode{}
+}
+
+func hasEdge(g *FlowGraph, from, to string) bool {
+	for _, e := range g.Edges {
+		if e.From == from && e.To == to {
+			return true
+		}
+	}
+	return false
+}
+
+// TestBuildFlowGraphTrunk asserts the single-round main trunk assembles as
+// input→llm→tool→output with final "done" status on every node.
+func TestBuildFlowGraphTrunk(t *testing.T) {
+	llm := spanRec("s1", "step1", "llm.call", SpanKindLLM, SpanStatusOK,
+		map[string]any{"stop_reason": "tool_calls"})
+	tool := spanRec("s2", "step1", "tool.echo", SpanKindTool, SpanStatusOK,
+		map[string]any{"result": "hello world"})
+
+	g := graphFor([]SpanRecord{llm, tool}, "你好", "你好呀")
+
+	if g.SessionID != "web" {
+		t.Fatalf("SessionID = %q, want web", g.SessionID)
+	}
+	if len(g.Nodes) != 4 {
+		t.Fatalf("Nodes = %d, want 4 (input/llm/tool/output) -> %+v", len(g.Nodes), g.Nodes)
+	}
+	if nodeByID(g, "input").Kind != "input" {
+		t.Fatalf("input node kind = %q", nodeByID(g, "input").Kind)
+	}
+	if nodeByID(g, "s1").Kind != "llm" || nodeByID(g, "s1").Status != FlowStatusDone {
+		t.Fatalf("llm node was not folded: %+v", nodeByID(g, "s1"))
+	}
+	if nodeByID(g, "s2").Kind != "tool" || nodeByID(g, "s2").Status != FlowStatusDone {
+		t.Fatalf("tool node was not folded: %+v", nodeByID(g, "s2"))
+	}
+	if !hasEdge(g, "input", "s1") {
+		t.Fatalf("expected edge input->s1, got %+v", g.Edges)
+	}
+	if !hasEdge(g, "s1", "s2") {
+		t.Fatalf("expected edge s1->s2, got %+v", g.Edges)
+	}
+	if !hasEdge(g, "s2", "output") {
+		t.Fatalf("expected edge s2->output, got %+v", g.Edges)
+	}
+}
+
+// TestBuildFlowGraphErrorTool asserts a failed tool span finalizes the node as
+// "error" while the rest of the trunk stays built.
+func TestBuildFlowGraphErrorTool(t *testing.T) {
+	llm := spanRec("s1", "step1", "llm.call", SpanKindLLM, SpanStatusOK, nil)
+	tool := spanRec("s2", "step1", "tool.bad", SpanKindTool, SpanStatusError,
+		map[string]any{"error": "boom", "error_kind": "execution"})
+
+	g := graphFor([]SpanRecord{llm, tool}, "q", "")
+	if got := nodeByID(g, "s2").Status; got != FlowStatusError {
+		t.Fatalf("tool status = %q, want %q", got, FlowStatusError)
+	}
+	if got := nodeByID(g, "s2").Kind; got != "tool" {
+		t.Fatalf("tool kind = %q", got)
+	}
+	if nodeByID(g, "s2").Props["error_kind"] != "execution" {
+		t.Fatalf("tool props missing error_kind: %+v", nodeByID(g, "s2").Props)
+	}
+	if !hasEdge(g, "s1", "s2") {
+		t.Fatalf("expected edge s1->s2")
+	}
+}
+
+// TestBuildFlowGraphSkipsStateTransition asserts the step container span is not
+// rendered as a node and does not break the chain.
+func TestBuildFlowGraphSkipsStateTransition(t *testing.T) {
+	step := spanRec("step1", "", "loop.step", SpanKindStateTransition, SpanStatusOK, nil)
+	llm := spanRec("s1", "step1", "llm.call", SpanKindLLM, SpanStatusOK, nil)
+
+	g := graphFor([]SpanRecord{step, llm}, "q", "a")
+	for _, n := range g.Nodes {
+		if n.ID == "step1" {
+			t.Fatalf("state_transition span leaked as a node: %+v", n)
+		}
+	}
+	if !hasEdge(g, "input", "s1") {
+		t.Fatalf("expected edge input->s1 (through the skipped container), got %+v", g.Edges)
+	}
+}
+
+// TestBuildFlowGraphRunningAndDone asserts a node created at start (via
+// AddSpanStart) is "running", then becomes "done" once its span finishes.
+func TestBuildFlowGraphRunningAndDone(t *testing.T) {
+	g := NewRunGraph("web")
+	g.Start(1, time.Now())
+	g.SeedInput("q")
+
+	g.AddSpanStart("s1", "llm.call", SpanKindLLM, "", time.Now())
+	if got := nodeByID(g.Snapshot(), "s1").Status; got != FlowStatusRunning {
+		t.Fatalf("start status = %q, want running", got)
+	}
+
+	g.AddSpan(spanRec("s1", "", "llm.call", SpanKindLLM, SpanStatusOK, nil))
+	if got := nodeByID(g.Snapshot(), "s1").Status; got != FlowStatusDone {
+		t.Fatalf("finished status = %q, want done", got)
+	}
+}
+
+// TestBuildFlowGraphParentEdgePrioritizesParent asserts that when a node's parent
+// is already a node (e.g. a nested subagent span), the edge wires to that parent
+// instead of the linear chain.
+func TestBuildFlowGraphParentEdgePrioritizesParent(t *testing.T) {
+	parent := spanRec("sub", "", "subagent.foo", SpanKindSubagent, SpanStatusOK, nil)
+	child := spanRec("nested", "sub", "llm.call", SpanKindLLM, SpanStatusOK, nil)
+
+	g := graphFor([]SpanRecord{parent, child}, "q", "a")
+	if !hasEdge(g, "sub", "nested") {
+		t.Fatalf("expected edge sub->nested (parent priority), got %+v", g.Edges)
+	}
+	if nodeByID(g, "sub").Kind != "subagent" {
+		t.Fatalf("subagent kind = %q", nodeByID(g, "sub").Kind)
+	}
+}

internal/runtime/trace/span.go

@@ -158,6 +158,16 @@ func (s *Span) recordLocked() SpanRecord {
 	return rec
 }
 
+// Snapshot returns an immutable copy of a finished span as a SpanRecord. It is
+// only safe to call after Finish returns (a closed span is immutable), and it
+// lets a consumer read the span's final state without holding its lock. Calling
+// it on a non-finished span returns a record with a zero Status/EndedAt.
+func (s *Span) Snapshot() SpanRecord {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.recordLocked()
+}
+
 // SpanRecord is an immutable, lock-free snapshot of a completed span, produced
 // by Finish and passed to a Writer for persistence. It is safe to copy.
 type SpanRecord struct {