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

package/src/client/agent-preset.ts

@@ -0,0 +1,121 @@
+/**
+ * 自定义 agent preset 的**纯数据与纯函数**（0029）。
+ *
+ * 与 `problem-domains.ts` 同一个理由：把「不依赖 React、可以在 node:test 里直接跑」
+ * 的那部分从 `.tsx` 里分出来。这里的两样东西都值得被测：preset 的 id 是一个会被
+ * 组合文件、安装脚本与界面同时引用的**冻结契约**；`readPersonaPrompt` 是一个真的
+ * 会读错的解析小函数。
+ *
+ * @module
+ */
+
+/** 我们这个 preset 的 id。与 `preset/<id>/`、安装脚本、组合文件里的引用一致。 */
+export const TITA_PRESET_ID = 'tita-data-agent'
+
+/**
+ * 承载「默认 preset」的那条 DSH **entry**（0.1.5 时叫设置命名空间）曾经在这里：
+ * `agent-preset-registry`。0.1.7 起控制台**不再读写它**。
+ *
+ * 原因是它是重复的：DSH 设置里本来就有同一项，写的是同一个字段。控制台再摆一个下拉，
+ * 用户就要回答「这两处哪个算数」—— 答案是都算数，但光看界面看不出来。所以这一项归
+ * DSH 设置，`AgentPresetCard` 只在我们的 preset 不是默认时把这件事说出来。
+ */
+
+/** 三个只在自定义 preset 里挂载的意图工具。子代理的 `toolFilter.deny` 也引用它们。 */
+export const INTENT_TOOL_NAMES = ['intent_record', 'intent_store_view', 'intent_registry_list'] as const
+
+/**
+ * `agentPresets/list` 的一行。结构来自 `dsh-agent-preset-registry` 的 client-safe 类型。
+ *
+ * 没有 `trust`：0.1.5 的 roster 会区分随包 / 本地，0.1.7 的 `remoteExportList` 只回
+ * `id` / `name` / `description` / `order` / `broken` 与 `isDefault`。声明一个宿主不回的
+ * 字段，只会让界面拿一个永远 undefined 的值去分支 —— 那种分支看起来像功能，实际是死代码。
+ */
+export interface PresetRow {
+  id: string
+  isDefault: boolean
+  name?: string
+  description?: string
+  broken?: string
+}
+
+/** Remote 调用的返回。失败那一支带一句给用户看的话，不带就退回默认文案。 */
+export type RemoteResult<T> = { ok: true; value: T } | { ok: false; message?: string }
+
+/**
+ * 客户端 Remote 命名空间的结构化视图。
+ *
+ * 与目录选择同理：`@deepseek-ai/dsh-agent-preset-registry` 是 DSH 安装里的包，不是可依赖的
+ * npm 版本，所以这里只声明真正用到的成员。取不到就是没有 —— 退化成「宿主没提供
+ * preset 名单」这一条如实回答，而不是崩掉。
+ *
+ * 0.1.7 起**没有** `settings.openAgentPresetDirectory`：DSH 那边的 preset 不再是一个
+ * 目录，而是组合里的一条声明行（见 docs/0036）。所以「打开 preset 目录」不走 settings
+ * 命名空间，而是走 `session.openWorkspacePath` —— 那是 DSH 里唯一一个「把宿主上的一个
+ * 路径交给系统文件管理器」的入口（文件预览的「在访达中显示」用的也是它）。它打开的是
+ * **本插件随包分发的 preset 真源目录**（`preset/tita-data-agent/`），因为提示词的唯一
+ * 真源是那里面的 `agent.cordis.yml`。
+ */
+export interface AgentPresetRemote {
+  agentPresets?: {
+    list(): Promise<RemoteResult<{ presets: PresetRow[] }>>
+    read(id: string): Promise<RemoteResult<{ content: string; name?: string; description?: string }>>
+  }
+  /**
+   * `dsh-api-session-controller` 的 `session` 命名空间，这里只声明路径打开那一个方法。
+   *
+   * 宿主会先验证这个路径确实映射到它自己的文件系统上（`verifyDesktopPath`），验证不过
+   * 就拒 —— 所以调用方必须把失败当成一种正常结果（如实说「打不开」并给出路径），
+   * 而不是当成崩了。
+   */
+  session?: {
+    openWorkspacePath(
+      request: { path: string; action?: 'reveal' | 'open' },
+      signal?: AbortSignal,
+    ): Promise<RemoteResult<{ opened: boolean }>>
+  }
+}
+
+/**
+ * 从组合正文里抽出 `persona` 行的 `prefix`。
+ *
+ * **这是预览用的读取，不是一个 YAML 解析器。** 它只认 `persona` 行里那一个
+ * `prefix:` 标量，三种写法都支持：
+ *
+ * - `prefix: 一行文字`
+ * - `prefix: |` 块标量（保留换行 —— 提示词正文用的就是这种）
+ * - `prefix: >-` 折叠标量（换行折成空格）
+ *
+ * 只读这一段是因为界面上要显示的就是它；真正的解析与校验由 DSH 挂载 preset 时做，
+ * 而如果组合坏了，`agentPresets/list` 会把 `broken` 一起报回来，界面照实显示。
+ *
+ * 返回 `null` 表示「这个 preset 里没有 persona 提示词」—— 那本身是一个有意义的
+ * 结论（它用的是部署级默认人格），不是失败。
+ */
+export function readPersonaPrompt(content: string): string | null {
+  const lines = content.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^\s*-\s+id:\s*persona\s*$/.test(lines[i]!)) continue
+    for (let j = i + 1; j < lines.length; j++) {
+      const line = lines[j]!
+      // 下一个顶层行 = persona 这一行结束了。
+      if (/^\s*-\s+id:/.test(line)) break
+      const match = /^(\s*)prefix:\s*((?:\||>)[-+]?)?\s*(.*)$/.exec(line)
+      if (!match) continue
+      const indent = match[1]!.length
+      // 单行标量：值就在这一行上。
+      if (!match[2]) return match[3]!.trim() || null
+      // 块标量：内容在下面，缩进比 `prefix:` 深，遇到不更深的行就结束。
+      const body: string[] = []
+      for (let k = j + 1; k < lines.length; k++) {
+        const inner = lines[k]!
+        // 空行属于块内（它就是要保留的段落间隔），不能当成结束。
+        if (inner.trim() === '') { body.push(''); continue }
+        if (inner.search(/\S/) <= indent) break
+        body.push(inner.slice(Math.min(inner.length, indent + 2)))
+      }
+      return body.join('\n').trim() || null
+    }
+  }
+  return null
+}

