refactor: clarify configuration import boundary

Author: bx33661

README.md

@@ -300,6 +300,16 @@ uv lock --check
 uv run python -m compileall -q Analyze.py api core services utils pure_auto_codeql tools
 ```
 
+## 配置导入约定
+
+运行时代码推荐从 `pure_auto_codeql.configuration` 导入 LLM 配置：
+
+```python
+from pure_auto_codeql.configuration import get_llm_config, LLMRole
+```
+
+历史脚本中的 `from config import ...` 和 `python config.py ...` 仍保持兼容。
+
 ## 安全说明
 
 - 不要提交真实密钥。`config/keys*.toml` 已被忽略，仓库只保留 `config/keys.example.toml` 模板。

config.py

@@ -1,19 +1,14 @@
-"""
-PureAutoCodeQL LLM 配置系统入口
-
-为了保持向后兼容，这个文件作为 config 模块的入口
-所有导入 config.py 的代码都会自动使用新的模块化系统
+"""Legacy script shim for the configuration CLI.
 
-新系统特性：
-- 模块化架构（config/ 文件夹）
-- keys.toml 统一配置
-- 零代码修改快速部署
+Runtime application code should import configuration helpers from
+`pure_auto_codeql.configuration`. The `config/` package remains available for
+legacy `from config import ...` imports, and this root-level file is kept so
+`python config.py ...` continues to launch the configuration CLI.
 """
 
-# 导入所有配置内容，保持向后兼容
 from config import *  # noqa: F401, F403
 
-# 命令行工具入口
 if __name__ == "__main__":
     from config.cli import main
+
     main()

config/MAIN_PROGRAM_INTEGRATION.md

@@ -5,15 +5,16 @@
 
 ## 验证范围
 
-本报告验证了项目主程序及关键模块是否正确使用了重构后的 `config/` 模块。
+本报告验证了项目主程序及关键模块是否正确使用了 canonical 配置入口
+`pure_auto_codeql.configuration`，并确认旧版 `config/` 模块兼容层仍可用。
 
 ## 验证结果
 
 ### ✅ 主程序 (Analyze.py)
 
 **导入内容:**
 ```python
