fix(tool, toolset): 兼容 additionalProperties schema 解析

- 将 additional_properties 字段类型从 bool 扩展为 Union[bool, ToolSchema]
- 递归解析 schema-valued additionalProperties，序列化时保留为对象
- 修正 from_any_openapi_schema 入口条件：if not schema → if schema is None，
  使空 dict {} 作为合法 JSON Schema（any）正确解析，而非降级为 string
- 将嵌套三元表达式重构为 if/elif/else 提升可读性
- 添加 OpenAPI、MCP tool schema 及空 schema 的回归测试

Change-Id: I1e14f80b169adbb7693f0ee668ed6462e2a4803c
Co-developed-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: OhYee

agentrun/tool/model.py

@@ -5,7 +5,7 @@
 """
 
 from enum import Enum
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
 from agentrun.utils.model import BaseModel
 
@@ -194,8 +194,8 @@ class ToolSchema(BaseModel):
     required: Optional[List[str]] = None
     """必填字段 / Required fields"""
 
-    additional_properties: Optional[bool] = None
-    """是否允许额外属性 / Whether additional properties are allowed"""
+    additional_properties: Optional[Union[bool, "ToolSchema"]] = None
+    """额外属性约束 / Additional properties constraint"""
 
     items: Optional["ToolSchema"] = None
     """数组元素类型 / Array item type"""
@@ -252,7 +252,7 @@ def from_any_openapi_schema(cls, schema: Any) -> "ToolSchema":
         递归解析所有嵌套结构，保留完整的 schema 信息。
         Recursively parses all nested structures, preserving complete schema information.
         """
-        if not schema or not isinstance(schema, dict):
+        if schema is None or not isinstance(schema, dict):
             return cls(type="string")
 
         from pydash import get as pydash_get
@@ -291,13 +291,21 @@ def from_any_openapi_schema(cls, schema: Any) -> "ToolSchema":
             else None
         )
 
+        additional_properties_raw = pydash_get(schema, "additionalProperties")
+        if isinstance(additional_properties_raw, dict):
+            additional_properties = cls.from_any_openapi_schema(
+                additional_properties_raw
+            )
+        else:
+            additional_properties = additional_properties_raw
+
         return cls(
             type=pydash_get(schema, "type"),
             description=pydash_get(schema, "description"),
             title=pydash_get(schema, "title"),
             properties=properties,
             required=pydash_get(schema, "required"),
-            additional_properties=pydash_get(schema, "additionalProperties"),
+            additional_properties=additional_properties,
             items=items,
             min_items=pydash_get(schema, "minItems"),
             max_items=pydash_get(schema, "maxItems"),
@@ -334,7 +342,11 @@ def to_json_schema(self) -> Dict[str, Any]:
         if self.required:
             result["required"] = self.required
         if self.additional_properties is not None:
-            result["additionalProperties"] = self.additional_properties
+            result["additionalProperties"] = (
+                self.additional_properties.to_json_schema()
+                if isinstance(self.additional_properties, ToolSchema)
+                else self.additional_properties
+            )
 
         if self.items:
             result["items"] = self.items.to_json_schema()

agentrun/toolset/model.py

@@ -5,7 +5,7 @@
 """
 
 from enum import Enum
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
 from agentrun.utils.model import BaseModel, Field, PageableInput
 
@@ -103,7 +103,7 @@ class ToolSchema(BaseModel):
     # 对象类型字段
     properties: Optional[Dict[str, "ToolSchema"]] = None
     required: Optional[List[str]] = None
-    additional_properties: Optional[bool] = None
+    additional_properties: Optional[Union[bool, "ToolSchema"]] = None
 
     # 数组类型字段
     items: Optional["ToolSchema"] = None
@@ -137,7 +137,7 @@ def from_any_openapi_schema(cls, schema: Any) -> "ToolSchema":
 
         递归解析所有嵌套结构，保留完整的 schema 信息。
         """
-        if not schema or not isinstance(schema, dict):
+        if schema is None or not isinstance(schema, dict):
             return cls(type="string")
 
         from pydash import get as pg
@@ -179,6 +179,14 @@ def from_any_openapi_schema(cls, schema: Any) -> "ToolSchema":
             else None
         )
 
