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

package/src/client/architecture.tsx

@@ -0,0 +1,530 @@
+/**
+ * 架构图的**唯一数据源**：节点是什么、属于哪条链路、核心逻辑是什么、现在实现到哪一步。
+ *
+ * 这个模块刻意不含任何图形代码（0025 之前它自带一套 DOM 车道 + 回字形阶段图）。
+ * 「Agent 概览」现在是一张 AntV G6 绘制的整体架构图（`./arch/`），节点卡片、右侧逻辑
+ * 面板、键盘可达的节点列表三处读的是**同一份 `NODE_META` 与 `nodeMetrics`**：
+ * 图上写「已实现」而面板写「部分实现」这种事，只能靠两处各写一份才会发生。
+ *
+ * 设置**不在**这里，也不在任何节点上。节点只承载三件事：它是什么、它的数据统计、
+ * 它的实现状态；改配置请去它所属的功能 tab（节点上的「跳转到配置」按钮就是那条路）。
+ */
+
+import {
+  BarChart3, Box, BrainCircuit, ClipboardCheck, Clock3, Database, FileCode2, FileText,
+  Gauge, GitBranch, HardDrive, Layers3, MessageCircle, RefreshCw, Search, Share2,
+  Table2, UserRound,
+} from '@tita-data-agent/ui/icons'
+import type { LucideIcon } from '@tita-data-agent/ui/icons'
+
+/**
+ * 视图级标记色。**架构图不再用它**：图上每个节点的身份就是它所属的链路（`lane`），
+ * 所以节点不需要再单独存一个 `tone` —— 那个字段曾经可以和 `lane` 打架（资金化属于
+ * C 带却写着绿色），而「一条链路一个色」是不能靠两处约定维持的。
+ */
+export type Tone = 'blue' | 'violet' | 'green' | 'amber' | 'neutral'
+
+/** 面板的一级 tab。`KnowledgePanel` 的 `ViewId` 就是它，避免两处各写一个联合。 */
+export type PanelTab = 'overview' | 'intent' | 'knowledge' | 'attribution' | 'memory' | 'eval'
+
+/**
+ * 知识库内部的分栏。**与知识链路的五个节点一一对应** —— 图上一个节点对应一个
+ * 能看内容、也能改设置的地方；对不上就说明要么缺页、要么多了一个没有归属的页。
+ */
+/**
+ * 知识库分栏（0033 把「召回」与「重排」合成一栏）。
+ *
+ * 合并不是因为「两个阶段变成一个」—— 它们在流水线上仍然是两步。合的是**界面**：
+ * 这两栏回答的是同一个问题（「跑一次真实召回，结果长什么样」），而且分成两栏时
+ * 用户必须先跑「召回」再切到「重排」才能看到同一次运行的全貌，两栏各自还有一个
+ * 测试按钮和一套 topK/topN 输入。一栏里从上到下就是一条链：三路各自命中什么 →
+ * 融合后的排序 → cross-encoder 丢了多少 → 最终进上下文的 topN。
+ */
+export type KnowledgeTab = 'source-raw' | 'wiki' | 'graph' | 'recall'
+
+/**
+ * 五个分栏的顺序、名字与图标。**定义在这里而不是在 `KnowledgeBaseTab` 里**：
+ * 渲染它的地方有两个 —— 面板外壳顶部那一条分栏 tab，和知识库内容本身。
+ * 两处各写一份，迟早会出现「tab 上写知识图谱、面板里写 Graph」。
+ *
+ * `step` 是这一栏在知识链路里**做的动作**。它存在的理由：这五栏不是五个并列的
+ * 视图，而是一条流水线（收录 → 编译 → 关联 → 检索 → 精排），所以它们的切换器
+ * 得说清「谁接谁」——只写名词（SourceRaw / Wiki / 知识图谱）看不出先后。
+ */
+export const KNOWLEDGE_TABS: Array<{ id: KnowledgeTab; label: string; step: string; icon: LucideIcon }> = [
+  { id: 'source-raw', label: 'SourceRaw', step: '收录', icon: Database },
+  { id: 'wiki', label: 'Wiki', step: '编译', icon: Layers3 },
+  { id: 'graph', label: '知识图谱', step: '关联', icon: GitBranch },
+  { id: 'recall', label: '召回重排', step: '检索 · 精排', icon: Search },
+]
+
+export type LaneId = 'interaction' | 'knowledge' | 'evolution'
+
+export interface LaneMeta {
+  id: LaneId
+  index: string
+  title: string
+  note: string
+}
+
+/**
+ * 三条链路。顺序就是阅读顺序，也是 G6 画布上从上到下的三条带。
+ *
+ * 只有三条：用户操作、知识编译与召回、自进化。多一条「基础设施」之类的带会让图变成
+ * 清单；少的那些（转换内核、Embedding）本来就是某一带里某个节点的手段，不是平级链路。
+ *
+ * `note` 写在每张带自己的左上角，`index` 是它的字母徽标 —— 链路名不进左侧留白，
+ * 因为那条留白要留给跨链路的走线（A↔B↔C 的关系就画在那里）。
+ */
+export const NODE_LANES: LaneMeta[] = [
+  { id: 'interaction', index: 'A', title: '用户操作链路', note: '提问 → 理解 → 执行 → 产出' },
+  { id: 'knowledge', index: 'B', title: '知识编译与召回链路', note: 'SourceRaw → 编译 → 构建 → 召回 → 重排' },
+  { id: 'evolution', index: 'C', title: '自进化 Agent', note: '交互 → 记忆 → 质量门 → 每日更新 → 资金化' },
+]
+
+export type NodeId =
+  | 'conversation' | 'intent' | 'runtime' | 'answer' | 'data-sheet' | 'data-notebook'
+  | 'source-raw' | 'compile' | 'build' | 'recall' | 'context'
+  | 'interaction' | 'episodic-memory' | 'procedural-memory' | 'memory-quality' | 'daily-update' | 'funded-value'
+
+/**
+ * 实现状态。**这是这张图最容易被写坏的一格**：把待实现的画成已实现，图就从契约
+ * 退化成宣传。所以状态只有四档，且每一档都要在 `statusNote` 里说清依据。
+ *
+ * - `host`：不是本插件的代码（Runtime / Table / Notebook 由宿主提供），不冒充我们的进度。
+ */
+export type NodeStatus = 'live' | 'partial' | 'planned' | 'host'
+
+export const NODE_STATUS_LABEL: Record<NodeStatus, string> = {
+  live: '已实现',
+  partial: '部分实现',
+  planned: '待实现',
+  host: '宿主提供',
+}
+
+/**
+ * 卡片上的状态文字。**只有「宿主提供」需要缩短** —— 它是四个字，而卡片右侧那点宽度
+ * 是从标题里借的：省下两个字，`记忆整理与质量检查` 这种九字标题才放得下。
+ * 面板、无障碍列表和状态记录读的仍是完整措辞，缩的只是图上那一处。
+ */
+export const NODE_STATUS_SHORT: Record<NodeStatus, string> = {
+  ...NODE_STATUS_LABEL,
+  host: '宿主',
+}
+
+/**
+ * 状态色：**四档只用三种颜色，而且只在文字上**。
+ *
+ * 「已实现」是常态，所以它拿绿（`--tita-success`，白底 5.7:1）；「部分实现」是唯一需要
+ * 人动手的一档，拿琥珀（`--tita-warning`，5.4:1）；「待实现」和「宿主提供」都不是我们的
+ * 进度，拿两级灰：文字分两级（faint / muted），圆点合并成 faint 一档 —— 共享词表里只有
+ * 三级墨色，而这两档圆点本来就只差一格，区分它们的是文字。
+ * 四档不各配一个背景色药丸 —— 那样四张卡片并排时，颜色比标题还响。
+ *
+ * `fill` 仍然保留，但它只用在**需要一整块底**的地方（例如图例上的小色块）；
+ * 卡片上的状态是「一个小圆点 + 状态文字」，不是一块色底。
+ *
+ * 这些值进的是 G6 **HTML 节点**的 innerHTML，也就是真实 DOM，所以可以用共享令牌。
+ */
+export const NODE_STATUS_TONE: Record<NodeStatus, { fill: string; text: string; dot: string }> = {
+  live: { fill: 'var(--tita-tone-green-tint)', text: 'var(--tita-success)', dot: 'var(--tita-success)' },
+  partial: { fill: 'var(--tita-tone-amber-tint)', text: 'var(--tita-warning)', dot: 'var(--tita-warning)' },
+  planned: { fill: 'var(--tita-surface-muted)', text: 'var(--tita-ink-faint)', dot: 'var(--tita-ink-faint)' },
+  host: { fill: 'var(--tita-surface-muted)', text: 'var(--tita-ink-muted)', dot: 'var(--tita-ink-faint)' },
+}
+
+/** 一个执行步骤。/  `state` 决定面板里显示对勾、半勾还是空心圈。 */
+export interface NodeStep {
+  label: string
+  detail: string
+  state?: 'done' | 'partial' | 'todo'
+}
+
+export interface NodeMeta {
+  title: string
+  /**
+   * 卡片上的短名。只给放不进 180px 卡片的标题用 —— 卡片是示意图，它旁边还站着
+   * 十来个同宽的字；面板里写的始终是完整名字，卡片的 `title` 悬停也给出完整名字。
+   */
+  shortTitle?: string
+  subtitle: string
+  /** 一句话核心逻辑：这一格负责把什么变成什么。 */
+  detail: string
+  /** 输入 → 输出。图上不写，面板里写 —— 它回答的是「它凭什么能工作」。 */
+  input: string
+  output: string
+  steps: NodeStep[]
+  status: NodeStatus
+  /** 状态的依据。面板「状态记录」直接展示，图上的徽标用它做 title。 */
+  statusNote: string
+  icon: LucideIcon
+  lane: LaneId
+  /** 点「跳转到配置」时切到哪个 tab；没有对应页面的节点不给按钮，而不是给一个假按钮。 */
+  tab?: PanelTab
+  /** `tab === 'knowledge'` 时落到哪个分栏。 */
+  knowledgeTab?: KnowledgeTab
+}
+
+export const NODE_META: Record<NodeId, NodeMeta> = {
+  conversation: {
+    title: '用户对话', subtitle: '提出问题、选择数据、执行分析',
+    detail: '接收自然语言问题、任务描述和当前会话上下文，把它转成一次可执行的分析请求。',
+    input: '自然语言问题、当前会话上下文', output: '一次带会话标识的分析请求',
+    steps: [
+      { label: '接收问题', detail: '用户在面板里提问，会话与轮次 id 一并带上', state: 'done' },
+      { label: '携带上下文', detail: '当前选中的知识库、数据范围随请求下发', state: 'done' },
+    ],
+    status: 'host', statusNote: '对话入口由宿主（DSH Web）提供，本插件不实现它，只在链路里标明位置。',
+icon: MessageCircle, lane: 'interaction',
+  },
+  intent: {
+    title: '意图与上下文', subtitle: '两段式判定：命中预置分类，否则模型自行判断',
+    detail: '识别用户意图，合并会话、数据范围、知识召回和可用工具，生成 Runtime 可消费的执行上下文。',
+    input: '用户原文 + 会话 + 任务上下文', output: '一条 intent 记录：category / act / 置信度 / 引用的知识',
+    steps: [
+      { label: '预置分类优先', detail: '命中「意图配置」里的分类就直接归类过去', state: 'done' },
+      { label: '未命中交模型判断', detail: '不命中时不硬塞，由模型自行给出 category 与 act', state: 'done' },
+      { label: '置信度与兜底', detail: '低于阈值的记录标 lowConfidence；漏调由 Host 补一条 fallback', state: 'done' },
+      { label: '引用溯源', detail: '记录这一轮引用了哪些知识（source / wiki）', state: 'done' },
+    ],
+    status: 'live', statusNote: '意图记录、分类注册表、act 词表、两段式路由提示词都已落盘并随 intent_record 工具下发。',
+icon: BrainCircuit, lane: 'interaction', tab: 'intent',
+  },
+  runtime: {
+    title: 'Tita Agent Runtime', shortTitle: 'Agent Runtime', subtitle: '规划、调用工具、执行分析',
+    detail: 'Agent 核心运行时：编排知识召回、数据表格、Notebook 和自进化记忆，组织结果并返回给用户。',
+    input: '意图与上下文 + 召回得到的知识', output: '回答、引用、结构化数据',
+    steps: [
+      { label: '注入 Context Pack', detail: '重排后的 wikiNotes 连同 wiki 与关系图进入模型上下文', state: 'done' },
+      { label: '调用工具', detail: '取数、表格、Notebook、知识写入都由工具完成', state: 'done' },
+      { label: '组织回答', detail: '解释与引用一起返回，结构化结果转交 Table / Notebook', state: 'done' },
+    ],
+    status: 'host', statusNote: 'Runtime 是宿主 Agent 本体；本插件以「召回上下文 + 知识工具」的方式接入它。',
+icon: Box, lane: 'interaction',
+  },
+  answer: {
+    title: '回答 / 数据工具', subtitle: '生成结果、可视化与方案',
+    detail: '输出解释、引用和数据结果，并把结构化结果继续交给 Table 或 Notebook 处理。',
+    input: '模型回答 + 工具返回值', output: '可读回答、可编辑表格、可复现 Notebook',
+    steps: [
+      { label: '回答与引用', detail: '每一条结论都能指回 wiki 与 SourceRaw', state: 'done' },
+      { label: '转交数据工具', detail: '结构化结果可继续在 Table / Notebook 里加工', state: 'done' },
+    ],
+    status: 'host', statusNote: '回答渲染与 Table / Notebook 由宿主工作区提供。',
+icon: BarChart3, lane: 'interaction',
+  },
+  'data-sheet': {
+    title: 'Table', subtitle: '生成 / 查看数据表格',
+    detail: '把 Agent 产出的结构化数据交给 Table，进行筛选、编辑、版本管理和导出。',
+    input: '结构化结果集', output: '带版本与导出的表格',
+    steps: [{ label: '打开数据表格', detail: '由宿主的 Table 插件承载', state: 'done' }],
+    status: 'host', statusNote: '属于 `dsh-data-table` 插件，这里只画调用关系。',
+icon: Table2, lane: 'interaction',
+  },
+  'data-notebook': {
+    title: 'Notebook', subtitle: '生成 / 分析 Notebook',
+    detail: '把查询、SQL、Markdown 和图表组织成可复用的分析 Notebook。',
+    input: '查询与代码片段', output: '可复现的分析 Notebook',
+    steps: [{ label: '打开数据笔记本', detail: '由宿主的 Notebook 插件承载', state: 'done' }],
+    status: 'host', statusNote: '属于 `dsh-data-notebook` 插件，这里只画调用关系。',
+icon: FileCode2, lane: 'interaction',
+  },
+
+  'source-raw': {
+    title: 'SourceRaw', subtitle: '原始可追溯文档',
+    detail: '保存原始来源文档（Markdown、图片、对话沉淀），可追溯、按 external_id 幂等；SourceRaw 本身不参与召回。',
+    input: '上传文件 / 转换内核产出 / Agent 写入', output: '带来源分类、内容 hash 与版本历史的原始文档',
+    steps: [
+      { label: '按格式路由解析', detail: '文件类型表决定走 anydoc 内核还是直读文本', state: 'done' },
+      { label: '来源分类闸门', detail: '分类注册表校验 source_type，自定义分类建完即可用', state: 'done' },
+      { label: '内容幂等写入', detail: '同 external_id 覆盖时先快照旧版本，正文没变则不造版本', state: 'done' },
+      { label: '版本历史与回滚', detail: '快照落在 04_memory/source-versions/，回滚本身也可回滚', state: 'done' },
+    ],
+    status: 'live', statusNote: '写入、分类、版本、回滚、详情都已在知识库 → SourceRaw 里实现。',
+icon: Database, lane: 'knowledge', tab: 'knowledge', knowledgeTab: 'source-raw',
+  },
+  compile: {
+    title: '编译', subtitle: 'SourceRaw → wiki 卡片 + wikiNotes',
+    detail: '把 SourceRaw 按主题聚合为 wiki 卡片，并切分出召回单元 wikiNotes。类型与名称一起定，判重按 slug。',
+    input: 'SourceRaw 文档 + Wiki 类型注册表', output: 'wiki 卡片（含版本）+ 可召回的 wikiNotes',
+    steps: [
+      { label: 'Pass 0 · 候选抽取', detail: '从正文标题、[[链接]]、frontmatter 与显式 candidates 抽实体 / 概念 / 关系，类型 + 名称 + 证据一起定', state: 'done' },
+      { label: '归一 · 与库内判重', detail: '按 slug 与别名比对，同指一物就复用（合并 source_refs），related ≠ same', state: 'done' },
+      { label: '落卡 · 按 schema 写入', detail: 'write_knowledge_card 校验必填小节 / 字段，命中则增量合并', state: 'done' },
+      { label: 'Finalize · 索引与质检', detail: '索引页、死链、交叉链接与三层质检，不调模型', state: 'partial' },
+    ],
+    status: 'partial', statusNote: 'Pass 0 抽取与归一判重已实现（规则抽取，不调模型：候选写进 02_wiki 后仍需人复核）；落卡已实现。Finalize 的索引页 / 死链 / 交叉链接还缺，所以这一格仍是「部分实现」。',
+icon: RefreshCw, lane: 'knowledge', tab: 'knowledge', knowledgeTab: 'wiki',
+  },
+  build: {
+    title: '构建', subtitle: 'wikiNotes → 向量 · wiki → 知识图谱',
+    detail: '从 wikiNotes 构建向量索引，从 wiki 卡片构建知识图谱：SourceRaw 作为溯源边；构建是确定性计算，可独立重跑。',
+    input: 'wikiNotes + wiki 卡片', output: '向量索引（binary + int8）与 knowledge_graph.json',
+    steps: [
+      { label: '切分召回单元', detail: '长卡片按小节切成多条 wikiNotes，unitId 稳定', state: 'done' },
+      { label: '构建向量索引', detail: '逐条 contentHash 复用，只有变化的条目重新编码', state: 'done' },
+      { label: '构建知识图谱', detail: 'wiki 节点 + supported_by 溯源边', state: 'done' },
+      { label: '图上的关系边', detail: 'Pass 0 抽出的 wiki↔wiki 关系边（relates_to）与溯源边并存', state: 'done' },
+    ],
+    status: 'live', statusNote: '向量与图谱构建都已实现且已增量（未变的条目复用向量，不重新编码）。',
+icon: HardDrive, lane: 'knowledge', tab: 'knowledge', knowledgeTab: 'graph',
+  },
+  recall: {
+    title: '召回', subtitle: 'wikiNotes 三路召回（关键词 / 向量 / 知识图谱）',
+    detail: '对 wikiNotes 做三路召回：关键词、向量和知识图谱（沿 wiki 链接关系扩展），三路融合后取 topK，再解析各自的父级 wiki。',
+    input: '查询语句 + topK + 路线', output: '带命中路线与得分的 wikiNotes',
+    steps: [
+      { label: '三路并行召回', detail: 'FTS 关键词、向量近邻、图谱 1 跳扩展', state: 'done' },
+      { label: '融合与截断', detail: '按融合分数排序取 topK，逐条标明是哪一路命中的', state: 'done' },
+      { label: '回溯父级 wiki', detail: '每条 wikiNote 通过 wikiId 解析回权威卡片', state: 'done' },
+    ],
+    status: 'live', statusNote: '三路召回与召回测试（含命中切片、得分、路线）都在知识库 → 召回重排里可跑。',
+icon: Search, lane: 'knowledge', tab: 'knowledge', knowledgeTab: 'recall',
+  },
+  context: {
+    title: '重排', subtitle: 'BERT cross-encoder · topN 上下文',
+    detail: '对候选 wikiNotes 做 BERT cross-encoder 精排，取 topN 连同 wiki 与关系图组成 Agent 可消费的上下文包。',
+    input: 'topK 条候选 wikiNotes', output: '注入 Runtime 的 Context Pack',
+    steps: [
+      { label: 'cross-encoder 精排', detail: 'query 与候选逐对打分，按 rerank 分数重排', state: 'done' },
+      { label: '降级不造假', detail: '模型或 worker 不可用时按融合分数排序并显式给出警告', state: 'done' },
+      { label: '展开上下文包', detail: '取 topN，连同 wiki 卡片与 1 跳关系图一起注入', state: 'done' },
+    ],
+    status: 'live', statusNote: '重排已实现（provider 可关）；不可用时降级为融合分数并返回警告，而不是伪造分数。它和召回在知识库 → 召回重排同一栏里（同一次运行，不切栏）。',
+icon: Layers3, lane: 'knowledge', tab: 'knowledge', knowledgeTab: 'recall',
+  },
+
+  interaction: {
+    title: '用户与 Agent 交互', shortTitle: '用户交互', subtitle: '对话、分析、使用功能的全过程',
+    detail: '记录用户做了什么、采用了什么结果，以及对分析结果的反馈，为自进化闭环提供输入。',
+    input: '每一轮的意图记录与工具调用', output: '可回溯的交互审计流',
+    steps: [
+      { label: '意图审计流', detail: '每轮一条 intent 记录，只标注不拦截', state: 'done' },
+      { label: '结果采纳与反馈', detail: '用户是否采用了结果、事后评价还没采集', state: 'todo' },
+    ],
+    status: 'partial', statusNote: '意图记录已经是一条真实的审计流；「结果是否被采用」这类反馈还没有采集入口。',
+icon: UserRound, lane: 'evolution', tab: 'memory',
+  },
+  'episodic-memory': {
+    title: '情节记忆', subtitle: '用户做了什么 / 对什么事的反应',
+    detail: '记录一次次任务、选择、反馈和结果评价，保留时间、会话和来源，用于理解用户偏好与上下文。',
+    input: '交互审计流', output: '带时间与会话的情节条目',
+    steps: [
+      { label: '采集', detail: '从交互审计流提取任务、选择、反馈', state: 'todo' },
+      { label: '归纳', detail: '按会话聚合为「做过什么」的条目', state: 'todo' },
+    ],
+    status: 'planned', statusNote: '还没有情节记忆的采集与归纳管线；记忆 Tab 上标的就是「示意」，不展示编造的数字。',
+icon: FileText, lane: 'evolution', tab: 'memory',
+  },
+  'procedural-memory': {
+    title: '操作记忆', subtitle: '用户常用操作 → Skill',
+    detail: '从重复操作中提取稳定步骤、参数和工具组合，经过审核后沉淀为可复用 Skill。',
+    input: '重复出现的操作序列', output: '候选 Skill',
+    steps: [
+      { label: '提取候选', detail: '从重复操作里归纳步骤、参数与工具组合', state: 'todo' },
+      { label: '审核后入库', detail: '进入审核队列，通过后写入 Skill Registry', state: 'todo' },
+    ],
+    status: 'planned', statusNote: '本次实测中，本次实测中还没有 Skill 提取与注册表写入的实现。',
+icon: Share2, lane: 'evolution', tab: 'memory',
+  },
+  'memory-quality': {
+    title: '记忆整理与质量检查', shortTitle: '记忆质量检查', subtitle: '去重、归纳、评估 / 过滤低质量内容',
+    detail: '对记忆进行去重、归纳、敏感信息检查和质量评估；涉及写入知识库或 Skill 的变更进入审核队列。',
+    input: '情节记忆 + 候选 Skill', output: '通过质检的变更',
+    steps: [
+      { label: '去重与归纳', detail: '同一件事的多条记录合并', state: 'todo' },
+      { label: '质量与敏感检查', detail: '低质量与敏感内容过滤，变更进入审核队列', state: 'todo' },
+    ],
+    status: 'planned', statusNote: '质量门还没有实现，只有卡片 schema 的三层校验是真实在跑的质检。',
+icon: ClipboardCheck, lane: 'evolution', tab: 'memory',
+  },
+  'daily-update': {
+    title: '每日更新知识库 / Skill', shortTitle: '每日更新', subtitle: '沉淀高价值经验，更新知识与 Skill',
+    detail: '每天按计划把确认后的情节记忆写入知识库、把操作记忆写入 Skill Registry，并生成版本记录。',
+    input: '通过质检的变更', output: '带版本记录的每日更新批次',
+    steps: [
+      { label: '批量写入', detail: '按计划把确认后的内容写进知识库与 Skill Registry', state: 'todo' },
+      { label: '版本与回滚', detail: '每批留版本记录，可回滚', state: 'todo' },
+    ],
+    status: 'planned', statusNote: '还没有定时任务；知识库本身的增量编译已经有了，但「每日自动跑一次」还没接。',
+icon: Clock3, lane: 'evolution', tab: 'memory',
+  },
+  'funded-value': {
+    title: '资金化', subtitle: '知识资产 → 可计量价值',
+    detail: '把可复用知识、Skill 和数据能力转化为可计量的业务价值入口，例如服务化、效率收益、指标改善与资产目录。',
+    input: '沉淀下来的知识与 Skill', output: '可计量的价值入口',
+    steps: [{ label: '价值候选', detail: '哪些知识与 Skill 值得被复用和计量的口径还没定', state: 'todo' }],
+    status: 'planned', statusNote: '产品目标，未实现；图上保留它是为了让「这条闭环最后要产出什么」可见。',
+icon: Gauge, lane: 'evolution',
+  },
+}
+
+/** 节点上的一条计数：`label` + 值。 */
+export interface NodeMetric { label: string; value: string }
+
+/** `/knowledge/stats` 的响应形状。节点指标与面板都是它的投影。 */
+export interface KnowledgeStats {
+  /** 知识树的段 → 文件数（0032 起**不含记忆**，记忆读 `memoryFiles`）。 */
+  layout?: Record<string, number>
+  /** 记忆段的真实位置（`<agentRoot>/memory/<库 id>`）与文件数（0032）。 */
+  memoryRoot?: string
+  memoryFiles?: number
+  sourceCount?: number
+  /** Wiki cards under `02_wiki` (the API calls this field `cards`). */
+  cards?: number
+  units?: number
+  notes?: number
+  graphNodes?: number
+  graphEdges?: number
+  buildVersion?: number
+  builtAt?: string
+  /** 已纳入增量指纹的卡片数 / 记忆段下的卡片版本快照数。 */
+  trackedCards?: number
+  cardVersions?: number
+  lastBuild?: {
+    only?: string
+    incremental?: boolean
+    skipped?: boolean
+    cardsReused?: number
+    cardsRecompiled?: number
+    cardsAdded?: number
+    cardsRemoved?: number
+    notesReused?: number
+    notesRecompiled?: number
+    /** Pass 0 · 候选抽取 + 归一的诚实计数（0028）。 */
+    candidatesExtracted?: number
+    candidatesRejected?: number
+    cardsCreated?: number
+    cardsMerged?: number
+    relationsExtracted?: number
+    relationsDropped?: number
+    sourcesExtracted?: number
+    sourcesSkipped?: number
+  } | null
+  lastCompileRunId?: string
+  recallTopK?: number
+  recallMode?: string
+  contextTopN?: number
+  rerankProvider?: string
+  rerankModel?: string
+  embeddingProvider?: string
+  embeddingModel?: string
+  embeddingDimension?: number
+  embeddingDevice?: string
+  vectorCount?: number
+  vectorQuantization?: string
+  embeddingStatus?: string
+  searchBackend?: string
+}
+
+/** SourceRaw 计数有两个来源：`stats.sourceCount` 与磁盘布局 `01_source_truth`。 */
+export function sourceCountOf(stats: KnowledgeStats): number {
+  return stats.sourceCount ?? Number(stats.layout?.['01_source_truth'] ?? 0)
+}
+
+/** wikiNotes 计数在接口里有 `notes` / `units` 两个别名。 */
+export function noteCountOf(stats: KnowledgeStats): number {
+  return stats.notes ?? stats.units ?? 0
+}
+
+/**
+ * 记忆段的落盘文件数：记忆相关的几个节点共用它。
+ *
+ * 0032 起读 `memoryFiles` 而不是 `layout['04_memory']` —— 记忆已经不在知识树里，
+ * `layout` 只装知识树的段。**读旧字段会静默变成 0**（段名不存在），而「0 个文件」
+ * 看起来像一个合理的数字，所以这里换字段的同时也换了标签文案。
+ */
+export function memoryCountOf(stats: KnowledgeStats): number {
+  return Number(stats.memoryFiles ?? 0)
+}
+
+/**
+ * 节点指标：真实计数只在这里派生一次，图上的节点卡片与右侧逻辑面板读的是同一个数组。
+ *
+ * 不给没有数据来源的节点编数字。宿主节点（对话 / Runtime / 回答 / Table）返回空数组，
+ * 卡片上就只是一句说明 —— 这比一个假的「0」诚实。
+ */
+export function nodeMetrics(id: NodeId, stats: KnowledgeStats, version: number): NodeMetric[] {
+  switch (id) {
+    case 'source-raw':
+      return [
+        { label: 'SourceRaw', value: String(sourceCountOf(stats)) },
+        { label: '待编译', value: sourceCountOf(stats) > 0 && version === 0 ? '是' : '否' },
+      ]
+    case 'compile':
+      return [
+        { label: 'wiki 卡片', value: String(stats.cards ?? 0) },
+        { label: 'wikiNotes', value: String(noteCountOf(stats)) },
+      ]
+    case 'build':
+      return [
+        { label: '向量', value: String(stats.vectorCount ?? 0) },
+        { label: '图谱', value: `${stats.graphNodes ?? 0} / ${stats.graphEdges ?? 0}` },
+        { label: '版本', value: version > 0 ? `v${version}` : '未构建' },
+      ]
+    case 'runtime':
+      return [
+        { label: '索引', value: version > 0 ? `v${version}` : '未构建' },
+        { label: '检索', value: stats.searchBackend === 'hybrid' ? 'Hybrid' : 'FTS fallback' },
+      ]
+    case 'recall':
+      return [
+        { label: 'topK', value: String(stats.recallTopK ?? 10) },
+        { label: '默认路线', value: stats.recallMode ?? 'hybrid' },
+      ]
+    case 'context':
+      return [
+        { label: 'topN', value: String(stats.contextTopN ?? 5) },
+        { label: 'rerank', value: stats.rerankProvider === 'none' ? '关闭' : stats.rerankProvider ?? 'bert-python' },
+      ]
+    case 'interaction':
+      return [{ label: 'memory/', value: `${memoryCountOf(stats)} 文件` }]
+    case 'episodic-memory':
+    case 'procedural-memory':
+    case 'memory-quality':
+    case 'daily-update':
+      return [
+        { label: 'memory/', value: `${memoryCountOf(stats)} 文件` },
+        { label: '卡片版本', value: String(stats.cardVersions ?? 0) },
+      ]
+    default:
+      return []
+  }
+}
+
+/** 一次算完整张图的节点指标（供图上一次性取值）。 */
+export function metricsByNode(stats: KnowledgeStats, version: number): Partial<Record<NodeId, NodeMetric[]>> {
+  const map: Partial<Record<NodeId, NodeMetric[]>> = {}
+  for (const id of NODE_ORDER) {
+    const rows = nodeMetrics(id, stats, version)
+    if (rows.length > 0) map[id] = rows
+  }
+  return map
+}
+
+/** 节点在图上出现的顺序：按链路，再按链内阅读顺序。它就是键盘可达列表的顺序。 */
+export const NODE_ORDER: NodeId[] = [
+  'conversation', 'intent', 'runtime', 'answer', 'data-sheet', 'data-notebook',
+  'source-raw', 'compile', 'build', 'recall', 'context',
+  'interaction', 'episodic-memory', 'procedural-memory', 'memory-quality', 'daily-update', 'funded-value',
+]
+
+/** 只在面板里出现、不占图上格子的节点（0025 起 Table / Notebook 已上图，这里保留给未来）。 */
+export const DERIVED_NODES: NodeId[] = []
+
+/** 某个节点归属的链路定义；找不到（例如未来新增节点漏填 lane）时返回 null 而不是猜。 */
+export function laneOf(id: NodeId): LaneMeta | null {
+  return NODE_LANES.find(lane => lane.id === NODE_META[id].lane) ?? null
+}
+
+/** 「跳转到配置」按钮的文案：跳不到就说清为什么，而不是给一个点不动的按钮。 */
+export function jumpTargetOf(id: NodeId): { tab: PanelTab; knowledgeTab?: KnowledgeTab } | null {
+  const meta = NODE_META[id]
+  if (!meta.tab) return null
+  return { tab: meta.tab, ...(meta.knowledgeTab ? { knowledgeTab: meta.knowledgeTab } : {}) }
+}
+
+/** 「未实现」的节点集合：概览与面板据此统一措辞。 */
+export function unimplementedNodes(): NodeId[] {
+  return NODE_ORDER.filter(id => NODE_META[id].status === 'planned')
+}