-from config import (
+from pure_auto_codeql.configuration import (
     list_available_providers, 
     get_llm_config_by_provider, 
     LLMRole, 
@@ -23,15 +24,16 @@ from config import (
 ```
 
 **状态:** ✅ 完全兼容
-- 所有导入的函数和类都已在新的 `config/__init__.py` 中正确导出
+- 所有导入的函数和类都已通过 `pure_auto_codeql.configuration` 统一导出
+- 旧版 `from config import ...` 入口仍可用于历史脚本
 - `list_siliconflow_models()` 在命令行参数 `--list-models` 中被调用
 - `get_llm_config()` 用于获取 think 和 chat 模型配置
 
 ### ✅ LLM 服务 (services/llm_service.py)
 
 **导入内容:**
 ```python
-from config import (
+from pure_auto_codeql.configuration import (
     get_chat_config, 
     LLMConfig, 
     get_resilient_llm_config, 
@@ -47,7 +49,7 @@ from config import (
 
 **导入内容:**
 ```python
-from config import get_chat_config
+from pure_auto_codeql.configuration import get_chat_config
 ```
 
 **状态:** ✅ 完全兼容
@@ -57,7 +59,7 @@ from config import get_chat_config
 
 **导入内容:**
 ```python
-from config import get_chat_config
+from pure_auto_codeql.configuration import get_chat_config
 ```
 
 **状态:** ✅ 完全兼容
@@ -148,10 +150,10 @@ config/
 
 ## 结论
 
-**✅ 主程序完全正确地使用了新的 config 模块**
+**✅ 主程序完全正确地使用了 canonical 配置入口**
 
 所有关键功能均已验证：
-1. 主程序 `Analyze.py` 可以正常导入和调用所有需要的config函数
+1. 主程序 `Analyze.py` 可以正常导入和调用所有需要的配置函数
 2. 服务层 `services/llm_service.py` 正确使用配置系统
 3. 示例和测试代码都能正常工作
 4. 向后兼容性完全保持
@@ -165,7 +167,6 @@ config/
 3. 运行主程序：`python Analyze.py --case CVE-XXXX-XXXX`
 
 ### 对于开发者
-1. 导入核心函数：`from config import get_llm_config, LLMRole`
+1. 导入核心函数：`from pure_auto_codeql.configuration import get_llm_config, LLMRole`
 2. 使用配置：`config = get_llm_config(LLMRole.CHAT)`
-3. 所有旧版API仍然可用，无需修改现有代码
-
+3. 所有旧版 API 仍然可用，历史代码无需立即修改

config/README.md

@@ -185,8 +185,11 @@ python Analyze.py --md-file vuln.md --src-path /path/to/src --provider my_api
 
 ### 在代码中使用
 
+运行时代码推荐使用 `pure_auto_codeql.configuration` 作为统一导入入口；旧的
+`from config import ...` 仍保持兼容。
+
 ```python
-from config import get_llm_config, LLMRole
+from pure_auto_codeql.configuration import get_llm_config, LLMRole
 
 # 获取默认配置
 chat_config = get_llm_config(LLMRole.CHAT)
@@ -219,7 +222,7 @@ print(f"Base URL: {config.base_url}")
 ### 便捷函数
 
 ```python
-from config import get_chat_config, get_think_config
+from pure_auto_codeql.configuration import get_chat_config, get_think_config
 
 # 直接获取对话模型配置
 chat_config = get_chat_config()
@@ -525,7 +528,10 @@ exists = ProviderRegistry.has("my_api")
 ### 显示函数
 
 ```python
-from config import display_providers_status, display_provider_detail
+from pure_auto_codeql.configuration import (
+    display_provider_detail,
+    display_providers_status,
+)
 
 # 显示所有提供商状态
 display_providers_status(validate_keys=False)
@@ -537,7 +543,7 @@ display_provider_detail("my_api")
 ### 向后兼容函数
 
 ```python
-from config import (
+from pure_auto_codeql.configuration import (
     list_available_providers,
     get_llm_config_by_provider,
     list_siliconflow_models

core/pipeline.py

@@ -21,10 +21,10 @@ def _get_llm_config_from_context(context: AnalysisContext, role) -> Any:
     """从上下文中获取LLM配置，支持配置中的模型、API Key和Base URL"""
     config = getattr(context, '_config', None)
     if not config:
-        from config import get_resilient_llm_config, LLMRole
+        from pure_auto_codeql.configuration import get_resilient_llm_config, LLMRole
         return get_resilient_llm_config(role)
 
-    from config import get_llm_config, LLMRole
+    from pure_auto_codeql.configuration import get_llm_config, LLMRole
     # 从配置中获取参数
     provider = config.llm_provider
     model_name = config.think_model if role == LLMRole.THINK else config.chat_model
@@ -73,7 +73,7 @@ def __init__(self):
 
     async def execute(self, context: AnalysisContext) -> Any:
         """执行CVE分析。"""
-        from config import LLMRole
+        from pure_auto_codeql.configuration import LLMRole
         llm_config = _get_llm_config_from_context(context, LLMRole.CHAT)
         analyzer = MultiAgentAnalyzer(llm_config)
         await analyzer.initialize(
@@ -116,7 +116,7 @@ def __init__(self):
 
     async def execute(self, context: AnalysisContext) -> Any:
         """执行Sink路径分析。"""
-        from config import LLMRole
+        from pure_auto_codeql.configuration import LLMRole
         llm_config = _get_llm_config_from_context(context, LLMRole.CHAT)
         analyzer = MultiAgentAnalyzer(llm_config)
         await analyzer.initialize(
@@ -197,7 +197,7 @@ def __init__(self):
 
     async def execute(self, context: AnalysisContext) -> Any:
         """执行Source分析。"""
-        from config import LLMRole
+        from pure_auto_codeql.configuration import LLMRole
         llm_config = _get_llm_config_from_context(context, LLMRole.CHAT)
         analyzer = MultiAgentAnalyzer(llm_config)
         await analyzer.initialize(
@@ -281,7 +281,7 @@ def __init__(self):
 
     async def execute(self, context: AnalysisContext) -> Any:
         """执行Path分析。"""
-        from config import LLMRole
+        from pure_auto_codeql.configuration import LLMRole
 
         # 检查是否有 Source 分析结果
         if not context.has_result("source_analysis"):
@@ -405,7 +405,7 @@ async def execute(self, context: AnalysisContext) -> Any:
                     logger.warning("Path 分析结果 JSON 解析失败")
 
         # 使用推理模型
-        from config import LLMRole
+        from pure_auto_codeql.configuration import LLMRole
         think_config = _get_llm_config_from_context(context, LLMRole.THINK)
         codeql_analyzer = MultiAgentAnalyzer(think_config)
         await codeql_analyzer.initialize(
@@ -758,7 +758,7 @@ async def _run_path_selection(
             return None
 
         try:
-            from config import LLMRole
+            from pure_auto_codeql.configuration import LLMRole
 
             llm_config = _get_llm_config_from_context(context, LLMRole.CHAT)
             service = PathSelectionService(llm_config, language=context.language)

docs/config_migration_guide.md

@@ -40,18 +40,23 @@ chat_config = get_chat_config()
 #### 新增的 API
 
 ```python
+from pure_auto_codeql.configuration import (
+    LLMRole,
+    ProviderRegistry,
+    display_providers_status,
+    get_llm_config,
+)
+
 # 🆕 新增：指定服务商
 config = get_llm_config(LLMRole.THINK, provider_name="siliconflow")
 
 # 🆕 新增：自动切换
 config = get_llm_config(LLMRole.THINK, auto_fallback=True)
 
 # 🆕 新增：注册中心
-from config import ProviderRegistry
 providers = ProviderRegistry.list_all()
 
 # 🆕 新增：美观展示
-from config import display_providers_status
 display_providers_status()
 ```
 
@@ -85,7 +90,7 @@ think_config = get_llm_config(LLMRole.THINK)
 
 ```python
 # 使用新的展示功能
-from config import display_providers_status
+from pure_auto_codeql.configuration import display_providers_status
 
 # 查看当前配置状态
 display_providers_status()
@@ -115,7 +120,7 @@ chat_config = get_llm_config(LLMRole.CHAT)
 
 **新代码（推荐）：**
 ```python
-from config import get_llm_config, LLMRole
+from pure_auto_codeql.configuration import get_llm_config, LLMRole
 
 # 基本使用保持不变
 think_config = get_llm_config(LLMRole.THINK)
@@ -188,6 +193,13 @@ config = LLMConfig(
 
 **新代码（更灵活）：**
 ```python
+from pure_auto_codeql.configuration import (
+    LLMRole,
+    ProviderConfig,
+    ProviderRegistry,
+    get_llm_config,
+)
+
 # 方式 1: 使用 get_llm_config（推荐）
 config = get_llm_config(
     LLMRole.THINK,
@@ -197,8 +209,6 @@ config = get_llm_config(
 )
 
 # 方式 2: 注册自定义服务商（更好的复用）
-from config import ProviderRegistry, ProviderConfig
-
 ProviderRegistry.register(ProviderConfig(
     name="my_custom",
     display_name="My Custom Provider",
@@ -261,7 +271,10 @@ providers = list_available_providers()  # 返回 dict 列表
 
 ```python
 # 新方式：使用 ProviderRegistry
-from config import ProviderRegistry
+from pure_auto_codeql.configuration import (
+    ProviderRegistry,
+    display_providers_status,
+)
 
 # 获取所有服务商
 providers = ProviderRegistry.list_all()  # 返回 ProviderConfig 对象列表
@@ -270,7 +283,6 @@ providers = ProviderRegistry.list_all()  # 返回 ProviderConfig 对象列表
 available = ProviderRegistry.list_available()
 
 # 美观展示
-from config import display_providers_status
 display_providers_status()
 ```
 
@@ -299,7 +311,11 @@ python config.py test siliconflow
 
 ```python
 # test_config_migration.py
-from config import get_llm_config, LLMRole, display_providers_status
+from pure_auto_codeql.configuration import (
+    LLMRole,
+    display_providers_status,
+    get_llm_config,
+)
 
 def test_basic():
     """测试基本用法"""
@@ -378,4 +394,3 @@ A: 如果您只使用了 `get_llm_config()`、`get_think_config()`、`get_chat_c
 - ✅ 逐步迁移，无压力
 
 欢迎使用新的配置系统！🎉
-