dsh-data-domain-knowledge 0.1.0-alpha.2 → 0.1.0-alpha.3

package/src/client/attribution/AttributionTab.tsx

@@ -1,7 +1,7 @@
 import {
-  GitBranch, History, Stethoscope, X,
+  Database, GitBranch, History, Sparkles, Stethoscope, X,
 } from '@tita-data-agent/ui/icons'
-import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
 import { createPortal } from 'react-dom'
 import { Button } from '@tita-data-agent/ui/components'
 import { AttributionGraph } from './AttributionGraph.tsx'
@@ -10,15 +10,36 @@ import { GraphStage } from './GraphStage.tsx'
 import { RunView } from './RunView.tsx'
 import { ViewSwitch, type ViewSwitchItem } from './ViewSwitch.tsx'
 import {
-  FilterBar, LegendBody, LegendToggle, NodeDetailCard, StatsStrip, ToolPill, ToolRail,
+  FilterBar, LegendBody, NodeDetailCard, OperationsRail, ReadBar, StatsStrip, ToolPill,
 } from './StageChrome.tsx'
 import type { GraphLayout } from './graph-options.ts'
 import {
-  candidatesOf, defaultFocusId, EMPTY_FILTER, filterGraph, gapHypothesisIds,
-  neighborhoodOf, summarize, symptomCountByProblemClass,
-  type AttributionGraphData, type AttributionNodeKind, type FailureMode, type ProblemClassId,
+  CHECK_COST_BANDS, EMPTY_FILTER, EMPTY_GRAPH, FILTERABLE_KINDS, LANES, PROBLEM_CLASSES,
+  candidatesOf, chainOf, defaultChainStart, defaultFocusId, filterGraph, gapHypothesisIds, laneKindVisible,
+  laneSegments, narrowedToLanes, neighborhoodOf, summarize, symptomCountByProblemClass,
+  type AttributionCase, type AttributionGraphData, type AttributionNodeKind, type FailureReason,
+  type LaneId, type ProblemClassId,
 } from './model.ts'
-import { SEED_CASES, SEED_GRAPH } from '../../diagnosis/seed.js'
+
+/** 一次载入的结果。空库也是一种正常结果，所以它不是错误分支。 */
+interface DiagnosisPayload {
+  graph?: AttributionGraphData
+  cases?: AttributionCase[]
+  source?: string
+  migrated?: boolean
+  problems?: string[]
+  /** 这个库还什么都没有 —— 空态可以「载入内置示例」。 */
+  canLoadSample?: boolean
+  /** 待人确认的卡片提议条数（§7.1）。归因侧只挂角标，review 在「知识库 → Wiki」。 */
+  proposals?: { pending: number; rejected: number; confirmed: number }
+}
+
+/** 服务端的三种来源 → 徽标上那句人话。 */
+function sourceLabelOf(source: string | undefined): string {
+  if (source === 'cards') return '02_wiki/diagnosis'
+  if (source === 'jsonl') return '05_diagnosis（旧格式）'
+  return '还没有排查知识'
+}
 
 type SubView = 'graph' | 'case' | 'run'
 
@@ -30,71 +51,203 @@ type SubView = 'graph' | 'case' | 'run'
  * 全部从「图谱的兄弟节点」改成「浮在画布上的四条边」：画布吃掉全部高度，控件
  * 叠在它上面。视觉结果就是「打开之后就是一张大图」。
  *
+ * **v1.4 起默认读法是动线视角**（§7.2 / §7.7）：五段泳道 + 点亮一条链。
+ * 理由不是审美 —— 力导向回答「这张图长什么样」（维护者的问题），而值班同学打开
+ * 这一栏问的是「下一步查什么」。默认要服务提问更多的那个角色；想看形状时切「关系」，
+ * 一步操作。
+ *
  * 三条读法各自回答一个问题（图谱=结构、案例=路径、排查=剪枝），它们是同一画框里
- * 的三层内容，由顶部的分段切换换页 —— 切换器本身也浮在同一个框里，所以**全屏时
- * 它天然跟着一起上去**，不需要为全屏再抄一份控件。
+ * 的三层内容，由顶部的分段切换换页 —— 切换器在**画框之外**（页面级控件），
+ * 所以全屏时它天然跟着一起上去，不需要为全屏再抄一份控件。
  *
- * 另外两个开关各自回答一个不同的问题：
- * - **布局**：`力导向` 回答「这张图长什么样」（浮动、可拖、靠聚簇表达关系）；
- *   `分层` 回答「谁是上游」（现象→假设→检查 的方向被显式画出来）。
- * - **筛选**：按类型 / 失败模式 / 文本收窄。它是**切面**而不是树的一层 ——
- *   可以多选、可以为空、随时能改回看全图，不会像层级那样「选错就得往回退」。
+ * 四角分区（§7.1）：
+ * - 画布左上 = 操作（四组按动线顺序）；右上 = 读法（四个开关同排）；
+ *   左下 = 读数（统计 + 来源）；底中 = 搜索；右侧 = 图例正文 / 节点详情。
  */
