LocalAgent/docs/PROJECT_STRUCTURE.md

# 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