[Bug]:很奇怪的一个bug，我让agent写入一个带有格式的html文件，整个参数都是空

[wangyangvip12345-prog]

1：agent正常写入md文档的时候没有问题，调试tool中的参数都能正常解析。
2：但是我当让agent写一个html格式的文件的时候，带有/n+空格的这种tool调用全都是null。

关于null的问题我刚开始是以为JsonUtils解析出来的map是空导致的，但是实际上我调试的之后，发现这个这个util是能正确的解析到这个json并且变成map的。并且map不是空。但是调用工具的时候就变成所有的参数都是null？这个问题怎么解决求助

[wangyangvip12345-prog]

标题

AgentScope：流式 ToolCall 在 input 非空但 value 为 null 时不会二次解析 arguments，导致工具入参全 null（复杂 HTML / 多行文本高概率触发）

现象

在使用 AgentScope（OpenAI streaming tool calls）时，模型调用工具 write_text_file(file_path, content, ...)：

• ToolCallsAccumulator 聚合后的 ToolUseBlock.input 看起来有 key（例如 size=3），但关键字段 file_path/content 的 value 可能为 null；
• 最终进入工具方法时 @ToolParam(name="file_path") String filePath、@ToolParam(name="content") String content 变为 null，导致写文件失败；
• 同样的逻辑写 md 文件通常没问题，写复杂 html（大量引号、多行、转义复杂）更容易复现。

线上可见类似日志（来自业务侧兜底 hook）：

Tool args repaired: id=..., name=write_text_file, inputKeysBefore=3, inputKeysAfter=5, contentLength=7125

这意味着：ToolUseBlock.content 中存在可恢复的完整 arguments，但 ToolUseBlock.input 中部分字段为 null / 缺失。

复现条件（建议）

1. 启用 OpenAI streaming；
2. 让模型调用任一带 file_path + content 的写文件工具；
3. content 使用大段 多行 HTML（包含大量 "、\n、可能还有反斜杠、脚本/CSS 等）；
4. 观察工具方法入参为 null，且 ToolUseBlock.content 内仍可看到完整 JSON arguments。

关键链路（源码位置）

1) 流式 tool call 解析阶段：OpenAIResponseParser

AgentScope 在流式解析时对 tool call 的处理（关键点：只有当 arguments“看起来完整”才尝试 parse）：

• 首块（有 toolName）：
  • 若 arguments.trim().startsWith("{") && arguments.trim().endsWith("}")，则 fromJson(arguments, Map.class)，把 parsed 放入 ToolUseBlock.input；
  • 无论是否 parse 成功，都会把原始 arguments 片段放进 ToolUseBlock.content。
• 后续片段（toolName 为空）：
  • 仅将 arguments 片段追加为 ToolUseBlock.content，input 为空 map。

代码参考：

• OpenAIResponseParser.java

2) 聚合阶段：ToolCallsAccumulator

流式片段会在 ToolCallsAccumulator 中合并：

• merge()：args.putAll(block.getInput())，rawContent.append(block.getContent())
• build()：只有当 finalArgs.isEmpty() 时，才会尝试对 rawContentStr 做最终一次 fromJson(rawContentStr, Map.class)。

代码参考：

• ToolCallsAccumulator.java

3) 执行阶段：ToolMethodInvoker

工具参数绑定是典型的：

• paramName = @ToolParam.name；
• value = input.get(paramName)；
• value == null → 直接返回 null。

代码参考：

• ToolMethodInvoker.java

原因分析（最可能的根因）

根因 A：finalArgs 非空但“不完整/含 null”，导致跳过最终解析

ToolCallsAccumulator.build() 的解析策略是：

仅当 finalArgs 为空，才尝试把 rawContentStr 解析为 Map。

这在“复杂 HTML + 流式 arguments”场景会出问题：

1. 首块 arguments 可能满足 {...} 形式（例如模型提前输出了 }，或者 delta 里出现了局部闭合结构），触发 “看起来完整就 parse” 的逻辑；
2. 但此时 arguments 内部字符串（HTML）往往还处于“非严格 JSON”状态（未转义换行/引号/控制字符），导致 parse 行为不稳定：
   • 有时 parse 失败 → argsMap 为空（但随后 rawContentStr 拼接完整后仍可解析）；
   • 更糟糕的是：parse 部分成功 或输出 key 但 value 为 null（具体取决于 JSON codec 的容错与模型输出形态）。
3. 一旦 argsMap 被塞进 finalArgs（哪怕只是一些 key 或 null value），finalArgs 就“非空”，从而 永远不会再对最终 rawContentStr 做一次完整解析；
4. 最终 ToolUseBlock.input 中出现 file_path/content 为 null，ToolMethodInvoker 直接绑定为 null。

换句话说：content 里有真相，但因为 input 不为空，就不再相信 content，这在 streaming 下是不安全的。

根因 B：Map 合并行为会被 null 覆盖（潜在）

merge() 使用 putAll，若后续某一块的 input 中带有 key -> null，将覆盖前面非 null 值（虽然 OpenAIResponseParser 的 fragment 目前传空 map，但其他 formatter/实现可能会把 null 带进来）。

官方建议优化（推荐）

建议 1：ToolCallsAccumulator 总是尝试解析 rawContentStr，并“只填缺失/不覆盖非 null”

将：

if (finalArgs.isEmpty() && rawContentStr.length() > 0) { parse rawContentStr }

改为更鲁棒的策略（伪代码）：

if (rawContentStr not blank) {
  parsed = fromJson(rawContentStr, Map.class)
  for (k,v in parsed) {
    if (v != null && (finalArgs.get(k) == null || !finalArgs.containsKey(k))) {
      finalArgs.put(k, v)
    }
  }
}

这样可以：

• 让最终完整 arguments 拥有“纠错机会”（尤其是大段字符串在 streaming 场景容易早期不合法）；
• 避免把已绑定的非 null 参数被覆盖；
• 对复杂文本（HTML/SQL/代码片段）更稳定。

建议 2：OpenAIResponseParser 避免“仅凭首尾大括号”判断 arguments 完整性（可选）

startsWith("{") && endsWith("}") 过于宽松，流式场景可能出现“局部闭合”误判。更稳妥做法：

• 延迟 parse：首块不 parse，只累积 raw arguments；完全交给 accumulator 在末尾 parse；
• 或增加更严格的“结构完整性”判断（括号深度、字符串状态机等）。