refactor: migrate services package under pure_auto_codeql

Move LLM/LSP/path-selection and related services into
pure_auto_codeql.services with nested top-level re-export shims.
Resolve repo-root paths via get_repo_root for MCP and language config.

Author: bx33661

docs/package_architecture.md

@@ -17,9 +17,9 @@ migration window.
 | `prompts` | `pure_auto_codeql.prompts` | Migrated (top-level re-export shim kept; `.md` assets co-located) |
 | `utils` | `pure_auto_codeql.utils` | Migrated (top-level re-export shim kept) |
 | `tools` | `pure_auto_codeql.tools` | Migrated Python modules (top-level re-export shim kept; `tools/mcp_ripgrep` stays at repo root) |
+| `services` | `pure_auto_codeql.services` | Migrated (top-level re-export shim kept) |
 | `api` | `pure_auto_codeql.api` | Planned staged migration |
 | `core` | `pure_auto_codeql.core` | Planned staged migration |
-| `services` | `pure_auto_codeql.services` | Planned staged migration |
 
 ## Compatibility Surface
 

pure_auto_codeql/services/__init__.py

@@ -0,0 +1,29 @@
+"""服务层模块
+
+提供各种业务服务，包括LLM服务、LSP服务、分析服务等。
+"""
+
+from .lsp_service import CodeQLLSPService
+from .codeql_prompt import build_placeholder_map, apply_placeholders
+from .codeql_syntax import CodeQLSyntaxSession
+from .codeql_execution import CodeQLExecutionService, CodeQLExecutionResult
+from .llm_service import MultiAgentAnalyzer, AgentResult
+from .language_detector import LanguageDetector
+from .knowledge_base import (
+    KnowledgeBaseFactory,
+    PythonKnowledgeBase,
+)
+
+__all__ = [
+    "CodeQLLSPService",
+    "KnowledgeBaseFactory",
+    "PythonKnowledgeBase",
+    "build_placeholder_map",
+    "apply_placeholders",
+    "CodeQLSyntaxSession",
+    "CodeQLExecutionService",
+    "CodeQLExecutionResult",
+    "MultiAgentAnalyzer",
+    "AgentResult",
+    "LanguageDetector"
+]

pure_auto_codeql/services/agent_mcp_config.py