-export function AttributionTab({ visible }: { visible: boolean }): ReactNode {
+export function AttributionTab({ visible, onOpenKnowledge }: {
+  visible: boolean
+  /**
+   * 切到「知识库」那一栏。空态的主操作要用它 —— 排查知识是从来源与卡片编译来的，
+   * 空的时候该把人送去**录知识的那一栏**，而不是让人在这一栏里等。
+   */
+  onOpenKnowledge?: () => void
+}): ReactNode {
   const [subView, setSubView] = useState<SubView>('graph')
-  const [layout, setLayout] = useState<GraphLayout>('force')
+  /** 默认动线：它是 §7.2 定的默认读法。 */
+  const [layout, setLayout] = useState<GraphLayout>('line')
   const [overview, setOverview] = useState(true)
-  const [focusId, setFocusId] = useState<string | undefined>(() => defaultFocusId(SEED_GRAPH))
-  const [activeCase, setActiveCase] = useState('CASE-001')
+  const [focusId, setFocusId] = useState<string | undefined>(undefined)
+  /**
+   * 被点亮的那条链的起点。
+   *
+   * 与 `focusId` **分开**：`focusId` 是「聚焦哪个节点的邻域」（默认落在度数最高的
+   * 假设上，打开这一栏就该看到最粗的那个结）；`selectedId` 是「点亮谁的链」。
+   *
+   * **它现在默认落在①段的第一个现象上。** 上一版默认是空的，理由是「一进来就压暗
+   * 半张图，等于把全景变成需要用户先学会退出」—— 那条理由在真机上被否掉了：3 个现象
+   * 共享 7 个假设，14 条 `may_be_caused_by` 交叉成一片，而§7.4 第 9 条本来就写着
+   * 「路径高亮是**默认读法**，不是附加功能」。默认空着，等于这条读法默认没生效。
+   *
+   * 代价仍然存在，所以出口必须明显：**点空白即取消**，而且取消之后不再被自动改回来
+   * （见 `pickedDefault`）。
+   */
+  const [selectedId, setSelectedId] = useState<string | undefined>(undefined)
+  /**
+   * 动线视角的**当前现象**：①段只画它，其余现象进段头的切换入口。
+   *
+   * 收窄到一个是必须的：3 个现象共享 7 个假设（§4.5），①→② 之间因此有 14 条
+   * `may_be_caused_by` 互相交叉 —— 交叉的成因是「有三个起点」。只留一个之后，
+   * 那 7 条线从一个点扇出，而画布上剩下的每一条边**都真实属于这个现象**。
+   *
+   * 代价：「三个现象共享同一批假设」在动线视角里看不到了，它在关系视图里照旧。
+   * 动线回答的是「这个现象的下一步」，那本来就是一个现象的事（§4.6）。
+   */
+  const [laneSymptomId, setLaneSymptomId] = useState<string | undefined>(undefined)
+  /**
+   * 已经替用户预置过一次焦点了吗？
+   *
+   * 预置只在**第一次拿到非空数据**时发生。少了这个闸，每次重载（载入示例、重建之后
+   * 刷新）都会把用户手动取消掉的焦点重新按回去 —— 那就是在跟用户抢方向盘。
+   */
+  const pickedDefault = useRef(false)
+  const [activeCase, setActiveCase] = useState('')
   const [full, setFull] = useState(false)
-  const [railOpen, setRailOpen] = useState(true)
+  /** 左栏：面板态默认收起成 pill（380px 塞不下四组控件 + 五段泳道，§7.7 末段）。 */
+  const [railOpen, setRailOpen] = useState(false)
   const [legendOpen, setLegendOpen] = useState(false)
-  const [data, setData] = useState<AttributionGraphData>(SEED_GRAPH)
+  /** ⑤ 段（实例层）默认折叠；用户展开过就记住。 */
+  const [instanceOpen, setInstanceOpen] = useState(false)
+  /**
+   * 图与案例都**从服务端来**，初始值是空的。
+   *
+   * 这里原来是 `useState(SEED_GRAPH)`：服务端还没答话时画的就是内置示例，
+   * 而它和「你的库真有 34 个节点」在屏幕上长得一样。现在初始值 `EMPTY_GRAPH`，
+   * 示例只在用户明确点了「载入内置示例」之后才出现（那时它已经是库里的真卡片了）。
+   */
+  const [data, setData] = useState<AttributionGraphData>(EMPTY_GRAPH)
+  const [cases, setCases] = useState<AttributionCase[]>([])
+  const [phase, setPhase] = useState<'loading' | 'ready' | 'error'>('loading')
+  /** 空库：可以载入内置示例。 */
+  const [canLoadSample, setCanLoadSample] = useState(false)
+  /**
+   * 待人确认的提议条数。它随图一起从 `/diagnosis/graph` 来（同一个响应体），
+   * 不另开一路请求 —— 两个数字来自同一次读取，界面上不可能互相矛盾。
+   */
+  const [pendingProposals, setPendingProposals] = useState(0)
+  const [sampleBusy, setSampleBusy] = useState(false)
+  const [sampleError, setSampleError] = useState<string | null>(null)
+  /** 载入成功之后的一句话说明：写进去的是什么、写在哪、能不能改。 */
+  const [sampleNotice, setSampleNotice] = useState<string | null>(null)
   /**
    * 宿主返回的**来源状态**。
    *
-   * 三种形态的可信度不同，必须分开显示：卡片是当前真相；`05_diagnosis` 旧格式意味着迁移
-   * 没能无损生效（有人手工加的边或孤立的资产节点会让它放弃迁移）；`seed 数据` 是宿主没就绪
-   * 时的兜底示例。`problems` 一并显示 —— 写卡片失败、迁移分歧都属于「不能只进日志」的信息。
+   * 两种形态的可信度不同，必须分开显示：卡片是当前真相；`05_diagnosis` 旧格式意味着迁移
+   * 没能无损生效（有人手工加的边或孤立的资产节点会让它放弃迁移）。`problems` 一并显示
+   * —— 写卡片失败、迁移分歧都属于「不能只进日志」的信息。
    */
   const [remote, setRemote] = useState<{ source: string; problems: string[] } | undefined>(undefined)
   const [resetToken, setResetToken] = useState(0)
   const [query, setQuery] = useState('')
+  /** 段（= 节点种类）切面。它就是「类型切面」的归位处（§7.3）。 */
   const [kinds, setKinds] = useState<ReadonlySet<AttributionNodeKind>>(new Set())
-  const [modes, setModes] = useState<ReadonlySet<FailureMode>>(new Set())
+  const [modes, setModes] = useState<ReadonlySet<FailureReason>>(new Set())
   const [problems, setProblems] = useState<ReadonlySet<ProblemClassId>>(new Set())
+  const [subclasses, setSubclasses] = useState<ReadonlySet<string>>(new Set())
+  const [gapOnly, setGapOnly] = useState(false)
+  const [costBands, setCostBands] = useState<ReadonlySet<string>>(new Set())
+  const [automations, setAutomations] = useState<ReadonlySet<string>>(new Set())
   const [includeNeighbors, setIncludeNeighbors] = useState(true)
-  const [symptomId, setSymptomId] = useState('S1')
+  const [symptomId, setSymptomId] = useState('')
+  /** 段头读数由画布回报（它才知道折叠后实际画了几个）。 */
+  /**
+   * 被**收起**的段。默认收起 ④ 查询依据。
+   *
+   * 判据是「它在这个布局里是不是决策对象」：④ 装的是引用层的资产（§0.1「只作定位
+   * 锚点」），动线要回答的是「下一步查什么」。而它在面板里要占掉 5 个节点 + 11 条
+   * 跨段边 —— 默认铺开时非空段是 4 段，每段的节点被压到几乎读不出字。
+   * 收起它之后非空段降到 3 段，节点明显变大，而「这条链到底要查什么」在点亮那条链
+   * 时照样展开（§7.7 末段的那条例外）。
+   */
+  const [collapsedLanes, setCollapsedLanes] = useState<ReadonlySet<LaneId>>(new Set<LaneId>(['asset']))
+  const [laneCounts, setLaneCounts] = useState<Record<LaneId, { shown: number; total: number }>>({
+    symptom: { shown: 0, total: 0 },
+    hypothesis: { shown: 0, total: 0 },
+    check_point: { shown: 0, total: 0 },
+    asset: { shown: 0, total: 0 },
+    instance: { shown: 0, total: 0 },
+  })
+
+  /** 把一次 `/diagnosis/graph` 的结果落进界面。空库也走这里 —— 它不是错误分支。 */
+  const applyPayload = useCallback((payload: DiagnosisPayload): void => {
+    const graph = payload.graph ?? EMPTY_GRAPH
+    const safe = Array.isArray(graph.nodes) && Array.isArray(graph.edges) ? graph : EMPTY_GRAPH
+    setData(safe)
+    // 默认聚焦度数最高的假设：打开这一栏就该看到「这张图里最粗的那个结」是什么，
+    // 而不是一块什么都没有的画布。空图时是 undefined，画布保持干净。
+    setFocusId(defaultFocusId(safe))
+    setCases(payload.cases ?? [])
+    setCanLoadSample(payload.canLoadSample === true)
+    setPendingProposals(payload.proposals?.pending ?? 0)
+    // 默认点亮①段第一个现象的那条链（§7.4 第 9 条）。只在第一次拿到非空数据时做一次：
+    // 之后用户取消过就保持取消，重载不把它按回去。
+    if (!pickedDefault.current) {
+      const start = defaultChainStart(safe)
+      if (start) { pickedDefault.current = true; setLaneSymptomId(start); setSelectedId(start) }
+    }
+    const troubles = payload.problems ?? []
+    setRemote({
+      source: sourceLabelOf(payload.source),
+      // 迁移成功也是信息：它说明这个知识根刚从旧格式换过来。
+      problems: payload.migrated ? [...troubles, '本次已把 05_diagnosis 的知识迁移为 wiki 卡片'] : troubles,
+    })
+  }, [])
 
-  // `/diagnosis/graph`：宿主已实现这条路由（05_diagnosis）。拿不到就静默回落到 seed，
-  // 并在界面上写明来源 ——「有没有真实数据」必须可见，不能靠猜。
+  /**
+   * 读一次 `/diagnosis/graph`。**这条路由只读不写** —— 「载入内置示例」是另一次显式 POST。
+   *
+   * 拿不到就当读失败如实说，不再回落到内置示例：兜底示例会让人把「宿主没答话」看成
+   * 「我的库里有 34 个节点」，而这正是这一栏最不该让人猜的地方。
+   */
+  const [reloadToken, setReloadToken] = useState(0)
   useEffect(() => {
-    if (!visible) return
+    if (!visible) return undefined
     let cancelled = false
+    setPhase('loading')
     void (async () => {
       try {
         const response = await fetch('/diagnosis/graph')
-        if (!response.ok) return
-        const payload = await response.json() as {
-          data?: { graph?: AttributionGraphData; source?: string; migrated?: boolean; problems?: string[] }
-        } & AttributionGraphData
-        const graph = payload.data?.graph ?? payload
-        if (!cancelled && Array.isArray(graph.nodes) && graph.nodes.length > 0) {
-          setData(graph)
-          const source = payload.data?.source
-          const problems = payload.data?.problems ?? []
-          setRemote({
-            source: source === 'cards' ? '02_wiki/diagnosis'
-              : source === 'jsonl' ? '05_diagnosis（旧格式）'
-                : '05_diagnosis',
-            // 迁移成功也是信息：它说明这个知识根刚从旧格式换过来。
-            problems: payload.data?.migrated ? [...problems, '本次已把 05_diagnosis 的知识迁移为 wiki 卡片'] : problems,
-          })
-        }
-      } catch { /* 宿主未就绪：保留 seed。 */ }
+        if (!response.ok) throw new Error(`HTTP ${response.status}`)
+        const body = await response.json() as { data?: DiagnosisPayload }
+        if (cancelled) return
+        applyPayload(body.data ?? {})
+        setPhase('ready')
+      } catch {
+        if (!cancelled) setPhase('error')
+      }
     })()
     return () => { cancelled = true }
-  }, [visible])
+  }, [visible, reloadToken, applyPayload])
+
+  /**
+   * 载入内置示例：**显式的一次写**，写进的是这个库自己的 `01_source_truth/` 与 `02_wiki/`。
+   *
+   * 载完重新读一次，让图、案例、来源徽标全部换成真实数据 —— 载入之后它们就是普通卡片，
+   * 可以照常改、照常删，所以说明里必须把这件事讲清楚。
+   */
+  const loadSample = async (): Promise<void> => {
+    setSampleBusy(true); setSampleError(null)
+    try {
+      const response = await fetch('/diagnosis/sample', { method: 'POST' })
+      const body = await response.json() as { ok?: boolean; data?: DiagnosisPayload; error?: { message?: string } }
+      if (!response.ok || body.ok === false) throw new Error(body.error?.message ?? `HTTP ${response.status}`)
+      applyPayload(body.data ?? {})
+      setSampleNotice('已载入内置示例：4 份来源写进 01_source_truth/，26 张卡片写进 02_wiki/diagnosis/。它们就是普通来源与卡片，可以照常改或删。')
+    } catch (error) {
+      setSampleError(error instanceof Error ? error.message : String(error))
+    } finally {
+      setSampleBusy(false)
+    }
+  }
 
   /**
    * 全屏期间锁住宿主页面的滚动。
@@ -116,48 +269,145 @@ export function AttributionTab({ visible }: { visible: boolean }): ReactNode {
   }, [full])
 
   const filter = useMemo(
-    () => ({ ...EMPTY_FILTER, query, kinds, failureModes: modes, problemClasses: problems, includeNeighbors }),
-    [query, kinds, modes, problems, includeNeighbors],
+    () => ({
+      ...EMPTY_FILTER, query, kinds, failureReasons: modes, problemClasses: problems,
+      problemSubclasses: subclasses, gapOnly, includeNeighbors,
+    }),
+    [query, kinds, modes, problems, subclasses, gapOnly, includeNeighbors],
   )
   const filtered = useMemo(() => filterGraph(data, filter), [data, filter])
   const gapIds = useMemo(() => new Set(gapHypothesisIds(filtered)), [filtered])
   const stats = useMemo(() => summarize(filtered), [filtered])
-  const candidateCount = useMemo(() => candidatesOf(data, symptomId).length, [data, symptomId])
   const symptomCounts = useMemo(() => symptomCountByProblemClass(data.nodes), [data])
   const symptoms = useMemo(() => data.nodes.filter(node => node.kind === 'symptom'), [data])
+  /**
+   * 当前选中的现象。**推导而不是存两份**：`symptomId` 的初值是空串，因为只有服务端
+   * 才知道这个库有哪几个现象 —— 换库、载入示例之后，原来那个 id 可能根本不存在，
+   * 而 `candidatesOf(data, '不存在的 id')` 会安静地返回空列表，看起来像「这个现象没有候选」。
+   */
+  const activeSymptomId = symptoms.some(node => node.id === symptomId) ? symptomId : (symptoms[0]?.id ?? '')
+  const candidateCount = useMemo(() => candidatesOf(data, activeSymptomId).length, [data, activeSymptomId])
+
+  /**
+   * 被点亮的那条链上的实例节点。
+   *
+   * ⑤ 段默认折叠，**但被点亮的那条链例外**（§7.7 末段）：那时用户问的正是
+   * 「这条链到底跑过没有」，把证据藏起来等于不回答。
+   */
+  const chainInstanceIds = useMemo(() => {
+    if (!selectedId) return new Set<string>()
+    const chain = chainOf(data, selectedId)
+    return new Set(data.nodes.filter(node => node.layer === 'instance' && chain.has(node.id)).map(node => node.id))
+  }, [data, selectedId])
+  const includeInstance = instanceOpen || chainInstanceIds.size > 0
+
+  /**
+   * 段切面先收窄「哪些段画」，问题大类再收成子图，最后叠节点谓词。
+   *
+   * 顺序就是 §7.3 的语义：**先决定这张图怎么画，再在图里找**。反过来的话，
+   * 「关掉检查点」会把已经按问题收窄的范围再切一刀，两边都不好解释。
+   */
+  const laneScoped = useMemo(
+    () => ({ nodes: narrowedToLanes(filtered.nodes, kinds), edges: filtered.edges }),
+    [filtered, kinds],
+  )
   const graphData = useMemo(
-    () => (overview ? filtered : (focusId ? neighborhoodOf(filtered, focusId, 1) : filtered)),
-    [filtered, overview, focusId],
+    () => (overview ? laneScoped : (focusId ? neighborhoodOf(laneScoped, focusId, 1) : laneScoped)),
+    [laneScoped, overview, focusId],
   )
   const focused = data.nodes.find(node => node.id === focusId)
   const filtering = query.trim() !== '' || kinds.size > 0 || modes.size > 0 || problems.size > 0
