fix(skill): make skill prompt cache refresh nonblocking (#1924)

* fix: make skill prompt cache refresh nonblocking

* fix: harden skills prompt cache refresh

* chore: add timeout to skills cache warm-up

backend/tests/test_lead_agent_prompt.py

@@ -1,6 +1,10 @@
+import threading
 from types import SimpleNamespace
 
+import anyio
+
 from deerflow.agents.lead_agent import prompt as prompt_module
+from deerflow.skills.types import Skill
 
 
 def test_build_custom_mounts_section_returns_empty_when_no_mounts(monkeypatch):
@@ -34,7 +38,7 @@ def test_apply_prompt_template_includes_custom_mounts(monkeypatch):
         skills=SimpleNamespace(container_path="/mnt/skills"),
     )
     monkeypatch.setattr("deerflow.config.get_app_config", lambda: config)
-    monkeypatch.setattr(prompt_module, "load_skills", lambda enabled_only=True: [])
+    monkeypatch.setattr(prompt_module, "_get_enabled_skills", lambda: [])
     monkeypatch.setattr(prompt_module, "get_deferred_tools_prompt_section", lambda: "")
     monkeypatch.setattr(prompt_module, "_build_acp_section", lambda: "")
     monkeypatch.setattr(prompt_module, "_get_memory_context", lambda agent_name=None: "")
@@ -44,3 +48,100 @@ def test_apply_prompt_template_includes_custom_mounts(monkeypatch):
 
     assert "`/home/user/shared`" in prompt
     assert "Custom Mounted Directories" in prompt
+
+
+def test_refresh_skills_system_prompt_cache_async_reloads_immediately(monkeypatch, tmp_path):
+    def make_skill(name: str) -> Skill:
+        skill_dir = tmp_path / name
+        return Skill(
+            name=name,
+            description=f"Description for {name}",
+            license="MIT",
+            skill_dir=skill_dir,
+            skill_file=skill_dir / "SKILL.md",
+            relative_path=skill_dir.relative_to(tmp_path),
+            category="custom",
+            enabled=True,
+        )
+
+    state = {"skills": [make_skill("first-skill")]}
+    monkeypatch.setattr(prompt_module, "load_skills", lambda enabled_only=True: list(state["skills"]))
+    prompt_module._reset_skills_system_prompt_cache_state()
+
+    try:
+        prompt_module.warm_enabled_skills_cache()
+        assert [skill.name for skill in prompt_module._get_enabled_skills()] == ["first-skill"]
+
+        state["skills"] = [make_skill("second-skill")]
+        anyio.run(prompt_module.refresh_skills_system_prompt_cache_async)
+
+        assert [skill.name for skill in prompt_module._get_enabled_skills()] == ["second-skill"]
+    finally:
+        prompt_module._reset_skills_system_prompt_cache_state()
+
+
+def test_clear_cache_does_not_spawn_parallel_refresh_workers(monkeypatch, tmp_path):
+    started = threading.Event()
+    release = threading.Event()
+    active_loads = 0
+    max_active_loads = 0
+    call_count = 0
+    lock = threading.Lock()
+
+    def make_skill(name: str) -> Skill:
+        skill_dir = tmp_path / name
+        return Skill(
+            name=name,
+            description=f"Description for {name}",
+            license="MIT",
+            skill_dir=skill_dir,
+            skill_file=skill_dir / "SKILL.md",
+            relative_path=skill_dir.relative_to(tmp_path),
+            category="custom",
+            enabled=True,
+        )
+
+    def fake_load_skills(enabled_only=True):
+        nonlocal active_loads, max_active_loads, call_count
+        with lock:
+            active_loads += 1
+            max_active_loads = max(max_active_loads, active_loads)
+            call_count += 1
+            current_call = call_count
+
+        started.set()
+        if current_call == 1:
+            release.wait(timeout=5)
+
+        with lock:
+            active_loads -= 1
+
+        return [make_skill(f"skill-{current_call}")]
+
+    monkeypatch.setattr(prompt_module, "load_skills", fake_load_skills)
+    prompt_module._reset_skills_system_prompt_cache_state()
+
+    try:
+        prompt_module.clear_skills_system_prompt_cache()
+        assert started.wait(timeout=5)
+
+        prompt_module.clear_skills_system_prompt_cache()
+        release.set()
+        prompt_module.warm_enabled_skills_cache()
+
+        assert max_active_loads == 1
+        assert [skill.name for skill in prompt_module._get_enabled_skills()] == ["skill-2"]
+    finally:
+        release.set()
+        prompt_module._reset_skills_system_prompt_cache_state()
+
+
+def test_warm_enabled_skills_cache_logs_on_timeout(monkeypatch, caplog):
+    event = threading.Event()
+    monkeypatch.setattr(prompt_module, "_ensure_enabled_skills_cache", lambda: event)
+
+    with caplog.at_level("WARNING"):
+        warmed = prompt_module.warm_enabled_skills_cache(timeout_seconds=0.01)
+
+    assert warmed is False
+    assert "Timed out waiting" in caplog.text

backend/tests/test_lead_agent_skills.py

@@ -21,7 +21,7 @@ def _make_skill(name: str) -> Skill:
 
 def test_get_skills_prompt_section_returns_empty_when_no_skills_match(monkeypatch):
     skills = [_make_skill("skill1"), _make_skill("skill2")]
-    monkeypatch.setattr("deerflow.agents.lead_agent.prompt.load_skills", lambda enabled_only: skills)
+    monkeypatch.setattr("deerflow.agents.lead_agent.prompt._get_enabled_skills", lambda: skills)
 
     result = get_skills_prompt_section(available_skills={"non_existent_skill"})
     assert result == ""
@@ -29,7 +29,7 @@ def test_get_skills_prompt_section_returns_empty_when_no_skills_match(monkeypatc
 
 def test_get_skills_prompt_section_returns_empty_when_available_skills_empty(monkeypatch):
     skills = [_make_skill("skill1"), _make_skill("skill2")]
-    monkeypatch.setattr("deerflow.agents.lead_agent.prompt.load_skills", lambda enabled_only: skills)
+    monkeypatch.setattr("deerflow.agents.lead_agent.prompt._get_enabled_skills", lambda: skills)
 
     result = get_skills_prompt_section(available_skills=set())
     assert result == ""
@@ -37,7 +37,7 @@ def test_get_skills_prompt_section_returns_empty_when_available_skills_empty(mon
 
 def test_get_skills_prompt_section_returns_skills(monkeypatch):
     skills = [_make_skill("skill1"), _make_skill("skill2")]
-    monkeypatch.setattr("deerflow.agents.lead_agent.prompt.load_skills", lambda enabled_only: skills)
+    monkeypatch.setattr("deerflow.agents.lead_agent.prompt._get_enabled_skills", lambda: skills)
 
     result = get_skills_prompt_section(available_skills={"skill1"})
     assert "skill1" in result
@@ -47,7 +47,7 @@ def test_get_skills_prompt_section_returns_skills(monkeypatch):
 
 def test_get_skills_prompt_section_returns_all_when_available_skills_is_none(monkeypatch):
     skills = [_make_skill("skill1"), _make_skill("skill2")]
-    monkeypatch.setattr("deerflow.agents.lead_agent.prompt.load_skills", lambda enabled_only: skills)
+    monkeypatch.setattr("deerflow.agents.lead_agent.prompt._get_enabled_skills", lambda: skills)
 
     result = get_skills_prompt_section(available_skills=None)
     assert "skill1" in result
@@ -56,7 +56,7 @@ def test_get_skills_prompt_section_returns_all_when_available_skills_is_none(mon
 
 def test_get_skills_prompt_section_includes_self_evolution_rules(monkeypatch):
     skills = [_make_skill("skill1")]
-    monkeypatch.setattr("deerflow.agents.lead_agent.prompt.load_skills", lambda enabled_only: skills)
+    monkeypatch.setattr("deerflow.agents.lead_agent.prompt._get_enabled_skills", lambda: skills)
     monkeypatch.setattr(
         "deerflow.config.get_app_config",
         lambda: SimpleNamespace(
@@ -70,7 +70,7 @@ def test_get_skills_prompt_section_includes_self_evolution_rules(monkeypatch):
 
 
 def test_get_skills_prompt_section_includes_self_evolution_rules_without_skills(monkeypatch):
-    monkeypatch.setattr("deerflow.agents.lead_agent.prompt.load_skills", lambda enabled_only: [])
+    monkeypatch.setattr("deerflow.agents.lead_agent.prompt._get_enabled_skills", lambda: [])
     monkeypatch.setattr(
         "deerflow.config.get_app_config",
         lambda: SimpleNamespace(
@@ -85,7 +85,7 @@ def test_get_skills_prompt_section_includes_self_evolution_rules_without_skills(
 
 def test_get_skills_prompt_section_cache_respects_skill_evolution_toggle(monkeypatch):
     skills = [_make_skill("skill1")]
-    monkeypatch.setattr("deerflow.agents.lead_agent.prompt.load_skills", lambda enabled_only: skills)
+    monkeypatch.setattr("deerflow.agents.lead_agent.prompt._get_enabled_skills", lambda: skills)
     config = SimpleNamespace(
         skills=SimpleNamespace(container_path="/mnt/skills"),
         skill_evolution=SimpleNamespace(enabled=True),

backend/tests/test_skill_manage_tool.py

@@ -26,7 +26,12 @@ def test_skill_manage_create_and_patch(monkeypatch, tmp_path):
     monkeypatch.setattr("deerflow.config.get_app_config", lambda: config)
     monkeypatch.setattr("deerflow.skills.manager.get_app_config", lambda: config)
     monkeypatch.setattr("deerflow.skills.security_scanner.get_app_config", lambda: config)
-    monkeypatch.setattr(skill_manage_module, "clear_skills_system_prompt_cache", lambda: None)
+    refresh_calls = []
+
+    async def _refresh():
+        refresh_calls.append("refresh")
+
+    monkeypatch.setattr(skill_manage_module, "refresh_skills_system_prompt_cache_async", _refresh)
     monkeypatch.setattr(skill_manage_module, "scan_skill_content", lambda *args, **kwargs: _async_result("allow", "ok"))
 
     runtime = SimpleNamespace(context={"thread_id": "thread-1"}, config={"configurable": {"thread_id": "thread-1"}})
@@ -53,6 +58,7 @@ def test_skill_manage_create_and_patch(monkeypatch, tmp_path):
     )
     assert "Patched custom skill" in patch_result
     assert "Patched skill" in (skills_root / "custom" / "demo-skill" / "SKILL.md").read_text(encoding="utf-8")
+    assert refresh_calls == ["refresh", "refresh"]
 
 
 def test_skill_manage_patch_replaces_single_occurrence_by_default(monkeypatch, tmp_path):
@@ -64,7 +70,11 @@ def test_skill_manage_patch_replaces_single_occurrence_by_default(monkeypatch, t
     monkeypatch.setattr("deerflow.config.get_app_config", lambda: config)
     monkeypatch.setattr("deerflow.skills.manager.get_app_config", lambda: config)
     monkeypatch.setattr("deerflow.skills.security_scanner.get_app_config", lambda: config)
-    monkeypatch.setattr(skill_manage_module, "clear_skills_system_prompt_cache", lambda: None)
+
+    async def _refresh():
+        return None
+
+    monkeypatch.setattr(skill_manage_module, "refresh_skills_system_prompt_cache_async", _refresh)
     monkeypatch.setattr(skill_manage_module, "scan_skill_content", lambda *args, **kwargs: _async_result("allow", "ok"))
 
     runtime = SimpleNamespace(context={"thread_id": "thread-1"}, config={"configurable": {"thread_id": "thread-1"}})
@@ -123,7 +133,12 @@ def test_skill_manage_sync_wrapper_supported(monkeypatch, tmp_path):
     )
     monkeypatch.setattr("deerflow.config.get_app_config", lambda: config)
     monkeypatch.setattr("deerflow.skills.manager.get_app_config", lambda: config)
-    monkeypatch.setattr(skill_manage_module, "clear_skills_system_prompt_cache", lambda: None)
+    refresh_calls = []
+
+    async def _refresh():
+        refresh_calls.append("refresh")
+
+    monkeypatch.setattr(skill_manage_module, "refresh_skills_system_prompt_cache_async", _refresh)
     monkeypatch.setattr(skill_manage_module, "scan_skill_content", lambda *args, **kwargs: _async_result("allow", "ok"))
 
     runtime = SimpleNamespace(context={"thread_id": "thread-sync"}, config={"configurable": {"thread_id": "thread-sync"}})
@@ -135,6 +150,7 @@ def test_skill_manage_sync_wrapper_supported(monkeypatch, tmp_path):
     )
 
     assert "Created custom skill" in result
+    assert refresh_calls == ["refresh"]
 
 
 def test_skill_manage_rejects_support_path_traversal(monkeypatch, tmp_path):
@@ -146,7 +162,11 @@ def test_skill_manage_rejects_support_path_traversal(monkeypatch, tmp_path):
     monkeypatch.setattr("deerflow.config.get_app_config", lambda: config)
     monkeypatch.setattr("deerflow.skills.manager.get_app_config", lambda: config)
     monkeypatch.setattr("deerflow.skills.security_scanner.get_app_config", lambda: config)
-    monkeypatch.setattr(skill_manage_module, "clear_skills_system_prompt_cache", lambda: None)
+
+    async def _refresh():
+        return None
+
+    monkeypatch.setattr(skill_manage_module, "refresh_skills_system_prompt_cache_async", _refresh)
     monkeypatch.setattr(skill_manage_module, "scan_skill_content", lambda *args, **kwargs: _async_result("allow", "ok"))
 
     runtime = SimpleNamespace(context={"thread_id": "thread-1"}, config={"configurable": {"thread_id": "thread-1"}})

backend/tests/test_skills_custom_router.py

@@ -1,4 +1,5 @@
 import json
+from pathlib import Path
 from types import SimpleNamespace
 
 from fastapi import FastAPI
@@ -6,6 +7,7 @@ from fastapi.testclient import TestClient
 
 from app.gateway.routers import skills as skills_router
 from deerflow.skills.manager import get_skill_history_file
+from deerflow.skills.types import Skill
 
 
 def _skill_content(name: str, description: str = "Demo skill") -> str:
@@ -18,6 +20,20 @@ async def _async_scan(decision: str, reason: str):
     return ScanResult(decision=decision, reason=reason)
 
 
+def _make_skill(name: str, *, enabled: bool) -> Skill:
+    skill_dir = Path(f"/tmp/{name}")
+    return Skill(
+        name=name,
+        description=f"Description for {name}",
+        license="MIT",
+        skill_dir=skill_dir,
+        skill_file=skill_dir / "SKILL.md",
+        relative_path=Path(name),
+        category="public",
+        enabled=enabled,
+    )
+
+
 def test_custom_skills_router_lifecycle(monkeypatch, tmp_path):
     skills_root = tmp_path / "skills"
     custom_dir = skills_root / "custom" / "demo-skill"
@@ -30,7 +46,12 @@ def test_custom_skills_router_lifecycle(monkeypatch, tmp_path):
     monkeypatch.setattr("deerflow.config.get_app_config", lambda: config)
     monkeypatch.setattr("deerflow.skills.manager.get_app_config", lambda: config)
     monkeypatch.setattr("app.gateway.routers.skills.scan_skill_content", lambda *args, **kwargs: _async_scan("allow", "ok"))
-    monkeypatch.setattr("app.gateway.routers.skills.clear_skills_system_prompt_cache", lambda: None)
+    refresh_calls = []
+
+    async def _refresh():
+        refresh_calls.append("refresh")
+
+    monkeypatch.setattr("app.gateway.routers.skills.refresh_skills_system_prompt_cache_async", _refresh)
 
     app = FastAPI()
     app.include_router(skills_router.router)
@@ -58,6 +79,7 @@ def test_custom_skills_router_lifecycle(monkeypatch, tmp_path):
         rollback_response = client.post("/api/skills/custom/demo-skill/rollback", json={"history_index": -1})
         assert rollback_response.status_code == 200
         assert rollback_response.json()["description"] == "Demo skill"
+        assert refresh_calls == ["refresh", "refresh"]
 
 
 def test_custom_skill_rollback_blocked_by_scanner(monkeypatch, tmp_path):
@@ -77,7 +99,11 @@ def test_custom_skill_rollback_blocked_by_scanner(monkeypatch, tmp_path):
         '{"action":"human_edit","prev_content":' + json.dumps(original_content) + ',"new_content":' + json.dumps(edited_content) + "}\n",
         encoding="utf-8",
     )
-    monkeypatch.setattr("app.gateway.routers.skills.clear_skills_system_prompt_cache", lambda: None)
+
+    async def _refresh():
+        return None
+
+    monkeypatch.setattr("app.gateway.routers.skills.refresh_skills_system_prompt_cache_async", _refresh)
 
     async def _scan(*args, **kwargs):
         from deerflow.skills.security_scanner import ScanResult
@@ -112,7 +138,12 @@ def test_custom_skill_delete_preserves_history_and_allows_restore(monkeypatch, t
     monkeypatch.setattr("deerflow.config.get_app_config", lambda: config)
     monkeypatch.setattr("deerflow.skills.manager.get_app_config", lambda: config)
     monkeypatch.setattr("app.gateway.routers.skills.scan_skill_content", lambda *args, **kwargs: _async_scan("allow", "ok"))
-    monkeypatch.setattr("app.gateway.routers.skills.clear_skills_system_prompt_cache", lambda: None)
+    refresh_calls = []
+
+    async def _refresh():
+        refresh_calls.append("refresh")
+
+    monkeypatch.setattr("app.gateway.routers.skills.refresh_skills_system_prompt_cache_async", _refresh)
 
     app = FastAPI()
     app.include_router(skills_router.router)
@@ -130,3 +161,37 @@ def test_custom_skill_delete_preserves_history_and_allows_restore(monkeypatch, t
         assert rollback_response.status_code == 200
         assert rollback_response.json()["description"] == "Demo skill"
         assert (custom_dir / "SKILL.md").read_text(encoding="utf-8") == original_content
+        assert refresh_calls == ["refresh", "refresh"]
+
+
+def test_update_skill_refreshes_prompt_cache_before_return(monkeypatch, tmp_path):
+    config_path = tmp_path / "extensions_config.json"
+    enabled_state = {"value": True}
+    refresh_calls = []
+
+    def _load_skills(*, enabled_only: bool):
+        skill = _make_skill("demo-skill", enabled=enabled_state["value"])
+        if enabled_only and not skill.enabled:
+            return []
+        return [skill]
+
+    async def _refresh():
+        refresh_calls.append("refresh")
+        enabled_state["value"] = False
+
+    monkeypatch.setattr("app.gateway.routers.skills.load_skills", _load_skills)
+    monkeypatch.setattr("app.gateway.routers.skills.get_extensions_config", lambda: SimpleNamespace(mcp_servers={}, skills={}))
+    monkeypatch.setattr("app.gateway.routers.skills.reload_extensions_config", lambda: None)
+    monkeypatch.setattr(skills_router.ExtensionsConfig, "resolve_config_path", staticmethod(lambda: config_path))
+    monkeypatch.setattr("app.gateway.routers.skills.refresh_skills_system_prompt_cache_async", _refresh)
+
+    app = FastAPI()
+    app.include_router(skills_router.router)
+
+    with TestClient(app) as client:
+        response = client.put("/api/skills/demo-skill", json={"enabled": False})
+
+    assert response.status_code == 200
+    assert response.json()["enabled"] is False
+    assert refresh_calls == ["refresh"]
+    assert json.loads(config_path.read_text(encoding="utf-8")) == {"mcpServers": {}, "skills": {"demo-skill": {"enabled": False}}}