full-stack-coding-assistant-agent 0.1.0__py3-none-any.whl

utils/agent_selector.py

@@ -0,0 +1,243 @@
+"""
+Agent 智能选择器 - 基于 LLM 分析用户需求，判断需要运行哪些 Agent
+"""
+
+import json
+import re
+from typing import Dict, Optional
+
+from model.model_router import ModelRouter
+from utils.logger import error, info, warning
+
+
+class AgentSelector:
+    """
+    智能选择需要运行的 Agent
+
+    使用轻量模型分析用户需求，输出需要运行的 Agent 列表。
+    同时处理依赖修正（如选中 frontend 时必须也选中 backend）。
+    """
+
+    # 所有可用的 Agent 类型
+    ALL_AGENTS = ["backend", "frontend", "test", "audit"]
+
+    # Agent 中文描述（用于 prompt）
+    AGENT_DESCRIPTIONS = {
+        "backend": "后端开发（生成/修改 API 接口、数据库、业务逻辑）",
+        "frontend": "前端开发（生成/修改 UI 组件、页面、样式）",
+        "test": "测试（生成/修改单元测试、集成测试、E2E 测试）",
+        "audit": "代码审计（检查代码质量、安全漏洞、性能问题）",
+    }
+
+    def __init__(self, model_router: ModelRouter):
+        """
+        初始化选择器
+
+        Args:
+            model_router: 模型路由器实例（使用轻量模型以节省成本）
+        """
+        self.model_router = model_router
+        # 使用轻量模型进行 Agent 选择
+        self.model = model_router.get_model_for_agent("frontend")  # frontend 用轻量模型
+
+    def select_agents(
+        self,
+        user_input: str,
+        existing_code_summary: str = "",
+    ) -> Dict:
+        """
+        分析用户需求，返回需要运行的 Agent 列表
+
+        Args:
+            user_input: 用户输入的需求描述
+            existing_code_summary: 已有代码的摘要（可选）
+
+        Returns:
+            字典 {
+                "agents": ["backend", "frontend"],
+                "reason": "需要修改登录接口和登录页面"
+            }
+        """
+        prompt = self._build_prompt(user_input, existing_code_summary)
+
+        try:
+            messages = [
+                {"role": "system", "content": self._get_system_prompt()},
+                {"role": "user", "content": prompt},
+            ]
+            response = self.model_router.chat(
+                messages=messages,
+                model=self.model,
+                temperature=0.1,  # 低温度，确保输出稳定
+                max_tokens=512,
+            )
+
+            result = self._parse_response(response["content"])
+            result = self._fix_dependencies(result)
+            return result
+
+        except Exception as e:
+            error(f"Agent 选择失败，使用默认全部 Agent: {e}")
+            return {
+                "agents": self.ALL_AGENTS,
+                "reason": f"LLM 调用失败，默认运行全部 Agent: {e}",
+            }
+
+    def _get_system_prompt(self) -> str:
+        """获取系统提示词"""
+        return """你是一个智能任务分析器。你的任务是分析用户的需求描述，判断需要运行哪些智能体（Agent）来完成任务。
+
+请以严格的 JSON 格式输出结果，不要输出任何 JSON 以外的内容。"""
+
+    def _build_prompt(self, user_input: str, existing_code_summary: str) -> str:
+        """构建用户提示词"""
+        agent_list = "\n".join(
+            f"- {name}: {desc}" for name, desc in self.AGENT_DESCRIPTIONS.items()
+        )
+
+        prompt = f"""分析以下用户需求，判断需要运行哪些智能体（Agent）：
+
+## 用户需求
+{user_input}
+
+## 可选 Agent
+{agent_list}
+
+## 输出要求
+请以以下 JSON 格式输出（只输出 JSON，不要有任何其他文字）：
+```json
+{{
+    "agents": ["backend", "frontend"],
+    "reason": "需要修改登录接口和登录页面"
+}}
+```
+
+## 选择规则
+1. 如果需求涉及后端逻辑、API、数据库，选择 backend
+2. 如果需求涉及前端页面、UI、交互，选择 frontend
+3. 如果需求明确提到测试、测试用例，选择 test
+4. 如果需求提到代码审查、安全检查、性能优化，选择 audit
+5. 如果不确定，选择全部 Agent
+6. frontend 依赖 backend 的输出（API 契约），如果选中 frontend 建议也选中 backend
+7. test 依赖 backend 和 frontend 的代码，如果选中 test 建议也选中 backend 和 frontend
+"""
+
+        if existing_code_summary:
+            prompt += f"\n## 已有代码摘要\n{existing_code_summary}\n"
+
+        prompt += "\n请只输出 JSON，不要有任何其他文字：\n"
+        return prompt
+
+    def _parse_response(self, response: str) -> Dict:
+        """
+        解析 LLM 返回的 JSON
+
+        Args:
+            response: LLM 返回的文本
+
+        Returns:
+            解析后的字典，失败时返回默认全部 Agent
+        """
+        if not response:
+            warning("Agent 选择器收到空响应，使用默认全部 Agent")
+            return {
+                "agents": self.ALL_AGENTS,
+                "reason": "LLM 返回空响应",
+            }
+
+        # 尝试提取 JSON（可能被 ```json ``` 包裹）
+        json_match = re.search(r"\{.*\}", response, re.DOTALL)
+        if not json_match:
+            warning(f"无法从响应中解析 JSON: {response[:200]}")
+            return {
+                "agents": self.ALL_AGENTS,
+                "reason": "无法解析 LLM 响应，默认运行全部 Agent",
+            }
+
+        try:
+            data = json.loads(json_match.group())
+
+            # 验证 agents 字段
+            agents = data.get("agents", [])
+            if not isinstance(agents, list) or len(agents) == 0:
+                warning(f"agents 字段无效: {agents}")
+                agents = self.ALL_AGENTS
+
+            # 过滤掉未知的 Agent 类型
+            agents = [a for a in agents if a in self.ALL_AGENTS]
+            if not agents:
+                agents = self.ALL_AGENTS
+
+            return {
+                "agents": agents,
+                "reason": data.get("reason", "用户需求涉及多个方面"),
+            }
+
+        except json.JSONDecodeError as e:
+            warning(f"JSON 解析失败: {e}, 响应: {response[:200]}")
+            return {
+                "agents": self.ALL_AGENTS,
+                "reason": "JSON 解析失败，默认运行全部 Agent",
+            }
+
+    def _fix_dependencies(self, result: Dict) -> Dict:
+        """
+        修正依赖关系：
+        - 如果选中 frontend 但未选中 backend，自动添加 backend
+        - 如果选中 test 但未选中 backend/frontend，自动添加
+        - 如果选中 audit 但未选中其他，也添加（audit 需要代码来审计）
+        """
+        agents = set(result["agents"])
+
+        # frontend 依赖 backend（需要 API 契约）
+        if "frontend" in agents and "backend" not in agents:
+            info("依赖修正: frontend 需要 backend，自动添加 backend")
+            agents.add("backend")
+
+        # test 依赖 backend 和 frontend
+        if "test" in agents:
+            if "backend" not in agents:
+                info("依赖修正: test 需要 backend，自动添加 backend")
+                agents.add("backend")
+            if "frontend" not in agents:
+                info("依赖修正: test 需要 frontend，自动添加 frontend")
+                agents.add("frontend")
+
+        # audit 需要代码来审计
+        if "audit" in agents and len(agents) == 1:
+            info("依赖修正: audit 需要代码来审计，自动添加 backend 和 frontend")
+            agents.add("backend")
+            agents.add("frontend")
+
+        result["agents"] = sorted(agents)
+        return result
+
+    @staticmethod
+    def format_existing_code_summary(output_dir: Optional[str]) -> str:
+        """
+        生成已有代码的简短摘要（用于注入到选择器的 prompt）
+
+        Args:
+            output_dir: 输出目录路径
+
+        Returns:
+            代码摘要字符串（文件名列表）
+        """
+        if not output_dir:
+            return ""
+
+        from pathlib import Path
+
+        path = Path(output_dir)
+        if not path.exists():
+            return ""
+
+        parts = []
+        for sub_dir in ["backend", "frontend", "tests"]:
+            target = path / sub_dir
+            if target.exists():
+                files = [f.name for f in target.iterdir() if f.is_file()]
+                if files:
+                    parts.append(f"{sub_dir}: {', '.join(files[:5])}")
+
+        return "\n".join(parts)

