@fx-data/ai-diagnostics 0.1.20261111015837 → 0.1.20261111112203

package/AGENT_SETUP.md

@@ -1,6 +1,6 @@
 # FX 数据诊断：Agent 安装与管理
 
-本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261111015837`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
+本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261111112203`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
 
 用户明确要求安装、更新、回退、卸载或检查 FX 数据诊断时，也会触发薄 Skill，并直接执行对应管理命令，不先运行 `context` 或读取诊断规则；只有开始诊断时才按薄 Skill 加载内容。普通聊天不主动加载。
 

package/README.md

@@ -20,6 +20,8 @@
 
 也可以提供更新的 dagId，询问这次更新为什么慢；或附上 Metric 文件，分析耗时和内存。描述问题时带上“用 FX 数据诊断”，也可以在技能列表中选择“FX 数据诊断”。
 
+要一份单租户更新报告，可以说「用 FX 数据诊断分析 corp-xxx 租户近 3 天的更新情况，生成 HTML 报告」。
+
 ## 更新
 
 每次开始新诊断时，工具会在后台检查更新，不等待更新即可排查。更新成功后，各 Agent 的下一次新诊断使用新版；当前调查保持原版本，更新失败也不影响排查。Agent 会随后续使用提示更新状态，没有新版时不打扰你。
@@ -38,4 +40,4 @@
 
 ---
 
-**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261111015837/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。
+**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261111112203/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。

package/content/AGENTS.md

@@ -27,9 +27,10 @@
 
 | 用户目标 | 起点 |
 |---|---|
