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

package/src/client/convert/ConvertPanel.tsx

@@ -361,7 +361,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} />

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,263 @@
+/**
+ * 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'
+
+/** 一次取多少字符。与抽屉的预览上限同量级：一页 ≈ 一次能读完的一屏多一点。 */
+const PAGE_CHARS = 20000
+
+interface AssetRef { rel: string; bytes: number; url: string }
+
+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') ?? '' }
+}
+
+/**
+ * 正文里的图片引用 → 能加载的 URL。
+ *
+ * 服务端在详情里已经把它认出来的每一张图放在 `assets` 里（`rel` 是相对知识库根，
+ * `url` 是 `/knowledge/assets/...`），但正文里写的是**相对这篇文档**的引用
+ * （`assets/pic-1.png`），两者不是同一个字符串。所以按三步认：整段相对路径相等、
+ * 以它为结尾、再退到文件名。都认不出来就交回 `null`，由渲染器显示 alt 文字 ——
+ * 显示一个坏图比显示「这张图没认出来」更糟。
+ */
+function imageResolverOf(assets: AssetRef[]): ((source: string) => string | null) | undefined {
+  if (assets.length === 0) return undefined
+  const byRel = new Map(assets.map(asset => [asset.rel, asset.url]))
+  const byName = new Map<string, string>()
+  for (const asset of assets) {
+    const name = asset.rel.split('/').pop() ?? ''
+    if (name !== '' && !byName.has(name)) byName.set(name, asset.url)
+  }
+  return (source: string): string | null => {
+    if (/^(?:https?:|data:)/i.test(source)) return source
+    const clean = source.replace(/^\.\//, '').replace(/^\/+/, '')
+    const exact = byRel.get(clean)
+    if (exact !== undefined) return exact
+    for (const [rel, url] of byRel) if (rel.endsWith(`/${clean}`)) return url
+    const name = clean.split('/').pop() ?? ''
+    return byName.get(name) ?? null
+  }
+}
+
+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/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/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
+}