KubeSense Alerts 处理两类彼此独立的任务：读取告警与创建告警，二者不应混淆。
一、读取告警（纯 MCP 工具调用） · list-active-alerts：来自原生存储的当前触发序列，与规则元数据合并。支持按 from_time/to_time、fingerprint、acknowledged、assignee、include_resolved 过滤。 · list-alerts：外部 Alertmanager 状态，仅标签、无规则配置，属不同数据源；除非明确需要 Alertmanager 状态或静默，否则应使用 list-active-alerts。 · list-alert-rules：规则定义，包含被禁用与未触发的规则，最新的在前。过滤项：enabled、state、severity、query_type、search、created_by。 · get-alert-details：单条规则的完整配置（query_config、condition、threshold）及其触发实例，调查时从这里开始。 · get-alert-history：触发/恢复转换记录，最新在前，用于判断是长期问题还是新问题。 · find-investigation-for-alert：最近一次已完成的 AI 调查及其根因；found=false 属正常结果，不是错误。 · list-notification-channels：仅已启用的渠道，返回 id、name、type。
注意：“我创建了哪些告警？”需先调用 get-current-user，再以其 username 作为 created_by 传入；存储的创建者是用户名，用邮箱永远不会匹配。fingerprint 标识某规则的单个触发序列（某个命名空间/Pod/工作负载），传入可收窄 get-alert-details / get-alert-history 的范围，省略则针对整条规则。
关于触发状态：确认（Acknowledge）表示“我在处理”，序列仍留在 Firing Now，但通知被双重抑制——一个最长 7 天的 Alertmanager 静默，加上引擎侧在数据库标记存在时完全跳过发送的检查，该标记没有过期时间，因此不要声称通知会在一周后自行恢复。解决（Resolve）表示“已处理”，序列不再留在 Firing Now，仅本次触发被抑制；当序列不再越界时引擎会清除标记，之后再次真正越界仍会正常通知，它不是静音。此外，MCP 输出无法区分手动解决与真正恢复，二者都只是增加 ends_at 并退出 list-active-alerts，因此不能仅凭 include_resolved 断定“它在 14:02 恢复了”。
二、创建告警（两条路径） · create-alert MCP 工具：每次调用一条规则；fields/group_by_fields 会自动桥接（先试目录标签，再试存储名），where 则严格要求目录标签；创建前预校验并给出精确错误；由智能体应用（写工具，需批准）。适合用户当前想创建的单个规则。 · 导入 JSON：每次一条或多条（支持批量）；字段名必须严格使用引擎自身词汇；在导入时由服务端校验；由用户在 UI 中应用。适合需要审阅产物、多条规则或迁移的场景。
create-alert 的要点：signal 取值 metrics | logs | traces；metrics 需提供 promql，logs/traces 需 where（search-logs 语法）加 value_operation，非 row_count 时还需 fields。此处的 value_operation 比查询工具更窄，仅支持 row_count、unique_count、avg、sum、min、max，不含百分位，因此 p95 延迟规则需走导入 JSON。必填项：name、threshold_operator、threshold_value、notification_channels。默认值：severity=warning、threshold_frequency=at_least_once、evaluation_interval=1m、time_window=5m。threshold_operator 在此处还接受 above/below（导入 JSON 不接受），会归一化为 greater_than/less_than。
多查询与公式：比率类规则（错误率、占比）无需再走导入路径，可传 queries 而非扁平单查询字段，并给最后一项一个 expression。queries 与扁平字段（promql、where、value_operation、fields、group_by_fields）互斥。label 默认按位置为 A、B、C，仅字母，最多 26 个查询。公式项只含 expression，且只能引用其之前列出的查询。每条非公式查询都跑在规则的同一 signal 上，规则不能混用 logs 与 metrics。被分组的输入必须按相同字段分组，否则键无法匹配；create-alert 会拒绝并指出两处分组。未分组的输入不受此限制，这是有意设计，可实现“某工作负载占总量的比例”。阈值作用于公式；多个查询而无公式时，用 threshold_query 指定对哪个查询应用阈值。在 queries 内 where 传空字符串是被接受的。
注意：where 只接受目录标签，不接受存储列名（例如须用 status_code 而非 return_code；用 instance 而非 pod_name），被拒绝时会明确报出存储列名及应使用的目录标签。fields 与 group_by_fields 则是宽容的，两者皆可。该工具自身描述里的示例存在此 bug（在 where 中写了 return_code），不要照抄。
调用前必须先调用 list-notification-channels：notification_channels 为必填且必须是真实存在的渠道 id，不存在的 id 会导致规则创建失败；若无渠道，应告知用户需先在设置中创建，不能静默创建规则，否则它会触发却无人收到通知。该工具是写操作，调用前应明确说明将要创建什么。
三、校验手工组装或迁移的规则 JSON 凡自行组装规则文档（导入 JSON、移植的 Datadog monitor、编辑过的导出文件），交给用户前都应先经 validate-alert-json 校验。它不存储任何内容，一次性报告所有问题，每个 path 是指向待修复值的 JSON Pointer，重复直到 valid=true。它校验的是 wire 文档（含 query_config、threshold_operator、frequency_type 的导入/导出形态），不适用于 create-alert 的参数——后者自行校验输入并以相同 findings 拒绝。
四、字段命名的多套词汇表 告警引擎接受的字段集与查询工具不同，共有三套词汇：查询工具（analyze-logs、search-traces）仅用目录标签；告警的 group-by/value 字段是标签与存储名的混合，严格校验；告警过滤键则是 group-by 集合加上额外的存储名叠加。 · 日志的 group-by 与 value 字段共 19 个（精确）：instance、workload、namespace、cluster、pod、container、node、pod_name、container_name、level、format、host、body_length、region、app_version、customer_identifier、source、service、env_type。两种拼写均可用（pod/pod_name、container/container_name、node/host）。注意此处严重级别是 level，不是查询工具的 type。service 与 env_type 是较近期才被接受（KUBE-2638），更早的安装会拒绝它们。日志过滤键为上述 19 个加 env、node_name、body。body 只是过滤键，不是维度；按消息文本分组会产生每行一个序列，无法聚合，body_length 才是数值字段。body 过滤会强制走原始表，每次评估都是全表扫描；对 body 的裸 ILIKE 会被改写为分词搜索，因而 “false positives” 是索引固有现象，不是缺陷。pattern_id 不被接受，因为只存在于 rollup 上。 · 追踪的 group-by 与 value 字段共 40 个（精确）：28 个目录标签（status、protocol、source、role、status_code、namespace、method、workload、container、region、app_version、resource、server、client、server_namespace、client_namespace、node、operation_name、partner_cluster、customer_identifier、duration、duration_quantile、duration_avg、pod、instance、cluster、return_code、app_service），加上 12 个存储名（container_name、pod_name、node_name、kind、subtype、protocol_type、clustered_resource、perspective_namespace、perspective_workload、env_type、app_db、issue_reason）。因此对追踪而言，目录名与存储名在过滤键和 group-by 中均可用。追踪过滤键为上述 40 个加 is_external、app_name、partner_namespace、partner_workload。注意 service 不被追踪接受，须用 app_service；日志则相反，service 被接受，且日志中 node_name 仅可作过滤键，作维度时列名为 host。 · 标记 is_attribute: true 的字段完全跳过校验，空值、advanced_query、以 @ 开头的过滤键亦然。
五、错误字段名的后果 导入时规则会以 400 被拒绝，并给出逐字段信息。该防护的存在是因为引擎在评估时无法解析的名称会每次评估都报错，随后引擎会保持规则当前状态：新规则静默永不触发，已触发的规则冻结——永不恢复，改阈值也无效，因为查询在检查阈值前就已报错。导入时的允许列表是手工维护的引擎镜像，无自动漂移检测，因此一条能通过校验却从不触发的规则可能命中此问题，应在条件图上核实。
六、会静默改变规则的陷阱 · groupBy 条目缺少 field、type 或 is_attribute：整个 groupBy 被清空，规则作为单个全局序列触发，而非按标签分别触发。 · value_operation 为数值型（如 p95）但 fields 缺失或错误：静默降级为 row_count。
原始资料在此处截断，后续内容暂未提供。