+| 明确要求把单租户一段时间内的更新情况做成报告或 HTML | [更新知识 · 企业更新分析](knowledge/update/workflow.md#企业更新分析) |
 | 慢、超时、卡顿、内存超限、OOM、`MemoryLimitExceeded`、资源消耗异常、性能退化或回归 | [性能排查入口](knowledge/common/workflow.md)，再按场景进入对应知识域 |
 | 只想拿到或看懂一份 engine metric | [引擎知识](knowledge/engine/workflow.md) |
-| 只想弄清更新来源、request、chain/DAG、node attempt、requeue、load、listener、engine task，或核对更新计数 | [更新知识 · 解释更新记录](knowledge/update/workflow.md#解释更新记录) |
+| 询问或分析租户近期更新情况，或解释更新来源、request、chain/DAG、node attempt、requeue、load、listener、engine task 和计数 | [更新知识 · 解释更新记录](knowledge/update/workflow.md#解释更新记录) |
 | 自动化有没有跑、为什么没触发、通知没收到、回填失败，或给了 workflowId 查执行情况 | [自动化知识](knowledge/automation/workflow.md) |
 | 只想配置诊断环境，或实时查询被工具、连接问题挡住 | [配置 SigNoZ MCP](knowledge/common/topics/setup-signoz-mcp.md)，弄好后回到原问题 |
 | 其他问题：非性能报错、结果异常、稳定性问题 | 有报错原文就先查[信号索引 · 常见报错](knowledge/signal-index.md#常见报错)；没有专门入口，先说明这块覆盖有限，再按[问题定位方法](docs/architecture.md)结合已有材料分析 |

package/content/README.md

@@ -10,6 +10,7 @@
 | 组件或仪表板加载慢 | 查询条件、筛选、参数、联动与组件取数 |
 | 更新慢、超时、内存超限 | 调度等待、依赖、计算、写入与重试 |
 | 更新来源或数量不清楚 | 触发来源、更新链路、节点与尝试次数 |
+| 生成单租户更新报告 | 小时峰值、`UpdateScene`、执行规模和耗时，交付 HTML |
 | 自动化没触发、通知没收到或回填失败 | 按 workflowId 核对每次执行、跳过原因、动作结果与回填进度 |
 | 其他报错、结果异常或偶发不可用 | 核对现象与执行记录，整理已确认事实和待验证问题 |
 
@@ -33,6 +34,8 @@ npm 安装：对 Agent 说“帮我安装并启用 FX 数据诊断，npm 包是
 
 > 企业 corp-xxx，帮我看一下最近的更新情况。
 
+> 分析 corp-xxx 租户近 3 天的更新情况，生成更新报告。
+
 > 客户怀疑重复更新，请根据这些日志区分更新请求、节点和重试次数。
 
 > 帮我看下 workflowId=xxx 这个自动化最近的执行情况，客户说昨晚没收到通知。
@@ -54,6 +57,7 @@ npm 安装：对 Agent 说“帮我安装并启用 FX 数据诊断，npm 包是
 
 - 当前结论：哪个对象的哪次操作出现问题，已定位到什么环节或条件。
 - 关键依据：对应执行记录、错误、统计或对照结果，以及它们如何支持判断。
+- 计算关系图：支持将同次计算已取得的依赖与逐表条件生成可独立打开的 HTML 图，能力与知识索引见[仪表板知识](knowledge/dashboard/README.md#能力)。
 - 待确认信息（有实质缺口时）：仍需确认的问题和最小补充材料；需要研发接手时整理可继续调查的材料。
 - 需求反馈（有依据时）：本轮发现的未覆盖场景、知识缺口或工具改进线索，供后续改进本项目。使用者无需提供开发方案或跟踪处理。详见[诊断后的需求反馈](docs/diagnostic-feedback.md)。
 

package/content/docs/architecture.md

@@ -33,6 +33,8 @@
 
 ## 沿实际操作还原过程
 
+用户明确要求生成单租户更新报告或 HTML 时，按[企业更新分析](../knowledge/update/workflow.md#企业更新分析)聚合窗口、按需下钻并生成文件。一般的更新情况分析按[解释更新记录](../knowledge/update/workflow.md#解释更新记录)在对话中交付。
+
 先说清这次算了什么，再解释哪里慢、为什么失败。按[场景排查](scenario-guide.md)核对：读了哪些表和数据范围；哪些筛选、参数、聚合、联动、权限参与了计算；慢在等待、计算、写入还是返回；有没有失败重试，多了多少工作。
 
 页面配置说明可能怎么算，请求和执行记录说明实际怎么算，两者对得上同一对象、同一次操作才能合起来解释。组件取数慢和更新慢同时出现时，要确认这次组件请求是不是在等或读这次更新的结果，共享底层计算只是线索。仪表板内组件异常先按[组件取数对照](../knowledge/dashboard/workflow.md#组件取数先做对照)看单独预览，没有对照也继续分析。

package/content/docs/index.md

@@ -35,9 +35,16 @@
 | 常见引擎性能问题的判断方法 | [常见引擎性能问题](../knowledge/engine/topics/patterns.md) |
 | 分析表 / 组件 / 仪表板的业务概念、入口 span 与 attribute | [分析表](../knowledge/dataset/README.md)、[组件](../knowledge/component/README.md)、[仪表板](../knowledge/dashboard/README.md) |
 | 仪表板筛选树的完整性、名称补齐与展示 | [仪表板 · 筛选树还原与交付](../knowledge/dashboard/topics/filter-tree.md#筛选树还原与交付) |
+| 仪表板计算全景字段、逐表条件与观测缺失 | [仪表板 · 快照字段与含义](../knowledge/dashboard/topics/calculation-panorama.md#快照字段与含义) |
+| 仪表板计算全景的获取与 HTML 生成命令 | [仪表板 · 计算全景查询与生成](../knowledge/dashboard/queries.md#计算全景) |
+| 仪表板计算关系图能力与知识索引 | [仪表板 · 能力](../knowledge/dashboard/README.md#能力) |
+| 仪表板计算关系图的展示内容与边界 | [仪表板 · 计算关系图](../knowledge/dashboard/topics/calculation-panorama.md#计算关系图) |
 | 仪表板配置影响范围与“绑定下移”核对 | [仪表板 · 核对配置影响范围](../knowledge/dashboard/conclusions.md#核对配置影响范围) |
 | 企业更新与 dagId 的检索窗口、降级和时间扩展 | [更新发现指引 · 检索时间](../knowledge/update/topics/discover-executions.md#检索时间) |
 | 按输入选择更新取证配方 | [更新 · 选哪个配方](../knowledge/update/queries.md#选哪个配方) |
+| 企业更新负载的首批统计、租户归属、多日同期对比与画像总结 | [企业更新负载分析](../knowledge/update/topics/enterprise-analysis.md) |
+| 企业更新报告的 JSON 格式和 HTML 渲染 | [企业更新报告交付](../knowledge/update/topics/enterprise-report.md) |
+| 定时同步组释放与回调归并的判读 | [定时同步与回调更新模式](../knowledge/update/topics/datasource-update-patterns.md) |
 | 更新的计数单位 / 允许的关联边 | [更新 · 计数单位与身份](../knowledge/update/concepts.md#计数单位与身份)、[关联边](../knowledge/update/topics/correlations.md#关联边) |
 | 更新记录的计数对账、判断矩阵与停止规则 | [更新 · 能下什么结论](../knowledge/update/conclusions.md) |
 | 按 workflowId 查自动化执行情况 | [自动化 · 按 workflowId 查](../knowledge/automation/queries.md#按-workflowid-查) |

package/content/knowledge/common/signals.md

@@ -25,11 +25,11 @@
 
 ## 仪表板组件预览入口
 
-`POST /v2/external/widget/data`（代码里叫外部组件取数）实际场景就是仪表板里的组件预览，线上绝大多数请求来自仪表板；仪表板以外的图表预览也走这个接口，但只占少数。沿同一入口父子链找带 `DataRequestObservation` 属性的 span，可能是 `previewComponent`，也可能是别的子 span；最外层 HTTP span 的 `reportId` 可能是空的。
+`POST /v2/external/widget/data`（代码里叫外部组件取数）实际场景就是仪表板里的组件预览，线上绝大多数请求来自仪表板；仪表板以外的图表预览也走这个接口，但只占少数。沿同一入口父子链找带 `DataRequestObservation` 属性的 span，可能是 `calc.component`，也可能是别的子 span；最外层 HTTP span 的 `reportId` 可能是空的。
 
 - 任一对应 span 的 `data.request_context=dashboard` 或 `reportId` 非空，就是仪表板内组件计算，完全归仪表板场景，不先经过组件专项分流。
 - 确认这条链上这些信号都是空的，才按仪表板以外的图表预览查。属性还没拿到时记为未知，不能当成空值。
-- `previewComponent` 只是共享入口的 span 名，决定不了场景。离开这条取数链的 `reportId` 只能当关联线索；接口和 attribute 说法不一致时，两边都留着，不要悄悄选一个。
+- 新版 `calc.component`、历史 `previewComponent` 只是共享入口的 span 名，决定不了场景。离开这条取数链的 `reportId` 只能当关联线索；接口和 attribute 说法不一致时，两边都留着，不要悄悄选一个。
 
 这套规则只定调查入口。单个组件 trace 或仪表板来源标识，都证明不了已经覆盖整次仪表板交互。
 

package/content/knowledge/common/topics/baseline-comparison.md

@@ -16,7 +16,7 @@
 
 这是仪表板组件异常的默认浅查，不要求用户先提出对比，也不扩大为整张仪表板或企业扫描。先从目标 trace 恢复组件、查询表、时间与业务服务。已有单独预览材料优先复用；没有时间的对照查找，以目标执行开始前 24 小时的半开窗口为限。用户给出更明确的单独预览时间或 trace 时按该侧记录恢复范围，不套用失败侧时间。
 
-首次在同环境、同业务服务和该窗口内按组件身份及单独预览入口取有限候选，按时间由近到远核对。单独预览入口是图表编辑的 `editComponent`，或 `previewComponent` 上 `data.request_context` 不是 `dashboard`、`reportId` 为空的请求；`data.request_context=dashboard` 的都是仪表板里的请求，不能当对照。图表编辑时可能不记录 `component.id` 和 `data.request_context`；首查未命中时，在同窗口与服务内只降级一次，改查图表编辑时请求日志中的精确组件 ID，或已确认查询表加请求用户、查询字段等识别信息，不要求 `reportId` 同时命中。查询表只能发现候选，身份与可比性按[组件计算对照怎么判断](../../dashboard/topics/component-comparison.md#组件计算对照怎么判断)核对；不能因同表就认定为同组件。
+首次在同环境、同业务服务和该窗口内按组件身份及单独预览入口取有限候选，按时间由近到远核对。单独预览入口是图表编辑的 `calc.edit`（历史名 `editComponent`），或 `calc.component`（历史名 `previewComponent`） 上 `data.request_context` 不是 `dashboard`、`reportId` 为空的请求；`data.request_context=dashboard` 的都是仪表板里的请求，不能当对照。图表编辑时可能不记录 `component.id` 和 `data.request_context`；首查未命中时，在同窗口与服务内只降级一次，改查图表编辑时请求日志中的精确组件 ID，或已确认查询表加请求用户、查询字段等识别信息，不要求 `reportId` 同时命中。查询表只能发现候选，身份与可比性按[组件计算对照怎么判断](../../dashboard/topics/component-comparison.md#组件计算对照怎么判断)核对；不能因同表就认定为同组件。
 
 候选达到 limit 时，不宣称已覆盖所有记录；能唯一核实最近可比执行时选定并冻结，否则保留覆盖缺口。不继续扩大时间、移除服务或换表试探。未找到或不可比就继续目标失败分析，按场景流程提示用户检查单独预览结果。找到可比成功执行时主动取得两侧执行统计，各侧 engine 服务分别确认，不能把失败侧 engine 服务过滤直接套到成功侧。
 

package/content/knowledge/common/workflow.md

@@ -6,7 +6,7 @@
 
 - 环境、时间、历史对比的默认值见[公共查询规则](queries.md)的“默认值速查”。用户说“之前没超限”“最近变慢”，就已经是在要历史对比，不用等他再说一句“帮我对比”。
 - 场景清楚就直接进对应的域：[分析表](../dataset/workflow.md)、[组件](../component/workflow.md)、[仪表板](../dashboard/workflow.md)、[更新](../update/workflow.md#更新性能排查)。给的是企业 ID 或 dagId，就从更新进。
-- 只有 trace、执行链接，或者看不出是哪个场景，先读[场景识别](signals.md)。仪表板组件预览入口要按[来源判定](signals.md#仪表板组件预览入口)分流，光看最外层 HTTP span 或 `previewComponent` 这个 span 名分不出来。
+- 只有 trace、执行链接，或者看不出是哪个场景，先读[场景识别](signals.md)。仪表板组件预览入口要按[来源判定](signals.md#仪表板组件预览入口)分流，光看最外层 HTTP span 或 `calc.component`（历史名 `previewComponent`） 这个 span 名分不出来。
 - 用户只给了资源，或者只说“有性能问题”，先挑几条候选执行看看：属于哪个场景、成功还是失败、是 OOM 还是 timeout。不要直接深挖最慢的成功执行。用户已经说了内存超限、OOM、保存失败，就用失败签名作为第一次检索条件，执行类型只当背景信息。
 - 只想拿到或看懂一份 Metric，直接看[引擎知识](../engine/workflow.md)。
 - 实时查询被工具、连接或鉴权挡住了，看[配置 SigNoZ MCP](topics/setup-signoz-mcp.md)，弄好再继续。

package/content/knowledge/component/queries.md

@@ -4,4 +4,4 @@
 
 ## SigNoZ 查询线索
 
-遵循[公共查询收敛规则](../common/queries.md)。资源驱动查询沿用公共规则确定的环境和问题发生时间，在业务 server 的 `service.name` 下组合组件入口 route、`editComponent`/`previewComponent`/`queryData` 与 `component.id` 或 widgetId。仪表板组件预览入口按[来源判定](../common/signals.md#仪表板组件预览入口)定向补取父子链中的上下文属性，不只读取 HTTP 根 span。
+遵循[公共查询收敛规则](../common/queries.md)。资源驱动查询沿用公共规则确定的环境和问题发生时间，在业务 server 的 `service.name` 下组合入口 route、`calc.edit`/`calc.component`/`calc.data` 与 `component.id` 或 widgetId；历史名称按[业务阶段命名](signals.md#业务阶段命名)对应。仪表板组件预览入口按[来源判定](../common/signals.md#仪表板组件预览入口)定向补取父子链中的上下文属性，不只读取 HTTP 根 span。

package/content/knowledge/component/signals.md

@@ -2,15 +2,23 @@
 
 回答“怎样认出入口，各个 span、attribute、日志和字段是什么意思”。
 
+## 目录
+
+- [场景识别](#场景识别)
+- [信号含义](#信号含义)
+- [组件计算的阶段](#组件计算的阶段)
+- [取数结果与失败](#取数结果与失败)
+
 ## 场景识别
 
 已确认的入口包括：
 
 - `POST /v2/design/widget/data`：图表编辑时的取数；
 - `POST /v2/external/widget/data`：仪表板组件预览入口（代码里叫外部组件取数），绝大多数来自仪表板，少数是仪表板以外的图表预览，需要结合请求上下文区分；
-- `POST /v2/query/data`：`queryData` 通用组件查询入口，不能仅凭 span 名补全画布或筛选器上下文。
+- `POST /v2/query/data`：`calc.data` 通用组件查询入口，不能仅凭 span 名补全画布或筛选器上下文。
+- `POST /v2/dashboard/component/data`：V2 仪表板组件取数，也使用 `calc.component`；可取得的上下文与快照以实际属性为准。
 
-已确认的特征 span 包括 `editComponent`、`previewComponent` 和 `queryData`。组件计算链路还可能出现 `getComponentMatrixData`。route 在 SigNoZ 里带部署上下文路径，见[识别方法](../common/signals.md#识别方法)。
+已确认的特征 span 包括 `calc.edit`、`calc.component` 和 `calc.data`。组件计算链路还可能出现 `calc.matrix`。route 在 SigNoZ 里带部署上下文路径，见[识别方法](../common/signals.md#识别方法)。
 
 仪表板组件预览入口的关键 attribute：
 
@@ -21,6 +29,8 @@
 
 ## 信号含义
 
+历史入口 span 名为 `editComponent`、`previewComponent`、`queryData` 和 `getComponentMatrixData`，完整对应关系见下方[业务阶段命名](#业务阶段命名)。
+
 - `component.id` 或用户提供的 `widgetId` 用于关联组件资源；
 - `component.query.table_id` 表示组件查询绑定表，可用于进入分析表调查；
 - 仪表板组件预览入口的 `reportId` 与 request context 按[来源判定](../common/signals.md#仪表板组件预览入口)解释，不能把关联字段直接当作场景结论；
@@ -30,26 +40,60 @@
 
 ## 组件计算的阶段
 
-仪表板组件预览入口（仪表板以外的图表预览也走这里）里，`previewComponent` 之下按顺序是这些阶段：
+仪表板组件预览入口（仪表板以外的图表预览也走这里）里，`calc.component` 之下按顺序是这些阶段：
 
 ```text
 POST /v2/external/widget/data
-└─ previewComponent
-   ├─ data.component.resolvePublishedTable                              取已发布表
-   ├─ data.component.checkPublishedTableStatus                          检查已发布表的状态
-   ├─ data.component.buildControlContext                                把筛选器、联动整理成过滤条件
-   ├─ data.component.checkTableStatus                                   检查表是否可读
-   ├─ data.component.analyzeControlContext                              把过滤条件应用到输入表
-   └─ data.component.executeRequest                                     执行查询
-      └─ data.component.executeSingleQuery
-      └─ QueryExecutor → execute                                        引擎查询：query 提交任务，fetchBlock 轮询取结果
+└─ calc.component
+   ├─ calc.permission        注入权限输入
+   ├─ calc.request           转换本次请求
+   ├─ calc.source            读取发布态
+   ├─ calc.check_sources     校验来源
+   ├─ calc.prepare_controls  整理筛选和联动输入
+   │  └─ calc.conditions     构建条件树
+   ├─ calc.check_table       检查表是否可读
+   ├─ calc.prepare_input     准备输入
+   │  └─ calc.build_query    构建输入查询，写出计算快照
+   └─ calc.execute           执行取数
+      └─ calc.query          单个组件查询
+         └─ QueryExecutor    引擎原生查询阶段
 ```
 
-这是主干，实际 trace 里每段下面还会嵌套不少 span，比如活跃检查 `checkUpdatePolars` 通常挂在 `analyzeControlContext` 之下。用它判断时间花在哪一段：`executeRequest` 一般占 `previewComponent` 的大头，其次是 `analyzeControlContext`，其余几段很短。`executeRequest` 占大头说明时间在引擎。`QueryExecutor` 下的 `query` 只是把任务交给引擎，通常很短；之后反复 `fetchBlock` 取结果，引擎没算完时取到的是空块（`rowCount=0`），所以引擎计算的时间主要落在这些 `fetchBlock` 里，不是传数据慢。具体算在哪，按 `taskName` 取 Metric，见[引擎知识](../engine/README.md)。引擎之前的活跃检查 `checkUpdatePolars` 见[分析表 · 活跃检查](../dataset/signals.md#活跃检查)。
+这是常见主干，阶段随实际分支出现，不要求每条 trace 完整包含这棵树。多查询时，`calc.execute` 下可以出现 `calc.queries`、多个 `calc.query` 和 `calc.result`；查询索引在 `query.index`，实际查询总数在父阶段的 `query.count`，排队耗时在 `query.queue_wait_ms`，不再重复写 `query.total`。
+
+先区分准备输入、构建查询和执行取数的耗时，再结合业务条件与引擎记录判断原因。`calc.execute` 包含查询构建和取数，不能仅凭它耗时就认定是引擎问题。`QueryExecutor` 下的 `query` 提交任务，`fetchBlock` 轮询结果；具体执行分析按 `taskName` 取 Metric，见[引擎知识](../engine/README.md)。输入阶段的活跃检查见[分析表 · 活跃检查](../dataset/signals.md#活跃检查)。
+
+### 业务阶段命名
+
+组件和控件取数主干统一使用 `calc.<阶段>`。名称只表达阶段，表名、组件名和参数值不拼入 span 名；引擎内部和其他业务域的原生名称不改写成业务阶段。下面保留历史名称供旧 trace 检索，不要求目标环境已经升级。
+
+| 当前名称 | 业务含义 | 历史名称 |
+|---|---|---|
+| `calc.edit` | 图表编辑取数 | `editComponent` |
+| `calc.component` | 组件取数入口 | `previewComponent`、`dashboard.componentData` |
+| `calc.data` | 通用组件查询 | `queryData` |
+| `calc.control` | 筛选器候选值入口 | `dashboard.controlData`、`dashboard.filterOptions` |
+| `calc.matrix` | 矩阵取数 | `getComponentMatrixData` |
+| `calc.permission` | 权限输入 | `data.injectAuthorityContext` |
+| `calc.request` | 请求转换 | `data.component.toComponentCalculator`、`dashboard.component.map` |
+| `calc.source` | 读取发布态 | `data.component.resolvePublishedTable`、`dashboard.filterOptions.loadSnapshot` |
+| `calc.check_sources` | 来源校验 | `data.component.checkPublishedTableStatus`、`data.control.validateSourceTables`、`calc.validate` |
+| `calc.prepare_controls` | 筛选和联动输入 | `data.component.buildControlContext`、`calc.context` |
+| `calc.conditions` | 条件树构建 | `FilterConditionsBuilder.build` |
+| `calc.check_table` | 当前表可读性 | `data.component.checkTableStatus`、`calc.ready` |
+| `calc.prepare_input` | 准备计算输入 | `data.component.analyzeControlContext`、`calc.input` |
+| `calc.build_query` | 构建输入查询 | `filter`、`dashboard.component.compile`、`dashboard.filterOptions.compile`、`calc.plan` |
+| `calc.execute` | 执行取数 | `data.component.executeRequest`、`data.control.engineExecute`、`dashboard.component.execute`、`dashboard.filterOptions.execute` |
+| `calc.query` | 单个组件查询 | `data.component.executeSingleQuery` |
+| `calc.queries` | 并行查询组 | `data.component.executeQueries` |
+| `calc.result` | 合并结果 | `data.component.combineResult`、`dashboard.component.result` |
+| `calc.options` | 候选值计算或原生候选查询入口 | `data.control.calculateOptions`、`filterOptions.query` |
+
+旧 `handler` 转发层已移除，输入查询保留 `calc.build_query`。新服务端不为兼容同时创建新旧两套阶段；历史记录仍按当时的名字读取。V2 查询准备后的控件条目数为 `query.control_count`，与入口原始请求的 `controls.input_count` 口径不同，不能相互替代。支持快照的入口在 `calc.build_query` 写出正文；只有阶段名不能证明已采集快照，完整性见[计算快照](../dashboard/topics/calculation-panorama.md#快照字段与含义)。
 
 ## 取数结果与失败
 
-`previewComponent` 上的 `result.status` 是本次取数的结果。图表编辑时（`editComponent`，路径是 `editComponent → data.component.executeSingleQuery → QueryExecutor`）没有 `result.status` 和 `error.class`，错误原文看出错 span 的 `status_message` 和同一 trace 的日志。
+`calc.component` 上的 `result.status` 是本次取数的结果。图表编辑时（`calc.edit`，路径是 `calc.edit → calc.query → QueryExecutor`）没有 `result.status` 和 `error.class`，错误原文看出错 span 的 `status_message` 和同一 trace 的日志。
 
 | 取值 | 含义 |
 |---|---|

package/content/knowledge/dashboard/README.md

@@ -2,6 +2,10 @@
 
 仪表板 2.0的筛选器候选值取数与组件计算。旧版仪表板不在覆盖范围内。
 
+## 能力
+
+支持将同次计算已取得的表依赖、逐表筛选、参数和动态字段生成可独立打开的 HTML 计算关系图。快照字段、展示内容和边界见[计算全景](topics/calculation-panorama.md)，取数与生成方法见[计算全景查询](queries.md#计算全景)。
+
 ## 槽位
 
 每个知识域都按同样的槽位组织。按要做的事选槽位，只读命中的章节。
@@ -22,6 +26,7 @@
 | [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) | 组件计算有多层过滤树、需要还原并展示完整树时 | 筛选树还原与交付 |
+| [topics/calculation-panorama.md](topics/calculation-panorama.md) | 需要了解计算快照或计算关系图能力时 | 快照字段、完整性、历史记录回退，以及计算关系图的展示内容与边界 |
 
 ## 关联
 

package/content/knowledge/dashboard/queries.md

@@ -10,7 +10,7 @@
 
 ## 已有精确 trace
 
-按 `trace_id` 和已确认业务 `service.name` 取得本次入口、组件/筛选器和筛选树记录。必要业务记录包括 `previewComponent`、`FilterConditionsBuilder.build`、`data.component.buildControlContext`、`data.control.calculateOptions`、`data.control.engineExecute`，以及 `data.endpoint=design_control_data` 或有关筛选器/仪表板组件预览入口的 `http.route`。不要求每条记录同时有所有属性。
+按 `trace_id` 和已确认业务 `service.name` 取得本次入口、组件/筛选器和计算记录。业务阶段包括 `calc.component`、`calc.conditions`、`calc.prepare_controls`、`calc.options`、`calc.execute` 和写出快照的 `calc.build_query`，历史名字按[业务阶段命名](../component/signals.md#业务阶段命名)对应。入口还可通过 `data.endpoint=design_control_data` 或相关 `http.route` 识别，不要求每条记录同时有所有属性。
 
 ```text
 trace_id = '<已确认trace>' AND service.name = '<业务服务>'
@@ -20,9 +20,9 @@ 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`；
+- 筛选器影响：`controls.ids/input_count/type_counts/valued_input_count`，涉及参数时加 `controls.has_parameter/parameter_input_count/parameter_ids`；这些是请求统计和检索索引，实际作用位置看计算快照；历史字段按[命名兼容](signals.md#命名与历史兼容)读取；
+- 筛选器自身：`control.id/name/type`、`control.option_source.bindings`，上下文统一读取 `controls.*`；
+- 计算快照：按下方[计算全景](#计算全景)读取同一 `calc.build_query` 的状态、分块和校验字段；旧记录才读取 `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 数也不等于最终生效的筛选数。
@@ -51,7 +51,7 @@ 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#动态字段覆盖与上游展开)处理。
+动态字段选项值、默认值和名称是不同信息。关系请求上报的 `name` 只补名称，历史 `controls.names` 也可能只是筛选器键；不得由二者推断选择值。确认覆盖需要哪些记录、什么时候停止补查，以及 `type=73`、`unbound`、普通参数统计和正数才写入的计数字段，统一按[动态字段覆盖与上游展开](topics/dynamic-fields.md#动态字段覆盖与上游展开)处理。
 
 ## 资源发现与影响范围
 
@@ -64,6 +64,24 @@ AND body CONTAINS '<精确字段ID>'
 
 只有同 report、同组件、同查询表、在可靠短交互窗里、不带目标筛选器的请求才有较强的对照价值；查询指纹没核对时，参数、排序、聚合或数据范围的差异不能靠时间和身份匹配消掉。不默认拿最短的无筛选器请求和最长的有筛选器请求做原因对照。
 
+## 计算全景
+
+先在已选定的计算 span 定向读取 `calculation.panorama.status/schema/part_count/length/sha256`。状态为 `CAPTURED` 时，按返回的块数一次补齐同一 span 的 `part_0...part_N`；已有响应包含分块时直接复用。分块数和长度是数值字段，`fieldDataType` 按当前工具声明选择。
+
+v2 位于实际查询构建的 `calc.build_query` span（历史名为 `filter`），按已有父子关系定位，不要求仍在旧条件构建 span。入口名称按原请求范围关联，不跨执行拼接。字段含义、完整性和历史记录差异见[计算全景快照](topics/calculation-panorama.md#快照字段与含义)；只有历史材料含有旧条件树时，才按下节恢复旧树。缺块或校验失败时先按同一 span 补齐，无法补齐则保留具体缺口，不声称取得了完整快照。
+
+### 生成 HTML
+
+使用 [HTML 生成器](../../scripts/render_calculation_panorama.py)处理保存的 MCP 原始响应或选定快照。生成器负责大材料解析、完整性检查和绘图，不选择执行、不查询业务资源、不推断绑定。展示内容与边界见[计算关系图](topics/calculation-panorama.md#计算关系图)。
+
+源码目录运行：
+
+```text
+python scripts/render_calculation_panorama.py --input <同次快照或MCP响应.json> --output <交付目录/计算全景.html>
+```
+
+安装副本按[固定版本的脚本入口](../../AGENTS.md#安装副本的助手规则)调用。有多份快照时，用 `--span-id` 选择已确认的计算。可用 `--context <说明.json>` 加入已核实的 `traceId`、`componentId`、`componentName`、`time`、`summary`、`evidence` 和 `requestParameters`（ID/name 列表）；这些内容只补请求说明，不修改逐节点事实或推断参数绑定。[离线模板](../../scripts/assets/calculation-panorama.html)由生成器自动使用，无需单独运行。
+
 ## 筛选树
 
 需要树结构时，按上方字段清单取得当前组件或操作的完整路径与 summary，不要求筛选树 span 自带筛选器字段。还原、校验、名称补齐和展示统一按[筛选树还原与交付](topics/filter-tree.md#筛选树还原与交付)执行；沿用本次请求父子范围，不再为展示重复取证。

package/content/knowledge/dashboard/signals.md

@@ -15,34 +15,41 @@
 
 ```text
 POST /v1/design/control/data
-└─ dashboard.controlData
-   ├─ data.control.validateSourceTables   先校验来源表是否被标红
-   └─ data.control.calculateOptions       候选值计算
-      ├─ FilterConditionsBuilder.build    把其他筛选器带来的条件构建成筛选条件树
-      └─ data.control.engineExecute       引擎查询：QueryExecutor → execute
+└─ calc.control
+   ├─ calc.permission       注入权限输入
+   ├─ calc.check_sources    校验来源
+   └─ calc.options          计算候选值
+      ├─ calc.conditions    构建条件树
+      ├─ calc.build_query   构建输入查询，写出计算快照
+      └─ calc.execute       引擎取数
 ```
 
-时间主要花在 `data.control.engineExecute`（引擎），它之前是准备输入表和筛选条件；进入引擎后按[引擎知识](../engine/README.md)解读。仪表板内组件计算的阶段 span 见[组件 · 组件计算的阶段](../component/signals.md#组件计算的阶段)，结果状态和失败类名见[取数结果与失败](../component/signals.md#取数结果与失败)。route 在 SigNoZ 里带部署上下文路径，见[识别方法](../common/signals.md#识别方法)。
+用这些阶段区分来源校验、输入构建和执行取数。`calc.execute` 内再结合引擎 span 与[引擎知识](../engine/README.md)解读，不能仅凭该阶段耗时认定原因在引擎。仪表板内组件计算的阶段 span 见[组件 · 组件计算的阶段](../component/signals.md#组件计算的阶段)，结果状态和失败类名见[取数结果与失败](../component/signals.md#取数结果与失败)。route 在 SigNoZ 里带部署上下文路径，见[识别方法](../common/signals.md#识别方法)。
+
+历史阶段名包括 `dashboard.controlData`、`data.control.validateSourceTables`、`data.control.calculateOptions`、`FilterConditionsBuilder.build` 和 `data.control.engineExecute`，对应关系见[业务阶段命名](../component/signals.md#业务阶段命名)。
+
+V2 的 `POST /v2/dashboard/filter/options` 也使用 `calc.control`；原生 `POST /v2/filter-options/query` 使用 `calc.options`，可由仪表板、指标树或 FVS 发起，不能仅凭这个名称认定业务场景。这些入口的上下文和快照覆盖以实际属性为准。
 
 共享的 `POST /v2/external/widget/data` 按[仪表板组件预览的来源判定](../common/signals.md#仪表板组件预览入口)识别。确认属于仪表板后，组件计算全部由本场景调查。
 
 ## 信号含义
 
 - `reportId`、`reportName`：仪表板或报表资源锚点；
-- `control.id`、`control.type`、筛选器上下文 attribute：标识本次候选值或筛选请求；
-- `control.option_source.table_ids`：候选值可能读取的表，可用于发现分析表关联；
+- `control.id`、`control.type_code`、筛选器上下文 attribute：标识本次候选值或筛选请求；`control.type` 保留历史分类，不等同于原始类型编号；
+- `control.option_source.bindings`：候选值请求的输出来源，包含 `analysis_table:表ID.字段ID` 或 `advanced_component:组件ID.字段ID`，不能当作本次实际扫描关系；
 - `component.id`：仪表板内组件锚点，用于在仪表板模块内定位具体组件计算。
 
-仪表板内组件计算的 `previewComponent` 上，下面几个属性用来看这次请求带入了多少上下文：
+仪表板内组件计算的 `calc.component` 上，下面几个属性用来看这次请求带入了多少上下文：
 
 | 属性 | 含义 |
 |---|---|
-| `controls.effect_count`、`controls.valued_effect_count` | 本次请求带入的筛选器影响数，以及其中有取值的个数 |
+| `controls.input_count`、`controls.valued_input_count` | 本次请求带入的筛选器影响数，以及其中有取值的个数 |
+| `controls.parameter_input_count`、`controls.parameter_ids`、`controls.has_parameter` | 普通参数筛选器的影响数、检索 ID 和是否存在；实际用途看计算快照 |
 | `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)。
+筛选器数多不等于慢，要结合筛选树和引擎耗时判断。`controls.*`、计算快照及历史 `filter_conditions.*` 的读法见[查询方法](queries.md)与[筛选树](topics/filter-tree.md)。
 
 ### 筛选器候选值请求的属性
 
@@ -53,15 +60,30 @@ POST /v1/design/control/data
 | `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.query.row_count` | 引擎实际返回的行数（含已选值）；等于 `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.options.page`、`page_size`、`keyword_count`、`selected_value_count` | 请求的页码、页大小、关键字个数、已选值个数 |
+| `control.result.candidate_count` | 本次取得、排除已选项后、翻页前的候选数；受取数上限影响，不能直接当作全部候选总数 |
+| `control.result.row_count`、`value_count`、`has_next` | 在入口统一记录文本候选响应：普通分页的行数、实际返回的值个数、是否还有下一页；全选仅计数时行数可大于零而值个数为零 |
+| `result.status` | 最终结果状态；`empty` 表示文本候选结果为空，非文本结果不补造数量 |
+| `controls.*` | 两种取数入口统一使用的控件影响统计和检索 ID；名称、条件与参数作用位置见计算快照 |
+
+读法：候选值慢时，先看 `control.query.mode` 和 `control.query.unbounded`（全选没有取数上限，最容易慢），再看 `control.option_source.truncated` 和 `distinct_count`（来源很多时会被截断），最后看 `control.query.row_count` 与 `control.result.candidate_count` 判断本次取得的数量。
+
+### 命名与历史兼容
+
+自定义属性使用小写、点分层和下划线，数量使用 `_count`；`reportId/reportName` 等公共字段及计算快照 JSON 的既有字段保持兼容。新记录只写当前名称，历史记录按下表读取，不要求同时存在新旧字段。
+
+| 当前字段 | 历史字段与读法 |
+|---|---|
+| `controls.input_count/valued_input_count/parameter_input_count/type_counts` | 对应 `controls.effect_count/valued_effect_count/parameter_effect_count/effect_type_counts`；均按输入条目统计 |
+| `controls.field_binding_count/advanced_component_binding_count` | 对应带 `_effect_count` 的旧名称，统计口径不变 |
+| `control.type_code` | 原 `control.filter_type`，表示控件类型编号，不能当作筛选运算符 |
+| `control.option_source.bindings/target_count/component_input_count` | 原 `control.sources`（更早为 `control.option_source.binding_info`）、`control.option_source.table_count/advanced_component_count`；分别是字段绑定、去重后的原始目标数、高级组件字段输入数。目标可能是表或组件，不能当作实际参与计算的表数 |
+| `control.options.page_size/keyword_count/selected_value_count` | 原 `pageSize/keywords.size/selectedValues.size` |
+| `control.query.row_count`、`control.result.candidate_count/row_count/value_count` | 原 `control.query.output_rows` 与 `control.result.candidate_size/row_size/value_size`；旧 `option_count` 仅在文本结果中可作返回行数理解，旧 `control.result.empty` 可结合 `result.status` 读取 |
 
-读法：候选值慢时，先看 `control.query.mode` 和 `control.query.unbounded`（全选没有取数上限，最容易慢），再看 `control.option_source.truncated` 和 `distinct_count`（来源很多时会被截断），最后看 `control.query.output_rows` 与 `candidate_size` 判断返回量。
+新版入口只保留检索 ID、请求统计和结果，筛选正文、名称及逐表参数关联统一在[计算快照](topics/calculation-panorama.md#快照字段与含义)中读取。候选值的输出来源只写 `control.option_source.bindings`，不再另写来源表 ID 列表和绑定摘要。历史 `control.context.*`、`controls.names`、`controls.parameter_names`、`controls.parameter_bindings`、`controls.binding_info`、`controls.raw_binding.*` 不再由新版写出，缺失不能解释成没有条件。
 
 ### 怎么读这些属性
 
@@ -69,8 +91,8 @@ POST /v1/design/control/data
 
 - 筛选器候选值请求只受其他筛选器的影响；组件请求的影响因素不限于筛选器，查询、绑定表、`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 按完整值匹配，不用前缀。
+- 历史 `controls.binding_info` 形如 `名称(id){type=N}->[analysis_table:tableId.fieldId]`，也可能是 `advanced_component:`、`parameter:` 或 `unbound`（旧版没有类型前缀）；它和 raw binding 只是摘要，完整关系以筛选树和请求内容为准，组件目标不能按 ID 巧合挂到分析表节点。表名、字段名要从同一仪表板的只读配置或资源元数据补，不从 ID 推断。
+- `controls.input_count` 是这次请求 control Map 的条目数，不是画布上的筛选器数；历史名为 `controls.effect_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/calculation-panorama.md

@@ -0,0 +1,38 @@
+# 仪表板计算全景
+
+说明仪表板这次计算依赖哪些表、筛选和参数在哪里参与，以及 HTML 计算关系图能力。排查顺序与业务假设见[仪表板入口](../workflow.md)，取数和脚本调用见[计算全景查询与生成](../queries.md#计算全景)。
+
+## 快照字段与含义
+
+`calculation.panorama.schema=calculation-panorama-v2` 记录本次实际查询构建。表名、参数名和筛选正文集中保存，通过 ID 关联作用位置；共享对象和同类边只记一次。新版不再双写旧 `filter_conditions.*` 树、路径和摘要，层数、路径及数量由图数据计算。是否已部署以目标记录为准，不假定历史 trace 含有新快照。
+
+支持快照的入口在本次输入查询的 `calc.build_query` 阶段写出正文（历史名为 `filter`）；V2 查询也使用该阶段名，但不能据此认定已采集计算快照，须检查实际属性。入口保留检索 ID、结果和请求统计，名称、筛选正文与参数作用位置在快照中只保存一份；ID 在引用和检索位置出现不等于重复正文。两种入口的控件摘要统一为 `controls.*`，候选值输出来源另存 `control.option_source.bindings`，它不能代替实际依赖。历史绑定摘要只用于旧记录，不要求新版同时提供。
+
+- `calculation.panorama.status=CAPTURED` 表示快照已生成；同一 span 的 `part_count`、`part_0...part_N`、`length`（UTF-16 长度）和 `sha256` 用于核对完整性。`OVERSIZE`、`FAILED`、缺块、长度或摘要不符均不算完整；不能混用不同 span 的分块。
+- `tables` 是本次涉及的表，`dependencies` 是实际查询构建时观察到的来源到使用者关系，包含直接读取的来源，不额外查询祖先血缘。`nodes` 与 `conditionEdges` 保留本次条件对象及传播关系；节点 `id` 区分同表不同实例，`tableId` 对应表。条件传播和实际扫描是不同事实；条件涉及但未读取的表不能认作本次重算。
+- `conditions` 集中记录筛选正文，节点的 `fieldFilters`、`componentFilters`、`linkageFilters` 以及步骤只引用筛选 ID；节点另有 `parameters` 和 `dynamicFields`。筛选保留字段、运算符与 AND/OR/NOT 组合；`valueState` 的 `REDACTED`、`UNAVAILABLE`、`TRUNCATED` 分别表示脱敏、未取得、截断，不能补猜值。
+- 条件的 `fieldTransforms` 保留字段变换，如按年、按月、求和及请求中的分组。HTML 把变换写在字段旁；`UNAVAILABLE`、`TRUNCATED` 要明确显示细节未记录或未采集完，不能简化成原字段比较。历史快照缺少此字段时，不补猜变换。
+- `tables[].fields` 按表保存本次涉及字段的显示名；先去掉已确认的所属表前缀，再按本表字典解析，不能用别表同名字段补名。`kind=INLINE_QUERY` 是实际计算中的内联子查询，其 ID 是计算实体标识，不能当业务表去查名称。`componentName` 是本次请求携带的组件名称；名称为空不能用另一个组件或结果表名替代。
+- 条件 `parameterIds` 是原始筛选翻译时确认的参数引用，`valueState=PARAMETER` 表示整个比较值就是参数，可直接显示“金额 ≥ 参数「最低金额」”。组合条件自身的参数引用只说明整组涉及该参数，不能分配给未知的子条件。前后 N 项也遵守相同脱敏规则，展示为“金额 取前 参数「展示数量」 项”或“金额 取后 ［值已脱敏］ 项”。其他结构不补写未知公式。`dynamicDefinitions` 给出命中的动态项名称和默认字段，节点 `dynamicFields` 给出本次选择；据此显示“分组：区域 → 渠道”。`controls` 集中保存实际使用的来源名称、原请求 ID 和类别，区分普通控件、行权限、组件联动、值联动、参数控件和动态字段控件。`conditionControls` 通过条件 ID 说明来源；参数及动态字段覆盖项的 `controlIds` 说明由哪个控件改变，同请求键的不同来源不能借用名称。历史快照没有覆盖项来源时不补猜；权限条件用“行权限”说明，业务值继续脱敏。
+- 节点参数 `id` 对应快照 `parameters` 名称表；`sources=TABLE` 表示分配给该表的覆盖输入，`COMPONENT` 表示组件带入，同一参数可同时有两种来源，`UNKNOWN` 保留未知。是否实际用于筛选，需要结合条件引用与读取方式，不能仅凭分配就认定已生效。根节点可能合并两类参数，不能把组件参数自动认作目标表的配置绑定。旧 `filter_conditions.parameter_ids` 只是全树集合，`controls.parameter_bindings` 是筛选器到参数关系，均不能代替逐表对应关系。
+- `tables[].definition` 保存本次读取方式和表内筛选。`READ_MATERIALIZED` 表示直接读取已有结果，`EXPANDED` 表示重新展开；`REUSED_INPUT` 表示复用已有查询输入，其内部条件不可得时用 `REUSED_INPUT_DETAILS_UNAVAILABLE:<表 ID>` 标明缺口，不能把未执行的准备算子当作本次筛选。`filters` 列表只保存非空筛选组的条件引用，不记录步骤 ID、算子类型或无筛选步骤。同表不同读取方式或筛选组保存在 `variants`，展示时全部保留，不能只取第一份；相同记录不重复输出。`componentDefinition` 保存实际执行的组件追加筛选，组件追加阶段复用已有输入而跳过准备算子时记录 `COMPONENT_INPUT_REUSED`。缺失只说明记录中没有对应读取方式，不能证明本次没有读取，也不能用当前或发布配置补造本次事实。公式、子查询内部条件不猜测展开。
+- `scope=QUERY_BUILT` 表示查询构建成功，不表示引擎已执行成功；`BUILD_FAILED` 保留失败前确认的事实，图必须标明未完成。重复构建或失败后重试时，保留预编译输入的参数和控件关联，实际依赖、读取方式和表内筛选只来自本轮；参数字典只覆盖本轮引用与保留输入，不包含未使用的预取条件或前次运行条件。
+- `componentStages` 的 `source=REQUEST` 表示本次请求明确配置的组件筛选，`DETAIL` 为汇总前明细筛选，`RESULT` 为组件结果筛选，作用于根表，条件正文仍引用 `conditions`。这些输入在同步构建阶段记录，不代表后续编译或执行已经成功；实际展开仍以 `dependencies`、读取方式及表内筛选为准。历史记录缺少 `source` 时沿用当时的编译条件含义。未提供这些字段的入口明确说明缺口。
+- 服务端补名失败或资源已不存在时，`TABLE_NAMES_MISSING` / `PARAMETER_NAMES_MISSING` 表示名称尚未补齐，不能把快照称作完整计算全景；展示时保留 ID 并明确缺口。`gaps`、`omittedNodes`、`omittedEdges`、条件截断及 `notCaptured` 必须随图展示。表与条件对象各最多 512，关系、算子检查、筛选内容及覆盖项在采集时有预算限制，达到上限标记 `*_LIMIT`，不影响原计算继续执行；省略数量不一定可知。正文最多 16 块，每块不超过 8000 个 UTF-16 单元，过大明确记 `OVERSIZE`。空数组仅在对应采集未省略的范围内证明该类直接条件为零。
+
+历史 `calculation-panorama-v1` 的依赖来自逻辑血缘，`INPUT` 是根表输入配置，`PUBLISHED` 仅为发布配置对照，不能当作本次实际展开。更旧记录仍可使用已有[条件树](filter-tree.md#筛选树还原与交付)；新观测不能补回历史缺失的事实。已有性能聚合指标保留原用途，不能代替业务关系。
+
+## 计算关系图
+
+支持将同次计算已取得的表依赖和逐表条件生成可独立打开的 HTML 图，展示多层、多分支、共享上游及跨表条件关系。图中的连线表示本次结果依赖哪些表，节点展示筛选、参数和动态字段的作用位置；请求调用关系和引擎算子属于其他层次。
+
+名称缺失时用 ID，关系不全时展示能证实的局部范围并标注缺口；生成图不需要先确认唯一原因。完全没有可证实的关系或文件生成受阻时，说明具体限制，不编图或声称已经生成。
+
+- **范围与关系**：注明业务对象、执行和来源，画全所选范围内已知的节点与边，方向为“上游来源 → 下游使用者 → 当前结果”。同表的不同条件对象保持可区分，共享上游不等于重复执行；旧树的身份、计数与环路按[筛选树](filter-tree.md#选定结构与完整性)核对。条件展开树不冒充完整产品血缘。
+- **图形主视图**：只保留按上下游排布的表节点和带箭头的连线。同一张表只画一次，多个下游直接连到它，不另设共享区、共享编号或引用卡片。表格、路径或缩进列表只作补充。大图可缩放、滚动或查找，全部节点与明细应能访问。
+- **逐表条件**：节点内只展示本节点直接记录的字段筛选、参数、动态字段和联动，优先展示名称与可读条件，不只写数量。参数要说明是本次传入还是本表实际使用；有明确关联时写进对应的筛选或公式，没有关联就标明“具体用途未记录”，不按名称或数值猜用途。不汇总或重复列出上游条件，上下游关系由连线表达。ID、条件对象和步骤信息收起查看；同表不同条件对象分组保留，不合并成一组同时生效的条件。条件是否直接作用于本表，按[名称、绑定与展示](filter-tree.md#名称绑定与展示)判断。全局请求参数只作上下文，不自动分配到表节点。
+- **缺失与推测**：随图展示采集缺口、截断和未采集范围，不补造关系。可疑路径或优化建议与已确认关系分开，并注明依据与业务前提；不要求每张图都附原因判断或优化方案。
+
+HTML 应能独立打开，数据、样式和脚本内嵌；保存到本次临时产物或客户端交付目录，按[诊断材料边界](../../../AGENTS.md#3-诊断原则)脱敏，不把真实业务材料写入仓库，日志与参数按文本安全转义。生成方法见[计算全景查询与生成](../queries.md#计算全景)。
+
+生成后核对图与原始关系、逐表条件一致；可预览时打开 HTML，检查首屏确有节点与连线、标签可读、共享上游可辨，主要交互可用。生成结果通过可打开的文件链接提供，数量摘要、文本示意或“可以画图”不能代替实际文件。无法生成或预览时如实说明限制，后续补充名称或条件复用已有图和记录。

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

@@ -8,13 +8,13 @@
 
 | 记录 | 能确认什么 | 还需核对什么 |
 |---|---|---|
-| `controls.ids`、`controls.effect_type_counts`、有值计数 | 请求带入了哪类筛选器项 | 最终是否生成覆盖；需要定位时核对绑定与树中位置 |
-| `filter_conditions.dynamic_field_count>0`、节点 `dynamic=N` 且 `N>0` | 最终条件树包含动态字段覆盖；节点摘要还可定位所在表路径 | 实际计划是否展开上游，以及对应计算和资源压力 |
+| `controls.ids`、`controls.type_counts`、有值计数 | 请求带入了哪类筛选器项 | 最终是否生成覆盖；需要定位时核对绑定与树中位置 |
+| 快照节点 `dynamicFields` 非空，或旧树 `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` 也可能只是普通字段绑定摘要为空，不能反证动态字段没有绑定或生效。筛选器名称缺失时，名称摘要可能退回到这个键。
+`controls.ids` 中的 `parameter:<id>` 可能只是请求 Map 的键，不能据前缀认定普通参数。`controls.has_parameter`、`controls.parameter_*` 只统计普通参数筛选器，不覆盖动态字段筛选器；它们为 false/零不能排除动态字段影响。历史 `controls.binding_info` 的 `unbound` 也可能只是普通字段绑定摘要为空，不能反证动态字段没有绑定或生效。旧名称摘要可能退回到这个键；新版名称和实际覆盖从[计算快照](calculation-panorama.md#快照字段与含义)读取。
 
 `filter_conditions.*_count` 的部分字段只在正数时写入；工具投影的零或 false 可能是缺字段默认值。优先用完整 `tree_summary` 中明确的五类计数核对零值，不由投影零值构造“无条件”对照。`dynamic_field_count` 为 0、`tree_summary` 也为空时，对用户说“这次没看到动态字段覆盖”就够了，不用列成缺口。计数摘要没有选项值和字段名，不意味着请求或关联日志也没有。
 

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

@@ -1,8 +1,10 @@
 # 筛选树还原与交付
 
+有新版[计算全景快照](calculation-panorama.md#快照字段与含义)时优先使用其中的实际查询依赖和条件作用关系；下面的路径还原规则用于旧版条件摘要，不把两者覆盖范围混同。
+
 组件计算存在多层、多分支过滤树，或判断依赖筛选器所在层级时，必须按本节校验并输出完整树结构。小而完整的树可直接解释；节点数、最大深度或筛选器数量不能代替树结构。
 
-筛选结构可记录 `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 详情缺自定义属性时，使用同执行的定向查询补齐。
+筛选结构可记录 `filter_conditions.root_table_id`、`node_count`、`path_node_count`、`max_depth`、`table_ids`、`table_paths`、`tree_summary` 及各类过滤数量。新版阶段名见[业务阶段命名](../../component/signals.md#业务阶段命名)；本节旧条件树对应的历史链路可出现 `data.control.calculateOptions`、`data.control.engineExecute`，不能只按 `controlData` 查找。默认 trace 详情缺自定义属性时，使用同执行的定向查询补齐。
 
 `node_count` 表示去重后的条件对象数量，`path_node_count` 表示沿不同路径访问对象的次数。共享对象可在多条路径上重复出现，对应 summary 保留五类过滤计数并标记 `shared=true`；同一个 tableId 不足以证明同一个条件对象，不能按表 ID 去重。展示时保留完整路径，在重复访问处标注共享，避免把多条路径当成多份独立业务对象。
 
@@ -28,8 +30,14 @@
 
 从同一 dashboard/report 的只读配置或资源元数据中，一次取得所选完整树所需的 tableId/fieldId 名称映射；只有筛选器 ID 时按[名称与请求上下文的关联取证](name-binding.md#名称与请求上下文的关联取证)核对已有关系请求。每个 ID 只查询一次，将名称补入树中，不根据 ID 形态猜名称。
 
-每个节点标注“表名（tableId）”及字段筛选、组件筛选、参数、动态字段、联动筛选五类 summary 是否存在；明确零条件时写“筛选：无”，缺失字段保持未知。筛选器字段筛选和绑定显示“字段名（fieldId）”，有依据时补充“绑定候选筛选器 + 绑定字段名（fieldId）”。名称不足时保留 ID，并列出缺少名称的表 ID 和字段绑定，不为补名称阻塞已成立的性能结论。
+每个节点标注“表名（tableId）”及字段筛选、组件筛选、参数、动态字段、联动筛选五类 summary 是否存在；五类均明确为零时写“本节点五类直接条件：无”，缺失字段保持未知。筛选器字段筛选和绑定显示“字段名（fieldId）”，有依据时补充“绑定候选筛选器 + 绑定字段名（fieldId）”。名称不足时保留 ID，并列出缺少名称的表 ID 和字段绑定，不为补名称阻塞已成立的性能结论。
+
+历史 `controls.binding_info` 与节点表匹配，只能建立绑定候选关系，不能证明筛选器产生了该节点的条件或实际生效。来源与生效范围须有明确的条件关联和执行记录。入口级权限信号没有节点位置时，作为树外上下文说明，不随意挂到表节点。
+
+逐表参数与筛选还需区分以下信息，图形展示内容与边界见[计算关系图](calculation-panorama.md#计算关系图)：
 
-`controls.binding_info` 与节点表匹配，只能建立绑定候选关系，不能证明筛选器产生了该节点的条件或实际生效。来源与生效范围须有明确的条件关联和执行记录。入口级权限信号没有节点位置时，作为树外上下文说明，不随意挂到表节点。
+- 节点有参数 ID 时，按完整 ID 关联请求中的名称和值；只有 `parameter=N` 时只确认数量，并写“参数身份未记录”。全局刚好有 N 个参数也不能据此把名称分配给该节点。
+- 节点只展示直接记录的条件和参数，上下游影响由连线表达，不再列“受上游条件影响”。节点直接参数为零，不代表不受上游参数影响，也不能据此给下游节点补写参数绑定。
+- 五类计数的明确零只说明该节点该类条件为零，不代表表定义、权限或整个查询不存在其他筛选。表达式、字段、操作符和值取得多少展示多少，缺失写“未记录”，不由计数猜条件内容。
 
 完整性只证明所选结构已覆盖，不证明配置合理、交互影响唯一或筛选器导致耗时增加；这些判断仍需业务配置、执行和必要对照。

package/content/knowledge/dashboard/workflow.md

@@ -2,6 +2,8 @@
 
 仪表板 2.0 的筛选器候选值或组件取数慢时从这里下手，旧版仪表板不在范围内。只有两类取数：筛选器自身取候选值，和组件取数。首次加载、筛选值变化、参数变化和联动只是组件取数的触发上下文，不算单独的场景。仪表板组件预览入口先按[来源判定](../common/signals.md#仪表板组件预览入口)确认；概念、信号、结论、查询分别见本域的 [concepts](concepts.md)、[signals](signals.md)、[conclusions](conclusions.md)、[queries.md](queries.md)。
 
+本域提供的能力与知识索引见[仪表板知识](README.md)。
+
 ## 入手
 
 - 报错落在引擎里（超时、内存超限）时，引擎只说明撞了什么线，原因回到下面还原的业务计算里找。

package/content/knowledge/engine/queries.md

@@ -66,7 +66,7 @@ trace_id = '<trace>' AND service.name = '<已确认业务服务>'
 ### 从 trace 整理任务绑定
 
 1. 先确认结果完整：带下一页游标、`hasMore`、截断标记，或行数到了查询上限，都说明候选不全，先补齐或说明缺口。
-2. 只列上表三类 span：`span_id`、父 span 名和 ID、task（`taskName` 或 `polars.taskId`）、有没有 `metric`、错误状态、耗时。业务入口（如 `operatorsPage`、`previewComponent`）单独记，不是任务 span。
+2. 只列上表三类 span：`span_id`、父 span 名和 ID、task（`taskName` 或 `polars.taskId`）、有没有 `metric`、错误状态、耗时。业务入口（如 `operatorsPage`、`calc.component`（历史名 `previewComponent`））单独记，不是任务 span。
 3. 分几次补到的属性按 `span_id` 合并；同一 span 的值冲突时都留着，不用后到的覆盖。
 4. 不属于这三类、但带 task 或 metric 字段的记录列为“未识别记录”，不丢弃。
 5. 按上面的规则选执行，多个候选都可信时全部保留。