# gmode check-detailed 功能文档

## 概述

在 Shell Bot 中新增了 `### gmode check-detailed ###` 命令，用于全面测试所有 Gemini 配置的健康状态，特别是 **Function Calling** 功能是否正常工作。

## 背景

之前的 `### gmode check ###` 只做基础的连接测试（ping），无法检测 Function Calling 是否损坏。而 Function Calling 是 Butler Bot 的核心功能，如果它不工作，Bot 就无法调用工具（如查询健康数据、执行shell命令等）。

## 新命令详情

### 命令格式

```
### gmode check-detailed ###
```

### 测试内容

对每个配置文件（`.gemini.*.env`）运行 3 个测试：

1. **简单对话（无工具）**
   - 发送 "Hello"，期望得到文本回复
   - 测试基础LLM连接

2. **健康查询（无工具）**
   - 使用完整的 system prompt 但不带工具
   - 发送 "今天睡得怎么样？"
   - 测试复杂 prompt 是否导致问题

3. **Function Calling (6工具)**
   - 使用完整的 system prompt + 6个轻量级工具
   - 发送 "今天睡得怎么样？"
   - 期望 LLM 调用 `get_daily_detailed_stats` 工具
   - **这是最关键的测试**

### 评分标准

- **🟢 A 级 (≥67% 通过)**: 健康，Function Calling 可用
- **🟡 C 级 (33-66% 通过)**: 一般，基础功能可用但 Function Calling 可能有问题
- **🔴 F 级 (<33% 通过)**: 故障，不建议使用

### 输出示例

```
================================================================================
📋 Testing: .gemini.local.env ⭐ CURRENT
================================================================================
Model: gemini-3-pro-high
Base URL: http://127.0.0.1:8045

  Running: 简单对话（无工具）... ✅ (285 chars) [7.40s]
  Running: 健康查询（无工具）... ❌ (empty) [8.61s]
  Running: Function Calling (6工具)... ❌ (no tool calls) [5.59s]

Overall Grade: 🟡 C (33% success, avg 7.20s)

================================================================================
📋 Testing: .gemini.openrouter.env
================================================================================
Model: google/gemini-3-flash-preview
Base URL: https://openrouter.ai/api

  Running: 简单对话（无工具）... ✅ (32 chars) [2.73s]
  Running: 健康查询（无工具）... ❌ (empty) [1.75s]
  Running: Function Calling (6工具)... ✅ (1 tools) [1.43s]

Overall Grade: 🟢 A (67% success, avg 1.97s)
```

## 使用场景

### 1. 诊断代理问题

当 Bot 无法正确调用工具时，使用此命令快速诊断：

```
你: ### gmode check-detailed ###
Bot: [显示详细健康报告]
     本地代理: 🔴 F (Function Calling 损坏)
     OpenRouter: 🟢 A (完全可用)
```

### 2. 选择最佳配置

在多个配置之间选择时，对比测试结果：

```
本地代理:
  - 成功率: 33%
  - 平均响应: 7.20s
  - Function Calling: ❌

OpenRouter:
  - 成功率: 67%
  - 平均响应: 1.97s
  - Function Calling: ✅

结论: 切换到 OpenRouter
```

### 3. 监控配置稳定性

定期运行（如每周）检查配置是否仍然健康：

```bash
# 在 Shell Bot 中
### gmode check-detailed ###

# 或者直接在服务器上运行
python3 scripts/select_gemini.py check-detailed
```

## 实现原理

### 文件结构

```
scripts/select_gemini.py
├── check_health()              # 快速检查（原有）
├── check_health_detailed()     # 详细检查（新增）
└── main()                      # 处理命令行参数

slack_bot/shell_main.py
└── handle_message()
    └── gmode_match              # 匹配 ### gmode ... ###
        ├── check               # 调用 check_health()
        └── check-detailed      # 调用 check_health_detailed()
```

### 关键代码位置

- `scripts/select_gemini.py:140-287` - `check_health_detailed()` 函数
- `slack_bot/shell_main.py:131-166` - gmode 命令处理器
- `slack_bot/shell/help_text.py:19-24` - 帮助文档

## 与其他工具的对比

| 工具 | 测试内容 | 输出格式 | 使用场景 |
|------|---------|---------|---------|
| `### gmode check ###` | 基础连接（ping） | 表格 | 快速检查配置是否可访问 |
| `### gmode check-detailed ###` | 完整测试（包括Function Calling） | 详细报告 | 诊断工具调用问题 |
| `scripts/health_check.py` | 全面测试（5个测试） | 详细报告 + 建议 | 深入分析代理健康状况 |
| `scripts/monitor_proxy_health.py` | 持续监控 | 历史趋势 | 长期跟踪代理稳定性 |

## 常见问题

### Q: 为什么有些测试失败是正常的？

A: 某些配置可能不支持某些功能。例如：
- `.gemini.api.env` 如果 API key 过期，所有测试都会失败
- 本地代理如果有 Function Calling bug，第3个测试会失败

### Q: 应该选择哪个配置？

A: 优先选择：
1. **Grade A** 的配置（≥67% 通过）
2. **Function Calling 可用** 的配置（第3个测试通过）
3. **响应速度快** 的配置（平均 <3s）

通常 OpenRouter 是最佳选择（Grade A + Function Calling ✅ + 2s 响应）。

### Q: 命令运行需要多久？

A: 约 30-60 秒，取决于配置数量和响应速度。

### Q: 可以在普通终端运行吗？

A: 可以！直接运行：

```bash
cd /path/to/bulter
source venv/bin/activate
python3 scripts/select_gemini.py check-detailed
```

## 总结

`### gmode check-detailed ###` 是一个强大的诊断工具，能够：

- ✅ 全面测试所有 Gemini 配置
- ✅ 检测 Function Calling 是否损坏
- ✅ 对比不同配置的性能
- ✅ 提供清晰的评分和建议
- ✅ 可通过 Slack 或终端使用

建议在以下情况使用：
- Bot 无法正确调用工具时
- 切换配置前对比性能时
- 定期健康检查时（每周）