LocalAgent/docs/P1-03_optimization.md

# P1-03 相似任务匹配优化方案

## 问题概述

**问题标题**: 相似任务匹配过粗，误复用概率高  
**问题类型**: 业务规则/交互体验  
**所在位置**: history/manager.py:219, history/manager.py:232, app/agent.py:374

### 原问题描述
仅用简单关键词 Jaccard 相似度，无法区分关键参数差异（格式、目录、命名规则），容易"看起来相似但目标不同"。

### 影响分析
- 错误输出
- 用户误操作
- 对复用能力失去信任

---

## 优化方案

### 1. 结构化任务特征提取 (`history/task_features.py`)

#### 核心改进
将简单的关键词匹配升级为**多维度结构化特征提取**：

**提取的特征维度**:
- **文件格式** (.txt, .csv, .json 等) - 权重 15%
- **目录路径** (D:/photos, C:/documents 等) - 权重 15% (关键)
- **文件名** - 权重隐含在关键词中
- **命名规则** (按日期、按序号、按前缀等) - 权重 15%
- **操作类型** (重命名、转换、批量处理等) - 权重 20% (关键)
- **数量信息** (100个、所有、批量) - 权重 10%
- **约束条件** (如果、当、满足等) - 权重 5%
- **基础关键词** - 权重 20%

#### 示例对比

**场景 1: 高度相似（仅目录不同）**
```
当前: 将 D:/photos 目录下的所有 .jpg 图片按日期重命名
历史: 将 C:/images 目录下的所有 .jpg 图片按日期重命名
相似度: 77% (旧方法可能 90%+)
差异: 目录路径 [关键差异]
```

**场景 2: 看似相似实则不同（操作类型不同）**
```
当前: 将 D:/photos 目录下的所有 .jpg 图片转换为 .png
历史: 将 D:/photos 目录下的所有 .jpg 图片按日期重命名
相似度: 32.5% (旧方法可能 70%+)
差异: 
  - 文件格式 [重要]: 当前=.png, 历史=(无)
  - 命名规则 [重要]: 当前=(无), 历史=按日期
  - 操作类型 [关键]: 当前=转换, 历史=重命名
```

**场景 3: 数量差异**
```
当前: 批量转换 100 个 .docx 文件为 .pdf
历史: 批量转换所有 .docx 文件为 .pdf
相似度: 85.33%
差异: 数量 [一般]: 当前=100个, 历史=所有
```

---

### 2. 差异分级与可视化 (`ui/reuse_confirm_dialog.py`)

#### 差异重要性分级
- **critical (关键)**: 操作类型、目录路径 - 红色标记
- **high (重要)**: 文件格式、命名规则 - 橙色标记
- **medium (一般)**: 数量、约束条件 - 蓝色标记
- **low (次要)**: 其他细节 - 灰色标记

#### 新的确认对话框
替换原有的简单 `messagebox.askyesno`，提供：
- **相似度百分比显示** (带颜色编码)
- **差异列表** (分类、分级、对比显示)
- **当前值 vs 历史值** 的清晰对比
- **关键差异统计** (如 "2 关键, 3 重要")
- **可滚动界面** (支持多个差异项)

---

### 3. 度量指标收集 (`history/reuse_metrics.py`)

#### 收集的指标
按照建议的度量指标实现：

**复用行为指标**:
- `total_offered`: 复用建议提供次数
- `total_accepted`: 用户接受次数
- `total_rejected`: 用户拒绝次数
- `acceptance_rate`: 接受率 = accepted / offered
- `rejection_rate`: 拒绝率 = rejected / offered

**复用质量指标**:
- `total_executed`: 复用后执行次数
- `success_rate`: 复用后成功率
- `failure_rate`: 复用后失败率
- `rollback_rate`: 复用后回滚率

**特征统计**:
- `avg_similarity`: 平均相似度
- `avg_differences`: 平均差异数量
- `avg_critical_differences`: 平均关键差异数量

#### 数据持久化
所有指标保存在 `workspace/reuse_metrics.json`，包含：
- 时间戳
- 原始任务 ID
- 新任务 ID
- 相似度分数
- 用户操作 (offered/accepted/rejected/executed/rollback)
- 差异统计
- 执行结果

---

### 4. 集成到主流程 (`app/agent.py`)

#### 修改点 1: `_handle_execution` 方法
```python
# 使用增强匹配获取详细信息
result = self.history.find_similar_success(user_input, return_details=True)
if result:
    similar_record, similarity_score, differences = result
    
    # 记录指标
    metrics.record_reuse_offered(...)
    
    # 显示增强对话框
    show_reuse_confirm_dialog(
        similarity_score=similarity_score,
        differences=differences,
        on_confirm=...,
        on_reject=...
    )
```

