@fx-data/ai-diagnostics 0.1.20261026070913 → 0.1.20261107142011

package/content/.agents/skills/diagnose-performance/SKILL.md

@@ -1,77 +0,0 @@
----
-name: diagnose-performance
-description: 当用户要排查 fx-data 端到端慢、超时、内存超限、OOM、MemoryLimitExceeded、资源消耗异常或性能回归时使用。接受资源、现象、时间、trace、日志或截图，选择分析表、组件、仪表板、更新专项，协调跨场景调查并汇总证据；不替代专项分析。仅配置 SigNoZ 或解读一份 engine metric 时使用对应公共 Skill。
----
-
-# 性能诊断
-
-负责确定性能调查范围、安排必要专项并交付有证据支持的判断。不要求用户判断业务场景或先提供 traceId、Metric。非性能问题交回根 Agent 重新路由。
-
-按用户当前问题推进：查记录先给概况，取数值或链接先用已有执行材料，分析原因时再深入。事实型追问沿用当前调查；原诊断还有必要分析时，回答后继续。
-
-从日志提出和核对候选原因时，参考[问题定位方法](../../../docs/architecture.md#每一步都用来区分原因)。专项提供字段和取证方法，由助手按当前线索选择下一步。
-
-## 工作流
-
-```text
-确定范围 → 选择专项 → 专项取证（含 Metric）→ 必要时进入关联场景 → 交付
-```
-
-1. 确定范围：按下方“从现有线索开始”确认对象、时间、环境和目标执行。
-2. 选择专项：一个场景明确时直接进入；多场景线索从证据最充分的一处开始。
-3. 专项取证：专项在本场景内完成取证，已选定慢或失败引擎执行时由专项直接调用 `$analyze-engine-metric`，不先回到本 Skill 转发。
-4. 关联场景：专项返回其他场景线索时，由本 Skill 判断是否进入，保持同一调查范围。
-5. 交付：满足“交付与停止”后输出结果。
-
-## 从现有线索开始
-
-- 环境、时间和历史对比的默认值见[公共查询规则](../../../knowledge/common/signoz-query-policy.md)的“默认值速查”，不向用户重复索要已有信息。“之前没超限”“以前正常”“最近变慢”已经是历史对比目标，不等待用户再次说“帮我对比”。
-- 企业更新或 dagId 是更新调查入口，按用户目标进入更新性能专项；只有企业 ID 而未说明要看什么时，合并询问更新现象和时间，不扩展成企业全部性能调查。
-- 场景明确时直接选择专项：分析表 `$diagnose-dataset-performance`、组件 `$diagnose-component-performance`、仪表板 `$diagnose-dashboard-performance`、更新 `$diagnose-update-performance`。
-- 仪表板内组件异常先由仪表板专项[有界核对组件单独计算](../diagnose-dashboard-performance/SKILL.md#组件取数先做对照)；未找到对照仍继续本次异常分析，不先要求用户提供成功 trace。
-- 只有 trace、执行链接或场景不明时，按需读取 [trace 路由](../../../knowledge/common/trace-routing.md)，用最小摘要选择起点。公共路由只返回场景及依据，不调用 analyzer；识别为更新后仍先进入 `$diagnose-update-performance`。公共知识无法识别时，以实际接口、span 或 attribute 搜索并只读命中场景的 `observability.md`。
-- 命中共享的外部组件取数入口时，必须先读取或复用[外部组件来源判定](../../../knowledge/common/trace-routing.md#外部组件取数入口)，按同一入口父子链确认来源，再进入组件或仪表板专项。不能仅凭最外层 HTTP span 或共享 span 名分流。
-- 多场景线索从证据最充分的一处开始，保留其他关联；调查起点不等于根因位置，需要跨场景核对时再进入第二个专项。用户明确只要求获取或解读 Metric 时，交给 `$analyze-engine-metric`；端到端性能问题则继续调查业务场景。
-- 只有资源或笼统的“性能问题”时，确认查询范围后对有限候选执行做浅分型，区分场景/执行形态、成功与失败、OOM/timeout 等异常。不要直接深挖最慢的成功执行，也不静默选择最新或最严重的一条。
-- 用户已明确内存超限、OOM、保存失败等失败现象时，以失败签名作为首次检索条件；执行类型只作上下文。不同类型具有相同失败签名和计算链路时可以联合解释，不因执行类型不同而请求消歧；各执行的计算证据仍须分别关联。
-- 只有一类候选明显吻合时继续；多个独立问题仍可信，或不同失败指向不同原因且目标不明时，展示差异，请用户做一次最小消歧。完成分型不等于需要把每类候选都分析到底。仅有宽泛现象时只补能进入下一步的 1～3 项信息，不机械要求 traceId。
-
-## 取证与交接
-
-已有日志、trace 导出或 Metric 足够时先离线处理。需要线上补证时读取[公共查询规则](../../../knowledge/common/signoz-query-policy.md)和[环境选择规则](../../../knowledge/common/signoz-environments.md)，本轮已读则复用。已确认范围和完整结果在本次调查中复用，切换场景不重新加载或重做发现。
-
-首次使用业务 Knowledge 时按 [知识适用性](../../../knowledge/common/knowledge-applicability.md) 核对范围和实际记录；有产品版本则辅助核对，版本未知仍可解释直接观测事实，保留版本相关判断。更新知识的专用校验由 analyzer 完成。
-
-内部调查摘要记录用户目标与执行范围、选中/排除候选、证据与反证、有效产物路径、原始执行/Metric 链接及覆盖范围，以及缺口和下一项动作。接续或进入专项时，交接这份摘要、新增信息和当前问题，无需复制全部历史或重新取证。
-
-调用 Skill 表示按其方法完成专项，不等于必须创建子代理。只有相互独立且都对当前判断必要的子任务才并行；依赖前一步结果的查询顺序执行。
-
-- 更新性能必须先进入 `$diagnose-update-performance`，再由它调用共享 update runtime analyzer 取得证据摘要；性能调查不绕过该场景专项直接解释更新 Knowledge。
-- 保留专项返回的证据、反证、限制和关联场景。不替代场景 Skill 或 engine Skill 重新分析；不扩大专项结论的置信度，不在专项未给方案时自行发明方案。Experience 只能生成假设，指南只解释可能行为。
-- 专项返回或 MCP 配置完成后继续未完成动作，不能把交接当作本轮停止条件。
-
-线上操作保持只读；配置、授权、业务操作和凭据处理遵守根 `AGENTS.md`。工具问题阻断补证时使用 `$setup-signoz-mcp`，恢复后继续原调查；已有材料足够则直接继续离线分析。
-
-## 失败分析的完成条件
-
-本节是各性能专项共用的 Metric 取证门槛，专项只引用、不另写版本。
-
-深入计算前区分失败在提交前、计算中还是结果返回时。已取消或尚未提交的执行先解释取消链、资源等待或准入条件；task ID、Metric 链接或整数超时时长不能证明已发生计算。同 task 的明确未提交证据优先于以下 Metric 要求，不查询注定不存在的计算统计。
-
-OOM、超时等失败模式不等于端到端根因。行数、内存、超时等保护阈值是直接失败条件（直接触发条件）；还要解释本次执行为什么达到该规模，保留输入与放大过程、相关 Operator、承接数据的执行阶段和最终阈值。只有阈值和总量时，不能写成业务根因。
-
-只有业务层 `polars query timeout` 时，即使普通 trace 详情没有 `taskName/metric`，也要进入 `$analyze-engine-metric` 的定位执行步骤，补读本次执行属性或从同 trace 的提交日志恢复 task。不能把“尚未查关联属性”当作“Metric 不可取得”；同 task 已明确未提交时仍按提交前失败交付。
-
-- 已选定的慢或失败引擎执行有 task/Metric 时，默认获取并解析 Metric；只有明确未提交、用户限定不读取或实际取证受阻时才跳过，并记录依据。缺属性先补读或恢复 task，不把尚未尝试当作取证受阻。
-- 单次失败诊断是默认模式。单份失败 Metric 可支持本次输入如何形成当前规模并触发资源边界，不能证明相对历史变化。没有基线时先完成单次失败诊断，不得把成功 trace 设为继续单次诊断的必填材料；不能用索要成功样本替代尚未完成的失败 Metric 分析。
-- 用户明确选择成功/失败对比，或主动提供可比成功执行时，把成功样本作为基线立即交给 `$analyze-engine-metric`；它不受资源发现阶段“不要深挖成功候选”的限制。取得两侧 Metric 并使用事实对比结果，各侧保持独立执行范围。
-- 引用 Operator 输入输出比例时，只消费 `$analyze-engine-metric` 取得的 `metric_report.json` 事实；要求 schema_version=2、complete=true，逐项使用 `data_scale_transitions` 的明确值及同口径 `input_output` 计算。不得从原始 Metric、不同 Pipeline 或非相邻节点手算新的放大关系；字段不可用时报告缺口。
-- 对比结果中的失败状态仍需同 task 错误日志确认。取得 `MemoryLimitExceeded` 等直接错误后，可将“达到内存边界”表述为已确认的直接失败原因，但不修改 Metric 产物，也不据此认定业务根因。
-
-## 交付与停止
-
-首次交付前读取 [诊断结果交付](../../../docs/diagnostic-report.md)，已读则复用。面向使用者交付，先说明业务结论，再给运行证据和复核依据；排查不以使用者拥有产品代码环境为前提，不默认展示调用了哪个 Skill。
-
-- 必要的 Metric 获取解析已完成或有明确跳过依据，且证据已解释用户现象和关键触发条件：完成交付，不重复获取正文。
-- 候选执行、环境或资源仍有实质歧义：展示差异，提出一次最小消歧。
-- 缺少必要证据或超出知识覆盖：交付阶段性结论、可信假设、缺口与最小验证动作；假设的使用范围见[助手执行契约](../../../AGENTS.md#3-诊断执行与证据边界)。

package/content/.agents/skills/diagnose-performance/agents/openai.yaml

@@ -1,7 +0,0 @@
-interface:
-  display_name: "性能诊断总控"
-  short_description: "组织性能问题的场景路由、证据推进、专项协作与结果汇总"
-  default_prompt: "使用 $diagnose-performance 组织这次性能问题的诊断和专项分析。"
-
-policy:
-  allow_implicit_invocation: true

package/content/.agents/skills/diagnose-update-performance/SKILL.md

@@ -1,55 +0,0 @@
----
-name: diagnose-update-performance
-description: 当 $diagnose-performance 已明确把一次更新慢、超时、内存超限、OOM、资源消耗异常或性能回归调查交给更新场景，并提供性能目标、环境、时间窗及 update run/trace/table 等候选锚点时使用。它通过 $analyze-analysis-table-update-runtime 获取版本匹配的更新运行证据摘要，只负责运行选择、基线比较、瓶颈归因、下游影响和性能结论，完成后返回 $diagnose-performance；不得由用户请求隐式触发。
----
-
-# 更新性能排查
-
-## 接收本次调查
-
-只接受 `$diagnose-performance` 的显式调用。输入至少说明：
-
-- 用户要解释的慢、超时、资源消耗或回归目标；
-- 环境、绝对时间窗与时区；
-- 已知 update run、trace、table 或其他候选锚点；
-
-已有正常执行、分位数、对照窗口或下游现象时一并交接；没有正常样本不阻断单次失败分析。
-
-缺少性能目标或调查负责人的交接时不启动。多个运行仍可信且无法区分时，向负责人说明候选差异和所需的最小选择证据，不自行挑选“最新”或“最慢”的一个。
-
-## 取得更新记录解释
-
-输入只有企业 ID 或 dagId 时，将目标和已确定范围交给 analyzer 的[发现指引](../analyze-analysis-table-update-runtime/references/discover-update-executions.md)，先取得候选再选择执行；不要求用户先提供 Trace。企业候选较多时返回分布和必要消歧，禁止把未选中的多个执行都深挖。已有精确执行不重走企业发现。
-
-需要提出或排序性能假设时读取 [references/experience.md](references/experience.md)，已读且仍适用则复用。调用 `$analyze-analysis-table-update-runtime` 取得对应候选运行和性能窗口的证据摘要；同一范围已有有效摘要时直接使用，只为新增缺口再次调用。更新记录分析负责版本化 Knowledge、身份与计数、逻辑/执行时间线、关联校验、lookup、查询计划、原始阶段测量和证据缺口；本场景不直接读取或复制这些规则。
-
-更新记录分析返回版本未知、范围不匹配、必要字段缺失、候选运行有歧义或关联边不成立时，保留限制并交回调查负责人。Experience、时间邻近或“最慢的一条”都不能补齐证据。缺口只影响依赖该知识或关联的判断；已由本次精确证据绑定的 engine task/Metric 仍可独立分析，但其结果不能反向证明缺失的更新关联。
-
-## 完成性能判断
-
-1. 由调查负责人或用户证据确认本次所选运行，并固定目标指标、统计总体和比较窗口。
-2. 比较 baseline、分位数或对照运行；没有可比样本时明确只做单次运行剖析。
-3. 使用更新记录分析返回的原始阶段测量计算耗时与占比，区分已测量耗时、边界估算和缺失区间。
-4. 对队列、依赖、合并、锁/容量、业务执行、load、engine 和 listener 阶段排序，只把证据支持且足以解释目标差异的阶段列为瓶颈。
-5. engine 阶段显著或出现 OOM、timeout 等资源失败时，区分当前只确认了失败模式、已经解释到物理执行机制，还是已连接到具体计算和本次触发条件：
-   - 同 task 已有明确未提交证据（如 `not submitted, skip finish`）时，返回提交前失败条件与证据，不因预生成的 task ID 或 Metric 链接建议获取该任务的计算统计；以下深挖要求不适用于该尝试；
-   - 只有通用错误、慢 span 或 engine 阶段名称时，不能在这里结束原因诊断；
-   - 已有明确 engine task ID、Metric 链接，或能在精确 trace 时间窗内取得 task ID 时，直接调用 `$analyze-engine-metric`，继续核对计算语义、物理热点、数据条件和资源边界；取证门槛和跳过条件见 `$diagnose-performance` 的“失败分析的完成条件”；
-   - Metric 无法取得时，保留已确认的 engine 事实、尚未解释的部分和下一项最小材料，不用算子经验补齐缺口。
-   Metric 只解释进入 engine 后的执行事实；此前的排队、依赖和选择过程需由相应记录证明。
-6. 行数、内存、超时或其他保护限制只作为直接触发条件。继续利用 trace、更新步骤语义和 Metric 中的 Operator 输入输出关系，解释哪项计算、哪些输入规模或哪段放大过程使本次执行达到边界；只有最终总量而没有形成过程时，向调查负责人说明缺口，不用“数据量大”代替原因。
-7. 为性能根因假设同时记录支持证据、反证和替代解释。单次运行依赖本次时间线与数据条件形成判断，不强制正常基线；解释回归或相对变化时才要求可比对照。资源超限只证明失败边界，不能自动证明端到端业务根因。
-8. 确认下游查询或其他场景是否消费了本次更新结果。发现 dataset/component/dashboard 线索时交回调查负责人协调，不直接调用另一个场景专项；没有 table、版本、运行 ID 和时间关联时，只报告相关信号，不确认因果。
-
-## 返回调查结果
-
-只向 `$diagnose-performance` 返回：
-
-- 已确认的 selected run、性能目标、baseline/分位数与比较窗口；
-- 对应的完整 traceId、task/chain ID 和环境/时间/资源范围；
-- 阶段耗时、占比、瓶颈排序及其测量边界；
-- 性能根因假设、支持证据、反证、本次输入规模与放大过程、直接失败边界和当前结论层级；
-- 下游影响、关联场景、engine Metric 分析结果和优化优先级；
-- analyzer 报告的 coverage、missing evidence 与下一项最小动作。
-
-本场景沿用当前调查上下文，将结果交回调查负责人。更新记录和 engine Metric 的阶段性证据按各自范围说明，不扩写为完整产品根因。

package/content/.agents/skills/diagnose-update-performance/agents/openai.yaml

@@ -1,7 +0,0 @@
-interface:
-  display_name: "更新性能排查"
-  short_description: "在性能总控下比较更新运行并定位性能瓶颈"
-  default_prompt: "作为 $diagnose-performance 交来的更新场景，使用 $diagnose-update-performance 基于更新运行证据定位瓶颈并返回 $diagnose-performance。"
-
-policy:
-  allow_implicit_invocation: false

package/content/.agents/skills/diagnose-update-performance/references/experience.md

@@ -1,47 +0,0 @@
-# 更新性能排查经验
-
-按更新阶段提出假设，并用本次运行记录验证。
-
-本文件只保留业务现象对应的候选与验证方向，取证和结束条件按[统一取证门槛](../../diagnose-performance/SKILL.md#失败分析的完成条件)执行。解释引擎耗时、内存或数据放大时，按需查[常见引擎性能问题](../../../../knowledge/engine/performance-patterns.md)，不在经验中另设读取 Metric 的条件。
-
-## 运行长时间没有进入计算
-
-候选假设：
-
-- 运行在排队；
-- 等待上游依赖；
-- 调度或资源分配未完成。
-
-验证：
-
-- 确认运行创建时间和状态变化；
-- 找到依赖或队列证据；
-- 用调度与依赖记录解释进入计算之前的等待。
-
-## 单个节点占据主要时间
-
-候选假设：
-
-- 节点 Query 本身计算重；
-- 节点等待输入或写入；
-- 错误重试放大总耗时。
-
-验证：
-
-- 建立节点时间线；
-- 区分计算、等待、写入和重试；
-- 核对与当前节点明确关联的引擎执行，按统一取证门槛完成分析。
-
-## 前台查询慢与更新相关
-
-候选假设：
-
-- 查询读取旧产物或遇到 updating 状态；
-- 更新失败导致下游不可用；
-- 两者只是时间上接近但没有因果关系。
-
-验证：
-
-- 对齐 table、版本、运行 ID 和时间窗；
-- 找到下游读取状态或资源版本证据；
-- 没有实例关联时不要确认因果。

package/content/.agents/skills/setup-signoz-mcp/SKILL.md

@@ -1,30 +0,0 @@
----
-name: setup-signoz-mcp
-description: 当用户需要安装、配置或恢复 SigNoZ MCP，或者诊断需要实时 SigNoZ 证据但当前客户端没有工具、无法启动、环境不明确、鉴权失败或只读查询不可用时使用。负责自动完成适配当前平台的 MCP Server 安装和当前客户端配置，通常只需用户提供目标环境的 API Key；完成后返回原诊断任务，不分析具体业务问题。
----
-
-# 配置 SigNoZ MCP
-
-为当前 Agent 客户端配置 SigNoZ 只读访问。正常首次配置只向用户请求缺少的 API Key；安装模式、发行包、MCP 名称和配置格式由助手按当前环境确定。
-
-## 默认流程
-
-未指定环境时使用环境知识中的默认 work；无需让用户先选择环境。默认连接不可用时修复该连接，不自动使用测试环境。已有调查范围和显式环境优先，未知名称或冲突仍需消歧。
-
-1. 检查当前客户端是否已经存在可用的 SigNoZ MCP，并从用户输入、现有配置或 [环境知识](../../../knowledge/common/signoz-environments.md) 确认目标环境。按环境知识的 URL、别名和后端服务映射固定目标，MCP 名称作为推荐连接名称；不根据可用工具顺序或 `service.environment` 猜测目标实例。团队口头表达中的 `work` 按正式环境处理；`prod` 不作为全局正式环境别名。URL 与口头环境冲突时只让用户确认“测试环境”或“正式环境”，确认前不写配置。
-2. 工具已经可用时跳过安装和配置。现有连接只要能按环境知识确认目标 URL，即可按当前客户端的工具声明继续使用；推荐名称不同不触发重配。完成最小只读验证后返回原任务，本轮已有成功查询则直接复用。
-3. MCP Server 缺失或损坏时，简短告知用户当前尚未安装，然后读取 [安装执行参考](references/installation.md) 并默认安装适配当前系统和 CPU 的产物。不要要求用户确认版本、下载源、安装目录或 command 路径。
-4. 安装完成后，如果当前客户端尚无目标环境的有效凭据，只请求一次 API Key。环境能够唯一确定时同时说明环境，不再询问 URL 或 MCP 名称。
-5. 用户提供 API Key 后，直接按当前客户端支持的本机方式完成配置；这已经表示用户同意本次目标环境的配置写入，不再追加配置确认。保留其他 MCP 和无关字段。
-6. 重载并执行最小只读验证。客户端必须由用户 Trust、启用或重启时，只提示这一项无法自动完成的动作；完成后继续验证。
-7. 配置成功后立即返回调用方并继续原诊断，不把安装过程变成独立任务。
-
-只配置当前正在运行的 Agent 客户端；不要因为发现 Cursor、Codex、WorkBuddy 等其他客户端的配置文件而切换配置目标。只有环境无法唯一确定、平台不受支持、已有同名配置冲突或客户端配置方式确实无法判断时，才请求相应的最小补充信息。
-
-## 交互与结果
-
-- 正常成功路径只说明 MCP 已准备好并继续原任务；不主动展示 checksum、压缩包、安装目录、完整配置或排障过程。
-- 安装后等待 Key 时，直接说明“当前没有可用的 SigNoZ MCP，已经完成安装，请提供 `<环境>` 的 API Key 以继续配置和诊断”。
-- 不回显用户提供的 API Key，也不把它写入仓库、Knowledge、Skill、fixture 或报告；只写入当前客户端支持的本机配置。
-- 失败时说明准确阻断和下一项最小动作，不用重装掩盖环境、凭据、权限或网络问题。
-- 本 Skill 只恢复 SigNoZ 访问能力，不判断业务根因；完成后由 `$diagnose-performance` 或原调用方继续。

package/content/.agents/skills/setup-signoz-mcp/agents/openai.yaml

@@ -1,7 +0,0 @@
-interface:
-  display_name: "安装与配置 SigNoZ MCP"
-  short_description: "安装、配置并恢复 SigNoZ MCP 的只读访问"
-  default_prompt: "使用 $setup-signoz-mcp 为当前客户端安装或恢复 SigNoZ MCP，并完成目标环境的最小只读验证。"
-
-policy:
-  allow_implicit_invocation: true

package/content/.agents/skills/setup-signoz-mcp/references/installation.md

@@ -1,75 +0,0 @@
-# SigNoZ MCP 安装执行参考
-
-仅在 MCP Server 或客户端配置缺失、损坏时读取。安装程序不接收 SigNoZ URL、API Key，也不修改客户端配置。
-
-## 安装 MCP Server
-
-macOS 和 Linux 优先执行 Skill 内的 Python 脚本：
-
-```bash
-python3 scripts/install_signoz_mcp.py
-```
-
-如果当前工作目录不是 Skill 目录，使用该脚本的绝对路径。仅在需要改变默认用户级安装目录时传入：
-
-```bash
-python3 scripts/install_signoz_mcp.py --install-dir <absolute-directory>
-```
-
-Windows 使用系统自带 PowerShell，不依赖 Python：
-
-```powershell
-powershell.exe -File scripts\install_signoz_mcp.ps1
-```
-
-只有需要改变默认用户级安装目录时才传入 `-InstallDir <absolute-directory>`。如果当前工作目录不是 Skill 目录，两种命令都使用脚本绝对路径。
-
-脚本会自动：
-
-1. 识别 macOS、Linux 或 Windows 及 CPU 架构；
-2. 从组织 OSS 下载固定的 checksum 清单和对应压缩包；
-3. 校验 SHA-256 后安全解压；
-4. 返回供客户端配置使用的绝对 `command` 路径。
-
-支持 macOS/Linux 的 amd64、arm64，以及 Windows amd64。Windows 使用组织构建，来源和边界见 [Windows 构建说明](windows-artifact.md)。不受支持的平台应明确停止，不要改用名称相近的产物。
-
-脚本执行不可用时，可以使用系统原生工具完成同等步骤，但仍必须同时满足：只访问 `https://signoz-mcp.oss-cn-beijing.aliyuncs.com/`、先读取 `signoz-mcp-server_0.10.0_checksums.txt`、精确匹配当前平台文件名、SHA-256 一致后才解压。不要跳过校验，也不要把二进制或 checksum 复制进本仓库。
-
-## 接入当前客户端
-
-安装完成后自动接入当前正在运行的 Agent 客户端。先检查该客户端公开支持的 MCP 管理命令、界面或用户级配置，不因为本机存在其他客户端的配置文件而切换目标。最小配置语义是：
-
-```text
-server name     -> 目标环境对应的稳定名称
-command         -> 安装脚本返回的绝对路径
-SIGNOZ_URL      -> 已确认的 SigNoZ 地址
-SIGNOZ_API_KEY  -> 使用者提供的该环境凭据
-```
-
-执行时遵守：
-
-1. 环境和稳定 MCP 名称能够根据输入或共享知识唯一确定时直接使用，不让用户再次确认。
-2. 缺少有效凭据时只请求 API Key；用户提供后直接完成本次目标环境配置，不再追加配置预览或确认。
-3. 使用客户端支持的本机持久方式保存 Key，不回显、不写入仓库、项目配置、Skill、Knowledge、fixture 或报告。
-4. 测试和正式环境分别配置，不复用或覆盖凭据。
-   未指定环境时按共享环境知识使用 work；默认连接缺凭据时只请求该环境 Key，不改用已经可用的其他环境。
-5. 增量修改已有配置，保留无关 server 和字段。
-6. 客户端支持工具 allowlist 时只启用诊断需要的只读工具。
-
-环境名称和 URL 读取 [共享环境知识](../../../../knowledge/common/signoz-environments.md)，不要在此复制。
-
-## 重载与恢复
-
-配置完成后按客户端支持的方式重载；无法自动完成 Trust、启用或重启时，只把这一项动作交给用户。随后依次验证：客户端发现 server、command 可以启动、最小只读请求成功、精确 ID 能在目标环境查询。成功后直接返回原调用任务，不向用户展开安装和配置明细。
-
-根据失败层恢复：
-
-| 现象 | 优先检查 |
-|---|---|
-| 客户端看不到工具 | 配置是否加载、server 是否启用、是否需要重载 |
-| server 启动失败 | command、文件存在性、平台架构、执行权限 |
-| 鉴权失败 | URL 与凭据是否属于同一环境、Key 是否失效或权限不足 |
-| 查询不到目标数据 | 精确 ID、时间与环境是否正确 |
-| 网络失败 | DNS、代理、OSS 或 SigNoZ 服务状态 |
-
-只重做失败层及其后续验证，不重复已经通过的步骤。

package/content/.agents/skills/setup-signoz-mcp/references/windows-artifact.md

@@ -1,14 +0,0 @@
-# Windows 构建说明
-
-Windows amd64 压缩包由组织维护并托管于 `signoz-mcp.oss-cn-beijing.aliyuncs.com`，用于补足当前上游发行版没有 Windows 原生产物的情况。
-
-- 文件名：`signoz-mcp-server_windows_amd64.zip`
-- 内容：`signoz-mcp-server.exe`
-- 上游：[SigNoZ MCP Server](https://github.com/SigNoz/signoz-mcp-server)，Apache-2.0 License
-- 构建：Go Windows amd64、`CGO_ENABLED=0`，内嵌版本为 `v0.0.6-0.20260224044326-53d3bdfb5af6+dirty`
-- 发布性质：组织构建，不是上游官方 v0.10.0 Windows Release
-- 签名：当前 PE 文件没有数字签名，不应通过关闭系统安全策略绕过拦截
-- 校验：安装时以同一 OSS 上的 `signoz-mcp-server_0.10.0_checksums.txt` 为准
-- 验证范围：来源、架构和 hash；真实 Windows 客户端启动与最小只读查询尚未验证
-
-本说明记录产物来源和使用限制，仓库不保存二进制或 checksum 副本。Windows 产物来源、构建方式或发布责任变化时，先更新并审核本说明，再调整安装入口。

package/content/docs/npm-cli.md

@@ -1,202 +0,0 @@
-# FX 数据诊断交付方案
-
-本文记录目标交付方案的选型、设计与使用方式，不改变 Core AI 的诊断方法。
-
-## 1. 背景与目标
-
-Core AI 已有性能排查、更新链路分析和引擎 Metric 解析等能力。直接使用源码仓库时，用户需要获取和同步 Git 仓库，再让 Agent 读取其中的规则、Skill 和知识，使用门槛较高。
-
-本方案补齐统一的交付与版本更新方式：开发者在一个仓库中维护和发布；同一份能力包供 WorkBuddy、Codex、Pi 等 Agent 使用，覆盖 Windows、macOS。用户通过一句话完成安装与启用，后续用自然语言诊断、更新或卸载，无需了解仓库结构或配置运行环境。
-
-## 2. 候选方案与选型决策
-
-| 方案 | 用户如何获取与更新 | 优势 | 主要代价 | 选型决策 |
-|---|---|---|---|---|
-| 直接使用 Git 仓库 | 克隆仓库、拉取更新、设置入口 | 开发与调试直接 | 用户需要操作 Git 和目录，环境与版本管理分散 | 不作为用户交付方式，仅供开发维护 |
-| 各 Agent 原生插件 | 从各 Agent 的插件入口安装、更新 | 安装和权限管理集成在 Agent 内 | 需要适配不同 Agent 的插件格式、分别打包发布；难以统一交付与维护，通用性不足、维护成本高 | 不采用 |
-| **npm 包 + CLI + 薄 Skill** | 一句话让 Agent 安装并登记 Skill，通过 CLI 更新 | **多个 Agent 统一复用同一套 CLI、Skill 和诊断内容，一套包与发布流程即可交付** | 安装流程需处理运行环境和各 Agent 的 Skill 登记位置 | **采用** |
-| 独立部署服务 | 访问统一服务，服务端集中更新 | 用户无需本地安装，入口统一 | 需要额外建设模型调用、身份认证、会话及服务运维，投入较大 | 不采用，超出本次交付优化范围 |
-
-选择 npm 方案，是因为目标 Agent 已具备执行 CLI、读取 Skill 的能力，可以直接使用同一份能力包。CLI 提供命令调用入口，Skill 提供使用说明；客户端差异集中由安装登记处理，无需分别维护插件包。
-
-## 3. 方案设计
-
-### 3.1 总览
-
-在现有诊断内容之上，补齐构建打包、发布分发、版本管理、安装与按需加载四项交付能力。开发者维护一个仓库，多个 Agent 使用同一份能力包，诊断过程继续由用户当前的 Agent 执行。
-
-CLI 负责安装、版本管理和脚本入口；薄 Skill 引导 Agent 按需读取诊断规则与知识；Agent 负责推理、调用工具和组织回答；SigNoZ MCP 负责线上查询。能力包不单独运行模型。
-
-各层名称如下：
-
-| 层次 | 设计名称 | 职责 |
-|---|---|---|
-| 开发仓库 | `core-ai` | 维护诊断规则、知识、脚本与交付工具 |
-| npm 分发包 | `@fx-data/ai-diagnostics` | `fx-data` 为组织，`ai-diagnostics` 为诊断能力包 |
-| CLI 与薄 Skill 标识 | `fx-data-diagnostics` | 执行命令、登记 Skill、定位诊断内容 |
-| 用户调用名称 | FX 数据诊断 | 中文介绍、Skill 标题和自然语言调用 |
-
-### 3.2 构建打包
-
-**构建阶段统一在 Docker 中完成检查、测试和打包，并固定 Node.js、npm、Python 的版本。** 这样可以减少开发机环境差异，并让后续 CI 直接复用。用户安装和使用能力包无需 Docker。
-
-交付代码集中在 `packages/ai-diagnostics/`，诊断 Skill、知识和解析脚本仍在原目录维护，由构建流程收集入包：
-
-```text
-packages/ai-diagnostics/
-├── src/core-ai.mjs          CLI 运行代码，保持单文件
-├── templates/              包清单、用户 README 与 Agent 安装说明模板
-├── scripts/build.mjs       检查、测试、组包与安装验证
-├── scripts/publish.mjs     上传既有产物并核验远端结果
-├── scripts/npm-publish.sh  编排 Docker 构建与发布
-├── scripts/release-support.mjs  共用的环境隔离与错误处理
-├── Dockerfile             固定构建和发布环境
-└── tests/                 交付模块测试
-```
-
-构建产物为一个 npm 包，包含 CLI、薄 Skill 生成逻辑和完整诊断内容：
-
-```text
-@fx-data/ai-diagnostics
-├── CLI 程序：安装、薄 Skill 登记、内容定位、版本管理、脚本调用
-├── README.md：面向用户的安装、使用、更新、卸载说明
-├── AGENT_SETUP.md：面向安装 Agent 的检测、登记与管理步骤
-└── 诊断内容
-    ├── AGENTS.md：诊断 Agent 的执行规则
-    ├── 各诊断 Skill
-    ├── 业务知识与参考资料
-    └── Python 解析脚本、MCP 配置指引与安装辅助脚本
-```
-
-### 3.3 发布分发
-
-**MVP 使用 npm 官方公共仓库。** 用户无需 npm 账号、公司内网或私有源配置即可下载，有利于快速安装和跨 Agent 使用。[公开包规则](https://docs.npmjs.com/about-public-packages/)
-
-线上查询由用户自己的 API Key 校验身份和数据权限。发布包仅包含确认可公开的工具、规则和知识，不包含凭据或真实业务材料；API Key 保护服务端访问，包内内容本身是公开的。
-
-公司内部 registry 作为有非公开内容或企业发布要求时的替代，沿用同一套包结构；下载权限与网络可达性由内部仓库配置决定。
-
-根目录的 `scripts/npm-publish.sh` 保留为统一发布入口，转交交付模块执行。构建阶段生成并验证包，发布阶段只接收已构建的产物，上传并核验下载结果；恢复发布时复用保存的版本和包，不重新构建。开发者提交代码后执行：
-
-```sh
-bash scripts/npm-publish.sh
-```
-
-```mermaid
-flowchart TD
-    A[执行 npm-publish.sh] --> B{恢复发布？}
-    B -->|否| C[导出提交源码，生成版本]
-    C --> D[Docker 构建：检查、测试、打包、安装验证]
-    D --> E[保存版本、npm 包与发布实现]
-    E --> F{仅构建 dry-run？}
-    F -->|是| G[结束，产物留待发布]
-    B -->|resume| H[读取已保存的版本与产物]
-    F -->|否| I
-    H --> I
-    subgraph Publish[Docker 发布：此时才注入 NPM_TOKEN]
-        I[查询远端，必要时上传 npm 官方仓库] --> J[下载并核验包，记录发布结果]
-    end
-```
-
-先手动执行脚本，后续由 CI 在代码合并后调用同一入口。本地与 CI 均支持环境变量 `NPM_TOKEN`，本地也可选用已保存的 Token；除仅构建模式外，缺失凭据会在构建前提示。Token 只注入发布容器，不写入代码、镜像或安装包。维护者操作及环境要求见 [发布 npm 包](../README.md#发布-npm-包)。
-
-### 3.4 版本管理
-
-**CLI、Skill、知识和脚本共用一个版本，按发包时间自动生成版本号。** 整包发布、整包更新，保证诊断内容与工具配套；用户默认安装或更新到最新版。
-
-同一系统账户下，各 Agent 共用一份安装和当前版本。CLI 管理各版本副本，通过固定入口执行更新与回退。新版下载并校验成功后切换，失败保留原可用版本，旧版保留供回退。更新或回退后，各 Agent 的新调查统一使用切换后的版本，进行中的调查保持原版本，避免中途改变诊断规则或脚本。
-
-CLI 记录更新前的版本，用户要求回退时，Agent 根据记录确定目标版本，无需用户记忆版本号；也支持用户明确指定版本。
-
-默认由用户发起更新。用户开启自动更新后，Agent 负责设置定时任务，客户端或系统负责按时调度，CLI 执行更新；手动与自动更新使用同一个入口。取消任务后仍可手动更新。诊断材料独立保存，更新不影响材料，也不替换独立安装的 MCP 及其配置。
-
-### 3.5 安装与加载
-
-**先检测已有安装，再决定是否下载。** Agent 按固定共享目录或已有薄 Skill 中的入口定位能力包，复用已有运行环境与当前版本，只为当前客户端补充薄 Skill；不因更换 Agent 或 npm 全局目录不同而重复安装，也不改写其他客户端的健康入口。
-
-尚未安装时，Agent 以 npm 包声明的运行环境要求为准，优先复用已有 Node/npm，不满足时自动补齐，然后执行：
-
-```sh
-npm install -g @fx-data/ai-diagnostics
-```
-
-npm 安装取得 CLI 和完整诊断内容；随后 Agent 只需调用一次 `install --agent <当前客户端>`，由 CLI 完成受管副本初始化、薄 Skill 登记、完整性与内容路径检查，并返回版本、复用结果、后续诊断入口和阶段耗时。已有 npm 包也可直接用于初始化，无需重新下载；成功后不再单独执行 `doctor`、`context` 或预读诊断规则，Python 与 MCP 留到实际诊断需要时再准备。
-
-客户端技能目录由 CLI 识别，兼顾 WorkBuddy 的不同目录布局，避免 Agent 临场研究客户端文件。检查结果区分文件登记和客户端发现；尚未验证发现时只提示刷新或新开聊天，不将文件存在当作已启用。
-
-包内 README 只保留用户说明和 Agent 文档入口；具体检测顺序和执行命令统一维护在随包发布的 `AGENT_SETUP.md`，成功路径与异常处理分开。该文档可在安装前通过版本固定的在线链接读取，也可从对应 npm 包取得。整个过程由 Agent 连续完成，用户在首次安装或切换客户端时都只需说同一句话。
-
-对外配置变量统一使用 `FX_DATA_DIAGNOSTICS_*`。安装完成后默认给出针对具体 trace 的内存超限排查示例，提示附上真实 traceId 或链接；不自动运行示例查询。
-
-每个客户端只登记一个薄 Skill，完整诊断 Skills 和知识留在共享能力包内。安装复用不会隐式更新版本；内容损坏或安装冲突应明确处理，不通过另装一份来绕过。
-
-安装、更新、回退、卸载和检查直接使用 CLI 管理命令，不加载诊断规则。用户明确要求用 FX 数据诊断分析问题，或在客户端中选中该 Skill 并描述问题后，Agent 按以下链路执行：
-
-```text
-读取薄 Skill
-  → 调用 CLI context 获取版本与内容路径
-  → 读取 AGENTS.md 和当前问题所需的 Skill、知识
-  → 调用 SigNoZ MCP 查询，或调用包内脚本解析材料
-  → 分析证据并回答
-```
-
-`context` 返回路径，不直接加载全部内容。普通对话只保留简短入口描述，进入诊断后再按需读取，减少上下文占用。薄 Skill 在用户明确要求用 FX 数据诊断分析问题，或安装、更新、回退、卸载、检查 FX 数据诊断时触发，不以“慢”“trace”等通用词默认触发；具体技能选择入口由各客户端提供。[Skill 渐进加载](https://agentskills.io/specification#progressive-disclosure)
-
-Agent 优先分析已有材料，必要时查询；按需准备 Python、复用或配置 MCP，凭据仅保存在用户本机。具体执行约定见包内 [AGENTS.md](../AGENTS.md#安装副本的助手规则)。
-
-卸载针对同一系统账户下的整套能力包。Agent 说明会一起移除已登记客户端的入口、已安装版本和 npm 包，进行中的诊断也将无法继续调用包内脚本；随后只调用一次 `uninstall`。CLI 按首次安装记录的原 npm 环境清理全局包，再移除受管副本和薄 Skill，并返回完整卸载状态及实际清理结果。npm 清理失败时保留受管入口供重试；安装未记录可用 npm 来源时，Agent 仅按返回指引补充处理，不猜测其他安装位置。用户提供的日志、Metric 文件和生成报告，以及独立安装的 MCP 和配置会保留；包内规则与知识随包删除，无需扫描或备份其他目录。
-
-## 4. 用户安装、使用与更新
-
-### 4.1 首次配置
-
-向 WorkBuddy、Codex 或 Pi 发送一句话，等待 Agent 返回安装结果；如需授权，按客户端提示完成：
-
-> 帮我安装并启用 FX 数据诊断，npm 包是 `@fx-data/ai-diagnostics`。
-
-首次需要查询线上数据且尚未配置连接时，按 Agent 提示提供目标环境的 API Key，并完成必要授权。分析已有材料无需配置线上连接。
-
-Agent 自动判断首次安装或复用已有安装，用户无需指定安装目录或告诉它其他客户端是否装过。环境准备、按需下载和薄 Skill 登记机制见[安装与加载](#35-安装与加载)。
-
-### 4.2 日常使用
-
-直接说“用 FX 数据诊断……”并描述问题，附上已有的标识、链接或文件即可。例如：
-
-| 想了解的问题 | 使用示例 |
-|---|---|
-| 指定执行 | “用 FX 数据诊断分析这条 trace 为什么内存超限。”附上 traceId 或链接。 |
-| 指定更新链路 | “用 FX 数据诊断分析这次更新为什么慢。”附上实际 dagId。 |
-| 引擎耗时与内存 | “用 FX 数据诊断看看这份 Metric 的耗时和内存。”附上文件。 |
-| 租户更新概况 | 明确需要整体概况时，提供实际 corpId 和时间范围，询问这段时间的更新情况。 |
-
-也可以在当前 Agent 的技能列表中选择 `fx-data-diagnostics`（FX 数据诊断），再直接描述问题。无需选择包内的专项 Skill。
-
-诊断内容的加载机制见[安装与加载](#35-安装与加载)。
-
-### 4.3 版本管理
-
-需要新版时说：
-
-> 更新 FX 数据诊断。
-
-希望每天自动更新时说：
-
-> 帮我设置一个每天上午 9 点（北京时间）检查并更新 FX 数据诊断到最新版的任务，更新失败时通知我。
-
-停止自动更新时说：
-
-> 取消 FX 数据诊断的自动更新任务。
-
-需要回退时说：
-
-> 把 FX 数据诊断回退到这次更新前的版本。
-
-也可以明确指定要回退的版本号。
-
-更新、回退和定时调度机制见[版本管理](#34-版本管理)。
-
-### 4.4 卸载
-
-> 卸载 FX 数据诊断。
-
-Agent 会说明影响并返回卸载结果；完整卸载会移除本账户各客户端中的 FX 数据诊断入口、已安装版本（含规则和知识）和 npm 包。用户提供的日志、Metric 文件和生成报告，以及独立安装的 MCP 和配置会保留，卸载机制见[安装与加载](#35-安装与加载)。

package/content/docs/roadmap.md

@@ -1,44 +0,0 @@
-# 指南完善方向
-
-使用者应能在没有产品代码环境的情况下，根据实际材料定位问题、复核判断并完成必要交接。各类问题都需要实际案例验证，章节齐全或辅助工具检查通过不能替代这项验证。
-
-## 当前覆盖
-
-| 范围 | 状态 |
-|---|---|
-| 分析表、组件、仪表板、更新的性能问题（慢、超时、内存超限、回归） | 有专项流程，支持从现象、对象链接、执行记录、日志或引擎统计开始 |
-| 引擎统计解读（耗时、内存、数据规模、执行阶段） | 有统一解析入口和语义知识 |
-| 更新来源、链路、节点、重试与计数解释 | 有专用证据分析能力 |
-| 企业最近更新概况、dagId 链路查询 | 支持无时间直接开始 |
-| 历史变化对比 | 自动查找目标执行之前的可比基线 |
-| 仪表板组件异常对照 | 优先核对单独计算，未找到仍分析异常；按[场景流程](../.agents/skills/diagnose-dashboard-performance/SKILL.md#组件取数先做对照)处理 |
-| 报错、结果异常、偶发不可用 | 仅通用方法，没有专项经验 |
-
-每条规则只有一个归属文件，统一登记在[文档目录](index.md)。各 Skill 保留触发条件和引用，经验用于提出业务假设，不另设取证门槛。
-
-正式方向见 [FX 数据诊断交付方案](npm-cli.md)：统一 npm 包与薄 Skill，优先采用公共 npm 分发，默认手动更新、自动更新由用户选择。当前实现已通过隔离安装生命周期测试及 Docker 构建演练；新版在真实客户端（包括 WorkBuddy）中的安装与使用、Windows 真机、空白环境初始化和公开发布仍待验收。早期 beta 的 macOS WorkBuddy 验证不代表当前实现已验收；CI 尚未接入。
-
-## 优先补齐什么
-
-1. 非性能问题的排查经验：普通报错、结果异常和偶发问题先按[反馈流程](diagnostic-feedback.md#非性能案例怎样保留)积累实际案例，将核实过的判断方法补入通用方法；有足够案例支持时再考虑专项。
-2. 用词是否易懂：首次出现的技术词是否有必要，能否改成操作、对象和可看到的记录；保留日志原名时说明它代表什么。
-3. 方法是否可执行：每一步是否能从页面、日志、执行详情或受控导出取得材料，是否说明查什么、为什么查、查到后怎样判断。
-4. 材料不足时能否继续：只有截图、失败日志或不完整记录时，是否先利用已有信息，并只补充影响判断的最小材料。
-5. 结论是否可复核、交接是否有效：能否定位对应操作，区分已确认事实和待验证原因；未解决的问题能否整理成研发可以继续验证的具体判断。
-6. 调查是否高效：减少重复读取、重复查询、不必要的用户确认和专项往返；按需读取知识，材料足够即交付。
-
-## 怎样反馈指南中的问题
-
-诊断交付时，助手按[需求反馈](diagnostic-feedback.md)整理本轮发现的未覆盖场景、知识缺口、本项目优化项和文档差异，在当前对话给出可转交的草案。反馈不触发额外查询或自动修订。
-
-使用脱敏材料说明：客户现象、已取得的信息、按照指南走到了哪一步、实际记录与描述哪里不一致。不要提交密码、令牌、完整业务数据或原始大日志。
-
-对新案例先保留事实、推测和限制，再判断是否适合纳入指南。单次相似现象不足以形成通用原因；经过多个案例复核的经验，才用于调整排查顺序。
-
-## 怎样验证改动
-
-收到改进请求后，用反馈中的案例和相近反例检查改动：知识是否补足了判断依据，证据不足时是否说明限制，已有场景是否受影响。改进效果以修改后的实际回答为准。
-
-用代表性情况检查：明确慢、明确失败、只有资源链接、只有失败样本、多个候选无法区分，以及缺少关键关联。非性能问题还应包含普通报错、预期与实际结果不同、偶发后恢复的情况。逐项核对助手能否依据材料继续判断。
-
-离线检查（`scripts/validate.py`）只验证结构、链接和脚本处理；Agent 行为需要另外用实际案例验收。