@fx-data/ai-diagnostics 0.1.20261026070913 → 0.1.20261107142011

package/content/docs/skill-writing-guide.md

@@ -1,65 +0,0 @@
-# 排查说明编写建议
-
-指南和助手指令应写清身份、解决的问题、判断方法和工具用法。每一步都应说明要做什么、依据什么判断，以及如何继续。
-
-## 从问题写起
-
-每份说明先写适用的现象、从哪些材料开始，以及要解释的问题。内部模块、类名、方法或工具清单放在需要它们的位置。
-
-只有操作方式或判断依据确实不同，才单独拆分场景。例如“筛选器候选值慢”与“选择筛选后图表慢”值得分开；不同日志字段数量不应产生新的流程。
-
-## 每一步写清三个要点
-
-看什么：给出可取得的页面信息、配置、记录或统计。
-
-为什么看：说明它能区分哪几种可能。
-
-怎样判断：说明哪些结果支持当前解释，哪些结果需要换方向，缺失时可以确认到哪里。
-
-例如，“检查更新链路异常”可以写成：“找到这次更新中迟迟未开始的节点，核对它的上游完成时间。有明确等待记录时说明等待阶段；没有关联记录时保留未知。”
-
-指南应说明可观察的行为、业务含义和适用条件，让读者依据记录排查，无需查阅产品代码或复现内部调用过程。
-
-## 用词与结论
-
-| 尽量避免 | 建议表达 |
-|---|---|
-| owner、overlay、handoff | 负责本次调查、场景排查、交接 |
-| evidence packet、projection | 证据摘要、与当前问题有关的记录 |
-| anchor、population、counting unit | 对应执行的标识、比较范围、正在统计的对象 |
-| gate、invalidator、needs-revalidation | 判断前需要满足的条件、哪些变化会使结论不适用、尚需核对 |
-| 闭环到某一层 | 已经确认什么、还不能解释什么 |
-| 数据量大导致慢 | 哪些数据在哪个环节增加，记录显示它怎样影响耗时 |
-
-接口、错误和日志字段需要精确匹配时保留原名，并在旁边解释含义。面向助手的调用名称可以保留在必要指令中，不应出现在给客户的报告里。
-
-使用“记录显示”“支持这一解释”“还不能确认”等表达区分证据力度。缺少字段不写成行为不存在，时间接近不写成因果，历史经验不写成本次根因。
-
-## 组织内容
-
-入口保持简洁，按现象链接到相关方法。业务关系、日志字段解释和排查经验分别维护，避免同一规则出现多个版本。
-
-知识写清事实、判断方法和适用限制，省去历史文档出处和提炼过程。保留运行证据的来源、字段口径和产物身份，供读者复核判断。
-
-将字段、环境、关联、结构核对和调查选择的规则写入知识，供助手判断。大模型难以可靠完成的大材料解析和精确计算才保留脚本，并写清适用场景、所需输入、结果含义与失败后的处理。已有材料无法支持下一步时，再请求补充信息或权限，并说明用途。
-
-每份场景说明都应写清何时继续、结束或交接。材料已经足够时直接分析；已经取得必要材料时，应按材料继续判断，不能停在通用错误名称。
-
-## 规则归属
-
-每条规则只在一个文件中维护，其他位置写一句结论加链接。修改前先在[文档目录](index.md)确认规则归属、文档分层和 Skill 调用关系；新增、删除或改名文件，或新增跨文件规则时，同步更新目录。
-
-## 控制执行成本
-
-- 入口只放适用目标、职责边界、下一步选择和必要约束；字段清单、查询细节和案例放在相关参考中，并写明什么时候读取。
-- 公共查询、安全和证据规则维护一处，专项链接复用，只补本场景差异。不要在多份文档复制完整流程。
-- 按已有材料选择起点：已有结构化产物先核对并解释，已有原始材料直接解析，缺运行证据才查询。列出多条命令时明确它们是替代入口还是依赖步骤，避免重复执行已包含的校验。
-- 写清哪些已读知识、已确认范围和产物可以继续使用，哪些输入变化需要重新核对；不能把复用解释为跳过新执行的证据校验。
-- Skill 交接时传递当前问题、范围、证据与产物、未完成动作，接收方沿用这些信息，无需重新查找或默认创建子代理。独立且必要的动作可并行，依赖动作顺序执行。
-- 优化后用同类输入检查判断是否正确、工具调用和追问是否减少，并核对必要分析与证据边界。字数和措辞检查只能辅助审阅，行为仍需验证。
-
-## 检查写好的说明
-
-用实际或脱敏的代表性输入走一遍：没有产品代码环境时步骤是否可执行，输入不完整是否能开始，相邻场景是否容易混淆，是否会漏掉失败尝试，以及结果是否足以让使用者复核或交接。
-
-结构和工具检查用于发现遗漏，不能替代对排查方法和表达质量的审阅。修改前阅读[问题定位方法](architecture.md)，修改后同步入口、相关场景和助手指令。

package/content/knowledge/common/signoz-environments.json

