refactor: finalize a2a v1 extension convergence

[liujuanjuan1984]

Closes #435

变更概览

本 PR 完成仓库在 A2A v1.0 extension 方向的收敛：稳定 extension identity、最小化 public discovery surface、统一 authenticated extended card 与匿名 OpenAPI 的披露边界，并对齐运行时协商、文档与测试。

contracts

• 将 extension identity 从 GitHub main 文档路径切回版本化永久 URN 命名空间。
• 为每个 extension 增加显式 spec 文档映射，避免继续依赖 URI 前缀反推本地文档路径。
• 更新 wire contract，仅保留 canonical GET /extendedAgentCard。

server

• 保持 public Agent Card 仅暴露 shared extension 与最小公开 skill。
• 保持 provider-private contract 只进入 authenticated extended card。
• 匿名 OpenAPI 继续只保留 shared 最小披露面，不回退到 provider-private method matrix 展开。
• 在 REST / JSON-RPC 成功响应中回显激活后的 A2A-Extensions。
• 移除 legacy /agent/authenticatedExtendedCard alias，仅保留 canonical /extendedAgentCard。

client

• 收紧 Agent Card URL 归一化逻辑，只识别 canonical public / extended card path。

docs

• 重写 docs/extension-specifications.md，明确“稳定 URI 与 GitHub 文档承载路径解耦”。
• 同步 docs/extensions/** 中每个 extension 的 canonical URI 到新 URN。
• 修正 docs/guide.md、docs/compatibility.md 的 extended card、OpenAPI 披露边界与 compatibility 叙事漂移。

tests

• 更新 extension contract consistency 测试，改为校验永久 URN 命名空间与显式 spec 映射。
• 删除 legacy extended-card alias 相关测试覆盖，只保留 canonical path 断言。
• 保持 Agent Card、transport contract、client resolver 等核心回归验证。

验证

• 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

[liujuanjuan1984]

独立审查结果：

1. 高优先级：extension identity 仍然绑定 GitHub main 路径，#435 的“稳定 URI / permanent identifier”目标没有完全落地。

• src/opencode_a2a/contracts/extensions.py:28-35 直接把 base URI 固定为 https://raw.githubusercontent.com/Intelligent-Internet/opencode-a2a/main/docs/extensions
• docs/extension-specifications.md:3-5,32-41 与 tests/contracts/test_extension_contract_consistency.py:89-110 又把这种绑定进一步固化成文档和测试约束
• 这只是把 identity 从 blob/main 挪到了 raw/main。仓库改名、迁移、默认分支调整、文档路径重排，仍然会直接改变 extension identity
• 如果 #435 的目标是“将 GitHub 文档仅作为 spec 承载页，不再作为协议标识本身”，这里还差最后一步

2. 高优先级：PR 新增 legacy extended-card alias，与 #435 明确写的“不新增任何过渡性 alias、双写、双读或兼容解释层”相冲突。

• src/opencode_a2a/a2a_protocol.py:7-12 新增 LEGACY_EXTENDED_AGENT_CARD_PATH
• src/opencode_a2a/server/application.py:982-992 同时注册 canonical 与 legacy HTTP path
• src/opencode_a2a/client/agent_card.py:27-40 和 tests/server/test_transport_contract.py:818-820 继续把 legacy path 当作正式兼容面维护
• docs/extension-specifications.md:24-26、docs/guide.md:12,74 也把这个 alias 文档化了
• 如果本任务就是 A2A v1.0 最佳实践收敛，这里更像是在继续扩大兼容面，而不是收口

3. 中优先级：文档对 OpenAPI 披露边界还有一处表述漂移，容易把后续实现再带回匿名厚披露。

• docs/compatibility.md:95 仍写着 Detailed extension params belong in the authenticated extended card and OpenAPI
• 但本 PR 在 src/opencode_a2a/server/openapi.py 的实际方向是 anonymous OpenAPI 只保留 shared 最小披露面
• 这里的文档表述建议收紧，否则之后很容易再次把 provider-private contract 塞回匿名 OpenAPI

结论：

• 当前 PR 的主方向是合理的，public/extended disclosure 分层、A2A-Extensions 回显、SDK 字段对齐等改动都有价值
• 但按 #435 自己定义的目标来看，identity 稳定性和 compatibility 收口还没有完全到位
• 基于这个判断，PR 目前使用 Related #435 比 Closes #435 更准确

[liujuanjuan1984]

复审结果更新：

• 未发现新的阻断性问题。
• 之前指出的 3 个偏差已经在 6f0c299 收口完成。

已收口项：

• extension identity 不再绑定 GitHub main 文档路径，已切回版本化永久 URN；GitHub 文档现在只是当前仓库中的规范承载页，不再承担协议 identity。
• legacy /agent/authenticatedExtendedCard alias 已从 server、client、docs、tests 全链路移除，只保留 canonical /extendedAgentCard。
• docs/compatibility.md 中关于 OpenAPI 披露边界的漂移已修正，匿名 OpenAPI 与 public Agent Card 现在都保持 shared 最小披露面叙事。

结论：

• 当前 PR 与 #435 的关系可以从 Related 调整为 Closes。
• 这次实现已经把 issue 里要求的“稳定 identity、最小 public 披露、去兼容 alias、统一 discovery/negotiation/doc/test”主目标收口到位。

剩余说明：

• 如果后续仓库要再进一步贴近官方“规范文档直接托管在 extension URI 本身”的推荐形态，可以在具备自有稳定 HTTPS 命名空间或 w3id 之后，再为这些 URN 增补额外 HTTPS 标识；这不再阻塞 #435 当前要解决的问题。