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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.8.1
+Version: 0.8.2
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -96,6 +96,8 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 
 > 要求 Python 3.13+
 
+> **版本提示**：`0.8.0` 存在空 `ToolRegistry` / 空 `Session` 被真值判断替换的缺陷，请使用 `0.8.1+`（当前推荐 `0.8.2`）。
+
 ## 模块与方法入口
 
 | 模块 | 类 / 入口 | 能力 | 需要 extra |
@@ -184,9 +186,11 @@ asyncio.run(main())
 ```
 
 - 模型档案沿用 `kit.ai`（`config/ai_models.json`），首轮可 failover，成功后锁定档案；
+- 档案可在 `ai_models.json` 写 `supports_tools: true/false` 声明 function calling 能力；缺省时运行时检测 400 并自动换候选；
 - Skill 只读工具：`read_skill` / `list_skill_files` / `read_skill_file`（路径越界拒绝）；
 - MCP 工具默认放行，skill 脚本默认拒绝；可用 `DenyAllApproval` 整体收紧；
-- `timeout` / `max_turns` / `tool_timeout` 控制总预算与轮次；
+- stdio 默认 `keep_alive=False`，`Agent` 退出即断开并终止直接子进程；
+- `timeout` / `max_turns` / `tool_timeout` / `approval_timeout` 控制总预算、轮次与审批等待；
 - 完整说明见 `docs/agents/modules/agent-kit.md`（仓库内）。
 
 ## 配置（.env）

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

@@ -8,6 +8,8 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 
 > 要求 Python 3.13+
 
+> **版本提示**：`0.8.0` 存在空 `ToolRegistry` / 空 `Session` 被真值判断替换的缺陷，请使用 `0.8.1+`（当前推荐 `0.8.2`）。
+
 ## 模块与方法入口
 
 | 模块 | 类 / 入口 | 能力 | 需要 extra |
@@ -96,9 +98,11 @@ asyncio.run(main())
 ```
 
 - 模型档案沿用 `kit.ai`（`config/ai_models.json`），首轮可 failover，成功后锁定档案；
+- 档案可在 `ai_models.json` 写 `supports_tools: true/false` 声明 function calling 能力；缺省时运行时检测 400 并自动换候选；
 - Skill 只读工具：`read_skill` / `list_skill_files` / `read_skill_file`（路径越界拒绝）；
 - MCP 工具默认放行，skill 脚本默认拒绝；可用 `DenyAllApproval` 整体收紧；
-- `timeout` / `max_turns` / `tool_timeout` 控制总预算与轮次；
+- stdio 默认 `keep_alive=False`，`Agent` 退出即断开并终止直接子进程；
+- `timeout` / `max_turns` / `tool_timeout` / `approval_timeout` 控制总预算、轮次与审批等待；
 - 完整说明见 `docs/agents/modules/agent-kit.md`（仓库内）。
 
 ## 配置（.env）

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

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

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

@@ -69,6 +69,34 @@ _EMBED_CONCURRENCY = 4
 # 不改变超时时长语义（推理帧被吞掉，不轮询就看不到思考阶段的活动）
 _FIRST_FRAME_POLL: Final[float] = 1.0
 
+# 运行时判定「档案不支持 function calling」的关键词（仅 400 时匹配）：
+# 必须同时命中「工具词」+「不支持/未识别词」，避免把参数错误误判为能力缺失
+_TOOL_ERROR_TERMS: Final[tuple[str, ...]] = ("tool", "function")
+_UNSUPPORTED_TERMS: Final[tuple[str, ...]] = (
+    "not supported",
+    "unsupported",
+    "not support",
+    "does not support",
+    "not enabled",
+    "unrecognized",
+    "unknown parameter",
+    "unknown field",
+)
+
+
+def _looks_like_tools_unsupported(exc: AIError) -> bool:
+    """判断 400 错误是否由 tools / function calling 不被支持引起。
+
+    仅匹配「工具词 + 不支持词」组合，未知错误一律不标记，避免把参数错误
+    误判为能力缺失。
+    """
+    if not isinstance(exc, AIRequestError) or exc.status_code != 400:
+        return False
+    message = str(exc).lower()
+    has_tool = any(term in message for term in _TOOL_ERROR_TERMS)
+    has_unsupported = any(term in message for term in _UNSUPPORTED_TERMS)
+    return has_tool and has_unsupported
+
 
 class _FailoverBase:
     """链式调用基类：候选迭代 + 失败冷却 + 整链预算 + 聚合异常。"""
