my-pi-agent 0.1.0

package/src/my_agent_core/extensions/core.py

@@ -0,0 +1,197 @@
+"""extension 机制 —— 外部扩展加载（事件订阅 + 工具注册 + 命令）。
+
+ExtensionAPI 是传给 extension 的能力面（on / tool / command 三件套）；
+ExtensionManager 是 Repository（发现 / 加载 / 命令调度），对标 SkillManager /
+SubagentManager。加载协议：扩展文件定义 `def extension(api)`（或 default /
+第一个形参名含 api 的函数），由 importlib 动态加载。
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import inspect
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, overload
+
+from my_agent_core.events import Event
+from my_agent_core.tools import Tool
+from my_agent_core.tools import tool as _tool
+
+if TYPE_CHECKING:
+    from my_agent_core.agent import Agent
+
+CommandHandler = Callable[..., Any]
+
+
+class ExtensionAPI:
+    """暴露给 extension 的能力面：事件订阅 + 工具注册 + 命令。"""
+
+    def __init__(self, agent: Agent) -> None:
+        self.agent = agent
+        self._commands: dict[str, CommandHandler] = {}
+        self._descriptions: dict[str, str] = {}
+
+    # ── 事件订阅 / Hook 拦截注册（支持 @api.on 作装饰器）────────
+
+    @overload
+    def on(
+        self, target: type, handler: None = None
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]: ...
+
+    @overload
+    def on(self, target: type, handler: Callable[..., Any]) -> None: ...
+
+    def on(self, target: type, handler: Callable[..., Any] | None = None) -> Any:
+        """注册只读事件订阅（Event 监听）或双向 Hook 拦截点回调（Hook 拦截干预）。
+
+        handler 签名统一为 (payload, api)。
+        - 若 target 是 Event 子类：注册至 agent.subscribe() 作为只读通知，忽略返回值；
+        - 否则：注册至 agent.hooks.register()，可返回 HookResult 进行干预。
+        """
+
+        def _register(h: Callable[..., Any]) -> Callable[..., Any]:
+            if isinstance(target, type) and issubclass(target, Event):
+
+                def event_listener(event: Event) -> Any:
+                    if isinstance(event, target):
+                        return h(event, self)
+
+                self.agent.subscribe(event_listener)
+            else:
+                if inspect.iscoroutinefunction(h):
+
+                    async def wrapped_async(hook_payload: Any) -> Any:
+                        return await h(hook_payload, self)
+
+                    self.agent.hooks.register(target, wrapped_async)
+                else:
+
+                    def wrapped_sync(hook_payload: Any) -> Any:
+                        return h(hook_payload, self)
+
+                    self.agent.hooks.register(target, wrapped_sync)
+            return h
+
+        if handler is not None:
+            _register(handler)
+            return None
+        return _register
+
+    # ── 工具注册（复用 @tool）────────────────────────────────────────
+
+    def register_tool(self, tool: Tool) -> None:
+        """注册工具 → agent.registry（撞名静默覆盖，registry 语义）。"""
+        self.agent.registry.register(tool)
+
+    def tool(self, **kwargs: Any):
+        """@api.tool(description=...) 装饰器：@tool 包装 + register_tool。"""
+
+        def decorator(func) -> Tool:
+            t = _tool(**kwargs)(func)
+            self.register_tool(t)
+            return t
+
+        return decorator
+
+    # ── 命令（注册 + 存表，调度在 ExtensionManager）────────────────────
+
+    def register_command(
+        self, name: str, handler: CommandHandler, description: str = ""
+    ) -> None:
+        """注册命令（name 不含 /）。"""
+        self._commands[name] = handler
+        self._descriptions[name] = description
+
+    def command(self, name: str, description: str = ""):
+        """@api.command("now") 装饰器。"""
+
+        def decorator(func: CommandHandler) -> CommandHandler:
+            self.register_command(name, func, description)
+            return func
+
+        return decorator
+
+    def get_commands(self) -> dict[str, CommandHandler]:
+        """已注册命令的拷贝（name → handler）。"""
+        return self._commands.copy()
+
+
+class ExtensionManager:
+    """扩展管理器（Repository）：发现 / 加载 / 命令调度。"""
+
+    DEFAULT_DIR_NAME = "extensions"  # <cwd>/.agents/extensions
+
+    def __init__(
+        self, agent: Agent, extension_dirs: Sequence[str | Path] | None = None
+    ):
+        """解析目录（三态同 skill_dirs）：None → 探测 <cwd>/.agents/extensions；
+        [] → 禁用；非空 → 只扫这些目录。load() 显式加载（有副作用）。"""
+        self.agent = agent
+        self.api = ExtensionAPI(agent)
+        self.extensions: dict[str, Any] = {}
+        if extension_dirs is None:
+            dirs = [Path.cwd() / ".agents" / self.DEFAULT_DIR_NAME]
+        else:
+            dirs = list(extension_dirs)
+        self._dirs: list[Path] = [Path(d) for d in dirs]
+
+    def discover(self, directory: Path | str) -> list[Path]:
+        """扫目录下 **/*.py（递归），跳过 _ 开头私有文件；目录不存在 → []。"""
+        directory = Path(directory)
+        if not directory.exists():
+            return []
+        return [p for p in directory.glob("**/*.py") if not p.name.startswith("_")]
+
+    async def load_extension(self, path: Path | str) -> None:
+        """importlib 动态加载 .py；找 extension → default → 第一个形参名含 api 的函数；
+        找不到 → ValueError；找到则 extension_func(self.api) 执行并登记。支持 async/sync 扩展。"""
+        path = Path(path)
+        if not path.exists():
+            raise FileNotFoundError(f"Extension not found: {path}")
+        spec = importlib.util.spec_from_file_location(path.stem, path)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Cannot load extension: {path}")
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+
+        extension_func = None
+        if hasattr(module, "extension"):
+            extension_func = module.extension
+        elif hasattr(module, "default"):
+            extension_func = module.default
+        else:
+            for _name, obj in inspect.getmembers(module, inspect.isfunction):
+                sig = inspect.signature(obj)
+                params = list(sig.parameters.values())
+                if params and "api" in params[0].name.lower():
+                    extension_func = obj
+                    break
+        if extension_func is None:
+            raise ValueError(
+                f"Extension {path} must define an 'extension' function that takes ExtensionAPI"
+            )
+        if inspect.iscoroutinefunction(extension_func):
+            await extension_func(self.api)
+        else:
+            extension_func(self.api)
+        self.extensions[path.name] = module
+
+    async def load(self) -> None:
+        """遍历 self._dirs 逐个 load_extension；单个失败只 print 不抛（隔离坏扩展）。"""
+        for directory in self._dirs:
+            for path in self.discover(directory):
+                try:
+                    await self.load_extension(path)
+                except Exception as exc:
+                    print(f"Failed to load extension {path}: {exc}")
+
+    def handle_command(self, command: str, args: str | None = None) -> Any:
+        """查表调用命令（未知命令 ValueError；0 参直接调，>0 参传 args）。"""
+        commands = self.api.get_commands()
+        if command not in commands:
+            raise ValueError(f"Unknown command: /{command}")
+        handler = commands[command]
+        if len(inspect.signature(handler).parameters) > 0:
+            return handler(args)
+        return handler()