@@ -0,0 +1,184 @@
+from pathlib import Path
+from typing import Dict, Optional, TYPE_CHECKING
+
+from langchain_mcp_adapters.client import MultiServerMCPClient  # noqa: F401  # 预留给未来可能的直接使用
+
+from utils.logger import get_logger
+from .mcp_language_config import MCPLanguageConfigService
+from pure_auto_codeql.paths import prompts_dir
+from pure_auto_codeql.paths import get_repo_root
+
+if TYPE_CHECKING:
+    from pure_auto_codeql.agents.cve_analysis_agent import CVEAnalysisAgent as _CVEAnalysisAgent
+    from pure_auto_codeql.agents.unified_sink_path_agent import UnifiedSinkPathAgent as _UnifiedSinkPathAgent
+    from pure_auto_codeql.agents.unified_source_analysis_agent import UnifiedSourceAnalysisAgent as _UnifiedSourceAnalysisAgent
+    from pure_auto_codeql.agents.path_analysis_agent import PathAnalysisAgent as _PathAnalysisAgent
+    from pure_auto_codeql.agents.codeql_gen_agents.codeql_gen_agent import CodeQLGenAgent as _CodeQLGenAgent
+    from pure_auto_codeql.agents.codeql_gen_agents.codeql_error_agent import CodeQLErrorAgent as _CodeQLErrorAgent
+    from pure_auto_codeql.agents.codeql_gen_agents.codeql_fix_inplace_agent import (
+        CodeQLFixInplaceAgent as _CodeQLFixInplaceAgent,
+    )
+    from pure_auto_codeql.agents.codeql_gen_agents.codeql_breakpoint_detect_agent import (
+        CodeQLBreakpointAgent as _CodeQLBreakpointAgent,
+    )
+
+
+logger = get_logger(__name__)
+
+
+AGENT_TYPES: Dict[str, str] = {
+    "cve_analysis": "pure_auto_codeql.agents.cve_analysis_agent.CVEAnalysisAgent",
+    "unified_sink_path": "pure_auto_codeql.agents.unified_sink_path_agent.UnifiedSinkPathAgent",
+    "unified_source_analysis": "pure_auto_codeql.agents.unified_source_analysis_agent.UnifiedSourceAnalysisAgent",
+    "path_analysis": "pure_auto_codeql.agents.path_analysis_agent.PathAnalysisAgent",
+    "codeql_gen": "pure_auto_codeql.agents.codeql_gen_agents.codeql_gen_agent.CodeQLGenAgent",
+    "codeql_error": "pure_auto_codeql.agents.codeql_gen_agents.codeql_error_agent.CodeQLErrorAgent",
+    "codeql_fix_inplace": "pure_auto_codeql.agents.codeql_gen_agents.codeql_fix_inplace_agent.CodeQLFixInplaceAgent",
+    "codeql_breakpoint_detect": "pure_auto_codeql.agents.codeql_gen_agents.codeql_breakpoint_detect_agent.CodeQLBreakpointAgent",
+    "template_refinement": "pure_auto_codeql.agents.codeql_gen_agents.template_refinement_agent.TemplateRefinementAgent",
+    "sink_verification": "pure_auto_codeql.agents.sink_verification_agent.SinkVerificationAgent",
+    "source_verification": "pure_auto_codeql.agents.source_verification_agent.SourceVerificationAgent",
+}
+
+AGENT_MCP_PROFILES: Dict[str, list[str]] = {
+    "cve_analysis": [],
+    "unified_sink_path": ["filesystem", "ripgrep", "language-server"],
+    # "unified_source_analysis": ["language-server"],
+    "unified_source_analysis": ["tree_sitter", "language-server", "filesystem"],
+    "source_analysis": ["tree_sitter", "language-server", "filesystem"],
+    "path_analysis": ["tree_sitter", "ripgrep"],
+    "codeql_gen": [],
+    "codeql_generation": ["filesystem", "ripgrep", "language-server"],
+    "codeql_error": ["filesystem", "ripgrep", "language-server"],
+    "codeql_fix_inplace": ["filesystem", "ripgrep", "language-server"],
+    "codeql_breakpoint_detect": ["tree_sitter", "ripgrep"],
+    "template_refinement": ["filesystem"],
+    "source_sink_fallback": ["ripgrep"],  # 需要 ripgrep 以支持 lsplookup 工具
+    "sink_verification": ["ripgrep", "language-server"],  # 需要 ripgrep 和 LSP 以支持 LSPFunctionLookupTool
+    "source_verification": ["ripgrep", "language-server"],  # 需要 ripgrep 和 LSP 以支持 LSPFunctionLookupTool
+    "default": [],
+}
+
+
+class AgentMCPConfigService:
+    """
+    Agent 级别的 MCP 配置管理服务。
+    """
+
+    def __init__(self, language_config_service: Optional[MCPLanguageConfigService] = None):
+        """
+        初始化配置服务。
+        """
+        self._language_config_service = language_config_service or MCPLanguageConfigService()
+
+    def get_config_for_agent(
+        self,
+        agent_type: str,
+        language: Optional[str] = None,
+        workspace_path: Optional[str] = None,
+    ) -> Dict[str, Dict]:
+        # 获取Agent对应的MCP配置文件，如果不存在则使用默认配置
+        profile = AGENT_MCP_PROFILES.get(agent_type, AGENT_MCP_PROFILES["default"])
+
+        # 针对 Source 分析类 Agent,根据语言调整 MCP 组合策略
+        normalized_language = (language or "").lower()
+        if agent_type in {"unified_source_analysis", "source_analysis"} and normalized_language:
+            if normalized_language == "java":
+                # Java: 使用 ripgrep + language-server + filesystem
+                profile = ["ripgrep", "language-server"]
+            elif normalized_language == "python":
+                # Python: 使用 tree_sitter + language-server + filesystem
+                profile = ["language-server", "ripgrep", "tree_sitter"]
+            elif normalized_language in {"c", "cpp", "c++"}:
+                # C/C++: 使用 tree_sitter + filesystem
+                profile = ["tree_sitter", "ripgrep"]
+
+        # 构建完整的MCP服务器配置
+        mcp_servers: Dict[str, Dict] = {}
+
+        # 添加文件系统MCP
+        if "filesystem" in profile:
+            if not workspace_path:
+                logger.warning("⚠️  filesystem MCP 需要 workspace_path 参数")
+            else:
+                workspace_path_str = str(workspace_path).replace("source_code", "")
+                workspace_path_obj = Path(workspace_path_str)
+                parents = workspace_path_obj.parents
+                repo_root = parents[1] if len(parents) > 1 else workspace_path_obj.parent
+
+                # 添加对于错误整理Agent的MCP配置
+                if agent_type == "template_refinement":
+                    prompts_path = prompts_dir()
+                    mcp_servers["filesystem"] = {
+                        "command": "npx",
+                        "args": [
+                            "-y",
+                            "@modelcontextprotocol/server-filesystem",
+                            str(prompts_path),
+                        ],
+                        "transport": "stdio",
+                    }
+                else:
+                    temp_codeql_path = repo_root / "temp" / "codeql_temp"
+                    prompts_path = prompts_dir()
+                    mcp_servers["filesystem"] = {
+                        "command": "npx",
+                        "args": [
+                            "-y",
+                            "@modelcontextprotocol/server-filesystem",
+                            workspace_path_str,
+                            str(temp_codeql_path),
+                            str(prompts_path),
+                        ],
+                        "transport": "stdio",
+                    }
+
+        # 添加ripgrep MCP
+        if "ripgrep" in profile:
+            mcp_servers["ripgrep"] = {
+                "command": "node",
+                "args": [
+                    str(
+                        get_repo_root()
+                        / "tools"
+                        / "mcp_ripgrep"
+                        / "dist"
+                        / "index.js"
+                    )
+                ],
+                "transport": "stdio",
+            }
+
+        # 添加 tree_sitter MCP
+        if "tree_sitter" in profile:
+            if not workspace_path:
+                logger.warning("⚠️  tree_sitter MCP 需要 workspace_path 参数")
+            else:
+                mcp_servers["tree_sitter"] = {
+                    "command": "uv",
+                    "args": [
+                        "--directory",
+                        str(workspace_path),
+                        "run",
+                        "-m",
+                        "mcp_server_tree_sitter.server",
+                    ],
+                    "transport": "stdio",
+                }
+
+        # 添加语言服务器MCP
+        if "language-server" in profile and language and workspace_path:
+            try:
+                language_config = self._language_config_service
+                if language_config.is_language_supported(language):
+                    lsp_config = language_config.get_language_server_config(language, workspace_path)
+                    mcp_servers["language-server"] = lsp_config
+                    logger.info(f"✓ 已添加 {language} LSP MCP 配置")
+                else:
+                    logger.info(f"ℹ️  语言 {language} 不支持 LSP MCP")
+            except Exception as e:  # pragma: no cover - 防御性日志记录
+                logger.warning(f"⚠️  LSP MCP 配置失败,继续使用基础 MCP: {e}")
+        elif "language-server" in profile:
+            logger.warning("⚠️  language-server MCP 需要 language 和 workspace_path 参数")
+
+        return mcp_servers

