[Priority: Med] [Feature] 暴露 OpenCode subagent/subtask/task tool 扩展能力

[liujuanjuan1984]

🔍 发现的问题 / 原始需求描述

上游 opencode 已经具备明确的 subagent / subtask / task tool 能力：内建 general、explore 等 subagent，会话执行过程中还会生成 subtask part，并通过 task tool 驱动子任务执行。当前 opencode-a2a 虽然能承接主聊天、session control 和 MCP/tool discovery，但并没有把“这个运行时具备子 agent 编排能力”作为独立 extension 对外声明，也没有给消费方稳定暴露 subtask/tool 执行语义、能力边界和机器可发现契约。

🛠️ 详细实施方案 (必须包含涉及的文件路径和核心逻辑/伪代码)

1. 新增 subagent/subtask 能力扩展声明。
   涉及文件：

• src/opencode_a2a/contracts/extensions.py
• src/opencode_a2a/server/agent_card.py
• src/opencode_a2a/profile/runtime.py
• docs/guide.md

建议新增一个 provider-private extension URI，例如：

• urn:opencode-a2a:subagent-orchestration/v1

建议声明内容至少包括：

• 支持 subagent / subtask 的运行时能力
• 是否支持并行 subtask
• 子任务是否复用同一 workspace / session 上下文
• task tool 的稳定语义字段，例如 subagent_type、description、command
• 与 shared stream hints 的关系

2. 让 Agent Card 和文档明确说明 subtask/tool 执行如何在流式事件中体现。
   涉及文件：

• src/opencode_a2a/server/agent_card.py
• docs/guide.md
• src/opencode_a2a/execution/stream_runtime.py

伪代码：

extension.params = {
  supported_agents: [...],
  execution_model: "subtask_via_task_tool",
  stream_metadata_fields: {
    subagent_type: "...",
    command: "...",
    status: "...",
  }
}

3. 评估是否需要补一个只读查询面，帮助客户端识别可用 subagent。
   涉及文件：

• src/opencode_a2a/contracts/extensions.py
• src/opencode_a2a/jsonrpc/dispatch.py
• src/opencode_a2a/jsonrpc/handlers/subagent_discovery.py (new)
• src/opencode_a2a/opencode_upstream_client.py

可选方法：

• opencode.subagents.list

实现上可先复用上游 /agent，再过滤出 mode=subagent 的 agent，避免和普通 agent 列表混淆。

4. 明确和现有 issue 的边界。
   涉及文件：

• docs/guide.md

建议本 issue 只解决“能力声明、发现、语义暴露”，不直接定义“客户端如何显式发起一个 subtask”请求契约；后者单独跟进，避免 discovery 和 invocation 混在同一个 issue 中。

🧪 回归测试建议

• 为 Agent Card / extension params 增加契约测试，验证 subagent orchestration extension 被正确声明。
• 为流式输出增加回归测试，确保 subtask / task tool 的关键字段可稳定观察。
• 如果新增 opencode.subagents.list，补齐成功、空列表、上游 payload mismatch、上游失败等 handler 测试。
• 运行 ./scripts/doctor.sh。

[liujuanjuan1984]

评估结论：该需求仍然合理、仍然有效，但 issue 范围需要收紧并拆阶段实施。

基于当前主干与上游 opencode 最新 dev 分支，我建议把 #338 定位为“能力声明 + 文档化 + 流式语义补齐”，不要和显式编排调用契约混做一件事。

原因：

• 当前仓库其实已经接受 subtask part，并会原样透传到 opencode.sessions.prompt_async。也就是说，底层承载能力并不是 0，而是“已有隐含支持，但没有正式声明为稳定 contract”。
• 当前 issue body 里“可选复用上游 /agent 做 opencode.subagents.list”这个建议，按最新上游代码已经不成立。上游当前公开 route 里没有稳定的 /agent 发现接口；如果强做本地 discovery，反而容易做出不稳定、与上游不对齐的私有面。
• 当前主干的最佳实践已经是：每类扩展一个独立 handler / contract / Agent Card / OpenAPI / guide，同类能力优先走只读 discovery 或声明式 contract，再逐步放出更强能力。#338 也应遵循这个节奏。

建议拆成 3 个实施步骤：

