python-library-ai-agent 0.1.0__py3-none-any.whl

ai_agent/skill/builtin_registry.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from ai_agent.tools import Tool
+
+ToolFactory = Callable[[], Tool]
+
+
+class BuiltinToolRegistry:
+    """
+    宿主预注册的安全工具库，供技能 frontmatter 以内置引用方式绑定。
+
+    不允许从技能文件动态执行任意 Python；未注册名称在启用技能时无法解析。
+    """
+
+    def __init__(self) -> None:
+        self._factories: dict[str, ToolFactory] = {}
+
+    def register(self, name: str, factory: ToolFactory) -> None:
+        """
+        注册内置工具工厂。
+
+        Args:
+            name: 不含 ``builtin:`` 前缀的名称
+            factory: 每次绑定 skill 时调用，返回新的 Tool 实例
+        """
+        key = name.strip()
+        if not key:
+            raise ValueError("内置工具名不能为空")
+        self._factories[key] = factory
+
+    def resolve(self, handler: str) -> Tool | None:
+        """
+        解析 handler 引用。
+
+        Args:
+            handler: 形如 ``builtin:tool_name``
+
+        Returns:
+            可注册的 Tool；未知 handler 时返回 None
+        """
+        cleaned = handler.strip()
+        if not cleaned.startswith("builtin:"):
+            return None
+        name = cleaned[len("builtin:") :].strip()
+        if not name:
+            return None
+        factory = self._factories.get(name)
+        if factory is None:
+            return None
+        return factory()
+
+    def known_names(self) -> tuple[str, ...]:
+        """已注册的内置工具名。"""
+        return tuple(sorted(self._factories))

ai_agent/skill/catalog.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ai_agent.skill.frontmatter import split_frontmatter
+from ai_agent.skill.roots import SkillRootsSandbox
+
+_MAX_READ_BYTES = 512 * 1024
+_SKILL_FILE = "SKILL.md"
+
+
+@dataclass(frozen=True)
+class SkillSummary:
+    """扫描得到的技能摘要（不含正文）。"""
+
+    root_key: str
+    """配置的技能根键名。"""
+    skill_id: str
+    """根目录下技能子文件夹名。"""
+    name: str
+    """frontmatter 中的展示名。"""
+    description: str
+    """frontmatter 中的简短说明。"""
+
+    @property
+    def skill_ref(self) -> str:
+        return f"{self.root_key}/{self.skill_id}"
+
+
+def scan_skills(sandbox: SkillRootsSandbox) -> list[SkillSummary]:
+    """
+    扫描所有根目录下含 SKILL.md 的子目录。
+
+    Args:
+        sandbox: 已配置的 skill 根
+
+    Returns:
+        按 skill_ref 字典序排列的摘要列表
+    """
+    found: list[SkillSummary] = []
+    for root_key in sandbox.root_keys:
+        root = sandbox.root_path(root_key)
+        if not root.is_dir():
+            continue
+        for child in sorted(root.iterdir()):
+            if not child.is_dir():
+                continue
+            skill_md = child / _SKILL_FILE
+            if not skill_md.is_file():
+                continue
+            summary = _summary_from_file(root_key, child.name, skill_md)
+            found.append(summary)
+    found.sort(key=lambda item: item.skill_ref)
+    return found
+
+
+def load_skill_text(sandbox: SkillRootsSandbox, skill_ref: str) -> str:
+    """
+    读取 SKILL.md 全文。
+
+    Args:
+        sandbox: skill 根沙箱
+        skill_ref: ``{root_key}/{skill_id}``
+
+    Returns:
+        文件全文
+    """
+    path = sandbox.skill_md_path(skill_ref)
+    if not path.is_file():
+        raise ValueError(f"未找到 SKILL.md: {skill_ref}")
+    return _read_bounded(path)
+
+
+def format_skill_list(summaries: list[SkillSummary]) -> str:
+    """将摘要列表格式化为模型可读文本（不含宿主机绝对路径）。"""
+    if not summaries:
+        return "（未找到 skill）"
+    lines: list[str] = []
+    for item in summaries:
+        lines.append(
+            f"- {item.skill_ref} | name={item.name} | {item.description}"
+        )
+    return "\n".join(lines)
+
+
+def _summary_from_file(root_key: str, skill_id: str, skill_md: Path) -> SkillSummary:
+    raw = _read_bounded(skill_md)
+    meta, _ = split_frontmatter(raw)
+    name = meta.get("name", "").strip() or skill_id
+    description = meta.get("description", "").strip()
+    return SkillSummary(
+        root_key=root_key,
+        skill_id=skill_id,
+        name=name,
+        description=description,
+    )
+
+
+def _read_bounded(path: Path) -> str:
+    size = path.stat().st_size
+    if size > _MAX_READ_BYTES:
+        raise ValueError(f"文件过大（>{_MAX_READ_BYTES} 字节）")
+    return path.read_text(encoding="utf-8", errors="replace")

ai_agent/skill/frontmatter.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import re
+
+_FRONTMATTER_RE = re.compile(
+    r"\A---\r?\n(.*?)\r?\n---\r?\n?",
+    re.DOTALL,
+)
+
+
+def split_frontmatter(text: str) -> tuple[dict[str, str], str]:
+    """
+    拆分 YAML frontmatter 与正文。
+
+    Args:
+        text: 完整文件内容
+
+    Returns:
+        元数据键值对与正文（无 frontmatter 时元数据为空 dict）
+    """
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        return {}, text
+    meta = _parse_simple_yaml(match.group(1))
+    body = text[match.end() :]
+    return meta, body
+
+
+def compose_skill_md(meta: dict[str, str], body: str) -> str:
+    """
+    组装带 frontmatter 的 SKILL.md 文本。
+
+    Args:
+        meta: 元数据；空 dict 时不写 frontmatter
+        body: Markdown 正文
+
+    Returns:
+        完整文件内容
+    """
+    normalized_body = body
+    if normalized_body and not normalized_body.endswith("\n"):
+        normalized_body += "\n"
+    if not meta:
+        return normalized_body
+    lines = ["---"]
+    for key in sorted(meta.keys()):
+        lines.append(f"{key}: {_yaml_scalar(meta[key])}")
+    lines.append("---")
+    lines.append("")
+    if normalized_body:
+        return "\n".join(lines) + "\n" + normalized_body.lstrip("\n")
+    return "\n".join(lines) + "\n"
+
+
+def _parse_simple_yaml(block: str) -> dict[str, str]:
+    meta: dict[str, str] = {}
+    for line in block.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if ":" not in stripped:
+            continue
+        key, _, value = stripped.partition(":")
+        key = key.strip()
+        value = value.strip()
+        if value.startswith('"') and value.endswith('"') and len(value) >= 2:
+            value = value[1:-1]
+        elif value.startswith("'") and value.endswith("'") and len(value) >= 2:
+            value = value[1:-1]
+        if key:
+            meta[key] = value
+    return meta
+
+
+def _yaml_scalar(value: str) -> str:
+    if not value:
+        return '""'
+    if re.search(r"[\n:#\"'\\]", value):
+        escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+    if re.search(r"[^\w.\-/]", value):
+        return f'"{value}"'
+    return value