#### 修改点 2: `_on_execution_complete` 方法
```python
# 如果是复用任务，记录执行结果
if self.current_task.get('is_reuse'):
    metrics.record_reuse_execution(
        original_task_id=...,
        new_task_id=result.task_id,
        success=result.success
    )
```

---

## 技术实现细节

### 特征提取算法

**文件格式提取**:
```python
FILE_FORMAT_PATTERN = r'\.(txt|csv|json|xml|xlsx?|docx?|pdf|png|jpe?g|...)'
```

**目录路径提取** (支持 Windows 和 Unix):
```python
DIR_PATH_PATTERN = r'(?:[a-zA-Z]:\\[\w\\\s\u4e00-\u9fa5.-]+|/[\w/\s\u4e00-\u9fa5.-]+|...)'
```

**操作类型识别** (关键词映射):
```python
OPERATION_KEYWORDS = {
    '重命名': ['重命名', '改名', '命名', '更名'],
    '转换': ['转换', '转为', '转成', '变成'],
    '批量处理': ['批量', '批处理', '一次性'],
    ...
}
```

### 相似度计算

**加权多维度评分**:
```python
total_score = (
    keyword_sim * 0.2 +
    format_sim * 0.15 +
    dir_sim * 0.15 +
    naming_sim * 0.15 +
    operation_sim * 0.2 +
    quantity_sim * 0.1 +
    constraint_sim * 0.05
)
```

---

## 测试结果

运行 `tests/test_task_features.py` 验证：

✅ **场景 1**: 仅目录不同 → 相似度 77% (合理，有关键差异)  
✅ **场景 2**: 操作类型不同 → 相似度 32.5% (正确降低)  
✅ **场景 3**: 完全不同任务 → 相似度 15% (正确识别)  
✅ **场景 4**: 仅数量不同 → 相似度 85.33% (合理，非关键差异)  
✅ **边界情况**: 完全相同 → 100%, 空输入 → 100%

---

## 预期效果

### 优化前
- 简单 Jaccard 相似度
- 无差异提示
- 用户盲目复用
- 高误操作率

### 优化后
- 多维度结构化匹配
- 清晰的差异对比
- 知情决策
- 降低误复用率

### 度量指标预期改善
- **复用确认放弃率**: 对于有关键差异的任务，用户会更多选择"生成新代码"
- **复用后失败率**: 下降 (因为用户看到差异后会更谨慎)
- **复用后回滚率**: 下降 (减少误操作)
- **用户信任度**: 提升 (透明的差异展示)

---

## 文件清单

### 新增文件
1. `history/task_features.py` - 任务特征提取与匹配核心模块
2. `history/reuse_metrics.py` - 复用度量指标收集模块
3. `ui/reuse_confirm_dialog.py` - 增强的复用确认对话框
4. `tests/test_task_features.py` - 测试用例

### 修改文件
1. `history/manager.py` - 增强 `find_similar_success` 方法
2. `app/agent.py` - 集成新的匹配逻辑和指标收集

---

## 使用示例

### 查看复用统计
```python
from history.reuse_metrics import get_reuse_metrics

metrics = get_reuse_metrics(workspace_path)
stats = metrics.get_statistics()

print(f"接受率: {stats['acceptance_rate']:.1%}")
print(f"成功率: {stats['success_rate']:.1%}")
print(f"平均相似度: {stats['avg_similarity']:.1%}")
```

### 手动测试匹配
```python
from history.task_features import get_task_matcher

matcher = get_task_matcher()
score, diffs = matcher.calculate_similarity(
    "将 D:/photos 下的 .jpg 按日期重命名",
    "将 C:/images 下的 .jpg 按日期重命名"
)

print(f"相似度: {score:.1%}")
for diff in diffs:
    print(f"{diff.category}: {diff.current_value} vs {diff.history_value}")
```

---

## 后续优化建议

1. **机器学习优化**: 根据用户的接受/拒绝行为，动态调整各维度权重
2. **智能阈值**: 根据差异重要性动态调整相似度阈值
3. **差异解释**: 使用 LLM 生成自然语言的差异说明
4. **A/B 测试**: 对比优化前后的用户行为数据

---

## 总结

本次优化通过**结构化特征提取**、**差异可视化**和**度量指标收集**三个方面，从根本上解决了相似任务匹配过粗的问题。用户现在可以清楚地看到任务之间的关键差异，做出更明智的复用决策，从而提升系统的可信度和用户体验。