Feature toolcall parse enhance

[miniceM]

#847

AgentScope-Java Version

1.0.10-SNAPSHOT

背景

在 LLM 工具调用场景中，模型输出的工具参数 JSON 格式可能 由于模型的能力导致输出格式不规范，常见问题包括：

• Markdown 代码块包裹（````json ... ```）
• JavaScript 风格注释（// 和 /* */）
• 单引号代替双引号
• 缺失的括号和尾随逗号
• Unicode 转义字符

这些格式问题导致标准 JSON 解析器无法正确处理，需要一种健壮的参数解析和修正机制。

目的

本 PR 新增 agentscope-extensions-tool-parser 扩展模块，提供：

1. 多阶段 JSON 清理策略：从标准 JSON 到完整修复的 5 阶段渐进式处理
2. Hook 自动集成：通过 ToolArgumentParserHook 自动拦截和修正工具调用参数
3. 完整测试覆盖：29 个解析器测试 + 20 个 Hook 测试，确保功能可靠性
4. 详细文档：提供完整的使用示例和最佳实践指南

变更内容

1. 核心解析器（ToolArgumentParser）

新增文件：

• ToolArgumentParser.java - 主解析器类（5 阶段清理策略）
• ParseResult.java - 解析结果记录类
• ParseStage.java - 解析阶段枚举

关键特性：

• ✅ 5 阶段渐进式清理：
  • Stage 0 (DIRECT): 标准 JSON 直接解析
  • Stage 1 (MARKDOWN_CLEAN): 移除 ```json 代码块
  • Stage 2 (COMMENT_STRIP): 移除 // 和 /* */ 注释
  • Stage 3 (QUOTE_FIX): 单引号转双引号
  • Stage 4 (JSON_REPAIR): 修复缺失括号和尾随逗号
• ✅ ReDoS 防护：所有正则表达式都有大小限制（代码块 50KB，注释 10KB，总参数 100KB）
• ✅ Jackson Lenient Mode：支持注释、单引号、非引号字段名
• ✅ 智能括号计数：跳过字符串内容，避免误判

2. Hook 集成（ToolArgumentParserHook）

新增文件：

• ToolArgumentParserHook.java - Hook 实现类

工作原理：

1. 拦截 PreActingEvent（工具执行前）
2. 从 ToolUseBlock.content 提取原始 JSON 字符串
3. 应用 5 阶段清理策略修正格式问题
4. 将修正后的 JSON 更新回 ToolUseBlock.content
5. 保留 ToolUseBlock 的 id、name、metadata 等字段

使用示例：
// 创建 Hook 并注册到 Agent
ToolArgumentParserHook hook = new ToolArgumentParserHook();

ReActAgent agent = ReActAgent.builder()
.name("Assistant")
.model(model)
.toolkit(toolkit)
.hooks(List.of(hook))
.build();

3. 模块配置

新增文件：

• pom.xml - Maven 模块配置

依赖管理：

• Jackson 2.18.2（JSON 处理）
• SLF4J 2.0.16（日志）
• Reactor Core 3.7.2（响应式编程）
• JUnit 5 + Mockito 5.14.2（测试）

4. 测试覆盖

新增文件：

• ToolArgumentParserTest.java - 解析器单元测试（29 个测试）
• ToolArgumentParserHookTest.java - Hook 单元测试（20 个测试）

测试类别：

• ✅ 基础功能测试（Hook 创建、优先级）
• ✅ PreActingEvent 处理测试（JSON、Markdown、注释等）
• ✅ 错误处理测试（无效 JSON、null content）
• ✅ 事件类型过滤测试（PostActingEvent 过滤）
• ✅ 特殊内容测试（Unicode、嵌套、数组、类型）
• ✅ Reactive 编程测试（Mono 响应式流）
• ✅ 元数据保留测试

5. 文档

新增文件：

• README.md - 完整的使用文档

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[codecov]

Codecov Report

❌ Patch coverage is 81.86047% with 39 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...gentscope/core/tool/parser/ToolArgumentParser.java	77.70%	19 Missing and 14 partials ⚠️
...scope/core/tool/parser/ToolArgumentParserHook.java	87.17%	5 Missing ⚠️
...ava/io/agentscope/core/tool/parser/ParseStage.java	90.90%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!