utils/config_validator.py

@@ -0,0 +1,143 @@
+"""
+配置验证工具 - 检查必需的环境变量和配置
+支持 Python 3.13+ 的类型检查
+"""
+
+import os
+import sys
+from typing import List, Tuple
+
+from utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class ConfigValidator:
+    """配置验证器"""
+
+    # 必需的环境变量
+    REQUIRED_ENVS = [
+        "TENCENT_API_KEY",
+    ]
+
+    # 可选的环境变量及其默认值
+    OPTIONAL_ENVS = {
+        "TENCENT_API_BASE": "https://api.hunyuan.cloud.tencent.com/hyllm/v1",
+        "SQLITE_DB_PATH": "./context.db",
+        "CODEBUDDY_CLI_PATH": "codebuddy",
+        "CODEBUDDY_TIMEOUT": "60",
+        "LOG_LEVEL": "INFO",
+        "DEBUG": "false",
+    }
+
+    # API Key 格式验证
+    API_KEY_PATTERNS = {
+        "TENCENT_API_KEY": r"^sk-",  # 腾讯混元 API Key 通常以 sk- 开头
+    }
+
+    @classmethod
+    def validate_envs(cls, exit_on_error: bool = True) -> Tuple[bool, List[str]]:
+        """
+        验证环境变量配置
+
+        Args:
+            exit_on_error: 验证失败时是否退出程序
+
+        Returns:
+            (是否通过验证, 错误信息列表)
+        """
+        errors = []
+        warnings = []
+
+        # 检查必需的环境变量
+        for env_name in cls.REQUIRED_ENVS:
+            value = os.getenv(env_name)
+            if not value or value == f"YOUR_{env_name}_HERE":
+                errors.append(f"缺少必需的环境变量: {env_name}")
+            else:
+                # 验证 API Key 格式
+                if env_name in cls.API_KEY_PATTERNS:
+                    import re
+
+                    pattern = cls.API_KEY_PATTERNS[env_name]
+                    if not re.match(pattern, value):
+                        warnings.append(f"{env_name} 格式可能不正确（期望以 sk- 开头）")
+
+        # 检查可选的环境变量
+        for env_name, default_value in cls.OPTIONAL_ENVS.items():
+            value = os.getenv(env_name)
+            if not value:
+                warnings.append(
+                    f"可选环境变量 {env_name} 未设置，将使用默认值: {default_value}"
+                )
+
+        # 输出结果
+        if warnings:
+            for warning in warnings:
+                logger.warning(warning)
+
+        if errors:
+            for error in errors:
+                logger.error(error)
+
+            if exit_on_error:
+                logger.error("配置验证失败，程序退出")
+                sys.exit(1)
+            return False, errors
+
+        logger.info("✅ 配置验证通过")
+        return True, []
+
+    @classmethod
+    def print_config_summary(cls):
+        """打印配置摘要"""
+        print("=" * 60)
+        print("配置摘要")
+        print("=" * 60)
+
+        # 必需的环境变量
+        print("\n【必需配置】")
+        for env_name in cls.REQUIRED_ENVS:
+            value = os.getenv(env_name)
+            if value and value != f"YOUR_{env_name}_HERE":
+                # 隐藏 API Key 的大部分内容
+                if "API_KEY" in env_name:
+                    masked_value = value[:10] + "*" * (len(value) - 10)
+                    print(f"  {env_name}: {masked_value}")
+                else:
+                    print(f"  {env_name}: {value}")
+            else:
+                print(f"  {env_name}: ❌ 未配置")
+
+        # 可选的环境变量
+        print("\n【可选配置】")
+        for env_name, default_value in cls.OPTIONAL_ENVS.items():
+            value = os.getenv(env_name, default_value)
+            print(f"  {env_name}: {value}")
+
+        print("=" * 60)
+
+
+def validate_config(exit_on_error: bool = True) -> bool:
+    """
+    便捷函数：验证配置
+
+    Args:
+        exit_on_error: 验证失败时是否退出程序
+
+    Returns:
+        是否通过验证
+    """
+    return ConfigValidator.validate_envs(exit_on_error)[0]
+
+
+def print_config():
+    """便捷函数：打印配置摘要"""
+    ConfigValidator.print_config_summary()
+
+
+if __name__ == "__main__":
+    # 单独运行此脚本时，打印配置摘要
+    print_config()
+    print("\n" + "=" * 60)
+    validate_config(exit_on_error=False)

