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

agent_core/skills/registry.py

@@ -0,0 +1,205 @@
+"""Skill 注册、选择和工具绑定。"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from pathlib import Path
+from typing import Any
+
+from agent_core.mcp import McpToolCaller
+from agent_core.skills.errors import SkillBindingError, SkillRegistrationError
+from agent_core.skills.loader import SkillLoader
+from agent_core.skills.types import SkillActivation, SkillSpec, SkillToolSpec
+from agent_core.tools import ToolRegistry
+
+
+class SkillRegistry:
+    """管理 Skill，并把激活 Skill 的工具安装到统一工具注册表。"""
+
+    def __init__(self) -> None:
+        self._skills: dict[str, SkillSpec] = {}
+
+    def register(self, skill: SkillSpec, *, replace: bool = False) -> None:
+        """注册一个 Skill；默认拒绝无意覆盖同名版本。"""
+        if skill.name in self._skills and not replace:
+            raise SkillRegistrationError(f"Skill 已注册：{skill.name}")
+        self._skills[skill.name] = skill
+
+    def unregister(self, name: str) -> None:
+        """移除一个 Skill。"""
+        self._skills.pop(name, None)
+
+    def get(self, name: str) -> SkillSpec | None:
+        """按名称查询 Skill。"""
+        return self._skills.get(name)
+
+    def names(self) -> tuple[str, ...]:
+        """按名称排序返回已注册 Skill。"""
+        return tuple(sorted(self._skills))
+
+    def all(self) -> tuple[SkillSpec, ...]:
+        """返回全部 Skill 规格。"""
+        return tuple(self._skills[name] for name in self.names())
+
+    def load(
+        self,
+        path: str | Path,
+        *,
+        loader: SkillLoader | None = None,
+        replace: bool = False,
+    ) -> SkillSpec:
+        """加载并注册一个 Skill。"""
+        skill = (loader or SkillLoader()).load(path)
+        self.register(skill, replace=replace)
+        return skill
+
+    def load_directory(
+        self,
+        directory: str | Path,
+        *,
+        loader: SkillLoader | None = None,
+        replace: bool = False,
+    ) -> tuple[SkillSpec, ...]:
+        """批量加载 Skill，并在写入注册表前完成全部重名检查。"""
+        skills = (loader or SkillLoader()).load_directory(directory)
+        batch_duplicates = self._duplicates(skill.name for skill in skills)
+        if batch_duplicates:
+            raise SkillRegistrationError(f"目录中包含重复 Skill：{', '.join(batch_duplicates)}")
+        conflicts = sorted(skill.name for skill in skills if skill.name in self._skills and not replace)
+        if conflicts:
+            raise SkillRegistrationError(f"Skill 已注册：{', '.join(conflicts)}")
+        for skill in skills:
+            self.register(skill, replace=replace)
+        return skills
+
+    def activate(
+        self,
+        names: str | Iterable[str] | None = None,
+        *,
+        tool_registry: ToolRegistry,
+        functions: Mapping[str, Callable[..., Any]] | None = None,
+        mcp_clients: Mapping[str, McpToolCaller] | None = None,
+        replace_tools: bool = False,
+    ) -> SkillActivation:
+        """激活 Skill，并绑定其 Function 与 MCP 工具。
+
+        ``functions`` 的键对应工具 ``target``；``mcp_clients`` 的键对应 MCP
+        工具 ``server``。清单只声明绑定关系，不会动态导入任意 Python 代码。
+        """
+        selected = self._select(names)
+        functions = functions or {}
+        mcp_clients = mcp_clients or {}
+
+        declared: dict[str, tuple[str, SkillToolSpec]] = {}
+        bindings: list[tuple[SkillToolSpec, Callable[..., Any]]] = []
+        for skill in selected:
+            for tool in skill.tools:
+                previous = declared.get(tool.name)
+                if previous is not None:
+                    raise SkillRegistrationError(
+                        f"Skill {skill.name} 与 {previous[0]} 重复声明工具：{tool.name}"
+                    )
+                declared[tool.name] = (skill.name, tool)
+                if tool_registry.get_tool(tool.name) is not None and not replace_tools:
+                    raise SkillRegistrationError(f"工具已注册：{tool.name}")
+                bindings.append(
+                    (
+                        tool,
+                        self._resolve_binding(
+                            tool,
+                            skill_name=skill.name,
+                            functions=functions,
+                            mcp_clients=mcp_clients,
+                        ),
+                    )
+                )
+
+        # 所有依赖和冲突都通过后再写注册表，保证失败不会产生部分注册。
+        for tool, function in bindings:
+            tool_registry.register(
+                tool.name,
+                function,
+                tool.description,
+                parameters=tool.parameters,
+                risk_level=tool.risk_level,
+                requires_approval=tool.requires_approval,
+                timeout_seconds=tool.timeout_seconds,
+                idempotent=tool.idempotent,
+            )
+
+        instructions = "\n\n".join(
+            skill.instructions.strip() for skill in selected if skill.instructions.strip()
+        )
+        definitions = [
+            {
+                "type": "function",
+                "function": {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "parameters": tool.parameters,
+                },
+            }
+            for _, tool in declared.values()
+        ]
+        return SkillActivation(
+            skills=selected,
+            instructions=instructions,
+            tool_names=tuple(declared),
+            tool_definitions=definitions,
+        )
+
+    def _select(self, names: str | Iterable[str] | None) -> tuple[SkillSpec, ...]:
+        if names is None:
+            selected_names = list(self.names())
+        elif isinstance(names, str):
+            selected_names = [names]
+        else:
+            selected_names = list(names)
+        duplicates = self._duplicates(selected_names)
+        if duplicates:
+            raise SkillRegistrationError(f"重复激活 Skill：{', '.join(duplicates)}")
+        missing = [name for name in selected_names if name not in self._skills]
+        if missing:
+            raise SkillRegistrationError(f"Skill 未注册：{', '.join(missing)}")
+        return tuple(self._skills[name] for name in selected_names)
+
+    @staticmethod
+    def _resolve_binding(
+        tool: SkillToolSpec,
+        *,
+        skill_name: str,
+        functions: Mapping[str, Callable[..., Any]],
+        mcp_clients: Mapping[str, McpToolCaller],
+    ) -> Callable[..., Any]:
+        if tool.kind == "function":
+            function = functions.get(tool.target)
+            if function is None:
+                raise SkillBindingError(f"Skill {skill_name} 缺少 Function 绑定：{tool.target}")
+            if not callable(function):
+                raise SkillBindingError(f"Skill {skill_name} 的 Function 绑定不可调用：{tool.target}")
+            return function
+
+        server = tool.server
+        if server is None:
+            raise SkillBindingError(f"Skill {skill_name} 的 MCP 工具未声明 server")
+        client = mcp_clients.get(server)
+        if client is None:
+            raise SkillBindingError(f"Skill {skill_name} 缺少 MCP 客户端：{server}")
+
+        async def call_mcp(**arguments: Any) -> dict[str, object]:
+            return await client.call_tool(tool.target, arguments)
+
+        return call_mcp
+
+    @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__ = ["SkillRegistry"]

agent_core/skills/types.py

@@ -0,0 +1,56 @@
+"""Skill 公共数据结构。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+SkillToolKind = Literal["function", "mcp"]
+
+
+@dataclass(frozen=True, slots=True)
+class SkillToolSpec:
+    """Skill 声明的一个可调用工具。"""
+
+    name: str
+    kind: SkillToolKind
+    target: str
+    description: str
+    parameters: dict[str, Any] = field(default_factory=dict)
+    server: str | None = None
+    risk_level: str = "read"
+    requires_approval: bool = False
+    timeout_seconds: float | None = None
+    idempotent: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class SkillSpec:
+    """一个可复用 Skill 的完整声明。"""
+
+    name: str
+    description: str
+    version: str
+    instructions: str = ""
+    tools: tuple[SkillToolSpec, ...] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)
+    source: Path | None = None
+
+
+@dataclass(slots=True)
+class SkillActivation:
+    """一组 Skill 激活后交给 Agent 的提示词和工具定义。"""
+
+    skills: tuple[SkillSpec, ...]
+    instructions: str
+    tool_names: tuple[str, ...]
+    tool_definitions: list[dict[str, Any]]
+
+    def compose_system_prompt(self, base_prompt: str) -> str:
+        """把 Skill 指令追加到应用的基础系统提示词。"""
+        parts = [part.strip() for part in (base_prompt, self.instructions) if part.strip()]
+        return "\n\n".join(parts)
+
+
+__all__ = ["SkillActivation", "SkillSpec", "SkillToolKind", "SkillToolSpec"]