@@ -133,6 +161,7 @@ class _FailoverBase:
         run: Callable[[Service], Awaitable[T]],
         *,
         deadline: float | None = None,
+        require_tools: bool = False,
     ) -> T:
         """按候选顺序执行 ``run``；单档案失败冷却后换下一个，全失败聚合抛出。
 
@@ -140,11 +169,15 @@ class _FailoverBase:
             deadline: 整链预算截止时刻（``time.monotonic()`` 秒）；每个候选
                 发起前检查，预算耗尽则不再发起新候选，改抛携带「预算耗尽」
                 语义的聚合异常（避免门面从外部 cancel 使备胎白等）
+            require_tools: True 时跳过声明/运行时判定不支持 function calling
+                的档案（工具循环专用）
         """
         tried: list[str] = []
         errors: list[AIError] = []
         budget_exhausted = False
-        for name, service in self._pool.iter_services(self._model_type):
+        for name, service in self._pool.iter_services(
+            self._model_type, require_tools=require_tools
+        ):
             if self._budget_exhausted(deadline):
                 budget_exhausted = True
                 break
@@ -231,18 +264,30 @@ class FailoverChatService(_FailoverBase):
         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,
-            )
+            try:
+                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,
+                )
+            except AIRequestError as exc:
+                if _looks_like_tools_unsupported(exc):
+                    profile = getattr(service, "profile", None)
+                    name = getattr(profile, "name", None)
+                    if isinstance(name, str):
+                        self._pool.mark_tool_unsupported(
+                            self._model_type, name, exc
+                        )
+                raise
 
-        return await self._attempt("工具对话", _run, deadline=deadline)
+        return await self._attempt(
+            "工具对话", _run, deadline=deadline, require_tools=True
+        )
 
     async def create_once(
         self,

{sdpy_kit-0.8.1 → sdpy_kit-0.8.2}/kit/ai/_internal/pool.py

@@ -116,6 +116,7 @@ class _Entry:
         "last_error",
         "last_ok_at",
         "service",
+        "tool_unsupported",
     )
 
     def __init__(self, profile: ModelProfile) -> None:
@@ -126,6 +127,8 @@ class _Entry:
         self.last_error: str | None = None
         self.last_ok_at: float | None = None
         self.service: Service | None = None
+        # function calling 能力：声明 False 或运行时 400 判定后为 True
+        self.tool_unsupported: bool = profile.supports_tools is False
 
 
 @dataclass
@@ -264,9 +267,15 @@ class AIServicePool:
 
     # ---------- 候选迭代 ----------
 
