[Priority: Med] [Contracts] 明确 chat acceptedOutputModes 前置校验与输出模式边界

[liujuanjuan1984]

背景

• 在对照 codex-a2a 与 opencode-a2a 的 input/output modes 实现时，发现 opencode-a2a 当前已经做了比较清晰的输入边界约束，但输出 modes 侧仍有一处可进一步收口的契约表达。
• codex-a2a 最近补上了 task-scoped 的 acceptedOutputModes 协商持久化；反过来看，opencode-a2a 有一条实践值得继续固化并补齐文档：对 chat 请求做 fail-fast 的 output modes 兼容性校验。

现状

• 当前实现已经在入口和 executor 层要求 OpenCode chat 至少接受 text/plain，否则会返回明确错误，而不是在运行过程中隐式丢内容。
• 这条约束本身是合理的，因为 OpenCode chat 的自然语言主输出仍以 TextPart 为主；application/json 仅覆盖结构化 tool_call 增量，不足以表达全部正常回复。
• 但这条设计意图在 guide 中还没有被直接说透，客户端读 Agent Card / guide 时，仍可能把 default_output_modes = [text/plain, application/json] 误解成“只接受 application/json 也总能工作”。

建议

• 将当前的 fail-fast 校验提升为显式稳定契约：对于 main chat，若请求声明了 acceptedOutputModes，则必须与服务声明能力兼容，且必须包含 text/plain。
• 在 guide 中直接补一句 consumer guidance：application/json 是增量结构化输出能力，不承诺所有自然语言回复都能无损升级为 JSON；期望普通 assistant prose 的客户端应继续接受 text/plain。
• 为这条约束补一组更聚焦的契约测试，覆盖：
  • acceptedOutputModes=["application/json"] 时在入口被拒绝
  • 错误类型/消息/数据字段稳定
  • Agent Card / guide /测试三处表达一致

可参考的另一方向

• 若未来 opencode-a2a 放宽 output modes 协商能力，可以参考 codex-a2a 刚补上的 task-scoped negotiation persistence：同一 task 的 message/send、message/stream、tasks/get、tasks/resubscribe、push notification 应共享同一 negotiated output surface，而不是只在当前响应出口做一次性降级。
• 相关参考实现与讨论见：
  • [bug] 对齐 Agent Card media modes 与 runtime 行为，并补上 acceptedOutputModes 协商 liujuanjuan1984/codex-a2a#214

价值

• 降低客户端误解 Agent Card modes 的概率
• 让失败更早、更稳定、更容易调试
• 为后续若要扩展更细粒度 output negotiation 留出清晰的契约起点

[liujuanjuan1984]

当前审查结论：#379 仍然合理且有效，但实施范围建议收敛为“公开契约固化”，不需要再发明一轮新的运行时主逻辑。

依据当前主干代码：

• 入口层已经有 fail-fast 校验，src/opencode_a2a/server/application.py 会在 message/send / message/stream 前检查 acceptedOutputModes 是否与 chat 声明能力兼容，并且显式要求包含 text/plain。
• executor 层也已有兜底，src/opencode_a2a/execution/executor.py 在真正执行前再次拒绝不接受 text/plain 的请求。
• Agent Card 已声明 chat default_output_modes=["text/plain", "application/json"]，但 guide 里还没有把“application/json 只是增量结构化输出能力，不代表普通 prose 回复都能无损 JSON 化；普通 chat 客户端仍应接受 text/plain”这层 consumer guidance 直接说透。

因此我建议把 issue 的实施边界收敛为：

1. 保持现有 fail-fast 逻辑，不额外再加一层新的运行时校验路径。
2. 在 docs/guide.md 明确写出 chat output modes 的消费者指引：
   • 显式 acceptedOutputModes 必须与声明能力兼容。
   • 当前 main chat 请求必须包含 text/plain。
   • application/json 是增量结构化输出支持，不承诺所有自然语言回复都能无损表示为 JSON。
3. 视表达需要，在 src/opencode_a2a/server/agent_card.py 的 opencode.chat skill description 里补一句边界说明，但不建议为了这一条约束单独新增新的 extension 字段或额外 metadata 面。
4. 测试上补更聚焦的契约测试：
   • 入口层拒绝 acceptedOutputModes=["application/json"]，并稳定断言错误 message 与 data 字段；
   • 入口层拒绝完全不兼容的 modes；
   • 继续保持 Agent Card 对 chat output modes 的声明为 text/plain + application/json。

另外，建议不要把“guide 文案一致性”做成脆弱的全文字符串快照测试。机器可消费的稳定契约仍应以 Agent Card / error payload / capability metadata 为主，guide 只做解释性补充。

对照 ~/codex-a2a-serve 的现状，这个判断也成立：那边已经把同类 guidance 直接写进 docs/guide.md 与 docs/compatibility.md，可以作为文案边界参考，但 opencode-a2a 不需要把 task-scoped output negotiation persistence 一并带进本 issue。

相关 open issues 审查：

• #348 高度相关，但不建议同分支一并开发。它是更大的版本兼容矩阵与支持边界公开问题，范围明显宽于 #379。
• #369 有关联，但也不建议绑定。#379 只需要在当前错误封装下把 chat output-mode 失败契约写稳，不必顺手启动 v1-ready error envelope 抽象。
• #370 只在“后续外部兼容性验证”层面相关，不适合和这次文档/契约固化混做。

结论：#379 建议单独推进，按“guide + 可选 skill 描述 + 聚焦契约测试”的最小边界实施即可；当前没有必须建议与它同分支捆绑开发的其它 open issue。

[liujuanjuan1984]

开始实施 #379。

本次按评估后的最小边界落地：

• 补 docs/guide.md 的 chat output modes consumer guidance
• 视需要补 opencode.chat skill description 的边界说明
• 补更聚焦的入口契约测试，稳定断言 acceptedOutputModes=["application/json"] 与完全不兼容 modes 的错误 message/data

不改现有主逻辑，也不把更大的版本兼容 / 错误封装抽象问题混进本次分支。

[liujuanjuan1984]

#379 已完成，范围按“契约固化”收敛，没有额外扩张到新的运行时主逻辑。

本次落地内容：

• 在 docs/guide.md 补充 chat output modes 的 consumer guidance，明确：
  • 显式 acceptedOutputModes 必须与 chat 声明能力兼容；
  • 当前 main chat 请求必须继续接受 text/plain；
  • application/json 是增量结构化输出支持，不承诺普通 prose 回复都能无损 JSON 化。
• 在 src/opencode_a2a/server/agent_card.py 的 opencode.chat skill description 中补充同一边界说明。
• 在 tests/server/test_app_behaviors.py 补充更聚焦的入口契约测试，稳定断言：
  • acceptedOutputModes=["application/json"] 会在入口被拒绝，且错误 data 字段固定包含 accepted_output_modes / required_output_modes / supported_output_modes；
  • 完全不兼容的 acceptedOutputModes=["image/png"] 也会在入口被拒绝，且错误 data 字段固定包含 accepted_output_modes / supported_output_modes。
• 在 tests/server/test_agent_card.py 补充 chat skill 文案断言，避免 Agent Card 说明回退。

回归结果：

• uv run pytest --no-cov tests/server/test_app_behaviors.py tests/server/test_agent_card.py -q
• ./scripts/doctor.sh

结果：482 passed，总覆盖率 91.42%。

[liujuanjuan1984]

关联 PR 已创建：

• PR docs: clarify chat output mode contract #381: docs: clarify chat output mode contract #381

当前 PR 标题：docs: clarify chat output mode contract