[TechDebt] 评估 non-stream success 中 status.message 与 artifact 的语义重复

[liujuanjuan1984]

背景

当前仓库在 core chat streaming success 路径上，已经基本遵循了较清晰的语义边界：

• 流式正文主要通过 TaskArtifactUpdateEvent 发出
• 终态 TaskStatusUpdateEvent 主要表达 TASK_STATE_COMPLETED 与相关 metadata

对应实现可见：

• src/opencode_a2a/execution/coordinator.py:393-436

但在 non-stream success 路径中，当前实现会同时：

• 构造一份最终 Artifact(parts=[Part(text=response_text)])
• 再把同一份完整文本复制进 terminal Task.status.message

对应实现可见：

• src/opencode_a2a/execution/coordinator.py:439-481

本地审查快照：8ea6a265fd62754a52a7e3fc5d96f08204bbd8de

问题描述

从 a2a-python 当前公开语义来看：

• TaskStatusUpdateEvent 更偏 task status delta / lifecycle update
• Artifact 更偏 task completed result container

在这个前提下，non-stream success 路径把“最终回答全文”同时放进 Task.status.message 与 artifacts，会带来两类问题：

1. 语义分层不够清晰

• 成功结果到底以 artifact 为主，还是以 status.message 为主，不够明确

2. 客户端消费顺序容易分叉

• 一些客户端会优先读 task.status.message
• 另一些客户端会优先读 task.artifacts
• 当前重复写入虽然提升了兼容性，但也让“哪个字段才是 canonical result”变得模糊

建议方向

建议评估并明确 non-stream success 的语义边界，至少选择其一并在文档/测试中固定下来：

方案 A：artifact 作为成功结果主通道

• 当 terminal Task 已带完整 artifacts 时，不再复制完整正文到 task.status.message
• task.status.message 仅在错误、输入请求、中断等场景承载用户可读说明

方案 B：保留兼容复制，但收窄语义

• 仍允许 task.status.message 存在
• 但它只保留简短 completion summary，例如 Done. / Completed.
• 不再与 artifact 重复承载完整回答正文

方案 C：如果短期必须保持现状

• 至少在文档中明确：artifacts 才是 success result 的 canonical carrier
• task.status.message 只是兼容性冗余字段，不应被新客户端当作唯一结果来源

建议验收标准

• 明确记录 non-stream success 下 task.status.message 与 artifacts 的职责边界
• 更新对应实现或文档，使 success result 的 canonical carrier 可被稳定说明
• 增补/更新测试，固定所选语义，避免后续再次漂移

参考依据

• a2a-python 迁移说明中，task lifecycle stream 示例采用“status 表示 processing/done，artifact 表示 result”的结构：
  https://github.com/a2aproject/a2a-python/blob/main/docs/migrations/v1_0/README.md
• a2a-python proto 注释中，Artifact 被描述为 task completed results container：
  https://github.com/a2aproject/a2a-python/blob/main/src/a2a/compat/v0_3/a2a_v0_3.proto

[liujuanjuan1984]

状态更新：已基于最新 main 创建本地分支 issue-481-nonstream-success-result-semantics 并完成评估与实现。

评估结论：需求仍然有效。最新主干仍在 non-stream success 路径中把完整回答同时写入 Task.artifacts 和 Task.status.message，与 streaming success 路径的分层语义不一致；a2a-python 当前迁移文档示例也更接近“artifact 承载 result，status 承载 lifecycle/status 文本”的结构。

实施选择：采用方案 B。保留 Task.status.message，但仅写入简短状态 Completed.；完整 assistant result 仅保留在 Task.artifacts，并在 docs/guide.md 明确 Task.artifacts 是 successful non-streaming completion 的 canonical carrier。同步调整了本仓库客户端 extract_text(Task) 的读取优先级，避免短状态文本遮蔽 artifact result。

相关 open issues：当前 open issue 仅有 #481 与 #451。#451 聚焦 push notification config persistence / capability 分层，与本次 result/status 语义边界没有高度耦合，不建议并入本分支。

验证：./scripts/doctor.sh 已通过，包含 mypy、690 个 pytest、覆盖率门槛、package build 和 built-wheel smoke test。