---
alwaysApply: true
---
# 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. **务必**更新文档与代码保持同步