dsh-data-domain-knowledge 0.1.0-alpha.13 → 0.1.0-alpha.15

package/src/client/KnowledgePanel.tsx

@@ -223,7 +223,12 @@ export function KnowledgePanel({ visible, currentQuestion, onOpenTab, settings,
    * 存储位置要 `agentRoot`、构建设置要 `resources` 的解析值 —— 都在同一份响应里。
    */
   const knowledgeSnapshot = useScope(settings?.knowledge)
-  const { layout } = useAgentLayout(knowledgeSnapshot.revision ?? 0)
+  /**
+   * `error` / `reload` 必须**真的被用掉**（U4）：只取 `layout` 的话，一次失败的
+   * `GET /knowledge/layout` 会让「数据位置」那一块永远停在「正在读取数据目录…」——
+   * 既不报错，也没有重试的路。两者都交给渲染路径字段的那一块。
+   */
+  const { layout, error: layoutError, reload: reloadLayout } = useAgentLayout(knowledgeSnapshot.revision ?? 0)
   const environment = useKnowledgeEnvironment(visible, knowledgeSnapshot.revision ?? 0)
 
   /**
@@ -344,9 +349,16 @@ export function KnowledgePanel({ visible, currentQuestion, onOpenTab, settings,
       <div className={cn(styles.content, (activeTab === 'attribution' || activeTab === 'overview') && styles.contentStage)}>
 
         {/* 一级 tab 已经说明「现在是哪一页」，这里不再重复一遍标题与说明。
-            只有真的出问题时才占一行：读取失败 / 读取中。 */}
+            只有真的出问题时才占一行：读取失败 / 读取中。
+            失败时**必须给一条重试的路**（A5）：这一栏的取数只由 `[visible, refreshStats]`
+            触发，而 `visible` 在内部各视图之间一直是 true —— 一次瞬时失败会让
+            「数据读取失败」和空计数一直挂在那里，除非重挂载整个面板。 */}
         {(statsError || statsLoading) && <p className={styles.viewStatus} role="status">
-          {statsError ? <><AlertCircle size={13} />数据读取失败：{statsError}</> : '正在读取知识库统计…'}
+          {statsError
+            ? <><AlertCircle size={13} />数据读取失败：{statsError}
+              <Button variant="ghost" size="sm" disabled={statsLoading} onClick={() => void refreshStats()}>重新读取</Button>
+            </>
+            : '正在读取知识库统计…'}
         </p>}
 
         {notice && <Card className={cn(styles.notice, notice.tone === 'error' ? styles.noticeError : styles.noticeSuccess)} role="status">
@@ -469,6 +481,8 @@ export function KnowledgePanel({ visible, currentQuestion, onOpenTab, settings,
               showAdvanced={showAdvancedSettings}
               agentRoot={layout?.agentRoot}
               session={remote?.session}
+              layoutError={layoutError}
+              onRetryLayout={reloadLayout}
               {...(node === 'build' && layout?.resources ? { resolved: layout.resources } : {})}
             />)}
           </div>

package/src/client/ListPager.tsx

@@ -7,8 +7,9 @@
  *
  * 三条纪律：
  *
- * 1. **不重新取数**。两份列表的数据本来就整份在手（`visibleDocuments` / `visibleCards`），
- *    分页只切渲染 —— 它不是一个接口概念，是版式概念。所以这里没有加载态。
+ * 1. **不重新取数**（卡片列表成立）。两份列表的数据本来整份在手（`visibleDocuments` /
+ *    `visibleCards`），分页只切渲染。**文件列表是例外**：它走服务端分页（`offset`），
+ *    因为「取 500 份再本地切页」会让超过 500 份的库从第 501 份起不可达。
  * 2. **页码在筛选变化时回到第 1 页**。停在第 5 页而结果只剩 1 页时，用户看到的是一片空白，
  *    而空白与「没有结果」在界面上长得一样。`usePage` 的第二个参数（筛选 key）管这件事。
  * 3. **只有一页时不渲染**。一页装得下的列表底下挂一行「第 1 / 1 页」是纯噪音。
@@ -71,11 +72,20 @@ export interface ListPagerProps {
 export function ListPager({ page, pageCount, total, onChange }: ListPagerProps): ReactNode {
   // 一页装得下就不显示：分页器只在「真的有下一页」时才有意义。
   if (total <= PAGE_SIZE) return null
+  /**
+   * 夹紧页码 —— **不能直接信 `page`**。
+   *
+   * 卡片抽屉那份列表是服务端分页的，总数可能在抽屉开着的时候变小；那时不夹紧就会在屏幕上
+   * 出现「第 3 / 2 页」这种自相矛盾的读数，而且两个按钮都还是可点的。标签与按钮边界
+   * 必须用同一个夹紧后的数。
+   */
+  const safePageCount = Math.max(1, Math.trunc(pageCount) || 1)
+  const current = Math.min(Math.max(1, Math.trunc(page) || 1), safePageCount)
   return <nav className={styles.pager} aria-label="分页">
     <span className={styles.pagerCount}>
-      共 {total} 条 · 第 <b>{page}</b> / {pageCount} 页
+      共 {total} 条 · 第 <b>{current}</b> / {safePageCount} 页
     </span>
-    <Button variant="outline" size="sm" disabled={page <= 1} onClick={() => onChange(page - 1)}>上一页</Button>
-    <Button variant="outline" size="sm" disabled={page >= pageCount} onClick={() => onChange(page + 1)}>下一页</Button>
+    <Button variant="outline" size="sm" disabled={current <= 1} onClick={() => onChange(current - 1)}>上一页</Button>
+    <Button variant="outline" size="sm" disabled={current >= safePageCount} onClick={() => onChange(current + 1)}>下一页</Button>
   </nav>
 }

package/src/client/MaterializeTrajectoryView.tsx

@@ -0,0 +1,124 @@
+/**
+ * 物化轨迹的渲染（2026-10-18）。
+ *
+ * 物化这一段的产物就是卡片本身，所以「卡里有什么」在 WikiCard 那一栏已经查得到。
+ * 这一页回答的是**另外**三个问题：
+ *
+ * 1. **这一次对这张卡做了什么**（新建 / 更新 / 停用），以及是按哪个分组指纹做的。
+ * 2. **正文是怎么排出来的**（模型组织，还是机械拼装；每节几条）。
+ * 3. **哪些知识进了这张卡、哪几张卡被链进来、为什么**。
+ *
+ * 第 3 条是改提示词之后最想看的东西：「这次正文里链到的那张卡，和上次是不是同一张」——
+ * 这在前一个版本里没有任何地方能回答。
+ */
+
+import { type ReactNode } from 'react'
+import { TriangleAlert } from '@tita-agent/ui/icons'
+import { styles } from './styles.ts'
+import type { MaterializeTrajectoryReport } from '../trajectory-types.js'
+
+const ROW_CAP = 200
+
+const ACTION_LABEL: Record<MaterializeTrajectoryReport['action'], string> = {
+  created: '新建卡片',
+  updated: '更新卡片',
+  withdrawn: '停用卡片',
+}
+
+const REASON_LABEL: Record<string, string> = {
+  coordinate: '同一坐标',
+  relation: '关系边',
+  source: '共同来源',
+}
+
+export function MaterializeTrajectory({ report }: { report: MaterializeTrajectoryReport }): ReactNode {
+  const card = report.card
+  const rows = report.rows ?? []
+  const related = report.related ?? []
+  return <div className={styles.trialReport}>
+    <section className={styles.trialOverview} aria-labelledby="materialize-overview-title">
+      <div className={styles.trialSectionHead}>
+        <h2 id="materialize-overview-title">结果概览</h2>
+        <span>{ACTION_LABEL[report.action] ?? report.action}</span>
+      </div>
+      <dl className={styles.trialOverviewStats}>
+        <div><dt>知识</dt><dd>{card?.knowledge ?? 0}<small>进这张卡</small></dd></div>
+        <div><dt>Event</dt><dd>{card?.events ?? 0}<small>同坐标引用</small></dd></div>
+        <div><dt>图</dt><dd>{card?.images ?? 0}<small>跟着原文走</small></dd></div>
+        <div><dt>小节</dt><dd>{card?.sections?.length ?? 0}<small>正文结构</small></dd></div>
+        <div><dt>正文字数</dt><dd>{(card?.characters ?? 0).toLocaleString('zh-CN')}<small>字符</small></dd></div>
+      </dl>
+      <p className={styles.trialOverviewTitle}>
+        <strong>{card?.title || report.group?.title || '（没有标题）'}</strong>
+        {/* 坐标在库里是**三个 id**，不是名字 —— 所以标出这是 id，别让它读成卡名。 */}
+        <span>坐标 id：{report.group?.coordinate || '无'} · 状态 {card?.status ?? '未知'}</span>
+      </p>
+    </section>
+
+    {card?.id === undefined && <p className={styles.trialError} role="alert">
+      <TriangleAlert size={12} />这条轨迹没有卡片身份，本次没有写入任何卡片。
+    </p>}
+
+    {report.warnings.length > 0 && <section className={styles.trialSection} aria-labelledby="materialize-warnings-title">
+      <div className={styles.trialSectionHead}>
+        <h2 id="materialize-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="materialize-sections-title">
+      <div className={styles.trialSectionHead}>
+        <h2 id="materialize-sections-title">正文结构</h2>
+        <span>{report.organize?.used ? `模型组织${report.organize.origin === 'fallback' ? '（本轮退回确定性布局）' : ''}` : '机械拼装（本库未开卡片组织）'}</span>
+      </div>
+      {card?.sections && card.sections.length > 0
+        ? <ul className={styles.trialItems}>{card.sections.map(section => <li key={section.label} className={styles.trialItem}>
+          <span className={styles.trialItemRef}>{section.label}</span>
+          <span className={styles.trialItemArrow} aria-hidden="true">·</span>
+          <span className={styles.trialItemValue}>{section.count} 条</span>
+        </li>)}</ul>
+        : <p className={styles.trialEmpty}>
+          {report.action === 'withdrawn' ? '停用不改正文，所以没有分节。' : '这张卡没有分节（正文里的知识全部平铺）。'}
+        </p>}
+    </section>
+
+    <section className={styles.trialSection} aria-labelledby="materialize-knowledge-title">
+      <div className={styles.trialSectionHead}>
+        <h2 id="materialize-knowledge-title">进卡的知识</h2>
+        <span>{rows.length} 条</span>
+      </div>
+      {rows.length === 0
+        ? <p className={styles.trialEmpty}>{report.action === 'withdrawn' ? '停用不涉及知识。' : '这一组没有知识。'}</p>
+        : <ul className={styles.trialOutputList}>{rows.slice(0, ROW_CAP).map(row => <li key={row.id} className={styles.trialOutputItem}>
+          <div className={styles.trialCandHead}>
+            <span className={styles.trialCandName}>{row.text}</span>
+            <span className={styles.trialCandMeta}>{row.id}</span>
+          </div>
+          <div className={styles.trialOutputMeta}>{row.sources} 条出处</div>
+        </li>)}</ul>}
+      {rows.length > ROW_CAP && <p className={styles.trialMore}>另有 {rows.length - ROW_CAP} 条未展开。</p>}
+    </section>
+
+    <section className={styles.trialSection} aria-labelledby="materialize-related-title">
+      <div className={styles.trialSectionHead}>
+        <h2 id="materialize-related-title">相关卡片与来源</h2>
+        <span>正文里的链接目标必须是库里真实存在的卡</span>
+      </div>
+      {related.length > 0 && <ul className={styles.trialCandidates}>{related.map((item, index) => <li key={`${item.title}-${index}`}>
+        <strong>{item.title}</strong><span>{REASON_LABEL[item.reason] ?? item.reason}</span>
+      </li>)}</ul>}
+      <dl className={styles.trialRows}>
+        <div className={styles.trialRow}><dt>来源</dt><dd>{report.sources.length > 0 ? report.sources.join('、') : '—'}</dd></div>
+        <div className={styles.trialRow}><dt>分组键</dt><dd>{report.group?.key || '—'}</dd></div>
+        <div className={styles.trialRow}><dt>分组指纹</dt><dd>{report.group?.fingerprint || '—'}</dd></div>
+        {report.organize?.layoutHash && <div className={styles.trialRow}><dt>布局指纹</dt><dd>{report.organize.layoutHash}</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>
+}

package/src/client/NodeSettings.tsx

@@ -87,10 +87,10 @@ export const NODE_SETTINGS: Record<SettingsNode, NodeSpec> = {
   // 0025：`compile` 设置组已撤。卡片编译模板是系统固定契约，不是用户设置项。
   build: {
     scope: 'knowledge',
-    title: '向量模型',
+    title: '向量运行设置',
     fields: [
       { key: 'embeddingProvider', label: '向量来源', kind: 'select', fallback: 'wemm-python', options: [{ value: 'wemm-python', label: '本地模型' }, { value: 'ollama', label: 'Ollama' }, { value: 'none', label: '关闭向量' }] },
-      { key: 'embeddingModel', label: '模型路径或名称', kind: 'text', fallback: '', hint: '本地模型留空时自动选择；Ollama 填模型名称。' },
+      { 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: '必须与所选模型输出维度一致；修改后需要重建向量索引。' },
@@ -107,7 +107,6 @@ export const NODE_SETTINGS: Record<SettingsNode, NodeSpec> = {
       { 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: 'rerankModel', label: '模型路径或名称', kind: 'text', fallback: '', 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 },
     ],
@@ -165,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)
 }
@@ -178,6 +204,7 @@ function needsDebounce(spec: FieldSpec): boolean {
 }
 
 function TextField({ spec, value, onChange, disabled, resolved }: { spec: FieldSpec; value: string; onChange: (value: string) => void; disabled: boolean; resolved?: string }) {
+  const invalid = fieldErrorOf(spec, value)
   return <Field label={spec.label} hint={spec.hint}>
     <Input
       type={spec.kind === 'number' ? 'number' : 'text'}
@@ -189,6 +216,8 @@ function TextField({ spec, value, onChange, disabled, resolved }: { spec: FieldS
       {...(resolved ? { placeholder: resolved } : {})}
       onChange={event => onChange(event.target.value)}
     />
+    {/* 非法草稿**留在输入框里**，只在旁边说一句「值无效、不会写」—— 见 `fieldErrorOf`。 */}
+    {invalid && <span className="tita-settingInvalid" role="status">{invalid}</span>}
   </Field>
 }
 
@@ -231,11 +260,15 @@ function ToggleField({ spec, value, onChange, disabled }: { spec: FieldSpec; val
 /**
  * 固定的数据目录：只读展示实际路径，打开动作交给 DSH 的 session 能力。
  */
-function StorageLocationField({ label, path, session, onError }: {
+function StorageLocationField({ label, path, session, onError, loadError, onRetry }: {
   label: string
   path?: string
   session?: AgentPresetRemote['session']
   onError: (message: string | null) => void
+  /** `/knowledge/layout` 的读取失败。它发生在这个字段上，所以报在这个字段旁边。 */
+  loadError?: string | null
+  /** 重读一次布局。不给人这条路的话，一次瞬时失败会永久停在一句占位文字上。 */
+  onRetry?: () => void
 }): ReactNode {
   const [opening, setOpening] = useState(false)
 
@@ -259,19 +292,26 @@ function StorageLocationField({ label, path, session, onError }: {
 
   return <Field as="div" label={label}>
     <div className="tita-pickerRow">
-      <Input readOnly value={path ?? ''} placeholder="正在读取数据目录…" aria-label={label} />
+      {/* 读不到布局时占位文字要跟着变：原来的「正在读取数据目录…」在失败之后
+          是一句**永远为真**的话，而它掩盖了「已经不读了」这个事实。 */}
+      <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, agentRoot, session, resolved = {}, highlight = false, showAdvanced = false }: {
+export function NodeSettingsPanel({ node, knowledge, agentRoot, session, resolved = {}, highlight = false, showAdvanced = false, layoutError = null, onRetryLayout }: {
   node: SettingsNode
   knowledge?: SettingsScopeLike
   /** `/knowledge/layout` 返回的固定 Agent 根目录。 */
@@ -284,6 +324,10 @@ export function NodeSettingsPanel({ node, knowledge, agentRoot, session, resolve
   highlight?: boolean
   /** Show the model and retrieval tuning fields. */
   showAdvanced?: boolean
+  /** `/knowledge/layout` 读取失败时的原话；只有「数据位置」那一块用得到。 */
+  layoutError?: string | null
+  /** 重读一次布局。 */
+  onRetryLayout?: () => void
 }): ReactNode {
   const spec = NODE_SETTINGS[node]
   const scope = knowledge
@@ -291,11 +335,18 @@ export function NodeSettingsPanel({ node, knowledge, agentRoot, session, resolve
   const [draft, setDraft] = useState<Record<string, string | boolean>>({})
   const [saveState, setSaveState] = useState<SaveState>('idle')
   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` 还是旧值，重置会把用户刚
@@ -304,21 +355,16 @@ export function NodeSettingsPanel({ node, knowledge, agentRoot, session, resolve
     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)
       // 「已保存」只是一个确认，不是一条状态：两秒后收回，免得它常驻成一个
@@ -332,18 +378,35 @@ export function NodeSettingsPanel({ node, knowledge, agentRoot, session, resolve
     }
   }, [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'
@@ -399,6 +462,8 @@ export function NodeSettingsPanel({ node, knowledge, agentRoot, session, resolve
               path={agentRoot}
               session={session}
               onError={setError}
+              loadError={layoutError}
+              {...(onRetryLayout ? { onRetry: onRetryLayout } : {})}
             />
             : <TextField
               key={field.key}

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>
+}