[chore] A2A v1.0 extensions 最佳实践收敛伞计划

[liujuanjuan1984]

背景

当前仓库已经明确从 A2A 0.3 升级到 1.0，且该升级视为 breaking change。

本仓库后续不再为 0.3 保留兼容胶水、过渡包装或双轨 contract。旧版本可通过 release/tag 继续服务既有使用者；main 上的新版本应直接按照 A2A 1.0 的最佳实践收敛 extensions 设计、声明、发现、协商与披露模型。

当前仓库在 extensions 方向的一个关键问题是：虽然已经建立了较完整的 extension contract 体系，但 extension identity 仍然强绑定到 GitHub blob/main 文档地址，且 public Agent Card 对 provider-private/operator-sensitive capability 的公开面仍然偏大。这些做法可以工作，但不适合作为 A2A 1.0 长期稳定形态。

参考伞 issue：

• Hub 消费侧 A2A v1.0 与 extensions 协商化改造伞计划 liujuanjuan1984/a2a-client-hub#873

官方参考：

• https://a2a-protocol.org/latest/topics/extensions/
• https://a2a-protocol.org/latest/topics/agent-discovery/
• https://a2a-protocol.org/latest/topics/extension-and-binding-governance/
• https://a2a-protocol.org/latest/specification/

总体原则

• 以 A2A 1.0 当前官方文档为最佳实践基线，而不是继续沿用 0.3 时代的过渡设计。
• 不再考虑 0.3 兼容；不新增任何过渡性 alias、双写、双读或兼容解释层。
• 保留“通过 Agent Card 声明 extensions”的标准路径，不把 extensions 退化成仅靠 README/OpenAPI 才能发现的私有 contract。
• 将 extension identity 与源码仓库路径解耦，避免把协议标识长期绑定到 GitHub blob/main。
• 保持 public Agent Card 最小披露；更详细或更敏感的 provider-private contract 走 authenticated extended card。
• breaking change 允许直接改到位，不为旧 consumer 保留额外负担。

本仓库需要解决的核心问题

1. extension identity 不应绑定 GitHub 文档页面

当前 extension URI 直接使用 GitHub blob/main 文档地址。该方案存在以下问题：

• 协议 identity 与源码托管路径强耦合
• 仓库改名、迁移、私有镜像、文档重构都会影响 contract 稳定性
• deployer 无法在不暴露源码仓库地址的前提下复用同一能力模型
• 不符合“稳定 URI / permanent identifier”方向

目标方向：

• 使用稳定的、可长期治理的 extension URI
• 优先考虑可控 HTTPS 命名空间或 permanent identifier（如 w3id 风格）
• 如需保留 GitHub 文档，仅作为 spec 承载页，不再作为 extension identity 本身

2. public Agent Card 与 authenticated extended card 的披露边界需要重新收敛

当前 public Agent Card 虽然已经做了参数瘦身，但仍然直接公开了较多 provider-private/operator-sensitive extension capability。

目标方向：

• public Agent Card 仅保留低敏、共享、基础 discoverability 所需的 extension 声明
• provider-private、operator-scoped、deployment-conditional extension 改为在 authenticated extended card 中声明详细能力
• 不再让 anonymous discovery 默认暴露过厚的私有 control-plane capability 面

3. extension 规范页面与标准协商路径需要对齐

目标方向：

• extension specification 明确回答：identity、versioning、params schema、activation、dependencies、security、披露边界
• 对请求级协商路径进行统一梳理，确保声明、请求、响应回显、运行时行为一致
• 避免“文档是一个体系、Agent Card 是一个体系、OpenAPI 又是另一个体系”的漂移

建议拆分阶段

阶段 0：定 A2A 1.0 extension 最佳实践基线

需要产出：

• 本仓库的 extension URI 命名与稳定性原则
• public vs authenticated extended card 的披露分层规则
• provider-private / shared / deployment-conditional 的分类规则
• extension specification 的规范模板

阶段 1：重做 extension identity 与文档托管边界

需要落地：

• 从 GitHub blob/main URI 迁移到稳定 extension URI
• 定义旧 URI 是否完全移除，还是仅在 release 线保留历史实现
• 同步更新 Agent Card、authenticated extended card、OpenAPI、测试与文档

阶段 2：重构 card 披露面与标准声明路径

需要落地：

