282 lines
10 KiB
Python
282 lines
10 KiB
Python
"""Beaver skills catalog loader。
|
||
|
||
第一版目标非常明确：
|
||
|
||
1. 扫描技能目录
|
||
2. 读取 `SKILL.md`
|
||
3. 解析前置元数据
|
||
4. 生成可注入上下文的正文与索引
|
||
|
||
这层不负责：
|
||
1. 动态选择本轮应该启用哪些 skill
|
||
2. skill review / publishing
|
||
3. skill 自动学习
|
||
|
||
这些决策属于 resolver 或更高层工作流。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from pathlib import Path
|
||
from typing import Any
|
||
|
||
from .utils import (
|
||
check_requirements,
|
||
escape_xml,
|
||
get_missing_requirements,
|
||
parse_frontmatter,
|
||
parse_skill_metadata_blob,
|
||
strip_frontmatter,
|
||
)
|
||
|
||
|
||
@dataclass(slots=True)
|
||
class SkillRecord:
|
||
"""单个 skill 的目录级元数据。"""
|
||
|
||
name: str
|
||
path: Path
|
||
source: str
|
||
|
||
|
||
class SkillsLoader:
|
||
"""从 workspace/builtin 目录中发现并读取 skills。"""
|
||
|
||
def __init__(
|
||
self,
|
||
workspace: str | Path,
|
||
*,
|
||
builtin_skills_dir: str | Path | None = None,
|
||
extra_dirs: list[str | Path] | None = None,
|
||
) -> None:
|
||
self.workspace = Path(workspace)
|
||
self.workspace_skills = self.workspace / "skills"
|
||
self.builtin_skills = Path(builtin_skills_dir) if builtin_skills_dir is not None else Path(__file__).resolve().parent.parent / "builtin"
|
||
self.extra_dirs = [Path(item) for item in (extra_dirs or [])]
|
||
|
||
def list_skills(self, *, filter_unavailable: bool = True) -> list[SkillRecord]:
|
||
"""列出当前可见的 skills。
|
||
|
||
优先级：
|
||
1. workspace
|
||
2. extra/plugin 目录
|
||
3. builtin
|
||
|
||
重名 skill 只保留优先级更高的那一个。
|
||
"""
|
||
|
||
ordered_roots: list[tuple[str, Path]] = [
|
||
("workspace", self.workspace_skills),
|
||
*[("plugin", path) for path in self.extra_dirs],
|
||
("builtin", self.builtin_skills),
|
||
]
|
||
found: dict[str, SkillRecord] = {}
|
||
|
||
for source, root in ordered_roots:
|
||
if not root.exists():
|
||
continue
|
||
for skill_dir in root.iterdir():
|
||
skill_file = skill_dir / "SKILL.md"
|
||
if not skill_dir.is_dir() or not skill_file.exists():
|
||
continue
|
||
name = skill_dir.name
|
||
if name in found:
|
||
continue
|
||
record = SkillRecord(name=name, path=skill_file, source=source)
|
||
if filter_unavailable and not self._record_available(record):
|
||
continue
|
||
found[name] = record
|
||
return list(found.values())
|
||
|
||
def load_skill(self, name: str) -> str | None:
|
||
"""按名称加载 skill 原始内容。"""
|
||
|
||
record = self._find_record(name)
|
||
if record is None:
|
||
return None
|
||
return record.path.read_text(encoding="utf-8")
|
||
|
||
def get_skill_record(self, name: str) -> SkillRecord | None:
|
||
"""按名称返回 skill record。"""
|
||
|
||
return self._find_record(name)
|
||
|
||
def get_skill_metadata(self, name: str) -> dict[str, Any] | None:
|
||
"""读取 skill frontmatter 元数据。"""
|
||
|
||
content = self.load_skill(name)
|
||
if content is None:
|
||
return None
|
||
metadata, _ = parse_frontmatter(content)
|
||
return metadata
|
||
|
||
def load_skills_for_context(self, skill_names: list[str]) -> str:
|
||
"""加载指定 skills 的正文，并整理成上下文块。"""
|
||
|
||
sections: list[str] = []
|
||
for name in skill_names:
|
||
content = self.load_skill(name)
|
||
if not content:
|
||
continue
|
||
body = strip_frontmatter(content).strip()
|
||
if not body:
|
||
continue
|
||
sections.append(f"## {name}\n\n{body}")
|
||
return "\n\n".join(sections)
|
||
|
||
def build_skills_summary(self) -> str:
|
||
"""构建可注入 system prompt 的 skills index。
|
||
|
||
虽然函数名还沿用 `summary`，但当前语义已经更接近 Hermes 的 skills index：
|
||
- 这里只告诉模型“系统里有哪些 skill 可用”
|
||
- 不负责把 skill 正文塞进 system prompt
|
||
- 真正激活的 skill 正文由 resolver/builder 走显式消息注入
|
||
"""
|
||
|
||
skills = self.list_skills(filter_unavailable=False)
|
||
if not skills:
|
||
return ""
|
||
|
||
lines = ["<skills>"]
|
||
for record in skills:
|
||
frontmatter = self.get_skill_metadata(record.name) or {}
|
||
meta_blob = parse_skill_metadata_blob(frontmatter.get("metadata", ""))
|
||
available = check_requirements(meta_blob)
|
||
description = frontmatter.get("description") or record.name
|
||
load_hint = f'Use skill_view(name="{record.name}") to load the full skill.'
|
||
lines.append(f' <skill available="{str(available).lower()}">')
|
||
lines.append(f" <name>{escape_xml(record.name)}</name>")
|
||
lines.append(f" <description>{escape_xml(description)}</description>")
|
||
lines.append(f" <load_hint>{escape_xml(load_hint)}</load_hint>")
|
||
support_files = self.list_skill_supporting_files(record.name)
|
||
if support_files:
|
||
lines.append(" <supporting_files>")
|
||
for file_path in support_files[:12]:
|
||
lines.append(f" <file>{escape_xml(file_path)}</file>")
|
||
if len(support_files) > 12:
|
||
lines.append(" <file>...additional files omitted...</file>")
|
||
lines.append(" </supporting_files>")
|
||
if not available:
|
||
missing = get_missing_requirements(meta_blob)
|
||
if missing:
|
||
lines.append(f" <requires>{escape_xml(missing)}</requires>")
|
||
lines.append(" </skill>")
|
||
lines.append("</skills>")
|
||
return "\n".join(lines)
|
||
|
||
def build_selection_candidates(self) -> list[dict[str, str]]:
|
||
"""构建给 LLM selector 使用的候选 skill 摘要。
|
||
|
||
这里刻意保持精简，只给：
|
||
- `name`
|
||
- `description`
|
||
|
||
选择器的任务只是“从候选里挑名字”，不是直接阅读完整 skill 正文。
|
||
真正激活后的 skill 正文仍然在后续阶段按需加载。
|
||
"""
|
||
|
||
candidates: list[dict[str, str]] = []
|
||
for record in self.list_skills(filter_unavailable=True):
|
||
frontmatter = self.get_skill_metadata(record.name) or {}
|
||
description = str(frontmatter.get("description") or "").strip()
|
||
if not description:
|
||
raw_content = self.load_skill(record.name) or ""
|
||
body = strip_frontmatter(raw_content).strip()
|
||
if body:
|
||
description = " ".join(body.splitlines()[:3])[:240].strip()
|
||
candidates.append(
|
||
{
|
||
"name": record.name,
|
||
"description": description or record.name,
|
||
}
|
||
)
|
||
return candidates
|
||
|
||
def list_skill_supporting_files(self, name: str) -> list[str]:
|
||
"""列出 skill 目录下可按需查看的支持文件相对路径。"""
|
||
|
||
record = self._find_record(name)
|
||
if record is None:
|
||
return []
|
||
skill_dir = record.path.parent
|
||
results: list[str] = []
|
||
for subdir in ("references", "templates", "scripts", "assets"):
|
||
root = skill_dir / subdir
|
||
if not root.exists():
|
||
continue
|
||
for file in sorted(root.rglob("*")):
|
||
if file.is_file() and not file.is_symlink():
|
||
results.append(str(file.relative_to(skill_dir)))
|
||
return results
|
||
|
||
def view_skill(self, name: str, file_path: str | None = None) -> tuple[str, str] | None:
|
||
"""读取 skill 正文或其支持文件。
|
||
|
||
返回 `(display_name, content)`：
|
||
- `display_name` 用于提示当前读取的是 skill 本体还是某个支持文件
|
||
- `content` 为实际文本内容
|
||
"""
|
||
|
||
record = self._find_record(name)
|
||
if record is None:
|
||
return None
|
||
if not self._record_available(record):
|
||
frontmatter = self.get_skill_metadata(name) or {}
|
||
meta_blob = parse_skill_metadata_blob(frontmatter.get("metadata", ""))
|
||
missing = get_missing_requirements(meta_blob)
|
||
detail = f" Missing requirements: {missing}." if missing else ""
|
||
raise ValueError(f"Skill '{name}' is currently unavailable.{detail}")
|
||
|
||
skill_dir = record.path.parent
|
||
if not file_path:
|
||
return ("SKILL.md", self._read_text_file(record.path, display_name="SKILL.md"))
|
||
|
||
candidate = (skill_dir / file_path).resolve()
|
||
try:
|
||
candidate.relative_to(skill_dir.resolve())
|
||
except ValueError as exc:
|
||
raise ValueError("Requested skill file must stay within the skill directory") from exc
|
||
if not candidate.exists() or not candidate.is_file():
|
||
raise FileNotFoundError(f"Skill file '{file_path}' does not exist")
|
||
display_name = str(candidate.relative_to(skill_dir))
|
||
return (display_name, self._read_text_file(candidate, display_name=display_name))
|
||
|
||
def get_always_skills(self) -> list[str]:
|
||
"""返回标记为 always 的可用 skill 名称。"""
|
||
|
||
result: list[str] = []
|
||
for record in self.list_skills(filter_unavailable=True):
|
||
frontmatter = self.get_skill_metadata(record.name) or {}
|
||
meta_blob = parse_skill_metadata_blob(frontmatter.get("metadata", ""))
|
||
if meta_blob.get("always") or str(frontmatter.get("always", "")).lower() == "true":
|
||
result.append(record.name)
|
||
return result
|
||
|
||
def _find_record(self, name: str) -> SkillRecord | None:
|
||
for record in self.list_skills(filter_unavailable=False):
|
||
if record.name == name:
|
||
return record
|
||
return None
|
||
|
||
def _record_available(self, record: SkillRecord) -> bool:
|
||
content = record.path.read_text(encoding="utf-8")
|
||
frontmatter, _ = parse_frontmatter(content)
|
||
meta_blob = parse_skill_metadata_blob(frontmatter.get("metadata", ""))
|
||
return check_requirements(meta_blob)
|
||
|
||
@staticmethod
|
||
def _read_text_file(path: Path, *, display_name: str) -> str:
|
||
try:
|
||
return path.read_text(encoding="utf-8")
|
||
except UnicodeDecodeError as exc:
|
||
raise ValueError(
|
||
f"Skill file '{display_name}' is not UTF-8 text and cannot be viewed with skill_view."
|
||
) from exc
|
||
|
||
def _skill_available(self, name: str) -> bool:
|
||
record = self._find_record(name)
|
||
if record is None:
|
||
return False
|
||
return self._record_available(record)
|