Clarify result and extension contract semantics

[liujuanjuan1984]

背景

Closes #481
Closes #484

本 PR 覆盖两个相邻的协议语义收敛点：non-stream success 的结果/status 分层，以及 opencode-a2a extension URI 的 canonical identifier 收敛。本轮收尾同时完成了当前分支内的高置信死代码/薄壳清理。

变更

• 将 successful non-streaming message:send 的完整 assistant result 固定在 Task.artifacts。
• 保留 terminal Task.status.message，但仅写入简短状态 Completed.，不再复制完整正文。
• 调整客户端 extract_text(Task) 的读取优先级，优先读取 artifact result，避免短状态文本遮蔽真实结果。
• 移除 extension URI path 中的 shared / private 占位层，收敛为 urn:opencode-a2a:extension:<contract>:v1。
• 保持 metadata.shared.* payload namespace 不变；provider-private metadata 继续使用 metadata.opencode.*，URI path 不再承载 auth/disclosure 语义。
• 在 OpenAPI x-a2a-extension-contracts 中补充 public extension 的 canonical extension_uri 字段。
• 删除两个无 contract 价值的薄壳 helper：identifiers._extension_uri 与 openapi._with_extension_uri，改用显式 URI 常量和 inline contract dict。
• 更新 extension spec、guide 与 contract consistency tests，固定新 URI 列表并防止旧 :shared: / :private: URI 回流。

Issue 关系

• [TechDebt] 评估 non-stream success 中 status.message 与 artifact 的语义重复 #481：本 PR 直接解决 non-stream success 中 status.message 与 artifact 重复承载问题。
• [chore] 移除 extension URI 中的 shared/private 语义层 #484：本 PR 直接解决 extension URI 中 shared / private 语义层移除问题。
• 本轮薄壳清理是 [chore] 移除 extension URI 中的 shared/private 语义层 #484 变更后的同分支维护清理，按本次要求不单独新建 issue。
• [Priority: Med] [Enhancement] 明确 push config persistence 与能力恢复的分层方案 #451：聚焦 push notification config persistence / capability 分层，与本 PR 两项语义收敛无直接耦合，不纳入本次范围。
• 下游适配跟踪：[Refactor] 适配上游移除 extension URI shared/private 层 liujuanjuan1984/a2a-client-hub#913。

审查结论

• [TechDebt] 评估 non-stream success 中 status.message 与 artifact 的语义重复 #481 采用兼容性较稳的方案 B：保留短状态文本，完整结果只走 artifact。
• [chore] 移除 extension URI 中的 shared/private 语义层 #484 不保留旧 URI alias，避免长期双轨识别；这是有意的 canonical contract change。
• Agent Card、extended Agent Card、OpenAPI metadata、compatibility profile 与 wire contract 均从同一个 URI SSOT 派生。
• 死代码审查未发现可安全删除的大块全仓死代码；本次仅清理两个高置信薄壳，避免误删协议接口、路由 handler、SDK 适配、fixtures 或兼容性测试。

验证

• uv run pytest --no-cov tests/contracts/test_extension_contract_consistency.py tests/server/test_agent_card.py tests/server/test_transport_contract.py 已通过：105 passed。
• ./scripts/doctor.sh 已通过：mypy、690 个 pytest、覆盖率门槛、package build、built-wheel smoke test。

[liujuanjuan1984]

代码变动独立审查结果：

• 未发现阻塞性问题。Task.artifacts 作为 successful non-streaming completion 的 canonical result carrier，Task.status.message 收敛为 Completed.，与 [TechDebt] 评估 non-stream success 中 status.message 与 artifact 的语义重复 #481 想解决的重复承载和语义边界问题一致。
• 客户端 extract_text(Task) 同步改为优先读取 artifacts，再回退到 message/status，避免本仓库消费侧把短 completion status 当成最终回答；这部分变更与服务端语义调整匹配。
• 测试覆盖了 fallback message id、tool loop、non-stream completed task、以及 artifact 优先提取，能够固定本次选择的语义。
• 文档已明确 Task.artifacts 是 successful non-streaming result text 的 canonical carrier，Task.status.message 不再复制全文。

风险评估：

• 主要兼容性风险是外部旧客户端若只读取 Task.status.message，将只能看到 Completed.。这是 [TechDebt] 评估 non-stream success 中 status.message 与 artifact 的语义重复 #481 需要消除的语义重复带来的预期取舍；PR 已通过文档和本仓库客户端逻辑降低新实现侧风险。
• 未发现冗余实现或与当前代码实践冲突的地方。

PR 文案与 issue 关系审查：

• PR 标题 Clarify non-stream success result semantics 符合英文 commit message 风格。
• PR 描述使用中文，已关联 Closes #481，关系准确。
• 当前另一个 open issue [Priority: Med] [Enhancement] 明确 push config persistence 与能力恢复的分层方案 #451 与本 PR 无直接耦合，不应标记 related 或 closes。

验证：

• ./scripts/doctor.sh 已通过。

[liujuanjuan1984]

追加 #484 后的 PR 代码变动审查结果：

