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

package/src/client/RecallPanel.tsx

@@ -9,9 +9,9 @@
  * `chunk_index` / `score` 一起给出 —— 只报「命中 N 条」看不出召回质量。
  */
 
-import { useEffect, useState, type ReactNode } from 'react'
-import { Check, CircleHelp, Play, Search } from '@tita-data-agent/ui/icons'
-import { Badge, Button, Card, Input, SelectMenu, cn } from '@tita-data-agent/ui/components'
+import { Fragment, useEffect, useState, type ReactNode } from 'react'
+import { ArrowUpDown, ChevronRight, CircleHelp, GitBranch, Play, Search } from '@tita-data-agent/ui/icons'
+import { Button, Card, Input, SelectMenu, cn } from '@tita-data-agent/ui/components'
 import { styles } from './styles.ts'
 
 /** 一条命中的 wikiNote。`match` 是**真正贡献了这次命中**的路线。 */
@@ -24,6 +24,8 @@ export interface RecallHitView {
   score: number
   status?: string
   entityType?: string
+  /** 这条 note 属于哪张卡片（点开预览用）。 */
+  entityId?: string
   rerankScore?: number
 }
 
@@ -36,8 +38,47 @@ export interface ContextItemView {
   rerankScore?: number
   wikiTitle?: string
   wikiId?: string
+  /** 这张卡片是命中的还是 1 跳扩展来的（0050）。 */
+  reason?: 'hit' | 'expansion'
+  /** 扩展条目的来路：「哪张卡（哪条边）」。 */
+  via?: string
 }
 