-    def iter_services(self, model_type: str) -> Iterator[tuple[str, Service]]:
+    def iter_services(
+        self, model_type: str, *, require_tools: bool = False
+    ) -> Iterator[tuple[str, Service]]:
         """按竞选顺序迭代（档案名, service）：prefer 项打头，跳过冷却档案。
 
+        Args:
+            require_tools: True 时额外跳过声明/运行时判定不支持 function calling
+                的档案（Agent 工具循环专用）；普通对话不受影响。
+
         候选计划（顺序 + prefer 提前 + 冷却到期复位 + 可用性过滤）在生成器
         首次推进时一次定格：此后 ``prefer()`` 切换与其它请求的失败冷却均
         不影响已开始迭代的调用方——切换只为「下一次」请求生效。
@@ -284,6 +293,8 @@ class AIServicePool:
             plan: list[tuple[str, Service | None]] = []
             for name in seq:
                 entry = chain.entries[name]
+                if require_tools and entry.tool_unsupported:
+                    continue
                 if entry.state is ProfileState.COOLING and now >= entry.cooling_until:
                     entry.state = ProfileState.AVAILABLE
                     entry.last_error = None
@@ -341,6 +352,24 @@ class AIServicePool:
             entry.last_ok_at = time.time()
             entry.last_error = None
 
+    def mark_tool_unsupported(
+        self, model_type: str, name: str, exc: BaseException
+    ) -> None:
+        """运行时判定档案不支持 function calling：后续工具调用跳过该档案。
+
+        只影响 ``require_tools=True`` 的候选迭代；普通对话仍可使用该档案。
+        """
+        with self._lock:
+            chain = self._chains.get(model_type)
+            entry = chain.entries.get(name) if chain else None
+            if entry is None:
+                return
+            entry.tool_unsupported = True
+        logger.warning(
+            f"{model_type}.{name} 判定不支持 function calling，"
+            f"后续工具调用将跳过: {exc}"
+        )
+
     # ---------- 当前项与状态 ----------
 
     def prefer(self, model_type: str, profile: str) -> None:
@@ -406,6 +435,11 @@ class AIServicePool:
                     last_ok_at=entry.last_ok_at,
                     thinking_switchable=entry.profile.thinking is not None,
                     json_mode_supported=entry.profile.structured_output is not None,
+                    tools_supported=(
+                        False
+                        if entry.tool_unsupported
+                        else entry.profile.supports_tools
+                    ),
                 )
                 for name, entry in chain.entries.items()
             ]
@@ -426,6 +460,9 @@ class AIServicePool:
                             model_type == "chat"
                             and config.structured_output is not False
                         ),
+                        tools_supported=(
+                            config.supports_tools if model_type == "chat" else None
+                        ),
                     )
                 )
         return rows

{sdpy_kit-0.8.1 → sdpy_kit-0.8.2}/kit/ai/agent/errors.py

@@ -20,6 +20,8 @@ Author: Clark Chang
 # date: 2026-11-10
 """kit.ai.agent 异常体系（统一继承 AgentError）。"""
 
+from typing import Any
+
 __all__ = [
     "AgentConfigError",
     "AgentEmptyReplyError",
@@ -79,11 +81,18 @@ class MaxTurnsExceeded(AgentError):
     Attributes:
         max_turns: 允许的最大轮次。
         turns: 实际执行轮次。
+        tool_calls: 已完成执行的工具调用记录（可选，便于调用方决定是否续跑）。
     """
 
-    def __init__(self, max_turns: int, turns: int | None = None) -> None:
+    def __init__(
+        self,
+        max_turns: int,
+        turns: int | None = None,
+        tool_calls: list[Any] | None = None,
+    ) -> None:
         self.max_turns: int = max_turns
         self.turns: int = turns if turns is not None else max_turns
+        self.tool_calls: list[Any] = list(tool_calls or [])
         super().__init__(f"工具循环超过 {max_turns} 轮仍未结束")
 
 

{sdpy_kit-0.8.1 → sdpy_kit-0.8.2}/kit/ai/agent/loop.py

@@ -105,6 +105,7 @@ class Agent:
         session: Session | None = None,
         system_prompt: str | None = None,
         approval: ApprovalHook | None = None,
+        approval_timeout: float = 30.0,
         max_turns: int = 8,
         timeout: float = 120.0,
         tool_timeout: float = 30.0,
@@ -119,6 +120,8 @@ class Agent:
             raise ValueError("timeout 必须 > 0")
         if tool_timeout <= 0:
             raise ValueError("tool_timeout 必须 > 0")
+        if approval_timeout <= 0:
+            raise ValueError("approval_timeout 必须 > 0")
         if max_tool_result_chars < 1:
             raise ValueError("max_tool_result_chars 必须 >= 1")
         self._tools: ToolRegistry = tools if tools is not None else ToolRegistry()
@@ -128,6 +131,7 @@ class Agent:
         self._approval: ApprovalHook = (
             approval if approval is not None else DefaultApproval()
         )
+        self._approval_timeout: float = approval_timeout
         self._max_turns: int = max_turns
         self._timeout: float = timeout
         self._tool_timeout: float = tool_timeout
@@ -310,7 +314,7 @@ class Agent:
 
             if turn >= self._max_turns:
                 # 最后一轮不再执行工具：没有余量回灌结果，避免无意义副作用
-                raise MaxTurnsExceeded(self._max_turns, turn)
+                raise MaxTurnsExceeded(self._max_turns, turn, records)
             self._append_assistant(prepared, sink, reply)
             for call in reply.tool_calls:
                 try:
@@ -331,7 +335,7 @@ class Agent:
                 if sink is not None:
                     sink.add_tool(call["id"], record.result.content)
 
