[Priority: Low] [Enhancement] 明确 Python API facade 导出契约

[liujuanjuan1984]

背景

在 #518 的冗余清理与跨仓库 facade 风险对照中发现，src/opencode_a2a/contracts/extensions/__init__.py 是仓库实际使用的聚合导入入口，目前通过 # ruff: noqa: F401 表达 re-export，但没有显式 __all__ 或独立 facade import contract tests。

当前没有功能故障：该入口有生产代码和契约测试消费者，不会被合理的死代码审查判定为无消费者模块。本 issue 仅作为低优先级 API 治理备忘，不代表现有全部 re-export 已经被承诺为长期稳定的公共 Python API。

需要明确的问题

• opencode_a2a.contracts.extensions 是否应作为受支持的稳定 Python API facade？
• 若是，哪些 symbols 属于有意公开的最小集合，哪些应继续从定义模块导入？
• 稳定性承诺是否只覆盖 client/__init__.py，还是还应覆盖 contracts facade？
• py.typed 发布与 Python API 兼容策略应如何在文档和测试中体现？

建议方案

1. 先记录仓库支持的 Python API 边界，避免仅凭当前导入形状隐式扩大兼容承诺。
2. 若确认 contracts.extensions 是稳定 facade：
   • 添加显式 __all__，仅列出有意公开的 symbols；
   • 添加 package/facade import contract tests；
   • 验证 wheel 中的导入路径和类型信息；
   • 在兼容性文档中说明变更与弃用策略。
3. 若不承诺该 facade：
   • 明确其 internal/convenience 定位；
   • 逐步让仓库内部消费者从真实定义模块导入，避免形成更强的事实 API。

非目标

• 不在本 issue 中改变 A2A wire contract、Agent Card、OpenAPI 或 JSON-RPC 行为。
• 不因为添加 __all__ 就自动承诺当前全部 re-export 永久稳定。
• 不与 升级 a2a-sdk 至 1.1.3 并审计下游兼容层 #515 的 SDK 升级和 compatibility layer 审计混合实施。

验收标准

• 明确记录受支持的 Python API/facade 边界。
• 对 contracts.extensions 作出“稳定 facade”或“内部便利入口”的明确决定。
• 若选择稳定 facade，添加最小显式 __all__ 和 import contract tests。
• 若选择内部入口，制定不破坏当前仓库调用的渐进收敛方案。
• 执行 bash ./scripts/doctor.sh。

关联

• Follow-up from refactor: remove high-confidence redundant code #518
• 参考跨仓库 https://github.com/liujuanjuan1984/codex-a2a/pull/358 中对已发布 JSON-RPC params facade 的兼容性复核经验。