dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/client/KnowledgeGraphView.tsx

@@ -0,0 +1,306 @@
+/**
+ * 知识图谱 —— 一张 AntV G6 画布画出当前知识库编译出来的图。
+ *
+ * 与「Agent 概览」那张架构图的分工：那张图回答**方案怎么搭**（三条链路、谁注入谁），
+ * 节点是固定的十七个，所以坐标是设计结论；这张图回答**这个库里到底连出了什么**
+ * （哪张卡片由哪几份原始文档支撑），节点随知识库增长，所以坐标交给 dagre。
+ *
+ * 三条纪律与架构图一致：
+ * 1. **画布只画，不算。** 筛选与坐标在 `./graph/layout.ts` 里，纯数据进出，可以断言。
+ * 2. **点击只改高亮，不重建画布。** 重建会把滚动位置和缩放档一起清掉。
+ * 3. **缩放不用 G6 的 `fitView`**：这版 G6 对 HTML 节点算不出内容包围盒（实测无效），
+ *    所以画布按设计尺寸渲染、再缩整块板 —— 见 `useFitScale`。
+ */
+
+import { Graph } from '@antv/g6'
+import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { Maximize2, Minimize2, Search } from '@tita-data-agent/ui/icons'
+import { Button, Input, cn } from '@tita-data-agent/ui/components'
+import {
+  GRAPH_NODE_H, GRAPH_NODE_W, edgeTypeCounts, filterGraph, keyOf, layoutGraph, neighborsOf, nodeTypeCounts,
+  type GraphEdgeView, type GraphNodeView, type PlacedGraph, type PlacedNode,
+} from './graph/layout.ts'
+import { useFitScale, type ZoomMode } from './useFitScale.ts'
+import { styles } from './styles.ts'
+// 图谱视图自己的版式（筛选栏 + 画布 + 详情条）跟着这个组件走。
+import './graph.css'
+
+const FONT = 'var(--font-tita)'
+/* 卡片是 G6 的 HTML 节点（innerHTML 进真实 DOM），所以这些值走共享令牌；画布**画**出来
+ * 的东西（边、画布底色）不行 —— canvas 渲染器把 `var()` 判为无效色，见下面的注释。 */
+const INK = 'var(--tita-ink)'
+const INK_MUTED = 'var(--tita-ink-muted)'
+const RULE = 'var(--tita-line)'
+
+/**
+ * 节点类型色。**这里是颜色承担信息的地方**，所以它必须与筛选条上的色点一一对应 ——
+ * 筛「metric」时用户找的就是那几个同色的小方块。
+ *
+ * 六档换到共享词表时收窄了：词表只有四个分类色（blue / violet / green / amber）加主色与
+ * danger，没有青色也没有品红，所以原来的青绿 `#0e7490` 取最近的绿、品红 `#be185d` 取
+ * danger —— 第 2 与第 5 档（tone-green / success）现在都是绿，靠标签文字区分。
+ * `source` 不参与轮转：它是溯源层，不是一类知识，所以它拿中性灰。
+ */
+const TYPE_COLORS = [
+  'var(--tita-primary)', 'var(--tita-tone-green)', 'var(--tita-tone-violet)',
+  'var(--tita-tone-amber)', 'var(--tita-success)', 'var(--tita-danger)',
+]
+export function typeColor(type: string, types: string[]): string {
+  if (type === 'source') return INK_MUTED
+  const index = types.filter(item => item !== 'source').indexOf(type)
+  return TYPE_COLORS[(index < 0 ? 0 : index) % TYPE_COLORS.length] as string
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char] as string)
+}
+
+/**
+ * 一张节点卡片。宽度固定 176px，所以标题只能一行，靠 `title` 属性补全。
+ *
+ * `source` 节点的标题在接口里就是它的 docId（`question:e062c1bf…`），读不出是哪份文档 ——
+ * 所以调用方把「docId → 文档标题」的映射传进来，能对上就显示标题，对不上才退回 id。
+ */
+function nodeHtml(node: PlacedNode, color: string, selected: boolean, dim: boolean, label: string): string {
+  // 来源节点不挂「来源」两个字：那两个字要从标题里借 28px，而来源的文档标题本来就长
+  // （「CASE-001 日报 GMV 为 0」），借完就只剩省略号。它靠三件事认出来就够了 ——
+  // 中性灰的圆点、右边那一列的位置、以及箭头都指向它。
+  const source = node.type === 'source'
+  return `<div class="tita-kgNode${selected ? ' tita-kgNodeOn' : ''}" title="${escapeHtml(`${node.type} · ${label}`)}" style="box-sizing:border-box;width:100%;height:100%;display:flex;align-items:center;gap:6px;padding:0 9px;border-radius:6px;background:${source ? 'var(--tita-surface-muted)' : 'var(--tita-surface)'};border:1px solid ${selected ? color : RULE};box-shadow:${selected ? `0 0 0 3px color-mix(in srgb, ${color} 13%, transparent)` : '0 1px 2px rgba(16,24,40,.04)'};font-family:${FONT};overflow:hidden;opacity:${dim ? .3 : 1}">
+  <span style="width:6px;height:6px;border-radius:999px;background:${color};flex:0 0 auto"></span>
+  <strong style="min-width:0;flex:1 1 auto;overflow:hidden;white-space:nowrap;text-overflow:ellipsis;font-size:11.5px;font-weight:${source ? 500 : 600};color:${source ? INK_MUTED : INK}">${escapeHtml(label)}</strong>
+</div>`
+}
+
+/* 画布侧的两个字面量颜色：canvas 不能读 CSS 变量（见建图那一处的注释），而图例色点
+ * 必须与画布上的边同色，所以它们共用这两个常量而不是各写一份。 */
+const EDGE_GREY = '#7d8b9e'
+const EDGE_SELECTED = '#175cd3'
+/* 选中光晕是「类型色 13%」。原写法 `${color}22` 依赖 color 是十六进制串；换成令牌之后
+ * 那个后缀会拼出非法颜色（整条 box-shadow 会被丢掉），所以用 color-mix 表达同一个 13%。 */
+
+/** 画布可视高度上限：知识图谱会长到几百上千像素，整块撑开会把页面拉得很长。 */
+const GRAPH_VIEWPORT_H = 520
+
+export interface KnowledgeGraphViewProps {
+  nodes: GraphNodeView[]
+  edges: GraphEdgeView[]
+  visible: boolean
+  loading?: boolean
+  /** SourceRaw 的 docId → 文档标题。图谱里的来源节点只有 id，得靠它才读得出来。 */
+  sourceTitles?: Map<string, string>
+}
+
+export function KnowledgeGraphView({ nodes, edges, visible, loading = false, sourceTitles }: KnowledgeGraphViewProps): ReactNode {
+  const host = useRef<HTMLDivElement>(null)
+  const scroller = useRef<HTMLDivElement>(null)
+  const stage = useRef<HTMLElement>(null)
+  const graphRef = useRef<Graph | null>(null)
+  const [fullscreen, setFullscreen] = useState(false)
+  const [mode, setMode] = useState<ZoomMode>('fit')
+  const [nodeTypes, setNodeTypes] = useState<string[]>([])
+  const [edgeTypes, setEdgeTypes] = useState<string[]>([])
+  const [query, setQuery] = useState('')
+  const [selected, setSelected] = useState<string | null>(null)
+  const [placed, setPlaced] = useState<PlacedGraph | null>(null)
+
+  const allTypes = useMemo(() => nodeTypeCounts(nodes).map(item => item.type), [nodes])
+  const filtered = useMemo(
+    () => filterGraph(nodes, edges, { nodeTypes, edgeTypes, query }),
+    [nodes, edges, nodeTypes, edgeTypes, query],
+  )
+
+  // 排一次版。筛选变了就重排 —— dagre 对同一份输入给出同一个形状，所以这是幂等的。
+  useEffect(() => {
+    if (!visible) return undefined
+    let cancelled = false
+    void layoutGraph(filtered.nodes, filtered.edges).then(result => { if (!cancelled) setPlaced(result) })
+    return () => { cancelled = true }
+  }, [visible, filtered])
+
+  // 筛掉的节点如果正被选中，选中态要跟着失效，否则面板会显示一个图上已经没有的节点。
+  useEffect(() => {
+    if (selected && !filtered.nodes.some(node => keyOf(node) === selected)) setSelected(null)
+  }, [filtered, selected])
+
+  const contentW = placed?.width ?? GRAPH_NODE_W * 2
+  const contentH = placed?.height ?? GRAPH_NODE_H * 2
+  const { scale, boardH } = useFitScale(scroller, contentW, contentH, visible && placed !== null, fullscreen, mode)
+
+  // ---------------------------------------------------------------- 建图
+  useEffect(() => {
+    const el = host.current
+    if (!el || !visible || !placed) return undefined
+    const graph = new Graph({
+      container: el,
+      width: el.clientWidth || contentW,
+      height: el.clientHeight || contentH,
+      // 画布底色交给容器（`.tita-kgScroll` 的 `--tita-surface`）：G6 的 canvas 渲染器
+      // 不认 CSS 变量，写 `var(--tita-surface)` 会被解析成全透明黑（`parseColor` 的兜底），
+      // 反而画出黑底。透明则透出容器已主题化的底，浅色下与原来的纯白一致。
+      background: 'transparent',
+      // 图级 node/edge type 不要设：G6 v5 用它覆盖元素自己声明的 type。
+    })
+    graphRef.current = graph
+    graph.on('node:click', event => {
+      const id = (event as { target?: { id?: string } }).target?.id
+      if (id) setSelected(current => current === id ? null : id)
+    })
+    graph.on('canvas:click', () => setSelected(null))
+    return () => { graph.destroy(); graphRef.current = null }
+  }, [visible, placed, contentW, contentH])
+
+  // ---------------------------------------------------------------- 喂数据
+  useEffect(() => {
+    const graph = graphRef.current
+    if (!graph || !visible || !placed) return
+    const colors = new Map(placed.nodes.map(node => [node.key, typeColor(node.type, allTypes)]))
+    graph.setData({
+      nodes: placed.nodes.map(node => ({
+        id: node.key,
+        type: 'html',
+        style: {
+          x: node.x, y: node.y, size: [GRAPH_NODE_W, GRAPH_NODE_H],
+          dx: -GRAPH_NODE_W / 2, dy: -GRAPH_NODE_H / 2,
+          innerHTML: nodeHtml(node, colors.get(node.key) as string, false, false, labelOf(node)),
+          pointerEvents: 'auto',
+        },
+      })),
+      edges: placed.edges.map((edge, index) => ({
+        id: `e${index}`,
+        source: edge.from,
+        target: edge.to,
+        // 分层图里用横向 S 曲线：直线在多层之间会互相穿插，曲线能看出哪条从哪来。
+        type: 'cubic-horizontal',
+        data: { kind: edge.type },
+        // 画布侧字面量：canvas 不认 `var()`（见上面的 background 注释）。
+        style: { stroke: EDGE_GREY, lineWidth: 1.2, endArrow: true, endArrowType: 'triangle', endArrowSize: 7 },
+      })),
+    })
+    void graph.render()
+  }, [visible, placed, allTypes, sourceTitles])
+
+  // ---------------------------------------------------------------- 高亮
+  useEffect(() => {
+    const graph = graphRef.current
+    if (!graph || !visible || !placed) return
+    const colors = new Map(placed.nodes.map(node => [node.key, typeColor(node.type, allTypes)]))
+    // 选中一个节点时，它的邻居仍然全亮，其余降到 0.3 —— 「这张卡片接着谁」一眼可见。
+    const keep = new Set<string>()
+    if (selected) {
+      keep.add(selected)
+      for (const edge of placed.edges) {
+        if (edge.from === selected) keep.add(edge.to)
+        if (edge.to === selected) keep.add(edge.from)
+      }
+    }
+    graph.updateNodeData(placed.nodes.map(node => ({
+      id: node.key,
+      style: { innerHTML: nodeHtml(node, colors.get(node.key) as string, node.key === selected, Boolean(selected) && !keep.has(node.key), labelOf(node)) },
+    })))
+    graph.updateEdgeData(placed.edges.map((edge, index) => ({
+      id: `e${index}`,
+      style: selected && (edge.from === selected || edge.to === selected)
+        ? { stroke: EDGE_SELECTED, lineWidth: 1.8 }
+        : { stroke: EDGE_GREY, lineWidth: 1.2 },
+    })))
+    void graph.draw()
+  }, [selected, visible, placed, allTypes, sourceTitles])
+
+  // ---------------------------------------------------------------- 全屏
+  const toggleFullscreen = (): void => {
+    const el = stage.current
+    if (!el) return
+    if (document.fullscreenElement === el) void document.exitFullscreen()
+    else void el.requestFullscreen()
+  }
+  useEffect(() => {
+    const onChange = (): void => setFullscreen(document.fullscreenElement === stage.current)
+    document.addEventListener('fullscreenchange', onChange)
+    return () => document.removeEventListener('fullscreenchange', onChange)
+  }, [])
+
+  const typeCounts = useMemo(() => nodeTypeCounts(nodes), [nodes])
+  const edgeCounts = useMemo(() => edgeTypeCounts(edges), [edges])
+  const selectedNode = selected ? placed?.nodes.find(node => node.key === selected) ?? null : null
+  const neighbors = selected && placed ? neighborsOf(selected, placed.nodes, placed.edges) : []
+  /** 卡片上显示什么：来源节点优先用真实文档标题，其余用卡片标题。 */
+  const labelOf = (node: PlacedNode): string =>
+    node.type === 'source' ? sourceTitles?.get(node.id) ?? node.title : node.title
+
+  const toggle = (list: string[], value: string, set: (next: string[]) => void): void => {
+    set(list.includes(value) ? list.filter(item => item !== value) : [...list, value])
+  }
+
+  return <section className={styles.kgStage} ref={stage} aria-label="知识图谱">
+    <header className={styles.kgBar}>
+      <div className={styles.kgFilters}>
+        <label className={styles.kgSearch}>
+          <Search size={13} aria-hidden="true" />
+          <Input value={query} placeholder="按标题或 id 搜索节点" onChange={event => setQuery(event.target.value)} />
+        </label>
+        <div className={styles.kgChips} role="group" aria-label="按节点类型筛选">
+          {typeCounts.map(item => <button
+            key={item.type} type="button"
+            className={cn(styles.kgChip, nodeTypes.includes(item.type) && styles.kgChipOn)}
+            aria-pressed={nodeTypes.includes(item.type)}
+            onClick={() => toggle(nodeTypes, item.type, setNodeTypes)}
+          >
+            <i style={{ background: typeColor(item.type, allTypes) }} aria-hidden="true" />
+            <code>{item.type}</code><b>{item.count}</b>
+          </button>)}
+        </div>
+        {edgeCounts.length > 1 && <div className={styles.kgChips} role="group" aria-label="按边类型筛选">
+          {edgeCounts.map(item => <button
+            key={item.type} type="button"
+            className={cn(styles.kgChip, edgeTypes.includes(item.type) && styles.kgChipOn)}
+            aria-pressed={edgeTypes.includes(item.type)}
+            onClick={() => toggle(edgeTypes, item.type, setEdgeTypes)}
+          >
+            {/* 色点与画布上的边同色，所以这里也用那个字面量（EDGE_GREY）。 */}
+            <i style={{ background: EDGE_GREY }} aria-hidden="true" />
+            <code>{item.type}</code><b>{item.count}</b>
+          </button>)}
+        </div>}
+      </div>
+      <div className={styles.kgActions}>
+        <span className={styles.kgCounts}>
+          <b>{filtered.nodes.length}</b>/{nodes.length} 节点
+          {/* 带进来的邻居要说出来，否则「筛了 8 个类型却显示 12 个节点」像是算错了。 */}
+          {filtered.nodes.length > filtered.matched && <em>含 {filtered.nodes.length - filtered.matched} 个邻居</em>}
+          <b>{filtered.edges.length}</b>/{edges.length} 边
+        </span>
+        <div className={styles.kgZoom} role="group" aria-label="缩放">
+          <button type="button" className={cn(styles.kgZoomOption, mode === 'fit' && styles.kgZoomOn)} aria-pressed={mode === 'fit'} onClick={() => setMode('fit')}>适应</button>
+          <button type="button" className={cn(styles.kgZoomOption, mode === 'actual' && styles.kgZoomOn)} aria-pressed={mode === 'actual'} onClick={() => setMode('actual')}>1:1</button>
+        </div>
+        <Button variant="outline" size="sm" onClick={toggleFullscreen} aria-pressed={fullscreen}>
+          {fullscreen ? <Minimize2 size={14} /> : <Maximize2 size={14} />}{fullscreen ? '退出全屏' : '全屏'}
+        </Button>
+      </div>
+    </header>
+
+    <div className={styles.kgScroll} style={fullscreen ? undefined : { height: Math.min(boardH, GRAPH_VIEWPORT_H) }} ref={scroller}>
+      <div className={styles.kgBoard} style={{ width: contentW, height: contentH, transform: `scale(${scale})`, transformOrigin: 'top left' }}>
+        <div className={styles.kgCanvas} ref={host} />
+      </div>
+      {placed && placed.nodes.length === 0 && <p className={styles.kgEmpty}>
+        {loading ? '正在读取图谱…' : nodes.length === 0 ? '这个知识库还没有图谱节点。先在上面的工具栏编译一次。' : '当前筛选下没有节点。清掉筛选条件看看。'}
+      </p>}
+    </div>
+
+    {/* 选中一个节点：它的类型、度数，以及直接相连的邻居（可点着走过去）。 */}
+    {selectedNode && <div className={styles.kgDetail}>
+      <span className={styles.kgDetailHead}>
+        <i style={{ background: typeColor(selectedNode.type, allTypes) }} aria-hidden="true" />
+        <code>{selectedNode.type}</code>
+        <strong>{labelOf(selectedNode)}</strong>
+        <em>{selectedNode.degree} 条边</em>
+      </span>
+      {neighbors.length > 0 && <span className={styles.kgNeighbors}>
+        相连：
+        {neighbors.map(node => <button key={keyOf(node)} type="button" onClick={() => setSelected(keyOf(node))}>{node.title}</button>)}
+      </span>}
+    </div>}
+  </section>
+}