dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/client/DirectoryPicker.tsx

@@ -0,0 +1,357 @@
+/**
+ * 根路径的选择与预览（0029）。
+ *
+ * 三件事，一个文件：
+ *
+ * 1. `DirectoryPickerField` —— 设置里的**那个**路径字段。它是一个只读显示 + 一个
+ *    「选择文件夹」按钮，不是一个输入框：路径是磁盘事实，让人手打只会得到拼错的
+ *    路径，而这一处错误决定整个 Agent 的东西存在哪。
+ * 2. `DirectoryBrowser` —— 宿主只能「列一层 / 建子目录」时（浏览器在远端）的页面内
+ *    浏览框。本机部署走系统对话框，这个框不会出现；但它是远端唯一能用的形态，所以
+ *    不能只有一句「不支持」。
+ * 3. `LayoutPreview` —— 把服务端算出来的四段布局画出来。目录结构本身就是这个方案
+ *    要交代的东西，所以它显式地摆在设置里，而不是等用户去磁盘上发现。
+ *
+ * @module
+ */
+
+import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react'
+import { Button, Input, cn } from '@tita-data-agent/ui/components'
+import { Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle } from '@tita-data-agent/ui/overlays'
+import { AlertCircle, Check, ChevronRight, FolderOpen, FolderPlus, Home, LoaderCircle } from '@tita-data-agent/ui/icons'
+
+interface Envelope<T> { ok?: boolean; data?: T; warnings?: string[]; error?: { code?: string; message?: string; suggestion?: string } }
+
+async function call<T>(url: string, init?: RequestInit): Promise<T> {
+  const response = await fetch(url, init)
+  const text = await response.text()
+  if (!text.trim()) throw new Error(`服务端返回空响应（HTTP ${response.status}）`)
+  let payload: Envelope<T>
+  try {
+    payload = JSON.parse(text) as Envelope<T>
+  } catch {
+    throw new Error(`服务端返回了无效响应（HTTP ${response.status}）`)
+  }
+  if (!response.ok || payload.ok === false) {
+    const base = payload.error?.message ?? `请求失败（${response.status}）`
+    const error = new Error(payload.error?.suggestion ? `${base} —— ${payload.error.suggestion}` : base) as Error & { code?: string }
+    error.code = payload.error?.code ?? (response.status === 404 ? 'NOT_FOUND' : undefined)
+    throw error
+  }
+  return payload.data as T
+}
+
+/**
+ * 接口不存在时**不要**把服务端的原话（「knowledge endpoint 不存在」）甩给用户。
+ *
+ * 它只会在一种情况下出现：客户端已经更新、宿主进程还在跑旧代码 —— 也就是「改了
+ * 插件但没重启 DSH」。这句话对用户没有任何可操作性，而真正要做的动作只有一个。
+ * 所以把它翻译成那一个动作。
+ */
+function explain(cause: unknown, fallback: string): string {
+  const code = (cause as { code?: string } | undefined)?.code
+  if (code === 'NOT_FOUND') return '目录布局接口还没生效 —— 插件代码更新了，但宿主进程还在跑旧的，重启 DSH 后即可。'
+  return cause instanceof Error ? cause.message : fallback
+}
+
+/** 一个目录行。与服务端 `directory-picker.ts` 的 `DirectoryEntry` 同形。 */
+interface DirectoryEntry { name: string; path: string; hidden: boolean }
+interface DirectoryListing { path: string; home: string; crumbs: DirectoryEntry[]; entries: DirectoryEntry[]; truncated: boolean }
+/** `/knowledge/layout` 的返回。 */
+export interface AgentLayoutView {
+  agentRoot: string
+  domainKnowledge: string
+  /** 0029：记忆那一段（版本快照、反馈、访问审计），按知识库分格。 */
+  memory: string
+  /** 意图记录那一段。 */
+  intent: string
+  tmp: string
+  /** 0029：家当那一段（模型 / Python 环境 / 注册表）。 */
+  resource: string
+  migration?: MigrationView
+  resourceMigration?: MigrationView
+  /** 三个「家当」路径**解析后**的值：设置里空着 = 自动，这里给的是它实际指向哪。 */
+  resources?: { python: string; embeddingModel: string; rerankModel: string }
+  /**
+   * 没落在 `resource/` 下的家当（服务端算的，见 `index.ts` 的 `outsideResource`）。
+   *
+   * `outside` = 是绝对路径但在别处（旧家当目录），迁移会把它搬进来；
+   * `bare` = 根本不是一个路径（`python3`、`BAAI/bge-reranker-base`），迁移搬不了它。
+   */
+  resourcesOutsideResource?: Array<{ key: string; value: string; kind: 'outside' | 'bare' }>
+  /**
+   * 设置分区注册失败的原因。
+   *
+   * 设置层在**登记命名空间**时就会解析一次 schema，所以 schema 里一个错误会让整个
+   * 分区注册不上：面板显示「设置服务不可用」、迁移不执行、存下来的设置一个都不生效。
+   * 有这句话，界面才能说「为什么」，而不是只显示症状。
+   */
+  settingsError?: string
+  pickerKind: string | null
+  /**
+   * preset 的**真源目录**（`<包根>/preset/tita-data-agent/`）。
+   *
+   * 提示词的唯一真源就在这个目录里的 `agent.cordis.yml`。0.1.7 起 DSH 那边 preset
+   * 不再是一个目录（它是组合里的一条声明行），所以「打开 preset 目录」打开的是
+   * 这个随插件分发的真源目录 —— 服务端算好给出来，客户端不拼路径。
+   */
+  presetDir?: string
+  /** 真源目录在不在。不在时界面如实说，而不是给一个弹空目录的按钮。 */
+  presetDirExists?: boolean
+}
+
+interface MigrationView {
+  status: 'skipped' | 'moved' | 'failed'
+  from?: string
+  to?: string
+  moved?: string[]
+  reason?: string
+}
+
+/** 读一次布局。设置面板与目录选择都用它。 */
+export function useAgentLayout(refreshKey: unknown): { layout: AgentLayoutView | null; error: string | null; reload: () => void } {
+  const [layout, setLayout] = useState<AgentLayoutView | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [nonce, setNonce] = useState(0)
+  useEffect(() => {
+    let alive = true
+    void call<AgentLayoutView>('/knowledge/layout')
+      .then(next => { if (alive) { setLayout(next); setError(null) } })
+      .catch(cause => { if (alive) setError(explain(cause, '读取目录布局失败')) })
+    return () => { alive = false }
+  }, [refreshKey, nonce])
+  return { layout, error, reload: useCallback(() => setNonce(value => value + 1), []) }
+}
+
+/* ─────────────────────────────────────────────────────────── 字段 */
+
+/**
+ * 根路径字段。
+ *
+ * 值的来源只有两个：用户选了一个目录，或者什么都没选（空串 = 用默认值）。
+ * 所以这里的 `<Input>` 是 `readOnly` —— 不是「暂时不给编辑」，是**这个字段本来
+ * 就不接受手打**。
+ */
+export function DirectoryPickerField({ label, value, onChange, disabled, pickerKind, onError }: {
+  /** 字段名。由调用方从 `spec.label` 传进来 —— 写死一份就等于同一件事有两个出处。 */
+  label: string
+  value: string
+  onChange: (next: string) => void
+  disabled: boolean
+  /** 宿主提供哪种交互；`null` 表示没挂目录选择器。 */
+  pickerKind: string | null
+  onError: (message: string | null) => void
+}): ReactNode {
+  const [busy, setBusy] = useState(false)
+  const [browsing, setBrowsing] = useState(false)
+
+  const choose = async (): Promise<void> => {
+    setBusy(true); onError(null)
+    try {
+      const picked = await call<{ kind: 'native' | 'browse'; path?: string | null }>('/knowledge/pick-directory', { method: 'POST' })
+      if (picked.kind === 'browse') setBrowsing(true)
+      else if (picked.path) onChange(picked.path)
+    } catch (cause) {
+      onError(explain(cause, '打开文件夹对话框失败'))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return <div className="tita-settingField">
+    <span>{label}</span>
+    <div className="tita-pickerRow">
+      {/* 只读而不是 disabled：disabled 的输入框读不出「这是当前值」，只读的能选中复制。 */}
+      <Input readOnly value={value} placeholder="未设置（使用默认位置）" aria-label={label} />
+      <Button variant="outline" onClick={() => void choose()} disabled={disabled || busy}>
+        {busy ? <LoaderCircle size={14} className="tita-spin" /> : <FolderOpen size={14} />}
+        {busy ? '等待选择…' : '选择文件夹'}
+      </Button>
+    </div>
+    <small className="tita-settingHint">
+      {pickerKind === 'browse'
+        ? '浏览器不在宿主那台机器上，所以这里会在页面内打开一个目录浏览框。'
+        : pickerKind === 'native'
+          ? '会打开系统文件夹对话框；取消对话框不会改动当前值。'
+          : '宿主没有提供目录选择器。若你刚更新过插件，重启 DSH 后这里会变成系统文件夹对话框。'}
+    </small>
+    {browsing && <DirectoryBrowser
+      onClose={() => setBrowsing(false)}
+      onPick={next => { onChange(next); setBrowsing(false) }}
+    />}
+  </div>
+}
+
+/* ─────────────────────────────────────────────────────── 页面内浏览 */
+
+/**
+ * 页面内目录浏览框（browse 形态）。
+ *
+ * 一列到底而不是 Miller 双列：这里只服务一个目的 —— 选一个根路径。双列在
+ * 「要找的那个目录就在下一层」时更快，但多出一整列的宽度与一套选中态；而这个
+ * 框是**兜底**形态，简单比快更重要。
+ */
+function DirectoryBrowser({ onPick, onClose }: { onPick: (path: string) => void; onClose: () => void }): ReactNode {
+  const [listing, setListing] = useState<DirectoryListing | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [showHidden, setShowHidden] = useState(false)
+  const [newName, setNewName] = useState('')
+  const [creating, setCreating] = useState(false)
+  /** 请求序号：快速连点目录时，只让最后一次的结果落地。 */
+  const seq = useRef(0)
+
+  const open = useCallback((path?: string): void => {
+    const ticket = ++seq.current
+    setLoading(true); setError(null)
+    void call<DirectoryListing>(`/knowledge/browse-directory${path ? `?path=${encodeURIComponent(path)}` : ''}`)
+      .then(next => { if (ticket === seq.current) setListing(next) })
+      .catch(cause => { if (ticket === seq.current) setError(cause instanceof Error ? cause.message : String(cause)) })
+      .finally(() => { if (ticket === seq.current) setLoading(false) })
+  }, [])
+
+  useEffect(() => { open() }, [open])
+
+  const create = async (): Promise<void> => {
+    if (!listing || !newName.trim()) return
+    setCreating(true); setError(null)
+    try {
+      const created = await call<{ path: string }>('/knowledge/create-directory', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ path: listing.path, name: newName }),
+      })
+      setNewName('')
+      open(created.path)
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause))
+    } finally {
+      setCreating(false)
+    }
+  }
+
+  const rows = (listing?.entries ?? []).filter(entry => showHidden || !entry.hidden)
+
+  return <Dialog open onOpenChange={next => { if (!next) onClose() }}>
+    <DialogContent className="tita-browseDialog">
+      <DialogHeader><DialogTitle>选择文件夹</DialogTitle></DialogHeader>
+
+      <nav className="tita-browseCrumbs" aria-label="路径">
+        <button type="button" className="tita-browseCrumb" onClick={() => open(listing?.home)} title="回到主目录">
+          <Home size={12} />
+        </button>
+        {(listing?.crumbs ?? []).map((crumb, index) => <span key={crumb.path} className="tita-browseCrumbWrap">
+          <ChevronRight size={11} aria-hidden />
+          <button
+            type="button"
+            className={cn('tita-browseCrumb', index === (listing?.crumbs.length ?? 0) - 1 && 'tita-browseCrumbOn')}
+            onClick={() => open(crumb.path)}
+          >{crumb.name}</button>
+        </span>)}
+      </nav>
+
+      <div className="tita-browsePath" title={listing?.path ?? ''}>{listing?.path ?? '…'}</div>
+
+      {error && <p className="tita-browseError" role="alert"><AlertCircle size={13} />{error}</p>}
+
+      <ul className="tita-browseList">
+        {loading && !listing && <li className="tita-browseEmpty">正在读取…</li>}
+        {!loading && rows.length === 0 && <li className="tita-browseEmpty">这一层没有子文件夹。</li>}
+        {rows.map(entry => <li key={entry.path}>
+          <button type="button" className="tita-browseRow" onDoubleClick={() => open(entry.path)} onClick={() => open(entry.path)}>
+            <FolderOpen size={14} />{entry.name}
+          </button>
+        </li>)}
+      </ul>
+
+      {listing?.truncated && <p className="tita-browseNote">这一层文件夹太多，只列出了前一部分。</p>}
+
+      <div className="tita-browseCreate">
+        <Input value={newName} placeholder="在此新建文件夹" onChange={event => setNewName(event.target.value)} onKeyDown={event => { if (event.key === 'Enter') void create() }} />
+        <Button variant="outline" onClick={() => void create()} disabled={creating || !newName.trim()}><FolderPlus size={14} />新建</Button>
+        <label className="tita-browseHidden"><input type="checkbox" checked={showHidden} onChange={event => setShowHidden(event.target.checked)} />显示隐藏项</label>
+      </div>
+
+      <DialogFooter>
+        <Button variant="ghost" onClick={onClose}>取消</Button>
+        <Button variant="default" disabled={!listing} onClick={() => { if (listing) onPick(listing.path) }}>
+          <Check size={14} />选择这个文件夹
+        </Button>
+      </DialogFooter>
+    </DialogContent>
+  </Dialog>
+}
+
+/* ─────────────────────────────────────────────────────── 布局预览 */
+
+/**
+ * 根路径下会长出来的段。顺序即它们出现的顺序，理由见 `layout.ts`。
+ *
+ * **`output` 不在这张表里**：交付物跟着工作项目走，落在工作区的 `output/<日期>/`，
+ * 不落在这个根路径下。把不属于这里的东西画进这张表，用户就会照着去这个目录找他的报告。
+ */
+const SEGMENTS: Array<{ key: 'domainKnowledge' | 'memory' | 'intent' | 'tmp' | 'resource'; name: string; note: string; keep: string }> = [
+  { key: 'domainKnowledge', name: 'domain_knowledge/', note: '知识树：每个知识库一格，里面是 SourceRaw、wiki 与编译产物', keep: '必须备份' },
+  { key: 'memory', name: 'memory/', note: '记忆：版本快照、反馈与访问审计，按知识库分格', keep: '删掉会丢历史版本' },
+  { key: 'intent', name: 'intent/', note: '意图记录：每轮「用户要什么」的留痕', keep: '可随时清空' },
+  { key: 'tmp', name: 'tmp/', note: '运行期临时文件：转换工作区与任务状态，二级按日期分桶', keep: '删掉只影响未完成的任务' },
+  { key: 'resource', name: 'resource/', note: 'Agent 跑起来所需要的家当：模型、Python 环境、知识库注册表', keep: '删掉会失去语义检索' },
+]
+
+/** 家当条目的中文名。路径本身没法读，用户看的是「哪个模型不在家当目录里」。 */
+const ASSET_LABELS: Record<string, string> = {
+  python: 'Python 环境',
+  embeddingModel: '嵌入模型',
+  rerankModel: '重排模型',
+}
+
+/**
+ * 布局预览。
+ *
+ * 它不只是「显示路径」，它同时回答四个问题：这个根路径下会长出什么、哪一段不能
+ * 删、上一次迁移把数据搬到哪了、以及**家当有没有真的在 `resource/` 里**。
+ * 目录结构的调整必须把原理一起交代出来，否则用户看到的只是三个陌生的文件夹名。
+ */
+export function LayoutPreview({ layout, error }: { layout: AgentLayoutView | null; error: string | null }): ReactNode {
+  if (error) return <p className="tita-layoutError" role="alert"><AlertCircle size={13} />{error}</p>
+  if (!layout) return <p className="tita-layoutError">正在读取目录布局…</p>
+  const outside = layout.resourcesOutsideResource ?? []
+  return <div className="tita-layoutPreview">
+    <ul className="tita-layoutSegments">
+      {SEGMENTS.map(segment => <li key={segment.key}>
+        <code>{segment.name}</code>
+        <span>{segment.note}</span>
+        <em>{segment.keep}</em>
+        <small title={layout[segment.key]}>{layout[segment.key]}</small>
+      </li>)}
+    </ul>
+    {/* 设置分区注册失败是**服务端**的故障，但用户先看到的是「设置服务不可用」这个
+        症状。把原因放在这里，才知道它不是自己的配置有问题。 */}
+    {layout.settingsError && <p className={cn('tita-kbNotice', 'tita-kbNoticeError')} role="alert">
+      <AlertCircle size={13} />
+      <span>设置分区没能注册：<code>{layout.settingsError}</code>。知识库设置会显示「设置服务不可用」，改动也不会生效 —— 这是插件 schema 的问题，不是你填错了。</span>
+    </p>}
+    {[layout.migration, layout.resourceMigration].map((migration, index) => {
+      if (!migration || migration.status === 'skipped') return null
+      const what = index === 0 ? '旧布局的知识树' : '旧位置的家当（模型 / Python 环境 / 注册表）'
+      return <p key={index} className={cn('tita-layoutMigration', migration.status === 'failed' && 'tita-layoutMigrationBad')}>
+        {migration.status === 'moved'
+          ? <>已把{what}从 <code>{migration.from}</code> 搬进 <code>{migration.to}</code>（{migration.moved?.length ?? 0} 项）。</>
+          : <>{what}搬迁失败：{migration.reason}。两边都还在原地，没有丢。</>}
+      </p>
+    })}
+    {/* 家当不在 `resource/` 下 = 删掉旧目录或 HF 缓存就会丢语义检索。两种原因要分开说，
+        因为要做的事完全不同：一种等迁移，一种得自己放。 */}
+    {outside.length > 0 && <div className="tita-layoutAssets" role="status">
+      <p><AlertCircle size={12} />{outside.length} 项家当不在 <code>resource/</code> 下</p>
+      <ul>
+        {outside.map(item => <li key={item.key}>
+          <b>{ASSET_LABELS[item.key] ?? item.key}</b>
+          {item.kind === 'outside'
+            ? <> 还在旧位置 <code>{item.value}</code> —— 下次重启会把家当搬进 <code>resource/</code>。</>
+            : <> 是 <code>{item.value}</code>，不是一个路径 —— 它从来不是家当，迁移搬不了它。要固定下来就放成 <code>resource/models/&lt;目录名&gt;</code>，或在设置里显式填一个路径。</>}
+        </li>)}
+      </ul>
+    </div>}
+  </div>
+}

package/src/client/InfoHint.tsx

@@ -0,0 +1,65 @@
+/**
+ * 小标题后面的说明入口：**图标常驻，说明悬停才出现**。
+ *
+ * ## 为什么把常驻说明改到这里
+ *
+ * 设置抽屉里每一节原来都在标题下面挂一段说明。六节连起来就是一屏解释文字，而用户打开
+ * 设置是来**改数值**的 —— 那些段落把真正要操作的控件挤到需要滚动才能看见。
+ *
+ * 说明本身有价值（「阈值是整条链路里唯一跨查询可比的相关性判据」这种话不该删），所以
+ * 不是删掉，而是挪到图标后面：要的时候悬停或聚焦就能看到，不要的时候不占地方。
+ *
+ * ## 两处刻意的决定
+ *
+ * 1. **触发体是 `<button>` 而不是 `<span>`**：`TooltipTrigger` 里放一个不可聚焦的元素，
+ *    等于这条说明对键盘用户不存在。按钮能 Tab 到，`aria-label` 让读屏直接念出全文。
+ * 2. **图标用共享 icon 模块里的 `CircleHelp`**，不自己画、也不在插件里再引一份 lucide ——
+ *    视觉真源是 `packages/ui`，多一套就会多一种描边粗细。
+ *
+ * @module
+ */
+
+import type { ReactNode } from 'react'
+import { CircleHelp } from '@tita-data-agent/ui/icons'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@tita-data-agent/ui/ui/tooltip'
+
+/**
+ * @param text - 要说明的内容。同时作为 `aria-label`，所以它必须是一句能独立读懂的话，
+ *   而不是碎片（读屏用户拿到的只有这一句）。
+ */
+export function InfoHint({ text }: { text: string }): ReactNode {
+  return <TooltipProvider>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button type="button" className="tita-infoHint" aria-label={text}>
+          <CircleHelp size={12} />
+        </button>
+      </TooltipTrigger>
+      {/*
+        `side="top"` + `avoidCollisions={false}` 必须**成对**用，只留一个都不对。
+
+        触发器在设置抽屉的**可滚动正文**里，而 radix 默认会拿裁剪祖先算碰撞：这一节的
+        标题正好是正文的第一个元素，「上方」落在正文的裁剪矩形之外，于是它把说明翻到
+        下方 —— 用户看到的就是「tips 没在上方，反而跑到下面去了」。
+
+        关掉翻转是安全的：说明通过 Portal 挂在 `body` 上，本来就不会被抽屉的 `overflow`
+        裁掉。翻转在这里解决的是一件并不存在的问题。
+
+        版式（限宽 / 换行 / 左对齐）交给插件 CSS 的 `.tita-infoHintPanel`，**不是**用
+        工具类覆盖 —— 插件没有自己的 Tailwind 构建：`max-w-[260px]` 这类任意值工具类
+        在插件里根本没有对应规则，而 `cn` 的 twMerge 又会先把 UI 包自带的 `max-w-xs`
+        删掉，结果是限宽彻底失效（实测宽度从 320px 变成 996px）。能生效的那几个
+        （`block`、`leading-relaxed`、`z-[1002]`）只是**碰巧** UI 包自己也用了同名类。
+
+        限宽那条规则写在 `styles.css` 里，选择器双写同名类以取得 (0,2,0) 的特异性 ——
+        见那里的说明。
+
+        `z-[1002]` 不是随手加的：UI 包的 tooltip 自带 `z-50`，而抽屉正文是 `z-[1001]`
+        （见 `overlays.tsx` 顶部那段关于弹层层级测量的注释）—— 不改的话 tips 会**画在
+        抽屉底下**，用户看到的就是「悬停什么都没出」。`SelectContent` 当年踩过同一个坑。
+        `cn` 是 `twMerge`，所以这里给的 `z-[1002]` 会直接替换掉 `z-50`，不需要 !important。
+      */}
+      <TooltipContent side="top" avoidCollisions={false} className="tita-infoHintPanel z-[1002]">{text}</TooltipContent>
+    </Tooltip>
+  </TooltipProvider>
+}

package/src/client/IntentLogicTab.tsx

@@ -0,0 +1,185 @@
+/**
+ * 「意图的逻辑」tab —— 把意图模型**讲清楚**，而不是只给一堆表单。
+ *
+ * 内容分五块，对应产品上的五个问题：什么是意图 / 为什么要配置 / 意图的描述是什么 /
+ * schema 各字段什么含义 / 背后的论文与术语。
+ *
+ * 这一页是**只读说明**：它不读引擎状态，也不写配置，所以不依赖 `settings` scope，
+ * 可以在设置服务不可用时照常阅读。
+ */
+
+import type { ReactNode } from 'react'
+import { CircleHelp, ClipboardCheck, Library, Lightbulb, ListTree } from '@tita-data-agent/ui/icons'
+import { Card } from '@tita-data-agent/ui/components'
+import { styles } from './styles.ts'
+
+/** 一张"字段含义"表。 */
+interface FieldDoc {
+  name: string
+  required: boolean
+  meaning: string
+  where: string
+}
+
+const RECORD_FIELDS: FieldDoc[] = [
+  { name: 'sessionKey', required: true, meaning: '这条意图属于哪个会话。记录按 session + turn 分组，TTL 到期即释放。', where: 'Host 从会话头取，模型不用传' },
+  { name: 'turnKey / turnId', required: true, meaning: '「哪一轮」。同一轮重复记录会 upsert 成一条，不会刷出多条流水。', where: 'Host 在 turn/start 时分配' },
+  { name: 'userInput', required: true, meaning: '本轮用户原文（截断到 2000 字）。它是审计的证据，不是分类的输入。', where: '模型从本轮消息里复制' },
+  { name: 'act', required: true, meaning: '用户在**做什么**：问、让做、补充、确认、取消……与 category 正交。', where: '模型从 act 词表里挑一个' },
+  { name: 'category', required: false, meaning: '这一轮属于**哪个业务类别**。两段式判定：先匹配预置，不命中才自创或落 unknown。', where: '模型判断，可在意图配置里预置' },
+  { name: 'predicate', required: false, meaning: '这轮最终要调的**工具/动作**，例如 query_babel_data。用来把意图和真实执行对齐。', where: '模型按可用工具填' },
+  { name: 'slots', required: false, meaning: '从用户话里抽出的关键参数（时间范围、对象、指标……），自由 JSON。', where: '模型抽取' },
+  { name: 'confidence', required: false, meaning: '模型自评把握度 0–1。低于澄清阈值只**标注** lowConfidence，不拦截请求。', where: '模型自评' },
+  { name: 'refs', required: false, meaning: '引用了哪些对象（表、文档、指标），形如 { id, kind, label }。', where: '模型抽取' },
+  { name: 'relation', required: true, meaning: '这轮与已有任务的关系：new_task（开新任务）/ subtask_of（续已有任务）/ unknown。', where: '模型判断，Host 校验 task 是否存在' },
+  { name: 'lineage', required: true, meaning: 'intentId / taskId / subtaskId / runId 四个 id 的链路，下游工具与产物靠它回溯。', where: 'Host 分配，模型可显式续接' },
+  { name: 'source', required: true, meaning: 'model = 模型记录；fallback = 轮次结束模型没记，Host 补的一条 unknown。', where: 'Host 标记' },
+]
+
+interface Paper {
+  title: string
+  authors: string
+  venue: string
+  url: string
+  /** 它对应本设计的哪一点。 */
+  relates: string
+  note?: string
+}
+
+const PAPERS: Paper[] = [
+  {
+    title: 'An Evaluation Dataset for Intent Classification and Out-of-Scope Prediction',
+    authors: 'Stefan Larson, Anish Mahendran, Joseph J. Peper, Christopher Clarke, Andrew Lee, Parker Hill, Jonathan Kummerfeld, Kevin Leach, Michael A. Laurenzano, Lingjia Tang, Jason Mars',
+    venue: 'EMNLP 2019（CLINC150）',
+    url: 'https://aclanthology.org/D19-1131/',
+    relates: '「全不命中怎么办」的标准答案：真实流量里必然有落在词表之外的句子，把它硬塞进最近的一类，比多问一句代价大得多。对应本设计的第 2 段（自创 id 或落 unknown）与 lowConfidence 标注。',
+    note: 'CLINC150 给出了 150 类 + out-of-scope 的评测集；数据集的标签体系与本产品的 12 类无关。',
+  },
+  {
+    title: 'A Survey of Joint Intent Detection and Slot Filling Models in Natural Language Understanding',
+    authors: 'H. Weld, X. Huang, S. Long, J. Poon, S. C. Han',
+    venue: 'ACM Computing Surveys, 2022',
+    url: 'https://dl.acm.org/doi/10.1145/3547138',
+    relates: '说明 intent 与 slot 为什么要一起看：`category`（意图）与 `slots`（参数）是同一个判断的两面。本设计把它们放在同一条记录里，就是为了不让"分类对了但参数丢了"成为常态。',
+    note: '这里只借它的问题定义与术语，没有训练任何联合模型。',
+  },
+  {
+    title: 'Efficient Intent Detection with Dual Sentence Encoders',
+    authors: 'Iñigo Casanueva, Tadas Temčinas, Daniela Gerz, Matthew Henderson, Ivan Vulić',
+    venue: 'NLP4ConvAI @ ACL 2020',
+    url: 'https://aclanthology.org/2020.nlp4convai-1.5/',
+    relates: '小样本下"用一句自然语言描述一个类别"就能做分类：这正是本设计的做法——预置分类用 `description` + `examples` 描述，而不是训练一个分类头。',
+    note: '该论文用双句编码器 + 少量标注样例；本产品直接把描述喂给大模型，没有额外模型。',
+  },
+  {
+    title: 'IntentGPT: Few-shot Intent Discovery with Large Language Models',
+    authors: 'Juan Rodriguez, Nicholas Botzer, David Vazquez, Christopher Pal, Marco Pedersoli, Issam H. Laradji',
+    venue: 'arXiv:2411.10670, 2024',
+    url: 'https://arxiv.org/abs/2411.10670',
+    relates: '对应第 2 段"不命中就自己起一个 id"：未知意图不应当被丢掉，而应当被发现为新类别。本设计把新 id 写进记录，后续可以据此把它提升为正式分类。',
+    note: '该论文用 LLM 做零样本意图发现并迭代扩展标签集；本产品只记录新 id，聚类/提升仍是人工动作。',
+  },
+  {
+    title: 'Recent Neural Methods on Dialogue State Tracking for Task-Oriented Dialogue Systems: A Survey',
+    authors: 'Vevake Balaraman, Seyedmostafa Sheikhalishahi, Bernhard Magnini',
+    venue: 'SIGDIAL 2021',
+    url: 'https://aclanthology.org/2021.sigdial-1.25/',
+    relates: '对应 `relation` 与任务链路：多轮对话里"这一轮是在续上一个任务还是开新任务"是对话状态的一部分，不是每轮独立判断。本设计把它显式建模为 new_task / subtask_of。',
+    note: '只借它的状态建模视角；本设计用规则 + 会话内已记录的任务集合来判定，没有跑 DST 模型。',
+  },
+]
+
+function Section({ icon: Icon, title, children }: { icon: typeof CircleHelp; title: string; children: ReactNode }): ReactNode {
+  return <Card className={styles.kbCard}>
+    <div className={styles.kbCardHead}>
+      <div><h3><Icon size={13} />{title}</h3></div>
+    </div>
+    {children}
+  </Card>
+}
+
+export function IntentLogicTab(): ReactNode {
+  return <div className={styles.viewStack}>
+    <Section icon={CircleHelp} title="什么是意图？">
+      <p className={styles.kbHint}>
+        这里说的「意图」不是要控制流程的指令，而是一条**审计事实**：这一轮用户在做什么、属于哪类业务、
+        要调什么动作、引用了哪些对象、和之前哪个任务同属一件事。
+      </p>
+      <ul className={styles.intentDocList}>
+        <li><b>判断完全交给大模型。</b>`intent_record` 只把模型给出的结论落成一条记录，不做关键词匹配、不做状态机、不反问、不阻断当前请求，也不会因为分类错了就让请求失败。</li>
+        <li><b>记录不驱动控制流。</b>它服务三件事：事后回溯（这轮到底想干什么）、链路串联（下游工具与产物继承 taskId / subtaskId）、质量观测（哪些轮次低置信度、哪些落到了 unknown）。</li>
+        <li><b>模型漏了也不丢。</b>轮次结束时如果没有任何记录，Host 补一条 <code>source: fallback</code> 的 unknown，保证"每轮一条"这个不变式成立。</li>
+      </ul>
+    </Section>
+
+    <Section icon={Lightbulb} title="为什么要配置意图？">
+      <p className={styles.kbHint}>
+        如果什么都不配，模型每轮都要**从零发明一套分类**。同一句话今天叫 data_analysis、明天叫
+        sales_query，记录就失去可比性：统计不出趋势，下游也接不住。
+      </p>
+      <ul className={styles.intentDocList}>
+        <li><b>预置分类是"先验"。</b>判定被拆成两段：先拿用户的话逐条比对预置分类的定义与例如说法，命中就直接用该 id；全不命中才自行判断。这让常见意图的判定从"生成"变成"匹配"，跨轮次稳定。</li>
+        <li><b>判定文案就是提示词。</b>每个分类的 `description` + `examples` 会拼进 `intent_record` 的工具描述，模型每次调用都看得到。写得越具体，越不需要临场发挥。</li>
+        <li><b>词表要能被改。</b>业务会变：今天做"测试评审"，明天做"合规检查"。分类、act 都在「意图配置」里就地增删改，保存后下一轮生效，不需要重启。</li>
+        <li><b>不追求一次分对。</b>拿不准就标 lowConfidence 或落 unknown，事后能筛出来复核——比强行归类更诚实。</li>
+      </ul>
+    </Section>
+
+    <Section icon={ListTree} title="意图的描述是什么？">
+      <p className={styles.kbHint}>
+        一条意图记录把"这一轮"描述成四个维度，它们互相正交，缺一个都会让回溯变模糊：
+      </p>
+      <div className={styles.intentDocGrid}>
+        <div><strong>做什么（act）</strong><span>问 / 让做 / 补充 / 确认 / 取消 …… 共 16 类，可配置。</span></div>
+        <div><strong>哪一类（category）</strong><span>数据分析 / 知识构建 / 产物交付 …… 12 类出厂预置，可配置。</span></div>
+        <div><strong>要调什么（predicate）</strong><span>最终落到哪个工具，例如 query_babel_data。</span></div>
+        <div><strong>和谁一起（relation + lineage）</strong><span>新任务还是续任务，以及 intentId / taskId / subtaskId / runId 链路。</span></div>
+      </div>
+      <p className={styles.kbHint}>
+        另一个维度是**把握度**：`confidence` 低于澄清阈值时记录被标成 lowConfidence。它只影响展示与筛选，
+        不改变这一轮的执行。
+      </p>
+    </Section>
+
+    <Section icon={ClipboardCheck} title="schema 分别是什么含义？">
+      <div className={styles.intentDocTableWrap}>
+        <table className={styles.intentDocTable}>
+          <thead><tr><th>字段</th><th>必填</th><th>含义</th><th>谁来填</th></tr></thead>
+          <tbody>
+            {RECORD_FIELDS.map(field => <tr key={field.name}>
+              <td><code>{field.name}</code></td>
+              <td>{field.required ? '✓' : ''}</td>
+              <td>{field.meaning}</td>
+              <td>{field.where}</td>
+            </tr>)}
+          </tbody>
+        </table>
+      </div>
+      <p className={styles.kbHint}>
+        配置侧还有三个 schema：<code>IntentCategory</code>（id / label / route / description / examples / enabled）、
+        <code>IntentActDef</code>（id / label / description / enabled）、以及 predicate 字符串表。
+        它们只决定"提示词给模型什么选项"，**不是校验闸门**：模型写了一个没配置的 act 或 category，
+        记录照样落库，只在 `warnings` 里说明。
+      </p>
+    </Section>
+
+    <Section icon={Library} title="引用了什么论文？">
+      <p className={styles.kbHint}>
+        诚实说明：**这套实现没有复现任何一篇论文的模型**。它是工程取舍的产物；下面是同一批问题的
+        公开研究，用来说明这些设计点不是凭空来的。每条都标了它对应哪一处设计。
+      </p>
+      <ul className={styles.intentPaperList}>
+        {PAPERS.map(paper => <li key={paper.url}>
+          <a href={paper.url} target="_blank" rel="noreferrer">{paper.title}</a>
+          <span className={styles.intentPaperMeta}>{paper.authors} · {paper.venue}</span>
+          <p>{paper.relates}</p>
+          {paper.note && <p className={styles.intentPaperNote}>注：{paper.note}</p>}
+        </li>)}
+      </ul>
+      <p className={styles.kbHint}>
+        另外两处术语来源不在论文里：<b>act / predicate</b> 的分法沿用本插件既有的意图契约（issue 0012），
+        <b>lineage</b> 是 DSH 自身的链路约定（session / turn / intent / task / subtask / run 六个 id）。
+      </p>
+    </Section>
+  </div>
+}