refactor: use canonical imports inside pure_auto_codeql

bx33661 · bx33661 · commit b72c03b6b9cb · 2026-07-21T10:56:26.000+08:00
Rewrite production imports under pure_auto_codeql/ (and examples/scripts)
to pure_auto_codeql.* so the package no longer depends on top-level
shims at runtime. Legacy flat imports remain available for external
callers; document the internal import convention.
diff --git a/docs/package_architecture.md b/docs/package_architecture.md
@@ -66,6 +66,15 @@ use `from config import ...`. The root-level `config.py` file is only a legacy
 script shim for `python config.py ...`; normal `import config` resolves to the
 `config/` package in this repository.
 
+
+## Internal Import Convention
+
+Runtime code under `pure_auto_codeql/` should import siblings via the
+canonical namespace (for example `from pure_auto_codeql.utils.case import ...`),
+not the temporary top-level shim packages. Top-level `utils` / `services` /
+`api` / ... shims remain only for external and legacy callers during the
+migration window.
+
 ## Verification
 
 Run these checks before committing package-architecture changes:
diff --git a/examples/agent_with_extra_files.py b/examples/agent_with_extra_files.py
@@ -5,8 +5,8 @@
 """
 
 from typing import Any
-from core.context import AnalysisContext
-from core.pipeline import AnalysisStep
+from pure_auto_codeql.core.context import AnalysisContext
+from pure_auto_codeql.core.pipeline import AnalysisStep
 
 
 class EnhancedCVEAnalysisStep(AnalysisStep):
@@ -217,8 +217,8 @@ def _determine_analysis_strategy(
 
 async def demo_enhanced_analysis():
     """演示增强分析流程"""
-    from utils.case import resolve_case, discover_cve_assets
-    from core.context import AnalysisContext
+    from pure_auto_codeql.utils.case import resolve_case, discover_cve_assets
+    from pure_auto_codeql.core.context import AnalysisContext
     
     print("\n" + "=" * 80)
     print("增强型 Agent 演示 - 使用额外输入文件")
diff --git a/examples/java_project_import_demo.py b/examples/java_project_import_demo.py
@@ -7,7 +7,7 @@
 
 from pathlib import Path
 
-from utils.project_importer import import_project
+from pure_auto_codeql.utils.project_importer import import_project
 
 
 def demo_java_import():
diff --git a/examples/path_selection_demo.py b/examples/path_selection_demo.py
@@ -13,7 +13,7 @@
 from pathlib import Path
 from typing import Any, Dict
 
-from services.path_selection import PathSelectionService
+from pure_auto_codeql.services.path_selection import PathSelectionService
 from pure_auto_codeql.configuration import get_chat_config
 
 
diff --git a/examples/simple_extra_files_demo.py b/examples/simple_extra_files_demo.py
@@ -5,7 +5,7 @@
 """
 
 from pathlib import Path
-from utils.case import resolve_case, discover_cve_assets
+from pure_auto_codeql.utils.case import resolve_case, discover_cve_assets
 
 
 def demo_basic():
