research/functional-completeness-assessment.md

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