refactor: code quality improvements - cleanup service, type safety, store optimization, URL/search/folder utils

Author: shijiashuai

main.py

@@ -12,10 +12,7 @@
 import glob
 from pathlib import Path
 
-# 添加项目路径
-PROJECT_ROOT = Path(__file__).parent
-sys.path.insert(0, str(PROJECT_ROOT))
-
+from src import __version__
 from src.ai_classifier import AIBookmarkClassifier
 from src.bookmark_processor import BookmarkProcessor
 from src.cli_interface import CLIInterface
@@ -48,7 +45,7 @@ def main():
     )
 
     # 基本参数
-    parser.add_argument('-V', '--version', action='version', version='%(prog)s 2.0.0')
+    parser.add_argument('-V', '--version', action='version', version=f'%(prog)s {__version__}')
 
     parser.add_argument('-i', '--input', nargs='+', help='输入的HTML书签文件')
     parser.add_argument('-o', '--output', default='output', help='输出目录')

models/recommendation.pkl

@@ -2,6 +2,29 @@
 
 为现有模块提供包命名空间，便于打包与 console script 导入。
 """
-__all__ = []
 
 __version__ = "2.0.0"
+
+__all__ = [
+    "AIBookmarkClassifier",
+    "BookmarkProcessor",
+    "RuleEngine",
+    "DataExporter",
+    "BookmarkDeduplicator",
+]
+
+
+def __getattr__(name: str):
+    """按需延迟导入，避免启动时加载全部模块。"""
+    _mapping = {
+        "AIBookmarkClassifier": ".ai_classifier",
+        "BookmarkProcessor": ".bookmark_processor",
+        "RuleEngine": ".rule_engine",
+        "DataExporter": ".data_exporter",
+        "BookmarkDeduplicator": ".deduplicator",
+    }
+    if name in _mapping:
+        import importlib
+        module = importlib.import_module(_mapping[name], __name__)
+        return getattr(module, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/__init__.py

@@ -15,7 +15,7 @@
 from typing import Dict, List, Tuple, Optional
 from dataclasses import dataclass, field
 from datetime import datetime
-from collections import defaultdict
+from collections import defaultdict, OrderedDict
 import hashlib
 import re
 from urllib.parse import urlparse
@@ -42,10 +42,14 @@
     SmartRuleLoader = None
     merge_with_main_config = None
 
-# 导入占位符模块
-from .placeholder_modules import (
-    SemanticAnalyzer, UserProfiler, PerformanceMonitor
-)
+# 导入核心分析组件
+from .semantic_analyzer import SemanticAnalyzer
+from .user_profiler import UserProfiler
+
+try:
+    from .performance_optimizer import PerformanceMonitor
+except ImportError:
+    PerformanceMonitor = None  # type: ignore[misc,assignment]
 
 
 @dataclass
@@ -107,9 +111,9 @@ def __init__(self, config_path: str = "config.json", enable_ml: bool = True, con
         self._ml_classifier: Optional[MLClassifierWrapper] = None
         self._llm_classifier: Optional[LLMClassifier] = None
 
-        # 缓存
+        # 缓存（OrderedDict 实现 LRU 淘汰）
         self.feature_cache: Dict[str, BookmarkFeatures] = {}
-        self.classification_cache: Dict[str, ClassificationResult] = {}
+        self.classification_cache: OrderedDict[str, ClassificationResult] = OrderedDict()
         self._max_cache_size = 5000
 
         # 统计
@@ -150,9 +154,12 @@ def user_profiler(self) -> UserProfiler:
         return self._user_profiler
 
     @property
-    def performance_monitor(self) -> PerformanceMonitor:
-        if self._performance_monitor is None:
-            self._performance_monitor = PerformanceMonitor()
+    def performance_monitor(self) -> Optional['PerformanceMonitor']:
+        if self._performance_monitor is None and PerformanceMonitor is not None:
+            try:
+                self._performance_monitor = PerformanceMonitor()
+            except Exception as e:
+                self.logger.warning(f"性能监控器初始化失败: {e}")
         return self._performance_monitor
 
     @property
@@ -300,6 +307,7 @@ def classify(self, url: str, title: str) -> ClassificationResult:
         cache_key = hashlib.md5(f"{url}::{title}".encode()).hexdigest()
         if cache_key in self.classification_cache:
             self.stats['cache_hits'] += 1
+            self.classification_cache.move_to_end(cache_key)  # LRU 更新
             cached = self.classification_cache[cache_key]
             cached.processing_time = (datetime.now() - start_time).total_seconds()
             return cached
@@ -310,43 +318,38 @@ def classify(self, url: str, title: str) -> ClassificationResult:
         # 多方法融合
         results: List[ClassificationResult] = []
 
+        def _collect(raw):
+            """将 dict / ClassificationResult / None 统一追加到 results。"""
+            if raw is None:
+                return
+            results.append(self._to_classification_result(raw))
+
         # 1) 规则引擎
-        rule_result = self.rule_engine.classify(features)
-        if rule_result:
-            results.append(rule_result)
+        _collect(self.rule_engine.classify(features))
 
         # 2) 机器学习
         if self.ml_classifier:
-            ml_result = self.ml_classifier.classify(features)
-            if ml_result:
-                results.append(ml_result)
+            _collect(self.ml_classifier.classify(features))
 
         # 3) 语义分析
         if self.config.get('ai_settings', {}).get('use_semantic_analysis', True):
-            semantic_result = self.semantic_analyzer.classify(features)
-            if semantic_result:
-                results.append(semantic_result)
+            _collect(self.semantic_analyzer.classify(features))
 
         # 4) 用户画像
         if self.config.get('ai_settings', {}).get('use_user_profiling', True):
-            user_result = self.user_profiler.classify(features)
-            if user_result:
-                results.append(user_result)
+            _collect(self.user_profiler.classify(features))
 
         # 5) LLM（可选）
         if self.llm_classifier and self.llm_classifier.enabled():
             try:
-                llm_result = self.llm_classifier.classify(
-                    url,
-                    title,
+                _collect(self.llm_classifier.classify(
+                    url, title,
                     context={
                         'domain': features.domain,
                         'content_type': features.content_type,
                         'language': features.language,
                     },
-                )
-                if llm_result:
-                    results.append(llm_result)
+                ))
             except Exception as e:
                 self.logger.warning(f"LLM 分类调用失败: {e}")
 
@@ -376,11 +379,31 @@ def classify(self, url: str, title: str) -> ClassificationResult:
         self._cache_result(cache_key, final_result)
         return final_result
 
+    @staticmethod
+    def _to_classification_result(raw) -> ClassificationResult:
+        """将 dict 或 ClassificationResult 统一为 ClassificationResult。"""
+        if isinstance(raw, ClassificationResult):
+            return raw
+        if isinstance(raw, dict):
+            return ClassificationResult(
+                category=raw.get('category', '未分类'),
+                confidence=float(raw.get('confidence', 0.0)),
+                subcategory=raw.get('subcategory'),
+                reasoning=raw.get('reasoning', []),
+                alternatives=raw.get('alternatives', []),
+                processing_time=float(raw.get('processing_time', 0.0)),
+                method=raw.get('method', 'unknown'),
+                facets=raw.get('facets', {}),
+            )
+        raise TypeError(f"Unexpected classification result type: {type(raw)}")
+
     def _cache_result(self, cache_key: str, result: ClassificationResult):
-        if len(self.classification_cache) >= self._max_cache_size:
-            oldest_key = next(iter(self.classification_cache))
-            del self.classification_cache[oldest_key]
-        self.classification_cache[cache_key] = result
+        if cache_key in self.classification_cache:
+            self.classification_cache.move_to_end(cache_key)
+        else:
+            if len(self.classification_cache) >= self._max_cache_size:
+                self.classification_cache.popitem(last=False)  # 淘汰最久未使用
+            self.classification_cache[cache_key] = result
 
     def _ensemble_classification(self, results: List[ClassificationResult], features: BookmarkFeatures) -> ClassificationResult:
         if not results:
@@ -406,18 +429,11 @@ def _ensemble_classification(self, results: List[ClassificationResult], features
         }
 
         for res in results:
-            if isinstance(res, dict):
-                method = res.get('method', 'unknown')
-                category = self._normalize_category_string(res.get('category', '未分类')) or '未分类'
-                confidence = res.get('confidence', 0.0)
-                reasoning = res.get('reasoning', [])
-                facets = res.get('facets', {}) or {}
-            else:
-                method = res.method
-                category = self._normalize_category_string(res.category) or '未分类'
-                confidence = res.confidence
-                reasoning = res.reasoning
-                facets = getattr(res, 'facets', {}) or {}
+            method = res.method
+            category = self._normalize_category_string(res.category) or '未分类'
+            confidence = res.confidence
+            reasoning = res.reasoning
+            facets = res.facets or {}
 
             weight = method_weights.get(method, 0.1)
             category_scores[category] += confidence * weight

src/ai_classifier.py

@@ -30,10 +30,10 @@
 except ImportError:
     LLMBookmarkOrganizer = None
 
-# 导入占位符模块
-from .placeholder_modules import (
-    DataExporter, BookmarkDeduplicator, HealthChecker
-)
+# 导入核心组件
+from .data_exporter import DataExporter
+from .deduplicator import BookmarkDeduplicator
+from .bookmark_health_checker import HealthChecker
 
 class BookmarkProcessor:
     """书签处理器主类"""
@@ -140,23 +140,20 @@ def classifier(self):
     def deduplicator(self):
         """Lazy loading deduplicator"""
         if self._deduplicator is None:
-            from .placeholder_modules import BookmarkDeduplicator
             self._deduplicator = BookmarkDeduplicator()
         return self._deduplicator
 
     @property
     def health_checker(self):
         """Lazy loading health checker"""
         if self._health_checker is None:
-            from .placeholder_modules import HealthChecker
             self._health_checker = HealthChecker()
         return self._health_checker
 
     @property
     def exporter(self):
         """Lazy loading exporter"""
         if self._exporter is None:
-            from .placeholder_modules import DataExporter
             self._exporter = DataExporter(config=self.config)
         return self._exporter
 
@@ -241,6 +238,9 @@ def process_files(self, input_files: List[str], output_dir: str = "output",
 
         # 可选：调用 LLM 进行更高层次的整理
         self.llm_organizer_meta = None
+        self.stats['llm_organizer_used'] = False
+        self.stats.pop('llm_organizer_meta', None)
+
         if self.llm_organizer and self.llm_organizer.enabled():
             try:
                 llm_result = self.llm_organizer.organize(
@@ -257,16 +257,6 @@ def process_files(self, input_files: List[str], output_dir: str = "output",
                 self.stats['llm_organizer_used'] = True
                 if self.llm_organizer_meta:
                     self.stats['llm_organizer_meta'] = self.llm_organizer_meta
-                elif 'llm_organizer_meta' in self.stats:
-                    self.stats.pop('llm_organizer_meta', None)
-            else:
-                self.stats['llm_organizer_used'] = False
-                if 'llm_organizer_meta' in self.stats:
-                    self.stats.pop('llm_organizer_meta', None)
-        else:
-            self.stats['llm_organizer_used'] = False
-            if 'llm_organizer_meta' in self.stats:
-                self.stats.pop('llm_organizer_meta', None)
 
         organized_bookmarks = self._sort_organized_structure(organized_bookmarks)
 

src/bookmark_processor.py

@@ -31,6 +31,9 @@
 
 import requests
 
+from .category_utils import strip_category_prefix, normalize_category_string
+
+
 class LLMClassifier:
     def __init__(self, config_path: str = "config.json"):
         self.config_path = config_path
@@ -152,26 +155,10 @@ def _load_config(self) -> Dict:
 
     @staticmethod
     def _strip_category_prefix(text: str) -> str:
-        if not text:
-            return ""
-        s = str(text).strip()
-        i = 0
-        while i < len(s) and not ("\u4e00" <= s[i] <= "\u9fff" or s[i].isalnum()):
-            i += 1
-        return s[i:].strip() if i < len(s) else s
+        return strip_category_prefix(text)
 
     def _normalize_category_string(self, category: str) -> str:
-        if not category:
-            return ""
-        cat = str(category).strip()
-        if not cat:
-            return ""
-        if '/' in cat:
-            main, sub = cat.split('/', 1)
-            main_n = self._strip_category_prefix(main)
-            sub_n = self._strip_category_prefix(sub)
-            return f"{main_n}/{sub_n}" if sub_n else main_n
-        return self._strip_category_prefix(cat)
+        return normalize_category_string(category)
 
     def _collect_valid_categories(self, config: Dict) -> List[str]:
         cats = []

src/llm_classifier.py

@@ -1,38 +1,32 @@
-"""
-Placeholder Modules - Backward Compatibility Forwarding Layer
+"""Backward Compatibility Forwarding Layer (DEPRECATED)
+
+此模块已弃用。请直接从对应模块导入：
 
-Original implementations have been split into independent modules:
-- semantic_analyzer.py       -> SemanticAnalyzer
-- user_profiler.py           -> UserProfiler
-- deduplicator.py            -> BookmarkDeduplicator
-- bookmark_health_checker.py -> HealthChecker, HealthStatus
-- data_exporter.py           -> DataExporter
-- performance_optimizer.py   -> PerformanceMonitor
+    from src.semantic_analyzer import SemanticAnalyzer
+    from src.user_profiler import UserProfiler
+    from src.deduplicator import BookmarkDeduplicator
+    from src.bookmark_health_checker import HealthChecker, HealthStatus
+    from src.data_exporter import DataExporter
+    from src.performance_optimizer import PerformanceMonitor
 """