+        additional_properties_raw = pg(schema, "additionalProperties")
+        if isinstance(additional_properties_raw, dict):
+            additional_properties = cls.from_any_openapi_schema(
+                additional_properties_raw
+            )
+        else:
+            additional_properties = additional_properties_raw
+
         return cls(
             # 基本字段
             type=pg(schema, "type"),
@@ -187,7 +195,7 @@ def from_any_openapi_schema(cls, schema: Any) -> "ToolSchema":
             # 对象类型
             properties=properties,
             required=pg(schema, "required"),
-            additional_properties=pg(schema, "additionalProperties"),
+            additional_properties=additional_properties,
             # 数组类型
             items=items,
             min_items=pg(schema, "minItems"),
@@ -231,7 +239,11 @@ def to_json_schema(self) -> Dict[str, Any]:
         if self.required:
             result["required"] = self.required
         if self.additional_properties is not None:
-            result["additionalProperties"] = self.additional_properties
+            result["additionalProperties"] = (
+                self.additional_properties.to_json_schema()
+                if isinstance(self.additional_properties, ToolSchema)
+                else self.additional_properties
+            )
 
         # 数组类型
         if self.items:

tests/unittests/tool/test_model.py

@@ -265,10 +265,9 @@ def test_from_any_openapi_schema_empty(self):
         schema = ToolSchema.from_any_openapi_schema(None)
         assert schema.type == "string"
 
-        # Empty dict creates a ToolSchema with None type (pydash_get returns None for missing keys)
+        # Empty dict is a valid JSON Schema meaning "any" — should not collapse to "string"
         schema = ToolSchema.from_any_openapi_schema({})
-        # Actually returns "string" due to the check at the beginning of the method
-        assert schema.type == "string"
+        assert schema.type is None
 
     def test_from_any_openapi_schema_non_dict(self):
         """测试从非 dict 输入创建"""
@@ -335,6 +334,72 @@ def test_from_any_openapi_schema_allof(self):
         assert schema.all_of[0].type == "object"
         assert schema.all_of[1].type == "object"
 
+    def test_from_any_openapi_schema_additional_properties_schema(self):
+        """测试 additionalProperties 为 schema 对象时的解析"""
+        openapi_schema = {
+            "type": "object",
+            "properties": {
+                "filters": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "anyOf": [
+                            {"type": "string"},
+                            {"type": "integer"},
+                        ]
+                    },
+                }
+            },
+        }
+
+        schema = ToolSchema.from_any_openapi_schema(openapi_schema)
+
+        assert schema.properties is not None
+        assert "filters" in schema.properties
+        filters_schema = schema.properties["filters"]
+        assert filters_schema.additional_properties is not None
+        assert filters_schema.additional_properties.any_of is not None
+        assert len(filters_schema.additional_properties.any_of) == 2
+        assert filters_schema.additional_properties.any_of[0].type == "string"
+        assert filters_schema.additional_properties.any_of[1].type == "integer"
+
+        json_schema = schema.to_json_schema()
+        assert (
+            json_schema["properties"]["filters"]["additionalProperties"][
+                "anyOf"
+            ][0]["type"]
+            == "string"
+        )
+        assert (
+            json_schema["properties"]["filters"]["additionalProperties"][
+                "anyOf"
+            ][1]["type"]
+            == "integer"
+        )
+
+    def test_from_any_openapi_schema_empty_additional_properties_schema(self):
+        """测试 additionalProperties 为空 schema 时保留原语义"""
+        openapi_schema = {
+            "type": "object",
+            "properties": {
+                "metadata": {
+                    "type": "object",
+                    "additionalProperties": {},
+                }
+            },
+        }
+
+        schema = ToolSchema.from_any_openapi_schema(openapi_schema)
+
+        assert schema.properties is not None
+        metadata_schema = schema.properties["metadata"]
+        assert metadata_schema.additional_properties is not None
+        assert metadata_schema.additional_properties.type is None
+
+        json_schema = schema.to_json_schema()
+        assert (
+            json_schema["properties"]["metadata"]["additionalProperties"] == {}
+        )
+
     def test_to_json_schema_simple(self):
         """测试转换为 JSON Schema - 简单情况"""
         schema = ToolSchema(
@@ -659,3 +724,38 @@ def model_dump(self):
         assert "param1" in info.parameters.properties
         assert "param2" in info.parameters.properties
         assert info.parameters.required == ["param1"]
+
+    def test_from_mcp_tool_with_schema_additional_properties(self):
+        """测试 MCP tool schema 中 additionalProperties 为对象时的解析"""
+        mcp_tool = {
+            "name": "get_news_by_date",
+            "description": "A tool with MCP schema-style date_range",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "date_range": {
+                        "anyOf": [
+                            {"type": "string"},
+                            {
+                                "type": "object",
+                                "additionalProperties": {"type": "string"},
+                            },
+                            {"type": "null"},
+                        ]
+                    }
+                },
+            },
+        }
+
+        info = ToolInfo.from_mcp_tool(mcp_tool)
+
+        assert info.name == "get_news_by_date"
+        assert info.parameters is not None
+        assert info.parameters.properties is not None
+        date_range_schema = info.parameters.properties["date_range"]
+        assert date_range_schema.any_of is not None
+        assert date_range_schema.any_of[1].type == "object"
+        assert date_range_schema.any_of[1].additional_properties is not None
+        assert (
+            date_range_schema.any_of[1].additional_properties.type == "string"
+        )