package/src/my_agent_core/hooks.py

@@ -0,0 +1,130 @@
+"""专职 Hook 拦截点契约与 HookRegistry —— Agent 关键节点双向拦截干预与控制流门禁。
+
+架构设计（对齐 Pi 架构）：
+1. 专职 Hook 拦截点契约（*Hook）：独立于 Event，专职控制流拦截、入参安全审批与出参改写。
+2. 统一干预结果模型（HookResult）：携带 block、reason、updated_* 属性，指示核心状态机如何处置。
+3. HookRegistry：负责拦截钩子的注册、注销、async/sync 混合调用及严格的 Never-Throw 异常隔离。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import inspect
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from my_agent_llm import Message  # pyright: ignore[reportMissingImports]
+
+logger = logging.getLogger(__name__)
+
+
+# ── 五大专职 Hook 拦截点契约（独立门禁系统，非 Event）
+@dataclass(frozen=True)
+class UserInputHook:
+    """Hook 1 (input): 拦截或改写用户原始输入文本。"""
+
+    input_text: str
+
+
+@dataclass(frozen=True)
+class AgentStartHook:
+    """Hook 2 (before_agent_start): 拦截启动或动态重写 system_prompt。"""
+
+    system_prompt: str
+
+
+@dataclass(frozen=True)
+class BeforeModelCallHook:
+    """Hook 3 (context): 调模型前 1ms 审查或临时改写发送视图。"""
+
+    messages: list[Message]
+    iteration: int
+
+
+@dataclass(frozen=True)
+class ToolCallHook:
+    """Hook 4 (tool_call): 工具执行前安全审批、阻断高危命令或改写入参。"""
+
+    tool_call_id: str
+    tool_name: str
+    args: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ToolResultHook:
+    """Hook 5 (tool_result): 工具执行后改写返回内容或篡改报错状态。"""
+
+    tool_call_id: str
+    tool_name: str
+    result: str
+    is_error: bool
+    terminate: bool = False
+
+
+@dataclass(frozen=True)
+class HookResult:
+    """Hook 拦截点的统一干预结果。返回 None = 纯观察，返回 HookResult = 干预。
+
+    - UserInputHook 用 block / reason / updated_input（拦截 / 改写用户输入）
+    - AgentStartHook 用 block / reason / updated_system_prompt（拦截 / 改写 system prompt）
+    - BeforeModelCallHook 用 block / reason / updated_messages（拦截 / 临时改写送给 LLM 的 messages 视图）
+    - ToolCallHook 用 block / reason / updated_args（拦截 / 改参数）
+    - ToolResultHook 用 updated_result（改结果）
+    """
+
+    block: bool = False
+    reason: str | None = None
+    updated_input: str | None = None
+    updated_system_prompt: str | None = None
+    updated_messages: list[Message] | None = None
+    updated_args: dict[str, Any] | None = None
+    updated_result: str | None = None
+    terminate: bool | None = None
+
+
+class HookRegistry:
+    """Hook 注册表：Hook 类型 → callback 列表。
+
+    支持 async / sync 钩子混合执行与 Never-Throw 异常捕获隔离。
+    """
+
+    def __init__(self) -> None:
+        self._handlers: dict[type, list[Callable[..., Any]]] = {}
+        self._hooks = self._handlers
+
+    def register(self, hook_cls: type, callback: Callable[..., Any]) -> None:
+        """挂一个 hook 回调到 hook 类型。同一 hook 可挂多个，按注册顺序触发。"""
+        self._handlers.setdefault(hook_cls, []).append(callback)
+
+    def unregister(self, hook_cls: type, callback: Callable[..., Any]) -> None:
+        """移除 hook 回调。"""
+        with contextlib.suppress(ValueError):
+            self._handlers.get(hook_cls, []).remove(callback)
+
+    async def emit(self, hook_payload: Any) -> HookResult | None:
+        """异步触发 hook 的所有回调，支持协程与普通函数。
+
+        - 返回第一个非 None 结果（短路）。
+        - 坚守 Never-Throw 保证：若回调执行抛出异常，捕获并记录日志，绝不向外抛出异常，继续执行后续回调。
+        """
+        for cb in list(self._handlers.get(type(hook_payload), [])):
+            try:
+                if inspect.iscoroutinefunction(cb):
+                    result = await cb(hook_payload)
+                else:
+                    result = cb(hook_payload)
+                    if inspect.isawaitable(result):
+                        result = await result
+                if result is not None:
+                    return result
+            except Exception as e:
+                logger.error(
+                    "Hook callback %r failed on %r: %s",
+                    cb,
+                    hook_payload,
+                    e,
+                    exc_info=True,
+                )
+        return None