[Architecture] tool_call 流块改用 DataPart 承载，避免语义混淆

[liujuanjuan1984]

现象

当前 opencode-a2a-serve 在输出流式 tool_call 块时，会把工具调用状态序列化为 JSON 字符串，并放进 TextPart：

• artifact.parts[*].kind = "text"
• 同时在 artifact.metadata.shared.stream.block_type = "tool_call" 中表达真实块类型

这在 A2A SDK 类型上是可运行的，但语义层存在混淆：parts.kind 表示载体是文本，而块语义实际上是工具调用。

影响

1. 下游如果没有严格优先读取 metadata.shared.stream.block_type，很容易把 tool_call 误判为普通文本。
2. 调试和抓包时，可读性不直观；同一个事件同时表达“文本载体”和“工具调用语义”。
3. 对非本仓库实现的通用 A2A 客户端而言，这种表达方式的兼容成本更高。

根因

当前实现使用 TextPart(text=<json string>) 作为工具调用流块的承载容器。

这不是 SDK 层面的非法用法，但从协议建模角度，工具调用状态更接近结构化数据，而不是自由文本。

建议方案

将流式 tool_call 块的承载从 TextPart 调整为 DataPart：

1. artifact.metadata.shared.stream.block_type 继续保留并作为块语义权威字段。
2. artifact.parts[*] 改为 DataPart(data={ ...structured tool payload... })。
3. text/reasoning 仍继续使用 TextPart。
4. 文档与测试同步更新，明确 tool_call 的结构化数据形状。

为什么这样更好

• DataPart 更符合“工具调用是结构化状态对象”的语义。
• 可减少下游把 tool_call 当成普通文本的概率。
• 与 metadata.shared.stream.block_type 组合后，协议表达更清晰。

验收标准

1. 流式 tool_call 更新输出为 DataPart。
2. artifact.metadata.shared.stream.block_type 仍为 tool_call。
3. 现有 text/reasoning 流块行为不回归。
4. 新增测试覆盖 tool_call 的 DataPart 输出。

[liujuanjuan1984]

基于 main@9938817 的复核，#155 仍然合理且有效，问题描述与当前实现一致：流式 tool_call 现在仍通过 TextPart(text=<json string>) 承载，同时再用 metadata.shared.stream.block_type = "tool_call" 补充真实语义。

这在运行上可用，但从契约建模看不够清晰，确实容易让下游把结构化工具状态误判为普通文本。当前主干里 #152 / #76 已经把 shared contract 与 provider-private contract 的边界收口得比较明确，因此这里的最佳实践也不是继续在 metadata 上叠更多补丁，而是把载体本身修正到与语义一致：

• text / reasoning 继续使用 TextPart
• tool_call 改为 DataPart(data={...})
• metadata.shared.stream.block_type = "tool_call" 继续保留，作为块语义权威字段
• 文档、Agent Card / OpenAPI 示例（如有）、测试一并同步

我没有发现与该问题高度重复的 open issue；它和下游总原则问题 https://github.com/liujuanjuan1984/a2a-client-hub/issues/443 也是一致的，因为这次调整的目标正是减少 provider / adapter 侧的语义歧义，而不是增加新的私有方言。

接下来我会按这个边界直接在当前分支实施。

[liujuanjuan1984]

已按前述边界在当前分支完成 #155 实施。

实现结果：

• 流式 tool_call 块已从 TextPart(text=<json string>) 切换为 DataPart(data={...})
• artifact.metadata.shared.stream.block_type = "tool_call" 继续保留，仍是块语义权威字段
• text / reasoning 继续保持 TextPart
• 流式 append-only 单 artifact 语义保持不变；tool_call 的去重现在基于结构化 payload 的规范化 fingerprint，而不是拼接字符串
• 文档与测试已同步更新

验证结果：

• uv run pre-commit run --all-files 通过
• uv run pytest 通过，158 passed，coverage 83.87%

当前实现没有引入新的 provider-private 方言，也没有改变 shared stream metadata 边界，和 https://github.com/liujuanjuan1984/a2a-client-hub/issues/443 的收口原则一致。

[liujuanjuan1984]

已基于当前分支实现做了完整排查，结论同步如下：

1. 本次需要从 TextPart 调整为 DataPart 的，当前只有 tool_call。
2. 已检查其它现有流式相关类型，没有发现第二类“结构化对象被当作文本承载”的同类问题。
3. text / reasoning 仍然是自然语言增量或文本快照，继续使用 TextPart 是合理的，不建议一并改动。
4. step-finish 没有映射为流式 artifact block；当前实现只是从这类事件里提取 token/cost 信息，并合并到最终 TaskStatusUpdateEvent(final=true) 的 metadata.shared.usage。因此它不属于这次 TextPart -> DataPart 的问题范畴。
5. permission.asked / question.asked 也不是 artifact part；当前实现会把它们映射为 TaskStatusUpdateEvent(final=false, state=input-required)，详细信息放在 metadata.shared.interrupt。因此它们也不属于这次 TextPart -> DataPart 的同类问题。

本分支上的对应实现、测试、文档已经对齐：

• tool_call 流块使用 DataPart(data={...}) 承载，artifact.metadata.shared.stream.block_type 仍保留为 tool_call。
• text / reasoning 继续使用 TextPart。
• 新增测试覆盖了 tool_call 的结构化输出和非累积去重语义。

已完成本地验证：

• uv run pre-commit run --all-files 通过
• uv run pytest 通过（158 passed）