8a538bb950
- 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.
6.0 KiB
6.0 KiB
LocalAgent 项目规则
项目结构规范
目录组织
LocalAgent/
├── app/ # 核心应用模块
│ ├── agent.py # 主Agent逻辑
│ ├── exceptions.py # 自定义异常
│ ├── metrics_logger.py # 指标日志
│ └── privacy_config.py # 隐私配置
├── executor/ # 代码执行模块
│ ├── sandbox_runner.py # 沙箱执行器
│ ├── path_guard.py # 路径安全守卫
│ ├── backup_manager.py # 备份管理
│ └── execution_metrics.py # 执行指标
├── safety/ # 安全检查模块
│ ├── rule_checker.py # 规则检查器
│ ├── llm_reviewer.py # LLM安全审查
│ └── security_metrics.py # 安全指标
├── history/ # 历史记录模块
│ ├── manager.py # 历史管理器
│ ├── task_features.py # 任务特征提取
│ └── reuse_metrics.py # 复用指标
├── intent/ # 意图识别模块
│ ├── classifier.py # 意图分类器
│ └── labels.py # 意图标签定义
├── llm/ # LLM交互模块
│ ├── client.py # LLM客户端
│ ├── prompts.py # 提示词模板
│ └── config_metrics.py # 配置指标
├── ui/ # 用户界面模块
│ ├── chat_view.py # 聊天视图
│ ├── history_view.py # 历史视图
│ ├── settings_view.py # 设置视图
│ └── ... # 其他UI组件
├── tests/ # 测试代码（所有测试文件必须放在此目录）
│ ├── test_*.py # 单元测试
│ └── __init__.py
├── docs/ # 项目文档（所有文档必须放在此目录）
│ ├── PRD.md # 产品需求文档
│ ├── P0-*.md # P0级别问题修复报告
│ ├── P1-*.md # P1级别优化方案
│ └── ...
├── workspace/ # 运行时工作空间
│ ├── codes/ # 生成的代码
│ ├── input/ # 输入文件
│ ├── output/ # 输出文件
│ ├── logs/ # 执行日志
│ └── metrics/ # 运行指标
├── build/ # 构建输出目录
├── dist/ # 分发包目录
├── main.py # 程序入口
├── build.py # 构建脚本
├── requirements.txt # 依赖清单
├── README.md # 项目说明（保留在根目录）
└── RULES.md # 本规则文档
代码规范
1. 文件命名
- Python模块使用小写字母和下划线：
rule_checker.py - 测试文件必须以
test_开头：test_rule_checker.py - 类名使用大驼峰：
RuleChecker - 函数和变量使用小写下划线：
check_safety_rules()
2. 模块职责
- app/: 核心业务逻辑，Agent主流程控制
- executor/: 代码执行相关，包括沙箱、路径守卫、备份
- safety/: 安全检查，包括规则检查和LLM审查
- history/: 历史任务管理和代码复用
- intent/: 用户意图识别和分类
- llm/: LLM API交互和提示词管理
- ui/: 用户界面组件
- tests/: 所有单元测试和集成测试
3. 测试规范
- 所有测试文件必须放在
tests/目录下 - 测试文件命名：
test_<模块名>.py - 每个核心模块都应有对应的测试文件
- 测试覆盖关键功能和边界情况
4. 文档规范
- 所有项目文档必须放在
docs/目录下 - README.md 保留在根目录，作为项目入口文档
- 文档命名规范：
PRD.md: 产品需求文档P0-XX_<描述>.md: P0级别问题修复报告P1-XX_<描述>.md: P1级别优化方案- 其他技术文档使用描述性名称
安全规范
1. 路径安全
- 所有文件操作必须经过
PathGuard验证 - 禁止访问工作空间外的路径
- 禁止访问系统敏感目录
2. 代码执行安全
- 所有代码必须在沙箱环境中执行
- 执行前必须通过
RuleChecker和LLMReviewer双重审查 - 禁止执行危险操作（网络访问、系统调用等）
3. 隐私保护
- 敏感信息不得记录到日志
- 历史记录支持隐私模式
- 用户可配置数据保留策略
开发流程
1. 新功能开发
- 在对应模块目录下创建或修改代码
- 在
tests/目录下编写对应测试 - 在
docs/目录下更新相关文档 - 运行测试确保通过
- 更新 README.md（如需要）
2. Bug修复
- 在
docs/目录下创建问题报告（P0/P1） - 修复代码并添加回归测试
- 更新问题报告记录修复方案
- 验证修复效果
3. 代码提交
- 提交前运行所有测试
- 确保代码符合规范
- 提交信息清晰描述改动
依赖管理
1. 添加依赖
- 在
requirements.txt中添加新依赖 - 指定版本号确保可重现性
- 更新文档说明依赖用途
2. 核心依赖
textual: TUI界面框架openai: LLM API客户端scikit-learn: 机器学习（意图分类、任务特征）pyinstaller: 打包工具
构建和发布
1. 构建可执行文件
python build.py
2. 输出位置
- 构建文件：
build/LocalAgent/ - 可执行文件：
dist/LocalAgent/LocalAgent.exe
3. 工作空间
- 可执行文件自带
workspace/目录 - 首次运行自动初始化工作空间结构
注意事项
- 不要在根目录堆积文件，保持根目录整洁
- 不要将测试代码放在业务模块中
- 不要将临时文档提交到版本控制
- 务必遵循安全规范，所有代码执行必须经过审查
- 务必为核心功能编写测试
- 务必更新文档与代码保持同步
版本历史
- 2026-02-27: 初始版本，规范项目结构和开发流程