[Feature]: @Tool 注解支持 additionalProperties 参数，实现严格参数校验

[WEIHUWEIHU]

问题背景

LLM 在调用工具时，有时会自行伪造（hallucinate）未定义的参数。由于当前框架对额外参数的处理规则是静默忽略，工具仍能正常返回结果，导致：

1. LLM 误以为伪造参数生效 — 工具正常返回了结果，LLM 没有收到任何错误反馈，便认为自己的传参（包括伪造的参数）都被正确处理了
2. LLM 对返回数据做出错误解读 — 例如 LLM 伪造了 "owners": ["admin"] 参数，工具返回了全量数据，LLM 误以为返回的是按 owner 过滤后的结果，从而对数据做出错误的判断和决策
3. 错误链持续传播 — 由于没有任何校验拦截，LLM 不会意识到参数有误，在整个推理链路中持续基于错误的假设进行后续操作

现状分析

目前框架中设置 additionalProperties 的途径存在以下问题：

1. 注解方式注册的工具没有设置入口

使用 @Tool 注解生成的 schema 中，没有任何地方可以设置 additionalProperties，生成的 schema 默认允许额外参数。

2. Schema 方式注册的工具天然支持

使用 SchemaOnlyTool 或直接实现 AgentTool 接口时，getParameters() 返回的 schema 由用户自行构建，天然可以包含 additionalProperties: false。

3. SkillBox.registration().extendedModel() 方式无法生效（疑似 Bug）

尝试通过 SimpleExtendedModel 添加 additionalProperties: false：

skillBox.registration()
    .tool(toolObject)
    .extendedModel(new SimpleExtendedModel(
        Map.of("additionalProperties", false), List.of()))
    .register();

但 ExtendedModel.mergeWithBaseSchema() 的实现会将 getAdditionalProperties() 返回的 Map 全部合并进 schema 的 properties 字段中（见 ExtendedModel.java 第 70-72 行），导致 additionalProperties 被错误地放进 properties 里，变成了一个名为 "additionalProperties" 的属性定义，而不是顶层的 additionalProperties: false。这是否是一个 Bug，请维护者确认。

期望行为

在 @Tool 注解上支持声明 additionalProperties，默认 false（不允许额外参数），与 JSON Schema 语义一致：

// 默认严格模式，拒绝额外参数
@Tool(name = "query_business_data")
public String queryData(@ToolParam(name = "reqVo") ReqVo reqVo) { ... }

// 显式允许额外参数（宽松模式）
@Tool(name = "query_business_data", additionalProperties = true)
public String queryData(@ToolParam(name = "reqVo") ReqVo reqVo) { ... }

当 LLM 传入未定义的参数时，ToolValidator 基于 additionalProperties: false 校验失败，返回错误信息，LLM 收到明确的校验错误反馈后可以自我纠正。

生成的 schema 应递归地为所有 type=object 节点注入 additionalProperties: false，包括嵌套对象的 properties、items、oneOf/anyOf/allOf、$defs 等。仅在顶层加不够，因为 LLM 伪造的参数往往出现在嵌套对象内部。

参考实现

以下是我们验证过的代码改动，供维护者参考：

1. Tool.java — 新增 additionalProperties 属性

Class<? extends ToolResultConverter> converter() default DefaultToolResultConverter.class;

/**
 * Whether to allow additional properties beyond those defined in the schema.
 *
 * <p>Corresponds to the {@code additionalProperties} keyword in JSON Schema.
 * When set to {@code false} (default), any extra parameters passed by the LLM
 * that are not defined in the schema will cause a validation error.
 * When set to {@code true}, extra parameters are silently ignored.
 *
 * <p>This setting is applied recursively to all nested objects within the schema.
 *
 * @return {@code false} to disallow additional properties (default), {@code true} to allow
 */
boolean additionalProperties() default false;

2. ToolSchemaGenerator.java — 新增重载方法 + 递归注入

Map<String, Object> generateParameterSchema(Method method, Set<String> excludeParams) {
    return generateParameterSchema(method, excludeParams, false);
}

@SuppressWarnings("unchecked")
Map<String, Object> generateParameterSchema(
        Method method, Set<String> excludeParams, boolean additionalProperties) {
    // ... 原有生成逻辑不变 ...

    if (!additionalProperties) {
        addAdditionalPropertiesFalseRecursively(schema);
    }

    return schema;
}

