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

package/src/client/KnowledgePanel.tsx

@@ -13,7 +13,7 @@ import { LayoutPreview, useAgentLayout } from './DirectoryPicker.tsx'
 import { AgentPresetCard, type AgentPresetRemote } from './AgentPresetCard.tsx'
 import {
   NODE_META, NODE_ORDER, NODE_STATUS_LABEL, noteCountOf, sourceCountOf,
-  type KnowledgeStats, type KnowledgeTab, type NodeId, type PanelTab, type Tone,
+  type KnowledgeStats, type KnowledgeTab, type NodeId, type PanelTab, type Tone, type WorkspaceTabKind,
 } from './architecture.tsx'
 import { AgentArchitectureGraph } from './arch/AgentArchitectureGraph.tsx'
 import { NodeLogicPanel } from './arch/NodeLogicPanel.tsx'
@@ -24,13 +24,14 @@ import { AttributionTab } from './attribution/AttributionTab.tsx'
 import { KnowledgeBaseTab } from './KnowledgeBaseTab.tsx'
 import { IntentTab } from './IntentTab.tsx'
 import { RecallPanel } from './RecallPanel.tsx'
+import { readRemembered, remember } from './panel-state.ts'
 import { styles, toneSuffix } from './styles.ts'
 import '@tita-data-agent/ui/styles.css'
 import './styles.css'
 
 interface Props {
   visible: boolean
-  onOpenTab?: (kind: 'data-sheet' | 'data-notebook') => void
+  onOpenTab?: (kind: WorkspaceTabKind) => void
   settings?: {
     intent?: SettingsScopeLike
     knowledge?: SettingsScopeLike
@@ -155,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>
@@ -167,7 +168,13 @@ function EvalTab({ visible, settings, onSelect }: { visible: boolean; settings?:
 }
 
 export function KnowledgePanel({ visible, onOpenTab, settings, remote }: Props): ReactNode {
-  const [activeTab, setActiveTab] = useState<ViewId>('overview')
+  /**
+   * 一级 tab。**起始值来自记住的位置**（`panel-state.ts`）：DSH 会重新挂载这个面板
+   * （刷新页面必然、换会话按宿主策略也会），只放在 `useState` 里的话，用户每次回来都
+   * 跳回「Agent 概览」。存的值先对着 `VIEW_ORDER` 校验 —— 上一版写下的旧 id 不能让面板
+   * 走进一个不存在的 tab。
+   */
+  const [activeTab, setActiveTab] = useState<ViewId>(() => readRemembered('view', VIEW_ORDER) ?? 'overview')
   const [stats, setStats] = useState<KnowledgeStats>({})
   const [statsLoading, setStatsLoading] = useState(false)
   const [statsError, setStatsError] = useState<string | null>(null)
@@ -230,9 +237,19 @@ export function KnowledgePanel({ visible, onOpenTab, settings, remote }: Props):
   const selectNode = (id: NodeId | null): void => { setSelected(id); setSelectedDomain(null); setNotice(null) }
   const selectDomain = (id: string | null): void => { setSelectedDomain(id); setSelected(null); setNotice(null) }
 
+  /**
+   * **换一级 tab 的唯一入口。** 三处都会换（tab 栏、节点面板的「去配置」、归因空态送人
+   * 去知识库录来源），每一处都顺手记一笔 —— 分头写的话，迟早有一处忘了记，
+   * 而那种漏表现为「从这个入口过去不记得、从那个入口过去记得」。
+   */
+  const changeTab = useCallback((tab: ViewId): void => {
+    setActiveTab(tab)
+    remember('view', tab)
+  }, [])
+
   /** 架构图节点 → 功能 tab。这是节点面板上「去配置」按钮唯一的落点。 */
   const jumpTo = (tab: PanelTab, knowledgeTab?: KnowledgeTab): void => {
-    setActiveTab(tab)
+    changeTab(tab)
     if (tab === 'knowledge' && knowledgeTab) setKnowledgeFocus({ tab: knowledgeTab, nonce: Date.now() })
   }
 
@@ -258,7 +275,7 @@ export function KnowledgePanel({ visible, onOpenTab, settings, remote }: Props):
 
   return <section className={styles.panel} aria-label="Tita Data Agent">
     {/* Tab 切换是面板外壳的一部分：它不参与 `.tita-content` 的滚动，永远停在顶部。 */}
-    <Tabs className={styles.panelTabs} value={activeTab} onValueChange={value => setActiveTab(value as ViewId)}>
+    <Tabs className={styles.panelTabs} value={activeTab} onValueChange={value => changeTab(value as ViewId)}>
       <div className={styles.tabBar}>
         <TabsList className={styles.tabsList}>
           {VIEW_ORDER.map(id => {
@@ -273,7 +290,10 @@ export function KnowledgePanel({ visible, onOpenTab, settings, remote }: Props):
         ><Settings2 size={15} /></Button>
       </div>
 
-      <div className={cn(styles.content, activeTab === 'attribution' && styles.contentStage)}>
+      {/* 两栏走「舞台」版式（自己占满高度、不参与面板滚动）：智能归因是图 + 运行面板，
+          概览是画布 + 画布内浮层。同一套语汇，同一个理由 —— 它们的内容都要自己撑满
+          可视区，让面板替它们滚会把画布推成一条可以滚出视口的纸。 */}
+      <div className={cn(styles.content, (activeTab === 'attribution' || activeTab === 'overview') && styles.contentStage)}>
 
         {/* 一级 tab 已经说明「现在是哪一页」，这里不再重复一遍标题与说明。
             只有真的出问题时才占一行：读取失败 / 读取中。 */}
@@ -286,11 +306,14 @@ export function KnowledgePanel({ visible, onOpenTab, settings, remote }: Props):
           <Button variant="ghost" size="icon" aria-label="关闭提示" title="关闭提示" onClick={() => setNotice(null)}><X size={14} /></Button>
         </Card>}
 
-        <TabsContent value="overview">
+        <TabsContent value="overview" className={styles.stageContent}>
           {/* 概览 = **一个画布**。0027 之前这里是「画布 + 右侧栏」，而问题域还收在栏底的
               折叠区里 —— 三块内容、两条边框，读起来是三个东西。现在画布是四条带
               （A/B/C 三条链路 + 一条问题域带），点节点或问题域牌子都在**画布内**的
               浮层里展开详情：不占侧栏、不缩字、可关闭。
+              0050：这一栏是**一块带发丝线的画布，整图居中、不可拖拽** ——
+              两个方向都适应容器，所以「图被拖到一边」这种状态不再存在；
+              1:1 档放不下时由容器自己出滚动条。
               设置不在这里：面板上唯一的设置入口在顶部 tab 栏最右边的齿轮里。 */}
           <AgentArchitectureGraph
             stats={stats} version={version} selected={selected}
@@ -312,7 +335,13 @@ export function KnowledgePanel({ visible, onOpenTab, settings, remote }: Props):
           <IntentTab visible={visible && activeTab === 'intent'} intent={settings?.intent} />
         </TabsContent>
 
-        <TabsContent value="knowledge">
+        {/* `forceMount`：知识库这一栏**不要在离开 tab 时卸载**。
+            它有一整套已经拉回来的状态（库列表、文件、卡片、图谱、统计），而 Radix 的
+            `TabsContent` 默认是卸载的 —— 于是每次从别的 tab 切回来，选择器先显示
+            「加载中…」、「类型定义」按钮跟着变灰，整栏白一下再长出来。那些数据并没有
+            过期，重拉一遍也不该把已经画好的东西先擦掉。
+            只有这一栏这么做：其余五栏拉的是各自独立的只读数据，卸载它们反而省事。 */}
+        <TabsContent value="knowledge" forceMount>
           <KnowledgeBaseTab
             visible={visible && activeTab === 'knowledge'}
             onChanged={() => void refreshStats()}
@@ -323,7 +352,12 @@ export function KnowledgePanel({ visible, onOpenTab, settings, remote }: Props):
         </TabsContent>
 
         <TabsContent value="attribution" className={styles.stageContent}>
-          <AttributionTab visible={visible && activeTab === 'attribution'} />
+          {/* 空态的主操作是「去知识库录来源」，所以这一栏要能把人送过去 ——
+              排查知识是从来源与卡片编译来的，它自己产不出第一份知识。 */}
+          <AttributionTab
+            visible={visible && activeTab === 'attribution'}
+            onOpenKnowledge={() => changeTab('knowledge')}
+          />
         </TabsContent>
 
         <TabsContent value="memory">

package/src/client/KnowledgeStepRail.tsx

@@ -39,6 +39,9 @@ export function KnowledgeStepRail({ tab, onChange, facts }: KnowledgeStepRailPro
           type="button"
           className={cn(styles.kbStep, on && styles.kbStepOn)}
           aria-current={on ? 'step' : undefined}
+          // 第二行的说明在窄栏下会省略号截断（它是 `nowrap` + ellipsis），
+          // 所以完整那句挂在这里 —— 截断的信息要有地方读得到。
+          title={`${item.label}：${fact.value} · ${fact.note}`}
           onClick={() => onChange(item.id)}
         >
           {/* 两行，不是一行挤四样东西。一行放「图标 + 名字 + 动作 + 计数」在宿主侧栏

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/NodeSettings.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useRef, useState, useSyncExternalStore, type ReactNode } from 'react'
-import { Button, Input, SelectMenu, Switch, cn } from '@tita-data-agent/ui/components'
+import { Button, Field, Input, SelectMenu, Switch, cn } from '@tita-data-agent/ui/components'
 import { AlertCircle, Check, LoaderCircle, SlidersHorizontal } from '@tita-data-agent/ui/icons'
 import { DirectoryPickerField } from './DirectoryPicker.tsx'
 import { InfoHint } from './InfoHint.tsx'
@@ -203,9 +203,13 @@ function needsDebounce(spec: FieldSpec): boolean {
 }
 
 function TextField({ spec, value, onChange, disabled, resolved }: { spec: FieldSpec; value: string; onChange: (value: string) => void; disabled: boolean; resolved?: string }) {
-  return <label className="tita-settingField">
-    <span>{spec.label}</span>
+  /* 两条说明各自成行：`Field` 的说明位是一个 span，两条挤在一行会读成一句。 */
+  const hint = <>
+    {spec.hint ? <span className="block">{spec.hint}</span> : null}
     {/* 留空 = 自动。占位符显示**解析后**的真实路径 —— 否则「自动」等于没说。 */}
+    {resolved ? <span className="block">留空 = 自动：<code>{resolved}</code></span> : null}
+  </>
+  return <Field label={spec.label} hint={hint}>
     <Input
       type={spec.kind === 'number' ? 'number' : 'text'}
       value={value}
@@ -213,23 +217,20 @@ function TextField({ spec, value, onChange, disabled, resolved }: { spec: FieldS
       {...(resolved ? { placeholder: resolved } : {})}
       onChange={event => onChange(event.target.value)}
     />
-    {/* 说明跟在它解释的那个字段下面，不是攒成一堆放在面板底部 ——
-        底部那行「字段名：说明；字段名：说明」是把标签和说明各念一遍。 */}
-    {spec.hint && <small className="tita-settingHint">{spec.hint}</small>}
-    {resolved && <small className="tita-settingHint">留空 = 自动：<code>{resolved}</code></small>}
-  </label>
+  </Field>
 }
 
 /**
- * A dropdown field. The wrapper is a `<div>`, not the `<label>` the text and
- * toggle fields use: the control is a `<button>` now (Radix's trigger), and a
- * `<label>` around a button makes the visible field name an ambiguous second
- * name. The name travels on the trigger's `aria-label` instead, and the visible
- * `<span>` stays the thing a person reads.
+ * A dropdown field.
+ *
+ * `as="div"`, not the `<label>` the text and toggle fields use: the control is a
+ * `<button>` now (Radix's trigger), and a `<label>` around a button makes the
+ * visible field name an ambiguous second name — clicking the caption would also
+ * open the menu. The name travels on the trigger's `aria-label` instead, and the
+ * visible caption stays the thing a person reads.
  */
 function SelectField({ spec, value, onChange, disabled }: { spec: FieldSpec; value: string; onChange: (value: string) => void; disabled: boolean }) {
-  return <div className="tita-settingField">
-    <span>{spec.label}</span>
+  return <Field as="div" label={spec.label} hint={spec.hint}>
     <SelectMenu
       value={value}
       disabled={disabled}
@@ -237,25 +238,22 @@ function SelectField({ spec, value, onChange, disabled }: { spec: FieldSpec; val
       options={spec.options ?? []}
       aria-label={spec.label}
     />
-    {spec.hint && <small className="tita-settingHint">{spec.hint}</small>}
-  </div>
+  </Field>
 }
 
 /**
  * 开关字段。
  *
- * 它现在和文本 / 下拉 / 目录选择**共用同一套结构**：标签在上、控件在中、说明在下。
+ * 它和文本 / 下拉 / 目录选择**共用同一套结构**：标签在上、控件在中、说明在下。
  *
  * 原来它是「带边框和底色的整行」，另外三种是无边框的堆叠 —— 四种字段两种长相，而且
  * 标签用 `<strong>`、说明塞在标签里，对齐方式也对不上。更实际的问题是那个边框：
  * 小节本身已经是一张卡片，字段再包一层就是**卡片套卡片**。
  */
 function ToggleField({ spec, value, onChange, disabled }: { spec: FieldSpec; value: boolean; onChange: (value: boolean) => void; disabled: boolean }) {
-  return <label className="tita-settingField">
-    <span>{spec.label}</span>
+  return <Field label={spec.label} hint={spec.hint}>
     <Switch checked={value} disabled={disabled} onCheckedChange={onChange} />
-    {spec.hint && <small className="tita-settingHint">{spec.hint}</small>}
-  </label>
+  </Field>
 }
 
 /** 写入状态。`saved` 只短暂出现，`error` 留到下一次改动。 */