pure_auto_codeql/services/codeql_execution.py

@@ -0,0 +1,168 @@
+"""CodeQL 查询执行与结果整理服务。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional
+
+from utils.sarif_config import get_sarif2json_config
+from utils.sarif_utils import write_paths_json
+
+
+@dataclass
+class CodeQLExecutionResult:
+    success: bool
+    output: str
+    sarif_path: Optional[str] = None
+    json_path: Optional[str] = None
+    paths_count: Optional[int] = None
+    result_file: Optional[str] = None
+    preview: Optional[str] = None
+    
+    @property
+    def has_results(self) -> bool:
+        """检测查询结果是否为空。"""
+        # 检查paths_count（analyze模式）
+        if self.paths_count is not None:
+            return self.paths_count > 0
+        
+        # 检查output内容（run模式）
+        if self.output and self.output.strip():
+            # 检查常见的空结果模式
+            empty_indicators = [
+                'No results.',
+                'No results found',
+                '0 results',
+                'Empty result set',
+                '查询结果为空',
+                '未找到结果'
+            ]
+            
+            output_lower = self.output.lower()
+            for indicator in empty_indicators:
+                if indicator.lower() in output_lower:
+                    return False
+            
+            # 检查是否有实际的数据行（非表头、非空行）
+            lines = [line.strip() for line in self.output.splitlines() if line.strip()]
+            if len(lines) <= 2:  # 只有表头或很少的行
+                return False
+                
+            # 检查是否有数据行（包含实际数据）
+            data_lines = [line for line in lines if not line.startswith('|') or '---' not in line]
+            return len(data_lines) > 1
+        
+        return False
+
+
+class CodeQLExecutionService:
+    """包装 CodeQL CLI 调用及 SARIF 后处理。"""
+
+    def __init__(
+        self,
+        *,
+        database_path: str,
+        language: str,
+        execute_fn: Callable[[str, str, Optional[str]], dict],
+        decode_fn: Optional[Callable[[str, str, Optional[str]], dict]] = None,
+    ) -> None:
+        self._database_path = database_path
+        self._language = language
+        self._execute_fn = execute_fn
+        self._decode_fn = decode_fn
+
+    def execute(self, query: str, exec_mode: str = "analyze") -> CodeQLExecutionResult:
+        mode = (exec_mode or "analyze").lower()
+
+        if mode == "run" and self._decode_fn:
+            return self._execute_run_mode(query)
+
+        return self._execute_analyze_mode(query)
+
+    def _execute_analyze_mode(self, query: str) -> CodeQLExecutionResult:
+        try:
+            raw_result = self._execute_fn(query, self._database_path, self._language)
+        except Exception as exc:  # pylint: disable=broad-except
+            return CodeQLExecutionResult(success=False, output=f"Execution failed: {exc}")
+
+        if not raw_result.get("success"):
+            return CodeQLExecutionResult(
+                success=False,
+                output=raw_result.get("output", "Unknown execution error"),
+            )
+
+        sarif_path = raw_result.get("sarif_path")
+        json_path: Optional[str] = None
+        paths_count: Optional[int] = None
+
+        if sarif_path:
+            try:
+                config = get_sarif2json_config()
+                json_file = Path(sarif_path).with_suffix(".json")
+                paths_count = write_paths_json(
+                    sarif_path,
+                    str(json_file),
+                    max_results=config.max_results,
+                    threadflow_index=config.threadflow_index,
+                    rule_filter=config.rule_filter,
+                    relative_to=None,
+                )
+                json_path = str(json_file)
+            except Exception:
+                # SARIF 转换失败时继续返回原结果
+                json_path = None
+                paths_count = None
+
+        result = CodeQLExecutionResult(
+            success=True,
+            output=raw_result.get("output", ""),
+            sarif_path=sarif_path,
+            json_path=json_path,
+            paths_count=paths_count,
+        )
+        
+        # 检测空结果并添加提示
+        result = self._handle_empty_results(result)
+        
+        return result
+
+    def _handle_empty_results(self, result: CodeQLExecutionResult) -> CodeQLExecutionResult:
+        """处理空结果检测和用户交互提示。"""
+        if not result.has_results:
+            result.output = f"⚠️ 查询执行成功，但未找到匹配结果。\n\n原始输出:\n{result.output}\n\n💡 请检查查询条件或选择是否继续优化查询。"
+        return result
+
+    def _execute_run_mode(self, query: str) -> CodeQLExecutionResult:
+        try:
+            raw_result = self._decode_fn(query, self._database_path, self._language)  # type: ignore[misc]
+        except Exception as exc:  # pylint: disable=broad-except
+            return CodeQLExecutionResult(success=False, output=f"Execution failed: {exc}")
+
+        if not raw_result.get("success"):
+            return CodeQLExecutionResult(
+                success=False,
+                output=raw_result.get("output", "Unknown execution error"),
+            )
+
+        full_text = raw_result.get("output", "") or ""
+        result_file = raw_result.get("result_file")
+        lines = full_text.splitlines()
+        preview = "\n".join(lines[:40]).strip()
+        if len(lines) > 40:
+            preview = f"{preview}\n..."
+
+        result = CodeQLExecutionResult(
+            success=True,
+            output=full_text,
+            result_file=result_file,
+            preview=preview if preview else None,
+        )
+        
+        # 检测空结果并添加提示
+        result = self._handle_empty_results(result)
+        
+        return result
+
+
+__all__ = ["CodeQLExecutionService", "CodeQLExecutionResult"]