+    || subclasses.size > 0 || gapOnly || costBands.size > 0 || automations.size > 0
 
-  const toggleKind = (kind: AttributionNodeKind): void => {
+  const toggleIn = <T,>(set: ReadonlySet<T>, value: T, apply: (next: ReadonlySet<T>) => void): void => {
+    const next = new Set(set)
+    if (next.has(value)) next.delete(value); else next.add(value)
+    apply(next)
+  }
+  const toggleKind = (kind: AttributionNodeKind): void => toggleIn(kinds, kind, setKinds)
+  const toggleMode = (mode: FailureReason): void => toggleIn(modes, mode, setModes)
+  const toggleProblem = (id: ProblemClassId): void => {
+    toggleIn(problems, id, next => {
+      setProblems(next)
+      // 大类取消勾选时，属于它的子类一并撤掉 —— 否则会留下一个「什么也筛不出」
+      // 的隐形条件：界面上再也看不到那个子类 chip（它只跟着选中的大类出现）。
+      if (!next.has(id)) {
+        setSubclasses(previous => {
+          const kept = new Set(previous)
+          for (const sub of PROBLEM_CLASS_IDS_TO_SUBCLASSES[id] ?? []) kept.delete(sub)
+          return kept
+        })
+      }
+    })
+  }
+  const toggleSubclass = (id: string): void => toggleIn(subclasses, id, setSubclasses)
+  const toggleCostBand = (id: string): void => toggleIn(costBands, id, setCostBands)
+  const toggleAutomation = (id: string): void => toggleIn(automations, id, setAutomations)
+  /**
+   * 段开关：关掉一段 = 那一段的节点种类一起离开（§7.3）。
+   *
+   * 关键是**「全开」与「全关」这两个边界**：`kinds` 空集表示不过滤，所以
+   * 从全开点掉一段，必须显式把**其余**段的种类写进去（否则空集又等于全开，
+   * 点一下没反应）；反过来把最后一段也点掉时，回到空集 = 回到全开 ——
+   * 「什么都不画」不是这张图上可表达的状态，一张空画布没法读。
+   */
+  const toggleLane = (id: LaneId): void => {
+    const lane = LANES.find(item => item.id === id)
+    if (!lane) return
+    const on = laneKindVisible(kinds, lane)
     const next = new Set(kinds)
-    if (next.has(kind)) next.delete(kind); else next.add(kind)
+    if (on) {
+      for (const kind of FILTERABLE_KINDS) if (!lane.kinds.includes(kind)) next.add(kind)
+    } else {
+      for (const kind of lane.kinds) next.delete(kind)
+    }
     setKinds(next)
   }
-  const toggleMode = (mode: FailureMode): void => {
-    const next = new Set(modes)
-    if (next.has(mode)) next.delete(mode); else next.add(mode)
-    setModes(next)
-  }
-  const toggleProblem = (id: ProblemClassId): void => {
-    const next = new Set(problems)
-    if (next.has(id)) next.delete(id); else next.add(id)
-    setProblems(next)
+  const clearFilter = (): void => {
+    setQuery(''); setKinds(new Set()); setModes(new Set()); setProblems(new Set())
+    setSubclasses(new Set()); setGapOnly(false); setCostBands(new Set()); setAutomations(new Set())
   }
-  const clearFilter = (): void => { setQuery(''); setKinds(new Set()); setModes(new Set()); setProblems(new Set()) }
+  /** 全部取消点亮：再点同一个节点、点空白处、或按「取消点亮」都走这一条。 */
+  const clearSelection = (): void => { setSelectedId(undefined); setFocusId(undefined) }
+  /**
+   * 换到另一个现象的动线。
+   *
+   * 它同时做两件事：①段改画那个现象、并点亮它的链。少了第二件，用户点了一个入口却
+   * 看到画面没变亮，会以为点没生效。
+   *
+   * 注意它**不碰** `focusId`：那是「聚焦哪个节点的邻域」，与「看哪个现象的动线」
+   * 是两件事，混在一起会让右上的「全景 / 聚焦」跟着乱跳。
+   */
+  const pickSymptom = useCallback((id: string): void => {
+    setLaneSymptomId(id)
+    setSelectedId(id)
+  }, [])
+  /** 被关掉的段（左栏段 chip 的选中态与划线）。 */
+  const lanesOff = useMemo(
+    () => new Set(LANES.filter(lane => !laneKindVisible(kinds, lane)).map(lane => lane.id)),
+    [kinds],
+  )
+
+  /** 收起 / 展开一段。点段头与左栏的段 chip 走同一条路。 */
+  const toggleLaneCollapsed = useCallback((lane: LaneId): void => {
+    setCollapsedLanes(previous => {
+      const next = new Set(previous)
+      if (next.has(lane)) next.delete(lane); else next.add(lane)
+      return next
+    })
+  }, [])
 
   /**
    * 进出全屏。
    *
-   * 进全屏时顺手把图例打开：那个档位本来就该「相关选项都展示上去」，而且全屏里
-   * 右侧副栏宽一倍，放得下。退出时不动用户的选择 —— 收起图例是用户的决定，
-   * 不该被一次全屏往返改回去。
+   * 进全屏时顺手展开左栏与图例（§7.6）：**全屏放得下，就不该让用户再点一次**。
+   * 面板态默认收起是因为 380px 塞不下四组控件 + 五段泳道；退出时不动用户的选择。
    */
   const toggleFull = (): void => {
-    if (!full) setLegendOpen(true)
+    if (!full) {
+      setLegendOpen(true)
+      setRailOpen(true)
+    }
     setFull(!full)
   }
 
@@ -165,43 +415,55 @@ export function AttributionTab({ visible }: { visible: boolean }): ReactNode {
   const viewItems: ReadonlyArray<ViewSwitchItem<SubView>> = [
     {
       id: 'graph', label: '图谱', icon: GitBranch,
-      hint: '结构：谁可能是谁的原因。空区和僵尸边只在这张图上可见。',
+      hint: '动线：问题现象 → 假设原因 → 检查点 → 查询依据 → 实际查询与结果。空区与僵尸边只在这张图上可见。',
       meta: String(stats.typeNodes + stats.referenceNodes),
     },
     {
       id: 'case', label: '案例', icon: History,
       hint: '路径：一次真实排查怎么走的，包括走错的那一段。',
-      meta: String(SEED_CASES.length),
+      meta: String(cases.length),
     },
     {
       id: 'run', label: '排查', icon: Stethoscope,
-      hint: '剪枝：按优先分排出下一步该查什么，每个检查都有主操作。',
+      hint: '剪枝：按优先分排出下一步该查什么，每个检查点都有主操作。',
       meta: String(candidateCount),
     },
   ]
 
-  const layoutHint = layout === 'force'
-    ? '力导向：节点可拖动，松手后图会继续摊开 —— 关系靠聚簇和距离表达，方向不保证。'
-    : '分层：现象 → 假设 → 检查 的方向被显式画出来，但看起来更像流程图。'
+  const layoutHint = layout === 'line'
+    ? `动线：五段泳道，段内各有排序；点一个现象或假设会点亮它那条链。${instanceOpen ? '⑤ 段已展开。' : '⑤ 段（实际查询与结果）默认折叠，点它可展开。'}`
+    : '关系：浮动节点、可拖拽，松手后图会继续摊开 —— 关系靠聚簇和距离表达，方向不保证。'
+  const filterCount = kinds.size + problems.size + subclasses.size + modes.size + costBands.size + automations.size + (gapOnly ? 1 : 0)
 
   const stage = <GraphStage
     mode={full ? 'fullscreen' : 'panel'}
     // 画布不随子视图卸载：切走再切回来时，拖过的位置要还在。
     canvas={<AttributionGraph
-      key={`${resetToken}-${layout}`}
+      key={`${resetToken}-${layout}-${full ? 'full' : 'panel'}`}
       data={graphData}
       gapIds={gapIds}
       rankdir="LR"
       layout={layout}
       mode={full ? 'fullscreen' : 'panel'}
-      selectedId={focusId}
-      onSelect={setFocusId}
+      selectedId={selectedId}
+      includeInstance={includeInstance}
+      collapsedLanes={collapsedLanes}
+      lanesOff={lanesOff}
+      onToggleLane={toggleLaneCollapsed}
+      {...(layout === 'line' && laneSymptomId ? { focusSymptomId: laneSymptomId } : {})}
+      onPickSymptom={pickSymptom}
+      onLaneCounts={setLaneCounts}
+      onSelect={id => {
+        // 再点一次取消，回到全亮；点空白处同理（§7.4 第 9 条）。
+        setSelectedId(previous => (id === undefined || previous === id ? undefined : id))
+        setFocusId(id)
+      }}
     />}
     topLeft={
-      // 画布左上角只剩「这张图怎么画」：布局 + 类型切面。页面切换已经搬到画框之外。
-      // 案例 / 排查页没有图可读，这两个开关也就没有对象 —— 不传，不留空壳。
+      // 画布左上角只剩「这张图怎么画」：四组按动线顺序的切面。页面切换已经搬到画框之外。
+      // 案例 / 排查页没有图可读，这些开关也就没有对象 —— 不传，不留空壳。
       subView !== 'graph' ? undefined : railOpen
-        ? <ToolRail
+        ? <OperationsRail
           layout={layout}
           onLayout={setLayout}
           onReset={() => setResetToken(token => token + 1)}
@@ -209,60 +471,88 @@ export function AttributionTab({ visible }: { visible: boolean }): ReactNode {
           onToggleKind={toggleKind}
           problems={problems}
           onToggleProblem={toggleProblem}
+          subclasses={subclasses}
+          onToggleSubclass={toggleSubclass}
           symptomCounts={symptomCounts}
-          hint={layoutHint + (!overview && focused ? ` 聚焦 ${focused.id} 的 1 跳邻域，点节点切换。` : '')}
+          failureReasons={modes}
+          onToggleFailureReason={toggleMode}
+          gapOnly={gapOnly}
+          onGapOnly={() => setGapOnly(!gapOnly)}
+          costBands={costBands}
+          onToggleCostBand={toggleCostBand}
+          automations={automations}
+          onToggleAutomation={toggleAutomation}
+          laneCounts={laneCounts}
+          lanesOff={lanesOff}
+          onToggleLane={toggleLane}
+          hint={layoutHint + (overview ? '' : (focused ? ` 正聚焦 ${focused.id} 的 1 跳邻域，点节点切换。` : ' 处在聚焦态，点一个节点看它的邻域。'))}
           onCollapse={() => setRailOpen(false)}
         />
-        : <ToolPill layout={layout} kinds={kinds} problems={problems} onClick={() => setRailOpen(true)} />
+        : <ToolPill
+          layout={layout}
+          filterCount={filterCount}
+          laneCount={laneScoped.nodes.length}
+          pendingProposals={pendingProposals}
+          {...(onOpenKnowledge ? { onOpenProposals: onOpenKnowledge } : {})}
+          onClick={() => setRailOpen(true)}
+        />
     }
-    topRight={<LegendToggle
-      open={legendOpen}
-      onToggle={() => setLegendOpen(!legendOpen)}
+    topRight={<ReadBar
+      legendOpen={legendOpen}
+      onToggleLegend={() => setLegendOpen(!legendOpen)}
+      showLegend={subView === 'graph'}
+      overview={overview}
+      onOverview={setOverview}
+      includeNeighbors={includeNeighbors}
+      onIncludeNeighbors={setIncludeNeighbors}
       full={full}
       onToggleFull={toggleFull}
-      showLegend={subView === 'graph'}
+      showScope={subView === 'graph'}
     />}
-    {...(subView === 'case' ? { layer: <CaseView activeId={activeCase} onActiveChange={setActiveCase} /> } : {})}
+    {...(subView === 'case' ? { layer: <CaseView cases={cases} activeId={activeCase} onActiveChange={setActiveCase} /> } : {})}
     {...(subView === 'run' ? {
       layer: <RunView
         data={data}
+        cases={cases}
         symptoms={symptoms}
-        symptomId={symptomId}
+        symptomId={activeSymptomId}
         onSymptomChange={setSymptomId}
-        onSelectNode={id => { setFocusId(id); setSubView('graph') }}
+        onSelectNode={id => { setSelectedId(id); setFocusId(id); setSubView('graph') }}
       />,
     } : {})}
     {...(subView === 'graph' ? {
+      // 底中**只剩文本搜索 + 命中数**（§7.1）：失败原因切面在左栏第 ③ 组，
+      // 「保留 1 跳邻居」在右上读法排。搜索留在底部，因为它是跨全图的动作。
       bottomCenter: <FilterBar
         query={query}
         onQuery={setQuery}
-        modes={modes}
-        onToggleMode={toggleMode}
-        includeNeighbors={includeNeighbors}
-        onIncludeNeighbors={setIncludeNeighbors}
         filtering={filtering}
         onClear={clearFilter}
         hit={filtered.nodes.length}
         total={data.nodes.length}
       />,
-      bottomRight: <StatsStrip
+      // 左下：读数（统计 + 数据来源），v1.4 从右下搬来。
+      bottomLeft: <StatsStrip
         stats={stats}
-        source={remote?.source ?? 'seed 数据'}
+        source={remote?.source ?? '还没有排查知识'}
         problems={remote?.problems ?? []}
       />,
+      // 右侧副栏贴右上展开：图例正文 + 选中节点详情。
       side: <>
-        {/* 「全景 / 聚焦邻域」是画布读法，不是筛选，所以它贴在图例下面而不是筛选条里。 */}
-        <div className="mb-1.5 flex justify-end">
-          <Button
-            size="sm"
-            className="h-[26px] min-h-[26px] px-2 text-[11px]"
-            variant={overview ? 'default' : 'outline'}
-            onClick={() => setOverview(!overview)}
-          >{overview ? '全景' : '聚焦 1 跳'}</Button>
-        </div>
+        {/* ⑤ 段（实例层）默认折叠。展开它就把每次排查的产物铺进来 ——
+            类型层会被挤成小点，所以它是**显式的一次选择**。 */}
+        {layout === 'line' && <label className="mb-1.5 flex cursor-pointer items-center gap-1.5 rounded-md border border-tita-line bg-tita-surface px-2 py-1 text-[10.5px] text-tita-ink-muted">
+          <input
+            type="checkbox"
+            className="h-[12px] w-[12px] accent-[var(--tita-primary)]"
+            checked={instanceOpen}
+            onChange={event => setInstanceOpen(event.target.checked)}
+          />
+          ⑤ 段（{laneCounts.instance.total} 条实际查询与结果）
+        </label>}
         <div className="flex flex-col gap-1.5">
           {legendOpen && <LegendBody stats={stats} />}
-          {focused && <NodeDetailCard node={focused} />}
+          {focused && <NodeDetailCard node={focused} onClear={selectedId ? clearSelection : undefined} />}
         </div>
       </>,
     } : {})}
@@ -274,7 +564,7 @@ export function AttributionTab({ visible }: { visible: boolean }): ReactNode {
    * 它曾经浮在画布的左上角。搬到外面来的理由不是审美：**页面切换是页面级控件，
    * 画布是它切换的内容之一**。放在画布里，等于把「换一页」和「改这张图怎么画」
    * 混成同一层的浮层 —— 而 §7.1 的分区原则正好相反（改「怎么画」的贴画布，
-   * 换「看哪一页」的贴页面）。搬出来之后画布左上角只剩布局与类型两个开关。
+   * 换「看哪一页」的贴页面）。搬出来之后画布左上角只剩四组切面。
    *
    * 说明文案不在切换器内部，而是同一行的右侧：一整行读下来是
    * 「你在哪一页 → 这一页回答什么问题」，比把它折到切换器下面更省一行高度。
@@ -289,6 +579,25 @@ export function AttributionTab({ visible }: { visible: boolean }): ReactNode {
   />
   const viewHint = viewItems.find(item => item.id === subView)?.hint ?? ''
 
+  /**
+   * 空态优先于一切。
+   *
+   * 这一栏原来没有空态：库是空的也照样画一张图 —— 只不过画的是内置示例的 34 个节点。
+   * 用户没法分辨「这是我的库」还是「这是样例」，实跑反馈里那句「为什么把我默认的知识库
+   * 内容也带进去了」问的就是这件事。现在空的就明说空，并且把「怎么让它有东西」摆出来。
+   */
+  if (phase !== 'ready' || data.nodes.length === 0) {
+    return <AttributionEmpty
+      phase={phase}
+      canLoadSample={canLoadSample}
+      busy={sampleBusy}
+      {...(sampleError ? { loadError: sampleError } : {})}
+      onLoadSample={() => void loadSample()}
+      onRetry={() => setReloadToken(token => token + 1)}
+      {...(onOpenKnowledge ? { onOpenKnowledge } : {})}
+    />
+  }
+
   if (full) {
     return createPortal(
       <div
@@ -323,6 +632,21 @@ export function AttributionTab({ visible }: { visible: boolean }): ReactNode {
   }
 
   return <div className="flex min-h-0 flex-1 flex-col gap-1.5">
+    {/* 载入示例之后的一句话。写清楚「写了什么、写在哪、能不能改」—— 载入是一次真实的
+        写入，用户有权知道它落在自己知识树的哪两个目录里。 */}
+    {sampleNotice && <div
+      role="status"
+      className="flex items-start gap-1.5 rounded-lg border border-tita-line bg-tita-surface-muted p-2 text-[10.5px] leading-relaxed text-tita-ink-muted"
+    >
+      <Sparkles size={12} className="mt-0.5 shrink-0" />
+      <span className="min-w-0 flex-1">{sampleNotice}</span>
+      <button
+        type="button"
+        aria-label="关闭提示"
+        className="shrink-0 rounded-sm focus-visible:outline-[3px] focus-visible:outline-offset-1 focus-visible:outline-tita-focus-ring"
+        onClick={() => setSampleNotice(null)}
+      ><X size={12} /></button>
+    </div>}
     <div className="flex min-w-0 items-center gap-2">
       {switcher}
       <p className="min-w-0 flex-1 truncate text-[10px] text-tita-ink-muted">{viewHint}</p>
@@ -330,3 +654,80 @@ export function AttributionTab({ visible }: { visible: boolean }): ReactNode {
     {stage}
   </div>
 }
+
+/** 大类 id → 它下面的子类 id。取消大类时要把这些子类一起撤掉。 */
+const PROBLEM_CLASS_IDS_TO_SUBCLASSES: Record<string, string[]> = Object.fromEntries(
+  PROBLEM_CLASSES.map(item => [item.id, item.subclasses.map(sub => sub.id)]),
+)
+
+/**
+ * 空态：这一栏还没有东西可看时，界面上唯一该出现的那一块。
+ *
+ * 三件事按顺序回答，不多不少：
+ * 1. **这里会有什么** —— 排查经验（现象 → 假设 → 检查点，再由案例串成路径），
+ *    以及它的出处（wiki 卡片，不是凭空生成的）；
+ * 2. **怎么让它有东西** —— 去知识库录来源（主操作）；
+ * 3. **示例是什么、写在哪** —— 一份排查手册加三篇复盘，写进你自己的
+ *    `01_source_truth/` 与 `02_wiki/diagnosis/`，载入后就是普通来源与卡片。
+ *
+ * 它**不是**一张卡片：这里只有一条正文，套进 `Card` 就变成「空页里放了一张卡」，
+ * 而卡片是给并列内容用的容器。读失败与读取中是同一块地方的另外两种状态。
+ */
+function AttributionEmpty({ phase, canLoadSample, busy, loadError, onLoadSample, onRetry, onOpenKnowledge }: {
+  phase: 'loading' | 'ready' | 'error'
+  canLoadSample: boolean
+  busy: boolean
+  loadError?: string
+  onLoadSample: () => void
+  onRetry: () => void
+  onOpenKnowledge?: () => void
+}): ReactNode {
+  if (phase === 'loading') {
+    return <div className="flex min-h-0 flex-1 items-center justify-center">
+      <p role="status" className="text-[11px] text-tita-ink-muted">正在读取这个知识库的排查知识…</p>
+    </div>
+  }
+
+  if (phase === 'error') {
+    return <div className="flex min-h-0 flex-1 items-center justify-center">
+      <div className="flex max-w-[300px] flex-col items-start gap-2">
+        <h3 className="text-[13px] font-semibold text-tita-ink">没能读到这个知识库的排查知识</h3>
+        <p className="text-[11px] leading-relaxed text-tita-ink-muted">
+          这一栏读的是 `/diagnosis/graph`，它没答话。宿主刚起来、或者这个知识库的根目录暂时读不到时会这样。
+        </p>
+        <Button size="sm" variant="outline" className="h-[26px] min-h-[26px] px-2 text-[11px]" onClick={onRetry}>重试</Button>
+      </div>
+    </div>
+  }
+
+  return <div className="flex min-h-0 flex-1 items-center justify-center p-3">
+    <div className="flex max-w-[320px] flex-col items-start gap-2">
+      <h3 className="text-[13px] font-semibold text-tita-ink">这个知识库还没有排查知识</h3>
+      <p className="text-[11px] leading-relaxed text-tita-ink-muted">
+        这一栏画的是排查经验：问题现象 → 假设原因 → 检查点，再由案例把它们串成一条走过的路径。
+        它由 wiki 卡片编译而来 —— 先在「知识库」里录一份手册、几篇复盘，或者把卡片写出来，
+        这里就会有东西。
+      </p>
+      <div className="flex flex-wrap gap-1.5">
+        {onOpenKnowledge && <Button
+          size="sm"
+          variant="default"
+          className="h-[26px] min-h-[26px] px-2 text-[11px]"
+          onClick={onOpenKnowledge}
+        ><Database size={12} />去知识库录来源</Button>}
+        {canLoadSample && <Button
+          size="sm"
+          variant={onOpenKnowledge ? 'outline' : 'default'}
+          className="h-[26px] min-h-[26px] px-2 text-[11px]"
+          disabled={busy}
+          onClick={onLoadSample}
+        ><Sparkles size={12} />{busy ? '载入中…' : '载入内置示例'}</Button>}
+      </div>
+      {canLoadSample && <p className="text-[10.5px] leading-relaxed text-tita-ink-muted">
+        示例是一份排查手册加三篇复盘。载入后它们写进你自己的 <b>01_source_truth/</b> 与
+        <b> 02_wiki/diagnosis/</b>，就是普通的来源与卡片 —— 可以照常改、照常删。
+      </p>}
+      {loadError && <p role="alert" className="text-[10.5px] leading-relaxed text-tita-danger">载入失败：{loadError}</p>}
+    </div>
+  </div>
+}