@SuppressWarnings("unchecked")
private void addAdditionalPropertiesFalseRecursively(Map<String, Object> schema) {
    if (!"object".equals(schema.get("type"))) {
        return;
    }
    schema.put("additionalProperties", false);

    Object propsObj = schema.get("properties");
    if (propsObj instanceof Map) {
        Map<String, Object> props = (Map<String, Object>) propsObj;
        for (Map.Entry<String, Object> entry : props.entrySet()) {
            if (entry.getValue() instanceof Map) {
                addAdditionalPropertiesFalseRecursively((Map<String, Object>) entry.getValue());
            }
        }
    }

    Object itemsObj = schema.get("items");
    if (itemsObj instanceof Map) {
        addAdditionalPropertiesFalseRecursively((Map<String, Object>) itemsObj);
    }

    for (String key : new String[]{"oneOf", "anyOf", "allOf"}) {
        Object listObj = schema.get(key);
        if (listObj instanceof Iterable) {
            for (Object item : (Iterable<?>) listObj) {
                if (item instanceof Map) {
                    addAdditionalPropertiesFalseRecursively((Map<String, Object>) item);
                }
            }
        }
    }

    Object defsObj = schema.get("$defs");
    if (defsObj instanceof Map) {
        Map<String, Object> defs = (Map<String, Object>) defsObj;
        for (Map.Entry<String, Object> entry : defs.entrySet()) {
            if (entry.getValue() instanceof Map) {
                addAdditionalPropertiesFalseRecursively((Map<String, Object>) entry.getValue());
            }
        }
    }

    Object definitionsObj = schema.get("definitions");
    if (definitionsObj instanceof Map) {
        Map<String, Object> definitions = (Map<String, Object>) definitionsObj;
        for (Map.Entry<String, Object> entry : definitions.entrySet()) {
            if (entry.getValue() instanceof Map) {
                addAdditionalPropertiesFalseRecursively((Map<String, Object>) entry.getValue());
            }
        }
    }
}

3. Toolkit.java — 读取注解值传给 generator

// registerToolMethod() 中 getParameters() 的实现
@Override
public Map<String, Object> getParameters() {
    Set<String> excludeParams =
            presetParameters != null
                    ? presetParameters.keySet()
                    : Collections.emptySet();
    return schemaGenerator.generateParameterSchema(
            method, excludeParams, toolAnnotation.additionalProperties());
}

影响范围

• 向后兼容：默认 false 即严格模式，这是更安全的默认行为。如果担心破坏现有用户，可以将默认值改为 true，让用户显式声明 additionalProperties = false 来启用严格模式
• 仅影响注解方式注册的工具：SchemaOnlyTool 和程序式注册的 AgentTool 不受影响

[itxaiohanglover]

你好，我在实际项目中也遇到了这个问题，LLM 伪造了未定义的查询参数，工具返回了全量数据，LLM 误以为是过滤后的结果，导致了错误的业务决策。希望能认领这个 issue，请问可以分配给我吗？

一共有三个子问题，我本地都做了复现确认：

问题 1：@tool 注解生成的 schema 没有 additionalProperties

Full schema: {type=object, properties={keyword={type=string, description=keyword}}, required=[keyword]}
Has 'additionalProperties' key? false

问题 2：ExtendedModel.mergeWithBaseSchema() 的 Bug 已确认

Merged schema: {type=object, properties={input={type=string}, additionalProperties=false}, required=[input]}
'additionalProperties' is IN properties map? true
'additionalProperties' is at top-level? false

additionalProperties 被错误地放进了 properties map 里，而不是顶层 schema key。不过这个 Bug 我计划作为单独的 PR 来修复，避免混合多个问题。

问题 3：LLM 伪造参数被静默接受

LLM input: {"keyword": "test", "owners": ["admin"]}
Validation result: null  (silently accepted!)

关于默认值

issue 建议默认 false（严格模式），但这会破坏向后兼容——现有用户的工具如果 LLM 传了额外参数，之前是静默忽略，改后会校验报错。建议默认值设为 true（保持当前宽松行为），用户显式设置 additionalProperties = false 来启用严格模式。

我的整体修复思路：

1. Tool.java — 新增 boolean additionalProperties() default true
2. ToolSchemaGenerator.java — 新增重载方法接收 additionalProperties 参数 + 递归注入所有嵌套 object
3. Toolkit.java — 在 registerToolMethod() 中读取注解值传给 generator

修复验证结果：

设置 additionalProperties = false 后，schema 正确生成为：

{additionalProperties=false, type=object, properties={keyword={type=string, description=keyword}}, required=[keyword]}

LLM 伪造参数被正确拒绝：

Validation result: 架构中未定义属性"owners"，并且架构不允许附加属性

默认行为完全不受影响（向后兼容）。

---

测试代码：

@DisplayName("Issue #1379 Fix Verification")
class Issue1379FixVerificationTest {

