LocalAgent/RULES.md

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. 构建可执行文件

python build.py

2. 输出位置

• 构建文件：build/LocalAgent/
• 可执行文件：dist/LocalAgent/LocalAgent.exe

3. 工作空间

• 可执行文件自带 workspace/ 目录
• 首次运行自动初始化工作空间结构

注意事项

1. 不要在根目录堆积文件，保持根目录整洁
2. 不要将测试代码放在业务模块中
3. 不要将临时文档提交到版本控制
4. 务必遵循安全规范，所有代码执行必须经过审查
5. 务必为核心功能编写测试
6. 务必更新文档与代码保持同步

版本历史

• 2026-02-27: 初始版本，规范项目结构和开发流程