# ISS-0063: Agent 未将 CPU% 指标归一化到实际 vCPU 配额

## Background

TCOC-5207 中，用户多次（多轮对话）纠正 agent：CPU 从 70% 上升到 100% 并非性能瓶颈，
因为该集群 TiDB 实例的实际 CPU 配额是 800%（即 8 vCPU × 100%）。Agent 将 100% CPU
读数直接当作"满载瓶颈"告警，忽视了云数据库中 CPU 百分比是按 vCPU 数量乘算的事实。

Workspace: ws-1778028682864-3efd1046a
Ticket: TCOC-5207
Reported via: GitHub issue #382

## Observed Behavior

- Agent 看到 CPU 指标显示 70%→100%，判断为 CPU 瓶颈
- 用户反复提示"实际限额是 800%"，Agent 仍多次回到 CPU 瓶颈结论
- 根本原因：Agent 不知道 TiDB Cloud 的 CPU% 指标含义是 total CPU time / (vCPU × 100%)
  - 一个 8 vCPU 实例：CPU 满载 = 800%，所以 100% 是 12.5% 负载
  - 一个 1 vCPU 实例：CPU 满载 = 100%，100% 才是满载

## Root Cause

`tidb-clinic-diagnosis` SKILL.md 中没有 CPU% 归一化指南。Agent 使用 Prometheus/Grafana
raw CPU 读数时，不知道需要结合集群规格（vCPU 数量）判断真实 CPU 负载率。

TiDB Cloud 的 CPU 指标通常有两种形态：
1. `process_cpu_seconds_total` 导出的 rate，单位是 core-seconds，100% = 1 core
2. `tidb_server_cpu_usage` 等 gauge，满值是 vCPU × 100%

Agent 需要区分这两种形态，并在 Jira/Clinic 中查询集群规格后归一化。

## Fix Plan

### Step 1: 在 SKILL.md Node C 增加 CPU% 解读规则

在分析 CPU 指标时，增加前置步骤：

```
CPU% 归一化检查（必须）：
1. 从集群规格获取 TiDB/TiKV vCPU 数量（Jira 附件/Clinic cluster_info）
2. 判断指标类型：
   - 若指标满值 = 100%（单核归一化）：实际负载 = CPU% / (vCPU × 100%)
   - 若指标满值 = vCPU × 100%：实际负载 = CPU% / (vCPU × 100%)
3. 仅当实际负载 > 80% 时才判为 CPU 瓶颈
4. 在诊断输出中注明：集群规格 N vCPU，CPU 满载阈值 = N×100%，
   当前 CPU = X%，实际负载率 = X/(N×100%)%
```

### Step 2: collect_evidence.py 增加集群规格采集

在 A0 段（基础信息）中获取 tidb/tikv 实例规格：

```python
# A0b: 获取集群规格 (instance CPU 配额)
# 从 Clinic cluster_info API 或 Jira 描述中提取 node_spec
# 输出到 evidence_summary 中供 Node C 使用
```

### Step 3: 增加已知误判模式

在 SKILL.md 增加"CPU 指标常见误判"：
- 100% CPU 读数在多核实例中可能只是轻度负载
- 必须结合 vCPU 数量、cluster size 综合判断
- 参考 TiDB Cloud 文档：CPU 使用率 = Σ(core CPU usage) / (vcpu_count × 100%)

## Verification

1. 针对 TCOC-5207 重跑诊断，检查 Agent 是否正确获取集群规格并归一化 CPU%
2. 检查 --check 是否在 CPU 瓶颈判断场景下要求输出 "vCPU count"