• 重新审查哪些 extension 应出现在 public Agent Card
• 重新审查哪些 extension 仅应在 authenticated extended card 声明详细 contract
• 保持“extension 通过 Agent Card 声明”的主路径，不退化为仅靠 OpenAPI 暴露

阶段 3：统一 request-scoped negotiation 与 contract 一致性

需要落地：

• 审查 A2A-Extensions / request-scoped activation 的运行时行为
• 对齐 Agent Card、OpenAPI、运行时响应头、错误处理与文档描述
• 清理旧有兼容思维下残留的 envelope / family / taxonomy 假设

建议拆分子任务

• 定义本仓库 A2A 1.0 extension 最佳实践基线
• 设计稳定 extension URI 命名空间与 versioning 规则
• 从 GitHub blob/main identity 迁移到稳定 URI
• 重定义 public Agent Card 与 authenticated extended card 的 extension 披露边界
• 重新审查 provider-private/operator-scoped extension 的公开策略
• 对齐 extension specification、Agent Card、OpenAPI、运行时协商头与测试
• 清理 0.3 时代遗留的兼容假设与过渡性约束

验收标准

• 新版本不再依赖 GitHub blob/main 文档地址作为 extension identity。
• extension URI、spec、Agent Card、OpenAPI、运行时协商行为在 A2A 1.0 语义下自洽。
• public Agent Card 的披露面收缩到最小必要 discoverability。
• 更详细或更敏感的 provider-private contract 通过 authenticated extended card 暴露。
• 仓库对 0.3 不再保留额外兼容设计负担。

[liujuanjuan1984]

基于当前代码现状，建议按以下顺序推进 #435：

1. 先定目标矩阵，不急着写代码。
   当前需要先统一三件事：

• extension identity 不再绑定 GitHub blob/main 文档 URL
• public Agent Card 收缩到最小 discoverability 面，不再默认公开 provider-private/operator-scoped extension 能力
• OpenAPI 与 authenticated extended card 对齐新的披露边界，避免匿名发现面仍然过厚

2. 重做 extension URI SSOT。
   修改 src/opencode_a2a/contracts/extensions.py，把当前基于 docs/extension-specifications.md#... 的 URI 生成逻辑替换为显式稳定 URI 常量，实现 identity 与 spec 页面解耦。

3. 收缩 public Agent Card。
   修改 src/opencode_a2a/server/agent_card.py，不再采用“public 仅去掉 params、但仍声明全部 extension”的做法。
   建议 public 仅保留低敏 shared extension：

• session binding
• model selection
• stream hints
• interactive interrupt callback
  其余 provider-private / operator-scoped / deployment-conditional extension 仅放入 authenticated extended card。

4. 对齐 OpenAPI 披露边界。
   修改 src/opencode_a2a/server/openapi.py，决定 OpenAPI 是否继续匿名公开 provider-private extension。建议与 public Agent Card 一致收口，避免把匿名披露面从 Agent Card 转移到 OpenAPI。

5. 统一 request-scoped negotiation 与运行时行为。
   核对 extension_negotiation.py、rest_tasks.py、execution/executor.py，确保 A2A-Extensions 协商、运行时 metadata 过滤、声明文档三者一致。

6. 重写 extension 文档边界。
   更新 docs/extension-specifications.md、docs/guide.md、docs/compatibility.md，让每个 extension 都明确：identity、versioning、activation、params schema、dependencies、security boundary、public vs extended disclosure。

7. 更新测试为新边界，而不是修补旧断言。
   重点更新：

• tests/server/test_agent_card.py
• tests/server/test_transport_contract.py
• tests/contracts/test_extension_contract_consistency.py
  需要移除两类脆弱断言：
• 依赖 GitHub blob/main URI 前缀
• 依赖 extension 列表固定顺序

8. 最后验证。
   建议先跑定向测试，再跑仓库基线：

• uv run pytest tests/server/test_agent_card.py tests/server/test_transport_contract.py tests/contracts/test_extension_contract_consistency.py
• bash ./scripts/doctor.sh

第 1 步目标矩阵建议如下：