-        raise MaxTurnsExceeded(self._max_turns, turns)
+        raise MaxTurnsExceeded(self._max_turns, turns, records)
 
     async def run_once(
         self,
@@ -384,6 +388,7 @@ class Agent:
             session=self._session,
             system_prompt=self._system_prompt,
             approval=self._approval,
+            approval_timeout=self._approval_timeout,
             max_turns=self._max_turns,
             timeout=self._timeout,
             tool_timeout=self._tool_timeout,
@@ -592,7 +597,14 @@ class Agent:
                 target=entry.approval_target or name,
                 arguments=arguments,
             )
-            if not await self._approval(request):
+            try:
+                async with asyncio.timeout(self._approval_timeout):
+                    approved = await self._approval(request)
+            except TimeoutError as exc:
+                raise ApprovalDeniedError(
+                    f"审批超时（{self._approval_timeout:g}s）: {request.target}"
+                ) from exc
+            if not approved:
                 raise ApprovalDeniedError(f"审批拒绝: {request.target}")
 
         remaining = deadline - time.monotonic()

{sdpy_kit-0.8.1 → sdpy_kit-0.8.2}/kit/ai/agent/mcp.py

@@ -146,6 +146,7 @@ class McpConnection:
                 args=list(config.args),
                 env=config.env,
                 cwd=config.cwd,
+                keep_alive=config.keep_alive,
             )
         return Client(
             transport,
@@ -195,7 +196,10 @@ class McpConnection:
             try:
                 await stack.aclose()
             except Exception as exc:  # noqa: BLE001 - 关闭阶段失败不影响退出
-                logger.warning(f"MCP server {self._config.name!r} 关闭失败: {exc}")
+                logger.warning(
+                    f"MCP server {self._config.name!r} 关闭失败: "
+                    f"{type(exc).__name__}: {exc}"
+                )
 
     async def __aenter__(self) -> "McpConnection":
         await self.open()
@@ -261,6 +265,12 @@ class McpConnection:
                 is_error=True,
             )
         except Exception as exc:  # noqa: BLE001 - 协议异常统一转为工具错误
