审查 A2A v1.0 官方迁移缺口与冗余兼容

[liujuanjuan1984]

背景

当前仓库已完成一轮 a2a-sdk 1.0.x 升级，但需要再对照官方迁移文档做一次系统审查，确认是否仍有未完成迁移点，或保留了不必要的旧兼容层。

对照基线：

• ~/a2a-python/docs/migrations/v1_0/README.md:64
• ~/a2a-python/docs/migrations/v1_0/README.md:500

目标

• 审查当前仓库相对于官方 A2A v1.0 迁移清单的剩余缺口
• 审查当前仓库中仍然存在的非必要兼容逻辑
• 形成明确的差异清单，区分：
  • 未迁移完成
  • 可以删除的兼容层
  • 需要保留的本仓库特化行为

验收

• 给出按模块归类的审查结果
• 标注高置信问题与建议处理方向
• 如发现明显可收敛项，可在当前分支继续推进实现与回归

[liujuanjuan1984]

当前基于 ~/a2a-python/docs/migrations/v1_0/README.md 的对照审查结论如下。

已完成的主干迁移：

• 生产代码已经使用 protobuf request / message 类型，Role.ROLE_*、TaskState.TASK_STATE_* 也已切换。
• client 侧已经采用 create_client()，并按 StreamResponse.HasField() 消费流式响应。
• AgentCard 已切到 supported_interfaces + AgentCapabilities.extended_agent_card 新结构。

仍存在的迁移缺口：

1. 默认协议线仍是 0.3，且默认声明同时支持 0.3 与 1.0：src/opencode_a2a/config.py:179-182。
2. REST HTTP+JSON 主路径仍以旧 payload 形状为准，要求 message.content，并把旧 file.{bytes|uri} 包装归一化成 v1 parts/raw/url：src/opencode_a2a/server/application.py:256-337，src/opencode_a2a/server/middleware.py:409-412。
3. JSON-RPC 主路径仍以内建 legacy method 名为中心，SendMessage / SubscribeToTask 等 v1 方法会先被改写成 message/send / tasks/resubscribe 再处理：src/opencode_a2a/a2a_protocol.py:8-24，src/opencode_a2a/server/request_parsing.py:98-111，src/opencode_a2a/jsonrpc/application.py:376-395。
4. OpenAPI / AgentCard 文案仍在展示旧术语和旧 method 名，例如 TextPart / FilePart、message/send、message.content：src/opencode_a2a/server/agent_card.py:122-125、src/opencode_a2a/server/agent_card.py:480-484、src/opencode_a2a/server/openapi.py:43-45、src/opencode_a2a/server/openapi.py:70-85、src/opencode_a2a/server/openapi.py:523-549。

不必要的兼容残留：

1. tests/conftest.py:13-163 仍整体伪造旧 SDK 符号与模块，包括 TextPart / FilePart / TaskIdParams / MessageSendParams / a2a.server.apps.*。
2. 多个测试仍直接依赖这些旧符号：tests/execution/test_multipart_input.py:2-3、tests/server/test_cancel_contract.py:7-16、tests/server/test_transport_contract.py:8。
3. client façade 里还保留了 ClientFactory fallback 分支，主要用于旧测试 seam，而不是当前 v1 主路径：src/opencode_a2a/client/client.py:323-329，对应测试 tests/client/test_client_facade.py:139-145、tests/client/test_client_facade.py:182-189。
4. handler 里 on_resubscribe_to_task() 仍接受非 SubscribeToTaskRequest 入参并二次包一层：src/opencode_a2a/server/application.py:707-716。

建议后续收敛顺序：

1. 先把默认协议与默认文档面切到纯 1.0。
2. 再删 JSON-RPC / REST 的旧 method 与旧 payload 归一化。
3. 最后清空测试 shim，并把测试改成真实 v1 request / part 形状。

[liujuanjuan1984]

已在 chore/423-a2a-v1-migration-gap-audit 上完成一轮 v1-only 迁移收敛。

本轮处理：

• 后端默认协议与声明改为仅支持 1.0
• 删除 REST / JSON-RPC 旧方法名与旧 payload 兼容归一化，改为严格要求 v1 canonical 语义
• 清理测试侧 legacy shim，补齐真实 v1 request / part / error model 测试
• 文档口径改为 v1-only，移除旧 0.3 / message/send / additionalInterfaces 等对外描述
• 新增 jsonrpc.application 覆盖测试，补足迁移后调度分支覆盖