agent_core/storage/__init__.py

@@ -0,0 +1,107 @@
+"""Agent Core 的通用存储实现。
+
+SQLite 使用 Python 标准库，开箱即用；PostgreSQL 使用延迟导入的 ``asyncpg``，
+只有实际创建 PostgreSQL 存储时才要求安装对应驱动。
+"""
+
+from agent_core.ports.model_selection import (
+    ModelSelection,
+    ModelSelectionScope,
+    ModelSelectionStore,
+)
+from agent_core.storage.context import (
+    ContextStore,
+    MemoryContextStore,
+    PostgresContextStore,
+    SqliteContextStore,
+    create_context_store,
+)
+from agent_core.storage.lease import (
+    MemoryRunLeaseStore,
+    PostgresRunLeaseStore,
+    RunLease,
+    RunLeaseStore,
+    SqliteRunLeaseStore,
+    create_run_lease_store,
+)
+from agent_core.storage.memory import (
+    InMemoryMemoryStore,
+    PostgresMemoryStore,
+    SqliteMemoryStore,
+    create_memory_store,
+)
+from agent_core.storage.model_selection import (
+    MemoryModelSelectionStore,
+    PostgresModelSelectionStore,
+    SqliteModelSelectionStore,
+    create_model_selection_store,
+)
+from agent_core.storage.runtime import (
+    MemoryRuntimeStore,
+    PostgresRuntimeStore,
+    RuntimeConcurrencyError,
+    RuntimeStore,
+    SqliteRuntimeStore,
+    create_runtime_store,
+)
+from agent_core.storage.session import (
+    BaseSessionStore,
+    MemorySessionStore,
+    PostgresSessionStore,
+    SessionManager,
+    SqliteSessionStore,
+    create_session_store,
+)
+from agent_core.storage.workflow import (
+    MemoryWorkflowExecutionStore,
+    PostgresWorkflowExecutionStore,
+    SqliteWorkflowExecutionStore,
+    WorkflowConcurrencyError,
+    WorkflowExecution,
+    WorkflowExecutionStore,
+    create_workflow_execution_store,
+)
+
+__all__ = [
+    "BaseSessionStore",
+    "ContextStore",
+    "InMemoryMemoryStore",
+    "MemoryContextStore",
+    "MemoryModelSelectionStore",
+    "MemoryRunLeaseStore",
+    "MemoryRuntimeStore",
+    "MemorySessionStore",
+    "MemoryWorkflowExecutionStore",
+    "ModelSelection",
+    "ModelSelectionScope",
+    "ModelSelectionStore",
+    "PostgresContextStore",
+    "PostgresMemoryStore",
+    "PostgresModelSelectionStore",
+    "PostgresRunLeaseStore",
+    "PostgresRuntimeStore",
+    "PostgresSessionStore",
+    "PostgresWorkflowExecutionStore",
+    "RunLease",
+    "RunLeaseStore",
+    "RuntimeConcurrencyError",
+    "RuntimeStore",
+    "SessionManager",
+    "SqliteContextStore",
+    "SqliteMemoryStore",
+    "SqliteModelSelectionStore",
+    "SqliteRunLeaseStore",
+    "SqliteRuntimeStore",
+    "SqliteSessionStore",
+    "SqliteWorkflowExecutionStore",
+    "WorkflowConcurrencyError",
+    "WorkflowExecution",
+    "WorkflowExecutionStore",
+    "create_context_store",
+    "create_memory_store",
+    "create_model_selection_store",
+    "create_run_lease_store",
+    "create_runtime_store",
+    "create_session_store",
+    "create_workflow_execution_store",
+]