package/src/client/attribution/AttributionGraph.tsx

@@ -0,0 +1,104 @@
+import { Graph } from '@antv/g6'
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import { buildGraphOptions, seedPositions, toGraphData, type GraphLayout, type StageMode } from './graph-options.ts'
+import { cn } from '@tita-data-agent/ui/components'
+import type { AttributionGraphData } from './model.ts'
+
+export interface AttributionGraphProps {
+  data: AttributionGraphData
+  /** 空区节点 id：有假设、无检查。由调用方算好传入，画布不重复推导。 */
+  gapIds: ReadonlySet<string>
+  /**
+   * 布局方向。**它随视图模式变**，不是用户偏好：
+   * 承载面板的右侧边栏只有 380px（宿主 `width:380px`），所以布局的长宽比必须
+   * 配合视口 —— 全景用 LR（竖长，贴住竖屏视口），聚焦用 TB（紧凑，让 7 个节点
+   * 能按接近 1:1 渲染而不是被压成一半）。
+   */
+  rankdir: 'LR' | 'TB'
+  /** `force` 浮动节点（默认）；`layered` 分层 DAG。 */
+  layout: GraphLayout
+  /** 视口参数档位：面板内 / 全屏。决定缩放区间与留白。 */
+  mode: StageMode
+  selectedId?: string
+  onSelect: (id: string) => void
+  className?: string
+}
+
+/**
+ * G6 v5 画布。
+ *
+ * **它铺满父容器，自己不带高度。** 尺寸由父级用 CSS 决定（`absolute inset-0` 或
+ * 普通 `h-full`），画布只负责把 `clientWidth/clientHeight` 读出来 —— 这样「图谱占满
+ * 整个内容区」是布局层的事，画布不需要知道「面板有多高」这种知识，全屏切换也就
+ * 只是父容器换了个尺寸，画布跟着 ResizeObserver 走。
+ *
+ * 实例策略：**在布局方向、档位或数据变化时重建 Graph，只有选中态变化时才走
+ * `setElementState`**。重建一个 20 多节点的图只要几十毫秒，而增量同步布局、
+ * 样式、标签的边界情况（G6 会缓存节点位置与 state）远比一次重建更容易出错 ——
+ * 这个取舍随图上到几千节点才需要反过来。
+ */
+export function AttributionGraph({ data, gapIds, rankdir, layout, mode, selectedId, onSelect, className }: AttributionGraphProps): ReactNode {
+  const host = useRef<HTMLDivElement>(null)
+  const graphRef = useRef<Graph | null>(null)
+  const selectRef = useRef(onSelect)
+  selectRef.current = onSelect
+  const dataRef = useRef(data)
+  dataRef.current = data
+  // 重建之后选中态要重新贴上去：新节点上没有任何 state，只靠 selectedId 的
+  // 变化触发不了那个 effect。
+  const [renderToken, setRenderToken] = useState(0)
+
+  useEffect(() => {
+    const el = host.current
+    if (!el) return
+    const measure = (): { width: number; height: number } => ({
+      // 兜底尺寸：容器还没被布局出来时（首帧、或宿主面板宽度为 0）先给一个能画的值，
+      // 免得 G6 拿到 0 之后整块空白。
+      width: el.clientWidth || 348,
+      height: el.clientHeight || 360,
+    })
+    const graph = new Graph({
+      ...buildGraphOptions(measure(), layout, rankdir, mode),
+      container: el,
+    })
+    graphRef.current = graph
+    graph.on('node:click', event => {
+      // G6 的 IEvent 是联合类型，取 id 需要一次窄化；断言限制在这一行内。
+      const id = (event as { target?: { id?: string } }).target?.id
+      if (id) selectRef.current(id)
+    })
+    const size = measure()
+    // 只有力导向才需要喂初始位置：分层布局的坐标由 dagre 算，喂了也会被覆盖。
+    const positions = layout === 'force' ? seedPositions(data, size.width, size.height) : undefined
+    graph.setData(toGraphData(data, { gapIds, ...(positions ? { positions } : {}) }))
+    void graph.render().then(() => setRenderToken(token => token + 1))
+
+    // 宿主面板宽度可被用户拖动，全屏切换也会改变尺寸，画布必须跟着走，
+    // 否则会留下一块空白或裁掉右侧。
+    const observed = new ResizeObserver(() => {
+      const next = measure()
+      if (next.width <= 0 || next.height <= 0) return
+      graph.setSize(next.width, next.height)
+      void graph.fitView()
+    })
+    observed.observe(el)
+    return () => {
+      observed.disconnect()
+      graph.destroy()
+      graphRef.current = null
+    }
+  }, [data, gapIds, rankdir, layout, mode])
+
+  useEffect(() => {
+    const graph = graphRef.current
+    if (!graph || !selectedId) return
+    // 选中节点可能被筛选掉了：G6 的 `setElementState` 对未知 id 是**抛异常**，
+    // 不是静默忽略（`data.getElementType` 里 `throw new Error`）。所以先确认它还在图上。
+    if (!dataRef.current.nodes.some(node => node.id === selectedId)) return
+    void graph.setElementState(selectedId, ['selected'])
+    // 上一个选中节点必须显式取消，否则连着点三个节点会留下三个蓝色描边。
+    return () => { void graph.setElementState(selectedId, []) }
+  }, [selectedId, renderToken])
+
+  return <div ref={host} className={cn('h-full w-full overflow-hidden bg-tita-surface', className)} />
+}