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

package/src/client/NodeSettings.tsx

@@ -1,8 +1,7 @@
 import { useCallback, useEffect, useRef, useState, useSyncExternalStore, type ReactNode } from 'react'
 import { Button, Field, Input, SelectMenu, Switch, cn } from '@tita-agent/ui/components'
-import { AlertCircle, Check, LoaderCircle, SlidersHorizontal } from '@tita-agent/ui/icons'
-import { DirectoryPickerField } from './DirectoryPicker.tsx'
-import { InfoHint } from './InfoHint.tsx'
+import { AlertCircle, Check, ChevronDown, FolderOpen, LoaderCircle, SlidersHorizontal } from '@tita-agent/ui/icons'
+import type { SessionRemote } from './session-remote.ts'
 
 /**
  * 方案级设置。
@@ -42,16 +41,22 @@ export interface SettingsScopeLike {
   unset?(field: string): Promise<void>
 }
 
-/** 设置组。编译模板是系统固定契约，不作为用户设置暴露。 */
-export type SettingsNode = 'storage' | 'build' | 'recall' | 'context'
+/** 设置分组。编译模板是系统固定契约，不作为用户设置暴露。 */
+export type SettingsNode = 'storage' | 'build' | 'recall'
 
 interface FieldSpec {
   key: string
   label: string
-  kind: 'text' | 'number' | 'select' | 'toggle' | 'picker'
+  kind: 'text' | 'number' | 'select' | 'toggle' | 'location'
   fallback: string | number | boolean
   hint?: string
   options?: Array<{ value: string; label: string }>
+  min?: number
+  max?: number
+  step?: number
+  /** Low-level tuning stays out of the default view. */
+  advanced?: boolean
+  visibleWhen?: { key: string; value: string }
   /** Comma-separated array field: shown as text, saved as `string[]`. */
   list?: boolean
 }
