@fx-data/ai-diagnostics 0.1.20261026070913 → 0.1.20261107142011

package/content/.agents/skills/analyze-analysis-table-update-runtime/SKILL.md

@@ -1,35 +0,0 @@
----
-name: analyze-analysis-table-update-runtime
-description: 当用户或上游 Skill 提供企业 ID、dagId、脱敏的分析表更新日志、trace 摘要、运行时导出、Trace ID 或绝对时间窗，需要查看企业最近更新、解释更新来源、scene/producer、request/root/chain/DAG、node/attempt/requeue/load/listener/engine-task、核对更新计数、关联边、逻辑或执行时间线，或生成有界查询计划时使用。它只返回版本匹配的更新运行证据摘要，不维护多轮调查上下文、不协调跨场景，也不宣称最终根因；慢、超时、内存超限、OOM、MemoryLimitExceeded、资源消耗或性能回归必须先由性能诊断入口路由。
----
-
-# 分析更新运行记录
-
-解释本次更新来源、request、chain/DAG、节点尝试、requeue、load、listener、engine task 或更新计数。返回阶段证据摘要，不维护多轮根因调查、不协调跨场景、不宣称最终根因或处置优先级。性能目标由性能入口及更新场景调用本能力。
-
-## 从当前问题开始
-
-沿用已有的对象、环境、时间、trace、chain/task 和调查材料。先确定本次要解释的记录与计数单位；已有材料足够时直接分析，无需先生成查询计划或填写适用性 JSON。
-
-只有企业 ID 或 dagId、尚未定位执行时，先按[企业与 DAG 发现指引](references/discover-update-executions.md)查找记录。企业命中消费 span 后，按已有显式链接直接查关联更新，不为例行检查先重取消费 trace 和日志。
-
-需要解释字段、阶段或关联时，按[更新运行知识](../../../knowledge/update/runtime-evidence.md)选择对应场景、recipe 和观测分片，只读取当前缺口需要的记录。参考[输出边界](references/update-diagnostic-contract.md)区分本阶段事实、静态知识和最终原因。
-
-## 取证与解释
-
-- 按当前问题选择执行，由助手依知识和当前工具声明查询。已有精确 trace/chain/task 不重做资源发现，查询范围及默认时间遵守[公共规则](../../../knowledge/common/signoz-query-policy.md)。
-- 按发布描述核对来源、版本、范围和字段语义。版本未知保持 unknown，语义漂移保留 needs_revalidation；继续交付直接观察事实，不要求使用者取得内部构建标识。
-- 来源、accepted entry、chain、node、attempt、load、listener 和 engine task 分阶段关联。每条边需其声明的原生关系或显式键；第一条必要边缺失时停止扩展。
-- 同租户、同表名、display name、相似数量、时间邻近或相邻 trace 不证明异步关系、重复更新、merge 或物理提交。知识只说明可能行为，不能代替本次记录。
-- 确定计数单位并保持一致，分别说明 request、chain、distinct node、attempt、load 和 task；同一完整结果足够时直接整理，不重复查询。
-- 只查询能改变当前判断的缺口，不能为走完 recipe 读取全部阶段。明确 engine task/Metric 时返回关联证据及缺口，由调用方继续；不自行扩展为调查负责人。
-
-## 返回结果
-
-简要说明当前问题、调查范围和知识适用限制，列出可信候选与所选运行、身份/计数单位、阶段时间线和阶段测量结果。保留直接事实、反证、已验证关联、覆盖范围和下一项最小缺口。
-
-直接向使用者答复时，按[公共交付说明](../../../docs/diagnostic-report.md)组织结果，本轮已读则复用，仍保留以下阶段证据边界。
-
-不返回 `final_root_cause`、`cross_scene_conclusion` 或 `remediation_priority`，不调用其他场景自行扩大调查。面对使用者说明记录和判断边界，内部索引、digest 和输出协议留在调查材料中。
-
-本轮实际遇到项目优化项或文档差异时，按[需求反馈](../../../docs/diagnostic-feedback.md)返回线索、依据和限制，由最终交付方汇总；不为反馈新建调查。

package/content/.agents/skills/analyze-analysis-table-update-runtime/agents/openai.yaml

@@ -1,7 +0,0 @@
-interface:
-  display_name: "分析表更新运行证据"
-  short_description: "解释更新来源、DAG、运行时间线、关联关系与计数口径"
-  default_prompt: "使用 $analyze-analysis-table-update-runtime 解释这份更新运行证据，并返回有边界的证据摘要。"
-
-policy:
-  allow_implicit_invocation: false

package/content/.agents/skills/analyze-analysis-table-update-runtime/references/discover-update-executions.md