@@ -1,52 +0,0 @@
-{
-  "schema_version": 2,
-  "default_environment": "work",
-  "environments": [
-    {
-      "id": "test",
-      "user_label": "测试环境",
-      "aliases": ["测试", "测试环境", "test"],
-      "signoz_url": "https://signoz.jsydevelop.com",
-      "mcp_server": "signoz_test"
-    },
-    {
-      "id": "formal",
-      "user_label": "正式环境",
-      "aliases": ["正式", "正式环境", "work"],
-      "signoz_url": "https://signoz.work.jsydevelop.com",
-      "mcp_server": "signoz_work"
-    }
-  ],
-  "scoped_targets": [
-    {
-      "scope": "fx-data-server",
-      "aliases": ["test", "hihidata-jsy-test"],
-      "environment_id": "test",
-      "service_name": "hihidata-jsy-test"
-    },
-    {
-      "scope": "fx-data-server",
-      "aliases": ["dev", "hihidata-jsy-dev"],
-      "environment_id": "test",
-      "service_name": "hihidata-jsy-dev"
-    },
-    {
-      "scope": "fx-data-server",
-      "aliases": ["prod", "hihidata-jsy-prod"],
-      "environment_id": "test",
-      "service_name": "hihidata-jsy-prod"
-    },
-    {
-      "scope": "fx-data-server",
-      "aliases": ["perftest", "hihidata-jsy-perftest"],
-      "environment_id": "test",
-      "service_name": "hihidata-jsy-perftest"
-    },
-    {
-      "scope": "fx-data-server",
-      "aliases": ["work", "default", "hihidata-jsy-default"],
-      "environment_id": "formal",
-      "service_name": "hihidata-jsy-default"
-    }
-  ]
-}

package/content/knowledge/common/signoz-environments.md

@@ -1,55 +0,0 @@
-# SigNoZ 环境识别
-
-本文件提供各 Skill 共用的 SigNoZ 环境映射和选择规则，用于确定本次连接目标。这里不保存 API Key，也不规定具体客户端的配置格式。
-
-Agent 按本文映射和选择规则确认目标环境。对应的 [`signoz-environments.json`](signoz-environments.json) 用于开发期一致性校验，诊断时无需先运行环境解析脚本。
-
-## 环境映射
-
-| 对用户名称 | 可识别别名 | SigNoZ URL | 推荐 MCP 名称 |
-|---|---|---|---|
-| 测试 | 测试、test | `https://signoz.jsydevelop.com` | `signoz_test` |
-| 正式 | 正式、work | `https://signoz.work.jsydevelop.com` | `signoz_work` |
-
-对用户只有“测试环境”和“正式环境”两个选项。团队口头表达中的 `work 环境` 就是正式环境，查询必须发送到该环境的 URL；询问用户时仍统一显示“正式环境”，不创造第三个“工作环境”选项。
-
-`prod` 和 `production` 不是全局正式环境别名。`prod` 在 fx-data-server 后端语境中表示测试 SigNoZ 实例内的一个服务子环境；`production` 当前没有经过确认的项目语义，不参与自动解析。
-
-`mcp_server` 是推荐名称，用于保持不同客户端中的语义一致。客户端已有其他稳定名称时可以保留，以现有连接信息确认目标 URL；调用方式和参数以当前客户端实际提供的工具声明为准。已确认的环境绑定和本轮成功查询直接复用，不因工具前缀不同重新安装、配置或验证。
-
-## fx-data-server 后端子环境
-
-fx-data-server 的 SigNoZ 实例与后端 `service.name` 是两层信息。诊断后端请求时，按下表同时确认 SigNoZ 实例和后端服务，再把 `service.name` 下推为查询过滤条件。
-
-| 用户或部署表达 | SigNoZ 实例 | 后端 `service.name` |
-|---|---|---|
-| `test` | 测试 | `hihidata-jsy-test` |
-| `dev` | 测试 | `hihidata-jsy-dev` |
-| `prod` | 测试 | `hihidata-jsy-prod` |
-| `perftest` | 测试 | `hihidata-jsy-perftest` |
-| `work` / `default` | 正式 | `hihidata-jsy-default` |
-
-因此，“`work` 环境”应连接正式 URL，并过滤 `service.name=hihidata-jsy-default`；“fx-data-server 的 `test` 环境”应连接测试 URL，并过滤 `service.name=hihidata-jsy-test`；“fx-data-server 的 `prod` 环境”同样连接测试 URL，但过滤 `service.name=hihidata-jsy-prod`。多个后端子环境共享同一 SigNoZ 实例，连接该实例后仍须下推服务过滤。不要仅凭 `service.environment=prod` 选择实例：该字段在不同 SigNoZ 实例中都可能出现，后端样本也可能不填该字段。
-
-## 选择顺序
-
-按以下证据顺序收敛环境：
-
-1. 用户提供的 SigNoZ URL 或链接是最强候选。URL 与口头环境词冲突时，保留冲突及 URL 对应候选，查询或配置前请用户只确认“测试环境”或“正式环境”。
-2. 没有 URL 时，使用用户明确给出的环境词。
-3. 本次调查已经确认环境时直接复用，不因用户后续省略环境而切换。
-4. 新调查没有环境词或 URL 时，默认使用 work；后端调查同时采用正式环境的服务过滤。不再要求用户选择环境，也不对多个环境探测。
-5. 从现有 MCP 连接信息核对目标 URL，按当前工具声明调用。连接信息只证明后端绑定，实际只读查询证明可用性；已有本轮成功查询时不追加验证查询。默认 work 不可访问时恢复该连接，不改用测试环境。用户给出未知名称、未知 URL 或互相冲突的输入时只处理该歧义，不用默认值吞掉错误。
-
-## 探测与使用边界
-
-- 用户明确要求跨环境核对精确 ID 时才执行有界探测；普通调查默认 work，不跨环境扫描。
-- 缺少时间时不再同时要求选择环境。各类入口的时间默认值、查询预算与异常优先规则统一见[公共查询规则](signoz-query-policy.md)的“默认值速查”。
-- 环境一旦确认，本次诊断的 trace、log 和 metric 查询固定使用该环境，不混合其他环境的数据。
-- MCP 目标连接决定查询发送到哪个 SigNoZ 实例；`service.environment` 等 trace/log attribute 只能过滤当前实例中的数据，不能代替后端选择，也不能把测试连接变成正式环境连接。
-- MCP server 能读取某环境的 SigNoZ 数据，不代表业务 artifact URL 自动继承相同鉴权。
-- 测试和正式环境分别维护 API Key，不能复用或相互覆盖。
-
-## 维护来源
-
-当前实例映射根据 `core-ai` 历史 SigNoZ Skill 中已经使用的组织环境约定整理；fx-data-server 后端子环境根据 2026-08-11 对测试、正式 SigNoZ 服务拓扑和样本 trace 的核对补充。域名、namespace、环境用途或推荐名称变化时，应先由环境维护方确认，再更新本文件及相关验证。