package/src/client/arch/AgentArchitectureGraph.tsx

@@ -0,0 +1,219 @@
+/**
+ * Agent 架构图 —— 一张 AntV G6 画布画出整个方案。
+ *
+ * 六条纪律：
+ * 1. **画布只画，不算。** 坐标、配色、卡片 DOM 全在 `./model.ts` 里算好，这个组件
+ *    负责挂载、交互、全屏。所以「重排在 Runtime 下方」「跨链路只有四条」这些结论
+ *    可以在 node:test 里断言，不需要启浏览器。
+ * 2. **点击只改选中态，不重建画布。** 缩放和平移是用户的空间记忆，点一下节点就把视图
+ *    重置回 fitView 会把它清掉。选中反馈走 `updateNodeData`（只换那一张卡的 DOM）。
+ * 3. **窄栏默认「适应宽度」，1:1 是一个可选档。**
+ *    这张画布设计宽度 1172px，宿主右侧栏只有 380–840px。只给一个 1:1 档的话，
+ *    用户第一眼只能看到 5 列里的 2 列半 —— 「整个链路在一张图里」就只是一句话。
+ *    所以默认整图缩到栏宽（看得全），需要读字时切到 1:1（看得清）。
+ *    缩放**不用 G6 的 `fitView` / `zoomTo`**：这版 G6 对 HTML 节点算不出内容包围盒，
+ *    两个 API 都实测无效（画布按 0.45 定了尺寸，内容仍按 1:1 画出去被裁掉）。
+ *    改成画布永远按设计尺寸渲染、再缩整块板：比例是我们算的，不依赖 G6 的判断。
+ * 4. **画布不接管视口。** 不注册 `drag-canvas` / `zoom-canvas`：滚轮该滚容器，
+ *    而不是缩画布；平移交给滚动条。G6 在这一页只负责画和点选。
+ * 5. **操作是浮层，画布上没有图例。**
+ *    0026 把图例、提示、状态统计和全屏按钮放在画布上方的一条 flex 行里，栏宽一窄
+ *    `flex-wrap` 就把全屏按钮甩到第二行最左边 —— 用户看到的「全屏不在右上角」就是这么来的。
+ *    0029 又把左上角那两行图例（边语义 + 全图状态分布）也撤了：读法已经写在带名、
+ *    卡片状态字和浮层正文里，再在画布上压一块半透明说明板，只是把图挡掉一角。
+ *    现在浮层只剩右上角的操作（缩放档 + 全屏）。
+ * 6. **细节也在画布内。** 节点详情是画布自己的浮层（`inspector` 插槽），不是旁边另一列：
+ *    0027 之前它是一块 320px 的侧栏，图因此被挤窄（实测缩放只有 0.42，字缩到读不出），
+ *    而且「图」与「这张图上的东西」分居两块表面。浮层不参与缩放，所以它始终是
+ *    可读的正文尺寸；关掉它，画布就恢复成完整的一张图。
+ */
+
+import { Graph } from '@antv/g6'
+import { useCallback, useEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react'
+import { Maximize2, Minimize2 } from '@tita-data-agent/ui/icons'
+import { Button, cn } from '@tita-data-agent/ui/components'
+import { NODE_META, NODE_STATUS_LABEL, nodeMetrics, type KnowledgeStats, type NodeId } from '../architecture.tsx'
+import {
+  CANVAS_HEIGHT, CANVAS_WIDTH, cardHtml, isDecoration, isProblemPlate, problemIdOf, problemPlateHtml,
+  toGraphData,
+} from './model.ts'
+import { PROBLEM_DOMAINS } from '../problem-domains.ts'
+import { useFitScale, type ZoomMode } from '../useFitScale.ts'
+import { styles } from '../styles.ts'
+// 架构视图自己的版式（图 + 浮层）跟着这个组件走，不并进插件通用 styles.css。
+import '../architecture.css'
+
+export interface AgentArchitectureGraphProps {
+  stats: KnowledgeStats
+  version: number
+  selected: NodeId | null
+  onSelect: (id: NodeId | null) => void
+  /** 选中的问题域（画布最下面那条带里的牌子）。与节点选中互斥，由调用方保证。 */
+  selectedDomain: string | null
+  onSelectDomain: (id: string | null) => void
+  /** 面板不可见时不建图：隐藏容器尺寸为 0，G6 拿到 0 会画出一块空白。 */
+  visible: boolean
+  /**
+   * 画布内的详情浮层。**它在画布自己的框里**，不是旁边另一列：选中节点或问题域时
+   * 出现，关掉就消失。它是画布内唯一不随缩放变小的东西，所以长文本放它这里。
+   */
+  inspector?: ReactNode
+}
+
+export function AgentArchitectureGraph({ stats, version, selected, onSelect, selectedDomain, onSelectDomain, visible, inspector }: AgentArchitectureGraphProps): ReactNode {
+  const host = useRef<HTMLDivElement>(null)
+  const scroller = useRef<HTMLDivElement>(null)
+  const stage = useRef<HTMLElement>(null)
+  const graphRef = useRef<Graph | null>(null)
+  const selectRef = useRef(onSelect)
+  selectRef.current = onSelect
+  const selectDomainRef = useRef(onSelectDomain)
+  selectDomainRef.current = onSelectDomain
+  const [fullscreen, setFullscreen] = useState(false)
+  const [mode, setMode] = useState<ZoomMode>('fit')
+  const { scale, boardH } = useFitScale(scroller, CANVAS_WIDTH, CANVAS_HEIGHT, visible, fullscreen, mode)
+  /** 选中态要在「建图 / 换数据 / 换选中」三条路径上都对得上，所以集中存一份。 */
+  const stateRef = useRef({ selected, selectedDomain, stats, version })
+  stateRef.current = { selected, selectedDomain, stats, version }
+  /** 上一次选中的对象：取消高亮要精确到「哪一个」，不能整块重画。 */
+  const lastSelected = useRef<NodeId | null>(null)
+  const lastDomain = useRef<string | null>(null)
+
+  // ---------------------------------------------------------------- 建图
+  // 只依赖 `visible`：画布尺寸永远是设计尺寸（CANVAS_WIDTH × CANVAS_HEIGHT），
+  // 缩放由外层那块板的 transform 承担，所以换档、换全屏都不必重建图。
+  useEffect(() => {
+    const el = host.current
+    if (!el || !visible) return undefined
+    const graph = new Graph({
+      container: el,
+      width: el.clientWidth || CANVAS_WIDTH,
+      height: el.clientHeight || CANVAS_HEIGHT,
+      // 画布底色交给容器（`.tita-archScroll` 的 `--tita-surface`）：canvas 不认 CSS 变量，
+      // 它会先 clearRect（清成全透明）再把 background 当 fillStyle 填 —— 传令牌字符串等于
+      // 交给浏览器一个无效值，填色被忽略，默认的黑色 fillStyle 会直接盖上来。透明才是
+      //「跟着主题走」在画布上的唯一正确写法，浅色下与原来的纯白一致。
+      background: 'transparent',
+      // 画布不承担缩放平移：视口交给外层滚动条与缩放档，G6 只管画。
+      // 图级 `node.type` / `edge.type` **不要设**：G6 v5 用它覆盖每个元素自己声明的
+      // `type`，于是装饰节点会被当成 HTML 节点画成空盒子，整张图只剩悬空的卡片
+      // （0025 起就是这样，实测确认）。类型一律由元素自己声明。
+    })
+    graphRef.current = graph
+    graph.on('node:click', event => {
+      const id = (event as { target?: { id?: string } }).target?.id
+      // 带名条是装饰节点：点它等于点空白。
+      if (!id || isDecoration(id)) return
+      // 问题域牌子不是架构节点，它点开的是这个域的完整论述。
+      if (isProblemPlate(id)) selectDomainRef.current(problemIdOf(id))
+      else selectRef.current(id as NodeId)
+    })
+    graph.on('canvas:click', () => { selectRef.current(null); selectDomainRef.current(null) })
+    return () => {
+      graph.destroy()
+      graphRef.current = null
+    }
+  }, [visible])
+
+  // ---------------------------------------------------------------- 喂数据
+  useEffect(() => {
+    const graph = graphRef.current
+    if (!graph || !visible) return
+    const { selected: node, selectedDomain: domain } = stateRef.current
+    graph.setData(toGraphData(stats, version, node, domain))
+    void graph.render()
+  }, [visible, stats, version])
+
+  // ---------------------------------------------------------------- 选中态
+  useEffect(() => {
+    const graph = graphRef.current
+    if (!graph || !visible) return
+    const { stats: currentStats, version: currentVersion } = stateRef.current
+    const previousNode = lastSelected.current
+    const previousDomain = lastDomain.current
+    lastSelected.current = selected
+    lastDomain.current = selectedDomain
+    const patch: Array<{ id: string; style: Record<string, unknown> }> = []
+    if (previousNode && previousNode !== selected) {
+      patch.push({ id: previousNode, style: { innerHTML: cardHtml(previousNode, nodeMetrics(previousNode, currentStats, currentVersion), false) } })
+    }
+    if (selected) {
+      patch.push({ id: selected, style: { innerHTML: cardHtml(selected, nodeMetrics(selected, currentStats, currentVersion), true) } })
+    }
+    // 问题域牌子与节点卡片是两种 DOM，但选中反馈是同一条规则：换 innerHTML。
+    const plate = (domainId: string, on: boolean): { id: string; style: Record<string, unknown> } | null => {
+      const domain = PROBLEM_DOMAINS.find(item => item.id === domainId)
+      if (!domain) return null
+      return { id: `domain:${domain.id}`, style: { innerHTML: problemPlateHtml(domain, currentStats, currentVersion, on) } }
+    }
+    if (previousDomain && previousDomain !== selectedDomain) {
+      const off = plate(previousDomain, false)
+      if (off) patch.push(off)
+    }
+    if (selectedDomain) {
+      const on = plate(selectedDomain, true)
+      if (on) patch.push(on)
+    }
+    if (patch.length === 0) return
+    graph.updateNodeData(patch)
+    void graph.draw()
+  }, [selected, selectedDomain, visible])
+
+  // ---------------------------------------------------------------- 全屏
+  const toggleFullscreen = useCallback((): void => {
+    const el = stage.current
+    if (!el) return
+    if (document.fullscreenElement === el) void document.exitFullscreen()
+    else void el.requestFullscreen()
+  }, [])
+
+  useEffect(() => {
+    const onChange = (): void => setFullscreen(document.fullscreenElement === stage.current)
+    document.addEventListener('fullscreenchange', onChange)
+    return () => document.removeEventListener('fullscreenchange', onChange)
+  }, [])
+
+  // 画布永远是设计尺寸，缩放由这块板承担。`fit` 档下板高就是缩完的高度，
+  // 容器因此没有可滚的余量；`1:1` 档下板高是设计高度，横向（窄栏）或双向（全屏）滚动。
+  const scrollStyle = fullscreen ? undefined : { height: boardH }
+  const boardStyle = {
+    width: CANVAS_WIDTH,
+    height: CANVAS_HEIGHT,
+    transform: `scale(${scale})`,
+    transformOrigin: 'top left',
+  }
+
+  return <section className={styles.archStage} ref={stage} aria-label="Tita Data Agent 整体架构">
+    <div className={styles.archPane}>
+      {/* 浮层只剩操作，固定在右上角。画布上不再压图例板：读法在带名、卡片状态字与
+          浮层正文里，左上角那块说明板只是把图挡掉一角。 */}
+      <div className={styles.archOverlay}>
+        <div className={styles.archOverlayActions}>
+          {/* 缩放档：两段的分段控件。两段都在，是因为一个来回翻转的按钮说不清「现在是哪一档」。 */}
+          <div className={styles.archZoom} role="group" aria-label="缩放">
+            <button type="button" className={cn(styles.archZoomOption, mode === 'fit' && styles.archZoomOn)}
+              aria-pressed={mode === 'fit'} onClick={() => setMode('fit')} title="整图缩到栏宽，一眼看全三条链路">适应</button>
+            <button type="button" className={cn(styles.archZoomOption, mode === 'actual' && styles.archZoomOn)}
+              aria-pressed={mode === 'actual'} onClick={() => setMode('actual')} title="按设计尺寸 1:1 显示，横向滚动查看">1:1</button>
+          </div>
+          <Button variant="outline" size="sm" onClick={toggleFullscreen} aria-pressed={fullscreen}>
+            {fullscreen ? <Minimize2 size={14} /> : <Maximize2 size={14} />}{fullscreen ? '退出全屏' : '全屏'}
+          </Button>
+        </div>
+      </div>
+      <div className={styles.archScroll} style={scrollStyle} ref={scroller}>
+        <div className={styles.archBoard} style={boardStyle}>
+          <div className={styles.archCanvas} ref={host} />
+        </div>
+      </div>
+      {/* 详情浮层：画布内，不缩放，可关闭。关掉之后画布恢复成完整的一张图。 */}
+      {inspector && <div className={styles.archInspector} style={{ '--arch-board-h': `${boardH}px` } as CSSProperties}>{inspector}</div>}
+    </div>
+    {/* 图上每个节点的状态说明：卡片只有 10px 的状态文字，完整依据挂在这里，视觉与无障碍同源。 */}
+    <ul className={styles.srOnly} aria-label="架构节点状态">
+      {(Object.keys(NODE_META) as NodeId[]).map(id => <li key={id}>
+        {NODE_META[id].title}：{NODE_STATUS_LABEL[NODE_META[id].status]} —— {NODE_META[id].statusNote}
+      </li>)}
+    </ul>
+  </section>
+}

package/src/client/arch/NodeLogicPanel.tsx

@@ -0,0 +1,133 @@
+/**
+ * 架构图内的节点面板：**核心逻辑 + 数据统计 + 状态记录 + 跳转**。
+ *
+ * 0027 之前它住在画布右边的一个侧栏里（`.tita-archRail`），而侧栏是画布**外面**的
+ * 一列：图被挤窄、面板和图各占一块表面，读起来是两件事。现在它是画布内的浮层，
+ * 由 `AgentArchitectureGraph` 的 `inspector` 插槽承载，壳（边框、圆角、投影）由浮层给。
+ *
+ * 这里**没有设置项**，一个都没有。设置已经回到它们真正生效的地方（意图 Tab、
+ * 知识库的各个分栏），面板只回答三个问题：这个节点是干什么的、它现在的数字是多少、
+ * 它实现到哪一步，以及「要改它就去哪」。
+ *
+ * 空态已经撤掉：画布上不再有「未选中」这一态 —— 没选中时浮层根本不出现，
+ * 而原来空态里那份「整体是什么」的内容（全图状态分布、逐带明细）已经搬到画布上的
+ * 问题域带名条里，那里本来就是「这一页整体是什么」的落点。
+ */
+
+import type { ReactNode } from 'react'
+import {
+  ArrowRight, Check, ChevronRight, CircleDot, CircleHelp, X,
+} from '@tita-data-agent/ui/icons'
+import { Badge, Button, cn } from '@tita-data-agent/ui/components'
+import {
+  NODE_META, NODE_STATUS_LABEL, jumpTargetOf, laneOf, nodeMetrics,
+  type KnowledgeStats, type KnowledgeTab, type NodeId, type NodeStatus, type PanelTab,
+} from '../architecture.tsx'
+import { LANE_PALETTE, recordRows } from './model.ts'
+import { styles } from '../styles.ts'
+
+const STATUS_BADGE: Record<NodeStatus, 'success' | 'warning' | 'neutral' | 'blue'> = {
+  live: 'success', partial: 'warning', planned: 'neutral', host: 'blue',
+}
+
+const STEP_ICON = { done: Check, partial: CircleDot, todo: CircleHelp } as const
+
+export interface NodeLogicPanelProps {
+  selected: NodeId
+  stats: KnowledgeStats
+  version: number
+  /** 跳到节点所属的功能 tab；`knowledgeTab` 存在时还要落到知识库里那一栏。 */
+  onJump: (tab: PanelTab, knowledgeTab?: KnowledgeTab) => void
+  onOpenTab?: (kind: 'data-sheet' | 'data-notebook') => void
+  onClose: () => void
+}
+
+/**
+ * 浮层里的一段。节点面板与问题域面板共用它 —— 两种内容、一种骨架，
+ * 换选中对象时版面不会跳。
+ */
+export function PanelSection({ title, extra, children }: { title: string; extra?: ReactNode; children: ReactNode }): ReactNode {
+  return <section className={styles.archPanelSection}>
+    <header className={styles.archPanelSectionHead}>
+      <h4>{title}</h4>
+      {extra}
+    </header>
+    {children}
+  </section>
+}
+
+export function NodeLogicPanel({ selected, stats, version, onJump, onOpenTab, onClose }: NodeLogicPanelProps): ReactNode {
+  const meta = NODE_META[selected]
+  const Icon = meta.icon
+  const lane = laneOf(selected)
+  const laneColor = LANE_PALETTE[meta.lane].accent
+  const metrics = nodeMetrics(selected, stats, version)
+  const records = recordRows(selected, stats, version)
+  const jump = jumpTargetOf(selected)
+
+  return <aside className={styles.archPanel} aria-label={`${meta.title} 节点详情`}>
+    <header className={styles.archPanelHead}>
+      <span className={styles.archPanelIcon}><Icon size={16} strokeWidth={1.85} /></span>
+      <div className={styles.archPanelHeadCopy}>
+        <div className={styles.archPanelTitleRow}>
+          <h3>{meta.title}</h3>
+          <Badge tone={STATUS_BADGE[meta.status]}>{NODE_STATUS_LABEL[meta.status]}</Badge>
+        </div>
+        <p>{meta.subtitle}</p>
+        {lane && <span className={styles.archPanelLane}>
+          <i style={{ background: laneColor }} aria-hidden="true" />{lane.index} · {lane.title}
+        </span>}
+      </div>
+      <Button variant="ghost" size="icon" aria-label="关闭节点详情" title="关闭" onClick={onClose}><X size={14} /></Button>
+    </header>
+
+    <div className={styles.archPanelBody}>
+      <PanelSection title="核心逻辑">
+        <p className={styles.archPanelText}>{meta.detail}</p>
+        <div className={styles.archPanelFlow}>
+          <span><small>输入</small>{meta.input}</span>
+          <ArrowRight size={13} aria-hidden="true" />
+          <span><small>输出</small>{meta.output}</span>
+        </div>
+        <ol className={styles.archPanelSteps}>
+          {meta.steps.map(step => {
+            const StepIcon = STEP_ICON[step.state ?? 'done']
+            return <li key={step.label} className={cn(styles.archPanelStep, step.state === 'todo' && styles.archPanelStepTodo)}>
+              <StepIcon size={13} strokeWidth={2} aria-hidden="true" />
+              <span><b>{step.label}</b><small>{step.detail}</small></span>
+            </li>
+          })}
+        </ol>
+      </PanelSection>
+
+      <PanelSection title="数据统计" extra={<span className={styles.archPanelEyebrow}>{metrics.length} 项</span>}>
+        {metrics.length === 0
+          ? <p className={styles.archPanelHint}><CircleHelp size={13} />这个节点没有本地计数：它不是本插件的产物，或者还没有可统计的落盘数据。</p>
+          : <div className={styles.archPanelMetrics}>
+            {metrics.map(metric => <span key={metric.label} className={styles.archPanelMetric}>
+              <small>{metric.label}</small><b>{metric.value}</b>
+            </span>)}
+          </div>}
+      </PanelSection>
+
+      <PanelSection title="状态记录">
+        <p className={styles.archPanelNote}>{meta.statusNote}</p>
+        <dl className={styles.archPanelRecords}>
+          {records.map(([label, value]) => <div key={label}><dt>{label}</dt><dd>{value}</dd></div>)}
+        </dl>
+      </PanelSection>
+
+      <PanelSection title="跳转" extra={<span className={styles.archPanelEyebrow}>{jump ? '可跳转' : '无独立页面'}</span>}>
+        {jump
+          ? <Button variant="default" size="sm" onClick={() => onJump(jump.tab, jump.knowledgeTab)}>
+            去配置<ArrowRight size={14} />
+          </Button>
+          : <p className={styles.archPanelHint}><CircleHelp size={13} />这个节点没有可配置页：{meta.status === 'host' ? '它由宿主提供' : meta.status === 'planned' ? '它还没实现，先在这里说明设计意图' : '它的行为由代码决定，没有可调参数'}。</p>}
+        {(selected === 'answer' || selected === 'data-sheet' || selected === 'data-notebook') && onOpenTab && <div className={styles.archPanelActions}>
+          <Button variant="outline" size="sm" onClick={() => onOpenTab('data-sheet')}><ChevronRight size={13} />打开 Table</Button>
+          <Button variant="outline" size="sm" onClick={() => onOpenTab('data-notebook')}><ChevronRight size={13} />打开 Notebook</Button>
+        </div>}
+      </PanelSection>
+    </div>
+  </aside>
+}

package/src/client/arch/ProblemDetailPanel.tsx

@@ -0,0 +1,88 @@
+/**
+ * 画布内浮层里的**问题域详情**。
+ *
+ * 问题域的牌子画在画布最下面一条带里，只放得下一眼能读完的东西（这一带是什么、
+ * 走到哪一步、衡量口径）。业界对照那一段是整段引述，在「适应」档缩到 0.7 之后
+ * 根本读不了，所以它落在浮层里 —— 那里是画布内唯一不随缩放变小的 HTML。
+ *
+ * 骨架与节点面板共用 `PanelSection`：两种内容、一种形状，换选中对象时版面不跳。
+ */
+
+import type { ReactNode } from 'react'
+import { ChevronRight, Compass, X } from '@tita-data-agent/ui/icons'
+import { Badge, Button } from '@tita-data-agent/ui/components'
+import { PanelSection } from './NodeLogicPanel.tsx'
+import { PROBLEM_BASE_NOTE, problemDomainOf } from '../problem-domains.ts'
+import type { KnowledgeStats, NodeId } from '../architecture.tsx'
+import { styles } from '../styles.ts'
+
+export interface ProblemDetailPanelProps {
+  domainId: string
+  stats: KnowledgeStats
+  version: number
+  onSelect: (id: NodeId) => void
+  onClose: () => void
+}
+
+export function ProblemDetailPanel({ domainId, stats, version, onSelect, onClose }: ProblemDetailPanelProps): ReactNode {
+  const domain = problemDomainOf(domainId)
+  // 找不到就不画：宁可浮层不出现，也不要显示一个 id 对不上的空壳。
+  if (!domain) return null
+  const Icon = domain.icon
+  const progress = domain.progress?.(stats, version) ?? []
+
+  return <aside className={styles.archPanel} aria-label={`${domain.title} 问题域详情`}>
+    <header className={styles.archPanelHead}>
+      <span className={styles.archPanelIcon}><Icon size={16} strokeWidth={1.85} /></span>
+      <div className={styles.archPanelHeadCopy}>
+        <div className={styles.archPanelTitleRow}>
+          <h3>{domain.title}</h3>
+          <Badge tone={domain.status.tone}>{domain.status.label}</Badge>
+        </div>
+        <p>{domain.question}</p>
+        <span className={styles.archPanelLane}>
+          <Compass size={11} aria-hidden="true" />问题域 {domain.index} · 画布最下面一条带
+        </span>
+      </div>
+      <Button variant="ghost" size="icon" aria-label="关闭问题域详情" title="关闭" onClick={onClose}><X size={14} /></Button>
+    </header>
+
+    <div className={styles.archPanelBody}>
+      <PanelSection title="业界怎么做">
+        <p className={styles.archPanelText}>{domain.industry}</p>
+      </PanelSection>
+
+      <PanelSection title="落在哪些节点上" extra={<span className={styles.archPanelEyebrow}>{domain.actions.filter(action => action.node).length} 个可跳转</span>}>
+        <div className={styles.archPanelChips}>
+          {domain.actions.map(action => action.node
+            ? <button
+              key={action.label}
+              type="button"
+              className={styles.archPanelChip}
+              onClick={() => onSelect(action.node as NodeId)}
+              title={`打开「${action.label}」节点`}
+            >{action.label}<ChevronRight size={12} aria-hidden="true" /></button>
+            : <span key={action.label} className={styles.archPanelChipOff}>{action.label}<Badge tone="warning">未落地</Badge></span>)}
+        </div>
+      </PanelSection>
+
+      <PanelSection title="现在走到哪一步" extra={<span className={styles.archPanelEyebrow}>{progress.length > 0 ? `${progress.length} 项真实计数` : '没有可统计的落盘数据'}</span>}>
+        {progress.length === 0
+          ? <p className={styles.archPanelHint}><Compass size={13} />这个域还没有可统计的落盘产物，所以这里不给数字 —— 一个编出来的进度比没有进度更糟。</p>
+          : <div className={styles.archPanelMetrics}>
+            {progress.map(item => <span key={item.label} className={styles.archPanelMetric}>
+              <small>{item.label}</small><b>{item.value}</b>
+            </span>)}
+          </div>}
+      </PanelSection>
+
+      <PanelSection title="衡量方式">
+        <p className={styles.archPanelNote}>{domain.measure}</p>
+      </PanelSection>
+
+      <PanelSection title="底座">
+        <p className={styles.archPanelText}>{PROBLEM_BASE_NOTE}</p>
+      </PanelSection>
+    </div>
+  </aside>
+}