fix: Align Anthropic ToolChoice.None mapping with disable tools intent

[BG0527]

关联 issue

• Fixes [Bug]: ToolChoice.None 被映射为 Anthropic any #2221

AgentScope-Java Version

2.0.1-SNAPSHOT

Description

Background

ToolChoice.None 的语义是"禁止模型调用任何工具"，即本轮只返回文本回复。Anthropic API 原生支持 tool_choice: none 选项（SDK com.anthropic:anthropic-java:2.14.0 中提供 ToolChoice.ofNone(ToolChoiceNone) 方法）。

Root Cause

AnthropicToolsHelper.applyToolChoice() 将 ToolChoice.None 映射为 ToolChoice.ofAny(ToolChoiceAny)，而 any 在 Anthropic API 中表示"必须调用工具"，与 None 的"禁止调用工具"语义完全相反。这导致设置了 ToolChoice.None 时，模型反而被强制调用工具。

原代码（L95-97）：

} else if (toolChoice instanceof ToolChoice.None) {
    // Anthropic doesn't have None, use Any instead
    builder.toolChoice(ofAny(ToolChoiceAny.builder().build()));

注释错误地声称"Anthropic doesn't have None"，实际上 Anthropic SDK 2.14.0 已提供 ToolChoiceNone 和 ToolChoice.ofNone()。

Fix

1. 核心修复：将 ToolChoice.None 映射从 ofAny(ToolChoiceAny) 改为 ofNone(ToolChoiceNone)，正确表达"工具存在但本轮禁止调用"的语义，与 OpenAI、Gemini、DashScope 等其他扩展保持一致。
2. 可观测性增强：当 tools 为空但 options 中设置了 toolChoice 时，增加 debug 日志提示，便于排查"设了 None 但没生效"的困惑场景。
3. 测试覆盖增强：
   • testApplyToolChoiceNone 增加排他性断言（!isAny()、!isAuto()）和 tools 列表完整性断言
   • 新增 testApplyToolChoiceNoneWithEmptyToolsSkipsToolChoice 边界测试

Changed files:

1. agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/main/java/io/agentscope/extensions/model/anthropic/formatter/AnthropicToolsHelper.java

• import 新增 ofNone、ToolChoiceNone
• applyToolChoice(): ToolChoice.None 分支从 ofAny(ToolChoiceAny.builder().build()) 改为 ofNone(ToolChoiceNone.builder().build())
• applyTools(): 空 tools 提前返回时增加 debug 日志

2. agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/test/java/io/agentscope/extensions/model/anthropic/formatter/AnthropicToolsHelperTest.java

• testApplyToolChoiceNone: 断言从 isAny() 改为 isNone()，新增排他性断言和 tools 列表完整性断言
• 新增 testApplyToolChoiceNoneWithEmptyToolsSkipsToolChoice 边界测试

Checklist

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[jujn]

LGTM