回归结果：

• ./scripts/doctor.sh passed
• 591 passed
• total coverage 90.97%
• src/opencode_a2a/jsonrpc/application.py coverage 99%

当前仍保留的仅是与 v1 兼容无关的已知非阻塞工具链 warning：构建阶段 vcs_versioning 的 GlobalOverrides 提示。

[liujuanjuan1984]

补充：本轮变更已整理为本地提交 eb2d593（refactor: complete a2a v1-only migration）。当前工作区已清洁。

[liujuanjuan1984]

独立复审补充（已推送 eb2d593 到 origin/chore/423-a2a-v1-migration-gap-audit）：

对照 ~/a2a-python/docs/migrations/v1_0/README.md:64 与 :500 一带迁移点再次核查后，主协议迁移已基本完成：

• 枚举已切到 ROLE_* / TASK_STATE_*
• Part 已切到 text/raw/url/data 直字段
• AgentCard 已切到 supported_interfaces + AgentCapabilities.extended_agent_card
• client 创建已改为 create_client()
• StreamResponse.HasField() 已用于客户端事件处理
• 未再启用 v0.3 compat flag，也未再声明 0.3 interface

仍建议关注的残留点：

1. OpencodeRequestHandler 仍把 agent_card 设计为可选，并在缺省时回退到占位 AgentCard(name="opencode-a2a")。这与迁移指南要求的“request handler 构造时显式提供 agent_card”不完全一致。
2. repo 自有 A2AClient facade 仍未直接暴露原生 AsyncIterator[StreamResponse]，而是继续适配成 Message | (Task, update)，并保留 polling fallback / resubscribe_task 这层仓库语义；这不是旧协议兼容，但也还不是完全贴近 SDK v1 原生表面。
3. 仍保留少量 legacy-shape 探测逻辑，仅用于拒绝旧 payload 并返回更明确错误，例如 _looks_like_legacy_message_payload() 及其中间件调用点。这不是 wire compatibility，但属于可继续删除的兼容感知代码。
4. helper 层仍主要使用仓库自建 a2a_utils，没有吸收官方 a2a.helpers 作为统一入口；这不是协议缺口，但属于迁移指南第 10 节未完全跟进。
5. 文档仍有极少量措辞残留，例如 docs/guide.md 里还写了 TaskState.canceled / subscribe 这类旧式表述，虽然不影响运行时。

[liujuanjuan1984]

继续收敛完成，已推送最新提交 71a33c5（refactor: remove remaining a2a v1 compat shims）。

这轮处理内容：

