refactor: 全量 Type Hints 现代化 — dict[str, object] / list[dict[str, object]] 风格

- llm.py: 6 个函数签名更新
- app.py: load_resources 返回类型细化
- utils.py: 3 个函数参数+返回类型细化
- views/: 8 个模块共 15 个函数签名更新
- i18n.py, logging_config.py, views/__init__.py: 已有完整类型无需修改
- 配合 from __future__ import annotations 使用现代 PEP 604 语法

Author: mosmxiaopeng

.pytest_cache/v/cache/lastfailed

@@ -1,7 +1,4 @@
 {
-  "tests/test_app.py::TestConstants": true,
-  "tests/test_app.py::TestEncodeProfile": true,
-  "tests/test_app.py::TestExportJson": true,
-  "tests/test_app.py::TestExportMarkdown": true,
-  "tests/test_app.py::TestFilterResources": true
+  "tests/e2e/test_core_flows.py::TestAppLoads::()::test_title_visible": true,
+  "tests/test_llm.py::TestGenerateTrendInsights::()::test_api_failure_returns_stale_cache": true
 }

.pytest_cache/v/cache/nodeids

@@ -24,6 +24,33 @@
   "tests/test_app.py::TestConstants::()::test_provider_presets_have_required_keys",
   "tests/test_app.py::TestConstants::()::test_direction_domains_are_lists",
   "tests/test_app.py::TestConstants::()::test_preset_profiles_have_required_fields",
+  "tests/test_config.py::TestProviderPresets::()::test_has_required_keys",
+  "tests/test_config.py::TestProviderPresets::()::test_preset_urls_are_strings",
+  "tests/test_config.py::TestProviderPresets::()::test_non_custom_have_models",
+  "tests/test_config.py::TestProviderPresets::()::test_custom_preset_empty",
+  "tests/test_config.py::TestProviderPresets::()::test_known_providers_exist",
+  "tests/test_config.py::TestEmojiMaps::()::test_level_emoji_covers_standard_levels",
+  "tests/test_config.py::TestEmojiMaps::()::test_type_emoji_covers_standard_types",
+  "tests/test_config.py::TestEmojiMaps::()::test_focus_emoji_covers_all",
+  "tests/test_config.py::TestEmojiMaps::()::test_level_order_values_ascending",
+  "tests/test_config.py::TestFormOptions::()::test_levels_not_empty",
+  "tests/test_config.py::TestFormOptions::()::test_preferences_not_empty",
+  "tests/test_config.py::TestFormOptions::()::test_languages_not_empty",
+  "tests/test_config.py::TestFormOptions::()::test_focus_options_not_empty",
+  "tests/test_config.py::TestFormOptions::()::test_focus_map_covers_all_options",
+  "tests/test_config.py::TestFormOptions::()::test_focus_map_values_valid",
+  "tests/test_config.py::TestDirections::()::test_directions_not_empty",
+  "tests/test_config.py::TestDirections::()::test_all_directions_in_domain_map",
+  "tests/test_config.py::TestDirections::()::test_domains_are_lists_of_strings",
+  "tests/test_config.py::TestPresetProfiles::()::test_has_required_fields",
+  "tests/test_config.py::TestPresetProfiles::()::test_levels_are_valid",
+  "tests/test_config.py::TestPresetProfiles::()::test_directions_are_valid",
+  "tests/test_config.py::TestPresetProfiles::()::test_descriptions_match_profiles",
+  "tests/test_config.py::TestPresetProfiles::()::test_hours_positive",
+  "tests/test_config.py::TestSystemPrompts::()::test_system_prompt_not_empty",
+  "tests/test_config.py::TestSystemPrompts::()::test_system_prompt_mentions_json",
+  "tests/test_config.py::TestSystemPrompts::()::test_chat_prompt_not_empty",
+  "tests/test_config.py::TestSystemPrompts::()::test_chat_prompt_has_rules",
   "tests/test_i18n.py::TestTranslationFunction::()::test_basic_zh",
   "tests/test_i18n.py::TestTranslationFunction::()::test_basic_en",
   "tests/test_i18n.py::TestTranslationFunction::()::test_default_lang_is_zh",
