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

package/src/client/KnowledgePanel.tsx

@@ -156,7 +156,7 @@ function EvalTab({ visible, settings, onSelect }: { visible: boolean; settings?:
         <p className={styles.cardDescription}>评测集接入前，这一栏只声明要评什么；左边的单问题检查已经是真实链路。</p>
         <div className={styles.evalRows}>
           <div><span>编译正确性</span><strong>待运行</strong></div>
-          <div><span>三路 Hybrid Recall@10</span><strong>待运行</strong></div>
+          <div><span>Hybrid Recall@10（关键词 + 向量）</span><strong>待运行</strong></div>
           <div><span>引用可追溯性</span><strong>待运行</strong></div>
           <div><span>多模态 Markdown</span><strong>待运行</strong></div>
           <div><span>增量编译复用率</span><strong>待运行</strong></div>
@@ -311,8 +311,9 @@ export function KnowledgePanel({ visible, onOpenTab, settings, remote }: Props):
               折叠区里 —— 三块内容、两条边框，读起来是三个东西。现在画布是四条带
               （A/B/C 三条链路 + 一条问题域带），点节点或问题域牌子都在**画布内**的
               浮层里展开详情：不占侧栏、不缩字、可关闭。
-              0042：这一栏改走「舞台」版式，画布不再是一张会自动收缩的卡片 ——
-              它占满可视高度、只按宽度适应，纵向溢出靠空格 + 拖拽平移。
+              0050：这一栏是**一块带发丝线的画布，整图居中、不可拖拽** ——
+              两个方向都适应容器，所以「图被拖到一边」这种状态不再存在；
+              1:1 档放不下时由容器自己出滚动条。
               设置不在这里：面板上唯一的设置入口在顶部 tab 栏最右边的齿轮里。 */}
           <AgentArchitectureGraph
             stats={stats} version={version} selected={selected}

package/src/client/KnowledgeToolRow.tsx

@@ -0,0 +1,331 @@
+/**
+ * 知识工具在**对话流**里的卡片（0045）。
+ *
+ * ## 为什么要有它
+ *
+ * 0045 之前，`import_sources` / `recall_knowledge` 这类调用在对话里只有两样东西：工具名
+ * 和一坨 JSON。人看到的是「import_sources」加一屏花括号，于是「Agent 到底导了几份、
+ * 编出了几张卡、召回命中哪几条」只能自己去右边面板里找 —— 而右侧面板压根不知道
+ * 刚才那一次调用做了什么。
+ *
+ * 现在这一层注册的是平台的 `tool.call.toolview` 槽位，按**工具名**命中
+ * （`key: 'recall_knowledge'`），命中即**替换**默认的通用行。数据有两个来源：
+ *
+ * 1. **参数**（`block.argsRaw` / `phase === 'start'`）：跑起来的那一刻就能显示
+ *    「导入 12 份来源并编译」，不必等结果；
+ * 2. **`block.meta`**：宿主侧 `presentationMeta` 产出的结构化账本（见 `src/present.ts`），
+ *    随会话日志落盘，所以**回放时与当时看到的一模一样**。
+ *
+ * ## 三条实现约束
+ *
+ * - 卡片长在**对话区**里，不是右侧面板里：排版密度、字号跟着对话走（13px / 24px 行高），
+ *   不套面板那套 11px 的小字。颜色仍然读同一份共享令牌（`--tita-*` 挂在 `:root, body`
+ *   上），所以深浅色主题自动一致。
+ * - **不猜**。meta 缺字段就少显示一行，不编造 0 或「未知」。宿主没给 meta（旧会话、或
+ *   调用在复合传输里跑的）时退回默认通用行 —— 由 `undefined` 返回触发。
+ * - 参数解析失败**不抛**：一条工具记录因为渲染报错整块消失，比显示得不好看严重得多。
+ */
+
+import type { ReactNode } from 'react'
+import {
+  ChevronRight, Database, FileText, Layers3, RefreshCw, Search, TriangleAlert, X,
+} from '@tita-data-agent/ui/icons'
+import { Badge, cn } from '@tita-data-agent/ui/components'
+
+/** 本插件注册了专用卡片的工具名 —— 与 `src/index.ts` 里的注册一一对应。 */
+export const KNOWLEDGE_TOOL_KEYS = ['import_sources', 'recall_knowledge', 'rebuild_knowledge', 'add_source', 'propose_wiki_cards'] as const
+
+/**
+ * 槽位 props 的**结构性子集**。
+ *
+ * 平台把 `tool.call.toolview` 的完整类型声明在 `@deepseek-ai/dsh-client-ui-tool/client`，
+ * 而那个包不在本插件的依赖里（客户端只 inject 了 sidebar-right / slots / renderer /
+ * settings 四个）。为一个**纯类型**去加一条 peer dependency，代价是发布面与安装面都变大，
+ * 而这里真正用到的只有五个字段。
+ *
+ * 所以：自己声明这五个字段 + 把槽位登记进 `SlotMap`（下面那段 `declare module`），
+ * 形状以平台那份声明为准（`ToolCallCommonProps` + 三个阶段 props）。
+ * **平台那份一旦改名，这里会编译不过** —— 那正是我们想要的失败方式。
+ */
+export interface KnowledgeToolViewProps {
+  /** 三个阶段二选一：`preparing` 连参数都没有。 */
+  phase: 'preparing' | 'start' | 'result'
+  /** 平台派发用的工具名（本卡片的键）。 */
+  toolName: string
+  callId: string
+  block: {
+    /** 只有 `start` 阶段有完整参数。 */
+    argsRaw?: string
+    /** 结果阶段：模型可见的内容块。 */
+    content?: readonly unknown[]
+    isError?: boolean
+    /** 宿主 `presentationMeta` 落下来的账本。 */
+    meta?: unknown
+  }
+  /** 平台提供的展开状态钩子：**每个调用各自持有**，切轮次会被重置。 */
+  useDisclosure: () => { readonly expanded: boolean; readonly setExpanded: (open: boolean) => void; readonly toggle: () => void }
+  /** 在轨迹视图里定位这次调用（可能没有）。 */
+  inspect?: () => void
+}
+
+/**
+ * 把槽位登记进平台的 `SlotMap`。
+ *
+ * 平台自己的声明在 `dsh-client-ui-tool/client` 里；这里补一份**同样的形状**，因为那个包
+ * 不在本插件的类型可见范围内。运行时不受影响 —— 派发按名字字符串走，这段只在编译期
+ * 让 `slots.register({ name: 'tool.call.toolview' })` 通过检查。
+ */
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    'tool.call.toolview': { kind: 'keyed'; scope: 'session'; owner: KnowledgeToolViewProps }
+  }
+}
+
+/** meta 里那本账的最小形状。所有字段都可缺：旧会话、失败信封都可能是残的。 */
+interface ToolMeta {
+  kind?: string
+  // 导入
+  attempted?: number
+  written?: Array<{ sourceId?: string; title?: string; bytes?: number }>
+  failed?: Array<{ index?: number; title?: string; code?: string; message?: string }>
+  compile?: { cardsCreated?: number; cardsUpdated?: number; cardsReused?: number; notesReused?: number; notesRecompiled?: number; sourcesExtracted?: number; sourcesSkipped?: number; embedding?: string; version?: number } | null
+  // 召回
+  query?: string
+  hits?: Array<{ entityId?: string; entityType?: string; title?: string; score?: number; rerankScore?: number; reviewScore?: number }>
+  contextTopN?: number
+  backend?: string
+  routes?: string[]
+  rerankStatus?: string
+  insufficientEvidence?: boolean
+  // 编译
+  only?: string
+  version?: number
+  cardsCreated?: number
+  cardsUpdated?: number
+  cardsReused?: number
+  notesReused?: number
+  notesRecompiled?: number
+  sourcesExtracted?: number
+  sourcesSkipped?: number
+  embedding?: string
+  skipped?: boolean
+  // 写卡
+  ids?: string[]
+  // 单份来源
+  sourceId?: string
+  path?: string
+  title?: string
+  sourceType?: string
+  bytes?: number
+  rejected?: Array<{ title?: string; reason?: string; code?: string }>
+}
+
+/** 参数：`phase === 'preparing'` 时还没有，别去猜。 */
+function argsOf(block: unknown): Record<string, any> {
+  const raw = (block as { argsRaw?: unknown } | undefined)?.argsRaw
+  if (typeof raw !== 'string' || raw.trim() === '') return {}
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' ? parsed as Record<string, any> : {}
+  } catch {
+    return {}
+  }
+}
+
+/** 模型可见的文本结果 —— 结果阶段之外用它兜底（也用于错误态）。 */
+function textOf(block: unknown): string {
+  const content = (block as { content?: unknown } | undefined)?.content
+  if (!Array.isArray(content)) return ''
+  return content
+    .map(part => (part && typeof part === 'object' && (part as { type?: string }).type === 'text' ? String((part as { text?: unknown }).text ?? '') : ''))
+    .filter(Boolean)
+    .join('\n')
+}
+
+function short(text: string, max = 60): string {
+  const flat = text.replace(/\s+/g, ' ').trim()
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat
+}
+
+/** 标题与摘要：**先写这一下要动什么**，结果回来之后再补上产物。 */
+function headOf(toolName: string, args: Record<string, any>, meta: ToolMeta | null): { icon: ReactNode; title: string; summary: string } {
+  const icon = (size = 14): ReactNode => {
+    switch (toolName) {
+      case 'recall_knowledge': return <Search size={size} />
+      case 'import_sources': return <Database size={size} />
+      case 'rebuild_knowledge': return <RefreshCw size={size} />
+      case 'propose_wiki_cards': return <Layers3 size={size} />
+      default: return <FileText size={size} />
+    }
+  }
+  if (toolName === 'recall_knowledge') {
+    const query = short(String(meta?.query ?? args?.query ?? ''), 36)
+    const hits = meta?.hits?.length
+    const summary = meta?.insufficientEvidence
+      ? '没有内容越过相关性阈值'
+      : meta
+        ? [hits !== undefined ? `命中 ${hits} 条` : '', meta.backend ? `${meta.backend}` : '', meta.contextTopN !== undefined ? `进上下文 ${meta.contextTopN} 条` : ''].filter(Boolean).join(' · ')
+        : '正在检索…'
+    return { icon: icon(), title: `召回「${query}」`, summary }
+  }
+  if (toolName === 'import_sources') {
+    const count = Array.isArray(args?.sources) ? args.sources.length : 0
+    const summary = meta
+      ? [
+        `写入 ${meta.written?.length ?? 0} 份`,
+        meta.failed && meta.failed.length > 0 ? `失败 ${meta.failed.length} 份` : '',
+        meta.compile ? `新建 ${meta.compile.cardsCreated ?? 0} 张卡 · 并入 ${meta.compile.cardsUpdated ?? 0} 张` : '未编译',
+      ].filter(Boolean).join(' · ')
+      : '正在写入并编译…'
+    return { icon: icon(), title: `导入 ${count} 份来源${args?.compile === false ? '' : '并编译'}`, summary }
+  }
+  if (toolName === 'rebuild_knowledge') {
+    const only = String(meta?.only ?? args?.only ?? 'all')
+    const what = only === 'all' ? '全链路' : only === 'wiki' ? 'wiki 与 wikiNotes' : only === 'embeddings' ? '向量索引' : '注册表'
+    const summary = meta
+      ? meta.skipped
+        ? '没有变化，全部复用'
+        : `新建 ${meta.cardsCreated ?? 0} · 并入 ${meta.cardsUpdated ?? 0} · 复用 ${meta.cardsReused ?? 0}${meta.version !== undefined ? ` · v${meta.version}` : ''}`
+      : '正在编译…'
+    return { icon: icon(), title: `编译知识库 · ${what}`, summary }
+  }
+  if (toolName === 'propose_wiki_cards') {
+    const count = Array.isArray(args?.proposals) ? args.proposals.length : 0
+    const summary = meta
+      ? `入库 ${meta.ids?.length ?? 0} 张${meta.rejected && meta.rejected.length > 0 ? ` · 被拒 ${meta.rejected.length} 张` : ''}`
+      : '正在写入…'
+    return { icon: icon(), title: `写入 ${count} 张 wiki 卡片`, summary }
+  }
+  const title = args?.title ? short(String(args.title), 30) : '(未命名)'
+  const summary = meta
+    ? `${meta.sourceType ?? 'document'} · ${meta.bytes ?? 0} 字符`
+    : '正在写入…'
+  return { icon: icon(), title: `写入来源「${title}」`, summary }
+}
+
+/** 展开之后的正文：**这一屏要回答「刚才到底发生了什么」**。 */
+function DetailsOf({ toolName, meta, fallback }: { toolName: string; meta: ToolMeta | null; fallback: string }): ReactNode {
+  if (!meta) {
+    return fallback
+      ? <pre className="max-h-[240px] overflow-auto whitespace-pre-wrap break-words rounded-lg border border-tita-line bg-tita-surface-muted p-2 font-mono text-[11px] leading-relaxed text-tita-ink-muted">{fallback}</pre>
+      : null
+  }
+  if (meta.kind === 'recall') {
+    if (meta.insufficientEvidence) {
+      return <p className="text-[12px] leading-relaxed text-tita-ink-muted">库里没有一条越过相关性阈值 —— 这是结论，不是错误。把来源导进来再问一次。</p>
+    }
+    return <div className="flex flex-col gap-1">
+      {(meta.hits ?? []).map((hit, index) => {
+        const score = typeof hit.rerankScore === 'number' ? hit.rerankScore : hit.score
+        return <div key={`${hit.entityType}:${hit.entityId}:${index}`} className="flex items-baseline gap-2 text-[12px]">
+          <span className="w-4 shrink-0 text-right tabular-nums text-tita-ink-faint">{index + 1}</span>
+          <span className="min-w-0 flex-1 truncate text-tita-ink" title={hit.title}>{hit.title || hit.entityId}</span>
+          <code className="shrink-0 font-mono text-[10.5px] text-tita-ink-faint">{hit.entityType}:{hit.entityId}</code>
+          <span className="w-12 shrink-0 text-right tabular-nums text-tita-ink-muted">{typeof score === 'number' ? score.toFixed(3) : '—'}</span>
+          {typeof hit.reviewScore === 'number' && <span className="shrink-0 text-[10.5px] text-tita-ink-faint">评分 {hit.reviewScore.toFixed(2)}</span>}
+        </div>
+      })}
+{/* 路由与重排状态：它们解释「为什么是这个顺序」，所以和命中列在同一块里。 */}
+      <p className="text-[11px] text-tita-ink-faint">
+        {[meta.backend ? `检索 ${meta.backend}` : '', meta.routes && meta.routes.length > 0 ? `路由 ${meta.routes.join('+')}` : '', meta.rerankStatus ? `重排 ${meta.rerankStatus}` : ''].filter(Boolean).join(' · ')}
+      </p>
+    </div>
+  }
+  if (meta.kind === 'import') {
+    return <div className="flex flex-col gap-1.5">
+      <ul className="flex flex-col gap-0.5">
+        {(meta.written ?? []).map(item => <li key={item.sourceId} className="flex items-baseline gap-2 text-[12px]">
+          <FileText size={11} className="mt-1 shrink-0 text-tita-ink-faint" />
+          <span className="min-w-0 flex-1 truncate text-tita-ink" title={item.title}>{item.title || item.sourceId}</span>
+          <span className="shrink-0 tabular-nums text-tita-ink-faint">{item.bytes ?? 0} 字符</span>
+        </li>)}
+      </ul>
+      {(meta.failed ?? []).length > 0 && <ul className="flex flex-col gap-0.5">
+        {(meta.failed ?? []).map(item => <li key={`${item.index}-${item.code}`} className="flex items-baseline gap-2 text-[12px] text-tita-danger">
+          <X size={11} className="mt-1 shrink-0" />
+          <span className="min-w-0 flex-1">第 {(item.index ?? 0) + 1} 份{item.title ? `「${short(item.title, 24)}」` : ''}：{item.message}</span>
+          <code className="shrink-0 font-mono text-[10.5px]">{item.code}</code>
+        </li>)}
+      </ul>}
+      {meta.compile
+        ? <p className="text-[11.5px] text-tita-ink-muted">
+          编译：新建 {meta.compile.cardsCreated ?? 0} 张 · 并入 {meta.compile.cardsUpdated ?? 0} 张 · 复用 {meta.compile.cardsReused ?? 0} 张 · wikiNotes 复用 {meta.compile.notesReused ?? 0} / 重编 {meta.compile.notesRecompiled ?? 0}
+          {meta.compile.version !== undefined ? ` · 索引 v${meta.compile.version}` : ''}
+        </p>
+        : <p className="text-[11.5px] text-tita-ink-muted">这次没有编译（<code className="font-mono">compile: false</code>）—— 卡片还没生成，需要时再编译一次。</p>}
+    </div>
+  }
+  if (meta.kind === 'rebuild') {
+    return <p className="text-[11.5px] leading-relaxed text-tita-ink-muted">
+      {meta.skipped ? '知识库没有变化：产物逐字复用，没有生成新的索引版本。' : <>新建 {meta.cardsCreated ?? 0} 张 · 并入 {meta.cardsUpdated ?? 0} 张 · 复用 {meta.cardsReused ?? 0} 张 · 重抽来源 {meta.sourcesExtracted ?? 0} 份 / 跳过 {meta.sourcesSkipped ?? 0} 份</>}
+      {meta.embedding ? ` · 向量 ${meta.embedding}` : ''}{meta.version !== undefined ? ` · 索引 v${meta.version}` : ''}
+    </p>
+  }
+  if (meta.kind === 'writeCards') {
+    return <div className="flex flex-col gap-1">
+      <ul className="flex flex-col gap-0.5">
+        {(meta.ids ?? []).map(id => <li key={id} className="text-[12px]"><code className="font-mono text-[11px] text-tita-ink-muted">{id}</code></li>)}
+      </ul>
+      {(meta.rejected ?? []).length > 0 && <ul className="flex flex-col gap-0.5">
+        {(meta.rejected ?? []).map((item, index) => <li key={index} className="text-[12px] text-tita-danger">{item.title ? `「${short(item.title, 24)}」` : '一条'}被拒：{item.reason ?? item.code ?? '原因未知'}</li>)}
+      </ul>}
+    </div>
+  }
+  if (meta.kind === 'addSource') {
+    return <p className="text-[11.5px] leading-relaxed text-tita-ink-muted">
+      已写入 <code className="font-mono text-[11px]">{meta.sourceId}</code>（{meta.sourceType}，{meta.bytes ?? 0} 字符）。下一步：编译它，才会生成 wiki 卡片。
+    </p>
+  }
+  return fallback
+    ? <pre className="max-h-[240px] overflow-auto whitespace-pre-wrap break-words rounded-lg border border-tita-line bg-tita-surface-muted p-2 font-mono text-[11px] leading-relaxed text-tita-ink-muted">{fallback}</pre>
+    : null
+}
+
+/**
+ * 一条知识工具调用的卡片。
+ *
+ * 返回 `null` 会让槽位退回默认通用行 —— 这是**刻意的出口**：拿到不认识的形状时，
+ * 宁可显示平台默认的样子，也不要显示一张自己编的卡。
+ */
+export function KnowledgeToolRow(props: KnowledgeToolViewProps): ReactNode {
+  const { phase, toolName, block, useDisclosure } = props
+  const { expanded, toggle } = useDisclosure()
+
+  const args = phase === 'preparing' ? {} : argsOf(block)
+  const meta = phase === 'result' ? (((block as { meta?: unknown }).meta ?? null) as ToolMeta | null) : null
+  const isError = phase === 'result' && (block as { isError?: boolean }).isError === true
+  const head = headOf(toolName, args, meta)
+  const fallback = phase === 'result' ? textOf(block) : ''
+  const details = phase === 'result' || Object.keys(args).length > 0
+  const summary = isError ? '失败' : head.summary
+
+  return <div className="flex flex-col" data-tool={toolName} data-phase={phase}>
+    <button
+      type="button"
+      className={cn(
+        'group flex w-full min-w-0 items-center gap-1.5 py-0.5 text-left',
+        details ? 'cursor-pointer' : 'cursor-default',
+      )}
+      aria-expanded={details ? expanded : undefined}
+      onClick={() => { if (details) toggle() }}
+    >
+      <span className={cn('flex size-4 shrink-0 items-center justify-center', isError ? 'text-tita-danger' : 'text-tita-ink-faint')}>
+        {isError ? <TriangleAlert size={14} /> : head.icon}
+      </span>
+      <span className="shrink-0 text-[13px] text-tita-ink" title={head.title}>{head.title}</span>
+      <span className="size-[2px] shrink-0 rounded-full bg-tita-ink-faint" aria-hidden />
+      <span className={cn('min-w-0 flex-1 truncate text-[13px]', isError ? 'text-tita-danger' : 'text-tita-ink-faint')}>{summary}</span>
+      {meta?.kind === 'import' && (meta.failed?.length ?? 0) > 0 && <Badge tone="warning" className="shrink-0">失败 {meta.failed?.length}</Badge>}
+      {meta?.insufficientEvidence && <Badge tone="warning" className="shrink-0">无命中</Badge>}
+      {details && <ChevronRight size={12} className={cn('shrink-0 text-tita-ink-faint transition-transform', expanded && 'rotate-90')} />}
+    </button>
+    {expanded && details && <div className="mt-1 mb-1 ml-[22px]">
+      {isError
+        ? <p className="flex items-start gap-1.5 text-[12px] leading-relaxed text-tita-danger">
+          <TriangleAlert size={12} className="mt-0.5 shrink-0" />
+          <span className="min-w-0 flex-1">{short(fallback || '调用失败', 400)}</span>
+        </p>
+        : <DetailsOf toolName={toolName} meta={meta} fallback={fallback} />}
+    </div>}
+  </div>
+}

