refactor(error): centralize upstream taxonomy and jsonrpc translators

[liujuanjuan1984]

• Closes [Priority: Med] [Enhancement] 引入中心化错误映射机制 (ErrorTranslator) #274

背景

#274 旨在收敛当前分散在多个出口的错误映射逻辑。当前主干在 client / tool 层已经有一部分中心化实现，但 jsonrpc/application.py 仍保留较多重复的 JSONRPCError(...) / InvalidParamsError(...) / InternalError(...) 组装逻辑，execution/upstream_errors.py 也仍维护独立的 upstream 状态码画像。

本 PR 按“共享 taxonomy + 分出口 translator”的方案落地收口，而不是再引入一个单体 ErrorTranslator。

本次改动

src/opencode_a2a/error_taxonomy.py

• 新增共享 upstream taxonomy
• 统一维护 upstream HTTP status -> canonical profile
• 统一维护 upstream response detail 提取逻辑

src/opencode_a2a/jsonrpc/error_mapping.py

• 新增 JSON-RPC error translator
• 收敛 unsupported method、session forbidden / not found、interrupt not found / expired、invalid params / internal error、upstream http / unreachable / payload mismatch 的构造逻辑

src/opencode_a2a/jsonrpc/application.py

• 将分散的 JSONRPCError(...) / InvalidParamsError(...) / InternalError(...) 组装接入 translator
• 保持现有 business code 与对外契约不变

src/opencode_a2a/execution/upstream_errors.py

• 改为复用共享 upstream taxonomy
• 删除重复维护的 upstream HTTP profile / detail 提取逻辑

tests/jsonrpc/test_error_mapping.py

• 新增 translator 单测
• 锁定 method unsupported、session / interrupt、upstream envelope、invalid params / internal error 的 contract

相关 commit

• 932e380 refactor(error): centralize upstream taxonomy and jsonrpc translators (#274)

验证

• uv run pre-commit run --all-files
• uv run pytest
• 348 passed
• coverage: 91.07%

[liujuanjuan1984]

本轮 PR 级审查结论：未发现阻塞问题。

判断：

• 改动方向合理，#274 的实现从“单体 ErrorTranslator”调整为“共享 taxonomy + 分出口 translator”，更符合当前代码结构。
• jsonrpc/application.py 的重复错误组装已明显收口，execution/upstream_errors.py 的 upstream profile 也不再单独维护。
• 回归覆盖合理：既有 JSON-RPC 集成测试仍在，新补的 translator 单测也把关键 contract 锁住了。

一个需要明确记录但不阻塞合并的点：

• 当前 jsonrpc 对外错误契约仍然刻意保留通用的 UPSTREAM_HTTP_ERROR / UPSTREAM_UNREACHABLE / UPSTREAM_PAYLOAD_ERROR。
• 共享 taxonomy 目前主要统一了内部分类和 stream-side 映射规则，而没有把 401/403/429 等 profile 直接暴露到现有 JSON-RPC business code 上。
• 这是兼容性取舍，不是实现缺陷；如果后续要让 metrics / logging 直接消费 canonical profile，可以在后续 PR 再继续接。

[liujuanjuan1984]

补了一轮死代码 / 薄壳清理，范围仅限本次 #274 新增的 JSON-RPC error mapping。

已收口：

• 删除 src/opencode_a2a/jsonrpc/error_mapping.py 中只做 str(exc) 转发的 invalid_params_exception_error
• 删除只做 InternalError(message=str(exc)) 包装的 internal_error
• 删除 upstream_http_error / upstream_unreachable_error / upstream_payload_error 上未被任何调用方使用的 message= 参数
• src/opencode_a2a/jsonrpc/application.py 改为在调用点直接构造对应 A2AError / InternalError
• 同步简化 tests/jsonrpc/test_error_mapping.py

说明：

• 这轮不改变对外 JSON-RPC error contract
• 只收掉新增模块里无语义增益的 helper / 参数入口

验证：

• uv run pre-commit run --all-files
• uv run pytest
• 348 passed，coverage 91.07%

[liujuanjuan1984]

继续收了一轮：

1. 命名收敛

• src/opencode_a2a/error_taxonomy.py -> src/opencode_a2a/upstream_taxonomy.py
• src/opencode_a2a/execution/upstream_errors.py -> src/opencode_a2a/execution/upstream_error_translator.py
• src/opencode_a2a/jsonrpc/error_mapping.py -> src/opencode_a2a/jsonrpc/error_responses.py
• tests/jsonrpc/test_error_mapping.py -> tests/jsonrpc/test_error_responses.py

2. 薄壳清理

• 删除新增 JSON-RPC error builder 中无语义增益的 helper / 参数入口

3. 结果

• 现在三层职责更明确：
  • taxonomy: upstream_taxonomy.py
  • execution translator: upstream_error_translator.py
  • jsonrpc response builder: error_responses.py

验证：

• uv run pre-commit run --all-files
• uv run pytest
• 348 passed，coverage 91.07%