diff --git a/examples/use_extra_input_files.py b/examples/use_extra_input_files.py
@@ -5,7 +5,7 @@
 """
 
 from pathlib import Path
-from utils.case import resolve_case, discover_cve_assets
+from pure_auto_codeql.utils.case import resolve_case, discover_cve_assets
 
 
 def example_basic_usage():
diff --git a/pure_auto_codeql/agents/codeql_gen_agents/codeql_breakpoint_detect_agent.py b/pure_auto_codeql/agents/codeql_gen_agents/codeql_breakpoint_detect_agent.py
@@ -7,8 +7,8 @@
 from pure_auto_codeql.paths import prompts_dir
 
 if TYPE_CHECKING:
-    from utils.io import AgentResult
-from services.llm_service import MultiAgentAnalyzer
+    from pure_auto_codeql.utils.io import AgentResult
+from pure_auto_codeql.services.llm_service import MultiAgentAnalyzer
 
 
 class CodeQLBreakpointAgent:
diff --git a/pure_auto_codeql/agents/cve_analysis_agent.py b/pure_auto_codeql/agents/cve_analysis_agent.py
@@ -13,7 +13,7 @@ class AgentResult:
     class MultiAgentAnalyzer:
         pass
 
-from utils.io import read_json_text
+from pure_auto_codeql.utils.io import read_json_text
 
 
 class CVEAnalysisAgent:
diff --git a/pure_auto_codeql/agents/path_analysis_agent.py b/pure_auto_codeql/agents/path_analysis_agent.py
@@ -14,7 +14,7 @@ class AgentResult:
     class MultiAgentAnalyzer:
         pass
 
-from prompts.path_analysis_prompts import build_path_analysis_prompt
+from pure_auto_codeql.prompts.path_analysis_prompts import build_path_analysis_prompt
 
 logger = logging.getLogger(__name__)
 
diff --git a/pure_auto_codeql/agents/sink_verification_agent.py b/pure_auto_codeql/agents/sink_verification_agent.py
@@ -9,24 +9,24 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple, Callable
 
-from services import (
+from pure_auto_codeql.services import (
     build_placeholder_map,
     apply_placeholders,
     CodeQLLSPService,
 )
-from utils.codeql import (
+from pure_auto_codeql.utils.codeql import (
     execute_codeql_query,
     is_empty_result,
     create_temporary_qlpack,
 )
-from utils.logger import get_logger
-from prompts.verification_prompt_manager import (
+from pure_auto_codeql.utils.logger import get_logger
+from pure_auto_codeql.prompts.verification_prompt_manager import (
     load_verification_template,
     build_verification_requirement,
 )
 
 if TYPE_CHECKING:
-    from services.llm_service import MultiAgentAnalyzer
+    from pure_auto_codeql.services.llm_service import MultiAgentAnalyzer
 
 logger = get_logger(__name__)
 
diff --git a/pure_auto_codeql/agents/source_verification_agent.py b/pure_auto_codeql/agents/source_verification_agent.py
@@ -9,24 +9,24 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple, Callable
 
-from services import (
+from pure_auto_codeql.services import (
     build_placeholder_map,
     apply_placeholders,
     CodeQLLSPService,
 )
-from utils.codeql import (
+from pure_auto_codeql.utils.codeql import (
     execute_codeql_query,
     is_empty_result,
     create_temporary_qlpack,
 )
-from utils.logger import get_logger
-from prompts.verification_prompt_manager import (
+from pure_auto_codeql.utils.logger import get_logger
+from pure_auto_codeql.prompts.verification_prompt_manager import (
     load_verification_template,
     build_verification_requirement,
 )
 
 if TYPE_CHECKING:
-    from services.llm_service import MultiAgentAnalyzer
+    from pure_auto_codeql.services.llm_service import MultiAgentAnalyzer
 
 logger = get_logger(__name__)
 
diff --git a/pure_auto_codeql/agents/unified_sink_path_agent.py b/pure_auto_codeql/agents/unified_sink_path_agent.py
@@ -20,7 +20,7 @@ class AgentResult:
     class MultiAgentAnalyzer:
         pass
 
-from prompts import build_sink_prompt
+from pure_auto_codeql.prompts import build_sink_prompt
 
 
 class UnifiedSinkPathAgent:
diff --git a/pure_auto_codeql/agents/unified_source_analysis_agent.py b/pure_auto_codeql/agents/unified_source_analysis_agent.py
@@ -17,8 +17,8 @@ class AgentResult:
     class MultiAgentAnalyzer:
         pass
 
-from tools.codeql_compose import CodeQLComposeTool
-from prompts.source_prompts import (
+from pure_auto_codeql.tools.codeql_compose import CodeQLComposeTool
+from pure_auto_codeql.prompts.source_prompts import (
     build_source_analysis_with_sink_prompt,
     build_source_analysis_with_codeql_prompt
 )
diff --git a/pure_auto_codeql/api/projects_routes.py b/pure_auto_codeql/api/projects_routes.py
@@ -25,7 +25,7 @@
     import_project_for_workflow,
     validate_project_import_request,
 )
-from utils.case import (
+from pure_auto_codeql.utils.case import (
     CasePaths,
     discover_cve_assets,
     resolve_case,
diff --git a/pure_auto_codeql/api/task_manager.py b/pure_auto_codeql/api/task_manager.py
@@ -5,8 +5,8 @@
 
 from .config import get_config
 from .models import TaskStatus, AnalysisTaskInfo, AnalysisResult
-from core.orchestrator import AnalysisOrchestrator
-from core.context import AnalysisConfig
+from pure_auto_codeql.core.orchestrator import AnalysisOrchestrator
+from pure_auto_codeql.core.context import AnalysisConfig
 
 
 class TaskManager:
diff --git a/pure_auto_codeql/application/analysis.py b/pure_auto_codeql/application/analysis.py
@@ -6,7 +6,7 @@
 from pathlib import Path
 from typing import Optional
 
-from utils.case import CasePaths, resolve_case
+from pure_auto_codeql.utils.case import CasePaths, resolve_case
 
 
 @dataclass(frozen=True)
diff --git a/pure_auto_codeql/application/project_import.py b/pure_auto_codeql/application/project_import.py
@@ -6,7 +6,7 @@
 from pathlib import Path
 from typing import Optional
 
-from utils.project_importer import (
+from pure_auto_codeql.utils.project_importer import (
     ProjectImportResult,
     import_project,
 )
diff --git a/pure_auto_codeql/cli/app.py b/pure_auto_codeql/cli/app.py
@@ -3,14 +3,14 @@
 import sys
 from pathlib import Path
 from typing import Optional, Sequence
-from core.orchestrator import AnalysisOrchestrator
-from core.context import AnalysisConfig
-from services.language_detector import LanguageDetector
-from utils.case import resolve_case, discover_cve_assets
-from utils.logger import setup_logging, get_logger, print_user_success, print_user_error, print_user_warning, print_user_info
+from pure_auto_codeql.core.orchestrator import AnalysisOrchestrator
+from pure_auto_codeql.core.context import AnalysisConfig
+from pure_auto_codeql.services.language_detector import LanguageDetector
+from pure_auto_codeql.utils.case import resolve_case, discover_cve_assets
+from pure_auto_codeql.utils.logger import setup_logging, get_logger, print_user_success, print_user_error, print_user_warning, print_user_info
 from pure_auto_codeql.configuration import list_available_providers, get_llm_config_by_provider, LLMRole, list_siliconflow_models, get_llm_config
-from tools.codeql_compose import CodeQLComposeTool
-from services.llm_service import MultiAgentAnalyzer
+from pure_auto_codeql.tools.codeql_compose import CodeQLComposeTool
+from pure_auto_codeql.services.llm_service import MultiAgentAnalyzer
 from pure_auto_codeql.application import (
     AnalysisValidationError,
     ProjectImportRequest,
@@ -19,7 +19,7 @@
     validate_analysis_case,
 )
 from pure_auto_codeql.agents.unified_source_analysis_agent import UnifiedSourceAnalysisAgent
-from utils.doctor import run_doctor
+from pure_auto_codeql.utils.doctor import run_doctor
 
 # 初始化日志系统
 setup_logging(level="INFO")
@@ -1020,7 +1020,7 @@ def _handle_doctor() -> None:
 
 def _handle_serve(args: argparse.Namespace) -> None:
     import uvicorn
-    from api.config import get_config
+    from pure_auto_codeql.api.config import get_config
 
     api_config = get_config()
     host = args.serve_host or api_config.host
diff --git a/pure_auto_codeql/core/context.py b/pure_auto_codeql/core/context.py
@@ -7,10 +7,10 @@
 from pathlib import Path
 from typing import Any, Dict, Optional
 
-from services.llm_service import AgentResult
-from services.path_selection import PathSelectionResult
-from utils.case import CasePaths, CveAssets
-from utils.intel import IntelBundle
+from pure_auto_codeql.services.llm_service import AgentResult
+from pure_auto_codeql.services.path_selection import PathSelectionResult
+from pure_auto_codeql.utils.case import CasePaths, CveAssets
+from pure_auto_codeql.utils.intel import IntelBundle
 
 
 @dataclass
diff --git a/pure_auto_codeql/core/orchestrator.py b/pure_auto_codeql/core/orchestrator.py
@@ -9,9 +9,9 @@
 
 from .context import AnalysisConfig, AnalysisContext, AnalysisResult
 from .pipeline import AnalysisPipeline
-from services.language_detector import LanguageDetector
-from utils.case import CveAssets, discover_cve_assets, resolve_case
-from utils.intel import IntelBundle, collect_intel
+from pure_auto_codeql.services.language_detector import LanguageDetector
+from pure_auto_codeql.utils.case import CveAssets, discover_cve_assets, resolve_case
+from pure_auto_codeql.utils.intel import IntelBundle, collect_intel
 
 logger = logging.getLogger(__name__)
 
diff --git a/pure_auto_codeql/core/pipeline.py b/pure_auto_codeql/core/pipeline.py
@@ -13,8 +13,8 @@
 from typing import Any, List, Optional
 
 from .context import AnalysisContext, AnalysisConfig, AnalysisResult
-from services.llm_service import AgentResult, MultiAgentAnalyzer
-from services.path_selection import PathSelectionService, PathSelectionResult
+from pure_auto_codeql.services.llm_service import AgentResult, MultiAgentAnalyzer
+from pure_auto_codeql.services.path_selection import PathSelectionService, PathSelectionResult
 
 
 def _get_llm_config_from_context(context: AnalysisContext, role) -> Any:
@@ -49,7 +49,7 @@ def _get_llm_config_from_context(context: AnalysisContext, role) -> Any:
 from pure_auto_codeql.agents.path_analysis_agent import PathAnalysisAgent
 from pure_auto_codeql.agents.sink_verification_agent import SinkVerificationAgent
 from pure_auto_codeql.agents.source_verification_agent import SourceVerificationAgent
-from tools.codeql_compose import CodeQLComposeTool
+from pure_auto_codeql.tools.codeql_compose import CodeQLComposeTool
 
 
 class AnalysisStep(ABC):
@@ -555,7 +555,7 @@ async def _consolidate_output_files(
     ) -> None:
         """整合所有输出文件到统一的文件夹结构。"""
         try:
-            from utils.io import write_analysis_output
+            from pure_auto_codeql.utils.io import write_analysis_output
 
             cve_id = getattr(context.cve_assets, "cve_id", None) if context.cve_assets else None
             case_tag = sanitize_tag(cve_id or context.case_id or "UNKNOWN")
@@ -670,7 +670,7 @@ async def _process_sarif_files(
             # 转换SARIF为JSON（在复制成功后）
             json_path: Optional[Path] = None
             try:
-                from utils.sarif_utils import sarif_to_all_paths
+                from pure_auto_codeql.utils.sarif_utils import sarif_to_all_paths
 
                 with open(target_sarif, 'r', encoding='utf-8') as f:
                     sarif_data = json.load(f)
diff --git a/pure_auto_codeql/services/agent_mcp_config.py b/pure_auto_codeql/services/agent_mcp_config.py
@@ -3,7 +3,7 @@
 
 from langchain_mcp_adapters.client import MultiServerMCPClient  # noqa: F401  # 预留给未来可能的直接使用
 
-from utils.logger import get_logger
+from pure_auto_codeql.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
diff --git a/pure_auto_codeql/services/codeql_execution.py b/pure_auto_codeql/services/codeql_execution.py
@@ -6,8 +6,8 @@
 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
+from pure_auto_codeql.utils.sarif_config import get_sarif2json_config
+from pure_auto_codeql.utils.sarif_utils import write_paths_json
 
 
 @dataclass
diff --git a/pure_auto_codeql/services/language_detector.py b/pure_auto_codeql/services/language_detector.py
@@ -6,7 +6,7 @@
 from pathlib import Path
 from typing import Dict, List
 
-from utils.case import CasePaths
+from pure_auto_codeql.utils.case import CasePaths
 
 
 class LanguageDetector:
diff --git a/pure_auto_codeql/services/llm_service.py b/pure_auto_codeql/services/llm_service.py
@@ -20,9 +20,9 @@
 from langchain_openai import ChatOpenAI
 
 from pure_auto_codeql.configuration import get_chat_config, LLMConfig, get_resilient_llm_config, LLMRole
-from utils.logger import get_logger
+from pure_auto_codeql.utils.logger import get_logger
 from .agent_mcp_config import AgentMCPConfigService
-from utils.mcp_schema_fixer import fix_mcp_tools_schemas
+from pure_auto_codeql.utils.mcp_schema_fixer import fix_mcp_tools_schemas
 
 
 class APIErrorClassifier:
@@ -886,7 +886,7 @@ async def initialize(
         # Add LSP Function Lookup Tool (uses ripgrep, no LSP engine needed)
         # 只有当配置包含 ripgrep 时才添加 LSPFunctionLookupTool（因为该工具依赖 ripgrep）
         if "ripgrep" in mcp_servers:
-            from tools.lsp_lookup_tool import LSPFunctionLookupTool
+            from pure_auto_codeql.tools.lsp_lookup_tool import LSPFunctionLookupTool
             # Pass language context to the tool if available
             lsp_lookup_tool = LSPFunctionLookupTool(default_language=self.language or "java")
             self.tools.append(lsp_lookup_tool)
diff --git a/pure_auto_codeql/services/lsp_service.py b/pure_auto_codeql/services/lsp_service.py
@@ -11,7 +11,7 @@
 from pathlib import Path
 from typing import Any, Dict
 
-from utils.logger import get_logger
+from pure_auto_codeql.utils.logger import get_logger
 
 logger = get_logger(__name__)
 
diff --git a/pure_auto_codeql/tools/codeql_compose.py b/pure_auto_codeql/tools/codeql_compose.py
diff --git a/pure_auto_codeql/tools/lsp_lookup_tool.py b/pure_auto_codeql/tools/lsp_lookup_tool.py
diff --git a/pure_auto_codeql/utils/intel.py b/pure_auto_codeql/utils/intel.py
diff --git a/pure_auto_codeql/utils/lsp_definition.py b/pure_auto_codeql/utils/lsp_definition.py
diff --git a/pure_auto_codeql/utils/project_importer.py b/pure_auto_codeql/utils/project_importer.py
diff --git a/scripts/smoke_lsp_syntax.py b/scripts/smoke_lsp_syntax.py
