# ISS-0090: Agent 使用幻觉参数 --promql 调用 clinic_cli.py metrics

## Background

ws-1779196521741-67b1f2f94（cluster 10518506906906971664，dedicated，2026-05-19）中，
用户报告连接问题（2026-05-08 08:30–12:35 CST），Agent 在第二轮（用户 follow-up "着重看下
tidb 的一些指标呢，这是连接的问题"）调用 clinic_cli.py metrics 时，使用了不存在的
`--promql` 参数：

```bash
python3 .opencode/skills/builtin/clinic-cli/scripts/clinic_cli.py metrics \
  --cluster-id 10518506906906971664 \
  --start 1778200200 --end 1778214900 \
  --promql 'sum(tidb_server_connections{component="tidb"}) by (instance)' \
  --name 'tidb_connections_by_instance' 2>&1 | python3 -c "..."
```

工具报错：
```
usage: clinic_cli.py metrics [-h] --cluster-id CLUSTER_ID --name NAME --query
                             QUERY --start START --end END ...
clinic_cli.py metrics: error: the following arguments are required: --query
```

Agent 在第二次重试时自行修正为 `--query`，但：
1. 触发了一次额外的失败 tool call
2. 第一次失败后，后续分析 metrics.json 的 Python 脚本出现
   `TypeError: unsupported format string passed to NoneType.__format__`
   （因为对应 metric_group_id 在第一次查询失败后为空记录）

## Root Cause Analysis

Agent 从 clinic-cli SKILL.md 或记忆中无法获得 `metrics` 子命令的完整参数签名，
凭猜测使用了 `--promql`（可能类比 Prometheus/VictoriaMetrics 的惯例命名），
而实际参数名为 `--query`。

当前 clinic-cli SKILL.md 对 `metrics` 子命令的参数描述可能不完整或未列出完整参数名。

## Observed Error (from workspace ws-1779196521741-67b1f2f94)

```
Failed tool: 查询 TiDB 各实例连接数
Command: clinic_cli.py metrics --promql '...' (wrong flag)
Error: the following arguments are required: --query
Status: failed → retried with --query → completed

Follow-on failure: 分析各 TiDB 实例连接数峰值
Error: TypeError: unsupported format string passed to NoneType.__format__
Cause: metrics.json lacks the metric_group_id due to prior query failure
Status: failed → retried with corrected parsing → completed
```

## Fix Plan

1. **clinic-cli SKILL.md 添加 metrics 子命令完整参数列表**:

```markdown
## metrics 子命令参数

```bash
clinic_cli.py metrics \
  --cluster-id <CLUSTER_ID> \   # 必填
  --name <METRIC_GROUP_NAME> \  # 必填：保存结果用的标识名
  --query <PROMQL_EXPR> \       # 必填：PromQL 查询表达式（注意：是 --query，不是 --promql）
  --start <EPOCH_SECONDS> \     # 必填
  --end <EPOCH_SECONDS> \       # 必填
  [--step <SECONDS>] \          # 可选，默认 30s
  [--metric-group-id <ID>] \    # 可选
  [--unit <UNIT>] \             # 可选
  [--inline-chart-data]          # 可选 flag
```
```

2. **clinic-cli SKILL.md 加警告**:
> ⚠️ 常见错误：`--query` 而非 `--promql`。Agent 必须使用 `--query` 传递 PromQL 表达式。

3. **collect_evidence.py analysis 脚本防御**:
   在 Python 分析脚本中，当 `metric_group_id` 不存在于 metrics.json 时，
   输出明确的 "metric {name} not available" 而非抛出 NoneType 异常。

## Verification

验证方式：
1. 在新 workspace 中运行连接指标查询，确认 Agent 使用 `--query` 参数
2. 在 clinic-cli SKILL.md 更新后重新运行诊断，观察是否仍出现 --promql 错误