Surface	Public Agent Card	Authenticated Extended Card	OpenAPI
Shared session binding	保留最小声明	保留完整 contract	保留最小匿名说明，详细 contract 走 extended card
Shared model selection	保留最小声明	保留完整 contract	保留最小匿名说明，详细 contract 走 extended card
Shared stream hints	保留最小声明	保留完整 contract	保留最小匿名说明，详细 contract 走 extended card
Shared interrupt callback	保留最小声明	保留完整 contract	保留最小匿名说明，详细 contract 走 extended card
OpenCode session management	不公开	公开完整 contract	不做匿名 contract 展开
OpenCode provider discovery	不公开	公开完整 contract	不做匿名 contract 展开
OpenCode workspace control	不公开	公开完整 contract	不做匿名 contract 展开
OpenCode interrupt recovery	不公开	公开完整 contract	不做匿名 contract 展开
Compatibility profile	不公开	公开完整 contract	不做匿名 contract 展开
Wire contract	不公开	公开完整 contract	不做匿名 contract 展开

下一步会先按这张矩阵调整 SSOT 和 Agent Card/OpenAPI 边界，再更新文档与测试。

[liujuanjuan1984]

基于当前 a2a-sdk==1.0.2 与最新 A2A 1.0 文档复查，当前 #435 还有 3 个需要收口的点：

1. 运行时仍未回显激活成功的 A2A-Extensions 响应头。

• 请求侧已要求显式协商，payload 侧也已按请求扩展做过滤，但当前成功响应没有把最终激活的 extension URI 集合写回响应头。
• 这与最新 extensions 文档里的“激活成功后响应 SHOULD include A2A-Extensions”仍有差距。

2. 文档对 latest SDK 的 extended-card 字段解释仍有漂移。

• 当前仓库锁定 a2a-sdk==1.0.2，实际能力字段在 capabilities.extendedAgentCard。
• 但仓库文档里仍保留了 top-level supportsAuthenticatedExtendedCard 的旧表述，需要收敛到 latest SDK / spec 语义。

3. extension identity 虽已脱离 GitHub blob/main，但还没有收敛到“可解析、可托管 spec 的稳定 HTTPS URI”。

• 当前使用 urn:a2a:opencode-a2a:* 已经解决了与源码托管路径耦合的问题。
• 但若按 latest 文档的 discoverability / publication guidance，extension URI 最终仍应优先收敛到稳定、可解析的 HTTPS 命名空间，而不是只停留在 URN。

接下来会按这个顺序收口：

• 补 A2A-Extensions 成功响应回显与测试
• 修 latest SDK 文档字段与扩展卡路径说明
• 将 extension URI 从当前 URN 收敛到稳定 HTTPS 命名空间，并同步 Agent Card / extended card / OpenAPI / 文档 / 测试

[liujuanjuan1984]

已在当前分支完成并推送本轮收口，commit：307ec2e（fix: align extension negotiation and spec URIs (#435)）。

这次把前面复查出来的 3 条缺口一起收掉了：

1. A2A-Extensions 响应头回显已补齐。

   • 成功的 REST / JSON-RPC 响应现在会按已激活扩展回显 A2A-Extensions。
   • public/shared 路径按公开共享扩展回显；provider-private JSON-RPC extension method 会回显对应私有扩展 URI。

2. latest A2A v1.0 SDK / spec 的 extended card 字段与路径语义已对齐。

   • 文档里残留的顶层 supportsAuthenticatedExtendedCard 已清掉，统一改为 AgentCard.capabilities.extendedAgentCard。
   • canonical HTTP 路径已切到 GET /extendedAgentCard。
   • 旧路径 /agent/authenticatedExtendedCard 保留为兼容别名，避免已有客户端直接断掉。
   • SDK-owned method 名称说明也统一改为 GetExtendedAgentCard。

3. extension URI 已从不可解析的 URN 收口到仓库自管的可解析 HTTPS 规范文档。

   • contracts/extensions.py 里的 extension identity 现在直接指向 docs/extensions/** 下的独立 spec 文档。
   • 新增 shared/private 各 extension 的独立规范文件，而不是继续把所有 identity 只压在一个索引页里。
   • 新增 MANIFEST.in，确保这些规范文档会进入 sdist，避免“仓库里有、发布包里没带上”的分发漂移。

补充：顺手把 guide 里残留的旧 message.content 示例改回了 v1 的 message.parts。

验证：

• 定向测试通过：
  • uv run pytest --no-cov tests/server/test_transport_contract.py tests/server/test_agent_card.py tests/contracts/test_extension_contract_consistency.py tests/client/test_agent_card.py
• 仓库基线通过：
  • bash ./scripts/doctor.sh
• 额外做了轻量构建校验，确认 docs/extensions/** 已进入 sdist。