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.
2026-02-27 14:32:30 +08:00
parent ab5bbff6f7
commit 8a538bb950
58 changed files with 13457 additions and 350 deletions
--- a/docs/P1-01-solution.md
+++ b/docs/P1-01-solution.md
@@ -0,0 +1,226 @@
+# P1-01 配置保存与客户端单例冲突问题 - 解决方案
+
+## 问题描述
+
+设置页写入 `.env` 后未刷新 LLMClient 单例，旧 API Key/URL 可能继续使用，用户感知为"保存不生效"。
+
+## 影响分析
+
+- 配置变更失败
+- 调用报错
+- 支持成本上升
+- 用户体验差
+
+## 解决方案
+
+### 1. 客户端单例重置机制
+
+**文件**: `llm/client.py`
+
+新增功能：
+- `reset_client()`: 重置全局客户端单例，强制下次调用时使用新配置
+- `test_connection()`: 测试 API 连接是否正常，返回详细的错误信息
+
+```python
+def reset_client() -> None:
+    """重置 LLM 客户端单例（配置变更后调用）"""
+    global _client
+    _client = None
+
+def test_connection(timeout: int = 10) -> tuple[bool, str]:
+    """测试 API 连接是否正常"""
+    # 发送测试请求，返回 (是否成功, 消息)
+```
+
+### 2. 设置保存流程优化
+
+**文件**: `ui/settings_view.py`
+
+保存配置后的处理流程：
+1. 保存配置到 `.env` 文件
+2. 更新环境变量 `os.environ`
+3. **重置客户端单例** `reset_client()`
+4. **进行连通性测试** `test_connection()`
+5. 向用户反馈测试结果
+6. 记录配置变更度量
+
+```python
+def _save_config(self) -> None:
+    # ... 保存配置 ...
+    
+    # 重置客户端单例
+    from llm.client import reset_client, test_connection
+    reset_client()
+    
+    # 连通性测试
+    success, message = test_connection(timeout=15)
+    
+    # 反馈结果
+    if success:
+        messagebox.showinfo("成功", f"配置已保存并生效！\n\n{message}")
+    else:
+        messagebox.showwarning("配置已保存", f"配置已保存，但连接测试失败：\n\n{message}")
+```
+
+### 3. 配置变更度量跟踪
+
+**文件**: `llm/config_metrics.py` (新增)
+
+跟踪指标：
+- 配置变更总次数
+- 首次调用成功率
+- 平均重试次数
+- 连接测试成功率
+- 从配置变更到首次成功调用的时间
+
+```python
+class ConfigMetricsManager:
+    def mark_config_changed(self, connection_test_success: bool):
+        """标记配置已变更"""
+    
+    def record_first_call(self, success: bool, error_message: Optional[str] = None):
+        """记录配置变更后的首次调用"""
+    
+    def increment_retry(self):
+        """增加重试计数"""
+    
+    def get_statistics(self) -> Dict[str, Any]:
+        """获取统计信息"""
+```
+
+### 4. Agent 集成
+
+**文件**: `app/agent.py`
+
+- 在首次 LLM 调用时记录成功/失败度量
+- 在重试时增加重试计数
+- 设置保存后更新 API 配置状态
+
+## 工作流程
+
+```
+用户修改配置
+    ↓
+保存到 .env
+    ↓
+更新 os.environ
+    ↓
+reset_client() ← 重置单例
+    ↓
+test_connection() ← 连通性测试
+    ↓
+记录度量 (mark_config_changed)
+    ↓
+反馈用户
+    ↓
+用户发起调用
+    ↓
+get_client() ← 创建新实例（使用新配置）
+    ↓
+记录首次调用结果 (record_first_call)
+```
+
+## 关键改进点
+
+### ✅ 配置立即生效
+- 保存后立即重置客户端单例
+- 下次调用自动使用新配置
+
+### ✅ 连通性校验反馈
+- 保存后自动测试连接
+- 详细的错误信息提示
+- 区分配置错误、网络错误、认证错误等
+
+### ✅ 度量指标跟踪
+- 首次调用成功率
+- 平均重试次数
+- 连接测试成功率
+- 响应时间统计
+
+### ✅ 用户体验优化
+- 明确的成功/失败反馈
+- 具体的错误原因说明
+- 配置生效状态提示
+
+## 测试验证
+
+运行测试脚本：
+```bash
+python test_config_refresh.py
+```
+
+测试内容：
+1. 加载初始配置
+2. 创建客户端实例
+3. 重置客户端单例
+4. 验证新实例使用新配置
+5. 测试 API 连接
+6. 查看度量统计
+
+## 度量指标
+
+### 建议监控指标
+
+1. **保存后首次调用成功率**
+   - 目标: ≥ 95%
+   - 计算: 成功次数 / 总配置变更次数
+
+2. **配置修改后重试次数**
+   - 目标: ≤ 0.5 次/配置变更
+   - 计算: 总重试次数 / 总配置变更次数
+
+3. **连接测试成功率**
+   - 目标: ≥ 90%
+   - 计算: 测试成功次数 / 总配置变更次数
+
+4. **配置生效时间**
+   - 目标: ≤ 2 秒
+   - 计算: 从保存到首次成功调用的时间
+
+### 查看度量数据
+
+度量数据保存在：`workspace/.metrics/config_metrics.json`
+
+可通过代码查看：
+```python
+from llm.config_metrics import get_config_metrics
+metrics = get_config_metrics(workspace)
+stats = metrics.get_statistics()
+print(stats)
+```
+
+## 影响范围
+
+### 修改的文件
+- `llm/client.py` - 新增重置和测试功能
+- `ui/settings_view.py` - 集成重置和测试流程
+- `app/agent.py` - 记录度量数据
+- `llm/config_metrics.py` - 新增度量模块
+
+### 新增的文件
+- `llm/config_metrics.py` - 配置度量管理
+- `test_config_refresh.py` - 测试脚本
+- `docs/P1-01-solution.md` - 本文档
+
+## 后续优化建议
+
+1. **异步连通性测试**: 避免阻塞 UI 线程
+2. **配置版本管理**: 记录配置变更历史
+3. **自动配置修复**: 检测到错误时提供修复建议
+4. **批量配置验证**: 保存前验证所有配置项的有效性
+5. **配置模板**: 提供常用 API 服务的配置模板
+
+## 总结
+
+通过引入客户端单例重置机制、连通性校验和度量跟踪，彻底解决了配置保存后不生效的问题。用户现在可以：
+
+- ✅ 保存配置后立即生效
+- ✅ 获得明确的连接测试反馈
+- ✅ 了解配置是否正确
+- ✅ 减少配置错误导致的调用失败
+
+预期效果：
+- 配置相关支持请求减少 80%+
+- 首次调用成功率提升至 95%+
+- 用户满意度显著提升
+