@@ -1,34 +0,0 @@
-# 从企业或 DAG 定位更新执行
-
-输入包含企业 ID／dagId、尚未定位更新执行时，读取本指引查找候选，不重建完整 DAG。企业入口只覆盖更新，其他企业级性能目标交回调用方确认范围。按[公共查询规则](../../../../knowledge/common/signoz-query-policy.md)确定环境、业务服务、时间和有限结果数：企业无时间默认最近 24 小时；dagId 直接定位链，由助手管理检索范围，不先索要时间或 trace。已有执行、时间和结果直接复用。
-
-## 检索时间
-
-企业更新与 dagId 的检索窗口只在本节维护，其他查询规则仍按公共规则执行。
-
-- 企业更新查询未提供时间，或只说“最近”，使用当前时钟之前 24 小时，时间参数按[公共查询规则](../../../../knowledge/common/signoz-query-policy.md#查询约束)处理。一句告知“未提供时间，先查看正式环境最近 24 小时的更新，优先检查异常”，随即查询，不等待确认。报告说明查询时间范围。用户指定的时间、URL 时间和已确认范围优先，含糊但明确指向历史的“那天”等不能用最近窗口覆盖。
-- dagId 对应更新 chain ID，标识一条更新链，链内可能有多个节点、尝试和 trace；不能把它当作可反复运行的表资源 ID，也不能以“不是运行唯一标识”为由先索要时间。已有该链的时间或查询结果直接复用。仅在工具明确支持按 dagId 无时间定位时直接调用；当前工具要求时间边界时按下方规则生成范围，不传入缺失参数或猜测新工具能力。
-- 工具必须带时间且只有 dagId 时，由助手生成最近 24 小时作为内部首次检索范围，按同环境、服务、精确 dagId 查询属性，再按发现指引在同范围降级一次。开场只说明按此 DAG 查询链路，不要求用户确认检索时间。首查窗口用于发现，不定义该链的起止边界；命中后从实际记录恢复时间，沿精确 trace、chain 和显式链接继续。关联记录跨初始窗口时记录证据及新边界，不能把同链的早期提交或后续节点排除为无关执行。
-- 只有 dagId 且上述两查确实为空时，核对标识与过滤条件；已知数据源保留范围且用户未限定时间的，允许再做一次同环境、服务和精确链标识的时间扩展，最多覆盖已知保留期与最近 30 天的交集，记录新旧边界。使用已确认支持链标识的来源查询，不扫描企业或移除服务过滤。保留期未知、扩展仍为空或查询失败时，交付实际覆盖范围再问大致日期或最小缺口；不猜保留期、不循环扩展。
-- 企业无结果时先完成同范围降级，再说明覆盖范围并询问更早时间；不自动扩大企业扫描。历史对比仍以目标执行开始前 24 小时为基线，和以当前时钟为右边界的“最近更新”分别维护。
-
-## 企业入口
-
-1. 企业 ID 按更新观测中的 `corpId` 精确检索。只使用已知环境、服务和时间，不同时要求 `span=update`、`dagId` 非空或错误状态；企业字段可能位于进入更新之前的消费 span，失败条件应在后续关联的更新执行上核对。
-2. 先保留命中的 trace/span ID、时间、tableId 及实际返回的属性。企业属性的放置条件复用 `lookup:analysis-update-attempt-consumed`；只有 `corpId` 无法判定记录已经属于一次完整更新。
-3. 按[独立 Trace 的显式链接](../../../../knowledge/common/signoz-query-policy.md#独立-trace-的显式链接)查询关联执行，使用实际 link 或 `linked`，不把原 trace 的 ID 当作新 `update` trace 的 ID。发现结果已含消费 trace ID 和可用的链接来源时，直接按链接查关联更新；没有需要解释的消费阶段缺口时，不先重取消费 trace 或日志。可批量使用已经取得的精确 ID，不重新扫描企业范围。某一 `update` span 没有 `corpId` 不能用来排除其企业归属；同时不能根据企业或时间相同把无链接的执行并入。
-4. 从关联更新记录取得实际 dagId、tableId、traceId、时间、结果与耗时。“最近更新情况”先交付已观察到的概况，优先展示有明确失败、超时、OOM 或有证据支持的等待异常的执行；只有耗时长或缺结束记录不能直接判异常。有异常时在本次目标内继续核对相关证据，正常记录简述即可，不要求用户必须选择一条继续。多个不同异常需要深入且目标无法判断时才展示差异作最小消歧；不擅自挑最慢的一条或深挖全部候选。无明确异常时简洁说明观察结果和必要覆盖限制，不逐条展开内部字段与查询过程。
-
-## DAG 入口
-
-1. 用户给出的 dagId 用 `dagId` attribute 精确过滤，在同服务与已确认或内部生成的检索范围内检查更新提交和节点执行。该标识在更新记录中对应 chain ID，标识一条链而非其中单个节点或 trace；不要求用户先提供发生时间。链内记录的时间可以超出默认发现窗口，按公共规则沿实际证据恢复范围。
-2. 属性查询未命中或不可查询时，在同一范围使用 `lookup:analysis-update-intent-accepted` 和 `lookup:analysis-update-primary-node-result` 声明的 chain ID 日志签名降级一次。精确匹配实际 chain 值和签名，不仅搜索通用的 `dag` 字样。
-3. 日志命中后提取其真实 trace_id；没有该字段时按公共规则补取关联字段。已有 chain 和绝对窗口即可进入现有 `dag-chain` 查询计划，不要求用户另找 trace。提交早期失败可能尚未写入 dagId attribute，因此不能只看完成属性。
-
-## 字段与交付边界
-
-- 两个入口的首查和同范围降级复用公共查询预算；只有 dagId 可按公共规则作一次已知保留期内的时间扩展。取得执行后只沿精确 ID 补证；关联查询不是再次发现整个企业。无结果时区分查询为空、字段不可查、权限问题和本地响应交接失败，不写“企业／DAG 字段未采集”的通用结论。
-- XS03 的 `tenantId`、dagId、traceId 属于更新结果埋点；字段存在不证明该埋点可由 SigNoZ 检索。产生条件及覆盖复用 `lookup:analysis-update-primary-node-result`；仅在已经有可访问数据源或用户材料时使用，不能把它作为 SigNoZ 首查或必需回退。
-- 达到 limit、分页未完成或窗口不全时，报告“已观察到”的候选数量及覆盖限制，不报告企业全部更新数；节点成功不代表 DAG 完成，多个 span 不代表多次更新。
-- 发现阶段只解释原生记录和显式链接，不先要求 application 通过业务语义校验。选中执行后才按主 Skill 核对版本、范围、字段及关联边，未知版本不能被本指引补齐。已有精确 task 可继续取得 Metric，但不反向补造 DAG 关系。
-- 向调用方交接候选、排除依据、选中执行、范围与未完成动作；发现完成不等于诊断完成。性能目标继续由更新性能专项负责，来源／计数等有界事实问题由本 Skill 交付。

package/content/.agents/skills/analyze-analysis-table-update-runtime/references/update-diagnostic-contract.md

@@ -1,101 +0,0 @@
-# 更新证据摘要边界
-
-按[更新运行知识](../../../../knowledge/update/runtime-evidence.md)读取所需分片并解释证据。助手选择执行、构造查询并判断适用范围，无需生成应用 JSON 或执行查询规划命令。
-
-发布来源与字段要求见知识 manifest 和索引，本次行为以运行记录为准。unknown 表示版本、范围、关联或关键字段无法确认；needs_revalidation 表示已知版本或语义发生变化，或不满足适用要求。引擎统计、相近时间或猜测的默认值都不能补足这些证据。
-
-证据摘要保留当前范围、全部仍可信候选、所选运行、计数单位和各阶段测量结果，并说明反证、已验证关联、覆盖范围，以及分析停在哪一步。问题型入口负责最终根因、跨场景结论及处置排序。
-
-## 逻辑事件与身份术语
-
-| 逻辑项 | 含义 | 身份边界 | 不得等同于 |
-| --- | --- | --- | --- |
-| update request | 一次 producer 提交，携带 candidate 集合和业务上下文 | 显式 request/trace 或 producer key（如存在） | accepted chain 或已完成更新 |
-| candidate root | producer 在资格与图约简前提出的 table/resource | 当前 request 内的 candidate identity | effective root |
-| effective root | scheduler 按当前依赖关系约简后保留的 root | 显式 root 与 accepted chain | 所有关联 DAG node |
-| update chain | 一次提交上下文被控制面接受的范围 | 显式 chain ID | data load、chain 完成或物理提交 |
-| merged chain member | 被吸收到 node 级合并任务中的 chain | 显式 member chain ID 和 merge decision | 所有 chain 已合成一个 DAG 的证明 |
-| DAG extent | 按当前依赖视图从 effective root 可达的关联 node | 显式 dependency/control record | entry 数或成功 load 数 |
-| node | 以 table/resource 为范围的可执行任务 | chain 内显式 node/resource ID | 物理 engine task |
-| attempt / execution detail | 一个 node 的一次入队或消费执行记录 | 显式 execution-detail ID、node ID 和 chain ID | 独立 node 或成功 commit |
-| requeue | 已分类的重新派发路径，例如 lock/capacity/recovery | 显式 requeue reason 或 producer-consumer 证据 | 普通业务失败或重复物理工作 |
-| load outcome | 任务执行 load、reuse、bypass、skip 或 fail 的显式决策/结果 | 显式 load-result 证据 | 不存在 load result 时的 node success |
-| engine task | 只有显式 handoff/result 能确认的 engine 侧任务 | 显式 server-to-engine/task 关系 | 每个 node、trace 或成功 listener |
-| trace / span | 遥测执行范围 | 原生 trace/span identity | request、chain、node 或物理 commit |
-
-## 允许的关联边
-
-只有在目标范围内验证字段语义和唯一性后，才能确认以下关联边：
-
-1. trace 原生父子关系、link 或消息关系可以连接遥测范围。新的消费 trace 不会自动成为请求 trace 的子 trace。原生 trace 关系不能确认业务、更新或引擎交接关系；每条待确认的业务关联仍需具备完整的已声明业务键。
-2. 已提交 request 必须有明确的接受记录，或共享且经过语义验证的 request/chain key，才能关联到 update chain。
-3. Chain 必须通过显式 chain、node/resource、execution-detail key 或持久控制记录，才能关联到 node 或 attempt 证据。
-4. Merge 关系需要明确的原始 chain 和成员 chain 标识。
-5. Load outcome 或 engine task 需要显式 result 或 handoff key。`edge-load-operation-to-engine-task` 必须同时具备服务端调用范围，以及写入统计成功返回的 engine task ID；仅有原生 trace 关系无法确认这次交接。
-
-时间邻近、租户相同、显示名称相同、表数量相同或 trace 相邻，只能用于筛选候选，不能确认一次跳转、重复更新、merged chain 或物理写入。
-
-## 计数单位与对账
-
-每次测量只使用一个单位，并保持一致：input request、candidate root、effective root、accepted chain、merged-chain member、DAG node、execution attempt、requeue、load outcome、engine task、trace/span 或 successful physical commit。聚合前记录统计对象范围、时间含义、去重键、包含和排除规则，以及证据覆盖范围。
-
-Update request、chain、DAG node、attempt、load、engine task 和 successful physical commit 分别计数。
-
-| 比较 | 只有满足以下条件才有效 | 否则报告 |
-| --- | --- | --- |
-| request → effective root | 显式 request-to-root 映射和 filtering coverage | fan-out/filtering unknown |
-| effective root → DAG node | 同一 chain/version 下的显式 dependency extent | graph expansion unknown |
-| chain → attempt | 显式 chain/execution key 和 retry 分类 | control acceptance，不是 execution 数 |
-| attempt → load | 显式 attempt/load result 映射 | execution 不代表物理 load |
-| load → engine task/commit | 显式 handoff/task 及 outcome/commit 证据 | 不得形成 engine 或 commit 结论 |
-| trace/span → 任一业务单位 | 显式语义 attribute 和去重规则 | 只能计为 telemetry 数量 |
-
-entry count、DAG count、node/update-span count、trace count 和 physical successful-commit count 不能互换。重复的 attempt 或 span 不能证明重复物理更新；多个 request 可能被过滤或合并，一个 root 也可能展开为多个节点。
-
-## 判断矩阵
-
-| 问题 | 必需证据 | 可直接回答 | 停止或移交 |
-| --- | --- | --- | --- |
-| 输入是否产生了被接受的控制面任务？ | 显式 request/chain acceptance key | 只分类 acceptance | 无 key：request-to-chain 为 unknown |
-| 为什么 entry 多于 chain 或 node？ | 冻结的计数单位及显式 root/merge/dependency 映射 | 识别已测量的 filtering、fan-out 或 merge 关系 | 无映射：报告不可比较 |
-| 重复 node 是否是 retry？ | 相同 node/attempt 及显式 requeue reason | 分类已观测的 requeue | 无 reason：重复信号不能证明 retry |
-| Node 是否写入数据？ | 显式 load result | 按记录分类 load/reuse/skip/failure | 无 load result：不得声称物理写入 |
-| Engine 是否 commit？ | 显式 handoff、engine task 和 commit outcome | 陈述有范围限制的 engine result | 无显式 engine relation：停在 server 边界 |
-| 权限/成员事件是否导致 DAG？ | 显式 producer/acceptance/chain key | 陈述已验证的 edge | 只有邻近事件/tenant/name：保留 candidate 并停止 |
-
-## 选择运行与阶段测量
-
-- 保留全部可信运行候选，按用户操作和明确关系选择目标；不按最新、最慢或链接存在性静默挑选。失败、成功重试、其他查询和正常基线分别保存。
-- 每段耗时保留原始开始/结束、字段口径和覆盖范围。异步阶段或并发分支可能重叠，不能把父子/并发耗时相加为端到端时间。
-- load/listener 的成功不是整链或全部分区的 successful physical commit，成功尝试也不自动代表整链成功。恢复或重试行为只报告实际观察到的分支。
-- 分页、截断、保留期缺失、字段缺失与关联缺口分别描述。有限样本不能代替总体；一次完整查询已回答计数时直接整理，不重复聚合。需要相对历史变化时另建可比基线，时间与证据独立。
-
-## Trace 优先与时间窗优先计划
-
-### Trace 优先
-
-1. 从提供的 Trace ID 或显式 producer key 开始，记录绝对时间区间及其来源时区。
-2. 确认 trace 记录对应的逻辑事件类型，并寻找显式 chain acceptance key。
-3. 存在原生关系或已验证的 chain/node/attempt key 时，才扩展到消费 trace；没有显式证据的跳转只保留为候选。
-4. 按顺序检查显式 merge、requeue、load 和可选 engine-task outcome，在第一条缺失的允许关联边停止。
-
-### 时间窗优先
-
-1. 查询前确定统计对象范围和计数单位，并保持一致。
-2. 使用完整的服务端聚合证据确定查询区间。原始记录只有经分页和覆盖核对确认完整后，才能代表总体；否则仅作为样本。
-3. 只使用已验证字段和去重规则，分别测量 request、chain、distinct node、attempt、load 和 engine task。
-4. 用少量代表性 trace 解释已测量的过程；样本不能代替总体聚合。
-
-查询前，先按逻辑条件确定候选范围，再将其中有界的过滤条件适配到当前可用的 SigNoZ MCP。分页、覆盖范围、统计对象范围和实际字段的发现过程保留在本次调查证据中，不回写到由来源材料提炼的知识包。
-
-## 降级与停止规则
-
-运行版本未知或关键字段缺失时保留 `unknown`；已知版本不匹配，或 tag/log 含义发生变化时使用 `needs_revalidation`。存在已生效的失效条件（包括配置变更）、范围不匹配、归属其他服务、必要身份关联缺失、分页不完整或必需证据不可用时，使用 `unknown`。不得仅为制造关联而扩大时间窗。
-
-当请求的分类已在声明的覆盖范围内获得证据、必要关联边不可用，或下一步需要研发确认产品行为、补充采集或分析因果时停止。说明下一步需要的最小检查，不给出猜测性结论。
-
-## 职责与移交
-
-本 Skill 与 manifest 只解释匹配的、无需产品源码即可核对的观测要求。知识以可审查的索引和小分片存储，生产侧候选扫描台账不复制到使用方仓库，只保留其原始哈希和数量作为来源证明。已有 log、trace 摘要和运行导出继续离线分析。需要查询时，按当前缺口选择知识中的关联键和字段，使用当前可用的 SigNoZ MCP；缺少 MCP 配置时，返回转交 `setup-signoz-mcp` 的建议。对显式关联的 engine task 或 metric，向调用方返回关联材料及转交 `analyze-engine-metric` 的建议。
-
-产品行为再验证和完整产品根因调查超出本分析流程的范围。停止时说明还需验证哪项产品行为，交由研发继续；本 Skill 不调查源码或诊断完整因果链。

package/content/.agents/skills/analyze-engine-metric/SKILL.md

@@ -1,76 +0,0 @@
----
-name: analyze-engine-metric
-description: 当用户提供 SigNoZ trace/metric 链接、MetricOuts 日志或完整引擎 metric 文件，要求分析执行耗时、内存、Pipeline、Operator、数据规模、资源边界或执行差异时使用；也供性能场景 Skill 深挖引擎证据。该 Skill 自行获取、解析并解释 Metric，不负责 DSL 或业务步骤映射。
----
-
-# 分析引擎 Metric
-
-获取并解释当前执行的引擎证据，说明任务结果、数据规模、耗时、内存和仍需确认的内容。助手选择执行、查询并判断原因，解析器整理事实。用户直接请求时，由本 Skill 交付；性能场景调用时，返回执行层判断，业务配置和最终业务根因由上游确认。
-
-## 从已有材料继续
-
-| 已有材料 | 当前动作 |
-|---|---|
-| 对应执行的结构化报告 | 核对 task、正文 hash、schema_version、normalization_version 和完整性后复用，按问题读取相关事实 |
-| MetricOuts 原始响应或完整 Metric 文件 | 直接解析，跳过执行发现 |
-| 已选 task 或 Metric 链接 | 在冻结范围内取得该 task 的正文 |
-| 已保存 trace 或少量日志 | 依据[执行关联与获取方法](../../../knowledge/engine/metric-retrieval.md)恢复任务，不重复查询 |
-| 只有精确 trace | 先读取当前缺少的时间线或任务属性，按用户问题选择执行 |
-| 两组材料 | 分别冻结目标与基线，再比较，保留不可比部分 |
-
-已有材料足够时直接解释。无法确认获取状态时，只补当前缺口。旧或不匹配产物从保留材料离线重建；旧摘要已有伴随 hash 却无事实路径时，从留存 MetricOuts 响应重建全部产物。
-
-## 获取和选择
-
-需要新增证据时复用[公共查询规则](../../../knowledge/common/signoz-query-policy.md)。字段、关联键、查询例子、精确 trace 回退见[获取方法](../../../knowledge/engine/metric-retrieval.md)，只读当前需要的部分。
-
-- 按当前问题和明确关联选择执行。保留失败、重试、混合执行和无链接候选；已选执行不能被更慢、更新或有链接的其他任务替换。耗时只用于排序。
-- 从 trace 整理任务绑定、补取属性和核对覆盖，按[获取方法 · 从 trace 整理任务绑定](../../../knowledge/engine/metric-retrieval.md#从-trace-整理任务绑定)直接完成，不依赖脚本。
-- 优先使用原始 Metric 链接的 task、logger、过滤和时间，读法见[获取方法 · Metric 链接与任务日志](../../../knowledge/engine/metric-retrieval.md#metric-链接与任务日志)；按当前 MCP 工具声明查询，不重新设计范围或删除不认识的条件。
-- 同 task 明确记录 `not submitted, skip finish` 时，交付提交前失败；预生成 ID 或其他缓存任务不能证明本次已计算。
-- 已选定的慢或失败引擎执行默认获取并解析 Metric。只有明确未提交、用户限定不读取或实际取证受阻时跳过。仅有 `polars query timeout` 且缺 task 时继续恢复关联，不能直接结束。
-- 单次失败不要求成功样本。历史变化目标按公共规则主动发现基线；两侧材料独立获取，不能互换时间窗或以附近执行替代。
-
-原始响应直接交给解析器或系统临时文件，完整正文保留到本次调查结束；交接失败重试本地传递，不重新获取正文。不得把原始响应、凭据或业务载荷写入工作区。
-
-## 统一解析入口
-
-在仓库根目录调用 `python3 .agents/skills/analyze-engine-metric/scripts/analyze_engine_metric.py`。`<dir>` 使用本次调查独占的系统临时目录。
-
-| 输入 | 参数 |
-|---|---|
-| 已选 task 的原始日志响应 | `--metric-log-json <path或-> --task-name <task> --artifacts-dir <dir>` |
-| 完整 Metric 文件 | `--metric <file> --artifacts-dir <dir>` |
-| 两次可比执行 | `--metric <before> --compare-metric <after> --artifacts-dir <dir>` |
-| 复用产物 | `--metric <原文> --reuse-summary <summary> --artifacts-dir <dir>` |
-
-解析日志前，助手先选定执行和 task，通过 `--task-name` 传入所选 task。解析器只核对正文 task 是否一致，不替助手选择执行。通过 `--query-limit` 传入日志查询的已知上限；上限未知时不套用另一份查询值，达到上限不能声明正文唯一。
-
-解析生成 `metric_summary.json` 和 `metric_report.json`。先读紧凑事实及报告路径，再按需展开；`--view summary` 显示已保存的排名。主明细和完整伴随摘要分别保存、解析，保留时间、hash、任务核对及独立路径。只有任务核对成立且产物完整时使用伴随信息，不合并不同快照的状态、内存或耗时。
-
-内存问题先查看紧凑摘要的 `memory_overview`，展示不足时沿报告指针展开；分组口径、不能相加的字段和旧摘要补齐规则见[事实产物](../../../knowledge/engine/metric-artifacts.md)。
-
-解析状态区分完整明细、完整摘要、真实空结果、分页/截断、正文不完整、任务不匹配、正文歧义、格式或本地处理失败。只有服务端确实返回空 rows 才能说查询为空；界面截断、传递失败或解析失败不能说未生成 Metric。完整 `RUNNING` 摘要和 `tasks=0` 仍是快照，不证明未提交或最终成功。
-
-## 解释事实
-
-首次解读字段时按需读取[Metric 语义](../../../knowledge/engine/metric-semantics.md)，同轮复用。
-
-按本次信号查阅[常见性能问题](../../../knowledge/engine/performance-patterns.md)中的相关条目，核对判断依据、其他可能解释和建议前提，无需遍历全部场景。
-
-- 先核对任务结果与直接错误，再连接热点、输入输出、IO、中间状态、并行度和资源边界。最慢 Pipeline 不自动是根因，高阻塞不单独证明 IO、网络或下游原因。
-- pending 是调度等待，blocked 是依赖等待。比较 active CPU/wall 前，先确认范围和聚合对象；累计 sum 除以 Pipeline 墙钟不能当作占比。JIT 后端的编译和 active 计时分别查看，不覆盖 Pipeline 汇总，也不相加为查询总时长。
-- 只有总行数时，不推断高基数、数据倾斜或 Join 放大；继续核对局部输入和中间状态。
-- `query_peak_memory_when_pipeline_closed` 是查询快照；arena 等算子专用字段分别保留来源，不将不同记录相加为同时驻留量。
-- 容量显示值可能舍入，精确边界以同 task 的整数字节证据核对；前后对比同时核对内存跟踪范围，不只比较同名字段。
-- 只有 schema_version=2、complete=true 的事实产物才引用算子比例。输入缺失、负哨兵、未知单位或聚合口径不同保持不可计算，不用相邻节点输出代替输入，不跨 Join/Aggregate/Union/Exchange 手算放大率。
-- 两份 Metric 的比较核对 `metric_comparison.json` 的对齐依据、歧义和未匹配项。数值变化不证明业务条件可比，也不自动解释配置变化或唯一原因。
-- 保留全部对象、原值、来源和未知项；摘要展示范围有限时沿报告指针展开。只有引擎证据时，结论停在执行层，页面步骤映射交给场景分析。
-
-## 交付
-
-直接向使用者答复时，按[公共交付说明](../../../docs/diagnostic-report.md)组织结果，本轮已读则复用；由性能专项调用时返回执行层判断及其范围，不自行扩写为业务根因。
-
-返回当前执行的判断、关键事实与来源、反证、限制，以及下一步判断所缺的证据。简单数值或链接直接回答；解释复杂原因时，用少量关键证据说明判断依据，不罗列全部指标，也不因缺少基线额外创建任务。
-
-交付时按[需求反馈](../../../docs/diagnostic-feedback.md)复核本轮已遇到的场景知识缺口、项目优化项和文档差异，复用现有证据，由最终交付方汇总一次。

package/content/.agents/skills/analyze-engine-metric/agents/openai.yaml

@@ -1,13 +0,0 @@
-interface:
-  display_name: "分析引擎 Metric"
-  short_description: "获取并分析引擎 Metric，解释执行热点和资源问题"
-  default_prompt: "使用 $analyze-engine-metric 获取并分析这次执行的 Metric，说明主要 Pipeline、Operator、数据条件和资源边界。"
-
-dependencies:
-  tools:
-    - type: "mcp"
-      value: "signoz"
-      description: "用于从 Trace 和 Logs 获取 Metric 证据的 SigNoZ MCP 服务"
-
-policy:
-  allow_implicit_invocation: true

package/content/.agents/skills/analyze-engine-metric/scripts/analyze_engine_metric.py

@@ -1,270 +0,0 @@
-#!/usr/bin/env python3
-"""Extract and normalize Metric facts. The diagnostic Skill interprets them."""
-
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-from pathlib import Path
-import sys
-
-SCRIPT_DIR = Path(__file__).resolve().parent
-if str(SCRIPT_DIR) not in sys.path:
-    sys.path.insert(0, str(SCRIPT_DIR))
-from engine_metric_analysis import (
-    NORMALIZATION_VERSION,
-    SCHEMA_VERSION,
-    build_report,
-    build_memory_overview,
-    build_summary,
-    compare_reports,
-)
-from engine_metric_analysis import signoz_extract as metric_extractor
-
-
-def _write_json(path, value):
-    path.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-
-
-def analyze_metric(metric_path: Path, artifacts_dir: Path, *, top: int = 5):
-    artifacts_dir.mkdir(parents=True, exist_ok=True)
-    report = build_report(metric_path, top=top)
-    report_path, summary_path = artifacts_dir / "metric_report.json", artifacts_dir / "metric_summary.json"
-    summary = build_summary(report, report_path, top=top)
-    _write_json(report_path, report)
-    _write_json(summary_path, summary)
-    return {"report": report, "summary": summary, "report_path": str(report_path), "summary_path": str(summary_path)}
-
-
-def analyze_metric_collection(receipt, task_name: str, artifacts_dir: Path, *, top: int = 5):
-    """Keep the selected detail and companion snapshots in separate reports."""
-    result = analyze_metric(Path(receipt["metric_path"]), artifacts_dir, top=top)
-    if task_name not in result["report"]["task_names"]:
-        raise metric_extractor.MetricExtractionError("Metric task does not match the selected execution", "task_mismatch")
-    collection = {key: value for key, value in receipt.items() if key != "body"}
-    for companion in collection["companion_candidates"]:
-        facts = analyze_metric(Path(companion["metric_path"]), artifacts_dir / "companions" / companion["body_sha256"], top=top)
-        summary = facts["summary"]
-        companion.update({key: summary[key] for key in ("schema_version", "task_names", "complete", "collection_status", "coverage")})
-        companion.update({"report_path": facts["report_path"], "summary_path": facts["summary_path"],
-                          "task_identity_matches": summary["task_names"] == [task_name],
-                          "job_states": [{key: job[key] for key in ("task_name", "status", "report_pointer")}
-                                         for job in summary["job_snapshots"]]})
-    result["summary"]["collection"] = collection
-    _write_json(Path(result["summary_path"]), result["summary"])
-    return result
-
-
-def validate_reuse(summary_path: Path, metric_path: Path):
-    summary = json.loads(summary_path.read_text(encoding="utf-8"))
-    report = json.loads(Path(summary["report_path"]).read_text(encoding="utf-8"))
-    required = {"task_names", "coverage", "pipelines", "source_lines", "query_fields", "summary_metrics", "data_scale_transitions", "complete", "collection_status"}
-    if not required.issubset(report) or any(key not in summary for key in ("task_names", "coverage", "complete", "collection_status")):
-        raise ValueError("Artifact is incomplete; reparse the retained Metric locally")
-    digest = hashlib.sha256(metric_path.read_bytes()).hexdigest()
-    if any(v.get("schema_version") != SCHEMA_VERSION or v.get("body_sha256") != digest for v in (summary, report)):
-        raise ValueError("Artifact schema or source hash changed; reparse the retained Metric locally")
-    if any(v.get("normalization_version") != NORMALIZATION_VERSION for v in (summary, report)):
-        raise ValueError("Artifact normalization changed; reparse the retained Metric locally")
-    if summary.get("task_names") != report.get("task_names"):
-        raise ValueError("Artifact task identities do not match")
-    if any(summary[k] != report[k] for k in ("complete", "collection_status", "coverage")):
-        raise ValueError("Artifact coverage does not match the full report")
-    if any(job["fields"].get(key, {}).get("unit") == "count" for job in report.get("jobs", [])
-           for key in ("queue_time", "wait_resource_time", "plan_time", "start_time")):
-        raise ValueError("Artifact treats a unitless phase field as a count; reparse the retained Metric locally")
-    for companion in summary.get("collection", {}).get("companion_candidates", []):
-        if "summary_path" not in companion:
-            raise ValueError("Companion facts are missing; reparse the retained MetricOuts response locally")
-        facts = validate_reuse(Path(companion["summary_path"]), Path(companion["metric_path"]))
-        if any(companion[key] != facts[key] for key in ("body_sha256", "report_path", "task_names", "complete", "collection_status", "coverage")):
-            raise ValueError("Companion artifact does not match its collection record; reparse the retained response locally")
-    if "memory_overview" not in summary:
-        summary["memory_overview"] = build_memory_overview(report)
-        _write_json(summary_path, summary)
-    return summary
-
-
-def compact_summary(summary, summary_path):
-    keys = (
-        "schema_version",
-        "normalization_version",
-        "report_path",
-        "body_sha256",
-        "source",
-        "task_names",
-        "collection_status",
-        "complete",
-        "input_format",
-        "coverage",
-        "job_snapshots",
-        "execution_overview",
-        "memory_overview",
-        "collection",
-    )
-    return {
-        **{key: summary[key] for key in keys if key in summary},
-        "summary_path": str(summary_path),
-    }
-
-
-def main():
-    parser = argparse.ArgumentParser(description=__doc__)
-    source = parser.add_mutually_exclusive_group()
-    source.add_argument("--metric")
-    source.add_argument(
-        "--metric-log-json", help="Original MCP response path, or '-' for stdin"
-    )
-    parser.add_argument(
-        "--query-limit",
-        type=int,
-        help="Known limit of the Metric log query",
-    )
-    parser.add_argument("--task-name")
-    parser.add_argument("--compare-metric")
-    parser.add_argument(
-        "--artifacts-dir",
-        help="Required for Metric analysis; use a system temporary directory",
-    )
-    parser.add_argument("--top", type=int, default=5)
-    parser.add_argument(
-        "--json",
-        action="store_true",
-        help="Retained for compatibility; stdout is always factual JSON",
-    )
-    parser.add_argument(
-        "--view",
-        choices=("compact", "summary"),
-        default="compact",
-        help="Single-Metric stdout is compact by default; summary includes the saved rankings",
-    )
-    parser.add_argument(
-        "--reuse-summary",
-        help="Validate existing v2 artifacts against --metric without querying",
-    )
-    args = parser.parse_args()
-    if args.top < 1:
-        parser.error("--top must be positive")
-    if args.query_limit is not None and args.query_limit < 1:
-        parser.error("--query-limit must be positive")
-    if not (args.metric or args.metric_log_json):
-        parser.error("provide --metric or --metric-log-json")
-    if (args.compare_metric or args.reuse_summary) and not args.metric:
-        parser.error("comparison and reuse require --metric")
-    if (args.metric or args.metric_log_json) and not args.artifacts_dir:
-        parser.error("Metric analysis requires --artifacts-dir")
-    try:
-        directory = Path(args.artifacts_dir).resolve()
-        receipt = None
-        if args.metric_log_json:
-            if not args.task_name or args.compare_metric or args.reuse_summary:
-                parser.error(
-                    "--metric-log-json requires --task-name and cannot combine with comparison/reuse"
-                )
-            payload = metric_extractor.read_payload(args.metric_log_json)
-            receipt = metric_extractor.write_metric(
-                payload, args.task_name, directory, query_limit=args.query_limit
-            )
-            metric_path = Path(receipt["metric_path"])
-        else:
-            metric_path = Path(args.metric)
-        if args.reuse_summary:
-            if args.compare_metric:
-                parser.error("--reuse-summary cannot combine with --compare-metric")
-            output = validate_reuse(Path(args.reuse_summary), metric_path)
-            if args.task_name and args.task_name not in output["task_names"]:
-                raise metric_extractor.MetricExtractionError(
-                    "Reused Metric task does not match the selected execution",
-                    "task_mismatch",
-                )
-        else:
-            result = (
-                analyze_metric_collection(
-                    receipt, args.task_name, directory, top=args.top
-                )
-                if receipt
-                else analyze_metric(metric_path, directory, top=args.top)
-            )
-            if args.task_name and args.task_name not in result["report"]["task_names"]:
-                raise metric_extractor.MetricExtractionError(
-                    "Metric task does not match the selected execution", "task_mismatch"
-                )
-            output = result["summary"]
-            if args.compare_metric:
-                target = analyze_metric(
-                    Path(args.compare_metric),
-                    directory / "comparison_target",
-                    top=args.top,
-                )
-                comparison = compare_reports(
-                    result["report"], target["report"], top=args.top
-                )
-                comparison["before"]["report_path"] = result["report_path"]
-                comparison["after"]["report_path"] = target["report_path"]
-                comparison_path = directory / "metric_comparison.json"
-                _write_json(comparison_path, comparison)
-                output = {
-                    "schema_version": SCHEMA_VERSION,
-                    "comparison_path": str(comparison_path),
-                    "aligned_count": len(comparison["operator_data_scale_changes"]),
-                    "ambiguity_count": len(
-                        comparison["operator_alignment_ambiguities"]
-                    ),
-                    "job_aligned_count": len(comparison["job_changes"]),
-                    "job_ambiguity_count": len(comparison["job_alignment_ambiguities"]),
-                    "before_status": result["summary"]["collection_status"],
-                    "after_status": target["summary"]["collection_status"],
-                    "before_summary": result["summary_path"],
-                    "after_summary": target["summary_path"],
-                }
-                output["before_overview"] = result["summary"]["execution_overview"]
-                output["after_overview"] = target["summary"]["execution_overview"]
-        if "collection_status" in output and args.view == "compact":
-            summary_path = (
-                Path(args.reuse_summary)
-                if args.reuse_summary
-                else directory / "metric_summary.json"
-            )
-            output = compact_summary(output, summary_path)
-        print(
-            json.dumps(
-                output, ensure_ascii=False, indent=2 if args.view == "summary" else None
-            )
-        )
-        statuses = [
-            output.get(k)
-            for k in ("collection_status", "before_status", "after_status")
-        ]
-        return (
-            2
-            if any(status in {"format_error", "body_incomplete"} for status in statuses)
-            else 0
-        )
-    except json.JSONDecodeError as exc:
-        print(
-            json.dumps(
-                {"collection_status": "format_error", "error": str(exc)},
-                ensure_ascii=False,
-            )
-        )
-        return 2
-    except metric_extractor.MetricExtractionError as exc:
-        print(
-            json.dumps(
-                {"collection_status": exc.status, "error": str(exc)}, ensure_ascii=False
-            )
-        )
-        return 2
-    except (ValueError, OSError, KeyError) as exc:
-        print(
-            json.dumps(
-                {"collection_status": "local_processing_error", "error": str(exc)},
-                ensure_ascii=False,
-            )
-        )
-        return 2
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/content/.agents/skills/analyze-engine-metric/scripts/engine_metric_analysis/__init__.py

@@ -1,11 +0,0 @@
-"""Metric format parsing and factual normalization."""
-from .metric_analyzer import (
-    NORMALIZATION_VERSION,
-    SCHEMA_VERSION,
-    build_report,
-    build_memory_overview,
-    build_summary,
-    compare_reports,
-)
-
-__all__ = ["NORMALIZATION_VERSION", "SCHEMA_VERSION", "build_report", "build_memory_overview", "build_summary", "compare_reports"]