@fx-data/ai-diagnostics 0.1.20261026070913 → 0.1.20261107142011

package/content/knowledge/component/workflow.md

@@ -0,0 +1,23 @@
+# 组件 · 排查入口
+
+组件（图表）取数慢或失败时从这里下手。要判断的是：问题出在请求上下文、数据绑定、组件查询、关联的分析表、上游更新，还是引擎执行。概念看[概念](concepts.md)，入口和信号看[信号](signals.md)，能下什么结论看[结论](conclusions.md)，写查询看[查询](queries.md)。
+
+## 入手
+
+- 先分清是图表编辑时的预览、仪表板里的组件请求，还是仪表板以外的图表预览。仪表板组件预览入口按[来源判定](../common/signals.md#仪表板组件预览入口)确认；来自仪表板的，直接转到[仪表板知识](../dashboard/workflow.md)。用户只说“图表慢、超时”时，第一步就是做这个区分。
+- 记下组件、绑定表、筛选、联动和权限上下文、环境、时间窗，以及用户感觉到的耗时。用精确 ID、请求上下文和时间窗缩小候选执行，不要按最慢的 span 挑。
+- 主要看三件事：一次是不是触发了多个查询，或者带了复杂的筛选、联动、聚合、排序；trace 里耗时集中在哪个阶段；绑定分析表的资源版本或更新状态和这次有没有关系。
+- 慢或失败的引擎执行，可以看[引擎知识](../engine/workflow.md)；线索指向分析表或更新时，转到对应的域。
+
+## 常见现象与候选假设
+
+- **请求数量或计算量太大**：一个组件实际发了好几个查询；筛选、联动、权限上下文把查询放大了；高基数聚合、排序或 TopN 占了主要时间。数一下同一次动作发了多少查询，看看这次请求带了哪些筛选器和联动上下文。
+- **慢在绑定的分析表**：绑定表还在更新、更新失败或者结果是旧的；组件查询本身很轻，慢在读表或算表。用 `component.query.table_id` 或资源配置确认真实绑定，再核对更新时间、版本和当前 trace 的关系；对不上时间或版本，只能说相关或推测。
+
+## 易错点
+
+- 配置说明组件可能发起什么查询，trace 才说明这一次实际发了什么。
+- 仪表板 trace 里出现组件 span，不代表业务入口是组件预览，也不代表问题在组件配置。
+- 底层表正在更新、组件恰好变慢，这只是时间上相关，不够确认因果。
+- 只看到通用的引擎 span，确认不了是组件场景。
+- 没有完整的仪表板交互记录时，不要说已经还原了全部请求扩散。

package/content/knowledge/dashboard/README.md

@@ -0,0 +1,31 @@
+# 仪表板知识
+
+仪表板 2.0的筛选器候选值取数与组件计算。旧版仪表板不在覆盖范围内。
+
+## 槽位
+
+每个知识域都按同样的槽位组织。按要做的事选槽位，只读命中的章节。
+
+| 要做什么 | 读 | 包含 |
+|---|---|---|
+| 这类问题从哪里入手 | [workflow.md](workflow.md) | 仪表板排查入口：入手提示、组件取数先做对照、常见现象的候选假设、易错点 |
+| 弄清概念是什么、怎么关联 | [concepts.md](concepts.md) | 仪表板、筛选器、组件、筛选与联动的业务概念；调查关系 |
+| 认出入口，看懂 span、attribute、日志和字段 | [signals.md](signals.md) | 认出仪表板入口与来源：接口、attribute、筛选器与联动观测字段的含义 |
+| 看完日志和 trace，能下什么结论 | [conclusions.md](conclusions.md) | 各类材料能说明什么；调查时要记下的信息 |
+| 写查询、选取证路径 | [queries.md](queries.md) | SigNoZ 查询线索，以及按问题组织的取证例子（已有 trace、单独预览对照、筛选器名称与动态字段、资源发现、筛选树） |
+
+## 展开明细
+
+| 文件 | 何时读 | 内容 |
+|---|---|---|
+| [topics/component-comparison.md](topics/component-comparison.md) | 需要判断仪表板内组件和单独预览是否可比、成功是否成立时 | 组件计算对照怎么判断 |
+| [topics/dynamic-fields.md](topics/dynamic-fields.md) | 筛选器里有动态字段或参数、怀疑上游被重算时 | 动态字段覆盖与上游展开 |
+| [topics/name-binding.md](topics/name-binding.md) | 只有筛选器或字段 ID、需要还原名称和绑定关系时 | 名称与请求上下文的关联取证 |
+| [topics/filter-tree.md](topics/filter-tree.md) | 组件计算有多层过滤树、需要还原并展示完整树时 | 筛选树还原与交付 |
+
+## 关联
+
+- 相关知识域：[组件](../component/README.md)：图表编辑，以及仪表板以外的图表预览
+- 相关知识域：[分析表](../dataset/README.md)：组件绑定的查询表
+- 相关知识域：[引擎](../engine/README.md)：进入计算后的 Metric
+- 相关知识域：[通用](../common/README.md)：仪表板组件预览入口的来源判定

package/content/knowledge/dashboard/concepts.md

@@ -0,0 +1,26 @@
+# 仪表板 · 概念与关联
+
+回答“这是什么、彼此怎么关联”。
+
+## 业务概念
+
+- 仪表板包含组件和筛选器。
+- 仪表板性能调查只有两个一级取数场景：筛选器自身候选值取数、组件取数。首次加载、筛选值变化、参数变化和联动是触发组件取数的动作，不是第三类取数场景。
+- 筛选器取数用于计算当前筛选器有哪些候选值，只可能受其他筛选器的筛选影响。
+- 组件取数用于执行当前组件计算。影响因素不限于筛选器，至少包括组件自身的查询配置、绑定表与算子、普通筛选器条件、参数、权限、自动联动和组件间自定义联动。
+- 仪表板 2.0 不再使用 `valueLinkageMap` 表达联动。
+- `control` 是组件取数请求 payload 的字段。其中 `type=81` 映射为 `ComponentControl`，表示组件间过滤；它不能单独证明跨源。跨源需要比较当前组件绑定表、`value.tableId`、`filterCols` 和实际生成的过滤条件。
+- 用户选择筛选值后可能触发多个受影响组件重新取数。用户感知完成点是全部受影响组件刷新完成；筛选器自身的候选值取数不属于该计算集合，应作为独立筛选器取数问题分析。
+
+## 调查关系
+
+```text
+dashboard / reportId
+  → control option query, or component calculation
+  → component trigger: load / filter change / parameter change / linkage / refresh
+  → optionally related component calculations
+  → bound analysis tables
+  → current query or upstream update
+```
+
+调查应区分请求扩散、关键组件慢、筛选器候选值计算、上游表状态和 engine 执行，不能把“仪表板慢”当作单一后端请求。

package/content/knowledge/dashboard/conclusions.md

@@ -0,0 +1,21 @@
+# 仪表板 · 能下什么结论
+
+回答“手上的日志、trace 和 Metric 能说明什么、不能说明什么，结论能下到哪一步”。组件对照、动态字段、筛选器名称和筛选树等展开主题见 README 的“展开明细”。
+
+## 各类材料能说明什么
+
+默认先解释当前筛选器或组件计算，不把组件取数预设为筛选触发。只有明确存在同一筛选时，才在能对上同一筛选或可靠时间窗的范围内观察全部受影响组件，以验证筛选绑定位置、影响范围和用户感知完成点；只看到单个组件 trace 时，仍应说明无法证明完整 dashboard fan-out。
+
+本域不覆盖并发容量、并发退化或压测问题。这里的多个相关组件计算属于一次业务交互的影响集合，不等同于并发性能诊断。
+
+## 调查时保留
+
+优先保留用户现象、入口 route、request context、report/dashboard、筛选器和组件 ID、查询字段与计算类型、绑定表和完整关系路径、候选值来源表、筛选树、参数、权限、`linkage`、`ComponentControl`、关联请求、耗时和错误。先用这些信息形成“具体算了什么、复杂在哪里、哪里扩大了范围”的业务解释。默认按单个筛选器或组件请求解释；只有明确是筛选值变化后多个组件刷新时，才组织全部受影响组件，筛选器自身的候选值取数仍单独分析。
+
+对筛选绑定影响，优先寻找同组件、同查询形态、同一短时间窗内不携带目标筛选器的基线，比较请求耗时、`node_count`、`max_depth` 和 `table_paths`。只有耗时而输入或查询形态不可比时，不宣称差异全部由筛选器导致。
+
+### 核对配置影响范围
+
+“可靠交互窗内没有观察到其他组件请求”只限定本次观测范围。要确认配置上没有其他组件受影响，必须读取 仪表板 2.0 `relatedFields`/targets，并按目标画布 `instanceId` 判断；`componentRef`/组件资产 ID 可被多个实例复用，不能替代按实例确认的目标。Trace 当前也不直接记录 `MAIN/COMPONENT` 筛选阶段或完整 `controlId → target instanceId` 映射，因此仅凭 Trace 可以确认上游绑定造成额外路径，但“可下移到哪个阶段”仍需配置验证。
+
+配置读取配方仅适用于已经提供的脱敏配置或当前可用的只读配置能力：从 control 的 `relatedFields`/targets 建立 `controlId → target instanceId` 集合，分别记录 instanceId 与 componentRef，再解析每个目标的绑定字段和阶段。普通 tableId 对应 MAIN，组件目标绑定对应 COMPONENT；只有 targets 唯一且目标字段在 COMPONENT 阶段存在时，才能把“只影响当前组件”和具体下移位置写成已验证的配置建议。缺少任一关联时保持未知，不用运行时“没看到请求”补成配置事实，也不虚构读取接口。

package/content/knowledge/dashboard/queries.md

@@ -0,0 +1,69 @@
+# 仪表板 · 查询方法
+
+回答“怎样取证、怎样查询”。环境、时间、服务、上限和结果复用遵守[公共查询规则](../common/queries.md)；下面的例子说明查询意图，不规定命令顺序。
+
+## SigNoZ 查询线索
+
+- 从资源出发：在业务 `service.name` 下，用用户动作的时间，组合筛选器或组件入口、`reportId`、control/component ID 和 request context，只找触发动作附近的候选请求；没有共同交互 ID 或可靠时间边界时，不扩成整天的扫描。
+- 已有精确 trace 但默认详情缺业务 attribute 或被截断：复用 traceId、业务服务和时间窗，按下面的字段清单定向补缺的字段，结果按父子 span 合并，不要求属性都在 HTTP 根 span 上。
+- `reportId`/dashboardId 先找筛选器或仪表板组件预览入口，组件 ID 先找 `component.id`。用户给的是组件资产 ID 时，还要确认它和画布 `instanceId`/widgetId 的对应，一个资产可能在多个仪表板实例里。
+
+## 已有精确 trace
+
+按 `trace_id` 和已确认业务 `service.name` 取得本次入口、组件/筛选器和筛选树记录。必要业务记录包括 `previewComponent`、`FilterConditionsBuilder.build`、`data.component.buildControlContext`、`data.control.calculateOptions`、`data.control.engineExecute`，以及 `data.endpoint=design_control_data` 或有关筛选器/仪表板组件预览入口的 `http.route`。不要求每条记录同时有所有属性。
+
+```text
+trace_id = '<已确认trace>' AND service.name = '<业务服务>'
+```
+
+只选择当前判断需要的字段：
+
+- 关联和时间：`name`、`trace_id`、`span_id`、`parent_span_id`、`timestamp`、`duration_nano`；
+- 本次计算：`reportId`、`data.request_context`、`data.endpoint`、`http.route`、`component.id/type/query.table_id`；
+- 筛选器影响：`controls.ids/names/binding_info/raw_binding.table_ids/raw_binding.field_ids`、`controls.effect_count/input_count/effect_type_counts/valued_effect_count`，涉及参数时加 `controls.has_parameter/parameter_effect_count/parameter_ids/parameter_names/parameter_bindings`；
+- 筛选器自身：`control.id/name/type`、`control.option_source.table_ids/binding_info`、`control.context.ids/binding_info`；
+- 筛选树：`filter_conditions.root_table_id/node_count/path_node_count/max_depth/table_paths/tree_summary`，需要环路或共享校验时加 `cycle_path_count/cycle_paths`，动态字段问题加 `dynamic_field_count`；
+- 其他计算上下文：只有判断涉及联动、参数或权限时补对应 observation 字段。
+
+`/` 表示同一前缀下的多个字段。计数和深度是数值字段，`calculation_context.has_*` 是布尔字段，`fieldDataType` 按工具声明（如 `number`、`bool`）。节点多不代表过滤条件多，effect 数也不等于最终生效的筛选数。
+
+## 组件单独预览对照
+
+时间与查询预算只按[仪表板内外组件对照](../common/topics/baseline-comparison.md#仪表板内外组件对照)，候选与成功判定按[组件计算对照怎么判断](topics/component-comparison.md#组件计算对照怎么判断)。先确认当前记录形态再构造过滤，不将跨入口对照限制在同 `reportId`。
+
+| 当前材料 | 查询选择 | 需要拿回的记录 |
+|---|---|---|
+| 已有单独预览 trace | 直接复用其时间、业务服务和入口 | 请求身份、业务结果、task 与 Metric |
+| 组件身份可在 span 属性中识别 | 同服务、组件 ID 与单独预览的入口 | `name/trace_id/span_id`、请求上下文、查询表、结果状态及耗时 |
+| 图表编辑时未记录组件属性，首查为空 | 同窗口、服务与图表编辑入口，在 `body` 或已声明的请求属性中精确匹配组件 ID；必要时用查询表和用户/查询配置确认候选 | 从有限日志提取 `trace_id`、入口、请求中的组件/表和查询字段，再按 trace 精确读取 |
+
+请求 JSON 中的 `tableBean.id`、`componentId` 等不是天然可查询的顶层字段。已有日志响应中恢复这些键即可，不猜 `widgetId` attribute；数据表 ID 命中不能直接认定同组件。返回 `result.status`、任务终态或明确业务响应确认成功，不使用 HTTP 状态码代替。
+
+## 筛选器名称与动态字段
+
+先复用当前 trace 的属性和请求材料；名称尚缺而已有字段 ID 时，按[名称关联规则](topics/name-binding.md#名称与请求上下文的关联取证)搜索已有筛选器关系请求。下面是日志正文查询意图，不是新增业务调用：
+
+```text
+service.name = '<业务服务>'
+AND body CONTAINS '/v1/conf/widget/relations'
+AND body CONTAINS '<精确字段ID>'
+```
+
+在已确认的元数据窗口只取有限 `timestamp/body/trace_id/span_id`；如已给关系请求 trace，直接按该 trace 查，不再做正文发现。命中后从保存结果中提取 `controls[].fieldPosition` 的身份与名称，并核对 `widgets` 包含目标组件。多个字段尽量合并在同次查询；正文或请求属性中没有关联线索时保留缺口，不盲扫所有服务、所有字段或循环试探关键词。
+
+动态字段选项值、默认值和名称是不同信息。关系请求上报的 `name` 只补名称，`controls.names` 也可能只是筛选器键；不得由二者推断选择值。确认覆盖需要哪些记录、什么时候停止补查，以及 `type=73`、`unbound`、普通参数统计和正数才写入的计数字段，统一按[动态字段覆盖与上游展开](topics/dynamic-fields.md#动态字段覆盖与上游展开)处理。
+
+## 资源发现与影响范围
+
+| 当前缺口 | 查询范围与条件 | 如何继续 |
+|---|---|---|
+| 只有 report/dashboard | 已确认时间、服务与 report，有限候选业务入口 | 按操作选 trace，补该 trace 的业务记录 |
+| 只有 component/widget | 已确认时间、服务、组件 observation | 核对资产 ID 与画布实例，不能自动互换 |
+| 某筛选器影响哪些请求 | 短交互窗、service、report、`controls.ids` 和组件 observation | 提取有关 traceId，再读取各 trace 的筛选树 |
+| 精确筛选器条件为空，或仍缺同窗影响范围/对照 | 同 report 同服务同短窗降级一次 | 不同时扩大时间和移除服务，不要求筛选树 span 自带筛选器字段 |
+
+只有同 report、同组件、同查询表、在可靠短交互窗里、不带目标筛选器的请求才有较强的对照价值；查询指纹没核对时，参数、排序、聚合或数据范围的差异不能靠时间和身份匹配消掉。不默认拿最短的无筛选器请求和最长的有筛选器请求做原因对照。
+
+## 筛选树
+
+需要树结构时，按上方字段清单取得当前组件或操作的完整路径与 summary，不要求筛选树 span 自带筛选器字段。还原、校验、名称补齐和展示统一按[筛选树还原与交付](topics/filter-tree.md#筛选树还原与交付)执行；沿用本次请求父子范围，不再为展示重复取证。

package/content/knowledge/dashboard/signals.md

@@ -0,0 +1,76 @@
+# 仪表板 · 入口与信号
+
+回答“怎样认出入口，各个 span、attribute、日志和字段是什么意思”。
+
+## 场景识别
+
+已确认的入口和直接信号包括：
+
+- `POST /v1/design/control/data`：仪表板筛选器候选值取数；
+- `data.endpoint=design_control_data`；
+- `data.request_context=dashboard`；
+- `sense=dashboard-controlData`。
+
+筛选器候选值请求的 span 结构：
+
+```text
+POST /v1/design/control/data
+└─ dashboard.controlData
+   ├─ data.control.validateSourceTables   先校验来源表是否被标红
+   └─ data.control.calculateOptions       候选值计算
+      ├─ FilterConditionsBuilder.build    把其他筛选器带来的条件构建成筛选条件树
+      └─ data.control.engineExecute       引擎查询：QueryExecutor → execute
+```
+
+时间主要花在 `data.control.engineExecute`（引擎），它之前是准备输入表和筛选条件；进入引擎后按[引擎知识](../engine/README.md)解读。仪表板内组件计算的阶段 span 见[组件 · 组件计算的阶段](../component/signals.md#组件计算的阶段)，结果状态和失败类名见[取数结果与失败](../component/signals.md#取数结果与失败)。route 在 SigNoZ 里带部署上下文路径，见[识别方法](../common/signals.md#识别方法)。
+
+共享的 `POST /v2/external/widget/data` 按[仪表板组件预览的来源判定](../common/signals.md#仪表板组件预览入口)识别。确认属于仪表板后，组件计算全部由本场景调查。
+
+## 信号含义
+
+- `reportId`、`reportName`：仪表板或报表资源锚点；
+- `control.id`、`control.type`、筛选器上下文 attribute：标识本次候选值或筛选请求；
+- `control.option_source.table_ids`：候选值可能读取的表，可用于发现分析表关联；
+- `component.id`：仪表板内组件锚点，用于在仪表板模块内定位具体组件计算。
+
+仪表板内组件计算的 `previewComponent` 上，下面几个属性用来看这次请求带入了多少上下文：
+
+| 属性 | 含义 |
+|---|---|
+| `controls.effect_count`、`controls.valued_effect_count` | 本次请求带入的筛选器影响数，以及其中有取值的个数 |
+| `calculation_context.has_auto_linkage`、`has_custom_linkage`、`has_permission_context` | 是否带入自动联动、组件间自定义联动、数据权限 |
+| `component.linkage.depth` | 联动的层数 |
+| `component.query_count` | 这个组件一次请求里的查询个数 |
+
+筛选器数多不等于慢，要结合筛选树和引擎耗时判断。`controls.*`、`filter_conditions.*` 的完整字段和读法见[查询方法](queries.md)与[筛选树](topics/filter-tree.md)。
+
+### 筛选器候选值请求的属性
+
+`POST /v1/design/control/data` 的文本筛选器候选值请求，会在 span 上记录下面这些属性。
+
+| 属性 | 含义 |
+|---|---|
+| `control.query.mode` | 本次取候选值的方式：`page` 翻页（默认）、`keyword_search` 带关键字搜索、`select_all` 全选、`search_select_all` 搜索后全选 |
+| `control.query.unbounded` | 取数有没有上限；全选（`select_all`）没有上限 |
+| `control.query.fetch_limit` | 有上限时的取数上限；没有上限时不写 |
+| `control.query.output_rows` | 引擎实际返回的行数（含已选值）；等于 `fetch_limit` 时，候选值可能被上限截断 |
+| `control.option_source.distinct_count`、`used_count`、`truncated` | 候选值来源去重后的个数、实际使用的个数；`truncated=true` 表示来源个数超过了使用上限，只读了其中一部分 |
+| `control.options.page`、`pageSize`、`keywords.size`、`selectedValues.size` | 请求的页码、页大小、关键字个数、已选值个数 |
+| `control.result.candidate_size` | 去掉已选值之后的候选总数（翻页之前） |
+| `control.result.row_size`、`value_size`、`has_next` | 本页返回的行数、值个数，以及是否还有下一页 |
+| `control.result.empty`、`option_count` | 结果是否为空，以及返回的选项数（只针对文本筛选器） |
+| `control.context.*` | 本次请求带上的其他筛选器的筛选上下文，例如 `input_count` 个数、`ids` / `names`、`value_present_count`、`has_parameter`、`has_control_linkage` |
+
+读法：候选值慢时，先看 `control.query.mode` 和 `control.query.unbounded`（全选没有取数上限，最容易慢），再看 `control.option_source.truncated` 和 `distinct_count`（来源很多时会被截断），最后看 `control.query.output_rows` 与 `candidate_size` 判断返回量。
+
+### 怎么读这些属性
+
+除了入口 attribute，请求内容里的筛选树和计算上下文也能用。按请求类型读：
+
+- 筛选器候选值请求只受其他筛选器的影响；组件请求的影响因素不限于筛选器，查询、绑定表、`control`、参数、权限、`linkage` 都要保留。
+- `linkage` 是自动联动（`has_auto_linkage` 可作入口信号）。组件间自定义联动从 `control` 里的 `ComponentControl` 认：`type=81` 稳定对应 `ComponentControl`，但是否跨源要比较组件绑定表、`value.tableId`、`filterCols.field/source` 和生成的过滤条件，不能单独证明跨源。仪表板 2.0 不再产生 `valueLinkageMap`，而 `has_custom_linkage` 仍依据它，所以都不能用来判断自定义联动。
+- `controls.binding_info` 形如 `名称(id){type=N}->[analysis_table:tableId.fieldId]`，也可能是 `advanced_component:`、`parameter:` 或 `unbound`（旧版没有类型前缀）；它和 raw binding 只是摘要，完整关系以筛选树和请求内容为准，组件目标不能按 ID 巧合挂到分析表节点。表名、字段名要从同一仪表板的只读配置或资源元数据补，不从 ID 推断。
+- `controls.effect_count` 是这次请求 control Map 的条目数，不是画布上的筛选器数（一个筛选器可能产生多个 effect）；`controls.input_count` 是旧字段。两者都没有时记为未知，不能按 0 当“无筛选器”基线；ID 按完整值匹配，不用前缀。
+- `component.linkage.depth`、`control_context_count`、`source_component_ids`、`edges` 描述计算拓扑，是摘要，替代不了画布的完整实例配置。部署较早或版本未知时，字段缺失不能反证没有筛选器、联动或深层路径（见[知识适用性](../common/conclusions.md#知识适用性)）。
+
+用这些还原业务计算：组件查询字段和计算类型、表关系路径、最终筛选树、筛选器、参数、权限、联动，说明这次算了什么、有多复杂。来源判定替代不了筛选树、组件集合和可靠时间边界组成的交互记录。业务解释通了，选定的慢或失败引擎执行也照样按[引擎知识](../engine/workflow.md)看 Metric。

package/content/knowledge/dashboard/topics/component-comparison.md

@@ -0,0 +1,9 @@
+# 组件计算对照怎么判断
+
+仪表板内组件可以正常直接读取分析表已有结果，也可能因附加条件展开上游计算；单独预览使用同一查询表，不代表两侧算了同样的内容。调查顺序见[组件取数先做对照](../workflow.md#组件取数先做对照)，本节只规定可比性。
+
+- 图表编辑时的预览可见 `POST /v2/design/widget/data`、`editComponent`；仪表板以外的图表预览（同样走仪表板组件预览入口）须按[来源判定](../../common/signals.md#仪表板组件预览入口)确认。`/v2/query/data` 只是通用查询，必须核对请求和组件关联。仪表板内的另一次成功请求仍是仪表板请求。
+- 图表编辑时不保证有仪表板组件预览入口的 `component.id`、`component.query.table_id` 和请求上下文属性。可以从请求日志恢复组件和 `tableBean.id`、查询字段及操作，再关联其 trace/task；不能过滤这些缺失属性后把零结果当成“没有单独预览”。
+- 有相同组件 ID 时仍需核对查询表、字段、聚合、排序、分页、配置版本和数据版本。ID 未记录时，同用户、同查询表与完整查询配置可作为对应组件的候选依据；同表、同用户或时间接近单独不足以确认身份。差异本身可作为调查对象，字段不全时标为相关对照，不强称严格等价。
+- 成功须有业务结果或任务最终完成的记录，例如 `result.status=success/empty`、明确成功响应或同 task 的 `FINISHED`，并核对是否真实执行。HTTP 200、耗时短、没有 ERROR 不足以证明成功；`updating`、取消、失败重试或返回旧结果也不能当成已完成同样计算。正常空结果可保留，但不能冒充同数据范围的非空结果。
+- 对照重点包括请求额外条件及实际计划：直接扫描目标表，还是展开来源表、关联、聚合和中间缓存。分别报告两侧输入、输出和失败边界，不将成功返回的汇总行与失败处理中间明细行直接计算放大倍数；Metric 比较口径沿用引擎知识。

package/content/knowledge/dashboard/topics/dynamic-fields.md

@@ -0,0 +1,21 @@
+# 动态字段覆盖与上游展开
+
+动态字段是一种可选择替代计算字段的业务配置，不等于任意运行时表达式，也不能从“日期”一词猜它的名称。仪表板 2.0 取数路径中，`control.type=73` 是动态字段下拉筛选器。绑定使用动态字段位置，包含 `id`、`name`、`operatorId`、`tableId`，组件分支还可带 `widgetId`；请求材料中的位置对象可称 `dynamicField`，筛选器关系请求中称 `fieldPosition`。
+
+有值且能匹配到有效动态字段配置时，所选计算字段与默认计算字段不同会产生动态字段覆盖；相同选择不产生该项覆盖。覆盖或参数作用于上游表时，下游可能不能直接读取原来已经保存的计算结果，而需沿依赖展开上游计算。普通字段过滤、联动及其他执行条件也可能改变计划，不能仅凭“仪表板入口”或一个筛选器存在就确定重算原因。
+
+核对时区分三层事实：
+
+| 记录 | 能确认什么 | 还需核对什么 |
+|---|---|---|
+| `controls.ids`、`controls.effect_type_counts`、有值计数 | 请求带入了哪类筛选器项 | 最终是否生成覆盖；需要定位时核对绑定与树中位置 |
+| `filter_conditions.dynamic_field_count>0`、节点 `dynamic=N` 且 `N>0` | 最终条件树包含动态字段覆盖；节点摘要还可定位所在表路径 | 实际计划是否展开上游，以及对应计算和资源压力 |
+| 对应执行计划展开来源表，并有任务与 Metric | 本次实际发生了哪些上游计算及资源压力 | 结合覆盖、筛选和其他条件区分触发因素 |
+
+性能诊断中，动态字段这一项默认取证到“是否存在覆盖”，无需具体选择值和默认计算字段。当前执行的最终条件树已有上述正数记录时，直接确认覆盖，继续沿实际计划和 Metric 分析上游计算、中间结果及资源压力；不为再次证明覆盖而补查这两个值，也不因缺少它们列出诊断缺口、阻塞交付或建议新增服务端埋点。只有用户明确询问具体替换内容或选项语义时，才定向补取这些值；没有取得就保持未知。覆盖存在不等于它导致了全部额外计算或内存超限，因果判断仍需同次执行的计算路径和资源记录。原因分析的展开程度及排查方向按[诊断结果交付](../../../docs/diagnostic-report.md)处理。
+
+`controls.ids` 中的 `parameter:<id>` 可能只是请求 Map 的键，不能据前缀认定普通参数。`controls.has_parameter`、`controls.parameter_*` 只统计普通参数筛选器，不覆盖动态字段筛选器；它们为 false/零不能排除动态字段影响。`controls.binding_info` 的 `unbound` 也可能只是普通字段绑定摘要为空，不能反证动态字段没有绑定或生效。筛选器名称缺失时，名称摘要可能退回到这个键。
+
+`filter_conditions.*_count` 的部分字段只在正数时写入；工具投影的零或 false 可能是缺字段默认值。优先用完整 `tree_summary` 中明确的五类计数核对零值，不由投影零值构造“无条件”对照。`dynamic_field_count` 为 0、`tree_summary` 也为空时，对用户说“这次没看到动态字段覆盖”就够了，不用列成缺口。计数摘要没有选项值和字段名，不意味着请求或关联日志也没有。
+
+不能把本地行为直接当成目标环境已部署事实；版本未知时保留依赖版本的判断。线上已有计数和计划可以直接说明观测事实，无需使用者准备产品代码。

package/content/knowledge/dashboard/topics/filter-tree.md

@@ -0,0 +1,35 @@
+# 筛选树还原与交付
+
+组件计算存在多层、多分支过滤树，或判断依赖筛选器所在层级时，必须按本节校验并输出完整树结构。小而完整的树可直接解释；节点数、最大深度或筛选器数量不能代替树结构。
+
+筛选结构可记录 `filter_conditions.root_table_id`、`node_count`、`path_node_count`、`max_depth`、`table_ids`、`table_paths`、`tree_summary` 及各类过滤数量。筛选器候选值链路还可出现 `data.control.calculateOptions`、`data.control.engineExecute`，不能只按历史 `controlData` 查找。默认 trace 详情缺自定义属性时，使用同执行的定向查询补齐。
+
+`node_count` 表示去重后的条件对象数量，`path_node_count` 表示沿不同路径访问对象的次数。共享对象可在多条路径上重复出现，对应 summary 保留五类过滤计数并标记 `shared=true`；同一个 tableId 不足以证明同一个条件对象，不能按表 ID 去重。展示时保留完整路径，在重复访问处标注共享，避免把多条路径当成多份独立业务对象。
+
+`cycle_paths` / `cycle_path_count` 表示记录中的环路边界，summary 形式为 `{cycle=true}`。该末端不含五类筛选数量，也不计入 `path_node_count`，展示到环路末端即停止，不推导后续关系或断言计算一定死循环。完整性需要同时核对路径访问数、条件对象数、共享与环标记；旧记录缺少新增字段时，只有完整、可解析的路径及 summary 能支持相同核对时才继续确认。
+
+`table_paths` 或 `tree_summary` 出现 `...(N)`、计数冲突或摘要缺失时，只恢复可见部分并保留缺口。不能把 `table_ids` 中的孤立 ID 拼回结构，也不能用 `max_depth` 猜测层级。字段缺失不能当成数值为零。
+
+## 选定结构与完整性
+
+先按当前组件、操作和请求父子范围选定树，再核对条件对象数、路径访问数及每条路径的 summary。绑定必须属于同请求父子范围，不能把同 trace 的另一组件条件挂到当前树。
+
+共享路径保留 `shared=true`，环路末端保留 `{cycle=true}`，`tree_summary` 必须覆盖每条已显示路径。出现 `...(N)`、计数冲突、缺失 summary 或其他完整性校验失败时，只输出可证明的局部树，说明能确认的缺失数量和缺失摘要的产物位置，并标为不完整。不得将截断后的孤立节点猜接回树，也不得声称已标注全部筛选器位置。
+
+助手从 `table_paths` 和 `tree_summary` 还原树，并依次核对：
+
+1. 逐条解析路径（如 `root->a->b`），按路径前缀建树。同一对象出现在多条路径中时，条件对象只计一次，路径访问按出现次数计。
+2. 每条可见路径都要在 `tree_summary` 中找到对应 summary；带 `shared=true` 的是共享对象的重复访问，带 `{cycle=true}` 的是环路末端，环末端不计入路径访问数。
+3. 用 `node_count` 核对条件对象数、`path_node_count` 核对路径访问数。
+4. 全部可见路径都有 summary、没有 `...(N)` 截断，且路径身份与环路标记均能核对时，缺失节点数按“声明的对象数减去已核对对象数”计算；其他情况写“缺失数量未知”。不能用声明的对象数减去可见路径数。尚未被有效 summary 核对的对象可能只是缺少摘要，不能直接当作缺失节点。
+5. 同一 trace 中有多棵树时，全部列出并注明来源 span。按当前组件和请求父子范围选定目标树，不默认选最大或最完整的一棵。
+
+## 名称、绑定与展示
+
+从同一 dashboard/report 的只读配置或资源元数据中，一次取得所选完整树所需的 tableId/fieldId 名称映射；只有筛选器 ID 时按[名称与请求上下文的关联取证](name-binding.md#名称与请求上下文的关联取证)核对已有关系请求。每个 ID 只查询一次，将名称补入树中，不根据 ID 形态猜名称。
+
+每个节点标注“表名（tableId）”及字段筛选、组件筛选、参数、动态字段、联动筛选五类 summary 是否存在；明确零条件时写“筛选：无”，缺失字段保持未知。筛选器字段筛选和绑定显示“字段名（fieldId）”，有依据时补充“绑定候选筛选器 + 绑定字段名（fieldId）”。名称不足时保留 ID，并列出缺少名称的表 ID 和字段绑定，不为补名称阻塞已成立的性能结论。
+
+`controls.binding_info` 与节点表匹配，只能建立绑定候选关系，不能证明筛选器产生了该节点的条件或实际生效。来源与生效范围须有明确的条件关联和执行记录。入口级权限信号没有节点位置时，作为树外上下文说明，不随意挂到表节点。
+
+完整性只证明所选结构已覆盖，不证明配置合理、交互影响唯一或筛选器导致耗时增加；这些判断仍需业务配置、执行和必要对照。

package/content/knowledge/dashboard/topics/name-binding.md

@@ -0,0 +1,9 @@
+# 名称与请求上下文的关联取证
+
+默认 trace 详情未展示名称或请求内容时，先定向补属性，再读取当前请求日志；默认详情、索引字段清单和计数摘要都不能代表完整可查询内容。日志先查 `body`，结构化请求字段仅在实际 schema 存在时读取；不要把未索引的 `widgetId` 等请求 JSON 键直接写成顶层查询字段。
+
+筛选器或动态字段名称可由 `POST /v1/conf/widget/relations` 的已有请求日志补齐。该请求用于分析仪表板筛选器关系，可记录 `widgets` 和 `controls`，动态字段位置 `controls[].fieldPosition` 包含 `id/name/operatorId/tableId/widgetId`。请求日志可能截断、脱敏或未采集；只提取命中的位置对象和组件标识，不输出完整业务载荷、用户身份或会话信息。
+
+从 `controls.ids` 的键提取候选字段 ID 后，仍按完整 ID 比较。关系请求必须核对当前租户/用户或会话范围、组件列表包含目标组件，以及字段的表、算子、分支标识与本次绑定是否一致；能取得 report 时同时核对。不是同一执行的关系请求只提供名称与绑定元数据，不可冒充失败 trace 的直接属性、当时的选择值或默认值，也不能证明两次请求由同一次交互触发。
+
+查询范围与预算见[仪表板内外组件对照](../../common/topics/baseline-comparison.md#仪表板内外组件对照)，取字段与过滤例子见[筛选器名称与动态字段](../queries.md#筛选器名称与动态字段)。一次补齐当前相关 ID，命中后按关联 trace 精确读取；同字段 ID 但表、算子或分支不同，名称冲突、配置可能已变时保留歧义。元数据只能支持“该次关联请求上报的字段名”，不能确认当前权威名称时说明限制；确无可用材料时再报告名称缺口，不能从表达式、截图结论或相似 ID 猜名称。

package/content/knowledge/dashboard/workflow.md

@@ -0,0 +1,35 @@
+# 仪表板 · 排查入口
+
+仪表板 2.0 的筛选器候选值或组件取数慢时从这里下手，旧版仪表板不在范围内。只有两类取数：筛选器自身取候选值，和组件取数。首次加载、筛选值变化、参数变化和联动只是组件取数的触发上下文，不算单独的场景。仪表板组件预览入口先按[来源判定](../common/signals.md#仪表板组件预览入口)确认；概念、信号、结论、查询分别见本域的 [concepts](concepts.md)、[signals](signals.md)、[conclusions](conclusions.md)、[queries.md](queries.md)。
+
+## 入手
+
+- 报错落在引擎里（超时、内存超限）时，引擎只说明撞了什么线，原因回到下面还原的业务计算里找。
+- **先分清是哪类取数**：筛选器取候选值只看它怎么算候选值、别的筛选器带来什么影响；组件取数看组件自己的查询。组件请求里带着筛选条件，不代表是筛选器自身取数。
+- **优先用 trace 的 span attribute 还原本次具体业务计算**：组件算哪些查询、用了哪些字段、聚合和排序；根表、绑定表、筛选字段所在表及它们之间的完整路径；筛选、参数、权限、自动联动、组件间联动各加了什么；数据范围有没有被父表路径、无关字段、重复分支或不合理的绑定放大。先据此判断计算复杂度，再看引擎，别一上来就按慢 span 找 Metric。
+- 筛选树多层或多分支时还原成完整的树，见[筛选树还原与交付](topics/filter-tree.md)；筛选器或动态字段只剩 ID 时见[名称关联取证](topics/name-binding.md)；怀疑上游被重算见[动态字段覆盖](topics/dynamic-fields.md)；默认详情缺业务 attribute 时按[取证例子](queries.md)定向补。
+- **筛选值变化后变慢**：能看出属于同一次筛选、或落在可靠时间边界内的组件请求，算这次受影响的集合；全部受影响组件刷新完成才是用户感觉的“好了”。分清是“影响范围大”还是“某一个算得慢”。没看到其他组件请求，不等于配置上绝对没有其他目标，要确认按[核对配置影响范围](conclusions.md#核对配置影响范围)读 targets。
+- 筛选字段绑在较上层父表、让组件走了更宽的数据链路，且请求内容、筛选树和资源关系能证明带来了额外计算时，可以当作性能原因；业务上能不能往下挪另说。
+- 慢或失败的引擎执行看[引擎知识](../engine/workflow.md)，业务上解释通了也最好补上。关键组件、绑定表或更新状态可疑时转[分析表](../dataset/workflow.md)或[更新](../update/workflow.md)。
+
+## 组件取数先做对照
+
+认出是仪表板里的组件计算后，主动去找这个组件单独预览的记录，不用等用户说“单独看是好的”。查找范围见[仪表板内外组件对照](../common/topics/baseline-comparison.md#仪表板内外组件对照)，可比性和成功判定见[组件计算对照怎么判断](topics/component-comparison.md#组件计算对照怎么判断)。
+
+- 单独预览成功、仪表板里失败或变慢：先看仪表板额外带进来的动态字段、参数、筛选、联动和权限；只因入口不同不能下结论。
+- 两边都异常：先查共同部分，即组件查询、输入数据和计算链。
+- 没找到对照：照样分析手上的异常 trace，同时提醒用户看看单独预览时是否也异常。仪表板里很快成功的请求只说明有另一条计算路径，不能当单独预览。
+
+## 常见现象与候选假设
+
+- **筛选器自身取数慢**：来源表或绑定字段多、自动解析读的范围大；别的筛选器带进的条件让查询变大；来源表的上游状态成了关键路径。对比读进来的数据量和最后的候选值数量。配了多个字段不一定慢，“按钮组绑了几个大字段又是自动解析”只是假设，不直接建议改手动解析。
+- **组件取数慢**：组件自身查询复杂；筛选绑在较上层父表撑大了过滤树；参数、权限、自动联动或 `ComponentControl` 加了计算；一次动作触发多个组件，少数关键组件或共享上游拖慢整体。见过的情况：日期区间参数不是默认值，一打开就实时计算；每次调日期区间都触发大计算；参数或筛选绑在很深的上游。改默认值、改点查询、绑定下移都有业务前提。
+- **引擎优化器超时或内存超限，请求只带了参数**：参数绑在很深的上游父表上时，参数一变，上游存好的结果都用不了，整条上游链被实时展开，查询语句变得极长，引擎在优化阶段就超时（`Task execution timeout after ... (limit: ...)`）或算到内存超限。看 `previewComponent` 上 `controls.parameter_names` / `controls.parameter_bindings` 带了哪些参数、筛选树是否为空，再按[查询规模信号](../engine/signals.md#查询规模信号)看 `dax length`、`end get parent` 次数。对得上就是参数绑定层级的问题。参数绑在哪张表 trace 里看不到，请用户在参数设置里看；建议绑定挪到靠近组件的表上，挪之前确认业务口径。案例见[仪表板参数绑在深层父表](../cases/dashboard-parameter-deep-binding.md)。
+- **单独预览正常，仪表板里展开上游后超限**：核查过的案例里，单独预览直接读几行保存好的汇总；仪表板里失败那次带了上游动态字段覆盖，展开了几路明细、关联和缓存后撞上内存上限。同一仪表板也有很快成功的请求，“在仪表板里”本身解释不了差异。先看有没有动态字段覆盖、覆盖所在表到组件查询表的路径；名称映射补不出失败那次选的值，历史请求也不能冒充失败 trace 的属性。
+
+## 易错点
+
+- 没有共同的交互 ID 或可靠时间窗时，不把挨着的 trace 拼在一起。请求多不代表关键路径慢，最慢的组件也不一定解释整体完成时间。
+- 仪表板只是调查起点，不代表问题就在仪表板。Metric 也不是仪表板排查的起点，替代不了对业务计算的还原。
+- 不用 `valueLinkageMap` 解释仪表板 2.0 的自定义联动。`control` 里的 `type=81` 只说明是 `ComponentControl` 组件间过滤，是否跨源要结合绑定表、`value.tableId`、`filterCols` 和生成的过滤条件看。
+- 不覆盖并发容量、并发退化或压测问题；同一筛选影响的多个组件只用来确认影响范围、绑定是否合理和关键路径。

package/content/knowledge/dataset/README.md

@@ -0,0 +1,27 @@
+# 分析表知识
+
+分析表的前台预览和步骤计算，以及预览所依赖的上游更新结果。只说明可能的链路与信号含义，本次事实以执行记录为准。
+
+## 槽位
+
+每个知识域都按同样的槽位组织。按要做的事选槽位，只读命中的章节。
+
+| 要做什么 | 读 | 包含 |
+|---|---|---|
+| 这类问题从哪里入手 | [workflow.md](workflow.md) | 分析表排查入口：入手提示、常见现象的候选假设、易错点 |
+| 弄清概念是什么、怎么关联 | [concepts.md](concepts.md) | 分析表与步骤的业务概念；预览请求、步骤、上游更新、engine 之间的调查关系 |
+| 认出入口，看懂 span、attribute、日志和字段 | [signals.md](signals.md) | 认出分析表入口：接口、span、attribute 的含义，历史入口与当前入口的区别 |
+| 看完日志和 trace，能下什么结论 | [conclusions.md](conclusions.md) | 配置、trace/log、Metric 各自能说明什么；调查时要保留的信息 |
+| 写查询、选取证路径 | [queries.md](queries.md) | 在 SigNoZ 中怎样组合入口、span 与 `tableId` 取证 |
+
+## 展开明细
+
+| 文件 | 何时读 | 内容 |
+|---|---|---|
+| [topics/steps.md](topics/steps.md) | 问题和某个步骤有关（加了某一步变慢、预览到某一步超时或内存超限），或要解释 `operatorType` 时 | 预览算到哪一步；步骤类型对照；哪些步骤容易慢或爆内存；怎么拿到步骤配置 |
+
+## 关联
+
+- 相关知识域：[更新](../update/README.md)：预览读取上一次更新产物时
+- 相关知识域：[引擎](../engine/README.md)：进入计算后的 Metric
+- 相关知识域：[通用](../common/README.md)：环境、trace 路由和查询规则

package/content/knowledge/dataset/concepts.md

@@ -0,0 +1,30 @@
+# 分析表 · 概念与关联
+
+回答“这是什么、彼此怎么关联”。
+
+## 业务概念
+
+- 分析表由表配置和有序操作步骤构成，每一步拿上一步的结果继续算；预览只算到选中的那一步。步骤类型和各自的计算特点见[分析步骤](topics/steps.md)。
+- 用户常见锚点包括 `tableId`、分析表预览请求、选中步骤和预览页。
+- 分析表的前台预览与后台更新可能共享计算语义，但不是同一次执行。
+
+## 调查关系
+
+```text
+tableId / preview request
+  → 分析表配置与选中步骤
+  → 本次预览执行
+  → Query
+  → engine task
+```
+
+如果预览读取的是上次更新产物，还需要保留：
+
+```text
+analysis table
+  → update run
+  → upstream dependency
+  → engine write
+```
+
+本次预览使用的配置版本和更新结果，需要资源元数据和运行记录确认。指南只说明可能的链路。

package/content/knowledge/dataset/conclusions.md

@@ -0,0 +1,11 @@
+# 分析表 · 能下什么结论
+
+回答“手上的日志、trace 和 Metric 能说明什么、不能说明什么，结论能下到哪一步”。
+
+## 各类材料能说明什么
+
+配置说明分析表可能如何计算，trace/log 说明本次实际执行，Metric 说明进入计算后的执行行为。引擎的物理计算阶段不能写成 server 保存的步骤。
+
+## 调查时保留
+
+优先保留 route、入口 span、table ID、选中步骤、trace ID、耗时、错误、Query 关联和资源版本。

package/content/knowledge/dataset/queries.md

@@ -0,0 +1,7 @@
+# 分析表 · 查询方法
+
+回答“怎样取证、怎样查询”。
+
+## SigNoZ 查询线索
+
+遵循[公共查询收敛规则](../common/queries.md)。资源驱动查询沿用公共规则确定的环境和问题发生时间，在业务 server 的 `service.name` 下组合分析表入口 route 或 `operatorsPage*` span 与 `tableId`；不要仅凭 tableId 跨环境或扫描天级时间窗。用户明确描述报错、内存超限或 OOM 时，失败信号优先于入口类型：先在相同约束内按 `tableId + 失败签名` 查询 ERROR 日志，收集全部精确命中的 trace 或 engine task，再标注它属于前台预览还是后台更新。预览与更新可能共享计算语义但不是同一次执行；相同失败签名和计算链路可以联合解释，其中的 trace、task 和 Metric 仍按执行隔离。只有不同执行指向不同原因且无法从用户现象判断目标时才请求消歧。用户只描述慢时再以入口 trace 为先。

package/content/knowledge/dataset/signals.md

@@ -0,0 +1,61 @@
+# 分析表 · 入口与信号
+
+回答“怎样认出入口，各个 span、attribute、日志和字段是什么意思”。
+
+## 场景识别
+
+可用于识别操作的入口。route 是去掉部署上下文路径后的写法；SigNoZ 里的 HTTP span 名和 `http.route` 都带上下文路径，测试环境是 `/decision`，例如 `POST /decision/v1/conf/analysis/operators/page`，筛选时按实际环境的前缀匹配。
+
+| route | 业务 span | 含义 |
+|---|---|---|
+| `POST /v1/conf/analysis/operators/page` | `operatorsPage` | 编辑步骤分页预览 |
+| `POST /v1/conf/analysis/operators/fields` | `analysis.operatorsFields` | 当前步骤字段 |
+| `POST /v1/conf/analysis/operators/count` | `analysis.operatorsPageCount` | 当前步骤行数 |
+| `POST /v1/conf/analysis/step/page` | `stepPage.stepDataPreview` | 将稳定 stepId 转换为预览请求后取数 |
+
+业务 span 名称由控制器方法声明。统计用户操作次数时以 HTTP route 为准，不要拿业务 span 条数直接当请求数。
+
+历史 `POST /v1/conf/analysis/operators/page/v2` 和 `operatorsPageV2` 属于历史预览入口。历史 trace 中出现它们仍可识别当时的分析表预览，但不能作为当前环境的发现入口，也不能据此决定当前请求使用 V1 或 V2 引擎。
+
+`stepPage.stepDataPreview` 请求也可能包含 `reportId`；脱离仪表板组件预览入口链路的 reportId 不能单独证明 仪表板 2.0 场景。
+
+预览入口可以记录 `tableId`、`tableName`、`selectIndex`、`subselectIndex` 和 `operatorType`。接口缺失时，入口 span 与这些 attribute 的组合仍可支持从分析表开始调查。
+
+## 信号含义
+
+- `tableId`、`tableName`：标识本次预览关联的分析表；
+- `selectIndex` 是请求 selected + 1（从 1 开始）；`subselectIndex` 保留请求 subSelected（从 0 开始）。两者不等同于稳定业务 stepId；
+- `operatorType`：当前步骤的类型（如 `Join`、`Group`、`AddNewColumn`），各类型的含义和计算特点见[分析步骤](topics/steps.md#步骤类型对照)；
+- Query、engine span：说明已经进入共享计算链路，不能单独证明分析表入口。
+
+`tableId` 也可能出现在组件绑定和更新链路中。缺少入口 span、route 或其他分析语义时，不应仅凭 `tableId` 判断为分析表场景。
+
+## 预览的阶段
+
+一次分析表预览（`operatorsPage`）里的 span 结构，用来判断时间花在哪一段：
+
+```text
+POST /v1/conf/analysis/operators/page
+└─ operatorsPage
+   ├─ batchGetEntryInfo、batchGetTableConf   取表信息与配置
+   ├─ grammarCheck                           逐步骤语法检查
+   ├─ dataModel                              取数的主体
+   │  ├─ optimizeUsingCache                  判断能否复用已缓存的步骤结果
+   │  ├─ createCacheTable                    把某一步的结果写成缓存表，供后续步骤复用
+   │  │  └─ DataFlowExecutor → execute       引擎写入
+   │  └─ QueryExecutor → execute             引擎查询：query 提交任务，fetchBlock 轮询取结果
+   └─ tryGetRowCount                         取行数
+```
+
+- `dataModel` 一般占 `operatorsPage` 的大头，其中 `QueryExecutor` 是引擎查询；`grammarCheck`、`optimizeUsingCache` 一般很短。`createCacheTable` 可能比它的父 span 还长（写缓存可以在预览返回后继续），它的耗时不一定计入这次预览的响应时间，判断预览慢在哪，以 `dataModel` 和 `QueryExecutor` 为准。
+- 取行数（`tryGetRowCount`）先用已有缓存的行数和步骤推算总行数，推不出来时才另发一次引擎计数查询。
+- 写缓存（`createCacheTable`）和预览查询（`QueryExecutor`）可能同时在跑、读同一张来源表，会争引擎资源和内存。两者各自记开始时间和耗时，重叠多时可以作为“预览变慢”的一个候选原因，但要有资源记录才能确认。
+- `optimizeUsingCache` 上有 `hit_operator_type`（命中缓存的步骤类型，如 `join`、`filter`、`group`）、`hit_operator_index`（第几步）和 `used_cache_table`：有值表示复用了缓存，没有值表示没命中。
+- `QueryExecutor` 和 `DataFlowExecutor` 以下是引擎执行，进入后按[引擎知识](../engine/README.md)解读。
+
+## 活跃检查
+
+引擎查询前会对涉及的表做活跃检查，在组件计算和筛选器候选值的 trace 里都能看到，span 是 `checkUpdatePolars`，里面有 `markActive`。它把这张表和它的所有父表标记为活跃，必要时对 `updateRoots` 触发一次更新，更新场景是 `ACTIVE`（见[更新场景](../update/concepts.md#更新场景updatescene)）。所以前台操作后出现的 `ACTIVE` 更新，可以从这里反查。
+
+`checkUpdatePolars` 带 `tableId`、`tenantId`，以及 `activeScene`（触发检查的操作）：`WIDGET_PREVIEW` 和 `HOME_PREVIEW` 是预览，`TABLE_EDIT` 是编辑表，`TABLE_EDIT_RED` 是编辑表时取标红信息，`TABLE_EDIT_SELECT` 是选表预览，`EXPORT` 是导出。
+

package/content/knowledge/dataset/topics/steps.md

@@ -0,0 +1,59 @@
+# 分析步骤
+
+分析表由一串有序的步骤组成，每一步拿上一步的结果继续算。用户说“加了某一步之后变慢”“预览到某一步就超时”时，先弄清那一步是什么类型、它在引擎里会变成什么计算，再结合这次的数据量判断。
+
+## 目录
+
+- [预览算到哪一步](#预览算到哪一步)
+- [步骤类型对照](#步骤类型对照)
+- [哪些步骤容易慢或爆内存](#哪些步骤容易慢或爆内存)
+- [怎么拿到步骤配置](#怎么拿到步骤配置)
+
+## 预览算到哪一步
+
+- 预览只算到用户选中的那一步，后面的步骤不参与。trace 上的 `selectIndex` 是选中第几步（从 1 开始），`operatorType` 是这一步的类型；左右合并、上下合并里面还有子步骤时，`subselectIndex` 是子步骤的位置（从 0 开始），`operatorType` 取子步骤的类型。
+- 页面上只显示前一页（Metric 计划里是 `LimitNode`），但排序、分类汇总、排名、累计这类步骤要先对全部数据算完才能截取。所以“只返回 100 行”说明不了算得少，要看引擎读了多少行、中间结果有多大，见[Metric 里常见的名字](../../engine/concepts.md#metric-里常见的名字)。
+- 前面的步骤可能命中缓存（`optimizeUsingCache` 上的 `hit_operator_index`），命中时只从那一步往后算，见[预览的阶段](../signals.md#预览的阶段)。
+
+## 步骤类型对照
+
+跟用户说步骤时，用页面上的中文名和位置，比如“第 53 步：新增字段”；trace 里的类型名和 Metric 里的算子名只用来自己对照，不写进答复。
+
+| 步骤（页面上叫） | trace 上的 `operatorType` | Metric 里大致对应 | 性能上要留意 |
+|---|---|---|---|
+| 选字段（选来源表和字段） | `SelectTable` | `DataSourceNode`，执行时是 `LakeConnectorSource` | 来源表的行数、列数；选的字段越多读得越多。来源表找不到时日志是 `select operator not found parentTable`，按原字段名当文本字段继续 |
+| 筛选 | `FilterOperator` | `FilterNode` | 本身很轻；放得越靠前，后面算得越少 |
+| 配置权限 | `PermissionSetting` | `FilterNode` | 同筛选 |
+| 左右合并 | `Join` | `JoinNode`，执行时是 `ParallelHashJoinSink`（建表）+ `ParallelHashJoin`（探测）；没有等值连接键时是 `CrossJoin` | 右表大小、连接键重复值。两边都有重复值时行数成倍放大，超过行数上限（物理计划里的 `rowRestrict`，按企业配置）报行数超限；两边数据量都很大又是多对多时，引擎会提前中断，报多对多关联 |
+| 上下合并 | `Union` | `UnionNode` | 行数是几张表相加 |
+| 分类汇总（含去重） | `Group` | `AggregateNode`，执行时是 `FinalPreHashAggregate` + `FinalMergeHashAggregate` | 分组字段组合越多，越吃内存 |
+| 排序 | `Sort` | `SortNode`，后面接取一页时常合成 `TopN` | 要保存全部行再排；数据大时吃内存 |
+| 新增字段：公式、分类赋值、条件赋值 | `AddNewColumn` | `ProjectNode` 里的表达式；分类赋值用了“前 N 名”这类条件时会多一个窗口计算 | 一般很轻 |
+| 新增字段：累积值、排名、占比、汇总值 | `AddNewColumn` | 窗口计算，`WindowNode` 或 `WindowBINode` 都可能（不排序、整组算的多是后者） | 要按分组和排序把整组数据攒齐；不分组或分组很少时最重 |
+| 新增字段：同环比、同环期 | `AddNewColumn` | `JoinNode`：上游结果当成 CTE 引用两次，再按日期错位 LEFT JOIN 自关联 | 相当于上游数据复制一份再合并，耗时和内存接近翻倍；分组字段加日期不唯一时会多对多放大 |
+| 组合步骤：同环比、排名、占比、拆分到列 | `CompositiveOperate` | 同环比是 `JoinNode` 自关联，排名、占比是窗口计算（`WindowNode` / `WindowBINode`），拆分到列是 `ProjectNode` | 按里面的具体计算看，同上面对应的新增字段 |
+| 行转列 | `Row2Column` | `AggregateNode`（按分组汇总出每个新列） | 输出列数由数据里的取值决定，取值多时列会很多 |
+| 列转行 | `Column2Row` | `UnnestNode` | 行数约等于原行数乘以转换的列数 |
+| 拆分到行 | `Unnest` | `UnnestNode` | 行数放大，倍数取决于拆出来的个数 |
+| 补全缺失行 | `Complete` | 几个 `AggregateNode`（取值去重）加 `JoinNode`（补全取值和原表 FULL 合并） | 补全字段取值多、分组多时行数会暴涨 |
+| 字段设置（重命名、删字段、改类型） | `FieldSet` | `ProjectNode` | 很轻 |
+| 数据脱敏 | `DataMasking` | `ProjectNode` 里的表达式 | 一般很轻 |
+| 动态字段 | `DynamicFieldConfig` | 没有专门的节点 | 仪表板里替换后可能让上游重算，见[动态字段覆盖](../../dashboard/topics/dynamic-fields.md) |
+| 计算模型 | `ModelOperator` | 没有专门的节点，模型里的步骤各自展开 | 看模型内部的步骤 |
+| 分组步骤 | `StepGroup` | 没有专门的节点，组内步骤各自展开 | 看组内步骤 |
+
+“Metric 里大致对应”列的是逻辑计划（`analyzed info`）里的节点名，节点名和执行层的算子名都在线上 MPP Metric 和编译代码里核对过；优化器会改写合并节点，物理计划和执行层不一定一一对应。判断时以这次 Metric 里对应节点和算子的行数、内存和耗时为准，各层名字见[Metric 里常见的名字](../../engine/concepts.md#metric-里常见的名字)。新增字段在 trace 上都是同一个类型，分不出是哪一种：Metric 里出现 `WindowNode` 或 `WindowBINode` 是累积值、排名、占比这类窗口计算，出现同一张表和自己 `JoinNode` 合并多半是同环比，都没有就是公式、赋值类；拿不准时请用户看这一步的设置。
+
+## 哪些步骤容易慢或爆内存
+
+- **会让行数变多的**：左右合并出现多对多、同环比自关联时日期不唯一、列转行、拆分到行、补全缺失行。看这一步前后的行数，倍数大就是放大的来源。
+- **要把整批数据攒齐的**：排序、分类汇总（分组很多时）、累积值、排名、占比。数据量不变也可能吃很多内存。同环比走自关联，等于把上游再算一遍合并进来，也很重。
+- **本身很轻的**：筛选、字段设置、公式、数据脱敏。这类步骤慢，多半是前面的步骤或来源表大，不是它自己。
+
+判断某一步是不是慢因：把选中步骤和前一步分别预览的耗时对比（用户可以直接在页面上切换选中步骤），或者在 Metric 里找这一步对应的 Operator，看它的输入输出和耗时。只凭步骤类型“看起来重”不能下结论。
+
+给建议时落在步骤上，比如把筛选挪到合并之前、检查连接键是否有重复、给窗口计算加上分区字段、减少补全字段的取值范围。改步骤会改变结果，要提醒用户确认业务口径。
+
+## 怎么拿到步骤配置
+
+trace 上只有选中步骤的类型和位置。请求日志 `After request [POST .../operators/page ...]` 里带了请求内容，但会被截断，通常只能看到开头一两个步骤。完整的步骤列表和每一步的设置，直接请用户在分析表页面上看，或者截图给你。