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

package/src/client/attribution/model.ts

@@ -0,0 +1,462 @@
+import { ZOMBIE_EDGE_DAYS } from '../../diagnosis/types.js'
+import {
+  PROBLEM_CLASSES, PROBLEM_CLASS_LABEL, problemClassIds, problemSubclassOf,
+} from '../../diagnosis/problem-classes.js'
+import type { ProblemClassId } from '../../diagnosis/problem-classes.js'
+import type {
+  AttributionEdge, AttributionEdgeKind, AttributionGraphData, AttributionNode, AttributionNodeKind,
+  AttributionStats, FailureMode, NodeLayer,
+} from '../../diagnosis/types.js'
+
+export { ZOMBIE_EDGE_DAYS, PROBLEM_CLASSES, PROBLEM_CLASS_LABEL, problemClassIds, problemSubclassOf }
+export type {
+  AttributionEdge, AttributionGraphData, AttributionNode, AttributionNodeKind,
+  AttributionEdgeKind, AttributionStats, FailureMode, NodeLayer,
+} from '../../diagnosis/types.js'
+export type { ProblemClassId, ProblemSubclassSpec } from '../../diagnosis/problem-classes.js'
+
+/**
+ * 智能归因图谱的**展示层计算**：调色、尺寸映射、空区与僵尸边判定、筛选、排序。
+ *
+ * 领域模型（节点 / 边 / 图的形状）已经搬到 `src/diagnosis/types.ts` —— 宿主也要读写
+ * 同一套结构，视图只是它的消费者。这里留下的是「只有画布才关心」的部分。
+ */
+
+/** 层 → 视觉基色（对应 styles.css 的 `--tita-*` 令牌）。 */
+export const LAYER_TONES: Record<NodeLayer, 'blue' | 'violet' | 'amber'> = {
+  type: 'violet',
+  reference: 'blue',
+  instance: 'amber',
+}
+
+/**
+ * 失败模式 → 颜色。分类在图谱视图里是**着色**而不是分区，所以它只影响一眼扫过的
+ * 分组感，不影响节点位置 —— 位置由布局按边的方向决定。
+ */
+export const FAILURE_MODE_STYLE: Record<FailureMode, { label: string; fill: string; stroke: string; text: string }> = {
+  'upstream-missing': { label: '上游未产出', fill: '#eef4ff', stroke: '#2563eb', text: '#1d4ed8' },
+  'spec-change': { label: '口径变更', fill: '#f3f0ff', stroke: '#6b54cf', text: '#5b45be' },
+  'data-processing': { label: '数据处理', fill: '#eafaf2', stroke: '#12875f', text: '#0f6b4d' },
+  consumption: { label: '消费与展示', fill: '#fff7ea', stroke: '#b96d14', text: '#96580f' },
+  permission: { label: '权限与过滤', fill: '#fdecea', stroke: '#b42318', text: '#98200f' },
+}
+
+/**
+ * 界面里的固定顺序：与 §4.5 的判断顺序一致，不随数据出现顺序抖动。
+ *
+ * **问题大类刻意不给配色。** 它和失败模式是两根轴，而画布上的颜色通道只有一条 ——
+ * 失败模式已经占用了它（假设节点的填充色）。再给问题大类一套颜色，会出现两件事：
+ * 同一张图上「蓝」既可能指「偏差」又可能指「上游未产出」；而现象节点本来是琥珀色胶囊，
+ * 再染一层色就没人认得出它是现象了。
+ *
+ * 所以问题大类走**文字通道**：现象节点下方挂一个「缺失 · 全量为 0」的徽标，筛选与图例
+ * 用中性 chip，靠标签区分。这也是「怎么区分哪些是问题」的正解 —— 问题侧不是另一种颜色，
+ * 它是**另一个维度**，在图例里必须与原因侧分开成组。
+ */
+export const PROBLEM_CLASS_ORDER = problemClassIds()
+
+/** 现象节点上的分类徽标文案：「缺失 · 全量为 0」。没分类就返回 undefined。 */
+export function problemBadgeOf(node: AttributionNode): string | undefined {
+  if (!node.problemClass) return undefined
+  const subclass = problemSubclassOf(node.problemSubclass)?.label
+  const major = PROBLEM_CLASS_LABEL[node.problemClass]
+  return subclass ? `${major} · ${subclass}` : major
+}
+
+/** 每个大类下各有几个现象 —— 筛选 chip 上直接标出来，避免点出一个空图。 */
+export function symptomCountByProblemClass(nodes: AttributionNode[]): Record<ProblemClassId, number> {
+  const counts = Object.fromEntries(PROBLEM_CLASS_ORDER.map(id => [id, 0])) as Record<ProblemClassId, number>
+  for (const node of nodes) {
+    if (node.kind === 'symptom' && node.problemClass) counts[node.problemClass] += 1
+  }
+  return counts
+}
+
+/** 无失败模式的节点（现象、资产、检查）用中性色。 */
+export const NEUTRAL_STYLE = { fill: '#ffffff', stroke: '#d6dce6', text: '#748091' }
+
+export const NODE_KIND_LABEL: Record<AttributionNodeKind, string> = {
+  symptom: '现象',
+  hypothesis: '假设',
+  check: '检查',
+  'failure-mode': '失败模式',
+  asset: '资产',
+  case: '案例',
+  evidence: '证据',
+  cause: '根因',
+  unknown: '未归类',
+}
+
+/**
+ * 会出现在「类型」筛选里的节点类型。
+ *
+ * 只列**会被筛**的类型：证据 / 根因 / 案例是实例层的附属，默认就折叠着，
+ * 把它们列进筛选器只会让用户点出一个空图。这份名单是模型事实（哪些类型值得筛），
+ * 不是界面偏好，所以放在模型层 —— 界面层两个组件（工具条、筛选条）都要用它。
+ */
+export const FILTERABLE_KINDS: AttributionNodeKind[] = ['symptom', 'hypothesis', 'check', 'asset', 'failure-mode']
+
+/**
+ * 节点尺寸：假设节点按复用次数放大，其余按类型给固定宽高。
+ *
+ * 用面积感而不是线性放大 —— 复用次数差 10 倍时，线性尺寸会让最大的节点把
+ * 版面撑爆。这里取 sqrt 并夹在 [46, 96]。
+ *
+ * 返回 `[宽, 高]`：假设是圆（宽高相等），其余是胶囊，宽度要容得下标题。
+ */
+export function nodeBoxOf(node: AttributionNode): [number, number] {
+  if (node.kind === 'hypothesis') {
+    const reuse = Math.max(0, node.reuseCount ?? 0)
+    const size = Math.round(Math.min(96, Math.max(46, 24 + Math.sqrt(reuse) * 20)))
+    return [size, size]
+  }
+  if (node.kind === 'symptom') return [150, 44]
+  if (node.kind === 'check') return [156, 38]
+  if (node.kind === 'asset') return [132, 36]
+  if (node.kind === 'failure-mode') return [104, 30]
+  if (node.kind === 'case') return [184, 38]
+  return [150, 36]
+}
+
+/** 只有假设画成圆：圆没有方向感，正适合「一个机制候选」这种无内部结构的节点。 */
+export function nodeShapeOf(node: AttributionNode): 'circle' | 'rect' {
+  return node.kind === 'hypothesis' ? 'circle' : 'rect'
+}
+
+/** 节点的取色：假设跟着失败模式走，其余走层色。 */
+export function nodeStyleOf(node: AttributionNode): { fill: string; stroke: string; text: string } {
+  if (node.failureMode) return FAILURE_MODE_STYLE[node.failureMode]
+  if (node.layer === 'reference') return { fill: '#eef4ff', stroke: '#9ec2ff', text: '#1d4ed8' }
+  if (node.kind === 'symptom') return { fill: '#fff7ea', stroke: '#b96d14', text: '#96580f' }
+  if (node.kind === 'check') return { fill: '#f5f1ff', stroke: '#c9b8ff', text: '#5b45be' }
+  return NEUTRAL_STYLE
+}
+
+/**
+ * 空区判定：一个假设如果没有任何 `verified_by` 出去的检查，它就是空区。
+ *
+ * 这是图谱视图存在的首要理由 —— 排查视图看不到这个，它只在「我要完善这张图」
+ * 的时候才可见。
+ */
+export function gapHypothesisIds(data: AttributionGraphData): string[] {
+  const hasCheck = new Set(
+    data.edges.filter(edge => edge.kind === 'verified_by').map(edge => edge.source),
+  )
+  return data.nodes
+    .filter(node => node.kind === 'hypothesis' && !hasCheck.has(node.id))
+    .map(node => node.id)
+}
+
+/** 僵尸边：90 天未走过的可能性边。它就该被剪掉，但剪之前先让人看见。 */
+export function zombieEdgeIds(data: AttributionGraphData): string[] {
+  return data.edges.filter(isZombieEdge).map(edge => edge.id)
+}
+
+export function isZombieEdge(edge: AttributionEdge): boolean {
+  return edge.kind === 'may_be_caused_by' && (edge.staleDays ?? 0) > ZOMBIE_EDGE_DAYS
+}
+
+export function summarize(data: AttributionGraphData): AttributionStats {
+  const byLayer = (layer: NodeLayer): number => data.nodes.filter(node => node.layer === layer).length
+  const reuseTotal = data.nodes.reduce((sum, node) => sum + (node.reuseCount ?? 0), 0)
+  return {
+    typeNodes: byLayer('type'),
+    referenceNodes: byLayer('reference'),
+    instanceNodes: byLayer('instance'),
+    reuseTotal,
+    symptoms: data.nodes.filter(node => node.kind === 'symptom').length,
+    problemClasses: new Set(
+      data.nodes.filter(node => node.kind === 'symptom' && node.problemClass).map(node => node.problemClass),
+    ).size,
+    gaps: gapHypothesisIds(data).length,
+    zombies: zombieEdgeIds(data).length,
+  }
+}
+
+/** 默认只渲染类型层 + 引用层：实例层是每次排查线性增长的，展开它会淹掉版面。 */
+export function visibleNodes(data: AttributionGraphData, includeInstance = false): AttributionNode[] {
+  const idSet = new Set(data.nodes.map(node => node.id))
+  const kept = includeInstance ? data.nodes : data.nodes.filter(node => node.layer !== 'instance')
+  // 只保留两端都在可见集里的边，否则 G6 会因为找不到 source/target 而整条图报错。
+  return kept.filter(node => idSet.has(node.id))
+}
+
+export function visibleEdges(data: AttributionGraphData, nodes: AttributionNode[]): AttributionEdge[] {
+  const ids = new Set(nodes.map(node => node.id))
+  return data.edges.filter(edge => ids.has(edge.source) && ids.has(edge.target))
+}
+
+/**
+ * 以某个节点为中心取 N 跳邻域。
+ *
+ * 存在的理由是**尺寸**：承载这个面板的右侧边栏实测只有 380px 宽（宿主
+ * `dsh-client-ui-sidebar-right` 的 `width:380px`）。整张图缩进 380px 之后节点
+ * 只剩十几像素，标签必然不可读。所以面板里默认走邻域视图 —— 五到八个节点可以按
+ * 接近 1:1 的缩放渲染，而「全图」只用来回答形状问题（哪块密、哪里空）。
+ *
+ * 双向遍历：入边和出边都算邻居。只走出边会把「谁指向我」丢掉，而资产反向索引
+ * 恰恰是入边。
+ */
+export function neighborhoodOf(data: AttributionGraphData, centerId: string, hops = 1): AttributionGraphData {
+  return scopeOf(data, [centerId], hops)
+}
+
+/**
+ * 从一组种子节点出发、`hops` 跳内可达的**诱导子图**。
+ *
+ * 与 `neighborhoodOf` 是同一个算法（后者就是单种子的特例），抽出来是因为问题大类的
+ * 筛选需要「一组现象一起扩」——同一段逐跳 BFS 写两遍，迟早会在其中一处忘记
+ * 「新节点留给下一轮」这条规则。
+ */
+export function scopeOf(data: AttributionGraphData, seedIds: Iterable<string>, hops: number): AttributionGraphData {
+  const keep = new Set<string>(seedIds)
+  let frontier = new Set<string>(keep)
+  for (let step = 0; step < hops; step += 1) {
+    const next = new Set<string>()
+    for (const edge of data.edges) {
+      if (frontier.has(edge.source) && !keep.has(edge.target)) next.add(edge.target)
+      if (frontier.has(edge.target) && !keep.has(edge.source)) next.add(edge.source)
+    }
+    for (const id of next) keep.add(id)
+    // 必须把这一轮的新节点**留给下一轮**，而不是在同一轮里继续扩散 ——
+    // 否则「经过 S1 再走到 H2」会被算作 1 跳，H1 的邻域会一步吃下整张图。
+    frontier = next
+  }
+  return {
+    nodes: data.nodes.filter(node => keep.has(node.id)),
+    edges: data.edges.filter(edge => keep.has(edge.source) && keep.has(edge.target)),
+  }
+}
+
+/** 度数：邻域视图里用来把「连接最多的那个」选成默认焦点。 */
+export function degreeOf(data: AttributionGraphData, id: string): number {
+  return data.edges.reduce((sum, edge) => sum + (edge.source === id || edge.target === id ? 1 : 0), 0)
+}
+
+/** 默认焦点：类型层里度数最高的假设。没有假设时退化为第一个节点。 */
+export function defaultFocusId(data: AttributionGraphData): string | undefined {
+  const hypotheses = data.nodes.filter(node => node.kind === 'hypothesis')
+  if (hypotheses.length === 0) return data.nodes[0]?.id
+  return hypotheses
+    .slice()
+    .sort((a, b) => degreeOf(data, b.id) - degreeOf(data, a.id) || (b.reuseCount ?? 0) - (a.reuseCount ?? 0))[0]!.id
+}
+
+/** 排查视图里的一个候选假设。 */
+export interface AttributionCandidate {
+  hypothesis: AttributionNode
+  /** 同现象下的根因占比。分母由 `SAMPLE_SIZE` 说明，不写死在界面上。 */
+  prior: number
+  /** 该假设下成本最低检查的耗时；没有检查时为 undefined（= 走不下去）。 */
+  costMinutes?: number
+  /** 优先分 = 根因占比（百分点）÷ 检查成本。没有检查时记为 0。 */
+  score: number
+  checks: AttributionNode[]
+  gap: boolean
+}
+
+/**
+ * 近 30 天的同现象排查样本量，用作根因占比的分母。
+ *
+ * 与 0021 §4.4 的示例表一致（12 / 6 / 4 / 3 / 1 / 5 / 2，合计 33 次已归类 + 8 次未归类）。
+ */
+export const SAMPLE_SIZE = 41
+
+/**
+ * 从一个现象节点出发算候选假设集，并按优先分排序。
+ *
+ * 这是**排查视图和排序公式的唯一实现**：界面只负责把结果画出来，不再各自算一遍。
+ * `prior` 这里先用「全量复用次数 ÷ 样本量」充当 —— 等 M1 的写回链路落地后，
+ * 换成本次召回集内的占比并叠加 α 平滑（0021 §4.4），公式位置不变。
+ */
+export function candidatesOf(data: AttributionGraphData, symptomId: string): AttributionCandidate[] {
+  const checksByHypothesis = new Map<string, AttributionNode[]>()
+  for (const edge of data.edges) {
+    if (edge.kind !== 'verified_by') continue
+    const list = checksByHypothesis.get(edge.source) ?? []
+    const check = data.nodes.find(node => node.id === edge.target)
+    if (check) list.push(check)
+    checksByHypothesis.set(edge.source, list)
+  }
+
+  const hypothesisIds = new Set(
+    data.edges.filter(edge => edge.kind === 'may_be_caused_by' && edge.source === symptomId).map(edge => edge.target),
+  )
+
+  return data.nodes
+    .filter(node => hypothesisIds.has(node.id))
+    .map(hypothesis => {
+      const checks = (checksByHypothesis.get(hypothesis.id) ?? [])
+        .slice()
+        .sort((a, b) => (a.costMinutes ?? 0) - (b.costMinutes ?? 0))
+      const costMinutes = checks[0]?.costMinutes
+      const prior = (hypothesis.reuseCount ?? 0) / SAMPLE_SIZE
+      return {
+        hypothesis,
+        prior,
+        ...(costMinutes === undefined ? {} : { costMinutes }),
+        // ×100 让分数与 0021 §4.4 的示例表同刻度（占比按百分点算），界面上
+        // 显示的就是「29 分」而不是「0.29 分」。
+        score: costMinutes === undefined || costMinutes === 0 ? 0 : (prior * 100) / costMinutes,
+        checks,
+        gap: checks.length === 0,
+      }
+    })
+    // 先比分数，并列再比占比（0021 §4.4 的 tie-break）。
+    // 必须带容差：6/41/3 与 4/41/2 在数学上相等，在浮点里差 1 ULP ——
+    // 不加容差，「占比高者胜出」这条规则会在这种恰好并列的情况下静默失效。
+    .sort((a, b) => {
+      const gap = b.score - a.score
+      return Math.abs(gap) > 1e-9 ? gap : b.prior - a.prior
+    })
+}
+
+/** 筛选条件。空集合 = 不按该维度过滤。 */
+export interface GraphFilter {
+  query: string
+  kinds: ReadonlySet<AttributionNodeKind>
+  failureModes: ReadonlySet<FailureMode>
+  /**
+   * 问题大类。**它不是一条节点谓词，而是一个子图选择器。**
+   *
+   * 原因侧的节点（假设、检查、资产）身上根本没有问题大类，按「节点必须同时满足所有
+   * 激活条件」的通行做法去合取，选了任一问题大类之后整张图会被清空 —— 那是把
+   * 「分类」当成了「合法性检查」，而它其实是「范围」。所以它先按现象把范围收窄，
+   * 其余条件再在这个范围里生效（见 `filterGraph`）。
+   */
+  problemClasses: ReadonlySet<ProblemClassId>
+  /** 命中节点之外，是否把它们的 1 跳邻居也留下作为上下文。 */
+  includeNeighbors: boolean
+}
+
+export const EMPTY_FILTER: GraphFilter = {
+  query: '',
+  kinds: new Set(),
+  failureModes: new Set(),
+  problemClasses: new Set(),
+  includeNeighbors: true,
+}
+
+/**
+ * 按问题筛时要走几跳。
+ *
+ * **2 跳**，因为「现象 → 假设 → 检查」正好两跳：只走 1 跳会得到一个只有假设、没有检查的
+ * 半张图，而检查恰好是这张图唯一能动手的地方 —— 筛完却看不到该做什么，等于没筛。
+ */
+export const PROBLEM_SCOPE_HOPS = 2
+
+/**
+ * 按问题扩范围时**允许走哪几种边、朝哪个方向**。
+ *
+ * 这里不能用 `neighborhoodOf` 那种双向扩散。双向 2 跳从「日报 GMV 为 0」出发会经由共享的
+ * 假设走回**另外两个现象**，再各自铺开 —— 结果是「按问题筛」返回了 32/34 个节点，
+ * 等于什么都没筛。原因不在跳数，在方向：双向扩散回答的是「谁和我相连」，
+ * 而按问题筛要回答的是**「这个问题能顺着哪些假设查到什么」**。
+ *
+ * 所以这里逐边显式定义方向：产出性关系朝前走（现象→假设→检查 / 失败模式），
+ * 归属与索引关系朝后找（由假设找回它的资产，由现象找回属于它的案例）。
+ */
+export const PROBLEM_SCOPE_EDGES: Partial<Record<AttributionEdgeKind, 'forward' | 'backward'>> = {
+  may_be_caused_by: 'forward',
+  verified_by: 'forward',
+  categorized_as: 'forward',
+  indexed_from: 'backward',
+  instance_of: 'backward',
+}
+
+/**
+ * 一组现象能「查得到」的子图：它的假设、那些假设的检查与失败模式、背后的资产、
+ * 以及属于这些现象的案例。**不包含相邻现象** —— 那是 `neighborhoodOf` 的语义。
+ */
+export function problemScopeOf(data: AttributionGraphData, symptomIds: Iterable<string>): AttributionGraphData {
+  const keep = new Set<string>(symptomIds)
+  let frontier = new Set<string>(keep)
+  for (let step = 0; step < PROBLEM_SCOPE_HOPS; step += 1) {
+    const next = new Set<string>()
+    for (const edge of data.edges) {
+      const direction = PROBLEM_SCOPE_EDGES[edge.kind]
+      if (direction === undefined) continue
+      const from = direction === 'forward' ? edge.source : edge.target
+      const to = direction === 'forward' ? edge.target : edge.source
+      if (frontier.has(from) && !keep.has(to)) next.add(to)
+    }
+    for (const id of next) keep.add(id)
+    frontier = next
+  }
+  return {
+    nodes: data.nodes.filter(node => keep.has(node.id)),
+    edges: data.edges.filter(edge => keep.has(edge.source) && keep.has(edge.target)),
+  }
+}
+
+function matchesQuery(node: AttributionNode, query: string): boolean {
+  const text = `${node.id} ${node.title} ${node.summary ?? ''}`.toLocaleLowerCase()
+  return text.includes(query)
+}
+
+/**
+ * 图上的筛选。
+ *
+ * 只按「类型 / 失败模式 / 文本」三个维度过滤，**不新增一个「分类树」**：
+ * 0021 §4.3 已经定了分类是切面，所以这里也做成切面 —— 它可以多选、可以为空、
+ * 可以随时改回来看全图，而不像树的层级那样「选错就得往回退」。
+ *
+ * `includeNeighbors` 默认开：只留命中节点会让图散成孤点，边的语义也一起丢了。
+ * 留下来的是命中节点及其 1 跳邻居，边只在两端都留下时才保留。
+ */
+export function filterGraph(data: AttributionGraphData, filter: GraphFilter): AttributionGraphData {
+  const query = filter.query.trim().toLocaleLowerCase()
+
+  // 第一步：问题大类先把**范围**收窄成「命中现象 2 跳以内」的子图。
+  // 顺序很重要 —— 先收范围再套文本/类型/失败模式，语义才是「在这类问题里找」，
+  // 而不是「在整张图里找同时满足所有条件的节点」（后者永远是空集）。
+  const inScope = filter.problemClasses.size === 0
+    ? data
+    : problemScopeOf(
+      data,
+      data.nodes
+        .filter(node => node.kind === 'symptom' && node.problemClass !== undefined && filter.problemClasses.has(node.problemClass))
+        .map(node => node.id),
+    )
+
+  const noFilter = query === '' && filter.kinds.size === 0 && filter.failureModes.size === 0
+  if (noFilter) return inScope
+
+  const hits = new Set<string>()
+  for (const node of inScope.nodes) {
+    if (query !== '' && !matchesQuery(node, query)) continue
+    if (filter.kinds.size > 0 && !filter.kinds.has(node.kind)) continue
+    if (filter.failureModes.size > 0) {
+      // 失败模式是假设的属性；失败模式节点本身也要能被选出来。
+      const isModeNode = node.kind === 'failure-mode'
+      if (!isModeNode && (node.failureMode === undefined || !filter.failureModes.has(node.failureMode))) continue
+    }
+    hits.add(node.id)
+  }
+
+  const keep = filter.includeNeighbors ? neighborhoodIds(inScope, hits) : hits
+  return {
+    nodes: inScope.nodes.filter(node => keep.has(node.id)),
+    edges: inScope.edges.filter(edge => keep.has(edge.source) && keep.has(edge.target)),
+  }
+}
+
+/** 命中集合 + 每命中节点各自的 1 跳邻居。 */
+function neighborhoodIds(data: AttributionGraphData, seeds: ReadonlySet<string>): Set<string> {
+  const keep = new Set<string>(seeds)
+  for (const edge of data.edges) {
+    if (seeds.has(edge.source)) keep.add(edge.target)
+    if (seeds.has(edge.target)) keep.add(edge.source)
+  }
+  return keep
+}
+
+/** 筛选结果计数，用于把「筛掉了多少」显式告诉用户。 */
+export function countByKind(nodes: AttributionNode[]): Array<{ kind: AttributionNodeKind; count: number }> {
+  const counts = new Map<AttributionNodeKind, number>()
+  for (const node of nodes) counts.set(node.kind, (counts.get(node.kind) ?? 0) + 1)
+  return [...counts.entries()]
+    .map(([kind, count]) => ({ kind, count }))
+    .sort((a, b) => b.count - a.count)
+}
+