+            message = str(exc).lower()
+            if "timed out" in message:
+                return ToolResult(
+                    content=f"[timeout after {self._config.call_timeout:g}s]",
+                    is_error=True,
+                )
             raise ToolExecutionError(
                 f"MCP 工具 {self._config.name}.{raw_name} 调用失败: "
                 f"{type(exc).__name__}: {exc}"

{sdpy_kit-0.8.1 → sdpy_kit-0.8.2}/kit/ai/agent/registry.py

@@ -123,8 +123,12 @@ class ToolRegistry:
             ValueError: 名称重复且未指定 ``replace=True``。
         """
         name = sanitize_tool_name(spec.name)
-        if name in self._tools and not replace:
-            raise ValueError(f"工具名重复: {name}")
+        existing = self._tools.get(name)
+        if existing is not None and not replace:
+            raise ValueError(
+                f"工具名重复: {name}"
+                f"（已有来源 {existing.kind}，本次来源 {kind}）"
+            )
         schema = clean_schema(spec.input_schema)
         if schema is None:
             logger.warning(

{sdpy_kit-0.8.1 → sdpy_kit-0.8.2}/kit/ai/agent/skill.py

@@ -114,11 +114,14 @@ class SkillRegistry:
                 if not skill_file.is_file():
                     continue
                 package = _parse_package(child, skill_file)
-                if package.name in self._packages:
+                existing = self._packages.get(package.name)
+                if existing is not None:
+                    if existing.root.resolve() == package.root.resolve():
+                        # 同一目录重复 load：幂等跳过，便于配置热重载
+                        continue
                     raise DuplicateSkillError(
                         f"技能重名: {package.name}"
-                        f"（已加载 {self._packages[package.name].root}，"
-                        f"本次 {package.root}）"
+                        f"（已加载 {existing.root}，本次 {package.root}）"
                     )
                 self._packages[package.name] = package
                 added += 1

{sdpy_kit-0.8.1 → sdpy_kit-0.8.2}/kit/ai/agent/types.py

@@ -98,6 +98,9 @@ class McpServerConfig:
     call_timeout: float = 60.0
     tool_prefix: bool = True
     optional: bool = False
+    # stdio 子进程是否跨连接保活。默认 False：close() 即断开并终止直接子进程；
+    # 设为 True 可复用子进程，但 Agent 退出后可能残留，需调用方自行管理。
+    keep_alive: bool = False
 
     def __post_init__(self) -> None:
         if not self.name or not self.name.strip():
@@ -131,6 +134,7 @@ class McpServerConfig:
             "call_timeout",
             "tool_prefix",
             "optional",
+            "keep_alive",
         }
         unknown = sorted(set(data) - allowed)
         if unknown:

{sdpy_kit-0.8.1 → sdpy_kit-0.8.2}/kit/ai/chat_service.py

@@ -30,7 +30,7 @@ from typing import Any, ClassVar, Final, Protocol, cast
 
 from kit.ai._internal.sdk_client import SdkServiceBase
 from kit.ai._internal.types import JSONObject
-from kit.ai.exceptions import AIError, AIResponseError
+from kit.ai.exceptions import AIConfigError, AIError, AIResponseError
 from kit.ai.messages import ChatReply, Message
 from kit.ai.profiles import (
     _RESERVED_PAYLOAD_KEYS,
@@ -535,6 +535,11 @@ class ChatService(SdkServiceBase):
             stats: 收尾统计累加器
             deadline: 整链预算截止时刻（``time.monotonic()`` 秒）
         """
+        if self._profile.supports_tools is False:
+            raise AIConfigError(
+                f"档案 {self._profile.name} 声明不支持 tools"
+                "（supports_tools=false），请改用支持 function calling 的档案"
+            )
         request = ChatRequest(
             messages,
             temperature=temperature,

{sdpy_kit-0.8.1 → sdpy_kit-0.8.2}/kit/ai/profiles.py

@@ -134,6 +134,8 @@ class ModelProfile:
             None 表示该档案不支持按调用切换思考
         structured_output: 结构化输出的注入声明（逐调用 ``json_mode=`` 据此翻译）；
             未声明时取内置协议默认，``None`` 表示档案显式声明不支持
+        supports_tools: 是否支持 OpenAI function calling；None 表示未声明
+            （按 0.8.1 行为直接尝试），False 表示明确不支持（工具循环跳过该档案）
     """
 
     name: str
@@ -151,6 +153,7 @@ class ModelProfile:
     extra_body: dict[str, Any] | None = None
     thinking: ThinkingSwitchSpec | None = None
     structured_output: StructuredOutputSpec | None = None
+    supports_tools: bool | None = None
 
 
 class ProfileState(enum.Enum):
@@ -178,6 +181,8 @@ class ProfileStatus:
         thinking_switchable: 该档案是否声明了思考开关（可逐调用关/开思考）
         json_mode_supported: 该档案是否支持结构化输出（仅显式 ``false`` 为 False；
             未声明按内置协议默认，视为支持）
+        tools_supported: 是否支持 function calling；None=未声明/未探测，
+            False=声明或运行时判定不支持
     """
 
     name: str
@@ -188,6 +193,7 @@ class ProfileStatus:
     last_ok_at: float | None = None
     thinking_switchable: bool = False
     json_mode_supported: bool = False
+    tools_supported: bool | None = None
 
 
 class ThinkingSwitchSpecModel(BaseModel):
@@ -303,6 +309,9 @@ class ProfileConfig(BaseModel):
     thinking: ThinkingSwitchSpecModel | None = None
     # 结构化输出注入声明：False = 该档案显式不支持；缺省 = 用内置协议默认
     structured_output: StructuredOutputSpecModel | Literal[False] | None = None
+    # function calling 能力声明：False = 明确不支持（工具循环跳过）；
+    # 缺省 None = 未声明，按 0.8.1 行为直接尝试，由运行时 400 兜底
+    supports_tools: bool | None = None
 
 
 class TypeConfig(BaseModel):
@@ -466,6 +475,8 @@ class ModelRegistry:
                 if model_type == "chat"
                 else None
             ),
+            # 工具能力仅对 chat 有意义；其余类型不参与 Agent
+            supports_tools=config.supports_tools if model_type == "chat" else None,
         )
 
     def get_profile(self, model_type: str, profile: str | None = None) -> ProfileConfig: