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

package/src/client/convert/ConvertPanel.tsx

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useMemo, useState, type ChangeEvent, type ReactNode } from 'react'
 import {
   AlertCircle, Check, Copy, Download, ExternalLink, FileText, FileUp, Inbox,
-  Package, RefreshCw, RotateCcw, ScanEye, X,
+  Link, Package, RefreshCw, RotateCcw, ScanEye, X,
 } from '@tita-data-agent/ui/icons'
 import type { LucideIcon } from '@tita-data-agent/ui/icons'
 import { Badge, Button, Input, Label, SelectMenu, Switch, Tabs, TabsContent, TabsList, TabsTrigger, cn } from '@tita-data-agent/ui/components'
@@ -121,6 +121,7 @@ const STATE_META: Record<TaskSummary['state'], { label: string; tone: 'neutral'
 const KIND_META: Record<string, { label: string; icon: LucideIcon }> = {
   file: { label: '文件', icon: FileText },
   text: { label: '文本', icon: FileUp },
+  url: { label: '链接', icon: Link },
 }
 
 function formatBytes(bytes: number | undefined): string {
@@ -148,7 +149,7 @@ export function ConvertPanel({ visible }: ConvertPanelProps): ReactNode {
   const [error, setError] = useState<string | null>(null)
   const [notice, setNotice] = useState<string | null>(null)
   const [busy, setBusy] = useState(false)
-  const [form, setForm] = useState({ kind: 'upload', path: '', text: '', title: '', sourceType: '', adapter: '' })
+  const [form, setForm] = useState({ kind: 'upload', path: '', url: '', text: '', title: '', sourceType: '', adapter: '' })
   const [uploadFile, setUploadFile] = useState<File | null>(null)
   const [ingestForm, setIngestForm] = useState({ sourceType: '', title: '', planOnly: false })
 
@@ -222,6 +223,13 @@ export function ConvertPanel({ visible }: ConvertPanelProps): ReactNode {
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ kind: 'file', local_path: form.path.trim(), ...common }),
         })