1. 第一步：正式声明现有 subtask 能力。
   • 目标：在 extensions.py、agent_card.py、openapi.py、docs/guide.md 中，把“opencode.sessions.prompt_async 支持 subtask part”写成正式 contract，而不是仅停留在 validator 支持。
   • 同步补测试：contract consistency、Agent Card、OpenAPI example、docs example、prompt_async 参数校验回归。
2. 第二步：补齐流式观察语义。
   • 目标：明确 task tool / subtask 在流式输出中哪些字段是稳定可消费的，哪些只是 passthrough；必要时在 stream_events.py / stream_runtime.py 中补充更稳定的 metadata 映射。
   • 这一阶段仍然不新增 invocation API。
3. 第三步：再评估是否需要 subagent discovery。
   • 前提：上游存在稳定发现面，或者我们能明确接受“基于本地静态配置推导”的 provider-private 语义。
   • 在这个前提没满足之前，不建议把 opencode.subagents.list 放进本 issue 的第一阶段。

相关 issue 关系：

• #339 与本 issue 高度相关，但不建议同分支一起做。#338 应先把“声明/发现/流式语义”收敛，再决定 #339 是否还需要独立的新调用契约。
• #336 有一定相关性，因为 tool catalog discovery 会帮助客户端理解 orchestration 能力边界，但不建议和本 issue 同分支混做。
• #332、#166 是后续更强 orchestration 能力的重要约束，但不是本 issue 第一阶段的并行开发项。

结论：

• 需要拆分实施步骤。
• 第一阶段可以直接做，而且范围不应扩大到新的 invocation API 或不稳定 discovery。
• 不建议把其它 open issues 与 #338 在同一分支一并开发。

[liujuanjuan1984]

补充说明：我将按上面的评估从本 issue 第一阶段直接开始实现，范围限定为：

• 正式声明 opencode.sessions.prompt_async 对 subtask part 的支持；
• 在 Agent Card / OpenAPI / guide 中把这条能力写成稳定 contract；
• 补齐与 task tool / 流式可观察字段相关的测试；
• 不在本阶段新增独立 subagents.list 或新的 invocation API。

实现完成后会把回归结果和 PR/提交信息再同步回本 issue。

[liujuanjuan1984]

实现完成，第一阶段已落地：

• 新增 provider-private subtask capability extension，正式声明 opencode.sessions.prompt_async 对 request.parts[].type=subtask 的支持；
• 在 Agent Card / OpenAPI / guide 中补齐 subtask 输入契约与 task tool 流式观察语义；
• 补齐 contract consistency、Agent Card、stream tool payload 相关回归测试。

回归结果：

• ./scripts/doctor.sh ✅
• 419 tests passed
• coverage 91.98%

本阶段未做：

• 未新增独立 subagents.list discovery；
• 未新增新的 invocation API；
• 未声明批量/并行 subtask 提交契约。

下一步我会继续推进 #339 的第一版显式 orchestration contract，优先复用现有 prompt_async + subtask part 路径，而不是先引入新方法。

[liujuanjuan1984]

补充评估：如果希望把本 issue 按“完全实施完成”来理解，当前还存在两个遗留缺口。

1. subagent discovery 仍未落地。

• 当前实现已经完成能力声明、Agent Card/OpenAPI/guide、以及 task tool 的流式可观察语义。
• 但尚未提供单独的 subagent discovery 能力。
• 这里的核心问题不是“忘了做”，而是上游最新 opencode 当前没有稳定公开的 /agent 发现 route，因此本仓库暂时没有合适的上游稳定面可以直接映射。
• 如果后续一定要补 discovery，需要先决定：
  • 是接受“基于本地静态配置/约定推导”的 provider-private 语义；
  • 还是等待上游出现稳定 discovery 面后再对齐。

2. 流式语义目前是“稳定字段声明”，不是更高层专用事件模型。

• 现在已经正式声明了 task tool 相关的稳定观察字段；
• 但没有再抽象成独立的 subtask 专用事件或更强的标准化 envelope。
• 是否需要更高层的抽象，还要看下游消费方是否真的需要脱离 tool_call block 去消费。

建议：

• 如果接受本 issue 已收敛为“能力声明/语义暴露/文档化”，我认为它已经可以进入收尾态；
• 如果坚持补足 discovery，则更适合作为后续独立子项继续跟进，而不是继续扩大本 issue 的边界。