dsh-data-domain-knowledge 0.1.0-alpha.9 → 0.1.1-alpha.2

package/src/client/GuideArchitectureCanvas.tsx

@@ -0,0 +1,470 @@
+/**
+ * 架构说明页的画布：**一条链路 = 画布上的一条工序带**。
+ *
+ * ## 它和 Agent 概览为什么不是同一个渲染层
+ *
+ * 两者画的是同一份数据（`architecture.tsx` 的 `NODE_META` + `arch/model.ts` 的坐标与连边），
+ * 但回答的问题不同：
+ *
+ * - **概览**是「现在跑到哪一步」—— 十七张卡要同时在场，卡片挂实时计数，
+ *   所以坐标固定、内容由数据喂（G6 HTML 节点 + `updateNodeData`）。
+ * - **这一页**是「这条链路有哪些环节、每一步做什么」—— 一次只读一条链路，
+ *   卡片要排三层信息（标题 / 步骤表 / 状态）。这是**排版**问题，不是画布问题。
+ *
+ * G6 的 canvas 文本只有一种字号与字重，装不下三层；换成 HTML 节点之后它又算不出内容
+ * 包围盒，`fitView` / `zoomTo` 实测失效（见 `useFitScale.ts` 的头注释）。所以这里
+ * **SVG 画带与连线、卡片是普通 DOM、缩放由整块板的 `transform` 承担**。
+ *
+ * ## 三条构图纪律（第一版在这里翻过车）
+ *
+ * 1. **三条链路始终在场。** 这是完整架构图，切换 Tab 只改变高亮，不改变节点位置。
+ * 2. **节点点击只选中一个节点。** 只有左上角显式选择链路时，才整体高亮这条链路。
+ * 3. **侧边详情不挤压画布。** Inspector 浮在画布右侧，节点仍使用完整设计宽度。
+ *
+ * 坐标仍然只有一个来源：`arch/model.ts`。位置、顺序、走线都不在这里重算。
+ */
+
+import { useEffect, useId, useLayoutEffect, useRef, useState, type PointerEvent as ReactPointerEvent, type ReactNode } from 'react'
+import { Button, Tabs, TabsList, TabsTrigger, cn } from '@tita-agent/ui/components'
+import { X } from '@tita-agent/ui/icons'
+import {
+  NODE_LANES, NODE_META, NODE_ORDER, NODE_STATUS_LABEL,
+  type NodeId, type NodeStep,
+} from './architecture.tsx'
+import {
+  ARCH_EDGES, BAND_H, BOTTOM, CANVAS_WIDTH, EDGE_STYLE,
+  GUTTER, LANE_HEAD_H, LANE_HEAD_W, LANE_PALETTE,
+  boxOf, columnGapX, laneCenter, laneGapY, laneTop,
+  type ArchEdge,
+} from './arch/model.ts'
+
+/** 说明页能选中的对象：架构图上的真实节点，外加四个产品概念入口。 */
+export type GuideNodeId = NodeId | 'knowledge' | 'attribution' | 'memory' | 'eval'
+
+/**
+ * 链路筛选。`all` 不是「第五条链路」，是**不筛选** —— 它是这张图的初始读法，
+ * 也是唯一能看到三条链路怎么咬合的那一档。
+ */
+export type GuideChainId = 'all' | 'compile' | 'recall' | 'memory'
+
+export interface GuideChainTab {
+  id: GuideChainId
+  label: string
+  /** 一句链路走向，写在 Tab 的 `title` 上。 */
+  note: string
+  /** 切到这条链路时右侧默认展开哪个环节。`all` 不动当前选择。 */
+  entry: GuideNodeId | null
+  /** 这条链路点亮哪些节点。 */
+  nodes: readonly NodeId[]
+}
+
+/**
+ * 四档筛选。**每一档点亮的集合是设计结论，不是包含关系**：
+ *
+ * - 编译只点亮写入侧（SourceRaw → 编译 → 构建）。把「召回」也算进来会让人以为
+ *   编译链路要等召回跑完，而它们是同一条 B 带的两端。
+ * - 记忆链路把 `source-raw` 一起点亮：确认后的记忆**汇成一份来源**再回到编译入口，
+ *   这是闭环的落点；不点亮它，链路的最后一段就没有去处。
+ */
+export const GUIDE_CHAIN_TABS: readonly GuideChainTab[] = [
+  { id: 'all', label: '全部链路', note: '三条链路：看清跨链路怎么咬合', entry: null, nodes: NODE_ORDER },
+  { id: 'compile', label: '知识编译', note: 'SourceRaw → 编译 → 构建', entry: 'compile', nodes: ['source-raw', 'compile', 'build'] },
+  { id: 'recall', label: '知识召回', note: '对话 → 意图 → 召回 → 重排 → Runtime → 回答', entry: 'recall', nodes: ['conversation', 'intent', 'recall', 'context', 'runtime', 'answer'] },
+  { id: 'memory', label: '记忆构建', note: '交互 → 记忆 → 质量门 → 每日更新 → SourceRaw', entry: 'interaction', nodes: ['interaction', 'episodic-memory', 'procedural-memory', 'memory-quality', 'daily-update', 'source-raw'] },
+]
+
+const TAB_BY_ID = new Map(GUIDE_CHAIN_TABS.map(tab => [tab.id, tab]))
+
+/** 这条链路点亮哪些节点（`all` 是全部）。 */
+export function activeNodesOf(chain: GuideChainId): readonly NodeId[] {
+  return TAB_BY_ID.get(chain)?.nodes ?? NODE_ORDER
+}
+
+/**
+ * 这个环节属于哪条链路，供深链初始化和链路入口定位使用；点击节点时不自动切 Tab。
+ *
+ * 四个产品概念入口没有自己的链路，映射到它**内容上属于**的那条：
+ * 知识库 → 编译、记忆 → 记忆构建。智能归因与评测是产品概念入口，
+ * 不属于某一条运行链路，所以不切（保持当前筛选）。
+ */
+export function chainOfNode(id: GuideNodeId): GuideChainId | null {
+  for (const tab of GUIDE_CHAIN_TABS) {
+    if (tab.id !== 'all' && (tab.nodes as readonly string[]).includes(id)) return tab.id
+  }
+  if (id === 'knowledge') return 'compile'
+  if (id === 'memory') return 'memory'
+  return null
+}
+
+export function isGuideChainId(value: string | undefined): value is GuideChainId {
+  return value !== undefined && TAB_BY_ID.has(value as GuideChainId)
+}
+
+// ------------------------------------------------------------------ 连边
+
+/**
+ * 一条边的折线。**从 `arch/model.ts` 的几何推导，坐标不在这里另立一份**。
+ *
+ * 四条跨链路边里只有 `x3` 需要手工绕行（见 `arch/model.ts` 的 `CROSS_ROUTES` 那段：
+ * 它的最短路径会横穿两张卡片）。其余三条实测走在空处，这里给它们的正交折线
+ * 与那个「最短路径」的结论一致。
+ */
+function edgePath(edge: ArchEdge): string {
+  const source = boxOf(edge.source)
+  const target = boxOf(edge.target)
+  const rightward = target.x >= source.x
+  const start: [number, number] = [source.x + (rightward ? source.width / 2 : -source.width / 2), source.y]
+  const end: [number, number] = [target.x + (rightward ? -target.width / 2 : target.width / 2), target.y]
+
+  if (edge.id === 'x1') return `M ${start[0]} ${start[1]} H ${CANVAS_WIDTH - 25} V ${end[1]} H ${end[0]}`
+  if (edge.id === 'x2') return `M ${start[0]} ${start[1]} H ${GUTTER - 25} V ${end[1]} H ${end[0]}`
+  if (edge.id === 'x3') {
+    const gap = columnGapX(1)
+    const channel = laneGapY(0)
+    return `M ${start[0]} ${start[1]} H ${gap} V ${channel} H ${target.x} V ${end[1]} H ${end[0]}`
+  }
+  if (edge.id === 'x4') {
+    const gap = columnGapX(2)
+    const channel = laneGapY(0)
+    return `M ${start[0]} ${start[1]} H ${gap} V ${channel} H ${target.x} V ${end[1]} H ${end[0]}`
+  }
+  if (Math.abs(source.y - target.y) < 1) return `M ${start[0]} ${start[1]} H ${end[0]}`
+  const trunk = (start[0] + end[0]) / 2
+  return `M ${start[0]} ${start[1]} H ${trunk} V ${end[1]} H ${end[0]}`
+}
+
+/**
+ * 跨链路边标签的落点。**不能交给「弧长中点」**：那四条线的中点常常正好压在一张卡片上，
+ * 而标签带白底 —— 压上去就是把一张卡糊掉一块。所以四条各自给坐标（拱在通道里）。
+ */
+const EDGE_LABEL_POSITIONS: Record<string, { x: number; y: number }> = {
+  x1: { x: CANVAS_WIDTH - 96, y: laneCenter(2) },
+  x2: { x: GUTTER - 20, y: laneGapY(1) + 4 },
+  x3: { x: columnGapX(1) + 44, y: laneGapY(0) - 9 },
+  x4: { x: columnGapX(2) + 44, y: laneGapY(0) + 17 },
+}
+
+const EDGE_MARKER: Record<string, 'flow' | 'cross'> = { flow: 'flow', branch: 'flow', inject: 'cross', collect: 'cross', feedback: 'cross' }
+
+// ------------------------------------------------------------------ 视口
+
+/**
+ * 量视口的**宽与高**。
+ *
+ * 两个都要：宽决定「适应」能放多大（整图设计宽 1172），高决定它能缩到多小。
+ * 视口高度是 CSS 给的固定值，不随缩放变化 —— 见下面的「固定边框」。
+ */
+function useBoxSize(ref: { current: HTMLElement | null }): { width: number; height: number } {
+  const [size, setSize] = useState({ width: 0, height: 0 })
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return undefined
+    const update = (): void => setSize(previous => {
+      const next = { width: el.offsetWidth, height: el.offsetHeight }
+      return previous.width === next.width && previous.height === next.height ? previous : next
+    })
+    update()
+    if (typeof ResizeObserver === 'undefined') return undefined
+    const observer = new ResizeObserver(update)
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [ref])
+  return size
+}
+
+/** 说明页画布高度按三条运行链路计算。 */
+const GUIDE_CANVAS_HEIGHT = laneTop(NODE_LANES.length - 1) + BAND_H + BOTTOM
+
+export interface GuideArchitectureCanvasProps {
+  chain: GuideChainId
+  onChainChange: (chain: GuideChainId) => void
+  selected: GuideNodeId | null
+  onSelect: (id: GuideNodeId) => void
+  inspector?: ReactNode
+  onCloseInspector?: () => void
+}
+
+const ZOOM_MIN = 0.35
+const ZOOM_MAX = 2.4
+/**
+ * Inspector 在右侧占掉多少像素（宽度上限 380 + 右边距 12）。
+ * **写成常量而不是量出来**：量出来要等一帧，而「图往左让还是居中」是一帧都不许抖的排版决定。
+ */
+const INSPECTOR_WIDTH = 392
+/**
+ * 「适应」档的比例上限。取 0.96 而不是 1，是为了让 1172px 宽的整图和 380px 的 Inspector
+ * 在常见的 1440–1920 屏上**同时站得下** —— 顶到 1 就会让 Inspector 压住最右一列。
+ */
+const MAX_FIT_SCALE = 0.96
+/**
+ * 窄于这个宽度时，Inspector 不再是「右边的一栏」，而是**落到画布下面**（见 pages.css 的同名
+ * 容器查询）。两个数字必须相同：JS 用它决定要不要预留右栏，CSS 用它决定 Inspector 摆在哪里 ——
+ * 差一点就会出现「预留了但没东西占位」或者「没预留却被盖住」。
+ */
+const BESIDE_MIN_WIDTH = 1100
+/** 图与边框之间留的呼吸位。 */
+const FIT_MARGIN = 24
+
+export function GuideArchitectureCanvas({ chain, onChainChange, selected, onSelect, inspector, onCloseInspector }: GuideArchitectureCanvasProps): ReactNode {
+  const markerId = useId().replace(/[^a-zA-Z0-9_-]/g, '')
+  const viewport = useRef<HTMLDivElement>(null)
+  const box = useBoxSize(viewport)
+  /** `null` = 「适应」（整图缩进边框）；数字 = 用户自己捏出来/按出来的比例。Tab 切换不动它。 */
+  const [manualScale, setManualScale] = useState<number | null>(null)
+  const [isPanning, setIsPanning] = useState(false)
+  const panRef = useRef<{ pointerId: number; clientX: number; clientY: number; scrollLeft: number; scrollTop: number } | null>(null)
+  const zoomAnchorRef = useRef<{ screenX: number; screenY: number; worldX: number; worldY: number } | null>(null)
+
+  const active = new Set<string>(activeNodesOf(chain))
+  /** 有被点亮环节的那几条带。**带头也要跟着调淡**，否则空带的标题比它的内容还响。 */
+  const activeLanes = new Set(NODE_LANES.filter(lane => activeNodesOf(chain).some(id => NODE_META[id].lane === lane.id)).map(lane => lane.id))
+  /** `all` 不筛选；切换链路时，非当前链路的卡片降为次级。 */
+  const filtered = chain !== 'all'
+
+  const available = box.width > 0 ? box.width - 2 : CANVAS_WIDTH
+  const availableHeight = box.height > 0 ? box.height - 2 : GUIDE_CANVAS_HEIGHT
+  /**
+   * 「适应」= 整图缩进边框，**并且给 Inspector 留出它那一栏**。
+   *
+   * 留这一栏是「不遮挡」的唯一可靠做法：整图 1172px 宽，右列 380px，
+   * 两者在窄屏上本来就放不下；不留就一定会压住最右一列（召回 / 重排、用户交互），
+   * 而它们正是要对照着读的环节。
+   *
+   * 实测这不会造成开合 Inspector 时图「跳一下」：常见窗口高度下这一档本来就被高度卡住
+   * （≈0.88），留不留这一栏算出来是同一个数。
+   */
+  const besideInspector = inspector !== undefined && box.width >= BESIDE_MIN_WIDTH
+  const reserve = besideInspector ? INSPECTOR_WIDTH + 28 : FIT_MARGIN
+  const fitScale = Math.max(ZOOM_MIN, Math.min(
+    MAX_FIT_SCALE,
+    (available - reserve) / CANVAS_WIDTH,
+    (availableHeight - FIT_MARGIN) / GUIDE_CANVAS_HEIGHT,
+  ))
+  const scale = manualScale ?? fitScale
+
+  const boardWidth = CANVAS_WIDTH * scale
+  const boardHeight = GUIDE_CANVAS_HEIGHT * scale
+  /** Inspector 在右边时图靠左站（它那一栏已经预留出来了）；否则居中，放不下就贴左边。 */
+  const offsetX = besideInspector ? 14 : Math.max(0, (available - boardWidth) / 2)
+  const offsetY = Math.max(0, (availableHeight - boardHeight) / 2)
+
+  /** 捏合要按指针锚定，锚点计算读的是「这一帧」的比例与位移 —— 存一份给原生监听用。 */
+  const viewRef = useRef({ scale, offsetX, offsetY })
+  viewRef.current = { scale, offsetX, offsetY }
+  const pannable = boardWidth > available + 1 || boardHeight > availableHeight + 1
+
+  /**
+   * 触控板捏合缩放。**必须是原生的非被动监听**：React 的 `onWheel` 挂在根容器上、
+   * 而且是 passive 的 —— 在那里 `preventDefault()` 不生效，浏览器会顺手把整页也缩放掉，
+   * 表现就是「一捏，页面和画布一起变大」。
+   *
+   * 触控板捏合在浏览器里的约定是「带 `ctrlKey` 的 wheel 事件」，所以这里只接管那一种；
+   * **普通两指滚动一概不碰**，交给容器自己滚（滚到头会继续滚页面）。
+   */
+  useEffect(() => {
+    const el = viewport.current
+    if (!el) return undefined
+    const onWheel = (event: WheelEvent): void => {
+      if (!event.ctrlKey && !event.metaKey) return
+      event.preventDefault()
+      const current = viewRef.current
+      const rect = el.getBoundingClientRect()
+      const screenX = event.clientX - rect.left
+      const screenY = event.clientY - rect.top
+      const worldX = (screenX + el.scrollLeft - current.offsetX) / current.scale
+      const worldY = (screenY + el.scrollTop - current.offsetY) / current.scale
+      // 单次最多放 1.38 倍：捏合会连发事件，一次跳太多会晕。
+      const delta = Math.max(-40, Math.min(40, event.deltaY))
+      const next = Math.max(ZOOM_MIN, Math.min(ZOOM_MAX, current.scale * Math.exp(-delta * 0.008)))
+      if (Math.abs(next - current.scale) < 0.0005) return
+      zoomAnchorRef.current = { screenX, screenY, worldX, worldY }
+      setManualScale(next)
+    }
+    el.addEventListener('wheel', onWheel, { passive: false })
+    return () => el.removeEventListener('wheel', onWheel)
+  }, [])
+
+  /** 缩放以后，把锚点下的画布坐标移回原来的屏幕位置 —— 不然放大时图会从指针底下跑掉。 */
+  useLayoutEffect(() => {
+    const el = viewport.current
+    const anchor = zoomAnchorRef.current
+    if (!el || !anchor) return
+    const nextOffsetX = besideInspector ? 14 : Math.max(0, (available - CANVAS_WIDTH * scale) / 2)
+    const nextOffsetY = Math.max(0, (availableHeight - GUIDE_CANVAS_HEIGHT * scale) / 2)
+    const nextScrollLeft = nextOffsetX + anchor.worldX * scale - anchor.screenX
+    const nextScrollTop = nextOffsetY + anchor.worldY * scale - anchor.screenY
+    const maxScrollLeft = Math.max(0, el.scrollWidth - el.clientWidth)
+    const maxScrollTop = Math.max(0, el.scrollHeight - el.clientHeight)
+    el.scrollLeft = Math.max(0, Math.min(maxScrollLeft, nextScrollLeft))
+    el.scrollTop = Math.max(0, Math.min(maxScrollTop, nextScrollTop))
+    zoomAnchorRef.current = null
+  }, [available, availableHeight, besideInspector, scale])
+
+  const beginPan = (event: ReactPointerEvent<HTMLDivElement>): void => {
+    // **左键在空白处拖就平移**，中键同理；落点在卡片上时不抢 —— 那一下是「选中这个环节」。
+    // 不占用空格键：那是整页翻页的键，画布没有资格把它拿走。
+    const onCard = event.target instanceof Element && event.target.closest('.tabGuideCard') !== null
+    const allowed = event.button === 1 || (event.button === 0 && !onCard)
+    if (!allowed) return
+    const el = event.currentTarget
+    event.preventDefault()
+    el.setPointerCapture(event.pointerId)
+    panRef.current = { pointerId: event.pointerId, clientX: event.clientX, clientY: event.clientY, scrollLeft: el.scrollLeft, scrollTop: el.scrollTop }
+    setIsPanning(true)
+  }
+
+  const movePan = (event: ReactPointerEvent<HTMLDivElement>): void => {
+    const el = event.currentTarget
+    const pan = panRef.current
+    if (!pan || pan.pointerId !== event.pointerId) return
+    event.preventDefault()
+    el.scrollLeft = pan.scrollLeft - (event.clientX - pan.clientX)
+    el.scrollTop = pan.scrollTop - (event.clientY - pan.clientY)
+  }
+
+  const endPan = (event: ReactPointerEvent<HTMLDivElement>): void => {
+    const pan = panRef.current
+    if (!pan || pan.pointerId !== event.pointerId) return
+    if (event.currentTarget.hasPointerCapture(event.pointerId)) event.currentTarget.releasePointerCapture(event.pointerId)
+    panRef.current = null
+    setIsPanning(false)
+  }
+
+  return <section className="tabGuideCanvas" aria-label="TitaAgent 完整架构图">
+    {/* 画布上只有一个浮层：左上角的链路 Tab。**右上角不再放任何控件** ——
+        缩放是一条触控板手势，全屏交给浏览器自己的键；两个按钮只是把画布切掉一角。 */}
+    <div className="tabGuideCanvasOverlay">
+      <Tabs className="tabGuideChainTabs" value={chain} onValueChange={value => {
+        if (isGuideChainId(value)) onChainChange(value)
+      }}>
+        <TabsList aria-label="按链路筛选架构图">
+          {GUIDE_CHAIN_TABS.map(tab => <TabsTrigger key={tab.id} value={tab.id} title={tab.note}>{tab.label}</TabsTrigger>)}
+        </TabsList>
+      </Tabs>
+    </div>
+
+    {/* **固定边框**：高度由 CSS 给，不跟缩放走 —— 缩放只动框里的内容。
+        滚轮捏合由原生监听接管（见上），所以这里没有 onWheel。 */}
+    <div className={cn('tabGuideCanvasViewport', isPanning && 'tabGuideCanvasViewportPanning')}
+      data-pannable={pannable ? 'true' : undefined} ref={viewport}
+      onPointerDown={beginPan} onPointerMove={movePan} onPointerUp={endPan} onPointerCancel={endPan}>
+      <div className="tabGuideCanvasFrame" style={{ width: boardWidth, height: boardHeight, left: offsetX, top: offsetY }}>
+        <div className="tabGuideCanvasBoard" style={{ width: CANVAS_WIDTH, height: GUIDE_CANVAS_HEIGHT, transform: `scale(${scale})` }}>
+          <svg className="tabGuideBoardEdges" width={CANVAS_WIDTH} height={GUIDE_CANVAS_HEIGHT}
+            viewBox={`0 0 ${CANVAS_WIDTH} ${GUIDE_CANVAS_HEIGHT}`} aria-hidden="true">
+            <defs>
+              <marker id={`${markerId}-flow`} markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto" markerUnits="strokeWidth">
+                <path d="M0 0 L8 4 L0 8 Z" fill={EDGE_STYLE.flow.stroke} />
+              </marker>
+              <marker id={`${markerId}-cross`} markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto" markerUnits="strokeWidth">
+                <path d="M0 0 L8 4 L0 8 Z" fill={EDGE_STYLE.inject.stroke} />
+              </marker>
+            </defs>
+
+            {NODE_LANES.map((lane, index) => {
+              const on = !filtered || activeLanes.has(lane.id)
+              return <g key={lane.id}>
+                <rect className="tabGuideBoardBand" x="14" y={laneTop(index)} width={CANVAS_WIDTH - 28} height={BAND_H} rx="10" />
+                <g className="tabGuideBoardLaneHead" style={{ opacity: on ? 1 : 0.32 }}>
+                <rect className={cn('tabGuideBoardLaneBadge', `tabGuideBoardLaneBadge-${lane.id}`)}
+                  x={GUTTER} y={laneTop(index) + 7} width={LANE_HEAD_W} height={LANE_HEAD_H - 12} rx="5" />
+                <text className="tabGuideBoardLaneLabel" x={GUTTER + 10} y={laneTop(index) + 20}>{`${lane.index} · ${lane.title}`}</text>
+                {/* 走向与逐带计数跟在带名后面，**不放到画布右边缘**：窄链路裁到三列时，
+                    右边缘在视野之外，那里的字一行都看不见。
+                    计数用 `tspan` 顺排，不靠估算字宽 —— 中英混排的字宽估不准，
+                    估错的后果是两段字压在一起（第一版就是这样）。 */}
+                <text className="tabGuideBoardLaneNote" x={GUTTER + LANE_HEAD_W + 14} y={laneTop(index) + 20}>{lane.note}</text>
+                </g>
+              </g>
+            })}
+
+            {ARCH_EDGES.map(edge => {
+              const style = EDGE_STYLE[edge.kind]
+              const on = !filtered || (active.has(edge.source) && active.has(edge.target))
+              return <path key={edge.id} className="tabGuideBoardEdge" d={edgePath(edge)}
+                style={{ stroke: style.stroke, strokeWidth: style.lineWidth, strokeDasharray: style.lineDash?.join(' '), opacity: on ? 0.9 : 0.1 }}
+                markerEnd={`url(#${markerId}-${EDGE_MARKER[edge.kind]})`} />
+            })}
+            {ARCH_EDGES.map(edge => {
+              const at = EDGE_LABEL_POSITIONS[edge.id]
+              if (!edge.label || !at) return null
+              const on = !filtered || (active.has(edge.source) && active.has(edge.target))
+              return <text key={`${edge.id}-label`} className="tabGuideBoardEdgeLabel" x={at.x} y={at.y} style={{ opacity: on ? 1 : 0.14 }}>{edge.label}</text>
+            })}
+          </svg>
+
+          {NODE_ORDER.map(id => <NodeCard key={id} id={id}
+            selected={selected === id} active={!filtered || active.has(id)} showSteps={filtered && active.has(id)}
+            onSelect={onSelect} />)}
+
+        </div>
+      </div>
+    </div>
+    {inspector && <aside className="tabGuideInspector" aria-label="节点详细信息">
+      <div className="tabGuideInspectorHeader">
+        <div className="tabGuideInspectorHeaderCopy">
+          <span>当前选中</span>
+          <strong>节点详细信息</strong>
+        </div>
+        {onCloseInspector && <Button variant="ghost" size="icon" aria-label="关闭节点详细信息" title="关闭"
+          onClick={onCloseInspector}><X size={14} aria-hidden="true" /></Button>}
+      </div>
+      <div className="tabGuideInspectorBody">{inspector}</div>
+    </aside>}
+  </section>
+}
+
+/** 步骤的三档状态：一枚小方块，颜色与右侧详情里的图标同源。 */
+const STEP_TONE: Record<string, string> = { done: 'done', partial: 'partial', todo: 'todo' }
+
+/**
+ * 一张环节卡片：**标题行 + 编号步骤表**。
+ *
+ * 步骤是这张卡的全部理由 —— 用户切到一条链路，要的就是「它分几步做」。
+ * 所以步骤**编号**而不是打点：编号说明顺序，而顺序正是链路的意思。
+ *
+ * 行数由**卡片自己的高度**决定（坐标是 `arch/model.ts` 给的，有 96 / 80 / 52 三档），
+ * 而不是写死一个数字 —— 换掉任一条高度常量，这里的正文会跟着变。
+ */
+function NodeCard({ id, selected, active, showSteps, onSelect }: {
+  id: NodeId
+  selected: boolean
+  active: boolean
+  showSteps: boolean
+  onSelect: (id: GuideNodeId) => void
+}): ReactNode {
+  const meta = NODE_META[id]
+  const box = boxOf(id)
+  const lane = LANE_PALETTE[meta.lane]
+  const lineHeight = 13.5
+  /**
+   * 能排下几行步骤。**收尾那一行要占一行**：装不下时先让出「还有 N 步」的位置，
+   * 而不是先把步骤排满、再让收尾那行溢出卡片底边（第一版只差 1px 就压到边上）。
+   */
+  const capacity = Math.max(1, Math.floor((box.height - 19 - 17 - 5) / lineHeight))
+  const truncated = showSteps && meta.steps.length > capacity
+  const shown: NodeStep[] = showSteps ? meta.steps.slice(0, truncated ? capacity - 1 : capacity) : []
+  const rest = showSteps ? meta.steps.length - shown.length : 0
+
+  return <button
+    type="button"
+    className={cn('tabGuideCard', selected && 'tabGuideCardSelected', !active && 'tabGuideCardDim')}
+    style={{ left: box.x - box.width / 2, top: box.y - box.height / 2, width: box.width, height: box.height }}
+    aria-pressed={selected}
+    title={`${meta.title}（${NODE_STATUS_LABEL[meta.status]}）—— ${meta.statusNote}`}
+    onClick={() => onSelect(id)}
+  >
+    <span className="tabGuideCardHead">
+      <i className="tabGuideCardDot" style={{ background: lane.accent }} aria-hidden="true" />
+      <strong className="tabGuideCardTitle">{meta.shortTitle ?? meta.title}</strong>
+    </span>
+    {showSteps
+      ? <span className="tabGuideCardSteps">
+        {shown.map((step, index) => <span key={step.label} className="tabGuideCardStep" data-state={STEP_TONE[step.state ?? 'done']}>
+          <i aria-hidden="true">{index + 1}</i>{step.label}
+        </span>)}
+        {rest > 0 && <span className="tabGuideCardStep tabGuideCardStepRest">还有 {rest} 步在右侧</span>}
+      </span>
+      : <span className="tabGuideCardSub" style={{ WebkitLineClamp: Math.max(1, Math.floor((box.height - 19 - 17 - 5) / 15)) }}>{meta.subtitle}</span>}
+  </button>
+}