utils/logger.py

@@ -0,0 +1,95 @@
+"""
+日志工具 - 提供统一的日志记录功能
+支持 Python 3.13+ 的最新日志特性
+"""
+
+import logging
+import os
+from typing import Optional
+
+
+def setup_logger(
+    name: str = "coding_agent",
+    log_level: Optional[str] = None,
+    log_file: Optional[str] = None,
+) -> logging.Logger:
+    """
+    设置日志记录器
+
+    Args:
+        name: 日志记录器名称
+        log_level: 日志级别 (DEBUG/INFO/WARNING/ERROR)
+        log_file: 日志文件路径
+
+    Returns:
+        配置好的 Logger 实例
+    """
+    # 从环境变量读取配置
+    if log_level is None:
+        log_level = os.getenv("LOG_LEVEL", "INFO")
+
+    if log_file is None:
+        log_file = os.getenv("LOG_FILE", "logs/app.log")
+
+    # 创建日志记录器
+    logger = logging.getLogger(name)
+    logger.setLevel(getattr(logging, log_level.upper()))
+
+    # 避免重复添加 handler
+    if logger.handlers:
+        return logger
+
+    # 创建日志目录
+    log_dir = os.path.dirname(log_file)
+    if log_dir and not os.path.exists(log_dir):
+        os.makedirs(log_dir, exist_ok=True)
+
+    # 日志格式（Python 3.13+ 优化）
+    formatter = logging.Formatter(
+        fmt="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    # 文件 Handler（带轮转）
+    file_handler = logging.FileHandler(log_file, encoding="utf-8")
+    file_handler.setLevel(getattr(logging, log_level.upper()))
+    file_handler.setFormatter(formatter)
+    logger.addHandler(file_handler)
+
+    # 控制台 Handler
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(getattr(logging, log_level.upper()))
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+
+    return logger
+
+
+# 全局日志记录器
+logger = setup_logger()
+
+
+def get_logger(name: str) -> logging.Logger:
+    """获取指定名称的日志记录器"""
+    return setup_logger(name)
+
+
+# 便捷函数
+def debug(msg: str, *args, **kwargs):
+    """记录 DEBUG 日志"""
+    logger.debug(msg, *args, **kwargs)
+
+
+def info(msg: str, *args, **kwargs):
+    """记录 INFO 日志"""
+    logger.info(msg, *args, **kwargs)
+
+
+def warning(msg: str, *args, **kwargs):
+    """记录 WARNING 日志"""
+    logger.warning(msg, *args, **kwargs)
+
+
+def error(msg: str, *args, **kwargs):
+    """记录 ERROR 日志"""
+    logger.error(msg, *args, **kwargs)