# 功能完整性评估方案调研

**Ticket**: [#18](https://git.solahqb22.cn/solahqb/AgentEvalTool/issues/18)
**Wayfinder**: [#13](https://git.solahqb22.cn/solahqb/AgentEvalTool/issues/13)
**日期**: 2026-08-25

## 1. 现有规则能力分析

### 1.1 keyword_match

**功能**：检查回复是否包含必需关键词，排除禁用词。

**量化方式**：
- `score = matched_keywords / total_keywords`
- 例如：需要 5 个关键词，匹配 3 个 → score = 0.6

**适用场景**：
- **任务完成度**：将每个必需信息项作为关键词，匹配率即为完成度
- 例如：挂号任务需要收集"科室、日期、时间、姓名、电话"5 项，每项作为一个关键词

**限制**：
- 只能做字面匹配，无法理解语义
- 无法判断意图是否正确识别

### 1.2 llm_score

**功能**：使用 LLM 对回复质量打分（0-10）。

**量化方式**：
- 通过 `criteria` 参数定义评分标准
- LLM 根据标准打分，返回 `{score, reason}`

**适用场景**：
- **意图识别准确率**：criteria 定义为"AI 是否正确理解了用户意图"
- **响应质量**：criteria 定义为"回答的准确性、相关性、完整性"

**限制**：
- 当前只支持单一分数，不支持多维度独立评分
- 评分质量依赖 LLM 能力和 prompt 设计

### 1.3 semantic_similarity

**功能**：使用 embedding 计算回复与参考答案的余弦相似度。

**量化方式**：
- `score = cosine_similarity(reply_embedding, reference_embedding)`
- 范围 0-1，阈值默认 0.7

**适用场景**：
- **响应质量**：与标准答案的语义接近程度
- **功能完整性**：如果参考答案代表"完整正确的回复"，相似度可衡量完整性

**限制**：
- 需要参考答案（reference）
- 只能做整体相似度，无法细分维度

## 2. 分层测量实现方案

### 2.1 方案 A：组合现有规则（推荐）

**Layer 1: 意图识别准确率**
- 使用 `llm_score`，criteria 定义为：
  ```
  判断 AI 是否正确理解了用户的意图。
  - 10 分：完全理解意图，准确回应
  - 7-9 分：基本理解意图，有小偏差
  - 4-6 分：部分理解意图
  - 0-3 分：误解或未理解意图
  ```
- 输出：0-10 分

**Layer 2: 任务完成度**
- 使用 `keyword_match`，将每个必需信息项作为关键词
- 例如：挂号任务配置
  ```json
  {
    "keywords": ["内科", "2026-08-26", "上午", "张三", "13800138000"],
    "min_match_ratio": 1.0
  }
  ```
- 输出：matched / total（如 3/5 = 0.6）

**Layer 3: 任务成功率**
- 二值判断：intent_score >= 7 AND completion_ratio >= 1.0
- 或概率：weighted_score = 0.4 * intent_score/10 + 0.6 * completion_ratio

**优点**：
- 无需新增规则类型
- 利用现有基础设施
- 配置灵活

**缺点**：
- 需要为每个任务手动配置关键词
- 意图识别和任务完成度分开评估，可能需要两次 LLM 调用

### 2.2 方案 B：新增 intent_classification 规则

新增规则类型 `intent_classification`，专门用于意图识别：
- 输入：用户问题 + 预期意图列表
- 输出：匹配的意图 + 置信度

**优点**：
- 语义更清晰
- 可以支持意图分类准确率统计

**缺点**：
- 需要新增规则类型
- 与 `llm_score` 功能重叠

### 2.3 方案 C：扩展 llm_score 支持多维度

扩展 `llm_score` 支持多个独立评分维度：
- 配置：`dimensions: [{name: "intent", criteria: "..."}, {name: "completion", criteria: "..."}]`
- 输出：`{intent: 8, completion: 6}`

**优点**：
- 一次 LLM 调用完成多维度评分
- 灵活配置

**缺点**：
- 需要修改 `llm_score` 规则
- Prompt 设计复杂

## 3. 推荐方案

**方案 A（组合现有规则）**，理由：
1. 无需代码改动，立即可用
2. 利用现有规则的成熟实现
3. 配置灵活，可逐步优化

**实施步骤**：
1. 为典型任务配置 `llm_score`（意图识别）+ `keyword_match`（任务完成度）
2. 定义成功阈值（如 intent >= 7 AND completion >= 1.0）
3. 在报告中聚合为"功能完整性"指标

## 4. 任务完成度量化方式

**推荐**：使用 `keyword_match` 的匹配率

**配置示例**：
```yaml
cases:
  - id: "appointment-task"
    messages:
      - "我要挂明天上午内科的号，姓名张三，电话 13800138000"
    rules:
      - type: keyword_match
        params:
          keywords: ["内科", "明天", "上午", "张三", "13800138000"]
          # 5 个必需信息项
```

**量化**：
- 完成度 = matched_keywords / total_keywords
- 例如：AI 确认了"内科、明天、上午"但遗漏姓名和电话 → 完成度 = 3/5 = 60%

## 5. 任务成功率定义

**推荐**：二值判断（通过/未通过）

**定义**：
- 成功 = (intent_score >= 7) AND (completion_ratio >= 1.0)
- 即：意图正确理解 + 所有必需信息收集完成

**备选**：概率分数
- success_score = 0.4 * (intent_score / 10) + 0.6 * completion_ratio
- 范围 0-1，可用于趋势分析

## 6. 工作量估算

**方案 A（组合现有规则）**：
- 配置模板设计：0.5 人天
- 文档编写（如何配置功能完整性评估）：0.5 人天
- 报告聚合逻辑：1 人天
- **总计：2 人天**

**方案 B（新增 intent_classification 规则）**：
- 规则实现：2 人天
- 测试：1 人天
- 文档：0.5 人天
- **总计：3.5 人天**

**方案 C（扩展 llm_score 多维度）**：
- 规则修改：2 人天
- 测试：1 人天
- 文档：0.5 人天
- **总计：3.5 人天**

## 7. 结论

**推荐方案 A**：组合现有规则（`llm_score` + `keyword_match`），无需代码改动，2 人天完成配置和文档。

**后续优化**：如果方案 A 在实际使用中遇到瓶颈（如配置复杂、LLM 调用成本高），可考虑方案 C（扩展 `llm_score` 多维度）。