[Priority: Low] [Docs/Architecture] 记录 A2A、subtask、subagent 与 task tool 的拓扑关系

[liujuanjuan1984]

背景

当前关于 A2A Task、OpenCode subtask、task tool、subagent 之间的关系，存在明显概念重叠和命名歧义，尤其在讨论 #338 / #339 时容易混淆：

• A2A Task 是协议层追踪对象；
• subtask 是 OpenCode 输入 part；
• task tool 是 OpenCode 内部执行子任务的工具；
• subagent 才是真正被调起来干活的 agent。

如果没有一份明确的拓扑图和术语说明，后续继续设计 orchestration contract、workspace/worktree 绑定、授权边界时会不断重复解释，影响 issue/PR 讨论效率。

建议记录内容

建议在仓库文档或设计说明里补一份拓扑图，至少说明以下关系：

Human / Client
    |
    |  A2A core methods / JSON-RPC extensions
    v
opencode-a2a
    |
    |  session binding / identity / directory boundary
    v
OpenCode session
    |
    |  request.parts[]
    |  - text
    |  - file
    |  - agent
    |  - subtask
    v
OpenCode prompt runtime
    |
    |  subtask -> task tool execute
    v
task tool
    |
    |  input: prompt / description / subagent_type / command
    v
subagent
    |
    v
tool result / tool part
    |
    v
OpenCode stream events
    |
    v
opencode-a2a streaming adapter
    |
    v
Client sees A2A Task updates

并明确以下术语区分：

• A2A Task：A2A 协议层执行单元
• subtask：OpenCode provider-private 输入 part
• task tool：OpenCode 内部用于执行 subtask 的 tool
• subagent：真正执行子任务的 agent

期望行为

• 后续讨论 #338 / #339 / #332 / #166 时，可以统一引用这份拓扑说明；
• 减少“task 到底指哪个 task”的歧义；
• 为后续批量/并行 subtask、workspace 绑定、授权边界讨论提供统一语义基线。

验收标准

• 新增一份英文落库文档或 guide/design section，记录上述拓扑图与术语说明
• 文档明确说明 subtask / task tool / subagent / A2A Task 的区别
• 文档明确说明 A2A 层与 OpenCode runtime 层之间的映射关系
• 在相关 issue/PR 讨论中可直接引用该文档

关联

• Related [Priority: Med] [Feature] 暴露 OpenCode subagent/subtask/task tool 扩展能力 #338
• Related [Priority: Med] [Feature] 设计 A2A 显式子 agent 编排与并行 subtask 契约 #339
• Related [Priority: High] [Feature] 暴露 OpenCode project/workspace/worktree 控制面 #332
• Related [Priority: Med] [Security] 设计单租户实例内认证与授权模型 #166

[liujuanjuan1984]

补充说明：subtask -> task tool -> subagent 这条链路当前不是“纯黑盒”，也不是“完整透传”，更准确地说是“半透明”。

当前已经对外显式暴露 / 可稳定观察的部分：

• 客户端可以显式提交 subtask，当前入口是 opencode.sessions.prompt_async；
• 流式输出中可以稳定观察到它表现为 tool_call block；
• 已声明的稳定字段包括：
  • artifact.parts[].data.tool = "task"
  • artifact.parts[].data.call_id
  • artifact.parts[].data.status
  • artifact.parts[].data.input.prompt
  • artifact.parts[].data.input.description
  • artifact.parts[].data.input.subagent_type
  • artifact.parts[].data.input.command
  • artifact.parts[].data.output
  • artifact.parts[].data.error

当前仍然属于黑盒的部分：

• task tool 内部如何调度 subagent
• subagent 自身的 prompt/runtime 细节
• subagent 是否又调用了哪些内部 tools、做了多少轮推理、如何重试
• 更细粒度的子步骤生命周期

因此，这条链路更适合记录为：

• subtask submit：对外显式
• task tool started：对外可观察
• task tool input/output：对外部分可观察
• subagent internals：当前基本仍是黑盒

建议在最终落库文档中把这层“半透明”边界也写清楚，避免后续误以为当前 runtime 已经提供完整的 subagent 执行透视面。