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