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/PROJECT_STRUCTURE.md
+++ b/docs/PROJECT_STRUCTURE.md
@@ -0,0 +1,231 @@
+# LocalAgent 项目结构总结
+
+## 项目概述
+
+LocalAgent 是一个基于 LLM 的本地代码执行智能助手，通过自然语言交互帮助用户生成和执行 Python 代码，具备完善的安全机制和历史复用能力。
+
+## 核心架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        用户界面层 (ui/)                        │
+│  Chat View │ History View │ Settings View │ Dialogs         │
+└─────────────────────┬───────────────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────────────┐
+│                     核心控制层 (app/)                          │
+│              Agent (主流程控制与协调)                          │
+└──┬────────┬────────┬────────┬────────┬────────┬────────────┘
+   │        │        │        │        │        │
+   ▼        ▼        ▼        ▼        ▼        ▼
+┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌──────────┐
+│Intent││ LLM  ││Safety││Execu-││Histo-││Workspace │
+│ 意图 ││ 交互 ││ 安全 ││ tor  ││ ry   ││  工作区  │
+│识别  ││      ││ 检查 ││ 执行 ││ 历史 ││          │
+└──────┘└──────┘└──────┘└──────┘└──────┘└──────────┘
+```
+
+## 目录结构详解
+
+### 核心业务模块
+
+#### `app/` - 应用核心
+- **agent.py** (1503行): 主Agent类，协调所有模块，处理用户请求
+- **exceptions.py**: 自定义异常类型
+- **metrics_logger.py**: 性能和行为指标记录
+- **privacy_config.py**: 隐私保护配置管理
+
+#### `executor/` - 代码执行引擎
+- **sandbox_runner.py** (493行): 沙箱执行器，隔离环境运行代码
+- **path_guard.py** (174行): 路径安全守卫，防止越界访问
+- **backup_manager.py**: 执行前数据备份管理
+- **execution_metrics.py**: 执行性能指标收集
+
+#### `safety/` - 安全防护层
+- **rule_checker.py** (334行): 基于规则的静态代码安全检查
+- **llm_reviewer.py**: 基于LLM的智能安全审查
+- **security_metrics.py**: 安全事件指标统计
+
+#### `history/` - 历史管理
+- **manager.py**: 历史任务存储和检索
+- **task_features.py**: 任务特征提取（TF-IDF）
+- **reuse_metrics.py**: 代码复用效果指标
+
+#### `intent/` - 意图识别
+- **classifier.py**: 基于机器学习的意图分类器
+- **labels.py**: 意图标签定义（代码生成/数据分析/文件操作等）
+
+#### `llm/` - LLM交互
+- **client.py**: OpenAI API客户端封装
+- **prompts.py**: 提示词模板管理
+- **config_metrics.py**: LLM配置和调用指标
+
+#### `ui/` - 用户界面
+- **chat_view.py**: 主聊天交互界面
+- **history_view.py**: 历史任务浏览
+- **settings_view.py**: 系统设置
+- **task_guide_view.py**: 任务引导
+- **privacy_settings_view.py**: 隐私设置
+- **reuse_confirm_dialog.py**: 代码复用确认对话框
+- **clear_confirm_dialog.py**: 清空确认对话框
+- **clarify_view.py**: 需求澄清界面
+
+### 支持目录
+
+#### `tests/` - 测试代码
+- **test_rule_checker.py**: 安全规则检查器测试
+- **test_intent_classifier.py**: 意图分类器测试
+- **test_history_manager.py**: 历史管理器测试
+- **test_task_features.py**: 任务特征提取测试
+- **test_config_refresh.py**: 配置刷新测试
+- **test_retry_fix.py**: 重试机制测试
+
+#### `docs/` - 项目文档
+- **PRD.md**: 产品需求文档
+- **P0-01_安全边界加固实施报告.md**: 路径安全加固
+- **P0-02_历史代码复用安全复检实施报告.md**: 复用安全机制
+- **P0-03_执行前清空数据丢失修复报告.md**: 备份机制实施
+- **P1-01-solution.md**: 优化方案
+- **P1-02_重试策略修复说明.md**: LLM重试优化
+- **P1-03_optimization.md**: 性能优化
+- **P1-04-optimization-summary.md**: 优化总结
+- **P1-05_执行结果状态模型升级.md**: 状态管理升级
+- **P1-06_隐私保护优化方案.md**: 隐私保护增强
+
+#### `workspace/` - 运行时工作空间
+```
+workspace/
+├── codes/          # 生成的Python代码
+├── input/          # 用户输入文件
+├── output/         # 代码执行输出
+├── logs/           # 执行日志
+├── metrics/        # 性能指标报告
+└── history.json    # 历史任务记录
+```
+
+#### `build/` & `dist/` - 构建输出
+- **build/**: PyInstaller构建中间文件
+- **dist/LocalAgent/**: 可分发的可执行程序包
+
+### 配置文件
+
+- **main.py**: 程序入口
+- **build.py**: PyInstaller构建脚本
+- **requirements.txt**: Python依赖清单
+- **LocalAgent.spec**: PyInstaller配置
+- **README.md**: 项目说明文档
+- **RULES.md**: 项目开发规范
+
+## 核心工作流程
+
+### 1. 用户请求处理流程
+```
+用户输入 → Intent分类 → History检索 
+    ↓
+复用确认 → LLM生成代码 → Safety双重审查
+    ↓
+Backup备份 → Sandbox执行 → 结果展示
+    ↓
+保存历史 → 指标记录
+```
+
+### 2. 安全检查流程
+```
+生成代码
+    ↓
+RuleChecker (规则检查)
+    ├─ 危险函数检测
+    ├─ 路径安全验证
+    └─ 导入模块检查
+    ↓
+LLMReviewer (智能审查)
+    ├─ 语义安全分析
+    ├─ 潜在风险评估
+    └─ 修复建议生成
+    ↓
+PathGuard (执行时守卫)
+    └─ 运行时路径拦截
+```
+
+### 3. 历史复用流程
+```
+用户需求 → 特征提取 (TF-IDF)
+    ↓
+相似度计算 (余弦相似度)
+    ↓
+候选任务排序 → 用户确认
+    ↓
+安全复检 → 直接执行/修改后执行
+```
+
+## 技术栈
+
+- **UI框架**: Textual (Python TUI)
+- **LLM**: OpenAI GPT-4
+- **机器学习**: scikit-learn (TF-IDF, 余弦相似度)
+- **代码执行**: subprocess (沙箱隔离)
+- **打包工具**: PyInstaller
+- **Python版本**: 3.8+
+
+## 关键特性
+
+### 安全性
+- ✅ 双重安全审查（规则+LLM）
+- ✅ 沙箱隔离执行
+- ✅ 路径访问控制
+- ✅ 执行前自动备份
+
+### 智能化
+- ✅ 意图自动识别
+- ✅ 历史代码复用
+- ✅ 相似任务推荐
+- ✅ 智能错误修复
+
+### 用户体验
+- ✅ 友好的TUI界面
+- ✅ 实时执行反馈
+- ✅ 历史任务管理
+- ✅ 隐私保护模式
+
+### 可观测性
+- ✅ 完整的指标体系
+- ✅ 执行日志记录
+- ✅ 性能报告生成
+- ✅ 安全事件追踪
+
+## 代码统计
+
+| 模块 | 核心文件 | 代码行数 | 职责 |
+|------|---------|---------|------|
+| app | agent.py | 1503 | 主控制逻辑 |
+| executor | sandbox_runner.py | 493 | 代码执行 |
+| safety | rule_checker.py | 334 | 安全检查 |
+| executor | path_guard.py | 174 | 路径守卫 |
+| tests | 6个测试文件 | ~800 | 质量保证 |
+| docs | 10个文档 | ~15000字 | 项目文档 |
+
+## 开发规范
+
+详见 `RULES.md` 文档，包括：
+- 目录组织规范
+- 代码命名规范
+- 测试编写规范
+- 文档管理规范
+- 安全开发规范
+- 构建发布流程
+
+## 未来规划
+
+- [ ] 支持更多编程语言
+- [ ] 增强LLM推理能力
+- [ ] 优化历史复用算法
+- [ ] 添加Web界面
+- [ ] 支持团队协作
+- [ ] 插件系统
+
+---
+
+**最后更新**: 2026-02-27  
+**项目状态**: 活跃开发中  
+**维护者**: LocalAgent Team
+