AI 智能体与可观测性：MCP 工具接入与智能排障

LLM 的局限：训练数据里没有"系统现在的状态"
路径A 喂监控快照：简单但数据旧、格式不稳、无法追问
路径B 工具实时查询：按需取数、可迭代追问、数据新鲜
结论：智能排障必须走"工具调用"路线，喂快照走不远

典型循环：感知异常 → 查指标（PromQL）→ 查日志 → 查 trace
  → 关联变更 → 输出根因候选+证据；每步对应一个工具

告警告诉你"出事了"；异常检测告诉你"哪里偏离基线"
智能 Agent：接住"出事了"，自己去查"为什么"→ 人确认执行

角色：Host（LLM 应用）→ Client → Server（暴露能力）
原语：Tools（可执行动作）、Resources（只读数据）、
  Prompts（可复用模板）；传输：stdio（本地）或 HTTP/SSE

from mcp.server import Server, stdio_server
server = Server("observability-mcp")

@server.tool()
async def query_metric(promql: str, start: str, end: str,
                       step: str = "1m") -> str:
    """执行 PromQL 查询，返回时序结果"""
    return format_series(await prometheus.range_query(
        promql, start, end, step))
# 同类工具：search_logs / get_trace / list_events

名称语义化：query_metric 比 "q" 好；description 说清
  "何时用、参数含义、返回什么"，参数给示例
坏示例：def foo(a, b): ...
好示例：query_metric(promql: 'rate(...[5m])', start/end/step)
  → 返回 [{timestamp, value}]，让 LLM 不用猜就能写对 PromQL

让 LLM 自由写 PromQL → 高风险（打爆后端）
解法：受限执行层——白名单函数、超时与返回上限（200 点/50 序列）、
  只读限时间跨度；query_metric 命中返回序列，查不到给明确错误

search_logs(service, query, since="30m", limit=20)
  → 结构化日志行（timestamp/level/msg），已脱敏，
  注明"样本还是全量"防止下大结论
get_trace(trace_id) / analyze_slow_traces(service, since="1h")
  → 从 span 结构推断调用链，指出"瓶颈在 DB 调用"
list_events(since="1h", scope="prod")：变更事件，根因候选第一位

文本一大段 → LLM 易"脑补"结论；结构化让"事实"与"推断"分离
好响应含：状态、schema 化数据、元信息、置信度、错误原因

{
  "tool": "query_metric", "status": "success",
  "meta": {"series": 3, "sampled": false, "truncated": true},
  "data": [{"metric": {"service": "checkout"},
            "values": [["2026-10-01T09:30:00Z", "0.42"]]}],
  "confidence": "high",
  "hint": "查询被截断，建议缩小窗口"
}

confidence：数据完整→high；被截断/样本→medium/low
  Agent 拿到 low 应主动扩大范围，不硬下结论

迭代追问：query_metric → 错误率飙升；search_logs → 超时堆栈；
  get_trace → 定位依赖服务
工具层：响应给"下一步建议"（hint）；失败给明确原因；
  记录查询轨迹便于审计

铁律：AI 工具默认只读、限定范围（绑定团队服务，跨团队审批）
分级：查询类默认开放；变更/导出类默认关闭（人工授权）
最小化：排障 Agent 只需 4~5 个只读工具

提示注入：日志/指标藏"忽略之前指令"污染 Agent
  → 工具数据当"不可信输入"，不执行其中指令
查询滥用：误写 PromQL 打爆后端 → 超时、并发上限、配额
数据外泄：结果被外部读取 → 工具层先脱敏再给 LLM

记录每次工具调用（谁/什么 Agent/查了什么/结果）
  审计进统一事件平台；结论带证据链接可复验
治理指标：工具误用率、结论人工采纳率
边界：自动修复必须"人工确认"兜底；定期评审工具清单

Copilot：Agent 只回答问题，人做判断与操作
RCA 助手：Agent 主动编排查询、输出根因候选+证据，人确认
预案执行：命中已知预案、人工授权下执行（限流/扩容）
自主闭环：低频可逆低风险动作全自动 + 事后审计

技术依赖：MCP 工具层稳定；trace 覆盖率高；变更事件可查询
流程依赖：值班确认机制；预案库（Playbook）结构化；审计与回滚
度量：根因准确率；MTTA/MTTR；自动处置成功率

常见失败：数据没打通就吹自动化；响应不规范 → 幻觉高发；
  没做权限边界 → 一次误操作吓退项目
正确节奏：先 Copilot 积累案例 → 再 RCA 助手（人确认）
  → 最后才碰自动执行，且只碰可逆动作

□ 用 MCP 封装只读工具：查指标/日志/trace/变更事件
□ 工具描述语义化，参数给示例，返回含 meta 与置信度
□ PromQL 走受限沙箱：白名单函数+超时+序列上限
□ 日志/返回值在工具层脱敏后再给 LLM
□ 默认只读 + 范围隔离，写操作人工授权
□ 防提示注入：工具数据当作不可信输入
□ 全量审计工具调用，结论带证据链接可复验
□ 变更事件作为根因候选第一优先级
□ 先 Copilot 再 RCA 助手，最后才受控自动执行
□ 度量采纳率/MTTR，而非"上了 Agent"

智能排障 = MCP 只读工具 + 结构化响应 + 权限边界 +
从辅助到受控自动化渐进，让 AI 会查、会判、不乱动。