package/src/client/PreviewSections.tsx

@@ -21,10 +21,12 @@
  *    下面的分块位置不再随正文长度漂移。
  */
 
-import { useState, type ReactNode } from 'react'
-import { ChevronDown, ChevronUp, FileCode2, FileText, History, Image, ListTree } from '@tita-data-agent/ui/icons'
+import { useMemo, useState, type ReactNode } from 'react'
+import { ChevronDown, ChevronUp, FileCode2, FileText, GitBranch, History, ListTree } from '@tita-data-agent/ui/icons'
 import { Button, Tabs, TabsContent, TabsList, TabsTrigger, cn } from '@tita-data-agent/ui/components'
 import { VersionManager, type VersionManagerProps } from '@tita-data-agent/ui/versions'
+import { DrawerSectionHead } from './DrawerSection.tsx'
+import { pathImagesOf, referencedRelsOf } from './asset-images.ts'
 // 平台提供的 Markdown 原子（DSH 的模块表里有它，本插件的 client bundle 也已把它列为
 // external）。原文与卡片正文本身就是 Markdown，用 `<pre>` 显示等于把标题、表格、链接
 // 全都拍平成源码 —— 所以默认阅读态走它，源码视图是**另一个**选项，不是替代品。
@@ -63,27 +65,18 @@ export interface PreviewRow {
   value: ReactNode
   /** 等宽显示：hash / id / 路径这类要逐字比对的值。 */
   code?: boolean
-}
-
-/**
- * 抽屉里的小节头 —— 三种层级里的中间那层（标题 15px / 小节头 13px / 正文 12px）。
- * 分隔线在 `.tita-drawerSection` 上（小节与上一块之间），所以这里只管内容。
- */
-function SectionHead({ icon, title, children }: { icon: ReactNode; title: string; children?: ReactNode }): ReactNode {
-  return <div className={styles.drawerSubHead}>
-    <h4>{icon}{title}</h4>
-    {children}
-  </div>
+  /** 悬停说明。**必须渲染出来** —— 否则调用方写了它、界面上什么也没有。 */
+  title?: string
 }
 
 /** 元信息：一张两列的事实表。标签列宽固定，所以标签要短且彼此对齐。 */
 export function PreviewMeta({ rows }: { rows: PreviewRow[] }): ReactNode {
   return <section className={styles.drawerSection}>
-    <SectionHead icon={<ListTree size={13} />} title="元信息" />
+    <DrawerSectionHead icon={<ListTree size={13} />} title="元信息" />
     <dl className={styles.kbKv}>
       {rows.map(row => <div key={row.label}>
         <dt>{row.label}</dt>
-        <dd className={row.code ? styles.kbCode : undefined}>{row.value}</dd>
+        <dd className={row.code ? styles.kbCode : undefined} {...(row.title ? { title: row.title } : {})}>{row.value}</dd>
       </div>)}
     </dl>
   </section>
@@ -92,21 +85,31 @@ export function PreviewMeta({ rows }: { rows: PreviewRow[] }): ReactNode {
 export interface PreviewAsset { rel: string; url: string; bytes: number }
 
 /**
- * 内容：小节头 + 读法工具栏 + 正文（锁高内滚）。
+ * 内容：小节头 + 读法工具栏 + 正文（锁高内滚）+ 正文没提到的图。
  *
  * 两个视图是**同一份内容**的两种读法：Markdown 是阅读态（默认），文本是源码态，
  * 用于逐字核对 —— 与版本 diff 是同一种读法。切换不重新取数，也不改内容。
- * 图片素材排在这一块的末尾：它也是内容，只是渲染器没能就地展开的那部分。
+ *
+ * **图片与正文是一份内容，不是一个附件区**（0049）。此前末尾另起一块「图片素材」
+ * 网格：正文里的图已经就地渲染过一遍，末尾再排一遍，同一张图一屏里出现两次。
+ * 现在只有一份读法 —— 正文里提到过的图就地渲染，**没提到的排在正文末尾**，
+ * 都在同一个滚动容器里。独立整页也是这么读的（它靠 `resolveImage` 就地渲染）。
+ *
+ * **正文里的图要就地显示**（0047）：`MarkdownText` 的 `pathImages` 拿 `assets` 把
+ * 相对引用换成 `/knowledge/assets/...`。不接它的话，浏览器会按当前页面地址去解析
+ * `_assets/<bucket>/img-x.png`（结果是 `/_assets/...` 404），于是「预览里看不到图」。
  *
  * `totalChars` 说全文有多少字符（服务端按 `SOURCE_PREVIEW_CHARS` 封顶，
- * `content.length` 已经不是全文长度了）。读全文的出口在**抽屉头**上，不在这一块里：
- * 它是「这份东西还能去哪看」，位置要固定，不该随正文是否被截断而出现或消失。
+ * `content.length` 已经不是全文长度了）。读全文的出口由调用方放在**小节头上**
+ * （`action`）：它是「这份东西还能去哪看」，位置要固定，不该随正文是否被截断而出现或消失。
  */
-export function PreviewContent({ content, assets = [], totalChars }: {
+export function PreviewContent({ content, assets = [], totalChars, action }: {
   content: string
   assets?: PreviewAsset[]
   /** 全文总字符数。省略时按 `content.length` 算（它本来就是全文）。 */
   totalChars?: number
+  /** 小节头右侧的动作（例如「新页面打开」）。与「内容」同一行，不占正文宽度。 */
+  action?: ReactNode
 }): ReactNode {
   const [view, setView] = useState<'md' | 'text'>('md')
   /** 卡片正文超过上限时的本地展开：卡片没有整页出口，只能在这里给出路。 */
@@ -115,10 +118,27 @@ export function PreviewContent({ content, assets = [], totalChars }: {
   const total = totalChars ?? content.length
   const clipped = shown.length < total
   const canExpand = content.length > PREVIEW_CHARS
+  /**
+   * 解析器按 `assets` 的记忆化：`MarkdownText` 是 memo 组件，每次渲染换一个新对象
+   * 会让它的流式渲染缓存整体作废（平台对这个 prop 的身份有明确要求）。
+   */
+  const pathImages = useMemo(() => pathImagesOf(assets), [assets])
+  /** 正文没提到的图：排在正文末尾，与正文同一个滚动容器。 */
+  const extra = useMemo(() => {
+    const referenced = referencedRelsOf(content, assets)
+    return assets.filter(asset => !referenced.has(asset.rel))
+  }, [content, assets])
   return <section className={styles.drawerSection}>
-    <SectionHead icon={<FileText size={13} />} title="内容">
-      <span className={styles.drawerHeadFact}>{total} 字符{clipped ? ` · 这里显示前 ${shown.length}` : ''}</span>
-    </SectionHead>
+    <DrawerSectionHead icon={<FileText size={13} />} title="内容">
+      {/* 事实与动作**成组**靠右：`drawerSubHead` 是 `space-between`，三个平级子节点会
+          把「20 字符」摆到行的正中间，读起来像另一栏。 */}
+      <span className={styles.drawerHeadAside}>
+        <span className={styles.drawerHeadFact}>
+          {total} 字符{clipped ? ` · 这里显示前 ${shown.length}` : ''}{assets.length > 0 ? ` · ${assets.length} 张图` : ''}
+        </span>
+        {action}
+      </span>
+    </DrawerSectionHead>
     {/* 读法工具栏：这个分块的**两种读法**是它自己的事，不再挤进小节标题那一行。 */}
     <Tabs value={view} onValueChange={next => setView(next as 'md' | 'text')}>
       <div className={styles.drawerToolbar}>
@@ -133,21 +153,82 @@ export function PreviewContent({ content, assets = [], totalChars }: {
           {expanded ? '收起' : `展开全部（还有 ${content.length - PREVIEW_CHARS} 字符）`}</Button>}
       </div>
       <TabsContent value="md">
-        <div className={styles.drawerBody}><div className={styles.kbMarkdown}><MarkdownText text={shown} labels={MARKDOWN_LABELS} /></div></div>
+        <div className={styles.drawerBody}>
+          <div className={styles.kbMarkdown}>
+            <MarkdownText text={shown} labels={MARKDOWN_LABELS} {...(pathImages === undefined ? {} : { pathImages })} />
+          </div>
+          {extra.length > 0 && <>
+            {/* 这块不是「另一些内容」，是**同一份内容的余下部分**：正文里没出现（或落在
+                预览长度之外）的图。写清楚它是什么，人才不会以为图丢了。 */}
+            <p className={styles.kbAssetsNote}>
+              正文里没出现的图 · {extra.length} 张{clipped ? `（正文只显示前 ${shown.length} 字符）` : ''}
+            </p>
+            <div className={styles.kbAssets}>
+            {extra.map(asset => <figure key={asset.rel} className={styles.kbAsset} title={asset.rel}>
+              {/* alt 用文件名而不是整条相对路径：图挂了的时候，`01_source_raw/_assets/…`
+                  会在 84px 的格子里折成三行，把这一块撑得比正文还高。 */}
+              <img src={asset.url} alt={asset.rel.split('/').pop() ?? asset.rel} loading="lazy" />
+              <figcaption>{formatBytes(asset.bytes)}</figcaption>
+            </figure>)}
+            </div>
+          </>}
+        </div>
       </TabsContent>
       <TabsContent value="text">
         <div className={styles.drawerBody}><pre className={styles.kbPre}>{shown}</pre></div>
       </TabsContent>
     </Tabs>
-    {assets.length > 0 && <>
-      <SectionHead icon={<Image size={13} />} title="图片素材"><span className={styles.drawerHeadFact}>{assets.length} 张</span></SectionHead>
-      <div className={styles.kbAssets}>
-        {assets.map(asset => <figure key={asset.rel} className={styles.kbAsset}>
-          <img src={asset.url} alt={asset.rel} loading="lazy" />
-          <figcaption>{formatBytes(asset.bytes)}</figcaption>
-        </figure>)}
-      </div>
-    </>}
+  </section>
+}
+
+/**
+ * 相关卡片（0049）：出链与入链，两处都是**可点的入口**。
+ *
+ * 为什么正文里已经有 `## 相关` 一块、这里还要再列一遍：正文里那一块写的是
+ * `[[类型/标题]]`，是给 `grep` 和编辑器用的**文件内引用**（面板渲染不了它，卡片也没有
+ * 自己的页面地址）；这里这几行是面板里真的能点开的东西 —— 点一下换到那张卡片。两处
+ * 的清单来自同一个计划（服务端的 `planRelated`），所以不会一处写着 A、一处列着 B。
+ *
+ * 「它引用 / 引用它」分开列，是因为方向不同：前者是这张卡片自己的判断，后者是别人
+ * 把它拉进来的。合成一列就分不清「我提到它」和「它提到我」。
+ */
+export interface RelatedLink {
+  entityId: string
+  entityType: string
+  title: string
+  reason: 'relation' | 'source'
+}
+
+const RELATED_REASON: Record<RelatedLink['reason'], string> = {
+  relation: '来源里写明的关系',
+  source: '同一份来源',
+}
+
+export function PreviewRelated({ outgoing, incoming, onOpen }: {
+  outgoing: RelatedLink[]
+  incoming: RelatedLink[]
+  onOpen: (link: RelatedLink) => void
+}): ReactNode {
+  if (outgoing.length === 0 && incoming.length === 0) return null
+  const group = (label: string, links: RelatedLink[], prefix: string): ReactNode => links.length === 0 ? null : <>
+    <p className={styles.kbRelatedGroup}>{label}</p>
+    <ul className={styles.kbRelatedList}>
+      {links.map(link => <li key={`${prefix}-${link.entityType}:${link.entityId}`}>
+        <button type="button" className={styles.kbRelatedRow} title={`${link.entityType}/${link.entityId}`} onClick={() => onOpen(link)}>
+          <span className={styles.kbRelatedTitle}>{link.title}</span>
+          <span className={styles.kbRelatedMeta}>{RELATED_REASON[link.reason]}</span>
+        </button>
+      </li>)}
+    </ul>
+  </>
+  return <section className={styles.drawerSection}>
+    <DrawerSectionHead icon={<GitBranch size={13} />} title="相关卡片">
+      <span className={styles.drawerHeadFact}>{outgoing.length + incoming.length} 条</span>
+    </DrawerSectionHead>
+    <div className={styles.kbRelated}>
+      {group('它引用', outgoing, 'out')}
+      {group('引用它', incoming, 'in')}
+    </div>
   </section>
 }
 
@@ -163,7 +244,7 @@ export function PreviewContent({ content, assets = [], totalChars }: {
  */
 export function PreviewVersions({ hint, ...manager }: { hint?: string } & VersionManagerProps): ReactNode {
   return <section className={styles.drawerSection}>
-    <SectionHead icon={<History size={13} />} title="版本"><span className={styles.drawerHeadFact}>{manager.entries?.length ?? 0} 个</span></SectionHead>
+    <DrawerSectionHead icon={<History size={13} />} title="版本"><span className={styles.drawerHeadFact}>{manager.entries?.length ?? 0} 个</span></DrawerSectionHead>
     {hint && <p className={styles.kbHint}>{hint}</p>}
     <VersionManager {...manager} />
   </section>