fix(skills): load categories independently and support non-git checkouts

SkillsManager refused to start when the local skills directory was not a
git repository (cloning into a non-empty path fails), and reload_skills()
returned early when injection/ was missing, so device and feature skills
never loaded. reload_packet_analysis_protocols() had the opposite bug:
an empty result wiped the registry while still reporting success.

- initialize(): accept a non-empty directory without .git as a local-only
  source (skip automatic updates, keep loading files); degrade to local
  files when GitPython is unavailable.
- _update_if_needed(): re-create/clone when the local directory vanished
  or moved, instead of reusing a stale handle forever.
- reload_skills(): injection, device and feature load independently; a
  missing category keeps its previously loaded entries.
- reload_packet_analysis_protocols(): an empty/missing directory keeps
  the existing registry and reports failure.
- reload_skills_repository(): drop the console guard cache so
  config/console_guard.txt applies on reload.

MCP device_skill_get now exposes the category filter, documents the
single-file (topic-less) layout, and returns a sections list for
index/summary of skills that have no topics/issues. An uninitialized
skills repository fails with a clear error instead of an empty list.
This commit is contained in:
yueguobin committed 2026-11-01 23:09:38 +08:00
1 parent 5ed252455d
commit 21fb84e91c
8 files changed
+338 -64

No files matched your search

