# 步骤 1：查询服务列表
GET /api/v1/services?keyword=order
Response: [{"id": "svc-123", "name": "order-service", ...}]

# 步骤 2：查询指标定义
GET /api/v1/metrics?service=svc-123&category=cpu
Response: [{"id": "metric-456", "name": "cpu_usage_percent", ...}]

# 步骤 3：查询实际数据（需要计算时间戳）
GET /api/v1/metrics/metric-456/data?start=1710828000&end=1710831600&step=60
Response: {"timestamps": [...], "values": [...]}

# 步骤 4：自己计算平均值
avg_cpu = sum(values) / len(values)

# 步骤 5：组织回复
"订单服务过去一小时平均 CPU 使用率为 67.5%"

# 单次工具调用
tool: query_service_health
parameters: {
  "service_name": "order-service",  # 支持模糊匹配
  "time_range": "1h",               # 语义化时间
  "metrics": ["cpu"]                # 指定关注的指标
}

# 返回结果（已聚合、分析、包含建议）
{
  "service": "order-service",
  "health_score": 78,
  "status": "warning",
  "cpu": {
    "avg": 67.5,
    "max": 89.2,
    "trend": "rising",
    "analysis": "CPU 使用率呈上升趋势，从 45% 升至 67%，峰值出现在 10:23"
  },
  "insights": [
    "CPU 突增与 10:23 的部署事件时间吻合",
    "建议检查该时段是否有定时任务或流量突增"
  ],
  "suggested_actions": [
    "查看 order-service 在 10:23 的部署/变更记录",
    "对比同一时段其他服务的负载情况"
  ]
}

def restart_service_instance(
    service_name: str,
    instance_id: str,
    restart_type: str = "graceful",  # graceful / force
    CONFIRM_RESTART: str = None
) -> str:
    """
    重启指定服务的单个实例。
    
    参数 CONFIRM_RESTART:
      必须为 "I_CONFIRM_RESTART_INSTANCE_UNDERSTAND_RISK"
      
      填写前请确认：
      1. instance_id 正确无误（可通过 list_service_instances 核对）
      2. 当前不是业务高峰期
      3. 该实例无正在执行的重要任务
      4. 已通知相关团队成员
    """

def scale_service(
    service_name: str,
    target_replicas: int,
    scaling_strategy: str = "gradual",
    CONFIRM_SCALE: str = None,
    EMERGENCY_OVERRIDE: bool = False  # 第二层确认
) -> str:
    """
    调整服务的实例数量（扩缩容）。⚠️ 高危操作。
    
    【第一层确认：基本风险评估】
    参数 CONFIRM_SCALE 必须为：
    "I_CONFIRM_SCALE_SERVICE_UNDERSTAND_RISKS"
    
    确认清单：
    1. 已确认 target_replicas 合理（当前副本数、负载、资源配额）
    2. 缩容不会导致服务容量不足
    3. 扩容不会超出预算或资源限制
    4. 已评估对上下游服务的影响
    5. 当前不是关键业务时段
    
    【第二层确认：紧急模式（可选）】
    参数 EMERGENCY_OVERRIDE:
    - 系统自动根据风险评估矩阵决定
    - true: 需要第二人审批（高风险操作）
    """

def delete_service_data(
    service_name: str,
    data_type: str,  # logs / metrics / traces / all
    time_range: str,
    CONFIRM_DELETE: str = None,
    require_secondary_approval: bool = None  # 动态决定
) -> str:
    """
    删除指定服务的历史数据。⚠️ 不可逆操作。
    
    【风险评估矩阵】
    
    系统根据以下因素自动评估风险等级：
    
    | 因素 | 低风险 | 中风险 | 高风险 |
    |------|--------|--------|--------|
    | data_type | logs | metrics | all |
    | time_range | < 7d | 7d-30d | > 30d |
    | 服务等级 | 非核心 | 重要 | 核心 |
    | 时段 | 低峰期 | 正常 | 高峰期 |
    
    【确认要求】
    
    基础确认（所有情况必填）：
    CONFIRM_DELETE = "I_CONFIRM_DELETE_SERVICE_DATA_IRREVERSIBLE"
    
    确认清单：
    1. 已确认 time_range 正确，不会误删其他时段数据
    2. 已确认数据已备份或不再需要
    3. 已了解删除操作不可逆，无法恢复
    4. 已通知相关团队
    
    【动态二次确认】
    
    参数 require_secondary_approval:
    - 系统自动根据风险评估矩阵决定
    - true: 需要第二人审批（高风险操作）
    """

# ❌ 不好的设计：数组结构，容易出错
def update_configs(
    configs: list  # 复杂对象数组
) -> str:
    """
    批量更新配置。
    
    configs: 配置列表，每项包含 service, key, value
    """
    ...

# 调用时容易出错
{
  "configs": [
    {"service": "order-service", "key": "timeout", "value": "30s"},
    {"service": "payment-service", "key": "retries", "value": 3}  # 注意这里没引号
  ]
}

# ✅ 好的设计：展开为独立参数
def update_service_config(
    target_service: str,
    config_key: str,
    config_value: str,
    UPDATE_CONFIRMATION: str,  # Reminder Pattern
    dry_run: bool = True
) -> str:
    """
    更新指定服务的配置项。
    
    如需批量更新，请多次调用本工具。
    """
    ...

# 更清晰、更安全
{
  "target_service": "order-service",
  "config_key": "timeout",
  "config_value": "30s",
  "UPDATE_CONFIRMATION": "I_CONFIRM_CONFIG_UPDATE_UNDERSTAND_RISK",
  "dry_run": true
}

# ❌ 不好的设计
def restart_pods(
    pod_names: list,  # 数组，容易出错
    namespace: str
) -> str:
    """重启指定 Pod"""
    ...

# ✅ 好的设计
def restart_service_instances(
    service_name: str,  # 语义化，自动发现实例
    restart_mode: str = "rolling",
    batch_size: int = 1,
    CONFIRM_RESTART: str = None,
    require_approval: bool = True
) -> str:
    """
    滚动重启服务的实例。
    
    无需指定具体实例名称，自动发现并执行滚动重启。
    """
    ...

# ❌ 不好的设计：嵌套数组
def create_alert_rule(
    rule_name: str,
    conditions: list,  # [{"metric": "cpu", "operator": ">", "threshold": 80}, ...]
    notification_channels: list  # [{"type": "slack", "channel": "#alerts"}, ...]
) -> str:
    """创建告警规则"""
    ...

# ✅ 好的设计：展开为独立参数 + 限制数量
def create_alert_rule(
    rule_name: str,
    condition_1_metric: str,
    condition_1_operator: str,  # >, <, ==, >=, <=
    condition_1_threshold: float,
    condition_2_metric: str = None,  # 可选，最多支持 3 个条件
    condition_2_operator: str = None,
    condition_2_threshold: float = None,
    notify_slack_channel: str = None,
    notify_pagerduty_key: str = None,
    notify_email_addresses: str = None,  # 逗号分隔
    CONFIRM_CREATE: str = None
) -> str:
    """
    创建告警规则。
    
    支持最多 3 个条件组合（AND 关系）。
    至少配置一种通知渠道。
    """
    ...