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

package/src/client/arch/model.ts

@@ -0,0 +1,691 @@
+/**
+ * Agent 架构图的**几何与图形映射**（纯函数，可测）。
+ *
+ * 为什么不是「交给布局算法」：这是一张**架构图**，不是关系图。节点位置是设计结论 ——
+ * 三条链路各占一行、五列网格对齐、跨链路的流转与反馈各有固定走线。把坐标交给
+ * d3-force / dagre，同一份数据每次刷新会长成另一个形状，「重排在 Runtime 下方」
+ * 这种空间记忆就失效了。因此这里显式算出坐标，G6 只负责画和交互。
+ *
+ * 0027 的三条结论，都写在这份几何里：
+ *
+ * 1. **三条带是同一张图的三个区域，不是三块独立的板。** 旧版每条带是一块 14px 圆角、
+ *    带浅色填充、彼此隔开 40px 的「卡片」，于是图上读出的是三个并列的方框；现在带与带
+ *    之间只隔一条发丝线，带名从左侧留白搬进各自区域的左上角。图因此是**一张**连续画布。
+ * 2. **左侧留白改作跨链路走线通道。** 旧版那 196px 装的是链路名牌子，占着地方却只重复
+ *    了图例；现在链路名回到带内，留白让给 A↔B↔C 的连线 —— 那正是这张图最该说清、
+ *    旧版最没说清的一件事。
+ * 3. **跨链路关系只用一个强调色，而且永远带文字。** 带内流向是灰的，跨链路是蓝的；
+ *    颜色回答「这条线是不是跨链路」，文字回答「它跨的是什么」。四个跨链路关系
+ *    （A→C 交互回采、C→B 沉淀、C→A 反馈、B→A 注入）正好构成 A → C → B → A 的闭环，
+ *    而旧版缺的正是 A→C 那一段 —— 闭环因此看不出来。
+ */
+
+import {
+  NODE_LANES, NODE_META, NODE_STATUS_LABEL, NODE_STATUS_SHORT, NODE_STATUS_TONE, memoryCountOf, nodeMetrics, sourceCountOf,
+  type KnowledgeStats, type LaneId, type LaneMeta, type NodeId, type NodeMetric, type NodeStatus,
+} from '../architecture.tsx'
+import { PROBLEM_BASE_NOTE, PROBLEM_DOMAINS, type ProblemDomain } from '../problem-domains.ts'
+// 画布几何是从这份数据推出来的，所以这里把它转出去：测试与画布读的必须是同一份，
+// 否则「三条牌子」这句话在两个地方各有一个真相。
+export { PROBLEM_BASE_NOTE, PROBLEM_DOMAINS, problemDomainOf, type ProblemDomain } from '../problem-domains.ts'
+
+// ----------------------------------------------------------------- 画布常量
+
+/**
+ * 左侧留白：**跨链路走线的通道**，不是边距。带名已经搬进带内，所以这块宽度只由
+ * 「一条总线 + 转角」决定。带内的所有内容（含带名）都从这个 x 开始，通道因此从头到尾
+ * 没有东西挡着 —— 这是让 C→A 那条长反馈能贴着板边走干净的前提。
+ */
+export const GUTTER = 116
+export const NODE_W = 180
+/** 卡片高度要装下四层：标题行、两行说明、统计行。 */
+export const NODE_H = 96
+/** 堆叠节点（Table/Notebook、情节/操作记忆）用略矮的规格。 */
+export const NODE_H_STACKED = 80
+export const COL_GAP = 32
+/** 堆叠两个节点时，各自中心相对带中心线的偏移。80 + 2×47 = 174 = 内容区高度，
+ * 且 80 ≤ 2×47 —— 这是两张卡不重叠的条件，不是审美偏好。 */
+export const STACK_OFFSET = 47
+/** 带名条的高度：一枚字母徽标 + 链路名。 */
+export const LANE_HEAD_H = 30
+/**
+ * 带名条**只占自己内容的宽度**，不铺满整条带。
+ *
+ * 铺满的话它就是一块横贯全图的障碍物，垂直的跨链路走线只能绕到它的左边或右边 ——
+ * 实测「每日更新 → 编译」本来是一条直线，被逼成「上、左、上、右」四段绕行，
+ * 而且正好从带名文字上穿过去。缩成一块牌子之后，垂直走线从牌子右边自由通过。
+ */
+export const LANE_HEAD_W = 224
+/**
+ * 带与带之间的留白。它同时是横向跨链路走线的通道，所以不能太窄；
+ * 也不放任何分隔线 —— 分隔线要么是障碍物（挡住走线），要么只是一条装饰。
+ */
+export const BAND_GAP = 24
+export const LANE_PAD = 12
+/** 带的内容区高度：按最高的那种排布（两个堆叠节点）定，单节点在其中居中。 */
+export const CONTENT_H = NODE_H_STACKED + 2 * STACK_OFFSET
+/** 带高 = 带名条 + 上下内边距 + 内容区。三条带等高，网格才对得齐。 */
+export const BAND_H = LANE_HEAD_H + LANE_PAD + CONTENT_H + LANE_PAD
+/** 两条带的上沿间距 = 带高 + 通道。 */
+export const BAND_PITCH = BAND_H + BAND_GAP
+/** 画布顶部留白：图例与操作浮层浮在这条空白上，同时它也是 B→A 注入的走线通道。 */
+export const TOP = 100
+export const BOARD_RIGHT_PAD = 28
+export const COLUMNS = 5
+
+export const CANVAS_WIDTH = GUTTER + COLUMNS * NODE_W + (COLUMNS - 1) * COL_GAP + BOARD_RIGHT_PAD
+/** 底部留白同样是走线通道：跨链路反馈会从 C 带下面绕回来。 */
+export const BOTTOM = 40
+
+// ------------------------------------------------- 第四条带 · 解决的问题域
+//
+// 0027 把问题域从「画布外面的一张卡」搬进画布本身。理由是这一页的定位：它是用户
+// 对整个 Agent 的认知入口，而「它解决什么问题」和「它由哪些节点组成」是同一个问题的
+// 两面 —— 分成两块表面之后，用户要在两块之间来回看才能把机制和问题对上。
+//
+// 因此画布是**四条带**：A / B / C 三条链路，加上最下面一条问题域带。它不是第四条链路，
+// 所以不参与带间等距的推导（`laneTop` 只算链路），但它和链路带共用同一套网格与边距。
+
+/** 链路带与问题域带之间的走线通道。与 BAND_GAP 同宽：两条带之间的关系也是「隔一条通道」。 */
+export const PROBLEM_GAP = BAND_GAP
+/** 问题域带的带名条：与链路带名条同规格，读起来才是同一种东西。 */
+export const PROBLEM_HEAD_H = LANE_HEAD_H
+/**
+ * 问题域带名牌比链路名牌宽得多 —— 这是**刻意**的：它下面没有垂直走线要过，
+ * 而且它要一次说清两件事：这一带是什么，以及全图现在实现到哪一步。
+ */
+export const PROBLEM_HEAD_W = 640
+export const PROBLEM_PLATE_H = 182
+export const PROBLEM_PLATE_GAP = 24
+/** 带内边距：与链路带的 LANE_PAD 同值，四条带的内容因此对齐在同一条垂直线上。 */
+export const PROBLEM_PAD = LANE_PAD
+export const PROBLEM_BAND_H = PROBLEM_HEAD_H + PROBLEM_PAD + PROBLEM_PLATE_H + PROBLEM_PAD
+/** 问题域带的上沿：紧接最后一条链路带，隔一条走线通道。 */
+export const PROBLEM_TOP = laneTop(NODE_LANES.length - 1) + BAND_H + PROBLEM_GAP
+export const CANVAS_HEIGHT = PROBLEM_TOP + PROBLEM_BAND_H + BOTTOM
+
+/** 三条问题域牌子的宽度：把内容区三等分（除不尽的余数留在最右边，不摊进牌子）。 */
+export const PROBLEM_PLATE_W = Math.floor((CANVAS_WIDTH - GUTTER - BOARD_RIGHT_PAD - (PROBLEM_DOMAINS.length - 1) * PROBLEM_PLATE_GAP) / PROBLEM_DOMAINS.length)
+
+/** 第 `index` 条问题域牌子的格子。 */
+export function problemPlateBox(index: number): ArchBox {
+  return {
+    x: GUTTER + index * (PROBLEM_PLATE_W + PROBLEM_PLATE_GAP) + PROBLEM_PLATE_W / 2,
+    y: PROBLEM_TOP + PROBLEM_HEAD_H + PROBLEM_PAD + PROBLEM_PLATE_H / 2,
+    width: PROBLEM_PLATE_W,
+    height: PROBLEM_PLATE_H,
+  }
+}
+
+/** 第 `col` 列节点的中心 x（0 起）。 */
+export function columnX(col: number): number {
+  return GUTTER + col * (NODE_W + COL_GAP) + NODE_W / 2
+}
+
+/** 第 `index` 条带的上沿。带与带之间不加间隙：一条发丝线就是全部的分隔。 */
+export function laneTop(index: number): number {
+  return TOP + index * BAND_PITCH
+}
+/** 带内容区的纵向中心：节点（单行或堆叠）都以它为基准。 */
+export function laneCenter(index: number): number {
+  return laneTop(index) + LANE_HEAD_H + LANE_PAD + CONTENT_H / 2
+}
+
+export interface ArchBox { x: number; y: number; width: number; height: number }
+
+/**
+ * 每个节点的格子。`lane` 是带序号（0/1/2），`col` 是列号（0..4）。
+ *
+ * 知识链路从左往右（写入侧 → 读取侧），自进化链路**从右往左**：交互从回答那一侧
+ * 出来，经过记忆与质量门，最后回到最左边的「资金化」—— 反向流不是排版花招，
+ * 它就是闭环的方向，也是 A→C 那条连线能画得短的原因。
+ */
+interface Slot { lane: number; col: number; stack?: 'upper' | 'lower' }
+
+export const ARCH_SLOTS: Record<NodeId, Slot> = {
+  conversation: { lane: 0, col: 0 },
+  intent: { lane: 0, col: 1 },
+  runtime: { lane: 0, col: 2 },
+  answer: { lane: 0, col: 3 },
+  'data-sheet': { lane: 0, col: 4, stack: 'upper' },
+  'data-notebook': { lane: 0, col: 4, stack: 'lower' },
+
+  'source-raw': { lane: 1, col: 0 },
+  compile: { lane: 1, col: 1 },
+  build: { lane: 1, col: 2 },
+  recall: { lane: 1, col: 3 },
+  context: { lane: 1, col: 4 },
+
+  'funded-value': { lane: 2, col: 0 },
+  'daily-update': { lane: 2, col: 1 },
+  'memory-quality': { lane: 2, col: 2 },
+  'episodic-memory': { lane: 2, col: 3, stack: 'upper' },
+  'procedural-memory': { lane: 2, col: 3, stack: 'lower' },
+  interaction: { lane: 2, col: 4 },
+}
+
+/**
+ * 左侧走线挡板：**一块不可见的矩形，只给路由器一个约束**。
+ *
+ * 跨链路反馈要贴着板的最左边走，而标签是以线为中心摆的 —— 走线在 x≈20 时，
+ * 「沉淀进知识库」的左半边直接被画布边界裁掉（实测只剩「沉淀进知识…」）。
+ * 用可见的 padding 解决不了：路由器照样贴边。所以这里放一块不画任何东西的挡板，
+ * 把走线推离边界，标签才有地方站。
+ */
+export const ROUTE_WALL_W = 56
+
+/** 图上的装饰节点 id 前缀：它们不可选中，点击处理要忽略掉。 */
+export const DECORATION_PREFIX = 'deco:'
+export function isDecoration(id: string): boolean {
+  return id.startsWith(DECORATION_PREFIX)
+}
+
+export function boxOf(id: NodeId): ArchBox {
+  const slot = ARCH_SLOTS[id]
+  const height = slot.stack ? NODE_H_STACKED : NODE_H
+  const center = laneCenter(slot.lane)
+  const y = slot.stack
+    ? center + (slot.stack === 'upper' ? -STACK_OFFSET : STACK_OFFSET)
+    : center
+  return { x: columnX(slot.col), y, width: NODE_W, height }
+}
+
+// ----------------------------------------------------------------- 连边
+
+/**
+ * 边的语义。**两类**，不是五类：
+ * - `flow` / `branch`：带内流向。灰色，因为它回答的是「这一带里谁接谁」，看图就知道。
+ * - `inject` / `collect` / `feedback`：跨链路关系。蓝色，因为它回答的是「三条链路怎么
+ *   咬合」—— 这正是这张图存在的理由，所以它必须比带内流向更响，而且每条都带文字标签。
+ *   `feedback` 用虚线：它是回程，不是主方向。
+ */
+export type EdgeKind = 'flow' | 'branch' | 'inject' | 'collect' | 'feedback'
+
+export interface ArchEdge {
+  id: string
+  source: NodeId
+  target: NodeId
+  kind: EdgeKind
+  label?: string
+}
+
+/**
+ * 整张图的边。**每一类语义各只出现一次**，不再有第二处定义。
+ *
+ * 带内边按链路的阅读顺序写；跨链路边写在最后，因为它们是这张图的结论，
+ * 画在最上层才不会被节点卡片压住。
+ */
+export const ARCH_EDGES: ArchEdge[] = [
+  // A · 用户操作链路
+  { id: 'a1', source: 'conversation', target: 'intent', kind: 'flow' },
+  { id: 'a2', source: 'intent', target: 'runtime', kind: 'flow' },
+  { id: 'a3', source: 'runtime', target: 'answer', kind: 'flow' },
+  { id: 'a4', source: 'answer', target: 'data-sheet', kind: 'branch' },
+  { id: 'a5', source: 'answer', target: 'data-notebook', kind: 'branch' },
+
+  // B · 知识编译与召回链路（写入侧 → 读取侧）
+  { id: 'b1', source: 'source-raw', target: 'compile', kind: 'flow' },
+  { id: 'b2', source: 'compile', target: 'build', kind: 'flow' },
+  { id: 'b3', source: 'build', target: 'recall', kind: 'flow' },
+  { id: 'b4', source: 'recall', target: 'context', kind: 'flow' },
+
+  // C · 自进化（从右往左：交互 → 记忆 → 质量门 → 每日更新 → 资金化）
+  { id: 'c1', source: 'interaction', target: 'episodic-memory', kind: 'branch' },
+  { id: 'c2', source: 'interaction', target: 'procedural-memory', kind: 'branch' },
+  { id: 'c3', source: 'episodic-memory', target: 'memory-quality', kind: 'flow' },
+  { id: 'c4', source: 'procedural-memory', target: 'memory-quality', kind: 'flow' },
+  { id: 'c5', source: 'memory-quality', target: 'daily-update', kind: 'flow' },
+  { id: 'c6', source: 'daily-update', target: 'funded-value', kind: 'flow' },
+
+  // 跨链路：A → C → B → A，四段合起来才是闭环。
+  // 旧版缺 x2，于是图上只有「知识注入进来」和「记忆反馈回去」，看不出用户侧
+  // 的交互是怎么进到自进化里去的 —— 闭环断在起点。
+  { id: 'x1', source: 'answer', target: 'interaction', kind: 'collect', label: '交互回采' },
+  { id: 'x2', source: 'daily-update', target: 'compile', kind: 'feedback', label: '沉淀进知识库' },
+  { id: 'x3', source: 'memory-quality', target: 'intent', kind: 'feedback', label: '反馈到意图理解' },
+  { id: 'x4', source: 'context', target: 'runtime', kind: 'inject', label: 'Context Pack 注入' },
+]
+
+/**
+ * 边的外观。灰 / 蓝两档，没有第三档色相。
+ *
+ * **这一组是画布侧的字面量，不是漏改。** 它们进的是 G6 的 canvas 绘制路径，而
+ * `@antv/g-lite` 的颜色解析器只认 CSS 色值语法：`var(--tita-ink)` 会被 `color()`
+ * 判为无效，退回 `rgba(0,0,0,0)` —— 也就是线会**消失**，不是变色。所以画布上的颜色
+ * 只能保留字面量；卡片（HTML 节点）那一侧照常走共享令牌。
+ *
+ * 灰线 `#7d8b9e` 在白底 3.5:1 —— 线不是文字，3:1 是它的门槛，旧版的 `#9db2cc`
+ * 只有 2.2:1，在投影和缩放之后基本消失。蓝线 `#175cd3` 是 6.0:1。
+ */
+export const EDGE_STYLE: Record<EdgeKind, { stroke: string; lineWidth: number; lineDash?: number[] }> = {
+  flow: { stroke: '#7d8b9e', lineWidth: 1.4 },
+  branch: { stroke: '#7d8b9e', lineWidth: 1.4 },
+  inject: { stroke: '#175cd3', lineWidth: 1.6 },
+  collect: { stroke: '#175cd3', lineWidth: 1.6 },
+  feedback: { stroke: '#175cd3', lineWidth: 1.6, lineDash: [5, 4] },
+}
+
+/** 跨链路边走正交路由并自动避障：它们是长线，不能斜穿卡片。 */
+const CROSS_LANE: EdgeKind[] = ['inject', 'collect', 'feedback']
+
+/** 图例条目。**从 `EDGE_STYLE` 派生**，所以图例与画布不可能各说一套。 */
+export interface EdgeLegendItem { label: string; stroke: string; lineWidth: number; lineDash?: number[] }
+
+export const EDGE_LEGEND: EdgeLegendItem[] = [
+  { label: '链路内流向', ...EDGE_STYLE.flow },
+  { label: '跨链路流转', ...EDGE_STYLE.inject },
+  { label: '跨链路反馈', ...EDGE_STYLE.feedback },
+]
+
+// ----------------------------------------------------------------- 配色
+
+export interface LanePalette { accent: string; soft: string }
+
+/**
+ * 链路身份色。**只在带名的字母徽标上出现**，节点卡片本身是中性白 ——
+ * 「这条属于哪条链路」由带的位置和徽标回答，不由每张卡片再染一次色。
+ *
+ * 三个色都是暗色阶，因为徽标是 11px 的字母，它得能当正文色用。它们只进徽标的
+ * 行内样式（DOM），所以直接用共享 tone 词表；带内的知识链路原来是青绿 `#0e7490`，
+ * 共享词表里没有青色，取语义最近的一档绿。
+ */
+export const LANE_PALETTE: Record<LaneId, LanePalette> = {
+  interaction: { accent: 'var(--tita-primary)', soft: 'var(--tita-primary-soft)' },
+  knowledge: { accent: 'var(--tita-tone-green)', soft: 'var(--tita-tone-green-tint)' },
+  evolution: { accent: 'var(--tita-tone-violet)', soft: 'var(--tita-tone-violet-tint)' },
+}
+
+const FONT = 'var(--font-tita)'
+/* 卡片与牌子是 G6 的 HTML 节点：innerHTML 进的是真实 DOM，所以这几个值走共享令牌，
+ * 深色主题下卡片会跟着面板一起翻。画布**画**出来的东西见文件里的 CANVAS_* 常量。 */
+const INK = 'var(--tita-ink)'
+const INK_MUTED = 'var(--tita-ink-muted)'
+const INK_FAINT = 'var(--tita-ink-faint)'
+const RULE = 'var(--tita-line)'
+const SUNKEN = 'var(--tita-surface-muted)'
+const SURFACE = 'var(--tita-surface)'
+/* 画布侧：边标签的底色与描边。canvas 里 `var()` 会被解析成全透明（见 EDGE_STYLE 注释），
+ * 所以这里保留字面量，值就是浅色主题下的 line / surface。 */
+const CANVAS_LABEL_BG = '#ffffff'
+const CANVAS_LABEL_RULE = '#e4e7ec'
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char] as string)
+}
+
+/**
+ * 一张节点卡片的 DOM 字符串。
+ *
+ * 用 G6 的 HTML 节点（而不是 canvas 文本）是因为这张卡片要写**四层信息**：
+ * 标题、一句话说明、数据统计、实现状态。canvas 文本只有一种字号与字重，
+ * 四层挤成一样大就等于没有层次。
+ *
+ * 关键样式全部内联：卡片是画布里的 DOM，不保证和插件样式表同时到位，
+ * 靠类名会得到一张没有边框的白块。类名只用于选中态这类可选增强。
+ *
+ * 视觉上是「白卡 + 1px 发丝边 + 6px 圆角 + 几乎看不见的投影」。状态不是一块色底，
+ * 而是一枚小圆点加状态文字 —— 四张卡并排时，色底会比标题还响。
+ */
+export function cardHtml(id: NodeId, metrics: NodeMetric[], selected = false): string {
+  const meta = NODE_META[id]
+  const lane = LANE_PALETTE[meta.lane]
+  const status = NODE_STATUS_TONE[meta.status]
+  const compact = Boolean(ARCH_SLOTS[id].stack)
+  /**
+   * 卡片上最多两个计数，而且是**一行纯文字**，不是会自动换行的 chip 组。
+   *
+   * 0027 之前这里是三枚 chip、允许换行；「每日更新知识库」正好卡在换行边界上，
+   * 第二行被卡片裁掉一半 —— 裁掉的数字比没有数字更糟。两个计数 + 不换行，
+   * 一行放得下所有节点的组合（最宽的一组实测 141px，卡片内宽 158px），
+   * 完整的计数列表在右侧面板里，一个都没少。
+   */
+  const chips = metrics.slice(0, 2).map(metric =>
+    `<span style="display:inline-flex;align-items:baseline;gap:3px;white-space:nowrap;font-size:10px;line-height:16px;color:${INK_FAINT}">${escapeHtml(metric.label)}<b style="color:${INK};font-weight:600;font-variant-numeric:tabular-nums">${escapeHtml(metric.value)}</b></span>`).join('')
+  // 悬停给出完整名字与状态依据：卡片上的名字可能被省略号截短，但信息不能丢。
+  return `<div class="tita-archCard${selected ? ' tita-archCardOn' : ''}" title="${escapeHtml(`${meta.title} —— ${meta.statusNote}`)}" style="box-sizing:border-box;width:100%;height:100%;display:flex;flex-direction:column;gap:5px;padding:10px 11px;border-radius:6px;background:${SURFACE};border:1px solid ${selected ? lane.accent : RULE};box-shadow:${selected ? `0 0 0 3px ${lane.soft}` : '0 1px 2px rgba(16,24,40,.04)'};font-family:${FONT};overflow:hidden">
+  <div style="display:flex;align-items:center;gap:6px">
+    <span style="width:6px;height:6px;border-radius:999px;background:${lane.accent};flex:0 0 auto"></span>
+    <strong style="font-size:12.5px;font-weight:600;color:${INK};line-height:1.25;white-space:nowrap;overflow:hidden;text-overflow:ellipsis">${escapeHtml(meta.shortTitle ?? meta.title)}</strong>
+    <span style="margin-left:auto;flex:0 0 auto;display:inline-flex;align-items:center;gap:4px;font-size:10px;font-weight:600;color:${status.text}"><i style="width:5px;height:5px;border-radius:999px;background:${status.dot}"></i>${escapeHtml(NODE_STATUS_SHORT[meta.status])}</span>
+  </div>
+  <div style="font-size:11px;line-height:1.4;color:${INK_MUTED};display:-webkit-box;-webkit-line-clamp:${compact ? 1 : 2};-webkit-box-orient:vertical;overflow:hidden">${escapeHtml(meta.subtitle)}</div>
+  ${chips ? `<div style="margin-top:auto;display:flex;align-items:baseline;gap:10px;overflow:hidden">${chips}</div>` : ''}
+</div>`
+}
+
+/** 某条链路当前有多少节点落在每一档状态上。带名条右侧读它。 */
+export function laneStatusCounts(lane: LaneId): Record<NodeStatus, number> {
+  const counts = { live: 0, partial: 0, planned: 0, host: 0 } as Record<NodeStatus, number>
+  for (const id of nodesOfLane(NODE_LANES.findIndex(item => item.id === lane))) counts[NODE_META[id].status] += 1
+  return counts
+}
+
+/**
+ * 问题域牌子的 id 前缀。它们**不是节点**（不可被当成架构节点选中），但和带名牌不同，
+ * 它们**可点**：点开是在画布内浮层里展开这个域的完整论述。所以它们既不能进
+ * `isDecoration`，也不能进 `NODE_META`，只能有自己的前缀。
+ */
+export const PROBLEM_PREFIX = 'domain:'
+export function isProblemPlate(id: string): boolean {
+  return id.startsWith(PROBLEM_PREFIX)
+}
+export function problemIdOf(id: string): string {
+  return id.slice(PROBLEM_PREFIX.length)
+}
+
+/** 问题域身份色。只在牌子的图标与序号上出现，牌子本身是中性白；同样只进 DOM。 */
+const DOMAIN_TONE: Record<string, { accent: string; soft: string }> = {
+  violet: { accent: 'var(--tita-tone-violet)', soft: 'var(--tita-tone-violet-tint)' },
+  green: { accent: 'var(--tita-tone-green)', soft: 'var(--tita-tone-green-tint)' },
+  blue: { accent: 'var(--tita-primary)', soft: 'var(--tita-primary-soft)' },
+  amber: { accent: 'var(--tita-tone-amber)', soft: 'var(--tita-tone-amber-tint)' },
+  neutral: { accent: 'var(--tita-ink-muted)', soft: 'var(--tita-surface-muted)' },
+}
+
+/**
+ * 一条问题域牌子的 DOM。
+ *
+ * 它画在画布上，所以只能放**一眼能读完**的东西：这一带是什么、它现在走到哪一步、
+ * 以及衡量它的口径。业界对照那一段是整段引述，放上来会把牌子撑成一块文字墙，
+ * 而且它在「适应」档缩到 0.7 之后本来也读不了 —— 它属于点开后的浮层。
+ *
+ * 「点开看完整对照」这行提示不是装饰：牌子上没有任何看起来像按钮的东西，
+ * 不说清楚就没人知道它能点。
+ */
+export function problemPlateHtml(domain: ProblemDomain, stats: KnowledgeStats, version: number, selected = false): string {
+  const palette = DOMAIN_TONE[domain.tone] ?? DOMAIN_TONE.neutral!
+  const progress = domain.progress?.(stats, version) ?? []
+  const statusColor = domain.status.tone === 'success' ? 'var(--tita-success)' : domain.status.tone === 'warning' ? 'var(--tita-warning)' : INK_FAINT
+  const statusDot = domain.status.tone === 'success' ? 'var(--tita-success)' : domain.status.tone === 'warning' ? 'var(--tita-warning)' : INK_FAINT
+  const mechanisms = domain.actions.map(action => action.node
+    ? escapeHtml(action.label)
+    : `<span style="color:${INK_FAINT}">${escapeHtml(action.label)}<span style="opacity:.7">（未落地）</span></span>`).join('<span style="color:var(--tita-line-strong)"> · </span>')
+  const numbers = progress.map(item =>
+    `<span style="display:inline-flex;align-items:baseline;gap:3px;white-space:nowrap;font-size:10px;color:${INK_FAINT}">${escapeHtml(item.label)}<b style="color:${INK};font-weight:600;font-variant-numeric:tabular-nums">${escapeHtml(item.value)}</b></span>`).join('')
+  return `<div class="tita-archPlate${selected ? ' tita-archPlateOn' : ''}" title="${escapeHtml(`${domain.title} —— 点击展开完整论述`)}" style="box-sizing:border-box;width:100%;height:100%;display:flex;flex-direction:column;gap:7px;padding:11px 12px;border-radius:6px;background:${SURFACE};border:1px solid ${selected ? palette.accent : RULE};box-shadow:${selected ? `0 0 0 3px ${palette.soft}` : '0 1px 2px rgba(16,24,40,.04)'};font-family:${FONT};overflow:hidden">
+  <div style="display:flex;align-items:center;gap:7px">
+    <span style="display:inline-flex;width:22px;height:22px;flex:0 0 auto;align-items:center;justify-content:center;border-radius:5px;background:${palette.soft};color:${palette.accent};font-size:10px;font-weight:700;font-variant-numeric:tabular-nums">${escapeHtml(domain.index)}</span>
+    <strong style="min-width:0;overflow:hidden;white-space:nowrap;text-overflow:ellipsis;font-size:12.5px;font-weight:650;color:${INK}">${escapeHtml(domain.title)}</strong>
+    <span style="margin-left:auto;flex:0 0 auto;display:inline-flex;align-items:center;gap:4px;font-size:10px;font-weight:600;color:${statusColor}"><i style="width:5px;height:5px;border-radius:999px;background:${statusDot}"></i>${escapeHtml(domain.status.label)}</span>
+  </div>
+  <div style="font-size:11px;line-height:1.45;color:${INK_MUTED};display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden">${escapeHtml(domain.question)}</div>
+  <div style="display:flex;align-items:baseline;gap:6px;min-width:0"><span style="flex:0 0 auto;font-size:9.5px;font-weight:700;letter-spacing:.06em;color:${INK_FAINT}">机制</span><span style="min-width:0;overflow:hidden;white-space:nowrap;text-overflow:ellipsis;font-size:10.5px;color:${INK_MUTED}">${mechanisms}</span></div>
+  ${numbers ? `<div style="margin-top:auto;display:flex;align-items:baseline;gap:10px;overflow:hidden">${numbers}</div>` : '<div style="margin-top:auto"></div>'}
+  <div style="display:flex;align-items:baseline;gap:6px;border-top:1px solid ${RULE};padding-top:6px"><span style="flex:0 0 auto;font-size:9.5px;font-weight:700;letter-spacing:.06em;color:${INK_FAINT}">衡量</span><span style="min-width:0;overflow:hidden;white-space:nowrap;text-overflow:ellipsis;font-size:10.5px;color:${INK_MUTED}">${escapeHtml(domain.measure)}</span><span style="margin-left:auto;flex:0 0 auto;font-size:10px;color:${palette.accent}">展开 ›</span></div>
+</div>`
+}
+
+/**
+ * 问题域带的带名条。
+ *
+ * 它比链路名牌宽，因为要一次说清两件事：这一带是什么，以及全图实现到哪一步。
+ * 逐带的状态计数（A / B / C 各自几实现几待做）也挂在这里 —— 0027 之前它写在右侧
+ * 面板的空态里，而空态面板已经撤掉了（画布上不再有「未选中」这一态）。
+ *
+ * 这里**不写**「三个问题域都建立在口径可信的取数之上」那句话：它是一整句论述，
+ * 挤进 30px 高的牌子只会被截成「…口径…」，读起来像坏了。那句话在浮层的「底座」一段。
+ */
+export function problemHeadHtml(): string {
+  const laneLine = NODE_LANES.map(lane => {
+    const counts = laneStatusCounts(lane.id)
+    const parts = (['live', 'partial', 'planned', 'host'] as NodeStatus[])
+      .filter(status => counts[status] > 0)
+      .map(status => `${NODE_STATUS_SHORT[status]} ${counts[status]}`)
+      .join(' · ')
+    return `${lane.index} ${parts}`
+  }).join('　')
+  return `<div style="box-sizing:border-box;width:100%;height:100%;display:flex;align-items:center;gap:10px;padding:0 11px;background:${SUNKEN};border:1px solid ${RULE};border-radius:6px;font-family:${FONT}">
+  <strong style="flex:0 0 auto;font-size:12px;font-weight:650;color:${INK}">Agent 解决的问题域</strong>
+  <span style="flex:0 0 auto;font-size:10.5px;color:${INK_FAINT}">按重要性排序 · 点开看业界对照与衡量方式</span>
+  <span style="margin-left:auto;flex:0 0 auto;font-size:10px;color:${INK_MUTED};font-variant-numeric:tabular-nums">${escapeHtml(laneLine)}</span>
+</div>`
+}
+
+/**
+ * 一条带的带名牌。**这是链路名唯一出现的地方** —— 它挂在带自己的左上角，
+ * 而不是左侧留白里：留白要留给跨链路走线，而且「带名贴着自己那条带」本来就更好读。
+ *
+ * 牌子上只有字母徽标和链路名，因为再多的东西就要把牌子撑宽，而牌子越宽，
+ * 垂直走线能走的余地越小。流程说明与状态统计因此搬到**问题域带的带名条**上 ——
+ * 那条带下面没有垂直走线，是这块版式里唯一放得下它们的地方。
+ */
+export function laneHeadHtml(lane: LaneMeta): string {
+  const palette = LANE_PALETTE[lane.id]
+  return `<div style="box-sizing:border-box;width:100%;height:100%;display:flex;align-items:center;gap:9px;padding:0 11px;background:${SUNKEN};border:1px solid ${RULE};border-radius:6px;font-family:${FONT}">
+  <span style="display:inline-flex;width:18px;height:18px;flex:0 0 auto;align-items:center;justify-content:center;border-radius:4px;background:${palette.soft};color:${palette.accent};font-size:11px;font-weight:700;line-height:1">${escapeHtml(lane.index)}</span>
+  <strong style="min-width:0;overflow:hidden;white-space:nowrap;text-overflow:ellipsis;font-size:12px;font-weight:650;color:${INK}">${escapeHtml(lane.title)}</strong>
+</div>`
+}
+
+// ----------------------------------------------------------------- G6 数据
+
+/**
+ * G6 的图数据形状。
+ *
+ * `[key: string]: unknown` 这一行不是偷懒：G6 的 `NodeData` / `EdgeData` 自带索引
+ * 签名，没有它这里的结构体无法赋给它（TS 会报「缺少索引签名」）。我仍然显式声明
+ * `id` / `source` / `target`，因为那才是我们真正依赖的字段。
+ */
+export interface ArchNodeDatum {
+  id: string
+  type: string
+  style: Record<string, unknown>
+  data?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+export interface ArchEdgeDatum {
+  id: string
+  source: string
+  target: string
+  /** G6 v5 读的是 **data 上的** `type`；写进 `style` 等于没写，会退回图级默认。 */
+  type: string
+  style: Record<string, unknown>
+  data?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+export interface ArchGraph { nodes: ArchNodeDatum[]; edges: ArchEdgeDatum[] }
+
+/** 三条带名牌 + 问题域带名牌 + 一块不可见的走线挡板。它们先入数组，画在卡片之下。 */
+function decorations(): ArchNodeDatum[] {
+  const wall: ArchNodeDatum = {
+    id: `${DECORATION_PREFIX}route-wall`,
+    type: 'rect',
+    style: {
+      x: ROUTE_WALL_W / 2, y: CANVAS_HEIGHT / 2,
+      size: [ROUTE_WALL_W, CANVAS_HEIGHT],
+      fill: 'transparent', stroke: 'transparent', lineWidth: 0,
+      pointerEvents: 'none',
+    },
+  }
+  return [wall, ...NODE_LANES.map((lane, index) => ({
+    id: `${DECORATION_PREFIX}lane-${lane.id}`,
+    type: 'html',
+    style: {
+      x: GUTTER + LANE_HEAD_W / 2, y: laneTop(index) + LANE_HEAD_H / 2,
+      size: [LANE_HEAD_W, LANE_HEAD_H],
+      // HTML 节点的容器以左上角为原点，靠 dx/dy 把它对到格子的中心。
+      dx: -LANE_HEAD_W / 2, dy: -LANE_HEAD_H / 2,
+      innerHTML: laneHeadHtml(lane),
+      // 点带名牌等于点空白：它是装饰，不是节点。
+      pointerEvents: 'none',
+    },
+  })), {
+    id: `${DECORATION_PREFIX}problems-head`,
+    type: 'html',
+    style: {
+      x: GUTTER + PROBLEM_HEAD_W / 2, y: PROBLEM_TOP + PROBLEM_HEAD_H / 2,
+      size: [PROBLEM_HEAD_W, PROBLEM_HEAD_H],
+      dx: -PROBLEM_HEAD_W / 2, dy: -PROBLEM_HEAD_H / 2,
+      innerHTML: problemHeadHtml(),
+      pointerEvents: 'none',
+    },
+  }]
+}
+
+/** 带上按阅读顺序排好的节点（自进化带是反向的，由 ARCH_SLOTS 的列号决定）。 */
+export function nodesOfLane(lane: number): NodeId[] {
+  const rank = (slot: Slot): number => slot.stack === 'upper' ? -1 : slot.stack === 'lower' ? 1 : 0
+  return (Object.keys(ARCH_SLOTS) as NodeId[])
+    .filter(id => ARCH_SLOTS[id].lane === lane)
+    .sort((left, right) => ARCH_SLOTS[left].col - ARCH_SLOTS[right].col || rank(ARCH_SLOTS[left]) - rank(ARCH_SLOTS[right]))
+}
+
+/**
+ * 把「节点 + 统计 + 状态」编译成 G6 的图数据。
+ *
+ * 统计只来自 `nodeMetrics(stats, version)`：图上卡片与右侧面板读的是同一个数组，
+ * 所以不会出现「图上 12 张卡片、面板 11 张」这种两边各算一次才有的错。
+ */
+export function toGraphData(stats: KnowledgeStats, version: number, selected: NodeId | null = null, selectedDomain: string | null = null): ArchGraph {
+  const nodes: ArchNodeDatum[] = decorations()
+  for (const id of Object.keys(ARCH_SLOTS) as NodeId[]) {
+    const box = boxOf(id)
+    nodes.push({
+      id,
+      type: 'html',
+      data: { nodeId: id },
+      style: {
+        x: box.x, y: box.y, size: [box.width, box.height],
+        dx: -box.width / 2, dy: -box.height / 2,
+        innerHTML: cardHtml(id, nodeMetrics(id, stats, version), selected === id),
+        pointerEvents: 'auto',
+      },
+    })
+  }
+  // 问题域牌子：**可点**，所以它们是真正的图元素，不是装饰。它们与节点共用一套
+  // 「选中就换边框」的反馈，读起来才是同一张图上的两种东西。
+  PROBLEM_DOMAINS.forEach((domain, index) => {
+    const box = problemPlateBox(index)
+    nodes.push({
+      id: `${PROBLEM_PREFIX}${domain.id}`,
+      type: 'html',
+      data: { domainId: domain.id },
+      style: {
+        x: box.x, y: box.y, size: [box.width, box.height],
+        dx: -box.width / 2, dy: -box.height / 2,
+        innerHTML: problemPlateHtml(domain, stats, version, selectedDomain === domain.id),
+        pointerEvents: 'auto',
+      },
+    })
+  })
+  const edges: ArchEdgeDatum[] = ARCH_EDGES.map(edge => {
+    const palette = EDGE_STYLE[edge.kind]
+    const style: Record<string, unknown> = {
+      stroke: palette.stroke,
+      lineWidth: palette.lineWidth,
+      ...(palette.lineDash ? { lineDash: palette.lineDash } : {}),
+      endArrow: true, endArrowType: 'triangle', endArrowSize: 8,
+    }
+    if (CROSS_LANE.includes(edge.kind)) {
+      // 正交 + 自动避障：这几条是长线，斜着连会横穿中间的卡片。
+      style.radius = 10
+      style.router = { type: 'shortest-path', enableObstacleAvoidance: true, offset: 14, gridSize: 8 }
+    } else if (edge.kind === 'branch') {
+      style.radius = 8
+      style.router = { type: 'orth', padding: 14 }
+    }
+    if (edge.label) {
+      Object.assign(style, {
+        labelText: edge.label, labelFontSize: 10, labelFill: palette.stroke, labelFontFamily: FONT,
+        // 默认会按路径方向旋转标签，竖直那一段于是把中文排成了一列一个字。
+        labelAutoRotate: false,
+        labelBackground: true, labelBackgroundFill: CANVAS_LABEL_BG, labelBackgroundRadius: 4,
+        // 画布侧的字面量：见文件顶部 CANVAS_LABEL_* 的说明。
+        labelBackgroundStroke: CANVAS_LABEL_RULE, labelBackgroundLineWidth: 1,
+        labelPadding: [2, 6, 2, 6],
+      })
+    }
+    return {
+      id: edge.id,
+      source: edge.source,
+      target: edge.target,
+      type: 'polyline',
+      data: { kind: edge.kind },
+      style,
+    }
+  })
+  return { nodes, edges }
+}
+
+/** 全图每条链路当前有多少节点「已实现 / 部分实现 / 待实现」——概览页脚用。 */
+export function statusCounts(): Record<string, number> {
+  const counts: Record<string, number> = {}
+  for (const meta of Object.values(NODE_META)) counts[meta.status] = (counts[meta.status] ?? 0) + 1
+  return counts
+}
+
+export function formatBuildTime(value: string | undefined): string {
+  if (!value) return '尚未编译'
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) return '已编译'
+  return date.toLocaleString('zh-CN', { month: 'numeric', day: 'numeric', hour: '2-digit', minute: '2-digit' })
+}
+
+/**
+ * 节点面板的「状态记录」。
+ *
+ * 只写**有出处**的字段：`/knowledge/stats` 里的构建清单与磁盘计数。拿不到的东西
+ * （比如「情节记忆 248 条」）就不写 —— 那一栏曾经是编出来的占位数字，0025 把它
+ * 换成了真实的增量编译计数，因为这张图现在是契约，不是示意图。
+ */
+export function recordRows(id: NodeId, stats: KnowledgeStats, version: number): Array<[string, string]> {
+  const build = stats.lastBuild ?? null
+  const rows: Array<[string, string]> = []
+  const indexRow: [string, string] = ['索引版本', version > 0 ? `v${version}` : '未构建']
+  switch (id) {
+    case 'source-raw':
+      rows.push(['SourceRaw 文档', String(sourceCountOf(stats))])
+      rows.push(['卡片版本快照', String(stats.cardVersions ?? 0)])
+      rows.push(['最近编译', formatBuildTime(stats.builtAt)])
+      break
+    case 'compile':
+      rows.push(['上一轮编译', build ? (build.skipped ? '跳过（语料无变化）' : `复用 ${build.cardsReused ?? 0} / 重编 ${build.cardsRecompiled ?? 0}`) : '尚未编译'])
+      rows.push(['新增 / 删除卡片', `${build?.cardsAdded ?? 0} / ${build?.cardsRemoved ?? 0}`])
+      rows.push(['wikiNotes 复用 / 重编', `${build?.notesReused ?? 0} / ${build?.notesRecompiled ?? 0}`])
+      rows.push(['已纳入指纹的卡片', String(stats.trackedCards ?? 0)])
+      break
+    case 'build':
+      rows.push(['向量条目', String(stats.vectorCount ?? 0)])
+      rows.push(['量化方式', stats.vectorQuantization ?? 'binary+hamming+int8'])
+      rows.push(['最近构建', formatBuildTime(stats.builtAt)])
+      rows.push(['上一轮向量复用', build ? String(build.notesReused ?? 0) : '—'])
+      rows.push(indexRow)
+      break
+    case 'recall':
+      rows.push(['默认路线', stats.recallMode ?? 'hybrid'])
+      rows.push(['召回 topK', String(stats.recallTopK ?? 10)])
+      rows.push(['检索后端', stats.searchBackend === 'hybrid' ? 'Hybrid（关键词 + 向量 + 图谱）' : 'FTS fallback'])
+      rows.push(indexRow)
+      break
+    case 'context':
+      rows.push(['重排 Provider', stats.rerankProvider === 'none' ? '关闭（按融合分数）' : stats.rerankProvider ?? 'bert-python'])
+      rows.push(['重排模型', stats.rerankModel ?? 'BAAI/bge-reranker-base'])
+      rows.push(['上下文 topN', String(stats.contextTopN ?? 5)])
+      rows.push(['可注入 Runtime', version > 0 ? '是' : '等待编译'])
+      break
+    case 'runtime':
+      rows.push(indexRow)
+      rows.push(['检索后端', stats.searchBackend === 'hybrid' ? 'Hybrid' : 'FTS fallback'])
+      rows.push(['Embedding', stats.embeddingStatus === 'ready' ? '已就绪' : stats.embeddingProvider === 'none' ? '关闭' : '不可用（FTS fallback）'])
+      rows.push(['模型 / 设备', `${stats.embeddingModel ?? 'WeMM'} · ${stats.embeddingDevice ?? 'auto'}`])
+      break
+    case 'interaction':
+      rows.push(['意图审计流', '每轮一条 intent 记录（只标注不拦截）'])
+      rows.push(['memory/ 落盘', `${memoryCountOf(stats)} 个文件`])
+      break
+    case 'episodic-memory':
+    case 'procedural-memory':
+    case 'memory-quality':
+    case 'daily-update':
+      rows.push(['memory/ 落盘', `${memoryCountOf(stats)} 个文件`])
+      rows.push(['卡片版本快照', String(stats.cardVersions ?? 0)])
+      rows.push(['最近编译', formatBuildTime(stats.builtAt)])
+      break
+    default:
+      rows.push(indexRow)
+      break
+  }
+  return rows
+}