    @Test
    @DisplayName("Fix 1: additionalProperties=false should appear in schema")
    void testSchemaContainsAdditionalPropertiesWhenFalse() {
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(
                new Object() {
                    @Tool(
                            name = "query_data",
                            description = "Query business data",
                            additionalProperties = false)
                    public String queryData(
                            @ToolParam(name = "keyword", description = "keyword") String keyword) {
                        return "result";
                    }
                });

        Map<String, Object> schema = toolkit.getToolSchemas().get(0).getParameters();

        assertTrue(schema.containsKey("additionalProperties"));
        assertEquals(false, schema.get("additionalProperties"));

        Map<String, Object> properties = (Map<String, Object>) schema.get("properties");
        assertFalse(properties.containsKey("additionalProperties"),
                "additionalProperties should NOT be inside properties map");
    }

    @Test
    @DisplayName("Fix 2: additionalProperties=true (default) should NOT appear in schema")
    void testSchemaNoAdditionalPropertiesWhenTrue() {
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(
                new Object() {
                    @Tool(name = "query_data", description = "Query business data")
                    public String queryData(
                            @ToolParam(name = "keyword", description = "keyword") String keyword) {
                        return "result";
                    }
                });

        Map<String, Object> schema = toolkit.getToolSchemas().get(0).getParameters();
        assertFalse(schema.containsKey("additionalProperties"),
                "Default behavior should NOT add additionalProperties to schema");
    }

    @Test
    @DisplayName("Fix 3: ToolValidator rejects hallucinated params with additionalProperties=false")
    void testToolValidatorRejectsExtraParamsWithAdditionalPropertiesFalse() {
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(
                new Object() {
                    @Tool(
                            name = "query_data",
                            description = "Query business data",
                            additionalProperties = false)
                    public String queryData(
                            @ToolParam(name = "keyword", description = "keyword") String keyword) {
                        return "result for: " + keyword;
                    }
                });

        Map<String, Object> schema = toolkit.getToolSchemas().get(0).getParameters();
        String hallucinatedInput = "{\"keyword\": \"test\", \"owners\": [\"admin\"]}";

        String validationError = ToolValidator.validateInput(hallucinatedInput, schema);
        assertNotNull(validationError);
        assertTrue(validationError.contains("owners"));
    }

    @Test
    @DisplayName("Fix 4: ToolValidator allows extra params with default (no additionalProperties)")
    void testToolValidatorAllowsExtraParamsByDefault() {
        Toolkit toolkit = new Toolkit();
        toolkit.registerTool(
                new Object() {
                    @Tool(name = "query_data", description = "Query business data")
                    public String queryData(
                            @ToolParam(name = "keyword", description = "keyword") String keyword) {
                        return "result for: " + keyword;
                    }
                });

        Map<String, Object> schema = toolkit.getToolSchemas().get(0).getParameters();
        String hallucinatedInput = "{\"keyword\": \"test\", \"owners\": [\"admin\"]}";

        String validationError = ToolValidator.validateInput(hallucinatedInput, schema);
        assertEquals(null, validationError,
                "Default behavior should allow extra params (backward compatible)");
    }
}

Maven输出：

-------------------------------------------------------
 T E S T S
-------------------------------------------------------
Running io.agentscope.core.tool.Issue1379FixVerificationTest

=== Fix 1: Schema with additionalProperties=false ===
Full schema: {additionalProperties=false, type=object, properties={keyword={type=string, description=keyword}}, required=[keyword]}
Has 'additionalProperties' key? true
additionalProperties value: false

=== Fix 2: Schema with additionalProperties=true (default) ===
Full schema: {type=object, properties={keyword={type=string, description=keyword}}, required=[keyword]}
Has 'additionalProperties' key? false

=== Fix 3: ToolValidator with additionalProperties=false ===
Schema: {additionalProperties=false, type=object, properties={keyword={type=string, description=keyword}}, required=[keyword]}
LLM input: {"keyword": "test", "owners": ["admin"]}
Validation result: 架构中未定义属性"owners"，并且架构不允许附加属性

=== Fix 4: ToolValidator with default (no additionalProperties) ===
Schema: {type=object, properties={keyword={type=string, description=keyword}}, required=[keyword]}
LLM input: {"keyword": "test", "owners": ["admin"]}
Validation result: null

Tests run: 4, Failures: 0, Errors: 0, Skipped: 0

BUILD SUCCESS

验证结论：

测试	结果	说明
Fix 1	✅	additionalProperties=false 正确出现在 schema 顶层，不在 properties 内
Fix 2	✅	默认 true 不生成 additionalProperties，完全向后兼容
Fix 3	✅	LLM 伪造的 owners 参数被 ToolValidator 拒绝，报错：架构中未定义属性"owners"
Fix 4	✅	默认行为下 LLM 伪造参数仍被静默接受，不影响现有用户