agent_core/storage/_sqlite_utils.py

@@ -0,0 +1,92 @@
+"""SQLite 存储共享工具：统一连接参数规范与线程池执行包装。
+
+sqlite3 驱动是同步实现；写锁等待（busy timeout）会冻结所在线程。
+存储层保持"每操作开新连接"的简单模型，但所有 async 方法体统一经
+`_run_in_thread` 放入工作线程执行，把可能的锁等待隔离在事件循环之外。
+
+统一连接参数规范（各存储的 `_connect` 必须经 `sqlite_connection` 复用）：
+
+- ``timeout=30.0``：写锁等待上限 30 秒，超时抛 ``sqlite3.OperationalError``；
+- `ensure_wal`：WAL 是库级持久属性（保存在数据库文件中），在存储初始化
+  建连接时开启一次即可，之后的连接自动继承。`sqlite_connection` 每次建连
+  都幂等调用 `ensure_wal`，因此初始化与后续每操作连接使用同一规范。
+
+构造期 DDL / PRAGMA 初始化同样入线程：构造函数是同步入口、无法 ``await``，
+统一经 `run_sync_in_thread` 在一次性工作线程中执行后返回。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+from collections.abc import Callable, Generator
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "SQLITE_CONNECT_TIMEOUT",
+    "_run_in_thread",
+    "ensure_wal",
+    "run_sync_in_thread",
+    "sqlite_connection",
+]
+
+# 所有 SQLite 存储统一使用的写锁等待上限（秒）。
+SQLITE_CONNECT_TIMEOUT = 30.0
+
+# 连接级回调签名：与 sqlite3.Connection.row_factory 的类型契约一致。
+RowFactory = Callable[[sqlite3.Cursor, tuple[Any, ...]], Any]
+
+
+def ensure_wal(conn: sqlite3.Connection) -> None:
+    """开启 WAL 日志模式与 NORMAL 同步级别（幂等，可重复调用）。
+
+    WAL 是库级属性：一经设置即持久保存在数据库文件中，后续连接自动继承；
+    ``synchronous`` 是连接级属性，因此每次建连都需要重新设置。
+    """
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA synchronous=NORMAL")
+
+
+@contextmanager
+def sqlite_connection(
+    db_path: str | Path,
+    *,
+    row_factory: RowFactory | None = None,
+) -> Generator[sqlite3.Connection]:
+    """按统一参数规范打开一个自动提交/回滚的 SQLite 连接（每操作一个）。
+
+    - ``timeout=30.0``：统一写锁等待上限；
+    - `ensure_wal`：统一开启 WAL 与 ``synchronous=NORMAL``。
+
+    退出时提交；异常时回滚并原样抛出；连接在 finally 中关闭。
+    """
+    conn = sqlite3.connect(str(db_path), timeout=SQLITE_CONNECT_TIMEOUT)
+    try:
+        if row_factory is not None:
+            conn.row_factory = row_factory
+        ensure_wal(conn)
+        yield conn
+        conn.commit()
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+async def _run_in_thread[T](func: Callable[[], T]) -> T:
+    """把同步 SQLite IO 放到默认线程池执行，避免锁等待冻结事件循环。"""
+    return await asyncio.to_thread(func)
+
+
+def run_sync_in_thread[T](func: Callable[[], T]) -> T:
+    """在一次性工作线程中执行同步初始化（DDL/PRAGMA）并等待完成。
+
+    存储构造函数是同步入口，无法 ``await``；初始化放入独立线程执行，
+    与 async 方法共用同一连接参数规范。
+    """
+    with ThreadPoolExecutor(max_workers=1, thread_name_prefix="agent-core-sqlite-init") as pool:
+        return pool.submit(func).result()