• 未发现阻塞性问题。URI SSOT 位于 contracts.extensions.identifiers，Agent Card、extended Agent Card、compatibility profile、wire contract 与 negotiation 逻辑都继续通过常量派生，因此 canonical URI 收敛不会产生多处手写漂移。
• metadata.shared.* payload namespace 未被修改，符合 [chore] 移除 extension URI 中的 shared/private 语义层 #484 的设计原则；本次只移除 extension URI path 中的 shared / private 语义层。
• OpenAPI x-a2a-extension-contracts 增加 extension_uri 字段是合理的，因为它让匿名 OpenAPI metadata 也明确暴露新 canonical URI；该新增字段为 additive，不重排既有 contract params 结构。
• Contract consistency tests 现在固定新 URI 列表，并检查 spec index 不再包含旧 urn:opencode-a2a:extension:shared: / private: URI。

风险评估：

• 这是 canonical identifier 变更，未保留旧 URI alias。风险主要在下游客户端需要同步更新 negotiated extension constants；[chore] 移除 extension URI 中的 shared/private 语义层 #484 已链接 downstream 适配 issue [Refactor] 适配上游移除 extension URI shared/private 层 liujuanjuan1984/a2a-client-hub#913，本 PR 描述也已保留该跟踪项。
• 未发现误改 metadata.shared.*、auth/disclosure policy 或 provider-private method behavior 的问题。

PR 文案与 issue 关系审查：

• PR 标题已更新为 Clarify result and extension URI semantics，符合英文 commit message 风格，并能覆盖 [TechDebt] 评估 non-stream success 中 status.message 与 artifact 的语义重复 #481 与 [chore] 移除 extension URI 中的 shared/private 语义层 #484 两项变更。
• PR 描述已增加 Closes #484；当前 Closes #481 与 Closes #484 均准确。
• [Priority: Med] [Enhancement] 明确 push config persistence 与能力恢复的分层方案 #451 仍不应标记 related/closes；它属于 push notification config 分层问题。

验证：

• uv run pytest --no-cov tests/contracts/test_extension_contract_consistency.py tests/server/test_agent_card.py tests/server/test_transport_contract.py 已通过。
• ./scripts/doctor.sh 已通过。

[liujuanjuan1984]

自审结果

代码变动审查

本 PR 当前包含三个提交：

• 45b183c Clarify non-stream success result semantics (#481)
• 4988ea7 Flatten extension URI identifiers (#484)
• 8a3686e Remove extension URI helper shells (#484)

审查结论：改动方向合理，且与 #481 / #484 的需求匹配。

• [TechDebt] 评估 non-stream success 中 status.message 与 artifact 的语义重复 #481 的实现将 successful non-streaming message:send 的完整 assistant result 固定在 Task.artifacts，terminal Task.status.message 只保留短状态 Completed.。这避免了同一结果在 status 与 artifact 中重复承载，也让客户端 extract_text(Task) 优先读取 artifact，语义更稳定。
• [chore] 移除 extension URI 中的 shared/private 语义层 #484 的实现将 extension URI 收敛到 urn:opencode-a2a:extension:<contract>:v1，不保留旧 :shared: / :private: alias。这个选择会带来有意的 canonical contract change，但可以避免长期双轨识别和新旧 URI 同时存在导致的契约漂移。
• OpenAPI x-a2a-extension-contracts 补充 extension_uri 后，Agent Card / extended Agent Card / OpenAPI / compatibility profile / wire contract 能从同一组 URI 常量派生，避免文档与运行时 contract 脱节。
• 本轮死代码审查没有发现可安全删除的大块全仓死代码；薄壳检测结果中大量对象属于协议接口、路由 handler、SDK 适配、fixtures 或兼容测试，不能仅凭“薄”判断删除。本次只清理两个高置信薄壳：identifiers._extension_uri 与 openapi._with_extension_uri。

风险与遗漏

• [TechDebt] 评估 non-stream success 中 status.message 与 artifact 的语义重复 #481 的行为变化要求消费者从 artifact 读取完整 non-stream result；PR 已同步 guide，并通过客户端 extract_text(Task) 降低调用侧误读短状态文本的风险。
• [chore] 移除 extension URI 中的 shared/private 语义层 #484 不保留旧 URI alias 是有意选择；风险主要在外部消费者仍写死旧 URI。PR 已通过文档、tests 和 OpenAPI metadata 明确新 canonical URI，下游适配由 [Refactor] 适配上游移除 extension URI shared/private 层 liujuanjuan1984/a2a-client-hub#913 跟踪。
• metadata.shared.* payload namespace 保留不变是合理的：它描述 payload 可共享字段，不再与 extension URI 的 disclosure/auth 语义耦合；provider-private metadata 继续使用 metadata.opencode.*，没有引入 metadata.private.* 或 metadata.privated.*。
• 未发现与 [Priority: Med] [Enhancement] 明确 push config persistence 与能力恢复的分层方案 #451 的直接耦合；[Priority: Med] [Enhancement] 明确 push config persistence 与能力恢复的分层方案 #451 聚焦 push notification config persistence / capability 分层，不应由本 PR 关闭或标记为 related。

Issue 关系审查

• Closes #481 准确。
• Closes #484 准确。
• 本轮薄壳清理是 [chore] 移除 extension URI 中的 shared/private 语义层 #484 变更后的同分支维护清理，按本次要求未新建 issue。
• 下游适配关系保留为 [Refactor] 适配上游移除 extension URI shared/private 层 liujuanjuan1984/a2a-client-hub#913。

验证

• uv run pytest --no-cov tests/contracts/test_extension_contract_consistency.py tests/server/test_agent_card.py tests/server/test_transport_contract.py：105 passed。
• ./scripts/doctor.sh：通过，包含 mypy、690 个 pytest、覆盖率门槛、package build、built-wheel smoke test。