+/** 账本里的一行（0050）：这一路对这个候选算出的分数与名次。 */
+export interface LedgerRowView {
+  unitId: string
+  title: string
+  entityType: string
+  entityId: string
+  score: number
+  rank: number
+  kept: boolean
+}
+
+/** 去重后的命中卡片（0050）。 */
+export interface WikiCardView {
+  entityId: string
+  entityType: string
+  title: string
+  summary?: string
+  /** 它有几条 note 进了上下文（命中的小节数）。 */
+  noteCount: number
+}
+
+/** 1 跳扩展进来的卡片（0050）。 */
+export interface ExpansionNodeView {
+  entityType: string
+  entityId: string
+  title: string
+  /** 来路：`来源卡片的 key|关系`。 */
+  via: string[]
+  /** 真的进了上下文吗（被预算挡住的也在列表里，只是标出来）。 */
+  included: boolean
+}
+
+/** 召回链路的三个步骤（0050 改版：召回 → 重排 → 扩展）。 */
+export type RecallStep = 'recall' | 'rerank' | 'expand'
+
 export interface RecallResultView {
   count: number
   backend: string
@@ -65,6 +106,31 @@ export interface RecallResultView {
   encoder?: { ok: boolean; reason?: string }
   hits: RecallHitView[]
   context: ContextItemView[]
+  /** 面板账本（0050）：每一路的全部候选 + 重排的全部候选（含被丢弃的）。 */
+  ledger?: {
+    fts: LedgerRowView[]
+    vector: LedgerRowView[]
+    rerank: Array<LedgerRowView & { fused: number; logit?: number; rerankScore?: number; dropped: boolean }>
+  }
+  /** 去重后的命中卡片（0050）。 */
+  wiki: WikiCardView[]
+  /** 1 跳扩展（0050）。 */
+  expansion?: { nodes: ExpansionNodeView[]; edgeCount: number; included: string[] }
+  /**
+   * 各阶段耗时（毫秒，0050 第二版）。
+   *
+   * 它进界面的理由：这几个数量级差得很远（查询编码 270ms vs 首次加载 8s），
+   * 只给「这次测试很慢」的感受，人没法判断该不该管它。
+   */
+  timings?: {
+    ftsMs: number; vectorMs: number; embedMs?: number; scanMs?: number
+    graphMs: number; fuseMs: number; rerankMs?: number; assembleMs: number; totalMs: number
+  }
+  /** 命中几张卡 + 1 跳扩展几张（0050）。 */
+  hitCards?: number
+  expandedCards?: number
+  omittedCards?: number
+  overflowPath?: string
   kbName?: string
   indexVersion?: number
 }
@@ -85,6 +151,95 @@ async function requestJson<T>(url: string): Promise<Envelope<T>> {
   return payload
 }
 
+/**
+ * 账本列表（0050）：**每一路的全部候选**，没过阈值的也在（虚线 + 淡色 + 一句原因）。
+ *
+ * 它与 `HitList` 的分工：`HitList` 是「这次召回最后剩了什么」（融合 + 重排之后），
+ * 这里是「这一路各自看到了什么、丢了什么」。面板要回答「为什么没召回」，靠的是后者。
+ */
+export function LedgerList({ rows, scoreLabel, droppedLabel, emptyLabel }: {
+  rows: Array<LedgerRowView & { fused?: number; logit?: number; rerankScore?: number; dropped?: boolean }>
+  scoreLabel: (row: LedgerRowView & { fused?: number; logit?: number; rerankScore?: number }) => string
+  droppedLabel?: string
+  emptyLabel?: string
+}): ReactNode {
+  if (rows.length === 0) return <div className={styles.emptyState}><CircleHelp size={16} />{emptyLabel ?? '这一路没有候选'}</div>
+  return <ul className={styles.hitList}>
+    {rows.map(row => {
+      const dropped = row.kept === false || row.dropped === true
+      return <li key={row.unitId} className={cn(styles.hitRow, dropped && styles.hitRowDropped)}>
+        <div className={styles.hitHead}>
+          <span className={styles.hitRank}>{row.rank}</span>
+          <span className={styles.hitTitle} title={row.unitId}>{row.title}</span>
+          {dropped && <span className={styles.hitDropped}>{droppedLabel ?? '已丢弃'}</span>}
+          <span className={styles.hitScore}>{scoreLabel(row)}</span>
+        </div>
+        <div className={styles.hitFoot}>
+          <span className={styles.kbCode}>{row.entityType}/{row.entityId}</span>
+        </div>
+      </li>
+    })}
+  </ul>
+}
+
+/** 命中卡片（去重后）与 1 跳扩展两块（0050 的「扩展」tab）。 */
+export function ExpansionView({ wiki, expansion, context, onOpenWiki }: {
+  wiki: WikiCardView[]
+  expansion?: RecallResultView['expansion']
+  context: ContextItemView[]
+  onOpenWiki?: OpenWikiCard
+}): ReactNode {
+  const expandedInContext = context.filter(item => item.reason === 'expansion')
+  /** 卡片标题：宿主给了抽屉就是按钮，没给就是纯文本 —— 面板不自己造一个抽屉出来。 */
+  const cardTitle = (card: { entityType: string; entityId: string; title: string }): ReactNode =>
+    onOpenWiki
+      ? <button type="button" className={styles.cardLink} onClick={() => onOpenWiki(card)}>{card.title}</button>
+      : <span className={styles.hitTitle}>{card.title}</span>
+  return <>
+    <div className={styles.kbSubHead}><h4>命中的 wiki 卡片（按卡片去重后）</h4><span>{wiki.length} 张</span></div>
+    <p className={styles.kbHint}>召回与重排的对象是 wikiNotes（片段），这里是把它们折回卡片的结果：同一张卡片的多个小节只算一张，等级取它最高那条 note。</p>
+    {wiki.length === 0
+      ? <div className={styles.emptyState}><CircleHelp size={16} />这次没有命中的卡片</div>
+      : <ul className={styles.hitList}>
+        {wiki.map(card => <li key={`${card.entityType}:${card.entityId}`} className={styles.hitRow}>
+          <div className={styles.hitHead}>
+            {cardTitle(card)}
+            <span className={styles.hitScore}>{card.noteCount} 条片段</span>
+          </div>
+          {card.summary && <p className={styles.hitSnippet}>{card.summary}</p>}
+          <div className={styles.hitFoot}><span className={styles.kbCode}>{card.entityType}/{card.entityId}</span></div>
+        </li>)}
+      </ul>}
+
+    <div className={styles.kbSubHead}>
+      <h4>1 跳知识图谱扩展</h4>
+      <span>{expansion?.nodes.length ?? 0} 张卡片 · {expansion?.edgeCount ?? 0} 条边</span>
+    </div>
+    <p className={styles.kbHint}>从上面那些卡片出发，沿图上的关系边与「共同来源」各走一跳。<b>它在去重之后发生</b> —— 所以这里列的都是邻居，不是召回来的。</p>
+    {(expansion?.nodes.length ?? 0) === 0
+      ? <div className={styles.emptyState}><CircleHelp size={16} />这些卡片在图上没有邻居</div>
+      : <ul className={styles.hitList}>
+        {expansion?.nodes.map(node => <li key={`${node.entityType}:${node.entityId}`} className={cn(styles.hitRow, !node.included && styles.hitRowDropped)}>
+          <div className={styles.hitHead}>
+            {cardTitle({ entityType: node.entityType, entityId: node.entityId, title: node.title })}
+            {!node.included && <span className={styles.hitDropped}>超预算</span>}
+            <span className={styles.hitScore}>{node.via.length} 条来路</span>
+          </div>
+          <div className={styles.hitFoot}>
+            <span className={styles.kbCode}>{node.entityType}/{node.entityId}</span>
+            <span>来自 {node.via.map(via => via.split('|')[0]).join('、')}</span>
+          </div>
+        </li>)}
+      </ul>}
+    {(expansion?.nodes.length ?? 0) > 0 && <p className={styles.kbHint}>
+      其中 {expandedInContext.length} 张进了上下文
+      {expandedInContext.length < (expansion?.nodes.length ?? 0)
+        ? `，其余 ${(expansion?.nodes.length ?? 0) - expandedInContext.length} 张被上下文预算挡在外面（完整内容在溢出文件里）`
+        : ''}。
+    </p>}
+  </>
+}
+
 /**
  * 召回是**两路**（关键词 BM25 + 向量）加一个图谱 boost（0031）。
  *
@@ -96,17 +251,23 @@ export const RECALL_ROUTES: Array<{ id: string; label: string; hint: string }> =
   { id: 'vector', label: '向量', hint: 'WeMM 向量近邻（binary 预筛 + int8 精算余弦）' },
 ]
 
+/**
+ * 路线选项**只有两路**（0050 改版）。
+ *
+ * 图谱 boost 不是一条路（它不能制造候选，只给已在池里的条目加权），所以它不该出现在
+ * 「选哪一路」的下拉里 —— 上一版那两条「融合 + 图谱 boost」「同融合」正是这个错：
+ * 把加权当成了路线。融合是两路的**组合方式**，写在选项文字里，不是第三个选项。
+ */
 export const RECALL_MODES: Array<{ id: string; label: string }> = [
-  { id: 'hybrid', label: '融合 + 图谱 boost（默认）' },
+  { id: 'hybrid', label: '关键词 + 向量（融合，默认）' },
   { id: 'fts', label: '仅关键词' },
   { id: 'vector', label: '仅向量' },
-  { id: 'graph', label: '同融合（图谱已不是独立一路）' },
 ]
 
 const HIT_ROUTES: Record<string, string> = {
   fts: styles.hitRouteFts, vector: styles.hitRouteVector, graph: styles.hitRouteGraph, hybrid: styles.hitRouteHybrid,
 }
-const HIT_ROUTE_LABEL: Record<string, string> = { fts: '关键词', vector: '向量', graph: '知识图谱', hybrid: '三路融合' }
+const HIT_ROUTE_LABEL: Record<string, string> = { fts: '关键词', vector: '向量', hybrid: '关键词+向量', graph: '图谱加权' }
 
 /** 去掉 markdown 脚手架，让命中读起来是一段正文而不是源码。 */
 export function snippetOf(content: string, limit = 200): string {
@@ -119,86 +280,38 @@ export function snippetOf(content: string, limit = 200): string {
   return plain.length > limit ? `${plain.slice(0, limit)}…` : plain
 }
 
-/**
- * 路线状态行。
- *
- * 0031 起它读的是 `diagnostics.routes` 而不是「`routes` 里有没有这个 id」：**降级也要看得见**。
- * 原来的写法只能表达「跑没跑」，于是向量路坏掉时芯片显示「（未跑）」而 `routes` 里却写着
- * `vector` —— 同一屏上两处互相矛盾，而且都没说为什么。
- */
-export function RecallRoutes({ routes, backend, routesDetail, graphBoost }: {
-  routes: string[]
-  backend?: string
-  routesDetail?: RecallResultView['routesDetail']
-  graphBoost?: RecallResultView['graphBoost']
-}): ReactNode {
-  const active = new Set(routes.map(route => route.toLocaleLowerCase()))
-  type RouteDetail = NonNullable<RecallResultView['routesDetail']>[number]
-  const detailOf = (id: string): RouteDetail | undefined => routesDetail?.find(item => item.route === id)
-  return <div className={styles.routeRow} aria-label="召回路线">
-    {RECALL_ROUTES.map(route => {
-      const detail = detailOf(route.id)
-      const ran = detail ? detail.status === 'ran' : (active.has(route.id) || (route.id === 'fts' && active.has('keyword')))
-      const degraded = detail?.status === 'degraded'
-      const title = degraded && detail?.reason ? `${route.hint} —— ${detail.reason}` : route.hint
-      const suffix = degraded ? '（降级）' : ran ? (detail?.kept !== undefined ? ` ${detail.kept}` : '') : '（未跑）'
-      return <span key={route.id} className={cn(styles.routeChip, ran && styles.routeChipOn, degraded && styles.routeChipOff)} title={title}>
-        {route.label}{suffix}
-      </span>
-    })}
-    {/* 图谱是 boost：显示它加权了几条，而不是「跑没跑」。 */}
-    <span className={styles.routeChip} title="图谱只给已在候选池里的条目加权，不能自己制造候选">
-      图谱 boost {graphBoost && graphBoost.applied > 0 ? `+${graphBoost.applied}` : '未生效'}
-    </span>
-    <span className={styles.routeBackend}>{backend ? backend.toUpperCase() : 'FTS'}</span>
-  </div>
-}
-
-function HitList({ hits }: { hits: RecallHitView[] }): ReactNode {
+function HitList({ hits, onOpenWiki }: { hits: RecallHitView[]; onOpenWiki?: OpenWikiCard }): ReactNode {
+  const [expanded, setExpanded] = useState<Record<string, boolean>>({})
   if (hits.length === 0) return null
   return <ul className={styles.hitList}>
-    {hits.map(hit => <li key={hit.unitId} className={styles.hitRow}>
-      <div className={styles.hitHead}>
-        <span className={cn(styles.hitRoute, HIT_ROUTES[hit.match] ?? styles.hitRouteFts)}>{HIT_ROUTE_LABEL[hit.match] ?? hit.match}</span>
-        <span className={styles.hitTitle} title={hit.unitId}>{hit.title}{hit.heading ? ` · ${hit.heading}` : ''}</span>
-        <span className={styles.hitScore}>{hit.score.toFixed(3)}</span>
-      </div>
-      <p className={styles.hitSnippet}>{hit.snippet || '（这条 wikiNote 没有正文）'}</p>
-      <div className={styles.hitFoot}>
-        <span className={styles.kbCode}>{hit.unitId}</span>
-        {hit.status && <span>状态 {hit.status}</span>}
-        {hit.entityType && <span>{hit.entityType}</span>}
-        {hit.rerankScore !== undefined && <span>rerank {hit.rerankScore.toFixed(3)}</span>}
-      </div>
-    </li>)}
-  </ul>
-}
-
-/**
- * 进入 Context Pack 的 topN。重排这一栏必须显示得分的**来源**：
- * rerank 真跑过就给 rerank 分数，降级时按融合分数排就只给融合分数，不混着显示。
- */
-function ContextList({ items, provider }: { items: ContextItemView[]; provider?: string }): ReactNode {
-  if (items.length === 0) return null
-  const reranked = provider !== 'none' && items.some(item => item.rerankScore !== undefined)
-  return <ol className={styles.contextList}>
-    {items.map((item, index) => <li key={item.unitId} className={styles.contextRow}>
-      <span className={styles.contextRank}>{index + 1}</span>
-      <div className={styles.contextCopy}>
-        <div className={styles.contextHead}>
-          <span className={styles.hitTitle} title={item.unitId}>{item.title}</span>
-          <span className={styles.hitScore}>{reranked && item.rerankScore !== undefined ? `rerank ${item.rerankScore.toFixed(3)}` : `融合 ${item.score.toFixed(3)}`}</span>
+    {hits.map(hit => {
+      const open = expanded[hit.unitId] === true
+      return <li key={hit.unitId} className={styles.hitRow}>
+        <div className={styles.hitHead}>
+          <span className={cn(styles.hitRoute, HIT_ROUTES[hit.match] ?? styles.hitRouteFts)}>{HIT_ROUTE_LABEL[hit.match] ?? hit.match}</span>
+          <span className={styles.hitTitle} title={hit.unitId}>{hit.title}{hit.heading ? ` · ${hit.heading}` : ''}</span>
+          <span className={styles.hitScore}>{hit.score.toFixed(3)}</span>
         </div>
-        <p className={styles.hitSnippet}>{item.snippet || '（这条 wikiNote 没有正文）'}</p>
+        {/* 正文默认只占两行：一条笔记的片段常有几百字，全摊开一屏只能看两条。
+            要读全文就点「展开正文」—— 数据没被截掉，只是不再默认占满屏幕。 */}
+        <p className={cn(styles.hitSnippet, !open && styles.hitSnippetClamp)}>{hit.snippet || '（这条 wikiNote 没有正文）'}</p>
         <div className={styles.hitFoot}>
-          <span className={styles.kbCode}>{item.unitId}</span>
-          {item.wikiTitle && <span>父级 wiki：{item.wikiTitle}</span>}
+          <span className={styles.kbCode}>{hit.unitId}</span>
+          {hit.status && <span>状态 {hit.status}</span>}
+          {hit.rerankScore !== undefined && <span>rerank {hit.rerankScore.toFixed(3)}</span>}
+          {onOpenWiki && hit.entityType && hit.entityId && <button type="button" className={styles.hitToggle}
+            onClick={() => onOpenWiki({ entityType: hit.entityType!, entityId: hit.entityId!, title: hit.title })}>打开卡片</button>}
+          {hit.snippet.length > 80 && <button type="button" className={styles.hitToggle}
+            onClick={() => setExpanded(current => ({ ...current, [hit.unitId]: !open }))}>{open ? '收起' : '展开正文'}</button>}
         </div>
-      </div>
-    </li>)}
-  </ol>
+      </li>
+    })}
+  </ul>
 }
 
+/** 打开某张 wiki 卡片的预览抽屉（由宿主提供；召回的扩展结果要能点进去看）。 */
+export type OpenWikiCard = (card: { entityType: string; entityId: string; title: string }) => void
+
 export interface RecallPanelProps {
   /** 作用范围：当前知识库；空表示默认库。 */
   kbId?: string
@@ -207,7 +320,7 @@ export interface RecallPanelProps {
   /** `recall` 看命中切片，`rerank` 看进入上下文的 topN，`runner` 是评测里的紧凑版。 */
   /**
    * `recall` = 知识库 → **召回重排**那一栏（0033 起召回与重排合成一栏，一次运行
-   * 从上到下给出三路命中 → 融合排序 → 精排丢了多少 → 进上下文的 topN）。
+   * 从上到下给出两路命中 → 融合排序 → 精排丢了多少 → 进上下文的 topN）。
    * `runner` = 评测里的紧凑版单问题检查。
    */
   variant?: 'recall' | 'runner'
@@ -220,9 +333,11 @@ export interface RecallPanelProps {
    * 参数住在设置抽屉里，这里只是那扇离现场更近的门。
    */
   settingsChip?: ReactNode
+  /** 点某张卡片时打开它的预览抽屉。不给就是纯文本（面板不自己造一个抽屉出来）。 */
+  onOpenWiki?: OpenWikiCard
 }
 
-export function RecallPanel({ kbId, kbName, visible, variant = 'recall', defaults, resetKey, settingsChip }: RecallPanelProps): ReactNode {
+export function RecallPanel({ kbId, kbName, visible, variant = 'recall', defaults, resetKey, settingsChip, onOpenWiki }: RecallPanelProps): ReactNode {
   const [query, setQuery] = useState('销售额')
   const [mode, setMode] = useState(defaults?.mode ?? 'hybrid')
   const [topK, setTopK] = useState(defaults?.topK ?? 10)
@@ -230,6 +345,10 @@ export function RecallPanel({ kbId, kbName, visible, variant = 'recall', default
   const [busy, setBusy] = useState(false)
   const [error, setError] = useState<string | null>(null)
   const [result, setResult] = useState<RecallResultView | null>(null)
+  /** 三个 tab（0050）：召回 / 重排 / 扩展 —— 一条链路的三段，各自回答一个问题。 */
+  const [tab, setTab] = useState<RecallStep>('recall')
+  /** 召回 tab 里正在看哪一路（`all` = 看融合后的命中）。 */
+  const [routeView, setRouteView] = useState<'all' | 'fts' | 'vector'>('all')
 
   // 知识库换了或设置存了：面板上的默认值跟着走，否则显示的还是上一个库的参数。
   // 用 effect 而不是渲染期 setState：这条同步是「外部输入变了」而不是渲染推导。
@@ -252,9 +371,16 @@ export function RecallPanel({ kbId, kbName, visible, variant = 'recall', default
       const boundedTopN = Math.min(topN, topK)
       const params = new URLSearchParams({ query: trimmed, top_k: String(topK), top_n: String(boundedTopN), mode })
       if (kbId) params.set('kb', kbId)
+      // `detail=true`：面板账本（每一路的候选、重排的全部候选）。工具调用不带它。
       const payload = await requestJson<{
         hits?: Array<Partial<RecallHitView> & { content?: string }>
-        context?: Array<{ note?: Partial<RecallHitView> & { content?: string }; wiki?: { entityId?: string; title?: string } | null }>
+        context?: Array<{
+          note?: Partial<RecallHitView> & { content?: string }
+          wiki?: { entityId?: string; entityType?: string; title?: string; summary?: string } | null
+          reason?: 'hit' | 'expansion'
+          via?: { title?: string; relation?: string }
+        }>
+        budget?: { hitCards?: number; expandedCards?: number; omittedCards?: number; overflowPath?: string }
         backend?: string
         routes?: string[]
         recallTopK?: number
@@ -269,6 +395,14 @@ export function RecallPanel({ kbId, kbName, visible, variant = 'recall', default
           encoder?: { ok: boolean; reason?: string }
         }
         indexVersion?: number
+        ledger?: {
+          fts?: LedgerRowView[]
+          vector?: LedgerRowView[]
+          rerank?: Array<LedgerRowView & { fused?: number; logit?: number; rerankScore?: number; dropped?: boolean }>
+        }
+        wiki?: Array<{ entityId?: string; entityType?: string; title?: string; summary?: string }>
+        expansion?: { nodes?: Array<{ entityType?: string; entityId?: string; title?: string; via?: string[] }>; edges?: unknown[]; included?: string[] }
+        timings?: RecallResultView['timings']
       }>(`/knowledge/search?${params.toString()}`)
       const data = payload.data ?? {}
       const hits: RecallHitView[] = (data.hits ?? []).map(hit => ({
@@ -280,22 +414,39 @@ export function RecallPanel({ kbId, kbName, visible, variant = 'recall', default
         score: Number(hit.score ?? 0),
         ...(hit.status ? { status: hit.status } : {}),
         ...(hit.entityType ? { entityType: hit.entityType } : {}),
+        ...(hit.entityId ? { entityId: hit.entityId } : {}),
         ...(hit.rerankScore === undefined ? {} : { rerankScore: hit.rerankScore }),
       }))
-      const context: ContextItemView[] = (data.context ?? []).map(item => ({
-        unitId: item.note?.unitId ?? item.note?.title ?? 'unknown',
-        title: item.note?.title ?? item.note?.unitId ?? '未命名切片',
-        snippet: snippetOf(item.note?.content ?? ''),
-        score: Number(item.note?.score ?? 0),
-        ...(item.note?.rerankScore === undefined ? {} : { rerankScore: item.note.rerankScore }),
-        ...(item.wiki?.title ? { wikiTitle: item.wiki.title } : {}),
-        ...(item.wiki?.entityId ? { wikiId: item.wiki.entityId } : {}),
-      }))
+      /**
+       * 0050 起上下文按**卡片**去重：一条 = 一张卡片 + 它命中的那些 note。
+       * 1 跳扩展来的卡片没有 note，所以这里用卡片自己兜底，并带上 `reason` ——
+       * 界面必须能分清「召回来的」与「邻居」（前者是证据，后者是延伸）。
+       */
+      const context: ContextItemView[] = (data.context ?? []).map(item => {
+        const note = item.note
+        const card = item.wiki
+        const expansion = item.reason === 'expansion'
+        return {
+          unitId: note?.unitId ?? (card?.entityType && card?.entityId ? `${card.entityType}:${card.entityId}` : 'unknown'),
+          title: note?.title ?? card?.title ?? '未命名',
+          snippet: snippetOf(note?.content ?? card?.summary ?? ''),
+          score: Number(note?.score ?? 0),
+          reason: expansion ? 'expansion' : 'hit',
+          ...(note?.rerankScore === undefined ? {} : { rerankScore: note.rerankScore }),
+          ...(card?.title ? { wikiTitle: card.title } : {}),
+          ...(card?.entityId ? { wikiId: card.entityId } : {}),
+          ...(expansion && item.via ? { via: `${item.via.title}（${item.via.relation}）` } : {}),
+        }
+      })
       setResult({
         count: hits.length,
         backend: data.backend ?? 'fts',
         routes: data.routes,
         contextCount: context.length,
+        ...(data.budget?.hitCards === undefined ? {} : { hitCards: data.budget.hitCards }),
+        ...(data.budget?.expandedCards === undefined ? {} : { expandedCards: data.budget.expandedCards }),
+        ...(data.budget?.omittedCards === undefined ? {} : { omittedCards: data.budget.omittedCards }),
+        ...(data.budget?.overflowPath === undefined ? {} : { overflowPath: data.budget.overflowPath }),
         recallTopK: topK,
         candidatePool: data.candidatePool,
         contextTopN: Math.min(topN, topK),
@@ -313,6 +464,35 @@ export function RecallPanel({ kbId, kbName, visible, variant = 'recall', default
         ...(data.diagnostics?.encoder === undefined ? {} : { encoder: data.diagnostics.encoder }),
         hits,
         context,
+        // 账本（0050）：每一路的全部候选 + 重排的全部候选。缺字段时给空数组而不是
+        // undefined —— 界面按「这一路没有候选」渲染，与「这次没取到账本」不是一回事，
+        // 而后者只可能出现在老服务端上。
+        ledger: {
+          fts: data.ledger?.fts ?? [],
+          vector: data.ledger?.vector ?? [],
+          rerank: (data.ledger?.rerank ?? []).map(row => ({ ...row, fused: Number(row.fused ?? row.score ?? 0), dropped: row.dropped === true })),
+        },
+        wiki: (data.wiki ?? []).map(card => ({
+          entityId: card.entityId ?? '',
+          entityType: card.entityType ?? '',
+          title: card.title ?? card.entityId ?? '未命名卡片',
+          ...(card.summary ? { summary: card.summary } : {}),
+          noteCount: context.filter(item => item.wikiId === card.entityId && item.reason === 'hit').length,
+        })),
+        ...(data.expansion === undefined ? {} : {
+          expansion: {
+            nodes: (data.expansion?.nodes ?? []).map(node => ({
+              entityType: node.entityType ?? '',
+              entityId: node.entityId ?? '',
+              title: node.title ?? node.entityId ?? '未命名卡片',
+              via: node.via ?? [],
+              included: (data.expansion?.included ?? []).includes(`${node.entityType}:${node.entityId}`),
+            })),
+            edgeCount: (data.expansion?.edges ?? []).length,
+            included: data.expansion?.included ?? [],
+          },
+        }),
+        ...(data.timings === undefined ? {} : { timings: data.timings }),
         ...(kbName ? { kbName } : {}),
         ...(data.indexVersion === undefined ? {} : { indexVersion: data.indexVersion }),
       })
@@ -323,22 +503,66 @@ export function RecallPanel({ kbId, kbName, visible, variant = 'recall', default
     }
   }
 
-  const title = variant === 'runner' ? '单问题召回检查' : '召回重排 · 三路召回 + 精排'
-  const description = variant === 'runner'
-    ? '换路线、调 topK，然后看真正命中的切片与得分 —— 不是只看一个命中总数。'
-    : '跑一次真实召回，从上到下看完整条链：三路各自命中了什么 → 融合后的排序 → cross-encoder 丢了多少 → 最终进入模型上下文的 topN 是哪几条。'
+  const title = variant === 'runner' ? '单问题召回检查' : '召回 · 精排'
+  // 这一栏没有「一句话说明」：那条步骤轨就是说明。每一步带自己的计数，
+  // 「两路各自命中了什么 → 融合排序 → 精排丢了多少 → 进上下文的是哪几条」
+  // 这句话由轨上的真实数字说，比一句固定文案准，也不会随实现变化而过期。
+
+  /**
+   * 三步的事实行（0050 改版）：每一步说清「这一段现在是多少」。
+   *
+   * 没跑过时写「未运行」，不编一个 0 —— 与知识库那条步骤轨同一条纪律：没有数据的那一步
+   * 宁可只写动作。三个步骤**一直在**（它是这条链路的结构，不是运行结果的一部分）。
+   */
+  const routesDetail = result?.routesDetail ?? []
+  const keptOf = (route: string): number | undefined => routesDetail.find(item => item.route === route)?.kept
+  /**
+   * 耗时怎么读：小于 1 秒给毫秒（向量扫描只有几毫秒，显示成「0.0s」等于没显示），
+   * 超过 1 秒给秒（首次加载模型是 8 秒，写 8300ms 反而难读）。
+   */
+  const ms = (value: number | undefined): string => {
+    if (value === undefined || !Number.isFinite(value)) return ''
+    return value < 1000 ? `${Math.round(value)}ms` : `${(value / 1000).toFixed(1)}s`
+  }
+  const timings = result?.timings
+  const steps: Array<{ id: RecallStep; icon: typeof Search; label: string; verb: string; value: string; note: string; cost: string; costTitle: string }> = [
+    {
+      id: 'recall', icon: Search, label: '召回', verb: '找',
+      value: result ? `关键词 ${keptOf('fts') ?? 0} · 向量 ${keptOf('vector') ?? 0}` : '未运行',
+      note: '两路各自过阈值的条数',
+      cost: timings ? ms(timings.ftsMs + timings.vectorMs) : '',
+      costTitle: timings
+        ? `关键词 ${ms(timings.ftsMs)}${timings.embedMs === undefined ? '' : ` · 查询编码 ${ms(timings.embedMs)}${timings.scanMs === undefined ? '' : ` · 索引扫描 ${ms(timings.scanMs)}`}`}`
+        : '',
+    },
+    {
+      id: 'rerank', icon: ArrowUpDown, label: '重排', verb: '排',
+      value: result ? `保留 ${result.count} · 丢 ${result.rerankDropped ?? 0}` : '未运行',
+      note: result?.rerankThreshold === undefined
+        ? 'cross-encoder 精排候选池'
+        : `阈值 ${result.rerankThreshold} · 最高 ${(result.rerankTopLogit ?? 0).toFixed(2)}`,
+      cost: timings?.rerankMs === undefined ? '' : ms(timings.rerankMs),
+      costTitle: result?.rerank !== 'ready' ? '这次没跑重排' : 'cross-encoder 打分（首次含加载模型）',
+    },
+    {
+      id: 'expand', icon: GitBranch, label: '扩展', verb: '展',
+      value: result ? `${result.hitCards ?? 0} 张 + ${result.expandedCards ?? 0} 张` : '未运行',
+      note: '命中的卡片 + 1 跳邻居',
+      cost: timings ? ms(timings.assembleMs) : '',
+      costTitle: timings ? `组装：按卡片去重 + 1 跳扩展 + 上下文预算` : '',
+    },
+  ]
+  const finalWiki = (result?.hitCards ?? 0) + (result?.expandedCards ?? 0)
 
   return <Card className={styles.workspaceCard}>
     <div className={styles.cardHeader}>
       <div><h3><Search size={14} />{title}</h3></div>
-      <div className={styles.cardHeaderActions}>
-        {settingsChip}
-        <Badge tone={result?.backend === 'hybrid' ? 'success' : 'neutral'}>{result?.backend === 'hybrid' ? '三路融合' : 'FTS fallback'}</Badge>
-      </div>
+      <div className={styles.cardHeaderActions}>{settingsChip}</div>
     </div>
     <div className={styles.recallTop}>
-      <p className={styles.cardDescription}>{description}</p>
       <span className={styles.recallScope}>作用范围 <b>{result?.kbName ?? kbName ?? '默认知识库'}</b></span>
+      {/* 总耗时放在作用范围这一行：它是这一屏的抬头，不属于任何一步。 */}
+      {result?.timings && <span className={styles.recallTiming} title="从查询进来到上下文组装完成">本次 {ms(result.timings.totalMs)}</span>}
     </div>
     <div className={styles.inputRow}>
       <Input value={query} placeholder="例如：销售额如何计算"
@@ -348,17 +572,13 @@ export function RecallPanel({ kbId, kbName, visible, variant = 'recall', default
         {variant === 'runner' && <Play size={13} />}{busy ? '测试中…' : variant === 'runner' ? '运行检查' : '测试'}
       </Button>
     </div>
+    {/* 旋钮集中在**一处**（0050 第二版）：路线、召回 topK、上下文 topN 是同一次运行的参数，
+        分散到各步骤里意味着「想改 topN 得先切到第三步」—— 那是把布局当成了状态。 */}
     <div className={styles.recallControls}>
       <div className={styles.recallControl}>
         <span>路线</span>
-        <SelectMenu
-          className="w-auto"
-          value={mode}
-          disabled={busy}
-          onValueChange={setMode}
-          aria-label="召回路线"
-          options={RECALL_MODES.map(item => ({ value: item.id, label: item.label }))}
-        />
+        <SelectMenu className="w-auto" value={mode} disabled={busy} onValueChange={setMode} aria-label="召回路线"
+          options={RECALL_MODES.map(item => ({ value: item.id, label: item.label }))} />
       </div>
       <label>召回 topK
         <Input type="number" min={1} max={50} value={topK} disabled={busy}
@@ -370,30 +590,101 @@ export function RecallPanel({ kbId, kbName, visible, variant = 'recall', default
       </label>
     </div>
     {error && <p className={cn(styles.kbNotice, styles.kbNoticeError)} role="alert">{error}</p>}
-    <RecallRoutes routes={result?.routes ?? []} backend={result?.backend} routesDetail={result?.routesDetail} graphBoost={result?.graphBoost} />
     {/* 弃答不是失败，是一个结论：知识库里没有能回答这个问题的东西。如实说出来，
         而不是把 5 条噪声塞给模型让它编。 */}
     {result?.insufficientEvidence && <p className={cn(styles.kbNotice, styles.kbNoticeError)} role="status">
       <CircleHelp size={13} /><span>知识库里没有能回答这个问题的内容{result.diagnosticsReason ? `：${result.diagnosticsReason}` : ''}（判据：{result.abstention === 'rerank-threshold' ? '重排阈值' : result.abstention === 'vector-threshold' ? '向量余弦阈值' : '关键词相对阈值，判据较弱'}）</span>
     </p>}
-    {result && <Badge className={styles.resultBadge} tone={result.insufficientEvidence ? 'warning' : 'success'}>
-      <Check size={13} />命中 {result.count} 条 wikiNotes · 上下文 {result.contextCount} 条{result.candidatePool ? ` · 候选池 ${result.candidatePool}` : ''}{result.rerank ? ` · rerank ${result.rerank}${result.rerankThreshold === undefined ? '' : `（阈值 ${result.rerankThreshold}${result.rerankDropped ? `，丢 ${result.rerankDropped}` : ''}${result.rerankTopLogit === undefined ? '' : `，最高 ${result.rerankTopLogit.toFixed(2)}`}）`}` : ''}
-    </Badge>}
-    {result && (result.hits.length > 0
-      ? <HitList hits={result.hits} />
-      : <div className={styles.emptyState}><CircleHelp size={16} />这个路线组合没有命中任何 wikiNote</div>)}
-    {result && result.context.length > 0 && <>
-      <div className={styles.kbSubHead}><h4>进入上下文包的 topN</h4><span>{result.context.length} 条</span></div>
-      <ContextList items={result.context} provider={result.rerankProvider} />
+
+    {/* 一条**步骤轨**，不是三个并列的 tab：召回 → 重排 → 扩展是有方向的（找 → 排 → 展），
+        方向本身就是信息。每一步带上它自己的计数，所以「这次到底发生了什么」不用再写一句
+        技术总结 —— 那句话说不了三步各自的账。 */}
+    <nav className={cn(styles.kbSteps, styles.recallSteps)} aria-label="召回链路">
+      {steps.map((step, index) => {
+        const Icon = step.icon
+        const on = tab === step.id
+        return <Fragment key={step.id}>
+          {index > 0 && <span className={styles.kbStepArrow} aria-hidden="true"><ChevronRight size={13} /></span>}
+          <button type="button" className={cn(styles.kbStep, on && styles.kbStepOn)}
+            aria-current={on ? 'step' : undefined}
+            title={`${step.label}：${step.value} · ${step.note}`}
+            onClick={() => setTab(step.id)}>
+            <span className={styles.kbStepTop}>
+              <Icon size={13} aria-hidden="true" /><b>{step.label}</b><em className={styles.kbStepVerb}>{step.verb}</em>
+              {step.cost && <em className={styles.kbStepCost} title={step.costTitle}>{step.cost}</em>}
+            </span>
+            <span className={styles.kbStepFacts}>
+              <span className={styles.kbStepValue}>{step.value}</span>
+              <span className={styles.kbStepNote}>{step.note}</span>
+            </span>
+          </button>
+        </Fragment>
+      })}
+    </nav>
+
+    {tab === 'recall' && <>
+      {/* 路由标签：点一下就只看这一路的候选（该路自己的分数与名次）。 */}
+      <div className={styles.recallRoutes}>
+        <button type="button" className={cn(styles.routeChip, routeView === 'all' && styles.routeChipOn)} onClick={() => setRouteView('all')}>
+          融合后命中 {result?.hits.length ?? 0}
+        </button>
+        {RECALL_ROUTES.map(route => {
+          const detail = routesDetail.find(item => item.route === route.id)
+          const rows = route.id === 'fts' ? result?.ledger?.fts ?? [] : result?.ledger?.vector ?? []
+          const kept = detail?.kept ?? rows.filter(row => row.kept).length
+          const total = detail?.candidates ?? rows.length
+          // 降级与「这一路没有候选」是两件事：前者要能一眼看出来（0031 的诚实边界）。
+          const degraded = detail?.status === 'degraded'
+          return <button key={route.id} type="button"
+            title={degraded && detail?.reason ? `${route.hint} —— ${detail.reason}` : route.hint}
+            className={cn(styles.routeChip, routeView === route.id && styles.routeChipOn, degraded && styles.routeChipOff)}
+            onClick={() => setRouteView(route.id as 'fts' | 'vector')}>
+            {route.label} {degraded ? '降级' : `${kept}/${total}`}
+          </button>
+        })}
+      </div>
+      {!result
+        ? <div className={styles.emptyState}><CircleHelp size={16} />先在上面输入一个查询，点「测试」跑一次召回</div>
+        : routeView === 'all'
+          ? (result.hits.length > 0
+            ? <HitList hits={result.hits} />
+            : <div className={styles.emptyState}><CircleHelp size={16} />这个路线组合没有命中任何 wikiNote</div>)
+          : <LedgerList
+            rows={routeView === 'fts' ? result.ledger?.fts ?? [] : result.ledger?.vector ?? []}
+            scoreLabel={row => row.score.toFixed(3)}
+            droppedLabel="低于阈值"
+          />}
     </>}
-    <div className={styles.infoList}>
-      <div><span>召回 topK</span><strong>{result?.recallTopK ?? topK}</strong></div>
-      <div><span>上下文 topN</span><strong>{result?.contextTopN ?? Math.min(topN, topK)}</strong></div>
-      <div><span>默认召回路线</span><strong>{mode}</strong></div>
-      {/* 词表是重排能不能用的**可见证据**：只有 5 个特殊 token 时模型照样出分，
-          所以「真的加载了 250002 条词表」这件事得看得见（0031）。 */}
-      {result?.rerankVocabSize !== undefined && <div><span>重排词表</span><strong>{result.rerankVocabSize}</strong></div>}
-      <div><span>索引版本</span><strong>{result?.indexVersion ? `v${result.indexVersion}` : '—'}</strong></div>
-    </div>
+
+    {tab === 'rerank' && (result === null
+      ? <div className={styles.emptyState}><CircleHelp size={16} />先跑一次召回，这里显示候选池里每一条的重排分</div>
+      : result.rerank !== 'ready'
+        ? <>
+          <p className={styles.kbHint}>这次没有跑重排（{result.rerank ?? 'skipped'}），下面是融合顺序 —— 分数是 RRF 融合分，不是模型分。</p>
+          <LedgerList rows={result.ledger?.rerank ?? []} emptyLabel="这次没有参与重排的候选" scoreLabel={row => `融合 ${(row.fused ?? row.score).toFixed(4)}`} />
+        </>
+        : <>
+          <p className={styles.kbHint}>
+            cross-encoder 对候选池的 <b>每一条</b> 打分（原始 logit，阈值 {result.rerankThreshold ?? 0.2}）：低于阈值的被丢弃并置灰 —— 这样「为什么没召回」看得见。
+          </p>
+          <LedgerList
+            rows={result.ledger?.rerank ?? []}
+            emptyLabel="这次没有参与重排的候选"
+            scoreLabel={row => row.logit === undefined ? `融合 ${(row.fused ?? row.score).toFixed(4)}` : `logit ${row.logit.toFixed(2)} · ${(row.rerankScore ?? 0).toFixed(3)}`}
+            droppedLabel={`低于阈值 ${result.rerankThreshold ?? 0.2}`}
+          />
+        </>)}
+
+    {tab === 'expand' && (result === null
+      ? <div className={styles.emptyState}><CircleHelp size={16} />先跑一次召回，这里显示最终进上下文的卡片与它们的 1 跳邻居</div>
+      : <>
+        <ExpansionView wiki={result.wiki} expansion={result.expansion} context={result.context} {...(onOpenWiki ? { onOpenWiki } : {})} />
+        <p className={styles.kbHint}>
+          最终 <b>{finalWiki} 个 wiki</b> 进上下文
+          {result.omittedCards ? `（另有 ${result.omittedCards} 张因为超出上下文预算没进去，完整内容在临时文件里）` : ''}
+          。
+        </p>
+      </>)}
+
   </Card>
 }