@fx-data/ai-diagnostics 0.1.20261111014808 → 0.1.20261111030608

package/AGENT_SETUP.md

@@ -1,6 +1,6 @@
 # FX 数据诊断：Agent 安装与管理
 
-本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261111014808`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
+本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261111030608`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
 
 用户明确要求安装、更新、回退、卸载或检查 FX 数据诊断时，也会触发薄 Skill，并直接执行对应管理命令，不先运行 `context` 或读取诊断规则；只有开始诊断时才按薄 Skill 加载内容。普通聊天不主动加载。
 
@@ -56,7 +56,7 @@
 
 用户明确要求用 FX 数据诊断分析问题后，按薄 Skill 调用一次稳定入口的 `context`，读取返回的 `agent_rules`，只加载当前问题需要的 Skill 和引用。CLI 同时在后台检查更新，固定本次调查返回的版本与 `pinned_cli`；同一调查继续复用，不重复调用稳定入口的 `context`。普通聊天和管理请求无需预加载诊断内容或检查更新。
 
-已有 SigNoZ MCP 直接复用；实时查询受阻时才按包内配置 Skill 处理，凭据只保存在本机。Python 按需准备；独立解释器可通过 `FX_DATA_DIAGNOSTICS_PYTHON` 指定绝对路径。
+已有 SigNoZ 查询途径（MCP、Skill 等）直接复用；实时查询受阻时才按包内配置 Skill 处理，凭据只保存在本机。Python 按需准备；独立解释器可通过 `FX_DATA_DIAGNOSTICS_PYTHON` 指定绝对路径。
 
 ## 更新与回退
 

package/README.md

@@ -38,4 +38,4 @@
 
 ---
 
-**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261111014808/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。
+**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261111030608/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。

package/bin/core-ai.mjs

@@ -189,7 +189,7 @@ context 返回当前版本、内容路径和 agent_rules。读取 agent_rules，
 
 context、status、session 的 auto_update.notification，以及 python 标准错误中 fx_data_diagnostics.auto_update.notification，是更新提示。有提示时按 message 简短告知用户；无新版不打扰。不为获取状态额外调用 CLI 或轮询；本轮没有后续 CLI 调用时，下次使用再补报。更新成功只影响下次新诊断，失败继续使用本次版本。
 
-当前调查固定使用首次 context 返回的 node、pinned_cli 和内容版本。脚本通过 <node> <pinned_cli> python <脚本绝对路径> ... 执行；Windows PowerShell 同样在带引号的 Node 路径前加 &。通过 session 获取临时目录，保存日志和 Metric 正文，不写入安装内容。只有包内 Python 脚本需要 Python；doctor 的 python.available=false 表示按需补齐，不代表安装失败。已有 MCP 直接复用；实时查询受阻时才读取 setup-signoz-mcp。
+当前调查固定使用首次 context 返回的 node、pinned_cli 和内容版本。脚本通过 <node> <pinned_cli> python <脚本绝对路径> ... 执行；Windows PowerShell 同样在带引号的 Node 路径前加 &。通过 session 获取临时目录，保存日志和 Metric 正文，不写入安装内容。只有包内 Python 脚本需要 Python；doctor 的 python.available=false 表示按需补齐，不代表安装失败。已有 SigNoZ 查询途径（MCP、Skill 等）直接复用；实时查询受阻时才读取 setup-signoz-mcp。
 
 用户要求更新时执行稳定入口 update，默认使用 latest；要求回退到上次更新前时执行 rollback，也可用 --version 指定版本。已保留版本校验通过后直接复用。各客户端的新调查共用切换后的版本，进行中调查继续使用原 pinned_cli。更新后按客户端要求刷新技能或新开聊天；安装副本不做 Git 更新。
 

package/content/README.md