@@ -33,5 +60,101 @@
   "tests/test_i18n.py::TestTranslationFunction::()::test_all_keys_have_zh_and_en",
   "tests/test_i18n.py::TestTranslationFunction::()::test_no_empty_translations",
   "tests/test_i18n.py::TestTranslationFunction::()::test_all_nav_keys_exist",
-  "tests/test_i18n.py::TestTranslationFunction::()::test_format_string_keys_have_placeholders"
+  "tests/test_i18n.py::TestTranslationFunction::()::test_format_string_keys_have_placeholders",
+  "tests/test_llm.py::TestGetLlmConfig::()::test_api_key_from_session_state",
+  "tests/test_llm.py::TestGetLlmConfig::()::test_api_key_from_secrets",
+  "tests/test_llm.py::TestGetLlmConfig::()::test_api_key_from_env",
+  "tests/test_llm.py::TestGetLlmConfig::()::test_default_provider",
+  "tests/test_llm.py::TestGetLlmConfig::()::test_custom_provider",
+  "tests/test_llm.py::TestGetLlmConfig::()::test_known_provider_uses_preset_url",
+  "tests/test_llm.py::TestGeneratePath::()::test_raises_without_api_key",
+  "tests/test_llm.py::TestGeneratePath::()::test_returns_parsed_json",
+  "tests/test_llm.py::TestGeneratePath::()::test_passes_correct_model",
+  "tests/test_llm.py::TestGeneratePath::()::test_user_message_contains_profile",
+  "tests/test_llm.py::TestCompactResources::()::test_single_resource",
+  "tests/test_llm.py::TestCompactResources::()::test_empty_list",
+  "tests/test_llm.py::TestCompactResources::()::test_topics_truncated",
+  "tests/test_llm.py::TestCompactResources::()::test_missing_optional_fields",
+  "tests/test_llm.py::TestCompactResources::()::test_multiple_resources",
+  "tests/test_llm.py::TestInsightsCache::()::test_no_cache_file",
+  "tests/test_llm.py::TestInsightsCache::()::test_save_and_load",
+  "tests/test_llm.py::TestInsightsCache::()::test_stale_cache_returns_none",
+  "tests/test_llm.py::TestInsightsCache::()::test_corrupted_cache_returns_none",
+  "tests/test_llm.py::TestGenerateTrendInsights::()::test_no_api_key_returns_empty",
+  "tests/test_llm.py::TestGenerateTrendInsights::()::test_empty_channels",
+  "tests/test_llm.py::TestGenerateTrendInsights::()::test_returns_insights_json",
+  "tests/test_llm.py::TestGenerateTrendInsights::()::test_uses_cache_when_fresh",
+  "tests/test_llm.py::TestGenerateTrendInsights::()::test_api_failure_returns_empty",
+  "tests/test_logging_config.py::TestGetLogger::()::test_returns_logger",
+  "tests/test_logging_config.py::TestGetLogger::()::test_default_name",
+  "tests/test_logging_config.py::TestGetLogger::()::test_idempotent_init",
+  "tests/test_logging_config.py::TestGetLogger::()::test_logger_has_handlers",
+  "tests/test_progress.py::TestCollectProgress::test_collects_chat_messages",
+  "tests/test_progress.py::TestCollectProgress::test_collects_done_keys",
+  "tests/test_progress.py::TestCollectProgress::test_collects_profile_and_path",
+  "tests/test_progress.py::TestCollectProgress::test_empty_state",
+  "tests/test_progress.py::TestCollectProgress::test_version_field",
+  "tests/test_progress.py::TestRestoreProgress::test_restores_chat",
+  "tests/test_progress.py::TestRestoreProgress::test_restores_done_keys",
+  "tests/test_progress.py::TestRestoreProgress::test_restores_language",
+  "tests/test_progress.py::TestRestoreProgress::test_restores_profile_and_path",
+  "tests/test_progress.py::TestRestoreProgress::test_returns_false_on_invalid",
+  "tests/test_progress.py::TestLocalFilePersistence::test_load_returns_none_when_no_file",
+  "tests/test_progress.py::TestLocalFilePersistence::test_save_and_load_roundtrip",
+  "tests/test_progress.py::TestLocalFilePersistence::test_save_returns_none_without_path",
+  "tests/test_progress.py::TestProgressToJson::test_accepts_explicit_data",
+  "tests/test_progress.py::TestProgressToJson::test_serializes_to_json",
+  "tests/test_utils_extended.py::TestEncodeDecodeEdge::()::test_special_characters",
+  "tests/test_utils_extended.py::TestEncodeDecodeEdge::()::test_nested_data",
+  "tests/test_utils_extended.py::TestEncodeDecodeEdge::()::test_large_profile",
+  "tests/test_utils_extended.py::TestEncodeDecodeEdge::()::test_decode_empty_string",
+  "tests/test_utils_extended.py::TestEncodeDecodeEdge::()::test_decode_non_base64_chars",
+  "tests/test_utils_extended.py::TestEncodeDecodeEdge::()::test_decode_none_input",
+  "tests/test_utils_extended.py::TestEncodeDecodeEdge::()::test_decode_non_dict_json",
+  "tests/test_utils_extended.py::TestEncodeDecodeEdge::()::test_numeric_values",
+  "tests/test_utils_extended.py::TestEncodeDecodeEdge::()::test_encode_deterministic",
+  "tests/test_utils_extended.py::TestFilterEdge::()::test_empty_resources",
+  "tests/test_utils_extended.py::TestFilterEdge::()::test_empty_direction",
+  "tests/test_utils_extended.py::TestFilterEdge::()::test_unknown_direction",
+  "tests/test_utils_extended.py::TestFilterEdge::()::test_focus_both_returns_all",
+  "tests/test_utils_extended.py::TestFilterEdge::()::test_filter_preserves_resource_integrity",
+  "tests/test_utils_extended.py::TestFilterEdge::()::test_zh_language_zh_first",
+  "tests/test_utils_extended.py::TestFilterEdge::()::test_direction_matched_before_general",
+  "tests/test_utils_extended.py::TestFilterEdge::()::test_applied_focus_ordering",
+  "tests/test_utils_extended.py::TestFilterEdge::()::test_resources_with_missing_domain",
+  "tests/test_utils_extended.py::TestExportEdge::()::test_markdown_empty_weeks",
+  "tests/test_utils_extended.py::TestExportEdge::()::test_markdown_unknown_resource_id",
+  "tests/test_utils_extended.py::TestExportEdge::()::test_markdown_channel_resource",
+  "tests/test_utils_extended.py::TestExportEdge::()::test_markdown_multiple_weeks",
+  "tests/test_utils_extended.py::TestExportEdge::()::test_json_empty_path",
+  "tests/test_utils_extended.py::TestExportEdge::()::test_json_profile_preserved",
+  "tests/test_utils_extended.py::TestExportEdge::()::test_markdown_has_checkbox",
+  "tests/test_utils_extended.py::TestExportEdge::()::test_markdown_profile_fields",
+  "tests/test_views.py::TestBuildChatContext::()::test_includes_resource_summary",
+  "tests/test_views.py::TestBuildChatContext::()::test_includes_profile_when_present",
+  "tests/test_views.py::TestBuildChatContext::()::test_includes_path_when_present",
+  "tests/test_views.py::TestBuildChatContext::()::test_no_profile_no_path",
+  "tests/test_views.py::TestBuildChatContext::()::test_topic_truncation",
+  "tests/test_views.py::TestBuildChatContext::()::test_resource_limit_60",
+  "tests/test_views.py::TestBuildChatContext::()::test_empty_resources",
+  "tests/test_views.py::TestBuildChatContext::()::test_path_with_no_weeks",
+  "tests/test_views.py::TestSubmitFeedback::()::test_local_save_returns_local",
+  "tests/test_views.py::TestSubmitFeedback::()::test_github_save_returns_github",
+  "tests/test_views.py::TestSubmitFeedback::()::test_github_failure_falls_back_local",
+  "tests/test_views.py::TestSubmitFeedback::()::test_local_save_failure_silent",
+  "tests/test_views.py::TestSubmitFeedback::()::test_feedback_file_content",
+  "tests/test_views.py::TestSubmitFeedback::()::test_github_issue_body_contains_rating",
+  "tests/test_views.py::TestImportPlanLogic::()::test_module_importable",
+  "tests/test_views.py::TestImportPlanLogic::()::test_settings_importable",
+  "tests/test_views.py::TestImportPlanLogic::()::test_all_views_importable",
+  "tests/e2e/test_core_flows.py::TestAppLoads::()::test_title_visible",
+  "tests/e2e/test_core_flows.py::TestAppLoads::()::test_sidebar_present",
+  "tests/e2e/test_core_flows.py::TestAppLoads::()::test_form_visible_on_first_load",
+  "tests/e2e/test_core_flows.py::TestNavigation::()::test_navigate_to_chat",
+  "tests/e2e/test_core_flows.py::TestNavigation::()::test_navigate_to_browser",
+  "tests/e2e/test_core_flows.py::TestNavigation::()::test_navigate_to_radar",
+  "tests/e2e/test_core_flows.py::TestResourceBrowser::()::test_resource_count_displayed",
+  "tests/e2e/test_core_flows.py::TestResourceBrowser::()::test_search_filters_resources",
+  "tests/e2e/test_core_flows.py::TestLanguageToggle::()::test_toggle_to_english",
+  "tests/e2e/test_core_flows.py::TestPresetTemplates::()::test_preset_buttons_visible"
 ]

