269 lines
11 KiB
Python
269 lines
11 KiB
Python
"""Post-turn background skill review worker.
|
|
|
|
After a conversation turn completes, SkillReviewMiddleware calls
|
|
``maybe_start_review()``. This module runs a lightweight LLM React agent
|
|
(with skill_manage + skill_list tools) that reads the conversation history
|
|
and decides whether to create or patch skills.
|
|
|
|
Concurrency model: per-thread asyncio.Lock + a single _pending slot.
|
|
If a review is already running for the thread, the newer messages overwrite
|
|
the pending slot; once the current review finishes, it drains that slot.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import asyncio
|
|
import logging
|
|
import textwrap
|
|
from typing import TYPE_CHECKING, Any
|
|
|
|
from langchain_core.messages import BaseMessage
|
|
|
|
if TYPE_CHECKING:
|
|
from deerflow.config.app_config import AppConfig
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
_locks: dict[str, asyncio.Lock] = {}
|
|
_pending: dict[str, list[BaseMessage]] = {}
|
|
|
|
|
|
def _get_lock(thread_id: str) -> asyncio.Lock:
|
|
if thread_id not in _locks:
|
|
_locks[thread_id] = asyncio.Lock()
|
|
return _locks[thread_id]
|
|
|
|
|
|
def extract_tool_call_count(messages: list[BaseMessage]) -> int:
|
|
"""Count total tool calls across all AI messages in the conversation."""
|
|
count = 0
|
|
for msg in messages:
|
|
tool_calls: Any = None
|
|
if hasattr(msg, "tool_calls"):
|
|
tool_calls = msg.tool_calls
|
|
elif isinstance(msg, dict):
|
|
tool_calls = msg.get("tool_calls")
|
|
if tool_calls:
|
|
count += len(tool_calls)
|
|
return count
|
|
|
|
|
|
def _format_messages_for_review(messages: list[BaseMessage], max_messages: int) -> str:
|
|
"""Serialize recent messages to a readable text block for the LLM reviewer."""
|
|
recent = messages[-max_messages:]
|
|
lines: list[str] = []
|
|
for msg in recent:
|
|
role = type(msg).__name__.replace("Message", "")
|
|
content = msg.content if isinstance(msg.content, str) else str(msg.content)
|
|
tool_calls = getattr(msg, "tool_calls", None)
|
|
if tool_calls:
|
|
calls_str = ", ".join(
|
|
f"{tc.name if hasattr(tc, 'name') else tc.get('name', '?')}()"
|
|
for tc in tool_calls
|
|
)
|
|
lines.append(f"[{role}] <tool_calls: {calls_str}>")
|
|
else:
|
|
preview = content[:400].replace("\n", " ")
|
|
lines.append(f"[{role}] {preview}")
|
|
return "\n".join(lines)
|
|
|
|
|
|
_REVIEW_SYSTEM_PROMPT = textwrap.dedent("""\
|
|
You are a skill review agent. Your job is to analyze a completed conversation
|
|
and decide whether any reusable multi-step workflow should be saved as a skill.
|
|
|
|
## Decision rules
|
|
1. Call skill_list first to see existing skills — avoid creating duplicates.
|
|
2. CREATE a new skill if: the conversation demonstrates ANY repeatable workflow
|
|
or technique that could be reused in future tasks — even a single-step pattern
|
|
is worth capturing if it's non-obvious or task-specific knowledge.
|
|
3. PATCH an existing skill if: the conversation revealed a gap, error, or improvement
|
|
to a skill that was already invoked.
|
|
4. DO NOTHING only if: the task was purely data-specific (one-off query with no
|
|
generalizable pattern) or already covered by an existing skill verbatim.
|
|
|
|
## Skill quality bar
|
|
- Name: kebab-case, lowercase letters/digits/hyphens only, max 64 chars.
|
|
Examples: "git-bisect-bug-hunt", "python-venv-setup", "api-load-test".
|
|
- Description: one sentence starting with "When" that states the trigger condition.
|
|
Max 1024 chars. No angle brackets (< >).
|
|
- Content: concise workflow guide (steps, commands, pitfalls) — NOT a transcript.
|
|
- Never embed user-specific data, file paths, or credentials.
|
|
|
|
## SKILL.md format (STRICT — validation will reject any deviation)
|
|
The `content` argument passed to skill_manage must be a valid SKILL.md:
|
|
|
|
```
|
|
---
|
|
name: <exact-same-as-the-name-argument>
|
|
description: <one sentence>
|
|
---
|
|
|
|
<Markdown body with workflow steps>
|
|
```
|
|
|
|
Rules:
|
|
- The `name` field in the frontmatter MUST exactly match the `name` argument
|
|
you pass to skill_manage. If they differ, the call will fail.
|
|
- Only these frontmatter keys are allowed: name, description, license,
|
|
allowed-tools, metadata, compatibility, version, author.
|
|
- The frontmatter block must start with `---` on its own line and end with `---`.
|
|
- Do NOT add extra keys like "tags", "category", "type", etc.
|
|
|
|
## Avoiding duplicate-creation errors
|
|
Before calling skill_manage with action="create":
|
|
1. Always call skill_list first.
|
|
2. If a skill with the same name already exists, use action="patch" instead.
|
|
Creating over an existing skill will raise an error.
|
|
3. If you get a tool error, read the message carefully and fix the issue
|
|
(wrong name, bad frontmatter, duplicate, etc.) before retrying.
|
|
|
|
Be conservative. Fewer high-quality skills beat many noisy ones.
|
|
""")
|
|
|
|
|
|
async def _run_review(thread_id: str, messages: list[BaseMessage], app_config: "AppConfig") -> None:
|
|
"""Core review logic: create_agent with full middleware chain, no 'silent creation' constraint.
|
|
|
|
Uses create_agent (the deerflow agent factory) directly so we can:
|
|
- Reuse the full middleware chain (ToolErrorHandlingMiddleware, etc.)
|
|
- Reuse the full tool set
|
|
- But pass app_config with skill_evolution.enabled=False to strip the
|
|
"Never create skills silently without user confirmation" constraint
|
|
from the system prompt.
|
|
Review instructions are injected via PromptPrefixMiddleware through
|
|
additional_kwargs["prompt_prefix"] on the HumanMessage.
|
|
"""
|
|
from langchain.agents import create_agent
|
|
from langchain_core.messages import HumanMessage
|
|
|
|
from deerflow.agents.lead_agent.prompt import apply_prompt_template
|
|
from deerflow.agents.middlewares.prompt_prefix_middleware import PromptPrefixMiddleware
|
|
from deerflow.agents.middlewares.tool_error_handling_middleware import build_lead_runtime_middlewares
|
|
from deerflow.agents.thread_state import ThreadState
|
|
from deerflow.models import create_chat_model
|
|
from deerflow.tools.tools import get_available_tools
|
|
|
|
evolution_cfg = app_config.skill_evolution
|
|
timeout = evolution_cfg.review_worker.timeout_seconds
|
|
max_messages = evolution_cfg.review_worker.max_messages
|
|
model_name = evolution_cfg.review_worker.model_name
|
|
|
|
conversation_text = _format_messages_for_review(messages, max_messages)
|
|
|
|
# Disable skill_evolution so the system prompt does NOT include
|
|
# "Never create skills silently without user confirmation".
|
|
# Also prevents SkillReviewMiddleware from registering (no recursive reviews).
|
|
review_app_config = app_config.model_copy(deep=True)
|
|
review_app_config.skill_evolution.enabled = False
|
|
|
|
try:
|
|
model = create_chat_model(name=model_name, app_config=review_app_config)
|
|
except Exception:
|
|
logger.warning("skill_review_worker: could not load model %r, aborting review", model_name)
|
|
return
|
|
|
|
tools = get_available_tools(app_config=review_app_config, subagent_enabled=False)
|
|
middlewares = build_lead_runtime_middlewares(app_config=review_app_config)
|
|
middlewares.append(PromptPrefixMiddleware())
|
|
|
|
system_prompt = apply_prompt_template(
|
|
subagent_enabled=False,
|
|
max_concurrent_subagents=0,
|
|
app_config=review_app_config,
|
|
memory_injection_enabled=False,
|
|
)
|
|
|
|
agent = create_agent(
|
|
model=model,
|
|
tools=tools,
|
|
middleware=middlewares,
|
|
system_prompt=system_prompt,
|
|
state_schema=ThreadState,
|
|
)
|
|
|
|
# Review instructions arrive as prompt_prefix: PromptPrefixMiddleware prepends
|
|
# them before every model call without persisting them to state.
|
|
first_message = HumanMessage(
|
|
content=(
|
|
"Review this conversation and apply any skill changes you deem appropriate.\n\n"
|
|
f"<conversation>\n{conversation_text}\n</conversation>"
|
|
),
|
|
additional_kwargs={"prompt_prefix": _REVIEW_SYSTEM_PROMPT},
|
|
)
|
|
|
|
try:
|
|
result = await asyncio.wait_for(
|
|
asyncio.get_event_loop().run_in_executor(
|
|
None,
|
|
lambda: agent.invoke({"messages": [first_message]}),
|
|
),
|
|
timeout=timeout,
|
|
)
|
|
# Log the final AI message so we can see what the review agent decided.
|
|
final_msgs = (result or {}).get("messages", [])
|
|
final_text = ""
|
|
for msg in reversed(final_msgs):
|
|
content = getattr(msg, "content", None)
|
|
if content and isinstance(content, str) and content.strip():
|
|
final_text = content.strip()[:1000]
|
|
break
|
|
logger.info(
|
|
"skill_review_worker: review completed for thread %s — agent said: %s",
|
|
thread_id,
|
|
final_text or "(no text response)",
|
|
)
|
|
except TimeoutError:
|
|
logger.warning("skill_review_worker: review timed out after %ds (thread %s)", timeout, thread_id)
|
|
except Exception:
|
|
logger.exception("skill_review_worker: review failed for thread %s", thread_id)
|
|
|
|
|
|
async def _run_review_with_pending(
|
|
thread_id: str,
|
|
messages: list[BaseMessage],
|
|
app_config: "AppConfig",
|
|
) -> None:
|
|
"""Run one review; if a newer snapshot arrived while we ran, drain it."""
|
|
lock = _get_lock(thread_id)
|
|
async with lock:
|
|
await _run_review(thread_id, messages, app_config)
|
|
|
|
pending = _pending.pop(thread_id, None)
|
|
if pending is not None:
|
|
asyncio.create_task(_run_review_with_pending(thread_id, pending, app_config))
|
|
|
|
|
|
def maybe_start_review(
|
|
thread_id: str,
|
|
messages: list[BaseMessage],
|
|
app_config: "AppConfig",
|
|
) -> bool:
|
|
"""Schedule a background review for ``thread_id``.
|
|
|
|
Returns True if a new task was started, False if queued or skipped.
|
|
"""
|
|
evolution_cfg = app_config.skill_evolution
|
|
if not evolution_cfg.enabled or not evolution_cfg.review_worker.enabled:
|
|
return False
|
|
|
|
tool_count = extract_tool_call_count(messages)
|
|
if tool_count < evolution_cfg.review_worker.min_tool_calls:
|
|
logger.debug(
|
|
"skill_review_worker: skipping review for thread %s (%d tool calls < min %d)",
|
|
thread_id,
|
|
tool_count,
|
|
evolution_cfg.review_worker.min_tool_calls,
|
|
)
|
|
return False
|
|
|
|
lock = _get_lock(thread_id)
|
|
if lock.locked():
|
|
_pending[thread_id] = messages
|
|
logger.debug("skill_review_worker: queued review for thread %s (review in progress)", thread_id)
|
|
return False
|
|
|
|
asyncio.create_task(_run_review_with_pending(thread_id, messages, app_config))
|
|
logger.info("skill_review_worker: started review for thread %s (%d tool calls)", thread_id, tool_count)
|
|
return True
|