@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/multi-task-flow/web/graph-projection.ts

@@ -0,0 +1,454 @@
+import type { Node, Task, View } from "./model";
+import { stateIconName, stateLabel, type StateIconName } from "./labels";
+
+export const HIDDEN_BOUNDARY_KINDS = new Set(["main_start", "main_end", "group_start", "group_end"]);
+
+export const GRAPH_LABEL_LIMITS = {
+  group: { lines: 2, columns: 14 },
+  task: { lines: 3, columns: 10 },
+  milestone: { lines: 2, columns: 9 },
+  other: { lines: 3, columns: 10 },
+} as const;
+
+export const GRAPH_SHAPES = {
+  group: "round-rectangle",
+  contribution: "round-rectangle",
+  release: "hexagon",
+  deployment: "rhomboid",
+  verification: "ellipse",
+  coordination: "octagon",
+  milestone: "diamond",
+} as const;
+
+export const MAX_GRAPH_PATHS = 512;
+
+export type GraphNodeKind = "group" | "task" | "milestone" | "other";
+
+export type GraphProjectionNode = {
+  id: string;
+  parentId: string | null;
+  nodeKind: GraphNodeKind;
+  sourceNodeId: string | null;
+  refId: string | null;
+  groupId: string | null;
+  plannedGroupId: string | null;
+  taskKind: string | null;
+  state: string | null;
+  stateLabel: string | null;
+  stateIcon: StateIconName | null;
+  title: string;
+  graphLabel: string;
+  fullLabel: string;
+};
+
+export type GraphDependencyPath = {
+  requires: string[];
+  sourceEdgeIds: string[];
+  boundaryNodeIds: string[];
+  truncated?: boolean;
+};
+
+export type GraphProjectionEdge = {
+  id: string;
+  source: string;
+  target: string;
+  paths: GraphDependencyPath[];
+  crossGroup: "yes" | "no";
+};
+
+export type GraphBoundaryDependency = {
+  direction: "incoming" | "outgoing";
+  nodeId: string;
+  paths: GraphDependencyPath[];
+};
+
+export type GraphProjection = {
+  nodes: GraphProjectionNode[];
+  edges: GraphProjectionEdge[];
+  boundaryDependencies: GraphBoundaryDependency[];
+  warnings: string[];
+};
+
+export function fitGraphLabel(value: string, limit: { lines: number; columns: number }): string {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  const capacity = limit.lines * limit.columns;
+  if (!normalized || capacity <= 0) return "";
+  const characters = Array.from(normalized);
+  const clipped = characters.length > capacity;
+  const visible = characters.slice(0, clipped ? Math.max(0, capacity - 1) : capacity);
+  const lines: string[] = [];
+  for (let index = 0; index < visible.length; index += limit.columns) lines.push(visible.slice(index, index + limit.columns).join(""));
+  if (clipped) {
+    if (!lines.length) lines.push("…");
+    else lines[lines.length - 1] = `${lines[lines.length - 1]!.slice(0, Math.max(0, limit.columns - 1))}…`;
+  }
+  return lines.join("\n");
+}
+
+function taskForNode(node: Node, tasks: Map<string, Task>): Task | null {
+  return node.ref_id ? tasks.get(node.ref_id) ?? null : null;
+}
+
+function canonicalTaskKind(kind: string | null): string | null {
+  if (kind === "development") return "contribution";
+  if (kind === "other") return "coordination";
+  return kind;
+}
+
+function currentGroupId(node: Node, task: Task | null): string | null {
+  if (node.kind === "task" && task) return task.group_id || node.group_id || node.planned_group_id;
+  return node.group_id ?? node.planned_group_id;
+}
+
+function plannedGroupId(node: Node): string | null {
+  return node.planned_group_id ?? node.group_id;
+}
+
+function projectionNodeKind(node: Node): GraphNodeKind {
+  if (node.kind === "task") return "task";
+  if (node.kind === "milestone") return "milestone";
+  return "other";
+}
+
+function labelLimit(kind: GraphNodeKind): { lines: number; columns: number } {
+  return kind === "group" ? GRAPH_LABEL_LIMITS.group : kind === "task" ? GRAPH_LABEL_LIMITS.task : kind === "milestone" ? GRAPH_LABEL_LIMITS.milestone : GRAPH_LABEL_LIMITS.other;
+}
+
+function displayEdgeKey(source: string, target: string): string {
+  return `${source}\u0000${target}`;
+}
+
+function pathKey(path: GraphDependencyPath): string {
+  return JSON.stringify([path.requires, path.sourceEdgeIds, path.boundaryNodeIds, path.truncated ?? false]);
+}
+
+function appendPath(path: GraphDependencyPath, edge: View["edges"][number], boundaryNodeId?: string): GraphDependencyPath {
+  return {
+    requires: edge.requires ? [...path.requires, edge.requires] : [...path.requires],
+    sourceEdgeIds: [...path.sourceEdgeIds, edge.id],
+    boundaryNodeIds: boundaryNodeId ? [...path.boundaryNodeIds, boundaryNodeId] : [...path.boundaryNodeIds],
+  };
+}
+
+function addPath(target: GraphDependencyPath[], path: GraphDependencyPath): boolean {
+  if (target.some((item) => pathKey(item) === pathKey(path))) return false;
+  target.push(path);
+  return true;
+}
+
+function uniqueId(candidate: string, usedIds: Set<string>): string {
+  let id = candidate;
+  let suffix = 2;
+  while (usedIds.has(id)) id = `${candidate}:${suffix++}`;
+  usedIds.add(id);
+  return id;
+}
+
+type WalkState = { nodeId: string; path: GraphDependencyPath; visited: Set<string> };
+
+type DisplayDependencyOptions = {
+  boundaryEndpointIds?: ReadonlyMap<string, string>;
+  syntheticOutgoing?: ReadonlyMap<string, View["edges"]>;
+  syntheticBoundaryStarts?: ReadonlyMap<string, string>;
+};
+
+function walkHiddenPaths(
+  initial: WalkState,
+  outgoing: Map<string, View["edges"]>,
+  visibleNodeIds: Set<string>,
+  nodeById: Map<string, Node>,
+  onVisible: (nodeId: string, path: GraphDependencyPath) => void,
+  onTerminal: (path: GraphDependencyPath) => void,
+  boundaryEndpointIds: ReadonlyMap<string, string> = new Map(),
+): boolean {
+  const queue: WalkState[] = [initial];
+  let processed = 0;
+  let emitted = 0;
+  let overflow = false;
+  while (queue.length) {
+    if (processed >= MAX_GRAPH_PATHS) {
+      overflow = true;
+      break;
+    }
+    const current = queue.shift()!;
+    processed += 1;
+    let advanced = false;
+    let blocked = false;
+    for (const edge of outgoing.get(current.nodeId) ?? []) {
+      const visibleTargetId = visibleNodeIds.has(edge.to_node_id)
+        ? edge.to_node_id
+        : boundaryEndpointIds.get(edge.to_node_id);
+      if (visibleTargetId !== undefined) {
+        if (visibleTargetId === current.nodeId || visibleTargetId === initial.nodeId) {
+          blocked = true;
+          continue;
+        }
+        if (emitted >= MAX_GRAPH_PATHS) {
+          overflow = true;
+          break;
+        }
+        emitted += 1;
+        advanced = true;
+        onVisible(visibleTargetId, appendPath(current.path, edge, visibleTargetId === edge.to_node_id ? undefined : edge.to_node_id));
+        continue;
+      }
+      const hiddenTarget = nodeById.get(edge.to_node_id);
+      if (!hiddenTarget || !HIDDEN_BOUNDARY_KINDS.has(hiddenTarget.kind) || current.visited.has(edge.to_node_id)) {
+        blocked = true;
+        continue;
+      }
+      advanced = true;
+      queue.push({ nodeId: edge.to_node_id, path: appendPath(current.path, edge, edge.to_node_id), visited: new Set([...current.visited, edge.to_node_id]) });
+    }
+    if (overflow) break;
+    if (!advanced && !blocked && current.path.boundaryNodeIds.length) onTerminal(current.path);
+  }
+  return overflow;
+}
+
+function findVisibleWitnesses(initial: WalkState, outgoing: Map<string, View["edges"]>, visibleNodeIds: Set<string>, nodeById: Map<string, Node>, boundaryEndpointIds: ReadonlyMap<string, string> = new Map()): Map<string, GraphDependencyPath> {
+  const queue: WalkState[] = [initial];
+  const visited = new Set(initial.visited);
+  const witnesses = new Map<string, GraphDependencyPath>();
+  let processed = 0;
+  while (queue.length && processed < MAX_GRAPH_PATHS && witnesses.size < MAX_GRAPH_PATHS) {
+    const current = queue.shift()!;
+    processed += 1;
+    for (const edge of outgoing.get(current.nodeId) ?? []) {
+      if (witnesses.size >= MAX_GRAPH_PATHS) break;
+      const visibleTargetId = visibleNodeIds.has(edge.to_node_id)
+        ? edge.to_node_id
+        : boundaryEndpointIds.get(edge.to_node_id);
+      if (visibleTargetId !== undefined) {
+        if (visibleTargetId !== initial.nodeId && !witnesses.has(visibleTargetId)) witnesses.set(visibleTargetId, appendPath(current.path, edge, visibleTargetId === edge.to_node_id ? undefined : edge.to_node_id));
+        continue;
+      }
+      const hiddenTarget = nodeById.get(edge.to_node_id);
+      if (!hiddenTarget || !HIDDEN_BOUNDARY_KINDS.has(hiddenTarget.kind) || visited.has(edge.to_node_id)) continue;
+      visited.add(edge.to_node_id);
+      if (queue.length < MAX_GRAPH_PATHS) queue.push({ nodeId: edge.to_node_id, path: appendPath(current.path, edge, edge.to_node_id), visited: new Set([edge.to_node_id]) });
+    }
+  }
+  return witnesses;
+}
+
+function findTerminalWitnesses(initial: WalkState, outgoing: Map<string, View["edges"]>, visibleNodeIds: Set<string>, nodeById: Map<string, Node>, boundaryEndpointIds: ReadonlyMap<string, string> = new Map()): GraphDependencyPath[] {
+  const queue: WalkState[] = [initial];
+  const visited = new Set(initial.visited);
+  const terminals: GraphDependencyPath[] = [];
+  let processed = 0;
+  while (queue.length && processed < MAX_GRAPH_PATHS && terminals.length < MAX_GRAPH_PATHS) {
+    const current = queue.shift()!;
+    processed += 1;
+    let advanced = false;
+    let blocked = false;
+    for (const edge of outgoing.get(current.nodeId) ?? []) {
+      if (visibleNodeIds.has(edge.to_node_id) || boundaryEndpointIds.has(edge.to_node_id)) {
+        blocked = true;
+        continue;
+      }
+      const hiddenTarget = nodeById.get(edge.to_node_id);
+      if (!hiddenTarget || !HIDDEN_BOUNDARY_KINDS.has(hiddenTarget.kind) || visited.has(edge.to_node_id)) {
+        blocked = true;
+        continue;
+      }
+      advanced = true;
+      visited.add(edge.to_node_id);
+      if (queue.length < MAX_GRAPH_PATHS) queue.push({ nodeId: edge.to_node_id, path: appendPath(current.path, edge, edge.to_node_id), visited: new Set([edge.to_node_id]) });
+    }
+    if (!advanced && !blocked && current.path.boundaryNodeIds.length) terminals.push(current.path);
+  }
+  return terminals;
+}
+
+function makeDisplayDependencies(view: View, visibleNodes: Node[], visibleNodeIds: Set<string>, nodeById: Map<string, Node>, tasks: Map<string, Task>, usedIds: Set<string>, options: DisplayDependencyOptions = {}): { edges: GraphProjectionEdge[]; boundaryDependencies: GraphBoundaryDependency[]; warnings: string[] } {
+  const outgoing = new Map<string, View["edges"]>();
+  for (const edge of view.edges) outgoing.set(edge.from_node_id, [...(outgoing.get(edge.from_node_id) ?? []), edge]);
+  for (const [sourceId, edges] of options.syntheticOutgoing ?? []) outgoing.set(sourceId, edges);
+  const collapsed = new Map<string, GraphProjectionEdge>();
+  const edgeIds = new Map<string, string>();
+  const boundary = new Map<string, GraphBoundaryDependency>();
+  const warnings: string[] = [];
+  const warn = (scope: string): void => {
+    const message = `图投影从 ${scope} 展开的路径超过 ${MAX_GRAPH_PATHS} 条，部分依赖路径未展开。`;
+    if (!warnings.includes(message)) warnings.push(message);
+  };
+
+  const addBoundary = (direction: "incoming" | "outgoing", nodeId: string, path: GraphDependencyPath): void => {
+    const key = `${direction}\u0000${nodeId}`;
+    const previous = boundary.get(key);
+    if (previous) addPath(previous.paths, path);
+    else boundary.set(key, { direction, nodeId, paths: [path] });
+  };
+
+  for (const source of visibleNodes) {
+    const syntheticBoundaryStart = options.syntheticBoundaryStarts?.get(source.id);
+    const initial: WalkState = { nodeId: source.id, path: { requires: [], sourceEdgeIds: [], boundaryNodeIds: syntheticBoundaryStart ? [syntheticBoundaryStart] : [] }, visited: new Set([source.id]) };
+    const pathBudget = { value: 0 };
+    const addVisiblePath = (targetId: string, path: GraphDependencyPath): void => {
+      const target = nodeById.get(targetId);
+      if (!target) return;
+      const sourceGroup = currentGroupId(source, taskForNode(source, tasks));
+      const targetGroup = currentGroupId(target, taskForNode(target, tasks));
+      const crossGroup: "yes" | "no" = sourceGroup && targetGroup && sourceGroup !== targetGroup ? "yes" : "no";
+      const key = displayEdgeKey(source.id, targetId);
+      const previous = collapsed.get(key);
+      if (previous?.paths.some((item) => pathKey(item) === pathKey(path))) return;
+      if (pathBudget.value >= MAX_GRAPH_PATHS) return;
+      let id = edgeIds.get(key);
+      if (!id) {
+        id = uniqueId(`display-edge:${encodeURIComponent(source.id)}:${encodeURIComponent(targetId)}`, usedIds);
+        edgeIds.set(key, id);
+      }
+      if (previous) addPath(previous.paths, path);
+      else collapsed.set(key, { id, source: source.id, target: targetId, paths: [path], crossGroup });
+      pathBudget.value += 1;
+    };
+    const addOutgoingPath = (path: GraphDependencyPath): void => {
+      const key = `outgoing\u0000${source.id}`;
+      const previous = boundary.get(key);
+      if (previous?.paths.some((item) => pathKey(item) === pathKey(path))) return;
+      if (pathBudget.value >= MAX_GRAPH_PATHS) return;
+      if (previous) addPath(previous.paths, path);
+      else addBoundary("outgoing", source.id, path);
+      pathBudget.value += 1;
+    };
+    const overflow = walkHiddenPaths(
+      initial,
+      outgoing,
+      visibleNodeIds,
+      nodeById,
+      addVisiblePath,
+      addOutgoingPath,
+      options.boundaryEndpointIds,
+    );
+    if (overflow) {
+      warn(`节点 ${source.id}`);
+      for (const [targetId, path] of findVisibleWitnesses(initial, outgoing, visibleNodeIds, nodeById, options.boundaryEndpointIds)) {
+        const edge = collapsed.get(displayEdgeKey(source.id, targetId));
+        if (!edge?.paths.some((item) => item.truncated)) addVisiblePath(targetId, { ...path, truncated: true });
+      }
+      for (const path of findTerminalWitnesses(initial, outgoing, visibleNodeIds, nodeById, options.boundaryEndpointIds)) addOutgoingPath({ ...path, truncated: true });
+    }
+  }
+
+  const hiddenNodeIds = new Set(view.nodes.filter((node) => HIDDEN_BOUNDARY_KINDS.has(node.kind)).map((node) => node.id));
+  const incoming = new Map<string, View["edges"]>();
+  for (const edge of view.edges) incoming.set(edge.to_node_id, [...(incoming.get(edge.to_node_id) ?? []), edge]);
+  const roots = [...hiddenNodeIds].filter((nodeId) => !(incoming.get(nodeId) ?? []).some((edge) => hiddenNodeIds.has(edge.from_node_id) || visibleNodeIds.has(edge.from_node_id)));
+  for (const root of roots) {
+    const initial: WalkState = { nodeId: root, path: { requires: [], sourceEdgeIds: [], boundaryNodeIds: [root] }, visited: new Set([root]) };
+    const pathBudget = { value: 0 };
+    const addIncomingPath = (targetId: string, path: GraphDependencyPath): void => {
+      const key = `incoming\u0000${targetId}`;
+      const previous = boundary.get(key);
+      if (previous?.paths.some((item) => pathKey(item) === pathKey(path))) return;
+      if (pathBudget.value >= MAX_GRAPH_PATHS) return;
+      if (previous) addPath(previous.paths, path);
+      else addBoundary("incoming", targetId, path);
+      pathBudget.value += 1;
+    };
+    const overflow = walkHiddenPaths(
+      initial,
+      outgoing,
+      visibleNodeIds,
+      nodeById,
+      addIncomingPath,
+      () => undefined,
+      options.boundaryEndpointIds,
+    );
+    if (overflow) {
+      warn(`计划入口 ${root}`);
+      for (const [targetId, path] of findVisibleWitnesses(initial, outgoing, visibleNodeIds, nodeById, options.boundaryEndpointIds)) {
+        const dependency = boundary.get(`incoming\u0000${targetId}`);
+        if (!dependency?.paths.some((item) => item.truncated)) addIncomingPath(targetId, { ...path, truncated: true });
+      }
+    }
+  }
+
+  return { edges: [...collapsed.values()], boundaryDependencies: [...boundary.values()], warnings };
+}
+
+export function buildGraphProjection(view: View, visibleTaskIds?: ReadonlySet<string>, visibleGroupIds?: ReadonlySet<string>): GraphProjection {
+  const taskById = new Map(view.tasks.map((task) => [task.id, task]));
+  const nodeById = new Map(view.nodes.map((node) => [node.id, node]));
+  const includedTasks = visibleTaskIds ?? new Set(view.tasks.map((task) => task.id));
+  const visibleNodes = view.nodes.filter((node) => !HIDDEN_BOUNDARY_KINDS.has(node.kind) && (node.kind !== "task" || (!!node.ref_id && includedTasks.has(node.ref_id))));
+  const visibleNodeIds = new Set(visibleNodes.map((node) => node.id));
+  const groupIds = new Set(visibleNodes.map((node) => currentGroupId(node, taskForNode(node, taskById))).filter((id): id is string => !!id));
+  if (visibleGroupIds) for (const groupId of visibleGroupIds) groupIds.add(groupId);
+  else if (visibleTaskIds === undefined || view.tasks.every((task) => includedTasks.has(task.id))) for (const group of view.groups) groupIds.add(group.id);
+  const usedNodeIds = new Set(visibleNodes.map((node) => node.id));
+  const groupNodeIds = new Map<string, string>();
+
+  const groupNodes: GraphProjectionNode[] = view.groups.filter((group) => groupIds.has(group.id)).map((group) => {
+    const id = uniqueId(`group:${group.id}`, usedNodeIds);
+    groupNodeIds.set(group.id, id);
+    return {
+      id,
+      parentId: null,
+      nodeKind: "group",
+      sourceNodeId: null,
+      refId: group.id,
+      groupId: group.id,
+      plannedGroupId: group.id,
+      taskKind: null,
+      state: group.state,
+      stateLabel: stateLabel(group.state),
+      stateIcon: stateIconName(group.state),
+      title: group.title,
+      graphLabel: fitGraphLabel(group.title, labelLimit("group")),
+      fullLabel: group.title,
+    };
+  });
+
+  const graphNodes: GraphProjectionNode[] = visibleNodes.map((node) => {
+    const task = taskForNode(node, taskById);
+    const nodeKind = projectionNodeKind(node);
+    const title = task?.title ?? node.label;
+    return {
+      id: node.id,
+      parentId: groupNodeIds.get(currentGroupId(node, task) ?? "") ?? null,
+      nodeKind,
+      sourceNodeId: node.id,
+      refId: node.ref_id,
+      groupId: currentGroupId(node, task),
+      plannedGroupId: plannedGroupId(node),
+      taskKind: canonicalTaskKind(task?.kind ?? null),
+      state: task?.state ?? null,
+      stateLabel: task ? stateLabel(task.state, task.is_ready) : null,
+      stateIcon: task ? stateIconName(task.state, task.is_ready) : null,
+      title,
+      graphLabel: fitGraphLabel(title, labelLimit(nodeKind)),
+      fullLabel: title,
+    };
+  });
+
+  const nodes = [...groupNodes, ...graphNodes];
+  // Empty delivery units need a synthetic endpoint so hidden boundaries still form visible relations.
+  const syntheticSources: Node[] = [];
+  const syntheticOutgoing = new Map<string, View["edges"]>();
+  const syntheticBoundaryStarts = new Map<string, string>();
+  const boundaryEndpointIds = new Map<string, string>();
+  for (const group of view.groups) {
+    const groupNodeId = groupNodeIds.get(group.id);
+    if (!groupNodeId || visibleNodes.some((node) => currentGroupId(node, taskForNode(node, taskById)) === group.id)) continue;
+    const boundaries = view.nodes.filter((node) => HIDDEN_BOUNDARY_KINDS.has(node.kind) && currentGroupId(node, taskForNode(node, taskById)) === group.id);
+    for (const boundary of boundaries) boundaryEndpointIds.set(boundary.id, groupNodeId);
+    const exit = boundaries.find((node) => node.kind === "group_end") ?? boundaries.find((node) => node.kind === "group_start");
+    if (!exit) continue;
+    const source: Node = { id: groupNodeId, kind: "milestone", ref_id: null, group_id: group.id, planned_group_id: group.id, label: group.title };
+    syntheticSources.push(source);
+    nodeById.set(source.id, source);
+    syntheticOutgoing.set(source.id, view.edges.filter((edge) => edge.from_node_id === exit.id));
+    syntheticBoundaryStarts.set(source.id, exit.id);
+  }
+  const dependencyNodes = [...visibleNodes, ...syntheticSources];
+  const dependencyNodeIds = new Set(dependencyNodes.map((node) => node.id));
+  const dependencies = makeDisplayDependencies(view, dependencyNodes, dependencyNodeIds, nodeById, taskById, new Set(nodes.map((node) => node.id)), { boundaryEndpointIds, syntheticOutgoing, syntheticBoundaryStarts });
+  return { nodes, ...dependencies };
+}
+
+export function nodeTitle(projection: GraphProjection, nodeId: string): string {
+  return projection.nodes.find((node) => node.id === nodeId)?.fullLabel ?? nodeId;
+}