package/content/knowledge/common/signoz-query-example.md

@@ -1,41 +0,0 @@
-# SigNoZ 原始记录查询例子
-
-仅在当前工具需要 Query Builder 对象、其说明资源不可读且已有字段知识足够时参考。例子描述 SigNoZ 原始记录结构；执行工具、调用参数和支持的字段以当前客户端声明为准。占位符必须替换；以下 `start` / `end` 仅为示例时间，实际使用时替换为已核对的 Unix 毫秒整数。在 Query Builder JSON 中直接传入整数，不加引号；便捷工具的独立时间参数仍按各自声明传入。
-
-```json
-{
-  "schemaVersion": "v1",
-  "start": 1700000000000,
-  "end": 1700000060000,
-  "requestType": "raw",
-  "compositeQuery": {
-    "queries": [{
-      "type": "builder_query",
-      "spec": {
-        "name": "A",
-        "signal": "traces",
-        "disabled": false,
-        "limit": 200,
-        "offset": 0,
-        "order": [{"key": {"name": "timestamp"}, "direction": "asc"}],
-        "filter": {"expression": "trace_id = '<trace>' AND service.name = '<service>'"},
-        "having": {"expression": ""},
-        "selectFields": [
-          {"name": "timestamp", "fieldDataType": "string", "signal": "traces", "fieldContext": "span"},
-          {"name": "trace_id", "fieldDataType": "string", "signal": "traces", "fieldContext": "span"},
-          {"name": "span_id", "fieldDataType": "string", "signal": "traces", "fieldContext": "span"},
-          {"name": "taskName", "fieldDataType": "string", "signal": "traces", "fieldContext": "attribute"}
-        ]
-      }
-    }]
-  },
-  "formatOptions": {"formatTableResultForUI": false, "fillGaps": false},
-  "variables": {}
-}
-```
-
-按当前缺口增减 selectFields，不能因为例子没有列出某字段就忽略场景所需证据。span 基本字段 context 为 span，自定义标签为 attribute，`service.name` 为 resource；数值与布尔标签分别使用已声明类型。当前执行与必要父记录分别保留。
-
-查询日志时 signal 改为 logs，timestamp/body/trace_id/span_id 属于 log，logger 与服务按实际字段声明选择。Metric 使用原始链接的完整过滤条件，或已核对 task + MetricOuts logger，不把业务服务套到 engine。
-
-设置当前问题所需的有限上限；命中上限、分页或截断时先处理覆盖。没有说明某结构或字段是否支持时取得工具说明，不猜测额外参数，也不反复枚举说明资源。

package/content/knowledge/common/signoz-query-policy.md