app.py

@@ -21,7 +21,7 @@
 
 
 @st.cache_data(show_spinner=False, ttl=3600)
-def load_resources() -> list[dict]:
+def load_resources() -> list[dict[str, object]]:
     """Cached wrapper — YAML is parsed once, refreshed every hour."""
     return _load_resources_uncached()
 

llm.py

@@ -39,7 +39,7 @@ def get_llm_config() -> tuple[str, str, str]:
     return api_key, base_url, model
 
 
-def _compact_resources(resources: list[dict]) -> str:
+def _compact_resources(resources: list[dict[str, object]]) -> str:
     """Compact resource list to minimal token footprint."""
     lines = []
     for r in resources:
@@ -52,7 +52,7 @@ def _compact_resources(resources: list[dict]) -> str:
     return "\n".join(lines)
 
 
-def generate_path(profile: dict, resources: list[dict]) -> dict:
+def generate_path(profile: dict[str, object], resources: list[dict[str, object]]) -> dict[str, object]:
     """Call LLM to generate a personalized learning path (streaming)."""
     api_key, base_url, model = get_llm_config()
     if not api_key:
@@ -130,7 +130,7 @@ def generate_path(profile: dict, resources: list[dict]) -> dict:
 }"""
 
 
-def _load_insights_cache() -> dict | None:
+def _load_insights_cache() -> dict[str, object] | None:
     """Load cached insights if fresh (same date)."""
     if not os.path.exists(INSIGHTS_CACHE_PATH):
         return None
@@ -144,7 +144,7 @@ def _load_insights_cache() -> dict | None:
     return None
 
 
-def _save_insights_cache(data: dict) -> None:
+def _save_insights_cache(data: dict[str, object]) -> None:
     """Save insights to local cache file."""
     try:
         with open(INSIGHTS_CACHE_PATH, "w", encoding="utf-8") as f:
@@ -153,7 +153,7 @@ def _save_insights_cache(data: dict) -> None:
         _log.warning("insights_cache_save_failed: %s", e)
 
 
-def generate_trend_insights(channels: list[dict], force_refresh: bool = False) -> dict:
+def generate_trend_insights(channels: list[dict[str, object]], force_refresh: bool = False) -> dict[str, object]:
     """Generate daily AI trend insights via LLM, with local caching."""
     if not force_refresh:
         cached = _load_insights_cache()

utils.py

@@ -38,7 +38,12 @@ def decode_profile(s: str) -> dict | None:
         return None
 
 
-def filter_resources_for_direction(resources: list[dict], direction: str, language: str, focus: str = "both") -> list[dict]:
+def filter_resources_for_direction(
+    resources: list[dict[str, object]],
+    direction: str,
+    language: str,
+    focus: str = "both",
+) -> list[dict[str, object]]:
     """Pre-filter resources by direction + language + focus, capped at 50."""
     domains = DIRECTION_TO_DOMAIN.get(direction, [])
     if domains:
@@ -67,7 +72,11 @@ def filter_resources_for_direction(resources: list[dict], direction: str, langua
     return filtered[:35]
 
 
-def export_plan_markdown(path_data: dict, profile: dict, resources: list[dict]) -> str:
+def export_plan_markdown(
+    path_data: dict[str, object],
+    profile: dict[str, object],
+    resources: list[dict[str, object]],
+) -> str:
     """Export learning path as readable Markdown."""
     ridx = {r["id"]: r for r in resources}
     lines = [
@@ -110,7 +119,7 @@ def export_plan_markdown(path_data: dict, profile: dict, resources: list[dict])
     return "\n".join(lines)
 
 
-def export_plan_json(path_data: dict, profile: dict) -> str:
+def export_plan_json(path_data: dict[str, object], profile: dict[str, object]) -> str:
     """Export learning path as importable JSON."""
     return json.dumps({"profile": profile, "path": path_data}, ensure_ascii=False, indent=2)
 

views/browser.py

@@ -10,7 +10,7 @@
 from views import _lang
 
 
-def render_resource_browser(resources: list[dict]) -> None:
+def render_resource_browser(resources: list[dict[str, object]]) -> None:
     L = _lang()
     st.title(t("browser_title", L))
     st.caption(t("browser_hint", L))

views/chat.py

@@ -14,7 +14,7 @@
 _log = get_logger("chat")
 
 
-def _build_chat_context(resources: list[dict]) -> str:
+def _build_chat_context(resources: list[dict[str, object]]) -> str:
     """Build chat context: user profile + current path + resource summary."""
     parts = []
     profile = st.session_state.get("profile")
@@ -36,7 +36,7 @@ def _build_chat_context(resources: list[dict]) -> str:
     return "\n\n".join(parts)
 
 
-def render_chat(resources: list[dict]) -> None:
+def render_chat(resources: list[dict[str, object]]) -> None:
     L = _lang()
     st.title(t("chat_title", L))
     st.markdown(t("chat_subtitle", L))

views/feedback.py

@@ -16,7 +16,7 @@
 _log = get_logger("feedback")
 
 
-def submit_feedback(feedback: dict) -> str:
+def submit_feedback(feedback: dict[str, object]) -> str:
     """Save feedback: local file (always try) + GitHub Issues (if token). Returns 'github' or 'local'."""
     try:
         feedback_dir = os.path.join(os.path.dirname(__file__), "..", "feedback")

views/form.py

@@ -11,7 +11,7 @@
 from views import _lang
 
 
-def render_form() -> tuple[bool, dict]:
+def render_form() -> tuple[bool, dict[str, object]]:
     L = _lang()
     st.title(t("form_title", L))
     st.markdown(t("form_subtitle", L))

views/import_plan.py

@@ -10,7 +10,7 @@
 from views import _lang
 
 
-def render_import_plan(resources: list[dict]) -> None:
+def render_import_plan(resources: list[dict[str, object]]) -> None:
     L = _lang()
     st.title(t("import_title", L))
     st.markdown(t("import_subtitle", L))