package/src/client/ImportFilesDialog.tsx

@@ -31,7 +31,7 @@ import { AlertCircle, Check, FileText, RefreshCw, Trash2, Upload, X } from '@tit
 import { Button, cn } from '@tita-agent/ui/components'
 import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from '@tita-agent/ui/overlays'
 import { styles } from './styles.ts'
-import { COMPILE_STEP_TITLE, type CompileProgressView } from './CompileDialogs.tsx'
+import { COMPILE_STEP_TITLE, compileRatio, type CompileProgressView } from './CompileDialogs.tsx'
 import type { ImportSummaryView } from './KnowledgeBaseTab.tsx'
 
 /** 一个文件在这一趟里走到哪了。**两段**（转 → 入库），编译那一段是整批共用的。 */
@@ -168,7 +168,7 @@ export function ImportFilesDialog({
 
         {compileProgress !== null && <>
           <div className={cn(styles.compileBar, styles.importBar)}>
-            <span style={{ inlineSize: `${ratioOf(compileProgress)}%` }} />
+            <span style={{ inlineSize: `${Math.round(compileRatio(compileProgress) * 100)}%` }} />
           </div>
           {/* 五段与编译弹窗、SourceRaw 抽取轨迹共用同一套名称和状态。
               这里回答的是「整批到哪了」，但不能再画成另一套不对应的步骤。 */}
@@ -318,14 +318,3 @@ function CompileStage({ title, note, children }: { title: string; note: string;
     <p className={styles.importStageBody}>{children}</p>
   </div>
 }
-
-/** 与编译对话框同一条算法：按阶段均分，正在跑的那一段再按文档数细分。 */
-function ratioOf(progress: CompileProgressView): number {
-  if (progress.finishedAt !== undefined) return 100
-  const total = progress.steps.length || 1
-  const done = progress.steps.filter(step => step.state === 'done').length
-  const running = progress.steps.find(step => step.state === 'running')
-  if (running === undefined) return Math.round((done / total) * 100)
-  const inner = running.id === 'knowledge' && progress.sourcesTotal > 0 ? progress.sourcesDone / progress.sourcesTotal : 0.5
-  return Math.min(99, Math.round(((done + inner) / total) * 100))
-}

package/src/client/IntentLogic.tsx

@@ -35,7 +35,7 @@ const RECORD_FIELDS: FieldDoc[] = [
   { name: 'refs', required: false, meaning: '引用了哪些对象（表、文档、指标），形如 { id, kind, label }。', where: '模型抽取' },
   { name: 'relation', required: true, meaning: '这轮与已有任务的关系：new_task（开新任务）/ subtask_of（续已有任务）/ unknown。', where: '模型判断，Host 校验 task 是否存在' },
   { name: 'lineage', required: true, meaning: 'intentId / taskId / subtaskId / runId 四个 id 的链路，下游工具与产物靠它回溯。', where: 'Host 分配，模型可显式续接' },
-  { name: 'source', required: true, meaning: 'model = 模型记录；fallback = 轮次结束模型没记，Host 补的一条 unknown。', where: 'Host 标记' },
+  { name: 'source', required: true, meaning: 'model = 模型记录；fallback = 数据轮次结束模型没记，Host 补的一条 unknown。', where: 'Host 标记' },
 ]
 
 interface Paper {
@@ -110,7 +110,7 @@ export function IntentLogic(): ReactNode {
       <ul className={styles.intentDocList}>
         <li><b>判断完全交给大模型。</b>`intent_record` 只把模型给出的结论落成一条记录，不做关键词匹配、不做状态机、不反问、不阻断当前请求，也不会因为分类错了就让请求失败。</li>
         <li><b>记录不驱动控制流。</b>它服务三件事：事后回溯（这轮到底想干什么）、链路串联（下游工具与产物继承 taskId / subtaskId）、质量观测（哪些轮次低置信度、哪些落到了 unknown）。</li>
-        <li><b>模型漏了也不丢。</b>轮次结束时如果没有任何记录，Host 补一条 <code>source: fallback</code> 的 unknown，保证"每轮一条"这个不变式成立。</li>
+        <li><b>数据轮次漏了也不丢。</b>只有进入数据 / 知识域的轮次才需要记录；如果模型漏记，Host 补一条 <code>source: fallback</code> 的 unknown。普通 Agent 和闲聊不会生成意图记录。</li>
       </ul>
     </Section>