+98 -58
View File
@@ -101,33 +101,60 @@ class SkillsManager:
Initialize the skills repository.
Behavior:
- If no local repo → clone from remote
- If local repo exists → open and run _update_if_needed()
- No local directory → create it and clone from remote
- Local git repo → open and run _update_if_needed()
- Local directory without .git → use it as a local-only source
(cloning into a non-empty directory cannot work, and local
content must stay usable without Git)
Returns:
True if successful, False otherwise
"""
try:
if not self.local_path.exists():
logger.info(f"Creating skills directory: {self.local_path}")
self.local_path.mkdir(parents=True, exist_ok=True)
if not (self.local_path / ".git").exists():
return self._clone()
# Repo exists, open it
try:
self._repo = git.Repo(self.local_path)
except Exception as e:
logger.error(f"Failed to open existing repository: {e}")
if not self._ensure_repo():
return False
self._update_if_needed()
return True
except Exception as e:
logger.error(f"Failed to initialize skills repository: {e}")
return False
def _ensure_repo(self) -> bool:
"""Prepare the local skills directory and open/clone the repo.
A non-empty directory without .git is accepted as a local-only
skills source: automatic updates are skipped, the files still load.
"""
if not self.local_path.exists():
logger.info(f"Creating skills directory: {self.local_path}")
self.local_path.mkdir(parents=True, exist_ok=True)
if not GIT_AVAILABLE:
logger.warning("GitPython is not installed; using local files without automatic updates")
self._repo = None
return True
if not (self.local_path / ".git").exists():
try:
is_empty = not any(self.local_path.iterdir())
except OSError:
is_empty = True
if is_empty:
return self._clone()
logger.warning(
"Skills directory %s is not a git repository; using local files without automatic updates",
self.local_path,
)
self._repo = None
return True
try:
self._repo = git.Repo(self.local_path)
except Exception as e:
logger.error(f"Failed to open existing repository: {e}")
return False
return True
def _update_if_needed(self) -> None:
"""
Check local repo status and pull updates if safe.
@@ -137,7 +164,15 @@ class SkillsManager:
- Up to date → nothing
- Network error → use existing files, log warning
"""
if not GIT_AVAILABLE or self._repo is None:
if not GIT_AVAILABLE:
return
if not self.local_path.exists():
# The directory can disappear or move between reloads (manual
# clone/rename); re-create/clone instead of failing forever.
if not self._ensure_repo():
logger.warning("Skills repository is unavailable; using local files")
return
if self._repo is None:
return
# Check for uncommitted changes
@@ -190,62 +225,64 @@ class SkillsManager:
def reload_skills(self) -> bool:
"""
Hot reload skills from YAML files into the registry.
Hot reload skills from YAML files into the registries.
Loads the latest skill definitions from YAML files and updates
the INJECTION_SKILLS_REGISTRY.
Injection, device and feature skills load independently: a missing
or empty directory keeps the previously loaded entries of that
category instead of blocking the others.
Returns:
True if successful, False otherwise
True if at least one category loaded, False otherwise
"""
try:
# Import here to avoid circular dependency
from .registry import INJECTION_SKILLS_REGISTRY, SKILLS_REGISTRY
# Load new injection skills from YAML files
new_injection_skills = self.loader.load_injection_skills()
# Load and validate injection skills (invalid ones are dropped
# before merging; validate_skill_format logs the reason).
new_injection_skills = {
skill_key: skill_data
for skill_key, skill_data in self.loader.load_injection_skills().items()
if self.loader.validate_skill_format(skill_data)
}
if not new_injection_skills:
logger.warning("No injection skills loaded, keeping existing skills")
return False
# Validate injection skills (drop invalid ones before merging)
valid_injection_skills = {}
for skill_key, skill_data in new_injection_skills.items():
if self.loader.validate_skill_format(skill_data):
valid_injection_skills[skill_key] = skill_data
else:
logger.error(f"Invalid skill format for {skill_key}, skipping")
if not valid_injection_skills:
logger.warning("No valid injection skills loaded, keeping existing skills")
return False
new_injection_skills = valid_injection_skills
# Load new device skills from YAML files
# Load new device and feature skills from YAML files
new_device_skills = self.loader.load_device_skills()
# Load new feature skills from YAML files
new_feature_skills = self.loader.load_feature_skills()
# Merge device and feature skills into single registry
all_skills = {}
all_skills.update(new_device_skills)
all_skills.update(new_feature_skills)
if not new_injection_skills and not new_device_skills and not new_feature_skills:
logger.warning("No skills loaded from any category, keeping existing skills")
return False
# Update registries (safe replace - never leaves dict empty)
for k in list(INJECTION_SKILLS_REGISTRY):
if k not in new_injection_skills:
del INJECTION_SKILLS_REGISTRY[k]
INJECTION_SKILLS_REGISTRY.update(new_injection_skills)
# Injection: an absent injection/ directory keeps old entries.
if new_injection_skills:
for k in list(INJECTION_SKILLS_REGISTRY):
if k not in new_injection_skills:
del INJECTION_SKILLS_REGISTRY[k]
INJECTION_SKILLS_REGISTRY.update(new_injection_skills)
else:
logger.warning("No valid injection skills loaded, keeping existing injection skills")
for k in list(SKILLS_REGISTRY):
if k not in all_skills:
del SKILLS_REGISTRY[k]
SKILLS_REGISTRY.update(all_skills)
# Device/feature: replace each category that yielded content and
# keep the old entries of a category that yielded none.
if new_device_skills or new_feature_skills:
all_skills: Dict[str, Dict[str, Any]] = {}
all_skills.update(
new_device_skills or {k: v for k, v in SKILLS_REGISTRY.items() if v.get("category") == "device"}
)
all_skills.update(
new_feature_skills or {k: v for k, v in SKILLS_REGISTRY.items() if v.get("category") == "feature"}
)
for k in list(SKILLS_REGISTRY):
if k not in all_skills:
del SKILLS_REGISTRY[k]
SKILLS_REGISTRY.update(all_skills)
else:
logger.warning("No device/feature skills loaded, keeping existing device/feature skills")
logger.info(
f"Loaded {len(new_injection_skills)} injection skills, {len(new_device_skills)} device skills, and {len(new_feature_skills)} feature skills"
f"Loaded {len(new_injection_skills)} injection skills, "
f"{len(new_device_skills)} device skills, and {len(new_feature_skills)} feature skills"
)
return True
except Exception as e:
@@ -256,8 +293,8 @@ class SkillsManager:
"""
Hot reload packet analysis protocol definitions from YAML files.
Loads the latest protocol definitions from YAML files and updates
the PACKET_ANALYSIS_REGISTRY.
An empty result (missing or empty directory) keeps the existing
registry and reports failure, matching the skills/prompts behavior.
Returns:
True if successful, False otherwise
@@ -267,6 +304,9 @@ class SkillsManager:
# Load new packet analysis protocols from YAML files
new_protocols = self.loader.load_packet_analysis_protocols()
if not new_protocols:
logger.warning("No packet analysis protocols loaded, keeping existing protocols")
return False
# Update registry (safe replace - never leaves dict empty)
for k in list(PACKET_ANALYSIS_REGISTRY):
@@ -355,6 +355,11 @@ def get_skills_repository_info() -> dict[str, Any]:
return manager.get_repository_info()
# Descriptive keys that are not content sections; excluded from the
# section list returned for skills that have no topics/issues.
_SKILL_META_KEYS = frozenset({"name", "description", "device_type", "category", "issues", "topics"})
def get_skill(
device_type: str,
category: str | None = None,
@@ -450,6 +455,12 @@ def get_skill(
}
if topics:
result["topics"] = {k: v.get("name", k) for k, v in topics.items()}
else:
# Single-file device/feature skills have no topics: name the
# top-level sections so the index is not an empty shell.
sections = [k for k in skill if k not in _SKILL_META_KEYS]
if sections:
result["sections"] = sections
return result
if detail == "summary":
@@ -472,6 +483,10 @@ def get_skill(
result["topics"] = {
k: {"name": v.get("name", k), "description": v.get("description", "")} for k, v in topics.items()
}
else:
sections = [k for k in skill if k not in _SKILL_META_KEYS]
if sections:
result["sections"] = sections
return result
# Full detail: topic bodies are replaced by the topic index
+11 -2
View File
@@ -2197,6 +2197,7 @@ async def device_skill_get(
Field(description="Skill key exactly as action='list' returns it, e.g. 'frr_vtysh', 'cisco_ios_telnet'"),
] = None,
action: Annotated[str | None, Field(description='"list" to enumerate skills; "get" (default) to fetch one')] = None,
category: Annotated[str | None, Field(description='Optional category filter, e.g. "device" or "feature"')] = None,
topic: Annotated[
str | None,
Field(
@@ -2216,12 +2217,18 @@ async def device_skill_get(
Step 2 returns the base skill plus the topic index; step 3 loads the
targeted body. Pass the key exactly as step 1 returned it.
Devices without topics (single-file skills such as gns3_vpcs_telnet
or nokia_srlinux_cli) are complete at step 2 with the default full
detail — there is no topic step, and detail="index" only lists their
sections (config_commands, display_commands, ...).
category="device" or "feature" narrows both list and get.
Skills carry the operational quirks the generic tools cannot know:
FRR's console lands directly in vtysh (no -c on its ping, 'do' prefixes
inside scripted config), VPCS command syntax, IOS paging pitfalls.
Requires the skills repository to be configured (cloned); when none is
loaded the error says so and action="list" returns an empty set.
Requires the skills repository to be configured (cloned); an
uninitialized repository fails with a clear error, while an empty but
initialized repository returns an empty list.
IF YOUR CLIENT OFFERS SUBAGENTS: on long tasks, delegate steps 1-2
to a subagent and ask it to return the exact command/quirk snippets
@@ -2231,6 +2238,8 @@ async def device_skill_get(
params: dict[str, Any] = {"action": action}
if device_type is not None:
params["device_type"] = device_type
if category is not None:
params["category"] = category
if topic is not None:
params["topic"] = topic
if detail is not None:
+12 -1
View File
@@ -49,12 +49,22 @@ def device_skills_handler(params: dict[str, Any], gns3_ctx: dict[str, Any]) -> d
log.debug("device_skill_get: skills registry unavailable: %s", e)
return {"status": "failed", "error": f"Skills subsystem unavailable: {e}"}
# First call on a fresh server may race the background repository
# load; triggering the (idempotent, retryable) init avoids returning
# an empty list just because the clone has not finished yet.
if not registry.SKILLS_REGISTRY and registry.get_skills_manager() is None:
return {
"status": "failed",
"error": "Skills repository is not initialized. Configure the GNS3-Skills repository "
"(skills_repo_url) and retry — the initial clone may still be running.",
}
action = params.get("action")
if not action:
# No explicit action: list when nothing to get, get otherwise.
action = "list" if not params.get("device_type") else "get"
if action == "list":
skills = registry.list_available_skills()
skills = registry.list_available_skills(params.get("category"))
return {"status": "ok", "count": len(skills), "skills": skills}
device_type = params.get("device_type")
@@ -67,6 +77,7 @@ def device_skills_handler(params: dict[str, Any], gns3_ctx: dict[str, Any]) -> d
result = registry.get_skill(
device_type,
category=params.get("category"),
detail=params.get("detail", "full"),
issue=params.get("issue"),
topic=params.get("topic"),