Skip to content

[chore] 收敛 streaming shared metadata contract 与 runtime/documentation drift #259

Description

@liujuanjuan1984

背景

当前仓库已经将 streaming runtime metadata 明确收敛到 shared metadata 语义,并且在 runtime、测试与文档中已经稳定暴露了多类字段:

  • metadata.shared.stream
  • metadata.shared.progress
  • metadata.shared.interrupt
  • metadata.shared.session
  • metadata.shared.usage

但基于当前主干复核,build_streaming_extension_params() 对外发布的 machine-readable contract 仍然偏薄,已经在若干位置落后于 runtime 实际输出与文档说明,削弱了 Agent Card / OpenAPI 作为 SSOT 的价值。

当前评估快照:

复现步骤

  1. 查看 src/opencode_a2a_server/extension_contracts.pybuild_streaming_extension_params() 的公开字段声明。
  2. 对照 src/opencode_a2a_server/agent.py / src/opencode_a2a_server/agent_support.py 中的实际 streaming 输出。
  3. 对照 streaming contract 相关测试与 docs/guide.md 的说明。

可以直接从以下位置观察:

  • src/opencode_a2a_server/extension_contracts.py
  • src/opencode_a2a_server/agent.py
  • src/opencode_a2a_server/agent_support.py
  • tests/test_streaming_output_contract_interrupts.py
  • tests/test_streaming_output_contract_blocks.py
  • tests/test_agent_card.py
  • docs/guide.md

当前实际行为

  1. interrupt contract 仅声明了 request_id / type / details,但 runtime 实际还会输出稳定的 phaseresolution
  2. tool_call 已经稳定以 DataPart(data={...}) 输出,并包含 call_id / tool / status / title / subtitle / input / output / error 等结构化字段,但 streaming extension params 没有对外声明 part kind 和 payload schema。
  3. runtime 已支持 metadata.shared.session.title,usage 也支持 reasoning_tokenscache_tokens.read_tokens / cache_tokens.write_tokens,但当前 contract 仍未完整声明这些字段。
  4. tests/test_agent_card.py 目前对 streaming extension params 的断言偏薄,难以及时发现后续 drift。

预期行为

  1. Agent Card / OpenAPI 发布的 streaming machine-readable contract 应与 runtime、测试、文档保持一致。
  2. interrupt metadata 的公开字段应至少覆盖当前稳定输出的 request_id / type / phase / details / resolution
  3. tool_call block 应在 contract 中明确声明:
    • block 对应的 part kind
    • 结构化 payload 的字段形状
  4. session/usage 的公开字段应补齐当前稳定支持的最小字段集合。
  5. 相关测试应能直接发现 contract 与 runtime/documentation 的漂移。

问题归纳

  • 这是同一类“runtime 已收敛,但 machine-readable contract 未同步补齐”的 SSOT drift。
  • 当前问题未必立刻导致 runtime 错误,但会误导依赖 Agent Card / OpenAPI 的集成方。
  • 如果后续继续扩展 streaming metadata,而 contract 侧没有同步收敛入口,类似问题还会重复出现。

建议方向

在不引入新的 legacy public shape 的前提下,继续沿用 build_streaming_extension_params() 作为声明入口,补齐至少以下内容:

  • interrupt_fields.phase
  • interrupt_fields.resolution
  • session_fields.id
  • session_fields.title
  • usage_fields.reasoning_tokens
  • usage_fields.cache_tokens.read_tokens
  • usage_fields.cache_tokens.write_tokens
  • block_types 增补 block -> part kind 映射
  • tool_call 增补结构化 payload schema / field contract

同时需要增强 Agent Card / OpenAPI 一致性测试,避免后续再出现实现和公开 contract 漂移。

验收标准

  • build_streaming_extension_params() 对 interrupt / tool_call / session / usage 的声明与当前 runtime 输出保持一致。
  • Agent Card / OpenAPI 对 streaming contract 的公开表述共享同一来源。
  • 文档说明与 machine-readable contract 一致,不再出现“文档有、contract 没有”的缺口。
  • 测试能够直接验证 streaming extension params 的关键字段集合与 shape。
  • 不新增平行 contract 或 legacy shape。

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions