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.
This commit is contained in:
Mimikko-zeus
172
RULES.md
Normal file
172
RULES.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# 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. 新功能开发
|
||||
1. 在对应模块目录下创建或修改代码
|
||||
2. 在 `tests/` 目录下编写对应测试
|
||||
3. 在 `docs/` 目录下更新相关文档
|
||||
4. 运行测试确保通过
|
||||
5. 更新 README.md（如需要）
|
||||
|
||||
### 2. Bug修复
|
||||
1. 在 `docs/` 目录下创建问题报告（P0/P1）
|
||||
2. 修复代码并添加回归测试
|
||||
3. 更新问题报告记录修复方案
|
||||
4. 验证修复效果
|
||||
|
||||
### 3. 代码提交
|
||||
- 提交前运行所有测试
|
||||
- 确保代码符合规范
|
||||
- 提交信息清晰描述改动
|
||||
|
||||
## 依赖管理
|
||||
|
||||
### 1. 添加依赖
|
||||
- 在 `requirements.txt` 中添加新依赖
|
||||
- 指定版本号确保可重现性
|
||||
- 更新文档说明依赖用途
|
||||
|
||||
### 2. 核心依赖
|
||||
- `textual`: TUI界面框架
|
||||
- `openai`: LLM API客户端
|
||||
- `scikit-learn`: 机器学习（意图分类、任务特征）
|
||||
- `pyinstaller`: 打包工具
|
||||
|
||||
## 构建和发布
|
||||
|
||||
### 1. 构建可执行文件
|
||||
```bash
|
||||
python build.py
|
||||
```
|
||||
|
||||
### 2. 输出位置
|
||||
- 构建文件：`build/LocalAgent/`
|
||||
- 可执行文件：`dist/LocalAgent/LocalAgent.exe`
|
||||
|
||||
### 3. 工作空间
|
||||
- 可执行文件自带 `workspace/` 目录
|
||||
- 首次运行自动初始化工作空间结构
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **不要**在根目录堆积文件，保持根目录整洁
|
||||
2. **不要**将测试代码放在业务模块中
|
||||
3. **不要**将临时文档提交到版本控制
|
||||
4. **务必**遵循安全规范，所有代码执行必须经过审查
|
||||
5. **务必**为核心功能编写测试
|
||||
6. **务必**更新文档与代码保持同步
|
||||
|
||||
## 版本历史
|
||||
|
||||
- 2026-02-27: 初始版本，规范项目结构和开发流程
|
||||
|
||||
Reference in New Issue
Block a user