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

package/src/client/AttributionEventGuide.tsx

@@ -6,7 +6,7 @@ import type { ReactNode } from 'react'
 /**
  * 智能归因的 Event 说明页。
  *
- * 这页解释 Document 如何并行提取 Knowledge 与 Event，以及它们如何在坐标 WikiCard 中相遇。
+ * 这页解释 Document 如何并行提取 Knowledge 与 Event，以及 Knowledge 卡片如何引用 Event。
  * Event 记录一次具体发生；坐标负责定位问题域。把这件事放在整页里，是因为它需要同时讲关系、例子和边界，
  * 不能压缩成侧栏里的 tooltip。
  */
@@ -19,12 +19,13 @@ export function AttributionEventGuide(): ReactNode {
         <h2>一份文档，如何得到 Knowledge 与 Event</h2>
         <p>
           同一份 Document 并行提取两类内容：Knowledge 保存可复用的事实与方法；Event 保存一次具体发生、
-          它的时间线、证据和结果。两者都通过 Object × Action × Scene 归一，再由 WikiCard 按坐标汇总。
+          它的时间线、证据和结果。两者都通过 Object × Action × Scene 归一；WikiCard 由 Knowledge 组织生成，
+          并用坐标引用相关 Event。
         </p>
       </div>
       <div className="attributionGuideFormula" aria-label="核心关系">
         <span>核心关系</span>
-        <code>Document → {`{ Knowledge[], Event[] }`} → WikiCard</code>
+        <code>Document → {`{ Knowledge[], Event[] }`} → Knowledge → WikiCard → Event refs</code>
       </div>
     </header>
 
@@ -32,18 +33,18 @@ export function AttributionEventGuide(): ReactNode {
       <div className="attributionGuideSectionHead">
         <p className="attributionGuideKicker">先看关系</p>
         <h3 id="attribution-event-map-title">同一份文档，并行产出两种信息</h3>
-        <p>Document 保留原始证据；Knowledge 与 Event 不互相转化；WikiCard 把同一坐标下的知识与事件放在一起。</p>
+        <p>Document 保留原始证据；Knowledge 与 Event 是并列事实。WikiCard 组织 Knowledge，并按坐标引用 Event。</p>
       </div>
 
-      <div className="attributionGuidePipeline" role="img" aria-label="Document 并行提取 Knowledge 和 Event，再按 Object、Action、Scene 坐标汇总到 WikiCard">
+      <div className="attributionGuidePipeline" role="img" aria-label="Document 并行提取 Knowledge 和 Event；Knowledge 按坐标生成 WikiCard，Event 按坐标建立引用">
         <GuideNode tone="source" icon={<FileText size={17} />} label="Document" title="原始记录" detail="复盘、工单、聊天、日志说明" />
         <GuideConnector label="并行抽取" />
         <div className="attributionGuideBranches">
           <GuideNode tone="knowledge" icon={<Lightbulb size={17} />} label="Knowledge" title="知识与方法" detail="可脱离本次事件复用" />
           <GuideNode tone="event" icon={<CircleDot size={17} />} label="Event" title="一次具体发生" detail="时间线、证据、结果与缺项" />
         </div>
-        <GuideConnector label="按坐标汇总" />
-        <GuideNode tone="card" icon={<GitBranch size={17} />} label="WikiCard" title="坐标知识页" detail="同坐标下 N 个 Knowledge / Event" />
+        <GuideConnector label="Knowledge 成卡；Event 引用" />
+        <GuideNode tone="card" icon={<GitBranch size={17} />} label="WikiCard" title="知识组织页" detail="组织 Knowledge，链接同坐标 Event" />
       </div>
 
       <div className="attributionGuideRelations" aria-label="补充关系">
@@ -120,9 +121,9 @@ export function AttributionEventGuide(): ReactNode {
         <h3 id="attribution-event-memory-title">Event 记录经历，Knowledge 保存可复用判断</h3>
         <p>
           多个 Event 可以成为总结 Knowledge 的证据，但提炼需要单独验证，不能因相似就自动合并。
-          Agent 按坐标找到 WikiCard 后，可以同时读取可复用 Knowledge 与历史 Event；Event 可补全后续复盘文档。
+          Agent 按坐标找到 WikiCard 后，可以读取可复用 Knowledge，并用 `get_knowledge_events` 沿卡片引用查看历史 Event；Event 可补全后续复盘文档。
         </p>
-        <p className="attributionGuideClosingRule"><strong>一句话：</strong>Document 同时抽 Knowledge 与 Event；两者共用坐标，按各自身份判重，再由 WikiCard 汇总呈现。</p>
+        <p className="attributionGuideClosingRule"><strong>一句话：</strong>Document 同时抽 Knowledge 与 Event；Knowledge 生成 WikiCard，Event 按坐标被引用并独立保存。</p>
       </div>
     </section>
   </article>

package/src/client/CompileDialogs.tsx

@@ -121,7 +121,15 @@ function elapsed(from: string, to: number): string {
  * 条形只是让人一眼看出「大概到哪了」，精确的账在文字里。没有这一行文字，那条按阶段均分
  * 的进度条就会被当成精确值，而在「抽取」这一段特别慢的库里它会显得长期不动。
  */
-function overallRatio(progress: CompileProgressView): number {
+/**
+ * 编译进度 → 0..1 的比例。**这是唯一一份**（0070）。
+ *
+ * 曾经有两个副本，而它们对「已结束」的处理不一致：一个只要 `finishedAt` 存在就返回
+ * 满格（把 failed / cancelled 也画成「完成」），另一个排除了这两种状态。同一个失败在
+ * 导入对话框里是满格主色、在编译对话框里是红色未完成 —— 两屏说两件事。
+ * 所以导出它，让两个消费者用同一份判断。
+ */
+export function compileRatio(progress: CompileProgressView): number {
   if (progress.finishedAt !== undefined && progress.state !== 'cancelled' && progress.state !== 'failed') return 1
   const total = progress.steps.length || 1
   const done = progress.steps.filter(step => step.state === 'done').length
@@ -168,7 +176,7 @@ export function CompileProgressDialog({ open, onOpenChange, progress, mine, queu
   const completed = done && progress?.state !== 'cancelled' && progress?.state !== 'failed'
   const stopped = progress?.state === 'cancelled'
   const failed = progress?.state === 'failed'
-  const ratio = progress === null ? 0 : overallRatio(progress)
+  const ratio = progress === null ? 0 : compileRatio(progress)
   const doneSteps = progress?.steps.filter(step => step.state === 'done').length ?? 0
   const finishedText = progress?.outcome
     ?? (progress === null ? (queued === true ? '排在前面那一次编译之后，轮到它就会开始。' : '正在建立编译任务…') : '编译结束。')

package/src/client/EnvironmentSetup.tsx

@@ -1,8 +1,8 @@
 import { useCallback, useEffect, useState, type ReactNode } from 'react'
 import { Button, cn, Select, SelectContent, SelectItem, SelectLabel, SelectGroup, SelectTrigger, SelectValue } from '@tita-agent/ui/components'
 import { AlertCircle, Check, ChevronDown, Download, LoaderCircle, RefreshCw } from '@tita-agent/ui/icons'
-import type { ModelSelection, ModelOptionView } from '../environment/model-catalog.js'
-import type { EnvironmentView } from '../environment/types.js'
+import { downloadBytes, formatBytes, type ModelSelection, type ModelOptionView } from '../environment/model-catalog.js'
+import type { EnvironmentCurrentModel, EnvironmentView } from '../environment/types.js'
 
 async function environmentRequest(init?: RequestInit): Promise<EnvironmentView> {
   const response = await fetch(init ? '/knowledge/environment/prepare' : '/knowledge/environment', init)
@@ -41,42 +41,91 @@ export function useKnowledgeEnvironment(visible: boolean, revision: number) {
 
 type EnvironmentController = ReturnType<typeof useKnowledgeEnvironment>
 
-function ModelSelect({ id, label, value, options, disabled, onChange }: {
+function ModelSelect({ id, label, value, options, currentModel, disabled, onChange }: {
   id: string
   label: string
   value: string
   options: ModelOptionView[]
+  currentModel: EnvironmentCurrentModel
   disabled: boolean
   onChange: (value: string) => void
 }): ReactNode {
   const chosen = options.find(option => option.id === value)
-  const descriptionId = `${id}-description`
   return <div className="grid min-w-0 gap-1.5">
     <label htmlFor={id} className="text-xs font-medium text-tita-ink">{label}</label>
     <Select value={value} onValueChange={onChange} disabled={disabled}>
-      <SelectTrigger id={id} aria-describedby={descriptionId} className="w-full"><SelectValue /></SelectTrigger>
+      <SelectTrigger id={id} className="w-full"><SelectValue>{chosen?.label ?? '请选择模型'}</SelectValue></SelectTrigger>
       <SelectContent position="popper" align="start" className="max-h-64">
         <SelectGroup>
-          <SelectLabel>按资源占用从低到高</SelectLabel>
-          {options.map(option => <SelectItem key={option.id} value={option.id}>
-            {option.label} · {option.download}
+          {!currentModel.id && <>
+            <SelectLabel>当前运行</SelectLabel>
+            <SelectItem value={`${id}-current`} disabled className="h-auto items-start py-1.5">
+              {currentModel.state === 'active' ? `当前使用：${currentModel.label}` : '当前未启用'}
+            </SelectItem>
+          </>}
+          <SelectLabel>模型选项 · 按资源占用从低到高</SelectLabel>
+          {options.map(option => <SelectItem key={option.id} value={option.id} className="h-auto items-start py-2">
+            <span className="flex min-w-0 flex-1 flex-col gap-0.5">
+              <span className="flex min-w-0 items-center gap-2">
+                <span className="min-w-0 flex-1 truncate font-medium">{option.label}</span>
+                {/* 下载状态：不知道就不标（服务端没给资源目录时 `installed` 是 undefined）。 */}
+                {option.installed === true && <span className="shrink-0 rounded-md border border-tita-tone-green-line bg-tita-tone-green-tint px-1.5 py-0.5 text-[10px] font-medium leading-none text-tita-tone-green">已下载</span>}
+                {option.installed === false && <span className="shrink-0 rounded-md border border-tita-line bg-tita-surface-muted px-1.5 py-0.5 text-[10px] font-medium leading-none text-tita-ink-muted">需下载</span>}
+                {option.id === currentModel.id && <span className="shrink-0 rounded-md border border-tita-line bg-tita-surface-muted px-1.5 py-0.5 text-[10px] font-medium leading-none text-tita-ink">当前使用</span>}
+              </span>
+              <span className="line-clamp-2 text-[11px] leading-snug text-tita-ink-muted">
+                {option.download}{option.dimension ? ` · ${option.dimension} 维` : ''} · {option.description}
+              </span>
+            </span>
           </SelectItem>)}
         </SelectGroup>
       </SelectContent>
     </Select>
-    <p id={descriptionId} className="m-0 text-xs leading-relaxed text-tita-ink-muted">
-      {chosen ? `${chosen.description} 下载约 ${chosen.download}${chosen.dimension ? `，输出 ${chosen.dimension} 维` : ''}。` : '请选择模型。'}
-    </p>
     {chosen?.modelCardUrl && <a href={chosen.modelCardUrl} target="_blank" rel="noreferrer" className="w-fit text-xs text-tita-ink underline underline-offset-2">查看模型卡与许可</a>}
   </div>
 }
 
+/**
+ * 这次点「安装」会下多少。
+ *
+ * 模型列表里每个选项自己标了「已下载 / 需下载」，但人真正要判断的是**这一次的总量**：
+ * 两个模型都可能已下载（那就只是补依赖 + 自检），也可能只差一个。所以把所选的两个加起来，
+ * 已下载的不重复计 —— 已下载的模型不会重新下载（HF 缓存 + 目标目录都在）。
+ */
+function DownloadSummary({ embedding, rerank, chosen }: { embedding: ModelOptionView[]; rerank: ModelOptionView[]; chosen: ModelSelection }): ReactNode {
+  const pick = (options: ModelOptionView[], id: string): ModelOptionView | undefined => options.find(option => option.id === id)
+  const pending = [pick(embedding, chosen.embedding), pick(rerank, chosen.rerank)]
+    .filter((option): option is ModelOptionView => option !== undefined && option.installed === false)
+  if (pending.length === 0) {
+    return <p className="m-0 text-xs leading-relaxed text-tita-ink-muted" role="status">
+      {pick(embedding, chosen.embedding)?.installed === true && pick(rerank, chosen.rerank)?.installed === true
+        ? '所选模型都已下载，安装只需补齐推理依赖并重新自检。'
+        : '无法读取模型下载状态，安装会按需要补齐。'}
+    </p>
+  }
+  const bytes = pending.reduce((sum, option) => sum + (downloadBytes(option.download) ?? 0), 0)
+  // 两个以上才报合计：一个模型时合计与它自己那句是同一个数，纯重复。
+  const total = pending.length > 1 && bytes > 0 ? `，合计${formatBytes(bytes)}` : ''
+  return <p className="m-0 text-xs leading-relaxed text-tita-ink" role="status">
+    本次需下载{pending.map(option => `${option.label}（${option.download}）`).join('、')}{total}；已下载的不会重下。
+  </p>
+}
+
 export function EnvironmentNotice({ controller, onOpen }: { controller: EnvironmentController; onOpen: () => void }): ReactNode {
   const { view, error, busy } = controller
   if (!error && (!view || view.report.state === 'ready')) return null
+  const items = view?.report.items ?? []
+  const failed = items.some(item => item.state === 'failed')
+  const missing = items.some(item => item.state === 'missing')
+  const previouslyChecked = Boolean(view?.report.checkedAt)
+  const message = error ? '环境状态读取失败'
+    : busy ? view?.job?.stage ?? '正在检查运行环境'
+      : failed ? '模型推理自检未通过，请查看原因并修复'
+        : missing ? '请准备或启用向量与重排模型，再运行自检'
+          : previouslyChecked ? '模型配置或资源已变化，请重新自检' : '首次使用前，请准备并自检向量与重排模型'
   return <div className="mx-3 mt-2 flex shrink-0 items-center gap-2 border-b border-tita-line pb-2 text-xs text-tita-ink" role="status">
     {busy ? <LoaderCircle size={14} className="tita-spin shrink-0" /> : <AlertCircle size={14} className="shrink-0 text-tita-warning" />}
-    <span className="min-w-0 flex-1">{error ? '环境状态读取失败' : busy ? view?.job?.stage ?? '正在检查运行环境' : '首次使用前，请准备向量和重排模型'}</span>
+    <span className="min-w-0 flex-1">{message}</span>
     <Button variant="outline" size="sm" onClick={onOpen}>环境准备</Button>
   </div>
 }
@@ -93,6 +142,11 @@ export function EnvironmentSetup({ controller }: { controller: EnvironmentContro
   const running = job?.state === 'running'
   const failure = job?.state === 'failed' ? job.error : undefined
   const chosen = selection ?? view?.selection
+  /** 已下载、但当前选择没用到的那些：只报出来，不替人删。 */
+  const unusedModels = view ? [
+    ...view.models.embedding.filter(option => option.installed === true && option.id !== view.selection.embedding),
+    ...view.models.rerank.filter(option => option.installed === true && option.id !== view.selection.rerank),
+  ] : []
   const selectionChanged = Boolean(chosen && view && (chosen.embedding !== view.selection.embedding || chosen.rerank !== view.selection.rerank))
   return <section id="tita-environment" tabIndex={-1} aria-labelledby="tita-environment-title" className="tita-settingsSection">
     <div className="tita-settingsSectionHeader">
@@ -113,12 +167,13 @@ export function EnvironmentSetup({ controller }: { controller: EnvironmentContro
       </li>)}
     </ul>
     {view && chosen && <div className="my-4 grid gap-3" aria-label="模型选择">
-      <ModelSelect id="tita-embedding-model" label="向量模型" value={chosen.embedding} options={view.models.embedding} disabled={busy}
+      <ModelSelect id="tita-embedding-model" label="向量模型" value={chosen.embedding} currentModel={view.current.embedding} options={view.models.embedding} disabled={busy}
         onChange={value => setSelection(current => ({ ...(current ?? view.selection), embedding: value as ModelSelection['embedding'] }))} />
-      <ModelSelect id="tita-rerank-model" label="重排模型" value={chosen.rerank} options={view.models.rerank} disabled={busy}
+      <ModelSelect id="tita-rerank-model" label="重排模型" value={chosen.rerank} currentModel={view.current.rerank} options={view.models.rerank} disabled={busy}
         onChange={value => setSelection(current => ({ ...(current ?? view.selection), rerank: value as ModelSelection['rerank'] }))} />
+      <DownloadSummary embedding={view.models.embedding} rerank={view.models.rerank} chosen={chosen} />
       {selectionChanged && <p className="m-0 text-xs leading-relaxed text-tita-warning" role="status">
-        安装并通过实际推理自检后才会切换当前模型。更改向量模型后，已有知识需要重新编译。
+        安装将启用所选本地模型，并替换高级设置中的自定义模型路径。自检失败会恢复原设置。更改向量模型后，请构建检索索引。
       </p>}
     </div>}
     {!view && !error && <p className="text-xs text-tita-ink-muted" role="status">正在读取环境状态…</p>}
@@ -132,12 +187,17 @@ export function EnvironmentSetup({ controller }: { controller: EnvironmentContro
       <Button variant="outline" size="sm" disabled={busy || selectionChanged} onClick={() => { void prepare('check') }}><RefreshCw size={13} />重新自检</Button>
       {running && <Button variant="ghost" size="sm" disabled={controller.busy && !running} onClick={() => { void prepare('cancel') }}>停止</Button>}
     </div>
-    {ready && <p className="mb-0 mt-3 text-xs text-tita-ink-muted">环境自检通过。已有知识请重新编译，以生成当前模型的向量索引。</p>}
+    {ready && <p className="mb-0 mt-3 text-xs text-tita-ink-muted">环境自检通过。已有卡片请构建检索索引，文档无需重新抽取。</p>}
     <Button variant="ghost" size="sm" className="mt-2" aria-expanded={details} aria-controls="tita-environment-details" onClick={() => setDetails(value => !value)}>
       <ChevronDown size={13} />{details ? '收起检查详情' : '检查详情与日志'}
     </Button>
     {details && <div id="tita-environment-details" className="mt-2 grid gap-2 text-xs leading-relaxed text-tita-ink-muted">
       {view?.report.checkedAt && <p className="m-0">最近自检：{new Date(view.report.checkedAt).toLocaleString()}</p>}
+      {/* 切换模型不会删掉旧的：它们留在资源目录里，重下不会发生，但会占磁盘。
+          这里只如实列出来 —— 删目录是不可逆的，不该由这一栏的一个按钮决定。 */}
+      {unusedModels.length > 0 && <p className="m-0">
+        已下载但未启用：{unusedModels.map(option => `${option.label}（${option.download}）`).join('、')}。它们留在资源目录里，不会被重新下载。
+      </p>}
       {view?.report.items.map(item => item.path && <p key={item.id} className="m-0 break-all">{item.label}：{item.path}</p>)}
       {job?.logs.length ? <pre className="m-0 max-h-40 overflow-auto whitespace-pre-wrap break-all rounded-tita-control bg-tita-surface-muted p-2 font-mono">{job.logs.join('\n')}</pre> : null}
     </div>}

package/src/client/ExpansionGraph.tsx

@@ -33,6 +33,10 @@ import { ExternalLink } from '@tita-agent/ui/icons'
 import { layoutGraph, type PlacedGraph, type PlacedNode } from './graph/layout.ts'
 import { cardKey, expansionGraphData, radiusOf, type ExpansionHit, type ExpansionNeighbor } from './graph/expansion.ts'
 import { edgeStyleOf } from './graph/edges.ts'
+import {
+  HIT_FILL as PALETTE_HIT_FILL, LABEL_FAINT as PALETTE_LABEL_FAINT, LABEL_INK as PALETTE_LABEL_INK,
+  NEIGHBOR_FILL as PALETTE_NEIGHBOR_FILL, OUTLINE_MUTED as PALETTE_OUTLINE_MUTED,
+} from './graph/palette.ts'
 import { styles } from './styles.ts'
 
 export type { ExpansionHit, ExpansionNeighbor } from './graph/expansion.ts'
@@ -62,14 +66,16 @@ const EXPANSION_METRICS = { nodeW: 104, nodeH: 26, linkDistance: 72, stage: 300,
 /*
  * 画布侧的颜色都是**字面量**：canvas 渲染器不认 CSS 变量，写 `var(--tita-primary)`
  * 会被解析成全透明黑（`parseColor` 的兜底）。图例上的色块必须与画布上的圆点同色，
- * 所以它在 CSS 里写了一份，并在注释里点名这里。
+ * 所以它在 CSS 里写了一份，并在注释里点名这里 —— 画布这一侧的值全部来自
+ * `graph/palette.ts`（三处各写一份正是它们漂开的真正原因）。
  */
-const HIT_FILL = '#4868b2'
-const NEIGHBOR_FILL = '#ffffff'
-const OUTLINE = '#4868b2'
-const OUTLINE_MUTED = '#98a2b3'
-const LABEL_INK = '#101828'
-const LABEL_FAINT = '#667085'
+const HIT_FILL = PALETTE_HIT_FILL
+const NEIGHBOR_FILL = PALETTE_NEIGHBOR_FILL
+/** 命中点的描边与填充同色：它是一个实心点，靠邻居的「空心」来区分两者。 */
+const OUTLINE = PALETTE_HIT_FILL
+const OUTLINE_MUTED = PALETTE_OUTLINE_MUTED
+const LABEL_INK = PALETTE_LABEL_INK
+const LABEL_FAINT = PALETTE_LABEL_FAINT
 /** 标签用的字面量字族：同上，canvas 读不到 `--font-tita`。 */
 const LABEL_FONT = '-apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif'