research: 功能完整性评估方案调研

调研现有规则（keyword_match、llm_score、semantic_similarity）组合实现
"意图识别→任务完成度→任务成功率"分层测量的可行性。

推荐方案 A：组合现有规则，无需代码改动，2 人天完成。

research/functional-completeness-assessment.md

@@ -0,0 +1,193 @@
+# 功能完整性评估方案调研
+
+**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` 多维度）。