[Priority: Low] [Enhancement] 明确 Python API facade 导出契约
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 初心者へのやさしさ
- 35/100
- issue の種類
- 機能追加
- 明瞭さ
- 説明が足りない
- 活発さ
- 活発
- 技術スタック
- python
調査の方向性
src/opencode_a2a/contracts/extensions/init.py から始め、その本番コンシューマーと既存のコントラクトテストを調査します。このファサードが安定しているのか内部向けなのかを判断して文書化し、選択した方針に従います。つまり、最小限の all とインポートのコントラクトテストを定義するか、定義モジュールから段階的にインポートする計画を立てます。bash ./scripts/doctor.sh を実行し、受け入れ基準を確認します。
索引モデルが issue の本文から書いたものです。
説明
背景
在 #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 兼容策略应如何在文档和测试中体现？
建议方案
- 先记录仓库支持的 Python API 边界，避免仅凭当前导入形状隐式扩大兼容承诺。
- 若确认
contracts.extensions是稳定 facade：- 添加显式
__all__，仅列出有意公开的 symbols； - 添加 package/facade import contract tests；
- 验证 wheel 中的导入路径和类型信息；
- 在兼容性文档中说明变更与弃用策略。
- 添加显式
- 若不承诺该 facade：
- 明确其 internal/convenience 定位；
- 逐步让仓库内部消费者从真实定义模块导入，避免形成更强的事实 API。
非目标
- 不在本 issue 中改变 A2A wire contract、Agent Card、OpenAPI 或 JSON-RPC 行为。
- 不因为添加
__all__就自动承诺当前全部 re-export 永久稳定。 - 不与 #515 的 SDK 升级和 compatibility layer 审计混合实施。
验收标准
- 明确记录受支持的 Python API/facade 边界。
- 对
contracts.extensions作出“稳定 facade”或“内部便利入口”的明确决定。 - 若选择稳定 facade，添加最小显式
__all__和 import contract tests。 - 若选择内部入口，制定不破坏当前仓库调用的渐进收敛方案。
- 执行
bash ./scripts/doctor.sh。
关联
- Follow-up from #518
- 参考跨仓库
https://github.com/liujuanjuan1984/codex-a2a/pull/358中对已发布 JSON-RPC params facade 的兼容性复核经验。
- 主要言語
- Python
- スター
- 38
- フォーク
- 13
- 平均マージ
- 3時間 43分
- マージ済み PR（30日）
- 4
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
Intelligent-Internet/opencode-a2a のほかの issue
-
難易度 4/5 3〜5日 初心者へのやさしさ 20/100
Intelligent-Internet/opencode-a2a#550 · コメント 3 件 · リアクション 1 件 ·
メンテナーはふだん 1 日以内に返信
-
status:todo
難易度 5/5 1週間以上 初心者へのやさしさ 42/100
Intelligent-Internet/opencode-a2a#451 · コメント 3 件 ·
メンテナーはふだん 1 日以内に返信
Intelligent-Internet/opencode-a2a の issue をすべて見る
似ている issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
UKGovernmentBEIS/inspect_ai#6512 ·
メンテナーはふだん 1 日以内に返信
-
area/c++ area/core kind/bug-report
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
tensorflow/quantum#1140 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 68/100
Kav-K/GPTDiscord#501 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
UKGovernmentBEIS/inspect_evals#2863 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信