+      } else if (form.kind === 'url') {
+        if (!form.url.trim()) throw new Error('粘贴一条 http(s) 链接。')
+        payload = await requestJson(`${BASE}/api/tasks`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ kind: 'url', url: form.url.trim(), ...common }),
+        })
       } else {
         payload = await requestJson(`${BASE}/api/tasks`, {
           method: 'POST',
@@ -288,7 +296,7 @@ export function ConvertPanel({ visible }: ConvertPanelProps): ReactNode {
       `- 标题：${hints.title}`,
       `- 正文必须使用下面这些图片相对路径（相对 02_wiki/<entity_type>/ 解析）：`,
       ...hints.imageRefs.map(ref => `  - ${ref}`),
-      '调用 write_knowledge_card 时把图片引用原样写进 content。',
+      '调用 propose_wiki_cards 时把图片引用原样写进 content（正文只读，之后改不了，所以一次写对）。',
     ].join('\n')
   }, [ingest])
 
@@ -361,7 +369,12 @@ export function ConvertPanel({ visible }: ConvertPanelProps): ReactNode {
                         <Button variant="ghost" size="sm" title="详情" onClick={() => void openTask(task)}><ScanEye size={13} /></Button>
                         {task.state === 'running' || task.state === 'queued'
                           ? <Button variant="ghost" size="sm" title="取消" onClick={() => void act(task.id, 'cancel')}><X size={13} /></Button>
-                          : <Button variant="ghost" size="sm" title="重试" onClick={() => void act(task.id, 'retry')}><RotateCcw size={13} /></Button>}
+                          : task.state === 'failed' || task.state === 'cancelled'
+                            // 只有这两个状态还能重试。已交付的任务**输入在交付后就清理了**，
+                            // 给它一枚重试按钮，点了只会得到 TASK_ALREADY_DELIVERED，
+                            // 而修复之前那一次点击还会顺手删掉刚交付的产物。
+                            ? <Button variant="ghost" size="sm" title="重试" onClick={() => void act(task.id, 'retry')}><RotateCcw size={13} /></Button>
+                            : null}
                         {task.state === 'succeeded' && (
                           <a className="tita-uiButton" href={`${BASE}/api/tasks/${encodeURIComponent(task.id)}/files/index.md`} target="_blank" rel="noreferrer" title="打开 index.md">
                             <Download size={13} />
@@ -385,6 +398,7 @@ export function ConvertPanel({ visible }: ConvertPanelProps): ReactNode {
                 aria-label="输入类型"
                 options={[
                   { value: 'upload', label: '上传文件' },
+                  { value: 'url', label: '网页链接' },
                   { value: 'file', label: '文档（本机路径）' },
                   { value: 'text', label: '内联文本' },
                 ]}
@@ -424,6 +438,24 @@ export function ConvertPanel({ visible }: ConvertPanelProps): ReactNode {
               </label>
             )}
 
+            {form.kind === 'url' && (
+              <label className={styles.field}>
+                <span className={styles.fieldLabel}>网页链接</span>
+                <Input
+                  type="url"
+                  inputMode="url"
+                  spellCheck={false}
+                  value={form.url}
+                  placeholder="https://mp.weixin.qq.com/s?__biz=…"
+                  onChange={(event: ChangeEvent<HTMLInputElement>) => setForm({ ...form, url: event.target.value })}
+                />
+                <span className={styles.fieldHint}>
+                  微信公众号文章直接粘整条链接。只抓这一个地址（不跟进页面里的链接），正文里的图片会下载成本地
+                  assets/，远程地址不会留在产物里。正文由 JS 渲染的站点抓不到，会明确报错并给出替代做法。
+                </span>
+              </label>
+            )}
+
             <div className={styles.grid2}>
               <label className={styles.field}>
                 <span className={styles.fieldLabel}>标题（可选）</span>

package/src/client/doc-page.css

@@ -0,0 +1,134 @@
+/*
+ * 独立整页（SourceRaw 全文预览）的页面样式。
+ *
+ * 它是一份**单独的浏览器文档**：没有 DSH 外壳、没有侧栏的 380px 宽度限制，唯一的
+ * 目的是把一份很长的原文读下来。所以这里的排版决定都围绕阅读：固定一列约 72ch 的
+ * 字号宽度、行高 1.75、顶部一条常驻的窄条回答「我在读什么、读到哪儿了」。
+ *
+ * 颜色全部走共享令牌（`@tita-data-agent/ui/styles.css` 带进来的那一套），元素排版走
+ * `@tita-data-agent/ui/markdown.css`。这一页不引入任何 Tailwind 工具类：它要能在一个
+ * 没有 DSH 模块表的文档里自足，样式越少越不容易在别处漂移。
+ */
+
+:root { color-scheme: light; }
+
+html { -webkit-text-size-adjust: 100%; }
+
+body {
+  margin: 0;
+  background: var(--tita-canvas);
+  color: var(--tita-ink);
+  font-family: var(--tita-font);
+  font-size: 15px;
+  line-height: 1.75;
+}
+
+/* 常驻窄条：长文档滚到一半时，「这是哪一份、还有多少」必须还在视野里。 */
+.docPage-bar {
+  position: sticky;
+  top: 0;
+  z-index: 2;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 9px max(24px, calc(50vw - 380px));
+  border-bottom: 1px solid var(--tita-line);
+  background: color-mix(in srgb, var(--tita-surface) 92%, transparent);
+  backdrop-filter: blur(6px);
+}
+
+.docPage-bar h1 {
+  min-width: 0;
+  flex: 1 1 auto;
+  margin: 0;
+  overflow: hidden;
+  font-size: 14px;
+  font-weight: 680;
+  letter-spacing: -0.01em;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.docPage-barMeta { flex: 0 0 auto; color: var(--tita-ink-muted); font-size: 11.5px; }
+
+.docPage-main { padding: 26px 24px 96px; }
+
+/* 正文一列：65–75ch 是阅读行长的区间，中文按 15px 算约 40 个汉字换成 760px 上限。 */
+.docPage-column { max-width: 760px; margin: 0 auto; }
+
+.docPage-head { margin-bottom: 22px; }
+
+.docPage-head h2 {
+  margin: 0 0 6px;
+  font-size: 22px;
+  font-weight: 700;
+  letter-spacing: -0.02em;
+  line-height: 1.3;
+}
+
+.docPage-headMeta { margin: 0; color: var(--tita-ink-muted); font-size: 12.5px; }
+/* 路径与 id 是**逐字比对**的值：等宽，别和正文混成一个字体。 */
+.docPage-headMeta code {
+  font-family: var(--tita-mono);
+  font-size: 0.92em;
+}
+.docPage-headMeta code:last-child { word-break: break-all; }
+
+/* 分页读取：每一段自己是一个渲染单元（见 doc-page.tsx 的理由）。段与段之间靠
+   首个子元素的上外边距接上 —— `markdown.css` 把每段第一个子元素的上边距清零了
+   （那是给抽屉顶部用的），所以第二段起要把它还回来，否则接缝处会贴在一起。 */
+.docPage-segment + .docPage-segment .tita-markdownLocal > :first-child { margin-top: 1.2em; }
+
+.docPage-foot {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  margin-top: 34px;
+  padding-top: 18px;
+  border-top: 1px solid var(--tita-line);
+}
+
+.docPage-progress { color: var(--tita-ink-muted); font-size: 12px; font-variant-numeric: tabular-nums; }
+
+.docPage-more {
+  height: 32px;
+  padding: 0 16px;
+  border: 1px solid var(--tita-line-strong);
+  border-radius: 999px;
+  background: var(--tita-surface);
+  color: var(--tita-ink);
+  font: inherit;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.docPage-more:hover { border-color: var(--tita-primary); color: var(--tita-primary); }
+.docPage-more:disabled { opacity: 0.55; cursor: default; }
+.docPage-more:focus-visible { outline: 3px solid var(--tita-focus-ring); outline-offset: 1px; }
+
+/* 自动加载的哨兵：它没有内容，只是「滚到这里就取下一页」的位置标记。 */
+.docPage-sentinel { height: 1px; }
+
+.docPage-state {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 8px;
+  max-width: 760px;
+  margin: 0 auto;
+  color: var(--tita-ink-muted);
+  font-size: 14px;
+}
+
+.docPage-state h2 { margin: 0; color: var(--tita-ink); font-size: 17px; font-weight: 680; }
+.docPage-state p { margin: 0; line-height: 1.7; }
+.docPage-state code {
+  padding: 0.12em 0.36em;
+  border: 1px solid var(--tita-line);
+  border-radius: 4px;
+  background: var(--tita-surface-muted);
+  font-family: var(--tita-mono);
+  font-size: 0.88em;
+}

package/src/client/doc-page.tsx

@@ -0,0 +1,242 @@
+/**
+ * SourceRaw 的**独立整页**：在一个新标签里读一份原文的全文。
+ *
+ * 为什么需要它（而不是把抽屉加宽）：抽屉只有 380px，而原文可能是一份几十万字的转换
+ * 文档。抽屉因此只发前 `SOURCE_PREVIEW_CHARS`（4000）个字符 —— 那是预览，不是阅读。
+ * 要读全文就得有一个**为阅读建的**页面：整页宽度、常驻的标题条、一列 65–75ch 的行长。
+ *
+ * 三个决定：
+ *
+ * 1. **分页取，不一次取全文**。「打开要等半天」的成因就是把整份正文一次发过来；
+ *    这里一次只要 20000 字符，滚到底再取下一页（哨兵自动取，按钮是它的可见形态与
+ *    无障碍通路）。所以这份页面第一次可读的时间与文档大小**无关**。
+ * 2. **每页各自是一个渲染单元**，不把累计文本拼成一份再渲染。拼起来等于每翻一页
+ *    都把前面重渲染一遍（O(n²) 的渲染开销）；分开渲染让每页的成本只和这一页有关，
+ *    代价是分页接缝可能落在一个块中间 —— 服务端已经把切点对齐到空行。
+ * 3. **它没有 DSH 模块表**：一个普通浏览器文档，所以正文走共享的本地子集渲染器
+ *    （`@tita-data-agent/ui/markdown`），而不是面板里那个平台原子。这也是渲染器
+ *    必须有共享一份的原因。
+ *
+ * 入口地址：`/knowledge/documents/<docId>/view?kb=<知识库 id>`（外壳由宿主渲染，
+ * 见 `standaloneDocumentHtml()`）。
+ */
+
+import { StrictMode, useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { LocalMarkdown } from '@tita-data-agent/ui/markdown'
+import '@tita-data-agent/ui/styles.css'
+import '@tita-data-agent/ui/markdown.css'
+import './doc-page.css'
+import { formatBytes } from './format.ts'
+import { imageResolverOf, type AssetRef } from './asset-images.ts'
+
+/** 一次取多少字符。与抽屉的预览上限同量级：一页 ≈ 一次能读完的一屏多一点。 */
+const PAGE_CHARS = 20000
+
+interface DocumentMeta {
+  docId: string
+  title: string
+  sourceType: string
+  sourceTypeKnown?: boolean
+  sourceFormat: string
+  parser: string
+  bytes: number
+  contentChars: number
+  contentTruncated: boolean
+  relativePath: string
+  ext: string
+  updatedAt: string
+  assets: AssetRef[]
+}
+
+interface ContentPage {
+  text: string
+  offset: number
+  nextOffset: number
+  totalChars: number
+  eof: boolean
+}
+
+interface Envelope<T> { ok?: boolean; data?: T; error?: { message?: string; suggestion?: string } }
+
+async function requestJson<T>(url: string): Promise<T> {
+  const response = await fetch(url)
+  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) throw new Error(payload.error?.message ?? `请求失败（${response.status}）`)
+  if (payload.data === undefined) throw new Error('服务端没有返回内容')
+  return payload.data
+}
+
+/** 这个页面只服务一条地址形状；不匹配时如实说。 */
+function readTarget(): { docId: string; kb: string } | undefined {
+  const match = /^\/knowledge\/documents\/([^/]+)\/view$/.exec(window.location.pathname)
+  if (match === null) return undefined
+  let docId = match[1] as string
+  try { docId = decodeURIComponent(docId) } catch { /* 不是合法的转义就按原样用 */ }
+  return { docId, kb: new URLSearchParams(window.location.search).get('kb') ?? '' }
+}
+
+/*
+ * 图片解析搬去了 `asset-images.ts`（0047）。
+ *
+ * 独立整页与面板抽屉问的是同一个问题：「正文里这个相对引用对应哪张真图」。两处各写
+ * 一遍，结果就是整页能看图、抽屉看不到图 —— 而抽屉才是默认入口。现在只有一份实现，
+ * 这里只管把它的返回值喂给 `LocalMarkdown`。
+ */
+
+function App(): ReactNode {
+  const target = useMemo(readTarget, [])
+  const [phase, setPhase] = useState<'loading' | 'ready' | 'error'>('loading')
+  const [failure, setFailure] = useState<string>('')
+  const [meta, setMeta] = useState<DocumentMeta | null>(null)
+  const [segments, setSegments] = useState<string[]>([])
+  const [shown, setShown] = useState(0)
+  const [totalChars, setTotalChars] = useState(0)
+  const [eof, setEof] = useState(false)
+  const [busy, setBusy] = useState(false)
+  const [pageError, setPageError] = useState<string | null>(null)
+  const [reloadToken, setReloadToken] = useState(0)
+
+  /** 取到哪儿了 / 有没有在取 —— 观察器回调与按钮都可能触发，用 ref 挡住重复请求。 */
+  const offsetRef = useRef(0)
+  const busyRef = useRef(false)
+  const sentinelRef = useRef<HTMLDivElement | null>(null)
+
+  const loadPage = useCallback(async (from: number): Promise<void> => {
+    if (target === undefined || busyRef.current) return
+    busyRef.current = true
+    setBusy(true)
+    setPageError(null)
+    try {
+      const query = new URLSearchParams({ kb: target.kb, offset: String(from), limit: String(PAGE_CHARS) })
+      const page = await requestJson<ContentPage>(`/knowledge/documents/${encodeURIComponent(target.docId)}/content?${query.toString()}`)
+      if (page.text !== '') setSegments(previous => [...previous, page.text])
+      offsetRef.current = page.nextOffset
+      setShown(page.nextOffset)
+      setTotalChars(page.totalChars)
+      setEof(page.eof)
+    } catch (error) {
+      setPageError(error instanceof Error ? error.message : String(error))
+    } finally {
+      busyRef.current = false
+      setBusy(false)
+    }
+  }, [target])
+
+  /** 第一页：先把详情读来（标题、大小、资产），再取正文第一页。 */
+  useEffect(() => {
+    if (target === undefined) { setPhase('error'); return undefined }
+    let cancelled = false
+    offsetRef.current = 0
+    setPhase('loading'); setFailure('')
+    setSegments([]); setShown(0); setTotalChars(0); setEof(false); setPageError(null)
+    void (async () => {
+      try {
+        const query = new URLSearchParams(target.kb === '' ? {} : { kb: target.kb })
+        const payload = await requestJson<{ document: DocumentMeta }>(`/knowledge/documents/${encodeURIComponent(target.docId)}?${query.toString()}`)
+        if (cancelled) return
+        setMeta(payload.document)
+        setTotalChars(payload.document.contentChars)
+        // 浏览器标签页的标题：整页是拿来和别的东西并排看的，标签上得认得出是哪一份。
+        window.document.title = `${payload.document.title} · 原文`
+        setPhase('ready')
+        await loadPage(0)
+      } catch (error) {
+        if (cancelled) return
+        setFailure(error instanceof Error ? error.message : String(error))
+        setPhase('error')
+      }
+    })()
+    return () => { cancelled = true }
+  }, [target, loadPage, reloadToken])
+
+  /**
+   * 滚到底自动取下一页。
+   *
+   * `rootMargin` 提前 600px 触发，所以正常阅读不会看到「正在读」这一行 —— 按钮仍然
+   * 留在页脚，它是这条通路的**可见形态**：没有 JS 观察器的环境（或用户就是想手动翻）
+   * 也能读完，键盘用户 Tab 得到它。
+   */
+  useEffect(() => {
+    const node = sentinelRef.current
+    if (node === null || phase !== 'ready' || eof) return undefined
+    const observer = new IntersectionObserver(
+      entries => { if (entries.some(entry => entry.isIntersecting)) void loadPage(offsetRef.current) },
+      { rootMargin: '600px 0px' },
+    )
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [phase, eof, loadPage, segments.length])
+
+  const resolveImage = useMemo(() => imageResolverOf(meta?.assets ?? []), [meta])
+
+  if (target === undefined) {
+    return <main className="docPage-main"><div className="docPage-state">
+      <h2>这个地址不是一份文档的整页</h2>
+      <p>整页的地址形状是 <code>/knowledge/documents/&lt;docId&gt;/view?kb=&lt;知识库 id&gt;</code>。
+        它由知识库面板里「原文 → 内容 → 新页面打开」打开，不需要手写。</p>
+    </div></main>
+  }
+
+  if (phase === 'loading') {
+    return <main className="docPage-main"><p className="docPage-state" role="status">正在读取这份原文…</p></main>
+  }
+
+  if (phase === 'error' || meta === null) {
+    return <main className="docPage-main"><div className="docPage-state">
+      <h2>没能读到这份原文</h2>
+      <p>文档 id：<code>{target.docId}</code></p>
+      {failure !== '' && <p role="alert">{failure}</p>}
+      <button type="button" className="docPage-more" onClick={() => setReloadToken(token => token + 1)}>重试</button>
+    </div></main>
+  }
+
+  const metaLine = [
+    meta.sourceTypeKnown === false ? `${meta.sourceType}（未知分类）` : meta.sourceType,
+    meta.ext,
+    meta.sourceFormat || 'unknown',
+    formatBytes(meta.bytes),
+    `${meta.contentChars.toLocaleString()} 字符`,
+  ].join(' · ')
+
+  return <>
+    <header className="docPage-bar">
+      <h1 title={meta.title}>{meta.title}</h1>
+      <span className="docPage-barMeta">
+        {eof ? '已到末尾' : `已显示 ${shown.toLocaleString()} / ${totalChars.toLocaleString()} 字符`}
+      </span>
+    </header>
+    <main className="docPage-main">
+      <div className="docPage-column">
+        <div className="docPage-head">
+          <h2>{meta.title}</h2>
+          <p className="docPage-headMeta">{metaLine} · <code>{meta.relativePath}</code></p>
+        </div>
+
+        {segments.map((text, index) => <div className="docPage-segment" key={`segment-${index}`}>
+          <LocalMarkdown text={text} {...(resolveImage === undefined ? {} : { resolveImage })} />
+        </div>)}
+
+        <div className="docPage-foot">
+          <p className="docPage-progress" role="status">
+            {pageError !== null
+              ? `这一页没取到：${pageError}`
+              : eof
+                ? `已到文档末尾 · 共 ${totalChars.toLocaleString()} 字符`
+                : `已显示 ${shown.toLocaleString()} / ${totalChars.toLocaleString()} 字符`}
+          </p>
+          {!eof && <button type="button" className="docPage-more" disabled={busy} onClick={() => void loadPage(offsetRef.current)}>
+            {pageError !== null ? '重试这一页' : busy ? '正在读…' : '加载更多'}
+          </button>}
+          <div className="docPage-sentinel" ref={sentinelRef} aria-hidden="true" />
+        </div>
+      </div>
+    </main>
+  </>
+}
+
+const container = document.getElementById('tita-document-root')
+if (container !== null) createRoot(container).render(<StrictMode><App /></StrictMode>)

package/src/client/index.ts

@@ -8,6 +8,7 @@ import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
 import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import { createElement, useEffect, useState, type ReactNode } from 'react'
 import { KnowledgePanel } from './KnowledgePanel.tsx'
+import { KnowledgeToolRow, KNOWLEDGE_TOOL_KEYS } from './KnowledgeToolRow.tsx'
 import type { SettingsScopeLike } from './NodeSettings.tsx'
 import { groupScope } from './config-scope.ts'
 import { type AgentPresetRemote } from './AgentPresetCard.tsx'
@@ -95,4 +96,21 @@ export function apply(ctx: ClientContext): void {
   const injected: TabInjected = { ...settings, remote: (ctx as unknown as { remote?: AgentPresetRemote }).remote ?? {} }
   ctx.effect(() => ctx.sidebarRightTabs.register(definition()), 'tita knowledge: tab type')
   ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register({ name: 'sidebar.right.pane.tab', key: ID }, props => Tab(props, injected))), 'tita knowledge: tab body')
+  /**
+   * 知识工具在**对话流**里的卡片（0045）。
+   *
+   * 按**工具名**命中（`key: '<tool name>'`）：命中就替换平台那条通用行 ——
+   * 通用行只显示「工具名 + 一坨 JSON」，而人要看的是「导了几份、编出几张卡、
+   * 命中哪几条」。数据来自宿主侧的 `presentationMeta`（见 `src/present.ts`），
+   * 它随会话日志落盘，所以回放与当时一致。
+   *
+   * 五个工具名字来自 `KNOWLEDGE_TOOL_KEYS`：一处声明，注册与测试共用一份，
+   * 免得「加了工具忘了加卡片」只能靠翻代码发现。
+   */
+  for (const key of KNOWLEDGE_TOOL_KEYS) {
+    ctx.effect(
+      () => ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key }, props => createElement(KnowledgeToolRow, props))),
+      `tita knowledge: tool row ${key}`,
+    )
+  }
 }

package/src/client/panel-state.ts

@@ -0,0 +1,105 @@
+/**
+ * 「上次看到哪儿」：一级 tab、知识库分栏、选中的知识库。
+ *
+ * ## 为什么它们必须活在 React 之外
+ *
+ * DSH 会在若干动作之后重新挂载右侧面板 —— 刷新页面必然，换会话按宿主的保留策略也会，
+ * 而 `useState` 随手就没了。用户看到的是**每次切回来都跳回「Agent 概览」**
+ * （2026-09-26 GUI 反馈原话）。兄弟插件 `dsh-data-table` 的 `store.ts` 记着同一条结论，
+ * 它记的是上次打开的工作簿；这里记的是三个位置。
+ *
+ * ## 三条约定
+ *
+ * 1. **读出来的值必须校验。** 存的是上一版写下的字符串时（tab 改名、知识库被删、
+ *    手改过 localStorage），面板不能因此走进一个不存在的位置。所以带 `valid` 的那个读法
+ *    对着注册表核对，不认识就返回 `null`，由调用方用它自己的默认值 —— 校验放在调用方，
+ *    因为**注册表在那边**（`VIEW_ORDER` / `KNOWLEDGE_TABS`），这个模块不认识它们。
+ * 2. **存储是尽力而为。** 锁死 localStorage 的浏览器里退化成「这个页面生命周期内有效」：
+ *    每个值同时留一份内存副本，内存优先，全程不抛。
+ * 3. **key 只在这里拼。** 三处各写一次字符串，改名时就会漏掉一处，然后表现为
+ *    「有的记住了、有的没记住」。
+ *
+ * 这个模块**不 import 任何东西**（连 React 都不 import），所以它可以被单独打包进 node
+ * 里跑真实现 —— `tests/panel-state.test.mjs` 就是这么测的。
+ *
+ * @module
+ */
+
+/**
+ * 被记住的位置 → localStorage key。
+ *
+ * `dsh.` 前缀与兄弟插件一致（`dsh.data-sheet.lastWorkbookId`），便于在浏览器里
+ * 「哪些是本产品写的」一眼可辨；中间那段是插件名，避免不同插件撞 key。
+ */
+const KEYS = {
+  view: 'dsh.data-domain-knowledge.activeView',
+  knowledgeTab: 'dsh.data-domain-knowledge.knowledgeTab',
+  knowledgeBase: 'dsh.data-domain-knowledge.activeBase',
+} as const
+
+export type RememberedSlot = keyof typeof KEYS
+
+/** 内存副本：localStorage 不可用时的兜底，同时也避免每次读都碰存储。 */
+const cache = new Map<RememberedSlot, string>()
+
+function storage(): Storage | null {
+  try {
+    return globalThis.localStorage ?? null
+  } catch {
+    // 某些浏览器在「禁止所有 Cookie」时连读 `localStorage` 这个属性都会抛。
+    return null
+  }
+}
+
+function readRaw(slot: RememberedSlot): string | null {
+  const cached = cache.get(slot)
+  if (cached !== undefined) return cached === '' ? null : cached
+  let raw: string | null = null
+  try {
+    raw = storage()?.getItem(KEYS[slot]) ?? null
+  } catch {
+    raw = null
+  }
+  cache.set(slot, raw ?? '')
+  return raw === null || raw === '' ? null : raw
+}
+
+/**
+ * 读一个记住的值，并且**只认 `valid` 里的成员**。
+ *
+ * @param valid - 允许的取值，来自那个东西自己的注册表（tab 顺序表、分栏表）。传空数组
+ *   等于「什么都不要」—— 那时返回 `null`，调用方用默认值。
+ */
+export function readRemembered<T extends string>(slot: RememberedSlot, valid: readonly T[]): T | null {
+  const raw = readRaw(slot)
+  if (raw === null) return null
+  return (valid as readonly string[]).includes(raw) ? (raw as T) : null
+}
+
+/**
+ * 读一个**没有注册表可校验**的记住值（目前只有知识库 id —— 它来自服务端，是数据不是枚举）。
+ * 拿不到就返回空串，调用方按「没有偏好」处理。
+ */
+export function readRememberedId(slot: RememberedSlot): string {
+  return readRaw(slot) ?? ''
+}
+
+/** 记住一个值。写失败只影响「换个页面还记得不记得」，不影响本次会话。 */
+export function remember(slot: RememberedSlot, value: string): void {
+  if (cache.get(slot) === value) return
+  cache.set(slot, value)
+  try {
+    if (value === '') storage()?.removeItem(KEYS[slot])
+    else storage()?.setItem(KEYS[slot], value)
+  } catch {
+    // 写不进去就用内存那份；它已经更新过了。
+  }
+}
+
+/** 测试用：忘掉内存副本，让下一次读重新问存储。 */
+export function forgetRememberedCache(): void {
+  cache.clear()
+}
+
+/** 测试用：这个模块会写哪些 key。把它暴露出来，测试才能断言不撞别的插件。 */
+export const REMEMBERED_KEYS: Readonly<Record<RememberedSlot, string>> = KEYS

package/src/client/problem-domains.ts

@@ -80,7 +80,7 @@ export const PROBLEM_DOMAINS: ProblemDomain[] = [
     industry: 'ThoughtSpot SpotIQ 的 Change Analysis 做跨周期、跨维度对比并回答「变了什么、为什么变」，配合 anomaly alert 告警；SmartBI 用指标树 + 维度贡献度分解；经典算法为 Adtributor / HotSpot / iDice。',
     status: { label: '设计中', tone: 'warning' },
     actions: [
-      { label: '三路召回', node: 'recall' },
+      { label: '两路召回', node: 'recall' },
       { label: '上下文包', node: 'context' },
       { label: '排查图谱（0021）' },
     ],

package/src/client/request.ts

@@ -0,0 +1,36 @@
+/**
+ * 插件面板与宿主路由之间的**那一层薄封装**：把信封拆成「成功的数据」或一个能读的错误。
+ *
+ * 它存在的理由是**错误信息必须带 suggestion**：服务端返回的 `suggestion` 是「下一步该
+ * 做什么」（去哪个设置、先调哪个工具），丢掉它之后界面上只剩一句错误码，而用户没有
+ * 别的办法知道该往哪走。
+ *
+ * 它原来是 `KnowledgeBaseTab.tsx` 里的一个局部函数。抽出来是因为第二个消费者出现了
+ * （`ProposalReview.tsx` 的待办队列），而抄第二份的下场是两处的错误处理迟早不一致 ——
+ * 而「同一个失败在两屏上读起来不一样」正是最让人怀疑系统状态的那种不一致。
+ */
+
+export interface Envelope<T> {
+  ok?: boolean
+  data?: T
+  warnings?: string[]
+  error?: { code?: string; message?: string; suggestion?: string } | null
+}
+
+export async function requestJson<T>(url: string, init?: RequestInit): Promise<Envelope<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}）`)
+  }
+  const error = payload.error
+  if (!response.ok || payload.ok === false) {
+    const detail = [error?.code, error?.message].filter(Boolean).join(' · ') || `请求失败（${response.status}）`
+    throw new Error(error?.suggestion ? `${detail} — ${error.suggestion}` : detail)
+  }
+  return payload
+}