DEVELOPMENT.md

开发规范与最佳实践

🎯 开发原则

1. 以性能为中心: 优化代码执行效率，减少资源消耗
2. 修改最少代码原则: 在保证功能的前提下，最小化代码变更
3. 模块化设计: 保持各模块间的松耦合
4. 异常处理: 完善的错误处理和日志记录

📁 目录结构规范

项目根目录/
├── 📄 XCometAgent.py          # 主入口文件
├── 📄 README.md               # 项目概述
├── 📄 CLAUDE.md              # 详细技术文档
├── 📄 EXAMPLES.md            # 使用示例
├── 📄 CHANGELOG.md           # 版本更新记录
├── 📄 requirements.txt       # 依赖管理
│
├── 🔧 Core/                  # 核心功能
│   ├── 📄 Agent.py          # 基础Agent类
│   ├── 📄 Tool_Use.py       # 工具调用系统
│   ├── 📄 BaseLLMCall.py    # LLM调用接口
│   ├── 📄 .env              # 核心环境变量
│   └── 📄 __init__.py       # 包初始化
│
├── 📦 Modules/               # 核心模块
│   ├── 📁 TaskGraph/        # 任务图处理
│   ├── 📁 Planner/          # 任务规划
│   ├── 📁 Context/          # 上下文管理
│   ├── 📁 Memory/           # 内存系统
│   └── 📁 AgentRouter/      # 智能路由
│
├── 🤖 Agents/               # 专用代理
│   ├── 📁 XWebSearchAgent/  # 网络搜索
│   ├── 📁 XLifeGetAgent/    # 生活服务
│   └── 📁 XFileOperatorAgent/ # 文件操作
│
├── 🔌 Plugin/               # 插件系统
├── 🔨 Framework/            # 框架组件
├── 📝 Prompts/              # 提示模板
├── 📋 TaskBox/              # 任务管理
└── 🔄 CometLoop/            # 循环处理

🐍 Python代码规范

导入规范

# 标准库导入
import os
import sys
from typing import List, Dict, Any

# 第三方库导入
import asyncio
from pathlib import Path

# 项目内模块导入（以项目根目录为基准）
from Core.Agent import AgentBase
from Modules.TaskGraph.graph import TaskGraph
from Agents.XWebSearchAgent.XWebSearchAgent import XWebSearchAgent

异常处理规范

def some_function():
    try:
        # 业务逻辑
        result = risky_operation()
        return result
    except SpecificException as e:
        # 记录并处理特定异常
        logger.error(f"具体错误: {e}")
        return None
    except Exception as e:
        # 记录并处理其他异常
        logger.error(f"未预期错误: {e}")
        raise
    finally:
        # 清理资源
        cleanup()

命名规范

• 类名: PascalCase (如 MetaAgent, TaskGraph)
• 函数名: snake_case (如 get_agent_info, run_task)
• 变量名: snake_case (如 user_query, agent_config)
• 常量名: UPPER_SNAKE_CASE (如 MAX_RETRIES, DEFAULT_TIMEOUT)

🔧 配置管理

环境变量

• 核心配置: Core/.env
• 框架配置: Framework/*/.env
• Agent配置: Agents/*/Agent.json
• MCP配置: */mcp.json

敏感信息处理

# ✅ 正确做法
from dotenv import load_dotenv
load_dotenv()  # 加载.env文件

# ❌ 错误做法
API_KEY = "hardcoded_key_123"  # 绝不在代码中硬编码

🧪 测试规范

单元测试

def test_agent_creation():
    """测试Agent创建功能"""
    from Core.Agent import AgentBase
    agent = AgentBase()
    assert agent is not None
    print("✅ Agent创建测试通过")

📋 开发流程

1. 功能开发:

   • 创建新模块/功能
   • 编写必要的测试
   • 更新相关文档

2. 代码审查:

   • 检查导入规范
   • 验证异常处理
   • 确认性能优化

3. 测试验证:

   • 运行单元测试
   • 执行集成测试
   • 验证系统完整性

🚀 部署建议

1. 依赖管理: 使用requirements.txt
2. 环境隔离: 使用虚拟环境
3. 配置管理: 使用环境变量和配置文件
4. 监控日志: 实现完善的日志记录

📚 相关文档

• README.md: 项目概述和快速开始
• CLAUDE.md: 详细技术架构