feat: refactor API key configuration and enhance application initialization
- Renamed `check_environment` to `check_api_key_configured` for clarity, simplifying the API key validation logic. - Removed the blocking behavior of the API key check during application startup, allowing the app to run while providing a prompt for configuration. - Updated `LocalAgentApp` to accept an `api_configured` parameter, enabling conditional messaging for API key setup. - Enhanced the `SandboxRunner` to support backup management and improved execution result handling with detailed metrics. - Integrated data governance strategies into the `HistoryManager`, ensuring compliance and improved data management. - Added privacy settings and metrics tracking across various components to enhance user experience and application safety.
This commit is contained in:
Mimikko-zeus
286
docs/P1-03_optimization.md
Normal file
286
docs/P1-03_optimization.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# 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 测试**: 对比优化前后的用户行为数据
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
本次优化通过**结构化特征提取**、**差异可视化**和**度量指标收集**三个方面，从根本上解决了相似任务匹配过粗的问题。用户现在可以清楚地看到任务之间的关键差异，做出更明智的复用决策，从而提升系统的可信度和用户体验。
|
||||
|
||||
Reference in New Issue
Block a user