@@ -59,8 +64,6 @@ interface FieldSpec {
 interface NodeSpec {
   scope: 'knowledge'
   title: string
-  /** 说明，收进标题旁的 `?`。给了才渲染 —— 存储那一组 2026-10-06 起不给（见下）。 */
-  description?: string
   fields: FieldSpec[]
 }
 
@@ -76,55 +79,42 @@ export const NODE_SETTINGS: Record<SettingsNode, NodeSpec> = {
    */
   storage: {
     scope: 'knowledge',
-    title: '存储设置',
+    title: '数据位置',
     fields: [
-      { key: 'agentRoot', label: 'Tita Agent 根路径', kind: 'picker', fallback: '' },
+      { key: 'agentRoot', label: 'Tita Agent 数据目录', kind: 'location', fallback: '' },
     ],
   },
   // 0025：`compile` 设置组已撤。卡片编译模板是系统固定契约，不是用户设置项。
   build: {
     scope: 'knowledge',
-    title: '构建设置',
-    description: '召回片段的向量编码方式与构建所用的 Python 环境。模型不可用时会降级到关键词路。',
+    title: '向量运行设置',
     fields: [
-      { key: 'embeddingProvider', label: 'Embedding Provider', kind: 'select', fallback: 'wemm-python', options: [{ value: 'wemm-python', label: 'Python 本地模型' }, { value: 'ollama', label: 'Ollama（文本）' }, { value: 'none', label: '关闭（FTS fallback）' }] },
-      { key: 'embeddingDevice', label: '运行设备', kind: 'select', fallback: 'auto', options: [{ value: 'auto', label: '自动（优先 MPS）' }, { value: 'mps', label: 'Apple MPS' }, { value: 'cpu', label: 'CPU' }] },
-      { key: 'embeddingModel', label: 'Embedding Model', kind: 'text', fallback: '', hint: '本地模型目录，或一个 HuggingFace 模型名' },
-      { key: 'embeddingBaseUrl', label: 'Embedding 地址', kind: 'text', fallback: 'http://127.0.0.1:11434' },
-      { key: 'embeddingDimension', label: '向量维度', kind: 'number', fallback: 512 },
-      { key: 'embeddingBatchSize', label: 'Embedding 批大小', kind: 'number', fallback: 8 },
-      { key: 'embeddingTimeoutMs', label: '编码超时（毫秒）', kind: 'number', fallback: 120000 },
-      { key: 'python', label: 'Python', kind: 'text', fallback: '', hint: '解释器路径；留空用根路径下那个本地环境' },
+      { key: 'embeddingProvider', label: '向量来源', kind: 'select', fallback: 'wemm-python', options: [{ value: 'wemm-python', label: '本地模型' }, { value: 'ollama', label: 'Ollama' }, { value: 'none', label: '关闭向量' }] },
+      { key: 'embeddingModel', label: 'Ollama 模型名称', kind: 'text', fallback: '', hint: '填写 Ollama 中已安装的模型名称。', visibleWhen: { key: 'embeddingProvider', value: 'ollama' } },
+      { key: 'embeddingBaseUrl', label: 'Ollama 地址', kind: 'text', fallback: 'http://127.0.0.1:11434', visibleWhen: { key: 'embeddingProvider', value: 'ollama' } },
+      { key: 'embeddingDevice', label: '运行设备', kind: 'select', fallback: 'auto', advanced: true, options: [{ value: 'auto', label: '自动' }, { value: 'mps', label: 'Apple MPS' }, { value: 'cpu', label: 'CPU' }] },
+      { key: 'embeddingDimension', label: '向量维度', kind: 'number', fallback: 512, min: 1, step: 1, advanced: true, hint: '必须与所选模型输出维度一致；修改后需要重建向量索引。' },
+      { key: 'embeddingBatchSize', label: '编码批大小', kind: 'number', fallback: 8, min: 1, max: 64, step: 1, advanced: true },
+      { key: 'embeddingTimeoutMs', label: '编码超时（毫秒）', kind: 'number', fallback: 120000, min: 1000, max: 600000, step: 1000, advanced: true },
     ],
   },
   recall: {
     scope: 'knowledge',
-    title: '召回设置',
-    description: 'Coordinate、关键词 BM25、向量三路各自生成 Section 候选，融合（RRF）后统一重排。知识图谱不参与候选生成。',
+    title: '检索与上下文',
     fields: [
-      { key: 'recallTopK', label: '最终条数（hits）', kind: 'number', fallback: 10, hint: '1–50，默认 10。这是给模型的最终条数，不是召回深度' },
-      { key: 'recallCandidatePool', label: '候选池深度', kind: 'number', fallback: 50, hint: '1–200，默认 50。融合与重排都作用在它上面 —— 太小则重排救不回排在窗口外的那条' },
-      { key: 'recallMode', label: '默认召回路线', kind: 'select', fallback: 'hybrid', options: [{ value: 'hybrid', label: 'Hybrid（Coordinate + 关键词 + 向量）' }, { value: 'vector', label: '仅向量' }, { value: 'fts', label: '仅关键词' }] },
-      { key: 'keywordThreshold', label: '关键词阈值', kind: 'number', fallback: 0.3, hint: '0–1，默认 0.3。归一化 BM25 的相对阈值：挡得住弱命中，挡不住「整批都弱」' },
-      { key: 'vectorThreshold', label: '向量阈值（余弦）', kind: 'number', fallback: 0.15, hint: '−1–1，默认 0.15。**绝对**阈值，弃答主要靠它' },
-    ],
-  },
-  context: {
-    scope: 'knowledge',
-    title: '重排设置',
-    description: 'BERT cross-encoder 对**候选池**精排，低于阈值的一律丢弃，再取上下文条数。阈值是整条链路里唯一跨查询可比的相关性判据，所以「弃答」主要靠它。',
-    fields: [
-      { key: 'contextTopN', label: '上下文 TopN', kind: 'number', fallback: 5, hint: '1–recallTopK，默认 5。同一张 wiki 最多 2 条，其余名额留给别的卡片' },
-      { key: 'rerankThreshold', label: '重排阈值', kind: 'number', fallback: 0.2, hint: '−10–10，默认 0.2。原始 cross-encoder 分（与 WeKnora 同刻度）：低于它的不进上下文' },
-      { key: 'rerankProvider', label: 'Rerank Provider', kind: 'select', fallback: 'bert-python', options: [{ value: 'bert-python', label: 'BERT Python（本地）' }, { value: 'none', label: '关闭（按融合分数）' }] },
-      { key: 'rerankModel', label: 'Rerank Model', kind: 'text', fallback: '', hint: '本地模型目录，或一个 HuggingFace 模型名' },
-      { key: 'rerankTimeoutMs', label: '重排超时（毫秒）', kind: 'number', fallback: 60000 },
+      { key: 'recallTopK', label: '最终召回片段数', kind: 'number', fallback: 10, min: 1, max: 50, step: 1, hint: '默认 10 条；低于重排阈值的片段会被过滤。' },
+      { key: 'contextTopN', label: '进入上下文的卡片数', kind: 'number', fallback: 5, min: 1, max: 50, step: 1, hint: '默认 5 张命中卡片；知识图谱的一跳扩展不占这个名额。' },
+      { key: 'keywordThreshold', label: '关键词阈值', kind: 'number', fallback: 0.3, min: 0, max: 1, step: 0.01, advanced: true, hint: '0–1 的归一化 BM25 分数；适合过滤弱命中，不能单独判断整批结果是否相关。' },
+      { key: 'vectorThreshold', label: '向量阈值', kind: 'number', fallback: 0.5, min: -1, max: 1, step: 0.01, advanced: true, hint: '原始余弦分数。默认 0.5 是当前本地模型与语料的起点，换模型后应按召回诊断校准。' },
+      { key: 'rerankThreshold', label: '重排最低分', kind: 'number', fallback: 0.2, min: -10, max: 10, step: 0.1, advanced: true },
+      { key: 'rerankTimeoutMs', label: '重排超时（毫秒）', kind: 'number', fallback: 60000, min: 1000, max: 600000, step: 1000, advanced: true },
+      { key: 'contextMaxChars', label: '上下文字符上限', kind: 'number', fallback: 20000, min: 0, max: 1000000, step: 1000, hint: '0 表示不限', advanced: true },
     ],
   },
 }
 
 /** 知识库那一组设置组的**展示顺序**。抽屉按它渲染。 */
-export const KNOWLEDGE_SETTINGS_ORDER: SettingsNode[] = ['storage', 'build', 'recall', 'context']
+export const KNOWLEDGE_SETTINGS_ORDER: SettingsNode[] = ['storage', 'build', 'recall']
 
 /**
  * 卡片头上的「参数」入口（0034）。
@@ -174,9 +164,36 @@ function readField(spec: FieldSpec, value: Record<string, unknown> | undefined):
   return String(raw)
 }
 
+/**
+ * 一个数字字段的草稿能不能落盘。返回 `null` = 能，否则是人话的原因。
+ *
+ * 这里挡的是两个具体的坏值，它们都不是「用户想存这个数」，而是**那一瞬间的输入状态**：
+ *
+ * - `Number('') === 0`：清空「向量维度」会把 0 写进设置，而 0 是被 `min` 挡掉的非法值；
+ * - `Number('abc') === NaN`：`JSON.stringify(NaN)` 是 `null`，存下去是一份坏设置。
+ *
+ * 所以非法文本**留在草稿里**（人看到自己敲的东西、右面有一句「值无效」），只是不写。
+ * 这比「敲一半就被改写」温和：中间态是人打字时的一个正常阶段，不是错误。
+ */
+function fieldErrorOf(spec: FieldSpec, value: string | boolean): string | undefined {
+  if (spec.kind !== 'number') return undefined
+  const text = String(value).trim()
+  if (text === '') return '值无效：请填写一个数字'
+  const parsed = Number(text)
+  if (!Number.isFinite(parsed)) return '值无效：请填写一个数字'
+  if (spec.min !== undefined && parsed < spec.min) return `值无效：不能小于 ${spec.min}`
+  if (spec.max !== undefined && parsed > spec.max) return `值无效：不能大于 ${spec.max}`
+  return undefined
+}
+
+/** 数字字段只在**合法**时才写。非法时返回 `undefined`，上层跳过这一次写入。 */
 function writeField(spec: FieldSpec, draft: string | boolean): unknown {
   if (spec.kind === 'toggle') return Boolean(draft)
-  if (spec.kind === 'number') return Number(draft)
+  if (spec.kind === 'number') {
+    const error = fieldErrorOf(spec, draft)
+    if (error !== undefined) return undefined
+    return Number(String(draft).trim())
+  }
   if (spec.list) return String(draft).split(',').map(item => item.trim()).filter(Boolean)
   return String(draft)
 }
@@ -187,20 +204,20 @@ function needsDebounce(spec: FieldSpec): boolean {
 }
 
 function TextField({ spec, value, onChange, disabled, resolved }: { spec: FieldSpec; value: string; onChange: (value: string) => void; disabled: boolean; resolved?: string }) {
-  /* 两条说明各自成行：`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}>
+  const invalid = fieldErrorOf(spec, value)
+  return <Field label={spec.label} hint={spec.hint}>
     <Input
       type={spec.kind === 'number' ? 'number' : 'text'}
       value={value}
       disabled={disabled}
+      min={spec.min}
+      max={spec.max}
+      step={spec.step}
       {...(resolved ? { placeholder: resolved } : {})}
       onChange={event => onChange(event.target.value)}
     />
+    {/* 非法草稿**留在输入框里**，只在旁边说一句「值无效、不会写」—— 见 `fieldErrorOf`。 */}
+    {invalid && <span className="tita-settingInvalid" role="status">{invalid}</span>}
   </Field>
 }
 