• OpencodeRequestHandler 不再接受缺省占位 agent_card，测试侧全部改为显式传入。
• 删除服务端 on_resubscribe_to_task() 内部别名，统一收敛到 on_subscribe_to_task()。
• 删除 _looks_like_legacy_message_payload() 和对应 REST legacy payload 探测分支；REST 仅对误发 JSON-RPC envelope 做专门提示，其余旧 shape 直接按 v1 parser 拒绝。
• A2AClient.send_message() / subscribe_to_task() 现在直接返回原生 StreamResponse，不再适配成仓库私有 tuple 事件；CLI、tool orchestration、payload text 和相关测试已同步到新语义。
• 文档与 transport contract 已改成 v1-only 口径。`

验证：

• ./scripts/doctor.sh passed
• 591 passed
• total coverage 91.11%

当前仍可见的只剩构建阶段 vcs_versioning 的 GlobalOverrides warning；这不是本轮迁移阻塞。

[liujuanjuan1984]

独立复审结论（对照 ~/a2a-python/docs/migrations/v1_0/README.md:64 与 :500）：

• 已确认主线迁移点完成：TaskState / Role 已统一使用 SCREAMING_SNAKE_CASE，Part 已统一使用 text/raw/url/data 直字段，create_client() 与 StreamResponse.HasField() 语义已在生产代码落地。
• 已再次扫过 src/ / tests/ / docs/，没有再发现 TextPart / FilePart / DataPart / ClientFactory / message/send / tasks/resubscribe / 0.3 协议别名这类旧协议兼容残留。
• 当前没有新的高置信迁移缺口；也没有发现还需要立即删除的旧版协议兼容壳。

剩余更像仓库自有抽象，而不是 v0.3 兼容残留：

• src/opencode_a2a/a2a_utils.py 仍维护了一层仓库自有 protobuf helper（如 make_text_part() / make_data_part() / part_text_fallback()），功能上已是 v1 语义，但尚未收敛到官方 a2a.helpers 统一入口。
• src/opencode_a2a/client/client.py 仍保留仓库级 facade 能力，例如 send() 的 polling fallback 与 auth/request-metadata 包装；这不是旧协议兼容，而是本仓库的 client DX 选择。
• src/opencode_a2a/server/state_store.py 等处的 legacy_* 命名，针对的是内部状态表/持久化数据迁移，不是 A2A wire protocol 兼容。

结论：A2A v1 迁移主线已完成；当前剩余的是仓库自有 helper / facade / 内部数据迁移命名，不应再归类为协议迁移缺口。

[liujuanjuan1984]

补充两点审查结论：

1. a2a_utils 当前不是一个纯“旧协议兼容层”，而是混合了三类职责：

   • protobuf 复制/替换/比较工具
   • Part 构造 helper
   • 输出协商时的结构化 -> 文本降级 helper

2. 从消费面看，当前最值得继续收敛的不是整包删除，而是把“简单构造”与“必要工具”分开：

   • 保留价值较高：clone_proto / proto_to_dict / proto_equals / replace_message_parts / replace_artifact_parts / replace_status_event_message / replace_artifact_event_artifact，这类是 protobuf 变换工具，官方 a2a.helpers 不覆盖。
   • 业务上合理：part_text_fallback() 与 make_data_part()，前者服务于 output negotiation 的 data -> text/plain 降级，后者服务于流式 structured payload 构造。
   • 明显偏薄壳：make_text_part() 当前在生产代码有 12 处调用，大多只是 Part(text=...) 的一层包裹；这类写法不比直接 protobuf 构造更清晰，也不比官方迁移建议更贴近 v1。
   • 高置信低价值残留：make_raw_part() / make_url_part() 当前无生产代码消费，只在测试中使用；replace_task_status_message() / replace_task_history() / replace_task_artifacts() / replace_task_metadata() 当前没有仓库消费。

另外，内部状态表旧行 TTL fallback 已拆出单独问题跟踪：#425。它与 A2A 协议升级解耦，不在当前 PR 内继续展开。

[liujuanjuan1984]

继续收敛完成，已提交并推送：b3b69c8 (refactor: remove low-value a2a part helpers)

这轮聚焦处理了上一轮审查里“最值得继续收敛”和“高置信低价值残留”的两类 helper：

• 生产代码不再通过 make_text_part() 这类薄壳构造简单文本 part，client / server / execution / jsonrpc / output_modes 主路径已直接改为 Part(text=...)。
• 删除 src/opencode_a2a/a2a_utils.py 中无生产价值的 helper：
  • 已删除：make_text_part()、make_raw_part()、make_url_part()
  • 已删除：part_is_text()、part_is_data()、part_is_file()
  • 已删除：part_data_to_python()
  • 已删除：replace_task_status_message()、replace_task_history()、replace_task_artifacts()、replace_task_metadata()
• 保留了仍有明确价值的 helper：protobuf clone/compare/dict 转换、make_data_part()、part_text_fallback()、以及 output negotiation 所需的 artifact/status 替换工具。
• 测试同步改为直接构造 Part(...) 或直接读取 protobuf data，不再要求生产模块继续为测试保留低价值 helper。

验证结果：

• ./scripts/doctor.sh passed
• 591 passed
• total coverage 91.37%
• 构建阶段仍会出现已接受的 vcs_versioning GlobalOverrides warning；处理策略不变，继续按上游 packaging warning 跟踪。

[liujuanjuan1984]

收尾审查已完成。

结论：

• 继续复核后，没有再发现可高置信删除的生产死代码；当前剩余低引用 helper 主要属于公开 API、pytest/autouse、protobuf 边界、SQLAlchemy 事件钩子或契约校验逻辑，不做盲删。
• PR refactor: finalize a2a v1-only migration cleanup #424 已更新标题与描述，现已按模块归纳完整覆盖本分支的 v1-only 收口、扩展协商收敛、文档同步、验证结果与 follow-up 边界。
• issue 关系已校正：PR 关闭本 issue，#425 仍保持范围外 follow-up；#427 到 #431 作为本分支内已单独关闭的后续收口项，仅保留关联说明，不再误写为新的 close 目标。