package/src/client/config-scope.ts

@@ -0,0 +1,119 @@
+/**
+ * 0.1.7 设置适配层：把**一个 entry 的 config 表单**投影成若干
+ * `SettingsScopeLike` 作用域。
+ *
+ * ## 为什么需要这一层
+ *
+ * 0.1.7 删掉了 `ctx.settingsScope.bind({ namespace })` 这套客户端设置 API，换成
+ * `ctx.configForms.get(entryId)`：**设置不再是按命名空间分的独立文档，而是一个
+ * 插件 entry 自己的 config**。本插件把三块设置合并进同一个 entry（`knowledge` /
+ * `intent` / `convert` 三个组），但下层的编辑器（`NodeSettings`、`KnowledgeBaseTab`
+ * …）是按「一个平铺的设置组」写的，它们读 `snapshot.value.recallTopK`、
+ * 写 `scope.set('recallTopK', 20)`。
+ *
+ * 让每个编辑器都知道「我这一组嵌在 entry config 的哪个键下面」会把这个细节漏进
+ * 十几处 UI 代码。这一层只做一次投影：值是组内切片，写操作把组名补成**路径前缀**
+ * （`set('recallTopK', 20)` → `{ op: 'set', path: ['knowledge', 'recallTopK'] }`），
+ * 于是上面的组件一行都不用改。
+ *
+ * ## 为什么用 `mutate` 而不是 `set`
+ *
+ * `ConfigForm.set(field, …)` 的契约是「**命名空间 section 里的标量字段**」——只认
+ * 顶层的键。分组之后的字段都在第二层，所以一律走按路径寻址的 `mutate`。`group`
+ * 省略时（`agent-preset-registry` 那条 DSH 自己的 entry）路径就只有字段名本身，
+ * 与 `set` 等价。
+ *
+ * @module
+ */
+
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { SettingsScopeLike, SettingsSnapshot } from './NodeSettings.tsx'
+
+/** `mutate` 接受的那组路径操作。 */
+type MutateOps = Parameters<ConfigForm<unknown>['mutate']>[0]
+
+/** 读一层对象成员；不是容器就是没有。 */
+function pick(container: unknown, key: string): unknown {
+  if (container === null || typeof container !== 'object') return undefined
+  return (container as Record<string, unknown>)[key]
+}
+
+/** 只保留有值的字段：`undefined` 与「字段不存在」在快照里不是一回事。 */
+function defined(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined))
+}
+
+/**
+ * 「宿主没给表单」时的快照。
+ *
+ * 模块级常量，**不是每次现造** —— 理由与下面的缓存相同：新的对象引用会让
+ * `useSyncExternalStore` 永远认为状态变了。（`NodeSettings.tsx` 里那个
+ * `UNAVAILABLE_SNAPSHOT` 是同一个理由。）
+ */
+const UNAVAILABLE: SettingsSnapshot = { status: 'unavailable', writable: false, mode: 'memory' }
+
+/**
+ * 把一个 entry 的 config 表单投影成某一组的设置作用域。
+ *
+ * @param form - `ctx.configForms.get(entryId)`；undefined 表示宿主没提供（退化成
+ *   `unavailable`，UI 显示「不可用」而不是崩）。
+ * @param group - entry config 里的组名。省略 = 整个 section。
+ */
+export function groupScope(
+  form: ConfigForm<Record<string, unknown>> | undefined,
+  group?: string,
+): SettingsScopeLike {
+  /** 组内切片；无组时就是整个 section。 */
+  const slice = <T>(container: unknown): T | undefined =>
+    group === undefined ? (container as T | undefined) : (pick(container, group) as T | undefined)
+  /** 字段名 → entry config 里的完整路径。 */
+  const pathOf = (field: string): string[] => (group === undefined ? [field] : [group, field])
+
+  /**
+   * 派生快照的缓存，键是**底层快照的引用**。
+   *
+   * `getSnapshot()` **必须**在底层没变时返回同一个对象：读它的是
+   * `useSyncExternalStore`（`NodeSettings.tsx` 的 `useScope`），而它的契约是
+   * 「快照引用在变化之前保持稳定」。每次现造一个对象 = 每次调用都「检测到变化」=
+   * 无限重渲染 → **Minified React error #185（Maximum update depth exceeded）**。
+   *
+   * 这个故障的表现极具误导性：`SlotErrorBoundary` 会接住它，把整个 tab 体换成
+   * `<div data-slot-error="sidebar.right.pane.tab">` —— 面板整片空白，而控制台里
+   * **没有一条来自本插件的错误**（渲染器那行 `slot entry crashed in '…'` 在首次挂载
+   * 时就打完了）。第一版漏了这层缓存，代价就是一次「打开 TitaAgent 什么都看不到」。
+   */
+  let lastSource: unknown
+  let lastDerived: SettingsSnapshot | undefined
+
+  return {
+    getSnapshot(): SettingsSnapshot {
+      if (!form) return UNAVAILABLE
+      const snapshot = form.getSnapshot()
+      // `ConfigForm` 承诺底层快照在变化前引用稳定，所以引用相等就等价于「没变化」。
+      if (lastDerived !== undefined && snapshot === lastSource) return lastDerived
+
+      const value = slice<Record<string, unknown>>(snapshot.value)
+      const user = slice<unknown>(snapshot.user)
+      lastSource = snapshot
+      lastDerived = {
+        status: snapshot.status,
+        ...defined({ value, user, writable: snapshot.writable, mode: snapshot.mode, revision: snapshot.revision }),
+      } as SettingsSnapshot
+      return lastDerived
+    },
+    subscribe(listener: () => void): () => void {
+      return form ? form.subscribe(listener) : () => undefined
+    },
+    async set(field: string, value: unknown): Promise<void> {
+      if (!form) return
+      // `value` 在这一层是 `unknown`（组件按自己的控件类型传），而线上协议的
+      // `JsonValue` 是这一层的上游约束。两者在这里必须对上：这一层不校验，交给
+      // 宿主的 schema 与 `SettingsForms.mutate` 去拒绝非法值。
+      await form.mutate([{ op: 'set', path: pathOf(field), value } as unknown as MutateOps[number]])
+    },
+    async unset(field: string): Promise<void> {
+      if (!form) return
+      await form.mutate([{ op: 'unset', path: pathOf(field) }])
+    },
+  }
+}