@@ -20,7 +20,7 @@
 npm 安装：对 Agent 说“帮我安装并启用 FX 数据诊断，npm 包是 `@fx-data/ai-diagnostics`”，它会按包内 README 安装（优先复用已有的共享安装），再登记当前客户端的 Skill。需要 Node.js/npm，Python 按需准备。安装副本每次新诊断时在后台检查更新，不耽误当前排查，更新失败继续用旧版（设计见源码仓库 `maintainers/npm-cli.md`）。
 
 1. 用源码目录时，用支持 `AGENTS.md` 的客户端（如 Codex、Claude Code）打开本仓库，更新规则见[助手执行契约](AGENTS.md#使用前更新代码)。
-2. 诊断要查 SigNoZ 的 trace、日志和引擎统计。还没有连接时助手会自动配置，只需提供对应环境的 API Key（正式、测试分开）。
+2. 诊断要查 SigNoZ 的 trace、日志和引擎统计。还没有连接时助手会自动安装和配置，只需按提示在本机配置里填入对应环境的 API Key（正式、测试分开），不要把 Key 发在对话里。
 3. 只有离线材料（日志、trace 导出、Metric 文件）时不用配置，直接交给助手。
 
 ## 如何提问
@@ -54,6 +54,7 @@ npm 安装：对 Agent 说“帮我安装并启用 FX 数据诊断，npm 包是
 
 - 当前结论：哪个对象的哪次操作出现问题，已定位到什么环节或条件。
 - 关键依据：对应执行记录、错误、统计或对照结果，以及它们如何支持判断。
+- 计算关系图：支持将同次计算已取得的依赖与逐表条件生成可独立打开的 HTML 图，能力与知识索引见[仪表板知识](knowledge/dashboard/README.md#能力)。
 - 待确认信息（有实质缺口时）：仍需确认的问题和最小补充材料；需要研发接手时整理可继续调查的材料。
 - 需求反馈（有依据时）：本轮发现的未覆盖场景、知识缺口或工具改进线索，供后续改进本项目。使用者无需提供开发方案或跟踪处理。详见[诊断后的需求反馈](docs/diagnostic-feedback.md)。
 

package/content/docs/index.md

@@ -35,6 +35,10 @@
 | 常见引擎性能问题的判断方法 | [常见引擎性能问题](../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#选哪个配方) |

package/content/knowledge/automation/queries.md

@@ -4,7 +4,7 @@
 
 ## 按 workflowId 查
 
-**列出每次执行**（默认最近 7 天，周期更长时放宽）：
+**列出每次执行**（默认最近 3 天；按周或更长周期执行、3 天内没有记录时，再放宽到覆盖一个周期）：
 
 ```text
 body CONTAINS '[Workflow] executor result' AND body CONTAINS '<workflowId>'
@@ -18,7 +18,7 @@ body CONTAINS '[Workflow] executor result' AND body CONTAINS '<workflowId>'
 body CONTAINS '<workflowId>'
 ```
 
-用日志搜索即可，7 天窗口可用。不要按 `body` 分组做 7 天聚合，容易超时。
+用日志搜索即可。时间窗越长越慢，放宽时也只做日志搜索，不要按 `body` 分组做多天聚合，容易超时。
 
 ## 看单次执行
 

package/content/knowledge/automation/workflow.md

@@ -6,7 +6,7 @@
 
 大多数问题都从 workflowId 开始，查询写法见[按 workflowId 查](queries.md#按-workflowid-查)。
 
-1. 用 workflowId 搜日志，默认看最近 7 天，先按 [`[Workflow] executor result`](signals.md#定时执行的时间线) 列出每次执行的时间、触发方式、动作数和失败数。周期比 7 天长时放宽时间窗。
+1. 用 workflowId 搜日志，默认看最近 3 天，先按 [`[Workflow] executor result`](signals.md#定时执行的时间线) 列出每次执行的时间、触发方式、动作数和失败数。按周或更长周期执行、3 天内没有记录时，再放宽到覆盖一个周期。
 2. 要看某一次，拿这次的 `trace_id` 查同一 trace 的日志。一次执行的条件判断、动作和回填都在这条 trace 里，动作级的日志不带 workflowId，只能这样串起来。
 3. 有失败就看 [`[WorkflowAction] Execute failed`](signals.md#动作失败的常见报错) 的异常消息。回填要继续看[回填的后半段](signals.md#回填的后半段)，第 1 步的成功只说明消息已经发出。
 4. 没有执行记录时，按触发方式核对[查不到记录时能说什么](conclusions.md#查不到记录时能说什么)。

package/content/knowledge/common/concepts.md

@@ -13,7 +13,7 @@
 
 `prod` 和 `production` 不是正式环境的别名。`prod` 在后端语境里是测试 SigNoZ 实例下的一个服务子环境；`production` 目前没有确认过的含义，不参与自动识别。
 
-有的客户端只连一个 SigNoZ MCP，靠工具的 `env` 参数切环境：正式环境传 `work`，测试环境按下面后端子环境的名字传；`env=prod` 查的是测试实例，不是正式环境。
+访问途径不限于每个环境一个 MCP：有的 MCP、Skill 或其他工具一个就能查多个环境，靠环境参数或选项切换。按它自己的环境名和说明对上正式、测试实例，常见约定是正式环境叫 `work`；这类工具里的 `prod` 同样指测试实例下的子环境，不是正式环境。
 
 推荐 MCP 名称只是为了各客户端叫法一致。客户端已有别的稳定名称就保留，以连接信息里的 URL 为准；调用方式和参数以当前客户端实际提供的工具为准。已经确认的环境和本轮成功的查询直接复用，不因为工具前缀不同就重新安装或验证。
 
@@ -45,5 +45,5 @@ SigNoZ 实例和后端 `service.name` 是两层信息。查后端请求时两者
 - 缺时间时不顺带让用户选环境。时间等入口默认值见[公共查询规则](queries.md)的“默认值速查”。
 - 环境一旦确认，这次诊断的 trace、日志和 metric 都只查这个环境，不混用别的环境的数据。
 - `service.environment` 这类 attribute 只能在当前实例里过滤，代替不了选实例。
-- MCP 能读某个环境的 SigNoZ，不代表业务页面链接也有同样的权限。
+- 工具能读某个环境的 SigNoZ，不代表业务页面链接也有同样的权限。
 - 测试和正式环境的 API Key 分开维护，不能混用或互相覆盖。

package/content/knowledge/common/queries.md

@@ -15,7 +15,7 @@
 
 | 情况 | 默认处理 |
 |---|---|
-| 未指定环境 | 默认 work（正式环境），显式环境、URL 和已确认范围优先；映射见[环境选择规则](concepts.md)。SigNoZ 工具带 `env` 参数时，正式环境传 `work`；`prod` 是测试实例下的子环境，不是正式环境 |
+| 未指定环境 | 默认 work（正式环境），显式环境、URL 和已确认范围优先；映射见[环境选择规则](concepts.md)。工具能切多个环境时按它的环境名选正式环境（常见是 `work`）；`prod` 是测试实例下的子环境，不是正式环境 |
 | 普通对象（tableId、widgetId、reportId 等）没有时间 | 完全缺少时间时合并询问一次时间，不同时要求选择环境，不要默认最近 7 天 |
 | 企业更新没有时间或只说“最近” | 企业更新无时间默认最近 24 小时，告知后直接查询，优先核对异常 |
 | 只有 dagId | dagId 不先追问时间，由助手管理检索窗口，命中后按实际记录恢复链范围 |
@@ -25,7 +25,7 @@
 
 ## 选择和调用工具
 
-- 先列出已连接 SigNoZ 的工具名，只读这次要用的那个工具的说明；读过一次就复用，不要把全部工具说明都输出一遍。调用方式以客户端实际的工具声明为准，按[环境选择规则](concepts.md)核对目标 URL，工具前缀和推荐名称不一样不用重配。
+- 先确认当前可用的 SigNoZ 查询途径（MCP 工具、Skill 等），只读这次要用的那个工具的说明；读过一次就复用，不要把全部工具说明都输出一遍。调用方式以该途径实际的声明或说明为准，按[环境选择规则](concepts.md)核对目标 URL，工具前缀和推荐名称不一样不用重配。
 - **已有 traceId 时**，便捷的 span 搜索和详情工具只返回 span 名、耗时、错误这些基本列，不带 `taskName`、`metric`、`data.request_context` 这类自定义 attribute。按这个顺序取：
   1. 日志按 `trace_id` 查一次，常常就能拿到报错原文、引擎任务 ID 和请求结束时间，比翻 trace 便宜。
   2. span 搜索按 `trace_id` 加 `has_error = true`、span 名或 `duration_nano` 取关键的几条 span，看时间线和错误。
@@ -46,7 +46,7 @@
 | tableId、widgetId、reportId 等资源 ID | 按默认或显式环境及发生时间，使用场景入口、服务和资源 attribute 寻找候选执行 |
 | 企业 ID（更新查询） | 复用已有时间；未提供时告知默认最近 24 小时后直接查询，先给更新概况并优先核对异常 |
 | dagId | 按更新链标识精确发现提交与节点，不要求用户先补时间或 trace；检索时间见[更新发现指引](../update/topics/discover-executions.md#检索时间) |
-| workflowId（自动化） | 未提供时间时默认最近 7 天，按日志正文精确查，见[按 workflowId 查](../automation/queries.md#按-workflowid-查) |
+| workflowId（自动化） | 未提供时间时默认最近 3 天，按日志正文精确查，见[按 workflowId 查](../automation/queries.md#按-workflowid-查) |
 | 截图或 OCR 提取的 ID | 先核对字符并确认锚点可信度；存在相似字符歧义时请用户确认或粘贴原始文本 |
 | 只有现象 | 补充能够确定场景或资源、发生时间的最小信息；未指定环境默认 work，不直接发起宽查询 |
 

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/topics/setup-signoz-mcp.md

@@ -1,6 +1,6 @@
 # 配置 SigNoZ MCP
 
-为当前 Agent 客户端配置 SigNoZ 只读访问。诊断需要实时查 SigNoZ，但当前客户端没有工具、无法启动、环境不明确、鉴权失败或只读查询不可用时读；已有可用的 SigNoZ 工具或只有离线材料时不需要。正常首次配置只向用户请求缺少的 API Key，安装模式、发行包、MCP 名称和配置格式由助手按当前环境确定。本主题只恢复 SigNoZ 访问能力，不分析业务问题；完成后回到原调查继续。
+为当前 Agent 客户端配置 SigNoZ 只读访问。诊断需要实时查 SigNoZ，但当前客户端没有工具、无法启动、环境不明确、鉴权失败或只读查询不可用时读；已有可用的 SigNoZ 查询途径（MCP、Skill 或其他工具，一个途径查多个环境也算）或只有离线材料时不需要。正常首次配置只需用户在本机填入缺少的 API Key，安装模式、发行包、MCP 名称和配置格式由助手按当前环境确定。本主题只恢复 SigNoZ 访问能力，不分析业务问题；完成后回到原调查继续。
 
 ## 目录
 
@@ -14,20 +14,20 @@
 ## 默认流程
 
 1. 确认目标环境：用户输入、现有配置或[环境知识](../concepts.md)，没指定就用 work，不让用户先选。`work` 是正式环境，`prod` 不是；不按工具顺序或 `service.environment` 猜实例。URL 和口头说法冲突时只让用户确认“测试环境”还是“正式环境”，确认前不写配置。默认连接不可用就修它，不改用测试环境。
-2. 当前客户端已有能确认目标 URL 的 SigNoZ 工具，就跳过安装配置（推荐名称不同不重配），做一次最小只读验证就回原任务；本轮已有成功查询直接复用。
+2. 当前客户端已有能查目标环境的 SigNoZ 途径，就跳过安装配置：不限于 MCP，Skill 或一个工具切多个环境都算，能从 URL 或它的环境名对上正式、测试即可（推荐名称不同不重配），做一次最小只读验证就回原任务；本轮已有成功查询直接复用。
 3. MCP Server 缺失或损坏时，简短告知尚未安装，按“安装 MCP Server”默认安装适配当前系统和 CPU 的产物，不让用户确认版本、下载源或路径。
-4. 没有目标环境的有效凭据时只请求一次 API Key，环境能唯一确定就一并说明，不再问 URL 或 MCP 名称。用户提供 API Key 就表示同意写入本次目标环境的配置，不再追加配置确认，直接按“接入当前客户端”配好。
-5. 重载并做最小只读验证；客户端必须由用户 Trust、启用或重启时，只提示这一步。成功后立即回到原调查，不把安装变成独立任务。
+4. 没有目标环境的有效凭据时，按“接入当前客户端”把配置写好，Key 位置留占位符，再请用户在本机填入一次，环境能唯一确定就一并说明，不再问 URL 或 MCP 名称，不再追加配置确认。不在对话里索取 Key：对话内容会发给模型服务并留在会话记录里。
+5. 用户填好后重载并做最小只读验证；客户端必须由用户 Trust、启用或重启时，只提示这一步。成功后立即回到原调查，不把安装变成独立任务。
 
 只配置当前正在运行的 Agent 客户端，不要因为发现 Cursor、Codex、WorkBuddy 等其他客户端的配置文件就切换目标。只有环境确定不了、平台不支持、同名配置冲突或配置方式确实判断不了时，才请用户补最小的信息。
 
 ## 交互与结果
 
 - 正常成功路径只说明 MCP 已准备好并继续原任务；不主动展示 checksum、压缩包、安装目录、完整配置或排障过程。
-- 安装后等待 Key 时，直接说明“当前没有可用的 SigNoZ MCP，已经完成安装，请提供 `<环境>` 的 API Key 以继续配置和诊断”。
-- 不回显用户提供的 API Key，也不把它写入仓库、知识、fixture 或报告；只写入当前客户端支持的本机配置。
+- 等待 Key 时，直接说明“当前没有可用的 SigNoZ MCP，已经完成安装和配置，请在 `<配置文件路径>` 填入 `<环境>` 的 API Key，填好后告诉我继续诊断”。
+- 用户仍把 Key 发在了对话里：不回显，按原流程写入本机配置，并提醒对话记录里已有这个 Key，建议诊断结束后在 SigNoZ 重新生成。
+- API Key 不写入仓库、知识、fixture 或报告，只存在当前客户端的本机配置或用户自己的环境变量里；配好一次后续诊断直接复用。
 - 失败时说明准确阻断和下一项最小动作，不用重装掩盖环境、凭据、权限或网络问题。
-
 ## 安装 MCP Server
 
 仅在 MCP Server 或客户端配置缺失、损坏时执行。安装程序不接收 SigNoZ URL 和 API Key，也不修改客户端配置。
@@ -41,9 +41,11 @@ python3 scripts/install_signoz_mcp.py
 Windows 使用系统自带 PowerShell，不依赖 Python：
 
 ```powershell
-powershell.exe -File scripts\install_signoz_mcp.ps1
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\install_signoz_mcp.ps1
 ```
 
+Windows 桌面版默认禁止运行脚本，`-File` 同样受限；`-ExecutionPolicy Bypass` 只作用于这一次进程，不修改系统设置。
+
 当前工作目录不是内容根目录时使用脚本的绝对路径。只有需要改变默认用户级安装目录时才传入 `--install-dir <absolute-directory>`（PowerShell 为 `-InstallDir <absolute-directory>`）。
 
 脚本会自动：
@@ -65,10 +67,11 @@ powershell.exe -File scripts\install_signoz_mcp.ps1
 server name     -> 目标环境对应的稳定名称
 command         -> 安装脚本返回的绝对路径
 SIGNOZ_URL      -> 已确认的 SigNoZ 地址
-SIGNOZ_API_KEY  -> 使用者提供的该环境凭据
+SIGNOZ_API_KEY  -> 占位符，由使用者自己填入该环境的凭据
 ```
 
-- Key 用客户端支持的本机持久方式保存，不回显，不写进仓库、项目配置、知识、fixture 或报告。
+- 默认写入当前客户端的用户级配置文件并留占位符，告诉用户文件路径和要填的字段，用户在助手之外（编辑器或自己的终端）填写，不经过对话。只有用户本来就用环境变量管理 Key 时才在配置里引用环境变量：从 Dock、开始菜单等图形界面启动的客户端常读不到 shell 配置里的变量，表现为配好了仍报 401。
+- 不写进仓库、项目配置、知识、fixture 或报告。
 - 测试和正式环境分别配置，不复用或覆盖凭据；默认连接缺凭据时只要该环境的 Key，不改用已可用的其他环境。
 - 增量修改已有配置，保留无关的 server 和字段；支持工具 allowlist 时只启用诊断需要的只读工具。
 
@@ -80,7 +83,7 @@ SIGNOZ_API_KEY  -> 使用者提供的该环境凭据
 |---|---|
 | 客户端看不到工具 | 配置是否加载、server 是否启用、是否需要重载 |
 | server 启动失败 | command、文件存在性、平台架构、执行权限 |
-| 401 | 没有凭据或凭据无效；URL 与凭据是否属于同一环境，只请求目标环境的 Key，不换用其他环境的 Key |
+| 401 | 没有凭据或凭据无效；URL 与凭据是否属于同一环境，只请用户补填目标环境的 Key，不换用其他环境的 Key |
 | 403 | 凭据有效但角色不够，只读查询至少需要 Viewer 级别；请使用者换用有读取权限的 Key |
 | 工具存在但报字段 / schema 错误 | 工具版本与说明不一致；重新读取当前工具声明或修复 MCP 版本，不沿用旧参数硬试 |
 | 查询不到目标数据 | 精确 ID、时间与环境是否正确 |

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。