sdpy-kit 0.7.5__tar.gz → 0.8.1__tar.gz

{sdpy_kit-0.7.5 → sdpy_kit-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.7.5
+Version: 0.8.1
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -22,6 +22,12 @@ Requires-Dist: pydantic-settings>=2.16.1
 Requires-Dist: pydantic>=2.14.1
 Requires-Dist: sqlalchemy~=2.0.54
 Requires-Dist: sqlmodel>=0.0.48
+Provides-Extra: agent
+Requires-Dist: fastmcp-slim[client]<5,>=4.1.7; extra == 'agent'
+Requires-Dist: httpx>=0.28.1; extra == 'agent'
+Requires-Dist: openai<4,>=3.44; extra == 'agent'
+Requires-Dist: python-dotenv>=1.2.4; extra == 'agent'
+Requires-Dist: pyyaml>=6.0.3; extra == 'agent'
 Provides-Extra: ai
 Requires-Dist: httpx>=0.28.1; extra == 'ai'
 Requires-Dist: openai<4,>=3.44; extra == 'ai'
@@ -97,6 +103,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.config` | `get_settings` / `get_default_logger` | 配置单例与统一日志 | 无 |
 | `kit.db` | `SQLiteKit` / `PgKit` / `MySqlKit` / `CRUDBase` | 统一 CRUD、原生 SQL、原生表操作、事务、表管理 | `pg` / `mysql` / `sqliteai` |
 | `kit.ai` | `AI`（同步门面）/ 4 个原生异步 Service | 对话 / 向量化 / 重排序 / 文生图 | `ai` |
+| `kit.ai.agent` | `Agent` / `ToolRegistry` / `SkillRegistry` / `McpServerConfig` / `Session` | MCP client（HTTP / stdio）+ Skill 包加载 + 模型驱动工具循环 | `agent` |
 | `kit.redis_kit` | `RedisKit` | Redis string / hash / list / set / zset | `redis` |
 | `kit.file_kit` | `FileKit` | 文件与目录读写、移动、遍历 | 无 |
 | `kit.common_kit` | `CommonKit` | 雪花 ID、时间戳 ID、时间格式化 | 无 |
@@ -140,8 +147,48 @@ uv add sdpy-kit
 | `laya` | LayaKit 类型化决策（laya + torch，本地小模型 choice / multi_choice / score / noul；支持多字段 / 批量 / 长文本） | `pip install "sdpy-kit[laya]"` |
 | `decima` | DecimaKit 决策模型（decima-ai + onnxruntime，**无 torch**；选项乱序不变、置信度可门控；磁盘约 137 MB） | `pip install "sdpy-kit[decima]"` |
 | `web-article` | WebArticleKit 通用网页文章抓取转存（trafilatura，纯 HTTP 无浏览器） | `pip install "sdpy-kit[web-article]"` |
+| `agent` | Agent 能力：MCP client（fastmcp-slim）+ Skill 加载 + 工具循环（含 ai 三项依赖与 pyyaml） | `pip install "sdpy-kit[agent]"` |
 | `recommended` | 常用能力集合（DB / 缓存 / AI / 文档 / 抓取）；不含重依赖（laya / decima）与 Marker（0.7.0 起暂停发布） | `pip install "sdpy-kit[recommended]"` |
 
+## Agent 快速开始（extra `agent`）
+
+```python
+import asyncio
+
+from kit.ai.agent import Agent, McpServerConfig, SkillRegistry
+
+
+async def main() -> None:
+    skills = SkillRegistry()
+    skills.load("./skills")  # 一级子目录含 SKILL.md 即注册
+
+    agent = Agent(
+        skills=skills,
+        servers=[
+            McpServerConfig(
+                name="filesystem",
+                transport="stdio",
+                command="npx",
+                args=["-y", "@modelcontextprotocol/server-filesystem", "./data"],
+            )
+        ],
+        system_prompt="你是一个谨慎的文档助手。",
+    )
+
+    async with agent:  # 建连一次，可多次 run()
+        result = await agent.run("总结 data 目录里的文件")
+        print(result.text)
+
+
+asyncio.run(main())
+```
+
+- 模型档案沿用 `kit.ai`（`config/ai_models.json`），首轮可 failover，成功后锁定档案；
+- Skill 只读工具：`read_skill` / `list_skill_files` / `read_skill_file`（路径越界拒绝）；
+- MCP 工具默认放行，skill 脚本默认拒绝；可用 `DenyAllApproval` 整体收紧；
+- `timeout` / `max_turns` / `tool_timeout` 控制总预算与轮次；
+- 完整说明见 `docs/agents/modules/agent-kit.md`（仓库内）。
+
 ## 配置（.env）
 
 kit 通过 pydantic-settings 读取项目根目录 `.env`；**同名真实环境变量优先于 `.env`**。全部变量都有默认值，按需覆盖即可。

{sdpy_kit-0.7.5 → sdpy_kit-0.8.1}/README.md

@@ -15,6 +15,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.config` | `get_settings` / `get_default_logger` | 配置单例与统一日志 | 无 |
 | `kit.db` | `SQLiteKit` / `PgKit` / `MySqlKit` / `CRUDBase` | 统一 CRUD、原生 SQL、原生表操作、事务、表管理 | `pg` / `mysql` / `sqliteai` |
 | `kit.ai` | `AI`（同步门面）/ 4 个原生异步 Service | 对话 / 向量化 / 重排序 / 文生图 | `ai` |
+| `kit.ai.agent` | `Agent` / `ToolRegistry` / `SkillRegistry` / `McpServerConfig` / `Session` | MCP client（HTTP / stdio）+ Skill 包加载 + 模型驱动工具循环 | `agent` |
 | `kit.redis_kit` | `RedisKit` | Redis string / hash / list / set / zset | `redis` |
 | `kit.file_kit` | `FileKit` | 文件与目录读写、移动、遍历 | 无 |
 | `kit.common_kit` | `CommonKit` | 雪花 ID、时间戳 ID、时间格式化 | 无 |
@@ -58,8 +59,48 @@ uv add sdpy-kit
 | `laya` | LayaKit 类型化决策（laya + torch，本地小模型 choice / multi_choice / score / noul；支持多字段 / 批量 / 长文本） | `pip install "sdpy-kit[laya]"` |
 | `decima` | DecimaKit 决策模型（decima-ai + onnxruntime，**无 torch**；选项乱序不变、置信度可门控；磁盘约 137 MB） | `pip install "sdpy-kit[decima]"` |
 | `web-article` | WebArticleKit 通用网页文章抓取转存（trafilatura，纯 HTTP 无浏览器） | `pip install "sdpy-kit[web-article]"` |
+| `agent` | Agent 能力：MCP client（fastmcp-slim）+ Skill 加载 + 工具循环（含 ai 三项依赖与 pyyaml） | `pip install "sdpy-kit[agent]"` |
 | `recommended` | 常用能力集合（DB / 缓存 / AI / 文档 / 抓取）；不含重依赖（laya / decima）与 Marker（0.7.0 起暂停发布） | `pip install "sdpy-kit[recommended]"` |
 
+## Agent 快速开始（extra `agent`）
+
+```python
+import asyncio
+
+from kit.ai.agent import Agent, McpServerConfig, SkillRegistry
+
+
+async def main() -> None:
+    skills = SkillRegistry()
+    skills.load("./skills")  # 一级子目录含 SKILL.md 即注册
+
+    agent = Agent(
+        skills=skills,
+        servers=[
+            McpServerConfig(
+                name="filesystem",
+                transport="stdio",
+                command="npx",
+                args=["-y", "@modelcontextprotocol/server-filesystem", "./data"],
+            )
+        ],
+        system_prompt="你是一个谨慎的文档助手。",
+    )
+
+    async with agent:  # 建连一次，可多次 run()
+        result = await agent.run("总结 data 目录里的文件")
+        print(result.text)
+
+
+asyncio.run(main())
+```
+
+- 模型档案沿用 `kit.ai`（`config/ai_models.json`），首轮可 failover，成功后锁定档案；
+- Skill 只读工具：`read_skill` / `list_skill_files` / `read_skill_file`（路径越界拒绝）；
+- MCP 工具默认放行，skill 脚本默认拒绝；可用 `DenyAllApproval` 整体收紧；
+- `timeout` / `max_turns` / `tool_timeout` 控制总预算与轮次；
+- 完整说明见 `docs/agents/modules/agent-kit.md`（仓库内）。
+
 ## 配置（.env）
 
 kit 通过 pydantic-settings 读取项目根目录 `.env`；**同名真实环境变量优先于 `.env`**。全部变量都有默认值，按需覆盖即可。

{sdpy_kit-0.7.5 → sdpy_kit-0.8.1}/kit/__init__.py

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.7.5"
+__version__ = "0.8.1"
 
 from kit.db import (
     MYSQL,

{sdpy_kit-0.7.5 → sdpy_kit-0.8.1}/kit/ai/__init__.py

@@ -32,6 +32,9 @@ Author: Clark Chang
 同步门面与决策引擎：
 - AI / run_sync / reload_config / shutdown / ReloadResult
 - DecimaKit / LayaKit（extra ``decima`` / ``laya``，不进 ``__all__``）
+
+Agent（extra ``agent``，不进 ``__all__``）：
+- Agent / ToolRegistry / Session / McpServerConfig
 """
 
 from importlib import import_module
@@ -73,6 +76,12 @@ _EXPORTS: dict[str, str] = {
     "DecimaError": "kit.ai.decision",
     "LayaKit": "kit.ai.decision",
     "LayaError": "kit.ai.decision",
+    # Agent 能力（extra ``agent``）只支持显式导入，不进 __all__：
+    # ``from kit.ai import *`` 不应在基础安装下触发 fastmcp。
+    "Agent": "kit.ai.agent",
+    "ToolRegistry": "kit.ai.agent",
+    "Session": "kit.ai.agent",
+    "McpServerConfig": "kit.ai.agent",
 }
 
 
@@ -86,4 +95,16 @@ def __getattr__(name: str) -> Any:
 
 
 def __dir__() -> list[str]:
-    return sorted(set(__all__) | {"DecimaError", "DecimaKit", "LayaError", "LayaKit"})
+    return sorted(
+        set(__all__)
+        | {
+            "DecimaError",
+            "DecimaKit",
+            "LayaError",
+            "LayaKit",
+            "Agent",
+            "ToolRegistry",
+            "Session",
+            "McpServerConfig",
+        }
+    )

{sdpy_kit-0.7.5 → sdpy_kit-0.8.1}/kit/ai/_internal/failover.py

@@ -34,14 +34,22 @@ Author: Clark Chang
 
 import asyncio
 import time
-from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable
+from collections.abc import (
+    AsyncGenerator,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Mapping,
+    Sequence,
+)
 from typing import Any, Final, TypeVar, cast
 
 from kit.ai._internal.pool import AIServicePool
-from kit.ai.chat_service import ChatService, StreamStats
+from kit.ai.chat_service import ChatService, StreamStats, ToolSpecLike
 from kit.ai.embedding_service import EmbeddingService
 from kit.ai.exceptions import AIAggregateError, AIError, AIRequestError, AITimeoutError
 from kit.ai.image_service import ImageResult, ImageService
+from kit.ai.messages import ChatReply
 from kit.ai.model_builder import Service
 from kit.ai.rerank_service import RerankHit, RerankService
 
@@ -68,6 +76,13 @@ class _FailoverBase:
     def __init__(self, pool: AIServicePool, model_type: str) -> None:
         self._pool: AIServicePool = pool
         self._model_type: str = model_type
+        # 最近一次成功的档案名（工具循环据此锁定档案，避免中途换模型）
+        self._last_profile: str | None = None
+
+    @property
+    def last_profile(self) -> str | None:
+        """最近一次成功调用使用的档案名；从未成功时为 None。"""
+        return self._last_profile
 
     def _aggregate_error(
         self,
@@ -146,6 +161,7 @@ class _FailoverBase:
                 )
                 continue
             self._pool.mark_success(self._model_type, name)
+            self._last_profile = name
             return result
         raise self._aggregate_error(
             label, tried, errors, budget_exhausted=budget_exhausted
@@ -194,6 +210,40 @@ class FailoverChatService(_FailoverBase):
 
         return await self._attempt("对话", _run, deadline=deadline)
 
+    async def create_with_tools(
+        self,
+        messages: list[dict[str, Any]],
+        tools: Sequence[ToolSpecLike | Mapping[str, Any]],
+        *,
+        tool_choice: str | dict[str, Any] | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        thinking: bool | None = None,
+        stats: StreamStats | None = None,
+        deadline: float | None = None,
+    ) -> ChatReply:
+        """带工具定义的对话（链式故障切换）。
+
+        仅第 1 轮使用本方法：成功后调用方可读 :attr:`last_profile` 锁定档案，
+        后续轮次改用单档案 ``ChatService``，不再切换候选。
+        """
+
+        async def _run(service: Service) -> ChatReply:
+            if stats is not None:
+                stats.reset()
+            return await cast(ChatService, service).create_with_tools(
+                messages,
+                tools,
+                tool_choice=tool_choice,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                thinking=thinking,
+                stats=stats,
+                deadline=deadline,
+            )
+
+        return await self._attempt("工具对话", _run, deadline=deadline)
+
     async def create_once(
         self,
         prompt: str,

{sdpy_kit-0.7.5 → sdpy_kit-0.8.1}/kit/ai/_internal/rerank_transport.py

@@ -37,10 +37,10 @@ except ImportError as e:
         "kit.ai 需要可选依赖，请安装：pip install sdpy-kit[ai]"
     ) from e
 
-from kit.ai._internal._retry_after import MIN_RETRY_BUDGET, parse_retry_after
+from kit.ai._internal.retry_after import MIN_RETRY_BUDGET, parse_retry_after
+from kit.ai._internal.types import JSONObject
 from kit.ai.exceptions import AIRequestError, AIResponseError, AITimeoutError
 from kit.ai.profiles import ModelProfile
-from kit.ai.types import JSONObject
 
 __all__ = ["RerankTransport"]
 

{sdpy_kit-0.7.5 → sdpy_kit-0.8.1}/kit/ai/_internal/sdk_client.py

@@ -46,16 +46,17 @@ except ImportError as e:
         "kit.ai 需要可选依赖，请安装：pip install sdpy-kit[ai]"
     ) from e
 
-from kit.ai._internal._retry_after import MIN_RETRY_BUDGET, parse_retry_after
-from kit.ai._internal._service_base import LoggingServiceBase
+from kit.ai._internal.retry_after import MIN_RETRY_BUDGET, parse_retry_after
+from kit.ai._internal.service_base import LoggingServiceBase
+from kit.ai._internal.types import JSONObject
 from kit.ai.exceptions import (
     AIError,
     AIRequestError,
     AIResponseError,
     AITimeoutError,
 )
+from kit.ai.messages import ChatReply, ToolCall
 from kit.ai.profiles import ModelProfile, resolve_max_tokens
-from kit.ai.types import JSONObject
 from kit.config.log_config import get_default_logger
 
 __all__ = ["SdkClient", "SdkServiceBase"]
@@ -101,6 +102,41 @@ def _reasoning_of(holder: Any) -> str:
     return ""
 
 
+def _parse_tool_calls(message: Any) -> list[ToolCall]:
+    """把 SDK 的 ``message.tool_calls`` 收敛为 kit 的 ``ToolCall`` 列表。
+
+    ``arguments`` 在 OpenAI 协议里是 JSON 字符串；部分兼容端点回 dict，
+    统一序列化为字符串（``ToolCall`` 的契约就是字符串）。
+    """
+    raw = getattr(message, "tool_calls", None)
+    if raw is None:
+        raw = _extra_of(message, "tool_calls")
+    if not raw:
+        return []
+    if not isinstance(raw, list):
+        raise AIResponseError("tool_calls 类型异常")
+    calls: list[ToolCall] = []
+    for index, item in enumerate(raw):
+        function = getattr(item, "function", None)
+        name = getattr(function, "name", None)
+        arguments = getattr(function, "arguments", None)
+        call_id = getattr(item, "id", None)
+        if not isinstance(name, str) or not name:
+            raise AIResponseError(f"tool_calls[{index}] 缺少 function.name")
+        if arguments is None:
+            arguments = "{}"
+        elif not isinstance(arguments, str):
+            arguments = json.dumps(arguments, ensure_ascii=False)
+        calls.append(
+            ToolCall(
+                id=str(call_id or f"call_{index}"),
+                type="function",
+                function={"name": name, "arguments": arguments},
+            )
+        )
+    return calls
+
+
 class SdkClient:
     """openai SDK 客户端（全异步，单实例复用）。
 
@@ -181,11 +217,13 @@ class SdkClient:
 
     def _chat_params(
         self,
-        messages: list[dict[str, str]],
+        messages: list[dict[str, Any]],
         extra_body: JSONObject | None,
         response_format: JSONObject | None,
         temperature: float | None,
         max_tokens: int | None,
+        tools: list[dict[str, Any]] | None = None,
+        tool_choice: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         params: dict[str, Any] = {
             "model": self._profile.model,
@@ -198,23 +236,39 @@ class SdkClient:
             params["max_tokens"] = effective_max_tokens
         if response_format is not None:
             params["response_format"] = response_format
+        if tools:
+            params["tools"] = tools
+        if tool_choice is not None:
+            params["tool_choice"] = tool_choice
         if extra_body:
             params["extra_body"] = extra_body
         return params
 
-    async def chat(
+    async def chat_raw(
         self,
         *,
-        messages: list[dict[str, str]],
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        tool_choice: str | dict[str, Any] | None = None,
         extra_body: JSONObject | None = None,
         response_format: JSONObject | None = None,
         temperature: float | None = None,
         max_tokens: int | None = None,
         deadline: float | None = None,
-    ) -> tuple[str | None, str, str | None]:
-        """非流式对话，返回 ``(正文, 推理文本, finish_reason)``。"""
+    ) -> ChatReply:
+        """非流式对话，返回完整回复（含 ``tool_calls``）。
+
+        ``tools`` 必须是已包装好的 OpenAI 结构（``type=function`` +
+        ``function.{name,description,parameters}``），字段改名由服务层完成。
+        """
         params = self._chat_params(
-            messages, extra_body, response_format, temperature, max_tokens
+            messages,
+            extra_body,
+            response_format,
+            temperature,
+            max_tokens,
+            tools=tools,
+            tool_choice=tool_choice,
         )
         resp = await self._request(
             lambda: self._client.chat.completions.create(
@@ -233,7 +287,33 @@ class SdkClient:
         if content is not None and not isinstance(content, str):
             raise AIResponseError(f"content 类型异常: {type(content).__name__}")
         finish = getattr(choice, "finish_reason", None)
-        return content, _reasoning_of(message), finish
+        return ChatReply(
+            content=content,
+            reasoning=_reasoning_of(message),
+            finish_reason=finish if isinstance(finish, str) else None,
+            tool_calls=_parse_tool_calls(message),
+        )
+
+    async def chat(
+        self,
+        *,
+        messages: list[dict[str, Any]],
+        extra_body: JSONObject | None = None,
+        response_format: JSONObject | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        deadline: float | None = None,
+    ) -> tuple[str | None, str, str | None]:
+        """非流式对话，返回 ``(正文, 推理文本, finish_reason)``。"""
+        reply = await self.chat_raw(
+            messages=messages,
+            extra_body=extra_body,
+            response_format=response_format,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            deadline=deadline,
+        )
+        return reply.content, reply.reasoning, reply.finish_reason
 
     async def chat_stream(
         self,

sdpy_kit-0.7.5/kit/ai/_internal/_service_base.py → sdpy_kit-0.8.1/kit/ai/_internal/service_base.py

@@ -31,9 +31,9 @@ from collections.abc import Iterator
 from contextlib import contextmanager
 from typing import ClassVar
 
+from kit.ai._internal.types import JSONValue
 from kit.ai.exceptions import AIError, AIResponseError
 from kit.ai.profiles import ModelProfile
-from kit.ai.types import JSONValue
 from kit.config.log_config import get_default_logger
 
 __all__ = ["LoggingServiceBase", "safe_get"]

{sdpy_kit-0.7.5/kit/ai → sdpy_kit-0.8.1/kit/ai/_internal}/types.py

@@ -17,7 +17,7 @@ Project: sdpy
 Author: Clark Chang
 """
 
-"""kit/ai 公共类型别名（PEP 695 type 语句，递归 JSON 类型）"""
+"""kit/ai 内部 JSON 类型别名（PEP 695 type 语句，递归 JSON 类型）"""
 
 # 递归 JSON 值类型：标量 | 数组 | 对象
 type JSONScalar = str | int | float | bool | None

sdpy_kit-0.8.1/kit/ai/agent/__init__.py

@@ -0,0 +1,127 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+# date: 2026-11-10
+"""kit.ai.agent - MCP + Skill + 工具循环（PEP 562 延迟导出）。
+
+``import kit.ai.agent`` 本身不加载任何可选依赖；访问 ``Agent`` /
+``McpConnection`` 时才检查 fastmcp 是否安装，缺依赖报错会提示
+``pip install sdpy-kit[agent]``。
+"""
+
+from importlib import import_module, util
+from typing import Any
+
+__all__ = [
+    "Agent",
+    "AgentConfigError",
+    "AgentEmptyReplyError",
+    "AgentError",
+    "AgentModelError",
+    "AgentResult",
+    "AgentTimeoutError",
+    "AgentTruncatedError",
+    "ApprovalDeniedError",
+    "ApprovalHook",
+    "ApprovalRequest",
+    "DefaultApproval",
+    "DenyAllApproval",
+    "DuplicateSkillError",
+    "MaxTurnsExceeded",
+    "McpConnection",
+    "McpConnectionError",
+    "McpServerConfig",
+    "SkillError",
+    "SkillNotFoundError",
+    "SkillPackage",
+    "SkillRegistry",
+    "SkillScript",
+    "SkillValidationError",
+    "Session",
+    "ToolCallRecord",
+    "ToolExecutionError",
+    "ToolNotFoundError",
+    "ToolRegistry",
+    "ToolResult",
+    "ToolSpec",
+    "load_servers",
+]
+
+# 符号 → (模块, 模块内属性名)；模块内属性名缺省与符号同名
+_EXPORTS: dict[str, tuple[str, str]] = {
+    "Agent": ("kit.ai.agent.loop", "Agent"),
+    "AgentResult": ("kit.ai.agent.types", "AgentResult"),
+    "ToolSpec": ("kit.ai.agent.types", "ToolSpec"),
+    "ToolResult": ("kit.ai.agent.types", "ToolResult"),
+    "ToolCallRecord": ("kit.ai.agent.types", "ToolCallRecord"),
+    "McpServerConfig": ("kit.ai.agent.types", "McpServerConfig"),
+    "load_servers": ("kit.ai.agent.types", "load_servers"),
+    "ToolRegistry": ("kit.ai.agent.registry", "ToolRegistry"),
+    "Session": ("kit.ai.agent.session", "Session"),
+    "ApprovalHook": ("kit.ai.agent.approval", "ApprovalHook"),
+    "ApprovalRequest": ("kit.ai.agent.approval", "ApprovalRequest"),
+    "DefaultApproval": ("kit.ai.agent.approval", "DefaultApproval"),
+    "DenyAllApproval": ("kit.ai.agent.approval", "DenyAllApproval"),
+    "SkillPackage": ("kit.ai.agent.skill", "SkillPackage"),
+    "SkillScript": ("kit.ai.agent.skill", "SkillScript"),
+    "SkillRegistry": ("kit.ai.agent.skill", "SkillRegistry"),
+    "McpConnection": ("kit.ai.agent.mcp", "McpConnection"),
+    "AgentError": ("kit.ai.agent.errors", "AgentError"),
+    "AgentConfigError": ("kit.ai.agent.errors", "AgentConfigError"),
+    "AgentModelError": ("kit.ai.agent.errors", "AgentModelError"),
+    "AgentTimeoutError": ("kit.ai.agent.errors", "AgentTimeoutError"),
+    "AgentEmptyReplyError": ("kit.ai.agent.errors", "AgentEmptyReplyError"),
+    "AgentTruncatedError": ("kit.ai.agent.errors", "AgentTruncatedError"),
+    "MaxTurnsExceeded": ("kit.ai.agent.errors", "MaxTurnsExceeded"),
+    "ApprovalDeniedError": ("kit.ai.agent.errors", "ApprovalDeniedError"),
+    "ToolNotFoundError": ("kit.ai.agent.errors", "ToolNotFoundError"),
+    "ToolExecutionError": ("kit.ai.agent.errors", "ToolExecutionError"),
+    "McpConnectionError": ("kit.ai.agent.errors", "McpConnectionError"),
+    "SkillError": ("kit.ai.agent.errors", "SkillError"),
+    "SkillValidationError": ("kit.ai.agent.errors", "SkillValidationError"),
+    "SkillNotFoundError": ("kit.ai.agent.errors", "SkillNotFoundError"),
+    "DuplicateSkillError": ("kit.ai.agent.errors", "DuplicateSkillError"),
+}
+
+# 需要 fastmcp 的符号：在导入前显式守卫，报错必须指向 [agent]
+_GUARDED = frozenset({"Agent", "McpConnection"})
+
+
+def _require_fastmcp(name: str) -> None:
+    if util.find_spec("fastmcp") is not None:
+        return
+    raise ImportError(
+        f"kit.ai.agent.{name} 需要可选依赖，请安装：pip install sdpy-kit[agent]"
+    )
+
+
+def __getattr__(name: str) -> Any:
+    target = _EXPORTS.get(name)
+    if target is None:
+        raise AttributeError(f"module 'kit.ai.agent' has no attribute {name!r}")
+    if name in _GUARDED:
+        _require_fastmcp(name)
+    module, attribute = target
+    value = getattr(import_module(module), attribute)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

sdpy_kit-0.8.1/kit/ai/agent/approval.py

@@ -0,0 +1,66 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+# date: 2026-11-10
+"""工具调用审批 Hook。
+
+默认策略：MCP 工具放行（用户显式配置 server 才引入，信任边界在配置层）；
+skill 脚本拒绝（``subprocess`` 执行任意代码，v1 不开放该工具）。
+"""
+
+from dataclasses import dataclass
+from typing import Any, Literal, Protocol
+
+__all__ = [
+    "ApprovalHook",
+    "ApprovalRequest",
+    "DefaultApproval",
+    "DenyAllApproval",
+]
+
+
+@dataclass(frozen=True)
+class ApprovalRequest:
+    """一次待审批的工具调用。"""
+
+    kind: Literal["mcp_tool", "skill_script"]
+    target: str
+    arguments: dict[str, Any]
+
+
+class ApprovalHook(Protocol):
+    """审批 Hook：返回 True 放行，False 拒绝。"""
+
+    async def __call__(self, request: ApprovalRequest) -> bool:
+        """判断是否放行。"""
+        ...
+
+
+class DefaultApproval:
+    """默认审批：MCP 工具放行，skill 脚本拒绝。"""
+
+    async def __call__(self, request: ApprovalRequest) -> bool:
+        return request.kind == "mcp_tool"
+
+
+class DenyAllApproval:
+    """全部拒绝（最严格策略）。"""
+
+    async def __call__(self, request: ApprovalRequest) -> bool:
+        return False