zero-agent-core 0.2.0__py3-none-any.whl

agent_core/serialization/registry.py

@@ -0,0 +1,318 @@
+"""仅允许显式注册类型的 JSON 序列化注册表。
+
+本模块不会根据输入中的 Python 模块或类路径执行动态导入，也不使用 pickle。
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from agent_core.access import AccessContext
+from agent_core.documents import Blob, Document, DocumentChunk, DocumentLocator
+from agent_core.errors import (
+    SerializationError,
+    UnknownSerializedTypeError,
+    UnsupportedSchemaVersionError,
+)
+from agent_core.protocol import ApprovalRecord, Message, RunContext, RunEvent, ToolResult
+
+Encoder = Callable[[Any], dict[str, Any]]
+Decoder = Callable[[dict[str, Any]], Any]
+Migration = Callable[[dict[str, Any]], dict[str, Any]]
+
+
+@dataclass(frozen=True)
+class SerializedEnvelope:
+    """持久化对象的类型和 Schema 版本信封。"""
+
+    type_id: str
+    schema_version: int
+    payload: dict[str, Any]
+
+    def __post_init__(self) -> None:
+        if not self.type_id.strip():
+            raise SerializationError("type_id 不能为空")
+        if self.schema_version <= 0:
+            raise SerializationError("schema_version 必须大于 0")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": self.type_id,
+            "schema_version": self.schema_version,
+            "payload": self.payload,
+        }
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> SerializedEnvelope:
+        if not isinstance(value.get("payload"), dict):
+            raise SerializationError("序列化 payload 必须是对象")
+        try:
+            return cls(
+                type_id=str(value["type"]),
+                schema_version=int(value["schema_version"]),
+                payload=dict(value["payload"]),
+            )
+        except (KeyError, TypeError, ValueError) as exc:
+            raise SerializationError("序列化信封缺少有效的 type 或 schema_version") from exc
+
+
+@dataclass(frozen=True)
+class _Codec:
+    type_id: str
+    python_type: type[Any]
+    schema_version: int
+    encoder: Encoder
+    decoder: Decoder
+    migrations: dict[int, Migration] = field(default_factory=dict)
+
+
+class SerializerRegistry:
+    """显式白名单注册表，负责版本迁移和对象重建。"""
+
+    def __init__(self) -> None:
+        self._by_type_id: dict[str, _Codec] = {}
+        self._by_python_type: dict[type[Any], _Codec] = {}
+
+    def register(
+        self,
+        type_id: str,
+        python_type: type[Any],
+        *,
+        schema_version: int,
+        encoder: Encoder,
+        decoder: Decoder,
+        migrations: Mapping[int, Migration] | None = None,
+    ) -> None:
+        """注册对象编码器；migration[n] 负责把版本 n 升级到 n+1。"""
+
+        normalized = type_id.strip()
+        if not normalized:
+            raise ValueError("type_id 不能为空")
+        if schema_version <= 0:
+            raise ValueError("schema_version 必须大于 0")
+        if normalized in self._by_type_id:
+            raise ValueError(f"序列化类型已注册：{normalized}")
+        if python_type in self._by_python_type:
+            raise ValueError(f"Python 类型已注册：{python_type.__qualname__}")
+        codec = _Codec(
+            type_id=normalized,
+            python_type=python_type,
+            schema_version=schema_version,
+            encoder=encoder,
+            decoder=decoder,
+            migrations=dict(migrations or {}),
+        )
+        self._by_type_id[normalized] = codec
+        self._by_python_type[python_type] = codec
+
+    def dump(self, value: Any) -> SerializedEnvelope:
+        codec = self._by_python_type.get(type(value))
+        if codec is None:
+            raise UnknownSerializedTypeError(f"类型未注册：{type(value).__qualname__}")
+        try:
+            payload = codec.encoder(value)
+        except SerializationError:
+            raise
+        except Exception as exc:
+            raise SerializationError(f"{codec.type_id} 编码失败：{exc}") from exc
+        if not isinstance(payload, dict):
+            raise SerializationError(f"{codec.type_id} 编码器必须返回 dict")
+        return SerializedEnvelope(codec.type_id, codec.schema_version, payload)
+
+    def load(self, value: SerializedEnvelope | Mapping[str, Any]) -> Any:
+        envelope = value if isinstance(value, SerializedEnvelope) else SerializedEnvelope.from_dict(value)
+        codec = self._by_type_id.get(envelope.type_id)
+        if codec is None:
+            raise UnknownSerializedTypeError(f"序列化类型未注册：{envelope.type_id}")
+        if envelope.schema_version > codec.schema_version:
+            raise UnsupportedSchemaVersionError(
+                f"{envelope.type_id} 版本 {envelope.schema_version} 高于当前版本 {codec.schema_version}"
+            )
+        payload = dict(envelope.payload)
+        version = envelope.schema_version
+        while version < codec.schema_version:
+            migration = codec.migrations.get(version)
+            if migration is None:
+                raise UnsupportedSchemaVersionError(
+                    f"{envelope.type_id} 缺少 {version} -> {version + 1} 迁移函数"
+                )
+            try:
+                payload = migration(payload)
+            except Exception as exc:
+                raise SerializationError(f"{envelope.type_id} 从版本 {version} 迁移失败：{exc}") from exc
+            if not isinstance(payload, dict):
+                raise SerializationError(
+                    f"{envelope.type_id} 的 {version} -> {version + 1} 迁移必须返回 dict"
+                )
+            version += 1
+        try:
+            return codec.decoder(payload)
+        except SerializationError:
+            raise
+        except Exception as exc:
+            raise SerializationError(f"{envelope.type_id} 解码失败：{exc}") from exc
+
+    def dumps(self, value: Any, *, ensure_ascii: bool = False) -> str:
+        try:
+            return json.dumps(self.dump(value).to_dict(), ensure_ascii=ensure_ascii)
+        except (TypeError, ValueError) as exc:
+            raise SerializationError(f"对象不能编码为 JSON：{exc}") from exc
+
+    def loads(self, value: str) -> Any:
+        try:
+            decoded = json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise SerializationError(f"无效 JSON：{exc}") from exc
+        if not isinstance(decoded, dict):
+            raise SerializationError("序列化根节点必须是对象")
+        return self.load(decoded)
+
+
+def _encode_blob(value: Blob) -> dict[str, Any]:
+    return {
+        "data": base64.b64encode(value.data).decode("ascii"),
+        "data_encoding": "base64",
+        "source": value.source,
+        "mime_type": value.mime_type,
+        "metadata": dict(value.metadata),
+        "checksum": value.checksum,
+    }
+
+
+def _decode_blob(value: dict[str, Any]) -> Blob:
+    if value.get("data_encoding") != "base64":
+        raise SerializationError("Blob 只接受 base64 数据")
+    try:
+        data = base64.b64decode(str(value.get("data", "")), validate=True)
+    except (ValueError, binascii.Error) as exc:
+        raise SerializationError("Blob 包含无效 base64 数据") from exc
+    return Blob(
+        data=data,
+        source=value.get("source"),
+        mime_type=value.get("mime_type"),
+        metadata=dict(value.get("metadata") or {}),
+        checksum=str(value.get("checksum", "")),
+    )
+
+
+def _decode_message(value: dict[str, Any]) -> Message:
+    return Message.from_dict(value)
+
+
+def _decode_access(value: dict[str, Any]) -> AccessContext:
+    return AccessContext(
+        user_id=str(value.get("user_id", "anonymous")),
+        tenant_id=str(value.get("tenant_id", "default")),
+        roles=frozenset(str(role) for role in value.get("roles", ["user"])),
+    )
+
+
+def _build_default_registry() -> SerializerRegistry:
+    registry = SerializerRegistry()
+    registry.register(
+        "agent_core.blob",
+        Blob,
+        schema_version=1,
+        encoder=_encode_blob,
+        decoder=_decode_blob,
+    )
+    registry.register(
+        "agent_core.document_locator",
+        DocumentLocator,
+        schema_version=1,
+        encoder=DocumentLocator.to_dict,
+        decoder=DocumentLocator.from_dict,
+    )
+    registry.register(
+        "agent_core.document",
+        Document,
+        schema_version=1,
+        encoder=Document.to_dict,
+        decoder=Document.from_dict,
+    )
+    registry.register(
+        "agent_core.document_chunk",
+        DocumentChunk,
+        schema_version=1,
+        encoder=DocumentChunk.to_dict,
+        decoder=DocumentChunk.from_dict,
+    )
+    registry.register(
+        "agent_core.message",
+        Message,
+        schema_version=1,
+        encoder=Message.to_dict,
+        decoder=_decode_message,
+    )
+    registry.register(
+        "agent_core.run_event",
+        RunEvent,
+        schema_version=1,
+        encoder=RunEvent.to_dict,
+        decoder=RunEvent.from_dict,
+    )
+    registry.register(
+        "agent_core.run_context",
+        RunContext,
+        schema_version=1,
+        encoder=RunContext.to_dict,
+        decoder=RunContext.from_dict,
+    )
+    registry.register(
+        "agent_core.approval_record",
+        ApprovalRecord,
+        schema_version=1,
+        encoder=ApprovalRecord.to_dict,
+        decoder=ApprovalRecord.from_dict,
+    )
+    registry.register(
+        "agent_core.tool_result",
+        ToolResult,
+        schema_version=1,
+        encoder=ToolResult.to_dict,
+        decoder=ToolResult.from_dict,
+    )
+    registry.register(
+        "agent_core.access_context",
+        AccessContext,
+        schema_version=1,
+        encoder=AccessContext.to_dict,
+        decoder=_decode_access,
+    )
+    return registry
+
+
+default_serializer_registry = _build_default_registry()
+
+
+def dumpd(value: Any, *, registry: SerializerRegistry = default_serializer_registry) -> dict[str, Any]:
+    """把对象编码为包含类型和版本的字典。"""
+
+    return registry.dump(value).to_dict()
+
+
+def dumps(value: Any, *, registry: SerializerRegistry = default_serializer_registry) -> str:
+    """把对象安全编码为 JSON。"""
+
+    return registry.dumps(value)
+
+
+def load(
+    value: SerializedEnvelope | Mapping[str, Any],
+    *,
+    registry: SerializerRegistry = default_serializer_registry,
+) -> Any:
+    """从版本化信封恢复白名单中的对象。"""
+
+    return registry.load(value)
+
+
+def loads(value: str, *, registry: SerializerRegistry = default_serializer_registry) -> Any:
+    """从 JSON 恢复白名单中的对象。"""
+
+    return registry.loads(value)

agent_core/skills/__init__.py

@@ -0,0 +1,24 @@
+"""可复用 Skill 清单、加载器和注册表。"""
+
+from agent_core.skills.errors import (
+    SkillBindingError,
+    SkillError,
+    SkillLoadError,
+    SkillRegistrationError,
+)
+from agent_core.skills.loader import SkillLoader
+from agent_core.skills.registry import SkillRegistry
+from agent_core.skills.types import SkillActivation, SkillSpec, SkillToolKind, SkillToolSpec
+
+__all__ = [
+    "SkillActivation",
+    "SkillBindingError",
+    "SkillError",
+    "SkillLoadError",
+    "SkillLoader",
+    "SkillRegistrationError",
+    "SkillRegistry",
+    "SkillSpec",
+    "SkillToolKind",
+    "SkillToolSpec",
+]

agent_core/skills/errors.py

@@ -0,0 +1,27 @@
+"""Skill 加载、注册和绑定错误。"""
+
+from agent_core.errors import ConfigurationError
+
+
+class SkillError(ConfigurationError):
+    """Skill 配置基础错误。"""
+
+
+class SkillLoadError(SkillError):
+    """Skill 清单或指令文件无法加载。"""
+
+
+class SkillRegistrationError(SkillError):
+    """Skill 名称或工具名称发生注册冲突。"""
+
+
+class SkillBindingError(SkillError):
+    """Skill 声明的 Function 或 MCP 客户端无法绑定。"""
+
+
+__all__ = [
+    "SkillBindingError",
+    "SkillError",
+    "SkillLoadError",
+    "SkillRegistrationError",
+]

agent_core/skills/loader.py

@@ -0,0 +1,258 @@
+"""从受约束的 JSON 清单加载 Skill。"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any, cast
+
+from agent_core.skills.errors import SkillLoadError
+from agent_core.skills.types import SkillSpec, SkillToolKind, SkillToolSpec
+
+_NAME_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$")
+_TOOL_NAME_PATTERN = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+_SKILL_FIELDS = {
+    "name",
+    "description",
+    "version",
+    "instructions",
+    "instructions_file",
+    "tools",
+    "metadata",
+}
+_TOOL_FIELDS = {
+    "name",
+    "kind",
+    "target",
+    "server",
+    "description",
+    "parameters",
+    "risk_level",
+    "requires_approval",
+    "timeout_seconds",
+    "idempotent",
+}
+
+
+class SkillLoader:
+    """加载 ``skill.json``，并校验其关联指令文件位于 Skill 目录内。"""
+
+    def __init__(self, *, manifest_name: str = "skill.json") -> None:
+        if not manifest_name or Path(manifest_name).name != manifest_name:
+            raise ValueError("manifest_name 必须是单个文件名")
+        self._manifest_name = manifest_name
+
+    def load(self, path: str | Path) -> SkillSpec:
+        """从 Skill 目录或 JSON 清单文件加载一个 Skill。"""
+        source = Path(path).expanduser()
+        manifest = source / self._manifest_name if source.is_dir() else source
+        manifest = manifest.resolve()
+        if not manifest.is_file():
+            raise SkillLoadError(f"Skill 清单不存在：{manifest}")
+
+        data = self._read_manifest(manifest)
+        self._reject_unknown_fields(data, _SKILL_FIELDS, f"Skill {manifest}")
+
+        name = self._required_string(data, "name", f"Skill {manifest}")
+        if not _NAME_PATTERN.fullmatch(name):
+            raise SkillLoadError(f"Skill 名称格式无效：{name!r}；只允许字母、数字、点、下划线和连字符")
+        description = self._required_string(data, "description", f"Skill {name}")
+        version = self._required_string(data, "version", f"Skill {name}")
+        instructions = self._load_instructions(data, manifest, name)
+
+        raw_tools = data.get("tools", [])
+        if not isinstance(raw_tools, list):
+            raise SkillLoadError(f"Skill {name} 的 tools 必须是数组")
+        tools = tuple(
+            self._parse_tool(item, skill_name=name, index=index) for index, item in enumerate(raw_tools)
+        )
+        duplicate_tools = self._duplicates(tool.name for tool in tools)
+        if duplicate_tools:
+            raise SkillLoadError(f"Skill {name} 包含重复工具名称：{', '.join(duplicate_tools)}")
+
+        metadata = data.get("metadata", {})
+        if not isinstance(metadata, dict):
+            raise SkillLoadError(f"Skill {name} 的 metadata 必须是对象")
+
+        return SkillSpec(
+            name=name,
+            description=description,
+            version=version,
+            instructions=instructions,
+            tools=tools,
+            metadata=dict(metadata),
+            source=manifest,
+        )
+
+    def load_directory(self, directory: str | Path) -> tuple[SkillSpec, ...]:
+        """递归加载目录下的所有 ``skill.json``，结果按路径稳定排序。"""
+        root = Path(directory).expanduser().resolve()
+        if not root.is_dir():
+            raise SkillLoadError(f"Skill 目录不存在：{root}")
+        manifests = sorted(root.rglob(self._manifest_name))
+        if not manifests:
+            raise SkillLoadError(f"目录中没有找到 {self._manifest_name}：{root}")
+        return tuple(self.load(manifest) for manifest in manifests)
+
+    @staticmethod
+    def _read_manifest(manifest: Path) -> dict[str, Any]:
+        try:
+            raw = json.loads(manifest.read_text(encoding="utf-8"))
+        except OSError as exc:
+            raise SkillLoadError(f"无法读取 Skill 清单：{manifest}（{exc}）") from exc
+        except json.JSONDecodeError as exc:
+            raise SkillLoadError(f"Skill 清单不是有效 JSON：{manifest}:{exc.lineno}:{exc.colno}") from exc
+        if not isinstance(raw, dict):
+            raise SkillLoadError(f"Skill 清单根节点必须是对象：{manifest}")
+        return cast(dict[str, Any], raw)
+
+    def _load_instructions(
+        self,
+        data: dict[str, Any],
+        manifest: Path,
+        skill_name: str,
+    ) -> str:
+        inline = data.get("instructions")
+        filename = data.get("instructions_file")
+        if inline is not None and filename is not None:
+            raise SkillLoadError(f"Skill {skill_name} 不能同时设置 instructions 和 instructions_file")
+        if inline is not None:
+            if not isinstance(inline, str):
+                raise SkillLoadError(f"Skill {skill_name} 的 instructions 必须是字符串")
+            return inline.strip()
+        if filename is None:
+            return ""
+        if not isinstance(filename, str) or not filename.strip():
+            raise SkillLoadError(f"Skill {skill_name} 的 instructions_file 必须是非空字符串")
+
+        skill_root = manifest.parent.resolve()
+        instruction_path = (skill_root / filename).resolve()
+        try:
+            instruction_path.relative_to(skill_root)
+        except ValueError as exc:
+            raise SkillLoadError(f"Skill {skill_name} 的 instructions_file 不能越过 Skill 目录") from exc
+        if not instruction_path.is_file():
+            raise SkillLoadError(f"Skill {skill_name} 的指令文件不存在：{instruction_path}")
+        try:
+            return instruction_path.read_text(encoding="utf-8").strip()
+        except OSError as exc:
+            raise SkillLoadError(
+                f"无法读取 Skill {skill_name} 的指令文件：{instruction_path}（{exc}）"
+            ) from exc
+
+    def _parse_tool(
+        self,
+        raw: object,
+        *,
+        skill_name: str,
+        index: int,
+    ) -> SkillToolSpec:
+        context = f"Skill {skill_name} 的 tools[{index}]"
+        if not isinstance(raw, dict):
+            raise SkillLoadError(f"{context} 必须是对象")
+        data = cast(dict[str, Any], raw)
+        self._reject_unknown_fields(data, _TOOL_FIELDS, context)
+
+        name = self._required_string(data, "name", context)
+        if not _TOOL_NAME_PATTERN.fullmatch(name):
+            raise SkillLoadError(
+                f"{context} 的工具名称格式无效：{name!r}；必须符合 Function Calling 命名规则"
+            )
+        kind = self._required_string(data, "kind", context).lower()
+        if kind not in {"function", "mcp"}:
+            raise SkillLoadError(f"{context} 的 kind 只支持 function 或 mcp")
+        description = self._required_string(data, "description", context)
+        target = data.get("target", name)
+        if not isinstance(target, str) or not target.strip():
+            raise SkillLoadError(f"{context} 的 target 必须是非空字符串")
+        target = target.strip()
+
+        server = data.get("server")
+        if kind == "mcp":
+            if not isinstance(server, str) or not server.strip():
+                raise SkillLoadError(f"{context} 的 MCP 工具必须声明 server")
+            server = server.strip()
+        elif server is not None:
+            raise SkillLoadError(f"{context} 的 Function 工具不能声明 server")
+
+        parameters = data.get(
+            "parameters",
+            {"type": "object", "properties": {}, "required": []},
+        )
+        self._validate_parameters(parameters, context)
+
+        risk_level = data.get("risk_level", "read")
+        if not isinstance(risk_level, str) or not risk_level.strip():
+            raise SkillLoadError(f"{context} 的 risk_level 必须是非空字符串")
+        requires_approval = self._boolean(data, "requires_approval", False, context)
+        idempotent = self._boolean(data, "idempotent", True, context)
+        timeout_seconds = data.get("timeout_seconds")
+        if timeout_seconds is not None:
+            if (
+                isinstance(timeout_seconds, bool)
+                or not isinstance(timeout_seconds, (int, float))
+                or timeout_seconds <= 0
+            ):
+                raise SkillLoadError(f"{context} 的 timeout_seconds 必须大于 0")
+            timeout_seconds = float(timeout_seconds)
+
+        return SkillToolSpec(
+            name=name,
+            kind=cast(SkillToolKind, kind),
+            target=target,
+            server=server,
+            description=description,
+            parameters=dict(cast(dict[str, Any], parameters)),
+            risk_level=risk_level.strip(),
+            requires_approval=requires_approval,
+            timeout_seconds=timeout_seconds,
+            idempotent=idempotent,
+        )
+
+    @staticmethod
+    def _validate_parameters(parameters: object, context: str) -> None:
+        if not isinstance(parameters, dict):
+            raise SkillLoadError(f"{context} 的 parameters 必须是 JSON Schema 对象")
+        if parameters.get("type", "object") != "object":
+            raise SkillLoadError(f"{context} 的 parameters.type 必须是 object")
+        properties = parameters.get("properties", {})
+        required = parameters.get("required", [])
+        if not isinstance(properties, dict):
+            raise SkillLoadError(f"{context} 的 parameters.properties 必须是对象")
+        if not isinstance(required, list) or not all(isinstance(item, str) for item in required):
+            raise SkillLoadError(f"{context} 的 parameters.required 必须是字符串数组")
+
+    @staticmethod
+    def _required_string(data: dict[str, Any], field: str, context: str) -> str:
+        value = data.get(field)
+        if not isinstance(value, str) or not value.strip():
+            raise SkillLoadError(f"{context} 缺少非空字符串字段 {field}")
+        return value.strip()
+
+    @staticmethod
+    def _boolean(data: dict[str, Any], field: str, default: bool, context: str) -> bool:
+        value = data.get(field, default)
+        if not isinstance(value, bool):
+            raise SkillLoadError(f"{context} 的 {field} 必须是布尔值")
+        return value
+
+    @staticmethod
+    def _reject_unknown_fields(data: dict[str, Any], allowed: set[str], context: str) -> None:
+        unknown = sorted(set(data) - allowed)
+        if unknown:
+            raise SkillLoadError(f"{context} 包含未知字段：{', '.join(unknown)}")
+
+    @staticmethod
+    def _duplicates(values: Iterable[str]) -> list[str]:
+        seen: set[str] = set()
+        duplicates: set[str] = set()
+        for value in values:
+            if value in seen:
+                duplicates.add(value)
+            seen.add(value)
+        return sorted(duplicates)
+
+
+__all__ = ["SkillLoader"]