tests/unittests/toolset/test_model.py

@@ -419,10 +419,9 @@ def test_from_any_openapi_schema_none(self):
         assert schema.type == "string"
 
     def test_from_any_openapi_schema_empty_dict(self):
-        """测试从空字典创建"""
+        """测试从空字典创建 — 空 dict 是合法的 JSON Schema，表示 'any'"""
         schema = ToolSchema.from_any_openapi_schema({})
-        # 空字典被视为 falsy，所以返回默认的 string 类型
-        assert schema.type == "string"
+        assert schema.type is None
 
     def test_from_any_openapi_schema_non_dict(self):
         """测试从非字典 schema 创建"""
@@ -448,6 +447,69 @@ def test_from_any_openapi_schema_with_properties(self):
         assert schema.required == ["name"]
         assert schema.additional_properties is False
 
+    def test_from_any_openapi_schema_with_schema_additional_properties(self):
+        """测试 additionalProperties 为 schema 对象时的解析"""
+        openapi_schema = {
+            "type": "object",
+            "properties": {
+                "filters": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "anyOf": [
+                            {"type": "string"},
+                            {"type": "integer"},
+                        ]
+                    },
+                }
+            },
+        }
+
+        schema = ToolSchema.from_any_openapi_schema(openapi_schema)
+
+        assert schema.properties is not None
+        filters_schema = schema.properties["filters"]
+        assert filters_schema.additional_properties is not None
+        assert filters_schema.additional_properties.any_of is not None
+        assert len(filters_schema.additional_properties.any_of) == 2
+
+        json_schema = schema.to_json_schema()
+        assert (
+            json_schema["properties"]["filters"]["additionalProperties"][
+                "anyOf"
+            ][0]["type"]
+            == "string"
+        )
+        assert (
+            json_schema["properties"]["filters"]["additionalProperties"][
+                "anyOf"
+            ][1]["type"]
+            == "integer"
+        )
+
+    def test_from_any_openapi_schema_with_empty_additional_properties(self):
+        """测试 additionalProperties 为空 schema 时保留原语义"""
+        openapi_schema = {
+            "type": "object",
+            "properties": {
+                "metadata": {
+                    "type": "object",
+                    "additionalProperties": {},
+                }
+            },
+        }
+
+        schema = ToolSchema.from_any_openapi_schema(openapi_schema)
+
+        assert schema.properties is not None
+        metadata_schema = schema.properties["metadata"]
+        assert metadata_schema.additional_properties is not None
+        assert metadata_schema.additional_properties.type is None
+
+        json_schema = schema.to_json_schema()
+        assert (
+            json_schema["properties"]["metadata"]["additionalProperties"] == {}
+        )
+
     def test_from_any_openapi_schema_with_items(self):
         """测试从带 items 的数组 schema 创建"""
         openapi_schema = {