feat(skills): 自我进化后端 — curator 配置可编辑 + 运行日志可读
后端骨架: - curator.py / usage.py / skill_tools.py:基于使用计数的生命周期管理 + LLM 合并/归档建议(同事已有原型,集中提交) - skill_evolution_config.py:CuratorConfig 嵌套模型 - app.py:启动时按间隔触发 curator 后台线程 - tools.py:开启自我进化时一并注册 skill_list / skill_view 工具 - skill_manage_tool.py:agent 创建技能时标记 source=agent 本次新增: - skill_evolution_runtime.py:skill_evolution.json 读写,原子写入 - app_config.py:把 overrides 深合并到 AppConfig.skill_evolution, 并把 overrides 的 mtime 纳入缓存失效条件,前端 PUT 后热生效 - curator_log.py:进程内 ring buffer (maxlen=200),所有 record/get 操作内部兜异常,保证 logging 永远不会让 curator 跑挂 - curator.py 关键节点插桩:run_started / 自动转换计数 / 候选数 / LLM agent invoke / 解析结果 / archive 动作 / run complete - routers/skills.py:GET/PUT /api/curator/config(写到 skill_evolution.json + reset_app_config)+ GET /api/curator/logs 测试: - tests/test_skill_evolution_runtime.py:overrides 往返、损坏 JSON 容错、AppConfig 合并、ring buffer 线程安全、record 异常吞咽 杂项: - .gitignore:忽略 .deer-flow/* 与 skills/* 等运行时目录 - uv.lock:跟随依赖锁更新 - 清理已废弃的 agent runtime 数据 SOUL.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
230eec1baf
commit
9b6b94d919
14 files changed
+3981
-2698
No files matched your search
@@ -0,0 +1,440 @@
|
||||
"""Skill curator — automatic lifecycle transitions and LLM consolidation pass."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
import re
|
||||
import tempfile
|
||||
import threading
|
||||
from datetime import UTC, datetime, timedelta
|
||||
from pathlib import Path
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
_CURATOR_STATE_FILENAME = ".curator_state"
|
||||
|
||||
|
||||
def _get_skills_root() -> Path:
|
||||
from deerflow.skills.storage import get_or_new_skill_storage
|
||||
|
||||
return Path(get_or_new_skill_storage().get_skills_root_path())
|
||||
|
||||
|
||||
def _curator_state_path() -> Path:
|
||||
return _get_skills_root() / _CURATOR_STATE_FILENAME
|
||||
|
||||
|
||||
def _read_curator_state() -> dict:
|
||||
path = _curator_state_path()
|
||||
if not path.exists():
|
||||
return {"run_count": 0, "paused": False}
|
||||
try:
|
||||
return json.loads(path.read_text(encoding="utf-8"))
|
||||
except Exception:
|
||||
return {"run_count": 0, "paused": False}
|
||||
|
||||
|
||||
def _write_curator_state(state: dict) -> None:
|
||||
path = _curator_state_path()
|
||||
try:
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
tmp_fd, tmp_path = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
|
||||
try:
|
||||
with os.fdopen(tmp_fd, "w", encoding="utf-8") as f:
|
||||
json.dump(state, f, indent=2, default=str)
|
||||
os.replace(tmp_path, path)
|
||||
except Exception:
|
||||
try:
|
||||
os.unlink(tmp_path)
|
||||
except Exception:
|
||||
pass
|
||||
raise
|
||||
except Exception:
|
||||
logger.debug("Failed to write curator state", exc_info=True)
|
||||
|
||||
|
||||
def _get_curator_config():
|
||||
try:
|
||||
from deerflow.config import get_app_config
|
||||
|
||||
config = get_app_config()
|
||||
skill_evo = getattr(config, "skill_evolution", None)
|
||||
return getattr(skill_evo, "curator", None)
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
|
||||
def should_run_now() -> bool:
|
||||
"""Return True if the curator interval has elapsed and it is not paused."""
|
||||
curator_cfg = _get_curator_config()
|
||||
if curator_cfg is None or not getattr(curator_cfg, "enabled", True):
|
||||
return False
|
||||
state = _read_curator_state()
|
||||
if state.get("paused"):
|
||||
return False
|
||||
last_run = state.get("last_run_at")
|
||||
if not last_run:
|
||||
return True
|
||||
interval_hours = getattr(curator_cfg, "interval_hours", 168)
|
||||
try:
|
||||
last_dt = datetime.fromisoformat(last_run)
|
||||
return datetime.now(UTC) >= last_dt + timedelta(hours=interval_hours)
|
||||
except Exception:
|
||||
return True
|
||||
|
||||
|
||||
def apply_automatic_transitions(now: datetime | None = None) -> dict:
|
||||
"""Pure age-based state transitions — no LLM involved.
|
||||
|
||||
Only processes skills with source=='agent'. Skips pinned skills.
|
||||
Returns counters: {marked_stale, archived, checked}.
|
||||
"""
|
||||
from deerflow.skills.usage import STATE_ACTIVE, STATE_ARCHIVED, STATE_STALE, agent_created_entries, latest_activity_at, set_state
|
||||
|
||||
if now is None:
|
||||
now = datetime.now(UTC)
|
||||
|
||||
curator_cfg = _get_curator_config()
|
||||
stale_days = getattr(curator_cfg, "stale_after_days", 30) if curator_cfg else 30
|
||||
archive_days = getattr(curator_cfg, "archive_after_days", 90) if curator_cfg else 90
|
||||
|
||||
entries = agent_created_entries()
|
||||
counters = {"marked_stale": 0, "archived": 0, "checked": len(entries)}
|
||||
|
||||
for name, entry in entries.items():
|
||||
if entry.get("pinned"):
|
||||
continue
|
||||
last_activity_str = latest_activity_at(name)
|
||||
if not last_activity_str:
|
||||
continue
|
||||
try:
|
||||
last_dt = datetime.fromisoformat(last_activity_str)
|
||||
if last_dt.tzinfo is None:
|
||||
last_dt = last_dt.replace(tzinfo=UTC)
|
||||
except Exception:
|
||||
continue
|
||||
|
||||
days_idle = (now - last_dt).days
|
||||
current_state = entry.get("state", STATE_ACTIVE)
|
||||
|
||||
if days_idle >= archive_days and current_state != STATE_ARCHIVED:
|
||||
set_state(name, STATE_ARCHIVED)
|
||||
counters["archived"] += 1
|
||||
elif days_idle >= stale_days and current_state == STATE_ACTIVE:
|
||||
set_state(name, STATE_STALE)
|
||||
counters["marked_stale"] += 1
|
||||
|
||||
return counters
|
||||
|
||||
|
||||
def _render_candidate_list() -> str:
|
||||
from deerflow.skills.usage import STATE_ARCHIVED, all_entries
|
||||
|
||||
entries = {k: v for k, v in all_entries().items() if v.get("source") == "agent" and v.get("state") != STATE_ARCHIVED}
|
||||
if not entries:
|
||||
return "No agent-created active skills found."
|
||||
lines = []
|
||||
for name, entry in sorted(entries.items()):
|
||||
state = entry.get("state", "active")
|
||||
use = entry.get("use_count", 0)
|
||||
view = entry.get("view_count", 0)
|
||||
patch = entry.get("patch_count", 0)
|
||||
last = entry.get("last_used_at") or entry.get("created_at") or "unknown"
|
||||
lines.append(f"- {name} [state={state}, use={use}, view={view}, patches={patch}, last_active={last}]")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
_CURATOR_REVIEW_PROMPT = (
|
||||
"You are running as DeerFlow's background skill CURATOR. This is an "
|
||||
"UMBRELLA-BUILDING consolidation pass, not a passive audit and not a "
|
||||
"duplicate-finder.\n\n"
|
||||
"The goal of the skill collection is a LIBRARY OF CLASS-LEVEL "
|
||||
"INSTRUCTIONS AND EXPERIENTIAL KNOWLEDGE. A collection of hundreds of "
|
||||
"narrow skills where each one captures one session's specific bug is "
|
||||
"a FAILURE of the library — not a feature. An agent searching skills "
|
||||
"matches on descriptions, not on exact names; one broad umbrella "
|
||||
"skill with labeled subsections beats five narrow siblings for "
|
||||
"discoverability, not the other way around.\n\n"
|
||||
"The right target shape is CLASS-LEVEL skills with rich SKILL.md "
|
||||
"bodies + `references/`, `templates/`, and `scripts/` subfiles for "
|
||||
"session-specific detail — not one-session-one-skill micro-entries.\n\n"
|
||||
"Hard rules — do not violate:\n"
|
||||
"1. DO NOT touch public (built-in) skills. The candidate list below "
|
||||
"is already filtered to agent-created custom skills only.\n"
|
||||
"2. DO NOT delete any skill. Archiving (moving the skill's directory "
|
||||
"into the .archive/ folder under the skills root) is the maximum "
|
||||
"destructive action. Archives are recoverable; deletion is not.\n"
|
||||
"3. DO NOT touch skills shown as pinned=yes. Skip them entirely.\n"
|
||||
"4. DO NOT use usage counters as a reason to skip consolidation. The "
|
||||
"counters are new and often mostly zero. Judge overlap on CONTENT, "
|
||||
"not on use_count. 'use=0' is not evidence a skill is valuable; it's "
|
||||
"absence of evidence either way.\n"
|
||||
"5. DO NOT reject consolidation on the grounds that 'each skill has "
|
||||
"a distinct trigger'. Pairwise distinctness is the wrong bar. The "
|
||||
"right bar is: 'would a human maintainer write this as N separate "
|
||||
"skills, or as one skill with N labeled subsections?' When the "
|
||||
"answer is the latter, merge.\n\n"
|
||||
"How to work — not optional:\n"
|
||||
"1. Scan the full candidate list. Identify PREFIX CLUSTERS (skills "
|
||||
"sharing a first word or domain keyword). Examples you are likely "
|
||||
"to find: search-*, code-*, data-*, api-*, file-*, analysis-*, "
|
||||
"workflow-*, report-*, monitor-*, debug-*, python-*, security-*, etc. "
|
||||
"Expect 10-25 clusters.\n"
|
||||
"2. For each cluster with 2+ members, do NOT ask 'are these pairs "
|
||||
"overlapping?' — ask 'what is the UMBRELLA CLASS these skills all "
|
||||
"serve? Would a maintainer name that class and write one skill for "
|
||||
"it?' If yes, pick (or create) the umbrella and absorb the siblings "
|
||||
"into it.\n"
|
||||
"3. Three ways to consolidate — use the right one per cluster:\n"
|
||||
" a. MERGE INTO EXISTING UMBRELLA — one skill in the cluster is "
|
||||
"already broad enough to be the umbrella. Patch it to add a labeled "
|
||||
"section for each sibling's unique insight, then archive the "
|
||||
"siblings.\n"
|
||||
" b. CREATE A NEW UMBRELLA SKILL.md — no existing member is broad "
|
||||
"enough. Create a new class-level skill whose SKILL.md covers the "
|
||||
"shared workflow and has short labeled subsections. Archive the "
|
||||
"now-absorbed narrow siblings.\n"
|
||||
" c. DEMOTE TO REFERENCES/TEMPLATES/SCRIPTS — a sibling has "
|
||||
"narrow-but-valuable session-specific content. Move it into the "
|
||||
"umbrella's appropriate support directory:\n"
|
||||
" • `references/<topic>.md` for session-specific detail OR "
|
||||
"condensed knowledge banks (quoted research, API docs excerpts, "
|
||||
"domain notes, provider quirks, reproduction recipes)\n"
|
||||
" • `templates/<name>.<ext>` for starter files meant to be "
|
||||
"copied and modified\n"
|
||||
" • `scripts/<name>.<ext>` for statically re-runnable actions "
|
||||
"(verification scripts, fixture generators, probes)\n"
|
||||
" Then archive the old sibling.\n"
|
||||
"4. Also flag skills whose NAME is too narrow (contains a specific "
|
||||
"issue number, a feature codename, a specific error string, an "
|
||||
"'audit' / 'diagnosis' / 'salvage' session artifact). These almost "
|
||||
"always belong as a subsection or support file under a class-level "
|
||||
"umbrella.\n"
|
||||
"5. Iterate. After one consolidation round, scan the remaining set "
|
||||
"and look for the NEXT umbrella opportunity. Don't stop after 3 "
|
||||
"merges.\n\n"
|
||||
"'keep' is a legitimate decision ONLY when the skill is already a "
|
||||
"class-level umbrella and none of the proposed merges would improve "
|
||||
"discoverability. 'This is narrow but distinct from its siblings' "
|
||||
"is NOT a reason to keep — it's a reason to move it under an "
|
||||
"umbrella as a subsection or support file.\n\n"
|
||||
"Expected output: real umbrella-ification. Process every obvious "
|
||||
"cluster. If you end the pass with fewer than 10 archives, you "
|
||||
"stopped too early — go back and look at the clusters you left "
|
||||
"alone.\n\n"
|
||||
"When done, write a human summary AND a structured machine-readable "
|
||||
"block so downstream tooling can distinguish consolidation from "
|
||||
"pruning. Format EXACTLY:\n\n"
|
||||
"## Structured summary (required)\n"
|
||||
"```yaml\n"
|
||||
"consolidations:\n"
|
||||
" - from: <old-skill-name>\n"
|
||||
" into: <umbrella-skill-name>\n"
|
||||
" reason: <one short sentence — why merged, not just 'similar'>\n"
|
||||
"prunings:\n"
|
||||
" - name: <skill-name>\n"
|
||||
" reason: <one short sentence — why archived with no merge target>\n"
|
||||
"```\n\n"
|
||||
"Every skill you moved to .archive/ MUST appear in exactly one of the "
|
||||
"two lists. If you consolidated X into umbrella Y (patched Y, wrote "
|
||||
"a references file to Y, or created Y with X's content absorbed), X "
|
||||
"goes under `consolidations` with `into: Y`. If you archived X with "
|
||||
"no absorption — truly stale, irrelevant, or obsolete — X goes under "
|
||||
"`prunings`. Leave a list empty (`consolidations: []`) if none. Do "
|
||||
"not omit the block. The block comes AFTER your human-readable "
|
||||
"summary of clusters processed, patches made, and decisions left alone."
|
||||
)
|
||||
|
||||
|
||||
def _make_skill_archive_tool():
|
||||
"""Curator-only tool: move a skill directory to .archive/ (recoverable)."""
|
||||
from langchain.tools import tool as lc_tool
|
||||
|
||||
from deerflow.skills import curator_log
|
||||
from deerflow.skills.storage import get_or_new_skill_storage
|
||||
|
||||
@lc_tool("skill_archive")
|
||||
def _skill_archive(name: str) -> str:
|
||||
"""Move an agent-created skill to the .archive/ directory (recoverable). Use this instead of delete.
|
||||
|
||||
Args:
|
||||
name: The skill name to archive.
|
||||
"""
|
||||
from deerflow.skills.usage import STATE_ARCHIVED, get_entry, set_state
|
||||
|
||||
storage = get_or_new_skill_storage()
|
||||
if not storage.custom_skill_exists(name):
|
||||
curator_log.record("warning", f"skill_archive: '{name}' not found or already archived")
|
||||
return f"Skill '{name}' not found or already archived."
|
||||
if get_entry(name).get("pinned"):
|
||||
curator_log.record("info", f"skill_archive: '{name}' is pinned — skipping")
|
||||
return f"Skill '{name}' is pinned — skipping."
|
||||
skill_dir = storage.get_custom_skill_dir(name)
|
||||
archive_root = Path(storage.get_skills_root_path()) / "custom" / ".archive"
|
||||
archive_root.mkdir(parents=True, exist_ok=True)
|
||||
stamp = datetime.now(UTC).strftime("%Y%m%d-%H%M%S")
|
||||
dest = archive_root / f"{name}-{stamp}"
|
||||
try:
|
||||
skill_dir.rename(dest)
|
||||
except Exception as e:
|
||||
curator_log.record("error", f"skill_archive: archive failed for '{name}': {e}")
|
||||
return f"Archive failed: {e}"
|
||||
set_state(name, STATE_ARCHIVED)
|
||||
curator_log.record("info", f"Archived '{name}' → custom/.archive/{dest.name}")
|
||||
return f"Archived '{name}' → custom/.archive/{dest.name}."
|
||||
|
||||
return _skill_archive
|
||||
|
||||
|
||||
def _run_llm_review(candidate_list: str) -> str:
|
||||
"""Run the curator consolidation pass as a React agent with skill tools bound."""
|
||||
from deerflow.skills import curator_log
|
||||
|
||||
try:
|
||||
from langchain_core.messages import HumanMessage
|
||||
from langgraph.prebuilt import create_react_agent
|
||||
|
||||
from deerflow.models import create_chat_model
|
||||
from deerflow.tools.builtins.skill_tools import skill_list_tool, skill_view_tool
|
||||
from deerflow.tools.skill_manage_tool import skill_manage_tool
|
||||
|
||||
model = create_chat_model()
|
||||
tools = [skill_list_tool, skill_view_tool, skill_manage_tool, _make_skill_archive_tool()]
|
||||
agent = create_react_agent(model, tools)
|
||||
|
||||
curator_log.record("info", "LLM review: invoking React agent")
|
||||
prompt = _CURATOR_REVIEW_PROMPT + f"\n\nSkill candidates for this pass:\n{candidate_list}"
|
||||
result = agent.invoke({"messages": [HumanMessage(content=prompt)]})
|
||||
|
||||
messages = result.get("messages", [])
|
||||
for msg in reversed(messages):
|
||||
if not getattr(msg, "tool_calls", None):
|
||||
content = getattr(msg, "content", "")
|
||||
if isinstance(content, str) and content.strip():
|
||||
curator_log.record("info", "LLM review: agent returned final answer")
|
||||
return content
|
||||
if isinstance(content, list):
|
||||
text = " ".join(
|
||||
block.get("text", "") if isinstance(block, dict) else str(block)
|
||||
for block in content
|
||||
).strip()
|
||||
curator_log.record("info", "LLM review: agent returned final answer")
|
||||
return text
|
||||
curator_log.record("warning", "LLM review: no final assistant message produced")
|
||||
return ""
|
||||
except Exception as e:
|
||||
logger.warning("Curator LLM review failed: %s", e)
|
||||
curator_log.record("warning", f"LLM review failed: {e}")
|
||||
return ""
|
||||
|
||||
|
||||
def _parse_structured_summary(text: str) -> dict:
|
||||
pattern = re.compile(r"```yaml\s*(.*?)```", re.DOTALL)
|
||||
match = pattern.search(text)
|
||||
if not match:
|
||||
return {"consolidations": [], "prunings": []}
|
||||
try:
|
||||
import yaml
|
||||
|
||||
data = yaml.safe_load(match.group(1)) or {}
|
||||
return {"consolidations": data.get("consolidations") or [], "prunings": data.get("prunings") or []}
|
||||
except Exception:
|
||||
return {"consolidations": [], "prunings": []}
|
||||
|
||||
|
||||
def run_curator_review() -> dict:
|
||||
"""Main curator run: automatic transitions → LLM consolidation → write state."""
|
||||
from deerflow.skills import curator_log
|
||||
|
||||
curator_log.start_new_run()
|
||||
|
||||
now = datetime.now(UTC)
|
||||
logger.info("Curator: starting run at %s", now.isoformat())
|
||||
curator_log.record("info", f"Curator starting run at {now.isoformat()}")
|
||||
|
||||
transition_counters = apply_automatic_transitions(now)
|
||||
logger.info("Curator: transitions=%s", transition_counters)
|
||||
curator_log.record(
|
||||
"info",
|
||||
(
|
||||
f"Age-based transitions: checked={transition_counters['checked']}, "
|
||||
f"marked_stale={transition_counters['marked_stale']}, "
|
||||
f"archived={transition_counters['archived']}"
|
||||
),
|
||||
)
|
||||
|
||||
candidate_list = _render_candidate_list()
|
||||
candidate_line_count = 0 if not candidate_list.strip() else len([line for line in candidate_list.splitlines() if line.startswith("- ")])
|
||||
curator_log.record("info", f"Candidates for LLM review: {candidate_line_count} skill(s)")
|
||||
|
||||
llm_text = _run_llm_review(candidate_list)
|
||||
suggestions = _parse_structured_summary(llm_text)
|
||||
curator_log.record(
|
||||
"info",
|
||||
(
|
||||
f"LLM suggestions parsed: consolidations={len(suggestions['consolidations'])}, "
|
||||
f"prunings={len(suggestions['prunings'])}"
|
||||
),
|
||||
)
|
||||
|
||||
state = _read_curator_state()
|
||||
state["last_run_at"] = now.isoformat()
|
||||
state["run_count"] = state.get("run_count", 0) + 1
|
||||
state["last_run_summary"] = (
|
||||
f"auto: {transition_counters['marked_stale']} marked stale, "
|
||||
f"{transition_counters['archived']} archived; "
|
||||
f"llm: {len(suggestions['consolidations'])} consolidations suggested"
|
||||
)
|
||||
state["last_consolidation_suggestions"] = suggestions
|
||||
_write_curator_state(state)
|
||||
|
||||
logger.info("Curator: run complete — %s", state["last_run_summary"])
|
||||
curator_log.record("info", f"Curator run complete — {state['last_run_summary']}")
|
||||
return {"transitions": transition_counters, "suggestions": suggestions}
|
||||
|
||||
|
||||
def _curator_thread_target() -> None:
|
||||
from deerflow.skills import curator_log
|
||||
|
||||
try:
|
||||
run_curator_review()
|
||||
except Exception as exc:
|
||||
logger.exception("Curator background run failed")
|
||||
curator_log.record("error", f"Curator background run failed: {exc}")
|
||||
|
||||
|
||||
async def maybe_run_curator() -> None:
|
||||
"""Async entry called at startup — spawns a daemon thread if the interval has elapsed."""
|
||||
if not should_run_now():
|
||||
return
|
||||
logger.info("Curator: interval elapsed, spawning background thread")
|
||||
thread = threading.Thread(target=_curator_thread_target, daemon=True, name="skill-curator")
|
||||
thread.start()
|
||||
|
||||
|
||||
def get_curator_status() -> dict:
|
||||
"""Return curator state for the API status endpoint."""
|
||||
from deerflow.skills.usage import STATE_ACTIVE, STATE_ARCHIVED, STATE_STALE, agent_created_entries
|
||||
|
||||
state = _read_curator_state()
|
||||
entries = agent_created_entries()
|
||||
counts: dict[str, int] = {STATE_ACTIVE: 0, STATE_STALE: 0, STATE_ARCHIVED: 0}
|
||||
for entry in entries.values():
|
||||
s = entry.get("state", STATE_ACTIVE)
|
||||
counts[s] = counts.get(s, 0) + 1
|
||||
|
||||
return {
|
||||
"enabled": _get_curator_config() is not None and getattr(_get_curator_config(), "enabled", True),
|
||||
"run_count": state.get("run_count", 0),
|
||||
"last_run_at": state.get("last_run_at"),
|
||||
"last_run_summary": state.get("last_run_summary"),
|
||||
"paused": state.get("paused", False),
|
||||
"agent_created_skills": {
|
||||
"total": len(entries),
|
||||
"active": counts[STATE_ACTIVE],
|
||||
"stale": counts[STATE_STALE],
|
||||
"archived": counts[STATE_ARCHIVED],
|
||||
},
|
||||
}
|
||||
Reference in new issue
Block a user