@@ -240,30 +257,99 @@ function ToggleField({ spec, value, onChange, disabled }: { spec: FieldSpec; val
   </Field>
 }
 
+/**
+ * 固定的数据目录：只读展示实际路径，打开动作交给 DSH 的 session 能力。
+ */
+function StorageLocationField({ label, path, session, onError, loadError, onRetry }: {
+  label: string
+  path?: string
+  session?: SessionRemote['session']
+  onError: (message: string | null) => void
+  /** `/knowledge/layout` 的读取失败。它发生在这个字段上，所以报在这个字段旁边。 */
+  loadError?: string | null
+  /** 重读一次布局。不给人这条路的话，一次瞬时失败会永久停在一句占位文字上。 */
+  onRetry?: () => void
+}): ReactNode {
+  const [opening, setOpening] = useState(false)
+
+  const open = async (): Promise<void> => {
+    if (!path) return
+    onError(null)
+    if (!session || typeof session.openWorkspacePath !== 'function') {
+      onError('宿主没有提供打开目录的能力，请手动打开下面显示的路径。')
+      return
+    }
+    setOpening(true)
+    try {
+      const result = await session.openWorkspacePath({ path, action: 'reveal' })
+      if (!result.ok) onError(result.message ?? '宿主拒绝打开这个目录，请手动打开下面显示的路径。')
+    } catch (cause) {
+      onError(`${cause instanceof Error ? cause.message : String(cause)}　请手动打开下面显示的路径。`)
+    } finally {
+      setOpening(false)
+    }
+  }
+
+  return <Field as="div" label={label}>
+    <div className="tita-pickerRow">
+      {/* 读不到布局时占位文字要跟着变：原来的「正在读取数据目录…」在失败之后
+          是一句**永远为真**的话，而它掩盖了「已经不读了」这个事实。 */}
+      <Input readOnly value={path ?? ''} placeholder={loadError ? '未能读取数据目录' : '正在读取数据目录…'} aria-label={label} />
+      <Button variant="outline" onClick={() => void open()} disabled={!path || opening}>
+        {opening ? <LoaderCircle size={14} className="tita-spin" /> : <FolderOpen size={14} />}
+        {opening ? '正在打开…' : '打开目录'}
+      </Button>
+    </div>
+    {loadError && <p className="tita-settingsRetry" role="alert">
+      <AlertCircle size={13} />
+      <span>读取数据目录失败：{loadError}</span>
+      {onRetry && <Button variant="ghost" size="sm" onClick={onRetry}>重新读取</Button>}
+    </p>}
+  </Field>
+}
+
 /** 写入状态。`saved` 只短暂出现，`error` 留到下一次改动。 */
 type SaveState = 'idle' | 'saving' | 'saved' | 'error'
 
-export function NodeSettingsPanel({ node, knowledge, pickerKind = null, resolved = {}, highlight = false }: {
+export function NodeSettingsPanel({ node, knowledge, agentRoot, session, resolved = {}, highlight = false, showAdvanced = false, advancedLabel, layoutError = null, onRetryLayout }: {
   node: SettingsNode
   knowledge?: SettingsScopeLike
-  /** 宿主提供哪种目录选择交互；`null` 表示没挂目录选择器。 */
-  pickerKind?: string | null
+  /** `/knowledge/layout` 返回的固定 Agent 根目录。 */
+  agentRoot?: string
+  /** DSH 提供的系统文件管理器能力，只用于打开固定目录。 */
+  session?: SessionRemote['session']
   /** 字段键 → 「留空时实际会用什么」。0029：家当路径空着就是跟着根路径走。 */
   resolved?: Record<string, string>
   /** 由卡片头的「参数」chip 定位过来的那一块：一次性强调 + 接管焦点。 */
   highlight?: boolean
+  /** Show the model and retrieval tuning fields. */
+  showAdvanced?: boolean
+  /** Keep low-frequency fields within this group, behind a named disclosure. */
+  advancedLabel?: string
+  /** `/knowledge/layout` 读取失败时的原话；只有「数据位置」那一块用得到。 */
+  layoutError?: string | null
+  /** 重读一次布局。 */
+  onRetryLayout?: () => void
 }): ReactNode {
   const spec = NODE_SETTINGS[node]
   const scope = knowledge
   const state = useScope(knowledge)
   const [draft, setDraft] = useState<Record<string, string | boolean>>({})
   const [saveState, setSaveState] = useState<SaveState>('idle')
+  const [advancedOpen, setAdvancedOpen] = useState(false)
   const [error, setError] = useState<string | null>(null)
-  /** 待落地的防抖写入，按字段键索引。 */
-  const timers = useRef(new Map<string, ReturnType<typeof setTimeout>>())
+  /**
+   * 待落地的防抖写入，按字段键索引。
+   *
+   * 除了计时器，它还记着**那次要写的值**：卸载时那个 `setTimeout` 不会再回来，
+   * 而草稿 state 在那一刻不一定已经渲染过（`setDraft` 是异步的）—— 从 timer 里读
+   * 值才是「用户最后敲进去的东西」的唯一可靠来源。
+   */
+  const pending = useRef(new Map<string, { timer: ReturnType<typeof setTimeout>; field: FieldSpec; value: string | boolean }>())
   /** 正在进行的写入数。用它挡住「写完 → revision 变 → 重置草稿」把输入抹掉。 */
   const inflight = useRef(0)
   const savedTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const disabled = !state.writable || state.status !== 'ready'
 
   useEffect(() => {
     // 有写入在飞的时候不重置草稿：那一刻 `state.value` 还是旧值，重置会把用户刚
@@ -272,21 +358,16 @@ export function NodeSettingsPanel({ node, knowledge, pickerKind = null, resolved
     setDraft(Object.fromEntries(spec.fields.map(field => [field.key, readField(field, state.value)])))
   }, [node, state.revision, state.value])
 
-  // 卸载时把还没落地的防抖写入丢掉并清计时器：一个已经离开的面板不该再写设置。
-  useEffect(() => () => {
-    for (const timer of timers.current.values()) clearTimeout(timer)
-    timers.current.clear()
-    if (savedTimer.current) clearTimeout(savedTimer.current)
-  }, [])
-
-  const disabled = !state.writable || state.status !== 'ready'
-
   const persist = useCallback(async (field: FieldSpec, raw: string | boolean): Promise<void> => {
     if (!scope || disabled) return
+    const value = writeField(field, raw)
+    // 非法草稿跳过这一次写入（见 `fieldErrorOf`）。它不是失败，也不该报错 ——
+    // 只是「这一笔现在还不能写」，草稿留在输入框里等人把它改对。
+    if (value === undefined) return
     inflight.current += 1
     setSaveState('saving'); setError(null)
     try {
-      await scope.set(field.key, writeField(field, raw))
+      await scope.set(field.key, value)
       setSaveState('saved')
       if (savedTimer.current) clearTimeout(savedTimer.current)
       // 「已保存」只是一个确认，不是一条状态：两秒后收回，免得它常驻成一个
@@ -300,18 +381,35 @@ export function NodeSettingsPanel({ node, knowledge, pickerKind = null, resolved
     }
   }, [scope, disabled])
 
+  // 卸载时把还没落地的防抖写入**冲出去**，而不是丢掉：用户敲完立刻按 Esc 是常规操作，
+  // 而丢掉的表现是「输入框里的值过一会儿自己变回去了」，中间连一个保存指示都没有。
+  // 冲出去就是替那一个 `setTimeout` 把事做完。卸载后 `persist` 里的 setState 会被
+  // React 忽略（它已经不在树上了），写入本身照旧发出去。
+  useEffect(() => () => {
+    for (const { timer, field, value } of pending.current.values()) {
+      clearTimeout(timer)
+      void persist(field, value)
+    }
+    pending.current.clear()
+    if (savedTimer.current) clearTimeout(savedTimer.current)
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
   const update = (field: FieldSpec, value: string | boolean): void => {
     setDraft(current => ({ ...current, [field.key]: value }))
     if (!needsDebounce(field)) {
       void persist(field, value)
       return
     }
-    const existing = timers.current.get(field.key)
-    if (existing) clearTimeout(existing)
-    timers.current.set(field.key, setTimeout(() => {
-      timers.current.delete(field.key)
-      void persist(field, value)
-    }, 600))
+    const existing = pending.current.get(field.key)
+    if (existing) clearTimeout(existing.timer)
+    pending.current.set(field.key, {
+      field,
+      value,
+      timer: setTimeout(() => {
+        pending.current.delete(field.key)
+        void persist(field, value)
+      }, 600),
+    })
   }
 
   const meta = state.status === 'loading'
@@ -323,12 +421,45 @@ export function NodeSettingsPanel({ node, knowledge, pickerKind = null, resolved
         : saveState === 'saved'
           ? '已保存'
           : saveState === 'error'
-            ? '未保存'
-            : state.mode === 'host' ? '改动即生效' : '当前会话'
+            ? '保存失败'
+            : ''
+
+  const visibleFields = spec.fields.filter(field => {
+    if (!field.visibleWhen) return true
+    const dependency = spec.fields.find(item => item.key === field.visibleWhen?.key)
+    const value = draft[field.visibleWhen.key] ?? (dependency ? readField(dependency, state.value) : undefined)
+    return value === field.visibleWhen.value
+  })
+
+  const fields = visibleFields.filter(field => showAdvanced || !field.advanced)
+  const advancedFields = visibleFields.filter(field => field.advanced)
 
   const anchor = settingsAnchorId(node)
   const titleId = `${anchor}-title`
 
+  const renderField = (field: FieldSpec): ReactNode => field.kind === 'toggle'
+        ? <ToggleField key={field.key} spec={field} value={Boolean(draft[field.key])} onChange={value => update(field, value)} disabled={disabled} />
+        : field.kind === 'select'
+          ? <SelectField key={field.key} spec={field} value={String(draft[field.key] ?? '')} onChange={value => update(field, value)} disabled={disabled} />
+          : field.kind === 'location'
+            ? <StorageLocationField
+              key={field.key}
+              label={field.label}
+              path={agentRoot}
+              session={session}
+              onError={setError}
+              loadError={layoutError}
+              {...(onRetryLayout ? { onRetry: onRetryLayout } : {})}
+            />
+            : <TextField
+              key={field.key}
+              spec={field}
+              value={String(draft[field.key] ?? '')}
+              onChange={value => update(field, value)}
+              disabled={disabled}
+              {...(resolved[field.key] && !(field.key === 'embeddingModel' && draft.embeddingProvider === 'ollama') ? { resolved: resolved[field.key]! } : {})}
+            />
+
   return <section
     id={anchor}
     className={cn('tita-settingsSection', highlight && 'tita-settingsSectionOn')}
@@ -339,9 +470,7 @@ export function NodeSettingsPanel({ node, knowledge, pickerKind = null, resolved
     aria-labelledby={titleId}
   >
     <div className="tita-settingsSectionHeader">
-      {/* 说明从标题下面挪到图标后面：常驻文字会把控件挤出首屏，而说明本身有价值。
-          见 `InfoHint`。 */}
-      <div><h3 id={titleId}>{spec.title}{spec.description && <InfoHint text={spec.description} />}</h3></div>
+      <div><h3 id={titleId}>{spec.title}</h3></div>
       <div className={`tita-settingMeta${saveState === 'error' ? ' tita-settingMetaBad' : ''}`} role="status" aria-live="polite">
         {saveState === 'saving' && <LoaderCircle size={11} className="tita-spin" />}
         {saveState === 'saved' && <Check size={11} />}
@@ -350,21 +479,13 @@ export function NodeSettingsPanel({ node, knowledge, pickerKind = null, resolved
     </div>
     {error && <div className="tita-settingsError" role="alert"><AlertCircle size={13} />{error}</div>}
     <div className="tita-settingsGrid">
-      {spec.fields.map(field => field.kind === 'toggle'
-        ? <ToggleField key={field.key} spec={field} value={Boolean(draft[field.key])} onChange={value => update(field, value)} disabled={disabled} />
-        : field.kind === 'select'
-          ? <SelectField key={field.key} spec={field} value={String(draft[field.key] ?? '')} onChange={value => update(field, value)} disabled={disabled} />
-          : field.kind === 'picker'
-            ? <DirectoryPickerField
-              key={field.key}
-              label={field.label}
-              value={String(draft[field.key] ?? '')}
-              disabled={disabled}
-              pickerKind={pickerKind}
-              onError={setError}
-              onChange={value => update(field, value)}
-            />
-            : <TextField key={field.key} spec={field} value={String(draft[field.key] ?? '')} onChange={value => update(field, value)} disabled={disabled} {...(resolved[field.key] ? { resolved: resolved[field.key]! } : {})} />)}
+      {fields.map(renderField)}
     </div>
+    {!showAdvanced && advancedLabel && advancedFields.length > 0 && <div className="mt-5 border-t border-tita-line pt-3">
+      <Button variant="ghost" size="sm" className="-ml-2" aria-expanded={advancedOpen} aria-controls={`${anchor}-advanced`} onClick={() => setAdvancedOpen(value => !value)}>
+        <ChevronDown size={14} className={advancedOpen ? 'rotate-180' : ''} />{advancedLabel}
+      </Button>
+      {advancedOpen && <div id={`${anchor}-advanced`} className="tita-settingsGrid mt-4">{advancedFields.map(renderField)}</div>}
+    </div>}
   </section>
 }

package/src/client/NormalizeTrajectoryView.tsx

@@ -0,0 +1,136 @@
+/**
+ * 归一轨迹的渲染（2026-10-18）。
+ *
+ * 归一这一段原来只留下两个东西：任务里一段会滚走的流式输出，和最终写进事实表的那些行。
+ * 中间那一步 ——「模型给的这些名字里，哪些命中了已有实体、哪些新建了候选、哪些因为不唯一
+ * 没猜」—— 跑完就查不到了。而它恰好是坐标错了之后唯一能复盘的东西：卡名错了，根在这里。
+ *
+ * 所以这一页只回答三个问题，按这个顺序：
+ *
+ * 1. **这次归一动了多少**（提及数、命中/新建/歧义、写进多少条事实）。
+ * 2. **每个名字落到了哪里**（名字 → 实体 id，以及凭什么）。
+ * 3. **写进去的事实长什么样**（正文、坐标、几条出处、哪几条还悬着）。
+ *
+ * 样式复用抽取报告那一套（`.tita-trial*`）：三份轨迹是同一件事的三种粒度，
+ * 长得不一样会让人以为是三个不同的功能。
+ */
+
+import { type ReactNode } from 'react'
+import { TriangleAlert } from '@tita-agent/ui/icons'
+import { cn } from '@tita-agent/ui/components'
+import { styles } from './styles.ts'
+import type { NormalizeTrajectoryReport } from '../trajectory-types.js'
+
+/** 名字最多摊这么多行。再多就该看总体结论，不该在页面上滚。 */
+const AXIS_CAP = 200
+const FACT_CAP = 200
+
+const OUTCOME_LABEL: Record<string, string> = {
+  matched: '命中已有',
+  new: '新建候选',
+  ambiguous: '不唯一，没猜',
+  'no-registry': '只做文档内归一',
+}
+
+export function NormalizeTrajectory({ report }: { report: NormalizeTrajectoryReport }): ReactNode {
+  const axes = report.axes ?? []
+  const rows = report.rows ?? []
+  const counts = report.counts ?? { matched: 0, created: 0, ambiguous: 0, mechanical: 0 }
+  const modelOk = report.model?.ok !== false
+  return <div className={styles.trialReport}>
+    <section className={styles.trialOverview} aria-labelledby="normalize-overview-title">
+      <div className={styles.trialSectionHead}>
+        <h2 id="normalize-overview-title">结果概览</h2>
+        <span>{report.knowledge?.unresolved ? `${report.knowledge.unresolved} 条坐标未决` : modelOk ? '已完成' : '需检查'}</span>
+      </div>
+      <dl className={styles.trialOverviewStats}>
+        <div><dt>坐标提及</dt><dd>{report.mentions ?? axes.length}</dd></div>
+        <div><dt>命中 / 新建</dt><dd>{counts.matched} / {counts.created}<small>已有实体 / 候选</small></dd></div>
+        <div><dt>歧义未决</dt><dd>{counts.ambiguous}<small>不猜，留给人</small></dd></div>
+        <div><dt>写入 Knowledge</dt><dd>{report.knowledge?.saved ?? 0}<small>另并入 {report.knowledge?.merged ?? 0} 条</small></dd></div>
+        <div><dt>写入 Event</dt><dd>{report.events?.saved ?? 0}<small>另并入 {report.events?.merged ?? 0} 个</small></dd></div>
+      </dl>
+      <p className={styles.trialOverviewTitle}>
+        <strong>{report.source?.title || '（来源已删除）'}</strong>
+        <span>v{report.source?.version ?? '?'} · 依据抽取记录 {report.extractionId || '—'}</span>
+      </p>
+    </section>
+
+    {!modelOk && <p className={styles.trialError} role="alert">
+      <TriangleAlert size={12} />{report.model?.why ?? '归一没有跑通'} · 这一份文档的事实没有写完。
+    </p>}
+
+    {report.warnings.length > 0 && <section className={styles.trialSection} aria-labelledby="normalize-warnings-title">
+      <div className={styles.trialSectionHead}>
+        <h2 id="normalize-warnings-title">警告</h2>
+        <span>{report.warnings.length} 条</span>
+      </div>
+      <ul className={styles.trialCandidates}>{report.warnings.map((warning, index) => <li key={index}>
+        {/* 不加装饰图标：这一段就叫「警告」，一条黄三角再标一次是同一句话说两遍。
+            而且 `trialCandidates > li` 是上下两行的栅格 —— 图标单占一行会让正文掉到第三行。 */}
+        <span className={styles.trialCandName}>{warning}</span>
+      </li>)}</ul>
+    </section>}
+
+    <section className={styles.trialSection} aria-labelledby="normalize-axes-title">
+      <div className={styles.trialSectionHead}>
+        <h2 id="normalize-axes-title">坐标解析</h2>
+        <span>{axes.length} 个名字{counts.mechanical > 0 ? ` · ${counts.mechanical} 个只做了机械归一` : ''}</span>
+      </div>
+      {axes.length === 0
+        ? <p className={styles.trialEmpty}>这次归一没有解析任何坐标名。</p>
+        : <ul className={styles.trialItems}>{axes.slice(0, AXIS_CAP).map((axis, index) => <li
+          key={`${axis.kind}-${axis.name}-${index}`}
+          className={axis.outcome === 'matched' ? styles.trialItem : `${styles.trialItem} ${styles.trialItemWarn}`}
+        >
+          <span className={styles.trialItemRef}>{axis.name}</span>
+          <span className={styles.trialItemArrow} aria-hidden="true">→</span>
+          <span className={styles.trialItemValue}>
+            {(OUTCOME_LABEL[axis.outcome] ?? axis.outcome)}{axis.id ? ` ${axis.id}` : ''}
+          </span>
+          <span className={styles.trialItemNote}>
+            {KIND_LABEL[axis.kind] ?? axis.kind}{axis.how ? ` · ${axis.how}` : ''}{axis.parentMention ? ` · 作用域：${axis.parentMention}` : ''}
+          </span>
+        </li>)}</ul>}
+      {axes.length > AXIS_CAP && <p className={styles.trialItemsMore}>另有 {axes.length - AXIS_CAP} 个名字未展开。</p>}
+    </section>
+
+    <section className={styles.trialSection} aria-labelledby="normalize-facts-title">
+      <div className={styles.trialSectionHead}>
+        <h2 id="normalize-facts-title">写入的事实</h2>
+        <span>{rows.length} 条{report.knowledge?.unresolved ? ` · ${report.knowledge.unresolved} 条坐标未决` : ''}</span>
+      </div>
+      {rows.length === 0
+        ? <p className={styles.trialEmpty}>这次归一没有写入 Knowledge。</p>
+        : <ul className={styles.trialOutputList}>{rows.slice(0, FACT_CAP).map((row, index) => <li key={index} className={styles.trialOutputItem}>
+          <div className={styles.trialCandHead}>
+            <span className={cn(styles.trialCandName, row.unresolved && styles.trialCandBad)}>{row.text}</span>
+          </div>
+          <div className={styles.trialOutputMeta}>
+            {row.coordinate} · {row.sources} 条出处
+            {row.unresolved && <strong>坐标未决</strong>}
+          </div>
+        </li>)}</ul>}
+      {rows.length > FACT_CAP && <p className={styles.trialMore}>另有 {rows.length - FACT_CAP} 条未展开。</p>}
+    </section>
+
+    <section className={styles.trialSection} aria-labelledby="normalize-fingerprint-title">
+      <div className={styles.trialSectionHead}>
+        <h2 id="normalize-fingerprint-title">续跑信息</h2>
+        <span>指纹没变，下一次归一会直接复用这一份</span>
+      </div>
+      <dl className={styles.trialRows}>
+        <div className={styles.trialRow}><dt>归一指纹</dt><dd>{report.fingerprint || '—'}</dd></div>
+        <div className={styles.trialRow}>
+          <dt>已下发坐标</dt>
+          <dd>{report.axesContext === undefined
+            ? '这次没有下发（没接注册表，或库里还没有实体）'
+            : `${report.axesContext.injected} / ${report.axesContext.totals} 条${report.axesContext.truncated > 0 ? ` · 未下发 ${report.axesContext.truncated} 条` : ''}${report.axesContext.selection === 'relevant' ? ' · 当前文档相关候选' : report.axesContext.selection === 'full' ? ' · 全集' : ''}`}</dd>
+        </div>
+        <div className={styles.trialRow}><dt>模型</dt><dd>{report.model?.model ? `${report.model.provider ? `${report.model.provider} / ` : ''}${report.model.model}${report.model.reasoningEffort ? ` · ${report.model.reasoningEffort}` : ''}` : '未记录'}</dd></div>
+      </dl>
+    </section>
+  </div>
+}
+
+const KIND_LABEL: Record<string, string> = { object: '对象', action: '动作', scene: '场景' }

package/src/client/PipelineNotice.tsx

@@ -0,0 +1,26 @@
+import { useEffect, useState } from 'react'
+import { Button } from '@tita-agent/ui/components'
+import type { PipelineStatus } from '../pipeline/types.js'
+import { requestJson } from './request.ts'
+
+export function PipelineNotice({ kb, revision, onOpen }: { kb: string; revision?: string; onOpen: () => void }) {
+  const [status, setStatus] = useState<PipelineStatus>()
+  useEffect(() => {
+    let active = true
+    const refresh = (): void => { void requestJson<PipelineStatus>(`/knowledge/pipeline?kb=${encodeURIComponent(kb)}`).then(result => { if (active && result.data) setStatus(result.data) }).catch(() => undefined) }
+    refresh()
+    window.addEventListener('focus', refresh)
+    return () => { active = false; window.removeEventListener('focus', refresh) }
+  }, [kb, revision])
+  if (!status) return null
+  const pending = status.pendingNew + status.pendingUpdated + status.pendingWithdrawn
+  const parts = [
+    status.sources.filter(source => source.state === 'pending' || source.state === 'outdated').length,
+    status.sources.filter(source => source.state === 'extracted').length,
+  ]
+  if (!parts.some(Boolean) && !pending && !status.indexPending) return null
+  return <div className="mx-3 flex min-w-0 items-center gap-2 border-b border-tita-line py-2 text-xs text-tita-ink-muted" role="status">
+    <span className="min-w-0 flex-1 leading-relaxed">{[parts[0] ? `${parts[0]} 份待抽取` : '', parts[1] ? `${parts[1]} 份待归一` : '', pending ? `${pending} 张 WikiCard 待物化` : '', status.indexPending ? '索引待更新' : ''].filter(Boolean).join(' · ')}</span>
+    <Button size="sm" variant="ghost" onClick={onOpen}>处理</Button>
+  </div>
+}