+import warnings as _warnings
 
-from .semantic_analyzer import SemanticAnalyzer
-from .user_profiler import UserProfiler
-from .deduplicator import BookmarkDeduplicator
-from .bookmark_health_checker import HealthChecker, HealthStatus
-from .data_exporter import DataExporter
+_warnings.warn(
+    "placeholder_modules is deprecated; import from the real modules directly.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from .semantic_analyzer import SemanticAnalyzer  # noqa: F401
+from .user_profiler import UserProfiler  # noqa: F401
+from .deduplicator import BookmarkDeduplicator  # noqa: F401
+from .bookmark_health_checker import HealthChecker, HealthStatus  # noqa: F401
+from .data_exporter import DataExporter  # noqa: F401
 
 try:
-    from .performance_optimizer import PerformanceMonitor
+    from .performance_optimizer import PerformanceMonitor  # noqa: F401
 except Exception:
-    class PerformanceMonitor:
-        """PerformanceMonitor fallback stub."""
-        def __init__(self, **kwargs):
-            self.metrics = {}
-        def get_summary(self):
-            return self.metrics
-        def __getattr__(self, name):
-            if name.startswith("_"):
-                raise AttributeError(name)
-            raise AttributeError(name)
-
-# Keep datetime import for any legacy code that did:
-#   from .placeholder_modules import datetime
-from datetime import datetime
+    PerformanceMonitor = None  # type: ignore[misc,assignment]
 
 __all__ = [
     "SemanticAnalyzer",