@@ -1,145 +0,0 @@
-# SigNoZ 查询收敛规则
-
-查询 SigNoZ 时，先用环境、时间、服务和业务标识缩小候选范围，再读取 trace 或 log。本文件维护多个诊断 Skill 共用的查询约束；场景接口清单和 MCP 安装由对应文档负责。
-
-入口默认值、查询预算和对比基线只在本文件维护；AGENTS.md、Skill 和说明文档只引用，不复制细则。
-
-## 默认值速查
-
-| 情况 | 默认处理 |
-|---|---|
-| 未指定环境 | 默认 work（正式环境），显式环境、URL 和已确认范围优先；映射见[环境选择规则](signoz-environments.md) |
-| 普通对象（tableId、widgetId、reportId 等）没有时间 | 完全缺少时间时合并询问一次时间，不同时要求选择环境，不要默认最近 7 天 |
-| 企业更新没有时间或只说“最近” | 企业更新无时间默认最近 24 小时，告知后直接查询，优先核对异常 |
-| 只有 dagId | dagId 不先追问时间，由助手管理检索窗口，命中后按实际记录恢复链范围 |
-| 用户说“之前没超限”“以前正常”“最近变慢” | 已经是历史对比目标；先定位目标执行，再主动查找目标执行前 24 小时的可比基线 |
-| 只有单次失败 | 单次失败诊断不要求发现或补充成功执行 |
-| 仪表板内组件计算异常 | 优先有界查找组件单独计算记录；未找到仍继续分析本次异常，见[仪表板内外组件对照](#仪表板内外组件对照) |
-
-细则见下方各节。
-
-## 选择和调用工具
-
-- 发现工具时按已确认连接列出工具名称，再读取本次需要的单个工具说明和参数。调用方式以当前客户端实际工具声明为准，按[环境选择规则](signoz-environments.md)核对目标 URL，不因工具前缀与推荐名称不同重配环境。不要输出全部环境或全部 SigNoZ 工具的完整说明；一个查询工具的说明读过后直接复用。
-- 已有精确 trace 时，详情工具用于取得基本时间线；自定义业务属性按场景知识选择所需字段，再交给当前可用的定向查询工具。已有对应字段与完整结果时跳过重复读取。
-- 区分工具参数与查询字段：详情工具的参数是 `traceId`，查询表达式使用 `trace_id`，不能把参数名直接写进过滤表达式。其他字段按工具 schema 和知识说明使用，收到字段错误时只修正报错字段。
-- 客户端若不能读取 SigNoZ 的 Query Builder 说明资源，记录一次能力缺口。先按场景字段和[原始查询例子](signoz-query-example.md)描述当前缺口；需要调用 schema 时取得当前工具声明或改用能完成同一精确查询的只读工具。不要反复枚举资源或猜测查询结构，也不要把说明资源不可读等同于 SigNoZ 不可查询。
-- 查询结果只向上下文返回本次所需字段和摘要。大响应直接交给临时文件或解析器，避免先完整输出再复制。命中条数达到 limit 时，即使没有 nextCursor，也不能据此声明覆盖完整；需要完整性时按同一精确执行缩小到必要 span 或字段核对。
-- 临时摘要也按白名单取字段，只展示操作、执行标识、时间、状态、错误签名及当前判断所需的明确数值。不要直接打印 `body` 首行、任意正文前缀或整份 Job 字段映射；其中可能包含租户、用户、描述和完整载荷。Metric 先用确定性入口生成摘要，其他日志在留存原文中提取必要事实后再输出。
-- 助手选择执行、核对结构、确定查询内容并判断关联；脚本使用范围见[助手执行契约](../../AGENTS.md#工具使用)。工具说明和指南本轮只读取一次；已取得的执行、task、Metric 原始链接和产物路径随调查摘要保留。索要链接或已有字段时先读取该摘要，不为展示重复查询。
-
-一条 trace 可能包含多次工作区操作或多个计算。已有目标执行 span 和时间时，把它们作为选择条件；首次结果达到上限，先按目标 span 或其必要父子范围收敛，不重复取得整条 trace，也不能按整条 trace 的最慢任务替换目标。实际入口不属于已建设场景时，保留入口名称，使用通用时间线和已明确绑定的任务解释，不能硬归为分析表或仪表板。
-
-在只能通过终端传递大结果的客户端，运行 `python3 -u scripts/receive_tool_result.py`（仓库根目录）并启用终端会话。收到 `READY` 后，将原始工具对象通过 `JSON.stringify(response) + "\n"` 写入该会话 stdin，读取返回的临时文件路径，再交给场景解析脚本。接收器关闭回显、保留 Unicode 和正文中的转义换行；无须自行编写编码或终端接收逻辑。需要核对调用方法时使用 `--help`，它只显示用法，不进入收包流程。接收失败复用内存中的响应重传，不能重新查询线上正文。
-
-Trace、业务属性和 Metric 的临时原文及产物在同一调查中保留并复用；首次交付或切换场景不立即删除。调查结束后按客户端临时目录策略清理，不把原始大响应写入工作区。
-
-用户明确要求从线上选取样本评测时，可以在获准环境和服务内自行设定有限的取样时间窗、耗时阈值和结果数，并说明选择依据。样本选定后转为对应执行的精确调查；取样范围不作为每个案例后续查询的默认范围。
-
-## 调查起点
-
-| 已有输入 | 首次动作 |
-|---|---|
-| SigNoZ trace 链接 | 从 URL 确认环境和 traceId，精确读取 trace，再使用 trace 时间与 `service.name` |
-| 精确 traceId 或执行 ID | 复用已确认环境；未指定时默认 work，精确查询并恢复执行时间 |
-| tableId、widgetId、reportId 等资源 ID | 按默认或显式环境及发生时间，使用场景入口、服务和资源 attribute 寻找候选执行 |
-| 企业 ID（更新查询） | 复用已有时间；未提供时告知默认最近 24 小时后直接查询，先给更新概况并优先核对异常 |
-| dagId | 按更新链标识精确发现提交与节点，不要求用户先补时间或 trace；检索时间见[更新发现指引](../../.agents/skills/analyze-analysis-table-update-runtime/references/discover-update-executions.md#检索时间) |
-| 截图或 OCR 提取的 ID | 先核对字符并确认锚点可信度；存在相似字符歧义时请用户确认或粘贴原始文本 |
-| 只有现象 | 补充能够确定场景或资源、发生时间的最小信息；未指定环境默认 work，不直接发起宽查询 |
-
-资源 ID 可以关联多次前台查询和后台更新，不是一次执行的唯一标识。环境按[环境选择规则](signoz-environments.md)处理：复用调查范围，显式输入优先，未指定默认 work。普通对象查询完全缺少时间时合并询问一次发生时间；企业更新和 dagId 使用下方规则直接开始。已经提供的时间、环境和标识不重复索要。环境冲突时只确认“测试环境”或“正式环境”，不创造第三个选项。fx-data-server 后端语境中的 `prod` 仍表示测试实例内的 `hihidata-jsy-prod` 服务。不要先扫描两个环境，也不要默认最近 7 天。
-
-资源 ID 不是精确执行 ID；默认环境不改变这个区分。企业更新与 dagId 的检索窗口、降级和时间扩展只适用于更新发现，细则见[更新发现指引](../../.agents/skills/analyze-analysis-table-update-runtime/references/discover-update-executions.md#检索时间)。
-
-## 锚点可信度
-
-- 用户直接粘贴的 URL、ID 文本以及工具返回的结构化字段可以作为精确锚点。
-- 截图、OCR 和人工转抄得到的值只作为候选。先逐字符核对原始材料；`g/q`、`0/o`、`1/l` 等字符无法可靠区分时，向用户展示识别结果并请求确认或粘贴原始文本。
-- 截图候选第一次精确查询为零时，零结果不能证明没有执行。先复核锚点；锚点未确认前，不得通过扩大时间、切换环境或移除 `service.name` 来补偿可能的字符错误。
-- 上游确认锚点后再把它交给场景 Skill、update analyzer 或 engine analyzer，避免下游在错误 ID 上生成更完整但无关的证据链。
-
-## 按现象选择首次证据源
-
-- 用户明确描述报错、更新失败、内存超限、OOM 或 `MemoryLimitExceeded` 时，先在已确认的环境、时间、`service.name` 和资源锚点内查询 ERROR 日志，收集全部精确命中的执行，从结果提取 traceId、chainId、taskId、执行类型或其他执行 ID，再精确读取 trace。第一次没有命中时，只在同一环境、时间、服务和资源锚点内去掉 severity 限制查一次；不能先做全局错误搜索，也不能先挑最慢的成功 trace。
-- 上述错误首查顺序用于尚未锁定执行的资源发现。已有精确失败 trace/task 或直接错误记录时，复用现有证据，只补尚未确认的提交、阶段或失败条件；不为重复确认报错先查 ERROR、再查同 span 的全级别业务日志。需要生命周期证据时，一次精确查询所需记录。
-- 预览、查看、更新、ETL 等执行类型用于防止不同运行的 trace、log 和 Metric 串线，是执行证据的上下文，不是用户必须预先选择的调查分支。同一资源和时间窗内的多个执行如果具有相同失败签名和计算链路，可以联合解释；不能仅因执行类型不同就请求用户消歧。只有不同执行指向不同原因且用户目标无法推断时，才展示差异并询问。
-- 用户明确描述慢、卡顿或耗时回归，且没有失败信号时，优先按入口、资源锚点和时间寻找 trace，再沿关键路径读取关联日志或 Metric。
-- 用户只说“性能问题”时，在受控范围内浅分型成功慢执行与失败执行，展示仍然可信的候选差异；不要替用户默认选择最慢或最新的一类。
-- engine Metric 是锁定执行后的解释证据，不是发现业务执行的第一入口。只有已经取得 taskName、Metric 链接或精确 trace 关联时才查询 MetricOuts。
-
-## 查询约束
-
-资源驱动的首次查询应尽量同时具备：
-
-```text
-已确认环境
-+ 明确时间范围
-+ service.name
-+ 场景入口或特征 span
-+ 资源 attribute / 精确业务 ID
-```
-
-- `service.name` 是优先下推的资源字段。优先从精确 trace、已验证的环境知识、部署配置或场景观测知识取得；无法唯一确定时，只在已确认环境和时间内收敛少量服务候选，必要时请求用户消歧。
-- 业务服务名随部署环境变化，应以对应执行或已核对的环境信息为准。不能把 `default`、某次测试服务名或历史服务名当作所有环境的固定值。
-- 用户给出具体时刻时，首次从该时刻前后各 15 分钟查找；用户给出明确时间段时使用该范围。普通对象发现没有时间时先询问；企业更新与 dagId 按更新发现指引处理。用户直接给出的 trace URL/traceId 属于精确执行锚点，不受这条资源发现限制。
-- 时间参数按当前工具声明传入。已有时间边界直接复用；“最近 24 小时”等范围在工具支持时直接使用 `timeRange`，无需另行换算。明确日期或历史基线使用绝对边界；工具要求 Unix 毫秒且需要转换时，用当前运行环境的日期函数一次处理，沿用上下文时区或客户端当前时区。查询前核对日期、时区、单位及起止顺序；只有日期、时区或夏令时存在实质歧义时才询问用户，不固定调用仓库时间脚本。
-- 返回的 `timestamp` 可能是带纳秒小数的 RFC3339 字符串，也可能是秒、毫秒、微秒或纳秒时间戳，保留原值。用作查询边界时按实际格式和单位处理，不能把字符串直接当整数，或把纳秒值作为毫秒传入。展示精度不改变原始证据。
-- 一旦首次查询开始，记录环境、时区和发现窗口；普通对象查询中，时间窗外的结果不能作为本次候选。选定执行后冻结该执行范围，不用较晚或较早的相邻执行替代它。DAG 的默认发现窗口不限制已由精确标识或显式链接确认的同链记录，按更新发现指引恢复其真实范围。目标执行与正常/成功基线各自拥有独立范围，不能把目标执行的时间窗用于查询基线；需要扩大某一侧时间时必须明确记录扩大原因和新旧边界。
-- 查询只选择当前判断需要的字段并设置有限结果数。已经存在 traceId、taskId 等精确锚点时，优先使用精确过滤，不再从资源 ID 重做发现。
-- 首次没有命中时，先核对时区、环境、服务和资源值。确认输入无误后，每次只扩大一个维度；不能同时跨环境、扩大时间并移除 `service.name`。
-- 便捷日志搜索未返回 `trace_id` 时，在相同过滤条件和冻结时间窗内执行一次 Query Builder，只补取 `timestamp`、`body`、`trace_id`、`span_id`、`service.name` 等关联字段；不能因此退化为按 operation 或全服务搜索 trace。
-
-企业／dagId 入口先按更新发现指引恢复关联执行，再在对应执行核对失败信号；不将上面的资源失败首查规则机械变成企业属性与错误必须同 span 命中的限制。
-
-## 独立 Trace 的显式链接
-
-部分后台执行会创建没有父 span 的新 trace，同时用 span link 指向进入该执行前的 span；新执行上的 `linked` attribute 保存被链接的原 trace ID。查询方向是：已有原 trace ID → 在相同服务与时间范围内查 `linked=<原 trace ID>` → 取得新执行的 trace ID。新执行已有原生 span link 时，优先核对它的 trace/span ID。
-
-原 trace 上的业务属性不会因 link 自动复制到新 trace。不能要求企业属性、执行属性和错误在同一个 span 上，也不能把独立 trace 当成原 trace 的 parent/child。先按实际返回的显式链接确认遥测范围，再核对本场景要求的业务标识。
-
-`linked` 只精确到原 trace，原 trace 可能承载多项操作；有多个候选时还需原生 link 的 span ID、对象和场景等实际证据消歧。链接缺失或仅有同企业、同表名、时间邻近时，保留关联缺口，不补造依赖、重试或引擎任务关系。
-
-这里只提供后台独立 trace 的查询候选知识，依据 2026-09-08 核对的后台独立 trace 行为；线上采集、索引和历史保留范围仍需实际核对。只有实际出现的 link／`linked` 可以支持本次关联；缺字段不等于对应行为未发生。
-
-## 查询预算与结果复用
-
-- 同一环境、时间、服务、锚点和过滤条件组成的查询不得重复执行。需要从同一结果提取不同字段时，复用已经取得的结果。
-- 资源发现最多执行“精确首查 + 同范围一次降级”。两次仍不能得到执行锚点时，先向用户确认资源、时间或服务，不继续串行试探相近关键词。只有 dagId 的精确链发现可使用更新发现指引中的一次有界时间扩展，不能套用到企业、普通对象或历史基线。
-- 一旦取得 traceId、taskId 或唯一执行，立即冻结该执行的环境、时间和服务；后续只做 trace、关联日志和 Metric 的精确查询，不再从资源 ID 重走发现链路。
-- taskId 或 chainId 只锚定执行，不等于已经取得 trace。只有这类锚点时，在冻结的环境、服务和执行时间窗内精确反查一次对应 trace；无法取得时保留 task/chain 证据并明确 trace 缺口，不扩大成新的资源发现。
-- 精确 trace 已确认但 span 明细因保留期或后端差异不可读时，优先在该 trace 的原时间窗和已确认业务服务下按 `trace_id` 精确查询日志。精确 trace URL 没有时间且默认读取为空时，允许按[Metric 获取方法](../engine/metric-retrieval.md)做一次最多 30 天的受控精确 ID 日志回退；URL 携带 `spanId` 时必须同时过滤 focused span。该动作只从同 trace/focused span 日志恢复原时间和 task，不属于资源发现，也不得继承另一条执行的时间窗。日志返回多个 task 时按用户明确的执行形态消歧，仍不唯一则保留歧义，不静默选择最新或最长的一条。
-- 单次失败诊断不要求发现或补充成功执行；仪表板内组件异常按[仪表板内外组件对照](#仪表板内外组件对照)优先查找，但未命中不阻断单次分析。“之前没超限”“以前正常”“最近变慢”等已经表达相对历史对比目标，不要求用户再次选择对比或先提供成功 trace；按下方“主动对比”建立基线。对比调查的查询预算按执行分别计算。成功基线是用户明确选择的证据目标，不受“不要深挖尚未选中的成功候选”限制；一侧查询和 Metric 产物不能冒充另一侧。
-- Trace 查询只选择识别场景、执行和关联所需字段。已有精确 traceId 时优先使用定向查询；没有必要时不拉取整棵 trace 的全部 span 和 attribute。
-- 同一完整原始结果已经足以回答数量或状态时，直接按明确单位整理，不再重复查询聚合。结果未覆盖完整、需要去重口径或总体统计时，才补相应聚合；样本不能替代总体。
-- MetricOuts 正文的获取、去重、复用和生命周期补查按[Metric 获取方法](../engine/metric-retrieval.md)执行。
-- 查询返回超大结果或发生截断时，不用重复同一查询解决截断；改为减少返回行数和字段、增加精确 task 过滤，或在工具侧完成提取后只返回摘要。
-
-## 主动对比
-
-先定位目标执行，再在同环境、对象和执行类型下发现正常基线；仪表板与组件单独计算的跨入口对照按下节处理。用户已给正常时间或成功执行时直接复用；只表达“之前正常”时，以目标执行开始时间为右边界，查询此前 24 小时的半开窗口，不用当前时钟或目标发现窗口的起点代替。时间参数按上方“查询约束”处理，两侧边界分别保留。
-
-基线发现同样遵守“精确首查 + 同范围一次降级”，只取有限候选及判断可比性所需字段。按时间由近到远检查同对象、操作、参数和数据范围的成功执行；有明确成功结果且可比时选择最近一条并记录依据，不能仅凭耗时短或没有 ERROR 认定成功。成功节点也不自动代表整条更新链成功。影响可比性的字段缺失或多个不同操作仍可信时，展示差异再作最小消歧；已经明确的数据范围变化可以作为待解释差异，不要求两侧数值完全相同。
-
-分别维护 `目标执行` 和 `基线执行`：各自记录环境、trace/focused span、时间、业务及 engine 服务、task、Metric 与覆盖范围；时间窗只在本侧冻结，不跨侧复用。切换已选执行必须说明原因和证据差异，不能用相邻失败或另一侧产物静默替代。
-
-选定后主动取两侧 Trace、task 和 Metric；已有产物复用，每侧范围独立冻结。不得停在“建议再取 Metric”或等待用户说“你帮我取”。对照未找到、不可比或无法取得时，交付本次事实与已查询范围，并请求更早正常时间或最小缺失项，不自动扩大到七天。用户没有相对变化目标时仍按单次诊断推进。
-
-### 仪表板内外组件对照
-
-这是仪表板组件异常的默认浅查，不要求用户先提出对比，也不扩大为整张仪表板或企业扫描。先从目标 trace 恢复组件、查询表、时间与业务服务。已有单独计算材料优先复用；没有时间的对照查找，以目标执行开始前 24 小时的半开窗口为限。用户给出更明确的单独预览时间或 trace 时按该侧证据恢复范围，不套用失败侧时间。
-
-首次在同环境、同业务服务和该窗口内按组件身份及单独计算入口取有限候选，按时间由近到远核对。编辑态可能不记录 `component.id` 和 `data.request_context`；首查未命中时，在同窗口与服务内只降级一次，改查编辑态请求日志中的精确组件 ID，或已确认查询表加请求用户、查询字段等识别信息，不要求 `reportId` 同时命中。查询表只能发现候选，身份与可比性按[组件计算对照的证据](../dashboard/observability.md#组件计算对照的证据)核对；不能因同表就认定为同组件。
-
-候选达到 limit 时，不宣称已覆盖所有记录；能唯一核实最近可比执行时选定并冻结，否则保留覆盖缺口。不继续扩大时间、移除服务或换表试探。未找到或不可比就继续目标失败分析，按场景流程提示用户检查单独预览结果。找到可比成功执行时主动取得两侧执行统计，各侧 engine 服务分别确认，不能把失败侧 engine 服务过滤直接套到成功侧。
-
-控件名称与绑定关系是另一项精确元数据取证，不是上述正常执行发现的重复查询。需要跨 trace 查控件关系时，默认复用同一前置窗口、业务服务和精确字段/组件标识；有明确关联请求时间或 trace 时直接精确读取。关联规则见[名称与请求上下文的关联取证](../dashboard/observability.md#名称与请求上下文的关联取证)，不得仅凭“附近”不断扩大范围。
-
-## 场景与服务角色
-
-四个业务场景先在业务 server 服务中寻找入口 trace，各场景的 route、span 和 attribute 读取对应 `observability.md`。确定 trace 后再沿实际上下游服务推进，不在定位入口时预先扫描所有服务。MetricOuts 由 engine 服务记录，业务 server 的 `service.name` 不能套用到 engine 日志，细则见[Metric 获取方法](../engine/metric-retrieval.md)。
-
-## 来源
-
-- SigNoZ Trace/Logs Query Builder：`service.name` 是 service 资源字段；
-- 2026-08-05 真实使用反馈：跨环境、天级时间窗和全服务查询会显著放大定位耗时。

package/content/knowledge/common/trace-routing.md

@@ -1,63 +0,0 @@
-# Trace 场景识别
-
-只有 trace、执行链接或场景尚不明确时，用本文件选择调查起点。这里说明跨场景的识别方法；四个场景的完整 span 字典及后续专项 Skill 或 analyzer 的选择由对应流程负责。
-
-路由结果确定从哪个业务场景开始调查，根因位置仍需验证。按已有材料说明调查起点、判断依据、其他可能关联的场景，以及必要时的下一项消歧信息，无需套用固定字段。
-
-## 最小 Trace 摘要
-
-优先从 trace 中提取：
-
-- 根 span 或入口 span、规范化 HTTP method 和 route；
-- 关键 span 名集合，包含最慢 span 之外的相关记录；
-- `data.request_context`、`data.endpoint`、`sense` 等业务 attribute；
-- `tableId`、`component.id`、`reportId`、`dagId` 等资源或执行锚点；
-- service、时间、耗时、错误和上下游关系。
-
-## 识别方法
-
-1. 已知接口或明确业务 attribute 命中某个场景时，读取对应场景的可观测知识确认含义。
-2. 接口缺失或未收录时，使用 trace 中实际出现的 span、attribute 名和值搜索场景可观测知识，只读取命中的候选文件；不得为了识别场景而调用 analyzer 或直接读取结构化诊断分片。
-3. 优先使用能够表达业务入口的信号组合。资源 ID 和上下游关系可以补强或建立关联，但通常不能单独决定场景。
-4. 命中共享的外部组件取数入口时，先按下方[外部组件取数入口](#外部组件取数入口)判定来源，再进入专项；不能仅凭最外层 HTTP span 或共享 span 名选择场景。
-5. 同时命中多个场景时，选择当前入口证据最强的场景开始，并保留其他关联场景；调查起点不等于根因位置。
-6. 只有通用 Query 或 engine span 时保持场景未知。可以继续分析 engine 层事实，但不能据此猜测业务入口。
-
-## 外部组件取数入口
-
-`POST /v2/external/widget/data` 同时用于独立组件预览和仪表板内组件计算。沿同一入口父子链检查承载 `DataRequestObservation` 属性的 span；它可能是 `previewComponent` 或其他对应子 span，最外层 HTTP span 的 `reportId` 可能为空。
-
-- 任一对应 span 的 `data.request_context=dashboard` 或 `reportId` 非空，判定为仪表板内组件计算，完全归仪表板场景，不先经过组件专项分流。
-- 只有确认链路内这些信号均为空后，才从独立组件预览开始。属性尚未取得时保留未知，不能按空值处理；已确认的其他入口仍按对应观测知识判断。
-- `previewComponent` 只是共享入口的 span 名，不能决定场景。离开该取数入口链路的 `reportId` 只能作为关联线索；接口与 attribute 冲突时保留冲突，不静默覆盖。
-
-这套规则只确定调查入口。单个组件 trace 和仪表板来源标识，都不能证明已经覆盖整次仪表板交互。
-
-## 场景可观测知识
-
-| 场景 | 观测知识 |
-|---|---|
-| 分析表 | [dataset/observability.md](../dataset/observability.md) |
-| 组件 | [component/observability.md](../component/observability.md) |
-| 仪表板 | [dashboard/observability.md](../dashboard/observability.md) |
-| 更新 | [update/observability.md](../update/observability.md) |
-
-场景文件提供识别入口、span 和 attribute 的最小线索。更新运行时事实仍由 `knowledge/update/diagnostic` 保存，但只有进入相应专项流程后才由 analyzer 消费，公共路由和兼容 Markdown 不复制详细清单。
-
-识别为更新场景后，把“更新”及其判断依据返回当前调用方：性能目标由 `$diagnose-performance` 进入 `$diagnose-update-performance`，再由更新性能专项调用 analyzer；只有更新来源、DAG、计数或已有运行材料解释等有界事实目标，才由根 Agent 直接调用 `$analyze-analysis-table-update-runtime`。场景识别本身不触发 analyzer。
-
-## 信号边界
-
-- 已确认的业务接口、显式请求上下文，或场景特有入口 span 与业务 attribute 的组合，可以直接支持选择调查起点。
-- `tableId` 等共享资源字段，以及脱离组件取数入口链路的 `reportId`，主要用于关联上下游，不能单独分类；组件取数入口链路中承载请求观测属性的 span 上，非空 `reportId` 是仪表板来源的直接信号。
-- 最慢 span 只表示耗时位置，不能证明业务场景。
-- 接口与 attribute 冲突时保留冲突证据，不静默覆盖其中一类信号。
-- 没有可靠命中时保持场景未知，只补充最有区分度的一项入口、上下文或资源信息。
-
-## 适用范围
-
-以本次实际入口和字段为准。历史入口只能帮助解释历史操作，字段缺失不能证明对应行为不存在。更新记录由专用分析流程核对适用性及关联，无法确认时保留具体缺口，不要求使用者查找产品实现。
-
-## 长 trace 与其他入口
-
-同一 trace 可包含多次工作区操作。已给出执行 span 与时间时，仅沿对应父子范围识别本次入口，不能把整个 trace 的最慢任务视为用户目标。实际入口为工作区详情等未列入专项的操作时，保留其业务入口，按通用时间线和明确关联的引擎任务解释；共享计算并不自动变成分析表预览。

package/content/knowledge/component/observability.md

@@ -1,60 +0,0 @@
-# 组件诊断知识
-
-本文件维护组件的业务实体、调查关系和可观测信号（接口、span、attribute），用于识别入口和解释本次执行记录；具体问题的排查经验在对应场景 Skill 的 `references/experience.md`。
-
-## 业务实体
-
-- 组件以 `widgetId` 或 `component.id` 为主要锚点，并绑定一个或多个查询表。
-- 组件查询可能携带筛选、联动、权限、聚合、排序和分页上下文。
-- 组件慢既可能来自本次查询，也可能来自所依赖分析表的状态或更新。
-
-## 调查关系
-
-```text
-widgetId / component.id
-  → 数据绑定与查询上下文
-  → component query execution
-  → analysis table
-  → Query
-  → engine task
-```
-
-不能因为 trace 中出现组件 span 就排除 dashboard 入口，也不能因为底层表正在更新就直接判定更新是根因。
-
-## 证据边界
-
-组件配置说明可能发起哪些查询，trace/log 记录本次发起的查询，Metric 展示计算过程。按 ID、时间窗和执行关联核对这些材料后，再合在一起解释。
-
-## 场景识别
-
-已确认的入口包括：
-
-- `POST /v2/design/widget/data`：编辑态组件取数；
-- `POST /v2/external/widget/data`：共享的外部组件取数入口，需要结合请求上下文消歧；
-- `POST /v2/query/data`：`queryData` 通用组件查询入口，不能仅凭 span 名补全画布或控件上下文。
-
-已确认的特征 span 包括 `editComponent`、`previewComponent` 和 `queryData`。组件计算链路还可能出现 `getComponentMatrixData`。
-
-外部组件入口的关键 attribute：
-
-- `data.endpoint=external_component_data`；
-- `data.request_context=component_preview`：从组件场景开始；
-- `data.request_context=dashboard`：完全交给仪表板场景；
-- `component.id`、`component.type`、`component.query.table_id`：组件和绑定表锚点。
-
-## 信号含义
-
-- `component.id` 或用户提供的 `widgetId` 用于关联组件资源；
-- `component.query.table_id` 表示组件查询绑定表，可用于进入分析表调查；
-- 外部入口的 `reportId` 与 request context 按[来源判定](../common/trace-routing.md#外部组件取数入口)解释，不能把关联字段直接当作场景结论；
-- 控件、筛选、联动和权限 attribute 描述本次请求上下文，不直接证明它们造成性能问题。
-
-只有通用 Query 或 engine span，或者只有共享的 `tableId`，都不足以确认组件场景。
-
-## SigNoZ 查询线索
-
-遵循[公共查询收敛规则](../common/signoz-query-policy.md)。资源驱动查询沿用公共规则确定的环境和问题发生时间，在业务 server 的 `service.name` 下组合组件入口 route、`editComponent`/`previewComponent`/`queryData` 与 `component.id` 或 widgetId。外部组件入口按[来源判定](../common/trace-routing.md#外部组件取数入口)定向补取父子链中的上下文属性，不只读取 HTTP 根 span。
-
-## 调查时保留
-
-优先保留入口 route、请求上下文、组件 ID、绑定表、report ID、筛选/联动摘要、关键 span、耗时、错误和 Query 关联。