package/toolkit/skills/multi-task-flow/web/graph-view.tsx

@@ -0,0 +1,72 @@
+import { TreePalm } from 'lucide';
+import React, { memo, useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { ReactFlow, BaseEdge, Handle, Position, type ReactFlowInstance, type NodeProps, type EdgeProps, type Node, type Edge, MarkerType } from '@xyflow/react';
+import { buildGraphProjection, type GraphProjection } from './graph-projection';
+import { layoutProjection, type GraphLayout, type Direction } from './graph-layout';
+import { accessibleNodeLabel, renderAccessibleNodes, highlightAccessibleSelection, type GraphContext } from './graph';
+import { taskKindLabel } from './labels';
+import type { Task } from './model';
+
+type CardData = { title: string; kind: string; state: string; idle: boolean; color: string; label: string; ports: {id:string; source:boolean}[]; direction: Direction; group: boolean; taskId: string | null; contextKind: "task" | "group" | null; contextId: string | null };
+const Card = memo(function Card({data}: NodeProps) {
+  const d = data as unknown as CardData;
+  return <div data-context-kind={d.contextKind ?? undefined} data-context-id={d.contextId ?? undefined} data-context-task={d.taskId ?? undefined} className={d.group ? 'dependency-group' : 'dependency-card'} style={{'--node-color':d.color} as React.CSSProperties}>
+    <div className="dependency-card-meta"><span>{d.kind}</span><span className={d.idle ? "dependency-state-idle" : undefined}>{d.idle ? <svg aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">{TreePalm.map(([tag, props], i) => React.createElement(tag, {...props, key:i}))}</svg> : null}{d.state}</span></div>
+    <div className="dependency-card-title">{d.title}</div>
+    {d.ports.map(p => <Handle key={p.id} id={p.id} type={p.source?'source':'target'} position={d.direction==='DOWN'?(p.source?Position.Bottom:Position.Top):(p.source?Position.Right:Position.Left)} />)}
+  </div>;
+});
+const Routed = memo(function Routed(props: EdgeProps) { return <BaseEdge id={props.id} path={String(props.data?.path ?? '')} markerEnd={props.markerEnd} style={props.style} interactionWidth={16} />; });
+const nodeTypes = {card: Card}, edgeTypes = {routed: Routed};
+
+export function createGraphController(context: GraphContext, calculateLayout = layoutProjection) {
+  const container = context.element('graph');
+  const root = createRoot(container);
+  let projection: GraphProjection | null = null, instance: ReactFlowInstance | null = null;
+  let direction: Direction = 'RIGHT', generation = 0;
+  let latest: Task[] = [], latestGroupIds: ReadonlySet<string> | undefined, update: (() => void) | null = null;
+  let layout: GraphLayout | null = null, error = '', pending = false;
+  let signature = '', viewportInitialized = false;
+  const highlightSelection = () => { highlightAccessibleSelection(projection, context); update?.(); };
+  function Surface() {
+    const [, refresh] = useState(0);
+    useEffect(() => { update = () => refresh(v=>v+1); return () => {update=null;}; }, []);
+    const selected = context.getSelected();
+    const nodes: Node[] = (layout?.nodes ?? []).map(({node:n,x,y,width,height}) => ({
+      id:n.id, type:'card', position:{x,y}, width,height,
+      zIndex:n.nodeKind==='group'?-1:1,
+      selectable: true, draggable:false,
+      ariaLabel: projection ? accessibleNodeLabel(n, projection) : n.title,
+      selected:n.nodeKind==='task'?selected.task===n.refId:selected.group===n.refId,
+      style:{width,height},
+      data:{taskId:n.nodeKind==='task'?n.refId:null,contextKind:n.nodeKind==='task'?'task':n.nodeKind==='group'?'group':n.nodeKind==='milestone'?'milestone':null,contextId:n.nodeKind==='task'||n.nodeKind==='group'?n.refId:n.nodeKind==='milestone'?n.id:null,title:n.title,group:n.nodeKind==='group',kind:n.nodeKind==='group'?'交付单元':n.nodeKind==='milestone'?'里程碑':taskKindLabel(n.taskKind??'coordination').split(' ')[0],state:n.stateLabel??'',idle:n.state==='agent_idle',direction,
+        color:n.nodeKind==='group'?context.groupColor(n.groupId):n.state?context.stateColor(n.state):context.css('--accent','#5889c4'),
+        ports:(projection?.edges??[]).filter(e=>e.source===n.id||e.target===n.id).map(e=>({id:`port:${e.id}:${e.source===n.id?'source':'target'}`,source:e.source===n.id})),},
+    }));
+    const edges: Edge[] = (layout?.edges??[]).map(e=>({id:e.id,source:e.source,target:e.target,type:'routed',sourceHandle:`port:${e.id}:source`,targetHandle:`port:${e.id}:target`,data:{path:e.path},markerEnd:{type:MarkerType.ArrowClosed,width:16,height:16,color:context.css('--muted','#789096')},style:{stroke:context.css('--muted','#789096'),strokeWidth:1.5}}));
+    return <><div className="dependency-layout-tools"><span>前置任务 → 后续任务 · 正交连线</span><label>排列方向 <select value={direction} onChange={e=>{direction=e.target.value as Direction;signature='';viewportInitialized=false;render(latest,latestGroupIds);}}><option value="DOWN">从上到下</option><option value="RIGHT">从左到右</option></select></label><button onClick={()=>{instance?.setViewport({x:24,y:24,zoom:1});context.setZoom(1);}}>100% 阅读</button></div>{error?<div role="alert" className="notice notice-warning">{error}</div>:null}<ReactFlow nodes={nodes} edges={edges} nodeTypes={nodeTypes} edgeTypes={edgeTypes}
+      onInit={i=>{instance=i;}} deleteKeyCode={null} nodesConnectable={false} nodesDraggable={false} elementsSelectable={true} minZoom={0.15} maxZoom={2.5}
+      zoomOnScroll={false} zoomOnPinch={true} panOnScroll={true} panOnDrag={true} preventScrolling={false}
+      onMoveEnd={(_,v)=>context.setZoom(Math.round(v.zoom*100)/100)}
+      onNodeClick={(_,n)=>{const item=projection?.nodes.find(p=>p.id===n.id);if(item?.refId){if(item.nodeKind==='task')context.selectTask(item.refId);else if(item.nodeKind==='group')context.selectGroup(item.refId);else if(item.nodeKind==='milestone')context.selectMilestone(item.id);}}}
+      onNodeMouseEnter={(event,n)=>{const data=context.getData(), item=projection?.nodes.find(p=>p.id===n.id);if(!item?.refId||!data)return;const target=event.currentTarget as HTMLElement;const task=data.tasks.find(t=>t.id===item.refId),group=data.groups.find(g=>g.id===item.refId);if(task)context.showHoverPreview(context.taskPreview(task),target.getBoundingClientRect());else if(group)context.showHoverPreview(context.groupPreview(group),target.getBoundingClientRect());}}
+      onNodeMouseLeave={context.hideHoverPreview} proOptions={{hideAttribution:false}} />{pending?<span className="dependency-layout-pending" role="status">正在计算布局…</span>:null}</>;
+  }
+  root.render(<Surface/>);
+  function render(tasks: Task[], visibleGroupIds?: ReadonlySet<string>) {
+    latest=tasks;latestGroupIds=visibleGroupIds;const data=context.getData();if(!data)return;
+    const next=buildGraphProjection(data,new Set(tasks.map(t=>t.id)),visibleGroupIds);
+    context.element('graph-empty').hidden=next.nodes.length>0;
+    const warning=context.element('graph-projection-warning');warning.hidden=!next.warnings.length;warning.textContent=next.warnings.join(' ');
+    projection=next;renderAccessibleNodes(next,context);
+    const key=JSON.stringify([direction,next.nodes.map(n=>[n.id,n.parentId,n.title]),next.edges.map(e=>[e.id,e.source,e.target])]);
+    if(key===signature){if(layout){const byId=new Map(next.nodes.map(n=>[n.id,n]));layout={...layout,nodes:layout.nodes.map(p=>({...p,node:byId.get(p.node.id)!}))};}highlightSelection();return;}
+    signature=key;layout=null;const serial=++generation;pending=true;error='';update?.();
+    calculateLayout(next,direction).then(result=>{
+      if(serial!==generation)return;const byId=new Map(projection!.nodes.map(n=>[n.id,n]));layout={...result,nodes:result.nodes.map(p=>({...p,node:byId.get(p.node.id)!}))};pending=false;container.style.height = `${Math.max(420,result.height+80)}px`;update?.();
+      requestAnimationFrame(()=>{if(serial!==generation)return;if(!viewportInitialized){instance?.setViewport({x:Math.max(24,(container.clientWidth-result.width)/2),y:24,zoom:1});context.setZoom(1);viewportInitialized=true;} highlightSelection();});
+    }).catch(e=>{if(serial!==generation)return;pending=false;error=`依赖图布局失败：${e instanceof Error?e.message:String(e)}`;signature='';update?.();});
+  }
+  return {render,highlightSelection,zoomIn:()=>instance?.zoomIn(),zoomOut:()=>instance?.zoomOut(),fit:()=>instance?.fitView({padding:0.08}),rankDir:()=>direction==='DOWN'?'TB':'LR',projection:()=>projection};
+}

package/toolkit/skills/multi-task-flow/web/graph.ts

@@ -0,0 +1,101 @@
+import type { Task, View } from "./model";
+import { dependencyLabel, taskKindLabel } from "./labels";
+import type { GraphDependencyPath, GraphProjection, GraphProjectionNode } from "./graph-projection";
+export { createGraphController } from "./graph-view";
+
+export type GraphContext = {
+  element: <T extends HTMLElement>(id: string) => T;
+  getData: () => View | null;
+  getViewState: () => { zoom: number };
+  setZoom: (zoom: number) => void;
+  css: (name: string, fallback: string) => string;
+  stateColor: (state: string, ready?: boolean) => string;
+  groupColor: (groupId: string | null) => string;
+  taskPreview: (task: Task) => HTMLElement;
+  groupPreview: (group: View["groups"][number]) => HTMLElement;
+  showHoverPreview: (content: HTMLElement, anchor: DOMRect) => void;
+  hideHoverPreview: () => void;
+  recordPointerType: (pointerType: string | null) => void;
+  selectTask: (id: string) => void;
+  selectGroup: (id: string) => void;
+  selectMilestone: (id: string) => void;
+  getSelected: () => { task: string | null; group: string | null; milestone: string | null };
+};
+
+function nodeKindLabel(node: GraphProjectionNode): string {
+  if (node.nodeKind === "group") return "交付单元";
+  if (node.nodeKind === "task") return taskKindLabel(node.taskKind ?? "coordination");
+  if (node.nodeKind === "milestone") return "里程碑 milestone";
+  return "节点";
+}
+
+function pathLabel(path: GraphDependencyPath): string {
+  const conditions = path.requires.length ? path.requires.map(dependencyLabel).join(" → ") : "未声明条件";
+  const edges = path.sourceEdgeIds.length ? path.sourceEdgeIds.join("、") : "无";
+  return `条件：${conditions}；原始边：${edges}${path.truncated ? "；其余路径已省略" : ""}`;
+}
+
+function dependencyLabels(projection: GraphProjection, nodeId: string, direction: "incoming" | "outgoing"): string[] {
+  const values = projection.edges
+    .filter((edge) => direction === "incoming" ? edge.target === nodeId : edge.source === nodeId)
+    .map((edge) => {
+      const neighborId = direction === "incoming" ? edge.source : edge.target;
+      const neighbor = projection.nodes.find((node) => node.id === neighborId)?.fullLabel ?? neighborId;
+      return `${neighbor}（${edge.paths.map(pathLabel).join("；")}）`;
+    });
+  values.push(...projection.boundaryDependencies
+    .filter((item) => item.direction === direction && item.nodeId === nodeId)
+    .map((item) => `${direction === "incoming" ? "计划入口" : "计划出口"}（${item.paths.map(pathLabel).join("；")}）`));
+  return values;
+}
+
+export function accessibleNodeLabel(node: GraphProjectionNode, projection: GraphProjection): string {
+  const parts = [`${nodeKindLabel(node)}：${node.title}`];
+  if (node.stateLabel) parts.push(`状态：${node.stateLabel}`);
+  const incoming = dependencyLabels(projection, node.id, "incoming");
+  const outgoing = dependencyLabels(projection, node.id, "outgoing");
+  if (incoming.length) parts.push(`前驱：${incoming.join("；")}`);
+  if (outgoing.length) parts.push(`后继：${outgoing.join("；")}`);
+  return parts.join("；");
+}
+
+function selectedProjectionNode(node: GraphProjectionNode, context: GraphContext): void {
+  if (!node.refId) return;
+  if (node.nodeKind === "task") context.selectTask(node.refId);
+  else if (node.nodeKind === "group") context.selectGroup(node.refId);
+  else if (node.nodeKind === "milestone") context.selectMilestone(node.id);
+}
+
+export function renderAccessibleNodes(projection: GraphProjection, context: GraphContext): void {
+  const container = context.element("graph-a11y");
+  container.replaceChildren();
+  container.setAttribute("aria-label", `依赖图节点列表，共 ${projection.nodes.length} 个节点`);
+  for (const node of projection.nodes) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "graph-a11y-node";
+    button.dataset.graphNodeId = node.id;
+    if ((node.nodeKind === "task" || node.nodeKind === "group" || node.nodeKind === "milestone") && node.refId) {
+      button.dataset.contextKind = node.nodeKind === "task" ? "task" : node.nodeKind === "milestone" ? "milestone" : "group";
+      button.dataset.contextId = node.nodeKind === "milestone" ? node.id : node.refId;
+      if (node.nodeKind === "task") button.dataset.contextTask = node.refId;
+    }
+    button.setAttribute("aria-pressed", "false");
+    button.setAttribute("aria-label", accessibleNodeLabel(node, projection));
+    button.textContent = `${node.title}${node.stateLabel ? ` · ${node.stateLabel}` : ""}`;
+    button.addEventListener("click", () => selectedProjectionNode(node, context));
+    const item = document.createElement("div");
+    item.setAttribute("role", "listitem");
+    item.append(button);
+    container.append(item);
+  }
+}
+
+export function highlightAccessibleSelection(projection: GraphProjection | null, context: GraphContext): void {
+  const selected = context.getSelected();
+  for (const button of context.element("graph-a11y").querySelectorAll<HTMLButtonElement>("[data-graph-node-id]")) {
+    const node = projection?.nodes.find((item) => item.id === button.dataset.graphNodeId);
+    const active = Boolean(node && ((node.nodeKind === "task" && node.refId === selected.task) || (node.nodeKind === "group" && node.refId === selected.group) || (node.nodeKind === "milestone" && node.id === selected.milestone)));
+    button.setAttribute("aria-pressed", String(active));
+  }
+}