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 方法

# 使用增强匹配获取详细信息
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 方法

# 如果是复用任务，记录执行结果
if self.current_task.get('is_reuse'):
    metrics.record_reuse_execution(
        original_task_id=...,
        new_task_id=result.task_id,
        success=result.success
    )

---

技术实现细节

特征提取算法

文件格式提取:

FILE_FORMAT_PATTERN = r'\.(txt|csv|json|xml|xlsx?|docx?|pdf|png|jpe?g|...)'

目录路径提取 (支持 Windows 和 Unix):

DIR_PATH_PATTERN = r'(?:[a-zA-Z]:\\[\w\\\s\u4e00-\u9fa5.-]+|/[\w/\s\u4e00-\u9fa5.-]+|...)'

操作类型识别 (关键词映射):

OPERATION_KEYWORDS = {
    '重命名': ['重命名', '改名', '命名', '更名'],
    '转换': ['转换', '转为', '转成', '变成'],
    '批量处理': ['批量', '批处理', '一次性'],
    ...
}

相似度计算

加权多维度评分:

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 - 集成新的匹配逻辑和指标收集

---

使用示例

查看复用统计

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%}")

手动测试匹配

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 测试: 对比优化前后的用户行为数据

---

总结

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